@wix/himalaya-cli 0.1032.0 → 0.1034.0

package/templates/branded-lite/tier5-src/himi-branded-lite-giftcards/index.ts

@@ -1,15 +1,14 @@
-// himi-branded-lite-giftcards — branded-lite "Gift Cards" worker with a SAMPLE-DATA
-// fallback (same pattern as the other branded-lite verticals). Reads the site's real
-// Wix Gift Cards (queryGiftCards); when the site has no Gift Cards app / none are
-// readable (the query errors — e.g. 403/404/428 — or returns empty), it substitutes
-// representative SAMPLE gift cards and flags `isMock`, so the screen shows a clearly-
-// labelled "Sample content" banner. Real gift cards always win the moment any exist.
+// himi-branded-lite-giftcards — reads the visitor's real Wix Gift Cards (queryGiftCards).
+// a failed query is an error with Retry (or Sign in when Wix refuses the
+// visitor) and an empty one is a real empty state — never sample rows presented as
+// the customer's own. Samples appear only in the host's explicit sample preview
+// (_shared/branded-load-state.ts).
 import { defineService } from "../_shared/collection-service.js";
+import { LOADING, loaded, loadFailed, type LoadCopy, type LoadFlags } from "../_shared/branded-load-state.js";
 import { queryGiftCards, type WixGiftCard } from "@himalaya/wix-gift-cards";
 
 interface Row { id: string; title: string; subtitle: string }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   cards: Row[]; emptyText: string;
   isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
    *  shows only when the site really has none, and the unavailable one only when the
