@bitmagic/cli 0.1.53-dev.0 → 0.1.53-dev.10

package/dist/render/qr-output.js

@@ -0,0 +1,71 @@
+/**
+ * Where a publish's QR code goes: the terminal when someone is looking at it, a file when nobody
+ * is.
+ *
+ * This module exists because the two are one decision, not two. `qr-terminal.ts` refuses a
+ * non-TTY for a good reason — escape sequences in a captured stream are noise — but refusing to
+ * DRAW is not the same as having nothing to offer, and for this CLI the captured stream is the
+ * common case. The pro lane is driven by an agent, so stdout is a pipe on almost every real
+ * publish, and the creator who would scan the code never sees the terminal at all. Gating the
+ * feature on `isTTY` alone turned it off exactly where the URL is most worth handing over.
+ *
+ * So: draw it if it can be drawn, and write `.bitmagic/publish-qr.png` whenever it cannot. That
+ * covers the pipe, and also the two smaller cases with the same shape — `TERM=dumb`, and a
+ * terminal too narrow to hold the code unwrapped — where a person is present but still has nothing
+ * to scan. A terminal that draws successfully writes no file: it already did the job.
+ *
+ * `.bitmagic/` is excluded from the publish fingerprint (`EXCLUDED_DIRS` in
+ * `@bitmagic/asset-core/publish-source`), so writing here cannot invalidate the verify the gate
+ * just checked.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { encodeQr } from './qr.js';
+import { encodeQrPng } from './qr-png.js';
+import { renderTerminalQr } from './qr-terminal.js';
+/** Where a publish leaves its QR image. One per project, overwritten each publish. */
+export function publishQrPath(root) {
+    return path.join(root, '.bitmagic', 'publish-qr.png');
+}
+/**
+ * Show `url` as a QR code however this run can, and return the image path when one was written.
+ *
+ * Never throws and never reports failure as an error: the caller has already printed the URL, and
+ * a code that could not be produced costs the creator a retype, not a publish.
+ */
+export function emitQr(url, options) {
+    const env = options.env ?? process.env;
+    if (options.disabled || env.BITMAGIC_NO_QR)
+        return null;
+    // Drawing is tried first and, when it works, is the whole answer — a file nobody opens is
+    // clutter in a directory the creator does read.
+    if (!options.json) {
+        const drawn = renderTerminalQr(url, {
+            env,
+            ...(options.isTTY === undefined ? {} : { isTTY: options.isTTY }),
+            columns: options.columns,
+            ...(options.write === undefined ? {} : { write: options.write }),
+        });
+        if (drawn)
+            return null;
+    }
+    const matrix = encodeQr(url);
+    if (matrix === null)
+        return null;
+    const file = publishQrPath(options.root);
+    try {
+        if (options.writeFile) {
+            options.writeFile(file, encodeQrPng(matrix));
+        }
+        else {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, encodeQrPng(matrix));
+        }
+        return file;
+    }
+    catch {
+        // A read-only or full disk is not worth failing a successful publish over.
+        return null;
+    }
+}
+//# sourceMappingURL=qr-output.js.map

