@parag.more.withsurface.com/forms-sdk 0.1.4 → 0.1.6

package/dist/types/tracking/conversionRules.d.ts

@@ -1,12 +1,4 @@
-/**
- * Ad-conversion rule engine (forms-sdk-plan.md row 55): a dependency-free port
- * of form-render's `adConversions/{evaluateRules,fireConversion}.ts` and the
- * `ZAdConversionRule` settings schema. The SDK always runs first-party, so the
- * native parent-page/postMessage/ack hop disappears — matching rules fire
- * directly on this window. Rule semantics, provider payloads, and the
- * `responseId` dedupe key are identical by construction; the contract test
- * validates these local types against the real Zod schema.
- */
+
 export type AdConversionProvider = "x" | "meta" | "openai" | "ga4" | "linkedin";
 export type AdConversionTrigger = "reached_qualified" | "form_submitted" | "reached_step" | "form_started" | "step_submitted" | "email_provided" | "meeting_booked";
 export type AdConversionCondition = {
@@ -77,11 +69,10 @@ export declare const DEFAULT_OPENAI_EVENT_NAME = "lead_created";
 export declare const matchesCondition: (condition: AdConversionCondition, params: TrackingParams) => boolean;
 export declare const matchesConditions: (conditions: AdConversionCondition[], params: TrackingParams, operator?: "and" | "or") => boolean;
 export declare const ruleToConversionEvent: (rule: AdConversionRule) => ConversionEvent | null;
-/** Rules firing for this trigger given the page's tracking params; `reached_step` also needs the step id to match. */
+
 export declare const selectFiringEvents: (rules: AdConversionRule[], trigger: AdConversionTrigger, params: TrackingParams, stepId?: string) => {
     rule: AdConversionRule;
     conversion: ConversionEvent;
 }[];
-/** Fire one conversion on this window. Best-effort: silent under ad blockers, never throws into the form. */
+
 export declare const fireConversion: (win: Window, conversion: ConversionEvent, ctx: FireContext) => boolean;
-//# sourceMappingURL=conversionRules.d.ts.map

package/dist/types/tracking/vendors.d.ts

@@ -1,17 +1,4 @@
-/**
- * Customer-tag bootstrap + lifecycle emission (forms-sdk-plan.md rows 51–54,
- * 58): GTM container, GA4, Meta Pixel, and HubSpot from the form's settings,
- * with the same don't-double-inject guards as the native runtime and the
- * parent tag. No React, no react-gtm-module / react-facebook-pixel — direct
- * global bootstraps like the parent tag's providers.
- *
- * Three native quirks are FIXED here by decision (2026-08-10, memory +
- * plan rows 51–52) — the parity harness whitelists them as intentional diffs:
- * - GTM `SurfaceFormSubmitEvent` carries `formId` (native omits it).
- * - `stepId` in `SurfaceFormStepSubmitted` is the real step id (native sends
- *   the step *name*) — migration note for name-keyed GTM triggers.
- * - GA4 config does NOT hardcode `debug_mode: true`.
- */
+
 export type LifecycleUrlData = {
     url: string;
     urlParams: Record<string, string>;
@@ -25,22 +12,16 @@ export type VendorSettings = {
     };
 };
 export type StepSubmittedPayload = LifecycleUrlData & {
-    /** Quirk fix: the real step id — native sends the step name here. */
+    
     stepId: string;
     formId: string;
     emailProvided: boolean;
     meetingBooked: boolean;
 };
-/**
- * One instance per SurfaceForms.init (no module-level singletons — §2.7):
- * injects the configured vendors immediately, exposes the three lifecycle
- * emitters with native event names/payload keys (they are customers' GTM
- * trigger contracts).
- */
+
 export declare const createVendorTracker: (win: Window, settings: VendorSettings) => {
     formStarted: (formId: string, urlData: LifecycleUrlData) => void;
     stepSubmitted: (payload: StepSubmittedPayload) => void;
     formCompleted: (formId: string, urlData: LifecycleUrlData) => void;
 };
 export type VendorTracker = ReturnType<typeof createVendorTracker>;
-//# sourceMappingURL=vendors.d.ts.map

package/dist/types/validation/attachEmailValidation.d.ts

@@ -5,4 +5,3 @@ export type AttachEmailValidationOptions = {
     validator: EmailValidator;
 };
 export declare const attachEmailValidation: ({ engine, validator }: AttachEmailValidationOptions) => (() => void);
-//# sourceMappingURL=attachEmailValidation.d.ts.map

package/docs/api.md

@@ -35,25 +35,25 @@ exact URL and host it tried.
 
 ### `SurfaceFormsInitOptions`
 
-| Option                | Type                         | Meaning                                                                                                                                                                                            |
-| --------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `environmentId`       | `string`                     | Required. From `get_sdk_binding_map`.                                                                                                                                                              |
-| `formId`              | `string`                     | Required.                                                                                                                                                                                          |
-| `apiBaseUrl`          | `string?`                    | The environment's host. **Required unless the environment is on `https://forms.withsurface.com`** — `get_sdk_binding_map` returns it.                                                              |
-| `container`           | `Element?`                   | Enables the `data-*` binding layer + view detection on this root (§4). Omit for fully headless use.                                                                                                |
-| `steps`               | `Array<{id, endStepKind?}>?` | Caller-provided step order — **skips the record fetch entirely** (offline mode). Normally omitted.                                                                                                 |
-| `settings`            | object?                      | Behavioral gates + tracking config (`trackPartialResponses`, `trackCookies`, `gtmId`, `gaMeasurementId`, `metaPixelId`, `hubspotTracking`, `adsConversions`). Caller values win over the record's. |
-| `expectedQuestionIds` | `string[]?`                  | Overrides the record-derived list behind the unbound-question console warning.                                                                                                                     |
-| `resolveNextStep`     | `ResolveNextStep?`           | Routing hook for `next()`/`submit()` (§7.3); defaults to linear record order.                                                                                                                      |
-| `urlDataStateId`      | `string?`                    | Seeds a `URL_DATA` attribution pseudo-answer under this id (rides every save).                                                                                                                     |
-| `source`              | `LeadSource?`                | Lead source for identify; defaults `"sdkForm"`.                                                                                                                                                    |
-| `journey`             | `boolean?`                   | Page-view tracking module (§7.6), default off.                                                                                                                                                     |
-| `emailValidation`     | `boolean?`                   | Automatic waterfall email validation (§5), default off — verdicts bill the form owner's validator quota.                                                                                           |
-| `preview`             | `boolean?`                   | Blocks ALL network writes (identify, responses, events, journey, enrichment, tracking). Scheduler returns synthetic bookings.                                                                      |
-| `previewToken`        | `string?`                    | With `preview: true`, serves a never-published form's DRAFT config. From `create_form` / `get_sdk_binding_map`.                                                                                    |
-| `resume`              | `{responseId, resumeToken}?` | Continue a stored response (§3). Ignored in preview.                                                                                                                                               |
-| `debug`               | `boolean?`                   | Logs lifecycle + audits every answer against the record; warns on states the server would reject and on inert config (declared enrichment source, no provider). Dev only.                          |
-| `meta`                | `Record<string, unknown>?`   | Seed response meta. `surfaceTagStatus` is always overwritten to `"sdk"`.                                                                                                                           |
+| Option                | Type                         | Meaning                                                                                                                                                                                                                                                                               |
+| --------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `environmentId`       | `string`                     | Required. From `get_sdk_binding_map`.                                                                                                                                                                                                                                                 |
+| `formId`              | `string`                     | Required.                                                                                                                                                                                                                                                                             |
+| `apiBaseUrl`          | `string?`                    | The environment's host. **Required unless the environment is on `https://forms.withsurface.com`** — `get_sdk_binding_map` returns it.                                                                                                                                                 |
+| `container`           | `Element?`                   | Enables the `data-*` binding layer + view detection on this root (§4). Omit for fully headless use.                                                                                                                                                                                   |
+| `steps`               | `Array<{id, endStepKind?}>?` | Caller-provided step order — **skips the record fetch entirely** (offline mode). Normally omitted.                                                                                                                                                                                    |
+| `settings`            | object?                      | Behavioral gates + tracking config (`trackPartialResponses`, `trackCookies`, `gtmId`, `gaMeasurementId`, `metaPixelId`, `hubspotTracking`, `adsConversions`). Caller values win over the record's.                                                                                    |
+| `expectedQuestionIds` | `string[]?`                  | Overrides the record-derived list behind the unbound-question console warning.                                                                                                                                                                                                        |
+| `resolveNextStep`     | `ResolveNextStep?`           | Routing hook for `next()`/`submit()` (§7.3); defaults to linear record order.                                                                                                                                                                                                         |
+| `urlDataStateId`      | `string?`                    | Seeds a `URL_DATA` attribution pseudo-answer under this id (rides every save).                                                                                                                                                                                                        |
+| `source`              | `LeadSource?`                | Lead source for identify; defaults `"sdkForm"`.                                                                                                                                                                                                                                       |
+| `journey`             | `boolean?`                   | Page-view tracking module (§7.6), default off.                                                                                                                                                                                                                                        |
+| `emailValidation`     | `boolean?`                   | Automatic waterfall email validation (§5), default off — verdicts bill the form owner's validator quota.                                                                                                                                                                              |
+| `preview`             | `boolean?`                   | Blocks ALL network writes (identify, responses, events, journey, enrichment, tracking). Scheduler returns synthetic bookings.                                                                                                                                                         |
+| `previewToken`        | `string?`                    | With `preview: true`, serves a never-published form's DRAFT config. From `create_form` / `get_sdk_binding_map`.                                                                                                                                                                       |
+| `resume`              | `{responseId, resumeToken}?` | Continue a stored response (§3). Ignored in preview.                                                                                                                                                                                                                                  |
+| `debug`               | `boolean?`                   | Logs lifecycle + navigation intent (`next requested from step …`, distinguishing an un-fired click from a blocked advance) + audits every answer against the record; warns on states the server would reject and on inert config (declared enrichment source, no provider). Dev only. |
+| `meta`                | `Record<string, unknown>?`   | Seed response meta. `surfaceTagStatus` is always overwritten to `"sdk"`.                                                                                                                                                                                                              |
 
 ## 2. The form handle — `SurfaceForm`
 
@@ -61,26 +61,28 @@ Everything the engine exposes (§7.3) minus internals, plus init-level helpers.
 Full method semantics, event payloads, and delivery guarantees:
 [`reference/engine.md`](reference/engine.md).
 
-| Member             | Signature                                   | Semantics                                                                                                                                                                                                                                        |
-| ------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `setAnswer`        | `(questionId, state) => void`               | Merges a partial state into the question's answer. Use the typed answer states (§6) — wrong shapes are the classic production 400.                                                                                                               |
-| `next` / `back`    | `() => Promise<void>` / `() => void`        | Linear advance (saves progress; the step being LEFT is stamped on the write) / rewind (never writes).                                                                                                                                            |
-| `goToStep`         | `(stepId) => Promise<void>`                 | Customer-owned routing: forward jumps save like `next()`; jumps to a visited step rewind like `back()`. Rejects unknown ids.                                                                                                                     |
-| `submit`           | `() => Promise<void>`                       | Finishes the form. **The terminal write is awaited** — when this resolves (and `saved` fires with `finished: true`), the server has the finished response; a delivery failure emits `error` instead. Then reveals the record's `thank_you` step. |
-| `disqualify`       | `() => Promise<void>`                       | Finishes as disqualified (`invalidResponse: true`); reveals the `disqualified` ending.                                                                                                                                                           |
-| `savePartial`      | `() => Promise<void>`                       | Explicit mid-form save (fire-and-forget beacon delivery).                                                                                                                                                                                        |
-| `flush`            | `() => Promise<void>`                       | Resolves when every queued write (including post-finish amends) has settled. Await before programmatic teardown.                                                                                                                                 |
-| `markViewed`       | `() => void`                                | Emits `form_viewed` + first-step `form_step_viewed`, once. The bind layer calls it via IntersectionObserver; headless callers call it themselves.                                                                                                |
-| `state`            | `() => FormEngineState`                     | `{ currentStepId, answers, externalStates, responseId, resumeToken, finished }`. Referentially stable between mutations (safe for `useSyncExternalStore`).                                                                                       |
-| `subscribe`        | `(cb) => Unsubscribe`                       | Store subscription (fires on any state change).                                                                                                                                                                                                  |
-| `on`               | `(event, cb) => Unsubscribe`                | Lifecycle events: `viewed`, `started`, `stepChanged {fromStepId,toStepId}`, `stepCompleted {stepId}`, `completed {formId}`, `disqualified {stepId}`, `saved {responseId, finished, resumeToken}`, `error {scope, error}`.                        |
-| `setExternalState` | `(id, {type, ...}) => void`                 | Writes a pseudo-answer that rides every save (enrichment results, custom attribution). Post-finish it amends the stored response.                                                                                                                |
-| `mergeMeta`        | `(partial) => void`                         | Records caller-computed values (qualification score, experiment bucket) onto response `meta`; rides the next save or amends post-finish. Reserved SDK keys (`surfaceTagStatus`, email-validation verdicts) are dropped with a warning.           |
-| `identify`         | `() => Promise<unknown>`                    | Re-runs visitor identify (SPA route change); later writes attribute to the fresh session.                                                                                                                                                        |
-| `validateEmail`    | `(email) => Promise<EmailValidationResult>` | On-demand deliverability verdict (§5).                                                                                                                                                                                                           |
-| `capabilities`     | `{enrichment, emailValidation, tracking}`   | What actually runs in THIS environment — a record can declare features the environment doesn't back.                                                                                                                                             |
-| `runtimeConfig`    | `RuntimeConfig?`                            | The fetched record (undefined when `steps` was caller-provided).                                                                                                                                                                                 |
-| `destroy`          | `() => void`                                | Tears down every module binding. One engine per page-life — re-`init` without `destroy` creates duplicate responses.                                                                                                                             |
+| Member                               | Signature                                   | Semantics                                                                                                                                                                                                                                                                |
+| ------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `setAnswer`                          | `(questionId, state) => void`               | Merges a partial state into the question's answer. Use the typed answer states (§6) — wrong shapes are the classic production 400.                                                                                                                                       |
+| `next` / `back`                      | `() => Promise<void>` / `() => void`        | Linear advance (saves progress; the step being LEFT is stamped on the write) / rewind (never writes).                                                                                                                                                                    |
+| `goToStep`                           | `(stepId) => Promise<void>`                 | Customer-owned routing: forward jumps save like `next()`; jumps to a visited step rewind like `back()`. Rejects unknown ids.                                                                                                                                             |
+| `submit`                             | `() => Promise<void>`                       | Finishes the form. **The terminal write is awaited** — when this resolves (and `saved` fires with `finished: true`), the server has the finished response; a delivery failure emits `error` instead. Then reveals the record's `thank_you` step.                         |
+| `disqualify`                         | `() => Promise<void>`                       | Finishes as disqualified (`invalidResponse: true`); reveals the `disqualified` ending.                                                                                                                                                                                   |
+| `savePartial`                        | `() => Promise<void>`                       | Explicit mid-form save (fire-and-forget beacon delivery).                                                                                                                                                                                                                |
+| `flush`                              | `() => Promise<void>`                       | Resolves when every queued write (including post-finish amends) has settled. Await before programmatic teardown.                                                                                                                                                         |
+| `markViewed`                         | `() => void`                                | Emits `form_viewed` + first-step `form_step_viewed`, once. The bind layer calls it via IntersectionObserver; headless callers call it themselves.                                                                                                                        |
+| `state`                              | `() => FormEngineState`                     | `{ currentStepId, answers, externalStates, responseId, resumeToken, finished }`. Referentially stable between mutations (safe for `useSyncExternalStore`).                                                                                                               |
+| `subscribe`                          | `(cb) => Unsubscribe`                       | Store subscription (fires on any state change).                                                                                                                                                                                                                          |
+| `on`                                 | `(event, cb) => Unsubscribe`                | Lifecycle events: `viewed`, `started`, `stepChanged {fromStepId,toStepId}`, `stepCompleted {stepId}`, `completed {formId}`, `disqualified {stepId}`, `saved {responseId, finished, resumeToken}`, `error {scope, error}`, `scheduler` (`SchedulerLifecycleEvent`, §7.8). |
+| `setExternalState`                   | `(id, {type, ...}) => void`                 | Writes a pseudo-answer that rides every save (enrichment results, custom attribution). Post-finish it amends the stored response.                                                                                                                                        |
+| `mergeMeta`                          | `(partial) => void`                         | Records caller-computed values (qualification score, experiment bucket) onto response `meta`; rides the next save or amends post-finish. Reserved SDK keys (`surfaceTagStatus`, email-validation verdicts) are dropped with a warning.                                   |
+| `identify`                           | `() => Promise<unknown>`                    | Re-runs visitor identify (SPA route change); later writes attribute to the fresh session.                                                                                                                                                                                |
+| `validateEmail`                      | `(email) => Promise<EmailValidationResult>` | On-demand deliverability verdict (§5).                                                                                                                                                                                                                                   |
+| `capabilities`                       | `{enrichment, emailValidation, tracking}`   | What actually runs in THIS environment — a record can declare features the environment doesn't back.                                                                                                                                                                     |
+| `runtimeConfig`                      | `RuntimeConfig?`                            | The fetched record (undefined when `steps` was caller-provided).                                                                                                                                                                                                         |
+| `notifyScheduler`                    | `(event) => void`                           | Emits on the `scheduler` channel (used by `mountScheduler`; emit-only, never writes).                                                                                                                                                                                    |
+| `transport` / `identity` / `preview` | advanced                                    | The boot transport, the live identity getter, and the preview flag — for modules acting on the form's behalf (`mountScheduler` uses all three).                                                                                                                          |
+| `destroy`                            | `() => void`                                | Tears down every module binding. One engine per page-life — re-`init` without `destroy` creates duplicate responses.                                                                                                                                                     |
 
 ## 3. Resume
 
@@ -268,6 +270,16 @@ true` page-view module (tag-compatible cookies, duplicate-URL skip, SPA
 
 Full `SchedulerClient` signatures and widget options: [`reference/clients.md`](reference/clients.md) + [`reference/binding.md`](reference/binding.md).
 
+- **`mountScheduler(options): () => void`** — the DEFAULT scheduler path: one
+  call renders the record's scheduler question for ANY supported provider
+  (Surface's widget default-styled, or the third-party embed native forms
+  use), emits the `SchedulerLifecycleEvent` union on `form.on("scheduler")` +
+  `onEvent`, and auto-persists the booking into the response
+  (`persist: false` opts out). Options table, provider matrix, and
+  persistence semantics: [`reference/binding.md`](reference/binding.md).
+- **`schedulerQuestionsOf(config): SchedulerQuestion[]`** — the record's
+  scheduler questions with provider + embed content
+  ([`reference/clients.md`](reference/clients.md)).
 - **`createSchedulerClient({ transport, preview? }): SchedulerClient`** —
   public Surface-scheduler endpoints: `getPublicEventType`,
   `getAvailabilitySummary`, `getMonthAvailability` (`YYYY-MM`), `getSlots`,

package/docs/reference/binding.md

@@ -63,24 +63,97 @@ flash.)
 - `expectedQuestionIds` (init derives them from the record) minus the ids actually bound →
   a console warning naming the unbound ids; the runtime counterpart of `validate_form_html`.
 
+## `mountScheduler(options): () => void`
+
+The DEFAULT scheduler path: renders the record's scheduler question for any supported provider,
+emits the lifecycle on the form's `scheduler` event channel, and persists the booking into the
+response automatically. Reach for `mountBookingWidget` (below) only when building a custom UI.
+
+### Options (`MountSchedulerOptions`)
+
+| Option       | Type                                 | Semantics                                                                                                                                                                                                                |
+| ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `form`       | `SurfaceForm`                        | The `init` handle — config, transport, identity, and persistence all come from it.                                                                                                                                       |
+| `container`  | `Element`                            | The embed mounts here; teardown removes it.                                                                                                                                                                              |
+| `questionId` | `string?`                            | Required only when the record has >1 scheduler question (the error names the candidates).                                                                                                                                |
+| `stepId`     | `string?`                            | Alternative selector: the step carrying the scheduler question.                                                                                                                                                          |
+| `styled`     | `boolean?` (default `true`)          | Injects a stylesheet scoped under `.surface-scheduler` on THIS container (Surface widget look + frame sizing). Override via `--surface-scheduler-*` custom props or the same class names; `false` keeps everything bare. |
+| `persist`    | `boolean?` (default `true`)          | Auto-persist lifecycle + booking into the response. `false` still emits events but never writes (and never creates a response).                                                                                          |
+| `prefill`    | `{name?, lastName?, email?}?`        | Overrides the prefill resolved from the record's linked answer refs (`linkNameToStep` etc.).                                                                                                                             |
+| `formatters` | `{month?, date?, time?}?`            | Surface provider only — forwarded to the booking widget.                                                                                                                                                                 |
+| `calendarId` | `string?`                            | DynamicScheduler only: pick a routed calendar by name. Without it: the default calendar, or a lone `calendars[0]`; ambiguous routing throws (conditions are your page's own routing).                                    |
+| `onEvent`    | `(SchedulerLifecycleEvent) => void?` | Same events as `form.on("scheduler", …)`.                                                                                                                                                                                |
+| `onComplete` | `(SchedulerBookingSummary) => void?` | Fires alongside `booking_confirmed`. NOT needed for persistence — that's automatic.                                                                                                                                      |
+
+### Lifecycle events (`SchedulerLifecycleEvent`)
+
+Every event carries `{questionId, stepId, provider}` plus:
+
+```ts
+| { type: "viewed" }                                       // once per mount
+| { type: "date_selected"; date? /* "YYYY-MM-DD" */ }
+| { type: "slot_selected"; slot?: { start; end? } }
+| { type: "form_opened" }
+| { type: "booking_confirmed"; booking: SchedulerBookingSummary }
+| { type: "booking_cancelled"; reason? }
+```
+
+`SchedulerBookingSummary` = `{provider, uri, meetingTime?, meetingEndTime?, inviteeName?,
+guestEmails?, ownerEmails?, joinLink?, raw?}` — `uri` is the provider-native booking id
+(HubSpot's embed reports none; its uri is the single space native forms persist), `raw` the
+untouched provider payload.
+
+### Providers
+
+| Provider (record `calendarType`) | Embed                                  | Booking signal                                         | Extra lifecycle                                                                          |
+| -------------------------------- | -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `Surface`                        | SDK booking widget (styled by default) | widget booking                                         | `date_selected`, `slot_selected`, `form_opened`; sub-steps persist as `schedulerSubStep` |
+| `Calendly`                       | iframe                                 | postMessage + server-poll fallback                     | provider-reported `viewed`, `slot_selected`; poll-reported cancellation                  |
+| `Cal` (Cal.com)                  | vendor script                          | `bookingSuccessful` CustomEvent                        | —                                                                                        |
+| `SavvyCal`                       | vendor script                          | `savvycal.scheduled` CustomEvent                       | —                                                                                        |
+| `ChiliCal` (Chili Piper)         | iframe                                 | `booking-confirmed` postMessage                        | —                                                                                        |
+| `Hubspot`                        | vendor script                          | `meetingBookSucceeded` postMessage                     | —                                                                                        |
+| `RevenueHero`                    | vendor script + router submit          | `MEETING_BOOKED` postMessage                           | —                                                                                        |
+| `Zoom`                           | iframe                                 | `bookingForm` postMessage                              | server-poll backfills host email / times / join link into the answer                     |
+| `ReclaimAI`                      | iframe                                 | server poll ONLY (no client events)                    | poll carries the booking                                                                 |
+| `Clari`                          | iframe                                 | **none** — embed-only; nothing is tracked or persisted | —                                                                                        |
+
+postMessage listeners are origin-checked strictly (exact origin or anchored host suffix — the
+SDK mirrors the vendor protocols, not the laxness some native checks have).
+
+### Persistence semantics
+
+- Confirmed booking → the frozen scheduler answer keys (`eventScheduled`, `uri`,
+  `meetingTime`…, `type` = the record's component type) merged via `setAnswer`, then a partial
+  save; after `submit()` the engine amends the stored response instead. `meta.bookingId` (Surface
+  bookings only) and the `meeting_booked` ad-conversion trigger follow automatically.
+- Poll-reported cancellation (after a confirmed booking) → `eventCancelled: true` + save.
+- Calendly/Zoom/Reclaim embeds carry the `responseId` in their URL, so mounting them creates the
+  response with a partial save when none exists yet. The Surface widget resolves identity lazily
+  at book time instead — lookers who never book create nothing.
+- `preview: true` on the form blocks every write and poll; the Surface widget books through the
+  fabricated preview client, so the whole flow demos offline.
+
 ## `mountBookingWidget(options): () => void`
 
-The unstyled Surface-scheduler booking flow (date → time → name/email form → booked) over a
-`SchedulerClient` ([`clients.md`](clients.md)). Never iframe the hosted booking page.
+The custom-UI escape hatch: the unstyled Surface-scheduler booking flow (date → time →
+name/email form → booked) over a `SchedulerClient` ([`clients.md`](clients.md)). Never iframe
+the hosted booking page. For the zero-effort path use `mountScheduler` (above).
 
 ### Options (`BookingWidgetOptions`)
 
-| Option        | Type                                           | Semantics                                                                                                                                                          |
-| ------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `container`   | `Element`                                      | The widget appends its own `div.surface-booking` root here; teardown removes it.                                                                                   |
-| `scheduler`   | `SchedulerClient`                              | From `createSchedulerClient` (share the transport; pass `preview` there for synthetic bookings).                                                                   |
-| `eventTypeId` | `string`                                       | From the record's `CalendlyScreen` content.                                                                                                                        |
-| `timezone`    | `string?`                                      | Defaults to the visitor's (`Intl.DateTimeFormat().resolvedOptions().timeZone`); slot labels format in it.                                                          |
-| `duration`    | `number?`                                      | Threaded into availability/slots/book queries.                                                                                                                     |
-| `prefill`     | `{name?, email?}?`                             | Pre-fills the widget's name/email inputs.                                                                                                                          |
-| `identity`    | `{responseId?, leadSessionId?, fingerprint?}?` | Threaded into `book()` for booking↔response linkage.                                                                                                               |
-| `formatters`  | `{month?, date?, time?}?`                      | Override the copy: `month("YYYY-MM")`, `date("YYYY-MM-DD")`, `time(slot)` (ISO instants; format in the widget timezone). Defaults are locale-formatted via `Intl`. |
-| `onComplete`  | `(booking: Booking) => void`                   | Fires after a successful booking — persist via `setAnswer({...toSchedulerAnswerState(booking), type: "<record type>"})` and navigate.                              |
+| Option        | Type                                                                      | Semantics                                                                                                                                                                                       |
+| ------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `container`   | `Element`                                                                 | The widget appends its own `div.surface-booking` root here; teardown removes it.                                                                                                                |
+| `scheduler`   | `SchedulerClient`                                                         | From `createSchedulerClient` (share the transport; pass `preview` there for synthetic bookings).                                                                                                |
+| `eventTypeId` | `string`                                                                  | From the record's `CalendlyScreen` content.                                                                                                                                                     |
+| `timezone`    | `string?`                                                                 | Defaults to the visitor's (`Intl.DateTimeFormat().resolvedOptions().timeZone`); slot labels format in it.                                                                                       |
+| `duration`    | `number?`                                                                 | Threaded into availability/slots/book queries.                                                                                                                                                  |
+| `prefill`     | `{name?, email?}?`                                                        | Pre-fills the widget's name/email inputs.                                                                                                                                                       |
+| `identity`    | `BookingIdentity \| (() => BookingIdentity \| Promise<BookingIdentity>)?` | Threaded into `book()` for booking↔response linkage. The getter form resolves at book time — a response created after mount still links.                                                        |
+| `formatters`  | `{month?, date?, time?}?`                                                 | Override the copy: `month("YYYY-MM")`, `date("YYYY-MM-DD")`, `time(slot)` (ISO instants; format in the widget timezone). Defaults are locale-formatted via `Intl`.                              |
+| `onEvent`     | `(BookingWidgetEvent) => void?`                                           | Sub-step transitions: `viewed`, `date_selected {date}`, `slot_selected {slot}`, `form_opened` (fresh opens only, not error re-renders), `booking_confirmed {booking}` (alongside `onComplete`). |
+| `onComplete`  | `(booking: Booking) => void`                                              | Fires after a successful booking — persist via `setAnswer({...toSchedulerAnswerState(booking), type: "<record type>"})` and navigate.                                                           |
 
 ### Behavior + DOM
 

package/docs/reference/clients.md

@@ -158,7 +158,27 @@ server links booking↔response with them; pass what you have.
   override `type` to the record's component type when persisting
   (`{...toSchedulerAnswerState(b), type: "CalendlyScreen"}`).
 
-The DOM widget over this client (`mountBookingWidget`) is in [`binding.md`](binding.md).
+The DOM widget over this client (`mountBookingWidget`) and the zero-effort embedded path
+(`mountScheduler`) are in [`binding.md`](binding.md).
+
+- **`schedulerQuestionsOf(config): SchedulerQuestion[]`** (`core/client/runtimeConfig`) — the
+  record's scheduler questions with everything `mountScheduler` reads:
+
+```ts
+type SchedulerQuestion = {
+  questionId;
+  stepId;
+  componentType: "CalendlyScreen" | "DynamicScheduler"; // also the persisted answer `type`
+  calendarType: string; // provider; the record omits it for the original default, Calendly
+  content: {
+    dataUrl?; eventTypeId?; savvyCalLinkId?; revenueHeroRouterId?;
+    dataUrlParams?: Record<string, { stepId; questionId; variable }>; // answer-state refs → embed params
+    linkNameToStep? / linkLastNameToStep? / linkEmailToStep?: { stepId; questionId }; // prefill refs
+    addSchedulerQueryParams?; skipFormIfPrefilled?;
+    calendars?; defaultCalendar?; // DynamicScheduler routing
+  };
+};
+```
 
 ## Email validation (`core/client/emailValidation` + `validation/attachEmailValidation`)
 

package/docs/reference/engine.md

@@ -30,7 +30,10 @@ creates one for you; construct directly for offline/custom stacks.
 
 - **`setAnswer(questionId, state)`** — merges (`{...prev, ...state}`) into the current step's
   answer for that question. Fires `started` (and the `form_started` event) exactly once, on the
-  first deep divergence from the initial answers. Notifies subscribers.
+  first deep divergence from the initial answers. Notifies subscribers. After the finishing
+  write it amends the stored response (like `setExternalState`/`mergeMeta`) — a booking
+  confirmed on a thank-you-step scheduler still persists; before that, it never writes on its
+  own (writes ride navigation/`savePartial`).
 - **`next(): Promise<void>`** — resolves the next step. Not finished → emits `stepCompleted`,
   pushes the `form_step_submitted`+`form_step_viewed` batch (`stepCompletionTime` = seconds since
   engine creation), records the journey transition, writes a partial (if enabled) stamped with the
@@ -78,6 +81,7 @@ resumeToken, finished}`. The snapshot is cached until the next mutation, so it i
 | `disqualified`  | `{stepId}`                            | Disqualified finish.                                                                                                                 |
 | `saved`         | `{responseId, finished, resumeToken}` | After a CONFIRMED write: every create, every partial dispatch, the awaited terminal update. Never fires for a failed terminal write. |
 | `error`         | `{scope: "submit", error}`            | Failed create (typed `TransportError`) or failed terminal update.                                                                    |
+| `scheduler`     | `SchedulerLifecycleEvent`             | Scheduler lifecycle, emitted via `notifyScheduler` (the `mountScheduler` path — union in [`binding.md`](binding.md)). Emit-only.     |
 
 ### Write serialization + delivery
 

package/docs/reference/events.md

@@ -2,7 +2,10 @@
 
 Exhaustive reference for the `core/events` domain. Map of everything: [`../api.md`](../api.md).
 (The engine's own lifecycle events — `viewed`/`started`/`stepChanged`/… — are in
-[`engine.md`](engine.md); this file covers the modules beneath them.)
+[`engine.md`](engine.md); the `scheduler` channel's `SchedulerLifecycleEvent` union is in
+[`binding.md`](binding.md) with `mountScheduler`. This file covers the modules beneath them.
+Scheduler lifecycle events are client-side only — the push-event vocabulary below is a closed
+server contract and gains no scheduler types.)
 
 ## Push events (`core/events/pushEvents`)
 

