@signosoft/signpad-js 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -2,142 +2,875 @@ import { CSSResult } from 'lit';
 import { LitElement } from 'lit';
 import { TemplateResult } from 'lit-html';
 
+declare class ButtonManager {
+    private component;
+    constructor(component: SignosoftSignpad);
+    /**
+     * Clears the current signature on device and UI, then dispatches SIGN_CLEAR.
+     * @returns Resolves when the clear flow completes.
+     */
+    handleClear(): Promise<void>;
+    /**
+     * Finalizes the signature, dispatches SIGN_OK, and returns captured data.
+     * @returns Captured signature payload from the driver.
+     */
+    handleOk(): Promise<any>;
+    /**
+     * Cancels the signature without collecting data, dispatches SIGN_CANCEL.
+     * @returns Resolves when the cancel flow completes.
+     */
+    handleCancel(): Promise<void>;
+    /**
+     * Starts a new signing session and transitions to the ready state.
+     * @param drawingOptions - Optional line thickness and color settings.
+     * @returns Resolves when the session is ready.
+     */
+    startSigning(drawingOptions?: IDrawingOptions): Promise<void>;
+    /**
+     * Stops the current signing session and returns captured data.
+     * @returns Captured signature payload from the driver.
+     */
+    stopSigning(): Promise<any>;
+    /**
+     * Shared template for OK, Cancel, and Clear actions.
+     * @param processingState - State used while processing the action.
+     * @param actionLogic - Action-specific logic to execute.
+     * @returns Result produced by the action logic.
+     */
+    private executeAction;
+    /**
+     * Resolves the ready state based on current connection type.
+     * @returns The next ready state (physical or fallback).
+     */
+    private getReadyState;
+    /**
+     * Handles post-action flow (state transition or auto-restart).
+     * @returns Resolves after state transition or auto-restart completes.
+     */
+    private finalizePostAction;
+    /**
+     * Fallback handling when startSigning cannot proceed.
+     */
+    private handleStartSigningError;
+    /**
+     * Centralized error handling for button actions.
+     * @param message - Human-readable error description.
+     * @param error - Original error instance.
+     */
+    private handleError;
+}
+
 /**
- * `signosoft-signpad` web component for capturing signatures using a tablet or mouse.
- * This component orchestrates signature capture, manages canvas drawing,
- * handles mouse input fallback, and provides custom events for application integration.
- *
- * @element signosoft-signpad
- *
- * @fires sign-pen - Fired on every pen movement (Wacom or mouse) with `penData` in `event.detail`.
- * @fires sign-clear - Fired when the signature is cleared (via internal UI button, tablet event, or by calling the public `clear()` method).
- * @fires sign-cancel - Fired when the signature process is cancelled (via internal UI button, tablet event, or by calling the public `cancel()` method).
- * @fires sign-ok - Fired when the 'OK' action is completed (via internal UI button, tablet event, or by calling the public `ok()` method).
- * @fires sign-disconnect - Fired if the tablet unexpectedly disconnects.
- * @fires sign-error - Fired when an error occurs during connection or initialization.
+ * `CanvasManager` handles all low-level drawing operations on the HTMLCanvasElement.
+ * It manages DPI scaling for high-resolution displays, stroke interpolation,
+ * pressure-sensitive line thickness, and canvas state.
+ */
+declare class CanvasManager {
+    /** @private The target canvas element */
+    private canvas;
+    /** @private The 2D rendering context */
+    private ctx;
+    /** @private The last point processed in the current stroke */
+    private lastDrawPoint;
+    /** @private The active configuration for line styles */
+    private currentDrawingOptions;
+    /**
+     * Creates an instance of CanvasManager.
+     * @param canvas - The HTMLCanvasElement to draw on.
+     * @param initialDrawingOptions - Configuration for colors and line thickness.
+     */
+    constructor(canvas: HTMLCanvasElement, initialDrawingOptions?: IDrawingOptions);
+    /**
+     * Returns the currently active drawing configuration.
+     * @returns A copy of the current drawing options.
+     */
+    get drawingOptions(): IDrawingOptions;
+    /**
+     * Updates the drawing options and immediately applies them to the context.
+     * @param options - The new drawing configuration.
+     */
+    updateDrawingOptions(options: IDrawingOptions): void;
+    /**
+     * Draws a line segment between the previous point and the current pen data.
+     * Handles coordinate normalization and pressure-based thickness.
+     * @param penData - Data containing coordinates (0-1), pressure, and contact status.
+     */
+    drawSegment(penData: IPenData): void;
+    /**
+     * Wipes the canvas clean and resets the drawing state.
+     */
+    clear(): void;
+    /**
+     * Adjusts the canvas internal resolution to match high-DPI (Retina) screens.
+     * Prevents signatures from appearing blurry.
+     * @private
+     */
+    private configureCanvasForDPI;
+    /**
+     * Applies line caps, joins, and composite operations to the rendering context.
+     * @param options - The style options to apply.
+     * @private
+     */
+    private applyDrawingStyles;
+}
+
+/**
+ * Handles config-driven side effects for the signpad component.
+ */
+declare class ConfigManager {
+    private component;
+    private configEventHandlers;
+    /**
+     * @param component - The host SignosoftSignpad instance.
+     */
+    constructor(component: SignosoftSignpad);
+    /**
+     * Applies config-driven side effects (localization, drawing, callbacks).
+     * @param prevConfig - Optional previous config for diffing.
+     */
+    apply(prevConfig?: SignpadConfig): void;
+    /**
+     * Applies custom CSS variables from the config to the host element.
+     */
+    applyCssVariables(): void;
+    /**
+     * Returns resolved UI visibility options with defaults applied.
+     * @returns UI visibility options.
+     */
+    getUiVisibilityOptions(): IUIVisibilityOptions;
+    /**
+     * Returns resolved drawing options with defaults applied.
+     * @returns Drawing options for the canvas.
+     */
+    getDrawingOptions(): IDrawingOptions;
+    /**
+     * Applies localization updates when language configuration changes.
+     * @param prevConfig - Previous configuration.
+     * @param currentConfig - Current configuration.
+     */
+    private applyLocalization;
+    /**
+     * Applies drawing option updates when configuration changes.
+     * @param prevConfig - Previous configuration.
+     * @param currentConfig - Current configuration.
+     */
+    private applyDrawingOptions;
+    /**
+     * Syncs config-provided event handlers with component listeners,
+     * adding, replacing, or removing them as needed.
+     * @param config - Current signpad configuration.
+     */
+    private syncConfigEventHandlers;
+    /**
+     * Removes all config-based event handlers from the component.
+     */
+    private clearConfigEventHandlers;
+}
+
+/**
+ * `ConnectionManager` handles the lifecycle of the signature pad connection.
+ * It manages driver initialization, license authentication, device handshaking,
+ * and event forwarding from the physical driver to the component.
+ */
+declare class ConnectionManager {
+    /** @private Reference to the parent component */
+    private component;
+    /** @private The low-level driver instance */
+    private sigLayer;
+    /** @private Debug counter for callback registrations */
+    private debugCallbackRegistrationCount;
+    /** @private Offscreen canvas used to capture driver input without direct UI interference */
+    private offscreenDrawingCanvas;
+    /** @private Cached device info from the last successful connect */
+    private cachedDeviceInfo;
+    /** @private Tracks SignatureLayer initialization state */
+    private sigLayerInitialized;
+    /** @private License server endpoint */
+    private licenseServerUrl;
+    /** @private Timestamp of the last pen event dispatch */
+    private lastPenDispatchTime;
+    /** @private Buffered pen data for throttling */
+    private penDataToDispatch;
+    /** @private Minimum delay between pen events (approx 60fps) */
+    private throttleDelayMs;
+    private fetchShimInstalled;
+    /**
+     * @param component - The host SignosoftSignpad instance.
+     */
+    constructor(component: SignosoftSignpad);
+    /**
+     * Initiates the connection process to a physical device or a mouse fallback.
+     *
+     * @param autoConnect - If true, attempts to connect without showing a device selection dialog.
+     * @param allowFallback - If true, enables mouse/pointer input if no physical device is found.
+     * @returns A promise resolving to true if connection (or fallback) was successful.
+     */
+    connect(autoConnect?: boolean, allowFallback?: boolean): Promise<boolean>;
+    /**
+     * Terminates the connection with the device and cleans up the driver instance.
+     * @returns Resolves when disconnection completes.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Returns true when a SignatureLayer instance exists.
+     * @returns True if the driver instance is available.
+     */
+    hasSignatureLayer(): boolean;
+    /**
+     * Returns the device info from SignatureLayer if available.
+     * @returns Device info or null if unavailable.
+     */
+    getDeviceInfo(): Promise<any | null>;
+    /**
+     * Returns true if the SignatureLayer reports an active connection.
+     * @returns True if a device is connected.
+     */
+    isDeviceConnected(): boolean;
+    /**
+     * Returns true if the SignatureLayer is in signing mode.
+     * @returns True if a signing session is active.
+     */
+    isSigningActive(): boolean;
+    /**
+     * Starts a signing session on the provided canvas.
+     * @param canvasElement - Optional canvas reference.
+     * @param drawingOptions - Optional drawing options.
+     * @returns A promise resolving to true if the session started successfully.
+     */
+    startSigning(canvas: HTMLCanvasElement, drawingOptions?: IDrawingOptions): Promise<boolean>;
+    /**
+     * Stops the current signing session if active.
+     * @returns Signature data if available.
+     */
+    stopSigning(): Promise<any>;
+    /**
+     * Clears the signature on the device if a signing session is active.
+     * Silently does nothing if no session is active.
+     * @returns Resolves when the clear completes.
+     */
+    clearSignature(): Promise<void>;
+    /**
+     * Instantiates the SignatureLayer if it doesn't exist and attaches listeners.
+     * @returns Resolves when the driver is ready.
+     */
+    private ensureSignatureLayer;
+    /**
+     * Configures driver event listeners (OK, Clear, Cancel, Pen events).
+     * @returns void
+     */
+    private setupCallbacks;
+    /**
+     * Throttles pen data dispatches to optimize event bus performance.
+     * @param data - The IPenData received from the driver.
+     */
+    private runThrottledPenDispatch;
+    /**
+     * Fetches a lease from the license server and initializes the driver.
+     * @returns Resolves when the driver is initialized.
+     */
+    private initializeTabletWithLicense;
+    /**
+     * Installs a fetch shim to resolve lib assets when bundled.
+     */
+    private installLibAsset;
+    isFallback(deviceInfo: any | null, isDeviceConnected: boolean, includeDisconnected: boolean): boolean;
+    /**
+     * Normalizes device info to always include deviceName.
+     * @param deviceInfo - Raw device info.
+     * @returns Normalized device info or null.
+     */
+    private normalizeDeviceInfo;
+}
+
+export declare enum DeviceStatusText {
+    NOT_CONNECTED = "NOT_CONNECTED",
+    CONNECTED = "CONNECTED",
+    CONNECTING = "CONNECTING",
+    MOUSE = "MOUSE",
+    CONNECTED_UNKNOWN = "CONNECTED_UNKNOWN_DEVICE"
+}
+
+export declare interface IActionHandlers {
+    handleOk?: () => any | Promise<any>;
+    handleClear?: () => any | Promise<any>;
+    handleCancel?: () => any | Promise<any>;
+}
+
+export declare interface IAutoconnectOptions {
+    autoConnect?: boolean;
+    autoConnectOnPlugIn?: boolean;
+    autoRestartSigningAfterAction?: boolean;
+}
+
+export declare interface IDrawingOptions {
+    minWidth?: number;
+    maxWidth?: number;
+    color?: string;
+}
+
+export declare interface IDriverInfo {
+    name: string;
+    ready: boolean;
+    aspectRatio: number;
+    isCanvasStyleTablet: boolean;
+    supportedCommands: string[];
+}
+
+export declare interface IEventCallbacks {
+    onConnect?: (event: CustomEvent<{
+        deviceInfo: any;
+    }>) => void;
+    onDisconnect?: (event: CustomEvent<void>) => void;
+    onPen?: (event: CustomEvent<PenData>) => void;
+    onOk?: (event: CustomEvent<void>) => void;
+    onClear?: (event: CustomEvent<void>) => void;
+    onCancel?: (event: CustomEvent<void>) => void;
+    onError?: (event: CustomEvent<Error>) => void;
+}
+
+export declare interface ILanguageOptions {
+    lang?: LanguageCode;
+    langPath?: string;
+    translations?: ITranslationSet | Record<string, ITranslationSet>;
+}
+
+export declare type IPenData = {
+    relativeX: number;
+    relativeY: number;
+    absoluteX?: number;
+    absoluteY?: number;
+    pressure?: number;
+    timestamp?: number;
+    inContact: boolean;
+    [key: string]: any;
+};
+
+export declare interface IPenDataCallback {
+    (penData: PenData): void;
+}
+
+export declare interface ITranslationSet {
+    [key: string]: string;
+}
+
+export declare interface IUIVisibilityOptions {
+    topBarVisible?: boolean;
+    topBarClearButtonVisible?: boolean;
+    bottomBarVisible?: boolean;
+    okButtonVisible?: boolean;
+    clearButtonVisible?: boolean;
+    cancelButtonVisible?: boolean;
+    canvasLineVisible?: boolean;
+    deviceStatusTextVisible?: boolean;
+    additionalTextVisible?: boolean;
+}
+
+export declare type LanguageCode = "en" | "cs" | "pt" | (string & {});
+
+/**
+ * Manages localization for the signpad component.
  *
- * @property {string} licenseKey - Backend license key for the signature driver.
- * @property {boolean} topBarVisible - Controls the visibility of the top action bar.
- * @property {boolean} bottomBarVisible - Controls the visibility of the bottom action bar with OK, Clear, Cancel buttons.
- * @property {boolean} okButtonVisible - Controls the visibility of the 'OK' button.
- * @property {boolean} clearButtonVisible - Controls the visibility of the 'Clear' button.
- * @property {boolean} cancelButtonVisible - Controls the visibility of the 'Cancel' button.
- * @property {boolean} canvasLineVisible - Controls the visibility of the line on the canvas.
- * @property {boolean} deviceStateTextVisible - Controls the visibility of the device state text.
- * @property {string | null} [customDeviceStateText] - Optional custom text to display for the device state, overriding the default.
- * @property {number} minThickness - Minimum pen stroke thickness in pixels.
- * @property {number} maxThickness - Maximum pen stroke thickness in pixels (at full pressure).
- * @property {string} penColor - Pen stroke color (CSS color, e.g., '#000000' or 'red').
- * @property {Record<string, string>} [customCssVariables] - An object containing CSS custom property names as keys and their values as strings. These will be applied directly to the component's host element for styling customization.
- * @property {function} [OkButton] - Optional callback function (async or sync) to execute when the public `ok()` method is called, either internally or externally. It runs after the component's internal processing.
- * @property {function} [ClearButton] - Optional callback function (async or sync) to execute when the public `clear()` method is called, either internally or externally. It runs after the component's internal processing.
- * @property {function} [CancelButton] - Optional callback function (async or sync) to execute when the public `cancel()` method is called, either internally or externally. It runs after the component's internal processing.
- * @property {string | null} [canvasAdditionalText] - Optional additional text to display in the canvas footer. If null or empty, a default text will be shown. Default behavior is "Sign area with mouse or pen" when disconnected/error, and "Sign with [device name]" when connected.
+ * This manager supports:
+ * 1. Built-in translations (English as default fallback).
+ * 2. External translation overrides via remote JSON files.
+ * 3. Dynamic parameter interpolation in strings.
+ */
+declare class LocalizationManager {
+    /** @private Reference to the parent component to trigger updates */
+    private component;
+    /** @private The currently active translation dictionary */
+    private translations;
+    /** @private The ISO code of the currently loaded language */
+    private currentLang;
+    /** @private The last used path for external translations */
+    private currentPath;
+    /**
+     * @param component - The LitElement instance that uses this manager.
+     */
+    constructor(component: LitElement);
+    /**
+     * Translates a key based on the loaded dictionary.
+     * Supports parameter interpolation using the `{key}` syntax.
+     *
+     * @param key - The translation key (e.g., "CONNECT_DEVICE").
+     * @param params - Key-value pairs to replace placeholders in the string.
+     * @returns The translated string, or the raw key if no translation exists.
+     */
+    t(key: string, params?: Record<string, string>): string;
+    /**
+     * Loads and merges translations for the specified language.
+     *
+     * Strategy:
+     * 1. Check for redundancy: If lang and path haven't changed, skip.
+     * 2. Baseline: Start with built-in translations (merged with English as fallback).
+     * 3. Fetch: If a path is provided, attempt to fetch an external JSON file.
+     * 4. Merge: External translations override built-in ones.
+     *
+     * @param langCode - ISO language code (e.g., 'en', 'cs', 'de').
+     * @param basePath - Optional path/URL to fetch external translation files.
+     * @param inlineTranslations - Optional inline translations to apply.
+     * @returns Resolves when translations are loaded and applied.
+     */
+    loadLanguage(langCode: string, basePath?: string, inlineTranslations?: ITranslationSet | Record<string, ITranslationSet>): Promise<void>;
+    /**
+     * Determines the initial translation set.
+     * If the language is built-in, it merges it with English to ensure no missing keys.
+     *
+     * @param langCode - The target language code.
+     * @returns Baseline translations for the language.
+     */
+    private getBaselineTranslations;
+    /**
+     * Resolves inline translations for the requested language, if provided.
+     * @param langCode - The target language code.
+     * @param inline - Inline translation map or set.
+     * @returns Inline translations for the language if found.
+     */
+    private resolveInlineTranslations;
+    /**
+     * Constructs the full URL for the translation JSON file.
+     *
+     * @param langCode - The language code.
+     * @param basePath - The directory path.
+     * @returns Resolved translation file URL.
+     */
+    private constructUrl;
+}
+
+/**
+ * `MouseManager` handles mouse interactions on a canvas element and converts them
+ * into standardized `IPenData`. This serves as a fallback mechanism for
+ * signature capture when a physical signature tablet is not available.
+ */
+declare class MouseManager {
+    /** @private */
+    private canvas;
+    /** @private */
+    private onPenData;
+    /** @private */
+    private isDrawing;
+    /** @private */
+    private sequenceCounter;
+    /** @private */
+    private sessionStartTime;
+    /** @private Debug counter for listener registrations */
+    private debugListenerRegistrationCount;
+    /** @private */
+    private listenersAttached;
+    private boundHandleMouseDown;
+    private boundHandleMouseMove;
+    private boundHandleMouseUp;
+    private boundHandleMouseLeave;
+    /**
+     * Creates an instance of MouseManager.
+     * @param canvas - The HTMLCanvasElement to attach mouse listeners to.
+     * @param onPenDataCallback - The callback function that receives generated IPenData.
+     */
+    constructor(canvas: HTMLCanvasElement, onPenDataCallback: IPenDataCallback);
+    /**
+     * Returns whether the user is currently in the middle of a drawing stroke.
+     */
+    get isCurrentlyDrawing(): boolean;
+    /**
+     * Attaches mouse event listeners to the canvas to enable signature capture.
+     */
+    addListeners(): void;
+    /**
+     * Removes mouse event listeners from the canvas and stops active drawing.
+     */
+    removeListeners(): void;
+    /**
+     * Returns true if mouse listeners are currently attached.
+     */
+    areListenersAttached(): boolean;
+    /**
+     * Resets the internal session state, including sequence counters and start time.
+     */
+    resetSession(): void;
+    /**
+     * Handles the 'mousedown' event: starts a stroke and initializes the session time.
+     * @private
+     */
+    private handleMouseDown;
+    /**
+     * Handles the 'mousemove' event: continues the stroke if mouse is down.
+     * @private
+     */
+    private handleMouseMove;
+    /**
+     * Handles the 'mouseup' event: ends the stroke.
+     * @private
+     */
+    private handleMouseUp;
+    /**
+     * Handles the 'mouseleave' event: ends the stroke if the mouse leaves the canvas area.
+     * @private
+     */
+    private handleMouseLeave;
+    /**
+     * Core logic to transform a MouseEvent into IPenData.
+     * @param event - The raw browser MouseEvent.
+     * @param inContact - Whether the "pen" (mouse button) is touching the surface.
+     * @private
+     */
+    private processMouseEvent;
+    /**
+     * Converts absolute mouse coordinates into a normalized 0-1 range relative to canvas size.
+     * @private
+     */
+    private getNormalizedCoordinates;
+    /**
+     * Calculates the seconds elapsed since the start of the signature session.
+     * @private
+     */
+    private timestampToSeconds;
+}
+
+/**
+ * SignosoftSignpad Web Component.
+ * A professional signature capture component supporting physical tablets and mouse fallback.
  */
 export declare class SignosoftSignpad extends LitElement {
-    licenseKey: string;
-    canvasAdditionalText: string | null;
-    topBarVisible: boolean;
-    bottomBarVisible: boolean;
-    okButtonVisible: boolean;
-    clearButtonVisible: boolean;
-    cancelButtonVisible: boolean;
-    canvasLineVisible: boolean;
-    deviceStateTextVisible: boolean;
-    customDeviceStateText: string | null;
-    minThickness: number;
-    maxThickness: number;
-    penColor: string;
-    OkButton?: () => Promise<void>;
-    ClearButton?: () => Promise<void>;
-    CancelButton?: () => Promise<void>;
-    customCssVariables: Record<string, string>;
+    #private;
+    /**
+     * Main configuration object for the signpad.
+     * Settable from outside via property binding.
+     */
+    config: SignpadConfig;
+    /**
+     * Reference to the internal canvas element.
+     * @private
+     */
     canvasRef: HTMLCanvasElement;
-    private _deviceStateText;
-    private _isConnected;
-    private _hasStartedDrawing;
-    private _isDisconnectingIntentionally;
-    private licenseServerUrl;
-    private sigLayer;
-    private canvasPainter;
-    private mouseInputHandler;
-    private offscreenDrawingCanvas;
+    /** Current state of the signpad machine. */
+    get currentState(): SignpadState;
+    /** Current status message key for localization. */
+    get statusMessage(): string;
+    /** Boolean flag indicating if the user has started drawing. */
+    get hasStartedDrawing(): boolean;
+    /** Text representation of the current device status. */
+    get deviceStatusText(): string;
+    setCurrentState(value: SignpadState): void;
+    setStatusMessage(value: string): void;
+    setHasStartedDrawing(value: boolean): void;
+    setDeviceStatusText(value: string): void;
+    canvasManager: CanvasManager | null;
+    mouseManager: MouseManager | null;
+    connectionManager: ConnectionManager;
+    stateManager: StateManager;
+    buttonManager: ButtonManager;
+    localizationManager: LocalizationManager;
+    configManager: ConfigManager;
+    webHIDAPI: any;
     static styles: CSSResult[];
-    constructor();
     /**
-     * Invoked once after the component's first render.
-     * Initializes CanvasPainter and MouseInputHandler, then starts driver initialization.
+     * Lit lifecycle: Invoked after the element's DOM has been updated the first time.
+     * Initializes managers and handles auto-connection logic.
+     * @protected
+     * @returns Resolves when initialization completes.
      */
-    protected firstUpdated(): void;
+    protected firstUpdated(): Promise<void>;
     /**
-     * Invoked before the component's render method is called.
-     * Updates CanvasPainter's drawing options if related properties have changed.
+     * Lit lifecycle: Invoked when the element's properties change.
+     * @param changedProperties - Map of changed properties.
+     * @protected
      */
     protected willUpdate(changedProperties: Map<string | number | symbol, unknown>): void;
     /**
-     * Invoked after the component's render method is called and its DOM has been updated.
-     * Applies custom CSS variables from the `customCssVariables` property to the host element.
+     * Lit lifecycle: Invoked after every update.
+     * @protected
      */
     protected updated(changedProperties: Map<PropertyKey, unknown>): void;
     /**
-     * Prepares the SignatureLayer instance.
-     * This method now creates a new instance if `sigLayer` is null.
-     */
-    private prepareSignatureLayer;
-    /**
-     * Sets up internal callbacks for the SignatureLayer instance.
-     * These callbacks ensure that actions from the Wacom tablet (e.g., OK, Clear, Cancel)
-     * trigger the corresponding public methods of this component.
+     * Component constructor.
+     * Initializes all sub-managers.
      */
-    private setupCallbacks;
+    constructor();
     /**
-     * Dispatches a custom event from this web component.
-     * @param name - The name of the custom event to dispatch.
-     * @param [detail] - Optional data to include with the event, accessible via `event.detail`.
+     * Dispatches a custom event from the component.
+     * @param name - The name of the event.
+     * @param detail - Optional data payload for the event.
+     * @returns void
      */
-    private dispatch;
+    dispatch(name: string, detail?: any): void;
     /**
-     * Connects to the signature tablet.
-     * This involves obtaining a license, initializing the signature layer,
-     * connecting to the device, and starting the signing process.
-     * This method strategically passes an offscreen canvas or the actual visible canvas to SignatureLayer
-     * based on the detected device, to prevent unwanted internal drawing by SignatureLayer.
-     * This method can be invoked externally (e.g., from a "Connect Signpad" button).
-     * @param autoConnect - If true, attempts to automatically select the first available device.
-     * @returns True if successfully connected and signing started, false otherwise.
+     * Attempts to establish a connection with a signature tablet.
+     * @param autoConnect - If true, tries to connect without showing a device picker.
+     * @param allowFallback - If true, enables mouse/touch signing if no device is found.
+     * @returns A promise resolving to true if connection (or fallback) succeeded.
      */
-    connectTablet(autoConnect?: boolean): Promise<boolean>;
+    connect(autoConnect?: boolean, allowFallback?: boolean): Promise<boolean>;
     /**
-     * Disconnects from the signature tablet and resets its state.
-     * This method can be invoked externally.
-     * @returns A promise that resolves when the tablet is disconnected.
+     * Closes the active tablet connection and cleans up the state.
+     * @returns A promise that resolves when disconnection is complete.
      */
-    disconnectTablet(): Promise<void>;
+    disconnect(): Promise<void>;
     /**
-     * Clears the current signature from both the tablet's screen and the component's canvas.
-     * Invokes the optional `ClearButton` external callback (if provided)
-     * and then dispatches a 'sign-clear' custom event.
-     * This method can be invoked externally or internally (e.g., from a "Clear" button).
+     * Clears the signature from both the UI canvas and the physical device screen.
+     * @returns Resolves when the clear flow completes.
      */
     clear(): Promise<void>;
     /**
-     * Handles the 'OK' action, typically stopping the signing process and preparing the signature for submission.
-     * If an `OkButton` callback function is provided via properties, it will be executed.
-     * Afterwards, a `sign-ok` custom event is dispatched.
-     * This method can be invoked externally or internally (e.g., from an "OK" button).
+     * Finalizes the signature session (OK action).
+     * @returns Captured signature payload from the driver.
      */
-    ok(): Promise<void>;
+    ok(): Promise<any>;
     /**
-     * Handles the 'Cancel' action, which typically clears any drawn signature and stops the signing process.
-     * If a `CancelButton` callback function is provided via properties, it will be executed.
-     * Finally, a `sign-cancel` custom event is dispatched.
-     * This method can be invoked externally or internally (e.g., from a "Cancel" button).
+     * Aborts the current signature session (Cancel action).
+     * @returns Resolves when the cancel flow completes.
      */
     cancel(): Promise<void>;
     /**
-     * Renders the component's HTML template.
+     * Programmatically starts a new signing session.
+     * @param drawingOptions - Optional settings for line thickness and color.
+     * @returns Resolves when the session is ready.
+     */
+    startSigning(drawingOptions?: IDrawingOptions): Promise<void>;
+    /**
+     * Programmatically stops the current signing session.
+     * @returns Resolves when the session stops.
+     */
+    stopSigning(): Promise<void>;
+    /**
+     * Resets the UI canvas and internal drawing flags.
+     * @returns void
+     */
+    resetDrawingState(): void;
+    /**
+     * Lit lifecycle: Invoked when the component is removed from the document's DOM.
+     * Performs necessary cleanup of listeners and connections.
+     * @returns void
+     */
+    disconnectedCallback(): void;
+    /**
+     * Attaches WebHID API event listeners for device connection and disconnection.
+     * @private
+     * @returns void
+     */
+    private addWebHIDListeners;
+    /**
+     * Removes WebHID API event listeners.
+     * @private
+     * @returns void
+     */
+    private removeWebHIDListeners;
+    /**
+     * Handler for HID device connection.
+     * @private
+     * @returns void
+     */
+    private handleHIDConnect;
+    /**
+     * Handler for HID device disconnection.
+     * @private
+     * @returns void
+     */
+    private handleHIDDisconnect;
+    /**
+     * Initializes the CanvasManager for rendering signature strokes.
+     * @private
+     * @returns void
+     */
+    private initializeCanvasManger;
+    /**
+     * Initializes the MouseManager for mouse and touch fallback.
+     * @private
+     * @returns void
+     */
+    private initializeMouseManager;
+    /**
+     * Renders the HTML template for the component.
+     * Uses Lit's html template literal.
+     * @returns Rendered template.
      */
     render(): TemplateResult<1>;
 }
 
