truescene-face-id-capture-sdk 1.0.0

package/dist/types/sdk/element.d.ts

@@ -0,0 +1,27 @@
+export declare class TrueSceneCaptureElement extends HTMLElement {
+    static observedAttributes: string[];
+    private root;
+    private mount;
+    private styleEl;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    set sessionToken(value: string);
+    get sessionToken(): string;
+    set compareUrl(value: string | undefined);
+    get compareUrl(): string | undefined;
+    set tokenHeader(value: string | undefined);
+    get tokenHeader(): string | undefined;
+    set tokenPrefix(value: string | undefined);
+    get tokenPrefix(): string | undefined;
+    set tokenField(value: string | null | undefined);
+    get tokenField(): string | null | undefined;
+    set autoStart(value: boolean);
+    get autoStart(): boolean;
+    set initialShowDebug(value: boolean);
+    get initialShowDebug(): boolean;
+    set showDebugToggle(value: boolean);
+    get showDebugToggle(): boolean;
+    private renderReact;
+}
+export declare const defineTrueSceneCapture: (tagName?: string) => void;

package/dist/types/sdk/index.d.ts

@@ -0,0 +1,4 @@
+export { defineTrueSceneCapture, TrueSceneCaptureElement } from './element';
+export type { CaptureExperienceProps } from './CaptureExperience';
+export type { CaptureImages, CompareResult } from './types';
+export type { CaptureStep, FaceAndIdCaptureMetrics, } from '../components/FaceAndIdCapture';

package/dist/types/sdk/react/index.d.ts

@@ -0,0 +1,42 @@
+import type { CSSProperties } from 'react';
+import type { CaptureImages, CompareResult } from '../types';
+import type { CaptureStep, FaceAndIdCaptureMetrics } from '../../components/FaceAndIdCapture';
+type ReadyState = {
+    faceReady: boolean;
+    idReady: boolean;
+};
+type TrueSceneCaptureElement = HTMLElement & {
+    sessionToken: string;
+    compareUrl?: string;
+    tokenHeader?: string;
+    tokenPrefix?: string;
+    tokenField?: string | null;
+    autoStart: boolean;
+    initialShowDebug: boolean;
+    showDebugToggle: boolean;
+};
+export type TrueSceneCaptureProps = {
+    sessionToken: string;
+    compareUrl?: string;
+    tokenHeader?: string;
+    tokenPrefix?: string;
+    tokenField?: string | null;
+    autoStart?: boolean;
+    initialShowDebug?: boolean;
+    showDebugToggle?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    onReadyChange?: (ready: ReadyState) => void;
+    onStepChange?: (step: CaptureStep) => void;
+    onMetricsChange?: (metrics: FaceAndIdCaptureMetrics) => void;
+    onCapture?: (images: CaptureImages) => void;
+    onCompareResult?: (result: CompareResult | null) => void;
+    onCompareError?: (message: string | null) => void;
+    onError?: (message: string) => void;
+};
+declare const TrueSceneCapture: ({ sessionToken, compareUrl, tokenHeader, tokenPrefix, tokenField, autoStart, initialShowDebug, showDebugToggle, className, style, onReadyChange, onStepChange, onMetricsChange, onCapture, onCompareResult, onCompareError, onError, }: TrueSceneCaptureProps) => import("react").ReactElement<{
+    ref: import("react").RefObject<TrueSceneCaptureElement | null>;
+    className: string | undefined;
+    style: CSSProperties | undefined;
+}, string | import("react").JSXElementConstructor<any>>;
+export default TrueSceneCapture;

package/dist/types/sdk/styles.d.ts

@@ -0,0 +1 @@
+export declare const captureStyles: string;

package/dist/types/sdk/types.d.ts

@@ -0,0 +1,13 @@
+export type CaptureImages = {
+    faceImage: string | null;
+    idImage: string | null;
+    fullImage: string | null;
+};
+export type CompareResult = {
+    match: boolean;
+    match_percentage: number;
+    cosine_distance: number;
+    cosine_similarity: number;
+    timestamp: number;
+    error?: string;
+};

package/dist/types/utils/config.d.ts

