@wix/himalaya-cli 0.1032.0 → 0.1034.0

package/templates/branded-lite/tier5-src/_shared/branded-load-state.ts

@@ -0,0 +1,106 @@
+// Load-state honesty for the branded-lite vertical workers.
+//
+// These workers used to answer every failed or empty query with representative SAMPLE
+// rows — discount codes, gift-card balances, invoices, reservations, inbox messages —
+// under a "Sample content" banner. On a customer build that is invented data presented
+// as the customer's own: a code that does not exist, a balance in the wrong currency, an
+// "Overdue" invoice, a booking labelled "tap to cancel". The banner did not make it
+// honest; the rows were still the first thing a visitor read.
+//
+// The rule now:
+//   • query FAILED     → status "error" with a customer sentence, a Retry, and — when
+//                        Wix refused an anonymous visitor (401) — a Sign in path instead;
+//   • query was EMPTY  → status "ready", no rows, the vertical's own empty sentence;
+//   • sample rows      → ONLY when the host explicitly asked for sample data (the web
+//                        preview's sample data mode, `__himiOwnerPreview: "sample"`).
+//                        Never on a device, never as a fallback.
+//
+// Every field here is flat and boolean-gated because descriptors can only
+// `hiddenWhen(<path>)` on a TRUE value: `notErrored` hides the error card, `noSignIn`
+// hides the sign-in CTA, `signInRequired` hides Retry when retrying cannot help.
+import { copyParam } from "./himi-copy.js";
+
+export interface LoadFlags {
+  status: "loading" | "ready" | "error";
+  /** The customer-facing failure sentence; "" unless status is "error". */
+  error: string;
+  signInRequired: boolean;
+  notErrored: boolean;
+  /** hiddenWhen gate for a loading skeleton. */
+  notLoading: boolean;
+  /** Loading or failed — gates content that has nothing to say in either. */
+  busy: boolean;
+  noSignIn: boolean;
+  isMock: boolean;
+  notMock: boolean;
+  notMockEmpty: boolean;
+  notMockUnavailable: boolean;
+}
+
+export const LOADING: LoadFlags = {
+  status: "loading", error: "", signInRequired: false, notErrored: true, notLoading: false, busy: true, noSignIn: true,
+  isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true,
+};
+
+const READY: LoadFlags = { ...LOADING, status: "ready", notLoading: true, busy: false };
+
+/** Did the HOST ask for sample data? Only the web preview's sample mode does; a native
+ *  build, a visitor preview and a live owner preview never carry it. */
+export function samplesRequested(): boolean {
+  const input = (globalThis as { himalaya?: { input?: Record<string, unknown> } }).himalaya?.input;
+  return input?.__himiOwnerPreview === "sample";
+}
+
+/** Wix refused an ANONYMOUS visitor: signing in is the fix, not retrying. A 403 is not
+ *  this — it also answers "feature not installed" and a signed-in member without the
+ *  permission, where a Sign in button leads nowhere — so it stays a Retry-able failure. */
+export function needsSignIn(err: unknown): boolean {
+  const msg = String((err as { message?: unknown })?.message ?? err ?? "");
+  return /\b401\b|unauthori[sz]ed|unauthenticated/i.test(msg);
+}
+
+export interface LoadCopy<T> {
+  /** The copy namespace (`giftCards`, `coupons`, …) — keys resolve through copyParam. */
+  prefix: string;
+  /** Shown when the site genuinely has none. */
+  empty: string;
+  /** Shown when the query failed. */
+  error: string;
+  /** Shown when Wix refused the visitor (member-only data). */
+  signIn: string;
+  /** Sample rows for the explicit sample preview ONLY. */
+  sample: () => T[];
+}
+
+type Rows<K extends string, T> = { [P in K]: T[] } & { emptyText: string } & LoadFlags;
+
+/** A query answered. Rows win; an empty answer is a real empty state. */
+export function loaded<K extends string, T>(key: K, rows: T[], copy: LoadCopy<T>): Rows<K, T> {
+  if (rows.length) return { ...READY, [key]: rows, emptyText: "" } as Rows<K, T>;
+  if (samplesRequested()) return sampleRows(key, copy, "empty");
+  return { ...READY, [key]: [], emptyText: copyParam(`${copy.prefix}.emptyText`, copy.empty) } as Rows<K, T>;
+}
+
+/** A query threw. Never rows the customer did not create. */
+export function loadFailed<K extends string, T>(key: K, err: unknown, copy: LoadCopy<T>): Rows<K, T> {
+  if (samplesRequested()) return sampleRows(key, copy, "unavailable");
+  const signIn = needsSignIn(err);
+  return {
+    ...READY,
+    status: "error",
+    [key]: [],
+    emptyText: "",
+    error: signIn ? copyParam(`${copy.prefix}.signInText`, copy.signIn) : copyParam(`${copy.prefix}.errorText`, copy.error),
+    signInRequired: signIn,
+    notErrored: false,
+    busy: true,
+    noSignIn: !signIn,
+  } as Rows<K, T>;
+}
+
+function sampleRows<K extends string, T>(key: K, copy: LoadCopy<T>, reason: "empty" | "unavailable"): Rows<K, T> {
+  return {
+    ...READY, [key]: copy.sample(), emptyText: "",
+    isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable",
+  } as Rows<K, T>;
+}

