@wix/himalaya-cli 0.1377.0 → 0.1378.0

package/dist/cli.mjs

@@ -7708,6 +7708,7 @@ 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/index.json

@@ -240,6 +240,12 @@
       "category": "Wix SDK",
       "file": "wix-sdk-overview.md"
     },
+    {
+      "id": "wix-pro-gallery",
+      "title": "Build an app over Wix Pro Gallery",
+      "category": "Wix SDK",
+      "file": "wix-pro-gallery.md"
+    },
     {
       "id": "wix-login-integration",
       "title": "Add a Wix login gate",

package/guides/wix-api-usage.md

@@ -210,11 +210,11 @@ else the query 403s. In-repo, `core/dev-server/tier5-bundles-src/_shared/himi-cm
 
 ## Declared capability
 
-**Today** a worker touching a vertical / raw wixApi needs **no** `declared_capabilities` entry (the bridge is
-installed unconditionally). **Target (RFC 0043 D4):** declare **`wix_api`** — symmetric with `wix_platform`,
-enforced at both the SDK-import and native-registry layers. Declaring `wix_api` now is forward-compatible;
-once Phase 4 lands it becomes required. (Contrast: the cross-cutting facade `@himalaya/wix-platform` already
-requires `"wix_platform"`.)
+**Declare `wix_api`** for any worker that touches a vertical or raw `wixApi`. The web host's runtime denies a
+raw `wixApi.call` from a worker that did not declare it: the call fails with `capability not declared: wix_api`.
+Declare it in both places (the app-level `capabilities` in `config.ts` and the screen's `declaredCapabilities`) —
+see [Native capabilities](./himi-capabilities.md#2-declare--in-two-places). Declaring it is also what the other
+hosts will require. (Contrast: the cross-cutting facade `@himalaya/wix-platform` requires `"wix_platform"`.)
 
 ## Errors & best-effort
 

package/guides/wix-pro-gallery.md

@@ -0,0 +1,145 @@
+# Build an app over Wix Pro Gallery
+
+How to build a Himalaya app that shows a Wix site's **Pro Gallery** data: the galleries a site owner made in the Wix Editor and the images, videos and text items inside them.
+
+Read [the Wix API usage guide](./wix-api-usage.md) first for the `wixApi.call` bridge. This guide adds only what is specific to Pro Gallery.
+
+Each fact below names its source:
+
+- **[docs]** = a page on dev.wix.com (verified 2026-10-19).
+- **[call]** = a live call on a test site (2026-10-14; the list-limit and `itemLimit` checks were run again on 2026-10-19).
+- **[example]** = a Himalaya example app that renders all 13 Pro Gallery layouts and an expand-mode viewer.
+- **[device]** = a test on an Android emulator (2026-10-15 to 2026-10-18).
+
+## 1. What the API gives you
+
+[docs] The Pro Gallery API has these methods and no others:
+
+- Galleries: Create, Get, Update, Delete, List.
+- Gallery items: Create, Get, List, Update, Delete, Bulk Delete.
+- Webhooks: Gallery Created / Updated / Deleted and Gallery Item Created / Updated / Deleted.
+
+[docs] A gallery item is an image, a video or a text item. It has a title, a description and a link.
+
+[call] The gallery response holds items only. It has **no layout or style settings**. Your app picks a layout and stores its own settings (see section 6).
+
+## 2. Read the galleries the site owner made
+
+[docs] Wix does **not** recommend that you create galleries with the API. A gallery you create with the API exists only on the site's backend. It does not appear on the live site unless the owner connects it to a gallery component with code. Galleries that the owner adds in the Editor stay in sync both ways. Use the API to read and manage those galleries.
+
+[docs] The Gallery Created and Gallery Updated webhooks do not return the gallery's items. Listen to the Gallery Item Created and Gallery Item Updated webhooks for items.
+
+## 3. Read from a worker
+
+[call] A **visitor** token can read two endpoints:
+
+| Call | Use |
+| --- | --- |
+| `GET /pro-gallery/v2/galleries?limit=10&offset=&itemLimit=` | List galleries. The response has `totalGalleries` and, for each gallery, `name`, `totalItems` and the first `itemLimit` items. |
+| `GET /pro-gallery/v2/galleries/{id}?itemOffset=&itemLimit=` | One gallery. `gallery.totalItems` is the total number of items in the gallery (not a page count). Keep requesting with a growing `itemOffset` while it is below `totalItems`. |
+
+[call] Writes need an owner token. A visitor app does not write.
+
+[call] Limits you will hit:
+
+- `limit` is at most **10**. `limit=11` returns `limit got 11, expected 10 or less`.
+- `itemLimit` must be **1 or more**. `itemLimit=0` returns `itemLimit got 0, expected 1 or more`. To get only the gallery names and counts, ask for `itemLimit=1`.
+
+```ts
+const api = globalThis.himalaya?.wixApi;
+// First page of galleries, 4 preview items each
+const list = await api.call("GET", "/pro-gallery/v2/galleries?limit=10&offset=0&itemLimit=4");
+// One gallery, items 0..99. Keep paging with itemOffset while it is below gallery.totalItems.
+const one = await api.call("GET", `/pro-gallery/v2/galleries/${encodeURIComponent(id)}?itemOffset=0&itemLimit=100`);
+const { totalItems, items } = one.gallery;
+```
+
+[call] The same list call also returns 200 on `/progallery/v2/galleries` (checked 2026-10-19). The example app and this guide use `/pro-gallery/v2/...`.
+
+[example] The example app loads a gallery 100 items at a time and lists galleries 10 at a time.
+
+## 4. Item types
+
+All fields below come from [call] responses unless marked.
+
+| Item `type` | Where the media is | Notes |
+| --- | --- | --- |
+| `IMAGE` | `image.imageInfo`: `id`, `url`, `width`, `height`, `altText` | `url` is a `static.wixstatic.com` media URL. |
+| `VIDEO`, `video.type` = `WIX_MEDIA` | `video.videoInfo`: `url`, `resolutions[]` (mp4 `url`, `width`, `height`, `quality`), `posters[]` | Wix-hosted. The type is `WIX_MEDIA`, not `WIX`. |
+| `VIDEO`, `video.type` = `YOUTUBE` or `VIMEO` | `video.videoInfo.url` only | `resolutions` and `posters` are empty. There is no thumbnail in the response. |
+| `TEXT` | `text.html`, `text.css.backgroundColor` | The text is **HTML**. |
+
+Every item can also carry `title`, `description` and a `link` with `type`, `text`, `url` and `target`.
+
+Thumbnails for external video:
+
+- YouTube: build it from the video id, for example `https://img.youtube.com/vi/<id>/hqdefault.jpg` [example].
+- Vimeo: the response has no thumbnail, and this guide has no source for another way to get one. Show a placeholder.
+
+To create an image item you must pass the media id. Without it the call fails with `imageInfo … id must not be empty` [call].
+
+## 5. Resize images
+
+[docs] Add a transform to a Wix media URL:
+
+```
+{url}/v1/fit/w_{w},h_{h}/file.{ext}
+```
+
+- `fit` keeps the whole image. `fill` fills the box and crops. `crop` cuts a region (`x_`, `y_`, `w_`, `h_`).
+- `w` and `h` are 1 to 5000.
+- It works only for public media on `static.wixstatic.com`.
+- It never makes an image larger than the original.
+
+A `q_` quality parameter (for example `q_85`) also works in practice [example], but the transform page does **not** document it. Leave it out, or treat it as undocumented.
+
+Use a small size for tiles (the example app uses 800 px) and a large size for the full-screen viewer (2000 px).
+
+## 6. What the app must decide for itself
+
+- **Layout and display settings.** The API returns none, so choose a layout in the app and store the choice on the device [call].
+- **Loves / likes.** No page in the Pro Gallery API index, the gallery object, Get Gallery Item or the Velo backend introduction mentions loves or likes [docs]. An app can keep loves only on the device, so a count is that device's count.
+
+## 7. Layout recipes
+
+[example] Himalaya has no masonry or collage component. The example app builds all 13 Pro Gallery layouts (Grid, Masonry, Collage, Thumbnails, Slider, Slideshow, Panorama, Columns, Magic, Bricks, Mix, Alternate, Blog) like this:
+
+- **Masonry:** one single-column `Grid` per column. Split the items into the columns in the worker and bind each `Grid` to its own list.
+- **Collage-type layouts:** one row template for each shape of item group, chosen with `FragmentSlot`.
+- **Item ratio:** the example puts each item in one of six buckets by its width-to-height ratio, and picks row templates from the buckets.
+
+[example] A screen descriptor over **256 KiB** is rejected on push (`413 item_too_large`). `himi validate` and `himi test` do not check this size. A descriptor that holds all 13 layouts is too big, so the example app has **three gallery screens, one for each layout family**. A layout change to another family replaces the screen with the same gallery and settings.
+
+## 8. Viewer, slideshow, download and video on a device
+
+These come from Android emulator tests [device].
+
+- **Carousel.** A data-bound `Carousel` (`itemsPath`) is a plain scrolling row on native. It has no paging, no `onChange` and no autoplay. The example viewer and slideshow therefore show **one bound slide**, a swipe is `swipeDismiss`, and the example's slideshow autoplay is a `setTimeout` in the worker, guarded by `typeof setTimeout === "function"` [example]. Not every worker runtime has timers: the [Tier-5 guide](./tier-5-add-a-screen.md) says a worker has no clock and describes `refresh: { intervalMs, action }` and `_poll` for timed work. Autoplay was tested only with the `setTimeout` form, on Android; it was not tested with `refresh` or `_poll`.
+- **Declare the capabilities.** The download and video recipes below call `media_playback` and `photos`, and the worker calls the API with `wix_api`, which the web host denies when undeclared. The example app lists `media_playback`, `photos` and `wix_api` in the app-level `capabilities` in `config.ts`, and in the `declaredCapabilities` of every screen that runs its worker [example]. A call a screen did not declare is denied. See [Native capabilities](./himi-capabilities.md#2-declare--in-two-places).
+- **Download.** On Android, `photos.saveToLibrary` needs a file in the app's own store, not a URL. First call `media_playback.download` for the original image. Then pass the store-relative path to `photos.saveToLibrary`. The handle's `uri` is an absolute `file:` URI, and `saveToLibrary` rejects it.
+- **Wix video.** A Wix MP4 plays in the `Video` component.
+- **YouTube.** A YouTube embed in a `WebView` needs a `Referer` header. Without it the player shows "Error 153".
+- **Vimeo.** A Vimeo embed needs protected-media (DRM) support in the app. This is fixed in the app shell. An app binary built before the fix shows "Rights issue" on Android, so **rebuild the binary** (`himi dist`) with a current CLI and shell (see section 9).
+- **`WebView` URL from `$service:`.** On Android, a `WebView` whose `url` is a `$service:` binding never loads. Feed it from a one-row list and bind `$item.url`.
+
+## 9. Known limitations
+
+| Limitation | Status | Source |
+| --- | --- | --- |
+| No loves / likes in the public API. | Platform gap, no fix announced in the sources. Keep loves on the device. | [docs] |
+| Galleries made with the API do not show on the live site. | Wix design, stated in the Pro Gallery introduction. Create galleries in the Editor. | [docs] |
+| Vimeo shows "Rights issue" on Android. | Fixed in the app shell. Still present in binaries built before the fix: rebuild the binary. | [device] |
+| A data-bound `Carousel` does not page. | Open. One-slide viewer is the workaround; autoplay timing needs a worker timer (see section 8). | [device] |
+| A `WebView` bound to a `$service:` URL never loads on Android. | Open. Use the one-row list workaround. | [device] |
+| `photos.saveToLibrary` rejects a URL or an absolute `file:` URI on Android. | Open. Use the `media_playback.download` path in section 8. | [device] |
+| No thumbnail for Vimeo items. | Open. The response has none. | [call] |
+| The `q_` image parameter is undocumented. | Works in practice. Not on the Wix transform page. | [docs], [example] |
+
+## 10. Test data
+
+[call] To get test galleries on a site you own:
+
+1. Import media with `POST /site-media/v1/files/import`.
+2. Create galleries and items with an **owner** token (`wix token --site <msid>`).
+
+Remember section 2: a gallery created this way does not show on the live site, but a visitor read through the API returns it, so your app can show it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1377.0",
+  "version": "0.1378.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": "8715e384332676e713233834b2588b1eb2a99e95bb50e9a4cda54340"
+  "falconPackageHash": "797df247428aeadb6579acbf4bffa3856e28b369ea6eed3bc20ae80e"
 }