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

package/docs/reference/identity.md

@@ -0,0 +1,116 @@
+# Reference — identity, attribution, journey
+
+Exhaustive reference for the `core/identity` domain. Map of everything: [`../api.md`](../api.md).
+
+## 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.
+- **`getHash(input): Promise<string>`** — SHA-256 hex via Web Crypto.
+
+```ts
+type Fingerprint = {
+  deviceType: "Mobile" | "Desktop";
+  screen: { width; height; colorDepth };
+  userAgent: string;
+  browser: Array<{ brand; version }>;
+  os: string;
+  language: string;
+  plugins?: string[]; // absent (never null/empty) when navigator.plugins is null
+  timezone: string;
+  environmentId: string;
+  id: string; // SHA-256 hex of the serialized fields above
+};
+```
+
+## Identify (`core/identity/identify`)
+
+- **`buildIdentifyPayload({environmentId, fingerprintId, pageUrl, source?, formId?, leadId?, sessionIdFromParams?})`**
+  — native's URL normalization (trailing slashes stripped from href and pathname), `source`
+  defaults `"sdkForm"`.
+- **`identifyLead(transport, payload, opts?): Promise<IdentifyResult | null>`** —
+  `POST /api/v1/lead/identify`, keepalive, `data.data` unwrap, **null on ANY failure** (identity
+  is best-effort; writes still happen unattributed).
+
+```ts
+type LeadSource =
+  | "surfaceForm"
+  | "htmlForm"
+  | "websiteDeAnon"
+  | "webhook"
+  | "website"
+  | "imported"
+  | "scheduler"
+  | "linkedin"
+  | "sdkForm";
+type IdentifyPayload = {
+  environmentId;
+  source: LeadSource;
+  sourceURL;
+  sourceURLDomain;
+  sourceURLPath;
+  sourceUrlSearchParams;
+  leadId?: string | null;
+  formId?;
+  fingerprint?;
+  sessionIdFromParams?: string | null;
+  referrer?: string | null;
+};
+type IdentifyResult = {
+  leadId;
+  sessionId;
+  existing: boolean;
+  leadHasExistingBookingAttr: boolean;
+  leadHasExistingEmailAttr: boolean;
+};
+```
+
+## Lead-data cache (`core/identity/leadDataCache`)
+
+- **`readLeadData(): CachedLeadData | null`** / **`writeLeadData(data)`** — TTL-stamped
+  localStorage cache under **`LEAD_DATA_STORAGE_KEY`** = `"surfaceLeadData"`, TTL
+  **`LEAD_DATA_TTL_MS`** = 10 min; expired entries are removed on read. **Byte-compatible with
+  the public Surface tag's entry** — on a page running both, whichever identified first wins and
+  both agree on the visitor. SSR reads as a miss; storage exceptions are swallowed (cache loss
+  only costs an extra identify).
+
+```ts
+type CachedLeadData = {
+  leadId: string | null;
+  leadSessionId: string | null;
+  fingerprint: string;
+  landingPageUrl?: string;
+  expiry?: number;
+};
+```
+
+## Boot identity step (`core/identity/ensureIdentified`)
+
+- **`ensureIdentified({transport, environmentId, formId?, pageUrl?, source?, preview?})`** — the
+  init sequence's identity resolution, run BEFORE any response write (attribute sync silently
+  no-ops for responses whose lead was never identified): a fresh cache entry with session +
+  fingerprint skips the network; otherwise computes the fingerprint, carries cached
+  leadId/session forward so the server preserves identity, calls identify, caches the result.
+  `preview: true` blocks the call outright. Concurrent calls may each identify — safe, the
+  server find-or-creates by fingerprint.
+
+## Page-view journey (`core/identity/journey`)
+
+- **`createJourneyTracker({transport, environmentId}): JourneyTracker`** — the `journey: true`
+  module, tag-parity: cookies **`JOURNEY_COOKIE_NAME`** = `"surface_journey_id"` (60 d, eTLD+1)
+  and **`RECENT_VISIT_COOKIE_NAME`** = `"surface_recent_visit"` (1 d); duplicate-URL skip;
+  delivery split — beacon when the journey id is known, fetch when it isn't so the server-issued
+  id can be captured (`POST /api/v1/lead/track`).
+
+```ts
+type JourneyTracker = {
+  trackPageView: (url?) => Promise<void>;
+  observeRouteChanges: () => () => void; // patches history + popstate; teardown restores originals
+  clear: () => void; // deletes both cookies (native's clear-on-first-step hook)
+};
+```
+
+Journey→response stitching (UTM backfill) is server-side; the client only delivers page views
+under a stable id.

