@wix/himalaya-cli 0.1548.0 → 0.1550.0

package/guides/component-reference.json

@@ -1263,7 +1263,7 @@
     "LogicBundleRef": "export interface LogicBundleRef {\n  url: string;\n  /** \"sha256-...\" SRI string. */\n  integrity: string;\n  contentType?: string;\n  /** SDK capability ids the bundle is permitted to import / invoke. */\n  declaredCapabilities: string[];\n  /** Bundle refuses to load on a binary older than this (semver). */\n  minBinaryVersion?: string;\n  /** Bundle's own semver. */\n  bundleVersion?: string;\n  /** Base64 detached publisher signature over the bundle bytes\n   *  (authenticity beyond SRI). Verified by a host-injected verifier when present;\n   *  unsigned bundles load as today. */\n  signature?: string;\n  /** The publisher key id a host pins, paired with `signature`. */\n  keyId?: string;\n  /** Ambient refresh (gap G2): the host invokes `action` (a `tier5.<svc>.<action>`\n   *  path) every `intervalMs` while the screen is visible — workers have no timer\n   *  of their own, so the host owns the cadence. */\n  refresh?: { intervalMs: number; action: string };\n}",
     "Modifiers": "export interface Modifiers {\n  padding?: EdgeInsets;\n  background?: TokenRef;\n  cornerRadius?: number;\n  /** Fixed intrinsic width (pt/dp/px). Honored by iOS (`FrameIfPresent`), Android\n   *  (frame) and web (`modifiers.ts`). With no `ScrollView` in the vocabulary and\n   *  regions clipped at `maxHeight`, `width`/`height`/`fillMaxWidth` are the main\n   *  sizing tools for embed/host content. */\n  width?: number;\n  /** Fixed intrinsic height (pt/dp/px). See `width`. */\n  height?: number;\n  /** Fill the available cross-axis width (keeps any fixed `height`). Mirrors\n   *  Compose `fillMaxWidth` / SwiftUI `.frame(maxWidth: .infinity)`. See `width`. */\n  fillMaxWidth?: boolean;\n  /** CAP the node's laid-out width at this many points. It CONSTRAINS, it\n   *  does not SET: a node narrower than the cap keeps its intrinsic width, so a\n   *  short chat bubble stays short while a long one stops at the cap — the\n   *  asymmetry `width` cannot express and `weight` cannot either (weights divide\n   *  the *available* space, so every child lands on the same fraction).\n   *  The cap covers the node's TOTAL width, padding + border included (CSS\n   *  `max-width` under `box-sizing: border-box`). `fillMaxWidth` grabs the axis but\n   *  THE CAP WINS — fill + cap is exactly `maxWidth` wide; a literal `width` larger\n   *  than the cap is clamped to it too. POINTS, not a fraction: a modifier is\n   *  resolved with no portable notion of \"the row\" on any renderer — compose a\n   *  percentage from a weighted sibling gap instead. `0`/absent = no cap. */\n  maxWidth?: number;\n  /** Flex weight along the parent stack's MAIN axis (HStack = width, VStack =\n   *  height). The stack measures its intrinsic (unweighted) children first, then\n   *  divides what is LEFT among the weighted ones in proportion to their weights:\n   *  two children at `1` split the leftover equally, `2` and `1` split it 2:1.\n   *  Absent (or <= 0) keeps the node at its intrinsic size. Use this — not\n   *  `fillMaxWidth` — when a node should claim the remaining space *beside* its\n   *  siblings; a full-bleed fill grabs the whole axis and starves them. Ignored\n   *  outside an HStack/VStack.\n   *  CAVEAT — row-sharing controls have NO intrinsic width to measure first: in an\n   *  HStack a `Button` and a `Toggle` are implicitly weighted, so they DIVIDE the\n   *  row with your weighted child instead of taking a width ahead of it —\n   *  `[VStack(weight:1), Button, Button]` is a three-way split, not \"the VStack gets\n   *  the remainder\". To opt a Button out on EVERY renderer set `fullWidth: false`\n   *  (an explicit flag wins in both directions; absent falls back to the style\n   *  default, which is \"share\" for every style but `tertiary`/`link`), or use\n   *  `iconOnly`. Otherwise give the actions their own row.\n   *  See `himi docs designing-himi-screens` §4. */\n  weight?: number;\n  /** RTL — pin the subtree's writing direction: `\"ltr\"` | `\"rtl\"` | `\"locale\"`\n   *  (inherit). The common RTL pattern is the inverse of `Text.textDirection`: pin a\n   *  container `ltr` (a logotype, an attachment-tile row, a composer button row)\n   *  inside an otherwise-RTL screen. Absent = inherit the ambient direction. #1060. */\n  layoutDirection?: \"ltr\" | \"rtl\" | \"locale\";\n  /** Absolute visual translation (pt/dp/px). Applied as the OUTERMOST transform so\n   *  it shifts the fully-styled node WITHOUT changing its layout footprint — lets a\n   *  ZStack place polar/absolute children (e.g. AgentOrbit). Negative allowed. */\n  offsetX?: number;\n  offsetY?: number;\n  onTap?: Action;\n  /** Double-tap gesture (e.g. Instagram double-tap-to-like). Distinct from onTap. */\n  onDoubleTap?: Action;\n  accessibilityLabel?: string;\n  hidden?: boolean;\n  /** Data-bound conditional visibility: a `\"$service:<svc>.<field>\"`\n   *  or `\"$item.<field>\"` sentinel resolving to a bool at render; when true the\n   *  subtree fully COLLAPSES (zero layout, like `hidden`), overriding the\n   *  literal `hidden`. */\n  hiddenPath?: string;\n  /** Long-press gesture modifier. */\n  onLongPress?: Action;\n  /** Fires once when the component first appears on screen. */\n  onAppear?: Action;\n  /** Scoped token overrides for the subtree. */\n  theme?: ThemeOverrides;\n  /** Names a token from the app's `shadows` registry. */\n  shadow?: TokenRef;\n  /** Names a token from the app's `gradients` registry (background fill). */\n  backgroundGradient?: TokenRef;\n  /** Value-driven gradient: a `$service:`/`$item.` path resolving to a gradient\n   *  TOKEN NAME used as the live background (e.g. weather sky day→night). */\n  backgroundGradientPath?: string;\n  /** Value-driven background COLOR: a `$service:`/`$item.` path resolving to a\n   *  color TOKEN NAME used as the live background. Honored on iOS + Android\n   *  (`BoundBackgroundIfPresent`); web render support is tracked in #1057. */\n  backgroundColorPath?: string;\n  /** Value-driven background IMAGE: a `$service:`/`$item.` path resolving to an\n   *  image URL used as the live background. Honored on iOS + Android; web render\n   *  support is tracked in #1057. */\n  backgroundImagePath?: string;\n  /** #1051 — MEASURE (publish): report this node's laid-out size into the renderer's\n   *  self-contained (worker-free) measure store under the named keys, so a SIBLING can\n   *  feed the number back into its own layout via a `$measure:<key>` binding. The SDUI\n   *  equivalent of SwiftUI `.onGeometryChange` / Compose `onGloballyPositioned`; the\n   *  canonical use is a pinned bottom bar whose measured height becomes a scroll view's\n   *  bottom inset (sticky-footer + scroll-inset, unrepresentable before — #1051). */\n  onMeasure?: Measure;\n  /** #1051 — bound height: a `\"$measure:<key>\"` (measure store) or\n   *  `\"$service:<svc>.<field>\"` / `\"$item.<field>\"` (worker/row state) sentinel resolving\n   *  to a NUMBER at render. Wins over the literal `height`. String path only, so a\n   *  binding can never blank the node (never overload the numeric `height`). */\n  heightPath?: string;\n  /** #1051 — bound width. See `heightPath`. Wins over the literal `width`. */\n  widthPath?: string;\n  /** #1051 — bound TOP inset (the header-height → top-inset idiom). A `$measure:`/\n   *  `$service:`/`$item.` sentinel resolving to a number; added as top padding. */\n  paddingTopPath?: string;\n  /** #1051 — bound BOTTOM inset (the sticky-footer-height → bottom-inset idiom). A\n   *  `$measure:`/`$service:`/`$item.` sentinel resolving to a number; added as bottom\n   *  padding so the last scroll row clears a pinned bottom bar. */\n  paddingBottomPath?: string;\n  /** #1053 — INLINE gradient background paint. Distinct from `backgroundGradient`\n   *  (which names a `gradients` registry token an embed host can't register): this\n   *  carries its stops/colours in the descriptor, so it works anywhere. Painted as\n   *  a surface (behind children), below `material`/`backgroundGradient` if those are\n   *  also set. */\n  gradient?: Gradient;\n  /** #1053 — gradient ALPHA MASK: the node shows through where the gradient is\n   *  opaque and fades where it's transparent (a transparent-token stop = fully\n   *  clear). The material-under-gradient-scrim / scroll-fade-out idiom. Mirrors iOS\n   *  `.mask()`, Android `BlendMode.DstIn`, web `mask-image`. */\n  mask?: Gradient;\n  /** Inline border/stroke. */\n  border?: Border;\n  /** Subtree alpha 0.0–1.0; absent = opaque. */\n  opacity?: number;\n  /** #433 — constrain the subtree to a width:height ratio (e.g. `1` = square,\n   *  `1.777` = 16:9). Width-driven: the height derives from the resolved width.\n   *  Lets a data-bound Grid cell / photo tile hold its shape at any width. */\n  aspectRatio?: number;\n  /** Names a token from the app's `motions` registry; the subtree\n   *  fades + slides up on first appearance. */\n  appear?: TokenRef;\n  /** Surface material token (flat/glass/frosted). */\n  material?: TokenRef;\n  /** Per-node construction-language override. */\n  variant?: string;\n  /** Per-node density / motion override. */\n  density?: string;\n  motion?: string;\n  /** Motion grammar (Batch 1) — press/tap feedback style\n   *  (auto|none|scale|highlight|scaleHighlight|lift); timing comes from `motion`.\n   *  Applied only when the node is interactive. Unknown degrades to `auto`. */\n  pressFeedback?: string;\n  /** Motion grammar (Batch 1) — press-coupled haptic\n   *  (none|selection|light|medium|heavy|success|warning|error); fires with onTap.\n   *  Default none (opt-in). Web is a no-op. */\n  haptic?: string;\n  /** Motion grammar (Batch 1) — animate this container's size changes instead of\n   *  snapping (iOS `.animation(value:)`, Android `animateContentSize`, web height\n   *  transition). Curve from the active `motion` personality. */\n  animateContentSize?: boolean;\n  /** Motion grammar (Batch 1) — enter/exit transition; supersedes `appear` when\n   *  both are present. */\n  transition?: Transition;\n  /** Motion grammar (Batch 2, scroll-driven) — defer the `transition` enter until\n   *  the node first crosses into the scroll viewport (reveal-on-scroll). Gated by\n   *  reduced motion (shown immediately when reduced). */\n  revealOnScroll?: boolean;\n  /** Motion grammar (Batch 2, scroll-driven) — parallax factor: the node drifts\n   *  vertically at this fraction of the scroll delta as it moves through the\n   *  viewport. Gated by reduced motion. Generalizes CollapsingHeader parallaxFactor. */\n  parallax?: number;\n  /** Motion grammar (Batch 4, rich visual) — when a backgroundGradient is present,\n   *  continuously drift/rotate it (animated gradient). Gated by reduced motion. */\n  animatedGradient?: boolean;\n  /** Motion grammar (Batch 3, hero/nav) — shared-element key: a matching\n   *  transitionId on the source + destination screen morphs that element across\n   *  navigation (web View Transitions / iOS matchedTransitionSource / Android\n   *  SharedTransitionLayout). Gated by reduced motion. */\n  transitionId?: string;\n  /** Motion grammar (Batch 4, rich visual) — render the backgroundGradient as a\n   *  mesh (overlapping multi-point blend) rather than a linear sweep; combine with\n   *  animatedGradient to drift it. */\n  meshGradient?: boolean;\n  /** Motion grammar (Batch 4, celebration) — burst a one-shot confetti overlay\n   *  within the node on appear. Gated by reduced motion. */\n  confetti?: boolean;\n  /** Motion grammar (Batch 2, scroll-driven) — pin this node to the top of its\n   *  scroll container (sticky section header). Functional positioning; not gated\n   *  by reduced motion. */\n  sticky?: boolean;\n  /** Motion grammar (Batch 2, scroll-driven) — turn this thin node into a\n   *  reading-progress bar that fills left→right with scroll (scaleX). web reads\n   *  window scroll; native reads the host scroll fraction. Functional. */\n  scrollProgress?: boolean;\n  /** Motion grammar (Batch 4, rich vector) — a named built-in vector animation\n   *  (\"loader\" | \"success\" | \"pulse\"), dependency-free. Gated by reduced motion.\n   *  Arbitrary Lottie/Rive JSON is the lib-backed superset follow-up. */\n  vectorAnim?: string;\n  /** Motion grammar (Batch 1, choreography) — delay this node's ENTER transition\n   *  by N ms so a screen can SEQUENCE its entrance beyond list stagger (\"title\n   *  fades, subtitle slides in 100ms later\"). Adds to any list `staggerMs`. Gated\n   *  by reduced motion. 0/absent = no extra delay. */\n  enterDelayMs?: number;\n  /** Motion grammar (Phase-3, per-node MotionSpec) — overrides the PRESS-feedback\n   *  curve with a `motions`-registry token, mirroring `Transition.motion` for the\n   *  enter curve. Absent → press uses the global `motion` personality. */\n  pressMotion?: TokenRef;\n  /** Motion grammar (Phase-3, gesture-driven) — finger-tracked drag-to-dismiss; past\n   *  threshold along `direction` it animates off and fires `action`, else springs back. */\n  swipeDismiss?: SwipeDismiss;\n  /** Motion grammar (Phase-4, reduced-motion) — per-node escape from the reduced-motion\n   *  gate. Default true (respect). false = \"must move anyway\" (transition/press animate\n   *  even when reduced motion is on). */\n  respectReducedMotion?: boolean;\n  /** #1052 — uniform scale (1 = no change). */\n  scale?: number;\n  /** #1052 — rotation in DEGREES. */\n  rotation?: number;\n  /** #1052 — stacking order within a ZStack/overlay. */\n  zIndex?: number;\n  /** #1052 — gaussian blur radius (pt/dp/px). */\n  blur?: number;\n  /** #1052 — `false` = decorative (ignores taps, unlike `hidden` which stays hit-testable);\n   *  `true` = force hit-testable (a clear tap target). */\n  hitTestable?: boolean;\n  /** #1052 — explicit drop shadow (colour + radius + offset), for upward / multi-layer\n   *  shadows the `shadow` token can't express. */\n  boxShadow?: Shadow;\n  /** The role assistive technology should announce. Absent = the\n   *  renderer INFERS it from the component type, so an author never restates the\n   *  obvious. `\"decorative\"` is node-local: the node itself stops being an\n   *  accessibility element (no role, not a stop) while its children stay\n   *  traversable — the ARIA `role=\"presentation\"` semantic. To remove the subtree\n   *  too, use `accessibilityHidden`. */\n  accessibilityRole?: AccessibilityRole;\n  /** The supplementary \"what happens if I act\" phrase\n   *  (iOS `accessibilityHint`, Android `onClickLabel`, ARIA `aria-describedby`).\n   *  Never a substitute for `accessibilityLabel`: AT may not speak a hint at all. */\n  accessibilityHint?: string;\n  /** Remove this node AND its subtree from the accessibility tree.\n   *  Distinct from `hidden` (which removes it visually too) and from the\n   *  `\"decorative\"` role (node-local; children stay reachable). */\n  accessibilityHidden?: boolean;\n  /** Mark the node as a heading at level 1–6, for rotor / heading\n   *  navigation. Implies the `\"heading\"` role when `accessibilityRole` is absent.\n   *  The LEVEL reaches iOS and web only: Android (Compose `heading()`) and React Native\n   *  (`accessibilityRole: \"header\"`) have no level primitive and mark a plain heading. */\n  headingLevel?: number;\n  /** An explicit SPOKEN value where the visual and spoken values\n   *  differ (a rating \"3 of 5\", a gauge \"72 percent\"). Where the value is derivable\n   *  from a prop the renderer computes it and this override is unnecessary. */\n  accessibilityValue?: string;\n  /** Additive state that a single role cannot carry. A node may\n   *  hold several. */\n  accessibilityTraits?: AccessibilityTrait[];\n  /** Explicit traversal index within the nearest focus group. Absent ⇒\n   *  the arm's visual / DOM order. The lower index is reached FIRST, which is why iOS\n   *  (whose `accessibilitySortPriority` is descending) negates it. */\n  focusOrder?: number;\n  /** This node's subtree is ONE traversal scope: children are ordered\n   *  relative to each other, then the group takes its parent's slot (iOS\n   *  `shouldGroupAccessibilityChildren`, Android `isTraversalGroup`, ARIA grouping). */\n  focusGroup?: boolean;\n  /** AT / keyboard focus lands here when the screen or a newly presented\n   *  modal appears. At most one per focus scope. */\n  initialFocus?: boolean;\n  /** A general live-region announcement, on any node and any transition.\n   *  The generalization of `FragmentSlotCase.accessibilityAnnouncement`, which only ever\n   *  fired on a fragment-slot case swap. */\n  announce?: LiveRegion;\n  /** Clip ANY node (content + surface) to a shape:\n   *  \"rectangle\" | \"roundedRectangle\" | \"capsule\" | \"circle\" | \"ellipse\". Unknown/empty =\n   *  no shape clip (`cornerRadius` keeps its meaning). When set it replaces the\n   *  corner-radius-only clip; a \"roundedRectangle\" uses `clipCornerRadii`, else `cornerRadius`. */\n  clipShape?: string;\n  /** Uneven corner radii for `clipShape: \"roundedRectangle\"`. */\n  clipCornerRadii?: CornerRadii;\n  /** A recurring, finite, transform-only motion on a decorative node: a\n   *  living character's idle `hop`, a `blink`, a working `breathe`. Never changes the\n   *  node's layout footprint. Stopped by reduced motion unless `respectReducedMotion`\n   *  is false. */\n  ambientMotion?: AmbientMotion;\n}",
     "TokenRef": "export interface TokenRef {\n  token: TokenName;\n}",
