@getrheo/rheo-skill 2.4.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.4.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.4.0",
-    "@getrheo/flow-runtime": "2.4.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.4.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/references/capabilities.md

@@ -111,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
 
-Normalized outcome keys for `externalSurfaceNodes[].outcomes`: `purchase_completed`, `purchase_cancelled`, `dismissed`, `failed`, `restore_completed`.
-Every external surface also needs a `fallback` jump target.
+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`.
+
+**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/flow-spec.md

@@ -199,7 +199,8 @@ instead of a plain footer CTA ([carousel-import.md](carousel-import.md)).
 ## 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
 {
@@ -208,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/manifest-agent-profile-fallback.md

@@ -67,7 +67,7 @@ Use only: `stack`, `text`, `image`, `lottie`, `video`, `icon`, `button`, `back_b
 - 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 **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

@@ -195,9 +195,13 @@ Use `conditional` when the source renders different content on **one** screen ba
 
 ## 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

@@ -45,9 +45,10 @@ These mirror `apps/web/src/features/builder/validateFlow.ts` and API `preflightP
 
 ### 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

@@ -83,15 +83,16 @@ Paging is swipe by default; map the pager's own next button to a `button` with
 ## 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

@@ -80,8 +80,9 @@ page. Paging is swipe by default; an explicit Next button becomes a `button` wit
 ## 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 →
@@ -90,7 +91,7 @@ page. Paging is swipe by default; an explicit Next button becomes a `button` wit
   `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
 

package/rheo/rheo-flow-import/scripts/lib/rheo-cli.mjs

@@ -8422,15 +8422,20 @@ var conditionalFieldScopeViolations = (screen) => {
   return violations;
 };
 var ExternalSurfaceNodeIdSchema = external_exports.string().min(1).max(64).regex(/^surf_[a-z0-9_]+$/i, "external surface node id must look like surf_<id>");
