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

package/docs/reference/binding.md

@@ -0,0 +1,116 @@
+# Reference — DOM binding, booking widget, React adapter
+
+Exhaustive reference for the `bind/` layer and the React subpath. Map of everything:
+[`../api.md`](../api.md). Concrete HTML shapes:
+[`../../skills/surface-forms-sdk/patterns.md`](../../skills/surface-forms-sdk/patterns.md).
+
+## `bindForm({engine, root, expectedQuestionIds?}): () => void`
+
+Makes plain `data-*` HTML drive a `FormEngine` with zero authored JS. `init` calls it when
+`container` is passed; use directly with your own engine. Returns a full teardown. Exact
+behavior:
+
+### Field discovery + resolution
+
+- Bound elements are everything with `data-question-id` under `root` (the element itself when it
+  IS an `input`/`select`/`textarea`, otherwise every such control inside it).
+- **Nearest-wrapper rule**: a control inside a NESTED `data-question-id` wrapper belongs to the
+  inner question only — it never also binds an outer one.
+- **Field name per control** (`fieldNameFor`): wrapper `data-field-name` ?? control
+  `data-field-name` ?? inferred — `"selected"` for a `<select>` on a Dropdown, `"email"` for
+  `input[type=email]`, else `"input"`.
+- **Question type** (`questionTypeFor`): wrapper `data-question-type` ?? control attr ??
+  inferred — `input[type=email]` → `EmailForm`, else `ShortInput`. Every answer carries `type`
+  (the wire validates a discriminated union).
+- **Values**: checkboxes contribute `checked` (boolean), radios their `value`, everything else
+  `field.value`. Multi-field components accumulate into ONE state per question
+  (`{firstName, lastName, …}`).
+- **Pre-filled values are seeded at bind time**: non-empty DOM values (SSR, autofill, values set
+  before init resolved) are captured immediately, not only on the next input event.
+
+### Choice groups (`CHOICE_ANSWER_BUILDERS`)
+
+For containers whose type is one of the five choice components, the answer is built from the
+whole radio/checkbox group (never per control; `data-field-name` is ignored on the options):
+
+| Type                                            | Built answer                                                                               |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `MultipleOptionsQuestion`                       | `{choices: [{key: option.value, value: option.checked, index}, …]}` — the FULL option list |
+| `MultipleChoiceQuestion` / `MMChoiceQuestion`   | `{choices: [{key, value}, …]}` — full list, no index                                       |
+| `GraphicOptions` / `MultipleChoiceSingleAnswer` | `{value, index}` of the checked option (`{value: "", index: -1}` when none)                |
+
+Control `value` attributes must equal the record's option keys exactly. A stray text control in
+the group (an "Other" input) is left to the author's own `setAnswer`.
+
+### Navigation markers
+
+Selector: `[data-surface-goto-step], .surface-disqualify-button, .surface-submit-button,
+.surface-next-button`. ONE action per element, most specific wins, in priority order: `goto` →
+`disqualify` → `submit` → `next`. `goto` failures (unknown step) are caught and console-warned,
+never thrown into the page. A `<form>` root's native `submit` event is also intercepted
+(`preventDefault`) and finishes the form.
+
+### Step visibility
+
+On every `stepChanged` (and at bind), each `[data-step-id]` container gets
+`hidden = (its id !== currentStepId)` — one visible step at a time. Single-step records may omit
+containers. (Author containers after the first as `hidden` in the HTML to avoid the pre-init
+flash.)
+
+### View detection + drift warning
+
+- `observeFormView(root, () => engine.markViewed())` is wired automatically.
+- `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`.
+
+## `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.
+
+### 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.                              |
+
+### Behavior + DOM
+
+- Every month/date/slot element carries its raw value in `data-value` (`YYYY-MM`, `YYYY-MM-DD`,
+  ISO instant) — relabel or assert without parsing text.
+- Async renders are generation-guarded: a stale fetch resolving after navigation never touches
+  the DOM; teardown ignores in-flight results.
+- Errors render `p.surface-booking-error` + `button.surface-booking-retry`; a failed booking
+  keeps the form up with the error appended; the submit button disables while booking.
+- No CSS is injected; the full class tree (also in `llms.txt`):
+
+```
+div.surface-booking
+├─ p.surface-booking-month [data-value]        (or p.surface-booking-loading / error+retry)
+├─ div.surface-booking-month-nav > button.surface-booking-month-button ×2
+└─ ul.surface-booking-dates > li.surface-booking-date > button.surface-booking-date-button [data-value]
+                              (li.surface-booking-no-dates when empty)
+-- date picked --  p.surface-booking-day [data-value] · button.surface-booking-back
+                   ul.surface-booking-slots > li.surface-booking-slot > button.surface-booking-slot-button [data-value]
+-- slot picked --  form.surface-booking-form > input.surface-booking-name + input.surface-booking-email + button.surface-booking-submit
+-- booked --       p.surface-booking-booked
+```
+
+## React — `useSurfaceForm(engine): UseSurfaceFormResult` (from `<package>/react`)
+
+`useSyncExternalStore` adapter over any `FormEngine` (including the `init` handle). Returns
+`{state, setAnswer, next, back, goToStep, submit, disqualify, savePartial, markViewed, on}` —
+`state` re-renders on engine mutations and is referentially stable between them. React ≥18 is an
+optional peer dependency; the main entry stays React-free. One engine per mounted form;
+`destroy()` on unmount (see the SPA pattern in
+[`patterns.md`](../../skills/surface-forms-sdk/patterns.md)); init-level members not on the hook
+(`flush`, `mergeMeta`, `validateEmail`, `capabilities`, `identify`, `destroy`) are read from the
+handle itself.

