@wix/himalaya-cli 0.1525.0 → 0.1527.0

package/templates/podcast-creator/tier5-src/himi-events-rsvp/index.ts

@@ -1,5 +1,6 @@
+import { withOnlineWrites, offlineWritesEnabled } from "../_shared/online-actions.js";
 // Tier-5 bundle: himi-events — member RSVP flow.
-import { defineService } from "@himalaya/state";
+import { defineService as registerService } from "@himalaya/state";
 import { dispatch } from "@himalaya/dispatch";
 import { createRsvp, getEvent, type WixEvent } from "@himalaya/wix-events";
 import { displayName, getMyData, type WixMyData } from "@himalaya/wix-users";
@@ -125,6 +126,7 @@ function contactName(dataLine: string): { first: string; last: string } {
   return { first: parts[0], last: parts.slice(1).join(" ") };
 }
 
+const defineService = withOnlineWrites(registerService, ["rsvp", "signIn"], { derive, secretFields: ["password"] });
 const svc = defineService<S, {
   load: (s: S, arg?: unknown) => Promise<S>;
   setEmail: (s: S, arg?: unknown) => S;
@@ -202,16 +204,17 @@ const svc = defineService<S, {
       // Optimistic local write — the RSVP row lands in the cache before the Wix POST.
       const rsvpRow = (id: string): DbEntity => ({ id, eventId: s.id, firstName: name.first, lastName: name.last, email: guestEmail, status: "YES", title: s.title });
       const localId = s.id;
-      await cachePut(rsvpRow(localId));
+      if (!offlineWritesEnabled) await cachePut(rsvpRow(localId));
       try {
         const res = await createRsvp(s.id, name.first, name.last, guestEmail, "YES");
         // Reconcile the optimistic local id with the server-assigned rsvp id.
         const serverId = res.rsvp?.id;
-        if (serverId && serverId !== localId) { await cacheDrop(localId); await cachePut(rsvpRow(serverId)); }
+        if (offlineWritesEnabled) await cachePut(rsvpRow(serverId || localId));
+        else if (serverId && serverId !== localId) { await cacheDrop(localId); await cachePut(rsvpRow(serverId)); }
         rememberRsvp(s.id);
         return derive({ ...s, successMessage: copyParam("rsvp.successMessage", "You are going. Added to My Events."), message: "" });
       } catch (e) {
-        if (isBridgeUnavailable(e)) {
+        if (!offlineWritesEnabled && isBridgeUnavailable(e)) {
           // Offline / no bridge: the optimistic cache row already shows; queue the
           // write to replay (WriteQueue, idempotent) when connectivity returns.
           await queueWrite("tier5.himiEventsRsvp.rsvp", { id: s.id, firstName: name.first, lastName: name.last, email: guestEmail, status: "YES" });

package/templates/podcast-creator/tier5-src/himi-store-account/index.ts

@@ -26,6 +26,10 @@ interface AuthRouteInput {
   returnScreenId?: string;
   returnId?: string;
   returnChannelId?: string;
+  /** Standalone sign-in only: "1" when it was opened as a modal (sheet / cover). */
+  modal?: string;
+  /** Modal only: the tab whose stack the return screen opens on once the modal closes. */
+  returnTab?: string;
 }
 
 // The screen's boot input survives refresh; consuming it must survive too.
@@ -61,6 +65,12 @@ function authIntentFromArg(arg: unknown, prev: Pick<S, "authIntent" | "authConte
   };
 }
 
+/** How the standalone form leaves. A modal is closed: on web `back` pops the tab's stack,
+ *  not the modal. A pushed form goes back. */
+function leaveNav(): "dismiss" | "back" {
+  return routeInput().modal === "1" ? "dismiss" : "back";
+}
+
 /** Where a successful sign-in returns to, or null. Never Account itself — that would
  *  only push a second copy of the screen the member is already on. */
 function resumeTarget(s: Pick<S, "returnScreenId" | "returnId" | "returnChannelId">): { screenId: string; args?: Record<string, string> } | null {
@@ -78,11 +88,26 @@ function resumeTarget(s: Pick<S, "returnScreenId" | "returnId" | "returnChannelI
  *  On the standalone sign-in screen the target is pushed, not a `replace`: on iOS and
  *  Android `replace` resets the stack to its root, which would drop the screens the
  *  visitor came through. Back from the target shows the form again, and the form sends a
- *  member back on appear (settle). With no target the form goes back. */
+ *  member back on appear (settle). With no target the form goes back.
+ *
+ *  A modal form closes. A target pushed from here would open inside the modal (iOS, Android)
+ *  or under it (web), so a modal that names a `returnTab` hands the target to that tab: the
+ *  host closes the modal, then pushes it on that tab's stack (Account's member rows). A host
+ *  showing no such tab (a drawer, a narrow Mac window) drops that request whole, modal and
+ *  all, so the modal is also dismissed directly: it always closes, and the row opens where
+ *  the tab exists. With no `returnTab` it only closes, and the screen under it loads again —
+ *  the screen that opened the modal is the return target. */
 function resumeAfterAuth(next: S): S {
   const target = resumeTarget(next);
   if (!next.isMember) return next;
-  if (!target) return next.standalone ? navigate(next, { presentation: "back" }) : next;
+  const tab = routeInput().modal === "1" ? routeInput().returnTab ?? "" : "";
+  if (target && tab && next.standalone) {
+    routeInputConsumed = true;
+    void dispatch("himi.open", { presentation: "dismiss" });
+    const cleared = derive({ ...next, authIntent: "", authContextName: "", returnScreenId: "", returnId: "", returnChannelId: "" });
+    return navigate(cleared, target.args ? { tab, screenId: target.screenId, args: target.args } : { tab, screenId: target.screenId });
+  }
+  if (!target || routeInput().modal === "1") return next.standalone ? navigate(next, { presentation: leaveNav() }) : next;
   routeInputConsumed = true;
   const cleared = derive({ ...next, authIntent: "", authContextName: "", returnScreenId: "", returnId: "", returnChannelId: "" });
   return navigate(cleared, target);
@@ -96,11 +121,31 @@ function forwardToSignIn(next: S): S {
   if (!next.authIntent && !next.returnScreenId) return next;
   routeInputConsumed = true;
   const args: Record<string, string> = { mode: "signin" };
-  for (const key of ["authIntent", "authContextName", "returnScreenId", "returnId", "returnChannelId"] as const) {
-    if (next[key]) args[key === "authIntent" ? "intent" : key === "authContextName" ? "contextName" : key] = next[key];
+  for (const key of ["authIntent", "authContextName"] as const) {
+    if (next[key]) args[key === "authIntent" ? "intent" : "contextName"] = next[key];
+  }
+  return openSignIn(derive({ ...next, authIntent: "", authContextName: "", returnScreenId: "", returnId: "", returnChannelId: "" }),
+    args, resumeTarget(next));
+}
+
+/** Account sends a guest to the standalone sign-in screen, with `after`, the member screen to
+ *  open once signed in. With a `signInPresentation` appear param it opens as that modal, and
+ *  `after` goes on Account's own tab (`signInReturnTab`) when the modal closes; pushed, the form
+ *  pushes `after` itself (resumeAfterAuth). */
+function openSignIn(next: S, args: Record<string, string>, after: { screenId: string; args?: Record<string, string> } | null): S {
+  const screenId = next.signInScreen || "himi_sign_in";
+  const presentation = signInPresentationRequested;
+  const back: Record<string, string> = {};
+  if (after) {
+    back.returnScreenId = after.screenId;
+    if (after.args?.id) back.returnId = after.args.id;
+    if (after.args?.channelId) back.returnChannelId = after.args.channelId;
   }
-  return navigate(derive({ ...next, authIntent: "", authContextName: "", returnScreenId: "", returnId: "", returnChannelId: "" }),
-    { screenId: next.signInScreen, args });
+  if (!presentation) return navigate(next, { screenId, args: { ...args, ...back } });
+  const modalArgs: Record<string, string> = { ...args, modal: "1" };
+  // With no tab to open it on, a modal has no way to the member screen: it only closes.
+  if (after && signInReturnTabRequested) Object.assign(modalArgs, back, { returnTab: signInReturnTabRequested });
+  return navigate(next, { screenId, presentation, args: modalArgs });
 }
 
 /** After a load: the standalone sign-in screen sends a member back (a stale link, or a
@@ -128,8 +173,11 @@ function settle(next: S, arg: unknown, latest = true): S {
     // The appear refresh returns `_nav`, which every host applies — binaries from before
     // worker nav dispatch included. Only an arg-less load, whose result iOS
     // discards, dispatches.
-    if (strField(arg, "standalone") === "1") return navigate(cleared, { presentation: "back" });
-    void dispatch("himi.open", { presentation: "back" });
+    if (strField(arg, "standalone") === "1") return navigate(cleared, { presentation: leaveNav() });
+    // Not from a modal: nothing pushed over it comes back to it, and on iOS the closing modal's
+    // own screen reloads here once, after it has asked to close — a late dismiss would close
+    // whatever modal is open by then.
+    if (routeInput().modal !== "1") void dispatch("himi.open", { presentation: leaveNav() });
     return cleared;
   }
   // Account forwards only on an appear refresh: the boot `load()` has no params and its
@@ -180,6 +228,10 @@ let appliedSeq = 0;
 // The appear params belong to the worker session too, like the two flags above: a probe
 // dropped because the visitor typed must not take them with it.
 let signInScreenRequested = "";
+/** Account only: how it opens the standalone sign-in screen ("" = push). */
+let signInPresentationRequested: "" | "sheet" | "full_screen" = "";
+/** Account only: its tab, where a member screen opens after a modal sign-in. */
+let signInReturnTabRequested = "";
 let standaloneRequested = false;
 let pollIdentityRequested = false;
 // Bumped by every mode switch, so a dropped probe never puts back a mode the visitor left.
@@ -210,6 +262,9 @@ function appearConfig(s: S, arg: unknown): AppearConfig {
     passwordDraft = "";
   }
   signInScreenRequested ||= strField(arg, "signInScreen") || s.signInScreen;
+  const presentation = strField(arg, "signInPresentation");
+  if (presentation === "sheet" || presentation === "full_screen") signInPresentationRequested = presentation;
+  signInReturnTabRequested ||= strField(arg, "signInReturnTab");
   // Only the sign-in screen's route carries `mode`, so it marks the form from the boot load on.
   standaloneRequested ||= s.standalone || appearing || (!routeInputConsumed && !!routeInput().mode);
   pollIdentityRequested ||= s.pollIdentity || strField(arg, "pollIdentity") === "1";
@@ -676,6 +731,7 @@ const svc = defineService<S, {
   signOut: (s: S) => Promise<S>;
   sync: (s: S) => Promise<S | undefined>;
   openMember: (s: S, arg?: unknown) => Promise<S>;
+  leave: (s: S) => S;
   restorePublish: (s: S) => S;
   iapRestore: (s: S) => Promise<undefined>;
 }>("himiStoreAccount", {
@@ -756,7 +812,8 @@ const svc = defineService<S, {
       return "next" in r ? r.next : undefined;
     },
     // A row to a member-only screen shows to a guest too. A member opens it; a guest signs
-    // in first and the sign-in screen replaces itself with it, so Back returns here.
+    // in first, and the sign-in screen then opens the row's screen — as a modal, by closing
+    // and pushing it on this tab (openSignIn) — so Back returns here either way.
     openMember: async (s, arg): Promise<S> => {
       const screenId = strField(arg, "screenId");
       if (!screenId) return s;
@@ -764,8 +821,10 @@ const svc = defineService<S, {
       // From the state as it is now: a probe may have landed during the identity read.
       const now = svc.getState();
       if (member) return navigate(now, { screenId });
-      return navigate(now, { screenId: now.signInScreen || "himi_sign_in", args: { mode: "signin", returnScreenId: screenId } });
+      return openSignIn(now, { mode: "signin" }, { screenId });
     },
+    // The standalone form's Continue: leaves the form the way it was opened.
+    leave: (s) => navigate(s, { presentation: leaveNav() }),
     // Typing means any focus request was delivered: clear the tokens (safe while mounted, since
     // bumpToken never repeats), so a visit rarely ends — and a pooled form rarely reopens —
     // holding one.

package/templates/podcast-creator-owner/tier5-src/_shared/collection-service.ts

@@ -1,3 +1,4 @@
+import { withOnlineWrites } from './online-actions.js';
 import { defineService as register, type ServiceDefinition } from '@himalaya/state';
 import { COLLECTIONS, COLLECTION_CHROME_MIN_ITEMS, initialCollection, normalizeCollection, projectCollection, collectionId, collectionActionsLabel, type CollectionRow } from './collection-contract.js';
 import { localPreferences, type PreferenceRuntime } from './local-preferences.js';
@@ -331,6 +332,8 @@ export function decorateCollection(name: string, def: { state: State; actions?:
  * reducer and reads the private controller snapshot, never an SDUI payload. */
 export function defineBackendCollection<S extends object, Row extends object>(name: string, options: {
   register?: typeof register;
+  /** Explicit mutation preflight; unrelated collection services keep their current reducers. */
+  onlineWrites?: boolean;
   /** Revalidate already opened pages on navigation return; explicit refresh resets. */
   restorePagesOnLoad?: boolean;
   /** The load action's argument (onAppear params beyond `copy`), before the query runs — for a
@@ -350,7 +353,8 @@ export function defineBackendCollection<S extends object, Row extends object>(na
     controller: controller as unknown as BackendCollection['controller'],
     apply: (state, page) => options.apply(state as S, page as unknown as CollectionQueryState<Row>) as State,
   });
-  const handle = (options.register ?? register)(name, definition);
+  const registerService = options.onlineWrites ? withOnlineWrites(options.register ?? register, ['confirmCancel', 'confirmOperation', 'retryOperation', 'commitWrite'], { messageFields: ['actionMessage'] }) : (options.register ?? register);
+  const handle = registerService(name, definition);
   // Registration restored the state a cold boot saved: the page it showed is this run's, before the first load. Only
   // when the service's own rows came back with it: a bundle that keeps them out of the restore (its `notHydrated`)
   // starts its first load as before, never from rows it chose not to restore. Rows that came back empty are the

package/templates/podcast-creator-owner/tier5-src/_shared/online-actions.ts

@@ -0,0 +1,76 @@
+import { connectivity, defineService as register, type ServiceDefinition } from '@himalaya/state';
+
+// Template generation enables this behavior only in the selected two starter families.
+export const offlineWritesEnabled = false;
+
+export const offlineWriteMessage = 'You’re offline. Connect to save this change, then submit it again.';
+
+/** The guard runs before the reducer: entered values survive and no optimistic
+ * changes, success state, or queued writes can occur. It never submits on reconnect. */
+export function offlineWriteState<S extends object>(state: S): S {
+  const next: Record<string, unknown> = { ...state, error: offlineWriteMessage, message: offlineWriteMessage };
+  for (const key of ['saving', 'isSaving', 'submitting', 'isSubmitting', 'adding', 'added', 'bookingInFlight']) {
+    if (key in next) next[key] = false;
+  }
+  for (const key of ['savedMessage', 'successMessage']) {
+    if (key in next) next[key] = '';
+  }
+  // A saved/favourited item is business state, not a submission-success flag.
+  return next as S;
+}
+
+interface OfflineWriteOptions<S> {
+  derive?: (state: S) => S;
+  /** Exempt only non-mutating branches of a registered action. */
+  requiresConnectivity?: (action: string, state: S, argument?: unknown) => boolean;
+  messageFields?: readonly string[] | ((action: string) => readonly string[]);
+  draftFields?: readonly string[] | Readonly<Record<string, string>>;
+  secretFields?: readonly string[];
+}
+
+export function withOnlineWrites<S extends object>(registerService: typeof register, names: readonly string[], options: OfflineWriteOptions<S> = {}): typeof register {
+  if (!offlineWritesEnabled) return registerService;
+  return ((name: string, definition: ServiceDefinition<Record<string, unknown>>) => {
+    let currentState: (() => Record<string, unknown>) | undefined;
+    const handle = registerService(name, {
+      ...definition,
+      notHydrated: [...new Set([...(definition.notHydrated ?? []), ...(options.secretFields ?? [])])],
+      actions: Object.fromEntries(Object.entries(definition.actions ?? {}).map(([action, reduce]) => [action,
+        (state: Record<string, unknown>, ...args: never[]) => {
+          if (!names.includes(action)) return reduce(state, ...args);
+          if (options.requiresConnectivity?.(action, state as S, args[0]) === false) return reduce(state, ...args);
+          const fields = typeof options.messageFields === 'function' ? options.messageFields(action) : options.messageFields ?? ['message'];
+          if (connectivity().online) {
+            let cleared = false;
+            for (const field of ['error', 'message', ...fields]) {
+              if (state[field] === offlineWriteMessage) { state[field] = ''; cleared = true; }
+            }
+            // Keep the runtime's state object: reducers may mutate it and return undefined.
+            const result = reduce(state, ...args);
+            if (!cleared) return result;
+            // Publish cleared feedback even for a void reducer. An async completion must
+            // keep any newer state published by another action while it was awaiting.
+            const finish = (next: Record<string, unknown> | undefined) => next === undefined ? currentState?.() ?? state : next;
+            return result && typeof (result as Promise<unknown>).then === 'function'
+              ? Promise.resolve(result).then(finish)
+              : finish(result as Record<string, unknown> | undefined);
+          }
+          const draft = { ...state };
+          const argument = args[0] as Record<string, unknown> | undefined;
+          const draftFields = options.draftFields ?? [];
+          const entries = Array.isArray(draftFields) ? draftFields.map(key => [key, key]) : Object.entries(draftFields);
+          for (const [key, source] of entries) {
+            if (argument && key in state && typeof argument[source] === typeof state[key]) draft[key] = argument[source];
+          }
+          for (const key of options.secretFields ?? []) draft[key] = '';
+          const feedback = Object.fromEntries(fields.map(key => [key, offlineWriteMessage]));
+          let next = { ...offlineWriteState(draft), ...feedback };
+          if (options.derive) next = options.derive(next as S) as Record<string, unknown>;
+          return { ...next, ...feedback };
+        },
+      ])),
+    });
+    if (typeof handle.getState === 'function') currentState = () => handle.getState();
+    return handle;
+  }) as typeof register;
+}

package/templates/portfolio-creative/dev/index.ts

@@ -2173,8 +2173,10 @@ const SCREENS = runtimeSetting({
                                     "actionId": "himi.open",
                                     "params": {
                                       "screenId": "himi_sign_in",
-                                      "mode": "signin"
-                                    }
+                                      "mode": "signin",
+                                      "modal": "1"
+                                    },
+                                    "presentation": "sheet"
                                   }
                                 }
                               }
@@ -2192,8 +2194,10 @@ const SCREENS = runtimeSetting({
                                     "actionId": "himi.open",
                                     "params": {
                                       "screenId": "himi_sign_in",
-                                      "mode": "register"
-                                    }
+                                      "mode": "register",
+                                      "modal": "1"
+                                    },
+                                    "presentation": "sheet"
                                   }
                                 }
                               }
@@ -3395,6 +3399,8 @@ const SCREENS = runtimeSetting({
             "memberAccountLinks": "1",
             "restorePurchases": "1",
             "signInScreen": "himi_sign_in",
+            "signInPresentation": "sheet",
+            "signInReturnTab": "profile",
             "pollIdentity": "1",
             "cartCount": "1",
             "copy": "{\"account.subtitle\":\"Orders, RSVPs and saved content in one place.\",\"storeAccount.authBody\":\"Sign in to continue — cart and RSVPs stay with you.\",\"storeAccount.authBodyRegister\":\"Create a member account to continue — cart and RSVPs stay with you.\"}"
@@ -3670,8 +3676,10 @@ const SCREENS = runtimeSetting({
                             "params": {
                               "screenId": "himi_sign_in",
                               "mode": "signin",
-                              "returnScreenId": "himi_account_settings"
-                            }
+                              "returnScreenId": "himi_account_settings",
+                              "modal": "1"
+                            },
+                            "presentation": "sheet"
                           }
                         }
                       },
@@ -5581,8 +5589,7 @@ const SCREENS = runtimeSetting({
                           "style": "primary",
                           "fullWidth": true,
                           "action": {
-                            "actionId": "nav.back",
-                            "presentation": "back"
+                            "actionId": "tier5.himiStoreAccount.leave"
                           }
                         }
                       }
@@ -5623,7 +5630,7 @@ const SCREENS = runtimeSetting({
       "declaredCapabilities": [
         "wix_api"
       ],
-      "minBinaryVersion": "0.2.0",
+      "minBinaryVersion": "1.7.0",
       "bundleVersion": "0.0.1"
     }
   },
@@ -6490,8 +6497,10 @@ const SCREENS = runtimeSetting({
                               "screenId": "himi_sign_in",
                               "mode": "signin",
                               "intent": "profile",
-                              "returnScreenId": "himi_view_profile"
-                            }
+                              "returnScreenId": "himi_view_profile",
+                              "modal": "1"
+                            },
+                            "presentation": "sheet"
                           }
                         }
                       }
@@ -15317,8 +15326,10 @@ const SCREENS = runtimeSetting({
                               "screenId": "himi_sign_in",
                               "mode": "signin",
                               "intent": "orders",
-                              "returnScreenId": "himi_orders"
-                            }
+                              "returnScreenId": "himi_orders",
+                              "modal": "1"
+                            },
+                            "presentation": "sheet"
                           }
                         }
                       }
@@ -15951,8 +15962,10 @@ const SCREENS = runtimeSetting({
                               "screenId": "himi_sign_in",
                               "mode": "signin",
                               "intent": "addresses",
-                              "returnScreenId": "himi_addresses"
-                            }
+                              "returnScreenId": "himi_addresses",
+                              "modal": "1"
+                            },
+                            "presentation": "sheet"
                           }
                         }
                       }
@@ -17008,8 +17021,10 @@ const SCREENS = runtimeSetting({
                               "screenId": "himi_sign_in",
                               "mode": "signin",
                               "intent": "addresses",
-                              "returnScreenId": "himi_address"
-                            }
+                              "returnScreenId": "himi_address",
+                              "modal": "1"
+                            },
+                            "presentation": "sheet"
                           }
                         }
                       }
