@wix/himalaya-cli 0.1291.0 → 0.1293.0

package/guides/himi-json-output.md

@@ -55,6 +55,7 @@ keeps its existing fields and adds the code:
 | `serve_unreachable` | A partial-push upload could not reach the publishing service. |
 | `no_serve_plane` | A loopback service answering a partial push is not a himi publishing service. |
 | `upload_http_error` | The upload returned a non-success HTTP status. `status` and the original `body` remain available; server errors never replace this CLI code. |
+| `binary_capability_gap` | The publish was refused (409): it declares a permission-bearing capability (iOS usage string or entitlement, Android permission) the app's last successful `himi dist` was not built with. `missing` names the ids; `dists` lists each platform's last dist that lacks them (`platform`, `jobId`, `missing`). The same code comes from `himi push --only` and `himi patch`. Run `himi dist` first, or re-run with `--allow-binary-gap`. |
 | `claim_failed` | Auto-claim returned a fatal refusal. Existing server fields and `status` remain available. |
 | `invalid_flag_value` | A flag violates the CLI flag grammar. |
 | `invalid_selector` | `--only` is missing a selector or its selector syntax is invalid. |

package/guides/importable-sdks.md

@@ -59,6 +59,7 @@ package in one greppable file) or `GET /v1/sdk/<name>` over HTTP; in the CLI,
 - `@himalaya/time` — Tier-5 temporal helpers.
 - `@himalaya/ui` — Tier-5 typed binding to the platform's imperative popup capability.
 - `@himalaya/webview` — Tier-5 typed binding for the page ↔ worker message channel of a worker-backed webview screen (Part 2 / RFC 0025 composition).
+- `@himalaya/webview-page` — browser-side SDK for a trusted page hosted by a worker-backed Himalaya WebView.
 - `@himalaya/widget` — Tier-5 logic-bundle widget surface.
 - `@himalaya/wix-llm` — narrow Tier-5 binding for Wix LLM text generation.
 - `@himalaya/wix-platform` — Wix Platform SDK (RFC 0042), worker-facing bindings.

package/guides/index.json

@@ -89,6 +89,12 @@
       "category": "Workers & SDKs",
       "file": "importable-sdks.md"
     },
+    {
+      "id": "webview-page-sdk",
+      "title": "Use native capabilities from a WebView page",
+      "category": "Workers & SDKs",
+      "file": "webview-page-sdk.md"
+    },
     {
       "id": "component-reference",
       "title": "Component reference",

package/guides/sdk-reference.json

@@ -4073,6 +4073,85 @@
         "jsdoc": "/**\n * Register a handler for messages the page posts via `window.HimalayaWorker.post(msg)`.\n * The latest registered handler wins. Call this once during the bundle's setup.\n */",
         "decl": "export function onPageMessage(cb: (msg: unknown) => void): void;"
       },
