@wix/himalaya-cli 0.1577.0 → 0.1578.0

package/guides/qa-builds.md

@@ -1210,12 +1210,20 @@ himi dist --app <app> --platform android --aab --wait --target bo
   a bundle id saved in between is refused and stays changeable). The owner must already have the app
   in App Store Connect under that bundle id. The files
   and the key are never stored: the pool and the upload each fetch them again, the job keeps only
-  their hashes. The upload runs on the first status read after the pool validated the IPA; any read
-  the caller may make of the app moves it on, since the owner was proven when the build started (the
-  Containers server's reads carry a project token, not the owner's Wix login). So a caller keeps
-  reading the job until `customerAppStore.status` is `UPLOADED` or `FAILED`, not only until the job
-  is `SUCCESS`: a read that stops early, or gives up mid-upload, leaves the IPA waiting (a claimed
-  upload is retried by a read 15 minutes later).
+  their hashes. The upload starts on its own once the pool reports the validated IPA: the pool's
+  callback starts it in the background, and so does every list read of the app's builds (the owner
+  card's poll) while it can be claimed, which also picks up one a stopped serve pod left. A status
+  read still uploads too; any read the caller may make of the app moves it on, since the owner was
+  proven when the build started (the Containers server's reads carry a project token, not the
+  owner's Wix login). A caller reads the job until `customerAppStore.status` is `UPLOADED` or
+  `FAILED` to learn how it ended; it no longer has to read for the upload to happen. An attempt that
+  fails on a passing error (a 429 or 5xx from mobile-apps-containers-builder or Apple, a timeout, a
+  download that broke off) goes back to `READY_FOR_UPLOAD` with `failedAttempts`, `retryAt` and
+  `lastError`, and is tried again 1, 5 and 15 minutes later. The 4th failed attempt (an attempt
+  whose 15-minute lease ran out counts as one) and any error the owner must fix (no app in App Store
+  Connect, a refused key, a closed version) end `FAILED`, with `error`. When the IPA's 7-day link is
+  within an hour of lapsing, the upload signs a fresh one from the stored bucket and key (the plane's
+  `DIST_ARTIFACT_AWS_*` key pair; without it, the recorded link).
   Refusals, each with `code` equal to `error`: `store_build_ios_only`, `store_build_version_invalid`
   and `store_build_shell_unsupported` 400, `store_build_site_forbidden` 403, `store_id_missing`,
   `store_app_site_taken`, `release_predates_store_builds`, `apple_credentials_missing`,

package/guides/sdk-reference.json

@@ -1017,6 +1017,12 @@
     "source": "core/sdk/clipboard/src/index.ts",
     "description": "Tier-5 typed binding for the system clipboard.",
     "api": [
+      {
+        "name": "\"@himalaya/sdk-types\"",
+        "kind": "reexport",
+        "jsdoc": "",
+        "decl": "export type { FileHandle } from \"@himalaya/sdk-types\";"
+      },
       {
         "name": "writeText",
         "kind": "function",
@@ -1035,11 +1041,59 @@
         "jsdoc": "/** Whether the clipboard holds text — no content access, no iOS paste banner. On\n *  web this can't be known without reading, so it returns true pessimistically;\n *  treat it as a hint, not a guarantee. */",
         "decl": "export async function hasText(): Promise<boolean>;"
       },
+      {
+        "name": "MAX_IMAGE_BYTES",
+        "kind": "const",
+        "jsdoc": "/** Largest image writeImage accepts (20 MB). Hosts enforce it too. */",
+        "decl": "export const MAX_IMAGE_BYTES = 20 * 1024 * 1024;"
+      },
+      {
+        "name": "IMAGE_MIME_TYPES",
+        "kind": "const",
+        "jsdoc": "/** Image MIME types writeImage copies. HEIC is iOS/macOS only (Android and web\n *  reject it `unsupported_type`); web accepts PNG only. The host sniffs the file's\n *  bytes, so a handle is judged by its content, not its `mimeType` — the binding only\n *  refuses up front a handle whose type is plainly not an image (e.g. application/pdf). */",
+        "decl": "export const IMAGE_MIME_TYPES: readonly string[] = [\"image/png\", \"image/jpeg\", \"image/webp\", \"image/heic\"];"
+      },
+      {
+        "name": "ClipboardImageErrorCode",
+        "kind": "type",
+        "jsdoc": "/** Why writeImage rejected. */",
+        "decl": "export type ClipboardImageErrorCode = \"unsupported_type\" | \"too_large\" | \"not_allowed\" | \"not_found\" | \"unavailable\";"
+      },
+      {
+        "name": "ClipboardImageError",
+        "kind": "interface",
+        "jsdoc": "/** A writeImage rejection: an `Error` named \"ClipboardImageError\" carrying a stable\n *  `code`. (A plain Error, not a subclass — Tier-5 bundles target an engine without\n *  class syntax.) Branch on `isClipboardImageError(e) && e.code === \"too_large\"`. */",
+        "decl": "export interface ClipboardImageError extends Error {\n  name: \"ClipboardImageError\";\n  code: ClipboardImageErrorCode;\n}"
+      },
+      {
+        "name": "clipboardImageError",
+        "kind": "function",
+        "jsdoc": "/** Build a coded writeImage rejection. */",
+        "decl": "export function clipboardImageError(code: ClipboardImageErrorCode, message?: string): ClipboardImageError;"
+      },
+      {
+        "name": "isClipboardImageError",
+        "kind": "function",
+        "jsdoc": "/** Whether `e` is a coded writeImage rejection. */",
+        "decl": "export function isClipboardImageError(e: unknown): e is ClipboardImageError;"
+      },
+      {
+        "name": "writeImage",
+        "kind": "function",
+        "jsdoc": "/** Copy an image file the worker already holds to the clipboard. Accepts a\n *  `FileHandle` (from files / camera / photos) or its substrate `uri`. Rejects with a\n *  `ClipboardImageError` (see `isClipboardImageError`) whose `code` is `unsupported_type` (not PNG/JPEG/WebP/HEIC, or\n *  not supported on this host), `too_large` (over 20 MB), `not_allowed` (outside the\n *  app's files substrate), `not_found`, or `unavailable` (no image clipboard here). */",
+        "decl": "export async function writeImage(file: FileHandle | string): Promise<void>;"
+      },
+      {
+        "name": "hasImage",
+        "kind": "function",
+        "jsdoc": "/** Whether the clipboard currently holds an image — without reading it (no iOS paste\n *  banner). Web cannot know without a permission-gated read, so it answers false. */",
+        "decl": "export async function hasImage(): Promise<boolean>;"
+      },
       {
         "name": "version",
         "kind": "const",
         "jsdoc": "/** Capability version, for bundles that gate on min binary version. */",
-        "decl": "export const version = 1;"
+        "decl": "export const version = 2;"
       }
     ]
   },
