@wix/agent-skills 1.20.0 → 1.20.1

package/skills/wix-headless-fast/references/forms/INSTRUCTIONS.md

@@ -8,16 +8,24 @@ every form has a different field set and no "contact form" component could ship
 
 ## The file map (deployed into `src/`)
 
-**Don't read the shipped files** — this table and the contracts below are everything you need.
-Open a shipped file's source only on a real fallback (runtime error / uncovered field kind).
+**On Astro and React the shipped files are tested and work as they are** — this table and the
+contracts below are everything you need to use them, so don't spend the run reading their source;
+wire them and build your surfaces. Reading them is the right move when something is off (a runtime
+error, a field kind this playbook doesn't cover) or when the brief wants a behaviour they don't
+offer — then read the file that owns it and change or extend it. On `lib`, `static`, and a port
+the hook doesn't deploy; the store behind it does, and the wiring sections below say what to
+read first. Files you edit: `SiteLayout.astro` and `styles/global.css`. Files you **create**
+(skeletons below): the form page and its island, plus your home page.
 
 | file | what it is |
 |---|---|
 | `wix/config.ts` · `wix/sdk.ts` · `wix/media.ts` · `wix/money.ts` | shared auth seam + helpers (deploy configures; nothing to set) |
-| `wix/forms/types.ts` | the DTOs (`FormDto`, `FormFieldDto`, `FormValues`, `FormErrors`) — contracts below |
-| `wix/forms/forms.ts` | `getForm`, `listForms` — the raw schema flattened into `FormFieldDto[]` |
-| `wix/forms/submissions.ts` | `uploadFiles`, `toSubmissionValues`, `createSubmission`, `submissionErrors`, `normalizePhone` |
-| `hooks/forms/useWixForm.ts` | the whole form as state — contract below |
+| `wix/forms/types.ts` | the DTOs (`FormDto`, `FormFieldDto`, `FormValues`, `FormErrors`, `SubmissionDto`) — contracts below |
+| `wix/forms/forms.ts` | `getForm`, `listForms` — the transport; the flattening of the raw schema into `FormFieldDto[]` is in `forms-core.ts` beside it (shared with the REST layer) |
+| `wix/forms/submissions.ts` | `uploadFiles`, `createSubmission` — the transport; `toSubmissionValues`, `submissionErrors`, `normalizePhone`, `SUBMITTED_OK` and the upload PUT are in `submissions-core.ts` beside it (shared with the REST layer) |
+| `wix/forms/form-store.ts` | the form state machine, framework-free (`createFormStore({ formId, initialForm? })` — `getState`/`subscribe` + `setValue`/`setValues`/`validate`/`submit`, one instance per form on the page); `validateValue`, `FORM_ERROR`; the hook below binds it to React, every other stack uses it directly |
+| `hooks/forms/useWixForm.ts` | React binding of `form-store.ts` — the whole form as state plus `bind` — contract below |
+| `rest/forms.ts` · `rest/submissions.ts` (skill-side) | the REST twin of the two data files: same exports, same DTOs, over `fetch` with the visitor token — what `--stack static` deploys, and the spec a port reads |
 | `styles/global.css` | the design system: Tailwind v4 + the `@theme` token block (shared across verticals) |
 
 There are **no shipped components and no shipped pages** — every control is yours.
@@ -36,7 +44,25 @@ Read the seed plan first: its forms and their fields are what the page renders.
 
 Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`, one pass).
 
-### The contracts your components consume
+### What a complete form page shows (recommended defaults)
+
+Defaults for a brief that says nothing about them; the prompt wins when it asks otherwise.
+
+- Every field's `label` visible above or beside its control; `required` marked the same way on
+  every field; `description` as help text under the control; `placeholder` only where the owner
+  wrote one.
+- An error under its own control (`errors[target]`, `id="err-<target>"` so `aria-describedby`
+  resolves), the form-level `errors[FORM_ERROR]` above the button; nothing turns red before the
+  visitor touched the field or pressed submit.
+- The submit button reads `submitText` when set, your wording else; disabled while `loading`.
+- `form === null` renders a skeleton of the section, not an empty `<form>`; `errors[FORM_ERROR]`
+  with no form renders the message and nothing else.
+- The thank-you replaces the form in place (same section, same width) — the visitor stays where
+  they were.
+- Copy is the owner's: labels and choices from the schema, no invented privacy promises or
+  response-time claims.
+
+### The contracts your components consume (tested and work as they are; read the source when something is off or the brief wants more)
 
 ```ts
 // FormDto — one form, ready to render
@@ -69,6 +95,13 @@ Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`,
 //     validate,    // validate(target) | validate("addr/city") | validate() for the whole form
 //     errors,      // target (or target/sub) → visitor-facing message; errors[FORM_ERROR] is form-level
 //     loading }    // loading the schema, or submitting
+
+// createFormStore({ formId, initialForm? }) — the same machine without React (lib, static, a port):
+// getState() → { form, values, errors, loading }; subscribe(fn); start() once mounted (loads the
+// schema unless initialForm was given); stop() on unmount; setValue(target, value);
+// setValues(next | fn); validate(target?) → boolean; submit(event?) → Promise<boolean>.
+// submit(event) reads event.currentTarget to focus the first invalid control — hand it the
+// native submit event. FORM_ERROR and validateValue are exported next to it.
 ```
 
 `bind` covers input / textarea / select. A **checkbox or radio group** carries `checked`
@@ -88,26 +121,169 @@ keeping the same `name`, `onBlur: () => validate(target)` and `aria-describedby`
 | `checkbox` | a single `<input type="checkbox">`; its value is a **boolean** |
 | `checkboxGroup` `tags` | one checkbox per choice; the value is an **array** of chosen values |
 | `address` | one control per `addressParts` entry; the value is an **object** keyed by `sub`, and its error keys are `target/sub` |
-| `file` `signature` | `<input type="file">` (uncontrolled) — put the `File` objects in `values[target]`; the hook uploads them on submit |
+| `file` `signature` | `<input type="file">` (uncontrolled) — put the `File` objects in `values[target]`; the store uploads them on submit |
 | `payment` `appointment` `unknown` | out of scope for a plain form — a payment field needs the payment flow, an appointment field needs the `bookings` vertical. Render a disabled note rather than an input that submits the wrong thing |
 
-### Wiring — Astro (default)
+### The page and island you create — skeletons
 
-Fetch in frontmatter so the first paint has the schema, and hand it to the island:
+The class names here are the Astro/React spelling of rules that hold on every stack; on a
+stack where the hook doesn't deploy, keep the rule and write it in your own CSS. Hooks first,
+branches after (an early return above a hook changes hook order between renders and React
+throws). The island renders on the server too (`client:load` SSRs) — render every state
+totally; nothing in a render path may throw.
 
 ```astro
 ---
-import { getForm } from "@/wix/forms/forms";
-const form = await getForm(FORM_ID);        // FORM_ID from the seed plan
+// src/pages/contact.astro — YOU create it. The schema is fetched SERVER-SIDE so the first paint
+// has the fields, and handed to the island as a serialized DTO prop.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import ContactForm from "../components/forms/ContactForm";
+import { getForm } from "../wix/forms/forms";
+import type { FormDto } from "../wix/forms/types";
+
+const FORM_ID = "…"; // from the seed result (seed-result.json → forms[].formId)
+let form: FormDto | null = null;
+try {
+  form = await getForm(FORM_ID);
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream; the island loads the
+  // schema itself and shows the real error if it fails again.
+}
 ---
-<ContactForm client:load initialForm={form} />
+<SiteLayout title="Contact">
+  <!-- your heading / intro, then: -->
+  <ContactForm client:load formId={FORM_ID} initialForm={form ?? undefined} />
+</SiteLayout>
+```
+
+```tsx
+// src/components/forms/ContactForm.tsx — YOU build it; contact.astro mounts it.
+import { useState } from "react";
+import { useWixForm, FORM_ERROR } from "../../hooks/forms/useWixForm";
+import type { FormDto } from "../../wix/forms/types";
+
+export default function ContactForm({ formId, initialForm }: { formId: string; initialForm?: FormDto }) {
+  const f = useWixForm(formId, { initialForm });   // no second fetch when initialForm is passed
+  const [sent, setSent] = useState(false);
+  // …you implement the render:
+  //   • sent → your thank-you, in place of the form (the resolved submit() IS the confirmation)
+  //   • f.errors[FORM_ERROR] && !f.form → the message alone (a form that can't load is a setup problem)
+  //   • !f.form → a skeleton of the section
+  //   • else <form noValidate onSubmit={async (e) => { if (await f.submit(e)) setSent(true); }}>
+  //       mapping f.form.fields to controls per the table above — text-ish: <input type=… {...f.bind(field.target)} />;
+  //       groups/checkbox/file by hand with the same name / onBlur / aria contract; the error for a
+  //       control in <p id={`err-${field.target}`}>{f.errors[field.target]}</p>; address subfield
+  //       errors under f.errors[`${field.target}/${sub}`]; f.errors[FORM_ERROR] above the button;
+  //       the button labelled f.form.submitText || your wording, disabled while f.loading.
+  //     noValidate: the store validates in your wording and focuses the first invalid control —
+  //     the browser's bubbles would race it.
+}
 ```
 
-The island calls `useWixForm(form.id, { initialForm })` — no second fetch, no loading flash.
+### The reference files for stacks where the components don't deploy
+
+On `lib`, `static`, and a port, nothing under `hooks/` arrives — and this vertical ships nothing
+under `components/` on any stack. The state machine behind the hook does arrive —
+`wix/forms/form-store.ts` — so you never rewrite it: `createFormStore` per form, `subscribe`,
+render from `getState()`, call its actions. Its `FormState` interface is the render contract;
+read that. What you write is the rendering, and one shipped file is worth reading first:
+
+1. `hooks/forms/useWixForm.ts` — `bind`: the exact props a text-ish control gets (`name`,
+   `value`, change → `setValue`, blur → `validate(target)`, `aria-describedby="err-<target>"`,
+   `aria-invalid`), and how a change of `formId` gets a fresh store. Your framework's controls
+   follow the same contract.
+
+The control table above is the spec for everything else. Under `references/forms/app/`.
+
+### Wiring — Astro (default)
+
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass).
+2. Create the form page and its island per the skeletons above — frontmatter machinery exact,
+   presentation yours. Fetch in frontmatter so the first paint has the schema; the island calls
+   `useWixForm(formId, { initialForm })` — no second fetch, no loading flash.
+3. Write `pages/index.astro` (home) on `SiteLayout`.
+
+### Wiring — another JS framework (`--stack lib`: Vue, Svelte, Solid, plain Vite)
+
+Read the reference file listed above before writing the surface.
+
+`deploy.mjs forms --stack lib` put the data layer in `src/wix/` and nothing else: `sdk.ts` (the
+visitor client, configured with the public client id), `media.ts`, `money.ts`, and `wix/forms/` —
+`forms.ts`, `submissions.ts`, `types.ts`, the two `*-core.ts` rule files, and `form-store.ts`.
+None of it is React. The hook doesn't ship on this stack; the store replaces it, and you write
+the controls in your framework to the contracts on this page:
+
+- bind the store with your framework's external-store primitive (Vue: `shallowRef` updated in
+  `subscribe`; Svelte: `readable(store.getState(), (set) => store.subscribe(() => set(store.getState())))`;
+  Solid: a signal set in `subscribe`). `createFormStore({ formId })` per form (`start()` when
+  mounted, `stop()` when unmounted). State in, actions out — exactly the hook's contract above;
+- a control's change handler calls `setValue(target, value)` (a checkbox group: the array of
+  checked values; a file input: `[...input.files]`), blur calls `validate(target)`, the
+  `<form>`'s submit handler calls `submit(event)` and shows the thank-you on `true`.
+
+Route `/contact` (or wherever the form lives); dev server on 4321; a static build goes through
+`npx @wix/cli@latest release` with `site.outputDirectory` pointing at the build folder, an SSR
+build is hosted by you.
+
+### Wiring — static site (`--stack static`, no bundler)
+
+Read the reference file listed above before writing the surface.
+
+`deploy.mjs forms --stack static --out site` put the REST layer in `site/js/wix/` (browser ESM,
+the `.ts` beside each `.js` for reading). Everything the visitor loads lives under `site/` —
+pages, styles, `js/` — and `wix.config.json`'s `site.outputDirectory` is `"./site"`; the project
+root (config, plan, seed output) is never the upload. Same function names and DTOs as the table
+above, so the contracts on this page hold unchanged: `getForm`, `listForms` from
+`./js/wix/forms.js`; `uploadFiles`, `createSubmission`, `toSubmissionValues`, `submissionErrors`
+from `./js/wix/submissions.js`. The state machine ships too: `createFormStore` from
+`./js/wix/form-store.js` (`start()` once the page is up; `setValue`, `validate`, `submit`;
+`FORM_ERROR` beside it). No hook, no components — you write the rendering in plain JS: build the
+controls ONCE when `getState().form` arrives (one element per `form.fields` entry, `name` =
+`target`, `input` → `setValue`, `blur` → `validate(target)`), and on later notifications update
+only the error text, `aria-invalid`, and the button's disabled state — rebuilding the inputs on
+every keystroke drops focus. `<form novalidate>` with `onsubmit = (e) => store.submit(e).then(ok
+=> ok && showThankYou())`; `submit` reads the native event's `currentTarget` to focus the first
+invalid control. Wix static hosting serves files, not directories: the page is `contact.html`,
+linked as such. The visitor token persists in `localStorage` on its own; never mint per page.
+The page's title and meta description are yours (a form is not an entity page; there is no
+`seoData`). `npx @wix/cli@latest release` uploads `site/`.
+
+### Wiring — server-rendered, another language (Flask, Laravel, Rails, …)
+
+Read the reference file listed above before writing the surface.
+
+Run `deploy.mjs forms --stack static` in the project folder anyway: `js/wix/` is both the
+browser-side code and the readable spec. Then split by where the call runs. **The schema on the
+server:** port `js/wix/forms.ts` and `forms-core.ts` to your language — `getForm` is one GET with
+the visitor token, `toForm` is the flattening — and render the fields in your template (labels,
+required marks, choices, the same `name` = `target`), so the form is in the HTML; one anonymous
+visitor token per process for this public read (mint and refresh per `client.ts`). **Values,
+validation and the submit in the browser:** load `./js/wix/form-store.js` in the template and
+drive the rendered controls through `createFormStore({ formId })` exactly as the static wiring
+above — the browser owns the visitor's token, so the server never handles per-visitor tokens or
+submissions. If the submit must run server-side anyway (no JS), port `submissions.ts` +
+`submissions-core.ts` and `client.ts`'s header applies: one token set per visitor in the visitor's
+session, never one process-wide token. Add your public https origin to the OAuth app's allowed
+domains.
+
+**Pre-rendered (Frozen-Flask, Pelican, any static-site generator) → Wix-hosted.** Same port for
+the schema read, run at build time with one anonymous token; the generator emits the form page
+with the fields in the HTML. Run `deploy.mjs forms --stack static --out <build dir>` so `js/wix/`
+is inside the output the page imports from, point `site.outputDirectory` at that folder, `wix
+release`. Pages sit at different depths: give the templates one base path to `js/wix/` (a
+template variable, or root-relative `/js/wix/…`), never a relative `./js/wix/` — it breaks one
+level down. The rendered fields are the first paint; values, validation and the submit still run
+client-side through `createFormStore()` from `./js/wix/form-store.js`, exactly as on a static
+site. Close with the rebuild + release command and one line for the owner: a field renamed or
+added in the dashboard reaches the rendered HTML when that command runs; the submit is live
+regardless.
 
 ### Wiring — React SPA (Vite etc.)
 