package/docs/reference/identity.md

@@ -5,9 +5,8 @@ Exhaustive reference for the `core/identity` domain. Map of everything: [`../api
 ## Fingerprint (`core/identity/browserFingerprint`)
 
 - **`getBrowserFingerprint(environmentId): Promise<Fingerprint>`** — the canonical Surface
-  fingerprint. The serialization (field insertion order, value shapes, falsy fallbacks) IS the
-  wire contract: the lead pipeline keys on `SHA-256(JSON.stringify(fields))`, so never derive
-  your own variant — a different serialization splits one visitor into two leads.
+  fingerprint. Its serialization is a server-side identity contract: always use this function
+  as-is — a hand-rolled variant produces a different `id` and splits one visitor into two leads.
 - **`getHash(input): Promise<string>`** — SHA-256 hex via Web Crypto.
 
 ```ts

package/llms.txt

@@ -45,9 +45,11 @@ Options beyond the four above: `preview: true` (no network writes at all — ide
 responses, events, journey all blocked; pass `previewToken` from the `create_form`
 or `get_sdk_binding_map` reply alongside it and a never-published form serves its
 DRAFT config, so you can preview before the first publish), `debug: true`
-(logs every captured answer + lifecycle event and warns on states the server
-would reject AND on inert configuration like a declared enrichment source with
-no enabled provider; development only), `journey: true` (page-view tracking),
+(logs every captured answer + lifecycle event + navigation intent — a
+`next requested from step …` line per `next()`/`submit()`/… call, so a click
+that never fired is distinguishable from a blocked advance — and warns on
+states the server would reject AND on inert configuration like a declared
+enrichment source with no enabled provider; development only), `journey: true` (page-view tracking),
 `urlDataStateId` (attribution pseudo-answer), `emailValidation: true`
 (automatic verdicts, see below), `resume`, `meta`, `source`.
 
@@ -95,7 +97,12 @@ Then:
 ### Choice questions bind as a GROUP
 
 Five types are group-built — `MultipleOptionsQuestion`, `MultipleChoiceQuestion`,
-`MMChoiceQuestion`, `GraphicOptions`, and `MultipleChoiceSingleAnswer`. Their
+`MMChoiceQuestion`, `GraphicOptions`, and `MultipleChoiceSingleAnswer`. All five
+bind when present in the record, but only the first three are creatable via
+`create_form` (`list_component_types` is the authority) —
+`MultipleChoiceQuestion` and `MultipleChoiceSingleAnswer` are legacy types you
+will only meet on pre-existing forms; build new records with
+`MultipleOptionsQuestion`. Their
 answers are structured (the record's whole option list / a selection object,
 and their shapes differ — only `MultipleOptionsQuestion` carries an option
 `index`; trust each question's `answerShape` from the binding map, never a
@@ -152,6 +159,11 @@ SPA route change), `validateEmail(email)`, `mergeMeta(partial)`,
 `disqualified`, `saved` (carries `responseId` + `resumeToken`), `error`. Every
 `on`/`subscribe` call returns an unsubscribe function.
 
+`state().answers` is keyed by stepId, then questionId
+(`Record<stepId, Record<questionId, state>>`) — reading an EARLIER step's
+answer (booking prefill, a summary screen) indexes by that step's id:
+`state().answers["step_about"]?.["q_name"]`, not by the current step.
+
 Delivery guarantees: the FINISHING write is awaited — when `submit()` resolves
 (and `saved` fires with `finished: true`) the server has the finished response;
 a failure emits `error` instead of lying. Mid-form partial saves are
@@ -219,7 +231,10 @@ Pass `emailValidation: true` to `init` for automatic mode: email answers are
 validated as they're captured (debounced; per-address, so nothing is billed
 twice) and the response carries the same `meta` verdict keys native forms
 write (`isEmailValid`, `emailValidation`, `emailValidationFailed`) for
