%E7%BE%8E%E5%9B%BD%E7%89%88/Food%20Labeling%20Management%20App%20UniApp/src/utils/print/manager/printerManager.ts

import {
  clearPrinter,
  discoverBleWriteCharacteristic,
  ensureBleUartNotifyIfNeeded,
  getBluetoothConnection,
  getCurrentPrinterDriverKey,
  getPrinterType,
  getStoredUposPrintOptions,
  isNativeBaseClassicBluetoothTransport,
  isVirtualBtBluetoothConnection,
  sendToPrinter,
  setBluetoothConnection,
  setBuiltinPrinter,
} from '../printerConnection'
// @ts-ignore - js bridge module (app-plus only)
import classicBluetooth from '../bluetoothTool.js'
import { rasterizeImageData, rasterizeImageForPrinter, trimMonochromeImageBottomWhitespace, sharpenInvertedTextInMonochromeRaster, INVERTED_TEXT_IMAGE_THRESHOLD } from '../imageRaster'
import { buildEscPosImageData, buildEscPosTemplateData } from '../protocols/escPosBuilder'
import { buildTscImageData, buildTscTemplateData } from '../protocols/tscProtocol'
import type { LabelPrintJobPayload } from '../../labelPreview/buildLabelPrintPayload'
import {
  connectNativeFastPrinter as connectNativeFastPrinterPlugin,
  disconnectNativeFastPrinter as disconnectNativeFastPrinterPlugin,
  isNativeFastPrinterAvailable,
  printNativeFastFromLabelPrintJob,
  printNativeFastTemplate as printNativeFastTemplatePlugin,
} from '../nativeFastPrinter'
import {
  getLabelPrintRasterLayout,
  renderLabelPreviewCanvasImageDataForPrint,
  renderLabelPreviewCanvasToTempPathForPrint,
  settleAfterLabelCanvasResize,
} from '../../labelPreview/renderLabelPreviewCanvas'
import {
  ensureTemplateHeightCoversElements,
  rasterDotsToMillimeters,
} from '../templatePhysicalMm'
import { storedValueLooksLikeImagePath } from '../../resolveMediaUrl'
import { printRunDiag } from '../printRunDiagnostics'
import { adaptSystemLabelTemplate } from '../systemTemplateAdapter'
import { templateRequiresCanvasStyleFidelity } from '../nativeTemplateElementSupport'
import { templateHasInvertedTextElements } from '../../invertColorsConfig'
import { hydrateSystemTemplateImagesForPrint } from '../hydrateTemplateImagesForPrint'
import { TEST_PRINT_SYSTEM_TEMPLATE, TEST_PRINT_TEMPLATE_DATA } from '../templates/testPrintTemplate'
import { describePrinterCandidate, getPrinterDriverByKey, resolvePrinterDriver } from './driverRegistry'
import type {
  CurrentPrinterSummary,
  LabelPrintPayload,
  LabelTemplateData,
  RawImageDataSource,
  PrintImageOptions,
  PrinterCandidate,
  PrinterDriver,
  StructuredLabelTemplate,
  SystemLabelTemplate,
} from '../types/printer'
type LastImagePrintDebug = {
  protocol: string
  rasterWidth: number
  rasterHeight: number
  blackPixels: number
  totalPixels: number
  blackRatio: number
  commandBytes: number
  updatedAt: number
}
let lastImagePrintDebug: LastImagePrintDebug | null = null
export function getLastImagePrintDebug (): LastImagePrintDebug | null {
  return lastImagePrintDebug
}
function getPrinterTypeDisplayName (type: '' | 'bluetooth' | 'builtin'): string {
  if (type === 'bluetooth') return 'Bluetooth'
  if (type === 'builtin') return 'Built-in'
  return ''
}
function connectClassicBluetooth (device: PrinterCandidate, driver: PrinterDriver): Promise<void> {
  return new Promise((resolve, reject) => {
    // #ifdef APP-PLUS
    /**
     * 一体机 / Virtual BT / d320fax：在已集成 native-fast-printer（安卓基座 AAR）时优先走佳博 SDK 连接；
     * 不再强制仅用 JS 经典蓝牙，否则光栅大包易超时，且与「走基座」需求不符。
     * gp-d320fx、ESC 等仍走通用 socket。
     */
    const shouldUseGenericClassicOnly =
      driver.key === 'gp-d320fx' ||
      driver.key === 'generic-tsc' ||
      driver.protocol === 'esc'
    const connectClassicSocketFallback = () => {
      try {
        if (!classicBluetooth || typeof classicBluetooth.connDevice !== 'function') {
          reject(new Error('Classic Bluetooth fallback is not available.'))
          return
        }
        classicBluetooth.connDevice(device.deviceId, (ok: boolean) => {
          if (ok) {
            /**
             * connDevice 回调 ok 可能早于 socket/outputStream 就绪；
             * 若立刻测试打印，会出现 state=idle、outputReady=false。
             */
            const start = Date.now()
            const poll = () => {
              const st = typeof classicBluetooth.getDebugState === 'function'
                ? classicBluetooth.getDebugState()
                : null
              const ready = !!st?.outputReady && (!!st?.socketConnected || String(st?.connectionState || '').toLowerCase() === 'connected')
              if (ready) {
                setBluetoothConnection({
                  deviceId: device.deviceId,
                  deviceName: device.name || 'Bluetooth Printer',
                  deviceType: 'classic',
                  transportMode: 'generic',
                  driverKey: driver.key,
                  mtu: driver.preferredBleMtu || 20,
                })
                resolve()
                return
              }
              if (Date.now() - start > 2500) {
                clearPrinter()
                reject(new Error('Classic Bluetooth connection is not ready'))
                return
              }
              setTimeout(poll, 120)
            }
            poll()
            return
          }
          const message = typeof classicBluetooth.getLastError === 'function'
            ? classicBluetooth.getLastError()
            : ''
          clearPrinter()
          reject(new Error(message || 'Classic Bluetooth connection failed.'))
        })
      } catch (error: any) {
        clearPrinter()
        reject(error instanceof Error ? error : new Error(String(error || 'Classic Bluetooth connection failed.')))
      }
    }
    if (!shouldUseGenericClassicOnly && isNativeFastPrinterAvailable()) {
      connectNativeFastPrinterPlugin({
        deviceId: device.deviceId,
        deviceName: device.name || 'Bluetooth Printer',
      }).then(() => {
        setBluetoothConnection({
          deviceId: device.deviceId,
          deviceName: device.name || 'Bluetooth Printer',
          deviceType: 'classic',
          transportMode: 'native-plugin',
          driverKey: driver.key,
          mtu: driver.preferredBleMtu || 20,
        })
        resolve()
      }).catch((error: any) => {
        if (driver.key === 'd320fax') {
          connectClassicSocketFallback()
          return
        }
        reject(error instanceof Error ? error : new Error(String(error || 'Classic Bluetooth connection failed.')))
      })
      return
    }
    if (driver.key === 'd320fax' || shouldUseGenericClassicOnly) {
      connectClassicSocketFallback()
      return
    }
    reject(new Error('NATIVE_FAST_PRINTER_PLUGIN_NOT_FOUND. Please rebuild the custom base with native-fast-printer.'))
    // #endif
    // #ifndef APP-PLUS
    reject(new Error('Classic Bluetooth requires the app.'))
    // #endif
  })
}
function requestBleMtu (deviceId: string, preferredMtu: number): Promise<number> {
  return new Promise((resolve) => {
    const targetMtu = Math.max(20, Math.min(512, Math.round(preferredMtu || 20)))
    if (targetMtu <= 20 || typeof (uni as any).setBLEMTU !== 'function') {
      resolve(20)
      return
    }
    let settled = false
    const done = (value: number) => {
      if (settled) return
      settled = true
      clearTimeout(timer)
      resolve(Math.max(20, Math.round(value || 20)))
    }
    const timer = setTimeout(() => done(20), 3000)
    ;(uni as any).setBLEMTU({
      deviceId,
      mtu: targetMtu,
      success: (res: any) => done(Number(res?.mtu) || targetMtu),
      fail: () => done(20),
    })
  })
}
function connectBlePrinter (device: PrinterCandidate, driver: PrinterDriver): Promise<void> {
  const finalizeExistingBleConnection = async () => {
    const write = await discoverBleWriteCharacteristic(device.deviceId)
    if (!write) {
      throw new Error('No writable characteristic found. This device may not support printing.')
    }
    await ensureBleUartNotifyIfNeeded(device.deviceId, write.serviceId, write.characteristicId)
    const negotiatedMtu = await requestBleMtu(device.deviceId, driver.preferredBleMtu || 20)
    setBluetoothConnection({
      deviceId: device.deviceId,
      deviceName: device.name || 'Bluetooth Printer',
      serviceId: write.serviceId,
      characteristicId: write.characteristicId,
      deviceType: 'ble',
      mtu: negotiatedMtu,
      driverKey: driver.key,
      bleWriteUsesNoResponse: write.bleWriteUsesNoResponse,
    })
  }
  return new Promise((resolve, reject) => {
    uni.createBLEConnection({
      deviceId: device.deviceId,
      timeout: 10000,
      success: async () => {
        try {
          await finalizeExistingBleConnection()
          resolve()
        } catch (e: any) {
          reject(e)
        }
      },
      fail: (err: any) => {
        if (err?.errCode === -1) {
          finalizeExistingBleConnection().then(() => resolve()).catch(reject)
        } else {
          reject(new Error(err?.errMsg || 'BLE connection failed.'))
        }
      },
    })
  })
}
export async function connectBluetoothPrinter (device: PrinterCandidate): Promise<PrinterDriver> {
  const driver = resolvePrinterDriver(device)
  try {
    if (driver.key === 'gp-d320fx') {
      try {
        await connectBlePrinter(device, driver)
      } catch (_) {
        await connectClassicBluetooth(device, driver)
      }
      return driver
    }
    const resolvedType = driver.resolveConnectionType(device)
    if (resolvedType === 'classic') {
      await connectClassicBluetooth(device, driver)
    } else {
      await connectBlePrinter(device, driver)
    }
    return driver
  } catch (error) {
    clearPrinter()
    throw error
  }
}
export function useBuiltinPrinter (driverKey = 'generic-tsc') {
  setBuiltinPrinter(driverKey)
}
export function getCurrentPrinterDriver (): PrinterDriver {
  const type = getPrinterType()
  const storedKey = getCurrentPrinterDriverKey()
  if (storedKey) return getPrinterDriverByKey(storedKey)
  if (type === 'bluetooth') {
    const connection = getBluetoothConnection()
    if (connection) {
      return resolvePrinterDriver({
        deviceId: connection.deviceId,
        name: connection.deviceName,
        type: connection.deviceType,
      })
    }
  }
  if (type === 'builtin') {
    return getPrinterDriverByKey('generic-tsc')
  }
  return getPrinterDriverByKey('generic-tsc')
}
export function getCurrentPrinterSummary (): CurrentPrinterSummary {
  const type = getPrinterType()
  const driver = getCurrentPrinterDriver()
  if (type === 'builtin') {
    return {
      type,
      displayName: getPrinterTypeDisplayName(type),
      deviceId: 'builtin',
      driverKey: driver.key,
      driverName: driver.displayName,
      protocol: driver.protocol,
      deviceType: '',
    }
  }
  if (type === 'bluetooth') {
    const connection = getBluetoothConnection()
    if (connection) {
      return {
        type,
        displayName: getPrinterTypeDisplayName(type),
        deviceId: connection.deviceId,
        driverKey: driver.key,
        driverName: driver.displayName,
        protocol: driver.protocol,
        deviceType: connection.deviceType,
      }
    }
  }
  return {
    type: '',
    displayName: '',
    deviceId: '',
    driverKey: driver.key,
    driverName: driver.displayName,
    protocol: driver.protocol,
    deviceType: '',
  }
}
/**
 * 内置 UPOS 的 `printNormal` 按「原始字节」打出；多数一体机机芯为 ESC/POS 通道，下发 TSPL 会被当成普通字符印在纸上（与预览 JSON 不符）。
 * 内置一律不走原生 TSPL printTemplate，改走预览同源 Canvas → PNG → ESC 光栅（resolveRasterPrintDriver 映射 generic-esc）。
 */
