@wix/himalaya-cli 0.1572.0 → 0.1573.0

package/guides/one-app-to-himi-app.md

@@ -501,6 +501,53 @@ mapping rows are research leads: inspect the current CLI's component, SDK and
 template contracts before using them. A previously empty row does not prove the
 feature is impossible today.
 
+### Standalone launch tab
+
+When the reconstructed navigation has a tab bar, preserve the app's actual tab
+IDs, source order, labels, icons and content. Do not keep the starter template's
+`home` ID or rename the first tab to `home` merely to match a shell default.
+An actual source tab named `home` is valid; the name is not reserved or required.
+A tab ID is not a `screenId`: a Community tab can use `id: "community"` with
+`screenId: "community_home"` and its visible Community label.
+For navigation with no tab bar, do not add a synthetic Home tab.
+
+Validate that tab IDs are non-empty and unique. Keep the source-to-target lookup,
+every `tabId` in
+`navigation.linkableScreens`, tab-selection actions and worker navigation requests
+consistent with the actual destination IDs, including detail screens that belong
+to the first tab. Remove stale template references instead of renaming the app's
+tabs to make them match. `himi validate --strict` rejects empty or duplicate tab
+IDs and linkable `tabId` references outside the selectable primary navigation
+on enabled surfaces when chrome lists are configured. An auxiliary drawer row is
+not a compact responsive tab: use an empty/default-stack `tabId` for a pushed
+screen without an owning tab. Explicit primary drawer/sidebar modes and declared
+surface overrides use their own destinations. This config-only membership check
+does not prove source fidelity, dynamic navigation requests, or deep-link behavior
+on every surface; verify those independently. For example,
+the navigation fragment for a Community-first app is:
+
+```json
+{
+  "tabBar": {
+    "items": [
+      { "id": "community", "screenId": "community_home", "label": "Community", "icon": "people" },
+      { "id": "profile", "screenId": "member_profile", "label": "Profile", "icon": "person" }
+    ]
+  },
+  "linkableScreens": [
+    { "screenId": "community_home", "isPublic": true, "paramKeys": [], "parentScreenId": "", "tabId": "community" },
+    { "screenId": "community_post", "isPublic": true, "paramKeys": ["id"], "parentScreenId": "community_home", "tabId": "community" }
+  ]
+}
+```
+
+Current standalone bottom-tab chrome selects the first visible configured tab
+when its stored selection is unknown. Do not infer this fallback for sidebar or
+responsive-wide chrome: verify its launch selection independently. A stored
+template default such as `home` must not override the app's navigation or leave
+it blank. If a binary does not handle the app's actual IDs, fix or update that
+shell and report the incompatibility; do not disguise it by renaming the first tab.
+
 ## 2. Write the reconstruction plan and resolve gaps
 
 Write `.himi/one-app/reconstruction-plan.md` before scaffolding. Describe the app
@@ -931,6 +978,13 @@ transactions against fixtures only. Read-only live checks verify the correct sit
 entity selection and runtime identity; they do not authorize placing orders,
 bookings, payments, form submissions or destructive updates during validation.
 
+For a tabbed migration, cold-launch the standalone app without a launch-screen
+override or incoming deep link. Confirm the first tab is selected and displays
+content. Then switch tabs and open a detail link belonging to the first tab;
+confirm it selects that tab and opens the intended screen. A hosted preview alone
+does not establish standalone launch behavior. Record an unavailable native check
+as unverified in the migration report.
+
 The UX audit requires app-specific network fixtures. `himi test --record` records
 only boot-time reads with the app's visitor identity, then crawls hermetically.
 Review its recorded/refused requests; do not run a source getter known to mutate

package/guides/sdk-reference.json

@@ -2771,7 +2771,7 @@
         "name": "OrderFailureCode",
         "kind": "type",
         "jsdoc": "",
-        "decl": "export type OrderFailureCode =\n  | \"notEnabled\" | \"notConfigured\" | \"signInRequired\" | \"unsupportedItem\" | \"notAppleRoute\"\n  | \"storageUnavailable\" | \"approvalRequired\" | \"orderClosed\" | \"orderRefused\" | \"chargeFailed\"\n  | \"paymentRefused\" | \"paymentHeld\" | \"alreadyOwned\" | \"paymentInProgress\" | \"productChanged\"\n  | \"invalidAssociation\" | \"needsSupport\" | \"unavailable\" | \"sessionChanged\" | \"outcomeUnknown\";"
+        "decl": "export type OrderFailureCode =\n  | \"notEnabled\" | \"notConfigured\" | \"signInRequired\" | \"unsupportedItem\" | \"notAppleRoute\"\n  | \"storageUnavailable\" | \"approvalRequired\" | \"orderClosed\" | \"orderRefused\" | \"chargeFailed\"\n  | \"paymentRefused\" | \"paymentHeld\" | \"alreadyOwned\" | \"paymentInProgress\" | \"productChanged\"\n  | \"sitePaymentUnavailable\" | \"invalidAssociation\" | \"needsSupport\" | \"unavailable\" | \"sessionChanged\" | \"outcomeUnknown\";"
       },
       {
         "name": "PaymentAccess",
@@ -2849,7 +2849,7 @@
         "name": "IapPurchaseCopy",
         "kind": "interface",
         "jsdoc": "/** Labels from the screen's copy pack; the shared layer only chooses between them. */",
-        "decl": "export interface IapPurchaseCopy {\n  buy: string;\n  buyAnother?: string;\n  processing: string;\n  awaitingApproval: string;\n  unavailable: string;\n  signInRequired: string;\n  retry: string;\n  priceChanged: string;\n  support: string;\n}"
+        "decl": "export interface IapPurchaseCopy {\n  buy: string;\n  buyAnother?: string;\n  processing: string;\n  awaitingApproval: string;\n  unavailable: string;\n  signInRequired: string;\n  retry: string;\n  /** Optional for existing SDK consumers; the app supplies a localized recovery message. */\n  sitePaymentUnavailable?: string;\n  priceChanged: string;\n  support: string;\n}"
       },
       {
         "name": "IapPurchaseFields",
@@ -25560,13 +25560,37 @@
         "jsdoc": "",
         "decl": "export interface WixListFeedItemsResponse {\n  feedItems: WixFeedItem[];\n  profiles?: WixFeedProfile[];\n  nextPageCursor?: string;\n}"
       },
