@wix/himalaya-cli 0.1319.0 → 0.1321.0

package/guides/capabilities.md

@@ -59,6 +59,23 @@ The screen list is enforced at runtime: a call the screen did not declare is **d
 so it must name every capability the app uses. A background variant (`location_background`,
 `audio_record_background`) is declared instead of — and grants — its foreground capability.
 
+### Local database and tenant switches
+
+On native hosts `local_database` is also scoped by the host's active tenant. On a multi-tenant host such as Himi Player, a worker is stamped with the tenant that was active when its boot started. The
+stamp travels with each dispatch; if the host switches tenants while a dispatch is in flight,
+the native handler refuses it at store or write-queue resolution instead of retargeting the
+request to the new tenant.
+
+The tenant's `dataSchema` is the allowlist for local entities and must be applied for the
+tenant whose config supplied it. A missing schema is applied as `{}` and clears the previous
+allowlist and encrypted backing configuration. Himi Player applies cached package config
+before an imported-package fetch and reapplies the fetched schema after foreground/reload
+refreshes only when the refresh still belongs to the current release and tenant; snapshot
+packages and stale or overtaken refreshes are not overwritten.
+
+The web host does not have this scoping yet: its IndexedDB `EntityStore` keys rows by
+`entity:<name>` only, so on the web Player two apps that use the same entity name share rows.
+
 ## 3. Check
 
 ```bash

package/guides/designing-himi-screens.md

@@ -408,6 +408,8 @@ nicety. Don't animate everything: if every element moves, nothing reads as impor
 - **`accessibility_label` on every non-text control, icon, and image.** This is **distinct from `id`** —
   `id` targets a node for Argus/test automation; `accessibility_label` is what a screen reader announces.
   A screen full of `id`s and no `accessibility_label`s is testable but unusable with VoiceOver/TalkBack.
+  It may be bound to worker state with `$service:<service>.<path>`; the web renderer keeps the
+  resulting `aria-label` current as that state changes.
 - **Tap targets** stay comfortably large (don't shrink `button`/`icon` hit areas below ~44pt).
 - **Contrast** comes from the token roles — pair `textPrimary`/`textSecondary` with the right surface,
   and provide the `highContrast` scheme value for load-bearing colors.

package/guides/getting-started.md

@@ -269,8 +269,10 @@ and `himi site function` (not analyze, and not `himi functions`).
 **Selling digital items** (programs, products, plans the owner registered with `himi store iap`)?
 Any screen that shows such an item's price — a template screen or one you write — gets its App
 Store price and payment route from the shared `createIapCatalogPricing` in `@himalaya/iap`:
-read `himi docs iap-pricing` before writing the worker. Starting from a template does not cover
-your own screens; each screen opts in explicitly.
+read `himi docs iap-pricing` before writing the worker. A screen that sells the item composes
+`createIapCommerce` from `@himalaya/iap-checkout` and binds Get access with
+`commerce.purchaseFields`, never StoreKit or the payment client directly. Starting from a template does
+not cover your own screens; each screen opts in explicitly.
 
 After `himi init … --template branded-lite` (or a vertical overlay), **point the app at your
 Wix site** before expecting live catalog data:

package/guides/himi-skill.md

@@ -292,8 +292,10 @@ and `himi site function` (not analyze, and not `himi functions`).
 **Selling digital items** (programs, products, plans the owner registered with `himi store iap`)?
 Any screen that shows such an item's price — a template screen or one you write — gets its App
 Store price and payment route from the shared `createIapCatalogPricing` in `@himalaya/iap`:
-read `himi docs iap-pricing` before writing the worker. Starting from a template does not cover
-your own screens; each screen opts in explicitly.
+read `himi docs iap-pricing` before writing the worker. A screen that sells the item composes
+`createIapCommerce` from `@himalaya/iap-checkout` and binds Get access with
+`commerce.purchaseFields`, never StoreKit or the payment client directly. Starting from a template does
+not cover your own screens; each screen opts in explicitly.
 
 After `himi init … --template branded-lite` (or a vertical overlay), **point the app at your
 Wix site** before expecting live catalog data:

package/guides/iap-pricing.md

@@ -6,9 +6,11 @@ displays or sells: a program, a product, a plan, or anything else you registered
 which items are sold through the App Store, fetches their prices from Apple, and returns display
 state plus a payment route. Your screen binds the result to its own UI.
 
-> **Not switched on yet.** Wix has not connected the service that maps your catalog to App Store
-> products. Until it does, every screen keeps its existing price and checkout. Apple purchasing is
-> not available in any case: this layer shows prices and blocks the wrong checkout, but never buys.
+> **On for bound apps only.** The mapping is read from the app's purchases catalog, which
+> `himi store iap connect` sets up. An app with no purchases-app binding reads every item as
+> `disabled` and keeps its existing price and checkout. This page shows prices and blocks the wrong
+> checkout; selling an App Store item is the shared checkout's job (`createIapCommerce` +
+> `commerce.purchaseFields`, [Wix Apple-IAP checkout](iap-wix-checkout.md#using-it-from-a-screen)).
 > Only one-time purchases (non-consumables) are supported. Subscriptions and consumables are not.
 
 ## What you get per item
@@ -20,7 +22,7 @@ what to do:
 |---|---|---|
 | `disabled` | Your screen's own price, exactly as before | Allowed |
 | `resolving` | A "Loading price…" label, never your own price | Blocked |
-| `appleIap` | `displayPrice` exactly as Apple formats it, plus a "One-time purchase" note | Blocked; purchasing is not available yet |
+| `appleIap` | `displayPrice` exactly as Apple formats it, plus a "One-time purchase" note | Blocked; the shared checkout sells it |
 | `regular` | `displayPrice` (the commerce price you passed), or nothing | Allowed |
 | `unavailable` | "Price unavailable", plus Retry when `retryable` | Blocked |
 
@@ -34,10 +36,9 @@ does not mean the item is free. Only an explicit `regular` route keeps your exis
 returns `null` for any other route. It is for a checkout to compare with the product it is asked to
 sell. Do not put it in screen state.
 
-> **Buying is not switched on.** `@wix/himalaya/iap-checkout` is a shared App Store checkout,
-> `createAppleIapCheckout`, built on this layer. It answers `notEnabled` and makes no call until Wix
-> enables it, so keep App Store items blocked as described above. Never build your own purchase
-> flow for them.
+> **Buy through the shared checkout only.** `@wix/himalaya/iap-checkout` (`createIapCommerce`) is
+> the App Store checkout built on this layer, and it sells only in a bound app. Keep App Store items
+> blocked in your own checkout as described above. Never build your own purchase flow for them.
 
 ## Catalog references
 
@@ -52,13 +53,16 @@ when it registers the item with Apple:
 
 ## Add it to a worker
 
-This is a complete worker for one screen. Copy the pattern, not the course names.
+This is a complete worker for one screen that shows an App Store price and guards its existing
+checkout. Copy the pattern, not the course names. A screen that also SELLS the item passes its
+vertical adapter to `createIapCommerce` and binds Get access with `commerce.purchaseFields` instead of
+blocking ([checkout recipe](iap-wix-checkout.md#using-it-from-a-screen)).
 
 ```ts
 // catalog-pricing-worker.ts
 import { defineService } from "@himalaya/state";
