@incodetech/web 2.3.2-rc.4 → 2.4.0-rc.0

package/dist/types/extensibility.d.ts

@@ -1,4 +1,5 @@
 import { ComponentChildren } from 'preact';
+import { CountryCode } from '@incodetech/core/phone-number';
 import { CSSProperties } from 'preact';
 import { FC } from 'preact/compat';
 import { FunctionalComponent } from 'preact';
@@ -11,7 +12,6 @@ import { IdCaptureState } from '@incodetech/core/id';
 import { IdDocumentType } from '@incodetech/core/id';
 import { InputHTMLAttributes } from 'preact';
 import { JSX } from 'preact';
-import { default as LightningIcon } from './lightningIcon.svg?react';
 import { PermissionStatus as PermissionStatus_2 } from '@incodetech/core/camera';
 import { PropsWithoutRef } from 'preact/compat';
 import { Ref } from 'preact';
@@ -19,6 +19,7 @@ import { RefObject } from 'preact';
 import { RefObject as RefObject_2 } from 'preact/compat';
 import { SelfieManager } from '@incodetech/core/selfie';
 import { SelfieState } from '@incodetech/core/selfie';
+import { SessionExpiredError } from '@incodetech/core/session';
 import { SVGProps } from 'preact/compat';
 import { TargetedEvent } from 'preact';
 import { VNode } from 'preact';
