Skip to content

Releases

MCP adapter 0.3.1

Choose a tag to compare

@ThibautMelen ThibautMelen released this 12 Nov 11:36
365585f

MCP adapter 0.3.1 scans QR codes and barcodes from image bytes or files in directories explicitly allowed by the operator. It uses the published 0.11.0 scanner engine, preserving decoded payload bytes and the engine's JSON report.

QR codes Barcodes
Try the scanner live QR code scanner Barcode scanner
MCP server guide QR code scanner MCP server Barcode scanner MCP server
Create a code QR code generator Barcode generator

Install

npm install --prefix ./qrscan-mcp-install --save-exact --ignore-scripts @qrcode-ai-com/qrcode-barcode-scanner-mcp@0.3.1

See the versioned README for client configuration, operator limits and the two tools:

  • scan_image reads supplied image bytes.
  • scan_file reads a file only inside operator-allowed directories. It is off by default.

Use Node.js 22.19+ on the 22 line, or 24+. The npm version is public. The adapter's version is independent of the engine's version.

Verification

The tag workflow qualified the archive, published it through GitHub Trusted Publishing, compared the public npm bytes with that archive, and installed the public version in clean Node 22.22.2 and 24.22.2 consumers on Linux x64. Modern and legacy official MCP SDK clients passed mixed QR/Code 128 scans in fast, frame and full, binary payload checks and file-access refusal checks. Product-client acceptance and additional hosts have their own checks.

  • Source commit: 365585f9db955fd41a6101a3240c4f63436434a3.
  • npm archive SHA-256: 705b3223f6049024fd74ce2a41377b2586774304a9dab13b6619d19b1059308e.
  • The attached archive is the same bytes served by npm. SHA256SUMS covers the archive and the two JSON receipts attached here.
  • The publication receipt records the exercised OIDC upload and public provenance metadata. Its presence alone is not cryptographic attestation verification.

Installing the archive still downloads its declared dependencies from npm, including scanner engine 0.11.0. The checksum file shares this release's trust and detects damaged downloads; it does not independently authenticate the release.

The Official MCP Registry listing, public skills and client bundles retain their own versions and publication checks. This release publishes the npm MCP adapter only. The frozen 0.3.0 tag was superseded before npm publication; no 0.3.0 npm version was uploaded.

AppImage of QR Code & Barcode Scanner 0.11.0

Choose a tag to compare

@ThibautMelen ThibautMelen released this 11 Nov 03:26
7e17064

Run the QR Code AI command-line scanner on GNU/Linux from one file, with nothing to install. qrscan reads QR codes and barcodes from local images and writes JSON reports.

QR codes Barcodes
Try the scanner live QR code scanner Barcode scanner
Command line guide QR code scanner for the command line Barcode scanner for the command line
Create a code QR code generator Barcode generator
Architecture File
x86_64 qrcode-barcode-scanner-0.11.0-x86_64.AppImage
ARM64 qrcode-barcode-scanner-0.11.0-aarch64.AppImage

Download the file for your architecture and the checksum list to the same directory. The files are unsigned, so check the download against the list:

sha256sum --check --ignore-missing qrcode-barcode-scanner-appimage-0.11.0-SHA256SUMS
chmod +x "qrcode-barcode-scanner-0.11.0-$(uname -m).AppImage"
"./qrcode-barcode-scanner-0.11.0-$(uname -m).AppImage" --version
"./qrcode-barcode-scanner-0.11.0-$(uname -m).AppImage" label.png --profile full

The file mounts itself through FUSE. On a host without FUSE, such as most containers, it unpacks itself and runs:

APPIMAGE_EXTRACT_AND_RUN=1 "./qrcode-barcode-scanner-0.11.0-$(uname -m).AppImage" --version

To remove it, delete the file.

Both files contain the unmodified qrscan 0.11.0 executable, with its licences, notices and the pointer to its source. They need the GNU C library 2.28 or later. The recipe builds the same two files from the same inputs: three builds on three commits gave these checksums.

The workflow that built them judged each file on an Ubuntu 22.04 runner and, with no network, on AlmaLinux 8, Ubuntu 22.04 and Fedora containers: the mixed sample returned its QR code and its Code 128 in the fast, frame and full profiles (run). In the containers the files ran through the unpack route.

