@signosoft/signpad-js 0.5.3 → 0.7.0

package/dist/index.d.ts

@@ -1,266 +1,7 @@
-import { ConnectionMode } from '@signosoft/tablet-driver';
 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<ISignatureConfirmationData | undefined>;
-    /**
-     * 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;
-    /**
-     * 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;
-}
-
-/**
- * `CanvasManager` is a lightweight canvas utility.
- * Drawing is handled by SignatureLayer from `@signosoft/tablet-driver`.
- */
-declare class CanvasManager {
-    /** @private The target canvas element */
-    private canvas;
-    /** @private The 2D rendering context */
-    private ctx;
-    /** @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;
-    /**
-     * 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
-     */
-    configureCanvasForDPI(): void;
-    /**
-     * 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;
-    private customEventListenerCache;
-    /**
-     * @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;
-    /**
-     * 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 Cached device info from the last successful connect */
-    private cachedDeviceInfo;
-    /** @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 static readonly POINTER_FALLBACK_DEVICE_NAME;
-    /**
-     * @param component - The host SignosoftSignpad instance.
-     */
-    constructor(component: SignosoftSignpad);
-    /**
-     * Initiates the connection process to a physical device or a mouse fallback.
-     *
-     * @param autoConnect - Connect mode: "manual" opens the browser device selection
-     *   dialog; "auto"/"hotplug" attempt already-authorized devices silently.
-     * @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?: ConnectionMode, 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;
-    /**
-     * 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.
-     */
-    initWithLease(lease: any): Promise<void>;
-    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;
-    /**
-     * Driver connect step (this is where interactive vs silent HID behavior happens).
-     * `autoConnect = false` may open the browser HID picker.
-     * `autoConnect = true` tries reconnecting already-authorized devices silently.
-     */
-    private runDriverConnectAttempt;
-    /**
-     * Chooses whether the component should finish in physical mode or mouse fallback.
-     * This step only decides state; it does not trigger HID dialog itself.
-     */
-    private resolveConnectionTarget;
-}
-
 export declare enum DeviceStatusText {
     MOUSE = "MOUSE",
     CONNECTED_UNKNOWN = "CONNECTED_UNKNOWN_DEVICE"
@@ -288,7 +29,7 @@ export declare interface IEventCallbacks {
     onOk?: (event: CustomEvent<ISignatureConfirmationData>) => void;
     onClear?: (event: CustomEvent<void>) => void;
     onCancel?: (event: CustomEvent<void>) => void;
-    onError?: (event: CustomEvent<Error>) => void;
+    onError?: (event: CustomEvent<ISignpadErrorDetail>) => void;
 }
 
 export declare interface ILanguageOptions {
@@ -360,6 +101,12 @@ export declare interface ISignatureTabletMeta {
     [key: string]: any;
 }
 
+export declare interface ISignpadErrorDetail {
+    code: SignpadErrorCode;
+    message: string;
+    error: Error;
+}
+
 export declare interface ITranslationSet {
     [key: string]: string;
 }
@@ -375,80 +122,11 @@ export declare interface IUIVisibilityOptions {
     canvasLineVisible?: boolean;
     deviceStatusTextVisible?: boolean;
     additionalTextVisible?: boolean;
+    startNewSignatureButtonVisible?: boolean;
 }
 
 export declare type LanguageCode = "en" | "cs" | "pt" | (string & {});
 
-/**
- * Manages localization for the signpad component.
- *
- * 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;
-}
-
 /**
  * SignosoftSignpad Web Component.
  * A professional signature capture component supporting physical tablets and mouse fallback.
@@ -465,25 +143,16 @@ export declare class SignosoftSignpad extends LitElement {
      * @private
      */
     canvasRef: HTMLCanvasElement;
-    /** Current state of the signpad machine. */
-    get currentState(): SignpadState;
+    /** Current state of the signpad machine. Starts as CONNECTING: waiting for the lease before the first connect. */
+    currentState: SignpadState;
     /** Current status message key for localization. */
-    get statusMessage(): string;
+    statusMessage: string;
+    /** Code of the current ERROR, or null outside ERROR. */
+    errorCode: SignpadErrorCode | null;
     /** Boolean flag indicating if the user has started drawing. */
-    get hasStartedDrawing(): boolean;
+    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;
-    connectionManager: ConnectionManager;
-    stateManager: StateManager;
-    buttonManager: ButtonManager;
-    localizationManager: LocalizationManager;
-    configManager: ConfigManager;
-    webHIDAPI: any;
+    deviceStatusText: string;
     clear: () => Promise<void>;
     ok: () => Promise<ISignatureConfirmationData | undefined>;
     cancel: () => Promise<void>;
@@ -508,18 +177,16 @@ export declare class SignosoftSignpad extends LitElement {
      * @protected
      */
     protected updated(changedProperties: Map<PropertyKey, unknown>): void;
+    /**
+     * Moves focus to the restart button when an error appears, but only if
+     * focus is already inside the component so host-page focus isn't stolen.
+     */
+    private focusRestartButtonOnError;
     /**
      * Component constructor.
      * Initializes all sub-managers.
      */
     constructor();
-    /**
-     * Dispatches a custom event from the component.
-     * @param name - The name of the event.
-     * @param detail - Optional data payload for the event.
-     * @returns void
-     */
-    dispatch(name: string, detail?: any): void;
     /**
      * Attempts to establish a connection with a signature tablet.
      * @param autoConnect - Connect mode: "manual" opens the browser HID picker;
@@ -528,27 +195,36 @@ export declare class SignosoftSignpad extends LitElement {
      * @returns A promise resolving to true if connection (or fallback) succeeded.
      */
     private connectWith;
+    /** True until the first connect attempt starts (waiting for the lease). */
+    private get isInitializing();
+    /** Moves to ERROR with `error`'s own code, or `fallback` if it has none. */
+    private reportError;
+    /**
+     * Resolves once `config.lease` is available. Waits up to LEASE_WAIT_ATTEMPTS
+     * times LEASE_WAIT_TIMEOUT_MS; after that the wait is spent and LICENSE_MISSING
+     * is reported immediately until a lease arrives (config change re-runs auto-connect).
+     * @returns True when a lease is present.
+     */
+    private requireLease;
+    private waitForLease;
     /**
      * Closes the active tablet connection and switches to mouse fallback mode.
      * @returns A promise that resolves when disconnection is complete.
      */
     disconnect(): Promise<void>;
-    /**
-     * Resets the UI canvas and internal drawing flags.
-     * @returns void
-     */
-    resetDrawingState(): void;
-    /**
-     * Enables or disables browser pointer interaction on the drawing canvas.
-     * Physical tablet mode disables browser pointer input to prevent mouse drawing.
-     */
-    setCanvasPointerInputEnabled(enabled: boolean): void;
     /**
      * Lit lifecycle: Invoked when the component is removed from the document's DOM.
      * Performs necessary cleanup of listeners and connections.
      * @returns void
      */
+    connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * Ends the driver session after the element was removed from the DOM. Unlike `disconnect()`
+     * it does not start a mouse fallback session (that would re-initialize the driver on a
+     * detached element).
+     */
+    private releaseDriver;
     /**
      * Keeps canvas internal size in sync with responsive layout changes.
      * @private
@@ -565,7 +241,7 @@ export declare class SignosoftSignpad extends LitElement {
     connect: () => Promise<void>;
     /**
      * If currently in mouse fallback, tears that session down seamlessly
-     * (no DISCONNECTED UI flash) so a physical-device connect attempt can
+     * (no intermediate UI flash) so a physical-device connect attempt can
      * proceed cleanly.
      */
     private prepareForManualConnect;
@@ -623,6 +299,7 @@ export declare class SignosoftSignpad extends LitElement {
      */
     private initializeFromConfigLeaseIfNeeded;
     private autoConnectIfConfigured;
+    private runAutoConnect;
     private ensureSignatureLayerReady;
     private deferAutoConnectForState;
     private clearPendingAutoConnectTimeout;
@@ -630,9 +307,22 @@ export declare class SignosoftSignpad extends LitElement {
     private shouldScheduleImmediateRetry;
     private scheduleAutoConnectRetry;
     private clearAutoConnectQueue;
+    /**
+     * Restarts the signing session after an error (restart button), respecting
+     * the connect/disconnect reentrancy lock so it never races a concurrent
+     * manual connect/disconnect or hotplug transition.
+     */
+    private restartSigningAfterError;
+    /**
+     * Runs `action` as the only connect/disconnect transition. Other transitions wait for it
+     * instead of interleaving (or being dropped), so state changes stay serialized.
+     */
+    private withTransitionLock;
+    /** Restart button in the error overlay. */
+    private handleRestartSessionClick;
     private delay;
     /**
-     * Disconnects current session without transitioning through DISCONNECTED UI.
+     * Disconnects current session without an intermediate UI state.
      * Used for smooth mode switching (mouse <-> physical).
      */
     private disconnectForSeamlessSwitch;
@@ -646,10 +336,6 @@ export declare class SignosoftSignpad extends LitElement {
      * stays physically plugged in.
      */
     private startMouseFallbackSigningSession;
-    /**
-     * Switches from physical tablet mode to mouse fallback after disconnect.
-     */
-    recoverToMouseFallback(messageKey?: string, minLoadingMs?: number): Promise<void>;
     /**
      * Promotes active mouse fallback session to a physical tablet when one is plugged in.
      */
@@ -669,6 +355,8 @@ export declare type SignosoftSignpadProps = {
 
 export declare interface SignpadConfig {
     lease?: {};
+    /** `"light"` (default), `"dark"`, or `"auto"` to follow the OS `prefers-color-scheme`. */
+    theme?: SignpadTheme;
     languageOptions?: ILanguageOptions;
     uiVisibilityOptions?: IUIVisibilityOptions;
     canvasAndDrawingOptions?: IDrawingOptions;
@@ -676,6 +364,22 @@ export declare interface SignpadConfig {
     eventCallbacks?: IEventCallbacks;
 }
 
+/**
+ * Error identifiers delivered in `onError` (`detail.code`), formatted `AREA-NN`:
+ * LIC license, DRV driver, CON connection, NET network, BIL billing,
+ * SES signing session, ACT signing actions (OK/Clear/Cancel).
+ */
+export declare enum SignpadErrorCode {
+    LICENSE_MISSING = "LIC-01",
+    LICENSE_INVALID = "LIC-02",
+    DRIVER_INIT_FAILED = "DRV-01",
+    CONNECT_FAILED = "CON-01",
+    NETWORK_ERROR = "NET-01",
+    BILLING_DENIED = "BIL-01",
+    START_SIGNING_FAILED = "SES-01",
+    ACTION_FAILED = "ACT-01"
+}
+
 export declare enum SignpadEventType {
     SIGN_PEN = "sign-pen",
     SIGN_OK = "sign-ok",
@@ -692,31 +396,34 @@ export declare enum SignpadMessage {
     CONNECTING_TO_DEVICE = "CONNECTING_TO_DEVICE",
     REVERTING_TO_DEFAULT = "REVERTING_TO_DEFAULT",
     DISCONNECTING_DEVICE = "DISCONNECTING_DEVICE",
-    COMPONENT_INITIALIZED = "COMPONENT_INITIALIZED",
+    PREPARING_SESSION = "PREPARING_SESSION",
+    RESTART_SESSION = "RESTART_SESSION",
+    PROCESSING_OK = "PROCESSING_OK",
+    PROCESSING_CLEAR = "PROCESSING_CLEAR",
+    PROCESSING_CANCEL = "PROCESSING_CANCEL",
+    INITIALIZING = "INITIALIZING",
     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",
+    TEXT_PRESS_START_SIGNING = "TEXT_PRESS_START_SIGNING",
+    LICENSE_MISSING = "LICENSE_MISSING",
     INVALID_LICENSE_KEY = "INVALID_LICENSE_KEY",
-    READY_TO_CONNECT = "READY_TO_CONNECT",
-    SIGNPAD_DETECTED = "SIGNPAD_DETECTED",
+    ERROR_DRIVER_INIT = "ERROR_DRIVER_INIT",
+    CONNECTION_ERROR = "CONNECTION_ERROR",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    INSUFFICIENT_TOKENS = "INSUFFICIENT_TOKENS",
+    ERROR_STARTING_SIGNING = "ERROR_STARTING_SIGNING",
+    ERROR_PROCESSING_ACTION = "ERROR_PROCESSING_ACTION",
     READY_TO_SIGN_MOUSE = "READY_TO_SIGN_MOUSE",
     READY_TO_SIGN_PHYSICAL = "READY_TO_SIGN_PHYSICAL"
 }
 
 export declare enum SignpadState {
-    INITIAL = "initial",
-    DISCONNECTED = "disconnected",
     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",
@@ -724,97 +431,7 @@ export declare enum SignpadState {
     ERROR = "error"
 }
 
-/**
- * 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 only for a physical device connection lifecycle.
-     * Mouse fallback is intentionally excluded.
-     * @returns True when a physical device is connected/signing/processing.
-     */
-    get isPhysicalConnected(): 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 type SignpadTheme = "light" | "dark" | "auto";
 
 export { }