@sythos/js_barcode_universal 1.5.13 → 1.5.15

package/src/ts/hanxin/tables.ts

@@ -0,0 +1,348 @@
+/*!
+ * 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 { GF16, GaloisField } from '../core/galois-field.js';
+import { rsDecode, rsEncode } from '../core/reed-solomon.js';
+import { FormatError } from '../core/errors.js';
+
+export const HANXIN_MIN_VERSION = 1;
+export const HANXIN_MAX_VERSION = 3;
+export const HANXIN_VERSIONS = [1, 2, 3] as const;
+export type HanXinVersion = typeof HANXIN_VERSIONS[number];
+
+export const HANXIN_ECC_LEVELS = ['L1', 'L2', 'L3', 'L4'] as const;
+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 const GF256_HANXIN = new GaloisField({
+  size: 256,
+  primitive: 0x163,
+  name: 'GF(256)/HanXin',
+});
+
+/** Total codewords, including error correction, for versions 1 through 3. */
+export const HANXIN_TOTAL_CODEWORDS = [25, 37, 50] as const;
+
+/** Data modules, including the five zero remainder modules in each compact version. */
+export const HANXIN_DATA_MODULES = [205, 301, 405] as const;
+
+/** Unused tail modules after the complete codeword stream. */
+export const HANXIN_REMAINDER_BITS = [5, 5, 5] as const;
+
+/**
+ * One Reed--Solomon batch is `(blockCount, dataCodewords, eccCodewords)`.
+ * The compact versions use one block at every error-correction level.
+ */
+const EC_BATCHES: ReadonlyArray<ReadonlyArray<readonly [number, number, number]>> = [
+  [[1, 21, 4], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+  [[1, 17, 8], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+  [[1, 13, 12], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+  [[1, 9, 16], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+  [[1, 31, 6], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+  [[1, 25, 12], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+  [[1, 19, 18], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+  [[1, 15, 22], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+  [[1, 42, 8], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+  [[1, 34, 16], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+  [[1, 26, 24], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+  [[1, 20, 30], [0, 0, 0], [0, 0, 0], [0, 0, 0]],
+];
+
+/** @returns {number} Side length in modules. */
+export function hanXinSize(version: number): number {
+  if (!Number.isInteger(version) || version < HANXIN_MIN_VERSION || version > HANXIN_MAX_VERSION) {
+    throw new FormatError(`Han Xin: supported versions are 1-3, got ${version}`);
+  }
+  return 21 + version * 2;
+}
+
+/** @returns {HanXinVersion} */
+export function normalizeHanXinVersion(value: unknown): HanXinVersion {
+  const version = typeof value === 'string' ? Number(value.replace(/^V/i, '')) : Number(value);
+  if (!Number.isInteger(version) || version < HANXIN_MIN_VERSION || version > HANXIN_MAX_VERSION) {
+    throw new FormatError(`Han Xin: supported versions are 1-3, got ${String(value)}`);
+  }
+  return version as HanXinVersion;
+}
+
+/** @returns {HanXinEccLevel} */
+export function normalizeHanXinEcc(value: unknown): HanXinEccLevel {
+  if (value == null) return 'L1';
+  if (typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 4) {
+    return HANXIN_ECC_LEVELS[value - 1];
+  }
+  const text = String(value).toUpperCase();
+  if ((HANXIN_ECC_LEVELS as readonly string[]).includes(text)) return text as HanXinEccLevel;
+  throw new FormatError(`Han Xin: error correction must be L1, L2, L3 or L4, got ${String(value)}`);
+}
+
+/** @returns {number} Index of an error-correction level. */
+export function hanXinEccIndex(level: HanXinEccLevel): number {
+  return HANXIN_ECC_LEVELS.indexOf(level);
+}
+
+/** @returns {{blockCount:number,dataCodewords:number,eccCodewords:number}} */
+export function hanXinEcLayout(version: HanXinVersion, level: HanXinEccLevel) {
+  const entry = EC_BATCHES[(version - 1) * 4 + hanXinEccIndex(level)][0];
+  return { blockCount: entry[0], dataCodewords: entry[1], eccCodewords: entry[2] };
+}
+
+/** @returns {number} Data codewords for a version and EC level. */
+export function hanXinDataCodewords(version: HanXinVersion, level: HanXinEccLevel): number {
+  return hanXinEcLayout(version, level).dataCodewords;
+}
+
+/** Four orientation-specific 7x7 finder patterns, packed MSB first. */
+export const HANXIN_FINDER_TOP_LEFT = [0x7f, 0x40, 0x5f, 0x50, 0x57, 0x57, 0x57] as const;
+export const HANXIN_FINDER_SIDE = [0x7f, 0x01, 0x7d, 0x05, 0x75, 0x75, 0x75] as const;
+export const HANXIN_FINDER_BOTTOM_RIGHT = [0x75, 0x75, 0x75, 0x05, 0x7d, 0x01, 0x7f] as const;
+
+export type HanXinCoordinate = readonly [number, number];
+
+function index(size: number, x: number, y: number): number {
+  return y * size + x;
+}
+
+function reserve(mask: Uint8Array, matrix: BitMatrix, x: number, y: number, dark: boolean): void {
+  if (x < 0 || y < 0 || x >= matrix.width || y >= matrix.height) return;
+  mask[index(matrix.width, x, y)] = 1;
+  matrix.setValue(x, y, dark);
+}
+
+function placeFinder(
+  mask: Uint8Array,
+  matrix: BitMatrix,
+  offsetX: number,
+  offsetY: number,
+  rows: readonly number[],
+): void {
+  for (let y = 0; y < 7; y++) for (let x = 0; x < 7; x++) {
+    reserve(mask, matrix, offsetX + x, offsetY + y, (rows[y] & (0x40 >> x)) !== 0);
+  }
+}
+
+/** Return the function modules and their fixed darkness for a version. */
+export function createHanXinFunctionGrid(version: HanXinVersion): {
+  matrix: BitMatrix;
+  reserved: Uint8Array;
+} {
+  const size = hanXinSize(version);
+  const matrix = new BitMatrix(size, size);
+  const reserved = new Uint8Array(size * size);
+
+  placeFinder(reserved, matrix, 0, 0, HANXIN_FINDER_TOP_LEFT);
+  placeFinder(reserved, matrix, size - 7, 0, HANXIN_FINDER_SIDE);
+  placeFinder(reserved, matrix, 0, size - 7, HANXIN_FINDER_SIDE);
+  placeFinder(reserved, matrix, size - 7, size - 7, HANXIN_FINDER_BOTTOM_RIGHT);
+
+  // The one-module light separators belong to the function region.
+  for (let i = 0; i < 8; i++) {
+    reserve(reserved, matrix, i, 7, false);
+    reserve(reserved, matrix, 7, i, false);
+    reserve(reserved, matrix, size - i - 1, 7, false);
+    reserve(reserved, matrix, 7, size - i - 1, false);
+    reserve(reserved, matrix, size - 8, i, false);
+    reserve(reserved, matrix, i, size - 8, false);
+    reserve(reserved, matrix, size - 8, size - i - 1, false);
+    reserve(reserved, matrix, size - i - 1, size - 8, false);
+  }
+
+  // Two redundant copies of the 34-bit structural information are carried
+  // around the finder patterns. The four 9-module strips below reserve all
+  // positions; shared corners make the wire order 9+8+9+8 modules per copy.
+  for (let i = 0; i < 9; i++) {
+    reserve(reserved, matrix, i, 8, false);
+    reserve(reserved, matrix, 8, i, false);
+    reserve(reserved, matrix, size - i - 1, 8, false);
+    reserve(reserved, matrix, 8, size - i - 1, false);
+    reserve(reserved, matrix, size - 9, i, false);
+    reserve(reserved, matrix, i, size - 9, false);
+    reserve(reserved, matrix, size - 9, size - i - 1, false);
+    reserve(reserved, matrix, size - i - 1, size - 9, false);
+  }
+
+  return { matrix, reserved };
+}
+
+/** Return payload positions in the normative row-major order. */
+export function hanXinDataCoordinates(version: HanXinVersion): HanXinCoordinate[] {
+  const { reserved } = createHanXinFunctionGrid(version);
+  const size = hanXinSize(version);
+  const result: HanXinCoordinate[] = [];
+  for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+    if (reserved[index(size, x, y)] === 0) result.push([x, y]);
+  }
+  return result;
+}
+
+/** Whether a data module is inverted by one of Han Xin's four masks. */
+export function hanXinMaskFlip(mask: number, x: number, y: number): boolean {
+  if (!Number.isInteger(mask) || mask < 0 || mask > 3) return false;
+  const i = y + 1;
+  const j = x + 1;
+  // The first public mask is the constant-zero (no inversion) mask.  The
+  // remaining three masks are the parity expressions from the format
+  // definition, represented here with zero-based API values 1-3.
+  if (mask === 0) return false;
+  if (mask === 1) return ((i + j) & 1) === 0;
+  if (mask === 2) return ((((i + j) % 3) + (j % 3)) & 1) === 0;
+  if (j === 0 || i === 0) return false;
+  return (((i % j) + (j % i) + (i % 3) + (j % 3)) & 1) === 0;
+}
+
+/** Build the 34 structural bits protected by the GF(16) short RS block. */
+export function hanXinFunctionInfoBits(
+  version: HanXinVersion,
+  level: HanXinEccLevel,
+  mask: number,
+): boolean[] {
+  if (!Number.isInteger(mask) || mask < 0 || mask > 3) throw new FormatError('Han Xin: mask must be an integer from 0 to 3');
+  const value = ((version + 20) << 4) | (hanXinEccIndex(level) << 2) | mask;
+  const data = [(value >>> 8) & 0x0f, (value >>> 4) & 0x0f, value & 0x0f];
+  const ecc = rsEncode(data, 4, GF16, 1);
+  const bits: boolean[] = [];
+  for (const symbol of data.concat(ecc)) for (let bit = 3; bit >= 0; bit--) bits.push(((symbol >>> bit) & 1) !== 0);
+  // The six non-codeword bits are part of the fixed Han Xin function
+  // information pattern, not arbitrary padding.
+  for (const bit of [false, true, false, true, false, true]) bits.push(bit);
+  if (bits.length !== 34) throw new FormatError('Han Xin: invalid function information length');
+  return bits;
+}
+
+/** Place both redundant structural-information copies in the fixed strips. */
+export function placeHanXinFunctionInfo(
+  matrix: BitMatrix,
+  version: HanXinVersion,
+  level: HanXinEccLevel,
+  mask: number,
+): void {
+  const size = hanXinSize(version);
+  const bits = hanXinFunctionInfoBits(version, level, mask);
+  // The four strips contain 9 + 8 + 9 + 8 modules.  The corner cells where
+  // two strips meet are shared; they must not consume the preceding bit a
+  // second time.
+  for (let i = 0; i < 9; i++) {
+    matrix.setValue(i, 8, bits[i]);
+    matrix.setValue(size - 1 - i, size - 9, bits[i]);
+  }
+  for (let i = 0; i < 8; i++) {
+    matrix.setValue(8, 7 - i, bits[9 + i]);
+    matrix.setValue(size - 9, size - 8 + i, bits[9 + i]);
+  }
+  for (let i = 0; i < 9; i++) {
+    matrix.setValue(size - 9, i, bits[i + 17]);
+    matrix.setValue(8, size - 1 - i, bits[i + 17]);
+  }
+  for (let i = 0; i < 8; i++) {
+    matrix.setValue(size - 8 + i, 8, bits[26 + i]);
+    matrix.setValue(7 - i, size - 9, bits[26 + i]);
+  }
+}
+
+function readInfoCopy(matrix: BitMatrix, version: HanXinVersion): boolean[] {
+  const size = hanXinSize(version);
+  const bits: boolean[] = [];
+  for (let i = 0; i < 9; i++) bits.push(matrix.get(i, 8));
+  for (let i = 0; i < 8; i++) bits.push(matrix.get(8, 7 - i));
+  for (let i = 0; i < 9; i++) bits.push(matrix.get(size - 9, i));
+  for (let i = 0; i < 8; i++) bits.push(matrix.get(size - 8 + i, 8));
+  return bits;
+}
+
+/** Decode a structural information copy, correcting up to two nibble errors. */
+export function decodeHanXinFunctionInfo(matrix: BitMatrix, version: HanXinVersion): {
+  version: HanXinVersion;
+  level: HanXinEccLevel;
+  mask: number;
+  corrections: number;
+} {
+  const copies = [readInfoCopy(matrix, version)];
+  const size = hanXinSize(version);
+  const second = new BitMatrix(size, size);
+  // The second copy is read directly in its wire order.  Keeping this helper
+  // local avoids exposing an orientation-specific representation publicly.
+  for (let i = 0; i < 9; i++) {
+    second.setValue(i, 8, matrix.get(size - 1 - i, size - 9));
+  }
+  for (let i = 0; i < 8; i++) {
+    second.setValue(8, 7 - i, matrix.get(size - 9, size - 8 + i));
+  }
+  for (let i = 0; i < 9; i++) {
+    second.setValue(size - 9, i, matrix.get(8, size - 1 - i));
+  }
+  for (let i = 0; i < 8; i++) {
+    second.setValue(size - 8 + i, 8, matrix.get(7 - i, size - 9));
+  }
+  copies.push(readInfoCopy(second, version));
+
+  let best: { value: number[]; corrections: number } | null = null;
+  for (const bits of copies) {
+    const fixedTail = [false, true, false, true, false, true];
+    if (bits.length !== 34 || fixedTail.some((bit, index) => bits[28 + index] !== bit)) continue;
+    const symbols = [] as number[];
+    for (let i = 0; i < 7; i++) {
+      let symbol = 0;
+      for (let bit = 0; bit < 4; bit++) symbol = (symbol << 1) | (bits[i * 4 + bit] ? 1 : 0);
+      symbols.push(symbol);
+    }
+    try {
+      const corrections = rsDecode(symbols, 4, GF16, 1);
+      if (!best || corrections < best.corrections) best = { value: symbols, corrections };
+    } catch {
+      // Try the redundant copy before rejecting the symbol.
+    }
+  }
+  if (!best) throw new FormatError('Han Xin: structural information is unreadable');
+  const value = (best.value[0] << 8) | (best.value[1] << 4) | best.value[2];
+  const encodedVersion = (value >>> 4) - 20;
+  const levelIndex = (value >>> 2) & 3;
+  const mask = value & 3;
+  if (encodedVersion !== version) throw new FormatError('Han Xin: structural version disagrees with matrix dimensions');
+  return {
+    version,
+    level: HANXIN_ECC_LEVELS[levelIndex],
+    mask,
+    corrections: best.corrections,
+  };
+}
+
+/** Verify all fixed modules and count the payload cells. */
+export function validateHanXinTables(): string[] {
+  const errors: string[] = [];
+  for (const version of HANXIN_VERSIONS) {
+    const size = hanXinSize(version);
+    const cells = hanXinDataCoordinates(version).length;
+    if (cells !== HANXIN_DATA_MODULES[version - 1]) {
+      errors.push(`Version ${version}: ${cells} data modules, expected ${HANXIN_DATA_MODULES[version - 1]}`);
+    }
+    for (const level of HANXIN_ECC_LEVELS) {
+      const layout = hanXinEcLayout(version, level);
+      if (layout.dataCodewords + layout.eccCodewords !== HANXIN_TOTAL_CODEWORDS[version - 1]) {
+        errors.push(`Version ${version} ${level}: invalid RS block total`);
+      }
+    }
+    if (size !== 21 + version * 2) errors.push(`Version ${version}: invalid dimension`);
+  }
+  return errors;
+}

package/src/ts/image/height-coded.d.ts

@@ -0,0 +1,101 @@
+/*!
+ * 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-FileCopyrightText: 2026 Sythos (https://www.sythos.net)
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+/**
+ * Generic normalized bar-height profiles for future height-coded symbols.
+ *
+ * A profile uses a top and bottom edge in a unit-height coordinate system: zero
+ * is the top of the symbol and one is the bottom. The four-state profiles use
+ * the two independent edge extensions that are common to this class of
+ * symbols, while the two-state profile is the tracker/full subset. A concrete
+ * symbology remains responsible for its own data, checksum and orientation
+ * rules.
+ *
+ * @module image/height-coded
+ */
+/** A state value accepted by a height-coded bar profile. */
+export type HeightState = 0 | 1 | 2 | 3;
+/** Supported numbers of states. */
+export type HeightStateCount = 2 | 4;
+/** Normalized top and bottom edges of one height-coded bar. */
+export interface HeightCodedBar {
+    /** Top edge, normalized to the inclusive range 0..1. */
+    top: number;
+    /** Bottom edge, normalized to the inclusive range 0..1. */
+    bottom: number;
+}
+/**
+ * Validate one state and return its narrowed value.
+ *
+ * When `stateCount` is supplied, states outside that alphabet are rejected;
+ * leaving it out validates the complete four-state range.
+ *
+ * @param {number} state
+ * @param {2|4} [stateCount]
+ * @returns {HeightState}
+ */
+export declare function validateHeightState(state: number, stateCount?: HeightStateCount): HeightState;
+/**
+ * Return the normalized top and bottom edges for one state.
+ *
+ * State numbering is intentionally generic: 0 is tracker, 1 is ascender,
+ * 2 is descender and 3 is full for the four-state alphabet. The two-state
+ * alphabet exposes tracker (0) and full (1), so it is a strict subset of the
+ * four-state geometry and does not prescribe a postal format's semantics.
+ *
+ * @param {number} state
+ * @param {2|4} stateCount
+ * @returns {HeightCodedBar}
+ */
+export declare function barHeightProfile(state: number, stateCount: HeightStateCount): HeightCodedBar;
+/**
+ * Convert a state sequence to normalized top/bottom bar profiles.
+ *
+ * The returned array and every profile in it are newly allocated, so callers
+ * can safely adjust rendering coordinates without changing shared constants.
+ *
+ * @param {ArrayLike<number>} states
+ * @param {2|4} stateCount
+ * @returns {HeightCodedBar[]}
+ */
+export declare function encodeHeightProfile(states: ArrayLike<number>, stateCount: HeightStateCount): HeightCodedBar[];
+/**
+ * Convert normalized top/bottom bar profiles back to their states.
+ *
+ * Decoding is deliberately exact: a profile must match one of the canonical
+ * normalized pairs for the selected alphabet. Raster or measurement code can
+ * quantize its observations before calling this helper; accepting arbitrary
+ * in-range pairs here would turn malformed bars into valid states.
+ *
+ * @param {ArrayLike<HeightCodedBar>} profile
+ * @param {2|4} stateCount
+ * @returns {HeightState[]}
+ */
+export declare function decodeHeightProfile(profile: ArrayLike<HeightCodedBar>, stateCount: HeightStateCount): HeightState[];

package/src/ts/image/height-coded.ts

@@ -0,0 +1,227 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Generic normalized bar-height profiles for future height-coded symbols.
+ *
+ * A profile uses a top and bottom edge in a unit-height coordinate system: zero
+ * is the top of the symbol and one is the bottom. The four-state profiles use
+ * the two independent edge extensions that are common to this class of
+ * symbols, while the two-state profile is the tracker/full subset. A concrete
+ * symbology remains responsible for its own data, checksum and orientation
+ * rules.
+ *
+ * @module image/height-coded
+ */
+
+/** A state value accepted by a height-coded bar profile. */
+export type HeightState = 0 | 1 | 2 | 3;
+
+/** Supported numbers of states. */
+export type HeightStateCount = 2 | 4;
+
+/** Normalized top and bottom edges of one height-coded bar. */
+export interface HeightCodedBar {
+  /** Top edge, normalized to the inclusive range 0..1. */
+  top: number;
+  /** Bottom edge, normalized to the inclusive range 0..1. */
+  bottom: number;
+}
+
+const TRACKER_PROFILE: HeightCodedBar = { top: 0.25, bottom: 0.75 };
+const ASCENDER_PROFILE: HeightCodedBar = { top: 0, bottom: 0.75 };
+const DESCENDER_PROFILE: HeightCodedBar = { top: 0.25, bottom: 1 };
+const FULL_PROFILE: HeightCodedBar = { top: 0, bottom: 1 };
+
+// Keep validation and output allocations bounded when a caller passes data
+// originating in a file or camera pipeline.
+const MAX_PROFILE_LENGTH = 1_000_000;
+
+function validateStateCount(stateCount: unknown): HeightStateCount {
+  if (stateCount !== 2 && stateCount !== 4) {
+    throw new RangeError(`Height state count must be 2 or 4, got ${String(stateCount)}`);
+  }
+  return stateCount;
+}
+
+function validateProfileLength(value: unknown, label: string): number {
+  if (value === null || (typeof value !== 'object' && typeof value !== 'function')) {
+    throw new TypeError(`${label} must be an array-like object`);
+  }
+
+  const length = (value as { length?: unknown }).length;
+  if (typeof length !== 'number'
+    || !Number.isSafeInteger(length) || length < 0 || length > MAX_PROFILE_LENGTH) {
+    throw new RangeError(
+      `${label} length must be a safe integer between 0 and ${MAX_PROFILE_LENGTH}`
+    );
+  }
+  return length;
+}
+
+/**
+ * Validate one state and return its narrowed value.
+ *
+ * When `stateCount` is supplied, states outside that alphabet are rejected;
+ * leaving it out validates the complete four-state range.
+ *
+ * @param {number} state
+ * @param {2|4} [stateCount]
+ * @returns {HeightState}
+ */
+export function validateHeightState(
+  state: number,
+  stateCount?: HeightStateCount,
+): HeightState {
+  if (stateCount !== undefined) validateStateCount(stateCount);
+  if (!Number.isSafeInteger(state)) {
+    throw new RangeError(`Height state must be a finite safe integer, got ${String(state)}`);
+  }
+
+  const maximum = stateCount === 2 ? 1 : 3;
+  if (state < 0 || state > maximum) {
+    throw new RangeError(
+      `Height state must be between 0 and ${maximum} for ${stateCount ?? 4} states, got ${state}`
+    );
+  }
+  return state as HeightState;
+}
+
+function copyProfile(profile: HeightCodedBar): HeightCodedBar {
+  return { top: profile.top, bottom: profile.bottom };
+}
+
+/**
+ * Return the normalized top and bottom edges for one state.
+ *
+ * State numbering is intentionally generic: 0 is tracker, 1 is ascender,
+ * 2 is descender and 3 is full for the four-state alphabet. The two-state
+ * alphabet exposes tracker (0) and full (1), so it is a strict subset of the
+ * four-state geometry and does not prescribe a postal format's semantics.
+ *
+ * @param {number} state
+ * @param {2|4} stateCount
+ * @returns {HeightCodedBar}
+ */
+export function barHeightProfile(
+  state: number,
+  stateCount: HeightStateCount,
+): HeightCodedBar {
+  const count = validateStateCount(stateCount);
+  const checked = validateHeightState(state, count);
+
+  if (count === 2) {
+    return copyProfile(checked === 0 ? TRACKER_PROFILE : FULL_PROFILE);
+  }
+
+  switch (checked) {
+    case 0: return copyProfile(TRACKER_PROFILE);
+    case 1: return copyProfile(ASCENDER_PROFILE);
+    case 2: return copyProfile(DESCENDER_PROFILE);
+    default: return copyProfile(FULL_PROFILE);
+  }
+}
+
+/**
+ * Convert a state sequence to normalized top/bottom bar profiles.
+ *
+ * The returned array and every profile in it are newly allocated, so callers
+ * can safely adjust rendering coordinates without changing shared constants.
+ *
+ * @param {ArrayLike<number>} states
+ * @param {2|4} stateCount
+ * @returns {HeightCodedBar[]}
+ */
+export function encodeHeightProfile(
+  states: ArrayLike<number>,
+  stateCount: HeightStateCount,
+): HeightCodedBar[] {
+  const count = validateStateCount(stateCount);
+  const length = validateProfileLength(states, 'Height states');
+  const profile = new Array<HeightCodedBar>(length);
+  for (let index = 0; index < length; index++) {
+    profile[index] = barHeightProfile(states[index], count);
+  }
+  return profile;
+}
+
+function decodeBar(profile: unknown, stateCount: HeightStateCount, index: number): HeightState {
+  if (profile === null || typeof profile !== 'object' || Array.isArray(profile)) {
+    throw new TypeError(`Height profile at index ${index} must be an object`);
+  }
+
+  const { top, bottom } = profile as Partial<HeightCodedBar>;
+  if (typeof top !== 'number' || typeof bottom !== 'number'
+    || !Number.isFinite(top) || !Number.isFinite(bottom)) {
+    throw new RangeError(`Height profile at index ${index} must contain finite edges`);
+  }
+  if (top < 0 || top > 1 || bottom < 0 || bottom > 1 || top >= bottom) {
+    throw new RangeError(
+      `Height profile at index ${index} must satisfy 0 <= top < bottom <= 1`
+    );
+  }
+
+  const maximum = stateCount === 2 ? 1 : 3;
+  for (let state = 0; state <= maximum; state++) {
+    const expected = barHeightProfile(state, stateCount);
+    if (top === expected.top && bottom === expected.bottom) {
+      return state as HeightState;
+    }
+  }
+
+  throw new RangeError(
+    `Height profile at index ${index} does not match a canonical ${stateCount}-state profile`
+  );
+}
+
+/**
+ * Convert normalized top/bottom bar profiles back to their states.
+ *
+ * Decoding is deliberately exact: a profile must match one of the canonical
+ * normalized pairs for the selected alphabet. Raster or measurement code can
+ * quantize its observations before calling this helper; accepting arbitrary
+ * in-range pairs here would turn malformed bars into valid states.
+ *
+ * @param {ArrayLike<HeightCodedBar>} profile
+ * @param {2|4} stateCount
+ * @returns {HeightState[]}
+ */
+export function decodeHeightProfile(
+  profile: ArrayLike<HeightCodedBar>,
+  stateCount: HeightStateCount,
+): HeightState[] {
+  const count = validateStateCount(stateCount);
+  const length = validateProfileLength(profile, 'Height profile');
+  const states = new Array<HeightState>(length);
+  for (let index = 0; index < length; index++) {
+    states[index] = decodeBar(profile[index], count, index);
+  }
+  return states;
+}