+      {
+        "name": "PageCapabilityRequest",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface PageCapabilityRequest {\n  v: 1;\n  id: string;\n  capability: string;\n  method: string;\n  args: unknown[];\n}"
+      },
+      {
+        "name": "PageCapabilityResponse",
+        "kind": "interface",
+        "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": "ExposedPageCapability",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface ExposedPageCapability {\n  module: Record<string, unknown>;\n  methods: readonly string[];\n}"
+      },
+      {
+        "name": "exposeCapabilitiesToPage",
+        "kind": "function",
+        "jsdoc": "/**\n * Expose selected typed @himalaya/* modules to the hosting page.\n *\n * The worker author must pass both the imported module and its explicit verb allowlist:\n *\n *   import * as health from \"@himalaya/health\";\n *   exposeCapabilitiesToPage({\n *     health: { module: health, methods: [\"availability\", \"query\"] },\n *   });\n *\n * The bundle still has to declare `webview` plus every exposed capability. Importing only\n * selected modules keeps native permissions and `himi dist` additions opt-in.\n */",
+        "decl": "export function exposeCapabilitiesToPage(\n  capabilities: Readonly<Record<string, ExposedPageCapability>>,\n): void;"
+      },
+      {
+        "name": "version",
+        "kind": "const",
+        "jsdoc": "",
+        "decl": "export const version = 1;"
+      }
+    ]
+  },
+  {
+    "name": "@himalaya/webview-page",
+    "source": "core/sdk/webview-page/src/index.ts",
+    "description": "browser-side SDK for a trusted page hosted by a worker-backed Himalaya WebView.",
+    "api": [
+      {
+        "name": "\"./capabilities.generated.js\"",
+        "kind": "reexport",
+        "jsdoc": "",
+        "decl": "export type { HimalayaPageCapabilities, HimalayaPageSdk } from \"./capabilities.generated.js\";"
+      },
+      {
+        "name": "WebViewPageRequest",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WebViewPageRequest {\n  v: 1;\n  id: string;\n  capability: string;\n  method: string;\n  args: unknown[];\n}"
+      },
+      {
+        "name": "WebViewPageError",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WebViewPageError {\n  message: string;\n  code?: string;\n}"
+      },
+      {
+        "name": "WebViewPageResponse",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WebViewPageResponse {\n  v: 1;\n  id: string;\n  ok: boolean;\n  result?: unknown;\n  error?: WebViewPageError;\n}"
+      },
+      {
+        "name": "call",
+        "kind": "function",
+        "jsdoc": "/** Invoke one method through the companion worker. Primarily useful to generated bindings. */",
+        "decl": "export function call<T>(\n  capability: string,\n  method: string,\n  args: unknown[] = [],\n  timeoutMs = 30_000,\n): Promise<T>;"
+      },
+      {
+        "name": "himalaya",
+        "kind": "const",
+        "jsdoc": "/**\n * Typed SDK proxy for every request/response capability in CAPABILITY_REGISTRY.\n * A namespace is usable only when this screen's companion worker explicitly imported and\n * exposed it and the bundle + host both declared it.\n */",
+        "decl": "export const himalaya = new Proxy({ version: 1 as const }, {\n  get(target, property) {\n    if (property === \"version\") return target.version;\n    if (typeof property !== \"string\" || property === \"then\") return undefined;\n    return pageMember(property, []);\n  },\n}) as HimalayaPageSdk;"
+      },
+      {
+        "name": "health",
+        "kind": "const",
+        "jsdoc": "/** Convenience named export; equivalent to `himalaya.health`. */",
+        "decl": "export const health = himalaya.health;"
+      },
       {
         "name": "version",
         "kind": "const",

package/guides/webview-page-sdk.md

@@ -0,0 +1,132 @@
+# Himalaya SDK for hosted WebView pages
+
+Use `@wix/himalaya/webview-page` when a trusted webpage hosted inside Brandy (or another
+worker-backed Himalaya WebView) needs an explicitly selected native capability. The webpage never
+talks directly to native code:
+
+```
+page → window.HimalayaWorker → companion Tier-5 worker → @himalaya/* → native registry
+```
+
+The same bundle declaration and host policy that protect an ordinary Tier-5 screen protect the
+page. A namespace present in TypeScript is not authority: the companion worker must import and
+allowlist it, its `logicBundle.declaredCapabilities` must name it, and the binary must serve it.
+
+## Page
+
+Install the published umbrella package and import its page entry:
+
+```ts
+import { himalaya } from "@wix/himalaya/webview-page";
+
+const available = await himalaya.health.availability();
+if (available.available) {
+  await himalaya.health.requestPermission({ read: ["steps"], write: ["workouts"] });
+  const result = await himalaya.health.query({
+    type: "steps",
+    from: new Date("2026-10-11T00:00:00Z").toISOString(),
+    to: new Date().toISOString(),
+  });
+  console.log(result.samples);
+}
+```
+
+The generated `himalaya` type includes every package represented by
+`CAPABILITY_REGISTRY`, including nested APIs such as `himalaya.base44.auth.*`. Calls made in an
+ordinary browser fail immediately with a clear “not inside a worker-backed Himalaya WebView”
+error.
+
+## Companion worker
+
+Import only what this website is allowed to use and allowlist only the methods it needs:
+
+```ts
+import * as health from "@himalaya/health";
+import { exposeCapabilitiesToPage } from "@himalaya/webview";
+
+exposeCapabilitiesToPage({
+  health: {
+    module: health,
+    methods: ["availability", "requestPermission", "getPermissionStatus", "query", "saveWorkout"],
+  },
+});
+```
+
+Build it like any other Tier-5 bundle. Its descriptor must declare both the transport and the
+selected capabilities:
+
+```ts
+logicBundle: {
+  url,
+  integrity,
+  declaredCapabilities: ["webview", "health"],
+}
+```
+
+Do not build one worker that imports every SDK. Static bundle scanning would correctly conclude
+that the release uses every capability, forcing unrelated permissions and native modules into the
+binary. One app-specific worker imports exactly the app’s selected subset.
+
+## Brandy
+
+Health has a built-in proof worker, so it needs no custom bundle name:
+
+```json
+{
+  "webSdk": {
+    "capabilities": ["health"],
+    "permissionCopy": {
+      "health": "Show your activity and save completed workouts."
+    }
+  }
+}
+```
+
+For another subset, add the companion bundle to the app and name it:
+
+```json
+{
+  "webSdk": {
+    "bundle": "customer-page-capabilities",
+    "capabilities": ["camera", "share"],
+    "permissionCopy": {
+      "camera": "Take a photo to attach it to your request."
+    }
+  }
+}
+```
+
+Brandy accepts capabilities `himi dist` can add to an extensible shell. Capabilities requiring
+app-specific boot wiring remain refused until that shell supplies the wiring. Base44 is accepted
+only when the same Brandy contract contains a Base44 binding.
+
+## Security and current transport boundary
+
+- Only the trusted main-frame origin receives `HimalayaWorker`; redirects and cross-origin frames
+  cannot use it.
+- The worker accepts JSON-compatible arguments and results, caps argument count, validates request
+  identifiers and resolves only own properties on an explicit method allowlist.
+- Errors preserve a typed `code` when the SDK provides one.
+- The page cannot use raw `capability.*` messages: Brandy site descriptors keep
+  `capabilitiesRequired: []`; native calls go through the companion worker.
+- v1 is request/response. SDK helpers returning `AsyncIterable`, accepting JavaScript callbacks,
+  or depending on worker action names need a page-specific adapter built from their lower-level
+  start/next/stop verbs. Do not expose such a helper unchanged.
+
+The package source includes complete `health-page.ts` and `health-worker.ts` examples matching the
+snippets above.
+
+## Demo app regression page
+
+The demo app hosts a page that calls every capability its iOS and Android boots already
+register. Open it with:
+
+```
+himalaya-demo-app://screen/demo_app_webview_sdk
+```
+
+The page is served at `/web/webview-sdk.html`. Its companion worker is
+`demo-app-webview-sdk`, which carries the catalog of allowlisted methods and read-only
+probes. Safe probes run on load.
+Verbs that prompt, write, or open system UI stay allowlisted and are not called. Streaming
+helpers that return a live object stay on the worker.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1291.0",
+  "version": "0.1293.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": [
@@ -70,5 +70,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "0e0aab5246aa6f8b622e65ac490679cc26e226218f468ec3c3825057"
+  "falconPackageHash": "1e4a8d2ba1f5fab907ed2786c0387721f5289baac64c2650c3240e88"
 }