@usefillo/core 0.3.2 → 0.5.0

package/README.md

@@ -15,7 +15,7 @@ npm i @usefillo/core
 ```ts
 import { createClient, defineForm, validateResponse, visibleBlocks } from "@usefillo/core";
 
-const client = createClient({ key: "pk_live_…" });
+const client = createClient({ key: "pk_live_…" }); // for syncing code-defined forms
 
 const form = defineForm({
   id: "cust-feedback",
@@ -26,6 +26,10 @@ const form = defineForm({
 });
 ```
 
+Published renderer embeds can fetch by `formId` without a key. Use a client object for custom API origins, uploads, or submissions from your own renderer; add a publishable key only when syncing `defineForm()` schemas from code.
+
+Schema settings include `submitMode: "auto"` for one-tap forms that should submit after a complete discrete answer instead of rendering the first submit button, and `submissionLimit: "once_per_visitor"` for browser-scoped duplicate prevention. Themes include `colorScheme: "light" | "dark" | "auto"` for renderer defaults.
+
 Key exports: `createClient` / `FilloClient`, `defineForm`, `validateResponse`, `validateField`, `visibleBlocks`, and the schema types (`FormSchema`, `Field`, `FieldKind`, `FormTheme`, `ResponseData`, …).
 
 ## Links

package/dist/index.d.ts

