@sythos/js_barcode_universal 1.1.0 → 1.3.1

package/src/datamatrix/tables.js

@@ -1,123 +1,123 @@
-/*!
- * 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.
- */
-
-/**
- * Data Matrix ECC 200 symbol parameters.
- *
- * Width and height include finder borders. `regionWidth` and `regionHeight`
- * describe the usable modules inside one data region. The last three columns
- * make the Reed-Solomon block split explicit instead of hiding the 144x144
- * exception in encoder control flow.
- *
- * @module datamatrix/tables
- */
-
-function symbol(width, height, dataRegionWidth, dataRegionHeight, dataCodewords, errorCodewords, dataBlockLengths) {
-  const blockCount = dataBlockLengths.length;
-  return Object.freeze({
-    width, height, rows: height, columns: width,
-    // Region dimensions include their one-module finder border on each side;
-    // dataRegion* expose the inner placement lattice explicitly.
-    regionWidth: dataRegionWidth + 2, regionHeight: dataRegionHeight + 2,
-    dataRegionWidth, dataRegionHeight,
-    dataRegionRows: dataRegionHeight, dataRegionColumns: dataRegionWidth,
-    dataCodewords, errorCodewords, blockCount,
-    eccPerBlock: errorCodewords / blockCount,
-    dataBlockLengths: Object.freeze(dataBlockLengths),
-  });
-}
-
-/** Classic ISO/IEC 16022 ECC 200 symbols; DMRE is deliberately excluded. */
-export const DATAMATRIX_SYMBOLS = Object.freeze([
-  symbol(10, 10, 8, 8, 3, 5, [3]),
-  symbol(12, 12, 10, 10, 5, 7, [5]),
-  symbol(14, 14, 12, 12, 8, 10, [8]),
-  symbol(16, 16, 14, 14, 12, 12, [12]),
-  symbol(18, 18, 16, 16, 18, 14, [18]),
-  symbol(20, 20, 18, 18, 22, 18, [22]),
-  symbol(22, 22, 20, 20, 30, 20, [30]),
-  symbol(24, 24, 22, 22, 36, 24, [36]),
-  symbol(26, 26, 24, 24, 44, 28, [44]),
-  symbol(32, 32, 14, 14, 62, 36, [62]),
-  symbol(36, 36, 16, 16, 86, 42, [86]),
-  symbol(40, 40, 18, 18, 114, 48, [114]),
-  symbol(44, 44, 20, 20, 144, 56, [144]),
-  symbol(48, 48, 22, 22, 174, 68, [174]),
-  symbol(52, 52, 24, 24, 204, 84, [102, 102]),
-  symbol(64, 64, 14, 14, 280, 112, [140, 140]),
-  symbol(72, 72, 16, 16, 368, 144, [92, 92, 92, 92]),
-  symbol(80, 80, 18, 18, 456, 192, [114, 114, 114, 114]),
-  symbol(88, 88, 20, 20, 576, 224, [144, 144, 144, 144]),
-  symbol(96, 96, 22, 22, 696, 272, [174, 174, 174, 174]),
-  symbol(104, 104, 24, 24, 816, 336, [136, 136, 136, 136, 136, 136]),
-  symbol(120, 120, 18, 18, 1050, 408, [175, 175, 175, 175, 175, 175]),
-  symbol(132, 132, 20, 20, 1304, 496, [163, 163, 163, 163, 163, 163, 163, 163]),
-  symbol(144, 144, 22, 22, 1558, 620, [156, 156, 156, 156, 156, 156, 156, 156, 155, 155]),
-  symbol(18, 8, 16, 6, 5, 7, [5]),
-  symbol(32, 8, 14, 6, 10, 11, [10]),
-  symbol(26, 12, 24, 10, 16, 14, [16]),
-  symbol(36, 12, 16, 10, 22, 18, [22]),
-  symbol(36, 16, 16, 14, 32, 24, [32]),
-  symbol(48, 16, 22, 14, 49, 28, [49]),
-]);
-
-/** Compatibility alias. */
-export const SYMBOLS = DATAMATRIX_SYMBOLS;
-
-/** Return the smallest permitted symbol that holds `count` data codewords. */
-export function symbolForDataCodewords(count, shape = 'any') {
-  for (const s of DATAMATRIX_SYMBOLS) {
-    const rectangular = s.width !== s.height;
-    if ((shape === 'square' && rectangular) || (shape === 'rectangular' && !rectangular)) continue;
-    if (count <= s.dataCodewords) return s;
-  }
-  throw new RangeError(`Data Matrix: ${count} data codewords do not fit an ECC 200 ${shape} symbol`);
-}
-
-/** Check redundant geometry and block identities in the static table. */
-export function validateDataMatrixTables() {
-  const issues = [];
-  for (const s of DATAMATRIX_SYMBOLS) {
-    const regionsX = s.width / s.regionWidth;
-    const regionsY = s.height / s.regionHeight;
-    if (!Number.isInteger(regionsX) || !Number.isInteger(regionsY)) issues.push(`${s.width}x${s.height}: non-integral regions`);
-    const modules = regionsX * regionsY * s.dataRegionWidth * s.dataRegionHeight;
-    // Annex F reserves four terminal modules on a few lattice dimensions.
-    // They are set to dark after codeword placement and do not carry data.
-    const unused = modules - (s.dataCodewords + s.errorCodewords) * 8;
-    if (unused !== 0 && unused !== 4) issues.push(`${s.width}x${s.height}: geometry/codeword mismatch`);
-    if (s.dataBlockLengths.reduce((a, b) => a + b, 0) !== s.dataCodewords) issues.push(`${s.width}x${s.height}: data block mismatch`);
-    if (s.eccPerBlock * s.blockCount !== s.errorCodewords) issues.push(`${s.width}x${s.height}: ecc block mismatch`);
-  }
-  return issues;
-}
-
-/** Compatibility alias. */
-export const validateTables = validateDataMatrixTables;
+/*!
+ * 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.
+ */
+
+/**
+ * Data Matrix ECC 200 symbol parameters.
+ *
+ * Width and height include finder borders. `regionWidth` and `regionHeight`
+ * describe the usable modules inside one data region. The last three columns
+ * make the Reed-Solomon block split explicit instead of hiding the 144x144
+ * exception in encoder control flow.
+ *
+ * @module datamatrix/tables
+ */
+
+function symbol(width, height, dataRegionWidth, dataRegionHeight, dataCodewords, errorCodewords, dataBlockLengths) {
+  const blockCount = dataBlockLengths.length;
+  return Object.freeze({
+    width, height, rows: height, columns: width,
+    // Region dimensions include their one-module finder border on each side;
+    // dataRegion* expose the inner placement lattice explicitly.
+    regionWidth: dataRegionWidth + 2, regionHeight: dataRegionHeight + 2,
+    dataRegionWidth, dataRegionHeight,
+    dataRegionRows: dataRegionHeight, dataRegionColumns: dataRegionWidth,
+    dataCodewords, errorCodewords, blockCount,
+    eccPerBlock: errorCodewords / blockCount,
+    dataBlockLengths: Object.freeze(dataBlockLengths),
+  });
+}
+
+/** Classic ISO/IEC 16022 ECC 200 symbols; DMRE is deliberately excluded. */
+export const DATAMATRIX_SYMBOLS = Object.freeze([
+  symbol(10, 10, 8, 8, 3, 5, [3]),
+  symbol(12, 12, 10, 10, 5, 7, [5]),
+  symbol(14, 14, 12, 12, 8, 10, [8]),
+  symbol(16, 16, 14, 14, 12, 12, [12]),
+  symbol(18, 18, 16, 16, 18, 14, [18]),
+  symbol(20, 20, 18, 18, 22, 18, [22]),
+  symbol(22, 22, 20, 20, 30, 20, [30]),
+  symbol(24, 24, 22, 22, 36, 24, [36]),
+  symbol(26, 26, 24, 24, 44, 28, [44]),
+  symbol(32, 32, 14, 14, 62, 36, [62]),
+  symbol(36, 36, 16, 16, 86, 42, [86]),
+  symbol(40, 40, 18, 18, 114, 48, [114]),
+  symbol(44, 44, 20, 20, 144, 56, [144]),
+  symbol(48, 48, 22, 22, 174, 68, [174]),
+  symbol(52, 52, 24, 24, 204, 84, [102, 102]),
+  symbol(64, 64, 14, 14, 280, 112, [140, 140]),
+  symbol(72, 72, 16, 16, 368, 144, [92, 92, 92, 92]),
+  symbol(80, 80, 18, 18, 456, 192, [114, 114, 114, 114]),
+  symbol(88, 88, 20, 20, 576, 224, [144, 144, 144, 144]),
+  symbol(96, 96, 22, 22, 696, 272, [174, 174, 174, 174]),
+  symbol(104, 104, 24, 24, 816, 336, [136, 136, 136, 136, 136, 136]),
+  symbol(120, 120, 18, 18, 1050, 408, [175, 175, 175, 175, 175, 175]),
+  symbol(132, 132, 20, 20, 1304, 496, [163, 163, 163, 163, 163, 163, 163, 163]),
+  symbol(144, 144, 22, 22, 1558, 620, [156, 156, 156, 156, 156, 156, 156, 156, 155, 155]),
+  symbol(18, 8, 16, 6, 5, 7, [5]),
+  symbol(32, 8, 14, 6, 10, 11, [10]),
+  symbol(26, 12, 24, 10, 16, 14, [16]),
+  symbol(36, 12, 16, 10, 22, 18, [22]),
+  symbol(36, 16, 16, 14, 32, 24, [32]),
+  symbol(48, 16, 22, 14, 49, 28, [49]),
+]);
+
+/** Compatibility alias. */
+export const SYMBOLS = DATAMATRIX_SYMBOLS;
+
+/** Return the smallest permitted symbol that holds `count` data codewords. */
+export function symbolForDataCodewords(count, shape = 'any') {
+  for (const s of DATAMATRIX_SYMBOLS) {
+    const rectangular = s.width !== s.height;
+    if ((shape === 'square' && rectangular) || (shape === 'rectangular' && !rectangular)) continue;
+    if (count <= s.dataCodewords) return s;
+  }
+  throw new RangeError(`Data Matrix: ${count} data codewords do not fit an ECC 200 ${shape} symbol`);
+}
+
+/** Check redundant geometry and block identities in the static table. */
+export function validateDataMatrixTables() {
+  const issues = [];
+  for (const s of DATAMATRIX_SYMBOLS) {
+    const regionsX = s.width / s.regionWidth;
+    const regionsY = s.height / s.regionHeight;
+    if (!Number.isInteger(regionsX) || !Number.isInteger(regionsY)) issues.push(`${s.width}x${s.height}: non-integral regions`);
+    const modules = regionsX * regionsY * s.dataRegionWidth * s.dataRegionHeight;
+    // Annex F reserves four terminal modules on a few lattice dimensions.
+    // They are set to dark after codeword placement and do not carry data.
+    const unused = modules - (s.dataCodewords + s.errorCodewords) * 8;
+    if (unused !== 0 && unused !== 4) issues.push(`${s.width}x${s.height}: geometry/codeword mismatch`);
+    if (s.dataBlockLengths.reduce((a, b) => a + b, 0) !== s.dataCodewords) issues.push(`${s.width}x${s.height}: data block mismatch`);
+    if (s.eccPerBlock * s.blockCount !== s.errorCodewords) issues.push(`${s.width}x${s.height}: ecc block mismatch`);
+  }
+  return issues;
+}
+
+/** Compatibility alias. */
+export const validateTables = validateDataMatrixTables;

