@wix/himalaya-cli 0.1610.0 → 0.1612.0

package/dist/quickjs-worker-entry.js

@@ -134,6 +134,10 @@ async function boot(msg) {
       let sweepError = null;
       try {
         actions = drain(ctx, runtime, msg.skipLoad ? "himi.quickjs.actions" : "himi.quickjs.loads");
+        if (msg.settleAuthoredActions) {
+          drainDetachedJobs(ctx, runtime);
+          actions = readbackJson(ctx, actionsReadback);
+        }
       } catch (e) {
         sweepError = String(e?.message ?? e);
       }

package/fixtures/wix-canned.json

@@ -1047,6 +1047,47 @@
       }
     ]
   },
+  "GET /loyalty-tiers/v1/tiers/program": {
+    "programSettings": {
+      "status": "ACTIVE",
+      "baseTierDefinition": {
+        "name": "Bronze"
+      },
+      "rollingWindow": {
+        "durationInMonths": 12
+      }
+    },
+    "tiers": [
+      {
+        "id": "tier-0001",
+        "tierDefinition": {
+          "name": "Silver"
+        },
+        "requiredPoints": 500
+      },
+      {
+        "id": "tier-0002",
+        "tierDefinition": {
+          "name": "Gold"
+        },
+        "requiredPoints": 1000
+      }
+    ]
+  },
+  "GET /loyalty-coupons/v1/coupons/my-coupons": {
+    "loyaltyCoupons": [
+      {
+        "id": "lc-0001",
+        "rewardName": "Free filter coffee",
+        "status": "ACTIVE",
+        "couponReference": {
+          "couponId": "cp-0001",
+          "code": "BEANS-0001",
+          "deleted": false
+        }
+      }
+    ]
+  },
   "POST /reviews/v1/reviews/query": {
     "reviews": [
       {

package/guides/component-reference.json

@@ -1,7 +1,7 @@
 {
   "_comment": "GENERATED by core/web-embed/authoring/gen-reference.mjs from core/ts/src/schema.ts — do not hand-edit. The schema is the source of truth; regenerate on schema changes.",
   "schemaSource": "core/ts/src/schema.ts",
-  "bindingGrammar": "$service:<service>.<path> (worker state) · $item.<field> (list row) · $flag:<key> (feature flag) · $env:<key> (client environment — #1056). Bindings resolve in the text/value props marked 'binding-aware' below — INCLUDING Modifiers token refs — but only `background` and `border.color`, which are the two whose token a binding actually fills: a worker can drive per-item theming (e.g. a game board's per-square color), not just text. `shadow` is NOT binding-aware on any renderer, and a gradient is driven by its own `backgroundGradientPath` prop resolving to a gradient token NAME, not by a binding inside a token ref — so `shadow: { token: \"$item.x\" }` and `backgroundGradient: { token: \"$item.x\" }` keep the sentinel and silently lose the per-item styling. Colour slots split by LEVEL, not by component: inside modifiers a colour is a TokenRef OBJECT ({ token: \"…\" }), inside props it is a bare TokenName STRING — there is no modifiers.color or modifiers.tint (see the 'Token slots' section in component-reference.md). A few input props render the LITERAL and are NOT binding-aware — notably SearchField.placeholder and Chip.label; SearchField.value is live and binding-aware like other content props. Bindings also CANNOT target strict-enum fields (style, size, alignment, severity, presentation, contentMode, …) — those fail at render, not validation. $env: is client-resolved (no worker) and valid in modifiers.hiddenPath and FragmentSlot.casePath ONLY — keys reduceMotion/colorScheme/sizeClass/isRTL, e.g. hiddenPath:\"$env:reduceMotion\" or hiddenPath:\"$env:colorScheme==light\", casePath:\"$env:colorScheme\"; unknown key fails open (shown / defaultCase).",
+  "bindingGrammar": "$service:<service>.<path> (worker state) · $item.<field> (list row) · $flag:<key> (feature flag) · $env:<key> (client environment — #1056). Bindings resolve in the text/value props marked 'binding-aware' below — INCLUDING Modifiers token refs — but only `background` and `border.color`, which are the two whose token a binding actually fills: a worker can drive per-item theming (e.g. a game board's per-square color), not just text. `shadow` is NOT binding-aware on any renderer, and a gradient is driven by its own `backgroundGradientPath` prop resolving to a gradient token NAME, not by a binding inside a token ref — so `shadow: { token: \"$item.x\" }` and `backgroundGradient: { token: \"$item.x\" }` keep the sentinel and silently lose the per-item styling. Colour slots split by LEVEL, not by component: inside modifiers a colour is a TokenRef OBJECT ({ token: \"…\" }), inside props it is a bare TokenName STRING — there is no modifiers.color or modifiers.tint (see the 'Token slots' section in component-reference.md). A few input props render the LITERAL and are NOT binding-aware — notably SearchField.placeholder and Chip.label; SearchField.value is live and binding-aware like other content props. Bindings also CANNOT target strict-enum fields (style, size, alignment, severity, presentation, contentMode, …) — those fail at render, not validation. $env: is client-resolved (no worker) and valid in modifiers.hiddenPath and FragmentSlot.casePath ONLY — keys reduceMotion/colorScheme/sizeClass/isRTL/keyboardVisible, e.g. hiddenPath:\"$env:reduceMotion\" or hiddenPath:\"$env:colorScheme==light\", casePath:\"$env:colorScheme\"; unknown key fails open (shown / defaultCase).",
   "componentCount": 88,
   "notImplementedComponents": [
     "Text",

package/guides/component-reference.md

@@ -6,7 +6,7 @@
 **88 core component types.** Every component body is `{ "package": "himalaya", "type": "<Type>", "props": { … } }`.
 Binding grammar: `$service:<service>.<path>` (worker state) · `$item.<field>` (list row template) · `$flag:<key>` (feature flag) · `$env:<key>` (client environment — #1056).
 Bindings resolve in the text/value props marked **binding-aware** below — **including two `Modifiers` token refs**, `background` and `border.color`, which are the only two whose token a binding actually fills: a worker can drive per-item **theming** (e.g. a game board's per-square color, `background: { token: "$item.bg" }`), not just text content. `shadow` and `backgroundGradient` are `TokenRef`s but are **not** binding-aware on any renderer — `shadow: { token: "$item.x" }` keeps the sentinel as a literal token name and silently loses the per-item styling, and a gradient is driven by its own `backgroundGradientPath` prop resolving to a gradient token NAME, not by a binding inside a token ref.
-`$env:` is **client-resolved** (no worker) and valid in `modifiers.hiddenPath` and `FragmentSlot.casePath` **only** — keys `reduceMotion` / `colorScheme` / `sizeClass` / `isRTL`, with an optional `==`/`!=` comparison (e.g. `hiddenPath: "$env:reduceMotion"`, `hiddenPath: "$env:colorScheme==light"`, `casePath: "$env:colorScheme"`). An unknown key fails open (shown / `defaultCase`).
+`$env:` is **client-resolved** (no worker) and valid in `modifiers.hiddenPath` and `FragmentSlot.casePath` **only** — keys `reduceMotion` / `colorScheme` / `sizeClass` / `isRTL` / `keyboardVisible` (an on-screen keyboard is up — `hiddenPath: "$env:keyboardVisible"` hides a header while typing), with an optional `==`/`!=` comparison (e.g. `hiddenPath: "$env:reduceMotion"`, `hiddenPath: "$env:colorScheme==light"`, `casePath: "$env:colorScheme"`). An unknown key fails open (shown / `defaultCase`).
 A few input props render the **literal** and are **not** binding-aware — notably `SearchField.placeholder` and `Chip.label`. `SearchField.value` is live/binding-aware like other content props.
 They **cannot target strict-enum fields** (`style`, `size`, `alignment`, `severity`, `presentation`, `contentMode`, …) — those fail at render time, not validation.
 

package/guides/getting-started.md

@@ -166,7 +166,9 @@ worker layer — trim it or mine it (`himi docs trim-a-template`): **trim** to t
 lists its screens (size, workers, `onAppear`), `--show <id>` prints one entry, and
 `--write <id> --from <file>` puts an edited entry back (refused if it breaks the file), and
 `--add <id> --from <file>` appends a NEW screen and registers it as linkable — the authoring half
-of mining a template. Not sure
+of mining a template. To add a screen, clone the closest one: `--show <closest>`, change the id
+and content, then `--add <new> --from <file> --display-name "<New title>"` (view names must be unique). `--from` takes that entry, a ScreenDescriptor
+JSON object, or `{ "<id>": <ScreenDescriptor> }`; never edit `dev/index.ts` by hand. Not sure
 which template fits? `himi template recommend --text "<the business>"` (or `--book <site analyze
 dir>` for a site's verticals) ranks the catalog with reasons. For a small **non-Wix** pattern, `himi init --template chat-bot --remote`. `himi template
 list --remote` shows the full catalog (title/description/tags) — including templates published

package/guides/himi-json-output.md

@@ -40,6 +40,17 @@ keeps its existing fields and adds the code:
 }
 ```
 
+## `himi test` authored journey failures
+
+| Code | Meaning |
+| --- | --- |
+| `test_journey_failed` | At least one unsuppressed authored journey failed: its destination is absent, initialization/action failed, or the expected rendered values were missing. The existing `failures`, `journeys`, counts and exit 1 remain. This includes cold-entry journeys with `steps: []`. |
+| `test_input_evidence_requires_json` | `--input-evidence` was requested without explicit `--json`. Exit 2 before build or worker execution. |
+| `test_input_evidence_unsupported_mode` | `--input-evidence` was combined with `--browser`, or the content is a functions package rather than an app worker crawl. Exit 2 before execution. |
+| `test_input_evidence_unavailable` | The isolated input crawl cannot establish all contained realms, cannot read a stable source archive before/after the crawl, or fails to return one complete JSON report (including interruption, process timeout or output limit). Exit 1; no host-realm fallback or positive input acceptance. |
+
+This is a scoped migration. Other legacy `himi test` failure paths retain their existing envelopes.
+
 ## `himi icon from-one-app` codes
 
 | Code | Meaning |
@@ -300,15 +311,17 @@ whole body gzip-encoded because it is over the plain 8 MB cap:
 |---|---|
 | `compressed_publish_unsupported` | The publish body went out gzipped and the publishing service did not accept it compressed. It either read the bytes as malformed JSON, or measured the decompressed body against the 8 MB uncompressed limit (HTTP 413). Either the service does not accept compressed bodies yet, or the credential is a self-serve one, which keeps the 8 MB uncompressed limit. Nothing was written. |
 
-## `himi template screens --upsert` codes
+## `himi template screens --upsert | --add | --write` codes
 
-`--upsert` writes many generated screens at once. Its refusals carry a code; nothing is written
-on any of them (a failed batch restores every file). Other `template screens` paths stay legacy.
+`--upsert` writes many generated screens at once; `--add <id>` and `--write <id>` write one. Their
+`--from` refusals carry a code; nothing is written on any of them (a failed batch restores every
+file). Other `template screens` paths, and `--add`/`--write` refusals about the package itself
+(an existing id, a symlink, a result that would not parse), stay legacy.
 
 | Code | Meaning |
 |---|---|
-| `invalid_usage` | `--upsert` was given without `--from <file>`. Exit 2. |
-| `invalid_input` | The `--from` file cannot be read or is not JSON. Exit 2. |
+| `invalid_usage` | `--upsert`, `--add` or `--write` was given without `--from <file>`. Exit 2. |
+| `invalid_input` | The `--from` file is missing, unreadable or not JSON. For `--add`/`--write` also: it is not a ScreenDescriptor object, `{ "<id>": <ScreenDescriptor> }` or the entry `--show` prints, or its key or `screenId` is not the `<id>` given; a templated route (`{ pattern, display, template }`) takes back only the text `--show` prints for it. `error` names the file. Exit 2. |
 | `upsert_refused` | The JSON is not `{ "<screenId>": <ScreenDescriptor> }`, an id or `screenId` does not match, the result would not parse as plain SCREENS entries, or a target file is a symlink. `error` names which. Exit 2. |
 
 ## `himi site member-app` codes

package/guides/himi-skill.md

@@ -189,7 +189,9 @@ worker layer — trim it or mine it (`himi docs trim-a-template`): **trim** to t
 lists its screens (size, workers, `onAppear`), `--show <id>` prints one entry, and
 `--write <id> --from <file>` puts an edited entry back (refused if it breaks the file), and
 `--add <id> --from <file>` appends a NEW screen and registers it as linkable — the authoring half
-of mining a template. Not sure
+of mining a template. To add a screen, clone the closest one: `--show <closest>`, change the id
+and content, then `--add <new> --from <file> --display-name "<New title>"` (view names must be unique). `--from` takes that entry, a ScreenDescriptor
+JSON object, or `{ "<id>": <ScreenDescriptor> }`; never edit `dev/index.ts` by hand. Not sure
 which template fits? `himi template recommend --text "<the business>"` (or `--book <site analyze
 dir>` for a site's verticals) ranks the catalog with reasons. For a small **non-Wix** pattern, `himi init --template chat-bot --remote`. `himi template
 list --remote` shows the full catalog (title/description/tags) — including templates published

package/guides/himi-test.md

@@ -74,6 +74,80 @@ Each stage runs on hermetic data with zero network:
 Engine: `core/dev-server/src/screen-crawl.ts`.
 CLI orchestration: `tools/himi-cli/src/test.ts`.
 
+## Machine input evidence
+
+`himi test --content <dir> --input-evidence --json` opts into additive
+`inputEvidence.version: 1` output. The local evaluator records actual dispatches; it
+does not interpret a Plan or decide whether a warning is benign. The flag requires
+explicit `--json`; browser-loop and functions-package modes refuse it with typed
+failure codes. An older CLI may omit the field: treat that as capability missing,
+never as a passing scan.
+
+The CLI runs this opt-in crawl in a separate process, enables the existing compiler
+import confinement, and establishes QuickJS/WASM realms for generated dev modules,
+config, worker boot and worker actions before loading generated modules. Explicit
+host-realm overrides or unavailable isolation refuse with
+`test_input_evidence_unavailable`; there is no host fallback. Packages containing
+symlinks are refused. The compiler accepts package-owned files and CLI-owned
+source/staged SDK roots; it does not expand arbitrary app or ancestor dependency
+links into trusted roots. A separate editor SDK install cannot substitute for the
+pinned CLI's runtime in this mode. The trusted caller must keep the generated
+source and its environment quiescent during capture and bind the final subject. The local
+receipt CLI projects only the caller-owned public `WIX_CLIENT_ID` and `WIX_SITE_URL`
+into contained config/dev compilation, preserving their supplied values. Other
+host environment keys (including secrets) are omitted; tokenless/default contained
+callers still receive an empty environment. Capture those public bindings with
+the run environment; the CLI does not choose an identity or provision a site.
+Packages requiring host filesystem/network work during config or descriptor construction must report
+that limitation instead of issuing contained evidence. The isolated crawl has a
+three-minute process limit; interruption forwards SIGTERM/SIGINT to its child.
+
+The receipt has these fields:
+
+| Field | Evidence |
+| --- | --- |
+| `subject` | Actual app, tested release ID and payload hash, test run ID, source diff/untracked hashes, and SHA256 of the exact `himi-test.json` bytes parsed for the run (`absent` when missing). `sourceArchiveHash` is SHA256 of the base64 deterministic ZIP from the publish source collector, including authored `himi-test.json`. It is captured before loading generated modules and rechecked after the crawl; unreadable or changed source refuses with `test_input_evidence_unavailable`. Generated `.himi` outputs are excluded by the shared archive rules. Git hashes may explicitly be `unavailable`. |
+| `execution` | CLI-established `devModule`, `appConfig`, `workerBoot` and `workerAction` modes, each `quickjs-wasm`. A v1 report missing these fields predates the contained CLI path; do not accept it as contained execution. This marker is meaningful only when captured from the trusted pinned producer. |
+| `probes` | Each synthesized typed dispatch's screen/component/action/hook, contract control and injected field/value, actual argument list, precondition input/current value/state hash, post-state hash, and observed state/navigation/request/host-call/throw results. Zero probes is not proof that required controls ran. |
+| `journeys` | Actual screen/input, each attempted step's scope, raw `declaredPayload`, effective row-resolved `descriptorPayload`, exact `testOverrides`, final merged `payload`, pre/post state hashes, executed/threw/not-dispatched status, final visible observations and evaluator-computed assertions. Unavailable actions remain not-dispatched, never successful steps. |
+| `unavailableScreens`, `unavailableJourneys` | Requested coverage for which the evaluator did not supply v1 evidence, including older engines, invalid/collapsed screens and unavailable journeys. With positional screen IDs, these lists contain only requested roots; requested unknown IDs remain unavailable. Unrelated configured journeys do not run or fail a scoped run. These gaps are not accepted behavior. |
+
+State hashes fingerprint the exact serialized worker snapshot captured at the dispatch
+boundary. `currentValuePresent` distinguishes an absent current value from null.
+Input records include the implicit screen ID, then baked descriptor input and route
+overrides with the same precedence the worker receives.
+Requests and host calls are attempted hermetic effects, not live-service success.
+Journey assertion kind `observation-substring` states the existing operator exactly:
+substring inclusion in joined visible `nodeId.field=value` lines. It does not prove
+exact text equality, complete result sets, absence of extra rows, or that an
+agent-authored expected value is an independently approved oracle.
+
+Journey parameters are synthetic overrides. A journey that replaces a descriptor's
+literal service-reference ID with a real ID tests that synthetic dispatch, not the
+actual UI tap. Inspect `testOverrides` alongside `descriptorPayload`; a passing
+assertion cannot waive a failing descriptor-driven flow. Worker (`tier5.*`) actions
+keep authored params/args literal by the existing action contract; reducers read
+their selected record from state/input rather than expecting nested service binding
+evaluation. This evidence does not change that contract.
+The origin fields are always present: unavailable declared/effective payloads and
+absent test parameters are explicit `null`; an explicitly empty override is `{}`.
+An omitted origin field is unknown, not evidence that no override occurred.
+
+This output leaves `ok`, finding severities and suppressions unchanged. In particular,
+`typed-value-ignored` remains a warning and can coexist with `ok: true`. Use the
+structured finding invariant/screen/trigger/field/axis to apply a separate trusted
+acceptance policy; do not parse message prose or reject every warning. Finding IDs
+are stable grouping identities, not unique case/dispatch IDs. Inspect suppressed,
+skipped and absent coverage explicitly. A different successful input cannot excuse
+an untested or failed required input.
+
+Attestation v2 still binds only aggregate report/coverage values alongside its
+existing source/release/descriptor/screenshot hashes; it does not acquire new
+acceptance semantics. A trusted host must capture the actual pinned CLI process
+exit/stdout, bind the full report to its own run and immutable final source/release,
+and supply independent required-control/case policy. Neither a negative-clear scan
+nor an unkeyed receipt is whole-product acceptance or trusted agent prose.
+
 ## Typed form journeys
 
 The crawl types into a control **only when it can read a legal value off the app itself** — an id
@@ -115,6 +189,19 @@ edge would hand it — so the journey boots the way a real tap into it would. Ke
 navigation in the ordinary edge pass, which boots the destination with real source
 parameters. Pair dynamic journeys with app-specific `dev/net-mocks.json` fixtures.
 
+Journeys run only the initialization the bundle and descriptor actually declare: module-scope
+calls and the root `onAppear`. Unlike the discovery crawl's convenience `load()` sweep, they do
+not call an otherwise uncalled loader. A declaration of `actions.load` alone does not initialize
+a cold screen on device.
+
+Use `"steps": []` to assert the result of entering a detail screen, without adding a synthetic
+load tap that could conceal missing initialization. Add separate journeys with different `input`
+IDs and requirement-derived `expectText` (title, notes, metadata and numeric values). Include
+missing/stale IDs and a not-found expectation. These are independent cold entries, not proof of
+back/return, state carry-over or the source row's emitted navigation params; verify those with
+real interactions as well. A green derived crawl without such expectations does not establish
+that a detail shows the selected record.
+
 ## What it checks
 
 Only **unambiguous** defects, so a green run stays worth trusting:
@@ -483,6 +570,7 @@ behavior. This instruction does not add an automatic suppression or retry gate t
 | `--offline` | Strip every data layer — see the failure UI head-on. (Excludes `--net`.) |
 | `--no-hostile` | Skip the empty-list / all-500 passes. |
 | `--no-shots` | Skip the per-screen PNGs written to `.himi/shots/`. |
+| `--input-evidence` | Requires `--json`; capture actual typed probes and authored-journey receipts in contained local worker mode (see the receipt contract above). |
 | `--net <file>` | Use an explicit net-mocks file instead of the app's own. |
 | `--budget <ms>` | Per-action settle budget (default 2000). |
 | `--native` | Also decode every baked descriptor, and the release's `tokens.json`, with the real native decoders; bare `--native` runs whichever toolchains are present and names each one it could NOT check in a top-level `skippedPlatforms: [{ platform, reason }]` (never a pass), while `--native ios` or `--native android` selects one and exits 2 when it is unavailable. The Android SDK is found from `ANDROID_HOME`, then `ANDROID_SDK_ROOT`, then `sdk.dir` in the source checkout's Android test harness `local.properties`, then the default install path (`~/Library/Android/sdk` on macOS, `~/Android/Sdk` on Linux). **Source-checkout only** — the decoder oracles are that tree's own HimalayaCore Swift package and Gradle harness, which a published install does not ship, so it cannot run this at all (and its coverage ledger stays silent about native decoding rather than suggesting it). |

package/guides/one-app-section-mappings.md

@@ -25,8 +25,8 @@ Source snapshots: Catalyst `617c06d43d2a5608b6876d724553269b1e5346f0`; Himalaya
 | Module | 13 |
 | Primitive | 7 |
 | Composition | 9 |
-| Partial | 24 |
-| Empty | 24 |
+| Partial | 25 |
+| Empty | 23 |
 | Total | 77 |
 
 ## Mappings by server group
@@ -127,7 +127,7 @@ carousel placement remain separate gaps; the mappings above stay Partial.
 
 | Source sectionDefinitionId | Source viewer component | Himalaya implementation | Placement / reuse | Class | Settings, actions and gaps |
 | --- | --- | --- | --- | --- | --- |
-| `loyalty_status_section` | `loyalty.components.StatusSection` |  |  | Empty | The existing Loyalty worker lists the program and rewards but does not load this member's points balance/tier/status. A rewards catalog is not a loyalty-status widget. |
+| `loyalty_status_section` | `loyalty.components.StatusSection` | [himi_loyalty member card](https://github.com/wix-private/himalaya/blob/adf4c8b47fd237307b278a5dbb8198a94b7feb69/apps/himi-branded-lite/dev/index.ts) (`buildLoyalty` points card) + [loyalty worker](https://github.com/wix-private/himalaya/blob/adf4c8b47fd237307b278a5dbb8198a94b7feb69/core/dev-server/tier5-bundles-src/himi-branded-lite-loyalty/index.ts "audience-lint-ok: optional pinned upstream evidence, not a local authoring dependency") | Existing base; adaptation needed | Partial | The member card on `himi_loyalty` reads the signed-in member's balance (`getCurrentMemberLoyaltyAccount`) and, beside it, the tiers program and the claimed coupons; it shows the balance, the tier name, the points-expiry line and `Rewards available (N)` (rewards the balance covers on the member's tier + ACTIVE claimed coupons), each blank when its read fails. Visitors get the sign-in gate. Not carried over: the referral-coupon share of the count (no referral spec in codegen) and the one-app `View` link (the catalog it opens is on the same screen). |
 | `loyalty_offering_section` | `loyalty.components.OfferingSection` | [himi_loyalty](https://github.com/wix-private/himalaya/blob/97f1542f2f7d6e8cb7a902b912c87dcaa37e5a67/apps/himi-branded-lite/dev/index.ts) + [rewards worker](https://github.com/wix-private/himalaya/blob/97f1542f2f7d6e8cb7a902b912c87dcaa37e5a67/core/dev-server/tier5-bundles-src/himi-branded-lite-loyalty/index.ts "audience-lint-ok: optional pinned upstream evidence, not a local authoring dependency") | Existing base; adaptation needed | Partial | Reuse program/reward reads and required-points presentation. Preserve offering selection. Member earning/redemption operations are not established by this read-only rewards list. |
 
 ### 8. referrals-section-definitions.json
@@ -355,7 +355,6 @@ These are the exact definitions whose target cells above remain empty. “Not fo
 | `events-section-definitions.json` | `events_discussion_section` | No event-scoped discussion implementation was found. Groups/social feed and Blog comments must not be selected automatically. |
 | `events-section-definitions.json` | `events_guests_section` | The Events detail has only a best-effort attendee summary/avatar strip using an owner-scoped guest query. It is not a full consumer guest-list section; leave the mapping unassigned. |
 | `groups-section-definitions.json` | `single_group_feed_section` | A feed exists, but it selects a relevant/home group internally and does not accept the configured fixed-group selector. No verified single-group feed adapter exists; keep this target empty until a policy/implementation is chosen. |
-| `loyalty-section-definitions.json` | `loyalty_status_section` | The existing Loyalty worker lists the program and rewards but does not load this member's points balance/tier/status. A rewards catalog is not a loyalty-status widget. |
 | `referrals-section-definitions.json` | `referrals_refer_section` | No consumer referral-code/link sharing and referral-status feature was found. Do not map to Loyalty or generic sharing without a user decision. A visitor-readable program read exists; see the row above. |
 | `referrals-section-definitions.json` | `referrals_description_section` | No referral-program description/data implementation was found. Text primitives alone do not resolve the business-bound referral content. A visitor-readable program read exists; see the row above. |
 | `photoalbum-section-definitions.json` | `photoAlbums_list_section` | Existing Photo Albums code is an empty-state placeholder with no album API wired. Pro Gallery uses a different data source and is not a substitute; choose an implementation explicitly. |

package/guides/qa-builds.md

@@ -636,6 +636,14 @@ gradle read the tree. The shell supplies the project; it no longer supplies the
 | `apps/<app>/ios/project.yml`, then its `build.gradle.kts` | the content app has source in this checkout — it already declared a version, so nothing new has to be declared |
 | the SHELL's own declared version | an off-repo app that declares nothing anywhere. Deliberate: `CFBundleShortVersionString` is **also** the OTA rollout floor (`HimalayaApp.swift` passes it as `binaryVersion`; serve-control's `resolveRelease` skips any ring whose `minBinaryVersion` it fails, and returns nothing when none qualifies), and the shell's version is the truth about what the binary can render |
 
+Branded Lite keeps the two apart, so the store version never moves its rollout floor. Its Android
+app reports `BuildConfig.SHELL_VERSION` as the OTA `binaryVersion`, and its iOS app the Info.plist
+key `HimalayaShellVersion`. Each is pinned equal to the shell's committed version. So a
+Containers app's App Store build, which stamps the owner's version into `CFBundleShortVersionString`
+through `APP_VERSION`, still reports the shell's version to update checks, and the build log says so.
+A shell commit older than the key reports `CFBundleShortVersionString`, as before. Force update
+(`minVersion`) compares the store version on both.
+
 The **build number** (`CFBundleVersion` / `versionCode`) is seconds since 2020-01-01Z, so it is
 monotonic and unique per app per second — App Store Connect rejects a duplicate version/build pair,
 and Play requires `versionCode` to increase.

package/guides/release-notes.md

@@ -14,6 +14,18 @@ areas, always in the same order, so you can skim for the one you care about.
 
 ---
 
+## 2026-11-08
+
+### Getting started & the CLI
+
+- **`himi template screens --add` and `--write` now take the screen as JSON.** `--from` accepts a
+  plain ScreenDescriptor (the id comes from `--add <id>` / `--write <id>`), `{ "<id>": <ScreenDescriptor> }`,
+  or the entry `--show` prints. Before, only that `--show` entry worked, and a JSON file failed with an
+  error pointing at a line of `dev/index.ts`. A file that is not one of these shapes, has a different
+  id or cannot be read is refused with `code: "invalid_input"`, and the error names your file. To add
+  a screen, clone the closest one: `--show <closest>`, edit it, then
+  `--add <new> --from <file> --display-name "<title>"`. (#5422)
+
 ## 2026-11-04
 
 ### Branded Lite & Owner Lite

package/guides/sdk-reference.json

@@ -23425,19 +23425,43 @@
         "name": "WixLoyaltyRewardConfig",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface WixLoyaltyRewardConfig {\n  tierId?: string;\n  costInPoints?: number;\n  amount?: number;\n  percentage?: number;\n}"
+        "decl": "export interface WixLoyaltyRewardConfig {\n  tierId?: string;\n  costInPoints?: number;\n  amount?: string | number;\n  percentage?: number;\n}"
+      },
+      {
+        "name": "WixLoyaltyTierConfig",
+        "kind": "type",
+        "jsdoc": "/** One reward price row: what the reward costs a member on tier `tierId` (absent = the base tier). */",
+        "decl": "export type WixLoyaltyTierConfig = WixLoyaltyRewardConfig;"
       },
       {
         "name": "WixLoyaltyProgram",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface WixLoyaltyProgram {\n  id?: string;\n  name?: string;\n  /** ACTIVE | DRAFT | PAUSED */\n  status?: string;\n  pointDefinition?: { customName?: string; icon?: WixLoyaltyImage };\n}"
+        "decl": "export interface WixLoyaltyProgram {\n  id?: string;\n  name?: string;\n  /** ACTIVE | DRAFT | PAUSED */\n  status?: string;\n  pointDefinition?: { customName?: string; icon?: WixLoyaltyImage };\n  /** Which premium loyalty features the site's plan unlocks. Absent on older responses. */\n  premiumFeatures?: { loyaltyProgram?: boolean; tiers?: boolean; pointsExpiration?: boolean };\n  /** The program-level expiry POLICY (not a member's date — that is `WixLoyaltyAccount.pointsExpiration`). */\n  pointsExpiration?: { status?: string; monthsOfInactivity?: number; expiringPointsPercentage?: number };\n}"
       },
       {
         "name": "WixLoyaltyReward",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface WixLoyaltyReward {\n  id: string;\n  name?: string;\n  type?: string;\n  /** Legacy adapter field. REST costs live in the reward's tier configurations. */\n  requiredPoints?: number;\n  discountAmount?: { configsByTier?: { tierId?: string; costInPoints?: number; amount?: string }[] };\n  couponReward?: {\n    fixedAmount?: { configsByTier?: WixLoyaltyRewardConfig[] };\n    percentage?: { configsByTier?: WixLoyaltyRewardConfig[] };\n    freeShipping?: { configsByTier?: WixLoyaltyRewardConfig[] };\n  };\n  active?: boolean;\n}"
+        "decl": "export interface WixLoyaltyReward {\n  id: string;\n  name?: string;\n  /** DISCOUNT_AMOUNT | COUPON_REWARD | COUPON | SPI_DISCOUNT_AMOUNT | … */\n  type?: string;\n  /** Legacy adapter field. REST costs live in the reward's tier configurations. */\n  requiredPoints?: number;\n  discountAmount?: { configsByTier?: WixLoyaltyRewardConfig[] };\n  couponReward?: {\n    fixedAmount?: { configsByTier?: WixLoyaltyRewardConfig[] };\n    percentage?: { configsByTier?: WixLoyaltyRewardConfig[] };\n    freeShipping?: { configsByTier?: WixLoyaltyRewardConfig[] };\n  };\n  active?: boolean;\n}"
+      },
+      {
+        "name": "WixLoyaltyAccount",
+        "kind": "interface",
+        "jsdoc": "/** The signed-in member's loyalty account (wix.loyalty.v1.account, `/my-account`). */",
+        "decl": "export interface WixLoyaltyAccount {\n  id?: string;\n  points?: { balance?: number; earned?: number; adjusted?: number; redeemed?: number; expired?: number };\n  /** The member's current tier; absent or without `id` while on the base tier. */\n  tier?: { id?: string; points?: number };\n  /** The member's own expiry — when and how many points lapse next. */\n  pointsExpiration?: { expirationDate?: string; expiringPointsAmount?: number };\n  rewardAvailable?: boolean;\n}"
+      },
+      {
+        "name": "WixLoyaltyTiersProgram",
+        "kind": "interface",
+        "jsdoc": "/** The tiers program: settings (ACTIVE | PAUSED, the base tier's definition) plus the custom tiers. */",
+        "decl": "export interface WixLoyaltyTiersProgram {\n  tiers?: WixLoyaltyTier[];\n  programSettings?: {\n    status?: string;\n    baseTierDefinition?: { name?: string; description?: string; icon?: unknown };\n    rollingWindow?: { durationInMonths?: number };\n  };\n}"
+      },
+      {
+        "name": "WixLoyaltyCoupon",
+        "kind": "interface",
+        "jsdoc": "/** A reward the member already claimed as a coupon (wix.loyalty.v1.coupon). */",
+        "decl": "export interface WixLoyaltyCoupon {\n  id?: string;\n  rewardName?: string;\n  /** ACTIVE | APPLIED | DELETED */\n  status?: string;\n  couponReference?: { couponId?: string; code?: string; deleted?: boolean };\n}"
       },
       {
         "name": "WixLoyaltyTier",
@@ -23480,6 +23504,22 @@
         "http": "GET /_api/loyalty-earning-rules/v1/earning-rules/rules",
         "scope": "visitor"
       },
+      {
+        "name": "getLoyaltyTiersProgram",
+        "kind": "function",
+        "jsdoc": "/** GET /loyalty-tiers/v1/tiers/program → { tiers, programSettings }. The custom tiers plus the\n *  settings that carry the BASE tier's name — the one a member with no `tier.id` is on.\n *\n * @scope visitor — readable without signing in. */",
+        "decl": "export function getLoyaltyTiersProgram(readOptions?: WixCallOptions): Promise<WixLoyaltyTiersProgram>;",
+        "http": "GET /loyalty-tiers/v1/tiers/program",
+        "scope": "visitor"
+      },
+      {
+        "name": "listMyLoyaltyCoupons",
+        "kind": "function",
+        "jsdoc": "/** GET /loyalty-coupons/v1/coupons/my-coupons → { loyaltyCoupons }. The member's claimed\n *  rewards; an ACTIVE, undeleted one still counts as a reward available to use.\n *\n * @scope member — requires a signed-in site member. */",
+        "decl": "export function listMyLoyaltyCoupons(readOptions?: WixCallOptions): Promise<{ loyaltyCoupons?: WixLoyaltyCoupon[] }>;",
+        "http": "GET /loyalty-coupons/v1/coupons/my-coupons",
+        "scope": "member"
+      },
       {
         "name": "LoyaltyOverview",
         "kind": "interface",
@@ -23514,7 +23554,7 @@
         "name": "getCurrentMemberLoyaltyAccount",
         "kind": "function",
         "jsdoc": "/** Read the authenticated member's own Loyalty account; no customer ID is accepted.\n * Source contract: loyalty-v1.getCurrentMemberAccount. Anonymous visitors are refused.\n * A signed-in customer recording is still required for migration acceptance.\n * @scope member\n */",
-        "decl": "export function getCurrentMemberLoyaltyAccount(readOptions?: WixCallOptions): Promise<{ account?: { points?: { balance?: number } } }>;",
+        "decl": "export function getCurrentMemberLoyaltyAccount(readOptions?: WixCallOptions): Promise<{ account?: WixLoyaltyAccount }>;",
         "http": "GET /loyalty-accounts/v1/accounts/my-account",
         "scope": "member"
       }

package/guides/templates.md

@@ -117,6 +117,8 @@ himi template screens                        # list the screens and their worker
 himi template screens --show himi_saved > saved.txt    # ONE screen's entry
 himi template screens --write himi_saved --from saved.txt   # put it back — re-parsed, refused if it breaks the file
 himi template screens --add himi_sellers --from sellers.txt --parent himi_branded_home   # a NEW screen, registered as linkable
+# --add/--write --from takes a ScreenDescriptor JSON object, { "<id>": <ScreenDescriptor> }, or the --show entry.
+# To add a screen, clone the closest one: --show it, change the id and content, then --add it.
 himi template sweep --set "Sample content=>Our latest" --dry-run   # copy inside string literals only
 himi template trim --from-spec --links drop --dry-run   # keep SPEC.md's Screen catalogue ids — read fromSpec.droppedPrimary first
 ```

package/guides/tier-5-add-a-screen.md

@@ -779,6 +779,20 @@ This works identically on web, iOS, and Android. (Regression-guarded by
 detail bundles for BOTH the primary `input.id` param and the back-compat
 `input.screenId` recovery.)
 
+**Prove the selected record, not just a successful build.** Each screen has its own worker,
+even when several screens name the same bundle and service. Setting a selected id in the list's
+service does not set the detail's state. Trace the tapped row id → navigation params →
+`himalaya.input` → the detail's initialized state. Route input is not automatically a loader
+argument, and `$input.id` is not a descriptor binding; read input in the worker as above.
+
+Add cold-entry journeys (`steps: []`) in `himi-test.json` for at least two distinct records per
+detail, asserting their requirement-derived title, metadata, notes and numeric values. Also
+assert missing/stale ids. See [cold-entry assertions](himi-test.md#typed-form-journeys). Do not
+manually dispatch `load` in these checks: that can make an uninitialized generated screen look
+correct. Then drive the actual row taps and back/return on each required surface, confirming
+that the second selection and a missing id show none of the first record's fields. Keep the
+source-nav and return evidence separate from the screen-local cold-entry assertions.
+
 **Alternative — a templated route that bakes a static `input`.** When the id space is
 enumerable, a `screens.templated` route can bake the id straight into the descriptor's
 **static `input`** instead of relying on a nav param — the `property_<id>` pattern. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1610.0",
+  "version": "0.1612.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": [
@@ -72,5 +72,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "fd34bb941dc2b1092069d5876a747cc0048164fc1b1ce148a32257b2"
+  "falconPackageHash": "ce8fd7a735a426892fa25365dcc0599b1c137be31ce634d59245ef55"
 }

package/templates/branded-lite/dev/index.ts

@@ -45241,6 +45241,90 @@ const SCREENS = runtimeSetting({
                                 }
                               }
                             },
+                            {
+                              "id": "himi_loyalty.member_tier",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Text",
+                                "props": {
+                                  "text": "$service:himiBrandedLoyalty.memberTier",
+                                  "style": "footnote",
+                                  "color": "textSecondary",
+                                  "maxLines": 1,
+                                  "collapseWhenEmpty": true
+                                }
+                              }
+                            },
+                            {
+                              "id": "himi_loyalty.member_expiry",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Text",
+                                "props": {
+                                  "text": "$service:himiBrandedLoyalty.memberExpiry",
+                                  "style": "caption",
+                                  "color": "textSecondary",
+                                  "collapseWhenEmpty": true
+                                }
+                              }
+                            },
+                            {
+                              "id": "himi_loyalty.member_expiry_urgent",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Text",
+                                "props": {
+                                  "text": "$service:himiBrandedLoyalty.memberExpiryUrgent",
+                                  "style": "caption",
+                                  "color": "danger",
+                                  "collapseWhenEmpty": true
+                                }
+                              }
+                            },
+                            {
+                              "id": "himi_loyalty.member_rewards",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "HStack",
+                                "props": {
+                                  "spacing": 4,
+                                  "alignment": "center",
+                                  "children": [
+                                    {
+                                      "id": "",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Icon",
+                                        "props": {
+                                          "name": "gift",
+                                          "size": 14,
+                                          "tint": "success"
+                                        }
+                                      },
+                                      "modifiers": {
+                                        "accessibilityRole": "decorative"
+                                      }
+                                    },
+                                    {
+                                      "id": "",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Text",
+                                        "props": {
+                                          "text": "$service:himiBrandedLoyalty.memberRewards",
+                                          "style": "footnote",
+                                          "color": "success",
+                                          "maxLines": 1
+                                        }
+                                      }
+                                    }
+                                  ]
+                                }
+                              },
+                              "modifiers": {
+                                "hiddenPath": "$service:himiBrandedLoyalty.hideMemberRewards"
+                              }
+                            },
                             {
                               "id": "",
                               "body": {