@sythos/js_barcode_universal 1.5.13 → 1.5.15

package/src/ts/hanxin/detector.ts

@@ -0,0 +1,124 @@
+/*!
+ * 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 { NotFoundError } from '../core/errors.js';
+import { decodeHanXin, HanXinDecodeResult } from './decoder.js';
+import { HanXinVersion, hanXinSize } from './tables.js';
+
+export interface HanXinDetection {
+  corners: Array<{ x: number; y: number }>;
+  dimension: { width: number; height: number };
+  moduleSize: number;
+  matrix: BitMatrix;
+  result: HanXinDecodeResult;
+}
+interface Bounds { x: number; y: number; width: number; height: number; }
+
+function boundsForPolarity(image: BitMatrix, inverted: boolean): Bounds | null {
+  let left = image.width;
+  let top = image.height;
+  let right = -1;
+  let bottom = -1;
+  for (let y = 0; y < image.height; y++) for (let x = 0; x < image.width; x++) {
+    const dark = image.get(x, y) !== inverted;
+    if (!dark) continue;
+    if (x < left) left = x;
+    if (x > right) right = x;
+    if (y < top) top = y;
+    if (y > bottom) bottom = y;
+  }
+  return right < left || bottom < top ? null : {
+    x: left,
+    y: top,
+    width: right - left + 1,
+    height: bottom - top + 1,
+  };
+}
+
+function sampleBounds(source: BitMatrix, bounds: Bounds, version: HanXinVersion, inverted: boolean): BitMatrix {
+  const size = hanXinSize(version);
+  const matrix = new BitMatrix(size, size);
+  for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+    const px = Math.min(source.width - 1, Math.max(0,
+      Math.floor(bounds.x + ((x + 0.5) * bounds.width) / size)));
+    const py = Math.min(source.height - 1, Math.max(0,
+      Math.floor(bounds.y + ((y + 0.5) * bounds.height) / size)));
+    if (source.get(px, py) !== inverted) matrix.set(x, y);
+  }
+  return matrix;
+}
+
+/** Detect one strict, integer-scale Han Xin symbol in a binarized image. */
+export function detectHanXin(binaryImage: BitMatrix): HanXinDetection | null {
+  if (!binaryImage || !Number.isInteger(binaryImage.width) || !Number.isInteger(binaryImage.height) ||
+    binaryImage.width < 1 || binaryImage.height < 1) {
+    throw new NotFoundError('detectHanXin: no image supplied');
+  }
+  const candidates: HanXinDetection[] = [];
+  for (const inverted of [false, true]) {
+    const bounds = boundsForPolarity(binaryImage, inverted);
+    if (!bounds) continue;
+    for (const version of [1, 2, 3] as HanXinVersion[]) {
+      const size = hanXinSize(version);
+      if (bounds.width !== bounds.height || bounds.width % size !== 0) continue;
+      const moduleSize = bounds.width / size;
+      if (!Number.isInteger(moduleSize) || moduleSize < 1) continue;
+      const matrix = sampleBounds(binaryImage, bounds, version, inverted);
+      let result: HanXinDecodeResult;
+      try {
+        result = decodeHanXin(matrix, { rotation: 'auto', inverted: false });
+      } catch {
+        continue;
+      }
+      candidates.push({
+        corners: [
+          { x: bounds.x, y: bounds.y },
+          { x: bounds.x + bounds.width, y: bounds.y },
+          { x: bounds.x + bounds.width, y: bounds.y + bounds.height },
+          { x: bounds.x, y: bounds.y + bounds.height },
+        ],
+        dimension: { width: size, height: size },
+        moduleSize,
+        matrix,
+        result: { ...result, inverted: result.inverted || inverted },
+      });
+    }
+  }
+  candidates.sort((left, right) => right.moduleSize - left.moduleSize);
+  return candidates[0] ?? null;
+}
+
+/** Detect and decode one verified Han Xin symbol, or return null. */
+export function detectAndDecodeHanXin(binaryImage: BitMatrix): HanXinDecodeResult & {
+  corners: Array<{ x: number; y: number }>;
+  moduleSize: number;
+} | null {
+  let detection: HanXinDetection | null;
+  try { detection = detectHanXin(binaryImage); } catch { return null; }
+  if (!detection) return null;
+  return {
+    ...detection.result,
+    corners: detection.corners,
+    moduleSize: detection.moduleSize,
+  };
+}