function canUseBuiltinNativeFastTemplatePrint (): boolean {
  return false
}
function canUseNativeFastTemplatePrint (driver: PrinterDriver): boolean {
  if (driver.protocol !== 'tsc' || !isNativeFastPrinterAvailable()) return false
  if (isNativeBaseClassicBluetoothTransport()) return true
  return canUseBuiltinNativeFastTemplatePrint()
}
function templateHasQrDataForCommandPrint (template: SystemLabelTemplate): boolean {
  const elements = template.elements || []
  for (const el of elements) {
    const type = String(el.type || '').toUpperCase()
    if (type !== 'QRCODE') continue
    const cfg = (el.config || {}) as Record<string, unknown>
    const raw = String(
      cfg.data ?? cfg.Data ?? cfg.value ?? cfg.Value ?? cfg.src ?? cfg.Src ?? cfg.url ?? cfg.Url ?? '',
    ).trim()
    if (!raw) continue
    if (storedValueLooksLikeImagePath(raw)) continue
    return true
  }
  return false
}
function templateHasUnsupportedElementsForCommandPrint (template: SystemLabelTemplate): boolean {
  const elements = template.elements || []
  for (const el of elements) {
    const type = String(el.type || '').toUpperCase()
    if (type.startsWith('TEXT_')) continue
    if (
      type === 'WEIGHT'
      || type === 'DATE'
      || type === 'TIME'
      || type === 'DURATION'
      || type === 'NUTRITION'
      || type === 'QRCODE'
      || type === 'BARCODE'
      || type === 'IMAGE'
      || type === 'BLANK'
    ) {
      continue
    }
    return true
  }
  return false
}
/** 预览/业务侧：是否可走 native-fast-printer 的 printTemplate（templateJson + dataJson） */
export function canPrintCurrentLabelViaNativeFastJob (): boolean {
  return canUseNativeFastTemplatePrint(getCurrentPrinterDriver())
}
/**
 * 整页标签光栅是否一律走 canvasGetImageData（纯 JS 二值化），而不用「PNG → Bitmap.getPixels → readJavaIntArrayValue」。
 * - 内置 / Virtual BT：一体机 Bitmap int[] 桥接读数恒为 0
 * - 纯蓝牙 BLE（如 GP-D320FX-ble）：手机基座 strip getPixels 同样全白 → RASTER_EMPTY_IMAGE
 */
