@usefillo/core 0.8.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;
@@ -151,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).
@@ -185,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
@@ -200,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). */
@@ -351,6 +386,13 @@ 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[];
@@ -378,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;
@@ -387,12 +478,18 @@ 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;
 
@@ -409,6 +506,14 @@ declare const FILLO_SDK_VERSION: string;
  * 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;
@@ -578,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;
@@ -593,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;
@@ -638,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
@@ -726,6 +853,10 @@ 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. */
@@ -946,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;
@@ -1064,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;
 }
@@ -1075,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: {
@@ -1211,6 +1362,8 @@ 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;
 /**
@@ -1258,6 +1411,10 @@ 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. */
@@ -1430,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_FIELD_STRINGS, DEFAULT_STRINGS, DRAFT_KINDS, type DateField, type DividerBlock, 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 LinearScaleField, type MatrixField, 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 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, formSchemasEqual, formatAnswer, formatNational, isAutoSubmitBlock, isBlockVisible, isCodeForm, isField, isFilloError, isPossiblePhone, needsExplicitSubmit, normalizeFormSchema, normalizeFormTheme, normalizeSettings, parsePhone, pipeBlock, positionPhonePopover, prefillFromParams, provisionWorkspace, resolveSlotClass, resolveStrings, resolveText, responseScopeValue, schemaFromJsx, sha1Base64, shouldAutoSubmit, slotClass, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields, visiblePageBlocks, 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 };

package/dist/index.js

@@ -54,9 +54,13 @@ function evalCondition(cond, resolve) {
     }
   }
 }