@@ -14,6 +14,8 @@ type BlockKind = FieldKind | ContentKind;
 interface SelectOption {
     id: string;
     label: string;
+    /** Optional visual hint for compact binary choices. */
+    icon?: "thumbs_up" | "thumbs_down";
 }
 interface BaseBlock {
     /** Stable id — for fields this is the key responses are stored under. */
@@ -30,9 +32,18 @@ interface BaseField extends BaseBlock {
     placeholder?: string;
 }
 interface TextField extends BaseField {
-    kind: "short_text" | "long_text" | "email" | "url" | "phone";
+    kind: "short_text" | "long_text" | "email" | "url";
     maxLength?: number;
 }
+interface PhoneField extends BaseField {
+    kind: "phone";
+    /**
+     * Country selected when the form opens (ISO-3166 alpha-2, e.g. "US"). When
+     * unset the renderer falls back to the respondent's browser locale, then the
+     * first country in the list. The respondent can always change it.
+     */
+    defaultCountry?: string;
+}
 interface NumberField extends BaseField {
     kind: "number";
     min?: number;
@@ -48,6 +59,8 @@ interface ChoiceField extends BaseField {
 }
 interface CheckboxField extends BaseField {
     kind: "checkbox";
+    /** Default checkbox or a switch-style toggle. */
+    appearance?: "checkbox" | "toggle";
 }
 interface RatingField extends BaseField {
     kind: "rating";
@@ -113,7 +126,7 @@ interface CustomField extends BaseField {
     /** Arbitrary options handed to your component. */
     config?: Record<string, unknown>;
 }
-type Field = TextField | NumberField | ChoiceField | CheckboxField | RatingField | LinearScaleField | RankingField | MatrixField | SignatureField | DateField | FileUploadField | HiddenField | CustomField;
+type Field = TextField | PhoneField | NumberField | ChoiceField | CheckboxField | RatingField | LinearScaleField | RankingField | MatrixField | SignatureField | DateField | FileUploadField | HiddenField | CustomField;
 interface HeadingBlock extends BaseBlock {
     kind: "heading";
     text: string;
@@ -135,11 +148,24 @@ interface FormPage {
     blocks: Block[];
 }
 interface FormSettings {
+    /**
+     * Default "button": respondents submit with the footer button. "auto" hides
+     * the final-page submit button in default renderers and submits after a
+     * single discrete answer, e.g. a thumbs up/down article rating.
+     */
+    submitMode?: "button" | "auto";
     submitLabel?: string;
     successTitle?: string;
     successMessage?: string;
     redirectUrl?: string;
     showProgress?: boolean;
+    /**
+     * Default "multiple": a browser can submit as often as it wants. Use
+     * "once_per_visitor" for tiny docs/article feedback where the SDK should
+     * remember this browser has already answered and send a server-side
+     * de-duplication key with the response.
+     */
+    submissionLimit?: "multiple" | "once_per_visitor";
     /** Notify this address on every submission. */
     notifyEmail?: string;
     /** Send respondents a receipt (to the first answered email field). */
@@ -153,6 +179,8 @@ interface FormSchema {
     settings: FormSettings;
 }
 interface FormTheme {
+    /** Force default renderer colors, or leave unset/"auto" to follow the system. */
+    colorScheme?: "light" | "dark" | "auto";
     /** Accent for buttons, focus rings, selection. */
     primary?: string;
     background?: string;
@@ -270,6 +298,8 @@ interface ValidationResult {
  */
 declare function validateResponse(form: FormSchema, data: ResponseData): ValidationResult;
 
+declare const FILLO_SCHEMA_VERSION: 1;
+declare const FILLO_SDK_VERSION = "0.5.0";
 interface SchemaValidationResult {
     ok: boolean;
     /** Present when ok — a normalized, structurally-valid schema. */
@@ -277,8 +307,11 @@ interface SchemaValidationResult {
     /** Present when !ok — a short human-readable reason. */
     error?: string;
 }
+/** Normalize untrusted input into a renderer-safe FormSchema. */
+declare function normalizeFormSchema(input: unknown): SchemaValidationResult;
 /** Validate an untrusted object as a FormSchema. Also enforces unique field ids. */
 declare function validateFormSchema(input: unknown): SchemaValidationResult;
+declare function normalizeFormTheme(input: unknown): FormTheme | null;
 
 /**
  * Canonical plain-text rendering of an answer — the single source of truth for
@@ -291,6 +324,62 @@ declare function validateFormSchema(input: unknown): SchemaValidationResult;
  */
 declare function formatAnswer(field: Field, value: FieldValue): string;
 
+/**
+ * Lightweight, dependency-free phone metadata + helpers powering the SDK's
+ * phone field. Deliberately small: it carries enough to render a country
+ * picker, format as-you-type, and do a *possible-length* check. Authoritative
+ * validation + canonical normalization happen server-side with full
+ * libphonenumber data (bundle size is irrelevant there), so this stays lean and
+ * the stored value is always E.164.
+ */
+interface PhoneCountry {
+    /** ISO 3166-1 alpha-2, uppercase ("US"). Also drives the flag emoji. */
+    iso2: string;
+    /** Display name ("United States"). */
+    name: string;
+    /** Country calling code without the "+" ("1", "44", "33"). */
+    dialCode: string;
+    /** Valid national-number lengths in digits. Empty = accept a generic range. */
+    lengths: number[];
+    /** Digit group sizes for display formatting, e.g. [3,3,4] → "415 555 0123". */
+    groups: number[];
+    /** Example national number (digits only) for the input placeholder. */
+    example: string;
+}
+/** Curated country metadata, ordered for the picker (broad coverage). */
+declare const PHONE_COUNTRIES: PhoneCountry[];
+/** Flag emoji from an ISO-3166 alpha-2 code (regional-indicator letters). */
+declare function flagEmoji(iso2: string): string;
+declare function countryByIso(iso2: string | undefined): PhoneCountry | undefined;
+/** Country whose dial code is the longest prefix of these digits (no "+"). */
+declare function countryByDialCode(digits: string): PhoneCountry | undefined;
+/** Keep only 0-9 (and a leading "+") from arbitrary input. */
+declare function digitsOnly(input: string): string;
+/** Group national digits per the country's format (cosmetic; generic = 3s). */
+declare function formatNational(country: PhoneCountry | undefined, national: string): string;
+/** Assemble the canonical E.164 value from a country + national digits. */
+declare function toE164(country: PhoneCountry, national: string): string;
+interface ParsedPhone {
+    /** Best-guess country, if the dial code matched one we know. */
+    country?: PhoneCountry;
+    /** National significant digits (dial code stripped). */
+    national: string;
+    /** Canonical E.164 ("+…"), or "" if there were no digits. */
+    e164: string;
+}
+/**
+ * Parse a stored/typed value into country + national + E.164. Accepts E.164
+ * ("+4915123456789"), a bare international number, or — with `fallback` — a
+ * national number typed without a dial code.
+ */
+declare function parsePhone(value: string, fallback?: PhoneCountry): ParsedPhone;
+/**
+ * Cheap "could this be a real number?" check used for inline feedback. Length
+ * only — never claims more than it knows; the server does authoritative
+ * validation. `country` (when known) tightens the accepted lengths.
+ */
+declare function isPossiblePhone(value: string): boolean;
+
 /** Display metadata for every block kind — drives the builder palette. */
 declare const BLOCK_KIND_META: Record<BlockKind, {
     label: string;
@@ -363,9 +452,15 @@ interface FilloClientOptions {
 interface PublishedForm {
     id: string;
     slug: string;
+    /** Wire contract version for server-provided schema data. */
+    schemaVersion?: number;
+    /** Lowest SDK version the server expects for this form payload. */
+    minSdkVersion?: string;
+    /** Data-only feature flags exposed by the server. */
+    capabilities?: string[];
     schema: FormSchema;
     theme: FormTheme | null;
-    /** True when the form has stopped accepting responses (closed/limit reached). */
+    /** True when the server says the form cannot accept responses. */
     closed?: boolean;
     /** Workspace branding state — absent means show the badge (default). */
     branding?: FormBranding;
@@ -373,6 +468,8 @@ interface PublishedForm {
 interface SubmitResult {
     ok: boolean;
     responseId?: string;
+    /** True when the API accepted the request as an already-recorded visitor response. */
+    duplicate?: boolean;
     /** fieldId -> message when the server rejects the submission. */
     errors?: Record<string, string>;
 }
@@ -384,6 +481,11 @@ interface SubmitMeta {
     elapsedMs?: number;
     /** Embedding surface; "headless" submissions require a paid plan (server-enforced). */
     surface?: "default" | "headless";
+    /**
+     * Browser-scoped de-duplication key sent when a form opts into
+     * settings.submissionLimit = "once_per_visitor".
+     */
+    submissionKey?: string;
 }
 interface UploadProgress {
     uploadedBytes: number;
@@ -481,7 +583,8 @@ interface ProvisionWorkspaceResult {
     organizationId: string;
     /** A claim link was emailed here so the owner can take ownership later. */
     claim: {
-        email: string;
+        url: string | null;
+        email: string | null;
         sent: boolean;
     };
     /** Caps applied until the workspace is claimed. */
@@ -526,9 +629,9 @@ interface FormControllerOptions {
     /** Honeypot value, supplied by your renderer; must be empty for a human. */
     getHoneypot?: () => string;
     /**
-     * Let page navigation (next) move forward without validating the current page.
-     * For previews/builders where you want to flip through pages without filling
-     * the form in. Submission still validates.
+     * @internal Let preview page navigation move forward without validating the
+     * current page. Submission still validates, and renderers must not use this
+     * option to change visitor-facing behavior such as branding.
      */
     skipValidation?: boolean;
     /**
@@ -662,4 +765,4 @@ declare class Sha1 {
 }
 declare const sha1Base64: (bytes: Uint8Array) => string;
 
-export { BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CustomField, DRAFT_KINDS, type DateField, type DividerBlock, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, FilloClient, type FilloClientOptions, FilloError, type FormBranding, type FormController, type FormControllerOptions, type FormControllerState, type FormDraftSpec, type FormPage, type FormSchema, type FormSettings, type FormStatus, type FormTheme, type HeadingBlock, type HiddenField, type JsonValue, type LinearScaleField, type MatrixField, type NumberField, type ParagraphBlock, type ProvisionWorkspaceResult, type PublishedForm, type RankingField, type RatingField, type ResponseData, type SchemaValidationResult, type SelectOption, Sha1, type SignatureField, type SubmitMeta, type SubmitResult, type SyncedForm, type TextField, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, allFields, assembleForm, contentHash, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, formatAnswer, isBlockVisible, isCodeForm, isField, pipeBlock, prefillFromParams, provisionWorkspace, resolveText, sha1Base64, syncCodeForm, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields };
+export { BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CustomField, DRAFT_KINDS, type DateField, type DividerBlock, FILLO_SCHEMA_VERSION, FILLO_SDK_VERSION, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, FilloClient, type FilloClientOptions, FilloError, type FormBranding, type FormController, type FormControllerOptions, type FormControllerState, type FormDraftSpec, type FormPage, type FormSchema, type FormSettings, type FormStatus, type FormTheme, type HeadingBlock, type HiddenField, type JsonValue, type LinearScaleField, type MatrixField, type NumberField, PHONE_COUNTRIES, type ParagraphBlock, type ParsedPhone, type PhoneCountry, type PhoneField, type ProvisionWorkspaceResult, type PublishedForm, type RankingField, type RatingField, type ResponseData, type SchemaValidationResult, type SelectOption, Sha1, type SignatureField, type SubmitMeta, type SubmitResult, type SyncedForm, type TextField, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, allFields, assembleForm, contentHash, countryByDialCode, countryByIso, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, flagEmoji, formatAnswer, formatNational, isBlockVisible, isCodeForm, isField, isPossiblePhone, normalizeFormSchema, normalizeFormTheme, parsePhone, pipeBlock, prefillFromParams, provisionWorkspace, resolveText, sha1Base64, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields };

package/dist/index.js

@@ -53,6 +53,152 @@ function visibleFields(form, data) {
 
 // src/validation.ts
 import { z } from "zod";
+
+// src/phone.ts
+var C = (iso2, name, dialCode, lengths = [], groups = [], example = "") => ({ iso2, name, dialCode, lengths, groups, example });
+var PHONE_COUNTRIES = [
+  C("US", "United States", "1", [10], [3, 3, 4], "2015550123"),
+  C("CA", "Canada", "1", [10], [3, 3, 4], "5145550123"),
+  C("GB", "United Kingdom", "44", [10], [4, 6], "7400123456"),
+  C("AU", "Australia", "61", [9], [3, 3, 3], "412345678"),
+  C("DE", "Germany", "49", [10, 11], [4, 7], "15123456789"),
+  C("FR", "France", "33", [9], [1, 2, 2, 2, 2], "612345678"),
+  C("IN", "India", "91", [10], [5, 5], "8123456789"),
+  C("DK", "Denmark", "45", [8], [2, 2, 2, 2], "32123456"),
+  C("SE", "Sweden", "46", [9], [2, 3, 4], "701234567"),
+  C("NO", "Norway", "47", [8], [3, 2, 3], "40612345"),
+  C("FI", "Finland", "358", [9, 10], [2, 3, 4], "412345678"),
+  C("NL", "Netherlands", "31", [9], [1, 4, 4], "612345678"),
+  C("BE", "Belgium", "32", [9], [3, 2, 2, 2], "470123456"),
+  C("ES", "Spain", "34", [9], [3, 3, 3], "612345678"),
+  C("IT", "Italy", "39", [9, 10], [3, 3, 4], "3123456789"),
+  C("PT", "Portugal", "351", [9], [3, 3, 3], "912345678"),
+  C("IE", "Ireland", "353", [9], [2, 3, 4], "851234567"),
+  C("CH", "Switzerland", "41", [9], [2, 3, 2, 2], "781234567"),
+  C("AT", "Austria", "43", [10, 11], [3, 7], "6641234567"),
+  C("PL", "Poland", "48", [9], [3, 3, 3], "512345678"),
+  C("CZ", "Czechia", "420", [9], [3, 3, 3], "601123456"),
+  C("GR", "Greece", "30", [10], [3, 3, 4], "6912345678"),
+  C("RO", "Romania", "40", [9], [3, 3, 3], "712345678"),
+  C("HU", "Hungary", "36", [9], [2, 3, 4], "201234567"),
+  C("UA", "Ukraine", "380", [9], [2, 3, 2, 2], "501234567"),
+  C("RU", "Russia", "7", [10], [3, 3, 2, 2], "9123456789"),
+  C("TR", "Turkey", "90", [10], [3, 3, 2, 2], "5012345678"),
+  C("IL", "Israel", "972", [9], [2, 3, 4], "501234567"),
+  C("AE", "United Arab Emirates", "971", [9], [2, 3, 4], "501234567"),
+  C("SA", "Saudi Arabia", "966", [9], [2, 3, 4], "512345678"),
+  C("ZA", "South Africa", "27", [9], [2, 3, 4], "711234567"),
+  C("NG", "Nigeria", "234", [10], [3, 3, 4], "8021234567"),
+  C("KE", "Kenya", "254", [9], [3, 3, 3], "712123456"),
+  C("EG", "Egypt", "20", [10], [3, 3, 4], "1001234567"),
+  C("BR", "Brazil", "55", [10, 11], [2, 5, 4], "11961234567"),
+  C("MX", "Mexico", "52", [10], [3, 3, 4], "2221234567"),
+  C("AR", "Argentina", "54", [10], [4, 6], "1123456789"),
+  C("CL", "Chile", "56", [9], [1, 4, 4], "221234567"),
+  C("CO", "Colombia", "57", [10], [3, 3, 4], "3211234567"),
+  C("PE", "Peru", "51", [9], [3, 3, 3], "912345678"),
+  C("CN", "China", "86", [11], [3, 4, 4], "13123456789"),
+  C("JP", "Japan", "81", [10], [2, 4, 4], "9012345678"),
+  C("KR", "South Korea", "82", [9, 10], [2, 4, 4], "1023456789"),
+  C("SG", "Singapore", "65", [8], [4, 4], "81234567"),
+  C("HK", "Hong Kong", "852", [8], [4, 4], "51234567"),
+  C("TW", "Taiwan", "886", [9], [3, 3, 3], "912345678"),
+  C("MY", "Malaysia", "60", [9, 10], [2, 3, 4], "123456789"),
+  C("ID", "Indonesia", "62", [10, 11], [3, 4, 4], "81234567890"),
+  C("TH", "Thailand", "66", [9], [2, 3, 4], "812345678"),
+  C("PH", "Philippines", "63", [10], [3, 3, 4], "9171234567"),
+  C("VN", "Vietnam", "84", [9], [3, 3, 3], "912345678"),
+  C("PK", "Pakistan", "92", [10], [3, 3, 4], "3012345678"),
+  C("BD", "Bangladesh", "880", [10], [2, 4, 4], "1812345678"),
+  C("NZ", "New Zealand", "64", [9, 10], [2, 3, 4], "211234567"),
+  C("SK", "Slovakia", "421", [9], [3, 3, 3], "912123456"),
+  C("BG", "Bulgaria", "359", [9], [2, 3, 4], "481234567"),
+  C("HR", "Croatia", "385", [8, 9], [2, 3, 4], "921234567"),
+  C("RS", "Serbia", "381", [8, 9], [2, 3, 4], "601234567"),
+  C("SI", "Slovenia", "386", [8], [2, 3, 3], "31234567"),
+  C("LT", "Lithuania", "370", [8], [3, 2, 3], "61234567"),
+  C("LV", "Latvia", "371", [8], [2, 3, 3], "21234567"),
+  C("EE", "Estonia", "372", [7, 8], [3, 4], "51234567"),
+  C("IS", "Iceland", "354", [7], [3, 4], "6111234"),
+  C("LU", "Luxembourg", "352", [9], [3, 3, 3], "628123456"),
+  C("MA", "Morocco", "212", [9], [3, 3, 3], "650123456"),
+  C("CR", "Costa Rica", "506", [8], [4, 4], "83123456"),
+  C("EC", "Ecuador", "593", [9], [2, 3, 4], "991234567"),
+  C("UY", "Uruguay", "598", [8], [1, 3, 4], "94231234"),
+  C("QA", "Qatar", "974", [8], [4, 4], "33123456"),
+  C("KW", "Kuwait", "965", [8], [4, 4], "50012345")
+];
+var byIso = new Map(PHONE_COUNTRIES.map((c) => [c.iso2, c]));
+function flagEmoji(iso2) {
+  const cc = iso2.toUpperCase();
+  if (!/^[A-Z]{2}$/.test(cc)) return "\u{1F3F3}\uFE0F";
+  return String.fromCodePoint(...[...cc].map((ch) => 127462 + ch.charCodeAt(0) - 65));
+}
+function countryByIso(iso2) {
+  return iso2 ? byIso.get(iso2.toUpperCase()) : void 0;
+}
+function countryByDialCode(digits) {
+  let best;
+  for (const c of PHONE_COUNTRIES) {
+    if (digits.startsWith(c.dialCode) && (!best || c.dialCode.length > best.dialCode.length)) {
+      best = c;
+    }
+  }
+  return best;
+}
+function digitsOnly(input) {
+  return input.replace(/[^\d]/g, "");
+}
+function formatNational(country, national) {
+  const digits = digitsOnly(national);
+  if (!digits) return "";
+  const groups = country?.groups?.length ? country.groups : [];
+  const out = [];
+  let i = 0;
+  for (const size of groups) {
+    if (i >= digits.length) break;
+    out.push(digits.slice(i, i + size));
+    i += size;
+  }
+  while (i < digits.length) {
+    out.push(digits.slice(i, i + 3));
+    i += 3;
+  }
+  return out.join(" ");
+}
+function toE164(country, national) {
+  const digits = digitsOnly(national);
+  return digits ? `+${country.dialCode}${digits}` : "";
+}
+function parsePhone(value, fallback) {
+  const trimmed = (value ?? "").trim();
+  const hasPlus = trimmed.startsWith("+");
+  const digits = digitsOnly(trimmed);
+  if (!digits) return { country: fallback, national: "", e164: "" };
+  if (hasPlus) {
+    const country = countryByDialCode(digits);
+    if (country) {
+      const national = digits.slice(country.dialCode.length);
+      return { country, national, e164: `+${digits}` };
+    }
+    return { national: digits, e164: `+${digits}` };
+  }
+  if (fallback) {
+    const national = digits.startsWith(fallback.dialCode) ? digits.slice(fallback.dialCode.length) : digits;
+    return { country: fallback, national, e164: `+${fallback.dialCode}${national}` };
+  }
+  return { national: digits, e164: `+${digits}` };
+}
+function isPossiblePhone(value) {
+  const { country, national, e164 } = parsePhone(value);
+  if (!e164) return false;
+  const total = digitsOnly(e164).length;
+  if (total < 8 || total > 15) return false;
+  if (country?.lengths.length) return country.lengths.includes(national.length);
+  return national.length >= 4;
+}
+
+// src/validation.ts
 var fileValueSchema = z.object({
   fileId: z.string().min(1),
   name: z.string(),
@@ -83,7 +229,7 @@ function validateField(field, value) {
       return null;
     }
     case "email": {
-      const r = z.string().email().safeParse(value);
+      const r = z.email().safeParse(value);
       return r.success ? null : "Enter a valid email address";
     }
     case "url": {
@@ -99,7 +245,7 @@ function validateField(field, value) {
       return null;
     }
     case "phone": {
-      if (typeof value !== "string" || !/^[+\d][\d\s\-().]{4,}$/.test(value))
+      if (typeof value !== "string" || !isPossiblePhone(value))
         return "Enter a valid phone number";
       return null;
     }
@@ -250,7 +396,7 @@ var FIELD_KINDS = [
 var CONTENT_KINDS2 = ["heading", "paragraph", "divider"];
 var ALL_KINDS = [...FIELD_KINDS, ...CONTENT_KINDS2];
 var idSchema = z2.string().min(1).max(128);
-var optionSchema = z2.object({ id: idSchema, label: z2.string().max(1e3) }).passthrough();
+var optionSchema = z2.object({ id: idSchema, label: z2.string().max(1e3), icon: z2.unknown().optional() }).passthrough();
 var blockSchema = z2.object({
   id: idSchema,
   kind: z2.enum(ALL_KINDS),
@@ -269,25 +415,279 @@ var schemaShape = z2.object({
   title: z2.string().max(2e3).optional().default(""),
   description: z2.string().max(5e3).optional(),
   pages: z2.array(pageSchema).min(1).max(50),
-  settings: z2.record(z2.unknown()).optional().default({})
+  settings: z2.record(z2.string(), z2.unknown()).optional().default({})
 });
-function validateFormSchema(input) {
+var MAX_SCHEMA_VERSION = 1;
+var FILLO_SCHEMA_VERSION = 1;
+var FILLO_SDK_VERSION = "0.5.0";
+function str(value, max, fallback = "") {
+  return typeof value === "string" ? value.trim().slice(0, max) : fallback;
+}
+function optionalStr(value, max) {
+  const s = str(value, max);
+  return s === "" ? void 0 : s;
+}
+function bool(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function finite(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function int(value, min, max, fallback) {
+  const n = finite(value);
+  if (n === void 0) return fallback;
+  return Math.max(min, Math.min(max, Math.round(n)));
+}
+function options(value, max = 200) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, max).flatMap((item) => {
+    if (!item || typeof item !== "object") return [];
+    const rec = item;
+    const id = str(rec.id, 128);
+    const label = str(rec.label, 1e3);
+    const icon = rec.icon === "thumbs_up" || rec.icon === "thumbs_down" ? rec.icon : void 0;
+    return id && label ? [cleanObject({ id, label, icon })] : [];
+  });
+}
+function conditions(value) {
+  if (!Array.isArray(value)) return void 0;
+  const normalized = value.slice(0, 20).flatMap((item) => {
+    if (!item || typeof item !== "object") return [];
+    const rec = item;
+    const op = rec.op;
+    if (op !== "eq" && op !== "neq" && op !== "contains" && op !== "gt" && op !== "lt" && op !== "answered" && op !== "not_answered") {
+      return [];
+    }
+    const fieldId = str(rec.fieldId, 128);
+    if (!fieldId) return [];
+    const raw = rec.value;
+    const value2 = typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean" ? raw : void 0;
+    return [{ fieldId, op, ...value2 !== void 0 ? { value: value2 } : {} }];
+  });
+  return normalized.length ? normalized : void 0;
+}
+function baseBlock(rec) {
+  return {
+    id: str(rec.id, 128),
+    visibleIf: conditions(rec.visibleIf)
+  };
+}
+function baseField(rec, kind) {
+  const base = baseBlock(rec);
+  return {
+    ...base,
+    kind,
+    label: str(rec.label, 2e3, "Untitled field"),
+    description: optionalStr(rec.description, 5e3),
+    required: bool(rec.required),
+    placeholder: optionalStr(rec.placeholder, 500)
+  };
+}
+function normalizeUrl(value) {
+  const raw = optionalStr(value, 2e3);
+  if (!raw) return void 0;
+  try {
+    const url = new URL(raw);
+    return url.protocol === "http:" || url.protocol === "https:" ? raw : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function normalizeSettings(value) {
+  const rec = value && typeof value === "object" ? value : {};
+  const submitMode = rec.submitMode === "button" || rec.submitMode === "auto" ? rec.submitMode : void 0;
+  const submissionLimit = rec.submissionLimit === "once_per_visitor" || rec.submissionLimit === "multiple" ? rec.submissionLimit : void 0;
+  return {
+    submitMode,
+    submitLabel: optionalStr(rec.submitLabel, 100),
+    successTitle: optionalStr(rec.successTitle, 200),
+    successMessage: optionalStr(rec.successMessage, 5e3),
+    redirectUrl: normalizeUrl(rec.redirectUrl),
+    showProgress: bool(rec.showProgress),
+    submissionLimit,
+    notifyEmail: z2.email().max(254).safeParse(rec.notifyEmail).success ? rec.notifyEmail : void 0,
+    sendReceipt: bool(rec.sendReceipt)
+  };
+}
+function cleanObject(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, value]) => value !== void 0));
+}
+function normalizeBlock(input) {
+  if (!input || typeof input !== "object") return null;
+  const rec = input;
+  const kind = rec.kind;
+  const base = baseBlock(rec);
+  if (!base.id || typeof kind !== "string") return null;
+  switch (kind) {
+    case "heading":
+      return cleanObject({ ...base, kind, text: str(rec.text, 2e3, "Section") });
+    case "paragraph":
+      return cleanObject({ ...base, kind, text: str(rec.text, 5e3) });
+    case "divider":
+      return cleanObject({ ...base, kind });
+    case "short_text":
+    case "email":
+    case "url":
+      return cleanObject({
+        ...baseField(rec, kind),
+        maxLength: finite(rec.maxLength) === void 0 ? void 0 : int(rec.maxLength, 1, 2e3, 2e3)
+      });
+    case "phone": {
+      const cc = optionalStr(rec.defaultCountry, 2)?.toUpperCase();
+      return cleanObject({
+        ...baseField(rec, kind),
+        defaultCountry: cc && /^[A-Z]{2}$/.test(cc) ? cc : void 0
+      });
+    }
+    case "long_text":
+      return cleanObject({
+        ...baseField(rec, kind),
+        maxLength: finite(rec.maxLength) === void 0 ? void 0 : int(rec.maxLength, 1, 2e4, 2e4)
+      });
+    case "number":
+      return cleanObject({ ...baseField(rec, kind), min: finite(rec.min), max: finite(rec.max) });
+    case "select":
+    case "multi_select":
+    case "dropdown": {
+      const opts = options(rec.options);
+      if (opts.length === 0) return null;
+      return cleanObject({
+        ...baseField(rec, kind),
+        options: opts,
+        allowOther: bool(rec.allowOther),
+        shuffleOptions: bool(rec.shuffleOptions)
+      });
+    }
+    case "checkbox": {
+      const appearance = rec.appearance === "toggle" ? "toggle" : void 0;
+      return cleanObject({
+        ...baseField(rec, kind),
+        appearance
+      });
+    }
+    case "signature":
+    case "date":
+      return cleanObject(baseField(rec, kind));
+    case "rating":
+      return cleanObject({ ...baseField(rec, kind), max: int(rec.max, 1, 10, 5) });
+    case "linear_scale": {
+      const min = int(rec.min, 0, 9, 1);
+      const max = int(rec.max, min + 1, 10, 10);
+      return cleanObject({
+        ...baseField(rec, kind),
+        min,
+        max,
+        minLabel: optionalStr(rec.minLabel, 100),
+        maxLabel: optionalStr(rec.maxLabel, 100)
+      });
+    }
+    case "ranking": {
+      const opts = options(rec.options);
+      if (opts.length < 2) return null;
+      return cleanObject({ ...baseField(rec, kind), options: opts });
+    }
+    case "matrix": {
+      const rows = options(rec.rows);
+      const columns = options(rec.columns);
+      if (rows.length === 0 || columns.length === 0) return null;
+      return cleanObject({ ...baseField(rec, kind), rows, columns });
+    }
+    case "hidden":
+      return cleanObject({
+        ...baseField(rec, kind),
+        // Hidden fields render nothing, so a required one with no matching URL
+        // param / default would be permanently unsubmittable — never required.
+        required: false,
+        paramName: optionalStr(rec.paramName, 128),
+        defaultValue: optionalStr(rec.defaultValue, 1e3)
+      });
+    case "file_upload":
+      return cleanObject({
+        ...baseField(rec, kind),
+        maxFiles: int(rec.maxFiles, 1, 20, 1),
+        maxFileSizeMb: int(rec.maxFileSizeMb, 1, 5e3, 500),
+        accept: Array.isArray(rec.accept) ? rec.accept.flatMap((v) => {
+          const item = optionalStr(v, 100);
+          return item ? [item] : [];
+        }).slice(0, 50) : void 0
+      });
+    case "custom":
+      return cleanObject({
+        ...baseField(rec, kind),
+        component: str(rec.component, 128),
+        config: rec.config && typeof rec.config === "object" && !Array.isArray(rec.config) ? rec.config : void 0
+      });
+    default:
+      return null;
+  }
+}
+function normalizeFormSchema(input) {
   const parsed = schemaShape.safeParse(input);
   if (!parsed.success) {
     const first = parsed.error.issues[0];
     const path = first?.path.join(".");
     return { ok: false, error: first ? `${path ? `${path}: ` : ""}${first.message}` : "Invalid schema" };
   }
+  if (parsed.data.version > MAX_SCHEMA_VERSION) {
+    return { ok: false, error: `Unsupported schema version: ${parsed.data.version}` };
+  }
+  const pages = parsed.data.pages.map((page) => {
+    const blocks = page.blocks.flatMap((raw) => {
+      const block = normalizeBlock(raw);
+      return block ? [block] : [];
+    });
+    return cleanObject({
+      id: page.id,
+      title: optionalStr(page.title, 500),
+      blocks
+    });
+  });
   const seen = /* @__PURE__ */ new Set();
-  for (const page of parsed.data.pages) {
+  for (const page of pages) {
     for (const block of page.blocks) {
-      if (seen.has(block.id)) {
-        return { ok: false, error: `Duplicate block id: ${block.id}` };
-      }
+      if (seen.has(block.id)) return { ok: false, error: `Duplicate block id: ${block.id}` };
       seen.add(block.id);
     }
   }
-  return { ok: true, schema: parsed.data };
+  if (pages.every((page) => page.blocks.length === 0)) {
+    return { ok: false, error: "Schema must contain at least one valid block" };
+  }
+  const schema = {
+    version: FILLO_SCHEMA_VERSION,
+    title: str(parsed.data.title, 2e3),
+    pages,
+    settings: normalizeSettings(parsed.data.settings)
+  };
+  const description = optionalStr(parsed.data.description, 5e3);
+  if (description) schema.description = description;
+  return { ok: true, schema };
+}
+function validateFormSchema(input) {
+  try {
+    return normalizeFormSchema(input);
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : "Invalid schema" };
+  }
+}
+function safeCssToken(value, max) {
+  const token = optionalStr(value, max);
+  if (!token) return void 0;
+  if (/[;{}<>]/.test(token) || /url\s*\(/i.test(token)) return void 0;
+  return token;
+}
+function normalizeFormTheme(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return null;
+  const rec = input;
+  const colorScheme = rec.colorScheme === "light" || rec.colorScheme === "dark" || rec.colorScheme === "auto" ? rec.colorScheme : void 0;
+  const theme = cleanObject({
+    colorScheme,
+    primary: safeCssToken(rec.primary, 200),
+    background: safeCssToken(rec.background, 200),
+    text: safeCssToken(rec.text, 200),
+    radius: safeCssToken(rec.radius, 64),
+    fontFamily: safeCssToken(rec.fontFamily, 200)
+  });
+  return Object.keys(theme).length > 0 ? theme : null;
 }
 
 // src/format.ts
@@ -318,11 +718,17 @@ function formatAnswer(field, value) {
     case "linear_scale":
     case "number":
       return typeof value === "number" ? String(value) : String(value);
+    case "phone": {
+      const { country, national, e164 } = parsePhone(String(value));
+      if (!e164) return String(value);
+      const grouped = formatNational(country, national);
+      const dial = country ? `+${country.dialCode}` : e164.replace(national, "");
+      return grouped ? `${dial} ${grouped}` : e164;
+    }
     case "short_text":
     case "long_text":
     case "email":
     case "url":
-    case "phone":
     case "date":
     case "hidden":
       return String(value);
@@ -337,14 +743,14 @@ function formatAnswer(field, value) {
 var ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
 var MASK = 256 - 256 % ALPHABET.length;
 function createId(size = 12) {
+  const csprng = globalThis.crypto;
+  if (typeof csprng === "undefined" || typeof csprng.getRandomValues !== "function") {
+    throw new Error("createId requires Web Crypto (globalThis.crypto.getRandomValues)");
+  }
   let id = "";
   while (id.length < size) {
     const bytes = new Uint8Array(size);
-    if (typeof globalThis.crypto !== "undefined") {
-      globalThis.crypto.getRandomValues(bytes);
-    } else {
-      for (let i = 0; i < size; i++) bytes[i] = Math.floor(Math.random() * 256);
-    }
+    csprng.getRandomValues(bytes);
     for (let i = 0; i < size && id.length < size; i++) {
       const b = bytes[i];
       if (b < MASK) id += ALPHABET[b % ALPHABET.length];
@@ -447,6 +853,8 @@ function createBlock(kind) {
       return { id, kind, label: "Upload a file", maxFiles: 1, maxFileSizeMb: 500 };
     case "checkbox":
       return { id, kind, label: "I agree" };
+    case "phone":
+      return { id, kind, label: "Phone number" };
     default:
       return { id, kind, label: BLOCK_KIND_META[kind].label };
   }
@@ -457,10 +865,12 @@ function createEmptyForm(title = "Untitled form") {
     title,
     pages: [{ id: createId(8), blocks: [] }],
     settings: {
+      submitMode: "button",
       submitLabel: "Submit",
       successTitle: "Thanks!",
       successMessage: "Your response has been recorded.",
-      showProgress: true
+      showProgress: true,
+      submissionLimit: "multiple"
     }
   };
 }
@@ -487,7 +897,7 @@ var DRAFT_KINDS = [
   "paragraph",
   "divider"
 ];
-function str(value, max) {
+function str2(value, max) {
   return typeof value === "string" ? value.trim().slice(0, max) : "";
 }
 function clampInt(value, lo, hi, fallback) {
@@ -496,7 +906,7 @@ function clampInt(value, lo, hi, fallback) {
   return n < lo ? lo : n > hi ? hi : n;
 }
 function toOptions(labels, fallback) {
-  const cleaned = (Array.isArray(labels) ? labels : []).map((l) => str(l, 200)).filter(Boolean);
+  const cleaned = (Array.isArray(labels) ? labels : []).map((l) => str2(l, 200)).filter(Boolean);
   if (cleaned.length < 2) return fallback;
   return cleaned.slice(0, 100).map((label) => ({ id: createId(6), label }));
 }
@@ -504,15 +914,15 @@ function assembleBlock(spec) {
   const kind = spec.kind;
   if (!DRAFT_KINDS.includes(kind)) return null;
   const block = createBlock(kind);
-  const label = str(spec.label, 500);
+  const label = str2(spec.label, 500);
   if (kind === "heading" || kind === "paragraph") {
-    block.text = str(spec.text, 2e3) || label || block.text;
+    block.text = str2(spec.text, 2e3) || label || block.text;
     return block;
   }
   if (kind === "divider") return block;
   if (label) block.label = label;
   if (spec.required) block.required = true;
-  if (spec.placeholder) block.placeholder = str(spec.placeholder, 200);
+  if (spec.placeholder) block.placeholder = str2(spec.placeholder, 200);
   switch (kind) {
     case "select":
     case "multi_select":
@@ -526,8 +936,8 @@ function assembleBlock(spec) {
     case "linear_scale":
       block.min = spec.min === 0 ? 0 : 1;
       block.max = clampInt(spec.max, 2, 10, 10);
-      if (spec.minLabel) block.minLabel = str(spec.minLabel, 100);
-      if (spec.maxLabel) block.maxLabel = str(spec.maxLabel, 100);
+      if (spec.minLabel) block.minLabel = str2(spec.minLabel, 100);
+      if (spec.maxLabel) block.maxLabel = str2(spec.maxLabel, 100);
       break;
     case "number":
       if (typeof spec.min === "number") block.min = spec.min;
@@ -541,12 +951,12 @@ function assembleBlock(spec) {
   return block;
 }
 function assembleForm(spec) {
-  const form = createEmptyForm(str(spec.title, 200) || "Untitled form");
-  const description = str(spec.description, 1e3);
+  const form = createEmptyForm(str2(spec.title, 200) || "Untitled form");
+  const description = str2(spec.description, 1e3);
   if (description) form.description = description;
   const pages = (Array.isArray(spec.pages) ? spec.pages : []).slice(0, 20).map((page) => ({
     id: createId(8),
-    title: str(page.title, 200) || void 0,
+    title: str2(page.title, 200) || void 0,
     blocks: (Array.isArray(page.fields) ? page.fields : []).slice(0, 100).map(assembleBlock).filter((b) => b !== null)
   })).filter((page) => page.blocks.length > 0);
   if (pages.length > 0) form.pages = pages;
@@ -673,8 +1083,31 @@ var FilloError = class extends Error {
   status;
 };
 var MAX_CHUNK_RETRIES = 3;
-function makeReporter(totalBytes, options) {
-  return (uploadedBytes) => options.onProgress?.({
+function compareVersions(a, b) {
+  const left = a.split(".").map((part) => Number(part) || 0);
+  const right = b.split(".").map((part) => Number(part) || 0);
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+function assertPublishedFormCompatible(form) {
+  if (form.schemaVersion !== void 0 && form.schemaVersion !== FILLO_SCHEMA_VERSION) {
+    throw new FilloError(
+      `This form uses schema version ${form.schemaVersion}; this SDK supports version ${FILLO_SCHEMA_VERSION}. Update @usefillo/* to render it.`,
+      426
+    );
+  }
+  if (form.minSdkVersion && compareVersions(FILLO_SDK_VERSION, form.minSdkVersion) < 0) {
+    throw new FilloError(
+      `This form requires @usefillo/* ${form.minSdkVersion} or newer. Current SDK is ${FILLO_SDK_VERSION}.`,
+      426
+    );
+  }
+}
+function makeReporter(totalBytes, options2) {
+  return (uploadedBytes) => options2.onProgress?.({
     uploadedBytes,
     totalBytes,
     fraction: totalBytes === 0 ? 1 : uploadedBytes / totalBytes
@@ -695,10 +1128,10 @@ var FilloClient = class {
   fetch;
   /** Publishable workspace key, when configured. */
   key;
-  constructor(options = {}) {
-    this.baseUrl = options.sameOrigin ? "" : DEFAULT_BASE_URL;
-    this.key = options.key;
-    this.fetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
+  constructor(options2 = {}) {
+    this.baseUrl = options2.sameOrigin ? "" : DEFAULT_BASE_URL;
+    this.key = options2.key;
+    this.fetch = options2.fetch ?? ((...args) => globalThis.fetch(...args));
   }
   url(path) {
     return `${this.baseUrl}/api/v1${path}`;
@@ -715,8 +1148,10 @@ var FilloClient = class {
     return await res.json();
   }
   /** Fetch a published form definition by id or slug. */
-  getForm(idOrSlug) {
-    return this.json(`/forms/${encodeURIComponent(idOrSlug)}`);
+  async getForm(idOrSlug) {
+    const form = await this.json(`/forms/${encodeURIComponent(idOrSlug)}`);
+    assertPublishedFormCompatible(form);
+    return form;
   }
   /**
    * Upsert a code-defined form into the workspace identified by the client's
@@ -728,9 +1163,18 @@ var FilloClient = class {
         new FilloError("createClient needs a `key` (pk_\u2026) to sync code-defined forms", 401)
       );
     }
+    const normalized = normalizeFormSchema(schema);
+    if (!normalized.ok) {
+      return Promise.reject(new FilloError(`Invalid form schema: ${normalized.error}`, 400));
+    }
     return this.json("/forms/sync", {
       method: "POST",
-      body: JSON.stringify({ key: this.key, id: handle, schema, theme })
+      body: JSON.stringify({
+        key: this.key,
+        id: handle,
+        schema: normalized.schema,
+        theme: normalizeFormTheme(theme)
+      })
     });
   }
   /** Submit a response. Returns per-field errors instead of throwing on validation failure. */
@@ -748,7 +1192,7 @@ var FilloClient = class {
       throw new FilloError(`Submit failed: ${res.status}`, res.status);
     }
     const body = await res.json();
-    return { ok: true, responseId: body.id };
+    return { ok: true, responseId: body.id, duplicate: body.duplicate };
   }
   /**
    * Open a respondent session for funnel analysis. Fire-and-forget: returns the
@@ -800,19 +1244,19 @@ var FilloClient = class {
    * sessions — in which case the bytes go straight from this browser to the
    * form owner's Drive and never touch the Fillo server.
    */
-  async uploadFile(formId, file, options) {
+  async uploadFile(formId, file, options2) {
     const name = file instanceof File ? file.name : "upload.bin";
     const mime = file.type || "application/octet-stream";
     let session;
-    if (options.sessionId) {
-      session = await this.getUploadSession(options.sessionId, options.uploadToken);
+    if (options2.sessionId) {
+      session = await this.getUploadSession(options2.sessionId, options2.uploadToken);
     } else {
       session = await this.json(
         `/forms/${encodeURIComponent(formId)}/uploads`,
         {
           method: "POST",
           body: JSON.stringify({
-            fieldId: options.fieldId,
+            fieldId: options2.fieldId,
             fileName: name,
             size: file.size,
             mime
@@ -822,11 +1266,11 @@ var FilloClient = class {
     }
     let completeBody;
     if (session.transport?.type === "gdrive") {
-      await this.driveUploadLoop(session, session.transport.uploadUrl, file, options);
+      await this.driveUploadLoop(session, session.transport.uploadUrl, file, options2);
     } else if (session.transport?.type === "s3-put") {
-      await this.s3PutUpload(session.transport.uploadUrl, file, options);
+      await this.s3PutUpload(session.transport.uploadUrl, file, options2);
     } else if (session.transport?.type === "box") {
-      completeBody = await this.boxUpload(session.transport, file, options);
+      completeBody = await this.boxUpload(session.transport, file, options2);
     } else {
       throw new FilloError("This form's storage doesn't support uploads \u2014 connect Drive, S3, or Box.");
     }
@@ -848,8 +1292,8 @@ var FilloClient = class {
    * SHA-1 `Digest`, then commit with the whole-file digest. Bytes go straight to
    * Box; we return the new file id for /complete to verify server-side.
    */
-  async boxUpload(transport, file, options) {
-    const report = makeReporter(file.size, options);
+  async boxUpload(transport, file, options2) {
+    const report = makeReporter(file.size, options2);
     report(0);
     const auth = { Authorization: `Bearer ${transport.token}` };
     if (transport.mode === "simple") {
@@ -860,8 +1304,8 @@ var FilloClient = class {
       );
       form.append("file", file, transport.fileName);
       const res = await this.retry(
-        options,
-        () => this.fetch(transport.uploadUrl, { method: "POST", headers: auth, body: form, signal: options.signal })
+        options2,
+        () => this.fetch(transport.uploadUrl, { method: "POST", headers: auth, body: form, signal: options2.signal })
       );
       if (!res.ok) throw new FilloError(`Box upload failed: ${res.status}`, res.status);
       const body = await res.json();
@@ -875,7 +1319,7 @@ var FilloClient = class {
       );
     }
     const sessionRes = await this.retry(
-      options,
+      options2,
       () => this.fetch(transport.sessionUrl, {
         method: "POST",
         headers: { ...auth, "Content-Type": "application/json" },
@@ -884,7 +1328,7 @@ var FilloClient = class {
           file_size: transport.size,
           file_name: transport.fileName
         }),
-        signal: options.signal
+        signal: options2.signal
       })
     );
     if (!sessionRes.ok) throw new FilloError(`Box session failed: ${sessionRes.status}`, sessionRes.status);
@@ -893,13 +1337,13 @@ var FilloClient = class {
     const parts = [];
     let offset = 0;
     while (offset < file.size) {
-      options.signal?.throwIfAborted();
+      options2.signal?.throwIfAborted();
       const end = Math.min(offset + session.part_size, file.size);
       const bytes = new Uint8Array(await file.slice(offset, end).arrayBuffer());
       whole.update(bytes);
       const partDigest = await digestPartBase64(bytes);
       const res = await this.retry(
-        options,
+        options2,
         () => this.fetch(session.session_endpoints.upload_part, {
           method: "PUT",
           headers: {
@@ -909,7 +1353,7 @@ var FilloClient = class {
             "Content-Range": `bytes ${offset}-${end - 1}/${file.size}`
           },
           body: bytes,
-          signal: options.signal
+          signal: options2.signal
         })
       );
       if (!res.ok) throw new FilloError(`Box part failed: ${res.status}`, res.status);
@@ -918,12 +1362,12 @@ var FilloClient = class {
       report(offset);
     }
     const commitRes = await this.retry(
-      options,
+      options2,
       () => this.fetch(session.session_endpoints.commit, {
         method: "POST",
         headers: { ...auth, "Content-Type": "application/json", Digest: `sha=${bytesToBase64(whole.digest())}` },
         body: JSON.stringify({ parts }),
-        signal: options.signal
+        signal: options2.signal
       })
     );
     if (!commitRes.ok) throw new FilloError(`Box commit failed: ${commitRes.status}`, commitRes.status);
@@ -931,13 +1375,13 @@ var FilloClient = class {
     return { providerFileId: committed.entries?.[0]?.id };
   }
   /** Retry a request with exponential backoff; never retries an aborted upload. */
-  async retry(options, fn) {
+  async retry(options2, fn) {
     let attempt = 0;
     for (; ; ) {
       try {
         return await fn();
       } catch (err) {
-        if (options.signal?.aborted) throw err;
+        if (options2.signal?.aborted) throw err;
         attempt += 1;
         if (attempt >= MAX_CHUNK_RETRIES) throw err;
         await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
@@ -950,12 +1394,12 @@ var FilloClient = class {
    * repeated failure we re-sync through our session endpoint (the server
    * queries Drive for the authoritative offset).
    */
-  async driveUploadLoop(session, uploadUrl, file, options) {
+  async driveUploadLoop(session, uploadUrl, file, options2) {
     let offset = session.uploadedBytes;
-    const report = makeReporter(file.size, options);
+    const report = makeReporter(file.size, options2);
     report(offset);
     while (offset < file.size) {
-      options.signal?.throwIfAborted();
+      options2.signal?.throwIfAborted();
       const end = Math.min(offset + session.chunkSize, file.size);
       const chunk = file.slice(offset, end);
       let attempt = 0;
@@ -967,7 +1411,7 @@ var FilloClient = class {
               "Content-Range": `bytes ${offset}-${end - 1}/${file.size}`
             },
             body: chunk,
-            signal: options.signal
+            signal: options2.signal
           });
           if (res.status === 308) {
             const range = res.headers.get("Range") ?? res.headers.get("range");
@@ -983,7 +1427,7 @@ var FilloClient = class {
           }
           throw new FilloError(`Drive chunk failed: ${res.status}`, res.status);
         } catch (err) {
-          if (options.signal?.aborted) throw err;
+          if (options2.signal?.aborted) throw err;
           attempt += 1;
           if (attempt >= MAX_CHUNK_RETRIES) throw err;
           await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
@@ -998,8 +1442,8 @@ var FilloClient = class {
    * S3-compatible single PUT to a presigned URL — bytes go straight to the
    * bucket. Not resumable (S3 single PUT is atomic), but retried on failure.
    */
-  async s3PutUpload(uploadUrl, file, options) {
-    const report = makeReporter(file.size, options);
+  async s3PutUpload(uploadUrl, file, options2) {
+    const report = makeReporter(file.size, options2);
     report(0);
     let attempt = 0;
     for (; ; ) {
@@ -1008,13 +1452,13 @@ var FilloClient = class {
           method: "PUT",
           headers: { "Content-Type": file.type || "application/octet-stream" },
           body: file,
-          signal: options.signal
+          signal: options2.signal
         });
         if (!res.ok) throw new FilloError(`S3 upload failed: ${res.status}`, res.status);
         report(file.size);
         return;
       } catch (err) {
-        if (options.signal?.aborted) throw err;
+        if (options2.signal?.aborted) throw err;
         attempt += 1;
         if (attempt >= MAX_CHUNK_RETRIES) throw err;
         await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
@@ -1022,16 +1466,16 @@ var FilloClient = class {
     }
   }
 };
-function createClient(options = {}) {
-  return new FilloClient(options);
+function createClient(options2 = {}) {
+  return new FilloClient(options2);
 }
-async function provisionWorkspace(options) {
-  const base = options.sameOrigin ? "" : DEFAULT_BASE_URL;
-  const doFetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
+async function provisionWorkspace(options2) {
+  const base = options2.sameOrigin ? "" : DEFAULT_BASE_URL;
+  const doFetch = options2.fetch ?? ((...args) => globalThis.fetch(...args));
   const res = await doFetch(`${base}/api/v1/workspaces/provision`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ email: options.email, source: options.source ?? "sdk" })
+    body: JSON.stringify({ email: options2.email, source: options2.source ?? "sdk" })
   });
   if (!res.ok) {
     const body = await res.text().catch(() => "");
@@ -1050,15 +1494,76 @@ function warnNoClient() {
     "[fillo] This form has no `client`, so responses can't be submitted \u2014 it's render-only. Pass a client (createClient) to collect responses in Fillo, or forward them to your own backend with webhooks: https://fillo.so/docs"
   );
 }
-function createFormController(options) {
-  const { onChange, onSubmitted } = options;
-  let form = options.form;
-  let formId = options.formId;
-  let client = options.client;
-  let data = { ...options.initialData ?? {} };
+var memorySubmissionKeys = /* @__PURE__ */ new Map();
+function browserStorage() {
+  try {
+    return globalThis.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+function submissionStorageKey(formId) {
+  return `fillo:submission:${formId}`;
+}
+function randomSubmissionKey() {
+  const crypto = globalThis.crypto;
+  if (crypto?.randomUUID) return crypto.randomUUID();
+  const bytes = new Uint8Array(16);
+  if (crypto?.getRandomValues) {
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function readStoredSubmission(formId) {
+  const store = browserStorage();
+  if (!store) return memorySubmissionKeys.get(formId) ?? null;
+  try {
+    const parsed = JSON.parse(store.getItem(submissionStorageKey(formId)) ?? "null");
+    if (parsed && typeof parsed.key === "string") return parsed;
+  } catch {
+  }
+  return null;
+}
+function writeStoredSubmission(formId, value) {
+  memorySubmissionKeys.set(formId, value);
+  const store = browserStorage();
+  if (!store) return;
+  try {
+    store.setItem(submissionStorageKey(formId), JSON.stringify(value));
+  } catch {
+  }
+}
+function ensureSubmissionKey(formId) {
+  const existing = readStoredSubmission(formId);
+  if (existing?.key) return existing.key;
+  const next = { key: randomSubmissionKey() };
+  writeStoredSubmission(formId, next);
+  return next.key;
+}
+function markSubmitted(formId, responseId) {
+  const existing = readStoredSubmission(formId);
+  writeStoredSubmission(formId, {
+    key: existing?.key ?? randomSubmissionKey(),
+    submittedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    responseId
+  });
+}
+function hasSubmittedOnce(form, formId) {
+  if (form.settings.submissionLimit !== "once_per_visitor" || !formId) return false;
+  return Boolean(readStoredSubmission(formId)?.submittedAt);
+}
+function createFormController(options2) {
+  const { onChange, onSubmitted } = options2;
+  const initial = normalizeFormSchema(options2.form);
+  if (!initial.ok) throw new Error(`Invalid form schema: ${initial.error}`);
+  let form = initial.schema;
+  let formId = options2.formId;
+  let client = options2.client;
+  let data = { ...options2.initialData ?? {} };
   let errors = {};
   let pageIndex = 0;
-  let status = "idle";
+  let status = hasSubmittedOnce(form, formId) ? "submitted" : "idle";
   const uploadingFields = /* @__PURE__ */ new Set();
   const listeners = /* @__PURE__ */ new Set();
   const mountedAt = Date.now();
@@ -1124,7 +1629,7 @@ function createFormController(options) {
   function next() {
     const pageCount = form.pages.length;
     const clamped = Math.min(pageIndex, Math.max(pageCount - 1, 0));
-    if (!options.skipValidation) {
+    if (!options2.skipValidation) {
       const pageErrors = validatePage(clamped);
       errors = pageErrors;
       if (Object.keys(pageErrors).length > 0) {
@@ -1146,20 +1651,24 @@ function createFormController(options) {
     const result = validateResponse(form, data);
     if (!result.ok) {
       errors = result.errors;
-      const firstBad = form.pages.findIndex((p) => p.blocks.some((b) => b.id in result.errors));
+      const firstBad = form.pages.findIndex(
+        (p) => visibleBlocks(p, data).some((b) => b.id in result.errors)
+      );
       if (firstBad >= 0) pageIndex = firstBad;
       notify();
       return;
     }
     if (client && formId) {
+      const submissionKey = form.settings.submissionLimit === "once_per_visitor" ? ensureSubmissionKey(formId) : void 0;
       status = "submitting";
       notify();
       let res;
       try {
         res = await client.submit(formId, result.data, {
-          hp: options.getHoneypot?.() ?? "",
+          hp: options2.getHoneypot?.() ?? "",
           elapsedMs: Date.now() - mountedAt,
-          surface: options.surface ?? "default"
+          surface: options2.surface ?? "default",
+          submissionKey
         });
       } catch (err) {
         status = "idle";
@@ -1173,12 +1682,13 @@ function createFormController(options) {
         return;
       }
       if (sessionId) client.reportProgress(sessionId, { completed: true });
+      if (submissionKey) markSubmitted(formId, res.responseId);
       status = "submitted";
       notify();
       emitSubmitted(res.responseId, result.data);
       return;
     }
-    if (options.skipValidation) {
+    if (options2.skipValidation) {
       status = "submitted";
       notify();
       emitSubmitted(void 0, result.data);
@@ -1205,9 +1715,12 @@ function createFormController(options) {
       if ("formId" in ctx) formId = ctx.formId;
       if ("client" in ctx) client = ctx.client;
       if (ctx.form && ctx.form !== form) {
-        form = ctx.form;
-        notify();
+        const next2 = normalizeFormSchema(ctx.form);
+        if (!next2.ok) throw new Error(`Invalid form schema: ${next2.error}`);
+        form = next2.schema;
       }
+      if (status === "idle" && hasSubmittedOnce(form, formId)) status = "submitted";
+      notify();
     },
     destroy() {
       listeners.clear();
@@ -1337,28 +1850,41 @@ export {
   BLOCK_KIND_META,
   CONTENT_KINDS,
   DRAFT_KINDS,
+  FILLO_SCHEMA_VERSION,
+  FILLO_SDK_VERSION,
   FilloClient,
   FilloError,
+  PHONE_COUNTRIES,
   Sha1,
   allFields,
   assembleForm,
   contentHash,
+  countryByDialCode,
+  countryByIso,
   createBlock,
   createClient,
   createEmptyForm,
   createFormController,
   createId,
   defineForm,
+  digitsOnly,
+  flagEmoji,
   formatAnswer,
+  formatNational,
   isBlockVisible,
   isCodeForm,
   isField,
+  isPossiblePhone,
+  normalizeFormSchema,
+  normalizeFormTheme,
+  parsePhone,
   pipeBlock,
   prefillFromParams,
   provisionWorkspace,
   resolveText,
   sha1Base64,
   syncCodeForm,
+  toE164,
   validateField,
   validateFormSchema,
   validateResponse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefillo/core",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Form schema, validation, logic engine and JS client for Fillo. Framework-agnostic.",
   "license": "MIT",
   "keywords": [
@@ -29,7 +29,7 @@
     "access": "public"
   },
   "dependencies": {
-    "zod": "^3.24.2"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "tsup": "^8.4.0",