Phone call — call card v3.1

1 · One card, one size (PRESCRIPTIVE — call card v3.1, CPO 2026-09-29)

Today (CANONICAL, QA)

02:41Shane Dusang

v3.1 (PRESCRIPTIVE)

Shane Dusang02:41

Connected

One size in every state: 360 × 128 (max-width 100%, so 358 in a 390 phone with 16 gutters). Nothing grows 72 → 120 at connect or shrinks after a refusal; a dragged card never jumps.
State lives in the header: its tone tint plus the audio orb. The 1px outline is gone; the card floats on --elevation-popover.
Icon keys in fixed slots: desktop Mute · Hold · Transfer · End; mobile adds Speaker in slot 0. A key that cannot act dims to 40% in place and line 2 says why.
Red only ends or declines a call. During Ask first the End slot is a neutral × Cancel; a green ✓ completes the transfer.
Header B (v3.2, CPO 2026-09-30): line 1 is the name alone; line 2 is the timer, then “ · ” and one plain phrase. The timer never truncates; the phrase ellipsizes (171 px after the timer), so lock reasons are short: “Can't hold or transfer”. No glyphs.
v3.2 adds a Keypad key at the right end of the header on every call state, and Transfer opens as a details panel beside the card. Specs: the keypad · the Transfer panel.
Same logic as the CANONICAL card (comp-phone-call-states): every key calls the callback it calls today. The only new data is one audio-level stream for the orb.

2 · Anatomy (PRESCRIPTIVE — call card v3.1, CPO 2026-09-29)

Desktop · 4 slots

Shane Dusang02:41

Connected

Mobile · 5 slots · 390 phone

Shane Dusang02:41

Connected

