@gongbaodd/qr-renderer 0.1.0

package/src/core/errors.ts

@@ -0,0 +1,24 @@
+export type ErrorCode =
+  | 'QWEN_API_FAILED'
+  | 'INVALID_INPUT'
+  | 'MASK_AMBIGUOUS'
+  | 'MASK_INVALID'
+  | 'QR_INVALID'
+  | 'QR_TEXT_MISMATCH'
+  | 'QR_LAYOUT_INVALID'
+  | 'COLOR_INVALID'
+  | 'OUTPUT_EXISTS'
+  | 'IMAGE_PROCESSING_FAILED'
+  | 'VERIFICATION_FAILED'
+
+export class QrPosterError extends Error {
+  readonly code: ErrorCode
+  readonly exitCode: 2 | 3 | 4
+
+  constructor(code: ErrorCode, message: string, exitCode: 2 | 3 | 4 = 2, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'QrPosterError'
+    this.code = code
+    this.exitCode = exitCode
+  }
+}

package/src/core/export-sizes.ts

@@ -0,0 +1,179 @@
+import { QrPosterError } from './errors'
+import type { RawImage } from './imaging/types'
+import type { RegionMask } from './types'
+
+export const RASTER_EXPORT_TARGETS = [320, 640, 1280] as const
+
+export interface RasterExportChoice {
+  key: string
+  targetPitch: number
+  width: number
+  height: number
+}
+
+export function dimensionsAtPitch(
+  width: number,
+  height: number,
+  originalPitch: number,
+  targetPitch: number,
+): { width: number; height: number } {
+  const scale = targetPitch / originalPitch
+  return {
+    width: Math.max(1, Math.round(width * scale)),
+    height: Math.max(1, Math.round(height * scale)),
+  }
+}
+
+/** Build distinct smaller choices while keeping every export on an integer QR-module pitch. */
+export function rasterExportChoices(width: number, height: number, originalPitch: number): RasterExportChoice[] {
+  if (!Number.isInteger(originalPitch) || originalPitch <= 4) return []
+  const byPitch = new Map<number, RasterExportChoice>()
+  const minimumDimensions = dimensionsAtPitch(width, height, originalPitch, 4)
+  byPitch.set(4, {
+    key: 'minimum',
+    targetPitch: 4,
+    ...minimumDimensions,
+  })
+
+  for (const target of RASTER_EXPORT_TARGETS) {
+    if (target >= Math.max(width, height)) continue
+    let targetPitch = 4
+    while (
+      targetPitch < originalPitch &&
+      Math.max(
+        dimensionsAtPitch(width, height, originalPitch, targetPitch).width,
+        dimensionsAtPitch(width, height, originalPitch, targetPitch).height,
+      ) < target
+    )
+      targetPitch++
+    if (targetPitch >= originalPitch) continue
+    if (byPitch.has(targetPitch)) continue
+    byPitch.set(targetPitch, {
+      key: `target-${target}`,
+      targetPitch,
+      ...dimensionsAtPitch(width, height, originalPitch, targetPitch),
+    })
+  }
+
+  return [...byPitch.values()].sort((left, right) => left.targetPitch - right.targetPitch)
+}
+
+/** Area-weighted RGBA shrink in premultiplied-alpha space. */
+export function resizeAreaPremultiplied(source: RawImage, width: number, height: number): Uint8Array {
+  if (width > source.width || height > source.height)
+    throw new QrPosterError('INVALID_INPUT', 'Raster export sizes cannot exceed the assembled poster.')
+  if (width === source.width && height === source.height) return Uint8Array.from(source.data)
+  const output = new Uint8Array(width * height * 4)
+  const scaleX = source.width / width
+  const scaleY = source.height / height
+
+  for (let targetY = 0; targetY < height; targetY++) {
+    const sourceTop = targetY * scaleY
+    const sourceBottom = (targetY + 1) * scaleY
+    const firstY = Math.floor(sourceTop)
+    const lastY = Math.min(source.height - 1, Math.ceil(sourceBottom) - 1)
+    for (let targetX = 0; targetX < width; targetX++) {
+      const sourceLeft = targetX * scaleX
+      const sourceRight = (targetX + 1) * scaleX
+      const firstX = Math.floor(sourceLeft)
+      const lastX = Math.min(source.width - 1, Math.ceil(sourceRight) - 1)
+      let totalWeight = 0
+      let alphaWeight = 0
+      let red = 0
+      let green = 0
+      let blue = 0
+      for (let sourceY = firstY; sourceY <= lastY; sourceY++) {
+        const vertical = Math.min(sourceBottom, sourceY + 1) - Math.max(sourceTop, sourceY)
+        for (let sourceX = firstX; sourceX <= lastX; sourceX++) {
+          const horizontal = Math.min(sourceRight, sourceX + 1) - Math.max(sourceLeft, sourceX)
+          const weight = horizontal * vertical
+          const offset = (sourceY * source.width + sourceX) * 4
+          const alpha = source.data[offset + 3]! / 255
+          totalWeight += weight
+          alphaWeight += weight * alpha
+          red += weight * alpha * source.data[offset]!
+          green += weight * alpha * source.data[offset + 1]!
+          blue += weight * alpha * source.data[offset + 2]!
+        }
+      }
+      const target = (targetY * width + targetX) * 4
+      output[target + 3] = totalWeight > 0 ? Math.round((alphaWeight / totalWeight) * 255) : 0
+      if (alphaWeight > 0) {
+        output[target] = Math.round(red / alphaWeight)
+        output[target + 1] = Math.round(green / alphaWeight)
+        output[target + 2] = Math.round(blue / alphaWeight)
+      }
+    }
+  }
+  return output
+}
+
+/** A target mask pixel is selected only when every source pixel in its footprint is selected. */
+export function resizeRegionMaskConservative(source: RegionMask, width: number, height: number): RegionMask {
+  const integralWidth = source.width + 1
+  const integral = new Uint32Array(integralWidth * (source.height + 1))
+  for (let y = 0; y < source.height; y++) {
+    let row = 0
+    for (let x = 0; x < source.width; x++) {
+      if (source.data[y * source.width + x]) row++
+      integral[(y + 1) * integralWidth + x + 1] = integral[y * integralWidth + x + 1]! + row
+    }
+  }
+
+  const data = new Uint8Array(width * height)
+  let area = 0
+  let sumX = 0
+  let sumY = 0
+  let minX = width
+  let minY = height
+  let maxX = -1
+  let maxY = -1
+  for (let y = 0; y < height; y++) {
+    const top = Math.floor((y * source.height) / height)
+    const bottom = Math.min(source.height, Math.ceil(((y + 1) * source.height) / height))
+    for (let x = 0; x < width; x++) {
+      const left = Math.floor((x * source.width) / width)
+      const right = Math.min(source.width, Math.ceil(((x + 1) * source.width) / width))
+      const selected =
+        integral[bottom * integralWidth + right]! -
+        integral[top * integralWidth + right]! -
+        integral[bottom * integralWidth + left]! +
+        integral[top * integralWidth + left]!
+      if (selected !== (right - left) * (bottom - top)) continue
+      data[y * width + x] = 255
+      area++
+      sumX += x
+      sumY += y
+      minX = Math.min(minX, x)
+      minY = Math.min(minY, y)
+      maxX = Math.max(maxX, x)
+      maxY = Math.max(maxY, y)
+    }
+  }
+  if (area === 0) throw new QrPosterError('MASK_INVALID', 'The selected region disappears at this export size.')
+  return {
+    data,
+    width,
+    height,
+    source: source.source,
+    area,
+    bounds: { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 },
+    centroid: { x: sumX / area, y: sumY / area },
+  }
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = ''
+  for (let start = 0; start < bytes.length; start += 0x8000)
+    binary += String.fromCharCode(...bytes.subarray(start, start + 0x8000))
+  return btoa(binary)
+}
+
+/** A self-contained full-poster SVG backed by the exact verified assembled PNG. */
+export function buildPosterSvg(png: Uint8Array, width: number, height: number): string {
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">\n` +
+    `  <image x="0" y="0" width="${width}" height="${height}" preserveAspectRatio="none" href="data:image/png;base64,${bytesToBase64(png)}"/>\n` +
+    '</svg>\n'
+  )
+}

