@souldi/try-on 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+**Breaking.** Refine and the size screen leave the widget (ADR-0095).
+
+- **One screen.** The result dialog is one **Try-on** screen. Before a try-on it shows the garment, the customer's size, the cart button and **Try on**; while the try-on is made the garment fades under a progress line, "Creating your try-on…", and the dialog stays open until the result lands. The size on the button opens it, before and after a try-on.
+- **Removed: the size screen.** "How size X sits on you" and its 3D mannequin are gone from the dialog, and the size in the dialog is no longer a button. The mannequin's standalone build is still published, for older bundles that load it.
+- **Removed: Refine.** The dialog has no Refine control, and the button handle's `refine()` is gone. `onError` no longer reports `operation: 'refine'`, and `onGenerationSuccess` / `onResultShown` no longer carry `refinable`. Refine stays in the Souldi API; the widget never sends a `refinement_prompt`.
+- `openSize()` on the button handle still opens the dialog on the customer's size. Before a try-on it now shows the garment and **Try on** there.
+- **New: between two sizes, the customer picks.** When the customer is between two neighbouring sizes, the dialog shows "Your size: between M and L" with two options, M for a closer fit and L for a looser one, the recommended one preselected, and "Both will fit you." under them. **Add size X to cart** follows the choice; a new recommendation (edited measurements, another colour) resets it. Shown only where there is a cart button; otherwise the dialog names one size and gives the same advice in words. A customer whose second size is not a neighbour still sees one size, now captioned "This one is harder to call." alone (it used to follow "From your measurements.").
+- **`onAddToCart` gains `recommendedSize` and `recommendationId`** beside `size`, which is the size the customer chose. Additive: a handler that reads `size` alone keeps working. See [`onAddToCart`](README.md#onaddtocart).
+
 ## 0.5.0
 
 **Breaking.** `init({ appearance })` replaces the `theme` option.

package/README.md

@@ -61,19 +61,20 @@ The result surface is the widget's and only the widget's: an accessible
 `<dialog>` inside an isolated Shadow DOM, appended to `<body>`. It reads none of
 your CSS selectors and never touches your product images, so a theme change
 cannot break it — and there is nothing to point it at. It is also where the
-customer decides. It has two screens:
-
-- **Try-on** — the render, beside the customer's size (when the garment has a
-  size chart), an **Add size X to cart** button (when you supply
-  [`onAddToCart`](#onaddtocart)), Refine, and the garment's back view when
-  there is one.
-- **Size** — "How size X sits on you": the same size and cart button beside a
-  mannequin showing how that size fits the customer's body, and a **Try on**
-  button (or **View try-on**, once a result exists).
-
-The dialog can open on **Size** before any try-on has been generated — the
-size comes from the customer's measurements, not from a render — so the size
-shown on the try-on button opens it, before and after a try-on. The ruler
+customer decides. It is one screen, **Try-on**, in three states:
+
+- **Before a try-on** — the garment (the button's `garmentUrl`) beside the
+  customer's size (when the garment has a size chart), an **Add size X to
+  cart** button (when you supply [`onAddToCart`](#onaddtocart)) and **Try on**.
+- **While it is being made** — the garment fades under a progress line,
+  "Creating your try-on…". The dialog stays open and shows the result when it
+  lands; closed meanwhile, it reopens with the result.
+- **With a result** — the render, the same size and cart button, and the
+  garment's back view when there is one.
+
+The dialog can open before any try-on has been generated — the size comes
+from the customer's measurements, not from a render — so the size shown on
+the try-on button opens it, before and after a try-on. The ruler
 shown on the button before a size exists is a way into sizing: it signs the
 customer in and takes them to their size, or to their profile when no size is
 ready yet. Neither ever starts a try-on. **Your profile** (retake the photo,
@@ -117,7 +118,7 @@ Callbacks about a specific try-on receive a trailing `info` object:
 | Field | Type | Present on | Description |
 |-------|------|-----------|-------------|
 | `buttonId` | `string` | most | The `containerId` of the button this callback is about |
-| `operation` | `'generate' \| 'refine' \| 'view'` | `onError`, `onResultShown` | Which operation this is about |
+| `operation` | `'generate' \| 'view'` | `onError`, `onResultShown` | Which operation this is about |
 | `shownInResult` | `boolean` | `onError` | `true` when the widget has already said this inside its open dialog, under the result it failed to change — so you need not say it again |
 | `view` | `string \| null` | `onGenerationSuccess`, `onResultShown` | The Render View this result is (e.g. `'front'`), when the garment offers more than one |
 | `how` | `'verified' \| 'shared' \| 'restored'` | `onSignedIn` | How this tab's session began. Only `'verified'` is a *new* sign-in — `'shared'` and `'restored'` are this tab catching up with a session that began elsewhere |
@@ -131,12 +132,9 @@ placed by guessing. Read it whenever you render results yourself.
 `info` is passed after the existing arguments, so `onGenerationSuccess(url)`
 and `onError(message)` keep working unchanged.
 
-Note that `onError` with `operation: 'refine'` also covers a refine the widget
-*declined* — only the most recently generated result can be refined, so a
-request against an older one is reported here rather than silently dropped.
-The previous result is untouched either way. A failed `refine` or `view` with
-the dialog open is already shown in it (`shownInResult: true`); with the dialog
-closed, it is yours to show if you want the customer to see it.
+A failed `view` leaves the previous result untouched. With the dialog open it
+is already shown in it (`shownInResult: true`); with the dialog closed, it is
+yours to show if you want the customer to see it.
 
 `onResultShown` receives the same `info` `onGenerationSuccess` did for that
 result, minus the image URL — it is about the same render, just reported once
@@ -167,17 +165,29 @@ address, or body measurements.
 #### `onAddToCart`
 
 The widget knows a customer's size; only you know your cart. Supply
-`onAddToCart` and the dialog draws an **Add size X to cart** button on both its
-screens. Leave it out and there is no cart control at all.
+`onAddToCart` and the dialog draws an **Add size X to cart** button under the
+customer's size. Leave it out and there is no cart control at all.
+
+When the customer is between two neighbouring sizes, the dialog says so ("Your
+size: between M and L") and lets them pick which one goes in the cart: the
+smaller for a closer fit, the larger for a looser one, with the recommended size
+preselected. The button follows their choice, and any new recommendation (edited
+measurements, another colour) resets it. Without `onAddToCart` there is nothing
+to pick for, so the dialog shows the one recommended size and says the same
+advice in words.
 
 It is called with one `intent` and must **resolve** (never reject) to an
 outcome:
 
 ```js
-onAddToCart: async ({ buttonId, size, sizeRun }) => {
-  // buttonId — the containerId of the button this is about
-  // size     — the size the customer chose, e.g. "M"
-  // sizeRun  — every size the garment's chart offers, e.g. ["S", "M", "L"]
+onAddToCart: async ({ buttonId, size, sizeRun, recommendedSize, recommendationId }) => {
+  // buttonId         — the containerId of the button this is about
+  // size             — the size to add: the customer's choice, e.g. "L"
+  // sizeRun          — every size the garment's chart offers, e.g. ["S", "M", "L"]
+  // recommendedSize  — the size the widget recommended, e.g. "M". It differs
+  //                    from `size` only when the customer picked the other of
+  //                    two neighbouring sizes
+  // recommendationId — the id of the recommendation on screen, or null
   const variant = resolveVariant(buttonId, size);
   if (!variant) return { ok: false, message: 'That size is not available in this colour.' };
   await addLineToCart(variant.id);
@@ -193,6 +203,13 @@ onAddToCart: async ({ buttonId, size, sizeRun }) => {
 | `quantity` | `ok: true` | Optional. How many of this line the cart now holds, for a repeat add |
 | `notice` | `ok: true` | Optional. A caveat when the add was adjusted on the way in (short stock, a cart limit) |
 
+`recommendedSize` and `recommendationId` are new in this release, and only
+added beside the fields you already read. A handler that reads `size` alone
+keeps working and adds what the customer chose. Keep `recommendationId` with the
+line item if you want to match a purchase to the recommendation behind it. The
+widget records each recommendation in the background and nothing waits for
+that record, so it may arrive after the add or not at all.
+
 Two rules the widget keeps for you: nothing is stated in the past tense until
 you have resolved `{ ok: true }`, and nothing reaches your handler without a
 click on the button — opening the dialog, a new result landing, and changing
@@ -213,7 +230,7 @@ It returns a handle for that button. Among its methods:
 | Method | Description |
 |--------|-------------|
 | `setGarment(garmentUrl)` | Point the button at another garment — a colour switch. The button's previous result is forgotten; a try-on still running for the previous garment is shown when it lands. |
-| `openSize()` | Open the dialog on the customer's size, exactly as the size on the button does — for a "check your size" control of your own. Does nothing while the button has no size to show. |
+| `openSize()` | Open the dialog on the customer's size, exactly as the size on the button does — for a "check your size" control of your own. Before a try-on it shows the garment, the size and **Try on**. Does nothing while the button has no size to show. |
 
 > **Removed in 0.2.0:** `targetImageId`. It named an `<img>` on your page for the
 > widget to overwrite with the result, and it is gone — the widget shows every
@@ -327,7 +344,7 @@ The widget then contacts no one but you for its fonts, and a `font-src 'self'` p
 
 Your API keys are available in your **Souldi Dashboard**. The publishable key is scoped to the domains you whitelist — it cannot be used from unauthorized origins.
 
-> **Security note:** Authentication and AI generation go through your Souldi API endpoint and are handled server-side. The browser also reaches Souldi's own storage, through short-lived signed URLs the API issues: a photo upload goes straight to it, and result images come from Souldi's image CDN. Beyond Souldi, the browser contacts unpkg (the package's CDN) for two static assets: the fonts, unless you set [`fontsUrl`](#fonts), and the 3D mannequin on the size screen. No other third-party service is contacted.
+> **Security note:** Authentication and AI generation go through your Souldi API endpoint and are handled server-side. The browser also reaches Souldi's own storage, through short-lived signed URLs the API issues: a photo upload goes straight to it, and result images come from Souldi's image CDN. Beyond Souldi, the browser contacts unpkg (the package's CDN) for its fonts, unless you set [`fontsUrl`](#fonts). No other third-party service is contacted.
 
 ---