Barcode/QR Scanning UX

A green camera result means “decoded,” not “the correct package is verified”

A decoder can return PKG-84219 in a fraction of a second and still leave the important questions unanswered. Does the current device support the expected symbology? Is the decoded value structurally valid? Does it belong to this order and this workflow step? Was the same code already accepted five seconds ago? If the camera path failed, where did the fallback value come from?

This lesson builds Scan Capability and Verification Contract v1. Capture is only the first stage. Business confirmation follows explicit capability, symbology, parsing, structure, context, dedupe, and provenance gates.

COM-033 ownership boundary

COM-033 owns scan capture and verification UX/evidence. COM-032 owns label printing, RTL, and barcode layout. COM-034 owns carrier tracking-event truth, normalization, and reconciliation. This lesson neither generates labels nor interprets carrier lifecycle events.

Three hard boundaries:

1. decoded != verified: a decoder output is not business identity proof.
2. supported != guaranteed: a format reported as supported is not a guarantee that every physical symbol will be recognized.
3. valid syntax != valid context: a perfectly valid identifier may belong to another order or package.

Mental model: Capture → Decode → Normalize → Validate → Bind → Dedupe → Confirm

Use an ordered pipeline:

camera / USB scanner / manual entry → capability adapter → raw decode → format + normalization → structural check → expected-context match → duplicate check → human-visible confirmation → bounded workflow transition

Each step produces its own evidence. If a decisive step is unknown, the state becomes HOLD, UNKNOWN, or FALLBACK_REQUIRED; the UI must not hide missing evidence behind a success animation.

Keep FACT, INFERENCE, and DESIGN separate

FACT: The current WICG draft exposes BarcodeDetector in secure contexts, provides getSupportedFormats(), and says supported formats are platform dependent. It also states that supported-format discovery cannot guarantee recognition of a specific image/symbol.

FACT: MDN currently marks the Barcode Detection API as Limited availability and Experimental, with an explicit compatibility check warning for production use.

FACT: GS1 guidance shows that QR Code, Data Matrix, and GS1 DataMatrix do not have identical reach across mobile cameras and retail/POS systems. QR Code with GS1 Digital Link is broadly accessible with default mobile cameras, while processing support for every 2D option is not universal.

INFERENCE: Capture capability and business identity are separate problems, so a safe UX represents them as separate evidence states.

DESIGN: MAKNOW does not allow decoder success alone to advance business state. Expected-context matching, dedupe, and fallback provenance are explicit gates.

The 22-dimension scan verification contract

Gate 1 — Capability-check the active capture adapter

For a camera path, checking only window.BarcodeDetector is insufficient; secure context and supported formats matter too. A desktop USB scanner may act as keyboard/HID input and bypass BarcodeDetector entirely. Capability evidence therefore belongs to the active adapter, not to a global assumption.

Gate 2 — Declare accepted symbologies before scanning

If the workflow accepts only qr_code and code_128, a decoded data_matrix is not accepted just because the decoder could read it. The expected set is part of the evidence contract.

Gate 3 — Preserve raw and normalized values separately

raw_scan_value is the exact capture evidence. normalized_identifier is produced by parsing/normalization. URI parsing, GS1 extraction, trimming, or separator removal must remain reconstructable.

Gate 4 — Parse and structure before context lookup

Apply syntax, prefix, length, schema, or check-digit rules before business lookup. Malformed input should not be sent into fuzzy resolution and then matched to a convenient entity.

Gate 5 — Context match is the business-identity gate

expected_context_id may represent an order, package set, picking wave, or workflow step. A structurally valid identifier that resolves outside that context becomes REJECTED_CONTEXT_MISMATCH.

Gate 6 — Suppress repeated frame reads

Camera scanning can decode the same symbol across multiple frames. A stable duplicate_key should include the scan session, normalized identifier, and workflow context (or an equivalent stable tuple). Preserve duplicate evidence, but do not repeat the downstream side effect.

Gate 7 — Manual entry is fallback, not bypass

If permission, detector support, or expected symbology fails, manual/USB fallback can be allowed. Record manual_entry_used and fallback_reason, then run the same parse, context, and dedupe gates.

Gate 8 — Confirmation is evidence-derived

ACCEPTED_VERIFIED is allowed only when decisive evidence is present, parsing/structure pass, context matches, and the scan is not a duplicate. Weaker evidence must produce a weaker state.

Gate 9 — Explain non-success states in the UX

“Scan failed” is too vague. Capability failure, unsupported format, malformed identifier, context mismatch, and duplicate are different repair paths and should be distinguishable to the operator.

Gate 10 — Transfer changes adapters, not acceptance rules

Moving from Android Chrome to iOS/Safari or desktop USB may change the capture implementation. Symbology policy, parsing, context matching, dedupe, and confirmation rules remain stable. Capability evidence must be recomputed for the new adapter rather than copied from the baseline.

Worked examples

1. Chrome + supported QR + correct context → ACCEPTED_VERIFIED