package/src/core/image.ts

@@ -0,0 +1,57 @@
+import { imaging } from './imaging'
+import { QrPosterError } from './errors'
+
+export interface LoadedPng {
+  path: string
+  file: Uint8Array
+  data: Uint8Array
+  width: number
+  height: number
+  sha256: string
+}
+
+export async function loadPng(path: string, label: string): Promise<LoadedPng> {
+  // The Node-only fs/path imports stay dynamic so browser bundles (the worker)
+  // never pull them in; scripts, tests, and the CLI are the only loadPng callers.
+  if (!path.toLowerCase().endsWith('.png'))
+    throw new QrPosterError('INVALID_INPUT', `${label} must be a PNG file: ${path}`)
+
+  let file: Uint8Array
+  try {
+    const { readFile } = await import('node:fs/promises')
+    file = await readFile(path)
+  } catch (error) {
+    throw new QrPosterError('INVALID_INPUT', `Could not read ${label}: ${path}`, 2, { cause: error })
+  }
+
+  return decodePng(file, path, label)
+}
+
+/** Decodes an in-memory PNG into the same shape {@link loadPng} returns. */
+export async function decodePng(file: Uint8Array, path: string, label: string): Promise<LoadedPng> {
+  try {
+    const raw = await imaging().decodePng(file)
+    return {
+      path,
+      file,
+      data: raw.data,
+      width: raw.width,
+      height: raw.height,
+      sha256: await imaging().sha256Hex(file),
+    }
+  } catch (error) {
+    throw new QrPosterError('INVALID_INPUT', `Could not decode ${label} as PNG: ${path}`, 2, { cause: error })
+  }
+}
+
+export async function rgbaToPng(data: Uint8Array, width: number, height: number): Promise<Uint8Array> {
+  return imaging().encodePngRgba(data, width, height)
+}
+
+export async function grayscaleToPng(data: Uint8Array, width: number, height: number): Promise<Uint8Array> {
+  return imaging().encodePngGrayscale(data, width, height)
+}
+
+export function luma(r: number, g: number, b: number): number {
+  return Math.round((299 * r + 587 * g + 114 * b) / 1000)
+}