package/src/ts/hanxin/encoder.d.ts

@@ -0,0 +1,41 @@
+/*!
+ * 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.
+ */
+/**
+ * Dependency-free Han Xin Code encoder for the alignment-free versions 1-3.
+ *
+ * The implementation follows the public ISO/IEC 20830 structure: four corner
+ * position patterns, protected structural information, GF(256) Reed--Solomon
+ * blocks, 13-column picket-fence ordering and one of the four data masks.
+ * Numeric, Text and Byte modes are intentionally explicit so callers never
+ * get a silent lossy conversion.
+ *
+ * @module hanxin/encoder
+ */
+import { BitMatrix } from '../core/bit-matrix.js';
+import { HanXinEccLevel, HanXinVersion } from './tables.js';
+export type HanXinEncodeMode = 'auto' | 'numeric' | 'text' | 'byte';
+export interface HanXinEncodeOptions {
+    /** Force one of the three implemented dimensions. */
+    version?: HanXinVersion | `V${HanXinVersion}` | number;
+    /** L1 is the least redundant level; L4 is the strongest. */
+    ecc?: HanXinEccLevel | 1 | 2 | 3 | 4;
+    /** Select the payload interpretation. Defaults to auto. */
+    mode?: HanXinEncodeMode;
+    /** Force a mask 0-3. By default the lowest local penalty is chosen. */
+    mask?: 0 | 1 | 2 | 3 | number;
+}
+/** Encode a string or byte array as a Han Xin Code module matrix. */
+export declare function encodeHanXin(value: string | Uint8Array | number[], options?: HanXinEncodeOptions): BitMatrix;
+/** Encode explicitly in byte mode; useful when the input contains arbitrary data. */
+export declare function encodeHanXinBytes(bytes: Uint8Array | number[], options?: Omit<HanXinEncodeOptions, 'mode'>): BitMatrix;
+/** Expose the implemented geometric side length for callers building rasters. */
+export declare function hanXinDimension(version: HanXinVersion | number): number;

package/src/ts/hanxin/encoder.ts