Card 360 × 128 · r7 · --gray-07 · --elevation-popover · no border, no outline · the whole card drags (drag, 16px clamp and saved position unchanged).
Header 64 · pad 8 / 16 / 8 / 12 · tone tint (-02) · orb 48 · 12 gap · name column 220 × 40 (218 in a 390 phone, 148 on a 320 phone) · 12 gap · Keypad key 40 × 40 at x 304–344, y 12–52 (hit area 48) on every call state, dimmed when it can't act (v3.2, keypad).
Line 1 24 · the name alone, --t-paragraph-sb gray-00, ellipsis, tap → customer.
Line 2 16 · --t-tiny gray-02 · the timer first (tabular, only after connect, never truncates), then “ · ” and one phrase that ellipsizes: transfer phase › On hold › Sending digits · N left › lock reason › note › Connected. Before connect there is no timer and the phrase starts at the left edge.
Bar 64 · pad 8 · gap 4 · gray-07 · key = 1 fr × 48, r5, one 20px FA Regular glyph, no label.
Slots desktop 1 Mute · 2 Hold · 3 Transfer · 4 End (≈83 each) · mobile 0 Speaker · 1 Mute · 2 Hold · 3 Transfer · 4 End (≈65 each; ≈51 on a 320 phone).
Slot swaps Hold ↔ Resume · Transfer → ✓ (Ask first) · End → × Cancel (Ask first) · incoming: Accept spans 1–3 (0–3 mobile), Decline takes 4.
Tones LIVE green-02 / green-01 (connected, muted, speaker, returned, 409, Ask first failed) · WAITING orange (incoming, on hold) · TRANSFER blue (Ask first, transferring, the colleague's card) · DIALING gray (calling).
Position desktop: centred over the 424 detail column, top 98 (same formula, cardW 360) · mobile: centred. While Transfer is open the card steps aside only if it overlaps the panel, and is never saved there (Transfer panel).

3 · Keys and tooltips (PRESCRIPTIVE — call card v3.1, CPO 2026-09-29)

Neutral · gray-06 / gray-00

End · Decline · red-01 / global-white

Accept · ✓ · green-01 / white

Unmute · red-02 / red-01

Resume · orange-02 / -01

Speaker on · panel open · blue-02 / -01

× Cancel (Ask first) · neutral

Can't act · opacity .4

You speaking · glyph green-01

No labels. Every key is one 20px glyph. Its name is the tooltip (hover and keyboard focus on desktop, the DS .sb-tooltip via [data-tip]) and a long-press Tooltip on mobile, and always the screen-reader label.
Names: Mute / Unmute · Hold / Resume · Transfer / Close transfer (panel open: .c3-key--blue, expanded, live even during isBusy) · Complete transfer · End call · Cancel Ask first · Accept · Decline · Speaker. The header's Keypad key: Keypad / Close keypad (fa-table-cells, 16px).
Glyphs (FA Regular): fa-microphone, fa-microphone-slash, fa-pause, fa-play, fa-right-left, fa-check, fa-xmark, fa-phone-slash, fa-phone-flip, fa-volume-low, fa-volume-high.
Hover: neutral → gray-05; End / Decline → red-02 fill, red-01 glyph, 1px inset red-01; Accept / ✓ → green-02 fill, green-01 glyph, 1px inset green-01. Toggled tones keep their fill.
Focus-visible: inset 2px blue-01 · focused + pressed: inset 2px gray-03 · disabled: opacity .4, no hover, default cursor.
Flag for a11y (light, measured): white on green-01 2.0:1 (as the composer Call button) · global-white on red-01 2.9:1 · toggled red 2.6, orange 2.3, blue 2.9 · green-01 mic glyph on gray-06 1.7. All pass in dark except blue toggled (4.2).

4 · The audio orb (PRESCRIPTIVE — call card v3.1, CPO 2026-09-29)

Customer speaking

Rings swell and roll faster with their voice.

Silence

A slow, shallow roll: alive, not reacting.

Incoming

Two pulses every 2 s.

Calling

Swells 2 s, rests 4 s, like ringback.

On hold

Energy 0, rolls at 0.2×.

Ask first ringing · transferring

The ringback rhythm on blue.

Ask first talking · colleague

Follows the colleague's voice.

No level stream

The library's own loop (iOS / Android for now).

Reduced motion

One still frame.

What it is: the thinking-orbs “listening” orb (libraries.dev/orbs, MIT, Jakub Antalik) — a dotted sphere of latitude rings rolling a slow wave, plain circle fills drawn far to near. 48 × 48 canvas.sb-callorb, ~102 dots (8 rings × 20), drawn by sb-callorb.js.
Colour: near dots in the tone accent (--c3-accent, -01); far dots fade 70% of the way to the header tint (--c3-hd, -02). No fill, no badge, no pause sign.
Connected, it follows OUTPUT (the other side): louder rings swell outward (+7%), draw bigger (+35%) and stronger dots and roll faster (4.3 × (0.5 + 0.9·energy)); each ring reads the level 60 ms later than the one nearer the equator, so a syllable rolls through it.
You speaking turns the Mute glyph green-01 (INPUT energy above 0.25 and not muted).
Drivers: level (connected, Ask first talking, the colleague's side) · ringing (incoming) · ringback (calling, Ask first ringing, transferring) · hold (energy 0, 0.2×) · none (no level stream: the library's own loop) · reduced motion (one still frame).

5 · The orb on a live call — Mute and Hold work on this card (PRESCRIPTIVE — call card v3.1, CPO 2026-09-29)

Shane Dusang02:41

Connected

SilenceThe same orb at 3.3×.

Customerraw levelCustomerorb energyYouraw levelYoumic energy

Bars: twilio.js Call volume, every 50 ms (0–0.6). Dashed: the noise floor the orb finds. Green: orb energy (0–1). Black: your mic energy, with the 0.25 green-glyph line. Click the chart to jump.
The levels are a synthesized two-voice call run through the exact analyser twilio.js 2.4.1 uses for its volume event (32-sample spectrum, −100 to −30 dB, averaged, every 50 ms). The trace is real; the voices are not.

Why it smooths: the raw value jumps every 50 ms and never reaches zero — line noise alone reads about 0.15, speech 0.2–0.5. Wired straight in, the orb would twitch in silence and flicker in speech.
Level → energy: floor = min(raw over the last 2.5 s), eased (falls in 0.15 s, rises in 0.6 s) · target = clamp((raw − floor − 0.04) / 0.30) · energy = target with a 50 ms attack and a 280 ms release. Speech sits around 0.6–0.95; silence around 0.04.
Calibrate on real calls before shipping: the floor window, gate and range come from this emulation (UNVERIFIED on real line noise, headsets, speakerphone).

6 · Every state · desktop · [1 Mute] [2 Hold] [3 Transfer] [4 End] (PRESCRIPTIVE — call card v3.1, CPO 2026-09-29)

S1 · Incoming · WAITING

Shane Dusang

Incoming Call

Orange tint; the orb pulses twice every 2 s (not audio). Accept (green, wide) spans slots 1–3; Decline (red) takes the End slot. Same height as in-call, so answering only recolours the header and swaps the bar.

S1 · Incoming · returned · WAITING

Shane Dusang

Returned · Karla Sellers didn't pick up

As S1; line 2 carries the returned note, ellipsis if long.

S1 · Incoming · asks first · WAITING

Shane Dusang

Devon Park asks first

The colleague's phone ringing during an Ask first: line 2 “{rep} asks first”.

S2 · Calling · DIALING

Shane Dusang

Calling...

Gray; the orb swells with the ringback rhythm (2 s on, 4 s off). No timer before connect. Mute works where the platform allows (canToggleMute); Hold and Transfer dim until connect, so nothing moves when it does.

S3 · Connected · legacy / v1 · LIVE

Shane Dusang02:41

Can't hold or transfer

Hold and Transfer dim in place and line 2 gives the reason. The ≤3 s v2 probe window uses the same dimmed keys with “Connected”.

S4 · Connected · v2 · LIVE

Shane Dusang02:41

Connected

The green orb follows the customer's voice; the Mute glyph turns green while you talk. Every key live. Ask first failed (S11) looks identical, plus the existing warning toast.

S5 · Muted · LIVE

Shane Dusang02:41

Connected

Mute → Unmute (red-02 / red-01). Nothing on the orb, which keeps following the customer. Nothing else moves.

S7 · On hold · WAITING

Shane Dusang02:41

On hold

Orange tint; the orb slows almost to a stop. Line 2 “On hold”; Hold → Resume (orange-02 / orange-01). No glyph on the timer.

S8 · Ask first · ringing · TRANSFER

Shane Dusang02:41

Calling Karla Sellers...

Blue; the orb follows the ringback while the colleague's phone rings. Timer = total call time. Transfer slot → ✓ (green, dim until the colleague answers). End slot → neutral × Cancel (cancelConsult): red never cancels.

S9 · Ask first · talking · TRANSFER

Shane Dusang03:05

Talking to Karla Sellers

The blue orb follows the colleague's voice. ✓ (completeConsult) beside × reads as confirm / cancel.

S10 · Transferring · TRANSFER

Shane Dusang03:12

Transferring to Karla Sellers...

Blue ringback; line 2 is why Hold and Transfer are dimmed. End still hangs up.

S13 · Returned · connected · LIVE

Shane Dusang00:37

Returned · Karla Sellers didn't pick up

Line 2 keeps “Returned · …” while idle; hold, Ask first and transferring phrases override it while they run.

S12 · Colleague's side · connected · TRANSFER

Shane Dusang00:12

Devon Park asks first

The colleague's card during an Ask first: the orb follows the rep who asked. Hold/Resume and Transfer dim (followsConsult); End hangs up. Turns LIVE when the consult ends.

409 · Controls refused · LIVE

Shane Dusang02:41

Can't hold or transfer

The card never shrinks: Hold and Transfer dim in place with the line-2 reason; the existing info toast still fires. (Since #2087 a probe 409 looks like this; an action 409 keeps the keys live.)

7 · Every state · mobile · [0 Speaker] [1 Mute] [2 Hold] [3 Transfer] [4 End] · names on long-press (PRESCRIPTIVE — call card v3.1, CPO 2026-09-29)

S1 · Incoming · WAITING

Shane Dusang

Incoming Call

Mobile web only: native iOS/Android keep the OS ring screen and first show the card at connect. Accept spans slots 0–3.

S1 · Incoming · returned · WAITING

Shane Dusang

Returned · Karla Sellers didn't pick up

Mobile web only. Line 2: the returned note.

S1 · Incoming · asks first · WAITING

Shane Dusang

Devon Park asks first

Mobile web only. Line 2: “{rep} asks first”.

S2 · Calling · DIALING

Shane Dusang

Calling...

Speaker is dimmed too until connect.

S3 · Connected · legacy / v1 · LIVE

Shane Dusang02:41

Can't hold or transfer

As desktop; Speaker stays live in slot 0.

S4 · Connected · v2 · LIVE

Shane Dusang02:41

Connected

Five keys; Speaker off = neutral fa-volume-low.

S5 · Muted · LIVE

Shane Dusang02:41

Connected

Mute → Unmute (red-02 / red-01). Nothing on the orb, which keeps following the customer. Nothing else moves.

S6 · Speaker on · LIVE

Shane Dusang02:41

Connected

Mobile only. Slot 0 is a toggle: blue-02 / blue-01 with fa-volume-high while the speaker is on.

S6 · Speaker off · LIVE

Shane Dusang02:41

Connected

Mobile only. Neutral with fa-volume-low, as on every other mobile row.

S7 · On hold · WAITING

Shane Dusang02:41

On hold

Orange tint; the orb slows almost to a stop. Line 2 “On hold”; Hold → Resume (orange-02 / orange-01). No glyph on the timer.

S8 · Ask first · ringing · TRANSFER

Shane Dusang02:41

Calling Karla Sellers...

S9 · Ask first · talking · TRANSFER

Shane Dusang03:05

Talking to Karla Sellers

The blue orb follows the colleague's voice. ✓ (completeConsult) beside × reads as confirm / cancel.

S10 · Transferring · TRANSFER

Shane Dusang03:12

Transferring to Karla Sellers...

Blue ringback; line 2 is why Hold and Transfer are dimmed. End still hangs up.

S13 · Returned · connected · LIVE

Shane Dusang00:37

Returned · Karla Sellers didn't pick up

Line 2 keeps “Returned · …” while idle; hold, Ask first and transferring phrases override it while they run.

S12 · Colleague's side · connected · TRANSFER

Shane Dusang00:12

Devon Park asks first

The colleague's card during an Ask first: the orb follows the rep who asked. Hold/Resume and Transfer dim (followsConsult); End hangs up. Turns LIVE when the consult ends.

409 · Controls refused · LIVE

Shane Dusang02:41

Can't hold or transfer

The card never shrinks: Hold and Transfer dim in place with the line-2 reason; the existing info toast still fires. (Since #2087 a probe 409 looks like this; an action 409 keeps the keys live.)

8 · Engineering handoff (PRESCRIPTIVE — call card v3.1, CPO 2026-09-29)

The orb in Flutter is written and tested: docs/engineering/call-orb in this repo — call_orb_engine.dart (plain Dart: geometry + level follower), call_orb.dart (Ticker + CustomPainter, ~102 drawCircle calls in a RepaintBoundary), the tests and their fixtures, and the thinking-orbs MIT notice that must travel with them.
Verified 2026-09-29 (Flutter 3.44.6 / Dart 3.12.2): with no audio the engine reproduces the library's golden frames (8 cases, 4,224 values, ≤1e-4); the follower and audio frames equal sb-callorb.js (2,118 energies + 3 frames, ≤1e-9); line noise < 0.05 vs speech > 0.7; every driver runs; reduced motion schedules no frames; ~20 µs geometry per frame; flutter analyze clean.
Level stream: PhoneCallService.audioLevel, a ValueListenable<CallAudioLevel?> {input, output} (raw 0..1), only while connected. Web: add call.on("volume", …) beside the listeners in packages/twilio_voice/lib/_internal/twilio_voice_web.dart:1019–1028. macOS (WKWebView) and Windows (WebView2) run the same twilio.js 2.4.1: add volume to TVCallEvent / attachEventListeners (TVCall.swift:151) and the Windows bridge. iOS / Android: no level API wired (no getStats in the plugin) → driver none until added.
Card: _CallInProgressCard → Column[_CallHeader(64), _CallBar(64)] at a fixed 360×128; foregroundDecoration removed, popover shadow added; _IconButton → _CallKey (48 tall, r5, 20px FaIcon, no label, Tooltip + Semantics, opacity .4 when onPressed == null); slotsFor(status, phase, platform) always returns 4 slots (5 on mobile); the End slot is a neutral × Cancel for consultRinging / consultTalking (it already calls cancelConsult).
Mic glyph: a second CallLevelFollower on INPUT; the Mute glyph is green-01 while its energy is above 0.25 and the call is not muted.
Unchanged: PhoneCallService and CallControlNotifier logic (probe, 409, isBusy, polling, auto-fail), every toast, transfer_sheet.dart, drag and clamp, the hidden incoming card on native mobile.
[CLOSED 09-30] The in-call keypad (#2087) is placed in v3.2: the header Keypad key, the entry line, the desktop pad and the mobile dock (comp-call-keypad). [UNVERIFIED] Floor / gate / range on real calls; the macOS / Windows bridge at 20 messages a second; desktop_app.dart:197-207 reads cardW.

State	Driver	What it does	Tint
Incoming	`ringing`	two 0.4 s pulses every 2 s (not audio)	orange
Calling · Ask first ringing · Transferring	`ringback`	swells 2 s, rests 4 s	gray · blue · blue
Connected · muted · speaker · returned · 409	`level`	follows the customer's voice	green
Ask first talking · colleague's side	`level`	follows the colleague's voice	blue
On hold	`hold`	energy 0, rolls at 0.2×	orange
No level stream (iOS / Android for now)	`none`	the library's listening loop, unchanged	by state
Reduced motion (any state)	`—`	one still frame (t = 0.6)	by state