@saar-ai/web-widget 0.9.0 → 0.10.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 (50) hide show
  1. package/dist/chunks/{chat-DAgqVvIS.js → chat-CU9VPqVO.js} +112 -16
  2. package/dist/chunks/{host-widget-CTK7C95y.js → host-widget-BtiYIMwb.js} +5456 -343
  3. package/dist/chunks/{schemas-D-uDc-9q.js → schemas-YN3wGSGZ.js} +7 -4
  4. package/dist/chunks/{telemetry-DQUulENJ.js → telemetry-B1xBTk1s.js} +1 -1
  5. package/dist/dock/dock-drag.d.ts +5 -5
  6. package/dist/dock/dock-drag.d.ts.map +1 -1
  7. package/dist/dock/dock-float.d.ts +116 -0
  8. package/dist/dock/dock-float.d.ts.map +1 -0
  9. package/dist/dock/dock-motion.d.ts +61 -6
  10. package/dist/dock/dock-motion.d.ts.map +1 -1
  11. package/dist/dock/dock-pill.d.ts +18 -1
  12. package/dist/dock/dock-pill.d.ts.map +1 -1
  13. package/dist/dock/dock-row.d.ts +128 -10
  14. package/dist/dock/dock-row.d.ts.map +1 -1
  15. package/dist/dock/dock-sheet.d.ts.map +1 -1
  16. package/dist/dock/dock-state.d.ts +129 -9
  17. package/dist/dock/dock-state.d.ts.map +1 -1
  18. package/dist/dock/dock.d.ts +103 -24
  19. package/dist/dock/dock.d.ts.map +1 -1
  20. package/dist/dock/geometry.d.ts +129 -3
  21. package/dist/dock/geometry.d.ts.map +1 -1
  22. package/dist/generated/widget-css.d.ts.map +1 -1
  23. package/dist/host-widget.d.ts +61 -2
  24. package/dist/host-widget.d.ts.map +1 -1
  25. package/dist/index.d.ts +1 -1
  26. package/dist/index.d.ts.map +1 -1
  27. package/dist/index.js +4 -3889
  28. package/dist/messages.d.ts +88 -1
  29. package/dist/messages.d.ts.map +1 -1
  30. package/dist/next/index.js +1 -1
  31. package/dist/rope-knot.d.ts +67 -0
  32. package/dist/rope-knot.d.ts.map +1 -1
  33. package/dist/theme/derive.d.ts +1 -1
  34. package/dist/theme/derive.d.ts.map +1 -1
  35. package/dist/use-chat-session.d.ts +33 -1
  36. package/dist/use-chat-session.d.ts.map +1 -1
  37. package/dist/use-voice-session.d.ts +2 -0
  38. package/dist/use-voice-session.d.ts.map +1 -1
  39. package/dist/voice-widget.d.ts +22 -1
  40. package/dist/voice-widget.d.ts.map +1 -1
  41. package/dist/widget-cards.d.ts +21 -1
  42. package/dist/widget-cards.d.ts.map +1 -1
  43. package/dist/widget-cart-summary.d.ts +10 -1
  44. package/dist/widget-cart-summary.d.ts.map +1 -1
  45. package/dist/widget.css +1 -1
  46. package/package.json +7 -3
  47. package/src/styles/concierge.css +528 -65
  48. package/src/styles/dock-surface.css +284 -0
  49. package/src/styles/tokens.css +22 -6
  50. package/src/styles/widget-entry.css +3 -0
@@ -1,4 +1,4 @@
1
- import { a as httpUrl, c as number, d as string, i as discriminatedUnion, l as object, n as array, o as literal, r as boolean, t as _enum, u as record } from "./schemas-D-uDc-9q.js";
1
+ import { a as httpUrl, c as number, d as string, f as uuid, i as discriminatedUnion, l as object, n as array, o as literal, r as boolean, t as _enum, u as record } from "./schemas-YN3wGSGZ.js";
2
2
  //#region ../widget-protocol/dist/act.js
3
3
  /**
4
4
  * ACT EVENTS — the concierge moving the store, rather than only describing it.
@@ -326,7 +326,33 @@ var WidgetChatCardSchema = object({
326
326
  currency: CURRENCY_CODE,
327
327
  available: boolean(),
328
328
  /** Short, optional "why this" — e.g. "matches your search". Never a price/stock claim. */
