@fluid-app/fluid-cli-theme-dev 0.1.29 → 0.1.31

package/dist/skills/themes-cart-feedback/SKILL.md

@@ -0,0 +1,452 @@
+---
+name: themes-cart-feedback
+description: |
+  Wire up shopper feedback for cart mutations in a Fluid Liquid theme, using the FairShare
+  web-widget SDK. Two surfaces: (1) the built-in feedback — a toast that confirms or reports
+  a cart add/update/remove and add-to-cart buttons that spin while the request is in flight,
+  enabled with `FairShareSDK.configureCartFeedback(...)` or `data-fluid-toast` /
+  `data-fluid-button-loading` script attributes; (2) the cart operation events —
+  `CART_OPERATION_SUCCESS` and `CART_OPERATION_ERROR` window events that fire on every cart
+  mutation regardless of toast config, so custom UI can react. Use when building or reviewing
+  anything that adds to cart or reacts to a cart change: custom product cards, shop / collection
+  grids, cart drawers and cart sections, mini-cart badges, "added to cart" confirmations, and
+  enrollment-pack join flows. Companion to `themes-review`'s FairShare `data-fluid-*` attributes
+  (those trigger the mutation; this skill handles the result). Edits are local Liquid/JS/CSS;
+  never run `fluid theme push` without explicit approval.
+---
+
+# Cart Feedback & Cart Operation Events
+
+When a shopper adds, updates, or removes a cart item on a Fluid theme, the FairShare web-widget SDK can surface the result two ways:
+
+1. **Built-in feedback** — a **toast** confirms success or reports a failure, and add-to-cart **buttons** show a spinner while the request is in flight. Opt in once; zero custom JS. This is the right default for most themes.
+2. **Cart operation events** — the SDK dispatches `CART_OPERATION_SUCCESS` and `CART_OPERATION_ERROR` on `window` for **every** mutation, whether or not the toast is enabled. Listen to these when you're building custom commerce UI that has to react — update a mini-cart badge, re-render a cart drawer, flash an inline confirmation on the specific product card, or route an enrollment flow forward.
+
+This skill is the **result** half of theme commerce. The **trigger** half — the declarative `data-fluid-add-to-cart`, `data-fluid-add-enrollment-pack`, `data-fluid-cart` attributes and the CDN `<script>` — lives in the `themes-review` skill's [FairShare attributes reference](../themes-review/references/fairshare-attributes.md). Read that first if the theme doesn't yet load the SDK or wire up add-to-cart buttons.
+
+## Which path do I need?
+
+| You want to…                                                                                     | Use                                                                 |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| Confirm every add/update/remove with a standard toast, and spin add-to-cart buttons              | **Built-in feedback** ([Part 1](#part-1--built-in-feedback))        |
+| Localize or restyle that toast, or move it to a corner                                            | **Built-in feedback** + config                                      |
+| Update a custom cart-count badge / mini-cart when the cart changes                                | **Events** ([Part 2](#part-2--cart-operation-events))               |
+| Flash an inline "Added ✓" on the exact product card the shopper clicked                           | **Events**, matched by `variantIds`                                 |
+| Re-render a hand-built cart drawer or cart section on update/remove                               | **Events**, filtered by `category`                                  |
+| Advance an enrollment-pack join flow after the pack lands (or show its error)                     | **Events**, keyed on `enrollmentPackId`                             |
+| Report a failure that the SDK would otherwise swallow (`addCartItems`, `decrementCartItem`)       | **Events** — `CART_OPERATION_ERROR` (a `try/catch` won't see it)    |
+
+Most themes want the built-in feedback for the common case **and** a small event listener or two for their custom UI. The two coexist — enabling the toast does not stop the events from firing.
+
+## Prerequisite — the SDK must be loaded
+
+Everything here depends on exactly one `<script id="fluid-cdn-script">` with `data-fluid-shop` set, loaded by `layouts/theme.liquid`:
+
+```html
+<script
+  id="fluid-cdn-script"
+  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
+  data-fluid-shop="{{ shop.handle }}"
+  defer
+></script>
+```
+
+Without it, `window.FairShareSDK` is undefined and no events fire. See the [FairShare attributes reference](../themes-review/references/fairshare-attributes.md) for the full script-tag contract. **Always guard SDK access with `window.FairShareSDK?.`** — with `defer`, the theme's own inline scripts can run before the SDK finishes initializing.
+
+---
+
+# Part 1 — Built-in feedback
+
+The built-in toast + button-loading covers the 80% case with no custom JavaScript. Turn it on once, localize the strings, optionally restyle, and you're done.
+
+## Enable it
+
+Two ways, and they merge (**precedence: `configureCartFeedback()` call > script-tag attributes > defaults**).
+
+### Runtime (recommended — lets you localize)
+
+Put this in `layouts/theme.liquid` (or a section that renders on every commerce page), inside a `DOMContentLoaded` listener so the SDK is ready and Liquid can inject translated strings:
+
+```liquid
+<script>
+  window.addEventListener("DOMContentLoaded", () => {
+    window.FairShareSDK?.configureCartFeedback({
+      toast: true,
+      buttonLoading: true,
+      position: "bottom-right",
+      messages: {
+        add: {{ 'cart.added' | t | json }},
+        update: {{ 'cart.updated' | t | json }},
+        remove: {{ 'cart.removed' | t | json }},
+        error: {{ 'cart.error' | t | json }},
+      },
+    });
+  });
+</script>
+```
+
+- The optional-chaining `?.` is required — the `defer`'d SDK may not have attached `configureCartFeedback` yet on a slow load; the guard makes a no-op instead of a `TypeError`.
+- `{{ '…' | t | json }}` runs the locale lookup **and** JSON-escapes the result, so quotes/newlines/apostrophes in a translation can't break the script. Never hand-quote a `{{ '…' | t }}` string. See [i18n](#localize-the-messages).
+
+### Script-tag attributes (no localization, quickest)
+
+Add attributes to the same `<script id="fluid-cdn-script">` tag:
+
+```html
+<script
+  id="fluid-cdn-script"
+  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
+  data-fluid-shop="{{ shop.handle }}"
+  data-fluid-toast="true"
+  data-fluid-button-loading="true"
+  data-fluid-toast-position="bottom-right"
+  defer
+></script>
+```
+
+Use this only when the theme doesn't need translated strings. Anything you can pass as a `data-fluid-toast-*` attribute you can also pass to `configureCartFeedback()`; the full attribute catalog is in [references/cart-operation-events.md](references/cart-operation-events.md).
+
+## The knobs
+
+| Key (`configureCartFeedback`) | Type      | Default          | Notes                                                                              |
+| ----------------------------- | --------- | ---------------- | ---------------------------------------------------------------------------------- |
+| `toast`                       | boolean   | `false`          | Master switch for the toast.                                                        |
+| `buttonLoading`               | boolean   | `false`          | Auto-spinner on `data-fluid-add-to-cart` / `data-fluid-add-enrollment-pack` buttons. |
+| `position`                    | string    | `bottom-center`  | `bottom-center` \| `bottom-left` \| `bottom-right` \| `top-center` \| `top-left` \| `top-right`. |
+| `duration`                    | number    | `4000`           | Auto-dismiss delay in ms.                                                           |
+| `class`                       | string    | —                | Extra CSS class on the toast, for styling.                                          |
+| `icon`                        | boolean   | `true`           | Show the variant icon.                                                             |
+| `successIcon` / `errorIcon` / `closeIcon` | string | built-ins | Emoji, text, or SVG markup.                                                         |
+| `messages`                    | object    | English defaults | `{ add, update, remove, error }` string overrides.                                 |
+
+Default messages: `add` → "Added to cart", `update` → "Cart updated", `remove` → "Removed from cart", `error` → "Something went wrong. Please try again."
+
+**Success toasts are suppressed while the cart drawer is open** (the drawer already shows the change); **error toasts always display**.
+
+## Localize the messages
+
+Drive every string through the theme's `locales/*.json` with the `t` filter, and always chain `| json`:
+
+```liquid
+messages: {
+  add: {{ 'cart.added' | t | json }},
+  update: {{ 'cart.updated' | t | json }},
+  remove: {{ 'cart.removed' | t | json }},
+  error: {{ 'cart.error' | t | json }},
+},
+```
+
+`| json` is not optional — it's what makes a French `"Ajouté à votre panier"` or an apostrophe-bearing string safe to drop into JavaScript. Add the four keys to `locales/en.json` (and every other locale the theme ships).
+
+## Button loading
+
+Two ways to spin a button while its cart request is in flight.
+
+### Declarative — for `data-fluid-*` buttons
+
+With `buttonLoading: true` (or `data-fluid-button-loading="true"`), any button carrying `data-fluid-add-to-cart` or `data-fluid-add-enrollment-pack` spins automatically. Customize the label with `data-fluid-loading-text`:
+
+```liquid
+<button
+  type="button"
+  data-fluid-add-to-cart="{{ product.first_variant.id }}"
+  data-fluid-loading-text="{{ 'product.adding' | t }}"
+>
+  {{ 'product.add_to_cart' | t }}
+</button>
+```
+
+### Programmatic — for buttons that call the SDK directly
+
+When you drive the mutation from your own JS (not via a `data-fluid-*` attribute), wrap the call so the spinner clears no matter how it resolves:
+
+```html
+<button id="custom-add" type="button">Add to cart</button>
+<script>
+  document.getElementById("custom-add")?.addEventListener("click", (e) => {
+    window.FairShareSDK?.withButtonLoading(e.currentTarget, () =>
+      window.FairShareSDK?.addCartItems(11111, { quantity: 1 }),
+    );
+  });
+</script>
+```
+
+- `withButtonLoading(el, fn)` — runs `fn`, shows the spinner, and clears it in a `finally` (so an error still stops the spin). Prefer this.
+- `setButtonLoading(el, on)` — manual toggle; idempotent, sets `aria-busy`. Use only when you can't wrap the call in a single function (then clear it in your own `finally`).
+
+The spinner inherits the button's text color, so it fits any button style with no extra CSS.
+
+## Style the toast
+
+The toast renders in **light DOM** with `id="fluid-toast"`, so plain CSS in an `assets/*.css` reaches it. Target state with the data attributes it carries — `data-variant` (`success` / `error`), `data-position`, `data-state` (`open` / `closed`) — plus any `class` you passed:
+
+```css
+#fluid-toast {
+  border-radius: var(--border_radius, 8px);
+  font-family: var(--font_family);
+  box-shadow: 0 8px 24px rgb(0 0 0 / 0.15);
+}
+#fluid-toast[data-variant="success"] {
+  background: var(--primary_color, #0f9d58);
+  color: #fff;
+}
+#fluid-toast[data-variant="error"] {
+  background: #d93025;
+  color: #fff;
+}
+```
+
+Reuse the theme's own CSS variables (`var(--primary_color)`, `var(--border_radius)`) so the toast matches the theme instead of hardcoding brand colors.
+
+## Suppress one toast without killing its event
+
+Pass `{ toast: false }` to a single mutation to skip its toast while the event still fires (handy when your custom UI already confirms that specific action):
+
+```javascript
+await window.FairShareSDK?.addCartItems(11111, { quantity: 1, toast: false });
+```
+
+---
+
+# Part 2 — Cart operation events
+
+For anything the built-in toast can't express — a live cart-count badge, a hand-built cart drawer, a per-card confirmation, an enrollment flow — listen to the two window events. **They fire on every mutation regardless of toast config.**
+
+## The two events
+
+```javascript
+window.addEventListener("CART_OPERATION_SUCCESS", (e) => {
+  // e.detail.operation, e.detail.category, e.detail.cart, …
+});
+
+window.addEventListener("CART_OPERATION_ERROR", (e) => {
+  // e.detail.operation, e.detail.category, e.detail.message, …
+});
+```
+
+The event names are **exact, uppercase, underscored** — `CART_OPERATION_SUCCESS` / `CART_OPERATION_ERROR`. `cart_operation_success`, `CartOperationSuccess`, or any other casing silently never fires.
+
+## The `detail` payload
+
+Both events carry a `CustomEvent.detail`. The fields you'll actually use:
+
+| Field              | On            | Use                                                                    |
+| ------------------ | ------------- | --------------------------------------------------------------------- |
+| `operation`        | both          | The mutation name, e.g. `"addCartItems"`.                              |
+| `category`         | both          | `"add"` \| `"update"` \| `"remove"` — the coarse bucket to switch on.  |
+| `cart`             | success only  | The resulting cart object.                                            |
+| `message`          | error only    | Best-effort human-readable error text — surface it or fall back to your own copy. |
+| `variantIds`       | when known    | `number[]` of affected variants — match a success back to a card.     |
+| `enrollmentPackId` | when known    | The pack id, on `addEnrollmentPack`.                                   |
+| `itemId`           | when known    | Cart item id for item-scoped ops.                                     |
+
+Full field list (plus `toast`, `timestamp`, `error`) is in [references/cart-operation-events.md](references/cart-operation-events.md).
+
+> **Reading the cart count:** rather than guessing the shape of `e.detail.cart`, the SDK exposes `window.FairShareSDK.getCartItemCount()` — call it from the success handler for a reliable count. Use `e.detail.cart` only for fields you've confirmed exist.
+
+## Attach the listener once
+
+Register the listener a single time, at the theme/layout level — **not** inside a section that can render more than once, or per product card. Duplicate listeners double-fire.
+
+```html
+{%- comment -%} In layouts/theme.liquid or a once-per-page section {%- endcomment -%}
+<script>
+  window.addEventListener("CART_OPERATION_SUCCESS", (e) => {
+    const badge = document.getElementById("fluid-cart-count");
+    if (badge) badge.textContent = String(window.FairShareSDK?.getCartItemCount() ?? "0");
+  });
+</script>
+```
+
+If you must attach from a section that may appear multiple times, guard against re-registering:
+
+```javascript
+if (!window.__themeCartListenerAttached) {
+  window.__themeCartListenerAttached = true;
+  window.addEventListener("CART_OPERATION_SUCCESS", handleCartChange);
+}
+```
+
+## Error handling — the swallow-vs-reject rule
+
+**This is why the error event matters.** Some mutations reject their promise on failure (you can `try/catch`); two **swallow** the failure and resolve `undefined` for backward compatibility, so a `try/catch` sees nothing:
+
+| Mutation                | On failure                        | Can `try/catch` see it? |
+| ----------------------- | --------------------------------- | ----------------------- |
+| `addCartItems`          | resolves `undefined` (swallowed)  | **No** — use the event  |
+| `decrementCartItem`     | resolves `undefined` (swallowed)  | **No** — use the event  |
+| `addEnrollmentPack`     | rethrows                          | Yes                     |
+| `updateCartItems`       | rethrows                          | Yes                     |
+| `updateCartItemVariant` | rethrows                          | Yes                     |
+| `removeCartItemById`    | rethrows                          | Yes                     |
+
+`CART_OPERATION_ERROR` fires for **all six**. So the durable rule: **surface failures from the event, not from a `try/catch`.** A `catch` block after `addCartItems` is dead code.
+
+```javascript
+window.addEventListener("CART_OPERATION_ERROR", (e) => {
+  showBanner(e.detail.message); // fires even for the swallowing mutations
+});
+```
+
+## Worked examples
+
+### A. Live cart-count badge (product cards, shop grids, navbar)
+
+The single most common need. One listener updates the count wherever the shopper adds from — a product card, a collection grid, a quick-add. Put the badge markup where you want it and the listener once in the layout:
+
+```html
+<span id="fluid-cart-count">{{ cart.item_count }}</span>
+
+<script>
+  window.addEventListener("CART_OPERATION_SUCCESS", () => {
+    const badge = document.getElementById("fluid-cart-count");
+    if (badge) badge.textContent = String(window.FairShareSDK?.getCartItemCount() ?? "0");
+  });
+</script>
+```
+
+### B. Inline "Added ✓" on the exact card clicked (`variantIds` match)
+
+When a grid of product cards shares one listener, use `variantIds` to light up only the card the shopper acted on. Reveal a **separate** confirmation element rather than overwriting the button text — the button's own label is managed by `withButtonLoading`, so leave it alone:
+
+```html
+{%- comment -%} Each card carries its variant id; a hidden confirmation sits alongside the button {%- endcomment -%}
+<div class="product-card" data-variant-id="{{ product.first_variant.id }}">
+  <button
+    type="button"
+    onclick="window.FairShareSDK?.withButtonLoading(this, () => window.FairShareSDK.addCartItems({{ product.first_variant.id }}, { quantity: 1 }))"
+  >
+    {{ 'product.add_to_cart' | t }}
+  </button>
+  <span class="added-flag" hidden>{{ 'product.added' | t }} ✓</span>
+</div>
+
+<script>
+  window.addEventListener("CART_OPERATION_SUCCESS", (e) => {
+    for (const id of e.detail.variantIds ?? []) {
+      const card = document.querySelector(`.product-card[data-variant-id="${id}"]`);
+      card?.querySelector(".added-flag")?.removeAttribute("hidden");
+    }
+  });
+</script>
+```
+
+### C. Re-render a custom cart drawer / cart section (`category` filter)
+
+A hand-built cart section refetches its own markup whenever the cart changes. Every success is an add / update / remove, so all three want a refresh — don't gate on `category` unless you're treating one differently (e.g. animating a removal):
+
+```javascript
+window.addEventListener("CART_OPERATION_SUCCESS", (e) => {
+  // e.detail.category is "add" | "update" | "remove" — switch on it only to
+  // vary the treatment; any of them changes what the cart section should show.
+  refreshCartSection(); // your fetch/re-render of the cart section
+});
+```
+
+Because success toasts self-suppress while the drawer is open, a re-rendering drawer and the toast don't fight.
+
+### D. Enrollment-pack join flow (`enrollmentPackId`)
+
+An enrollment CTA adds the pack, spins while it's in flight, then advances on success or shows the error:
+
+```html
+<button
+  type="button"
+  data-fluid-add-enrollment-pack="{{ section.settings.starter_pack.id }}"
+  data-fluid-loading-text="{{ 'enroll.joining' | t }}"
+>
+  {{ 'enroll.join_with_pack' | t }}
+</button>
+
+<script>
+  window.addEventListener("CART_OPERATION_SUCCESS", (e) => {
+    if (e.detail.operation === "addEnrollmentPack") {
+      window.location.href = "/checkout"; // or reveal the next step
+    }
+  });
+  window.addEventListener("CART_OPERATION_ERROR", (e) => {
+    if (e.detail.operation === "addEnrollmentPack") {
+      showEnrollError(e.detail.message);
+    }
+  });
+</script>
+```
+
+Combine `data-fluid-button-loading` (declarative spinner) with the events (routing) — the attribute handles the in-flight state, the event handles the outcome.
+
+---
+
+## Anti-patterns
+
+- **Rolling your own `fetch` to the cart API.** You lose the events, the toast, button loading, BFF-mode handling, and locale settings. Always go through `FairShareSDK.addCartItems` / `addEnrollmentPack` / `updateCartItems` / `removeCartItemById`, or the declarative `data-fluid-*` attributes.
+- **Wrong event-name casing.** Only `CART_OPERATION_SUCCESS` / `CART_OPERATION_ERROR` fire. `cart_operation_success`, `CartOperationSuccess`, `cartOperationSuccess` bind a listener that never runs.
+- **`try/catch` after `addCartItems` / `decrementCartItem`.** They swallow failures and resolve `undefined`; the `catch` is dead code. Listen for `CART_OPERATION_ERROR`.
+- **Registering the listener per section / per card.** Sections re-render; you'll double- or triple-fire. Attach once at layout level, or guard with a `window.__…Attached` flag.
+- **Calling `configureCartFeedback` / the SDK without `?.` or before `DOMContentLoaded`.** The `defer`'d SDK may not be ready; guard every access with `window.FairShareSDK?.`.
+- **Hardcoding toast strings.** Use `messages: { add: {{ 'cart.added' | t | json }} }`. Hand-quoting `{{ '…' | t }}` breaks on apostrophes and defeats localization.
+- **Reimplementing a button spinner.** Use `data-fluid-button-loading` or `withButtonLoading` — they set `aria-busy` and inherit the button color for free.
+- **Guessing `e.detail.cart` field names.** Use `getCartItemCount()` for the count; only read cart fields you've verified in a running theme.
+
+## Quick audit
+
+From the theme repo root:
+
+```bash
+# Wrong event-name casing (should be exact CART_OPERATION_SUCCESS / _ERROR)
+grep -rnE "addEventListener\((['\"])(cart_operation|CartOperation|cartOperation)" --include='*.liquid' --include='*.js' . 2>/dev/null
+
+# Dead try/catch around a swallowing mutation
+grep -rnE -B2 -A4 'addCartItems|decrementCartItem' --include='*.liquid' --include='*.js' . 2>/dev/null | grep -i 'catch'
+
+# SDK access without an optional-chaining guard
+grep -rnE 'window\.FairShareSDK\.' --include='*.liquid' --include='*.js' . 2>/dev/null
+
+# Hardcoded toast messages (missing | t | json)
+grep -rnE 'messages:[[:space:]]*\{' --include='*.liquid' . 2>/dev/null
+
+# Hand-rolled cart fetches that bypass the SDK
+grep -rnE "fetch\(['\"][^'\"]*cart" --include='*.liquid' --include='*.js' . 2>/dev/null
+```
+
+Each hit is a candidate finding — confirm in context before flagging.
+
+## Checklist
+
+**SDK & setup**
+
+- [ ] Exactly one `<script id="fluid-cdn-script">` with `data-fluid-shop` set (see `themes-review` FairShare reference)
+- [ ] Every `FairShareSDK` access is guarded with `?.` and runs on/after `DOMContentLoaded`
+
+**Built-in feedback (Part 1)**
+
+- [ ] `configureCartFeedback({ toast, buttonLoading, … })` called once, in a `DOMContentLoaded` listener
+- [ ] `messages` sourced from `locales/*.json` via `{{ 'key' | t | json }}` (never hand-quoted)
+- [ ] The four message keys (`cart.added` / `cart.updated` / `cart.removed` / `cart.error`) exist in every locale file
+- [ ] Toast styled through `#fluid-toast` + `data-variant`, reusing theme CSS variables (not hardcoded brand colors)
+- [ ] Button spinners use `data-fluid-button-loading` or `withButtonLoading` (no hand-rolled spinner)
+
+**Events (Part 2)**
+
+- [ ] Event names are exactly `CART_OPERATION_SUCCESS` / `CART_OPERATION_ERROR`
+- [ ] Listener attached once (layout level or guarded), never per-section / per-card
+- [ ] Failures surfaced from `CART_OPERATION_ERROR`, not a `try/catch` (mandatory for `addCartItems` / `decrementCartItem`)
+- [ ] Per-card / per-item reactions matched via `variantIds` / `itemId`; enrollment via `enrollmentPackId`
+- [ ] Cart count read via `getCartItemCount()`, not a guessed `e.detail.cart` field
+
+**Correctness**
+
+- [ ] Cart mutations go through the SDK (or `data-fluid-*`), never a hand-rolled `fetch`
+- [ ] Verified in a running theme with `fluid theme dev` (lint does not check runtime JS — see below)
+
+---
+
+## Boundaries — local edits, lint, never push
+
+- Everything here is a **local file edit** — Liquid, JS, and CSS in the theme repo. This skill never runs `fluid theme push`, never calls the API, and never writes to the live theme **without explicit approval**.
+- Run `fluid theme lint --json` after schema-adjacent edits and parse the JSON, as with any theme change. **But note:** the linter validates `{% schema %}` and section references only — it does **not** execute or check the JavaScript, the event wiring, or the toast config. The real check for this skill is **`fluid theme dev`**: open the storefront, add/update/remove an item, and watch the toast, the spinner, the badge, and (via the console) the events actually fire.
+- When reviewing a PR rather than authoring, follow the `themes-review` workflow — inline `file:line` findings with a `blocker` / `should` / `nit` severity, and don't push to the author's branch.
+
+## Reference
+
+- **[references/cart-operation-events.md](references/cart-operation-events.md)** — the complete catalogs: every mutation's success/failure behavior, the full `detail` field list, the full `configureCartFeedback` config keys, every `data-fluid-toast-*` script attribute, and the toast styling hooks. Read it when you need an exhaustive lookup rather than the common-case guidance above.
+- **[themes-review FairShare attributes](../themes-review/references/fairshare-attributes.md)** — the declarative `data-fluid-*` attributes that *trigger* cart mutations, and the CDN script contract. The trigger half of this skill's result half.

package/dist/skills/themes-cart-feedback/references/cart-operation-events.md

@@ -0,0 +1,209 @@
+# Cart operation events & feedback — full reference
+
+> Part of the `themes-cart-feedback` skill. See [`../SKILL.md`](../SKILL.md) for the authoring workflow, decision table, and worked examples. This file is the exhaustive lookup: mutation behavior, the complete `detail` payload, every config key and script attribute, and the toast styling hooks.
+
+## Contents
+
+- The two events
+- Mutations that emit events (success/failure behavior)
+- Event `detail` — complete field list
+- `configureCartFeedback()` — complete config keys
+- Script-tag `data-fluid-*` attributes — complete list
+- Precedence & merging
+- Toast styling hooks
+- Button-loading APIs
+- Per-call toast suppression
+
+---
+
+## The two events
+
+The SDK dispatches two uniform `window` `CustomEvent`s for **all** cart mutations:
+
+- **`CART_OPERATION_SUCCESS`** — fires when a mutation completes successfully.
+- **`CART_OPERATION_ERROR`** — fires when a mutation fails.
+
+Both fire **regardless of toast configuration** — enabling or disabling the built-in toast has no effect on the events. Names are exact, uppercase, underscore-separated; any other casing binds a listener that never runs.
+
+```javascript
+window.addEventListener("CART_OPERATION_SUCCESS", (e) => {
+  console.log(e.detail.operation, "succeeded", e.detail.cart);
+});
+
+window.addEventListener("CART_OPERATION_ERROR", (e) => {
+  console.log(e.detail.operation, "failed:", e.detail.message);
+});
+```
+
+## Mutations that emit events
+
+Every cart mutation dispatches one of the two events. The **failure column matters**: two mutations swallow the failure (resolve `undefined`) for backward compatibility, so a `try/catch` around them sees nothing — the error surfaces **only** through `CART_OPERATION_ERROR`. The other four rethrow, so you can `try/catch` *or* use the event.
+
+| Function                | Category | On success               | On failure                                            |
+| ----------------------- | -------- | ------------------------ | ----------------------------------------------------- |
+| `addCartItems`          | add      | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **resolves `undefined`** (swallowed) |
+| `addEnrollmentPack`     | add      | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **rethrows**                 |
+| `updateCartItems`       | update   | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **rethrows**                 |
+| `decrementCartItem`     | update   | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **resolves `undefined`** (swallowed) |
+| `updateCartItemVariant` | update   | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **rethrows**                 |
+| `removeCartItemById`    | remove   | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **rethrows**                 |
+
+**Rule:** to report a cart failure to the shopper, listen for `CART_OPERATION_ERROR`. It covers all six functions; a `try/catch` covers only the four that rethrow.
+
+## Event `detail` — complete field list
+
+Both events expose an identical `detail` object structure. Fields marked "when known" are present only when the SDK has that value for the operation.
+
+| Field              | Type                            | Presence     | Purpose                                            |
+| ------------------ | ------------------------------- | ------------ | -------------------------------------------------- |
+| `operation`        | `string`                        | always       | Function name, e.g. `"addCartItems"`.              |
+| `category`         | `"add" \| "update" \| "remove"` | always       | Coarse operation bucket.                           |
+| `toast`            | `boolean`                       | always       | `false` if the call passed `{ toast: false }`.     |
+| `timestamp`        | `string`                        | always       | ISO 8601 timestamp.                                |
+| `cart`             | `Cart`                          | success only | The resulting cart object.                         |
+| `error`            | `unknown`                       | error only   | The raw thrown value.                              |
+| `message`          | `string`                        | error only   | Best-effort human-readable error text.             |
+| `variantIds`       | `number[]`                      | when known   | Variant ids affected.                              |
+| `itemId`           | `number`                        | when known   | Cart item id (item-scoped ops).                    |
+| `enrollmentPackId` | `number`                        | when known   | Enrollment pack id (`addEnrollmentPack`).          |
+
+> Prefer `window.FairShareSDK.getCartItemCount()` over reading a count out of `e.detail.cart` — the count getter is a stable, documented API, whereas the `cart` object's shape is not enumerated here. Read `e.detail.cart` fields only after confirming them in a running theme.
+
+## `configureCartFeedback()` — complete config keys
+
+```javascript
+window.addEventListener("DOMContentLoaded", () => {
+  window.FairShareSDK?.configureCartFeedback({
+    toast: true,
+    buttonLoading: true,
+    position: "bottom-right",
+    class: "theme-toast",
+    duration: 5000,
+    icon: true,
+    successIcon: "✓",
+    errorIcon: "⚠",
+    closeIcon: "✕",
+    messages: {
+      add: "Added! 🎉",
+      update: "Cart updated",
+      remove: "Removed from cart",
+      error: "Couldn't add that — try again.",
+    },
+  });
+});
+```
+
+All keys optional.
+
+| Key             | Type      | Default          | Notes                                                                                              |
+| --------------- | --------- | ---------------- | -------------------------------------------------------------------------------------------------- |
+| `toast`         | boolean   | `false`          | Enable the built-in toast.                                                                          |
+| `buttonLoading` | boolean   | `false`          | Auto-spinner on `data-fluid-add-to-cart` / `data-fluid-add-enrollment-pack` buttons.               |
+| `position`      | string    | `bottom-center`  | `bottom-center` \| `bottom-left` \| `bottom-right` \| `top-center` \| `top-left` \| `top-right`.   |
+| `class`         | string    | —                | Extra CSS class on the toast element.                                                              |
+| `duration`      | number    | `4000`           | Auto-dismiss delay (ms).                                                                            |
+| `icon`          | boolean   | `true`           | Show the variant icon.                                                                             |
+| `successIcon`   | string    | built-in         | Emoji, text, or SVG markup for the success variant.                                                |
+| `errorIcon`     | string    | built-in         | Emoji, text, or SVG markup for the error variant.                                                  |
+| `closeIcon`     | string    | `✕`              | Close-button glyph.                                                                                |
+| `messages`      | object    | English defaults | `{ add, update, remove, error }`. Default: "Added to cart" / "Cart updated" / "Removed from cart" / "Something went wrong. Please try again." |
+
+## Script-tag `data-fluid-*` attributes — complete list
+
+Set on the `<script id="fluid-cdn-script">` tag. Use these when no localization is needed; otherwise prefer `configureCartFeedback()` so Liquid can inject translated strings.
+
+| Attribute                        | Maps to                    | Notes                                                    |
+| -------------------------------- | -------------------------- | -------------------------------------------------------- |
+| `data-fluid-toast`               | `toast`                    | `"true"` to enable.                                      |
+| `data-fluid-button-loading`      | `buttonLoading`            | `"true"` to enable.                                      |
+| `data-fluid-toast-class`         | `class`                    | Custom class name.                                       |
+| `data-fluid-toast-position`      | `position`                 | Same six values as `position` (default `bottom-center`). |
+| `data-fluid-toast-duration`      | `duration`                 | Milliseconds (default `4000`).                          |
+| `data-fluid-toast-icon`          | `icon`                     | `"false"` to hide the icon.                             |
+| `data-fluid-toast-success-icon`  | `successIcon`              | Custom success icon.                                    |
+| `data-fluid-toast-error-icon`    | `errorIcon`                | Custom error icon.                                      |
+| `data-fluid-toast-close-icon`    | `closeIcon`                | Custom close glyph (default `✕`).                       |
+| `data-fluid-toast-msg-add`       | `messages.add`             | Default "Added to cart".                                |
+| `data-fluid-toast-msg-update`    | `messages.update`          | Default "Cart updated".                                 |
+| `data-fluid-toast-msg-remove`    | `messages.remove`          | Default "Removed from cart".                            |
+| `data-fluid-toast-msg-error`     | `messages.error`           | Default "Something went wrong. Please try again."       |
+
+Example:
+
+```html
+<script
+  id="fluid-cdn-script"
+  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
+  data-fluid-shop="your-shop-id"
+  data-fluid-toast="true"
+  data-fluid-toast-position="bottom-right"
+  data-fluid-toast-duration="4000"
+  data-fluid-toast-msg-add="Added! 🎉"
+  defer
+></script>
+```
+
+## Precedence & merging
+
+When both are present, they merge per key: **`configureCartFeedback()` call > `data-fluid-*` attributes > defaults.** So you can set the base config on the script tag and override just the localized strings at runtime.
+
+## Toast styling hooks
+
+The toast renders in **light DOM** (no shadow root), so plain theme CSS reaches it. It carries:
+
+- `id="fluid-toast"` — the always-present selector hook.
+- any `class` you passed via `class:` / `data-fluid-toast-class`.
+- `data-variant` — `"success"` or `"error"`.
+- `data-position` — the configured position value.
+- `data-state` — `"open"` or `"closed"`.
+
+```css
+#fluid-toast {
+  border-radius: var(--border_radius, 8px);
+  font-family: var(--font_family);
+  box-shadow: 0 8px 24px rgb(0 0 0 / 0.15);
+}
+#fluid-toast[data-variant="success"] { background: var(--primary_color, #0f9d58); color: #fff; }
+#fluid-toast[data-variant="error"]   { background: #d93025; color: #fff; }
+```
+
+**Behavior:** success toasts are suppressed while the cart drawer is open (the drawer already reflects the change); error toasts always display.
+
+## Button-loading APIs
+
+| API                        | Behavior                                                                                          |
+| -------------------------- | ------------------------------------------------------------------------------------------------ |
+| `data-fluid-button-loading="true"` (script attr) / `buttonLoading: true` (config) | Global opt-in. Buttons with `data-fluid-add-to-cart` or `data-fluid-add-enrollment-pack` auto-spin. |
+| `data-fluid-loading-text`  | Per-button label shown while loading.                                                            |
+| `withButtonLoading(el, fn)`| Runs `fn` with the spinner shown; clears it in a `finally`. **Preferred** for custom mutations.  |
+| `setButtonLoading(el, on)` | Manual toggle; idempotent; sets `aria-busy`. Clear it yourself in a `finally`.                   |
+
+The spinner inherits the button's text color, so it needs no per-theme CSS.
+
+```javascript
+// Automated cleanup (preferred)
+button.addEventListener("click", (e) => {
+  window.FairShareSDK?.withButtonLoading(e.currentTarget, () =>
+    window.FairShareSDK.addCartItems(11111, { quantity: 1 }),
+  );
+});
+
+// Manual control
+button.addEventListener("click", async (e) => {
+  const btn = e.currentTarget;
+  window.FairShareSDK?.setButtonLoading(btn, true);
+  try {
+    await window.FairShareSDK?.addCartItems(11111, { quantity: 1 });
+  } finally {
+    window.FairShareSDK?.setButtonLoading(btn, false);
+  }
+});
+```
+
+## Per-call toast suppression
+
+Pass `{ toast: false }` to a single mutation to suppress just that toast. The event **still fires** (with `detail.toast === false`); only the toast is skipped.
+
+```javascript
+await window.FairShareSDK?.addCartItems(11111, { quantity: 1, toast: false });
+```