-`useWixForm(FORM_ID)` with no `initialForm`; render a skeleton while `form` is null.
+Import `./styles/global.css` once at the app entry (needs `@tailwindcss/vite` in the vite config
+plugins — deploy already added the dep). `useWixForm(FORM_ID)` with no `initialForm`; render a
+skeleton while `form` is null. Deploy wrote the public client id into `wix/config.ts`; nothing
+else to configure.
 
 ## Hard rules
 
@@ -117,6 +293,10 @@ The island calls `useWixForm(form.id, { initialForm })` — no second fetch, no
 - **Never build a form without reading the schema.** A hand-built `<form>` posting to Wix Data
   or an email service silently drops real enquiries and loses the dashboard form builder,
   spam protection, notifications and CRM contact mapping.
+- **Values, validation and the submit go through `useWixForm` / the store** — never call the
+  submission API by hand, never re-derive a request shape, never validate by a field's name.
+  Extend by adding a function in `wix/forms/` for what they don't cover (API contracts: the
+  `wix-docs` skill).
 - **The visitor token is enough.** Both the schema read and the submission return 200 on an
   anonymous visitor, even though the spec lists them under owner scopes. Never add a backend,
   a connector token, or `auth.elevate` to make a form work.
@@ -127,24 +307,32 @@ The island calls `useWixForm(form.id, { initialForm })` — no second fetch, no
   owner gets duplicates for an entry they already have.
 - **Never mock, fail loudly.** A form that cannot load is a setup problem — surface it; never
   fall back to a hand-built form.