+      {
+        "name": "WixFeedPageOptions",
+        "kind": "interface",
+        "jsdoc": "/** Read controls shared by the source's single-group and central feeds. */",
+        "decl": "export interface WixFeedPageOptions extends WixCallOptions {\n  /** Opaque server cursor; pass it back unchanged when loading the next page. */\n  cursor?: string;\n  invalidatePermissionsCache?: boolean;\n}"
+      },
+      {
+        "name": "WixGroupFeedOptions",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixGroupFeedOptions extends WixFeedPageOptions {\n  topicId?: string;\n}"
+      },
+      {
+        "name": "WixCentralFeedOptions",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixCentralFeedOptions extends WixFeedPageOptions {\n  withSuggestedPosts?: boolean;\n  /** Omit to use the central-feed service's default representation. */\n  contentType?: \"DRAFTJS\";\n}"
+      },
       {
         "name": "listFeedItems",
         "kind": "function",
-        "jsdoc": "/**\n * List a group's activity feed — GET\n * https://social.wix.com/serverless/mobile/feed/v4/feedPosts (the ENRICHED read the\n * real mobile app uses). Each item carries content (Ricos blocks), commentsCount, and\n * reactionsList (count = length); the response's top-level `profiles[]` resolves each\n * item's author.id → userName + profileImage. Verified live (200). Replaces the lean\n * GET /api/v1/feed/items read, which omitted counts + author.\n *\n * @scope member — verified live with a signed-in member session; visitor/anonymous\n * readability of a public group's feed is unconfirmed.\n */",
-        "decl": "export function listFeedItems(groupId: string, limit = 20, options?: WixCallOptions): Promise<WixListFeedItemsResponse>;",
+        "jsdoc": "/**\n * List one group's activity feed. Mirrors wix-one-app-feed getFeedPosts:\n * containerId + Groups appDefId + feedType=all + contentType=DRAFTJS, with optional\n * topic and opaque paging cursor. Existing site/cache options remain per-call.\n * Reactions lists must not be treated as authoritative totals.\n *\n * @scope member — verified live with a signed-in member session; visitor readability\n * depends on group permissions and is not established by the central-feed probe.\n */",
+        "decl": "export function listFeedItems(groupId: string, limit = 20, options?: WixGroupFeedOptions): Promise<WixListFeedItemsResponse>;",
         "scope": "member"
       },
+      {
+        "name": "listCentralFeedItems",
+        "kind": "function",
+        "jsdoc": "/**\n * List the site's combined feed, rather than substituting a selected group's feed.\n * Mirrors wix-one-app-feed getCentralFeedPosts: there is no containerId or appDefId.\n * Authentication and business selection belong to the bridge (or per-call `site`).\n *\n * Source: wix-one-app-feed@6ef53170e94e27349d2a6c1cf08038b078d86228,\n * src/services/feed-api.ts. A real Visitor read returned 200 with posts and a cursor.\n * That establishes the server contract only: native consumers need a core release with the exact read-route guard, and\n * production web still refuses social.wix.com. This SDK method does\n * not change those policies or establish membership/write permission. Consumers must\n * surface a transport refusal; they must not substitute a group directory or empty feed.\n */",
+        "decl": "export function listCentralFeedItems(limit = 20, options?: WixCentralFeedOptions): Promise<WixListFeedItemsResponse>;"
+      },
       {
         "name": "createFeedItem",
         "kind": "function",

package/guides/webview-page-sdk.md

@@ -94,7 +94,28 @@ every message none of them claims, including a handler registered directly on
 `himalaya.webview.onPageMessage` after `@himalaya/webview` loaded).
 
 ```ts
-import { emitToPage, onPageLifecycle, onPageRequest, openPageStream } from "@himalaya/webview";
+import { defineService } from "@himalaya/state";
+import { emitToPage, onPageLifecycle, onPageRequest, openPageStream, type PageStream } from "@himalaya/webview";
+
+// The worker has NO setTimeout / setInterval on any renderer. A stream that produces over time
+// is paced by the host clock: an action returns a `_poll`, and each tick sends the next chunk.
+const watching = new Set<PageStream>();
+let armed = false; // re-arming a live id with `immediate` fires an extra tick at once — arm once
+const steps = defineService("steps", {
+  state: {},
+  actions: {
+    arm: (s) => ({ ...s, _poll: { id: "steps", intervalMs: 1000, action: "steps.tick", immediate: true } }),
+    tick: (s) => {
+      for (const stream of watching) {
+        if (stream.closed) watching.delete(stream); // ended, or the page broke out of its loop
+        else stream.next({ steps: Math.random() });
+      }
+      if (watching.size) return s;
+      armed = false;
+      return { ...s, _poll: { id: "steps", stop: true } };
+    },
+  },
+});
 
 onPageRequest("nano", {
   // (args, ctx) → value | promise. ctx = { instanceId, requestId, active }.
@@ -102,8 +123,8 @@ onPageRequest("nano", {
   // Return a stream handle to answer with many chunks.
   "steps.watch": (_args, ctx) => {
     const stream = openPageStream(ctx.instanceId, ctx.requestId);
-    const timer = setInterval(() => stream.next({ steps: Math.random() }), 1000);
-    stream.onCancel(() => clearInterval(timer)); // the page broke out of its loop
+    watching.add(stream);
+    if (!armed) { armed = true; void steps.arm(); }
     return stream;
   },
 });
@@ -112,6 +133,9 @@ emitToPage("*", "nano.theme.changed", { dark: true }); // or one instance id
 const off = onPageLifecycle(({ instanceId, state }) => console.log(instanceId, state)); // mounted … unmounted
 ```
 
+A timer in a worker is not a style choice: `setInterval` here throws `Can't find variable` on the
+device, and the page sees the request fail (`_poll`: [Tier-5 guide](tier-5-add-a-screen.md#refresh-on-a-cadence-with-_poll-the-worker-has-no-clock)).
+
 - `ctx.instanceId` is the WebView the **host** says the request came from; a page-sent `iid` is
   ignored. `ctx.active` is live: `false` between `inactive` and `active` lifecycle events.
 - A namespace — and an exposed capability id — follows the capability-id pattern
@@ -255,3 +279,44 @@ The page is served at `/web/webview-sdk.html`. Its companion worker is
 probes. Safe probes run on load.
 Verbs that prompt, write, or open system UI stay allowlisted and are not called. Streaming
 helpers that return a live object stay on the worker.
+
+## Embedding worker-bridged WebViews
+
+A Tier-5 SDUI screen embeds any number of `WebView` nodes that talk to the **owning screen's
+worker** over the same channel: set `bridge: "worker"` on the node, declare `"webview"`
+in the screen's `logic_bundle`, and give each widget an explicit `instance_id` (inside a
+`LazyList`/`Carousel` item template it must be item-derived, e.g. `"row-$item.id"`). Untrusted or
+LLM-generated inline HTML additionally wants `origin_isolation: "per_instance"` (its own origin +
+storage per widget), `frame_policy: "content"` (top frame pinned, bridge main-frame-only),
+`bridge_security: { profile: "app_content" }` (multi-line-friendly caps) and `console_forwarding`.
+The host injects the page client at document start, so the page imports nothing; an app alias
+(`inject_js_document_start: "window.demoSdk = himalaya.demo;"`) runs after it, and the platform
+knows no app names. On web (phase 1), only an app-controlled **cross-origin `url`** page listed in
+`allowed_origins` is bridged; an inline (`srcdoc`) widget stays unbridged and the worker hears
+`mounted` with `detail: { bridged: false, reason: "web_srcdoc_unbridged" }` — show a fallback.
+
+A complete shape to copy — the demo app's **Embedded widgets** screen (`demo_app_embedded_widgets`)
+is built exactly this way:
+
+- three isolated inline widgets in a `Carousel` with `live_window: 1`, so only the current widget
+  and its neighbours are mounted (swiping to widget 3 unmounts widget 1), plus one bridged
+  cross-origin `url` page — all served by **one** worker;
+- the worker answers `onPageRequest("demo", { echo, bump, stream })`: a request, a per-instance
+  counter that answers with `emitToPage(ctx.instanceId, "demo.tick", n)`, and a 5-chunk stream the
+  page can stop (`break` out of its loop), paced by a host `_poll` as above;
+- `muted_path`, `active_path` and one widget's `reload_key_path` bound to worker state, and an
+  `onPageLifecycle` handler that shows each widget's last state;
+- each widget keeps its own `localStorage` counter, which survives a relaunch and is never visible
+  to its neighbours.
+
+Test such a screen by the document, not only by lifecycle envelopes: put state in a widget's page
+(an echo reply), swipe away and back, and check the state survived where the widget should have
+stayed mounted. **Crash recovery:** when a widget's content process dies, the host sends `crashed`
+and then remounts it (`reloaded`). On iOS and macOS each widget has its own content process, so the
+page exhausting memory (the demo's "Crash widget 3" does) kills only that widget; killing the
+`com.apple.WebKit.WebContent` process serving it by hand on a simulator triggers the same two
+envelopes. **On Android, don't use a memory hog:** one renderer process serves every WebView of the
+app — the screen's own worker included — so the hog takes them all down, and repeated renderer
+crashes exhaust the worker's recovery budget. Trigger it by hand instead: kill the app's sandboxed
+WebView process (`adb shell ps -A | grep sandboxed_process`, then `adb shell kill <pid>`) and watch
+for `crashed` then `reloaded`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1572.0",
+  "version": "0.1573.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "20229381643935ec0f9390addc404f459d7040e7dfd5b634ab41385c"
+  "falconPackageHash": "39a44e1a057f7d34899d550863397025bfdec7b4f241a6e45b677246"
 }

package/templates/beauty-salon/tier5-src/_shared/iap-worker.ts

@@ -4,6 +4,7 @@
 // SDK; this only supplies the copy and the hydration reset.
 import { hostSessionFromGlobal, type IapPriceCopy } from "@himalaya/iap";
 import type { IapCommerce, IapPurchaseCopy, IapRestoreResult } from "@himalaya/iap-checkout";
+import { paymentSetupMessage } from "./payment-setup.js";
 import { copyParam, copyTemplate } from "./himi-copy.js";
 
 /** Price labels from the screen's copy pack (`<prefix>.priceLoadingText`, …). */
@@ -25,6 +26,7 @@ export function iapPurchaseCopy(prefix: string): IapPurchaseCopy {
     awaitingApproval: copyParam(`${prefix}.purchaseAwaitingApprovalText`, "Waiting for approval"),
     unavailable: copyParam(`${prefix}.purchaseTemporarilyUnavailableText`, "Purchasing is temporarily unavailable."),
     signInRequired: copyParam(`${prefix}.purchaseSignInText`, "Sign in to buy."),
+    sitePaymentUnavailable: paymentSetupMessage(prefix),
     retry: copyParam(`${prefix}.purchaseRetryText`, "Something went wrong. Try again."),
     priceChanged: copyParam(`${prefix}.purchasePriceChangedText`, "The price changed. Check it and try again."),
     support: copyParam(`${prefix}.purchaseSupportText`, "We couldn't finish this purchase. Contact support."),

package/templates/beauty-salon/tier5-src/_shared/payment-setup.ts

@@ -0,0 +1,6 @@
+import { copyParam } from "./himi-copy.js";
+
+/** No provider or country guess: Wix only established that online payment is unavailable. */
+export function paymentSetupMessage(prefix: string): string {
+  return copyParam(`${prefix}.paymentSetupUnavailable`, "This site is not accepting online payments. Go back or contact the business for other payment options.");
+}

package/templates/beauty-salon/tier5-src/himi-booking-time/index.ts

@@ -1,3 +1,4 @@
+import { paymentSetupMessage } from "../_shared/payment-setup.js";
 import { withOnlineWrites, offlineWritesEnabled } from "../_shared/online-actions.js";
 // Tier-5 bundle: himi-booking — availability and member booking.
 import { defineService as registerService, navigate } from "@himalaya/state";
@@ -9,7 +10,7 @@ import { dispatch } from "@himalaya/dispatch";
 import { bookSchedule, bookSlot, getService, queryServiceAvailability, registerToWaitlist, type WixBookingSlotFull, type WixSelectedPaymentOption, type WixService } from "@himalaya/wix-bookings";
 import { createCheckout, createOrder } from "@himalaya/wix-ecom";
 import { createRedirectSession, type WixSlot } from "@himalaya/wix-redirects";
-import { payCashierOrder } from "@himalaya/checkout";
+import { isPaymentSetupFailure, payCashierOrder } from "@himalaya/checkout";
 import { hostedCheckoutOpener, isHostedWorker } from "../_shared/hosted-checkout.js";
 import { session as wixPlatformSession } from "@himalaya/wix-platform";
 import { displayName, getMyData, type WixMyData } from "@himalaya/wix-users";
@@ -1587,10 +1588,12 @@ async function bookSelectedIn(s: S): Promise<S> {
           ? copyParam("time.coursePaymentCancelled", "Payment cancelled — your course booking wasn't confirmed. Try again.")
           : copyParam("time.paymentCancelled", "Payment cancelled — your booking wasn't confirmed. Pick a time to try again.") });
       }
+      if (isPaymentSetupFailure(pay)) return derive({ ...s, bookingInFlight: false, message: paymentSetupMessage("time") });
       return derive({ ...s, bookingInFlight: false, message: s.isCourse
         ? copyParam("time.coursePaymentFailed", "Payment couldn't be completed. Try again.")
         : copyParam("time.paymentFailed", "Payment couldn't be completed. Pick another time or try again.") });
-    } catch {
+    } catch (error) {
+      if (isPaymentSetupFailure(error)) return derive({ ...s, bookingInFlight: false, message: paymentSetupMessage("time") });
       return derive({ ...s, bookingInFlight: false, message: s.isCourse
         ? copyParam("time.courseCheckoutFailed", "Checkout could not start. Try again.")
         : copyParam("time.checkoutFailed", "Checkout could not start. Pick another time or try again.") });

package/templates/beauty-salon/tier5-src/himi-branded-lite-cart/index.ts

@@ -1,3 +1,4 @@
+import { paymentSetupMessage } from "../_shared/payment-setup.js";
 import { withOnlineWrites } from "../_shared/online-actions.js";
 import { defineService as registerState } from "@himalaya/state";
 import { getStoreProduct } from "../_shared/himi-store.js";
@@ -7,7 +8,7 @@ import { withIapPresentation } from "../_shared/iap-presentation.js";
 import { type IapCommerce, classifyCart } from "@himalaya/iap-checkout";
 import { addCouponToCurrentCart, calculateCurrentCart, createCheckoutFromCurrentCart, getCurrentCart, removeCouponFromCurrentCart, removeLineItemsFromCurrentCart, updateLineItemsQuantity, type WixCartDetail, type WixCartLineItemDetail } from "@himalaya/wix-ecom";
 import { createRedirectSession } from "@himalaya/wix-redirects";
-import { payCashierOrder } from "@himalaya/checkout";
+import { isPaymentSetupFailure, payCashierOrder } from "@himalaya/checkout";
 import { hostedCheckoutOpener, isHostedWorker } from "../_shared/hosted-checkout.js";
 import { formatCurrency } from "../_shared/engine-intl.js";
 
@@ -574,8 +575,10 @@ const svc = defineService<State, {
           // only confirmed once it lands, so the cart must survive a bail-out.
           return derive({ ...state, checkoutHint: copyParam("cart.checkoutOpenedMessage", "Checkout opened.") });
         }
+        if (isPaymentSetupFailure(pay)) return derive({ ...state, checkoutHint: paymentSetupMessage("cart") });
         return derive({ ...state, checkoutHint: copyParam("cart.checkoutFailedMessage", "Checkout could not start.") });
-      } catch {
+      } catch (error) {
+        if (isPaymentSetupFailure(error)) return derive({ ...state, checkoutHint: paymentSetupMessage("cart") });
         return derive({ ...state, checkoutHint: copyParam("cart.checkoutFailedMessage", "Checkout could not start.") });
       }
     },

