@incodetech/core 2.0.1 → 2.1.0-rc.0

package/dist/document-capture.esm.js

@@ -1,12 +1,16 @@
+import "./WasmUtilProvider-CiEN7Gjn.esm.js";
 import "./api-CESGtpbH.esm.js";
-import { n as eventModuleNames, o as createManagerInstrumentation } from "./events-D6-e4vok.esm.js";
-import "./endpoints-CnN3SyDa.esm.js";
-import { c as createManager, s as createActor } from "./xstate.esm-B70JrNqo.esm.js";
-import "./ITimerCapability-C67ZRskg.esm.js";
-import "./camera-PA2Ljri3.esm.js";
-import "./platform-CfrjKhmi.esm.js";
-import "./backCameraStream-DMdMeGk2.esm.js";
-import { n as DOCUMENT_CAPTURE_ERROR_CODES, t as documentCaptureMachine } from "./documentCaptureStateMachine-BqzTDy9k.esm.js";
+import { n as eventModuleNames, o as createManagerInstrumentation } from "./events-Dvvriq9l.esm.js";
+import "./endpoints-BeTK0Mlt.esm.js";
+import "./platform-SKvEfCBh.esm.js";
+import { c as createManager, s as createActor } from "./xstate.esm-C9wncMQa.esm.js";
+import "./MotionSensorProvider-Bx7Mpzt0.esm.js";
+import "./permissionServices-CG3bMSfG.esm.js";
+import "./camera-DJWm3V4g.esm.js";
+import "./ITimerCapability-CB0I1Uf2.esm.js";
+import "./backCameraStream-D7Wo4Nbx.esm.js";
+import "./permissionGuards-C1ispV96.esm.js";
+import { n as DOCUMENT_CAPTURE_ERROR_CODES, t as documentCaptureMachine } from "./documentCaptureStateMachine-WYV1r9le.esm.js";
 
 //#region src/modules/document-capture/documentCaptureActor.ts
 function createDocumentCaptureActor(options) {
@@ -15,6 +19,12 @@ function createDocumentCaptureActor(options) {
 
 //#endregion
 //#region src/modules/document-capture/documentCaptureManager.ts
+function getPermissionStatus(snapshot) {
+	if (snapshot.matches({ permissions: "learnMore" })) return "learnMore";
+	if (snapshot.matches({ permissions: "requesting" })) return "requesting";
+	if (snapshot.matches({ permissions: "denied" })) return "denied";
+	return "idle";
+}
 function mapState(snapshot) {
 	const typedSnapshot = snapshot;
 	const { context } = typedSnapshot;
@@ -30,6 +40,10 @@ function mapState(snapshot) {
 			pageNumber: context.pageNumber
 		};
 	}
+	if (typedSnapshot.matches("permissions")) return {
+		status: "permissions",
+		permissionStatus: getPermissionStatus(typedSnapshot)
+	};
 	if (typedSnapshot.matches("initCamera")) return { status: "initializingCamera" };
 	if (typedSnapshot.matches("capturing")) return {
 		status: "capturing",
@@ -124,6 +138,18 @@ function createApi({ actor, trackElementClicked }) {
 			trackElementClicked?.("close");
 			actor.send({ type: "CLOSE" });
 		},
+		requestPermission() {
+			trackElementClicked?.("requestPermission");
+			actor.send({ type: "REQUEST_PERMISSION" });
+		},
+		goToLearnMore() {
+			trackElementClicked?.("goToLearnMore");
+			actor.send({ type: "GO_TO_LEARN_MORE" });
+		},
+		back() {
+			trackElementClicked?.("back");
+			actor.send({ type: "BACK" });
+		},
 		captureNextPageFromCamera() {
 			trackElementClicked?.("captureNextPageFromCamera");
 			actor.send({ type: "NEXT_PAGE_CAMERA" });

package/dist/document-upload.d.ts

@@ -1,11 +1,11 @@
-import { t as Manager } from "./Manager-C8PrhBOx.js";
-import "./Actor-CI32dTbG.js";
-import "./camera-DBSxa6ML.js";
-import { n as DocumentUploadContext, r as DocumentUploadInput, t as DocumentUploadConfig } from "./types-CFV9G_7j.js";
-import * as xstate618 from "xstate";
+import { t as Manager } from "./Manager-BHn8wH8K.js";
+import "./Actor-Y0_Fj-KL.js";
+import "./camera-SRBpPq2X.js";
+import { n as DocumentUploadContext, r as DocumentUploadInput, t as DocumentUploadConfig } from "./types-Bj9hdFjU.js";
+import * as xstate368 from "xstate";
 
 //#region src/modules/document-upload/documentUploadStateMachine.d.ts
-declare const documentUploadMachine: xstate618.StateMachine<DocumentUploadContext, {
+declare const documentUploadMachine: xstate368.StateMachine<DocumentUploadContext, {
   type: "START";
 } | {
   type: "CAPTURE";
@@ -18,52 +18,52 @@ declare const documentUploadMachine: xstate618.StateMachine<DocumentUploadContex
 } | {
   type: "CLOSE";
 }, {
-  [x: string]: xstate618.ActorRefFromLogic<xstate618.PromiseActorLogic<void, {
+  [x: string]: xstate368.ActorRefFromLogic<xstate368.PromiseActorLogic<MediaStream, void, xstate368.EventObject>> | xstate368.ActorRefFromLogic<xstate368.PromiseActorLogic<void, {
     imageBase64: string;
     documentType: string;
     onProgress: (progress: number) => void;
-  }, xstate618.EventObject>> | xstate618.ActorRefFromLogic<xstate618.PromiseActorLogic<MediaStream, void, xstate618.EventObject>> | undefined;
-}, xstate618.Values<{
+  }, xstate368.EventObject>> | undefined;
+}, xstate368.Values<{
   uploadDocument: {
     src: "uploadDocument";
-    logic: xstate618.PromiseActorLogic<void, {
+    logic: xstate368.PromiseActorLogic<void, {
       imageBase64: string;
       documentType: string;
       onProgress: (progress: number) => void;
-    }, xstate618.EventObject>;
+    }, xstate368.EventObject>;
     id: string | undefined;
   };
   initCamera: {
     src: "initCamera";
-    logic: xstate618.PromiseActorLogic<MediaStream, void, xstate618.EventObject>;
+    logic: xstate368.PromiseActorLogic<MediaStream, void, xstate368.EventObject>;
     id: string | undefined;
   };
-}>, xstate618.Values<{
+}>, xstate368.Values<{
   setError: {
     type: "setError";
-    params: xstate618.NonReducibleUnknown;
+    params: xstate368.NonReducibleUnknown;
   };
   clearError: {
     type: "clearError";
-    params: xstate618.NonReducibleUnknown;
+    params: xstate368.NonReducibleUnknown;
   };
   setStream: {
     type: "setStream";
-    params: xstate618.NonReducibleUnknown;
-  };
-  setImageAndClearError: {
-    type: "setImageAndClearError";
-    params: xstate618.NonReducibleUnknown;
+    params: xstate368.NonReducibleUnknown;
   };
   setProgress: {
     type: "setProgress";
-    params: xstate618.NonReducibleUnknown;
+    params: xstate368.NonReducibleUnknown;
   };
   stopStream: {
     type: "stopStream";
-    params: xstate618.NonReducibleUnknown;
+    params: xstate368.NonReducibleUnknown;
+  };
+  setImageAndClearError: {
+    type: "setImageAndClearError";
+    params: xstate368.NonReducibleUnknown;
   };
-}>, never, never, "error" | "idle" | "uploading" | "closed" | "finished" | "initCamera" | "capturing", string, DocumentUploadInput, xstate618.NonReducibleUnknown, xstate618.EventObject, xstate618.MetaObject, {
+}>, never, never, "error" | "idle" | "uploading" | "closed" | "finished" | "initCamera" | "capturing", string, DocumentUploadInput, xstate368.NonReducibleUnknown, xstate368.EventObject, xstate368.MetaObject, {
   readonly id: "documentUpload";
   readonly initial: "idle";
   readonly context: ({
@@ -72,67 +72,67 @@ declare const documentUploadMachine: xstate618.StateMachine<DocumentUploadContex
     spawn: {
       <TSrc extends "uploadDocument" | "initCamera">(logic: TSrc, ...[options]: ({
         src: "uploadDocument";
-        logic: xstate618.PromiseActorLogic<void, {
+        logic: xstate368.PromiseActorLogic<void, {
           imageBase64: string;
           documentType: string;
           onProgress: (progress: number) => void;
-        }, xstate618.EventObject>;
+        }, xstate368.EventObject>;
         id: string | undefined;
       } extends infer T ? T extends {
         src: "uploadDocument";
-        logic: xstate618.PromiseActorLogic<void, {
+        logic: xstate368.PromiseActorLogic<void, {
           imageBase64: string;
           documentType: string;
           onProgress: (progress: number) => void;
-        }, xstate618.EventObject>;
+        }, xstate368.EventObject>;
         id: string | undefined;
       } ? T extends {
         src: TSrc;
-      } ? xstate618.ConditionalRequired<[options?: ({
+      } ? xstate368.ConditionalRequired<[options?: ({
         id?: T["id"] | undefined;
         systemId?: string;
-        input?: xstate618.InputFrom<T["logic"]> | undefined;
+        input?: xstate368.InputFrom<T["logic"]> | undefined;
         syncSnapshot?: boolean;
-      } & { [K in xstate618.RequiredActorOptions<T>]: unknown }) | undefined], xstate618.IsNotNever<xstate618.RequiredActorOptions<T>>> : never : never : never) | ({
+      } & { [K in xstate368.RequiredActorOptions<T>]: unknown }) | undefined], xstate368.IsNotNever<xstate368.RequiredActorOptions<T>>> : never : never : never) | ({
         src: "initCamera";
-        logic: xstate618.PromiseActorLogic<MediaStream, void, xstate618.EventObject>;
+        logic: xstate368.PromiseActorLogic<MediaStream, void, xstate368.EventObject>;
         id: string | undefined;
       } extends infer T_1 ? T_1 extends {
         src: "initCamera";
-        logic: xstate618.PromiseActorLogic<MediaStream, void, xstate618.EventObject>;
+        logic: xstate368.PromiseActorLogic<MediaStream, void, xstate368.EventObject>;
         id: string | undefined;
       } ? T_1 extends {
         src: TSrc;
-      } ? xstate618.ConditionalRequired<[options?: ({
+      } ? xstate368.ConditionalRequired<[options?: ({
         id?: T_1["id"] | undefined;
         systemId?: string;
-        input?: xstate618.InputFrom<T_1["logic"]> | undefined;
+        input?: xstate368.InputFrom<T_1["logic"]> | undefined;
         syncSnapshot?: boolean;
-      } & { [K_1 in xstate618.RequiredActorOptions<T_1>]: unknown }) | undefined], xstate618.IsNotNever<xstate618.RequiredActorOptions<T_1>>> : never : never : never)): xstate618.ActorRefFromLogic<xstate618.GetConcreteByKey<xstate618.Values<{
+      } & { [K_1 in xstate368.RequiredActorOptions<T_1>]: unknown }) | undefined], xstate368.IsNotNever<xstate368.RequiredActorOptions<T_1>>> : never : never : never)): xstate368.ActorRefFromLogic<xstate368.GetConcreteByKey<xstate368.Values<{
         uploadDocument: {
           src: "uploadDocument";
-          logic: xstate618.PromiseActorLogic<void, {
+          logic: xstate368.PromiseActorLogic<void, {
             imageBase64: string;
             documentType: string;
             onProgress: (progress: number) => void;
-          }, xstate618.EventObject>;
+          }, xstate368.EventObject>;
           id: string | undefined;
         };
         initCamera: {
           src: "initCamera";
-          logic: xstate618.PromiseActorLogic<MediaStream, void, xstate618.EventObject>;
+          logic: xstate368.PromiseActorLogic<MediaStream, void, xstate368.EventObject>;
           id: string | undefined;
         };
       }>, "src", TSrc>["logic"]>;
-      <TLogic extends xstate618.AnyActorLogic>(src: TLogic, ...[options]: xstate618.ConditionalRequired<[options?: ({
+      <TLogic extends xstate368.AnyActorLogic>(src: TLogic, ...[options]: xstate368.ConditionalRequired<[options?: ({
         id?: never;
         systemId?: string;
-        input?: xstate618.InputFrom<TLogic> | undefined;
+        input?: xstate368.InputFrom<TLogic> | undefined;
         syncSnapshot?: boolean;
-      } & { [K in xstate618.RequiredLogicInput<TLogic>]: unknown }) | undefined], xstate618.IsNotNever<xstate618.RequiredLogicInput<TLogic>>>): xstate618.ActorRefFromLogic<TLogic>;
+      } & { [K in xstate368.RequiredLogicInput<TLogic>]: unknown }) | undefined], xstate368.IsNotNever<xstate368.RequiredLogicInput<TLogic>>>): xstate368.ActorRefFromLogic<TLogic>;
     };
     input: DocumentUploadInput;
-    self: xstate618.ActorRef<xstate618.MachineSnapshot<DocumentUploadContext, {
+    self: xstate368.ActorRef<xstate368.MachineSnapshot<DocumentUploadContext, {
       type: "START";
     } | {
       type: "CAPTURE";
@@ -144,7 +144,7 @@ declare const documentUploadMachine: xstate618.StateMachine<DocumentUploadContex
       type: "RETRY";
     } | {
       type: "CLOSE";
-    }, Record<string, xstate618.AnyActorRef | undefined>, xstate618.StateValue, string, unknown, any, any>, {
+    }, Record<string, xstate368.AnyActorRef | undefined>, xstate368.StateValue, string, unknown, any, any>, {
       type: "START";
     } | {
       type: "CAPTURE";
@@ -156,7 +156,7 @@ declare const documentUploadMachine: xstate618.StateMachine<DocumentUploadContex
       type: "RETRY";
     } | {
       type: "CLOSE";
-    }, xstate618.AnyEventObject>;
+    }, xstate368.AnyEventObject>;
   }) => {
     config: DocumentUploadConfig;
     stream: undefined;
@@ -226,7 +226,7 @@ declare const documentUploadMachine: xstate618.StateMachine<DocumentUploadContex
           } | {
             type: "CLOSE";
           };
-          self: xstate618.ActorRef<xstate618.MachineSnapshot<DocumentUploadContext, {
+          self: xstate368.ActorRef<xstate368.MachineSnapshot<DocumentUploadContext, {
             type: "START";
           } | {
             type: "CAPTURE";
@@ -238,7 +238,7 @@ declare const documentUploadMachine: xstate618.StateMachine<DocumentUploadContex
             type: "RETRY";
           } | {
             type: "CLOSE";
-          }, Record<string, xstate618.AnyActorRef>, xstate618.StateValue, string, unknown, any, any>, {
+          }, Record<string, xstate368.AnyActorRef>, xstate368.StateValue, string, unknown, any, any>, {
             type: "START";
           } | {
             type: "CAPTURE";
@@ -250,7 +250,7 @@ declare const documentUploadMachine: xstate618.StateMachine<DocumentUploadContex
             type: "RETRY";
           } | {
             type: "CLOSE";
-          }, xstate618.AnyEventObject>;
+          }, xstate368.AnyEventObject>;
         }) => {
           imageBase64: string;
           documentType: string;

package/dist/document-upload.esm.js

@@ -1,11 +1,11 @@
 import { t as api } from "./api-CESGtpbH.esm.js";
-import { n as eventModuleNames, o as createManagerInstrumentation } from "./events-D6-e4vok.esm.js";
-import { t as endpoints } from "./endpoints-CnN3SyDa.esm.js";
-import { a as fromPromise, c as createManager, r as assign, s as createActor, t as setup } from "./xstate.esm-B70JrNqo.esm.js";
-import "./ITimerCapability-C67ZRskg.esm.js";
-import { i as stopCameraStream } from "./camera-PA2Ljri3.esm.js";
-import "./platform-CfrjKhmi.esm.js";
-import { t as getBackCameraStream } from "./backCameraStream-DMdMeGk2.esm.js";
+import { n as eventModuleNames, o as createManagerInstrumentation } from "./events-Dvvriq9l.esm.js";
+import { t as endpoints } from "./endpoints-BeTK0Mlt.esm.js";
+import "./platform-SKvEfCBh.esm.js";
+import { a as fromPromise, c as createManager, r as assign, s as createActor, t as setup } from "./xstate.esm-C9wncMQa.esm.js";
+import { i as stopCameraStream } from "./camera-DJWm3V4g.esm.js";
+import "./ITimerCapability-CB0I1Uf2.esm.js";
+import { n as getBackCameraStream } from "./backCameraStream-D7Wo4Nbx.esm.js";
 
 //#region src/modules/document-upload/documentUploadServices.ts
 async function uploadDocument({ imageBase64, documentType, onProgress, signal }) {

package/dist/{documentCaptureStateMachine-BqzTDy9k.esm.js → documentCaptureStateMachine-WYV1r9le.esm.js}

@@ -1,8 +1,10 @@
 import { t as api } from "./api-CESGtpbH.esm.js";
-import { t as endpoints } from "./endpoints-CnN3SyDa.esm.js";
-import { a as fromPromise, r as assign, t as setup } from "./xstate.esm-B70JrNqo.esm.js";
-import { i as stopCameraStream } from "./camera-PA2Ljri3.esm.js";
-import { t as getBackCameraStream } from "./backCameraStream-DMdMeGk2.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 { n as invokeRequestPermissionActor, t as checkPermission } from "./permissionServices-CG3bMSfG.esm.js";
+import { i as stopCameraStream } from "./camera-DJWm3V4g.esm.js";
+import { n as getBackCameraStream } from "./backCameraStream-D7Wo4Nbx.esm.js";
+import { r as resolveStoredPermissionResult, t as isReadyForCaptureFromPermission } from "./permissionGuards-C1ispV96.esm.js";
 
 //#region src/modules/document-capture/types.ts
 const PROCESSING_TYPE_MAP = {
@@ -90,6 +92,12 @@ const documentCaptureMachine = setup({
 		input: {}
 	},
 	actors: {
+		checkPermission: fromPromise(async () => {
+			return checkPermission();
+		}),
+		requestPermission: fromPromise(async ({ input }) => {
+			return invokeRequestPermissionActor(input);
+		}),
 		initCamera: fromPromise(async () => {
 			const { stream } = await getBackCameraStream(void 0);
 			return stream;
@@ -171,6 +179,11 @@ const documentCaptureMachine = setup({
 		canRetry: ({ context }) => context.attemptsRemaining > 0,
 		attemptsExhausted: ({ context }) => context.attemptsRemaining <= 0,
 		isCameraMode: ({ context }) => context.config.captureMode === "camera",
+		isCameraPermissionGranted: ({ context, event }) => {
+			const output = event.output;
+			return isReadyForCaptureFromPermission(resolveStoredPermissionResult(output, context.permissionResult), false);
+		},
+		isCameraPermissionDenied: ({ event }) => event.output === "denied",
 		isCaptureMethodCamera: ({ context }) => context.captureMethod === "camera",
 		isCaptureMethodGallery: ({ context }) => context.captureMethod === "gallery",
 		isCaptureMethodFile: ({ context }) => context.captureMethod === "file",
@@ -203,6 +216,7 @@ const documentCaptureMachine = setup({
 				step2Text
 			},
 			stream: void 0,
+			permissionResult: void 0,
 			capturedDocument: void 0,
 			captureMethod: void 0,
 			progress: 0,
@@ -215,7 +229,7 @@ const documentCaptureMachine = setup({
 	states: {
 		tutorial: { on: {
 			CAPTURE: [{
-				target: "initCamera",
+				target: "permissions",
 				guard: "isCameraMode"
 			}, { target: "capturing" }],
 			FILE_SELECTED: [{
@@ -232,6 +246,76 @@ const documentCaptureMachine = setup({
 			},
 			CLOSE: { target: "closed" }
 		} },
+		permissions: {
+			initial: "idle",
+			states: {
+				idle: {
+					invoke: {
+						id: "checkPermissionIdle",
+						src: "checkPermission",
+						onDone: [
+							{
+								target: "#documentCapture.initCamera",
+								guard: "isCameraPermissionGranted",
+								actions: assign({ permissionResult: ({ event }) => event.output })
+							},
+							{
+								target: "denied",
+								guard: "isCameraPermissionDenied",
+								actions: assign({ permissionResult: ({ event }) => event.output })
+							},
+							{
+								target: "waitingForUser",
+								actions: assign({ permissionResult: ({ event }) => event.output })
+							}
+						],
+						onError: {
+							target: "waitingForUser",
+							actions: assign({ permissionResult: () => "prompt" })
+						}
+					},
+					on: {
+						REQUEST_PERMISSION: "requesting",
+						GO_TO_LEARN_MORE: "learnMore"
+					}
+				},
+				waitingForUser: { on: {
+					REQUEST_PERMISSION: "requesting",
+					GO_TO_LEARN_MORE: "learnMore"
+				} },
+				learnMore: { on: {
+					BACK: "idle",
+					REQUEST_PERMISSION: "requesting"
+				} },
+				requesting: { invoke: {
+					id: "requestPermission",
+					src: "requestPermission",
+					input: ({ context }) => ({
+						permissionResult: context.permissionResult === "refresh" ? void 0 : context.permissionResult,
+						requestMotionPermission: false
+					}),
+					onDone: [
+						{
+							target: "#documentCapture.initCamera",
+							guard: "isCameraPermissionGranted",
+							actions: assign({ permissionResult: ({ event }) => event.output })
+						},
+						{
+							target: "denied",
+							guard: "isCameraPermissionDenied",
+							actions: assign({ permissionResult: ({ event }) => event.output })
+						},
+						{
+							target: "waitingForUser",
+							actions: assign({ permissionResult: ({ event }) => event.output })
+						}
+					],
+					onError: { target: "denied" }
+				} },
+				denied: { entry: assign({ permissionResult: () => "refresh" }) }
+			},
+			on: { CLOSE: { target: "closed" } }
+		},
 		initCamera: {
 			invoke: {
 				id: "initCamera",
@@ -344,7 +428,7 @@ const documentCaptureMachine = setup({
 		} },
 		nextPage: { on: {
 			NEXT_PAGE_CAMERA: {
-				target: "initCamera",
+				target: "permissions",
 				actions: ["clearForNextPage", "setCaptureMethodCamera"]
 			},
 			NEXT_PAGE_PHOTO_LIBRARY: {

package/dist/dynamic-forms.d.ts

@@ -1,5 +1,5 @@
-import { t as Manager } from "./Manager-C8PrhBOx.js";
-import "./Actor-CI32dTbG.js";
+import { t as Manager } from "./Manager-BHn8wH8K.js";
+import "./Actor-Y0_Fj-KL.js";
 
 //#region src/modules/dynamic-forms/types.d.ts
 
@@ -42,6 +42,10 @@ type DynamicFormsConfig = {
   screens?: Screen[];
 };
 //#endregion
+//#region src/modules/dynamic-forms/dynamicFormsFields.d.ts
+/** Map of `questionId` → currently-displayed i18n error key. */
+type DynamicFormsValidationErrors = Partial<Record<string, string>>;
+//#endregion
 //#region src/modules/dynamic-forms/dynamicFormsStateMachine.d.ts
 /** Whether the form completed normally or was skipped due to a screen-loading failure. */
 type DynamicFormsResult = 'completed' | 'skipped';
@@ -68,7 +72,8 @@ type DynamicFormsLoadingState = {
  * @property totalScreens - Total number of screens in the form
  * @property answers - Current answer values keyed by questionId
  * @property answerValidity - Per-question format validity reported via `setAnswerValidity` (phone, email, CPF, etc.)
- * @property canSubmit - True when all required questions have non-empty answers AND no validity flag is false
+ * @property validationErrors - Errors currently surfaced to the user, keyed by questionId. Entries appear on blur or submit, clear on type. Render as-is — no further UI-side gating.
+ * @property canSubmit - True when no validation errors are currently displayed. Optimistic semantic: enabled on initial empty form; disables only after a submit attempt populates errors.
  */
 type DynamicFormsInputtingState = {
   status: 'inputting';
@@ -77,6 +82,7 @@ type DynamicFormsInputtingState = {
   totalScreens: number;
   answers: Record<string, string>;
   answerValidity: Record<string, boolean>;
+  validationErrors?: DynamicFormsValidationErrors;
   canSubmit: boolean;
 };
 /**
@@ -96,6 +102,7 @@ type DynamicFormsSubmittingState = {
   currentScreen: Screen;
   answers: Record<string, string>;
   answerValidity: Record<string, boolean>;
+  validationErrors?: DynamicFormsValidationErrors;
 };
 /**
  * All screens submitted — success screen visible for ~3 s before
@@ -154,12 +161,20 @@ declare function createDynamicFormsManager(options: CreateDynamicFormsActorOptio
   /**
    * Reports the format validity of a question's current value.
    * Used for fields with format constraints (PHONE, EMAIL, CPF).
-   * Core factors this into `canSubmit` — a false entry blocks submission.
+   * A `false` entry feeds into the `formatViaAnswerValidity` validation rule
+   * and surfaces as a `validationErrors[questionId]` entry once validated.
    *
    * @param questionId - The question ID from the screen definition
    * @param isValid - Whether the current value passes format validation
    */
   setAnswerValidity(questionId: string, isValid: boolean): void;
+  /**
+   * Triggers validation for a single field (e.g., on blur).
+   * Populates or clears `validationErrors[questionId]` accordingly.
+   *
+   * @param questionId - The question ID from the screen definition
+   */
+  validateField(questionId: string): void;
   /**
    * Submits the current screen's answers.
    * Transitions to 'submitting', then advances to the next screen or 'finished'.
@@ -175,4 +190,4 @@ declare function createDynamicFormsManager(options: CreateDynamicFormsActorOptio
 /** Type representing a dynamic forms manager instance. */
 type DynamicFormsManager = ReturnType<typeof createDynamicFormsManager>;
 //#endregion
-export { type DynamicFormsConfig, type DynamicFormsManager, type DynamicFormsResult, type DynamicFormsState, type InputType, type Question, type Screen, createDynamicFormsManager, dynamicFormsMachine };
+export { type DynamicFormsConfig, type DynamicFormsManager, type DynamicFormsResult, type DynamicFormsState, type DynamicFormsValidationErrors, type InputType, type Question, type Screen, createDynamicFormsManager, dynamicFormsMachine };