@@ -44,21 +43,26 @@ const MOCK: Row[] = [
   { id: "sample-3", title: "Gift card ····3312", subtitle: "Balance $0.00" },
 ];
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", cards: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
-}
+/** sample rows reach the screen ONLY in the host's explicit sample preview;
+ *  a failed or empty query is an honest error / empty state (branded-load-state.ts). */
+const COPY: LoadCopy<Row> = {
+  prefix: "giftCards",
+  empty: "You don't have any gift cards yet.",
+  error: "Your gift cards couldn't be loaded.",
+  signIn: "Sign in to see your gift cards.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedGiftCards", {
-  state: { status: "loading", cards: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+  state: { ...LOADING, cards: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
         const r = await queryGiftCards({ query: { cursorPaging: { limit: 20 } } });
         const cards = (r.giftCards ?? []).map(norm);
-        if (cards.length) return { ...s, status: "ready", cards, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return { ...s, ...loaded("cards", cards, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("cards", err, COPY) };
       }
     },
   },

package/templates/branded-lite/tier5-src/himi-branded-lite-inbox/index.ts

@@ -1,17 +1,17 @@
-// himi-branded-lite-inbox — branded-lite "Inbox" worker (Wix Inbox / member↔business
-// chat). Reads the site's real inbox conversations (listConversations); when the site
-// has no Inbox app / no conversations (the query errors — e.g. 403/404/428 — or returns
-// empty), it substitutes representative SAMPLE conversations and flags `isMock`, so the
-// screen shows a clearly-labelled "Sample content" banner. Real conversations always win.
+// himi-branded-lite-inbox — reads the visitor's real Wix Inbox conversations (listConversations).
+// a failed query is an error with Retry (or Sign in when Wix refuses the
+// visitor) and an empty one is a real empty state — never sample rows presented as
+// the customer's own. Samples appear only in the host's explicit sample preview
+// (_shared/branded-load-state.ts).
 //
 // Inbox exposes no list-messages endpoint (only listConversations + single getMessage),
 // so this is a conversation LIST — same read-view scope as the Galleries/Forms verticals.
 import { defineService } from "../_shared/collection-service.js";
+import { LOADING, loaded, loadFailed, type LoadCopy, type LoadFlags } from "../_shared/branded-load-state.js";
 import { listConversations, type WixConversation } from "@himalaya/wix-inbox";
 
 interface Row { id: string; title: string; subtitle: string }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   conversations: Row[]; emptyText: string;
   isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
    *  shows only when the site really has none, and the unavailable one only when the
@@ -43,21 +43,26 @@ const MOCK: Row[] = [
   { id: "sample-team",    title: "The Team", subtitle: "Welcome 👋 Thanks for joining us!" },
 ];
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", conversations: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
-}
+/** sample rows reach the screen ONLY in the host's explicit sample preview;
+ *  a failed or empty query is an honest error / empty state (branded-load-state.ts). */
+const COPY: LoadCopy<Row> = {
+  prefix: "inbox",
+  empty: "No messages yet.",
+  error: "Your messages couldn't be loaded.",
+  signIn: "Sign in to see your messages.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedInbox", {
-  state: { status: "loading", conversations: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+  state: { ...LOADING, conversations: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
         const r = await listConversations({ paging: { limit: 50 } });
         const conversations = (r.conversations ?? []).map(norm);
-        if (conversations.length) return { ...s, status: "ready", conversations, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return { ...s, ...loaded("conversations", conversations, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("conversations", err, COPY) };
       }
     },
   },

package/templates/branded-lite/tier5-src/himi-branded-lite-invoices/index.ts

@@ -1,15 +1,14 @@
-// himi-branded-lite-invoices — branded-lite "My Invoices" worker with a SAMPLE-DATA
-// fallback (same pattern as the other branded-lite verticals). Reads the member's
-// real Wix Invoices (queryInvoices); when the site has no Invoices app / the member
-// has none (the query errors — e.g. 404/428 — or returns empty), it substitutes
-// representative SAMPLE invoices and flags `isMock`, so the screen shows a clearly-
-// labelled "Sample content" banner. Real invoices always win the moment any exist.
+// himi-branded-lite-invoices — reads the member's real Wix Invoices (queryInvoices).
+// a failed query is an error with Retry (or Sign in when Wix refuses the
+// visitor) and an empty one is a real empty state — never sample rows presented as
+// the customer's own. Samples appear only in the host's explicit sample preview
+// (_shared/branded-load-state.ts).
 import { defineService } from "../_shared/collection-service.js";
+import { LOADING, loaded, loadFailed, type LoadCopy, type LoadFlags } from "../_shared/branded-load-state.js";
 import { queryInvoices, type WixInvoice } from "@himalaya/wix-invoices";
 
 interface Row { id: string; title: string; subtitle: string }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   invoices: Row[]; emptyText: string;
   isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
    *  shows only when the site really has none, and the unavailable one only when the
@@ -45,21 +44,26 @@ const MOCK: Row[] = [
   { id: "sample-1042", title: "Invoice #1042", subtitle: "Overdue · $45.00" },
 ];
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", invoices: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
-}
+/** sample rows reach the screen ONLY in the host's explicit sample preview;
+ *  a failed or empty query is an honest error / empty state (branded-load-state.ts). */
+const COPY: LoadCopy<Row> = {
+  prefix: "invoices",
+  empty: "You don't have any invoices yet.",
+  error: "Your invoices couldn't be loaded.",
+  signIn: "Sign in to see your invoices.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedInvoices", {
-  state: { status: "loading", invoices: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+  state: { ...LOADING, invoices: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
         const r = await queryInvoices({ query: { paging: { limit: 20 } } });
         const invoices = (r.invoices ?? []).filter((v) => v.archived !== true).map(norm);
-        if (invoices.length) return { ...s, status: "ready", invoices, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return { ...s, ...loaded("invoices", invoices, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("invoices", err, COPY) };
       }
     },
   },

package/templates/branded-lite/tier5-src/himi-branded-lite-loyalty/index.ts

@@ -1,16 +1,14 @@
-// himi-branded-lite-loyalty — branded-lite "Rewards" worker with a SAMPLE-DATA
-// fallback (same pattern as himi-branded-lite-coupons/-notifications). Reads the
-// real Wix Loyalty program + rewards catalog (getLoyaltyProgram + listLoyaltyRewards);
-// when the site has no Loyalty program / no rewards (the query errors — e.g.
-// 404/428 — or returns empty), it substitutes representative SAMPLE rewards and
-// flags `isMock`, so the screen shows a clearly-labelled "Sample content" banner.
-// Real rewards always win the moment the program is active with rewards.
+// himi-branded-lite-loyalty — reads the real Wix Loyalty program + rewards (getLoyaltyProgram + listLoyaltyRewards).
+// a failed query is an error with Retry (or Sign in when Wix refuses the
+// visitor) and an empty one is a real empty state — never sample rows presented as
+// the customer's own. Samples appear only in the host's explicit sample preview
+// (_shared/branded-load-state.ts).
 import { defineService } from "../_shared/collection-service.js";
+import { LOADING, loaded, loadFailed, type LoadCopy, type LoadFlags } from "../_shared/branded-load-state.js";
 import { getLoyaltyProgram, listLoyaltyRewards, type WixLoyaltyReward } from "@himalaya/wix-loyalty";
 
 interface Row { id: string; name: string; subtitle: string }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   programName: string; unit: string;
   rewards: Row[]; emptyText: string;
   isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
@@ -39,12 +37,18 @@ const MOCK: Row[] = [
   { id: "sample-gift",    name: "Free welcome gift",     subtitle: "1,000 points" },
 ];
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", programName: "Rewards", unit: "points", rewards: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
-}
+/** sample rows reach the screen ONLY in the host's explicit sample preview;
+ *  a failed or empty query is an honest error / empty state (branded-load-state.ts). */
+const COPY: LoadCopy<Row> = {
+  prefix: "loyalty",
+  empty: "No rewards to redeem yet.",
+  error: "The rewards program couldn't be loaded.",
+  signIn: "Sign in to see your points and rewards.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedLoyalty", {
-  state: { status: "loading", programName: "Rewards", unit: "points", rewards: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+  state: { ...LOADING, programName: "Rewards", unit: "points", rewards: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
@@ -54,10 +58,9 @@ const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedLoyalty
         const programName = (p?.name || "Rewards").trim() || "Rewards";
         const r = await listLoyaltyRewards();
         const rewards = (r.rewards ?? []).filter((x) => x.active !== false).map((x) => norm(x, unit));
-        if (rewards.length) return { ...s, status: "ready", programName, unit, rewards, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return { ...s, programName, unit, ...loaded("rewards", rewards, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("rewards", err, COPY) };
       }
     },
   },

package/templates/branded-lite/tier5-src/himi-branded-lite-notifications/index.ts

@@ -1,13 +1,12 @@
-// himi-branded-lite-notifications — branded-lite member-inbox worker with a
-// SAMPLE-DATA fallback (same pattern as himi-branded-lite-coupons). Reads the
-// signed-in member's real notifications via the Members Feed Viewer service
-// (queryNotifications); when the member has no notifications yet (empty) or the
-// query errors (e.g. app not installed / 428), it substitutes representative
-// SAMPLE notifications and flags `isMock`, so the screen shows a clearly-labelled
-// "Sample content" banner. Real notifications always win the moment any exist.
+// himi-branded-lite-notifications — reads the member's notifications via Members Feed Viewer (queryNotifications).
+// a failed query is an error with Retry (or Sign in when Wix refuses the
+// visitor) and an empty one is a real empty state — never sample rows presented as
+// the customer's own. Samples appear only in the host's explicit sample preview
+// (_shared/branded-load-state.ts).
 // mark-one-read / mark-all-read stay wired: they update state optimistically and
 // best-effort the real write (a no-op on sample rows).
 import { defineService } from "../_shared/collection-service.js";
+import { LOADING, loaded, loadFailed, type LoadCopy, type LoadFlags } from "../_shared/branded-load-state.js";
 import { queryNotifications, markRead, markAllRead, type MfvNotification } from "@himalaya/wix-members-feed-viewer";
 
 interface Row {
@@ -22,8 +21,7 @@ interface Row {
   initial: string;
   dest: string;
 }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   items: Row[]; emptyText: string;
   isMock: boolean; notMock: boolean;
   /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
@@ -92,25 +90,29 @@ const MOCK: Row[] = [
   { id: "sample-offer",   name: "New offer just for you",               subtitle: "15% off your next order · 3d ago", unread: false, unreadDot: "", photo: "", initial: "%", dest: "" },
 ];
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", items: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false,
-    notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable" };
-}
+/** sample rows reach the screen ONLY in the host's explicit sample preview;
+ *  a failed or empty query is an honest error / empty state (branded-load-state.ts). */
+const COPY: LoadCopy<Row> = {
+  prefix: "notifications",
+  empty: "You're all caught up — no notifications yet.",
+  error: "Notifications couldn't be loaded.",
+  signIn: "Sign in to see your notifications.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, {
   load: (s: S) => Promise<S>;
   markOneRead: (s: S, id: string) => Promise<S>;
   markAll: (s: S) => Promise<S>;
 }>("himiBrandedNotifications", {
-  state: { status: "loading", items: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true },
+  state: { ...LOADING, items: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
         const items = (await queryNotifications(25)).map(norm);
-        if (items.length) return { ...s, status: "ready", items, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true };
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return { ...s, ...loaded("items", items, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("items", err, COPY) };
       }
     },
     // Mark one read; optimistically clear its dot. Real write is best-effort and

package/templates/branded-lite/tier5-src/himi-branded-lite-notifsettings/index.ts

@@ -1,13 +1,13 @@
-// himi-branded-lite-notifsettings — branded-lite "Notification Settings" worker
-// with a SAMPLE-DATA fallback (same pattern as the other branded-lite verticals).
-// Reads the site's real notification topics (getNotificationTopics) + the member's
-// per-topic delivery preferences (getMyNotificationPreferences); when the site has
-// no topics configured (the query errors — e.g. 404/428 — or returns empty), it
-// substitutes representative SAMPLE topics and flags `isMock`, so the screen shows
-// a clearly-labelled "Sample content" banner. Real topics always win the moment
+// himi-branded-lite-notifsettings — reads the site's notification topics + the member's preferences.
+// a failed query is an error with Retry (or Sign in when Wix refuses the
+// visitor) and an empty one is a real empty state — never sample rows presented as
+// the customer's own. Samples appear only in the host's explicit sample preview
+// (_shared/branded-load-state.ts).
 // any exist. INTERACTIVE: tapping a row toggles that topic On/Off — optimistic +
 // best-effort upsertMyNotificationPreferences (a no-op on sample rows).
 import { defineService } from "@himalaya/state";
+import { withEmptyFlags } from "../_shared/empty-flags.js";
+import { LOADING, loaded, loadFailed, type LoadCopy, type LoadFlags } from "../_shared/branded-load-state.js";
 import {
   getNotificationTopics,
   getMyNotificationPreferences,
@@ -30,8 +30,7 @@ const CHANNEL = "MOBILE";
 interface Row { id: string; name: string; subtitle: string; note: string; on: boolean; locked: boolean;
   /** Inverse of `locked` (hiddenWhen hides on TRUE) and the plain On/Off a locked row shows. */
   notLocked: boolean; stateLabel: string }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   topics: Row[]; emptyText: string;
   isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
    *  shows only when the site really has none, and the unavailable one only when the
@@ -82,15 +81,21 @@ const MOCK: Row[] = [
   row("sample-community", "Community activity", true),
 ];
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", topics: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
-}
+/** sample rows reach the screen ONLY in the host's explicit sample preview;
+ *  a failed or empty query is an honest error / empty state (branded-load-state.ts). */
+const COPY: LoadCopy<Row> = {
+  prefix: "notifsettings",
+  empty: "No notification topics to manage yet.",
+  error: "Notification settings couldn't be loaded.",
+  signIn: "Sign in to manage your notifications.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, {
   load: (s: S) => Promise<S>;
   toggle: (s: S, p?: { id?: string; value?: unknown }) => Promise<S>;
-}>("himiBrandedNotifSettings", {
-  state: { status: "loading", topics: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+}>("himiBrandedNotifSettings", withEmptyFlags({
+  state: { ...LOADING, topics: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
@@ -100,10 +105,9 @@ const svc = defineService<S, {
         ]);
         const prefs = readPreferences(prefsRes);
         const topics = readTopics(topicsRes).map((t) => norm(t, prefs));
-        if (topics.length) return { ...s, status: "ready", topics, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true };
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return { ...s, ...loaded("topics", topics, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("topics", err, COPY) };
       }
     },
     // Flip one topic's On/Off. Optimistic (updates the row immediately); the real
@@ -132,6 +136,6 @@ const svc = defineService<S, {
       return { ...s, topics };
     },
   },
-});
+}, { topics: "noTopics" }));
 svc.load();
 export { svc };

package/templates/branded-lite/tier5-src/himi-branded-lite-podcasts/index.ts

@@ -154,7 +154,7 @@ const svc = defineService<S, {
     load: async (s, arg) => {
       const configured = typeof (arg as { feedUrl?: unknown } | undefined)?.feedUrl === "string" ? String((arg as { feedUrl: string }).feedUrl).trim() : "";
       if (!configured) {
-        return derive({ ...s, status: "ready", episodes: [], emptyText: "Set the podcast feed URL for this app before building or deploying.", isMock: false, notMock: true, mockBanner: "" });
+        return derive({ ...s, status: "ready", episodes: [], emptyText: "No episodes yet — check back soon.", isMock: false, notMock: true, mockBanner: "" });
       }
       try {
         const api = host().wixApi;

package/templates/branded-lite/tier5-src/himi-branded-lite-reservations/index.ts

@@ -1,12 +1,10 @@
-// himi-branded-lite-reservations — branded-lite "My Reservations" worker with a
-// SAMPLE-DATA fallback (same pattern as the other branded-lite verticals). Reads
-// the member's real Wix Table Reservations (queryReservations); when the site has
-// no Table Reservations app / the member has none (the query errors — e.g. 404/428
-// — or returns empty), it substitutes representative SAMPLE reservations and flags
-// `isMock`, so the screen shows a clearly-labelled "Sample content" banner. Real
-// reservations always win the moment any exist. INTERACTIVE: tapping an upcoming
-// reservation cancels it — optimistic + best-effort cancelReservation (no-op on
-// sample rows).
+// himi-branded-lite-reservations — branded-lite "My Reservations" worker. Reads
+// the member's real Wix Table Reservations (queryReservations). A failed query is an
+// error with Retry (or Sign in when Wix refuses the visitor), an empty one is a real
+// empty state — never invented bookings labelled "tap to cancel". Sample rows
+// appear only in the host's explicit sample preview (branded-load-state.ts).
+// INTERACTIVE: tapping an upcoming reservation cancels it — optimistic + best-effort
+// cancelReservation (no-op on sample rows).
 //
 // RFC 0052 consumer: the list is a `himalaya.Agenda` — chronological, grouped
 // by LOCAL day under sticky headers. A reservation list is a diary, and the
@@ -14,12 +12,12 @@
 // no row knew what day the row above it was on. `Agenda` owns the day headers
 // and the time column, so a row carries only what is actually per-reservation.
 import { defineService } from "@himalaya/state";
+import { LOADING, loaded, loadFailed, type LoadCopy, type LoadFlags } from "../_shared/branded-load-state.js";
 import { queryReservations, cancelReservation, type WixReservation } from "@himalaya/wix-table-reservations";
 import { type CalendarEvent } from "@himalaya/time";
 
 interface Row { id: string; revision: string; title: string; subtitle: string; cancellable: boolean; canceled: boolean; start: string; raw: string }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   reservations: Row[];
   /** The Agenda wire shape, derived from `reservations` on every transition. */
   events: CalendarEvent[];
@@ -122,8 +120,17 @@ function mockRows(): Row[] {
   ];
 }
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return withEvents({ ...s, status: "ready", emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"}, mockRows());
+const COPY: LoadCopy<Row> = {
+  prefix: "reservations",
+  empty: "You don't have any reservations yet.",
+  error: "Your reservations couldn't be loaded.",
+  signIn: "Sign in to see your reservations.",
+  sample: mockRows,
+};
+
+/** Every settled load goes through withEvents so the Agenda never drifts from the rows. */
+function settle(s: S, next: Pick<S, "reservations" | "emptyText"> & LoadFlags): S {
+  return withEvents({ ...s, ...next }, next.reservations);
 }
 
 /** The reservation id out of a tap. `Agenda.onSelectEvent` dispatches
@@ -141,7 +148,7 @@ const svc = defineService<S, {
   load: (s: S) => Promise<S>;
   cancel: (s: S, p?: unknown) => Promise<S>;
 }>("himiBrandedReservations", {
-  state: { status: "loading", reservations: [], events: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+  state: { ...LOADING, reservations: [], events: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
@@ -149,12 +156,9 @@ const svc = defineService<S, {
         // to hand it chronological order rather than newest-first.
         const r = await queryReservations({ cursorPaging: { limit: 20 }, sort: [{ fieldName: "details.startDate", order: "ASC" }] });
         const reservations = (r.reservations ?? []).map(norm);
-        if (reservations.length) {
-          return withEvents({ ...s, status: "ready", emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true}, reservations);
-        }
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return settle(s, loaded("reservations", reservations, COPY));
+      } catch (err) {
+        return settle(s, loadFailed("reservations", err, COPY));
       }
     },
     // Cancel one upcoming reservation. Optimistic (marks it Canceled immediately);

package/templates/branded-lite/tier5-src/himi-branded-lite-reviews/index.ts

@@ -1,17 +1,15 @@
-// himi-branded-lite-reviews — branded-lite "Reviews" worker with a SAMPLE-DATA
-// fallback (same pattern as himi-branded-lite-coupons/-notifications/-loyalty).
-// Reads the real Wix Reviews (queryReviews, public/approved only); when the site
-// has no Reviews app / no reviews (the query errors — e.g. 404/428 — or returns
-// empty), it substitutes representative SAMPLE reviews and flags `isMock`, so the
-// screen shows a clearly-labelled "Sample content" banner. Real reviews always
-// win the moment any approved review exists.
+// himi-branded-lite-reviews — reads the site's approved Wix Reviews (queryReviews).
+// a failed query is an error with Retry (or Sign in when Wix refuses the
+// visitor) and an empty one is a real empty state — never sample rows presented as
+// the customer's own. Samples appear only in the host's explicit sample preview
+// (_shared/branded-load-state.ts).
 import { defineService } from "../_shared/collection-service.js";
+import { LOADING, loaded, loadFailed, type LoadCopy, type LoadFlags } from "../_shared/branded-load-state.js";
 import { queryReviews, type WixReview } from "@himalaya/wix-reviews";
 
 /** `rating` (0–5) feeds the row's Rating control (spoken "N out of 5"); `stars` stays for older descriptors. */
 interface Row { id: string; author: string; stars: string; rating: number; title: string; body: string }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   reviews: Row[]; emptyText: string;
   isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
    *  shows only when the site really has none, and the unavailable one only when the
@@ -48,22 +46,27 @@ const MOCK: Row[] = [
   { id: "sample-4", author: "Amit L.",   stars: "★★★★☆", rating: 4, title: "Solid",                body: "Good quality and quick service. Would order again." },
 ];
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", reviews: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
-}
+/** sample rows reach the screen ONLY in the host's explicit sample preview;
+ *  a failed or empty query is an honest error / empty state (branded-load-state.ts). */
+const COPY: LoadCopy<Row> = {
+  prefix: "reviews",
+  empty: "No reviews yet.",
+  error: "Reviews couldn't be loaded.",
+  signIn: "Sign in to see reviews.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedReviews", {
-  state: { status: "loading", reviews: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+  state: { ...LOADING, reviews: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
         const r = await queryReviews({ cursorPaging: { limit: 20 } });
         const raw = (r.reviews ?? r.results ?? []) as WixReview[];
         const reviews = raw.map(norm).filter((x) => x.title || x.body);
-        if (reviews.length) return { ...s, status: "ready", reviews, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return { ...s, ...loaded("reviews", reviews, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("reviews", err, COPY) };
       }
     },
   },