package/dist/render/qr-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr-output.js","sourceRoot":"","sources":["../../src/render/qr-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAsB,MAAM,kBAAkB,CAAC;AAExE,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,gBAAgB,CAAC,CAAC;AACxD,CAAC;AAiBD;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,GAAW,EAAE,OAAsB;IACxD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,IAAI,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC,cAAc;QAAE,OAAO,IAAI,CAAC;IAExD,0FAA0F;IAC1F,gDAAgD;IAChD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,EAAE;YAClC,GAAG;YACH,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAChE,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;SACjE,CAAC,CAAC;QACH,IAAI,KAAK;YAAE,OAAO,IAAI,CAAC;IACzB,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEjC,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/C,CAAC;aAAM,CAAC;YACN,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACtD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/render/qr-png.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A QR code as PNG bytes, for the creator who cannot scan the terminal.
+ *
+ * `qr-terminal.ts` covers the case where a person is looking at the output. That is not the common
+ * case for this CLI: the pro lane is driven by an agent, so stdout is a pipe, and the human who
+ * would do the scanning is on the far side of it. A file crosses that boundary where escape
+ * sequences cannot — an agent can hand an image to its creator, and cannot hand them a repainted
+ * terminal.
+ *
+ * Greyscale, one byte per pixel. A QR carries one bit per module, so colour would be three bytes of
+ * nothing; and at this size the whole image deflates to a few hundred bytes either way. The
+ * encoder is hand-rolled for the same reason `qr.ts` is — `@bitmagic/cli` ships four runtime
+ * dependencies on purpose, and node's own `zlib` (already used in `publish/` and `assets/`) does
+ * the only part that is genuinely hard.
+ *
+ * Two other hand-rolled PNG encoders exist in this repo — `world-forger-internal`'s vehicle atlas
+ * and `game-play-agent`'s solid-colour tile — and neither is reachable from here: the first is in a
+ * `private: true` package the CLI does not depend on, the second is server code. A shared home
+ * would have to be `@bitmagic/asset-core`; that is worth doing when something needs the third copy,
+ * not for the second.
+ */
+import { Buffer } from 'buffer';
+export interface QrPngOptions {
+    /** Pixels per module. Defaults to `MODULE_PIXELS`. */
+    scale?: number;
+    /** Quiet zone in modules. Defaults to `QUIET_MODULES`. */
+    quietZone?: number;
+}
+/** The pixel width (and height) `encodeQrPng` produces for a matrix of this size. */
+export declare function qrPngDimension(matrix: boolean[][], options?: QrPngOptions): number;
+/**
+ * Encode a module matrix as a greyscale PNG: dark modules black, everything else white.
+ *
+ * White is 0xff and dark is 0x00, never inverted — a scanner wants dark on light, and unlike the
+ * terminal there is no theme here to fight about it.
+ */
+export declare function encodeQrPng(matrix: boolean[][], options?: QrPngOptions): Buffer;

package/dist/render/qr-png.js

