@scanly/core 2.0.0

package/README.md

@@ -0,0 +1,3 @@
+# @scanly/core
+
+Framework-independent SDK v2 preview contracts, bounded capture router, deterministic session lifecycle, and the migrated QR pipeline. It has no React or Next.js dependency. The default QR path currently supports QR Code Model 2 through jsQR and ZXing JavaScript; other format identifiers are capability vocabulary, not support claims.

package/dist/barcode/contracts.d.ts

@@ -0,0 +1,44 @@
+import type { BarcodeFormat, BarcodeFormatClass } from "@scanly/scenario-schema";
+import type { CornerPoint, ScanResult } from "../contracts/result.js";
+import type { RetailBarcodeMetadata } from "./retail.js";
+export interface Gs1Metadata {
+    applicationIdentifiers: readonly string[];
+    rawFnc1?: boolean;
+    parseWarnings?: readonly string[];
+}
+export interface BarcodeMetadata {
+    retail?: RetailBarcodeMetadata;
+    gs1?: Gs1Metadata;
+    [key: string]: unknown;
+}
+export interface StructuredAppendMetadata {
+    index: number;
+    total: number;
+    parity?: number;
+}
+export interface DecodedBarcode {
+    text: string;
+    rawBytes?: Uint8Array;
+    format: BarcodeFormat;
+    formatClass: BarcodeFormatClass;
+    symbologyIdentifier?: string;
+    isGs1?: boolean;
+    cornerPoints?: readonly CornerPoint[];
+    orientation?: number;
+    engineId: string;
+    engineVersion?: string;
+    engineMetadata?: Record<string, unknown>;
+    structuredAppend?: StructuredAppendMetadata;
+    metadata?: BarcodeMetadata;
+}
+export declare class UnsupportedBarcodeFormatError extends Error {
+    readonly code: "unsupported_format";
+    constructor(message: string);
+}
+export declare class InvalidBarcodeChecksumError extends Error {
+    readonly code: "invalid_barcode_checksum";
+    constructor(message: string);
+}
+/** Convert the legacy Alpha.4 result shape to the generic Alpha.5 contract. */
+export declare function toDecodedBarcode(result: ScanResult): DecodedBarcode;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/barcode/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/barcode/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD,MAAM,WAAW,WAAW;IAC1B,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,EAAE,kBAAkB,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,IAAI,EAAG,0BAA0B,CAAU;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAenE"}

package/dist/barcode/contracts.js

@@ -0,0 +1,33 @@
+import { barcodeFormatClass } from "./format.js";
+export class UnsupportedBarcodeFormatError extends Error {
+    code = "unsupported_format";
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedBarcodeFormatError";
+    }
+}
+export class InvalidBarcodeChecksumError extends Error {
+    code = "invalid_barcode_checksum";
+    constructor(message) {
+        super(message);
+        this.name = "InvalidBarcodeChecksumError";
+    }
+}
+/** Convert the legacy Alpha.4 result shape to the generic Alpha.5 contract. */
+export function toDecodedBarcode(result) {
+    return {
+        text: result.rawText,
+        ...(result.rawBytes ? { rawBytes: result.rawBytes } : {}),
+        format: result.format,
+        formatClass: result.formatClass ?? barcodeFormatClass(result.format),
+        ...(result.symbologyIdentifier ? { symbologyIdentifier: result.symbologyIdentifier } : {}),
+        ...(result.isGs1 !== undefined ? { isGs1: result.isGs1 } : {}),
+        ...(result.cornerPoints ? { cornerPoints: result.cornerPoints } : {}),
+        ...(result.orientation !== undefined ? { orientation: result.orientation } : {}),
+        engineId: result.engine.id,
+        engineVersion: result.engine.version,
+        engineMetadata: result.engine,
+        ...(result.metadata ? { metadata: result.metadata } : {}),
+    };
+}
+//# sourceMappingURL=contracts.js.map

package/dist/barcode/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/barcode/contracts.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAoCjD,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IAC7C,IAAI,GAAG,oBAA6B,CAAC;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAC3C,IAAI,GAAG,0BAAmC,CAAC;IACpD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,OAAO;QACpB,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC;QACpE,GAAG,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,MAAM,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1F,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,GAAG,CAAC,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE;QAC1B,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO;QACpC,cAAc,EAAE,MAAM,CAAC,MAAM;QAC7B,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1D,CAAC;AACJ,CAAC"}