-import { get as appInfo } from "@himalaya/app-info";
-import { createIapCatalogPricing, iapPriceFields, onlineProgramItem } from "@himalaya/iap";
+import { iapPriceFields, onlineProgramItem } from "@himalaya/iap";
+import { createIapCommerce } from "@himalaya/iap-checkout";
 
 const COPY = {
   loading: "Loading price…",
@@ -74,25 +78,25 @@ type CourseState = Record<string, unknown>;
 
 /** `startCheckout` is the screen's existing commerce flow. */
 export function registerCourseScreen(course: Course, startCheckout: () => Promise<string>) {
-  const pricing = createIapCatalogPricing({ onChange: () => { void service.publish(); } });
+  // No adapters: this screen shows the price and keeps its own checkout. `commerce.pricing` is the
+  // shared `createIapCatalogPricing` layer; the host scopes its lookup (app identity, platform, and
+  // the app's purchases-app site when it has one).
+  const commerce = createIapCommerce({ onChange: () => { void service.publish(); } });
+  const pricing = commerce.pricing;
   const item = onlineProgramItem({ id: course.id }, course.commercePrice)!;
   let message = "";
   let scopeIncomplete = false;
 
-  async function hostScope() {
-    const info = await appInfo().catch(() => undefined);
-    scopeIncomplete = !info?.appId || !info?.bundleId || !info?.platform;
-    return { scope: { appId: info?.appId ?? "", bundleId: info?.bundleId ?? "" }, platform: info?.platform ?? "" };
-  }
-
   async function loadPrices() {
-    if (pricing.enabled) await pricing.load({ ...(await hostScope()), items: [item] });
+    if (pricing.enabled) scopeIncomplete = !(await commerce.loadPrices([item])).scopeComplete;
     void service.publish();
   }
 
   function present(state: CourseState): CourseState {
-    if (!pricing.enabled) return { ...state, priceText: course.commercePrice, buyDisabled: false, message };
-    const price = iapPriceFields(pricing.view(item.reference), COPY);
+    const view = pricing.view(item.reference);
+    // `disabled`: no source, or an app that sells nothing through the App Store — the screen's own price.
+    if (view.route === "disabled") return { ...state, priceText: course.commercePrice, buyDisabled: false, message };
+    const price = iapPriceFields(view, COPY);
     return { ...state, priceText: price.priceText, priceNote: price.priceNote, hidePriceRetry: price.hidePriceRetry && !scopeIncomplete,
       buyDisabled: price.actionDisabled, buyNote: price.actionNote, message };
   }
@@ -125,14 +129,14 @@ export function registerCourseScreen(course: Course, startCheckout: () => Promis
 }
 ```
 
-Bind the fields in the screen descriptor and declare both capabilities the worker calls. To show
+Bind the fields in the screen descriptor and declare the capabilities the worker calls. To show
 real App Store prices, the app must also grant `iap` (and `app_info`) in its `config.ts`
 `capabilities`, so its native shell registers the store bridge; until it does, the screen fails
 closed to "Price unavailable" rather than showing a price it could not confirm.
 
 ```json
 {
-  "logicBundle": { "declaredCapabilities": ["iap", "app_info"] },
+  "logicBundle": { "declaredCapabilities": ["iap", "app_info", "wix_api"] },
   "price":   { "type": "Text",   "props": { "text": "$service:course.priceText", "collapseWhenEmpty": true } },
   "note":    { "type": "Text",   "props": { "text": "$service:course.priceNote", "collapseWhenEmpty": true } },
   "retry":   { "type": "Button", "props": { "title": "Try again", "action": { "actionId": "tier5.course.refreshPrice" } },
@@ -163,8 +167,9 @@ closed to "Price unavailable" rather than showing a price it could not confirm.
 - **Keep prices out of hydration** with `notHydrated`, so a cold start never shows an old amount.
 - **Content first.** A pricing failure is per item. Never replace the screen with an error because a
   price could not load.
-- **iOS only.** On Android, web and macOS, App Store routes come back `unavailable`. Regular
-  routes are unaffected.
+- **iOS only.** Android, web and macOS binaries carry no purchases-app binding, so the shipped
+  source reads every item there as `disabled` and the screen's own price and checkout apply. A
+  mapping that does name an App Store product on those hosts comes back `unavailable`.
 
 ## Adopting it
 
@@ -173,7 +178,9 @@ closed to "Price unavailable" rather than showing a price it could not confirm.
 - **Existing screens, including apps created from a template before this existed:** an SDK update
   never changes a screen that does not call this layer. Add the worker calls, the bindings and the
   two capabilities above. After that, screens pick up layer fixes on their next build.
-- **Custom screens:** follow the worker above for any item you sell, whatever its vertical.
+- **Custom screens:** follow the worker above for any item you price, and the
+  [checkout recipe](iap-wix-checkout.md#using-it-from-a-screen) for any item you sell, whatever its
+  vertical.
 - **New item types:** use the kind `himi store iap` registers for it, build `{ kind, id }`, and call
   the same layer. Never write your own mapping lookup, App Store price request or payment guard.
 

package/guides/index.json

@@ -20,7 +20,8 @@
   ],
   "guardrails": [
     "Prefer Tier-5 (SDUI descriptor + JS worker) over native screens — reach for native only when SDUI genuinely can't express it.",
-    "A screen that shows or sells an item that may be an App Store in-app purchase (a program, product or plan — template or custom screen alike) uses the shared layer `createIapCatalogPricing` from `@himalaya/iap` (`himi docs iap-pricing`): it batches the mapping lookup, fetches Apple prices and decides the payment route. Never hand-wire a mapping, an Apple price request or a payment guard in a worker. Call `checkoutGuard` immediately before a commerce flow starts, and `continueCheckoutGuard` before each later step of a flow already under way (a payment after a join), so a routine price refresh cannot strand it halfway. It is off until Wix connects the mapping service, and Apple purchasing is not available yet.",
+    "A screen that shows or sells an item that may be an App Store in-app purchase (a program, product or plan — template or custom screen alike) uses the shared layer `createIapCatalogPricing` from `@himalaya/iap` (`himi docs iap-pricing`): it batches the mapping lookup, fetches Apple prices and decides the payment route. Never hand-wire a mapping, an Apple price request or a payment guard in a worker. Call `checkoutGuard` immediately before a commerce flow starts, and `continueCheckoutGuard` before each later step of a flow already under way (a payment after a join), so a routine price refresh cannot strand it halfway. It is off until Wix connects the mapping service.",
+    "To SELL an App Store item, a screen composes `createIapCommerce` from `@himalaya/iap-checkout` once per worker (its catalog pricing plus the shared checkout, with the vertical's order adapter) and binds its Get access action with `commerce.purchaseFields`: the order, Apple's sheet, proof delivery, finishing and the access read all happen inside it. Never call StoreKit (`purchaseForVerification`), `finishTransaction` or the payment client from a worker, never fall back to Wix checkout for an App Store item, and show access only when it reports `accessReady`. Purchasing stays unavailable until Wix provides its routes and mapping.",
     "Keep structure descriptor-authored: use FragmentSlot for enumerable variants and bound list/grid templates for repetition. Use WorkerSubtree only for runtime-unknowable structure, with an explicit screen allowlist, policy budgets, and shipped fallback.",
     "Bindings ($service:<svc>.<path>, $item.<field>, $flag:<key>) are plain strings in ANY prop — INCLUDING Modifiers token refs (background, color, tint), so a worker can drive per-item theming, not just text. They CANNOT target strict-enum fields (style, size, alignment, severity, presentation, …) — those fail at render, not validation.",
     "Workers are sandboxed: no DOM, no timers, no raw fetch. Produce state synchronously in actions; do not rely on an ambient refresh tick.",

package/guides/qa-builds.md

@@ -8,10 +8,12 @@ A **QA build** is a real, installable app you hand to QA — an enterprise/ad-ho
 distinct from the CI gates (`test:*`, `argus:*`), which only prove the code builds
 and passes flows; nothing installable comes out of those.
 
-> **QA only — not TestFlight.** `himi dist` returns an installable QA artifact and
-> install link. It never submits to App Store Connect or Google Play. In particular,
-> it is separate from Himi Player's Wix Mobile Release TestFlight route and its
-> output is not an MRE-approved upload artifact.
+> **The default is QA; customer TestFlight is an explicit BYO path.** The ordinary
+> `himi dist` request returns an installable QA artifact and install link. A customer
+> iOS request may instead use `--signing byo --destination testflight --site <id>
+> --version <x.y.z>`; the build validates the App Store IPA, and an authorized
+> `himi dist status <jobId>` read uploads it to the customer's App Store Connect account.
+> The customer path is not Himi Player's Wix Mobile Release route and does not use MRE.
 
 > **Customer request gate.** Do not dispatch `himi dist` merely because a draft preview is ready.
 > First confirm that the customer explicitly asked to download the app, identify the approved
@@ -32,8 +34,31 @@ This submits `destination: testflight`. The pool produces an IPA in the MRE-appr
 `wix-ios-app-builds` bucket; deployed serve then invokes MRE using its POCO service
 identity and persists the MRE request ID/status on the same Job Service record. It
 accepts only the `himi-player` app, `player` shell, iOS, and its own bundle identity.
-`himi dist` keeps `destination: link`, does not call MRE, and remains the QA path for
-Himi distribution apps.
+The customer BYO path below also uses `destination: testflight`, but it uploads through
+an authorized `himi dist status` read rather than MRE. The ordinary `himi dist` path
+keeps `destination: link` and remains the QA path for Himi distribution apps.
+
+### Customer App Store / TestFlight handoff
+
+For an owned app, the customer must authorize the selected site and provide the existing
+customer distribution certificate plus an **App Store** provisioning profile (not the ad-hoc
+profile the QA `--signing byo` path below selects) and an App Store Connect API key (key id,
+issuer id and private key) in the site's customer signing binding. Without that key the
+request fails with `customer_app_store_validation_key_missing`. The request is iOS-only:
+
+```bash
+himi dist --app <app> --release <published-release-id> --site <owned-site-id> \
+  --platform ios --signing byo --destination testflight \
+  --version <marketing-version> --no-wait --target wix
+himi dist status <jobId> --target wix
+```
+
+The pool records `READY_FOR_UPLOAD` after validating the IPA. The status read proves site
+ownership with the Wix credential, then claims and uploads the IPA once; repeat reads are
+safe. Without that authorization, status reports the waiting state and does not upload.
+The upload also requires customer App Store upload to be enabled on the Himi backend
+(`HIMI_DIST_CUSTOMER_APP_STORE_UPLOAD=1`); where that switch is off, the job stays at `READY_FOR_UPLOAD` with a validated IPA that is
+never uploaded.
 
 ### iOS bundle identities are channel-specific
 
@@ -147,8 +172,9 @@ The chosen policy is written to the job record (`signing`), so `himi dist status
 answer "whose certificate is on this binary" without re-deriving it from serve config that may
 have changed since.
 
-**`--signing byo`** uses an owned Wix site and its existing personal Apple distribution certificate
-and ad-hoc profile. Himi checks site ownership, the app's recorded native ID, profile
+**`--signing byo`** (QA, `destination: link`) uses an owned Wix site and its existing personal
+Apple distribution certificate and ad-hoc profile. The TestFlight handoff above uses the App Store
+profile and ASC key instead; an ad-hoc setup does not satisfy it. Himi checks site ownership, the app's recorded native ID, profile
 type, certificate match, expiry, registered devices and production APNs entitlement before dispatch.
 It selects an existing compatible ad-hoc profile; the build does not create or revoke Apple assets.
 The runner fetches the certificate and profile using both its job token and a short-lived Buildkite

package/guides/sdk-reference.json

@@ -432,8 +432,8 @@
       {
         "name": "BiometricKind",
         "kind": "type",
-        "jsdoc": "",
-        "decl": "export type BiometricKind = \"face\" | \"fingerprint\" | \"iris\" | \"none\";"
+        "jsdoc": "/**\n * The enrolled biometric, as far as the platform can tell:\n * - `\"face\"` / `\"fingerprint\"` / `\"iris\"` — that modality.\n * - `\"biometric\"` — a biometric is enrolled but the platform can't say which\n *   (Android phones with both face and fingerprint hardware; the web). Label\n *   the unlock neutrally (\"Use biometrics\") rather than guessing a modality.\n * - `\"none\"` — nothing enrolled, or no hardware.\n *\n * Additive: treat any value you don't recognise like `\"biometric\"`.\n */",
+        "decl": "export type BiometricKind = \"face\" | \"fingerprint\" | \"iris\" | \"biometric\" | \"none\";"
       },
       {
         "name": "available",
@@ -1878,7 +1878,7 @@
         "name": "IapMappingSource",
         "kind": "interface",
         "jsdoc": "/** A deployed Wix→Apple mapping backend. Never supplied by a screen. */",
-        "decl": "export interface IapMappingSource {\n  mapping: PricingMappingProvider;\n  /** The site this backend serves, used when the caller passes no site. */\n  siteId?: string;\n}"
+        "decl": "export interface IapMappingSource {\n  mapping: PricingMappingProvider;\n  /** Whether this app sells through the App Store at all — the binary carries a purchases-app binding.\n   *  When it answers false, every item reads `disabled` with no lookup, exactly as with no source, so the\n   *  screen's own commerce applies; asked again on every load. Absent means always active. */\n  active?(): Promise<boolean>;\n  /** The site this backend serves, used when the caller passes no site. */\n  siteId?: string;\n}"
       },
       {
         "name": "IapPollDirective",
@@ -2065,7 +2065,7 @@
       {
         "name": "createWixIapClient",
         "kind": "function",
-        "jsdoc": "/**\n * Creates a client for Wix's in-app-purchase payments service (`mobile-apps-wix-iap`), which pays\n * a Wix order with a store purchase the member makes in the app.\n *\n * NOT ENABLED and not production-ready. No app wires it, and no call reaches the service: it has\n * no public gateway route yet, so `route` must be supplied and there is no default. It calls\n * StartPayment (`POST …/payments/start`), CompletePayment (`POST …/payments/complete`)\n * and GetPayment (`GET …/payments/{id}`) through the\n * `wix_api` bridge. A matched or approved Payment is not durable access and never finishes the\n * store transaction.\n *\n * Production use stays blocked: there is no public route or member authorization on the service,\n * no trusted app-binding source, and checkout stays disabled. When this client uses the host\n * bridge, it also requires the host's identity clock and passes that captured expectation\n * through the bridge. An injected transport keeps the previous call shape unless the session\n * itself exposes an identity.\n */",
+        "jsdoc": "/**\n * Creates a client for Wix's in-app-purchase payments service (`mobile-apps-wix-iap`), which pays\n * a Wix order with a store purchase the member makes in the app.\n *\n * The shared checkout (`createIapCommerce`) builds it with Serve's IAP route for an app whose binary\n * carries a purchases-app binding; `route` stays a parameter with no default. It calls\n * StartPayment (`POST …/payments/start`), CompletePayment (`POST …/payments/complete`)\n * and GetPayment (`GET …/payments/{id}`) through the\n * `wix_api` bridge. A matched or approved Payment is not durable access and never finishes the\n * store transaction.\n *\n * A sale needs the binding baked into the binary and an active mapping for the item; without them\n * nothing is offered, and before a production Serve release carries the IAP routes the mapping read\n * fails, so nothing is offered either. When this client uses the host\n * bridge, it also requires the host's identity clock and passes that captured expectation\n * through the bridge. An injected transport keeps the previous call shape unless the session\n * itself exposes an identity.\n */",
         "decl": "export function createWixIapClient(deps: WixIapClientDependencies): WixIapClient;",
         "verified": false
       },
@@ -2079,7 +2079,7 @@
         "name": "HostIdentitySource",
         "kind": "interface",
         "jsdoc": "/** A session provider that can also name the principal captured for one generation. */",
-        "decl": "export interface HostIdentitySource {\n  readonly identityBound: boolean;\n  identity(session: SessionSnapshot): HostCallExpectation | null;\n}"
+        "decl": "export interface HostIdentitySource {\n  readonly identityBound: boolean;\n  identity(session: SessionSnapshot): HostCallExpectation | null;\n  /** The site the native bridge fences protected calls to, from the latest ready snapshot. Null\n   *  when the host installed no session source: iOS publishes the bridge (`identityBound`) to\n   *  every worker that has `wix_api`, with or without one. */\n  site(): string | null;\n}"
       },
       {
         "name": "HostSessionProvider",
@@ -2248,6 +2248,18 @@
         "kind": "const",
         "jsdoc": "/** The managed native verbs as the delivery coordinator's store. */",
         "decl": "export const appleManagedStore: TransactionStore = { purchaseForVerification, getUnfinishedTransactions, finishTransaction };"
+      },
+      {
+        "name": "hostAppBindingSource",
+        "kind": "function",
+        "jsdoc": "/** The purchases-service binding the host baked into this binary at build time (the app's build\n *  contract → Info.plist), checked natively against the running bundle, app and site. Never read\n *  from a screen, OTA config or navigation param: a worker cannot choose which purchases app it\n *  sells through. Null means not provisioned: an unbound build, an older binary without the verb,\n *  or a platform with no managed App Store purchasing. A host that has the verb and fails to answer\n *  proves neither, so that read rejects and is not kept: the caller must not fall back to the\n *  unbound app's commerce. The binding cannot change while the process runs, so a source asks the\n *  host once. */",
+        "decl": "export function hostAppBindingSource(): AppBindingSource;"
+      },
+      {
+        "name": "sharedHostAppBindingSource",
+        "kind": "function",
+        "jsdoc": "/** One binding source per worker, shared by pricing and checkout, so one screen never acts on two\n *  different answers to the same question. */",
+        "decl": "export function sharedHostAppBindingSource(): AppBindingSource;"
       }
     ]
   },

package/guides/tokens.md

@@ -18,7 +18,7 @@ one registry, mirrored byte-for-byte by the iOS + Android decoders.
 | `motions` | name → { duration, easing?, spring? } | optional |
 | `materials` | name → { style, tint?, opacity?, blur? } | optional |
 | `tabBar` / `drawer` / `sidebar` | nav-chrome style blocks | optional |
-| `kit` | { material?, variant?, density?, motion? } | optional — the active design kit |
+| `kit` | { material?, variant?, density?, motion?, reduceMotion?, colorScheme? } | optional — the active design kit |
 | `contentMaxWidth` | { base, medium?, expanded? } | optional |
 | `elevations` | name → { level?, tint?, shadow?, border? } | optional — a Card wears `card` |
 | `controls` | { button?: { sm?, md?, lg?, variants? } } | optional — every Button's size and paint |
@@ -39,6 +39,27 @@ platform's own UI face — SF Pro on iOS/macOS, Roboto on Android, the system UI
 A color is a hex string, OR a per-scheme object `{ light, dark?, highContrast? }`. In the
 object form **`light` is required**; `dark`/`highContrast` fall back to it.
 
+## Light or dark — `kit.colorScheme`
+
+By default an app follows the device appearance. To pin it, set `kit.colorScheme` — it ships
+OTA with the tokens, so a published release re-skins installed apps without a new binary:
+
+| value | effect |
+|---|---|
+| `"system"` (or absent) | follow the device light/dark setting |
+| `"light"` | always light |
+| `"dark"` | always dark |
+
+Only those three lowercase values are recognised: another string counts as `"system"` and
+`himi validate` warns; a non-string (a number, a boolean) is an error, because it fails the
+whole tokens.json on device. The pin replaces only the device light/dark signal: an explicit
+in-app theme choice (`theme.set`, a host's own Appearance setting), a preview's scheme pin,
+and the OS high-contrast setting still win over it. Native chrome — the status bar and the
+navigation bar — follows the pin too. Binaries older than the core release that added it
+ignore the key and keep following the device. Set it in the top-level `kit` block (an idiom
+overlay cannot change it), merged into the existing block rather than replacing it; adopting a
+design kit keeps it.
+
 ## Motion
 
 `easing` is `linear`, `easeIn`, `easeOut`, `easeInOut`, `spring` or `emphasized` (Material 3's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1319.0",
+  "version": "0.1321.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": "60f160d9f74860a80bb7b1bedb582949eda4352aaf8909967561bac5"
+  "falconPackageHash": "3318113ec10ae018bbbe09e99bb3bef1207460516f9ca12d20e128ff"
 }

package/templates/branded-lite/dev/index.ts

@@ -85162,6 +85162,9 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                             "actionId": "tier5.himiBrandedProgram.enroll"
                           }
                         }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiBrandedProgram.enrollHidden"
                       }
                     },
                     {
@@ -85175,6 +85178,44 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                           "color": "textSecondary",
                           "collapseWhenEmpty": true
                         }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiBrandedProgram.enrollHidden"