export function shouldRasterPrintViaCanvasImageData (): boolean {
  if (getPrinterType() === 'builtin') return true
  if (isVirtualBtBluetoothConnection()) return true
  const conn = getBluetoothConnection()
  if (conn?.deviceType === 'ble') return true
  return false
}
/**
 * 将 buildLabelPrintJobPayload / getLastLabelPrintJobPayload 同构数据送入原生 printTemplate；
 * 与 JSON.stringify(payload.template) + JSON.stringify(payload.printInputJson) 一致。
 */
export async function printLabelPrintJobPayloadForCurrentPrinter (
  payload: LabelPrintJobPayload,
  options: { printQty?: number } = {},
  onProgress?: (percent: number) => void
): Promise<PrinterDriver> {
  const driver = getCurrentPrinterDriver()
  const connection = getBluetoothConnection()
  if (
    driver.protocol === 'tsc'
    && connection?.deviceType === 'classic'
    && connection?.transportMode === 'native-plugin'
    && !isNativeFastPrinterAvailable()
  ) {
    throw new Error('NATIVE_FAST_PRINTER_PLUGIN_NOT_FOUND. Please rebuild the custom base with native-fast-printer.')
  }
  if (!canUseNativeFastTemplatePrint(driver)) {
    throw new Error('Native fast template print is not available for the current printer.')
  }
  const printQty = Math.max(1, options.printQty ?? payload.meta?.printQuantity ?? 1)
  if (canUseBuiltinNativeFastTemplatePrint()) {
    const upos = getStoredUposPrintOptions()
    await printNativeFastFromLabelPrintJob({
      deviceId: 'builtin-upos',
      deviceName: 'Built-in',
      payload,
      dpi: driver.imageDpi || 203,
      printQty,
      outputTransport: 'upos',
      uposPrefer: upos.prefer,
      uposSerialPath: upos.serialPath || '',
      uposBaudrate: upos.baudrate,
    })
    if (onProgress) onProgress(100)
    return driver
  }
  const nativeConnection = getNativeClassicConnection()
  if (!nativeConnection) {
    throw new Error('Native classic Bluetooth connection is not ready.')
  }
  await printNativeFastFromLabelPrintJob({
    deviceId: nativeConnection.deviceId,
    deviceName: nativeConnection.deviceName,
    payload,
    dpi: driver.imageDpi || 203,
    printQty,
  })
  if (onProgress) onProgress(100)
  return driver
}
function getNativeClassicConnection () {
  const connection = getBluetoothConnection()
  if (!connection || connection.deviceType !== 'classic' || connection.transportMode !== 'native-plugin') return null
  return connection
}
/**
 * 连接自检用测试页；**不要**在此处调用 `postUsAppLabelPrint` / 接口 9（仅预览页业务打印落库）。
 */
