@signosoft/signpad-js 0.3.2 β†’ 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +117 -71
  2. package/dist/index.d.ts +55 -18
  3. package/dist/signosoft-signpad.js +977 -799
  4. package/dist/signosoft-signpad.umd.cjs +47 -39
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -2,14 +2,16 @@
2
2
 
3
3
  ## πŸ“ Table of Contents
4
4
 
5
- | Core Concepts & Overview | Getting Started & Usage | Advanced & Support |
6
- | :---------------------------------------- | :-------------------------------- | :--------------------------------- |
7
- | πŸ“œ [Description](#-description) | πŸ“¦ [Installation](#-installation) | πŸ’¬ [Feedback](#-feedback--support) |
8
- | 🎬 [Demo](#-demo) | πŸ” [Licensing](#-lease-setup) | πŸ› οΈ [Contributing](#-contributing) |
9
- | βš™οΈ [Tech stack](#-tech-stack--built-with) | πŸš€ [Quick Start](#-quick-start) | πŸ“„ [License](#-license) |
10
- | | πŸ“‹ [Properties](#-properties) | |
11
- | | 🧩 [Methods](#-methods) | |
12
- | | 🎨 [Styling](#-styling--theming) | |
5
+ | Core Concepts & Overview | Getting Started & Usage | Advanced & Support |
6
+ | :---------------------------------------- | :-------------------------------------------------- | :--------------------------------- |
7
+ | πŸ“œ [Description](#-description) | πŸ“¦ [Installation](#-installation) | πŸ’¬ [Feedback](#-feedback--support) |
8
+ | 🎬 [Demo](#-demo) | πŸ” [Licensing](#-lease-setup) | πŸ› οΈ [Contributing](#-contributing) |
9
+ | βš™οΈ [Tech stack](#-tech-stack--built-with) | πŸš€ [Quick Start](#-quick-start) | πŸ“„ [License](#-license) |
10
+ | | πŸ“‹ [Properties](#-properties) | |
11
+ | | 🧩 [Methods](#-methods) | |
12
+ | | 🎨 [Styling](#-styling--theming) | |
13
+ | | 🌐 [Localization](#-localization--translation-keys) |
14
+ | | |
13
15
 
14
16
  ## πŸ“œ Description
15
17
 
@@ -604,18 +606,18 @@ Controls how the component handles hardware connections and session flow.
604
606
 
605
607
  Toggles the visibility of specific User Interface elements.
606
608
 
607
- | Field | Type | Description |
608
- | :------------------------- | :-------- | :-------------------------------------------------------------- |
609
- | `topBarVisible` | `boolean` | Shows/hides the entire top navigation bar. |
610
- | `topBarClearButtonVisible` | `boolean` | Shows a "Clear" button in the top-left corner. |
609
+ | Field | Type | Description |
610
+ | :--------------------------- | :-------- | :---------------------------------------------------------------- |
611
+ | `topBarVisible` | `boolean` | Shows/hides the entire top navigation bar. |
612
+ | `topBarClearButtonVisible` | `boolean` | Shows a "Clear" button in the top-left corner. |
611
613
  | `topBarConnectButtonVisible` | `boolean` | Shows the connect/disconnect button area in the top-right corner. |
612
- | `bottomBarVisible` | `boolean` | Shows/hides the entire bottom action bar. |
613
- | `okButtonVisible` | `boolean` | Shows the **OK** button in the bottom bar. |
614
- | `clearButtonVisible` | `boolean` | Shows the **Clear** button in the bottom bar. |
615
- | `cancelButtonVisible` | `boolean` | Shows the **Cancel** button in the bottom bar. |
616
- | `canvasLineVisible` | `boolean` | Shows the horizontal signature guide line on the canvas. |
617
- | `deviceStatusTextVisible` | `boolean` | Shows the name of the connected device (e.g., "Wacom STU-540"). |
618
- | `additionalTextVisible` | `boolean` | Shows helper status messages (e.g., "Ready to sign"). |
614
+ | `bottomBarVisible` | `boolean` | Shows/hides the entire bottom action bar. |
615
+ | `okButtonVisible` | `boolean` | Shows the **OK** button in the bottom bar. |
616
+ | `clearButtonVisible` | `boolean` | Shows the **Clear** button in the bottom bar. |
617
+ | `cancelButtonVisible` | `boolean` | Shows the **Cancel** button in the bottom bar. |
618
+ | `canvasLineVisible` | `boolean` | Shows the horizontal signature guide line on the canvas. |
619
+ | `deviceStatusTextVisible` | `boolean` | Shows the name of the connected device (e.g., "Wacom STU-540"). |
620
+ | `additionalTextVisible` | `boolean` | Shows helper status messages (e.g., "Ready to sign"). |
619
621
 
620
622
  ### πŸ–‹οΈ canvasAndDrawingOptions
621
623
 
@@ -633,11 +635,54 @@ Adjusts the visual appearance of the digital ink.
633
635
 
634
636
  Handles component localization. It can load external files or use inline definitions.
635
637
 
636
- | Field | Type | Description |
637
- | :------------- | :------- | :---------------------------------------------------------------------------------------------------- |
638
+ | Field | Type | Description |
639
+ | :------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
638
640
  | `lang` | `string` | The active language code. Built-in translations are bundled for `'en'` and `'cs'`; other languages can be supplied via `langPath` or `translations`. |
639
- | `langPath` | `string` | URL path to fetch translation files. Expects files in `[path]/[lang].json` format. |
640
- | `translations` | `object` | An inline object containing key-value pairs (e.g., `{ "OK": "Confirm signature" }`). Overrides files. |
641
+ | `langPath` | `string` | URL path to fetch translation files. Expects files in `[path]/[lang].json` format. |
642
+ | `translations` | `object` | An inline object containing key-value pairs (e.g., `{ "OK": "Confirm signature" }`). Overrides files. |
643
+
644
+ ## 🌐 Localization & Translation Keys
645
+
646
+ Localization is driven from `languageOptions`, but you can also provide overrides at runtime:
647
+
648
+ 1. **Set the language code** in `config.languageOptions.lang`. English (`en`) is the fallback and Czech (`cs`) is shipped alongside it.
649
+ 2. **Load a hosted file** by pointing `languageOptions.langPath` to the directory that contains `[lang].json`. The loader will fetch `${langPath}/${lang}.json` (or the exact file if you include the `.json` suffix).
650
+ 3. **Override only specific phrases** by passing a `translations` objectβ€”either a flat key map or a per-language map (`{ en: {...}, cs: {...} }`). Inline values take precedence over both built-in and fetched files.
651
+ 4. **Dynamic placeholders** (for example, `{device}` in `TEXT_SIGNING_WITH_DEVICE`) are replaced using the `LocalizationManager.t` helper. Keep the braces intact if you expect runtime interpolation.
652
+
653
+ The complete list of keys that can be translated is maintained in `src/i18n/en.json`. You can copy the structure when creating new language files or inline overrides. The defaults are:
654
+
655
+ | Key | Default (English) |
656
+ | :--------------------------- | :-------------------------------------------------- |
657
+ | `OK` | OK |
658
+ | `CLEAR` | Clear |
659
+ | `CANCEL` | Cancel |
660
+ | `CLEAR_SIGNATURE` | Clear signature |
661
+ | `DISCONNECT` | Disconnect |
662
+ | `CONNECT_SIGNPAD` | Connect Signpad |
663
+ | `NOT_CONNECTED` | Not Connected |
664
+ | `MOUSE` | Mouse |
665
+ | `CONNECTED_UNKNOWN_DEVICE` | Connected (Unknown Device) |
666
+ | `AUTO_CONNECTING` | Auto-connecting to device... |
667
+ | `CONNECTING_TO_DEVICE` | Connecting to your device... |
668
+ | `REVERTING_TO_DEFAULT` | Reverting to default input... |
669
+ | `DISCONNECTING_DEVICE` | Disconnecting device... |
670
+ | `COMPONENT_INITIALIZED` | Component initialized. |
671
+ | `TEXT_START_SIGNING` | Connect your device. |
672
+ | `TEXT_SIGN_WITH_PHYSICAL` | Please sign using the device pen. |
673
+ | `TEXT_SIGN_WITH_MOUSE` | Please sign using your mouse. |
674
+ | `TEXT_SIGN_GENERIC` | Sign in the area above using mouse or pen. |
675
+ | `TEXT_SIGNING_WITH_DEVICE` | Signing with {device} |
676
+ | `NO_DEVICE_FOUND` | No device found. |
677
+ | `CONNECTION_ERROR` | Connection error. |
678
+ | `ERROR_DISCONNECTION` | Error during disconnection. |
679
+ | `ERROR_INSTANTIATING_DRIVER` | Error instantiating driver. |
680
+ | `SIGNPAD_DISCONNECTED` | Signpad disconnected. |
681
+ | `INVALID_LICENSE_KEY` | Invalid license key. |
682
+ | `READY_TO_CONNECT` | Ready to connect. |
683
+ | `SIGNPAD_DETECTED` | Signpad detected. Click 'Connect Signpad' to begin. |
684
+
685
+ If you add any new keys, mirror them in every language file you provide to guarantee they fall back gracefully to English.
641
686
 
642
687
  ### βš™οΈ Logic & Events
643
688
 
@@ -690,8 +735,7 @@ this.config = {
690
735
  eventCallbacks: {
691
736
  onConnect: (e) =>
692
737
  console.log("Pad connected:", e.detail.deviceInfo.deviceName),
693
- onError: (event) =>
694
- console.error("Signpad Error:", event.detail.message),
738
+ onError: (event) => console.error("Signpad Error:", event.detail.message),
695
739
  },
696
740
  };
697
741
  ```
@@ -930,7 +974,9 @@ signosoft-signpad {
930
974
  --sign-bottom-bar-border-top-left-radius: 0;
931
975
  --sign-bottom-bar-border-top-right-radius: 0;
932
976
  --sign-bottom-bar-border-bottom-left-radius: var(--sign-common-border-radius);
933
- --sign-bottom-bar-border-bottom-right-radius: var(--sign-common-border-radius);
977
+ --sign-bottom-bar-border-bottom-right-radius: var(
978
+ --sign-common-border-radius
979
+ );
934
980
 
935
981
  /* Button general settings */
936
982
  --sign-button-font-size: 16px;
@@ -975,17 +1021,17 @@ signosoft-signpad {
975
1021
 
976
1022
  #### Base Colors & General
977
1023
 
978
- | Variable | Default | Description |
979
- | :---------------------- | :------------------ | :-------------------------- |
980
- | `--primary-color-0` | `#4e56ea` | Primary brand color. |
981
- | `--primary-color-10` | `#7178ee` | Primary hover/accent color. |
982
- | `--background-color-0` | `#f1f2fd` | Secondary background color. |
983
- | `--background-color-10` | `#e3e4fc` | Main bar background color. |
984
- | `--text-color-0` | `#333e4a` | Main text color. |
985
- | `--white-color` | `#ffffff` | Pure white color. |
986
- | `--grey-color` | `#b5b9be` | Disabled state color. |
987
- | `--sign-font-family` | `Arial, sans-serif` | Global font family. |
988
- | `--sign-common-border-radius` | `8px` | Shared radius token reused by bars and buttons. |
1024
+ | Variable | Default | Description |
1025
+ | :---------------------------- | :------------------ | :---------------------------------------------- |
1026
+ | `--primary-color-0` | `#4e56ea` | Primary brand color. |
1027
+ | `--primary-color-10` | `#7178ee` | Primary hover/accent color. |
1028
+ | `--background-color-0` | `#f1f2fd` | Secondary background color. |
1029
+ | `--background-color-10` | `#e3e4fc` | Main bar background color. |
1030
+ | `--text-color-0` | `#333e4a` | Main text color. |
1031
+ | `--white-color` | `#ffffff` | Pure white color. |
1032
+ | `--grey-color` | `#b5b9be` | Disabled state color. |
1033
+ | `--sign-font-family` | `Arial, sans-serif` | Global font family. |
1034
+ | `--sign-common-border-radius` | `8px` | Shared radius token reused by bars and buttons. |
989
1035
 
990
1036
  #### Layout & Constraints
991
1037
 
@@ -996,46 +1042,46 @@ signosoft-signpad {
996
1042
 
997
1043
  #### Top Bar
998
1044
 
999
- | Variable | Default | Description |
1000
- | :-------------------------- | :--------------------------- | :------------------------------- |
1001
- | `--sign-top-bar-bg-base` | `var(--background-color-10)` | Background color of the top bar. |
1002
- | `--sign-top-bar-text-base` | `var(--primary-color-0)` | Text color in the top bar. |
1003
- | `--sign-top-bar-padding` | `var(--spacing-constraints)` | Inner padding of the top bar. |
1004
- | `--sign-top-bar-min-height` | `var(--min-height)` | Minimum height of the top bar. |
1005
- | `--sign-top-bar-border-top-left-radius` | `var(--sign-common-border-radius)` | Top-left radius of the top bar. |
1006
- | `--sign-top-bar-border-top-right-radius` | `var(--sign-common-border-radius)` | Top-right radius of the top bar. |
1007
- | `--sign-top-bar-border-bottom-left-radius` | `0` | Bottom-left radius of the top bar. |
1008
- | `--sign-top-bar-border-bottom-right-radius` | `0` | Bottom-right radius of the top bar. |
1045
+ | Variable | Default | Description |
1046
+ | :------------------------------------------ | :--------------------------------- | :---------------------------------- |
1047
+ | `--sign-top-bar-bg-base` | `var(--background-color-10)` | Background color of the top bar. |
1048
+ | `--sign-top-bar-text-base` | `var(--primary-color-0)` | Text color in the top bar. |
1049
+ | `--sign-top-bar-padding` | `var(--spacing-constraints)` | Inner padding of the top bar. |
1050
+ | `--sign-top-bar-min-height` | `var(--min-height)` | Minimum height of the top bar. |
1051
+ | `--sign-top-bar-border-top-left-radius` | `var(--sign-common-border-radius)` | Top-left radius of the top bar. |
1052
+ | `--sign-top-bar-border-top-right-radius` | `var(--sign-common-border-radius)` | Top-right radius of the top bar. |
1053
+ | `--sign-top-bar-border-bottom-left-radius` | `0` | Bottom-left radius of the top bar. |
1054
+ | `--sign-top-bar-border-bottom-right-radius` | `0` | Bottom-right radius of the top bar. |
1009
1055
 
1010
1056
  #### Canvas & Signature Line
1011
1057
 
1012
- | Variable | Default | Description |
1013
- | :---------------------------------- | :--------------------------------------------- | :-------------------------------------------- |
1014
- | `--sign-canvas-bg-base` | `var(--background-color-0)` | Background color of the drawing area. |
1015
- | `--sign-canvas-wrapper-border-top-left-radius` | `0` | Top-left canvas radius, typically rounded when the top bar is hidden. |
1016
- | `--sign-canvas-wrapper-border-top-right-radius` | `0` | Top-right canvas radius, typically rounded when the top bar is hidden. |
1017
- | `--sign-canvas-wrapper-border-bottom-left-radius` | `0` | Bottom-left canvas radius, typically rounded when the bottom bar is hidden. |
1018
- | `--sign-canvas-wrapper-border-bottom-right-radius` | `0` | Bottom-right canvas radius, typically rounded when the bottom bar is hidden. |
1019
- | `--sign-line-height` | `22px` | Vertical offset/height for the guide line. |
1020
- | `--sign-line-margin-bottom` | `16px` | Bottom spacing used in canvas line layout. |
1021
- | `--sign-line-border-base` | `var(--primary-color-10)` | Color of the signature guide line. |
1022
- | `--sign-line-additional-text-color` | `var(--text-color-0)` | Color of the helper text below the line. |
1023
- | `--sign-line-margin` | `0px 24px var(--sign-line-margin-bottom) 24px` | Spacing around the guide line. |
1024
- | `--sign-canvas-line-text-font-size` | `12px` | Font size for guide line labels. |
1025
- | `--sign-canvas-height-offset` | `var(--sign-line-height)` | Canvas offset calculation for the guide line. |
1058
+ | Variable | Default | Description |
1059
+ | :------------------------------------------------- | :--------------------------------------------- | :--------------------------------------------------------------------------- |
1060
+ | `--sign-canvas-bg-base` | `var(--background-color-0)` | Background color of the drawing area. |
1061
+ | `--sign-canvas-wrapper-border-top-left-radius` | `0` | Top-left canvas radius, typically rounded when the top bar is hidden. |
1062
+ | `--sign-canvas-wrapper-border-top-right-radius` | `0` | Top-right canvas radius, typically rounded when the top bar is hidden. |
1063
+ | `--sign-canvas-wrapper-border-bottom-left-radius` | `0` | Bottom-left canvas radius, typically rounded when the bottom bar is hidden. |
1064
+ | `--sign-canvas-wrapper-border-bottom-right-radius` | `0` | Bottom-right canvas radius, typically rounded when the bottom bar is hidden. |
1065
+ | `--sign-line-height` | `22px` | Vertical offset/height for the guide line. |
1066
+ | `--sign-line-margin-bottom` | `16px` | Bottom spacing used in canvas line layout. |
1067
+ | `--sign-line-border-base` | `var(--primary-color-10)` | Color of the signature guide line. |
1068
+ | `--sign-line-additional-text-color` | `var(--text-color-0)` | Color of the helper text below the line. |
1069
+ | `--sign-line-margin` | `0px 24px var(--sign-line-margin-bottom) 24px` | Spacing around the guide line. |
1070
+ | `--sign-canvas-line-text-font-size` | `12px` | Font size for guide line labels. |
1071
+ | `--sign-canvas-height-offset` | `var(--sign-line-height)` | Canvas offset calculation for the guide line. |
1026
1072
 
1027
1073
  #### Bottom Bar
1028
1074
 
1029
- | Variable | Default | Description |
1030
- | :----------------------------- | :--------------------------- | :--------------------------------------- |
1031
- | `--sign-bottom-bar-bg-base` | `var(--background-color-10)` | Background color of the bottom bar. |
1032
- | `--sign-bottom-bar-padding` | `var(--spacing-constraints)` | Inner padding of the bottom bar. |
1033
- | `--sign-bottom-bar-min-height` | `var(--min-height)` | Minimum height of the bottom bar. |
1034
- | `--sign-bottom-bar-gap` | `12px` | Space between buttons in the bottom bar. |
1035
- | `--sign-bottom-bar-border-top-left-radius` | `0` | Top-left radius of the bottom bar. |
1036
- | `--sign-bottom-bar-border-top-right-radius` | `0` | Top-right radius of the bottom bar. |
1037
- | `--sign-bottom-bar-border-bottom-left-radius` | `var(--sign-common-border-radius)` | Bottom-left radius of the bottom bar. |
1038
- | `--sign-bottom-bar-border-bottom-right-radius` | `var(--sign-common-border-radius)` | Bottom-right radius of the bottom bar. |
1075
+ | Variable | Default | Description |
1076
+ | :--------------------------------------------- | :--------------------------------- | :--------------------------------------- |
1077
+ | `--sign-bottom-bar-bg-base` | `var(--background-color-10)` | Background color of the bottom bar. |
1078
+ | `--sign-bottom-bar-padding` | `var(--spacing-constraints)` | Inner padding of the bottom bar. |
1079
+ | `--sign-bottom-bar-min-height` | `var(--min-height)` | Minimum height of the bottom bar. |
1080
+ | `--sign-bottom-bar-gap` | `12px` | Space between buttons in the bottom bar. |
1081
+ | `--sign-bottom-bar-border-top-left-radius` | `0` | Top-left radius of the bottom bar. |
1082
+ | `--sign-bottom-bar-border-top-right-radius` | `0` | Top-right radius of the bottom bar. |
1083
+ | `--sign-bottom-bar-border-bottom-left-radius` | `var(--sign-common-border-radius)` | Bottom-left radius of the bottom bar. |
1084
+ | `--sign-bottom-bar-border-bottom-right-radius` | `var(--sign-common-border-radius)` | Bottom-right radius of the bottom bar. |
1039
1085
 
1040
1086
  #### Buttons (General)
1041
1087
 
package/dist/index.d.ts CHANGED
@@ -61,17 +61,14 @@ declare class ButtonManager {
61
61
  }
62
62
 
63
63
  /**
64
- * `CanvasManager` handles all low-level drawing operations on the HTMLCanvasElement.
65
- * It manages DPI scaling for high-resolution displays, stroke interpolation,
66
- * pressure-sensitive line thickness, and canvas state.
64
+ * `CanvasManager` is a lightweight canvas utility.
65
+ * Drawing is handled by SignatureLayer/SignatureCapture in `src/lib`.
67
66
  */
68
67
  declare class CanvasManager {
69
68
  /** @private The target canvas element */
70
69
  private canvas;
71
70
  /** @private The 2D rendering context */
72
71
  private ctx;
73
- /** @private The last point processed in the current stroke */
74
- private lastDrawPoint;
75
72
  /** @private The active configuration for line styles */
76
73
  private currentDrawingOptions;
77
74
  /**
@@ -91,9 +88,9 @@ declare class CanvasManager {
91
88
  */
92
89
  updateDrawingOptions(options: IDrawingOptions): void;
93
90
  /**
94
- * Draws a line segment between the previous point and the current pen data.
95
- * Handles coordinate normalization and pressure-based thickness.
96
- * @param penData - Data containing coordinates (0-1), pressure, and contact status.
91
+ * Kept for backward compatibility with callers that may still invoke it.
92
+ * The actual stroke rendering is done in `src/lib/SignatureCapture.js`.
93
+ * @param penData - Ignored.
97
94
  */
98
95
  drawSegment(penData: IPenData_2): void;
99
96
  /**
@@ -270,8 +267,6 @@ declare class ConnectionManager {
270
267
 
271
268
  export declare enum DeviceStatusText {
272
269
  NOT_CONNECTED = "NOT_CONNECTED",
273
- CONNECTED = "CONNECTED",
274
- CONNECTING = "CONNECTING",
275
270
  MOUSE = "MOUSE",
276
271
  CONNECTED_UNKNOWN = "CONNECTED_UNKNOWN_DEVICE"
277
272
  }
@@ -648,6 +643,11 @@ export declare class SignosoftSignpad extends LitElement {
648
643
  * @returns void
649
644
  */
650
645
  resetDrawingState(): void;
646
+ /**
647
+ * Enables or disables browser pointer interaction on the drawing canvas.
648
+ * Physical tablet mode disables browser pointer input to prevent mouse drawing.
649
+ */
650
+ setCanvasPointerInputEnabled(enabled: boolean): void;
651
651
  /**
652
652
  * Lit lifecycle: Invoked when the component is removed from the document's DOM.
653
653
  * Performs necessary cleanup of listeners and connections.
@@ -660,6 +660,19 @@ export declare class SignosoftSignpad extends LitElement {
660
660
  * @returns void
661
661
  */
662
662
  private handleWindowResize;
663
+ /**
664
+ * Connect button workflow:
665
+ * - if currently in mouse fallback, disconnect it first
666
+ * - then try physical device connect
667
+ * - if physical is not available, allow fallback as a secondary attempt
668
+ */
669
+ private handleConnectClick;
670
+ /**
671
+ * UI disconnect action:
672
+ * when physical device is active, switch seamlessly to mouse fallback.
673
+ * For other states, perform regular disconnect.
674
+ */
675
+ private handleDisconnectClick;
663
676
  /**
664
677
  * Attaches WebHID API event listeners for device connection and disconnection.
665
678
  * @private
@@ -684,6 +697,9 @@ export declare class SignosoftSignpad extends LitElement {
684
697
  * @returns void
685
698
  */
686
699
  private handleHIDDisconnect;
700
+ private shouldPromoteMouseFallback;
701
+ private shouldAutoConnectOnPlugIn;
702
+ private showSignpadDetectedState;
687
703
  /**
688
704
  * Initializes the CanvasManager for rendering signature strokes.
689
705
  * @private
@@ -708,8 +724,28 @@ export declare class SignosoftSignpad extends LitElement {
708
724
  private initializeFromConfigLeaseIfNeeded;
709
725
  private shouldAutoConnect;
710
726
  private autoConnectIfConfigured;
727
+ private canAttemptAutoConnect;
728
+ private ensureSignatureLayerReady;
729
+ private deferAutoConnectForState;
730
+ private clearPendingAutoConnectTimeout;
731
+ private performAutoConnectSequence;
732
+ private shouldScheduleImmediateRetry;
711
733
  private scheduleAutoConnectRetry;
712
734
  private clearAutoConnectQueue;
735
+ private delay;
736
+ /**
737
+ * Disconnects current session without transitioning through DISCONNECTED UI.
738
+ * Used for smooth mode switching (mouse <-> physical).
739
+ */
740
+ private disconnectForSeamlessSwitch;
741
+ /**
742
+ * Switches from physical tablet mode to mouse fallback after disconnect.
743
+ */
744
+ recoverToMouseFallback(messageKey?: string, minLoadingMs?: number): Promise<void>;
745
+ /**
746
+ * Promotes active mouse fallback session to a physical tablet when one is plugged in.
747
+ */
748
+ private promoteMouseFallbackToPhysical;
713
749
  /**
714
750
  * Renders the HTML template for the component.
715
751
  * Uses Lit's html template literal.
@@ -751,6 +787,7 @@ export declare enum SignpadEventType {
751
787
  export declare enum SignpadMessage {
752
788
  AUTO_CONNECTING = "AUTO_CONNECTING",
753
789
  CONNECTING_TO_DEVICE = "CONNECTING_TO_DEVICE",
790
+ REVERTING_TO_DEFAULT = "REVERTING_TO_DEFAULT",
754
791
  DISCONNECTING_DEVICE = "DISCONNECTING_DEVICE",
755
792
  COMPONENT_INITIALIZED = "COMPONENT_INITIALIZED",
756
793
  TEXT_START_SIGNING = "TEXT_START_SIGNING",
@@ -763,20 +800,14 @@ export declare enum SignpadMessage {
763
800
  ERROR_DISCONNECTION = "ERROR_DISCONNECTION",
764
801
  ERROR_INSTANTIATING_DRIVER = "ERROR_INSTANTIATING_DRIVER",
765
802
  SIGNPAD_DISCONNECTED = "SIGNPAD_DISCONNECTED",
766
- DEVICE_UNEXPECTEDLY_DISCONNECTED = "DEVICE_UNEXPECTEDLY_DISCONNECTED",
767
- SIGN_SUCCESSFUL = "SIGN_SUCCESSFUL",
768
- SIGN_CANCELLED = "SIGN_CANCELLED",
769
- SIGN_CLEARED = "SIGN_CLEARED",
770
- MISSING_LICENSE_KEY = "MISSING_LICENSE_KEY",
803
+ INVALID_LICENSE_KEY = "INVALID_LICENSE_KEY",
771
804
  READY_TO_CONNECT = "READY_TO_CONNECT",
772
- SIGNPAD_DETECTED = "SIGNPAD_DETECTED",
773
- NO_LICENSE_KEY = "NO_LICENSE_KEY"
805
+ SIGNPAD_DETECTED = "SIGNPAD_DETECTED"
774
806
  }
775
807
 
776
808
  export declare enum SignpadState {
777
809
  INITIAL = "initial",
778
810
  DISCONNECTED = "disconnected",
779
- FINISHED = "finished",
780
811
  CONNECTING = "connecting",
781
812
  WAITING_FOR_DEVICE_SELECTION = "waiting_for_device_selection",
782
813
  CONNECTED_PHYSICAL = "connected_physical",
@@ -834,6 +865,12 @@ declare class StateManager {
834
865
  * @returns True when connected or signing.
835
866
  */
836
867
  get isConnected(): boolean;
868
+ /**
869
+ * Returns true only for a physical device connection lifecycle.
870
+ * Mouse fallback is intentionally excluded.
871
+ * @returns True when a physical device is connected/signing/processing.
872
+ */
873
+ get isPhysicalConnected(): boolean;
837
874
  /**
838
875
  * Returns true if the component is performing an asynchronous operation.
839
876
  * @returns True when busy.