jc-printer-sdk-ts 0.1.0 → 0.1.2

package/src/webBluetoothTransport.ts

@@ -0,0 +1,1171 @@
+import type {
+  BitmapLike,
+  BundleLike,
+  IAtBitmapDocument,
+  PaperInfo,
+  PrintCallback,
+  PrintDocument,
+  PrinterDevice,
+  PrinterInfo,
+  PrinterReadiness,
+  PrinterReadinessWarningCode,
+  PrinterSdkCallback,
+  PrinterState,
+  PrinterStatusSnapshot,
+  ScanCallback,
+} from "./types.js";
+import { JCPrintApi } from "./client.js";
+import type { PrinterTransport } from "./transport.js";
+import {
+  createConnectFrame,
+  createFrame,
+  createRowFrames,
+  fallbackProfile,
+  identifyProfile,
+  parseFrame,
+  parseModelId,
+  parseProtocolVersion,
+  rasterizeDocumentPage,
+  type NiimbotPrinterProfile,
+} from "./niimbotProtocol.js";
+
+export interface WebBluetoothPrinterTransportOptions {
+  serviceUuid?: string;
+  characteristicUuid?: string;
+  deviceNameFilter?: string;
+  scanMode?: "all" | "name";
+  optionalServices?: string[];
+  chunkSize?: number;
+  preflightStatus?: boolean;
+  statusQueryTimeoutMs?: number;
+}
+
+interface ResolvedWebBluetoothPrinterTransportOptions {
+  serviceUuid: string;
+  characteristicUuid: string;
+  deviceNameFilter: string;
+  scanMode: "all" | "name";
+  optionalServices: string[];
+  chunkSize: number;
+  preflightStatus: boolean;
+  statusQueryTimeoutMs: number;
+}
+
+export const NIIMBOT_WEB_BLUETOOTH_SERVICE_UUID = "e7810a71-73ae-499d-8c15-faa9aef0c3f2";
+export const NIIMBOT_WEB_BLUETOOTH_CHARACTERISTIC_UUID = "bef8d6c9-9c21-4c9e-b632-bd58c1009f9f";
+
+export const DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS: ResolvedWebBluetoothPrinterTransportOptions = {
+  serviceUuid: NIIMBOT_WEB_BLUETOOTH_SERVICE_UUID,
+  characteristicUuid: NIIMBOT_WEB_BLUETOOTH_CHARACTERISTIC_UUID,
+  deviceNameFilter: "",
+  scanMode: "all",
+  optionalServices: [],
+  chunkSize: 180,
+  preflightStatus: true,
+  statusQueryTimeoutMs: 700,
+};
+
+interface PrintJobContext {
+  density: number;
+  paperType: number;
+  printMode: number;
+  callback?: PrintCallback;
+}
+
+type PayloadEnvelope = {
+  kind: "jc-printer-sdk-ts/web-bluetooth";
+  sentAt: string;
+  job: {
+    density: number;
+    paperType: number;
+    printMode: number;
+  };
+  document?: PrintDocument;
+  jsonPages?: string[];
+  infoPages?: string[];
+  profile?: Record<string, unknown>;
+};
+
+interface ParsedResponse {
+  cmd: number;
+  data: number[];
+}
+
+interface PendingResponse {
+  expected: Set<number>;
+  resolve(response: ParsedResponse | null): void;
+  reject(error: Error): void;
+  timeoutId: number;
+  optional: boolean;
+}
+
+const DEFAULT_GATT_BUSY_RETRY_COUNT = 8;
+const DEFAULT_GATT_BUSY_RETRY_DELAY_MS = 25;
+const HEARTBEAT_ADVANCED_1 = 0x01;
+const HEARTBEAT_ADVANCED_2 = 0x04;
+const HEARTBEAT_RESPONSE_COMMANDS = [0xd9, 0xdd, 0xde, 0xdf];
+const INVERTED_LID_MODEL_IDS = new Set([512, 514, 513, 2304, 1792, 3584, 5120, 2560, 3840, 4352, 272, 273, 274]);
+
+function clone<T>(value: T): T {
+  if (typeof globalThis.structuredClone === "function") {
+    return globalThis.structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function normalizeUuid(uuid: string): string {
+  return uuid.trim().toLowerCase();
+}
+
+function uniqueStrings(values: Array<string | undefined>): string[] {
+  return Array.from(new Set(values.map((value) => value?.trim()).filter((value): value is string => !!value)));
+}
+
+function isGattOperationBusyError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return /GATT operation already in progress/i.test(error.message);
+}
+
+function resolveOptions(
+  options: Partial<WebBluetoothPrinterTransportOptions> = {},
+): ResolvedWebBluetoothPrinterTransportOptions {
+  const chunkSize = Number.isFinite(options.chunkSize)
+    ? Math.trunc(Number(options.chunkSize))
+    : DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.chunkSize;
+
+  return {
+    serviceUuid: options.serviceUuid ?? DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.serviceUuid,
+    characteristicUuid: options.characteristicUuid ?? DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.characteristicUuid,
+    deviceNameFilter: options.deviceNameFilter?.trim() ?? DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.deviceNameFilter,
+    scanMode: options.scanMode ?? DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.scanMode,
+    optionalServices: [...(options.optionalServices ?? DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.optionalServices)],
+    chunkSize: Math.max(20, chunkSize),
+    preflightStatus: options.preflightStatus ?? DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.preflightStatus,
+    statusQueryTimeoutMs: Math.max(
+      100,
+      Math.trunc(Number(options.statusQueryTimeoutMs ?? DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.statusQueryTimeoutMs)),
+    ),
+  };
+}
+
+function signedByte(value: number): number {
+  const byte = value & 0xff;
+  return byte > 0x7f ? byte - 0x100 : byte;
+}
+
+function signedWord(high: number, low: number): number {
+  const value = ((high & 0xff) << 8) | (low & 0xff);
+  return value > 0x7fff ? value - 0x10000 : value;
+}
+
+function defaultPrinterInfo(): PrinterInfo {
+  return {
+    deviceType: 2,
+    deviceName: "",
+    deviceVersion: "",
+    softwareVersion: "web-bluetooth",
+    deviceAddress: "",
+    deviceAddrType: 2,
+    deviceDPI: 0,
+    deviceWidth: 0,
+    manufacturer: "",
+    seriesName: "",
+    devIntName: "",
+    peripheralFlags: 0,
+    hardwareFlags: 0,
+    softwareFlags: 0,
+  };
+}
+
+function defaultPaperInfo(): PaperInfo {
+  return {
+    state: 0,
+    gapHeightPixel: 0,
+    totalHeightPixel: 0,
+    paperType: 0,
+    gapHeight: 0,
+    totalHeight: 0,
+    paperWidthPixel: 0,
+    paperWidth: 0,
+    direction: 0,
+    tailLengthPixel: 0,
+    tailLength: 0,
+  };
+}
+
+export class WebBluetoothPrinterTransport implements PrinterTransport {
+  private options: ResolvedWebBluetoothPrinterTransportOptions;
+  private sdkCallback: PrinterSdkCallback | undefined;
+  private device: BluetoothDevice | undefined;
+  private server: BluetoothRemoteGATTServer | undefined;
+  private characteristic: BluetoothRemoteGATTCharacteristic | undefined;
+  private printerName = "";
+  private printerInfo: PrinterInfo = defaultPrinterInfo();
+  private paperInfo: PaperInfo = defaultPaperInfo();
+  private printerState: PrinterState = "Disconnected";
+  private lastAddress = "";
+  private currentJob: PrintJobContext | undefined;
+  private lastPayload: PayloadEnvelope | undefined;
+  private reconnecting = false;
+  private connectedProfile: NiimbotPrinterProfile | null = null;
+  private b1HandshakeDone = false;
+  private responseQueue: ParsedResponse[] = [];
+  private pendingResponse: PendingResponse | undefined;
+  private gattOperationQueue: Promise<void> = Promise.resolve();
+
+  constructor(options: Partial<WebBluetoothPrinterTransportOptions> = {}) {
+    this.options = resolveOptions(options);
+  }
+
+  configure(options: Partial<WebBluetoothPrinterTransportOptions>): void {
+    this.options = resolveOptions({
+      ...this.options,
+      ...options,
+    });
+  }
+
+  getLastPayload(): PayloadEnvelope | undefined {
+    return this.lastPayload ? clone(this.lastPayload) : undefined;
+  }
+
+  setSdkCallback(callback?: PrinterSdkCallback): void {
+    this.sdkCallback = callback;
+    if (callback && this.printerState !== "Disconnected" && this.lastAddress) {
+      callback.onConnectSuccess(this.lastAddress, 20);
+    }
+  }
+
+  async initSdk(): Promise<boolean> {
+    return true;
+  }
+
+  async init(): Promise<boolean> {
+    return true;
+  }
+
+  async connectBluetoothPrinter(address: string): Promise<number> {
+    if (!navigator.bluetooth) {
+      throw new Error("Web Bluetooth is not available in this browser.");
+    }
+
+    const deviceFilter = this.options.deviceNameFilter?.trim() || address.trim();
+    const serviceUuid = normalizeUuid(this.options.serviceUuid);
+    const characteristicUuid = normalizeUuid(this.options.characteristicUuid);
+    if (!serviceUuid || !characteristicUuid) {
+      throw new Error("Service UUID and characteristic UUID are required for Web Bluetooth printing.");
+    }
+    const optionalServices = uniqueStrings([serviceUuid, ...(this.options.optionalServices ?? [])]);
+    const useNameFilter = this.options.scanMode === "name" && deviceFilter;
+    const requestOptions: BluetoothRequestDeviceOptions = useNameFilter
+      ? {
+          filters: [{ namePrefix: deviceFilter }],
+          optionalServices,
+        }
+      : {
+          acceptAllDevices: true,
+          optionalServices,
+        };
+
+    const device = await navigator.bluetooth.requestDevice(requestOptions);
+    const server = await this.runGattOperation(() => device.gatt!.connect());
+    if (!server) {
+      throw new Error("Failed to open the selected Bluetooth device.");
+    }
+
+    const service = await this.runGattOperation(() => server.getPrimaryService(serviceUuid));
+    const characteristic = await this.runGattOperation(() => service.getCharacteristic(characteristicUuid));
+
+    this.device = device;
+    this.server = server;
+    this.characteristic = characteristic;
+    this.lastAddress = device.name || device.id || deviceFilter || serviceUuid;
+    this.printerName = this.lastAddress;
+    this.printerState = "Connected";
+    this.printerInfo = {
+      ...defaultPrinterInfo(),
+      deviceName: this.printerName,
+      deviceAddress: this.lastAddress,
+      softwareVersion: "web-bluetooth",
+      deviceAddrType: 2,
+    };
+    this.paperInfo = defaultPaperInfo();
+
+    device.addEventListener("gattserverdisconnected", this.handleDisconnect);
+    characteristic.addEventListener("characteristicvaluechanged", this.handleCharacteristicChanged);
+    await this.runGattOperation(() => characteristic.startNotifications());
+    await this.handshakeAndIdentify();
+    this.sdkCallback?.onConnectSuccess(this.lastAddress, 20);
+    return 0;
+  }
+
+  async openPrinterByAddress(address: string): Promise<number> {
+    return this.connectBluetoothPrinter(address);
+  }
+
+  async openPrinterSync(address: string): Promise<number> {
+    return this.connectBluetoothPrinter(address);
+  }
+
+  async connectWifiPrinter(): Promise<number> {
+    throw new Error("Wi-Fi printing is not implemented in the browser transport.");
+  }
+
+  async configurationWifi(): Promise<number> {
+    return 0;
+  }
+
+  async getConfigurationWifiName(): Promise<string> {
+    return "";
+  }
+
+  async scanWifiPrinter(callback: ScanCallback): Promise<void> {
+    callback.onFinish();
+  }
+
+  async setPrinterAutoShutdownTime(): Promise<number> {
+    return 0;
+  }
+
+  async setTotalPrintQuantity(): Promise<void> {
+    return;
+  }
+
+  async setTotalQuantityOfPrints(): Promise<void> {
+    return;
+  }
+
+  async startPrintJob(
+    density: number,
+    paperType: number,
+    printMode: number,
+    callback: PrintCallback,
+  ): Promise<void> {
+    if (this.currentJob && (this.printerState === "Printing" || this.printerState === "Working")) {
+      throw new Error("A print job is already in progress on this Web Bluetooth printer.");
+    }
+
+    this.currentJob = { density, paperType, printMode, callback };
+    this.printerState = "Working";
+
+    try {
+      if (this.options.preflightStatus) {
+        const readiness = await this.evaluatePrintReadiness(this.options.statusQueryTimeoutMs, true);
+        if (!readiness.canPrint) {
+          throw new Error(`Printer is not ready to print: ${readiness.reason}`);
+        }
+      }
+
+      this.printerState = "Printing";
+      callback.onProgress(0, 0, {
+        phase: "start",
+        density,
+        paperType,
+        printMode,
+      });
+    } catch (error) {
+      this.currentJob = undefined;
+      this.printerState = this.server?.connected ? "Connected" : "Disconnected";
+      throw error;
+    }
+  }
+
+  async commitData(jsonPages: string[], infoPages: string[]): Promise<void> {
+    await this.writePayload({
+      kind: "jc-printer-sdk-ts/web-bluetooth",
+      sentAt: new Date().toISOString(),
+      job: {
+        density: this.currentJob?.density ?? 0,
+        paperType: this.currentJob?.paperType ?? 0,
+        printMode: this.currentJob?.printMode ?? 0,
+      },
+      jsonPages: clone(jsonPages),
+      infoPages: clone(infoPages),
+    });
+  }
+
+  async commitDocument(document: PrintDocument, infoPages: string[]): Promise<void> {
+    const profile = await this.resolveProfile(document);
+    this.lastPayload = {
+      kind: "jc-printer-sdk-ts/web-bluetooth",
+      sentAt: new Date().toISOString(),
+      job: {
+        density: document.job.density ?? this.currentJob?.density ?? 0,
+        paperType: document.job.paperType ?? this.currentJob?.paperType ?? 0,
+        printMode: document.job.printMode ?? this.currentJob?.printMode ?? 0,
+      },
+      document: clone(document),
+      infoPages: clone(infoPages),
+      profile: { ...profile },
+    };
+    await this.printNiimbotDocument(document, profile);
+    this.currentJob?.callback?.onProgress(document.pages.length, document.job.totalQuantity ?? 1, {
+      pages: document.pages.length,
+      profile: profile.label,
+      task: profile.task,
+      dpi: profile.dpi,
+    });
+    this.currentJob?.callback?.onBufferFree(document.pages.length, profile.printheadWidthPx);
+  }
+
+  async endJob(): Promise<boolean> {
+    return this.endPrintJob();
+  }
+
+  async endPrintJob(): Promise<boolean> {
+    this.printerState = this.server?.connected ? "Connected" : "Disconnected";
+    this.currentJob = undefined;
+    return true;
+  }
+
+  async cancelJob(): Promise<boolean> {
+    this.currentJob?.callback?.onCancelJob(true);
+    this.currentJob = undefined;
+    this.printerState = this.server?.connected ? "Connected" : "Disconnected";
+    return true;
+  }
+
+  async cancel(): Promise<void> {
+    await this.cancelJob();
+  }
+
+  async reopenPrinter(): Promise<boolean> {
+    if (this.reconnecting || !this.device?.gatt || this.server?.connected) {
+      return !!this.server?.connected;
+    }
+
+    this.reconnecting = true;
+    try {
+      const server = await this.runGattOperation(() => this.device!.gatt!.connect());
+      this.server = server;
+      const service = await this.runGattOperation(() => server.getPrimaryService(normalizeUuid(this.options.serviceUuid)));
+      const characteristic = await this.runGattOperation(() =>
+        service.getCharacteristic(normalizeUuid(this.options.characteristicUuid)),
+      );
+      this.characteristic = characteristic;
+      characteristic.addEventListener("characteristicvaluechanged", this.handleCharacteristicChanged);
+      await this.runGattOperation(() => characteristic.startNotifications());
+      await this.handshakeAndIdentify();
+      this.printerState = "Connected";
+      this.sdkCallback?.onConnectSuccess(this.lastAddress, 20);
+      return true;
+    } finally {
+      this.reconnecting = false;
+    }
+  }
+
+  async reopenPrinterSync(): Promise<boolean> {
+    return this.reopenPrinter();
+  }
+
+  async close(): Promise<void> {
+    this.currentJob?.callback?.onCancelJob(true);
+    this.currentJob = undefined;
+    this.printerState = "Disconnected";
+    if (this.device) {
+      this.device.removeEventListener("gattserverdisconnected", this.handleDisconnect);
+    }
+    if (this.characteristic) {
+      this.characteristic.removeEventListener("characteristicvaluechanged", this.handleCharacteristicChanged);
+      try {
+        await this.runGattOperation(() => this.characteristic!.stopNotifications());
+      } catch {
+        // Some browsers reject when the device is already gone.
+      }
+    }
+    if (this.server?.connected) {
+      this.server.disconnect();
+    }
+    this.server = undefined;
+    this.characteristic = undefined;
+    this.printerName = "";
+    this.lastAddress = "";
+    this.sdkCallback?.onDisConnect();
+  }
+
+  async quit(): Promise<void> {
+    await this.close();
+  }
+
+  async printBitmap(bitmap: BitmapLike, _bundle: BundleLike = {}): Promise<boolean> {
+    await this.writeJson({
+      kind: "jc-printer-sdk-ts/web-bluetooth-bitmap",
+      sentAt: new Date().toISOString(),
+      bitmap,
+    });
+    return true;
+  }
+
+  async printATBitmap(bitmap: IAtBitmapDocument, _bundle: BundleLike = {}): Promise<boolean> {
+    await this.writeJson({
+      kind: "jc-printer-sdk-ts/web-bluetooth-at-bitmap",
+      sentAt: new Date().toISOString(),
+      bitmap,
+    });
+    return true;
+  }
+
+  async getPaperInfo(): Promise<PaperInfo> {
+    return clone(this.paperInfo);
+  }
+
+  async isConnection(): Promise<number> {
+    return this.server?.connected ? 0 : -1;
+  }
+
+  async getPrintScaleMultiplier(): Promise<number> {
+    return 1;
+  }
+
+  async getPrinterName(): Promise<string> {
+    return this.printerName;
+  }
+
+  async getPrinterInfo(): Promise<PrinterInfo> {
+    return clone(this.printerInfo);
+  }
+
+  async queryPrinterStatus(timeoutMs = this.options.statusQueryTimeoutMs): Promise<PrinterStatusSnapshot> {
+    if (!this.isDeviceConnected()) {
+      return this.createLocalStatusSnapshot(false);
+    }
+
+    if (this.currentJob && (this.printerState === "Printing" || this.printerState === "Working")) {
+      return this.createLocalStatusSnapshot(true);
+    }
+
+    return this.queryPhysicalPrinterStatus(timeoutMs);
+  }
+
+  async canStartPrintJob(timeoutMs = this.options.statusQueryTimeoutMs): Promise<PrinterReadiness> {
+    return this.evaluatePrintReadiness(timeoutMs, false);
+  }
+
+  async getPrinterState(): Promise<PrinterState> {
+    return this.printerState;
+  }
+
+  async waitPrinterState(state: PrinterState, timeoutMs: number): Promise<boolean> {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+      if (this.printerState === state) {
+        return true;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return false;
+  }
+
+  async measureFontHeight(
+    text: string,
+    _x: number,
+    _y: number,
+    _width: number,
+    _height: number,
+    _rotation: number,
+    fontSize: number,
+  ): Promise<number> {
+    const lines = text.split(/\r?\n/).length;
+    return Math.max(fontSize, Math.ceil(fontSize * 1.2 * lines));
+  }
+
+  async generatePreviewImage(json: string, info: string): Promise<BitmapLike> {
+    return {
+      width: 0,
+      height: 0,
+      description: "web-bluetooth-preview",
+      meta: { json, info },
+    };
+  }
+
+  async generatePrintPreviewImage(
+    json: string,
+    widthMm: number,
+    heightMm: number,
+    orientation: number,
+  ): Promise<BitmapLike> {
+    return {
+      width: widthMm,
+      height: heightMm,
+      description: "web-bluetooth-print-preview",
+      meta: { json, orientation },
+    };
+  }
+
+  setPrinterState(state: PrinterState): void {
+    this.printerState = state;
+  }
+
+  setPrinterInfo(info: PrinterInfo): void {
+    this.printerInfo = clone(info);
+  }
+
+  setPaperInfo(info: PaperInfo): void {
+    this.paperInfo = clone(info);
+  }
+
+  setScanResults(_results: PrinterDevice[]): void {
+    return;
+  }
+
+  emitPrintProgress(pageIndex: number, quantityIndex: number, meta?: Record<string, unknown>): void {
+    this.currentJob?.callback?.onProgress(pageIndex, quantityIndex, meta ?? {});
+  }
+
+  emitPrintError(errorCode: number, printState?: number): void {
+    this.currentJob?.callback?.onError(errorCode, printState);
+  }
+
+  emitBufferFree(pageIndex: number, bufferSize: number): void {
+    this.currentJob?.callback?.onBufferFree(pageIndex, bufferSize);
+  }
+
+  emitCancel(success: boolean): void {
+    this.currentJob?.callback?.onCancelJob(success);
+  }
+
+  private isDeviceConnected(): boolean {
+    return !!this.server?.connected && !!this.characteristic;
+  }
+
+  private createLocalStatusSnapshot(connected = this.isDeviceConnected()): PrinterStatusSnapshot {
+    return {
+      connected,
+      state: this.printerState,
+      statusAvailable: false,
+    };
+  }
+
+  private async evaluatePrintReadiness(
+    timeoutMs: number,
+    ignoreCurrentJob: boolean,
+  ): Promise<PrinterReadiness> {
+    if (!this.isDeviceConnected()) {
+      return this.createReadiness("not_connected", "Printer is not connected.", false, this.createLocalStatusSnapshot(false));
+    }
+
+    if (!ignoreCurrentJob && this.currentJob && this.printerState === "Printing") {
+      return this.createReadiness(
+        "sdk_printing",
+        "A print job is already in progress on this Web Bluetooth printer.",
+        false,
+        this.createLocalStatusSnapshot(true),
+      );
+    }
+
+    if (!ignoreCurrentJob && this.currentJob && this.printerState === "Working") {
+      return this.createReadiness(
+        "printer_working",
+        "Printer is preparing another job.",
+        false,
+        this.createLocalStatusSnapshot(true),
+      );
+    }
+
+    const status = await this.queryPhysicalPrinterStatus(timeoutMs);
+    const warnings = this.collectReadinessWarnings(status);
+
+    if (!status.statusAvailable) {
+      return this.createReadiness(
+        "status_unavailable",
+        "Printer is connected, but live hardware status did not respond before the timeout.",
+        true,
+        status,
+        warnings,
+      );
+    }
+
+    if (status.lidClosed === false) {
+      return this.createReadiness("cover_open", "Printer cover is open.", false, status, warnings);
+    }
+
+    if (status.paperInserted === false) {
+      return this.createReadiness("paper_missing", "Printer has no paper inserted.", false, status, warnings);
+    }
+
+    if (status.voltageState !== undefined && status.voltageState !== 0) {
+      return this.createReadiness("voltage_error", "Printer voltage state is abnormal.", false, status, warnings);
+    }
+
+    return this.createReadiness("ready", "Printer is ready to receive a print job.", true, status, warnings);
+  }
+
+  private createReadiness(
+    code: PrinterReadiness["code"],
+    reason: string,
+    canPrint: boolean,
+    status: PrinterStatusSnapshot,
+    warnings: PrinterReadinessWarningCode[] = [],
+  ): PrinterReadiness {
+    return {
+      canPrint,
+      code,
+      reason,
+      warnings,
+      state: status.state,
+      connected: status.connected,
+      status,
+    };
+  }
+
+  private collectReadinessWarnings(status: PrinterStatusSnapshot): PrinterReadinessWarningCode[] {
+    const warnings: PrinterReadinessWarningCode[] = [];
+    if (status.paperRfidSuccess === false) {
+      warnings.push("paper_rfid_failed");
+    }
+    if (status.ribbonInserted === false) {
+      warnings.push("ribbon_missing");
+    }
+    if (status.ribbonRfidSuccess === false) {
+      warnings.push("ribbon_rfid_failed");
+    }
+    if (status.lightingErrorCode !== undefined && status.lightingErrorCode !== 0) {
+      warnings.push("lighting_error");
+    }
+    return warnings;
+  }
+
+  private async queryPhysicalPrinterStatus(timeoutMs: number): Promise<PrinterStatusSnapshot> {
+    if (!this.isDeviceConnected()) {
+      return this.createLocalStatusSnapshot(false);
+    }
+
+    const heartbeatType = this.connectedProfile?.protocolVersion !== undefined && this.connectedProfile.protocolVersion < 3
+      ? HEARTBEAT_ADVANCED_1
+      : HEARTBEAT_ADVANCED_2;
+    let response = await this.sendCommand(0xdc, [heartbeatType], HEARTBEAT_RESPONSE_COMMANDS, timeoutMs, true);
+    if (!response && heartbeatType !== HEARTBEAT_ADVANCED_1) {
+      response = await this.sendCommand(0xdc, [HEARTBEAT_ADVANCED_1], HEARTBEAT_RESPONSE_COMMANDS, timeoutMs, true);
+    }
+
+    if (!response) {
+      return this.createLocalStatusSnapshot(true);
+    }
+
+    return this.parseHeartbeatStatus(response);
+  }
+
+  private parseHeartbeatStatus(response: ParsedResponse): PrinterStatusSnapshot {
+    const status: PrinterStatusSnapshot = {
+      connected: this.isDeviceConnected(),
+      state: this.printerState,
+      statusAvailable: false,
+      responseCommand: response.cmd,
+      rawData: [...response.data],
+    };
+
+    if (response.cmd === 0xd9) {
+      this.applyAdvanced2Heartbeat(status, response.data);
+    } else if (response.cmd === 0xdd) {
+      this.applyAdvanced1Heartbeat(status, response.data);
+    }
+
+    return status;
+  }
+
+  private applyAdvanced2Heartbeat(status: PrinterStatusSnapshot, data: number[]): void {
+    if (data.length < 9) {
+      return;
+    }
+
+    status.chargeLevel = signedByte(data[2]);
+    status.temperature = signedByte(data[3]);
+    status.lidClosed = signedByte(data[4]) === 0;
+    status.paperInserted = signedByte(data[5]) === 0;
+    status.paperRfidSuccess = signedByte(data[6]) !== 0;
+    status.ribbonRfidSuccess = signedByte(data[7]) !== 0;
+    status.ribbonInserted = signedByte(data[8]) === 0;
+    if (data.length >= 11) {
+      status.wifiRssi = signedWord(data[9], data[10]);
+    }
+    if (data.length >= 13) {
+      status.lightingErrorCode = signedByte(data[12]);
+    }
+    if (data.length >= 14) {
+      status.voltageState = signedByte(data[13]);
+    }
+    status.statusAvailable = true;
+  }
+
+  private applyAdvanced1Heartbeat(status: PrinterStatusSnapshot, data: number[]): void {
+    if (data.length === 10) {
+      status.lidClosed = signedByte(data[8]) === 0;
+      status.chargeLevel = signedByte(data[9]);
+    } else if (data.length === 13) {
+      status.lidClosed = signedByte(data[9]) === 0;
+      status.chargeLevel = signedByte(data[10]);
+      status.paperInserted = signedByte(data[11]) === 0;
+      status.paperRfidSuccess = signedByte(data[12]) !== 0;
+    } else if (data.length === 19) {
+      status.lidClosed = signedByte(data[15]) === 0;
+      status.chargeLevel = signedByte(data[16]);
+      status.paperInserted = signedByte(data[17]) === 0;
+      status.paperRfidSuccess = signedByte(data[18]) !== 0;
+    } else if (data.length === 20) {
+      status.paperInserted = signedByte(data[18]) === 0;
+      status.paperRfidSuccess = signedByte(data[19]) !== 0;
+    } else {
+      return;
+    }
+
+    if (status.lidClosed !== undefined && INVERTED_LID_MODEL_IDS.has(this.printerInfo.deviceType)) {
+      status.lidClosed = !status.lidClosed;
+    }
+    status.statusAvailable = true;
+  }
+
+  private handleDisconnect = (): void => {
+    this.printerState = "Disconnected";
+    this.server = undefined;
+    this.characteristic = undefined;
+    this.sdkCallback?.onDisConnect();
+  };
+
+  private handleCharacteristicChanged = (event: Event): void => {
+    const characteristic = event.target as BluetoothRemoteGATTCharacteristic | null;
+    const value = characteristic?.value;
+    if (!value) {
+      return;
+    }
+
+    const frame = parseFrame(value);
+    if (!frame) {
+      return;
+    }
+
+    const response = { cmd: frame.cmd, data: frame.data };
+    const pending = this.pendingResponse;
+    if (pending && pending.expected.has(response.cmd)) {
+      clearTimeout(pending.timeoutId);
+      this.pendingResponse = undefined;
+      pending.resolve(response);
+      return;
+    }
+
+    this.responseQueue.push(response);
+  };
+
+  private async writePayload(payload: PayloadEnvelope): Promise<void> {
+    this.lastPayload = clone(payload);
+    await this.writeJson(payload);
+    this.currentJob?.callback?.onProgress(1, 1, {
+      bytes: JSON.stringify(payload).length,
+    });
+    this.currentJob?.callback?.onBufferFree(1, JSON.stringify(payload).length);
+  }
+
+  private async writeJson(payload: unknown): Promise<void> {
+    const characteristic = this.characteristic;
+    if (!characteristic) {
+      throw new Error("No writable Bluetooth characteristic is connected.");
+    }
+
+    const text = JSON.stringify(payload);
+    const encoded = new TextEncoder().encode(text);
+    const chunkSize = Math.max(20, this.options.chunkSize ?? 180);
+    const canWriteWithoutResponse = typeof characteristic.writeValueWithoutResponse === "function";
+
+    for (let offset = 0; offset < encoded.length; offset += chunkSize) {
+      const chunk = encoded.slice(offset, offset + chunkSize);
+      await this.writeBytes(chunk, 0, characteristic, canWriteWithoutResponse);
+    }
+  }
+
+  private async handshakeAndIdentify(): Promise<void> {
+    this.responseQueue = [];
+    this.connectedProfile = null;
+    this.b1HandshakeDone = false;
+
+    await this.writeBytes(createConnectFrame());
+    await this.waitForCommand([0xc2], 1500, true);
+
+    const status = await this.sendCommand(0xa5, [0x01], [0xb5], 1500, true);
+    const protocolVersion = status ? parseProtocolVersion(status.data) : undefined;
+    const model = await this.sendCommand(0x40, [0x08], [0x48], 1500, true);
+    const modelId = model ? parseModelId(model.data) : undefined;
+    this.connectedProfile = identifyProfile(modelId, protocolVersion);
+
+    if (this.connectedProfile?.task === "b1") {
+      await this.finishB1Handshake();
+    }
+
+    const profile = this.connectedProfile;
+    if (profile) {
+      this.printerInfo = {
+        ...this.printerInfo,
+        deviceType: profile.modelId ?? 0,
+        deviceDPI: profile.dpi,
+        deviceWidth: profile.printheadWidthPx,
+        seriesName: profile.label,
+        hardwareFlags: profile.modelId ?? 0,
+        softwareFlags: profile.protocolVersion ?? 0,
+      };
+    }
+  }
+
+  private async finishB1Handshake(): Promise<void> {
+    if (this.b1HandshakeDone) {
+      return;
+    }
+
+    for (const subCode of [0x0b, 0x0d, 0x0a, 0x07, 0x03, 0x0c, 0x09]) {
+      await this.sendCommand(0x40, [subCode], [0x40 + subCode], 1500, true);
+    }
+    await this.sendCommand(0xdc, [0x04], [0xd9], 1500, true);
+    this.b1HandshakeDone = true;
+  }
+
+  private async resolveProfile(document: PrintDocument): Promise<NiimbotPrinterProfile> {
+    const requestedTask = document.job.meta?.printTask;
+    const task = requestedTask === "b1" || requestedTask === "v4" ? requestedTask : "auto";
+    const requestedDpi = Number(document.job.meta?.dpi ?? 0);
+
+    if (task === "auto" && this.connectedProfile) {
+      return clone(this.connectedProfile);
+    }
+
+    const fallback = fallbackProfile(task, requestedDpi);
+    if (fallback.task === "b1") {
+      await this.finishB1Handshake();
+    }
+    return fallback;
+  }
+
+  private async printNiimbotDocument(document: PrintDocument, profile: NiimbotPrinterProfile): Promise<void> {
+    if (!document.pages.length) {
+      throw new Error("The print document has no pages.");
+    }
+
+    const copies = Math.max(1, Math.trunc(Number(document.job.totalQuantity ?? 1)));
+    const physicalPages = document.pages.length * copies;
+    const density = this.normalizeDensity(Number(document.job.density ?? 3), profile.task);
+    const speed = this.normalizeSpeed(Number(document.job.meta?.speed ?? 2));
+
+    this.currentJob?.callback?.onProgress(0, 0, {
+      phase: "protocol-start",
+      task: profile.task,
+      profile: profile.label,
+      dpi: profile.dpi,
+      physicalPages,
+    });
+
+    await this.sendCommand(0x21, [density], [0x31], 2000);
+    await this.sendCommand(0x23, [Number(document.job.paperType ?? 1) & 0xff], [0x33], 2000);
+
+    const startPayload =
+      profile.task === "v4"
+        ? [physicalPages >> 8, physicalPages & 0xff, 0, 0, 0, 0, 0, speed, 0]
+        : [physicalPages >> 8, physicalPages & 0xff, 0, 0, 0, 0, 0];
+    await this.sendCommand(0x01, startPayload, [0x02], 3000);
+    if (profile.task === "v4") {
+      await this.sendCommand(0xa3, [0x01], undefined, 0, true);
+      await delay(30);
+    }
+
+    let printedPage = 0;
+    for (let copyIndex = 0; copyIndex < copies; copyIndex += 1) {
+      for (let pageIndex = 0; pageIndex < document.pages.length; pageIndex += 1) {
+        const page = document.pages[pageIndex];
+        const raster = await rasterizeDocumentPage(page, document, profile);
+
+        if (profile.task === "b1") {
+          await this.sendCommand(0x03, [0x01], [0x04], 3000);
+        } else {
+          await this.sendCommand(0xa3, [0x01], undefined, 0, true);
+          await delay(30);
+        }
+
+        const sizePayload =
+          profile.task === "v4"
+            ? [
+                raster.heightPx >> 8,
+                raster.heightPx & 0xff,
+                raster.widthPx >> 8,
+                raster.widthPx & 0xff,
+                0x00,
+                0x01,
+                0x00,
+                0x00,
+                0x00,
+                0x00,
+                0x00,
+                0x00,
+                0x00,
+              ]
+            : [
+                raster.heightPx >> 8,
+                raster.heightPx & 0xff,
+                raster.widthPx >> 8,
+                raster.widthPx & 0xff,
+                0x00,
+                0x01,
+              ];
+        await this.sendCommand(0x13, sizePayload, [0x14], 3000);
+
+        await this.writeRows(createRowFrames(raster), profile.paceMs);
+        await this.sendCommand(0xe3, [0x01], [0xe4], 8000);
+        printedPage += 1;
+        this.currentJob?.callback?.onProgress(pageIndex + 1, copyIndex + 1, {
+          phase: "page-sent",
+          page: printedPage,
+          total: physicalPages,
+          widthPx: raster.widthPx,
+          heightPx: raster.heightPx,
+          stride: raster.stride,
+        });
+      }
+    }
+
+    await this.waitUntilPrinted(physicalPages);
+    await this.sendCommand(0xf3, [0x01], [0xf4], 8000);
+    if (profile.task === "v4") {
+      await this.sendCommand(0xdc, [0x01], undefined, 0, true);
+    }
+  }
+
+  private async waitUntilPrinted(pageNumber: number): Promise<void> {
+    const startedAt = Date.now();
+    this.responseQueue = this.responseQueue.filter((response) => response.cmd !== 0xb3);
+
+    while (Date.now() - startedAt < 25000) {
+      const response = await this.sendCommand(0xa3, [0x01], [0xb3], 1200, true);
+      if (response?.data && response.data.length >= 2) {
+        const page = (response.data[0] << 8) | response.data[1];
+        if (page >= pageNumber) {
+          return;
+        }
+      }
+      await delay(400);
+    }
+  }
+
+  private async writeRows(frames: Uint8Array[], paceMs: number): Promise<void> {
+    for (const frame of frames) {
+      await this.writeBytes(frame, paceMs);
+    }
+  }
+
+  private async sendCommand(
+    cmd: number,
+    data: number[] | Uint8Array,
+    expected?: number[],
+    timeoutMs = 2000,
+    optional = false,
+  ): Promise<ParsedResponse | null> {
+    await this.writeBytes(createFrame(cmd, data));
+    return expected?.length ? this.waitForCommand(expected, timeoutMs, optional) : null;
+  }
+
+  private async waitForCommand(
+    expected: number[],
+    timeoutMs: number,
+    optional: boolean,
+  ): Promise<ParsedResponse | null> {
+    const expectedSet = new Set(expected.map((cmd) => cmd & 0xff));
+    const queuedIndex = this.responseQueue.findIndex((response) => expectedSet.has(response.cmd));
+    if (queuedIndex >= 0) {
+      const [queued] = this.responseQueue.splice(queuedIndex, 1);
+      return queued;
+    }
+
+    return new Promise((resolve, reject) => {
+      this.pendingResponse = {
+        expected: expectedSet,
+        resolve,
+        reject,
+        optional,
+        timeoutId: window.setTimeout(() => {
+          this.pendingResponse = undefined;
+          if (optional) {
+            resolve(null);
+          } else {
+            reject(new Error(`Timed out waiting for printer response 0x${expected[0].toString(16)}.`));
+          }
+        }, timeoutMs),
+      };
+    });
+  }
+
+  private async writeBytes(
+    bytes: Uint8Array,
+    paceMs = 0,
+    characteristic = this.characteristic,
+    canWriteWithoutResponse = !!characteristic && typeof characteristic.writeValueWithoutResponse === "function",
+  ): Promise<void> {
+    if (!characteristic) {
+      throw new Error("No writable Bluetooth characteristic is connected.");
+    }
+
+    const payload = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(payload).set(bytes);
+
+    await this.runGattOperation(async () => {
+      if (canWriteWithoutResponse) {
+        await characteristic.writeValueWithoutResponse(payload);
+      } else {
+        await characteristic.writeValue(payload);
+      }
+    });
+
+    if (paceMs > 0) {
+      await delay(paceMs);
+    }
+  }
+
+  private async runGattOperation<T>(operation: () => Promise<T>): Promise<T> {
+    const run = async (): Promise<T> => {
+      let lastError: unknown;
+
+      for (let attempt = 0; attempt <= DEFAULT_GATT_BUSY_RETRY_COUNT; attempt += 1) {
+        try {
+          return await operation();
+        } catch (error) {
+          lastError = error;
+          if (!isGattOperationBusyError(error) || attempt >= DEFAULT_GATT_BUSY_RETRY_COUNT) {
+            throw error;
+          }
+
+          await delay(DEFAULT_GATT_BUSY_RETRY_DELAY_MS * (attempt + 1));
+        }
+      }
+
+      throw lastError;
+    };
+
+    const queued = this.gattOperationQueue.then(run, run);
+    this.gattOperationQueue = queued.then(
+      () => undefined,
+      () => undefined,
+    );
+    return queued;
+  }
+
+  private normalizeDensity(value: number, task: "v4" | "b1"): number {
+    if (task === "b1") {
+      return Math.max(1, Math.min(5, Math.round(value)));
+    }
+    return Math.max(1, Math.min(14, Math.round(value)));
+  }
+
+  private normalizeSpeed(value: number): number {
+    return Math.max(0, Math.min(4, Math.round(value)));
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => window.setTimeout(resolve, ms));
+}
+
+export function createWebBluetoothPrinterTransport(
+  options: Partial<WebBluetoothPrinterTransportOptions> = {},
+): WebBluetoothPrinterTransport {
+  return new WebBluetoothPrinterTransport(options);
+}
+
+export function createWebBluetoothPrinterClient(
+  options: Partial<WebBluetoothPrinterTransportOptions> = {},
+  sdkCallback?: PrinterSdkCallback,
+): JCPrintApi {
+  return new JCPrintApi(createWebBluetoothPrinterTransport(options), sdkCallback);
+}