package/templates/beauty-salon/tier5-src/himi-branded-lite-plans/index.ts

@@ -1,3 +1,4 @@
+import { paymentSetupMessage } from "../_shared/payment-setup.js";
 import { offlineWriteMessage, offlineWritesEnabled, withOnlineWrites } from "../_shared/online-actions.js";
 import { connectivity } from "@himalaya/state";
 import { defineService as registerService } from "../_shared/collection-service.js";
@@ -6,7 +7,7 @@ import { createRedirectSession } from "@himalaya/wix-redirects";
 import { open as openUrl } from "@himalaya/open-url";
 import { session as wixPlatformSession } from "@himalaya/wix-platform";
 import { copyParam, copyTemplate, stashCopy } from "../_shared/himi-copy.js";
-import { activePlanIds, entitlement, payCashierOrder } from "@himalaya/checkout";
+import { activePlanIds, entitlement, isPaymentSetupFailure, payCashierOrder } from "@himalaya/checkout";
 import { hostSessionFromGlobal, iapPriceFields, type IapCatalogItem } from "@himalaya/iap";
 import { createIapCommerce, pricingPlanOrders } from "@himalaya/iap-checkout";
 import { iapPriceCopy, iapPurchaseCopy, resetUnhydratedKeysOnOlderRuntime } from "../_shared/iap-worker.js";
