feat: add Han Xin Unicode mode

Author: Streetblock

README.md

@@ -47,7 +47,8 @@ The app controller and UI. Manages state, binds DOM events, and provides the int
 The `feat/han-xin-core` branch adds a native ISO/IEC 20830-oriented Han Xin
 encoder without changing the QR studio UI. It supports versions 1–84, ECC
 levels L1–L4, automatic mode segmentation, GB18030 text, raw bytes, GS1, all four
-masks and a neutral SVG matrix renderer. See [docs/HANXIN.md](docs/HANXIN.md)
+masks, dedicated UTF-8 Unicode compression and a neutral SVG matrix renderer.
+See [docs/HANXIN.md](docs/HANXIN.md)
 for the public API and reference notes.
 
 ## Installation & Usage

docs/HANXIN.md

@@ -17,6 +17,7 @@ const symbol = new HanXinCore('汉信码 123456', {
   eci: 0,                // optional ECI assignment number, 0–999999
   gs1: false,            // true for a GS1 element string
   uri: false,            // true for compact URI/URL encoding
+  unicode: false,        // true for dedicated UTF-8 Unicode compression
 }).generate()
 
 const svg = new HanXinSvgRenderer(symbol, {
@@ -46,6 +47,7 @@ silently selecting a different symbol.
 - ECI headers
 - GS1 framing and FNC1 element separators
 - URI-A, URI-B, URI-C and compact `%XX` byte sequences
+- dedicated Unicode mode with adaptive 1-, 2-, 3- and 4-byte grouping
 - all 84 versions and ECC levels L1–L4
 - ISO-style structural information, assistant/alignment patterns, RS blocks,
   picket-fence reordering and all four data masks
@@ -64,9 +66,16 @@ built-in fragments such as `https://`, `www.`, `.com` and `.org`. Existing
 must therefore be percent-encoded by the caller. URI mode cannot be combined
 with GS1 or ECI.
 
-The optional dedicated Unicode mode is not currently exposed. One ECI value
-applies to the complete ordinary input; a public multi-segment ECI API is not
-yet provided.
+Set `unicode: true` for the dedicated Han Xin Unicode mode. It converts string
+input to strict UTF-8, chooses cost-optimal 1-, 2-, 3- and 4-byte groups, and
+compresses each byte column as a minimum value plus unsigned differences.
+This differs from ordinary string input, which uses GB18030 and may select the
+Chinese region modes. Unicode mode accepts strings only and cannot be combined
+with GS1, URI or ECI. Its result segments are measured in UTF-8 bytes and expose
+their `byteWidth` and group `count`.
+
+One ECI value applies to the complete ordinary input; a public multi-segment
+ECI API is not yet provided.
 
 ## References and verification
 
@@ -78,6 +87,9 @@ yet provided.
   installed by this repository and is not imported by production code.
 - GS1 framing, FNC1 separator encoding and numeric-boundary optimization are
   verified against BWIPP's MIT-licensed Han Xin PostScript reference.
+- Unicode framing, counters and compression codewords are verified against
+  Aspose.BarCode for Java as an external development oracle. Aspose is not
+  installed by this repository and is never a runtime dependency.
 
 BWIPP currently writes an alternating pattern into the final six structural
 information bits. ISO/IEC 20830:2021 and current Zint clear those bits. This

libs/HanXinCompaction.js

@@ -92,6 +92,24 @@ export function normalizeHanXinInput(input) {
   throw new TypeError('Han Xin data must be a string, Uint8Array, typed-array view, or ArrayBuffer');
 }
 
+export function normalizeHanXinUnicodeInput(input) {
+  if (typeof input !== 'string') throw new TypeError('Han Xin Unicode mode requires string input');
+  if (!input.length) throw new RangeError('Han Xin data must not be empty');
+  const units = [];
+  for (const character of input) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint >= 0xd800 && codePoint <= 0xdfff) {
+      throw new RangeError(`Han Xin Unicode mode cannot encode an unpaired surrogate U+${codePoint.toString(16).toUpperCase()}`);
+    }
+    if (codePoint < 0x80) units.push(codePoint);
+    else if (codePoint < 0x800) units.push(0xc0 | codePoint >>> 6, 0x80 | codePoint & 0x3f);
+    else if (codePoint < 0x10000) units.push(0xe0 | codePoint >>> 12, 0x80 | codePoint >>> 6 & 0x3f, 0x80 | codePoint & 0x3f);
+    else units.push(0xf0 | codePoint >>> 18, 0x80 | codePoint >>> 12 & 0x3f,
+      0x80 | codePoint >>> 6 & 0x3f, 0x80 | codePoint & 0x3f);
+  }
+  return { units, inputType: 'text', encoding: 'UTF-8' };
+}
+
 const isDigit = (value) => value >= 0x30 && value <= 0x39;
 const isUpper = (value) => value >= 0x41 && value <= 0x5a;
 const isLower = (value) => value >= 0x61 && value <= 0x7a;
