pour-engine 1.38.0 → 1.41.0

package/engine/COVERAGE.md

@@ -3,8 +3,10 @@
 Generated by `node scripts/wcag-coverage.js` — do not edit by hand.
 
 All 86 success criteria of WCAG 2.2, and how the native engine covers them.
-"Partially automated" means our rules catch common failures but cannot prove conformance;
-"Manual review" criteria need a human (most of the spec — true for every automated tool).
+"Partially automated" means rules check some aspects or identify candidates for human review.
+Some rules return review findings only; a listed rule does not promise an automatic violation verdict.
+"Manual review" means no active rule currently assists with that criterion. Human review is also
+needed for partially automated criteria; no rule proves conformance.
 No criterion is listed as fully "Automated": every one of them ends in a question about
 meaning that only a person can settle, even where a rule decides most real pages.
 

package/engine/README.md

@@ -7,8 +7,9 @@ the product's only engine.
 **WCAG only, by design.** pour engine tracks the WCAG spec exclusively — no
 Section 508, EN 301 549, or other standards. The full WCAG 2.2 catalog (all
 86 success criteria) lives in `wcag22.js`, and `COVERAGE.md` (generated by
-`node scripts/wcag-coverage.js`) shows exactly which criteria are automated,
-partially automated, or need human review. `AUDIT.html` is the latest full
+`node scripts/wcag-coverage.js`) shows which criteria have automated assistance
+and which currently rely on the manual checklist. Assistance includes checks
+that only nominate candidates for human review. `AUDIT.html` is the latest full
 spec-sweep audit of every rule against the spec — over-violation,
 under-violation, and what the engine cannot test. It is a self-contained
 page: open it straight from disk in any browser. Regenerated by running
@@ -103,12 +104,16 @@ just to static analysis.
 Rules alone can never "cover WCAG" — most criteria need human judgment.
 pour engine therefore reports on **every** in-scope criterion, one of two ways:
 
-1. **Automated/partial** — the rules in `rules/`.
+1. **Automated assistance**: the rules in `rules/` either establish specific
+   failures or nominate review candidates. A rule may return only review
+   findings when the DOM cannot establish a violation.
 2. **Manual review** — every audit's results include `manualReview`: the
    in-scope criteria (filtered by the requested WCAG version and level)
    that automation can't judge, for a host to render however it wants.
 
-Nothing in the spec is silently skipped — that claim is the product.
+The checklist accounts for the criteria; it does not mean every page state
+or possible failure has been tested. A snapshot audit still needs human
+assessment, including interaction states and any checks reported as skipped.
 
 ## Honest current state
 

package/engine/index.js

@@ -4,7 +4,7 @@
 import config from '../config/project.config.js';
 import rules from './rules/index.js';
 import wcagCatalog from './wcag22.js';
-import { isVisible, isRendered, cssPath, htmlSnippet, ownText, collectRoots } from './lib/dom.js';
+import { isVisible, isRendered, cssPath, htmlSnippet, ownText, collectRoots, resetDOMCaches, releaseDOMCaches } from './lib/dom.js';
 import { accessibleName } from './lib/accessible-name.js';
 import { resetAuditCaches } from './lib/contrast.js';
 
