@wix/himalaya-cli 0.1242.0 → 0.1244.0

package/guides/getting-started.md

@@ -218,6 +218,12 @@ mapper writes the site's light colour into the dark arm too, so dark mode is whe
 To create/publish/invoke the site's Velo HTTP functions, `himi docs wix-site-http-functions`
 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.
+
 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

@@ -247,6 +247,12 @@ mapper writes the site's light colour into the dark arm too, so dark mode is whe
 To create/publish/invoke the site's Velo HTTP functions, `himi docs wix-site-http-functions`
 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.
+
 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

@@ -1,225 +1,176 @@
-# Shared Apple IAP pricing
-
-`@himalaya/iap` resolves read-only payment mappings and retrieves Apple metadata for
-cards, details, and checkout previews. It neither buys anything nor proves access.
-The mapping provider is an internal client port; a deployed production backend is
-still required. Do not call the purchase-delivery coordinator for price lookup.
-
-## Inputs and states
-
-Create one controller per worker/service with `createPricingController({ mapping,
-getProducts, onState })`. Inject the existing SDK `getProducts` as the real store
-adapter; tests may inject another function. `load(input)` accepts:
-
-- `scope`: app ID, bundle ID, Wix site ID, and optional opaque `contextRevision`.
-  Change the revision whenever a member/audience change affects mapping. Pass no
-  credential or raw member identity.
-- `platform`: the actual trusted host platform. Only `ios` resolves Apple prices.
-- `items`: `{ reference: { kind, id }, commerceDisplayPrice? }`. References are
-  unique by the pair; repeated references retain the first occurrence and its
-  commerce input. Different entity kinds cannot collide.
-
-The injected batch `mapping.resolve({ scope, references })` returns one mapping
-per requested reference: `appleIap` with `productId` and `mappingRevision`,
-`regular`, or `unavailable`. Missing, duplicate, unknown, or malformed routes are
-unresolved. This is not an agreed Scala wire contract or a deployed endpoint.
-
-`getState()` returns a detached serializable snapshot with revision, captured
-scope, and per-reference items. Loading and unavailable items contain **no price**.
-Apple ready items carry `source: "appleIap"`, product ID, mapping revision, and
-exact StoreKit `displayPrice`; regular ready items carry `source: "regular"` and
-the caller's existing commerce price. Copy remains the screen's responsibility.
-When that commerce price is missing or blank, `commercePriceUnavailable` is
-non-retryable: the caller must supply a usable price in a new `load(input)`.
-Refreshing the same input cannot supply it.
-
-Apple strings are displayed unchanged, including spaces and currency placement;
-they are not reconstructed from micros or phone locale. See Apple's
-[displayPrice contract](https://developer.apple.com/documentation/storekit/product/displayprice).
-Only non-consumables are supported here. A lookup failure, empty response, missing
-product, or blank price is `priceUnavailable`, not proof of a network failure or
-nonexistent product: the current native adapter collapses store errors into `[]`.
-There is never a Wix price or external-checkout fallback for an Apple route.
-
-`load` batches unique Apple IDs and joins identical work already in flight within
-this controller. Input identity includes scope, platform, item order/references,
-and commerce display prices. Every call after completion performs a fresh lookup.
-`refresh()` reloads the last captured input, also joining identical in-flight work.
-Changing input invalidates prior work before its results can publish; obsolete
-mapping results do not start a store lookup. `dispose()` clears readable state,
-suppresses later publications/calls, and cannot cancel store/network I/O already
-sent. No persistent or app-wide cache exists; separate workers perform independent
-lookups.
-
-## Complete Tier-5 service example
-
-This example is compiled and executed by `pricing-integration.test.ts` against the
-actual worker bootstrap and SDK dispatch seam. Register it separately in each
-screen worker, injecting the mapping provider and trusted initial input. It is a
-checkout **preview**: purchase readiness stays false independently of metadata.
+# Showing App Store prices on any screen
 
-```ts
-// pricing-worker.ts
-import { defineService } from "@himalaya/state";
-import {
-  createPricingController, getProducts,
-  type PricingInput, type PricingMappingProvider, type PricingState,
-} from "@himalaya/iap";
-
-export interface PriceCopy {
-  loading: string;
-  unavailable: string;
-  apple: string;
-  regular: string;
-}
+`@himalaya/iap` gives every screen one shared way to show the App Store price of an item it
+displays or sells: a program, a product, a plan, or anything else you registered with
+`himi store iap`. Your worker passes its scope and the items on screen. The shared layer looks up
+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.
 
-interface PriceRow {
-  id: string;
-  status: "loading" | "ready" | "unavailable";
-  displayPrice: string;
-  message: string;
-  retryable: boolean;
-  loading: boolean;
-  hideLoading: boolean;
-  hideRetry: boolean;
-}
+> **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.
+> Only one-time purchases (non-consumables) are supported. Subscriptions and consumables are not.
 
-interface PriceServiceState {
-  pricing: PricingState;
-  rows: PriceRow[];
-  canPurchase: boolean;
-  purchaseDisabled: boolean;
-}
+## What you get per item
 
-export function registerPricingService(
-  mapping: PricingMappingProvider, initialInput: PricingInput, copy: PriceCopy,
-) {
-  let input = initialInput;
-  let disposed = false;
-  const controller = createPricingController({
-    mapping, getProducts,
-    onState: () => { void service.publish(); },
-  });
+`pricing.view(reference)` returns plain data you can put in state. Its `route` tells the screen
+what to do:
+
+| `route` | Show | Existing checkout |
+|---|---|---|
+| `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 |
+| `regular` | `displayPrice` (the commerce price you passed), or nothing | Allowed |
+| `unavailable` | "Price unavailable", plus Retry when `retryable` | Blocked |
+
+Never fall back to your own price or checkout for an item on an App Store route. A missing price
+does not mean the item is free. Only an explicit `regular` route keeps your existing flow.
+
+`iapPriceFields(view, copy)` turns a view into bindable fields (`priceText`, `priceNote`,
+`priceLoading`, `hidePriceRetry`, `actionDisabled`, `actionNote`) using labels from your own copy.
+
+## Catalog references
+
+An item is identified by `{ kind, id }`. The kind is the same entity type `himi store iap` uses
+when it registers the item with Apple:
+
+| `kind` | Item | Helper |
+|---|---|---|
+| `onlineProgram` | An Online Programs program | `onlineProgramItem(program, commercePrice)` |
+| `storesProduct` | A Wix Stores product | Build `{ kind: "storesProduct", id }` |
+| `pricingPlan` | A one-time Pricing Plans plan | Build `{ kind: "pricingPlan", id }` |
+
+## Add it to a worker
+
+This is a complete worker for one screen. Copy the pattern, not the course names.
 
-  function project(pricing: PricingState): PriceRow[] {
-    return pricing.items.map(item => ({
-      id: JSON.stringify([item.reference.kind, item.reference.id]),
-      status: item.status,
-      displayPrice: item.status === "ready" ? item.displayPrice : "",
-      message: item.status === "loading" ? copy.loading : item.status === "unavailable"
-        ? copy.unavailable : item.source === "appleIap" ? copy.apple : copy.regular,
-      retryable: item.status === "unavailable" && item.retryable,
-      loading: item.status === "loading",
-      hideLoading: item.status !== "loading",
-      hideRetry: item.status !== "unavailable" || !item.retryable,
-    }));
+```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";
+
+const COPY = {
+  loading: "Loading price…",
+  unavailable: "Price unavailable",
+  oneTimePurchase: "One-time purchase",
+  purchaseUnavailable: "Purchasing is not available yet.",
+};
+// This run's prices and buy state must never be restored from a cold-boot snapshot.
+const PRICE_KEYS = ["priceText", "priceNote", "hidePriceRetry", "buyDisabled", "buyNote"];
+
+interface Course { id: string; title: string; commercePrice: string }
+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(); } });
+  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 ?? "" };
   }
 
-  const actions = {
-    start: (state: PriceServiceState) => ({ ...state, _poll: {
-      id: "pricing", action: "pricing.reload", intervalMs: 60_000, immediate: true,
-    } }),
-    publish: (state: PriceServiceState) => {
-      const pricing = controller.getState();
-      return { ...state, pricing, rows: project(pricing), canPurchase: false, purchaseDisabled: true };
-    },
-    reload: async () => {
-      if (!disposed) await controller.load(input);
-      // Publication uses a separate reducer; returning captured state would race.
-      return undefined;
-    },
-    retry: async () => {
-      if (!disposed) await controller.refresh();
-      return undefined;
-    },
-    setInput: async (_state: PriceServiceState, next: PricingInput) => {
-      if (!disposed) { input = next; await controller.load(input); }
-      return undefined;
-    },
-    dispose: (state: PriceServiceState) => {
-      disposed = true;
-      controller.dispose();
-      return { ...state, pricing: controller.getState(), rows: [], canPurchase: false, purchaseDisabled: true };
+  async function loadPrices() {
+    if (pricing.enabled) await pricing.load({ ...(await hostScope()), items: [item] });
+    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);
+    return { ...state, priceText: price.priceText, priceNote: price.priceNote, hidePriceRetry: price.hidePriceRetry && !scopeIncomplete,
+      buyDisabled: price.actionDisabled, buyNote: price.actionNote, message };
+  }
+
+  const service = defineService("course", {
+    state: { title: course.title, priceText: "", priceNote: "", hidePriceRetry: true, buyDisabled: pricing.enabled, buyNote: "", message: "" } as CourseState,
+    notHydrated: pricing.enabled ? PRICE_KEYS : [],
+    actions: {
+      // The screen starts the first lookup; the host's poll and Retry only refresh one that exists.
+      start: (state: CourseState) => {
+        void loadPrices();
+        return { ...present(state), _poll: pricing.pollDirective("course.refreshPrice") };
+      },
+      publish: (state: CourseState) => present(state),
+      // Re-reads the host too: `pricing.refresh()` would replay a scope whose identity read failed.
+      refreshPrice: async () => { await loadPrices(); return undefined; },
+      buy: async () => {
+        // Re-check at the moment of the mutation: a price refresh can change the route after render.
+        // While a refresh resolves the route is unknown, so refuse without claiming anything.
+        const start = pricing.checkoutGuard(item.reference);
+        if (start.allowed) message = await startCheckout();
+        else message = start.route === "resolving" ? "" : COPY.purchaseUnavailable;
+        void service.publish();
+        return undefined;
+      },
     },
-  };
-  const initialPricing: PricingState = { ...controller.getState(), items: initialInput.items.map(item => ({
-    reference: { kind: item.reference.kind, id: item.reference.id }, status: "loading",
-  })) };
-  const service = defineService<PriceServiceState, typeof actions>("pricing", {
-    state: { pricing: initialPricing, rows: project(initialPricing), canPurchase: false, purchaseDisabled: true },
-    notHydrated: ["pricing", "rows", "canPurchase", "purchaseDisabled"], actions,
   });
   void service.start();
   return service;
 }
 ```
 
-The bundle must declare `iap`. To derive platform/app identity from the host,
-declare `app_info` too and call `@himalaya/app-info.get()` before registering the
-service. Use its `platform`, `appId`, and `bundleId`, with the caller's site and
-opaque context revision. If the call rejects or identity is absent, keep the
-Apple route unavailable; never assume iOS. Its `environment: dev | prod` describes
-Himalaya serving, **not** Apple Sandbox/production. Do not introduce an app-info
-dependency into the pricing package itself.
-
-Bind price text to `$service:pricing.rows.0.displayPrice` for a single card/detail/
-checkout item, and use the existing bound list template for multiple rows. Bind
-loading visibility to `hideLoading`, Retry visibility to `hideRetry`, and the
-purchase button's `disabledPath` to `$service:pricing.purchaseDisabled`. The Retry
-action is `tier5.pricing.retry`. Existing Text, ActivityIndicator, and Button components
-are sufficient; keep labels in the consuming copy pack and use stable component
-IDs. Regular commerce route/checkout remains owned by the existing commerce flow.
-
-## Lifecycle and purchase boundaries
-
-The service arms `_poll` at module evaluation with an immediate first load and a
-60-second visible cadence. The **host** schedules it: worker JS has no ordinary
-timers. Current iOS pooling pauses off-screen polls, resumes immediately on return,
-and the lifecycle scheduler pauses in the background and fires on resume. Worker
-teardown cancels polling. `_poll` has no explicit stop directive; a disposed
-service ignores subsequent ticks until its worker is destroyed.
-
-Use the same module-evaluation registration on card, detail, and checkout entry;
-checkout opens with a fresh controller/lookup, or call `reload` if retaining its
-controller. Route supported caller scope/reference changes through `setInput`.
-Do not use descriptor `onAppear` as a reliable iOS return callback: retained
-screens do not necessarily remount. Prices and derived fields must be excluded
-from persisted worker hydration, as above, on hosts supporting `notHydrated`.
-
-Every new lookup clears the amount immediately. A failed periodic/background
-refresh shows unavailable with Retry rather than keeping a prior amount as freshly
-confirmed. Overlapping entry, poll, checkout, and Retry requests join matching
-in-flight work. No polling continues while the iOS host has pooled/backgrounded
-the worker.
-
-No Storefront update bridge is implemented in this slice. Supported invalidations
-refresh prices; a storefront change while visible may remain undetected until the
-next poll or explicit refresh. This does not establish immediate storefront
-notification. Native `Storefront.updates` remains a separate follow-up.
-
-Price metadata is not purchase authorization or entitlement. A future activated
-checkout must compare its purchase context's Apple product ID with the displayed
-ready state; if they differ, refresh mapping/price and show the new amount before
-allowing purchase. The existing purchase coordinator remains unchanged, and this
-preview never invokes it. Mapping fixtures and their failure scenarios belong only
-in the local demonstration. Production mapping, checkout activation, and template
-migration are still required before rollout.
-
-The dedicated iOS LiftGear QA binary opts into the existing managed transaction
-API before shared capability registration. Its native identity requires both
-`com.alexchudnovsky.liftgear` and baked app
-`alexanderch3.fit-gear-2-push-test`; the tenant is `liftgear-sandbox-lab`.
-This opt-in cannot be selected by worker input, member identity, or OTA content.
-Other Branded Lite identities retain their existing registration behavior.
-For this dedicated QA identity, a pinned baked config with the
-`liftgear-pricing` scheme and a pricing-card home supplies the navigation menu
-and initial screen. This keeps the embedded demonstration visible after an
-update over an existing LiftGear installation or a live config refresh, without
-changing stored member data or managed purchase policy. Ordinary or incomplete
-baked configs continue to use the cached navigation. This is a bounded preview
-host rule, not a general fix for distribution release routing.
-The separate, explicitly armed purchase demonstration calls
-`purchaseForVerification` with a labelled synthetic association, reports Apple's
-actual transaction environment, and leaves the transaction unfinished. It has
-no transaction-server integration or program-access delivery. Pricing alone
-does not arm the demonstration or start a purchase.
+Bind the fields in the screen descriptor and declare both 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"] },
+  "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" } },
+               "modifiers": { "hiddenPath": "$service:course.hidePriceRetry" } },
+  "buy":     { "type": "Button", "props": { "title": "Enrol", "disabledPath": "$service:course.buyDisabled",
+               "action": { "actionId": "tier5.course.buy" } } },
+  "buyNote": { "type": "Text",   "props": { "text": "$service:course.buyNote", "collapseWhenEmpty": true } }
+}
+```
+
+## Rules
+
+- **One pricing instance per worker, one `load` per set of visible items.** Pass every item the
+  screen shows in a single call; the layer batches the lookup and fetches each Apple product once.
+- **Guard the action, not only the button.** Call `checkoutGuard` immediately before a commerce flow
+  starts; actions can run without a tap. Before each later step of a flow that already started (a
+  payment after a join or reservation), call `continueCheckoutGuard`: it lets the step through on the
+  route the last lookup settled, so a routine refresh cannot strand the flow halfway, and stops it
+  once a refresh settles on an App Store route. If the flow pays through `payOrder` from
+  `@wix/himalaya/checkout`, pass the same check as `mayCharge`; it runs again right before the wallet
+  charges and before the hosted cashier opens.
+- **One writer.** Publish through a synchronous action that reads `pricing.view` at that moment.
+  An async action that returns its own state can land after a newer price and repaint a stale one.
+- **No timers.** `pollDirective` asks the app to refresh every 60 seconds while the screen is
+  visible and on return to it. Point it and Retry at an action that reads the host and calls `load`
+  again, so a failed identity read recovers; `refresh` replays the last scope unchanged. Every
+  lookup clears the old price first.
+- **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.
+
+## Adopting it
+
+- **Starter templates with Online Programs** (`branded-lite`, `yoga-studio`) already include it on
+  their Programs list and program screens.
+- **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.
+- **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.
+
+## What turns it on
+
+Register your digital products with `himi store iap` (see `himi docs iap-products`). When Wix
+connects the mapping service those registrations feed, screens that use this layer start showing
+App Store prices on their next build — in an app that grants the `iap` capability in `config.ts`.
+Screens that do not use the layer are unaffected.

package/guides/index.json

@@ -20,6 +20,7 @@
   ],
   "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.",
     "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.",
@@ -178,12 +179,6 @@
       "category": "Workers & SDKs",
       "file": "capabilities.md"
     },
-    {
-      "id": "iap-pricing",
-      "title": "Apple IAP pricing in a worker",
-      "category": "Workers & SDKs",
-      "file": "iap-pricing.md"
-    },
     {
       "id": "wix-api-usage",
       "title": "Call Wix APIs from a worker",
@@ -327,6 +322,12 @@
       "title": "Registering digital products as App Store in-app purchases",
       "category": "CLI & Loop",
       "file": "iap-products.md"
+    },
+    {
+      "id": "iap-pricing",
+      "title": "Showing App Store prices on any screen",
+      "category": "Workers & SDKs",
+      "file": "iap-pricing.md"
     }
   ],
   "componentReferenceFile": "component-reference.json",

package/guides/sdk-reference.json

@@ -1777,6 +1777,102 @@
         "jsdoc": "/** Creates one worker's read-only pricing controller with injected mapping, store lookup, and state publication. */",
         "decl": "export function createPricingController(deps: PricingDependencies): PricingController;"
       },
+      {
+        "name": "IAP_CATALOG_KINDS",
+        "kind": "const",
+        "jsdoc": "/** The Wix entity types `himi store iap` writes into its Wix→Apple mapping, so a mapping\n *  backend can serve that export without translating kinds. */",
+        "decl": "export const IAP_CATALOG_KINDS = [\"onlineProgram\", \"storesProduct\", \"pricingPlan\"] as const;"
+      },
+      {
+        "name": "IapCatalogKind",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type IapCatalogKind = typeof IAP_CATALOG_KINDS[number];"
+      },
+      {
+        "name": "IapCatalogItem",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapCatalogItem {\n  reference: CatalogReference;\n  /** The screen's own formatted commerce price; shown only on an explicit regular route. */\n  commerceDisplayPrice?: string;\n}"
+      },
+      {
+        "name": "IapCatalogScope",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapCatalogScope {\n  appId: string;\n  bundleId: string;\n  /** Wix metaSiteId. Omit it to use the connected mapping source's bound site. */\n  siteId?: string;\n  contextRevision?: string;\n}"
+      },
+      {
+        "name": "IapCatalogInput",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapCatalogInput {\n  scope: IapCatalogScope;\n  /** The host's own platform (from `@himalaya/app-info`); only \"ios\" resolves Apple prices. */\n  platform: string;\n  items: IapCatalogItem[];\n}"
+      },
+      {
+        "name": "IapPaymentRoute",
+        "kind": "type",
+        "jsdoc": "/** `disabled` means no backend is connected: the screen's existing commerce behavior applies. */",
+        "decl": "export type IapPaymentRoute = \"disabled\" | \"regular\" | \"appleIap\" | \"resolving\" | \"unavailable\";"
+      },
+      {
+        "name": "IapItemView",
+        "kind": "interface",
+        "jsdoc": "/** Serializable per-item state a screen binds. Carries no credential, transaction or entitlement. */",
+        "decl": "export interface IapItemView {\n  reference: CatalogReference;\n  route: IapPaymentRoute;\n  /** Apple: StoreKit's string verbatim. Regular: the caller's commerce price. Otherwise \"\". */\n  displayPrice: string;\n  reason?: PricingUnavailableReason;\n  retryable: boolean;\n  /** True only when the existing commerce checkout may run: disabled or an explicit regular route. */\n  canStartRegularCheckout: boolean;\n  /** Apple purchasing is not available until a backend verifies transactions. */\n  purchasable: false;\n}"
+      },
+      {
+        "name": "IapCheckoutDecision",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapCheckoutDecision {\n  allowed: boolean;\n  route: IapPaymentRoute;\n}"
+      },
+      {
+        "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}"
+      },
+      {
+        "name": "IapPollDirective",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapPollDirective {\n  id: string;\n  action: string;\n  intervalMs: number;\n  immediate: boolean;\n}"
+      },
+      {
+        "name": "IapCatalogPricing",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapCatalogPricing {\n  readonly enabled: boolean;\n  /** Batched mapping + Apple lookup for the items a screen shows. */\n  load(input: IapCatalogInput): Promise<void>;\n  refresh(): Promise<void>;\n  view(reference: CatalogReference): IapItemView;\n  /** May a commerce flow START now? Re-read immediately before the first mutation: the route as it\n   *  is now, so a refresh in flight (`resolving`) blocks. */\n  checkoutGuard(reference: CatalogReference): IapCheckoutDecision;\n  /** May a flow that already STARTED take its next commerce step (e.g. pay after a join)? While no\n   *  new answer exists (a refresh in flight, or a mapping backend that did not answer) it uses the\n   *  route the last settled lookup gave for the current scope, so a routine refresh cannot strand a\n   *  regular checkout halfway; any new answer other than regular stops it. */\n  continueCheckoutGuard(reference: CatalogReference): IapCheckoutDecision;\n  /** The host-scheduled visible refresh; undefined while disabled. */\n  pollDirective(action: string): IapPollDirective | undefined;\n  dispose(): void;\n}"
+      },
+      {
+        "name": "IapPriceCopy",
+        "kind": "interface",
+        "jsdoc": "/** Labels come from the screen's copy pack; the shared layer only chooses between them. */",
+        "decl": "export interface IapPriceCopy {\n  loading: string;\n  unavailable: string;\n  oneTimePurchase: string;\n  purchaseUnavailable: string;\n}"
+      },
+      {
+        "name": "IapPriceFields",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapPriceFields {\n  priceText: string;\n  priceNote: string;\n  priceLoading: boolean;\n  hidePriceRetry: boolean;\n  actionDisabled: boolean;\n  actionNote: string;\n}"
+      },
+      {
+        "name": "createIapCatalogPricing",
+        "kind": "function",
+        "jsdoc": "/** One screen worker's catalog pricing. Activation comes only from the connected mapping\n *  source, so a screen cannot turn Apple prices on by supplying its own mapping. */",
+        "decl": "export function createIapCatalogPricing(options: { onChange?(): void } = {}): IapCatalogPricing;"
+      },
+      {
+        "name": "iapPriceFields",
+        "kind": "function",
+        "jsdoc": "/** Bindable display state for one item. A screen spreads these into its own state and binds\n *  them; the labels stay in the screen's copy pack. */",
+        "decl": "export function iapPriceFields(view: IapItemView, copy: IapPriceCopy): IapPriceFields;"
+      },
+      {
+        "name": "onlineProgramItem",
+        "kind": "function",
+        "jsdoc": "/** An Online Programs program as a shared IAP catalog item. A program without a Wix ID cannot be\n *  mapped (a title fallback is not an identity), so it has no item and its screen shows no price. */",
+        "decl": "export function onlineProgramItem(program: { id?: string | null }, commerceDisplayPrice?: string): IapCatalogItem | undefined;"
+      },
       {
         "name": "ProductType",
         "kind": "type",

package/guides/tier-5-add-a-screen.md

@@ -479,6 +479,15 @@ This is what makes the fail-closed capability gates readable. `local_database: e
 "X" is not declared in the app's dataSchema` is a message written to be read — before
 #2288 an author only ever saw an eternal spinner.
 
