@hxa-rn/rn-qr-generator 2.0.0-beta.1

package/harmony/qr_generator/src/main/ets/ZxingImageHelper.ets

@@ -0,0 +1,1449 @@
+/*
+ * RNQrGenerator image / ZXing helper for HarmonyOS.
+ *
+ * Implements the same behavior as the Android RNQrGeneratorModule:
+ *  - generate: MultiFormatWriter.encode (ERROR_CORRECTION / CHARACTER_SET / MARGIN hints)
+ *              -> BitMatrix -> RGBA_8888 buffer -> PixelMap -> PNG bytes -> cacheDir file -> sandbox URI
+ *  - detect:   uri/base64 -> PixelMap -> RGBA -> luminance ((R+2G+B)/4)
+ *              -> RGBLuminanceSource + HybridBinarizer + MultiFormatReader decode,
+ *              with Android-aligned multi-round retry:
+ *              original -> inverted -> 3 relative crops -> 1.2/1.5/2.0 zoom.
+ */
+
+import { MultiFormatWriter, BarcodeFormat, EncodeHintType, QRCodeDecoderErrorCorrectionLevel,
+  MultiFormatReader, DecodeHintType, BinaryBitmap, HybridBinarizer, GlobalHistogramBinarizer,
+  RGBLuminanceSource, InvertedLuminanceSource, Result, ResultMetadataType, ZXingStringEncoding,
+  LuminanceSource, DataMatrixReader, PDF417Reader, Reader } from '@ohos/zxing';
+import { image } from '@kit.ImageKit';
+import { fileIo as fs, fileUri } from '@kit.CoreFileKit';
+import { util } from '@kit.ArkTS';
+import { hilog } from '@kit.PerformanceAnalysisKit';
+import { TM } from './generated/ts';
+
+const TAG: string = 'RNQrGenerator';
+const DOMAIN: number = 0x0000;
+const MAX_SCAN_DIMENSION: number = 1280;
+
+/**
+ * 16 formats for general multi-format scan. MaxiCode is excluded because its reader
+ * assumes a pure barcode image and can abort the process when invoked from crop/zoom
+ * retries or inverted passes on album photos.
+ */
+const STANDARD_DECODE_FORMATS: BarcodeFormat[] = [
+  BarcodeFormat.AZTEC,
+  BarcodeFormat.CODABAR,
+  BarcodeFormat.CODE_39,
+  BarcodeFormat.CODE_93,
+  BarcodeFormat.CODE_128,
+  BarcodeFormat.DATA_MATRIX,
+  BarcodeFormat.EAN_8,
+  BarcodeFormat.EAN_13,
+  BarcodeFormat.ITF,
+  BarcodeFormat.PDF_417,
+  BarcodeFormat.QR_CODE,
+  BarcodeFormat.RSS_14,
+  BarcodeFormat.RSS_EXPANDED,
+  BarcodeFormat.UPC_A,
+  BarcodeFormat.UPC_E,
+  BarcodeFormat.UPC_EAN_EXTENSION,
+];
+
+const MAXICODE_DECODE_FORMATS: BarcodeFormat[] = [BarcodeFormat.MAXICODE];
+
+/** 2D matrix symbologies that MultiFormatReader may miss on @ohos/zxing; retried with dedicated readers. */
+const MATRIX_SYMBOLOGY_READERS: Reader[] = [
+  new DataMatrixReader(),
+  new PDF417Reader(),
+];
+
+/** Result of generate(), mirrors JS GenerateResult. */
+export interface GenerateResultData {
+  uri: string;
+  width: number;
+  height: number;
+  base64?: string;
+}
+
+/** Result of detect(), mirrors JS DetectResult. */
+export interface DetectResultData {
+  values: string[];
+  type: string;
+  types?: string[];
+  correctionLevel?: string;
+}
+
+/** Plain scan payload returned from the taskpool worker. */
+export interface DetectScanPayload {
+  values: string[];
+  type: string;
+  types?: string[];
+  correctionLevel?: string;
+}
+
+export interface DetectScanInput {
+  lum: Uint8ClampedArray;
+  w: number;
+  h: number;
+}
+
+interface LuminanceData {
+  lum: Uint8ClampedArray;
+  w: number;
+  h: number;
+}
+
+interface ImageSize {
+  width: number;
+  height: number;
+}
+
+interface PaddingInsets {
+  top: number;
+  left: number;
+  bottom: number;
+  right: number;
+}
+
+interface ScanRegion {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+interface ScanRetryOptions {
+  /** Full-image scanBasic already ran in scanAllResults. */
+  skipInitialBasic?: boolean;
+  /** Use DataMatrix/PDF417 dedicated readers during crop/zoom retries. */
+  dedicatedMatrixReaders?: boolean;
+}
+
+/** Pixel budget above which zoom retries are skipped to avoid OOM on album photos. */
+const MAX_RETRY_ZOOM_PIXELS: number = 512 * 512;
+/** Pixel budget above which crop retries are reduced to a single pass. */
+const MAX_RETRY_CROP_PIXELS: number = 1024 * 1024;
+
+export class ZxingImageHelper {
+  /**
+   * Generate a QR code PNG and write it to the cache directory.
+   * Resolves with { uri, width, height, base64? }; rejects with error message string.
+   */
+  static generate(options: TM.RNQrGenerator.GenerateOptions, cacheDir: string): Promise<GenerateResultData> {
+    return new Promise<GenerateResultData>((resolve, reject) => {
+      try {
+        ZxingImageHelper.ensureSafeStringCodec();
+        const value: string = options.value ?? '';
+        const fileName: string = options.fileName ?? '';
+        const correctionLevel: string = options.correctionLevel ?? 'H';
+        const width: number = options.width ?? 100;
+        const height: number = options.height ?? 100;
+        const backgroundColor: number = options.backgroundColor ?? 0xFFFFFFFF;
+        const color: number = options.color ?? 0xFF000000;
+        const base64: boolean = options.base64 ?? false;
+
+        if (value.length === 0) {
+          reject('Property "value" is missing');
+          return;
+        }
+
+        const insets = ZxingImageHelper.parsePaddingFromOptions(options);
+        const top: number = insets.top;
+        const left: number = insets.left;
+        const bottom: number = insets.bottom;
+        const right: number = insets.right;
+
+        const hasPadding: boolean = top !== 0 || left !== 0 || bottom !== 0 || right !== 0;
+        // Android-aligned: subtract padding from encode dimensions first, then expand the
+        // output canvas to matrixSize + padding (not a fixed width×height clip rect).
+        const encodeW: number = width - left - right;
+        const encodeH: number = height - top - bottom;
+        if (hasPadding && (encodeW < 1 || encodeH < 1)) {
+          reject('padding exceeds image dimensions');
+          return;
+        }
+
+        const qrWidth: number = hasPadding ? encodeW : width;
+        const qrHeight: number = hasPadding ? encodeH : height;
+
+        // Build encode hints, aligned with Android generateQrCode (MARGIN=0, padding handled separately).
+        const hints = new Map<EncodeHintType, Object>();
+        hints.set(EncodeHintType.ERROR_CORRECTION, ZxingImageHelper.parseCorrectionLevel(correctionLevel));
+        hints.set(EncodeHintType.CHARACTER_SET, 'UTF-8');
+        hints.set(EncodeHintType.MARGIN, 0);
+
+        const writer: MultiFormatWriter = new MultiFormatWriter();
+        const matrix = writer.encode(value, BarcodeFormat.QR_CODE, qrWidth, qrHeight, hints);
+        const matrixW: number = matrix.getWidth();
+        const matrixH: number = matrix.getHeight();
+
+        // Fill the QR pixel buffer (RGBA_8888 byte order R,G,B,A) from the BitMatrix.
+        const qrBuf: ArrayBuffer = new ArrayBuffer(matrixW * matrixH * 4);
+        const qrArr: Uint8ClampedArray = new Uint8ClampedArray(qrBuf);
+        for (let y = 0; y < matrixH; y++) {
+          for (let x = 0; x < matrixW; x++) {
+            const on: boolean = matrix.get(x, y);
+            const c: number = on ? color : backgroundColor;
+            const idx: number = (y * matrixW + x) * 4;
+            qrArr[idx] = (c >> 16) & 0xFF;
+            qrArr[idx + 1] = (c >> 8) & 0xFF;
+            qrArr[idx + 2] = c & 0xFF;
+            const a: number = (c >> 24) & 0xFF;
+            qrArr[idx + 3] = a === 0 ? 0xFF : a;
+          }
+        }
+
+        // When padding is non-zero, expand the canvas to fit the encoded QR plus insets,
+        // fill with background, and draw the QR bitmap at (left, top). Matches Android.
+        let finalW: number = matrixW;
+        let finalH: number = matrixH;
+        let finalBuffer: ArrayBuffer = qrBuf;
+        if (hasPadding) {
+          finalW = matrixW + left + right;
+          finalH = matrixH + top + bottom;
+          const outBuf: ArrayBuffer = new ArrayBuffer(finalW * finalH * 4);
+          const outArr: Uint8ClampedArray = new Uint8ClampedArray(outBuf);
+          for (let i = 0; i < finalW * finalH; i++) {
+            const idx: number = i * 4;
+            outArr[idx] = (backgroundColor >> 16) & 0xFF;
+            outArr[idx + 1] = (backgroundColor >> 8) & 0xFF;
+            outArr[idx + 2] = backgroundColor & 0xFF;
+            const a: number = (backgroundColor >> 24) & 0xFF;
+            outArr[idx + 3] = a === 0 ? 0xFF : a;
+          }
+          for (let y = 0; y < matrixH; y++) {
+            for (let x = 0; x < matrixW; x++) {
+              const srcIdx: number = (y * matrixW + x) * 4;
+              const dstIdx: number = ((y + top) * finalW + (x + left)) * 4;
+              outArr[dstIdx] = qrArr[srcIdx];
+              outArr[dstIdx + 1] = qrArr[srcIdx + 1];
+              outArr[dstIdx + 2] = qrArr[srcIdx + 2];
+              outArr[dstIdx + 3] = qrArr[srcIdx + 3];
+            }
+          }
+          finalBuffer = outBuf;
+        }
+
+        const initOptions: image.InitializationOptions = {
+          size: { width: finalW, height: finalH },
+          srcPixelFormat: image.PixelMapFormat.RGBA_8888,
+          pixelFormat: image.PixelMapFormat.RGBA_8888,
+          editable: true,
+        };
+        const pixelMap: image.PixelMap = image.createPixelMapSync(finalBuffer, initOptions);
+
+        const packer: image.ImagePacker = image.createImagePacker();
+        const packOptions: image.PackingOption = { format: 'image/png', quality: 100 };
+        packer.packToData(pixelMap, packOptions).then((pngBytes: ArrayBuffer) => {
+          try {
+            const name: string = fileName.length > 0 ? fileName : util.generateRandomUUID();
+            const nameWithExt: string = name.endsWith('.png') ? name : name + '.png';
+            const filePath: string = cacheDir + '/' + nameWithExt;
+            let file: fs.File | undefined;
+            try {
+              const openMode =
+                fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE | fs.OpenMode.TRUNC;
+              file = fs.openSync(filePath, openMode);
+              fs.writeSync(file.fd, pngBytes);
+            } finally {
+              if (file !== undefined) {
+                fs.closeSync(file);
+              }
+            }
+
+            const result: GenerateResultData = {
+              uri: fileUri.getUriFromPath(filePath),
+              width: finalW,
+              height: finalH,
+            };
+            if (base64) {
+              const b64Helper: util.Base64Helper = new util.Base64Helper();
+              result.base64 = b64Helper.encodeToStringSync(new Uint8Array(pngBytes));
+            }
+            resolve(result);
+          } catch (e) {
+            const err: Error = e as Error;
+            hilog.error(DOMAIN, TAG, 'generate write failed: %{public}s', ZxingImageHelper.errMsg(err));
+            reject(err.message);
+          }
+        }).catch((err: Object) => {
+          const e: Error = err as Error;
+          hilog.error(DOMAIN, TAG, 'generate packToData failed: %{public}s', ZxingImageHelper.errMsg(e));
+          reject(e.message);
+        });
+      } catch (e) {
+        const err: Error = e as Error;
+        hilog.error(DOMAIN, TAG, 'generate failed: %{public}s', ZxingImageHelper.errMsg(err));
+        reject(err.message);
+      }
+    });
+  }
+
+  /**
+   * Detect/decode a barcode from a local image uri or base64 string.
+   * Resolves with { values: string[], type: string }; on image load failure rejects 'IMAGE_NOT_FOUND'.
+   */
+  static detect(options: TM.RNQrGenerator.DetectOptions): Promise<DetectResultData> {
+    return ZxingImageHelper.prepareDetectInput(options).then((input: DetectScanInput | null) => {
+      if (input === null) {
+        const emptyResult: DetectResultData = { values: [], type: '' };
+        return emptyResult;
+      }
+      return ZxingImageHelper.buildDetectPayload(
+        ZxingImageHelper.scanAllResultsInternal(input.lum, input.w, input.h));
+    }).catch((err: Object) => {
+      const msg: string = ZxingImageHelper.errMsg(err as Error);
+      if (msg.includes('IMAGE_NOT_FOUND') || msg.includes('No such file') || msg.includes('not found')) {
+        throw new Error(msg);
+      }
+      hilog.error(DOMAIN, TAG, 'detect failed: %{public}s', msg);
+      const emptyResult: DetectResultData = { values: [], type: '' };
+      return emptyResult;
+    });
+  }
+
+  static prepareDetectInput(options: TM.RNQrGenerator.DetectOptions): Promise<DetectScanInput | null> {
+    return new Promise<DetectScanInput | null>((resolve, reject) => {
+      const uri: string = options.uri ?? '';
+      const base64: string = options.base64 ?? '';
+      if (uri.length === 0 && base64.length === 0) {
+        reject('IMAGE_NOT_FOUND');
+        return;
+      }
+
+      let pixelMap: image.PixelMap | undefined = undefined;
+      try {
+        pixelMap = ZxingImageHelper.loadPixelMap(uri, base64);
+        pixelMap = ZxingImageHelper.preparePixelMapForScan(pixelMap);
+        const extracted: LuminanceData = ZxingImageHelper.extractLuminance(pixelMap);
+        resolve({
+          lum: new Uint8ClampedArray(extracted.lum),
+          w: extracted.w,
+          h: extracted.h,
+        });
+      } catch (e) {
+        if (uri.length > 0) {
+          reject('IMAGE_NOT_FOUND');
+          return;
+        }
+        reject(e as Error);
+      } finally {
+        if (pixelMap !== undefined) {
+          try {
+            pixelMap.release();
+          } catch (releaseErr) {
+            hilog.warn(
+              DOMAIN,
+              TAG,
+              'detect release pixelMap failed: %{public}s',
+              ZxingImageHelper.errMsg(releaseErr as Error)
+            );
+          }
+        }
+      }
+    });
+  }
+
+  /** Entry for taskpool worker; keeps heavy ZXing work off the UI thread. */
+  static scanForDetectWorker(lum: Uint8ClampedArray, w: number, h: number): DetectScanPayload {
+    ZxingImageHelper.ensureSafeStringCodec();
+    return ZxingImageHelper.buildDetectPayload(ZxingImageHelper.scanAllResultsInternal(lum, w, h));
+  }
+
+  private static scanAllResultsInternal(lum: Uint8ClampedArray, w: number, h: number): Result[] {
+    try {
+      return ZxingImageHelper.scanAllResults(lum, w, h);
+    } catch (scanErr) {
+      hilog.error(DOMAIN, TAG, 'scanAllResults failed: %{public}s', ZxingImageHelper.errMsg(scanErr as Error));
+      return [];
+    }
+  }
+
+  private static buildDetectPayload(results: Result[]): DetectScanPayload {
+    if (results.length === 0) {
+      return { values: [], type: '' };
+    }
+    const values: string[] = [];
+    const types: string[] = [];
+    for (let i = 0; i < results.length; i++) {
+      try {
+        values.push(ZxingImageHelper.copyDecodedText(results[i].getText()));
+        types.push(ZxingImageHelper.getCodeType(results[i].getBarcodeFormat()));
+      } catch (textErr) {
+        hilog.warn(DOMAIN, TAG, 'getText failed: %{public}s', ZxingImageHelper.errMsg(textErr as Error));
+      }
+    }
+    if (values.length === 0) {
+      return { values: [], type: '' };
+    }
+    const payload: DetectScanPayload = {
+      values: values,
+      type: types[0],
+      types: types,
+    };
+    const correctionLevel: string | undefined = ZxingImageHelper.extractCorrectionLevel(results[0]);
+    if (correctionLevel !== undefined) {
+      payload.correctionLevel = correctionLevel;
+    }
+    return payload;
+  }
+
+  /** Read RGBA from PixelMap and compute luminance; honors row stride when present. */
+  private static extractLuminance(pixelMap: image.PixelMap): LuminanceData {
+    const info: image.ImageInfo = pixelMap.getImageInfoSync();
+    const w: number = info.size.width;
+    const h: number = info.size.height;
+    const bufferSize: number = pixelMap.getPixelBytesNumber();
+    const rowBytes: number = pixelMap.getBytesNumberPerRow();
+    const buf: ArrayBuffer = new ArrayBuffer(bufferSize);
+    pixelMap.readPixelsToBufferSync(buf);
+    const rgba: Uint8ClampedArray = new Uint8ClampedArray(buf);
+    const lum: Uint8ClampedArray = new Uint8ClampedArray(w * h);
+    for (let y = 0; y < h; y++) {
+      const rowBase: number = y * rowBytes;
+      for (let x = 0; x < w; x++) {
+        const j: number = rowBase + x * 4;
+        const alpha: number = rgba[j + 3];
+        if (alpha < 16) {
+          // PNG transparency must not become black bars that break MaxiCode pure-bit extraction.
+          lum[y * w + x] = 255;
+          continue;
+        }
+        if (alpha < 255) {
+          const scale: number = alpha / 255;
+          const r: number = 255 * (1 - scale) + rgba[j] * scale;
+          const g: number = 255 * (1 - scale) + rgba[j + 1] * scale;
+          const b: number = 255 * (1 - scale) + rgba[j + 2] * scale;
+          lum[y * w + x] = (r + g * 2 + b) / 4;
+          continue;
+        }
+        lum[y * w + x] = (rgba[j] + rgba[j + 1] * 2 + rgba[j + 2]) / 4;
+      }
+    }
+    return { lum: lum, w: w, h: h };
+  }
+
+  /** Downscale very large images before decode to avoid UI freeze/OOM on album photos. */
+  private static preparePixelMapForScan(pixelMap: image.PixelMap): image.PixelMap {
+    const info: image.ImageInfo = pixelMap.getImageInfoSync();
+    const w: number = info.size.width;
+    const h: number = info.size.height;
+    const maxSide: number = Math.max(w, h);
+    if (maxSide <= MAX_SCAN_DIMENSION) {
+      return pixelMap;
+    }
+    const scale: number = MAX_SCAN_DIMENSION / maxSide;
+    pixelMap.scaleSync(scale, scale);
+    return pixelMap;
+  }
+
+  private static computeDesiredSize(width: number, height: number): ImageSize {
+    const maxSide: number = Math.max(width, height);
+    if (maxSide <= MAX_SCAN_DIMENSION) {
+      return { width: width, height: height };
+    }
+    const scale: number = MAX_SCAN_DIMENSION / maxSide;
+    return {
+      width: Math.max(1, Math.round(width * scale)),
+      height: Math.max(1, Math.round(height * scale)),
+    };
+  }
+
+  private static buildDecodingOptions(sourceSize?: ImageSize): image.DecodingOptions {
+    const options: image.DecodingOptions = {
+      editable: true,
+      desiredPixelFormat: image.PixelMapFormat.RGBA_8888,
+    };
+    if (sourceSize !== undefined) {
+      options.desiredSize = ZxingImageHelper.computeDesiredSize(sourceSize.width, sourceSize.height);
+    }
+    return options;
+  }
+
+  private static readSourceSize(source: image.ImageSource): ImageSize | undefined {
+    try {
+      const info: image.ImageInfo = source.getImageInfoSync();
+      return { width: info.size.width, height: info.size.height };
+    } catch (e) {
+      return undefined;
+    }
+  }
+
+  private static loadPixelMap(uri: string, base64: string): image.PixelMap {
+    if (uri.length > 0) {
+      const path: string = ZxingImageHelper.normalizeSourcePath(uri);
+      return ZxingImageHelper.loadPixelMapFromPath(path);
+    }
+    const b64: string = base64.includes(',') ? base64.substring(base64.indexOf(',') + 1) : base64;
+    try {
+      const b64Helper: util.Base64Helper = new util.Base64Helper();
+      const bytes: Uint8Array = b64Helper.decodeSync(b64);
+      const copyBuf: ArrayBuffer = new ArrayBuffer(bytes.byteLength);
+      new Uint8Array(copyBuf).set(bytes);
+      const source: image.ImageSource = image.createImageSource(copyBuf);
+      try {
+        const sourceSize = ZxingImageHelper.readSourceSize(source);
+        return source.createPixelMapSync(ZxingImageHelper.buildDecodingOptions(sourceSize));
+      } finally {
+        try {
+          source.release();
+        } catch (releaseErr) {
+          hilog.warn(
+            DOMAIN,
+            TAG,
+            'loadPixelMap base64 release failed: %{public}s',
+            ZxingImageHelper.errMsg(releaseErr as Error)
+          );
+        }
+      }
+    } catch (e) {
+      const err3: Error = e as Error;
+      hilog.error(DOMAIN, TAG, 'loadPixelMap base64 decode failed: %{public}s', ZxingImageHelper.errMsg(err3));
+      throw err3;
+    }
+  }
+
+  /**
+   * Multi-round scan, aligned with Android scanBitmap:
+   *   original -> inverted -> 3 relative crop configs -> 1.2/1.5/2.0 zoom on each crop.
+   * Returns the first successful Result, or null when nothing decodes.
+   */
+  private static scanWithRetries(lum: Uint8ClampedArray, w: number, h: number,
+    options?: ScanRetryOptions): Result | null {
+    try {
+      const pixelCount: number = w * h;
+      const hints: Map<DecodeHintType, Object> =
+        ZxingImageHelper.createDecodeHints(pixelCount <= MAX_RETRY_ZOOM_PIXELS);
+      if (options?.skipInitialBasic !== true) {
+        const basicResult: Result | null = ZxingImageHelper.scanBasic(lum, w, h, hints);
+        if (basicResult !== null) {
+          return basicResult;
+        }
+      }
+
+      const cropConfigs: number[][] = pixelCount > MAX_RETRY_CROP_PIXELS
+        ? [[0.15, 0.05, 0.35, 0.05]]
+        : [
+          [0.15, 0.05, 0.35, 0.05],
+          [0.25, 0.05, 0.25, 0.05],
+          [0.35, 0.05, 0.15, 0.05],
+        ];
+      const zoomFactors: number[] = pixelCount > MAX_RETRY_ZOOM_PIXELS
+        ? []
+        : pixelCount > MAX_RETRY_ZOOM_PIXELS / 2
+          ? [1.2]
+          : [1.2, 1.5, 2.0];
+
+    for (let c = 0; c < cropConfigs.length; c++) {
+      const config: number[] = cropConfigs[c];
+      const topInset: number = config[0];
+      const leftInset: number = config[1];
+      const bottomInset: number = config[2];
+      const rightInset: number = config[3];
+
+      if (topInset + bottomInset >= 1.0 || leftInset + rightInset >= 1.0) {
+        continue;
+      }
+      const left: number = Math.max(0, Math.round(leftInset * w));
+      const top: number = Math.max(0, Math.round(topInset * h));
+      const right: number = Math.max(0, Math.round(rightInset * w));
+      const bottom: number = Math.max(0, Math.round(bottomInset * h));
+      const cropW: number = w - left - right;
+      const cropH: number = h - top - bottom;
+      if (cropW <= 0 || cropH <= 0) {
+        continue;
+      }
+
+      // Crop via RGBLuminanceSource sub-region (no second image decode needed).
+      const croppedSource: RGBLuminanceSource = new RGBLuminanceSource(lum, cropW, cropH, w, h, left, top);
+      const croppedResult: Result | null = options?.dedicatedMatrixReaders === true
+        ? ZxingImageHelper.decodeWithDedicatedMatrixReaders(croppedSource, hints)
+        : ZxingImageHelper.decodeOnSource(croppedSource, hints);
+      if (croppedResult !== null) {
+        return croppedResult;
+      }
+
+      for (let z = 0; z < zoomFactors.length; z++) {
+        const zoom: number = zoomFactors[z];
+        if (zoom <= 1.0) {
+          continue;
+        }
+        try {
+          const zoomedSource: RGBLuminanceSource =
+            ZxingImageHelper.scaleLuminance(croppedSource.getMatrix(), cropW, cropH, zoom);
+          const zoomedResult: Result | null = options?.dedicatedMatrixReaders === true
+            ? ZxingImageHelper.decodeWithDedicatedMatrixReaders(zoomedSource, hints)
+            : ZxingImageHelper.decodeOnSource(zoomedSource, hints);
+          if (zoomedResult !== null) {
+            return zoomedResult;
+          }
+        } catch (e) {
+          // continue with next zoom / crop
+        }
+      }
+    }
+
+    return null;
+    } catch (retryErr) {
+      hilog.warn(DOMAIN, TAG, 'scanWithRetries failed: %{public}s', ZxingImageHelper.errMsg(retryErr as Error));
+      return null;
+    }
+  }
+
+  /**
+   * Collect multiple barcodes with a bounded scan plan.
+   *
+   * A full-image scan runs first so normal single-code images return promptly.
+   * Lightweight QR-only region probes then collect additional codes for F02-005.
+   * Expensive crop/zoom retries run once on the full image only when neither
+   * basic path succeeds, preserving difficult single-code behavior without
+   * multiplying the heavy path across regions.
+   */
+  private static scanAllResults(lum: Uint8ClampedArray, w: number, h: number): Result[] {
+    let maxiResult: Result | null = null;
+    try {
+      maxiResult = ZxingImageHelper.scanMaxiCode(lum, w, h);
+    } catch (maxiErr) {
+      hilog.warn(DOMAIN, TAG, 'scanMaxiCode failed: %{public}s', ZxingImageHelper.errMsg(maxiErr as Error));
+    }
+    if (maxiResult !== null) {
+      return [maxiResult];
+    }
+
+    const pixelCount: number = w * h;
+    const isWideAlbumLayout: boolean = w > h * 1.25;
+    const tryHarder: boolean = !isWideAlbumLayout && pixelCount <= MAX_RETRY_ZOOM_PIXELS;
+    const hints: Map<DecodeHintType, Object> = ZxingImageHelper.createDecodeHints(tryHarder);
+    const fullResult: Result | null =
+      ZxingImageHelper.scanBasic(lum, w, h, hints, !isWideAlbumLayout);
+
+    if (fullResult !== null && !ZxingImageHelper.shouldProbeForAdditionalCodes(w, h)) {
+      return [fullResult];
+    }
+
+    const regionHints: Map<DecodeHintType, Object> = ZxingImageHelper.createMultiRegionDecodeHints();
+    const multiRegions: ScanRegion[] = ZxingImageHelper.buildMultiQrRegions(w, h);
+    const regionalResults: Result[] =
+      ZxingImageHelper.scanRegions(lum, w, h, multiRegions, regionHints);
+    const mergedBasic: Result[] = ZxingImageHelper.mergeUniqueResults(
+      fullResult !== null ? [fullResult] : [],
+      regionalResults,
+    );
+    if (mergedBasic.length > 0) {
+      return mergedBasic;
+    }
+
+    if (fullResult !== null) {
+      return [fullResult];
+    }
+
+    if (isWideAlbumLayout) {
+      let wideFallback: Result | null = null;
+      try {
+        wideFallback = ZxingImageHelper.scanWideAlbumFallback(lum, w, h);
+      } catch (wideErr) {
+        hilog.warn(
+          DOMAIN,
+          TAG,
+          'scanWideAlbumFallback failed: %{public}s',
+          ZxingImageHelper.errMsg(wideErr as Error)
+        );
+      }
+      if (wideFallback !== null) {
+        return [wideFallback];
+      }
+    }
+
+    const enhancedResult: Result | null =
+      ZxingImageHelper.scanWithRetries(lum, w, h, { skipInitialBasic: true });
+    if (enhancedResult !== null) {
+      return [enhancedResult];
+    }
+
+    const matrixFallback: Result | null = ZxingImageHelper.scanMatrixSymbologyFallback(lum, w, h);
+    return matrixFallback === null ? [] : [matrixFallback];
+  }
+
+  /** Aspect ratio suggests side-by-side or stacked multiple codes (F02-005). */
+  private static shouldProbeForAdditionalCodes(w: number, h: number): boolean {
+    return w > h * 1.35 || h > w * 1.35;
+  }
+
+  /** Build a bounded, aspect-aware regional probe set for multi-QR images (F02-005). */
+  private static buildMultiQrRegions(w: number, h: number): ScanRegion[] {
+    const regions: ScanRegion[] = [];
+    const isWide: boolean = w > h * 1.25;
+    const isTall: boolean = h > w * 1.25;
+
+    if (isWide) {
+      ZxingImageHelper.appendThirdColumnBands(regions, w, h);
+      ZxingImageHelper.appendCardStyleHorizontalProbes(regions, w, h);
+      ZxingImageHelper.appendCenteredColumnProbes(regions, w, h, 3);
+      ZxingImageHelper.appendOverlappingHorizontalProbes(regions, w, h);
+    } else if (isTall) {
+      ZxingImageHelper.appendThirdRowBands(regions, w, h);
+      ZxingImageHelper.appendCenteredRowProbes(regions, w, h, 3);
+      ZxingImageHelper.appendOverlappingVerticalProbes(regions, w, h);
+    } else {
+      ZxingImageHelper.appendThirdColumnBands(regions, w, h);
+      ZxingImageHelper.appendThirdRowBands(regions, w, h);
+      ZxingImageHelper.appendCenteredColumnProbes(regions, w, h, 3);
+      ZxingImageHelper.appendCenteredRowProbes(regions, w, h, 3);
+      const halfW: number = Math.floor(w / 2);
+      const halfH: number = Math.floor(h / 2);
+      if (halfW > 0 && halfH > 0) {
+        regions.push({ x: 0, y: 0, width: halfW, height: halfH });
+        regions.push({ x: halfW, y: 0, width: w - halfW, height: halfH });
+        regions.push({ x: 0, y: halfH, width: halfW, height: h - halfH });
+        regions.push({ x: halfW, y: halfH, width: w - halfW, height: h - halfH });
+      }
+    }
+    return regions;
+  }
+
+  private static appendThirdColumnBands(regions: ScanRegion[], w: number, h: number): void {
+    const bandW: number = Math.floor(w / 3);
+    if (bandW <= 0) {
+      return;
+    }
+    regions.push({ x: 0, y: 0, width: bandW, height: h });
+    regions.push({ x: bandW, y: 0, width: bandW, height: h });
+    regions.push({ x: bandW * 2, y: 0, width: w - bandW * 2, height: h });
+  }
+
+  private static appendThirdRowBands(regions: ScanRegion[], w: number, h: number): void {
+    const bandH: number = Math.floor(h / 3);
+    if (bandH <= 0) {
+      return;
+    }
+    regions.push({ x: 0, y: 0, width: w, height: bandH });
+    regions.push({ x: 0, y: bandH, width: w, height: bandH });
+    regions.push({ x: 0, y: bandH * 2, width: w, height: h - bandH * 2 });
+  }
+
+  /**
+   * 50%-height sliding windows (25% step) so 3+ stacked QRs each get a window
+   * where the code is fully contained; tight 1/3 bands alone often miss codes.
+   */
+  private static appendOverlappingVerticalProbes(regions: ScanRegion[], w: number, h: number): void {
+    const probeH: number = Math.max(1, Math.floor(h / 2));
+    const stepH: number = Math.max(1, Math.floor(h / 4));
+    if (probeH >= h) {
+      return;
+    }
+    let y: number = 0;
+    while (y + probeH <= h) {
+      regions.push({ x: 0, y: y, width: w, height: probeH });
+      y += stepH;
+    }
+    const lastY: number = h - probeH;
+    if (lastY > 0) {
+      regions.push({ x: 0, y: lastY, width: w, height: probeH });
+    }
+  }
+
+  /** 50%-width sliding windows (33% step) for side-by-side multi-QR layouts. */
+  private static appendOverlappingHorizontalProbes(regions: ScanRegion[], w: number, h: number): void {
+    const probeW: number = Math.max(1, Math.floor(w / 2));
+    const stepW: number = Math.max(1, Math.floor(w / 3));
+    if (probeW >= w) {
+      return;
+    }
+    let x: number = 0;
+    while (x + probeW <= w) {
+      regions.push({ x: x, y: 0, width: probeW, height: h });
+      x += stepW;
+    }
+    const lastX: number = w - probeW;
+    if (lastX > 0) {
+      regions.push({ x: lastX, y: 0, width: probeW, height: h });
+    }
+  }
+
+  /**
+   * Column-centered windows (~45% image width) aligned to N-column grids so the
+   * rightmost of 3 side-by-side QRs is fully enclosed with quiet zone margin.
+   */
+  private static appendCenteredColumnProbes(regions: ScanRegion[], w: number, h: number,
+    columns: number): void {
+    if (columns <= 0 || w <= 0 || h <= 0) {
+      return;
+    }
+    const cellW: number = w / columns;
+    const probeW: number = Math.max(1, Math.min(w, Math.floor(Math.max(cellW, w * 0.45))));
+    for (let i = 0; i < columns; i++) {
+      const centerX: number = cellW * (i + 0.5);
+      let x: number = Math.floor(centerX - probeW / 2);
+      if (x < 0) {
+        x = 0;
+      }
+      if (x + probeW > w) {
+        x = w - probeW;
+      }
+      if (x < 0) {
+        x = 0;
+      }
+      const width: number = Math.min(probeW, w - x);
+      if (width > 0) {
+        regions.push({ x: x, y: 0, width: width, height: h });
+      }
+    }
+  }
+
+  /**
+   * Wide card-style rows (labels above each code): square crops per column, skipping
+   * the top caption band so ZXing sees one QR per window on album screenshots.
+   */
+  private static appendCardStyleHorizontalProbes(regions: ScanRegion[], w: number, h: number): void {
+    if (w < h * 1.5 || w <= 0 || h <= 0) {
+      return;
+    }
+    ZxingImageHelper.appendCardStyleHorizontalProbesForColumns(regions, w, h, 3);
+  }
+
+  private static appendCardStyleHorizontalProbesForColumns(regions: ScanRegion[], w: number, h: number,
+    columns: number): void {
+    if (columns <= 0) {
+      return;
+    }
+    const cellW: number = w / columns;
+    const topSkip: number = Math.max(0, Math.floor(h * 0.12));
+    const availH: number = h - topSkip;
+    let squareSize: number = Math.floor(Math.min(cellW * 0.92, availH * 0.92));
+    if (squareSize < 32) {
+      return;
+    }
+    for (let i = 0; i < columns; i++) {
+      const centerX: number = cellW * (i + 0.5);
+      let x: number = Math.floor(centerX - squareSize / 2);
+      if (x < 0) {
+        x = 0;
+      }
+      if (x + squareSize > w) {
+        x = w - squareSize;
+      }
+      if (x < 0) {
+        x = 0;
+      }
+      const width: number = Math.min(squareSize, w - x);
+      const height: number = Math.min(squareSize, availH);
+      if (width > 0 && height > 0) {
+        regions.push({ x: x, y: topSkip, width: width, height: height });
+      }
+    }
+  }
+
+  /** Row-centered windows for 3+ vertically stacked QRs (symmetric to column probes). */
+  private static appendCenteredRowProbes(regions: ScanRegion[], w: number, h: number,
+    rows: number): void {
+    if (rows <= 0 || w <= 0 || h <= 0) {
+      return;
+    }
+    const cellH: number = h / rows;
+    const probeH: number = Math.max(1, Math.min(h, Math.floor(Math.max(cellH, h * 0.45))));
+    for (let i = 0; i < rows; i++) {
+      const centerY: number = cellH * (i + 0.5);
+      let y: number = Math.floor(centerY - probeH / 2);
+      if (y < 0) {
+        y = 0;
+      }
+      if (y + probeH > h) {
+        y = h - probeH;
+      }
+      if (y < 0) {
+        y = 0;
+      }
+      const height: number = Math.min(probeH, h - y);
+      if (height > 0) {
+        regions.push({ x: 0, y: y, width: w, height: height });
+      }
+    }
+  }
+
+  private static mergeUniqueResults(first: Result[], second: Result[]): Result[] {
+    const merged: Result[] = [];
+    const seenTexts: string[] = [];
+    const lists: Result[][] = [first, second];
+    for (let i = 0; i < lists.length; i++) {
+      const list: Result[] = lists[i];
+      for (let j = 0; j < list.length; j++) {
+        ZxingImageHelper.appendUniqueResult(merged, seenTexts, list[j]);
+      }
+    }
+    return merged;
+  }
+
+  private static appendUniqueResult(merged: Result[], seenTexts: string[], result: Result): void {
+    let text: string = '';
+    try {
+      text = ZxingImageHelper.copyDecodedText(result.getText());
+    } catch (textErr) {
+      return;
+    }
+    if (text.length === 0) {
+      return;
+    }
+    for (let i = 0; i < seenTexts.length; i++) {
+      if (seenTexts[i] === text) {
+        return;
+      }
+    }
+    seenTexts.push(text);
+    merged.push(result);
+  }
+
+  private static scanRegions(lum: Uint8ClampedArray, srcW: number, srcH: number,
+    regions: ScanRegion[], hints: Map<DecodeHintType, Object>): Result[] {
+    const results: Result[] = [];
+    const tryHarderHints: Map<DecodeHintType, Object> =
+      ZxingImageHelper.createSmallRegionDecodeHints();
+    for (let i = 0; i < regions.length; i++) {
+      const region: ScanRegion = regions[i];
+      const regionLum: Uint8ClampedArray = ZxingImageHelper.copyLuminanceRegion(
+        lum, srcW, srcH, region.x, region.y, region.width, region.height);
+      const useTryHarder: boolean =
+        ZxingImageHelper.shouldUseTryHarderForRegion(region, srcW, srcH);
+      const regionHints: Map<DecodeHintType, Object> = useTryHarder ? tryHarderHints : hints;
+      const result: Result | null =
+        ZxingImageHelper.scanBasic(regionLum, region.width, region.height, regionHints);
+      if (result !== null && result.getText().length > 0) {
+        results.push(result);
+      }
+    }
+    return results;
+  }
+
+  /** TRY_HARDER only on narrow bands and card-style square crops; avoids 2x cost on large windows. */
+  private static shouldUseTryHarderForRegion(region: ScanRegion, srcW: number, srcH: number): boolean {
+    const narrowW: boolean = region.width * 10 <= srcW * 4;
+    const narrowH: boolean = region.height * 10 <= srcH * 4;
+    const topSkip: number = Math.max(0, Math.floor(srcH * 0.12));
+    const isCardCrop: boolean = region.y >= topSkip && region.height <= srcH * 0.88;
+    return narrowW || narrowH || isCardCrop;
+  }
+
+  private static createSmallRegionDecodeHints(): Map<DecodeHintType, Object> {
+    const hints = new Map<DecodeHintType, Object>();
+    hints.set(DecodeHintType.TRY_HARDER, true);
+    hints.set(DecodeHintType.POSSIBLE_FORMATS, STANDARD_DECODE_FORMATS);
+    hints.set(DecodeHintType.CHARACTER_SET, 'UTF-8');
+    return hints;
+  }
+
+  private static createDecodeHints(tryHarder: boolean = true): Map<DecodeHintType, Object> {
+    const hints = new Map<DecodeHintType, Object>();
+    if (tryHarder) {
+      hints.set(DecodeHintType.TRY_HARDER, true);
+    }
+    hints.set(DecodeHintType.POSSIBLE_FORMATS, STANDARD_DECODE_FORMATS);
+    hints.set(DecodeHintType.CHARACTER_SET, 'UTF-8');
+    return hints;
+  }
+
+  /** MaxiCode only: no TRY_HARDER, no inverted pass, bounded to full image (+ one center crop). */
+  private static createMaxiCodeDecodeHints(): Map<DecodeHintType, Object> {
+    const hints = new Map<DecodeHintType, Object>();
+    hints.set(DecodeHintType.POSSIBLE_FORMATS, MAXICODE_DECODE_FORMATS);
+    hints.set(DecodeHintType.CHARACTER_SET, 'UTF-8');
+    return hints;
+  }
+
+  /**
+   * Wide album photos often place the barcode on the left and descriptive text on the right.
+   * Probe those left-biased crops before giving up on a landscape layout.
+   */
+  private static buildWideAlbumLeftRegions(w: number, h: number): ScanRegion[] {
+    const regions: ScanRegion[] = [];
+    if (w <= h * 1.25) {
+      return regions;
+    }
+    const squareW: number = Math.min(h, w);
+    regions.push({ x: 0, y: 0, width: squareW, height: h });
+    const left45: number = Math.max(1, Math.round(w * 0.45));
+    if (left45 !== squareW) {
+      regions.push({ x: 0, y: 0, width: left45, height: h });
+    }
+    const leftW: number = Math.max(1, Math.round(w * 0.55));
+    if (leftW !== squareW && leftW !== left45) {
+      regions.push({ x: 0, y: 0, width: leftW, height: h });
+    }
+    return regions;
+  }
+
+  private static scanWideAlbumFallback(lum: Uint8ClampedArray, w: number, h: number): Result | null {
+    const regions: ScanRegion[] = ZxingImageHelper.buildWideAlbumLeftRegions(w, h);
+    if (regions.length === 0) {
+      return null;
+    }
+    const hints: Map<DecodeHintType, Object> = ZxingImageHelper.createDecodeHints(true);
+    for (let i = 0; i < regions.length; i++) {
+      const region: ScanRegion = regions[i];
+      const regionLum: Uint8ClampedArray = ZxingImageHelper.copyLuminanceRegion(
+        lum, w, h, region.x, region.y, region.width, region.height);
+      const result: Result | null =
+        ZxingImageHelper.scanBasic(regionLum, region.width, region.height, hints, true);
+      if (result !== null) {
+        return result;
+      }
+    }
+    return null;
+  }
+
+  private static scanMaxiCode(lum: Uint8ClampedArray, w: number, h: number): Result | null {
+    const hints: Map<DecodeHintType, Object> = ZxingImageHelper.createMaxiCodeDecodeHints();
+    const regions: ScanRegion[] = ZxingImageHelper.buildWideAlbumLeftRegions(w, h);
+    regions.push({ x: 0, y: 0, width: w, height: h });
+    if (w > 32 && h > 32) {
+      const marginX: number = Math.max(1, Math.round(w * 0.05));
+      const marginY: number = Math.max(1, Math.round(h * 0.05));
+      const cropW: number = w - marginX * 2;
+      const cropH: number = h - marginY * 2;
+      if (cropW > 0 && cropH > 0) {
+        regions.push({ x: marginX, y: marginY, width: cropW, height: cropH });
+      }
+    }
+    for (let i = 0; i < regions.length; i++) {
+      const region: ScanRegion = regions[i];
+      const regionLum: Uint8ClampedArray = region.x === 0 && region.y === 0 &&
+        region.width === w && region.height === h
+        ? lum
+        : ZxingImageHelper.copyLuminanceRegion(
+          lum, w, h, region.x, region.y, region.width, region.height);
+      const result: Result | null =
+        ZxingImageHelper.tryMaxiCodeDecode(regionLum, region.width, region.height, hints);
+      if (result !== null) {
+        return result;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * MaxiCodeReader assumes a nearly-square pure barcode. Skip decode when the binarized
+   * enclosing rectangle is too wide/tall, which otherwise crashes on album composite images.
+   */
+  private static tryMaxiCodeDecode(lum: Uint8ClampedArray, w: number, h: number,
+    hints: Map<DecodeHintType, Object>): Result | null {
+    const source: RGBLuminanceSource = new RGBLuminanceSource(lum, w, h);
+    const hybridResult: Result | null =
+      ZxingImageHelper.tryMaxiCodeOnSource(source, hints, true);
+    if (hybridResult !== null) {
+      return hybridResult;
+    }
+    const globalResult: Result | null =
+      ZxingImageHelper.tryMaxiCodeOnSource(source, hints, false);
+    if (globalResult !== null) {
+      return globalResult;
+    }
+    try {
+      const inverted: InvertedLuminanceSource = new InvertedLuminanceSource(source);
+      return ZxingImageHelper.tryMaxiCodeOnSource(inverted, hints, true);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  private static tryMaxiCodeOnSource(source: LuminanceSource, hints: Map<DecodeHintType, Object>,
+    useHybrid: boolean): Result | null {
+    try {
+      const bitmap: BinaryBitmap = useHybrid
+        ? new BinaryBitmap(new HybridBinarizer(source))
+        : new BinaryBitmap(new GlobalHistogramBinarizer(source));
+      const matrix = bitmap.getBlackMatrix();
+      const enclosing: Int32Array | null = matrix.getEnclosingRectangle();
+      if (enclosing === null || enclosing === undefined) {
+        return null;
+      }
+      const rectW: number = enclosing[2];
+      const rectH: number = enclosing[3];
+      if (rectW <= 0 || rectH <= 0) {
+        return null;
+      }
+      const aspect: number = rectW / rectH;
+      if (aspect > 1.8 || aspect < 0.55) {
+        return null;
+      }
+      return ZxingImageHelper.decodeBinaryBitmap(bitmap, hints);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  /** F02-005 region probes support mixed barcode formats, bounded without TRY_HARDER. */
+  private static createMultiRegionDecodeHints(): Map<DecodeHintType, Object> {
+    const hints = new Map<DecodeHintType, Object>();
+    hints.set(DecodeHintType.POSSIBLE_FORMATS, STANDARD_DECODE_FORMATS);
+    hints.set(DecodeHintType.CHARACTER_SET, 'UTF-8');
+    return hints;
+  }
+
+  /**
+   * Bypass @zxing/text-encoding's huge GB18030/Shift_JIS tables, which can crash
+   * ArkTS when a Chinese QR (Hanzi/GB2312 or UTF-8 byte mode) is decoded.
+   */
+  private static stringCodecReady: boolean = false;
+
+  private static ensureSafeStringCodec(): void {
+    if (ZxingImageHelper.stringCodecReady) {
+      return;
+    }
+    ZXingStringEncoding.customDecoder = (bytes: Uint8Array, encodingName: string): string => {
+      return ZxingImageHelper.decodeBytesToString(bytes, encodingName);
+    };
+    ZxingImageHelper.stringCodecReady = true;
+  }
+
+  private static copyDecodedText(text: string): string {
+    return text === undefined || text === null ? '' : String(text);
+  }
+
+  private static normalizeCharsetLabel(encodingName: string): string {
+    const raw: string = encodingName === undefined || encodingName === null ? '' : encodingName;
+    const lowered: string = raw.trim().toLowerCase();
+    const n: string = lowered.split('_').join('-').split(' ').join('-');
+    if (n === 'utf8' || n === 'utf-8' || n === 'unicode') {
+      return 'utf-8';
+    }
+    if (n === 'gb2312' || n === 'gbk' || n === 'gb18030') {
+      return 'gb18030';
+    }
+    if (n === 'shift-jis' || n === 'sjis' || n === 'shiftjis') {
+      return 'shift_jis';
+    }
+    if (n === 'iso8859-1' || n === 'iso-8859-1' || n === 'iso88591') {
+      return 'iso-8859-1';
+    }
+    return n.length > 0 ? n : 'utf-8';
+  }
+
+  private static decodeBytesToString(bytes: Uint8Array, encodingName: string): string {
+    const label: string = ZxingImageHelper.normalizeCharsetLabel(encodingName);
+    if (label === 'iso-8859-1') {
+      let latin1: string = '';
+      for (let i = 0; i < bytes.length; i++) {
+        latin1 += String.fromCharCode(bytes[i] & 0xFF);
+      }
+      return latin1;
+    }
+    try {
+      const decoder = util.TextDecoder.create(label);
+      return decoder.decodeWithStream(bytes, { stream: false });
+    } catch (e) {
+      if (label !== 'utf-8') {
+        const utf8Decoder = util.TextDecoder.create('utf-8');
+        return utf8Decoder.decodeWithStream(bytes, { stream: false });
+      }
+      const err: Error = e as Error;
+      throw err;
+    }
+  }
+
+  /** Original and inverted decode only; does not allocate crop/zoom retry buffers. */
+  private static scanBasic(lum: Uint8ClampedArray, w: number, h: number,
+    hints: Map<DecodeHintType, Object>, allowInverted: boolean = true): Result | null {
+    const source: RGBLuminanceSource = new RGBLuminanceSource(lum, w, h);
+    const original: Result | null = ZxingImageHelper.decodeOnSource(source, hints);
+    if (original !== null) {
+      return original;
+    }
+    if (!allowInverted) {
+      return null;
+    }
+    try {
+      const inverted: InvertedLuminanceSource = new InvertedLuminanceSource(source);
+      return ZxingImageHelper.decodeOnSource(inverted, hints);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  /**
+   * Retry DataMatrix / PDF417 with dedicated readers after MultiFormatReader fails.
+   * @ohos/zxing MultiFormatReader can miss matrix codes even when they are listed in POSSIBLE_FORMATS.
+   */
+  private static scanMatrixSymbologyFallback(lum: Uint8ClampedArray, w: number, h: number): Result | null {
+    const hints: Map<DecodeHintType, Object> = new Map<DecodeHintType, Object>();
+    hints.set(DecodeHintType.TRY_HARDER, true);
+    hints.set(DecodeHintType.CHARACTER_SET, 'UTF-8');
+    const source: RGBLuminanceSource = new RGBLuminanceSource(lum, w, h);
+    let result: Result | null = ZxingImageHelper.decodeWithDedicatedMatrixReaders(source, hints);
+    if (result !== null) {
+      return result;
+    }
+    try {
+      const inverted: InvertedLuminanceSource = new InvertedLuminanceSource(source);
+      result = ZxingImageHelper.decodeWithDedicatedMatrixReaders(inverted, hints);
+      if (result !== null) {
+        return result;
+      }
+    } catch (e) {
+      // continue with crop retries
+    }
+    return ZxingImageHelper.scanWithRetries(lum, w, h, {
+      skipInitialBasic: true,
+      dedicatedMatrixReaders: true,
+    });
+  }
+
+  private static decodeWithDedicatedMatrixReaders(source: LuminanceSource,
+    hints: Map<DecodeHintType, Object>): Result | null {
+    const bitmaps: BinaryBitmap[] = [
+      new BinaryBitmap(new HybridBinarizer(source)),
+      new BinaryBitmap(new GlobalHistogramBinarizer(source)),
+    ];
+    for (let b = 0; b < bitmaps.length; b++) {
+      for (let r = 0; r < MATRIX_SYMBOLOGY_READERS.length; r++) {
+        try {
+          const result: Result = MATRIX_SYMBOLOGY_READERS[r].decode(bitmaps[b], hints);
+          if (result !== null && result.getText().length > 0) {
+            return result;
+          }
+        } catch (e) {
+          // try next reader / binarizer
+        }
+      }
+    }
+    return null;
+  }
+
+  private static decodeOnSource(source: LuminanceSource,
+    hints: Map<DecodeHintType, Object>): Result | null {
+    const hybridResult: Result | null = ZxingImageHelper.decodeBinaryBitmap(
+      new BinaryBitmap(new HybridBinarizer(source)), hints);
+    if (hybridResult !== null) {
+      return hybridResult;
+    }
+    return ZxingImageHelper.decodeBinaryBitmap(
+      new BinaryBitmap(new GlobalHistogramBinarizer(source)), hints);
+  }
+
+  private static copyLuminanceRegion(
+    lum: Uint8ClampedArray, srcW: number, srcH: number,
+    x: number, y: number, regionW: number, regionH: number,
+  ): Uint8ClampedArray {
+    const out: Uint8ClampedArray = new Uint8ClampedArray(regionW * regionH);
+    for (let row = 0; row < regionH; row++) {
+      const srcStart: number = (y + row) * srcW + x;
+      const dstStart: number = row * regionW;
+      for (let col = 0; col < regionW; col++) {
+        out[dstStart + col] = lum[srcStart + col];
+      }
+    }
+    return out;
+  }
+
+  private static decodeBinaryBitmap(bitmap: BinaryBitmap, hints: Map<DecodeHintType, Object>): Result | null {
+    try {
+      const reader: MultiFormatReader = new MultiFormatReader();
+      reader.setHints(hints);
+      return reader.decode(bitmap, hints);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  /** Nearest-neighbor luminance upscaling, equivalent to Android Bitmap.createScaledBitmap. */
+  private static scaleLuminance(
+    src: Uint8ClampedArray,
+    srcW: number,
+    srcH: number,
+    factor: number
+  ): RGBLuminanceSource {
+    const dstW: number = Math.max(1, Math.round(srcW * factor));
+    const dstH: number = Math.max(1, Math.round(srcH * factor));
+    const dst: Uint8ClampedArray = new Uint8ClampedArray(dstW * dstH);
+    for (let y = 0; y < dstH; y++) {
+      const srcY: number = Math.min(srcH - 1, Math.floor(y / factor));
+      for (let x = 0; x < dstW; x++) {
+        const srcX: number = Math.min(srcW - 1, Math.floor(x / factor));
+        dst[y * dstW + x] = src[srcY * srcW + srcX];
+      }
+    }
+    return new RGBLuminanceSource(dst, dstW, dstH);
+  }
+
+  /** Read QR error correction level decoded from format information metadata. */
+  private static extractCorrectionLevel(result: Result): string | undefined {
+    const metadata: Map<ResultMetadataType, Object> | null = result.getResultMetadata();
+    if (metadata === null || metadata === undefined) {
+      return undefined;
+    }
+    const ecLevel: Object | undefined = metadata.get(ResultMetadataType.ERROR_CORRECTION_LEVEL);
+    if (ecLevel === undefined || ecLevel === null) {
+      return undefined;
+    }
+    const level: string = String(ecLevel);
+    return level.length > 0 ? level : undefined;
+  }
+
+  /** Map BarcodeFormat to the JS CodeType string, aligned with Android getCodeType(). */
+  private static getCodeType(format: BarcodeFormat): string {
+    switch (format) {
+      case BarcodeFormat.AZTEC:
+        return 'Aztec';
+      case BarcodeFormat.CODABAR:
+        return 'Codabar';
+      case BarcodeFormat.CODE_39:
+        return 'Code39';
+      case BarcodeFormat.CODE_93:
+        return 'Code93';
+      case BarcodeFormat.CODE_128:
+        return 'Code128';
+      case BarcodeFormat.DATA_MATRIX:
+        return 'DataMatrix';
+      case BarcodeFormat.EAN_8:
+        return 'Ean8';
+      case BarcodeFormat.EAN_13:
+        return 'Ean13';
+      case BarcodeFormat.ITF:
+        return 'ITF';
+      case BarcodeFormat.MAXICODE:
+        return 'MaxiCode';
+      case BarcodeFormat.PDF_417:
+        return 'PDF417';
+      case BarcodeFormat.QR_CODE:
+        return 'QRCode';
+      case BarcodeFormat.RSS_14:
+        return 'RSS14';
+      case BarcodeFormat.RSS_EXPANDED:
+        return 'RSSExpanded';
+      case BarcodeFormat.UPC_A:
+        return 'UPCA';
+      case BarcodeFormat.UPC_E:
+        return 'UPCE';
+      case BarcodeFormat.UPC_EAN_EXTENSION:
+        return 'UPCEANExtension';
+      default:
+        return '';
+    }
+  }
+
+  /** Convert a sandbox URI or legacy file:// path to an absolute path for file/image APIs. */
+  private static normalizeSourcePath(source: string): string {
+    if (source.startsWith('file://')) {
+      try {
+        return new fileUri.FileUri(source).path;
+      } catch (e) {
+        // Fall back for legacy file:///absolute/path URIs.
+      }
+      let path: string = source.substring(7);
+      try {
+        path = decodeURIComponent(path);
+      } catch (decodeErr) {
+        // keep original path when it is not a valid encoded uri
+      }
+      return path;
+    }
+    return source;
+  }
+
+  private static loadPixelMapFromPath(path: string): image.PixelMap {
+    if (!ZxingImageHelper.fileExists(path)) {
+      throw new Error('IMAGE_NOT_FOUND');
+    }
+    let source: image.ImageSource | undefined = undefined;
+    try {
+      source = image.createImageSource(path);
+    } catch (e) {
+      throw new Error('IMAGE_NOT_FOUND');
+    }
+    if (source === undefined || source === null) {
+      throw new Error('IMAGE_NOT_FOUND');
+    }
+    try {
+      const sourceSize = ZxingImageHelper.readSourceSize(source);
+      return source.createPixelMapSync(ZxingImageHelper.buildDecodingOptions(sourceSize));
+    } catch (e) {
+      const err: Error = e as Error;
+      hilog.error(
+        DOMAIN,
+        TAG,
+        'loadPixelMapFromPath failed: %{public}s path=%{public}s',
+        ZxingImageHelper.errMsg(err),
+        path
+      );
+      throw new Error('IMAGE_NOT_FOUND');
+    } finally {
+      try {
+        source.release();
+      } catch (releaseErr) {
+        hilog.warn(
+          DOMAIN,
+          TAG,
+          'loadPixelMapFromPath release failed: %{public}s',
+          ZxingImageHelper.errMsg(releaseErr as Error)
+        );
+      }
+    }
+  }
+
+  private static fileExists(path: string): boolean {
+    try {
+      fs.accessSync(path);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  /** Read padding insets from TurboModule options (nested object via Record bridge). */
+  private static parsePaddingFromOptions(options: TM.RNQrGenerator.GenerateOptions): PaddingInsets {
+    const opts = options as Record<string, Object>;
+    const paddingVal: Object | undefined = opts.padding;
+    if (paddingVal !== undefined && paddingVal !== null) {
+      const padding = paddingVal as Record<string, Object>;
+      return {
+        top: ZxingImageHelper.getOptionNumber(padding, 'top', 0),
+        left: ZxingImageHelper.getOptionNumber(padding, 'left', 0),
+        bottom: ZxingImageHelper.getOptionNumber(padding, 'bottom', 0),
+        right: ZxingImageHelper.getOptionNumber(padding, 'right', 0),
+      };
+    }
+    const typedPadding = options.padding;
+    if (typedPadding !== undefined && typedPadding !== null) {
+      return {
+        top: typedPadding.top ?? 0,
+        left: typedPadding.left ?? 0,
+        bottom: typedPadding.bottom ?? 0,
+        right: typedPadding.right ?? 0,
+      };
+    }
+    return { top: 0, left: 0, bottom: 0, right: 0 };
+  }
+
+  /** Map correction level string to ZXing enum, aligned with Android RNQrGeneratorModule. */
+  private static parseCorrectionLevel(level: string): QRCodeDecoderErrorCorrectionLevel {
+    if (level === 'L') {
+      return QRCodeDecoderErrorCorrectionLevel.L;
+    }
+    if (level === 'M') {
+      return QRCodeDecoderErrorCorrectionLevel.M;
+    }
+    if (level === 'Q') {
+      return QRCodeDecoderErrorCorrectionLevel.Q;
+    }
+    return QRCodeDecoderErrorCorrectionLevel.H;
+  }
+
+  private static getOptionString(options: Record<string, Object>, key: string, defaultValue: string): string {
+    const val: Object | undefined = options[key];
+    return val === undefined || val === null ? defaultValue : String(val);
+  }
+
+  private static getOptionNumber(options: Record<string, Object>, key: string, defaultValue: number): number {
+    const val: Object | undefined = options[key];
+    return val === undefined || val === null ? defaultValue : Number(val);
+  }
+
+  private static getOptionBoolean(options: Record<string, Object>, key: string, defaultValue: boolean): boolean {
+    const val: Object | undefined = options[key];
+    if (val === undefined || val === null) {
+      return defaultValue;
+    }
+    return val as boolean;
+  }
+
+  private static errMsg(e: Error): string {
+    const msg: string = e.message;
+    return msg !== undefined && msg !== null && msg.length > 0 ? msg : String(e);
+  }
+}