@wix/himalaya-cli 0.1359.0 → 0.1360.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/ts/src/schema.d.ts

@@ -1955,6 +1955,12 @@ export interface PdfViewProps {
     zoomable?: boolean;
     allowShare?: boolean;
 }
+/**
+ * Inline video player. Needs the `media_playback` capability: the player lives in the native
+ * media module, which a binary links only when the app declares `media_playback` (in
+ * `capabilities` or `capabilityEnvelope`). Without it the component draws a sized placeholder,
+ * and `himi validate` rejects a screen that uses it.
+ */
 export interface VideoProps {
     url?: string;
     poster?: string;
@@ -2023,7 +2029,12 @@ export interface MediaPlayerAppearance {
     controlSize?: "compact" | "regular" | "large";
     cornerStyle?: "none" | "small" | "medium" | "large" | "pill";
 }
-/** RFC 0044 — the server-driven audio/video/podcast/provider player. */
+/**
+ * RFC 0044 — the server-driven audio/video/podcast/provider player. Needs the `media_playback`
+ * capability: the player lives in the native media module, which a binary links only when the
+ * app declares `media_playback` (in `capabilities` or `capabilityEnvelope`). Without it the
+ * component draws a sized placeholder, and `himi validate` rejects a screen that uses it.
+ */
 export interface MediaPlayerProps {
     sessionId?: string;
     items?: MediaItem[];
@@ -2075,7 +2086,10 @@ export interface MediaPlayerProps {
  * Lottie/Rive vector animation (motion grammar Batch 4). `source` is an https
  * URL to the animation JSON or the inline JSON string; it ships OTA. Native:
  * lottie-ios / lottie-compose; web: lottie-web. Reduced motion → static last
- * frame. Needs an explicit `height` to compose in scroll containers.
+ * frame. Needs an explicit `height` to compose in scroll containers. Needs the `animation`
+ * capability: Lottie lives in the native animation module, which a binary links only when the
+ * app declares `animation` (in `capabilities` or `capabilityEnvelope`). Without it the component
+ * draws a sized placeholder, and `himi validate` rejects a screen that uses it.
  */
 export interface LottieProps {
     source?: string;
@@ -2086,7 +2100,10 @@ export interface LottieProps {
 }
 /** A Rive animation (motion grammar, Phase-2). `source` = https .riv URL shipped OTA;
  *  `artboard`/`stateMachine` select within it. Native: rive-ios/rive-android; web:
- *  @rive-app/canvas (dynamic import). Reduced motion → static first frame. */
+ *  @rive-app/canvas (dynamic import). Reduced motion → static first frame. Needs the `animation`
+ *  capability: Rive lives in the native animation module, which a binary links only when the app
+ *  declares `animation` (in `capabilities` or `capabilityEnvelope`). Without it the component
+ *  draws a sized placeholder, and `himi validate` rejects a screen that uses it. */
 export interface RiveProps {
     source?: string;
     artboard?: string;

package/dist/cli.mjs

@@ -7650,7 +7650,6 @@ function buttonVariant(style) {
 var SYSTEM_FONT_FAMILY, TONAL_ELEVATION_ALPHA, BUTTON_MIN_HIT_TARGET, nonNegative, nonEmpty, own, COLOR_TOKEN_PROPS, TYPOGRAPHY_TOKEN_PROPS, BUTTON_VARIANTS;
 var init_tokens = __esm({
   "../../core/ts/src/tokens.ts"() {
-    "use strict";
     SYSTEM_FONT_FAMILY = "$system";
     TONAL_ELEVATION_ALPHA = [0, 0.05, 0.08, 0.11, 0.12, 0.14];
     BUTTON_MIN_HIT_TARGET = 44;
@@ -7706,7 +7705,6 @@ function resolveTranslation(value, catalog3, sourceCatalog) {
 var BINDING_SIGILS, BINDING_SIGIL_RE, TRANSLATION_PREFIX, TRANSLATION_KEY_RE;
 var init_bindings = __esm({
   "../../core/ts/src/bindings.ts"() {
-    "use strict";
     BINDING_SIGILS = ["service", "flag", "item", "t"];
     BINDING_SIGIL_RE = new RegExp(
       `^\\$(?:${BINDING_SIGILS.filter((s2) => s2 !== "t").join("|")})\\b|^\\$t:`

package/guides/app-config.md

@@ -17,6 +17,12 @@ A content package configures itself in three layers:
   prefix of `id`), `ports: { devServer, web }`, `schemaPackageRange: { min, max }`.
 - **Theming:** `designTokensPath` → tokens.json (the kit is chosen *inside* tokens.json's `kit` block).
 - `capabilities: Capability[]` — the app's declared native capabilities.
+- `capabilityEnvelope?: Capability[]` — the native BUILD envelope, a superset of `capabilities`. The
+  binary is built for `capabilities ∪ capabilityEnvelope` (usage strings, entitlements, permissions and
+  the native modules those capabilities link), so a later release can turn an envelope capability on
+  over the air by widening `capabilities` — within the envelope only; beyond it needs a new binary.
+  `capabilities ⊆ capabilityEnvelope` is enforced (`himi validate` and `defineApp` error on an id
+  outside it). Omitted ⇒ defaults to `capabilities`. `himi docs capabilities` has the details.
 - `navigation: NavigationConfig`.
 - `entities: Record<string, EntityConfig>` — **required**, and `entities: {}` is the normal value.
   Each entry is a build-time DOMAIN entity and its cache materialization shape (`{ file }` or
@@ -115,6 +121,12 @@ with a native footprint only arrives with a new binary. `himi docs capabilities`
 loop — discover, declare, validate, ship — and `himi capabilities <id>` shows the import and which
 shells' binaries serve it.
 
+Declared capabilities also decide which native modules link into the binary: a capability the build
+does not include answers `module_not_linked` on device. Some components need one — `Video`,
+`MediaPlayer` and `CarBrowse` need `media_playback`, `Lottie` and `Rive` need `animation` —
+and `himi validate` errors on a screen that uses one the app does not declare.
+`presigned_upload.putFile` also requires `files` on the calling screen.
+
 App-level capability vocabulary: `camera`, `barcode_scanner`, `biometrics`, `secure_storage`, `share`, `push`, `file_picker`, `files`, `open_url`, `pdf`, `clipboard`, `theme`, `photos`, `presigned_upload`, `ui`, `calendar`, `contacts`, `tasks`, `audio_record`, `audio_record_background`, `calls`, `location`, `location_background`, `motion`, `health`, `media_playback`, `webview`, `browser_auth`, `haptic`, `himi_apps`, `iap`, `keyboard`, `wix_cashier`, `live_activity`, `local_database`, `speech`, `speaker_diarization`, `system_intents`, `on_device_ai`, `app_info`, `release_control`, `godot`, `base44`, `animation`.
 
 ## What `himi validate` checks (7 passes)

package/guides/capabilities.md

@@ -59,6 +59,40 @@ 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.
 
+### Headroom for later: `capabilityEnvelope`
+
+`capabilities` is what the app serves today, and by default it is also what the binary is built
+for. To be able to turn a capability on later **without a new binary**, list it in
+`capabilityEnvelope` as well — the native build envelope, a superset of `capabilities`:
+
+```ts
+// config.ts — the binary carries camera's usage string and permission; the app serves only push today
+capabilities: ["push"],
+capabilityEnvelope: ["push", "camera"],
+```
+
+- The binary is built for `capabilities ∪ capabilityEnvelope`: every id in the envelope gets its
+  usage strings, entitlements, permissions and native module, **where applicable** (ids such as
+  `secure_storage` or `share` add none of these), even before `capabilities` lists it.
+- `capabilities ⊆ capabilityEnvelope` is enforced when `capabilityEnvelope` is **present**:
+  `himi validate` (and `defineApp`) reports an error for an id in `capabilities` that the envelope
+  lacks, because no install would carry its
+  native config. A background variant in the envelope covers its foreground capability.
+- Turning a capability on over the air means widening `capabilities` **within** the envelope and
+  pushing. Going beyond the envelope still needs a new binary and a store resubmission.
+- Omit `capabilityEnvelope` and it defaults to `capabilities` — the smallest binary.
+
+### Capabilities that need another capability
+
+- **`presigned_upload.putFile` requires `files`.** `putFile` uploads a file from the app's document
+  store, so the screen that calls it must declare `files` too (and so must `config.ts`). Without
+  it the worker gate refuses `capability.presigned_upload.putFile` on iOS, macOS, Android and the
+  web. Declaring `presigned_upload` grants none of the files surface, and `put` (bytes the worker
+  already holds) needs only `presigned_upload`.
+- **Some components need a capability** — `Video`, `MediaPlayer`, `CarBrowse`, `Lottie` and
+  `Rive` render through a native module, so the app must declare the capability that links
+  it. See [Components that need a capability](#components-that-need-a-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
@@ -87,10 +121,14 @@ The `capabilities` pass reports:
 - an **unknown id** (a typo such as `camara`) — an error, with a suggestion;
 - a bundle that **calls a capability its screen does not declare**;
 - a capability a screen declares that **`config.ts` `capabilities` is missing**;
-- when the app names its shell, a capability **that shell's binary does not serve**.
-
-An undeclared call is a warning, and an error under `--strict`. The last two describe the binary
-rather than your content, so they stay warnings — except a mismatch with the shared Himi Player
+- when the app names its shell, a capability **that shell's binary does not serve**;
+- an id in `capabilities` that a **present** `capabilityEnvelope` is missing — an error (omitting
+  the field defaults it to `capabilities`, so it can never trip);
+- a screen using a **component whose native module the app does not link** (`Video` without
+  `media_playback`, `Lottie` without `animation`, …) — an error.
+
+An undeclared call is a warning, and an error under `--strict`. The missing app-level id and the
+shell mismatch describe the binary rather than your content, so they stay warnings — except a mismatch with the shared Himi Player
 binary, which is always an error: one binary hosts every app, and no content change can add to it.
 
 Name the shell your app ships in once, in `himalaya.content.json`, and both `himi validate` and
@@ -137,9 +175,18 @@ prompt.
   it "needs a new `himi dist`" — the installed binary cannot call it until you rebuild.
 - **"needs a new binary".** A successful `himi dist` remembers what its binary was built with —
   on the job (`buildCapabilities`) and in your package (`.himi/last-dist.json`). From then on
-  `himi push` prints `needs a new binary: <ids> — run himi dist` when the release declares an id
-  that build lacks, a following device's draft offer says the same, and `himi validate` compares
-  against that build rather than the committed shell.
+  `himi validate` compares against that build rather than the committed shell, and `himi push`
+  checks every release against it:
+  - a release that declares a **permission-bearing** capability (an iOS usage string or
+    entitlement, an Android permission — camera, location, push, …) the last dist lacks is
+    **refused**: the push fails with 409 `binary_capability_gap`, naming the missing ids and each
+    platform's last dist that lacks them. An over-the-air push cannot add an OS permission, and on
+    iOS asking for one whose purpose string is missing kills the app. Run `himi dist` first, or
+    pass `--allow-binary-gap` when every installed binary already carries it (the release records
+    `allowedBinaryGap`). `himi push --only` and `himi patch` refuse the same way;
+  - a gap in a **permission-free** capability (share, clipboard, …) does not block: the push
+    prints `needs a new binary: <ids> — run himi dist`, and a following device's draft offer says
+    the same.
 - **Never a silent strip.** On iOS, a capability whose entitlement the signing profile cannot grant
   fails the dist job, naming the capability — the binary would otherwise build green and fail on
   the first call. The minted profile's Apple capabilities are derived from the build's own set.
@@ -150,11 +197,88 @@ prompt.
   attach it to an expense." }` — or the build uses a generic one, which App Review often rejects.
 - **What a build cannot add.** `player` (Himi Player — one binary for every app) and `demo-app` are
   fixed: a release declaring an id they do not serve is refused with `shell_capability_mismatch`,
-  naming shells that can carry it. On an extensible shell, an id with no core handler, or one that
-  needs wiring a build cannot do (`local_database` needs the app's data schema installed first,
-  `live_activity` a widget extension target, `base44` / `godot` an opt-in SDK, `wix_platform` boot
-  configuration), is refused with `unsupported_capability` and the reason. `health` is addable:
-  the build links HealthKit and Health Connect, and `permissionCopy.health` is the iOS purpose
-  string and the Health Connect rationale. A shell that does not carry a capability's usage
-  string can crash the app at the permission prompt, which is why both the build and
-  `himi validate` check before you ship.
+  naming shells that can carry it. On an extensible shell, a build links any capability whose
+  native module the platform ships (see [Native modules](#6-native-modules-what-a-capability-links))
+  and installs its handlers at boot. What it cannot do is the per-app **boot wiring** a few
+  capabilities need beyond that registration, so these are refused with `unsupported_capability`
+  and the reason:
+
+  | Id | Why a build cannot add it |
+  |---|---|
+  | `local_database` | the shell has to install the app's data schema first — registering it without one would store declared-encrypted entities in plaintext |
+  | `live_activity` | needs a WidgetKit extension target in the shell's project |
+  | `wix_platform` | the shell's boot has to configure it with a Wix API client and launch services |
+  | `himi_apps` | a multi-app host surface (Himi Player), not something one app's binary serves |
+  | `app_info` | the shell's boot has to configure it with the app id it reports |
+  | `system_intents` | the shell has to wire the system-intents host (app identity, deep-link routing, refresh) |
+  | `release_control` | the shell's boot has to configure it with the app id whose releases it switches |
+  | `base44` | the shell's boot has to bind the Base44 app it talks to; the module links, the binding is the shell's |
+  | `godot` | needs the shell's game surface view and, on Android, the shell's pick of the engine's C++ runtime |
+
+  An id with no handler on both iOS and Android is refused the same way. Everything else with a
+  native module is addable — `health` (the build links HealthKit and Health Connect, and
+  `permissionCopy.health` is the iOS purpose string and the Health Connect rationale), `iap`,
+  `calls` (the WebRTC engine), `animation`, `media_playback` and the rest. A shell that does not
+  carry a capability's usage string can crash the app at the permission prompt, which is why both
+  the build and `himi validate` check before you ship.
+
+## 6. Native modules: what a capability links
+
+A capability whose native code pulls in a permission-gated OS framework or a third-party library
+(HealthKit, StoreKit, WebRTC, Lottie and Rive, the media player, …) lives in its own native module.
+**The capabilities your app declares decide which native code is linked into its binary**: a
+build links a module only when its build set — `capabilities ∪ capabilityEnvelope`, plus what
+`himi dist` bakes in — contains a capability the module serves. Everything else stays out, so the
+binary carries neither the code nor the store-review footprint of a framework it does not use.
+
+| Module | Linked by |
+|---|---|
+| animation | `animation` |
+| audio (iOS) | `audio_record`, `audio_record_background` |
+| base44 | `base44` |
+| biometrics | `biometrics` |
+| calendar | `calendar` |
+| calls | `calls` |
+| contacts | `contacts` |
+| godot | `godot` |
+| health | `health` |
+| iap | `iap` (and `wix_cashier` on iOS) |
+| live_activity | `live_activity` |
+| location | `location`, `location_background` |
+| location_background (iOS) | `location_background` |
+| media | `media_playback` |
+| motion | `motion` |
+| on_device_ai (iOS) | `on_device_ai` |
+| push | `push` |
+| speech (iOS) | `speech` |
+| tasks (iOS) | `tasks` |
+
+What that means for a worker:
+
+- **Undeclared means not linked.** The `capability.<id>.*` verbs always exist in the core, so the
+  declaration gate and the call shape are the same in every binary. In a binary that does not link
+  the module, the verbs answer `module_not_linked`: a permission check reports `denied` with
+  `reason: "module_not_linked"`, and other verbs reject with `unavailable: module_not_linked`.
+  The fix is to declare the capability and ship a new binary — not to retry.
+- **Treat it like any other declined capability.** `himi test` already exercises the
+  unavailable path; a worker that handles a denied camera handles an unlinked module too.
+
+### Components that need a capability
+
+A few components draw through a native module. A screen that uses one in an app whose build set
+does not link that module would render a component whose library is not in the binary, so
+`himi validate` reports an **error** naming the component and the capabilities that would link it.
+
+| Component | Needs | Without it |
+|---|---|---|
+| `Video` | `media_playback` | sized placeholder |
+| `MediaPlayer` | `media_playback` | sized placeholder |
+| `CarBrowse` — the Android Auto media browse tree | `media_playback` | no car media surface |
+| `Lottie` | `animation` | sized placeholder |
+| `Rive` | `animation` | sized placeholder |
+
+`animation` has no verbs and no permission: it exists only so the build links Lottie and Rive.
+Add it to `capabilityEnvelope` instead of `capabilities` if a later release may start using
+those components. A release whose screens use one of these components also requires the
+capability from its host, so a Player binary that does not link the module refuses the release
+instead of drawing placeholders.

package/guides/component-reference.json

@@ -1212,6 +1212,7 @@
       "name": "Video",
       "category": "Cross-cutting & media",
       "propsType": "VideoProps",
+      "requiresCapability": "media_playback",
       "bindings": [],
       "notImplemented": {
         "props": [
@@ -1261,6 +1262,7 @@
       "name": "MediaPlayer",
       "category": "Cross-cutting & media",
       "propsType": "MediaPlayerProps",
+      "requiresCapability": "media_playback",
       "bindings": [
         "itemsPath"
       ],
@@ -1320,6 +1322,7 @@
       "name": "Lottie",
       "category": "Rich vector & celebration (motion grammar Batch 4)",
       "propsType": "LottieProps",
+      "requiresCapability": "animation",
       "bindings": [],
       "propsSource": "export interface LottieProps {\n  source?: string;\n  loop?: boolean;\n  autoplay?: boolean;\n  speed?: number;\n  height?: number;\n}"
     },
@@ -1327,6 +1330,7 @@
       "name": "Rive",
       "category": "Rich vector & celebration (motion grammar Batch 4)",
       "propsType": "RiveProps",
+      "requiresCapability": "animation",
       "bindings": [],
       "propsSource": "export interface RiveProps {\n  source?: string;\n  artboard?: string;\n  stateMachine?: string;\n  autoplay?: boolean;\n  height?: number;\n}"
     },

package/guides/component-reference.md

@@ -2012,6 +2012,8 @@ export interface VideoProps {
 }
 ```
 
+> **Needs the `media_playback` capability.** It renders through a native module the binary links only when `config.ts` declares `media_playback` (in `capabilities` or `capabilityEnvelope`). Without it the component draws a sized placeholder, and `himi validate` rejects a screen that uses it.
+
 > ⚠️ **Implemented, but these props are inert on ios:** `poster` — `poster` is not shown.
 
 #### PdfView
@@ -2084,6 +2086,8 @@ export interface MediaPlayerProps {
 }
 ```
 
+> **Needs the `media_playback` capability.** It renders through a native module the binary links only when `config.ts` declares `media_playback` (in `capabilities` or `capabilityEnvelope`). Without it the component draws a sized placeholder, and `himi validate` rejects a screen that uses it.
+
 > ⚠️ **Not implemented on ios:** `autoplayVisibilityThreshold`, `preload`, `playbackRates`, `showQueue`, `showChapters`, `showTranscript` — `autoplayVisibilityThreshold` is ignored (whenVisible = once on appear). `preload` is ignored. `playbackRates` is ignored, and the queue/chapters/transcript panels never render.
 
 > ⚠️ **Not implemented on android:** `externalPlayback`, `appearance`, `allowCellular`, `preload`, `playbackRates`, `showQueue`, `showChapters`, `showTranscript` — `externalPlayback` is forced off. `appearance` is ignored. `allowCellular` is ignored. `preload` is ignored. `playbackRates` is ignored, and the queue/chapters/transcript panels never render.
@@ -2104,6 +2108,8 @@ export interface LottieProps {
 }
 ```
 
+> **Needs the `animation` capability.** It renders through a native module the binary links only when `config.ts` declares `animation` (in `capabilities` or `capabilityEnvelope`). Without it the component draws a sized placeholder, and `himi validate` rejects a screen that uses it.
+
 #### Rive
 
 ```ts
@@ -2116,6 +2122,8 @@ export interface RiveProps {
 }
 ```
 
+> **Needs the `animation` capability.** It renders through a native module the binary links only when `config.ts` declares `animation` (in `capabilities` or `capabilityEnvelope`). Without it the component draws a sized placeholder, and `himi validate` rejects a screen that uses it.
+
 #### MonthCalendar
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1359.0",
+  "version": "0.1360.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": "8b9cac99029b9f7bced8bd984c585ef4ce4cd8b5fe5290a8bfb7a34d"
+  "falconPackageHash": "0a238e262e21ac93a2e8120f032811ae402c599e5b3e208cd0def547"
 }