specqr 1.0.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 1.0.0-rc.1 - 2026-05-17
+
+SpecQR の v1 target は、dependency-free な JavaScript QR Code Model 2 generator として、実用上安全な通常 QR generation に集中します。
+
+### 含まれるもの
+
+- QR Code Model 2 versions 1 through 40。
+- Error correction levels L, M, Q, H。
+- Numeric、alphanumeric、UTF-8 byte、QR Kanji、binary、ECI、manual segments、automatic mixed segmentation。
+- GS1 QR Code / FNC1 first position と、対応 AI に限定した human-readable parser / element-string helper。
+- Matrix、SVG、SVG Data URL、PNG、PNG Data URL、browser canvas、Node PNG、browser Blob/ImageData/Object URL output。
+- Version / mask selection、capacity、codeword counts、quiet zone、color contrast、scan risk、print sizing の diagnostics。
+- Golden conformance fixtures、decoder validation、jsQR independent decoder validation、release-candidate smoke tests、package smoke tests。
+
+### 意図的な制限
+
+- FNC1 second position は未対応。
+- Full GS1 AI catalog、industry-specific GS1 validation、check-digit validation は未対応。
+- Structured Append、Micro QR、rMQR、Frame QR、SQRC、logo overlay、styled modules、playground は未対応。
+- Package は ESM-first。CommonJS と minified browser build は、将来 build pipeline を導入するまで保留。
+
+### Publish Checklist
+
+- `npm test`, `npm run verify:decode`, `npm run verify:decode:jsqr`, `npm run verify:decode:optional`, `npm pack --dry-run` を実行する。
+- publish 前に `npm publish --dry-run` を実行する。
+- RC は `latest` ではなく、`next` などの npm dist tag で公開する。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpecQR contributors
+
+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.

package/README.md

