@incodetech/web 2.1.0-rc.1 → 2.1.0-rc.3

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

@@ -6,6 +6,26 @@ export declare const FieldComparison: FC<FieldComparisonProps>;
 
 declare type FieldComparisonProps = IncodeModuleProps<FieldComparisonConfig, void, FieldComparisonManager>;
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -19,8 +39,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

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

@@ -5,6 +5,26 @@ export declare const FiscalQr: FC<FiscalQrProps>;
 
 declare type FiscalQrProps = IncodeModuleProps<FiscalQrConfig>;
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -18,8 +38,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

package/dist/types/flow.d.ts

@@ -45,6 +45,26 @@ declare type FlowUiConfig = {
     spinnerConfig?: SpinnerConfig;
 };
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 export declare const IncodeFlow: FC<IncodeFlowProps>;
 
 declare type IncodeFlowProps = IncodeModuleProps<FlowConfig, FinishStatus>;
@@ -62,8 +82,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

package/dist/types/geolocation.d.ts

@@ -1,10 +1,33 @@
 import { FC } from 'preact/compat';
 import { GeolocationConfig } from '@incodetech/core/geolocation';
+import { GeolocationManager } from '@incodetech/core/geolocation';
 
 declare const Geolocation_2: FC<GeolocationProps>;
 export { Geolocation_2 as Geolocation }
 
-declare type GeolocationProps = IncodeModuleProps<GeolocationConfig>;
+declare type GeolocationProps = IncodeModuleProps<GeolocationConfig> & {
+    manager?: GeolocationManager;
+};
+
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
 
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
@@ -19,8 +42,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

package/dist/types/{governmentValidation.d.ts → government-validation.d.ts}

@@ -5,6 +5,26 @@ export declare const GovernmentValidation: FC<GovernmentValidationProps>;
 
 declare type GovernmentValidationProps = IncodeModuleProps<GovernmentValidationConfig>;
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -18,8 +38,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

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

@@ -5,6 +5,26 @@ export declare const IdVerification: FC<IdVerificationProps>;
 
 declare type IdVerificationProps = IncodeModuleProps<IdVerificationConfig>;
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -18,8 +38,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

package/dist/types/id.d.ts

@@ -6,6 +6,26 @@ export declare const Id: FC<IdProps>;
 
 declare type IdProps = IncodeModuleProps<IdCaptureConfig, void, IdCaptureManager>;
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -19,8 +39,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

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

@@ -6,6 +6,26 @@ export declare const IdentityReuse: FC<IdentityReuseProps>;
 
 declare type IdentityReuseProps = IncodeModuleProps<IdentityReuseConfig, void, IdentityReuseManager>;
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -19,8 +39,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

package/dist/types/phone.d.ts

@@ -2,6 +2,26 @@ import { FC } from 'preact/compat';
 import { PhoneConfig } from '@incodetech/core/phone';
 import { PhoneManager } from '@incodetech/core/phone';
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -15,8 +35,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

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

@@ -1,6 +1,26 @@
 import { FC } from 'preact/compat';
 import { QeSignatureConfig } from '@incodetech/core/qe-signature';
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -14,8 +34,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

package/dist/types/selfie.d.ts

@@ -2,6 +2,26 @@ import { FC } from 'preact/compat';
 import { SelfieConfig } from '@incodetech/core/selfie';
 import { SelfieManager } from '@incodetech/core/selfie';
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -15,8 +35,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

package/dist/types/signature.d.ts

@@ -1,6 +1,26 @@
 import { FC } from 'preact/compat';
 import { SignatureConfig } from '@incodetech/core/signature';
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -14,8 +34,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

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

@@ -0,0 +1,72 @@
+import { FC } from 'preact/compat';
+import { VideoSelfieConfig } from '@incodetech/core/video-selfie';
+
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
+declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
+    /**
+     * Module configuration required to render the flow.
+     * For Web Components, this is typically assigned via `element.config = ...`.
+     */
+    config?: TConfig;
+    /**
+     * Optional pre-built manager. When provided, the module does not create or manage the manager lifecycle.
+     */
+    manager?: TManager;
+    /**
+     * Callback invoked when the module completes successfully.
+     * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
+     */
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
+    /**
+     * Callback invoked when a fatal module error occurs.
+     *
+     * @param error - Human-readable error message.
+     * @param errorCode - Optional numeric code (e.g. HTTP status). Populated by
+     *   the workflow and flow modules on QR validation failures —
+     *   `4026` (`expiredUUID`), `4081` (`invalidQRuuid`) or `4083` (`onboardingUrlAlreadyUsed`).
+     * @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.
+     */
+    onError?: (error: string | undefined, errorCode?: number, moduleErrorCode?: string) => void;
+};
+
+/**
+ * Video Selfie UI component. Records + streams a multi-step, camera-switching
+ * session and renders a live preview with per-step auto-capture guidance.
+ *
+ * @see {@link createVideoSelfieRecordingManager} for headless usage.
+ */
+export declare const VideoSelfie: FC<VideoSelfieProps>;
+
+/** Props for the {@link VideoSelfie} component. */
+declare type VideoSelfieProps = IncodeModuleProps<VideoSelfieConfig>;
+
+export { }
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'incode-video-selfie': HTMLElement & IncodeModuleProps<VideoSelfieConfig>;
+    }
+}

package/dist/types/watchlist.d.ts

@@ -1,6 +1,26 @@
 import { FC } from 'preact/compat';
 import { WatchlistConfig } from '@incodetech/core/watchlist';
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -14,8 +34,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *

package/dist/types/workflow.d.ts

@@ -14,6 +14,26 @@ declare type ClientIdSessionBootstrap = {
     clientId: string;
 };
 
+/**
+ * Extra context passed to `onFinish` alongside the result. Lets a host decide
+ * how to react to the terminal state without inspecting the DOM. Only the
+ * workflow module sets these fields today.
+ */
+export declare type IncodeFinishMeta = {
+    /**
+     * True when the SDK owns the terminal screen — it has already rendered its
+     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
+     * screen), so the host should not render its own completion screen on top.
+     * `onFinish` still fires so the host can run side effects (e.g. notify an
+     * OAuth parent).
+     *
+     * Advisory only: the SDK cannot stop a host from rendering. This works solely
+     * because the host reads this flag — a host that ignores it will still
+     * replace the SDK screen. Not a guarantee.
+     */
+    sdkOwnsTerminalScreen?: boolean;
+};
+
 declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Module configuration required to render the flow.
@@ -27,8 +47,10 @@ declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown> = {
     /**
      * Callback invoked when the module completes successfully.
      * @param result - Optional result data from the module completion
+     * @param meta - Optional context about how the module resolved (e.g. whether
+     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
      */
-    onFinish?: (result?: TResult) => void;
+    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
     /**
      * Callback invoked when a fatal module error occurs.
      *