libniimai 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # libniimai
 
-Print from the browser on four families of thermal printers: **NIIMBOT**, **TSPL label printers**, **ESC/POS mini printers** and **cat printers**. One API connects, detects the printer and prints any canvas, over Web Bluetooth or Web Serial. No server, no drivers, no app.
+Print from the browser on four families of thermal printers: **NIIMBOT**, **TSPL label printers**, **ESC/POS receipt printers** and **cat printers**. One API connects, detects the printer and prints any canvas, over Web Bluetooth or Web Serial. No server, no drivers, no app.
 
 libniimai powers [niimai](https://niimai.app), the label designer.
 
@@ -9,11 +9,11 @@ libniimai powers [niimai](https://niimai.app), the label designer.
 | Family | Paper | Print width | Connection | Models |
 |---|---|---|---|---|
 | **NIIMBOT** | Labels with gaps, black mark, continuous, transparent | 12 mm and up, by model | Bluetooth, USB | D11, D110, D101, B1, B18, B21, B3S and more |
-| **TSPL label printers** | Labels with gaps, black mark, continuous | Up to 80 mm | Bluetooth | QR380A (sold as CC390) |
-| **ESC/POS mini printers** | 58 mm continuous | 48 mm | Bluetooth | MP583, MPT-II, PT-210, RPP02, ZJ-58 and more |
-| **Cat printers** | 58 mm continuous | 48 mm | Bluetooth | GB01, GB02, GB03, MX05, MX06, MX10 and more |
+| **TSPL label printers** | Labels with gaps, black mark, continuous | Up to 80 mm | Bluetooth | QR380A (sold as CC390), Gprinter GP-M322 |
+| **ESC/POS receipt printers** | 58 or 80 mm, continuous or stickers with gaps | 48 or 72 mm | Bluetooth | MP583, MPT-II, Xprinter XP-58IIL, PT-210, RPP02, MPT-3, RPP300 and more |
+| **Cat printers** | 58 mm continuous, stickers with gaps | 48 mm | Bluetooth | GB01, GB02, GB03, MX05, MX06, MX10 and more |
 
-The family is found from the device the user picks: by its Bluetooth name, then checked against the services it offers. Every family gets the same treatment:
+The family is found from the device the user picks: by its Bluetooth name in `PRINTER_CATALOG`, then checked against the services it offers. A name that matches no family is treated as a NIIMBOT, unless a type from `PRINTER_TYPES` is set for unrecognised printers. Every family gets the same treatment:
 
 - **Detection**: the right client and settings, picked for you.
 - **Page handling**: each page is cropped to the head, rotated where the printer needs it, and encoded in the printer's own format.
@@ -29,13 +29,13 @@ Label printers in many widths, from 12 mm pocket models up. Protocol by [niimblu
 
 Desktop label printers up to 80 mm wide that take TSC's TSPL label language. The printer finds each label's edge itself, and confirms each job. When a job goes unconfirmed, libniimai asks the printer why, and an open cover, jam or empty roll comes back as an error. Common 2- to 3-inch label sizes are listed in `profile.sizes`, 3 × 4 inch included. These printers cannot sense the roll, so `status.label.barcode` gives a stable key to remember its size per printer.
 
-### ESC/POS mini printers
+### ESC/POS receipt printers
 
-Pocket receipt printers on 58 mm paper with a 384-dot head. Pages print as one raster image at any length, for receipts, lists and long labels.
+Receipt printers on 58 mm paper with a 384-dot head, and 80 mm models with a 576-dot head. Pages print as one raster image at any length, for receipts, lists and long labels. `feed(mm)` lines up the paper; these printers have no reverse feed. For sticker rolls, `gapMm` keeps each print on its sticker.
 
 ### Cat printers
 
-The small "cat" printers sold under many names, on 58 mm paper with a 384-dot head. Five darkness levels, flow control so long prints never overrun the printer, and the newer GB03 and MX-series variants handled per model.
+The small "cat" printers sold under many names, on 58 mm paper with a 384-dot head. Five darkness levels, flow control so long prints never overrun the printer, and the newer GB03 and MX-series variants handled per model. `feed(mm)` moves the paper either way to line it up, and `gapMm` keeps prints on sticker rolls.
 
 Each model is marked by how well it is tested in `TSPL_MODELS`, `ESCPOS_MODELS` and `CAT_MODELS`; see also [thermal-printers.md](https://github.com/theanam/niimai/blob/main/docs/thermal-printers.md).
 
@@ -95,7 +95,8 @@ Returns a `PrinterService`, which owns one printer connection.
 | `print(source, options)` | Prints a canvas, or a `{ count, page(i) }` source for a batch of different labels. |
 | `getStatus()` | The current `PrinterStatus`. |
 | `subscribe(fn)` | Calls `fn` on every status change. Returns a function that unsubscribes. |
-| `setManualProfile(id)` | Picks a printer type from `MANUAL_PROFILES` for NIIMBOT models niimbluelib does not know yet. |
+| `feed(mm)` | Moves the paper by `mm` to line it up, back into the printer when negative. For printers that cannot sense the paper, where `status.canFeed` is true. |
+| `setManualProfile(id)` | Picks a printer type for a printer that is not recognised: a NIIMBOT model from `MANUAL_PROFILES`, or a receipt, label or cat printer from `PRINTER_TYPES`. With one of those, the Bluetooth chooser lists every device. |
 
 **Print options**
 
@@ -105,6 +106,7 @@ Returns a `PrinterService`, which owns one printer connection.
 | `copies` | Copies of each page. |
 | `labelType` | Paper type, from `PAPER_TYPES`: 1 labels with gaps, 2 black mark, 3 continuous. |
 | `offset` | Nudges the print, in mm: `{ x, y }`. |
+| `gapMm` | Stickers with gaps on printers that cannot sense them (`status.canFeed`): each label is followed by exactly this much feed, in place of the tear-off feed. |
 
 **`PrinterStatus`**
 
@@ -116,6 +118,7 @@ Returns a `PrinterService`, which owns one printer connection.
 | `label` | The loaded roll, where the printer reports one. |
 | `battery` | Battery level, where the printer reports one. |
 | `progress` | `{ page, total, sending }`; `sending` is 0–100 for the page going over the link. |
+| `canFeed` | True when `feed(mm)` can move the paper: ESC/POS and cat printers. |
 
 ### Your own clients
 
@@ -154,8 +157,8 @@ Every piece is exported, for building your own flow:
 
 - `createClient(kind)` returns a raw client for one connection.
 - `TsplPrinterClient`, `EscPosPrinterClient` and `CatPrinterClient` take any `ThermalTransport`, so they also work over other links.
-- `tsplJob`, `escposJob` and `catJob` build the bytes for one page.
-- `tsplModelFor`, `escposModelFor` and `catModelFor` match a Bluetooth name to a known model.
+- `tsplJob`, `escposJob` and `catJob` build the bytes for one page; `escposFeed` and `catFeed` the bytes that move the paper.
+- `identifyPrinter(name)` matches a Bluetooth name to a known model across every family, from `PRINTER_CATALOG`; `tsplModelFor`, `escposModelFor` and `catModelFor` look in one family.
 - `unsupportedReason(kind)` says in a few words why a connection type cannot be used in the current browser.
 
 ## Browsers

package/dist/ble.d.ts

@@ -4,8 +4,8 @@ type Lib = typeof import('@mmote/niimbluelib');
 export declare const CANDIDATE_SERVICES: string[];
 /** Name prefixes of NIIMBOT printers; the chooser lists only these and known cat printers. */
 export declare const NAME_PREFIXES: string[];
-/** Opens the browser's printer chooser. */
-export declare function requestPrinter(extraPrefixes?: string[]): Promise<BluetoothDevice>;
+/** Opens the browser's printer chooser. `all` lists every device, for printers whose names niimai does not know. */
+export declare function requestPrinter(extraPrefixes?: string[], all?: boolean): Promise<BluetoothDevice>;
 interface CharLike {
     uuid: string;
     properties: {

package/dist/bluetooth.d.ts

@@ -3,16 +3,20 @@ type Lib = typeof import('@mmote/niimbluelib');
 /**
  * The Bluetooth printer behind the Connect button. One chooser lists NIIMBOT
  * printers and the known extra thermal printers. A known cat printer offering
- * AE30 gets the cat client, a known ESC/POS printer offering 18F0 the ESC/POS
- * client, a known TSPL label printer offering 18F0 the TSPL client, and
- * everything else the NIIMBOT client exactly as before. Known names never
- * overlap, so each printer matches one client at most.
+ * AE30 gets the cat client; a known ESC/POS printer the ESC/POS client, over
+ * 18F0, the shared E781 service (as Xprinters use), or any serial service
+ * with a writable characteristic; a known TSPL label printer offering 18F0
+ * the TSPL client; and everything else the NIIMBOT client exactly as before.
+ * Known names never overlap, so each printer matches one client at most.
  */
 export declare class BluetoothPrinter implements ClientLike {
     private lib;
     private inner;
     constructor(lib: () => Promise<Lib>);
     private get client();
+    /** The kind of printer to treat an unrecognised one as; null leaves it to NIIMBOT. */
+    private fallback;
+    unrecognisedAs(typeId: string | null): void;
     connect(): Promise<{
         deviceName?: string;
     }>;
@@ -53,5 +57,7 @@ export declare class BluetoothPrinter implements ClientLike {
     };
     get encodePage(): ((canvas: HTMLCanvasElement) => unknown) | undefined;
     get rollKey(): (() => string) | undefined;
+    get feedPaper(): ((dots: number) => Promise<void>) | undefined;
+    get feedsBack(): boolean | undefined;
 }
 export {};

package/dist/cat.d.ts

@@ -36,12 +36,19 @@ export declare const FLOW_PAUSE: number[];
 export declare const FLOW_RESUME: number[];
 /** Rows for a cat printer: leftmost dot in the lowest bit. */
 export declare const encodeRows: (data: ArrayLike<number>, width: number, height: number) => Uint8Array[];
-/** Everything sent for one job: setup, the rows for each copy, then feed and finish. */
-export declare function printJob(rows: Uint8Array[], { density, copies, model }: {
+/**
+ * Everything sent for one job: setup, the rows for each copy, then feed and
+ * finish. With `gapDots`, for labels with gaps, every label is followed by
+ * exactly that feed, so the next print starts on the next label.
+ */
+export declare function printJob(rows: Uint8Array[], { density, copies, model, gapDots }: {
     density: number;
     copies: number;
     model: CatModel | null;
+    gapDots?: number;
 }): Uint8Array;
+/** Moves the paper by `dots`, back when negative. Models that mishandle the feed command get blank rows. */
+export declare function catFeed(dots: number, model: CatModel | null): Uint8Array;
 /** A cat printer: the shared thermal client with cat packets and flow control. */
 export declare class CatPrinterClient extends ThermalPrinterClient {
     readonly model: CatModel | null;
@@ -49,5 +56,8 @@ export declare class CatPrinterClient extends ThermalPrinterClient {
     protected readonly modelName: string;
     constructor(transport: ThermalTransport, model: CatModel | null, pace?: Pace);
     protected encodeRows(data: ArrayLike<number>, width: number, height: number): Uint8Array<ArrayBufferLike>[];
-    protected job(rows: Uint8Array[], density: number, copies: number): Uint8Array<ArrayBufferLike>;
+    protected job(rows: Uint8Array[], density: number, copies: number, _labelType: number, gapDots?: number): Uint8Array<ArrayBufferLike>;
+    readonly feedsBack = true;
+    /** These printers cannot sense the paper, so the user lines it up by hand. */
+    feedPaper(dots: number): Promise<void>;
 }

package/dist/catalog.d.ts

@@ -0,0 +1,17 @@
+import { type ThermalModel } from './thermal.js';
+export type PrinterFamily = 'escpos' | 'tspl' | 'cat';
+export interface CatalogEntry {
+    family: PrinterFamily;
+    model: ThermalModel;
+}
+export declare const PRINTER_CATALOG: CatalogEntry[];
+/** The known printer a Bluetooth name belongs to, longest prefix first across every family. */
+export declare function identifyPrinter(name: string | undefined): CatalogEntry | null;
+/** A kind of printer to pick for one niimai does not recognise. */
+export interface PrinterType extends CatalogEntry {
+    id: string;
+    name: string;
+}
+/** The kinds of printer an unrecognised one can be set to, alongside NIIMBOT's MANUAL_PROFILES. */
+export declare const PRINTER_TYPES: PrinterType[];
+export declare const findPrinterType: (id: string | null | undefined) => PrinterType | null;

package/dist/client.d.ts

@@ -56,6 +56,16 @@ export interface ClientLike {
      * size the user sets, per printer. NIIMBOT printers read their rolls instead.
      */
     rollKey?(): string;
+    /** Printers that cannot sense the paper: moves it by `dots`, back into the printer when negative. */
+    feedPaper?(dots: number): Promise<void>;
+    /** feedPaper can also move the paper back. */
+    feedsBack?: boolean;
+    /**
+     * Bluetooth: the kind of printer to treat one with an unknown name as, set
+     * before connecting: an id from PRINTER_TYPES, or a NIIMBOT profile id the
+     * client ignores.
+     */
+    unrecognisedAs?(typeId: string | null): void;
 }
 export type ConnectionKind = 'bluetooth' | 'serial' | 'demo';
 export declare const supportsBluetooth: () => boolean;

package/dist/escpos.d.ts

@@ -6,17 +6,35 @@
 import { ThermalPrinterClient, type Pace, type ThermalModel, type ThermalTransport } from './thermal.js';
 export declare const ESCPOS_SERVICE = "000018f0-0000-1000-8000-00805f9b34fb";
 export declare const ESCPOS_WRITE = "00002af1-0000-1000-8000-00805f9b34fb";
+/** The serial service many budget printers offer, Xprinter among them; NIIMBOT printers use it too. */
+export declare const ESCPOS_ALT_SERVICE = "e7810a71-73ae-499d-8c15-faa9aef0c3f2";
+export declare const ESCPOS_ALT_WRITE = "bef8d6c9-9c21-4c9e-b632-bd58c1009f9f";
 /**
- * Models known to take ESC/POS raster images over 18F0. "tested": printed
- * with niimai on real hardware. "medium": the same chipset and service are
- * widely reported, untested here.
+ * Models known to take ESC/POS raster images, by Bluetooth name. "tested":
+ * printed with niimai on real hardware. "high": supported by several
+ * open-source printer projects. "medium": the name is reported by one or two
+ * of them, untested here. Names from receipt-printer projects such as
+ * WebBluetoothReceiptPrinter and bitbank2/Thermal_Printer; see
+ * docs/thermal-printers.md for sources. Most of these printers share one
+ * Bluetooth module, so its services tell nothing apart: the name decides.
  */
 export declare const ESCPOS_MODELS: ThermalModel[];
 export declare const escposModelFor: (name: string | undefined) => ThermalModel | null;
-/** Rows for an ESC/POS printer: leftmost dot in the highest bit. */
-export declare const encodeRows: (data: ArrayLike<number>, width: number, height: number) => Uint8Array[];
-/** ESC @, then each copy as GS v 0 bands with a gap between, then a feed. */
-export declare function escposJob(rows: Uint8Array[], copies: number): Uint8Array;
+/** Rows for an ESC/POS printer: leftmost dot in the highest bit, centred on a head `head` dots wide. */
+export declare const encodeRows: (data: ArrayLike<number>, width: number, height: number, head?: number) => Uint8Array[];
+/**
+ * ESC @, then each copy as GS v 0 bands with a gap between, then a feed past
+ * the tear bar. With `gapDots`, for labels with gaps, every label is followed
+ * by exactly that feed, so the next print starts on the next label.
+ */
+export declare function escposJob(rows: Uint8Array[], copies: number, gapDots?: number): Uint8Array;
+/**
+ * Moves the paper forward by `dots`: line feeds with the line spacing set to
+ * the distance (ESC 3 n, LF), then the default spacing back (ESC 2). The
+ * MP583 ignores ESC J, the usual dot feed, but takes line feeds. These
+ * printers have no reverse feed.
+ */
+export declare function escposFeed(dots: number): Uint8Array;
 /**
  * An ESC/POS printer: the shared thermal client with raster commands. These
  * printers send no flow control, so writes are paced. Heat settings vary by
@@ -26,7 +44,10 @@ export declare class EscPosPrinterClient extends ThermalPrinterClient {
     readonly model: ThermalModel | null;
     protected readonly densityLevels = 1;
     protected readonly modelName: string;
+    protected readonly headDots: number;
     constructor(transport: ThermalTransport, model: ThermalModel | null, pace?: Pace);
     protected encodeRows(data: ArrayLike<number>, width: number, height: number): Uint8Array<ArrayBufferLike>[];
-    protected job(rows: Uint8Array[], _density: number, copies: number): Uint8Array<ArrayBufferLike>;
+    protected job(rows: Uint8Array[], _density: number, copies: number, _labelType: number, gapDots?: number): Uint8Array<ArrayBufferLike>;
+    /** These printers cannot sense the paper, so the user lines it up by hand. */
+    feedPaper(dots: number): Promise<void>;
 }

package/dist/index.d.ts

@@ -25,12 +25,14 @@ export { correctTask, findManualProfile, inkOutsideHead, MANUAL_PROFILES, printh
 export type { LabelSize, PrintDirection, PrinterProfile } from './profiles.js';
 export { effectivePaper, labelTypeOf, PAPER_TYPES, paperFromLabelType, paperName } from './paper.js';
 export type { PaperType } from './paper.js';
+export { findPrinterType, identifyPrinter, PRINTER_CATALOG, PRINTER_TYPES } from './catalog.js';
+export type { CatalogEntry, PrinterFamily, PrinterType } from './catalog.js';
 export { BluetoothPrinter } from './bluetooth.js';
 export { describeBleError } from './ble.js';
 export { DEMO_META, MockClient } from './mock.js';
 export { modelFor, THERMAL_DEFAULT_SIZE, THERMAL_HEAD_DOTS, THERMAL_HEAD_MM, THERMAL_SIZES, ThermalPrinterClient, webTransport } from './thermal.js';
 export type { Confidence, Pace, ThermalModel, ThermalTransport } from './thermal.js';
-export { CAT_MODELS, CAT_UNSUPPORTED, CatPrinterClient, catModelFor, printJob as catJob } from './cat.js';
+export { CAT_MODELS, CAT_UNSUPPORTED, CatPrinterClient, catFeed, catModelFor, printJob as catJob } from './cat.js';
 export type { CatModel } from './cat.js';
-export { ESCPOS_MODELS, EscPosPrinterClient, escposJob, escposModelFor } from './escpos.js';
+export { ESCPOS_MODELS, EscPosPrinterClient, escposFeed, escposJob, escposModelFor } from './escpos.js';
 export { TSPL_MODELS, TSPL_SIZES, TsplPrinterClient, tsplJob, tsplModelFor } from './tspl.js';