qr-kit 2.1.0

package/utils/link.js

@@ -0,0 +1,154 @@
+// utils/link.js
+// Universal QR link builder with automatic payload fitting.
+// No external dependencies. Works in any browser environment.
+
+import { sanitizeUrlForQR, utf8ByteLen } from './url.js';
+
+/**
+ * Encodes a string to Base64 preserving full UTF-8.
+ * @param {string} str
+ * @returns {string}
+ */
+function b64utf8(str) {
+  if (typeof TextEncoder !== 'undefined') {
+    const u8 = new TextEncoder().encode(str);
+    let bin = '';
+    for (let i = 0; i < u8.length; i++) bin += String.fromCharCode(u8[i]);
+    return btoa(bin);
+  }
+  // Fallback for older environments
+  return btoa(unescape(encodeURIComponent(str)));
+}
+
+/**
+ * Builds a QR-friendly URL with a JSON payload encoded as Base64 in a query parameter.
+ *
+ * Two URLs are returned:
+ *  - `fullUrl`  — complete URL for sharing/copying (includes all params)
+ *  - `qrUrl`    — trimmed URL optimised to fit within `qrBudgetBytes` (for the QR code itself)
+ *
+ * The `payload` object is serialised to JSON and base64-encoded into `paramName`.
+ * An optional `trimKey` specifies which string field to shorten (binary search)
+ * if the full payload exceeds the byte budget.
+ *
+ * @param {object} opts
+ * @param {string}  opts.baseUrl            - Base URL, e.g. "https://example.com/landing"
+ * @param {object}  opts.payload            - Arbitrary JSON payload (will be base64-encoded)
+ * @param {string}  [opts.paramName]        - Query parameter name for the encoded payload (default: "data")
+ * @param {object}  [opts.extraParams]      - Additional query params added to fullUrl only (e.g. UTM tags)
+ * @param {number}  [opts.qrBudgetBytes]    - Max byte length of qrUrl (default: 134, fits QR v6-L)
+ * @param {boolean} [opts.removeProtocol]   - Strip https:// from qrUrl to save bytes (default: true)
+ * @param {string}  [opts.trimKey]          - Payload key to shorten when budget is exceeded
+ * @param {'trim'|'drop'|'error'} [opts.strategy] - Overflow strategy (default: 'trim')
+ *
+ * @returns {{ fullUrl: string, qrUrl: string, trimmed: boolean, removed: boolean, error?: string }}
+ *
+ * @example
+ * // Basic usage
+ * const { fullUrl, qrUrl } = buildQrLink({
+ *   baseUrl: 'https://example.com/join',
+ *   payload: { userId: '123', plan: 'pro' },
+ *   extraParams: { utm_source: 'poster', utm_medium: 'print' },
+ * });
+ *
+ * @example
+ * // With promo code trimming
+ * const { fullUrl, qrUrl, trimmed } = buildQrLink({
+ *   baseUrl: 'https://example.com/promo',
+ *   payload: { ref: 'abc', code: 'SUPERSALE2024' },
+ *   trimKey: 'code',
+ *   strategy: 'trim',
+ * });
+ */
+export function buildQrLink({
+  baseUrl,
+  payload,
+  paramName = 'data',
+  extraParams = {},
+  qrBudgetBytes = 134,
+  removeProtocol = true,
+  trimKey = null,
+  strategy = 'trim',
+}) {
+  if (!baseUrl) throw new Error('buildQrLink: baseUrl is required');
+  if (!payload || typeof payload !== 'object') throw new Error('buildQrLink: payload must be an object');
+
+  // --- Build fullUrl (all params) ---
+  const fullB64 = b64utf8(JSON.stringify(payload));
+  const fullUrlObj = new URL(baseUrl);
+  fullUrlObj.searchParams.set(paramName, fullB64);
+  for (const [k, v] of Object.entries(extraParams)) {
+    fullUrlObj.searchParams.set(k, v);
+  }
+  const fullUrl = fullUrlObj.toString();
+
+  // --- Build qrUrl (minimal params, optional protocol stripping) ---
+  const mkQrUrl = (b64) => {
+    const raw = `${baseUrl}?${paramName}=${b64}`;
+    return sanitizeUrlForQR(raw, {
+      whitelist: [paramName],
+      aggressive: true,
+      preserveProtocol: !removeProtocol,
+    });
+  };
+
+  // Try full payload first
+  let qrUrl = mkQrUrl(fullB64);
+  if (utf8ByteLen(qrUrl) <= qrBudgetBytes) {
+    return { fullUrl, qrUrl, trimmed: false, removed: false };
+  }
+
+  // --- Overflow handling ---
+  if (strategy === 'error') {
+    return { fullUrl, qrUrl: '', trimmed: false, removed: false, error: 'QR payload too long for budget' };
+  }
+
+  if (strategy === 'drop' || !trimKey) {
+    const reduced = { ...payload };
+    if (trimKey) delete reduced[trimKey];
+    const b64 = b64utf8(JSON.stringify(reduced));
+    return { fullUrl, qrUrl: mkQrUrl(b64), trimmed: false, removed: !!trimKey };
+  }
+
+  // strategy === 'trim': binary-search the shortest trimKey value that still fits
+  const rawValue = payload[trimKey];
+  if (rawValue != null && typeof rawValue !== 'string') {
+    // trimKey points to a non-string field (number, boolean, object) — cannot be trimmed.
+    // Fall through to 'drop' behaviour instead of silently corrupting data.
+    const reduced = { ...payload };
+    delete reduced[trimKey];
+    return { fullUrl, qrUrl: mkQrUrl(b64utf8(JSON.stringify(reduced))), trimmed: false, removed: true };
+  }
+  const originalValue = String(rawValue || '').trim();
+  let lo = 0, hi = originalValue.length, best = -1, bestQr = '';
+
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const cut = originalValue.slice(0, mid);
+    const candidate = { ...payload };
+    if (cut) {
+      candidate[trimKey] = cut;
+    } else {
+      delete candidate[trimKey];
+    }
+    const b64 = b64utf8(JSON.stringify(candidate));
+    const url = mkQrUrl(b64);
+    if (utf8ByteLen(url) <= qrBudgetBytes) {
+      best = mid;
+      bestQr = url;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+
+  if (best >= 0) {
+    return { fullUrl, qrUrl: bestQr, trimmed: best < originalValue.length, removed: false };
+  }
+
+  // Last resort: drop the trimKey entirely
+  const fallback = { ...payload };
+  delete fallback[trimKey];
+  const b64 = b64utf8(JSON.stringify(fallback));
+  return { fullUrl, qrUrl: mkQrUrl(b64), trimmed: false, removed: true };
+}

package/utils/logo.js

@@ -0,0 +1,189 @@
+// utils/logo.js
+// Embeds a logo image inside a QR code using the error-correction recovery budget.
+//
+// Design:
+//   - makeQrWithLogoSvg(model, logoDataUrl, opts)  — zero-DOM, works in Node/Worker/browser
+//   - loadLogoAsDataUrl(src)                        — browser helper: URL → data URL
+//   - buildQrWithLogoSvgAsync(model, src, opts)     — browser convenience wrapper
+//
+// How it works:
+//   ECC M corrects up to ~15% of damaged codewords. We use at most `maxCoverage`
+//   (default 11%) of the total module area for the logo, leaving the remaining
+//   4% as a safety buffer for real-world damage (dirty scanner, low contrast, etc.)
+//
+//   Finder patterns + timing strips + alignment patterns are NEVER obscured —
+//   they are drawn on a separate layer that composites above the logo.
+//
+// Why zero-DOM:
+//   The SVG renderer works in Node.js, Deno, Cloudflare Workers, and any environment
+//   with no `document`. The logo must be provided as a data URL (base64-encoded).
+//   For browser use, call `buildQrWithLogoSvgAsync(model, '/logo.png')` which
+//   fetches and encodes the image for you.
+
+import { computeLayout } from './layout.js';
+import { makeQrPathSplit } from '../renderers/svg.js';
+
+// ─── Public constants ──────────────────────────────────────────────────────────
+
+/** Maximum fraction of QR area safe to cover with ECC M (~15% budget, 4% safety margin). */
+export const LOGO_MAX_COVERAGE_ECC_M = 0.11;
+
+/** Maximum fraction of QR area safe to cover with ECC L (~7% budget, 3% safety margin). */
+export const LOGO_MAX_COVERAGE_ECC_L = 0.04;
+
+// ─── Core: zero-DOM SVG builder ───────────────────────────────────────────────
+
+/**
+ * Builds a complete SVG string with a logo embedded in the centre.
+ * The logo sits above data modules; function modules (finder, timing) are
+ * rendered on a separate layer above the logo to remain scannable.
+ *
+ * @param {import('../qr/qr-core.js').QRModel} model  - Output of makeQr().
+ * @param {string} logoDataUrl  - base64 data URL of the logo (any image format).
+ *                                Use loadLogoAsDataUrl() in the browser to obtain this.
+ * @param {object} [opts]
+ * @param {number}  [opts.size=256]           - Outer SVG size in px.
+ * @param {number}  [opts.margin=16]          - Quiet-zone padding in px.
+ * @param {string}  [opts.fg='#000']          - Data module colour.
+ * @param {string}  [opts.fnFg='#000']        - Function module colour (finder/timing).
+ * @param {string}  [opts.bg='#fff']          - Background colour.
+ * @param {number}  [opts.maxCoverage]        - Max fraction of QR area to cover.
+ *                                              Default: 0.11 for ECC M, 0.04 for ECC L.
+ * @param {number}  [opts.logoPadding=4]      - White padding around logo in px.
+ * @param {string}  [opts.logoBg='#fff']      - Colour of logo background pad.
+ * @param {number}  [opts.logoRadius=6]       - Border-radius of logo bg rect in px.
+ * @param {string}  [opts.title='QR Code']
+ * @returns {string} Complete SVG markup.
+ */
+export function makeQrWithLogoSvg(model, logoDataUrl, {
+  size        = 256,
+  margin      = 16,
+  fg          = '#000',
+  fnFg        = '#000',
+  bg          = '#fff',
+  maxCoverage,
+  logoPadding = 4,
+  logoBg      = '#fff',
+  logoRadius  = 6,
+  title       = 'QR Code',
+} = {}) {
+  if (!logoDataUrl) throw new Error('makeQrWithLogoSvg: logoDataUrl is required');
+
+  const ecc = model.eccLevel ?? 'M';
+  const maxCov = maxCoverage ?? (ecc === 'M' ? LOGO_MAX_COVERAGE_ECC_M : LOGO_MAX_COVERAGE_ECC_L);
+
+  const { outer, moduleSize, quietLeft, quietTop } = computeLayout(model.size, size, margin);
+
+  // Maximum logo size in pixels based on ECC budget
+  const qrPx      = model.size * moduleSize;
+  const maxLogoPx = Math.floor(Math.sqrt(maxCov) * qrPx);
+
+  // Logo sits in the centre of the QR grid (not the outer canvas)
+  const gridCentreX = quietLeft + qrPx / 2;
+  const gridCentreY = quietTop  + qrPx / 2;
+
+  const logoSize   = maxLogoPx;
+  const padded     = logoSize + logoPadding * 2;
+  const logoX      = gridCentreX - padded / 2;
+  const logoY      = gridCentreY - padded / 2;
+
+  // Get separate paths: data modules below the logo, function modules above
+  const { dataPath, functionPath } = makeQrPathSplit(model, { size, margin });
+
+  // Escape helpers
+  const ea = s => String(s).replace(/[&<>"']/g, c =>
+    ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+  const logoImgX  = logoX + logoPadding;
+  const logoImgY  = logoY + logoPadding;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"`
+       + ` width="${outer}" height="${outer}" viewBox="0 0 ${outer} ${outer}"`
+       + ` role="img" aria-label="${ea(title)}" shape-rendering="crispEdges">`
+       + `<title>${ea(title)}</title>`
+       + `<rect width="100%" height="100%" fill="${ea(bg)}"/>`
+
+       // Layer 1: data modules (covered by logo, but scannable due to ECC)
+       + `<path fill="${ea(fg)}" d="${dataPath}"/>`
+
+       // Layer 2: logo background + logo image
+       + `<rect x="${logoX.toFixed(1)}" y="${logoY.toFixed(1)}"`
+       + ` width="${padded.toFixed(1)}" height="${padded.toFixed(1)}"`
+       + ` rx="${logoRadius}" ry="${logoRadius}"`
+       + ` fill="${ea(logoBg)}"/>`
+       + `<image href="${logoDataUrl}"`
+       + ` x="${logoImgX.toFixed(1)}" y="${logoImgY.toFixed(1)}"`
+       + ` width="${logoSize.toFixed(1)}" height="${logoSize.toFixed(1)}"`
+       + ` preserveAspectRatio="xMidYMid meet"/>`
+
+       // Layer 3: function modules — always on top, never obscured
+       + `<path fill="${ea(fnFg)}" d="${functionPath}"/>`
+
+       + `</svg>`;
+}
+
+/**
+ * Returns the maximum safe logo size in pixels for a given QR model and output size.
+ * Use this to pre-validate a logo before calling makeQrWithLogoSvg.
+ *
+ * @param {import('../qr/qr-core.js').QRModel} model
+ * @param {number} size         - Outer SVG size in px (same as passed to makeQrWithLogoSvg).
+ * @param {number} margin       - Quiet-zone in px.
+ * @param {number} [maxCoverage]
+ * @returns {{ maxLogoSize: number, paddedSize: number, coverageFraction: number }}
+ */
+export function getLogoConstraints(model, size, margin, maxCoverage) {
+  const ecc    = model.eccLevel ?? 'M';
+  const maxCov = maxCoverage ?? (ecc === 'M' ? LOGO_MAX_COVERAGE_ECC_M : LOGO_MAX_COVERAGE_ECC_L);
+  const { moduleSize } = computeLayout(model.size, size, margin);
+  const qrPx   = model.size * moduleSize;
+  const maxLogoPx = Math.floor(Math.sqrt(maxCov) * qrPx);
+  return {
+    maxLogoSize: maxLogoPx,
+    paddedSize: maxLogoPx + 8,   // +8 = default padding (4px each side)
+    coverageFraction: (maxLogoPx / qrPx) ** 2,
+  };
+}
+
+// ─── Browser helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Fetches an image URL and converts it to a base64 data URL.
+ * Browser-only (requires fetch + FileReader or canvas).
+ *
+ * @param {string} src    - URL of the image (JPEG, PNG, SVG, WebP…)
+ * @param {object} [opts]
+ * @param {AbortSignal} [opts.signal]
+ * @returns {Promise<string>} base64 data URL
+ */
+export async function loadLogoAsDataUrl(src, { signal } = {}) {
+  // Try fetch first (works for remote URLs with CORS, local URLs, data URIs)
+  if (src.startsWith('data:')) return src; // already a data URL
+
+  const res = await fetch(src, { signal });
+  if (!res.ok) throw new Error(`loadLogoAsDataUrl: fetch failed ${res.status} for ${src}`);
+
+  const blob     = await res.blob();
+  const reader   = new FileReader();
+  const dataUrl  = await new Promise((resolve, reject) => {
+    reader.onload  = () => resolve(/** @type {string} */ (reader.result));
+    reader.onerror = () => reject(new Error('FileReader failed'));
+    reader.readAsDataURL(blob);
+  });
+  return dataUrl;
+}
+
+/**
+ * Browser convenience: loads a logo from a URL and returns a complete QR SVG string.
+ * Equivalent to `makeQrWithLogoSvg(model, await loadLogoAsDataUrl(src), opts)`.
+ *
+ * @param {import('../qr/qr-core.js').QRModel} model
+ * @param {string} logoSrc   - URL of the logo image.
+ * @param {object} [opts]    - Same options as makeQrWithLogoSvg, plus `signal`.
+ * @returns {Promise<string>} Complete SVG markup.
+ */
+export async function buildQrWithLogoSvgAsync(model, logoSrc, opts = {}) {
+  const { signal, ...svgOpts } = opts;
+  const dataUrl = await loadLogoAsDataUrl(logoSrc, { signal });
+  return makeQrWithLogoSvg(model, dataUrl, svgOpts);
+}

package/utils/pdf.js

@@ -0,0 +1,314 @@
+// utils/pdf.js
+// Zero-dependency browser PDF builder: assembles a PDF with a background image
+// and a QR code, both embedded as JPEG XObjects.
+//
+// IMPORTANT: PDF coordinates originate from the BOTTOM-LEFT corner of the page.
+
+import { svgToPngDataURL, pngDataURLtoJpegBytes, dataURLToImage, dataURLToBytes } from './raster.js';
+
+// -----------------------------
+// Internal helpers: image loading
+// -----------------------------
+
+// Fetches raw image bytes (JPEG/PNG) without re-encoding
+async function fetchBytes(url, { signal } = {}) {
+  const res = await fetch(url, { signal });
+  if (!res.ok) throw new Error(`Failed to fetch ${url}: ${res.status}`);
+  const buf = await res.arrayBuffer();
+  return new Uint8Array(buf);
+}
+
+// Loads an <img> element without crossOrigin (we only need width/height)
+function loadImgNoCors(src) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload  = () => resolve(img);
+    img.onerror = reject;
+    img.src = src;
+  });
+}
+
+// Returns true if bytes start with the JPEG magic number FF D8
+function isJpeg(u8) {
+  return u8.length > 2 && u8[0] === 0xFF && u8[1] === 0xD8;
+}
+
+// Re-encodes any image (PNG, WebP, GIF, CMYK JPEG, …) to RGB JPEG via canvas
+async function recodeToRgbJpeg(src, quality = 0.92) {
+  const img = await loadImgNoCors(src);
+  const canvas = document.createElement('canvas');
+  canvas.width = img.width;
+  canvas.height = img.height;
+  canvas.getContext('2d').drawImage(img, 0, 0);
+  return dataURLToBytes(canvas.toDataURL('image/jpeg', quality));
+}
+
+// Detects the number of colour components in a JPEG (1=Gray, 3=RGB/YCbCr, 4=CMYK)
+function jpegComponents(u8) {
+  let i = 0;
+  if (u8[i++] !== 0xFF || u8[i++] !== 0xD8) return null; // not a JPEG
+  while (i + 4 < u8.length) {
+    if (u8[i] !== 0xFF) { i++; continue; }
+    const marker = u8[i + 1];
+    i += 2;
+    if (marker === 0xDA) break; // SOS marker — image data starts here
+    const len = (u8[i] << 8) | u8[i + 1]; i += 2;
+    if (marker === 0xC0 || marker === 0xC1 || marker === 0xC2) {
+      // SOF0/1/2: precision(1), H(2), W(2), Nf(1)
+      return u8[i + 5] || null;
+    } else {
+      i += len - 2;
+    }
+  }
+  return null;
+}
+
+function colorSpaceDictForJpeg(u8) {
+  const nf = jpegComponents(u8);
+  if (nf === 1) return { cs: '/DeviceGray', decode: '' };
+  if (nf === 4) return { cs: '/DeviceCMYK', decode: ' /Decode [1 0 1 0 1 0 1 0]' };
+  return { cs: '/DeviceRGB', decode: '' }; // default
+}
+
+// -----------------------------
+// Internal helpers: PDF low-level
+// -----------------------------
+
+function arrayBufferToLatin1(buf) {
+  const u8 = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  let s = '';
+  for (let i = 0; i < u8.length; i++) s += String.fromCharCode(u8[i]);
+  return s;
+}
+
+function strToBytesLatin1(str) {
+  const out = new Uint8Array(str.length);
+  for (let i = 0; i < str.length; i++) out[i] = str.charCodeAt(i) & 0xFF;
+  return out;
+}
+
+function concatBytes(...parts) {
+  let total = 0;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  let o = 0;
+  for (const p of parts) { out.set(p, o); o += p.length; }
+  return out;
+}
+
+// Binary stream object (used for image XObjects)
+// << >> delimiters and CRLF around stream/endstream are required by PDF spec
+function streamObj({ dict, bytes }) {
+  const head = `<< ${dict} >>\r\nstream\r\n`;
+  const tail  = `\r\nendstream`;
+  return head + arrayBufferToLatin1(bytes) + tail;
+}
+
+// ASCII content stream (used for page content operators)
+function streamRaw(content) {
+  const length = content.length;
+  return `<< /Length ${length} >>\r\nstream\r\n${content}\r\nendstream`;
+}
+
+// Assembles a complete PDF byte sequence from an array of object strings.
+// The binary comment after the header tells viewers that the file contains binary streams.
+function assemblePDF(objects) {
+  const header    = '%PDF-1.7\r\n%\xFF\xFF\xFF\xFF\r\n';
+  const bodyParts = objects.map((o, i) => `${i + 1} 0 obj\r\n${o}\r\nendobj\r\n`);
+  const body      = bodyParts.join('');
+
+  const offsets = [0];
+  let cursor    = header.length;
+  for (const part of bodyParts) { offsets.push(cursor); cursor += part.length; }
+
+  const xrefStart = header.length + body.length;
+  let xref = `xref\r\n0 ${objects.length + 1}\r\n0000000000 65535 f \r\n`;
+  for (let i = 1; i <= objects.length; i++) {
+    xref += `${String(offsets[i]).padStart(10, '0')} 00000 n \r\n`;
+  }
+
+  const trailer = `trailer\r\n<< /Size ${objects.length + 1} /Root ${objects.length} 0 R >>\r\nstartxref\r\n${xrefStart}\r\n%%EOF`;
+
+  return {
+    pdfBytes: concatBytes(
+      strToBytesLatin1(header),
+      strToBytesLatin1(body),
+      strToBytesLatin1(xref),
+      strToBytesLatin1(trailer),
+    ),
+  };
+}
+
+function downloadBytes(bytes, filename) {
+  const blob = new Blob([bytes], { type: 'application/pdf' });
+  const url  = URL.createObjectURL(blob);
+  const a    = document.createElement('a');
+  a.href = url; a.download = filename; document.body.appendChild(a); a.click(); a.remove();
+  URL.revokeObjectURL(url);
+}
+
+// Escapes a string for use inside a PDF text literal (ASCII only)
+function escapePDFText(s) {
+  return String(s).replace(/[\\()]/g, m => ({ '\\': '\\\\', '(': '\\(', ')': '\\)' }[m]));
+}
+
+// -----------------------------
+// PUBLIC API — Data primitives (return bytes, no side effects)
+// -----------------------------
+
+/**
+ * Builds a simple A4 PDF and returns it as a Uint8Array.
+ * Use this to send the PDF to a server, store in state, or test without triggering a download.
+ *
+ * @param {object} opts - Same options as downloadQrPdf except no `fileName`.
+ * @returns {Promise<Uint8Array>}
+ */
+export async function buildQrPdfBytes({
+  svgEl,
+  title  = 'Leaflet',
+  org,
+  url,
+  notes  = [],
+  images = [],
+}) {
+  const pageW = 595.276, pageH = 841.890;
+  const qrDataUrl   = await svgToPngDataURL(svgEl, 3);
+  const qrJpegBytes = await pngDataURLtoJpegBytes(qrDataUrl, 0.92);
+  const qrImgEl     = await dataURLToImage(qrDataUrl);
+
+  const extra = [];
+  for (const item of images) {
+    try {
+      const imgEl = await loadImgNoCors(item.src);
+      let bytes = await fetchBytes(item.src);
+      if (!isJpeg(bytes)) bytes = await recodeToRgbJpeg(item.src, 0.9);
+      extra.push({ imgEl, bytes, spec: colorSpaceDictForJpeg(bytes), caption: item.caption });
+    } catch (e) { console.warn('Image load failed:', item.src, e); }
+  }
+
+  const objs = [], addObj = s => { objs.push(s); return objs.length; };
+  const fontId = addObj(`<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>`);
+  const qrSpec = colorSpaceDictForJpeg(qrJpegBytes);
+  const qrId   = addObj(streamObj({ dict: `/Type /XObject /Subtype /Image /Width ${qrImgEl.width} /Height ${qrImgEl.height} /ColorSpace ${qrSpec.cs}${qrSpec.decode} /BitsPerComponent 8 /Filter /DCTDecode /Length ${qrJpegBytes.length}`, bytes: qrJpegBytes }));
+  const extraIds = extra.map(e => addObj(streamObj({ dict: `/Type /XObject /Subtype /Image /Width ${e.imgEl.width} /Height ${e.imgEl.height} /ColorSpace ${e.spec.cs}${e.spec.decode} /BitsPerComponent 8 /Filter /DCTDecode /Length ${e.bytes.length}`, bytes: e.bytes })));
+
+  const c = [];
+  c.push(`BT /F1 20 Tf 50 ${pageH - 60} Td (${escapePDFText(title)}) Tj ET`);
+  const lines = [org && `Org: ${org}`, url && `URL: ${url}`, ...notes].filter(Boolean);
+  let y = pageH - 90;
+  c.push('BT /F1 11 Tf');
+  for (const line of lines) { c.push(`50 ${y} Td (${escapePDFText(line)}) Tj`); y -= 16; }
+  c.push('ET');
+  const qrSize = 220, qrX = pageW - 50 - qrSize, qrY = pageH - 60 - qrSize;
+  c.push(`q ${qrSize} 0 0 ${qrSize} ${qrX} ${qrY} cm /ImQR Do Q`);
+  let imgX = 50, imgY = qrY - 30;
+  for (let i = 0; i < extraIds.length; i++) {
+    if (imgX + 120 > pageW - 50) { imgX = 50; imgY -= 110; }
+    c.push(`q 120 0 0 80 ${imgX} ${imgY - 80} cm /Im${i} Do Q`);
+    if (extra[i].caption) c.push(`BT /F1 10 Tf ${imgX} ${imgY - 94} Td (${escapePDFText(extra[i].caption)}) Tj ET`);
+    imgX += 136;
+  }
+
+  const cId  = addObj(streamRaw(c.join('\n')));
+  const xObj = [`/ImQR ${qrId} 0 R`, ...extraIds.map((id, i) => `/Im${i} ${id} 0 R`)].join(' ');
+  const rId  = addObj(`<< /ProcSet [/PDF /ImageC] /Font << /F1 ${fontId} 0 R >> /XObject << ${xObj} >> >>`);
+  const pgId = addObj(`<< /Type /Page /Parent 0 0 R /MediaBox [0 0 ${pageW} ${pageH}] /Resources ${rId} 0 R /Contents ${cId} 0 R >>`);
+  const psId = addObj(`<< /Type /Pages /Kids [${pgId} 0 R] /Count 1 >>`);
+  objs[pgId - 1] = `<< /Type /Page /Parent ${psId} 0 R /MediaBox [0 0 ${pageW} ${pageH}] /Resources ${rId} 0 R /Contents ${cId} 0 R >>`;
+  addObj(`<< /Type /Catalog /Pages ${psId} 0 R >>`);
+  return assemblePDF(objs).pdfBytes;
+}
+
+/**
+ * Builds a PDF with a full-page background image + QR overlay, returns Uint8Array.
+ * Use this to upload to a server, test, or create a Blob manually.
+ *
+ * @param {object} opts - Same as downloadPdfWithTemplateImage except no `fileName`.
+ * @returns {Promise<Uint8Array>}
+ */
+export async function buildPdfWithTemplateBytes({
+  svgEl,
+  templateSrc,
+  page          = { width: 595.276, height: 841.890 },
+  qr            = { x: 420, y: 130, size: 160 },
+  recodeBgToRgb = false,
+  signal,
+}) {
+  signal?.throwIfAborted?.();
+  const pageW = page.width || 595.276, pageH = page.height || 841.890;
+  const bgImgEl = await loadImgNoCors(templateSrc);
+  let bgBytes   = await fetchBytes(templateSrc, { signal });
+  if (recodeBgToRgb || !isJpeg(bgBytes)) bgBytes = await recodeToRgbJpeg(templateSrc, 0.92);
+  const bgSpec = colorSpaceDictForJpeg(bgBytes);
+
+  const qrPngUrl = await svgToPngDataURL(svgEl, 3);
+  const qrImgEl  = await dataURLToImage(qrPngUrl);
+  const qrBytes  = await pngDataURLtoJpegBytes(qrPngUrl, 0.92);
+  const qrSpec   = colorSpaceDictForJpeg(qrBytes);
+
+  const objs = [], addObj = s => { objs.push(s); return objs.length; };
+  const bgId = addObj(streamObj({ dict: `/Type /XObject /Subtype /Image /Width ${bgImgEl.width} /Height ${bgImgEl.height} /ColorSpace ${bgSpec.cs}${bgSpec.decode} /BitsPerComponent 8 /Filter /DCTDecode /Length ${bgBytes.length}`, bytes: bgBytes }));
+  const qrId = addObj(streamObj({ dict: `/Type /XObject /Subtype /Image /Width ${qrImgEl.width} /Height ${qrImgEl.height} /ColorSpace ${qrSpec.cs}${qrSpec.decode} /BitsPerComponent 8 /Filter /DCTDecode /Length ${qrBytes.length}`, bytes: qrBytes }));
+  const cId  = addObj(streamRaw(`q ${pageW} 0 0 ${pageH} 0 0 cm /ImBG Do Q\nq ${qr.size} 0 0 ${qr.size} ${qr.x} ${qr.y} cm /ImQR Do Q`));
+  const rId  = addObj(`<< /ProcSet [/PDF /ImageC] /XObject << /ImBG ${bgId} 0 R /ImQR ${qrId} 0 R >> >>`);
+  const pgId = addObj(`<< /Type /Page /Parent 0 0 R /MediaBox [0 0 ${pageW} ${pageH}] /Resources ${rId} 0 R /Contents ${cId} 0 R >>`);
+  const psId = addObj(`<< /Type /Pages /Kids [${pgId} 0 R] /Count 1 >>`);
+  objs[pgId - 1] = `<< /Type /Page /Parent ${psId} 0 R /MediaBox [0 0 ${pageW} ${pageH}] /Resources ${rId} 0 R /Contents ${cId} 0 R >>`;
+  addObj(`<< /Type /Catalog /Pages ${psId} 0 R >>`);
+  return assemblePDF(objs).pdfBytes;
+}
+
+// -----------------------------
+// PUBLIC API — Download wrappers (browser side-effects)
+// -----------------------------
+
+/**
+ * Generates a simple A4 PDF (title + optional text + QR code) and triggers a download.
+ *
+ * Note: text rendering uses the built-in Helvetica font — only ASCII characters
+ * are supported in text fields. For Cyrillic/non-Latin, use the image-based
+ * variant `downloadPdfWithTemplateImage` with a pre-rendered background.
+ *
+ * @param {object} opts
+ * @param {SVGSVGElement} opts.svgEl
+ * @param {string}  [opts.title]
+ * @param {string}  [opts.org]
+ * @param {string}  [opts.url]
+ * @param {string[]} [opts.notes]
+ * @param {Array<{src: string, caption?: string}>} [opts.images]
+ * @param {string}  [opts.fileName='leaflet.pdf']
+ */
+export async function downloadQrPdf({
+  svgEl, title = 'Leaflet', org, url, notes = [], images = [], fileName = 'leaflet.pdf',
+}) {
+  const bytes = await buildQrPdfBytes({ svgEl, title, org, url, notes, images });
+  downloadBytes(bytes, fileName);
+}
+
+/** @deprecated Use `downloadQrPdf` instead. */
+export const downloadLeafletPDF = downloadQrPdf;
+
+/**
+ * Generates a PDF with a full-page background image and QR overlay, then triggers a download.
+ *
+ * Background images are auto-converted to RGB JPEG if needed (PNG, WebP, CMYK JPEG).
+ * Set `recodeBgToRgb: true` to force this even for regular JPEGs (e.g. CMYK sources).
+ *
+ * @param {object}  opts
+ * @param {SVGSVGElement} opts.svgEl
+ * @param {string}  opts.templateSrc
+ * @param {{ width: number, height: number }} [opts.page]  - Default: A4
+ * @param {{ x: number, y: number, size: number }} [opts.qr] - pt from bottom-left
+ * @param {string}  [opts.fileName='leaflet.pdf']
+ * @param {boolean} [opts.recodeBgToRgb=false]
+ */
+export async function downloadPdfWithTemplateImage({
+  svgEl, templateSrc,
+  page = { width: 595.276, height: 841.890 },
+  qr   = { x: 420, y: 130, size: 160 },
+  fileName = 'leaflet.pdf',
+  recodeBgToRgb = false,
+}) {
+  const bytes = await buildPdfWithTemplateBytes({ svgEl, templateSrc, page, qr, recodeBgToRgb });
+  downloadBytes(bytes, fileName);
+}