package/dist/barcode/format-selection.d.ts

@@ -0,0 +1,12 @@
+import type { BarcodeFormat } from "@scanly/scenario-schema";
+export interface FormatSelection {
+    formats: readonly BarcodeFormat[];
+    strict?: boolean;
+}
+export interface NormalizedFormatSelection {
+    readonly formats: readonly BarcodeFormat[];
+    readonly strict: boolean;
+}
+export declare function normalizeFormatSelection(selection?: FormatSelection | readonly BarcodeFormat[]): NormalizedFormatSelection;
+export declare function assertFormatsSupported(requested: readonly BarcodeFormat[], supported: readonly BarcodeFormat[], engineId: string): void;
+//# sourceMappingURL=format-selection.d.ts.map

package/dist/barcode/format-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-selection.d.ts","sourceRoot":"","sources":["../../src/barcode/format-selection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAID,wBAAgB,wBAAwB,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,SAAS,aAAa,EAAE,GAAG,yBAAyB,CAqB1H;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,EAAE,SAAS,EAAE,SAAS,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAKvI"}

package/dist/barcode/format-selection.js

@@ -0,0 +1,32 @@
+import { SdkException, sdkError } from "../contracts/errors.js";
+import { isPublicBarcodeFormat, PUBLIC_BARCODE_FORMATS } from "./format.js";
+const MAX_REQUESTED_FORMATS = PUBLIC_BARCODE_FORMATS.length;
+export function normalizeFormatSelection(selection) {
+    const formats = Array.isArray(selection) ? selection : selection?.formats;
+    const strict = Array.isArray(selection) || !selection ? true : selection.strict ?? true;
+    if (!formats || formats.length === 0) {
+        throw new SdkException(sdkError("unsupported_format", "At least one barcode format must be requested."));
+    }
+    const unique = [];
+    const seen = new Set();
+    for (const format of formats) {
+        if (!isPublicBarcodeFormat(format)) {
+            throw new SdkException(sdkError("unsupported_format", `Unsupported barcode format '${String(format)}'.`, { format: String(format) }));
+        }
+        if (!seen.has(format)) {
+            seen.add(format);
+            unique.push(format);
+        }
+    }
+    if (unique.length > MAX_REQUESTED_FORMATS) {
+        throw new SdkException(sdkError("resource_limit_exceeded", `At most ${MAX_REQUESTED_FORMATS} barcode formats may be requested.`));
+    }
+    return Object.freeze({ formats: Object.freeze(unique), strict });
+}
+export function assertFormatsSupported(requested, supported, engineId) {
+    const missing = requested.filter((format) => !supported.includes(format));
+    if (missing.length) {
+        throw new SdkException(sdkError("unsupported_format", `Engine '${engineId}' does not support: ${missing.join(", ")}.`, { engineId, formats: missing.join(",") }));
+    }
+}
+//# sourceMappingURL=format-selection.js.map

package/dist/barcode/format-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-selection.js","sourceRoot":"","sources":["../../src/barcode/format-selection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAY5E,MAAM,qBAAqB,GAAG,sBAAsB,CAAC,MAAM,CAAC;AAE5D,MAAM,UAAU,wBAAwB,CAAC,SAAsD;IAC7F,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,SAAyC,EAAE,OAAO,CAAC;IAC3G,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,SAA6B,CAAC,MAAM,IAAI,IAAI,CAAC;IAC7G,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,YAAY,CAAC,QAAQ,CAAC,oBAAoB,EAAE,gDAAgD,CAAC,CAAC,CAAC;IAC3G,CAAC;IACD,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,YAAY,CAAC,QAAQ,CAAC,oBAAoB,EAAE,+BAA+B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QACxI,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACjB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,GAAG,qBAAqB,EAAE,CAAC;QAC1C,MAAM,IAAI,YAAY,CAAC,QAAQ,CAAC,yBAAyB,EAAE,WAAW,qBAAqB,oCAAoC,CAAC,CAAC,CAAC;IACpI,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,SAAmC,EAAE,SAAmC,EAAE,QAAgB;IAC/H,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1E,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,YAAY,CAAC,QAAQ,CAAC,oBAAoB,EAAE,WAAW,QAAQ,uBAAuB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACpK,CAAC;AACH,CAAC"}

package/dist/barcode/format.d.ts

