@sythos/js_barcode_universal 1.5.13 → 1.5.15

package/src/ts/dotcode/tables.ts

@@ -0,0 +1,174 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * DotCode structural constants and the public 5-of-9 symbol assignment.
+ *
+ * The pattern assignment is a normative symbology table. It is recorded as
+ * compact hexadecimal values so the runtime does not need a third-party table
+ * or a generated dependency. Bit 8 is the first dot in the nine-dot pattern.
+ * Every entry contains exactly five dark dots.
+ *
+ * @module dotcode/tables
+ */
+
+import { GaloisField } from '../core/galois-field.js';
+
+export const DOTCODE_MIN_DIMENSION = 5;
+export const DOTCODE_MAX_DIMENSION = 200;
+export const DOTCODE_FIELD_SIZE = 113;
+export const DOTCODE_CODEWORD_COUNT = 113;
+export const DOTCODE_MIN_ECC = 3;
+export const DOTCODE_MASK_STEPS = Object.freeze([0, 3, 7, 17]);
+
+/** GF(113), with the primitive root required by the DotCode RS procedure. */
+export const GF113_DOTCODE = new GaloisField({
+  size: DOTCODE_FIELD_SIZE,
+  prime: true,
+  generator: 3,
+  name: 'GF(113)/DotCode',
+});
+
+/**
+ * DotCode Annex C's 113 legal 5-of-9 patterns.
+ *
+ * This is format data, not executable code copied from an implementation.
+ * Keeping it in the authoritative TypeScript source makes the JS runtime and
+ * its declarations reproducible without a package-time generator.
+ */
+export const DOTCODE_PATTERNS: readonly number[] = Object.freeze([
+  0x155, 0x0ab, 0x0ad, 0x0b5, 0x0d5, 0x156, 0x15a, 0x16a, 0x1aa, 0x0ae,
+  0x0b6, 0x0ba, 0x0d6, 0x0da, 0x0ea, 0x12b, 0x12d, 0x135, 0x14b, 0x14d,
+  0x153, 0x159, 0x165, 0x169, 0x195, 0x1a5, 0x1a9, 0x057, 0x05b, 0x05d,
+  0x06b, 0x06d, 0x075, 0x097, 0x09b, 0x09d, 0x0a7, 0x0b3, 0x0b9, 0x0cb,
+  0x0cd, 0x0d3, 0x0d9, 0x0e5, 0x0e9, 0x12e, 0x136, 0x13a, 0x14e, 0x15c,
+  0x166, 0x16c, 0x172, 0x174, 0x196, 0x19a, 0x1a6, 0x1ac, 0x1b2, 0x1b4,
+  0x1ca, 0x1d2, 0x1d4, 0x05e, 0x06e, 0x076, 0x07a, 0x09e, 0x0bc, 0x0ce,
+  0x0dc, 0x0e6, 0x0ec, 0x0f2, 0x0f4, 0x117, 0x11b, 0x11d, 0x127, 0x133,
+  0x139, 0x147, 0x163, 0x171, 0x18b, 0x18d, 0x193, 0x199, 0x1a3, 0x1b1,
+  0x1c5, 0x1c9, 0x1d1, 0x02f, 0x037, 0x03b, 0x03d, 0x04f, 0x067, 0x073,
+  0x079, 0x08f, 0x0c7, 0x0e3, 0x0f1, 0x11e, 0x13c, 0x178, 0x18e, 0x19c,
+  0x1b8, 0x1c6, 0x1cc,
+]);
+
+const PATTERN_TO_CODEWORD = new Map<number, number>(DOTCODE_PATTERNS.map((pattern, value) => [pattern, value]));
+
+/** Return the nine-dot pattern assigned to a codeword. */
+export function dotCodePattern(codeword: number): number {
+  if (!Number.isInteger(codeword) || codeword < 0 || codeword >= DOTCODE_CODEWORD_COUNT) {
+    throw new RangeError(`DotCode: codeword must be an integer in 0..${DOTCODE_CODEWORD_COUNT - 1}`);
+  }
+  return DOTCODE_PATTERNS[codeword];
+}
+
+/** Return a codeword for a nine-dot pattern, or -1 when it is not assigned. */
+export function dotCodeCodeword(pattern: number): number {
+  return PATTERN_TO_CODEWORD.get(pattern) ?? -1;
+}
+
+/** Number of active alternating positions in a W by H symbol. */
+export function dotCodeActivePositions(width: number, height: number): number {
+  return Math.floor((width * height) / 2);
+}
+
+/** Number of complete nine-bit codewords available after the mask bits. */
+export function dotCodeCodewordCapacity(width: number, height: number): number {
+  return Math.floor((dotCodeActivePositions(width, height) - 2) / 9);
+}
+
+/** DotCode uses alternating positions; the six corner positions carry tail bits. */
+export function dotCodeIsDataPosition(column: number, row: number): boolean {
+  return ((column + row) & 1) === 0;
+}
+
+/** Return true for one of the six corner positions used by the folded stream. */
+export function dotCodeIsCorner(column: number, row: number, width: number, height: number): boolean {
+  if (column === 0 && row === 0) return true;
+  if (height & 1) {
+    if ((column === width - 2 && row === 0) || (column === width - 1 && row === 1)) return true;
+    if (column === 0 && row === height - 1) return true;
+  } else {
+    if (column === width - 1 && row === 0) return true;
+    if ((column === 0 && row === height - 2) || (column === 1 && row === height - 1)) return true;
+  }
+  return (column === width - 2 && row === height - 1) ||
+    (column === width - 1 && row === height - 2);
+}
+
+/** Return the six corner coordinates in wire order for a canonical matrix. */
+export function dotCodeCornerOrder(width: number, height: number): readonly [number, number][] {
+  if (height & 1) {
+    return [
+      [width - 2, 0],
+      [width - 2, height - 1],
+      [width - 1, 1],
+      [width - 1, height - 2],
+      [0, 0],
+      [0, height - 1],
+    ];
+  }
+  return [
+    [width - 1, height - 2],
+    [0, height - 2],
+    [width - 2, height - 1],
+    [1, height - 1],
+    [width - 1, 0],
+    [0, 0],
+  ];
+}
+
+/** Largest data-codeword count that fits the supplied nine-bit capacity. */
+export function dotCodeDataCapacity(codewordCapacity: number): number {
+  if (!Number.isInteger(codewordCapacity) || codewordCapacity < DOTCODE_MIN_ECC + 1) return 0;
+  let best = 0;
+  for (let data = 1; data <= codewordCapacity; data++) {
+    const ecc = DOTCODE_MIN_ECC + Math.floor(data / 2);
+    if (data + ecc <= codewordCapacity) best = data;
+  }
+  return best;
+}
+
+/** Check public structural constants and pattern invariants. */
+export function validateDotCodeTables(): string[] {
+  const errors: string[] = [];
+  if (DOTCODE_PATTERNS.length !== DOTCODE_CODEWORD_COUNT) {
+    errors.push(`pattern count ${DOTCODE_PATTERNS.length} is not ${DOTCODE_CODEWORD_COUNT}`);
+  }
+  const seen = new Set<number>();
+  for (let value = 0; value < DOTCODE_PATTERNS.length; value++) {
+    const pattern = DOTCODE_PATTERNS[value];
+    if (seen.has(pattern)) errors.push(`pattern 0x${pattern.toString(16)} is duplicated`);
+    seen.add(pattern);
+    if (pattern < 0 || pattern > 0x1ff || pattern.toString(2).split('1').length - 1 !== 5) {
+      errors.push(`pattern ${value} is not a 5-of-9 value`);
+    }
+  }
+  return errors;
+}