@@ -290,7 +291,9 @@ async function regularJoinMessage(row: PlanRow, reference: { kind: string; id: s
     if (pay.kind === "cancelled") {
       return copyParam("plans.joinCancelledMessage", "Payment cancelled — you haven't joined.");
     }
-  } catch {
+    if (isPaymentSetupFailure(pay)) return paymentSetupMessage("plans");
+  } catch (error) {
+    if (isPaymentSetupFailure(error)) return paymentSetupMessage("plans");
   }
   return copyTemplate("plans.joinOnSiteMessage", "Memberships are purchased on the website — visit the site to join {name}.", { name: row.name });
 }

package/templates/branded-lite/tier5-src/_shared/iap-worker.ts

@@ -4,6 +4,7 @@
 // SDK; this only supplies the copy and the hydration reset.
 import { hostSessionFromGlobal, type IapPriceCopy } from "@himalaya/iap";
 import type { IapCommerce, IapPurchaseCopy, IapRestoreResult } from "@himalaya/iap-checkout";
+import { paymentSetupMessage } from "./payment-setup.js";
 import { copyParam, copyTemplate } from "./himi-copy.js";
 
 /** Price labels from the screen's copy pack (`<prefix>.priceLoadingText`, …). */
@@ -25,6 +26,7 @@ export function iapPurchaseCopy(prefix: string): IapPurchaseCopy {
     awaitingApproval: copyParam(`${prefix}.purchaseAwaitingApprovalText`, "Waiting for approval"),
     unavailable: copyParam(`${prefix}.purchaseTemporarilyUnavailableText`, "Purchasing is temporarily unavailable."),
     signInRequired: copyParam(`${prefix}.purchaseSignInText`, "Sign in to buy."),
+    sitePaymentUnavailable: paymentSetupMessage(prefix),
     retry: copyParam(`${prefix}.purchaseRetryText`, "Something went wrong. Try again."),
     priceChanged: copyParam(`${prefix}.purchasePriceChangedText`, "The price changed. Check it and try again."),
     support: copyParam(`${prefix}.purchaseSupportText`, "We couldn't finish this purchase. Contact support."),

package/templates/branded-lite/tier5-src/_shared/payment-setup.ts

@@ -0,0 +1,6 @@
+import { copyParam } from "./himi-copy.js";
+
+/** No provider or country guess: Wix only established that online payment is unavailable. */
+export function paymentSetupMessage(prefix: string): string {
+  return copyParam(`${prefix}.paymentSetupUnavailable`, "This site is not accepting online payments. Go back or contact the business for other payment options.");
+}

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

@@ -1,3 +1,4 @@
+import { paymentSetupMessage } from "../_shared/payment-setup.js";
 import { withOnlineWrites, offlineWritesEnabled } from "../_shared/online-actions.js";
 // Tier-5 bundle: himi-booking — availability and member booking.
 import { defineService as registerService, navigate } from "@himalaya/state";
@@ -9,7 +10,7 @@ import { dispatch } from "@himalaya/dispatch";
 import { bookSchedule, bookSlot, getService, queryServiceAvailability, registerToWaitlist, type WixBookingSlotFull, type WixSelectedPaymentOption, type WixService } from "@himalaya/wix-bookings";
 import { createCheckout, createOrder } from "@himalaya/wix-ecom";
 import { createRedirectSession, type WixSlot } from "@himalaya/wix-redirects";
-import { payCashierOrder } from "@himalaya/checkout";
+import { isPaymentSetupFailure, payCashierOrder } from "@himalaya/checkout";
 import { hostedCheckoutOpener, isHostedWorker } from "../_shared/hosted-checkout.js";
 import { session as wixPlatformSession } from "@himalaya/wix-platform";
 import { displayName, getMyData, type WixMyData } from "@himalaya/wix-users";
@@ -1587,10 +1588,12 @@ async function bookSelectedIn(s: S): Promise<S> {
           ? copyParam("time.coursePaymentCancelled", "Payment cancelled — your course booking wasn't confirmed. Try again.")
           : copyParam("time.paymentCancelled", "Payment cancelled — your booking wasn't confirmed. Pick a time to try again.") });
       }
