From f8a77d13ab50c7808ef98e0096d6af4bf0ce73dc Mon Sep 17 00:00:00 2001
From: "Felipe M." <me@fmartingr.com>
Date: Sat, 23 May 2026 08:33:31 +0200
Subject: [PATCH] Gate Bluetooth and USB transports independently

Previously the compatibility check disabled all printing when Web
Bluetooth was missing, even if WebUSB was available. Browsers that
ship only one of the two device APIs (e.g. privacy-focused Chromium
forks) couldn't reach the working transport.

Changes:
- checkCompatibility() now keeps state.canPrint true when at least
  one transport is available, and warns about each missing one
  individually instead of blocking everything.
- The connection-type <select> options are now *disabled* (with a
  tooltip) when their transport is unavailable, instead of one being
  silently removed. Same treatment for the mobile select.
- When Bluetooth is missing but USB is present, the default
  connection type flips to 'usb' and both selects update to match.
- The Connect button's no-transport alert now fires only when truly
  no path is available, and recommends a Chromium-based browser.
- User-facing copy across app.js, index.html and usb.js drops the
  'Web Bluetooth' / 'WebUSB' / 'API' jargon in favour of plain
  'Bluetooth printing' / 'USB printing'.
- README: new 'USB on Linux' section covering the usblp kernel
  driver claim-interface error and three fix paths (modprobe -r,
  blacklist, per-device udev rule), plus a note on the generic
  'USB Composite Device' productName triggering the manual model
  picker.
---
 README.md          | 52 ++++++++++++++++++++++++++++++++++++++----
 src/web/app.js     | 57 ++++++++++++++++++++++++++++++++++++----------
 src/web/index.html |  2 +-
 src/web/usb.js     |  2 +-
 4 files changed, 95 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index abdae96..a9f98a6 100644
--- a/README.md
+++ b/README.md
@@ -93,7 +93,7 @@ Dynamic values that evaluate at print/export time using `[[expression]]` syntax:
 - **Device memory** - App remembers your printer model for each device
 
 ### Local System Fonts
-- **System font access** - Use any font installed on your computer (Chrome/Edge only)
+- **System font access** - Use any font installed on your computer (Chromium browsers only, e.g. Chrome/Edge/Opera)
 - **One-click setup** - Click "Add System Fonts" to grant permission
 - **Persistent preference** - Fonts auto-load on future visits after first authorization
 - **Graceful fallback** - Preset fonts always available; system fonts are additive
@@ -169,7 +169,7 @@ If auto-detection fails (e.g., printer shows serial number instead of model), yo
 ## Quick Start
 
 **Option 1: Use the live version**
-1. Open https://phomymo.affordablemagic.net in Chrome
+1. Open https://phomymo.affordablemagic.net in Chrome, Edge, Opera or another Chromium-based browser
 2. Click **Connect** to pair with your Phomemo printer via Bluetooth (or **USB** for PM-241)
 3. Design your label and click **Print**
 
@@ -198,9 +198,9 @@ If auto-detection fails (e.g., printer shows serial number instead of model), yo
 
 ## Browser Requirements
 
-- Chrome, Edge, or another Chromium-based browser (desktop or Android)
+- Chrome, Edge, Opera or another Chromium-based browser (desktop or Android)
 - Web Bluetooth API support (not available in Firefox or Safari)
