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

package/dist/setup-DHc6OaHm.esm.js

@@ -0,0 +1,562 @@
+import { f as deriveSiblingJsPath, r as warmupWasm, t as WasmUtilProvider } from "./WasmUtilProvider-ADG54T6M.esm.js";
+import { t as BrowserTimerProvider } from "./BrowserTimerProvider-CHloo0eQ.esm.js";
+import { a as resetApi, i as isApiConfigured, n as getApi, r as getToken, t as api } from "./api-DsbUi7TO.esm.js";
+import { i as upgradeToWasmHttpClient, n as installFreshHttpClient, r as resetHttpClientState, t as getStoredHttpConfig } from "./clientLifecycle-Ct7h9uxx.esm.js";
+import { f as getAnalyticsBatcher, m as setAnalyticsBatcher, p as resetAnalyticsBatcher, u as createAnalyticsBatchingService } from "./events-CqGY1yMq.esm.js";
+import { t as endpoints } from "./endpoints-BzMJFAPV.esm.js";
+import { r as resetDeviceStatsQueue, t as addDeviceStats } from "./stats-CYcScXcO.esm.js";
+import { a as setClientIpLookupEnabled, i as resetSessionInit, r as initializeSession } from "./sessionInitializer-C_TYIgyk.esm.js";
+import { a as resetTRI, n as initializeTRI, o as resetTRIProviderInstance } from "./tri-BG1iJsr4.esm.js";
+
+//#region ../infra/src/wasm/wasmDefaults.ts
+const WASM_CDN_BASE_URL = "https://cdn.incodesmile.com/ml-wasm-kit-release";
+/** The WASM version bundled and tested with this SDK release. */
+const DEFAULT_WASM_VERSION = "v2.14.07-post7";
+const PATH_KEYS = [
+	"wasmPath",
+	"wasmSimdPath",
+	"glueCodePath",
+	"glueCodeSimdPath",
+	"modelsBasePath"
+];
+function isBlank(value) {
+	return value.trim() === "";
+}
+function hasDisallowedControlChars(value) {
+	for (let i = 0; i < value.length; i += 1) {
+		const code = value.charCodeAt(i);
+		if (code < 32 || code === 127) return true;
+	}
+	return false;
+}
+function isMalformedPath(value) {
+	const trimmed = value.trim();
+	if (trimmed === "") return false;
+	if (hasDisallowedControlChars(trimmed)) return true;
+	if (/^https?:\/\//i.test(trimmed)) try {
+		new URL(trimmed);
+		return false;
+	} catch {
+		return true;
+	}
+	return false;
+}
+function warnInvalidWasmPath(field, reason) {
+	if (reason === "empty") {
+		console.warn(`[Incode SDK] wasm.${field} is empty. Falling back to CDN default.`);
+		return;
+	}
+	console.warn(`[Incode SDK] wasm.${field} appears malformed. Falling back to CDN default.`);
+}
+function warnMalformedWasmPath(field) {
+	console.warn(`[Incode SDK] wasm.${field} appears malformed. Check the URL or path.`);
+}
+/**
+* Validates merged WASM path strings. When overrides contained blank path
+* values, callers should have already fallen back to defaults before this runs.
+*/
+function validateWasmPaths(config) {
+	for (const key of PATH_KEYS) {
+		const value = config[key];
+		if (typeof value === "string" && isMalformedPath(value)) warnMalformedWasmPath(key);
+	}
+}
+function pickPath(key, overrides, defaultValue) {
+	if (!overrides || !(key in overrides)) return defaultValue;
+	const raw = overrides[key];
+	if (raw === void 0) return defaultValue;
+	if (typeof raw !== "string") return defaultValue;
+	if (isBlank(raw)) {
+		warnInvalidWasmPath(key, "empty");
+		return defaultValue;
+	}
+	if (isMalformedPath(raw)) {
+		warnInvalidWasmPath(key, "malformed");
+		return defaultValue;
+	}
+	return raw.trim();
+}
+/** Builds a WarmupConfig from a directory that mirrors the ml-wasm-kit CDN layout. */
+function buildWasmConfigFromBasePath(basePath) {
+	const base = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+	return {
+		wasmPath: `${base}/webLib.wasm`,
+		wasmSimdPath: `${base}/webLibSimd.wasm`,
+		glueCodePath: `${base}/webLib.js`,
+		glueCodeSimdPath: `${base}/webLibSimd.js`,
+		modelsBasePath: `${base}/models`
+	};
+}
+/** Builds the standard WarmupConfig from the Incode CDN. */
+function buildDefaultWasmConfig() {
+	return buildWasmConfigFromBasePath(`${WASM_CDN_BASE_URL}/${DEFAULT_WASM_VERSION}`);
+}
+/**
+* Merges optional WASM path overrides with CDN defaults. Explicit non-blank
+* paths take precedence. Blank override strings log a warning and fall back to defaults.
+*/
+function resolveWasmConfig(overrides) {
+	if (!overrides) return buildDefaultWasmConfig();
+	const defaults = buildWasmConfigFromBasePath(pickPath("basePath", overrides, `${WASM_CDN_BASE_URL}/${DEFAULT_WASM_VERSION}`));
+	const simdDefault = defaults.wasmSimdPath ?? defaults.wasmPath;
+	const modelsDefault = defaults.modelsBasePath ?? (() => {
+		const lastSlash = defaults.wasmPath.lastIndexOf("/");
+		return lastSlash === -1 ? "models" : `${defaults.wasmPath.substring(0, lastSlash)}/models`;
+	})();
+	const resolvedWasmSimdPath = pickPath("wasmSimdPath", overrides, simdDefault);
+	const glueCodeSimdDefault = deriveSiblingJsPath(resolvedWasmSimdPath);
+	const merged = {
+		wasmPath: pickPath("wasmPath", overrides, defaults.wasmPath),
+		wasmSimdPath: resolvedWasmSimdPath,
+		glueCodePath: pickPath("glueCodePath", overrides, defaults.glueCodePath),
+		glueCodeSimdPath: pickPath("glueCodeSimdPath", overrides, glueCodeSimdDefault),
+		modelsBasePath: pickPath("modelsBasePath", overrides, modelsDefault),
+		useSimd: overrides.useSimd,
+		pipelines: overrides.pipelines,
+		pipelineModels: overrides.pipelineModels
+	};
+	validateWasmPaths(merged);
+	return merged;
+}
+
+//#endregion
+//#region ../infra/src/providers/browser/BrowserPageLifecycleProvider.ts
+var BrowserPageLifecycleProvider = class {
+	sendBeacon(url, body, contentType = "application/json") {
+		if (typeof navigator === "undefined" || typeof navigator.sendBeacon !== "function") return false;
+		const blob = new Blob([body], { type: contentType });
+		return navigator.sendBeacon(url, blob);
+	}
+	onPageHide(listener) {
+		const onVisibilityChange = () => {
+			if (document.visibilityState === "hidden") listener();
+		};
+		document.addEventListener("visibilitychange", onVisibilityChange);
+		window.addEventListener("pagehide", listener);
+		window.addEventListener("beforeunload", listener);
+		return () => {
+			document.removeEventListener("visibilitychange", onVisibilityChange);
+			window.removeEventListener("pagehide", listener);
+			window.removeEventListener("beforeunload", listener);
+		};
+	}
+};
+
+//#endregion
+//#region ../infra/src/providers/browser/DevtoolsDetectorProvider.ts
+var DevtoolsDetectorProvider = class {
+	constructor() {
+		this.detectorPaused = true;
+		this.isDevtoolsOpen = false;
+	}
+	start(options) {
+		if (!this.canUseDevtoolsDetector() || this.heart) return;
+		this.startDetector({
+			pollingIntervalSeconds: .25,
+			maxMillisBeforeAckWhenClosed: 100,
+			moreAnnoyingDebuggerStatements: 1,
+			onDetectOpen: options.onInspectorOpened,
+			onDetectClose: void 0,
+			startup: "asap"
+		});
+	}
+	stop() {
+		this.clearNextPulse();
+		this.resolveVerdict?.(null);
+		this.resolveVerdict = void 0;
+		this.heart?.terminate();
+		this.heart = void 0;
+		this.detectorPaused = true;
+		this.isDevtoolsOpen = false;
+	}
+	canUseDevtoolsDetector() {
+		return typeof globalThis !== "undefined" && typeof Worker !== "undefined" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function" && typeof Blob !== "undefined";
+	}
+	createDetectorWorker() {
+		return new Worker(URL.createObjectURL(new Blob([`"use strict";
+onmessage = (ev) => { postMessage({isOpenBeat:true});
+  debugger; for (let i = 0; i < ev.data.moreDebugs; i++) { debugger; }
+  postMessage({isOpenBeat:false});
+};`], { type: "text/javascript" })));
+	}
+	clearNextPulse() {
+		if (this.nextPulseTimeout !== void 0) {
+			clearTimeout(this.nextPulseTimeout);
+			this.nextPulseTimeout = void 0;
+		}
+	}
+	doOnePulse(moreDebugs) {
+		this.heart?.postMessage({ moreDebugs });
+	}
+	startDetector(config) {
+		this.heart = this.createDetectorWorker();
+		const onHeartMsg = (msg) => {
+			if (msg.data.isOpenBeat) new Promise((resolve) => {
+				this.resolveVerdict = resolve;
+				setTimeout(() => {
+					this.resolveVerdict?.(true);
+				}, config.maxMillisBeforeAckWhenClosed + 1);
+			}).then((verdict) => {
+				if (verdict === null) return;
+				if (verdict !== this.isDevtoolsOpen) {
+					this.isDevtoolsOpen = verdict;
+					if (verdict) config.onDetectOpen();
+					else if (config.onDetectClose) config.onDetectClose();
+				}
+				this.clearNextPulse();
+				this.nextPulseTimeout = setTimeout(() => {
+					this.nextPulseTimeout = void 0;
+					this.doOnePulse(config.moreAnnoyingDebuggerStatements);
+				}, config.pollingIntervalSeconds * 1e3);
+			});
+			else this.resolveVerdict?.(false);
+		};
+		this.heart.addEventListener("message", onHeartMsg);
+		const resume = () => {
+			if (!this.detectorPaused) return;
+			this.detectorPaused = false;
+			this.doOnePulse(config.moreAnnoyingDebuggerStatements);
+		};
+		switch (config.startup) {
+			case "manual": break;
+			case "asap":
+				resume();
+				break;
+			case "domContentLoaded":
+				if (typeof document !== "undefined" && document.readyState !== "loading") resume();
+				else if (typeof document !== "undefined") document.addEventListener("DOMContentLoaded", resume, { once: true });
+				break;
+		}
+	}
+};
+
+//#endregion
+//#region src/internal/device/devtoolsDetectorBridge.ts
+const devtoolsDetector = new DevtoolsDetectorProvider();
+async function reportInspectorOpened() {
+	try {
+		(await WasmUtilProvider.getInstance()).setInspectorOpened(true);
+	} catch {
+		return;
+	}
+	addDeviceStats({ inspectorOpened: true });
+}
+/**
+* Starts the devtools inspector detector (ported from legacy welcome `setupFiles`).
+*/
+function startDevtoolsDetector() {
+	devtoolsDetector.start({ onInspectorOpened: () => {
+		reportInspectorOpened();
+	} });
+}
+/**
+* Stops the devtools detector. Invoked from {@link reset}.
+*/
+function stopDevtoolsDetector() {
+	devtoolsDetector.stop();
+}
+
+//#endregion
+//#region src/setup.ts
+let wasmConfig;
+/**
+* Legacy Java backend default for OAEP MGF1 padding compatibility.
+* Most existing Incode E2EE environments expect this.
+*/
+const DEFAULT_MGF1 = "sha1";
+/**
+* Normalizes the public `encryption` option into the internal shape used by
+* the HTTP client lifecycle. Returns `undefined` when the caller did not
+* specify `encryption` at all (so callers can distinguish "preserve stored
+* value" from "explicitly off").
+*/
+function normalizeEncryption(input) {
+	if (input === void 0) return void 0;
+	if (input === false) return {
+		enabled: false,
+		mgf1: DEFAULT_MGF1
+	};
+	if (input === true) return {
+		enabled: true,
+		mgf1: DEFAULT_MGF1
+	};
+	return {
+		enabled: true,
+		mgf1: input.mgf1 ?? DEFAULT_MGF1
+	};
+}
+let configured = false;
+/**
+* Initializes the SDK with the provided configuration.
+* Must be called before using any SDK functionality.
+*
+* WASM loads only when `options.wasm` is provided as an object.
+*
+* `setup` is boot — it provisions the HTTP client, the optional E2EE
+* handshake, WASM warmup, and the analytics batcher. The session token is a
+* separate concern: hand it off via `initializeSession({ token })` from
+* `@incodetech/core/session`, or pass it inline as `setup({ apiURL, token })`
+* (a convenience that delegates to `initializeSession` for you).
+*
+* @param options - Configuration options for the SDK
+*
+* @example Boot first, activate the session later (preferred)
+* ```ts
+* import { setup } from '@incodetech/core';
+* import { createSession, initializeSession } from '@incodetech/core/session';
+*
+* await setup({ apiURL: 'https://api.incode.com' });
+* const session = await createSession(apiKey, { configurationId });
+* await initializeSession({ token: session.token });
+* ```
+*
+* @example One-shot convenience
+* ```ts
+* await setup({ apiURL: 'https://api.incode.com', token: 'session-token' });
+* ```
+*
+* @example Explicitly disable WASM
+* ```ts
+* await setup({ apiURL: 'https://api.incode.com', wasm: false });
+* ```
+*
+* @example Use CDN defaults for paths and preload only one pipeline
+* ```ts
+* await setup({
+*   apiURL: 'https://api.incode.com',
+*   wasm: { pipelines: ['selfie'] },
+* });
+* ```
+*
+* @example Self-hosted WASM (pin a version folder on your CDN)
+* ```ts
+* await setup({
+*   apiURL: 'https://api.incode.com',
+*   wasm: {
+*     basePath: 'https://my-cdn.example.com/ml-wasm-kit-release/v2.13.21',
+*   },
+* });
+* ```
+*
+* @example Partial override: only models path, rest from CDN
+* ```ts
+* await setup({
+*   apiURL: 'https://api.incode.com',
+*   wasm: { modelsBasePath: 'https://my-cdn/models' },
+* });
+* ```
+*
+* @example Sessionless setup (all API actors overridden via .provide())
+* ```ts
+* await setup({
+*   wasm: {
+*     wasmPath: '/wasm/ml-wasm.wasm',
+*     glueCodePath: '/wasm/ml-wasm.js',
+*     pipelines: ['selfie'],
+*   },
+* });
+* ```
+*
+* @example Enable end-to-end encryption at boot (defaults to MGF1 = SHA-1)
+* ```ts
+* // `/0` lets the server read the API key from the session JWT.
+* await setup({
+*   apiURL: 'https://your-e2ee-api.incodesmile.com/0',
+*   encryption: true,
+* });
+* ```
+*
+* @example Enable encryption with the SHA-256 MGF1 padding
+* ```ts
+* await setup({
+*   apiURL: 'https://your-e2ee-api.incodesmile.com/0',
+*   encryption: { mgf1: 'sha256' },
+* });
+* ```
+*
+* @example E2EE without the `/0` suffix — pass the API key explicitly
+* ```ts
+* await setup({
+*   apiURL: 'https://your-e2ee-api.incodesmile.com',
+*   encryption: true,
+*   customHeaders: { 'x-api-key': process.env.INCODE_API_KEY },
+* });
+* ```
+* @example Disable third-party IP lookup
+* ```ts
+* await setup({
+*   apiURL: 'https://api.incode.com',
+*   ipLookup: false,
+* });
+* ```
+*
+* @example Local development: silence the devtools detector and surface WASM logs
+* ```ts
+* await setup({
+*   apiURL: 'https://api.incode.com',
+*   wasm: { showLogs: true }, // WASM logs are off by default
+*   devMode: true, // skip the devtools detector (don't ship this in prod)
+* });
+* ```
+* @example Enable TRI — exchange the API key for an SDK token first, then pass it to setup
+* ```ts
+* const session = await createTRISession(process.env.INCODE_API_KEY, {
+*   apiURL: process.env.INCODE_TRI_API_URL,
+* });
+*
+* await setup({
+*   apiURL: 'https://api.incode.com',
+*   tri: { token: session.token, apiURL: process.env.INCODE_TRI_API_URL },
+* });
+* ```
+*
+* @example Defer TRI collection until after a consent gate
+* ```ts
+* // Boot without starting collectors:
+* await setup({
+*   apiURL: 'https://api.incode.com',
+*   tri: { token: session.token, apiURL: process.env.INCODE_TRI_API_URL, autostart: false },
+* });
+*
+* // somewhere else in the code
+* await startTRI();
+* ```
+*/
+async function setup(options) {
+	if (options.ipLookup !== void 0) setClientIpLookupEnabled(options.ipLookup);
+	if (!getAnalyticsBatcher()) setAnalyticsBatcher(createAnalyticsBatchingService({
+		endpoint: endpoints.events,
+		authToken: () => getToken(),
+		apiBaseUrl: () => getApi().defaults.baseURL,
+		apiClient: api,
+		pageLifecycle: new BrowserPageLifecycleProvider(),
+		timer: BrowserTimerProvider.getInstance()
+	}));
+	const requestedEncryption = normalizeEncryption(options.encryption);
+	const stored = getStoredHttpConfig();
+	if (requestedEncryption && stored) {
+		if (requestedEncryption.enabled !== stored.encryption.enabled || requestedEncryption.enabled && requestedEncryption.mgf1 !== stored.encryption.mgf1) throw new Error("Encryption is locked at the first setup() call and cannot be changed at runtime. Call reset() to fully reinitialize the SDK if you need a different encryption configuration.");
+	}
+	if (requestedEncryption?.enabled && options.wasm === false) throw new Error("Encryption is incompatible with `wasm: false`. Either remove `wasm: false` or omit `encryption`.");
+	const effectiveEncryption = requestedEncryption ?? stored?.encryption ?? {
+		enabled: false,
+		mgf1: "sha1"
+	};
+	const effectiveWasm = options.wasm || requestedEncryption?.enabled ? resolveWasmConfig(options.wasm || {}) : void 0;
+	if (options.apiURL) await installFreshHttpClient(options.apiURL, options, effectiveWasm, effectiveEncryption);
+	if (options.token && isApiConfigured()) initializeSession({
+		token: options.token,
+		hostingApp: options.hostingApp
+	}).catch((error) => {
+		console.warn("Session initialization failed:", error);
+	});
+	configured = true;
+	if (effectiveWasm) {
+		wasmConfig = {
+			...effectiveWasm,
+			pipelines: effectiveWasm.pipelines ? [...effectiveWasm.pipelines] : void 0
+		};
+		await warmupWasm(effectiveWasm);
+		const provider = await WasmUtilProvider.getInstance();
+		await provider.initialize({
+			...effectiveWasm,
+			pipelines: effectiveWasm.pipelines ? [...effectiveWasm.pipelines] : void 0
+		});
+		const showWasmLogs = typeof options.wasm === "object" && options.wasm.showLogs === true;
+		await provider.setProductionMode(!showWasmLogs);
+		if (!options.devMode) startDevtoolsDetector();
+	}
+	if (options.tri) await initializeTRI(options.tri, { sessionToken: options.token });
+}
+/**
+* Sets the WASM configuration without performing warmup.
+* Useful when WASM warmup is handled separately (e.g., conditionally based on flow).
+*
+* @param config - WASM configuration to store
+*/
+function setWasmConfig(config) {
+	wasmConfig = config;
+}
+/**
+* Initializes WasmUtilProvider with the stored WASM configuration.
+* Should be called after warmupWasm() completes when using conditional warmup.
+* This ensures image encryption works properly.
+*
+* @param config - Optional WASM configuration. If not provided, uses the stored config from setWasmConfig().
+* @throws Error if no config is provided and none is stored
+*/
+async function initializeWasmUtil(config) {
+	const wasmConfigToUse = config ?? wasmConfig;
+	if (!wasmConfigToUse) throw new Error("WASM config is required. Provide config parameter or call setWasmConfig() first.");
+	const resolved = resolveWasmConfig(wasmConfigToUse);
+	await (await WasmUtilProvider.getInstance()).initialize({
+		...resolved,
+		pipelines: resolved.pipelines ? [...resolved.pipelines] : void 0
+	});
+}
+/**
+* Warms additional WASM pipelines on demand, reusing the WASM config stored by
+* `setup({ wasm })` / `setWasmConfig`. Used for module-level lazy loading — e.g.
+* the video-selfie tutorial preloads its `videoSelfie`/`videoSelfieId` pipelines
+* while the user reads, so detection is ready the moment recording starts.
+*
+* `warmupWasm` is idempotent: already-loaded pipelines are skipped and missing
+* ones are merged into the running instance. No-op when WASM was never
+* configured or `pipelines` is empty.
+*
+* @param pipelines - The pipelines to ensure are loaded.
+*/
+async function ensureWasmPipelines(pipelines) {
+	if (pipelines.length === 0 || !wasmConfig) return;
+	await warmupWasm({
+		...resolveWasmConfig(wasmConfig),
+		pipelines: [...pipelines]
+	});
+}
+/**
+* Replaces the active HTTP client with the WASM-backed one. Used internally
+* by lazy-loading UI components (`<incode-flow>`, `<incode-workflow>`) when
+* WASM finishes warming up.
+*
+* No-op when no apiURL was originally configured, or when the active client is
+* already the WASM one.
+*
+* @internal NOT a public API. Application code should use
+*   `setup({ wasm: {...} })` instead — that path is the supported way to opt
+*   into the WASM HTTP client.
+*
+* @param config - Optional WASM configuration. Defaults to the config stored via `setWasmConfig`.
+*/
+async function upgradeToWasmHttpClient$1(config) {
+	const configToUse = config ?? wasmConfig;
+	if (!configToUse) return;
+	await upgradeToWasmHttpClient(resolveWasmConfig(configToUse));
+}
+/**
+* Checks if the SDK has been configured.
+*
+* @returns true if setup() has been called, false otherwise
+*/
+function isConfigured() {
+	return configured;
+}
+/**
+* Resets the SDK configuration. Useful for testing.
+*/
+function reset() {
+	stopDevtoolsDetector();
+	resetDeviceStatsQueue();
+	resetApi();
+	resetSessionInit();
+	setClientIpLookupEnabled(true);
+	resetAnalyticsBatcher();
+	resetHttpClientState();
+	resetTRI();
+	configured = false;
+	wasmConfig = void 0;
+	WasmUtilProvider.resetInstance();
+	resetTRIProviderInstance();
+}
+
+//#endregion
+export { setWasmConfig as a, DEFAULT_WASM_VERSION as c, resolveWasmConfig as d, reset as i, buildDefaultWasmConfig as l, initializeWasmUtil as n, setup as o, isConfigured as r, upgradeToWasmHttpClient$1 as s, ensureWasmPipelines as t, buildWasmConfigFromBasePath as u };