@@ -1550,20 +1604,68 @@
       {
         "name": "HapticPattern",
         "kind": "type",
-        "jsdoc": "/** Maps to a native impact/notification/selection generator. */",
-        "decl": "export type HapticPattern =\n  | \"selection\"\n  | \"light\"\n  | \"medium\"\n  | \"heavy\"\n  | \"success\"\n  | \"warning\"\n  | \"error\";"
+        "jsdoc": "/**\n * Maps to a native impact/notification/selection generator.\n *\n * - `rigid` / `soft` — iOS `UIImpactFeedbackGenerator.FeedbackStyle.rigid` / `.soft`.\n *   Android: `rigid` is a short full-amplitude click (`VibrationEffect.EFFECT_CLICK`-like),\n *   `soft` a longer low-amplitude tick (`PRIMITIVE_LOW_TICK`-like); on a device without\n *   amplitude control both are plain one-shots of different length.\n */",
+        "decl": "export type HapticPattern =\n  | \"selection\"\n  | \"light\"\n  | \"medium\"\n  | \"heavy\"\n  | \"rigid\"\n  | \"soft\"\n  | \"success\"\n  | \"warning\"\n  | \"error\";"
+      },
+      {
+        "name": "PlayOptions",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface PlayOptions {\n  /**\n   * 0..1, clamped. Scales the strength of an IMPACT style (`light`, `medium`, `heavy`,\n   * `rigid`, `soft`): iOS `impactOccurred(intensity:)`, Android amplitude where the\n   * vibrator has amplitude control. Ignored for `selection` and the notification styles\n   * (`success`, `warning`, `error`) — those have a fixed system strength — and on web.\n   */\n  intensity?: number;\n}"
+      },
+      {
+        "name": "HapticStep",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface HapticStep {\n  pattern: HapticPattern;\n  /** Milliseconds to wait BEFORE this step plays (≥ 0). */\n  delayMs: number;\n  /** Same meaning as {@link PlayOptions.intensity}. */\n  intensity?: number;\n}"
+      },
+      {
+        "name": "HapticResult",
+        "kind": "type",
+        "jsdoc": "/**\n * What a verb reports. `ok: false` is honest: `unavailable` (this surface has no haptic\n * hardware/API — web without `navigator.vibrate`, macOS) or `unsupported_binary` (the\n * native app predates the verb; nothing played, nothing broke).\n */",
+        "decl": "export type HapticResult = { ok: true } | { ok: false; reason: \"unavailable\" | \"unsupported_binary\" };"
+      },
+      {
+        "name": "MAX_SEQUENCE_STEPS",
+        "kind": "const",
+        "jsdoc": "/** Most steps one {@link sequence} may carry. */",
+        "decl": "export const MAX_SEQUENCE_STEPS = 32;"
+      },
+      {
+        "name": "MAX_DURATION_MS",
+        "kind": "const",
+        "jsdoc": "/** Longest a {@link sequence} or {@link vibrate} pattern may run, in milliseconds. */",
+        "decl": "export const MAX_DURATION_MS = 10_000;"
+      },
+      {
+        "name": "clampIntensity",
+        "kind": "function",
+        "jsdoc": "/** Clamp an intensity into 0..1; `undefined` / non-finite → `undefined` (system default). */",
+        "decl": "export function clampIntensity(intensity: number | undefined): number | undefined;"
       },
       {
         "name": "play",
         "kind": "function",
-        "jsdoc": "/**\n * Play a haptic feedback pattern. Fire-and-forget; resolves once handed to the\n * platform. A no-op on web and for unknown patterns.\n */",
-        "decl": "export async function play(pattern: HapticPattern = \"light\"): Promise<void>;"
+        "jsdoc": "/**\n * Play a haptic feedback pattern. Fire-and-forget; resolves once handed to the\n * platform. Unknown pattern names keep their historical behaviour (the platform's\n * default tap). `intensity` applies to impact styles only — see {@link PlayOptions}.\n */",
+        "decl": "export async function play(pattern: HapticPattern = \"light\", options: PlayOptions = {}): Promise<HapticResult>;"
+      },
+      {
+        "name": "sequence",
+        "kind": "function",
+        "jsdoc": "/**\n * Play `steps` in order, waiting each step's `delayMs` before it plays. Runs natively\n * as ONE bridge call (the timing does not depend on the worker), so a drum roll or a\n * countdown keeps its rhythm. A new `sequence` cancels one still running. Resolves once\n * the sequence has been scheduled.\n *\n * Rejects (`RangeError`) with more than {@link MAX_SEQUENCE_STEPS} steps, a negative or\n * non-finite delay, or delays totalling over {@link MAX_DURATION_MS}. An empty list just\n * cancels a running sequence.\n */",
+        "decl": "export async function sequence(steps: HapticStep[]): Promise<HapticResult>;"
+      },
+      {
+        "name": "vibrate",
+        "kind": "function",
+        "jsdoc": "/**\n * Raw vibration: `patternMs` alternates OFF / ON durations in milliseconds, starting\n * with an off gap (`[0, 200, 100, 400]` = buzz 200, pause 100, buzz 400).\n *\n * Android plays it as `VibrationEffect.createWaveform`. iOS approximates: with Core\n * Haptics each ON span is a continuous event (a transient one under 30 ms); without it,\n * each ON span becomes one `heavy` impact at its start. Web uses `navigator.vibrate`.\n *\n * Rejects (`RangeError`) on an empty list, a negative or non-finite duration, or a\n * pattern totalling over {@link MAX_DURATION_MS}.\n */",
+        "decl": "export async function vibrate(patternMs: number[]): Promise<HapticResult>;"
       },
       {
         "name": "version",
         "kind": "const",
         "jsdoc": "/** Capability version, for bundles that gate on a min binary version. */",
-        "decl": "export const version = 1;"
+        "decl": "export const version = 2;"
       }
     ]
   },