+function conditionsMet(conds, resolve) {
+  if (conds.length === 0) return true;
+  return conds.every((cond) => evalCondition(cond, resolve));
+}
 function blockVisibleWith(block, resolve) {
   if (!block.visibleIf || block.visibleIf.length === 0) return true;
-  return block.visibleIf.every((cond) => evalCondition(cond, resolve));
+  return conditionsMet(block.visibleIf, resolve);
 }
 function makeResolver(data, scoped, visible) {
   return (fieldId) => scoped.has(fieldId) && !visible.has(fieldId) ? void 0 : data[fieldId];
@@ -108,6 +112,70 @@ function visibleFields(form, data) {
   const visible = visibleFieldIds(fields, data);
   return fields.filter((f) => visible.has(f.id));
 }
+function formResolver(form, data) {
+  const fields = allFields(form);
+  const scoped = new Set(fields.map((f) => f.id));
+  return makeResolver(data, scoped, visibleFieldIds(fields, data));
+}
+function resolveNextPage(form, currentPageId, data) {
+  const page = form.pages.find((p) => p.id === currentPageId);
+  const rules = page?.next;
+  if (!rules || rules.length === 0) return { linear: true };
+  const resolve = formResolver(form, data);
+  for (const rule of rules) {
+    if (conditionsMet(rule.when, resolve)) {
+      return rule.to === "end" ? { end: true } : { to: rule.to };
+    }
+  }
+  return { linear: true };
+}
+function reachablePageSequence(form, data) {
+  const seq = [];
+  if (form.pages.length === 0) return seq;
+  const seen = /* @__PURE__ */ new Set();
+  let index = 0;
+  for (let steps = 0; steps <= form.pages.length; steps++) {
+    const page = form.pages[index];
+    if (!page || seen.has(page.id)) break;
+    seen.add(page.id);
+    seq.push(page.id);
+    const nav = resolveNextPage(form, page.id, data);
+    if ("end" in nav) break;
+    if ("to" in nav) {
+      const target = form.pages.findIndex((p) => p.id === nav.to);
+      if (target < 0) break;
+      index = target;
+    } else {
+      index += 1;
+      if (index >= form.pages.length) break;
+    }
+  }
+  return seq;
+}
+function reachablePageIds(form, data) {
+  return new Set(reachablePageSequence(form, data));
+}
+function isTerminalPage(form, pageId, data) {
+  if ("end" in resolveNextPage(form, pageId, data)) return true;
+  const seq = reachablePageSequence(form, data);
+  return seq.length > 0 && seq[seq.length - 1] === pageId;
+}
+function reachableFieldIds(form, data) {
+  const reachablePages = reachablePageIds(form, data);
+  const visible = visibleFieldIds(allFields(form), data);
+  const ids = /* @__PURE__ */ new Set();
+  for (const page of form.pages) {
+    if (!reachablePages.has(page.id)) continue;
+    for (const block of page.blocks) {
+      if (isField(block) && visible.has(block.id)) ids.add(block.id);
+    }
+  }
+  return ids;
+}
+function reachableFields(form, data) {
+  const ids = reachableFieldIds(form, data);
+  return allFields(form).filter((f) => ids.has(f.id));
+}
 
 // src/validation.ts
 import * as z from "zod/mini";
@@ -440,7 +508,8 @@ var DEFAULT_STRINGS = {
   renderFailed: "This form could not be rendered.",
   resumeNotice: "Picked up where you left off.",
   editNotice: "You're updating your earlier response.",
-  resumeStartOver: "Start over"
+  resumeStartOver: "Start over",
+  challengeUnavailable: "The verification check couldn't load. Refresh the page, or check that challenges.cloudflare.com isn't blocked."
 };
 var DEFAULT_FIELD_STRINGS = {
   required: REQUIRED_FIELD_MESSAGE,
@@ -617,7 +686,7 @@ function validateField(field2, value) {
   }
 }
 function validateResponse(form, data) {
-  const fields = visibleFields(form, data);
+  const fields = reachableFields(form, data);
   const errors = {};
   const cleaned = {};
   for (const field2 of fields) {
@@ -688,7 +757,11 @@ var blockSchema = z2.looseObject({
 var pageSchema = z2.object({
   id: idSchema,
   title: z2.optional(z2.string().check(z2.maxLength(500))),
-  blocks: z2.array(blockSchema).check(z2.maxLength(500))
+  blocks: z2.array(blockSchema).check(z2.maxLength(500)),
+  // Optional conditional page flow. Kept as unknown here (this schema is strict,
+  // so it would otherwise be dropped at parse) and normalized by hand below once
+  // the page-id set is known — a jump to a missing page is dropped, never kept.
+  next: z2.optional(z2.unknown())
 });
 var schemaShape = z2.object({
   version: z2.literal(1),
@@ -699,8 +772,9 @@ var schemaShape = z2.object({
 });
 var MAX_SCHEMA_VERSION = 1;
 var FILLO_SCHEMA_VERSION = 1;
-var FILLO_SDK_VERSION = true ? "0.8.0" : "0.0.0-dev";
+var FILLO_SDK_VERSION = true ? "0.9.0" : "0.0.0-dev";
 var FILLO_MIN_SDK_VERSION = "0.4.0";
+var FILLO_CHALLENGE_MIN_SDK_VERSION = "0.9.0";
 function str(value, max, fallback = "") {
   return typeof value === "string" ? value.trim().slice(0, max) : fallback;
 }
@@ -755,6 +829,23 @@ function conditions(value) {
   });
   return normalized.length ? normalized : void 0;
 }
+function jumpRules(value, pageIds, sourceId, allowedFieldIds) {
+  if (!Array.isArray(value)) return void 0;
+  const rules = value.slice(0, 50).flatMap((item) => {
+    if (!item || typeof item !== "object") return [];
+    const rec = item;
+    const to = typeof rec.to === "string" ? rec.to : void 0;
+    if (!to || to !== "end" && !pageIds.has(to)) return [];
+    if (to === sourceId) return [];
+    const rawWhen = rec.when;
+    if (rawWhen !== void 0 && !Array.isArray(rawWhen)) return [];
+    const when2 = conditions(rawWhen);
+    if (Array.isArray(rawWhen) && rawWhen.length > 0 && when2 === void 0) return [];
+    if (when2 && when2.some((c) => !allowedFieldIds.has(c.fieldId))) return [];
+    return [{ when: when2 ?? [], to }];
+  });
+  return rules.length ? rules : void 0;
+}
 function baseBlock(rec) {
   return {
     id: str(rec.id, 128),
@@ -798,6 +889,17 @@ function normalizeResponseLimit(value) {
     onRepeat
   };
 }
+function normalizeTrust(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const rec = value;
+  const unverified = rec.unverified === "allow" || rec.unverified === "quarantine" ? rec.unverified : void 0;
+  const challenge = rec.challenge === "turnstile" ? "turnstile" : void 0;
+  if (!unverified && !challenge) return void 0;
+  return {
+    ...unverified ? { unverified } : {},
+    ...challenge ? { challenge } : {}
+  };
+}
 function normalizeSettings(value) {
   const rec = value && typeof value === "object" ? value : {};
   const submitMode = rec.submitMode === "button" || rec.submitMode === "auto" ? rec.submitMode : void 0;
@@ -809,6 +911,7 @@ function normalizeSettings(value) {
     redirectUrl: normalizeUrl(rec.redirectUrl),
     showProgress: bool(rec.showProgress),
     responseLimit: normalizeResponseLimit(rec.responseLimit),
+    trust: normalizeTrust(rec.trust),
     notifyEmail: z2.email().check(z2.maxLength(254)).safeParse(rec.notifyEmail).success ? rec.notifyEmail : void 0,
     sendReceipt: bool(rec.sendReceipt),
     saveProgress: bool(rec.saveProgress),
@@ -948,15 +1051,24 @@ function normalizeFormSchema(input) {
   if (parsed.data.version > MAX_SCHEMA_VERSION) {
     return { ok: false, error: `Unsupported schema version: ${parsed.data.version}` };
   }
-  const pages = parsed.data.pages.map((page) => {
+  const rebuilt = parsed.data.pages.map((page) => {
     const blocks = page.blocks.flatMap((raw) => {
       const block = normalizeBlock(raw);
       return block ? [block] : [];
     });
+    return { id: str(page.id, 128), title: optionalStr(page.title, 500), blocks, next: page.next };
+  });
+  const targetIds = new Set(rebuilt.map((p) => p.id));
+  const priorFieldIds = /* @__PURE__ */ new Set();
+  const pages = rebuilt.map((page) => {
+    for (const block of page.blocks) {
+      if (isField(block)) priorFieldIds.add(block.id);
+    }
     return cleanObject({
-      id: str(page.id, 128),
-      title: optionalStr(page.title, 500),
-      blocks
+      id: page.id,
+      title: page.title,
+      blocks: page.blocks,
+      next: jumpRules(page.next, targetIds, page.id, new Set(priorFieldIds))
     });
   });
   const pageIds = /* @__PURE__ */ new Set();
@@ -2353,6 +2465,8 @@ function isDraftGone(err) {
   return isFilloError(err) && (err.status === 401 || err.status === 403 || err.status === 404);
 }
 var DRAFT_DEBOUNCE_MS = 1500;
+var CHALLENGE_INCOMPLETE_MESSAGE = "Please complete the verification check, then submit.";
+var CHALLENGE_RETRY_MESSAGE = "That verification didn't go through. Please complete the check again and resubmit.";
 function submitFailureMessage(err) {
   if (isFilloError(err) && err.status && err.status > 0 && err.message) return err.message;
   return "Couldn't reach the server \u2014 check your connection and try again. If this keeps happening, a browser extension, firewall, or the site's Content-Security-Policy may be blocking the request.";
@@ -2458,7 +2572,10 @@ function createFormController(options2) {
       // keeps it — never a field whose answer submit would silently drop.
       blocks: visiblePageBlocks(form, page, data),
       isFirstPage: clamped === 0,
-      isLastPage: clamped === pageCount - 1,
+      // Terminal-aware: true when the current page is the last reachable page OR
+      // a matched jump rule ends the form here — so the footer reads Submit and
+      // its handler submits. Same shared engine the validator reaches with.
+      isLastPage: isTerminalPage(form, page.id, data),
       uploading: uploadingFields.size > 0,
       submitError,
       restoredSubmission,
@@ -2659,6 +2776,20 @@ function createFormController(options2) {
     else uploadingFields.delete(fieldId);
     notify();
   }
+  function currentSeqPosition(seq) {
+    if (seq.length === 0) return -1;
+    const pageCount = form.pages.length;
+    const clamped = Math.min(pageIndex, Math.max(pageCount - 1, 0));
+    const currentId = form.pages[clamped]?.id;
+    const exact = currentId === void 0 ? -1 : seq.indexOf(currentId);
+    if (exact >= 0) return exact;
+    let fallback = 0;
+    for (let i = 0; i < seq.length; i++) {
+      const idx = form.pages.findIndex((p) => p.id === seq[i]);
+      if (idx >= 0 && idx <= clamped) fallback = i;
+    }
+    return fallback;
+  }
   function next() {
     const pageCount = form.pages.length;
     const clamped = Math.min(pageIndex, Math.max(pageCount - 1, 0));
@@ -2670,14 +2801,31 @@ function createFormController(options2) {
         return;
       }
     }
-    pageIndex = Math.min(clamped + 1, pageCount - 1);
+    const current = form.pages[clamped];
+    const seq = reachablePageSequence(form, data);
+    const pos = currentSeqPosition(seq);
+    const terminal = (current ? isTerminalPage(form, current.id, data) : true) || pos < 0 || pos + 1 >= seq.length;
+    if (terminal) {
+      void submit();
+      return;
+    }
+    const nextIndex = form.pages.findIndex((p) => p.id === seq[pos + 1]);
+    pageIndex = nextIndex >= 0 ? nextIndex : Math.min(clamped + 1, pageCount - 1);
     if (sessionId && client) client.reportProgress(sessionId, { furthestPage: pageIndex });
     notify();
     checkpointDraft();
   }
   function back() {
     errors = {};
-    pageIndex = Math.max(Math.min(pageIndex, form.pages.length - 1) - 1, 0);
+    const seq = reachablePageSequence(form, data);
+    const pos = currentSeqPosition(seq);
+    if (pos > 0) {
+      const prevIndex = form.pages.findIndex((p) => p.id === seq[pos - 1]);
+      pageIndex = prevIndex >= 0 ? prevIndex : Math.max(Math.min(pageIndex, form.pages.length - 1) - 1, 0);
+    } else if (seq.length > 0) {
+      const firstIndex = form.pages.findIndex((p) => p.id === seq[0]);
+      pageIndex = firstIndex >= 0 ? firstIndex : 0;
+    }
     notify();
     checkpointDraft();
   }
@@ -2710,6 +2858,13 @@ function createFormController(options2) {
       const visitorKey = form.settings.responseLimit?.by === "browser" ? ensureSubmissionKey(visitorSubmissionKeyId(form, formId, result.data)) : void 0;
       const submissionKey = visitorKey ?? idempotencyKey;
       const submitDraft = form.settings.saveProgress ? draftRef ?? readDraftRef(formId) : null;
+      const challengeToken = options2.challengeRequired ? options2.getChallengeToken?.() : void 0;
+      if (options2.challengeRequired && !challengeToken) {
+        status = "idle";
+        submitError = CHALLENGE_INCOMPLETE_MESSAGE;
+        notify();
+        return;
+      }
       status = "submitting";
       submitError = void 0;
       notify();
@@ -2721,10 +2876,17 @@ function createFormController(options2) {
           surface: options2.surface ?? "headless",
           submissionKey,
           draft: submitDraft ? { id: submitDraft.id, token: submitDraft.token } : void 0,
-          respondent
+          respondent,
+          challengeToken
         });
       } catch (err) {
         status = "idle";
+        if (isFilloError(err) && err.code === "challenge_failed") {
+          submitError = CHALLENGE_RETRY_MESSAGE;
+          options2.onChallengeFailed?.();
+          notify();
+          return;
+        }
         submitError = submitFailureMessage(err);
         notify();
         throw err;
@@ -2833,7 +2995,7 @@ function needsExplicitSubmit(visible) {
 }
 function shouldAutoSubmit(field2, value, ctx) {
   if (ctx.form.settings.submitMode !== "auto") return false;
-  if (!ctx.isLastPage || ctx.status !== "idle" || ctx.uploading) return false;
+  if (ctx.status !== "idle" || ctx.uploading) return false;
   const hasDiscreteAnswer = (() => {
     switch (field2.kind) {
       case "select":
@@ -2851,7 +3013,9 @@ function shouldAutoSubmit(field2, value, ctx) {
   if (!hasDiscreteAnswer) return false;
   if (value === ctx.data[field2.id]) return false;
   const nextData = { ...ctx.data, [field2.id]: value };
-  const interactive = visibleFields(ctx.form, nextData).filter((f) => f.kind !== "hidden");
+  const page = ctx.form.pages.find((p) => p.blocks.some((b) => b.id === field2.id));
+  if (!page || !isTerminalPage(ctx.form, page.id, nextData)) return false;
+  const interactive = reachableFields(ctx.form, nextData).filter((f) => f.kind !== "hidden");
   if (interactive.length !== 1 || interactive[0]?.id !== field2.id) return false;
   return validateResponse(ctx.form, nextData).ok;
 }
@@ -2877,7 +3041,8 @@ var FILLO_SLOTS = [
   "footer",
   "button",
   "success",
-  "resume"
+  "resume",
+  "turnstile"
 ];
 var FILLO_DATA_ATTRS = {
   /** Slot name, on every slot element: `data-fillo="control"`. */
@@ -2985,7 +3150,7 @@ function formSchemasEqual(left, right) {
 var syncTtlMs = (status) => status === "published" ? 36e5 : 6e4;
 var isVolatileSync = (result) => Boolean(result.staged || result.resolvedSchema || result.syncError);
 function storageKey(client, handle) {
-  return `fillo:sync:v2:${client.baseUrl}|${client.key}|${handle}`;
+  return `fillo:sync:v3:${client.baseUrl}|${client.key}|${handle}`;
 }
 function readStoredSync(client, handle, hash) {
   try {
@@ -3003,6 +3168,7 @@ function readStoredSync(client, handle, hash) {
 }
 function writeStoredSync(client, handle, hash, r) {
   if (r.staged || r.resolvedSchema || r.syncError) return;
+  if (r.challenge) return;
   try {
     globalThis.localStorage?.setItem(
       storageKey(client, handle),
@@ -3415,6 +3581,7 @@ export {
   DEFAULT_FIELD_STRINGS,
   DEFAULT_STRINGS,
   DRAFT_KINDS,
+  FILLO_CHALLENGE_MIN_SDK_VERSION,
   FILLO_DATA_ATTRS,
   FILLO_MIN_SDK_VERSION,
   FILLO_SCHEMA_VERSION,
@@ -3433,6 +3600,7 @@ export {
   allFields,
   assembleForm,
   codeFormFromJsx,
+  conditionsMet,
   contentHash,
   countryByDialCode,
   countryByIso,
@@ -3454,6 +3622,7 @@ export {
   isField,
   isFilloError,
   isPossiblePhone,
+  isTerminalPage,
   needsExplicitSubmit,
   normalizeFormSchema,
   normalizeFormTheme,
@@ -3463,6 +3632,11 @@ export {
   positionPhonePopover,
   prefillFromParams,
   provisionWorkspace,
+  reachableFieldIds,
+  reachableFields,
+  reachablePageIds,
+  reachablePageSequence,
+  resolveNextPage,
   resolveSlotClass,
   resolveStrings,
   resolveText,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefillo/core",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Form schema, validation, logic engine and JS client for Fillo. Framework-agnostic.",
   "license": "MIT",
   "keywords": [