@@ -66,7 +67,7 @@ export declare type AssetOverride = string | {
 
 export declare type AssetOverrides = Partial<Record<AssetKey, AssetOverride>>;
 
-export declare const BaseTutorial: ({ className, animationData, title, titleId, subtitle, onContinue, buttonText, disclaimerText, isLoading, secondaryAction, actionsSlot, stopFramePosition, recolor, shouldScaleAnimationContainer, }: BaseTutorialProps) => JSX.Element;
+export declare const BaseTutorial: ({ className, animationData, title, titleId, subtitle, onContinue, buttonText, disclaimerText, isLoading, actionsSlot, stopFramePosition, recolor, shouldScaleAnimationContainer, }: BaseTutorialProps) => JSX.Element;
 
 declare type BaseTutorialProps = {
     className?: string;
@@ -78,12 +79,6 @@ declare type BaseTutorialProps = {
     buttonText: string;
     disclaimerText: string;
     isLoading?: boolean;
-    /** Optional alternative to the primary CTA, rendered as a link below it. */
-    secondaryAction?: {
-        label: string;
-        onClick: () => void;
-        testId?: string;
-    };
     /** Rendered below the primary CTA inside the button stack (e.g. a link action). */
     actionsSlot?: ComponentChildren;
     stopFramePosition?: 'first' | 'middle' | 'last';
@@ -184,11 +179,20 @@ declare type CameraOverlayHeaderProps = {
     className?: string;
     titleId?: string;
     titleRef?: RefObject_2<HTMLHeadingElement>;
+    /**
+     * Defer the title's focus move. A screen that reveals itself with an
+     * animation must keep focus off the heading until the reveal completes —
+     * see the crossfade ownership rule in `.agents/standards/accessibility.md`.
+     * Defaults to `true` (focus on mount), which is what live capture wants.
+     */
+    autoFocusTitle?: boolean;
 };
 
 declare type CameraOverlayProps = {
     children: ComponentChildren;
     className?: string;
+    floatingHelpButton?: FloatingHelpButton;
+    floatingCloseButton?: FloatingCloseButton;
 };
 
 export declare const CameraView: FC<CameraViewProps>;
@@ -223,6 +227,16 @@ declare type CaptureFooterProps = {
     encryptionLabel?: string;
     children?: ComponentChildren;
     hideActions?: boolean;
+    showHelpButton?: boolean;
+    className?: string;
+    inactive?: boolean;
+};
+
+/** Everything the help button needs, independent of where it mounts. */
+declare type CaptureHelpButton = {
+    onOpenHelp: () => void;
+    ariaLabel: string;
+    buttonRef?: Ref<HTMLButtonElement>;
 };
 
 declare type CaptureProps = {
@@ -309,20 +323,20 @@ declare type ChooserProps = {
     }>;
 };
 
-declare type CloseButtonOptions = {
-    show?: boolean;
-    onClose?: () => void;
-    position?: 'left' | 'right';
-    offset?: string;
-    onCancel?: () => void;
-    color?: string;
+/** Close button data, independent of where it mounts. */
+declare type CloseButton = {
+    onQuit: () => void;
+    ariaLabel: string;
 };
 
-declare type CloseButtonOptions_2 = {
+declare type CloseButtonOptions = {
     show?: boolean;
     onClose?: () => void;
 };
 
+/** Corner the close button renders in. Defaults to `topRight`. */
+declare type CloseButtonPosition = 'topRight' | 'topLeft';
+
 export declare const CloseIcon: FC<CloseIconProps>;
 
 declare type CloseIconProps = {
@@ -363,8 +377,6 @@ declare type ConnectionErrorProps = {
 
 export declare const countries: CountryData[];
 
-declare type CountryCode = 'AC' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TA' | 'TC' | 'TD' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'XK' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW';
-
 declare type CountryData = {
     code: CountryCode;
     /** ISO 3166-1 alpha-3 code, for backends that report alpha-3 (e.g. MRZ). */
@@ -466,6 +478,18 @@ declare type FlipAnimationProps = {
     direction: 'toBack' | 'toFront';
 };
 
+/** Close button resolved to a corner — shared by `Page`'s header and the floating overlay control. */
+declare type FloatingCloseButton = CloseButton & {
+    position: CloseButtonPosition;
+};
+
+declare type FloatingHelpButton = CaptureHelpButton & {
+    position: FloatingHelpButtonPosition;
+};
+
+/** Placements that render outside `CaptureFooter`, on the camera overlay. */
+declare type FloatingHelpButtonPosition = 'topRight' | 'topLeft';
+
 export declare const FormField: FC<FormFieldProps>;
 
 declare type FormFieldProps = {
@@ -496,6 +520,13 @@ export declare function getCountryByCallingCode(callingCode: string): CountryDat
 
 export declare function getCountryByCode(code: string | undefined): CountryData | undefined;
 
+/**
+ * Where the capture help button renders. `topLeft`/`topRight` float outside
+ * the footer — the footer's own box only covers the bottom of the screen, so
+ * a top offset inside it would land mid-screen, not near the header.
+ */
+export declare type HelpButtonPosition = 'bottomRight' | 'topRight' | 'topLeft';
+
 export declare const HelpIcon: FC<HelpIconProps>;
 
 declare type HelpIconProps = {
@@ -552,10 +583,16 @@ export declare const IdTutorial: FC<TutorialProps_2>;
  * Wraps UI modules with the standard container. Blocks unsupported browsers
  * and shows a landscape blocker on rotated mobile (excluding iPad).
  */
-export declare function IncodeComponent({ children }: IncodeComponentProps): VNode;
+export declare function IncodeComponent({ children, deferBrowserCheck, }: IncodeComponentProps): VNode;
 
 declare type IncodeComponentProps = {
     children?: ComponentChildren;
+    /**
+     * Skips the browser check here. `<incode-flow>` and `<incode-workflow>` set
+     * it and run the check themselves once their server config has loaded,
+     * because that config owns `disableUnsupportedBrowserScreen` for them.
+     */
+    deferBrowserCheck?: boolean;
 };
 
 /**
@@ -576,6 +613,15 @@ declare type IncodeFinishMeta = {
      * replace the SDK screen. Not a guarantee.
      */
     sdkOwnsTerminalScreen?: boolean;
+    /**
+     * True when the workflow is OAuth2-secured. The OAuth authorization server
+     * owns the redirect back to the client's `redirect_uri`, so the host must not
+     * navigate to `redirectionUrl` itself. A host redirect drops the `error` and
+     * `state` parameters, and the client reads a failed authentication as a
+     * success. The workflow always sets it on finish; treat a missing value as
+     * unknown.
+     */
+    oauth2Secured?: boolean;
 };
 
 export declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TConfigInput = ConfigWithOverrides<TConfig>> = {
@@ -589,7 +635,10 @@ export declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknow
      */
     config?: TConfigInput;
     /**
-     * Optional pre-built manager. When provided, the module does not create or manage the manager lifecycle.
+     * Optional pre-built manager. The host owns its ordinary lifecycle.
+     * Session expiry always stops it to release capture resources, even when
+     * supplied by the host. Create a new manager for a replacement session;
+     * do not reuse the stopped instance in another mounted module.
      */
     manager?: TManager;
     /**
@@ -609,8 +658,10 @@ export declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknow
      * @param moduleErrorCode - Optional machine-readable error code (e.g. a
      *   `FaceErrorCode` such as `NONEXISTENT_CUSTOMER`). Lets an orchestrator
      *   branch on the specific terminal error without parsing the message string.
+     * @param details - Structured session-expiry error with statusCode 401 and
+     *   code/type SESSION_EXPIRED. The first three arguments stay compatible.
      */
-    onError?: (error: string | undefined, errorCode?: number, moduleErrorCode?: string) => void;
+    onError?: ModuleErrorHandler;
 };
 
 declare type InferState<T> = T extends {
@@ -634,7 +685,7 @@ declare type InputComposedProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'i
     helper?: string;
     showErrorIcon?: boolean;
     showHelperIcon?: boolean;
-    closeButton?: CloseButtonOptions_2;
+    closeButton?: CloseButtonOptions;
     rightIcon?: ComponentChildren;
     suppressMessages?: boolean;
     class?: string;
@@ -658,11 +709,18 @@ declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
     spinner?: SpinnerPresentation;
+    /**
+     * `true` hides the unsupported-browser screen for this element; `false`
+     * forces it on. Wins over `setup({ uiConfig })`. When both are omitted, the
+     * session Flow's setting applies. `<incode-flow>` and `<incode-workflow>`
+     * ignore it and always use their server setting.
+     */
+    disableUnsupportedBrowserScreen?: boolean;
 };
 
 export declare function LandscapeBlocker(): VNode | null;
 
-export { LightningIcon }
+export declare const LightningIcon: SvgComponent;
 
 export declare const LockIcon: FC<LockIconProps>;
 
@@ -802,6 +860,8 @@ declare type ModalTitleSectionProps = {
     align?: 'center' | 'left';
 };
 
+declare type ModuleErrorHandler = (message: string | undefined, errorCode?: number, moduleErrorCode?: string, details?: SessionExpiredError) => void;
+
 export declare const OtpInput: FC<OtpInputProps>;
 
 declare type OtpInputProps = {
@@ -852,7 +912,6 @@ declare type PageProps = {
     };
     hideFooterBranding?: boolean;
     hideHeader?: boolean;
-    closeButton?: CloseButtonOptions;
     footerBrandingSlot?: ComponentChildren;
     'data-testid'?: string;
     'data-permission-status'?: string;
@@ -938,6 +997,12 @@ declare type ProgressBarProps = {
     label?: string;
     className?: string;
     labelledById?: string;
+    /**
+     * Also creep the bar forward on its own for a few seconds, in CSS, while
+     * `progress` has not moved yet. The bar shows whichever fill is longer.
+     * Starts after `--progress-bar-simulated-delay` (default 0s).
+     */
+    simulated?: boolean;
 };
 
 export declare const RadioButtonComposed: FunctionalComponent<PropsWithoutRef<RadioButtonComposedProps> & {
@@ -994,6 +1059,16 @@ declare type RadioGroupOption = {
     disabled?: boolean;
 };
 
+/**
+ * How the realtime feedback message (the live capture cues — not aligned, too
+ * blurry, glare, show front, show back) presents itself.
+ *
+ * - `standard` — the full message: Lottie animation beside the copy.
+ * - `minimal` — compact: no animation, copy centred. More legible on small
+ *   screens, where the animation crowds the text out of the frame.
+ */
+export declare type RealtimeFeedbackMessageUIFlavor = 'standard' | 'minimal';
+
 export declare const SearchIcon: FC<SearchIconProps>;
 
 declare type SearchIconProps = {
@@ -1019,7 +1094,7 @@ export declare type SegmentedDateInputProps = Omit<InputComposedProps, 'type' |
 
 export declare const SelfieCapture: FC<CaptureProps>;
 
-export declare const SelfieTutorial: ({ manager, ageAssurance, showManualUploadLink, }: TutorialProps) => JSX.Element;
+export declare const SelfieTutorial: ({ manager, ageAssurance }: TutorialProps) => JSX.Element;
 
 /**
  * Sets global UI configuration defaults for `@incodetech/ui`.
@@ -1163,7 +1238,6 @@ declare type TitleProps = HTMLAttributes_2<HTMLHeadingElement> & {
 declare type TutorialProps = {
     manager: SelfieManager;
     ageAssurance?: boolean;
-    showManualUploadLink?: boolean;
 };
 
 /**
@@ -1214,6 +1288,29 @@ export declare type UiConfig = {
      * {@link SpinnerPresentation}.
      */
     spinner?: SpinnerPresentation;
+    /** Where the capture help button renders. Defaults to `'bottomRight'`. */
+    helpButtonPosition?: HelpButtonPosition;
+    /** Shows an X close button that cancels the current module. Off by default. */
+    showCloseButton?: boolean;
+    /**
+     * Close button corner when `showCloseButton` is true. Defaults to
+     * `'topRight'`. Can't match `helpButtonPosition` — on a collision the help
+     * button falls back to its own default and a dev warning is logged.
+     */
+    closeButtonPosition?: CloseButtonPosition;
+    /**
+     * How the ID-capture realtime feedback message (live cues) renders.
+     * Defaults to `'standard'` — see {@link RealtimeFeedbackMessageUIFlavor}.
+     */
+    realtimeFeedbackMessageUIFlavor?: RealtimeFeedbackMessageUIFlavor;
+    /**
+     * `true` hides the unsupported-browser screen in standalone modules; `false`
+     * forces it on. A per-element `config.disableUnsupportedBrowserScreen` wins
+     * over this. When both are omitted, the session Flow's setting applies.
+     * `<incode-flow>` and `<incode-workflow>` ignore it and always use their
+     * server setting.
+     */
+    disableUnsupportedBrowserScreen?: boolean;
 };
 
 /**
@@ -1231,6 +1328,11 @@ export declare function useManager<TManager extends {
 
 declare type UseManagerOptions = {
     autoLoad?: boolean;
+    /**
+     * False leaves ordinary lifecycle ownership with the caller. Session expiry
+     * always stops the manager to release capture resources; use a new manager
+     * when mounting a replacement session.
+     */
     manageLifecycle?: boolean;
 };
 
@@ -1242,7 +1344,7 @@ export declare function useScreenOrientation(): {
     isLandscapeMobile: boolean;
 };
 
-export declare function VerificationOptionCard({ icon: Icon, title, testId, onClick, tag, }: Readonly<VerificationOptionCardProps>): JSX.Element;
+export declare function VerificationOptionCard({ icon: Icon, iconSrc, title, testId, onClick, tag, }: Readonly<VerificationOptionCardProps>): JSX.Element;
 
 export declare function VerificationOptionCardList({ children, }: Readonly<VerificationOptionCardListProps>): JSX.Element;
 
@@ -1251,9 +1353,15 @@ declare type VerificationOptionCardListProps = {
 };
 
 declare type VerificationOptionCardProps = {
+    /** Glyph rendered in the icon slot; the fallback when `iconSrc` is absent. */
     icon: FC<{
         className?: string;
     }>;
+    /**
+     * Image URL (e.g. a digital-ID provider logo) rendered in the icon slot
+     * instead of `icon`. Decorative — the card is labelled by its title.
+     */
+    iconSrc?: string;
     title: string;
     testId: string;
     onClick: () => void;

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

@@ -3,6 +3,7 @@ import { FaceMatchConfig } from '@incodetech/core/face-match';
 import { FaceMatchManager } from '@incodetech/core/face-match';
 import { FC } from 'preact/compat';
 import { FunctionComponent } from 'preact';
+import { SessionExpiredError } from '@incodetech/core/session';
 import { SVGProps } from 'preact/compat';
 
 /**
@@ -82,6 +83,15 @@ declare type IncodeFinishMeta = {
      * replace the SDK screen. Not a guarantee.
      */
     sdkOwnsTerminalScreen?: boolean;
+    /**
+     * True when the workflow is OAuth2-secured. The OAuth authorization server
+     * owns the redirect back to the client's `redirect_uri`, so the host must not
+     * navigate to `redirectionUrl` itself. A host redirect drops the `error` and
+     * `state` parameters, and the client reads a failed authentication as a
+     * success. The workflow always sets it on finish; treat a missing value as
+     * unknown.
+     */
+    oauth2Secured?: boolean;
 };
 
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TConfigInput = ConfigWithOverrides<TConfig>> = {
@@ -95,7 +105,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
      */
     config?: TConfigInput;
     /**
-     * Optional pre-built manager. When provided, the module does not create or manage the manager lifecycle.
+     * Optional pre-built manager. The host owns its ordinary lifecycle.
+     * Session expiry always stops it to release capture resources, even when
+     * supplied by the host. Create a new manager for a replacement session;
+     * do not reuse the stopped instance in another mounted module.
      */
     manager?: TManager;
     /**
@@ -115,8 +128,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
      * @param moduleErrorCode - Optional machine-readable error code (e.g. a
      *   `FaceErrorCode` such as `NONEXISTENT_CUSTOMER`). Lets an orchestrator
      *   branch on the specific terminal error without parsing the message string.
+     * @param details - Structured session-expiry error with statusCode 401 and
+     *   code/type SESSION_EXPIRED. The first three arguments stay compatible.
      */
-    onError?: (error: string | undefined, errorCode?: number, moduleErrorCode?: string) => void;
+    onError?: ModuleErrorHandler;
 };
 
 /**
@@ -131,6 +146,13 @@ declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
     spinner?: SpinnerPresentation;
+    /**
+     * `true` hides the unsupported-browser screen for this element; `false`
+     * forces it on. Wins over `setup({ uiConfig })`. When both are omitted, the
+     * session Flow's setting applies. `<incode-flow>` and `<incode-workflow>`
+     * ignore it and always use their server setting.
+     */
+    disableUnsupportedBrowserScreen?: boolean;
 };
 
 declare type LottieAnimationData = {
@@ -142,6 +164,8 @@ declare type LottieAnimationData = {
     h: number;
 };
 
+declare type ModuleErrorHandler = (message: string | undefined, errorCode?: number, moduleErrorCode?: string, details?: SessionExpiredError) => void;
+
 /**
  * Host-facing loader presentation, settable globally via
  * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
@@ -170,3 +194,9 @@ declare type SpinnerSize = 'small' | 'medium' | 'large';
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 
 export { }
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'incode-face-match': HTMLElement & import('preact').ComponentProps<typeof FaceMatch>;
+    }
+}

package/dist/types/field-comparison.d.ts

@@ -3,6 +3,7 @@ import { FC } from 'preact/compat';
 import { FieldComparisonConfig } from '@incodetech/core/field-comparison';
 import { FieldComparisonManager } from '@incodetech/core/field-comparison';
 import { FunctionComponent } from 'preact';
+import { SessionExpiredError } from '@incodetech/core/session';
 import { SVGProps } from 'preact/compat';
 
 /**
@@ -79,6 +80,15 @@ declare type IncodeFinishMeta = {
      * replace the SDK screen. Not a guarantee.
      */
     sdkOwnsTerminalScreen?: boolean;
+    /**
+     * True when the workflow is OAuth2-secured. The OAuth authorization server
+     * owns the redirect back to the client's `redirect_uri`, so the host must not
+     * navigate to `redirectionUrl` itself. A host redirect drops the `error` and
+     * `state` parameters, and the client reads a failed authentication as a
+     * success. The workflow always sets it on finish; treat a missing value as
+     * unknown.
+     */
+    oauth2Secured?: boolean;
 };
 
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TConfigInput = ConfigWithOverrides<TConfig>> = {
@@ -92,7 +102,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
      */
     config?: TConfigInput;
     /**
-     * Optional pre-built manager. When provided, the module does not create or manage the manager lifecycle.
+     * Optional pre-built manager. The host owns its ordinary lifecycle.
+     * Session expiry always stops it to release capture resources, even when
+     * supplied by the host. Create a new manager for a replacement session;
+     * do not reuse the stopped instance in another mounted module.
      */
     manager?: TManager;
     /**
@@ -112,8 +125,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
      * @param moduleErrorCode - Optional machine-readable error code (e.g. a
      *   `FaceErrorCode` such as `NONEXISTENT_CUSTOMER`). Lets an orchestrator
      *   branch on the specific terminal error without parsing the message string.
+     * @param details - Structured session-expiry error with statusCode 401 and
+     *   code/type SESSION_EXPIRED. The first three arguments stay compatible.
      */
-    onError?: (error: string | undefined, errorCode?: number, moduleErrorCode?: string) => void;
+    onError?: ModuleErrorHandler;
 };
 
 /**
@@ -128,6 +143,13 @@ declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
     spinner?: SpinnerPresentation;
+    /**
+     * `true` hides the unsupported-browser screen for this element; `false`
+     * forces it on. Wins over `setup({ uiConfig })`. When both are omitted, the
+     * session Flow's setting applies. `<incode-flow>` and `<incode-workflow>`
+     * ignore it and always use their server setting.
+     */
+    disableUnsupportedBrowserScreen?: boolean;
 };
 
 declare type LottieAnimationData = {
@@ -139,6 +161,8 @@ declare type LottieAnimationData = {
     h: number;
 };
 
+declare type ModuleErrorHandler = (message: string | undefined, errorCode?: number, moduleErrorCode?: string, details?: SessionExpiredError) => void;
+
 /**
  * Host-facing loader presentation, settable globally via
  * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
@@ -167,3 +191,9 @@ declare type SpinnerSize = 'small' | 'medium' | 'large';
 declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;
 
 export { }
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'incode-field-comparison': HTMLElement & import('preact').ComponentProps<typeof FieldComparison>;
+    }
+}

package/dist/types/fiscal-qr.d.ts

@@ -3,6 +3,7 @@ import { FC } from 'preact/compat';
 import { FiscalQrConfig } from '@incodetech/core/fiscal-qr';
 import { FiscalQrManager } from '@incodetech/core/fiscal-qr';
 import { FunctionComponent } from 'preact';
+import { SessionExpiredError } from '@incodetech/core/session';
 import { SVGProps } from 'preact/compat';
 
 /**
@@ -79,6 +80,15 @@ declare type IncodeFinishMeta = {
      * replace the SDK screen. Not a guarantee.
      */
     sdkOwnsTerminalScreen?: boolean;
+    /**
+     * True when the workflow is OAuth2-secured. The OAuth authorization server
+     * owns the redirect back to the client's `redirect_uri`, so the host must not
+     * navigate to `redirectionUrl` itself. A host redirect drops the `error` and
+     * `state` parameters, and the client reads a failed authentication as a
+     * success. The workflow always sets it on finish; treat a missing value as
+     * unknown.
+     */
+    oauth2Secured?: boolean;
 };
 
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TConfigInput = ConfigWithOverrides<TConfig>> = {
@@ -92,7 +102,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
      */
     config?: TConfigInput;
     /**
-     * Optional pre-built manager. When provided, the module does not create or manage the manager lifecycle.
+     * Optional pre-built manager. The host owns its ordinary lifecycle.
+     * Session expiry always stops it to release capture resources, even when
+     * supplied by the host. Create a new manager for a replacement session;
+     * do not reuse the stopped instance in another mounted module.
      */
     manager?: TManager;
     /**
@@ -112,8 +125,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
      * @param moduleErrorCode - Optional machine-readable error code (e.g. a
      *   `FaceErrorCode` such as `NONEXISTENT_CUSTOMER`). Lets an orchestrator
      *   branch on the specific terminal error without parsing the message string.
+     * @param details - Structured session-expiry error with statusCode 401 and
+     *   code/type SESSION_EXPIRED. The first three arguments stay compatible.
      */
-    onError?: (error: string | undefined, errorCode?: number, moduleErrorCode?: string) => void;
+    onError?: ModuleErrorHandler;
 };
 
 /**
@@ -128,6 +143,13 @@ declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
     spinner?: SpinnerPresentation;
+    /**
+     * `true` hides the unsupported-browser screen for this element; `false`
+     * forces it on. Wins over `setup({ uiConfig })`. When both are omitted, the
+     * session Flow's setting applies. `<incode-flow>` and `<incode-workflow>`
+     * ignore it and always use their server setting.
+     */
+    disableUnsupportedBrowserScreen?: boolean;
 };
 
 declare type LottieAnimationData = {
@@ -139,6 +161,8 @@ declare type LottieAnimationData = {
     h: number;
 };
 
+declare type ModuleErrorHandler = (message: string | undefined, errorCode?: number, moduleErrorCode?: string, details?: SessionExpiredError) => void;
+
 /**
  * Host-facing loader presentation, settable globally via
  * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
@@ -170,6 +194,6 @@ export { }
 
 declare global {
     interface HTMLElementTagNameMap {
-        'incode-fiscal-qr': HTMLElement & IncodeModuleProps<FiscalQrConfig, void, FiscalQrManager>;
+        'incode-fiscal-qr': HTMLElement & import('preact').ComponentProps<typeof FiscalQr>;
     }
 }

package/dist/types/flow.d.ts

@@ -4,6 +4,7 @@ import { FinishStatus } from '@incodetech/core/flow';
 import { FlowEvent } from '@incodetech/core/flow-events';
 import { FunctionComponent } from 'preact';
 import { RedirectReturnParams } from '@incodetech/core/id';
+import { SessionExpiredError } from '@incodetech/core/session';
 import { SVGProps } from 'preact/compat';
 import { WasmConfig } from '@incodetech/core/wasm';
 
@@ -167,6 +168,15 @@ declare type IncodeFinishMeta = {
      * replace the SDK screen. Not a guarantee.
      */
     sdkOwnsTerminalScreen?: boolean;
+    /**
+     * True when the workflow is OAuth2-secured. The OAuth authorization server
+     * owns the redirect back to the client's `redirect_uri`, so the host must not
+     * navigate to `redirectionUrl` itself. A host redirect drops the `error` and
+     * `state` parameters, and the client reads a failed authentication as a
+     * success. The workflow always sets it on finish; treat a missing value as
+     * unknown.
+     */
+    oauth2Secured?: boolean;
 };
 
 export declare const IncodeFlow: FC<IncodeFlowProps>;
@@ -184,7 +194,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
      */
     config?: TConfigInput;
     /**
-     * Optional pre-built manager. When provided, the module does not create or manage the manager lifecycle.
+     * Optional pre-built manager. The host owns its ordinary lifecycle.
+     * Session expiry always stops it to release capture resources, even when
+     * supplied by the host. Create a new manager for a replacement session;
+     * do not reuse the stopped instance in another mounted module.
      */
     manager?: TManager;
     /**
@@ -204,8 +217,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TCon
      * @param moduleErrorCode - Optional machine-readable error code (e.g. a
      *   `FaceErrorCode` such as `NONEXISTENT_CUSTOMER`). Lets an orchestrator
      *   branch on the specific terminal error without parsing the message string.
+     * @param details - Structured session-expiry error with statusCode 401 and
+     *   code/type SESSION_EXPIRED. The first three arguments stay compatible.
      */
-    onError?: (error: string | undefined, errorCode?: number, moduleErrorCode?: string) => void;
+    onError?: ModuleErrorHandler;
 };
 
 /**
@@ -220,6 +235,13 @@ declare type InstanceOverrides = {
     assets?: AssetOverrides;
     animations?: AnimationOverrides;
     spinner?: SpinnerPresentation;
+    /**
+     * `true` hides the unsupported-browser screen for this element; `false`
+     * forces it on. Wins over `setup({ uiConfig })`. When both are omitted, the
+     * session Flow's setting applies. `<incode-flow>` and `<incode-workflow>`
+     * ignore it and always use their server setting.
+     */
+    disableUnsupportedBrowserScreen?: boolean;
 };
 
 declare type LottieAnimationData = {
@@ -231,6 +253,8 @@ declare type LottieAnimationData = {
     h: number;
 };
 
+declare type ModuleErrorHandler = (message: string | undefined, errorCode?: number, moduleErrorCode?: string, details?: SessionExpiredError) => void;
+
 /**
  * Preload runs before the Flow component mounts and only prefetches the flow
  * config + theme — it never burns a urlUuid. Allowing one would silently skip
@@ -324,6 +348,6 @@ export { }
 
 declare global {
     interface HTMLElementTagNameMap {
-        'incode-flow': HTMLElement & IncodeModuleProps<FlowConfig, FinishStatus>;
+        'incode-flow': HTMLElement & import('preact').ComponentProps<typeof IncodeFlow>;
     }
 }