+      if (isPaymentSetupFailure(pay)) return derive({ ...s, bookingInFlight: false, message: paymentSetupMessage("time") });
       return derive({ ...s, bookingInFlight: false, message: s.isCourse
         ? copyParam("time.coursePaymentFailed", "Payment couldn't be completed. Try again.")
         : copyParam("time.paymentFailed", "Payment couldn't be completed. Pick another time or try again.") });
-    } catch {
+    } catch (error) {
+      if (isPaymentSetupFailure(error)) return derive({ ...s, bookingInFlight: false, message: paymentSetupMessage("time") });
       return derive({ ...s, bookingInFlight: false, message: s.isCourse
         ? copyParam("time.courseCheckoutFailed", "Checkout could not start. Try again.")
         : copyParam("time.checkoutFailed", "Checkout could not start. Pick another time or try again.") });

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

@@ -1,3 +1,4 @@
+import { paymentSetupMessage } from "../_shared/payment-setup.js";
 import { withOnlineWrites } from "../_shared/online-actions.js";
 import { defineService as registerState } from "@himalaya/state";
 import { getStoreProduct } from "../_shared/himi-store.js";
@@ -7,7 +8,7 @@ import { withIapPresentation } from "../_shared/iap-presentation.js";
 import { type IapCommerce, classifyCart } from "@himalaya/iap-checkout";
 import { addCouponToCurrentCart, calculateCurrentCart, createCheckoutFromCurrentCart, getCurrentCart, removeCouponFromCurrentCart, removeLineItemsFromCurrentCart, updateLineItemsQuantity, type WixCartDetail, type WixCartLineItemDetail } from "@himalaya/wix-ecom";
 import { createRedirectSession } from "@himalaya/wix-redirects";
-import { payCashierOrder } from "@himalaya/checkout";
+import { isPaymentSetupFailure, payCashierOrder } from "@himalaya/checkout";
 import { hostedCheckoutOpener, isHostedWorker } from "../_shared/hosted-checkout.js";
 import { formatCurrency } from "../_shared/engine-intl.js";
 
@@ -574,8 +575,10 @@ const svc = defineService<State, {
           // only confirmed once it lands, so the cart must survive a bail-out.
           return derive({ ...state, checkoutHint: copyParam("cart.checkoutOpenedMessage", "Checkout opened.") });
         }
+        if (isPaymentSetupFailure(pay)) return derive({ ...state, checkoutHint: paymentSetupMessage("cart") });
         return derive({ ...state, checkoutHint: copyParam("cart.checkoutFailedMessage", "Checkout could not start.") });
-      } catch {
+      } catch (error) {
+        if (isPaymentSetupFailure(error)) return derive({ ...state, checkoutHint: paymentSetupMessage("cart") });
         return derive({ ...state, checkoutHint: copyParam("cart.checkoutFailedMessage", "Checkout could not start.") });
       }
     },

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

