@nitra/zebra 6.1.7 → 6.2.0

package/dist/plugin.js

@@ -3,8 +3,8 @@ import { WebPlugin, registerPlugin } from '@capacitor/core';
 /**
  * ZebraPrinterWeb - Web implementation for development
  *
- * Uses local printer-server.js (TCP/IP) so developers can
- * test the printer in the browser.
+ * Uses local printer-server.js (TCP/IP) or Web Bluetooth API.
+ * Falls back to BLE when TCP/IP is not available (like iOS).
  *
  * Production (iOS) uses the native BLE implementation.
  */
@@ -24,12 +24,103 @@ import { WebPlugin, registerPlugin } from '@capacitor/core';
 
 const API_BASE = '/api/printer';
 
+// Zebra printer BLE service UUIDs
+const ZEBRA_SERVICE_UUID = '38eb4a80-c570-11e3-9507-0002a5d5c51b';
+const ZEBRA_WRITE_CHAR_UUID = '38eb4a82-c570-11e3-9507-0002a5d5c51b';
+// Alternative service for some Zebra models
+const ZEBRA_SPP_SERVICE_UUID = '00001101-0000-1000-8000-00805f9b34fb';
+
+// LocalStorage key for persisting printer settings
+const STORAGE_KEY = 'zebra_printer_settings';
+
 class ZebraPrinterWeb extends WebPlugin {
   constructor() {
     super();
-    this.connectedPrinter = null;
     this.serviceAvailable = null;
     this.defaultSubnet = this._getDefaultSubnet();
+    // BLE state
+    this.bleDevice = null;
+    this.bleServer = null;
+    this.bleCharacteristic = null;
+    this.discoveredBleDevices = [];
+    // Load last printer from localStorage
+    this.connectedPrinter = this._loadFromStorage();
+    if (this.connectedPrinter) {
+      console.log(
+        '[Storage] Loaded:',
+        this.connectedPrinter.name || this.connectedPrinter.ip
+      );
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // LOCAL STORAGE PERSISTENCE
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Load printer settings from localStorage
+   * @returns {Object|null} Saved printer settings or null
+   */
+  _loadFromStorage() {
+    try {
+      if (typeof localStorage === 'undefined') return null;
+      const saved = localStorage.getItem(STORAGE_KEY);
+      return saved ? JSON.parse(saved) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Save printer settings to localStorage
+   * @param {Object} printer - Printer settings to save
+   */
+  _saveToStorage(printer) {
+    try {
+      if (typeof localStorage === 'undefined') return;
+      if (printer) {
+        // Don't save BLE device reference (can't be serialized)
+        const toSave = { ...printer };
+        delete toSave.bleDevice;
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(toSave));
+        console.log('[Storage] Saved:', toSave.name || toSave.ip);
+      } else {
+        localStorage.removeItem(STORAGE_KEY);
+        console.log('[Storage] Cleared');
+      }
+    } catch {
+      // Ignore storage errors
+    }
+  }
+
+  /**
+   * Clear saved printer from localStorage
+   * @returns {{success: boolean, message: string}} Result object
+   */
+  clearSavedPrinter() {
+    this._saveToStorage(null);
+    return { success: true, message: 'Saved printer cleared' };
+  }
+
+  /**
+   * Check if Web Bluetooth is supported
+   * @returns {boolean} True if Web Bluetooth API is available
+   */
+  _isBleSupported() {
+    return (
+      typeof navigator !== 'undefined' && navigator.bluetooth !== undefined
+    );
+  }
+
+  /**
+   * Delay helper for BLE chunk sending
+   * @param {number} ms - Milliseconds to delay
+   * @returns {Promise<void>} Resolves after delay
+   */
+  _delay(ms) {
+    const { promise, resolve } = Promise.withResolvers();
+    setTimeout(resolve, ms);
+    return promise;
   }
 
   /**
@@ -56,6 +147,260 @@ class ZebraPrinterWeb extends WebPlugin {
     }
   }
 
+  /**
+   * Scan for BLE printers using Web Bluetooth API
+   * @returns {Promise<ScanResult>} List of discovered BLE printers
+   */
+  async _scanBlePrinters() {
+    if (!this._isBleSupported()) {
+      return {
+        success: false,
+        error: 'Web Bluetooth is not supported in this browser',
+        printers: [],
+        count: 0,
+      };
+    }
+
+    try {
+      console.log('[BLE] Scanning...');
+
+      // Request device with Zebra name prefixes
+      const device = await navigator.bluetooth.requestDevice({
+        filters: [
+          { namePrefix: 'Zebra' },
+          { namePrefix: 'ZT' },
+          { namePrefix: 'ZD' },
+          { namePrefix: 'ZQ' },
+          { namePrefix: 'XXZHN' },
+        ],
+        optionalServices: [ZEBRA_SERVICE_UUID, ZEBRA_SPP_SERVICE_UUID],
+      });
+
+      console.log('[BLE] Found:', device.name);
+
+      // Store discovered device
+      if (!this.discoveredBleDevices.some((d) => d.id === device.id)) {
+        this.discoveredBleDevices.push(device);
+      }
+
+      return {
+        success: true,
+        printers: this.discoveredBleDevices.map((d) => ({
+          name: d.name || 'Zebra Printer',
+          address: d.id,
+          type: 'bluetooth',
+          paired: false,
+        })),
+        count: this.discoveredBleDevices.length,
+      };
+    } catch (error) {
+      console.warn('[BLE] Scan failed:', error.message);
+      return {
+        success: false,
+        error: error.message || 'BLE scan failed',
+        printers: [],
+        count: 0,
+      };
+    }
+  }
+
+  /**
+   * Connect to a BLE printer
+   * @param {string} deviceId - Device ID from scan
+   * @returns {Promise<ConnectResult>} Connection result with success status
+   */
+  async _connectBle(deviceId) {
+    if (!this._isBleSupported()) {
+      return {
+        success: false,
+        connected: false,
+        error: 'Web Bluetooth is not supported',
+      };
+    }
+
+    try {
+      let device = this.discoveredBleDevices.find((d) => d.id === deviceId);
+
+      // If device not found, request new device
+      if (!device) {
+        console.log('[BLE] Device not cached, requesting...');
+        device = await navigator.bluetooth.requestDevice({
+          filters: [
+            { namePrefix: 'Zebra' },
+            { namePrefix: 'ZT' },
+            { namePrefix: 'ZD' },
+            { namePrefix: 'ZQ' },
+            { namePrefix: 'XXZHN' },
+          ],
+          optionalServices: [ZEBRA_SERVICE_UUID, ZEBRA_SPP_SERVICE_UUID],
+        });
+        this.discoveredBleDevices.push(device);
+      }
+
+      console.log('[BLE] Connecting to', device.name);
+
+      // Connect to GATT server
+      this.bleServer = await device.gatt.connect();
+      this.bleDevice = device;
+
+      console.log('[BLE] GATT connected');
+
+      // Try to get Zebra service
+      let service;
+      try {
+        service = await this.bleServer.getPrimaryService(ZEBRA_SERVICE_UUID);
+        console.log('[BLE] Found Zebra service');
+      } catch {
+        // Try alternative service
+        console.log('[BLE] Trying alternative services...');
+        const services = await this.bleServer.getPrimaryServices();
+        console.log('[BLE] Found', services.length, 'services');
+
+        for (const svc of services) {
+          console.log(`  - Service: ${svc.uuid}`);
+          try {
+            const chars = await svc.getCharacteristics();
+            for (const char of chars) {
+              console.log(
+                `    - Characteristic: ${char.uuid}, props:`,
+                char.properties
+              );
+              if (
+                char.properties.write ||
+                char.properties.writeWithoutResponse
+              ) {
+                service = svc;
+                this.bleCharacteristic = char;
+                console.log('[BLE] Found writable characteristic');
+                break;
+              }
+            }
+            if (this.bleCharacteristic) break;
+          } catch {
+            console.warn('[BLE] Could not get characteristics for', svc.uuid);
+          }
+        }
+      }
+
+      // Get write characteristic if not found yet
+      if (service && !this.bleCharacteristic) {
+        try {
+          this.bleCharacteristic = await service.getCharacteristic(
+            ZEBRA_WRITE_CHAR_UUID
+          );
+          console.log('[BLE] Found Zebra write characteristic');
+        } catch {
+          // Find any writable characteristic
+          const chars = await service.getCharacteristics();
+          for (const char of chars) {
+            if (char.properties.write || char.properties.writeWithoutResponse) {
+              this.bleCharacteristic = char;
+              console.log('[BLE] Found alternative write characteristic');
+              break;
+            }
+          }
+        }
+      }
+
+      if (!this.bleCharacteristic) {
+        throw new Error('No writable characteristic found on printer');
+      }
+
+      // Update connected printer state
+      this.connectedPrinter = {
+        name: device.name || 'Zebra Printer',
+        address: device.id,
+        type: 'bluetooth',
+        bleDevice: device,
+      };
+
+      // Save to localStorage (without bleDevice reference)
+      this._saveToStorage(this.connectedPrinter);
+
+      // Listen for disconnection
+      device.addEventListener('gattserverdisconnected', () => {
+        console.log('[BLE] Disconnected');
+        this.bleDevice = null;
+        this.bleServer = null;
+        this.bleCharacteristic = null;
+        if (this.connectedPrinter?.type === 'bluetooth') {
+          this.connectedPrinter = null;
+        }
+      });
+
+      return {
+        success: true,
+        connected: true,
+        address: device.id,
+        type: 'bluetooth',
+        message: `Connected to ${device.name}`,
+      };
+    } catch (error) {
+      console.error('[BLE] Connection failed:', error);
+      return {
+        success: false,
+        connected: false,
+        error: error.message || 'BLE connection failed',
+      };
+    }
+  }
+
+  /**
+   * Send data to BLE printer in chunks
+   * @param {string} data - Data to send
+   * @returns {Promise<boolean>} True if data sent successfully
+   */
+  async _sendBlePrint(data) {
+    if (!this.bleCharacteristic) {
+      console.error('[BLE] No characteristic available');
+      return false;
+    }
+
+    try {
+      const encoder = new TextEncoder();
+      const bytes = encoder.encode(data);
+      const MTU_SIZE = 20; // Standard BLE MTU
+
+      console.log('[BLE] Sending', bytes.length, 'bytes');
+
+      for (let offset = 0; offset < bytes.length; offset += MTU_SIZE) {
+        const chunk = bytes.slice(
+          offset,
+          Math.min(offset + MTU_SIZE, bytes.length)
+        );
+
+        if (this.bleCharacteristic.properties.writeWithoutResponse) {
+          await this.bleCharacteristic.writeValueWithoutResponse(chunk);
+        } else {
+          await this.bleCharacteristic.writeValue(chunk);
+        }
+
+        // Small delay between chunks like iOS
+        if (offset + MTU_SIZE < bytes.length) {
+          await this._delay(50);
+        }
+      }
+
+      console.log('[BLE] Data sent');
+      return true;
+    } catch (error) {
+      console.error('[BLE] Send failed:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Disconnect BLE printer
+   */
+  _disconnectBle() {
+    if (this.bleDevice?.gatt?.connected) {
+      this.bleDevice.gatt.disconnect();
+    }
+    this.bleDevice = null;
+    this.bleServer = null;
+    this.bleCharacteristic = null;
+  }
+
   /**
    * Fetch wrapper with error handling
    * @param {string} endpoint - API route
@@ -142,16 +487,20 @@ class ZebraPrinterWeb extends WebPlugin {
    */
   async checkPermissions() {
     const serviceOk = await this._checkService();
-    const hasNavigator = typeof navigator !== 'undefined';
-    const bleSupported = hasNavigator && navigator.bluetooth !== undefined;
+    const bleSupported = this._isBleSupported();
 
-    if (!serviceOk) {
-      console.warn('ZebraPrinter: printer-server not available');
+    // With BLE support, we can work even without printer-server
+    const hasPermissions = serviceOk || bleSupported;
+
+    if (!hasPermissions) {
+      console.warn(
+        'ZebraPrinter: no print method available (no printer-server, no BLE)'
+      );
       return {
         hasPermissions: false,
-        missingPermissions: ['printer-server'],
-        bluetoothSupported: bleSupported,
-        bleSupported: bleSupported,
+        missingPermissions: ['printer-server', 'bluetooth'],
+        bluetoothSupported: false,
+        bleSupported: false,
         webMode: true,
         serviceAvailable: false,
       };
@@ -163,7 +512,10 @@ class ZebraPrinterWeb extends WebPlugin {
       bluetoothSupported: bleSupported,
       bleSupported: bleSupported,
       webMode: true,
-      serviceAvailable: true,
+      serviceAvailable: serviceOk,
+      // New: indicate which methods are available
+      tcpAvailable: serviceOk,
+      bleAvailable: bleSupported,
     };
   }
 
@@ -194,6 +546,29 @@ class ZebraPrinterWeb extends WebPlugin {
 
     const zplPayload = this._wrapTextIfNeeded(text);
 
+    // If connected via BLE, use BLE printing
+    if (this.connectedPrinter?.type === 'bluetooth' && this.bleCharacteristic) {
+      console.log('[BLE] Printing...');
+      const success = await this._sendBlePrint(zplPayload);
+
+      if (success) {
+        return {
+          success: true,
+          message: 'Print successful (BLE)',
+          zpl: `${zplPayload.slice(0, 100)}...`,
+          bytes: zplPayload.length,
+          method: 'bluetooth',
+        };
+      }
+
+      return {
+        success: false,
+        message: 'BLE print failed',
+        error: 'Failed to send data to printer via Bluetooth',
+      };
+    }
+
+    // Otherwise use TCP/IP via printer-server
     const result = await this._fetch('/print', {
       method: 'POST',
       body: JSON.stringify({
@@ -208,6 +583,7 @@ class ZebraPrinterWeb extends WebPlugin {
         message: 'Print successful',
         zpl: `${zplPayload.slice(0, 100)}...`,
         bytes: zplPayload.length,
+        method: 'tcp',
       };
     }
 
@@ -230,6 +606,20 @@ class ZebraPrinterWeb extends WebPlugin {
       };
     }
 
+    // BLE connection status
+    if (this.connectedPrinter.type === 'bluetooth') {
+      const isConnected =
+        this.bleDevice?.gatt?.connected === true &&
+        this.bleCharacteristic !== null;
+      return {
+        connected: isConnected,
+        status: isConnected ? 'connected' : 'disconnected',
+        printerAddress: this.connectedPrinter.address,
+        printerType: 'bluetooth',
+      };
+    }
+
+    // TCP/IP status
     const result = await this._fetch('/check', {
       method: 'POST',
       body: JSON.stringify({ ip: this.connectedPrinter.ip }),
@@ -256,11 +646,26 @@ class ZebraPrinterWeb extends WebPlugin {
       };
     }
 
-    // On web we send ~HS command
+    const statusCommand = '~HS';
+
+    // BLE status check
+    if (this.connectedPrinter.type === 'bluetooth' && this.bleCharacteristic) {
+      const success = await this._sendBlePrint(statusCommand);
+      return {
+        success,
+        message: success
+          ? 'Status command sent (BLE)'
+          : 'Failed to send status command',
+        command: statusCommand,
+        method: 'bluetooth',
+      };
+    }
+
+    // TCP/IP status check
     const result = await this._fetch('/print', {
       method: 'POST',
       body: JSON.stringify({
-        zpl: '~HS',
+        zpl: statusCommand,
         ip: this.connectedPrinter.ip,
       }),
     });
@@ -268,36 +673,78 @@ class ZebraPrinterWeb extends WebPlugin {
     return {
       success: result.success,
       message: result.success ? 'Status command sent' : result.error,
-      command: '~HS',
+      command: statusCommand,
+      method: 'tcp',
     };
   }
 
   /**
    * Scan for available printers
-   * @param {{subnet?: string}} [options] - Custom subnet (e.g., "192.168.0")
+   * @param {{subnet?: string, useBle?: boolean, skipCache?: boolean}} [options] - Custom subnet or BLE mode
    * @returns {Promise<ScanResult>} List of found printers
    */
   async scanForPrinters(options = {}) {
+    const { useBle, skipCache } = options;
     const serviceOk = await this._checkService();
+    const bleSupported = this._isBleSupported();
 
-    if (!serviceOk) {
-      return {
-        success: false,
-        error:
-          'Printer service is not available. Add printer-server.js and vite-plugin-zebra-printer.js to your project.',
-        printers: [],
-        count: 0,
-      };
+    // Check if last saved printer is still reachable (fast reconnect)
+    if (!skipCache && !useBle) {
+      const lastPrinter = this._loadFromStorage();
+      if (lastPrinter?.ip && serviceOk) {
+        console.log('[Cache] Checking:', lastPrinter.ip);
+        const check = await this._fetch('/check', {
+          method: 'POST',
+          body: JSON.stringify({ ip: lastPrinter.ip }),
+        });
+
+        if (check.reachable) {
+          console.log('[Cache] Printer reachable');
+          // Auto-connect to last printer
+          this.connectedPrinter = lastPrinter;
+          return {
+            success: true,
+            printers: [
+              {
+                name: lastPrinter.name || `Zebra @ ${lastPrinter.ip}`,
+                address: lastPrinter.ip,
+                type: 'network',
+                paired: true, // Mark as "paired" since it was saved
+              },
+            ],
+            count: 1,
+            fromCache: true,
+            autoConnected: true,
+          };
+        }
+        console.log('[Cache] Printer not reachable, scanning...');
+      }
+    }
+
+    // If explicitly requesting BLE or printer-server not available
+    if (useBle || !serviceOk) {
+      if (!bleSupported) {
+        return {
+          success: false,
+          error:
+            'Web Bluetooth is not supported in this browser. Use Chrome or Edge.',
+          printers: [],
+          count: 0,
+        };
+      }
+
+      console.log('[Web] Using BLE scan...');
+      return await this._scanBlePrinters();
     }
 
     const subnet = options.subnet || this.defaultSubnet || '192.168.1';
 
-    // Scan the network (can be slow)
+    // Try TCP/IP scan first
     const result = await this._fetch(
       `/scan?subnet=${encodeURIComponent(subnet)}`
     );
 
-    if (result.success) {
+    if (result.success && result.printers?.length > 0) {
       return {
         success: true,
         printers: (result.printers || []).map((p) => ({
@@ -307,14 +754,30 @@ class ZebraPrinterWeb extends WebPlugin {
           paired: false,
         })),
         count: result.printers?.length || 0,
+        method: 'tcp',
       };
     }
 
+    // Fallback to BLE if TCP/IP found nothing and BLE is supported
+    if (bleSupported) {
+      console.log('[Web] TCP/IP found nothing, trying BLE...');
+      const bleResult = await this._scanBlePrinters();
+
+      if (bleResult.success) {
+        return {
+          ...bleResult,
+          method: 'bluetooth',
+          tcpFallback: true,
+        };
+      }
+    }
+
     return {
       success: false,
-      error: result.error || 'Scan failed',
+      error: result.error || 'No printers found',
       printers: [],
       count: 0,
+      bleAvailable: bleSupported,
     };
   }
 
@@ -326,24 +789,45 @@ class ZebraPrinterWeb extends WebPlugin {
   async connect(options) {
     const { address, type } = options || {};
 
-    if (!address) {
-      return {
-        success: false,
-        connected: false,
-        error: 'Printer address (IP) not provided',
-      };
+    // BLE connection (like iOS)
+    if (type === 'bluetooth') {
+      if (!this._isBleSupported()) {
+        return {
+          success: false,
+          connected: false,
+          error:
+            'Web Bluetooth is not supported in this browser. Use Chrome or Edge.',
+        };
+      }
+
+      console.log('[Web] Connecting via BLE...');
+      return await this._connectBle(address);
     }
 
-    // On web we support only network connections
-    if (type === 'bluetooth') {
+    // If no address provided but BLE devices were discovered, connect via BLE
+    if (!address && this.discoveredBleDevices.length > 0) {
+      console.log('[Web] No IP, using discovered BLE device...');
+      return await this._connectBle(this.discoveredBleDevices[0].id);
+    }
+
+    if (!address) {
+      // No address and no BLE devices - try to scan BLE
+      if (this._isBleSupported()) {
+        console.log('[Web] No address, scanning BLE...');
+        const scanResult = await this._scanBlePrinters();
+        if (scanResult.success && scanResult.printers.length > 0) {
+          return await this._connectBle(scanResult.printers[0].address);
+        }
+      }
+
       return {
         success: false,
         connected: false,
-        error:
-          'Bluetooth is not available on web. Use IP address or test in the iOS app.',
+        error: 'Printer address (IP) not provided',
       };
     }
 
+    // TCP/IP connection via printer-server
     const result = await this._fetch('/connect', {
       method: 'POST',
       body: JSON.stringify({ ip: address }),
@@ -356,6 +840,9 @@ class ZebraPrinterWeb extends WebPlugin {
         type: 'network',
       };
 
+      // Save to localStorage for quick reconnect
+      this._saveToStorage(this.connectedPrinter);
+
       return {
         success: true,
         connected: true,
@@ -365,6 +852,12 @@ class ZebraPrinterWeb extends WebPlugin {
       };
     }
 
+    // If TCP connection failed and BLE is supported, offer BLE as fallback
+    if (this._isBleSupported()) {
+      console.log('[Web] TCP failed, trying BLE...');
+      return await this._connectBle(address);
+    }
+
     return {
       success: false,
       connected: false,
@@ -411,9 +904,20 @@ class ZebraPrinterWeb extends WebPlugin {
 
   /**
    * Disconnect from the printer
+   * @param {{clearSaved?: boolean}} [options] - Options for disconnect
    * @returns {Promise<DisconnectResult>} Disconnect result
    */
-  async disconnect() {
+  async disconnect(options = {}) {
+    // Disconnect BLE if connected
+    if (this.connectedPrinter?.type === 'bluetooth') {
+      this._disconnectBle();
+    }
+
+    // Optionally clear saved printer
+    if (options.clearSaved) {
+      this._saveToStorage(null);
+    }
+
     this.connectedPrinter = null;
     await Promise.resolve();
     return {
@@ -421,6 +925,367 @@ class ZebraPrinterWeb extends WebPlugin {
       connected: false,
     };
   }
+
+  /**
+   * Get device network info (web not supported directly)
+   * @returns {Promise<{supported: boolean, type: string, error?: string, ip?: string, ssid?: string}>} Network info proxied via printer-server if available
+   */
+  async getNetworkInfo() {
+    const serviceOk = await this._checkService();
+    if (!serviceOk) {
+      return {
+        supported: false,
+        type: 'unknown',
+        error: 'Printer service not available for network info',
+      };
+    }
+
+    const result = await this._fetch('/network-info', { method: 'GET' });
+
+    if (result?.success) {
+      return {
+        supported: true,
+        type: result.type || 'unknown',
+        ip: result.ip,
+        ssid: result.ssid,
+      };
+    }
+
+    return {
+      supported: false,
+      type: 'unknown',
+      error: result?.error || 'Network info not available',
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // DEV HELPER METHODS
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Get saved printer from localStorage
+   * @returns {Object|null} Saved printer settings
+   */
+  getSavedPrinter() {
+    return this._loadFromStorage();
+  }
+
+  /**
+   * Try to auto-connect to saved printer
+   * @returns {Promise<ConnectResult>} Connection result
+   */
+  async autoConnect() {
+    const savedPrinter = this._loadFromStorage();
+
+    if (!savedPrinter) {
+      return {
+        success: false,
+        connected: false,
+        error: 'No saved printer found',
+      };
+    }
+
+    console.log('[AutoConnect] Trying:', savedPrinter.name);
+
+    // For BLE printers, need to re-scan and connect
+    if (savedPrinter.type === 'bluetooth') {
+      return await this.connect({
+        type: 'bluetooth',
+        address: savedPrinter.address,
+      });
+    }
+
+    // For TCP/IP printers, check if reachable first
+    if (savedPrinter.ip) {
+      const check = await this._fetch('/check', {
+        method: 'POST',
+        body: JSON.stringify({ ip: savedPrinter.ip }),
+      });
+
+      if (check.reachable) {
+        this.connectedPrinter = savedPrinter;
+        return {
+          success: true,
+          connected: true,
+          address: savedPrinter.ip,
+          type: 'network',
+          message: 'Auto-connected to saved printer',
+          fromCache: true,
+        };
+      }
+    }
+
+    return {
+      success: false,
+      connected: false,
+      error: 'Saved printer not reachable',
+    };
+  }
+
+  /**
+   * Show PWA-style printer picker dialog
+   * Creates a native-feeling modal for printer selection
+   * @param {{title?: string, scanOnOpen?: boolean}} [options] - Dialog options
+   * @returns {Promise<{success: boolean, printer?: Object, cancelled?: boolean}>} Selected printer or cancellation
+   */
+  async showPrinterPicker(options = {}) {
+    const { title = 'Select Printer', scanOnOpen = true } = options;
+
+    const { promise, resolve } = Promise.withResolvers();
+
+    // Create modal container
+    const overlay = document.createElement('div');
+    overlay.id = 'zebra-printer-picker';
+    overlay.innerHTML = this._getPickerHTML(title);
+    document.body.append(overlay);
+
+    // Store state for this picker instance
+    const pickerState = {
+      printers: [],
+      resolve,
+      cleanup: () => overlay.remove(),
+    };
+
+    // Setup event handlers
+    this._setupPickerEvents(overlay, pickerState);
+
+    // Auto-scan if requested
+    if (scanOnOpen) {
+      await this._updatePickerPrinters(overlay, {});
+    }
+
+    return promise;
+  }
+
+  /**
+   * Get picker HTML template
+   * @private
+   * @param {string} title - Dialog title
+   * @returns {string} HTML string
+   */
+  _getPickerHTML(title) {
+    const bleButton = this._isBleSupported()
+      ? '<button class="zpp-btn zpp-btn-ble" data-action="ble">BLE</button>'
+      : '';
+
+    return `
+      <style>
+        #zebra-printer-picker {
+          position: fixed;
+          inset: 0;
+          z-index: 999999;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          background: rgba(0, 0, 0, 0.5);
+          backdrop-filter: blur(4px);
+          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        }
+        .zpp-modal {
+          background: white;
+          border-radius: 16px;
+          width: 90%;
+          max-width: 400px;
+          max-height: 80vh;
+          overflow: hidden;
+          box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+          animation: zpp-slideUp 0.3s ease-out;
+        }
+        @keyframes zpp-slideUp {
+          from { opacity: 0; transform: translateY(20px); }
+          to { opacity: 1; transform: translateY(0); }
+        }
+        .zpp-header {
+          padding: 20px;
+          border-bottom: 1px solid #e5e7eb;
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+        }
+        .zpp-header h2 { margin: 0; font-size: 18px; font-weight: 600; color: #111827; }
+        .zpp-close { background: none; border: none; padding: 8px; cursor: pointer; border-radius: 8px; color: #6b7280; font-size: 18px; }
+        .zpp-close:hover { background: #f3f4f6; }
+        .zpp-content { padding: 16px; max-height: 400px; overflow-y: auto; }
+        .zpp-loading { text-align: center; padding: 40px 20px; color: #6b7280; }
+        .zpp-spinner {
+          width: 40px; height: 40px;
+          border: 3px solid #e5e7eb; border-top-color: #3b82f6;
+          border-radius: 50%; animation: zpp-spin 1s linear infinite;
+          margin: 0 auto 16px;
+        }
+        @keyframes zpp-spin { to { transform: rotate(360deg); } }
+        .zpp-list { list-style: none; margin: 0; padding: 0; }
+        .zpp-item {
+          display: flex; align-items: center; padding: 16px;
+          border: 1px solid #e5e7eb; border-radius: 12px;
+          margin-bottom: 8px; cursor: pointer; transition: all 0.15s ease;
+        }
+        .zpp-item:hover { border-color: #3b82f6; background: #eff6ff; }
+        .zpp-item.saved { border-color: #10b981; background: #ecfdf5; }
+        .zpp-icon {
+          width: 40px; height: 40px; background: #f3f4f6; border-radius: 10px;
+          display: flex; align-items: center; justify-content: center;
+          margin-right: 12px; font-size: 20px;
+        }
+        .zpp-info { flex: 1; }
+        .zpp-name { font-weight: 500; color: #111827; margin-bottom: 2px; }
+        .zpp-addr { font-size: 13px; color: #6b7280; }
+        .zpp-badge { font-size: 11px; padding: 2px 8px; border-radius: 9999px; background: #10b981; color: white; margin-left: 8px; }
+        .zpp-empty { text-align: center; padding: 40px 20px; color: #6b7280; }
+        .zpp-actions { padding: 16px; border-top: 1px solid #e5e7eb; display: flex; gap: 8px; }
+        .zpp-btn {
+          flex: 1; padding: 12px 16px; border-radius: 10px;
+          font-size: 14px; font-weight: 500; cursor: pointer;
+          border: none; transition: all 0.15s ease;
+        }
+        .zpp-btn-secondary { background: #f3f4f6; color: #374151; }
+        .zpp-btn-secondary:hover { background: #e5e7eb; }
+        .zpp-btn-primary { background: #3b82f6; color: white; }
+        .zpp-btn-primary:hover { background: #2563eb; }
+        .zpp-btn-ble { background: #8b5cf6; color: white; }
+        .zpp-btn-ble:hover { background: #7c3aed; }
+      </style>
+      <div class="zpp-modal">
+        <div class="zpp-header">
+          <h2>${title}</h2>
+          <button class="zpp-close" data-action="close">✕</button>
+        </div>
+        <div class="zpp-content">
+          <div class="zpp-loading">
+            <div class="zpp-spinner"></div>
+            <div>Searching for printers...</div>
+          </div>
+        </div>
+        <div class="zpp-actions">
+          <button class="zpp-btn zpp-btn-secondary" data-action="cancel">Cancel</button>
+          <button class="zpp-btn zpp-btn-primary" data-action="rescan">Rescan</button>
+          ${bleButton}
+        </div>
+      </div>
+    `;
+  }
+
+  /**
+   * Setup picker event handlers
+   * @private
+   * @param {HTMLElement} overlay - Picker overlay element
+   * @param {Object} state - Picker state object
+   */
+  _setupPickerEvents(overlay, state) {
+    // Handle button clicks
+    overlay.addEventListener('click', async (e) => {
+      const action = e.target.dataset?.action;
+
+      if (action === 'close' || action === 'cancel') {
+        state.cleanup();
+        state.resolve({ success: false, cancelled: true });
+        return;
+      }
+
+      if (action === 'rescan') {
+        await this._updatePickerPrinters(overlay, { skipCache: true });
+        return;
+      }
+
+      if (action === 'ble') {
+        await this._updatePickerPrinters(overlay, { useBle: true });
+        return;
+      }
+
+      // Check if clicked on printer item
+      const item = e.target.closest('.zpp-item');
+      if (item) {
+        const printer = {
+          address: item.dataset.address,
+          type: item.dataset.type,
+          name: item.dataset.name,
+        };
+
+        state.cleanup();
+
+        // Auto-connect to selected printer
+        const connectResult = await this.connect({
+          address: printer.address,
+          type: printer.type,
+        });
+
+        state.resolve({
+          success: connectResult.success,
+          printer: connectResult.success ? printer : undefined,
+          error: connectResult.error,
+        });
+      }
+    });
+
+    // Close on overlay click (outside modal)
+    overlay.addEventListener('click', (e) => {
+      if (e.target === overlay) {
+        state.cleanup();
+        state.resolve({ success: false, cancelled: true });
+      }
+    });
+  }
+
+  /**
+   * Update picker with scanned printers
+   * @private
+   * @param {HTMLElement} overlay - Picker overlay element
+   * @param {Object} options - Scan options
+   */
+  async _updatePickerPrinters(overlay, options) {
+    const content = overlay.querySelector('.zpp-content');
+    const loadingMsg = options.useBle
+      ? 'Scanning for Bluetooth printers...'
+      : 'Searching for printers...';
+
+    content.innerHTML = `
+      <div class="zpp-loading">
+        <div class="zpp-spinner"></div>
+        <div>${loadingMsg}</div>
+      </div>
+    `;
+
+    const result = await this.scanForPrinters(options);
+    const printers = result.printers || [];
+
+    if (printers.length === 0) {
+      content.innerHTML = `
+        <div class="zpp-empty">
+          <div style="font-size: 32px; margin-bottom: 16px; opacity: 0.5;">⎙</div>
+          <div>No printers found</div>
+          <div style="font-size: 13px; margin-top: 8px;">Make sure the printer is on and connected to the network</div>
+        </div>
+      `;
+      return;
+    }
+
+    const savedPrinter = this._loadFromStorage();
+    let html = '<ul class="zpp-list">';
+
+    for (const p of printers) {
+      const isSaved =
+        savedPrinter?.ip === p.address || savedPrinter?.address === p.address;
+      const icon = p.type === 'bluetooth' ? 'BT' : 'IP';
+      const typeLabel = p.type === 'bluetooth' ? 'Bluetooth' : 'Network';
+      const badge = p.paired ? '<span class="zpp-badge">Saved</span>' : '';
+
+      html += `
+        <li class="zpp-item ${isSaved ? 'saved' : ''}" 
+            data-address="${p.address}" 
+            data-type="${p.type}" 
+            data-name="${p.name}">
+          <div class="zpp-icon">${icon}</div>
+          <div class="zpp-info">
+            <div class="zpp-name">${p.name}${badge}</div>
+            <div class="zpp-addr">${p.address} • ${typeLabel}</div>
+          </div>
+        </li>
+      `;
+    }
+
+    html += '</ul>';
+    content.innerHTML = html;
+  }
 }
 
 const ZebraPrinter = registerPlugin('ZebraPrinter', {