package/src/ts/hanxin/decoder.d.ts

@@ -0,0 +1,48 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ * SPDX-FileCopyrightText: 2026 Sythos (https://www.sythos.net)
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+/**
+ * Strict Han Xin Code decoder for the alignment-free versions 1-3.
+ *
+ * The reader treats the matrix as untrusted input.  It first validates the
+ * fixed corner patterns and both structural-information copies, then checks
+ * Reed--Solomon parity and finally parses a complete payload.  A partially
+ * readable stream is never returned as a successful result.
+ *
+ * @module hanxin/decoder
+ */
+import { BitMatrix } from '../core/bit-matrix.js';
+import { HanXinEccLevel, HanXinVersion } from './tables.js';
+export type HanXinRotation = 0 | 90 | 180 | 270;
+export interface HanXinDecodeOptions {
+    /** Try the listed clockwise orientation, or all right-angle turns. */
+    rotation?: HanXinRotation | 'auto';
+    /** Select polarity, or try normal then inverted modules. */
+    inverted?: boolean | 'auto';
+}
+export interface HanXinDecodeResult {
+    format: 'hanxin';
+    text: string;
+    bytes: Uint8Array;
+    version: HanXinVersion;
+    ecc: HanXinEccLevel;
+    mask: 0 | 1 | 2 | 3;
+    mode: 'numeric' | 'text' | 'byte';
+    corrections: number;
+    rows: number;
+    columns: number;
+    inverted: boolean;
+    rotation: HanXinRotation;
+}
+/** Verify finder patterns, separators and all non-information function cells. */
+export declare function hanXinStructureMatches(matrix: BitMatrix, version: HanXinVersion): boolean;
+/** Decode a verified Han Xin module matrix. */
+export declare function decodeHanXin(matrix: BitMatrix, options?: HanXinDecodeOptions): HanXinDecodeResult;

package/src/ts/hanxin/decoder.ts

@@ -0,0 +1,314 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ * SPDX-FileCopyrightText: 2026 Sythos (https://www.sythos.net)
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Strict Han Xin Code decoder for the alignment-free versions 1-3.
+ *
+ * The reader treats the matrix as untrusted input.  It first validates the
+ * fixed corner patterns and both structural-information copies, then checks
+ * Reed--Solomon parity and finally parses a complete payload.  A partially
+ * readable stream is never returned as a successful result.
+ *
+ * @module hanxin/decoder
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { BitReader } from '../core/bit-buffer.js';
+import { FormatError } from '../core/errors.js';
+import { rsDecode } from '../core/reed-solomon.js';
+import { GF256_HANXIN } from './tables.js';
+import {
+  HANXIN_ECC_LEVELS,
+  HanXinEccLevel,
+  HanXinVersion,
+  HANXIN_DATA_MODULES,
+  HANXIN_TOTAL_CODEWORDS,
+  createHanXinFunctionGrid,
+  decodeHanXinFunctionInfo,
+  hanXinDataCoordinates,
+  hanXinEcLayout,
+  hanXinMaskFlip,
+  hanXinSize,
+} from './tables.js';
+
+export type HanXinRotation = 0 | 90 | 180 | 270;
+
+export interface HanXinDecodeOptions {
+  /** Try the listed clockwise orientation, or all right-angle turns. */
+  rotation?: HanXinRotation | 'auto';
+  /** Select polarity, or try normal then inverted modules. */
+  inverted?: boolean | 'auto';
+}
+
+export interface HanXinDecodeResult {
+  format: 'hanxin';
+  text: string;
+  bytes: Uint8Array;
+  version: HanXinVersion;
+  ecc: HanXinEccLevel;
+  mask: 0 | 1 | 2 | 3;
+  mode: 'numeric' | 'text' | 'byte';
+  corrections: number;
+  rows: number;
+  columns: number;
+  inverted: boolean;
+  rotation: HanXinRotation;
+}
+
+interface PayloadResult {
+  text: string;
+  bytes: Uint8Array;
+  mode: HanXinDecodeResult['mode'];
+}
+
+function rotateMatrix(source: BitMatrix, rotation: HanXinRotation): BitMatrix {
+  if (rotation === 0) return source;
+  const output = new BitMatrix(source.height, source.width);
+  for (let y = 0; y < source.height; y++) for (let x = 0; x < source.width; x++) {
+    if (!source.get(x, y)) continue;
+    if (rotation === 90) output.set(source.height - 1 - y, x);
+    else if (rotation === 180) output.set(source.width - 1 - x, source.height - 1 - y);
+    else output.set(y, source.width - 1 - x);
+  }
+  return output;
+}
+
+function invertMatrix(source: BitMatrix): BitMatrix {
+  const output = source.clone();
+  for (let y = 0; y < output.height; y++) for (let x = 0; x < output.width; x++) output.flip(x, y);
+  return output;
+}
+
+function functionInfoCells(version: HanXinVersion): Set<string> {
+  const size = hanXinSize(version);
+  const cells = new Set<string>();
+  for (let i = 0; i < 9; i++) {
+    cells.add(`${i},8`);
+    cells.add(`${size - 1 - i},${size - 9}`);
+    cells.add(`8,${8 - i}`);
+    cells.add(`${size - 9},${size - 9 + i}`);
+    cells.add(`${size - 9},${i}`);
+    cells.add(`8,${size - 1 - i}`);
+    cells.add(`${size - 9 + i},8`);
+    cells.add(`${8 - i},${size - 9}`);
+  }
+  return cells;
+}
+
+/** Verify finder patterns, separators and all non-information function cells. */
+export function hanXinStructureMatches(matrix: BitMatrix, version: HanXinVersion): boolean {
+  const size = hanXinSize(version);
+  if (matrix.width !== size || matrix.height !== size) return false;
+  const template = createHanXinFunctionGrid(version);
+  const info = functionInfoCells(version);
+  for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+    if (template.reserved[y * size + x] === 0 || info.has(`${x},${y}`)) continue;
+    if (matrix.get(x, y) !== template.matrix.get(x, y)) return false;
+  }
+  return true;
+}
+
+function inversePicketFence(wire: number[]): number[] {
+  const codewords = new Array<number>(wire.length).fill(0);
+  let cursor = 0;
+  for (let column = 0; column < 13; column++) {
+    for (let i = column; i < codewords.length; i += 13) codewords[i] = wire[cursor++];
+  }
+  if (cursor !== wire.length) throw new FormatError('Han Xin: codeword reordering is inconsistent');
+  return codewords;
+}
+
+function readCodewords(matrix: BitMatrix, version: HanXinVersion, mask: number): number[] {
+  const coordinates = hanXinDataCoordinates(version);
+  const total = HANXIN_DATA_MODULES[version - 1];
+  const codewordBits = HANXIN_TOTAL_CODEWORDS[version - 1] * 8;
+  const wire = new Array<number>(HANXIN_TOTAL_CODEWORDS[version - 1]).fill(0);
+  for (let i = 0; i < total; i++) {
+    const [x, y] = coordinates[i];
+    let dark = matrix.get(x, y);
+    if (hanXinMaskFlip(mask, x, y)) dark = !dark;
+    if (i < codewordBits) {
+      if (dark) wire[i >>> 3] |= 1 << (7 - (i & 7));
+    } else if (dark) {
+      throw new FormatError('Han Xin: non-zero remainder modules');
+    }
+  }
+  return inversePicketFence(wire);
+}
+
+function ensureZeroPadding(reader: BitReader): void {
+  while (reader.available() > 0) {
+    if (reader.readBit()) throw new FormatError('Han Xin: non-zero data follows the payload terminator');
+  }
+}
+
+function utf8Bytes(text: string): Uint8Array {
+  return new TextEncoder().encode(text);
+}
+
+function decodeByteText(bytes: Uint8Array): string {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    // A byte-mode symbol is allowed to carry arbitrary octets.  Preserve
+    // every octet losslessly when it is not valid UTF-8.
+    return Array.from(bytes, (value) => String.fromCharCode(value)).join('');
+  }
+}
+
+function decodeNumeric(reader: BitReader): string {
+  const groups: number[] = [];
+  while (reader.available() >= 10) {
+    const value = reader.read(10);
+    if (value >= 1021 && value <= 1023) {
+      const count = value - 1020;
+      if (groups.length === 0) throw new FormatError('Han Xin: numeric payload has no data group');
+      const last = groups.pop() as number;
+      if (last >= 10 ** count) throw new FormatError('Han Xin: numeric final group has an invalid width');
+      return groups.map((group) => String(group).padStart(3, '0')).join('') +
+        String(last).padStart(count, '0');
+    }
+    if (value > 999) throw new FormatError('Han Xin: numeric group is outside the 000-999 range');
+    groups.push(value);
+    if (groups.length > 2730) throw new FormatError('Han Xin: numeric payload exceeds the supported stream limit');
+  }
+  throw new FormatError('Han Xin: numeric payload has no complete terminator');
+}
+
+function text1Character(value: number): string | null {
+  if (value >= 0 && value <= 9) return String.fromCharCode(0x30 + value);
+  if (value >= 10 && value <= 35) return String.fromCharCode(0x41 + value - 10);
+  if (value >= 36 && value <= 61) return String.fromCharCode(0x61 + value - 36);
+  return null;
+}
+
+function text2Character(value: number): string | null {
+  if (value >= 0 && value <= 27) return String.fromCharCode(value);
+  if (value >= 28 && value <= 43) return String.fromCharCode(0x20 + value - 28);
+  if (value >= 44 && value <= 50) return String.fromCharCode(0x3a + value - 44);
+  if (value >= 51 && value <= 56) return String.fromCharCode(0x5b + value - 51);
+  if (value >= 57 && value <= 61) return String.fromCharCode(0x7b + value - 57);
+  return null;
+}
+
+function decodeText(reader: BitReader): string {
+  let submode: 1 | 2 = 1;
+  const characters: string[] = [];
+  while (reader.available() >= 6) {
+    const value = reader.read(6);
+    if (value === 63) {
+      if (characters.length === 0) throw new FormatError('Han Xin: text payload is empty');
+      return characters.join('');
+    }
+    if (value === 62) {
+      submode = submode === 1 ? 2 : 1;
+      continue;
+    }
+    const character = submode === 1 ? text1Character(value) : text2Character(value);
+    if (character === null) throw new FormatError(`Han Xin: text value ${value} is not assigned in submode ${submode}`);
+    characters.push(character);
+    if (characters.length > 8191) throw new FormatError('Han Xin: text payload exceeds the supported stream limit');
+  }
+  throw new FormatError('Han Xin: text payload has no complete terminator');
+}
+
+function decodeByte(reader: BitReader): Uint8Array {
+  if (reader.available() < 13) throw new FormatError('Han Xin: byte payload has no complete length field');
+  const count = reader.read(13);
+  if (count < 1 || count > 8191) throw new FormatError(`Han Xin: byte count ${count} is outside the supported range`);
+  if (count * 8 > reader.available()) throw new FormatError('Han Xin: byte payload is truncated');
+  const bytes = new Uint8Array(count);
+  for (let i = 0; i < count; i++) bytes[i] = reader.read(8);
+  return bytes;
+}
+
+function parsePayload(data: Uint8Array): PayloadResult {
+  const reader = new BitReader(data);
+  if (reader.available() < 4) throw new FormatError('Han Xin: payload has no mode indicator');
+  const mode = reader.read(4);
+  if (mode === 1) {
+    const text = decodeNumeric(reader);
+    ensureZeroPadding(reader);
+    return { text, bytes: utf8Bytes(text), mode: 'numeric' };
+  }
+  if (mode === 2) {
+    const text = decodeText(reader);
+    ensureZeroPadding(reader);
+    return { text, bytes: utf8Bytes(text), mode: 'text' };
+  }
+  if (mode === 3) {
+    const bytes = decodeByte(reader);
+    ensureZeroPadding(reader);
+    return { text: decodeByteText(bytes), bytes, mode: 'byte' };
+  }
+  throw new FormatError(`Han Xin: unsupported mode indicator ${mode}`);
+}
+
+function candidateRotations(option: HanXinDecodeOptions['rotation']): HanXinRotation[] {
+  if (option === 'auto' || option == null) return [0, 90, 180, 270];
+  if (option === 0 || option === 90 || option === 180 || option === 270) return [option];
+  throw new FormatError('Han Xin: rotation must be 0, 90, 180, 270 or auto');
+}
+
+function candidatePolarities(option: HanXinDecodeOptions['inverted']): boolean[] {
+  if (option === 'auto' || option == null) return [false, true];
+  if (option === false || option === true) return [option];
+  throw new FormatError('Han Xin: inverted must be true, false or auto');
+}
+
+/** Decode a verified Han Xin module matrix. */
+export function decodeHanXin(matrix: BitMatrix, options: HanXinDecodeOptions = {}): HanXinDecodeResult {
+  if (!matrix || !Number.isInteger(matrix.width) || !Number.isInteger(matrix.height)) {
+    throw new FormatError('Han Xin: a BitMatrix is required');
+  }
+  const rotations = candidateRotations(options.rotation);
+  const polarities = candidatePolarities(options.inverted);
+  let lastError: unknown = null;
+
+  for (const rotation of rotations) {
+    const rotated = rotateMatrix(matrix, rotation);
+    for (const inverted of polarities) {
+      const candidate = inverted ? invertMatrix(rotated) : rotated;
+      for (const version of [1, 2, 3] as HanXinVersion[]) {
+        if (candidate.width !== hanXinSize(version) || candidate.height !== hanXinSize(version)) continue;
+        if (!hanXinStructureMatches(candidate, version)) continue;
+        try {
+          const info = decodeHanXinFunctionInfo(candidate, version);
+          if (!HANXIN_ECC_LEVELS.includes(info.level)) throw new FormatError('Han Xin: invalid error-correction level');
+          const codewords = readCodewords(candidate, version, info.mask);
+          const layout = hanXinEcLayout(version, info.level);
+          const corrections = rsDecode(codewords, layout.eccCodewords, GF256_HANXIN, 1);
+          const data = Uint8Array.from(codewords.slice(0, layout.dataCodewords));
+          const payload = parsePayload(data);
+          return {
+            format: 'hanxin',
+            text: payload.text,
+            bytes: payload.bytes,
+            version,
+            ecc: info.level,
+            mask: info.mask as 0 | 1 | 2 | 3,
+            mode: payload.mode,
+            corrections: info.corrections + corrections,
+            rows: candidate.height,
+            columns: candidate.width,
+            inverted,
+            rotation,
+          };
+        } catch (error) {
+          lastError = error;
+        }
+      }
+    }
+  }
+  if (lastError instanceof FormatError) throw lastError;
+  throw new FormatError('Han Xin: no valid symbol found in the supplied matrix');
+}