export async function testPrintCurrentPrinter (onProgress?: (percent: number) => void): Promise<PrinterDriver> {
  const driver = getCurrentPrinterDriver()
  const connection = getBluetoothConnection()
  if (
    driver.protocol === 'tsc'
    && connection?.deviceType === 'classic'
    && connection?.transportMode === 'native-plugin'
    && !isNativeFastPrinterAvailable()
  ) {
    throw new Error('NATIVE_FAST_PRINTER_PLUGIN_NOT_FOUND. Please rebuild the custom base with native-fast-printer.')
  }
  if (canUseNativeFastTemplatePrint(driver)) {
    if (canUseBuiltinNativeFastTemplatePrint()) {
      const upos = getStoredUposPrintOptions()
      await printNativeFastTemplatePlugin({
        deviceId: 'builtin-upos',
        deviceName: 'Built-in',
        template: TEST_PRINT_SYSTEM_TEMPLATE,
        data: TEST_PRINT_TEMPLATE_DATA,
        dpi: driver.imageDpi || 203,
        printQty: 1,
        outputTransport: 'upos',
        uposPrefer: upos.prefer,
        uposSerialPath: upos.serialPath || '',
        uposBaudrate: upos.baudrate,
      })
      if (onProgress) onProgress(100)
      return driver
    }
    const nativeConnection = getNativeClassicConnection()
    if (nativeConnection) {
      await printNativeFastTemplatePlugin({
        deviceId: nativeConnection.deviceId,
        deviceName: nativeConnection.deviceName,
        template: TEST_PRINT_SYSTEM_TEMPLATE,
        data: TEST_PRINT_TEMPLATE_DATA,
        dpi: driver.imageDpi || 203,
        printQty: 1,
      })
      if (onProgress) onProgress(100)
      return driver
    }
  }
  // d320fax 在部分安卓设备上经 sendToPrinter Promise 链会无回调卡住；测试页走经典蓝牙直发更稳定。
  if (driver.key === 'd320fax' && connection?.deviceType === 'classic') {
    // #ifdef APP-PLUS
    try {
      const payload = driver.buildTestPrintData().map((byte) => {
        const v = byte & 0xff
        return v >= 128 ? v - 256 : v
      })
      if (onProgress) onProgress(10)
      /**
       * 部分设备会出现“连接状态看似为 connected，但实际输出流不可写”的假连接。
       * 测试打印前强制重连一次 classic socket，确保 btOutStream 新鲜可用。
       */
      await new Promise<void>((resolve, reject) => {
        if (typeof classicBluetooth?.connDevice !== 'function') {
          reject(new Error('D320FAX_CLASSIC_CONN_API_MISSING'))
          return
        }
        let done = false
        const timer = setTimeout(() => {
          if (done) return
          done = true
          reject(new Error('D320FAX_CLASSIC_RECONNECT_TIMEOUT'))
        }, 8000)
        try {
          classicBluetooth.connDevice(connection.deviceId, (ok: boolean) => {
            if (done) return
            done = true
            clearTimeout(timer)
            if (ok) resolve()
            else reject(new Error(classicBluetooth.getLastError?.() || 'D320FAX_CLASSIC_RECONNECT_FAILED'))
          })
        } catch (e: any) {
          if (done) return
          done = true
          clearTimeout(timer)
          reject(e instanceof Error ? e : new Error(String(e || 'D320FAX_CLASSIC_RECONNECT_EXCEPTION')))
        }
      })
      if (typeof classicBluetooth?.ensureConnection === 'function') {
        classicBluetooth.ensureConnection(connection.deviceId)
      }
      if (onProgress) onProgress(30)
      const ok = await new Promise<boolean>((resolve) => {
        let done = false
        const timer = setTimeout(() => {
          if (done) return
          done = true
          resolve(false)
        }, 10000)
        try {
          if (typeof classicBluetooth?.sendByteDataAsync === 'function') {
            const started = classicBluetooth.sendByteDataAsync(payload, (sendOk: boolean) => {
              if (done) return
              done = true
              clearTimeout(timer)
              resolve(!!sendOk)
            })
            if (started === false) {
              done = true
              clearTimeout(timer)
              resolve(false)
            }
            return
          }
          done = true
          clearTimeout(timer)
          resolve(false)
        } catch {
          done = true
          clearTimeout(timer)
          resolve(false)
        }
      })
      if (!ok) {
        const err = typeof classicBluetooth?.getLastError === 'function'
          ? classicBluetooth.getLastError()
          : ''
        const debug = typeof classicBluetooth?.getDebugState === 'function'
          ? classicBluetooth.getDebugState()
          : null
        const details = [
          `device=${connection.deviceId}`,
          `state=${String(debug?.connectionState || '-')}`,
          `connected=${String(!!debug?.socketConnected)}`,
          `outputReady=${String(!!debug?.outputReady)}`,
          `sendMode=${String(debug?.lastSendMode || '-')}`,
          err ? `lastError=${err}` : '',
        ].filter(Boolean).join('\n')
        throw new Error(`D320FAX_CLASSIC_SEND_TIMEOUT_OR_FAILED\n${details}`)
      }
      if (onProgress) onProgress(100)
      return driver
    } catch (e: any) {
      throw (e instanceof Error ? e : new Error(String(e || 'D320FAX_CLASSIC_SEND_EXCEPTION')))
    }
    // #endif
  }
  /** 内置 UPOS 同业务打印：勿发 TSC 自检页（会被当文本打出） */
  if (getPrinterType() === 'builtin') {
    await sendToPrinter(getPrinterDriverByKey('generic-esc').buildTestPrintData(), onProgress)
    return driver
  }
  await sendToPrinter(driver.buildTestPrintData(), onProgress)
  return driver
}
export async function printLabelForCurrentPrinter (
  payload: LabelPrintPayload,
  onProgress?: (percent: number) => void
): Promise<PrinterDriver> {
  const driver = getCurrentPrinterDriver()
  await sendToPrinter(driver.buildLabelData(payload), onProgress)
  return driver
}
/**
 * 界面仍可存 generic-tsc；内置 UPOS（rk3568 等）实际需 ESC/POS 位图。
 * D320FAX Virtual BT 佳博 SDK 连接为 TSC 模式，禁止转 ESC，否则 write 成功但不出纸。
 */
