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

package/dist/types/curp-validation.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/document-capture.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/ekyb.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/ekyc.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/electronic-signature.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/email.d.ts

@@ -120,15 +120,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 @@ 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/extensibility.d.ts

@@ -630,15 +630,17 @@ declare type InputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'class' |
 };
 
 /**
- * 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;
 };
 
 export declare function LandscapeBlocker(): VNode | null;
@@ -994,6 +996,9 @@ export declare const SelfieTutorial: ({ manager, ageAssurance }: TutorialProps)
 
 /**
  * Sets global UI configuration defaults for `@incodetech/ui`.
+ *
+ * Replaces (does not merge with) the previous host-supplied config, so omitting
+ * a field clears it. The dashboard theme is held separately and is unaffected.
  */
 export declare function setUiConfig(next: UiConfig): void;
 
@@ -1007,6 +1012,37 @@ declare type SpacerProps = {
 
 export declare const Spinner: FC<SpinnerProps>;
 
+/**
+ * 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;
+};
+
 declare type SpinnerProps = {
     /** Title text to display below the spinner */
     title?: string;
@@ -1029,8 +1065,23 @@ declare type SpinnerProps = {
      * screen reader must not be able to swipe into or hear it behind that prompt.
      */
     presentational?: boolean;
+    /**
+     * Render the title/subtitle without the spinning icon.
+     *
+     * Backs `renderMode: 'textOnly'`, for hosts that animate their own copy and
+     * want no icon competing with it.
+     */
+    hideIcon?: boolean;
 };
 
+/**
+ * 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';
 
 export declare const SuccessIcon: FC<SuccessIconProps>;
@@ -1114,6 +1165,11 @@ export declare type UiConfig = {
     hideFooterBranding?: boolean;
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
+    /**
+     * Global loader presentation. Copy stays in i18n — see
+     * {@link SpinnerPresentation}.
+     */
+    spinner?: SpinnerPresentation;
 };
 
 /**

package/dist/types/face-match.d.ts

@@ -120,15 +120,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 @@ 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/field-comparison.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/fiscal-qr.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/flow.d.ts

@@ -105,6 +105,11 @@ declare type FlowUiConfig = {
     assets?: AssetOverrides;
     /** Per-instance Lottie-animation overrides for this flow. */
     animations?: AnimationOverrides;
+    /**
+     * Per-instance loader presentation for this flow and its modules. Overrides
+     * the global `setup({ uiConfig: { spinner } })` value. Copy stays in i18n.
+     */
+    spinner?: SpinnerPresentation;
 };
 
 /**
@@ -167,15 +172,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 = {
@@ -214,12 +221,45 @@ declare type SelfLoadingFlowRuntimeConfig = FlowBaseConfig & SelfLoadingSessionO
 
 declare type SelfLoadingSessionOptions = Pick<CreateSessionOptions, 'configurationId' | 'externalId' | 'externalCustomerId' | 'customFields' | 'uuid' | 'urlUuid' | 'interviewId' | 'loginHint'>;
 
-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). */