+- Don't wrap shipped calls in your own API routes — they run client-side by design.
+- Where the shipped code deploys (Astro, React): theme via the `@theme` tokens, and your markup
+  uses Tailwind utilities on the same tokens — one design system. Where it doesn't (`lib`,
+  `static`, a port): style with whatever your stack does well, on one token set of your own.
+- **Call every hook before any conditional return.** An island that returns early for the
+  skeleton or the thank-you above `useWixForm`/`useState` changes hook order between renders and
+  React throws. Hooks first, branches after.
 
 ## Point the user to their dashboard
 
-The owner edits fields, sees submissions, and sets notifications at
-`https://manage.wix.com/dashboard/<siteId>/form/forms`. Say so when you hand the site over —
-the whole value of this vertical is that their edits land on the site with no code change.
+Hand the owner these links — `{siteId}` is `siteId` in `wix.config.json` (the deploy JSON prints it as
+`dashboardUrl`); `{formId}` is the id the seed result returned.
+
+| page | `https://manage.wix.com/dashboard/{siteId}/` + |
+|---|---|
+| Forms list | `wix-forms` |
+| Edit the form (fields, rules, submit settings, notifications) | `wix-forms/form/{formId}` |
+| Its submissions | `wix-forms/form/{formId}/submissions` |
+
+Say so when you hand the site over — the whole value of this vertical is that their edits land on the
+site with no code change. Submissions are per form; there is no site-wide submissions page.
 
 ## Seeding
 
 `seed/SEED.md` is the contract: a plain-data plan in, created forms out. Read it when drafting
 the plan; the seed writes the form ids your pages import.
 