The scanner is licensed under AGPL-3.0-or-later. The corresponding source archive is attached to the engine release.

Fedora RPM packages for QR Code & Barcode Scanner 0.11.0

Choose a tag to compare

@ThibautMelen ThibautMelen released this 09 Nov 12:43

Install the QR Code AI command-line scanner on Fedora 44. qrscan reads QR codes and barcodes from local images and writes JSON reports.

QR codes Barcodes
Try the scanner live QR code scanner Barcode scanner
Command line guide QR code scanner for the command line Barcode scanner for the command line
Create a code QR code generator Barcode generator
Fedora 44 architecture RPM
x86_64 qrcode-barcode-scanner-0.11.0-1.fc44.x86_64.rpm
ARM64 qrcode-barcode-scanner-0.11.0-1.fc44.aarch64.rpm

Download the RPM for your architecture and the checksum manifest to the same directory. The project distributes these RPMs directly through GitHub. They are unsigned, so verify the download against the manifest before installing.

sha256sum --check --ignore-missing qrcode-barcode-scanner-rpm-0.11.0-1.fc44-SHA256SUMS
sudo dnf install "./qrcode-barcode-scanner-0.11.0-1.fc44.$(uname -m).rpm"
qrscan --version

Both RPMs contain the unmodified qrscan 0.11.0 executable. Fedora 44 container tests installed the RPM with DNF, detected the QR and Code 128 together in the mixed test image in fast, frame and full, and removed the package cleanly. The source RPM contains the packaging recipe, the two original GNU/Linux archives, and the corresponding source archive.

Linux packages for QR Code & Barcode Scanner 0.11.0

Choose a tag to compare

Debian and Ubuntu packages

Install the qrscan command from a .deb built around the published 0.11.0
Linux CLI. The Debian package revision is 0.11.0-1.

Platform Package
x86-64 / amd64 qrcode-barcode-scanner_0.11.0-1_amd64.deb
ARM64 / arm64 qrcode-barcode-scanner_0.11.0-1_arm64.deb

Download the file for your architecture and the SHA-256 manifest from Assets.
In a directory with both packages, verify the full set with
sha256sum -c qrcode-barcode-scanner-debian-0.11.0-1-SHA256SUMS.
With one package, compare its sha256sum to the matching manifest line.

sudo apt install ./qrcode-barcode-scanner_0.11.0-1_amd64.deb
qrscan --version
curl -fsSLo mixed-code128-qr.png https://raw.githubusercontent.com/qrcode-ai-com/qrcode-barcode-scanner/176ac96ef16ee330dbfc6ada10327d0b4e23a8b2/fixtures/symbology/mixed-code128-qr.png
qrscan mixed-code128-qr.png --profile fast --budget-ms 0
sudo apt purge qrcode-barcode-scanner

The same image returns QR payload https://qrc-ai.com/76xMa and Code 128
STOCK-4827. Clean Debian 12 and Ubuntu 24.04 containers passed installation,
the mixed scan in fast, frame and full, and removal on both
architectures. The x86-64 checks used emulation, and the ARM64 checks used an
ARM64 Linux virtual machine.

These packages carry the upstream license and notices. See the
packaging recipe,
engine release
and corresponding source archive.

QR codes Barcodes
Try the scanner live QR code scanner Barcode scanner
Command line guide QR code scanner for the command line Barcode scanner for the command line
Create a code QR code generator Barcode generator

v0.11.0

Choose a tag to compare

@ThibautMelen ThibautMelen released this 05 Nov 11:43

QR Code & Barcode Scanner 0.11.0

A single Rust engine for QR codes, linear barcodes and matrix codes, with local decoding across Rust, Node.js, browsers and Python.

  • Mixed codes stay visible. A neighboring QR no longer hides STOCK-4827 (Code 128); regression coverage spans fast, frame and full profiles.
  • Physical occurrences. Repeated copies retain their own measured geometry while sharing decoded content.
  • One browser WASM. Camera capture, tracking, perspective overlays and explicit destination inspection ship with the browser package.
  • New package family. Rust, npm and Python use qrcode-barcode-scanner; the source publisher is qrcode-ai-com.
  • Stronger runtime contracts. Consistent option validation, safer Node cancellation, and native addon floor checks across six targets.
