@getrheo/rheo-skill 2.3.0 → 2.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @getrheo/rheo-skill
 
-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`).
+Current release: **`2.5.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.3.0",
+  "version": "2.5.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.3.0",
-    "@getrheo/flow-runtime": "2.3.0",
+    "@getrheo/contracts": "2.5.0",
+    "@getrheo/flow-runtime": "2.5.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.3.0"
+  rheo-version: "2.5.0"
   manifest-schema-version: "7"
 ---
 

package/rheo/rheo-best-practices/SKILL.md

@@ -30,7 +30,8 @@ Only install packages or edit host code when the user explicitly asks for implem
 - **Pass the channel public id**, not a flow id, to `Flow` / `FlowView`.
 - **Preserve the existing onboarding** as a fallback/rollback path (feature flag or route swap) unless the user explicitly asks to remove it.
 - **Read local conventions first** (package manager, navigation, env handling) and keep edits localized to the integration entry point and app config.
-- **RevenueCat and AppsFlyer are host integrations**, not SDK peers — the host configures and owns those SDKs and their secrets. Wire `fallback` for every external surface.
+- **RevenueCat and AppsFlyer are host integrations**, not SDK peers — the host configures and owns those SDKs and their secrets. Wire `fallback` for every Integration / External Surface Node.
+- **External Surface Nodes** need a host `externalSurfaces` registry keyed by Host key (`config.hostKey` or `surf_*` id; callbacks `onComplete` / `onBack` / `onDismiss`). No App settings toggle.
 - **Do not add `request_app_review`** prompts unless the user explicitly asks; Apple discourages prompting from raw button taps.
 - Run the **narrowest useful verification** (typecheck or a build of the touched module), not a full app build, unless asked.
 

package/rheo/rheo-best-practices/references/integrations.md

@@ -1,12 +1,19 @@
 # Integrations
 
-## RevenueCat
+In the flow builder, partner paywalls and host UI are **two add-menu nodes** that share the `externalSurfaceNodes` schema:
+
+| Builder node | Manifest `config.provider` | App settings toggle |
+| --- | --- | --- |
+| **Integration Node** | `revenuecat` (and future partners) | Required |
+| **External Surface Node** | `headless` | None (host registry) |
+
+## RevenueCat (Integration Node)
 
 Detect source calls such as `Purchases.configure`, `react-native-purchases`, `react-native-purchases-ui`, or existing paywall presentation code.
 
 Manifest mapping:
 
-- Create an external surface with `config.provider: "revenuecat"`.
+- Create an **Integration Node** / external surface with `config.provider: "revenuecat"`.
 - Preserve offering or placement identifiers when visible in source.
 - Wire known outcomes:
   - `purchase_completed`
@@ -17,6 +24,37 @@ Manifest mapping:
 
 The host remains responsible for configuring RevenueCat. Rheo does not own purchase SDK secrets or receipt validation.
 
+## External Surface Node (headless host UI)
+
+Use when a source screen is owned by the host (custom native UI, third-party screen Rheo does not ship) rather than a Rheo layer tree or RevenueCat paywall.
+
+Manifest mapping:
+
+- Create an **External Surface Node** with `config.provider: "headless"`.
+- Keep a stable `surf_*` id for graph routing / analytics. Optionally set `config.hostKey` for the host `externalSurfaces` registry (defaults to the node id).
+- Wire outcomes:
+  - `completed` ← host `onComplete`
+  - `back` ← host `onBack`
+  - `dismissed` ← host `onDismiss`
+  - `failed` ← missing host component (SDK)
+- Always wire `fallback`.
+
+Host wiring (required for success):
+
+```ts
+// React Native — key matches Host key (hostKey or surf_* id)
+<Flow
+  channelId="…"
+  externalSurfaces={{
+    onboardingQuiz: ({ onComplete, onBack, onDismiss }) => /* host UI */,
+  }}
+/>
+```
+
+SwiftUI / Flutter: pass the same map on `FlowView` as `externalSurfaces` (builders receive `onComplete` / `onBack` / `onDismiss`). Docs: product Developer Guide → Headless external surfaces.
+
+Do **not** use an External Surface Node to wrap RevenueCat when you need `iap_purchase` commerce events — use an Integration Node with `provider: "revenuecat"`.
+
 ## AppsFlyer
 
 Detect `react-native-appsflyer` or Swift attribution setup. Do not include AppsFlyer secrets in manifests.

