@kreiseck/kasseneck-api 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,78 @@ Was vor 0.7.0 geschah, steht in der Commit-Historie (`git log`); ab hier wird
 es hier geführt. Ein Eintrag nennt die Änderung **und ihren Grund** —
 nur der Grund überlebt den nächsten Umbau.
 
+## 0.11.0
+
+### Die QR-Modulgröße wird gerechnet, nicht gesetzt — samt Notausgang und Modell 1
+
+**Anlass:** Am echten Beleg fehlte der QR-Code, die Probe im Drucker-Wizard
+druckte ihn. Der native QR-Befehl bekommt eine Modulgröße in Druckpunkten mit
+und rechnet nicht nach, ob das Symbol samt Ruhezone auf die Rolle geht. Ein
+Beleg-QR mit realer RKSV-Nutzlast hat 57 Module, mit Ruhezone also 65; bei
+sechs Punkten je Modul sind das 390 Druckpunkte, und ein 58-mm-Kopf hat 384.
+Zu breit heißt bei den meisten Geräten nicht „abgeschnitten", sondern **gar
+kein QR**. Der Befund stammt aus dem Flutter-Zwilling `kasseneck_api` (dort
+6.9.0), der fest mit sechs Punkten druckte; dieses Paket druckt seit jeher mit
+vier und war davon nicht betroffen. Die Regel ist trotzdem dieselbe — sie
+deckelt auch eine bewusst gewählte größere Modulgröße gegen den Papierrand ab.
+
+- **Neu `…/printing`: die Rechenregel, rein und ohne Drucker.**
+  `qrModulAnzahl(nutzlast)` gibt die Modulanzahl bei Fehlerkorrektur **M**
+  (konservativ: der native Befehl druckt mit L, das braucht nie mehr Module);
+  `qrGroesseBerechnen({ papierbreitePunkte, moduleAnzahl, groesse })` und
+  `qrGroesseFuer({ nutzlast, papierbreitePunkte, groesse })` geben ein
+  `QrGroesse` mit `punkte` (`null` = passt nicht), `module`, `breitePunkte`,
+  `unterMindestmass` und `passt`. Dazu `QrModulGroesse`, `QR_MODUL_DECKEL`,
+  `QR_RUHEZONE_MODULE` (4), `QR_MINDEST_PUNKTE` (4), `QR_AUSNAHME_PUNKTE` (3),
+  `QR_HOECHST_PUNKTE` (8) und `QR_DRUCK_PUNKTE` (58 mm = 384, 80 mm = 576 —
+  die echte Kopfbreite, nicht die Spaltenbreite 372/558).
+- **`escPosQrCode` rechnet, wenn keine feste `size` mitkommt.** `groesse` ist
+  ein **Deckel**, keine Vorgabe: gedruckt wird die größte Größe, die noch
+  passt, höchstens aber der Deckel. `auto` deckelt beim Bestandswert dieses
+  Pakets (4), `klein` 4, `mittel` 6, `gross` 8. **Ohne ausdrückliche Wahl
+  ändert sich kein Byte** — nur dort, wo heute gar nichts herauskommt, rechnet
+  die Regel herunter. (Im Flutter-Zwilling deckelt `auto` bei 6, weil dort 6
+  der Bestandswert ist; die Regel ist dieselbe, der Bestand nicht.)
+- **`EscPosDocument.qrFehler` / `.qrAusweich`.** `qrFehler` heißt „Beleg ohne
+  QR" — das Symbol passt auch mit der Ausnahmegröße nicht, und ein Befehl, von
+  dem man weiß, dass er nichts druckt, täuscht nur einen Ausdruck vor.
+  `qrAusweich` heißt „gedruckt, aber nicht auf dem eingestellten Weg" — unter
+  der Mindestgröße oder als Bild. Das eine gehört dem Kunden gesagt, das
+  andere dem Chef. `escPosReset` räumt beide weg.
+- **Neu `…/receipt`: `escPosLayoutErgebnis`** gibt `{ bytes, qrFehler,
+  qrAusweich }`; `escPosLayoutBytes` bleibt unverändert und gibt weiter nur
+  die Bytes. Neue Optionen `qrGroesse`, `qrModus` (`QrPrintMode`) und
+  `qrMatrix`.
+- **Der Notausgang.** Passt das Symbol nativ nicht aufs Papier und ist ein
+  `qrMatrix` mitgegeben, geht der QR als Rasterbild hinaus (`GS v 0`) statt
+  gar nicht — ein Pflichtbeleg ohne QR ist der schlechteste aller Ausgänge.
+  Das Raster kommt vom Aufrufer: dieses Paket rechnet keine QR-Codes und
+  verarbeitet keine Bilder. Dafür neu `escPosQrRaster`, `qrRasterPunkte` und
+  der Typ `QrMatrix`.
+- **Modell 1.** `qrCodeBytes(..., { modell1: true })` bzw. `qrModus:
+  'nativeModel1'` stellt den Wahlbefehl `GS ( k 04 00 31 41 31 00` voran. Für
+  günstige Drucker, die nur diesen älteren Symboltyp beherrschen; belegt ist
+  eines, das bei Modell 2 unter dem Code eine „0" ausgibt — das Parameterbyte
+  `0x30` des Druckbefehls, das es nicht als Befehl erkennt. Ohne ausdrückliche
+  Wahl geht **gar kein** Modellbefehl hinaus, wie bisher.
+- **Derselbe Fehler im ePOS-Weg — und dort ist er der akute.** `eposPrintXml`
+  setzte `<symbol … width="6">` fest, unabhängig von der Papierbreite: 57
+  Module plus Ruhezone sind bei sechs Punkten 390 Druckpunkte, ein 58-mm-Kopf
+  hat 384, und der Epson lässt ein zu breites Symbol weg. **Genau daran fehlte
+  am echten Beleg der QR.** Jetzt gilt dieselbe Regel — Untergrenze 4,
+  Ausnahme 3 mit Meldung, darunter kein `<symbol>`. Der Bestandswert dieses
+  Wegs ist 6, deshalb ist die Vorgabe hier der Deckel `mittel`; ohne
+  ausdrückliche Wahl ändert sich nur dort etwas, wo heute gar nichts
+  herauskommt. Neu `eposPrintXmlErgebnis` (`{ xml, qrFehler, qrAusweich }`) und
+  die Optionen `qrGroesse` an `eposPrintXml` und `eposDirectPrint`; `qrBreite`
+  bleibt, ist jetzt aber ausdrücklich die **feste** Größe und schaltet die
+  Rechnung ab.
+- **Bestandsschutz als Golden-Test.** Zwei feste SHA-256 über den gesamten
+  Bytestrom eines Belegs (58 und 80 mm) und zwei weitere über das vollständige
+  ePOS-XML halten fest, dass sich ohne Wahl kein Byte ändert. Dazu prüft `test/paket-inhalt.test.ts`, dass die Dateiliste des
+  Pakets eine Positivliste bleibt und im mitgelieferten `fixtures/` nichts
+  Örtliches liegt.
+
 ## 0.10.0
 
 ### Die Antwortcodeliste von hobex — jeder Code eingeordnet, jeder Ausgang mit Grund
