@usefillo/core 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -20,7 +20,7 @@ interface JumpRule {
     /** 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 FieldKind = "short_text" | "long_text" | "email" | "url" | "phone" | "number" | "select" | "multi_select" | "dropdown" | "checkbox" | "rating" | "linear_scale" | "ranking" | "matrix" | "signature" | "date" | "file_upload" | "hidden" | "calculated" | "custom";
 type ContentKind = "heading" | "paragraph" | "divider";
 type BlockKind = FieldKind | ContentKind;
 interface SelectOption {
@@ -61,6 +61,17 @@ interface NumberField extends BaseField {
     kind: "number";
     min?: number;
     max?: number;
+    /** DISPLAY-ONLY rounding/padding (0–6). Deliberate divergence from
+     *  calculated.decimals, which rounds the STORED value — see decision 1. */
+    decimals?: number;
+    prefix?: string;
+    suffix?: string;
+    /** Thousand separators in the SDK input. Display-only; never reaches the
+     *  wire, the server, or exports. Named by the GROUP separator:
+     *  - `"grouped"`: detect from the respondent's browser locale;
+     *  - `"grouped-comma"`: fixed comma groups, dot decimal — `1,234.56`;
+     *  - `"grouped-dot"`: fixed dot groups, comma decimal — `1.234,56`. */
+    notation?: "grouped" | "grouped-comma" | "grouped-dot";
 }
 interface ChoiceField extends BaseField {
     kind: "select" | "multi_select" | "dropdown";
@@ -129,6 +140,64 @@ interface FileUploadField extends BaseField {
     /** Accepted types, e.g. ["image/*", ".pdf", "video/mp4"]. Empty = anything. */
     accept?: string[];
 }
+/**
+ * The calculation AST (logic depth P2). A typed tree, never a formula string,
+ * and the permanent expression substrate — extending it later means adding
+ * ops, never replacing it. v1 is numeric-only: totals and derived values.
+ *
+ * `if.when` reuses the existing {@link Condition} model verbatim (AND-combined,
+ * same ops) — one condition language across visibility, jumps, and calculations.
+ *
+ * Referenceable operand kinds (v1): `number`, `rating`, `linear_scale`, and
+ * `calculated` (chaining). Nothing else coerces implicitly.
+ */
+type CalcExpr = 
+/** A numeric field ref. Resolves through the same visibility discipline as
+ *  conditions: a logic-hidden source reads as unanswered (→ null). */
+{
+    op: "value";
+    fieldId: string;
+} | {
+    op: "const";
+    value: number;
+}
+/** n-ary, length >= 1. Any null operand → null result (strict propagation). */
+ | {
+    op: "add" | "mul" | "min" | "max";
+    args: CalcExpr[];
+}
+/** Division by zero (and any non-finite result) → null. */
+ | {
+    op: "sub" | "div";
+    left: CalcExpr;
+    right: CalcExpr;
+}
+/** Half-away-from-zero at `decimals` (default 0). */
+ | {
+    op: "round";
+    arg: CalcExpr;
+    decimals?: number;
+} | {
+    op: "if";
+    when: Condition[];
+    then: CalcExpr;
+    else: CalcExpr;
+};
+/**
+ * A derived numeric value computed from other answers — never an input. The
+ * client recomputes it live for piping/conditions/jumps; the server recomputes
+ * it authoritatively on submit, so a tampered client value is ignored by
+ * construction. A null result means the field is unanswered (key absent).
+ */
+interface CalculatedField extends BaseField {
+    kind: "calculated";
+    calc: CalcExpr;
+    /** Rounds the STORED value, not just the display — one deterministic number
+     *  everywhere (client preview, server recompute, grid, CSV, webhooks). */
+    decimals?: number;
+    prefix?: string;
+    suffix?: string;
+}
 /**
  * A field type Fillo doesn't ship. You define it in code and supply the
  * renderer via the SDK's `customComponents` map, keyed by `component`. The
@@ -143,7 +212,7 @@ interface CustomField extends BaseField {
     /** Arbitrary options handed to your component. */
     config?: Record<string, unknown>;
 }