QR codes Barcodes
Try the scanner live QR code scanner Barcode scanner
SDK guides QR code scanner SDKs Barcode scanner SDKs
Create a code QR code generator Barcode generator

Migration guide · API and documentation

Install the published 0.11.0 packages for your runtime:

Runtime Install
Rust library cargo add qrcode-barcode-scanner@0.11.0
CLI cargo install qrcode-barcode-scanner-cli --version 0.11.0 --locked
Node.js npm install @qrcode-ai-com/qrcode-barcode-scanner@0.11.0
Browser / WASM npm install @qrcode-ai-com/qrcode-barcode-scanner-wasm@0.11.0
Python python -m pip install qrcode-barcode-scanner==0.11.0

Rust/CLI, npm native/WASM and Python 0.11.0 are published. The six Python wheels and source distribution were published through GitHub OIDC, with verified PyPI provenance for all seven files. See the current public install paths below.

Prebuilt CLI, container and agent installs

Mobile bindings are outside this release cut. Physical-camera and comparative performance claims are not part of this release qualification.

Full changelog and prebuilt CLI verification

0.11.0 — 2026-10-31

Package names

  • From 0.11.0 the packages carry the QR Code & Barcode Scanner family names,
    one per registry. Each new name is versioned from its first release under
    that name, 0.11.0:
    • Rust library: qrcode-ai-scanner becomes qrcode-barcode-scanner on
      crates.io, imported as qrcode_barcode_scanner.
    • Command line: qrcode-ai-scanner-cli becomes qrcode-barcode-scanner-cli
      on crates.io. Both crates install the qrscan command, so uninstall the
      former one first.
    • Node: @supernovae-st/qrcode-ai-scanner and its six platform packages
      become @qrcode-ai-com/qrcode-barcode-scanner and
      @qrcode-ai-com/qrcode-barcode-scanner-<suffix> on npm, with the same six
      suffixes. The addon file is qrcode-barcode-scanner.<suffix>.node.
    • Browser: @supernovae-st/qrcode-ai-scanner-wasm becomes
      @qrcode-ai-com/qrcode-barcode-scanner-wasm on npm. Its module files are
      qrcode-barcode-scanner.js, qrcode-barcode-scanner.d.ts and
      qrcode-barcode-scanner_bg.wasm, and the compatible/ paths are gone
      (browser upgrade note, under Changed).
    • Python: qrcode-ai-scanner, last released as 0.9.0, becomes
      qrcode-barcode-scanner on PyPI, imported as qrcode_barcode_scanner.
    • The qrscan archives, new on the GitHub release, are named
      qrcode-barcode-scanner-cli-0.11.0-* (under Added).
  • Nothing from 0.11.0 on is published under a former name, and there are no
    alias or wrapper packages. Releases up to 0.10.x stay installable under
    their former names and are not modified.
  • The rename itself changes no wire value: the JSON report and its
    versions, the schema $id, the [QRS-xxx] codes, the exit codes, the
    qrscan flags, the option names and values and the binding function names
    stay as they were.
  • The Kotlin binding's Maven coordinate follows the repository: group
    com.github.qrcode-ai-com, artifact qrcode-barcode-scanner. The UniFFI,
    Kotlin, Swift and Android module names, the repository directories and the
    never-published Cargo packages qrcode-ai-scanner-node,
    qrcode-ai-scanner-wasm, qrcode-ai-scanner-uniffi and
    qrcode-ai-scanner-fuzz keep their earlier spelling. The Python binding's
    Cargo package becomes qrcode-barcode-scanner-py; it names the CycloneDX
    SBOM file and its root component in each wheel. The Flutter package's
    pub.dev name and first release are recorded in
    bindings/flutter/CHANGELOG.md when it is published there.
  • The MCP adapter, the agent skill and the container images keep their
    published names and versions; their next releases take names from the new
    family. No 0.11 image goes to Docker Hub.
  • The first version under each new npm name is uploaded by the repository
    owner from the tag run's inspected tarballs, as RELEASING.md describes, so
    npm 0.11.0 carries no npm provenance. CI publishing with provenance is
    reserved for a later qualified version after its trusted publishers are configured.
  • The migration guide maps each former name to its new one and gives the steps
    for each runtime:
    https://github.com/qrcode-ai-com/qrcode-barcode-scanner/blob/v0.11.0/docs/guides/migrate-to-qrcode-barcode-scanner.mdx