-    "Action": "export interface Action {\n  actionId: string;\n  /** Backwards-compatible string-only params. Prefer `args` for typed payloads. */\n  params?: Record<string, string>;\n  /** Typed action args; nested objects/arrays preserved end-to-end. With `presentation: \"sheet\"`,\n   *  `args.detents` (fractions of the height in (0, 1], e.g. `[0.5, 1]`) sizes the presented\n   *  sheet; absent ⇒ the default sheet. Applies on iOS, Android and web; a macOS (and tvOS)\n   *  screen sheet is a window-modal panel sized to its content, so there it is accepted and\n   *  ignored, as for the BottomSheet component. */\n  args?: Record<string, Value>;\n  /** Navigation hint for the router; ignored for non-nav actions. */\n  presentation?: Presentation;\n}",
+    "Action": "export interface Action {\n  actionId: string;\n  /** : applied before the worker action; its returned legacy _nav is ignored. */\n  nav?: ActionNavigation;\n  /** Backwards-compatible string-only params. Prefer `args` for typed payloads. */\n  params?: Record<string, string>;\n  /** Typed action args; nested objects/arrays preserved end-to-end. With `presentation: \"sheet\"`,\n   *  `args.detents` (fractions of the height in (0, 1], e.g. `[0.5, 1]`) sizes the presented\n   *  sheet; absent ⇒ the default sheet. Applies on iOS, Android and web; a macOS (and tvOS)\n   *  screen sheet is a window-modal panel sized to its content, so there it is accepted and\n   *  ignored, as for the BottomSheet component. */\n  args?: Record<string, Value>;\n  /** Navigation hint for the router; ignored for non-nav actions. */\n  presentation?: Presentation;\n}",
     "Presentation": "export type Presentation =\n  | \"push\"\n  | \"sheet\"\n  | \"replace\"\n  | \"dismiss\"\n  | \"back\"\n  | \"full_screen\"\n  | \"alert\"\n  | \"snackbar\";",
     "FilterChip": "export interface FilterChip {\n  id: string;\n  label: string;\n  leadingIcon?: IconRef;\n  count?: number;\n}",
     "TabItem": "export interface TabItem {\n  id: string;\n  label: string;\n  badge?: string;\n}",

