quadqr-js 1.2.0 → 1.3.0

package/FORMAT.md

@@ -4,7 +4,7 @@
 
 Experimental custom symbology. It is not ISO QR Code.
 
-Only this RGBW format is implemented. Earlier RGB/ternary formats are intentionally not supported.
+Normal mode uses the default 4-state RGBW data cells. An optional experimental **High Density Mode** uses the 16-state Triangle16 physical layout for payload/body cells. Earlier RGB/ternary formats are intentionally not supported.
 
 ## Matrix sizes
 
@@ -33,6 +33,17 @@ Four data states:
 
 Structural white and data white intentionally share the same visible/internal value. Reserved-position geometry distinguishes their roles.
 
+### High Density Mode (Triangle16)
+
+High Density Mode is identified by header flag bit 6 and implemented with Triangle16 cells. Each non-reserved payload module is split by a fixed `/` diagonal into an upper-left triangle and a lower-right triangle. Each triangle independently uses the RGBW 2-bit alphabet. The packed internal value is:
+
+```text
+cell = (upperLeftColor << 2) | lowerRightColor
+range = 0..15
+```
+
+Therefore Triangle16 has 16 visible states and carries 4 raw bits per body data cell. Same-color pairs such as R/R or B/B render as a visually solid module. Structural modules never use Triangle16 packing.
+
 ## Finder structures
 
 Three 7×7 black/white finder structures are placed at top-left, top-right, and bottom-left, with white separator cells where they fit inside the matrix.
@@ -99,6 +110,18 @@ Therefore:
 1 RGBW data cell = exactly 2 raw bits
 ```
 
+For Triangle16 ECC/body bytes:
+
+```text
+bits 7..4 -> Triangle16 cell 0
+bits 3..0 -> Triangle16 cell 1
+
+1 byte = exactly 2 Triangle16 body cells
+1 Triangle16 body cell = exactly 4 raw bits
+```
+
+The protected header remains encoded as four solid-color RGBW-equivalent cells per byte even when Triangle16 is selected. Internally those solid header cells are represented as R/R, G/G, B/B, or W/W. This keeps the bootstrap/header substantially easier to recover from blur and perspective distortion.
+
 ## Masks
 
 Four masks are defined. Each returns a 2-bit value 0..3:
@@ -117,7 +140,7 @@ visible = raw XOR mask
 raw     = visible XOR mask
 ```
 
-The encoder evaluates all four masks using run-length and four-state balance penalties. The mask ID is not serialized. The decoder tries all four and accepts only a path whose protected header, ECC, and CRC validate.
+The encoder evaluates all four masks using run-length and color-balance penalties. In Triangle16 body cells, two deterministic 2-bit masks are packed into one 4-bit XOR mask; protected solid-color header cells use the normal RGBW mask on both halves so they remain solid. The mask ID is not serialized. The decoder tries all four and accepts only a path whose protected header, ECC, and CRC validate.
 
 ## Header
 
@@ -167,7 +190,10 @@ Flags for both header forms:
 bit 0      UTF-8 text flag
 bits 1..2  ECC profile id
 bit 3      Secure Payload envelope flag