Fixed

  • The perspective warp's sine and cosine, the glare model's exponential and
    one distance in the ISO 15415 grading are computed in f64 and rounded once
    to f32. Computed in f32, they could differ between platform math libraries
    and move a stress axis or a score.
  • The native Node addon for Windows (win32-x64-msvc) links the C runtime
    statically, as node.exe does, so it imports no Visual C++ runtime DLL.
    0.10.0's addon imported VCRUNTIME140.dll, which a Windows install without
    the Visual C++ Redistributable lacks; GitHub's Windows runners carry it, so
    the consumer jobs could not see the difference.
    scripts/native-floor.py reads each release addon's bytes (ELF needed
    libraries and symbol versions, Mach-O load commands and minimum OS, PE
    imports and delay imports). It refuses an addon that needs more than Node
    18 needs on its platform: glibc 2.28, macOS 10.15 on x64 and 11 on arm64,
    no Visual C++ runtime DLL, and no library outside the operating system,
    including one a Mach-O addon loads lazily, weakly, upward or as a
    re-export. npm-publish runs it on the packed release set and again on
    the tarballs about to be uploaded. On every pull request CI runs its
    self-test: planted binaries, then the command line on npm tarballs (a
    release set, the same set with a win32 addon importing VCRUNTIME140.dll,
    five of six targets, a target twice, no addon).
  • A QR code found in the downscaled pyramid no longer suppresses a readable
    neighboring barcode or small matrix code. One budgeted non-QR read at input resolution
    completes QR pyramid results before the early return.
    Regression coverage retains STOCK-4827 beside a QR in fast, frame and full
    profiles, including the existing browser WASM checks, and adds native exact
    QR/Data Matrix coverage in both placements. Detection identity and QR quality
    scoring remain unchanged. This completion is pipeline 4's change; the release
    publishes pipeline 5 with occurrences (below).
  • Equal printed copies of one linear content are no longer collapsed into one
    read. The scanner's copy of rxing 0.9.3's multiple-barcode reader
    (src/engine/multi_reader.rs, Apache-2.0 notices kept, THIRD-PARTY.md)
    decides duplicates by kind of symbol and by the image's pixels instead of
    point count, normalizes every read's points into the image's frame, reads a
    node again past a read without points, uses one fixed reader order and a
    fresh reader state for each read. All three rxing entry points use it: the
    unrestricted, family and single-format passes; the local DataBar Expanded
    reader; and the rMQR-only pass of score cells and envelope probes.
  • The S5 rescue keeps identically damaged twins at different places as
    separate candidates and rescues each place, instead of stopping at the
    first recovered stre...
Read more

MCP adapter 0.2.1

Choose a tag to compare

@ThibautMelen ThibautMelen released this 05 Nov 22:06
610879c

MCP adapter 0.2.1 corrects the installation and client configuration
instructions in the npm package. It still uses the same 0.11.0 scanner
engine
and report schema.

QR codes Barcodes
Try the scanner live QR code scanner Barcode scanner
MCP server guide QR code scanner MCP server Barcode scanner MCP server
Agent skills guide QR code scanner agent skill Barcode scanner agent skill
Create a code QR code generator Barcode generator
npm install --prefix ./qrscan-mcp-install --save-exact --ignore-scripts @qrcode-ai-com/qrcode-barcode-scanner-mcp@0.2.1

The npm archive was published through GitHub Trusted Publishing and matches
the archive qualified before publication. Its SHA-256 is
e948ef8bac8fb8c197cd8cabb1a3df3d3d5db60e1b90d965125308186c8797e2.
The public version was installed in fresh Node 22 and 24 consumers, exercising
modern and legacy MCP, including mixed QR and Code 128 in all three profiles.

Files attached to this release

Three archives were attached on 11 November 2026, for people who install from a
release page instead of a registry. They add nothing new: each one is a copy of
something this tag already published or holds.

File What it is SHA-256
qrcode-barcode-scanner-mcp-0.2.1.tgz The npm archive of the MCP adapter 0.2.1, byte for byte e948ef8bac8fb8c197cd8cabb1a3df3d3d5db60e1b90d965125308186c8797e2
qrcode-barcode-scanner-skill-0.2.0.zip The five files of the skill folder skills/qrcode-barcode-scanner at this tag ef84d7a2e4d1c949371fc2d1aa242e101c0e79e85de88027f6a9f9656fe2884c
qrcode-barcode-scanner-skill-0.2.0.tar.gz The same five files e73e7b5fe8c6da40ce5c1971e35d1f27d923aa8bf574eeb5c70b55e7a18899a8

