@wix/himalaya-cli 0.1447.0 → 0.1449.0

package/guides/designing-himi-screens.md

@@ -176,11 +176,13 @@ responsive master/detail. *Reach for `Card` to cluster, not to wrap every single
 (`columns: 1, columnsMedium: 2`); `Table` for tabular rows; `Carousel`/`Pager` for swipeable panels;
 `Timeline` for chronological events. Compose rows as `ListItem` / `LabeledContent` / `DisclosureGroup`
 cells inside a `Card([VStack(spacing: 0)])`.
-> **Don't make `LazyList` the screen root.** The native `ScreenView` already wraps a screen's content
-> in a scroll view, so a `LazyList` as the (modifier-wrapped) root collapses to **zero height and
-> renders blank**. For a feed/list *screen*, use a plain `vstack` of `Card`s — it scrolls with the
-> screen. Reach for `LazyList` only *nested* inside a bounded-height slot (a fixed-height panel, a
-> horizontal rail) where its own virtualized scroll is what you want.
+> For a feed/list *screen*, prefer a root `VStack` with a direct vertical worker-bound `LazyList`
+> when the screen has the simple root shape supported by the native host; Android flattens that
+> shape into one lazy root so long lists do not compose every row. Other root shapes stay on the
+> eager screen path, as does a root list that sets `pagination`, `stickyHeader` or
+> `rowSwipeActions`. A `LazyList` nested deeper inside the screen's outer scroll is rendered
+> eagerly on Android to avoid nested-scroll measurement failures, even in a fixed-height panel. A
+> worker-bound horizontal `LazyList` is eager on Android too, so keep rails short.
 
 **Text** — `Text` for a single styled string (`maxLines` to truncate); `RichText` for inline mixed
 marks (bold/italic/link within one paragraph); `RichContent` for a Wix Ricos document with blocks,
@@ -233,12 +235,12 @@ validation, which is what it used to cost.
 for the standard case; `Fab` for a single floating primary action on a scroll; `Menu` for a set of
 secondary actions behind one affordance. *One `primary` button per screen.* An **`iconOnly` button still
 needs a `title`** (`Button.title` is non-optional in the native schema — it doubles as the a11y label).
-> **Strict whole-screen decode — supply every required prop.** The native renderer decodes a screen's
-> descriptor with strict `Codable`: a single missing non-optional field (e.g. a titleless `Button`)
-> makes the **whole screen** fail to decode and fall back to the app's generic *"Couldn't load"* error
-> state — you do **not** get a partial render with one broken node. When a screen unexpectedly shows the
-> error state, suspect a missing required prop, not a network failure. (The dev-server serves it `200`;
-> the strictness is on-device.)
+> **Required fields still matter.** A single missing non-optional field (e.g. a titleless `Button`)
+> can make the **whole screen** fail to decode and fall back to the app's generic *"Couldn't load"*
+> error state. An unknown value in an optional enum field decodes to nil (the field is simply absent; only a required enum with an explicit fallback receives one), and an undecodable child
+> (for example an unknown required discriminator) is replaced by an `unknown` placeholder, so those cases do not discard the rest of the screen. When a
+> screen unexpectedly shows the error state, suspect a missing required prop, not a network failure.
+> (The dev-server serves it `200`; required-field validation is on-device.)
 
 **Navigation** — `Tabs` / `SegmentedControl` to switch peer views; `Pager` + `PageControl` for
 full-width swipe; `StepIndicator` for a wizard's progress; `CollapsingHeader` for a large-title-to-inline
@@ -313,8 +315,8 @@ build/validate/render cycles because the failure looks like a content bug rather
   "top". A wishlist heart authored as a top-right overlay therefore lands **center-right**. For a
   true corner overlay use a `ZStack` whose overlay child carries its own padding, rather than
   looking for an alignment value that does not exist. Authoring one anyway is a hard error —
-  `validate --strict` rejects an unknown enum value because the native decoders drop the whole
-  screen rather than degrading the field.
+  `validate --strict` still catches unknown enum values for authoring feedback, even though the
+  runtime decoders decode an unknown optional-field value to nil (a required discriminator degrades the child to an `unknown` placeholder) rather than discarding the whole screen.
 - **A `Text` sharing a flex row with a `Spacer` gets truncated or wrapped.** The spacer takes the
   slack the text needed. Give the text `fillMaxWidth` (or put it in its own row) instead of relying
   on the spacer to push a sibling; see the "centered separator" idiom above for the same hazard with

package/guides/himi-test.md

