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

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

@@ -0,0 +1,64 @@
+# Debugging an SDK form
+
+Symptom → cause → check, distilled from real field runs. Surface never sees the customer's HTML,
+so debugging always triangulates three views: the **browser console** (the SDK warns at runtime),
+**`validate_form_html`** (the static gate), and **response read-back**
+(`list_responses`/`get_response` — what actually landed). When in doubt, read a response back;
+that is the only end-to-end truth.
+
+## First moves, always
+
+1. `form.state()` in the browser console — `currentStepId`, `answers`, `responseId`, `finished`
+   tell you most of the story. `form.capabilities` tells you what's actually wired
+   (enrichment/emailValidation/tracking) in this environment.
+2. Attach a firehose while reproducing:
+   ```js
+   [
+     "viewed",
+     "started",
+     "stepChanged",
+     "stepCompleted",
+     "completed",
+     "disqualified",
+     "saved",
+     "error",
+   ].forEach((e) => form.on(e, (p) => console.log("[surface]", e, p)));
+   ```
+3. Re-run `validate_form_html` against the deployed HTML — drift since the last validation is the
+   most common root cause after any record edit.
+
+## Symptom table
+
+| Symptom                                           | Likely cause                                                                                                                                             | Check                                                                                                                 |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `init` throws "could not fetch runtime config"    | Wrong/missing `apiBaseUrl` — the error names the exact URL and host it tried                                                                             | Use the `apiBaseUrl` from `get_sdk_binding_map`; curl the URL from the error                                          |
+| No responses at all                               | `preview: true` left in the deployed page (blocks ALL writes)                                                                                            | Grep the page for `preview`; `saved` event never fires in preview                                                     |
+| No responses at all                               | Form never published — runtime-config serves the "not published yet" placeholder, so step/question ids don't match                                       | Console shows unbound-questionId warnings; `publish_form`                                                             |
+| Some answers missing                              | Binding drift: questionId unbound or misspelled                                                                                                          | Console warning "record declares questionIds with no bound element"; `validate_form_html`                             |
+| Some answers missing                              | Partial saves off and visitor abandoned mid-form                                                                                                         | `trackPartialResponses` in settings; expected behavior                                                                |
+| Finished response stored as a partial             | SDK < 0.1.3 sent the terminal write fire-and-forget; current SDK awaits it — remaining cause is tearing the page down mid-flight                         | Upgrade; `await form.submit()` then `await form.flush()` before any programmatic close                                |
+| 400 "Fields are missing or incorrectly formatted" | Hand-built `setAnswer` with the wrong shape (choice questions want structured lists, not label strings)                                                  | Compare the payload with the binding map's `answerShape`; prefer `data-*` binding, which builds choice answers itself |
+| Choice answers wrong/empty                        | Radio/checkbox `value` attrs drifted from the record's option keys                                                                                       | `validate_form_html` warns option-key drift; diff against `choiceKeys`                                                |
+| Same email accepted one day, rejected the next    | Fail-open verdict (`isValid: true, failed: true`) later resolving to a definitive one — expected waterfall behavior, not a bug                           | Check `failed` on the verdict; don't write tests expecting stable verdicts for fresh domains                          |
+| Thank-you never shows                             | Record has no `endStepKind: "thank_you"` step, or the HTML has no container for it                                                                       | Binding map: does a step carry `endStepKind`? Submit reveals it automatically when it exists                          |
+| Disqualified visitors see the thank-you           | No `endStepKind: "disqualified"` step; or page routes them manually to the wrong container                                                               | Same check; `disqualify()` only reveals a `disqualified` ending                                                       |
+| Steps don't switch                                | `data-step-id` doesn't match record stepIds, or goto target invalid                                                                                      | Console warns on invalid `goToStep`; `validate_form_html` blocks unknown step ids                                     |
+| Duplicate responses per visitor                   | `init` called more than once without `destroy()` (SPA remounts)                                                                                          | One engine per page-life; call `form.destroy()` on teardown                                                           |
+| GTM/GA4/Meta events not firing                    | Preview mode (tracking is fully blocked in preview), or settings not set                                                                                 | Deployed page without preview; `window.dataLayer` after a step submit; settings via `update_form_settings`            |
+| Conversions (ads rules) not firing                | Rules gate on the trigger + URL conditions; terminal rules only fire on `completed`, never on disqualify; everything queues until the first `responseId` | Check rule trigger/conditions in the dashboard; watch for the `saved` event before expecting queued fires             |
+| Enrichment fields empty                           | The environment has no ENABLED enrichment provider — a record-declared `enrichmentSourceField` is then silently inert                                    | `form.capabilities.enrichment` (false = inert); `debug: true` warns at boot; enable a provider in the dashboard       |
+| Lead attribution missing                          | `identify` blocked (preview) or ad-blocked; re-identify after SPA route change                                                                           | `form.identify()`; network tab `identify` call                                                                        |
+
+## Reading a response back
+
+`list_responses` (newest first) → `get_response` with the id. Confirm: every expected questionId
+present, choice answers carry the structured list, `surfaceTagStatus: "sdk"` in meta, and — if a
+booking step exists — the scheduler answer has `eventScheduled: true` plus the meeting fields.
+A response that looks right here ends the client-side investigation.
+
+## When the record and HTML disagree about reality
+
+`get_sdk_binding_map` (draft AND `source: "live"`) is the arbiter: the live map is what the
+deployed SDK actually fetched; the draft map is what the next publish will make true. An HTML
+page validated against the draft but running against an older live record explains most
+"validator says fine, runtime disagrees" reports — publish, or validate against `source: "live"`.

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