@@ -17679,8 +17694,10 @@ const SCREENS = runtimeSetting({
                               "screenId": "himi_sign_in",
                               "mode": "signin",
                               "intent": "wallet",
-                              "returnScreenId": "himi_wallet"
-                            }
+                              "returnScreenId": "himi_wallet",
+                              "modal": "1"
+                            },
+                            "presentation": "sheet"
                           }
                         }
                       }
@@ -18177,8 +18194,10 @@ const SCREENS = runtimeSetting({
                                   "action": {
                                     "actionId": "himi.open",
                                     "params": {
-                                      "screenId": "himi_sign_in"
-                                    }
+                                      "screenId": "himi_sign_in",
+                                      "modal": "1"
+                                    },
+                                    "presentation": "sheet"
                                   }
                                 }
                               },
@@ -20780,8 +20799,10 @@ const SCREENS = runtimeSetting({
                               "screenId": "himi_sign_in",
                               "mode": "signin",
                               "intent": "post",
-                              "returnScreenId": "himi_create_post"
-                            }
+                              "returnScreenId": "himi_create_post",
+                              "modal": "1"
+                            },
+                            "presentation": "sheet"
                           }
                         }
                       }
@@ -28627,8 +28648,10 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                     "params": {
                       "screenId": "himi_sign_in",
                       "returnScreenId": "himi_order",
-                      "returnId": "$service:himiBrandedOrder.id"
-                    }
+                      "returnId": "$service:himiBrandedOrder.id",
+                      "modal": "1"
+                    },
+                    "presentation": "sheet"
                   }
                 }
               },