package/llms.txt

@@ -0,0 +1,317 @@
+# Surface Forms SDK
+
+> Thin-client SDK for Surface Forms. The form record on Surface is the data model
+> (steps, questions, validation, tracking settings); your HTML is presentation only
+> and you host it yourself — Surface never stores or serves it. This file is the
+> binding contract and boot sequence for agents authoring SDK form pages. The
+> package also ships `skills/surface-forms-sdk/SKILL.md` — the full authoring
+> workflow with a starter template; read it before your first form — and
+> `docs/api.md`, the complete public API reference (every export with
+> semantics). Anything not covered here is covered there; never read the
+> bundle to answer an API question.
+
+Import from the package name you actually installed (check your package.json —
+code samples below say `@parag.more.withsurface.com/forms-sdk`, substitute yours). `init` uses
+top-level `await`-friendly ESM; bundlers need `target: "esnext"` (Vite:
+`build.target`) or an async wrapper.
+
+## Boot
+
+```html
+<script src="surface-forms-sdk.min.js"></script>
+<script>
+  SurfaceFormsSDK.SurfaceForms.init({
+    environmentId: "env_…",
+    formId: "form_…",
+    apiBaseUrl: "https://…", // REQUIRED unless the environment is on the default host
+    container: document.querySelector("#my-form"),
+  });
+</script>
+```
+
+ESM: `import { SurfaceForms } from "@parag.more.withsurface.com/forms-sdk"`. `init` is async and returns
+the form handle. When `steps` is omitted (the normal case) it fetches the record
+from `GET {apiBaseUrl}/api/v1/public/forms/{formId}/runtime-config` and derives
+the step order, expected questionIds, and behavioral settings; caller-provided
+values win.
+
+**`apiBaseUrl` is the #1 boot failure.** The default is
+`https://forms.withsurface.com`; any environment on another deployment 404s
+until you pass its host. The `get_sdk_binding_map` MCP tool returns the correct
+`apiBaseUrl` and a ready-to-paste `init` snippet that includes it — use that
+snippet verbatim. A failed fetch throws with the exact URL it tried.
+
+Options beyond the four above: `preview: true` (no network writes at all — identify,
+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),
+`urlDataStateId` (attribution pseudo-answer), `emailValidation: true`
+(automatic verdicts, see below), `resume`, `meta`, `source`.
+
+Boot-flash tip: mark every `data-step-id` container after the first `hidden`
+in your HTML — `bindForm` sets visibility only after the async `init`
+resolves, so unhidden steps flash stacked during boot.
+
+### Endpoints the SDK calls (all relative to `apiBaseUrl`)
+
+`GET /api/v1/public/forms/{formId}/runtime-config` (record; `?preview=1&pt=` for drafts) ·
+`POST /api/v1/lead/identify` · `POST /api/v1/responses/` (create) ·
+`POST /api/v1/responses/update` · `GET /api/v1/responses/getResponse?rid=&rt=` (resume) ·
+`POST /api/v1/edge/emailValidation` · `POST /api/v1/services/enrichment/realtime` ·
+`POST /api/v1/pushEvent` · `POST /api/v1/form-journey/track` · `POST /api/v1/lead/track` (journey) ·
+`POST /api/v1/check-password` · `/api/v1/scheduler/*` (availability, slots, book, reschedule).
+
+## Binding contract (the `data-*` vocabulary)
+
+Get the exact ids for a form from the `get_sdk_binding_map` MCP tool — each
+question's `answerShape` there is the exact state object its answer must have.
+Then:
+
+- `data-question-id="<questionId>"` — on the input itself or a wrapper; every
+  `input`/`select`/`textarea` inside binds. Bind every stateful questionId the
+  record declares; unbound ids warn in the console at runtime. EXCEPTION:
+  scheduler (`CalendlyScreen`/`DynamicScheduler`) and `FileUploader` questions
+  need NO binding — their answers are written in code via `setAnswer`
+  (`validate_form_html` knows this and only notes them).
+- `data-field-name="<key>"` — which key of the component's answer object this
+  control writes. Resolved PER CONTROL: wrapper attr ?? control attr ?? inferred
+  (`"selected"` for a Dropdown's `<select>`, `"email"` for `input[type=email]`,
+  else `"input"`). Inference only works when the control type matches the
+  component (an email input bound to a ShortInput needs explicit
+  `data-field-name="input"`); set it explicitly on each control of a
+  multi-field component.
+- `data-question-type="<ComponentType>"` — the record's component type, from the
+  binding map. Inferred only for ShortInput (default) and EmailForm (email
+  inputs); every other type must be set or the answer carries the wrong type.
+- `data-step-id="<stepId>"` — one container per record step. Multi-step records
+  are stepped-only: every step needs a container; the SDK shows exactly one at a
+  time (`hidden` on the rest). Single-step records may omit containers.
+- Checkboxes submit `checked` (boolean); radios are handled by the choice-group
+  rules below.
+
+### Choice questions bind as a GROUP
+
+Five types are group-built — `MultipleOptionsQuestion`, `MultipleChoiceQuestion`,
+`MMChoiceQuestion`, `GraphicOptions`, and `MultipleChoiceSingleAnswer`. 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
+remembered shape), so the SDK builds them from the container's radio/checkbox
+group automatically — never set `data-field-name` on the options:
+
+```html
+<div data-question-id="q_role" data-question-type="MultipleOptionsQuestion">
+  <label><input type="radio" name="role" value="Sales Ops" /> Sales Ops</label>
+  <label><input type="radio" name="role" value="Leadership" /> Leadership</label>
+</div>
+```
+
+Rules: `data-question-type` is REQUIRED on the container (without it the SDK
+falls back to per-control string capture and the server rejects the answer);
+each control's `value` must equal the record option key exactly; author the
+controls in record order; multi-select uses checkboxes the same way. Dropdowns
+bind a `<select>` whose option values are the record option keys (state key
+`"selected"`).
+
+## Navigation (you own routing)
+
+The SDK does not evaluate routing logic — your page decides where visitors go.
+Markers, most specific wins, ONE per element:
+
+- `data-surface-goto-step="<stepId>"` — jump to a step. Forward jumps save
+  progress; jumping to an already-visited step rewinds without a write.
+- `class="surface-disqualify-button"` — end the form as disqualified.
+- `class="surface-submit-button"` — finish and submit.
+- `class="surface-next-button"` — advance to the next step in record order.
+
+A `<form>` container's native submit also finishes. Conditional branching =
+your JS choosing which goto button to show, or calling the API below. Driving
+navigation/submit entirely from JS (async gates like email validation)?
+Put `data-surface-nav="js"` on any element — it tells `validate_form_html`
+the page submits in code, silencing its advance/submit warnings.
+
+Finishing reveals the record's matching ending step: after the terminal write,
+`submit()` moves to the step with `endStepKind: "thank_you"` and `disqualify()`
+to the `"disqualified"` one (when the record declares them), so its
+`data-step-id` container shows automatically. Put the submit button on the last
+question step, not on the thank-you step.
+
+## Headless API
+
+The handle from `init` (and the engine under `useSurfaceForm`) exposes:
+`setAnswer(questionId, state)`, `next()`, `back()`, `goToStep(stepId)`,
+`submit()`, `disqualify()`, `savePartial()`, `flush()`, `markViewed()`,
+`state()`, `subscribe(cb)`, `on(event, cb)`, `identify()` (re-attribute after
+SPA route change), `validateEmail(email)`, `mergeMeta(partial)`,
+`capabilities`, `runtimeConfig`, `destroy()`.
+
+`on` events: `viewed`, `started`, `stepChanged`, `stepCompleted`, `completed`,
+`disqualified`, `saved` (carries `responseId` + `resumeToken`), `error`. Every
+`on`/`subscribe` call returns an unsubscribe function.
+
+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
+fire-and-forget beacons reconciled server-side. `await form.flush()` before
+tearing the page down programmatically (SPA unmount, test harness closing the
+browser) so no queued write is cut off.
+
+`mergeMeta(partial)` records caller-computed values (a qualification score, an
+experiment bucket) onto the response `meta` — they ride the next save, or amend
+the stored response if the form already finished. SDK-owned keys
+(`surfaceTagStatus`, the email-validation verdicts) are dropped with a warning.
+
+`capabilities` reports what actually runs in THIS environment:
+`{ enrichment, emailValidation, tracking }`. Check `capabilities.enrichment`
+before promising enriched lead data — a record can declare an enrichment source
+that the environment backs with no provider (nothing else surfaces that).
+
+## Resume
+
+The first save returns a `resumeToken` alongside the `responseId` (both on the
+`saved` event and in `state()`). Persist the pair (e.g. localStorage or a
+`?rid=&rt=` link) and pass it back to continue the same response later:
+
+```js
+SurfaceForms.init({ ..., resume: { responseId, resumeToken } });
+```
+
+Boot fetches the stored answers through the token-gated read-back and seeds
+the engine: writes become updates (no duplicate response), earlier answers are
+preserved in every save, and `state().answers` holds them for your UI to
+prefill. A failed fetch (wrong token, deleted response) warns and starts a
+fresh session. The token proves the caller obtained the responseId
+legitimately — never build resume links from ids alone. Resume is ignored in
+preview.
+
+React: `import { useSurfaceForm } from "@parag.more.withsurface.com/forms-sdk/react"` — a
+`useSyncExternalStore` adapter over the same engine; render controlled inputs
+from `state`, call the same actions.
+
+Headless `setAnswer` calls should be annotated with the exported answer types
+(`ShortInputAnswer`, `MultipleOptionsAnswer`, `IdentityInfoAnswer`,
+`SchedulerAnswer`, … — union `KnownAnswerState`) so the compiler enforces the
+wire shapes; during development, `debug: true` audits them at runtime too.
+
+## Email validation
+
+`form.validateEmail(email)` resolves the server-side deliverability verdict
+(provider waterfall + the environment's spam blacklist; keys stay
+server-side): `{ isValid, status, reason, failed? }`. Verdicts are cached per
+address for the form's lifetime and FAIL OPEN: when no validator can run, the
+result is `{ isValid: true, failed: true, status: "unknown" }` — never lock a
+visitor out on a vendor outage. Two consequences to design for: (1) check
+`failed` if you want to soft-warn instead of hard-block; (2) the same address
+can be accepted today (fail-open) and return a definitive `invalid` tomorrow —
+that's the waterfall resolving, not a bug; don't write tests that assume a
+fixed verdict for a fresh domain. Use it to drive your own navigation:
+
+```js
+const { isValid, reason, failed } = await form.validateEmail(emailInput.value);
+if (isValid) form.next();
+else showError(`Email rejected: ${reason}`);
+```
+
+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
+network. Offline callers wire it themselves: `createEmailValidator({
+transport, environmentId })` and optionally `attachEmailValidation({ engine,
+validator })`.
+
+## Real-time enrichment
+
+When the form's environment has an enabled enrichment provider, `init` wires
+it automatically for records fetched from runtime-config: a valid email (or
+website domain) answered on an IdentityInfo `enrichmentSourceField` /
+`websiteUrl` / EmailForm field triggers the form-scoped enrichment endpoint
+(provider key stays server-side), and the result rides every save as
+`enrichedFields` — becoming enriched lead attributes. Deduped per value;
+never fires in preview. Nothing to configure page-side. **No enabled provider
+= silently inert**: check `form.capabilities.enrichment` (and `debug: true`
+warns) rather than assuming a declared source field means enrichment runs.
+Customers who want to autofill their own inputs from the result can read
+`state().externalStates.selfServeEnrichment.data` via `subscribe`. Offline
+callers (caller-provided `steps`) wire it themselves: `attachEnrichment({
+engine, transport, formId, sources })` with sources from
+`enrichmentSourcesOf(config)`.
+
+## Scheduler booking (Surface schedulers)
+
+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
+`onComplete` below writes the answer):
+
+```js
+import { createSchedulerClient, createTransport, mountBookingWidget, toSchedulerAnswerState } from "@parag.more.withsurface.com/forms-sdk";
+
+const scheduler = createSchedulerClient({ transport: createTransport({ apiBaseUrl }), preview });
+mountBookingWidget({
+  container: document.querySelector("#booking"),
+  scheduler,
+  eventTypeId: "<from the record's CalendlyScreen content>",
+  identity: { responseId: form.state().responseId ?? undefined },
+  prefill: { name, email }, // pre-fills the widget's name/email inputs
+  onComplete: (booking) => {
+    form.setAnswer("<schedulerQuestionId>", { ...toSchedulerAnswerState(booking), type: "CalendlyScreen" });
+    form.submit(); // or goToStep/next, per your flow
+  },
+});
+```
+
+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:
+
+```
+div.surface-booking
+├─ p.surface-booking-month              (or p.surface-booking-loading / p.surface-booking-error + button.surface-booking-retry)
+├─ div.surface-booking-month-nav > button.surface-booking-month-button ×2   (Previous/Next month)
+└─ ul.surface-booking-dates > li.surface-booking-date > button.surface-booking-date-button
+                              (li.surface-booking-no-dates when empty)
+-- after a date is picked --
+p.surface-booking-day · button.surface-booking-back
+ul.surface-booking-slots > li.surface-booking-slot > button.surface-booking-slot-button
+-- after a slot is picked --
+form.surface-booking-form > input.surface-booking-name + input.surface-booking-email + button.surface-booking-submit
+                            (p.surface-booking-error on failure)
+-- booked --
+p.surface-booking-booked
+```
+
+`toSchedulerAnswerState` emits `type: "DynamicScheduler"`; override `type` to
+the record's component type as shown. With `preview: true` the scheduler client
+returns a synthetic booking, so the whole flow is testable without a calendar.
+
+## Authoring loop (MCP tools)
+
+1. `plan_form` with `sdk: true` when requirements are vague — routing stays
+   prose (your page owns it) and styling/layout questions are skipped.
+2. `create_form` with `sdk: true` — creates the record (no styling/routing params).
+3. `get_sdk_binding_map` — ids, field names, `answerShape` per question, the
+   `environmentId` AND `apiBaseUrl` for `init` (its snippet is ready to paste).
+4. Write the HTML in the user's project using this contract.
+5. `validate_form_html` — fix every blocker; take warnings seriously (they are
+   silent data loss at runtime). JS-driven navigation declares itself with
+   `data-surface-nav="js"`.
+6. `validate_form` — the record's own logic checks. (`simulate_response` does
+   not apply to SDK forms: it evaluates record routing, which SDK records
+   don't have.)
+7. Preview locally with `preview: true` + the `previewToken` from step 2 or 3
+   (works before publishing), then `publish_form`; deploy the page.
+8. Submit one test response, `await form.flush()` before closing the tab, then
+   read it back with `get_response`/`list_responses` and check every answer
+   landed.
+
+Rules: labels live on the record — they default to each question's text and the
+responses table reads them, so give every question real question text. Styling
+and routing MCP tools refuse on SDK forms by design; presentation is entirely
+yours.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@parag.more.withsurface.com/forms-sdk",
+  "version": "0.1.4",
+  "description": "Thin-client Surface Forms SDK: headless core over the public runtime endpoints (field-test build).",
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/types/react/index.d.ts",
+      "import": "./dist/react/index.mjs",
+      "require": "./dist/react/index.cjs"
+    }
+  },
+  "files": ["dist", "docs", "llms.txt", "README.md", "skills"],
+  "peerDependencies": { "react": ">=18" },
+  "peerDependenciesMeta": { "react": { "optional": true } }
+}

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