qrcode-barcode-scanner-mcp-0.2.1-SHA256SUMS and
qrcode-barcode-scanner-skill-0.2.0-SHA256SUMS list the same values. They are
assets of this same release, so they detect a damaged download, not a
substituted release. For the adapter, the signed npm provenance above is the
independent check.

Install the MCP adapter from the attached file:

npm install --prefix ./qrscan-mcp-install --save-exact --ignore-scripts https://github.com/qrcode-ai-com/qrcode-barcode-scanner/releases/download/agents-v0.2.1/qrcode-barcode-scanner-mcp-0.2.1.tgz

The file holds the adapter only. npm still fetches its dependencies from the
npm registry, among them the scanner engine 0.11.0.

Install the skill from an archive. The archives have no top-level folder:
extract them into a folder named qrcode-barcode-scanner inside the skill
directory of your host.

curl -fsSLO https://github.com/qrcode-ai-com/qrcode-barcode-scanner/releases/download/agents-v0.2.1/qrcode-barcode-scanner-skill-0.2.0.tar.gz
mkdir -p skills/qrcode-barcode-scanner
tar -xzf qrcode-barcode-scanner-skill-0.2.0.tar.gz -C skills/qrcode-barcode-scanner

The skill holds no engine: install it separately, as its SKILL.md describes.

The three files were downloaded signed out and used as written above. The
adapter was installed from the file in empty projects on Node 22 and 24 and
driven over modern and legacy MCP. Each skill archive was extracted, compared
with the tag file by file, and passed its own 26 checks against a fresh engine
0.11.0. Every run read the mixed QR and Code 128 fixture.

The engine release 0.11.0,
ClawHub skill 0.2.0
and OpenClaw bundle 0.2.0
retain their own versions.

v0.10.1 — browser loading compatibility

Choose a tag to compare

@ThibautMelen ThibautMelen released this 20 Oct 12:12

Local QR code and barcode scanning, maintained by QR Code AI.

Browser loading compatibility

The browser package now includes equivalent SIMD and compatible WASM builds.
The additive @supernovae-st/qrcode-ai-scanner-wasm/auto entry probes actual
capabilities in its calling browser or worker, then fetches and initializes one
build. Existing root imports remain available as explicit SIMD loading.

Initialization failures have distinct feature, asset/network, binary validation,
compilation and instantiation codes. Concurrent calls share one bounded attempt;
an unidentified initialization error does not trigger an automatic reload loop.
Decoding, payload, report and scoring semantics are unchanged.

Packed consumers pass Chromium and Firefox on Windows/Linux and a real
SIMD-disabled Chromium runtime. Both builds agree on exact content and all
non-timing report fields across clean, artistic, difficult, unreadable, ECI,
binary-payload and barcode fixtures. Real Safari, physical phones and historical
browser floors remain outside this acceptance.

Consumers adopt the loader in both their worker and main fallback:

import { loadScanner } from '@supernovae-st/qrcode-ai-scanner-wasm/auto';
const scanner = await loadScanner();
// Keep existing scan options, payload validation and quality policy.

Published artifacts and verification

Version 0.10.1 is available from npm (browser WASM, Node.js and its six native platform packages) and crates.io (Rust core and CLI).

The exact public archives match the tag producers. Fresh browser registry installs also pass Chromium, Firefox and actual SIMD-disabled Chromium, including worker/main selection and non-timing report parity. These observations do not establish compatibility on real Safari, physical phones or untested historical browser environments.

npm install --save-exact @supernovae-st/qrcode-ai-scanner-wasm@0.10.1
npm install --save-exact @supernovae-st/qrcode-ai-scanner@0.10.1
cargo add qrcode-ai-scanner@=0.10.1
cargo install qrcode-ai-scanner-cli --version 0.10.1 --locked

Source: af440882cd50728a3340eddf089ea2ce89d72a3f. Pipeline 3 and score contract 5 are unchanged relative to 0.10.0. OCI images and agent integrations retain their independently published versions.