-bits 4..7  reserved
+bit 4      internal payload-extension metadata present
+bit 5      signed-payload hint
+bit 6      High Density Mode flag
+bit 7      reserved
 ```
 
 ECC ids:

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>Four visible states. Two bits per data cell. A modern experiment in high-density matrix codes.</strong>
+  <strong>Normal RGBW mode by default, with an optional experimental High Density Mode using Triangle16 split cells.</strong>
 </p>
 
 <p align="center">
@@ -26,9 +26,9 @@
   <a href="SPECIFICATION.md">Technical Specification</a>
 </p>
 
-**QuadQR** is an experimental open-source 2D matrix code that uses four visible data states instead of the two states used by a traditional black-and-white QR module.
+**QuadQR** is an experimental open-source 2D matrix code that uses RGBW color states instead of the two states used by a traditional black-and-white QR module. Normal mode stores **2 bits per RGBW data cell**. This experimental branch also includes an optional **High Density Mode**, implemented with Triangle16 split cells, that stores **4 raw bits per body cell**. High Density Mode is disabled by default.
 
-Each QuadQR data cell represents exactly **2 bits**:
+Default RGBW mapping:
 
 | Color | Bits |
 |---|---|
@@ -39,6 +39,28 @@ Each QuadQR data cell represents exactly **2 bits**:
 
 That gives QuadQR a four-symbol alphabet and a raw density of **2 bits per data cell**.
 
+### Experimental High Density Mode
+
+When `highDensity: true` is enabled, Triangle16 splits each payload cell along one fixed `/` diagonal. The upper-left and lower-right triangles independently use Red, Green, Blue, or White:
+
+```text
+4 colors × 4 colors = 16 states
+log2(16) = 4 bits per data cell
+```
+
+The protected bootstrap/header deliberately remains solid-color even in High Density Mode, while the ECC-protected body uses the full 16-state alphabet. This sacrifices a small amount of theoretical capacity to make mode detection and damaged-camera recovery more reliable. Finder, timing, alignment, calibration, ECC, CRC, and matrix dimensions remain unchanged.
+
+```js
+const code = encodeText("High-density QuadQR", {
+  ecc: "M",
+  highDensity: true
+});
+```
+
+Image and camera scanning automatically detect High Density Mode, so a separate scanner mode is not required. High Density Mode is experimental and should be stress-tested at the intended physical size and camera distance.
+
+See [`docs/HIGH_DENSITY_MODE.md`](docs/HIGH_DENSITY_MODE.md) for the physical cell mapping, protected-header strategy, scanner sampling rules, and reliability caveats.
+
 QuadQR keeps the parts that make QR-like codes practical, such as a square matrix, finder patterns, timing structures, error correction, masking, perspective recovery, and camera scanning, while experimenting with a higher-density color-based data layer.
 
 > **Important:** QuadQR is an experimental custom format. It is **not ISO QR Code**, and normal QR scanner apps cannot decode it.
@@ -131,7 +153,8 @@ So at the raw data-cell level:
 | Format | States per data cell | Raw information |
 |---|---:|---:|
 | Binary QR | 2 | 1 bit |
-| QuadQR | 4 | 2 bits |
+| QuadQR RGBW | 4 | 2 bits |
+| QuadQR High Density Mode (Triangle16) | 16 | 4 bits |
 
 This is a **2× raw symbol-density advantage**.
 
@@ -280,7 +303,7 @@ Therefore:
 
 > The capacity benchmark is a same-dimension and same-label comparison, not yet an equal-damage-tolerance comparison.
 
-The raw QuadQR data alphabet is exactly **2 bits per data cell**. Ratios approaching ~3× in the current usable-payload benchmark are caused by differences in total structural and ECC overhead between the two formats, not because a QuadQR cell contains 3 bits.
+The published baseline benchmark uses **normal RGBW mode at exactly 2 bits per data cell**. Ratios approaching ~3× in that RGBW usable-payload benchmark are caused by differences in total structural and ECC overhead between the two formats, not because an RGBW QuadQR cell contains 3 bits. The experimental **Triangle16** profile is a separate 4-bit/body-cell mode and should be benchmarked independently because its real-world advantage depends on camera resolution, perspective, blur, resizing, and print quality.
 
 A future goal is to add **equal-reliability benchmarking**, where QuadQR and standard QR are compared after calibrating both to similar real-world damage recovery.
 
@@ -442,7 +465,7 @@ White → (255, 255, 255)
 
 Real camera input is not expected to match those exact values.
 
-QuadQR includes calibration and nearest-color classification so the scanner can work with observed colors after lighting, camera processing, perspective changes, and other image transformations. The clean-frame path stays fast: QuadQR tries the normal detected geometry and observed palette first. Only after that fails does it progressively try stronger recovery, including white balancing, spatial normalization, Auto Tone / Auto Contrast / Auto Color-style enhancement, and bounded sub-module geometry refinement. For live video, QuadQR scans the CSS-visible `object-fit: cover` camera region instead of the hidden full sensor frame, so the code keeps the same apparent size/resolution the user sees in the guide. If finder geometry is already strong but color decoding fails, a QR-only rectified pixel enhancement retry is performed immediately; whole-frame enhancement remains reserved for harder locator failures.
+QuadQR includes calibration and nearest-color classification so the scanner can work with observed colors after lighting, camera processing, perspective changes, and other image transformations. The clean-frame path stays fast: QuadQR tries the normal detected geometry and observed palette first. Dense versions can refine an imperfect four-point homography with reliable secondary alignment markers already present in the matrix, without reserving any new cells. If a steep angle leaves exactly two strong finder patterns, a bounded looser third-finder pass runs before heavier color recovery. Only after geometry/color decoding still fails does QuadQR progressively try stronger recovery, including white balancing, spatial normalization, Auto Tone / Auto Contrast / Auto Color-style enhancement, and bounded sub-module geometry refinement. For live video, QuadQR scans the CSS-visible `object-fit: cover` camera region instead of the hidden full sensor frame, so the code keeps the same apparent size/resolution the user sees in the guide. When a dense frame already exposes at least two finders, the camera scanner can also retry the visible ROI at up to 1600 px before expensive color recovery. If finder geometry is already strong but color decoding fails, a QR-only rectified pixel enhancement retry is performed immediately; whole-frame enhancement remains reserved for harder locator failures.
 
 ---
 
@@ -504,9 +527,11 @@ version hypothesis
   ↓
 primary alignment search
   ↓
-homography / perspective correction
+initial homography / perspective correction
   ↓
 distributed alignment-grid validation
+  ↓ (when geometry is plausible but imperfect)
+secondary alignment multi-point homography refinement
   ↓
 module-grid reconstruction
   ↓
@@ -1034,7 +1059,7 @@ Returns a standalone SVG string using the same exact `imageSize`, render styles,
 
 ### `scanImageData(imageData, options?)`
 
-Runs the complete perspective-aware and color-aware image scanner. The scanner first tries the normal detected geometry with the observed RGB palette, preserving the fast path for clean images. Only after that fails does it progressively fall back to per-channel white balancing, spatial black/white normalization, tighter centre sampling, a cheap module-grid Auto Tone / Auto Contrast / Auto Color-style recovery, a rectified QR-region pixel enhancement pass, and finally bounded sub-module geometry micro-refinement. If locator detection itself is weakened by a flat/yellow frame, a full-image enhancement retry is also available. RGBW confidence values are carried into Reed-Solomon so ambiguous cells can be treated as erasures when ordinary hard-decision ECC is insufficient.
+Runs the complete perspective-aware and color-aware image scanner. The scanner first tries the normal detected geometry with the observed RGB palette, preserving the fast path for clean images. Dense versions use distributed alignment markers to refine a plausible but imperfect projective solution, and a two-finder recovery pass can rescue a third locator that has been stretched by perspective. Only after that fails does it progressively fall back to per-channel white balancing, spatial black/white normalization, tighter centre sampling, a cheap module-grid Auto Tone / Auto Contrast / Auto Color-style recovery, a rectified QR-region pixel enhancement pass, and finally bounded sub-module geometry micro-refinement. If locator detection itself is weakened by a flat/yellow frame, a full-image enhancement retry is also available. RGBW confidence values are carried into Reed-Solomon so ambiguous cells can be treated as erasures when ordinary hard-decision ECC is insufficient.
 
 ### `scanFile(file, options?)`
 
@@ -1046,7 +1071,7 @@ Scans one frame from an HTML video element. By default, if the video is displaye
 
 ### `startCameraScanner(video, options?)`
 
-Starts a reusable live-camera scanning loop. On supported browsers it requests continuous focus/exposure/white-balance camera modes and scans the CSS-visible preview crop. A normal frame always gets the fast RGB-value finder pass first. If that fails, the **same captured frame** enters a QR-guide recovery path: QuadQR progressively crops away 8%, 16%, and 22% of the surrounding camera frame (then tries the full frame as a final fallback), applies the Photoshop-style Auto Color correction inside that code-centric region, and runs finder detection again. This matters because a live preview can contain dark room pixels, browser chrome, a monitor bezel, or other content that completely changes global Auto Color/Otsu statistics even though a manually cropped screenshot scans instantly. Normal scanning stays unchanged and fast because these recovery crops run only after a miss. Finder-only recovery also tries multiple center-weighted Auto Color histograms before threshold bracketing. `cameraAutoColorEvery` defaults to 1 so the same-frame Auto Color recovery is attempted immediately after each fast miss. Multi-frame voting remains enabled by default with a four-frame history. The optional `onDiagnostic(event)` callback exposes finder candidates, active locator method, crop/geometry/version hypothesis, recovery method, timing, and scan dimensions. `onResult(result, frame)` receives the exact raw decoded camera frame and, when Auto Color was used, the enhanced recovery pixels and their crop rectangle, so UIs can keep the frozen frame and finder overlay aligned.
+Starts a reusable live-camera scanning loop. On supported browsers it requests continuous focus/exposure/white-balance camera modes and scans the CSS-visible preview crop. A normal frame always gets the fast RGB-value finder pass first. If a miss still exposes at least two strong finder patterns, QuadQR retries the visible camera ROI at up to 1600 px by default so dense symbols retain more pixels per module. This high-resolution retry is bounded and does not run on empty frames. If it still fails, the **same captured frame** enters a QR-guide recovery path: QuadQR progressively crops away 8%, 16%, and 22% of the surrounding camera frame (then tries the full frame as a final fallback), applies the Photoshop-style Auto Color correction inside that code-centric region, and runs finder detection again. This matters because a live preview can contain dark room pixels, browser chrome, a monitor bezel, or other content that completely changes global Auto Color/Otsu statistics even though a manually cropped screenshot scans instantly. Normal scanning stays unchanged and fast because these recovery paths run only after a miss. Finder-only recovery also tries multiple center-weighted Auto Color histograms before threshold bracketing. `cameraHighResolutionMaxDimension` defaults to 1600, `cameraHighResolutionEvery` defaults to 2, and `cameraAutoColorEvery` defaults to 1. Multi-frame voting remains enabled by default with a four-frame history. The optional `onDiagnostic(event)` callback exposes finder candidates, active locator method, crop/geometry/version hypothesis, recovery method, timing, and scan dimensions. `onResult(result, frame)` receives the exact raw decoded camera frame and, when Auto Color was used, the enhanced recovery pixels and their crop rectangle, so UIs can keep the frozen frame and finder overlay aligned.
 
 ### `getVersionInfo(version, options?)`
 

package/SPECIFICATION.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-QuadQR is an experimental four-state RGBW matrix symbology. It is not ISO/IEC QR Code and is not intended to be decoded by standard QR readers.
+QuadQR is an experimental RGBW matrix symbology. Normal mode uses 4-state RGBW cells, while the optional **High Density Mode** is experimental and uses the 16-state Triangle16 physical layout. It is not ISO/IEC QR Code and is not intended to be decoded by standard QR readers.
 
 The physical matrix format remains **QuadQR Format v5**. Normal application data is always treated simply as UTF-8 text or arbitrary bytes. Compression, signatures, encryption, rendering, and diagnostics are optional features layered around that stable matrix codec.
 
@@ -22,7 +22,7 @@ Application bytes / UTF-8 text
              ├─ CRC-32
              ├─ GF(256) Reed-Solomon Spectrum ECC
              ├─ spectral-spatial interleaving
-             └─ RGBW matrix
+             └─ normal RGBW or High Density Triangle16 matrix
 ```
 
 There is deliberately **no public payload-type registry**. Applications do not select URL, JSON, contact, Wi-Fi, or other semantic types. They encode text or bytes and interpret that data themselves.