@@ -0,0 +1,290 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Dependency-free Han Xin Code encoder for the alignment-free versions 1-3.
+ *
+ * The implementation follows the public ISO/IEC 20830 structure: four corner
+ * position patterns, protected structural information, GF(256) Reed--Solomon
+ * blocks, 13-column picket-fence ordering and one of the four data masks.
+ * Numeric, Text and Byte modes are intentionally explicit so callers never
+ * get a silent lossy conversion.
+ *
+ * @module hanxin/encoder
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { BitWriter } from '../core/bit-buffer.js';
+import { EncodeError } from '../core/errors.js';
+import { rsEncode } from '../core/reed-solomon.js';
+import {
+  GF256_HANXIN,
+  HANXIN_VERSIONS,
+  HanXinEccLevel,
+  HanXinVersion,
+  createHanXinFunctionGrid,
+  hanXinDataCoordinates,
+  hanXinDataCodewords,
+  hanXinEcLayout,
+  hanXinMaskFlip,
+  hanXinSize,
+  normalizeHanXinEcc,
+  normalizeHanXinVersion,
+  placeHanXinFunctionInfo,
+} from './tables.js';
+
+export type HanXinEncodeMode = 'auto' | 'numeric' | 'text' | 'byte';
+
+export interface HanXinEncodeOptions {
+  /** Force one of the three implemented dimensions. */
+  version?: HanXinVersion | `V${HanXinVersion}` | number;
+  /** L1 is the least redundant level; L4 is the strongest. */
+  ecc?: HanXinEccLevel | 1 | 2 | 3 | 4;
+  /** Select the payload interpretation. Defaults to auto. */
+  mode?: HanXinEncodeMode;
+  /** Force a mask 0-3. By default the lowest local penalty is chosen. */
+  mask?: 0 | 1 | 2 | 3 | number;
+}
+
+function inputBytes(value: string | Uint8Array | number[]): { bytes: Uint8Array; text: string | null } {
+  if (value instanceof Uint8Array) {
+    if (value.length === 0) throw new EncodeError('Han Xin: payload must not be empty');
+    return { bytes: new Uint8Array(value), text: null };
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0 || value.length > 8191 || value.some((item) => !Number.isInteger(item) || item < 0 || item > 255)) {
+      throw new EncodeError('Han Xin: byte arrays must contain at most 8191 values from 0 to 255');
+    }
+    return { bytes: Uint8Array.from(value), text: null };
+  }
+  if (typeof value !== 'string') throw new EncodeError('Han Xin: value must be text or bytes');
+  if (!value.length) throw new EncodeError('Han Xin: payload must not be empty');
+  return { bytes: new TextEncoder().encode(value), text: value };
+}
+
+function text1Value(codePoint: number): number | null {
+  if (codePoint >= 0x30 && codePoint <= 0x39) return codePoint - 0x30;
+  if (codePoint >= 0x41 && codePoint <= 0x5a) return codePoint - 0x41 + 10;
+  if (codePoint >= 0x61 && codePoint <= 0x7a) return codePoint - 0x61 + 36;
+  return null;
+}
+
+function text2Value(codePoint: number): number | null {
+  if (codePoint >= 0 && codePoint <= 0x1b) return codePoint;
+  if (codePoint >= 0x20 && codePoint <= 0x2f) return codePoint - 0x20 + 28;
+  if (codePoint >= 0x3a && codePoint <= 0x40) return codePoint - 0x3a + 44;
+  if (codePoint >= 0x5b && codePoint <= 0x60) return codePoint - 0x5b + 51;
+  if (codePoint >= 0x7b && codePoint <= 0x7f) return codePoint - 0x7b + 57;
+  return null;
+}
+
+function textValue(codePoint: number, mode: 1 | 2): number | null {
+  return mode === 1 ? text1Value(codePoint) : text2Value(codePoint);
+}
+
+function selectMode(text: string | null, requested: HanXinEncodeMode | undefined): HanXinEncodeMode {
+  const mode = requested == null ? 'auto' : String(requested).toLowerCase() as HanXinEncodeMode;
+  if (!['auto', 'numeric', 'text', 'byte'].includes(mode)) {
+    throw new EncodeError(`Han Xin: unsupported payload mode ${String(requested)}`);
+  }
+  if (text == null) {
+    if (mode === 'numeric' || mode === 'text') throw new EncodeError('Han Xin: numeric and text modes require a string input');
+    return 'byte';
+  }
+  const points = Array.from(text);
+  const numeric = /^\d+$/.test(text);
+  const textCompatible = points.every((point) => {
+    const cp = point.codePointAt(0) as number;
+    return cp <= 0x7f && (text1Value(cp) !== null || text2Value(cp) !== null);
+  });
+  if (mode === 'numeric' && !numeric) throw new EncodeError('Han Xin: numeric mode accepts digits only');
+  if (mode === 'text' && !textCompatible) throw new EncodeError('Han Xin: text mode accepts supported ASCII characters only');
+  if (mode === 'auto') return numeric ? 'numeric' : textCompatible ? 'text' : 'byte';
+  return mode;
+}
+
+function encodeNumeric(text: string, writer: BitWriter): void {
+  let finalCount = 0;
+  for (let offset = 0; offset < text.length; offset += 3) {
+    finalCount = Math.min(3, text.length - offset);
+    writer.put(Number(text.slice(offset, offset + finalCount)), 10);
+  }
+  writer.put(1020 + finalCount, 10);
+}
+
+function encodeText(text: string, writer: BitWriter): void {
+  let submode: 1 | 2 = 1;
+  for (const point of Array.from(text)) {
+    const cp = point.codePointAt(0) as number;
+    let value = textValue(cp, submode);
+    if (value === null) {
+      submode = submode === 1 ? 2 : 1;
+      writer.put(62, 6);
+      value = textValue(cp, submode);
+    }
+    if (value === null) throw new EncodeError(`Han Xin: character U+${cp.toString(16).padStart(4, '0')} is not encodable in text mode`);
+    writer.put(value, 6);
+  }
+  writer.put(63, 6);
+}
+
+function encodeByte(bytes: Uint8Array, writer: BitWriter): void {
+  if (bytes.length > 8191) throw new EncodeError('Han Xin: byte mode supports at most 8191 bytes');
+  writer.put(3, 4);
+  writer.put(bytes.length, 13);
+  writer.putBytes(bytes);
+}
+
+function payloadBits(value: string | Uint8Array | number[], mode: HanXinEncodeMode): BitWriter {
+  const source = inputBytes(value);
+  const writer = new BitWriter();
+  if (mode === 'numeric') {
+    writer.put(1, 4);
+    encodeNumeric(source.text as string, writer);
+  } else if (mode === 'text') {
+    writer.put(2, 4);
+    encodeText(source.text as string, writer);
+  } else {
+    encodeByte(source.bytes, writer);
+  }
+  return writer;
+}
+
+function picketFence(codewords: number[]): number[] {
+  const output: number[] = [];
+  for (let column = 0; column < 13; column++) {
+    for (let i = column; i < codewords.length; i += 13) output.push(codewords[i]);
+  }
+  return output;
+}
+
+function placePayload(matrix: BitMatrix, version: HanXinVersion, codewords: number[], mask: number): void {
+  const coordinates = hanXinDataCoordinates(version);
+  const bits = picketFence(codewords);
+  const totalBits = bits.length * 8;
+  for (let i = 0; i < coordinates.length; i++) {
+    const [x, y] = coordinates[i];
+    // Compact versions have five remainder modules after the final complete
+    // codeword.  They carry zero before masking and are checked by the reader.
+    let dark = i < totalBits && ((bits[i >>> 3] >>> (7 - (i & 7))) & 1) !== 0;
+    if (hanXinMaskFlip(mask, x, y)) dark = !dark;
+    matrix.setValue(x, y, dark);
+  }
+}
+
+function maskPenalty(matrix: BitMatrix, version: HanXinVersion, level: HanXinEccLevel, mask: number): number {
+  const candidate = matrix.clone();
+  for (const [x, y] of hanXinDataCoordinates(version)) {
+    if (hanXinMaskFlip(mask, x, y)) candidate.flip(x, y);
+  }
+  placeHanXinFunctionInfo(candidate, version, level, mask);
+  let penalty = 0;
+  const runPenalty = (values: boolean[]): void => {
+    let current = values[0];
+    let run = 1;
+    for (let i = 1; i <= values.length; i++) {
+      if (i < values.length && values[i] === current) run++;
+      else {
+        if (run >= 3) penalty += run * 4;
+        current = values[i];
+        run = 1;
+      }
+    }
+  };
+  for (let y = 0; y < candidate.height; y++) {
+    const row: boolean[] = [];
+    for (let x = 0; x < candidate.width; x++) row.push(candidate.get(x, y));
+    runPenalty(row);
+  }
+  for (let x = 0; x < candidate.width; x++) {
+    const column: boolean[] = [];
+    for (let y = 0; y < candidate.height; y++) column.push(candidate.get(x, y));
+    runPenalty(column);
+  }
+  return penalty;
+}
+
+function chooseMask(base: BitMatrix, version: HanXinVersion, level: HanXinEccLevel, requested: number | undefined): number {
+  if (requested !== undefined) {
+    if (!Number.isInteger(requested) || requested < 0 || requested > 3) throw new EncodeError('Han Xin: mask must be an integer from 0 to 3');
+    return requested;
+  }
+  let best = 0;
+  let score = Number.POSITIVE_INFINITY;
+  for (let mask = 0; mask < 4; mask++) {
+    const candidate = base.clone();
+    // The score is intentionally simple and stable.  Every candidate is still
+    // validated by the strict reader, so no mask choice can affect integrity.
+    const value = maskPenalty(candidate, version, level, mask);
+    if (value < score) { score = value; best = mask; }
+  }
+  return best;
+}
+
+function encodeVersion(
+  writer: BitWriter,
+  version: HanXinVersion,
+  level: HanXinEccLevel,
+  requestedMask: number | undefined,
+): BitMatrix {
+  const dataCodewords = hanXinDataCodewords(version, level);
+  const layout = hanXinEcLayout(version, level);
+  const capacity = dataCodewords * 8;
+  if (writer.length > capacity) throw new EncodeError(`Han Xin: payload needs ${writer.length} bits but ${capacity} are available`);
+  const data = new Uint8Array(dataCodewords);
+  const encoded = writer.toBytes();
+  data.set(encoded.subarray(0, data.length));
+  const parity = rsEncode(Array.from(data), layout.eccCodewords, GF256_HANXIN, 1);
+  const full = Array.from(data).concat(parity);
+  const { matrix } = createHanXinFunctionGrid(version);
+  placePayload(matrix, version, full, 0);
+  const mask = chooseMask(matrix, version, level, requestedMask);
+  placePayload(matrix, version, full, mask);
+  placeHanXinFunctionInfo(matrix, version, level, mask);
+  return matrix;
+}
+
+/** Encode a string or byte array as a Han Xin Code module matrix. */
+export function encodeHanXin(
+  value: string | Uint8Array | number[],
+  options: HanXinEncodeOptions = {},
+): BitMatrix {
+  const source = inputBytes(value);
+  const mode = selectMode(source.text, options.mode);
+  const writer = payloadBits(value, mode);
+  const level = normalizeHanXinEcc(options.ecc);
+  const wantedVersion = options.version == null ? null : normalizeHanXinVersion(options.version);
+  const requestedMask = options.mask == null ? undefined : Number(options.mask);
+  if (requestedMask !== undefined &&
+    (!Number.isInteger(requestedMask) || requestedMask < 0 || requestedMask > 3)) {
+    throw new EncodeError('Han Xin: mask must be an integer from 0 to 3');
+  }
+
+  for (const version of HANXIN_VERSIONS) {
+    if (wantedVersion !== null && version !== wantedVersion) continue;
+    try { return encodeVersion(writer, version, level, requestedMask); } catch (error) {
+      if (!(error instanceof EncodeError)) throw error;
+    }
+  }
+  const target = wantedVersion == null ? 'versions 1-3' : `version ${wantedVersion}`;
+  throw new EncodeError(`Han Xin: payload does not fit ${target} at error correction ${level}`);
+}
+
+/** Encode explicitly in byte mode; useful when the input contains arbitrary data. */
+export function encodeHanXinBytes(bytes: Uint8Array | number[], options: Omit<HanXinEncodeOptions, 'mode'> = {}): BitMatrix {
+  return encodeHanXin(bytes, { ...options, mode: 'byte' });
+}
+
+/** Expose the implemented geometric side length for callers building rasters. */
+export function hanXinDimension(version: HanXinVersion | number): number {
+  return hanXinSize(Number(version));
+}

