v1.21.0

changelog.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2026-04-11 - 1.21.0 - feat(providers)
+replace provider creation modal with a guided multi-step setup flow
+
+- Adds a stepper-based provider creation flow with provider type selection, connection, credentials, advanced settings, and review steps.
+- Applies built-in templates for Sipgate and O2/Alice from the selected provider type instead of separate add actions.
+- Adds a final review step with generated provider ID preview and duplicate ID collision handling before saving.
+
+## 2026-04-11 - 1.20.5 - fix(readme)
+improve architecture and call flow documentation with Mermaid diagrams
+
+- Replace ASCII architecture and audio pipeline diagrams with Mermaid diagrams for better readability
+- Document the WebRTC browser call setup sequence, including offer handling and session-to-call linking
+
 ## 2026-04-11 - 1.20.4 - fix(deps)
 bump @design.estate/dees-catalog to ^3.71.1
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "siprouter",
-  "version": "1.20.4",
+  "version": "1.21.0",
   "private": true,
   "type": "module",
   "scripts": {

readme.md

@@ -28,39 +28,26 @@ siprouter sits between your SIP trunk providers and your endpoints — hardware
 
 ## 🏗️ Architecture
 
-```
-┌─────────────────────────────────────┐
-│           Browser Softphone          │
-│     (WebRTC via WebSocket signaling) │
-└──────────────┬──────────────────────┘
-               │ Opus/WebRTC
-               ▼
-┌──────────────────────────────────────┐
-│            siprouter                  │
-│                                      │
-│  TypeScript Control Plane            │
-│  ┌────────────────────────────────┐  │
-│  │ Config · WebRTC Signaling      │  │
-│  │ REST API · Web Dashboard       │  │
-│  │ Voicebox Manager · TTS Cache   │  │
-│  └────────────┬───────────────────┘  │
-│          JSON-over-stdio IPC         │
-│  ┌────────────┴───────────────────┐  │
-│  │ Rust proxy-engine (data plane) │  │
-│  │                                │  │
-│  │ SIP Stack · Dialog SM · Auth   │  │
-│  │ Call Manager · N-Leg Mixer     │  │
-│  │ 48kHz f32 Bus · Jitter Buffer  │  │
-│  │ Codec Engine · RTP Port Pool   │  │
-│  │ WebRTC Engine · Kokoro TTS     │  │
-│  │ Voicemail · IVR · Recording    │  │
-│  └────┬──────────────────┬────────┘  │
-└───────┤──────────────────┤───────────┘
-        │                  │
- ┌──────┴──────┐    ┌──────┴──────┐
- │ SIP Devices │    │ SIP Trunk   │
- │ (HT801 etc) │    │ Providers   │
- └─────────────┘    └─────────────┘
+```mermaid
+flowchart TB
+    Browser["🌐 Browser Softphone<br/>(WebRTC via WebSocket signaling)"]
+    Devices["📞 SIP Devices<br/>(HT801, desk phones, ATAs)"]
+    Trunks["☎️ SIP Trunk Providers<br/>(sipgate, easybell, …)"]
+
+    subgraph Router["siprouter"]
+        direction TB
+        subgraph TS["TypeScript Control Plane"]
+            TSBits["Config · WebRTC Signaling<br/>REST API · Web Dashboard<br/>Voicebox Manager · TTS Cache"]
+        end
+        subgraph Rust["Rust proxy-engine (data plane)"]
+            RustBits["SIP Stack · Dialog SM · Auth<br/>Call Manager · N-Leg Mixer<br/>48kHz f32 Bus · Jitter Buffer<br/>Codec Engine · RTP Port Pool<br/>WebRTC Engine · Kokoro TTS<br/>Voicemail · IVR · Recording"]
+        end
+        TS <-->|"JSON-over-stdio IPC"| Rust
+    end
+
+    Browser <-->|"Opus / WebRTC"| TS
+    Rust <-->|"SIP / RTP"| Devices
+    Rust <-->|"SIP / RTP"| Trunks
 ```
 
 ### 🧠 Key Design Decisions
@@ -71,6 +58,37 @@ siprouter sits between your SIP trunk providers and your endpoints — hardware
 - **Per-Session Codec Isolation** — Each call leg gets its own encoder/decoder/resampler/denoiser state — no cross-call corruption.
 - **SDP Codec Negotiation** — Outbound encoding uses the codec actually negotiated in SDP answers, not just the first offered codec.
 
+### 📲 WebRTC Browser Call Flow
+
+Browser calls are set up in a strict three-step dance — the WebRTC leg cannot be attached at call-creation time because the browser's session ID is only known once the SDP offer arrives:
+
+```mermaid
+sequenceDiagram
+    participant B as Browser
+    participant TS as TypeScript (sipproxy.ts)
+    participant R as Rust proxy-engine
+    participant P as SIP Provider
+
+    B->>TS: POST /api/call
+    TS->>R: make_call (pending call, no WebRTC leg yet)
+    R-->>TS: call_created
+    TS-->>B: webrtc-incoming (callId)
+
+    B->>TS: webrtc-offer (sessionId, SDP)
+    TS->>R: handle_webrtc_offer
+    R-->>TS: webrtc-answer (SDP)
+    TS-->>B: webrtc-answer
+    Note over R: Standalone WebRTC session<br/>(not yet attached to call)
+
+    B->>TS: webrtc_link (callId + sessionId)
+    TS->>R: link session → call
+    R->>R: wire WebRTC leg through mixer
+    R->>P: SIP INVITE
+    P-->>R: 200 OK + SDP
+    R-->>TS: call_answered
+    Note over B,P: Bidirectional Opus ↔ codec-transcoded<br/>audio flows through the mixer
+```
+
 ---
 
 ## 🚀 Getting Started
@@ -246,9 +264,17 @@ The `proxy-engine` binary handles all real-time audio processing with a **48kHz
 
 ### Audio Pipeline
 
-```
-Inbound:   Wire RTP → Jitter Buffer → Decode → Resample to 48kHz → Denoise (RNNoise) → Mix Bus
-Outbound:  Mix Bus → Mix-Minus → Resample to codec rate → Encode → Wire RTP
+```mermaid
+flowchart LR
+    subgraph Inbound["Inbound path (per leg)"]
+        direction LR
+        IN_RTP["Wire RTP"] --> IN_JB["Jitter Buffer"] --> IN_DEC["Decode"] --> IN_RS["Resample → 48 kHz"] --> IN_DN["Denoise (RNNoise)"] --> IN_BUS["Mix Bus"]
+    end
+
+    subgraph Outbound["Outbound path (per leg)"]
+        direction LR
+        OUT_BUS["Mix Bus"] --> OUT_MM["Mix-Minus"] --> OUT_RS["Resample → codec rate"] --> OUT_ENC["Encode"] --> OUT_RTP["Wire RTP"]
+    end
 ```
 
 - **Adaptive jitter buffer** — per-leg `BTreeMap`-based buffer keyed by RTP sequence number. Delivers exactly one frame per 20ms mixer tick in sequence order. Adaptive target depth starts at 3 frames (60ms) and adjusts between 2–6 frames based on observed network jitter. Handles hold/resume by detecting large forward sequence jumps and resetting cleanly.

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: 'siprouter',
-  version: '1.20.4',
+  version: '1.21.0',
   description: 'undefined'
 }

ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: 'siprouter',
-  version: '1.20.4',
+  version: '1.21.0',
   description: 'undefined'
 }