@@ -0,0 +1,7 @@
+import type { BarcodeFormat, BarcodeFormatClass } from "@scanly/scenario-schema";
+export type { BarcodeFormat, BarcodeFormatClass } from "@scanly/scenario-schema";
+export declare const PUBLIC_BARCODE_FORMATS: readonly BarcodeFormat[];
+export declare const BARCODE_FORMAT_CLASS: Readonly<Record<BarcodeFormat, BarcodeFormatClass>>;
+export declare function barcodeFormatClass(format: BarcodeFormat): BarcodeFormatClass;
+export declare function isPublicBarcodeFormat(value: unknown): value is BarcodeFormat;
+//# sourceMappingURL=format.d.ts.map

package/dist/barcode/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/barcode/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAEjF,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAEjF,eAAO,MAAM,sBAAsB,EAAE,SAAS,aAAa,EAEzD,CAAC;AAEH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,kBAAkB,CAAC,CASnF,CAAC;AAEH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,kBAAkB,CAE5E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAE5E"}

package/dist/barcode/format.js

@@ -0,0 +1,20 @@
+export const PUBLIC_BARCODE_FORMATS = Object.freeze([
+    "qr_code", "data_matrix", "pdf417", "code_128", "ean_13", "ean_8", "upc_a", "upc_e",
+]);
+export const BARCODE_FORMAT_CLASS = Object.freeze({
+    qr_code: "matrix",
+    data_matrix: "matrix",
+    pdf417: "stacked",
+    code_128: "linear",
+    ean_13: "linear",
+    ean_8: "linear",
+    upc_a: "linear",
+    upc_e: "linear",
+});
+export function barcodeFormatClass(format) {
+    return BARCODE_FORMAT_CLASS[format];
+}
+export function isPublicBarcodeFormat(value) {
+    return typeof value === "string" && PUBLIC_BARCODE_FORMATS.includes(value);
+}
+//# sourceMappingURL=format.js.map

package/dist/barcode/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/barcode/format.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,sBAAsB,GAA6B,MAAM,CAAC,MAAM,CAAC;IAC5E,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;CACpF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAwD,MAAM,CAAC,MAAM,CAAC;IACrG,OAAO,EAAE,QAAQ;IACjB,WAAW,EAAE,QAAQ;IACrB,MAAM,EAAE,SAAS;IACjB,QAAQ,EAAE,QAAQ;IAClB,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,QAAQ;IACf,KAAK,EAAE,QAAQ;IACf,KAAK,EAAE,QAAQ;CAChB,CAAC,CAAC;AAEH,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,sBAA4C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACpG,CAAC"}

package/dist/barcode/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./format.js";
+export * from "./format-selection.js";
+export * from "./contracts.js";
+export * from "./retail.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/barcode/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/barcode/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/barcode/index.js

@@ -0,0 +1,5 @@
+export * from "./format.js";
+export * from "./format-selection.js";
+export * from "./contracts.js";
+export * from "./retail.js";
+//# sourceMappingURL=index.js.map

package/dist/barcode/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/barcode/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/barcode/retail.d.ts

@@ -0,0 +1,16 @@
+import type { BarcodeFormat } from "@scanly/scenario-schema";
+export interface RetailBarcodeMetadata {
+    gtin?: string;
+    checkDigitValid: boolean;
+    normalizedGtin14?: string;
+    expandedUpcA?: string;
+}
+/** Restore the public UPC representation emitted by the physical symbol. */
+export declare function canonicalizeRetailText(format: BarcodeFormat, value: string): string;
+export declare function isValidRetailChecksum(value: string): boolean;
+export declare function normalizeRetailBarcode(format: BarcodeFormat, value: string): RetailBarcodeMetadata | null;
+/** Expand a valid number-system-0 UPC-E payload without replacing the original text. */
+export declare function expandUpcE(value: string): string | null;
+/** Compress UPC-A only when an exact, checksum-valid UPC-E round trip exists. */
+export declare function compressUpcA(value: string): string | null;
+//# sourceMappingURL=retail.d.ts.map

package/dist/barcode/retail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retail.d.ts","sourceRoot":"","sources":["../../src/barcode/retail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAUnF;AAMD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAQ5D;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAmBzG;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwBvD;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAczD"}

package/dist/barcode/retail.js

