@wix/himalaya-cli 0.1451.0 → 0.1453.0

package/guides/sdk-reference.json

@@ -4743,6 +4743,12 @@
     "source": "core/sdk/webview/src/index.ts",
     "description": "Tier-5 typed binding for the page ↔ worker message channel of a worker-backed webview screen (Part 2 / RFC 0025 composition).",
     "api": [
+      {
+        "name": "\"./dispatcher.js\"",
+        "kind": "reexport",
+        "jsdoc": "",
+        "decl": "export {\n  PAGE_HANDSHAKE_CAPABILITY,\n  PAGE_HANDSHAKE_METHOD,\n  type ExposedPageCapability,\n  type PageCapabilityRequest,\n  type PageCapabilityResponse,\n  type PageConsoleEvent,\n  type PageCtx,\n  type PageLifecycleEvent,\n  type PageRequestHandler,\n  type PageStream,\n} from \"./dispatcher.js\";"
+      },
       {
         "name": "postToPage",
         "kind": "function",
@@ -4752,43 +4758,43 @@
       {
         "name": "onPageMessage",
         "kind": "function",
-        "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;"
+        "jsdoc": "/**\n * Register a handler for messages the page posts via `window.HimalayaWorker.post(msg)` that no\n * responder (`exposeCapabilitiesToPage`, `onPageRequest`) claims. The latest registered handler\n * wins. `instanceId` is the embedded WebView the host says the message came from (`\"\"` for the\n * full-screen page). Call this once during the bundle's setup.\n */",
+        "decl": "export function onPageMessage(cb: (msg: unknown, instanceId: string) => 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": "onPageRequest",
+        "kind": "function",
+        "jsdoc": "/**\n * Answer page requests `call(namespace, method, args)` from `@wix/himalaya/webview-page` (or\n * `himalaya.<namespace>.<method>(…)`) with worker code. A handler gets `(args, ctx)` and returns a value or a promise; a throw answers\n * `ok: false`. To stream, return `openPageStream(ctx.instanceId, ctx.requestId)`.\n *\n * Throws when `namespace` is `\"himalaya\"`, already registered, already exposed, or not\n * `/^[a-z][a-z0-9_]{0,63}$/`. A method the namespace lacks answers `code: \"unknown_method\"`.\n */",
+        "decl": "export function onPageRequest(namespace: string, handlers: Readonly<Record<string, PageRequestHandler>>): void;"
       },
       {
-        "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": "emitToPage",
+        "kind": "function",
+        "jsdoc": "/**\n * Push an event to one page instance, or `\"*\"` for every instance that has sent a message or\n * mounted and not unmounted. `event` is `\"<namespace>.<event>\"`, split on the first dot; the page\n * receives it through `himalaya.<namespace>.on(\"<event>\", cb)`.\n */",
+        "decl": "export function emitToPage(instanceId: string, event: `${string}.${string}`, data: unknown): void;"
       },
       {
-        "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": "openPageStream",
+        "kind": "function",
+        "jsdoc": "/**\n * Open a stream answer for an in-flight `onPageRequest` call. Return the handle from the handler;\n * the page then iterates the chunks. After `end`, `error`, or a page cancel, `next` is a no-op.\n */",
+        "decl": "export function openPageStream(instanceId: string, requestId: string): PageStream;"
       },
       {
-        "name": "PAGE_HANDSHAKE_METHOD",
-        "kind": "const",
-        "jsdoc": "",
-        "decl": "export const PAGE_HANDSHAKE_METHOD = \"capabilities\";"
+        "name": "onPageLifecycle",
+        "kind": "function",
+        "jsdoc": "/**\n * Observe host lifecycle envelopes (`mounted | loaded | active | inactive | crashed | reloaded |\n * navBlocked | unmounted`). They arrive only on the host's lifecycle primitive, never from a page.\n * On a runtime without instance support, nothing is delivered. Returns an unsubscribe function.\n */",
+        "decl": "export function onPageLifecycle(cb: (e: PageLifecycleEvent) => void): () => void;"
       },
       {
-        "name": "ExposedPageCapability",
-        "kind": "interface",
-        "jsdoc": "",
-        "decl": "export interface ExposedPageCapability {\n  module: Record<string, unknown>;\n  methods: readonly string[];\n}"
+        "name": "onPageConsole",
+        "kind": "function",
+        "jsdoc": "/**\n * Observe `console_forwarding` output of the embedded pages. UNTRUSTED page data: a page can forge\n * these, so never treat them as host events. Returns an unsubscribe function.\n */",
+        "decl": "export function onPageConsole(cb: (e: PageConsoleEvent) => void): () => void;"
       },
       {
         "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 */",
+        "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. The page handshake\n * (`call(\"himalaya\", \"capabilities\")`) answers this allowlist plus every `onPageRequest` namespace.\n */",
         "decl": "export function exposeCapabilitiesToPage(\n  capabilities: Readonly<Record<string, ExposedPageCapability>>,\n): void;"
       },
       {
@@ -4811,52 +4817,46 @@
         "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",
+        "name": "\"./client.js\"",
+        "kind": "reexport",
         "jsdoc": "",
-        "decl": "export interface WebViewPageResponse {\n  v: 1;\n  id: string;\n  ok: boolean;\n  result?: unknown;\n  error?: WebViewPageError;\n}"
+        "decl": "export type {\n  PageEventHandler,\n  WebViewPageError,\n  WebViewPageEvent,\n  WebViewPageRequest,\n  WebViewPageResponse,\n  WebViewPageStreamEnvelope,\n} from \"./client.js\";"
       },
       {
         "name": "call",
         "kind": "function",
-        "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. */",
+        "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.\n *  A method the worker answers as a stream resolves to an `AsyncIterable` of its chunks:\n *  `for await (const chunk of await call(…))`; `break` cancels it on the worker. */",
         "decl": "export function call<T>(\n  capability: string,\n  method: string,\n  args: unknown[] = [],\n  timeoutMs = 30_000,\n): Promise<T>;"
       },
+      {
+        "name": "on",
+        "kind": "function",
+        "jsdoc": "/** Subscribe to `namespace.event`, pushed by the worker's `emitToPage(iid, \"<namespace>.<event>\", data)`.\n *  Same as `himalaya.<namespace>.on(event, handler)`. Returns the unsubscribe function. */",
+        "decl": "export function on(namespace: string, event: string, handler: PageEventHandler): () => void;"
+      },
       {
         "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>;"
+        "decl": "export 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>;"
+        "decl": "export 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>;"
+        "jsdoc": "/** For an app older than the handshake: CALL `capability.method` and report whether it answered\n *  (even with an error other than `unknown_method`). It runs the method, so pass only a read-only one. */",
+        "decl": "export function probe(capability: string, method: string, args: unknown[] = [], timeoutMs = 3_000): Promise<boolean>;"
       },
       {
         "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;"
+        "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. Built by the same `merge` a host uses for the\n * injected client, so `himalaya.call/on/probe/…` are the client's members here too.\n */",
+        "decl": "export const himalaya = client.merge({}) as HimalayaPageSdk;"
       },
       {
         "name": "health",

package/guides/web-page-native-sdk.md

@@ -79,7 +79,7 @@ type Bridge = { post(message: unknown): boolean; onMessage(handler: (message: un
 type Reply = { v: 1; id: string; ok: boolean; result?: unknown; error?: { message: string; code?: string } };
 
 export class HimalayaError extends Error {
-  /** "not_in_app" | "bridge_refused" | "timeout", or the capability's own code (e.g. "not_authorized"). */
+  /** "not_in_app" | "bridge_refused" | "timeout" | "unknown_method", or the capability's own code (e.g. "not_authorized"). */
   readonly code: string;
   constructor(message: string, code: string) {
     super(message);
@@ -224,8 +224,9 @@ export async function probe(capability: string, method: string, args: unknown[]
     await call(capability, method, args, timeoutMs);
     return true;
   } catch (error) {
-    // Only an answer from the app (even an error) proves the method is enabled.
-    return !(error instanceof HimalayaError && ["timeout", "not_in_app", "bridge_refused"].includes(error.code));
+    // Only an answer from the app (even an error) proves the method is enabled — except the app
+    // saying it has no such method.
+    return !(error instanceof HimalayaError && ["timeout", "not_in_app", "bridge_refused", "unknown_method"].includes(error.code));
   }
 }
 

package/guides/webview-page-sdk.md

@@ -85,6 +85,104 @@ Do not build one worker that imports every SDK. Static bundle scanning would cor
 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.
 
+## Custom namespaces, events and streams
+
+One worker can serve any number of embedded pages at once. Beside `exposeCapabilitiesToPage`, the
+worker answers its own namespaces, pushes events and streams results; all of them share one
+internal dispatcher, so registering one never replaces another (and `onPageMessage` still receives
+every message none of them claims, including a handler registered directly on
+`himalaya.webview.onPageMessage` after `@himalaya/webview` loaded).
+
+```ts
+import { emitToPage, onPageLifecycle, onPageRequest, openPageStream } from "@himalaya/webview";
+
+onPageRequest("nano", {
+  // (args, ctx) → value | promise. ctx = { instanceId, requestId, active }.
+  "location.getCurrentLocation": async () => ({ lat: 32.08, lng: 34.78 }),
+  // Return a stream handle to answer with many chunks.
+  "steps.watch": (_args, ctx) => {
+    const stream = openPageStream(ctx.instanceId, ctx.requestId);
+    const timer = setInterval(() => stream.next({ steps: Math.random() }), 1000);
+    stream.onCancel(() => clearInterval(timer)); // the page broke out of its loop
+    return stream;
+  },
+});
+
+emitToPage("*", "nano.theme.changed", { dark: true }); // or one instance id
+const off = onPageLifecycle(({ instanceId, state }) => console.log(instanceId, state)); // mounted … unmounted
+```
+
+- `ctx.instanceId` is the WebView the **host** says the request came from; a page-sent `iid` is
+  ignored. `ctx.active` is live: `false` between `inactive` and `active` lifecycle events.
+- A namespace — and an exposed capability id — follows the capability-id pattern
+  (`/^[a-z][a-z0-9_]{0,63}$/`). Registering it twice, registering `himalaya`, or a name already
+  exposed throws. So do names the page's `himalaya.<name>` cannot reach: `call`, `on`, `probe`,
+  `version`, `then`, `constructor` and `general`, a method named `on`, and a method with a `then`,
+  `toString` or `valueOf` segment. The handshake lists custom namespaces beside exposed capabilities.
+- A request whose page unmounted, reloaded or crashed before it answered is not answered at all:
+  the instance id may already belong to a new document. A `reloaded` right after `crashed` counts
+  as one boundary; a `mounted` or `loaded` in between ends that pair (so a host that remounts after
+  a crash delivers `reloaded` before the new document's `loaded`). A message still queued when
+  its instance unmounted reaches `onPageMessage` but revives nothing, and its request is not
+  answered; the instance is back once it mounts again.
+- A method a registered namespace lacks answers at once with
+  `{ ok: false, error: { code: "unknown_method" } }` — the page does not wait out a timeout, and
+  `probe()` reads it as "not enabled". A request for a capability that is neither exposed nor
+  registered is not the dispatcher's: it reaches `onPageMessage` (the bundle's own protocol) and is
+  otherwise unanswered, because pages built against an older `probe()` read any answer as
+  "enabled". A method outside an allowlist and unknown methods on the reserved `himalaya` name also
+  stay unanswered.
+- `emitToPage(iid, "<ns>.<event>", data)` splits on the first dot; `"*"` reaches every instance
+  that has sent a message or mounted and has not unmounted (on a single-page runtime, its page).
+- A stream answers `{ v: 1, id, ok: true, stream: true }`, then `{ v: 1, sid, chunk }`… and
+  `{ v: 1, sid, end: true }` or `{ v: 1, sid, error }`; `sid` is the request id. After `end`,
+  `error`, a page cancel, or the instance unmounting, reloading or crashing, `next` is a no-op.
+  `onCancel` also runs when a handler opens a stream and then returns something else or throws,
+  and at once if it is registered after the stream was abandoned. `next(undefined)` sends `null`.
+- `onPageLifecycle` envelopes come only from the host's lifecycle primitive; one arriving as a page
+  message is never treated as lifecycle. Of the page's `{ v: 1, sys }` messages the dispatcher keeps
+  only `cancel` and `console`; any other `sys` reaches `onPageMessage`. `onPageConsole` surfaces `console_forwarding` output — **untrusted** page
+  data the page can forge; never treat it as a host event.
+- On a runtime without instance support (`himalaya.webview.onPageLifecycle` absent) every message
+  is instance `""`, lifecycle never fires, and posts to any other instance are dropped. Such a host
+  does not report a page reload either, so a stream there stops only when the page cancels it:
+  bound the producer (a count or a deadline) rather than relying on `onCancel` alone.
+- A page `probe()` of a streamed method cancels the stream it started.
+
+On the page:
+
+```ts
+import { call, on } from "@wix/himalaya/webview-page";
+
+declare function applyTheme(theme: unknown): void;
+declare function render(reading: { steps: number }): void;
+
+// A typed capability has the same method: himalaya.<capability>.on("<event>", cb).
+const off = on("nano", "theme.changed", (data) => applyTheme(data));
+let readings = 0;
+for await (const reading of await call<AsyncIterable<{ steps: number }>>("nano", "steps.watch")) {
+  render(reading);
+  if (++readings === 10) break; // sends { v: 1, sys: "cancel", sid } — the worker's onCancel runs
+}
+off();
+```
+
+A stream `error` envelope throws from the loop. The page accepts only `v: 1` envelopes, and
+responses only for a request id it sent.
+
+**Injected client (planned host behaviour).** No host injects it yet: today a page imports
+`@wix/himalaya/webview-page`. The native and web hosts are planned to inject the same client at
+document start for worker-bridged WebViews, so inline HTML will need no import.
+`PAGE_CLIENT_SOURCE` (`@himalaya/webview-page/page-client`, generated from `src/client.ts` by
+`scripts/generate-page-client.ts`) is a script that defines no global and evaluates to
+`createPageClient(getBridge)`. The host's bridge shim defines `window.himalaya` non-writable, so
+the client is to be merged into the shim's own object before it is frozen:
+`client.merge({ general: … })` adds `call`, `on`, `enabledCapabilities`, `isEnabled`, `probe` and
+`version`, freezes the object, and resolves any other name to a namespace proxy
+(`himalaya.nano.on(…)`, `himalaya.nano.location.getCurrentLocation()`). The package's own
+`himalaya` export is built the same way, so both surfaces have the same members. Coercing a
+namespace to a string (`` `${himalaya.nano}` ``) sends nothing to the worker.
+
 ## Brandy
 
 Name the capabilities; Brandy supplies the companion worker, so neither the page author nor the
@@ -135,9 +233,10 @@ Base44 is accepted only when the same Brandy contract contains a Base44 binding.
 - 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.
+- `exposeCapabilitiesToPage` is request/response. SDK helpers returning `AsyncIterable`, accepting
+  JavaScript callbacks, or depending on worker action names need an `onPageRequest` adapter
+  (a stream or `emitToPage` events) 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1451.0",
+  "version": "0.1453.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": "cb3204a26dd5603f14ee56cbf6422f13f5ffa19d1500d2fef6fa3e99"
+  "falconPackageHash": "297fee15efe43307e066ee404fb90579178287997e8e01f43d6c03a3"
 }