@@ -0,0 +1,52 @@
+export type Range = {
+    min: number;
+    max: number;
+};
+export type FaceConfig = {
+    analysisWidth: number;
+    analysisHeight: number;
+    ovalRxRatio: number;
+    ovalRyRatio: number;
+    minHeightRatio: number;
+    maxHeightRatio: number;
+    marginRatio: number;
+    meanLum: Range;
+    overexposureRatioMax: number;
+    blurScoreMin: number;
+    pose: {
+        yawMax: number;
+        pitchMax: number;
+        rollMax: number;
+        yawScale: number;
+        pitchScale: number;
+    };
+};
+export type IdPlacementConfig = {
+    rectAspect: number;
+    rectWidthScale: number;
+    rectWidthMin: number;
+    rectWidthMax: number;
+    rectTopOffset: number;
+    smoothAlpha: number;
+    missingHoldMs: number;
+    eyesHoldMs: number;
+};
+export type IdRoiConfig = {
+    detectionFps: number;
+    maxRoiWidth: number;
+    expandBelowRatio: number;
+    minFaceHeightRatio: number;
+    minFaceAreaRatio: number;
+    meanLum: Range;
+    blurScoreMin: number;
+};
+export type CaptureConfig = {
+    detectionFps: number;
+    stablePassCount: number;
+    face: FaceConfig;
+    id: {
+        placement: IdPlacementConfig;
+        roi: IdRoiConfig;
+    };
+};
+export declare const DEFAULT_CAPTURE_CONFIG: CaptureConfig;

package/dist/types/utils/faceAnalysis.d.ts

@@ -0,0 +1,26 @@
+export type Landmark = {
+    x: number;
+    y: number;
+    z?: number;
+};
+export type NormalizedBox = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export declare const computeFaceBox: (landmarks: Landmark[]) => NormalizedBox;
+export declare const captureFrameToCanvas: (video: HTMLVideoElement, canvas: HTMLCanvasElement, ctx: CanvasRenderingContext2D) => void;
+export declare const computeMeanLuminance: (imageData: ImageData) => number;
+export declare const computeOverexposureRatio: (imageData: ImageData) => number;
+export declare const computeBlurLaplacianVariance: (imageData: ImageData) => number;
+export type PoseMetrics = {
+    yawDeg: number;
+    pitchDeg: number;
+    rollDeg: number;
+    valid: boolean;
+};
+export declare const estimatePoseFromLandmarks: (landmarks: Landmark[], config: {
+    yawScale: number;
+    pitchScale: number;
+}) => PoseMetrics;

package/dist/types/utils/faceChecks.d.ts

@@ -0,0 +1,19 @@
+import { type Landmark, type NormalizedBox } from './faceAnalysis';
+import type { FaceConfig } from './config';
+export type FaceCheckMetrics = {
+    faceCount: number;
+    faceBox: NormalizedBox | null;
+    meanLum: number;
+    blurScore: number;
+    overexposureRatio: number;
+    yawDeg: number;
+    pitchDeg: number;
+    rollDeg: number;
+    poseValid: boolean;
+};
+export type FaceCheckResult = {
+    pass: boolean;
+    hint: string;
+    metrics: FaceCheckMetrics;
+};
+export declare const evaluateFace: (faceLandmarks: Landmark[][], meanLum: number, overexposureRatio: number, blurScore: number, config: FaceConfig) => FaceCheckResult;

package/dist/types/utils/idPlacement.d.ts

@@ -0,0 +1,13 @@
+import type { Landmark, NormalizedBox } from './faceAnalysis';
+import type { IdPlacementConfig } from './config';
+export type NormalizedRect = NormalizedBox;
+export type IdRectState = {
+    rect: NormalizedRect | null;
+    lastSeenMs: number;
+};
+export type IdRectUpdate = {
+    rect: NormalizedRect | null;
+    state: IdRectState;
+    missingTooLong: boolean;
+};
+export declare const updateIdRect: (state: IdRectState, landmarks: Landmark[] | null, faceBox: NormalizedBox | null, nowMs: number, config: IdPlacementConfig) => IdRectUpdate;

package/dist/types/utils/overlayDraw.d.ts

@@ -0,0 +1,15 @@
+import type { FaceConfig } from './config';
+import type { NormalizedBox } from './faceAnalysis';
+export type OverlayStep = 'FACE_ALIGN' | 'ID_ALIGN';
+export type OverlayOptions = {
+    step: OverlayStep;
+    hint: string;
+    statusColor: 'green' | 'yellow' | 'red';
+    faceConfig: FaceConfig;
+    idRect: NormalizedBox | null;
+    videoSize?: {
+        width: number;
+        height: number;
+    };
+};
+export declare const drawOverlay: (ctx: CanvasRenderingContext2D, width: number, height: number, options: OverlayOptions) => void;