+### Show App Store prices for catalog items
+
+A screen that shows or sells a program, product or plan that may be an App Store in-app purchase
+does not look up mappings or Apple prices itself. It uses the shared catalog layer
+(`createIapCatalogPricing` in `@himalaya/iap`), which also hands it the `_poll` directive below and
+the guards a commerce flow must call: `checkoutGuard` before it starts, `continueCheckoutGuard`
+before each later step. The adoption guide, with a compiled and tested
+worker example, is `himi docs iap-pricing` ([iap-pricing-for-screens.md](iap-pricing-for-screens.md)).
+
 ### Refresh on a cadence with `_poll` (the worker has no clock)
 
 A worker is a pure reducer with **no `setTimeout` and no `setInterval`** — its sandbox

package/guides/tokens.md

@@ -21,6 +21,7 @@ one registry, mirrored byte-for-byte by the iOS + Android decoders.
 | `kit` | { material?, variant?, density?, motion? } | 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 |
 
 ## ⚠️ Typography requires `size`, `weight`, AND `line`
 
@@ -96,3 +97,30 @@ by copying its `tokens` into tokens.json; the active kit's app-wide axes
 is a hairline inside the edge (default 0.5). Declare none and Cards stay flat. To look native on
 each platform, declare `"card": {}` and let the idiom overlays fill it: `material` a `level`,
 `ios` a `border` + `shadow`.