@@ -1,3 +1,4 @@
+import { paymentSetupMessage } from "../_shared/payment-setup.js";
 import { offlineWriteMessage, offlineWritesEnabled, withOnlineWrites } from "../_shared/online-actions.js";
 import { connectivity } from "@himalaya/state";
 import { defineService as registerService } from "../_shared/collection-service.js";
@@ -6,7 +7,7 @@ import { createRedirectSession } from "@himalaya/wix-redirects";
 import { open as openUrl } from "@himalaya/open-url";
 import { session as wixPlatformSession } from "@himalaya/wix-platform";
 import { copyParam, copyTemplate, stashCopy } from "../_shared/himi-copy.js";
-import { activePlanIds, entitlement, payCashierOrder } from "@himalaya/checkout";
+import { activePlanIds, entitlement, isPaymentSetupFailure, payCashierOrder } from "@himalaya/checkout";
 import { hostSessionFromGlobal, iapPriceFields, type IapCatalogItem } from "@himalaya/iap";
 import { createIapCommerce, pricingPlanOrders } from "@himalaya/iap-checkout";
 import { iapPriceCopy, iapPurchaseCopy, resetUnhydratedKeysOnOlderRuntime } from "../_shared/iap-worker.js";
@@ -290,7 +291,9 @@ async function regularJoinMessage(row: PlanRow, reference: { kind: string; id: s
     if (pay.kind === "cancelled") {
       return copyParam("plans.joinCancelledMessage", "Payment cancelled — you haven't joined.");
     }
-  } catch {
+    if (isPaymentSetupFailure(pay)) return paymentSetupMessage("plans");
+  } catch (error) {
+    if (isPaymentSetupFailure(error)) return paymentSetupMessage("plans");
   }
   return copyTemplate("plans.joinOnSiteMessage", "Memberships are purchased on the website — visit the site to join {name}.", { name: row.name });
 }

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

@@ -1,3 +1,4 @@
+import { paymentSetupMessage } from "../_shared/payment-setup.js";
 import { dispatch } from "@himalaya/dispatch";
 import { memberAccess, assertMemberAccess } from "../_shared/member-access.js";
 import { offlineWriteMessage, withOnlineWrites } from "../_shared/online-actions.js";
