@wix/himalaya-cli 0.1359.0 → 0.1361.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

@@ -28057,6 +28057,7 @@ __export(capabilities_exports, {
   capabilityConfigFindings: () => capabilityConfigFindings,
   capabilityInfo: () => capabilityInfo,
   capabilityIssues: () => capabilityIssues,
+  capabilityRemedy: () => capabilityRemedy,
   contentShell: () => contentShell,
   envelopeSubsetIssues: () => envelopeSubsetIssues,
   formatCapability: () => formatCapability,
@@ -28065,6 +28066,7 @@ __export(capabilities_exports, {
   isShell: () => isShell,
   lastDistFromJob: () => lastDistFromJob,
   needsBinaryNotice: () => needsBinaryNotice,
+  notInBinaryReason: () => notInBinaryReason,
   readLastDist: () => readLastDist,
   shellDistAdds: () => shellDistAdds,
   shellServes: () => shellServes,
@@ -28109,6 +28111,8 @@ function capabilityInfo(rawId, sdkRef = []) {
   const pkgs = PACKAGES[id] ?? [...new Set((CAPABILITY_IMPLIES[id] ?? []).flatMap((i2) => PACKAGES[i2] ?? []))];
   const ios = iosPlanFor([id]);
   const android = androidPlanFor([id]);
+  const modules = modulesOf(id);
+  const refusal = distAddRefusal(id);
   return {
     id,
     import: [...pkgs],
@@ -28118,9 +28122,30 @@ function capabilityInfo(rawId, sdkRef = []) {
     ios: { info: ios.info, entitlements: ios.entitlements },
     android: { permissions: android.permissions, features: android.features.map((f2) => f2.name) },
     shells: Object.fromEntries(SHELLS.map((s2) => [s2, shellSupport(s2, id)])),
-    declare: DECLARE_HINT
+    declare: DECLARE_HINT,
+    description: summaryOf2(pkgs, sdkRef),
+    implies: [...CAPABILITY_IMPLIES[id] ?? []],
+    modules,
+    components: Object.entries(COMPONENT_MODULES).filter(([, m2]) => modules.some((x2) => x2.id === m2)).map(([component]) => component).sort(),
+    distAddable: refusal === null,
+    distAddRefusal: refusal
   };
 }
+function modulesOf(id) {
+  return NATIVE_MODULES.filter((m2) => {
+    const caps = capabilitiesOfModule(m2);
+    return caps.ios.includes(id) || caps.android.includes(id);
+  }).map((m2) => ({
+    id: m2.id,
+    ...m2.ios ? { ios: m2.ios.product } : {},
+    ...m2.android ? { android: m2.android.project } : {}
+  }));
+}
+function summaryOf2(pkgs, sdkRef) {
+  const d2 = pkgs.map((p2) => sdkRef.find((s2) => s2.name === p2)?.description ?? "").find((x2) => x2.trim()) ?? "";
+  const first = /^[\s\S]*?[.!?](?=\s|$)/.exec(d2.trim())?.[0] ?? d2.trim();
+  return first.replace(/\s+/g, " ").slice(0, 200);
+}
 function allCapabilities(sdkRef = []) {
   return KNOWN_CAPABILITY_IDS.map((id) => capabilityInfo(id, sdkRef));
 }
@@ -28179,22 +28204,53 @@ function needsBinaryNotice(json6) {
 function noImportLabel(id) {
   return BRIDGE_CAPABILITY_IDS.includes(id) || id === "wix_platform" ? "a bridge capability (no @himalaya import of its own)" : "declare-only (no @himalaya import of its own)";
 }
-function formatCapability(c2) {
+function notInBinaryReason(c2, shell) {
+  const s2 = SHELL_CAPABILITIES[shell];
+  if (s2 && !s2.extensible) {
+    return `${s2.shared ? "one shared binary" : "a fixed binary"} \u2014 only a new ${shell} build adds it; a content package cannot`;
+  }
+  return c2.distAddRefusal ? `a dist build cannot add it: ${c2.id} ${c2.distAddRefusal}` : "a dist build would add it";
+}
+function capabilityRemedy(c2, shell) {
+  const sel = shell ? SHELL_CAPABILITIES[shell] : void 0;
+  if (shell && sel && !sel.extensible && c2.shells[shell] !== "serves") {
+    return `${shell} is ${sel.shared ? "one shared binary" : "a fixed binary"} \u2014 only a new ${shell} build adds ${c2.id}; \`himi dist\` and an OTA push cannot. Or pick a shell whose binary already serves it (${SHELLS.filter((x2) => c2.shells[x2] === "serves").join(", ") || "none today"}).`;
+  }
+  if (!c2.distAddable) {
+    const serves = SHELLS.filter((s2) => c2.shells[s2] === "serves");
+    return `pick a shell whose binary already serves it (${serves.join(", ") || "none today"}) \u2014 a dist build cannot add it (${c2.id} ${c2.distAddRefusal}).`;
+  }
+  if (!c2.needsNativeBuild) return "declare it; `himi dist` registers it in an extensible shell that does not yet.";
+  return "a NEW binary (`himi dist`) \u2014 declare it in config.ts `capabilities`, or list it in `capabilityEnvelope` to build it in now and turn it on later over the air. An OTA push alone cannot add it.";
+}
+function formatCapability(c2, shell) {
   const lines = [`${c2.id}  \u2014  ${c2.import.length ? `import from ${c2.import.join(" or ")}` : noImportLabel(c2.id)}`];
+  if (c2.description) lines.push(`  about:    ${c2.description}`);
   if (c2.exports.length) lines.push(`  exports:  ${c2.exports.join(", ")}`);
   if (c2.verbs.length) lines.push(`  verbs:    ${c2.verbs.map((v2) => `capability.${c2.id}.${v2}`).join(", ")}`);
+  if (c2.implies.length) lines.push(`  implies:  ${c2.implies.join(", ")} (declaring ${c2.id} grants it)`);
   lines.push(`  declare:  ${c2.declare}`);
   const iosKeys = [...Object.keys(c2.ios.info), ...Object.keys(c2.ios.entitlements)];
   const androidKeys = [...c2.android.permissions, ...c2.android.features];
   lines.push(
     c2.needsNativeBuild ? `  binary:   needs a NATIVE build \u2014 iOS ${iosKeys.join(", ") || "(nothing)"}; Android ${androidKeys.join(", ") || "(nothing)"}. An OTA push cannot add it.` : "  binary:   no native footprint \u2014 works in any shell that registers its handler."
   );
+  lines.push(
+    c2.modules.length ? `  module:   ${c2.modules.map((m2) => `${m2.id} (${[m2.ios && `iOS ${m2.ios}`, m2.android && `Android ${m2.android}`].filter(Boolean).join(", ")})`).join("; ")}` + (c2.components.length ? ` \u2014 also needed by the ${c2.components.join(", ")} component${c2.components.length === 1 ? "" : "s"}` : "") : "  module:   none \u2014 its native code is in the core runtime"
+  );
+  lines.push(`  dist:     ${c2.distAddable ? "a `himi dist` build can add it to an extensible shell" : `cannot be added at dist \u2014 ${c2.id} ${c2.distAddRefusal}`}`);
   const serves = SHELLS.filter((s2) => c2.shells[s2] === "serves");
   const adds = SHELLS.filter((s2) => c2.shells[s2] === "dist-adds");
   const not = SHELLS.filter((s2) => c2.shells[s2] === "not-in-binary");
+  const byReason = /* @__PURE__ */ new Map();
+  for (const s2 of not) {
+    const r2 = notInBinaryReason(c2, s2);
+    byReason.set(r2, [...byReason.get(r2) ?? [], s2]);
+  }
   lines.push(
-    `  shells:   served by ${serves.join(", ") || "none"}` + (adds.length ? `; \`himi dist\` adds it to ${adds.join(", ")}` : "") + (not.length ? `; NOT in the ${not.join(", ")} binary` : "")
+    `  shells:   served by ${serves.join(", ") || "none"}` + (adds.length ? `; \`himi dist\` adds it to ${adds.join(", ")}` : "") + [...byReason].map(([r2, shells]) => `; NOT in the ${shells.join(", ")} binary (${r2})`).join("")
   );
+  if (adds.length || not.length) lines.push(`  remedy:   ${capabilityRemedy(c2, shell)}`);
   return lines;
 }
 function formatCapabilityList(caps, shell) {
@@ -153532,7 +153588,7 @@ function rawTools() {
     {
       name: "himi_capabilities",
       title: "Native capabilities (camera, location, push, \u2026)",
-      description: "The native capabilities a worker can use: the @himalaya import, where to declare it (config.ts `capabilities` + the screen's logicBundle.declaredCapabilities), what the binary needs (usage strings, permissions), and which `himi dist --shell` binaries serve it. A capability with a native footprint only arrives with a new binary \u2014 an OTA push cannot add it. Offline.",
+      description: "The native capabilities a worker can use: the @himalaya import, where to declare it (config.ts `capabilities` + the screen's logicBundle.declaredCapabilities), what the binary needs (usage strings, permissions), the native module it links (`modules`) and the components that need that module (`components`), and which `himi dist --shell` binaries serve it. A capability with a native footprint only arrives with a new binary \u2014 an OTA push cannot add it; list it in config.ts `capabilityEnvelope` to build it in now and turn it on later. `distAddable` / `distAddRefusal` say whether a `himi dist` build can add it to an extensible shell, and why not. Offline.",
       annotations: LEARN,
       inputSchema: z3.object({
         id: z3.string().optional().describe("One capability, e.g. `camera`. Omit for all."),
@@ -178517,7 +178573,7 @@ Guides in your browser: ${idx.portalUrl}`);
       return 0;
     }
     case "capabilities": {
-      const { allCapabilities: allCapabilities2, capabilityInfo: capabilityInfo2, contentShell: contentShell2, formatCapability: formatCapability2, formatCapabilityList: formatCapabilityList2, isShell: isShell2, SHELLS: SHELLS2 } = await Promise.resolve().then(() => (init_capabilities(), capabilities_exports));
+      const { allCapabilities: allCapabilities2, capabilityInfo: capabilityInfo2, contentShell: contentShell2, formatCapability: formatCapability2, formatCapabilityList: formatCapabilityList2, isShell: isShell2, notInBinaryReason: notInBinaryReason2, SHELLS: SHELLS2 } = await Promise.resolve().then(() => (init_capabilities(), capabilities_exports));
       const sdkRef = loadSdkReference();
       const shell = contentShell2(contentDir(flags), str9(flags.shell));
       if (shell && !isShell2(shell)) {
@@ -178535,8 +178591,11 @@ Guides in your browser: ${idx.portalUrl}`);
           print({ ok: true, ...c2, ...shell ? { shell, servedByShell: c2.shells[shell] === "serves" } : {} });
           return 0;
         }
-        for (const line of formatCapability2(c2)) io2.log(line);
-        if (shell) io2.log(`  ${shell}:  ${c2.shells[shell] === "serves" ? "serves it" : "does NOT serve it \u2014 its binary is not built with it"}`);
+        for (const line of formatCapability2(c2, shell ?? void 0)) io2.log(line);
+        if (shell) {
+          const v2 = c2.shells[shell];
+          io2.log(`  ${shell}:  ${v2 === "serves" ? "serves it" : v2 === "dist-adds" ? "does not serve it yet \u2014 `himi dist` adds it" : `does NOT serve it \u2014 ${notInBinaryReason2(c2, shell)}`}`);
+        }
         return 0;
       }
       const caps = allCapabilities2(sdkRef);

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.1361.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": "b5d19122c31f70fd18ec1b8a2e6d66e67ad3c2ffb5a4545a8bc432a1"
 }