+
+## Buttons (`controls.button`)
+
+Restyle every `Button` of one size or one style from the design system — no per-screen props:
+
+```json
+"controls": {
+  "button": {
+    "sm": { "height": 36, "paddingH": 13, "paddingV": 6, "text": "bodyEmphasis", "icon": 14 },
+    "variants": { "secondary": { "radius": 4, "borderWidth": 1 }, "primary": { "fill": "brand" } }
+  }
+}
+```
+
+- **Per size** (`sm` / `md` / `lg`): `height` (the VISIBLE minimum height), `paddingH`,
+  `paddingV`, `text` (a `typography` token), `icon` (glyph size), `radius`.
+- **Per variant** (`variants.<style>`, e.g. `primary`, `secondary`, `tertiary`, `destructive`):
+  `fill`, `label`, `border` (colour tokens or `#hex`), `borderWidth` (0 = no outline), `radius`
+  (wins over the size's).
+- Every field is optional. An absent field keeps the built-in Button, so a tokens.json without
+  `controls` renders exactly as before. `Button.cornerRadius` / `Button.minHeight` on a node
+  still win over the tokens.
+- The **44pt tap target stays**: a `height` under 44 gets a transparent hit area above and below
+  (web: a hit band, React Native: `hitSlop`, iOS/macOS: a padded content shape, Android: Material
+  3's 48dp touch target), so a 36px `sm` button still passes accessibility.
+- `himi validate` errors when `text` names no `typography` token, or a colour names no
+  `colors` token.