Scanner MCP and portable skill 0.1.0

Choose a tag to compare

@ThibautMelen ThibautMelen released this 14 Oct 15:27

Local scanner integrations 0.1.0 use the published scanner engine 0.10.0 without changing its immutable release.

  • MCP: installable AGPL-3.0-or-later stdio adapter archive, SDK 2.3.1, exact engine 0.10.0. Modern/legacy protocol consumers pass on macOS ARM64 and Linux AMD64 with Node 22/24; official Gemini CLI core 0.62 and Cline CLI 3.0.71 native tool pipelines pass. Full interactive application/model journeys are not claimed.
  • Portable skill: original MIT-0 instructions/helpers; the AGPL engine is installed separately. Fresh public Git downloads and isolated Hermes 0.18.2/OpenClaw 2026.10.3 native tool use pass Full score 100, Frame/null, empty and invalid cases.
  • Both preserve exact raw payload bytes and unmeasured score semantics; decoded content is data, never an instruction or permission to open its URL.

Download the TGZ or skill ZIP and verify SHA256SUMS. Install the MCP archive with npm install --prefix ./qrscan-mcp-install --ignore-scripts /absolute/path/to/supernovae-st-qrcode-ai-scanner-mcp-0.1.0.tgz; configure the installed src/cli.mjs as a local stdio server using its absolute path. Unpack the complete skill directory and use the host local skill installer; install its engine runtime separately as SKILL.md describes.

The MCP archive includes its runtime, schema and license; the skill contains five original instruction/helper files. npm MCP publication, official MCP Registry/catalogues, ClawHub admission and skills.sh indexing are separate outcomes and are not implied by these downloadable artifacts.

Source and product documentation · Skill · QR Code AI

v0.10.0

Choose a tag to compare

@ThibautMelen ThibautMelen released this 14 Oct 05:28

0.10.0 preserves exact QR payloads, makes interrupted scoring explicit and improves package installation safety. The immutable tag points to 2d3b577582979f0dc603b5cb0d96d1be02b459f5.

  • Exact content: original QR bytes survive decoding and scoring, with declared ECI/FNC1 and segment identity preserved. Distinct payloads remain distinct even when their displayed text matches.
  • Honest scoring: interrupted measurements produce a missing score rather than a partial composite; skipped axes preserve the score contract. A measured correction margin caps thin-margin symbols continuously. Pipeline version is 3; score contract is 5.
  • Portable packages: native Node packages cover macOS ARM/Intel, Linux ARM/x64 GNU, Linux x64 musl and Windows x64. The standalone Rust CLI retains decoder overflow checks. Source-distribution rebuilds preserve Python typing, with Python delivery following separately.
  • Trusted publication: Rust and npm publish inspected archives from a version tag through GitHub OIDC; npm packages include provenance attestations.

Available channels:

Package Version Installation
Rust core 0.10.0 cargo add qrcode-ai-scanner@=0.10.0
Rust CLI 0.10.0 cargo install qrcode-ai-scanner-cli --version =0.10.0 --locked
Node 0.10.0 npm install @supernovae-st/qrcode-ai-scanner@0.10.0
WebAssembly 0.10.0 npm install @supernovae-st/qrcode-ai-scanner-wasm@0.10.0

Python, Flutter and native mobile registry delivery follow separately. Automated desktop-browser qualification covers current Chromium, Firefox and Playwright WebKit; the camera success path uses a synthetic feed. Physical iOS/Android camera acceptance, real Safari and historical browser floors remain unverified. Budget checks are cooperative and do not guarantee a hard bound for every input.

See the full changelog and report specification for behavior and compatibility details.

0.9.0 — alpha flatten, placement envelope, score presets

Choose a tag to compare

@ThibautMelen ThibautMelen released this 20 Jul 14:42

