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

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

@@ -0,0 +1,35 @@
+import type { FormEngine } from "../core/engine/formEngine";
+import { type AdConversionRule } from "./conversionRules";
+import { type VendorSettings } from "./vendors";
+/**
+ * Phase-2 tracking runtime (forms-sdk-plan.md rows 51–55): binds one engine
+ * instance to the customer-tag lifecycle events and the ad-conversion rule
+ * engine. Trigger moments mirror `useConversionRules`' semantics translated
+ * from React effects to engine events:
+ *
+ * - `form_started`: the response row landing (first `saved`) in a session that
+ *   began without a responseId — a resume never refires.
+ * - `step_submitted`: the first `stepCompleted` of the session.
+ * - `reached_step`: every step that becomes current (including the initial
+ *   one), once per step — back-nav never refires.
+ * - terminal (`reached_qualified` + `form_submitted` union, deduped by rule):
+ *   the `completed` event; a disqualified finish never fires.
+ * - `email_provided` / `meeting_booked`: first non-empty email answer / first
+ *   scheduler state with `eventScheduled` — detected via `subscribe`.
+ *
+ * Every rule fires once per instance; `responseId` stays the platform-side
+ * dedupe key, so moments reached before the first write queue and flush when
+ * `saved` delivers the id (native's pending-refs, minus the React plumbing).
+ * All state is instance-scoped (§2.7) — two forms on one page track separately.
+ */
+export type TrackingSettings = VendorSettings & {
+    adsConversions?: AdConversionRule[];
+};
+export type AttachTrackingOptions = {
+    engine: FormEngine;
+    formId: string;
+    settings: TrackingSettings;
+    win?: Window;
+};
+export declare const attachTracking: ({ engine, formId, settings, win }: AttachTrackingOptions) => (() => void);
+//# sourceMappingURL=attachTracking.d.ts.map

package/dist/types/tracking/attachTracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachTracking.d.ts","sourceRoot":"","sources":["../../../src/tracking/attachTracking.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAGL,KAAK,gBAAgB,EAItB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAA8C,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG;IAAE,cAAc,CAAC,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC;AAExF,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAmDF,eAAO,MAAM,cAAc,sCAAuC,qBAAqB,KAAG,CAAC,MAAM,IAAI,CAkKpG,CAAC"}

package/dist/types/tracking/attachTracking.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=attachTracking.test.d.ts.map

package/dist/types/tracking/attachTracking.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachTracking.test.d.ts","sourceRoot":"","sources":["../../../src/tracking/attachTracking.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=conversionRules.contract.test.d.ts.map

