hh-shipments 0.3.27 → 0.3.29

package/package.json

@@ -19,7 +19,7 @@
     "test": "node test/run-extract-tests.js && node test/run-tests.js && node test/run-carriers-tests.js"
   },
   "type": "commonjs",
-  "version": "0.3.27",
+  "version": "0.3.29",
   "bin": {
     "hh-shipments": "server.js"
   },

package/public/app.js

@@ -154,10 +154,16 @@ async function runQuick(text, targetEl, preset) {
 }
 
 // When OCR finds no tracking number, show the raw read so the user can
-// spot the misread and type it in manually.
-function showOcrRead(targetEl, text) {
+// spot the misread and type it in manually. Includes which OCR stage
+// produced the text and the app build, so a failure is diagnosable from
+// the screenshot itself — no more blind "it didn't work".
+function appBuild() {
+  return (document.querySelector('meta[name="app-version"]') || {}).content || '?';
+}
+function showOcrRead(targetEl, text, stage) {
   const t = (text || '').trim();
-  targetEl.innerHTML += `<details class="ocr-read"><summary>What I read from the picture</summary><pre>${esc(t || '(nothing readable)')}</pre></details>`;
+  const diag = stage ? ` <span class="muted">· read via ${esc(stage)} · build ${esc(appBuild())}</span>` : '';
+  targetEl.innerHTML += `<details class="ocr-read"><summary>What I read from the picture</summary>${diag}<pre>${esc(t || '(nothing readable)')}</pre></details>`;
 }
 async function loadDashCounts() { /* counts refresh on next dashboard visit */ }
 
@@ -179,17 +185,22 @@ function loadTesseract() {
 // - Chat screenshots (dark): invert, PSM 6 (uniform block)
 // - Labels (light): crop to tracking zone, upscale, PSM 6
 // - Falls back to full-image PSM 3 if targeted fails
+// Returns { text, stage } — the stage that produced the text is surfaced in
+// the UI so a failed read is diagnosable from a screenshot (which pass ran,
+// which build), instead of another blind "it didn't work".
 async function ocrFile(file, statusEl) {
   await loadTesseract();
-  statusEl.textContent = 'Reading screenshot…';
+  if (statusEl) statusEl.textContent = 'Reading screenshot…';
   const isDark = await isDarkImage(file);
   file = isDark ? await invertImage(file) : file;
 
   const log = (m) => { if (m.status === 'recognizing text' && statusEl) statusEl.textContent = `Reading… ${Math.round(m.progress * 100)}%`; };
+  const ANCHOR = /(1Z|12|IZ|17)\s*[0-9A-Z)\]}(\[{|!]/i;
 
   // Pass 1: targeted — for labels, crop to the tracking-number zone (bottom 45%)
   // and upscale for Tesseract. For chats, use the full image.
-  let bestText = '';
+  let bestText = '', bestStage = 'none';
+  const consider = (t, stage) => { if (t && t.length > bestText.length) { bestText = t; bestStage = stage; } };
   if (!isDark) {
     try {
       const zoned = await cropAndUpscale(file, 0, 0.55, 1, 0.45, 2);
@@ -197,36 +208,61 @@ async function ocrFile(file, statusEl) {
         logger: log,
         tessedit_pageseg_mode: '6', // uniform block of text
       });
-      bestText = r1.data.text || '';
+      const t1 = r1.data.text || '';
+      consider(t1, 'zone');
       // If the zone has a plausible tracking number, we're done
-      if (/(1Z|12|IZ|17)\s*[0-9A-Z)\]}(\[{|!]/i.test(bestText)) {
+      if (ANCHOR.test(t1)) {
         if (statusEl) statusEl.textContent = '';
-        return bestText;
+        return { text: t1, stage: 'zone' };
       }
     } catch (e) {}
   }
 
+  // Pass 1b: tracking-line band SWEEP — the printed "TRACKING #:" line sits
+  // in a narrow band whose vertical position shifts with photo framing and
+  // angle. A single fixed band missed real labels, so sweep overlapping
+  // bands; the first whose OCR contains the tracking anchor wins.
+  // Verified on a real label: the center band alone read
+  // "TRACKING # 12 GE2 384 03 3726 7306" off a photo the other passes
+  // scored as "1 1 (1".
+  if (!isDark) {
+    const bands = [0.50, 0.44, 0.56, 0.38, 0.62];
+    for (const fy of bands) {
+      try {
+        const band = await cropAndUpscale(file, 0.03, fy, 0.87, 0.12, 3);
+        const rb = await Tesseract.recognize(band, 'eng', {
+          logger: log,
+          tessedit_pageseg_mode: '6',
+        });
+        const tb = rb.data.text || '';
+        consider(tb, 'band');
+        if (ANCHOR.test(tb)) {
+          if (statusEl) statusEl.textContent = '';
+          return { text: tb, stage: 'band' };
+        }
+      } catch (e) {}
+    }
+  }
+
   // Pass 2: full image with PSM 6
   try {
     const r2 = await Tesseract.recognize(file, 'eng', {
       logger: log,
       tessedit_pageseg_mode: '6',
     });
-    const t2 = r2.data.text || '';
-    if (t2.length > bestText.length) bestText = t2;
+    consider(r2.data.text || '', 'full');
   } catch (e) {}
 
   // Pass 3: fallback to default PSM 3 if we got nothing useful
   if (!bestText || bestText.trim().length < 10) {
     try {
       const r3 = await Tesseract.recognize(file, 'eng', { logger: log });
-      const t3 = r3.data.text || '';
-      if (t3.length > bestText.length) bestText = t3;
+      consider(r3.data.text || '', 'psm3');
     } catch (e) {}
   }
 
   if (statusEl) statusEl.textContent = '';
-  return bestText;
+  return { text: bestText, stage: bestStage };
 }
 
 async function isDarkImage(file) {
@@ -300,7 +336,7 @@ async function handlePhotoFile(f) {
     target.innerHTML = `<div class="review"><img src="${url}" style="max-width:100%;border-radius:10px"><p class="muted" id="ocr-live-photo">📷 Scanning barcode…</p></div>`;
     const live = $('ocr-live-photo');
     const barcode = await decodeBarcode(f);
-    let text, preset, topText = null, upIdPhoto = null;
+    let text, preset, topText = null, upIdPhoto = null, ocrStage = null;
     if (barcode) {
       text = barcode;
       if (live) live.textContent = '📷 Barcode read — reading sender…';
@@ -315,7 +351,9 @@ async function handlePhotoFile(f) {
       preset = topText ? { labelText: topText } : undefined;
     } else {
       if (live) live.textContent = '📖 Reading screenshot…';
-      text = await ocrFile(f, $('ocr-status'));
+      const ocrRes = await ocrFile(f, $('ocr-status'));
+      text = ocrRes.text;
+      ocrStage = ocrRes.stage;
       // Upload original for reference, then run the quick flow on OCR text
       const fd = new FormData();
       fd.append('image', f);
@@ -330,7 +368,7 @@ async function handlePhotoFile(f) {
     if (upIdPhoto) api.patch('/api/intake/' + upIdPhoto, { state: 'reviewed' }).catch(() => {});
     if (looksLikeAppScreenshot(topText || text)) $('photo-result').insertAdjacentHTML('afterbegin', '<p class="warn">⚠️ This looks like a screenshot of the app itself — choose the label photo directly for best results.</p>');
     if (barcode && r && r.added.length) $('photo-result').insertAdjacentHTML('afterbegin', '<p class="muted">📷 Read from the barcode — checksum verified.</p>');
-    if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead($('photo-result'), text);
+    if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead($('photo-result'), text, barcode ? 'barcode' : ocrStage);
     loadPending();
   } catch (err) { $('ocr-status').textContent = ''; $('photo-result').innerHTML = `<p class="error">${esc(err.message)}</p>`; }
 }
@@ -419,7 +457,7 @@ async function ocrTopStrip(origFile, statusEl) {
     bmp.close();
     const blob = await new Promise((res) => canvas.toBlob(res, 'image/jpeg', 0.92));
     if (!blob) return null;
-    const p = ocrFile(new File([blob], 'top.jpg', { type: 'image/jpeg' }), statusEl);
+    const p = ocrFile(new File([blob], 'top.jpg', { type: 'image/jpeg' }), statusEl).then((r) => r.text);
     return await Promise.race([p, new Promise((_, rej) => setTimeout(() => rej(new Error('top-strip timeout')), 25000))]);
   } catch (e) { return null; }
 }
@@ -450,6 +488,18 @@ async function decodeOne(reader, url, ms = 9000) {
   } catch (e) { return null; }
 }
 
+// Rank barcode candidates by format specificity: a 1Z UPS read or a
+// 22-digit USPS read is unambiguous, while a 10-digit "DHL" read off a
+// label is often a fragment of another carrier's number (or a routing
+// barcode). Weak hits never beat strong ones.
+function barcodeRank(num) {
+  if (/^1Z/i.test(num)) return 0;                              // UPS
+  if (/^9[1-5]\d{18,20}$/.test(num)) return 1;                 // USPS
+  if (/^96\d{20}$/.test(num) || /^\d{15}$/.test(num) || /^\d{20}$/.test(num)) return 2; // FedEx long
+  if (/^\d{12}$/.test(num)) return 3;                          // FedEx 12 (weak: may be routing)
+  return 4;                                                    // DHL 10/11 (weakest)
+}
+
 // Whole-label decode usually fails (barcodes too small in frame), so try
 // horizontal region strips, upscaled — the 1Z barcode lives low on UPS labels.
 async function decodeBarcode(file) {
@@ -467,6 +517,11 @@ async function decodeBarcode(file) {
     [0, 0.60, 1, 0.35],
     [0.05, 0.55, 0.90, 0.40],
   ];
+  // Collect every candidate across the sweep and take the strongest —
+  // never let the first weak hit (e.g. a 10-digit routing barcode read as
+  // DHL) win over the real tracking barcode. Unambiguous reads (UPS/USPS)
+  // still return immediately on the fast path.
+  let best = null, bestRank = 99;
   try {
     for (const [fx, fy, fw, fh] of regions) {
       for (const scale of [1, 1.5, 2]) {
@@ -491,11 +546,15 @@ async function decodeBarcode(file) {
         const url = canvas.toDataURL('image/png');
         const text = await decodeOne(reader, url);
         const num = strictTracking(text);
-        if (num) return num;
+        if (num) {
+          const r = barcodeRank(num);
+          if (r < bestRank) { best = num; bestRank = r; }
+          if (r <= 1) return num; // UPS or USPS: unambiguous, fast path
+        }
       }
     }
   } finally { bmp.close(); }
-  return null;
+  return best;
 }
 // Detect when the pasted image is a screenshot OF THE APP itself (its own
 // header/buttons/tab bar get OCR'd) — the label inside is too small to read
@@ -516,7 +575,7 @@ async function handlePastedImageFile(f) {
     const live = $('ocr-live');
     // 1) Barcode first: checksum-verified, essentially never wrong
     const barcode = await decodeBarcode(f);
-    let text;
+    let text, ocrStage = null;
     if (barcode) {
       text = barcode;
       if (live) live.textContent = '📷 Barcode read — reading sender…';
@@ -536,17 +595,18 @@ async function handlePastedImageFile(f) {
       if (upId) api.patch('/api/intake/' + upId, { state: 'reviewed' }).catch(() => {});
       if (looksLikeAppScreenshot(topText)) target.insertAdjacentHTML('afterbegin', '<p class="warn">⚠️ This looks like a screenshot of the app itself — paste the label photo directly for best results.</p>');
       if (r && r.added.length) target.insertAdjacentHTML('afterbegin', '<p class="muted">📷 Read from the barcode — checksum verified.</p>');
-      if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead(target, text);
+      if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead(target, text, 'barcode');
       return;
     }
     // 2) Fallback: OCR the printed text (+ the sender strip for the name,
     // in parallel — the number crop usually excludes the sender block)
     if (live) live.textContent = '📖 Reading screenshot…';
-    const [ocrText, topTextFb] = await Promise.all([
+    const [ocrRes, topTextFb] = await Promise.all([
       ocrFile(f, $('ocr-status-paste')),
       ocrTopStrip(orig, $('ocr-status-paste')),
     ]);
-    text = ocrText;
+    text = ocrRes.text;
+    ocrStage = ocrRes.stage;
     if (live) live.textContent = '⬆️ Uploading…';
     const fd = new FormData();
     fd.append('image', f);
@@ -560,7 +620,7 @@ async function handlePastedImageFile(f) {
     // Paste flow already handled this image — don't leave it nagging in the review queue.
     if (upId2) api.patch('/api/intake/' + upId2, { state: 'reviewed' }).catch(() => {});
     if (looksLikeAppScreenshot(text)) target.insertAdjacentHTML('afterbegin', '<p class="warn">⚠️ This looks like a screenshot of the app itself — paste the label photo directly for best results.</p>');
-    if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead(target, text);
+    if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead(target, text, ocrStage);
   } catch (err) { $('ocr-status-paste').textContent = ''; target.innerHTML = `<p class="error">${esc(err.message)}</p>`; }
 }
 
@@ -617,7 +677,7 @@ async function reviewPendingImage(id) {
     const resp = await fetch(`/api/intake/image/${id}`);
     const blob = await resp.blob();
     const file = new File([blob], 'pending.jpg', { type: blob.type || 'image/jpeg' });
-    const text = await ocrFile(file, null);
+    const { text } = await ocrFile(file, null);
     await api.patch('/api/intake/' + id, { state: 'reviewed' });
     await runQuick(text, $('photo-result'));
     loadPending();

package/public/extract.js

@@ -59,13 +59,14 @@
   // Strict UPS structure: 1Z + 6-char shipper number + 2-digit service + 8-digit serial.
   var UPS_STRICT = /^1Z[0-9A-Z]{6}[0-9]{2}[0-9]{8}$/;
   function repairUpsZ(ups) {
-    // Tesseract often reads the "1Z" anchor as "12" (or "IZ"). Repair it
-    // only when the rest has strict UPS structure AND the shipper segment
-    // contains a letter — real UPS shipper numbers do, random digit runs
-    // don't. Never invent numbers from thin air.
+    // Tesseract often reads the "1Z" anchor as "12" (or "IZ", or "17" —
+    // 7→Z confusion). Repair it only when the rest has strict UPS structure
+    // AND the shipper segment contains a letter — real UPS shipper numbers
+    // do, random digit runs don't. Never invent numbers from thin air.
     var cand = null;
     if (/^12[0-9A-Z]{16}$/.test(ups)) cand = '1Z' + ups.slice(2);
     else if (/^IZ[0-9A-Z]{16}$/i.test(ups)) cand = '1Z' + ups.slice(2);
+    else if (/^17[0-9A-Z]{16}$/.test(ups)) cand = '1Z' + ups.slice(2);
     if (!cand || !UPS_STRICT.test(cand)) return null;
     if (!/[A-Z]/.test(cand.slice(2, 8))) return null;
     return cand;
@@ -73,17 +74,55 @@
 
   // UPS number split by spaces/dashes: "1Z 9999 99 ..." (or "12 ..."/"IZ ..." misreads)
   function spacedUpsIn(text, found, seen, conf) {
-    var m, re = /\b(?:1Z|12|IZ)[\s-]?(?:[0-9A-Z][\s-]?){16}\b/gi;
+    // Anchor covers common 1Z misreads: 12, IZ, 17 (7→Z confusion)
+    var m, re = /\b(?:1Z|12|IZ|17)[\s-]?(?:[0-9A-Z][\s-]?){16}\b/gi;
     while ((m = re.exec(text)) !== null) {
       var ups = normalize(m[0]);
       var num = /^1Z[0-9A-Z]{16}$/.test(ups) ? ups : repairUpsZ(ups);
       if (num && !seen[num]) {
         seen[num] = true;
-        found.push({ number: num, carrier: 'ups', confidence: conf, ocr_fixed: num !== ups });
+        found.push({ number: num, carrier: 'ups', confidence: conf, ocr_fixed: num !== ups, ocr_path: true });
       }
     }
   }
 
+  // ---- UPS Mod-10 check digit ----
+  // Every real 1Z number carries a check digit (last char). This is the
+  // arbiter when blurry OCR produces 2↔Z / O↔0 style ambiguity: the wrong
+  // read fails the check, the right one passes. Verified against two real
+  // shipped labels (1Z1XJ5390328621735, 1ZGE23840337267306).
+  // Letter values: (alphabetical index + 1) mod 10 → A=2 … I=0, J=1 … Z=7.
+  var UPS_LETTER_VAL = {};
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('').forEach(function (ch, i) { UPS_LETTER_VAL[ch] = (i + 2) % 10; });
+  function upsCheckDigitOk(num) {
+    var n = String(num).toUpperCase();
+    if (!/^1Z[0-9A-Z]{16}$/.test(n)) return false;
+    var body = n.slice(2, 17); // 15 chars after 1Z, excluding check digit
+    var vals = [];
+    for (var i = 0; i < body.length; i++) {
+      var ch = body[i];
+      vals.push(ch >= '0' && ch <= '9' ? +ch : UPS_LETTER_VAL[ch]);
+    }
+    var odd = 0, even = 0;
+    for (var j = 0; j < vals.length; j++) { if (j % 2 === 0) odd += vals[j]; else even += vals[j]; }
+    var check = (10 - ((odd + even * 2) % 10)) % 10;
+    return check === +n[17];
+  }
+  // Try single-character OCR-confusion swaps until the check digit passes.
+  // A repair that validates is error correction, not invention.
+  var UPS_CHECK_CONFUSIONS = { 'Z': '2', '2': 'Z', 'O': '0', '0': 'O', 'I': '1', '1': 'I', 'S': '5', '5': 'S', 'B': '8', '8': 'B', 'G': '6', '6': 'G', 'A': '4', '4': 'A' };
+  function repairUpsCheckDigit(num) {
+    var upper = String(num).toUpperCase();
+    for (var i = 2; i < 18; i++) {
+      var rep = UPS_CHECK_CONFUSIONS[upper[i]];
+      if (!rep) continue;
+      var cand = upper.slice(0, i) + rep + upper.slice(i + 1);
+      if (!UPS_STRICT.test(cand)) continue;
+      if (upsCheckDigitOk(cand)) return cand;
+    }
+    return null;
+  }
+
   function extractTrackingNumbers(text) {
     var found = [];
     var seen = {};
@@ -105,6 +144,21 @@
     spacedDigitGroupsIn(text, found, seen, 'medium');
     // 2) OCR-tolerant recovery pass
     extractOcrTolerant(text, found, seen);
+    // 3) UPS check-digit gate: a 1Z candidate that fails the Mod-10 check is
+    // an OCR misread (2↔Z etc.). Repair it via confusion swaps when one
+    // validates; otherwise demote to review — never auto-add a wrong number.
+    for (var i = 0; i < found.length; i++) {
+      var c = found[i];
+      if (c.carrier !== 'ups' || c.confidence === 'low') continue;
+      if (!/^1Z[0-9A-Z]{16}$/i.test(c.number)) continue;
+      if (upsCheckDigitOk(c.number)) continue;
+      var fixed = (c.ocr_fixed || c.ocr_path) ? repairUpsCheckDigit(c.number) : null;
+      if (fixed) {
+        if (seen[fixed]) { found.splice(i, 1); i--; } // another pass already found it
+        else { seen[fixed] = true; c.number = fixed; c.ocr_fixed = true; }
+      }
+      else c.confidence = 'medium';
+    }
     var rank = { high: 0, medium: 1, low: 2 };
     found.sort(function (a, b) { return rank[a.confidence] - rank[b.confidence]; });
     return found;

package/public/index.html

@@ -4,7 +4,7 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
 <meta name="theme-color" content="#0a84ff">
-<meta name="app-version" content="0.3.25">
+<meta name="app-version" content="__APP_VERSION__">
 <title>HH Shipments</title>
 <link rel="manifest" href="/manifest.webmanifest">
 <link rel="apple-touch-icon" href="/icon-192.png">

package/server.js

@@ -599,7 +599,18 @@ app.get('/sw.js', (req, res) => {
     res.type('application/javascript').set('Cache-Control', 'no-cache').send(src.replace(/__APP_VERSION__/g, APP_VERSION));
   });
 });
+// Serve index.html dynamically with the real build version injected — the
+// Settings "app v" line reads this meta tag, and it was hardcoded at 0.3.25
+// for days, making every "confirm the version" check unverifiable. The
+// version line must never lie about the build on the phone.
+function serveIndex(req, res) {
+  fs.readFile(path.join(__dirname, 'public', 'index.html'), 'utf8', (err, src) => {
+    if (err) return res.sendStatus(404);
+    res.type('text/html').set('Cache-Control', 'no-cache').send(src.replace(/__APP_VERSION__/g, APP_VERSION));
+  });
+}
+app.get(['/', '/index.html'], serveIndex);
 app.use(express.static(path.join(__dirname, 'public')));
-app.get('*', (req, res) => res.sendFile(path.join(__dirname, 'public', 'index.html')));
+app.get('*', serveIndex);
 
 app.listen(PORT, () => console.log(`[hh-shipments] listening on :${PORT}`));

package/src/extract.js

@@ -189,7 +189,7 @@
         var num = repairUpsTail(expanded.slice(2)) || expanded;
         if (num && UPS_STRICT.test(num) && /[A-Z]/.test(num.slice(2, 8)) && !seen[num]) {
           seen[num] = true;
-          found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: true });
+          found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: true, ocr_path: true });
         }
       }
     }
@@ -216,7 +216,7 @@
       }
       if (num && !seen[num]) {
         seen[num] = true;
-        found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: num !== ups });
+        found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: num !== ups, ocr_path: true });
       }
     }
   }
