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

package/dist/createFaceAvatar-B8pFpy6o.d.ts

@@ -0,0 +1,401 @@
+import { t as IncodeCanvas } from "./canvas-CJUmoXSD.js";
+
+//#region ../infra/src/wasm/wasmWebClient.d.ts
+
+/**
+ * Configuration shape that the C++ `WebApi` passes when calling `.post(...)`
+ * on its host JS adapter. Mirrors the upstream `ml-wasm-kit/WebClient`
+ * `RequestConfig` for the subset of fields actually set by `WebApi`.
+ */
+type WebApiHostRequestConfig = {
+  ie?: boolean;
+  headers?: Record<string, string>;
+  params?: Record<string, string | number | boolean | undefined>;
+  timeout?: number;
+};
+//#endregion
+//#region ../infra/src/capabilities/IMLProviderCapability.d.ts
+/**
+ * Base configuration shared by all ML provider capabilities.
+ */
+interface MLProviderConfig {
+  /** Path to the WASM binary */
+  wasmPath?: string;
+  /** Path to the SIMD-optimized WASM binary (optional) */
+  wasmSimdPath?: string;
+  /** Path to the WASM glue code (paired with `wasmPath`) */
+  glueCodePath?: string;
+  /**
+   * Path to the SIMD-optimized WASM glue code (paired with `wasmSimdPath`).
+   * If omitted, defaults to a sibling `.js` derived from `wasmSimdPath`.
+   */
+  glueCodeSimdPath?: string;
+  /** Whether to use SIMD optimizations (default: true) */
+  useSimd?: boolean;
+  /**
+   * Base path for ML model files. Models will be loaded from `${modelsBasePath}/${modelFileName}`.
+   * If not provided, models are expected in a 'models' subdirectory relative to the WASM binary.
+   */
+  modelsBasePath?: string;
+}
+/**
+ * Base interface for ML provider capabilities.
+ * Provides common lifecycle and frame processing methods shared by
+ * FaceDetectionCapability and IdCaptureCapability.
+ */
+interface IMLProviderCapability<TConfig extends MLProviderConfig> {
+  /**
+   * Whether the provider has been initialized and is ready to process frames.
+   */
+  readonly initialized: boolean;
+  /**
+   * Initializes the provider with the given configuration.
+   * If WASM was already warmed up via `setup()` or `warmupWasm()`, this returns almost instantly.
+   * @param config - Provider configuration including WASM paths
+   */
+  initialize(config: TConfig): Promise<void>;
+  /**
+   * Processes a frame through the ML pipeline.
+   * Callbacks set via `setCallbacks()` will be invoked based on the analysis results.
+   * @param image - Image data to process
+   * @throws Error if provider is not initialized
+   */
+  processFrame(image: ImageData): Promise<void>;
+  /**
+   * Resets the pipeline to its initial state.
+   * Safe to call even if not initialized (no-op in that case).
+   */
+  reset(): void;
+  /**
+   * Disposes of resources and resets initialization state.
+   * Safe to call even if not initialized.
+   */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region ../infra/src/capabilities/IFaceDetectionCapability.d.ts
+/**
+ * Configuration for face detection provider.
+ * Extends base ML provider config with face-detection specific options.
+ */
+interface FaceDetectionConfig extends MLProviderConfig {
+  autocaptureInterval?: number;
+  /**
+   * Load the on-device selfie workflow (6 models including liveness + age
+   * estimation) instead of the default selfie workflow (4 models). Required
+   * when SELFIE/AUTHENTICATION has `onDeviceFaceResultsSubmissionEnabled`.
+   */
+  useOnDeviceWorkflow?: boolean;
+  /**
+   * Load the video-selfie face workflow (`SelfieWithAggregationMetrics`, the
+   * frame-aggregation best-shot pipeline used by the video-selfie flow)
+   * instead of the default quality-metrics selfie workflow. Mutually exclusive
+   * with `useOnDeviceWorkflow`.
+   */
+  videoSelfie?: boolean;
+}
+interface FacePositionConstraints {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+interface FaceDetectionThresholds {
+  brightnessThreshold: number;
+  blurrinessThreshold: number;
+  tiltRotationAngleThreshold: number;
+  minMagicCropSize: number;
+  autocaptureInterval: number;
+  minFaceQualityScore: number;
+  faceOcclusionThreshold: number;
+  /**
+   * Milliseconds the C++ workflow waits after `onGetReady` fires before
+   * triggering autocapture. Mirrors V1's `getReadyDelay` (2000 ms) — without
+   * it, autocapture can fire on the first quality-passing frame, before the
+   * front camera has finished locking focus, producing blurry captures that
+   * the on-device quality model rejects.
+   */
+  getReadyDelay: number;
+  /**
+   * Milliseconds over which face-detection results are aggregated before the
+   * autocapture decision. Mirrors V1's `framesAggregationInterval` (2000 ms).
+   */
+  framesAggregationInterval: number;
+  /**
+   * Minimum consecutive frames with a detected face required before
+   * autocapture can trigger. Mirrors V1's `minFramesWithFace` (3).
+   */
+  minFramesWithFace: number;
+}
+interface FaceAttributesThresholds {
+  headwearThreshold: number;
+  lensesThreshold: number;
+  closedEyesThreshold: number;
+  maskThreshold: number;
+}
+interface FaceChecksConfig {
+  lenses: boolean;
+  mask: boolean;
+  closedEyes: boolean;
+  headWear: boolean;
+  occlusion: boolean;
+}
+interface FaceData {
+  rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  rightEye: {
+    x: number;
+    y: number;
+  };
+  leftEye: {
+    x: number;
+    y: number;
+  };
+  noseTip: {
+    x: number;
+    y: number;
+  };
+  rightMouthCorner: {
+    x: number;
+    y: number;
+  };
+  leftMouthCorner: {
+    x: number;
+    y: number;
+  };
+  pitch: number;
+  yaw: number;
+  roll: number;
+}
+type FaceCoordinates = {
+  rightEyeX: number;
+  rightEyeY: number;
+  leftEyeX: number;
+  leftEyeY: number;
+  noseTipX: number;
+  noseTipY: number;
+  rightMouthX: number;
+  rightMouthY: number;
+  mouthX: number;
+  mouthY: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+interface FaceDetectionCallbacks {
+  onFarAway?: () => void;
+  onTooClose?: () => void;
+  onTooManyFaces?: () => void;
+  onNoFace?: () => void;
+  onCapture?: (canvas: IncodeCanvas, faceCoordinates: FaceCoordinates) => void;
+  onGetReady?: () => void;
+  onGetReadyFinished?: () => void;
+  onCenterFace?: () => void;
+  onDark?: () => void;
+  onBlur?: () => void;
+  onFaceAngle?: () => void;
+  /**
+   * Fires on **every** processed frame that contains at least one detected
+   * face, with the freshly-computed face data (pitch/yaw/roll/landmarks).
+   *
+   * Use `onFaceData` when you need a dense per-frame signal for live UI
+   * feedback — e.g. the Personhood avatar that mirrors head pose. The
+   * default capture pipeline does not subscribe to this, so consumers
+   * that don't need per-frame data pay no cost.
+   *
+   * `frameSize` is the source frame's pixel dimensions. Optional so
+   * existing single-arg consumers keep working (TypeScript callback
+   * variance handles it). Personhood uses it to compute an
+   * orientation-invariant face-size ratio for distance-aware smoothing.
+   */
+  onFaceData?: (face: FaceData, frameSize?: {
+    width: number;
+    height: number;
+  }) => void;
+  onLenses?: () => void;
+  onMask?: () => void;
+  onEyesClosed?: () => void;
+  onHeadWear?: () => void;
+  onSwitchToManualCapture?: () => void;
+  onFaceOccluded?: () => void;
+}
+/**
+ * Capability interface for face detection and selfie capture.
+ * Extends the base ML provider capability with face-detection specific methods.
+ */
+interface IFaceDetectionCapability extends IMLProviderCapability<FaceDetectionConfig> {
+  /**
+   * Sets callbacks for face detection events.
+   * @param callbacks - Object containing callback functions for various detection events
+   */
+  setCallbacks(callbacks: FaceDetectionCallbacks): void;
+  /**
+   * Sets position constraints for face detection.
+   * @param constraints - Bounding box constraints for valid face position
+   */
+  setPositionConstraints(constraints: FacePositionConstraints): void;
+  /**
+   * Sets detection thresholds for quality checks.
+   * @param thresholds - Threshold values for various quality metrics
+   */
+  setThresholds(thresholds: FaceDetectionThresholds): void;
+  /**
+   * Sets thresholds for face attribute detection.
+   * @param thresholds - Threshold values for attribute detection (headwear, lenses, etc.)
+   */
+  setAttributesThresholds(thresholds: FaceAttributesThresholds): void;
+  /**
+   * Enables or disables specific face checks.
+   * @param config - Configuration for which checks to enable
+   */
+  setChecksEnabled(config: FaceChecksConfig): void;
+  /**
+   * Sets video selfie mode.
+   * @param enabled - Whether to enable video selfie mode
+   */
+  setVideoSelfieMode(enabled: boolean): void;
+  /**
+   * Manually triggers the `onCapture` callback registered via
+   * `setCallbacks`, using the best-quality frame the provider has
+   * seen so far (or the most recent processed frame as a fallback).
+   * Used by callers that want to complete a capture flow without
+   * waiting for WASM's own autocapture criteria — e.g. Personhood's
+   * "complete with far-away face" path, where the user may be too
+   * small in frame for autocapture to ever fire but a verdict
+   * (likely lower-confidence) is still desired.
+   *
+   * No-op when no frame is available at all (camera hasn't produced
+   * a single decoded frame yet) or when no `onCapture` callback was
+   * registered.
+   */
+  forceCapture(): void;
+  /**
+   * Synchronous manual-capture entry point for the on-device selfie workflow.
+   * Runs the full on-device pipeline on a single canvas image and stages the
+   * results inside WASM for the next {@link postFaceResults} call. No-op for
+   * default (non-on-device) configurations; callers should guard with the
+   * `onDeviceFaceResultsSubmissionEnabled` flag.
+   */
+  processPhoto(canvas: HTMLCanvasElement): void;
+  /**
+   * POSTs the staged on-device face-results JSON to `/omni/add/face-results`.
+   * The C++ side encrypts the body via `SessionEncryptor` and routes through
+   * the WASM `WebClient`, so the SDK's WebClient must be initialized first
+   * (consumers calling this must configure `setup({ apiURL, wasm })`).
+   */
+  postFaceResults(config?: WebApiHostRequestConfig): Promise<unknown>;
+}
+//#endregion
+//#region ../infra/src/avatar/faceFeed.d.ts
+/**
+ * A tiny per-frame pub/sub channel for the Incode WASM pipeline's `FaceData`.
+ *
+ * The parked `incode-2d` avatar drives the cosmetic avatar from the **existing** Incode face-detection
+ * pipeline (no second MediaPipe model). The detection pipeline lives in core's
+ * detection actor, while the avatar lives in the avatar actor — so the avatar is
+ * *fed* `FaceData` through this channel rather than running its own model.
+ *
+ * Deliberately NOT routed through XState events/context: the pipeline emits
+ * ~10×/s, and assigning that into context would re-run `mapState` and notify all
+ * manager subscribers 10×/s — needless churn that could itself regress UI perf.
+ * The feed is a plain emitter passed as input to both actors (detection
+ * publishes, the avatar source subscribes); nothing else observes it.
+ *
+ * Strictly read-only w.r.t. the authoritative pipeline — the feed only forwards
+ * data the pipeline already computed; it never influences detection/autocapture.
+ */
+interface FaceFeedReader {
+  /** Subscribe to per-frame faces. Returns an unsubscribe function. */
+  subscribe(listener: (face: FaceData) => void): () => void;
+  /** The most recently published face, or null if none yet. */
+  getLatest(): FaceData | null;
+  /**
+   * Subscribe to the coarse "eyes closed" pulse — the only real eye signal the
+   * Incode pipeline exposes (a threshold event, both eyes, fired only when the
+   * closed-eyes check is enabled via `validateClosedEyes`). The avatar uses it
+   * to drive a real blink. Returns an unsubscribe function.
+   */
+  onEyesClosed(listener: () => void): () => void;
+}
+interface FaceFeed extends FaceFeedReader {
+  publish(face: FaceData): void;
+  /** Fire the eyes-closed pulse (from the detection pipeline's threshold event). */
+  signalEyesClosed(): void;
+}
+//#endregion
+//#region ../infra/src/capabilities/IFaceAvatarCapability.d.ts
+/**
+ * Caller-supplied overrides. Any omitted field falls back to the default
+ * CDN layout (see `avatar/avatarDefaults.ts`). `basePath`/`version` rewrite
+ * the whole directory; the individual `*Path` fields win over both.
+ */
+interface AvatarAssetsOverrides {
+  basePath?: string;
+  version?: string;
+  mediapipeModulePath?: string;
+  mediapipeWasmPath?: string;
+  faceLandmarkerModelPath?: string;
+  vrmModelPath?: string;
+}
+/**
+ * Verdict cue an avatar can reflect: `detecting` (working) / `success` / `error`.
+ * Pose-driven 2D avatars colour the face accordingly (green wink / red frown);
+ * avatars without a verdict visual (VRM, privacy-lens) treat `setState` as a no-op.
+ * Driven by the host module (selfie capture outcome, personhood verdict).
+ */
+type AvatarFaceState = 'detecting' | 'success' | 'error';
+//#endregion
+//#region src/internal/avatar/createFaceAvatar.d.ts
+/**
+ * Shared face-avatar dispatch — the single code path BOTH the selfie module
+ * (`faceCapture` runAvatar actor) and the public `@incodetech/core/avatar` facade
+ * use, so every camera module mounts avatars the same way. Lives in `internal/`
+ * (not `modules/`) because `internal/` may not import from `modules/`; the public
+ * `modules/avatar` entry is a thin re-export of this. See
+ * docs/features/FACE_AVATAR.md.
+ *
+ * Public catalog of shippable face avatars. Each id maps to a lazily-loaded
+ * provider, so a module only pays the bundle cost of the avatar it picks:
+ *  - `avatar-3d`    → 3D VRM character, MediaPipe-tracked (premium look).
+ *  - `avatar-2d`    → stylized 2D "satin" face, MediaPipe-tracked. Also the
+ *                     personhood avatar.
+ *  - `privacy-lens` → WebGL frosted-glass lens over the real video (no tracking).
+ *
+ * (The Incode-data 2D avatar is parked — kept in infra, not in the public
+ * catalog. See docs/features/FACE_AVATAR.md → Parked: the Incode-data avatar.)
+ */
+type AvatarId = 'avatar-3d' | 'avatar-2d' | 'privacy-lens';
+interface FaceAvatarOptions {
+  /** Which avatar to render. */
+  variant: AvatarId;
+  /** The already-acquired camera stream (the host module owns it). */
+  stream: MediaStream;
+  /** Runtime asset overrides (MediaPipe wasm/model, VRM); defaults to the CDN layout. */
+  assets?: AvatarAssetsOverrides;
+  /** Upper bound on the avatar's internal detect/render loop (default 30). */
+  maxFps?: number;
+  /** Initial verdict cue; defaults to `detecting`. */
+  initialState?: AvatarFaceState;
+}
+interface FaceAvatarHandle {
+  /** The canvas to mount in place of the live video. */
+  readonly canvas: HTMLCanvasElement;
+  /** Push a verdict cue (no-op for avatars without a verdict visual). */
+  setState(state: AvatarFaceState): void;
+  /** Tear down the loop, model and hidden decode video. */
+  stop(): void;
+}
+/**
+ * Mounts a cosmetic face avatar: lazy-loads the chosen provider, starts it on the
+ * given stream, and returns a handle to mount the canvas + push verdict cues. The
+ * avatar is **cosmetic-only** — it never feeds the authoritative
+ * detection/quality/liveness/upload pipeline.
+ */
+declare function createFaceAvatar(options: FaceAvatarOptions): Promise<FaceAvatarHandle>;
+//#endregion
+export { MLProviderConfig as _, AvatarAssetsOverrides as a, FaceAttributesThresholds as c, FaceDetectionCallbacks as d, FaceDetectionConfig as f, IMLProviderCapability as g, IFaceDetectionCapability as h, createFaceAvatar as i, FaceChecksConfig as l, FacePositionConstraints as m, FaceAvatarHandle as n, AvatarFaceState as o, FaceDetectionThresholds as p, FaceAvatarOptions as r, FaceFeed as s, AvatarId as t, FaceCoordinates as u, WebApiHostRequestConfig as v };

package/dist/createFaceAvatar-BOHDKQRq.esm.js

@@ -0,0 +1,46 @@
+//#region src/internal/avatar/createFaceAvatar.ts
+/** Lazy-load the provider for an avatar id (each lands in its own chunk). */
+async function loadProvider(variant) {
+	switch (variant) {
+		case "avatar-3d": return (await import("./3dAvatarProvider-ChciZmjE.esm.js")).createProvider();
+		case "avatar-2d": return (await import("./Face2DProvider-BeLlYBbB.esm.js")).createProvider();
+		case "privacy-lens": return (await import("./PrivacyLensProvider-hDzaDzZ6.esm.js")).createProvider();
+		default: {
+			const exhaustive = variant;
+			throw new Error(`Unknown avatar variant: ${String(exhaustive)}`);
+		}
+	}
+}
+/**
+* Mounts a cosmetic face avatar: lazy-loads the chosen provider, starts it on the
+* given stream, and returns a handle to mount the canvas + push verdict cues. The
+* avatar is **cosmetic-only** — it never feeds the authoritative
+* detection/quality/liveness/upload pipeline.
+*/
+async function createFaceAvatar(options) {
+	const provider = await loadProvider(options.variant);
+	try {
+		await provider.start(options.stream, {
+			assets: options.assets,
+			maxFps: options.maxFps
+		});
+		if (options.initialState) provider.setState?.(options.initialState);
+	} catch (error) {
+		provider.stop();
+		throw error;
+	}
+	return {
+		get canvas() {
+			return provider.getCanvas();
+		},
+		setState(state) {
+			provider.setState?.(state);
+		},
+		stop() {
+			provider.stop();
+		}
+	};
+}
+
+//#endregion
+export { createFaceAvatar as t };

package/dist/cross-document-data-match.d.ts

@@ -1,4 +1,5 @@
-import { t as Manager } from "./Manager-BHn8wH8K.js";
+import "./StateMachine-C_AY4cs7.js";
+import { t as Manager } from "./Manager-CJ3G2zqi.js";
 
 //#region src/modules/cross-document-data-match/crossDocumentDataMatchManager.d.ts
 type CrossDocumentDataMatchIdleState = {

package/dist/cross-document-data-match.esm.js

@@ -1,8 +1,9 @@
-import { t as api } from "./api-CESGtpbH.esm.js";
-import { n as eventModuleNames, o as createManagerInstrumentation } from "./events-Dvvriq9l.esm.js";
-import { t as endpoints } from "./endpoints-BeTK0Mlt.esm.js";
-import { a as fromPromise, c as createManager, s as createActor, t as setup } from "./xstate.esm-C9wncMQa.esm.js";
-import { t as sleep } from "./ITimerCapability-CB0I1Uf2.esm.js";
+import { t as api } from "./api-DsbUi7TO.esm.js";
+import { n as createManagerInstrumentation } from "./events-CqGY1yMq.esm.js";
+import { n as eventModuleNames } from "./types-ElOJAGaM.esm.js";
+import { t as endpoints } from "./endpoints-BzMJFAPV.esm.js";
+import { a as fromPromise, l as createManager, s as createActor, t as setup } from "./xstate.esm-Bomq1a0z.esm.js";
+import { t as sleep } from "./ITimerCapability-pltuG1E8.esm.js";
 
 //#region src/modules/cross-document-data-match/crossDocumentDataMatchServices.ts
 /** Minimum spinner duration (ms), aligned with SDK v1 `ProcessCrossDocumentData`. */

package/dist/curp-validation.d.ts

@@ -1,10 +1,13 @@
-import "./Manager-BHn8wH8K.js";
-import "./Actor-Y0_Fj-KL.js";
-import "./camera-SRBpPq2X.js";
-import "./types-Bj9hdFjU.js";
-import "./types-DvGZI7BF.js";
-import "./types-DOUhndhT.js";
-import { a as CurpValidationActor, c as CurpValidationErrors, d as GenerateCurpFieldDef, f as GenerateCurpFieldType, i as createCurpValidationManagerFromActor, l as CurpValidationRule, n as CurpValidationState, o as curpValidationMachine, p as GenerateCurpForm, r as createCurpValidationManager, s as CurpValidationConfig, t as CurpValidationManager, u as EnterCurpFieldDef } from "./curpValidationManager-RttixpIc.js";
+import "./StateMachine-C_AY4cs7.js";
+import "./Manager-CJ3G2zqi.js";
+import "./Actor-CGEelYtQ.js";
+import "./camera-CNVUo-bC.js";
+import "./types-DgGlgyZT.js";
+import "./types-D_IceWxT.js";
+import "./canvas-CJUmoXSD.js";
+import "./createFaceAvatar-B8pFpy6o.js";
+import "./types-BsYXnC5s.js";
+import { a as CurpValidationActor, c as CurpValidationErrors, d as GenerateCurpFieldDef, f as GenerateCurpFieldType, i as createCurpValidationManagerFromActor, l as CurpValidationRule, n as CurpValidationState, o as curpValidationMachine, p as GenerateCurpForm, r as createCurpValidationManager, s as CurpValidationConfig, t as CurpValidationManager, u as EnterCurpFieldDef } from "./curpValidationManager-Co6LZAHT.js";
 
 //#region src/modules/curp-validation/curpValidationUtils.d.ts
 type MexicanState = {

package/dist/curp-validation.esm.js

@@ -1,8 +1,9 @@
-import "./api-CESGtpbH.esm.js";
-import "./events-Dvvriq9l.esm.js";
-import "./endpoints-BeTK0Mlt.esm.js";
-import "./xstate.esm-C9wncMQa.esm.js";
-import { i as mexicanStates, n as ENTER_CURP_FIELD, r as GENERATE_CURP_FIELDS, t as curpValidationMachine } from "./curpValidationStateMachine-B7V_qp66.esm.js";
-import { n as createCurpValidationManagerFromActor, t as createCurpValidationManager } from "./curpValidationManager-CFem6zP9.esm.js";
+import "./api-DsbUi7TO.esm.js";
+import "./events-CqGY1yMq.esm.js";
+import "./types-ElOJAGaM.esm.js";
+import "./endpoints-BzMJFAPV.esm.js";
+import "./xstate.esm-Bomq1a0z.esm.js";
+import { i as mexicanStates, n as ENTER_CURP_FIELD, r as GENERATE_CURP_FIELDS, t as curpValidationMachine } from "./curpValidationStateMachine-DXTPK6vI.esm.js";
+import { n as createCurpValidationManagerFromActor, t as createCurpValidationManager } from "./curpValidationManager-BafobPXC.esm.js";
 
 export { ENTER_CURP_FIELD, GENERATE_CURP_FIELDS, createCurpValidationManager, createCurpValidationManagerFromActor, curpValidationMachine, mexicanStates };

package/dist/{curpValidationManager-CFem6zP9.esm.js → curpValidationManager-BafobPXC.esm.js}

@@ -1,6 +1,7 @@
-import { n as eventModuleNames, o as createManagerInstrumentation } from "./events-Dvvriq9l.esm.js";
-import { c as createManager, s as createActor } from "./xstate.esm-C9wncMQa.esm.js";
-import { t as curpValidationMachine } from "./curpValidationStateMachine-B7V_qp66.esm.js";
+import { n as createManagerInstrumentation, t as topLevelStateName } from "./events-CqGY1yMq.esm.js";
+import { n as eventModuleNames } from "./types-ElOJAGaM.esm.js";
+import { l as createManager, s as createActor } from "./xstate.esm-Bomq1a0z.esm.js";
+import { t as curpValidationMachine } from "./curpValidationStateMachine-DXTPK6vI.esm.js";
 
 //#region src/modules/curp-validation/curpValidationActor.ts
 function createCurpValidationActor(options) {
@@ -10,6 +11,52 @@ function createCurpValidationActor(options) {
 //#endregion
 //#region src/modules/curp-validation/curpValidationManager.ts
 const hasNoErrors = (errors) => Object.keys(errors ?? {}).length === 0;
+/**
+* Maps a CURP-validation 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: CURP Figma file → Tracked Events canvas
+* (`https://www.figma.com/design/YFYCUUSIxLV6I8jnwWgWDW/CURP---In-Prod?node-id=2786-8314`).
+* The Figma sections name the analytics family as `CURP.EnterCURP.*` (verify
+* path) and `CURP.Gene.*` (generate path), with `CURP` as the module token.
+*
+* Figma screens that have no dedicated state-machine counterpart yet
+* (intentionally not mapped here — they collapse into the section's primary
+* screen until the SM surfaces them):
+*
+* - `CURP.EnterCURP.filled` — UI sub-state of `enterCurp.inputting` (input
+*   has a valid value but submit hasn't been pressed yet).
+* - `CURP.EnterCURP.error` — UI inline validation error on `enterCurp`.
+* - `CURP.Gene.dropdwon` (sic — Figma typo for "dropdown") and
+*   `CURP.Gene.filled` — UI sub-states of `generateCurp.inputting`.
+*
+* `finished` is mapped to `CURP.EnterCURP.Verified` to keep the user on the
+* last visible Figma success screen (the happy-path destination), preventing
+* the adapter from falling back to the generic `<module>.finished` default.
+* `closed` is intentionally left unmapped (terminal user-dismissed state —
+* handled by `moduleClosed`).
+*/
+function getCurpValidationScreenName(snapshot) {
+	const stateName = topLevelStateName(snapshot.value);
+	if (stateName === void 0) return void 0;
+	switch (stateName) {
+		case "idle":
+		case "enterCurp": return "CURP.EnterCURP.default";
+		case "loading": return "CURP.EnterCURP.processing";
+		case "verifying": return "CURP.EnterCURP.verifying";
+		case "success":
+		case "finished": return "CURP.EnterCURP.Verified";
+		case "failure": return "CURP.EnterCURP.notVerify";
+		case "generateCurp": return "CURP.Gene.default";
+		case "generating": return "CURP.Gene.generating";
+		case "confirmCurp": return "CURP.Gene.confirm";
+		case "generateError": return "CURP.Gene.error";
+		default: return;
+	}
+}
 function mapState(snapshot) {
 	const typedSnapshot = snapshot;
 	const { context } = typedSnapshot;
@@ -101,7 +148,7 @@ function createCurpValidationManager(options) {
 		actor: createCurpValidationActor(options),
 		mapState,
 		createApi,
-		instrumentation: createManagerInstrumentation(eventModuleNames.curpValidation)
+		instrumentation: createManagerInstrumentation(eventModuleNames.curpValidation, { getEventScreenName: getCurpValidationScreenName })
 	});
 }
 /**
@@ -114,7 +161,7 @@ function createCurpValidationManagerFromActor(actor) {
 		actor,
 		mapState,
 		createApi,
-		instrumentation: createManagerInstrumentation(eventModuleNames.curpValidation)
+		instrumentation: createManagerInstrumentation(eventModuleNames.curpValidation, { getEventScreenName: getCurpValidationScreenName })
 	});
 }
 

package/dist/{curpValidationManager-RttixpIc.d.ts → curpValidationManager-Co6LZAHT.d.ts}

@@ -1,6 +1,6 @@
-import { t as Manager } from "./Manager-BHn8wH8K.js";
-import { t as ActorRefFrom } from "./Actor-Y0_Fj-KL.js";
-import { i as FlowModuleConfig } from "./types-DOUhndhT.js";
+import { t as Manager } from "./Manager-CJ3G2zqi.js";
+import { t as ActorRefFrom } from "./Actor-CGEelYtQ.js";
+import { i as FlowModuleConfig } from "./types-BsYXnC5s.js";
 
 //#region src/modules/curp-validation/types.d.ts
 type CurpValidationConfig = FlowModuleConfig['CURP_VALIDATION'] & {
@@ -72,6 +72,7 @@ type CreateCurpValidationActorOptions = {
 type CurpValidationActor = ActorRefFrom<CurpValidationMachine>;
 //#endregion
 //#region src/modules/curp-validation/curpValidationManager.d.ts
+
 type CurpValidationIdleState = {
   status: 'idle';
 };

package/dist/{curpValidationStateMachine-B7V_qp66.esm.js → curpValidationStateMachine-DXTPK6vI.esm.js}

@@ -1,6 +1,6 @@
-import { t as api } from "./api-CESGtpbH.esm.js";
-import { t as endpoints } from "./endpoints-BeTK0Mlt.esm.js";
-import { a as fromPromise, r as assign, t as setup } from "./xstate.esm-C9wncMQa.esm.js";
+import { t as api } from "./api-DsbUi7TO.esm.js";
+import { t as endpoints } from "./endpoints-BzMJFAPV.esm.js";
+import { a as fromPromise, r as assign, t as setup } from "./xstate.esm-Bomq1a0z.esm.js";
 
 //#region src/modules/curp-validation/curpValidationUtils.ts
 const CURP_PATTERN = /^([A-Z][AEIOUX][A-Z]{2}\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])[HMX](?:AS|B[CS]|C[CLMSH]|D[FG]|G[TR]|HG|JC|M[CNS]|N[ETL]|OC|PL|Q[TR]|S[PLR]|T[CSL]|VZ|YN|ZS)[B-DF-HJ-NP-TV-Z]{3}[A-Z\d])(\d)$/;

package/dist/custom-fields.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/custom-fields/types.d.ts
 type CustomFieldType = 'INTEGER' | 'DOUBLE' | 'BOOLEAN' | 'STRING' | 'DATE';
@@ -23,6 +24,7 @@ type CreateCustomFieldsActorOptions = {
 };
 //#endregion
 //#region src/modules/custom-fields/customFieldsManager.d.ts
+
 /**
  * A `CustomField` enriched with a computed `label` for display.
  * Label is derived from `alias` when present, otherwise auto-formatted from `name`.