@mostajs/qrpanel 0.5.0 → 0.6.0

package/src/qr-png.js

@@ -0,0 +1,40 @@
+// @mostajs/qrpanel — sortie PNG (data:URL) d'un QR. Author: Dr Hamid MADANI <drmdh@msn.com>
+// Pour les contextes où le SVG inline est bloqué (emails : billets, magic-link). Node (node:zlib pour l'IDAT).
+import zlib from 'node:zlib';
+import { qrMatrix } from './qr-svg.js';
+
+const CRC = (() => { const t = new Uint32Array(256); for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = (c & 1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1); t[n] = c >>> 0; } return t; })();
+const crc32 = (b) => { let c = 0xFFFFFFFF; for (let i = 0; i < b.length; i++) c = CRC[(c ^ b[i]) & 0xFF] ^ (c >>> 8); return (c ^ 0xFFFFFFFF) >>> 0; };
+const u32 = (n) => Uint8Array.of((n >>> 24) & 255, (n >>> 16) & 255, (n >>> 8) & 255, n & 255);
+const cat = (...a) => { const o = new Uint8Array(a.reduce((s, x) => s + x.length, 0)); let p = 0; for (const x of a) { o.set(x, p); p += x.length; } return o; };
+const chunk = (type, data) => { const body = cat(Uint8Array.from([...type].map((c) => c.charCodeAt(0))), data); return cat(u32(data.length), body, u32(crc32(body))); };
+const toB64 = (bytes) => (typeof Buffer !== 'undefined' ? Buffer.from(bytes).toString('base64') : btoa(String.fromCharCode(...bytes)));
+
+/** QR en PNG (niveaux de gris) → data:image/png;base64,…  { scale=6, margin=4 }. */
+export function qrPng(text, { scale = 6, margin = 4 } = {}) {
+  const { matrix, size } = qrMatrix(text);
+  const dim = (size + margin * 2) * scale;
+  const stride = dim + 1; // 1 octet de filtre par ligne
+  const raw = new Uint8Array(stride * dim);
+  for (let y = 0; y < dim; y++) {
+    raw[y * stride] = 0; // filtre None
+    const my = Math.floor(y / scale) - margin;
+    for (let x = 0; x < dim; x++) {
+      const mx = Math.floor(x / scale) - margin;
+      const dark = my >= 0 && my < size && mx >= 0 && mx < size && matrix[my][mx];
+      raw[y * stride + 1 + x] = dark ? 0 : 255;
+    }
+  }
+  const sig = Uint8Array.of(137, 80, 78, 71, 13, 10, 26, 10);
+  const ihdr = cat(u32(dim), u32(dim), Uint8Array.of(8, 0, 0, 0, 0)); // 8 bits, grayscale
+  const idat = new Uint8Array(zlib.deflateSync(raw));
+  const png = cat(sig, chunk('IHDR', ihdr), chunk('IDAT', idat), chunk('IEND', new Uint8Array(0)));
+  return 'data:image/png;base64,' + toB64(png);
+}
+
+const _esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/** Figure PNG d'un QR avec légende (pendant de qrLive pour le rendu PNG : billets/badges imprimables). { scale=5, margin=2, maxWidth=240 }. */
+export function qrPngFigure(data, caption = '', { scale = 5, margin = 2, maxWidth = 240 } = {}) {
+  return `<figure style="margin:0;text-align:center"><img src="${qrPng(data, { scale, margin })}" alt="QR" style="max-width:${maxWidth}px;width:60vw;image-rendering:pixelated">${caption ? `<figcaption style="font-size:12px;margin-top:4px;opacity:.7">${_esc(caption)}</figcaption>` : ''}</figure>`;
+}

package/src/qr-svg.js

