@getrheo/rheo-skill 2.2.0 → 2.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @getrheo/rheo-skill
 
-Current release: **`2.1.0`** on npm. Public source: [getrheo/rheo-skill](https://github.com/getrheo/rheo-skill) (mirrored from this private monorepo via `pnpm extract:oss-repos`).
+Current release: **`2.3.0`** on npm (`PLATFORM_SDK_VERSION` in `scripts/publish-package-registry.mjs`). Public source: [getrheo/rheo-skill](https://github.com/getrheo/rheo-skill) (mirrored from this private monorepo via `pnpm extract:oss-repos`).
 
 Source and build tooling for the **`rheo`** agent skill — a single, self-contained
 skill with two sub-skills:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrheo/rheo-skill",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "type": "module",
   "description": "Rheo agent skill — SDK install guidance and flow manifest import tooling.",
   "main": "./src/index.ts",
@@ -9,8 +9,8 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@getrheo/contracts": "2.2.0",
-    "@getrheo/flow-runtime": "2.2.0",
+    "@getrheo/contracts": "2.4.0",
+    "@getrheo/flow-runtime": "2.4.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {

package/rheo/SKILL.md

@@ -3,7 +3,7 @@ name: rheo
 description: Work with Rheo, the headless onboarding/paywall flow engine for mobile apps. Use when a user wants to install or wire the Rheo SDK (React Native, Expo, or SwiftUI), follow Rheo SDK best practices, configure integrations (RevenueCat, AppsFlyer), wire auth/permissions/terminal callbacks, OR import/migrate an existing mobile flow into a compliant Rheo FlowManifest and validate it. Routes to the `rheo-best-practices` and `rheo-flow-import` sub-skills.
 compatibility: Requires Node.js 20+. rheo-flow-import scripts are fully self-contained (no install step). Internet access fetches the latest Manifest Agent Profile; a bundled fallback works offline.
 metadata:
-  rheo-version: "2.2.0"
+  rheo-version: "2.4.0"
   manifest-schema-version: "7"
 ---
 

package/rheo/rheo-flow-import/SKILL.md

@@ -57,7 +57,7 @@ All `<manifest.json>` / `<flow-spec.json>` paths and outputs resolve from the **
 - **Choice inputs:** `single_choice`/`multiple_choice` require `fieldKey` (snake_case), `children` (≥2 option stacks), `optionBindings` (one per option, `rootLayerId` = child stack `lyr_*` id), and `branching` (`{ "enabled": false, "conditions": [] }` when no branches). Never `"options"`/`"choices"`.
 - **Styling:** when the audit reports colors, populate `manifest.theme` and layer `style` (including `style.color` on every text layer and nested button label). No black-and-white defaults when color evidence exists.
 - **Gradients:** map `LinearGradient`/gradient stops to `screen.containerStyle.backgroundFill.color` as a `linear-gradient(...)` CSS string.
-- **Carousels:** pager/carousel evidence (`infoSteps`, horizontal pager, `pagingEnabled`) → `kind: "carousel"`, one slide per page, swipe-only (no in-pager buttons). See [references/carousel-import.md](references/carousel-import.md).
+- **Carousels:** pager/carousel evidence (`infoSteps`, horizontal pager, `pagingEnabled`) → `kind: "carousel"`, one slide per page; swipe by default, or a `button` with `action.kind: "advance_carousel"` when the source has an explicit Next control. See [references/carousel-import.md](references/carousel-import.md).
 - **Fonts:** custom fonts go in `rheo-import.fonts.json` under `assets/fonts/` and `manifest.theme.fontFamily`; **never** in `rheo-import.assets.json`. See [references/font-import.md](references/font-import.md).
 - **Localization:** resolve **default-locale** strings into every `text.default` — never raw translation keys. Set `manifest.defaultLocale`. See [references/localization-import.md](references/localization-import.md).
 - **Animations:** map motion from the audit only when intake Q6 is yes and the plan includes animations ([references/animation-import.md](references/animation-import.md)); otherwise omit all `animations`, `stagger`, `restingMotion`.

package/rheo/rheo-flow-import/references/capabilities.md

@@ -26,6 +26,7 @@ Every layer `kind` accepted by the manifest:
 - `multiple_choice`
 - `text_input`
 - `scale_input`
+- `wheel_picker`
 - `oauth_provider`
 - `oauth_login`
 - `email_password_auth`
@@ -34,10 +35,17 @@ Every layer `kind` accepted by the manifest:
 - `carousel`
 - `hyperlink`
 - `checkbox`
+- `conditional`
 
 Container layers that **must** include a `children` array (or `slides` for carousel): `stack`, `carousel`,
 `button`, `back_button`, `hyperlink`, `single_choice`, `multiple_choice`, `oauth_login`,
-`oauth_provider` (custom variant), `email_password_auth`, `email_password_field`, `email_password_submit`.
+`oauth_provider` (custom variant), `email_password_auth`, `email_password_field`, `email_password_submit`,
+`conditional`.
+
+`conditional` picks which of its child stacks renders: ordered `cases[]` (each with a `DecisionExpr`
+and a `rootLayerId`) plus a required `elseRootLayerId`. Every bound id must be a distinct direct child
+`stack`. Cases may only read fields answered above the conditional, every case needs at least one rule
+before publish, and the one-input limit applies per active path so sibling branches may each own an input.
 
 ## Button / back_button variants
 
@@ -59,11 +67,13 @@ Valid `action.kind` values on `button` layers:
 - `request_os_permission`
 - `play_media`
 - `request_app_review`
+- `advance_carousel`
 
 - `FlowGraphNodeJumpTarget` (`scr_*` | `dec_*` | `surf_*`): `go_to_step.screenId`, choice `branching.conditions[].goTo`, loader/lottie/video `onComplete` when mode is `screen`, and `request_os_permission` outcomes (except `continue`/`end`).
 - `go_back_one_screen` and `back_button` accept optional `fallbackScreenId` (`scr_*` only).
 - `request_os_permission` requires `permissionKey` and `outcomes` (`granted`/`denied`/`blocked`).
 - `play_media` requires `targetLayerIds` (≥1) pointing at Lottie/video layers on the same screen.
+- `advance_carousel` requires `targetLayerId` (exactly one `carousel` layer on the same screen) and takes optional `onLast` (`noop` default, or `complete` to finish the carousel when already on the last slide).
 - `back_button` takes **no** `action` (back navigation is built in).
 
 ## OS permission keys
@@ -95,7 +105,7 @@ Valid `permissionKey` values for `request_os_permission`:
 
 ## Inputs and auth
 
-- `text_input` types: `plain`, `email`, `phone`, `url`, `multiline`.
+- `text_input` types: `plain`, `email`, `phone`, `url`, `number`, `multiline`.
 - `text_input` classification: `safe`, `sensitive`.
 - `oauth_login` preset providers: `github`, `google`, `apple`.
 - `email_password_auth` modes: `sign_in`, `sign_up` (sign_up requires email + password + confirm fields).

package/rheo/rheo-flow-import/references/carousel-import.md

@@ -2,15 +2,25 @@
 
 Use when the source flow has an **in-screen pager** (`infoSteps`, `currentInfoStep`, horizontal `FlatList` / `PagerView`, dot indicators).
 
-## Rheo carousel behavior (swipe-only)
+## Rheo carousel behavior (swipe by default)
 
-- Users move between slides by **swiping** (horizontal scroll with snap).
+- Users move between slides by **swiping** (horizontal scroll with snap). Swipe is always available.
 - Optional **`pageControl`** adds dot indicators — not buttons.
-- There is **no** Next / Continue button on the carousel layer in the manifest or at runtime.
-- On the **last slide** (when `loop` is false and there are 2+ slides), swiping to that slide emits a carousel completion so `screen.next` can run.
+- On the **last slide** (when `loop` is false and there are 2+ slides), arriving at that slide emits a carousel completion so `screen.next` can run.
 - **Single-slide** carousels do not auto-complete; add a `regions.footer` **Continue** (or other) button to advance the flow.
 - **`loop: true`** carousels never auto-complete; pair with a separate screen-level CTA when the flow should move on.
 
+## Optional Next button (`advance_carousel`)
+
+A button may page the carousel when the source screen genuinely has a Next control:
+
+- Action shape: `{ "kind": "advance_carousel", "targetLayerId": "<carousel layer id>", "onLast": "noop" | "complete" }`.
+- `targetLayerId` must name **exactly one** `carousel` layer on the **same screen**.
+- `onLast` is optional and defaults to `"noop"` (stay on the last slide). Use `"complete"` when tapping Next on the last slide should finish the carousel and follow `screen.next`.
+- `loop: true` and single-slide carousels never complete through this action — they wrap or do nothing.
+- Advancing from second-to-last to last emits carousel completion just like a swipe, so a `"complete"` `onLast` only matters when the user is **already** on the last slide.
+- Runtime support: **Web and React Native**. Flutter and SwiftUI decode the action but do nothing on tap, so do not rely on it for flow exit on those platforms — use a `continue` button instead.
+
 ## Manifest shape
 
 - One `kind: "carousel"` in `regions.body` (or inside a body stack).
@@ -24,8 +34,9 @@ Use when the source flow has an **in-screen pager** (`infoSteps`, `currentInfoSt
 | Pager pages | `carousel.slides[]` |
 | Dot indicators | `pageControl` only |
 | Swipe between pages | Default — no extra buttons |
-| Footer that only increments pager index | **Omit** — not `regions.footer` |
-| Footer / CTA that exits to **next route** | `regions.footer` with `continue` / `go_to_step`, or rely on last-slide swipe completion + `screen.next` |
+| Footer that only increments pager index, with no visible Next affordance | **Omit** — swipe already covers it |
+| Explicit **Next** button in the source pager | `button` with `advance_carousel` targeting the carousel |
+| Footer / CTA that exits to **next route** | `regions.footer` with `continue` / `go_to_step`, or rely on last-slide completion + `screen.next` |
 
 ## Example (swipe + dots)
 
@@ -57,8 +68,54 @@ Use when the source flow has an **in-screen pager** (`infoSteps`, `currentInfoSt
 }
 ```
 
+## Example (explicit Next button)
+
+```json
+{
+  "regions": {
+    "body": {
+      "kind": "stack",
+      "direction": "vertical",
+      "children": [
+        {
+          "id": "lyr_car_intro",
+          "kind": "carousel",
+          "slides": [
+            {
+              "kind": "stack",
+              "direction": "vertical",
+              "children": [
+                { "kind": "text", "text": { "default": "Slide 1" }, "style": { "color": "#111111" } }
+              ]
+            },
+            {
+              "kind": "stack",
+              "direction": "vertical",
+              "children": [
+                { "kind": "text", "text": { "default": "Slide 2" }, "style": { "color": "#111111" } }
+              ]
+            }
+          ],
+          "pageControl": { "position": "bottom" }
+        }
+      ]
+    },
+    "footer": {
+      "kind": "button",
+      "variant": "primary",
+      "action": { "kind": "advance_carousel", "targetLayerId": "lyr_car_intro", "onLast": "complete" },
+      "children": [
+        { "kind": "text", "text": { "default": "Next" }, "style": { "color": "#FFFFFF" } }
+      ]
+    }
+  },
+  "next": { "default": "scr_next" }
+}
+```
+
 ## Completion gate
 
-- [ ] No `button` layers for in-pager next/continue.
+- [ ] No `button` layers that only mimic paging without an `advance_carousel` action.
+- [ ] Every `advance_carousel` button targets a `carousel` on the same screen.
 - [ ] `screen.next` targets the next **screen** in the flow, not “next slide”.
 - [ ] Single-slide carousel screens include a flow-level CTA if the flow must advance without swiping.

package/rheo/rheo-flow-import/references/flow-spec.md

@@ -62,7 +62,7 @@ the scaffold expands into a real layer. `id` is always optional. `style` and
 { "kind": "text", "text": "Welcome to Rheo", "style": { "color": "#FFFFFF" } }
 { "kind": "text", "text": { "default": "Hi", "translations": { "es": "Hola" } } }
 { "kind": "image", "mediaAssetId": "00000000-0000-0000-0000-000000000101", "alt": "Hero" }
-{ "kind": "icon", "iconName": "sparkles-outline" }            // family defaults to ionicons
+{ "kind": "icon", "iconName": "sparkles-outline" }            // family defaults to ionicons; size defaults to 24×24
 { "kind": "lottie", "mediaAssetId": "…", "loop": true, "autoPlay": true }
 { "kind": "video", "mediaAssetId": "…", "autoPlay": false }    // needs a play_media button
 ```
@@ -91,23 +91,29 @@ Action shorthands: `"none"`, `"continue"`, `"skip"`, `"end_flow"`,
 `"go_back_one_screen"`, `"request_app_review"`. Object forms:
 `{ "kind": "go_to_step", "screenId": "scr_x" }` (or `dec_*` / `surf_*`),
 `{ "kind": "request_os_permission", "permissionKey": "…", "outcomes": { "granted": "scr_a", "denied": "dec_b", "blocked": "surf_c" } }` (targets may be `scr_*`, `dec_*`, `surf_*`, `"continue"`, or `"end"`),
-`{ "kind": "play_media", "targetLayerIds": ["lyr_video"] }`.
+`{ "kind": "play_media", "targetLayerIds": ["lyr_video"] }`,
+`{ "kind": "advance_carousel", "targetLayerId": "lyr_carousel", "onLast": "noop" }`
+(`onLast` is optional and defaults to `"noop"`; use `"complete"` to finish the carousel when the
+button is tapped on the last slide).
 
 ### Stacks (layout)
 
 ```jsonc
-{ "kind": "stack", "direction": "vertical", "align": "center", "gap": 12,
+{ "kind": "stack", "direction": "vertical", "align": "center", "distribution": "center", "gap": 12,
   "style": { "padding": { "t": 24, "r": 16, "b": 24, "l": 16 } },
   "children": [ { "kind": "text", "text": "Centered hero copy" } ] }
 ```
 
+Use `distribution` for main-axis packing (`start` \| `center` \| `end` \| `between` \| `around`). Legacy flow-spec `justify` is accepted by the scaffold and rewritten to `distribution`, but prefer writing `distribution` directly.
+
 Card chrome (border/shadow/background/radius) goes on a wrapping stack's `style`.
 
 ### Choices
 
 You provide `options`; the scaffold builds the option `stack` children,
 `optionBindings`, and `branching`. `optionId` defaults to a slug of the label.
-Map unselected chrome to `style` and selected chrome to `selectedStyle` per option.
+Map unselected chrome to `style` and selected chrome to `selectedStyle` per option
+(bake padding/radius/background/border into `style` — do not omit default chrome).
 
 ```jsonc
 {
@@ -136,11 +142,13 @@ option, set `branching: { "enabled": true, "conditions": [{ "choiceId": "male",
   "inputType": "plain", "required": true, "classification": "safe" }
 { "kind": "scale_input", "fieldKey": "fitness_level", "min": 1, "max": 5, "step": 1,
   "minLabel": "Beginner", "maxLabel": "Pro" }
+{ "kind": "wheel_picker", "fieldKey": "birth_year", "mode": "date", "datePart": "year",
+  "minYear": 1950, "maxYear": 2010, "defaultValue": "1990" }
 { "kind": "checkbox", "fieldKey": "accept_terms", "blocking": true }
 ```
 
 Use **at most one** input layer per screen, and add a `continue` button on
-screens with `text_input`, `multiple_choice`, or `scale_input`.
+screens with `text_input`, `multiple_choice`, `scale_input`, or `wheel_picker`.
 
 ### Auth
 
@@ -156,7 +164,7 @@ screens with `text_input`, `multiple_choice`, or `scale_input`.
 
 Keep OAuth, email/password, and questionnaire inputs on **separate screens**.
 
-### Carousel (swipe-only onboarding pager)
+### Carousel (onboarding pager)
 
 ```jsonc
 {
@@ -175,7 +183,9 @@ Keep OAuth, email/password, and questionnaire inputs on **separate screens**.
 }
 ```
 
-No buttons inside a carousel — paging is swipe-only ([carousel-import.md](carousel-import.md)).
+Paging is swipe by default. When the source screen has an explicit Next control, add a
+`button` with `action: { "kind": "advance_carousel", "targetLayerId": "<carousel id>" }`
+instead of a plain footer CTA ([carousel-import.md](carousel-import.md)).
 
 ### Counter / progress / loader
 

package/rheo/rheo-flow-import/references/import-workflow.md

@@ -63,12 +63,12 @@ If the user has not named an entry point, stop after question 1 and wait for an
    - When source uses `infoSteps`, `currentInfoStep`, horizontal `translateX` pagers, or `pagingEnabled` lists, emit `kind: "carousel"`.
    - Each slide is a vertical `stack` with image, title, and body text from that slide.
    - Add `pageControl: { "position": "bottom" }` when dot indicators exist (dots only).
-   - Carousels are **swipe-only** — no Next/Continue button on the carousel layer. Do not add footer/body buttons for in-pager paging.
-   - Use `regions.footer` only when the source CTA advances the **next screen in the flow**, or for single-slide carousels that need an explicit Continue.
+   - Carousels page by swipe. When the source has an explicit Next control, keep it as a `button` with `action.kind: "advance_carousel"` targeting that carousel; never add a plain footer/body button that only bumps the pager index.
+   - Use `regions.footer` when the source CTA advances the **next screen in the flow**, or for single-slide carousels that need an explicit Continue.
    - Bundle every slide image; every asset referenced in the carousel must appear in `rheo-import.assets.json`.
    - Do not collapse multi-slide routes into one static screen with a single image.
 11. Map layout, alignment, borders, and shadows:
-   - Parent vertical stacks that center content need `align: "center"` (and `justify: "center"` when appropriate).
+   - Parent vertical stacks that center content need `align: "center"` (and `distribution: "center"` when appropriate).
    - Hero images belong inside centered stacks, not as lone siblings in an unaligned vertical stack.
    - Card rows (rating, testimonials, why-it-works cards) use wrapping stacks with `style.background`, `style.radius`, `style.padding`, `style.border`, and `style.shadow` from source.
 12. Map custom fonts from audit findings ([font-import.md](font-import.md)):

package/rheo/rheo-flow-import/references/manifest-agent-profile-fallback.md

@@ -43,7 +43,7 @@ Before zipping, read [layer-schema-pitfalls.md](layer-schema-pitfalls.md) and ru
 
 ## Layer Kinds
 
-Use only: `stack`, `text`, `image`, `lottie`, `video`, `icon`, `button`, `back_button`, `progress`, `loader`, `counter`, `single_choice`, `multiple_choice`, `text_input`, `scale_input`, `oauth_provider`, `oauth_login`, `email_password_auth`, `email_password_field`, `email_password_submit`, `carousel`, `hyperlink`, `checkbox`.
+Use only: `stack`, `text`, `image`, `lottie`, `video`, `icon`, `button`, `back_button`, `progress`, `loader`, `counter`, `single_choice`, `multiple_choice`, `text_input`, `scale_input`, `wheel_picker`, `oauth_provider`, `oauth_login`, `email_password_auth`, `email_password_field`, `email_password_submit`, `carousel`, `hyperlink`, `checkbox`, `conditional`.
 
 ## Rules
 
@@ -55,13 +55,17 @@ Use only: `stack`, `text`, `image`, `lottie`, `video`, `icon`, `button`, `back_b
 - Inspect theme/style/token files, StyleSheet, and Tailwind classes before using black-and-white defaults.
 - Set `style.color` on text for dark/saturated screen backgrounds.
 - Gradients: `screen.containerStyle.backgroundFill.color` as `linear-gradient(...)` CSS when `kind` is `color`.
-- In-screen pagers → `kind: "carousel"` with one slide per page; swipe-only; bundle every slide asset. See carousel-import.md in references.
+- In-screen pagers → `kind: "carousel"` with one slide per page; swipe by default, or an `advance_carousel` button when the source has an explicit Next control; bundle every slide asset. See carousel-import.md in references.
 - Center images with parent stack `align: "center"`; map card borders/shadows to wrapping stacks.
 - Custom fonts: bundle files in `rheo-import.fonts.json` only (never `rheo-import.assets.json`), `manifest.theme.fontFamily`. See `font-import.md`.
-- Choice options: each option stack uses `style` (default) and `selectedStyle` (selected).
+- Choice options: each option stack bakes default chrome into `style` and selected overrides into `selectedStyle` (optional `selectedStyleBreakpoints`).
+- Stack packing: `distribution` — never `justify`. Width fill parent is `"full"` — never width `"fill"`.
+- `text_input.fieldStyle` is typography only; chrome on outer `style`.
+- `wheel_picker`: scroll wheel / date parts; `itemStyle` / `selectedItemStyle` typography only; branch later via `dec_*` with string predicates.
+- Icons default to 24×24 unless source specifies another size.
 - Publish gates: explicit `style.color` on all text (including button labels), Continue on manual-submit screens, valid entry/completion path. Run `scripts/audit-publish-manifest.mjs` before finishing.
 - Black-and-white fallback is acceptable only when the audit finds no style/token evidence and the user confirms no theme source.
-- Use at most one input layer kind per screen.
+- Use at most one input layer kind per **active path** (`single_choice`, `multiple_choice`, `text_input`, `scale_input`, `wheel_picker`) — one per screen unless sibling `conditional` branches split the path.
 - Non-reserved `sdk.*` decision keys must be listed in `sdkAttributeKeys`.
 - RevenueCat paywalls are external surface nodes and always need `fallback`.
 - Emit complete graph edges for imported flows.

package/rheo/rheo-flow-import/references/manifest-rules.md

@@ -23,7 +23,7 @@ See [layer-schema-pitfalls.md](layer-schema-pitfalls.md) for common id mistakes
 
 ## Layer Kinds
 
-Allowed kinds: `stack`, `text`, `image`, `lottie`, `video`, `icon`, `button`, `back_button`, `progress`, `loader`, `counter`, `single_choice`, `multiple_choice`, `text_input`, `scale_input`, `oauth_provider`, `oauth_login`, `email_password_auth`, `email_password_field`, `email_password_submit`, `carousel`, `hyperlink`, `checkbox`.
+Allowed kinds: `stack`, `text`, `image`, `lottie`, `video`, `icon`, `button`, `back_button`, `progress`, `loader`, `counter`, `single_choice`, `multiple_choice`, `text_input`, `scale_input`, `wheel_picker`, `oauth_provider`, `oauth_login`, `email_password_auth`, `email_password_field`, `email_password_submit`, `carousel`, `hyperlink`, `checkbox`, `conditional`.
 
 ## Regions
 
@@ -56,27 +56,36 @@ Map clear brand values into `manifest.theme` and layer styles. Set `style.color`
 
 - In-screen pagers (`infoSteps`, horizontal pager, dot indicators) → `kind: "carousel"` with one slide stack per page.
 - Do not collapse multi-slide routes to one static screen.
-- `pageControl` is optional dot chrome only. Carousels are swipe-only (no pager buttons).
-- Do not duplicate paging with `regions.footer` Continue when the source footer only increments pager index. See [carousel-import.md](carousel-import.md).
+- `pageControl` is optional dot chrome only; the carousel layer has no built-in paging buttons.
+- An explicit source Next control becomes a `button` with `action: { "kind": "advance_carousel", "targetLayerId": "<carousel id>" }` on the same screen.
+- Do not duplicate paging with a `regions.footer` Continue when the source footer only increments pager index. See [carousel-import.md](carousel-import.md).
 
 ## Layout
 
 - Center images: parent stack `align: "center"`.
+- Main-axis packing: stack / button `distribution` (not `justify`).
 - Card chrome: wrapping stacks with `border`, `shadow`, `background`, `radius`, `padding`.
+- Do not invent image `radius` unless the source has rounded corners.
 
 ## Explicit Sizing
 
-Set `style.width` and `style.height` on every layer — do not omit them. `width` accepts `"full"`, `"auto"`, a fraction (`"1/2"`, `"1/3"`, `"2/3"`, `"1/4"`, `"3/4"`), or a pixel number; `height` accepts `"fill"`, `"auto"`, or a pixel number. Use these per-kind defaults unless the design requires otherwise:
+Set `style.width` and `style.height` on every layer — do not omit them. `width` accepts `"full"` (**never** `"fill"` on width), `"auto"`, a fraction (`"1/2"`, `"1/3"`, `"2/3"`, `"1/4"`, `"3/4"`), or a pixel number; `height` accepts `"fill"`, `"auto"`, or a pixel number. Optional clamps: `minWidth` / `maxWidth` / `minHeight` / `maxHeight`. Use these per-kind defaults unless the design requires otherwise:
 
 | Layer kinds | `width` | `height` |
 |-------------|---------|----------|
-| `stack`, `text_input`, `scale_input`, `oauth_login`, `email_password_auth`, `email_password_field`, `progress`, `loader` | `"full"` | `"fill"` |
+| `stack`, `text_input`, `scale_input`, `wheel_picker`, `oauth_login`, `email_password_auth`, `email_password_field`, `progress`, `loader` | `"full"` | `"fill"` |
 | `button`, `back_button`, `oauth_provider`, `email_password_submit`, `checkbox`, `single_choice`, `multiple_choice` | `"full"` | `"auto"` |
-| `text`, `counter`, `icon`, `hyperlink` | `"auto"` | `"auto"` |
+| `text`, `counter`, `hyperlink` | `"auto"` | `"auto"` |
+| `icon` | `24` | `24` |
 | `image`, `lottie`, `video` | `"full"` | number (e.g. `160`) |
 | `carousel` | — (no outer `style` sizing) | — |
 
-Dashboard import backfills these defaults automatically, but emitting them explicitly produces higher-fidelity first drafts.
+Stack packing uses **`distribution`** (`start` \| `center` \| `end` \| `between` \| `around`). Never emit legacy `justify`.
+
+`text_input.fieldStyle` is typography only; outer chrome stays on `style` / `styleBreakpoints`.
+`wheel_picker.itemStyle` / `selectedItemStyle` are row typography only; outer chrome stays on `style` / `styleBreakpoints`.
+
+Dashboard import backfills sizing defaults automatically, but emitting them explicitly produces higher-fidelity first drafts.
 
 ## Container Layers (Required `children`)
 
@@ -135,6 +144,7 @@ When source uses a chevron-only back control, still nest an `icon` child (and op
 - **`back_button`** has no `action` field; navigation is built-in. Use in `regions.header` for back/close chrome.
 - Prefer `continue`, `skip`, and `end_flow` actions for imported first drafts (on `button` only).
 - **`request_app_review`** is allowed for human/explicit requests only (not default imports): empty action object, requires `screen.next.default`, single CTA after a positive moment.
+- **`advance_carousel`** is for a source pager's own Next control: `targetLayerId` must be a `carousel` on the same screen, and optional `onLast` is `noop` (default) or `complete`.
 
 ## Custom Fonts
 
@@ -159,9 +169,10 @@ Full template: [layer-schema-pitfalls.md](layer-schema-pitfalls.md#single_choice
 
 ## Inputs
 
-- Use at most one input layer kind per screen.
+- Use at most one input layer kind per **active path** (`single_choice`, `multiple_choice`, `text_input`, `scale_input`, `wheel_picker`) — one per screen unless sibling `conditional` branches split the path.
 - Use stable snake_case `fieldKey` values.
 - Mark text input classification as `safe` or `sensitive`.
+- `wheel_picker` captures a string (options or date part); no layer branching — use `dec_*` with string predicates.
 
 ## Decisions
 
@@ -169,6 +180,19 @@ Full template: [layer-schema-pitfalls.md](layer-schema-pitfalls.md#single_choice
 - Non-reserved `sdk.*` keys used in decisions must be listed in `sdkAttributeKeys`.
 - Prefer source semantics over visual guessing.
 
+## Conditionals (same-screen variants)
+
+Use `conditional` when the source renders different content on **one** screen based on locale, platform, an SDK attribute, or an answer already captured. Use `dec_*` when the source picks a different **screen**.
+
+- Ordered `cases[]` (1–16), each with a `DecisionExpr` `expression` and a `rootLayerId`; first match wins.
+- Required `elseRootLayerId` for the fallback. Every bound id is a distinct direct child `stack`.
+- Cases read only fields answered **above** the conditional — upstream screens, or same-screen inputs earlier in tree order. Never a field captured inside its own branches.
+- One input / `oauth_login` / `email_password_auth` per active path; sibling branches each get their own.
+- `fieldKey` values stay unique across the whole screen, including across branches.
+- Every case needs at least one rule before publish.
+- No `style` or layout of its own; the winning branch renders in place.
+- Do not use a conditional to reproduce a source screen that was genuinely a separate route.
+
 ## External Surfaces
 
 - RevenueCat paywalls become `externalSurfaceNodes` with provider `revenuecat`.
@@ -194,4 +218,4 @@ When source screens use i18n ([localization-import.md](localization-import.md)):
 - Avoid orphaned screens unless intentionally parked for later editing.
 - Run `scripts/audit-publish-manifest.mjs` before finishing — it enforces dashboard **Publish** rules (see [publish-gates.md](publish-gates.md)).
 - Every `text` and `icon` layer needs explicit `style.color` (including nested button label text).
-- Screens with `text_input`, `multiple_choice`, or `scale_input` need a `continue` button.
+- Screens with `text_input`, `multiple_choice`, `scale_input`, or `wheel_picker` need a `continue` button.

package/rheo/rheo-flow-import/references/publish-gates.md

@@ -26,11 +26,13 @@ These mirror `apps/web/src/features/builder/validateFlow.ts` and API `preflightP
 | **Choice input shape** | `single_choice` / `multiple_choice` missing `optionBindings` or `branching`, using `"options"` instead of `children`, or `fieldKey` not snake_case. |
 | **Container `children`** | `back_button`, `button`, or `hyperlink` emitted without a `children` array (or with label text on the parent instead of nested `text` children). Crashes import on Indie plans during motion strip; fails Zod validation. |
 | **Text/icon `style.color`** | Body text or **button label** (nested text child) left without `style.color` — native does not inherit CSS colors. |
-| **Continue button** | `text_input`, `multiple_choice`, or `scale_input` without a `button` with `action.kind: "continue"`. |
-| **One input per screen** | Multiple inputs, or OAuth/email-password combined with inputs. |
+| **Continue button** | `text_input`, `multiple_choice`, `scale_input`, or `wheel_picker` without a `button` with `action.kind: "continue"`. |
+| **One input per active path** | Multiple inputs on the same path, or OAuth/email-password combined with inputs. Sibling `conditional` branches each get their own budget. |
+| **Conditional bindings** | `cases[].rootLayerId` / `elseRootLayerId` not pointing at distinct direct child stacks, or a case reading a field captured inside its own branch. |
 | **fieldKey** | Missing or non–snake_case on input layers. |
 | **Graph targets** | `go_to_step`, choice `goTo`, loader/lottie/video `onComplete` (screen mode), permission outcomes, and fallbacks point at missing `scr_*` / `dec_*` / `surf_*` ids. |
 | **Media triggers** | Lottie/video with `autoPlay: false` needs a `play_media` button targeting that layer. |
+| **Carousel targets** | `advance_carousel` must point `targetLayerId` at a `carousel` layer on the same screen. |
 | **Screen backgrounds** | Image/video fills need `mediaAssetId`; manual background video needs trigger wiring. |
 
 ### Publishable graph (`validatePublishable`)
@@ -39,6 +41,7 @@ These mirror `apps/web/src/features/builder/validateFlow.ts` and API `preflightP
 - `entryScreenId` set and valid.
 - A **completion path** from entry (`end_flow`, terminal `next`, or external surface end).
 - Decision nodes: every case and `elseNext` connected.
+- `conditional` layers: every case has at least one rule (`conditional.incomplete_cases`).
 
 ### Integrations (default: enabled)
 

package/rheo/rheo-flow-import/references/react-native-source-patterns.md

@@ -38,7 +38,7 @@ Ask the user to confirm the entry file if it is not obvious; do not guess.
 | `react-native-video` / `expo-video` | `video` |
 | `<Pressable>`/`<TouchableOpacity>` acting as CTA | `button` (label = nested `text` child) |
 | Header back chevron / close (`<HeaderBackButton>`, a back `Pressable` in a top bar) | `back_button` in `regions.header`, `icon.family: "ionicons"`, no `action` |
-| `<View style={{ flexDirection, alignItems, gap }}>` | `stack` (`direction`, `align`, `justify`, `gap`) |
+| `<View style={{ flexDirection, alignItems, gap }}>` | `stack` (`direction`, `align`, `distribution`, `gap`) |
 | Vector icons (`react-native-vector-icons`, `@expo/vector-icons` Ionicons) | `icon` (`family: "ionicons"`) |
 | External `Linking.openURL(...)` / `<A href>` | `hyperlink` |
 | Progress bar / step dots tied to step index | `progress` (header) |
@@ -55,6 +55,7 @@ Hero images that render through wrapper components (`<Illustration>`, `<Logo>`,
 - `<TextInput>` collecting a value → `text_input` with a snake_case `fieldKey`;
   mark password/email/PII as `classification: "sensitive"`.
 - Sliders / rating rows → `scale_input`. Consent toggles → `checkbox`.
+- Native scroll wheels / `Picker` / year-month-day selectors → `wheel_picker` (not `single_choice`).
 - Screens with a manual-submit input need a `continue` button.
 
 ## Theme, colors, gradients, fonts
@@ -75,8 +76,9 @@ Hero images that render through wrapper components (`<Illustration>`, `<Logo>`,
 `react-native-pager-view`, a `FlatList horizontal pagingEnabled`, a
 `ScrollView horizontal` snap pager, `Animated` `translateX` paging, or an
 `infoSteps`/`currentStep` index → `kind: "carousel"` with one slide per page.
-Carousels are swipe-only; do not turn the pager's own next button into a footer
-button ([carousel-import.md](carousel-import.md)).
+Paging is swipe by default; map the pager's own next button to a `button` with
+`action.kind: "advance_carousel"` rather than a footer CTA
+([carousel-import.md](carousel-import.md)).
 
 ## Integrations and native steps
 

package/rheo/rheo-flow-import/references/swiftui-source-patterns.md

@@ -36,7 +36,7 @@ Ask the user to confirm the entry view/coordinator if it is not obvious.
 | `VideoPlayer` / `AVPlayer` | `video` |
 | `Button { … } label: { … }` acting as CTA | `button` (label = nested `text` child) |
 | Toolbar back/close (`.toolbar { ToolbarItem(placement: .navigationBarLeading) }`, a chevron `Button`) | `back_button` in `regions.header`, `icon.family: "ionicons"`, no `action` |
-| `VStack`/`HStack`/`ZStack` with `spacing`, `alignment` | `stack` (`direction`, `align`, `justify`, `gap`) |
+| `VStack`/`HStack`/`ZStack` with `spacing`, `alignment` | `stack` (`direction`, `align`, `distribution`, `gap`) |
 | SF Symbol `Image(systemName:)` | `icon` — **remap to a valid `ionicons` name** (SF Symbols are not allowed on `icon`) |
 | `Link(destination:)` / `openURL` | `hyperlink` |
 | `ProgressView(value:)` / step dots | `progress` (header) |
@@ -53,6 +53,7 @@ real asset — follow the struct to its `Image("…")` to find the asset name.
 - `TextField`/`SecureField` → `text_input` with a snake_case `fieldKey`
   (`SecureField` / email / PII → `classification: "sensitive"`).
 - `Slider` / star rating → `scale_input`. `Toggle` consent → `checkbox`.
+- `Picker` / `WheelPicker` / date-part wheels → `wheel_picker` (not `single_choice`).
 - Manual-submit input screens need a `continue` button.
 
 ## Theme, colors, gradients, fonts
@@ -73,7 +74,8 @@ real asset — follow the struct to its `Image("…")` to find the asset name.
 
 A paging `TabView { … }.tabViewStyle(.page)`, a horizontal `ScrollView` with snap
 paging, or an `infoSteps`/`currentStep` index → `kind: "carousel"`, one slide per
-page, swipe-only (no in-pager button) ([carousel-import.md](carousel-import.md)).
+page. Paging is swipe by default; an explicit Next button becomes a `button` with
+`action.kind: "advance_carousel"` ([carousel-import.md](carousel-import.md)).
 
 ## Integrations and native steps