+                      }
+                    },
+                    {
+                      "id": "himi_program.buy",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Button",
+                        "props": {
+                          "title": "$service:himiBrandedProgram.buyLabel",
+                          "style": "primary",
+                          "fullWidth": true,
+                          "disabledPath": "$service:himiBrandedProgram.buyDisabled",
+                          "action": {
+                            "actionId": "tier5.himiBrandedProgram.buy"
+                          }
+                        }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiBrandedProgram.buyHidden"
+                      }
+                    },
+                    {
+                      "id": "himi_program.buy_note",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Text",
+                        "props": {
+                          "text": "$service:himiBrandedProgram.buyNote",
+                          "style": "footnote",
+                          "color": "textSecondary",
+                          "collapseWhenEmpty": true
+                        }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiBrandedProgram.buyHidden"
                       }
                     },
                     {

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

@@ -1,49 +1,11 @@
-// Worker-side glue for the shared IAP catalog layer (`@himalaya/iap` → createIapCatalogPricing),
-// shared by every screen that shows or sells an IAP-backed item. Mapping, Apple prices and payment
-// guards live in the SDK; this only supplies the host scope, the copy, and the hydration reset.
-import { get as appInfo } from "@himalaya/app-info";
-import type { IapCatalogScope, IapPriceCopy } from "@himalaya/iap";
+// Worker-side glue for the shared IAP layer (`@himalaya/iap` catalog pricing and
+// `@himalaya/iap-checkout` → createIapCommerce), shared by every screen that shows or sells an
+// IAP-backed item. Mapping, Apple prices, payment guards, the host scope and the sale live in the
+// SDK; this only supplies the copy and the hydration reset.
+import type { IapPriceCopy } from "@himalaya/iap";
+import type { IapPurchaseCopy } from "@himalaya/iap-checkout";
 import { copyParam } from "./himi-copy.js";
 
-export interface HostIapScope {
-  scope: IapCatalogScope;
-  platform: string;
-}
-
-let hostScope: Promise<HostIapScope> | undefined;
-
-/** Read once per worker, and only by an enabled screen: a disabled one makes no app-info call.
- *  App identity and platform come from the host, never a screen param. The site is the host-owned
- *  native preference business (the web partition uses an OAuth client ID); without one, the mapping source's
- *  bound site applies. A failed read leaves identity empty, which fails every item closed — and is
- *  not kept, so the next lookup asks the host again instead of staying invalid for good. */
-export function hostIapScope(): Promise<HostIapScope> {
-  return hostScope ??= readHostScope().then((read) => {
-    if (!hostScopeComplete(read)) hostScope = undefined;
-    return read;
-  });
-}
-
-/** An incomplete scope prices every item `invalidInput`, which the shared layer never offers to
- *  retry — so a screen offers Retry itself while its own host read is what failed. */
-export function hostScopeComplete(read: HostIapScope): boolean {
-  return !!read.scope.appId && !!read.scope.bundleId && !!read.platform;
-}
-
-async function readHostScope(): Promise<HostIapScope> {
-  const identity = await appInfo().catch(() => undefined);
-  const siteId = identity?.platform === "web" ? "" : hostSiteId();
-  return {
-    scope: { appId: identity?.appId ?? "", bundleId: identity?.bundleId ?? "", ...(siteId ? { siteId } : {}) },
-    platform: identity?.platform ?? "",
-  };
-}
-
-function hostSiteId(): string {
-  const value = (globalThis as { himalaya?: { input?: Record<string, unknown> } }).himalaya?.input?.__himiPreferenceBusiness;
-  return typeof value === "string" ? value.trim() : "";
-}
-
 /** Price labels from the screen's copy pack (`<prefix>.priceLoadingText`, …). */
 export function iapPriceCopy(prefix: string): IapPriceCopy {
   return {
@@ -54,6 +16,21 @@ export function iapPriceCopy(prefix: string): IapPriceCopy {
   };
 }
 
+/** App Store purchase labels from the screen's copy pack (`<prefix>.buyCta`, …), for
+ *  `iapPurchaseFields`. Customer copy only: no backend names, ids or diagnostics. */
+export function iapPurchaseCopy(prefix: string): IapPurchaseCopy {
+  return {
+    buy: copyParam(`${prefix}.buyCta`, "Get access"),
+    processing: copyParam(`${prefix}.purchaseProcessingText`, "Processing your purchase…"),
+    awaitingApproval: copyParam(`${prefix}.purchaseAwaitingApprovalText`, "Waiting for approval"),
+    unavailable: copyParam(`${prefix}.purchaseTemporarilyUnavailableText`, "Purchasing is temporarily unavailable."),
+    signInRequired: copyParam(`${prefix}.purchaseSignInText`, "Sign in to buy."),
+    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."),
+  };
+}
+
 /** What `notHydrated` does, for a runtime that ignores the option (a binary older than it, still
  *  served new bundles): put the listed keys back to their declared values before any action runs,
  *  so a persisted price or an enabled purchase action never paints as this run's. */