@wix/himalaya-cli 0.1617.0 → 0.1619.0

package/guides/android-ux.md

@@ -1,39 +1,76 @@
 # Designing a Himi App for Android
 
-Apply the official [Android design guidance](https://developer.android.com/design) throughout
-planning, implementation, and review. Keep the product intent shared with iOS; use Android-native
-expectations when they materially change navigation, back behaviour, feedback, or adaptation.
+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 Android page it comes from. Read
+it with `himi docs ios-ux` (https://apps.wix.com/_api/himi-serve/docs/ios-ux.md): iPhone and Android
+render the **same** descriptor, so a decision you make here is made for iPhone too.
 
-## Plan
+## What Android does for you, and what it cannot do
 
-- Define the Android back path for every flow, especially sheets, search, selection, and forms.
-- Design for compact and expanded windows from the start; Android's
-  [adaptive layout guidance](https://developer.android.com/design/ui/mobile/guides/layout-and-content/adapt-layout)
-  is the reference.
-- Make loading, empty, error, permission, offline, and destructive states actionable.
-- Plan TalkBack, scalable text, contrast, reduced motion, RTL, and touch targets. Use Android's
-  [accessibility guidance](https://developer.android.com/design/ui/mobile/guides/foundations/accessibility)
-  for the current requirements.
+A Himi screen is one descriptor that the Android shell renders with Jetpack Compose and
+Material 3. Three things are native without any work from you, and you should not redraw them:
 
-## Author
+- **Chrome the shell draws:** the navigation bar at the bottom, the top app bar and its title,
+  system and predictive Back, the search bar, bottom sheets and dialogs.
+- **Controls the renderer draws:** `Toggle` is a Material switch, `SegmentedControl` a
+  segmented button, `Picker`/`DatePicker`/`Menu`/`BottomSheet`/`AlertDialog` the Material ones.
+- **Your type scale:** typography tokens are emitted in `sp` and follow the user's font scale.
 
-- Express intent through Himi semantic components and tokens; let the Android renderer supply the
-  native interaction model rather than recreating Material chrome in the descriptor.
-- Prefer responsive grids, split views, and shell navigation. Use `defineView(surface)` only when
-  the screen's job differs by surface.
-- Treat `@himalaya/app-info` as an exceptional, asynchronous behavioural fallback—not a layout or
-  theme selector. Use capability availability for platform feature support.
+One thing it **cannot** do: give Android a different layout from iPhone. Lists, cards and inset
+sections draw the same on every renderer. Choose one structure and say so
+in `MOBILE-UX.md`. Per-platform *look* — type face, corner radius, spacing — is the
+`material` token overlay (see **Idiom overlay** in `himi docs ios-ux`), not a second screen.
+The overlay may change type face, radius and spacing; it may not change a brand colour.
+`himi render --platform android` changes the switch, the segmented button, and the type face.
+A list or a grid looks the same in the iPhone PNG. That is one descriptor, not a failed render.
 
-## Audit
+## Patterns
+
+| Decision | Do this on Android | Himi mapping | Android source |
+| --- | --- | --- | --- |
+| Top-level destinations | Navigation bar of three to five destinations on a phone. | `navigation` tabs in `config.ts` (`himi docs app-config`); the shell draws the bar. | [Navigation bar](https://m3.material.io/components/navigation-bar/guidelines) |
+| Screen title | Top app bar with the screen title. | Set the screen's `title`. Do not repeat it, or the app name, as Text in the body in any style. Today's Android shell leaves the top-bar title slot empty, so a body title would show twice on iPhone and still not as a bar title here. A group's name is the `Section` `header`. A render with no large heading at the top is correct when `title` is set. `himi render --platform android` draws the Material switch and segmented button. | [Top app bar](https://m3.material.io/components/top-app-bar/guidelines) |
+| Back | System Back, including the predictive back gesture, closes transient UI before it leaves the screen. | The shell handles Back. Plan the order in `MOBILE-UX.md`: an open sheet, search or selection closes first. | [Predictive back](https://developer.android.com/design/ui/mobile/guides/patterns/predictive-back) |
+| Completing a flow (Book, Pay, Confirm) | One filled button at the bottom of the content. | `stickyFooter` holding one `Button` with `style: "primary"` and `fullWidth: true`. The same footer serves iPhone. | [Buttons](https://m3.material.io/components/buttons/guidelines) |
+| Creating, adding, editing, saving | An action in the top app bar. | `topBar.items: [{ id, placement: "trailing", label, icon, onTap, role: "confirm" }]`. It is a top-app-bar action here and a bar button on iPhone. | [Top app bar](https://m3.material.io/components/top-app-bar/guidelines) |
+| Floating action button | Material's create affordance, but a shared screen also draws it on iPhone. | Prefer the `topBar.items` action. Use `Fab` only when the app is deliberately Android-first, and write down that iPhone shows it too. | [FAB](https://m3.material.io/components/floating-action-button/guidelines) |
+| Collections people choose by photo (products, books, portfolio, projects) | A lazy grid of image tiles, or a carousel of covers; the tile is the tap target. | `Grid` `columns: 2` (`columnsMedium: 3`, `columnsExpanded: 4`); a gallery `columns: 3`, `spacing: 2`; a shelf a horizontal `LazyList` sized so the next cover peeks at 360dp. 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. The same grid renders on iPhone. | [Lazy grids](https://developer.android.com/develop/ui/compose/lists#lazy-grids), [Carousel](https://m3.material.io/components/carousel/guidelines) |
+| Lists and grouped content | List rows with supporting text; group related settings under a header. | `LazyList` of `ListItem` rows for a schedule or a service menu; `Section` (`header`, optional `inset: true`) for a group. Do not wrap each row in a `Card`. 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`. The same structure renders on iPhone. | [Lists](https://m3.material.io/components/lists/guidelines) |
+| On/off, one of a few, pick a date | Switch, segmented button, menu or dialog 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`. Group the rows in a `Section`, not a `Card`. | [Switch](https://m3.material.io/components/switch/guidelines), [Segmented buttons](https://m3.material.io/components/segmented-buttons/guidelines) |
+| A short task on top of a screen | A modal bottom sheet, dismissed by Back or the scrim. | `BottomSheet`. A new destination is a navigation instead. | [Bottom sheets](https://m3.material.io/components/bottom-sheets/guidelines) |
+| Destructive or blocking decision | A dialog that names the action. | `AlertDialog`; confirm or offer undo. | [Dialogs](https://m3.material.io/components/dialogs/guidelines) |
+| Success | A snackbar above the navigation bar. | `ui.snackbar` from the worker. | [Snackbar](https://m3.material.io/components/snackbar/guidelines) |
+| Search | A search bar in the top app bar, or a dedicated search screen. | `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 screen when search starts a new task (`himi docs recipe-search`). | [Search](https://m3.material.io/components/search/guidelines) |
+| Tablets, foldables, wide windows | List and detail side by side from the expanded width class (840dp and wider); a readable column for reading. | `SplitView`, `Grid` `columnsMedium`/`columnsExpanded`, `contentMaxWidth`. Render at 840px or wider and record the choice. | [Adaptive layouts](https://developer.android.com/design/ui/mobile/guides/layout-and-content/adapt-layout) |
+| Type and shape | The Material type scale and shape scale, following the user's font size. | Typography tokens from the built-in ramp, no raw sizes; a `material` overlay in `tokens.json` `idiom` with `"$system"` (Roboto) and Material radii, turned on by `idiom: { policy: "follow-surface" }` in `config.ts`. | [Typography](https://m3.material.io/styles/typography/applying-type) |
+| Touch targets | At least 48×48dp. | Use `Button`/`ListItem`; do not shrink a hit area. | [Accessibility](https://developer.android.com/design/ui/mobile/guides/foundations/accessibility) |
+| Edge to edge | Content draws under the system bars; nothing important sits behind them. | The shell applies the insets; keep the last row clear of `stickyFooter`. | [Edge-to-edge](https://developer.android.com/design/ui/mobile/guides/layout-and-content/edge-to-edge) |
+
+## Settings, copied as props
+
+A settings screen is one `Section` (`inset: true`, `header`), not a stack of `Card`s, and it has no `title1` Text in the body. 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`.
 
-- Drive the installed Android app—not only a phone-width render—through system Back from transient
-  UI, typed input and keyboard submit, completion, touch exploration/TalkBack, enlarged text, dark
-  scheme, error recovery, and compact plus expanded width. Record the result for every declared
-  state in `MOBILE-UX.md`'s acceptance matrix.
-- Check each documented Android variance against `MOBILE-UX.md` and its official source.
+## Plan
+
+In `MOBILE-UX.md` → `## Platform decisions`, fill the Android column of each row from the table
+above: navigation, title, back order, primary action, create/add, lists and grouped content, photo collections,
+controls, sheets and dialogs, search, expanded width, and type/idiom. Give the official URL.
+
+Also plan TalkBack labels on every icon and image, font scale, contrast in light and dark,
+reduced motion, right-to-left, and permission, offline and error states.
+
+## Audit
 
-## Route to official guidance
+Render each primary screen with `--platform android` at a compact width (`--width 360`) and at
+an expanded width (`--width 840`), in light and with `--scheme dark`. Check: the primary action
+in the footer or the top bar, no floating button unless the plan chose it, no hand-drawn
+controls, no heading and no app name added to stand in for the empty top-bar title, a schedule
+made of `ListItem` rows rather than a `Card` per row, products, books and photos as image tiles
+with every image filled and none stretched, a rail that shows part of its next item, a horizontal
+choice row that still shows its last item, and an expanded layout that is either adaptive or recorded as an
+intentional single column.
 
-- [Android design](https://developer.android.com/design)
-- [Adaptive layouts](https://developer.android.com/design/ui/mobile/guides/layout-and-content/adapt-layout)
-- [Accessibility](https://developer.android.com/design/ui/mobile/guides/foundations/accessibility)
+On an installed Android app, drive system Back from every transient UI, typed input and
+keyboard submit, completion, TalkBack, enlarged text, dark theme, error recovery, and compact
+plus expanded width. Record the result in the `MOBILE-UX.md` acceptance matrix; with no device,
+record `himi ux record --status unavailable` with the reason.

package/guides/component-reference.json

@@ -2,7 +2,7 @@
   "_comment": "GENERATED by core/web-embed/authoring/gen-reference.mjs from core/ts/src/schema.ts — do not hand-edit. The schema is the source of truth; regenerate on schema changes.",
   "schemaSource": "core/ts/src/schema.ts",
   "bindingGrammar": "$service:<service>.<path> (worker state) · $item.<field> (list row) · $flag:<key> (feature flag) · $env:<key> (client environment — #1056). Bindings resolve in the text/value props marked 'binding-aware' below — INCLUDING Modifiers token refs — but only `background` and `border.color`, which are the two whose token a binding actually fills: a worker can drive per-item theming (e.g. a game board's per-square color), not just text. `shadow` is NOT binding-aware on any renderer, and a gradient is driven by its own `backgroundGradientPath` prop resolving to a gradient token NAME, not by a binding inside a token ref — so `shadow: { token: \"$item.x\" }` and `backgroundGradient: { token: \"$item.x\" }` keep the sentinel and silently lose the per-item styling. Colour slots split by LEVEL, not by component: inside modifiers a colour is a TokenRef OBJECT ({ token: \"…\" }), inside props it is a bare TokenName STRING — there is no modifiers.color or modifiers.tint (see the 'Token slots' section in component-reference.md). A few input props render the LITERAL and are NOT binding-aware — notably SearchField.placeholder and Chip.label; SearchField.value is live and binding-aware like other content props. Bindings also CANNOT target strict-enum fields (style, size, alignment, severity, presentation, contentMode, …) — those fail at render, not validation. $env: is client-resolved (no worker) and valid in modifiers.hiddenPath and FragmentSlot.casePath ONLY — keys reduceMotion/colorScheme/sizeClass/isRTL/keyboardVisible, e.g. hiddenPath:\"$env:reduceMotion\" or hiddenPath:\"$env:colorScheme==light\", casePath:\"$env:colorScheme\"; unknown key fails open (shown / defaultCase).",
-  "componentCount": 88,
+  "componentCount": 89,
   "notImplementedComponents": [
     "Text",
     "Icon",
@@ -97,6 +97,15 @@
       ],
       "propsSource": "export interface ErrorStateProps {\n  /** Default `\"server\"`. An unknown value is treated as `\"server\"`. */\n  variant?: \"server\" | \"offline\" | \"permission\" | \"signIn\";\n  /** `$service:` binding that selects the variant at runtime; wins over `variant`. */\n  variantPath?: string;\n  title?: string;\n  body?: string;\n  /** The CTA's action. Absent → no button. */\n  cta?: Action;\n  ctaLabel?: string;\n  /** `\"screen\"` (default, ~96px from the top) or `\"section\"` (~24px). */\n  placement?: \"screen\" | \"section\";\n}"
     },
+    {
+      "name": "QrCode",
+      "category": "Core",
+      "propsType": "QrCodeProps",
+      "bindings": [
+        "valuePath"
+      ],
+      "propsSource": "export interface QrCodeProps {\n  /** Literal payload (UTF-8). One of `value` / `valuePath` is required. */\n  value?: string;\n  /** `$service:` / `$item.` binding for the payload; wins over `value` once it resolves to a\n   *  non-empty string (until then — no worker yet, an empty field — `value` draws). */\n  valuePath?: string;\n  /** Side length (pt/dp/px), quiet zone included. Default `160`. */\n  size?: number;\n  /** Default `\"M\"`. A literal over the level's capacity is a validator error. */\n  errorCorrection?: \"L\" | \"M\" | \"Q\" | \"H\";\n  /** Module colour token. Default `\"textPrimary\"`. */\n  color?: string;\n  /** Background colour token. Default `\"surfacePrimary\"`. */\n  background?: string;\n  /** Light margin, in modules. Default `4` (the spec minimum). */\n  quietZone?: number;\n}"
+    },
     {
       "name": "Text",
       "category": "Core",
@@ -780,8 +789,11 @@
       "name": "Section",
       "category": "Structure & disclosure",
       "propsType": "SectionProps",
-      "bindings": [],
-      "propsSource": "export interface SectionProps {\n  header?: string;\n  footer?: string;\n  children?: Component[];\n  inset?: boolean;\n}"
+      "bindings": [
+        "header",
+        "footer"
+      ],
+      "propsSource": "export interface SectionProps {\n  /** Section caption — binding-aware (\"$service:\") on web, iOS and Android. */\n  header?: string;\n  /** Section caption — binding-aware (\"$service:\") on web, iOS and Android. */\n  footer?: string;\n  children?: Component[];\n  inset?: boolean;\n}"
     },
     {
       "name": "DisclosureGroup",

package/guides/component-reference.md

@@ -3,7 +3,7 @@
 > GENERATED from `core/ts/src/schema.ts` by `core/web-embed/authoring/gen-reference.mjs`.
 > The schema is the source of truth — regenerate on schema changes; do not hand-edit.
 
-**88 core component types.** Every component body is `{ "package": "himalaya", "type": "<Type>", "props": { … } }`.
+**89 core component types.** Every component body is `{ "package": "himalaya", "type": "<Type>", "props": { … } }`.
 Binding grammar: `$service:<service>.<path>` (worker state) · `$item.<field>` (list row template) · `$flag:<key>` (feature flag) · `$env:<key>` (client environment — #1056).
 Bindings resolve in the text/value props marked **binding-aware** below — **including two `Modifiers` token refs**, `background` and `border.color`, which are the only two whose token a binding actually fills: a worker can drive per-item **theming** (e.g. a game board's per-square color, `background: { token: "$item.bg" }`), not just text content. `shadow` and `backgroundGradient` are `TokenRef`s but are **not** binding-aware on any renderer — `shadow: { token: "$item.x" }` keeps the sentinel as a literal token name and silently loses the per-item styling, and a gradient is driven by its own `backgroundGradientPath` prop resolving to a gradient token NAME, not by a binding inside a token ref.
 `$env:` is **client-resolved** (no worker) and valid in `modifiers.hiddenPath` and `FragmentSlot.casePath` **only** — keys `reduceMotion` / `colorScheme` / `sizeClass` / `isRTL` / `keyboardVisible` (an on-screen keyboard is up — `hiddenPath: "$env:keyboardVisible"` hides a header while typing), with an optional `==`/`!=` comparison (e.g. `hiddenPath: "$env:reduceMotion"`, `hiddenPath: "$env:colorScheme==light"`, `casePath: "$env:colorScheme"`). An unknown key fails open (shown / `defaultCase`).
@@ -38,6 +38,7 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 | `Spacer` | Core | — |
 | `EmptyState` | Core | — |
 | `ErrorState` | Core | `variantPath` |
+| `QrCode` | Core | `valuePath` |
 | `Text` | Core | `text` |
 | `Image` | Core | `url`, `initials`, `contentDescription` |
 | `Icon` | Core | — |
@@ -82,7 +83,7 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 | `Popover` | Overlays & menus | `presentedPath` |
 | `Chip` | Chips & selection | `selectedPath`, `tokenPath` |
 | `ChipsInput` | Chips & selection | `valuesPath` |
-| `Section` | Structure & disclosure | — |
+| `Section` | Structure & disclosure | `header`, `footer` |
 | `DisclosureGroup` | Structure & disclosure | `expandedPath` |
 | `LabeledContent` | Structure & disclosure | — |
 | `Label` | Structure & disclosure | — |
@@ -120,7 +121,7 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 
 These props are accepted by the schema and pass validation, but the named platform's renderer never reads them — they silently do nothing (no warning, no log). Prefer a prop NOT listed here, or drive the behaviour from a worker.
 
-**Scope: 7 of 88 components, all of them android / web / ios-only** — every other component/platform pair reads every prop it decodes. The list splits in two, and the halves mean different things:
+**Scope: 7 of 89 components, all of them android / web / ios-only** — every other component/platform pair reads every prop it decodes. The list splits in two, and the halves mean different things:
 
 - **`category` (2: `MediaPlayer`, `TimeGrid`)** — the prop changes the component's *kind*. These genuinely are **not implemented**: an overlay renders always-visible inline, so the component does not do the job its name implies. Check the row's note for a working alternative.
 - **`styling` (5: `Text`, `Icon`, `WebView`, `Video`, `PdfView`)** — the component itself **works**; only the listed prop is inert. Use the component; just do not depend on that one prop.
@@ -438,6 +439,28 @@ export interface ErrorStateProps {
 }
 ```
 
+#### QrCode
+
+```ts
+export interface QrCodeProps {
+  /** Literal payload (UTF-8). One of `value` / `valuePath` is required. */
+  value?: string;
+  /** `$service:` / `$item.` binding for the payload; wins over `value` once it resolves to a
+   *  non-empty string (until then — no worker yet, an empty field — `value` draws). */
+  valuePath?: string;
+  /** Side length (pt/dp/px), quiet zone included. Default `160`. */
+  size?: number;
+  /** Default `"M"`. A literal over the level's capacity is a validator error. */
+  errorCorrection?: "L" | "M" | "Q" | "H";
+  /** Module colour token. Default `"textPrimary"`. */
+  color?: string;
+  /** Background colour token. Default `"surfacePrimary"`. */
+  background?: string;
+  /** Light margin, in modules. Default `4` (the spec minimum). */
+  quietZone?: number;
+}
+```
+
 #### Text
 
 ```ts
@@ -1542,7 +1565,9 @@ export interface ChipsInputProps {
 
 ```ts
 export interface SectionProps {
+  /** Section caption — binding-aware ("$service:") on web, iOS and Android. */
   header?: string;
+  /** Section caption — binding-aware ("$service:") on web, iOS and Android. */
   footer?: string;
   children?: Component[];
   inset?: boolean;

package/guides/designing-himi-screens.md

@@ -18,6 +18,35 @@ prescriptive layer that sits **above** the wiring guide: `himi docs tier-5-add-a
 > `.agents/skills/himalaya/examples/stocks-dashboard.descriptor.json` into the app — a
 > fully-composed screen to study.
 
+**A phone screen, before anything below.** Read `himi docs ios-ux` and `himi docs android-ux` too;
+they decide what a phone screen looks like, and this guide decides how to compose it.
+
+- **The title lives in the bar, not the body.** Set the screen's `title`; the shell draws it. Do
+  not open the body with the screen title, the app name or a greeting as `largeTitle`/`title1`
+  text. `himi render` does not draw the bar, so a PNG that starts with content is correct.
+- **A collection is rows, not a card per item.** A schedule, a service menu, a session list or a
+  settings group is `ListItem` rows — in a root `LazyList`, or in one `Section` with `inset: true`
+  and a `header`. Time, price, coach or duration go in the row's `subtitle`/`trailing`; a small
+  action (Book, Full) goes in `trailing`. One featured object may be a single `Card`.
+- **When people choose by the photo, the photo leads.** Products, books, a portfolio and projects
+  are image tiles, not rows with a small thumbnail: a `Grid` with `columns: 2` (`columnsMedium: 3`,
+  `columnsExpanded: 4`) for products and projects, `columns: 3` with `spacing: 2` and no captions
+  for a photo gallery, and a horizontal `LazyList` of covers for each shelf. A tile is one `Image`
+  (`fillWidth: true`, a fixed `aspectRatio`, `contentMode: "fill"`, `placeholder`,
+  `contentDescription`) with the name and price as text under it, and the whole tile is the tap
+  target (`modifiers.onTap`). No `Card` and no button on each tile. A collection without photos
+  stays rows.
+- **Choices that may not fit go sideways.** Days and times are a `LazyList` with
+  `horizontal: true`, so the last chip stays reachable at 390 points. Size a rail of covers or
+  cards so part of the next one shows at 390 points (a cover about 110 points wide, a card about
+  160), or nothing tells the reader the rail scrolls.
+- **A detail screen opens with its photos.** A product, a book or a project starts with its image
+  (a paged `Carousel` when there are several), edge to edge with a fixed height: the root `VStack`
+  has no padding, the image is its first child, and the name, price and options follow in a
+  `VStack` that carries the 16-point gutter.
+- **The step that finishes the task sits in `stickyFooter`** — one primary `Button`, not a button
+  inside the last card.
+
 ---
 
 ## 1. The materials at a glance
@@ -58,7 +87,8 @@ Screen root gets consistent padding — `padding: { leading: 16, trailing: 16,
 `surfacePrimary` root reads well. Tight, even spacing is most of what makes a screen look "designed."
 
 ### Typography — use the scale, don't invent
-`title1` for the one screen heading, `title3` for a sub-heading/stat, `body` for content, `caption`
+`title1` for a heading inside the body that is not the screen title (a featured card, an empty
+state, an onboarding page — the screen title itself is the screen's `title` field), `title3` for a sub-heading/stat, `body` for content, `caption`
 for secondary/meta, `bodyEmphasis` when you need weight inside body copy. Do **not** introduce new
 sizes or weights inline to "make it bigger" — that's a token change, deliberated once, not a per-screen
 decision.
@@ -190,10 +220,10 @@ tiles; `Card` to group a related cluster onto a raised `surfaceSecondary`; `Sect
 group; `Divider` for a hairline separation; `Spacer` to push apart within a row; `SplitView` for
 responsive master/detail. *Reach for `Card` to cluster, not to wrap every single element.*
 
-**Lists & collections** — `LazyList` for long/unbounded scrolls (virtualized); `Grid` for a 2-up gallery
-(`columns: 1, columnsMedium: 2`); `Table` for tabular rows; `Carousel`/`Pager` for swipeable panels;
+**Lists & collections** — `LazyList` for long/unbounded scrolls (virtualized); `Grid` for photo tiles
+(`columns: 2, columnsMedium: 3` for products, `columns: 3` for a photo gallery); `Table` for tabular rows; `Carousel`/`Pager` for swipeable panels;
 `Timeline` for chronological events. Compose rows as `ListItem` / `LabeledContent` / `DisclosureGroup`
-cells inside a `Card([VStack(spacing: 0)])`.
+cells in one `Section` with `inset: true` (or directly in a root `LazyList`) — never one `Card` per row.
 > For a feed/list *screen*, put a vertical worker-bound `LazyList` directly in a plain root
 > `VStack`, as the screen's only bound list: the root carries padding and a literal background at
 > most, is leading-aligned, starts with a child that is always shown, and holds no `Spacer` or
@@ -233,7 +263,8 @@ long-form Ricos content rather than flattening it into text rows.*
 **Inputs & forms** — field controls: `TextField` (with `keyboard`/`autoCapitalization`/`secure`),
 `SearchField`, `Toggle`, `Stepper`, `Slider`, `SelectionControl` (checkbox/radio),
 `Picker`/`WheelPicker`, `DatePicker`, `ColorPicker`, `OtpInput`, `ChipsInput`. *Reach for `Toggle` for
-on/off, `SelectionControl` for pick-from-set — not a row of `Button`s.*
+on/off, `SelectionControl` for pick-from-set — not a row of `Button`s.* A `Toggle`'s `label` is the
+row drawn beside the switch; a `ListItem` `title` with the same word paints it a second time.
 
 **Search** — use a dedicated search screen by default when search starts from a broader context
 (such as Home or a catalog); keep search inline when it only filters the list already on screen.
@@ -293,7 +324,7 @@ Use a live `title` binding to announce “Adding to cart” while pending; `load
 
 **Navigation** — `Tabs` / `SegmentedControl` to switch peer views; `Pager` + `PageControl` for
 full-width swipe; `StepIndicator` for a wizard's progress; `CollapsingHeader` for a large-title-to-inline
-scroll. *Reach for `SegmentedControl` for 2–4 in-content modes; `Tabs`/tab-bar for top-level sections.*
+scroll. *Reach for `SegmentedControl` for 2–4 in-content modes; `Tabs`/tab-bar for top-level sections.* Each option is `{ id, label }`. `label` is required — `title` on an option fails native decode and drops the whole screen. `title` belongs on `Button` and `ListItem`.
 > **`Pager` sizes each page to its natural content height** (it doesn't stretch to fill), and multi-line
 > text inside a page **truncates** — so onboarding/carousel slides need *short* titles + an explicit
 > `maxLines`, and you can't vertically center a slide with a `spacer()` inside the page (put the spacer
@@ -317,7 +348,9 @@ dense row); `ProgressBar` for determinate progress, `ActivityIndicator` for inde
 a single dial metric. *Use a `Badge` for a count, a `Tag` for a category — they aren't interchangeable.*
 
 **Media** — `Image` (`fillWidth`, `height`, always `contentDescription`); `Video`/`Lottie`/`Rive` for
-motion media; `Map` for location; `Avatar` for a person; `WebView` only when native can't express it.
+motion media; `Map` for location; `Avatar` for a person; `QrCode` to share a link, ticket or invite
+as a code generated on the device (bind `valuePath`; keep the payload short, since a literal over the
+level's capacity fails validation); `WebView` only when native can't express it.
 *Fill-width media gets a `cornerRadius` so it doesn't fight the card edges.*
 For audio apps, keep playback UI in SDUI and call `@himalaya/media-playback` from the Tier-5 worker:
 compose artwork with `Image`, transport controls with icon buttons, scrubbing with `Slider`, buffering
@@ -337,9 +370,10 @@ Concrete patterns lifted from real usage:
 - **Row with a leading label and trailing detail** — `hstack({ spacing: 8, children: [ icon, text, spacer(), trailingText ] })`. The `spacer()` does the push; don't hand-pad.
 - **Fill-width controls share a row** — put fill-width controls in **one** `HStack` and let them share it (weight/flex), rather than stacking `fillMaxWidth` elements. This is a real iOS↔Android parity requirement, not a preference — a full-width control alone in an HStack renders differently across platforms.
 - **A screen that owns its top bar (search beside back)** — set `topBar: { leading: "none" }` and put the row in `stickyHeader`: `hstack([ iconButton({ icon: "arrow_left", accessibilityLabel: "Back", action: { actionId: "nav.back", presentation: "back" } }), withModifiers(textField({ placeholder: "Search", … }), { weight: 1 }) ])`. With **both** set, every shell draws no bar and no back control of its own (iOS hides the system bar, Android floats no chevron and reserves no band, web hides its bar on every look), so the row is the only top bar. `leading: "none"` without a `stickyHeader` keeps the bar's title and trailing actions but drops the back control (and the hamburger, for that screen). System back — hardware, gesture, edge swipe, browser — still pops. Any other `leading` value keeps today's chrome; demo: `gallery_search_topbar`, linked from the gallery's "Lists & data".
-- **Cell list** — `card([ vstack({ spacing: 0, alignment: "leading", children: [ …ListItem cells… ] }) ])`. `spacing: 0` because the cells own their own dividers/padding.
+- **Cell list** — one `Section` with `inset: true` and a `header`, its children the `ListItem` cells; the cells own their own dividers and padding. A schedule, a service menu and a session list are this shape too, not a `Card` around each item.
+- **Photo tile** — `vstack({ spacing: 6, alignment: "leading", children: [ image({ url, fillWidth: true, aspectRatio: 0.8, contentMode: "fill", placeholder: "surfaceSecondary", contentDescription }) + cornerRadius 8, text(name, "body"), text(price, "callout", { color: "textSecondary" }) ] })` with `modifiers.onTap` on the stack, inside `grid({ columns: 2, columnsMedium: 3, columnsExpanded: 4, spacing: 12 })`. A shelf is the same tile at a fixed `width` (about 110) in `lazyList({ horizontal: true, spacing: 12 })`.
 - **Overlay** — `zstack({ alignment: "center", children: [ backdropImage(cornerRadius 12), withModifiers(label, { padding, background: { token: "accentPrimary" }, cornerRadius: 10 }) ] })`.
-- **Responsive** — `grid({ columns: 1, columnsMedium: 2, spacing: 12 })` for 1-up on phone / 2-up on tablet; `splitView({ primary, detail, primaryMaxWidth: 280 })` for master/detail that stacks on a phone; set `contentMaxWidth` in tokens so wide surfaces keep a readable column instead of running edge-to-edge.
+- **Responsive** — `grid({ columns: 1, columnsMedium: 2, spacing: 12 })` for wide cards, 1-up on phone / 2-up on tablet (photo tiles start at 2 on a phone); `splitView({ primary, detail, primaryMaxWidth: 280 })` for master/detail that stacks on a phone; set `contentMaxWidth` in tokens so wide surfaces keep a readable column instead of running edge-to-edge.
 - **Centered separator, not a flanked divider** — the classic "—— or ——" needs each `divider()` to take equal remaining width, and the HStack row-share only kicks in for controls with an intrinsic fill. **A bare `divider()` inside an HStack is a column separator, not a flanking line**: iOS, macOS, Android, web and React Native all draw it as a thin vertical rule the height of the row that takes no share of the width, which is right for a stats row (`12 | 340 | 87`) and wrong for "—— or ——". For "—— or ——", use a **centered caption**: `hstack({ children: [spacer(), text("or continue with", "caption", { color: "textSecondary" }), spacer()] })`, optionally over a single full-width `divider()`.
 
 > **Intrinsic-fill controls grab the row.** `Button` and `TextField` have an intrinsic FILL, so the next four idioms are about NOT letting that surprise you (they were the papercuts every off-repo app hit):
@@ -588,7 +622,7 @@ nicety. Don't animate everything: if every element moves, nothing reads as impor
   A screen full of `id`s and no `accessibility_label`s is testable but unusable with VoiceOver/TalkBack.
   It may be bound to worker state with `$service:<service>.<path>`; the web renderer keeps the
   resulting `aria-label` current as that state changes.
-- **Tap targets** stay comfortably large (don't shrink `button`/`icon` hit areas below ~44pt).
+- **Tap targets** stay comfortably large: at least 44pt on iOS and 48dp on Android — don't shrink `button`/`icon` hit areas below that.
 - **Contrast** comes from the token roles — pair `textPrimary`/`textSecondary` with the right surface,
   and provide the `highContrast` scheme value for load-bearing colors.
 - **Reduced motion** — §6.
@@ -670,6 +704,7 @@ Run this punch list on the screen (it's also a good reviewer checklist):
 - [ ] Verified in **both** light and dark (and highContrast for load-bearing color)?
 - [ ] RTL-safe — leading/trailing alignment + logical insets throughout?
 - [ ] Kit-clean — no hardcoded look a kit would override; `material`/gradient/background precedence respected?
+- [ ] Platform-clean — the shell draws the tab bar, title and Back (none redrawn in the body); the primary action sits in `stickyFooter` or a trailing `topBar.items` entry, not a `Fab` an iPhone would also show; switches, segmented choices, pickers, sheets and alerts are the native components (`himi docs ios-ux`, `himi docs android-ux`)?
 - [ ] Fast (§7b) — long or paged lists at the scroll root, stable row ids, `nav` on taps whose destination is fixed, short rails, fixed-size row images?
 
 ---
@@ -679,7 +714,7 @@ Run this punch list on the screen (it's also a good reviewer checklist):
 The demo gallery's `layout()` is a compact model of the
 principles:
 
-- **Type scale, not sizes** — `title1` heading, `body` content, `caption` secondary, colored via
+- **Type scale, not sizes** — `title1` for a heading inside a card, `body` content, `caption` secondary, colored via
   `textPrimary`/`textSecondary`/`accentPrimary` tokens (never hex), `maxLines: 1` to truncate.
 - **Card = cluster** — related copy grouped in `card([ vstack({ spacing: 4, alignment: "leading" }) ])`
   on `surfaceSecondary`, not scattered.

package/guides/getting-started.md

@@ -33,7 +33,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

package/guides/hhp.md

@@ -213,10 +213,12 @@ A screen may also carry `params` (the navigation input a device opens it with, u
 himi fidelity --content <dir> [--screen a,b] [--variant light,dark,rtl,tablet] [--ios <udid>] [--android <serial>] [--ios-tablet <udid>] [--android-tablet <serial>] [--app-id <id>] [--release <id>] [--serve <port>] [--no-native] [--json] [--post-pr <n>]
 ```
 
+`rtl` runs only when config.ts `locale.default` or `locale.translations` names a right-to-left language the Player supports (today `he`), and `locale.pin` does not pin a left-to-right default. A language picked inside the app also outranks the device, and the command cannot read or reset it: on a device where the app's language was changed in the Player, reinstall the Player before an `rtl` run. The Player follows the app's locale, so an app that ships no such language stays left-to-right on a Hebrew device, and comparing it with a mirrored page would only report that. Otherwise every `rtl` row is reported `skipped` with the reason.
+
 For each screen and variant (`light`, `dark`, `rtl`, `tablet`), the command does four things:
 
 1. **Captures the mockup.** It draws the page in Chromium at the variant's width. Dark mode is drawn by emulating `prefers-color-scheme`. RTL is drawn by setting `dir=rtl` on the page.
-2. **Captures the web render** from the app's recorded data, as `himi render` does by default. Native frames come from Himi Player on the devices you pass: `--ios <udid>` and `--android <serial>`, plus `--ios-tablet` and `--android-tablet` for the tablet variant. Only those devices are touched. For each variant the command sets dark or light appearance and, for `rtl`, the Hebrew language (iOS `AppleLanguages`, Android per-app locale, API 33+). It opens `himi://app/<app>/screen/<screen>` and captures once two frames match. Every setting it changed is restored afterwards, also on Ctrl-C. A variant with no device is reported `skipped`, never passed. Without `--release <id>` or `--serve <port>` the Player shows the app's **live** release, not your working copy. `--serve <port>` serves the working copy on `127.0.0.1:<port>` as `himi run` does, so native and web render the same release. The Player reads a local origin only from a Debug build that compiled it in (see [View your package on a device](himi-player-implementation.md#view-your-package-on-a-device)): build it with `HIMALAYA_API_BASE_URL_INFO=http://127.0.0.1:<port>` on iOS and `-PhimalayaDevServeBaseUrl=http://10.0.2.2:<port>` on Android. An iOS device whose Player reads another origin is skipped with the rebuild to run. Android's origin cannot be read back from the installed app, so check that build yourself. A screen that declares `params` is skipped natively for now, because the Player's deep link does not carry them yet. On a fresh iOS simulator, open one `himi://` link by hand first and accept iOS's "Open in Himi Player?" prompt: the command cannot answer it, and until it is accepted every iOS capture shows the prompt.
+2. **Captures the web render** from the app's recorded data, as `himi render` does by default. Native frames come from Himi Player on the devices you pass: `--ios <udid>` and `--android <serial>`, plus `--ios-tablet` and `--android-tablet` for the tablet variant. Only those devices are touched. For each variant the command sets dark or light appearance and, for `rtl`, the app's right-to-left language (iOS `AppleLanguages`, Android per-app locale, API 33+). It opens `himi://app/<app>/screen/<screen>` and captures once two frames match. Every setting it changed is restored afterwards, also on Ctrl-C. A variant with no device is reported `skipped`, never passed. Without `--release <id>` or `--serve <port>` the Player shows the app's **live** release, not your working copy. `--serve <port>` serves the working copy on `127.0.0.1:<port>` as `himi run` does, so native and web render the same release. The Player reads a local origin only from a Debug build that compiled it in (see [View your package on a device](himi-player-implementation.md#view-your-package-on-a-device)): build it with `HIMALAYA_API_BASE_URL_INFO=http://127.0.0.1:<port>` on iOS and `-PhimalayaDevServeBaseUrl=http://10.0.2.2:<port>` on Android. An iOS device whose Player reads another origin is skipped with the rebuild to run. Android's origin cannot be read back from the installed app, so check that build yourself. A screen that declares `params` is skipped natively for now, because the Player's deep link does not carry them yet. On a fresh iOS simulator, open one `himi://` link by hand first and accept iOS's "Open in Himi Player?" prompt: the command cannot answer it, and until it is accepted every iOS capture shows the prompt.
 3. **Scores mockup↔web** with ImageMagick SSIM, globally and per tile. The worst tile says where the screens differ most.
 4. **Asks a fresh model** two questions, using the repo's fidelity judge prompt. The model never ran in the session that wrote the app.
    - **Design:** does WEB look like the MOCKUP? This judges the port.

package/guides/himi-json-output.md

@@ -83,10 +83,20 @@ publication readiness or bound metadata not yet supplied to the final push.
 | --- | --- |
 | `invalid_usage` | Missing, repeated or unsupported checker arguments. |
 | `payment_review_unreadable` | The collected source evidence or site-bound payment review cannot be read or verified. |
-| `payment_decision_required` | Payment intent, readiness evidence or an explicit owner decision remains unresolved before scaffolding. Selecting connect-provider waits for setup and a new review. |
+| `payment_decision_required` | Payment intent, site-bound evidence, target checkout compatibility or a required owner decision remains unresolved before scaffolding. Selecting connect-provider waits for setup and a new review. Unknown payment readiness alone does not refuse a reviewed, supported existing checkout. |
 
 The checker validates recorded evidence and decisions; it does not independently
 verify merchant readiness or create transactions. General publication remains unchanged.
+Newly collected schema-2 payment reviews require checkout compatibility evidence
+for every online-paid flow. Legacy schema-1 completed ready reviews remain accepted
+without that field.
+
+Successful checks include a `warnings` array. When an existing paid flow proceeds
+with unverified payment readiness and supported target checkout, it contains
+`{ code: "payment_readiness_unverified", flowId, message }` for that flow. This is
+advisory: it does not mean payments are disconnected, does not require an owner
+decision and does not certify a successful purchase. Other successful reviews
+return an empty array.
 
 ## `himi one-app validate-identity` codes
 

package/guides/himi-skill.md

@@ -56,7 +56,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

package/guides/index.json

@@ -1,7 +1,7 @@
 {
   "_comment": "AUTO-GENERATED by tools/authoring-kit/bundle.mjs — DO NOT EDIT. Regenerate with: npm run authoring:gen",
   "schemaStamp": {
-    "componentCount": 88,
+    "componentCount": 89,
     "schemaSource": "core/ts/src/schema.ts"
   },
   "portalUrl": "https://apps.wix.com/_api/himi-serve/docs",