@@ -42,7 +43,7 @@ import { getMyMember } from "@himalaya/wix-members";
 import { session as wixPlatformSession } from "@himalaya/wix-platform";
 import { cleanTitle, initials } from "../_shared/himi-text.js";
 import { copyParam, copyTemplate, stashCopy } from "../_shared/himi-copy.js";
-import { payCashierOrder } from "@himalaya/checkout";
+import { isPaymentSetupFailure, payCashierOrder } from "@himalaya/checkout";
 import { formatCurrency } from "../_shared/engine-intl.js";
 import { iapPriceFields, onlineProgramItem, type IapCatalogItem, type IapPollDirective, type IapPriceFields } from "@himalaya/iap";
 import { createIapCommerce, onlineProgramOrders, type IapPurchaseFields } from "@himalaya/iap-checkout";
@@ -251,9 +252,11 @@ async function enrollmentMessage(id: string, name: string, guards: CommerceGuard
       : copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
     if (pay.kind === "handoff") return "";
     if (pay.kind === "cancelled") return copyParam("program.joinCancelledMessage", "Payment cancelled — you haven't enrolled.");
-  } catch {
+    if (isPaymentSetupFailure(pay)) return paymentSetupMessage("program");
+  } catch (error) {
     if (!connectivity().online) return offlineWriteMessage;
     if (preparationWithdrawn) return blocked();
+    if (isPaymentSetupFailure(error)) return paymentSetupMessage("program");
     // fall through to the site-directing message
   }
   return copyTemplate("program.joinOnSiteMessage", "Enrolment happens on the website — visit the site to join {name}.", { name });

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

@@ -1,3 +1,4 @@
+import { paymentSetupMessage } from "../_shared/payment-setup.js";
 // Tier-5 bundle: himi-events — event detail.
 import { calendarDay, formatClock, formatCurrency, formatWeekdayDateTime, formatWeekdayMonthDay, formatTimeZoneLabel } from "../_shared/engine-intl.js";
 import { defineService as registerService } from "@himalaya/state";
@@ -18,7 +19,7 @@ import {
   type WixEvent,
 } from "@himalaya/wix-events";
 import { session as wixPlatformSession } from "@himalaya/wix-platform";
-import { payCashierOrder } from "@himalaya/checkout";
+import { isPaymentSetupFailure, payCashierOrder } from "@himalaya/checkout";
 import { get, upsert, type DbEntity } from "@himalaya/local-db";
 import {
   currentInputId,
@@ -986,16 +987,18 @@ const svc: ReturnType<typeof defineService<S, DetailActions>> = defineService<S,
               if (pay.kind === "paid") result = { ...s, ticketSheetOpen: false, snackbarMessage: detailCopy("event.ticketIssued", "You're in — your ticket is confirmed.") };
               else if (pay.kind === "handoff") result = { ...s, ticketSheetOpen: false, snackbarMessage: detailCopy("event.checkoutOpened", "Complete checkout in the browser to get your tickets.") };
               else if (pay.kind === "cancelled") result = { ...s, snackbarMessage: detailCopy("event.ticketCancelled", "Payment cancelled — no ticket was issued.") };
+              else if (isPaymentSetupFailure(pay)) result = { ...s, snackbarMessage: paymentSetupMessage("event") };
               else throw new Error("Payment could not be completed");
             }
           }
         }
-      } catch {
+      } catch (error) {
+        if (isPaymentSetupFailure(error)) result = { ...s, snackbarMessage: paymentSetupMessage("event") };
         try {
           // A public event page is not pinned to this selection or price. Only
           // continue in hosted checkout when a reservation already holds it.
           const params = reservationId ? { reservationId } : undefined;
-          if (params) {
+          if (params && !result) {
             const redirect = await createRedirectSession({ eventsCheckout: params });
             const url = redirect.redirectSession?.fullUrl;
             if (url) {
@@ -1003,7 +1006,9 @@ const svc: ReturnType<typeof defineService<S, DetailActions>> = defineService<S,
               result = { ...s, ticketSheetOpen: false, snackbarMessage: opened.opened ? detailCopy("event.checkoutOpened", "Complete checkout in the browser to get your tickets.") : detailCopy("event.registrationOpenFailed", "Could not open the registration page.") };
             }
           }
-        } catch { /* report below */ }
+        } catch (error) {
+          if (isPaymentSetupFailure(error)) result = { ...s, snackbarMessage: paymentSetupMessage("event") };
+        }
         if (!result) result = { ...s, snackbarMessage: detailCopy("event.purchaseUnavailable", "Purchasing is temporarily unavailable.") };
       } finally { ticketCheckoutInFlight = false; }
       return derive(result!);

package/templates/community-club/tier5-src/_shared/iap-worker.ts

@@ -4,6 +4,7 @@
 // SDK; this only supplies the copy and the hydration reset.
 import { hostSessionFromGlobal, type IapPriceCopy } from "@himalaya/iap";
 import type { IapCommerce, IapPurchaseCopy, IapRestoreResult } from "@himalaya/iap-checkout";
+import { paymentSetupMessage } from "./payment-setup.js";
 import { copyParam, copyTemplate } from "./himi-copy.js";
 
 /** Price labels from the screen's copy pack (`<prefix>.priceLoadingText`, …). */