export function resolveRasterPrintDriver (driver: PrinterDriver): PrinterDriver {
  const useEscRaster =
    getPrinterType() === 'builtin'
    && !isVirtualBtBluetoothConnection()
    && driver.protocol === 'tsc'
  if (useEscRaster) {
    return getPrinterDriverByKey('generic-esc')
  }
  return driver
}
export async function printImageForCurrentPrinter (
  imageSource: string,
  options: PrintImageOptions = {},
  onProgress?: (percent: number) => void
): Promise<PrinterDriver> {
  const driver = getCurrentPrinterDriver()
  const rasterDriver = resolveRasterPrintDriver(driver)
  const printerType = getPrinterType()
  const startedAt = Date.now()
  const withStageTimeout = async <T>(promise: Promise<T>, ms: number, stage: string): Promise<T> => {
    return await new Promise<T>((resolve, reject) => {
      let settled = false
      const timer = setTimeout(() => {
        if (settled) return
        settled = true
        reject(new Error(`PRINT_STAGE_TIMEOUT:${stage}:${ms}`))
      }, ms)
      promise.then(
        (v) => {
          if (settled) return
          settled = true
          clearTimeout(timer)
          resolve(v)
        },
        (e) => {
          if (settled) return
          settled = true
          clearTimeout(timer)
          reject(e)
        }
      )
    })
  }
  console.warn(
    '[print-image] start'
    + ' printerType=' + String(printerType || '-')
    + ' driver=' + String(driver.key || '-')
    + ' rasterDriver=' + String(rasterDriver.key || '-')
    + ' source=' + String(imageSource ? 'ok' : 'empty')
  )
  printRunDiag('printImage_start', {
    printerType,
    driver: driver.key,
    rasterDriver: rasterDriver.key,
    rasterProtocol: rasterDriver.protocol,
  })
  if (onProgress) onProgress(2)
  const rasterOptions: PrintImageOptions = { ...options }
  if (onProgress) {
    const prevRasterCb = options.onRasterizeProgress
    rasterOptions.onRasterizeProgress = (sub) => {
      try {
        prevRasterCb?.(sub)
      } catch (_) {}
      onProgress(2 + Math.round((Math.min(100, Math.max(0, sub)) / 100) * 16))
    }
  }
  const rasterStart = Date.now()
  let raster = rasterDriver.protocol === 'esc'
    ? await rasterizeImageForPrinter(imageSource, rasterDriver, rasterOptions)
    : await withStageTimeout(
      rasterizeImageForPrinter(imageSource, rasterDriver, rasterOptions),
      120000,
      'rasterize'
    )
  console.warn(
    '[print-image] rasterize done'
    + ' ms=' + String(Date.now() - rasterStart)
    + ' width=' + String(raster.width)
    + ' height=' + String(raster.height)
  )
  printRunDiag('printImage_rasterize_done', {
    ms: Date.now() - rasterStart,
    w: raster.width,
    h: raster.height,
  })
  const calcBlackStats = (r: { width: number; height: number; pixels: number[] }) => {
    const totalPixels = Math.max(1, r.width * r.height)
    let blackPixels = 0
    for (let i = 0; i < r.pixels.length; i++) {
      if (r.pixels[i]) blackPixels++
    }
    const blackRatio = blackPixels / totalPixels
    return { totalPixels, blackPixels, blackRatio }
  }
  let { totalPixels, blackPixels, blackRatio } = calcBlackStats(raster)
  if (blackRatio <= 0) {
    printRunDiag('printImage_raster_retry_black0', {
      blackPixels,
      totalPixels,
      firstPassMs: Date.now() - rasterStart,
    })
    // 某些复杂模板在特定阈值/清顶行下会被二值化成“全白”。
    // 为了避免继续抛错，这里做一次失败后重光栅兜底：逐步降低 threshold，并在必要时不再清顶行。
    const tried: string[] = []
    const baseClearTop = options.clearTopRasterRows
    const thresholdCandidates = [150, 130, 110, 90]
    const clearTopCandidates: Array<number | undefined> = [
      baseClearTop,
      0, // 兜底：避免把内容切掉（printSystemTemplateForCurrentPrinter 里默认 clearTopRasterRows=1）
    ].filter((v, i, arr) => v !== undefined || arr.indexOf(undefined) === i)
    const rasterAttempts = async () => {
      for (const clearTop of clearTopCandidates) {
        for (const threshold of thresholdCandidates) {
          tried.push(`clearTop=${String(clearTop)};threshold=${threshold}`)
          /** 重试光栅勿再回调 onRasterizeProgress，否则会从 2% 重新映射，UI 像「15% 突然掉回 5%」 */
          const nextRaster = await rasterizeImageForPrinter(
            imageSource,
            rasterDriver,
            {
              ...rasterOptions,
              threshold,
              ...(typeof clearTop === 'number' ? { clearTopRasterRows: clearTop } : {}),
              onRasterizeProgress: undefined,
            },
          )
          const stats = calcBlackStats(nextRaster)
          console.warn(
            '[print-image] raster retry stats'
            + ` clearTop=${String(clearTop)}`
            + ` threshold=${threshold}`
            + ` black=${stats.blackPixels}/${stats.totalPixels}`
            + ` ratio=${stats.blackRatio.toFixed(4)}`
          )
          if (stats.blackRatio > 0) {
            raster = nextRaster
            totalPixels = stats.totalPixels
            blackPixels = stats.blackPixels
            blackRatio = stats.blackRatio
            return true
          }
        }
      }
      return false
    }
    const ok = await rasterAttempts()
    if (!ok) {
      throw new Error(
        `RASTER_EMPTY_IMAGE:protocol=${String(driver.protocol || '-')};size=${raster.width}x${raster.height};pixels=${blackPixels}/${totalPixels};tried=${tried.join('|')}`
      )
    }
  }
  const rasterForPrint = finalizeRasterForPrint(raster, rasterDriver.protocol, options)
  let data: number[] = []
  if (rasterDriver.protocol === 'esc') {
    data = buildEscPosImageData(rasterForPrint, options)
  } else {
    data = buildTscImageData(raster, options, rasterDriver.imageDpi || 203)
  }
  lastImagePrintDebug = {
    protocol: String(rasterDriver.protocol || '-'),
    rasterWidth: raster.width,
    rasterHeight: raster.height,
    blackPixels,
    totalPixels,
    blackRatio,
    commandBytes: data.length,
    updatedAt: Date.now(),
  }
  console.warn(
    '[print-image] raster-stats'
    + ' logicalDriver=' + String(driver.key || '-')
    + ' protocol=' + String(lastImagePrintDebug.protocol)
    + ' size=' + String(raster.width) + 'x' + String(raster.height)
    + ' black=' + String(blackPixels) + '/' + String(totalPixels)
    + ' ratio=' + String(blackRatio.toFixed(4))
    + ' bytes=' + String(data.length)
  )
  console.warn(
    '[print-image] build bytes done'
    + ' protocol=' + String(rasterDriver.protocol || '-')
    + ' bytes=' + String(data.length)
    + ' elapsed=' + String(Date.now() - startedAt)
  )
  printRunDiag('printImage_commands_built', {
    protocol: rasterDriver.protocol,
    commandBytes: data.length,
    elapsedMs: Date.now() - startedAt,
  })
  if (onProgress) onProgress(22)
  const sendStart = Date.now()
  let sendVisualProgress = 22
  let lastExternalProgressAt = Date.now()
  const reportSendProgress = (p: number) => {
    if (!onProgress) return
    const u = Math.min(100, Math.max(0, Math.round(p)))
    const mapped = 22 + Math.round((u / 100) * 78)
    if (mapped > sendVisualProgress) {
      sendVisualProgress = mapped
      onProgress(mapped)
    } else {
      lastExternalProgressAt = Date.now()
    }
  }
  const sendProgressKeepAlive = onProgress
    ? setInterval(() => {
        // 内置/部分传输链路不会持续回调进度，UI 会停在 22%；这里做轻量保活推进。
        if (Date.now() - lastExternalProgressAt < 1200) return
        if (sendVisualProgress >= 96) return
        sendVisualProgress += sendVisualProgress < 80 ? 2 : 1
        onProgress(sendVisualProgress)
      }, 800)
    : null
  printRunDiag('printImage_send_start', { bytes: data.length })
  if (rasterDriver.protocol === 'esc') {
    try {
      await sendToPrinter(data, (p) => {
        lastExternalProgressAt = Date.now()
        reportSendProgress(p)
        if (p === 0 || p === 50 || p === 100) {
          printRunDiag('printImage_send_progress', { p })
        }
      })
    } finally {
      if (sendProgressKeepAlive) clearInterval(sendProgressKeepAlive)
    }
  } else {
    try {
      const sendStageMs = isVirtualBtBluetoothConnection() ? 600000 : 180000
      await withStageTimeout(
        sendToPrinter(data, (p) => {
          lastExternalProgressAt = Date.now()
          reportSendProgress(p)
          if (p === 0 || p === 50 || p === 100) {
            printRunDiag('printImage_send_progress', { p })
          }
        }),
        sendStageMs,
        'sendToPrinter'
      )
    } finally {
      if (sendProgressKeepAlive) clearInterval(sendProgressKeepAlive)
    }
  }
  console.warn(
    '[print-image] send done'
    + ' ms=' + String(Date.now() - sendStart)
    + ' total=' + String(Date.now() - startedAt)
  )
  printRunDiag('printImage_send_done', {
    sendMs: Date.now() - sendStart,
    totalMs: Date.now() - startedAt,
  })
  if (onProgress) onProgress(100)
  return driver
}
export async function printImageDataForCurrentPrinter (
  imageData: RawImageDataSource,
  options: PrintImageOptions = {},
  onProgress?: (percent: number) => void
): Promise<PrinterDriver> {
  const driver = getCurrentPrinterDriver()
  const rasterDriver = resolveRasterPrintDriver(driver)
  let raster = rasterizeImageData(imageData, options)
  raster = finalizeRasterForPrint(raster, rasterDriver.protocol, options)
  if (onProgress) onProgress(18)
  const data = rasterDriver.protocol === 'esc'
    ? buildEscPosImageData(raster, options)
    : buildTscImageData(raster, options, rasterDriver.imageDpi || 203)
  let sendVisual = 22
  let lastExternalAt = Date.now()
  const reportSend = (p: number) => {
    if (!onProgress) return
    const mapped = 22 + Math.round((Math.min(100, Math.max(0, p)) / 100) * 78)
    if (mapped > sendVisual) {
      sendVisual = mapped
      onProgress(sendVisual)
    } else {
      lastExternalAt = Date.now()
    }
  }
  const keepAlive = onProgress
    ? setInterval(() => {
        if (Date.now() - lastExternalAt < 1200) return
        if (sendVisual >= 96) return
        sendVisual += sendVisual < 80 ? 2 : 1
        onProgress(sendVisual)
      }, 800)
    : null
  try {
    await sendToPrinter(data, reportSend)
  } finally {
    if (keepAlive) clearInterval(keepAlive)
  }
  if (onProgress) onProgress(100)
  return driver
}
export async function printTemplateForCurrentPrinter (
  template: StructuredLabelTemplate,
  data: LabelTemplateData = {},
  onProgress?: (percent: number) => void
): Promise<PrinterDriver> {
  const driver = getCurrentPrinterDriver()
  const bytes = driver.protocol === 'esc'
    ? buildEscPosTemplateData(template, data)
    : buildTscTemplateData(template, data)
  await sendToPrinter(bytes, onProgress)
  return driver
}
/** 与预览页「整页光栅」分支一致：用同一套 canvas 绘制再下发位图（/picture/、中文、￥ 与屏幕一致） */
export type SystemTemplatePrintCanvasRasterOptions = {
  canvasId: string
  componentInstance: any
  /** 绘制前把隐藏 canvas 的 width/height（像素）设为 layout.outW/outH，并 await nextTick */
  applyLayout?: (layout: {
    cw: number
    ch: number
    outW: number
    outH: number
    scale: number
  }) => void | Promise<void>
}
function templateForRasterPrint (template: SystemLabelTemplate): SystemLabelTemplate {
  return ensureTemplateHeightCoversElements(template)
}
/** 内置 ESC 光栅：按图像高度走纸，裁掉底部全白行（布局已按 contentHeight 时仍可去掉少量留白） */
function finalizeRasterForEscPrint (
  raster: { width: number; height: number; pixels: number[] },
  protocol: string,
  options: PrintImageOptions,
) {
  if (protocol !== 'esc' || options.useContentHeight === false) return raster
  return trimMonochromeImageBottomWhitespace(raster, 8)
}
function finalizeRasterForPrint (
  raster: { width: number; height: number; pixels: number[] },
  protocol: string,
  options: PrintImageOptions,
) {
  let out = finalizeRasterForEscPrint(raster, protocol, options)
  if (options.sharpenInvertedText) {
    out = sharpenInvertedTextInMonochromeRaster(out)
  }
  return out
}
function buildInvertedTextPrintImageOptions (
  template: SystemLabelTemplate,
  base: PrintImageOptions = {},
): PrintImageOptions {
  if (!templateHasInvertedTextElements(template)) return base
  return {
    ...base,
    threshold: base.threshold ?? INVERTED_TEXT_IMAGE_THRESHOLD,
    bilinearImageScale: base.bilinearImageScale ?? false,
    sharpenInvertedText: base.sharpenInvertedText ?? true,
    density: base.density ?? 10,
    printSpeed: base.printSpeed ?? 4,
  }
}
export async function printSystemTemplateForCurrentPrinter (
  template: SystemLabelTemplate,
  data: LabelTemplateData = {},
  options: {
    printQty?: number
    canvasRaster?: SystemTemplatePrintCanvasRasterOptions
  } = {},
  onProgress?: (percent: number) => void
): Promise<PrinterDriver> {
  const driver = getCurrentPrinterDriver()
  const rasterDriver = resolveRasterPrintDriver(driver)
  const canvasRaster = options.canvasRaster
  const bypassCanvasRasterForQr =
    !!canvasRaster
    && templateHasQrDataForCommandPrint(template)
    && !templateHasUnsupportedElementsForCommandPrint(template)
    && !templateRequiresCanvasStyleFidelity(template)
  if (canvasRaster && !bypassCanvasRasterForQr) {
    if (onProgress) onProgress(1)
    const templateForDraw = templateForRasterPrint(template)
    const maxDots =
      rasterDriver.imageMaxWidthDots || (rasterDriver.protocol === 'esc' ? 384 : 576)
    const printDpi = rasterDriver.imageDpi || 203
    const layout = getLabelPrintRasterLayout(templateForDraw, maxDots, printDpi)
    if (onProgress) onProgress(4)
    if (canvasRaster.applyLayout) {
      await Promise.resolve(canvasRaster.applyLayout(layout))
    }
    if (onProgress) onProgress(7)
    await settleAfterLabelCanvasResize()
    if (onProgress) onProgress(9)
    const layoutMm = rasterDotsToMillimeters(layout.outW, layout.outH, printDpi)
    const printOpts = buildInvertedTextPrintImageOptions(templateForDraw, {
      printQty: options.printQty || 1,
      clearTopRasterRows: 0,
      targetWidthDots: layout.outW,
      targetHeightDots: layout.outH,
      useContentHeight: false,
      cutBetweenCopies: true,
      widthMm: layoutMm.widthMm,
      heightMm: layoutMm.heightMm,
    })
    const mapRasterProgress = onProgress
      ? (p: number) => {
          onProgress(12 + Math.round((Math.min(100, Math.max(0, p)) / 100) * 88))
        }
      : undefined
    /** 内置一体机：统一 canvas 取像素，避免 Bitmap int[] 桥接假 0 */
    if (shouldRasterPrintViaCanvasImageData()) {
      try {
        const imageData = await renderLabelPreviewCanvasImageDataForPrint(
          canvasRaster.canvasId,
          canvasRaster.componentInstance,
          templateForDraw,
          layout,
        )
        if (onProgress) onProgress(12)
        await printImageDataForCurrentPrinter(imageData, printOpts, mapRasterProgress)
        return driver
      } catch (e) {
        console.warn('[print] builtin canvasGetImageData failed, fallback PNG→Bitmap raster', e)
      }
    }
    const tmpPath = await renderLabelPreviewCanvasToTempPathForPrint(
      canvasRaster.canvasId,
      canvasRaster.componentInstance,
      templateForDraw,
      layout,
    )
    if (onProgress) onProgress(12)
    await printImageForCurrentPrinter(tmpPath, printOpts, mapRasterProgress)
    return driver
  }
  const connection = getBluetoothConnection()
  /**
   * d320fax + classic 历史上存在卡顿风险，这里对图片 hydration 增加总超时兜底：
   * - 成功：使用本地化后的图片路径，提高 IMAGE/QRCODE 出图概率
   * - 超时/失败：自动回退原模板，保证仍可继续出纸
   */
  if (onProgress) onProgress(1)
  const preferStableForD320faxClassic = driver.key === 'd320fax' && connection?.deviceType === 'classic'
  let templateReady = template
  if (preferStableForD320faxClassic) {
    try {
      if (onProgress) onProgress(3)
      templateReady = await Promise.race<SystemLabelTemplate>([
        hydrateSystemTemplateImagesForPrint(template),
        new Promise<SystemLabelTemplate>((resolve) => setTimeout(() => resolve(template), 8000)),
      ])
    } catch {
      templateReady = template
    }
  } else {
    if (onProgress) onProgress(3)
    templateReady = await hydrateSystemTemplateImagesForPrint(template)
  }
  if (onProgress) onProgress(12)
  if (
    driver.protocol === 'tsc'
    && connection?.deviceType === 'classic'
    && connection?.transportMode === 'native-plugin'
    && !isNativeFastPrinterAvailable()
  ) {
    throw new Error('NATIVE_FAST_PRINTER_PLUGIN_NOT_FOUND. Please rebuild the custom base with native-fast-printer.')
  }
  if (canUseNativeFastTemplatePrint(driver)) {
    if (canUseBuiltinNativeFastTemplatePrint()) {
      const upos = getStoredUposPrintOptions()
      await printNativeFastTemplatePlugin({
        deviceId: 'builtin-upos',
        deviceName: 'Built-in',
        template: templateReady,
        data,
        dpi: driver.imageDpi || 203,
        printQty: options.printQty || 1,
        outputTransport: 'upos',
        uposPrefer: upos.prefer,
        uposSerialPath: upos.serialPath || '',
        uposBaudrate: upos.baudrate,
      })
      if (onProgress) onProgress(100)
      return driver
    }
    const nativeConnection = getNativeClassicConnection()
    if (nativeConnection) {
      await printNativeFastTemplatePlugin({
        deviceId: nativeConnection.deviceId,
        deviceName: nativeConnection.deviceName,
        template: templateReady,
        data,
        dpi: driver.imageDpi || 203,
        printQty: options.printQty || 1,
      })
      if (onProgress) onProgress(100)
      return driver
    }
  }
  if (onProgress) onProgress(14)
  const structuredTemplate = adaptSystemLabelTemplate(templateReady, data, {
    dpi: driver.imageDpi || 203,
    printQty: options.printQty || 1,
    disableBitmapText: driver.key === 'gp-d320fx' || driver.key === 'd320fax',
    /**
     * d320fax 内置字库对货币符号兼容差，TEXT_PRICE 容易整段丢失。
     * 仅恢复“货币文本位图”兜底（非全量位图文本），兼顾稳定性与 ￥ 展示。
     */
    allowCurrencyBitmapWhenDisabled: true,
  })
  if (onProgress) onProgress(16)
  const bytes = driver.protocol === 'esc'
    ? buildEscPosTemplateData(structuredTemplate)
    : buildTscTemplateData(structuredTemplate)
  if (onProgress) onProgress(18)
  await sendToPrinter(bytes, (p) => {
    if (!onProgress) return
    const u = Math.min(100, Math.max(0, Math.round(p)))
    onProgress(18 + Math.round((u / 100) * 82))
  })
  if (onProgress) onProgress(100)
  return driver
}
export function describeDiscoveredPrinter (device: PrinterCandidate) {
  return describePrinterCandidate(device)
}
export function disconnectCurrentPrinter (): Promise<void> {
  return new Promise((resolve) => {
    const type = getPrinterType()
    const connection = getBluetoothConnection()
    if (type === 'bluetooth' && connection?.deviceType === 'classic') {
      // #ifdef APP-PLUS
      if (connection.transportMode === 'native-plugin' && isNativeFastPrinterAvailable()) {
        disconnectNativeFastPrinterPlugin().catch((e: any) => {
          console.error('Disconnect native fast printer failed', e)
        }).finally(() => {
          clearPrinter()
          resolve()
        })
        return
      }
      try {
        const classic = classicBluetooth
        if (classic && classic.disConnDevice) classic.disConnDevice()
      } catch (e) {
        console.error('Disconnect classic bluetooth failed', e)
      }
      // #endif
      clearPrinter()
      resolve()
      return
    }
    clearPrinter()
    if (type === 'bluetooth' && connection?.deviceId) {
      uni.closeBLEConnection({
        deviceId: connection.deviceId,
        complete: () => resolve(),
      })
      return
    }
    resolve()
  })
}