-dashboards and workflows. Preview resolves synthetic valid verdicts with no
+dashboards and workflows. Automatic mode ANNOTATES ONLY — it never blocks
+navigation or submission (an invalid address still submits, with
+`isEmailValid: false` on the response); to actually gate, call
+`validateEmail` in your own navigation as above. Preview resolves synthetic valid verdicts with no
 network. Offline callers wire it themselves: `createEmailValidator({
 transport, environmentId })` and optionally `attachEmailValidation({ engine,
 validator })`.
@@ -241,11 +256,41 @@ callers (caller-provided `steps`) wire it themselves: `attachEnrichment({
 engine, transport, formId, sources })` with sources from
 `enrichmentSourcesOf(config)`.
 
-## Scheduler booking (Surface schedulers)
+## Scheduler booking
+
+**Default path — one call, any provider.** `mountScheduler` reads the record's
+scheduler question (provider, event URL/id, prefill links), renders a working
+scheduler, tracks the lifecycle, and persists the booking into the response.
+No `onComplete` wiring, no answer writing, no HTML binding:
+
+```js
+import { mountScheduler } from "@parag.more.withsurface.com/forms-sdk";
+
+const teardown = mountScheduler({
+  form, // the SurfaceForms.init handle
+  container: document.querySelector("#booking"),
+  // questionId: "q_booking",   // only when the record has >1 scheduler question
+  onEvent: (e) => console.log(e.type), // optional; also on form.on("scheduler", …)
+});
+```
 