@@ -12,7 +84,8 @@ nur der Grund überlebt den nächsten Umbau.
 geschickt. Drei der Codes kamen seit dem 28.08.2026 im Betrieb vor (`100004`,
 `100005`, `100015`) und waren bis jetzt ungedeutet. Jede Zahlung damit lief in
 die Klaerung und endete erst ueber die Zwei-9027-Regel. Zwilling:
-`kasseneck_api` 6.9.0, Begruendungen dort in `doc/kartenzahlung.md`.
+`kasseneck_api` 6.10.0 (6.9.0 war inzwischen vergeben), Begruendungen dort in
+`doc/kartenzahlung.md`.
 
 - **`HPS_CODES`** fuehrt alle 31 Codes der Liste zusammen mit den gemessenen:
   Code, hobex-Titel, Bedeutung, Wirkung (`effect`), Grund (`reason`) und

package/README.md

@@ -344,6 +344,47 @@ app.post('/kasseneck-webhook', express.raw({ type: '*/*' }), async (req, res) =>
 
 So zieht sich niemand den React-Adapter in ein Node-Programm.
 
+## Der QR-Code passt aufs Papier
+
+Der native QR-Befehl bekommt eine Modulgröße in Druckpunkten mit und rechnet
+selbst nicht nach, ob das Symbol samt Ruhezone auf die Rolle geht. Zu breit
+heißt bei den meisten Bondruckern nicht „abgeschnitten", sondern **gar kein
+QR** — auf einem Pflichtbeleg der schlechteste aller Ausgänge. Deshalb rechnet
+dieses Paket die Größe, statt sie zu setzen:
+
+```ts
+import { qrGroesseFuer, QR_DRUCK_PUNKTE } from '@kreiseck/kasseneck-api/printing';
+
+const mass = qrGroesseFuer({ nutzlast: beleg.qr, papierbreitePunkte: QR_DRUCK_PUNKTE.mm58 });
+// mass.punkte: Punkte je Modul, null = passt auch mit der Ausnahmegröße nicht
+// mass.unterMindestmass: gedruckt, aber unter 4 Punkten je Modul
+```
+
+Am Belegweg passiert das von selbst. `qrGroesse` ist ein **Deckel**, keine
+Vorgabe: gedruckt wird die größte Größe, die noch passt, höchstens aber der
+Deckel. `auto` (Vorgabe) deckelt beim Bestandswert 4 — ohne ausdrückliche Wahl
+ändert sich also kein Byte.
+
+```ts
+import { escPosLayoutErgebnis } from '@kreiseck/kasseneck-api/receipt';
+
+const { bytes, qrFehler, qrAusweich } = escPosLayoutErgebnis(layout, {
+  qrGroesse: 'gross',        // 'auto' | 'klein' | 'mittel' | 'gross'
+  qrModus: 'nativeModel1',   // ältere Drucker, die nur Modell 1 können
+  qrMatrix: rasterFuer,      // Notausgang: der QR als Bild statt gar nicht
+});
+```
+
+Der Epson-Weg (`eposPrintXml` / `eposDirectPrint`) rechnet genauso;
+`eposPrintXmlErgebnis` gibt dort `{ xml, qrFehler, qrAusweich }`. Sein
+Bestandswert ist 6, deshalb ist die Vorgabe dort der Deckel `mittel`.
+
+`qrFehler` heißt „Beleg ohne QR" — das gehört dem Kunden gesagt. `qrAusweich`
+heißt „gedruckt, aber der eingestellte Weg taugt für dieses Gerät nicht" — das
+gehört dem Chef gesagt. Den Bildweg fährt das Paket nur mit einem `qrMatrix`,
+das die Nutzlast in ein fertiges Raster übersetzt: hier wird bewusst weder ein
+QR gerechnet noch ein Bild verarbeitet.
+
 ## Hobex HPS über Kasseneck Connect
 
 Ein Browser hat weiterhin keine rohen TCP-Sockets — ein **direkter**

package/dist/cjs/printing/escpos.d.ts

@@ -27,6 +27,7 @@
  * Nicht enthalten (bewusst): Rasterbilder/Logos, Capability-Profile einzelner
  * Druckermodelle, Kassenlade, 1D-Barcodes.
  */
+import { type QrModulGroesse } from './qr-groesse.js';
 /** Papierbreite der Bonrolle. */
 export type PosPaperSize = 'mm58' | 'mm80';
 /** Ausrichtung einer Textzeile bzw. innerhalb einer Spalte. */
@@ -43,6 +44,14 @@ export type PosTextSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
 export type QrSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
 /** Fehlerkorrekturstufe des QR-Codes. */
 export type QrCorrection = 'L' | 'M' | 'Q' | 'H';
+/**
+ * Fertig gerechnetes QR-Raster, quadratisch, `true` = schwarzes Modul —
+ * **ohne** Ruhezone, die setzt der Drucker-Weg selbst.
+ *
+ * Dieses Paket rastert bewusst nicht selbst (keine Bildverarbeitung, siehe
+ * Kopf dieser Datei); wer den Bildweg braucht, bringt sein eigenes Raster mit.
+ */
+export type QrMatrix = readonly (readonly boolean[])[];
 /** Textstil. Fehlende Felder gelten als Vorgabewert (nicht als "unveraendert"). */
 export interface PosStyles {
     bold?: boolean;
@@ -88,8 +97,26 @@ export interface EscPosHrOptions {
 }
 export interface EscPosQrOptions {
     align?: PosAlign;
+    /**
+     * Feste Modulgroesse in Druckpunkten. Gesetzt schaltet sie die Rechnung ab —
+     * fuer Aufrufer, die genau wissen, was ihr Geraet kann. Ohne sie entscheidet
+     * die Regel in `qr-groesse.ts`.
+     */
     size?: QrSize;
     correction?: QrCorrection;
+    /** Deckel fuer die gerechnete Modulgroesse; wirkungslos neben `size`. */
+    groesse?: QrModulGroesse;
+    /** Modell 1 des Symbols ausdruecklich waehlen — siehe `qrCodeBytes`. */
+    modell1?: boolean;
+}
+export interface EscPosQrRasterOptions {
+    align?: PosAlign;
+    /** Feste Punkte je Modul; ohne Angabe gerechnet (mindestens 1). */
+    punkteJeModul?: number;
+    /** Deckel fuer die gerechnete Groesse. */
+    groesse?: QrModulGroesse;
+    /** Ruhezone je Seite in Modulen; Vorgabe `QR_RUHEZONE_MODULE` (4). */
+    ruhezoneModule?: number;
 }
 /** Interner Stilzustand — immer vollstaendig, nie teilbefuellt. */
 interface AktuelleStile {
@@ -111,6 +138,25 @@ interface AktuelleStile {
 export interface EscPosDocument {
     readonly paperSize: PosPaperSize;
     readonly spaceBetweenRows: number;
+    /**
+     * Der Beleg ging ohne QR hinaus — `null`, solange alles in Ordnung ist.
+     * Gesetzt, wenn das Symbol auch mit der Ausnahmegroesse nicht auf das Papier
+     * passt und kein Bildweg mitgegeben wurde. Auf einer oesterreichischen Kassa
+     * ist der QR die maschinenlesbare Signatur: das muss der Aufrufer erfahren,
+     * ohne den Bytestrom zu durchsuchen.
+     */
+    qrFehler: string | null;
+    /**
+     * Der QR steht auf dem Papier, aber nicht so wie eingestellt — `null`,
+     * solange nichts abgewichen ist. Zwei Faelle, beide mit Grund im Text: das
+     * Symbol war fuer den nativen Befehl zu breit und ging als Bild hinaus, oder
+     * es passte nur unter der Mindest-Modulgroesse.
+     *
+     * Getrennt von `qrFehler`, weil die Handlung eine andere ist: dort heisst es
+     * "Beleg ohne QR, nachdrucken oder elektronisch ausgeben", hier "gedruckt,
+     * aber der eingestellte Weg taugt fuer dieses Geraet nicht".
+     */
+    qrAusweich: string | null;
     /** intern: bisher erzeugte Bytes */
     readonly bytes: number[];
     /** intern: global gesetzte Codepage (ueberlebt `escPosReset`) */
@@ -213,7 +259,45 @@ export declare function escPosRow(doc: EscPosDocument, columns: readonly PosColu
 export declare function qrCodeBytes(text: string, options?: {
     size?: QrSize;
     correction?: QrCorrection;
+    modell1?: boolean;
 }): Uint8Array;
-/** Setzt die Ausrichtung und haengt den nativen QR-Befehl an. */
+/**
+ * Setzt die Ausrichtung und haengt den nativen QR-Befehl an — mit
+ * **gerechneter** Modulgroesse, sofern `options.size` sie nicht festlegt.
+ *
+ * Ohne `size` entscheidet die Regel aus `qr-groesse.ts`: so gross wie
+ * moeglich, gedeckelt durch `options.groesse` (Vorgabe `auto` = der
+ * Bestandswert 4 dieses Pakets). Passt das Symbol auch mit der
+ * Ausnahmegroesse nicht aufs Papier, geht **kein** QR-Befehl hinaus und
+ * `doc.qrFehler` sagt warum: der Drucker schneidet ein zu breites Symbol
+ * nicht ab, er laesst es weg — ein Befehl, von dem man weiss, dass er nichts
+ * druckt, taeuschte nur einen Ausdruck vor. Den Bildweg kennt diese Ebene
+ * nicht; den faehrt `escPosQrRaster` bzw. der Belegweg in `layout-escpos.ts`.
+ *
+ * Eine leere Nutzlast geht unveraendert durch (fester Bestandsweg, keine
+ * Rechnung): sie ist ein Datenfehler, kein Papierfehler, und der Aufrufer
+ * behandelt sie ohnehin schon.
+ */
 export declare function escPosQrCode(doc: EscPosDocument, text: string, options?: EscPosQrOptions): void;
+/**
+ * Der Bildweg: ein fertiges QR-Raster als Rasterbild (`GS v 0`) — der
+ * Notausgang, wenn der native Befehl das Symbol nicht auf das Papier bringt.
+ *
+ * Ein Pflichtbeleg ohne QR ist der schlechteste aller Ausgaenge; als Bild
+ * geht jedes Symbol hinaus, weil die Punkte je Modul hier bis auf 1 fallen
+ * duerfen. Dafuer ist das Bild langsamer und auf manchen Geraeten blasser.
+ *
+ * Das Raster selbst kommt vom Aufrufer (siehe `QrMatrix`): dieses Paket
+ * rechnet keine QR-Codes und verarbeitet keine Bilder.
+ */
+export declare function escPosQrRaster(doc: EscPosDocument, matrix: QrMatrix, options?: EscPosQrRasterOptions): void;
+/**
+ * Punkte je Modul, mit denen `escPosQrRaster` ein Raster dieser Groesse auf
+ * dieses Papier bringt — dieselbe Rechnung, nur ohne Untergrenze 3: ein Bild
+ * darf bis auf einen Punkt je Modul schrumpfen und passt darum immer.
+ */
+export declare function qrRasterPunkte(paperSize: PosPaperSize, moduleAnzahl: number, options?: {
+    groesse?: QrModulGroesse;
+    ruhezoneModule?: number;
+}): number;
 export {};

package/dist/cjs/printing/escpos.js

@@ -47,6 +47,9 @@ exports.escPosHr = escPosHr;
 exports.escPosRow = escPosRow;
 exports.qrCodeBytes = qrCodeBytes;
 exports.escPosQrCode = escPosQrCode;
+exports.escPosQrRaster = escPosQrRaster;
+exports.qrRasterPunkte = qrRasterPunkte;
+const qr_groesse_js_1 = require("./qr-groesse.js");
 // -------------------------------------------------------------- Befehlsbytes
 // Wortwoertlich aus commands.dart. Die Zahlen sind ASCII-Codes der dortigen
 // Zeichenketten: cCutFull = '$gs' + 'V0' ist GS 0x56 0x30 — die Ziffer '0',
@@ -81,6 +84,8 @@ const ZEILENUMBRUCH = 0x0a;
 const CODEPAGE_ID = { CP437: 0, CP1252: 16 };
 /** Korrekturstufen fuer GS ( k Funktion 169 — aus qrcode.dart. */
 const QR_KORREKTUR = { L: 48, M: 49, Q: 50, H: 51 };
+/** Nennbreite der Rolle in Millimetern — nur fuer Meldungstexte. */
+const PAPIER_MM = { mm58: 58, mm80: 80 };
 /** Druckbreite in Punkten je Papierformat — aus enums.dart (EscPaperSize.width). */
 const PAPIER_BREITE = { mm58: 372, mm80: 558 };
 /** Zeichen je Zeile nach Papier und Schrift — aus generator.dart. */
@@ -231,6 +236,8 @@ function createEscPosDocument(options = {}) {
         globalFont: null,
         maxCharsPerLine: null,
         styles: vollstaendigeStile(),
+        qrFehler: null,
+        qrAusweich: null,
     };
 }
 /** Die bisher erzeugten Bytes als Kopie. */
@@ -245,6 +252,10 @@ function escPosBytes(doc) {
 function escPosReset(doc) {
     anhaengen(doc, C_INIT);
     doc.styles = vollstaendigeStile();
+    // Wie `PrintPaper.reset()` im Flutter-Zwilling: ein neu begonnener Beleg
+    // erbt die QR-Meldungen des vorigen nicht.
+    doc.qrFehler = null;
+    doc.qrAusweich = null;
     escPosSetGlobalCodeTable(doc, doc.globalCodeTable);
     escPosSetGlobalFont(doc, doc.globalFont);
 }
@@ -609,6 +620,16 @@ function qrCodeBytes(text, options = {}) {
         throw new Error('QR-Inhalt ist zu lang');
     }
     const bytes = [];
+    // Funktion 165: Symboltyp. Ohne diesen Befehl — dem Bestandsweg — waehlt der
+    // Drucker sein eigenes Modell, in aller Regel Modell 2. Genau das koennen
+    // manche guenstigen Geraete nicht: belegt ist eines, das unter dem Code eine
+    // "0" ausgibt, das Parameterbyte 0x30 des Druckbefehls, das es nicht als
+    // Befehl erkannt hat. Der Befehl geht deshalb nur hinaus, wenn er
+    // ausdruecklich verlangt ist; ein aufgedraengtes "Modell 2 fuer alle" waere
+    // eine stille Umstellung an jedem Bestandsgeraet.
+    if (options.modell1 === true) {
+        bytes.push(...C_QR_HEADER, 0x04, 0x00, 0x31, 0x41, 0x31, 0x00);
+    }
     // Funktion 167: Modulgroesse
     bytes.push(...C_QR_HEADER, 0x03, 0x00, 0x31, 0x43, size);
     // Funktion 169: Fehlerkorrektur
@@ -624,15 +645,57 @@ function qrCodeBytes(text, options = {}) {
     bytes.push(...C_QR_HEADER, 0x03, 0x00, 0x31, 0x51, 0x30);
     return Uint8Array.from(bytes);
 }
-/** Setzt die Ausrichtung und haengt den nativen QR-Befehl an. */
+/**
+ * Setzt die Ausrichtung und haengt den nativen QR-Befehl an — mit
+ * **gerechneter** Modulgroesse, sofern `options.size` sie nicht festlegt.
+ *
+ * Ohne `size` entscheidet die Regel aus `qr-groesse.ts`: so gross wie
+ * moeglich, gedeckelt durch `options.groesse` (Vorgabe `auto` = der
+ * Bestandswert 4 dieses Pakets). Passt das Symbol auch mit der
+ * Ausnahmegroesse nicht aufs Papier, geht **kein** QR-Befehl hinaus und
+ * `doc.qrFehler` sagt warum: der Drucker schneidet ein zu breites Symbol
+ * nicht ab, er laesst es weg — ein Befehl, von dem man weiss, dass er nichts
+ * druckt, taeuschte nur einen Ausdruck vor. Den Bildweg kennt diese Ebene
+ * nicht; den faehrt `escPosQrRaster` bzw. der Belegweg in `layout-escpos.ts`.
+ *
+ * Eine leere Nutzlast geht unveraendert durch (fester Bestandsweg, keine
+ * Rechnung): sie ist ein Datenfehler, kein Papierfehler, und der Aufrufer
+ * behandelt sie ohnehin schon.
+ */
 function escPosQrCode(doc, text, options = {}) {
     escPosSetStyles(doc, { align: options.align ?? 'center' });
     const qrOptionen = {};
-    if (options.size !== undefined)
-        qrOptionen.size = options.size;
     if (options.correction !== undefined)
         qrOptionen.correction = options.correction;
-    anhaengen(doc, qrCodeBytes(text, qrOptionen));
+    if (options.modell1 !== undefined)
+        qrOptionen.modell1 = options.modell1;
+    let drucken = true;
+    if (options.size !== undefined) {
+        qrOptionen.size = options.size;
+    }
+    else if (text !== '') {
+        const mass = (0, qr_groesse_js_1.qrGroesseFuer)({
+            nutzlast: text,
+            papierbreitePunkte: qr_groesse_js_1.QR_DRUCK_PUNKTE[doc.paperSize],
+            groesse: options.groesse ?? 'auto',
+        });
+        if (!mass.passt) {
+            doc.qrFehler =
+                `QR mit ${mass.module} Modulen ist fuer ${PAPIER_MM[doc.paperSize]} mm ` +
+                    `(${qr_groesse_js_1.QR_DRUCK_PUNKTE[doc.paperSize]} Punkte) zu breit`;
+            drucken = false;
+        }
+        else {
+            if (mass.unterMindestmass) {
+                doc.qrAusweich =
+                    `QR mit ${mass.module} Modulen passt nur mit ${String(mass.punkte)} Punkten ` +
+                        `je Modul — unter dem Mindestmass von ${qr_groesse_js_1.QR_MINDEST_PUNKTE}`;
+            }
+            qrOptionen.size = mass.punkte;
+        }
+    }
+    if (drucken)
+        anhaengen(doc, qrCodeBytes(text, qrOptionen));
     // Ausrichtung SOFORT zuruecksetzen: `ESC a` gilt nur am Zeilenanfang. Die
     // Spalten-Positionierung (`ESC $`) schickt ihren Reset sonst mitten in der
     // Zeile — Epson ignoriert ihn, und alles nach dem QR rueckte nach rechts
@@ -641,3 +704,76 @@ function escPosQrCode(doc, text, options = {}) {
         escPosSetStyles(doc, { align: 'left' });
     }
 }
+/**
+ * Der Bildweg: ein fertiges QR-Raster als Rasterbild (`GS v 0`) — der
+ * Notausgang, wenn der native Befehl das Symbol nicht auf das Papier bringt.
+ *
+ * Ein Pflichtbeleg ohne QR ist der schlechteste aller Ausgaenge; als Bild
+ * geht jedes Symbol hinaus, weil die Punkte je Modul hier bis auf 1 fallen
+ * duerfen. Dafuer ist das Bild langsamer und auf manchen Geraeten blasser.
+ *
+ * Das Raster selbst kommt vom Aufrufer (siehe `QrMatrix`): dieses Paket
+ * rechnet keine QR-Codes und verarbeitet keine Bilder.
+ */
+function escPosQrRaster(doc, matrix, options = {}) {
+    const module = matrix.length;
+    if (module <= 0)
+        throw new Error('QR-Raster ist leer');
+    for (const zeile of matrix) {
+        if (zeile.length !== module)
+            throw new Error('QR-Raster ist nicht quadratisch');
+    }
+    const ruhezone = options.ruhezoneModule ?? qr_groesse_js_1.QR_RUHEZONE_MODULE;
+    if (!istGanzzahl(ruhezone) || ruhezone < 0) {
+        throw new Error('ruhezoneModule muss eine Ganzzahl >= 0 sein');
+    }
+    const gesamtModule = module + 2 * ruhezone;
+    let punkte = options.punkteJeModul;
+    if (punkte === undefined) {
+        const deckel = qr_groesse_js_1.QR_MODUL_DECKEL[options.groesse ?? 'auto'];
+        punkte = Math.max(1, Math.min(deckel, Math.floor(qr_groesse_js_1.QR_DRUCK_PUNKTE[doc.paperSize] / gesamtModule)));
+    }
+    if (!istGanzzahl(punkte) || punkte < 1) {
+        throw new Error('punkteJeModul muss eine Ganzzahl >= 1 sein');
+    }
+    const breite = gesamtModule * punkte;
+    const byteJeZeile = Math.ceil(breite / 8);
+    const daten = new Uint8Array(byteJeZeile * breite);
+    for (let y = 0; y < breite; y++) {
+        const modulY = Math.floor(y / punkte) - ruhezone;
+        if (modulY < 0 || modulY >= module)
+            continue;
+        const zeile = matrix[modulY];
+        for (let x = 0; x < breite; x++) {
+            const modulX = Math.floor(x / punkte) - ruhezone;
+            if (modulX < 0 || modulX >= module)
+                continue;
+            if (zeile[modulX] !== true)
+                continue;
+            const i = y * byteJeZeile + (x >> 3);
+            daten[i] = daten[i] | (0x80 >> (x & 7));
+        }
+    }
+    escPosSetStyles(doc, { align: options.align ?? 'center' });
+    // GS v 0 m xL xH yL yH d1...dk — m = 0: normale Dichte, 1:1.
+    anhaengen(doc, [
+        GS, 0x76, 0x30, 0x00,
+        byteJeZeile & 0xff, (byteJeZeile >> 8) & 0xff,
+        breite & 0xff, (breite >> 8) & 0xff,
+        ...daten,
+    ]);
+    anhaengen(doc, [ZEILENUMBRUCH]);
+    if ((options.align ?? 'center') !== 'left') {
+        escPosSetStyles(doc, { align: 'left' });
+    }
+}
+/**
+ * Punkte je Modul, mit denen `escPosQrRaster` ein Raster dieser Groesse auf
+ * dieses Papier bringt — dieselbe Rechnung, nur ohne Untergrenze 3: ein Bild
+ * darf bis auf einen Punkt je Modul schrumpfen und passt darum immer.
+ */
+function qrRasterPunkte(paperSize, moduleAnzahl, options = {}) {
+    const ruhezone = options.ruhezoneModule ?? qr_groesse_js_1.QR_RUHEZONE_MODULE;
+    const deckel = qr_groesse_js_1.QR_MODUL_DECKEL[options.groesse ?? 'auto'];
+    return Math.max(1, Math.min(deckel, Math.floor(qr_groesse_js_1.QR_DRUCK_PUNKTE[paperSize] / (moduleAnzahl + 2 * ruhezone))));
+}

package/dist/cjs/printing/index.d.ts

@@ -1,3 +1,4 @@
-export { type PosPaperSize, type PosAlign, type PosFont, type PosCutMode, type PosCodeTable, type PosTextSize, type QrSize, type QrCorrection, type PosStyles, type PosColumn, type EscPosOptions, type EscPosTextOptions, type EscPosHrOptions, type EscPosQrOptions, type EscPosDocument, createEscPosDocument, escPosBytes, escPosReset, escPosSetGlobalCodeTable, escPosSetGlobalFont, escPosSetStyles, escPosText, escPosEmptyLines, escPosFeed, escPosCut, escPosHr, escPosRow, escPosQrCode, encodeEscPosText, qrCodeBytes, escPosMaxCharsPerLine, escPosWortzeilen, wortzeilenText, } from './escpos.js';
+export { type PosPaperSize, type PosAlign, type PosFont, type PosCutMode, type PosCodeTable, type PosTextSize, type QrSize, type QrCorrection, type QrMatrix, type PosStyles, type PosColumn, type EscPosOptions, type EscPosTextOptions, type EscPosHrOptions, type EscPosQrOptions, type EscPosQrRasterOptions, type EscPosDocument, createEscPosDocument, escPosBytes, escPosReset, escPosSetGlobalCodeTable, escPosSetGlobalFont, escPosSetStyles, escPosText, escPosEmptyLines, escPosFeed, escPosCut, escPosHr, escPosRow, escPosQrCode, escPosQrRaster, qrRasterPunkte, encodeEscPosText, qrCodeBytes, escPosMaxCharsPerLine, escPosWortzeilen, wortzeilenText, } from './escpos.js';
+export { type QrModulGroesse, type QrGroesse, QR_MODUL_DECKEL, QR_RUHEZONE_MODULE, QR_MINDEST_PUNKTE, QR_AUSNAHME_PUNKTE, QR_HOECHST_PUNKTE, QR_DRUCK_PUNKTE, qrModulAnzahl, qrGroesseBerechnen, qrGroesseFuer, } from './qr-groesse.js';
 export { escPosPrintableText } from './printable.js';
 export { type UsbEndpointLike, type UsbAlternateLike, type UsbInterfaceLike, type UsbConfigurationLike, type UsbTransferOutResultLike, type UsbWriterLike, type UsbIdentityLike, type UsbDeviceLike, type UsbPrinterEndpoint, type UsbPrinterConnection, USB_VENDOR_EPSON, USB_CLASS_PRINTER, UsbTimeoutError, usbDeviceKey, usbFindPrinterEndpoint, usbWriteAll, usbConnectPrinter, usbPrint, usbDisconnect, } from './webusb.js';

package/dist/cjs/printing/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.usbDisconnect = exports.usbPrint = exports.usbConnectPrinter = exports.usbWriteAll = exports.usbFindPrinterEndpoint = exports.usbDeviceKey = exports.UsbTimeoutError = exports.USB_CLASS_PRINTER = exports.USB_VENDOR_EPSON = exports.escPosPrintableText = exports.wortzeilenText = exports.escPosWortzeilen = exports.escPosMaxCharsPerLine = exports.qrCodeBytes = exports.encodeEscPosText = exports.escPosQrCode = exports.escPosRow = exports.escPosHr = exports.escPosCut = exports.escPosFeed = exports.escPosEmptyLines = exports.escPosText = exports.escPosSetStyles = exports.escPosSetGlobalFont = exports.escPosSetGlobalCodeTable = exports.escPosReset = exports.escPosBytes = exports.createEscPosDocument = void 0;
+exports.usbDisconnect = exports.usbPrint = exports.usbConnectPrinter = exports.usbWriteAll = exports.usbFindPrinterEndpoint = exports.usbDeviceKey = exports.UsbTimeoutError = exports.USB_CLASS_PRINTER = exports.USB_VENDOR_EPSON = exports.escPosPrintableText = exports.qrGroesseFuer = exports.qrGroesseBerechnen = exports.qrModulAnzahl = exports.QR_DRUCK_PUNKTE = exports.QR_HOECHST_PUNKTE = exports.QR_AUSNAHME_PUNKTE = exports.QR_MINDEST_PUNKTE = exports.QR_RUHEZONE_MODULE = exports.QR_MODUL_DECKEL = exports.wortzeilenText = exports.escPosWortzeilen = exports.escPosMaxCharsPerLine = exports.qrCodeBytes = exports.encodeEscPosText = exports.qrRasterPunkte = exports.escPosQrRaster = exports.escPosQrCode = exports.escPosRow = exports.escPosHr = exports.escPosCut = exports.escPosFeed = exports.escPosEmptyLines = exports.escPosText = exports.escPosSetStyles = exports.escPosSetGlobalFont = exports.escPosSetGlobalCodeTable = exports.escPosReset = exports.escPosBytes = exports.createEscPosDocument = void 0;
 var escpos_js_1 = require("./escpos.js");
 Object.defineProperty(exports, "createEscPosDocument", { enumerable: true, get: function () { return escpos_js_1.createEscPosDocument; } });
 Object.defineProperty(exports, "escPosBytes", { enumerable: true, get: function () { return escpos_js_1.escPosBytes; } });
@@ -15,11 +15,23 @@ Object.defineProperty(exports, "escPosCut", { enumerable: true, get: function ()
 Object.defineProperty(exports, "escPosHr", { enumerable: true, get: function () { return escpos_js_1.escPosHr; } });
 Object.defineProperty(exports, "escPosRow", { enumerable: true, get: function () { return escpos_js_1.escPosRow; } });
 Object.defineProperty(exports, "escPosQrCode", { enumerable: true, get: function () { return escpos_js_1.escPosQrCode; } });
+Object.defineProperty(exports, "escPosQrRaster", { enumerable: true, get: function () { return escpos_js_1.escPosQrRaster; } });
+Object.defineProperty(exports, "qrRasterPunkte", { enumerable: true, get: function () { return escpos_js_1.qrRasterPunkte; } });
 Object.defineProperty(exports, "encodeEscPosText", { enumerable: true, get: function () { return escpos_js_1.encodeEscPosText; } });
 Object.defineProperty(exports, "qrCodeBytes", { enumerable: true, get: function () { return escpos_js_1.qrCodeBytes; } });
 Object.defineProperty(exports, "escPosMaxCharsPerLine", { enumerable: true, get: function () { return escpos_js_1.escPosMaxCharsPerLine; } });
 Object.defineProperty(exports, "escPosWortzeilen", { enumerable: true, get: function () { return escpos_js_1.escPosWortzeilen; } });
 Object.defineProperty(exports, "wortzeilenText", { enumerable: true, get: function () { return escpos_js_1.wortzeilenText; } });
+var qr_groesse_js_1 = require("./qr-groesse.js");
+Object.defineProperty(exports, "QR_MODUL_DECKEL", { enumerable: true, get: function () { return qr_groesse_js_1.QR_MODUL_DECKEL; } });
+Object.defineProperty(exports, "QR_RUHEZONE_MODULE", { enumerable: true, get: function () { return qr_groesse_js_1.QR_RUHEZONE_MODULE; } });
+Object.defineProperty(exports, "QR_MINDEST_PUNKTE", { enumerable: true, get: function () { return qr_groesse_js_1.QR_MINDEST_PUNKTE; } });
+Object.defineProperty(exports, "QR_AUSNAHME_PUNKTE", { enumerable: true, get: function () { return qr_groesse_js_1.QR_AUSNAHME_PUNKTE; } });
+Object.defineProperty(exports, "QR_HOECHST_PUNKTE", { enumerable: true, get: function () { return qr_groesse_js_1.QR_HOECHST_PUNKTE; } });
+Object.defineProperty(exports, "QR_DRUCK_PUNKTE", { enumerable: true, get: function () { return qr_groesse_js_1.QR_DRUCK_PUNKTE; } });
+Object.defineProperty(exports, "qrModulAnzahl", { enumerable: true, get: function () { return qr_groesse_js_1.qrModulAnzahl; } });
+Object.defineProperty(exports, "qrGroesseBerechnen", { enumerable: true, get: function () { return qr_groesse_js_1.qrGroesseBerechnen; } });
+Object.defineProperty(exports, "qrGroesseFuer", { enumerable: true, get: function () { return qr_groesse_js_1.qrGroesseFuer; } });
 var printable_js_1 = require("./printable.js");
 Object.defineProperty(exports, "escPosPrintableText", { enumerable: true, get: function () { return printable_js_1.escPosPrintableText; } });
 var webusb_js_1 = require("./webusb.js");

package/dist/cjs/printing/qr-groesse.d.ts

@@ -0,0 +1,122 @@
+import type { PosPaperSize, QrSize } from './escpos.js';
+/**
+ * Die Rechenregel fuer die Modulgroesse des Beleg-QR — rein, ohne Drucker.
+ * Zwilling von `kasseneck_api/lib/src/printing/qr_groesse.dart` (Flutter).
+ *
+ * Vorgeschichte: der native QR-Befehl bekommt eine feste Modulgroesse in
+ * Druckpunkten mit und rechnet nicht nach, ob das Symbol aufs Papier passt.
+ * Ein Beleg-QR mit realer RKSV-Nutzlast hat 57 Module, mit Ruhezone also
+ * (57 + 8) Module breit; bei sechs Punkten je Modul sind das 390 Druckpunkte,
+ * und ein 58-mm-Kopf hat 384. Zu breit heisst bei den meisten Geraeten nicht
+ * "abgeschnitten", sondern **gar kein QR** — auf einem Pflichtbeleg der
+ * schlechteste aller Ausgaenge. (Im Flutter-Zwilling war genau das der
+ * belegte Fehler; dieses Paket druckt seit jeher mit vier Punkten und blieb
+ * darum verschont. Die Regel ist trotzdem dieselbe: sie deckelt auch eine
+ * ausdruecklich gewaehlte groessere Modulgroesse gegen den Papierrand ab.)
+ */
+/**
+ * Wie gross die Module des Beleg-QR werden duerfen — ein **Deckel**, keine
+ * Vorgabe: gedruckt wird immer die groesste Groesse, die noch aufs Papier
+ * passt, hoechstens aber diese hier.
+ *
+ * `auto` und `klein` decken beide bei 4 — das ist kein Versehen. 4 ist der
+ * Wert, den der native Weg dieses Pakets seit jeher druckt
+ * (`qrCodeBytes(..., size ?? 4)`); ohne diesen Deckel bekaeme jedes Geraet ab
+ * sofort ungefragt einen groesseren QR als gestern. `auto` heisst also
+ * "rechne, aber aendere den Bestand nicht".
+ *
+ * **Abweichung zum Flutter-Zwilling, bewusst:** dort deckelt `auto` bei 6,
+ * weil dort 6 der Bestandswert ist. Die Regel ist in beiden Paketen
+ * dieselbe — "so gross wie moeglich, hoechstens der Bestandswert" —, nur der
+ * Bestandswert unterscheidet sich. `mittel` (6) und `gross` (8) sind in
+ * beiden Paketen gleich; sie waehlt ein Mensch.
+ */
+export type QrModulGroesse = 'auto' | 'klein' | 'mittel' | 'gross';
+/** Groesste Modulgroesse in Druckpunkten, die der jeweilige Deckel zulaesst. */
+export declare const QR_MODUL_DECKEL: Readonly<Record<QrModulGroesse, number>>;
+/**
+ * Ergebnis der Modulgroessen-Rechnung.
+ *
+ * Traegt bewusst mehr als die Zahl: ob ueberhaupt etwas passt (`passt`), ob
+ * nur unter der Mindestgroesse (`unterMindestmass`) und wie breit das Symbol
+ * wird (`breitePunkte`). Eine blosse Zahl haette die Ausnahme verschwiegen.
+ */
+export interface QrGroesse {
+    /**
+     * Modulgroesse in Druckpunkten, `null` wenn das Symbol auch mit der
+     * Ausnahmegroesse nicht aufs Papier passt.
+     */
+    readonly punkte: QrSize | null;
+    /** Modulanzahl des Symbols (ohne Ruhezone). */
+    readonly module: number;
+    /** Gesamtbreite inklusive Ruhezone in Druckpunkten; 0, wenn nichts passt. */
+    readonly breitePunkte: number;
+    /**
+     * Gedruckt wird unter `QR_MINDEST_PUNKTE`. Erlaubt, aber eine Ausnahme, von
+     * der der Aufrufer erfahren muss — billige Thermodrucker und Handykameras
+     * tun sich damit schwer, besonders auf gewelltem Papier.
+     */
+    readonly unterMindestmass: boolean;
+    /** Kurz fuer `punkte !== null`. */
+    readonly passt: boolean;
+}
+/** Ruhezone je Seite, in Modulen (QR-Norm). */
+export declare const QR_RUHEZONE_MODULE = 4;
+/** Untergrenze: 4 Punkte sind bei 203 dpi rund 0,5 mm je Modul. */
+export declare const QR_MINDEST_PUNKTE = 4;
+/** Ausnahme, wenn `QR_MINDEST_PUNKTE` nicht passt — gemeldet, nicht still. */
+export declare const QR_AUSNAHME_PUNKTE = 3;
+/** Obergrenze des Druckbefehls in diesem Stack (`GS ( k` Funktion 167: 1..8). */
+export declare const QR_HOECHST_PUNKTE = 8;
+/**
+ * Druckbreite des Kopfes in Punkten (203 dpi): 58 mm = 384, 80 mm = 576 —
+ * Zwilling von `KeckPaperSize.druckPunkte`.
+ *
+ * Nicht dasselbe wie die Spaltenbreite in `escpos.ts` (372/558): die stammt
+ * aus `EscPaperSize.width` und laesst absichtlich Rand fuer die
+ * Textpositionierung. Wer rechnet, ob ein Symbol aufs Papier passt, braucht
+ * die echte Kopfbreite — ein QR, der auch nur einen Punkt zu breit ist, wird
+ * von den meisten Geraeten gar nicht gedruckt.
+ */
+export declare const QR_DRUCK_PUNKTE: Readonly<Record<PosPaperSize, number>>;
+/**
+ * Modulanzahl, die `nutzlast` bei Fehlerkorrektur **M** braucht.
+ *
+ * Warum M, obwohl der native Befehl mit L druckt: M braucht bei gleicher
+ * Nutzlast gleich viele oder mehr Module als L. Wer mit M rechnet und mit L
+ * druckt, druckt nie breiter als gerechnet — die Rechnung ist konservativ,
+ * nie knapp. Umgekehrt waere sie eine Rechnung, die aufgeht, und ein Symbol,
+ * das ueber den Papierrand laeuft. Dasselbe gilt fuer die Byte-Zaehlung: hier
+ * zaehlt UTF-8 (wie im Flutter-Zwilling), waehrend `qrCodeBytes` die Nutzlast
+ * als Latin-1 sendet — UTF-8 ist nie kuerzer, die Rechnung also nie zu klein.
+ *
+ * Wirft, wenn die Nutzlast in keine Version passt — wie `qrCodeBytes` bei zu
+ * langem Inhalt. Ein still zurueckgegebenes "passt nicht" haette den
+ * Datenfehler als Papierfehler getarnt.
+ */
+export declare function qrModulAnzahl(nutzlast: string): number;
+/**
+ * Groesste Modulgroesse, mit der `moduleAnzahl` Module **samt Ruhezone** in
+ * `papierbreitePunkte` passen, gedeckelt durch `groesse`.
+ *
+ * Wirft bei sinnlosen Eingaben: eine Papierbreite von 0 oder ein Symbol ohne
+ * Module ist ein Programmierfehler, und ein still zurueckgegebenes "passt
+ * nicht" haette ihn als Druckerproblem getarnt.
+ */
+export declare function qrGroesseBerechnen(options: {
+    papierbreitePunkte: number;
+    moduleAnzahl: number;
+    groesse?: QrModulGroesse;
+}): QrGroesse;
+/**
+ * Wie `qrGroesseBerechnen`, nur mit der Modulanzahl aus `nutzlast`.
+ *
+ * Eine leere Nutzlast ergibt kein Symbol — sie "passt nicht", statt zu
+ * werfen: der Aufrufer behandelt den Fall ohnehin schon (leerer QR am Beleg
+ * ist ein Datenfehler, kein Papierfehler).
+ */
+export declare function qrGroesseFuer(options: {
+    nutzlast: string;
+    papierbreitePunkte: number;
+    groesse?: QrModulGroesse;
+}): QrGroesse;