@usefillo/react 0.6.2 → 0.8.0

package/dist/index.js

@@ -1,10 +1,12 @@
 "use client";
 
 // src/FilloForm.tsx
-import { useEffect as useEffect7, useId as useId2, useMemo as useMemo5, useRef as useRef5, useState as useState6 } from "react";
+import { useEffect as useEffect7, useId as useId2, useMemo as useMemo5, useRef as useRef6, useState as useState6 } from "react";
 import {
   FilloError as FilloError2,
   createClient,
+  formSchemasEqual,
+  isFilloError as isFilloError2,
   needsExplicitSubmit,
   normalizeFormSchema,
   normalizeFormTheme,
@@ -15,6 +17,7 @@ import { resolveStrings, slotClass as slotClass3 } from "@usefillo/core";
 // src/appearance.tsx
 import { createContext, useContext } from "react";
 import {
+  DEFAULT_FIELD_STRINGS,
   DEFAULT_STRINGS,
   slotClass
 } from "@usefillo/core";
@@ -49,7 +52,10 @@ function useFieldSlots(field, error) {
     control: (base) => slotClass(base, appearance, { slot: "control", ...state })
   };
 }
-var FilloStringsContext = createContext(DEFAULT_STRINGS);
+var FilloStringsContext = createContext({
+  ...DEFAULT_STRINGS,
+  ...DEFAULT_FIELD_STRINGS
+});
 function useStrings() {
   return useContext(FilloStringsContext);
 }
@@ -120,13 +126,19 @@ function useFilloController(options) {
       skipValidation: options.skipValidation,
       surface: options.surface ?? "headless",
       // Wrapped so the engine (created once) always calls the latest resolver.
-      resolveFormId: options.resolveFormId ? () => optsRef.current.resolveFormId() : void 0
+      resolveFormId: options.resolveFormId ? () => optsRef.current.resolveFormId() : void 0,
+      respondent: options.respondent
     });
   }
   const store = storeRef.current;
   useEffect(() => {
-    store.setContext({ form: options.form, formId: options.formId, client: options.client });
-  }, [store, options.form, options.formId, options.client]);
+    store.setContext({
+      form: options.form,
+      formId: options.formId,
+      client: options.client,
+      respondent: options.respondent
+    });
+  }, [store, options.form, options.formId, options.client, options.respondent]);
   useEffect(() => () => store.destroy(), [store]);
   const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
   return useMemo2(
@@ -139,20 +151,40 @@ function useFilloController(options) {
       setUploading: store.setUploading,
       next: store.next,
       back: store.back,
-      submit: store.submit
+      submit: store.submit,
+      flushDraft: store.flushDraft,
+      resetDraft: store.resetDraft
     }),
     [store, state, options.form, options.formId, options.client]
   );
 }
+function useDraftFlush(api) {
+  const enabled = Boolean(api.form.settings.saveProgress);
+  const flush = api.flushDraft;
+  useEffect(() => {
+    if (!enabled || typeof window === "undefined") return;
+    const onPageHide = () => flush();
+    const onVisibility = () => {
+      if (document.visibilityState === "hidden") flush();
+    };
+    window.addEventListener("pagehide", onPageHide);
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => {
+      window.removeEventListener("pagehide", onPageHide);
+      document.removeEventListener("visibilitychange", onVisibility);
+    };
+  }, [enabled, flush]);
+}
 
 // src/define.ts
 import {
   contentHash,
   FilloError,
   isCodeForm,
+  isFilloError,
   syncCodeForm
 } from "@usefillo/core";
-import { useEffect as useEffect2, useState } from "react";
+import { useEffect as useEffect2, useRef as useRef2, useState } from "react";
 import { defineForm, isCodeForm as isCodeForm2, syncCodeForm as syncCodeForm2 } from "@usefillo/core";
 var noticedSync = /* @__PURE__ */ new Set();
 function noticeSync(handle, kind, message) {
@@ -161,39 +193,156 @@ function noticeSync(handle, kind, message) {
   noticedSync.add(key);
   console.info(message);
 }
-function useCodeFormSync(form, client, onError) {
+function useCodeFormSync(form, client, onError, options) {
   const codeForm = isCodeForm(form) ? form : null;
-  const [synced, setSynced] = useState({ formId: null, status: null });
+  const [synced, setSynced] = useState({
+    key: null,
+    client: void 0,
+    settled: false,
+    formId: null,
+    status: null,
+    error: null,
+    noticeError: null,
+    staged: false
+  });
   const hasKey = Boolean(client?.key);
+  const allowUnsynced = Boolean(options?.allowUnsynced);
   const handle = codeForm?.id;
   const contentKey = codeForm ? contentHash(JSON.stringify(codeForm.schema) + JSON.stringify(codeForm.theme ?? null)) : null;
+  const syncKey = codeForm ? client?.key ? `${client.baseUrl}|${client.key}|${codeForm.id}|${contentKey}` : allowUnsynced ? null : `${client?.baseUrl ?? ""}|<missing-key>|${codeForm.id}|${contentKey}` : null;
+  const onErrorRef = useRef2(onError);
+  onErrorRef.current = onError;
   useEffect2(() => {
-    if (!codeForm || !client?.key) return;
+    if (!codeForm || !syncKey) return;
     let cancelled = false;
+    setSynced(
+      (previous) => previous.key === syncKey && previous.client === client ? {
+        ...previous,
+        settled: false,
+        formId: null,
+        status: null,
+        error: null,
+        noticeError: null,
+        staged: false,
+        resolvedSchema: void 0,
+        resolvedTheme: void 0
+      } : {
+        key: syncKey,
+        client,
+        settled: false,
+        formId: null,
+        status: null,
+        error: null,
+        noticeError: null,
+        staged: false
+      }
+    );
+    if (!client?.key) {
+      const error = new FilloError(
+        'Code forms need createClient({ key: "pk_\u2026" }) to resolve the live form. Pass a publishable key or a published formId.',
+        401,
+        void 0,
+        "sync_key_required"
+      );
+      console.warn(`[fillo] form sync failed (${error.code}): ${error.message}`);
+      setSynced({
+        key: syncKey,
+        client,
+        settled: true,
+        formId: null,
+        status: null,
+        error,
+        noticeError: null,
+        staged: false
+      });
+      onErrorRef.current?.(error);
+      return;
+    }
     syncCodeForm(client, codeForm).then((r) => {
       if (cancelled) return;
-      setSynced({ formId: r.formId, status: r.status ?? null });
+      if ((r.staged || r.syncError) && !r.resolvedSchema) {
+        throw new FilloError(
+          "Sync did not return the live schema needed to render safely. Publish changes before deploy, and update @usefillo/* or your API.",
+          409,
+          void 0,
+          "sync_snapshot_required"
+        );
+      }
+      const noticeError = r.syncError ? new FilloError(r.syncError.message, 403, void 0, r.syncError.code) : null;
+      setSynced({
+        key: syncKey,
+        client,
+        settled: true,
+        formId: r.formId,
+        status: r.status ?? null,
+        branding: r.branding,
+        error: null,
+        noticeError,
+        staged: Boolean(r.staged),
+        resolvedSchema: r.resolvedSchema,
+        resolvedTheme: r.resolvedTheme
+      });
       const dashboardUrl = `${client.baseUrl || "https://fillo.so"}/forms/${r.formId}`;
       if (r.warning) console.warn(`[fillo] ${r.warning}`);
+      if (noticeError) {
+        console.warn(
+          `[fillo] form sync needs attention (${noticeError.code}): ${noticeError.message}`
+        );
+        onErrorRef.current?.(noticeError);
+      }
       if (r.staged) {
-        noticeSync(codeForm.id, "staged", `[fillo] "${codeForm.id}": changes staged as a draft \u2014 publish them at ${dashboardUrl}`);
+        noticeSync(
+          codeForm.id,
+          "staged",
+          `[fillo] "${codeForm.id}": changes staged as a draft \u2014 the live version remains rendered until you publish them at ${dashboardUrl}`
+        );
       } else if (r.status === "draft") {
         noticeSync(codeForm.id, "draft", `[fillo] "${codeForm.id}" is a draft \u2014 it renders here but won't accept responses until published: ${dashboardUrl}`);
       }
     }).catch((err) => {
-      const error = err instanceof FilloError ? err : new FilloError(String(err), 0);
-      console.warn("[fillo] form sync failed:", error.message);
-      if (!cancelled) onError?.(error);
+      if (cancelled) return;
+      const error = isFilloError(err) ? err : new FilloError(String(err), 0);
+      console.warn(
+        `[fillo] form sync failed${error.code ? ` (${error.code})` : ""}: ${error.message}`
+      );
+      setSynced({
+        key: syncKey,
+        client,
+        settled: true,
+        formId: null,
+        status: null,
+        error,
+        noticeError: null,
+        staged: false
+      });
+      onErrorRef.current?.(error);
     });
     return () => {
       cancelled = true;
     };
-  }, [hasKey, handle, contentKey, client, onError]);
-  return synced;
+  }, [hasKey, handle, contentKey, client, syncKey, allowUnsynced]);
+  return synced.key === syncKey && synced.client === client ? {
+    formId: synced.formId,
+    status: synced.status,
+    branding: synced.branding,
+    error: synced.error,
+    noticeError: synced.noticeError,
+    syncing: Boolean(syncKey) && !synced.settled,
+    staged: synced.staged,
+    resolvedSchema: synced.resolvedSchema,
+    resolvedTheme: synced.resolvedTheme
+  } : {
+    formId: null,
+    status: null,
+    error: null,
+    noticeError: null,
+    syncing: Boolean(syncKey),
+    staged: false
+  };
 }
 
 // src/fields.tsx