@@ -0,0 +1,95 @@
+/** Restore the public UPC representation emitted by the physical symbol. */
+export function canonicalizeRetailText(format, value) {
+    if (format === "upc_a" && validDigits(value, 13) && value.startsWith("0")) {
+        const upcA = value.slice(1);
+        return isValidRetailChecksum(upcA) ? upcA : value;
+    }
+    if (format === "upc_e") {
+        const upcA = validDigits(value, 13) && value.startsWith("0") ? value.slice(1) : value;
+        return compressUpcA(upcA) ?? value;
+    }
+    return value;
+}
+function validDigits(value, length) {
+    return new RegExp(`^\\d{${length}}$`).test(value);
+}
+export function isValidRetailChecksum(value) {
+    if (!/^\d+$/.test(value) || value.length < 2)
+        return false;
+    let sum = 0;
+    const check = Number(value[value.length - 1]);
+    for (let index = value.length - 2, position = 0; index >= 0; index -= 1, position += 1) {
+        sum += Number(value[index]) * (position % 2 === 0 ? 3 : 1);
+    }
+    return (10 - (sum % 10)) % 10 === check;
+}
+export function normalizeRetailBarcode(format, value) {
+    if (format === "ean_13" && validDigits(value, 13)) {
+        const valid = isValidRetailChecksum(value);
+        return { gtin: value, checkDigitValid: valid, normalizedGtin14: `0${value}` };
+    }
+    if (format === "ean_8" && validDigits(value, 8)) {
+        const valid = isValidRetailChecksum(value);
+        return { gtin: value, checkDigitValid: valid, normalizedGtin14: `000000${value}` };
+    }
+    if (format === "upc_a" && validDigits(value, 12)) {
+        const valid = isValidRetailChecksum(value);
+        return { gtin: value, checkDigitValid: valid, normalizedGtin14: `00${value}` };
+    }
+    if (format === "upc_e" && validDigits(value, 8)) {
+        const expandedUpcA = expandUpcE(value) ?? undefined;
+        const valid = Boolean(expandedUpcA);
+        return { gtin: value, checkDigitValid: valid, ...(expandedUpcA ? { normalizedGtin14: `00${expandedUpcA}` } : {}), ...(expandedUpcA ? { expandedUpcA } : {}) };
+    }
+    return null;
+}
+/** Expand a valid number-system-0 UPC-E payload without replacing the original text. */
+export function expandUpcE(value) {
+    if (!validDigits(value, 8))
+        return null;
+    const numberSystem = value[0];
+    if (numberSystem !== "0" && numberSystem !== "1")
+        return null;
+    const body = value.slice(1, 7);
+    const check = value[7];
+    const last = body[5];
+    let manufacturer;
+    let product;
+    if ("012".includes(last)) {
+        manufacturer = `${body.slice(0, 2)}${last}00`;
+        product = `00${body.slice(2, 5)}`;
+    }
+    else if (last === "3") {
+        manufacturer = `${body.slice(0, 3)}00`;
+        product = `000${body.slice(3, 5)}`;
+    }
+    else if (last === "4") {
+        manufacturer = `${body.slice(0, 4)}0`;
+        product = `0000${body[4]}`;
+    }
+    else {
+        manufacturer = body.slice(0, 5);
+        product = `0000${last}`;
+    }
+    const upc = `${numberSystem}${manufacturer}${product}${check}`;
+    return validDigits(upc, 12) && isValidRetailChecksum(upc) ? upc : null;
+}
+/** Compress UPC-A only when an exact, checksum-valid UPC-E round trip exists. */
+export function compressUpcA(value) {
+    if (!validDigits(value, 12) || !isValidRetailChecksum(value))
+        return null;
+    const numberSystem = value[0];
+    if (numberSystem !== "0" && numberSystem !== "1")
+        return null;
+    const manufacturer = value.slice(1, 6);
+    const product = value.slice(6, 11);
+    const check = value[11];
+    const candidates = [
+        `${numberSystem}${manufacturer.slice(0, 2)}${product.slice(2)}${manufacturer[2]}${check}`,
+        `${numberSystem}${manufacturer.slice(0, 3)}${product.slice(3)}3${check}`,
+        `${numberSystem}${manufacturer.slice(0, 4)}${product[4]}4${check}`,
+        `${numberSystem}${manufacturer}${product[4]}${check}`,
+    ];
+    return candidates.find((candidate) => expandUpcE(candidate) === value) ?? null;
+}
+//# sourceMappingURL=retail.js.map

package/dist/barcode/retail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retail.js","sourceRoot":"","sources":["../../src/barcode/retail.ts"],"names":[],"mappings":"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"}