package/guides/component-reference.md

@@ -2828,6 +2828,8 @@ over the string-only `params`; `presentation` is the router hint for nav actions
 ```ts
 export interface Action {
   actionId: string;
+  /** : applied before the worker action; its returned legacy _nav is ignored. */
+  nav?: ActionNavigation;
   /** Backwards-compatible string-only params. Prefer `args` for typed payloads. */
   params?: Record<string, string>;
   /** Typed action args; nested objects/arrays preserved end-to-end. With `presentation: "sheet"`,

package/guides/iap-products.md

@@ -626,9 +626,12 @@ future importer must authenticate ownership and re-read Apple before activating
 - **Handle the business side.** Paid Apps agreement, banking and tax information go
   through the owner's App Store Connect account.
 - **Submit for review.** Your first in-app purchases must be submitted together with an
-  app version: attach them to the version in App Store Connect before you submit it (see
-  `/submit-ios-app`). Later ones can be submitted on their own. This command never
-  submits, and never makes a product available for sale.
+  app version. Products registered with the IAP Catalog are: the iOS release
+  (`/submit-ios-app`) hands the version to Catalog, which submits it with its pending
+  in-app purchases, once the app's store config names its Catalog registration. Otherwise,
+  attach them to the version in App Store Connect before you submit it. Later ones can be
+  submitted on their own. This command never submits, and never makes a product available
+  for sale.
 - **Allow for Sandbox delay.** Product changes can take a while to appear in Sandbox
   purchase testing. Sandbox is for purchases, not a separate product catalogue:
   these API calls change the real product records.

package/guides/qa-builds.md

@@ -1133,6 +1133,37 @@ himi dist --app <app> --platform android --aab --wait --target bo
   check-only mode, so it locks nothing. It names no release, so it cannot give
   `409 release_predates_store_builds`; a draft the editor just built is on a current commit. It never
   falls back to the locking call.
+- **A Containers app's TestFlight build is an App Store build.** For an app bound to a Wix site,
+  `--platform ios --destination testflight --version <x.y.z>` with no `--signing` builds the app for
+  the owner's own App Store account: signed with the owner's certificate, under the bundle id saved
+  in mobile-apps-containers-builder, and uploaded to the owner's TestFlight with the owner's App
+  Store Connect key. The checks run last before the build starts: the caller owns the app's site
+  (send your Wix login, as for a bundle), the app holds its site's store app, the release's commit
+  can make one (`appStoreBuild` in the signing marker), `ValidateStoreBuild`'s check-only mode finds a
+  saved bundle id and an eligible plan (so an ineligible site never reaches Apple), then
+  `PrepareAppleCertificates` registers the bundle id in the owner's Apple account and answers the
+  certificate, profile and key, and only then `ValidateStoreBuild` locks the bundle id (so a bundle id
+  Apple refuses can still change), and only while it is still the prepared one (`expected_store_id`:
+  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).
+  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`,
+  `apple_private_key_invalid`, `apple_credentials_rejected`, `apple_credentials_access_denied`,
+  `apple_agreement_not_accepted`, `bundle_id_not_available`, `apple_certificate_limit_reached`,
+  `app_store_app_missing`, `premium_plan_required` and `store_app_concurrent_update` 409,
+  `store_builds_unconfigured` 501 (also until the generated client carries
+  `PrepareAppleCertificates`, and where customer App Store upload is off), `app_store_signing_invalid`
+  502 (the prepared files failed Himalaya's checks, the check's code in `reason`: a fix on Wix's
+  side, not a retry), `store_builds_unavailable` 503. A named `--signing byo` keeps the
+  customer-signed path above, from the site's legacy BuildSecrets.
 
 **Why the Wix production key, and only for the bundle.** There are two Android keys: the committed
 QA keystore and the Wix production key (WixOne). WixOne is the Play **upload** key every Branded

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