@@ -116,18 +116,23 @@ export async function run(context = document, options = {}, onProgress) {
   // Per-audit caches (resolved backgrounds, opacities) must start fresh —
   // the page may have changed since the last run.
   resetAuditCaches();
+  resetDOMCaches();
   // Every queryable root — the page plus all open shadow trees — collected
   // once so rules see web-component content without re-walking per rule.
   const roots = collectRoots(context.querySelectorAll ? context : document);
   // Universal-selector rules (aria attribute checks) share one full scan
   // instead of each re-enumerating every element on the page.
   let universalScan = null;
+  const query = (root, selector) => [
+    ...(root.nodeType === 1 && root.matches(selector) ? [root] : []),
+    ...root.querySelectorAll(selector),
+  ];
   const elementsFor = (selector) => {
     if (selector === '*') {
-      universalScan ??= roots.flatMap((root) => [...root.querySelectorAll('*')]);
+      universalScan ??= roots.flatMap((root) => query(root, '*'));
       return universalScan;
     }
-    return roots.flatMap((root) => [...root.querySelectorAll(selector)]);
+    return roots.flatMap((root) => query(root, selector));
   };
   let completed = 0;
   // Running totals so the UI can count issues up live as rules finish —
@@ -161,6 +166,16 @@ export async function run(context = document, options = {}, onProgress) {
     lastYield = performance.now();
   };
 
+  const checkAbort = () => {
+    if (options.signal?.aborted) throw new DOMException('Audit stopped', 'AbortError');
+  };
+  // Bulk rules use the same task budget and cancellation as per-node rules.
+  const helpers = { ...ruleHelpers, yieldToMain: async () => {
+    checkAbort();
+    await yieldToRenderer();
+    checkAbort();
+  } };
+  try {
   for (const rule of activeRules) {
     // Between rules is the abort granularity we have — the same boundary
     // the renderer yield uses.
@@ -186,7 +201,7 @@ export async function run(context = document, options = {}, onProgress) {
     if (rule.evaluateAll) {
       // Awaiting a plain array is a no-op, so sync evaluateAll rules are
       // untouched — async ones (the deferred-reference probe) resolve here.
-      outcomes = await rule.evaluateAll(elements, ruleHelpers);
+      outcomes = await rule.evaluateAll(elements, helpers);
     } else {
       // Evaluate sequentially with periodic yields so ONE heavy rule on a
       // huge element set can't freeze the page for its whole duration —
@@ -204,7 +219,7 @@ export async function run(context = document, options = {}, onProgress) {
             running: true,
           }));
         }
-        outcomes[i] = await rule.evaluate(elements[i], ruleHelpers);
+        outcomes[i] = await rule.evaluate(elements[i], helpers);
       }
     }
 