@@ -0,0 +1,254 @@
+# SpecQR
+
+SpecQR is a dependency-free JavaScript QR Code Model 2 generator. It focuses on standards-conscious QR generation with SVG, PNG, matrix, diagnostics, Kanji, ECI, and GS1/FNC1 support.
+
+Repository: https://github.com/SpecQR/SpecQR
+
+SpecQR は、通常の QR Code Model 2 を JavaScript だけで生成するためのライブラリです。実用上「生成はできるが読めない」「仕様端で壊れる」「環境で挙動が変わる」問題を避けるため、v1 では対応範囲を明確に絞り、テストとデコード検証を厚めに置いています。
+
+## インストール
+
+```sh
+npm install specqr@1.0.0-rc.1
+```
+
+## v1 RC の対応範囲
+
+- QR Code Model 2
+- Version 1 から 40
+- 誤り訂正レベル L, M, Q, H
+- Numeric / alphanumeric / UTF-8 byte mode
+- Shift_JIS ベースの QR Kanji mode
+- 自動 mixed-segment optimization
+- binary input と manual segment input
+- GS1 QR Code / FNC1 first position
+- 対応 AI に限定した GS1 human-readable parser / element string helper
+- `matrix`, `svg`, Data URL, PNG, canvas output
+- Node PNG helper と browser Blob/ImageData/Object URL helper
+- capacity、mask/version selection、contrast、quiet zone、print warning を含む diagnostics
+
+Micro QR、rMQR、logo overlay、styled modules、FNC1 second position、Structured Append は v1 RC の対象外です。
+
+## 基本的な使い方
+
+```js
+import { QRCode } from "specqr";
+
+const svg = QRCode.generate("https://example.com", {
+  errorCorrectionLevel: "M",
+  output: "svg"
+});
+```
+
+Data URL や PNG bytes も返せます。
+
+```js
+const dataUrl = QRCode.generate("https://example.com", {
+  output: "png-data-url"
+});
+
+const pngBytes = QRCode.generate("https://example.com", {
+  output: "png"
+});
+```
+
+ブラウザの canvas に直接描画できます。
+
+```js
+const canvas = document.querySelector("canvas");
+
+QRCode.drawToCanvas(canvas, "https://example.com", {
+  scale: 8,
+  margin: 4
+});
+```
+
+matrix と diagnostics を取得する例です。
+
+```js
+const result = QRCode.generate("hello", {
+  output: "matrix",
+  diagnostics: true
+});
+
+console.log(result.matrix);
+console.log(result.diagnostics);
+```
+
+## セグメント最適化
+
+`mode: "auto"` では、入力に応じて numeric、alphanumeric、kanji、byte のセグメントを自動で選びます。
+
+```js
+QRCode.generate("ORDER-1234567890-こんにちは", {
+  mode: "auto",
+  optimizeSegments: true
+});
+```
+
+QR Kanji mode で表現できる日本語は、自動的に compact な Kanji segment になります。
+
+```js
+const result = QRCode.generate("こんにちは漢字", {
+  output: "matrix",
+  diagnostics: true
+});
+
+console.log(result.diagnostics.mode); // "kanji"
+```
+
+同じ Version に収まる範囲で誤り訂正レベルを上げたい場合は `boostErrorCorrection` を使います。
+
+```js
+QRCode.generate("HELLO", {
+  errorCorrectionLevel: "L",
+  boostErrorCorrection: true
+});
+```
+
+UTF-8 byte data であることを ECI で明示する例です。
+
+```js
+QRCode.generate("こんにちは", {
+  eci: true
+});
+```
+
+## GS1 QR Code / FNC1 first position
+
+GS1 QR Code を生成する場合は、human-readable GS1 text を parse して raw GS1 element string に変換し、`gs1: true` を指定します。
+
+```js
+import { QRCode, createGs1ElementString, parseGs1HumanReadable } from "specqr";
+
+const elements = parseGs1HumanReadable("(01)04912345678904(10)ABC123(17)251231");
+const data = createGs1ElementString(elements);
+
+const svg = QRCode.generate(data, {
+  gs1: true,
+  output: "svg"
+});
+```
+
+`parseGs1HumanReadable()` は対応 AI の parentheses 表記を `{ ai, value }[]` に変換します。`createGs1ElementString()` は値を検証し、可変長 AI の後に別の AI が続く場合だけ ASCII GS separator (`"\x1D"`) を挿入します。AI values は先頭ゼロを保持するため string で渡してください。全 GS1 AI catalog、業界別 validation、check digit validation は v1 RC の対象外です。
+
+## バイナリ入力
+
+byte-perfect な payload を扱う場合は `Uint8Array`、`ArrayBuffer`、`ArrayBufferView`、または byte array を渡せます。
+
+```js
+const matrix = QRCode.generate(new Uint8Array([0x00, 0x01, 0x02, 0xFF]), {
+  output: "matrix"
+});
+
+QRCode.generate([0x41, 0x42, 0x43], {
+  output: "png"
+});
+```
+
+## Manual segments
+
+QR mode を利用者側で制御したい場合は `generateSegments()` を使います。
+
+```js
+const svg = QRCode.generateSegments([
+  { mode: "alphanumeric", data: "ORDER-" },
+  { mode: "numeric", data: "1234567890" },
+  { mode: "kanji", data: "こんにちは" }
+], {
+  output: "svg"
+});
+```
+
+## Diagnostics
+
+`diagnostics: true` を指定すると、選ばれた Version、mask、capacity、warnings などを取得できます。
+
+```js
+const result = QRCode.generate("HELLO", {
+  output: "png",
+  diagnostics: true,
+  margin: 2,
+  foreground: "#777777",
+  background: "#888888",
+  printDpi: 600
+});
+
+console.log(result.diagnostics.warnings);
+```
+
+## Node helpers
+
+Node 専用 helper は `specqr/node` から import します。
+
+```js
+import { writePngFile, toPngBuffer } from "specqr/node";
+
+await writePngFile("qr.png", "https://example.com");
+const buffer = toPngBuffer("https://example.com");
+```
+
+## Browser helpers
+
+ブラウザ向け helper は `specqr/browser` から import します。
+
+```js
+import { toBlob, toImageData, toObjectURL } from "specqr/browser";
+
+const blob = toBlob("https://example.com");
+const imageData = toImageData("https://example.com");
+const url = toObjectURL("https://example.com");
+```
+
+## Errors
+
+エラーは安定した class と `code` field を持ちます。
+
+```js
+import { DataTooLongError, QRCode } from "specqr";
+
+try {
+  QRCode.generate("x".repeat(100), { version: 1 });
+} catch (error) {
+  if (error instanceof DataTooLongError) {
+    console.error(error.code);
+  }
+}
+```
+
+## 開発と検証
+
+```sh
+npm test
+```
+
+`npm test` には、固定 Version / 誤り訂正 / mask の golden conformance fixture が含まれます。matrix rows、codewords、diagnostics、format bits、version bits、remainder bits の代表ケースを固定しています。
+
+QR 構築ロジックの意図した変更を受け入れる場合だけ、snapshot を更新します。
+
+```sh
+npm run fixtures:golden
+npm test
+```
+
+macOS では Vision を使った fixture decode validation も実行できます。
+
+```sh
+npm run verify:decode
+```
+
+ローカルに利用可能な decoder がある場合は optional multi-decoder validation も使えます。
+
+```sh
+npm run verify:decode:optional
+```
+
+この optional script は `jsqr`、`zbarimg`、ZXing 系 CLI を検出し、未導入の decoder は skip します。
+
+portable な独立 decoder release gate として、jsQR-backed check も用意しています。
+
+```sh
+npm run verify:decode:jsqr
+```
+
+`jsqr` は devDependency のみです。SpecQR の runtime package は dependency-free のままです。

