novac 2.0.1 → 2.2.0

package/kits/kitqr/kitdef.js

@@ -0,0 +1,637 @@
+// kitqr — novac QR code generation kit
+// Pure JS, no native dependencies.
+// Encodes text/URLs/data → QR matrix → ASCII / Unicode-art / SVG output.
+//
+// Supports QR versions 1-40, error correction L/M/Q/H, byte mode encoding.
+
+'use strict';
+
+// ─── CONSTANTS ────────────────────────────────────────────────────────────────
+
+const EC = { L: 0, M: 1, Q: 2, H: 3 };
+const EC_NAME = ['L', 'M', 'Q', 'H'];
+
+// Number of data codewords per version per EC level (versions 1-10 subset for brevity)
+// Full table: ISO 18004:2015 Table 9
+const DATA_CODEWORDS = [
+  //        L    M    Q    H
+  null,
+  [null, 19,  16,  13,  9 ],  // v1
+  [null, 34,  28,  22,  16],  // v2
+  [null, 55,  44,  34,  26],  // v3
+  [null, 80,  64,  48,  36],  // v4
+  [null, 108, 86,  62,  46],  // v5
+  [null, 136, 108, 76,  60],  // v6
+  [null, 156, 124, 88,  66],  // v7
+  [null, 194, 154, 110, 86],  // v8
+  [null, 232, 182, 132, 100], // v9
+  [null, 274, 216, 154, 122], // v10
+  [null, 324, 254, 180, 140], // v11
+  [null, 370, 290, 206, 158], // v12
+  [null, 428, 334, 244, 180], // v13
+  [null, 461, 365, 261, 197], // v14
+  [null, 523, 415, 295, 223], // v15
+  [null, 589, 453, 325, 253], // v16
+  [null, 647, 507, 367, 283], // v17
+  [null, 721, 563, 397, 313], // v18
+  [null, 795, 627, 445, 341], // v19
+  [null, 861, 669, 485, 385], // v20
+  [null, 932, 714, 512, 406], // v21
+  [null,1006, 782, 568, 442], // v22
+  [null,1094, 860, 614, 464], // v23
+  [null,1174, 914, 664, 514], // v24
+  [null,1276,1000, 718, 538], // v25
+  [null,1370,1062, 754, 596], // v26
+  [null,1468,1128, 808, 628], // v27
+  [null,1531,1193, 871, 661], // v28
+  [null,1631,1267, 911, 701], // v29
+  [null,1735,1373, 985, 745], // v30
+  [null,1843,1455,1033, 793], // v31
+  [null,1955,1541,1115, 845], // v32
+  [null,2071,1631,1171, 901], // v33
+  [null,2191,1725,1231, 961], // v34
+  [null,2306,1812,1286, 986], // v35
+  [null,2434,1914,1354,1054], // v36
+  [null,2566,1992,1426,1096], // v37
+  [null,2702,2102,1502,1142], // v38
+  [null,2812,2216,1582,1222], // v39
+  [null,2956,2334,1666,1276], // v40
+];
+
+// EC codewords per block and block counts — ISO 18004 Table 9 (abbreviated)
+// Format: [ecPerBlock, blocks1, dataPerBlock1, blocks2, dataPerBlock2]
+const EC_BLOCKS = [
+  null,
+  // v1
+  [[7,1,19],[10,1,16],[13,1,13],[17,1,9]],
+  // v2
+  [[10,1,34],[16,1,28],[22,1,22],[28,1,16]],
+  // v3
+  [[15,1,55],[26,1,44],[18,2,17],[22,2,13]],
+  // v4
+  [[20,1,80],[18,2,32],[26,2,24],[16,4,9]],
+  // v5
+  [[26,1,108],[24,2,43],[18,2,15,2,16],[22,2,11,2,12]],
+  // v6
+  [[18,2,68],[16,4,27],[24,4,19],[28,4,15]],
+  // v7
+  [[20,2,78],[18,4,31],[18,2,14,4,15],[26,4,13,1,14]],
+  // v8
+  [[24,2,97],[22,2,38,2,39],[22,4,18,2,19],[26,4,14,2,15]],
+  // v9
+  [[30,2,116],[22,3,36,2,37],[20,4,16,4,17],[24,4,12,4,13]],
+  // v10
+  [[18,2,68,2,69],[26,4,43,1,44],[24,6,19,2,20],[28,6,15,2,16]],
+];
+
+// Alignment pattern positions per version
+const ALIGN_POS = [
+  null,
+  [],        // v1
+  [6,18],    // v2
+  [6,22],    // v3
+  [6,26],    // v4
+  [6,30],    // v5
+  [6,34],    // v6
+  [6,22,38], // v7
+  [6,24,42], // v8
+  [6,26,46], // v9
+  [6,28,50], // v10
+  [6,30,54], // v11
+  [6,32,58], // v12
+  [6,34,62], // v13
+  [6,26,46,66],  // v14
+  [6,26,48,70],  // v15
+  [6,26,50,74],  // v16
+  [6,30,54,78],  // v17
+  [6,30,56,82],  // v18
+  [6,30,58,86],  // v19
+  [6,34,62,90],  // v20
+  [6,28,50,72,94],   // v21
+  [6,26,50,74,98],   // v22
+  [6,30,54,78,102],  // v23
+  [6,28,54,80,106],  // v24
+  [6,32,58,84,110],  // v25
+  [6,30,58,86,114],  // v26
+  [6,34,62,90,118],  // v27
+  [6,26,50,74,98,122],   // v28
+  [6,30,54,78,102,126],  // v29
+  [6,26,52,78,104,130],  // v30
+  [6,30,56,82,108,134],  // v31
+  [6,34,60,86,112,138],  // v32
+  [6,30,58,86,114,142],  // v33
+  [6,34,62,90,118,146],  // v34
+  [6,30,54,82,110,138,166], // v35
+  [6,24,50,76,102,128,154], // v36
+  [6,28,54,80,106,132,158], // v37
+  [6,32,58,84,110,136,162], // v38
+  [6,26,54,82,110,138,166], // v39
+  [6,30,58,86,114,142,170], // v40
+];
+
+// Format information strings (15-bit, pre-computed) — ISO 18004 Table C.1
+const FORMAT_INFO = [
+  // EC L (00)
+  [0x77C4, 0x72F3, 0x7DAA, 0x789D, 0x662F, 0x6318, 0x6C41, 0x6976],
+  // EC M (01)
+  [0x5412, 0x5125, 0x5E7C, 0x5B4B, 0x45F9, 0x40CE, 0x4F97, 0x4AA0],
+  // EC Q (10)
+  [0x355F, 0x3068, 0x3F31, 0x3A06, 0x24B4, 0x2183, 0x2EDA, 0x2BED],
+  // EC H (11)
+  [0x1689, 0x13BE, 0x1CE7, 0x19D0, 0x0762, 0x0255, 0x0D0C, 0x083B],
+];
+
+// Version information strings for v7-v40 — ISO 18004 Table D.1
+const VERSION_INFO = [
+  null,null,null,null,null,null,null,
+  0x07C94, 0x085BC, 0x09A99, 0x0A4D3, 0x0BBF6, 0x0C762, 0x0D847,
+  0x0E60D, 0x0F928, 0x10B78, 0x1145D, 0x12A17, 0x13532, 0x149A6,
+  0x15683, 0x168C9, 0x177EC, 0x18EC4, 0x191E1, 0x1AFAB, 0x1B08E,
+  0x1CC1A, 0x1D33F, 0x1ED75, 0x1F250, 0x209D5, 0x216F0, 0x228BA,
+  0x2379F, 0x24B0B, 0x2542E, 0x26A64, 0x27541, 0x28C69,
+];
+
+// GF(256) log/exp tables for Reed-Solomon
+const GF_EXP = new Uint8Array(512);
+const GF_LOG = new Uint8Array(256);
+(function buildGF() {
+  let x = 1;
+  for (let i = 0; i < 255; i++) {
+    GF_EXP[i] = x;
+    GF_LOG[x] = i;
+    x = (x << 1) ^ (x & 0x80 ? 0x11D : 0);
+  }
+  for (let i = 255; i < 512; i++) GF_EXP[i] = GF_EXP[i - 255];
+})();
+
+function gfMul(a, b) {
+  if (a === 0 || b === 0) return 0;
+  return GF_EXP[GF_LOG[a] + GF_LOG[b]];
+}
+
+function rsGeneratorPoly(degree) {
+  let g = [1];
+  for (let i = 0; i < degree; i++) {
+    const ng = new Array(g.length + 1).fill(0);
+    for (let j = 0; j < g.length; j++) {
+      ng[j] ^= gfMul(g[j], GF_EXP[i]);
+      ng[j + 1] ^= g[j];
+    }
+    g = ng;
+  }
+  return g;
+}
+
+function rsEncode(data, ecLen) {
+  const gen = rsGeneratorPoly(ecLen);
+  const msg = [...data, ...new Array(ecLen).fill(0)];
+  for (let i = 0; i < data.length; i++) {
+    const coeff = msg[i];
+    if (coeff === 0) continue;
+    for (let j = 0; j < gen.length; j++) {
+      msg[i + j] ^= gfMul(gen[j], coeff);
+    }
+  }
+  return msg.slice(data.length);
+}
+
+// ─── ENCODING ─────────────────────────────────────────────────────────────────
+
+function encodeData(text, version, ecLevel) {
+  const bytes = Array.from(Buffer.from(text, 'utf8'));
+  const charCount = bytes.length;
+  const totalBits = DATA_CODEWORDS[version][ecLevel] * 8;
+
+  const bits = [];
+  const push = (val, len) => {
+    for (let i = len - 1; i >= 0; i--) bits.push((val >> i) & 1);
+  };
+
+  // Mode indicator: byte mode = 0100
+  push(0b0100, 4);
+  // Character count: 8 bits for v1-9, 16 for v10-26, 16 for v27-40
+  const ccBits = version < 10 ? 8 : 16;
+  push(charCount, ccBits);
+  // Data
+  for (const b of bytes) push(b, 8);
+  // Terminator
+  const term = Math.min(4, totalBits - bits.length);
+  for (let i = 0; i < term; i++) bits.push(0);
+  // Byte-align
+  while (bits.length % 8 !== 0) bits.push(0);
+  // Pad codewords
+  const padWords = [0xEC, 0x11];
+  let pi = 0;
+  while (bits.length < totalBits) { push(padWords[pi++ % 2], 8); }
+
+  // Convert to bytes
+  const codewords = [];
+  for (let i = 0; i < bits.length; i += 8) {
+    let byte = 0;
+    for (let j = 0; j < 8; j++) byte = (byte << 1) | bits[i + j];
+    codewords.push(byte);
+  }
+  return codewords;
+}
+
+function interleaveBlocks(codewords, version, ecLevel) {
+  const spec = EC_BLOCKS[version]?.[ecLevel];
+  if (!spec) return codewords; // fallback
+
+  const [ecPerBlock, b1count, b1data, b2count = 0, b2data = 0] = spec;
+
+  const blocks = [];
+  let pos = 0;
+
+  const makeBlocks = (count, dataLen) => {
+    for (let i = 0; i < count; i++) {
+      const data = codewords.slice(pos, pos + dataLen);
+      pos += dataLen;
+      const ec = rsEncode(data, ecPerBlock);
+      blocks.push({ data, ec });
+    }
+  };
+
+  makeBlocks(b1count, b1data);
+  if (b2count) makeBlocks(b2count, b2data);
+
+  const result = [];
+  const maxData = Math.max(b1data, b2data || 0);
+  for (let i = 0; i < maxData; i++)
+    for (const b of blocks) if (i < b.data.length) result.push(b.data[i]);
+  for (let i = 0; i < ecPerBlock; i++)
+    for (const b of blocks) result.push(b.ec[i]);
+
+  return result;
+}
+
+// ─── MATRIX ───────────────────────────────────────────────────────────────────
+
+const DARK = 1, LIGHT = 0, RESERVED = 2;
+
+function makeMatrix(size) {
+  return Array.from({ length: size }, () => new Int8Array(size).fill(-1));
+}
+
+function setFinderPattern(matrix, row, col) {
+  for (let r = -1; r <= 7; r++) {
+    for (let c = -1; c <= 7; c++) {
+      const mr = row + r, mc = col + c;
+      if (mr < 0 || mr >= matrix.length || mc < 0 || mc >= matrix.length) continue;
+      const inModule = r >= 0 && r <= 6 && c >= 0 && c <= 6;
+      const onBorder = r === 0 || r === 6 || c === 0 || c === 6;
+      const inInner  = r >= 2 && r <= 4 && c >= 2 && c <= 4;
+      matrix[mr][mc] = inModule && (onBorder || inInner) ? DARK : LIGHT;
+    }
+  }
+}
+
+function setTimingPattern(matrix, size) {
+  for (let i = 8; i < size - 8; i++) {
+    const v = i % 2 === 0 ? DARK : LIGHT;
+    matrix[6][i] = v;
+    matrix[i][6] = v;
+  }
+}
+
+function setAlignmentPatterns(matrix, version) {
+  const pos = ALIGN_POS[version] || [];
+  for (const r of pos) {
+    for (const c of pos) {
+      if (matrix[r][c] !== -1) continue;
+      for (let dr = -2; dr <= 2; dr++) {
+        for (let dc = -2; dc <= 2; dc++) {
+          const onEdge = Math.abs(dr) === 2 || Math.abs(dc) === 2;
+          const center = dr === 0 && dc === 0;
+          matrix[r + dr][c + dc] = onEdge || center ? DARK : LIGHT;
+        }
+      }
+    }
+  }
+}
+
+function reserveFormatArea(matrix, size) {
+  // Reserve format info areas
+  for (let i = 0; i <= 8; i++) {
+    if (matrix[8][i] === -1) matrix[8][i] = RESERVED;
+    if (matrix[i][8] === -1) matrix[i][8] = RESERVED;
+  }
+  for (let i = size - 8; i < size; i++) {
+    if (matrix[8][i] === -1) matrix[8][i] = RESERVED;
+    if (matrix[i][8] === -1) matrix[i][8] = RESERVED;
+  }
+  // Dark module
+  matrix[size - 8][8] = DARK;
+}
+
+function reserveVersionArea(matrix, size, version) {
+  if (version < 7) return;
+  for (let i = 0; i < 6; i++) {
+    for (let j = size - 11; j < size - 8; j++) {
+      matrix[i][j] = RESERVED;
+      matrix[j][i] = RESERVED;
+    }
+  }
+}
+
+function placeData(matrix, size, data) {
+  let bitIdx = 0;
+  const bits = [];
+  for (const byte of data) for (let i = 7; i >= 0; i--) bits.push((byte >> i) & 1);
+
+  let up = true;
+  for (let col = size - 1; col >= 1; col -= 2) {
+    if (col === 6) col--;
+    for (let rowOff = 0; rowOff < size; rowOff++) {
+      const row = up ? size - 1 - rowOff : rowOff;
+      for (let dc = 0; dc < 2; dc++) {
+        const c = col - dc;
+        if (matrix[row][c] !== -1) continue;
+        matrix[row][c] = bitIdx < bits.length ? bits[bitIdx++] : LIGHT;
+      }
+    }
+    up = !up;
+  }
+}
+
+// Mask patterns
+const MASKS = [
+  (r, c) => (r + c) % 2 === 0,
+  (r, _) => r % 2 === 0,
+  (_, c) => c % 3 === 0,
+  (r, c) => (r + c) % 3 === 0,
+  (r, c) => (Math.floor(r / 2) + Math.floor(c / 3)) % 2 === 0,
+  (r, c) => (r * c) % 2 + (r * c) % 3 === 0,
+  (r, c) => ((r * c) % 2 + (r * c) % 3) % 2 === 0,
+  (r, c) => ((r + c) % 2 + (r * c) % 3) % 2 === 0,
+];
+
+function applyMask(matrix, size, maskIdx) {
+  const fn = MASKS[maskIdx];
+  const m  = matrix.map(r => Int8Array.from(r));
+  for (let r = 0; r < size; r++)
+    for (let c = 0; c < size; c++)
+      if (m[r][c] !== RESERVED && fn(r, c)) m[r][c] ^= 1;
+  return m;
+}
+
+function penaltyScore(matrix, size) {
+  let score = 0;
+  // Rule 1: 5+ in a row
+  for (let r = 0; r < size; r++) {
+    for (let c = 0; c < size; ) {
+      const v = matrix[r][c];
+      let run = 1;
+      while (c + run < size && matrix[r][c + run] === v) run++;
+      if (run >= 5) score += 3 + (run - 5);
+      c += run;
+    }
+  }
+  for (let c = 0; c < size; c++) {
+    for (let r = 0; r < size; ) {
+      const v = matrix[r][c];
+      let run = 1;
+      while (r + run < size && matrix[r + run][c] === v) run++;
+      if (run >= 5) score += 3 + (run - 5);
+      r += run;
+    }
+  }
+  // Rule 2: 2×2 blocks
+  for (let r = 0; r < size - 1; r++)
+    for (let c = 0; c < size - 1; c++)
+      if (matrix[r][c] === matrix[r+1][c] &&
+          matrix[r][c] === matrix[r][c+1] &&
+          matrix[r][c] === matrix[r+1][c+1]) score += 3;
+  // Rule 3: finder-like patterns
+  const pat1 = [1,0,1,1,1,0,1,0,0,0,0];
+  const pat2 = [0,0,0,0,1,0,1,1,1,0,1];
+  const check = (arr) => {
+    for (let i = 0; i <= arr.length - 11; i++) {
+      if (pat1.every((v,j) => arr[i+j] === v) || pat2.every((v,j) => arr[i+j] === v)) score += 40;
+    }
+  };
+  for (let r = 0; r < size; r++) check(Array.from(matrix[r]));
+  for (let c = 0; c < size; c++) check(Array.from({ length: size }, (_,r) => matrix[r][c]));
+  // Rule 4: dark module ratio
+  let dark = 0;
+  for (let r = 0; r < size; r++) for (let c = 0; c < size; c++) if (matrix[r][c] === DARK) dark++;
+  const pct = dark / (size * size) * 100;
+  score += Math.abs(Math.floor(pct / 5) * 5 - 50) / 5 * 10 +
+           Math.abs(Math.ceil(pct / 5) * 5 - 50) / 5 * 10;
+  return score;
+}
+
+function writeFormatInfo(matrix, size, ecLevel, maskIdx) {
+  const info = FORMAT_INFO[ecLevel][maskIdx];
+  const bits = [];
+  for (let i = 14; i >= 0; i--) bits.push((info >> i) & 1);
+
+  // Around top-left finder
+  let bi = 0;
+  for (let i = 0; i <= 5; i++) matrix[8][i] = bits[bi++];
+  matrix[8][7] = bits[bi++];
+  matrix[8][8] = bits[bi++];
+  matrix[7][8] = bits[bi++];
+  for (let i = 5; i >= 0; i--) matrix[i][8] = bits[bi++];
+
+  // Bottom-left and top-right
+  bi = 0;
+  for (let i = size - 1; i >= size - 8; i--) matrix[i][8] = bits[bi++];
+  for (let i = size - 8; i < size; i++) matrix[8][i] = bits[bi++];
+}
+
+function writeVersionInfo(matrix, size, version) {
+  if (version < 7) return;
+  const info = VERSION_INFO[version];
+  let bi = 17;
+  for (let i = 0; i < 6; i++) {
+    for (let j = 0; j < 3; j++) {
+      const bit = (info >> bi--) & 1;
+      matrix[i][size - 11 + j] = bit;
+      matrix[size - 11 + j][i] = bit;
+    }
+  }
+}
+
+// ─── MAIN ENCODE ──────────────────────────────────────────────────────────────
+
+function encode(text, opts = {}) {
+  const ecLevel = typeof opts.ec === 'string' ? EC[opts.ec.toUpperCase()] ?? EC.M : (opts.ec ?? EC.M);
+  const quiet   = opts.quiet ?? 4;
+
+  // Find minimum version
+  const bytes = Buffer.from(text, 'utf8');
+  let version = opts.version ?? 0;
+
+  if (!version) {
+    // byte mode char count overhead: mode(4) + cc(8 for v1-9, 16 for v10+) + data
+    for (let v = 1; v <= 40; v++) {
+      const ccBits = v < 10 ? 8 : 16;
+      const needed = Math.ceil((4 + ccBits + bytes.length * 8) / 8);
+      if (needed <= DATA_CODEWORDS[v][ecLevel]) { version = v; break; }
+    }
+  }
+  if (!version) throw new Error('Data too large for QR code (max version 40)');
+
+  const size = version * 4 + 17;
+
+  // Build codewords
+  const dataWords  = encodeData(text, version, ecLevel);
+  const finalWords = interleaveBlocks(dataWords, version, ecLevel);
+
+  // Build matrix
+  const matrix = makeMatrix(size);
+  setFinderPattern(matrix, 0, 0);
+  setFinderPattern(matrix, 0, size - 7);
+  setFinderPattern(matrix, size - 7, 0);
+  setTimingPattern(matrix, size);
+  setAlignmentPatterns(matrix, version);
+  reserveFormatArea(matrix, size);
+  reserveVersionArea(matrix, size, version);
+  placeData(matrix, size, finalWords);
+  writeVersionInfo(matrix, size, version);
+
+  // Choose best mask
+  let bestMask = 0, bestScore = Infinity;
+  for (let m = 0; m < 8; m++) {
+    const masked = applyMask(matrix, size, m);
+    writeFormatInfo(masked, size, ecLevel, m);
+    const s = penaltyScore(masked, size);
+    if (s < bestScore) { bestScore = s; bestMask = m; }
+  }
+
+  const finalMatrix = applyMask(matrix, size, bestMask);
+  writeFormatInfo(finalMatrix, size, ecLevel, bestMask);
+
+  return {
+    matrix:  finalMatrix,
+    size,
+    version,
+    ec:      EC_NAME[ecLevel],
+    mask:    bestMask,
+    quiet,
+  };
+}
+
+// ─── RENDERERS ────────────────────────────────────────────────────────────────
+
+function toAscii(qr, opts = {}) {
+  const dark  = opts.dark  ?? '##';
+  const light = opts.light ?? '  ';
+  const q     = qr.quiet;
+  const pad   = light.repeat(qr.size + q * 2);
+  const lines = [pad.repeat ? pad : pad];
+
+  const emptyRow = light.repeat(qr.size + q * 2);
+  for (let i = 0; i < q; i++) lines.push(emptyRow);
+
+  for (let r = 0; r < qr.size; r++) {
+    let line = light.repeat(q);
+    for (let c = 0; c < qr.size; c++) {
+      line += qr.matrix[r][c] === DARK ? dark : light;
+    }
+    line += light.repeat(q);
+    lines.push(line);
+  }
+  for (let i = 0; i < q; i++) lines.push(emptyRow);
+  return lines.join('\n');
+}
+
+function toUnicode(qr) {
+  // Uses half-block characters: each char covers 2 rows
+  const q    = qr.quiet;
+  const wide = qr.size + q * 2;
+  const lines = [];
+  const get  = (r, c) => {
+    const mr = r - q, mc = c - q;
+    if (mr < 0 || mr >= qr.size || mc < 0 || mc >= qr.size) return false;
+    return qr.matrix[mr][mc] === DARK;
+  };
+  for (let r = 0; r < qr.size + q * 2; r += 2) {
+    let line = '';
+    for (let c = 0; c < wide; c++) {
+      const top = get(r, c), bot = get(r + 1, c);
+      if (top && bot)   line += '█';
+      else if (top)     line += '▀';
+      else if (bot)     line += '▄';
+      else              line += ' ';
+    }
+    lines.push(line);
+  }
+  return lines.join('\n');
+}
+
+function toSVG(qr, opts = {}) {
+  const moduleSize = opts.moduleSize ?? 4;
+  const dark       = opts.dark       ?? '#000000';
+  const light      = opts.light      ?? '#ffffff';
+  const q          = qr.quiet;
+  const total      = (qr.size + q * 2) * moduleSize;
+
+  const rects = [];
+  for (let r = 0; r < qr.size; r++) {
+    for (let c = 0; c < qr.size; c++) {
+      if (qr.matrix[r][c] === DARK) {
+        const x = (c + q) * moduleSize;
+        const y = (r + q) * moduleSize;
+        rects.push(`<rect x="${x}" y="${y}" width="${moduleSize}" height="${moduleSize}" fill="${dark}"/>`);
+      }
+    }
+  }
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" version="1.1"
+     viewBox="0 0 ${total} ${total}" width="${total}" height="${total}">
+  <rect width="${total}" height="${total}" fill="${light}"/>
+  ${rects.join('\n  ')}
+</svg>`;
+}
+
+function toMatrix(qr) {
+  // Returns a plain 2D array of booleans (true=dark)
+  return qr.matrix.map(row => Array.from(row).map(v => v === DARK));
+}
+
+function toDataURL(qr, opts = {}) {
+  // Returns a data URL with SVG content (base64)
+  const svg = toSVG(qr, opts);
+  return 'data:image/svg+xml;base64,' + Buffer.from(svg).toString('base64');
+}
+
+// ─── HIGH-LEVEL API ───────────────────────────────────────────────────────────
+
+function qr(text, opts = {}) {
+  const encoded = encode(text, opts);
+  const format  = opts.format ?? 'unicode';
+  switch (format) {
+    case 'ascii':   return toAscii(encoded, opts);
+    case 'unicode': return toUnicode(encoded);
+    case 'svg':     return toSVG(encoded, opts);
+    case 'matrix':  return toMatrix(encoded);
+    case 'dataurl': return toDataURL(encoded, opts);
+    case 'raw':     return encoded;
+    default: throw new Error(`Unknown format: ${format}. Use 'ascii', 'unicode', 'svg', 'matrix', 'dataurl', or 'raw'.`);
+  }
+}
+
+// ─── EXPORTS ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+    // High-level: encode and render in one call
+    qr,
+
+    // Low-level: encode only → returns raw QR object { matrix, size, version, ec, mask }
+    encode,
+
+    // Renderers (accept raw QR object)
+    toAscii,
+    toUnicode,
+    toSVG,
+    toMatrix,
+    toDataURL,
+
+    // EC level constants
+    EC,
+  }
+};