package/src/core/imaging/browser.ts

@@ -0,0 +1,186 @@
+/**
+ * The browser imaging backend: @jsquash/png for the lossless PNG codec and
+ * @resvg/resvg-wasm as the SVG rasterizer. Pixel work (composite, flatten,
+ * nearest resize) shares the pure-TS helpers in pixels.ts so both environments
+ * implement the same document semantics.
+ *
+ * The WASM binaries are initialized lazily on the first operation. In a browser
+ * bundle both codecs auto-resolve their `.wasm` assets relative to their own
+ * module URL; in Node (parity harness) pass the raw wasm bytes via
+ * {@link installBrowserImaging}.
+ */
+
+import { decode as pngDecodeWasm, encode as pngEncodeWasm } from '@jsquash/png'
+import { init as initPngCodec } from '@jsquash/png/decode.js'
+import type { InitInput as PngWasmInput } from '@jsquash/png/codec/pkg/squoosh_png.js'
+import { Resvg, initWasm } from '@resvg/resvg-wasm'
+import type { InitInput as ResvgWasmInput } from '@resvg/resvg-wasm'
+import { QrPosterError } from '../errors'
+import { compositeOver, flattenOverWhite, resizeNearest } from './pixels'
+import type { Imaging, RawImage, RenderedSvgPng, SvgRenderOptions } from './types'
+
+/** Mirrors sharp's `limitInputPixels` on the Node backend. */
+const PNG_DECODE_PIXEL_LIMIT = 16_000_000
+
+export interface BrowserImagingOptions {
+  /** resvg wasm source; defaults to the codec's bundled URL in browser builds. */
+  resvgWasm?: ResvgWasmInput
+  /** jSquash png wasm source; defaults to the codec's bundled URL in browser builds. */
+  pngWasm?: PngWasmInput
+}
+
+let initialized: Promise<void> | null = null
+
+/** Pre-initializes the codec WASMs; call once per worker/entry point. */
+export function installBrowserImaging(options: BrowserImagingOptions = {}): Promise<void> {
+  if (initialized) {
+    if (!options.resvgWasm && !options.pngWasm) return initialized
+    return Promise.reject(new Error('The browser imaging backend is already initialized.'))
+  }
+  initialized = Promise.all([
+    initWasm(options.resvgWasm as ResvgWasmInput),
+    initPngCodec(options.pngWasm as PngWasmInput),
+  ]).then(() => undefined)
+  return initialized
+}
+
+/**
+ * Turbopack emits the wasm binaries as assets and returns their URLs. The
+ * `@resvg/resvg-wasm` default auto-init cannot run under Turbopack: it relies on
+ * `import.meta.url`, which the bundler replaces with `void 0`, so its internal
+ * `new URL('index_bg.wasm', void 0)` throws Invalid URL. We import both assets
+ * explicitly and hand the URLs to the inits instead.
+ */
+async function defaultWasmInputs(): Promise<BrowserImagingOptions> {
+  const [resvgAsset, pngAsset] = await Promise.all([
+    import('@resvg/resvg-wasm/index_bg.wasm'),
+    import('@jsquash/png/codec/pkg/squoosh_png_bg.wasm'),
+  ])
+  const resvgUrl = (resvgAsset as { default: string }).default
+  const pngUrl = (pngAsset as unknown as { default: string }).default
+  return {
+    resvgWasm: fetch(resvgUrl) as unknown as ResvgWasmInput,
+    pngWasm: fetch(pngUrl) as unknown as PngWasmInput,
+  }
+}
+
+function ensureInit(): Promise<void> {
+  if (!initialized) {
+    initialized = defaultWasmInputs()
+      .then((options) =>
+        Promise.all([initWasm(options.resvgWasm as ResvgWasmInput), initPngCodec(options.pngWasm as PngWasmInput)]),
+      )
+      .then(() => undefined)
+  }
+  return initialized
+}
+
+interface RgbaLike {
+  data: Uint8Array
+  width: number
+  height: number
+}
+
+/** Encodes RGBA pixels through @jsquash/png (it requires an exact-size buffer). */
+async function encodeRgba(data: Uint8Array, width: number, height: number): Promise<Uint8Array> {
+  const imageData = { data: new Uint8Array(data), width, height } as unknown as ImageData
+  const png = await pngEncodeWasm(imageData)
+  return new Uint8Array(png)
+}
+
+/** Renders at the SVG's intrinsic size, returning the pixel raster. */
+async function renderResvgIntrinsic(svg: string): Promise<RgbaLike> {
+  await ensureInit()
+  const renderer = new Resvg(svg, {
+    fitTo: { mode: 'original' },
+    font: { loadSystemFonts: false },
+  })
+  const rendered = renderer.render()
+  const result = { data: new Uint8Array(rendered.pixels), width: rendered.width, height: rendered.height }
+  renderer.free()
+  return result
+}
+
+/** Renders and enforces exact target dimensions, mirroring the call-site checks. */
+async function renderResvg(svg: string, width: number, height: number, what: string): Promise<RgbaLike> {
+  const raw = await renderResvgIntrinsic(svg)
+  if (raw.width !== width || raw.height !== height) {
+    throw new QrPosterError(
+      'IMAGE_PROCESSING_FAILED',
+      `${what} produced ${raw.width}x${raw.height} instead of ${width}x${height}.`,
+      3,
+    )
+  }
+  return raw
+}
+
+export const browserImaging: Imaging = {
+  async decodePng(file: Uint8Array): Promise<RawImage> {
+    try {
+      const bytes = new Uint8Array(file)
+      const imageData = (await pngDecodeWasm(bytes.buffer)) as unknown as RgbaLike
+      const { width, height } = imageData
+      if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0)
+        throw new Error('undecodable PNG dimensions')
+      if (width * height > PNG_DECODE_PIXEL_LIMIT) throw new Error('exceeds the pixel limit')
+      return { data: new Uint8Array(imageData.data), width, height }
+    } catch (error) {
+      throw new QrPosterError('INVALID_INPUT', 'Could not decode the image as PNG.', 2, { cause: error })
+    }
+  },
+
+  async encodePngRgba(data: Uint8Array, width: number, height: number): Promise<Uint8Array> {
+    return encodeRgba(data, width, height)
+  },
+
+  async encodePngGrayscale(data: Uint8Array, width: number, height: number): Promise<Uint8Array> {
+    // Expand one byte per pixel to opaque gray RGBA; PNG bytes differ between encoders,
+    // decoded pixels do not.
+    const rgba = new Uint8Array(width * height * 4)
+    for (let index = 0; index < data.length; index++) {
+      const value = data[index]!
+      rgba[index * 4] = value
+      rgba[index * 4 + 1] = value
+      rgba[index * 4 + 2] = value
+      rgba[index * 4 + 3] = 255
+    }
+    return encodeRgba(rgba, width, height)
+  },
+
+  async rasterizeSvg(svg: string, width: number, height: number): Promise<RawImage> {
+    return renderResvg(svg, width, height, 'SVG rasterization')
+  },
+
+  async renderSvgToPng(svg: string, options: SvgRenderOptions): Promise<RenderedSvgPng> {
+    const raw = await renderResvgIntrinsic(svg)
+    const pixels = options.flatten ? flattenOverWhite(raw.data) : raw.data
+    const png = await encodeRgba(pixels, raw.width, raw.height)
+    return { png, width: raw.width, height: raw.height }
+  },
+
+  async composeQrPng(basePng: Uint8Array, overlaySvgs: string[]): Promise<Uint8Array> {
+    const base = await this.decodePng(basePng)
+    const overlays = overlaySvgs.filter((svg) => svg.length > 0)
+    const rasters: RawImage[] = []
+    for (const svg of overlays)
+      rasters.push(await renderResvg(svg, base.width, base.height, 'QR overlay rasterization'))
+    const composited = overlays.length > 0 ? compositeOver(base, rasters) : Uint8Array.from(base.data)
+    return encodeRgba(composited, base.width, base.height)
+  },
+
+  async normalizeQrPng(file: Uint8Array, targetSize: number): Promise<Uint8Array> {
+    const source = await this.decodePng(file)
+    const flattened = flattenOverWhite(source.data)
+    const resized =
+      source.width === targetSize
+        ? flattened
+        : resizeNearest({ data: flattened, width: source.width, height: source.height }, targetSize, targetSize)
+    return encodeRgba(resized, targetSize, targetSize)
+  },
+
+  async sha256Hex(input: string | Uint8Array): Promise<string> {
+    const bytes = typeof input === 'string' ? new TextEncoder().encode(input) : new Uint8Array(input)
+    const digest = await crypto.subtle.digest('SHA-256', bytes.slice().buffer)
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+  },
+}