@@ -0,0 +1,111 @@
+/**
+ * A QR code as PNG bytes, for the creator who cannot scan the terminal.
+ *
+ * `qr-terminal.ts` covers the case where a person is looking at the output. That is not the common
+ * case for this CLI: the pro lane is driven by an agent, so stdout is a pipe, and the human who
+ * would do the scanning is on the far side of it. A file crosses that boundary where escape
+ * sequences cannot — an agent can hand an image to its creator, and cannot hand them a repainted
+ * terminal.
+ *
+ * Greyscale, one byte per pixel. A QR carries one bit per module, so colour would be three bytes of
+ * nothing; and at this size the whole image deflates to a few hundred bytes either way. The
+ * encoder is hand-rolled for the same reason `qr.ts` is — `@bitmagic/cli` ships four runtime
+ * dependencies on purpose, and node's own `zlib` (already used in `publish/` and `assets/`) does
+ * the only part that is genuinely hard.
+ *
+ * Two other hand-rolled PNG encoders exist in this repo — `world-forger-internal`'s vehicle atlas
+ * and `game-play-agent`'s solid-colour tile — and neither is reachable from here: the first is in a
+ * `private: true` package the CLI does not depend on, the second is server code. A shared home
+ * would have to be `@bitmagic/asset-core`; that is worth doing when something needs the third copy,
+ * not for the second.
+ */
+import { Buffer } from 'buffer';
+import * as zlib from 'zlib';
+/** Pixels per QR module. Large enough that a phone camera reads it off a normal screen. */
+const MODULE_PIXELS = 8;
+/**
+ * Quiet zone in modules. Four, the value the spec asks for, rather than the two `qr-terminal.ts`
+ * uses — that one is trading margin for terminal columns, and a file has no such constraint.
+ */
+const QUIET_MODULES = 4;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** The standard CRC-32 table (PNG spec annex D), built once. */
+function buildCrcTable() {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n += 1) {
+        let c = n;
+        for (let k = 0; k < 8; k += 1) {
+            c = (c & 1) !== 0 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        }
+        table[n] = c >>> 0;
+    }
+    return table;
+}
+const CRC_TABLE = buildCrcTable();
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/** One PNG chunk: length, type, data, and the CRC over type+data (never over the length). */
+function chunk(type, data) {
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(data.length, 0);
+    const typeAndData = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(typeAndData), 0);
+    return Buffer.concat([length, typeAndData, crc]);
+}
+/** The pixel width (and height) `encodeQrPng` produces for a matrix of this size. */
+export function qrPngDimension(matrix, options = {}) {
+    const scale = options.scale ?? MODULE_PIXELS;
+    const quiet = options.quietZone ?? QUIET_MODULES;
+    return (matrix.length + quiet * 2) * scale;
+}
+/**
+ * Encode a module matrix as a greyscale PNG: dark modules black, everything else white.
+ *
+ * White is 0xff and dark is 0x00, never inverted — a scanner wants dark on light, and unlike the
+ * terminal there is no theme here to fight about it.
+ */
+export function encodeQrPng(matrix, options = {}) {
+    const scale = options.scale ?? MODULE_PIXELS;
+    const quiet = options.quietZone ?? QUIET_MODULES;
+    const dimension = qrPngDimension(matrix, options);
+    // One filter byte per scanline (0 = None: a QR is flat colour, so the other filters buy nothing
+    // that deflate does not already get from the runs), then one byte per pixel.
+    const raw = Buffer.alloc(dimension * (dimension + 1), 0xff);
+    for (let y = 0; y < dimension; y += 1) {
+        const rowStart = y * (dimension + 1);
+        raw[rowStart] = 0;
+        const moduleRow = Math.floor(y / scale) - quiet;
+        if (moduleRow < 0 || moduleRow >= matrix.length)
+            continue;
+        for (let x = 0; x < dimension; x += 1) {
+            const moduleCol = Math.floor(x / scale) - quiet;
+            if (moduleCol < 0 || moduleCol >= matrix.length)
+                continue;
+            if (matrix[moduleRow][moduleCol])
+                raw[rowStart + 1 + x] = 0x00;
+        }
+    }
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(dimension, 0);
+    ihdr.writeUInt32BE(dimension, 4);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 0; // colour type 0 — greyscale
+    ihdr[10] = 0; // compression: deflate, the only value PNG defines
+    ihdr[11] = 0; // filter method: adaptive, the only value PNG defines
+    ihdr[12] = 0; // interlace: none
+    return Buffer.concat([
+        PNG_SIGNATURE,
+        chunk('IHDR', ihdr),
+        // deflateSync, not fflate's — fflate's `deflateSync` emits RAW deflate with no zlib header,
+        // and an IDAT must carry the zlib wrapper. (fflate's `zlibSync` would also do.)
+        chunk('IDAT', zlib.deflateSync(raw)),
+        chunk('IEND', Buffer.alloc(0)),
+    ]);
+}
+//# sourceMappingURL=qr-png.js.map

package/dist/render/qr-png.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr-png.js","sourceRoot":"","sources":["../../src/render/qr-png.ts"],"names":[],"mappings":"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"}