package/dist/utils/config.js

@@ -0,0 +1,44 @@
+export const DEFAULT_CAPTURE_CONFIG = {
+    detectionFps: 6,
+    stablePassCount: 8,
+    face: {
+        analysisWidth: 320,
+        analysisHeight: 180,
+        ovalRxRatio: 0.23,
+        ovalRyRatio: 0.39,
+        minHeightRatio: 0.2,
+        maxHeightRatio: 0.8,
+        marginRatio: 0.03,
+        meanLum: { min: 70, max: 190 },
+        overexposureRatioMax: 0.52,
+        blurScoreMin: 120,
+        pose: {
+            yawMax: 15,
+            pitchMax: 12,
+            rollMax: 10,
+            yawScale: 50,
+            pitchScale: 45,
+        },
+    },
+    id: {
+        placement: {
+            rectAspect: 1.586,
+            rectWidthScale: 1,
+            rectWidthMin: 0.45,
+            rectWidthMax: 0.85,
+            rectTopOffset: 0.03,
+            smoothAlpha: 0.35,
+            missingHoldMs: 1000,
+            eyesHoldMs: 1500,
+        },
+        roi: {
+            detectionFps: 6,
+            maxRoiWidth: 360,
+            expandBelowRatio: 3,
+            minFaceHeightRatio: 0.18,
+            minFaceAreaRatio: 0.03,
+            meanLum: { min: 70, max: 190 },
+            blurScoreMin: 90,
+        },
+    },
+};

package/dist/utils/faceAnalysis.js

@@ -0,0 +1,144 @@
+export const computeFaceBox = (landmarks) => {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const lm of landmarks) {
+        if (lm.x < minX)
+            minX = lm.x;
+        if (lm.y < minY)
+            minY = lm.y;
+        if (lm.x > maxX)
+            maxX = lm.x;
+        if (lm.y > maxY)
+            maxY = lm.y;
+    }
+    return {
+        x: minX,
+        y: minY,
+        w: Math.max(0, maxX - minX),
+        h: Math.max(0, maxY - minY),
+    };
+};
+export const captureFrameToCanvas = (video, canvas, ctx) => {
+    ctx.drawImage(video, 0, 0, canvas.width, canvas.height);
+};
+export const computeMeanLuminance = (imageData) => {
+    const { data } = imageData;
+    const totalPixels = data.length / 4;
+    let sum = 0;
+    for (let i = 0; i < data.length; i += 4) {
+        const r = data[i];
+        const g = data[i + 1];
+        const b = data[i + 2];
+        sum += 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    }
+    return totalPixels > 0 ? sum / totalPixels : 0;
+};
+export const computeOverexposureRatio = (imageData) => {
+    const { data } = imageData;
+    const totalPixels = data.length / 4;
+    let overexposed = 0;
+    for (let i = 0; i < data.length; i += 4) {
+        const r = data[i];
+        const g = data[i + 1];
+        const b = data[i + 2];
+        if (r > 245 && g > 245 && b > 245) {
+            overexposed += 1;
+        }
+    }
+    return totalPixels > 0 ? overexposed / totalPixels : 0;
+};
+export const computeBlurLaplacianVariance = (imageData) => {
+    const { data, width, height } = imageData;
+    if (width < 3 || height < 3) {
+        return 0;
+    }
+    const gray = new Float32Array(width * height);
+    for (let i = 0, p = 0; i < data.length; i += 4, p += 1) {
+        const r = data[i];
+        const g = data[i + 1];
+        const b = data[i + 2];
+        gray[p] = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    }
+    let sum = 0;
+    let sumSq = 0;
+    let count = 0;
+    for (let y = 1; y < height - 1; y += 1) {
+        for (let x = 1; x < width - 1; x += 1) {
+            const idx = y * width + x;
+            const lap = -4 * gray[idx] +
+                gray[idx - 1] +
+                gray[idx + 1] +
+                gray[idx - width] +
+                gray[idx + width];
+            sum += lap;
+            sumSq += lap * lap;
+            count += 1;
+        }
+    }
+    if (count === 0) {
+        return 0;
+    }
+    const mean = sum / count;
+    return sumSq / count - mean * mean;
+};
+const NOSE_TIP_INDEX = 1;
+const MOUTH_LEFT_INDEX = 61;
+const MOUTH_RIGHT_INDEX = 291;
+const LEFT_EYE_INDEX = 33;
+const RIGHT_EYE_INDEX = 263;
+const LEFT_CHEEK_INDEX = 234;
+const RIGHT_CHEEK_INDEX = 454;
+const distance = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+export const estimatePoseFromLandmarks = (landmarks, config) => {
+    const nose = landmarks[NOSE_TIP_INDEX];
+    const mouthLeft = landmarks[MOUTH_LEFT_INDEX];
+    const mouthRight = landmarks[MOUTH_RIGHT_INDEX];
+    const leftEye = landmarks[LEFT_EYE_INDEX];
+    const rightEye = landmarks[RIGHT_EYE_INDEX];
+    const leftCheek = landmarks[LEFT_CHEEK_INDEX];
+    const rightCheek = landmarks[RIGHT_CHEEK_INDEX];
+    if (!nose ||
+        !mouthLeft ||
+        !mouthRight ||
+        !leftEye ||
+        !rightEye ||
+        !leftCheek ||
+        !rightCheek) {
+        return {
+            yawDeg: 0,
+            pitchDeg: 0,
+            rollDeg: 0,
+            valid: false,
+        };
+    }
+    const rollRad = Math.atan2(rightEye.y - leftEye.y, rightEye.x - leftEye.x);
+    const rollDeg = (rollRad * 180) / Math.PI;
+    const distLeft = distance(nose, leftCheek);
+    const distRight = distance(nose, rightCheek);
+    const yawSignal = distLeft + distRight > 0
+        ? (distRight - distLeft) / (distRight + distLeft)
+        : 0;
+    const yawDeg = yawSignal * config.yawScale;
+    const eyesMid = {
+        x: (leftEye.x + rightEye.x) / 2,
+        y: (leftEye.y + rightEye.y) / 2,
+    };
+    const mouthMid = {
+        x: (mouthLeft.x + mouthRight.x) / 2,
+        y: (mouthLeft.y + mouthRight.y) / 2,
+    };
+    const eyesToNose = distance(eyesMid, nose);
+    const noseToMouth = distance(nose, mouthMid);
+    const pitchSignal = eyesToNose + noseToMouth > 0
+        ? (noseToMouth - eyesToNose) / (noseToMouth + eyesToNose)
+        : 0;
+    const pitchDeg = pitchSignal * config.pitchScale;
+    return {
+        yawDeg,
+        pitchDeg,
+        rollDeg,
+        valid: true,
+    };
+};