@@ -764,6 +764,59 @@ route a worker's `himi.open` dispatch on all three hosts, but older iOS and Andr
 send it to the native action registry, which has no `himi.open` handler, so it does nothing
 there; `_nav` works on every binary.
 
+#### Navigate before the worker answers: `nav` on the action
+
+When a tap's destination does not depend on what the reducer does — the reducer only records
+a selection or a recent item, or clears a message — declare the destination on the descriptor
+action, beside the worker action it already fires:
+
+```ts
+button({ title: "Edit", action: {
+  actionId: "tier5.addresses.edit", params: { id: "$item.id" },
+  nav: { screenId: "address" },              // the editor opens at once, with { id }
+} })
+button({ title: "Add", action: {
+  actionId: "tier5.addresses.add",
+  nav: { screenId: "address", args: {} },    // args replaces params: send the editor nothing
+} })
+```
+
+The host opens the screen immediately, then runs `tier5.addresses.edit` with its own params.
+It ignores the `_nav` that action returns. `nav` takes exactly what `_nav` takes (the table
+above): a screen with an optional `presentation`, `{ presentation: "back" }` or `"dismiss"`, or
+`{ tab, reset?: true, screenId?, args? }`. `nav.args`, when present, is the destination's whole
+input (strings only) instead of the action's `params`; a tab switch with nothing to push and
+back/dismiss take none of them.
+
+```ts
+// switch to Orders now; the worker still records which filter was tapped
+button({ title: "All orders", action: { actionId: "tier5.home.viewOrders", params: { filter: "open" }, nav: { tab: "orders" } } })
+```
+
+Keep the reducer returning the same `_nav`: a binary that predates `nav` ignores the
+declaration and still navigates through it. `himi validate` warns when the two name
+different screens. Leave `nav` off when the logic decides where to go or whether to go at
+all — after a save whose result names the destination, a check that can fail, a branch on
+what the reducer computed — and do not
+`dispatch("himi.open")` from a reducer whose action declares `nav`. An invalid declaration (an
+unresolved `$item.` value, an unknown presentation) is ignored and the action behaves as if
+`nav` were absent.
+
+A destination the reducer only reads from state the screen already shows can still be declared:
+`$service:` strings in `nav.screenId`, `nav.tab` and `nav.args` resolve when the tap happens,
+against the screen's worker, or against the saved state a cold screen painted from. Expose the
+value in the service's state first:
+
+```ts
+// The agenda sheet's "View class": its state carries the sheet session's service id.
+{ actionId: "tier5.himiBrandedAgenda.viewSession",
+  nav: { screenId: "himi_service", args: { id: "$service:himiBrandedAgenda.sheetServiceId" } } }
+```
+
+It is all or nothing: a binding that is missing, null, an empty string or not a scalar leaves
+the whole declaration unused, and the tap waits for the reducer's `_nav` as before.
+`presentation` and `reset` cannot be bound.
+
 #### Back, dismiss, and tabs
 
 A Close or Done button is a **descriptor** action with a `presentation` verb —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1548.0",
