@incodetech/web 2.2.0-rc.1 → 2.2.0-rc.2

package/dist/types/id-selfie-flow.d.ts

@@ -129,15 +129,17 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
 };
 
 /**
- * Per-instance asset/animation overrides for a single mounted SDK module.
+ * Per-instance overrides for a single mounted SDK module.
  *
  * These ride on the module's `config` prop and are published once at the
  * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
- * reads them via {@link useInstanceOverrides} without any prop drilling.
+ * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
+ * any prop drilling.
  */
 declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    spinner?: SpinnerPresentation;
 };
 
 declare type LottieAnimationData = {
@@ -149,6 +151,30 @@ declare type LottieAnimationData = {
     h: number;
 };
 
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
+    size?: SpinnerSize;
+};
+
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
+declare type SpinnerSize = 'small' | 'medium' | 'large';
+
 /** An SVG imported as a Preact component (the `?react` import shape). */
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 

package/dist/types/id-verification.d.ts

@@ -114,15 +114,17 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
 };
 
 /**
- * Per-instance asset/animation overrides for a single mounted SDK module.
+ * Per-instance overrides for a single mounted SDK module.
  *
  * These ride on the module's `config` prop and are published once at the
  * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
- * reads them via {@link useInstanceOverrides} without any prop drilling.
+ * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
+ * any prop drilling.
  */
 declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    spinner?: SpinnerPresentation;
 };
 
 declare type LottieAnimationData = {
@@ -134,6 +136,30 @@ declare type LottieAnimationData = {
     h: number;
 };
 
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
+    size?: SpinnerSize;
+};
+
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
+declare type SpinnerSize = 'small' | 'medium' | 'large';
+
 /** An SVG imported as a Preact component (the `?react` import shape). */
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 

package/dist/types/id.d.ts

@@ -117,15 +117,17 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
 };
 
 /**
- * Per-instance asset/animation overrides for a single mounted SDK module.
+ * Per-instance overrides for a single mounted SDK module.
  *
  * These ride on the module's `config` prop and are published once at the
  * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
- * reads them via {@link useInstanceOverrides} without any prop drilling.
+ * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
+ * any prop drilling.
  */
 declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    spinner?: SpinnerPresentation;
 };
 
 declare type LottieAnimationData = {
@@ -137,6 +139,30 @@ declare type LottieAnimationData = {
     h: number;
 };
 
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
+    size?: SpinnerSize;
+};
+
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
+declare type SpinnerSize = 'small' | 'medium' | 'large';
+
 /** An SVG imported as a Preact component (the `?react` import shape). */
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 

package/dist/types/identity-reuse.d.ts

@@ -114,15 +114,17 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
 };
 
 /**
- * Per-instance asset/animation overrides for a single mounted SDK module.
+ * Per-instance overrides for a single mounted SDK module.
  *
  * These ride on the module's `config` prop and are published once at the
  * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
- * reads them via {@link useInstanceOverrides} without any prop drilling.
+ * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
+ * any prop drilling.
  */
 declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    spinner?: SpinnerPresentation;
 };
 
 declare type LottieAnimationData = {
@@ -134,6 +136,30 @@ declare type LottieAnimationData = {
     h: number;
 };
 
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
+    size?: SpinnerSize;
+};
+
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
+declare type SpinnerSize = 'small' | 'medium' | 'large';
+
 /** An SVG imported as a Preact component (the `?react` import shape). */
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 

package/dist/types/index.d.ts

@@ -147,6 +147,47 @@ declare type SetupOptions = {
     theme?: ThemeSetup;
 };
 
+/**
+ * The presentation fields plus the legacy inline copy accepted by
+ * `<incode-flow>` / `<incode-workflow>`.
+ */
+export declare type SpinnerConfig = SpinnerPresentation & {
+    /**
+     * @deprecated Set loader copy via i18n translations (`loadingCircle.holdOn`).
+     * TODO(2.3.0): remove.
+     */
+    title?: string;
+    /**
+     * @deprecated Set loader copy via i18n translations (`loadingCircle.validating`).
+     * TODO(2.3.0): remove.
+     */
+    subtitle?: string;
+};
+
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+export declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
+    size?: SpinnerSize;
+};
+
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+export declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
+export declare type SpinnerSize = 'small' | 'medium' | 'large';
+
 /** An SVG imported as a Preact component (the `?react` import shape). */
 export declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 