329
- reason: string().max(CARD_TEXT_MAX).optional()
329
+ reason: string().max(CARD_TEXT_MAX).optional(),
330
+ /**
331
+ * `true` when the product has MORE THAN ONE sellable variant, so the
332
+ * shopper has to choose one before anything can go in their cart (SAA-175,
333
+ * owner rule: never add a variant the shopper did not choose). Omitted
334
+ * otherwise — never `false`.
335
+ *
336
+ * `variantId`/`platformVariantId`/`priceMinor` on such a card still
337
+ * describe ONE variant — the representative `build_curation` priced the card
338
+ * with (`pickRepresentativeVariant`) — and that is exactly why they must not
339
+ * be added: the shopper never picked it. `@saar-ai/web-widget` replaces the
340
+ * card's Add button with "Choose options", which asks the concierge (whose
341
+ * `add_to_cart` answers `needs_variant_choice`) or opens the product page.
342
+ *
343
+ * A bare literal, deliberately: it carries no option names, labels or
344
+ * prices, so it adds no merchant text to the wire and nothing the model
345
+ * could be handed.
346
+ *
347
+ * **Deploy skew.** A widget bundle that predates this field ignores it: the
348
+ * typed leg casts `items` without parsing, and this schema is a plain
349
+ * `z.object`, which STRIPS an unknown key rather than refusing the card. An
350
+ * old widget therefore draws its old Add button, which is what it did
351
+ * before the field existed — the gap closes when the widget ships, and no
352
+ * capability negotiation is needed. Keep this schema non-strict for that
353
+ * reason; `__tests__/chat.variant-choice.test.ts` pins it.
354
+ */
355
+ variantChoiceRequired: literal(true).optional()
330
356
  });