Changed

  • Transparent inputs flatten before decode (pipeline 1→2,
    score_contract 3→4) — the engine used to read the RGB stored under
    the transparency (alpha was dropped at the input seam), which made the
    verdict exporter-dependent: the same visual design scored 100
    (white-under-alpha exports), 74 (canvas-style black-under-alpha) or
    "no detection" (dark modules over canvas transparency) depending on
    which tool wrote the PNG. Since this release the input composites over
    a DECLARED background before luma conversion and RGB extraction —
    every stage (ladder · score · UEC · ISO) sees the flattened image, and
    the stored under-alpha RGB can never influence the report
    (exporter-invariance is pinned by test). auto (the default) measures
    the design on its intended placement: dark content over white, light
    content over black, with an opposite-background retry on a
    zero-detection scan (alpha.fallback_used) so a mis-called mean can
    never produce a false "no detection". Opaque inputs are untouched —
    their reports stay byte-identical (the alpha key is omitted
    entirely, not null). Spec: 01-report § Alpha · 07-pipeline.

Added

  • ScanConfig.alpha_background on every surface, per the
    score_skip_axes precedent — core (AlphaBackground +
    from_name), wasm (scan_image(..., alpha_background)), Node
    (alphaBackground option, typed
    "auto" | "white" | "black" | "none" | hex), CLI
    (--alpha-background), Python (alpha_background= kwarg, stub
    updated), UniFFI/Kotlin/Swift (alpha_background arg with a typed
    UnknownAlphaBackground error). #rrggbb forces the host's real
    placement surface — the truest verdict when the embedder knows where
    the code will sit; none restores the drop-the-channel behavior as
    an escape hatch. Unknown values fail loud on every surface. (The
    Flutter facade parses the new block; its option arg lands with the
    facade's next options pass — it exposes neither budget nor skips
    today.)

  • The placement envelope (alpha.envelope, Full profile) — the
    transparent-design question is not "does it scan" but "over which
    backgrounds does it keep scanning": five fixed neutral rungs
    (luma 0 · 64 · 128 · 192 · 255) plus one bisection probe per verdict
    boundary, each a quick decode in the primary symbol's own decode
    class. The report carries the probes (every endpoint a TESTED
    background, never interpolation), the contiguous safe_luma bands,
    and a placement verdict (any · light_only · dark_only ·
    mixed · none). Informational by contract: it never moves
    score.value. Skippable through the standard seam
    (score_skip_checks: ["alpha_envelope"] — ScoreCheck gains the
    variant on every surface).

  • Hint::AlphaBackgroundDependent { placement } — fires when the
    envelope is narrower than any: pin a background layer in the
    artwork, or constrain placement to the safe bands. The generator/UI
    loop's alpha feedback.

  • report.alpha block: coverage · content_luma · mode ·
    background ("white" / "black" / "#rrggbb") · fallback_used
    · envelope. Schema, TS types, Dart mirror and the type-parity gate
    updated in lockstep; qrscan --pretty renders the flatten verdict
    and the envelope strip.

  • alpha_palette on every option surface (alphaPalette /
    --alpha-palette) — the host's theme/brand colors probed by the
    envelope inside the SAME scan: per-color verdicts land in
    alpha.envelope.palette (request order, each at its BT.601 luma),
    instead of one full scan per candidate background. Palette colors
    never distort the neutral probes/bands/placement. Unknown colors fail
    loud (white · black · #rrggbb only — the flatten keywords are
    modes, not colors).

  • Hint::AddBackgroundPlate { color } — the canonical REMEDY riding
    with the alpha_background_dependent diagnosis: add an opaque plate
    (rounded rectangle + quiet-zone margin) behind the symbol; color
    (white for dark content, black for light) maximizes contrast.
    Maps 1:1 to an editor's one-click fix.

  • score.weights_run — the honesty integer: Σ contract weights of the
    axes that ran (100 = the full six-axis contract). A partial score now
    SAYS how much contract stands behind it; pre-0.9 reports parse
    leniently (default 0). qrscan --pretty renders "· 70% of contract"
    when partial.

  • score_preset on every option surface (scorePreset /
    --score-preset): the two canonical postures by NAME — design
    (generated previews: skips perspective+rotation, keeps lighting) ·
    capture (all six). Sugar over score_skip_axes, mutually exclusive
    with an explicit list (rejects loudly on every surface) — N host
    integrations can no longer drift apart on hand-built lists.

  • axes[].refined_failed_at — the knee, bisected once at Full depth:
    the tightest TESTED failing intensity ("blur 2.25", "435px", "63%").
    One extra probe per kneed ramp; the composite never reads it; absent
    when no refinement ran. The generate→scan→regenerate loop sees
    sub-cell progress instead of 2-4 point cliffs.