Secure context is present, the detector reports qr_code, the value parses, resolves inside the expected order, and is not a duplicate.

2. Detector exists but expected Data Matrix is unsupported → FALLBACK_REQUIRED

Do not treat the camera as “close enough.” Route to a controlled USB/manual fallback and preserve the same verification gates.

3. Valid QR, wrong order → REJECTED_CONTEXT_MISMATCH

The identifier is real and well-formed, but it belongs to a different order. Decoder correctness does not make the business action correct.

4. Same package scanned again → DUPLICATE_SUPPRESSED

The second read is retained as evidence but does not cause another workflow transition.

5. Camera permission/API unavailable → provenance-bearing fallback

Manual input is acceptable only when its fallback reason is recorded and the value passes the same structure/context/dedupe checks.

6. Mixed fleet: iOS/Safari + desktop USB

Each device gets capture-adapter evidence. Acceptance semantics are shared; device capability is not assumed to be shared.

Common failure modes

• Decoder-success promotion: every successful decode advances the workflow.
• Global capability assumption: success on one Android device becomes a fleet-wide assumption.
• Symbology ambiguity: decoded formats outside the allow-list are accepted.
• Raw/normalized collapse: transformation history disappears.
• Cross-order acceptance: a real identifier is accepted because it exists, even in the wrong context.
• Frame duplicate side effects: multiple frames create multiple transitions.
• Manual-entry bypass: fallback skips verification gates.
• Green-check UX: the operator cannot tell why a scan is blocked.
• Transfer copy: Android capability evidence is reused for iOS/USB without recomputation.

Alternatives and trade-offs

Accelerated/native BarcodeDetector: simple and fast where supported, but availability is not universal and remains experimental/limited.

JavaScript/WASM decoder: can improve portability but moves bundle, CPU, camera pipeline, and quality tuning into your application. It still does not solve business-context correctness.

USB/HID scanner: practical for desktop operations, but focus management, accidental keystrokes, and device configuration need controls.

Manual entry: universal fallback with higher typo risk, making structure checks and operator provenance even more important.

One universal scan screen: looks simpler but can hide capability differences. Adapter-based capture plus one shared verification contract has more explicit plumbing and less false confidence.

Experienced bridge: eleven review questions

1. What is the active capture adapter and how was its capability evidenced?
2. Is secure context actually present for the camera path?
3. Where is the expected symbology set versioned?
4. Can raw input and normalized identifier both be reconstructed?
5. How does parser ambiguity fail?
6. Which identifier type owns the structural/check-digit rule?
7. Is expected context known before the scan or guessed afterward?
8. Does the duplicate key include the right session/workflow boundary?
9. Does fallback run the same verification gates?
10. Can the UX distinguish capability failure from context mismatch?
11. In a mixed fleet, what is reusable and what must be recomputed?

Guided and independent practice

The offline lab contains eight fixtures: baseline, unsupported format, wrong-order code, duplicate, missing evidence, manual fallback, and two transfer cases. Do not memorize labels; identify the evidence dimension that changes each decision.

Then create a new fixture with a valid raw value but a changed expected_context_id. It must not remain accepted. Next switch capture from camera to USB while keeping the acceptance gates unchanged; only capability/fallback evidence should be rebuilt.

Verification evidence

An acceptable artifact shows:

• all 22 dimensions, or explicit justification for nullable fields;
• capability and supported-format evidence for the active adapter;
• raw and normalized values separately;
• parse/structure checks before business context;
• expected-context binding before confirmation;
• duplicate suppression without repeated side effects;
• provenance-bearing manual fallback through the same verification gates;
• ACCEPTED_VERIFIED only with complete decisive evidence;
• mixed-fleet transfer through adapter recomputation, not baseline copying.

The learner lab is deterministic and offline; it needs no real camera, API key, customer data, or network access.

Assessment and transfer

To complete the lesson, independently:

1. explain the COM-033 boundary and one adjacent non-goal;
2. build Scan Capability and Verification Contract v1 from the baseline fixture;
3. diagnose unsupported capability, wrong context, and duplicate evidence with the correct repair;
4. transfer the workflow to iOS/Safari and desktop USB while recomputing capture-adapter evidence only;
5. explain why decoder success is never sufficient business-identity proof.

Copying the baseline device decision into the new fleet without recomputing capability/fallback evidence fails transfer.

References and freshness

• WICG Accelerated Shape Detection draft — BarcodeDetector, secure context, getSupportedFormats(), and platform-dependent support; checked 2026-09-14, review due 2026-10-18.
• MDN BarcodeDetector — Limited availability / Experimental and production compatibility warning; checked 2026-09-14, review due 2026-10-18.
• GS1 2D barcode guidance — differences across QR/Data Matrix/GS1 DataMatrix and uneven mobile/POS processing support; checked 2026-09-14, practice review due 2026-12-31.

External references provide platform/carrier FACTs only. Context binding, duplicate suppression, fallback provenance, and confirmation policy are MAKNOW design choices.