331
357
  var WidgetChatTextDeltaEventSchema = object({
332
358
  type: literal("text-delta"),
@@ -356,13 +382,18 @@ var WidgetChatCardsEventSchema = object({
356
382
  * `available` stay OUT of this list on purpose: there is no honest way to
357
383
  * show a product with no price, or a price with no currency, so a failure in
358
384
  * one of those drops the whole card instead (see {@link buildWidgetChatCard}).
385
+ *
386
+ * `variantChoiceRequired` is droppable because every producer writes it as a
387
+ * literal `true` or not at all, so a refusal there is a producer bug, and a
388
+ * producer bug should not cost the shopper the recommendation.
359
389
  */
360
390
  var DROPPABLE_CARD_FIELDS = [
361
391
  "variantId",
362
392
  "platformVariantId",
363
393
  "imageUrl",
364
394
  "handle",
365
- "reason"
395
+ "reason",
396
+ "variantChoiceRequired"
366
397
  ];
367
398
  /**
368
399
  * Generic "try the whole candidate; if every refusal is on a DROPPABLE field,
@@ -600,8 +631,9 @@ var WidgetCartAddReportSchema = object({
600
631
  *
601
632
  * ## Why this kind has to exist
602
633
  *
603
- * `add_to_cart` (`apps/api/src/catalog/tools/add-to-cart.tool.ts`) returns
604
- * `status: 'requested'` and can never return more: the cart lives in the
634
+ * `add_to_cart` (`apps/api/src/catalog/tools/add-to-cart.tool.ts`) has no
635
+ * status meaning "added": at most `status: 'requested'`, the only answer that
636
+ * emits an event. The cart lives in the
605
637
  * shopper's browser, behind their own session cookie, and the server has no
606
638
  * handle on it. The add is performed afterwards by `@saar-ai/web-widget`'s
607
639
  * `ConciergeWidget` (`performAgentCartAdd`), and when the host bridge rejects
@@ -633,6 +665,40 @@ var WidgetCartAddFailedReportSchema = object({
633
665
  productId: string().min(1).max(ID_MAX).optional()
634
666
  }).strict();
635
667
  /**
668
+ * The storefront reporting that the shopper pressed "Choose options" on a card
669
+ * for a product with more than one sellable variant
670
+ * ({@link WidgetChatCardSchema}'s `variantChoiceRequired`, SAA-175).
671
+ *
672
+ * ## Why a report, and not a sentence the widget types for the shopper
673
+ *
674
+ * The first cut sent "What options does {title} come in?" as an ordinary
675
+ * shopper message. Review found three defects in that, and a typed report
676
+ * fixes all three:
677
+ *
678
+ * - **Injection.** The title is merchant data, and it landed verbatim in a
679
+ * USER-role turn, the one place the model is told to take instructions from
680
+ * the shopper. Here the server composes the model's line from `productId`
681
+ * alone (`composeStorefrontReportText`); `title` never reaches the model.
682
+ * - **Misattribution.** The desk transcript showed the widget's sentence as
683
+ * the shopper's own words. A report renders as a storefront event.
684
+ * - **Loop.** A free-text line is indistinguishable from the shopper asking
685
+ * again, so nothing could tell the server this turn is an open variant
686
+ * question. The report kind is that signal: the server stands its forced
687
+ * curation down for it.
688
+ *
689
+ * `productId` is the catalog UUID the card carries, validated as one, because
690
+ * it is the only id the model is told to pass to `add_to_cart`. `title` is the
691
+ * card's display title, trimmed and bounded like every other report title, and
692
+ * kept ONLY as a label for the operator's transcript. `.strict()`: no
693
+ * `variantId` can ride along, since a variant is exactly what the shopper has
694
+ * not chosen yet.
695
+ */
696
+ var WidgetVariantChoiceRequestReportSchema = object({
697
+ kind: literal("variant_choice_request"),
698
+ productId: uuid(),
699
+ title: string().trim().min(1).max(REPORT_TITLE_MAX).optional()
700
+ }).strict();
701
+ /**
636
702
  * Every report kind a chat request may carry — the shape a further kind
637
703
  * (`cart_removed`, `checkout_started`) slots into without touching either
638
704
  * side's parse code.
@@ -648,7 +714,8 @@ var WidgetChatReportSchema = discriminatedUnion("kind", [
648
714
  WidgetCartAddReportSchema,
649
715
  WidgetCartAddFailedReportSchema,
650
716
  WidgetSpotlightFailedReportSchema,
651
- WidgetNavigateFailedReportSchema
717
+ WidgetNavigateFailedReportSchema,
718
+ WidgetVariantChoiceRequestReportSchema
652
719
  ]);
653
720
  /**
654
721
  * Parse a request body's `report` field. Never throws — the caller decides
@@ -714,7 +781,8 @@ function buildWidgetChatCardsEvent(curationId, items) {
714
781
  priceMinor: item.priceMinor,
715
782
  currency: item.currency,
716
783
  available: true,
717
- ...item.reason !== null ? { reason: item.reason } : {}
784
+ ...item.reason !== null ? { reason: item.reason } : {},
785
+ ...item.variantChoiceRequired === true ? { variantChoiceRequired: true } : {}
718
786
  });
719
787
  if (card !== null) cards.push(card);
720
788
  }
@@ -829,16 +897,40 @@ function buildWidgetChatCardsEvent(curationId, items) {
829
897
  * bounded integers, and `.strict()` on both objects so an unknown key is a
830
898
  * rejection rather than something that reaches the prompt.
831
899
  *
832
- * ### What is deliberately NOT on a line
833
- *
834
- * No product or variant ids. The `cart_add` report carries them so a consumer
835
- * can join a report to a product without re-matching prose; nothing joins
836
- * this snapshot to anything — it exists to be READ, in one prompt section, by
837
- * a model that has no use for a UUID and every reason not to be handed one it
838
- * might repeat to a shopper.
900
+ * ### Variant ids ride the wire — and are stripped before any prompt
901
+ *
902
+ * A line MAY name the variant it is (SAA-174), in either id space, both
903
+ * optional: {@link CART_LINE_VARIANT_ID_PATTERN | `variantId`}, our INTERNAL
904
+ * catalogue UUID (what a widget-sourced line built from a card knows, and
905
+ * what a `'catalog'`-space host knows), and
906
+ * {@link CART_LINE_PLATFORM_VARIANT_ID_PATTERN | `platformVariantId`}, the
907
+ * storefront platform's own numeric id (Shopify's `/cart.js` `variant_id`).
908
+ * They exist for ONE consumer: `apps/api`'s price-drift check, which joins a
909
+ * line to `product_variants.price` and logs when the storefront's unit price
910
+ * and our catalogue disagree. That is a signal for us, never for the model —
911
+ * it changes nothing the concierge says, and the storefront's own figures
912
+ * are still the ones quoted.
913
+ *
914
+ * So the ids MUST be stripped before a cart is rendered into a prompt or
915
+ * published to the turn tier (`apps/api`'s `toShopperCart`). A model has no
916
+ * use for a UUID and every reason not to be handed one it might repeat to a
917
+ * shopper, and `@wesence/agent-core`'s `ShopperCartLineSchema` is strict and
918
+ * deliberately does not know these keys.
919
+ *
920
+ * Shaped, not merely bounded: a UUID and a positive integer of at most 20
921
+ * digits, so an id is never free text on its way into a tenant-scoped query
922
+ * or a log line. A client filters with the exported patterns before sending
923
+ * (`@saar-ai/web-widget`'s `toChatCart`), because a malformed id is a 400
924
+ * like any other malformed field. Trust is unchanged: an id is as
925
+ * client-asserted as the price beside it, and a forged one can only point
926
+ * the drift log at a different row of the SAME tenant's catalogue.
839
927
  */
840
928
  /** Bound on a cart line's display title. Tighter than a card's: fifty of these ride in one prompt section. */
841
929
  var CART_LINE_TITLE_MAX = 200;
930
+ /** Shape of a cart line's INTERNAL catalogue variant id — a UUID, any version, either case. */
931
+ var CART_LINE_VARIANT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
932
+ /** Shape of a cart line's PLATFORM variant id — a positive integer in decimal, no leading zero, at most 20 digits (Shopify's numeric variant id). Never a GID. */
933
+ var CART_LINE_PLATFORM_VARIANT_ID_PATTERN = /^[1-9][0-9]{0,19}$/;
842
934
  /** A basket, not a warehouse. Fifty lines is far past any real storefront cart and still a bounded prompt. */
843
935
  var MAX_CART_LINES = 50;
844
936
  /** A billion minor units — past any real cart line or subtotal, and far short of where an integer stops being exact. */
@@ -855,7 +947,11 @@ var WidgetChatCartLineSchema = object({
855
947
  /** Trimmed before it is bounded, so a whitespace-only title is a rejection rather than a line that names nothing — same reasoning as the report's `title`. */
856
948
  title: string().trim().min(1).max(CART_LINE_TITLE_MAX),
857
949
  quantity: number().int().min(1).max(REPORT_QUANTITY_MAX),
858
- priceMinor: number().int().min(0).max(CART_AMOUNT_MINOR_MAX)
950
+ priceMinor: number().int().min(0).max(CART_AMOUNT_MINOR_MAX),
951
+ /** INTERNAL catalogue variant id, for the server's price-drift join only — see "Variant ids ride the wire" above. Never rendered. */
952
+ variantId: string().regex(CART_LINE_VARIANT_ID_PATTERN).optional(),
953
+ /** The storefront platform's numeric variant id, for the same join — see above. Never rendered. */
954
+ platformVariantId: string().regex(CART_LINE_PLATFORM_VARIANT_ID_PATTERN).optional()
859
955
  }).strict();
860
956
  /**
861
957
  * Where the lines came from, because it changes what the reply may honestly
@@ -901,4 +997,4 @@ function parseWidgetChatCart(value) {
901
997
  return parsed.success ? parsed.data : null;
902
998
  }
903
999
  //#endregion
904
- export { DROPPABLE_CARD_FIELDS, MAX_CARDS_PER_EVENT, MAX_CART_LINES, WidgetCartAddFailedReportSchema, WidgetCartAddReportSchema, WidgetChatAddToCartEventSchema, WidgetChatCardSchema, WidgetChatCardsEventSchema, WidgetChatCartLineSchema, WidgetChatCartSchema, WidgetChatCartSourceSchema, WidgetChatCheckoutEventSchema, WidgetChatDoneEventSchema, WidgetChatErrorEventSchema, WidgetChatEscalatedEventSchema, WidgetChatReportSchema, WidgetChatSseEventSchema, WidgetChatTextDeltaEventSchema, WidgetToolEventSchema, buildWidgetChatCard, buildWidgetChatCardsEvent, buildWithDroppableFields, extractWidgetToolEvent, parseWidgetChatCart, parseWidgetChatReport };
1000
+ export { CART_LINE_PLATFORM_VARIANT_ID_PATTERN, CART_LINE_VARIANT_ID_PATTERN, DROPPABLE_CARD_FIELDS, MAX_CARDS_PER_EVENT, MAX_CART_LINES, WidgetCartAddFailedReportSchema, WidgetCartAddReportSchema, WidgetChatAddToCartEventSchema, WidgetChatCardSchema, WidgetChatCardsEventSchema, WidgetChatCartLineSchema, WidgetChatCartSchema, WidgetChatCartSourceSchema, WidgetChatCheckoutEventSchema, WidgetChatDoneEventSchema, WidgetChatErrorEventSchema, WidgetChatEscalatedEventSchema, WidgetChatReportSchema, WidgetChatSseEventSchema, WidgetChatTextDeltaEventSchema, WidgetToolEventSchema, WidgetVariantChoiceRequestReportSchema, buildWidgetChatCard, buildWidgetChatCardsEvent, buildWithDroppableFields, extractWidgetToolEvent, parseWidgetChatCart, parseWidgetChatReport };