@@ -0,0 +1,67 @@
+# Editing an existing SDK form
+
+The record and the HTML live in different places (Surface vs the user's project) and only stay
+consistent if every record edit is followed through to the HTML. This is the highest-drift-risk
+journey in the SDK: a record edit that ships without its HTML counterpart silently degrades data
+capture, and `validate_form_html` is the only gate that sees both sides.
+
+## The loop
+
+1. **Read the current record** — `get_form_structure` for the machine-address view (stepIds,
+   row/column addresses, questionIds), `get_sdk_binding_map` for what the HTML must bind. Note the
+   `revision` — pass it as `ifRevision` on every write so a concurrent edit fails loudly instead of
+   interleaving.
+2. **Edit the record** — `update_component` / `add_component` (with `placement`) /
+   `remove_component` / `update_step` / `batch_edit` (all-or-nothing, one `ifRevision` for the
+   whole batch — prefer it for multi-part restructures). `move_component` refuses on SDK forms;
+   position is presentation and lives in the HTML.
+3. **Re-fetch `get_sdk_binding_map` and diff against the HTML.** Every difference is work:
+   - **New question** → add its binding (`data-question-id`, `data-question-type`, field names per
+     `answerShape`). Until bound, it's a `validate_form_html` blocker (scheduler/file questions
+     excepted — their answers are written in code).
+   - **Removed question** → delete its binding; a stale `data-question-id` is a blocker (answers
+     would be dropped server-side).
+   - **Changed choice options** (`choiceKeys`) → update every radio/checkbox `value` to the new
+     keys. The SDK builds answers from control values, so stale values submit options that no
+     longer exist — `validate_form_html` warns on exactly this drift.
+   - **Changed IdentityInfo fields** (`fieldNames`) → update the `data-field-name` attributes.
+   - **New/removed steps** → add/remove the `data-step-id` container and adjust navigation markers
+     (`data-surface-goto-step` targets pointing at a removed step are blockers).
+4. **`validate_form_html`** with the updated HTML against `source: "draft"` (the default). Fix
+   every blocker; re-run until clean.
+5. **`validate_form`** if the edit touched more than presentation-adjacent content.
+   (`simulate_response` does not apply to SDK forms — it evaluates record routing.)
+6. **`publish_form` with `confirm: true`.** Draft edits are invisible to the SDK until this —
+   and once a form has been published, `preview: true` serves the LIVE config, not the draft
+   (the draft path needs a never-published form plus the `previewToken` from
+   `get_sdk_binding_map`). So for edits to a published form, `validate_form_html` is the
+   pre-publish gate; there is no draft preview.
+7. **Deploy the HTML change and publish the record together.** If the HTML deploy and
+   `publish_form` can't be simultaneous, sequence by change type — every ordering has a
+   divergence window, so pick the one whose window degrades least:
+   - **Additions → publish the record first.** During the window the old HTML doesn't show the
+     new question, so responses arrive without it — nothing errors, but a newly-required
+     question goes unanswered until the deploy lands (SDK ingest does not enforce `required`
+     server-side). If that gap is unacceptable, hold the publish until the deploy is ready to
+     go out with it. The reverse order is strictly worse: deployed bindings for a questionId
+     that isn't on the live record yet let visitors answer a visible question whose answer is
+     dropped server-side.
+   - **Removals or choice-key changes → deploy the HTML first.** The stale record briefly
+     declares a question nobody is asked (harmless); the reverse leaves visitors answering
+     removed questions or submitting stale option keys.
+     Never leave the two sides diverged longer than a deploy cycle.
+8. **Read back one response** (`list_responses` / `get_response`) after the first post-edit
+   submission and confirm the changed answers landed with the expected shape.
+
+## Record-side effects worth knowing
+
+- Changing a question's text also updates its label (`questionName`) if the label was never
+  customized — the responses table follows automatically.
+- Replacing an IdentityInfo's `fields[]` re-validates `enrichmentSourceField` against the new
+  keys; pointing it at a removed field is rejected in the same call (update or clear it together
+  with `fields`).
+- Content edits rebuild content-derived state (choice lists) but preserve `questionId`s — existing
+  HTML bindings and analytics survive a re-word.
+- `update_form_settings` changes (tracking ids, language, partial-response gates) propagate to the
+  edge on confirm and do NOT need a `publish_form` — but allow a few minutes for the CDN response
+  cache to roll over before verifying.

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