@@ -166,6 +207,11 @@ export declare type UiConfig = {
     hideFooterBranding?: boolean;
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    /**
+     * Global loader presentation. Copy stays in i18n — see
+     * {@link SpinnerPresentation}.
+     */
+    spinner?: SpinnerPresentation;
 };
 
 export { }

package/dist/types/phone.d.ts

@@ -111,15 +111,17 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
 };
 
 /**
- * Per-instance asset/animation overrides for a single mounted SDK module.
+ * Per-instance overrides for a single mounted SDK module.
  *
  * These ride on the module's `config` prop and are published once at the
  * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
- * reads them via {@link useInstanceOverrides} without any prop drilling.
+ * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
+ * any prop drilling.
  */
 declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    spinner?: SpinnerPresentation;
 };
 
 declare type LottieAnimationData = {
@@ -140,6 +142,30 @@ export declare const Phone: FC<Omit<PhoneProps, "config"> & {
  */
 declare type PhoneProps = IncodeModuleProps<PhoneConfig, void, PhoneManager>;
 
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
+    size?: SpinnerSize;
+};
+
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
+declare type SpinnerSize = 'small' | 'medium' | 'large';
+
 /** An SVG imported as a Preact component (the `?react` import shape). */
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 

package/dist/types/qe-signature.d.ts

@@ -111,15 +111,17 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
 };
 
 /**
- * Per-instance asset/animation overrides for a single mounted SDK module.
+ * Per-instance overrides for a single mounted SDK module.
  *
  * These ride on the module's `config` prop and are published once at the
  * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
- * reads them via {@link useInstanceOverrides} without any prop drilling.
+ * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
+ * any prop drilling.
  */
 declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    spinner?: SpinnerPresentation;
 };
 
 declare type LottieAnimationData = {
@@ -137,6 +139,30 @@ export declare const QeSignature: FC<Omit<QeSignatureModuleProps, "config"> & {
 
 declare type QeSignatureModuleProps = IncodeModuleProps<QeSignatureConfig, void, QeSignatureManager>;
 
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
+    size?: SpinnerSize;
+};
+
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
+declare type SpinnerSize = 'small' | 'medium' | 'large';
+
 /** An SVG imported as a Preact component (the `?react` import shape). */
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 

package/dist/types/selfie.d.ts

@@ -111,15 +111,17 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
 };
 
 /**
- * Per-instance asset/animation overrides for a single mounted SDK module.
+ * Per-instance overrides for a single mounted SDK module.
  *
  * These ride on the module's `config` prop and are published once at the
  * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
- * reads them via {@link useInstanceOverrides} without any prop drilling.
+ * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
+ * any prop drilling.
  */
 declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    spinner?: SpinnerPresentation;
 };
 
 declare type LottieAnimationData = {
@@ -137,6 +139,30 @@ export declare const Selfie: FC<Omit<SelfieProps, "config"> & {
 
 declare type SelfieProps = IncodeModuleProps<SelfieConfig, void, SelfieManager>;
 
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
+    size?: SpinnerSize;
+};
+
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
+declare type SpinnerSize = 'small' | 'medium' | 'large';
+
 /** An SVG imported as a Preact component (the `?react` import shape). */
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 

package/dist/types/signature.d.ts

@@ -111,15 +111,17 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
 };
 
 /**
- * Per-instance asset/animation overrides for a single mounted SDK module.
+ * Per-instance overrides for a single mounted SDK module.
  *
  * These ride on the module's `config` prop and are published once at the
  * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
- * reads them via {@link useInstanceOverrides} without any prop drilling.
+ * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
+ * any prop drilling.
  */
 declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    spinner?: SpinnerPresentation;
 };
 
 declare type LottieAnimationData = {
@@ -137,6 +139,30 @@ export declare const Signature: FC<Omit<SignatureProps, "config"> & {
 
 declare type SignatureProps = IncodeModuleProps<SignatureConfig, void, SignatureManager>;
 
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
+    size?: SpinnerSize;
+};
+
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
+declare type SpinnerSize = 'small' | 'medium' | 'large';
+
 /** An SVG imported as a Preact component (the `?react` import shape). */
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 

package/dist/types/video-selfie.d.ts

@@ -110,15 +110,17 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
 };
 
 /**
- * Per-instance asset/animation overrides for a single mounted SDK module.
+ * Per-instance overrides for a single mounted SDK module.
  *
  * These ride on the module's `config` prop and are published once at the
  * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
- * reads them via {@link useInstanceOverrides} without any prop drilling.
+ * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
+ * any prop drilling.
  */
 declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    spinner?: SpinnerPresentation;
 };
 
 declare type LottieAnimationData = {
@@ -130,6 +132,30 @@ declare type LottieAnimationData = {
     h: number;
 };
 
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
+    size?: SpinnerSize;
+};
+
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
+declare type SpinnerSize = 'small' | 'medium' | 'large';
+
 /** An SVG imported as a Preact component (the `?react` import shape). */
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 