package/dist/utils/faceChecks.js

@@ -0,0 +1,84 @@
+import { computeFaceBox, estimatePoseFromLandmarks, } from './faceAnalysis';
+export const evaluateFace = (faceLandmarks, meanLum, overexposureRatio, blurScore, config) => {
+    const faceCount = faceLandmarks.length;
+    let faceBox = null;
+    let pose = null;
+    if (faceCount === 1) {
+        faceBox = computeFaceBox(faceLandmarks[0]);
+        pose = estimatePoseFromLandmarks(faceLandmarks[0], config.pose);
+    }
+    let hint = '';
+    let pass = true;
+    if (faceCount === 0) {
+        hint = 'Show your face in the frame';
+        pass = false;
+    }
+    else if (faceCount > 1) {
+        hint = 'Only one person in frame';
+        pass = false;
+    }
+    else if (faceBox) {
+        if (faceBox.h < config.minHeightRatio) {
+            hint = 'Move closer';
+            pass = false;
+        }
+        else if (faceBox.h > config.maxHeightRatio) {
+            hint = 'Move a bit back';
+            pass = false;
+        }
+        else {
+            const margin = config.marginRatio;
+            const insideMargins = faceBox.x >= margin &&
+                faceBox.y >= margin &&
+                faceBox.x + faceBox.w <= 1 - margin &&
+                faceBox.y + faceBox.h <= 1 - margin;
+            if (!insideMargins) {
+                hint = 'Center your face';
+                pass = false;
+            }
+            else if (pose?.valid && Math.abs(pose.yawDeg) > config.pose.yawMax) {
+                hint = pose.yawDeg > 0 ? 'Turn your face slightly right' : 'Turn your face slightly left';
+                pass = false;
+            }
+            else if (pose?.valid && Math.abs(pose.pitchDeg) > config.pose.pitchMax) {
+                hint = pose.pitchDeg > 0 ? 'Lower your chin slightly' : 'Raise your chin slightly';
+                pass = false;
+            }
+            else if (pose?.valid && Math.abs(pose.rollDeg) > config.pose.rollMax) {
+                hint = pose.rollDeg > 0 ? 'Tilt your head left slightly' : 'Tilt your head right slightly';
+                pass = false;
+            }
+            else if (meanLum < config.meanLum.min) {
+                hint = 'Move to a brighter place';
+                pass = false;
+            }
+            else if (meanLum > config.meanLum.max ||
+                overexposureRatio > config.overexposureRatioMax) {
+                hint = 'Avoid direct light';
+                pass = false;
+            }
+            else if (blurScore < config.blurScoreMin) {
+                hint = 'Hold still';
+                pass = false;
+            }
+        }
+    }
+    if (pass && !hint) {
+        hint = 'Hold still for a moment';
+    }
+    return {
+        pass,
+        hint,
+        metrics: {
+            faceCount,
+            faceBox,
+            meanLum,
+            blurScore,
+            overexposureRatio,
+            yawDeg: pose?.yawDeg ?? 0,
+            pitchDeg: pose?.pitchDeg ?? 0,
+            rollDeg: pose?.rollDeg ?? 0,
+            poseValid: pose?.valid ?? false,
+        },
+    };
+};