@@ -4867,7 +4969,13 @@
         "name": "AlertOptions",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface AlertOptions {\n  /** Required — the native presenters drop alerts with an empty title. */\n  title: string;\n  message?: string;\n  /** Confirm button label. Default \"Confirm\". */\n  confirmLabel?: string;\n  /** Cancel button label. OMIT for a single-button alert (no cancel button). */\n  cancelLabel?: string;\n  /** Style the confirm button with the `danger` token. */\n  destructive?: boolean;\n}"
+        "decl": "export interface AlertOptions {\n  /** Required — the native presenters drop alerts with an empty title. */\n  title: string;\n  message?: string;\n  /** Confirm button label. Default \"Confirm\". */\n  confirmLabel?: string;\n  /** Cancel button label. OMIT for a single-button alert (no cancel button). */\n  cancelLabel?: string;\n  /** Style the confirm button with the `danger` token. A destructive confirm is not the\n   *  affirmative button: its `confirm.actionId` still runs, but without gesture credit. */\n  destructive?: boolean;\n  /** The affirmative button's ACTION. Pressing it runs `actionId` as a NEW invocation\n   *  with user-gesture origin (so an app service's `app.<svc>.<action>` may return `_nav` and\n   *  navigate — the \"Ready — View\" alert). `label` replaces `confirmLabel`. The id is checked when\n   *  you set it, against this worker: a `capability.<id>.*` needs `<id>` allowed, an `app.*` from a\n   *  screen worker needs `app_services` and an exported action, a `tier5.*` must be this worker's\n   *  own; anything else rejects (`action_not_allowed`). Cancel and dismissal run nothing. */\n  confirm?: AlertConfirm;\n}"
+      },
+      {
+        "name": "AlertConfirm",
+        "kind": "interface",
+        "jsdoc": "/** The affirmative button of an `alert()`: its label and the action its press runs. */",
+        "decl": "export interface AlertConfirm {\n  label: string;\n  actionId: string;\n  /** Passed to the action (JSON types kept). */\n  args?: Record<string, unknown>;\n}"
       },
       {
         "name": "AlertResult",
@@ -4878,7 +4986,7 @@
       {
         "name": "alert",
         "kind": "function",
-        "jsdoc": "/** Present a modal alert on the current screen. Resolves when the user picks a\n *  button. Rejects with `ui_busy` while another alert() is pending, and with\n *  `no_ui_host` if the app has no presenter attached. */",
+        "jsdoc": "/** Present a modal alert on the current screen. Resolves when the user picks a\n *  button. Rejects with `ui_busy` while another alert() is pending, and with\n *  `no_ui_host` if the app has no presenter attached — or, from an APP SERVICE, when no\n *  shell is in the foreground (re-show it from `onForeground`). An app service's alert shows on\n *  whatever screen is open. */",
         "decl": "export async function alert(options: AlertOptions): Promise<AlertResult>;"
       },
       {

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

@@ -22,12 +22,12 @@ the SDK sources, so it matches the shipped SDKs.
 - [`calendar`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fcalendar?format=md) — Device calendar. 6 methods.
 - [`calls`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fcalls?format=md) — Real-time 1:1 audio calls (Stage 1). 16 methods.
 - [`camera`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fcamera?format=md) — Camera capability. 4 methods · returns FileHandles.
-- [`clipboard`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fclipboard?format=md) — System clipboard. 3 methods.
+- [`clipboard`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fclipboard?format=md) — System clipboard. 5 methods.
 - [`contacts`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fcontacts?format=md) — Device address book. 4 methods.
 - [`file_picker`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Ffile_picker?format=md) — User-mediated document access OUTSIDE the app sandbox. 3 methods · returns FileHandles.
 - [`files`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Ffiles?format=md) — App-scoped document storage. 6 methods · returns FileHandles.
 - [`godot`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fgodot?format=md) — A Godot game surface. 3 methods · not in Brandy.
-- [`haptic`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fhaptic?format=md) — Haptic capability. 1 method.
+- [`haptic`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fhaptic?format=md) — Haptic capability. 3 methods.
 - [`health`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fhealth?format=md) — Platform HEALTH store. 5 methods.
 - [`himi_apps`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fhimi_apps?format=md) — Cross-app open / host queries. 4 methods · not in Brandy.
 - [`iap`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fiap?format=md) — In-app-purchase capability. 9 methods.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1577.0",
+  "version": "0.1578.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": "9902ef55d169da2c82868b986ceafb0c54b8102e501f513b72e4c8c0"
+  "falconPackageHash": "0a206d4a3d13e9f1302334dcaeb9d70a507f8c916a8ac190fe8bfd8e"
 }