package/src/ts/hanxin/detector.d.ts

@@ -0,0 +1,45 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ * SPDX-FileCopyrightText: 2026 Sythos (https://www.sythos.net)
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+/**
+ * Integer-scale Han Xin detector.
+ *
+ * Detection deliberately accepts one prominent, axis-aligned symbol from a
+ * binarized image.  It does not guess a perspective quadrilateral or return a
+ * low-confidence payload: the strict module decoder remains the final gate.
+ *
+ * @module hanxin/detector
+ */
+import { BitMatrix } from '../core/bit-matrix.js';
+import { HanXinDecodeResult } from './decoder.js';
+export interface HanXinDetection {
+    corners: Array<{
+        x: number;
+        y: number;
+    }>;
+    dimension: {
+        width: number;
+        height: number;
+    };
+    moduleSize: number;
+    matrix: BitMatrix;
+    result: HanXinDecodeResult;
+}
+/** Detect one strict, integer-scale Han Xin symbol in a binarized image. */
+export declare function detectHanXin(binaryImage: BitMatrix): HanXinDetection | null;
+/** Detect and decode one verified Han Xin symbol, or return null. */
+export declare function detectAndDecodeHanXin(binaryImage: BitMatrix): (HanXinDecodeResult & {
+    corners: Array<{
+        x: number;
+        y: number;
+    }>;
+    moduleSize: number;
+}) | null;