@sythos/js_barcode_universal 1.5.13 → 1.5.15

package/src/js/hanxin/decoder.js

@@ -0,0 +1,299 @@
+/*!
+ * 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, HANXIN_DATA_MODULES, HANXIN_TOTAL_CODEWORDS, createHanXinFunctionGrid, decodeHanXinFunctionInfo, hanXinDataCoordinates, hanXinEcLayout, hanXinMaskFlip, hanXinSize, } from './tables.js';
+function rotateMatrix(source, rotation) {
+    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) {
+    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) {
+    const size = hanXinSize(version);
+    const cells = new Set();
+    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, version) {
+    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) {
+    const codewords = new Array(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, version, mask) {
+    const coordinates = hanXinDataCoordinates(version);
+    const total = HANXIN_DATA_MODULES[version - 1];
+    const codewordBits = HANXIN_TOTAL_CODEWORDS[version - 1] * 8;
+    const wire = new Array(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) {
+    while (reader.available() > 0) {
+        if (reader.readBit())
+            throw new FormatError('Han Xin: non-zero data follows the payload terminator');
+    }
+}
+function utf8Bytes(text) {
+    return new TextEncoder().encode(text);
+}
+function decodeByteText(bytes) {
+    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) {
+    const groups = [];
+    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();
+            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) {
+    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) {
+    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) {
+    let submode = 1;
+    const characters = [];
+    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) {
+    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) {
+    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) {
+    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) {
+    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, options = {}) {
+    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 = 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]) {
+                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,
+                        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/js/hanxin/detector.js

@@ -0,0 +1,122 @@
+/*!
+ * 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 } from './decoder.js';
+import { hanXinSize } from './tables.js';
+function boundsForPolarity(image, inverted) {
+    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, bounds, version, inverted) {
+    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) {
+    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 = [];
+    for (const inverted of [false, true]) {
+        const bounds = boundsForPolarity(binaryImage, inverted);
+        if (!bounds)
+            continue;
+        for (const version of [1, 2, 3]) {
+            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;
+            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) {
+    let detection;
+    try {
+        detection = detectHanXin(binaryImage);
+    }
+    catch {
+        return null;
+    }
+    if (!detection)
+        return null;
+    return {
+        ...detection.result,
+        corners: detection.corners,
+        moduleSize: detection.moduleSize,
+    };
+}

package/src/js/hanxin/encoder.js

@@ -0,0 +1,259 @@
+/*!
+ * 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.
+ */
+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, createHanXinFunctionGrid, hanXinDataCoordinates, hanXinDataCodewords, hanXinEcLayout, hanXinMaskFlip, hanXinSize, normalizeHanXinEcc, normalizeHanXinVersion, placeHanXinFunctionInfo, } from './tables.js';
+function inputBytes(value) {
+    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) {
+    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) {
+    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, mode) {
+    return mode === 1 ? text1Value(codePoint) : text2Value(codePoint);
+}
+function selectMode(text, requested) {
+    const mode = requested == null ? 'auto' : String(requested).toLowerCase();
+    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);
+        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, writer) {
+    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, writer) {
+    let submode = 1;
+    for (const point of Array.from(text)) {
+        const cp = point.codePointAt(0);
+        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, writer) {
+    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, mode) {
+    const source = inputBytes(value);
+    const writer = new BitWriter();
+    if (mode === 'numeric') {
+        writer.put(1, 4);
+        encodeNumeric(source.text, writer);
+    }
+    else if (mode === 'text') {
+        writer.put(2, 4);
+        encodeText(source.text, writer);
+    }
+    else {
+        encodeByte(source.bytes, writer);
+    }
+    return writer;
+}
+function picketFence(codewords) {
+    const output = [];
+    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, version, codewords, mask) {
+    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, version, level, mask) {
+    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) => {
+        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 = [];
+        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 = [];
+        for (let y = 0; y < candidate.height; y++)
+            column.push(candidate.get(x, y));
+        runPenalty(column);
+    }
+    return penalty;
+}
+function chooseMask(base, version, level, requested) {
+    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, version, level, requestedMask) {
+    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, options = {}) {
+    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, options = {}) {
+    return encodeHanXin(bytes, { ...options, mode: 'byte' });
+}
+/** Expose the implemented geometric side length for callers building rasters. */
+export function hanXinDimension(version) {
+    return hanXinSize(Number(version));
+}

package/src/js/hanxin/index.js

@@ -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';