package/templates/branded-lite/tier5-src/_shared/collection-contract.ts

@@ -30,6 +30,9 @@ export interface CollectionConfig {
    * `screenId` opens that screen with the row id; without it the verb reuses the
    * row's own tap action (the detail screen that owns the verb). */
   primaryVerb?: { label: string; screenId?: string };
+  /** A state field the DOMAIN narrows `rows` by (e.g. a category picker). While it is set,
+   *  zero rows is a filtered result, not an empty source. */
+  narrowedBy?: string;
 }
 /** At or below this many records, with no query/filter narrowing them and no further
  * page, the list/grid toggle, Refine, chips, search and count are noise. */
@@ -41,7 +44,7 @@ export const COLLECTIONS: Record<string, CollectionConfig> = {
     defaultFilter: 'value:Upcoming', searchPlaceholder: 'Exact booking ID', filterValues: ['Upcoming', 'Past', 'Cancelled'],
     sortLabels: { default: 'Soonest', az: 'Oldest', za: 'Latest' } },
   himiEvents: { rows: 'results', title: 'title', subtitle: 'dateLine', image: 'image', view: 'grid', backendQuery: true, searchPlaceholder: 'Exact event title', filterValues: ['Upcoming', 'Past'], sortLabels: { default: 'Date', az: 'Title A–Z', za: 'Title Z–A' }, primaryVerb: { label: 'Register' } },
-  himiBlogFeed: { rows: 'posts', title: 'title', subtitle: 'excerpt', image: 'image', filter: 'category', filterValuesFrom: 'categories', view: 'grid' },
+  himiBlogFeed: { rows: 'posts', title: 'title', subtitle: 'excerpt', image: 'image', filter: 'category', filterValuesFrom: 'categories', view: 'grid', narrowedBy: 'selectedCategoryId' },
   himiOwnerLiteProducts: { rows: 'products', title: 'name', subtitle: 'price', image: 'image', view: 'grid', backendQuery: true },
   himiOwnerModules: { instanceInput: 'module', rows: 'rows', title: 'title', subtitle: 'subtitle', image: 'image', filter: 'statusLabel', view: 'list', paged: true, reviewAction: 'prepareRecord', reviewSelectedAction: 'prepareSelected' },
   himiOwnerLiteServices: { rows: 'services', title: 'name', subtitle: 'subtitle', view: 'list', backendQuery: true, searchPlaceholder: 'Service name starts with…' },

package/templates/branded-lite/tier5-src/_shared/collection-service.ts