package/dist/contracts/engine.d.ts

@@ -0,0 +1,84 @@
+import type { BarcodeFormat, BarcodeFormatClass } from "@scanly/scenario-schema";
+import type { NormalizedFrame } from "./frame.js";
+import type { CornerPoint } from "./result.js";
+export interface EngineCapabilities {
+    formats: readonly BarcodeFormat[];
+    formatClasses?: readonly BarcodeFormatClass[];
+    supportsMultiple: boolean;
+    returnsRawBytes: boolean;
+    /** Alpha.5 spelling retained alongside the Alpha.4 returnsRawBytes field. */
+    supportsRawBytes?: boolean;
+    returnsCornerPoints: boolean;
+    threadSafe: boolean;
+    estimatedScratchBytesPerPixel?: number;
+    copiesInputBuffer?: boolean;
+    runtimeKinds?: readonly ("browser" | "worker" | "node")[];
+    supportsInversion?: boolean;
+    supportsStructuredAppend?: boolean;
+    supportsGs1?: boolean;
+    supportsOrientation?: boolean;
+    initializationMode?: "lazy" | "explicit";
+    executionModel?: "javascript" | "wasm" | "native";
+}
+export type EngineFailureCategory = "not-found" | "unsupported-format" | "invalid-input" | "initialization" | "execution" | "cancelled" | "timeout";
+export type EngineFailureCode = "asset_not_found" | "asset_integrity_failed" | "wasm_compile_failed" | "wasm_instantiate_failed" | "unsupported_runtime" | "unsupported_simd" | "initialization_timeout" | "native_decode_failed" | "invalid_native_result" | "out_of_memory" | "cancelled" | "disposed";
+export interface EngineExecutionMetadata {
+    variant?: string;
+    executionModel?: "javascript" | "wasm" | "native";
+    initializationMs?: number;
+    wasmLinearMemoryBytes?: number;
+    requestedFormats?: readonly BarcodeFormat[];
+    nativeFormat?: string;
+    detectedFormat?: BarcodeFormat;
+}
+export interface EngineDecodeResult {
+    text: string;
+    rawBytes?: Uint8Array;
+    format: BarcodeFormat;
+    cornerPoints?: CornerPoint[];
+    orientation?: number;
+    symbologyIdentifier?: string;
+    isGs1?: boolean;
+    metadata?: Record<string, unknown>;
+    engineMetadata?: EngineExecutionMetadata;
+    elapsedMs: number;
+}
+export type EngineOutcome = {
+    ok: true;
+    results: [EngineDecodeResult, ...EngineDecodeResult[]];
+} | {
+    ok: false;
+    category: EngineFailureCategory;
+    message: string;
+    elapsedMs: number;
+    code?: EngineFailureCode;
+};
+export interface EngineDecodeOptions {
+    formats: readonly BarcodeFormat[];
+    findMultiple: boolean;
+    signal?: AbortSignal;
+    /** Whether upstream preprocessing already inverted the candidate. */
+    inversion?: "unknown" | "original" | "inverted";
+}
+export interface DecoderEngine {
+    readonly id: string;
+    readonly version: string;
+    readonly capabilities: EngineCapabilities;
+    initialize?(): Promise<void>;
+    decode(frame: NormalizedFrame, options: EngineDecodeOptions): Promise<EngineOutcome>;
+    dispose?(): void | Promise<void>;
+}
+export interface EngineRegistrationOptions {
+    /** Duplicate ids are rejected unless replacement is explicit. */
+    replace?: boolean;
+}
+export interface EngineRegistryContract {
+    register(engine: DecoderEngine, options?: EngineRegistrationOptions): void;
+    unregister(id: string): void;
+    get(id: string): DecoderEngine | undefined;
+    list(): readonly DecoderEngine[];
+    resolve(formats: readonly BarcodeFormat[]): readonly DecoderEngine[];
+    initializeAll(): Promise<void>;
+    disposeAll(): Promise<void>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/contracts/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/contracts/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,aAAa,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC9C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,UAAU,EAAE,OAAO,CAAC;IACpB,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,YAAY,CAAC,EAAE,SAAS,CAAC,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IACzC,cAAc,CAAC,EAAE,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;CACnD;AACD,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,oBAAoB,GAAG,eAAe,GAAG,gBAAgB,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;AACpJ,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GAAG,wBAAwB,GAAG,qBAAqB,GAAG,yBAAyB,GAChG,qBAAqB,GAAG,kBAAkB,GAAG,wBAAwB,GAAG,sBAAsB,GAC9F,uBAAuB,GAAG,eAAe,GAAG,WAAW,GAAG,UAAU,CAAC;AACzE,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gBAAgB,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,aAAa,CAAC;CAChC;AACD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,MAAM,EAAE,aAAa,CAAC;IACtB,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,cAAc,CAAC,EAAE,uBAAuB,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,CAAC,kBAAkB,EAAE,GAAG,kBAAkB,EAAE,CAAC,CAAA;CAAE,GACpE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,qBAAqB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,iBAAiB,CAAA;CAAE,CAAC;AACjH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qEAAqE;IACrE,SAAS,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;CACjD;AACD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACrF,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC3E,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAC3C,IAAI,IAAI,SAAS,aAAa,EAAE,CAAC;IACjC,OAAO,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,aAAa,EAAE,CAAC;IACrE,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B"}

package/dist/contracts/engine.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=engine.js.map

package/dist/contracts/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/contracts/engine.ts"],"names":[],"mappings":""}

package/dist/contracts/errors.d.ts

@@ -0,0 +1,17 @@
+export declare const SDK_ERROR_CODES: readonly ["no_symbol_found", "unsupported_format", "invalid_image", "resource_limit_exceeded", "timeout", "cancelled", "worker_initialization_failure", "engine_initialization_failure", "engine_execution_failure", "camera_permission_denied", "camera_not_found", "camera_busy", "camera_constraint_failed", "camera_track_ended", "camera_capability_unsupported", "camera_recovery_failed", "browser_background_suspended", "camera_unavailable", "source_disconnected", "unsupported_browser_capability", "malformed_scenario", "invalid_configuration", "internal_invariant_failure", "session_not_running", "session_disposed", "concurrent_call_rejected"];
+export type SdkErrorCode = (typeof SDK_ERROR_CODES)[number];
+export type SdkErrorCategory = "input" | "resource" | "lifecycle" | "engine" | "source" | "configuration" | "internal";
+export interface SdkError {
+    code: SdkErrorCode;
+    category: SdkErrorCategory;
+    message: string;
+    retryable: boolean;
+    details?: Readonly<Record<string, string | number | boolean | null>>;
+    cause?: unknown;
+}
+export declare class SdkException extends Error {
+    readonly error: SdkError;
+    constructor(error: SdkError);
+}
+export declare function sdkError(code: SdkErrorCode, message: string, details?: SdkError["details"], cause?: unknown): SdkError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/contracts/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/contracts/errors.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,qoBAQlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,GAAG,UAAU,CAAC;AAEvH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC;IACrE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;gBACb,KAAK,EAAE,QAAQ;CAK5B;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,CAatH"}

package/dist/contracts/errors.js

@@ -0,0 +1,31 @@
+export const SDK_ERROR_CODES = [
+    "no_symbol_found", "unsupported_format", "invalid_image", "resource_limit_exceeded", "timeout",
+    "cancelled", "worker_initialization_failure", "engine_initialization_failure", "engine_execution_failure",
+    "camera_permission_denied", "camera_not_found", "camera_busy", "camera_constraint_failed",
+    "camera_track_ended", "camera_capability_unsupported", "camera_recovery_failed",
+    "browser_background_suspended", "camera_unavailable", "source_disconnected", "unsupported_browser_capability",
+    "malformed_scenario", "invalid_configuration", "internal_invariant_failure", "session_not_running",
+    "session_disposed", "concurrent_call_rejected",
+];
+export class SdkException extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.name = "SdkException";
+        this.error = error;
+    }
+}
+export function sdkError(code, message, details, cause) {
+    const category = code === "invalid_image" || code === "unsupported_format" || code === "no_symbol_found" ? "input" :
+        code === "resource_limit_exceeded" || code === "timeout" ? "resource" :
+            code.includes("engine") || code.includes("worker") ? "engine" :
+                code.includes("camera") || code === "source_disconnected" || code === "unsupported_browser_capability" ? "source" :
+                    code.includes("scenario") || code === "invalid_configuration" ? "configuration" :
+                        code === "internal_invariant_failure" ? "internal" : "lifecycle";
+    const retryable = ![
+        "unsupported_format", "malformed_scenario", "invalid_configuration", "session_disposed",
+        "camera_permission_denied", "camera_not_found", "camera_capability_unsupported", "unsupported_browser_capability",
+    ].includes(code);
+    return { code, category, message, retryable, details, ...(cause === undefined ? {} : { cause }) };
+}
+//# sourceMappingURL=errors.js.map

