@saar-ai/web-widget 0.5.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/dist/card-aspect.d.ts +58 -0
  2. package/dist/card-aspect.d.ts.map +1 -0
  3. package/dist/chunks/{host-widget-B0SkhMIs.js → host-widget-CAPud_Jz.js} +4609 -5776
  4. package/dist/chunks/{telemetry-Bw-3F_Zk.js → telemetry-BI_SEWTb.js} +104 -2
  5. package/dist/dock/dock-caption.d.ts +67 -0
  6. package/dist/dock/dock-caption.d.ts.map +1 -0
  7. package/dist/dock/dock-motion.d.ts +270 -0
  8. package/dist/dock/dock-motion.d.ts.map +1 -0
  9. package/dist/dock/dock-pill.d.ts +38 -0
  10. package/dist/dock/dock-pill.d.ts.map +1 -0
  11. package/dist/dock/dock-row.d.ts +120 -0
  12. package/dist/dock/dock-row.d.ts.map +1 -0
  13. package/dist/dock/dock-sheet.d.ts +89 -0
  14. package/dist/dock/dock-sheet.d.ts.map +1 -0
  15. package/dist/dock/dock-shelf.d.ts +38 -0
  16. package/dist/dock/dock-shelf.d.ts.map +1 -0
  17. package/dist/dock/dock-state.d.ts +221 -0
  18. package/dist/dock/dock-state.d.ts.map +1 -0
  19. package/dist/dock/dock.d.ts +344 -0
  20. package/dist/dock/dock.d.ts.map +1 -0
  21. package/dist/dock/geometry.d.ts +161 -0
  22. package/dist/dock/geometry.d.ts.map +1 -0
  23. package/dist/dock/motion-gate.d.ts +123 -0
  24. package/dist/dock/motion-gate.d.ts.map +1 -0
  25. package/dist/generated/widget-css.d.ts.map +1 -1
  26. package/dist/host-widget.d.ts +94 -16
  27. package/dist/host-widget.d.ts.map +1 -1
  28. package/dist/index.d.ts +7 -3
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/index.js +4029 -7
  31. package/dist/messages.d.ts +69 -0
  32. package/dist/messages.d.ts.map +1 -1
  33. package/dist/next/index.js +1 -1
  34. package/dist/session-log.d.ts +7 -0
  35. package/dist/session-log.d.ts.map +1 -1
  36. package/dist/session-panel.d.ts +13 -3
  37. package/dist/session-panel.d.ts.map +1 -1
  38. package/dist/theme/color.d.ts +114 -0
  39. package/dist/theme/color.d.ts.map +1 -0
  40. package/dist/theme/derive.d.ts +92 -0
  41. package/dist/theme/derive.d.ts.map +1 -0
  42. package/dist/theme/index.d.ts +10 -0
  43. package/dist/theme/index.d.ts.map +1 -0
  44. package/dist/use-chat-session.d.ts +18 -16
  45. package/dist/use-chat-session.d.ts.map +1 -1
  46. package/dist/use-voice-session.d.ts +79 -3
  47. package/dist/use-voice-session.d.ts.map +1 -1
  48. package/dist/voice-widget.d.ts +49 -19
  49. package/dist/voice-widget.d.ts.map +1 -1
  50. package/dist/widget-cards.d.ts +28 -1
  51. package/dist/widget-cards.d.ts.map +1 -1
  52. package/dist/widget.css +1 -1
  53. package/package.json +4 -4
  54. package/src/styles/concierge.css +758 -28
  55. package/src/styles/tokens.css +67 -0
  56. package/dist/concierge-launcher.d.ts +0 -53
  57. package/dist/concierge-launcher.d.ts.map +0 -1
  58. package/dist/concierge-shell.d.ts +0 -256
  59. package/dist/concierge-shell.d.ts.map +0 -1
  60. package/dist/position.d.ts +0 -65
  61. package/dist/position.d.ts.map +0 -1
  62. package/dist/transcript-geometry.d.ts +0 -220
  63. package/dist/transcript-geometry.d.ts.map +0 -1