package/docs/api.md

@@ -0,0 +1,226 @@
+# API
+
+この文書は SpecQR `1.0.0-rc.1` の公開 API を説明します。API 名、option 名、型名、error class 名は JavaScript/TypeScript から利用する識別子なので英語のままです。
+
+## Core
+
+### `QRCode.generate(input, options)`
+
+JavaScript string、byte array、`Uint8Array`、`ArrayBuffer`、`ArrayBufferView` から QR Code を生成します。
+
+```js
+import { QRCode } from "specqr";
+
+const svg = QRCode.generate("https://example.com", {
+  errorCorrectionLevel: "M",
+  version: "auto",
+  minVersion: 1,
+  maxVersion: 40,
+  maskPattern: "auto",
+  mode: "auto",
+  encoding: "utf-8",
+  optimizeSegments: true,
+  margin: 4,
+  scale: 8,
+  foreground: "#000000",
+  background: "#ffffff",
+  output: "svg",
+  boostErrorCorrection: false,
+  eci: false,
+  gs1: false,
+  diagnostics: false,
+  printDpi: null
+});
+```
+
+### `QRCode.generateSegments(segments, options)`
+
+呼び出し側が明示した segment から QR Code を生成します。対応する segment mode は `fnc1`, `eci`, `numeric`, `alphanumeric`, `byte`, `kanji` です。
+
+```js
+QRCode.generateSegments([
+  { mode: "alphanumeric", data: "ORDER-" },
+  { mode: "numeric", data: "1234567890" },
+  { mode: "kanji", data: "漢字" },
+  { mode: "byte", data: new Uint8Array([0x41, 0x42, 0x43]) }
+]);
+```
+
+### `QRCode.drawToCanvas(target, input, options)`
+
+ブラウザの canvas element、または 2D rendering context に直接描画します。
+
+```js
+const canvas = document.querySelector("canvas");
+
+QRCode.drawToCanvas(canvas, "https://example.com", {
+  scale: 8,
+  margin: 4
+});
+```
+
+## Options
+
+- `errorCorrectionLevel`: `"L" | "M" | "Q" | "H"`。default は `"M"`。
+- `version`: `1..40 | "auto"`。default は `"auto"`。
+- `minVersion`: `1..40`。default は `1`。
+- `maxVersion`: `1..40`。default は `40`。
+- `maskPattern`: `0..7 | "auto"`。default は `"auto"`。
+- `mode`: `"auto" | "numeric" | "alphanumeric" | "byte" | "kanji"`。`"auto"` は効率のよい QR segment を自動選択します。
+- `encoding`: 現在は byte-mode string input 向けの `"utf-8"` のみ。
+- `optimizeSegments`: `mode` が `"auto"` のとき、numeric、alphanumeric、kanji、byte を混在 segment に分割して bit length を減らします。default は `true`。
+- `margin`: quiet zone の module 数。default は `4`。
+- `scale`: SVG/PNG/canvas/ImageData output での 1 module の pixel size。default は `8`。
+- `foreground`: dark module color。default は `"#000000"`。
+- `background`: light module color。default は `"#ffffff"`。
+- `output`: `"matrix" | "svg" | "svg-data-url" | "png" | "png-data-url"`。default は `"svg"`。
+- `boostErrorCorrection`: `true` の場合、選択 Version を増やさずに収まる範囲で error correction level を上げます。default は `false`。
+- `eci`: `false | true | number`。default は `false`。`true` は UTF-8 ECI assignment number `26` を挿入し、auto-selected non-ASCII text を byte mode に保ちます。
+- `gs1`: boolean。default は `false`。`true` の場合、GS1 QR Code 用に QR FNC1 first position (`0101`) を先頭に挿入します。この実装では ECI と併用できません。
+- `diagnostics`: `true` の場合、生成詳細と warnings を返します。
+- `printDpi`: print-size diagnostics のための optional DPI。生成結果そのものには影響しません。
+
+## GS1 / FNC1 First Position
+
+`gs1: true` は、入力が raw GS1 element string である場合に使います。QR Code の FNC1 first position mode indicator を先頭に挿入します。
+
+```js
+import { QRCode, createGs1ElementString, parseGs1HumanReadable } from "specqr";
+
+const elements = parseGs1HumanReadable("(01)04912345678904(10)ABC123(17)251231");
+const data = createGs1ElementString(elements);
+
+const svg = QRCode.generate(data, {
+  gs1: true,
+  output: "svg"
+});
+```
+
+manual segment でも FNC1 first position を明示できます。
+
+```js
+QRCode.generateSegments([
+  { mode: "fnc1" },
+  { mode: "numeric", data: "0104912345678904" },
+  { mode: "alphanumeric", data: "10ABC123" }
+]);
+```
+
+### GS1 Helpers
+
+- `parseGs1HumanReadable(input)`: `(01)04912345678904(10)ABC123(17)251231` のような parentheses-based input を `{ ai, value }[]` に変換します。
+- `createGs1ElementString(elements)`: 対応 AI の `{ ai, value }` string entries を検証し、QR input として使う raw GS1 element string を返します。leading zero を保持するため、AI values は string で渡す必要があります。
+- `GS1_FNC1_SEPARATOR`: 可変長 AI の後に別の element が続く場合に挿入される ASCII GS separator `"\x1D"` です。
+
+helper が対応する代表 AI は次の範囲です。
+
+- fixed length: `00`, `01`, `02`, `11`, `12`, `13`, `15`, `16`, `17`, `20`, `410` through `415`, `3100` through `3105`, `3200` through `3205`
+- variable length: `10`, `21`, `22`, `30`, `37`, `240`, `241`, `400`, `420`, `91` through `99`
+
+validation は、対応 AI format、fixed/max length、numeric-only AI、printable ASCII text values、raw value 内の separator/parentheses rejection を対象にします。可変長 AI の後に別の element が続く場合は `"\x1D"` を挿入し、最後の可変長 AI は separator なしで終端します。
+
+全 GS1 AI catalog、業界別 AI rule、check digit validation、FNC1 second position は v1 RC の対象外です。
+
+## Return Values
+
+`output` が `"svg"` の場合、`generate()` は SVG string を返します。
+
+`output` が `"matrix"` の場合、二次元 boolean matrix を返します。
+
+`output` が `"svg-data-url"` または `"png-data-url"` の場合、Data URL string を返します。
+
+`output` が `"png"` の場合、PNG `Uint8Array` を返します。
+
+PNG と ImageData output は `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `"black"`, `"white"`, `"transparent"` colors に対応します。
+
+`diagnostics` が true の場合は次の形を返します。
+
+```js
+{
+  matrix,
+  svg,
+  diagnostics: {
+    version,
+    size,
+    errorCorrectionLevel,
+    requestedErrorCorrectionLevel,
+    boostedErrorCorrection,
+    versionSelection,
+    versionSelectionReason,
+    maskPattern,
+    maskPenalty,
+    maskPenalties,
+    maskSelectionReason,
+    mode,
+    eciAssignmentNumber,
+    fnc1,
+    gs1,
+    segments,
+    dataBitLength,
+    capacityBits,
+    remainingBits,
+    capacityUtilization,
+    inputBytes,
+    dataCodewords,
+    errorCorrectionCodewords,
+    totalCodewords,
+    quietZone,
+    colors,
+    print,
+    warnings
+  }
+}
+```
+
+## Node Helpers
+
+`specqr/node` subpath は Node-only の file / Buffer helper を core entrypoint から分離します。
+
+```js
+import { toPngBuffer, writePngFile } from "specqr/node";
+
+const buffer = toPngBuffer("https://example.com");
+await writePngFile("qr.png", "https://example.com");
+```
+
+利用可能な helper:
+
+- `toPngBuffer(input, options)`
+- `toPngBufferFromSegments(segments, options)`
+- `writePngFile(path, input, options)`
+- `writePngFileFromSegments(path, segments, options)`
+
+## Browser Helpers
+
+`specqr/browser` subpath は browser convenience helper を提供します。
+
+```js
+import { toBlob, toImageData, toObjectURL } from "specqr/browser";
+
+const blob = toBlob("https://example.com");
+const imageData = toImageData("https://example.com");
+const objectUrl = toObjectURL("https://example.com");
+```
+
+利用可能な helper:
+
+- `toBlob(input, options)`
+- `toBlobFromSegments(segments, options)`
+- `toObjectURL(input, options)`
+- `toObjectURLFromSegments(segments, options)`
+- `toImageData(input, options)`
+- `toImageDataFromSegments(segments, options)`
+
+## Errors
+
+SpecQR は安定した error class と `code` field を export します。
+
+- `DataTooLongError`
+- `InvalidInputError`
+- `InvalidVersionError`
+- `InvalidModeError`
+- `InvalidColorError`
+- `InvalidEciError`
+- `InvalidGs1Error`
+- `InvalidOutputError`
+- `InvalidCanvasTargetError`

package/docs/spec-scope.md

@@ -0,0 +1,75 @@
+# 仕様対応範囲
+
+## Target
+
+SpecQR `1.0.0-rc.1` は、実務で使う通常の QR Code Model 2 generation を対象にします。v1 RC では「通常 QR Code を安定して生成する」ことを優先し、別系統の QR family や装飾機能は core に混ぜません。
+
+## 実装済み範囲
+
+- QR Code Model 2 のみ
+- Version 1 から 40
+- Error correction levels L, M, Q, H
+- JavaScript string input
+- byte array、`Uint8Array`、`ArrayBuffer`、`ArrayBufferView` binary input
+- Numeric mode
+- Alphanumeric mode
+- UTF-8 byte mode
+- QR Kanji ranges で表現できる文字向けの Shift_JIS-based QR Kanji mode
+- `fnc1`, `numeric`, `alphanumeric`, `byte`, `kanji`, `eci` の manual segment API
+- Automatic mixed-segment optimization
+- UTF-8 と explicit assignment number 向けの optional ECI metadata
+- GS1 QR Code / FNC1 first position mode
+- 代表的な fixed-length / variable-length AI 向けの GS1 element string helper と human-readable parser
+- 選択 Version を増やさない optional error correction boosting
+- Automatic version selection
+- Automatic mask selection
+- Matrix output
+- SVG output
+- SVG Data URL output
+- PNG output
+- PNG Data URL output
+- Browser canvas drawing
+- Node PNG buffer/file helpers
+- Browser Blob/ImageData/Object URL helpers
+- quiet zone、contrast、capacity、mask/version selection、scan risk、print DPI の diagnostics / warnings
+
+## Compatibility Notes
+
+Kanji mode は、platform の `TextDecoder("shift_jis")` 実装を使って Unicode character を QR-compatible Shift_JIS double-byte value に対応付けます。runtime が Shift_JIS `TextDecoder` を持たない場合、explicit Kanji mode は input を reject し、auto mode は byte mode に fallback します。
+
+`eci: true` は byte-mode text が UTF-8 であることを明示するための option です。そのため、ECI が有効な場合、auto segmentation は non-ASCII text を byte mode に保ちます。explicit manual Kanji segment は引き続き利用できます。
+
+`gs1: true` は FNC1 first position を先頭に挿入し、input が raw GS1 element string であることを期待します。`parseGs1HumanReadable()` は対応 AI の parentheses notation を `{ ai, value }[]` に変換し、`createGs1ElementString()` は値を検証して、必要な位置に ASCII GS (`"\x1D"`) separator を挿入します。全 GS1 AI catalog validation、業界別 AI rule、check digit validation、FNC1 second position はこの phase には含めません。ECI と GS1/FNC1 first position は control-mode ordering が曖昧になるため併用を reject します。
+
+package は ESM-first です。`specqr`, `specqr/node`, `specqr/browser` の separate export を持ちます。CommonJS と minified browser build は build pipeline を導入するまで生成しません。source package は dependency-free runtime を保ちます。
+
+## v1 RC で意図的に対象外とするもの
+
+次の機能は core Model 2 package には実装していません。
+
+- FNC1 second position
+- Full GS1 AI catalog validation
+- Industry-specific GS1 AI rules
+- GS1 check digit validation
+- Structured Append
+- Micro QR
+- rMQR
+- Frame QR
+- SQRC
+- Logo overlay
+- Styled modules
+- Browser playground
+
+## v1 後の Roadmap
+
+通常 QR Code Model 2 以外の symbol family や domain extension は、core に直接混ぜず、別 module として扱う方針です。
+
+- `@specqr/gs1`: full GS1 AI validation、check-digit helpers、追加の GS1 domain helpers
+- `@specqr/structured-append`: multi-symbol splitting
+- `@specqr/micro`: Micro QR implementation
+- `@specqr/rmqr`: rectangular QR implementation
+- `@specqr/styled`: logo / module styling helpers と scan-risk diagnostics
+
+## Design Principle
+
+core generator は optional platform helper から独立させます。Matrix generation、Reed-Solomon error correction、data placement、mode encoding、mask selection は、browser や Node file system API なしで test できる状態を保ちます。