+export declare type SignosoftSignpadProps = {
+    config?: SignpadConfig;
+    class?: string;
+    id?: string;
+    style?: string | Record<string, string>;
+    key?: string | number;
+    ref?: any;
+    children?: any;
+};
+
+export declare interface SignpadConfig {
+    licenseKey?: string;
+    languageOptions?: ILanguageOptions;
+    autoconnectOptions?: IAutoconnectOptions;
+    uiVisibilityOptions?: IUIVisibilityOptions;
+    canvasAndDrawigOptions?: IDrawingOptions;
+    actionHandlers?: IActionHandlers;
+    eventCallbacks?: IEventCallbacks;
+    customCssVariables?: Record<string, string>;
+}
+
+export declare enum SignpadEventType {
+    SIGN_PEN = "sign-pen",
+    SIGN_OK = "sign-ok",
+    SIGN_CLEAR = "sign-clear",
+    SIGN_CANCEL = "sign-cancel",
+    SIGN_ERROR = "sign-error",
+    SIGN_CONNECT = "sign-connect",
+    SIGN_DISCONNECT = "sign-disconnect"
+}
+
+export declare enum SignpadMessage {
+    AUTO_CONNECTING = "AUTO_CONNECTING",
+    CONNECTING_TO_DEVICE = "CONNECTING_TO_DEVICE",
+    DISCONNECTING_DEVICE = "DISCONNECTING_DEVICE",
+    COMPONENT_INITIALIZED = "COMPONENT_INITIALIZED",
+    TEXT_START_SIGNING = "TEXT_START_SIGNING",
+    TEXT_SIGN_WITH_PHYSICAL = "TEXT_SIGN_WITH_PHYSICAL",
+    TEXT_SIGN_WITH_MOUSE = "TEXT_SIGN_WITH_MOUSE",
+    TEXT_SIGN_GENERIC = "TEXT_SIGN_GENERIC",
+    TEXT_SIGNING_WITH_DEVICE = "TEXT_SIGNING_WITH_DEVICE",
+    NO_DEVICE_FOUND = "NO_DEVICE_FOUND",
+    CONNECTION_ERROR = "CONNECTION_ERROR",
+    ERROR_DISCONNECTION = "ERROR_DISCONNECTION",
+    ERROR_INSTANTIATING_DRIVER = "ERROR_INSTANTIATING_DRIVER",
+    SIGNPAD_DISCONNECTED = "SIGNPAD_DISCONNECTED",
+    DEVICE_UNEXPECTEDLY_DISCONNECTED = "DEVICE_UNEXPECTEDLY_DISCONNECTED",
+    SIGN_SUCCESSFUL = "SIGN_SUCCESSFUL",
+    SIGN_CANCELLED = "SIGN_CANCELLED",
+    SIGN_CLEARED = "SIGN_CLEARED",
+    MISSING_LICENSE_KEY = "MISSING_LICENSE_KEY",
+    READY_TO_CONNECT = "READY_TO_CONNECT",
+    SIGNPAD_DETECTED = "SIGNPAD_DETECTED",
+    NO_LICENSE_KEY = "NO_LICENSE_KEY"
+}
+
+export declare enum SignpadState {
+    INITIAL = "initial",
+    DISCONNECTED = "disconnected",
+    FINISHED = "finished",
+    CONNECTING = "connecting",
+    WAITING_FOR_DEVICE_SELECTION = "waiting_for_device_selection",
+    CONNECTED_PHYSICAL = "connected_physical",
+    CONNECTED_MOUSE_FALLBACK = "connected_mouse_fallback",
+    SIGNING_ACTIVE = "signing_active",
+    PROCESSING_OK = "processing_ok",
+    PROCESSING_CLEAR = "processing_clear",
+    PROCESSING_CANCEL = "processing_cancel",
+    DISCONNECTING = "disconnecting",
+    ERROR = "error"
+}
+
+export declare enum SignpadUI {
+    OK = "OK",
+    CLEAR = "CLEAR",
+    CANCEL = "CANCEL",
+    CLEAR_SIGNATURE = "CLEAR_SIGNATURE",
+    DISCONNECT = "DISCONNECT",
+    CONNECT_SIGNPAD = "CONNECT_SIGNPAD"
+}
+
+/**
+ * Manages the finite state machine and UI logic for the Signpad component.
+ * It handles state transitions, side effects (like adding/removing listeners),
+ * and provides computed properties for the UI (button states, visibility, etc.).
+ */
+declare class StateManager {
+    /**
+     * Reference to the parent component.
+     * @private
+     */
+    private component;
+    /**
+     * @param component - The host SignosoftSignpad instance.
+     */
+    constructor(component: SignosoftSignpad);
+    /**
+     * Returns the localization key or device name for the current status.
+     * @returns Localization key or device name.
+     */
+    get deviceStatusKey(): string;
+    /**
+     * Returns the current status message key.
+     * @returns Status message key.
+     */
+    get statusMessageKey(): string;
+    /**
+     * Computes the localization key for instructions based on current state.
+     * Returns null if custom additionalText is provided by the user.
+     * @returns Localization key for additional text.
+     */
+    get additionalTextKey(): string;
+    /**
+     * Returns true if the component is in any connected state (Physical or Fallback).
+     * @returns True when connected or signing.
+     */
+    get isConnected(): boolean;
+    /**
+     * Returns true if the component is performing an asynchronous operation.
+     * @returns True when busy.
+     */
+    get isBusy(): boolean;
+    /**
+     * Returns true if the component is in an ERROR state.
+     * @returns True when in error state.
+     */
+    get isError(): boolean;
+    /**
+     * Logic for disabling primary action buttons (OK, Clear, Cancel).
+     * Buttons are disabled if not connected, if no drawing has occurred, or if busy.
+     * @returns True if action buttons should be disabled.
+     */
+    get actionButtonsDisabled(): boolean;
+    /**
+     * Logic for disabling the Connect button.
+     * @returns True if the connect button should be disabled.
+     */
+    get connectButtonDisabled(): boolean;
+    /**
+     * Logic for disabling the Disconnect button.
+     * @returns True if the disconnect button should be disabled.
+     */
+    get disconnectButtonDisabled(): boolean;
+    /**
+     * Transitions the component to a new state and triggers side effects.
+     *
+     * @param newState - The target SignpadState.
+     * @param messageKey - An optional localization key for status messages.
+     * @param error - Optional error object if transitioning to an ERROR state.
+     * @returns void
+     */
+    transitionTo(newState: SignpadState, messageKey?: string, error?: Error): void;
+    /**
+     * Updates the internal drawing flag. Triggers a UI update if the value changes.
+     * @param started - Boolean indicating if the user has started drawing.
+     */
+    setDrawingStarted(started: boolean): void;
+    /**
+     * Handles side effects triggered by state transitions, such as
+     * initializing mouse listeners or clearing the canvas.
+     * @param newState - The state being transitioned to.
+     * @param oldState - The previous state.
+     * @private
+     */
+    private handleSideEffects;
+}
+
 export { }
+
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "signosoft-signpad": SignosoftSignpad;
+  }
+  namespace JSX {
+    interface IntrinsicElements {
+      "signosoft-signpad": SignosoftSignpadProps;
+    }
+  }
+
+  namespace React {
+    namespace JSX {
+      interface IntrinsicElements {
+        "signosoft-signpad": SignosoftSignpadProps;
+      }
+    }
+  }
+}