@wix/himalaya-cli 0.1320.0 → 0.1322.0

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/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;"
       }
     ]
   },
@@ -4176,6 +4188,18 @@
         "jsdoc": "",
         "decl": "export interface PageCapabilityResponse {\n  v: 1;\n  id: string;\n  ok: boolean;\n  result?: unknown;\n  error?: { message: string; code?: string };\n}"
       },
+      {
+        "name": "PAGE_HANDSHAKE_CAPABILITY",
+        "kind": "const",
+        "jsdoc": "/** `call(\"himalaya\", \"capabilities\")` answers `{ v: 1, capabilities: { <id>: [<method>…] } }`:\n *  exactly the allowlist this worker was given. Reserved, so no real capability can take it. */",
+        "decl": "export const PAGE_HANDSHAKE_CAPABILITY = \"himalaya\";"
+      },
+      {
+        "name": "PAGE_HANDSHAKE_METHOD",
+        "kind": "const",
+        "jsdoc": "",
+        "decl": "export const PAGE_HANDSHAKE_METHOD = \"capabilities\";"
+      },
       {
         "name": "ExposedPageCapability",
         "kind": "interface",
@@ -4228,9 +4252,27 @@
       {
         "name": "call",
         "kind": "function",
-        "jsdoc": "/** Invoke one method through the companion worker. Primarily useful to generated bindings. */",
+        "jsdoc": "/** Invoke one method through the companion worker. Primarily useful to generated bindings.\n *  A call that shows native UI (a permission prompt, the share sheet) answers only when the user\n *  is done with it: pass a long `timeoutMs` (e.g. 120_000) rather than the 30-second default. */",
         "decl": "export function call<T>(\n  capability: string,\n  method: string,\n  args: unknown[] = [],\n  timeoutMs = 30_000,\n): Promise<T>;"
       },
+      {
+        "name": "enabledCapabilities",
+        "kind": "function",
+        "jsdoc": "/**\n * The capabilities and methods this page's companion worker answers, as `{ <id>: [<method>…] }`;\n * `null` outside the app, when the app is older than the handshake, or nothing answered in\n * `timeoutMs`. A list is remembered (and returned at once, whatever `timeoutMs`); a miss is not,\n * because a worker that is still booting drops the first messages.\n */",
+        "decl": "export async function enabledCapabilities(timeoutMs = 3_000): Promise<Record<string, string[]> | null>;"
+      },
+      {
+        "name": "isEnabled",
+        "kind": "function",
+        "jsdoc": "/** Whether the companion worker lets this page call `capability.method`, read from\n *  enabledCapabilities() — nothing is called. `false` when there is no list. */",
+        "decl": "export async function isEnabled(capability: string, method: string, timeoutMs = 3_000): Promise<boolean>;"
+      },
+      {
+        "name": "probe",
+        "kind": "function",
+        "jsdoc": "/** For an app older than the handshake: CALL `capability.method` and report whether it answered\n *  (even with an error). It runs the method, so pass only a read-only one. */",
+        "decl": "export async function probe(capability: string, method: string, args: unknown[] = [], timeoutMs = 3_000): Promise<boolean>;"
+      },
       {
         "name": "himalaya",
         "kind": "const",
@@ -23096,12 +23138,12 @@
         "name": "StoreProductSearch",
         "kind": "interface",
         "jsdoc": "/** User-facing product discovery. V3 name search/sorting belong to Search\n * Products; Query Products deliberately does not support the name field.\n * V1 uses its documented JSON-string filter/sort dialect. */",
-        "decl": "export interface StoreProductSearch {\n  query?: string;\n  sort?: 'default' | 'az' | 'za';\n  ids?: string[];\n  limit?: number;\n  cursor?: string;\n  /** Extra v3 fieldsets. Additive — widens the default, never replaces it. */\n  fields?: readonly string[];\n}"
+        "decl": "export interface StoreProductSearch {\n  query?: string;\n  sort?: 'default' | 'az' | 'za';\n  ids?: string[];\n  /**\n   * Only products in this category (V3) / collection (V1) — a category screen's\n   * \"products in X\". ANDed with `ids` when both are given.\n   *\n   * V3 matches `allCategoriesInfo.categories`, so a parent category also lists its\n   * subcategories' products, as the site does. Only Search Products can filter by\n   * category — Query Products answers `not declared as filterable` — so a\n   * `categoryId` always routes the V3 read to `/products/search`. V1 matches\n   * `collections.id`.\n   */\n  categoryId?: string;\n  limit?: number;\n  cursor?: string;\n  /** Extra v3 fieldsets. Additive — widens the default, never replaces it. */\n  fields?: readonly string[];\n}"
       },
       {
         "name": "searchStoreProducts",
         "kind": "function",
-        "jsdoc": "",
+        "jsdoc": "/**\n * Search, sort, and filter products on whichever catalog this site runs — the read\n * behind a shop list, a saved-products list, and a category screen.\n *\n * `categoryId` narrows to one category's products (V3 `allCategoriesInfo`, so a parent\n * category includes its subcategories; V1 `collections.id`), ANDed with `ids`. An\n * empty `ids` array resolves to an empty page WITHOUT a request. Paging is one\n * contract on both catalogs: pass back `pagingMetadata.cursors.next` as `cursor`.\n * A non-catalog failure (401/403, offline) rejects; it is never retried on V1.\n */",
         "decl": "export async function searchStoreProducts(options: StoreProductSearch = {}): Promise<StoreProductsResponse>;",
         "http": "POST /stores/v1/products/query"
       },

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/guides/web-page-native-sdk.md

@@ -31,19 +31,30 @@ Your page can only use capabilities the **app owner** turned on for your site. I
 
 - `capabilities` — the capability ids your page will call (see the
   [Web page SDK reference](https://apps.wix.com/_api/himi-serve/docs/web-page-sdk-reference.md) for every id and method).
-- `permissionCopy` — the sentence the phone shows when it asks the user for permission. Write it
-  for the end user, about what *they* get.
+- `permissionCopy` — optional: the sentence the phone shows when it asks the user for permission,
+  at most 500 characters. Write it for the end user, about what *they* get. Only capabilities that
+  prompt need one (Health, camera, photos, location, microphone…); `haptic` and `share` never ask,
+  and a capability left out gets the app's built-in generic sentence.
 - No worker code is needed. Brandy generates the companion worker that answers your page from
-  `capabilities`, allowing every method the capability's page lists — except
+  `capabilities`, allowing **every** method the capability's page lists — except
   `presigned_upload.putFile`, which reads a device file and is allowed only when `files` is enabled
-  too. (An owner who wants a
-  narrower allowlist can still name their own worker in `bundle`.)
+  too. So enabling a capability is enough; the owner does not list methods.
 - Enabling a capability changes the app's native permissions, so the owner ships a **new app
   build** with it before your page can call it. Until then the call times out.
 
-When you hand work to the app owner, give them the list as `capability.method` pairs, for example
-`health.availability`, `health.requestPermission`, `health.query`, `haptic.play`. A method that is
-not on the allowlist never answers — your call times out (see *Errors*).
+**You cannot enable anything from the page, or with any public command.** The app owner is
+whoever builds the app (for an app Wix builds for a customer, the team that ships it). Hand them a
+request they can act on without asking you anything back — for example:
+
+> Please enable these web page capabilities for `https://www.example.com` in the app's `webSdk`
+> provisioning and ship a new build: `["health", "haptic", "share"]`, with
+> `permissionCopy.health` = "Show your step count for today." The page checks what is enabled and
+> hides the rest, so it is safe to ship before the build.
+
+An owner who wrote their own companion worker (named in `webSdk.bundle`) chooses methods one by
+one: for that app only, add the exact `capability.method` pairs your page calls, for example
+`health.availability`, `health.requestPermission`, `health.query`, `haptic.play`. A method that
+worker does not allow never answers — your call times out (see *Errors*).
 
 Your page must be served from the site origin the app was built for. Pages in iframes, and pages
 reached through a redirect to another origin, do not get the bridge.
@@ -100,7 +111,12 @@ export function isInHimiApp(): boolean {
   return bridge() !== undefined;
 }
 
-/** Call one native method, e.g. call("health", "query", [{ type: "steps", from, to }]). */
+/**
+ * Call one native method, e.g. call("health", "query", [{ type: "steps", from, to }]).
+ * A call that shows native UI (a permission prompt, the share sheet) answers only when the user is
+ * done: give it a long timeoutMs, such as 120_000. Never wait without a deadline — a message the app
+ * drops (see "Keep what you send small") gets no answer at all.
+ */
 export function call<T = unknown>(capability: string, method: string, args: unknown[] = [], timeoutMs = 30_000): Promise<T> {
   const target = bridge();
   if (!target) return Promise.reject(new HimalayaError("Not running inside a Himi app", "not_in_app"));
@@ -119,8 +135,86 @@ export function call<T = unknown>(capability: string, method: string, args: unkn
   });
 }
 
-/** True when `capability.method` answers within `timeoutMs`. Use a read-only method. */
-export async function isEnabled(capability: string, method: string, args: unknown[] = [], timeoutMs = 3_000): Promise<boolean> {
+let manifest: { on: Bridge; list: Record<string, string[]> } | undefined;
+
+let asking: { on: Bridge; until: number; answer: Promise<Record<string, string[]> | null> } | undefined;
+
+/**
+ * ONE question loop per bridge, however many callers wait on it: every message counts against the
+ * app's rate limit, so twenty gated controls must not ask twenty times a second. It asks every
+ * half second until the latest caller's deadline (a message sent before the app is ready is lost);
+ * each question listens for 2 s, so a slow answer still lands and at most four are in flight.
+ */
+function askShared(target: Bridge, budget: number): Promise<Record<string, string[]> | null> {
+  const until = Date.now() + budget;
+  if (asking?.on === target) {
+    asking.until = Math.max(asking.until, until);
+    return asking.answer;
+  }
+  const state = { on: target, until, answer: Promise.resolve<Record<string, string[]> | null>(null) };
+  asking = state; // before the first ask: a loop that ends at once must clear itself
+  state.answer = new Promise((resolve) => {
+    let done = false;
+    const finish = (list: Record<string, string[]> | null) => {
+      if (done) return;
+      done = true;
+      clearInterval(again);
+      if (asking === state) asking = undefined;
+      if (list) manifest = { on: target, list };
+      resolve(list);
+    };
+    const ask = () => {
+      if (done) return;
+      const left = state.until - Date.now();
+      if (left <= 0 || bridge() !== target) return finish(null); // deadline, or the page's bridge changed
+      call<{ capabilities?: Record<string, string[]> }>("himalaya", "capabilities", [], Math.max(1, Math.min(2_000, left))).then(
+        (reply) => finish(reply?.capabilities ?? null),
+        // A timed-out question is not an answer; the deadline decides. Anything else is final.
+        (error) => { if (!(error instanceof HimalayaError && error.code === "timeout")) finish(null); },
+      );
+    };
+    const again = setInterval(ask, 500);
+    ask();
+  });
+  return state.answer;
+}
+
+/**
+ * What this app lets the page call, as { capability: [method, …] }. null outside the app, in an app
+ * build older than this question, or when nothing answered within timeoutMs. A list is remembered
+ * (and returned at once, whatever timeoutMs); a miss is not, because an app that is still starting
+ * drops the first messages.
+ */
+export async function enabledCapabilities(timeoutMs = 3_000): Promise<Record<string, string[]> | null> {
+  const target = bridge();
+  if (!target) return null;
+  if (manifest?.on === target) return manifest.list;
+  if (!(timeoutMs > 0)) return null; // no time to ask: nothing can answer
+  // setTimeout cannot wait longer than 2^31-1 ms (a longer delay fires at once), so clamp it.
+  const budget = Math.min(timeoutMs, 2_147_483_647);
+  const answer = askShared(target, budget);
+  // This caller's own deadline; the shared question may keep going for a caller who waits longer.
+  return new Promise((resolve) => {
+    const stop = setTimeout(() => resolve(manifest?.on === target ? manifest.list : null), budget);
+    void answer.then((list) => { clearTimeout(stop); resolve(list); });
+  });
+}
+
+/**
+ * True when the app lets the page call `capability.method`, read from enabledCapabilities(): nothing
+ * is called and nothing happens on the phone. false when there is no list (outside the app, an app
+ * build older than the list, or no answer yet).
+ */
+export async function isEnabled(capability: string, method: string, timeoutMs = 3_000): Promise<boolean> {
+  const enabled = await enabledCapabilities(timeoutMs);
+  return enabled?.[capability]?.includes(method) ?? false;
+}
+
+/**
+ * For an app build older than enabledCapabilities(): CALL `capability.method` and report whether the
+ * app answered it (even with an error). It runs the method, so pass only a read-only one.
+ */
+export async function probe(capability: string, method: string, args: unknown[] = [], timeoutMs = 3_000): Promise<boolean> {
   try {
     await call(capability, method, args, timeoutMs);
     return true;
@@ -154,15 +248,15 @@ Capability ids are snake_case (`health`, `haptic`, `secure_storage`, `local_data
 names are exactly the SDK's function names. Arguments and results are plain JSON.
 
 ```ts
-import { himalaya, HimalayaError } from "./lib/himalaya";
+import { call, himalaya, HimalayaError } from "./lib/himalaya";
 
 // Light, fire-and-forget feedback.
 await himalaya.haptic.play("success");
 
-// Health: check, ask (from a button tap), then read.
+// Health: check, ask (from a button tap), then read. The prompt waits for the user: allow two minutes.
 const { available } = await himalaya.health.availability();
 if (available) {
-  await himalaya.health.requestPermission({ read: ["steps"] });
+  await call("health", "requestPermission", [{ read: ["steps"] }], 120_000);
   const midnight = new Date();
   midnight.setHours(0, 0, 0, 0);
   const { samples } = await himalaya.health.query({
@@ -174,13 +268,21 @@ if (available) {
 ```
 
 `call("health", "availability")` is the same thing without the proxy, and is handy when the
-capability or method name is a variable.
+capability or method name is a variable — or when you need a timeout other than the 30-second
+default. **Give every call that shows native UI a long deadline** — `call(..., 120_000)` for a
+permission prompt, the share sheet, the camera or a photo picker: it answers when the user is
+done, and the 30-second default can turn a slow user into a `timeout` your page reads as "not
+enabled". Keep a deadline even there: a message the app drops gets no answer at all.
+
+`steps`, `activeEnergy` and `distance` come back summed (one sample for the whole range, or one
+per `bucket: "hour" | "day"`), and `heartRate` averaged; summing `samples` for a total is right
+either way.
 
 ## Step 3 — React pattern
 
 ```tsx
 import { useEffect, useState } from "react";
-import { call, himalaya, isInHimiApp, HimalayaError } from "./lib/himalaya";
+import { call, himalaya, isEnabled, isInHimiApp, HimalayaError } from "./lib/himalaya";
 
 export function StepsCard() {
   const [state, setState] = useState<"checking" | "browser" | "off" | "ready" | "denied" | "failed">("checking");
@@ -188,8 +290,10 @@ export function StepsCard() {
 
   useEffect(() => {
     if (!isInHimiApp()) return setState("browser");
-    // Answering is not enough: a phone without a health store answers { available: false }.
-    call<{ available: boolean }>("health", "availability", [], 3_000)
+    // Enabled for this site? Answered from the app's list, without calling anything.
+    isEnabled("health", "availability")
+      .then((on) => (on ? call<{ available: boolean }>("health", "availability", [], 3_000) : { available: false }))
+      // Enabled is not enough: a phone without a health store answers { available: false }.
       .then(({ available }) => setState(available ? "ready" : "off"))
       // Not enabled for this site (timeout) hides the feature; any other failure offers a retry.
       .catch((error) => setState(error instanceof HimalayaError && error.code === "timeout" ? "off" : "failed"));
@@ -197,7 +301,7 @@ export function StepsCard() {
 
   async function connect() {
     try {
-      await himalaya.health.requestPermission({ read: ["steps"] });
+      await call("health", "requestPermission", [{ read: ["steps"] }], 120_000); // waits for the user
       const from = new Date(); from.setHours(0, 0, 0, 0);
       const { samples } = await himalaya.health.query({ type: "steps", from: from.toISOString(), to: new Date().toISOString() });
       setSteps(samples.reduce((sum: number, s: { value: number }) => sum + s.value, 0));
@@ -232,9 +336,21 @@ The same page must keep working in an ordinary browser (and in Base44 / Lovable
   device (`availability()` tells you). Show a calm fallback, not an error. On iOS a denied Health
   **read** is not reported as `not_authorized`: the read succeeds with no samples, exactly like a
   day with no data. Word an empty result so it also covers "access is off".
-- **Hide features the app doesn't enable.** Probe once with `isEnabled(...)` on a read-only method
-  and hide the UI when it is `false`. `true` only means the method is enabled — still read its
-  answer (`availability()` can say `{ available: false }`).
+- **Hide features the app doesn't enable.** Check with `isEnabled(capability, method)` and hide the
+  UI when it is `false`. The app answers from its list of enabled capabilities
+  (`enabledCapabilities()`), so nothing is called and nothing happens on the phone — this works
+  for `haptic.play` too. An app build older than that list has none, so `isEnabled` answers
+  `false` there. To support such a build, fall back to `probe(capability, method)`, which **calls**
+  the method — use it only with a read-only one (`health.availability`, never `haptic.play`).
+  `true` only means the method is enabled — still read its answer (`availability()` can say
+  `{ available: false }`).
+- **Ask for a permission once, then trust the result you read.** `health.requestPermission`
+  resolves with `{ granted }`, but on iOS a read type counts as granted once asked, whatever the
+  user chose — so read the data and treat an empty result as "no data or access off". The phone
+  shows each permission prompt once; asking again answers without showing anything.
+- **Check for the app when you need it.** In current app builds the bridge exists before your
+  first script runs. On an older Android System WebView it is added as the page loads, so call
+  `isInHimiApp()` where you use it (for example in `useEffect`), not once at module load.
 - **Plain JSON only.** Arguments and results cross as JSON: no functions, `Date` objects (use ISO
   strings), `Blob`s or class instances.
 - **Keep what you send small.** The app checks every message a page sends and silently drops one
@@ -258,7 +374,7 @@ Every failure rejects with a `HimalayaError` that has a `code`:
 | `code` | Meaning | What to do |
 |---|---|---|
 | `not_in_app` | Ordinary browser or preview, no bridge | Render the browser fallback |
-| `timeout` | No answer: capability or method not enabled for this site, not on this app build, or the message broke a size rule (see *Keep what you send small*) | Check your arguments; otherwise hide the feature and ask the app owner to enable `capability.method` |
+| `timeout` | No answer within `timeoutMs`: capability or method not enabled for this site, not on this app build, or the message broke a size rule (see *Keep what you send small*). A call that shows native UI can also time out while the user is still looking at it — give it a long `timeoutMs` (`120_000`) | Check your arguments; otherwise hide the feature and ask the app owner to enable the capability |
 | `bridge_refused` | The app's bridge refused the message outright | Retry later; send less often |
 | `not_authorized` | The user denied permission | Explain how to enable it in Settings |
 | `unavailable` | Not supported on this device | Hide the feature |
@@ -275,6 +391,8 @@ Codes other than the first three come from the capability itself; its reference
 
   ```ts
   const answers: Record<string, unknown> = {
+    // What the app answers when the page asks which capabilities it may call.
+    "himalaya.capabilities": { v: 1, capabilities: { health: ["availability", "query", "requestPermission"], haptic: ["play"] } },
     "health.availability": { available: true },
     "health.requestPermission": undefined,
     "health.query": { samples: [{ value: 4200 }] },
@@ -289,21 +407,24 @@ Codes other than the first three come from the capability itself; its reference
 
   Never ship the fake: a page that defines `HimalayaWorker` itself is lying to its own feature
   checks.
-- **On a phone** — open the page inside the app build the owner configured. Check each feature
-  once with permission granted and once denied.
+- **On a phone** — there is no public preview app that carries your site's capabilities: ask the
+  app owner for an installable test build of the app with your capabilities enabled, open your
+  page inside it, and check each feature once with permission granted and once denied. Until then,
+  the fake bridge above is the test.
 
 ## More recipes
 
 Each uses the client from Step 1. The exact types are on each capability's page (see *Reference*).
 
 ```ts
-import { himalaya, HimalayaError } from "./lib/himalaya";
+import { call, himalaya } from "./lib/himalaya";
 
-// Share a link through the phone's share sheet (from a tap).
-const { completed } = await himalaya.share.share({ text: "Join me on Friday", url: "https://example.com/e/42" });
+// Share a link through the phone's share sheet (from a tap). The sheet waits for the user: allow two minutes.
+// Outside the app, fall back to the browser's own share (or copy the link).
+const { completed } = await call<{ completed: boolean }>("share", "share", [{ text: "Join me on Friday", url: "https://example.com/e/42" }], 120_000);
 
 // Where am I? Ask first, then read once. getCurrent answers null when no fix arrives in time.
-const status = await himalaya.location.requestPermission();
+const status = await call("location", "requestPermission", [], 120_000);
 if (status === "granted") {
   const here = await himalaya.location.getCurrent({ timeoutMs: 10_000 });
   if (here) console.log(here.lat, here.lng, `±${here.accuracy}m`);
@@ -315,7 +436,7 @@ const saved = await himalaya.secure_storage.read("refresh-token"); // string | n
 
 // Scan a QR code with the camera (iOS). null when the user cancels — and always on Android,
 // which has no built-in QR decoder — so keep a way to type the code in.
-const code = (await himalaya.camera.scanQR()) ?? window.prompt("Enter the code");
+const code = (await call<string | null>("camera", "scanQR", [], 120_000)) ?? window.prompt("Enter the code");
 ```
 
 **Files arrive as handles.** Methods that return a photo, recording or file give you a
@@ -324,15 +445,15 @@ You cannot put it in an `<img>` directly. Hand it to another call that takes one
 save it to the photo library:
 
 ```ts
-const [photo] = await himalaya.photos.pick({ limit: 1 });
-if (photo) await himalaya.share.share({ files: [photo] });
+const [photo] = await call<any[]>("photos", "pick", [{ limit: 1 }], 120_000);
+if (photo) await call("share", "share", [{ files: [photo] }], 120_000);
 ```
 
 To get the bytes into the page, read them with the `files` capability (the app owner must enable
 it too). `files.readBase64` returns the contents as base64, up to 8 MiB:
 
 ```ts
-const [photo] = await himalaya.photos.pick({ limit: 1 });
+const [photo] = await call<any[]>("photos", "pick", [{ limit: 1 }], 120_000);
 if (photo) {
   const base64 = await himalaya.files.readBase64(photo);
   const img = document.createElement("img");