@@ -214,14 +229,19 @@ export async function run(context = document, options = {}, onProgress) {
     // large pages.
     const buckets = { fail: [], incomplete: [] };
     let passCount = 0;
-    elements.forEach((element, i) => {
+    let skippedCount = 0;
+    for (let i = 0; i < elements.length; i++) {
+      if ((i & 127) === 0) await helpers.yieldToMain();
+      const element = elements[i];
       const status = outcomes[i].status;
       if (status === 'pass') passCount += 1;
+      else if (status === 'skipped') skippedCount += 1;
       else buckets[status]?.push(toResultNode(element, outcomes[i]));
-    });
+    }
 
     const ruleResult = {
       id: rule.id,
+      ...(skippedCount ? { skippedCount } : {}),
       // Human display name ("Form field labels"); the id stays the
       // machine handle everywhere (selectors, exports, docs anchors).
       name: rule.name ?? rule.id,
@@ -241,7 +261,8 @@ export async function run(context = document, options = {}, onProgress) {
     if (buckets.fail.length) liveTypeCounts[rule.impact] = (liveTypeCounts[rule.impact] ?? 0) + 1;
     if (buckets.incomplete.length) liveTypeCounts.review += 1;
     const ms = Math.round((performance.now() - ruleStarted) * 10) / 10;
-    results.ruleTimings.push({ rule: rule.id, ms, elements: elements.length });
+    results.ruleTimings.push({ rule: rule.id, ms, elements: elements.length, ...(skippedCount ? { skippedCount } : {}) });
+    if (skippedCount) results.skippedChecks = (results.skippedChecks ?? 0) + skippedCount;
     onProgress?.({
       done: ++completed,
       total: activeRules.length,
@@ -263,4 +284,9 @@ export async function run(context = document, options = {}, onProgress) {
 
   results.durationMs = Math.round(performance.now() - auditStarted);
   return results;
+  } finally {
+    releaseDOMCaches();
+    yieldChannel?.port1.close();
+    yieldChannel?.port2.close();
+  }
 }

package/engine/lib/accessible-name.js

@@ -2,8 +2,10 @@
 // the ARIA accname spec: aria-labelledby → aria-label → native labelling
 // (alt, <label>, text content, value) → title/placeholder fallbacks.
 //
-// Deliberately simpler than the full spec. Good enough for name-presence
-// rules; grow it as rules need more.
+// This DOM implementation follows the recursive naming paths used by the
+// rules. Browser accessibility trees remain the behavioral check for edge
+// cases; text presence alone is not a full assessment of name quality.
+import { flatTreeParent } from './dom.js';
 
 /** Input types whose `.value` is user-entered text rather than a state. */
 const TEXT_INPUT = new Set(['text', 'search', 'url', 'tel', 'email', 'password', 'number', 'date',
@@ -15,7 +17,7 @@ const TEXT_INPUT = new Set(['text', 'search', 'url', 'tel', 'email', 'password',
 const LABELABLE = new Set(['input', 'select', 'textarea', 'button', 'meter', 'output', 'progress']);
 
 export function accessibleName(element) {
-  return computeName(element, false);
+  return computeName(element, false, false, new Set());
 }
 
 /** The name aria-labelledby contributes, resolved the way accname requires:
@@ -24,27 +26,48 @@ export function accessibleName(element) {
  *  too, and reading textContent instead reports those elements as nameless.
  *  Rules that only need "is it labelled?" call this directly. */
 export function labelledByName(element) {
+  return referencedName(element, new Set()) ?? '';
+}
+
+/** Native label text, excluding the control being named from recursion. */
+export function nativeLabelName(element, label) {
+  return computeName(label, false, hiddenForName(label), new Set([element]));
+}
+
+// Accname 2A: only a reference whose root is itself hidden includes its
+// hidden descendants. A visible reference does not resurrect hidden text.
+function hiddenForName(element) {
+  for (let node = element; node; node = flatTreeParent(node)) {
+    if (node.getAttribute?.('aria-hidden') === 'true') return true;
+    const style = getComputedStyle(node);
+    if (style.display === 'none') return true;
+  }
+  const visibility = getComputedStyle(element).visibility;
+  return visibility === 'hidden' || visibility === 'collapse';
+}
+
+function referencedName(element, visited) {
   const refs = element.getAttribute?.('aria-labelledby');
-  if (!refs) return '';
+  if (!refs) return null;
   const root = element.getRootNode();
-  return refs
-    .split(/\s+/)
-    .filter(Boolean)
-    .map((id) => {
-      const target = root.getElementById?.(id);
-      return target ? computeName(target, true) : '';
-    })
-    .join(' ')
-    .replace(/\s+/g, ' ')
-    .trim();
+  const targets = refs.split(/\s+/).filter(Boolean).map((id) => root.getElementById?.(id)).filter(Boolean);
+  if (!targets.length) return null;
+  return targets.map((target) => {
+    // Self-reference can contribute the element's aria-label or content,
+    // but does not follow aria-labelledby again (accname 2B).
+    const path = new Set(visited);
+    if (target === element) path.delete(element);
+    return computeName(target, true, hiddenForName(target), path);
+  }).join(' ').replace(/\s+/g, ' ').trim();
 }
 
-function computeName(element, inLabelledBy) {
-  // accname step 2B: a referenced element's own aria-labelledby is not
-  // followed a second time. That is also what stops <p id="a"
-  // aria-labelledby="a"> recursing forever.
+function computeName(element, inLabelledBy, includeHidden, visited) {
+  if (visited.has(element)) return '';
+  visited.add(element);
   if (!inLabelledBy) {
-    const fromLabelledBy = labelledByName(element);
+    const fromLabelledBy = referencedName(element, visited);
+    // Browsers retain aria-label/content fallbacks when all referenced
+    // text is empty. Do not assert a missing name that is actually exposed.
     if (fromLabelledBy) return fromLabelledBy;
   }
 
@@ -64,7 +87,8 @@ function computeName(element, inLabelledBy) {
   // id="b"> from the label. Widened from the three field tags 2026-08-25
   // overnight audit: button-name was asserting a label-named button nameless.
   if (LABELABLE.has(tag) && element.labels?.length) {
-    const text = [...element.labels].map((label) => label.textContent).join(' ').trim();
+    const text = [...element.labels].map((label) =>
+      computeName(label, inLabelledBy, hiddenForName(label), visited)).join(' ').trim();
     if (text) return text;
   }
 
@@ -98,27 +122,43 @@ function computeName(element, inLabelledBy) {
   // display:none/visibility:hidden subtrees does not name an element
   // (per the accname spec). The one exception is a subtree reached THROUGH
   // aria-labelledby, where accname ignores the hidden state.
-  const fromContents = visibleContentText(element, inLabelledBy).replace(/\s+/g, ' ').trim();
+  const fromContents = visibleContentText(element, includeHidden, inLabelledBy, visited).replace(/\s+/g, ' ').trim();
   if (fromContents) return fromContents;
 
   return (element.getAttribute('title') ?? element.getAttribute('placeholder') ?? '').trim();
 }
 
-function visibleContentText(element, includeHidden) {
+function visibleContentText(element, includeHidden, inLabelledBy, visited) {
   // A custom element with a shadow root renders its shadow content — name
   // from contents follows the FLAT tree (slots inside pull light DOM back).
   const nodes = element.shadowRoot ? element.shadowRoot.childNodes : element.childNodes;
-  return generatedContent(element, '::before')
-    + textFromNodes(nodes, includeHidden)
-    + generatedContent(element, '::after');
+  return generatedContent(element, '::before', includeHidden)
+    + textFromNodes(nodes, includeHidden, inLabelledBy, visited)
+    + generatedContent(element, '::after', includeHidden);
 }
 
 /** CSS generated content contributes to name-from-contents per the accname
  *  spec — icon-font prefixes and content:"…" labels are real names. Only
- *  plain strings count: counters, url(), attr() are not resolvable here. */
-function generatedContent(element, pseudo) {
-  const content = getComputedStyle(element, pseudo).content;
+ *  plain strings count: counters, url(), attr() are not resolvable here.
+ *
+ *  The exception is the CSS alternative text syntax, content: <image or
+ *  string> / "alt", which exists precisely to give assistive technology the
+ *  text for generated content and which browsers expose: an icon-only button
+ *  drawn with content: url(menu.svg) / "Menu" IS named "Menu" (Chromium's
+ *  accessibility tree agrees), and calling it nameless asserted a critical
+ *  4.1.2 failure against the recommended pattern. An EMPTY alternative marks
+ *  the generated content decorative and contributes nothing, which is how
+ *  the same syntax silences icon glyphs. */
+function generatedContent(element, pseudo, includeHidden) {
+  const style = getComputedStyle(element, pseudo);
+  // Generated nodes follow the same hidden-content exclusion as ordinary
+  // descendants. A hover label can exist in computed content while its
+  // pseudo-element is visibility:hidden and absent from the AX name.
+  if (!includeHidden && (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse')) return '';
+  const content = style.content;
   if (!content || content === 'none' || content === 'normal') return '';
+  const alt = content.match(/\/\s*"((?:[^"\\]|\\.)*)"\s*$/);
+  if (alt) return alt[1].replace(/\\(.)/g, '$1');
   const match = content.match(/^"((?:[^"\\]|\\.)*)"$/);
   return match ? match[1].replace(/\\(.)/g, '$1') : '';
 }
@@ -126,7 +166,7 @@ function generatedContent(element, pseudo) {
 /** `includeHidden` is set while resolving an aria-labelledby target: accname
  *  ignores the hidden state of referenced content, which is what makes the
  *  visually-hidden label span (and the display:none one) work in browsers. */
-function textFromNodes(nodes, includeHidden) {
+function textFromNodes(nodes, includeHidden, inLabelledBy, visited) {
   let text = '';
   for (const node of nodes) {
     if (node.nodeType === 3 /* TEXT_NODE */) {
@@ -141,50 +181,27 @@ function textFromNodes(nodes, includeHidden) {
     // with lazy-load <noscript> fallbacks leaking "<img …>" into names).
     if (tag === 'script' || tag === 'style' || tag === 'noscript' || tag === 'template') continue;
     if (!includeHidden) {
-      if (node.getAttribute('aria-hidden') === 'true' || node.hasAttribute('hidden')) continue;
+      if (node.getAttribute('aria-hidden') === 'true') continue;
       const style = getComputedStyle(node);
-      if (style.display === 'none' || style.visibility === 'hidden') continue;
+      if (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse') continue;
     }
     // A slot renders its assigned light-DOM nodes (fallback children when
     // nothing is slotted) — a shadow <button><slot></slot></button> is named
     // by the text the page slots in.
     if (tag === 'slot') {
       const assigned = node.assignedNodes?.() ?? [];
-      text += textFromNodes(assigned.length ? assigned : node.childNodes, includeHidden);
+      text += textFromNodes(assigned.length ? assigned : node.childNodes, includeHidden, inLabelledBy, visited);
       continue;
     }
-    if (tag === 'img' || tag === 'area') {
-      // HTML-AAM order for an image's own name: aria-label → alt → title.
-      // A PRESENT-but-empty alt marks the image decorative and contributes
-      // nothing — title must not resurrect it. Only when alt is ABSENT do
-      // the fallbacks apply (a title-only <img> inside a link names the
-      // link; Chromium exposes exactly this, measured on a live site where
-      // the walk's old alt-or-nothing shortcut called a named link nameless).
-      const imgAria = node.getAttribute('aria-label')?.trim();
-      if (imgAria) { text += ` ${imgAria} `; continue; }
-      const alt = node.getAttribute('alt');
-      if (alt !== null) { text += ` ${alt} `; continue; }
-      const imgTitle = node.getAttribute('title')?.trim();
-      if (imgTitle) text += ` ${imgTitle} `;
-      continue;
-    }
-    const ariaLabel = node.getAttribute('aria-label')?.trim();
-    if (ariaLabel) {
-      text += ` ${ariaLabel} `;
-      continue;
-    }
-    // Flat-tree descent: shadow content renders in place of a host's
-    // light children (archive.org-style nested web components).
-    const fromSubtree = textFromNodes(node.shadowRoot ? node.shadowRoot.childNodes : node.childNodes, includeHidden);
-    if (fromSubtree.trim()) {
-      text += fromSubtree;
-      continue;
-    }
-    // Accname's tooltip fallback applies per traversed element: a
-    // text-less <div title="upvote"> inside a link names it "upvote"
-    // (browsers and screen readers both honour this).
-    const title = node.getAttribute('title')?.trim();
-    if (title) text += ` ${title} `;
+    // Every descendant re-enters the naming algorithm, including its
+    // references, native labels and generated content (accname 2F).
+    // Empty alt remains decorative rather than falling through to title.
+    if ((tag === 'img' || tag === 'area') && node.getAttribute('alt') === ''
+      && !node.getAttribute('aria-label')?.trim() && !node.getAttribute('aria-labelledby')) continue;
+    const childName = computeName(node, inLabelledBy, includeHidden, visited);
+    text += tag === 'img' || tag === 'area' || node.hasAttribute('aria-label') || node.hasAttribute('aria-labelledby')
+      ? ` ${childName} ` : childName;
+
   }
   return text;
 }

package/engine/lib/contrast.js

@@ -132,6 +132,9 @@ let panelRectsCache = null;
 let pseudoCache = new WeakMap();
 let zeroClipCache = new WeakMap();
 let firstLineRulesCache = new WeakMap();
+let chainEffectCache = new WeakMap();
+let uncoveredEffectCache = new WeakMap();
+let blendBackdropCache = new WeakMap();
 const HAS_IMAGE = Symbol('background-image in chain');
 
 export function resetAuditCaches() {
@@ -143,6 +146,100 @@ export function resetAuditCaches() {
   pseudoCache = new WeakMap();
   zeroClipCache = new WeakMap();
   firstLineRulesCache = new WeakMap();
+  chainEffectCache = new WeakMap();
+  uncoveredEffectCache = new WeakMap();
+  blendBackdropCache = new WeakMap();
+}
+
+const flatParentOf = (node) => node.assignedSlot ?? node.parentElement ?? node.getRootNode()?.host ?? null;
+
+/** Every filter function except drop-shadow recolours the pixels it applies
+ *  to (blur, grayscale, invert, url() and the rest). A drop shadow paints a
+ *  copy of the element's silhouette BEHIND it and leaves its own pixels
+ *  alone. Parsed at nesting depth zero so the rgba() inside a shadow is not
+ *  read as a second function. */
+function colourChangingFilter(filter) {
+  if (!filter || filter === 'none') return false;
+  let depth = 0;
+  let name = '';
+  for (const ch of filter) {
+    if (ch === '(') {
+      if (depth === 0 && name && name !== 'drop-shadow') return true;
+      depth += 1;
+      name = '';
+    } else if (ch === ')') {
+      depth -= 1;
+    } else if (depth === 0) {
+      name = /[a-z-]/i.test(ch) ? name + ch.toLowerCase() : '';
+    }
+  }
+  return false;
+}
+
+/** A colour-changing filter or a blend mode on the element or any flat-tree
+ *  ancestor recolours the text no matter what is painted in between: a
+ *  greyscale group is grey throughout, and a group blend blends the whole
+ *  group, opaque cards included, against what lies behind it. */
+function chainEffect(node) {
+  if (!node || node.nodeType !== 1) return false;
+  if (chainEffectCache.has(node)) return chainEffectCache.get(node);
+  const style = getComputedStyle(node);
+  const own = colourChangingFilter(style.filter) || (style.mixBlendMode && style.mixBlendMode !== 'normal');
+  const result = Boolean(own || chainEffect(flatParentOf(node)));
+  chainEffectCache.set(node, result);
+  return result;
+}
+
+/** A backdrop filter and a drop shadow only reach the text through paint
+ *  that is not opaque: the frosted-glass header (backdrop-filter: blur on a
+ *  translucent bar) shows the blurred page through everything up to the
+ *  first opaque background, and a drop shadow on a transparent wrapper is a
+ *  shadow of the glyphs themselves. Opaque paint at or below the effect
+ *  covers it, so the text's backdrop is that paint and the effect is not an
+ *  uncertainty. Measured 2026-09-12: 72 of 184 such reviews on nine sites
+ *  had opaque paint between the text and the effect. */
+function uncoveredEffect(node) {
+  if (!node || node.nodeType !== 1) return false;
+  if (uncoveredEffectCache.has(node)) return uncoveredEffectCache.get(node);
+  const style = getComputedStyle(node);
+  let result;
+  if ((parseColor(style.backgroundColor)?.a ?? 0) >= 1) result = false; // everything above is covered
+  else if ((style.backdropFilter && style.backdropFilter !== 'none') || (style.filter && style.filter !== 'none')) result = true;
+  else result = uncoveredEffect(flatParentOf(node));
+  uncoveredEffectCache.set(node, result);
+  return result;
+}
+
+/** Filters and blend modes change the presented glyph/background pair.
+ * WCAG judges that presented pair, not the unfiltered CSS declarations.
+ * Cached per node along the flat tree so ordinary text pays once per
+ * ancestor. */
+export function hasPaintEffects(element) {
+  if (!element || element.nodeType !== 1) return false;
+  return chainEffect(element) || uncoveredEffect(element);
+}
+
+/** A blend cannot reach paint outside its containing isolated group.
+ * Stop at opaque paint inside that group; otherwise an intervening stacking
+ * context means the ordinary ancestor background is not a proven backdrop. */
+export function isolatedBlendBackdrop(element) {
+  if (!element || element.nodeType !== 1) return false;
+  if (blendBackdropCache.has(element)) return blendBackdropCache.get(element);
+  const style = getComputedStyle(element);
+  const background = parseColor(style.backgroundColor);
+  let result = false;
+  if (!background || background.a < 1) {
+    const isolated = style.isolation === 'isolate'
+      || ['fixed', 'sticky'].includes(style.position) || style.zIndex !== 'auto'
+      || ['transform', 'perspective', 'filter', 'backdropFilter', 'clipPath', 'maskImage', 'webkitMaskImage']
+        .some((key) => style[key] && style[key] !== 'none')
+      || /(?:paint|layout|strict|content)/.test(style.contain)
+      || (style.willChange && style.willChange !== 'auto')
+      || parseFloat(style.opacity) < 1;
+    result = isolated || isolatedBlendBackdrop(element.assignedSlot ?? element.parentElement ?? element.getRootNode()?.host);
+  }
+  blendBackdropCache.set(element, result);
+  return result;
 }
 
 /**
@@ -1233,11 +1330,12 @@ export function sampleGridFor(extent) {
   return { width, height, reduced: extent.width / width > 4.5 || extent.height / height > 4.5 };
 }
 
-export function imageLuminanceRange(url, overlays = [], grid = null) {
+export function imageLuminanceRange(url, overlays = [], grid = null, under = null) {
   const width = grid?.width ?? 32;
   const height = grid?.height ?? 32;
   const sizeKey = width === 32 && height === 32 ? '' : `|${width}x${height}`;
-  const cacheKey = `${url}${overlays.length ? `|${overlayKey(overlays)}` : ''}${sizeKey}`;
+  const backdrop = under?.a >= 1 ? under : null;
+  const cacheKey = `${url}${overlays.length ? `|${overlayKey(overlays)}` : ''}${sizeKey}${backdrop ? `|under:${overlayKey([backdrop])}` : ''}`;
   if (imageRangeCache.has(cacheKey)) return imageRangeCache.get(cacheKey);
   const promise = new Promise((resolve) => {
     const img = new Image();
@@ -1252,8 +1350,8 @@ export function imageLuminanceRange(url, overlays = [], grid = null) {
         const ctx = canvas.getContext('2d', { willReadFrequently: true });
         ctx.drawImage(img, 0, 0, width, height);
         const data = ctx.getImageData(0, 0, width, height).data;
-        let min = 1;
-        let max = 0;
+        let min = Infinity;
+        let max = -Infinity;
         // The colours at those extremes, kept for the same reason the
         // gradient range keeps them: translucent text blends with the actual
         // pixels, and a luminance cannot be un-gamma'd back into an rgb.
@@ -1266,19 +1364,22 @@ export function imageLuminanceRange(url, overlays = [], grid = null) {
           // painted beneath it — the sampled range alone then describes only
           // the ink, not the backdrop the eye meets. Callers widen the range
           // with the underlying paint (rangeWithBackdrop) or abstain.
-          if (data[i + 3] < 255) alphaSeen = true;
-          if (data[i + 3] < 128) continue; // mostly-transparent pixels reveal what's beneath — unknowable
-          opaquePixels += 1;
+          if (data[i + 3] < 255 && !backdrop) alphaSeen = true;
+          if (data[i + 3] > 0) opaquePixels += 1;
+          if (data[i + 3] === 0 && !backdrop) continue;
           // Composite each pixel through anything painted between the image
           // and the text before measuring: a photo under a 75% black scrim is
           // seen as the blend, never as the photo.
-          const pixel = { r: data[i], g: data[i + 1], b: data[i + 2], a: 1 };
-          const shown = overlays.length ? applyOverlays(pixel, overlays) : pixel;
+          const pixel = { r: data[i], g: data[i + 1], b: data[i + 2], a: data[i + 3] / 255 };
+          // A nonzero alpha is real paint. Composite over a known backdrop
+          // before sampling; without one, keep the conservative raw range.
+          const painted = backdrop ? composite(pixel, backdrop) : { ...pixel, a: 1 };
+          const shown = overlays.length ? applyOverlays(painted, overlays) : painted;
           const l = luminance(shown);
           if (l < min) { min = l; minColor = shown; }
           if (l > max) { max = l; maxColor = shown; }
         }
-        // Not one opaque pixel: a spacer, a cleared sprite, or a decorative
+        // Not one nontransparent pixel: a spacer, a cleared sprite, or a decorative
         // layer left in place with nothing in it. It covers the background
         // without changing a single one of its pixels.
         if (!opaquePixels) {