-import { isField, pipeBlock, shouldAutoSubmit, slotClass as slotClass2, visibleFields } from "@usefillo/core";
+import { isField, pipeBlock, REQUIRED_FIELD_MESSAGE, shouldAutoSubmit, slotClass as slotClass2, visibleFields } from "@usefillo/core";
 import { memo, useEffect as useEffect6, useMemo as useMemo4, useState as useState5 } from "react";
 
 // src/phone.tsx
@@ -205,9 +354,10 @@ import {
   flagEmoji,
   formatNational,
   parsePhone,
+  positionPhonePopover,
   toE164
 } from "@usefillo/core";
-import { useEffect as useEffect3, useLayoutEffect, useMemo as useMemo3, useRef as useRef2, useState as useState2 } from "react";
+import { useEffect as useEffect3, useLayoutEffect, useMemo as useMemo3, useRef as useRef3, useState as useState2 } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 function localeCountry() {
   if (typeof navigator === "undefined") return void 0;
@@ -228,31 +378,6 @@ function nationalFor(stored, country) {
   const digits = digitsOnly(stored);
   return digits.startsWith(country.dialCode) ? digits.slice(country.dialCode.length) : digits;
 }
-var PHONE_POPOVER_VIEWPORT_GAP = 8;
-function positionPhonePopover(anchor, popover) {
-  if (!anchor || !popover || typeof window === "undefined") return "below";
-  const gap = PHONE_POPOVER_VIEWPORT_GAP;
-  const viewportWidth = document.documentElement.clientWidth || window.innerWidth;
-  const viewportHeight = document.documentElement.clientHeight || window.innerHeight;
-  const anchorRect = anchor.getBoundingClientRect();
-  const spaceBelow = Math.max(0, viewportHeight - anchorRect.bottom - gap);
-  const spaceAbove = Math.max(0, anchorRect.top - gap);
-  const placement = spaceBelow < popover.scrollHeight && spaceAbove > spaceBelow ? "above" : "below";
-  const availableHeight = placement === "above" ? spaceAbove : spaceBelow;
-  const maxHeight = Math.max(0, Math.min(availableHeight, viewportHeight - gap * 2));
-  const maxWidth = Math.max(0, viewportWidth - gap * 2);
-  popover.style.setProperty("--fillo-phone-popover-max-height", `${Math.floor(maxHeight)}px`);
-  popover.style.setProperty("--fillo-phone-popover-max-width", `${Math.floor(maxWidth)}px`);
-  popover.style.setProperty("--fillo-phone-popover-offset-x", "0px");
-  const width = Math.min(popover.offsetWidth, maxWidth);
-  let offsetX = 0;
-  const rightOverflow = anchorRect.left + width - (viewportWidth - gap);
-  if (rightOverflow > 0) offsetX -= rightOverflow;
-  const leftOverflow = gap - (anchorRect.left + offsetX);
-  if (leftOverflow > 0) offsetX += leftOverflow;
-  popover.style.setProperty("--fillo-phone-popover-offset-x", `${Math.round(offsetX)}px`);
-  return placement;
-}
 function PhoneField({ field, value, error, setValue, ids: providedIds }) {
   const ids = useFilloFieldIds(field.id, providedIds);
   const slots = useFieldSlots(field, error);
@@ -262,7 +387,12 @@ function PhoneField({ field, value, error, setValue, ids: providedIds }) {
   const [country, setCountry] = useState2(
     () => parsePhone(stored).country ?? countryByIso(schema.defaultCountry) ?? PHONE_COUNTRIES[0]
   );
-  const touched = useRef2(false);
+  const touched = useRef3(false);
+  useEffect3(() => {
+    if (touched.current || !stored) return;
+    const restoredCountry = parsePhone(stored).country;
+    if (restoredCountry) setCountry(restoredCountry);
+  }, [stored]);
   useEffect3(() => {
     if (touched.current) return;
     if (parsePhone(stored).country || countryByIso(schema.defaultCountry)) return;
@@ -271,8 +401,8 @@ function PhoneField({ field, value, error, setValue, ids: providedIds }) {
   }, []);
   const national = nationalFor(stored, country);
   const display = formatNational(country, national);
-  const inputRef = useRef2(null);
-  const caretDigits = useRef2(null);
+  const inputRef = useRef3(null);
+  const caretDigits = useRef3(null);
   useLayoutEffect(() => {
     const el = inputRef.current;
     if (!el || caretDigits.current == null) return;
@@ -350,10 +480,10 @@ function CountrySelect({
   const [query, setQuery] = useState2("");
   const [active, setActive] = useState2(0);
   const [placement, setPlacement] = useState2("below");
-  const rootRef = useRef2(null);
-  const triggerRef = useRef2(null);
-  const popoverRef = useRef2(null);
-  const searchRef = useRef2(null);
+  const rootRef = useRef3(null);
+  const triggerRef = useRef3(null);
+  const popoverRef = useRef3(null);
+  const searchRef = useRef3(null);
   const listId = `${labelledBy}-countries`;
   const matches = useMemo3(() => {
     const q = query.trim().toLowerCase();
@@ -423,6 +553,7 @@ function CountrySelect({
         className: "fillo-phone-flag",
         "aria-haspopup": "listbox",
         "aria-expanded": open,
+        "aria-controls": open ? listId : void 0,
         "aria-label": `Country: ${country.name} (+${country.dialCode})`,
         onClick: () => setOpen((o) => !o),
         children: [
@@ -446,6 +577,7 @@ function CountrySelect({
           "aria-expanded": "true",
           "aria-controls": listId,
           "aria-autocomplete": "list",
+          "aria-label": "Search country or code",
           "aria-activedescendant": matches[active] ? `${listId}-opt-${active}` : void 0,
           placeholder: "Search country or code",
           value: query,
@@ -487,15 +619,15 @@ function CountrySelect({
 }
 
 // src/signature.tsx
-import { useEffect as useEffect4, useRef as useRef3, useState as useState3 } from "react";
+import { useEffect as useEffect4, useRef as useRef4, useState as useState3 } from "react";
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 function SignatureField({ field, value, error, setValue, ids: providedIds }) {
   const ids = useFilloFieldIds(field.id, providedIds);
   const slots = useFieldSlots(field, error);
   const strings = useStrings();
   const typedInputId = `${ids.inputId}-typed`;
-  const canvasRef = useRef3(null);
-  const drawing = useRef3(false);
+  const canvasRef = useRef4(null);
+  const drawing = useRef4(false);
   const [hasInk, setHasInk] = useState3(Boolean(value));
   const [typedName, setTypedName] = useState3("");
   useEffect4(() => {
@@ -512,12 +644,31 @@ function SignatureField({ field, value, error, setValue, ids: providedIds }) {
     ctx.lineCap = "round";
     ctx.lineJoin = "round";
     ctx.strokeStyle = getComputedStyle(canvas).color;
+  }, []);
+  useEffect4(() => {
+    const canvas = canvasRef.current;
+    const ctx = canvas?.getContext("2d");
+    if (!canvas || !ctx) return;
+    let cancelled = false;
+    const rect = canvas.getBoundingClientRect();
     if (typeof value === "string" && value.startsWith("data:image/")) {
+      setHasInk(true);
       const img = new Image();
-      img.onload = () => ctx.drawImage(img, 0, 0, rect.width, rect.height);
+      img.onload = () => {
+        if (cancelled) return;
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        ctx.drawImage(img, 0, 0, rect.width, rect.height);
+      };
       img.src = value;
+    } else {
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
+      setHasInk(false);
+      setTypedName("");
     }
-  }, []);
+    return () => {
+      cancelled = true;
+    };
+  }, [value]);
   function point(e) {
     const rect = e.currentTarget.getBoundingClientRect();
     return { x: e.clientX - rect.left, y: e.clientY - rect.top };
@@ -597,6 +748,7 @@ function SignatureField({ field, value, error, setValue, ids: providedIds }) {
                 onPointerDown: start,
                 onPointerMove: move,
                 onPointerUp: end,
+                onPointerCancel: end,
                 onPointerLeave: end
               }
             ),
@@ -632,21 +784,15 @@ function SignatureField({ field, value, error, setValue, ids: providedIds }) {
 }
 
 // src/upload.tsx
-import { useEffect as useEffect5, useRef as useRef4, useState as useState4 } from "react";
+import { useEffect as useEffect5, useRef as useRef5, useState as useState4 } from "react";
 import { Fragment, jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
-function uploadStatus(inFlight, doneCount) {
+function uploadStatus(inFlight, doneCount, strings) {
   const failed = inFlight.filter((f) => f.error).length;
   const active = inFlight.length - failed;
   const parts = [];
-  if (active > 0) {
-    parts.push(`Uploading ${active} ${active === 1 ? "file" : "files"}, please wait\u2026`);
-  }
-  if (failed > 0) {
-    parts.push(`${failed} ${failed === 1 ? "upload" : "uploads"} failed.`);
-  }
-  if (active === 0 && doneCount > 0) {
-    parts.push(`${doneCount} ${doneCount === 1 ? "file" : "files"} uploaded.`);
-  }
+  if (active > 0) parts.push(strings.filesUploading(active));
+  if (failed > 0) parts.push(strings.uploadsFailed(failed));
+  if (active === 0 && doneCount > 0) parts.push(strings.filesUploaded(doneCount));
   return parts.join(" ");
 }
 function formatBytes(bytes) {
@@ -660,41 +806,49 @@ function FileUploadField({ field, value, error, setValue, api, ids: providedIds
   const slots = useFieldSlots(field, error);
   const strings = useStrings();
   const schema = field;
-  const inputRef = useRef4(null);
+  const inputRef = useRef5(null);
   const [inFlight, setInFlight] = useState4([]);
   const [dragOver, setDragOver] = useState4(false);
-  const mountedRef = useRef4(true);
-  const controllers = useRef4(/* @__PURE__ */ new Map());
-  const inFlightCount = useRef4(0);
-  useEffect5(
-    () => () => {
+  const mountedRef = useRef5(true);
+  const controllers = useRef5(/* @__PURE__ */ new Map());
+  const inFlightCount = useRef5(0);
+  const setUploading = api.setUploading;
+  const fieldId = field.id;
+  useEffect5(() => {
+    mountedRef.current = true;
+    return () => {
       mountedRef.current = false;
       controllers.current.forEach((c) => c.abort());
-    },
-    []
-  );
+      if (inFlightCount.current > 0) setUploading(fieldId, false);
+    };
+  }, [fieldId, setUploading]);
   const files = Array.isArray(value) ? value : [];
+  const filesRef = useRef5(files);
+  filesRef.current = files;
   const maxFiles = schema.maxFiles ?? 1;
-  const maxBytes = (schema.maxFileSizeMb ?? 500) * 1024 * 1024;
+  const maxMb = schema.maxFileSizeMb ?? 500;
+  const maxBytes = maxMb * 1024 * 1024;
   const canUpload = Boolean(api.client && api.formId);
-  const remaining = maxFiles - files.length - inFlight.length;
+  const activeInFlight = inFlight.filter((f) => !f.error).length;
+  const remaining = maxFiles - files.length - activeInFlight;
   async function startUpload(file) {
+    if (maxFiles - filesRef.current.length - inFlightCount.current <= 0) return;
     const key = `${file.name}-${file.size}-${Math.floor(performance.now())}`;
     if (file.size > maxBytes) {
       setInFlight((prev) => [
         ...prev,
-        { key, name: file.name, size: file.size, fraction: 0, error: `Larger than ${schema.maxFileSizeMb ?? 500} MB limit` }
+        { key, name: file.name, size: file.size, fraction: 0, file, tooLarge: true, error: strings.fileTooLarge(maxMb) }
       ]);
       return;
     }
-    setInFlight((prev) => [...prev, { key, name: file.name, size: file.size, fraction: 0 }]);
+    setInFlight((prev) => [...prev, { key, name: file.name, size: file.size, fraction: 0, file }]);
     inFlightCount.current += 1;
-    api.setUploading(field.id, true);
+    setUploading(fieldId, true);
     const controller = new AbortController();
     controllers.current.set(key, controller);
     try {
       const uploaded = await api.client.uploadFile(api.formId, file, {
-        fieldId: field.id,
+        fieldId,
         signal: controller.signal,
         onProgress: ({ fraction }) => {
           if (mountedRef.current) {
@@ -704,11 +858,12 @@ function FileUploadField({ field, value, error, setValue, api, ids: providedIds
       });
       if (!mountedRef.current) return;
       setInFlight((prev) => prev.filter((f) => f.key !== key));
-      const current = Array.isArray(api.data[field.id]) ? api.data[field.id] : [];
-      setValue([...current, uploaded]);
+      const next = [...filesRef.current, uploaded].slice(0, maxFiles);
+      filesRef.current = next;
+      setValue(next);
     } catch (err) {
       if (mountedRef.current) {
-        const message = err instanceof Error && err.name === "FilloError" && err.message ? err.message : "Upload failed \u2014 try again";
+        const message = err instanceof Error && err.name === "FilloError" && err.message ? err.message : strings.uploadFailed;
         setInFlight(
           (prev) => prev.map((f) => f.key === key ? { ...f, error: message } : f)
         );
@@ -716,7 +871,7 @@ function FileUploadField({ field, value, error, setValue, api, ids: providedIds
     } finally {
       controllers.current.delete(key);
       inFlightCount.current -= 1;
-      if (mountedRef.current && inFlightCount.current === 0) api.setUploading(field.id, false);
+      if (mountedRef.current && inFlightCount.current === 0) setUploading(fieldId, false);
     }
   }
   function cancelUpload(key) {
@@ -725,11 +880,14 @@ function FileUploadField({ field, value, error, setValue, api, ids: providedIds
   }
   function handleFiles(list) {
     if (!list) return;
-    Array.from(list).slice(0, Math.max(0, remaining)).forEach((file) => void startUpload(file));
+    const currentRoom = Math.max(0, maxFiles - filesRef.current.length - inFlightCount.current);
+    Array.from(list).slice(0, currentRoom).forEach((file) => void startUpload(file));
     if (inputRef.current) inputRef.current.value = "";
   }
   function removeFile(fileId) {
-    setValue(files.filter((f) => f.fileId !== fileId));
+    const next = filesRef.current.filter((f) => f.fileId !== fileId);
+    filesRef.current = next;
+    setValue(next);
   }
   const describedBy = [field.description ? ids.descriptionId : null, error ? ids.errorId : null].filter(Boolean).join(" ") || void 0;
   return /* @__PURE__ */ jsxs3("div", { ...slots.wrapperProps(`fillo-field fillo-field--file_upload${error ? " fillo-field--error" : ""}`), children: [
@@ -757,12 +915,16 @@ function FileUploadField({ field, value, error, setValue, api, ids: providedIds
         onClick: () => canUpload && inputRef.current?.click(),
         role: "button",
         tabIndex: 0,
+        "aria-disabled": !canUpload || void 0,
         "aria-labelledby": ids.labelId,
         "aria-required": field.required ? true : void 0,
         "aria-invalid": error ? true : void 0,
         "aria-describedby": describedBy,
         onKeyDown: (e) => {
-          if ((e.key === "Enter" || e.key === " ") && canUpload) inputRef.current?.click();
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            if (canUpload) inputRef.current?.click();
+          }
         },
         children: [
           /* @__PURE__ */ jsx3(
@@ -772,23 +934,16 @@ function FileUploadField({ field, value, error, setValue, api, ids: providedIds
               id: ids.inputId,
               type: "file",
               hidden: true,
+              disabled: !canUpload,
               multiple: maxFiles > 1,
               accept: schema.accept?.join(","),
               onChange: (e) => canUpload && handleFiles(e.target.files)
             }
           ),
           canUpload ? /* @__PURE__ */ jsxs3(Fragment, { children: [
-            /* @__PURE__ */ jsxs3("span", { className: "fillo-dropzone-title", children: [
-              "Drop ",
-              maxFiles > 1 ? "files" : "a file",
-              " here or click to browse"
-            ] }),
-            /* @__PURE__ */ jsxs3("span", { className: "fillo-dropzone-hint", children: [
-              "Up to ",
-              schema.maxFileSizeMb ?? 500,
-              " MB per file \xB7 resumable"
-            ] })
-          ] }) : /* @__PURE__ */ jsx3("span", { className: "fillo-dropzone-hint", children: "Uploads are disabled in preview" })
+            /* @__PURE__ */ jsx3("span", { className: "fillo-dropzone-title", children: strings.dropzoneTitle(maxFiles > 1) }),
+            /* @__PURE__ */ jsx3("span", { className: "fillo-dropzone-hint", children: strings.dropzoneHint(maxMb) })
+          ] }) : /* @__PURE__ */ jsx3("span", { className: "fillo-dropzone-hint", children: strings.uploadsDisabled })
         ]
       }
     ),
@@ -799,7 +954,7 @@ function FileUploadField({ field, value, error, setValue, api, ids: providedIds
         "aria-live": "polite",
         className: "fillo-sr-only",
         style: { position: "absolute", left: "-9999px", width: 1, height: 1, overflow: "hidden" },
-        children: uploadStatus(inFlight, files.length)
+        children: uploadStatus(inFlight, files.length, strings)
       }
     ),
     (inFlight.length > 0 || files.length > 0) && /* @__PURE__ */ jsxs3("ul", { className: "fillo-files", children: [
@@ -832,6 +987,21 @@ function FileUploadField({ field, value, error, setValue, api, ids: providedIds
             /* @__PURE__ */ jsx3("span", { className: "fillo-file-name", children: f.name }),
             f.error ? /* @__PURE__ */ jsxs3(Fragment, { children: [
               /* @__PURE__ */ jsx3("span", { className: "fillo-file-meta", children: f.error }),
+              f.file && !f.tooLarge && remaining > 0 && /* @__PURE__ */ jsx3(
+                "button",
+                {
+                  type: "button",
+                  className: "fillo-file-retry",
+                  "aria-label": `${strings.uploadRetry} ${f.name}`,
+                  onClick: () => {
+                    const retryFile = f.file;
+                    if (!retryFile) return;
+                    setInFlight((prev) => prev.filter((x) => x.key !== f.key));
+                    void startUpload(retryFile);
+                  },
+                  children: strings.uploadRetry
+                }
+              ),
               /* @__PURE__ */ jsx3(
                 "button",
                 {
@@ -950,6 +1120,9 @@ function TextInput({ field, value, error, setValue, ids: providedIds }) {
       type,
       value: typeof value === "string" || typeof value === "number" ? String(value) : "",
       placeholder: field.placeholder,
+      maxLength: "maxLength" in field ? field.maxLength : void 0,
+      min: field.kind === "number" ? field.min : void 0,
+      max: field.kind === "number" ? field.max : void 0,
       onChange: (e) => setValue(e.target.value),
       ...fieldAria(field, error, ids)
     }
@@ -966,6 +1139,7 @@ function LongText({ field, value, error, setValue, ids: providedIds }) {
       rows: 4,
       value: typeof value === "string" ? value : "",
       placeholder: field.placeholder,
+      maxLength: "maxLength" in field ? field.maxLength : void 0,
       onChange: (e) => setValue(e.target.value),
       ...fieldAria(field, error, ids)
     }
@@ -1221,12 +1395,18 @@ function MultiChoice({ field, value, error, setValue, ids: providedIds }) {
     }
   ) });
 }
-var OTHER_SENTINEL = "__fw_other__";
+function otherSentinel(field) {
+  let value = "__fillo_other__";
+  const ids = new Set(field.options.map((option) => option.id));
+  while (ids.has(value)) value += "_";
+  return value;
+}
 function Dropdown({ field, value, error, setValue, ids: providedIds }) {
   const ids = useFilloFieldIds(field.id, providedIds);
   const strings = useStrings();
   const choice = field;
   const options = useDisplayOptions(choice);
+  const otherValue = otherSentinel(choice);
   const isOtherValue = typeof value === "string" && value !== "" && !choice.options.some((o) => o.id === value);
   const [otherOn, setOtherOn] = useState5(isOtherValue);
   const otherActive = isOtherValue || value === "" && otherOn;
@@ -1239,9 +1419,9 @@ function Dropdown({ field, value, error, setValue, ids: providedIds }) {
           id: ids.inputId,
           ...control,
           ...fieldAria(field, error, ids),
-          value: otherActive ? OTHER_SENTINEL : typeof value === "string" ? value : "",
+          value: otherActive ? otherValue : typeof value === "string" ? value : "",
           onChange: (e) => {
-            if (e.target.value === OTHER_SENTINEL) {
+            if (e.target.value === otherValue) {
               setOtherOn(true);
               setValue("");
             } else {
@@ -1252,7 +1432,7 @@ function Dropdown({ field, value, error, setValue, ids: providedIds }) {
           children: [
             /* @__PURE__ */ jsx4("option", { value: "", children: field.placeholder ?? strings.choosePlaceholder }),
             options.map((opt) => /* @__PURE__ */ jsx4("option", { value: opt.id, children: opt.label }, opt.id)),
-            choice.allowOther && /* @__PURE__ */ jsx4("option", { value: OTHER_SENTINEL, children: `${strings.other}\u2026` })
+            choice.allowOther && /* @__PURE__ */ jsx4("option", { value: otherValue, children: `${strings.other}\u2026` })
           ]
         }
       ),
@@ -1276,17 +1456,15 @@ function Checkbox({ field, value, error, setValue, ids: providedIds }) {
   const ids = useFilloFieldIds(field.id, providedIds);
   const strings = useStrings();
   const appearance = useFilloAppearance();
+  const slots = useFieldSlots(field, error);
   const checkbox = field;
   if (checkbox.appearance === "toggle") {
     return /* @__PURE__ */ jsxs4(
       "div",
       {
-        className: `fillo-field fillo-field--checkbox fillo-field--toggle${error ? " fillo-field--error" : ""}`,
-        "data-fillo": "field",
-        "data-field": field.id,
-        "data-kind": field.kind,
-        "data-invalid": error ? "" : void 0,
-        "data-required": field.required ? "" : void 0,
+        ...slots.wrapperProps(
+          `fillo-field fillo-field--checkbox fillo-field--toggle${error ? " fillo-field--error" : ""}`
+        ),
         children: [
           /* @__PURE__ */ jsxs4("label", { className: "fillo-toggle", "data-fillo": "option", "data-checked": value === true ? "" : void 0, children: [
             /* @__PURE__ */ jsx4("span", { className: "fillo-toggle-copy", children: /* @__PURE__ */ jsxs4("span", { className: slotClass2("fillo-option-label", appearance, { slot: "optionLabel", kind: field.kind, fieldId: field.id }), "data-fillo": "optionLabel", children: [
@@ -1308,8 +1486,8 @@ function Checkbox({ field, value, error, setValue, ids: providedIds }) {
             ),
             /* @__PURE__ */ jsx4("span", { className: "fillo-toggle-track", "aria-hidden": "true", children: /* @__PURE__ */ jsx4("span", { className: "fillo-toggle-thumb" }) })
           ] }),
-          field.description && /* @__PURE__ */ jsx4("p", { className: "fillo-description", id: ids.descriptionId, children: field.description }),
-          error && /* @__PURE__ */ jsx4("p", { className: "fillo-error", id: ids.errorId, role: "alert", children: error })
+          field.description && /* @__PURE__ */ jsx4("p", { className: slots.description, "data-fillo": "fieldDescription", id: ids.descriptionId, children: field.description }),
+          error && /* @__PURE__ */ jsx4("p", { className: slots.error, "data-fillo": "error", id: ids.errorId, role: "alert", children: error })
         ]
       }
     );
@@ -1317,12 +1495,9 @@ function Checkbox({ field, value, error, setValue, ids: providedIds }) {
   return /* @__PURE__ */ jsxs4(
     "div",
     {
-      className: `fillo-field fillo-field--checkbox${error ? " fillo-field--error" : ""}`,
-      "data-fillo": "field",
-      "data-field": field.id,
-      "data-kind": field.kind,
-      "data-invalid": error ? "" : void 0,
-      "data-required": field.required ? "" : void 0,
+      ...slots.wrapperProps(
+        `fillo-field fillo-field--checkbox${error ? " fillo-field--error" : ""}`
+      ),
       children: [
         /* @__PURE__ */ jsxs4("label", { className: "fillo-option", "data-fillo": "option", "data-checked": value === true ? "" : void 0, children: [
           /* @__PURE__ */ jsx4(
@@ -1341,8 +1516,8 @@ function Checkbox({ field, value, error, setValue, ids: providedIds }) {
             !field.required && /* @__PURE__ */ jsx4("span", { className: "fillo-optional", children: strings.optional })
           ] })
         ] }),
-        field.description && /* @__PURE__ */ jsx4("p", { className: "fillo-description", id: ids.descriptionId, children: field.description }),
-        error && /* @__PURE__ */ jsx4("p", { className: "fillo-error", id: ids.errorId, role: "alert", children: error })
+        field.description && /* @__PURE__ */ jsx4("p", { className: slots.description, "data-fillo": "fieldDescription", id: ids.descriptionId, children: field.description }),
+        error && /* @__PURE__ */ jsx4("p", { className: slots.error, "data-fillo": "error", id: ids.errorId, role: "alert", children: error })
       ]
     }
   );
@@ -1488,73 +1663,106 @@ function Ranking({ field, value, error, setValue, ids: providedIds }) {
     [next[index], next[target]] = [next[target], next[index]];
     setValue(next);
   }
-  return /* @__PURE__ */ jsx4(FieldShell, { field, error, ids, children: /* @__PURE__ */ jsx4("ol", { className: "fillo-ranking", children: order.map((id, index) => {
-    const option = ranking.options.find((o) => o.id === id);
-    if (!option) return null;
-    return /* @__PURE__ */ jsxs4("li", { className: "fillo-ranking-item", children: [
-      /* @__PURE__ */ jsx4("span", { className: "fillo-ranking-index", children: index + 1 }),
-      /* @__PURE__ */ jsx4("span", { className: "fillo-ranking-label", children: option.label }),
-      /* @__PURE__ */ jsxs4("span", { className: "fillo-ranking-controls", children: [
-        /* @__PURE__ */ jsx4(
-          "button",
-          {
-            type: "button",
-            className: "fillo-ranking-move",
-            "aria-label": `Move ${option.label} up`,
-            disabled: index === 0,
-            onClick: () => move(id, -1),
-            children: "\u2191"
-          }
-        ),
-        /* @__PURE__ */ jsx4(
-          "button",
-          {
-            type: "button",
-            className: "fillo-ranking-move",
-            "aria-label": `Move ${option.label} down`,
-            disabled: index === order.length - 1,
-            onClick: () => move(id, 1),
-            children: "\u2193"
-          }
-        )
-      ] })
-    ] }, id);
-  }) }) });
+  return /* @__PURE__ */ jsx4(FieldShell, { field, error, ids, children: /* @__PURE__ */ jsx4(
+    "div",
+    {
+      id: ids.inputId,
+      role: "group",
+      "aria-labelledby": ids.labelId,
+      ...fieldAria(field, error, ids),
+      children: /* @__PURE__ */ jsx4("ol", { className: "fillo-ranking", children: order.map((id, index) => {
+        const option = ranking.options.find((o) => o.id === id);
+        if (!option) return null;
+        return /* @__PURE__ */ jsxs4("li", { className: "fillo-ranking-item", children: [
+          /* @__PURE__ */ jsx4("span", { className: "fillo-ranking-index", children: index + 1 }),
+          /* @__PURE__ */ jsx4("span", { className: "fillo-ranking-label", children: option.label }),
+          /* @__PURE__ */ jsxs4("span", { className: "fillo-ranking-controls", children: [
+            /* @__PURE__ */ jsx4(
+              "button",
+              {
+                type: "button",
+                className: "fillo-ranking-move",
+                "aria-label": `Move ${option.label} up`,
+                disabled: index === 0,
+                onClick: () => move(id, -1),
+                children: "\u2191"
+              }
+            ),
+            /* @__PURE__ */ jsx4(
+              "button",
+              {
+                type: "button",
+                className: "fillo-ranking-move",
+                "aria-label": `Move ${option.label} down`,
+                disabled: index === order.length - 1,
+                onClick: () => move(id, 1),
+                children: "\u2193"
+              }
+            )
+          ] })
+        ] }, id);
+      }) })
+    }
+  ) });
 }
 function Matrix({ field, value, error, setValue, ids: providedIds }) {
   const ids = useFilloFieldIds(field.id, providedIds);
   const matrix = field;
   const answers = value && typeof value === "object" && !Array.isArray(value) ? value : {};
-  return /* @__PURE__ */ jsx4(FieldShell, { field, error, ids, children: /* @__PURE__ */ jsx4("div", { className: "fillo-matrix-wrap", children: /* @__PURE__ */ jsxs4("table", { className: "fillo-matrix", children: [
-    /* @__PURE__ */ jsx4("thead", { children: /* @__PURE__ */ jsxs4("tr", { children: [
-      /* @__PURE__ */ jsx4("th", {}),
-      matrix.columns.map((col) => /* @__PURE__ */ jsx4("th", { scope: "col", children: col.label }, col.id))
-    ] }) }),
-    /* @__PURE__ */ jsx4("tbody", { children: matrix.rows.map((row) => {
-      const rowLabelId = `${ids.inputId}-${row.id}`;
-      const answered = answers[row.id] !== void 0;
-      const rowInvalid = Boolean(error) && field.required && !answered;
-      return (
-        // Each row is its own radiogroup, labelled by the row question.
-        /* @__PURE__ */ jsxs4("tr", { role: "radiogroup", "aria-labelledby": rowLabelId, children: [
-          /* @__PURE__ */ jsx4("th", { scope: "row", id: rowLabelId, children: row.label }),
-          matrix.columns.map((col) => /* @__PURE__ */ jsx4("td", { children: /* @__PURE__ */ jsx4(
-            "input",
-            {
-              type: "radio",
-              className: "fillo-option-input",
-              name: `${ids.name}-${row.id}`,
-              "aria-label": `${row.label}: ${col.label}`,
-              "aria-required": field.required ? true : void 0,
-              "aria-invalid": rowInvalid ? true : void 0,
-              checked: answers[row.id] === col.id,
-              onChange: () => setValue({ ...answers, [row.id]: col.id })
-            }
-          ) }, col.id))
-        ] }, row.id)
-      );
-    }) })
-  ] }) }) });
+  return /* @__PURE__ */ jsx4(FieldShell, { field, error, ids, children: /* @__PURE__ */ jsx4(
+    "div",
+    {
+      id: ids.inputId,
+      className: "fillo-matrix-wrap",
+      role: "group",
+      "aria-labelledby": ids.labelId,
+      ...fieldAria(field, error, ids),
+      children: /* @__PURE__ */ jsxs4("table", { className: "fillo-matrix", children: [
+        /* @__PURE__ */ jsx4("thead", { children: /* @__PURE__ */ jsxs4("tr", { children: [
+          /* @__PURE__ */ jsx4("th", {}),
+          matrix.columns.map((col) => /* @__PURE__ */ jsx4("th", { scope: "col", children: col.label }, col.id))
+        ] }) }),
+        /* @__PURE__ */ jsx4("tbody", { children: matrix.rows.map((row) => {
+          const rowLabelId = `${ids.inputId}-${row.id}`;
+          const answered = answers[row.id] !== void 0;
+          const rowInvalid = Boolean(error) && field.required && !answered;
+          const radioId = (col) => `${ids.inputId}-${row.id}-${col.id}`;
+          return (
+            // The <tr> keeps its native row role so the grid's row/column
+            // header association survives for screen readers. The row's
+            // radiogroup lives on an inner element that aria-owns the radios
+            // scattered across the cells (they can't be DOM-nested inside a
+            // single element within a table row).
+            /* @__PURE__ */ jsxs4("tr", { children: [
+              /* @__PURE__ */ jsx4("th", { scope: "row", children: /* @__PURE__ */ jsx4(
+                "div",
+                {
+                  role: "radiogroup",
+                  "aria-labelledby": rowLabelId,
+                  "aria-owns": matrix.columns.map(radioId).join(" "),
+                  children: /* @__PURE__ */ jsx4("span", { id: rowLabelId, children: row.label })
+                }
+              ) }),
+              matrix.columns.map((col) => /* @__PURE__ */ jsx4("td", { children: /* @__PURE__ */ jsx4(
+                "input",
+                {
+                  id: radioId(col),
+                  type: "radio",
+                  className: "fillo-option-input",
+                  name: `${ids.name}-${row.id}`,
+                  "aria-label": `${row.label}: ${col.label}`,
+                  "aria-required": field.required ? true : void 0,
+                  "aria-invalid": rowInvalid ? true : void 0,
+                  checked: answers[row.id] === col.id,
+                  onChange: () => setValue({ ...answers, [row.id]: col.id })
+                }
+              ) }, col.id))
+            ] }, row.id)
+          );
+        }) })
+      ] })
+    }
+  ) });
 }
 function Hidden() {
   return null;
@@ -1608,8 +1816,8 @@ function blockPropsEqual(prev, next) {
   const id = next.block.id;
   if (prev.api.data[id] !== next.api.data[id]) return false;
   if (prev.api.errors[id] !== next.api.errors[id]) return false;
-  if (next.block.kind === "custom") {
-    return prev.api.data === next.api.data && prev.api.status === next.api.status && prev.api.uploading === next.api.uploading && prev.api.isFirstPage === next.api.isFirstPage && prev.api.isLastPage === next.api.isLastPage && prev.api.pageIndex === next.api.pageIndex;
+  if (next.block.kind === "custom" || isField(next.block) && Boolean(next.components?.[next.block.kind])) {
+    return prev.api === next.api;
   }
   if ((blockHasPiping(prev.block) || blockHasPiping(next.block)) && prev.api.data !== next.api.data) {
     return false;
@@ -1624,6 +1832,7 @@ function blockPropsEqual(prev, next) {
 function BlockRendererInner({ block, api, components, customComponents }) {
   block = pipeBlock(block, api.data, api.form);
   const ids = useFilloFieldIds(block.id);
+  const strings = useStrings();
   if (!isField(block)) return /* @__PURE__ */ jsx4(ContentRenderer, { block });
   let Component;
   if (block.kind === "custom") {
@@ -1640,12 +1849,14 @@ function BlockRendererInner({ block, api, components, customComponents }) {
   } else {
     Component = components?.[block.kind] ?? DEFAULT_COMPONENTS[block.kind];
   }
+  const rawError = api.errors[block.id];
+  const error = rawError === REQUIRED_FIELD_MESSAGE ? strings.required : rawError;
   return /* @__PURE__ */ jsx4(
     Component,
     {
       field: block,
       value: api.data[block.id],
-      error: api.errors[block.id],
+      error,
       setValue: (v) => {
         api.setValue(block.id, v);
         const ctx = {
@@ -1724,7 +1935,9 @@ function badgeUrl(href) {
 function focusFirstInvalid(formEl) {
   if (!formEl || typeof window === "undefined") return;
   const run = () => {
-    const target = formEl.querySelector('[aria-invalid="true"]');
+    const invalid = formEl.querySelector('[aria-invalid="true"]');
+    const focusable = 'input:not([disabled]), textarea:not([disabled]), select:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex="-1"])';
+    const target = invalid?.matches(focusable) ? invalid : invalid?.querySelector(focusable);
     target?.focus?.();
   };
   if (typeof requestAnimationFrame === "function") requestAnimationFrame(run);
@@ -1752,35 +1965,54 @@ function FilloForm(props) {
     () => props.client ?? (formId ? createClient() : void 0),
     [props.client, formId]
   );
-  const [fetched, setFetched] = useState6(null);
-  const [fetchedTheme, setFetchedTheme] = useState6(null);
-  const [loadError, setLoadError] = useState6(null);
-  const [closed, setClosed] = useState6(false);
-  const [fetchedBranding, setFetchedBranding] = useState6(null);
+  const [loaded, setLoaded] = useState6(null);
+  const [loadFailure, setLoadFailure] = useState6(null);
   const codeForm = isCodeForm2(form) ? form : null;
-  const inlineSchema = codeForm ? codeForm.schema : form;
   const onError = props.onError;
-  const { formId: syncedFormId, status: syncedStatus } = useCodeFormSync(form, client, onError);
-  const onErrorRef = useRef5(onError);
+  const {
+    formId: syncedFormId,
+    status: syncedStatus,
+    branding: syncedBranding,
+    error: syncError,
+    noticeError: syncNoticeError,
+    syncing: codeFormSyncing,
+    staged: codeChangesStaged,
+    resolvedSchema,
+    resolvedTheme
+  } = useCodeFormSync(form, client, onError, {
+    // An absent client is intentional render-only use. Builder previews and an
+    // explicit canonical id also do not need publishable-key resolution.
+    allowUnsynced: Boolean(!client || props.skipValidation || formId)
+  });
+  const renderResolvedSnapshot = Boolean(resolvedSchema && !isDevEnv());
+  const inlineSchema = codeForm ? renderResolvedSnapshot ? resolvedSchema : codeForm.schema : form;
+  const onErrorRef = useRef6(onError);
   useEffect7(() => {
     onErrorRef.current = onError;
   });
   const needsFetch = !inlineSchema && Boolean(client && formId);
   useEffect7(() => {
-    if (!needsFetch || !client || !formId) return;
+    if (!needsFetch || !client || !formId) {
+      setLoaded(null);
+      setLoadFailure(null);
+      return;
+    }
     let cancelled = false;
-    setFetched(null);
-    setLoadError(null);
+    setLoaded(null);
+    setLoadFailure(null);
     client.getForm(formId).then((published) => {
       if (cancelled) return;
-      setFetched(published.schema);
-      setFetchedTheme(published.theme);
-      setClosed(Boolean(published.closed));
-      setFetchedBranding(published.branding ?? null);
+      setLoaded({
+        formId,
+        schema: published.schema,
+        theme: published.theme,
+        closed: Boolean(published.closed),
+        branding: published.branding ?? null
+      });
     }).catch((err) => {
       if (cancelled) return;
       const error = err instanceof FilloError2 ? err : new FilloError2("This form could not be loaded.", 0);
-      setLoadError(error);
+      setLoadFailure({ formId, error });
       onErrorRef.current?.(error);
     });
     return () => {
@@ -1788,10 +2020,13 @@ function FilloForm(props) {
     };
   }, [needsFetch, client, formId]);
   const strings = resolveStrings(props.strings);
-  const rawSchema = inlineSchema ?? fetched;
+  const currentLoaded = needsFetch && loaded?.formId === formId ? loaded : null;
+  const loadError = needsFetch && loadFailure && loadFailure.formId === formId ? loadFailure.error : null;
+  const rawSchema = inlineSchema ?? currentLoaded?.schema ?? null;
   const normalized = useMemo5(() => rawSchema ? normalizeFormSchema(rawSchema) : null, [rawSchema]);
   const schema = normalized?.ok ? normalized.schema : null;
-  const theme = props.appearance?.theme ?? props.theme ?? codeForm?.theme ?? fetchedTheme ?? void 0;
+  const resolvedCodeTheme = renderResolvedSnapshot ? resolvedTheme ?? void 0 : codeForm?.theme;
+  const theme = props.appearance?.theme ?? props.theme ?? resolvedCodeTheme ?? currentLoaded?.theme ?? void 0;
   if (normalized && !normalized.ok) {
     const error = new FilloError2(`This form could not be rendered: ${normalized.error}`, 422);
     if (props.renderError) return /* @__PURE__ */ jsx5(Fragment2, { children: props.renderError(error) });
@@ -1804,16 +2039,34 @@ function FilloForm(props) {
     const message = loadError.status === 404 ? strings.loadFailedNotFound : loadError.status === 0 ? strings.loadFailedNetwork : strings.loadFailed;
     return /* @__PURE__ */ jsx5("div", { className: `fillo-form fillo-form--error ${props.className ?? ""}`, children: message });
   }
-  if (closed) {
+  if (currentLoaded?.closed) {
     return /* @__PURE__ */ jsx5("div", { className: `fillo-form fillo-form--closed ${props.className ?? ""}`, ...themeProps(theme), children: /* @__PURE__ */ jsx5("p", { className: "fillo-closed", children: strings.closed }) });
   }
+  const canonicalSyncError = codeForm && syncError && !props.skipValidation ? syncError : null;
+  if (canonicalSyncError && props.renderError) {
+    return /* @__PURE__ */ jsx5(Fragment2, { children: props.renderError(canonicalSyncError) });
+  }
+  if (canonicalSyncError && !isDevEnv()) {
+    return /* @__PURE__ */ jsx5(
+      "div",
+      {
+        className: `fillo-form fillo-form--error ${props.className ?? ""}`,
+        role: "alert",
+        "data-fillo": "root",
+        "data-state": "error",
+        ...themeProps(theme),
+        children: strings.loadFailed
+      }
+    );
+  }
   const notPublished = Boolean(codeForm) && syncedStatus === "draft" && !props.skipValidation;
   if (notPublished && !isDevEnv()) {
     const error = new FilloError2("This form isn't published yet.", 403);
     if (props.renderError) return /* @__PURE__ */ jsx5(Fragment2, { children: props.renderError(error) });
     return /* @__PURE__ */ jsx5("div", { className: `fillo-form fillo-form--closed ${props.className ?? ""}`, ...themeProps(theme), children: /* @__PURE__ */ jsx5("p", { className: "fillo-closed", children: strings.notLive }) });
   }
-  if (!schema) {
+  const awaitingCanonical = Boolean(codeForm && codeFormSyncing && !props.skipValidation);
+  if (!isDevEnv() && awaitingCanonical || !schema) {
     return /* @__PURE__ */ jsxs5(
       "div",
       {
@@ -1828,7 +2081,8 @@ function FilloForm(props) {
       }
     );
   }
-  const poweredBy = fetchedBranding?.poweredBy ?? true;
+  const branding = codeForm ? syncedBranding : currentLoaded?.branding;
+  const poweredBy = branding?.poweredBy ?? true;
   return /* @__PURE__ */ jsx5(
     ResolvedForm,
     {
@@ -1838,9 +2092,11 @@ function FilloForm(props) {
       theme,
       formId: syncedFormId ?? formId,
       poweredBy,
-      brandLabel: fetchedBranding?.label,
-      brandHref: fetchedBranding?.href,
-      draftNotice: notPublished
+      brandLabel: branding?.label,
+      brandHref: branding?.href,
+      draftNotice: notPublished,
+      stagedNotice: codeChangesStaged,
+      syncErrorNotice: syncError ?? syncNoticeError ?? void 0
     }
   );
 }
@@ -1864,18 +2120,85 @@ function DevDraftNotice() {
     " It renders here, but it won\u2019t accept responses until you publish it in your Fillo dashboard. (This notice only appears in development.)"
   ] });
 }
+function DevStagedNotice() {
+  return /* @__PURE__ */ jsxs5("div", { className: "fillo-devwarning", role: "alert", children: [
+    /* @__PURE__ */ jsx5("strong", { children: "Code changes are staged." }),
+    " This local preview is not the live form yet. Publish the changes in Fillo before deploying them for respondents."
+  ] });
+}
+function DevSyncErrorNotice({ error }) {
+  return /* @__PURE__ */ jsxs5("div", { className: "fillo-devwarning", role: "alert", children: [
+    /* @__PURE__ */ jsxs5("strong", { children: [
+      "Form sync needs attention",
+      error.code ? ` (${error.code})` : "",
+      "."
+    ] }),
+    " ",
+    error.message,
+    " The safe form remains available for development."
+  ] });
+}
 function ResolvedForm(props) {
   const { schema, theme } = props;
   const instanceId = useId2().replace(/:/g, "");
-  const hpRef = useRef5("");
+  const hpRef = useRef6(null);
   const codeForm = isCodeForm2(props.form) ? props.form : null;
   const client = props.client;
   const resolveFormId = useMemo5(
     () => codeForm && client?.key ? (
       // bypassCache: a stale cached formId must not be trusted at submit time.
-      () => syncCodeForm2(client, codeForm, { bypassCache: true }).then((r) => r.formId)
+      async () => {
+        try {
+          const result = await syncCodeForm2(client, codeForm, { bypassCache: true });
+          if (result.status === "draft") {
+            throw new FilloError2(
+              "This form is no longer published. Submission was stopped before sending answers.",
+              403,
+              void 0,
+              "form_not_published"
+            );
+          }
+          const authoritative = normalizeFormSchema(result.resolvedSchema ?? codeForm.schema);
+          if (!authoritative.ok) {
+            throw new FilloError2(
+              `The canonical form schema was invalid: ${authoritative.error}`,
+              502,
+              void 0,
+              "invalid_sync_schema"
+            );
+          }
+          if (!formSchemasEqual(schema, authoritative.schema)) {
+            throw new FilloError2(
+              "The live form changed after this page loaded. Submission stopped before incompatible answers were sent. Reload to use the published schema.",
+              409,
+              void 0,
+              "form_schema_changed"
+            );
+          }
+          if (result.syncError) {
+            const notice = new FilloError2(
+              result.syncError.message,
+              403,
+              void 0,
+              result.syncError.code
+            );
+            console.warn(
+              `[fillo] form sync needs attention (${notice.code}): ${notice.message}`
+            );
+            props.onError?.(notice);
+          }
+          return result.formId;
+        } catch (error) {
+          const failure = isFilloError2(error) ? error : new FilloError2(error instanceof Error ? error.message : String(error), 0);
+          console.warn(
+            `[fillo] form sync failed${failure.code ? ` (${failure.code})` : ""}: ${failure.message}`
+          );
+          props.onError?.(failure);
+          throw failure;
+        }
+      }
     ) : void 0,
-    [codeForm, client]
+    [codeForm, client, props.onError, schema]
   );
   const api = useFilloController({
     form: schema,
@@ -1885,26 +2208,29 @@ function ResolvedForm(props) {
     onChange: props.onChange,
     onSubmitted: props.onSubmitted,
     skipValidation: props.skipValidation,
-    getHoneypot: () => hpRef.current,
+    getHoneypot: () => hpRef.current?.value ?? "",
     // Framed renderer: Fillo draws the layout (and badge), so the surface is
     // "default", never the bare-engine "headless".
     surface: "default",
-    resolveFormId
+    resolveFormId,
+    respondent: props.respondent
   });
+  useDraftFlush(api);
   const themed = useMemo5(() => themeProps(theme), [theme]);
   const settings = schema.settings;
   const submitted = api.status === "submitted";
+  const liveSubmit = submitted && !api.restoredSubmission;
   useEffect7(() => {
-    if (!submitted || !settings.redirectUrl || typeof window === "undefined") return;
+    if (!liveSubmit || !settings.redirectUrl || typeof window === "undefined") return;
     const url = safeHttpUrl(settings.redirectUrl);
     if (url) window.location.assign(url);
-  }, [submitted, settings.redirectUrl]);
-  const successRef = useRef5(null);
+  }, [liveSubmit, settings.redirectUrl]);
+  const successRef = useRef6(null);
   useEffect7(() => {
-    if (submitted) successRef.current?.focus();
-  }, [submitted]);
-  const blocksRef = useRef5(null);
-  const prevPageIndex = useRef5(api.pageIndex);
+    if (liveSubmit) successRef.current?.focus();
+  }, [liveSubmit]);
+  const blocksRef = useRef6(null);
+  const prevPageIndex = useRef6(api.pageIndex);
   useEffect7(() => {
     if (prevPageIndex.current === api.pageIndex) return;
     prevPageIndex.current = api.pageIndex;
@@ -1937,7 +2263,7 @@ function ResolvedForm(props) {
               children: [
                 /* @__PURE__ */ jsx5("div", { className: "fillo-success-mark", "aria-hidden": "true", children: "\u2713" }),
                 /* @__PURE__ */ jsx5("h2", { className: "fillo-success-title", children: settings.successTitle ?? strings.successTitle }),
-                /* @__PURE__ */ jsx5("p", { className: "fillo-success-message", children: settings.successMessage ?? strings.successMessage })
+                /* @__PURE__ */ jsx5("p", { className: "fillo-success-message", children: api.duplicateSubmission ? strings.alreadyAnswered : settings.successMessage ?? strings.successMessage })
               ]
             }
           ),
@@ -1977,13 +2303,37 @@ function ResolvedForm(props) {
       children: [
         !props.client && !props.skipValidation && isDevEnv() && /* @__PURE__ */ jsx5(DevNoClientNotice, {}),
         props.draftNotice && isDevEnv() && /* @__PURE__ */ jsx5(DevDraftNotice, {}),
+        props.stagedNotice && isDevEnv() && /* @__PURE__ */ jsx5(DevStagedNotice, {}),
+        props.syncErrorNotice && isDevEnv() && /* @__PURE__ */ jsx5(DevSyncErrorNotice, { error: props.syncErrorNotice }),
+        (api.resumedDraft || api.editingPrevious) && /* @__PURE__ */ jsxs5(
+          "div",
+          {
+            className: slotClass3("fillo-resume", appearance, { slot: "resume" }),
+            "data-fillo": "resume",
+            role: "status",
+            children: [
+              /* @__PURE__ */ jsx5("span", { className: "fillo-resume-text", children: api.editingPrevious ? strings.editNotice : strings.resumeNotice }),
+              /* @__PURE__ */ jsx5("button", { type: "button", className: "fillo-resume-clear", onClick: api.resetDraft, children: strings.resumeStartOver })
+            ]
+          }
+        ),
+        api.resumeLinkFailed && !api.resumedDraft && !api.editingPrevious && /* @__PURE__ */ jsx5(
+          "div",
+          {
+            className: slotClass3("fillo-resume fillo-resume--expired", appearance, { slot: "resume" }),
+            "data-fillo": "resume",
+            role: "status",
+            children: /* @__PURE__ */ jsx5("span", { className: "fillo-resume-text", children: strings.resumeLinkExpired })
+          }
+        ),
         multiPage && settings.showProgress !== false && /* @__PURE__ */ jsx5(
           "div",
           {
             className: slotClass3("fillo-progress-track", appearance, { slot: "progress" }),
             "data-fillo": "progress",
             role: "progressbar",
-            "aria-valuemin": 0,
+            "aria-label": schema.title || "Form progress",
+            "aria-valuemin": 1,
             "aria-valuemax": api.pageCount,
             "aria-valuenow": api.pageIndex + 1,
             children: /* @__PURE__ */ jsx5(
@@ -1997,7 +2347,7 @@ function ResolvedForm(props) {
           }
         ),
         api.pageIndex === 0 && props.showTitle !== false && /* @__PURE__ */ jsxs5("header", { className: slotClass3("fillo-header", appearance, { slot: "header" }), "data-fillo": "header", children: [
-          /* @__PURE__ */ jsx5("h1", { className: slotClass3("fillo-title", appearance, { slot: "title" }), "data-fillo": "title", children: schema.title }),
+          schema.title && /* @__PURE__ */ jsx5("h1", { className: slotClass3("fillo-title", appearance, { slot: "title" }), "data-fillo": "title", children: schema.title }),
           schema.description && /* @__PURE__ */ jsx5(
             "p",
             {
@@ -2029,9 +2379,9 @@ function ResolvedForm(props) {
             "aria-hidden": "true",
             defaultValue: "",
             style: HP_STYLE,
-            ref: assertHpHidden,
-            onChange: (e) => {
-              hpRef.current = e.target.value;
+            ref: (element) => {
+              hpRef.current = element;
+              assertHpHidden(element);
             }
           }
         ),
@@ -2065,7 +2415,7 @@ function ResolvedForm(props) {
 }
 
 // src/jsx.tsx
-import { useRef as useRef6 } from "react";
+import { useRef as useRef7 } from "react";
 import {
   codeFormFromJsx,
   FilloJsxError,
@@ -2078,7 +2428,7 @@ function JsxForm(props) {
   const { id, title, description, settings, theme, client, children, ...rest } = props;
   const compiled = codeFormFromJsx({ id, title, description, settings, theme }, children);
   const json = JSON.stringify(compiled.schema) + JSON.stringify(compiled.theme ?? null);
-  const memo2 = useRef6(null);
+  const memo2 = useRef7(null);
   if (memo2.current && memo2.current.json !== json && isDevEnv2()) {
     console.warn(
       `[fillo] "${id}": form structure changed between renders. If you just edited the form, ignore this. Otherwise: conditional questions are visibleIf={when(\u2026)\u2026}, never {cond && <Fillo.\u2026/>} \u2014 a per-visitor schema churns drafts in your workspace.`
@@ -2132,29 +2482,121 @@ var Fillo = {
 
 // src/provider.tsx
 import { useId as useId3, useMemo as useMemo6 } from "react";
-import { FilloError as FilloError3, normalizeFormSchema as normalizeFormSchema2, resolveStrings as resolveStrings2 } from "@usefillo/core";
-import { jsx as jsx7 } from "react/jsx-runtime";
-function FilloProvider({ children, form, formId, client, appearance, strings, ...options }) {
+import {
+  FilloError as FilloError3,
+  formSchemasEqual as formSchemasEqual2,
+  isFilloError as isFilloError3,
+  normalizeFormSchema as normalizeFormSchema2,
+  resolveStrings as resolveStrings2,
+  syncCodeForm as syncCodeForm3
+} from "@usefillo/core";
+import { Fragment as Fragment3, jsx as jsx7 } from "react/jsx-runtime";
+function FilloProvider({
+  children,
+  form,
+  formId,
+  client,
+  appearance,
+  strings,
+  onError,
+  renderError,
+  ...options
+}) {
   const instanceId = useId3().replace(/:/g, "");
   const codeForm = isCodeForm2(form) ? form : null;
-  const rawSchema = codeForm ? codeForm.schema : form;
-  const schemaKey = useMemo6(() => JSON.stringify(rawSchema), [rawSchema]);
-  const normalized = useMemo6(() => normalizeFormSchema2(rawSchema), [rawSchema, schemaKey]);
+  const {
+    formId: syncedFormId,
+    status: syncedStatus,
+    error: syncError,
+    syncing: codeFormSyncing,
+    resolvedSchema
+  } = useCodeFormSync(form, client, onError, {
+    allowUnsynced: Boolean(!client || formId || options.skipValidation)
+  });
+  const rawSchema = codeForm ? resolvedSchema && !isDevEnv3() ? resolvedSchema : codeForm.schema : form;
+  const normalized = useMemo6(() => normalizeFormSchema2(rawSchema), [rawSchema]);
   if (!normalized.ok) {
     throw new FilloError3(`This form could not be rendered: ${normalized.error}`, 422);
   }
   const schema = normalized.schema;
-  const { formId: syncedFormId } = useCodeFormSync(form, client);
+  const resolveFormId = useMemo6(
+    () => codeForm && client?.key ? async () => {
+      try {
+        const result = await syncCodeForm3(client, codeForm, { bypassCache: true });
+        if (result.status === "draft") {
+          throw new FilloError3(
+            "This form is no longer published. Submission was stopped before sending answers.",
+            403,
+            void 0,
+            "form_not_published"
+          );
+        }
+        const authoritative = normalizeFormSchema2(result.resolvedSchema ?? codeForm.schema);
+        if (!authoritative.ok) {
+          throw new FilloError3(
+            `The canonical form schema was invalid: ${authoritative.error}`,
+            502,
+            void 0,
+            "invalid_sync_schema"
+          );
+        }
+        if (!formSchemasEqual2(schema, authoritative.schema)) {
+          throw new FilloError3(
+            "The live form changed after this page loaded. Submission stopped before incompatible answers were sent. Reload to use the published schema.",
+            409,
+            void 0,
+            "form_schema_changed"
+          );
+        }
+        if (result.syncError) {
+          const notice = new FilloError3(
+            result.syncError.message,
+            403,
+            void 0,
+            result.syncError.code
+          );
+          console.warn(
+            `[fillo] form sync needs attention (${notice.code}): ${notice.message}`
+          );
+          onError?.(notice);
+        }
+        return result.formId;
+      } catch (error) {
+        const failure = isFilloError3(error) ? error : new FilloError3(error instanceof Error ? error.message : String(error), 0);
+        console.warn(
+          `[fillo] form sync failed${failure.code ? ` (${failure.code})` : ""}: ${failure.message}`
+        );
+        onError?.(failure);
+        throw failure;
+      }
+    } : void 0,
+    [client, codeForm, onError, schema]
+  );
   const api = useFilloController({
     ...options,
     client,
     form: schema,
     formId: syncedFormId ?? formId,
+    resolveFormId,
     // Headless = your markup, no Fillo-rendered layout. Free like every embed
     // method; recorded per response so usage stays measurable.
     surface: "headless"
   });
-  return /* @__PURE__ */ jsx7(FilloContext.Provider, { value: api, children: /* @__PURE__ */ jsx7(FilloStringsContext.Provider, { value: resolveStrings2(strings), children: /* @__PURE__ */ jsx7(FilloAppearanceContext.Provider, { value: appearance, children: /* @__PURE__ */ jsx7(FilloInstanceIdContext.Provider, { value: instanceId, children }) }) }) });
+  useDraftFlush(api);
+  const resolvedStrings = resolveStrings2(strings);
+  const canonicalSyncError = syncError && !options.skipValidation ? syncError : null;
+  if (canonicalSyncError && renderError) return /* @__PURE__ */ jsx7(Fragment3, { children: renderError(canonicalSyncError) });
+  if (canonicalSyncError && !isDevEnv3()) return null;
+  if (codeFormSyncing && !options.skipValidation && !isDevEnv3()) return null;
+  const notPublished = Boolean(codeForm) && syncedStatus === "draft" && !options.skipValidation;
+  if (notPublished && !isDevEnv3()) {
+    const error = new FilloError3("This form isn't published yet.", 403, void 0, "form_not_published");
+    return renderError ? /* @__PURE__ */ jsx7(Fragment3, { children: renderError(error) }) : null;
+  }
+  return /* @__PURE__ */ jsx7(FilloContext.Provider, { value: api, children: /* @__PURE__ */ jsx7(FilloStringsContext.Provider, { value: resolvedStrings, children: /* @__PURE__ */ jsx7(FilloAppearanceContext.Provider, { value: appearance, children: /* @__PURE__ */ jsx7(FilloInstanceIdContext.Provider, { value: instanceId, children }) }) }) });
+}
+function isDevEnv3() {
+  return typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
 }
 
 // src/index.ts