@@ -122,14 +122,38 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     const errored = s.status === 'error' || s.isErrored === true || s.errored === true || backendState?.status === 'error';
     const domainError = typeof s.error === 'string' ? s.error.trim() : '';
     const queryError = typeof backendState?.error === 'string' ? backendState.error.trim() : '';
-    const errorMessage = queryError || domainError || copyParam('collection.loadError', 'This collection could not load. Try again.');
+    // Some domains carry their failure sentence in `emptyText` (portfolio, podcasts);
+    // the screen folds that node into this block, so keep the domain's own words.
+    const domainEmptyError = errored && typeof s.emptyText === 'string' ? s.emptyText.trim() : '';
+    const errorMessage = queryError || domainError || domainEmptyError || copyParam('collection.loadError', 'This collection could not load. Try again.');
     const canRetry = !!backend || typeof def.actions?.refresh === 'function' || typeof def.actions?.load === 'function' || typeof def.actions?.collectionRetry === 'function';
+    // Wix refused the visitor: retrying cannot help, signing in can.
+    const signInRequired = errored && s.signInRequired === true;
+    // "the source has nothing" and "your filter matched nothing" are
+    // different states. Only the second may offer "Clear filters", and the list chrome
+    // (view, refine, chips, counter, search) means nothing over a source with no rows.
+    // Loaded-row collections hold the whole source in `rows`, so zero rows IS an empty
+    // source. A backend query returns only matches, so zero rows is source-empty only
+    // when nothing narrowed it.
+    // Anything the customer (or the domain) narrowed the result by. While narrowed, zero rows
+    // is "your filter matched nothing" and the controls that got them here must stay.
+    // The DOMAIN's own filter (config.narrowedBy, e.g. blog category) narrowed the rows: the
+    // domain owns that empty state and its clear action. The shared "Clear filters" block
+    // cannot reset a domain filter, so it never shows for one.
+    const domainNarrowed = !!config.narrowedBy && !!s[config.narrowedBy];
     // A default view is what the screen opens on; anything else is the member's own
     // narrowing, which keeps the chrome (and the Clear that undoes it) on screen.
     // "All" and the collection's own default (e.g. Upcoming) are both un-narrowed: Clear
     // resets to "All", so showing it on either would offer a reset that changes nothing.