@@ -250,11 +250,48 @@
       if (num && !seen[num]) {
         seen[num] = true;
         // repairUpsTail only returns strict-validated numbers: trust them.
-        found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: true });
+        found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: true, ocr_path: true });
       }
     }
   }
 
+  // ---- UPS Mod-10 check digit ----
+  // Every real 1Z number carries a check digit (last char). This is the
+  // arbiter when blurry OCR produces 2↔Z / O↔0 style ambiguity: the wrong
+  // read fails the check, the right one passes. Verified against two real
+  // shipped labels (1Z1XJ5390328621735, 1ZGE23840337267306).
+  // Letter values: (alphabetical index + 1) mod 10 → A=2 … I=0, J=1 … Z=7.
+  var UPS_LETTER_VAL = {};
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('').forEach(function (ch, i) { UPS_LETTER_VAL[ch] = (i + 2) % 10; });
+  function upsCheckDigitOk(num) {
+    var n = String(num).toUpperCase();
+    if (!/^1Z[0-9A-Z]{16}$/.test(n)) return false;
+    var body = n.slice(2, 17); // 15 chars after 1Z, excluding check digit
+    var vals = [];
+    for (var i = 0; i < body.length; i++) {
+      var ch = body[i];
+      vals.push(ch >= '0' && ch <= '9' ? +ch : UPS_LETTER_VAL[ch]);
+    }
+    var odd = 0, even = 0;
+    for (var j = 0; j < vals.length; j++) { if (j % 2 === 0) odd += vals[j]; else even += vals[j]; }
+    var check = (10 - ((odd + even * 2) % 10)) % 10;
+    return check === +n[17];
+  }
+  // Try single-character OCR-confusion swaps until the check digit passes.
+  // A repair that validates is error correction, not invention.
+  var UPS_CHECK_CONFUSIONS = { 'Z': '2', '2': 'Z', 'O': '0', '0': 'O', 'I': '1', '1': 'I', 'S': '5', '5': 'S', 'B': '8', '8': 'B', 'G': '6', '6': 'G', 'A': '4', '4': 'A' };
+  function repairUpsCheckDigit(num) {
+    var upper = String(num).toUpperCase();
+    for (var i = 2; i < 18; i++) {
+      var rep = UPS_CHECK_CONFUSIONS[upper[i]];
+      if (!rep) continue;
+      var cand = upper.slice(0, i) + rep + upper.slice(i + 1);
+      if (!UPS_STRICT.test(cand)) continue;
+      if (upsCheckDigitOk(cand)) return cand;
+    }
+    return null;
+  }
+
   function extractTrackingNumbers(text) {
     var found = [];
     var seen = {};
@@ -267,7 +304,8 @@
       runPatterns(z.text, found, seen, z.carrier);
       spacedUpsIn(z.text, found, seen, 'high');
       looseUpsIn(z.text, found, seen, 'high');
-      spacedDigitGroupsIn(z.text, found, seen, 'high');
+      spacedDigitGroupsIn(z.text, found, seen, 'high', z.carrier);
+      if (z.carrier === 'ups') upsAnchorlessRecovery(z.text, found, seen);
     });
     // 1) Whole-text strict patterns
     runPatterns(text, found, seen, false);