package/dist/render/qr-terminal.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Drawing a QR code into the terminal, so the URL `bitmagic publish` just printed can be scanned
+ * off the screen instead of retyped into a phone. The Creator has had this since it shipped — the
+ * publish dialog ends on a QR — and the CLI's publish is the same moment: `--visibility private`
+ * puts a real, phone-reachable URL on a game nobody else can find, which is exactly a "try it on
+ * my phone" build.
+ *
+ * The contract is `inline-image.ts`'s, deliberately: the code is strictly ADDITIONAL. The caller
+ * prints the URL first, unconditionally; this either draws underneath it or does nothing at all. It
+ * never replaces a line and it never reports failure as an error, because an agent tool is usually
+ * what reads this output.
+ *
+ * That last clause is also why nothing should call this module directly. Refusing to DRAW into a
+ * pipe is right; having nothing to offer when there is one is not, and since an agent drives most
+ * publishes, the pipe is the common case rather than the edge. `qr-output.ts` owns that decision —
+ * it asks this module first and falls back to a PNG file — and `bitmagic publish` goes through it.
+ *
+ * Where it DIVERGES from that file is the gate. `supportsInlineImage` is an allowlist of terminals
+ * known to implement the iTerm2 protocol, because the ones that do not print a screenful of raw
+ * base64. Nothing here is exotic: half-block characters and SGR colour are universal, and tmux
+ * passes both through rather than swallowing them. So the gate below asks what the terminal can do
+ * — is it a terminal at all, is it wide enough — and never who it is.
+ */
+export interface TerminalQrEnv {
+    TERM?: string | undefined;
+    BITMAGIC_NO_QR?: string | undefined;
+}
+/**
+ * Whether this terminal can show a scannable code at all.
+ *
+ * Not an allowlist — see the file header. `TERM=dumb` is the one terminal that answers no on its
+ * own behalf, and a non-TTY means something is reading this rather than looking at it — which is a
+ * reason not to paint escape sequences, NOT a reason to withhold the code. `qr-output.ts` writes an
+ * image for every case this function turns down.
+ */
+export declare function supportsTerminalQr(env: TerminalQrEnv, isTTY: boolean): boolean;
+/** How many columns the drawn code occupies, quiet zone included. */
+export declare function terminalQrWidth(matrix: boolean[][]): number;
+/**
+ * The code as terminal lines, quiet zone included and each line self-contained.
+ *
+ * Exported so a test can read the output without a TTY. The padded symbol has an odd number of
+ * module rows — the module count is always odd and the quiet zone adds an even number — so the
+ * final terminal row pairs its top half against a light row that is not in the symbol. That is
+ * correct rather than a rounding artefact: it reads as one more row of quiet zone.
+ */
+export declare function terminalQrLines(matrix: boolean[][]): string[];
+export interface RenderTerminalQrOptions {
+    env?: TerminalQrEnv;
+    isTTY?: boolean;
+    /** Terminal width. Undefined means unknown, which is treated as wide enough. */
+    columns?: number | undefined;
+    write?: (chunk: string) => void;
+    caption?: string;
+}
+/**
+ * Draw `text` as a QR code if this terminal can show one. Returns whether anything was drawn, so a
+ * caller can decide what else to say — never throws, and never writes when unsupported.
+ *
+ * The caption and the code go out in a single write, so the creator never sees an invitation to
+ * scan with nothing under it.
+ */
+export declare function renderTerminalQr(text: string, options?: RenderTerminalQrOptions): boolean;

package/dist/render/qr-terminal.js