package/dist/signature.d.ts

@@ -1,5 +1,6 @@
-import { t as Manager } from "./Manager-BHn8wH8K.js";
-import "./Actor-Y0_Fj-KL.js";
+import "./StateMachine-C_AY4cs7.js";
+import { t as Manager } from "./Manager-CJ3G2zqi.js";
+import "./Actor-CGEelYtQ.js";
 
 //#region src/modules/signature/types.d.ts
 /**
@@ -59,6 +60,7 @@ type CreateSignatureActorOptions = {
 };
 //#endregion
 //#region src/modules/signature/signatureManager.d.ts
+
 type SignatureIdleState = {
   status: 'idle';
 };

package/dist/signature.esm.js

@@ -1,8 +1,9 @@
-import "./api-CESGtpbH.esm.js";
-import { n as eventModuleNames, o as createManagerInstrumentation } from "./events-Dvvriq9l.esm.js";
-import "./endpoints-BeTK0Mlt.esm.js";
-import { c as createManager, s as createActor } from "./xstate.esm-C9wncMQa.esm.js";
-import { t as signatureMachine } from "./signatureStateMachine-C5qqYLRz.esm.js";
+import "./api-DsbUi7TO.esm.js";
+import { n as createManagerInstrumentation, t as topLevelStateName } from "./events-CqGY1yMq.esm.js";
+import { n as eventModuleNames } from "./types-ElOJAGaM.esm.js";
+import "./endpoints-BzMJFAPV.esm.js";
+import { l as createManager, s as createActor } from "./xstate.esm-Bomq1a0z.esm.js";
+import { t as signatureMachine } from "./signatureStateMachine-DtoiPzys.esm.js";
 
 //#region src/modules/signature/signatureActor.ts
 function createSignatureActor(options) {
@@ -11,6 +12,48 @@ function createSignatureActor(options) {
 
 //#endregion
 //#region src/modules/signature/signatureManager.ts
+/**
+* Maps a signature state-machine snapshot to the exact Figma "Tracked
+* Events" screen name. Returned strings are the Figma-verbatim absolute
+* analytics path (module prefix included), emitted as-is on `event.screen`
+* by `createManagerInstrumentation`'s `getEventScreenName` path. See
+* `docs/patterns/INSTRUMENTATION.md`.
+*
+* Source of truth: Electronic Signature Figma file → Tracked Events canvas
+* (`https://www.figma.com/design/kUsDigsC8Mq1WobTewF0R6/Electronic-Signature---Latest-Design?node-id=4268-3602`).
+* Section names are taken as canonical — note the canvas mixes
+* `eSign.writeSignature.*` for the `default`/`completed` screens with
+* `eSign.writeYourSignature.success` (without the `Signature` collapse) for
+* the success surface; both spellings are preserved verbatim.
+*
+* State → screen mapping rationale:
+*
+* - `idle`/`captureSignature` collapse to `eSign.writeSignature.default` —
+*   the state machine stays in `captureSignature` throughout drawing (stroke
+*   validity changes via `SIGNATURE_CHANGED` are context-only and don't fire
+*   a new `screenOpened`). The `eSign.writeSignature.completed` Figma surface
+*   is therefore the post-submit "signed canvas while we wait for the API"
+*   surface, mapped to `submittingSignature`.
+* - `success`/`finished` both map to `eSign.writeYourSignature.success` so
+*   the terminal `finished` state stays on the visible success canvas rather
+*   than falling back to the generic `<module>.finished` default.
+* - `error` is intentionally unmapped — the Figma canvas does not define a
+*   dedicated error screen yet. The adapter falls back to the generic
+*   `eSign.error` default, which `errorTriggered` consumers can still
+*   correlate against the error payload.
+*/
+function getSignatureScreenName(snapshot) {
+	const stateName = topLevelStateName(snapshot.value);
+	if (stateName === void 0) return void 0;
+	switch (stateName) {
+		case "idle":
+		case "captureSignature": return "eSign.writeSignature.default";
+		case "submittingSignature": return "eSign.writeSignature.completed";
+		case "success":
+		case "finished": return "eSign.writeYourSignature.success";
+		default: return;
+	}
+}
 function mapState(snapshot) {
 	const typedSnapshot = snapshot;
 	const { context } = typedSnapshot;
@@ -58,7 +101,7 @@ function createSignatureManager(options) {
 		actor: createSignatureActor(options),
 		mapState,
 		createApi,
-		instrumentation: createManagerInstrumentation(eventModuleNames.signature)
+		instrumentation: createManagerInstrumentation(eventModuleNames.signature, { getEventScreenName: getSignatureScreenName })
 	});
 }