package/src/frameqr/decoder.js

@@ -0,0 +1,239 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Decoder for the Sythos Canvas QR profile.
+ *
+ * This is intentionally not a DENSO FrameQR decoder. The profile is a QR
+ * symbol with a bounded artwork reservation and an explicit `frameqr` marker.
+ * A normal QR matrix is rejected unless a detector (or another trusted
+ * caller) supplies the profile and explicitly opts in to an unmarked matrix.
+ *
+ * The QR decoder is deliberately kept as the single payload decoder. It can
+ * repair the bounded modules removed for the canvas because the encoder fixes
+ * error correction to H and validates the reservation before clearing it.
+ *
+ * @module frameqr/decoder
+ */
+
+import { FormatError } from '../core/errors.js';
+import { decodeQR } from '../qr/decoder.js';
+import {
+  FRAMEQR_PROFILE,
+  normalizeCanvasSpec,
+  validateCanvasSpec,
+  analyzeCanvasDamage,
+} from './tables.js';
+
+/** @param {unknown} value @returns {boolean} */
+function isObject(value) {
+  return value !== null && typeof value === 'object';
+}
+
+/**
+ * Return the profile marker attached by the encoder. Older callers sometimes
+ * use camel case, so accepting it here is harmless while the emitted marker
+ * remains the canonical `frameqr` property.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ * @returns {object|null}
+ */
+function markerOf(matrix) {
+  const marker = matrix && (matrix.frameqr ?? matrix.frameQR);
+  return isObject(marker) ? marker : null;
+}
+
+/** @param {unknown} profile @returns {boolean} */
+function isExpectedProfile(profile) {
+  if (profile === FRAMEQR_PROFILE.id) return true;
+  return isObject(profile) && profile.id === FRAMEQR_PROFILE.id;
+}
+
+/**
+ * Normalize and validate the canvas metadata. Validation functions in the
+ * table module throw on invalid input; a few consumers also return `false` or
+ * a problem list, so those forms are handled defensively here.
+ *
+ * @param {number} symbolSize
+ * @param {number} version
+ * @param {object} canvas
+ * @returns {{canvas: object, damage: object}}
+ */
+function validateCanvas(symbolSize, version, canvas) {
+  if (!isObject(canvas)) throw new FormatError('Sythos Canvas QR: canvas metadata is missing');
+
+  let normalized;
+  try {
+    normalized = normalizeCanvasSpec(symbolSize, canvas);
+    const validation = validateCanvasSpec(version, normalized);
+    if (
+      validation === false ||
+      (Array.isArray(validation) && validation.length > 0) ||
+      (isObject(validation) && validation.valid === false) ||
+      (isObject(validation) && validation.safe === false)
+    ) {
+      throw new Error('canvas geometry is outside the profile limits');
+    }
+  } catch (error) {
+    if (error instanceof FormatError) throw error;
+    throw new FormatError(`Sythos Canvas QR: invalid canvas metadata: ${error.message}`);
+  }
+
+  let damage;
+  try {
+    damage = analyzeCanvasDamage(version, normalized);
+  } catch (error) {
+    throw new FormatError(`Sythos Canvas QR: cannot analyse canvas damage: ${error.message}`);
+  }
+  return { canvas: normalized, damage };
+}
+
+/**
+ * Resolve the profile marker and canvas from the matrix/options pair.
+ *
+ * `allowUnmarked` is deliberately opt-in. It exists for a detector that has
+ * already verified the canvas signature after sampling a photograph; it is
+ * not enabled by the public default and therefore cannot silently relabel an
+ * ordinary QR Code as FrameQR.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ * @param {object} options
+ * @returns {{profile: string, canvas: object, damage: object, certified: false}}
+ */
+function resolveProfile(matrix, options) {
+  const marker = markerOf(matrix);
+  const suppliedProfile = options.profile;
+  const markerProfile = marker ? marker.profile : undefined;
+  if (markerProfile !== undefined && suppliedProfile !== undefined) {
+    const markerId = isObject(markerProfile) ? markerProfile.id : markerProfile;
+    const suppliedId = isObject(suppliedProfile) ? suppliedProfile.id : suppliedProfile;
+    if (markerId !== suppliedId) {
+      throw new FormatError('Sythos Canvas QR: matrix and requested profile markers disagree');
+    }
+  }
+  const profile = markerProfile ?? suppliedProfile;
+
+  if (!isExpectedProfile(profile)) {
+    throw new FormatError(
+      'Sythos Canvas QR: profile marker is missing or is not the Sythos Canvas QR profile'
+    );
+  }
+  if (marker && marker.certified === true) {
+    throw new FormatError(
+      'Sythos Canvas QR: certified FrameQR input is not supported by this profile decoder'
+    );
+  }
+  if (!marker && !options.allowUnmarked) {
+    throw new FormatError(
+      'Sythos Canvas QR: unmarked QR matrix rejected; provide a verified profile marker'
+    );
+  }
+
+  const markerCanvas = marker ? marker.canvas : undefined;
+  const canvas = options.canvas ?? markerCanvas;
+  const version = (matrix.width - 17) / 4;
+  if (!Number.isInteger(version) || version < 1 || version > 40) {
+    throw new FormatError(`Sythos Canvas QR: invalid QR symbol size ${matrix.width}`);
+  }
+  const checked = validateCanvas(matrix.width, version, canvas);
+  if (markerCanvas && options.canvas) {
+    let marked;
+    try {
+      marked = normalizeCanvasSpec(matrix.width, markerCanvas);
+    } catch (error) {
+      throw new FormatError(`Sythos Canvas QR: invalid marker canvas: ${error.message}`);
+    }
+    const fields = ['shape', 'centerX', 'centerY', 'width', 'height', 'angle'];
+    if (fields.some((field) => marked[field] !== checked.canvas[field])) {
+      throw new FormatError('Sythos Canvas QR: matrix and requested canvas metadata disagree');
+    }
+  }
+  return {
+    profile: FRAMEQR_PROFILE.id,
+    canvas: checked.canvas,
+    damage: checked.damage,
+    certified: false,
+  };
+}
+
+/**
+ * Decode a Sythos Canvas QR matrix.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ *   Square QR modules, normally returned by `encodeFrameQR` or a FrameQR
+ *   detector. The encoder's `frameqr` metadata is required by default.
+ * @param {object} [options]
+ * @param {object} [options.canvas] Explicit canvas metadata for a sampled
+ *   matrix when the source marker was not preserved.
+ * @param {string|object} [options.profile] Expected profile identifier.
+ * @param {boolean} [options.allowUnmarked=false] Explicit detector opt-in for
+ *   a matrix whose marker was lost during image sampling.
+ * @returns {import('../qr/decoder.js').DecodeResult & {
+ *   format: 'frameqr', profile: string, certified: false,
+ *   frame: object, canvas: object, canvasDamage: object
+ * }}
+ * @throws {FormatError} If the profile marker/canvas is invalid or the input
+ *   is an ordinary QR Code.
+ */
+export function decodeFrameQR(matrix, options = {}) {
+  if (!matrix || !Number.isInteger(matrix.width) || !Number.isInteger(matrix.height)) {
+    throw new FormatError('Sythos Canvas QR: no matrix supplied');
+  }
+  if (matrix.width !== matrix.height) {
+    throw new FormatError(
+      `Sythos Canvas QR: symbol must be square, got ${matrix.width}x${matrix.height}`
+    );
+  }
+
+  const profile = resolveProfile(matrix, options);
+  let decoded;
+  try {
+    decoded = decodeQR(matrix);
+  } catch (error) {
+    // Preserve the original QR/RS error when possible, but give callers a
+    // profile-specific context without exposing implementation details.
+    if (error instanceof FormatError) {
+      throw new FormatError(`Sythos Canvas QR: payload is not recoverable: ${error.message}`);
+    }
+    throw error;
+  }
+
+  return {
+    ...decoded,
+    format: 'frameqr',
+    profile: profile.profile,
+    certified: profile.certified,
+    frame: profile.canvas,
+    canvas: profile.canvas,
+    canvasDamage: profile.damage,
+  };
+}
+
+export { isExpectedProfile };