@@ -277,6 +315,23 @@
     spacedDigitGroupsIn(text, found, seen, 'medium');
     // 2) OCR-tolerant recovery pass
     extractOcrTolerant(text, found, seen);
+    // 3) UPS check-digit gate: a 1Z candidate that fails the Mod-10 check is
+    // an OCR misread (2↔Z etc.). On OCR-path candidates, repair it via
+    // confusion swaps when one validates; otherwise demote to review.
+    // Clean (non-OCR) reads are never rewritten — a typed typo goes to
+    // review, not silently "fixed" into a different number.
+    for (var i = 0; i < found.length; i++) {
+      var c = found[i];
+      if (c.carrier !== 'ups' || c.confidence === 'low') continue;
+      if (!/^1Z[0-9A-Z]{16}$/i.test(c.number)) continue;
+      if (upsCheckDigitOk(c.number)) continue;
+      var fixed = (c.ocr_fixed || c.ocr_path) ? repairUpsCheckDigit(c.number) : null;
+      if (fixed) {
+        if (seen[fixed]) { found.splice(i, 1); i--; } // another pass already found it
+        else { seen[fixed] = true; c.number = fixed; c.ocr_fixed = true; }
+      }
+      else c.confidence = 'medium';
+    }
     var rank = { high: 0, medium: 1, low: 2 };
     found.sort(function (a, b) { return rank[a.confidence] - rank[b.confidence]; });
     return found;