package/docs/reference/clients.md

@@ -0,0 +1,212 @@
+# Reference — transport, runtime config, responses, scheduler, email validation, enrichment
+
+Exhaustive reference for the `core/client` domain plus the watcher modules that ride on it.
+Map of everything: [`../api.md`](../api.md).
+
+## Transport (`core/client/transport`)
+
+- **`DEFAULT_API_BASE_URL`** = `"https://forms.withsurface.com"`.
+- **`SDK_VERSION`** rides every request: header `X-Surface-Sdk-Version` on fetch paths, `?sdv=`
+  query param on beacons (sendBeacon cannot carry headers).
+- **`createTransport({apiBaseUrl?}): Transport`** — trailing slash stripped; all paths resolve
+  absolute against it (SDK pages are customer-hosted, always cross-origin).
+
+```ts
+type Transport = {
+  get: <T>(path) => Promise<TransportResult<T>>;
+  post: <T>(
+    path,
+    payload,
+    opts?: { keepalive?: boolean; credentials?: boolean }
+  ) => Promise<TransportResult<T>>;
+  /** true only when sendBeacon queued it; the fire-and-forget fetch fallback reports false. */
+  beacon: (path, payload) => boolean;
+};
+type TransportResult<T> = { ok: true; data: T } | { ok: false; error: TransportError };
+type TransportError = { kind: "network"; cause: unknown } | { kind: "http"; status: number; body?: unknown };
+```
+
+Never throws — always a typed result (the never-break-the-host-page guarantee). `credentials:
+true` sends cookies (the `{formId}_pa` repeat-visitor cookie lives on the API origin;
+`SameSite=None; Secure`, so only credentialed requests carry it cross-origin). The beacon
+fallback fetch is always credentialed (matches sendBeacon's behavior); unserializable payloads
+are swallowed.
+
+## Runtime config (`core/client/runtimeConfig`)
+
+- **`fetchRuntimeConfig(transport, formId, {preview?, previewToken?})`** →
+  `GET /api/v1/public/forms/{formId}/runtime-config` — the same payload the hosted page reads.
+  `preview: true` appends `?preview=1` (+`&pt=<previewToken>`): a NEVER-published form serves its
+  draft config when the token validates; otherwise the published config (a placeholder step for
+  never-published forms). `settings.password` never arrives (server-stripped; gated forms
+  validate via `POST /api/v1/check-password`).
+
+```ts
+type RuntimeConfig = {
+  id: string;
+  name?: string;
+  environmentId?: string;
+  config: { steps?: Array<{ id; endStepKind?; components? }> } & Record<string, unknown>;
+  settings?: ({ trackPartialResponses?: boolean; trackCookie?: boolean } & Record<string, unknown>) | null;
+};
+```
+
+Helpers over a fetched config (all tolerate grid-layout or flat component arrays):
+
+- **`stepsOf(config)`** → ordered `{id, endStepKind?}[]` — the engine's `steps` input.
+- **`statefulQuestionsOf(config)`** → `{questionId, componentType?}[]` (answer-recording
+  components); **`statefulQuestionIdsOf(config)`** → just the ids.
+- **`enrichmentSourcesOf(config)`** → `{questionId, fieldNames}[]`: IdentityInfo fires on its
+  configured `enrichmentSourceField` (default `emailAddress`) and always on `websiteUrl`;
+  EmailForm on `email`.
+- **`hasEnabledEnrichmentProvider(settings)`** — v2 enrichment config with ≥1 enabled provider
+  exposing fields (the runtime gate for automatic enrichment).
+
+## Responses (`core/client/responses`)
+
+- **`submitResponse(transport, payload)`** → `POST /api/v1/responses/` (awaited, credentialed —
+  reads/refreshes the `{formId}_pa` cookie). Returns
+  `CreateResponseResult = { responseId, leadId: string|null, resumeToken: string|null }`; a 200
+  without an id is normalized to an http error.
+- **`updateResponse(transport, payload)`** → beacon to `/api/v1/responses/update`
+  (fire-and-forget; the engine uses an awaited keepalive post for the FINISHING update — see
+  [`engine.md`](engine.md)).
+
+## Scheduler (`core/client/scheduler`)
+
+- **`createSchedulerClient({transport, preview?}): SchedulerClient`** — public Surface-scheduler
+  endpoints; shapes mirror the native booking UI byte-for-byte. `preview: true`: queries carry
+  `preview=true`, and `book()` resolves a fabricated booking with NO network call.
+
+```ts
+type SchedulerClient = {
+  getPublicEventType: <T = unknown>(eventTypeId) => Promise<TransportResult<T>>;
+  getAvailabilitySummary: (args: {
+    eventTypeId;
+    timezone?;
+  }) => Promise<TransportResult<{ data?: AvailabilitySummary }>>;
+  getMonthAvailability: (args: {
+    eventTypeId;
+    month /* "YYYY-MM" */;
+    timezone;
+    duration?;
+    hostId?;
+    ownerEmail?;
+  }) => Promise<TransportResult<{ data?: { dates?: unknown[]; resolvedHost? } }>>;
+  getSlots: (args: {
+    eventTypeId;
+    date /* "YYYY-MM-DD" */;
+    timezone;
+    duration?;
+    hostId?;
+    ownerEmail?;
+  }) => Promise<TransportResult<{ data?: { slots?: TimeSlot[] } }>>;
+  book: (args: {
+    eventTypeId;
+    startTime;
+    endTime /* required; preview fabrication only, never sent */;
+    timezone;
+    inviteeName;
+    inviteeEmail;
+    duration?;
+    intakeResponses?;
+    guestEmails?;
+    captchaToken?;
+    responseId?;
+    leadSessionId?;
+    fingerprint?;
+    hostRouting?;
+  }) => Promise<TransportResult<Booking>>;
+  reschedule: (args: {
+    bookingId;
+    rescheduleToken;
+    newStartTime;
+    timezone;
+  }) => Promise<TransportResult<Booking>>;
+};
+type Booking = {
+  id;
+  startTime;
+  endTime;
+  timezone;
+  inviteeName;
+  inviteeEmail;
+  meetingJoinLink: string | null;
+  cancelToken;
+  rescheduleToken;
+  attendees: BookingAttendee[];
+};
+type BookingAttendee = { name; email; isHost: boolean };
+type TimeSlot = { start: string; end: string }; // ISO instants
+type AvailabilitySummary = {
+  has_availability;
+  available_slots_7d;
+  available_slots_14d;
+  available_slots_30d;
+  available_days_7d;
+  next_available_date: string | null;
+  total_available_slots;
+  rep_meeting_count_today;
+};
+```
+
+`book()`'s `responseId`/`leadSessionId`/`fingerprint` thread into the booking meta block — the
+server links booking↔response with them; pass what you have.
+
+- **`toSchedulerAnswerState(booking): Record<string, unknown>`** — the persisted scheduler
+  answer (`SchedulerAnswer` shape, [`engine.md`](engine.md)). Emits `type: "DynamicScheduler"` —
+  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).
+
+## Email validation (`core/client/emailValidation` + `validation/attachEmailValidation`)
+
+- **`createEmailValidator({transport, environmentId, preview?}): EmailValidator`** —
+  `POST /api/v1/edge/emailValidation` (provider waterfall + the environment's spam blacklist;
+  vendor keys stay server-side).
+  - `validate(email)` / `validateBatch(emails)`; a batch posts only uncached addresses and shares
+    one request.
+  - **Per-address Promise cache** for the validator's lifetime — successes AND failures stick, so
+    nothing is ever billed twice and concurrent calls share the in-flight request.
+  - **Fail-open**: request failure or `validationSuccessfullyRan: false` →
+    `{isValid: true, status: "unknown", reason: "validation_failed", failed: true}`. The same
+    address can later resolve definitively — design for the transition, check `failed` to
+    soft-warn.
+  - `preview: true` → synthetic `{isValid: true, status: "preview"}` with no network.
+
+```ts
+type EmailValidationResult = {
+  email;
+  isValid: boolean;
+  status?;
+  reason?;
+  blacklistEntryIds?: string[];
+  failed?: boolean;
+};
+```
+
+- **`attachEmailValidation({engine, validator}): () => void`** — the `emailValidation: true`
+  watcher: watches answer keys `email`/`emailAddress`/`workEmailAddress`, debounces 300 ms
+  (native's), flushes on `stepCompleted`/`completed`, then merges native's response-meta keys via
+  `engine.mergeMeta`: `isEmailValid` (ANY currently-present email valid; fail-open counts valid),
+  `emailValidation` (`{status, reason, blacklistEntryIds?}` of the first detailed verdict),
+  `emailValidationFailed` (any verdict failed). The aggregation window follows the LIVE answers —
+  a replaced address's verdict stops describing the response; verdicts landing after the finish
+  amend the stored response. Returns a teardown.
+
+## Enrichment (`enrichment/attachEnrichment`)
+
+- **`attachEnrichment({engine, transport, formId, sources}): () => void`** — real-time identity
+  enrichment. Watches the `sources` (`{questionId, fieldNames}[]`, from `enrichmentSourcesOf`);
+  a value that is a valid email or domain and stable for 1 s fires
+  `POST /api/v1/services/enrichment/realtime` ONCE per value (deduped, in-flight guarded);
+  `stepCompleted`/`completed` flush the pending debounce. The result is stored via
+  `engine.setExternalState(ENRICHMENT_STATE_ID, …)` — riding every save as `enrichedFields` and
+  readable at `state().externalStates.selfServeEnrichment.data` for caller autofill. The request
+  is never awaited (submission must not block on the vendor); a post-finish result amends the
+  stored response. Returns a teardown.
+- **`ENRICHMENT_STATE_ID`** = `"selfServeEnrichment"`; **`EnrichmentSource`** =
+  `{questionId, fieldNames}`.
+- `init` wires this automatically only when the record was fetched AND
+  `hasEnabledEnrichmentProvider(settings)` — check `form.capabilities.enrichment`.

package/docs/reference/engine.md

@@ -0,0 +1,193 @@
+# Reference — engine, answer states, payloads, page-context helpers
+
+Exhaustive reference for the `core/engine` domain. Map of everything: [`../api.md`](../api.md).
+
+## `createFormEngine(options): FormEngine`
+
+The headless core: answers, traversal, response writes, lifecycle events. `SurfaceForms.init`
+creates one for you; construct directly for offline/custom stacks.
+
+### Options
+
+| Option                  | Type                                                                  | Semantics                                                                                                                                                                                                                   |
+| ----------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `formId`                | `string`                                                              | Required.                                                                                                                                                                                                                   |
+| `environmentId`         | `string?`                                                             | Stamped on `form_viewed`/`form_completed` events.                                                                                                                                                                           |
+| `steps`                 | `Array<{id, endStepKind?: "thank_you"\|"disqualified"}>`              | Required, ≥1 (throws on empty). The ordered data contract; `endStepKind` drives the ending-step reveal.                                                                                                                     |
+| `transport`             | `Transport`                                                           | Required.                                                                                                                                                                                                                   |
+| `resolveNextStep`       | `(currentStepId, answers) => {stepId, reason?} \| "END" \| "INVALID"` | Routing hook consulted by `next()`/`submit()`. `"END"` finishes, `"INVALID"` disqualifies, a step object advances (its `reason` becomes the journey transition reason). Default: linear order, `"END"` after the last step. |
+| `trackPartialResponses` | `boolean` (default `true`)                                            | Gates every mid-form write. The FINISHING write always happens regardless.                                                                                                                                                  |
+| `trackCookies`          | `boolean` (default `false`)                                           | Rides the payload's cookie-meta gate.                                                                                                                                                                                       |
+| `externalStates`        | `ExternalStates?`                                                     | Seed pseudo-answers (e.g. a `URL_DATA` entry).                                                                                                                                                                              |
+| `meta`                  | `Record<string, unknown>?`                                            | Seed response meta; mutated in place by `mergeMeta` (rides every write by reference).                                                                                                                                       |
+| `identity`              | `() => {fingerprint?, leadSessionId?, leadId?}`                       | A GETTER read at every write/event — a later re-identify attributes subsequent writes to the fresh session.                                                                                                                 |
+| `pushEvents`            | `PushEventClient?`                                                    | Receives the lifecycle event stream (see [`events.md`](events.md)).                                                                                                                                                         |
+| `formJourney`           | `FormJourneyTracker?`                                                 | Receives step-journey visits/transitions/terminals.                                                                                                                                                                         |
+| `preview`               | `boolean` (default `false`)                                           | `write()` short-circuits — traversal and events run, responses are never created.                                                                                                                                           |
+| `resume`                | `{responseId, answers?}`                                              | Seeds the responseId (every write becomes an update — no duplicate row) and the stored answers (cloned, keyed under the FIRST step — the wire flattens steps; presentation is the caller's navigation).                     |
+
+### Methods
+
+- **`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.
+- **`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
+  step being LEFT, advances, emits `stepChanged`. Finished (`"END"`/`"INVALID"`/no next step) →
+  behaves like `submit()`/`disqualify()`.
+- **`back(): void`** — pops history, emits `stepChanged`, records a `back_nav` journey transition.
+  NEVER writes. No-op when history is empty or the form finished.
+- **`goToStep(stepId): Promise<void>`** — rejects unknown ids without touching state. Same-step
+  no-ops. A step already in history → rewinds like `back()` (no write). Otherwise a forward jump
+  with full forward semantics; journey reason `conditional_match` (the caller's own condition
+  chose the target).
+- **`submit(): Promise<void>`** — finishes: terminal write (`finished: true`), then reveals the
+  record's `thank_you` step (display-only step change, no write), records the journey terminal,
+  pushes `form_completed`, emits `completed`. When it resolves, the server HAS the response — see
+  Delivery below.
+- **`disqualify(): Promise<void>`** — finishes with `invalidResponse: true`; reveals the
+  `disqualified` ending; journey terminal carries
+  `disqualification: {reason: "conditional_match", atStepId}`; emits `disqualified`.
+- **`savePartial(): Promise<void>`** — explicit mid-form write. The stepId is captured at CALL
+  time, so a save queued behind an in-flight advance stays attributed to the step the caller was
+  on. Skipped silently if the form finishes before it runs.
+- **`flush(): Promise<void>`** — resolves when every write queued so far (including post-finish
+  amends) has settled.
+- **`markViewed(): void`** — once: pushes `form_viewed` + first-step `form_step_viewed`, emits
+  `viewed`.
+- **`setExternalState(id, {type, ...})`** — writes/replaces a pseudo-answer that rides every
+  subsequent save; post-finish it amends the stored response (below).
+- **`mergeMeta(partial)`** — `Object.assign` onto `meta`; rides the next save or amends
+  post-finish. (The `init` handle wraps this with a reserved-key guard.)
+- **`state(): FormEngineState`** — `{currentStepId, answers, externalStates, responseId,
+resumeToken, finished}`. The snapshot is cached until the next mutation, so it is referentially
+  stable — the `useSyncExternalStore` contract.
+- **`subscribe(listener): Unsubscribe`** — store subscription; fires on every state change.
+- **`on(event, handler): Unsubscribe`** — see Events.
+
+### Events (`FormEngineEvents`)
+
+| Event           | Payload                               | Fires                                                                                                                                |
+| --------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `viewed`        | `{formId}`                            | Once, from `markViewed`.                                                                                                             |
+| `started`       | `{formId}`                            | Once, first answer divergence.                                                                                                       |
+| `stepChanged`   | `{fromStepId, toStepId}`              | Every step move, incl. rewinds and the ending reveal.                                                                                |
+| `stepCompleted` | `{stepId}`                            | Leaving a step forward (also flush signal for debounced watchers).                                                                   |
+| `completed`     | `{formId}`                            | Successful non-disqualified finish.                                                                                                  |
+| `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.                                                                    |
+
+### Write serialization + delivery
+
+- One queue serializes every write-initiating call: a double-clicked `next()` joins the pending
+  advance (advances once); `submit()` during an in-flight `next()` queues behind it and then
+  finishes (submit intent never dropped); queued ops re-check `finished` when they run, so
+  nothing writes after the finishing submit.
+- First forward write CREATES the response (`POST /api/v1/responses/`, awaited, credentialed);
+  later writes UPDATE it. Every write resends the FULL answer set + external states.
+- A failed create: `error` event; `response_submission_error` pushEvent only for network-kind
+  failures (the server logs HTTP-level ones itself); the responseId stays null (the next write
+  retries the create).
+- **The terminal (finishing) update is awaited** `fetch(keepalive)`: `submit()` resolving means
+  delivery is confirmed. On failure: `error` event + one best-effort beacon fallback, and `saved`
+  does NOT fire. Mid-form updates are beacon-first fire-and-forget (the server's drop-off sweep
+  reconciles missed ones).
+- **Post-finish amends**: `setExternalState`/`mergeMeta` after the finish re-issue the terminal
+  update by extending the queue (full resends are idempotent; a result landing while the terminal
+  create is still in flight amends after it settles; a failed terminal create is never
+  resurrected as a new response).
+
+## Typed answer states (`core/engine/answerStates`)
+
+Exact wire shapes; contract-tested against the server schemas. `setAnswer` merges partials, so
+patching one key of a multi-field state is legal.
+
+```ts
+type ShortInputAnswer  = { type: "ShortInput"; input: string };
+type LongInputAnswer   = { type: "LongInput"; input: string };
+type EmailFormAnswer   = { type: "EmailForm"; email: string; subscriptionCheck?: boolean };
+type DropdownAnswer    = { type: "Dropdown"; selected: string | string[] };
+type DisclaimerAnswer  = { type: "Disclaimer"; check?: boolean };
+type FileUploaderAnswer = { type: "FileUploader"; fileUrl?: string };
+// The ENTIRE option list, one entry per record option — never only the picked one:
+type MultipleOptionsAnswer = { type: "MultipleOptionsQuestion";
+  choices: Array<{ key: string; value: boolean; index: number }>; selectedOther?: boolean };
+type MMChoiceAnswer        = { type: "MMChoiceQuestion";       choices: Array<{ key: string; value: boolean }> };
+type MultipleChoiceAnswer  = { type: "MultipleChoiceQuestion"; choices: Array<{ key: string; value: boolean }> };
+type GraphicOptionsAnswer  = { type: "GraphicOptions"; value: string; index: number };
+type MultipleChoiceSingleAnswerAnswer = { type: "MultipleChoiceSingleAnswer"; value: string; index: number };
+type IdentityInfoAnswer = { type: "IdentityInfo" } & Partial<Record<IdentityInfoAnswerKey, string>>;
+type SchedulerAnswer = { type: "CalendlyScreen" | "DynamicScheduler"; eventScheduled: boolean;
+  uri: string; meetingTime?: string; meetingEndTime?: string; ownerEmails?: string;
+  guestEmails?: string; inviteeName?: string; googleMeetLink?: string };
+type KnownAnswerState = /* union of all of the above */;
+```
+
+`IDENTITY_INFO_ANSWER_KEYS` (complete): `firstName`, `lastName`, `fullName`, `emailAddress`,
+`workEmailAddress`, `phoneNumber`, `companyName`, `numberOfEmployees`, `websiteUrl`, `title`,
+`streetAddress`, `aptSuiteEtc`, `city`, `state`, `country`, `zipCode`, `companyRevenue`,
+`profilePictureUrl`.
+
+## Response payload builders (`core/engine/responsePayload`)
+
+```ts
+type SingleFormResponse = { questionId: string; response: Record<string, unknown> };
+type AnswerStates = Record<stepId, Record<questionId, Record<string, unknown>>>;
+type ExternalStates = Record<stateId, { type: string } & Record<string, unknown>>;
+type FormResponsePayload = {
+  formId;
+  responses: SingleFormResponse[];
+  enrichedFields;
+  finished;
+  invalidResponse;
+  stepId;
+  fingerprint?;
+  leadSessionId?;
+  meta;
+  responseShapeVersion: "2.0";
+};
+type FormUpdateResponsePayload = Omit<FormResponsePayload, "responseShapeVersion"> & { responseId };
+```
+
+- **`buildResponsesArray(answers, externalStates)`** → `{responses, enrichedFields, bookingId?}` —
+  flattens ALL steps' answers plus every external state as a pseudo-answer keyed by its stateId;
+  skips `SCHEDULER_AVAILABILITY_DATA` (transient); detects a Surface-native booking (first answer
+  with `eventScheduled: true` and a non-Calendly/Cal.com `uri`) into `bookingId`; hoists the
+  enrichment state's fields into `enrichedFields` (existing keys win).
+- **`createSubmitResponsePayload(options)`** / **`createUpdateResponsePayload(options)`** — the
+  full wire payloads; every write resends everything (server-side UTM preservation depends on the
+  `URL_DATA` entry riding every update). Cookie capture inside `meta` is gated by `trackCookies`.
+
+## Page-context helpers
+
+### `core/engine/urlData`
+
+- **`buildUrlData({trackCookies?, defaultUrl?}): UrlData`** — the `URL_DATA` attribution entry:
+  `{type: "URL_DATA", fullUrl?, params?, referrer?, cookies?}` read directly from
+  `location`/`document` (self-hosted pages need no query-param relay). `defaultUrl` wins over
+  `location.href`; cookies only when `trackCookies`; malformed URLs are swallowed.
+- **`constructUrlParamsObject(url)`** — query params as a record (repeated params: last wins,
+  pinned native quirk).
+- **`parseCookiesObject(cookieString)`** — `document.cookie` → record.
+
+### `core/engine/urlPrefill`
+
+- **`parsePrefillParams(search): ParsedUrlQuestionId[]`** / **`parseQuestionId(input)`** — the
+  `?<questionId>_<fieldName>=value` prefill syntax. Splits on the FIRST underscore (field names
+  may contain more); both sides trimmed; `url`/`referrer`/`cookies` reserved for attribution;
+  params without an underscore ignored. `ParsedUrlQuestionId` =
+  `{originalId, questionId, fieldName, value}`.
+
+### `core/engine/redirect`
+
+- **`buildRedirectUrl(url, {leadId?, sessionId?})`** — appends `leadId`/`sessionId` query params
+  (identity handoff so the destination's tag/SDK resolves the same visitor). Blank → `""`;
+  unparseable → passed through unchanged. Protocol default pins native's `addProtocolToUrl`
+  including its quirk: the check is `startsWith("https")`, so an explicit `http://` URL gets
+  double-prefixed.
+- **`performRedirect({url, redirectType?, leadId?, sessionId?, preview?})`** — `"CurrentWindow"`
+  (default) sets `window.location`, `"NewTab"` opens a tab. `preview: true` never navigates.
+- **`DEFAULT_REDIRECT_TIMEOUT_MS`** = `400` (native's delay before an ending redirect).
+- **`RedirectType`** = `"NewTab" | "CurrentWindow"`.

package/docs/reference/events.md

@@ -0,0 +1,93 @@
+# Reference — event pipeline, journey telemetry, detectors, emitter
+
+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.)
+
+## Push events (`core/events/pushEvents`)
+
+- **`createPushEventClient({transport, preview?}): PushEventClient`** — the internal analytics
+  pipeline, `POST /api/v1/pushEvent`, beacon-first. Client-side bot filter (UA regex); any event
+  missing `type`/`entityType`/`entityId` drops the WHOLE request; `preview: true` blocks every
+  send. `push(request)` is fire-and-forget.
+- **`buildStepTransitionEventBatch({sessionId, formId, currentStepId, nextStepId, stepCompletionTime})`**
+  — the one batch shape the server accepts: `form_step_submitted` (with
+  `stepCompletionTime` property, seconds) + `form_step_viewed` for the next step.
+
+```ts
+type SurfaceEventType =
+  | "form_viewed"
+  | "form_started"
+  | "form_completed"
+  | "form_step_viewed"
+  | "form_step_submitted"
+  | "form_step_dropoff"
+  | "form_question_submitted"
+  | "response_submission_created"
+  | "response_submission_error";
+type SurfaceEventEntityType = "form" | "form_step" | "response";
+type PushEventProperty = { key: string; value: unknown };
+type PushEventPayload = {
+  type;
+  entityType;
+  entityId;
+  stepId?: string | null;
+  leadSessionId?: string | null;
+  properties?: PushEventProperty[];
+  leadId?;
+  environmentId?;
+};
+type PushEventBatch = { events: [submitted, viewed] }; // exactly the step-transition pair
+type PushEventRequest = PushEventPayload | PushEventBatch;
+type PushEventClient = { push: (request: PushEventRequest) => void };
+```
+
+## Form-journey telemetry (`core/events/formJourneyTracker`)
+
+- **`createFormJourneyTracker({transport, preview?}): FormJourneyTracker`** — step-journey
+  visits/transitions/outcomes beaconed to `POST /api/v1/form-journey/track`. Direct native port:
+  visit ordinals (revisits get new ordinals; back-nav never overwrites a prior enter time),
+  close-previous-visit timing (`exitedAt`/`durationMs`), 50-visit cap with `truncated`,
+  freeze-on-terminal-outcome, microtask coalescing (a transition immediately followed by a
+  terminal sends ONE beacon), synchronous flush for the `in_progress` terminal (pagehide-safe).
+  Sends only once a responseId is set.
+
+```ts
+type FormJourneyOutcome = "in_progress" | "completed" | "partial" | "disqualified" | "dropped_off";
+type FormJourneyTransitionReason = "initial" | "linear" | "conditional_match" | "back_nav" | …;
+type FormJourneyVisit = { ordinal; stepId; enteredAt; exitedAt?; durationMs?; fromStepId?;
+  transitionReason; transitionMeta? };
+type FormJourneyTrackPayload = { responseId; formId; outcome?; disqualification?:
+  { reason: "conditional_match"|"default_fallback"; matched? } | null;
+  disqualifiedAtStepId?; disqualifiedTriggerStepId?; events: FormJourneyVisit[] };
+interface FormJourneyTracker {
+  recordEntry(stepId): void;
+  recordTransition({fromStepId, toStepId, reason, transitionMeta?}): void;
+  recordTerminal({outcome, disqualification?: {reason, atStepId, triggerStepId?, matched?}}): void;
+  setResponseId(responseId): void;
+  setFormId(formId): void;
+  hasRecordedTransition(): boolean;
+}
+```
+
+## Detectors
+
+- **`observeFormView(element, onViewed): () => void`** — `form_viewed` detection:
+  IntersectionObserver on the bound root, fires the callback exactly once, then disconnects.
+  When IO is unavailable the callback fires immediately (counting a below-fold mount beats
+  losing view analytics). Returns a teardown.
+- **`createStartedDetector(initialAnswers): (current) => boolean`** — `form_started` detection:
+  snapshots (deep-clones) the initial answers; returns true exactly ONCE, on the first
+  deep-inequality (key-order insensitive) vs the snapshot.
+- **`observeDropoff(pushEvents, getState): () => void`** — `form_step_dropoff` on `pagehide`
+  (the only teardown event that still delivers beacons), only after the form started, never for
+  bfcache suspensions (`event.persisted`). `getState` is read at fire time:
+  `() => ({started, formId, stepId, sessionId})`. Returns a teardown.
+
+## Emitter primitive (`core/events/emitter`)
+
+- **`createEmitter<TEventMap>(): Emitter<TEventMap>`** — the typed, instance-scoped emitter the
+  engine's `on()` is built on. `on(event, handler) => Unsubscribe`; `emit(event, payload)`.
+  Handler exceptions are isolated per handler — a throwing host callback never breaks the engine
+  or sibling handlers. No module-level singletons: multi-form pages get independent emitters.
+- **`Unsubscribe`** = `() => void`.