@usefillo/core 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -8,6 +8,18 @@ interface Condition {
     op: ConditionOp;
     value?: string | number | boolean;
 }
+/**
+ * A single conditional page-flow rule (P1 logic depth). When every condition in
+ * `when` matches (AND — the same evaluator as `visibleIf`), navigation leaves
+ * the current page for `to`: another page's id, or the literal `"end"` to finish
+ * the form early. An empty `when` is an unconditional jump. Rules are evaluated
+ * top-to-bottom; the first match wins. See {@link FormPage.next}.
+ */
+interface JumpRule {
+    when: Condition[];
+    /** Target page id, or "end" to finish the form. */
+    to: string | "end";
+}
 type FieldKind = "short_text" | "long_text" | "email" | "url" | "phone" | "number" | "select" | "multi_select" | "dropdown" | "checkbox" | "rating" | "linear_scale" | "ranking" | "matrix" | "signature" | "date" | "file_upload" | "hidden" | "custom";
 type ContentKind = "heading" | "paragraph" | "divider";
 type BlockKind = FieldKind | ContentKind;
@@ -67,6 +79,8 @@ interface RatingField extends BaseField {
     kind: "rating";
     /** Number of steps, default 5. */
     max?: number;
+    /** Optional analysis meaning. CSAT requires a 1–5 rating. */
+    insightsMetric?: "csat";
 }
 interface DateField extends BaseField {
     kind: "date";
@@ -79,6 +93,8 @@ interface LinearScaleField extends BaseField {
     max?: number;
     minLabel?: string;
     maxLabel?: string;
+    /** Optional analysis meaning. NPS requires 0–10; CSAT requires 1–5. */
+    insightsMetric?: "csat" | "nps";
 }
 interface RankingField extends BaseField {
     kind: "ranking";
@@ -147,6 +163,10 @@ interface FormPage {
     id: string;
     title?: string;
     blocks: Block[];
+    /** Conditional page flow (P1 logic depth). Rules are evaluated top-to-bottom;
+     *  the first whose conditions all match decides the next step. No rule matches
+     *  → default linear next page. Absent → today's linear behavior. */
+    next?: JumpRule[];
 }
 /**
  * Limit repeat responses. Absent = no limit (submit as often as you like).
@@ -181,6 +201,22 @@ interface ResponseLimit {
      */
     onRepeat: "keep" | "update";
 }
+/**
+ * Per-form submission-trust policy. Absent = accept everything (today's
+ * behavior). See docs/roadmap/07-submission-trust.md.
+ */
+interface TrustPolicy {
+    /** What to do with a submission whose respondent is NOT HMAC-verified.
+     *  "allow" (default) accepts it normally; "quarantine" stores it withheld
+     *  from every downstream consumer until an owner releases it. Declared-agent
+     *  classes come in a later phase. */
+    unverified?: "allow" | "quarantine";
+    /** Require a human-verification challenge before accepting a submission.
+     *  "off" (default) = no challenge; "turnstile" = a Cloudflare Turnstile widget
+     *  that the SDK renders and the server verifies. Provider-agnostic on purpose.
+     *  Independent of `unverified` — a form can require both. */
+    challenge?: "off" | "turnstile";
+}
 interface FormSettings {
     /**
      * Default "button": respondents submit with the footer button. "auto" hides
@@ -196,6 +232,9 @@ interface FormSettings {
     /** Limit repeat responses (who counts as the same responder, and what a
      *  repeat does). Absent = no limit. See {@link ResponseLimit}. */
     responseLimit?: ResponseLimit;
+    /** Per-form submission-trust policy. Absent = accept everything (today's
+     *  behavior). See docs/roadmap/07-submission-trust.md. */
+    trust?: TrustPolicy;
     /** Notify this address on every submission. */
     notifyEmail?: string;
     /** Send respondents a receipt (to the first answered email field). */
@@ -291,6 +330,10 @@ type UploadStatus = "pending" | "uploading" | "complete" | "aborted";
  * - "gdrive": direct to a Google Drive resumable session URL (Content-Range
  *   protocol).
  * - "s3-put": a single PUT to a presigned S3/R2 URL — straight to the bucket.
+ *   Retained for sessions created by older Fillo servers.
+ * - "s3-multipart": resumable S3/R2 multipart upload. The client asks Fillo
+ *   for one short-lived UploadPart URL at a time; only the server can assemble
+ *   the parts into an object.
  * - "box": direct to Box with a folder-scoped upload token — small files via a
  *   single multipart POST, large files via Box's chunked session (the client
  *   computes the SHA-1 digests Box requires). The server commits/verifies in the
@@ -302,6 +345,8 @@ type UploadTransport = {
 } | {
     type: "s3-put";
     uploadUrl: string;
+} | {
+    type: "s3-multipart";
 } | {
     type: "box";
     mode: "simple";
@@ -341,9 +386,29 @@ interface UploadSession {
     file?: FileValue;
 }
 
+/**
+ * All conditions must hold (AND); no conditions = true. THE shared evaluator —
+ * both block visibility (`visibleIf`) and page jumps (`JumpRule.when`) run
+ * through this over the SAME whole-form fixpoint resolver, so a jump gated by a
+ * logic-hidden controller field behaves identically to a visibility rule.
+ */
+declare function conditionsMet(conds: Condition[], resolve: (fieldId: string) => FieldValue): boolean;
 /** All conditions must hold (AND). No conditions = visible. */
 declare function isBlockVisible(block: Block, data: ResponseData): boolean;
 declare function visibleBlocks(page: FormPage, data: ResponseData): Block[];
+/**
+ * Blocks to render on `page`, resolved against the WHOLE-FORM visibility
+ * fixpoint rather than just this page's own fields. A field whose `visibleIf`
+ * references an answer on another page must appear/validate here exactly when
+ * the server would keep that answer — and the server (validateResponse →
+ * visibleFields) uses the whole-form fixpoint, hiding any controlling field
+ * that is itself logic-hidden. Scoping per page instead reads a stale answer
+ * behind a hidden cross-page trigger as still-answered, so the client would
+ * render (and validate) a field whose answer the server then silently drops.
+ * Use this for anything that must agree with validateResponse; the per-page
+ * `visibleBlocks` remains for callers holding only a single page.
+ */
+declare function visiblePageBlocks(form: FormSchema, page: FormPage, data: ResponseData): Block[];
 /** Every field in the form (across pages), in order. */
 declare function allFields(form: FormSchema): Field[];
 /**
@@ -355,8 +420,57 @@ declare function allFields(form: FormSchema): Field[];
  * per-visitor key and the server's per-person dedup so both scope identically.
  */
 declare function responseScopeValue(settings: FormSettings, data: ResponseData): string | null;
-/** Fields currently visible given the response data — the set that gets validated. */
+/** Fields currently visible given the response data. */
 declare function visibleFields(form: FormSchema, data: ResponseData): Field[];
+/** Where navigation goes when leaving a page. */
+type NextPage = {
+    to: string;
+} | {
+    end: true;
+} | {
+    linear: true;
+};
+/**
+ * Evaluate a page's `next` jump rules top-to-bottom against the current data;
+ * the first whose conditions all match decides the step ("end" → finish the
+ * form). No rule (or no `next`) → the default linear next page. THE single
+ * function the client renderer, the server validator, and the funnel share so
+ * they always agree on flow.
+ */
+declare function resolveNextPage(form: FormSchema, currentPageId: string, data: ResponseData): NextPage;
+/**
+ * The ORDERED list of reachable page ids for the given data: walk from
+ * `pages[0]` following `resolveNextPage` (linear → next index; jump → target id;
+ * end → stop). A rule that points backward could loop, so stop on the first
+ * revisit and cap the walk at `pages.length` steps. THE single ordered engine
+ * the client renderer, the server validator, and navigation all agree through —
+ * a no-jump form yields `[pages[0].id, …, pages[N].id]`, so everything built on
+ * it reduces to today's linear behavior. {@link reachablePageIds} is the set of
+ * this exact walk (one walk, no divergence).
+ */
+declare function reachablePageSequence(form: FormSchema, data: ResponseData): string[];
+/**
+ * The page ids reachable for the given data. The unordered set of
+ * {@link reachablePageSequence} — one shared walk keeps the ordered navigation
+ * and the reachability the validator uses provably in agreement. THE function
+ * the client renderer and server validator both use to decide which pages/fields
+ * are in play.
+ */
+declare function reachablePageIds(form: FormSchema, data: ResponseData): Set<string>;
+/**
+ * Whether `pageId` is terminal for the given data — pressing the footer button
+ * there submits rather than advancing. True when a matched jump rule resolves to
+ * "end", or when the page is the LAST element of the reachable sequence (the
+ * last reachable page, including a cycle broken at its revisit, so a backward
+ * jump can never loop — the pre-revisit page becomes terminal and Submit
+ * appears). For a no-jump form this is exactly "the last page".
+ */
+declare function isTerminalPage(form: FormSchema, pageId: string, data: ResponseData): boolean;
+/** Reachable field ids: fields on reachable pages, intersected with visibility. */
+declare function reachableFieldIds(form: FormSchema, data: ResponseData): Set<string>;
+/** Fields that are both reachable AND visible — the set that gets validated and
+ *  kept on submit. Equals {@link visibleFields} for a form with no jumps. */
+declare function reachableFields(form: FormSchema, data: ResponseData): Field[];
 
 /** Validate a single answered value for a field. Returns an error message or null. */
 declare function validateField(field: Field, value: FieldValue): string | null;
@@ -364,18 +478,42 @@ interface ValidationResult {
     ok: boolean;
     /** fieldId -> message for every failing field. */
     errors: Record<string, string>;
-    /** Data trimmed to the fields that are visible (hidden answers are dropped). */
+    /** Data trimmed to the fields that are reachable + visible (answers to fields
+     *  hidden by logic OR on pages skipped by a jump/early-end are dropped). */
     data: ResponseData;
 }
 /**
- * Validate a full submission against the schema. Only currently-visible fields
- * are validated and kept — answers to fields hidden by logic are discarded.
+ * Validate a full submission against the schema. Only reachable + currently-
+ * visible fields are validated and kept — answers to fields hidden by logic, or
+ * on pages a page-jump/early-end skipped, are discarded. A legitimately
+ * early-ended submission therefore does NOT 422 on a skipped page's required
+ * field. Reachability is computed by the SAME shared engine the client renderer
+ * navigates with, so render and validate always agree. A form with no jumps has
+ * every page reachable, so this validates exactly as before.
  */
 declare function validateResponse(form: FormSchema, data: ResponseData): ValidationResult;
 
 declare const FILLO_SCHEMA_VERSION: 1;
 /** Injected from package.json at build time (tsup define) — never hand-edited. */
 declare const FILLO_SDK_VERSION: string;
+/**
+ * The oldest published @usefillo/* SDK that can still render a form the current
+ * server serves. This is a DELIBERATE floor — bump it BY HAND only when a
+ * genuinely wire-breaking change ships (a new required request/response field an
+ * old SDK can't produce or read). It must never be tied to FILLO_SDK_VERSION:
+ * the server used to serve its own build version as the min, so every release
+ * 426'd every customer still on an older pinned SDK. Field-kind/schema-shape
+ * breaks are gated separately by FILLO_SCHEMA_VERSION, so this floor stays low.
+ */
+declare const FILLO_MIN_SDK_VERSION = "0.4.0";
+/**
+ * The floor served INSTEAD of FILLO_MIN_SDK_VERSION for challenge-enabled
+ * forms: the first release that ships the Turnstile widget. An older SDK passes
+ * the base floor but renders no widget, so the server would reject its every
+ * submit — the raised floor makes it fail fast with the clear "update
+ * @usefillo/*" error instead of a form that silently can't submit.
+ */
+declare const FILLO_CHALLENGE_MIN_SDK_VERSION = "0.9.0";
 declare function normalizeSettings(value: unknown): FormSettings;
 interface SchemaValidationResult {
     ok: boolean;
@@ -457,6 +595,18 @@ declare function parsePhone(value: string, fallback?: PhoneCountry): ParsedPhone
  * validation. `country` (when known) tightens the accepted lengths.
  */
 declare function isPossiblePhone(value: string): boolean;
+/** Whether the country-picker popover opens below or above its trigger. */
+type PhonePopoverPlacement = "below" | "above";
+/** Minimum gap kept between the popover and the viewport edge, in px. */
+declare const PHONE_POPOVER_VIEWPORT_GAP = 8;
+/**
+ * Decide whether the country-picker popover should open below or above its
+ * anchor and size it to fit the viewport, writing the result to CSS custom
+ * properties on the popover. Pure DOM math with no framework assumptions, so
+ * the React and vanilla renderers share one implementation instead of drifting
+ * copies. Returns "below" when there is nothing to position (SSR / detached).
+ */
+declare function positionPhonePopover(anchor: HTMLElement | null, popover: HTMLElement | null): PhonePopoverPlacement;
 
 /** Display metadata for every block kind — drives the builder palette. */
 declare const BLOCK_KIND_META: Record<BlockKind, {
@@ -491,6 +641,7 @@ interface FieldSpec {
     max?: number;
     minLabel?: string;
     maxLabel?: string;
+    insightsMetric?: "csat" | "nps";
     rows?: string[];
     columns?: string[];
     placeholder?: string;
@@ -532,6 +683,18 @@ interface FilloClientOptions {
     baseUrl?: string;
     fetch?: typeof fetch;
 }
+/**
+ * Public human-verification challenge config the SDK needs to render a widget.
+ * Delivered as a TOP-LEVEL field on the form GET (never inside the schema): the
+ * schema's trust policy is server-only and stripped, but the widget needs the
+ * PUBLIC site key. Injected server-side from Fillo's env — the SECRET key never
+ * leaves the server. Absent = no challenge (render nothing, load no script).
+ */
+interface ChallengeConfig {
+    provider: "turnstile";
+    /** Cloudflare Turnstile PUBLIC site key. Safe to ship to the browser. */
+    siteKey: string;
+}
 interface PublishedForm {
     id: string;
     slug: string;
@@ -547,6 +710,9 @@ interface PublishedForm {
     closed?: boolean;
     /** Workspace branding state — absent means show the badge (default). */
     branding?: FormBranding;
+    /** Human-verification challenge to render before submit, when the form
+     *  requires one. Absent = no challenge. Carries only the PUBLIC site key. */
+    challenge?: ChallengeConfig;
 }
 type SubmitResult = {
     ok: true;
@@ -592,6 +758,13 @@ interface SubmitMeta {
      * stable user/account id.
      */
     respondent?: FilloRespondent;
+    /**
+     * Human-verification challenge token (e.g. from the Cloudflare Turnstile
+     * widget). Present only when the form requires a challenge; the server
+     * verifies it and rejects the submit if it is missing or invalid. Never a
+     * secret — it is a single-use, server-verifiable proof of the widget solve.
+     */
+    challengeToken?: string;
 }
 /**
  * The host app's account context for the person filling the form. Passed as
@@ -656,14 +829,23 @@ interface UploadFileOptions {
     sessionId?: string;
     /** Ownership token for the resumed session (from the original create call). */
     uploadToken?: string;
+    /** Persist this handle if the host wants reload-safe resumability. */
+    onSession?: (handle: {
+        sessionId: string;
+        uploadToken?: string;
+    }) => void;
 }
 declare class FilloError extends Error {
     status?: number | undefined;
     /** Server-suggested wait (from a 429's Retry-After header), seconds. */
     retryAfterSec?: number | undefined;
+    /** Stable machine-readable API error code, when the server provides one. */
+    code?: string | undefined;
     constructor(message: string, status?: number | undefined, 
     /** Server-suggested wait (from a 429's Retry-After header), seconds. */
-    retryAfterSec?: number | undefined);
+    retryAfterSec?: number | undefined, 
+    /** Stable machine-readable API error code, when the server provides one. */
+    code?: string | undefined);
 }
 /** Duck-typed — `instanceof` breaks when two SDK copies end up in one bundle. */
 declare function isFilloError(err: unknown): err is FilloError;
@@ -671,10 +853,25 @@ interface SyncFormResult {
     formId: string;
     slug: string;
     branding?: FormBranding;
+    /** Human-verification challenge to render before submit, when the LIVE form
+     *  requires one (staged changes don't gate until published). Absent = no
+     *  challenge. Carries only the PUBLIC site key. */
+    challenge?: ChallengeConfig;
     /** Lifecycle on newer servers: a draft can't accept public responses yet. */
     status?: "draft" | "published";
     /** Changes were staged as a draft for a human to publish. */
     staged?: boolean;
+    /**
+     * Server-authoritative live snapshot. Present when the incoming code schema
+     * is not the version respondents may submit against yet.
+     */
+    resolvedSchema?: FormSchema;
+    resolvedTheme?: FormTheme | null;
+    /** Non-fatal integration problem; the resolved live snapshot remains usable. */
+    syncError?: {
+        code: string;
+        message: string;
+    };
     warning?: string;
 }
 declare class FilloClient {
@@ -689,8 +886,10 @@ declare class FilloClient {
     /** Fetch a published form definition by id or slug. */
     getForm(idOrSlug: string): Promise<PublishedForm>;
     /**
-     * Upsert a code-defined form into the workspace identified by the client's
-     * publishable key. Returns the canonical form id used for submissions.
+     * Resolve a code-defined form through the workspace identified by the
+     * client's publishable key. Depending on workspace policy, changed content
+     * may be staged for review or resolved to the authoritative live snapshot.
+     * Returns the canonical form id used for submissions.
      */
     syncForm(handle: string, schema: FormSchema, theme?: FormTheme | null): Promise<SyncFormResult>;
     /** Submit a response. Returns per-field errors instead of throwing on validation failure. */
@@ -700,8 +899,14 @@ declare class FilloClient {
      * used to prefill their answers for editing. Requires a VERIFIED identity
      * ({id, hash}); anything else 404s (returned as null), because an
      * unverified read would hand anyone's answers to any page script.
+     *
+     * `scopeValue` scopes the lookup for forms whose response limit is keyed to
+     * a field (responseLimit.scopeField) — e.g. one response per article. When
+     * the form is scoped, the server returns 404 unless the matching scope value
+     * is sent, so a page loaded for article B never prefills article A's answers.
+     * Optional and back-compatible: omit it for unscoped forms.
      */
-    fetchOwnResponse(formId: string, respondent: FilloRespondent): Promise<{
+    fetchOwnResponse(formId: string, respondent: FilloRespondent, scopeValue?: string): Promise<{
         responseId: string;
         data: ResponseData;
     } | null>;
@@ -743,13 +948,12 @@ declare class FilloClient {
     /** Discard a draft (the "Start over" path). */
     deleteDraft(draftId: string, token: string): Promise<void>;
     /** Current state of an upload session — used to resume after interruption. */
-    getUploadSession(sessionId: string, token?: string): Promise<UploadSession>;
+    getUploadSession(sessionId: string, token?: string, signal?: AbortSignal): Promise<UploadSession>;
     /**
-     * Resumable chunked upload. Creates (or resumes) a session, streams the file
-     * chunk by chunk with progress callbacks, and finalizes into a FileValue that
-     * goes into the response data. Survives flaky connections: each chunk is
-     * retried, and on repeated failure the true offset is re-queried so no byte
-     * is sent twice or skipped.
+     * Provider-aware browser-direct upload. Creates a session, uses the storage
+     * transport selected by the server, reports progress, and finalizes into a
+     * FileValue. Resumable providers can continue an existing session; one-shot
+     * transports are retried according to their own safe semantics.
      *
      * Depending on the form's storage settings the server picks a transport:
      * direct-to-Google-Drive resumable
@@ -768,7 +972,7 @@ declare class FilloClient {
     /**
      * Caller signal (if any) combined with a fresh per-request timeout. Created per
      * fetch so each retry attempt gets its own deadline; the caller's own abort
-     * still drives the resumable-upload cancel semantics.
+     * still drives upload cancellation across every provider transport.
      */
     private uploadSignal;
     /** Retry a request with exponential backoff; never retries an aborted upload. */
@@ -780,6 +984,13 @@ declare class FilloClient {
      * queries Drive for the authoritative offset).
      */
     private driveUploadLoop;
+    /**
+     * S3-compatible multipart protocol. Fillo owns the provider upload id and is
+     * the only party allowed to complete it; the browser receives only narrowly
+     * scoped UploadPart URLs. That keeps uploads resumable and means an old or
+     * slow browser request cannot materialize an object after server-side abort.
+     */
+    private s3MultipartUploadLoop;
     /**
      * 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.
@@ -791,13 +1002,13 @@ interface ProvisionWorkspaceResult {
     /** Publishable key (pk_…) for the new workspace. Pass to createClient({ key }). */
     key: string;
     organizationId: string;
-    /** A claim link was emailed here so the owner can take ownership later. */
+    /** The private workspace link is emailed directly; `url` stays null. */
     claim: {
         url: string | null;
         email: string | null;
         sent: boolean;
     };
-    /** Caps applied until the workspace is claimed. */
+    /** Caps applied until the workspace is saved to an account. */
     limits: {
         responses: number;
         expiresAt: string;
@@ -805,9 +1016,9 @@ interface ProvisionWorkspaceResult {
 }
 /**
  * Provision a Fillo workspace from an email — no signup — and get a publishable
- * key back, so a form can collect real responses immediately. A claim link is
- * emailed to `email`; until someone claims it the workspace runs as a capped
- * preview (limited responses, for a limited time). Built for setup automation,
+ * key back, so a form can collect real responses immediately. A private
+ * workspace link is emailed to `email`; until someone saves it to an account,
+ * the workspace runs as a capped preview (limited responses, for a limited time). Built for setup automation,
  * e.g. a coding agent wiring Fillo into an app during integration.
  *
  *   const { key } = await provisionWorkspace({ email: "you@co.com" });
@@ -853,10 +1064,10 @@ interface FormControllerOptions {
      */
     surface?: "default" | "headless";
     /**
-     * Resolve the submission target at submit time when `formId` is still
-     * unset — e.g. re-run a code-form sync that failed at mount. Answers are
-     * held (never dropped) while it runs; failure sets `submitError` and the
-     * respondent can retry.
+     * Resolve/verify the submission target immediately before submit. Code-form
+     * renderers use this to recover a missing target and to detect a live schema
+     * change after a cached mount. Answers are held (never dropped) while it
+     * runs; failure sets `submitError` and the respondent can retry.
      */
     resolveFormId?: () => Promise<string>;
     /**
@@ -866,6 +1077,24 @@ interface FormControllerOptions {
      * the respondent can do.
      */
     respondent?: FilloRespondent;
+    /**
+     * True when the form requires a human-verification challenge (Turnstile).
+     * When set, submit refuses to send until a token is available and always
+     * attaches the token from {@link getChallengeToken}. The server is the real
+     * gate — this only avoids firing a submit the server would reject.
+     */
+    challengeRequired?: boolean;
+    /**
+     * Read the current challenge token (from the rendered widget) at submit time.
+     * Returns undefined until the challenge is solved. Read lazily so an expired
+     * token that was refreshed just before submit is picked up fresh.
+     */
+    getChallengeToken?: () => string | undefined;
+    /**
+     * The server rejected the submission's challenge (stale/replayed/invalid
+     * token). The renderer resets the widget so the human can solve a fresh one.
+     */
+    onChallengeFailed?: () => void;
 }
 interface FormControllerState {
     data: ResponseData;
@@ -904,6 +1133,27 @@ interface FormControllerState {
      * show an "updating your earlier response" notice.
      */
     editingPrevious: boolean;
+    /**
+     * True when the last submit was accepted as an already-recorded response
+     * rather than a new one (the server returns this only for a VERIFIED
+     * identify() repeat on a keep-mode form). Renderers show an "already
+     * answered" message on the success screen instead of implying a fresh
+     * submission — otherwise a repeat visitor's new answers look saved when the
+     * server kept the original.
+     */
+    duplicateSubmission: boolean;
+    /**
+     * True when the last submit UPDATED the person's existing response in place
+     * (responseLimit onRepeat "update"), rather than creating a new one.
+     */
+    updatedSubmission: boolean;
+    /**
+     * True when a resume link (#fillo-draft=…) could not be adopted because it
+     * was expired, already used, or not this browser's — so no progress was
+     * restored. Renderers surface a "that link expired — start again" notice
+     * instead of showing a silently blank form.
+     */
+    resumeLinkFailed: boolean;
 }
 interface FormController {
     /** Stable snapshot — same reference until something changes (safe for useSyncExternalStore). */
@@ -963,6 +1213,8 @@ interface AutoSubmitContext {
     form: FormSchema;
     data: ResponseData;
     status: FormStatus;
+    /** Terminal-aware last-page flag from the controller. Advisory here —
+     *  shouldAutoSubmit re-derives terminal from the RESULTING data (see below). */
     isLastPage: boolean;
     uploading: boolean;
 }
@@ -974,7 +1226,7 @@ declare function shouldAutoSubmit(field: Field, value: FieldValue, ctx: AutoSubm
  * (Tailwind `data-[invalid]:…`) can react to it. Slot names and attribute
  * names are public API — renames are breaking; additions are minors.
  */
-declare const FILLO_SLOTS: readonly ["root", "header", "title", "description", "pageTitle", "progress", "progressFill", "blocks", "field", "label", "fieldDescription", "control", "options", "option", "optionLabel", "error", "footer", "button", "success", "resume"];
+declare const FILLO_SLOTS: readonly ["root", "header", "title", "description", "pageTitle", "progress", "progressFill", "blocks", "field", "label", "fieldDescription", "control", "options", "option", "optionLabel", "error", "footer", "button", "success", "resume", "turnstile"];
 type FilloSlot = (typeof FILLO_SLOTS)[number];
 /** data-* names emitted alongside the stable fillo-* classes. */
 declare const FILLO_DATA_ATTRS: {
@@ -1061,10 +1313,23 @@ declare const FILLO_THEME_VARS: readonly [{
 }];
 
 /**
- * Every visitor-facing string the default renderers emit, overridable as a
- * unit so a localized site never shows stray English at the submit moment.
+ * The default English validation message for a required field left empty.
+ * `validateField` returns this exact sentinel (core has no strings context),
+ * and the React render layer swaps it for `strings.required` so a localized
+ * site can translate it. Keep it identical to `DEFAULT_FIELD_STRINGS.required`.
+ */
+declare const REQUIRED_FIELD_MESSAGE = "This field is required";
+/**
+ * The form-chrome strings the default renderers emit, overridable as a unit so
+ * a localized site never shows stray English at the submit moment.
  * Schema-authored text (labels, descriptions, success copy set in settings)
  * always wins over these defaults.
+ *
+ * Field-level and validation copy (required message, upload field, duplicate/
+ * resume notices) lives in {@link FilloFieldStrings} — split out so this
+ * documented, all-`string` surface stays stable while parametrized field
+ * strings can be functions. The renderers resolve both together
+ * ({@link FilloRendererStrings}); the `strings` prop overrides either.
  */
 interface FilloStrings {
     back: string;
@@ -1097,25 +1362,78 @@ interface FilloStrings {
     editNotice: string;
     /** The discard action next to the resume notice. */
     resumeStartOver: string;
+    /** Shown when the human-verification widget can't load (script blocked). */
+    challengeUnavailable: string;
 }
 declare const DEFAULT_STRINGS: FilloStrings;
-declare function resolveStrings(overrides?: Partial<FilloStrings>): FilloStrings;
+/**
+ * Field-level and validation strings the default renderers emit. Kept apart
+ * from {@link FilloStrings} so parametrized entries can be functions (a
+ * translation places the value where its grammar needs it) without widening
+ * the documented all-`string` chrome surface.
+ */
+interface FilloFieldStrings {
+    /** Validation: a required field was left empty. Mirrors REQUIRED_FIELD_MESSAGE. */
+    required: string;
+    /** Notice when a spent/expired resume link couldn't restore progress. */
+    resumeLinkExpired: string;
+    /** Success-screen message when a verified identity re-submits and the form
+     *  keeps the first answer (a visible duplicate, not a fresh response). */
+    alreadyAnswered: string;
+    /** Retry control on a failed upload row. */
+    uploadRetry: string;
+    /** Dropzone copy when uploads can't run (no client / preview). */
+    uploadsDisabled: string;
+    /** An upload attempt failed with no actionable server message. */
+    uploadFailed: string;
+    /** Dropzone call to action; `multiple` is true when several files are allowed. */
+    dropzoneTitle: (multiple: boolean) => string;
+    /** Dropzone hint stating the per-file size limit in MB. */
+    dropzoneHint: (maxMb: number) => string;
+    /** A file exceeded the per-file MB limit before upload started. */
+    fileTooLarge: (maxMb: number) => string;
+    /** Screen-reader status: N uploads in progress. */
+    filesUploading: (count: number) => string;
+    /** Screen-reader status: N uploads failed. */
+    uploadsFailed: (count: number) => string;
+    /** Screen-reader status: N uploads completed. */
+    filesUploaded: (count: number) => string;
+}
+declare const DEFAULT_FIELD_STRINGS: FilloFieldStrings;
+/** Everything the default renderers can localize — chrome + field/validation. */
+type FilloRendererStrings = FilloStrings & FilloFieldStrings;
+/** Merge overrides over the built-in chrome + field defaults. Accepts a partial
+ *  of the full renderer surface so the `strings` prop can override either set. */
+declare function resolveStrings(overrides?: Partial<FilloRendererStrings>): FilloRendererStrings;
 
 /** Result of syncing a code-defined form: its canonical id, slug, and branding. */
 interface SyncedForm {
     formId: string;
     slug: string;
     branding?: FormBranding;
+    /** Human-verification challenge to render before submit, when the LIVE form
+     *  requires one (staged changes don't gate until published). Absent = no
+     *  challenge. Carries only the PUBLIC site key. */
+    challenge?: ChallengeConfig;
     /** Lifecycle on newer servers: a draft can't accept public responses yet. */
     status?: "draft" | "published";
     /** Changes were staged as a draft for a human to publish. */
     staged?: boolean;
+    /** Server-authoritative live snapshot when local code is not live yet. */
+    resolvedSchema?: FormSchema;
+    resolvedTheme?: FormTheme | null;
+    /** Non-fatal integration problem; resolvedSchema remains safe to render. */
+    syncError?: {
+        code: string;
+        message: string;
+    };
     warning?: string;
 }
 /**
- * A form whose structure lives in user code. Framework renderers can show it
- * immediately, then sync it into a Fillo workspace when a publishable key is
- * present so responses, uploads, webhooks, and exports work normally.
+ * A form whose structure lives in user code. Development and explicit
+ * render-only usage can show it immediately; production renderers with a
+ * publishable key first resolve the canonical form from Fillo so responses,
+ * uploads, webhooks, and exports stay bound to the published version.
  */
 interface CodeForm {
     /** Stable handle, unique in the workspace. */
@@ -1136,10 +1454,16 @@ declare function isCodeForm(form: unknown): form is CodeForm;
 /** Stable djb2 hash of a string — used to key code-form sync by content. */
 declare function contentHash(input: string): string;
 /**
- * Sync a code-defined form into a workspace at most once per session for the
- * same client, handle, schema, and theme. `bypassCache` forces the network —
- * used by submit-time resolution, where a stale cached formId must not be
- * trusted over a fresh sync.
+ * Compare normalized schema JSON while ignoring object-key order (Postgres
+ * jsonb and custom API proxies may reorder keys). Array order remains part of
+ * the form definition because it controls pages, blocks, and options.
+ */
+declare function formSchemasEqual(left: FormSchema, right: FormSchema): boolean;
+/**
+ * Resolve a code-defined form with in-flight dedupe and bounded stable-result
+ * caching (published 1h, draft 60s). Staged/live-fallback results are evicted
+ * once settled so an SPA can observe publication without a hard reload.
+ * `bypassCache` forces the network for submit-time compatibility checks.
  */
 declare function syncCodeForm(client: FilloClient, form: CodeForm, opts?: {
     bypassCache?: boolean;
@@ -1263,4 +1587,4 @@ declare class Sha1 {
 }
 declare const sha1Base64: (bytes: Uint8Array) => string;
 
-export { type AutoSubmitContext, 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 CreatedDraft, type CustomField, DEFAULT_STRINGS, DRAFT_KINDS, type DateField, type DividerBlock, FILLO_DATA_ATTRS, FILLO_SCHEMA_VERSION, FILLO_SDK_VERSION, FILLO_SLOTS, FILLO_THEME_VARS, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, type FilloAppearance, FilloClient, type FilloClientOptions, FilloError, FilloJsxError, type FilloRespondent, type FilloSlot, type FilloStrings, type FormBranding, type FormController, type FormControllerOptions, type FormControllerState, type FormDraftSpec, type FormPage, type FormSchema, type FormSettings, type FormStatus, type FormTheme, type HeadingBlock, type HiddenField, JSX_BLOCK_COMPONENTS, JSX_BLOCK_SPECS, type JsonValue, type JsxFormMeta, 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 ResponseDraft, type ResponseLimit, type SchemaValidationResult, type SelectOption, Sha1, type SignatureField, type SlotClass, type SlotState, type SubmitMeta, type SubmitResult, type SyncFormResult, type SyncedForm, type TextField, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, type WhenBuilder, allFields, assembleForm, codeFormFromJsx, contentHash, countryByDialCode, countryByIso, countryByTimeZone, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, flagEmoji, formatAnswer, formatNational, isAutoSubmitBlock, isBlockVisible, isCodeForm, isField, isFilloError, isPossiblePhone, needsExplicitSubmit, normalizeFormSchema, normalizeFormTheme, normalizeSettings, parsePhone, pipeBlock, prefillFromParams, provisionWorkspace, resolveSlotClass, resolveStrings, resolveText, responseScopeValue, schemaFromJsx, sha1Base64, shouldAutoSubmit, slotClass, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields, when };
+export { type AutoSubmitContext, BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type ChallengeConfig, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CreatedDraft, type CustomField, DEFAULT_FIELD_STRINGS, DEFAULT_STRINGS, DRAFT_KINDS, type DateField, type DividerBlock, FILLO_CHALLENGE_MIN_SDK_VERSION, FILLO_DATA_ATTRS, FILLO_MIN_SDK_VERSION, FILLO_SCHEMA_VERSION, FILLO_SDK_VERSION, FILLO_SLOTS, FILLO_THEME_VARS, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, type FilloAppearance, FilloClient, type FilloClientOptions, FilloError, type FilloFieldStrings, FilloJsxError, type FilloRendererStrings, type FilloRespondent, type FilloSlot, type FilloStrings, type FormBranding, type FormController, type FormControllerOptions, type FormControllerState, type FormDraftSpec, type FormPage, type FormSchema, type FormSettings, type FormStatus, type FormTheme, type HeadingBlock, type HiddenField, JSX_BLOCK_COMPONENTS, JSX_BLOCK_SPECS, type JsonValue, type JsxFormMeta, type JumpRule, type LinearScaleField, type MatrixField, type NextPage, type NumberField, PHONE_COUNTRIES, PHONE_POPOVER_VIEWPORT_GAP, type ParagraphBlock, type ParsedPhone, type PhoneCountry, type PhoneField, type PhonePopoverPlacement, type ProvisionWorkspaceResult, type PublishedForm, REQUIRED_FIELD_MESSAGE, type RankingField, type RatingField, type ResponseData, type ResponseDraft, type ResponseLimit, type SchemaValidationResult, type SelectOption, Sha1, type SignatureField, type SlotClass, type SlotState, type SubmitMeta, type SubmitResult, type SyncFormResult, type SyncedForm, type TextField, type TrustPolicy, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, type WhenBuilder, allFields, assembleForm, codeFormFromJsx, conditionsMet, contentHash, countryByDialCode, countryByIso, countryByTimeZone, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, flagEmoji, formSchemasEqual, formatAnswer, formatNational, isAutoSubmitBlock, isBlockVisible, isCodeForm, isField, isFilloError, isPossiblePhone, isTerminalPage, needsExplicitSubmit, normalizeFormSchema, normalizeFormTheme, normalizeSettings, parsePhone, pipeBlock, positionPhonePopover, prefillFromParams, provisionWorkspace, reachableFieldIds, reachableFields, reachablePageIds, reachablePageSequence, resolveNextPage, resolveSlotClass, resolveStrings, resolveText, responseScopeValue, schemaFromJsx, sha1Base64, shouldAutoSubmit, slotClass, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields, visiblePageBlocks, when };