@@ -0,0 +1,222 @@
+# SDK form HTML patterns
+
+Concrete shapes for the authoring step. Substitute the real `environmentId`/`formId`/
+`questionId`/`stepId`/`apiBaseUrl` values from `get_sdk_binding_map` — never invent ids.
+Class names and layout are examples; keep the user's own markup style.
+
+## Boot — script tag (plain HTML page)
+
+```html
+<form id="contact-form">
+  <!-- bindings here -->
+</form>
+<script src="/vendor/surface-forms-sdk.min.js"></script>
+<script>
+  SurfaceFormsSDK.SurfaceForms.init({
+    environmentId: "env_xxx",
+    formId: "form_xxx",
+    apiBaseUrl: "https://…", // from get_sdk_binding_map — required off the default host
+    container: document.querySelector("#contact-form"),
+    preview: true, // remove before deploying
+    previewToken: "…", // with preview: true, serves a never-published form's DRAFT config
+  });
+</script>
+```
+
+ESM projects: `import { SurfaceForms } from "@parag.more.withsurface.com/forms-sdk"` (substitute the
+installed package name) and pass the same options.
+
+## Single-step form
+
+No `data-step-id` needed. The `<form>` container's native submit finishes, so a plain submit button works; `surface-submit-button` is for non-form containers or extra buttons.
+
+```html
+<form id="contact-form">
+  <label
+    >Work email
+    <input type="email" data-question-id="q_email" data-question-type="ShortInput" data-field-name="input" />
+  </label>
+  <label
+    >Company size
+    <select data-question-id="q_size" data-question-type="Dropdown">
+      <option>1-10</option>
+      <option>11-50</option>
+    </select>
+  </label>
+  <button type="submit">Send</button>
+</form>
+```
+
+Note the email input: when the record's component is `ShortInput`, the explicit attributes
+override the SDK's `type=email → EmailForm` inference. The Dropdown's `<select>` infers its
+state key (`selected`); its option values must equal the record's option keys.
+
+## Choice question (radios/checkboxes)
+
+The SDK builds the structured answer from the whole group — `data-question-type` on the container is REQUIRED, each control's `value` must equal the record option key exactly, and no `data-field-name` is set:
+
+```html
+<fieldset data-question-id="q_role" data-question-type="MultipleOptionsQuestion">
+  <label><input type="radio" name="role" value="Revenue / Sales Ops" /> Revenue / Sales Ops</label>
+  <label><input type="radio" name="role" value="Sales leadership" /> Sales leadership</label>
+  <label><input type="radio" name="role" value="Other" /> Other</label>
+</fieldset>
+```
+
+Multi-select records use checkboxes with the same markup. `validate_form_html` cross-checks the control values against the record's options.
+
+## Multi-step with a branch, disqualify, and a thank-you ending
+
+One `data-step-id` container per record step — the SDK shows one at a time (mark the
+containers after the first `hidden` to avoid a boot flash). The branch is the page's own
+buttons; the record has no routing. The submit button lives on the LAST QUESTION step: after
+the terminal write the SDK reveals the record's `endStepKind: "thank_you"` step by itself
+(and the `"disqualified"` one on disqualify).
+
+```html
+<form id="qualify-form">
+  <section data-step-id="step_role">
+    <label
+      >Your role
+      <input data-question-id="q_role" />
+    </label>
+    <button type="button" data-surface-goto-step="step_company">I'm a buyer</button>
+    <button type="button" class="surface-disqualify-button">Just browsing</button>
+  </section>
+
+  <section data-step-id="step_company" hidden>
+    <label
+      >Company
+      <input data-question-id="q_company" />
+    </label>
+    <button type="submit" class="surface-submit-button">Finish</button>
+  </section>
+
+  <section data-step-id="step_done" hidden>
+    <p>Thanks — we'll be in touch.</p>
+  </section>
+</form>
+```
+
+Dynamic branching instead of static buttons: keep a handle from `init` and call
+`form.goToStep(stepId)` / `form.disqualify()` from your own logic, and declare
+`data-surface-nav="js"` on any element so `validate_form_html` knows navigation/submit is
+code-driven. Full event list for your own listeners: `viewed`, `started`, `stepChanged`,
+`stepCompleted`, `completed`, `disqualified`, `saved`, `error`.
+
+## Multi-field component
+
+`data-field-name` resolves per control — set it on each input, not (only) the wrapper. `IdentityInfo` is the standard contact-details component; bind only the fields the record declares (its `fieldNames` in the binding map):
+
+```html
+<div data-question-id="q_contact" data-question-type="IdentityInfo">
+  <input data-field-name="firstName" placeholder="First name" />
+  <input data-field-name="lastName" placeholder="Last name" />
+  <input type="email" data-field-name="workEmailAddress" placeholder="Work email" />
+</div>
+```
+
+## Scheduler step (Surface scheduler)
+
+A `CalendlyScreen` with `calendarType: "Surface"` renders through the SDK's own unstyled widget — never iframe the hosted booking page, and never bind the question in HTML (the `onComplete` writes the answer):
+
+```html
+<section data-step-id="step_book" hidden>
+  <div id="booking"></div>
+</section>
+<script>
+  const { createSchedulerClient, createTransport, mountBookingWidget, toSchedulerAnswerState } =
+    SurfaceFormsSDK;
+  const scheduler = createSchedulerClient({ transport: createTransport({ apiBaseUrl }), preview: PREVIEW });
+  mountBookingWidget({
+    container: document.querySelector("#booking"),
+    scheduler,
+    eventTypeId: "evt_xxx", // the record's CalendlyScreen content.eventTypeId
+    identity: { responseId: form.state().responseId ?? undefined },
+    onComplete(booking) {
+      form.setAnswer("q_booking", { ...toSchedulerAnswerState(booking), type: "CalendlyScreen" });
+      form.submit();
+    },
+  });
+</script>
+```
+
+The widget emits semantic markup under stable `surface-booking-*` classes (full DOM tree in
+`llms.txt`) and injects no CSS — style from the page. Labels are locale-formatted by default
+with the raw value on each element's `data-value`; pass `formatters: { month?, date?, time? }`
+to override the copy. In preview mode the client returns a synthetic booking, so the flow is
+testable offline.
+
+## React adapter (SPA)
+
+Headless mode: `init` without `container` (no `data-*` binding), one engine per mounted form, `destroy()` on unmount — remounting without destroy creates duplicate responses. Answers are set imperatively with the exact `answerShape` from the binding map (choice questions included — there is no group auto-build without the bind layer).
+
+```tsx
+import { SurfaceForms, type SurfaceForm } from "@parag.more.withsurface.com/forms-sdk";
+import { useSurfaceForm } from "@parag.more.withsurface.com/forms-sdk/react";
+import { useEffect, useState } from "react";
+
+export function QualifyForm() {
+  const [form, setForm] = useState<SurfaceForm | null>(null);
+
+  useEffect(() => {
+    let handle: SurfaceForm | null = null;
+    let disposed = false;
+    void SurfaceForms.init({
+      environmentId: "env_xxx",
+      formId: "form_xxx",
+      apiBaseUrl: "https://…", // from get_sdk_binding_map
+    }).then((created) => {
+      if (disposed) created.destroy();
+      else {
+        handle = created;
+        setForm(created);
+      }
+    });
+    return () => {
+      disposed = true;
+      handle?.destroy();
+    };
+  }, []);
+
+  if (!form) return null;
+  return <QualifySteps form={form} />;
+}
+
+function QualifySteps({ form }: { form: SurfaceForm }) {
+  const { state, setAnswer, goToStep, disqualify, submit } = useSurfaceForm(form);
+  const role = (state.answers[state.currentStepId]?.q_role as { input?: string })?.input ?? "";
+
+  if (state.currentStepId === "step_role") {
+    return (
+      <section>
+        <input
+          value={role}
+          onChange={(e) => setAnswer("q_role", { type: "ShortInput", input: e.target.value })}
+        />
+        <button onClick={() => goToStep("step_company")}>I'm a buyer</button>
+        <button onClick={() => disqualify()}>Just browsing</button>
+      </section>
+    );
+  }
+  if (state.currentStepId === "step_done") return <p>Thanks — we'll be in touch.</p>;
+  return (
+    <section>
+      {/* … company inputs … */}
+      <button onClick={() => submit()}>Finish</button>
+    </section>
+  );
+}
+```
+
+`state` is `useSyncExternalStore`-backed: referentially stable between engine mutations, safe to render from directly. `submit()`/`disqualify()` move `state.currentStepId` to the record's matching ending step, so the same step-switch renders the confirmation. On SPA route changes call `form.identify()` to re-attribute the visitor; on programmatic teardown after a submit flow, `await form.flush()` first.
+
+## Tracking setup
+
+Tracking is settings-driven and needs no page code — the SDK bootstraps the vendors and fires the same events as native forms (`SurfaceFormStarted`, `SurfaceFormStepSubmitted`, `SurfaceFormSubmitEvent` on GTM's dataLayer; Meta `trackCustom`; GA4 events).
+
+- **Set via MCP**: `update_form_settings` accepts `gtmId`, `gaMeasurementId`, `metaPixelId`, `trackPartialResponses`, `trackCookie` (two-phase: preview → `confirm: true`). Ad-conversion rules (`adsConversions`) and HubSpot are **not settable via MCP** — the user configures those in the dashboard (Form settings → tracking).
+- **Or pass at init**: `SurfaceForms.init({ settings: { gtmId, gaMeasurementId, metaPixelId, adsConversions } })` — caller values win over the record's, which lets a customer wire conversions entirely client-side.
+- **Preview blocks tracking entirely** (no vendor scripts load, nothing fires) — always verify on a deployed non-preview page.
+- **Verify**: complete a step, then inspect `window.dataLayer` for `SurfaceFormStepSubmitted` (its `stepId` is the real step id and the submit event carries `formId`). Conversion rules fire once per rule per response, queue until the first save produces a `responseId`, and terminal rules fire on completion only — never on disqualify.
+- `form.capabilities.tracking` tells you whether any tracking config is active for this init.