hcc2d-encoder 0.0.0-stage → 0.9.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.9.0-rc.1
+
+- added a pure JavaScript HCC2D reference encoder for Node.js
+- aligned encoding behavior with the public C and Python reference encoders 0.9.0
+- added standard QR, HCC2D4, and HCC2D8 output
+- added raw and HCC2DF payload formats for text and files
+- aligned defaults, validation limits, palettes, help, copyright, license,
+  disclaimer, and specification references with the other official encoders
+- added an importable ES module API and the `hcc2d-encoder` console command
+- added regression tests for known QR, HCC2D4, and HCC2D8 outputs
+- added 842 C/Python/JavaScript parity cases covering every forced version,
+  binary capacity boundaries, automatic selection, multi-block symbols, and
+  decompressed PNG output, plus 12 exact overflow-rejection checks
+- added GitHub Actions CI for supported Node.js 22 and 24 LTS releases and
+  Node.js 26 Current, with npm 12.2.1 for release automation
+- added npm package smoke testing and an OIDC Trusted Publishing workflow with
+  immutable action and reference-encoder revisions

package/LICENSE

@@ -0,0 +1,186 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of
+such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent, as a
+whole, an original work of authorship. For the purposes of this License,
+Derivative Works shall not include works that remain separable from, or
+merely link (or bind by name) to the interfaces of, the Work and Derivative
+Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the
+purposes of this definition, "submitted" means any form of electronic, verbal,
+or written communication sent to the Licensor or its representatives,
+including but not limited to communication on electronic mailing lists, source
+code control systems, and issue tracking systems that are managed by, or on
+behalf of, the Licensor for the purpose of discussing and improving the Work,
+but excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed by
+their Contribution(s) alone or by combination of their Contribution(s) with
+the Work to which such Contribution(s) was submitted. If You institute patent
+litigation against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent
+licenses granted to You under this License for that Work shall terminate as of
+the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from
+the Source form of the Work, excluding those notices that do not pertain to
+any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution,
+then any Derivative Works that You distribute must include a readable copy of
+the attribution notices contained within such NOTICE file, excluding those
+notices that do not pertain to any part of the Derivative Works, in at least
+one of the following places: within a NOTICE text file distributed as part of
+the Derivative Works; within the Source form or documentation, if provided
+along with the Derivative Works; or, within a display generated by the
+Derivative Works, if and wherever such third-party notices normally appear.
+The contents of the NOTICE file are for informational purposes only and do not
+modify the License. You may add Your own attribution notices within Derivative
+Works that You distribute, alongside or as an addendum to the NOTICE text from
+the Work, provided that such additional attribution notices cannot be
+construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a
+whole, provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein
+shall supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as
+required for reasonable and customary use in describing the origin of the Work
+and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability
+to use the Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all other
+commercial damages or losses), even if such Contributor has been advised of
+the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+or Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification
+within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,312 @@
-# Temporary Holding Version
+# HCC2D JavaScript Encoder 0.9.0-rc.1
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/marco-querini/hcc2d-cli-javascript-encoder/actions/workflows/ci.yml/badge.svg)](https://github.com/marco-querini/hcc2d-cli-javascript-encoder/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/hcc2d-encoder.svg)](https://www.npmjs.com/package/hcc2d-encoder)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+Written by Marco Querini.
+
+Pure JavaScript reference encoder for standard QR Code, HCC2D4, and HCC2D8.
+It provides both an importable ES module API and the `hcc2d-encoder` command.
+The encoding algorithm is an independent JavaScript implementation: it does
+not invoke the C or Python encoders and does not use WebAssembly or native npm
+add-ons.
+
+## Official links
+
+- HCC2D website: <https://hcc2d.com/en/>
+- HCC2D Code Specification 0.9.0: <https://doi.org/10.5281/zenodo.22206528>
+- HCC2D API: <https://hcc2d.com/en/api>
+- Source: <https://github.com/marco-querini/hcc2d-cli-javascript-encoder>
+- npm package: <https://www.npmjs.com/package/hcc2d-encoder>
+- C reference encoder: <https://github.com/marco-querini/hcc2d-cli-c-encoder>
+- Python reference encoder: <https://github.com/marco-querini/hcc2d-cli-python-encoder>
+- Client-side WebAssembly encoder: <https://marco-querini.github.io/hcc2d-web-encoder/>
+- HCC2D Decoder:
+  - Google Play: <https://play.google.com/store/apps/details?id=com.hcc2d.decoder>
+  - Huawei AppGallery: <https://appgallery.cloud.huawei.com/marketshare/app/C117478101>
+  - App Store: <https://apps.apple.com/app/id6762202762>
+- HCC2D Encoder on the Mac App Store: <https://apps.apple.com/app/id6767833986>
+
+## Supported features
+
+- standard black/white QR Code
+- HCC2D4 with 4 colours and 2 bits per data module
+- HCC2D8 with 8 colours and 3 bits per data module
+- error-correction levels `L`, `M`, `Q`, and `H`
+- versions `1..40`, or automatic selection
+- screen-oriented Model 1 and print-oriented Model 2 palettes
+- custom palettes through the JavaScript API, with normative black/white anchors
+- raw payloads and optional HCC2DF file wrapping
+- indexed PNG output
+- importable modern ECMAScript module (ESM) API
+- command-line interface for text and binary files
+- no npm runtime dependencies
+
+HCC2D16 is not included because it is not part of HCC2D Code Specification
+0.9.0 or the public C and Python reference encoders 0.9.0.
+
+## Requirements
+
+- Node.js 22 or later
+- npm 10 or later for installation and package management
+
+Continuous integration covers the supported Node.js 22 and 24 LTS lines and
+Node.js 26 Current. Development and release automation use npm 12.2.1.
+
+The package uses only Node.js standard-library modules. There are no runtime
+dependencies, native npm add-ons, post-install scripts, downloads, or
+telemetry.
+
+## Installation
+
+Install the release candidate into a project:
+
+```bash
+npm install hcc2d-encoder@next
+```
+
+Install the CLI globally:
+
+```bash
+npm install --global hcc2d-encoder@next
+hcc2d-encoder --help
+```
+
+Run the CLI without a permanent global installation:
+
+```bash
+npx hcc2d-encoder@next --help
+```
+
+For local development, install from a clone:
+
+```bash
+npm install
+npm link
+hcc2d-encoder --help
+```
+
+## JavaScript API
+
+### Generate an HCC2D4 PNG
+
+```javascript
+import { encodeHcc2d, writePng } from "hcc2d-encoder";
+
+const payload = new TextEncoder().encode("hello");
+const symbol = encodeHcc2d(payload, {
+  mode: "hcc2d4",
+  ecLevel: "Q",
+  version: 0,
+  scale: 12,
+  quietZone: 4,
+});
+
+writePng("hello.png", symbol);
+```
+
+### Generate an HCC2D8 PNG in memory
+
+```javascript
+import { PALETTE_8_MODEL2, encodeHcc2d } from "hcc2d-encoder";
+
+const symbol = encodeHcc2d(Buffer.from("Batch=2026-06-16;Unit=004271"), {
+  mode: "hcc2d8",
+  palette: PALETTE_8_MODEL2,
+});
+
+const png = symbol.toPng(); // Node.js Buffer
+```
+
+### Generate a standard QR Code
+
+```javascript
+import { encodeQr } from "hcc2d-encoder";
+
+const symbol = encodeQr(Buffer.from("https://hcc2d.com/"), {
+  ecLevel: "Q",
+});
+const png = symbol.toPng();
+```
+
+### Wrap a file in HCC2DF
+
+```javascript
+import { readFileSync } from "node:fs";
+import { buildHcc2dfPayload, encodeHcc2d } from "hcc2d-encoder";
+
+const wrapped = buildHcc2dfPayload("report.pdf", readFileSync("report.pdf"));
+const symbol = encodeHcc2d(wrapped, { mode: "hcc2d8", ecLevel: "L" });
+```
+
+The encoding functions accept `Buffer`, `Uint8Array`, or `ArrayBuffer`. They
+return an `EncodedSymbol` with these public properties:
+
+- `mode`
+- `ecLevel`
+- `version`
+- `innerDimension`
+- `fullDimension`
+- `maskPattern`
+- `palette`
+- `pixels`
+- `width`
+- `height`
+
+Call `symbol.toPng()` to obtain PNG bytes or `writePng(path, symbol)` to write
+the PNG directly.
+
+## Command-line usage
+
+Show the complete help and legal notice:
+
+```bash
+hcc2d-encoder --help
+```
+
+Generate a standard QR Code containing raw UTF-8 text:
+
+```bash
+hcc2d-encoder --text "https://hcc2d.com/spec" \
+  --mode qr --file-format raw qr-spec-url.png
+```
+
+Generate an HCC2D4 symbol containing raw text bytes:
+
+```bash
+hcc2d-encoder --text "Batch=2026-06-16;Line=A3;Unit=004271" \
+  --mode hcc2d4 --file-format raw hcc2d4-label.png
+```
+
+Generate an HCC2D8 symbol carrying a file in an HCC2DF container:
+
+```bash
+hcc2d-encoder --input-file report.pdf --mode hcc2d8 \
+  --file-format hcc2df --ec-level L hcc2d8-report.png
+```
+
+Defaults are HCC2D4, EC level Q, automatic version selection, 12 pixels per
+module, a 4-module quiet zone, Model 1 palette, and HCC2DF wrapping.
+
+### Raw versus HCC2DF
+
+Use `raw` when the bytes are already the complete payload and filename
+metadata is unnecessary. This minimizes overhead.
+
+Use `hcc2df` for file-oriented payloads. It preserves the basename and applies
+zlib compression only when the content is at least 128 bytes and the compressed
+representation is strictly smaller than 90% of the original size.
+
+## Compatibility and validation
+
+The JavaScript implementation is validated against both public reference
+encoders. The forced-version matrix covers:
+
+- all versions from 1 through 40
+- QR, HCC2D4, and HCC2D8
+- EC levels L, M, Q, and H
+- Model 1 and Model 2 where applicable
+- 800 structural combinations using a minimal payload
+
+For every case, the comparison verifies identical PNG dimensions, palette
+entries, and decompressed indexed pixels across JavaScript, C, and Python.
+Compressed IDAT bytes are intentionally not required to match because different
+zlib versions can produce different lossless streams for identical pixels.
+
+An additional 42 binary-payload cases verify automatic version selection,
+multi-block symbols, and the exact capacity boundary at representative
+versions 1, 10, 27, and 40. Twelve corresponding overflow cases verify that
+all three encoders reject the first byte beyond the supported capacity. The
+complete reference suite therefore compares 842 generated PNGs and 12 exact
+rejection boundaries.
+
+Run the normal test suite:
+
+```bash
+npm test
+```
+
+When sibling clones of the C and Python repositories are available, run the
+full cross-implementation comparison:
+
+```bash
+npm run test:reference
+```
+
+Override their locations when required:
+
+```bash
+HCC2D_C_REFERENCE_DIR=/path/to/hcc2d-cli-c-encoder \
+HCC2D_PYTHON_REFERENCE_DIR=/path/to/hcc2d-cli-python-encoder \
+npm run test:reference
+```
+
+GitHub Actions tests Node.js 22, 24, and 26. A separate packaging job
+builds the exact npm tarball, installs it into a clean project, invokes its
+published CLI entry point, and verifies a generated PNG.
+
+## Architecture and independence
+
+The JavaScript implementation independently performs:
+
+1. byte-mode framing and capacity selection;
+2. Reed-Solomon error-correction generation and interleaving;
+3. QR-compatible function-pattern and data-module placement;
+4. mask selection;
+5. HCC2D plane construction and Color Palette Pattern rendering;
+6. indexed raster generation and PNG serialization;
+7. optional HCC2DF filename wrapping and compression.
+
+The package does not execute the C or Python implementations. Those projects
+are used only by the optional development-time reference comparison.
+
+The current npm package targets Node.js. For a fully client-side browser build,
+use the official HCC2D WebAssembly encoder linked above; it runs locally in a
+Web Worker and does not upload payloads.
+
+## Building and inspecting the npm package
+
+```bash
+npm ci
+npm run check
+npm pack
+npm install --global ./hcc2d-encoder-0.9.0-rc.1.tgz
+```
+
+`npm pack --dry-run` shows every file that would be published. The `files`
+allow-list in `package.json` prevents tests, workflows, local output, and
+development scripts from entering the production package.
+
+## Security and privacy
+
+Encoding is local. The package contains no network requests, analytics,
+advertising, dynamic code downloads, installation hooks, or credential access.
+Input data is read only when explicitly supplied through the API or CLI.
+
+See [SECURITY.md](SECURITY.md) for responsible vulnerability reporting.
+
+## Publication
+
+npm releases are immutable. Production publication is performed from a tagged
+GitHub release using npm Trusted Publishing with short-lived OIDC credentials.
+No long-lived npm token is stored in the repository. See
+[PUBLISHING.md](PUBLISHING.md) for the complete release checklist.
+
+## License and warranty
+
+Copyright 2010-2026 Marco Querini.
+
+SPDX-License-Identifier: Apache-2.0. See [LICENSE](LICENSE).
+
+This software is provided "as is", without warranties or conditions of any
+kind. Use is entirely at your own risk. The author assumes no responsibility
+for unreadable or non-decodable codes, failed scans, data loss, or other
+consequences arising from its use.
+
+## Notice
+
+The views expressed in connection with the HCC2D Code Specification, HCC2D
+applications, and HCC2D source code are solely those of the author and do not
+necessarily reflect the official position of any institution, organization,
+or employer with which the author is or has been affiliated.

package/bin/hcc2d-encoder.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+process.exitCode = main();

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "hcc2d-encoder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.0-rc.1",
+  "description": "Pure JavaScript reference encoder for QR, HCC2D4, and HCC2D8 symbols",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "hcc2d-encoder": "bin/hcc2d-encoder.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "test:reference": "node scripts/compare-reference.mjs",
+    "check": "npm test && npm pack --dry-run",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10"
+  },
+  "packageManager": "npm@12.2.1",
+  "keywords": [
+    "hcc2d",
+    "qr-code",
+    "barcode",
+    "encoder",
+    "color-barcode"
+  ],
+  "author": "Marco Querini",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marco-querini/hcc2d-cli-javascript-encoder.git"
+  },
+  "bugs": {
+    "url": "https://github.com/marco-querini/hcc2d-cli-javascript-encoder/issues"
+  },
+  "homepage": "https://hcc2d.com/en/",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}