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

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

@@ -116,14 +116,38 @@ code-driven. Full event list for your own listeners: `viewed`, `started`, `stepC
 </div>
 ```
 
-## Scheduler step (Surface scheduler)
+## Scheduler step
 
-A `CalendlyScreen` with `calendarType: "Surface"` renders through the SDK's own unstyled widget — never iframe the hosted booking page, and never bind the question in HTML (the `onComplete` writes the answer):
+Default: one call. `mountScheduler` renders the record's scheduler question for ANY supported
+provider (Surface's widget default-styled, or the record's third-party embed — Calendly,
+Cal.com, SavvyCal, Chili Piper, HubSpot, RevenueHero, Zoom, Reclaim.ai, Clari), emits the
+lifecycle on `form.on("scheduler")`, and persists the booking into the response by itself.
+Never iframe the hosted booking page, and never bind the question in HTML:
 
 ```html
 <section data-step-id="step_book" hidden>
   <div id="booking"></div>
 </section>
+<script>
+  const teardown = SurfaceFormsSDK.mountScheduler({
+    form,
+    container: document.querySelector("#booking"),
+    onEvent(e) {
+      if (e.type === "booking_confirmed") form.submit(); // or next()/goToStep, per your flow
+    },
+  });
+</script>
+```
+
+Note the booking itself needs no wiring — persistence is automatic (`persist: false` opts out);
+`onEvent` here only drives navigation. `styled: false` skips the injected scoped stylesheet
+(Surface provider). Clari is embed-only (no booking signal → drive navigation yourself).
+In preview mode the Surface path books synthetically and nothing is written.
+
+Custom booking UI (only when asked): mount the unstyled widget directly and write the answer
+yourself —
+
+```html
 <script>
   const { createSchedulerClient, createTransport, mountBookingWidget, toSchedulerAnswerState } =
     SurfaceFormsSDK;
@@ -144,8 +168,7 @@ A `CalendlyScreen` with `calendarType: "Surface"` renders through the SDK's own
 The widget emits semantic markup under stable `surface-booking-*` classes (full DOM tree in
 `llms.txt`) and injects no CSS — style from the page. Labels are locale-formatted by default
 with the raw value on each element's `data-value`; pass `formatters: { month?, date?, time? }`
-to override the copy. In preview mode the client returns a synthetic booking, so the flow is
-testable offline.
+to override the copy.
 
 ## React adapter (SPA)
 
@@ -209,7 +232,9 @@ function QualifySteps({ form }: { form: SurfaceForm }) {
 }
 ```
 
-`state` is `useSyncExternalStore`-backed: referentially stable between engine mutations, safe to render from directly. `submit()`/`disqualify()` move `state.currentStepId` to the record's matching ending step, so the same step-switch renders the confirmation. On SPA route changes call `form.identify()` to re-attribute the visitor; on programmatic teardown after a submit flow, `await form.flush()` first.
+`state` is `useSyncExternalStore`-backed: referentially stable between engine mutations, safe to render from directly. `state.answers` is keyed by stepId then questionId — the example reads the current step (`state.answers[state.currentStepId]`), but an EARLIER step's answer (booking prefill, a summary screen) is read by that step's id: `state.answers["step_role"]?.["q_role"]`. `submit()`/`disqualify()` move `state.currentStepId` to the record's matching ending step, so the same step-switch renders the confirmation. On SPA route changes call `form.identify()` to re-attribute the visitor.
+
+React teardown rule: `destroy()` alone in the effect cleanup is correct — a cleanup cannot await, partial saves are beacons that survive unmount, and the finishing write was already awaited by `submit()` itself before the cleanup can run. Reserve `await form.flush()` for programmatic teardown where the process itself may die with a write still queued (a test harness closing the browser), not for ordinary SPA unmounts.
 
 ## Tracking setup