package/src/core/imaging/cloudflare.ts

@@ -0,0 +1,15 @@
+import type { InitInput as PngWasmInput } from '@jsquash/png/codec/pkg/squoosh_png.js'
+// Cloudflare bundles this import as a WebAssembly.Module; the package's adjacent
+// declaration describes the wasm-bindgen JavaScript exports instead.
+// @ts-expect-error Worker WASM module import is typed by src/types/wasm.d.ts.
+import pngWasm from '@jsquash/png/codec/pkg/squoosh_png_bg.wasm'
+import type { InitInput as ResvgWasmInput } from '@resvg/resvg-wasm'
+import resvgWasm from '@resvg/resvg-wasm/index_bg.wasm'
+import { setImaging } from './index'
+import { browserImaging, installBrowserImaging } from './browser'
+
+/** Installs the same codec backend used in the browser worker using bundled Worker WASM modules. */
+export const cloudflareImagingReady = installBrowserImaging({
+  resvgWasm: resvgWasm as ResvgWasmInput,
+  pngWasm: pngWasm as PngWasmInput,
+}).then(() => setImaging(browserImaging))

package/src/core/imaging/index.ts

@@ -0,0 +1,14 @@
+import type { Imaging } from './types'
+
+let active: Imaging | null = null
+
+/** Installs one backend. Entry points only (test setup, scripts, route handlers, the worker). */
+export function setImaging(backend: Imaging): void {
+  active = backend
+}
+
+/** The installed backend. Core modules call this instead of importing sharp directly. */
+export function imaging(): Imaging {
+  if (!active) throw new Error('Imaging backend not installed: this entry point must call setImaging().')
+  return active
+}