-var NORMALIZED_SURFACE_OUTCOMES = [
+var IAP_SURFACE_OUTCOMES = [
   "purchase_completed",
   "purchase_cancelled",
   "dismissed",
   "failed",
   "restore_completed"
 ];
+var NORMALIZED_SURFACE_OUTCOMES = [
+  ...IAP_SURFACE_OUTCOMES,
+  "completed",
+  "back"
+];
 var NormalizedSurfaceOutcomeSchema = external_exports.enum(NORMALIZED_SURFACE_OUTCOMES);
-var SurfaceProviderSchema = external_exports.enum(["unspecified", "revenuecat"]);
+var SurfaceProviderSchema = external_exports.enum(["unspecified", "revenuecat", "headless"]);
 var UnspecifiedExternalSurfaceConfigSchema = external_exports.object({
   provider: external_exports.literal("unspecified")
 });
@@ -8441,16 +8446,28 @@ var RevenueCatSurfaceConfigSchema = external_exports.object({
   placementId: external_exports.string().min(1).max(128).optional(),
   presentation: RevenueCatSurfacePresentationSchema.optional()
 });
+var ExternalSurfaceHostKeySchema = external_exports.string().min(1).max(64).regex(
+  /^[a-zA-Z][a-zA-Z0-9_]*$/,
+  "host key must start with a letter and contain only letters, digits, or underscores"
+);
+var HeadlessExternalSurfaceConfigSchema = external_exports.object({
+  provider: external_exports.literal("headless"),
+  /** Registry key for `Flow` / `FlowView` `externalSurfaces`. Defaults to the node id. */
+  hostKey: ExternalSurfaceHostKeySchema.optional()
+});
 var ExternalSurfaceConfigSchema = external_exports.discriminatedUnion("provider", [
   UnspecifiedExternalSurfaceConfigSchema,
-  RevenueCatSurfaceConfigSchema
+  RevenueCatSurfaceConfigSchema,
+  HeadlessExternalSurfaceConfigSchema
 ]);
 var ExternalSurfaceOutcomesMapSchema = external_exports.object({
   purchase_completed: FlowJumpTargetSchema2.optional(),
   purchase_cancelled: FlowJumpTargetSchema2.optional(),
   dismissed: FlowJumpTargetSchema2.optional(),
   failed: FlowJumpTargetSchema2.optional(),
-  restore_completed: FlowJumpTargetSchema2.optional()
+  restore_completed: FlowJumpTargetSchema2.optional(),
+  completed: FlowJumpTargetSchema2.optional(),
+  back: FlowJumpTargetSchema2.optional()
 }).strict();
 var ExternalSurfaceNodeSchema = external_exports.object({
   id: ExternalSurfaceNodeIdSchema,
@@ -8461,6 +8478,12 @@ var ExternalSurfaceNodeSchema = external_exports.object({
   /** Required: used for any outcome not in `outcomes` (e.g. provider quirks, unmapped events). */
   fallback: FlowJumpTargetSchema2
 });
+var resolveExternalSurfaceHostKey = (node) => {
+  if (node.config.provider === "headless" && node.config.hostKey) {
+    return node.config.hostKey;
+  }
+  return node.id;
+};
 var RESERVED_RC_SDK_KEYS = [
   /** Last RC event observed by the SDK (e.g. `purchase_completed`, `purchase_cancelled`). */
   "onb_rc_last_event",
@@ -8710,6 +8733,7 @@ var refineManifestGraph = (manifest, ctx, jumpTargets) => {
     }
   });
   const seenSurfaceId = /* @__PURE__ */ new Set();
+  const seenHostKey = /* @__PURE__ */ new Set();
   manifest.externalSurfaceNodes.forEach((sn, si) => {
     if (seenSurfaceId.has(sn.id)) {
       ctx.addIssue({
@@ -8733,6 +8757,17 @@ var refineManifestGraph = (manifest, ctx, jumpTargets) => {
         path: ["externalSurfaceNodes", si]
       });
     }
+    if (sn.config.provider === "headless") {
+      const hostKey = resolveExternalSurfaceHostKey(sn);
+      if (seenHostKey.has(hostKey)) {
+        ctx.addIssue({
+          code: external_exports.ZodIssueCode.custom,
+          message: `duplicate external surface host key "${hostKey}"`,
+          path: ["externalSurfaceNodes", si, "config", "hostKey"]
+        });
+      }
+      seenHostKey.add(hostKey);
+    }
     for (const [outcome, target] of Object.entries(sn.outcomes)) {
       if (target != null && !jumpTargets.has(target)) {
         ctx.addIssue({
@@ -12435,7 +12470,7 @@ var fixForBuilderMessage = (message) => {
     return "Set externalSurfaceNodes[].config.provider to a real provider (e.g. revenuecat), not unspecified.";
   }
   if (message.includes("Fallback edge")) {
-    return "Connect every external surface fallback to the next screen/decision/surface when the paywall dismisses or fails.";
+    return "Connect every external surface fallback to the next screen/decision/surface when no specific outcome is mapped.";
   }
   return `Resolve builder publish rule: ${message}`;
 };
@@ -12449,7 +12484,7 @@ var collectIntegrationIssues = (manifest, integrations) => {
     }
     if (node.fallback == null) {
       issues.push(
-        `External surface "${node.name ?? node.id}" needs a connected Fallback edge \u2014 every paywall must route somewhere when no specific outcome is mapped.`
+        `External surface "${node.name ?? node.id}" needs a connected Fallback edge \u2014 every external surface must route somewhere when no specific outcome is mapped.`
       );
     }
     if (node.config.provider === "revenuecat" && !integrations.revenuecat.enabled) {
@@ -15004,16 +15039,19 @@ var ScreenSpecSchema = external_exports.object({
 var ExternalSurfaceSpecSchema = external_exports.object({
   id: external_exports.string().min(1).max(64),
   name: external_exports.string().min(1).max(80).optional(),
-  provider: external_exports.enum(["revenuecat", "unspecified"]),
+  provider: external_exports.enum(["revenuecat", "headless", "unspecified"]),
   offeringId: external_exports.string().min(1).max(128).optional(),
   placementId: external_exports.string().min(1).max(128).optional(),
   presentation: external_exports.enum(["paywall", "paywall_if_needed"]).optional(),
+  hostKey: external_exports.string().min(1).max(64).regex(/^[a-zA-Z][a-zA-Z0-9_]*$/).optional(),
   outcomes: external_exports.object({
     purchase_completed: external_exports.string().min(1).nullable().optional(),
     purchase_cancelled: external_exports.string().min(1).nullable().optional(),
     dismissed: external_exports.string().min(1).nullable().optional(),
     failed: external_exports.string().min(1).nullable().optional(),
-    restore_completed: external_exports.string().min(1).nullable().optional()
+    restore_completed: external_exports.string().min(1).nullable().optional(),
+    completed: external_exports.string().min(1).nullable().optional(),
+    back: external_exports.string().min(1).nullable().optional()
   }).optional(),
   fallback: external_exports.string().min(1).nullable()
 });
@@ -15518,6 +15556,9 @@ var buildExternalSurface = (surface) => {
     ...surface.offeringId ? { offeringId: surface.offeringId } : {},
     ...surface.placementId ? { placementId: surface.placementId } : {},
     ...surface.presentation ? { presentation: surface.presentation } : {}
+  } : surface.provider === "headless" ? {
+    provider: "headless",
+    ...surface.hostKey ? { hostKey: surface.hostKey } : {}
   } : { provider: "unspecified" };
   const outcomes = {};
   for (const [key, value] of Object.entries(surface.outcomes ?? {})) {