@@ -32145,8 +32168,10 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                             "params": {
                               "screenId": "himi_sign_in",
                               "mode": "signin",
-                              "intent": "rsvp"
-                            }
+                              "intent": "rsvp",
+                              "modal": "1"
+                            },
+                            "presentation": "sheet"
                           }
                         }
                       },

package/templates/portfolio-creative/tier5-src/_shared/collection-service.ts

@@ -1,3 +1,4 @@
+import { withOnlineWrites } from './online-actions.js';
 import { defineService as register, type ServiceDefinition } from '@himalaya/state';
 import { COLLECTIONS, COLLECTION_CHROME_MIN_ITEMS, initialCollection, normalizeCollection, projectCollection, collectionId, collectionActionsLabel, type CollectionRow } from './collection-contract.js';
 import { localPreferences, type PreferenceRuntime } from './local-preferences.js';
@@ -331,6 +332,8 @@ export function decorateCollection(name: string, def: { state: State; actions?:
  * reducer and reads the private controller snapshot, never an SDUI payload. */
 export function defineBackendCollection<S extends object, Row extends object>(name: string, options: {
   register?: typeof register;
+  /** Explicit mutation preflight; unrelated collection services keep their current reducers. */
+  onlineWrites?: boolean;
   /** Revalidate already opened pages on navigation return; explicit refresh resets. */
   restorePagesOnLoad?: boolean;
   /** The load action's argument (onAppear params beyond `copy`), before the query runs — for a
@@ -350,7 +353,8 @@ export function defineBackendCollection<S extends object, Row extends object>(na
     controller: controller as unknown as BackendCollection['controller'],
     apply: (state, page) => options.apply(state as S, page as unknown as CollectionQueryState<Row>) as State,
   });
-  const handle = (options.register ?? register)(name, definition);
+  const registerService = options.onlineWrites ? withOnlineWrites(options.register ?? register, ['confirmCancel', 'confirmOperation', 'retryOperation', 'commitWrite'], { messageFields: ['actionMessage'] }) : (options.register ?? register);
+  const handle = registerService(name, definition);
   // Registration restored the state a cold boot saved: the page it showed is this run's, before the first load. Only
   // when the service's own rows came back with it: a bundle that keeps them out of the restore (its `notHydrated`)
   // starts its first load as before, never from rows it chose not to restore. Rows that came back empty are the

package/templates/portfolio-creative/tier5-src/_shared/online-actions.ts

@@ -0,0 +1,76 @@
+import { connectivity, defineService as register, type ServiceDefinition } from '@himalaya/state';
+
+// Template generation enables this behavior only in the selected two starter families.
+export const offlineWritesEnabled = false;
+
+export const offlineWriteMessage = 'You’re offline. Connect to save this change, then submit it again.';
+
+/** The guard runs before the reducer: entered values survive and no optimistic
+ * changes, success state, or queued writes can occur. It never submits on reconnect. */
+export function offlineWriteState<S extends object>(state: S): S {
+  const next: Record<string, unknown> = { ...state, error: offlineWriteMessage, message: offlineWriteMessage };
+  for (const key of ['saving', 'isSaving', 'submitting', 'isSubmitting', 'adding', 'added', 'bookingInFlight']) {
+    if (key in next) next[key] = false;
+  }
+  for (const key of ['savedMessage', 'successMessage']) {
+    if (key in next) next[key] = '';
+  }
+  // A saved/favourited item is business state, not a submission-success flag.
+  return next as S;
+}
+
+interface OfflineWriteOptions<S> {
+  derive?: (state: S) => S;
+  /** Exempt only non-mutating branches of a registered action. */
+  requiresConnectivity?: (action: string, state: S, argument?: unknown) => boolean;
+  messageFields?: readonly string[] | ((action: string) => readonly string[]);
+  draftFields?: readonly string[] | Readonly<Record<string, string>>;
+  secretFields?: readonly string[];
+}
+
+export function withOnlineWrites<S extends object>(registerService: typeof register, names: readonly string[], options: OfflineWriteOptions<S> = {}): typeof register {
+  if (!offlineWritesEnabled) return registerService;
+  return ((name: string, definition: ServiceDefinition<Record<string, unknown>>) => {
+    let currentState: (() => Record<string, unknown>) | undefined;
+    const handle = registerService(name, {
+      ...definition,
+      notHydrated: [...new Set([...(definition.notHydrated ?? []), ...(options.secretFields ?? [])])],
+      actions: Object.fromEntries(Object.entries(definition.actions ?? {}).map(([action, reduce]) => [action,
+        (state: Record<string, unknown>, ...args: never[]) => {
+          if (!names.includes(action)) return reduce(state, ...args);
+          if (options.requiresConnectivity?.(action, state as S, args[0]) === false) return reduce(state, ...args);
+          const fields = typeof options.messageFields === 'function' ? options.messageFields(action) : options.messageFields ?? ['message'];
+          if (connectivity().online) {
+            let cleared = false;
+            for (const field of ['error', 'message', ...fields]) {
+              if (state[field] === offlineWriteMessage) { state[field] = ''; cleared = true; }
+            }
+            // Keep the runtime's state object: reducers may mutate it and return undefined.
+            const result = reduce(state, ...args);
+            if (!cleared) return result;
+            // Publish cleared feedback even for a void reducer. An async completion must
+            // keep any newer state published by another action while it was awaiting.
+            const finish = (next: Record<string, unknown> | undefined) => next === undefined ? currentState?.() ?? state : next;
+            return result && typeof (result as Promise<unknown>).then === 'function'
+              ? Promise.resolve(result).then(finish)
+              : finish(result as Record<string, unknown> | undefined);
+          }
+          const draft = { ...state };
+          const argument = args[0] as Record<string, unknown> | undefined;
+          const draftFields = options.draftFields ?? [];
+          const entries = Array.isArray(draftFields) ? draftFields.map(key => [key, key]) : Object.entries(draftFields);
+          for (const [key, source] of entries) {
+            if (argument && key in state && typeof argument[source] === typeof state[key]) draft[key] = argument[source];
+          }
+          for (const key of options.secretFields ?? []) draft[key] = '';
+          const feedback = Object.fromEntries(fields.map(key => [key, offlineWriteMessage]));
+          let next = { ...offlineWriteState(draft), ...feedback };
+          if (options.derive) next = options.derive(next as S) as Record<string, unknown>;
+          return { ...next, ...feedback };
+        },
+      ])),
+    });
+    if (typeof handle.getState === 'function') currentState = () => handle.getState();
+    return handle;
+  }) as typeof register;
+}

package/templates/portfolio-creative/tier5-src/himi-branded-lite-address/index.ts

@@ -1,9 +1,10 @@
+import { withOnlineWrites } from "../_shared/online-actions.js";
 // Tier-5 bundle: Branded Lite — add / edit one saved address (himi_address).
 //
 // No `id` nav param → a new address; `?id=` → that address, prefilled. Save writes it
 // to the member's address book (@himalaya/wix-ecom) and goes back to My Addresses,
 // which reloads on appear. Edit also offers Remove, behind an in-screen confirm.
-import { defineService, navigate } from "@himalaya/state";
+import { defineService as registerService, navigate } from "@himalaya/state";
 import {
   createMemberAddress,
   deleteMemberAddress,
@@ -176,6 +177,7 @@ async function remove(state: State): Promise<State> {
   }
 }
 
+const defineService = withOnlineWrites(registerService, ["save", "remove"], { derive });
 const svc = defineService<State, {
   load: (state: State, arg?: unknown) => Promise<State>;
   retry: (state: State) => Promise<State>;

package/templates/portfolio-creative/tier5-src/himi-branded-lite-addresses/index.ts

@@ -1,10 +1,11 @@
+import { withOnlineWrites } from "../_shared/online-actions.js";
 // Tier-5 bundle: Branded Lite — My Addresses (the member's saved address book).
 //
 // The same book the site's Members Area "My Addresses" page and checkout use
 // (addresses-web, see @himalaya/wix-ecom listMemberAddresses). A member sees every
 // saved address, picks the default, and removes one after an in-screen confirm;
 // add/edit open himi_address. A guest gets the shared member gate.
-import { defineService, navigate } from "@himalaya/state";
+import { defineService as registerService, navigate } from "@himalaya/state";
 import {
   deleteMemberAddress,
   listMemberAddresses,
@@ -152,6 +153,7 @@ async function write(state: State, run: () => Promise<unknown>, done: string, fa
   }
 }
 
+const defineService = withOnlineWrites(registerService, ["setDefault", "remove"], { derive });
 const svc = defineService<State, {
   load: (state: State, arg?: unknown) => Promise<State>;
   retry: (state: State) => Promise<State>;

package/templates/portfolio-creative/tier5-src/himi-branded-lite-cart/index.ts

@@ -1,3 +1,5 @@
+import { withOnlineWrites } from "../_shared/online-actions.js";
+import { defineService as registerState } from "@himalaya/state";
 import { getStoreProduct } from "../_shared/himi-store.js";
 import { iapPriceCopy } from "../_shared/iap-worker.js";
 import { withIapPresentation } from "../_shared/iap-presentation.js";
@@ -378,6 +380,7 @@ function couponDetails(result: unknown): { id: string; code: string } {
 
 let cartPricing: IapCommerce;
 const defineService = withIapPresentation<State>({
+  register: withOnlineWrites(registerState, ["remove", "increment", "decrement", "checkout", "beginPromo", "applyPromo", "removePromo"], { derive, messageFields: action => action.includes("Promo") ? ["promoError"] : ["checkoutHint"] }),
   onCreate: commerce => { cartPricing = commerce; },
   prefix: "cart", transientKeys: ["items", "subtotal", "promoBusy"], contentActions: ["load", "remove", "increment", "decrement"],
   items: state => state.items.flatMap(row => row.catalogReference?.catalogItemId ? [{ reference: { kind: "storesProduct", id: row.catalogReference.catalogItemId }, commerceDisplayPrice: row.commerceTotal ?? row.total }] : []),