+  "version": "0.1550.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": "2e7918679db2cb4ae797f6d4886f5dec2f7f903c4e1f7e2ed118e37a"
+  "falconPackageHash": "9a87baae6e742bf463b9aca4b2c132475e6cef51f18e15512e545aab"
 }

package/templates/beauty-salon/dev/index.ts

@@ -16881,6 +16881,9 @@ const SCREENS = runtimeSetting({
                                             "actionId": "tier5.himiBrandedAddresses.edit",
                                             "params": {
                                               "id": "$item.id"
+                                            },
+                                            "nav": {
+                                              "screenId": "himi_address"
                                             }
                                           }
                                         }
@@ -17117,7 +17120,11 @@ const SCREENS = runtimeSetting({
                   "fullWidth": true,
                   "leadingIcon": "plus",
                   "action": {
-                    "actionId": "tier5.himiBrandedAddresses.add"
+                    "actionId": "tier5.himiBrandedAddresses.add",
+                    "nav": {
+                      "screenId": "himi_address",
+                      "args": {}
+                    }
                   }
                 }
               },
@@ -24430,7 +24437,13 @@ const SCREENS = runtimeSetting({
                                         "fullWidth": true,
                                         "disabledPath": "$service:himiBrandedAgenda.sheetBusy",
                                         "action": {
-                                          "actionId": "tier5.himiBrandedAgenda.viewSession"
+                                          "actionId": "tier5.himiBrandedAgenda.viewSession",
+                                          "nav": {
+                                            "screenId": "himi_service",
+                                            "args": {
+                                              "id": "$service:himiBrandedAgenda.sheetServiceId"
+                                            }
+                                          }
                                         }
                                       }
                                     }

package/templates/beauty-salon/tier5-src/himi-branded-lite-agenda/index.ts