package/dist/types/watchlist.d.ts

@@ -111,15 +111,17 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
 };
 
 /**
- * Per-instance asset/animation overrides for a single mounted SDK module.
+ * Per-instance overrides for a single mounted SDK module.
  *
  * These ride on the module's `config` prop and are published once at the
  * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
- * reads them via {@link useInstanceOverrides} without any prop drilling.
+ * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
+ * any prop drilling.
  */
 declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    spinner?: SpinnerPresentation;
 };
 
 declare type LottieAnimationData = {
@@ -131,6 +133,30 @@ declare type LottieAnimationData = {
     h: number;
 };
 
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
+    size?: SpinnerSize;
+};
+
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
+declare type SpinnerSize = 'small' | 'medium' | 'large';
+
 /** An SVG imported as a Preact component (the `?react` import shape). */
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 

package/dist/types/workflow.d.ts

@@ -126,15 +126,17 @@ export declare const IncodeWorkflow: FC<IncodeWorkflowProps>;
 declare type IncodeWorkflowProps = IncodeModuleProps<WorkflowComponentConfig, FinishStatus>;
 
 /**
- * Per-instance asset/animation overrides for a single mounted SDK module.
+ * Per-instance overrides for a single mounted SDK module.
  *
  * These ride on the module's `config` prop and are published once at the
  * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
- * reads them via {@link useInstanceOverrides} without any prop drilling.
+ * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
+ * any prop drilling.
  */
 declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    spinner?: SpinnerPresentation;
 };
 
 declare type LottieAnimationData = {
@@ -175,12 +177,45 @@ declare type SelfLoadingWorkflowRuntimeConfig = WorkflowBaseConfig & SelfLoading
     interviewId?: never;
 };
 
-declare type SpinnerConfig = {
+/**
+ * The presentation fields plus the legacy inline copy accepted by
+ * `<incode-flow>` / `<incode-workflow>`.
+ */
+declare type SpinnerConfig = SpinnerPresentation & {
+    /**
+     * @deprecated Set loader copy via i18n translations (`loadingCircle.holdOn`).
+     * TODO(2.3.0): remove.
+     */
     title?: string;
+    /**
+     * @deprecated Set loader copy via i18n translations (`loadingCircle.validating`).
+     * TODO(2.3.0): remove.
+     */
     subtitle?: string;
+};
+
+/**
+ * Host-facing loader presentation, settable globally via
+ * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
+ *
+ * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
+ * which keeps it localizable — a literal string here would freeze in whatever
+ * language the host typed it in when the user switches language mid-flow — and
+ * leaves one source of truth for user-facing strings.
+ */
+declare type SpinnerPresentation = {
+    renderMode?: SpinnerRenderMode;
     size?: SpinnerSize;
 };
 
+/**
+ * Which parts of a loader render.
+ *
+ * An enum rather than a pair of booleans so the meaningless fourth state —
+ * neither icon nor text, i.e. a blank screen — is unrepresentable.
+ */
+declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';
+
 declare type SpinnerSize = 'small' | 'medium' | 'large';
 
 /** An SVG imported as a Preact component (the `?react` import shape). */
@@ -216,6 +251,12 @@ declare type WorkflowBaseConfig = {
     disableDashboardTheme?: boolean;
     wasmConfig?: WasmConfig | false;
     spinnerConfig?: SpinnerConfig;
+    /**
+     * Per-instance loader presentation for this workflow and its modules.
+     * Overrides the global `setup({ uiConfig: { spinner } })` value. Copy stays
+     * in i18n.
+     */
+    spinner?: SpinnerPresentation;
     customModuleCallback?: CustomModuleCallback;
     /** Whether the device is a desktop. Determines desktop-to-mobile redirect injection. Defaults to true. */
     isDesktop?: boolean;