@@ -0,0 +1,142 @@
+/**
+ * Drawing a QR code into the terminal, so the URL `bitmagic publish` just printed can be scanned
+ * off the screen instead of retyped into a phone. The Creator has had this since it shipped — the
+ * publish dialog ends on a QR — and the CLI's publish is the same moment: `--visibility private`
+ * puts a real, phone-reachable URL on a game nobody else can find, which is exactly a "try it on
+ * my phone" build.
+ *
+ * The contract is `inline-image.ts`'s, deliberately: the code is strictly ADDITIONAL. The caller
+ * prints the URL first, unconditionally; this either draws underneath it or does nothing at all. It
+ * never replaces a line and it never reports failure as an error, because an agent tool is usually
+ * what reads this output.
+ *
+ * That last clause is also why nothing should call this module directly. Refusing to DRAW into a
+ * pipe is right; having nothing to offer when there is one is not, and since an agent drives most
+ * publishes, the pipe is the common case rather than the edge. `qr-output.ts` owns that decision —
+ * it asks this module first and falls back to a PNG file — and `bitmagic publish` goes through it.
+ *
+ * Where it DIVERGES from that file is the gate. `supportsInlineImage` is an allowlist of terminals
+ * known to implement the iTerm2 protocol, because the ones that do not print a screenful of raw
+ * base64. Nothing here is exotic: half-block characters and SGR colour are universal, and tmux
+ * passes both through rather than swallowing them. So the gate below asks what the terminal can do
+ * — is it a terminal at all, is it wide enough — and never who it is.
+ */
+import { encodeQr } from './qr.js';
+/** Written as an escape rather than a literal control byte, so the source stays greppable. */
+const ESC = '\u001b';
+/**
+ * Black on bright white, and the reset that closes every line.
+ *
+ * Explicit on purpose. A scanner wants dark modules on a light field, and the creator's terminal is
+ * probably a dark theme — left to inherit, the code would come out inverted, which many scanners
+ * cope with and some do not. The reset ends each line so the colour cannot bleed into a wrapped
+ * line or the prompt. Bright white (107) rather than plain white (47) because the latter is a light
+ * grey in most palettes, and contrast is the one thing a scanner cannot make up for.
+ */
+const PAINT = `${ESC}[30;107m`;
+const RESET = `${ESC}[0m`;
+/**
+ * Quiet-zone width in modules, matching the `margin: 2` the Creator passes `QRCode.toDataURL` —
+ * a value already proven to scan in production. The spec asks for 4; if scans ever prove flaky,
+ * that is the knob, and it costs 4 columns and 1 line.
+ */
+const QUIET_ZONE = 2;
+/**
+ * Two module rows per terminal row, drawn with half-blocks.
+ *
+ * This is what makes the code square. Terminal cells are roughly twice as tall as they are wide, so
+ * one module per cell would stretch the symbol into a rectangle no scanner would read; half-blocks
+ * put two module rows in one cell and bring the aspect ratio back to 1:1.
+ */
+const BOTH_DARK = '█'; // full block
+const TOP_DARK = '▀'; // upper half block
+const BOTTOM_DARK = '▄'; // lower half block
+const BOTH_LIGHT = ' ';
+/**
+ * Whether this terminal can show a scannable code at all.
+ *
+ * Not an allowlist — see the file header. `TERM=dumb` is the one terminal that answers no on its
+ * own behalf, and a non-TTY means something is reading this rather than looking at it — which is a
+ * reason not to paint escape sequences, NOT a reason to withhold the code. `qr-output.ts` writes an
+ * image for every case this function turns down.
+ */
+export function supportsTerminalQr(env, isTTY) {
+    if (!isTTY)
+        return false;
+    if (env.BITMAGIC_NO_QR)
+        return false;
+    return env.TERM !== 'dumb';
+}
+/** How many columns the drawn code occupies, quiet zone included. */
+export function terminalQrWidth(matrix) {
+    return matrix.length + QUIET_ZONE * 2;
+}
+/**
+ * The code as terminal lines, quiet zone included and each line self-contained.
+ *
+ * Exported so a test can read the output without a TTY. The padded symbol has an odd number of
+ * module rows — the module count is always odd and the quiet zone adds an even number — so the
+ * final terminal row pairs its top half against a light row that is not in the symbol. That is
+ * correct rather than a rounding artefact: it reads as one more row of quiet zone.
+ */
+export function terminalQrLines(matrix) {
+    const width = terminalQrWidth(matrix);
+    const height = width;
+    const dark = (row, col) => {
+        const r = row - QUIET_ZONE;
+        const c = col - QUIET_ZONE;
+        if (r < 0 || c < 0 || r >= matrix.length || c >= matrix.length)
+            return false;
+        return matrix[r][c];
+    };
+    const lines = [];
+    for (let row = 0; row < height; row += 2) {
+        let line = '';
+        for (let col = 0; col < width; col += 1) {
+            const top = dark(row, col);
+            const bottom = row + 1 < height && dark(row + 1, col);
+            if (top && bottom)
+                line += BOTH_DARK;
+            else if (top)
+                line += TOP_DARK;
+            else if (bottom)
+                line += BOTTOM_DARK;
+            else
+                line += BOTH_LIGHT;
+        }
+        lines.push(`${PAINT}${line}${RESET}`);
+    }
+    return lines;
+}
+/**
+ * Draw `text` as a QR code if this terminal can show one. Returns whether anything was drawn, so a
+ * caller can decide what else to say — never throws, and never writes when unsupported.
+ *
+ * The caption and the code go out in a single write, so the creator never sees an invitation to
+ * scan with nothing under it.
+ */
+export function renderTerminalQr(text, options = {}) {
+    const env = options.env ?? process.env;
+    const isTTY = options.isTTY ?? process.stdout.isTTY === true;
+    if (!supportsTerminalQr(env, isTTY))
+        return false;
+    const matrix = encodeQr(text);
+    if (matrix === null)
+        return false;
+    // A code wider than the terminal wraps, and a wrapped code is not a code — it is noise that
+    // looks like output. Better to leave the plain URL standing on its own.
+    const columns = options.columns ?? process.stdout.columns;
+    if (typeof columns === 'number' && columns < terminalQrWidth(matrix))
+        return false;
+    const caption = options.caption ?? 'Scan to play on your phone:';
+    const write = options.write ?? ((chunk) => process.stdout.write(chunk));
+    try {
+        write(`\n${caption}\n\n${terminalQrLines(matrix).join('\n')}\n\n`);
+        return true;
+    }
+    catch {
+        // A closed or non-writable stdout is not worth failing a successful publish over.
+        return false;
+    }
+}
+//# sourceMappingURL=qr-terminal.js.map