@@ -136,6 +136,8 @@ interface S extends LoadFlags {
   sheetHideCancel: boolean;
   sheetHideLeave: boolean;
   sheetBusy: boolean;
+  /** The sheet session's service: View class reads its declared route (`nav`) from it. "" with no sheet. */
+  sheetServiceId: string;
 }
 
 const flag = (on: boolean): string => (on ? "true" : "");
@@ -573,6 +575,7 @@ function derive(s: S): S {
     sheetHideCancel: sheetPlace !== "booked",
     sheetHideLeave: sheetPlace !== "waitlisted",
     sheetBusy: busy || calendarBusy,
+    sheetServiceId: sheet?.serviceId ?? "",
   };
 }
 
@@ -698,7 +701,7 @@ function initial(): S {
     ...LOADING, firstWeekday: 0, today: "", selectedDate: "", rangeStart: "", rangeEnd: "",
     decorations: [], events: [], scrollTo: "", signedIn: false, updateRequired: false, updateMessage: "", listHidden: true,
     ...emptyFlags(false, false), resultOpen: false, resultOpenB: false, resultText: "", resultOk: false, resultInfo: false,
-    sheetOpen: false, sheetTitle: "", sheetWhen: "", sheetMeta: "", sheetHideCalendar: true, sheetHideCancel: true, sheetHideLeave: true, sheetBusy: false,
+    sheetOpen: false, sheetTitle: "", sheetWhen: "", sheetMeta: "", sheetHideCalendar: true, sheetHideCancel: true, sheetHideLeave: true, sheetBusy: false, sheetServiceId: "",
   };
 }
 

package/templates/beauty-salon-owner/dev/index.ts