package/dist/utils/idPlacement.js

@@ -0,0 +1,66 @@
+const NOSE_TIP_INDEX = 1;
+const MOUTH_LEFT_INDEX = 61;
+const MOUTH_RIGHT_INDEX = 291;
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+const clampRect = (rect) => {
+    const w = clamp(rect.w, 0, 1);
+    const h = clamp(rect.h, 0, 1);
+    const x = clamp(rect.x, 0, 1 - w);
+    const y = clamp(rect.y, 0, 1 - h);
+    return { x, y, w, h };
+};
+const lerp = (from, to, alpha) => from + (to - from) * alpha;
+const smoothRect = (prev, next, alpha) => {
+    if (!prev) {
+        return next;
+    }
+    return {
+        x: lerp(prev.x, next.x, alpha),
+        y: lerp(prev.y, next.y, alpha),
+        w: lerp(prev.w, next.w, alpha),
+        h: lerp(prev.h, next.h, alpha),
+    };
+};
+export const updateIdRect = (state, landmarks, faceBox, nowMs, config) => {
+    if (!landmarks || !faceBox) {
+        const missingTooLong = !state.rect ||
+            nowMs - state.lastSeenMs > config.missingHoldMs;
+        return {
+            rect: state.rect,
+            state,
+            missingTooLong,
+        };
+    }
+    const nose = landmarks[NOSE_TIP_INDEX];
+    const mouthLeft = landmarks[MOUTH_LEFT_INDEX];
+    const mouthRight = landmarks[MOUTH_RIGHT_INDEX];
+    if (!nose || !mouthLeft || !mouthRight) {
+        const missingTooLong = !state.rect ||
+            nowMs - state.lastSeenMs > config.missingHoldMs;
+        return {
+            rect: state.rect,
+            state,
+            missingTooLong,
+        };
+    }
+    const mouthCenterX = (mouthLeft.x + mouthRight.x) / 2;
+    const rectWidth = clamp(faceBox.w * config.rectWidthScale, config.rectWidthMin, config.rectWidthMax);
+    const rectHeight = rectWidth / config.rectAspect;
+    const rectTopY = nose.y + config.rectTopOffset;
+    const nextRect = clampRect({
+        x: mouthCenterX - rectWidth / 2,
+        y: rectTopY,
+        w: rectWidth,
+        h: rectHeight,
+    });
+    const smoothed = smoothRect(state.rect, nextRect, config.smoothAlpha);
+    const updatedState = {
+        rect: smoothed,
+        lastSeenMs: nowMs,
+    };
+    return {
+        rect: smoothed,
+        state: updatedState,
+        missingTooLong: false,
+    };
+};

package/dist/utils/overlayDraw.js