-**⚠️ Build the UI only after the seed has run** — the form id comes from it, and the field set
+**Build the UI only after the seed has run** — the form id comes from it, and the field set
 you are rendering is the one it created.
-
-## Verify (before declaring done)
-
-- The rendered controls match the seeded fields — same labels, same order, same required marks.
-- A submit with an empty required field shows YOUR inline message, and focus moves to it.
-- A valid submit resolves and shows the thank-you; the entry appears in the owner's dashboard.
-- Renaming a field in the dashboard changes the page on reload, with no code change.

package/skills/wix-headless-fast/references/forms/app/hooks/forms/useWixForm.ts

@@ -1,145 +1,20 @@
-// One form as state — schema in, validated submission out, minus the markup. This vertical
-// ships no components: a form is schema-driven (the owner picks the fields), so every form has
-// a different field set and no "contact form" component could ship for it. You render
-// `form.fields`; see references/forms/INSTRUCTIONS.md.
+// React binding of the form store (wix/forms/form-store.ts) — schema in, validated submission
+// out, minus the markup; the state machine lives there, framework-free. This hook subscribes to
+// one store per mounted form and exposes its state and actions under one name, plus `bind` (the
+// props a text-ish control spreads). Astro islands and React SPAs use this; a static page, Vue,
+// or Svelte uses the store directly.
+//
+// This vertical ships no components: a form is schema-driven (the owner picks the fields), so
+// every form has a different field set and no "contact form" component could ship for it. You
+// render `form.fields`; see references/forms/INSTRUCTIONS.md.
 //
 // SSR-friendly: pass a server-fetched FormDto as `initialForm` (Astro frontmatter) and no
 // client fetch happens; a SPA passes nothing and the hook loads it.
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { getForm } from "../../wix/forms/forms";
-import {
-  createSubmission,
-  normalizePhone,
-  submissionErrors,
-  toSubmissionValues,
-  uploadFiles,
-} from "../../wix/forms/submissions";
-import type { FormDto, FormErrors, FormFieldDto, FormValues } from "../../wix/forms/types";
-
-/**
- * The key in `errors` for a message that belongs to the FORM rather than one field — a schema
- * that failed to load, or a rejection with no per-field violations. `@` cannot appear in a
- * form `target`, so this never collides with a field's own error.
- */
-export const FORM_ERROR = "@form";
-
-/** The empty form: every field at a value of the shape its control binds to. */
-function defaultValues(fields: FormFieldDto[]): FormValues {
-  const values: FormValues = {};
-  for (const f of fields) values[f.target] = Array.isArray(f.defaultValue) ? [...f.defaultValue] : f.defaultValue;
-  return values;
-}
-
-/**
- * Check one field's value against its own schema. Exported because it is a plain function —
- * usable outside React, and the place to look when a message needs rewording.
- *
- * Every rule comes from the schema, never from a field's NAME. (The classic mistake is keying
- * the email check on `target === "email"`; deriving it from `format` means an owner-added
- * PHONE/URL/length rule is honored with no code change.)
- *
- * ⚠️ A client check LAXER than the server's is worse than none — the visitor then learns about
- * the problem only after a round trip, in the server's wording rather than yours.
- */
-export function validateValue(field: FormFieldDto, value: unknown): string {
-  const v = String(value ?? "").trim();
-  const rules = field.validation;
-
-  if (field.required && !v) return `${field.label} is required.`;
-  if (!v) return ""; // optional and empty → fine
-
-  if (field.control === "number" || field.control === "rating") {
-    // The control hands back a string, so parse before comparing: "9" > 10 is false but
-    // "9" > "10" is true.
-    const n = Number(v);
-    if (!Number.isFinite(n)) return `${field.label} must be a number.`;
-    if (rules.minimum != null && n < rules.minimum) return `${field.label} must be ${rules.minimum} or more.`;
-    if (rules.maximum != null && n > rules.maximum) return `${field.label} must be ${rules.maximum} or less.`;
-    return "";
-  }
-
-  if (rules.minLength && v.length < rules.minLength)
-    return `${field.label} must be at least ${rules.minLength} characters.`;
-  if (rules.maxLength && v.length > rules.maxLength)
-    return `${field.label} must be at most ${rules.maxLength} characters.`;
-  if (rules.format === "EMAIL" && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v))
-    return "Please enter a valid email address.";
-  if (rules.format === "URL" && !/^https?:\/\/.+/.test(v)) return "Please enter a valid URL.";
-  // PHONE is E.164 server-side: leading +, country code, digits. Strip formatting first —
-  // visitors add spaces, dashes and parens, and rejecting those is a UX bug, not validation.
-  if (rules.format === "PHONE" && !/^\+[1-9]\d{6,14}$/.test(normalizePhone(v)))
-    return "Use international format, starting with + and the country code.";
-  if (rules.pattern && !new RegExp(rules.pattern).test(v))
-    return `${field.label} is not in the expected format.`;
-  return "";
-}
-
-/**
- * One field's error entries, keyed the way the controls are named. A plain field yields at most
- * one (`target`); an ADDRESS yields one per failing subfield (`target/sub`).
- *
- * An address subfield gets the `required` check only — `country` and `subdivision` are
- * country-dependent enums the schema does not enumerate, so their content is the server's call.
- */
-function errorsForField(field: FormFieldDto, values: FormValues): FormErrors {
-  const errors: FormErrors = {};
-
-  if (field.control === "address") {
-    const parts = (values[field.target] ?? {}) as Record<string, unknown>;
-    for (const { sub, label, required } of field.addressParts) {
-      if (required && !String(parts[sub] ?? "").trim()) errors[`${field.target}/${sub}`] = `${label} is required.`;
-    }
-    return errors;
-  }
-
-  if (field.control === "file" || field.control === "signature") {
-    // Files are File objects, which no string rule can judge — check the count instead.
-    const picked = ([] as unknown[]).concat(values[field.target] ?? []).filter(Boolean);
-    const limit = field.validation.fileLimit;
-    if (field.required && !picked.length) errors[field.target] = `${field.label} is required.`;
-    else if (limit && picked.length > limit)
-      errors[field.target] = `Attach at most ${limit} file${limit === 1 ? "" : "s"}.`;
-    return errors;
-  }
-
-  if (field.inputType === "ARRAY") {
-    const picked = (Array.isArray(values[field.target]) ? (values[field.target] as unknown[]) : []).filter(Boolean);
-    const { minItems, maxItems } = field.validation;
-    if (field.required && !picked.length) errors[field.target] = `${field.label} is required.`;
-    else if (minItems && picked.length < minItems) errors[field.target] = `Choose at least ${minItems}.`;
-    else if (maxItems && picked.length > maxItems) errors[field.target] = `Choose at most ${maxItems}.`;
-    return errors;
-  }
-
-  if (field.control === "checkbox") {
-    if (field.required && values[field.target] !== true) errors[field.target] = `${field.label} is required.`;
-    return errors;
-  }
-
-  const message = validateValue(field, values[field.target]);
-  if (message) errors[field.target] = message;
-  return errors;
-}
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { createFormStore, type FormStore, type FormSubmitEvent } from "../../wix/forms/form-store";
+import type { FormDto, FormErrors, FormValues } from "../../wix/forms/types";
 