-type Field = TextField | PhoneField | NumberField | ChoiceField | CheckboxField | RatingField | LinearScaleField | RankingField | MatrixField | SignatureField | DateField | FileUploadField | HiddenField | CustomField;
+type Field = TextField | PhoneField | NumberField | ChoiceField | CheckboxField | RatingField | LinearScaleField | RankingField | MatrixField | SignatureField | DateField | FileUploadField | HiddenField | CalculatedField | CustomField;
 interface HeadingBlock extends BaseBlock {
     kind: "heading";
     text: string;
@@ -493,6 +562,49 @@ interface ValidationResult {
  */
 declare function validateResponse(form: FormSchema, data: ResponseData): ValidationResult;
 
+/**
+ * Evaluate a calc expression to a number, or null for "unanswered".
+ * `resolve` maps a fieldId to its effective value and must apply the SAME
+ * visibility discipline as conditions (a logic-hidden source resolves to
+ * undefined) — the shared fixpoint's resolver does exactly that. Semantics:
+ * - an unanswered `value` ref → null; numeric strings bridge exactly like
+ *   condition gt/lt (shared `conditionNumber`), nothing else coerces;
+ * - any null operand → null result (strict propagation, no silent zero);
+ * - division by zero and non-finite results → null;
+ * - `round` is half-away-from-zero at `decimals` (default 0);
+ * - `if` runs its `when` through the standard condition evaluator (AND), so
+ *   unanswered behavior is identical to visibility/jump rules.
+ */
+declare function evaluateCalc(expr: CalcExpr, resolve: (fieldId: string) => FieldValue): number | null;
+/**
+ * Response data with every calculated field's value written in (null or
+ * logic-hidden → key absent, i.e. unanswered) and any client-supplied value
+ * for a calculated id dropped — the engine, never the wire, owns these keys.
+ * Returns `data` unchanged for a calc-free form.
+ *
+ * THE canonical evaluator, shared verbatim by the controller (live display,
+ * piping, conditions) and the server's submit recompute — the contract's
+ * "deterministic, identical evaluation on client and server". Before the
+ * joint {visible set, calc values} fixpoint runs, answers are reduced to the
+ * canonical form the server stores:
+ * - value shape: resolveLogicState reads canonical values (trimmed, coerced,
+ *   empty-as-unanswered — canonical.ts), so `if.when` conditions match the
+ *   kept answers, never a divergent live shape;
+ * - reachability: an answer on a jump-skipped page reads as unanswered, the
+ *   same pruning validateResponse applies before the server recompute. The
+ *   prune below can itself flip a jump or visibility rule, so it iterates to
+ *   a fixed point — each pass keeps a SUBSET of the previous keys (pruning
+ *   only ever removes), so the loop is monotone, terminates within the key
+ *   count, and the client (raw live data) and the server (the once-pruned
+ *   kept set) walk the same shrinking chain to the SAME view.
+ *
+ * The pruned view is EVALUATION input only: non-calc answers pass through to
+ * the output untouched, so the controller keeps a stale answer behind a
+ * flipped jump (navigating back restores it) while its calc display, piping,
+ * and jump decisions read it as unanswered — exactly what the server stores.
+ */
+declare function computeCalculated(form: FormSchema, data: ResponseData): ResponseData;
+
 declare const FILLO_SCHEMA_VERSION: 1;
 /** Injected from package.json at build time (tsup define) — never hand-edited. */
 declare const FILLO_SDK_VERSION: string;
@@ -514,6 +626,17 @@ declare const FILLO_MIN_SDK_VERSION = "0.4.0";
  * @usefillo/*" error instead of a form that silently can't submit.
  */
 declare const FILLO_CHALLENGE_MIN_SDK_VERSION = "0.9.0";
+/**
+ * The floor served INSTEAD of FILLO_MIN_SDK_VERSION for forms whose live
+ * schema contains a calculated field: the first release that ships the kind.
+ * An older SDK's zod enum strips the unknown block, so it renders the form
+ * WITHOUT the calc row — piping shows blanks and any visibility/jump rule
+ * reading the calc id misbehaves. That's wrong-form-behavior, not merely
+ * missing chrome, so it fails fast with the "update @usefillo/*" error
+ * instead (the Turnstile-floor precedent; the form GET picks the max of the
+ * applicable floors).
+ */
+declare const FILLO_CALC_MIN_SDK_VERSION = "0.11.0";
 declare function normalizeSettings(value: unknown): FormSettings;
 interface SchemaValidationResult {
     ok: boolean;
@@ -539,6 +662,90 @@ declare function normalizeFormTheme(input: unknown): FormTheme | null;
  */
 declare function formatAnswer(field: Field, value: FieldValue): string;
 
+/**
+ * Grouped-number display + parsing for the Number field's `notation` input
+ * — browser-locale detection (`"grouped"`) or an author-fixed style
+ * (`"grouped-comma"` = `1,234.56`, `"grouped-dot"` = `1.234,56`); design
+ * contract: docs/decisions/number-formatting.md. All helpers are pure,
+ * side-effect-free, and DOM-free, so the same code runs in @usefillo/react,
+ * @usefillo/dom, and Node. All are strictly display-only — grouping never
+ * touches validation, canonical storage, or the wire (contract decision 2)
+ * — and all degrade to canonical text instead of throwing when `Intl` is
+ * unavailable.
+ */
+/**
+ * The `Intl` locale a `notation` value pins the separators to — the single
+ * source of the notation→locale map, consumed by BOTH renderers (never
+ * duplicate it). Notation values are named by the GROUP separator:
+ * - `"grouped"` (and unset): `undefined` — detect from the respondent's
+ *   browser locale, exactly the pre-fixed-style behavior;
+ * - `"grouped-comma"`: `"en-US"` — comma groups, dot decimal, `1,234.56`;
+ * - `"grouped-dot"`: `"de-DE"` — dot groups, comma decimal, `1.234,56`.
+ */
+declare function localeForNotation(notation?: "grouped" | "grouped-comma" | "grouped-dot"): string | undefined;
+/**
+ * Locale-grouped display text for a finite number — the blurred value of a
+ * `notation: "grouped"` number input. `maximumFractionDigits` is set
+ * explicitly to 20 when `decimals` is unset: Intl's own silent default (3)
+ * would truncate/round a longer fraction on display, silently disagreeing
+ * with the stored value. When `decimals` is set it pins both the minimum and
+ * maximum fraction digits — padding to a stable width, the same contract
+ * `formatAnswer`'s toFixed follows. Non-finite input and a missing `Intl`
+ * both fall back to canonical text; this must never throw mid-keystroke.
+ */
+declare function formatGroupedNumber(value: number, opts?: {
+    locale?: string;
+    decimals?: number;
+}): string;
+/**
+ * Canonical text (what `Number()` can parse) for a grouped-number input's raw
+ * typed text — this is what `setValue` receives on every keystroke (contract
+ * decision 2: the input holds grouped text only while unfocused; `data`
+ * always holds canonical numerics). Returns the INPUT UNCHANGED when it can't
+ * produce a parseable result — validation flags it from there, same as an
+ * unformatted number field today.
+ *
+ * Derives the locale's group/decimal marks via
+ * `Intl.NumberFormat(locale).formatToParts(1234567.8)`, then:
+ * - strips group separators — several locales (fr-FR among them) use
+ *   U+00A0/U+202F no-break spaces, so any whitespace-class character is
+ *   accepted as a group separator whenever the locale's own is whitespace;
+ * - maps the locale decimal mark to ".";
+ * - ALWAYS also accepts "." as a decimal mark regardless of locale — see
+ *   {@link resolveAmbiguousGrouping} for the locale families where a "." or
+ *   "," group separator collides with a decimal reading (a "," group run
+ *   that isn't exact 3-digit chunking reads as a decimal, so "12,5" under a
+ *   comma-grouping locale is 12.5, never a silently-stripped 125);
+ * - preserves a leading minus;
+ * - preserves partial typing states ("1234." stays "1234." — `Number()` can
+ *   still parse it, and rewriting mid-keystroke fights the respondent).
+ *
+ * Empty/whitespace input and a missing `Intl` both return the input as-is.
+ */
+declare function parseGroupedNumber(text: string, locale?: string): string;
+/**
+ * Keystroke-level filter for a formatted number input's raw typed text (the
+ * input-quality contract's "optional future: React Aria-style
+ * `isValidPartialNumber` keystroke filter", `docs/decisions/input-quality.md`).
+ * Permissive on separator PLACEMENT — {@link parseGroupedNumber} and server
+ * validation own semantics — this only blocks characters or counts that can
+ * never resolve to a number: letters and other symbols, a non-leading "-",
+ * or more than one decimal mark.
+ *
+ * Reuses {@link parseGroupedNumber}'s locale-mark derivation
+ * (`Intl.NumberFormat(locale).formatToParts`) and its two special cases: a
+ * whitespace-class group separator accepts ANY whitespace character, and
+ * where "." is itself the locale's group separator (the de-DE family), "."
+ * is unlimited and only the locale's real decimal mark is capped at one.
+ *
+ * A candidate is validated as a WHOLE string, never character-by-character —
+ * a bad paste is rejected in full, not trimmed down to its valid prefix
+ * (React Aria's behavior). `Intl`-absent falls back to a minimal
+ * digits/"."/"," character class (the leading-"-" rule still applies, since
+ * it needs no locale data).
+ */
+declare function isValidPartialNumberText(text: string, locale?: string): boolean;
+
 /**
  * Lightweight, dependency-free phone metadata + helpers powering the SDK's
  * phone field. Deliberately small: it carries enough to render a country
@@ -546,11 +753,18 @@ declare function formatAnswer(field: Field, value: FieldValue): string;
  * validation + canonical normalization happen server-side with full
  * libphonenumber data (bundle size is irrelevant there), so this stays lean and
  * the stored value is always E.164.
+ *
+ * Coverage is every ITU dial code (~all of ISO 3166-1): 70 curated entries
+ * below carry full formatting metadata; every other country is packed
+ * "iso2+dialCode" data with no metadata (formatNational/isPossiblePhone fall
+ * back to grouping-in-3s / plain E.164 possibility). Names are resolved at
+ * runtime via Intl.DisplayNames — zero hardcoded English name literals.
  */
 interface PhoneCountry {
     /** ISO 3166-1 alpha-2, uppercase ("US"). Also drives the flag emoji. */
     iso2: string;
-    /** Display name ("United States"). */
+    /** Localized display name, resolved via `Intl.DisplayNames` (falls back
+     *  to the iso2 code when that API is unavailable). */
     name: string;
     /** Country calling code without the "+" ("1", "44", "33"). */
     dialCode: string;
@@ -561,8 +775,22 @@ interface PhoneCountry {
     /** Example national number (digits only) for the input placeholder. */
     example: string;
 }
-/** Curated country metadata, ordered for the picker (broad coverage). */
+/**
+ * Every known phone country: the 70 curated entries (rich metadata) then
+ * every other ITU dial code (name + dial code only). Order is NOT display
+ * order (see PHONE_PICKER_COUNTRIES) — it's the tie-break priority
+ * `countryByDialCode` resolves shared codes with, preserved so growing this
+ * list from 70 to ~240 doesn't change how any of the original 70 resolve.
+ */
 declare const PHONE_COUNTRIES: PhoneCountry[];
+/**
+ * PHONE_COUNTRIES reordered for a picker UI: localized name, Intl.Collator-
+ * compared (falls back to iso2 order without Intl.Collator). Kept separate
+ * from PHONE_COUNTRIES, whose order countryByDialCode depends on for
+ * curated-first tie-breaking — sorting by name would flip those ties (e.g.
+ * "Canada" before "United States" would flip which one "+1…" resolves to).
+ */
+declare const PHONE_PICKER_COUNTRIES: PhoneCountry[];
 /** Flag emoji from an ISO-3166 alpha-2 code (regional-indicator letters). */
 declare function flagEmoji(iso2: string): string;
 declare function countryByIso(iso2: string | undefined): PhoneCountry | undefined;
@@ -576,19 +804,60 @@ declare function formatNational(country: PhoneCountry | undefined, national: str
 /** Assemble the canonical E.164 value from a country + national digits. */
 declare function toE164(country: PhoneCountry, national: string): string;
 interface ParsedPhone {
-    /** Best-guess country, if the dial code matched one we know. */
+    /** Best-guess country, if the dial code matched one we know. Always unset
+     *  while `pending`. */
     country?: PhoneCountry;
-    /** National significant digits (dial code stripped). */
+    /** National significant digits: dial code stripped once a country is
+     *  known, otherwise every digit typed after "+" (or all digits, with no
+     *  "+" and no fallback). */
     national: string;
     /** Canonical E.164 ("+…"), or "" if there were no digits. */
     e164: string;
+    /**
+     * True for a "+"-prefixed value that hasn't resolved a country: no digits
+     * at all ("+"), digits that prefix a real dial code without completing
+     * one ("+4"), or digits identical to `ParsePhoneOptions.previousDigits` —
+     * a bare "+" just prepended to unchanged, stale digits.
+     *
+     * `national`/`e164` still carry the typed digits (a caller that ignores
+     * `pending` degrades gracefully). The renderer should hold off committing
+     * a stored value while pending, and redisplay `raw` verbatim instead of
+     * `formatNational(country, national)` — there's no country to format
+     * against yet, and reformatting a bare "+" into "" is the corruption this
+     * field exists to prevent.
+     */
+    pending?: boolean;
+    /** The trimmed input, verbatim. Set only when `pending`. */
+    raw?: string;
+}
+interface ParsePhoneOptions {
+    /**
+     * National digits already in the field before this edit (dial code
+     * already stripped — the same shape `parsePhone` returns as `national`).
+     * Lets `parsePhone` recognize a bare "+" just prepended to unchanged
+     * digits and stay `pending` instead of resolving a country from a
+     * coincidental prefix match: without this hint, stale digits from a
+     * previous, unrelated number always resolve a country the instant "+"
+     * lands in front of them (an old "5551234" would silently become
+     * Brazilian the moment "+" is typed, since "55" is Brazil's dial code).
+     * Pass the pre-edit digits on every keystroke; once they actually change,
+     * resolution proceeds normally on the next call.
+     */
+    previousDigits?: string;
 }
 /**
  * Parse a stored/typed value into country + national + E.164. Accepts E.164
  * ("+4915123456789"), a bare international number, or — with `fallback` — a
  * national number typed without a dial code.
+ *
+ * See `ParsedPhone.pending`/`ParsePhoneOptions.previousDigits` for the
+ * pending-international-entry contract: a "+"-prefixed value that doesn't
+ * resolve a dial code (incl. a lone "+") returns pending instead of
+ * silently reverting to `fallback` with an emptied value, and
+ * `previousDigits` stops stale leftover digits from resolving a country
+ * they never meant to represent, just because "+" was prepended.
  */
-declare function parsePhone(value: string, fallback?: PhoneCountry): ParsedPhone;
+declare function parsePhone(value: string, fallback?: PhoneCountry, opts?: ParsePhoneOptions): ParsedPhone;
 /**
  * Cheap "could this be a real number?" check used for inline feedback. Length
  * only — never claims more than it knows; the server does authoritative
@@ -626,8 +895,10 @@ declare function createEmptyForm(title?: string): FormSchema;
  * defaults — the model only ever supplies the human-meaningful parts.
  */
 /**
- * Field kinds the generator may use. Excludes hidden/custom/signature: the
- * first two are code-only concerns and signature is too niche to draft well.
+ * Field kinds the generator may use. Excludes hidden/custom/signature (the
+ * first two are code-only concerns and signature is too niche to draft well)
+ * and calculated (an LLM can't reliably wire a calc AST to stable field ids —
+ * owners add calculations deliberately, in the builder or in code).
  */
 declare const DRAFT_KINDS: readonly BlockKind[];
 /** The LLM-friendly intermediate shape. Everything optional but `kind`. */
@@ -711,7 +982,7 @@ interface PublishedForm {
     /**
      * Whether a submission would be accepted right now. Absent on older servers
      * — renderers must then keep today's behavior. When false, the default
-     * renderers show the not-open overlay instead of a fillable form.
+     * renderers show the not-open state instead of a fillable form.
      */
     accepting?: boolean;
     /**
@@ -725,6 +996,9 @@ interface PublishedForm {
     /** Whether new file uploads can start right now. Absent on older servers is
      * treated as available; this never changes whether ordinary answers submit. */
     uploadsAvailable?: boolean;
+    /** Server-owned per-file ceiling for the active storage lane. Renderers use
+     * the lower of this and the field's configured maxFileSizeMb. */
+    uploadFileSizeLimitMb?: number;
     /** Workspace branding state — absent means show the badge (default). */
     branding?: FormBranding;
     /** Human-verification challenge to render before submit, when the form
@@ -881,7 +1155,7 @@ interface SyncFormResult {
     /**
      * Whether a submission would be accepted right now. Absent on older servers
      * — renderers must then keep today's behavior. When false, the default
-     * renderers show the not-open overlay instead of a fillable form.
+     * renderers show the not-open state instead of a fillable form.
      */
     accepting?: boolean;
     /**
@@ -896,6 +1170,9 @@ interface SyncFormResult {
      * response acceptance so a completed file can still be submitted after the
      * workspace reaches its upload cap. Absent on older servers means available. */
     uploadsAvailable?: boolean;
+    /** Server-owned per-file ceiling for the active storage lane. Renderers use
+     * the lower of this and the field's configured maxFileSizeMb. */
+    uploadFileSizeLimitMb?: number;
     /**
      * Server-authoritative live snapshot. Present when the incoming code schema
      * is not the version respondents may submit against yet.
@@ -1102,7 +1379,9 @@ interface FormControllerOptions {
     getHoneypot?: () => string;
     /**
      * @internal Let preview page navigation move forward without validating the
-     * current page. Submission still validates, and renderers must not use this
+     * current page. Submission still validates every answerable field; a
+     * transportless preview ignores required file-upload fields because its
+     * disabled picker cannot possibly satisfy them. Renderers must not use this
      * option to change visitor-facing behavior such as branding.
      */
     skipValidation?: boolean;
@@ -1280,13 +1559,35 @@ interface AutoSubmitContext {
 }
 declare function shouldAutoSubmit(field: Field, value: FieldValue, ctx: AutoSubmitContext): boolean;
 
+/**
+ * Pure keyboard-navigation math for a roving-tabindex radiogroup (choice
+ * radios, rating, linear_scale, matrix rows) — shared by both renderers so
+ * the arrow/Home/End handling isn't duplicated and can't drift (audit
+ * P2.3: today's `radiogroupKeyDown`/`bindRadioKeys` copies wrap at the
+ * extremes, have no Home/End, and are RTL-blind).
+ *
+ * No DOM/framework dependency: given the pressed key, the currently active
+ * index, and the option count, this returns the new index to select and
+ * focus, or `null` when `key` isn't a navigation key (the caller falls
+ * through to its own handling, e.g. Space/Enter selection).
+ *
+ * `index` is expected in range (`0`..`length-1`, e.g. from a roving-tabindex
+ * helper that already normalizes "nothing selected" to `0` — matching both
+ * renderers' existing `rovingIndex`). Out-of-range input is still handled
+ * safely: the result is clamped to `[0, length-1]` the same as any other
+ * step, with no special-casing for negative or overflowing starting indexes.
+ */
+declare function radioGroupStep(key: string, index: number, length: number, opts?: {
+    rtl?: boolean;
+}): number | null;
+
 /**
  * The styling contract, shared by every renderer: named slots a consumer can
  * attach classes to, and data-* attributes that expose state so utility CSS
  * (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", "turnstile"];
+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", "calculated"];
 type FilloSlot = (typeof FILLO_SLOTS)[number];
 /** data-* names emitted alongside the stable fillo-* classes. */
 declare const FILLO_DATA_ATTRS: {
@@ -1371,6 +1672,26 @@ declare const FILLO_THEME_VARS: readonly [{
 }, {
     readonly var: "--fillo-primary-contrast";
 }];
+/**
+ * Infer `colorScheme` for a `FormTheme` with `background` AND `text` set
+ * but no explicit `colorScheme`, from the background's WCAG relative
+ * luminance — fixes the foot-gun where `theme={{background, text}}` alone
+ * left the light palette's muted/border/control-bg/error/primary-contrast
+ * tokens in place, reading as near-white-on-white (≈1.10:1) on a dark
+ * author-chosen background.
+ *
+ * Explicit `colorScheme` always wins (returned unchanged). Only one of
+ * `background`/`text` set, neither set, or a non-`#rgb`/`#rrggbb`
+ * `background` also pass through unchanged — no inference.
+ *
+ * Returns a `FormTheme`, not just the scheme, so a renderer can drop this
+ * in ahead of its existing code with no other change:
+ * `const safeTheme = resolveThemeAppearance(normalizeFormTheme(theme));`
+ * then read `.colorScheme`/`.primary`/… exactly as today — inferred and
+ * explicit schemes cascade through the same shipped
+ * `[data-fillo-color-scheme="dark"]` CSS, so no new CSS is needed.
+ */
+declare function resolveThemeAppearance(theme: FormTheme | null): FormTheme | null;
 
 /**
  * The default English validation message for a required field left empty.
@@ -1410,12 +1731,11 @@ interface FilloStrings {
     successMessage: string;
     closed: string;
     notLive: string;
-    /** Title of the not-open overlay card (a draft/storage-blocked form rendered
-     *  in production shows the real form blurred beneath it). */
+    /** Title of the not-open state for a draft/storage-blocked form in production. */
     notOpenTitle: string;
-    /** Body of the not-open overlay card. */
+    /** Body of the not-open state. */
     notOpenBody: string;
-    /** Title of the closed-flavor overlay card (expired/capped workspace);
+    /** Title of the closed-flavor state (expired/capped workspace);
      *  the body reuses `closed`. */
     closedTitle: string;
     /** Fallback when a submit fails without a server message. */
@@ -1438,7 +1758,9 @@ declare const DEFAULT_STRINGS: 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.
+ * the documented all-`string` chrome surface. Also the growth point for new
+ * strings in general — unlike `FilloStrings`, nothing depends on this being
+ * an exhaustively-enumerated, closed set.
  */
 interface FilloFieldStrings {
     /** Validation: a required field was left empty. Mirrors REQUIRED_FIELD_MESSAGE. */
@@ -1450,10 +1772,14 @@ interface FilloFieldStrings {
     alreadyAnswered: string;
     /** Retry control on a failed upload row. */
     uploadRetry: string;
-    /** Dropzone copy when uploads can't run (no client / preview). */
+    /** Dropzone copy when uploads can't run because the form isn't connected. */
     uploadsDisabled: string;
+    /** Dropzone copy for an explicit render-only preview, which never has transport. */
+    uploadsRenderOnly: string;
     /** Dropzone copy when the server temporarily refuses new file sessions. */
     uploadsUnavailable: string;
+    /** An upload request reached the server, but storage could not accept it. */
+    uploadUnavailable: string;
     /** An upload attempt failed with no actionable server message. */
     uploadFailed: string;
     /** Dropzone call to action; `multiple` is true when several files are allowed. */
@@ -1468,6 +1794,24 @@ interface FilloFieldStrings {
     uploadsFailed: (count: number) => string;
     /** Screen-reader status: N uploads completed. */
     filesUploaded: (count: number) => string;
+    /** Live-region announcement while a submit is in flight — for auto-submit
+     *  forms, which have no footer/button to show `submitting` on. */
+    submittingAnnouncement: string;
+    /** Heading on the failed-submit error summary (one `role="alert"` summary
+     *  linking to fields, GOV.UK pattern — replaces N competing per-field alerts). */
+    errorSummaryTitle: string;
+    /** Live-region announcement after a ranking move: "«label», position n of m". */
+    rankingPosition: (label: string, position: number, count: number) => string;
+    /** Live-region announcement once a phone country-picker selection commits
+     *  (focus moves straight to the national input, so nothing else announces it). */
+    phoneCountrySelected: (name: string) => string;
+    /** Live-region announcement of the phone country-picker's filtered result
+     *  count as the respondent types in the search box. */
+    phoneResultsCount: (count: number) => string;
+    /** Accessible name/state for an empty signature canvas. */
+    signatureEmpty: string;
+    /** Accessible name/state for a signed signature canvas. */
+    signatureSigned: string;
 }
 declare const DEFAULT_FIELD_STRINGS: FilloFieldStrings;
 /** Everything the default renderers can localize — chrome + field/validation. */
@@ -1503,6 +1847,9 @@ interface SyncedForm {
     /** Whether new file uploads can start right now. Independent from response
      * acceptance; absent on older servers means available. */
     uploadsAvailable?: boolean;
+    /** Server-owned per-file ceiling for the active storage lane. Renderers use
+     * the lower of this and the field's configured maxFileSizeMb. */
+    uploadFileSizeLimitMb?: number;
     /** Server-authoritative live snapshot when local code is not live yet. */
     resolvedSchema?: FormSchema;
     resolvedTheme?: FormTheme | null;
@@ -1711,4 +2058,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 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, isBuildTimeDevEnv, isCodeForm, isField, isFilloError, isLikelyDevEnv, 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 };
+export { type AutoSubmitContext, BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type CalcExpr, type CalculatedField, 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_CALC_MIN_SDK_VERSION, 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_PICKER_COUNTRIES, PHONE_POPOVER_VIEWPORT_GAP, type ParagraphBlock, type ParsePhoneOptions, 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, computeCalculated, conditionsMet, contentHash, countryByDialCode, countryByIso, countryByTimeZone, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, evaluateCalc, flagEmoji, formSchemasEqual, formatAnswer, formatGroupedNumber, formatNational, isAutoSubmitBlock, isBlockVisible, isBuildTimeDevEnv, isCodeForm, isField, isFilloError, isLikelyDevEnv, isPossiblePhone, isTerminalPage, isValidPartialNumberText, localeForNotation, needsExplicitSubmit, normalizeFormSchema, normalizeFormTheme, normalizeSettings, parseGroupedNumber, parsePhone, pipeBlock, positionPhonePopover, prefillFromParams, provisionWorkspace, radioGroupStep, reachableFieldIds, reachableFields, reachablePageIds, reachablePageSequence, resolveNextPage, resolveSlotClass, resolveStrings, resolveText, resolveThemeAppearance, responseScopeValue, schemaFromJsx, sha1Base64, shouldAutoSubmit, slotClass, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields, visiblePageBlocks, when };