ts_web/elements/sipproxy-view-providers.ts

@@ -164,173 +164,346 @@ export class SipproxyViewProviders extends DeesElement {
         iconName: 'lucide:plus',
         type: ['header'] as any,
         actionFunc: async () => {
-          await this.openAddModal();
-        },
-      },
-      {
-        name: 'Add Sipgate',
-        iconName: 'lucide:phone',
-        type: ['header'] as any,
-        actionFunc: async () => {
-          await this.openAddModal(PROVIDER_TEMPLATES.sipgate, 'Sipgate');
-        },
-      },
-      {
-        name: 'Add O2/Alice',
-        iconName: 'lucide:phone',
-        type: ['header'] as any,
-        actionFunc: async () => {
-          await this.openAddModal(PROVIDER_TEMPLATES.o2, 'O2/Alice');
+          await this.openAddStepper();
         },
       },
     ];
   }
 
-  // ---- add provider modal --------------------------------------------------
+  // ---- add provider stepper ------------------------------------------------
 
-  private async openAddModal(
-    template?: typeof PROVIDER_TEMPLATES.sipgate,
-    templateName?: string,
-  ) {
-    const { DeesModal } = await import('@design.estate/dees-catalog');
+  private async openAddStepper() {
+    const { DeesStepper } = await import('@design.estate/dees-catalog');
+    type TDeesStepper = InstanceType<typeof DeesStepper>;
+    // IStep / menuOptions types: we keep content typing loose (`any[]`) to
+    // avoid having to import tsclass IMenuItem just for one parameter annotation.
 
-    const formData = {
-      displayName: templateName || '',
-      domain: template?.domain || '',
-      outboundProxyAddress: template?.outboundProxy?.address || '',
-      outboundProxyPort: String(template?.outboundProxy?.port ?? 5060),
+    type TProviderType = 'Custom' | 'Sipgate' | 'O2/Alice';
+    interface IAccumulator {
+      providerType: TProviderType;
+      displayName: string;
+      domain: string;
+      outboundProxyAddress: string;
+      outboundProxyPort: string;
+      username: string;
+      password: string;
+      // Advanced — exposed in step 4
+      registerIntervalSec: string;
+      codecs: string;
+      earlyMediaSilence: boolean;
+    }
+
+    const accumulator: IAccumulator = {
+      providerType: 'Custom',
+      displayName: '',
+      domain: '',
+      outboundProxyAddress: '',
+      outboundProxyPort: '5060',
       username: '',
       password: '',
-      registerIntervalSec: String(template?.registerIntervalSec ?? 300),
-      codecs: template?.codecs ? template.codecs.join(', ') : '9, 0, 8, 101',
-      earlyMediaSilence: template?.quirks?.earlyMediaSilence ?? false,
+      registerIntervalSec: '300',
+      codecs: '9, 0, 8, 101',
+      earlyMediaSilence: false,
     };
 
-    const heading = template
-      ? `Add ${templateName} Provider`
-      : 'Add Provider';
+    // Snapshot the currently-selected step's form (if any) into accumulator.
+    const snapshotActiveForm = async (stepper: TDeesStepper) => {
+      const form = stepper.activeForm;
+      if (!form) return;
+      const data: Record<string, any> = await form.collectFormData();
+      Object.assign(accumulator, data);
+    };
 
-    await DeesModal.createAndShow({
-      heading,
-      width: 'small',
-      showCloseButton: true,
+    // Overwrite template-owned fields. Keep user-owned fields (username,
+    // password) untouched. displayName is replaced only when empty or still
+    // holds a branded auto-fill.
+    const applyTemplate = (type: TProviderType) => {
+      const tpl =
+        type === 'Sipgate' ? PROVIDER_TEMPLATES.sipgate
+        : type === 'O2/Alice' ? PROVIDER_TEMPLATES.o2
+        : null;
+      if (!tpl) return;
+      accumulator.domain = tpl.domain;
+      accumulator.outboundProxyAddress = tpl.outboundProxy.address;
+      accumulator.outboundProxyPort = String(tpl.outboundProxy.port);
+      accumulator.registerIntervalSec = String(tpl.registerIntervalSec);
+      accumulator.codecs = tpl.codecs.join(', ');
+      accumulator.earlyMediaSilence = tpl.quirks.earlyMediaSilence;
+      if (
+        !accumulator.displayName ||
+        accumulator.displayName === 'Sipgate' ||
+        accumulator.displayName === 'O2/Alice'
+      ) {
+        accumulator.displayName = type;
+      }
+    };
+
+    // --- Step builders (called after step 1 so accumulator is populated) ---
+
+    const buildConnectionStep = (): any => ({
+      title: 'Connection',
       content: html`
-        <div style="display:flex;flex-direction:column;gap:12px;padding:4px 0;">
+        <dees-form>
           <dees-input-text
             .key=${'displayName'}
             .label=${'Display Name'}
-            .value=${formData.displayName}
-            @input=${(e: Event) => { formData.displayName = (e.target as any).value; }}
+            .value=${accumulator.displayName}
+            .required=${true}
           ></dees-input-text>
           <dees-input-text
             .key=${'domain'}
             .label=${'Domain'}
-            .value=${formData.domain}
-            @input=${(e: Event) => { formData.domain = (e.target as any).value; }}
+            .value=${accumulator.domain}
+            .required=${true}
           ></dees-input-text>
           <dees-input-text
             .key=${'outboundProxyAddress'}
             .label=${'Outbound Proxy Address'}
-            .value=${formData.outboundProxyAddress}
-            @input=${(e: Event) => { formData.outboundProxyAddress = (e.target as any).value; }}
+            .value=${accumulator.outboundProxyAddress}
           ></dees-input-text>
           <dees-input-text
             .key=${'outboundProxyPort'}
             .label=${'Outbound Proxy Port'}
-            .value=${formData.outboundProxyPort}
-            @input=${(e: Event) => { formData.outboundProxyPort = (e.target as any).value; }}
+            .value=${accumulator.outboundProxyPort}
           ></dees-input-text>
+        </dees-form>
+      `,
+      menuOptions: [
+        {
+          name: 'Continue',
+          iconName: 'lucide:arrow-right',
+          action: async (stepper: TDeesStepper) => {
+            await snapshotActiveForm(stepper);
+            stepper.goNext();
+          },
+        },
+      ],
+    });
+
+    const buildCredentialsStep = (): any => ({
+      title: 'Credentials',
+      content: html`
+        <dees-form>
           <dees-input-text
             .key=${'username'}
             .label=${'Username / Auth ID'}
-            .value=${formData.username}
-            @input=${(e: Event) => { formData.username = (e.target as any).value; }}
+            .value=${accumulator.username}
+            .required=${true}
           ></dees-input-text>
           <dees-input-text
             .key=${'password'}
             .label=${'Password'}
             .isPasswordBool=${true}
-            .value=${formData.password}
-            @input=${(e: Event) => { formData.password = (e.target as any).value; }}
+            .value=${accumulator.password}
+            .required=${true}
           ></dees-input-text>
+        </dees-form>
+      `,
+      menuOptions: [
+        {
+          name: 'Continue',
+          iconName: 'lucide:arrow-right',
+          action: async (stepper: TDeesStepper) => {
+            await snapshotActiveForm(stepper);
+            stepper.goNext();
+          },
+        },
+      ],
+    });
+
+    const buildAdvancedStep = (): any => ({
+      title: 'Advanced',
+      content: html`
+        <dees-form>
           <dees-input-text
             .key=${'registerIntervalSec'}
             .label=${'Register Interval (sec)'}
-            .value=${formData.registerIntervalSec}
-            @input=${(e: Event) => { formData.registerIntervalSec = (e.target as any).value; }}
+            .value=${accumulator.registerIntervalSec}
           ></dees-input-text>
           <dees-input-text
             .key=${'codecs'}
             .label=${'Codecs (comma-separated payload types)'}
-            .value=${formData.codecs}
-            @input=${(e: Event) => { formData.codecs = (e.target as any).value; }}
+            .value=${accumulator.codecs}
           ></dees-input-text>
           <dees-input-checkbox
             .key=${'earlyMediaSilence'}
             .label=${'Early Media Silence (quirk)'}
-            .value=${formData.earlyMediaSilence}
-            @newValue=${(e: CustomEvent) => { formData.earlyMediaSilence = e.detail; }}
+            .value=${accumulator.earlyMediaSilence}
           ></dees-input-checkbox>
-        </div>
+        </dees-form>
       `,
       menuOptions: [
         {
-          name: 'Cancel',
-          iconName: 'lucide:x',
-          action: async (modalRef: any) => {
-            modalRef.destroy();
+          name: 'Continue',
+          iconName: 'lucide:arrow-right',
+          action: async (stepper: TDeesStepper) => {
+            await snapshotActiveForm(stepper);
+            // Rebuild the review step so its rendering reflects the latest
+            // accumulator values (the review step captures values at build time).
+            stepper.steps = [...stepper.steps.slice(0, 4), buildReviewStep()];
+            await (stepper as any).updateComplete;
+            stepper.goNext();
           },
         },
-        {
-          name: 'Create',
-          iconName: 'lucide:check',
-          action: async (modalRef: any) => {
-            if (!formData.displayName.trim() || !formData.domain.trim()) {
-              deesCatalog.DeesToast.error('Display name and domain are required');
-              return;
-            }
-            try {
-              const providerId = slugify(formData.displayName);
-              const codecs = formData.codecs
+      ],
+    });
+
+    const buildReviewStep = (): any => {
+      const resolvedId = slugify(accumulator.displayName);
+      return {
+        title: 'Review & Create',
+        content: html`
+          <dees-panel>
+            <div
+              style="display:grid;grid-template-columns:auto 1fr;gap:6px 16px;font-size:.85rem;padding:8px 4px;"
+            >
+              <div style="color:#94a3b8;">Type</div>
+              <div>${accumulator.providerType}</div>
+              <div style="color:#94a3b8;">Display Name</div>
+              <div>${accumulator.displayName}</div>
+              <div style="color:#94a3b8;">ID</div>
+              <div style="font-family:'JetBrains Mono',monospace;">${resolvedId}</div>
+              <div style="color:#94a3b8;">Domain</div>
+              <div>${accumulator.domain}</div>
+              <div style="color:#94a3b8;">Outbound Proxy</div>
+              <div>
+                ${accumulator.outboundProxyAddress || accumulator.domain}:${accumulator.outboundProxyPort}
+              </div>
+              <div style="color:#94a3b8;">Username</div>
+              <div>${accumulator.username}</div>
+              <div style="color:#94a3b8;">Password</div>
+              <div>${'*'.repeat(Math.min(accumulator.password.length, 12))}</div>
+              <div style="color:#94a3b8;">Register Interval</div>
+              <div>${accumulator.registerIntervalSec}s</div>
+              <div style="color:#94a3b8;">Codecs</div>
+              <div>${accumulator.codecs}</div>
+              <div style="color:#94a3b8;">Early-Media Silence</div>
+              <div>${accumulator.earlyMediaSilence ? 'yes' : 'no'}</div>
+            </div>
+          </dees-panel>
+        `,
+        menuOptions: [
+          {
+            name: 'Create Provider',
+            iconName: 'lucide:check',
+            action: async (stepper: TDeesStepper) => {
+              // Collision-resolve id against current state.
+              const existing = (this.appData.providers || []).map((p) => p.id);
+              let uniqueId = resolvedId;
+              let suffix = 2;
+              while (existing.includes(uniqueId)) {
+                uniqueId = `${resolvedId}-${suffix++}`;
+              }
+
+              const parsedCodecs = accumulator.codecs
                 .split(',')
                 .map((s: string) => parseInt(s.trim(), 10))
                 .filter((n: number) => !isNaN(n));
 
               const newProvider: any = {
-                id: providerId,
-                displayName: formData.displayName.trim(),
-                domain: formData.domain.trim(),
+                id: uniqueId,
+                displayName: accumulator.displayName.trim(),
+                domain: accumulator.domain.trim(),
                 outboundProxy: {
-                  address: formData.outboundProxyAddress.trim() || formData.domain.trim(),
-                  port: parseInt(formData.outboundProxyPort, 10) || 5060,
+                  address:
+                    accumulator.outboundProxyAddress.trim() || accumulator.domain.trim(),
+                  port: parseInt(accumulator.outboundProxyPort, 10) || 5060,
                 },
-                username: formData.username.trim(),
-                password: formData.password,
-                registerIntervalSec: parseInt(formData.registerIntervalSec, 10) || 300,
-                codecs,
+                username: accumulator.username.trim(),
+                password: accumulator.password,
+                registerIntervalSec: parseInt(accumulator.registerIntervalSec, 10) || 300,
+                codecs: parsedCodecs.length ? parsedCodecs : [9, 0, 8, 101],
                 quirks: {
-                  earlyMediaSilence: formData.earlyMediaSilence,
+                  earlyMediaSilence: accumulator.earlyMediaSilence,
                 },
               };
 
-              const result = await appState.apiSaveConfig({
-                addProvider: newProvider,
-              });
-
-              if (result.ok) {
-                modalRef.destroy();
-                deesCatalog.DeesToast.success(`Provider "${formData.displayName}" created`);
-              } else {
-                deesCatalog.DeesToast.error('Failed to save provider');
+              try {
+                const result = await appState.apiSaveConfig({
+                  addProvider: newProvider,
+                });
+                if (result.ok) {
+                  await stepper.destroy();
+                  deesCatalog.DeesToast.success(
+                    `Provider "${newProvider.displayName}" created`,
+                  );
+                } else {
+                  deesCatalog.DeesToast.error('Failed to save provider');
+                }
+              } catch (err: any) {
+                console.error('Failed to create provider:', err);
+                deesCatalog.DeesToast.error('Failed to create provider');
+              }
+            },
+          },
+        ],
+      };
+    };
+
+    // --- Step 1: Provider Type ------------------------------------------------
+    //
+    // Note: `DeesStepper.createAndShow()` dismisses on backdrop click; a user
+    // mid-form could lose work. Acceptable for v1 — revisit if users complain.
+
+    const typeOptions: { option: string; key: TProviderType }[] = [
+      { option: 'Custom', key: 'Custom' },
+      { option: 'Sipgate', key: 'Sipgate' },
+      { option: 'O2 / Alice', key: 'O2/Alice' },
+    ];
+    const currentTypeOption =
+      typeOptions.find((o) => o.key === accumulator.providerType) || null;
+
+    const typeStep: any = {
+      title: 'Choose provider type',
+      content: html`
+        <dees-form>
+          <dees-input-dropdown
+            .key=${'providerType'}
+            .label=${'Provider Type'}
+            .options=${typeOptions}
+            .selectedOption=${currentTypeOption}
+            .enableSearch=${false}
+            .required=${true}
+          ></dees-input-dropdown>
+        </dees-form>
+      `,
+      menuOptions: [
+        {
+          name: 'Continue',
+          iconName: 'lucide:arrow-right',
+          action: async (stepper: TDeesStepper) => {
+            // `dees-input-dropdown.value` is an object `{option, key, payload?}`,
+            // not a plain string — extract the `key` directly instead of using
+            // the generic `snapshotActiveForm` helper (which would clobber
+            // `accumulator.providerType`'s string type via Object.assign).
+            const form = stepper.activeForm;
+            if (form) {
+              const data: Record<string, any> = await form.collectFormData();
+              const selected = data.providerType;
+              if (selected && typeof selected === 'object' && selected.key) {
+                accumulator.providerType = selected.key as TProviderType;
               }
-            } catch (err: any) {
-              console.error('Failed to create provider:', err);
-              deesCatalog.DeesToast.error('Failed to create provider');
             }
+            if (!accumulator.providerType) {
+              accumulator.providerType = 'Custom';
+            }
+            applyTemplate(accumulator.providerType);
+            // (Re)build steps 2-5 with current accumulator values.
+            stepper.steps = [
+              typeStep,
+              buildConnectionStep(),
+              buildCredentialsStep(),
+              buildAdvancedStep(),
+              buildReviewStep(),
+            ];
+            await (stepper as any).updateComplete;
+            stepper.goNext();
           },
         },
       ],
-    });
+    };
+
+    await DeesStepper.createAndShow({ steps: [typeStep] });
   }
 
   // ---- edit provider modal -------------------------------------------------