package/dist/contracts/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/contracts/errors.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,EAAE,yBAAyB,EAAE,SAAS;IAC9F,WAAW,EAAE,+BAA+B,EAAE,+BAA+B,EAAE,0BAA0B;IACzG,0BAA0B,EAAE,kBAAkB,EAAE,aAAa,EAAE,0BAA0B;IACzF,oBAAoB,EAAE,+BAA+B,EAAE,wBAAwB;IAC/E,8BAA8B,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,gCAAgC;IAC7G,oBAAoB,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,qBAAqB;IAClG,kBAAkB,EAAE,0BAA0B;CACtC,CAAC;AAcX,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,KAAK,CAAW;IACzB,YAAY,KAAe;QACzB,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,MAAM,UAAU,QAAQ,CAAC,IAAkB,EAAE,OAAe,EAAE,OAA6B,EAAE,KAAe;IAC1G,MAAM,QAAQ,GACZ,IAAI,KAAK,eAAe,IAAI,IAAI,KAAK,oBAAoB,IAAI,IAAI,KAAK,iBAAiB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACnG,IAAI,KAAK,yBAAyB,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;YACvE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;gBAC/D,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,KAAK,qBAAqB,IAAI,IAAI,KAAK,gCAAgC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;oBACnH,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,IAAI,KAAK,uBAAuB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;wBACjF,IAAI,KAAK,4BAA4B,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;IACnE,MAAM,SAAS,GAAG,CAAC;QACjB,oBAAoB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,kBAAkB;QACvF,0BAA0B,EAAE,kBAAkB,EAAE,+BAA+B,EAAE,gCAAgC;KAClH,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AACpG,CAAC"}

