@saar-ai/web-widget 0.4.1 → 0.6.0

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 (68) 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/chat-tMKkYmTC.js +592 -0
  4. package/dist/chunks/host-widget-C0XT9lHX.js +9637 -0
  5. package/dist/chunks/{telemetry-Bw-3F_Zk.js → telemetry-BI_SEWTb.js} +104 -2
  6. package/dist/dock/dock-caption.d.ts +67 -0
  7. package/dist/dock/dock-caption.d.ts.map +1 -0
  8. package/dist/dock/dock-motion.d.ts +155 -0
  9. package/dist/dock/dock-motion.d.ts.map +1 -0
  10. package/dist/dock/dock-pill.d.ts +38 -0
  11. package/dist/dock/dock-pill.d.ts.map +1 -0
  12. package/dist/dock/dock-row.d.ts +120 -0
  13. package/dist/dock/dock-row.d.ts.map +1 -0
  14. package/dist/dock/dock-sheet.d.ts +89 -0
  15. package/dist/dock/dock-sheet.d.ts.map +1 -0
  16. package/dist/dock/dock-shelf.d.ts +38 -0
  17. package/dist/dock/dock-shelf.d.ts.map +1 -0
  18. package/dist/dock/dock-state.d.ts +221 -0
  19. package/dist/dock/dock-state.d.ts.map +1 -0
  20. package/dist/dock/dock.d.ts +344 -0
  21. package/dist/dock/dock.d.ts.map +1 -0
  22. package/dist/dock/geometry.d.ts +161 -0
  23. package/dist/dock/geometry.d.ts.map +1 -0
  24. package/dist/format-money.d.ts +54 -17
  25. package/dist/format-money.d.ts.map +1 -1
  26. package/dist/generated/widget-css.d.ts.map +1 -1
  27. package/dist/host-widget.d.ts +156 -16
  28. package/dist/host-widget.d.ts.map +1 -1
  29. package/dist/index.d.ts +7 -3
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +4029 -7
  32. package/dist/messages.d.ts +86 -0
  33. package/dist/messages.d.ts.map +1 -1
  34. package/dist/next/index.js +1 -1
  35. package/dist/session-log.d.ts +7 -0
  36. package/dist/session-log.d.ts.map +1 -1
  37. package/dist/session-panel.d.ts +13 -3
  38. package/dist/session-panel.d.ts.map +1 -1
  39. package/dist/theme/color.d.ts +114 -0
  40. package/dist/theme/color.d.ts.map +1 -0
  41. package/dist/theme/derive.d.ts +92 -0
  42. package/dist/theme/derive.d.ts.map +1 -0
  43. package/dist/theme/index.d.ts +10 -0
  44. package/dist/theme/index.d.ts.map +1 -0
  45. package/dist/turn-order.d.ts +106 -0
  46. package/dist/turn-order.d.ts.map +1 -0
  47. package/dist/use-chat-session.d.ts +146 -17
  48. package/dist/use-chat-session.d.ts.map +1 -1
  49. package/dist/use-voice-session.d.ts +110 -4
  50. package/dist/use-voice-session.d.ts.map +1 -1
  51. package/dist/voice-widget.d.ts +114 -24
  52. package/dist/voice-widget.d.ts.map +1 -1
  53. package/dist/widget-cards.d.ts +28 -1
  54. package/dist/widget-cards.d.ts.map +1 -1
  55. package/dist/widget.css +1 -1
  56. package/package.json +4 -4
  57. package/src/styles/concierge.css +803 -28
  58. package/src/styles/tokens.css +67 -0
  59. package/dist/chunks/chat-DfajYOmN.js +0 -240
  60. package/dist/chunks/host-widget-C9EyGeiN.js +0 -9745
  61. package/dist/concierge-launcher.d.ts +0 -53
  62. package/dist/concierge-launcher.d.ts.map +0 -1
  63. package/dist/concierge-shell.d.ts +0 -256
  64. package/dist/concierge-shell.d.ts.map +0 -1
  65. package/dist/position.d.ts +0 -65
  66. package/dist/position.d.ts.map +0 -1
  67. package/dist/transcript-geometry.d.ts +0 -220
  68. package/dist/transcript-geometry.d.ts.map +0 -1
@@ -65,3 +65,70 @@
65
65
  --background: oklch(14% 0.01 280);
66
66
  --foreground: oklch(97% 0.006 84.6);
67
67
  }