-- WebUSB support for PM-241 printers (Linux may require udev rules)
+- WebUSB support for PM-241 printers (Linux: see [USB on Linux](#usb-on-linux))
 - HTTPS or localhost
 - **Mobile**: Android Chrome supported with full touch interface; iOS not supported (no Web Bluetooth)
 
@@ -208,6 +208,50 @@ If auto-detection fails (e.g., printer shows serial number instead of model), yo
 
 When the Bluetooth device picker appears, select the device showing a **signal strength indicator**. Devices listed without signal strength may be cached/ghost entries that won't connect properly.
 
+## USB on Linux
+
+On Linux, the kernel's generic USB printer driver (`usblp`) auto-binds to thermal printers when they're plugged in and claims the printer interface. WebUSB then can't claim the same interface and you'll see:
+
+```
+Failed to execute 'claimInterface' on 'USBDevice': Unable to claim interface.
+```
+
+You need to release the device from `usblp`. Pick one:
+
+**Quick test (non-persistent):** unload the module without unplugging the printer.
+
+```bash
+sudo modprobe -r usblp
+```
+
+Click Connect again. `usblp` will rebind on the next replug or reboot.
+
+**Persistent (blacklist):** prevents `usblp` from ever loading. Simple, but **breaks CUPS / `lp` printing for all USB printers** on this machine.
+
+```bash
+echo 'blacklist usblp' | sudo tee /etc/modprobe.d/blacklist-usblp.conf
+sudo modprobe -r usblp
+```
+
+**Persistent (per-device, recommended if you also use CUPS):** detach `usblp` only from the Phomemo. Get the printer's vendor/product ID with `lsusb`, then create `/etc/udev/rules.d/70-phomemo-webusb.rules`:
+
+```
+# Replace XXXX:YYYY with your IDs from `lsusb`
+SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="YYYY", MODE="0660", TAG+="uaccess"
+ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="YYYY", \
+  RUN+="/bin/sh -c 'echo -n %k:1.0 > /sys/bus/usb/drivers/usblp/unbind 2>/dev/null || true'"
+```
+
+Reload and replug:
+
+```bash
+sudo udevadm control --reload-rules
+```
+
+### Printer model not auto-detected on USB
+
+Many Phomemo printers report a generic name like "USB Composite Device" over USB rather than a recognizable model string. When this happens, the app will prompt you to pick the model on first connection and remember your choice for next time. You can also set it manually in Print Settings → Printer Model.
+
 ## How It Works
 
 1. **Label Size Configuration** - Sets pixel dimensions based on label size (203 DPI)
diff --git a/src/web/app.js b/src/web/app.js
index ade63f7..46689d5 100644
--- a/src/web/app.js
+++ b/src/web/app.js
@@ -4560,9 +4560,13 @@ function initPrinterModelPrompt() {
  * @param {MouseEvent} event - Click event (shift+click shows all devices)
  */
 async function handleConnect(event) {
-  // Check if printing is supported in this browser
+  // No transports at all → tell the user which browsers do work
   if (!state.canPrint) {
-    alert('Printing is not available in this browser.\n\nPlease use Chrome, Edge, or Opera on desktop for Bluetooth printing.');
+    alert(
+      'Printing is not available in this browser.\n\n' +
+      'Bluetooth and USB printing are both unavailable. Please use Chrome, ' +
+      'Edge, Opera, or another Chromium-based browser to print.'
+    );
     return;
   }
 
@@ -5533,6 +5537,26 @@ function hideShortcutsModal() {
   $('#shortcuts-modal').classList.add('hidden');
 }
 
+/**
+ * Disable options in a connection-type <select> whose underlying transport
+ * (Web Bluetooth / WebUSB) isn't exposed by this browser.
+ * @param {HTMLSelectElement|null} selectEl
+ */
+function disableUnsupportedConnOptions(selectEl) {
+  if (!selectEl) return;
+  const hasBluetooth = 'bluetooth' in navigator;
+  const hasUsb = 'usb' in navigator;
+  for (const opt of selectEl.options) {
+    if (opt.value === 'ble' && !hasBluetooth) {
+      opt.disabled = true;
+      opt.title = 'Bluetooth printing isn\'t supported in this browser';
+    } else if (opt.value === 'usb' && !hasUsb) {
+      opt.disabled = true;
+      opt.title = 'USB printing isn\'t supported in this browser';
+    }
+  }
+}
+
 /**
  * Check browser compatibility
  */
@@ -5545,13 +5569,19 @@ function checkCompatibility() {
     canPrint = false;
   }
 
-  if (!('bluetooth' in navigator)) {
-    warnings.push('Web Bluetooth not supported - printing requires Chrome, Edge, or Opera');
-    canPrint = false;
+  const hasBluetooth = 'bluetooth' in navigator;
+  const hasUsb = 'usb' in navigator;
+
+  if (!hasBluetooth) {
+    warnings.push('Bluetooth printing isn\'t supported in this browser');
+  }
+  if (!hasUsb) {
+    warnings.push('USB printing isn\'t supported in this browser');
   }
 
-  if (!('usb' in navigator)) {
-    console.warn('WebUSB not supported - USB printing will not be available');
+  // Need at least one transport to print at all
+  if (!hasBluetooth && !hasUsb) {
+    canPrint = false;
   }
 
   // Store print capability in state for disabling print buttons
@@ -5571,7 +5601,7 @@ function checkCompatibility() {
             </div>
             <div>
               <h3 class="text-lg font-bold">Limited Browser Support</h3>
-              <p class="text-amber-100 text-xs">Printing requires Chrome, Edge, or Opera</p>
+              <p class="text-amber-100 text-xs">Printing requires Chrome, Edge, Opera or another Chromium-based browser</p>
             </div>
           </div>
         </div>
@@ -5860,6 +5890,7 @@ function initMobileUI() {
   const mobileConnType = $('#mobile-conn-type');
   const desktopConnType = $('#conn-type');
   if (mobileConnType && desktopConnType) {
+    disableUnsupportedConnOptions(mobileConnType);
     mobileConnType.value = desktopConnType.value;
     mobileConnType.addEventListener('change', (e) => {
       desktopConnType.value = e.target.value;
@@ -6739,11 +6770,13 @@ function init() {
     setTapeWidth(parseInt(e.target.value, 10));
   });
 
-  // Connection type
+  // Connection type — disable options whose underlying transport is missing
   const connType = $('#conn-type');
-  if (!('usb' in navigator)) {
-    const usbOption = connType.querySelector('option[value="usb"]');
-    if (usbOption) usbOption.remove();
+  disableUnsupportedConnOptions(connType);
+  // If default ('ble') isn't supported, fall back to USB when available
+  if (!('bluetooth' in navigator) && 'usb' in navigator) {
+    state.connectionType = 'usb';
+    if (connType) connType.value = 'usb';
   }
   connType.addEventListener('change', (e) => {
     state.connectionType = e.target.value;
diff --git a/src/web/index.html b/src/web/index.html
index ede48ce..c869d79 100644
--- a/src/web/index.html
+++ b/src/web/index.html
@@ -1513,7 +1513,7 @@ <h4 class="font-semibold text-gray-900 text-sm">Multi-Label Rolls</h4>
         </div>
 
         <!-- Browser note -->
-        <p class="text-xs text-gray-500 text-center">Requires Chrome, Edge, or Chromium-based browser with Web Bluetooth.</p>
+        <p class="text-xs text-gray-500 text-center">Requires Chrome, Edge or another Chromium-based browser.</p>
       </div>
 
       <!-- Footer -->
diff --git a/src/web/usb.js b/src/web/usb.js
index 3884d07..6237e0d 100644
--- a/src/web/usb.js
+++ b/src/web/usb.js
@@ -90,7 +90,7 @@ export class USBTransport {
    */
   async connect(options = {}) {
     if (!USBTransport.isAvailable()) {
-      throw new Error('WebUSB is not supported in this browser');
+      throw new Error('USB printing isn\'t supported in this browser');
     }
 
     // Try to reconnect to existing device first