@@ -52246,6 +52246,14 @@ const SCREENS = runtimeSetting({
                                                                     "actionId": "tier5.himiOwnerLiteManage.create",
                                                                     "params": {
                                                                       "id": "$item.id"
+                                                                    },
+                                                                    "nav": {
+                                                                      "screenId": "$item.createScreenId",
+                                                                      "args": {
+                                                                        "title": "$item.createNavTitle",
+                                                                        "subtitle": "$item.createNavSubtitle",
+                                                                        "search": "$item.createNavSearch"
+                                                                      }
                                                                     }
                                                                   },
                                                                   "accessibilityLabel": "$item.createLabel",
@@ -52307,6 +52315,14 @@ const SCREENS = runtimeSetting({
                                                     "actionId": "tier5.himiOwnerLiteManage.openArea",
                                                     "params": {
                                                       "id": "$item.id"
+                                                    },
+                                                    "nav": {
+                                                      "screenId": "$item.screenId",
+                                                      "args": {
+                                                        "title": "$item.navTitle",
+                                                        "subtitle": "$item.navSubtitle",
+                                                        "search": "$item.navSearch"
+                                                      }
                                                     }
                                                   },
                                                   "accessibilityLabel": "$item.title",
@@ -52552,6 +52568,14 @@ const SCREENS = runtimeSetting({
                                                                             "actionId": "tier5.himiOwnerLiteManage.create",
                                                                             "params": {
                                                                               "id": "$item.id"
+                                                                            },
+                                                                            "nav": {
+                                                                              "screenId": "$item.createScreenId",
+                                                                              "args": {
+                                                                                "title": "$item.createNavTitle",
+                                                                                "subtitle": "$item.createNavSubtitle",
+                                                                                "search": "$item.createNavSearch"
+                                                                              }
                                                                             }
                                                                           },
                                                                           "accessibilityLabel": "$item.createLabel",
@@ -52613,6 +52637,14 @@ const SCREENS = runtimeSetting({
                                                             "actionId": "tier5.himiOwnerLiteManage.openArea",
                                                             "params": {
                                                               "id": "$item.id"
+                                                            },
+                                                            "nav": {
+                                                              "screenId": "$item.screenId",
+                                                              "args": {
+                                                                "title": "$item.navTitle",
+                                                                "subtitle": "$item.navSubtitle",
+                                                                "search": "$item.navSearch"
+                                                              }
                                                             }
                                                           },
                                                           "accessibilityLabel": "$item.title",
@@ -65956,7 +65988,10 @@ const SCREENS = runtimeSetting({
                                             "title": "Back to Inbox",
                                             "style": "secondary",
                                             "action": {
-                                              "actionId": "tier5.ownerLiteInboxThread.back"
+                                              "actionId": "tier5.ownerLiteInboxThread.back",
+                                              "nav": {
+                                                "presentation": "back"
+                                              }
                                             }
                                           }
                                         }

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-manage/logic.ts

@@ -56,6 +56,13 @@ export interface ManageArea {
   navigation?: ManageNavigation;
   /** The same for its create screen. */
   createNavigation?: ManageNavigation;
+  /** [navigation] flattened for the card's declared route (`$item.` reads flat fields only); "" when absent. */
+  navTitle?: string;
+  navSubtitle?: string;
+  navSearch?: string;
+  createNavTitle?: string;
+  createNavSubtitle?: string;
+  createNavSearch?: string;
 }
 
 /** A page's navigation as the build declares it: its title and subtitle, and where its search goes (none without one). */
@@ -118,6 +125,8 @@ export function parseAreas(value: unknown): ManageArea[] {
     const area = Object.fromEntries(required) as Record<string, string>;
     const createScreenId = clean(raw.createScreenId);
     const createLabel = clean(raw.createLabel);
+    const navigation = parseNavigation(raw.navigation);
+    const createNavigation = createScreenId && createLabel ? parseNavigation(raw.createNavigation) : undefined;
     // Creation is only an in-app route when both fields are present. A lone
     // label must not produce a promising but inert action.
     return [{
@@ -126,8 +135,11 @@ export function parseAreas(value: unknown): ManageArea[] {
       hideCreate: !(createScreenId && createLabel),
       hideHandoff: !DASHBOARD_PATHS[area.id],
       handoffLabel: clean(raw.handoffLabel) || `Open in Wix: ${area.title}`,
-      ...(parseNavigation(raw.navigation) ? { navigation: parseNavigation(raw.navigation) } : {}),
-      ...(createScreenId && createLabel && parseNavigation(raw.createNavigation) ? { createNavigation: parseNavigation(raw.createNavigation) } : {}),
+      ...(navigation ? { navigation } : {}),
+      ...(createNavigation ? { createNavigation } : {}),
+      navTitle: navigation?.title ?? "", navSubtitle: navigation?.subtitle ?? "", navSearch: navigation?.search ?? "",
+      createNavTitle: createNavigation?.title ?? "", createNavSubtitle: createNavigation?.subtitle ?? "",
+      createNavSearch: createNavigation?.search ?? "",
       metricText: "—",
       statusText: "",
       unavailable: false,

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

@@ -18197,6 +18197,9 @@ const SCREENS = runtimeSetting({
                                             "actionId": "tier5.himiBrandedAddresses.edit",
                                             "params": {
                                               "id": "$item.id"
+                                            },
+                                            "nav": {
+                                              "screenId": "himi_address"
                                             }
                                           }
                                         }
@@ -18433,7 +18436,11 @@ const SCREENS = runtimeSetting({
                   "fullWidth": true,
                   "leadingIcon": "plus",
                   "action": {
-                    "actionId": "tier5.himiBrandedAddresses.add"
+                    "actionId": "tier5.himiBrandedAddresses.add",
+                    "nav": {
+                      "screenId": "himi_address",
+                      "args": {}
+                    }
                   }
                 }
               },
@@ -25818,7 +25825,13 @@ const SCREENS = runtimeSetting({
                                         "fullWidth": true,
                                         "disabledPath": "$service:himiBrandedAgenda.sheetBusy",
                                         "action": {
-                                          "actionId": "tier5.himiBrandedAgenda.viewSession"
+                                          "actionId": "tier5.himiBrandedAgenda.viewSession",
+                                          "nav": {
+                                            "screenId": "himi_service",
+                                            "args": {
+                                              "id": "$service:himiBrandedAgenda.sheetServiceId"
+                                            }
+                                          }
                                         }
                                       }
                                     }

package/templates/branded-lite/tier5-src/himi-branded-lite-agenda/index.ts

@@ -136,6 +136,8 @@ interface S extends LoadFlags {
   sheetHideCancel: boolean;
   sheetHideLeave: boolean;
   sheetBusy: boolean;
+  /** The sheet session's service: View class reads its declared route (`nav`) from it. "" with no sheet. */
+  sheetServiceId: string;
 }
 
 const flag = (on: boolean): string => (on ? "true" : "");
@@ -573,6 +575,7 @@ function derive(s: S): S {
     sheetHideCancel: sheetPlace !== "booked",
     sheetHideLeave: sheetPlace !== "waitlisted",
     sheetBusy: busy || calendarBusy,
+    sheetServiceId: sheet?.serviceId ?? "",
   };
 }
 
@@ -698,7 +701,7 @@ function initial(): S {
     ...LOADING, firstWeekday: 0, today: "", selectedDate: "", rangeStart: "", rangeEnd: "",
     decorations: [], events: [], scrollTo: "", signedIn: false, updateRequired: false, updateMessage: "", listHidden: true,
     ...emptyFlags(false, false), resultOpen: false, resultOpenB: false, resultText: "", resultOk: false, resultInfo: false,
-    sheetOpen: false, sheetTitle: "", sheetWhen: "", sheetMeta: "", sheetHideCalendar: true, sheetHideCancel: true, sheetHideLeave: true, sheetBusy: false,
+    sheetOpen: false, sheetTitle: "", sheetWhen: "", sheetMeta: "", sheetHideCalendar: true, sheetHideCancel: true, sheetHideLeave: true, sheetBusy: false, sheetServiceId: "",
   };
 }
 

package/templates/community-club-owner/dev/index.ts

@@ -52246,6 +52246,14 @@ const SCREENS = runtimeSetting({
                                                                     "actionId": "tier5.himiOwnerLiteManage.create",
                                                                     "params": {
                                                                       "id": "$item.id"
+                                                                    },
+                                                                    "nav": {
+                                                                      "screenId": "$item.createScreenId",
+                                                                      "args": {
+                                                                        "title": "$item.createNavTitle",
+                                                                        "subtitle": "$item.createNavSubtitle",
+                                                                        "search": "$item.createNavSearch"
+                                                                      }
                                                                     }
                                                                   },
                                                                   "accessibilityLabel": "$item.createLabel",
@@ -52307,6 +52315,14 @@ const SCREENS = runtimeSetting({
                                                     "actionId": "tier5.himiOwnerLiteManage.openArea",
                                                     "params": {
                                                       "id": "$item.id"
+                                                    },
+                                                    "nav": {
+                                                      "screenId": "$item.screenId",
+                                                      "args": {
+                                                        "title": "$item.navTitle",
+                                                        "subtitle": "$item.navSubtitle",
+                                                        "search": "$item.navSearch"
+                                                      }
                                                     }
                                                   },
                                                   "accessibilityLabel": "$item.title",
@@ -52552,6 +52568,14 @@ const SCREENS = runtimeSetting({
                                                                             "actionId": "tier5.himiOwnerLiteManage.create",
                                                                             "params": {
                                                                               "id": "$item.id"
+                                                                            },
+                                                                            "nav": {
+                                                                              "screenId": "$item.createScreenId",
+                                                                              "args": {
+                                                                                "title": "$item.createNavTitle",
+                                                                                "subtitle": "$item.createNavSubtitle",
+                                                                                "search": "$item.createNavSearch"
+                                                                              }
                                                                             }
                                                                           },
                                                                           "accessibilityLabel": "$item.createLabel",
@@ -52613,6 +52637,14 @@ const SCREENS = runtimeSetting({
                                                             "actionId": "tier5.himiOwnerLiteManage.openArea",
                                                             "params": {
                                                               "id": "$item.id"
+                                                            },
+                                                            "nav": {
+                                                              "screenId": "$item.screenId",
+                                                              "args": {
+                                                                "title": "$item.navTitle",
+                                                                "subtitle": "$item.navSubtitle",
+                                                                "search": "$item.navSearch"
+                                                              }
                                                             }
                                                           },
                                                           "accessibilityLabel": "$item.title",
@@ -65956,7 +65988,10 @@ const SCREENS = runtimeSetting({
                                             "title": "Back to Inbox",
                                             "style": "secondary",
                                             "action": {
-                                              "actionId": "tier5.ownerLiteInboxThread.back"
+                                              "actionId": "tier5.ownerLiteInboxThread.back",
+                                              "nav": {
+                                                "presentation": "back"
+                                              }
                                             }
                                           }
                                         }

package/templates/community-club-owner/tier5-src/himi-owner-lite-manage/logic.ts

@@ -56,6 +56,13 @@ export interface ManageArea {
   navigation?: ManageNavigation;
   /** The same for its create screen. */
   createNavigation?: ManageNavigation;
+  /** [navigation] flattened for the card's declared route (`$item.` reads flat fields only); "" when absent. */
+  navTitle?: string;
+  navSubtitle?: string;
+  navSearch?: string;
+  createNavTitle?: string;
+  createNavSubtitle?: string;
+  createNavSearch?: string;
 }
 
 /** A page's navigation as the build declares it: its title and subtitle, and where its search goes (none without one). */
@@ -118,6 +125,8 @@ export function parseAreas(value: unknown): ManageArea[] {
     const area = Object.fromEntries(required) as Record<string, string>;
     const createScreenId = clean(raw.createScreenId);
     const createLabel = clean(raw.createLabel);
+    const navigation = parseNavigation(raw.navigation);
+    const createNavigation = createScreenId && createLabel ? parseNavigation(raw.createNavigation) : undefined;
     // Creation is only an in-app route when both fields are present. A lone
     // label must not produce a promising but inert action.
     return [{
@@ -126,8 +135,11 @@ export function parseAreas(value: unknown): ManageArea[] {
       hideCreate: !(createScreenId && createLabel),
       hideHandoff: !DASHBOARD_PATHS[area.id],
       handoffLabel: clean(raw.handoffLabel) || `Open in Wix: ${area.title}`,
-      ...(parseNavigation(raw.navigation) ? { navigation: parseNavigation(raw.navigation) } : {}),
-      ...(createScreenId && createLabel && parseNavigation(raw.createNavigation) ? { createNavigation: parseNavigation(raw.createNavigation) } : {}),
+      ...(navigation ? { navigation } : {}),
+      ...(createNavigation ? { createNavigation } : {}),
+      navTitle: navigation?.title ?? "", navSubtitle: navigation?.subtitle ?? "", navSearch: navigation?.search ?? "",
+      createNavTitle: createNavigation?.title ?? "", createNavSubtitle: createNavigation?.subtitle ?? "",
+      createNavSearch: createNavigation?.search ?? "",
       metricText: "—",
       statusText: "",
       unavailable: false,

package/templates/events-meetups-owner/dev/index.ts

@@ -51863,6 +51863,14 @@ const SCREENS = runtimeSetting({
                                                                     "actionId": "tier5.himiOwnerLiteManage.create",
                                                                     "params": {
                                                                       "id": "$item.id"
+                                                                    },
+                                                                    "nav": {
+                                                                      "screenId": "$item.createScreenId",
+                                                                      "args": {
+                                                                        "title": "$item.createNavTitle",
+                                                                        "subtitle": "$item.createNavSubtitle",
+                                                                        "search": "$item.createNavSearch"
+                                                                      }
                                                                     }
                                                                   },
                                                                   "accessibilityLabel": "$item.createLabel",
@@ -51924,6 +51932,14 @@ const SCREENS = runtimeSetting({
                                                     "actionId": "tier5.himiOwnerLiteManage.openArea",
                                                     "params": {
                                                       "id": "$item.id"
+                                                    },
+                                                    "nav": {
+                                                      "screenId": "$item.screenId",
+                                                      "args": {
+                                                        "title": "$item.navTitle",
+                                                        "subtitle": "$item.navSubtitle",
+                                                        "search": "$item.navSearch"
+                                                      }
                                                     }
                                                   },
                                                   "accessibilityLabel": "$item.title",
@@ -52169,6 +52185,14 @@ const SCREENS = runtimeSetting({
                                                                             "actionId": "tier5.himiOwnerLiteManage.create",
                                                                             "params": {
                                                                               "id": "$item.id"
+                                                                            },
+                                                                            "nav": {
+                                                                              "screenId": "$item.createScreenId",
+                                                                              "args": {
+                                                                                "title": "$item.createNavTitle",
+                                                                                "subtitle": "$item.createNavSubtitle",
+                                                                                "search": "$item.createNavSearch"
+                                                                              }
                                                                             }
                                                                           },
                                                                           "accessibilityLabel": "$item.createLabel",
@@ -52230,6 +52254,14 @@ const SCREENS = runtimeSetting({
                                                             "actionId": "tier5.himiOwnerLiteManage.openArea",
                                                             "params": {
                                                               "id": "$item.id"
+                                                            },
+                                                            "nav": {
+                                                              "screenId": "$item.screenId",
+                                                              "args": {
+                                                                "title": "$item.navTitle",
+                                                                "subtitle": "$item.navSubtitle",
+                                                                "search": "$item.navSearch"
+                                                              }
                                                             }
                                                           },
                                                           "accessibilityLabel": "$item.title",
@@ -65573,7 +65605,10 @@ const SCREENS = runtimeSetting({
                                             "title": "Back to Inbox",
                                             "style": "secondary",
                                             "action": {
-                                              "actionId": "tier5.ownerLiteInboxThread.back"
+                                              "actionId": "tier5.ownerLiteInboxThread.back",
+                                              "nav": {
+                                                "presentation": "back"
+                                              }
                                             }
                                           }
                                         }