@usefillo/core 0.9.0 → 0.11.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,14 @@ 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;
+    /** Locale-aware thousand separators in the SDK input. Display-only;
+     *  never reaches the wire, the server, or exports. */
+    notation?: "grouped";
 }
 interface ChoiceField extends BaseField {
     kind: "select" | "multi_select" | "dropdown";
@@ -129,6 +137,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 +209,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 +559,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 +623,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 +659,76 @@ 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:
+ * "grouped"` input (design contract: docs/decisions/number-formatting.md).
+ * Both helpers are pure, side-effect-free, and DOM-free, so the same code
+ * runs in @usefillo/react, @usefillo/dom, and Node. Both are strictly
+ * display-only — grouping never touches validation, canonical storage, or
+ * the wire (contract decision 2) — and both degrade to canonical text
+ * instead of throwing when `Intl` is unavailable.
+ */
+/**
+ * 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 resolveDotGroup} for the one locale family where that collides
+ *   with "." also being the group separator;
+ * - 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 +736,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 +758,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 +787,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 +878,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`. */
@@ -708,6 +962,26 @@ interface PublishedForm {
     theme: FormTheme | null;
     /** True when the server says the form cannot accept responses. */
     closed?: boolean;
+    /**
+     * 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 state instead of a fillable form.
+     */
+    accepting?: boolean;
+    /**
+     * Companion to `accepting` — present only when it is false.
+     * `draft`: not published yet; `expired`/`capped`: the unclaimed preview
+     * workspace hit its time window or response cap. Storage reasons may be
+     * returned for drafts or by older servers; published upload readiness is
+     * represented independently by `uploadsAvailable`.
+     */
+    acceptingReason?: "draft" | "expired" | "capped" | "storage_required" | "storage_full";
+    /** 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
@@ -861,6 +1135,27 @@ interface SyncFormResult {
     status?: "draft" | "published";
     /** Changes were staged as a draft for a human to publish. */
     staged?: boolean;
+    /**
+     * 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 state instead of a fillable form.
+     */
+    accepting?: boolean;
+    /**
+     * Companion to `accepting` — present only when it is false.
+     * `draft`: not published yet; `expired`/`capped`: the unclaimed preview
+     * workspace hit its time window or response cap; `storage_required`: the
+     * form needs a connected storage destination before it can go live;
+     * `storage_full`: Fillo's temporary upload allowance is exhausted.
+     */
+    acceptingReason?: "draft" | "expired" | "capped" | "storage_required" | "storage_full";
+    /** Whether new file uploads can start right now. This is independent from
+     * 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.
@@ -872,7 +1167,23 @@ interface SyncFormResult {
         code: string;
         message: string;
     };
+    /**
+     * Human-readable storage heads-up for the form owner. This can be advisory
+     * while uploads and responses remain available; never use it to gate UI.
+     */
     warning?: string;
+    /**
+     * Machine-readable owner advisory for `warning`. Hard unavailability uses
+     * `"storage_required"`; transit threshold advisories use distinct codes.
+     * Point the human at `warningUrl`; use `uploadsAvailable`, not this field,
+     * to gate new file controls.
+     */
+    warningCode?: string;
+    /**
+     * Absolute dashboard URL where a human connects a storage destination.
+     * Present whenever `warningCode` is.
+     */
+    warningUrl?: string;
 }
 declare class FilloClient {
     /** Server origin this client targets, normalized (no trailing slash). */
@@ -1070,6 +1381,15 @@ interface FormControllerOptions {
      * runs; failure sets `submitError` and the respondent can retry.
      */
     resolveFormId?: () => Promise<string>;
+    /**
+     * Surface the REAL {@link resolveFormId} failure (message + machine code)
+     * in `submitError` instead of the respondent-safe "This form is
+     * unavailable." fallback. Dev chrome only: renderers set it from the same
+     * gate as their other developer surfaces (preview prop / dev environment),
+     * so production visitors never see integration details such as keys,
+     * origins, or deployment commands.
+     */
+    verboseResolutionErrors?: boolean;
     /**
      * Host-app account context (identify()): who is filling this form, by your
      * own user id. Sent with the submission and recorded as an unverified
@@ -1220,13 +1540,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: {
@@ -1311,6 +1653,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.
@@ -1350,6 +1712,13 @@ interface FilloStrings {
     successMessage: string;
     closed: string;
     notLive: string;
+    /** Title of the not-open state for a draft/storage-blocked form in production. */
+    notOpenTitle: string;
+    /** Body of the not-open state. */
+    notOpenBody: string;
+    /** Title of the closed-flavor state (expired/capped workspace);
+     *  the body reuses `closed`. */
+    closedTitle: string;
     /** Fallback when a submit fails without a server message. */
     submitFailed: string;
     loadFailedNotFound: string;
@@ -1370,7 +1739,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. */
@@ -1384,6 +1755,10 @@ interface FilloFieldStrings {
     uploadRetry: string;
     /** Dropzone copy when uploads can't run (no client / preview). */
     uploadsDisabled: 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. */
@@ -1398,6 +1773,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. */
@@ -1419,6 +1812,23 @@ interface SyncedForm {
     status?: "draft" | "published";
     /** Changes were staged as a draft for a human to publish. */
     staged?: boolean;
+    /** Whether a submission would be accepted right now. Absent on older
+     *  servers — renderers must then keep the status-based behavior. */
+    accepting?: boolean;
+    /**
+     * Companion to `accepting` — present only when it is false. `draft`: not
+     * published yet; `expired`/`capped`: the unclaimed preview workspace hit its
+     * time window or response cap; `storage_required`: the form needs a
+     * connected storage destination before it can go live; `storage_full`:
+     * Fillo's temporary upload allowance is exhausted.
+     */
+    acceptingReason?: "draft" | "expired" | "capped" | "storage_required" | "storage_full";
+    /** 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;
@@ -1428,6 +1838,15 @@ interface SyncedForm {
         message: string;
     };
     warning?: string;
+    /**
+     * Machine-readable owner advisory for `warning`. Hard unavailability uses
+     * `"storage_required"`; advisory thresholds use distinct codes. Use
+     * `uploadsAvailable`, not this field, to decide whether an upload may start.
+     */
+    warningCode?: string;
+    /** Absolute dashboard URL where a human connects a storage destination.
+     *  Present whenever `warningCode` is. */
+    warningUrl?: string;
 }
 /**
  * A form whose structure lives in user code. Development and explicit
@@ -1543,6 +1962,37 @@ interface WhenBuilder {
 }
 declare function when(fieldId: string): WhenBuilder;
 
+/**
+ * The build-time half of the dev check: `NODE_ENV` alone, no hostname
+ * inspection. It evaluates identically on the server and in the browser for
+ * the same bundle, which is what SSR hydration needs — the server has no
+ * `window`, so a hostname-aware check would disagree with the client's first
+ * paint. Renderers use this as the server/hydration snapshot and upgrade to
+ * {@link isLikelyDevEnv} after hydration.
+ */
+declare function isBuildTimeDevEnv(): boolean;
+/**
+ * Whether this runtime looks like local development, so renderers can show
+ * actionable dev surfaces (draft banner, missing-client warning, local schema
+ * render) instead of the deliberately quiet production states.
+ *
+ * The build-time `NODE_ENV` signal alone misses real local setups: the
+ * standalone `<script>` bundle has no `process` at all (so it always read as
+ * production), `vite preview` / `next start` serve a production build on
+ * localhost, and some bundlers never define `NODE_ENV`. So a browser whose
+ * hostname is localhost/loopback also counts as development. Real
+ * deployments keep production semantics because they serve from real
+ * hostnames — see {@link isLocalHostname} for why mDNS `*.local` names and
+ * private-LAN addresses are deliberately excluded.
+ *
+ * SSR-safe to CALL (with no `window`, only the `NODE_ENV` check applies), but
+ * NOT hydration-safe for render output: the server pass can't see the page
+ * hostname, so under `next start` on localhost it disagrees with the client.
+ * Render paths should hydrate from {@link isBuildTimeDevEnv} and upgrade to
+ * this check after hydration (see the React renderer's useIsDevEnv()).
+ */
+declare function isLikelyDevEnv(): boolean;
+
 /**
  * Build initial response data from URL query parameters — Tally-style
  * prefilling. Hidden fields read their configured paramName; every other
@@ -1587,4 +2037,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, 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 };
+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, 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 };