@@ -0,0 +1,153 @@
+---
+name: surface-forms-sdk
+description: Build a self-hosted Surface form with the Forms SDK — create the form record over the Surface MCP tools, author HTML against the data-* binding contract, validate, preview, publish, and verify the stored response. Use whenever the task is "build/embed a form with the Surface Forms SDK".
+---
+
+# Building a Surface SDK form
+
+You are building a **self-hosted** form: the form record on Surface is the data
+model (steps, questions, validation, tracking); the page — HTML, CSS, routing
+logic — is yours and never leaves the user's project. The SDK binds the two.
+
+Read `llms.txt` in this package first (binding contract + full API). This skill
+is the workflow and the traps that cost previous runs the most time. Deeper
+references alongside this file — read the one that matches the job:
+
+- [`patterns.md`](patterns.md) — concrete HTML shapes: boot, choice groups,
+  multi-step with branching, multi-field components, the scheduler widget, the
+  React/SPA adapter (destroy-on-unmount), and tracking setup + verification.
+- [`editing.md`](editing.md) — changing an EXISTING SDK form: the record↔HTML
+  sync loop, `ifRevision` guards, and how to sequence the record publish vs the
+  HTML deploy so nothing lands answers in a divergence window.
+- [`debugging.md`](debugging.md) — symptom → cause → check runbook (missing
+  responses/answers, 400s, verdict flakiness, silent tracking/enrichment).
+- [`../../docs/api.md`](../../docs/api.md) — the complete public API reference:
+  every export (transport, engine, clients, identity, events, scheduler,
+  React) with semantics. Consult it for anything beyond the happy path —
+  never read the bundle.
+
+## Prerequisites
+
+- The Surface MCP tools (`create_form`, `get_sdk_binding_map`,
+  `validate_form_html`, `publish_form`, `get_response`, …) connected for the
+  target environment.
+- This npm package installed. Import from the name in the user's package.json —
+  docs may say `@parag.more.withsurface.com/forms-sdk`; the installed name wins.
+- Bundler `target: "esnext"` (top-level await), or wrap `init` in an async fn.
+
+## The workflow
+
+1. **Plan (optional).** Vague requirements → `plan_form` with `sdk: true`.
+   Branching stays prose (`routingIntent`) — your page implements it; never
+   encode structured routing for an SDK form.
+2. **Create the record.** `create_form` with `sdk: true`. Give every question
+   real question text — the responses table reads those labels. Save the
+   `formId` and `previewToken` from the reply.
+3. **Get the binding map.** `get_sdk_binding_map` returns, per question:
+   `questionId`, `componentType`, `fieldNames`, and `answerShape` — the EXACT
+   object each answer must be. It also returns **`apiBaseUrl` and a
+   ready-to-paste `init` snippet that includes it. Use that snippet.** Booting
+   without the right `apiBaseUrl` is the #1 failure: the runtime-config fetch
+   404s against the default host.
+4. **Author the page** against the template below.
+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.
+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,
+   which SDK forms don't have.
+7. **Publish.** `publish_form`.
+8. **Verify end-to-end.** Submit one real test response; `await form.flush()`
+   before closing the page; read it back with `get_response` and confirm every
+   answer + `meta.surfaceTagStatus: "sdk"`.
+
+## Traps (each cost a previous field run real time)
+
+- **`apiBaseUrl`** — always from `get_sdk_binding_map`; never assume the default.
+- **Answer shapes** — copy `answerShape` per question; never guess. The five
+  choice types (`MultipleOptionsQuestion`, `MultipleChoiceQuestion`,
+  `MMChoiceQuestion`, `GraphicOptions`, `MultipleChoiceSingleAnswer`) have
+  DIFFERENT shapes; the SDK builds them from the radio/checkbox group — never
+  put `data-field-name` on choice options, always set `data-question-type` on
+  the group container, and make each control's `value` exactly the record's
+  option key.
+- **IdentityInfo keys** are a closed set: `emailAddress`/`workEmailAddress`
+  (not `email`), `phoneNumber` (not `phone`). Multi-field components need an
+  explicit `data-field-name` per control.
+- **Boot flash** — mark every step container after the first `hidden`; the SDK
+  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.
+- **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
+  domains.
+- **Enrichment can be silently inert** — check `form.capabilities.enrichment`
+  before promising enriched fields; a declared source field without an enabled
+  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).
+- **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).
+
+## Starter template
+
+```html
+<div id="form" data-surface-nav="js" hidden>
+  <section data-step-id="STEP_1_ID">
+    <label
+      >Work email <input type="email" data-question-id="Q_EMAIL_ID" />
+      <!-- EmailForm infers type+field -->
+    </label>
+    <p class="error" hidden></p>
+    <button type="button" id="to-step-2">Continue</button>
+  </section>
+
+  <section data-step-id="STEP_2_ID" hidden>
+    <div data-question-id="Q_ROLE_ID" data-question-type="MultipleOptionsQuestion">
+      <label><input type="radio" name="role" value="OPTION_KEY_1" /> OPTION_KEY_1</label>
+      <label><input type="radio" name="role" value="OPTION_KEY_2" /> OPTION_KEY_2</label>
+    </div>
+    <button type="button" class="surface-submit-button">Submit</button>
+  </section>
+
+  <section data-step-id="THANK_YOU_STEP_ID" hidden><h2>Thanks!</h2></section>
+</div>
+```
+
+```js
+import { SurfaceForms } from "PACKAGE_NAME";
+
+const form = await SurfaceForms.init({
+  environmentId: "ENV_ID",
+  formId: "FORM_ID",
+  apiBaseUrl: "API_BASE_URL", // from get_sdk_binding_map — do not omit
+  container: document.querySelector("#form"),
+  emailValidation: true, // opt-in: writes native-parity verdict meta
+});
+document.querySelector("#form").hidden = false;
+
+// JS-driven forward nav: gate on the email verdict, then branch yourself.
+document.querySelector("#to-step-2").addEventListener("click", async () => {
+  const email = document.querySelector("[data-question-id=Q_EMAIL_ID]").value;
+  const { isValid, reason } = await form.validateEmail(email);
+  if (!isValid) return showError(`That address looks undeliverable (${reason}).`);
+  form.next(); // or form.goToStep("…") / form.disqualify() per your rules
+});
+
+form.on("saved", ({ responseId, resumeToken }) =>
+  localStorage.setItem("surface-resume", JSON.stringify({ responseId, resumeToken }))
+);
+```
+
+Back navigation can stay markerless JS too (`form.back()`), or use the
+declarative markers (`surface-next-button`, `data-surface-goto-step`,
+`surface-disqualify-button`) when no async gate is needed.