@@ -0,0 +1,185 @@
+// @mostajs/qrpanel/qr-svg — encodeur QR Code ZÉRO-DÉPENDANCE → SVG (server-side, pas de natif, pas de npm). Author: Dr Hamid MADANI <drmdh@msn.com>
+// Complète qrpanel (qr-image = navigateur via `qrcode` ; server.js = @resvg natif) par un encodeur PUR JS server-side, idéal apps zéro-dép.
+// Modes numérique & octet (byte/UTF-8), niveau de correction M, versions 1→10 (auto). Reed-Solomon GF(256), 8 masques + pénalité.
+// Vérifié contre le vecteur de référence publié (« 01234567 », v1-M → 10 mots de code EC connus). Sortie : matrice booléenne + SVG.
+
+// ── GF(256) — corps de Galois, primitif 0x11d (x^8+x^4+x^3+x^2+1). ──
+const EXP = new Array(512), LOG = new Array(256);
+(() => { let x = 1; for (let i = 0; i < 255; i++) { EXP[i] = x; LOG[x] = i; x <<= 1; if (x & 0x100) x ^= 0x11d; } for (let i = 255; i < 512; i++) EXP[i] = EXP[i - 255]; })();
+const gmul = (a, b) => (a === 0 || b === 0) ? 0 : EXP[LOG[a] + LOG[b]];
+
+// Polynôme générateur Reed-Solomon de degré `n`.
+function rsGenPoly(n) {
+  let g = [1];
+  for (let i = 0; i < n; i++) { const ng = new Array(g.length + 1).fill(0); for (let j = 0; j < g.length; j++) { ng[j] ^= gmul(g[j], 1); ng[j + 1] ^= gmul(g[j], EXP[i]); } g = ng; }
+  return g;
+}
+// Mots de code de correction d'erreur pour `data` (octets) avec `ecLen` symboles.
+function rsEncode(data, ecLen) {
+  const gen = rsGenPoly(ecLen); const res = new Array(ecLen).fill(0);   // gen a ecLen+1 coeffs (gen[0]=1, ignoré dans la division)
+  for (const d of data) { const factor = d ^ res[0]; res.shift(); res.push(0); if (factor !== 0) for (let i = 0; i < ecLen; i++) res[i] ^= gmul(gen[i + 1], factor); }
+  return res;
+}
+
+// ── Tables niveau M, versions 1→10 : [totalDataCodewords, ecPerBlock, [ [nbBlocks, dataPerBlock], ... ] ]. ──
+const VERSIONS_M = {
+  1: [16, 10, [[1, 16]]], 2: [28, 16, [[1, 28]]], 3: [44, 26, [[1, 44]]], 4: [64, 18, [[2, 32]]],
+  5: [86, 24, [[2, 43]]], 6: [108, 16, [[4, 27]]], 7: [124, 18, [[4, 31]]], 8: [154, 22, [[2, 38], [2, 39]]],
+  9: [182, 22, [[3, 36], [2, 37]]], 10: [216, 26, [[4, 43], [1, 44]]],
+};
+// Positions des motifs d'alignement (centres) par version.
+const ALIGN = { 1: [], 2: [6, 18], 3: [6, 22], 4: [6, 26], 5: [6, 30], 6: [6, 34], 7: [6, 22, 38], 8: [6, 24, 42], 9: [6, 26, 46], 10: [6, 28, 50] };
+const sizeOf = (v) => 17 + 4 * v;
+
+const isNumeric = (s) => /^[0-9]+$/.test(s);
+
+// ── Encodage des données (bitstream) selon le mode. ──
+function encodeData(text, version, totalDataCw) {
+  const bits = [];
+  const push = (val, len) => { for (let i = len - 1; i >= 0; i--) bits.push((val >> i) & 1); };
+  if (isNumeric(text)) {
+    push(0b0001, 4);                                   // mode numérique
+    push(text.length, version < 10 ? 10 : 12);
+    for (let i = 0; i < text.length; i += 3) { const chunk = text.substr(i, 3); push(parseInt(chunk, 10), chunk.length === 3 ? 10 : chunk.length === 2 ? 7 : 4); }
+  } else {
+    const bytes = Buffer.from(text, 'utf8');
+    push(0b0100, 4);                                   // mode octet
+    push(bytes.length, version < 10 ? 8 : 16);
+    for (const b of bytes) push(b, 8);
+  }
+  const cap = totalDataCw * 8;
+  for (let i = 0; i < 4 && bits.length < cap; i++) bits.push(0);   // terminateur
+  while (bits.length % 8 !== 0) bits.push(0);                       // alignement octet
+  const pads = [0xec, 0x11]; let p = 0;
+  while (bits.length < cap) { push(pads[p % 2], 8); p++; }
+  const cw = []; for (let i = 0; i < bits.length; i += 8) { let b = 0; for (let j = 0; j < 8; j++) b = (b << 1) | bits[i + j]; cw.push(b); }
+  return cw;
+}
+
+// Choisit la plus petite version (≤10) qui contient `text`.
+function pickVersion(text) {
+  const len = isNumeric(text) ? null : Buffer.from(text, 'utf8').length;
+  for (let v = 1; v <= 10; v++) {
+    const totalData = VERSIONS_M[v][0];
+    // estimation grossière de capacité : entête (~4 + count bits) puis données
+    const headerBits = 4 + (v < 10 ? (isNumeric(text) ? 10 : 8) : (isNumeric(text) ? 12 : 16));
+    const dataBits = isNumeric(text) ? Math.ceil(text.length / 3) * 10 : (len * 8);
+    if (headerBits + dataBits <= totalData * 8) return v;
+  }
+  throw new Error('contenu trop long pour QR v≤10 (raccourcir l\'URL/jeton)');
+}
+
+// Entrelace données + EC par blocs (spec QR).
+function interleave(dataCw, version) {
+  const [, ecLen, groups] = VERSIONS_M[version];
+  const blocks = []; let idx = 0;
+  for (const [nb, dpb] of groups) for (let i = 0; i < nb; i++) { const d = dataCw.slice(idx, idx + dpb); idx += dpb; blocks.push({ d, e: rsEncode(d, ecLen) }); }
+  const maxD = Math.max(...blocks.map((b) => b.d.length));
+  const out = [];
+  for (let i = 0; i < maxD; i++) for (const b of blocks) if (i < b.d.length) out.push(b.d[i]);
+  for (let i = 0; i < ecLen; i++) for (const b of blocks) out.push(b.e[i]);
+  return out;
+}
+
+// ── Matrice : motifs de repérage, séparateurs, timing, alignement, module sombre, réservé format. ──
+// Information de version (18 bits BCH) — OBLIGATOIRE dès la version 7. Sans elle, les scanners rejettent le QR.
+const VERSION_INFO = { 7: 0x07C94, 8: 0x085BC, 9: 0x09A99, 10: 0x0A4D3 };
+
+function buildMatrix(version) {
+  const n = sizeOf(version);
+  const m = Array.from({ length: n }, () => new Array(n).fill(null));   // null = libre
+  const fn = Array.from({ length: n }, () => new Array(n).fill(false)); // true = fonction (non masquable)
+  const set = (r, c, v) => { m[r][c] = v ? 1 : 0; fn[r][c] = true; };
+  const finder = (r, c) => { for (let i = -1; i <= 7; i++) for (let j = -1; j <= 7; j++) { const rr = r + i, cc = c + j; if (rr < 0 || rr >= n || cc < 0 || cc >= n) continue; const inb = i >= 0 && i <= 6 && j >= 0 && j <= 6; const ring = i === 0 || i === 6 || j === 0 || j === 6; const core = i >= 2 && i <= 4 && j >= 2 && j <= 4; set(rr, cc, inb && (ring || core)); } };
+  finder(0, 0); finder(0, n - 7); finder(n - 7, 0);
+  for (let i = 0; i < n; i++) { if (m[6][i] === null) set(6, i, i % 2 === 0); if (m[i][6] === null) set(i, 6, i % 2 === 0); }   // timing
+  const ac = ALIGN[version];
+  for (const r of ac) for (const c of ac) { if ((r <= 7 && c <= 7) || (r <= 7 && c >= n - 8) || (r >= n - 8 && c <= 7)) continue; for (let i = -2; i <= 2; i++) for (let j = -2; j <= 2; j++) set(r + i, c + j, Math.max(Math.abs(i), Math.abs(j)) !== 1); }
+  set(n - 8, 8, 1);   // module sombre
+  // Réserve les zones d'info de format (sans valeur définitive) → marquées fonction.
+  for (let i = 0; i < 9; i++) { if (m[8][i] === null) { m[8][i] = 0; fn[8][i] = true; } if (m[i][8] === null) { m[i][8] = 0; fn[i][8] = true; } }
+  for (let i = 0; i < 8; i++) { if (m[8][n - 1 - i] === null) { m[8][n - 1 - i] = 0; fn[8][n - 1 - i] = true; } if (m[n - 1 - i][8] === null) { m[n - 1 - i][8] = 0; fn[n - 1 - i][8] = true; } }
+  // Information de version (v≥7) : 18 bits fixes, deux blocs 3×6 près des viseurs haut-droit et bas-gauche.
+  if (version >= 7) { const vi = VERSION_INFO[version]; for (let i = 0; i < 18; i++) { const bit = (vi >> i) & 1; const a = n - 11 + (i % 3), b = Math.floor(i / 3); set(b, a, bit); set(a, b, bit); } }
+  return { m, fn, n };
+}
+
+// Place le bitstream en zigzag (colonnes de 2, de droite à gauche, en sautant la colonne 6).
+function placeData(m, fn, n, bytes) {
+  let bitIdx = 0; const bitsArr = []; for (const b of bytes) for (let i = 7; i >= 0; i--) bitsArr.push((b >> i) & 1);
+  let up = true;
+  for (let col = n - 1; col > 0; col -= 2) {
+    if (col === 6) col--;
+    for (let k = 0; k < n; k++) { const row = up ? n - 1 - k : k; for (const c of [col, col - 1]) { if (!fn[row][c]) { m[row][c] = bitIdx < bitsArr.length ? bitsArr[bitIdx] : 0; bitIdx++; } } }
+    up = !up;
+  }
+}
+
+const MASKS = [
+  (r, c) => (r + c) % 2 === 0, (r) => r % 2 === 0, (r, 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(m, fn, n, maskFn) { const o = m.map((row) => row.slice()); for (let r = 0; r < n; r++) for (let c = 0; c < n; c++) if (!fn[r][c] && maskFn(r, c)) o[r][c] ^= 1; return o; }
+
+// Info de format (niveau M = bits 00) + masque → 15 bits BCH, placée aux deux emplacements.
+function placeFormat(m, n, maskId) {
+  const data = (0b00 << 3) | maskId; let bch = data << 10;
+  for (let i = 14; i >= 10; i--) if ((bch >> i) & 1) bch ^= 0b10100110111 << (i - 10);
+  const bits = (((data << 10) | bch) ^ 0b101010000010010);
+  const get = (i) => (bits >> i) & 1;
+  // 1ʳᵉ copie (autour du viseur haut-gauche) : bits 0-7 → colonne 8 (haut), bits 8-14 → ligne 8 (gauche). Ordre du SPEC (ISO 18004).
+  for (let i = 0; i <= 5; i++) m[i][8] = get(i);
+  m[7][8] = get(6); m[8][8] = get(7); m[8][7] = get(8);
+  for (let i = 9; i <= 14; i++) m[8][14 - i] = get(i);
+  // 2ᵉ copie : bits 0-7 → ligne 8 (droite), bits 8-14 → colonne 8 (bas).
+  for (let i = 0; i <= 7; i++) m[8][n - 1 - i] = get(i);
+  for (let i = 8; i <= 14; i++) m[n - 15 + i][8] = get(i);
+}
+
+function penalty(m, n) {
+  let p = 0;
+  for (let r = 0; r < n; r++) for (const line of [m[r], m.map((x) => x[r])]) { let run = 1; for (let c = 1; c < n; c++) { if (line[c] === line[c - 1]) { run++; if (run === 5) p += 3; else if (run > 5) p++; } else run = 1; } }
+  for (let r = 0; r < n - 1; r++) for (let c = 0; c < n - 1; c++) if (m[r][c] === m[r][c + 1] && m[r][c] === m[r + 1][c] && m[r][c] === m[r + 1][c + 1]) p += 3;
+  let dark = 0; for (let r = 0; r < n; r++) for (let c = 0; c < n; c++) dark += m[r][c]; const ratio = (dark * 100) / (n * n); p += Math.floor(Math.abs(ratio - 50) / 5) * 10;
+  return p;
+}
+
+/** Encode `text` en matrice QR (booléens true=module sombre). Niveau M, version auto ≤10. */
+export function qrMatrix(text) {
+  const version = pickVersion(text);
+  const totalData = VERSIONS_M[version][0];
+  const dataCw = encodeData(text, version, totalData);
+  const finalCw = interleave(dataCw, version);
+  const { m, fn, n } = buildMatrix(version);
+  placeData(m, fn, n, finalCw);
+  let best = null, bestScore = Infinity, bestMask = 0;
+  for (let mask = 0; mask < 8; mask++) { const cand = applyMask(m, fn, n, MASKS[mask]); placeFormat(cand, n, mask); const s = penalty(cand, n); if (s < bestScore) { bestScore = s; best = cand; bestMask = mask; } }
+  return { matrix: best.map((row) => row.map((v) => v === 1)), size: n, version, mask: bestMask };
+}
+
+/** Rend `text` en SVG QR (scannable). `scale` px/module, `margin` modules de zone calme. */
+export function qrSvg(text, { scale = 4, margin = 4, dark = '#000', light = '#fff' } = {}) {
+  const { matrix, size } = qrMatrix(text);
+  const dim = (size + margin * 2) * scale;
+  let rects = '';
+  for (let r = 0; r < size; r++) for (let c = 0; c < size; c++) if (matrix[r][c]) rects += `<rect x="${(c + margin) * scale}" y="${(r + margin) * scale}" width="${scale}" height="${scale}"/>`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${dim}" height="${dim}" viewBox="0 0 ${dim} ${dim}" shape-rendering="crispEdges" role="img" aria-label="QR code"><rect width="${dim}" height="${dim}" fill="${light}"/><g fill="${dark}">${rects}</g></svg>`;
+}
+
+const _esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+/**
+ * Figure QR « scannable à l'écran » : SVG GROS (scale élevé + quiet zone large) + légende, dans un conteneur responsive.
+ * Pensé pour un QR qu'on affiche pour être SCANNÉ (plateau live, billet, lien public) — pas une vignette.
+ * Garde des URLs COURTES (≤ ~84 octets / version 6) : l'encodeur ne pose pas les « version information » des versions ≥ 7.
+ *   qrLive(data, caption?, { scale=6, margin=3, maxWidth=240, dark, light }?)
+ */
+export function qrLive(data, caption = '', { scale = 6, margin = 3, maxWidth = 240, dark, light } = {}) {
+  const svg = qrSvg(data, { scale, margin, ...(dark ? { dark } : {}), ...(light ? { light } : {}) });
+  return `<figure style="margin:0;text-align:center"><div style="max-width:${maxWidth}px;margin:auto">${svg}</div>${caption ? `<figcaption style="font-size:12px;margin-top:2px;opacity:.7">${_esc(caption)}</figcaption>` : ''}</figure>`;
+}
+
+// Exposés pour les tests (vérification contre le vecteur de référence publié).
+export const _internal = { rsEncode, encodeData, interleave, VERSIONS_M };
+export default { qrMatrix, qrSvg, qrLive };

package/src/server.ts

@@ -0,0 +1,212 @@
+// @mostajs/qrpanel/server — server-side QR generation (Node)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Wrap minimaliste de la lib `qrcode` (npm) + extension thématique
+// pilotée par .qrconfig.json (chargée à process.cwd() au runtime, cache
+// invalidé par mtime).
+//
+// Cross-OS natif (Linux, macOS, Windows) — qrcode est pure-JS, et la
+// rasterization PNG composite passe par @resvg/resvg-js (rust prebuilt
+// binaries cross-OS, pas de chromium ni puppeteer).
+//
+// API legacy 100% rétro-compatible :
+//   - generateQrPng/Svg/DataUrl(text, opts) marchent comme en 0.2.x
+//     si .qrconfig.json est absent ET opts.genimage non-précisé.
+//   - Le master toggle genimage=false (config ou opts) court-circuite
+//     toute la chaîne thématique.
+
+import QRCode from 'qrcode'
+import { signInviteToken } from '@mostajs/auth/lib/invite-token'
+import {
+  loadQrConfig, type QrConfigDefaults,
+} from './config.js'
+import {
+  composeThemedSvg, composeThemedPng, composeThemedDataUrl, mergeComposeOpts,
+  type ComposeOptions,
+} from './composer.js'
+import type { ThemeKey } from './themes.js'
+
+// ─── Public types ──────────────────────────────────────────────────
+
+export interface QrOptions {
+  /** Largeur/hauteur de l'image en pixels. Default 600 (ou config). */
+  width?: number
+  /** Marge blanche autour du QR (en modules). Default 2 (ou config). */
+  margin?: number
+  /**
+   * Niveau de correction d'erreur :
+   *   L = 7 % | M = 15 % | Q = 25 % | H = 30 % (recommandé pour overlay)
+   */
+  errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H'
+  /** Couleur des modules sombres. Default '#0f172a'. */
+  darkColor?: string
+  /** Couleur du fond. Default '#ffffff'. */
+  lightColor?: string
+
+  // ── v0.3 — extension thématique ─────────────────────────────────
+  /**
+   * Master toggle. `false` court-circuite tout le pipeline thématique
+   * et retombe sur le QR pur (comportement v0.2.x). Override de la
+   * valeur config.
+   */
+  genimage?: boolean
+  /**
+   * Thème à appliquer en cadre (4 motifs aux coins). Pris dans le
+   * registry natif (12 thèmes). 'random' tire dans `themePool`.
+   * 'none' désactive le composite ponctuellement.
+   * Objet `{ svg }` → motif custom inline.
+   */
+  theme?: ThemeKey | 'random' | 'none' | { svg: string; label?: string }
+  /** Sous-set des thèmes pour le tirage 'random'. Default = tous. */
+  themePool?: ThemeKey[]
+  /** Marge cadre image / canvas (proportion). Default 0.13. */
+  framePadding?: number
+  /** Taille du cartouche blanc central (proportion 0..1). Default 0.62. */
+  centerWhiteRatio?: number
+  /** Opacité du cadre image (0..1). Default 1. */
+  themeOpacity?: number
+  /** Couleur monochrome du cadre image. Default '#1e293b'. */
+  themeColor?: string
+}
+
+// ─── Internal helpers ──────────────────────────────────────────────
+
+/**
+ * Décide si on bascule sur le pipeline composite ou le legacy.
+ * Order : opts.genimage > config.default.genimage. theme='none' force legacy.
+ */
+function shouldComposite(opts: QrOptions, cfg: QrConfigDefaults): boolean {
+  if (opts.genimage === false) return false
+  if (opts.genimage === true) {
+    // explicit on : ne respecte pas theme=none ? Si l'app dit explicitement
+    // genimage=true mais theme=none, on respecte theme=none (QR pur ponctuel).
+    const theme = opts.theme ?? cfg.theme
+    return theme !== 'none'
+  }
+  // Pas d'override opts → suit la config
+  if (cfg.genimage === false) return false
+  const theme = opts.theme ?? cfg.theme
+  return theme !== 'none'
+}
+
+function composeOptsFromQrOptions(opts: QrOptions, cfg: QrConfigDefaults): ComposeOptions {
+  return mergeComposeOpts(cfg, {
+    width: opts.width,
+    errorCorrectionLevel: opts.errorCorrectionLevel,
+    darkColor: opts.darkColor,
+    lightColor: opts.lightColor,
+    theme: opts.theme,
+    themePool: opts.themePool,
+    framePadding: opts.framePadding,
+    centerWhiteRatio: opts.centerWhiteRatio,
+    themeOpacity: opts.themeOpacity,
+    themeColor: opts.themeColor,
+  })
+}
+
+// ─── Public API : 3 generators ─────────────────────────────────────
+
+/** Génère un PNG (Buffer) d'un QR code encodant `text`. */
+export async function generateQrPng(text: string, opts: QrOptions = {}): Promise<Buffer> {
+  const cfg = loadQrConfig().default
+  if (shouldComposite(opts, cfg)) {
+    const composed = await composeThemedPng(text, composeOptsFromQrOptions(opts, cfg))
+    if (composed) return composed
+  }
+  // Legacy QR pur (qrcode lib direct)
+  return QRCode.toBuffer(text, {
+    width: opts.width ?? cfg.width,
+    margin: opts.margin ?? 2,
+    errorCorrectionLevel: opts.errorCorrectionLevel ?? cfg.errorCorrectionLevel,
+    color: {
+      dark: opts.darkColor ?? cfg.darkColor,
+      light: opts.lightColor ?? cfg.lightColor,
+    },
+  })
+}
+
+/** Génère un SVG (string) d'un QR code encodant `text`. */
+export async function generateQrSvg(text: string, opts: QrOptions = {}): Promise<string> {
+  const cfg = loadQrConfig().default
+  if (shouldComposite(opts, cfg)) {
+    const composed = await composeThemedSvg(text, composeOptsFromQrOptions(opts, cfg))
+    if (composed) return composed
+  }
+  return QRCode.toString(text, {
+    type: 'svg',
+    width: opts.width ?? cfg.width,
+    margin: opts.margin ?? 2,
+    errorCorrectionLevel: opts.errorCorrectionLevel ?? cfg.errorCorrectionLevel,
+    color: {
+      dark: opts.darkColor ?? cfg.darkColor,
+      light: opts.lightColor ?? cfg.lightColor,
+    },
+  })
+}
+
+/** Génère un Data URL `data:image/png;base64,...` */
+export async function generateQrDataUrl(text: string, opts: QrOptions = {}): Promise<string> {
+  const cfg = loadQrConfig().default
+  if (shouldComposite(opts, cfg)) {
+    const composed = await composeThemedDataUrl(text, composeOptsFromQrOptions(opts, cfg))
+    if (composed) return composed
+  }
+  return QRCode.toDataURL(text, {
+    width: opts.width ?? cfg.width,
+    margin: opts.margin ?? 2,
+    errorCorrectionLevel: opts.errorCorrectionLevel ?? cfg.errorCorrectionLevel,
+    color: {
+      dark: opts.darkColor ?? cfg.darkColor,
+      light: opts.lightColor ?? cfg.lightColor,
+    },
+  })
+}
+
+// ─── Helpers haut-niveau (URL builder + invite-token combiné) ─────
+
+export interface BuildInviteUrlsOptions {
+  /** Base absolue (https://app.example.com), sans slash final. */
+  baseUrl: string
+  /** Path public direct (ex: '/projet-x'). Sera concaténé à baseUrl. */
+  directPath: string
+  /** Secret HMAC pour signer le token invite. */
+  inviteSecret: string | Buffer
+  /** Identifiant opaque encodé dans le token (resource id). */
+  inviteId: string
+  /** TTL en ms (default 60 jours). */
+  ttlMs?: number
+  /** Path du callback invite (default '/invite'). */
+  invitePath?: string
+  /** Meta libre encodée dans le token. */
+  inviteMeta?: Record<string, string | number | boolean>
+}
+
+export interface InviteUrls {
+  /** URL absolue mode "direct" (auth standard derrière). */
+  directUrl: string
+  /** URL absolue mode "invite" (token HMAC signé). */
+  inviteUrl: string
+  /** Le token signé seul (pour storage si besoin). */
+  inviteToken: string
+}
+
+/**
+ * Helper combiné — signe un invite-token et construit la paire d'URLs
+ * (direct + invite) prête à passer à `<QrPanel>` côté client.
+ */
+export function buildInviteUrls(opts: BuildInviteUrlsOptions): InviteUrls {
+  const base = String(opts.baseUrl).replace(/\/+$/, '')
+  const direct = opts.directPath.startsWith('/') ? opts.directPath : '/' + opts.directPath
+  const invitePath = (opts.invitePath ?? '/invite').replace(/\/+$/, '')
+  const inviteToken = signInviteToken(opts.inviteSecret, opts.inviteId, opts.ttlMs, opts.inviteMeta)
+  return {
+    directUrl: base + direct,
+    inviteUrl: `${base}${invitePath}/${inviteToken}`,
+    inviteToken,
+  }
+}
+
+// ─── Re-exports utiles côté serveur ────────────────────────────────
+
+export { listThemes, THEME_KEYS, THEMES, getTheme, type ThemeKey, type ThemeAsset } from './themes.js'
+export { loadQrConfig, ensureQrConfig, DEFAULT_CONFIG, type QrConfig } from './config.js'