@@ -0,0 +1,96 @@
+const drawRoundedRect = (ctx, x, y, width, height, radius) => {
+    const r = Math.min(radius, width / 2, height / 2);
+    ctx.beginPath();
+    ctx.moveTo(x + r, y);
+    ctx.lineTo(x + width - r, y);
+    ctx.arcTo(x + width, y, x + width, y + r, r);
+    ctx.lineTo(x + width, y + height - r);
+    ctx.arcTo(x + width, y + height, x + width - r, y + height, r);
+    ctx.lineTo(x + r, y + height);
+    ctx.arcTo(x, y + height, x, y + height - r, r);
+    ctx.lineTo(x, y + r);
+    ctx.arcTo(x, y, x + r, y, r);
+    ctx.closePath();
+};
+export const drawOverlay = (ctx, width, height, options) => {
+    ctx.clearRect(0, 0, width, height);
+    const strokeColor = options.statusColor === 'green'
+        ? '#46e3a8'
+        : options.statusColor === 'yellow'
+            ? '#f7c452'
+            : '#ff6b6b';
+    if (options.step === 'FACE_ALIGN') {
+        const centerX = width / 2;
+        const centerY = height / 2;
+        const radiusX = options.faceConfig.ovalRxRatio * width;
+        const radiusY = options.faceConfig.ovalRyRatio * height;
+        ctx.save();
+        ctx.fillStyle = 'rgba(8, 12, 16, 0.55)';
+        ctx.fillRect(0, 0, width, height);
+        ctx.globalCompositeOperation = 'destination-out';
+        ctx.beginPath();
+        ctx.ellipse(centerX, centerY, radiusX, radiusY, 0, 0, Math.PI * 2);
+        ctx.fill();
+        ctx.restore();
+        ctx.save();
+        ctx.strokeStyle = strokeColor;
+        ctx.lineWidth = 3;
+        ctx.shadowColor = strokeColor;
+        ctx.shadowBlur = 12;
+        ctx.beginPath();
+        ctx.ellipse(centerX, centerY, radiusX, radiusY, 0, 0, Math.PI * 2);
+        ctx.stroke();
+        ctx.restore();
+    }
+    else if (options.idRect) {
+        const rect = options.idRect;
+        let rectX = rect.x * width;
+        let rectY = rect.y * height;
+        let rectW = rect.w * width;
+        let rectH = rect.h * height;
+        const videoSize = options.videoSize;
+        if (videoSize && videoSize.width > 0 && videoSize.height > 0) {
+            const scale = Math.max(width / videoSize.width, height / videoSize.height);
+            const drawWidth = videoSize.width * scale;
+            const drawHeight = videoSize.height * scale;
+            const offsetX = (width - drawWidth) / 2;
+            const offsetY = (height - drawHeight) / 2;
+            rectX = offsetX + rect.x * drawWidth;
+            rectY = offsetY + rect.y * drawHeight;
+            rectW = rect.w * drawWidth;
+            rectH = rect.h * drawHeight;
+        }
+        ctx.save();
+        ctx.fillStyle = 'rgba(8, 12, 16, 0.55)';
+        ctx.fillRect(0, 0, width, height);
+        ctx.globalCompositeOperation = 'destination-out';
+        drawRoundedRect(ctx, rectX, rectY, rectW, rectH, 18);
+        ctx.fill();
+        ctx.restore();
+        ctx.save();
+        ctx.strokeStyle = strokeColor;
+        ctx.lineWidth = 3;
+        ctx.shadowColor = strokeColor;
+        ctx.shadowBlur = 12;
+        drawRoundedRect(ctx, rectX, rectY, rectW, rectH, 18);
+        ctx.stroke();
+        ctx.restore();
+    }
+    const hintText = options.hint;
+    const fontSize = Math.max(9, Math.round(height * 0.02));
+    ctx.font = `600 ${fontSize}px "Sora", sans-serif`;
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    const textWidth = ctx.measureText(hintText).width;
+    const paddingX = 18;
+    const paddingY = 10;
+    const boxWidth = textWidth + paddingX * 2;
+    const boxHeight = fontSize + paddingY * 2;
+    const boxX = width / 2 - boxWidth / 2;
+    const boxY = height - boxHeight - Math.max(16, height * 0.06);
+    ctx.fillStyle = 'rgba(8, 12, 16, 0.7)';
+    drawRoundedRect(ctx, boxX, boxY, boxWidth, boxHeight, 18);
+    ctx.fill();
+    ctx.fillStyle = '#f8fafc';
+    ctx.fillText(hintText, width / 2, boxY + boxHeight / 2);
+};