@@ -204,6 +222,75 @@ class BitBuffer {
   }
 }
 
+const unicodeCountWidth = (count) => count <= 7 ? 4 : count <= 63 ? 8 : count <= 511 ? 12 : count <= 4095 ? 16 : 20;
+
+function appendUnicodeCount(output, count) {
+  if (count < 1 || count > 32767) throw new RangeError('A Han Xin Unicode segment cannot exceed 32767 byte groups');
+  if (count <= 7) output.append(count, 4);
+  else if (count <= 63) output.append(0x80 | count, 8);
+  else if (count <= 511) output.append(0xc00 | count, 12);
+  else if (count <= 4095) output.append(0xe000 | count, 16);
+  else output.append(0xf0000 | count, 20);
+}
+
+function compactUnicodeHanXin(units, eci) {
+  if (eci) throw new RangeError('Han Xin Unicode mode does not support an ECI header');
+  const costs = Array(units.length + 1).fill(Number.POSITIVE_INFINITY);
+  const choices = Array(units.length).fill(null);
+  costs[units.length] = 0;
+
+  for (let start = units.length - 1; start >= 0; start--) {
+    for (let width = 1; width <= 4; width++) {
+      const minima = Array(width).fill(0xff);
+      const maxima = Array(width).fill(0);
+      const maximumGroups = Math.min(32767, Math.floor((units.length - start) / width));
+      for (let count = 1; count <= maximumGroups; count++) {
+        const groupStart = start + (count - 1) * width;
+        for (let column = 0; column < width; column++) {
+          const value = units[groupStart + column];
+          minima[column] = Math.min(minima[column], value);
+          maxima[column] = Math.max(maxima[column], value);
+        }
+        const differenceWidths = minima.map((minimum, column) => {
+          const difference = maxima[column] - minimum;
+          return difference ? Math.floor(Math.log2(difference)) + 1 : 0;
+        });
+        const end = start + count * width;
+        const bitLength = 4 + unicodeCountWidth(count) + width * 12 +
+          count * differenceWidths.reduce((sum, value) => sum + value, 0);
+        const candidate = bitLength + costs[end];
+        if (candidate < costs[start]) {
+          costs[start] = candidate;
+          choices[start] = { width, count, end, minima: [...minima], differenceWidths };
+        }
+      }
+    }
+  }
+
+  const output = new BitBuffer();
+  const modes = Array(units.length);
+  const segments = [];
+  output.append(9, 4);
+  for (let start = 0; start < units.length;) {
+    const choice = choices[start];
+    output.append(choice.width, 4);
+    appendUnicodeCount(output, choice.count);
+    for (const width of choice.differenceWidths) output.append(width, 4);
+    for (const minimum of choice.minima) output.append(minimum, 8);
+    for (let position = start; position < choice.end; position += choice.width) {
+      for (let column = 0; column < choice.width; column++) {
+        output.append(units[position + column] - choice.minima[column], choice.differenceWidths[column]);
+      }
+    }
+    modes.fill(`u${choice.width}`, start, choice.end);
+    segments.push({ mode: `u${choice.width}`, start, end: choice.end, length: choice.end - start,
+      byteWidth: choice.width, count: choice.count });
+    start = choice.end;
+  }
+  output.append(15, 4);
+  return { bits: output.bits, modes, segments };
+}
+
 const URI_A_TOKENS = [
   ...'abcdefghijklmnopqrstuvwxyz0123456789./-_~:@?#=+$&',
   'http://', 'https://', 'ftp://', 'mailto:', 'ldap://', 'tel:', 'urn:', 'www.',
@@ -420,11 +507,12 @@ function segmentsFromModes(modes) {
   return result;
 }
 
-export function compactHanXin(units, { eci = 0, gs1 = false, uri = false } = {}) {
+export function compactHanXin(units, { eci = 0, gs1 = false, uri = false, unicode = false } = {}) {
   if (!Number.isInteger(eci) || eci < 0 || eci > 999999) throw new RangeError('ECI must be an integer from 0 to 999999');
-  if (gs1 && uri) throw new RangeError('Han Xin GS1 and URI modes cannot be combined');
+  if ([gs1, uri, unicode].filter(Boolean).length > 1) throw new RangeError('Han Xin GS1, URI, and Unicode modes cannot be combined');
   if (gs1) return compactGs1HanXin(units, eci);
   if (uri) return compactUriHanXin(units, eci);
+  if (unicode) return compactUnicodeHanXin(units, eci);
   const modes = selectHanXinModes(units);
   const segments = segmentsFromModes(modes);
   const output = new BitBuffer();

libs/HanXinCore.js

@@ -1,4 +1,4 @@
-import { compactHanXin, normalizeHanXinInput } from './HanXinCompaction.js';
+import { compactHanXin, normalizeHanXinInput, normalizeHanXinUnicodeInput } from './HanXinCompaction.js';
 import { addHanXinErrorCorrection } from './HanXinErrorCorrection.js';
 import { createHanXinGrid, populateAndMaskHanXin } from './HanXinMatrix.js';
 import { HAN_XIN_DATA_CODEWORDS, HAN_XIN_TOTAL_CODEWORDS } from './HanXinTables.js';
@@ -38,10 +38,12 @@ export class HanXinCore {
     const requestedMask = parseMask(this.options.mask);
     if (this.options.gs1 != null && typeof this.options.gs1 !== 'boolean') throw new TypeError('Han Xin gs1 must be a boolean');
     if (this.options.uri != null && typeof this.options.uri !== 'boolean') throw new TypeError('Han Xin uri must be a boolean');
+    if (this.options.unicode != null && typeof this.options.unicode !== 'boolean') throw new TypeError('Han Xin unicode must be a boolean');
     const gs1 = this.options.gs1 === true;
     const uri = this.options.uri === true;
-    const normalized = normalizeHanXinInput(this.data);
-    const compacted = compactHanXin(normalized.units, { eci: this.options.eci ?? 0, gs1, uri });
+    const unicode = this.options.unicode === true;
+    const normalized = unicode ? normalizeHanXinUnicodeInput(this.data) : normalizeHanXinInput(this.data);
+    const compacted = compactHanXin(normalized.units, { eci: this.options.eci ?? 0, gs1, uri, unicode });
     const requiredCodewords = Math.ceil(compacted.bits.length / 8);
     let version = forcedVersion;
     if (version == null) {
@@ -71,6 +73,7 @@ export class HanXinCore {
       encoding: normalized.encoding,
       gs1,
       uri,
+      unicode,
       eci: this.options.eci ?? 0,
       bitLength: compacted.bits.length,
       dataCodewords,
@@ -81,6 +84,7 @@ export class HanXinCore {
       segments: compacted.segments.map((segment) => ({ ...segment, name: {
         n: 'numeric', t: 'text', b: 'binary', 1: 'region-one', 2: 'region-two', d: 'double-byte', f: 'four-byte', g: 'gs1-separator',
         ua: 'uri-a', ub: 'uri-b', uc: 'uri-c', up: 'uri-percent',
+        u1: 'unicode-1-byte', u2: 'unicode-2-byte', u3: 'unicode-3-byte', u4: 'unicode-4-byte',
       }[segment.mode] })),
       capacity: {
         dataCodewords: dataCapacity,

tests/hanxin-core.test.mjs

@@ -158,6 +158,47 @@ test('validates URI mode combinations and character set', () => {
   assert.throws(() => new HanXinCore('https://example.com/a b', { uri: true }).generate(), /character sets/);
 });
 
+test('matches independent Han Xin Unicode reference codewords', () => {
+  const vectors = [
+    ['A', [0x91, 0x10, 0x41, 0xf0]],
+    ['Привет', [0x92, 0x61, 0x6d, 0x08, 0x03, 0xf0, 0x1c, 0x32, 0x6b, 0x0b, 0xc0]],
+    ['🙂', [0x91, 0x47, 0x82, 0xdc, 0x74, 0xb8, 0x0f]],
+  ];
+  for (const [text, expected] of vectors) {
+    const result = new HanXinCore(text, { unicode: true, version: 10, errorCorrection: 'L1', mask: 0 }).generate();
+    assert.deepEqual(result.dataCodewords.slice(0, expected.length), expected);
+    assert.equal(result.unicode, true);
+    assert.equal(result.encoding, 'UTF-8');
+  }
+});
+
+test('uses Unicode byte-column compression and variable-length group counters', () => {
+  const repeated = new HanXinCore('a'.repeat(12), { unicode: true }).generate();
+  assert.equal(repeated.bitLength, 32);
+  assert.deepEqual(repeated.segments.map(({ name, byteWidth, count, length }) => ({ name, byteWidth, count, length })), [
+    { name: 'unicode-1-byte', byteWidth: 1, count: 12, length: 12 },
+  ]);
+  assert.equal(new HanXinCore('a'.repeat(7), { unicode: true }).generate().bitLength, 28);
+  assert.equal(new HanXinCore('a'.repeat(8), { unicode: true }).generate().bitLength, 32);
+
+  const cyrillic = new HanXinCore('Привет', { unicode: true }).generate();
+  assert.deepEqual(cyrillic.segments.map(({ name, byteWidth, count }) => ({ name, byteWidth, count })), [
+    { name: 'unicode-2-byte', byteWidth: 2, count: 6 },
+  ]);
+  assert.ok(cyrillic.bitLength < new HanXinCore('Привет').generate().bitLength);
+  assert.equal(new HanXinCore('汉'.repeat(6), { unicode: true }).generate().segments[0].name, 'unicode-3-byte');
+  assert.equal(new HanXinCore('🙂'.repeat(6), { unicode: true }).generate().segments[0].name, 'unicode-4-byte');
+});
+
+test('validates Unicode input and mutually exclusive specialized modes', () => {
+  assert.throws(() => new HanXinCore(Uint8Array.of(0x41), { unicode: true }).generate(), /string input/);
+  assert.throws(() => new HanXinCore('\ud800', { unicode: true }).generate(), /unpaired surrogate/);
+  assert.throws(() => new HanXinCore('text', { unicode: 'yes' }).generate(), /boolean/);
+  assert.throws(() => new HanXinCore('text', { unicode: true, eci: 26 }).generate(), /ECI/);
+  assert.throws(() => new HanXinCore('text', { unicode: true, gs1: true }).generate(), /cannot be combined/);
+  assert.throws(() => new HanXinCore('text', { unicode: true, uri: true }).generate(), /cannot be combined/);
+});
+
 test('maps representative Unicode points to GB18030 without a runtime codec', () => {
   assert.deepEqual(unicodeToGb18030(0x41), [0x41]);
   assert.deepEqual(unicodeToGb18030('汉'.codePointAt(0)), [0xbaba]);