@fluid-app/fluid-cli-theme-dev 0.1.244 → 0.1.245

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.
@@ -32,7 +32,7 @@ This skill is the **result** half of theme commerce. The **trigger** half — th
32
32
  | Localize or restyle that toast, or move it to a corner | **Built-in feedback** + config |
33
33
  | Update a custom cart-count badge / mini-cart when the cart changes | **Events** ([Part 2](#part-2--cart-operation-events)) |
34
34
  | Flash an inline "Added ✓" on the exact product card the shopper clicked | **Events**, matched by `variantIds` |
35
- | Re-render a hand-built cart drawer or cart section on update/remove | **Events**, filtered by `category` |
35
+ | Draw a hand-built cart drawer, including the line of an add that is still filling | **Events** + [custom drawer recipe](#custom-buttons-and-drawers-async-carts) (`getPendingCartItems` + `onCartChange`) |
36
36
  | Advance an enrollment-pack join flow after the pack lands (or show its error) | **Events**, keyed on `enrollmentPackId` |
37
37
  | Report a failure that the SDK would otherwise swallow (`addCartItems`, `decrementCartItem`) | **Events** — `CART_OPERATION_ERROR` (a `try/catch` won't see it) |
38
38
 
@@ -164,6 +164,8 @@ When you drive the mutation from your own JS (not via a `data-fluid-*` attribute
164
164
  <button id="custom-add" type="button">Add to cart</button>
165
165
  <script>
166
166
  document.getElementById("custom-add")?.addEventListener("click", (e) => {
167
+ // Show the SDK cart drawer at the click, before the add resolves.
168
+ window.FairShareSDK?.cart.control.open();
167
169
  window.FairShareSDK?.withButtonLoading(e.currentTarget, () =>
168
170
  window.FairShareSDK?.addCartItems(11111, { quantity: 1 }),
169
171
  );
@@ -173,6 +175,7 @@ When you drive the mutation from your own JS (not via a `data-fluid-*` attribute
173
175
 
174
176
  - `withButtonLoading(el, fn)` — runs `fn`, shows the spinner, and clears it in a `finally` (so an error still stops the spin). Prefer this.
175
177
  - `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`).
178
+ - Call `FairShareSDK.cart.control.open()` at the click when this button should show the SDK drawer. Declarative `data-fluid-add-to-cart` buttons open it at the click for you; a direct `addCartItems` call does not.
176
179
 
177
180
  The spinner inherits the button's text color, so it fits any button style with no extra CSS.
178
181
 
@@ -242,7 +245,7 @@ Both events carry a `CustomEvent.detail`. The fields you'll actually use:
242
245
 
243
246
  Full field list (plus `toast`, `timestamp`, `error`) is in [references/cart-operation-events.md](references/cart-operation-events.md).
244
247
 
245
- > **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.
248
+ > **Reading the cart count:** the SDK keeps every `id="fluid-cart-count"` element in sync by itself (worked example A), so a badge needs no handler. `getCartItemCount()` counts only the stored cart's items, so it is `0` while a new cart is still filling and ignores lines still pending; in your own handler call it only after `await window.FairShareSDK.whenCartSettled()`, or redraw from `onCartChange`. Use `e.detail.cart` only for fields you've confirmed exist.
246
249
 
247
250
  ## Attach the listener once
248
251
 
@@ -251,8 +254,10 @@ Register the listener a single time, at the theme/layout level — **not** insid
251
254
  ```html
252
255
  {%- comment -%} In layouts/theme.liquid or a once-per-page section {%- endcomment -%}
253
256
  <script>
254
- window.addEventListener("CART_OPERATION_SUCCESS", (e) => {
255
- const badge = document.getElementById("fluid-cart-count");
257
+ window.addEventListener("CART_OPERATION_SUCCESS", async (e) => {
258
+ // A new cart can still be filling: wait before reading the stored cart.
259
+ await window.FairShareSDK?.whenCartSettled();
260
+ const badge = document.getElementById("my-cart-badge"); // not #fluid-cart-count: the SDK fills that one
256
261
  if (badge) badge.textContent = String(window.FairShareSDK?.getCartItemCount() ?? "0");
257
262
  });
258
263
  </script>
@@ -269,13 +274,13 @@ if (!window.__themeCartListenerAttached) {
269
274
 
270
275
  ## Error handling — the swallow-vs-reject rule
271
276
 
272
- **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:
277
+ **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. On success `addCartItems` resolves with the filled cart (see [the resolve value](#custom-buttons-and-drawers-async-carts)), so `undefined` always means the add, or the cart fill, failed:
273
278
 
274
279
  | Mutation | On failure | Can `try/catch` see it? |
275
280
  | ----------------------- | --------------------------------- | ----------------------- |
276
281
  | `addCartItems` | resolves `undefined` (swallowed) | **No** — use the event |
277
282
  | `decrementCartItem` | resolves `undefined` (swallowed) | **No** — use the event |
278
- | `addEnrollmentPack` | rethrows | Yes |
283
+ | `addEnrollmentPack` | rethrows (`undefined` if the cart fill fails) | Yes (the fill failure: use the event) |
279
284
  | `updateCartItems` | rethrows | Yes |
280
285
  | `updateCartItemVariant` | rethrows | Yes |
281
286
  | `removeCartItemById` | rethrows | Yes |
@@ -288,6 +293,26 @@ window.addEventListener("CART_OPERATION_ERROR", (e) => {
288
293
  });
289
294
  ```
290
295
 
296
+ ## Custom buttons and drawers (async carts)
297
+
298
+ Every Fluid storefront creates carts in the background. A new cart comes back empty with `population_status: "pending"` and fills over the realtime channel (`complete` or `failed`), usually within a few hundred ms to about 2 s. Theme code that adds to the cart or draws its own cart must allow for that. Full reference: [Carts that fill in the background](https://docs.fluid.app/sdk/cart-api#carts-that-fill-in-the-background) and [Custom cart drawers](https://docs.fluid.app/themes/custom-cart-drawer).
299
+
300
+ **The resolve value.** `addCartItems`, `addEnrollmentPack` and `setEnrollment` wait (at most 10 s) for the fill and resolve with the FILLED cart. When the add or the fill fails they resolve `undefined` and `CART_POPULATION_FAILED` fires for a failed fill. `getCart()` and `refreshCart()` also wait while the cart fills. `await window.FairShareSDK.whenCartSettled()` waits explicitly; call it before reading `getLocalCart()` right after an add.
301
+
302
+ **Events around an add.** `CART_ITEMS_ADDING` fires synchronously before any request, with the lines being added (`detail.lines`). `CART_ITEMS_SETTLED` fires when the add ends (`detail.outcome` is `"success"` or `"error"`). Its `detail.cart` can be a cart that is still filling, so read items from it only when `population_status` is `"complete"`.
303
+
304
+ **Open the drawer at the click.** A declarative `data-fluid-add-to-cart` or `data-fluid-add-enrollment-pack` button opens the SDK drawer at the click with an optimistic line. A theme that calls `addCartItems` itself and wants the SDK drawer calls `window.FairShareSDK.cart.control.open()` at the click, before it awaits the add.
305
+
306
+ **Never use `createCart()` to read data.** `FairShareSDK.createCart()` always creates a NEW empty cart and replaces the shopper's cart token. To read the country or language use `getCountryCode()` / `getLanguage()`; to read the cart use `getLocalCart()`.
307
+
308
+ **Custom drawer recipe.** A hand-built drawer (not the Fluid cart widget) draws the stored cart plus the lines of adds the server has not answered yet:
309
+
310
+ 1. Open the drawer at the click, or on the `CART_ITEMS_ADDING` window event. On an SDK button set `data-fluid-open-cart-after-add="false"` so the SDK drawer does not open as well.
311
+ 2. Render once with `getLocalCart()` and `getPendingCartItems()`; the `onCartChange` handler is not called on subscribe.
312
+ 3. Subscribe with `onCartChange(({ cart, pendingItems }) => render(cart, pendingItems))` and redraw on every call. It fires when an add starts or settles, when a cart body arrives, when a fill fails and when a pending item expires.
313
+ 4. Draw `pendingItems` after `cart.items`. Show totals as pending while `pendingItems.length > 0`.
314
+ 5. `await window.FairShareSDK.waitForCheckoutReady()` before you send the shopper to checkout yourself; `checkout()` already waits.
315
+
291
316
  ## Worked examples
292
317
 
293
318
  ### A. Live cart-count badge (product cards, shop grids, navbar)
@@ -298,18 +323,19 @@ The single most common need, and it needs no JavaScript. The SDK keeps the text
298
323
  <span id="fluid-cart-count">0</span>
299
324
  ```
300
325
 
301
- Do not seed it with `{{ cart.item_count }}`: `cart` exists only in `cart_page` templates, so everywhere else it renders empty until the SDK fills it. To drive a different element, listen for the cart state events (`UPDATE_CART_ITEM`, `ADD_TO_CART`, `REMOVE_FROM_CART`) and read `window.FairShareSDK.getCartItemCount()`.
326
+ Do not seed it with `{{ cart.item_count }}`: `cart` exists only in `cart_page` templates, so everywhere else it renders empty until the SDK fills it. To drive a different element, subscribe with `window.FairShareSDK.onCartChange(...)` and count `cart.items` yourself. `getCartItemCount()` counts only the stored cart's items (`0` while a new cart is still filling), so call it only after `await window.FairShareSDK.whenCartSettled()`.
302
327
 
303
328
  ### B. Inline "Added ✓" on the exact card clicked (`variantIds` match)
304
329
 
305
- 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:
330
+ When a grid of product cards shares one listener, use `variantIds` to light up only the card the shopper acted on. Use the declarative button (it spins on its own and needs no inline JavaScript), and reveal a **separate** confirmation element rather than overwriting the button text. `data-fluid-open-cart-after-add="false"` keeps the cart drawer closed so the flag is the confirmation:
306
331
 
307
332
  ```html
308
333
  {%- comment -%} Each card carries its variant id; a hidden confirmation sits alongside the button {%- endcomment -%}
309
334
  <div class="product-card" data-variant-id="{{ product.selected_or_first_available_variant.id }}">
310
335
  <button
311
336
  type="button"
312
- onclick="window.FairShareSDK?.withButtonLoading(this, () => window.FairShareSDK.addCartItems({{ product.selected_or_first_available_variant.id }}, { quantity: 1 }))"
337
+ data-fluid-add-to-cart="{{ product.selected_or_first_available_variant.id }}"
338
+ data-fluid-open-cart-after-add="false"
313
339
  >
314
340
  {{ 'product.add_to_cart' | t }}
315
341
  </button>
@@ -326,19 +352,52 @@ When a grid of product cards shares one listener, use `variantIds` to light up o
326
352
  </script>
327
353
  ```
328
354
 
329
- ### C. Re-render a custom cart drawer / cart section (`category` filter)
355
+ ### C. Draw a custom cart drawer (`getPendingCartItems` + `onCartChange`)
330
356
 
331
- 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):
357
+ A hand-built drawer must show an added line at the click, even when the add creates the cart and the server's cart is still empty. Do not wait for `CART_OPERATION_SUCCESS` to open or redraw it. Draw the stored cart, then the pending items on top, and redraw on every `onCartChange`:
332
358
 
333
- ```javascript
334
- window.addEventListener("CART_OPERATION_SUCCESS", (e) => {
335
- // e.detail.category is "add" | "update" | "remove" — switch on it only to
336
- // vary the treatment; any of them changes what the cart section should show.
337
- refreshCartSection(); // your fetch/re-render of the cart section
338
- });
359
+ ```html
360
+ <button data-fluid-add-to-cart="22190" data-fluid-open-cart-after-add="false">Add</button>
361
+ <aside id="my-cart" hidden>
362
+ <ul id="my-cart-lines"></ul>
363
+ <p id="my-cart-total"></p>
364
+ </aside>
365
+ <script>
366
+ window.addEventListener("DOMContentLoaded", () => {
367
+ const sdk = window.FairShareSDK;
368
+ if (!sdk) return;
369
+ const drawer = document.getElementById("my-cart");
370
+ const list = document.getElementById("my-cart-lines");
371
+ const total = document.getElementById("my-cart-total");
372
+
373
+ function render({ cart, pendingItems }) {
374
+ // Simplified: matches a line on its variant only. Subscription and bundle
375
+ // lines need the matching rules in the SDK README ("Custom cart drawers").
376
+ const rows = (cart?.items ?? []).map((item) => ({
377
+ variantId: item.variant?.id,
378
+ quantity: item.quantity,
379
+ title: item.product_title,
380
+ }));
381
+ for (const p of pendingItems) {
382
+ const row = rows.find((r) => r.variantId === p.variant_id);
383
+ if (row) row.quantity = p.listedQuantity + p.quantity;
384
+ else rows.push({ variantId: p.variant_id, quantity: p.quantity, title: p.preview?.product_title ?? "Adding…" });
385
+ }
386
+ list.replaceChildren(
387
+ ...rows.map((r) => Object.assign(document.createElement("li"), { textContent: `${r.quantity} x ${r.title}` })),
388
+ );
389
+ // cart.sub_total_in_currency does not count the pending lines yet.
390
+ total.textContent = pendingItems.length ? "…" : (cart?.sub_total_in_currency ?? "");
391
+ }
392
+
393
+ window.addEventListener("CART_ITEMS_ADDING", () => { drawer.hidden = false; }); // before any request
394
+ sdk.onCartChange(render);
395
+ render({ cart: sdk.getLocalCart(), pendingItems: sdk.getPendingCartItems() }); // not called on subscribe
396
+ });
397
+ </script>
339
398
  ```
340
399
 
341
- Because success toasts self-suppress while the drawer is open, a re-rendering drawer and the toast don't fight.
400
+ Send the shopper to checkout with `await sdk.waitForCheckoutReady(); sdk.checkout();`, or call `checkout()` alone, which waits too.
342
401
 
343
402
  ### D. Enrollment-pack join flow (`enrollmentPackId`)
344
403
 
@@ -380,7 +439,11 @@ The declarative button handles its in-flight state automatically; the events han
380
439
  - **Calling `configureCartFeedback` / the SDK without `?.` or before `DOMContentLoaded`.** The `defer`'d SDK may not be ready; guard every access with `window.FairShareSDK?.`.
381
440
  - **Hardcoding toast strings.** Use `messages: { add: {{ 'cart.added' | t | json }} }`. Hand-quoting `{{ '…' | t }}` breaks on apostrophes and defeats localization.
382
441
  - **Reimplementing a button spinner.** Declarative `data-fluid-*` buttons spin automatically; use `withButtonLoading` for direct SDK calls. Both set `aria-busy` and inherit the button color.
383
- - **Guessing `e.detail.cart` field names.** Use `getCartItemCount()` for the count; only read cart fields you've verified in a running theme.
442
+ - **Guessing `e.detail.cart` field names.** Use the SDK-synced `#fluid-cart-count` for a badge, or `getCartItemCount()` after `whenCartSettled()`; only read cart fields you've verified in a running theme.
443
+ - **Calling `createCart()` to read data.** It always creates a NEW empty cart and replaces the shopper's cart token. Use `getCountryCode()`, `getLanguage()` or `getLocalCart()`.
444
+ - **A custom `addCartItems` button that never opens the drawer at the click.** Call `FairShareSDK.cart.control.open()` at the click, before awaiting the add; otherwise the shopper sees nothing until the cart fills.
445
+ - **Redrawing a hand-built drawer only on `CART_OPERATION_SUCCESS`.** It arrives after the fill, so a new cart shows empty first. Use `getPendingCartItems()` + `onCartChange()` (worked example C).
446
+ - **Reading `getCartItemCount()` or `getLocalCart()` right after an add.** The stored cart can still be filling. Await `whenCartSettled()` first, or use the cart the add resolved with.
384
447
 
385
448
  ## Quick audit
386
449
 
@@ -399,6 +462,12 @@ grep -rnE 'window\.FairShareSDK\.' --include='*.liquid' --include='*.js' . 2>/de
399
462
  # Hardcoded toast messages (missing | t | json)
400
463
  grep -rnE 'messages:[[:space:]]*\{' --include='*.liquid' . 2>/dev/null
401
464
 
465
+ # createCart() used to read data (it replaces the shopper's cart)
466
+ grep -rnE 'createCart\(' --include='*.liquid' --include='*.js' . 2>/dev/null
467
+
468
+ # Custom addCartItems calls: confirm each one opens the drawer at the click
469
+ grep -rlE 'addCartItems' --include='*.liquid' --include='*.js' . 2>/dev/null | xargs grep -LE 'cart\.control\.open|openCart|data-fluid-cart="open"' 2>/dev/null
470
+
402
471
  # Hand-rolled cart fetches that bypass the SDK
403
472
  grep -rnE "fetch\(['\"][^'\"]*cart" --include='*.liquid' --include='*.js' . 2>/dev/null
404
473
  ```
@@ -426,7 +495,10 @@ Each hit is a candidate finding — confirm in context before flagging.
426
495
  - [ ] Listener attached once (layout level or guarded), never per-section / per-card
427
496
  - [ ] Failures surfaced from `CART_OPERATION_ERROR`, not a `try/catch` (mandatory for `addCartItems` / `decrementCartItem`)
428
497
  - [ ] Per-card / per-item reactions matched via `variantIds` / `itemId`; enrollment via `enrollmentPackId`
429
- - [ ] Cart count read via `getCartItemCount()`, not a guessed `e.detail.cart` field
498
+ - [ ] Cart count comes from `#fluid-cart-count`, or from `getCartItemCount()` after `whenCartSettled()`, not a guessed `e.detail.cart` field
499
+ - [ ] A custom `addCartItems` button opens the SDK drawer at the click (`FairShareSDK.cart.control.open()`), before awaiting the add
500
+ - [ ] A hand-built drawer draws `getPendingCartItems()` and redraws on `onCartChange()`, not only on `CART_OPERATION_SUCCESS`
501
+ - [ ] No `createCart()` call reads data (it replaces the shopper's cart); use `getCountryCode()` / `getLanguage()` / `getLocalCart()`
430
502
 
431
503
  **Correctness**
432
504
 
@@ -438,7 +510,7 @@ Each hit is a candidate finding — confirm in context before flagging.
438
510
  ## Boundaries — local edits, lint, never push
439
511
 
440
512
  - 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**.
441
- - 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.
513
+ - 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, and warns (never errors) on two cart-code patterns: `cart/create-cart-for-data` (`FairShareSDK.createCart()` used to read data; it creates a new empty cart, so use `getCountryCode()` / `getLocalCart()`) and `cart/custom-add-without-drawer-open` (a file calls `addCartItems` / `addEnrollmentPack` / `setEnrollment` but never opens the drawer at click or renders from `onCartChange()` / `getPendingCartItems()`; the SDK drawer does not open for a scripted add, only for declarative buttons). It does **not** execute or check 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.
442
514
  - 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.
443
515
 
444
516
  ## Reference
@@ -41,8 +41,8 @@ Every cart mutation dispatches one of the two events. The **failure column matte
41
41
 
42
42
  | Function | Category | On success | On failure |
43
43
  | ----------------------- | -------- | ------------------------ | ----------------------------------------------------- |
44
- | `addCartItems` | add | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **resolves `undefined`** (swallowed) |
45
- | `addEnrollmentPack` | add | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **rethrows** |
44
+ | `addCartItems` | add | `CART_OPERATION_SUCCESS` (resolves with the filled cart) | `CART_OPERATION_ERROR` — **resolves `undefined`** (swallowed); also when the cart fill fails |
45
+ | `addEnrollmentPack` | add | `CART_OPERATION_SUCCESS` (resolves with the filled cart) | `CART_OPERATION_ERROR` — **rethrows** (resolves `undefined` when the cart fill fails) |
46
46
  | `updateCartItems` | update | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **rethrows** |
47
47
  | `decrementCartItem` | update | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **resolves `undefined`** (swallowed) |
48
48
  | `updateCartItemVariant` | update | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **rethrows** |
@@ -67,7 +67,7 @@ Both events expose an identical `detail` object structure. Fields marked "when k
67
67
  | `itemId` | `number` | when known | Cart item id (item-scoped ops). |
68
68
  | `enrollmentPackId` | `number` | when known | Enrollment pack id (`addEnrollmentPack`). |
69
69
 
70
- > 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.
70
+ > For a count, use the SDK-synced `id="fluid-cart-count"` element, or call `window.FairShareSDK.getCartItemCount()` after `await window.FairShareSDK.whenCartSettled()`: the getter counts only the stored cart's items, so it is `0` while a new cart is still filling and ignores lines still pending. The `cart` object's shape is not enumerated here, so read `e.detail.cart` fields only after confirming them in a running theme.
71
71
 
72
72
  ## `configureCartFeedback()` — complete config keys
73
73
 
@@ -184,6 +184,7 @@ The spinner inherits the button's text color, so it needs no per-theme CSS.
184
184
  ```javascript
185
185
  // Automated cleanup (preferred)
186
186
  button.addEventListener("click", (e) => {
187
+ window.FairShareSDK?.cart.control.open(); // only if the SDK drawer should show the add; open at click
187
188
  window.FairShareSDK?.withButtonLoading(e.currentTarget, () =>
188
189
  window.FairShareSDK.addCartItems(11111, { quantity: 1 }),
189
190
  );
@@ -151,6 +151,16 @@ The reviewer should flag these on any element that uses `data-fluid-*`:
151
151
  | `data-fluid-quantity="{{ section.settings.default_qty | default: 1 }}"` rendering to empty | `should` | Always provide a `default:` filter for settings that are required by the SDK to be integers. |
152
152
  | `data-fluid-bundled-items` JSON built with un-escaped Liquid (commas/quotes from user content) | `blocker` | Render through ` | json` or hand-craft only with sanitized numeric IDs. User-controlled strings inside JSON attributes are an XSS path. |
153
153
 
154
+ #### Cart calls in theme JavaScript
155
+
156
+ Every storefront creates carts in the background: a new cart is empty and `population_status: "pending"` for a few hundred ms to about 2 s. `addCartItems`, `addEnrollmentPack` and `setEnrollment` wait for the fill and resolve with the filled cart (`undefined` when the add or the fill fails). See [Cart operation feedback](../../themes-cart-feedback/SKILL.md#custom-buttons-and-drawers-async-carts) for the recipes.
157
+
158
+ | You see | Severity | Fix |
159
+ | --- | --- | --- |
160
+ | `FairShareSDK.createCart()` used to read data such as the country | `blocker` | `createCart()` always creates a NEW empty cart and replaces the shopper's cart token. Read with `getCountryCode()`, `getLanguage()` or `getLocalCart()`. |
161
+ | A theme script calls `addCartItems(...)` for a button that should show the SDK cart drawer and never calls `FairShareSDK.cart.control.open()` | `should` | Call `FairShareSDK.cart.control.open()` at the click, before awaiting the add. Only declarative `data-fluid-add-to-cart` / `data-fluid-add-enrollment-pack` buttons open the drawer at click on their own. |
162
+ | A hand-built drawer opens or redraws only on `CART_OPERATION_SUCCESS` | `should` | Draw `getPendingCartItems()` on top of the cart and redraw on `onCartChange()`. |
163
+
154
164
  ### Quick audit
155
165
 
156
166
  From the theme repo root:
@@ -172,6 +182,9 @@ done
172
182
 
173
183
  # Wrong cart action values
174
184
  grep -rE 'data-fluid-cart="(?!(open|close|toggle)")' --include='*.liquid' . 2>/dev/null
185
+
186
+ # createCart() used to read data (it replaces the shopper's cart)
187
+ grep -rnE 'createCart\(' --include='*.liquid' --include='*.js' . 2>/dev/null
175
188
  ```
176
189
 
177
190
  ### Checklist for FairShare-attributed elements
@@ -183,5 +196,7 @@ grep -rE 'data-fluid-cart="(?!(open|close|toggle)")' --include='*.liquid' . 2>/d
183
196
  - [ ] `data-fluid-bundled-items` / `data-fluid-bundle-selections` are valid JSON arrays with numeric IDs and quantities
184
197
  - [ ] Attributes live on a `<button>` or `<a>` (or have appropriate ARIA + click semantics)
185
198
  - [ ] Script tag has `id="fluid-cdn-script"` and `data-fluid-shop` set, and there is exactly one
199
+ - [ ] No `FairShareSDK.createCart()` call reads data; it replaces the shopper's cart
200
+ - [ ] A custom `addCartItems` button opens the SDK drawer at the click with `FairShareSDK.cart.control.open()`
186
201
 
187
202
  ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fluid-app/fluid-cli-theme-dev",
3
- "version": "0.1.244",
3
+ "version": "0.1.245",
4
4
  "description": "Fluid CLI plugin for theme developer workflows — dev server, push, pull, init, crawl, compare",
5
5
  "files": [
6
6
  "dist",