@souldi/try-on 0.4.5 → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# 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.
+
+## 0.5.0
+
+**Breaking.** `init({ appearance })` replaces the `theme` option.
+
+- **New: `appearance`.** `init({ appearance: { ink, fill, corners, font } })` styles the try-on button, the result dialog and the sign-in and upload screens. It is the same closed set of values a Shopify merchant sets on the Souldi block. Missing or unknown values fall back to the defaults, one by one, and never throw. See [Appearance](README.md#appearance).
+- **Removed: `theme`.** Its properties (`mode`, `accentColor`, `accentTextColor`, `borderRadius`, `fontFamily`, `headingFontFamily`, `buttonOutlineColor`) are gone, not deprecated. A `theme` that is still passed is ignored and logs one console warning.
+- **Removed: dark mode.** The widget is light-only, like its result dialog. An embedder who passed `theme: { mode: 'dark' }` now gets the light sign-in and upload screens.
+- **Contrast is reported, never corrected.** The `ink` is used as given. If it is below 4.5:1 against white, the widget logs one console warning.
+
+**CDN embedders get this on the day it is published.** The README's script tag, `https://unpkg.com/@souldi/try-on/dist/widget.umd.js`, names no version, so it serves the newest release. To stay on 0.4 while you move from `theme` to `appearance`, pin the version in the URL (`https://unpkg.com/@souldi/try-on@0.4/dist/widget.umd.js`) or in your `package.json`.

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,
@@ -97,7 +98,7 @@ Call once per page load to configure the widget.
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `tenantApiKey` | `string` | Yes | Your publishable API key (from your Souldi dashboard) |
-| `theme` | `object` | No | Customize the widget appearance ([see Theming](#theming)) |
+| `appearance` | `object` | No | How the widget looks: ink, fill, corners and font ([see Appearance](#appearance)) |
 | `fontsUrl` | `string` | No | Where you serve the package's `dist/fonts` directory, to load the fonts from your own origin instead of unpkg ([see Fonts](#fonts)) |
 | `declareFonts` | `boolean` | No | Default `true`: the widget declares its fonts in your page ([see Fonts](#fonts)). Pass `false` only if your page already declares them |
 | `onGenerationStart` | `function(info)` | No | Called when AI generation begins |
@@ -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
@@ -213,7 +211,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
@@ -222,51 +220,40 @@ It returns a handle for that button. Among its methods:
 
 ---
 
-## Theming
+## Appearance
 
-The widget ships with **dark** and **light** themes and supports deep customization to match your store's brand.
-
-### Theme Modes
+One **appearance** styles the whole widget: the try-on button, the result dialog, and the sign-in and upload screens. It is the same closed set of choices a Shopify merchant makes on the Souldi block, so every embed has one appearance contract.
 
 ```javascript
 VirtualTryOn.init({
   tenantApiKey: 'your_key',
-  theme: {
-    mode: 'light',  // 'dark' (default) or 'light'
+  appearance: {
+    ink: '#7A1F5C',      // your brand colour, as six hex digits
+    fill: 'filled',      // 'outlined' (default) or 'filled'
+    corners: 'rounded',  // 'square' (default), 'rounded' or 'pill'
+    font: 'theme',       // 'souldi' (default) or 'theme'
   },
 });
 ```
 
-### Custom Brand Colors
+| Property | Values | Default | What it does |
+|----------|--------|---------|--------------|
+| `ink` | `#rrggbb` | `#1F201F` | Colours the accents only: the primary action, selected states, the size stamp and focus rings. Never body text. |
+| `fill` | `'outlined'` \| `'filled'` | `'outlined'` | The primary action is the ink on white (outlined) or white on the ink (filled). Secondary actions stay outlined. |
+| `corners` | `'square'` \| `'rounded'` \| `'pill'` | `'square'` | Buttons take the shape as chosen. Cards and sheets cap it (0, 12px and 20px), so a dialog never turns into an oval. |
+| `font` | `'souldi'` \| `'theme'` | `'souldi'` | The widget's own faces ([see Fonts](#fonts)), or your page's font, inherited everywhere, headings included. |
 
-Override individual properties to match your brand:
+Each value is checked on its own. A missing or unknown value falls back to its default and never throws, so a typo can't break your page. An `ink` that isn't six hex digits (`#FFF`, `red`) falls back to the default ink.
 
-```javascript
-VirtualTryOn.init({
-  tenantApiKey: 'your_key',
-  theme: {
-    mode: 'dark',
-    accentColor: '#7C3AED',          // Primary button & accent color
-    accentTextColor: '#FFFFFF',       // Text color on accent buttons
-    borderRadius: '8px',             // Border radius for cards & modals
-    fontFamily: '"Inter", sans-serif',
-    headingFontFamily: '"Playfair Display", serif',
-    buttonOutlineColor: '#7C3AED',   // Outline on the split button
-  },
-});
-```
+**Pick an ink that reads on white.** The ink is used exactly as you give it. If it is below 4.5:1 contrast against white (the WCAG AA minimum for text), the widget logs one console warning and still uses it. It doesn't darken the colour for you.
 
-### Available Theme Options
+There is no `size` option. One that is passed is ignored.
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `mode` | `'dark' \| 'light'` | `'dark'` | Base color palette |
-| `accentColor` | CSS color | `#5e8b5c` (dark) / `#1F201F` (light) | Primary action color on the sign-in and upload screens |
-| `accentTextColor` | CSS color | `#193620` (dark) / `#FFFFFF` (light) | Text on accent buttons |
-| `borderRadius` | CSS value | `0` (square) | Corner rounding for buttons; cards take about 1.7× it |
-| `fontFamily` | CSS font stack | `'Souldi Manrope', system-ui, sans-serif` | Body text font |
-| `headingFontFamily` | CSS font stack | `'Souldi Newsreader', serif` | Heading font |
-| `buttonOutlineColor` | CSS color | `transparent` | Border color on the try-on button |
+> **Removed in 0.5.0:** `theme` (`mode`, `accentColor`, `accentTextColor`,
+> `borderRadius`, `fontFamily`, `headingFontFamily`, `buttonOutlineColor`) and
+> the dark mode it selected. The widget is light-only. A `theme` that is still
+> passed is ignored and logs one console warning. Move to `appearance`. See the
+> [changelog](CHANGELOG.md).
 
 All UI is rendered inside a **Shadow DOM**, so your site's CSS will never leak into the widget and the widget will never break your styles.
 
@@ -309,7 +296,7 @@ The widget then contacts no one but you for its fonts, and a `font-src 'self'` p
   <script>
     VirtualTryOn.init({
       tenantApiKey: 'pk_live_abc123',
-      theme: { mode: 'light', accentColor: '#2563EB' },
+      appearance: { ink: '#2563EB', corners: 'rounded' },
       onGenerationSuccess: (url) => {
         console.log('Try-on result:', url);
       },
@@ -338,7 +325,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.
 
 ---