package/dist/contracts/frame.d.ts

@@ -0,0 +1,37 @@
+export type FramePixelFormat = "rgba8888" | "rgb888" | "gray8" | "yuv420";
+export type FrameSourceType = "camera" | "upload" | "pixel-buffer" | "video-frame" | "hardware-scanner";
+export type FrameBufferOwnership = "borrowed" | "transferred" | "owned";
+export type FrameOrientation = 0 | 90 | 180 | 270;
+export interface FrameDeviceMetadata {
+    deviceId?: string;
+    label?: string;
+    facingMode?: "user" | "environment" | "left" | "right";
+    platform?: string;
+    torchActive?: boolean;
+    zoom?: number;
+    hardwareScannerId?: string;
+    [key: string]: string | number | boolean | undefined;
+}
+export interface NormalizedFrame {
+    id: string;
+    timestampMs: number;
+    width: number;
+    height: number;
+    rowStride: number;
+    pixelFormat: FramePixelFormat;
+    /** Clockwise rotation required to display source-buffer pixels upright. */
+    orientation: FrameOrientation;
+    sourceType: FrameSourceType;
+    data: Uint8Array | Uint8ClampedArray;
+    ownership: FrameBufferOwnership;
+    device?: FrameDeviceMetadata;
+    dispose?: () => void;
+}
+export interface FrameValidationIssue {
+    path: string;
+    message: string;
+}
+export declare function bytesPerPixel(format: FramePixelFormat): number | null;
+export declare function validateFrame(frame: unknown): FrameValidationIssue[];
+export declare function createRgbaFrame(data: Uint8ClampedArray, width: number, height: number, options?: Partial<Omit<NormalizedFrame, "data" | "width" | "height" | "pixelFormat" | "rowStride">>): NormalizedFrame;
+//# sourceMappingURL=frame.d.ts.map

package/dist/contracts/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/contracts/frame.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAC1E,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,GAAG,cAAc,GAAG,aAAa,GAAG,kBAAkB,CAAC;AACxG,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,aAAa,GAAG,OAAO,CAAC;AACxE,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,MAAM,GAAG,OAAO,CAAC;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACtD;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,2EAA2E;IAC3E,WAAW,EAAE,gBAAgB,CAAC;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,IAAI,EAAE,UAAU,GAAG,iBAAiB,CAAC;IACrC,SAAS,EAAE,oBAAoB,CAAC;IAChC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAKrE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,EAAE,CAsCpE;AAID,wBAAgB,eAAe,CAC7B,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,CAAC,CAAM,GACtG,eAAe,CAejB"}

