@wix/himalaya-cli 0.1117.0 → 0.1119.0

package/templates/gym-fitness/tier5-src/himi-store-product/index.ts

@@ -282,12 +282,18 @@ function derive(s: S): S {
   };
 }
 
+// Bumped by every add (queued, failed or landed): a cart count read BEFORE it — the load's badge
+// read answering late — must not replace the badge the add set (#3468 review).
+let cartBadgeEpoch = 0;
+
 const svc = defineService<S, {
   load: (s: S, arg?: unknown) => Promise<S>;
   setQuantity: (s: S, arg?: unknown) => S;
   selectOption: (s: S, arg?: unknown) => S;
   addToCart: (s: S) => Promise<S>;
   beginAdd: (s: S, arg?: unknown) => S;
+  paintCached: (s: S, arg?: unknown) => S;
+  setCartCount: (s: S, arg?: unknown) => S;
   share: (s: S) => Promise<S>;
   toggleSave: (s: S) => S;
 }>("himiStoreProduct", {
@@ -350,9 +356,46 @@ const svc = defineService<S, {
         lastLoadedId = undefined;
         return derive({ ...s, status: "ready", quantity: 1, optionGroups: [], selection: {}, optionsUnknown: false, emptyText: copyParam("product.notFoundText", "Product not found.") });
       }
-      try {
-        const r = await getStoreProduct(id);
-        const p = (r.product ?? (r as unknown as StoreProduct)) as StoreProduct;
+      // The cart count only feeds the top-bar badge: ask for it NOW, beside the product, instead
+      // of after it — it used to add a whole cart round trip before the page could paint.
+      const cartCount = cartItemCount();
+      // The badge must never hold the page: remember the count if it is already in, and
+      // publish it separately if it lands after the product (#3468 review).
+      let cartKnown: number | undefined;
+      void cartCount.then((n) => { cartKnown = n; }, () => {});
+      // The live product read goes out FIRST too — the local-db read below must never delay it.
+      // Settled into a value so a failure is handled where it is awaited, never unhandled.
+      const live = getStoreProduct(id).then(
+        (r) => ({ ok: true as const, r }),
+        () => ({ ok: false as const }),
+      );
+      // Paint at once from the row the list already synced (name, price, image) — the page used
+      // to sit on its skeleton for the product round trip even when the list had just shown it.
+      // The live read then fills in the description and gallery.
+      const synced = await readCachedProduct(id);
+      let painted = false;
+      if (synced && s.status === "loading") {
+        await svc.paintCached(synced);
+        painted = true;
+      }
+      const outcome = await live;
+      // Once painted the page is INTERACTIVE while the live read is on the wire: the visitor may
+      // save, change the quantity or add to cart. Build on the state as it is NOW, and keep what
+      // they did — overwriting it would untick a stored save, reset the quantity, and drop the
+      // in-flight add's `adding` guard (a second tap would add the line twice).
+      const base: S = painted ? (svc.getState() as S) : s;
+      const keep = painted
+        ? { saved: base.saved, saveHint: base.saveHint, quantity: base.quantity, adding: base.adding, added: base.added, cartHint: base.cartHint }
+        : { cartHint: "", quantity: 1 };
+      const badge = (): number => {
+        if (painted && (base.adding || base.added)) return base.cartCount;
+        if (cartKnown !== undefined) return cartKnown;
+        const epoch = cartBadgeEpoch;
+        void cartCount.then((n) => { void svc.setCartCount({ count: n, epoch }); }, () => {});
+        return base.cartCount;
+      };
+      if (outcome.ok) {
+        const p = (outcome.r.product ?? (outcome.r as unknown as StoreProduct)) as StoreProduct;
         const name = cleanTitle(p.name) || "Product";
         const image = productImage(p, WIX_DETAIL_IMAGE);
         lastProduct = p;
@@ -373,7 +416,8 @@ const svc = defineService<S, {
         }
         lastLoadedId = id;
         return derive({
-          ...s,
+          ...base,
+          ...keep,
           status: "ready",
           optionGroups,
           selection: { ...defaultSelection(optionGroups), ...carried },
@@ -385,46 +429,42 @@ const svc = defineService<S, {
           gallery: productGallery(p),
           initial: (name[0] || "#").toUpperCase(),
           shareUrl: productShareUrl(p),
-          cartHint: "",
-          cartCount: await cartItemCount(),
+          cartCount: badge(),
           emptyText: "",
-          quantity: 1,
         });
-      } catch {
-        // Offline: fall back to the last-synced cached product row before the error state.
-        const cached = await readCachedProduct(id);
-        if (cached) {
-          const name = String(cached.name ?? "") || "Product";
-          const image = String(cached.image ?? "");
-          // The cached list row carries no options, and guessing "none" would offer
-          // a one-tap Add to cart for a product that needs a colour and a size. So
-          // the offline detail shows no picker AND marks the options UNKNOWN, which
-          // keeps `optionsIncomplete` true: the CTA stays disabled and `addToCart`
-          // refuses. `cartHint` carries the reason, because the options card is hidden
-          // on `noOptions` and would otherwise leave a dead button unexplained.
-          lastProduct = undefined;
-          lastLoadedId = undefined;
-          return derive({
-            ...s,
-            status: "ready",
-            optionGroups: [],
-            selection: {},
-            optionsUnknown: true,
-            name,
-            price: String(cached.subtitle ?? ""),
-            description: "",
-            image,
-            initial: String(cached.initial ?? "") || (name[0] || "#").toUpperCase(),
-            cartHint: copyParam("product.cartHintOffline", "Reconnect to choose options and add this to your cart."),
-            cartCount: await cartItemCount(),
-            emptyText: "",
-            quantity: 1,
-          });
-        }
+      }
+      // Offline: fall back to the last-synced cached product row before the error state.
+      if (synced) {
+        const name = String(synced.name ?? "") || "Product";
+        const image = String(synced.image ?? "");
+        // The cached list row carries no options, and guessing "none" would offer
+        // a one-tap Add to cart for a product that needs a colour and a size. So
+        // the offline detail shows no picker AND marks the options UNKNOWN, which
+        // keeps `optionsIncomplete` true: the CTA stays disabled and `addToCart`
+        // refuses. `cartHint` carries the reason, because the options card is hidden
+        // on `noOptions` and would otherwise leave a dead button unexplained.
         lastProduct = undefined;
         lastLoadedId = undefined;
-        return derive({ ...s, status: "error", optionGroups: [], selection: {}, optionsUnknown: false, emptyText: copyParam("product.errorText", "Product could not load.") });
+        return derive({
+          ...base,
+          ...keep,
+          status: "ready",
+          optionGroups: [],
+          selection: {},
+          optionsUnknown: true,
+          name,
+          price: String(synced.subtitle ?? ""),
+          description: "",
+          image,
+          initial: String(synced.initial ?? "") || (name[0] || "#").toUpperCase(),
+          cartHint: copyParam("product.cartHintOffline", "Reconnect to choose options and add this to your cart."),
+          cartCount: badge(),
+          emptyText: "",
+        });
       }
+      lastProduct = undefined;
+      lastLoadedId = undefined;
+      return derive({ ...s, status: "error", optionGroups: [], selection: {}, optionsUnknown: false, emptyText: copyParam("product.errorText", "Product could not load.") });
     },
     // The stepper fires onChange with { value } on every tap; clamp 1–99 and
     // ignore unparsable/garbage args instead of silently zeroing the quantity.
@@ -456,8 +496,41 @@ const svc = defineService<S, {
     // settle. Called from addToCart, not from the descriptor.
     beginAdd: (s, arg) => {
       const quantity = parseQuantity(argValue(arg, "quantity")) ?? 1;
+      cartBadgeEpoch += 1;
       return derive({ ...s, adding: true, added: false, cartHint: "", cartCount: s.cartCount + quantity });
     },
+    // The first paint from the list's synced row (called from load, not from the descriptor):
+    // name, price and image are on screen while the live product — description, gallery — loads.
+    // The cart count answered after the product: only the top-bar badge changes.
+    setCartCount: (s, arg) => {
+      // An add since the count was asked for owns the badge — in flight, landed or QUEUED offline
+      // (which leaves adding/added false): a pre-add count must not undo it.
+      const { count, epoch } = (arg ?? {}) as { count?: unknown; epoch?: unknown };
+      if (epoch !== cartBadgeEpoch || s.adding || s.added) return s;
+      const n = Math.max(0, Math.floor(Number(count)));
+      return Number.isFinite(n) ? derive({ ...s, cartCount: n }) : s;
+    },
+    paintCached: (s, arg) => {
+      const row = (arg ?? {}) as DbEntity;
+      const name = String(row.name ?? "") || "Product";
+      return derive({
+        ...s,
+        status: "ready",
+        name,
+        price: String(row.subtitle ?? ""),
+        description: "",
+        image: String(row.image ?? ""),
+        gallery: [],
+        initial: String(row.initial ?? "") || (name[0] || "#").toUpperCase(),
+        // The synced list row carries no options: until the live read says what they are,
+        // they are UNKNOWN, which keeps the CTA disabled — never a one-tap Add to cart for a
+        // product that needs a size. The live read replaces this a moment later.
+        optionGroups: [],
+        optionsUnknown: true,
+        emptyText: "",
+        quantity: 1,
+      });
+    },
     addToCart: async (s) => {
       const id = inputId();
       if (!id) return derive({ ...s, cartHint: copyParam("product.cartHintNoProduct", "No product to add.") });

package/templates/portfolio-creative/tier5-src/himi-store-product/index.ts

@@ -282,12 +282,18 @@ function derive(s: S): S {
   };
 }
 
+// Bumped by every add (queued, failed or landed): a cart count read BEFORE it — the load's badge
+// read answering late — must not replace the badge the add set (#3468 review).
+let cartBadgeEpoch = 0;
+
 const svc = defineService<S, {
   load: (s: S, arg?: unknown) => Promise<S>;
   setQuantity: (s: S, arg?: unknown) => S;
   selectOption: (s: S, arg?: unknown) => S;
   addToCart: (s: S) => Promise<S>;
   beginAdd: (s: S, arg?: unknown) => S;
+  paintCached: (s: S, arg?: unknown) => S;
+  setCartCount: (s: S, arg?: unknown) => S;
   share: (s: S) => Promise<S>;
   toggleSave: (s: S) => S;
 }>("himiStoreProduct", {
@@ -350,9 +356,46 @@ const svc = defineService<S, {
         lastLoadedId = undefined;
         return derive({ ...s, status: "ready", quantity: 1, optionGroups: [], selection: {}, optionsUnknown: false, emptyText: copyParam("product.notFoundText", "Product not found.") });
       }
-      try {
-        const r = await getStoreProduct(id);
-        const p = (r.product ?? (r as unknown as StoreProduct)) as StoreProduct;
+      // The cart count only feeds the top-bar badge: ask for it NOW, beside the product, instead
+      // of after it — it used to add a whole cart round trip before the page could paint.
+      const cartCount = cartItemCount();
+      // The badge must never hold the page: remember the count if it is already in, and
+      // publish it separately if it lands after the product (#3468 review).
+      let cartKnown: number | undefined;
+      void cartCount.then((n) => { cartKnown = n; }, () => {});
+      // The live product read goes out FIRST too — the local-db read below must never delay it.
+      // Settled into a value so a failure is handled where it is awaited, never unhandled.
+      const live = getStoreProduct(id).then(
+        (r) => ({ ok: true as const, r }),
+        () => ({ ok: false as const }),
+      );
+      // Paint at once from the row the list already synced (name, price, image) — the page used
+      // to sit on its skeleton for the product round trip even when the list had just shown it.
+      // The live read then fills in the description and gallery.
+      const synced = await readCachedProduct(id);
+      let painted = false;
+      if (synced && s.status === "loading") {
+        await svc.paintCached(synced);
+        painted = true;
+      }
+      const outcome = await live;
+      // Once painted the page is INTERACTIVE while the live read is on the wire: the visitor may
+      // save, change the quantity or add to cart. Build on the state as it is NOW, and keep what
+      // they did — overwriting it would untick a stored save, reset the quantity, and drop the
+      // in-flight add's `adding` guard (a second tap would add the line twice).
+      const base: S = painted ? (svc.getState() as S) : s;
+      const keep = painted
+        ? { saved: base.saved, saveHint: base.saveHint, quantity: base.quantity, adding: base.adding, added: base.added, cartHint: base.cartHint }
+        : { cartHint: "", quantity: 1 };
+      const badge = (): number => {
+        if (painted && (base.adding || base.added)) return base.cartCount;
+        if (cartKnown !== undefined) return cartKnown;
+        const epoch = cartBadgeEpoch;
+        void cartCount.then((n) => { void svc.setCartCount({ count: n, epoch }); }, () => {});
+        return base.cartCount;
+      };
+      if (outcome.ok) {
+        const p = (outcome.r.product ?? (outcome.r as unknown as StoreProduct)) as StoreProduct;
         const name = cleanTitle(p.name) || "Product";
         const image = productImage(p, WIX_DETAIL_IMAGE);
         lastProduct = p;
@@ -373,7 +416,8 @@ const svc = defineService<S, {
         }
         lastLoadedId = id;
         return derive({
-          ...s,
+          ...base,
+          ...keep,
           status: "ready",
           optionGroups,
           selection: { ...defaultSelection(optionGroups), ...carried },
@@ -385,46 +429,42 @@ const svc = defineService<S, {
           gallery: productGallery(p),
           initial: (name[0] || "#").toUpperCase(),
           shareUrl: productShareUrl(p),
-          cartHint: "",
-          cartCount: await cartItemCount(),
+          cartCount: badge(),
           emptyText: "",
-          quantity: 1,
         });
-      } catch {
-        // Offline: fall back to the last-synced cached product row before the error state.
-        const cached = await readCachedProduct(id);
-        if (cached) {
-          const name = String(cached.name ?? "") || "Product";
-          const image = String(cached.image ?? "");
-          // The cached list row carries no options, and guessing "none" would offer
-          // a one-tap Add to cart for a product that needs a colour and a size. So
-          // the offline detail shows no picker AND marks the options UNKNOWN, which
-          // keeps `optionsIncomplete` true: the CTA stays disabled and `addToCart`
-          // refuses. `cartHint` carries the reason, because the options card is hidden
-          // on `noOptions` and would otherwise leave a dead button unexplained.
-          lastProduct = undefined;
-          lastLoadedId = undefined;
-          return derive({
-            ...s,
-            status: "ready",
-            optionGroups: [],
-            selection: {},
-            optionsUnknown: true,
-            name,
-            price: String(cached.subtitle ?? ""),
-            description: "",
-            image,
-            initial: String(cached.initial ?? "") || (name[0] || "#").toUpperCase(),
-            cartHint: copyParam("product.cartHintOffline", "Reconnect to choose options and add this to your cart."),
-            cartCount: await cartItemCount(),
-            emptyText: "",
-            quantity: 1,
-          });
-        }
+      }
+      // Offline: fall back to the last-synced cached product row before the error state.
+      if (synced) {
+        const name = String(synced.name ?? "") || "Product";
+        const image = String(synced.image ?? "");
+        // The cached list row carries no options, and guessing "none" would offer
+        // a one-tap Add to cart for a product that needs a colour and a size. So
+        // the offline detail shows no picker AND marks the options UNKNOWN, which
+        // keeps `optionsIncomplete` true: the CTA stays disabled and `addToCart`
+        // refuses. `cartHint` carries the reason, because the options card is hidden
+        // on `noOptions` and would otherwise leave a dead button unexplained.
         lastProduct = undefined;
         lastLoadedId = undefined;
-        return derive({ ...s, status: "error", optionGroups: [], selection: {}, optionsUnknown: false, emptyText: copyParam("product.errorText", "Product could not load.") });
+        return derive({
+          ...base,
+          ...keep,
+          status: "ready",
+          optionGroups: [],
+          selection: {},
+          optionsUnknown: true,
+          name,
+          price: String(synced.subtitle ?? ""),
+          description: "",
+          image,
+          initial: String(synced.initial ?? "") || (name[0] || "#").toUpperCase(),
+          cartHint: copyParam("product.cartHintOffline", "Reconnect to choose options and add this to your cart."),
+          cartCount: badge(),
+          emptyText: "",
+        });
       }
+      lastProduct = undefined;
+      lastLoadedId = undefined;
+      return derive({ ...s, status: "error", optionGroups: [], selection: {}, optionsUnknown: false, emptyText: copyParam("product.errorText", "Product could not load.") });
     },
     // The stepper fires onChange with { value } on every tap; clamp 1–99 and
     // ignore unparsable/garbage args instead of silently zeroing the quantity.
@@ -456,8 +496,41 @@ const svc = defineService<S, {
     // settle. Called from addToCart, not from the descriptor.
     beginAdd: (s, arg) => {
       const quantity = parseQuantity(argValue(arg, "quantity")) ?? 1;
+      cartBadgeEpoch += 1;
       return derive({ ...s, adding: true, added: false, cartHint: "", cartCount: s.cartCount + quantity });
     },
+    // The first paint from the list's synced row (called from load, not from the descriptor):
+    // name, price and image are on screen while the live product — description, gallery — loads.
+    // The cart count answered after the product: only the top-bar badge changes.
+    setCartCount: (s, arg) => {
+      // An add since the count was asked for owns the badge — in flight, landed or QUEUED offline
+      // (which leaves adding/added false): a pre-add count must not undo it.
+      const { count, epoch } = (arg ?? {}) as { count?: unknown; epoch?: unknown };
+      if (epoch !== cartBadgeEpoch || s.adding || s.added) return s;
+      const n = Math.max(0, Math.floor(Number(count)));
+      return Number.isFinite(n) ? derive({ ...s, cartCount: n }) : s;
+    },
+    paintCached: (s, arg) => {
+      const row = (arg ?? {}) as DbEntity;
+      const name = String(row.name ?? "") || "Product";
+      return derive({
+        ...s,
+        status: "ready",
+        name,
+        price: String(row.subtitle ?? ""),
+        description: "",
+        image: String(row.image ?? ""),
+        gallery: [],
+        initial: String(row.initial ?? "") || (name[0] || "#").toUpperCase(),
+        // The synced list row carries no options: until the live read says what they are,
+        // they are UNKNOWN, which keeps the CTA disabled — never a one-tap Add to cart for a
+        // product that needs a size. The live read replaces this a moment later.
+        optionGroups: [],
+        optionsUnknown: true,
+        emptyText: "",
+        quantity: 1,
+      });
+    },
     addToCart: async (s) => {
       const id = inputId();
       if (!id) return derive({ ...s, cartHint: copyParam("product.cartHintNoProduct", "No product to add.") });

package/templates/retail-store/tier5-src/himi-store-product/index.ts

@@ -282,12 +282,18 @@ function derive(s: S): S {
   };
 }
 
+// Bumped by every add (queued, failed or landed): a cart count read BEFORE it — the load's badge
+// read answering late — must not replace the badge the add set (#3468 review).
+let cartBadgeEpoch = 0;
+
 const svc = defineService<S, {
   load: (s: S, arg?: unknown) => Promise<S>;
   setQuantity: (s: S, arg?: unknown) => S;
   selectOption: (s: S, arg?: unknown) => S;
   addToCart: (s: S) => Promise<S>;
   beginAdd: (s: S, arg?: unknown) => S;
+  paintCached: (s: S, arg?: unknown) => S;
+  setCartCount: (s: S, arg?: unknown) => S;
   share: (s: S) => Promise<S>;
   toggleSave: (s: S) => S;
 }>("himiStoreProduct", {
@@ -350,9 +356,46 @@ const svc = defineService<S, {
         lastLoadedId = undefined;
         return derive({ ...s, status: "ready", quantity: 1, optionGroups: [], selection: {}, optionsUnknown: false, emptyText: copyParam("product.notFoundText", "Product not found.") });
       }
-      try {
-        const r = await getStoreProduct(id);
-        const p = (r.product ?? (r as unknown as StoreProduct)) as StoreProduct;
+      // The cart count only feeds the top-bar badge: ask for it NOW, beside the product, instead
+      // of after it — it used to add a whole cart round trip before the page could paint.
+      const cartCount = cartItemCount();
+      // The badge must never hold the page: remember the count if it is already in, and
+      // publish it separately if it lands after the product (#3468 review).
+      let cartKnown: number | undefined;
+      void cartCount.then((n) => { cartKnown = n; }, () => {});
+      // The live product read goes out FIRST too — the local-db read below must never delay it.
+      // Settled into a value so a failure is handled where it is awaited, never unhandled.
+      const live = getStoreProduct(id).then(
+        (r) => ({ ok: true as const, r }),
+        () => ({ ok: false as const }),
+      );
+      // Paint at once from the row the list already synced (name, price, image) — the page used
+      // to sit on its skeleton for the product round trip even when the list had just shown it.
+      // The live read then fills in the description and gallery.
+      const synced = await readCachedProduct(id);
+      let painted = false;
+      if (synced && s.status === "loading") {
+        await svc.paintCached(synced);
+        painted = true;
+      }
+      const outcome = await live;
+      // Once painted the page is INTERACTIVE while the live read is on the wire: the visitor may
+      // save, change the quantity or add to cart. Build on the state as it is NOW, and keep what
+      // they did — overwriting it would untick a stored save, reset the quantity, and drop the
+      // in-flight add's `adding` guard (a second tap would add the line twice).
+      const base: S = painted ? (svc.getState() as S) : s;
+      const keep = painted
+        ? { saved: base.saved, saveHint: base.saveHint, quantity: base.quantity, adding: base.adding, added: base.added, cartHint: base.cartHint }
+        : { cartHint: "", quantity: 1 };
+      const badge = (): number => {
+        if (painted && (base.adding || base.added)) return base.cartCount;
+        if (cartKnown !== undefined) return cartKnown;
+        const epoch = cartBadgeEpoch;
+        void cartCount.then((n) => { void svc.setCartCount({ count: n, epoch }); }, () => {});
+        return base.cartCount;
+      };
+      if (outcome.ok) {
+        const p = (outcome.r.product ?? (outcome.r as unknown as StoreProduct)) as StoreProduct;
         const name = cleanTitle(p.name) || "Product";
         const image = productImage(p, WIX_DETAIL_IMAGE);
         lastProduct = p;
@@ -373,7 +416,8 @@ const svc = defineService<S, {
         }
         lastLoadedId = id;
         return derive({
-          ...s,
+          ...base,
+          ...keep,
           status: "ready",
           optionGroups,
           selection: { ...defaultSelection(optionGroups), ...carried },
@@ -385,46 +429,42 @@ const svc = defineService<S, {
           gallery: productGallery(p),
           initial: (name[0] || "#").toUpperCase(),
           shareUrl: productShareUrl(p),
-          cartHint: "",
-          cartCount: await cartItemCount(),
+          cartCount: badge(),
           emptyText: "",
-          quantity: 1,
         });
-      } catch {
-        // Offline: fall back to the last-synced cached product row before the error state.
-        const cached = await readCachedProduct(id);
-        if (cached) {
-          const name = String(cached.name ?? "") || "Product";
-          const image = String(cached.image ?? "");
-          // The cached list row carries no options, and guessing "none" would offer
-          // a one-tap Add to cart for a product that needs a colour and a size. So
-          // the offline detail shows no picker AND marks the options UNKNOWN, which
-          // keeps `optionsIncomplete` true: the CTA stays disabled and `addToCart`
-          // refuses. `cartHint` carries the reason, because the options card is hidden
-          // on `noOptions` and would otherwise leave a dead button unexplained.
-          lastProduct = undefined;
-          lastLoadedId = undefined;
-          return derive({
-            ...s,
-            status: "ready",
-            optionGroups: [],
-            selection: {},
-            optionsUnknown: true,
-            name,
-            price: String(cached.subtitle ?? ""),
-            description: "",
-            image,
-            initial: String(cached.initial ?? "") || (name[0] || "#").toUpperCase(),
-            cartHint: copyParam("product.cartHintOffline", "Reconnect to choose options and add this to your cart."),
-            cartCount: await cartItemCount(),
-            emptyText: "",
-            quantity: 1,
-          });
-        }
+      }
+      // Offline: fall back to the last-synced cached product row before the error state.
+      if (synced) {
+        const name = String(synced.name ?? "") || "Product";
+        const image = String(synced.image ?? "");
+        // The cached list row carries no options, and guessing "none" would offer
+        // a one-tap Add to cart for a product that needs a colour and a size. So
+        // the offline detail shows no picker AND marks the options UNKNOWN, which
+        // keeps `optionsIncomplete` true: the CTA stays disabled and `addToCart`
+        // refuses. `cartHint` carries the reason, because the options card is hidden
+        // on `noOptions` and would otherwise leave a dead button unexplained.
         lastProduct = undefined;
         lastLoadedId = undefined;
-        return derive({ ...s, status: "error", optionGroups: [], selection: {}, optionsUnknown: false, emptyText: copyParam("product.errorText", "Product could not load.") });
+        return derive({
+          ...base,
+          ...keep,
+          status: "ready",
+          optionGroups: [],
+          selection: {},
+          optionsUnknown: true,
+          name,
+          price: String(synced.subtitle ?? ""),
+          description: "",
+          image,
+          initial: String(synced.initial ?? "") || (name[0] || "#").toUpperCase(),
+          cartHint: copyParam("product.cartHintOffline", "Reconnect to choose options and add this to your cart."),
+          cartCount: badge(),
+          emptyText: "",
+        });
       }
+      lastProduct = undefined;
+      lastLoadedId = undefined;
+      return derive({ ...s, status: "error", optionGroups: [], selection: {}, optionsUnknown: false, emptyText: copyParam("product.errorText", "Product could not load.") });
     },
     // The stepper fires onChange with { value } on every tap; clamp 1–99 and
     // ignore unparsable/garbage args instead of silently zeroing the quantity.
@@ -456,8 +496,41 @@ const svc = defineService<S, {
     // settle. Called from addToCart, not from the descriptor.
     beginAdd: (s, arg) => {
       const quantity = parseQuantity(argValue(arg, "quantity")) ?? 1;
+      cartBadgeEpoch += 1;
       return derive({ ...s, adding: true, added: false, cartHint: "", cartCount: s.cartCount + quantity });
     },
+    // The first paint from the list's synced row (called from load, not from the descriptor):
+    // name, price and image are on screen while the live product — description, gallery — loads.
+    // The cart count answered after the product: only the top-bar badge changes.
+    setCartCount: (s, arg) => {
+      // An add since the count was asked for owns the badge — in flight, landed or QUEUED offline
+      // (which leaves adding/added false): a pre-add count must not undo it.
+      const { count, epoch } = (arg ?? {}) as { count?: unknown; epoch?: unknown };
+      if (epoch !== cartBadgeEpoch || s.adding || s.added) return s;
+      const n = Math.max(0, Math.floor(Number(count)));
+      return Number.isFinite(n) ? derive({ ...s, cartCount: n }) : s;
+    },
+    paintCached: (s, arg) => {
+      const row = (arg ?? {}) as DbEntity;
+      const name = String(row.name ?? "") || "Product";
+      return derive({
+        ...s,
+        status: "ready",
+        name,
+        price: String(row.subtitle ?? ""),
+        description: "",
+        image: String(row.image ?? ""),
+        gallery: [],
+        initial: String(row.initial ?? "") || (name[0] || "#").toUpperCase(),
+        // The synced list row carries no options: until the live read says what they are,
+        // they are UNKNOWN, which keeps the CTA disabled — never a one-tap Add to cart for a
+        // product that needs a size. The live read replaces this a moment later.
+        optionGroups: [],
+        optionsUnknown: true,
+        emptyText: "",
+        quantity: 1,
+      });
+    },
     addToCart: async (s) => {
       const id = inputId();
       if (!id) return derive({ ...s, cartHint: copyParam("product.cartHintNoProduct", "No product to add.") });