package/dist/render/qr-terminal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr-terminal.js","sourceRoot":"","sources":["../../src/render/qr-terminal.ts"],"names":[],"mappings":"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"}

package/dist/render/qr.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A QR encoder, so `bitmagic publish` can hand the creator's phone the URL it just printed.
+ *
+ * The Creator does this server-side already — `PublishController.generateQRCode` calls the `qrcode`
+ * package and the publish dialog shows the PNG. The CLI cannot follow it there: `qrcode` drags in
+ * `dijkstrajs`, `pngjs` and `yargs@15`, and `@bitmagic/cli` is a published package with four
+ * deliberately-chosen runtime dependencies. So the encoder lives here instead, cut down to exactly
+ * what a published-game URL needs:
+ *
+ *   - **Byte mode only.** A URL is bytes. Numeric, alphanumeric and kanji modes would encode it
+ *     smaller in theory and never in practice, because `https://` alone rules out alphanumeric.
+ *   - **Error correction level M only**, matching the Creator's `errorCorrectionLevel: 'M'` — a code
+ *     scanned from this terminal and one scanned from the publish dialog then behave identically.
+ *   - **Versions 1-9 only.** The character-count indicator is 8 bits up to version 9 and 16 bits
+ *     from version 10, so stopping here removes a branch and four tables. Version 9 holds 180 bytes;
+ *     the longest URL this ever sees is the dev portal's, around 60. Anything longer returns null
+ *     rather than growing the tables — see `encodeQr`.
+ *
+ * Structure follows ISO/IEC 18004. Every table below is a literal with the spec's own name for it,
+ * and `__tests__/qr.test.ts` checks each one against fixtures generated by the `qrcode` package, so
+ * a transposed digit fails loudly instead of producing a code that scans as garbage.
+ */
+/**
+ * The spec's four penalty rules (8.8.2), summed. Lower is better.
+ *
+ * Scored over the entire symbol including function patterns, as the spec requires — the finders'
+ * own 1:1:3:1:1 ratio is exactly what rule 3 hunts for elsewhere, and excluding them would let a
+ * mask hide a false finder against a real one.
+ */
+export declare function maskPenalty(matrix: boolean[][]): number;
+/**
+ * Encode `text` with an explicitly chosen mask.
+ *
+ * Exported for the fixture tests, which pin the mask so they compare structure — codewords, ECC,
+ * interleaving, function patterns, format bits — rather than a mask heuristic. Callers outside the
+ * tests want `encodeQr`.
+ */
+export declare function encodeQrWithMask(text: string, mask: number): boolean[][] | null;
+/**
+ * Encode `text` as a matrix of modules, row-major, true meaning dark. Null when it does not fit.
+ *
+ * The mask is chosen by the spec's penalty rules. That choice is a legibility heuristic and not a
+ * correctness property — all eight masks produce a valid, scannable symbol, and a decoder reads the
+ * chosen one out of the format information either way.
+ *
+ * There is no quiet zone here: it belongs to whatever draws the symbol, which knows what it is
+ * drawing onto. `qr-terminal.ts` paints its own.
+ */
+export declare function encodeQr(text: string): boolean[][] | null;
+/** The longest text this encoder can hold, in bytes. Exported so a caller can explain a refusal. */
+export declare const MAX_BYTES: number;