-    const narrowed = !!prefs.query.trim() || (prefs.filter !== 'all' && prefs.filter !== initialCollection(config).filter);
-    const hideChrome = !narrowed && !s.nextCursor && projected.loaded < COLLECTION_CHROME_MIN_ITEMS;
+    const narrowed = !!prefs.query.trim() || (prefs.filter !== 'all' && prefs.filter !== initialCollection(config).filter) || domainNarrowed;
+    const sourceEmpty = !loading && !errored && rows.length === 0 &&
+      (!(backend && config.backendQuery) || !narrowed) && !domainNarrowed;
+    const emptySourceText = (typeof s.emptyText === 'string' && s.emptyText.trim()) || copyParam('collection.emptySource', 'Nothing here yet');
+    // Chrome is noise over a small un-narrowed list (fewer than COLLECTION_CHROME_MIN_ITEMS
+    // records, no further page), over an empty source, and before the FIRST load or an
+    // un-narrowed failure. A re-query while typing keeps it (and the search field's focus).
+    const hideChrome = (!narrowed && !s.nextCursor && projected.loaded < COLLECTION_CHROME_MIN_ITEMS)
+      || sourceEmpty || ((loading || errored) && rows.length === 0 && !narrowed);
     return { ...s, collection: { ...prefs, ...projected,
       hideChrome, noActiveCriteria: !narrowed,
       viewName, viewMessage, saveMessage, noSavedViews: prefs.savedViews.length === 0,
@@ -138,8 +162,15 @@ export function decorateCollection(name: string, def: { state: State; actions?:
       noPageError: s.pageError !== true,
       noOffline: s.fromCache !== true,
       noError: !errored,
-      noRetry: !canRetry,
+      noRetry: !canRetry || signInRequired,
+      noSignIn: !signInRequired,
+      errorTitle: signInRequired ? copyParam('collection.signInTitle', 'Sign in to see this') : copyParam('collection.loadErrorTitle', 'This collection could not load'),
       errorMessage,
+      noLoading: !loading,
+      // De-dup against a domain that paints its OWN empty block (screen-kit emptyBlock is
+      // gated on the domain's top-level `noEmpty`): only one empty state ever shows.
+      noEmptySource: !sourceEmpty || s.noEmpty === false,
+      emptySourceText,
       hideList: prefs.view !== 'list', hideGrid: prefs.view !== 'grid',
       hideComfortable: prefs.density !== 'comfortable', hideCompact: prefs.density !== 'compact',
       selectingLabel: prefs.selecting ? copyParam('collection.done', 'Done') : copyParam('collection.select', 'Select'),
@@ -147,7 +178,7 @@ export function decorateCollection(name: string, def: { state: State; actions?:
       cannotSaveSelected: !prefs.selectedIds.length || prefs.selectedIds.some(id => !rows.some(row => collectionId(row) === id)),
       filtersPresented, previewPresented: !!previewId, preview: projected.items.filter(row => row.collectionId === previewId),
       persistenceLabel: persisted.available ? copyParam('collection.onDevice', 'Saved on this device') : copyParam('collection.sessionOnly', 'Choices last for this session'),
-      noEmpty: loading || errored || projected.items.length > 0,
+      noEmpty: loading || errored || sourceEmpty || domainNarrowed || projected.items.length > 0,
       summary: backend && config.backendQuery
         ? (s.fromCache ? copyParam('collection.cached', 'Saved offline · may be outdated')
           : typeof s.total === 'number' ? `${projected.items.length} / ${s.total} ${copyParam('collection.results', 'results')}`

package/templates/branded-lite/tier5-src/_shared/empty-flags.ts

@@ -0,0 +1,33 @@
+// Empty-collection flags for descriptors.
+//
+// A bound Grid/LazyList with zero rows still renders a zero-height box, and a stack
+// allocates its `spacing` between CHILDREN, not between painted children — so every
+// empty list left a full gap of blank on the screen (the measure pass's `dead-gap`, on
+// iOS and Android as much as on web). `hiddenWhen` hides on a TRUE scalar only, and an
+// empty array is not one, so a descriptor cannot gate a list on its own rows.
+//
+// `withEmptyFlags(def, { rows: "noRows" })` derives `noRows = rows is empty` into the
+// initial state and after EVERY action (sync or async), so a builder can write
+// `hiddenWhen(grid(...), "$service:svc.noRows")` without each reducer remembering to.
+type State = Record<string, unknown>;
+type Action = (s: State, ...args: unknown[]) => unknown;
+
+export function withEmptyFlags<D extends { state: object; actions?: object }>(def: D, flags: Record<string, string>): D {
+  const derive = <T>(s: T): T => {
+    if (!s || typeof s !== "object") return s;
+    const out = { ...(s as State) };
+    for (const [rows, flag] of Object.entries(flags)) {
+      const v = out[rows];
+      out[flag] = !Array.isArray(v) || v.length === 0;
+    }
+    return out as T;
+  };
+  const actions: Record<string, Action> = {};
+  for (const [name, action] of Object.entries((def.actions ?? {}) as Record<string, Action>)) {
+    actions[name] = (s, ...args) => {
+      const r = action(s, ...args);
+      return r && typeof (r as Promise<unknown>).then === "function" ? (r as Promise<unknown>).then(derive) : derive(r);
+    };
+  }
+  return { ...def, state: derive(def.state), actions } as D;
+}

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

@@ -1,17 +1,16 @@
-// himi-branded-lite-badges — branded-lite "Badges" worker with a SAMPLE-DATA
-// fallback (same pattern as the other branded-lite verticals). Reads the site's
-// real Wix Badges catalog (list); when the site has no Badges app / no badges
-// (the query errors — e.g. 404/428 — or returns empty), it substitutes
-// representative SAMPLE badges and flags `isMock`, so the screen shows a clearly-
-// labelled "Sample content" banner. Real badges always win the moment any exist.
+// himi-branded-lite-badges — reads the site's real Wix Badges catalog (query).
+// 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";
 // v4 (the live Badges service) has no plain GET list — only the query endpoint;
 // GET /badges/v4/badges 404s. v1-v3 are back-compat proxies that 404 here too.
 import { query as queryBadges, type WixBadge } from "@himalaya/wix-badges";
 
 interface Row { id: string; title: string; subtitle: string }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   badges: 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
@@ -32,21 +31,26 @@ const MOCK: Row[] = [
   { id: "sample-vip",         title: "VIP",             subtitle: "A valued long-standing customer." },
 ];
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", badges: 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: "badges",
+  empty: "No badges yet.",
+  error: "Badges couldn't be loaded.",
+  signIn: "Sign in to see community badges.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedBadges", {
-  state: { status: "loading", badges: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+  state: { ...LOADING, badges: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
         const r = await queryBadges({ query: { cursorPaging: { limit: 50 } } });
         const badges = (r.badges ?? []).map(norm);
-        if (badges.length) return { ...s, status: "ready", badges, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return { ...s, ...loaded("badges", badges, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("badges", err, COPY) };
       }
     },
   },

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

@@ -1,15 +1,14 @@
-// himi-branded-lite-coupons — branded-lite coupons/offers LIST worker with a
-// SAMPLE-DATA fallback (same pattern as himi-branded-lite-forum). Reads the real
-// Wix Coupons (queryCoupons); when the site has no Coupons app / no coupons (the
-// query errors — e.g. 404/428 — or returns empty), it substitutes representative
-// SAMPLE offers and flags `isMock`, so the screen shows a clearly-labelled
-// "Sample content" banner. Real data always wins the moment coupons exist.
+// himi-branded-lite-coupons — reads the site's real Wix Coupons (queryCoupons).
+// 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 { queryCoupons, type WixCoupon } from "@himalaya/wix-coupons";
 
 interface Row { id: string; name: string; subtitle: string }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   coupons: 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
@@ -30,25 +29,26 @@ const MOCK: Row[] = [
   { id: "sample-loyal10", name: "Loyalty reward — $10 off", subtitle: "Code: LOYAL10 · members only" },
 ];
 
-/** The sample fallback, shared by both arms so neither can drift from the other — this
- *  worker inlined it twice, which is how a rename reached the constants and missed the
- *  uses. */
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", coupons: MOCK, 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: "coupons",
+  empty: "No offers right now — check back soon.",
+  error: "Offers couldn't be loaded.",
+  signIn: "Sign in to see offers available to you.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedCoupons", {
-  state: { status: "loading", coupons: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+  state: { ...LOADING, coupons: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
         const r = await queryCoupons({ paging: { limit: 30 } } as never);
         const coupons = (((r as unknown as { coupons?: WixCoupon[] }).coupons) ?? []).map(norm);
-        if (coupons.length) return { ...s, status: "ready", coupons, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return { ...s, ...loaded("coupons", coupons, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("coupons", err, COPY) };
       }
     },
   },

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

@@ -1,15 +1,14 @@
-// himi-branded-lite-donations — branded-lite "Donations" worker with a SAMPLE-DATA
-// fallback (same pattern as the other branded-lite verticals). Reads the site's real
-// Wix Donations campaigns (queryDonationCampaigns); when the site has no Donations app /
-// no campaigns (the query errors — e.g. 404/428 — or returns empty), it substitutes
-// representative SAMPLE campaigns and flags `isMock`, so the screen shows a clearly-
-// labelled "Sample content" banner. Real campaigns always win the moment any exist.
+// himi-branded-lite-donations — reads the site's real Wix Donations campaigns (queryDonationCampaigns).
+// 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 { queryDonationCampaigns, type WixDonationCampaign } from "@himalaya/wix-donations";
 
 interface Row { id: string; title: string; subtitle: string }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   campaigns: 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
@@ -40,21 +39,26 @@ const MOCK: Row[] = [
   { id: "sample-relief", title: "Winter Relief Fund",     subtitle: "Goal: $5,000 · Goal reached" },
 ];
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", campaigns: 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: "donations",
+  empty: "No donation campaigns right now.",
+  error: "Donation campaigns couldn't be loaded.",
+  signIn: "Sign in to see donation campaigns.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedDonations", {
-  state: { status: "loading", campaigns: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+  state: { ...LOADING, campaigns: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
         const r = await queryDonationCampaigns({ query: { cursorPaging: { limit: 20 } } });
         const campaigns = (r.donationCampaigns ?? []).filter((c) => c.archived !== true).map(norm);
-        if (campaigns.length) return { ...s, status: "ready", campaigns, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return { ...s, ...loaded("campaigns", campaigns, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("campaigns", err, COPY) };
       }
     },
   },

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

@@ -1,18 +1,16 @@
-// himi-branded-lite-forms — branded-lite "Forms" worker with a SAMPLE-DATA fallback
-// (same pattern as the other branded-lite verticals). Reads the site's real Wix Forms
-// (queryForms, which REQUIRES a namespace filter — a bare query is answered
-// `400 MISSING_NAMESPACE_FILTER` for every site, #2769); when the site has no Forms
-// app (403/404/428) or has no forms, it substitutes representative SAMPLE forms and
-// flags `isMock`, so the screen shows a clearly-labelled "Sample content" banner.
-// A query that FAILS for any other reason is reported as a failure — sample content
-// there would state "this site has none yet", which the app never established.
-// Real forms always win the moment any exist.
+// himi-branded-lite-forms — reads the site's real Wix Forms (queryForms, which
+// REQUIRES a namespace filter — a bare query is answered `400 MISSING_NAMESPACE_FILTER`
+// for every site, #2769).
+// 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 { queryForms, type WixForm } from "@himalaya/wix-forms";
 
 interface Row { id: string; title: string; subtitle: string }
-interface S {
-  status: "loading" | "ready" | "error";
+interface S extends LoadFlags {
   forms: 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
@@ -35,39 +33,33 @@ function norm(f: WixForm): Row {
   return { id: f.id || "form", title, subtitle: parts.join(" · ") };
 }
 
-/** Two banners, because the sample rows answer two different questions and only one of
- *  them is a statement about the customer's site.
- *
- *  There used to be one banner, "this site has no forms yet", shown whenever the rows were
- *  samples — including when the query had FAILED. A site WITH forms got told it had none.
- *  The sample fallback itself is deliberate and covered by the renderer's offline test,
- *  which keeps these verticals showing labelled sample content rather than a blank screen.
- *  So what was wrong was never the samples — it was claiming to know something the app had
- *  not established. */
+/** Preview-only sample forms (see COPY below). */
 const MOCK: Row[] = [
   { id: "sample-contact",   title: "Contact Us",       subtitle: "4 fields · Published" },
   { id: "sample-subscribe", title: "Newsletter Signup", subtitle: "2 fields · Published" },
   { id: "sample-feedback",  title: "Feedback",          subtitle: "5 fields · Published" },
 ];
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", forms: 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: "forms",
+  empty: "No forms available yet.",
+  error: "Forms couldn't be loaded.",
+  signIn: "Sign in to see available forms.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedForms", {
-  state: { status: "loading", forms: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+  state: { ...LOADING, forms: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
         const r = await queryForms({ filter: { namespace: FORMS_NAMESPACE }, paging: { limit: 50 } });
         const forms = (r.forms ?? []).map(norm);
-        if (forms.length) return { ...s, status: "ready", forms, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
-        return mockState(s, "empty");
-      } catch {
-        // The samples still render — a blank screen helps nobody and this vertical
-        // deliberately ships a fallback — but the banner no longer asserts the site is
-        // empty, because a failed query established no such thing.
-        return mockState(s, "unavailable");
+        return { ...s, ...loaded("forms", forms, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("forms", err, COPY) };
       }
     },
   },

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

@@ -4,13 +4,14 @@
 // codegen — the real consumer app (wix-private/wix-one-app-pro-gallery) fetches it
 // from the photography one-app viewer REST endpoint. So this worker mirrors that: it
 // GETs the site's galleries from that endpoint through the raw wixApi bridge (absolute
-// URL + the app's WixApiCapability auth), with the sample-data fallback. When the site
-// has no Pro Gallery / it isn't readable (errors or empty), it substitutes SAMPLE
-// galleries and flags `isMock`. Real galleries always win the moment any exist.
+// URL + the app's WixApiCapability auth). a failed query is an error with
+// Retry (or Sign in), an empty one a real empty state; sample galleries appear only
+// in the host's explicit sample preview (_shared/branded-load-state.ts).
 //
 // Endpoint verbatim from wix-one-app-pro-gallery/src/constants (API_BASE_URL) +
 // api/photo-gallery-api.js (fetchGalleries).
 import { defineService } from "../_shared/collection-service.js";
+import { LOADING, loaded, loadFailed, type LoadCopy, type LoadFlags } from "../_shared/branded-load-state.js";
 
 const GALLERIES_URL =
   "https://www.wix.com/_api/photography-one-app-viewer/galleries?itemsPerGallery=1&offset=0&limit=30&withHidden=false&useNew=true";
@@ -22,8 +23,7 @@ function wixApi(): WixApi | null {
 
 interface RawGallery { id?: string; name?: string; totalItemsCount?: number }
 interface Row { id: string; title: string; subtitle: string }
-interface S {
-  status: "loading" | "ready";
+interface S extends LoadFlags {
   galleries: 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,17 +45,23 @@ const MOCK: Row[] = [
   { id: "sample-team",   title: "The Team",     subtitle: "9 photos" },
 ];
 
-function mockState(s: S, reason: "empty" | "unavailable"): S {
-  return { ...s, status: "ready", galleries: 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: "galleries",
+  empty: "No galleries yet — check back soon.",
+  error: "Galleries couldn't be loaded.",
+  signIn: "Sign in to see galleries.",
+  sample: () => MOCK.map((r) => ({ ...r })),
+};
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedGalleries", {
-  state: { status: "loading", galleries: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
+  state: { ...LOADING, galleries: [], emptyText: "" },
   actions: {
     load: async (s) => {
       try {
         const api = wixApi();
-        if (!api) return mockState(s, "unavailable");
+        if (!api) return { ...s, ...loadFailed("galleries", new Error("Wix bridge unavailable"), COPY) };
         const res = (await api.call("GET", GALLERIES_URL)) as
           { galleries?: RawGallery[] } | RawGallery[] | { data?: { galleries?: RawGallery[] } };
         // Accept {galleries:[...]}, a top-level array, or a {data:{galleries}} envelope.
@@ -64,10 +70,9 @@ const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedGalleri
           (Array.isArray(res) ? (res as RawGallery[]) : undefined) ??
           (res as { data?: { galleries?: RawGallery[] } })?.data?.galleries ?? [];
         const galleries = raw.map(norm);
-        if (galleries.length) return { ...s, status: "ready", galleries, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
-        return mockState(s, "empty");
-      } catch {
-        return mockState(s, "unavailable");
+        return { ...s, ...loaded("galleries", galleries, COPY) };
+      } catch (err) {
+        return { ...s, ...loadFailed("galleries", err, COPY) };
       }
     },
   },