-A record step with a Surface scheduler (`CalendlyScreen` with
-`calendarType: "Surface"`) renders through the SDK's own unstyled widget — do
-NOT iframe the hosted booking page, and do NOT bind the question in HTML (the
+Works for every provider native forms support — Surface's own scheduler
+(rendered through the SDK widget, default-styled; `styled: false` keeps it
+bare), Calendly, Cal.com, SavvyCal, Chili Piper, HubSpot, RevenueHero, Zoom,
+Reclaim.ai, Clari — embedding each third-party widget and listening to its
+booking events exactly like native forms do. Lifecycle events
+(`viewed` / `date_selected` / `slot_selected` / `form_opened` /
+`booking_confirmed` / `booking_cancelled`) emit on `form.on("scheduler")` and
+the `onEvent` option; the confirmed booking is written to the response
+automatically (`persist: false` opts out). Caveats: Clari exposes no booking
+signal (embed-only — the visitor advances manually); Calendly/Zoom/Reclaim
+create the response at mount when none exists yet (their embeds carry the
+`responseId` for booking↔response linkage). Full options + provider matrix:
+`docs/reference/binding.md`.
+
+**Custom-UI path (advanced).** When you're building your own booking UI for a
+Surface scheduler, mount the SDK's unstyled widget directly — do NOT iframe
+the hosted booking page, and do NOT bind the question in HTML (the
 `onComplete` below writes the answer):
 
 ```js
@@ -269,7 +314,10 @@ The widget walks date → time → name/email form → booked. Labels are
 human-readable by default (`Intl` in the visitor's locale; every month/date/slot
 element also carries its raw value in `data-value` — `YYYY-MM`, `YYYY-MM-DD`,
 ISO instant); pass `formatters: { month?, date?, time? }` to override the copy.
-It injects no CSS — style it from your page. The rendered tree:
+The widget itself injects no CSS — style it from your page. (`mountScheduler`'s
+default styling is a stylesheet scoped under `.surface-scheduler` on ITS
+container only; bare `mountBookingWidget` mounts are never restyled.) The
+rendered tree:
 
 ```
 div.surface-booking

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parag.more.withsurface.com/forms-sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Thin-client Surface Forms SDK: headless core over the public runtime endpoints (field-test build).",
   "license": "MIT",
   "sideEffects": false,

package/skills/surface-forms-sdk/SKILL.md

@@ -53,7 +53,13 @@ references alongside this file — read the one that matches the job:
 5. **Validate.** `validate_form_html` until clean. Scheduler/file questions
    report as notes (no binding needed — code writes their answers). If your
    navigation/submit is JS-driven, declare `data-surface-nav="js"` on any
-   element instead of adding fake buttons.
+   element instead of adding fake buttons. For a JSX/React page the check is a
+   one-shot against transcribed markup — ALSO commit a drift test: extract
+   every `data-question-id` / `data-step-id` / choice `value` from the
+   component source (regex over the file is fine) and assert them against the
+   binding map's ids saved in your contract module. Binding drift is silent
+   data loss; only a committed test catches the refactor that renames a
+   question wrapper.
 6. **Preview before publishing.** `init({ preview: true, previewToken })`
    serves the DRAFT record with zero network writes; the scheduler returns a
    synthetic booking. Skip `simulate_response` — it evaluates record routing,
@@ -80,7 +86,9 @@ references alongside this file — read the one that matches the job:
   reveals the current one after async init.
 - **Teardown** — the finishing write is awaited (`submit()` resolving means the
   server has it), but partial saves are beacons: `await form.flush()` before a
-  programmatic page close or your test harness records a partial.
+  programmatic page close or your test harness records a partial. In a React
+  effect cleanup call `destroy()` alone — a cleanup cannot await, and beacons
+  survive an SPA unmount; `flush()` is for closing the whole page/process.
 - **Email validation fails open** — `{ isValid: true, failed: true }` on vendor
   outage, and a fresh domain may resolve to a definitive verdict later. Check
   `failed` to soft-warn; don't write tests expecting stable verdicts for new
@@ -90,10 +98,15 @@ references alongside this file — read the one that matches the job:
   provider does nothing (`debug: true` warns).
 - **Custom values on the response** — `form.mergeMeta({ qualificationScore })`;
   reserved SDK keys are dropped. Don't invent external-state types.
-- **Scheduler** — mount the SDK's widget (never iframe the hosted page), write
-  the answer in `onComplete` via `setAnswer({ ...toSchedulerAnswerState(b),
-type: "CalendlyScreen" })`. Labels are human-readable with raw values in
-  `data-value`; style via the `surface-booking-*` classes (tree in llms.txt).
+- **Scheduler** — default to ONE call: `mountScheduler({ form, container })`
+  renders the record's scheduler (any provider — Surface widget default-styled,
+  or the third-party embed), tracks the lifecycle on `form.on("scheduler")`,
+  and persists the booking automatically. Never iframe the hosted booking
+  page. Build custom UI only when explicitly asked: `mountBookingWidget` +
+  `setAnswer({ ...toSchedulerAnswerState(b), type: "CalendlyScreen" })` in
+  `onComplete`. Traps: Clari emits no booking signal (embed-only);
+  Calendly/Zoom/Reclaim mounts create the response early (their embed URLs
+  carry the responseId); `styled: false` opts out of the injected scoped CSS.
 - **Business logic is invisible to Surface tooling.** Your qualification/
   branching thresholds live in page code no validator can see — test them in a
   real browser walk (both branches, plus a boundary case).