-function errorsForForm(fields: FormFieldDto[], values: FormValues): FormErrors {
-  const errors: FormErrors = {};
-  for (const field of fields) Object.assign(errors, errorsForField(field, values));
-  return errors;
-}
-
-/**
- * Move focus to a control by input name. ⚠️ `namedItem` returns a RadioNodeList for a radio or
- * checkbox group and an element for everything else — a guard checking only for an element
- * silently skips every choice group.
- */
-function focusControl(formEl: HTMLFormElement | null, name: string): void {
-  const control = formEl?.elements?.namedItem?.(name) as unknown;
-  const node =
-    typeof RadioNodeList !== "undefined" && control instanceof RadioNodeList
-      ? (control[0] as HTMLElement | undefined)
-      : (control as HTMLElement | undefined);
-  node?.focus?.();
-}
+export { FORM_ERROR, validateValue } from "../../wix/forms/form-store";
 
 export interface UseWixFormOptions {
   /** Server-fetched form (Astro frontmatter) — skips the client fetch entirely. */
@@ -162,7 +37,7 @@ export interface UseWixForm {
     "aria-invalid": true | undefined;
   };
   /** `onSubmit`. Resolves TRUE when the submission was created — that IS the success signal. */
-  submit: (event?: { preventDefault?: () => void; currentTarget?: unknown }) => Promise<boolean>;
+  submit: (event?: FormSubmitEvent) => Promise<boolean>;
   /** One field, one address subfield, or the whole form when called with nothing. */
   validate: (target?: string) => boolean;
   errors: FormErrors;
@@ -172,84 +47,15 @@ export interface UseWixForm {
 
 export function useWixForm(formId: string, options: UseWixFormOptions = {}): UseWixForm {
   const { initialForm } = options;
-  const [form, setForm] = useState<FormDto | null>(initialForm ?? null);
-  const [values, setValues] = useState<FormValues>({});
-  const [errors, setErrors] = useState<FormErrors>({});
-  const [loading, setLoading] = useState(!initialForm);
-  // The empty form to reset to after a successful submit — the schema's own defaults.
-  const emptyRef = useRef<FormValues>({});
-
-  const fields = useMemo(() => form?.fields ?? [], [form]);
-
-  useEffect(() => {
-    if (initialForm) return; // the SSR pass already answered this
-    let alive = true;
-    if (!formId) {
-      setLoading(false);
-      setErrors({ [FORM_ERROR]: "No formId — pass one from the seed's forms map." });
-      return;
-    }
-    setLoading(true);
-    getForm(formId)
-      .then((loaded) => {
-        if (!alive) return;
-        setForm(loaded);
-        setErrors({});
-        setLoading(false);
-      })
-      .catch((e: unknown) => {
-        if (!alive) return;
-        // Fail loudly. A form that cannot load is a setup problem — never fall back to a
-        // hand-built form, which would drop real enquiries silently.
-        setErrors({ [FORM_ERROR]: e instanceof Error ? e.message : "Could not load the form." });
-        setLoading(false);
-      });
-    return () => {
-      alive = false;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [formId]);
-
-  // Seed the controls once the schema is in: every control is controlled from the first render,
-  // so each target must hold a value of the right shape before any of them mount.
+  const ref = useRef<{ formId: string; store: FormStore } | null>(null);
+  if (!ref.current || ref.current.formId !== formId) ref.current = { formId, store: createFormStore({ formId, initialForm }) };
+  const store = ref.current.store;
   useEffect(() => {
-    const empty = defaultValues(fields);
-    emptyRef.current = empty;
-    setValues(empty);
-  }, [fields]);
-
-  const validate = useCallback(
-    (target?: string) => {
-      if (!target) {
-        const all = errorsForForm(fields, values);
-        setErrors(all);
-        return Object.keys(all).length === 0;
-      }
-      const key = String(target);
-      const field = fields.find((f) => f.target === key.split("/")[0]);
-      if (!field) return true;
-
-      // The keys this call owns, so a re-check CLEARS what it fixed as well as flagging what it
-      // did not: one key for a plain field, or every subfield when an address itself is named.
-      const owned = key.includes("/")
-        ? [key]
-        : field.control === "address"
-          ? field.addressParts.map(({ sub }) => `${field.target}/${sub}`)
-          : [field.target];
-
-      const found = errorsForField(field, values);
-      setErrors((prev) => {
-        const next = { ...prev };
-        for (const k of owned) {
-          delete next[k];
-          if (found[k]) next[k] = found[k];
-        }
-        return next;
-      });
-      return owned.every((k) => !found[k]);
-    },
-    [fields, values],
-  );
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  const { values, errors } = state;
 
   // Covers input / textarea / select. A checkbox or radio group carries `checked` instead of
   // `value`, and a file input cannot be controlled at all — wire those by hand, keeping the
@@ -258,60 +64,22 @@ export function useWixForm(formId: string, options: UseWixFormOptions = {}): Use
     (target: string) => ({
       name: target,
       value: String(values[target] ?? ""),
-      onChange: (e: { target: { value: string } }) =>
-        setValues((prev) => ({ ...prev, [target]: e.target.value })),
-      onBlur: () => validate(target),
+      onChange: (e: { target: { value: string } }) => store.setValue(target, e.target.value),
+      onBlur: () => store.validate(target),
       "aria-describedby": `err-${target}`,
       "aria-invalid": errors[target] ? (true as const) : undefined,
     }),
-    [values, errors, validate],
-  );
-
-  const submit = useCallback(
-    async (event?: { preventDefault?: () => void; currentTarget?: unknown }) => {
-      event?.preventDefault?.();
-      // Capture the <form> NOW: React clears currentTarget once the handler returns, so reading
-      // it after the await below (to focus a server-rejected control) comes back null.
-      const formEl = (event?.currentTarget ?? null) as HTMLFormElement | null;
-      if (!form) return false;
-
-      // Client pass first, so the visitor gets inline feedback in OUR wording before a round trip.
-      const clientErrors = errorsForForm(fields, values);
-      if (Object.keys(clientErrors).length) {
-        setErrors(clientErrors);
-        // FOCUS the first invalid control — scrollIntoView moves the viewport and nothing else,
-        // leaving a keyboard or screen-reader user where they were.
-        focusControl(formEl, Object.keys(clientErrors)[0]);
-        return false;
-      }
-
-      setLoading(true);
-      try {
-        // Attachments go up FIRST — a File is not something the submission API takes, and its
-        // value is the upload URL this hands back. No file fields → nothing happens here.
-        const uploaded = await uploadFiles(form.id, fields, values);
-        setValues(uploaded); // keep the URLs, so a rejection on another field never re-uploads
-        await createSubmission(form.id, toSubmissionValues(fields, uploaded));
-        setErrors({});
-        setValues(emptyRef.current); // back to the schema's defaults, ready for another
-        return true;
-      } catch (e) {
-        const mapped = submissionErrors(e, fields);
-        if (Object.keys(mapped).length) {
-          setErrors(mapped);
-          focusControl(formEl, Object.keys(mapped)[0]);
-        } else {
-          setErrors({
-            [FORM_ERROR]: e instanceof Error ? e.message : "Could not send the form. Please try again.",
-          });
-        }
-        return false;
-      } finally {
-        setLoading(false);
-      }
-    },
-    [fields, form, values],
+    [values, errors, store],
   );
 
-  return { form, values, setValues, bind, submit, validate, errors, loading };
+  return {
+    form: state.form,
+    values,
+    setValues: store.setValues,
+    bind,
+    submit: store.submit,
+    validate: store.validate,
+    errors,
+    loading: state.loading,
+  };
 }