@@ -0,0 +1,89 @@
1
+ import { type ReactNode, type RefObject } from 'react';
2
+ /**
3
+ * THE SHEET — docs/DOCK_SPEC.md §3.3, and the one surface in this package
4
+ * that is NOT a modal on purpose.
5
+ *
6
+ * §1 rule 2: "Never a modal. No backdrop, no blur, no focus trap, no
7
+ * `aria-modal`. The page stays interactive in every state." So:
8
+ *
9
+ * - `role="dialog"` **without** `aria-modal` (§11). The role names the
10
+ * surface; `aria-modal` would tell a screen reader the rest of the page is
11
+ * inert, which is a lie — a shopper can still tap a product behind it, and
12
+ * that is the whole design.
13
+ * - **No focus trap.** `Tab` from the last control leaves the widget and
14
+ * lands on the merchant's page. A trap on a storefront is how a widget
15
+ * becomes the thing a shopper cannot escape.
16
+ * - `Escape` closes the sheet and returns focus to the caption field — it
17
+ * does not "close the concierge", because there is nothing to close. The
18
+ * handler lives on the DOCK's root (`dock.tsx`), not here: the shopper's
19
+ * focus is as likely to be on the row's mark or the composer as inside the
20
+ * sheet, and a handler that only listened where the sheet has focus would
21
+ * answer `Escape` in one of those places and not the other.
22
+ * - **No blur** (§7.1 rule 11). Opaque `--wgt-surface`.
23
+ *
24
+ * ## Three snap points, and why the floor never moves
25
+ *
26
+ * `closed` / `peek` (three shelf rows) / `expanded`. The ROW is the sheet's
27
+ * floor and never moves when the sheet opens — the shopper's thumb stays
28
+ * where they left it, which is the difference between a surface that grew and
29
+ * one that jumped.
30
+ *
31
+ * Below a 500 px viewport height the sheet offers `peek` only (§3.3): an
32
+ * expanded sheet on a short landscape phone is a takeover with a keyboard
33
+ * over it.
34
+ *
35
+ * ## The drag is pointer events, and `touch-action: none` is on the HANDLE
36
+ *
37
+ * §7.1 rule 8. On the sheet BODY, `touch-action: none` would kill the
38
+ * internal scroll the shopper needs to read the transcript. The handle is the
39
+ * only element that claims the gesture, and the position it writes is a CSS
40
+ * custom property written once per frame (rule 5) — never React state, or a
41
+ * drag would re-render the whole conversation sixty times a second.
42
+ *
43
+ * ## Growth follows the reader, not the content
44
+ *
45
+ * A streamed reply grows the sheet's contents. The scroll follows ONLY if the
46
+ * reader was already at the bottom — the same `FOLLOW_TOLERANCE_PX` rule the
47
+ * retired panel used, and for the same reason: yanking someone back down
48
+ * while they are re-reading an earlier answer is worse than a message they
49
+ * have to scroll for.
50
+ */
51
+ export type DockSheetSnap = 'closed' | 'peek' | 'expanded';
52
+ /**
53
+ * How far off the bottom still counts as "following". Not zero: fractional
54
+ * scroll metrics on zoomed and hi-dpi displays never land exactly on the
55
+ * bottom, and a smooth scroll is still in flight when the next streamed token
56
+ * resizes the content.
57
+ */
58
+ export declare const FOLLOW_TOLERANCE_PX = 24;
59
+ /**
60
+ * How many frames the follow may spend converging on the newest row.
61
+ *
62
+ * §7.1 rule 3's `content-visibility: auto` makes the transcript's scroll range
63
+ * an estimate until the rows in question have been rendered once, so the first
64
+ * assignment lands short and each subsequent one lands truer. Four frames is
65
+ * ~66 ms at 60 Hz and is a CEILING, not a cost: the loop stops the moment a
66
+ * pass moves nothing, which on a transcript that fits is the first one.
67
+ */
68
+ export declare const FOLLOW_SETTLE_FRAMES = 4;
69
+ export interface DockSheetProps {
70
+ readonly snap: DockSheetSnap;
71
+ readonly onSnapChange: (snap: DockSheetSnap) => void;
72
+ /** §11 — labelled by the identity name, never by "dialog". */
73
+ readonly label: string;
74
+ /** §3.3 — `peek` only below a 500 px viewport height. */
75
+ readonly peekOnly: boolean;
76
+ /** The sheet's own header row: "Show what was said", "Minimise". */
77
+ readonly header?: ReactNode;
78
+ readonly children: ReactNode;
79
+ /** `Escape`, and every "the shopper turned to the page" close — returns focus to the caption. */
80
+ readonly onDismiss: () => void;
81
+ /** Bumped whenever the contents grew, so the scroll can follow a reader who was at the bottom. */
82
+ readonly followKey?: unknown;
83
+ readonly sheetRef?: RefObject<HTMLDivElement | null>;
84
+ /** 0 under reduced motion (§7.1 rule 10). */
85
+ readonly durationMs: number;
86
+ readonly dragHandleLabel: string;
87
+ }
88
+ export declare function DockSheet({ snap, onSnapChange, label, peekOnly, header, children, onDismiss, followKey, sheetRef, durationMs, dragHandleLabel, }: DockSheetProps): import("react").JSX.Element;
89
+ //# sourceMappingURL=dock-sheet.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dock-sheet.d.ts","sourceRoot":"","sources":["../../src/dock/dock-sheet.tsx"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAUf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAQtC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;IACrD,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,iGAAiG;IACjG,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;IAC/B,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrD,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,SAAS,EACT,SAAS,EACT,QAAQ,EACR,UAAU,EACV,eAAe,GAChB,EAAE,cAAc,+BAgVhB"}
@@ -0,0 +1,38 @@
1
+ import { type WidgetMessages } from '../messages.js';
2
+ import type { ChatCards } from '../use-chat-session.js';
3
+ /**
4
+ * THE SHELF — docs/DOCK_SPEC.md §3.4, the sheet's contents for a VOICE
5
+ * session.
6
+ *
7
+ * §1 rule 3: "Recommendations are not a payload inside a bubble: cards are a
8
+ * shelf of at most three; 'see all' is a real page." So this is deliberately
9
+ * NOT `WidgetCardList` (which belongs to a text transcript, where a curation
10
+ * hangs off the turn that produced it): a spoken answer has no bubble, the
11
+ * shelf is the latest curation and only the latest, and the overflow is a
12
+ * link out rather than a longer list.
13
+ *
14
+ * **Full-width rows on mobile, 3-up on desktop** (§3.4), switched by the
15
+ * dock's own `data-viewport` attribute in CSS rather than by a media query
16
+ * here — the dock already knows which viewport class it is in (it sizes the
17
+ * row from it), and two sources for one breakpoint is how they drift.
18
+ *
19
+ * **Prices come from the catalogue, never the model** (§6) — `priceMinor` and
20
+ * `currency` ride on the card the server built. `showPrice` is a tenant
21
+ * toggle (§9.1); `false` hides the line, it does not substitute one.
22
+ */
23
+ /** §3.4 — "up to three cards from the latest curation". */
24
+ export declare const SHELF_LIMIT = 3;
25
+ export interface DockShelfProps {
26
+ readonly cards: ChatCards;
27
+ readonly messages: WidgetMessages;
28
+ readonly locale: string;
29
+ /** §9.1 `cards.showPrice`. */
30
+ readonly showPrice: boolean;
31
+ /** Builds the "See all N" href. Absent ⇒ no link, and the shelf simply shows its three. */
32
+ readonly curationHref?: (curationId: string) => string;
33
+ readonly productHref?: (handle: string) => string;
34
+ /** A plain left click is handed to the host's router; everything else stays a real link. */
35
+ readonly navigate?: (url: string) => void | Promise<void>;
36
+ }
37
+ export declare function DockShelf({ cards, messages, locale, showPrice, curationHref, productHref, navigate, }: DockShelfProps): import("react").JSX.Element | null;
38
+ //# sourceMappingURL=dock-shelf.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dock-shelf.d.ts","sourceRoot":"","sources":["../../src/dock/dock-shelf.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,KAAK,EAAgB,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,2DAA2D;AAC3D,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACvD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,QAAQ,EACR,MAAM,EACN,SAAS,EACT,YAAY,EACZ,WAAW,EACX,QAAQ,GACT,EAAE,cAAc,sCAiDhB"}
@@ -0,0 +1,221 @@
1
+ /**
2
+ * THE DOCK'S STATE MACHINE — docs/DOCK_SPEC.md §5.1, as one pure function.
3
+ *
4
+ * Everything under `dock/` renders what `deriveDockState` returns: the row
5
+ * picks its controls from `controls`, the caption reads `caption`, the border
6
+ * and the mark read `border`/`mark`, and the sheet reads `sheet`. Nothing
7
+ * else in the dock decides a state.
8
+ *
9
+ * ## Why it is a pure function over a snapshot
10
+ *
11
+ * The same reason `voice-session-state.ts` and `bot-state.ts` are separate
12
+ * from the components that draw them: whether the shopper is being heard,
13
+ * answered, muted or reconnected is the one thing a voice product has to get
14
+ * right, and it must be assertable without a LiveKit room, a socket, a
15
+ * microphone or a DOM. §5.1 is a thirteen-row table; `dock-state.test.ts`
16
+ * walks it row by row, which is only possible because this takes data and
17
+ * returns data.
18
+ *
19
+ * ## The precedence order IS the behaviour
20
+ *
21
+ * Several claimants can be true at once — a live call that has just
22
+ * escalated, a duck with a curation landing inside it, a reconnect with a
23
+ * refused microphone. The order below is spelled out rather than left to the
24
+ * shape of the `if`s, and it is the same precedence `host-widget.tsx`'s
25
+ * status line already uses for its three claimants (session > voice > cart):
26
+ *
27
+ * 1. **`error`** — the conversation is broken; nothing else the row could
28
+ * say matters more.
29
+ * 2. **`offline`** — the tenant says there is no channel to answer on.
30
+ * 3. **`human`** — a PERSON holds the conversation. Voice is AI-only, so
31
+ * every voice state below is a lie while this is true.
32
+ * 4. **`mic_blocked`** — the browser refused. It outranks `reconnecting`
33
+ * because "resume" is an instruction the shopper cannot follow.
34
+ * 5. **`reconnecting`** — §5.1: the most-seen state on a conventionally
35
+ * navigating storefront.
36
+ * 6. **`ducked`** — the shopper turned to the page.
37
+ * 7. the live voice states, in the order `botStateFor` already established.
38
+ * 8. **`cards`** — only over a quiet row (`dormant`/`ducked`) and only while
39
+ * the sheet is closed, per §5.1's "replaces `dock_ducked` once cards land
40
+ * during a duck". It never steals the caption from a live audio state,
41
+ * where the clause and the partial transcript are the point.
42
+ * 9. **`dormant`**.
43
+ *
44
+ * ## Copy is a KEY, never a string
45
+ *
46
+ * `caption` carries either `{ kind: 'message', key }` — a `WidgetMessages`
47
+ * key the renderer resolves against the tenant's own catalogue — or
48
+ * `{ kind: 'text', text }` for something live (a partial transcript, a spoken
49
+ * clause, an operator's line, the host's error). This module never formats
50
+ * and never localises: it has no messages, on purpose, so the table can be
51
+ * asserted without one.
52
+ */
53
+ import type { VoicePhase } from '../voice-session-state.js';
54
+ /** Every state the row can be in — §5.1's nine, plus the four the shipped widget already had. */
55
+ export declare const DOCK_STATES: readonly ['dormant', 'connecting', 'listening', 'thinking', 'speaking', 'ducked', 'reconnecting', 'muted', 'mic_blocked', 'human', 'offline', 'error', 'cards'];
56
+ export type DockState = (typeof DOCK_STATES)[number];
57
+ /**
58
+ * §2's control candidates. Never more than three are returned, and the ORDER
59
+ * is the order they are drawn in — `interrupt` first in `speaking` because
60
+ * §5.1 puts it there and because it is the one a thumb reaches for.
61
+ */
62
+ export type DockControl = 'mic' | 'mute' | 'keyboard' | 'send' | 'interrupt' | 'see' | 'fix_browser' | 'attach';
63
+ /** §2 — the mark carries session state as a TREATMENT, not a colour swap. */
64
+ export type DockMark = 'live' | 'dimmed';
65
+ /** §2's activity slot: a waveform while audio flows, a progress track during retrieval. */
66
+ export type DockActivity = 'none' | 'waveform' | 'progress';
67
+ /** §1 rule 5 — the only chrome that changes. */
68
+ export type DockBorder = 'rest' | 'primary';
69
+ /**
70
+ * What this state does to the sheet. `as-is` is a real answer, not a missing
71
+ * one: most states must leave the sheet exactly where the shopper put it.
72
+ */
73
+ export type DockSheetPolicy = 'closed' | 'as-is' | 'collapsed';
74
+ /**
75
+ * The caption, as data. `key` is a `WidgetMessages` key (see `messages.ts` —
76
+ * every `dock_*` key is OPTIONAL there, so an older host catalogue falls back
77
+ * to shipped English rather than rendering an empty row).
78
+ */
79
+ export type DockCaptionSpec = {
80
+ readonly kind: 'field';
81
+ } | {
82
+ readonly kind: 'text';
83
+ readonly text: string;
84
+ } | {
85
+ readonly kind: 'message';
86
+ readonly key: DockMessageKey;
87
+ readonly vars?: Readonly<Record<string, string | number>>;
88
+ };
89
+ /** The `WidgetMessages` keys this module can name. Narrow on purpose — a typo is a compile error. */
90
+ export type DockMessageKey = 'dock_connecting' | 'dock_listening' | 'dock_thinking' | 'dock_ducked' | 'dock_still_here' | 'dock_still_here_resume' | 'dock_muted' | 'dock_mic_blocked' | 'dock_cards' | 'dock_voice_failed' | 'escalated_banner';
91
+ /** The voice leg, as the row needs to see it — a superset of `VoiceSessionSnapshot`'s fields. */
92
+ export interface DockVoiceInput {
93
+ /** The tenant published voice AND this is not an embedded webview (§8.4). */
94
+ readonly enabled: boolean;
95
+ readonly phase: VoicePhase;
96
+ /** The caller's microphone is published to the room. */
97
+ readonly micOpen: boolean;
98
+ /** The browser is being asked for the microphone right now (`VoiceSessionSnapshot.micPending`). */
99
+ readonly micPending: boolean;
100
+ /** The browser REFUSED. Distinct from muted: no press can undo it on this page (§5.1). */
101
+ readonly micBlocked: boolean;
102
+ readonly agentPresent: boolean;
103
+ readonly agentSpeaking: boolean;
104
+ readonly callerSpeaking: boolean;
105
+ readonly awaitingAgent: boolean;
106
+ }
107
+ export interface DockStateInput {
108
+ /** The shopper has expressed intent — before that the dock is resting, whatever the transports say. */
109
+ readonly engaged: boolean;
110
+ readonly voice: DockVoiceInput;
111
+ /** What is in the composer right now. Only `dormant` reads it, for the send control. */
112
+ readonly draft: string;
113
+ /** §5.5 — the shopper turned to the page during `speaking`. */
114
+ readonly ducked: boolean;
115
+ /** §8.6 — the session is being resumed (a navigation, a return from lock). */
116
+ readonly reconnecting: boolean;
117
+ /** The room itself dropped, so the resume needs a tap rather than just a wait. */
118
+ readonly roomDropped: boolean;
119
+ /** A PERSON holds the conversation (`UseChatSessionResult.status === 'escalated'`). */
120
+ readonly escalated: boolean;
121
+ /** The operator's last line, once they have said anything. */
122
+ readonly operatorLine?: string;
123
+ /** The attach control is escalated-only (`AGENTS.md` — the concierge has no vision path). */
124
+ readonly canAttach: boolean;
125
+ /**
126
+ * A host that can actually open the browser's own permission help (§5.1's
127
+ * `dock_fix_browser`).
128
+ *
129
+ * Gated for the same reason `canAttach` is: a control that provably does
130
+ * nothing is worse than no control. Nothing in the browser can open that UI
131
+ * from script, so most hosts have nothing to offer here — and
132
+ * `dock_mic_blocked` ("Mic blocked — type instead") already tells the
133
+ * shopper what they can do.
134
+ */
135
+ readonly canFixPermission: boolean;
136
+ readonly offline: boolean;
137
+ readonly offlineMessage?: string;
138
+ /**
139
+ * The host's status line, for the two claimants that are genuinely ERRORS:
140
+ * the conversation itself is broken, or the voice leg is (a refused
141
+ * microphone, a dead speech vendor).
142
+ */
143
+ readonly error?: string;
144
+ /**
145
+ * WHICH claimant `error` came from — the conversation, or the voice leg.
146
+ *
147
+ * The host resolves the precedence (session > voice) into one string before
148
+ * it reaches the dock, and the string alone cannot say what it is: this
149
+ * module has to know a voice CONNECT failed to swap its transport text for
150
+ * §5.1's `dock_voice_failed`, and it must not do that to a session error
151
+ * that merely happened while the room was also down.
152
+ */
153
+ readonly errorSource?: 'session' | 'voice';
154
+ /**
155
+ * A line the shopper needs to READ that is not an error — today, only
156
+ * `cart_add_failed`: the concierge said an item was going in the basket and
157
+ * only this browser knows it did not.
158
+ *
159
+ * It replaces the CAPTION and changes nothing else. Folding it into `error`
160
+ * instead cost the row its whole live state: an add that failed mid-call
161
+ * took `speaking` down to `error` for the rest of the session, so the
162
+ * clause disappeared and mute and interrupt went with it — and
163
+ * `agentAddFailed` is only cleared by the NEXT successful agent add, so it
164
+ * did not go away. §5.1 puts `cart_add_failed` in the caption; that is all
165
+ * it asks for.
166
+ */
167
+ readonly notice?: string;
168
+ /** How many cards the latest curation put on the shelf. */
169
+ readonly shelfCount: number;
170
+ readonly sheetOpen: boolean;
171
+ /** The live partial transcript, current utterance only (§5.1's `listening`). */
172
+ readonly partialTranscript?: string;
173
+ /** `FillerPolicy`'s model-authored acknowledgement (§6) — the designed `thinking` caption. */
174
+ readonly preamble?: string;
175
+ /** The clause the agent is saying right now (§5.1's `speaking`). */
176
+ readonly clause?: string;
177
+ }
178
+ export interface DockView {
179
+ readonly state: DockState;
180
+ readonly mark: DockMark;
181
+ readonly activity: DockActivity;
182
+ readonly caption: DockCaptionSpec;
183
+ /** At most three (§2), in draw order. */
184
+ readonly controls: readonly DockControl[];
185
+ readonly border: DockBorder;
186
+ readonly sheet: DockSheetPolicy;
187
+ /**
188
+ * There is a CALL to end — the room is being dialled, is up, or is waiting
189
+ * for the worker to join.
190
+ *
191
+ * The sheet's header hangs "End the call" off this rather than off the
192
+ * presence of an `onEndCall` handler, which is a property of the HOST and
193
+ * not of the session: `host-widget.tsx` passes the handler for any tenant
194
+ * with voice published, so the control stood in `dormant` before anything
195
+ * had been dialled and stayed standing after a connect that failed. A
196
+ * control whose only honest answer is "there is nothing to end" is the
197
+ * thing §5.1's table exists to prevent.
198
+ *
199
+ * Mute is not a hang-up and a reconnect is not a disconnection, so both
200
+ * keep it — it goes false only when the room is genuinely gone (`idle`,
201
+ * `disconnected`, `failed`) or the tenant has no voice leg at all.
202
+ */
203
+ readonly callActive: boolean;
204
+ /**
205
+ * The microphone is drawn but cannot be used — `human` only. DISABLED
206
+ * rather than hidden, the posture this widget already takes everywhere
207
+ * else: a mic that vanishes at the handoff reads as a bug, a dimmed one
208
+ * with a reason on it reads as the product.
209
+ */
210
+ readonly micDisabled?: boolean;
211
+ }
212
+ /** A dock nobody has touched, on a tenant with no voice. Every field explicit — see `DockStateInput`. */
213
+ export declare const idleDockInput: DockStateInput;
214
+ /**
215
+ * §5.1's table, as a function.
216
+ *
217
+ * @param input the session, as data — see {@link DockStateInput}
218
+ * @returns everything the row, the caption and the sheet need for one render
219
+ */
220
+ export declare function deriveDockState(input: DockStateInput): DockView;
221
+ //# sourceMappingURL=dock-state.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dock-state.d.ts","sourceRoot":"","sources":["../../src/dock/dock-state.ts"],"names":[],"mappings":"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"}