package/dist/contracts/frame.js

@@ -0,0 +1,77 @@
+export function bytesPerPixel(format) {
+    if (format === "rgba8888")
+        return 4;
+    if (format === "rgb888")
+        return 3;
+    if (format === "gray8")
+        return 1;
+    return null;
+}
+export function validateFrame(frame) {
+    const issues = [];
+    if (!frame || typeof frame !== "object" || Array.isArray(frame)) {
+        return [{ path: "$", message: "Frame must be an object." }];
+    }
+    const value = frame;
+    if (typeof value.id !== "string" || value.id.length === 0)
+        issues.push({ path: "id", message: "Frame id is required." });
+    if (typeof value.timestampMs !== "number" || !Number.isFinite(value.timestampMs) || value.timestampMs < 0)
+        issues.push({ path: "timestampMs", message: "Timestamp must be a non-negative finite number." });
+    if (!Number.isSafeInteger(value.width) || (value.width ?? 0) < 1)
+        issues.push({ path: "width", message: "Width must be a positive safe integer." });
+    if (!Number.isSafeInteger(value.height) || (value.height ?? 0) < 1)
+        issues.push({ path: "height", message: "Height must be a positive safe integer." });
+    const pixelFormats = ["rgba8888", "rgb888", "gray8", "yuv420"];
+    const validPixelFormat = pixelFormats.includes(value.pixelFormat);
+    if (!validPixelFormat)
+        issues.push({ path: "pixelFormat", message: "Pixel format must be rgba8888, rgb888, gray8, or yuv420." });
+    if (![0, 90, 180, 270].includes(value.orientation))
+        issues.push({ path: "orientation", message: "Orientation must be 0, 90, 180, or 270." });
+    const sourceTypes = ["camera", "upload", "pixel-buffer", "video-frame", "hardware-scanner"];
+    if (!sourceTypes.includes(value.sourceType))
+        issues.push({ path: "sourceType", message: "Frame source type is invalid." });
+    const ownershipValues = ["borrowed", "transferred", "owned"];
+    if (!ownershipValues.includes(value.ownership))
+        issues.push({ path: "ownership", message: "Frame ownership must be borrowed, transferred, or owned." });
+    const validData = value.data instanceof Uint8Array || value.data instanceof Uint8ClampedArray;
+    const data = validData ? value.data : null;
+    if (!validData)
+        issues.push({ path: "data", message: "Frame data must be a Uint8Array or Uint8ClampedArray." });
+    if (value.dispose !== undefined && typeof value.dispose !== "function")
+        issues.push({ path: "dispose", message: "Frame dispose must be a function when provided." });
+    if (validPixelFormat && Number.isSafeInteger(value.width) && (value.width ?? 0) > 0 && Number.isSafeInteger(value.height) && (value.height ?? 0) > 0) {
+        const bpp = bytesPerPixel(value.pixelFormat);
+        const minimumStride = value.width * (bpp ?? 1);
+        if (!Number.isSafeInteger(value.rowStride) || (value.rowStride ?? 0) < minimumStride) {
+            issues.push({ path: "rowStride", message: `Row stride must be at least ${minimumStride} bytes for ${value.pixelFormat}.` });
+        }
+        else if (data) {
+            const requiredBytes = value.rowStride * value.height;
+            if (!Number.isSafeInteger(requiredBytes)) {
+                issues.push({ path: "data", message: "Frame dimensions and stride exceed the safe buffer-size range." });
+            }
+            else if (data.byteLength < requiredBytes) {
+                issues.push({ path: "data", message: `Frame buffer has ${data.byteLength} bytes; ${requiredBytes} are required by dimensions and stride.` });
+            }
+        }
+    }
+    return issues;
+}
+let frameSequence = 0;
+export function createRgbaFrame(data, width, height, options = {}) {
+    return {
+        id: options.id ?? `frame-${Date.now()}-${++frameSequence}`,
+        timestampMs: options.timestampMs ?? Date.now(),
+        width,
+        height,
+        rowStride: width * 4,
+        pixelFormat: "rgba8888",
+        orientation: options.orientation ?? 0,
+        sourceType: options.sourceType ?? "pixel-buffer",
+        data,
+        ownership: options.ownership ?? "borrowed",
+        device: options.device,
+        dispose: options.dispose,
+    };
+}
+//# sourceMappingURL=frame.js.map