68
+
69
+ /*
70
+ * ---------------------------------------------------------------------------
71
+ * DOCK TOKENS (`--wgt-*`) — docs/DOCK_SPEC.md §9.2.
72
+ *
73
+ * ADDITIVE, alongside the `--widget-*` roles above. The two sets coexist on
74
+ * purpose: the shipped panel still reads `--widget-*` and will keep reading
75
+ * them until DOCK_SPEC §17 PR 4 replaces `ConciergeShell`, while the dock's
76
+ * row, pill and sheet read only `--wgt-*`. Removing or renaming anything
77
+ * above would break the widget that is live on merchant sites today.
78
+ *
79
+ * These are DEFAULTS, not the theme. A published tenant config is turned into
80
+ * the same twelve properties by `src/theme/derive.ts` and written onto the
81
+ * shadow host — as an inline `style` attribute by the CDN `core` stage, and as
82
+ * an adopted stylesheet by the React dock — where they override this block.
83
+ * What lives here is the neutral fallback that renders a correct, readable
84
+ * dock when no config has arrived yet (first paint, a failed
85
+ * `GET /widget/config`, a Storybook story with no theme decorator).
86
+ *
87
+ * The values are the exact output of
88
+ * `deriveTheme({ primary: '#111827', tone: 'auto' }, { font: 'inherit',
89
+ * radius: 'soft', caps: 'none' })` — copied rather than computed, because CSS
90
+ * cannot call the function and a hand-tuned near-miss here would make the
91
+ * fallback and the themed dock two different-looking widgets. Regenerate them
92
+ * from `deriveTheme` if the derivation changes; do not tune them by eye.
93
+ *
94
+ * Dark uses the SAME `.dark` class hook as the block above, not
95
+ * `prefers-color-scheme` — the shadow host's class is what the mount controls,
96
+ * and a media query here would fight it. `themeToCss` emits the media query
97
+ * for a themed dock; this fallback follows the host's explicit choice.
98
+ * --------------------------------------------------------------------------- */
99
+
100
+ :host,
101
+ :root {
102
+ --wgt-primary: #111827;
103
+ --wgt-on-primary: #ffffff;
104
+ --wgt-accent: #191525;
105
+ --wgt-surface: #ffffff;
106
+ --wgt-surface-2: #f0efef;
107
+ --wgt-text: #1c1618;
108
+ --wgt-text-muted: rgb(28 22 24 / 0.62);
109
+ --wgt-border: rgb(28 22 24 / 0.12);
110
+ --wgt-ring: #111827;
111
+ --wgt-radius: 12px;
112
+ --wgt-sheet-radius: 12px;
113
+ --wgt-card-radius: 12px;
114
+ --wgt-font: inherit;
115
+ --wgt-caps: none;
116
+ }
117
+
118
+ :host(.dark),
119
+ .dark {
120
+ --wgt-primary: #111827;
121
+ --wgt-on-primary: #ffffff;
122
+ --wgt-accent: #191525;
123
+ --wgt-surface: #141414;
124
+ --wgt-surface-2: #1f1f1f;
125
+ --wgt-text: #fbf2f5;
126
+ --wgt-text-muted: rgb(251 242 245 / 0.62);
127
+ --wgt-border: rgb(251 242 245 / 0.12);
128
+ --wgt-ring: #5a6376;
129
+ --wgt-radius: 12px;
130
+ --wgt-sheet-radius: 12px;
131
+ --wgt-card-radius: 12px;
132
+ --wgt-font: inherit;
133
+ --wgt-caps: none;
134
+ }
@@ -1,240 +0,0 @@
1
- import { a as httpUrl, c as number, i as discriminatedUnion, l as object, n as array, o as literal, r as boolean, u as string } from "./schemas-Bl_6mxe4.js";
2
- //#region ../widget-protocol/dist/chat.js
3
- /**
4
- * The webchat SSE wire contract, and the sidecar `widgetEvent` a tool result
5
- * may carry to short-circuit into one of those events.
6
- *
7
- * ## Why this lives in `@saar-ai/widget-protocol`, zod, not a plain interface
8
- *
9
- * Two independent runtimes read this shape: `apps/api`'s
10
- * `widget-chat.controller.ts` WRITES it onto an SSE response, and
11
- * `@saar-ai/web-widget`'s voice leg (`use-voice-session.ts`, via the
12
- * `widget.event` sidecar on the telemetry channel — see `./telemetry.ts`)
13
- * PARSES `WidgetToolEventSchema` off it. A hand-maintained interface on each
14
- * side drifts silently — the failure mode is a widget that renders
15
- * `undefined` for a field the server renamed. Zod schemas, exported from one
16
- * package both sides can import, make the shape a single source of truth and
17
- * let each side `.parse()`/`.safeParse()` at its own boundary instead of
18
- * trusting an unchecked cast.
19
- *
20
- * Moved here from the framework-inherited `@wesence/shared-types` — this
21
- * package's own `AGENTS.md` explains why a widget-only contract does not
22
- * belong inside a package a framework regeneration can silently clobber, and
23
- * why it must not be reachable from `@saar-ai/web-widget`'s published bundle
24
- * via a `@wesence/*` import path at all (docs/PACKAGE_DISTRIBUTION.md).
25
- *
26
- * ## The six event types, and why cards/checkout are separate events from text
27
- *
28
- * A reply may interleave prose with product/price/checkout data. Prices,
29
- * stock, and product attributes are NEVER stated as text by the model (see
30
- * `widget-chat.service.ts`'s system-prompt guardrail) — they arrive only as
31
- * `cards`, sourced from a tool result, so the widget can render them as
32
- * structured UI (an image, a price, an availability badge) rather than text
33
- * the model could hallucinate. The real checkout URL is likewise never typed
34
- * by the model — it arrives only as `checkout`.
35
- *
36
- * - `text-delta` — one chunk of the assistant's streamed reply.
37
- * - `cards` — one or more product/curation cards to render.
38
- * - `escalated` — the conversation just moved to a human/queue; the AI
39
- * will not reply further on this turn. The widget should show a "connecting
40
- * you with a person" state and start polling `/widget/messages`.
41
- * - `checkout` — a real Shopify cart permalink to hand the shopper off
42
- * to; the widget renders a "Go to checkout" control around `url`.
43
- * - `done` — the turn is over. Carries the turn id so the widget can
44
- * correlate a later `/widget/messages` page against what it already
45
- * rendered inline.
46
- * - `error` — the turn failed. `message` is safe to show the visitor
47
- * (never a raw exception/stack).
48
- *
49
- * ## `widgetEvent` — the tool-result sidecar
50
- *
51
- * A tool (e.g. a product-search tool) may attach `widgetEvent` to its output
52
- * to ask the chat loop to forward one of these events verbatim, alongside the
53
- * tool's own return value the model sees. Only `cards`, `escalated`, and
54
- * `checkout` are valid sidecar events — `text-delta`/`done`/`error` are
55
- * lifecycle events the runtime itself owns and a tool must never emit.
56
- */
57
- /** Bound for a display string a card renders. Never free-form model prose. */
58
- var CARD_TEXT_MAX = 500;
59
- /** Bound for an id-shaped field (product/variant/curation ids). */
60
- var ID_MAX = 200;
61
- /**
62
- * One product/curation card. `priceMinor` is the ISO 4217 minor-unit integer
63
- * (cents, paise, …) — never a float — and `currency` is the ISO 4217 code, so
64
- * the widget formats price itself rather than trusting a pre-formatted
65
- * string the model could get wrong.
66
- */
67
- var WidgetChatCardSchema = object({
68
- productId: string().min(1).max(ID_MAX),
69
- /** The INTERNAL catalog UUID (`curation_items.variant_id`) — never a platform id. See `platformVariantId` for what a storefront `addToCart` bridge actually needs. */
70
- variantId: string().min(1).max(ID_MAX).optional(),
71
- /**
72
- * The PLATFORM-NATIVE variant id (e.g. Shopify's numeric `/cart/add.js`
73
- * id) — extracted server-side from the variant's provider GID via
74
- * `apps/api/src/catalog/checkout-permalink.ts`'s
75
- * `parseShopifyVariantNumericId`, the SAME parser the checkout permalink
76
- * uses, never a string-slice of `variantId`. `@saar-ai/web-widget`'s
77
- * `resolveAddToCartHandler` calls a storefront bridge's `addToCart` with
78
- * THIS field, never `variantId` (adversarial-review finding #2 — the
79
- * internal UUID is meaningless to `ShopifyBridge`'s `POST /cart/add.js`).
80
- * Absent whenever the underlying variant's external id isn't a
81
- * recognised platform GID (§5.3's "degrade, never fabricate" — never
82
- * guessed) — the widget then offers no add-to-cart action for the card
83
- * and falls back to a PDP navigation instead.
84
- */
85
- platformVariantId: string().min(1).max(ID_MAX).optional(),
86
- title: string().min(1).max(CARD_TEXT_MAX),
87
- /** http(s) only — `z.httpUrl()` refuses `javascript:`/`data:`/etc, the same scheme allowlist `conversations/attribution.ts` enforces for stored URLs. */
88
- imageUrl: httpUrl().optional(),
89
- /**
90
- * The product's storefront handle, so the widget's card can link to its PDP.
91
- *
92
- * A SLUG, never a URL or a path: the widget's host builds the href from it
93
- * (`widget-launcher.tsx`'s `productHref`), so anything path-like here would
94
- * let a catalogue row steer where a card points. The character class below
95
- * is what a Shopify handle actually is, and it cannot express a scheme, a
96
- * host, a `..` segment or a leading slash.
97
- */
98
- handle: string().min(1).max(ID_MAX).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/i).optional(),
99
- /** ISO 4217 minor units — an integer, never a float. */
100
- priceMinor: number().int().min(0),
101
- /** ISO 4217 currency code, e.g. "USD". */
102
- currency: string().length(3),
103
- available: boolean(),
104
- /** Short, optional "why this" — e.g. "matches your search". Never a price/stock claim. */
105
- reason: string().max(CARD_TEXT_MAX).optional()
106
- });
107
- var WidgetChatTextDeltaEventSchema = object({
108
- type: literal("text-delta"),
109
- delta: string()
110
- });
111
- var WidgetChatCardsEventSchema = object({
112
- type: literal("cards"),
113
- /** Correlates this render back to whichever tool call produced it, when the tool supplies one. */
114
- curationId: string().min(1).max(ID_MAX).optional(),
115
- items: array(WidgetChatCardSchema).min(1).max(20)
116
- });
117
- var WidgetChatEscalatedEventSchema = object({ type: literal("escalated") });
118
- /**
119
- * A real Shopify checkout handoff — `checkout_handoff` (the concierge tool)
120
- * emits this as a `widgetEvent` sidecar so the widget can render a "Go to
121
- * checkout" control instead of the model reciting a raw URL. `url` is a
122
- * SERVER-BUILT Shopify cart permalink (`apps/api/src/catalog/checkout-permalink.ts`)
123
- * — never a client- or model-supplied value; it carries no internal
124
- * identifier, only Shopify variant ids/quantities and an opaque attribution
125
- * token (see that module's doc comment).
126
- */
127
- var WidgetChatCheckoutEventSchema = object({
128
- type: literal("checkout"),
129
- handoffId: string().min(1).max(ID_MAX),
130
- url: httpUrl(),
131
- itemCount: number().int().positive()
132
- });
133
- var WidgetChatDoneEventSchema = object({
134
- type: literal("done"),
135
- turnId: string().min(1)
136
- });
137
- var WidgetChatErrorEventSchema = object({
138
- type: literal("error"),
139
- /** Safe to show the visitor as-is — never a raw exception message or stack. */
140
- message: string().min(1).max(CARD_TEXT_MAX)
141
- });
142
- /** The full SSE event union — every `event:`/`data:` pair `/widget/chat` may write. */
143
- var WidgetChatSseEventSchema = discriminatedUnion("type", [
144
- WidgetChatTextDeltaEventSchema,
145
- WidgetChatCardsEventSchema,
146
- WidgetChatEscalatedEventSchema,
147
- WidgetChatCheckoutEventSchema,
148
- WidgetChatDoneEventSchema,
149
- WidgetChatErrorEventSchema
150
- ]);
151
- /**
152
- * What a tool result may carry, under an `output.widgetEvent` key, to ask the
153
- * chat loop to forward one of these as its own SSE event. Deliberately a
154
- * NARROWER union than {@link WidgetChatSseEventSchema} — `text-delta`,
155
- * `done`, and `error` are lifecycle events the runtime alone controls; a tool
156
- * asserting one of those could inject a fake "done" mid-stream or spoof a
157
- * fake error to the visitor.
158
- */
159
- var WidgetToolEventSchema = discriminatedUnion("type", [
160
- WidgetChatCardsEventSchema,
161
- WidgetChatEscalatedEventSchema,
162
- WidgetChatCheckoutEventSchema
163
- ]);
164
- /**
165
- * ## Storefront reports — the OTHER direction, and why they are not messages
166
- *
167
- * A chat request carries EITHER a shopper `message` or a `report`: a typed
168
- * statement of something the STOREFRONT did, which the shopper never typed.
169
- * Today there is exactly one kind, `cart_add`, sent by
170
- * `@saar-ai/web-widget`'s `ConciergeWidget` the moment a bridge add resolves,
171
- * so the concierge can answer with something that goes WITH the item.
172
- *
173
- * It replaced a free-text `Added <title> to cart` sentence sent over the
174
- * ordinary shopper message channel, which had three defects a shape fixes:
175
- * a shopper who TYPED those words got the storefront's treatment; the
176
- * synthetic sentence persisted as a shopper line in the operator's
177
- * transcript; and the server matched it by its exact wording, so any change
178
- * to how a card renders a title broke the match with nothing failing.
179
- *
180
- * **The sentence the model sees is composed SERVER-side** from these fields
181
- * (`apps/api/src/widget/widget-chat.service.ts`'s
182
- * `composeStorefrontReportText`) — the client no longer authors any part of
183
- * the model's input, which is what makes shopper prose and a storefront
184
- * report structurally impossible to confuse.
185
- *
186
- * **Still client-asserted, and that is unchanged.** A report is trusted
187
- * exactly as far as the chat token that carried it: whoever holds a session
188
- * can claim an add that never happened, precisely as they could type the old
189
- * sentence. Cross-verifying a report against the server's own
190
- * `CheckoutHandoffService.recordCartAdd` record is explicitly out of scope —
191
- * the win here is typing, non-collision with shopper prose, and a turn the
192
- * console can tell apart, not a new trust boundary.
193
- */
194
- var REPORT_TITLE_MAX = CARD_TEXT_MAX;
195
- /**
196
- * The storefront reporting a completed add. `title` is the card's own
197
- * display title (what the shopper saw); the ids are the catalog's, carried
198
- * so a later consumer can join the report to a product without re-matching
199
- * on prose.
200
- */
201
- var WidgetCartAddReportSchema = object({
202
- kind: literal("cart_add"),
203
- /**
204
- * Trimmed before it is bounded, so a whitespace-only title is a
205
- * rejection rather than a report that names nothing: the server trims
206
- * the title again when it composes its line, and `min(1)` on the raw
207
- * string would let `" "` through to `added ""`.
208
- */
209
- title: string().trim().min(1).max(REPORT_TITLE_MAX),
210
- quantity: number().int().min(1).max(999),
211
- /** The INTERNAL catalog UUID — same field, same meaning, as {@link WidgetChatCardSchema}'s. */
212
- variantId: string().min(1).max(ID_MAX).optional(),
213
- productId: string().min(1).max(ID_MAX).optional()
214
- }).strict();
215
- /**
216
- * Every report kind a chat request may carry. A discriminated union of one
217
- * today — the shape a second kind (`cart_removed`, `checkout_started`) slots
218
- * into without touching either side's parse code.
219
- */
220
- var WidgetChatReportSchema = discriminatedUnion("kind", [WidgetCartAddReportSchema]);
221
- /**
222
- * Parse a request body's `report` field. Never throws — the caller decides
223
- * whether `null` means "absent" (no report was sent) or "malformed", which
224
- * `apps/api`'s widget chat controller distinguishes by checking presence
225
- * first and rejecting a present-but-unparseable value with a 400.
226
- */
227
- function parseWidgetChatReport(value) {
228
- const parsed = WidgetChatReportSchema.safeParse(value);
229
- return parsed.success ? parsed.data : null;
230
- }
231
- /** Parse a tool's raw output for an optional, well-shaped `widgetEvent`. Never throws. */
232
- function extractWidgetToolEvent(output) {
233
- if (typeof output !== "object" || output === null) return null;
234
- const candidate = output["widgetEvent"];
235
- if (candidate === void 0) return null;
236
- const parsed = WidgetToolEventSchema.safeParse(candidate);
237
- return parsed.success ? parsed.data : null;
238
- }
239
- //#endregion
240
- export { WidgetCartAddReportSchema, WidgetChatCardSchema, WidgetChatCardsEventSchema, WidgetChatCheckoutEventSchema, WidgetChatDoneEventSchema, WidgetChatErrorEventSchema, WidgetChatEscalatedEventSchema, WidgetChatReportSchema, WidgetChatSseEventSchema, WidgetChatTextDeltaEventSchema, WidgetToolEventSchema, extractWidgetToolEvent, parseWidgetChatReport };