@@ -124,7 +124,7 @@ Only **unambiguous** defects, so a green run stays worth trusting:
 | `nav-target-missing` | **warning** | A `himi.open` whose target is neither a baked screen, nor one of the app's declared `linkableScreens`, nor an instance of one (`course_detail_c1` under the base `course_detail`) — the tap opens nothing. Only judged when the caller supplies the app's exact linkable set; an absent set means no opinion, never a guess. A target still carrying an **unresolved** `$` token is dropped before it becomes an edge and is never judged — but one that RESOLVED to a concrete id is judged, which is the point: `$item.detailScreenId` resolving to `course_detail_c1` against the first row is exactly the case the instance rule exists for. |
 | `poll-action-missing` | error | A `_poll` directive every host will silently ignore — an action the bundle never declares, a malformed `action`, a missing `id`, or a non-positive `intervalMs`. Each ends the same way: a screen that never refreshes, with nothing saying why. Nothing in the descriptor names the polled action, so no static check can see it. (A merely too-small interval is legal — the host clamps it.) |
 | `no-request-issued` | **warning** | A worker that uses the Wix transport but never fetches — "the screen loaded with sample data." A warning: a conditional or tap-triggered fetch is legitimate. |
-| `native-decode-failed` | error | Under `--native`, the real Swift/Kotlin decoder rejected the baked descriptor bytes (one bad enum blanks the whole screen on device) — or the release's `tokens.json`, reported with `screen: "tokens.json"`: both natives decode it in one strict pass, so a single fractional `typography.*.size` or a `motions.*.duration` written in seconds drops the whole theme. A token finding fails the run but never counts as a failed screen. |
+| `native-decode-failed` | error | Under `--native`, the real Swift/Kotlin decoder rejected the baked descriptor bytes (the oracle decodes strictly, so an unknown enum value or malformed child is reported here even though production decoding degrades it to a fallback or an `unknown` placeholder) — or the release's `tokens.json`, reported with `screen: "tokens.json"`: both natives decode it in one strict pass, so a single fractional `typography.*.size` or a `motions.*.duration` written in seconds drops the whole theme. A token finding fails the run but never counts as a failed screen. |
 | `token-type-invalid` | error | The package's tokens file holds a value a native `Int` field rejects — `typography.<k>.size` or `.weight`, `motions.<k>.duration` (milliseconds: `0.3` → `300`), or a `spacing` / `radius` entry — in the base document or any `idiom.<overlay>`. Both natives decode tokens.json in one strict pass, so one such value drops the WHOLE theme (iOS "Theme unavailable"; Android default palette and fonts) while the web preview looks right. Reported with `screen: "tokens.json"`, never counted as a failed screen; `himi validate` reports the same finding. |
 | `capability-undeclared` | error | A `capability.<id>.<verb>` call the screen's gate denied — reported from the gate itself, so it is raised **even when the worker catches the rejection** (which on device leaves a control that silently does nothing). Fix: declare the id on that screen's `logicBundle.declaredCapabilities` and in `config.ts` `capabilities`. One per capability per screen. See [Capabilities](#capabilities). |
 | `journey-failed` | error | A `himi-test.json` journey named an action the screen lacks, threw, or never rendered its `expectText`. |

package/guides/push-cli-onboarding.md

@@ -203,6 +203,37 @@ routes: [
 A notification whose link matches no route opens the app without navigating. `himi validate`
 warns when a declared route names a screen the app does not declare.
 
+### Notification action buttons
+
+Declare actionable categories in the app's source `config.ts`. The native shells render one
+button per category action on iOS and Android; the notification payload selects the category.
+This is structural app configuration, not a `himi notify send` flag:
+
+```ts
+push: {
+  categories: [{
+    id: "time.action-required",
+    actions: [
+      { id: "review", title: "Review" },
+      { id: "snooze", title: "Snooze 1h", input: true },
+    ],
+  }],
+  observerAction: "tier5.myNav.onNotification",
+},
+```
+
+The app-level worker action named by `observerAction` receives every notification through the
+existing observer path. Use `readNotificationEvent` from `@himalaya/push` to read its params:
+
+- `notificationAction` is the pressed action id, or `""` for a receipt or ordinary body tap.
+- `notificationText` is the inline reply for an `input: true` action, or `""` otherwise.
+- Action presses have `tapped: "false"`; they are responses to an already-observed notification,
+  not new arrivals. They never navigate. The body tap retains the existing link navigation.
+
+Each action has its own deduplication key, so a foreground receipt does not swallow a later button
+press and pressing the same button twice is reported once. A press received before the worker is
+configured is queued and replayed once the current site's configuration is ready.
+
 **Customer push QA builds use `himi dist --signing byo`.** After publishing an approved
 release, use a backend and reachable runner source that support the customer-signing flow.
 Use the app owner's account for both logins and explicitly select the deployed customer target:

package/guides/recipe-dynamic-list.md

@@ -14,6 +14,15 @@ the app's `.agents/skills/himalaya/examples/` (written by `himi init` and `himi
 card grids). `Carousel` and `Menu` take `itemsPath` the same way. Do **not** hand-roll
 a "VStack of Cards" — that renders only static items and can't bind live data.
 
+For a long list screen, make the vertical `LazyList` a direct child of the root `VStack`
+when the rest of the root uses only the supported simple layout. Android can then flatten
+the root into one `LazyColumn` and compose only visible rows. This applies only to a plain
+list: a `LazyList` that sets `pagination`, `stickyHeader` or `rowSwipeActions` keeps the
+screen's own scroll on Android and composes every row. A list nested deeper inside the
+screen's outer scroll also stays eager, and a fixed-height panel inside that scroll does not
+change that on Android. A worker-bound horizontal list is also eager on Android: it renders
+every row in a plain `Row`, so keep rails short.
+
 **`Grid` is not a `LazyList` with one column.** It shares `itemsPath` and the row
 template, and nothing else: the gesture props in §5 (`onPullToRefresh`, `pagination`)
 and `stickyHeader`/`rowSwipeActions` are declared on `LazyListProps` only. A key `Grid`

package/guides/testing-himi-apps.md

@@ -317,9 +317,9 @@ findings appear as accepted-risk entries so the file stays auditable.
 
 ### What it cannot tell you
 
-This is the **web renderer's** view. It cannot see native decode strictness (one bad enum field
-blanks an entire iOS/Android screen while this tree looks healthy) or components that render
-blank on device when bound — so rather than pass those silently it names them:
+This is the **web renderer's** view. It cannot see native-only decode failures (for example, a
+missing required field can still blank an iOS/Android screen while this tree looks healthy) or
+components that render blank on device when bound — so rather than pass those silently it names them:
 
 ```
   ⚠ 2 nodes NOT verifiable headless:

package/guides/wix-api-usage.md

@@ -104,6 +104,23 @@ response. The client holds **no** auth or HTTP —
 that's `WixApiCapability` (attaches auth per call, 401→refresh→retry). Import the domain by its canonical
 package `@himalaya/wix-<domain>` (unversioned name; the REST version is in the path — RFC 0043 D2).
 
+### Read an owner-created async job
+
+The first-party `@himalaya/wix-async-jobs` client exposes the current state of an async job through the
+Wix gateway. It is an owner-scoped read and requires `INFRA.ASYNC_JOB_READ`; visitor sessions receive
+403. Poll the returned `job.status` while it is `INITIALIZED` or `PROCESSING`, and stop at `FINISHED`
+or `FAILED`:
+
+```ts
+import { getAsyncJob } from "@himalaya/wix-async-jobs";
+
+const { job } = await getAsyncJob(jobId);
+const status = job?.status;
+```
+
+The client calls `GET /async-jobs/v1/async-jobs/{jobId}`. A missing job is an HTTP 404 with
+`JOB_NOT_FOUND`; do not treat that response as authorization evidence.
+
 > **Catalog V1 vs V3 — use V3 by default.** For a new Stores reader use
 > **`queryStoreProducts`** (POST
 > `/stores/v3/products/query`) and **`getStoreProduct`**, from the same `@himalaya/wix-stores`

package/guides/wix-sdk-overview.md

@@ -43,6 +43,7 @@ Same idea, one canonical entry — don't reach for the others:
 | I want to… | Canonical door | Layer |
 |---|---|---|
 | Read/write a Wix domain (products, bookings, members…) | `@himalaya/wix-<domain>` from a worker | L3 |
+| Read the state of an owner-created async job | `@himalaya/wix-async-jobs` → `getAsyncJob(jobId)` | L3 |
 | Emit a BI beacon | `wix-platform.bi` | L2 |
 | Conduct an experiment / read a flag | `wix-platform.experiments` / `wix-platform.flags` | L2 |
 | Translate a string / read the locale | `wix-platform.i18n` | L2 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1447.0",
+  "version": "0.1449.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": "ec7806275850384530f4bb3f9e2a1ee23e66bf5223389c5dc7a3446a"
+  "falconPackageHash": "9703ffb9052d9fc0ed9a8ec8510c21e600640b5a10c12c51d336e278"
 }