package/dist/types/tracking/conversionRules.contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversionRules.contract.test.d.ts","sourceRoot":"","sources":["../../../src/tracking/conversionRules.contract.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,87 @@
+/**
+ * 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 = {
+    param: string;
+    operator: "equals_any" | "contains" | "is_present";
+    values?: string[];
+};
+export type AdConversionRule = {
+    id: string;
+    provider: AdConversionProvider;
+    trigger?: AdConversionTrigger;
+    triggerStepId?: string;
+    enabled?: boolean;
+    conditionsOperator?: "and" | "or";
+    conditions?: AdConversionCondition[];
+    eventId?: string;
+    pixelId?: string;
+    measurementId?: string;
+    eventName?: string;
+    partnerId?: string;
+    conversionId?: string;
+};
+export type TrackingParams = Record<string, string>;
+export type ConversionClickIds = {
+    twclid?: string;
+    fbclid?: string;
+    gclid?: string;
+    li_fat_id?: string;
+};
+export type FireContext = {
+    responseId: string;
+    email?: string;
+} & ConversionClickIds;
+export type ConversionEvent = {
+    provider: "x";
+    event: {
+        event_id: string;
+        pixel_id: string;
+    };
+} | {
+    provider: "meta";
+    event: {
+        pixel_id: string;
+        event_name: string;
+    };
+} | {
+    provider: "openai";
+    event: {
+        pixel_id: string;
+        event_name: string;
+    };
+} | {
+    provider: "ga4";
+    event: {
+        measurement_id: string;
+        event_name: string;
+    };
+} | {
+    provider: "linkedin";
+    event: {
+        partner_id: string;
+        conversion_id: string;
+    };
+};
+export declare const DEFAULT_META_EVENT_NAME = "Lead";
+export declare const DEFAULT_GA4_EVENT_NAME = "generate_lead";
+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/conversionRules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversionRules.d.ts","sourceRoot":"","sources":["../../../src/tracking/conversionRules.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=conversionRules.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conversionRules.test.d.ts","sourceRoot":"","sources":["../../../src/tracking/conversionRules.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,46 @@
+/**
+ * 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>;
+};
+export type VendorSettings = {
+    gtmId?: string;
+    gaMeasurementId?: string;
+    metaPixelId?: string;
+    hubspotTracking?: {
+        trackingId?: string;
+    };
+};
+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/tracking/vendors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vendors.d.ts","sourceRoot":"","sources":["../../../src/tracking/vendors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,MAAM,MAAM,gBAAgB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAElF,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C,CAAC;AAwEF,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG;IACpD,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IAGf,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAS,MAAM,YAAY,cAAc;IAsBrE,WAAW,WAAW,MAAM,WAAW,gBAAgB;IAKvD,aAAa,YAAY,oBAAoB;IAK7C,aAAa,WAAW,MAAM,WAAW,gBAAgB;CAO5D,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vendors.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vendors.test.d.ts","sourceRoot":"","sources":["../../../src/tracking/vendors.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,8 @@
+import type { EmailValidator } from "../core/client/emailValidation";
+import type { FormEngine } from "../core/engine/formEngine";
+export type AttachEmailValidationOptions = {
+    engine: FormEngine;
+    validator: EmailValidator;
+};
+export declare const attachEmailValidation: ({ engine, validator }: AttachEmailValidationOptions) => (() => void);
+//# sourceMappingURL=attachEmailValidation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"attachEmailValidation.d.ts","sourceRoot":"","sources":["../../../src/validation/attachEmailValidation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAC5F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AA0B5D,MAAM,MAAM,4BAA4B,GAAG;IACzC,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,cAAc,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,qBAAqB,0BAA2B,4BAA4B,KAAG,CAAC,MAAM,IAAI,CA0FtG,CAAC"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=attachEmailValidation.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"attachEmailValidation.test.d.ts","sourceRoot":"","sources":["../../../src/validation/attachEmailValidation.test.ts"],"names":[],"mappings":""}

package/docs/api.md

@@ -0,0 +1,310 @@
+# Surface Forms SDK — API reference
+
+Every public export of the package, with semantics — so nothing requires reading
+the bundle. Companion docs: `llms.txt` (binding contract + boot, read it first),
+`skills/surface-forms-sdk/` (workflow, HTML patterns, editing, debugging).
+Import everything from the package name you installed; React bits from the
+`/react` subpath. All types below also ship as `.d.ts`.
+
+Layering: **`SurfaceForms.init` composes everything in this file for you.**
+Sections 1–6 are the surface most integrations touch. Section 7 documents the
+building blocks individually for advanced/offline callers assembling their own
+stack (custom transport, server-side tests, partial adoption) — using them
+directly is never required.
+
+This file is the complete MAP (every export appears here); the exhaustive
+per-domain detail — full type bodies, option tables, exact runtime semantics —
+lives in `docs/reference/`. Open the one matching your question:
+
+| Deep reference                                   | Covers                                                                                                                                                         |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`reference/engine.md`](reference/engine.md)     | `createFormEngine` (options, methods, events, write-queue/delivery semantics), all typed answer states, response-payload builders, urlData/urlPrefill/redirect |
+| [`reference/clients.md`](reference/clients.md)   | transport, runtime-config fetch + helpers, response senders, the full `SchedulerClient`, email validation (client + watcher), enrichment watcher               |
+| [`reference/identity.md`](reference/identity.md) | fingerprint (full type + wire contract), identify payload/result, tag-compatible lead cache, `ensureIdentified`, page-view journey                             |
+| [`reference/events.md`](reference/events.md)     | pushEvent pipeline wire types, form-journey telemetry, view/started/drop-off detectors, the emitter primitive                                                  |
+| [`reference/binding.md`](reference/binding.md)   | `bindForm`'s exact resolution algorithm + choice-group builders, `mountBookingWidget` (all options, DOM tree, behavior), React adapter                         |
+
+---
+
+## 1. Boot — `SurfaceForms.init(options): Promise<SurfaceForm>`
+
+Fetches the form record, identifies the visitor, creates the engine, and wires
+every enabled module (DOM binding, tracking, enrichment, email validation,
+journey, drop-off). Throws if the record fetch fails — the error names the
+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"`.                                                                                                                           |
+
+## 2. The form handle — `SurfaceForm`
+
+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.                                                                                                                             |
+
+## 3. Resume
+
+The first save returns `resumeToken` (on `saved` and in `state()`). Persist
+`{responseId, resumeToken}` and pass as `init({ resume })`: boot fetches the
+stored answers through the token-gated read-back, seeds the engine (writes
+become updates, stored answers ride every resend), and `state().answers` holds
+them for prefill. A failed fetch warns and starts fresh. Never build resume
+links from responseIds alone — the token is the authorization.
+
+## 4. DOM binding — `bindForm({ engine, root, expectedQuestionIds? }): () => void`
+
+Exact resolution algorithm and choice-group builders: [`reference/binding.md`](reference/binding.md).
+
+What `init` wires when `container` is passed; exported for callers composing
+their own engine. Discovers `data-question-id` / `data-field-name` /
+`data-question-type` / `data-step-id` and the navigation markers, captures
+input events into `setAnswer` (seeding values already present in the DOM —
+autofill/SSR), builds choice-group answers from radio/checkbox groups, shows
+one step container at a time, and warns on record questionIds with no bound
+element. Returns a teardown. Full attribute contract: `llms.txt`.
+
+## 5. Email validation
+
+- **`createEmailValidator({ transport, environmentId, preview? }): EmailValidator`** —
+  `validate(email)` / `validateBatch(emails)` against
+  `POST /api/v1/edge/emailValidation` (provider waterfall + the environment's
+  spam blacklist; keys stay server-side). Verdicts are cached per address for
+  the validator's lifetime — including failures — so nothing is billed twice.
+  **Fail-open**: when no validator can run the result is
+  `{ isValid: true, failed: true, status: "unknown" }`; the same address can
+  later resolve to a definitive verdict. Preview returns synthetic valid
+  verdicts with no network.
+- **`EmailValidationResult`** — `{ email, isValid, status?, reason?, blacklistEntryIds?, failed? }`.
+- **`attachEmailValidation({ engine, validator }): () => void`** — the
+  `emailValidation: true` watcher: debounced (300 ms, native's) validation of
+  email-bearing answers (`email`, `emailAddress`, `workEmailAddress`), flushed
+  on step completion, writing native's response-meta verdict keys
+  (`isEmailValid`, `emailValidation`, `emailValidationFailed`) with native
+  aggregation (any valid email wins; fail-open counts valid; the window
+  follows the live answers).
+
+## 6. Typed answer states
+
+Full type bodies: [`reference/engine.md`](reference/engine.md).
+
+Local mirrors of each component's wire schema, contract-tested against the
+server's Zod schemas. Annotate headless `setAnswer` calls with them:
+
+`ShortInputAnswer` `{type:"ShortInput", input}` · `LongInputAnswer` ·
+`EmailFormAnswer` `{type:"EmailForm", email, subscriptionCheck?}` ·
+`DropdownAnswer` `{type:"Dropdown", selected}` · `DisclaimerAnswer` ·
+`FileUploaderAnswer` `{type:"FileUploader", fileUrl?}` ·
+`MultipleOptionsAnswer` `{type, choices: [{key, value, index}, …]}` (the ENTIRE
+option list, one entry per record option) · `MMChoiceAnswer` /
+`MultipleChoiceAnswer` `{type, choices: [{key, value}, …]}` ·
+`GraphicOptionsAnswer` `{type, value, index}` ·
+`MultipleChoiceSingleAnswerAnswer` `{type, value, index}` ·
+`IdentityInfoAnswer` (keys from `IDENTITY_INFO_ANSWER_KEYS`:
+`firstName`, `lastName`, `fullName`, `emailAddress`, `workEmailAddress`,
+`phoneNumber`, `companyName`, `numberOfEmployees`, `websiteUrl`, `title`, …) ·
+`SchedulerAnswer` `{type:"CalendlyScreen"|"DynamicScheduler", eventScheduled, uri, …}` ·
+union **`KnownAnswerState`**.
+
+The five choice types have DIFFERENT shapes — trust the binding map's
+`answerShape`, never a remembered one.
+
+## 7. Building blocks (what `init` composes)
+
+### 7.1 Transport
+
+- **`createTransport({ apiBaseUrl? }): Transport`** — `get`/`post` (typed
+  `TransportResult<T>` = `{ok:true,data} | {ok:false,error:TransportError}`,
+  never throws; `post` opts: `keepalive`, `credentials`) and `beacon`
+  (sendBeacon-first, `fetch(keepalive)` fallback, failures swallowed). Every
+  request carries `X-Surface-Sdk-Version` (beacons: `?sdv=` param).
+- **`DEFAULT_API_BASE_URL`** — `"https://forms.withsurface.com"`.
+
+### 7.2 Runtime config
+
+- **`fetchRuntimeConfig(transport, formId, { preview?, previewToken? })`** —
+  `GET /api/v1/public/forms/{formId}/runtime-config` (the same payload the
+  hosted page reads; `settings.password` never arrives). `?preview=1&pt=`
+  serves a never-published form's draft.
+- Helpers over the fetched `RuntimeConfig`: **`stepsOf(config)`** (ordered
+  `{id, endStepKind?}`), **`statefulQuestionsOf`** / **`statefulQuestionIdsOf`**
+  (answer-recording questions), **`enrichmentSourcesOf`** (questionId +
+  fieldNames that can trigger enrichment), **`hasEnabledEnrichmentProvider(settings)`**.
+
+### 7.3 Engine — `createFormEngine(options): FormEngine`
+
+Full option table, method semantics, and event payloads: [`reference/engine.md`](reference/engine.md).
+
+The headless core: answers, traversal, response writes, lifecycle events.
+Options: `formId`, `environmentId?`, `steps` (required), `transport`,
+`resolveNextStep?`, `trackPartialResponses?` (default true),
+`trackCookies?`, `externalStates?`, `meta?`, `identity?` (a GETTER, read at
+write time), `pushEvents?`, `formJourney?`, `preview?`, `resume?`.
+
+Semantics that matter:
+
+- Partial saves happen on forward movement only, stamped with the step being
+  left; the first forward move creates the response, later moves update it.
+- Every write-initiating call runs through one queue — double-clicks advance
+  once, a `submit()` during an in-flight `next()` queues behind it, nothing
+  writes after the finishing submit.
+- The FINISHING write is an awaited `fetch(keepalive)`; partial updates are
+  beacons. A failed terminal write emits `error` (with a best-effort beacon
+  fallback) and never fires `saved`.
+- `setExternalState` / `mergeMeta` after finish amend the stored response by
+  re-issuing the terminal update (full-answer-set resends are idempotent).
+- `resolveNextStep(currentStepId, answers) => {stepId, reason?} | "END" | "INVALID"`
+  — `"END"` finishes, `"INVALID"` disqualifies; default is linear order.
+- **`ResolvedNextStep`**, **`ResolveNextStep`**, **`FormEngineState`**,
+  **`FormEngineEvents`** types exported.
+
+### 7.4 Response wire
+
+- **`submitResponse(transport, payload)`** — `POST /api/v1/responses/`
+  (credentialed: reads/refreshes the `{formId}_pa` repeat-visitor cookie);
+  returns `{responseId, leadId, resumeToken}`.
+- **`updateResponse(transport, payload)`** — beacon to `/api/v1/responses/update`.
+- **`createSubmitResponsePayload`** / **`createUpdateResponsePayload`** /
+  **`buildResponsesArray`** — payload builders mirroring the native runtime:
+  full answer-set resend, external-state pseudo-answers, scheduler-availability
+  skip, booking detection, `responseShapeVersion: "2.0"`. Types:
+  `FormResponsePayload`, `FormUpdateResponsePayload`, `SingleFormResponse`,
+  `AnswerStates`, `ExternalStates`.
+
+### 7.5 Identity
+
+- **`getBrowserFingerprint(environmentId): Promise<Fingerprint>`** /
+  **`getHash(input)`** — the canonical fingerprint; serialization is a wire
+  contract (do not derive your own).
+- **`identifyLead(transport, payload, opts?)`** / **`buildIdentifyPayload`** —
+  `POST /api/v1/lead/identify`; null on any failure. **`LeadSource`** union
+  (SDK default `"sdkForm"`). **`IdentifyPayload`**, **`IdentifyResult`**.
+- **`ensureIdentified({ transport, environmentId, formId, source?, preview? })`**
+  — the boot step: fresh cache skips the network; otherwise fingerprints,
+  carries cached ids forward, caches the result.
+- **`readLeadData()`** / **`writeLeadData(data)`** +
+  **`LEAD_DATA_STORAGE_KEY`** (`"surfaceLeadData"`), **`LEAD_DATA_TTL_MS`**
+  (10 min) — the tag-compatible identity cache: on a page that also runs the
+  Surface tag, both read the same entry and agree on the visitor.
+
+### 7.6 Analytics / events
+
+- **`createPushEventClient({ transport, preview? })`** — the internal event
+  pipeline (`POST /api/v1/pushEvent`): bot filter, drop-on-invalid,
+  beacon-first. **`buildStepTransitionEventBatch`** builds the
+  `form_step_submitted` + `form_step_viewed` pair. Wire types exported
+  (`PushEventPayload`, `PushEventBatch`, `SurfaceEventType`, …).
+- **`createFormJourneyTracker({ transport, preview? })`** — step-journey
+  telemetry (`POST /api/v1/form-journey/track`): visit ordinals, 50-visit cap,
+  terminal freeze, microtask coalescing. Types: `FormJourneyTracker`,
+  `FormJourneyOutcome`, `FormJourneyTransitionReason`, ….
+- **`createJourneyTracker({ transport, environmentId })`** +
+  **`JOURNEY_COOKIE_NAME`** / **`RECENT_VISIT_COOKIE_NAME`** — the `journey:
+true` page-view module (tag-compatible cookies, duplicate-URL skip, SPA
+  history patching; `observeRouteChanges()` returns a teardown).
+- **`observeFormView(element, onViewed)`** — IntersectionObserver, fires once
+  (immediately when IO is unavailable).
+- **`observeDropoff(pushEvents, getState)`** — `form_step_dropoff` on
+  `pagehide` (never for bfcache suspensions, only after the form started).
+- **`createStartedDetector(initialAnswers)`** — returns a checker that fires
+  true exactly once, on the first deep-inequality vs the snapshot.
+- **`createEmitter<EventMap>()`** — the typed, instance-scoped emitter
+  primitive (`Emitter`, `Unsubscribe`); handler exceptions are isolated.
+
+### 7.7 Page context
+
+- **`buildUrlData({ trackCookies?, defaultUrl? }): UrlData`** +
+  **`constructUrlParamsObject`** / **`parseCookiesObject`** — the `URL_DATA`
+  attribution entry (fullUrl/params/referrer/cookies) read from the page.
+- **`parsePrefillParams(search)`** / **`parseQuestionId`** — the
+  `?<questionId>_<fieldName>=value` URL-prefill syntax (splits on the FIRST
+  underscore; `url`/`referrer`/`cookies` reserved).
+- **`buildRedirectUrl(url, { leadId?, sessionId? })`** /
+  **`performRedirect({ url, type, preview? })`** +
+  **`DEFAULT_REDIRECT_TIMEOUT_MS`** (400 ms), **`RedirectType`**
+  (`"NewTab" | "CurrentWindow"`) — ending-redirect helpers with the identity
+  handoff query params; preview never navigates.
+
+### 7.8 Scheduler + enrichment
+
+Full `SchedulerClient` signatures and widget options: [`reference/clients.md`](reference/clients.md) + [`reference/binding.md`](reference/binding.md).
+
+- **`createSchedulerClient({ transport, preview? }): SchedulerClient`** —
+  public Surface-scheduler endpoints: `getPublicEventType`,
+  `getAvailabilitySummary`, `getMonthAvailability` (`YYYY-MM`), `getSlots`,
+  `book` (threads `responseId`/`leadSessionId`/`fingerprint` into the booking
+  meta for booking↔response linkage), `reschedule`. Preview fabricates
+  bookings without network. Types: `Booking`, `TimeSlot`,
+  `AvailabilitySummary`, `BookingAttendee`.
+- **`toSchedulerAnswerState(booking)`** — the persisted scheduler answer
+  (emits `type: "DynamicScheduler"`; override `type` to the record's component
+  type).
+- **`mountBookingWidget(options)`** — see `llms.txt` (DOM tree, labels,
+  `formatters`, `data-value`).
+- **`attachEnrichment({ engine, transport, formId, sources })`** +
+  **`ENRICHMENT_STATE_ID`** (`"selfServeEnrichment"`), **`EnrichmentSource`** —
+  the real-time enrichment watcher: valid email/domain stable for the debounce
+  fires `POST /api/v1/services/enrichment/realtime` once per value; the result
+  becomes an external state that rides every save as `enrichedFields`.
+
+## 8. React — `import { useSurfaceForm } from "<package>/react"`
+
+**`useSurfaceForm(engine): UseSurfaceFormResult`** — a `useSyncExternalStore`
+adapter over any `FormEngine` (including the handle from `init`): returns
+`{ state, setAnswer, next, back, goToStep, submit, disqualify, savePartial,
+markViewed, on }`. `state` is referentially stable between engine mutations —
+render controlled inputs from it directly. React is an optional peer
+dependency; the main entry is React-free.
+
+## 9. Cross-cutting guarantees
+
+- **Zero runtime dependencies**; SSR-safe module scope; instance-scoped state
+  (multi-form pages work).
+- **Never break the host page**: transports resolve typed results instead of
+  throwing; event-handler exceptions are isolated.
+- **Preview writes nothing**: identify, responses, events, journey, enrichment,
+  tracking, and email validation (synthetic verdicts) are all blocked.
+- **Delivery**: creates + the finishing update are awaited; mid-form updates
+  and analytics are beacon-first fire-and-forget. `flush()` before
+  programmatic teardown.
+- Send `X-Surface-Sdk-Version` on everything — visible server-side for rate
+  limit observability.