@wix/himalaya-cli 0.1617.0 → 0.1619.0

package/guides/ios-ux.md

@@ -1,40 +1,119 @@
 # Designing a Himi App for iOS
 
-Apply [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)
-while planning, building, and reviewing—not only at the end. Keep the task and brand shared with
-Android; respect iOS conventions when they alter a user's learned expectation.
+Read this before you write `MOBILE-UX.md`, and again before you compose a screen. Each pattern
+below is a decision, the Himi field that implements it, and the Apple page it comes from. Read
+it with `himi docs android-ux` (https://apps.wix.com/_api/himi-serve/docs/android-ux.md): iPhone
+and Android render the **same** descriptor, so a decision you make here is made for Android too.
+
+## What iOS does for you, and what it cannot do
+
+A Himi screen is one descriptor that the iOS shell renders with SwiftUI. Three things are
+native on iPhone without any work from you, and you should not redraw them:
+
+- **Chrome the shell draws:** the tab bar, the navigation bar and its title, Back and the edge
+  swipe, the search field in the bar, sheets and alerts.
+- **Controls the renderer draws:** `Toggle` is a `UISwitch`, `SegmentedControl` is a segmented
+  control, `Picker`/`DatePicker`/`Menu`/`BottomSheet`/`AlertDialog` are the system ones.
+- **Your type scale:** typography tokens scale with Dynamic Type.
+
+One thing it **cannot** do: give iPhone a different layout from Android. Lists, cards and inset
+sections draw the same on every renderer. Choose one structure and say so
+in `MOBILE-UX.md`; do not plan "inset grouped on iPhone, full-bleed on Android", because no Himi
+screen can deliver it. Per-platform *look* — type face, corner radius, spacing — is a token
+overlay (see **Idiom overlay** below), not a second screen. `himi render --platform ios` changes
+the switch, the segmented control, and the type face. A list or a grid looks the same in the
+Android PNG. That is one descriptor, not a failed render.
+
+## Patterns
+
+| Decision | Do this on iOS | Himi mapping | Apple source |
+| --- | --- | --- | --- |
+| Top-level destinations | Tab bar of three to five destinations; the shell draws it. | `navigation` tabs in `config.ts` (`himi docs app-config`). Never a row of buttons at the bottom of a screen. | [Tab bars](https://developer.apple.com/design/human-interface-guidelines/tab-bars) |
+| Screen title | Large title on a tab's root screen, collapsing as it scrolls; inline title on a pushed screen. | Set the screen's `title`; the shell makes a root screen's title large on its own. `topBar.titleDisplay: "large" \| "inline"` overrides it. Do not repeat the title, or the app name, as Text in the body in any style. A group's name is the `Section` `header`, not a heading above it. `himi render` does not draw that bar — pass `--platform ios` so the controls match iPhone, and judge the title by the `title` field. A PNG with no large heading at the top is correct when `title` is set. | [Navigation bars](https://developer.apple.com/design/human-interface-guidelines/navigation-bars) |
+| Back | Back button plus edge swipe; the system owns both. | Push with navigation actions; the shell adds Back. Only `topBar.leading: "none"` with a `stickyHeader` replaces the bar, and system back still works. | [Navigation and search](https://developer.apple.com/design/human-interface-guidelines/navigation-and-search) |
+| Completing a flow (Book, Pay, Confirm) | One prominent button at the bottom, above the home indicator. | `stickyFooter` holding one `Button` with `style: "primary"` and `fullWidth: true`, on a `surfacePrimary` background with padding. | [Buttons](https://developer.apple.com/design/human-interface-guidelines/buttons) |
+| Creating, adding, editing, saving | A bar button in the navigation bar, trailing. | `topBar.items: [{ id, placement: "trailing", label, icon, onTap, role: "confirm" }]`. It is a bar button on iPhone and a top-app-bar action on Android. | [Toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars) |
+| Floating action button | Not an iOS pattern. | Avoid `Fab` in a shared screen: it draws on iPhone too. Use the trailing `topBar.items` entry instead. | [Toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars) |
+| Grouped content (settings, profile, booking details) | Inset grouped sections with a header and footer. | `Section` with `inset: true`, `header`, `footer`; rows are `ListItem` (`accessory: "chevron"` to drill in). The same sections render on Android. | [Lists and tables](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables) |
+| Collections people choose by photo (products, books, portfolio, projects) | A collection of image tiles; the tile is the tap target. | `Grid` `columns: 2` (`columnsMedium: 3`, `columnsExpanded: 4`); a gallery `columns: 3`, `spacing: 2`; a shelf of covers a horizontal `LazyList` sized so the next cover peeks at 390 points. Each tile is an `Image` (`fillWidth`, fixed `aspectRatio`, `contentMode: "fill"`, `placeholder`, `contentDescription`) with the name and price under it and `modifiers.onTap` on the tile; no `Card` or button per tile. A detail screen opens with its photos edge to edge. | [Collections](https://developer.apple.com/design/human-interface-guidelines/collections), [Images](https://developer.apple.com/design/human-interface-guidelines/images) |
+| Long collections without photos (schedule, services, settings-like lists) | A plain scrolling list; the row is the tap target. | Root `LazyList` of `ListItem` rows; one primary action per row at most; `pagination` for more. A class and a service are `ListItem`s, not one `Card` each. One featured object may be a single `Card`. Choices that may not fit the width, such as times, go in a `LazyList` with `horizontal: true`, so the last choice is reachable at 390 points. | [Lists and tables](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables) |
+| On/off, one of a few, pick a date | The system switch, segmented control, picker. | `Toggle` (`label`, `value`): the `label` is the row drawn beside the switch. `SegmentedControl` with `options: [{ id, label }]` — `label` is required, and `title` on an option fails native decode and drops the whole screen. `Picker`, `DatePicker`. Never a row of buttons or a drawn switch. | [Toggles](https://developer.apple.com/design/human-interface-guidelines/toggles), [Segmented controls](https://developer.apple.com/design/human-interface-guidelines/segmented-controls) |
+| A short task on top of a screen | A sheet; Cancel and Done in its bar. | `BottomSheet`. A new destination is a push instead. | [Sheets](https://developer.apple.com/design/human-interface-guidelines/sheets) |
+| Destructive or blocking decision | An alert, with the destructive button styled as such. | `AlertDialog`, or a `ToolbarItem` with `role: "destructive"`. Confirm or offer undo. | [Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts) |
+| Success | Brief, non-blocking feedback. | `ui.snackbar` from the worker, not an alert. | [Feedback](https://developer.apple.com/design/human-interface-guidelines/feedback) |
+| Search | A search field in the navigation bar. | `topBar.searchable` plus the page's own `SearchField` (or the row that holds it) with `hiddenPath: "$env:topBarSearch"`. The standard app shell draws that field; only a host with a native search handler hides it for the bar. A dedicated search screen when search starts a new task (`himi docs recipe-search`). | [Search fields](https://developer.apple.com/design/human-interface-guidelines/search-fields) |
+| iPad and wide windows | Sidebar or split view for collections; a readable column for reading. | `SplitView`, `Grid` `columnsMedium`/`columnsExpanded`, `contentMaxWidth` in tokens. Render at 834px and record the choice. | [Split views](https://developer.apple.com/design/human-interface-guidelines/split-views) |
+| Type | The system text styles, scaled by Dynamic Type. | Typography tokens from the built-in ramp: `largeTitle`, `title1`–`title3`, `headline`, `body`, `bodyEmphasis`, `callout`, `caption`, `footnote`. No raw sizes. | [Typography](https://developer.apple.com/design/human-interface-guidelines/typography) |
+| Touch targets | At least 44×44 points. | Use `Button`/`ListItem`; do not shrink an icon's hit area below that. | [Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) |
+
+## Settings, copied as props
+
+A settings screen is one `Section`, not a stack of `Card`s, and it has no `title1` Text in the body. The screen `title` is the heading. A `Toggle`'s `label` is the row the renderer draws beside the switch. A `ListItem` `title` with the same word paints it a second time. A row that drills in stays a `ListItem` (`title`, `accessory: "chevron"`).
+
+```jsonc
+"type": "Section",
+"props": { "inset": true, "header": "Preferences", "children": [ /* Toggle, then SegmentedControl */ ] }
+
+"type": "SegmentedControl",
+"props": {
+  "selectedId": "auto",
+  "options": [
+    { "id": "light", "label": "Light" },
+    { "id": "dark", "label": "Dark" },
+    { "id": "auto", "label": "Automatic" }
+  ]
+}
+```
+
+`Button` and `ListItem` take `title`. A segment takes `label`. Mixing those up is what drops the screen on device.
+
+## Idiom overlay — the iOS look without a second screen
+
+The brand stays the same on both phones. What may differ is the platform's dialect: the system
+face, softer or sharper corners, spacing. That lives in `tokens.json`, as a named overlay the
+iOS runtime merges over your base tokens:
+
+```jsonc
+// tokens.json — an overlay may only restyle tokens the base already declares
+"idiom": {
+  "ios":      { "typography": { "body": { "family": "$system", "size": 17, "weight": 400, "line": 1.3 } }, "radius": { "md": 10 } },
+  "material": { "typography": { "body": { "family": "$system", "size": 16, "weight": 400, "line": 1.5 } }, "radius": { "md": 12 } }
+}
+```
+
+```ts
+// config.ts — declaring the block turns it on; each phone picks its own overlay
+idiom: { policy: "follow-surface" },
+```
+
+`"$system"` is SF Pro on an iPhone and Roboto on Android. Keep each typography entry complete
+(`size`, `weight`, `line`), or the theme fails to decode on device. An overlay cannot change a
+brand colour (`accentPrimary`, `accentSecondary`, `accentSurface`, `textOnAccent`); that is
+deliberate, so one brand reads as one brand.
 
 ## Plan
 
-- Choose navigation around user destinations, with one clear primary action per screen.
-- Let the iOS shell own system navigation and chrome; do not reproduce bars or gestures in a
-  descriptor.
-- Specify input, confirmation, cancellation, destructive-action recovery, and empty states.
-- Include dynamic type, VoiceOver, contrast, reduced motion, and right-to-left content from the
-  first screen map. Use Apple's [accessibility guidance](https://developer.apple.com/design/human-interface-guidelines/accessibility)
-  for the current requirements.
-
-## Author
-
-- Use Himi semantic components, logical leading/trailing alignment, accessibility labels, and
-  token-based typography and colour. Native renderers preserve the expected iOS behaviour.
-- Preserve comfortably sized touch targets; Apple documents 44×44 points as the standard control
-  target.
-- Prefer responsive projection for iPad and macOS width. Use `defineView(surface)` only where the
-  content or task differs—not merely because the canvas is larger.
-- Use `@himalaya/app-info` only for a documented runtime behavioural fallback. It must not become
-  a layout switch.
+In `MOBILE-UX.md` → `## Platform decisions`, write one row for each of: navigation, title,
+back, primary action, create/add, lists and grouped content, photo collections, controls, sheets and alerts,
+search, expanded width, and type/idiom. Fill the Himi mapping with the field from the table
+above and the official source with its URL.
 
-## Audit
+Also plan Dynamic Type, VoiceOver labels on every icon and image, contrast in light and dark,
+reduced motion, and right-to-left, from the first screen map.
 
-- Drive the installed iOS app—not only a phone-width render—through back/cancel, typed input and
-  keyboard submit, completion, failure, Dynamic Type, VoiceOver, dark appearance, and reduced
-  motion. Record the result for every declared state in `MOBILE-UX.md`'s acceptance matrix.
-- Compare every deliberate iOS difference with the `MOBILE-UX.md` decision record.
+## Audit
 
-## Route to official guidance
+Render each primary screen with `himi render <screen> --device iphone --platform ios --png <file>`
+and again with `--scheme dark` and at `--device ipad --platform ios`. `--platform ios` draws the
+iPhone switch and segmented control. The navigation bar is still the shell's, so a missing title
+in the PNG is not a missing `title` field. Check: the screen's `title` is set, no heading and no
+app name in the body, a schedule is `ListItem` rows rather than a `Card` per row, products,
+books and photos are image tiles with every image filled and none stretched, a rail shows part of
+its next item, a horizontal choice row still shows its last item, the primary action in the footer or the bar
+(never floating), no hand-drawn switch or segmented control, and nothing hidden behind the home
+indicator.
 
-- [Navigation and hierarchy](https://developer.apple.com/design/human-interface-guidelines/navigation-and-search)
-- [Tab bars](https://developer.apple.com/design/human-interface-guidelines/tab-bars)
-- [Typography](https://developer.apple.com/design/human-interface-guidelines/typography)
-- [Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility)
+On an installed iOS app, drive back and edge swipe, typed input and keyboard submit,
+completion, failure, Dynamic Type, VoiceOver and dark appearance. Record the result for every
+declared state in the `MOBILE-UX.md` acceptance matrix; with no device, record
+`himi ux record --status unavailable` with the reason.

package/guides/mobile-ux.md

@@ -18,7 +18,10 @@ the approved acceptance scenarios as the readiness bar for the private preview.
    data sources, platform envelope, screen catalogue, and non-goals.
 2. Write `MOBILE-UX.md`: task flows, every screen state, accessibility and localisation needs,
    motion, and platform decisions.
-3. Apply the iOS and Android guides while planning, then again while authoring and reviewing.
+3. Read `himi docs ios-ux` (https://apps.wix.com/_api/himi-serve/docs/ios-ux.md) and
+   `himi docs android-ux` (https://apps.wix.com/_api/himi-serve/docs/android-ux.md) in full
+   **before** filling `## Platform decisions`, then apply them again while authoring and
+   reviewing. They map each Apple and Material pattern to the Himi field that builds it.
 4. Build shared Himi screens from the contract. Keep the two documents with the app so the next
    author can extend the experience without rediscovering its decisions.
 
@@ -87,6 +90,14 @@ perform the customer task, says what is unavailable, and cannot write customer d
 ## Platform decisions
 | Shared intent | iOS behaviour | Android behaviour | Himi mapping | Official source |
 | --- | --- | --- | --- | --- |
+| Top-level navigation | | | | |
+| Title and back | | | | |
+| Primary action | | | | |
+| Create / add | | | | |
+| Lists and grouped content | | | | |
+| Controls, sheets, alerts | | | | |
+| Expanded width | | | | |
+| Type and idiom | | | | |
 
 ## Implementation acceptance
 | Flow or declared state | Trigger | Expected visible result | Primary CTA | Render / device evidence |
@@ -287,10 +298,16 @@ target file.
 Use the least expensive option that preserves the task:
 
 1. **One descriptor, responsive projection** — the normal case. Use semantic components, size
-   classes, grids, split views, and shell navigation.
-2. **One worker, surface-specific view** — use `defineView(surface)` when a phone, desktop, or
-   wrist answers a materially different question. See [authoring per surface](authoring-per-surface.md).
-3. **Tier-0 native screen** — use only when native APIs or interaction are the point of the screen.
+   classes, grids, split views, and shell navigation. The shell and the native controls already
+   look like iOS on an iPhone and like Material on Android.
+2. **Idiom overlay** — when iPhone and Android should differ in *look* (type face, radius,
+   spacing) but not in structure: a `tokens.json` `idiom` block with `ios` and `material`
+   overlays, turned on by `idiom: { policy: "follow-surface" }` in `config.ts`. It cannot change
+   brand colours. See `himi docs ios-ux` → Idiom overlay.
+3. **One worker, surface-specific view** — use `defineView(surface)` when a phone, desktop, or
+   wrist answers a materially different question. Surfaces are form factors (`phone`, `tablet`,
+   `desktop`, `watch`, …), not operating systems: there is no iPhone-only or Android-only view.
+4. **Tier-0 native screen** — use only when native APIs or interaction are the point of the screen.
 
 Do not create per-node OS conditionals in a descriptor. The wire model stays platform-blind.
 

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

@@ -31,6 +31,38 @@ Source snapshots: Catalyst `617c06d43d2a5608b6876d724553269b1e5346f0`; Himalaya
 
 ## Mappings by server group
 
+### Member-only visibility during migration
+
+The following eleven definitions omit `visitorModeEnabled`, whose source default
+is false. Their authentication visibility is supported through
+`oneAppSection`/`createOneAppSectionService`: hidden for visitors and unresolved
+authentication, visible after confirmed sign-in subject to all other restrictions,
+hidden again after sign-out. This visibility support does not change a row's data/UI
+mapping classification or certify an unimplemented vertical.
+
+| Section definition | Visibility migration rule |
+| --- | --- |
+| `food_section` | Signed-in-only; preserve instance settings, content and ordering. |
+| `newBlog_submit_post_section` | Signed-in-only; preserve author permissions, settings and ordering. |
+| `selections` | Signed-in-only; preserve instance settings, content and ordering. |
+| `file_share_section` | Signed-in-only; preserve folder/file access, settings and View All action. |
+| `events_guests_section` | Signed-in-only; preserve event scope, guest privacy and settings. |
+| `events_discussion_section` | Signed-in-only; preserve event scope, discussion settings and actions. |
+| `performance_tracker_section` | Signed-in-only; preserve member performance, settings and tracker CTA. |
+| `achievements_participant_carousel_section` | Signed-in-only; preserve member participation/progress, settings, default limit 5 and participant-programs CTA. |
+| `memberships_packages_section` | Signed-in-only; preserve member plan orders, balances/credits, settings and MyMemberships CTA. |
+| `upcoming_bookings_section` | Signed-in-only; preserve upcoming-only selection, settings, limit and ActivityFeedCards CTA. |
+| `loyalty_status_section` | Signed-in-only; preserve member points, tier/status and display settings. |
+
+Use the collected definition when present, including an explicit visitor-enabled
+override; otherwise the migration graph uses these pinned stable IDs. Preserve
+general experiments, visitor experiments and other conditions, with unknown values
+unresolved. Apply the same gate to layouts, detached layouts and Business Profile
+placements of these eleven types, keeping duplicate instances separate. Other
+section types retain their existing visibility/access behavior and receive no new
+authentication gate, including when their definitions are absent. See the current migration guide's
+[visibility recipe and deterministic test contract](https://apps.wix.com/_api/himi-serve/docs/one-app-to-himi-app.md#preserve-section-visibility-across-authentication).
+
 The **Himalaya implementation** cell is blank for every unassigned row. Notes on existing partial building blocks are not fallback selections.
 
 ### 1. mobile-app-widgets-section-definitions.json

package/guides/one-app-to-himi-app.md

@@ -164,6 +164,14 @@ The CLI's versioned native-widget inventory supplies these rows automatically.
 | `newBlog_postlist_vertical_section`, `newBlog_compact_post_list_vertical_section` | Row display options, unlimited paging or a limited count with See All Posts, and layout. Coverage derives these per placement from the authored settings: see "Generate blog post lists from their settings". |
 | `events_list_section` | Date badge, Share and the appropriate RSVP/ticket action. |
 | `platform_general_members_section`, `platform_general_members_section_bp` | Effective member strip and directory journey: totals/search, alphabetical sections, Follow, activity/privacy. Distinguish badge chips from actual viewed-member program progress. |
+| `file_share_section` | Signed-in-only file/folder section. Preserve access rules, instance settings and View All (`media.openFileShareListScreen`); a media gallery is not File Share. |
+| `events_guests_section` | Signed-in-only guests for the configured event, preserving the event selector, guest privacy and display settings; an avatar summary is not the full guest list. |
+| `events_discussion_section` | Signed-in-only discussion for the configured event, preserving its selector, settings and actions; do not substitute a group feed or blog comments. |
+| `performance_tracker_section` | Signed-in-only member performance tracker, settings and `wix.bookings.performanceTrackerCTA`; do not substitute a generic steps/session-goal widget. |
+| `achievements_participant_carousel_section` | Signed-in-only participating-programs carousel with actual member progress, source selectors/settings, default limit 5 and `wix-one-app-achievements.ParticipantChallengesScreen` CTA; not the public Programs catalog. |
+| `memberships_packages_section` | Signed-in-only memberships/packages, including member plan orders, package balances/session credits, authored settings and `memberships.screens.MyMemberships` CTA. |
+| `upcoming_bookings_section` | Signed-in-only upcoming member bookings, preserving upcoming-only selection, source limit/settings and `wix.bookings.activities.ActivityFeedCards` CTA; do not include historical bookings. |
+| `loyalty_status_section` | Signed-in-only member points, tier/status and authored display settings; the public rewards catalog does not implement member status. |
 
 This initial checklist comes from reported native source-device observations
 on 2026-11-02 across two migrations, not editor demo records.
@@ -177,6 +185,92 @@ no adaptation waiver, and this checklist must not force the disabled control on.
 Data/access-dependent controls need the relevant source state; never fabricate
 participants or derive program completion from a badge title.
 
+### Preserve section visibility across authentication
+
+The eight member-only rows above are supported by the shared visibility recipe below;
+their data/UI implementation still needs the per-section mapping and live verification.
+The same visibility rule also applies to `food_section`,
+`newBlog_submit_post_section` and `selections`; these three are intentionally not
+added to the native-defaults table.
+
+OneApp's section-definition contract defaults omitted `visitorModeEnabled` to
+`false`. The eleven IDs above omit it in the pinned source definitions. The source
+graph records `sectionVisibility[sectionId]` **only for these eleven definition IDs**, deterministically from collected
+`definitions.sections[sectionDefinitionId]`, falling back to those pinned IDs
+only when the definition is absent. A collected explicit `true` takes precedence.
+For these eleven types, malformed definitions or flags/experiment lists remain unresolved; never
+guess from a display name. The raw section instances, settings, permissions and
+placement order remain intact, even when absent from the visitor-enriched view.
+
+All other section types keep their existing visibility and access behavior. Do not
+wrap them in this new authentication gate or infer member-only access from missing
+definitions. An absent `sectionVisibility[sectionId]` means this recipe does not
+apply; it does not mean hidden or unresolved. Preserve their existing permission,
+experiment and other source restrictions separately.
+The graph omits `sectionVisibility` entirely when no reviewed placements exist;
+use `graph.sectionVisibility?.[sectionId]` when selecting the recipe.
+
+For every placement **of these eleven types** in screen layouts, detached layouts and the Business Profile:
+
+- Keep the section hidden while authentication is unresolved and while signed out.
+  Show it after successful sign-in in its original position, subject to its other
+  permission/OS/paid-plan and general experiment conditions. Hide it after sign-out.
+  Cancelled or failed sign-in does not reveal it; restored sessions reveal it only
+  after identity is established. Keep content/configuration, not the last member's
+  runtime data.
+- Preserve `experiments` for every identity. For visitor-enabled definitions,
+  require all `visitorModeExperiments` for visitors; unknown values are unresolved,
+  never assumed true. General restrictions continue to apply after sign-in.
+- Use `oneAppSection` and `createOneAppSectionService` from
+  `@wix/himalaya/screens` in the screen's worker. Assign a distinct stable service
+  and wrapper ID to every placement, including repeated types and profile copies.
+  Declare `wix_platform` and `app_info`, and set the screen bundle's
+  `minBinaryVersion: "1.9.0"` (`min_binary_version` on the wire), for identity reads and the host's reserved
+  `onIdentityChange` hook (iOS/macOS, Android and web). No rebuild or remigration
+  is needed on identity changes. Older hosts without this hook need a runtime
+  update; a one-time identity read alone is not parity. The helper also checks the
+  native binary version and hydration/persistence support (the web host uses
+  the advertised `identityChangeVersion` feature support, since its version is a
+  placeholder), resets legacy hydrated data
+  synchronously and stays hidden without reads on an incompatible runtime.
+- Pass the graph's visibility rule to the service, current experiment values via
+  `experiments`, and the conjunction of the other rules via `otherAllowed`.
+  Pass `getIdentity: () => auth.getIdentity()` from the screen worker's
+  `@himalaya/wix-platform` import; the helper calls it only after runtime compatibility checks.
+  Call `load` when non-auth conditions change. Supply the member read through
+  `read`, bind its `data`/`loading`/`error` state in the authored content,
+  and compose it inside `oneAppSection(content, {id, service})`. Do not start an
+  eager member worker or read outside the gate. The helper's empty hidden
+  FragmentSlot case does not mount member controls/onAppear actions. It clears
+  runtime data on identity changes and drops late reads from the previous identity.
+
+Coverage derives an `access-state` obligation only for placements with a visibility rule in that scoped map.
+Do not mark it supported on a manual screenshot or AI evaluation alone: run
+deterministic tests asserting migration output and observable rendered sections.
+Parameterize all eleven IDs; assert unchanged content/settings/order and stable
+repeat output; cover visitor → successful sign-in → sign-out, unresolved/restored
+identity, cancelled/failed sign-in, duplicate instances, layouts plus Business
+Profile, mixed public/private screens, omitted/false/true flags, experiments and
+other restrictions. Assert zero hidden member reads and reject late results after
+sign-out or account changes. Keep the test command/results and rendered evidence
+with the exact release's coverage records.
+Verify non-target section types, including those with absent definitions, receive
+no new gate or authentication obligation and retain their content and placement.
+
+For a signed-in-only placement, the passed `access-state` record must include
+`sectionVisibility: {kind: "automated", command, hiddenMemberReads: 0, states,
+testReport: {path, sha256}}`. The report path is relative to the content root and
+its SHA-256 must match the actual test report. `states` must assert
+`unresolved`, `visitor`, `signedOut`, `cancelled`, `failed` and
+`otherRestricted` as `"hidden"`, and `signedIn`/`restored` as `"visible"`.
+The check's existing requirement ID, target and release hash still apply.
+Coverage verification rejects a generic/manual pass, missing assertions or changed
+test reports. These records report tests actually run, never invented evidence.
+
+Source evidence: [section definitions](https://github.com/wix-private/catalyst-server/tree/617c06d43d2a5608b6876d724553269b1e5346f0/one-app-sections/one-app-sections-definitions/src/main/resources/sections),
+[visitor criteria](https://github.com/wix-private/mobile-apps-editor/blob/53cac5fabd41f761632d3574b6a74624c2816427/packages/mobile-apps-editor-middleware/src/domain/EnrichedStructure/DisplayCriteria.ts#L161)
+and [layout/profile filtering](https://github.com/wix-private/mobile-apps-editor/blob/53cac5fabd41f761632d3574b6a74624c2816427/packages/mobile-apps-editor-middleware/src/domain/EnrichedStructure/EnrichedViewer.ts#L293).
+
 ### Generate blog post lists from their settings
 
 A migrated blog list is app-authored, not a template screen, so nothing makes it match the source
@@ -845,13 +939,39 @@ The readiness `metaSiteId` must match this migration's collected site. `state` i
 when it was checked. Use verified site-bound owner payment settings or a proven
 read-only contract when available. A denied or unavailable read remains
 `unverified`, with the actual access gap recorded. Never infer provider eligibility
-from the site's country. Ready evidence permits `decision: { action: "proceed" }`.
-For missing or unverified setup, tell the owner what is known and ask them to:
-
-- `connect-provider`: complete setup in their site dashboard, then recheck before
-  generating that paid UI. Migration does not connect the provider itself.
+from the site's country. The target must stay bound to the same site; preserve its
+existing payment configuration instead of asking the owner to connect it again.
+
+Review the source purchase action against the target's checkout path, including
+the vertical, payment method and any native in-app purchase requirements. Record
+`checkout: { state, evidence }`, where `state` is `supported`, `unsupported` or
+`unverified` and `evidence` names the source flow and target implementation. Do not
+mark an unsupported target ready just because the merchant has a provider.
+Newly collected reviews use `schemaVersion: 2` and require `checkout` for every
+online-paid flow, including those with verified merchant readiness. Legacy
+schema-1 ready reviews without `checkout` remain accepted for compatibility.
+Do not downgrade a newly collected review to bypass its checkout check.
+
+If payment readiness is `ready`, use `decision: { action: "proceed" }` unless the
+checkout review identifies a gap. If readiness is `unverified` and checkout is
+`supported`, preserve the existing flow by default: omit `decision` or record
+`{ action: "proceed" }`. No owner decision or pre-checkout warning is required
+solely because the payment settings read is unavailable. Keep the uncertainty in
+the review and migration report; the checker returns a per-flow
+`payment_readiness_unverified` warning without refusing generation. Do not tell
+the owner or customers that payments are disconnected based on an unavailable read.
+
+For confirmed missing setup or a target checkout gap, explain the specific issue
+and ask how to proceed. Investigate unverified target compatibility before asking
+the owner to choose an adaptation. The available decisions are:
+
+- `connect-provider`: for confirmed missing payment setup, complete setup in their
+  site dashboard, then recheck before generating that paid UI. Migration does not
+  connect the provider itself. Connecting a provider cannot resolve an unsupported
+  target checkout.
 - `retain`: keep the flow with a localized explanation **before checkout** that
-  payments are unavailable or unverified, plus a real contact or back action.
+  describes the confirmed issue or unresolved compatibility, plus a real contact
+  or back action. Do not claim missing payment setup when its status is unknown.
   Record that copy in `decision.explanation` and the actual planned recovery in
   `decision.recovery`: `{ action: "back" }` or `{ action: "contact", target:
   "<real contact route>" }`. Implement the copy and action in the target; the
@@ -860,17 +980,21 @@ For missing or unverified setup, tell the owner what is known and ask them to:
   and the remaining free/offline content.
 
 Record their instruction in `decision.instruction`; cite an existing explicit
-instruction instead of asking again. Run `himi one-app validate-payments
+instruction instead of asking again; an existing retain/hide/connect-provider
+instruction still applies when the payment read is unavailable. Run `himi one-app validate-payments
 --evidence-dir .himi/one-app --json` before scaffolding. It reads this editable
 review and the hash-verified collected source, checks decisions and site binding,
 and creates nothing. A passing check validates the recorded plan, not the truth
 of merchant readiness. The review's original manifest hash describes the initial
 template; edit the review without rewriting collected evidence or manifest hashes.
 Keep the decision, resulting target controls and controlled runtime evidence in
-the reconstruction plan and migration report. For retained flows, handle the exact
+the reconstruction plan and migration report. For all paid flows, handle the exact
 structured `SITE_NOT_ACCEPTING_PAYMENTS` failure with clear recovery; unrelated
 HTTP 428 failures must retain their own meaning. Test paid/free/offline and
-missing/ready/unverified cases without real transactions. General app validation
+missing/ready/unverified cases and target checkout compatibility without real
+transactions. If a purchase worked in the original app but fails after migration,
+investigate the target checkout and site binding before attributing it to the
+owner's payment setup. General app validation
 and publishing do not gain a new payment gate.
 
 Write `SPEC.md` and `MOBILE-UX.md` in the workspace. Use the current

package/guides/skill.md

@@ -9,6 +9,24 @@ description: Guide a business from a mobile-app idea to a browser-reviewed priva
 
 You are the customer's mobile-product partner and implementation agent. Take them from an idea to a working, **owner-private** web preview. Do not make the customer paste a long setup prompt or force them to understand Himalaya terminology.
 
+## Required design-guide reading for coding agents
+
+This page is long; if your tool shows only its start, read the rest from the saved output. Before
+you write `MOBILE-UX.md`, and again before you compose the first screen, fetch each of these four
+public guides by its own URL and read it in full (or `himi docs <id>` from the installed CLI):
+
+- https://apps.wix.com/_api/himi-serve/docs/mobile-ux.md — the product and UX contract.
+- https://apps.wix.com/_api/himi-serve/docs/ios-ux.md — Apple's patterns mapped to the Himi field that builds each one.
+- https://apps.wix.com/_api/himi-serve/docs/android-ux.md — Material's patterns mapped the same way.
+- https://apps.wix.com/_api/himi-serve/docs/designing-himi-screens.md — composing one screen from components and tokens.
+
+A grep or summarized excerpt does not satisfy this. The iOS and Android guides are what make the
+app native: the shell already draws the tab bar, title and Back on each platform, a shared `Fab`
+also draws on iPhone, lists render the same on every renderer, and per-platform look comes from a
+`tokens.json` `idiom` overlay, not from a second screen. Fill `## Platform decisions` from
+them, with each official source as a URL. Do not add a customer approval gate just for reading
+these public guides.
+
 ## One App migration route — before generic discovery
 
 When the user invokes `himi one-app migrate`, or you are continuing that user's
@@ -27,7 +45,8 @@ and template-preview journey below. Write the reconstruction plan, `SPEC.md`,
 same-site One App visitor binding, checks and hosted draft. Obtain the
 site owner's agreement before creating or updating an OAuth client for optional
 member flows; visitor reads and native email/password sign-in need no client.
-Before composing content, read `himi docs designing-himi-screens` and apply the
+Before composing content, read `himi docs ios-ux`, `himi docs android-ux` and
+`himi docs designing-himi-screens`, and apply the
 migration guide's screen-content contract: readable detail sections, stable rail
 and image sizing, grouped icon rows for More, native bottom clearance and distinct
 loading/empty/error states. Put the relevant cases in `MOBILE-UX.md` and verify
@@ -70,6 +89,11 @@ These are agent instructions, not a claim that the CLI enforces a reading or ret
    - **Write this skeleton into `MOBILE-UX.md`, then fill it in.** `himi validate --strict` and `himi ux audit --strict` read these exact headings and columns, so a plan written in your own structure fails the gate after approval, when rewriting it is most expensive. Keep both headings spelled as shown, give the acceptance table a `Primary CTA` column with one row per state and exactly one CTA per cell (`none` is an answer; a comma-, semicolon- or slash-separated list is not), and under `## Evidence` write the widths you actually rendered — one compact (at most 599px) and one wider (at least 600px); `himi render <screenId> --device iphone` renders 390px and `--device ipad` renders 834px. Your own sections (flows, states, accessibility, platform decisions) go around these. The full contract is `himi docs mobile-ux` (https://apps.wix.com/_api/himi-serve/docs/mobile-ux.md before the CLI is installed).
 
      ```markdown
+     ## Platform decisions
+     | Shared intent | iOS behaviour | Android behaviour | Himi mapping | Official source |
+     | --- | --- | --- | --- | --- |
+     | Primary action | <from ios-ux> | <from android-ux> | <stickyFooter or topBar.items> | <developer.apple.com/design/… and m3.material.io/… URLs> |
+
      ## Implementation acceptance
      | Flow or declared state | Trigger | Expected visible result | Primary CTA | Render / device evidence |
      | --- | --- | --- | --- | --- |

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

@@ -159,6 +159,8 @@ one object either way.
 
 So a text-input reducer is `setDraft: (s, p) => ({ ...s, draft: String(p?.value ?? "") })`, bound with `onChange: { actionId: "tier5.notes.setDraft" }`.
 
+**Annotate that payload.** `defineService` gives an unannotated second parameter the type `never`, so `p.value` and `p.selectedId` fail `himi validate --strict` even when the read is the one in the table. Write the parameter's type: `setDraft: (s, p: { value?: unknown } | undefined) => ({ ...s, draft: String(p?.value ?? "") })`. A `SegmentedControl` handler names `selectedId` on that same type.
+
 **The payload argument can be absent.** A host calls the reducer with one merged object when
 `params`/`args` carry anything, and with **no argument at all** when both are empty — so the
 second parameter is `undefined`, not `{}`. A device always injects `{ value }` for the controls in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1617.0",
+  "version": "0.1619.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": "ca22226ed33669cefe5f25805d924885e9f4472817b9be7ad316e2d1"
+  "falconPackageHash": "d9d834feab74f884aec00e986ae13ed5dcb2f5fea15f6ea9ac2e5796"
 }

package/templates/brandy/dev/index.ts

@@ -347,10 +347,11 @@ export default {
   config,
   homeScreenId: "site_home",
   screens: {
-    // A fresh copy per build: descriptors are pure functions of the site block.
+    // A fresh copy per build: descriptors are pure functions of the site block. A JSON round
+    // trip, not structuredClone: `himi test` builds screens in the contained realm, which withholds it.
     exact: {
-      ...Object.fromEntries(Object.keys(SCREENS).map((id) => [id, () => structuredClone(SCREENS[id])])),
-      himi_notification_settings: () => structuredClone(NOTIFICATIONS),
+      ...Object.fromEntries(Object.keys(SCREENS).map((id) => [id, () => JSON.parse(JSON.stringify(SCREENS[id]))])),
+      himi_notification_settings: () => JSON.parse(JSON.stringify(NOTIFICATIONS)),
     },
     templated: [],
   },