@@ -25,6 +26,7 @@ export function iapPurchaseCopy(prefix: string): IapPurchaseCopy {
     awaitingApproval: copyParam(`${prefix}.purchaseAwaitingApprovalText`, "Waiting for approval"),
     unavailable: copyParam(`${prefix}.purchaseTemporarilyUnavailableText`, "Purchasing is temporarily unavailable."),
     signInRequired: copyParam(`${prefix}.purchaseSignInText`, "Sign in to buy."),
+    sitePaymentUnavailable: paymentSetupMessage(prefix),
     retry: copyParam(`${prefix}.purchaseRetryText`, "Something went wrong. Try again."),
     priceChanged: copyParam(`${prefix}.purchasePriceChangedText`, "The price changed. Check it and try again."),
     support: copyParam(`${prefix}.purchaseSupportText`, "We couldn't finish this purchase. Contact support."),

package/templates/community-club/tier5-src/_shared/payment-setup.ts

@@ -0,0 +1,6 @@
+import { copyParam } from "./himi-copy.js";
+
+/** No provider or country guess: Wix only established that online payment is unavailable. */
+export function paymentSetupMessage(prefix: string): string {
+  return copyParam(`${prefix}.paymentSetupUnavailable`, "This site is not accepting online payments. Go back or contact the business for other payment options.");
+}

package/templates/community-club/tier5-src/himi-events-detail/index.ts

@@ -1,3 +1,4 @@
+import { paymentSetupMessage } from "../_shared/payment-setup.js";
 // Tier-5 bundle: himi-events — event detail.
 import { calendarDay, formatClock, formatCurrency, formatWeekdayDateTime, formatWeekdayMonthDay, formatTimeZoneLabel } from "../_shared/engine-intl.js";
 import { defineService as registerService } from "@himalaya/state";
@@ -18,7 +19,7 @@ import {
   type WixEvent,
 } from "@himalaya/wix-events";
 import { session as wixPlatformSession } from "@himalaya/wix-platform";
-import { payCashierOrder } from "@himalaya/checkout";
+import { isPaymentSetupFailure, payCashierOrder } from "@himalaya/checkout";
 import { get, upsert, type DbEntity } from "@himalaya/local-db";
 import {
   currentInputId,
@@ -986,16 +987,18 @@ const svc: ReturnType<typeof defineService<S, DetailActions>> = defineService<S,
               if (pay.kind === "paid") result = { ...s, ticketSheetOpen: false, snackbarMessage: detailCopy("event.ticketIssued", "You're in — your ticket is confirmed.") };
               else if (pay.kind === "handoff") result = { ...s, ticketSheetOpen: false, snackbarMessage: detailCopy("event.checkoutOpened", "Complete checkout in the browser to get your tickets.") };
               else if (pay.kind === "cancelled") result = { ...s, snackbarMessage: detailCopy("event.ticketCancelled", "Payment cancelled — no ticket was issued.") };
+              else if (isPaymentSetupFailure(pay)) result = { ...s, snackbarMessage: paymentSetupMessage("event") };
               else throw new Error("Payment could not be completed");
             }
           }
         }
-      } catch {
+      } catch (error) {
+        if (isPaymentSetupFailure(error)) result = { ...s, snackbarMessage: paymentSetupMessage("event") };
         try {
           // A public event page is not pinned to this selection or price. Only
           // continue in hosted checkout when a reservation already holds it.
           const params = reservationId ? { reservationId } : undefined;
-          if (params) {
+          if (params && !result) {
             const redirect = await createRedirectSession({ eventsCheckout: params });
             const url = redirect.redirectSession?.fullUrl;
             if (url) {
@@ -1003,7 +1006,9 @@ const svc: ReturnType<typeof defineService<S, DetailActions>> = defineService<S,
               result = { ...s, ticketSheetOpen: false, snackbarMessage: opened.opened ? detailCopy("event.checkoutOpened", "Complete checkout in the browser to get your tickets.") : detailCopy("event.registrationOpenFailed", "Could not open the registration page.") };
             }
           }
-        } catch { /* report below */ }
+        } catch (error) {
+          if (isPaymentSetupFailure(error)) result = { ...s, snackbarMessage: paymentSetupMessage("event") };
+        }
         if (!result) result = { ...s, snackbarMessage: detailCopy("event.purchaseUnavailable", "Purchasing is temporarily unavailable.") };
       } finally { ticketCheckoutInFlight = false; }
       return derive(result!);

package/templates/events-meetups/tier5-src/_shared/iap-worker.ts

@@ -4,6 +4,7 @@
 // SDK; this only supplies the copy and the hydration reset.
 import { hostSessionFromGlobal, type IapPriceCopy } from "@himalaya/iap";
 import type { IapCommerce, IapPurchaseCopy, IapRestoreResult } from "@himalaya/iap-checkout";
+import { paymentSetupMessage } from "./payment-setup.js";
 import { copyParam, copyTemplate } from "./himi-copy.js";
 
 /** Price labels from the screen's copy pack (`<prefix>.priceLoadingText`, …). */
@@ -25,6 +26,7 @@ export function iapPurchaseCopy(prefix: string): IapPurchaseCopy {
     awaitingApproval: copyParam(`${prefix}.purchaseAwaitingApprovalText`, "Waiting for approval"),
     unavailable: copyParam(`${prefix}.purchaseTemporarilyUnavailableText`, "Purchasing is temporarily unavailable."),
     signInRequired: copyParam(`${prefix}.purchaseSignInText`, "Sign in to buy."),
+    sitePaymentUnavailable: paymentSetupMessage(prefix),
     retry: copyParam(`${prefix}.purchaseRetryText`, "Something went wrong. Try again."),
     priceChanged: copyParam(`${prefix}.purchasePriceChangedText`, "The price changed. Check it and try again."),
     support: copyParam(`${prefix}.purchaseSupportText`, "We couldn't finish this purchase. Contact support."),