@@ -305,7 +360,10 @@
       // anchor line + the two lines under it (the number is printed below)
       var slice = lines.slice(i, Math.min(lines.length, i + 3));
       var carrier = null;
-      slice.forEach(function (sl) { carrier = carrier || anchorCarrier(sl); });
+      // Scan the slice AND the line above it: "UPS GROUND" typically sits
+      // directly above the "TRACKING #:" line, and the zone needs to know.
+      var scan = slice.concat(i > 0 ? [lines[i - 1]] : []);
+      scan.forEach(function (sl) { carrier = carrier || anchorCarrier(sl); });
       zones.push({ text: slice.join('\n'), carrier: carrier });
     }
     return zones;
@@ -377,7 +435,11 @@
   // contains a separator (contiguous runs are already covered by PATTERNS).
   // Joined candidates must validate against a carrier format; IMpb barcodes
   // yield their tracking number, never the routing.
-  function spacedDigitGroupsIn(text, found, seen, conf) {
+  // zoneCarrier: when the anchor zone names a carrier ("UPS GROUND"), a
+  // candidate of any OTHER carrier is a fragment of the real number
+  // ("03 3985 0416" off a UPS label is not a DHL shipment) — demote it to
+  // low so it can only ever surface for review, never auto-add.
+  function spacedDigitGroupsIn(text, found, seen, conf, zoneCarrier) {
     var re = /\b\d(?:[\s-]?\d){9,33}\b/g, m;
     while ((m = re.exec(text)) !== null) {
       if (!/[\s-]/.test(m[0])) continue;
@@ -387,13 +449,34 @@
       var impb = parseImpb(num);
       if (impb) {
         seen[num] = true;
-        if (!seen[impb]) { seen[impb] = true; found.push({ number: impb, carrier: 'usps', confidence: conf }); }
+        var ic = (zoneCarrier && zoneCarrier !== 'usps') ? 'low' : conf;
+        if (!seen[impb]) { seen[impb] = true; found.push({ number: impb, carrier: 'usps', confidence: ic }); }
         continue;
       }
       var carrier = guessCarrier(num);
       if (carrier === 'unknown') { seen[num] = true; continue; }
       seen[num] = true;
-      found.push({ number: num, carrier: carrier, confidence: conf });
+      var c = (zoneCarrier && carrier !== zoneCarrier) ? 'low' : conf;
+      found.push({ number: num, carrier: carrier, confidence: c });
+    }
+  }
+
+  // Last resort for UPS zones: the "1Z" anchor itself was unreadable, so the
+  // number survives only as a 16-char alphanumeric tail ("X01 48H 03 3985
+  // 0416"). If it validates as strict UPS tail structure, offer 1Z+tail at
+  // medium (review-only, never auto-add) — far better than a DHL fragment.
+  var UPS_TAIL_STRICT = /^[0-9A-Z]{6}[0-9]{2}[0-9]{8}$/;
+  function upsAnchorlessRecovery(text, found, seen) {
+    var re = /\b([0-9A-Z](?:[\s-]?[0-9A-Z]){15})\b/gi, m;
+    while ((m = re.exec(text)) !== null) {
+      var token = normalize(m[1]);
+      if (/^(1Z|12|IZ|17)/i.test(token)) continue; // anchored — handled elsewhere
+      if (!UPS_TAIL_STRICT.test(token)) continue;
+      if (!/[A-Z]/.test(token.slice(0, 6))) continue; // real shipper codes have a letter
+      var num = '1Z' + token;
+      if (seen[num]) continue;
+      seen[num] = true;
+      found.push({ number: num, carrier: 'ups', confidence: 'medium', ocr_fixed: true, ocr_path: true });
     }
   }