package/rheo/rheo-best-practices/references/react-native-bare.md

@@ -15,7 +15,7 @@ pnpm add @getrheo/react-native-bare \
   react-native-safe-area-context react-native-in-app-review react-native-video
 ```
 
-**Integrations (host only):** `react-native-appsflyer`, `react-native-purchases`, `react-native-purchases-ui` when needed.
+**Integrations (host only):** `react-native-appsflyer`, `react-native-purchases`, `react-native-purchases-ui` when needed. External Surface Nodes use `Flow` `externalSurfaces` (no extra native peer).
 
 ## Minimal Runtime
 
@@ -24,7 +24,13 @@ import { Flow, RheoProvider } from '@getrheo/react-native-bare';
 
 export const OnboardingHost = () => (
   <RheoProvider config={{ publishableKey: '…', userId: '…' }}>
-    <Flow channelId="ch_…" onFlowCompleted={() => {}} />
+    <Flow
+      channelId="ch_…"
+      onFlowCompleted={() => {}}
+      externalSurfaces={{
+        // surf_*: ({ onComplete, onBack, onDismiss }) => host UI
+      }}
+    />
   </RheoProvider>
 );
 ```

package/rheo/rheo-best-practices/references/react-native-expo.md

@@ -15,7 +15,7 @@ pnpm add @getrheo/react-native-expo \
   react-native-safe-area-context expo-store-review expo-video
 ```
 
-**Integrations (host only, not SDK peers):** `react-native-appsflyer`, `react-native-purchases`, `react-native-purchases-ui` when the flow uses attribution or RevenueCat paywalls.
+**Integrations (host only, not SDK peers):** `react-native-appsflyer`, `react-native-purchases`, `react-native-purchases-ui` when the flow uses attribution or RevenueCat Integration Nodes. External Surface Nodes use `Flow` / `useFlow` `externalSurfaces` (no extra native peer).
 
 ## Minimal Runtime
 

package/rheo/rheo-best-practices/references/swiftui.md

@@ -46,7 +46,8 @@ struct OnboardingHost: View {
 
 ## Notes
 
-- Use `RheoSwiftUIRevenueCat` for RevenueCat external surface presenter helpers.
+- Use `RheoSwiftUIRevenueCat` for RevenueCat Integration Node presenter helpers.
+- External Surface Nodes: pass `externalSurfaces: [surfId: { ctx in AnyView(...) }]` on `FlowView` (`ctx.onComplete` / `onBack` / `onDismiss`).
 - Use `RheoSwiftUIAppsFlyer` for AppsFlyer attribution providers.
 - Host apps must include Info.plist usage strings for authored permission prompts.
 - Host apps must register branding fonts if relying on downloaded font families.

package/rheo/rheo-best-practices/references/troubleshooting.md

@@ -38,7 +38,7 @@ Fix workflow:
 
 ## Missing Fallback Edge
 
-Every external surface needs `fallback`. RevenueCat outcomes that are not explicitly mapped fall through to this target.
+Every Integration / External Surface Node needs `fallback`. Outcomes that are not explicitly mapped (RevenueCat purchase outcomes or headless `completed` / `back` / `dismissed`) fall through to this target.
 
 ## Integration Disabled
 

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

@@ -35,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
 
@@ -60,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
@@ -102,7 +111,10 @@ Valid `permissionKey` values for `request_os_permission`:
 - `email_password_auth` modes: `sign_in`, `sign_up` (sign_up requires email + password + confirm fields).
 - `icon` families: `ionicons`.
 
-## External surface outcomes (RevenueCat)
+## External surface outcomes
+
+Builder add-menu kinds share `externalSurfaceNodes`: **Integration Node** (partner providers such as RevenueCat) and **External Surface Node** (`provider: "headless"`). Every node needs a `fallback` jump target.
+
+**Integration Node / RevenueCat** (`provider: "revenuecat"`): `purchase_completed`, `purchase_cancelled`, `dismissed`, `failed`, `restore_completed`.
 
-Normalized outcome keys for `externalSurfaceNodes[].outcomes`: `purchase_completed`, `purchase_cancelled`, `dismissed`, `failed`, `restore_completed`.
-Every external surface also needs a `fallback` jump target.
+**External Surface Node / Headless** (`provider: "headless"`): `completed`, `back`, `dismissed`, `failed`. Host apps register UI via `externalSurfaces[hostKey]` (`config.hostKey` or node id) with `onComplete` / `onBack` / `onDismiss`.

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

@@ -91,7 +91,10 @@ 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)
 
@@ -161,7 +164,7 @@ screens with `text_input`, `multiple_choice`, `scale_input`, or `wheel_picker`.
 
 Keep OAuth, email/password, and questionnaire inputs on **separate screens**.
 
-### Carousel (swipe-only onboarding pager)
+### Carousel (onboarding pager)
 
 ```jsonc
 {
@@ -180,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
 
@@ -194,7 +199,8 @@ No buttons inside a carousel — paging is swipe-only ([carousel-import.md](caro
 ## Decisions and external surfaces
 
 `decisions` accepts full `@getrheo/contracts` `DecisionNode` objects (the scaffold
-passes them through). RevenueCat paywalls use `externalSurfaces`:
+passes them through). External surfaces use `externalSurfaces` (builder:
+**Integration Node** for `revenuecat`, **External Surface Node** for `headless`):
 
 ```jsonc
 {
@@ -203,7 +209,16 @@ passes them through). RevenueCat paywalls use `externalSurfaces`:
   "offeringId": "default",
   "presentation": "paywall",
   "outcomes": { "purchase_completed": "scr_done", "restore_completed": "scr_done", "dismissed": "scr_offer2" },
-  "fallback": "scr_offer2"   // required
+  "fallback": "scr_offer2"   // required — Integration Node
+}
+```
+
+```jsonc
+{
+  "id": "surf_custom_step",
+  "provider": "headless",
+  "outcomes": { "completed": "scr_done", "back": "scr_welcome", "dismissed": "scr_offer2" },
+  "fallback": "scr_offer2"   // required — External Surface Node; host registers externalSurfaces.surf_custom_step
 }
 ```
 

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

@@ -63,8 +63,8 @@ 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:

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`, `wheel_picker`, `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,7 +55,7 @@ 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 bakes default chrome into `style` and selected overrides into `selectedStyle` (optional `selectedStyleBreakpoints`).
@@ -65,9 +65,9 @@ Use only: `stack`, `text`, `image`, `lottie`, `video`, `icon`, `button`, `back_b
 - 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 (`single_choice`, `multiple_choice`, `text_input`, `scale_input`, `wheel_picker`).
+- 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`.
+- RevenueCat **Integration Nodes** and headless **External Surface Nodes** both live in `externalSurfaceNodes` and always need `fallback`.
 - Emit complete graph edges for imported flows.
 - Use placeholder UUID media ids and `rheo-import.assets.json`; never put file paths directly in `mediaAssetId`.
 - Do not silently drop media layers. If a traced asset cannot be copied, report the missing file and do not call the import complete.

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`, `wheel_picker`, `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,8 +56,9 @@ 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
 
@@ -143,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
 
@@ -167,7 +169,7 @@ Full template: [layer-schema-pitfalls.md](layer-schema-pitfalls.md#single_choice
 
 ## Inputs
 
-- Use at most one input layer kind per screen (`single_choice`, `multiple_choice`, `text_input`, `scale_input`, `wheel_picker`).
+- 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.
@@ -178,11 +180,28 @@ 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`.
-- Every external surface needs a `fallback`.
-- Map known paywall outcomes to `purchase_completed`, `restore_completed`, `dismissed`, and `failed`.
+In the builder UI these are two add-menu kinds sharing `externalSurfaceNodes`:
+
+- **Integration Node** — RevenueCat paywalls become nodes with provider `revenuecat`.
+- **External Surface Node** — Host-owned custom screens become nodes with provider `headless` (stable `surf_*` id; optional `config.hostKey` for the host `externalSurfaces` registry).
+- Every node needs a `fallback`.
+- Map paywall outcomes to `purchase_completed`, `restore_completed`, `dismissed`, and `failed`.
+- Map headless outcomes to `completed`, `back`, `dismissed`, and `failed`.
 
 ## Assets
 

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

@@ -27,10 +27,12 @@ These mirror `apps/web/src/features/builder/validateFlow.ts` and API `preflightP
 | **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`, `scale_input`, or `wheel_picker` without a `button` with `action.kind: "continue"`. |
-| **One input per screen** | Multiple inputs, or OAuth/email-password combined with inputs. |
+| **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,12 +41,14 @@ 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)
 
-- External surfaces need `config.provider` (not `unspecified`).
+- External surfaces need `config.provider` (not `unspecified`). Integration Nodes use partner providers such as `revenuecat`; External Surface Nodes use `headless`.
 - Every external surface needs `fallback`.
 - RevenueCat surfaces require RevenueCat integration enabled (import assumes enabled).
+- External Surface Nodes (`provider: "headless"`) do not require an App settings toggle; the host must supply `externalSurfaces`.
 
 ### Canvas editor gates (default: all enabled)
 

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

@@ -76,21 +76,23 @@ 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
 
 - `react-native-purchases` / `react-native-purchases-ui` / `Purchases.configure`
-  / a `<Paywall>` → a RevenueCat **external surface** (`provider: "revenuecat"`,
-  required `fallback`). See [integrations](../../rheo-best-practices/references/integrations.md).
+  / a `<Paywall>` → a RevenueCat **Integration Node** (`provider: "revenuecat"`,
+  required `fallback`). Host-owned custom screens → an **External Surface Node**
+  (`provider: "headless"`). See [integrations](../../rheo-best-practices/references/integrations.md).
 - `react-native-appsflyer` → represent stable attribution branches via decision
   nodes; add keys to `sdkAttributeKeys`. Never include AppsFlyer/RevenueCat secrets.
 - OAuth / email-password screens → `oauth_login` / `email_password_auth` (host
   owns the actual auth logic).
 - `react-native-permissions` prompts → a `request_os_permission` button action.
 - Signature pads, camera capture, custom WebViews → confirm with the user whether
-  to keep native (host-owned) or approximate; flag unmappable behavior in chat.
+  to keep native (External Surface Node / host-owned) or approximate; flag unmappable behavior in chat.
 
 ## i18n
 

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

@@ -74,13 +74,15 @@ 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
 
 - RevenueCat (`Purchases.configure`, `RevenueCatUI` `PaywallView`, `.presentPaywall`)
-  → a RevenueCat **external surface** (`provider: "revenuecat"`, required
-  `fallback`). See [integrations](../../rheo-best-practices/references/integrations.md).
+  → a RevenueCat **Integration Node** (`provider: "revenuecat"`, required
+  `fallback`). Host-owned custom screens → an **External Surface Node**
+  (`provider: "headless"`). See [integrations](../../rheo-best-practices/references/integrations.md).
 - AppsFlyer (`AppsFlyerLib`) → represent stable attribution branches via decision
   nodes; add keys to `sdkAttributeKeys`. Never include secrets.
 - "Sign in with Apple" (`SignInWithAppleButton`) / OAuth / email-password →
@@ -89,7 +91,7 @@ page, swipe-only (no in-pager button) ([carousel-import.md](carousel-import.md))
   `UNUserNotificationCenter`) → a `request_os_permission` button action; the host
   must declare the matching `Info.plist` usage strings.
 - `PencilKit` signature, camera capture, custom `WKWebView` → confirm whether to
-  keep native (host-owned) or approximate; flag unmappable behavior in chat.
+  keep native (External Surface Node / host-owned) or approximate; flag unmappable behavior in chat.
 
 ## Localization