package/src/frameqr/detector.js

@@ -0,0 +1,192 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Detector for the non-certified Sythos Canvas QR profile.
+ *
+ * The profile deliberately reuses QR Model 2 geometry. Finder localisation and
+ * projective sampling therefore use the QR detector; the additional profile
+ * check is the light canvas signature. A sampled image cannot carry the
+ * encoder's in-memory marker, so the detector reconstructs the expected
+ * metadata, verifies that every reserved canvas module is light, and only then
+ * opts into the profile decoder. This rejects ordinary QR symbols whose centre
+ * merely happens to contain a plausible payload.
+ *
+ * Detection is verified for clean binarized rasters, integer scaling, quiet
+ * zones, and in-plane quarter turns. Arbitrary photographic perspective is not
+ * claimed by this module.
+ *
+ * @module frameqr/detector
+ */
+
+import { NotFoundError } from '../core/errors.js';
+import { sampleQuad } from '../image/grid-sampler.js';
+import { detectQR } from '../qr/detector.js';
+import { decodeFrameQR } from './decoder.js';
+import {
+  FRAMEQR_PROFILE,
+  canvasModules,
+  normalizeCanvasSpec,
+} from './tables.js';
+
+/** @typedef {{x:number, y:number}} Point */
+
+/** @typedef {object} FrameQRDetection
+ * @property {Point[]} corners Outer corners in reading order.
+ * @property {number} dimension QR modules per side.
+ * @property {number} version QR Model 2 version.
+ * @property {number} moduleSize Estimated pixels per module.
+ * @property {number} rotation Clockwise in-plane orientation in degrees.
+ * @property {BitMatrix} matrix Rectified profile matrix.
+ * @property {object} canvas Normalized canvas specification.
+ * @property {string} profile Profile identifier.
+ * @property {false} certified Always false for this implementation.
+ */
+
+function orientationDegrees(corners) {
+  const [tl, tr] = corners;
+  const angle = Math.atan2(tr.y - tl.y, tr.x - tl.x) * 180 / Math.PI;
+  return ((Math.round(angle / 90) * 90) % 360 + 360) % 360;
+}
+/**
+ * Return the number of canvas modules that are dark in a sampled matrix.
+ *
+ * Encoded profile symbols clear the whole reserved canvas. A non-zero count
+ * means either a normal QR symbol or a raster whose canvas was overwritten by
+ * artwork; both are rejected because decoding that image would be speculative.
+ */
+function canvasDarkCount(matrix, canvas) {
+  let dark = 0;
+  for (const [x, y] of canvasModules(matrix.width, canvas)) {
+    if (matrix.get(x, y)) dark++;
+  }
+  return dark;
+}
+
+function sameCandidate(left, right) {
+  if (left.dimension !== right.dimension) return false;
+  const a = left.corners[0];
+  const b = right.corners[0];
+  return Math.hypot(a.x - b.x, a.y - b.y) <= Math.max(left.moduleSize, right.moduleSize) * 2;
+}
+
+/**
+ * Detect Sythos Canvas QR symbols in a binarized raster.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} binaryImage Set bit = dark.
+ * @param {object} [options]
+ * @param {object} [options.canvas] Explicit canvas metadata for non-default
+ *   shapes/size. Without it, the profile's canonical centered square is used.
+ * @param {boolean} [options.voting=false] Use majority sampling per module.
+ * @returns {FrameQRDetection[]} Best candidate first; empty when no verified
+ *   profile signature is found.
+ */
+export function detectFrameQR(binaryImage, options = {}) {
+  if (!binaryImage || !binaryImage.width || !binaryImage.height) {
+    throw new NotFoundError('detectFrameQR: no image supplied');
+  }
+
+  let candidates;
+  try { candidates = detectQR(binaryImage); } catch { return []; }
+  const detections = [];
+
+  for (const candidate of candidates) {
+    // QR detector dimensions are already constrained to legal Model 2 sizes.
+    let canvas;
+    try { canvas = normalizeCanvasSpec(candidate.dimension, options.canvas); }
+    catch { continue; }
+
+    for (const voting of [Boolean(options.voting), !Boolean(options.voting)]) {
+      let matrix;
+      try { matrix = sampleQuad(binaryImage, candidate.dimension, candidate.corners, voting); }
+      catch { continue; }
+
+      // The signature check is intentionally strict. It prevents an ordinary
+      // QR symbol from being relabelled as Canvas QR by the decoder's explicit
+      // allowUnmarked escape hatch.
+      if (canvasDarkCount(matrix, canvas) !== 0) continue;
+
+      const marked = matrix;
+      marked.frameqr = {
+        profile: FRAMEQR_PROFILE.id,
+        certified: false,
+        canvas,
+      };
+      let decoded;
+      try {
+        decoded = decodeFrameQR(marked, {
+          profile: FRAMEQR_PROFILE.id,
+          canvas,
+          allowUnmarked: true,
+        });
+      } catch { continue; }
+
+      const detection = {
+        corners: candidate.corners,
+        dimension: candidate.dimension,
+        version: candidate.version,
+        moduleSize: candidate.moduleSize,
+        rotation: orientationDegrees(candidate.corners),
+        matrix: marked,
+        canvas,
+        profile: FRAMEQR_PROFILE.id,
+        certified: false,
+        result: decoded,
+      };
+      if (!detections.some((entry) => sameCandidate(entry, detection))) detections.push(detection);
+      break;
+    }
+  }
+
+  detections.sort((a, b) => b.moduleSize - a.moduleSize);
+  return detections;
+}
+
+/**
+ * Detect and decode all verified Canvas QR symbols in one call.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} binaryImage
+ * @param {object} [options]
+ * @returns {Array<object>}
+ */
+export function detectAndDecodeFrameQR(binaryImage, options = {}) {
+  let detections;
+  try { detections = detectFrameQR(binaryImage, options); } catch { return []; }
+  const results = [];
+  const seen = new Set();
+  for (const detection of detections) {
+    const result = detection.result;
+    const key = `${result.version}|${result.text}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    results.push({ ...result, corners: detection.corners, rotation: detection.rotation });
+  }
+  return results;
+}