package/src/core/imaging/node.ts

@@ -0,0 +1,95 @@
+/** The Node imaging backend. Every operation mirrors the exact sharp pipeline the call
+ * site used before the seam, so Node-side output bytes stay bit-identical after extraction. */
+
+import { createHash } from 'node:crypto'
+import sharp from 'sharp'
+import { QrPosterError } from '../errors'
+import type { Imaging, RawImage, RenderedSvgPng, SvgRenderOptions } from './types'
+
+export const nodeImaging: Imaging = {
+  async decodePng(file: Uint8Array): Promise<RawImage> {
+    try {
+      const bytes = Buffer.from(file.buffer, file.byteOffset, file.byteLength)
+      const source = sharp(bytes, { failOn: 'error', limitInputPixels: 16_000_000 })
+      const metadata = await source.metadata()
+      if (metadata.format !== 'png' || !metadata.width || !metadata.height) throw new Error('not a decodable PNG')
+      const { data, info } = await source.ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+      return {
+        data,
+        width: info.width,
+        height: info.height,
+      }
+    } catch (error) {
+      throw new QrPosterError('INVALID_INPUT', 'Could not decode the image as PNG.', 2, { cause: error })
+    }
+  },
+
+  async encodePngRgba(data: Uint8Array, width: number, height: number): Promise<Uint8Array> {
+    const png = await sharp(Buffer.from(data.buffer, data.byteOffset, data.byteLength), {
+      raw: { width, height, channels: 4 },
+    })
+      .png()
+      .toBuffer()
+    return png
+  },
+
+  async encodePngGrayscale(data: Uint8Array, width: number, height: number): Promise<Uint8Array> {
+    const png = await sharp(Buffer.from(data.buffer, data.byteOffset, data.byteLength), {
+      raw: { width, height, channels: 1 },
+    })
+      .png()
+      .toBuffer()
+    return png
+  },
+
+  async rasterizeSvg(svg: string, width: number, height: number): Promise<RawImage> {
+    const { data, info } = await sharp(Buffer.from(svg)).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+    if (info.width !== width || info.height !== height) {
+      throw new QrPosterError(
+        'IMAGE_PROCESSING_FAILED',
+        `SVG rasterization produced ${info.width}x${info.height} instead of ${width}x${height}.`,
+        3,
+      )
+    }
+    return { data, width: info.width, height: info.height }
+  },
+
+  async renderSvgToPng(svg: string, options: SvgRenderOptions): Promise<RenderedSvgPng> {
+    const raster = sharp(Buffer.from(svg))
+    const { data, info } = await (options.flatten ? raster.flatten({ background: '#ffffff' }) : raster)
+      .png()
+      .toBuffer({ resolveWithObject: true })
+    return {
+      png: data,
+      width: info.width,
+      height: info.height,
+    }
+  },
+
+  async composeQrPng(basePng: Uint8Array, overlaySvgs: string[]): Promise<Uint8Array> {
+    const composites = overlaySvgs.filter((svg) => svg.length > 0).map((svg) => ({ input: Buffer.from(svg) }))
+    const png =
+      composites.length === 0
+        ? await sharp(Buffer.from(basePng.buffer, basePng.byteOffset, basePng.byteLength))
+            .png()
+            .toBuffer()
+        : await sharp(Buffer.from(basePng.buffer, basePng.byteOffset, basePng.byteLength))
+            .composite(composites)
+            .png()
+            .toBuffer()
+    return png
+  },
+
+  async normalizeQrPng(file: Uint8Array, targetSize: number): Promise<Uint8Array> {
+    const png = await sharp(Buffer.from(file.buffer, file.byteOffset, file.byteLength))
+      .flatten({ background: '#ffffff' })
+      .resize(targetSize, targetSize, { fit: 'fill', kernel: sharp.kernel.nearest })
+      .png()
+      .toBuffer()
+    return png
+  },
+
+  async sha256Hex(input: string | Uint8Array): Promise<string> {
+    return createHash('sha256').update(input).digest('hex')
+  },
+}