@@ -40,6 +40,10 @@ Data modules use exactly four states:
 
 Structural black is separate from the data alphabet. One encoded byte maps to exactly four RGBW data cells.
 
+### High Density Mode
+
+When `highDensity: true` is selected, each payload module has a fixed `/` diagonal and two independently classified RGBW regions. This creates 16 states and 4 raw bits per body cell. The protected header stays solid-color at 2 bits per cell for robust bootstrap recovery, then header flag bit 6 tells the decoder that the ECC/body stream uses Triangle16 packing. Scanner sampling uses two points well inside the triangles and excludes the diagonal boundary.
+
 ## 3. Matrix sizing
 
 ```text
@@ -59,7 +63,8 @@ bits 1..2  ECC profile id
 bit 3      Secure Payload v1 envelope
 bit 4      internal payload-extension metadata present
 bit 5      signed-payload hint
-bits 6..7  reserved
+bit 6      High Density Mode flag
+bit 7      reserved
 ```
 
 Bit 4 is an implementation/interoperability hint used only when compression or signing requires metadata. It is not a user-selectable payload mode.

package/bin/quadqr.js

@@ -15,7 +15,7 @@ import {
 import { savePNG, saveSVG, scanFile } from "../dist/node.js";
 
 function help() {
-  console.log(`QuadQR CLI\n\nUsage:\n  quadqr encode <text> [-o file.png|file.svg] [--ecc M] [--version auto|1..40]\n  quadqr encode <text> [--compression auto]\n  quadqr encode <text> --sign-key signing-key.json [--key-id issuer-main]\n  quadqr encode <text> --password <password> [-o file.png|file.svg]\n  quadqr decode <file.png> [--password <password> | --key <64-hex-key>] [--verify-key signing-key.json] [--debug]\n  quadqr keygen\n  quadqr signkeygen [-o signing-key.json]\n\nOptions:\n  -o, --output <file>       Output PNG/SVG path, or signing-key JSON for signkeygen\n  --ecc <L|M|Q|H>          ECC profile (default: M)\n  --version <auto|1..40>    Symbol version (default: auto)\n  --compression <mode>      none|auto|lz (default: auto)\n  --sign-key <file>         Sign using a signkeygen JSON bundle\n  --key-id <id>             Override the signing key ID stored in the QuadQR\n  --embed-public-key        Also embed the public key for untrusted/self-contained checks\n  --verify-key <file>       Verify a signed QuadQR with a trusted key bundle\n  --password <text>         Encrypt/decrypt with password mode\n  --key <hex>               Encrypt/decrypt with raw 256-bit key mode\n  --print                   Use the print-safe render profile\n  --image-size <px>         Exact square output size (default: 720)\n  --module-size <px>        Legacy pixels-per-module sizing\n  --quiet-zone <modules>    Quiet zone in modules (default: 4)\n  --debug                   Emit scanner diagnostics to stderr on decode\n  -h, --help                Show help\n`);
+  console.log(`QuadQR CLI\n\nUsage:\n  quadqr encode <text> [-o file.png|file.svg] [--ecc M] [--version auto|1..40] [--high-density]\n  quadqr encode <text> [--compression auto]\n  quadqr encode <text> --sign-key signing-key.json [--key-id issuer-main]\n  quadqr encode <text> --password <password> [-o file.png|file.svg]\n  quadqr decode <file.png> [--password <password> | --key <64-hex-key>] [--verify-key signing-key.json] [--debug]\n  quadqr keygen\n  quadqr signkeygen [-o signing-key.json]\n\nOptions:\n  -o, --output <file>       Output PNG/SVG path, or signing-key JSON for signkeygen\n  --ecc <L|M|Q|H>          ECC profile (default: M)\n  --version <auto|1..40>    Symbol version (default: auto)\n  --compression <mode>      none|auto|lz (default: auto)\n  --high-density            Enable experimental Triangle16 High Density Mode\n  --sign-key <file>         Sign using a signkeygen JSON bundle\n  --key-id <id>             Override the signing key ID stored in the QuadQR\n  --embed-public-key        Also embed the public key for untrusted/self-contained checks\n  --verify-key <file>       Verify a signed QuadQR with a trusted key bundle\n  --password <text>         Encrypt/decrypt with password mode\n  --key <hex>               Encrypt/decrypt with raw 256-bit key mode\n  --print                   Use the print-safe render profile\n  --image-size <px>         Exact square output size (default: 720)\n  --module-size <px>        Legacy pixels-per-module sizing\n  --quiet-zone <modules>    Quiet zone in modules (default: 4)\n  --debug                   Emit scanner diagnostics to stderr on decode\n  -h, --help                Show help\n`);
 }
 
 function parse(argv) {
@@ -27,6 +27,7 @@ function parse(argv) {
     else if (token === "-o" || token === "--output") flags.output = argv[++i];
     else if (token === "--ecc") flags.ecc = argv[++i];
     else if (token === "--version") flags.version = argv[++i];
+    else if (token === "--high-density") flags.highDensity = true;
     else if (token === "--password") flags.password = argv[++i];
     else if (token === "--key") flags.key = argv[++i];
     else if (token === "--compression") flags.compression = argv[++i];
@@ -101,6 +102,7 @@ async function main() {
 
     const options = {
       ecc: flags.ecc || "M",
+      highDensity: Boolean(flags.highDensity),
       compression: flags.compression || "auto",
       ...(flags.version && flags.version !== "auto" ? { version: Number(flags.version) } : {})
     };
@@ -138,7 +140,7 @@ async function main() {
     const saved = output.toLowerCase().endsWith(".svg")
       ? await saveSVG(code, output, renderOptions)
       : await savePNG(code, output, renderOptions);
-    console.log(`Saved ${output} (${saved.bytes} bytes, v${code.version}, ${code.size}x${code.size}, ECC ${code.eccLevel}).`);
+    console.log(`Saved ${output} (${saved.bytes} bytes, v${code.version}, ${code.size}x${code.size}, ${code.highDensity ? "High Density experimental" : "Normal RGBW"}, ECC ${code.eccLevel}).`);
     return;
   }
 

package/dist/esm/benchmark.js

@@ -30,6 +30,16 @@ function normalizeEcc(ecc = "M") {
   return value;
 }
 
+function resolveHighDensity(options = {}) {
+  if (typeof options.highDensity === "boolean") return options.highDensity;
+  // Backward compatibility for the first experimental Triangle16 branch.
+  return options.cellEncoding === "triangle16";
+}
+
+function encodingForHighDensity(highDensity) {
+  return highDensity ? "triangle16" : "rgbw";
+}
+
 function nowMs() {
   if (typeof performance !== "undefined" && typeof performance.now === "function") {
     return performance.now();
@@ -76,9 +86,11 @@ export function getStandardQrByteCapacity(version, ecc = "M") {
   return STANDARD_QR_BYTE_CAPACITY[normalizeEcc(ecc)][version - 1];
 }
 
-export function compareCapacity(version, ecc = "M") {
+export function compareCapacity(version, ecc = "M", options = {}) {
   const level = normalizeEcc(ecc);
-  const quadqr = getVersionInfo(version, { ecc: level });
+  const highDensity = resolveHighDensity(options);
+  const cellEncoding = encodingForHighDensity(highDensity);
+  const quadqr = getVersionInfo(version, { ecc: level, highDensity });
   const standardQrBytes = getStandardQrByteCapacity(version, level);
   const quadqrBytes = quadqr.capacityBytes;
   const differenceBytes = quadqrBytes - standardQrBytes;
@@ -94,6 +106,8 @@ export function compareCapacity(version, ecc = "M") {
     differenceBytes,
     ratio,
     gainPercent,
+    highDensity,
+    cellEncoding: quadqr.cellEncoding,
     quadqrBitsPerDataCell: quadqr.bitsPerDataCell,
     quadqrPayloadEfficiencyPercent: quadqr.theoreticalBits > 0
       ? (quadqrBytes * 8 / quadqr.theoreticalBits) * 100
@@ -108,6 +122,8 @@ export function compareCapacity(version, ecc = "M") {
 /** Calculate the smallest QuadQR and standard QR versions for a payload size. */
 export function calculateCapacityPlan(options = {}) {
   const ecc = normalizeEcc(options.ecc ?? "M");
+  const highDensity = resolveHighDensity(options);
+  const cellEncoding = encodingForHighDensity(highDensity);
   let sourceBytes;
   const hasConcretePayload = options.payload instanceof Uint8Array || typeof options.payload === "string";
   if (options.payload instanceof Uint8Array) sourceBytes = options.payload;
@@ -143,7 +159,7 @@ export function calculateCapacityPlan(options = {}) {
   let quadqrVersion = null;
   let quadqrInfo = null;
   for (let version = 1; version <= MAX_VERSION; version++) {
-    const info = getVersionInfo(version, { ecc });
+    const info = getVersionInfo(version, { ecc, highDensity });
     if (encodedBytes <= info.capacityBytes) {
       quadqrVersion = version;
       quadqrInfo = info;
@@ -162,6 +178,8 @@ export function calculateCapacityPlan(options = {}) {
 
   return {
     ecc,
+    highDensity,
+    cellEncoding,
     sourceBytes: sourceBytes.length,
     encodedBytes,
     storedBytes,
@@ -185,12 +203,15 @@ export function calculateCapacityPlan(options = {}) {
 
 export function buildCapacityComparison(options = {}) {
   const ecc = normalizeEcc(options.ecc ?? "M");
+  const highDensity = resolveHighDensity(options);
   const versions = options.versions ?? Array.from({ length: MAX_VERSION }, (_, i) => i + 1);
-  return versions.map((version) => compareCapacity(version, ecc));
+  return versions.map((version) => compareCapacity(version, ecc, { highDensity }));
 }
 
 export function benchmarkCodec(options = {}) {
   const ecc = normalizeEcc(options.ecc ?? "M");
+  const highDensity = resolveHighDensity(options);
+  const cellEncoding = encodingForHighDensity(highDensity);
   const iterations = Math.max(1, Math.floor(options.iterations ?? 30));
   const warmup = Math.max(0, Math.floor(options.warmup ?? Math.min(5, iterations)));
   const requestedSizes = options.payloadSizes ?? [24, 32, 128, 512, 1024, 2048];
@@ -202,14 +223,14 @@ export function benchmarkCodec(options = {}) {
 
     let probe;
     try {
-      probe = encodeBytes(payload, { ecc });
+      probe = encodeBytes(payload, { ecc, highDensity });
     } catch (error) {
       results.push({ payloadBytes, skipped: true, reason: error.message });
       continue;
     }
 
     for (let i = 0; i < warmup; i++) {
-      const encoded = encodeBytes(payload, { ecc, version: probe.version });
+      const encoded = encodeBytes(payload, { ecc, highDensity, version: probe.version });
       decodeMatrix(encoded.matrix);
     }
 
@@ -219,7 +240,7 @@ export function benchmarkCodec(options = {}) {
 
     for (let i = 0; i < iterations; i++) {
       let start = nowMs();
-      encoded = encodeBytes(payload, { ecc, version: probe.version });
+      encoded = encodeBytes(payload, { ecc, highDensity, version: probe.version });
       encodeSamples.push(nowMs() - start);
 
       start = nowMs();
@@ -231,7 +252,7 @@ export function benchmarkCodec(options = {}) {
       }
     }
 
-    const versionInfo = getVersionInfo(encoded.version, { ecc });
+    const versionInfo = getVersionInfo(encoded.version, { ecc, highDensity });
     results.push({
       payloadBytes,
       skipped: false,
@@ -250,6 +271,8 @@ export function benchmarkCodec(options = {}) {
   return {
     format: "QuadQR",
     ecc,
+    highDensity,
+    cellEncoding,
     iterations,
     warmup,
     generatedAt: new Date().toISOString(),
@@ -259,11 +282,13 @@ export function benchmarkCodec(options = {}) {
 
 export function benchmarkReport(options = {}) {
   const ecc = normalizeEcc(options.ecc ?? "M");
+  const highDensity = resolveHighDensity(options);
   const versions = options.versions ?? [1, 2, 5, 10, 20, 30, 40];
   return {
-    capacity: buildCapacityComparison({ ecc, versions }),
+    capacity: buildCapacityComparison({ ecc, versions, highDensity }),
     performance: benchmarkCodec({
       ecc,
+      highDensity,
       iterations: options.iterations ?? 30,
       warmup: options.warmup,
       payloadSizes: options.payloadSizes