package/src/ts/hanxin/index.d.ts

@@ -0,0 +1,16 @@
+/*!
+ * 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.
+ */
+/** Public Han Xin Code API. @module hanxin */
+export * from './tables.js';
+export * from './encoder.js';
+export * from './decoder.js';
+export * from './detector.js';

package/src/ts/hanxin/index.ts

@@ -0,0 +1,18 @@
+/*!
+ * 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.
+ */
+
+/** Public Han Xin Code API. @module hanxin */
+
+export * from './tables.js';
+export * from './encoder.js';
+export * from './decoder.js';
+export * from './detector.js';

package/src/ts/hanxin/tables.d.ts

@@ -0,0 +1,80 @@
+/*!
+ * 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.
+ */
+/**
+ * Han Xin Code structural tables and geometry.
+ *
+ * This module deliberately starts with the compact, alignment-free part of
+ * ISO/IEC 20830: versions 1 through 3.  Keeping the function pattern mask in
+ * one place makes the encoder, decoder and detector agree about every payload
+ * cell and prevents accidental data placement over structural information.
+ *
+ * @module hanxin/tables
+ */
+import { BitMatrix } from '../core/bit-matrix.js';
+import { GaloisField } from '../core/galois-field.js';
+export declare const HANXIN_MIN_VERSION = 1;
+export declare const HANXIN_MAX_VERSION = 3;
+export declare const HANXIN_VERSIONS: readonly [1, 2, 3];
+export type HanXinVersion = typeof HANXIN_VERSIONS[number];
+export declare const HANXIN_ECC_LEVELS: readonly ['L1', 'L2', 'L3', 'L4'];
+export type HanXinEccLevel = typeof HANXIN_ECC_LEVELS[number];
+/** Han Xin's data field is GF(2^8) with x^8+x^6+x^5+x+1. */
+export declare const GF256_HANXIN: GaloisField;
+/** Total codewords, including error correction, for versions 1 through 3. */
+export declare const HANXIN_TOTAL_CODEWORDS: readonly [25, 37, 50];
+/** Data modules, including the five zero remainder modules in each compact version. */
+export declare const HANXIN_DATA_MODULES: readonly [205, 301, 405];
+/** Unused tail modules after the complete codeword stream. */
+export declare const HANXIN_REMAINDER_BITS: readonly [5, 5, 5];
+/** @returns {number} Side length in modules. */
+export declare function hanXinSize(version: number): number;
+/** @returns {HanXinVersion} */
+export declare function normalizeHanXinVersion(value: unknown): HanXinVersion;
+/** @returns {HanXinEccLevel} */
+export declare function normalizeHanXinEcc(value: unknown): HanXinEccLevel;
+/** @returns {number} Index of an error-correction level. */
+export declare function hanXinEccIndex(level: HanXinEccLevel): number;
+/** @returns {{blockCount:number,dataCodewords:number,eccCodewords:number}} */
+export declare function hanXinEcLayout(version: HanXinVersion, level: HanXinEccLevel): {
+    blockCount: number;
+    dataCodewords: number;
+    eccCodewords: number;
+};
+/** @returns {number} Data codewords for a version and EC level. */
+export declare function hanXinDataCodewords(version: HanXinVersion, level: HanXinEccLevel): number;
+/** Four orientation-specific 7x7 finder patterns, packed MSB first. */
+export declare const HANXIN_FINDER_TOP_LEFT: readonly [127, 64, 95, 80, 87, 87, 87];
+export declare const HANXIN_FINDER_SIDE: readonly [127, 1, 125, 5, 117, 117, 117];
+export declare const HANXIN_FINDER_BOTTOM_RIGHT: readonly [117, 117, 117, 5, 125, 1, 127];
+export type HanXinCoordinate = readonly [number, number];
+/** Return the function modules and their fixed darkness for a version. */
+export declare function createHanXinFunctionGrid(version: HanXinVersion): {
+    matrix: BitMatrix;
+    reserved: Uint8Array;
+};
+/** Return payload positions in the normative row-major order. */
+export declare function hanXinDataCoordinates(version: HanXinVersion): HanXinCoordinate[];
+/** Whether a data module is inverted by one of Han Xin's four masks. */
+export declare function hanXinMaskFlip(mask: number, x: number, y: number): boolean;
+/** Build the 34 structural bits protected by the GF(16) short RS block. */
+export declare function hanXinFunctionInfoBits(version: HanXinVersion, level: HanXinEccLevel, mask: number): boolean[];
+/** Place both redundant structural-information copies in the fixed strips. */
+export declare function placeHanXinFunctionInfo(matrix: BitMatrix, version: HanXinVersion, level: HanXinEccLevel, mask: number): void;
+/** Decode a structural information copy, correcting up to two nibble errors. */
+export declare function decodeHanXinFunctionInfo(matrix: BitMatrix, version: HanXinVersion): {
+    version: HanXinVersion;
+    level: HanXinEccLevel;
+    mask: number;
+    corrections: number;
+};
+/** Verify all fixed modules and count the payload cells. */
+export declare function validateHanXinTables(): string[];