@usefillo/core 0.6.2 → 0.7.0

package/README.md

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

package/dist/index.d.ts

@@ -148,6 +148,39 @@ interface FormPage {
     title?: string;
     blocks: Block[];
 }
+/**
+ * Limit repeat responses. Absent = no limit (submit as often as you like).
+ */
+interface ResponseLimit {
+    /**
+     * Who counts as the same responder:
+     * - "browser": same device, anonymous — the SDK remembers this browser
+     *   answered and sends a de-duplication key (ratings, polls, "was this
+     *   helpful").
+     * - "field": the person self-identifies by answering `field` (an email or
+     *   phone field). A self-claim — unverified, soft dedup — so the hosted link
+     *   and anonymous embeds can still dedupe.
+     * - "identify": the identify() respondent (HMAC-verifiable). The strong
+     *   path; only embedded surfaces that call identify() are recognized.
+     */
+    by: "browser" | "field" | "identify";
+    /** The email/phone field whose answer identifies the person. `by: "field"` only. */
+    field?: string;
+    /**
+     * Optionally sub-scope the limit by a field's answer (usually a hidden
+     * article/product/order id): "one response per responder PER that value" —
+     * e.g. one 👍 per visitor per article from a single shared form.
+     */
+    scopeField?: string;
+    /**
+     * A repeat from the same responder: "keep" answers with the standing
+     * response (the first answer stands); "update" edits it in place (re-anchored
+     * to the current schema, `response.updated` webhook, previous answers
+     * prefilled for a verified respondent). "update" applies to `by: "identify"`
+     * only — a self-claim/browser must not overwrite another person's response.
+     */
+    onRepeat: "keep" | "update";
+}
 interface FormSettings {
     /**
      * Default "button": respondents submit with the footer button. "auto" hides
@@ -160,17 +193,49 @@ interface FormSettings {
     successMessage?: string;
     redirectUrl?: string;
     showProgress?: boolean;
-    /**
-     * Default "multiple": a browser can submit as often as it wants. Use
-     * "once_per_visitor" for tiny docs/article feedback where the SDK should
-     * remember this browser has already answered and send a server-side
-     * de-duplication key with the response.
-     */
-    submissionLimit?: "multiple" | "once_per_visitor";
+    /** Limit repeat responses (who counts as the same responder, and what a
+     *  repeat does). Absent = no limit. See {@link ResponseLimit}. */
+    responseLimit?: ResponseLimit;
     /** Notify this address on every submission. */
     notifyEmail?: string;
     /** Send respondents a receipt (to the first answered email field). */
     sendReceipt?: boolean;
+    /**
+     * Save respondents' in-progress answers to Fillo (default off). The SDK
+     * autosaves as they type and restores on return, so long forms survive
+     * reloads and tab closes. Off by default because it stores answers before
+     * the respondent chooses to submit — the form owner opts in.
+     */
+    saveProgress?: boolean;
+    /**
+     * Let workspace members read the answers a respondent has typed but not yet
+     * submitted (default off; requires saveProgress). This exposes pre-submission
+     * content to the owner's team, so it's a separate opt-in with its own consent
+     * framing — disclose it in your privacy policy. Respondents still see the
+     * "progress saved" notice. The content is visible only in the authenticated
+     * dashboard; the draft token stays the only public read capability.
+     */
+    draftAnswersVisible?: boolean;
+    /**
+     * Email a respondent one "pick up where you left off" link when they leave a
+     * form idle (default off; requires saveProgress). Sent at most once per
+     * draft, to an address they entered or their verified account email — never
+     * with any answer content. Owner opt-in.
+     */
+    resumeEmails?: boolean;
+    /**
+     * Where a resume link should land for an embedded form (http(s) only). The
+     * draft reference travels in the URL fragment, which the SDK adopts on load;
+     * defaults to the hosted /f page when unset.
+     */
+    resumeUrl?: string;
+    /**
+     * Email the form's notification address a daily digest of who dropped off —
+     * abandoned and open draft counts, where people stalled, and verified
+     * respondents by name (default off; requires notifyEmail). Never any answer
+     * content or resume links.
+     */
+    draftDigest?: boolean;
 }
 interface FormSchema {
     version: 1;
@@ -281,6 +346,15 @@ declare function isBlockVisible(block: Block, data: ResponseData): boolean;
 declare function visibleBlocks(page: FormPage, data: ResponseData): Block[];
 /** Every field in the form (across pages), in order. */
 declare function allFields(form: FormSchema): Field[];
+/**
+ * The scope key for a response limit: the string form of the answer to
+ * `settings.responseLimit.scopeField`, or null when there is no scope field or the
+ * answer is not a usable scalar. A non-scalar answer (checkbox boolean,
+ * multi_select/ranking array, matrix object) means "no scope" — the limit
+ * spans the whole form rather than silently mis-bucketing. Shared by the SDK's
+ * 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. */
 declare function visibleFields(form: FormSchema, data: ResponseData): Field[];
 
@@ -302,6 +376,7 @@ declare function validateResponse(form: FormSchema, data: ResponseData): Validat
 declare const FILLO_SCHEMA_VERSION: 1;
 /** Injected from package.json at build time (tsup define) — never hand-edited. */
 declare const FILLO_SDK_VERSION: string;
+declare function normalizeSettings(value: unknown): FormSettings;
 interface SchemaValidationResult {
     ok: boolean;
     /** Present when ok — a normalized, structurally-valid schema. */
@@ -478,6 +553,8 @@ type SubmitResult = {
     responseId: string;
     /** True when the API accepted the request as an already-recorded visitor response. */
     duplicate?: boolean;
+    /** True when an update-in-place limit (responseLimit onRepeat "update") updated the person's living response. */
+    updated?: boolean;
     errors?: undefined;
 } | {
     ok: false;
@@ -496,9 +573,74 @@ interface SubmitMeta {
     surface?: "default" | "headless";
     /**
      * Browser-scoped de-duplication key sent when a form opts into
-     * settings.submissionLimit = "once_per_visitor".
+     * settings.responseLimit.by = "browser".
      */
     submissionKey?: string;
+    /**
+     * Saved-progress draft this submission completes (forms with
+     * settings.saveProgress). The server deletes the draft with the response
+     * commit so it can't be resumed after submitting.
+     */
+    draft?: {
+        id: string;
+        token: string;
+    };
+    /**
+     * Host-app account context for this respondent (identify()). Recorded with
+     * the response and shown in the dashboard/webhooks as a CLAIM from the
+     * embedding page — it is metadata, not authentication. `id` is your own
+     * stable user/account id.
+     */
+    respondent?: FilloRespondent;
+}
+/**
+ * The host app's account context for the person filling the form. Passed as
+ * the `respondent` option on FilloForm / FilloProvider / renderForm /
+ * createFormController; Fillo keys responses to it so the dashboard,
+ * webhooks, and integrations can say WHO answered.
+ */
+interface FilloRespondent {
+    /** Your stable user/account id — the identity key within your workspace. */
+    id: string;
+    email?: string;
+    name?: string;
+    /** Small primitive facts (plan, role, region…) — not a data warehouse. */
+    traits?: Record<string, string | number | boolean>;
+    /**
+     * Identity verification (optional): hex HMAC-SHA256 of `id`, computed on
+     * YOUR server with the workspace identity secret from Fillo settings. Once
+     * the workspace holds a secret, Fillo records identity only with a valid
+     * hash — never compute this in the browser or the secret leaks.
+     */
+    hash?: string;
+}
+/** Wire shape of a saved-progress draft (settings.saveProgress forms). */
+interface ResponseDraft {
+    id: string;
+    formId: string;
+    /** Partial answers exactly as last saved — validated only at submit. */
+    data: ResponseData;
+    /** 0-based page the respondent was on when the draft was last saved. */
+    page: number;
+    /** A freshly rotated bearer, returned only when adopting a resume link — the
+     *  URL token is spent, so this is what future saves must use. */
+    token?: string;
+}
+interface CreatedDraft {
+    id: string;
+    /**
+     * Per-draft bearer, returned once at creation; sent back as
+     * X-Fillo-Draft-Token on every read/save/delete of this draft.
+     */
+    token: string;
+    /** ISO timestamp; the server slides it forward on every save. */
+    expiresAt?: string;
+    /**
+     * True when a VERIFIED identity picked up its existing draft from another
+     * device — the token was rotated to this caller, and the draft's answers
+     * were left untouched (fetch them with getDraft to restore).
+     */
+    existing?: boolean;
 }
 interface UploadProgress {
     uploadedBytes: number;
@@ -553,6 +695,16 @@ declare class FilloClient {
     syncForm(handle: string, schema: FormSchema, theme?: FormTheme | null): Promise<SyncFormResult>;
     /** Submit a response. Returns per-field errors instead of throwing on validation failure. */
     submit(formId: string, data: ResponseData, meta?: SubmitMeta): Promise<SubmitResult>;
+    /**
+     * The identified person's own living response on an upsert-mode form —
+     * 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.
+     */
+    fetchOwnResponse(formId: string, respondent: FilloRespondent): Promise<{
+        responseId: string;
+        data: ResponseData;
+    } | null>;
     /**
      * Open a respondent session for funnel analysis. Fire-and-forget: returns the
      * session id, or null if tracking is unavailable (never blocks the form).
@@ -563,6 +715,33 @@ declare class FilloClient {
         furthestPage?: number;
         completed?: boolean;
     }): void;
+    /**
+     * Create a saved-progress draft (forms with settings.saveProgress). Returns
+     * the draft id and its ownership token — the token is shown only once.
+     */
+    createDraft(formId: string, body: {
+        data: ResponseData;
+        page?: number;
+        respondent?: FilloRespondent;
+    }): Promise<CreatedDraft>;
+    /** Fetch a draft to restore. 404s once expired, consumed, or deleted. When
+     *  `adopt` is set (resume-link adoption), the server rotates the bearer and
+     *  returns the new `token` — the URL token becomes single-use. */
+    getDraft(draftId: string, token: string, adopt?: boolean): Promise<ResponseDraft>;
+    /**
+     * Overwrite a draft's answers/page and slide its expiry. `keepalive` lets a
+     * tab-close flush outlive the page; browsers reject keepalive bodies over
+     * ~64KB, in which case this save is simply lost — the debounced autosaves
+     * every few keystrokes are the real persistence, the flush is a bonus.
+     */
+    saveDraft(draftId: string, token: string, body: {
+        data: ResponseData;
+        page?: number;
+    }, opts?: {
+        keepalive?: boolean;
+    }): Promise<void>;
+    /** 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>;
     /**
@@ -680,6 +859,13 @@ interface FormControllerOptions {
      * respondent can retry.
      */
     resolveFormId?: () => Promise<string>;
+    /**
+     * Host-app account context (identify()): who is filling this form, by your
+     * own user id. Sent with the submission and recorded as an unverified
+     * claim — it changes what the dashboard/webhooks can tell you, never what
+     * the respondent can do.
+     */
+    respondent?: FilloRespondent;
 }
 interface FormControllerState {
     data: ResponseData;
@@ -697,6 +883,27 @@ interface FormControllerState {
     uploading: boolean;
     /** Human-readable message for the last failed submit; cleared on edit/retry. */
     submitError?: string;
+    /**
+     * True when `status` is "submitted" because the once-per-visitor gate
+     * restored a previous visit's response, not because a submit happened in
+     * this controller instance. Renderers use it to skip one-time "just
+     * submitted" reactions (moving focus to the success screen, redirecting) —
+     * otherwise every remount of an already-answered form replays them.
+     */
+    restoredSubmission: boolean;
+    /**
+     * True when a saved-progress draft (settings.saveProgress) was restored
+     * into this fill — answers and/or page position came from a previous
+     * visit. Renderers use it to show a "continuing where you left off"
+     * notice with a Start over action (resetDraft).
+     */
+    resumedDraft: boolean;
+    /**
+     * True when an update-in-place limit prefilled the VERIFIED respondent's own
+     * previous answers — submitting updates that response in place. Renderers
+     * show an "updating your earlier response" notice.
+     */
+    editingPrevious: boolean;
 }
 interface FormController {
     /** Stable snapshot — same reference until something changes (safe for useSyncExternalStore). */
@@ -721,7 +928,21 @@ interface FormController {
         form?: FormSchema;
         formId?: string;
         client?: FilloClient;
+        /** Late-bind identify() context — host sessions often resolve after mount. */
+        respondent?: FilloRespondent;
     }): void;
+    /**
+     * Persist any unsaved draft progress right now (settings.saveProgress
+     * forms). Renderers call this on pagehide/visibility-hidden so the last
+     * keystrokes survive a tab close; a no-op when there's nothing to save.
+     */
+    flushDraft(): void;
+    /**
+     * Discard the saved draft and reset to a fresh fill: answers back to
+     * initialData + URL prefill, first page, errors cleared. The "Start over"
+     * action next to the resume notice.
+     */
+    resetDraft(): void;
     /** Drop all listeners. */
     destroy(): void;
 }
@@ -753,7 +974,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"];
+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"];
 type FilloSlot = (typeof FILLO_SLOTS)[number];
 /** data-* names emitted alongside the stable fillo-* classes. */
 declare const FILLO_DATA_ATTRS: {
@@ -870,6 +1091,12 @@ interface FilloStrings {
     loadFailedNetwork: string;
     loadFailed: string;
     renderFailed: string;
+    /** Saved-progress notice when a draft restored earlier answers. */
+    resumeNotice: string;
+    /** Upsert-mode notice when the person's previous response was prefilled. */
+    editNotice: string;
+    /** The discard action next to the resume notice. */
+    resumeStartOver: string;
 }
 declare const DEFAULT_STRINGS: FilloStrings;
 declare function resolveStrings(overrides?: Partial<FilloStrings>): FilloStrings;
@@ -1036,4 +1263,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 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 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 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, parsePhone, pipeBlock, prefillFromParams, provisionWorkspace, resolveSlotClass, resolveStrings, resolveText, 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 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 };

package/dist/index.js

@@ -77,6 +77,12 @@ function visibleBlocks(page, data) {
 function allFields(form) {
   return form.pages.flatMap((p) => p.blocks.filter(isField));
 }
+function responseScopeValue(settings, data) {
+  const field2 = settings.responseLimit?.scopeField;
+  if (!field2) return null;
+  const value = data[field2];
+  return typeof value === "string" || typeof value === "number" ? String(value) : null;
+}
 function visibleFields(form, data) {
   const fields = allFields(form);
   const visible = visibleFieldIds(fields, data);
@@ -594,7 +600,7 @@ var schemaShape = z2.object({
 });
 var MAX_SCHEMA_VERSION = 1;
 var FILLO_SCHEMA_VERSION = 1;
-var FILLO_SDK_VERSION = true ? "0.6.2" : "0.0.0-dev";
+var FILLO_SDK_VERSION = true ? "0.7.0" : "0.0.0-dev";
 function str(value, max, fallback = "") {
   return typeof value === "string" ? value.trim().slice(0, max) : fallback;
 }
@@ -668,10 +674,25 @@ function normalizeUrl(value) {
     return void 0;
   }
 }
+function normalizeResponseLimit(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const rec = value;
+  const by = rec.by === "browser" || rec.by === "field" || rec.by === "identify" ? rec.by : void 0;
+  if (!by) return void 0;
+  const field2 = by === "field" ? optionalStr(rec.field, 128) : void 0;
+  if (by === "field" && !field2) return void 0;
+  const scopeField = optionalStr(rec.scopeField, 128);
+  const onRepeat = rec.onRepeat === "update" && by === "identify" ? "update" : "keep";
+  return {
+    by,
+    ...field2 ? { field: field2 } : {},
+    ...scopeField ? { scopeField } : {},
+    onRepeat
+  };
+}
 function normalizeSettings(value) {
   const rec = value && typeof value === "object" ? value : {};
   const submitMode = rec.submitMode === "button" || rec.submitMode === "auto" ? rec.submitMode : void 0;
-  const submissionLimit = rec.submissionLimit === "once_per_visitor" || rec.submissionLimit === "multiple" ? rec.submissionLimit : void 0;
   return {
     submitMode,
     submitLabel: optionalStr(rec.submitLabel, 100),
@@ -679,9 +700,14 @@ function normalizeSettings(value) {
     successMessage: optionalStr(rec.successMessage, 5e3),
     redirectUrl: normalizeUrl(rec.redirectUrl),
     showProgress: bool(rec.showProgress),
-    submissionLimit,
+    responseLimit: normalizeResponseLimit(rec.responseLimit),
     notifyEmail: z2.email().check(z2.maxLength(254)).safeParse(rec.notifyEmail).success ? rec.notifyEmail : void 0,
-    sendReceipt: bool(rec.sendReceipt)
+    sendReceipt: bool(rec.sendReceipt),
+    saveProgress: bool(rec.saveProgress),
+    draftAnswersVisible: bool(rec.draftAnswersVisible),
+    resumeEmails: bool(rec.resumeEmails),
+    resumeUrl: normalizeUrl(rec.resumeUrl),
+    draftDigest: bool(rec.draftDigest)
   };
 }
 function cleanObject(obj) {
@@ -1049,8 +1075,7 @@ function createEmptyForm(title = "Untitled form") {
       submitLabel: "Submit",
       successTitle: "Thanks!",
       successMessage: "Your response has been recorded.",
-      showProgress: true,
-      submissionLimit: "multiple"
+      showProgress: true
     }
   };
 }
@@ -1413,7 +1438,24 @@ var FilloClient = class {
       throw new FilloError(message, res.status, retryAfterSec(res));
     }
     const body = await res.json();
-    return { ok: true, responseId: body.id, duplicate: body.duplicate };
+    return { ok: true, responseId: body.id, duplicate: body.duplicate, updated: body.updated };
+  }
+  /**
+   * The identified person's own living response on an upsert-mode form —
+   * 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.
+   */
+  async fetchOwnResponse(formId, respondent) {
+    try {
+      return await this.json(
+        `/forms/${encodeURIComponent(formId)}/respondent-response`,
+        { method: "POST", body: JSON.stringify({ respondent }) }
+      );
+    } catch (err) {
+      if (isFilloError(err) && (err.status === 404 || err.status === 403)) return null;
+      throw err;
+    }
   }
   /**
    * Open a respondent session for funnel analysis. Fire-and-forget: returns the
@@ -1448,6 +1490,45 @@ var FilloClient = class {
     } catch {
     }
   }
+  /**
+   * Create a saved-progress draft (forms with settings.saveProgress). Returns
+   * the draft id and its ownership token — the token is shown only once.
+   */
+  createDraft(formId, body) {
+    return this.json(`/forms/${encodeURIComponent(formId)}/drafts`, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  /** Fetch a draft to restore. 404s once expired, consumed, or deleted. When
+   *  `adopt` is set (resume-link adoption), the server rotates the bearer and
+   *  returns the new `token` — the URL token becomes single-use. */
+  getDraft(draftId, token, adopt) {
+    return this.json(`/drafts/${encodeURIComponent(draftId)}`, {
+      headers: adopt ? { "X-Fillo-Draft-Token": token, "X-Fillo-Draft-Adopt": "1" } : { "X-Fillo-Draft-Token": token }
+    });
+  }
+  /**
+   * Overwrite a draft's answers/page and slide its expiry. `keepalive` lets a
+   * tab-close flush outlive the page; browsers reject keepalive bodies over
+   * ~64KB, in which case this save is simply lost — the debounced autosaves
+   * every few keystrokes are the real persistence, the flush is a bonus.
+   */
+  async saveDraft(draftId, token, body, opts) {
+    await this.json(`/drafts/${encodeURIComponent(draftId)}`, {
+      method: "PATCH",
+      headers: { "X-Fillo-Draft-Token": token },
+      body: JSON.stringify(body),
+      ...opts?.keepalive ? { keepalive: true } : {}
+    });
+  }
+  /** Discard a draft (the "Start over" path). */
+  async deleteDraft(draftId, token) {
+    await this.json(`/drafts/${encodeURIComponent(draftId)}`, {
+      method: "DELETE",
+      headers: { "X-Fillo-Draft-Token": token }
+    });
+  }
   /** Current state of an upload session — used to resume after interruption. */
   getUploadSession(sessionId, token) {
     return this.json(
@@ -1842,25 +1923,36 @@ function randomSubmissionKey() {
   }
   return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
-function readStoredSubmission(formId) {
+function readStoredJson(memory, storageKey2, memoryKey, isValid) {
   const store = browserStorage();
-  if (!store) return memorySubmissionKeys.get(formId) ?? null;
+  if (!store) return memory.get(memoryKey) ?? null;
   try {
-    const parsed = JSON.parse(store.getItem(submissionStorageKey(formId)) ?? "null");
-    if (parsed && typeof parsed.key === "string") return parsed;
+    const parsed = JSON.parse(store.getItem(storageKey2) ?? "null");
+    if (parsed && isValid(parsed)) return parsed;
   } catch {
   }
   return null;
 }
-function writeStoredSubmission(formId, value) {
-  memorySubmissionKeys.set(formId, value);
+function writeStoredJson(memory, storageKey2, memoryKey, value) {
+  memory.set(memoryKey, value);
   const store = browserStorage();
   if (!store) return;
   try {
-    store.setItem(submissionStorageKey(formId), JSON.stringify(value));
+    store.setItem(storageKey2, JSON.stringify(value));
   } catch {
   }
 }
+function readStoredSubmission(formId) {
+  return readStoredJson(
+    memorySubmissionKeys,
+    submissionStorageKey(formId),
+    formId,
+    (p) => typeof p.key === "string"
+  );
+}
+function writeStoredSubmission(formId, value) {
+  writeStoredJson(memorySubmissionKeys, submissionStorageKey(formId), formId, value);
+}
 function ensureSubmissionKey(formId) {
   const existing = readStoredSubmission(formId);
   if (existing?.key) return existing.key;
@@ -1876,10 +1968,40 @@ function markSubmitted(formId, responseId) {
     responseId
   });
 }
-function hasSubmittedOnce(form, formId) {
-  if (form.settings.submissionLimit !== "once_per_visitor" || !formId) return false;
-  return Boolean(readStoredSubmission(formId)?.submittedAt);
+function visitorSubmissionKeyId(form, formId, data) {
+  const scope = responseScopeValue(form.settings, data);
+  return scope === null ? formId : `${formId}::${scope}`;
+}
+function hasSubmittedOnce(form, formId, data) {
+  if (form.settings.responseLimit?.by !== "browser" || !formId) return false;
+  return Boolean(readStoredSubmission(visitorSubmissionKeyId(form, formId, data))?.submittedAt);
+}
+var memoryDraftRefs = /* @__PURE__ */ new Map();
+function draftStorageKey(formId) {
+  return `fillo:draft:${formId}`;
+}
+function readDraftRef(formId) {
+  return readStoredJson(memoryDraftRefs, draftStorageKey(formId), formId, (p) => {
+    const ref = p;
+    return typeof ref.id === "string" && typeof ref.token === "string";
+  });
+}
+function writeDraftRef(formId, ref) {
+  writeStoredJson(memoryDraftRefs, draftStorageKey(formId), formId, ref);
 }
+function clearDraftRef(formId) {
+  memoryDraftRefs.delete(formId);
+  const store = browserStorage();
+  if (!store) return;
+  try {
+    store.removeItem(draftStorageKey(formId));
+  } catch {
+  }
+}
+function isDraftGone(err) {
+  return isFilloError(err) && (err.status === 401 || err.status === 403 || err.status === 404);
+}
+var DRAFT_DEBOUNCE_MS = 1500;
 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.";
@@ -1891,15 +2013,13 @@ function createFormController(options2) {
   let form = initial.schema;
   let formId = options2.formId;
   let client = options2.client;
+  let respondent = options2.respondent;
   let data = { ...options2.initialData ?? {} };
   let errors = {};
   let pageIndex = 0;
   let status = "idle";
+  let restoredSubmission = false;
   queueMicrotask(() => {
-    if (status === "idle" && hasSubmittedOnce(form, formId)) {
-      status = "submitted";
-      notify();
-    }
     if (typeof location !== "undefined" && location.search) {
       const params = Object.fromEntries(new URLSearchParams(location.search));
       let merged = null;
@@ -1914,6 +2034,31 @@ function createFormController(options2) {
         notify();
       }
     }
+    if (status === "idle" && hasSubmittedOnce(form, formId, data)) {
+      status = "submitted";
+      restoredSubmission = true;
+      notify();
+    }
+    let adopting = false;
+    if (form.settings.saveProgress && formId && client && typeof location !== "undefined" && location.hash.includes("fillo-draft=")) {
+      const match = /fillo-draft=([^&]+)/.exec(location.hash);
+      const raw = match?.[1] ? decodeURIComponent(match[1]) : "";
+      const dot = raw.indexOf(".");
+      if (dot > 0) {
+        adopting = true;
+        const did = raw.slice(0, dot);
+        const dtok = raw.slice(dot + 1);
+        client.getDraft(did, dtok, true).then((d) => {
+          writeDraftRef(formId, { id: did, token: d.token ?? dtok });
+          try {
+            history.replaceState(null, "", location.pathname + location.search);
+          } catch {
+          }
+        }).catch(() => {
+        }).finally(() => maybeRestoreDraft());
+      }
+    }
+    if (!adopting) maybeRestoreDraft();
   });
   let submitError;
   const uploadingFields = /* @__PURE__ */ new Set();
@@ -1922,6 +2067,16 @@ function createFormController(options2) {
   const idempotencyKey = randomSubmissionKey();
   let sessionId = null;
   let sessionStarted = false;
+  let resumedDraft = false;
+  let editingPrevious = false;
+  let editAttempted = false;
+  let draftRef = null;
+  let draftTimer = null;
+  let draftChain = Promise.resolve();
+  let draftDirty = false;
+  let draftDisabled = false;
+  let draftRestoreAttempted = false;
+  let draftAffinityAttempted = false;
   function computeSnapshot() {
     const pageCount = form.pages.length;
     const clamped = Math.min(pageIndex, Math.max(pageCount - 1, 0));
@@ -1937,7 +2092,10 @@ function createFormController(options2) {
       isFirstPage: clamped === 0,
       isLastPage: clamped === pageCount - 1,
       uploading: uploadingFields.size > 0,
-      submitError
+      submitError,
+      restoredSubmission,
+      resumedDraft,
+      editingPrevious
     };
   }
   let snapshot = computeSnapshot();
@@ -1963,6 +2121,153 @@ function createFormController(options2) {
     }
     return pageErrors;
   }
+  function draftsEnabled() {
+    return Boolean(form.settings.saveProgress && client && formId && !draftDisabled);
+  }
+  function knownFieldIds() {
+    const ids = /* @__PURE__ */ new Set();
+    for (const page of form.pages) {
+      for (const block of page.blocks) if (isField(block)) ids.add(block.id);
+    }
+    return ids;
+  }
+  function applyDraftSnapshot(draft) {
+    if (status !== "idle" || sessionStarted) return;
+    const ids = knownFieldIds();
+    let merged = null;
+    for (const [key, value] of Object.entries(draft.data ?? {})) {
+      if (data[key] === void 0 && ids.has(key)) {
+        merged = merged ?? { ...data };
+        merged[key] = value;
+      }
+    }
+    const target = typeof draft.page === "number" && Number.isFinite(draft.page) ? Math.max(0, Math.min(Math.floor(draft.page), form.pages.length - 1)) : 0;
+    const movePage = target > 0 && pageIndex === 0;
+    if (!merged && !movePage) return;
+    if (merged) data = merged;
+    if (movePage) pageIndex = target;
+    resumedDraft = true;
+    notify();
+  }
+  function maybeRestoreDraft() {
+    if (status !== "idle") return;
+    if (!draftsEnabled()) {
+      maybePrefillOwnResponse();
+      return;
+    }
+    const fid = formId;
+    const c = client;
+    const ref = draftRef ?? readDraftRef(fid);
+    if (ref && !draftRestoreAttempted) {
+      draftRestoreAttempted = true;
+      draftRef = ref;
+      void c.getDraft(ref.id, ref.token).then(applyDraftSnapshot).catch((err) => {
+        if (isDraftGone(err)) {
+          clearDraftRef(fid);
+          draftRef = null;
+        }
+      });
+      return;
+    }
+    if (!ref && !draftAffinityAttempted && respondent?.hash) {
+      draftAffinityAttempted = true;
+      void c.createDraft(fid, { data: {}, page: 0, respondent }).then((created) => {
+        if (draftRef) return;
+        draftRef = { id: created.id, token: created.token };
+        writeDraftRef(fid, draftRef);
+        if (created.existing) {
+          return c.getDraft(created.id, created.token).then(applyDraftSnapshot);
+        }
+        maybePrefillOwnResponse();
+      }).catch((err) => {
+        if (!(isFilloError(err) && err.status !== void 0 && err.status >= 400 && err.status < 500)) {
+          draftAffinityAttempted = false;
+        }
+      });
+    }
+  }
+  function maybePrefillOwnResponse() {
+    if (editAttempted || form.settings.responseLimit?.onRepeat !== "update") return;
+    if (!client || !formId || !respondent?.hash || status !== "idle") return;
+    editAttempted = true;
+    const c = client;
+    void c.fetchOwnResponse(formId, respondent).then((own) => {
+      if (!own || status !== "idle" || sessionStarted || resumedDraft) return;
+      applyDraftSnapshot({ data: own.data, page: 0 });
+      if (resumedDraft) {
+        resumedDraft = false;
+        editingPrevious = true;
+        notify();
+      }
+    }).catch(() => {
+    });
+  }
+  function persistDraft(keepalive = false) {
+    if (draftTimer) {
+      clearTimeout(draftTimer);
+      draftTimer = null;
+    }
+    if (!draftsEnabled() || status !== "idle" || !draftDirty) return;
+    const fid = formId;
+    const c = client;
+    draftDirty = false;
+    draftChain = draftChain.then(async () => {
+      const payload = {
+        data,
+        page: Math.max(0, Math.min(pageIndex, form.pages.length - 1))
+      };
+      const ref = draftRef ?? readDraftRef(fid);
+      try {
+        if (ref) {
+          try {
+            await c.saveDraft(ref.id, ref.token, payload, keepalive ? { keepalive: true } : void 0);
+            draftRef = ref;
+            return;
+          } catch (err) {
+            if (!isDraftGone(err)) throw err;
+            clearDraftRef(fid);
+            draftRef = null;
+          }
+        }
+        const created = await c.createDraft(
+          fid,
+          respondent?.hash ? { ...payload, respondent } : payload
+        );
+        draftRef = { id: created.id, token: created.token };
+        writeDraftRef(fid, draftRef);
+        if (created.existing) draftDirty = true;
+      } catch (err) {
+        if (isFilloError(err) && err.status !== void 0 && err.status >= 400 && err.status < 500 && err.status !== 429) {
+          draftDisabled = true;
+        } else {
+          draftDirty = true;
+        }
+      }
+    });
+  }
+  function scheduleDraftSave() {
+    if (!draftsEnabled() || status !== "idle") return;
+    draftDirty = true;
+    if (draftTimer) clearTimeout(draftTimer);
+    draftTimer = setTimeout(() => {
+      draftTimer = null;
+      persistDraft();
+    }, DRAFT_DEBOUNCE_MS);
+  }
+  function checkpointDraft() {
+    if (!draftsEnabled() || !sessionStarted && !draftRef) return;
+    draftDirty = true;
+    persistDraft();
+  }
+  function discardDraftState() {
+    if (draftTimer) {
+      clearTimeout(draftTimer);
+      draftTimer = null;
+    }
+    draftDirty = false;
+    if (formId) clearDraftRef(formId);
+    draftRef = null;
+  }
   function setValue(fieldId, value) {
     if (!sessionStarted && client && formId) {
       sessionStarted = true;
@@ -1975,6 +2280,7 @@ function createFormController(options2) {
       errors = Object.fromEntries(Object.entries(errors).filter(([k]) => k !== fieldId));
     }
     notify();
+    scheduleDraftSave();
   }
   function setUploading(fieldId, busy) {
     if (busy) uploadingFields.add(fieldId);
@@ -1995,11 +2301,13 @@ function createFormController(options2) {
     pageIndex = 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);
     notify();
+    checkpointDraft();
   }
   async function submit() {
     if (status === "submitting" || status === "submitted") return;
@@ -2027,8 +2335,9 @@ function createFormController(options2) {
       }
     }
     if (client && formId) {
-      const visitorKey = form.settings.submissionLimit === "once_per_visitor" ? ensureSubmissionKey(formId) : void 0;
+      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;
       status = "submitting";
       submitError = void 0;
       notify();
@@ -2038,7 +2347,9 @@ function createFormController(options2) {
           hp: options2.getHoneypot?.() ?? "",
           elapsedMs: Date.now() - mountedAt,
           surface: options2.surface ?? "headless",
-          submissionKey
+          submissionKey,
+          draft: submitDraft ? { id: submitDraft.id, token: submitDraft.token } : void 0,
+          respondent
         });
       } catch (err) {
         status = "idle";
@@ -2053,7 +2364,8 @@ function createFormController(options2) {
         return;
       }
       if (sessionId) client.reportProgress(sessionId, { completed: true });
-      if (visitorKey) markSubmitted(formId, res.responseId);
+      if (visitorKey) markSubmitted(visitorSubmissionKeyId(form, formId, result.data), res.responseId);
+      discardDraftState();
       status = "submitted";
       notify();
       emitSubmitted(res.responseId, result.data);
@@ -2086,15 +2398,47 @@ function createFormController(options2) {
     setContext(ctx) {
       if ("formId" in ctx) formId = ctx.formId;
       if ("client" in ctx) client = ctx.client;
+      if ("respondent" in ctx) respondent = ctx.respondent;
       if (ctx.form && ctx.form !== form) {
         const next2 = normalizeFormSchema(ctx.form);
         if (!next2.ok) throw new Error(`Invalid form schema: ${next2.error}`);
         form = next2.schema;
       }
-      if (status === "idle" && hasSubmittedOnce(form, formId)) status = "submitted";
+      if (status === "idle" && hasSubmittedOnce(form, formId, data)) {
+        status = "submitted";
+        restoredSubmission = true;
+      }
+      maybeRestoreDraft();
+      notify();
+    },
+    flushDraft() {
+      persistDraft(true);
+    },
+    resetDraft() {
+      if (status === "submitting") return;
+      const ref = draftRef ?? (formId ? readDraftRef(formId) : null);
+      discardDraftState();
+      if (ref && client) void client.deleteDraft(ref.id, ref.token).catch(() => {
+      });
+      data = { ...options2.initialData ?? {} };
+      if (typeof location !== "undefined" && location.search) {
+        const params = Object.fromEntries(new URLSearchParams(location.search));
+        for (const [key, value] of Object.entries(prefillFromParams(form, params))) {
+          if (data[key] === void 0) data[key] = value;
+        }
+      }
+      errors = {};
+      pageIndex = 0;
+      submitError = void 0;
+      resumedDraft = false;
+      editingPrevious = false;
       notify();
     },
     destroy() {
+      if (draftTimer) {
+        clearTimeout(draftTimer);
+        draftTimer = null;
+      }
       listeners.clear();
     }
   };
@@ -2155,7 +2499,8 @@ var FILLO_SLOTS = [
   "error",
   "footer",
   "button",
-  "success"
+  "success",
+  "resume"
 ];
 var FILLO_DATA_ATTRS = {
   /** Slot name, on every slot element: `data-fillo="control"`. */
@@ -2224,7 +2569,10 @@ var DEFAULT_STRINGS = {
   loadFailedNotFound: "Form not found \u2014 check the form id and that it's published.",
   loadFailedNetwork: "Couldn't reach the server \u2014 check your connection or CORS.",
   loadFailed: "This form could not be loaded.",
-  renderFailed: "This form could not be rendered."
+  renderFailed: "This form could not be rendered.",
+  resumeNotice: "Picked up where you left off.",
+  editNotice: "You're updating your earlier response.",
+  resumeStartOver: "Start over"
 };
 function resolveStrings(overrides) {
   return overrides ? { ...DEFAULT_STRINGS, ...overrides } : DEFAULT_STRINGS;
@@ -2691,6 +3039,7 @@ export {
   needsExplicitSubmit,
   normalizeFormSchema,
   normalizeFormTheme,
+  normalizeSettings,
   parsePhone,
   pipeBlock,
   prefillFromParams,
@@ -2698,6 +3047,7 @@ export {
   resolveSlotClass,
   resolveStrings,
   resolveText,
+  responseScopeValue,
   schemaFromJsx,
   sha1Base64,
   shouldAutoSubmit,

package/package.json

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