@bicharts/chart-host 0.5.73 → 0.5.74

package/dist/{chunk-D3DERYG3.mjs → chunk-E6P2ZMGC.mjs}

@@ -1972,6 +1972,267 @@ function fitRenderedChart(container, opts = {}) {
   return result;
 }
 
+// src/labelContrast.ts
+function parseRGBA(c) {
+  if (typeof c !== "string") return null;
+  const s = c.trim();
+  const m2 = s.match(/^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)$/i);
+  if (m2) return [parseFloat(m2[1]), parseFloat(m2[2]), parseFloat(m2[3]), m2[4] !== void 0 ? parseFloat(m2[4]) : 1];
+  let h2 = s.replace(/^#/, "");
+  if (h2.length === 3) h2 = h2.split("").map((ch) => ch + ch).join("");
+  if (h2.length === 6 && /^[0-9a-fA-F]{6}$/.test(h2)) {
+    return [parseInt(h2.slice(0, 2), 16), parseInt(h2.slice(2, 4), 16), parseInt(h2.slice(4, 6), 16), 1];
+  }
+  return null;
+}
+var DARK_TEXT = "#111111";
+var LIGHT_TEXT = "#ffffff";
+var MIN_CONTRAST = 3;
+var WHITE_TEXT_BG_LUM = 0.5;
+var PILL_MIN_ALPHA = 0.05;
+var PILL_OPAQUE_ALPHA = 0.85;
+var PAGE_MATCH_TOLERANCE = 2;
+function isPillBackdropAlpha(a2) {
+  return a2 >= PILL_MIN_ALPHA && a2 < PILL_OPAQUE_ALPHA;
+}
+var PILL_MIN_COVERAGE = 0.6;
+function pillBacksGlyph(overlapArea, glyphArea) {
+  if (!(glyphArea > 0) || !isFinite(overlapArea) || overlapArea <= 0) return false;
+  return overlapArea / glyphArea >= PILL_MIN_COVERAGE;
+}
+var BACKING_MAJORITY = 0.5;
+function backingHoldsGlyph(backedArea, glyphArea) {
+  if (!(glyphArea > 0) || !isFinite(backedArea) || backedArea <= 0) return false;
+  return backedArea / glyphArea >= BACKING_MAJORITY;
+}
+function cellSuppressesNormalize(cellClass) {
+  return typeof cellClass === "string" && /(^|\s)lch-deck-panel(\s|$)/.test(cellClass);
+}
+var NAMED = {
+  white: [255, 255, 255, 1],
+  black: [0, 0, 0, 1],
+  none: [0, 0, 0, 0],
+  transparent: [0, 0, 0, 0]
+};
+function toRGBA(c) {
+  if (typeof c !== "string") return null;
+  const k2 = c.trim().toLowerCase();
+  if (k2 in NAMED) return NAMED[k2];
+  return parseRGBA(c);
+}
+function compositeOver(fg, bg) {
+  const a2 = Math.max(0, Math.min(1, fg[3]));
+  return [
+    Math.round(fg[0] * a2 + bg[0] * (1 - a2)),
+    Math.round(fg[1] * a2 + bg[1] * (1 - a2)),
+    Math.round(fg[2] * a2 + bg[2] * (1 - a2))
+  ];
+}
+function relativeLuminance(rgb) {
+  const lin = rgb.map((v2) => {
+    const s = v2 / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2];
+}
+function contrastRatio(l1, l2) {
+  const hi = Math.max(l1, l2);
+  const lo = Math.min(l1, l2);
+  return (hi + 0.05) / (lo + 0.05);
+}
+function decideLabelColor(textColor, fill, fillOpacity, pageBg, minContrast = MIN_CONTRAST, normalize = false) {
+  const fillRGBA = toRGBA(fill);
+  if (!fillRGBA) return { fix: false, color: "", reason: "fill-unparsed" };
+  const pageRGBA = toRGBA(pageBg) || [255, 255, 255, 1];
+  const pageRGB = [pageRGBA[0], pageRGBA[1], pageRGBA[2]];
+  const effFill = [fillRGBA[0], fillRGBA[1], fillRGBA[2], fillRGBA[3] * clamp01(fillOpacity)];
+  const bgRGB = compositeOver(effFill, pageRGB);
+  const bgLum = relativeLuminance(bgRGB);
+  const bgIsPage = Math.abs(bgRGB[0] - pageRGB[0]) <= PAGE_MATCH_TOLERANCE && Math.abs(bgRGB[1] - pageRGB[1]) <= PAGE_MATCH_TOLERANCE && Math.abs(bgRGB[2] - pageRGB[2]) <= PAGE_MATCH_TOLERANCE;
+  const effNormalize = normalize && !bgIsPage;
+  const textRGBA = toRGBA(textColor);
+  if (!effNormalize && textRGBA) {
+    const txtRGB = compositeOver(textRGBA, bgRGB);
+    const cur = contrastRatio(relativeLuminance(txtRGB), bgLum);
+    if (cur >= minContrast) return { fix: false, color: "", reason: "ok" };
+  }
+  const darkC = contrastRatio(relativeLuminance(hexToRGB(DARK_TEXT)), bgLum);
+  const lightC = contrastRatio(relativeLuminance(hexToRGB(LIGHT_TEXT)), bgLum);
+  let useLight = bgLum <= WHITE_TEXT_BG_LUM;
+  if (useLight && lightC < minContrast && darkC >= minContrast) useLight = false;
+  if (!useLight && darkC < minContrast && lightC >= minContrast) useLight = true;
+  return useLight ? { fix: true, color: LIGHT_TEXT, reason: "fixed-light" } : { fix: true, color: DARK_TEXT, reason: "fixed-dark" };
+}
+var GLYPH_SAMPLE_N = 3;
+function glyphSampleGrid(box, n = GLYPH_SAMPLE_N) {
+  const out = [];
+  if (!box || !(box.width > 0) || !(box.height > 0) || !(n >= 1)) return out;
+  const k2 = Math.floor(n);
+  for (let i = 0; i < k2; i++) {
+    for (let j2 = 0; j2 < k2; j2++) {
+      out.push({
+        x: box.left + box.width * (i + 0.5) / k2,
+        y: box.top + box.height * (j2 + 0.5) / k2
+      });
+    }
+  }
+  return out;
+}
+function clamp01(v2) {
+  if (typeof v2 !== "number" || !isFinite(v2)) return 1;
+  return Math.max(0, Math.min(1, v2));
+}
+function hexToRGB(hex) {
+  const p2 = toRGBA(hex);
+  return [p2[0], p2[1], p2[2]];
+}
+
+// src/labelContrastDom.ts
+var LABEL_CONTRAST_DONE_ATTR = "data-lch-contrast";
+var LABEL_CONTRAST_CAP = 2e3;
+var EMPTY3 = { rects: 0, scanned: 0, fixed: 0, pillsBoosted: 0, offFill: 0, pageMajority: 0 };
+function backedSamples(el, pts) {
+  try {
+    const ge = el;
+    if (typeof ge.isPointInFill !== "function" || typeof ge.getScreenCTM !== "function") return null;
+    const m2 = ge.getScreenCTM();
+    const svg = ge.ownerSVGElement;
+    if (!m2 || !svg || typeof svg.createSVGPoint !== "function") return null;
+    if (pts.length === 0) return null;
+    const inv = m2.inverse();
+    const hit = [];
+    for (let i = 0; i < pts.length; i++) {
+      const p2 = svg.createSVGPoint();
+      p2.x = pts[i].x;
+      p2.y = pts[i].y;
+      hit.push(ge.isPointInFill(p2.matrixTransform(inv)));
+    }
+    return hit;
+  } catch {
+    return null;
+  }
+}
+function applyLabelContrast(container, opts = {}) {
+  const report = { ...EMPTY3 };
+  if (!container) {
+    report.skipped = "no-container";
+    return report;
+  }
+  const CAP = opts.cap ?? LABEL_CONTRAST_CAP;
+  const pageBg = opts.pageBg || "#ffffff";
+  try {
+    const rects = [];
+    let ord = 0;
+    const pushShape = (el) => {
+      const tag = el.tagName.toLowerCase();
+      if (tag !== "rect" && tag !== "path") return;
+      const r = el.getBoundingClientRect();
+      if (r.width <= 0 || r.height <= 0) return;
+      let fill = el.getAttribute("fill") || "";
+      const win2 = container.ownerDocument?.defaultView;
+      if ((!fill || fill === "none") && win2 && typeof win2.getComputedStyle === "function") {
+        fill = win2.getComputedStyle(el).fill || "";
+      }
+      if (!fill || fill === "none") return;
+      const opAttr = el.getAttribute("fill-opacity");
+      const op = opAttr === null ? 1 : parseFloat(opAttr);
+      rects.push({ r, fill, op: isFinite(op) ? op : 1, area: r.width * r.height, el, ord: ord++ });
+    };
+    const shapeEls = container.querySelectorAll("rect, path");
+    if (shapeEls.length === 0) {
+      report.skipped = "no-shapes";
+      return report;
+    }
+    if (shapeEls.length > CAP) {
+      report.skipped = "too-many-shapes";
+      return report;
+    }
+    for (let i = 0; i < shapeEls.length; i++) pushShape(shapeEls[i]);
+    if (rects.length === 0) {
+      report.skipped = "no-shapes";
+      return report;
+    }
+    report.rects = rects.length;
+    const pageRGBA = toRGBA(pageBg) || [255, 255, 255, 1];
+    const pageRGB = [pageRGBA[0], pageRGBA[1], pageRGBA[2]];
+    const effAlpha = (mk) => {
+      const c = toRGBA(mk.fill);
+      return (c ? c[3] : 1) * mk.op;
+    };
+    const texts = container.querySelectorAll("text");
+    if (texts.length > CAP) {
+      report.skipped = "too-many-texts";
+      return report;
+    }
+    const win = container.ownerDocument?.defaultView;
+    for (let t = 0; t < texts.length; t++) {
+      const tx = texts[t];
+      if (tx.getAttribute(LABEL_CONTRAST_DONE_ATTR) === "1") continue;
+      const tr = tx.getBoundingClientRect();
+      if (tr.width <= 0 || tr.height <= 0) continue;
+      const ovArea = (r) => Math.max(0, Math.min(r.right, tr.right) - Math.max(r.left, tr.left)) * Math.max(0, Math.min(r.bottom, tr.bottom) - Math.max(r.top, tr.top));
+      const glyphArea = tr.width * tr.height;
+      const boxed = rects.map((mk) => ({ mk, ov: ovArea(mk.r) })).filter((x2) => x2.ov > 0);
+      const pts = glyphSampleGrid({ left: tr.left, top: tr.top, width: tr.width, height: tr.height });
+      const painted = pts.map(() => false);
+      let unmeasured = 0;
+      const under = boxed.map((x2) => {
+        const mask = backedSamples(x2.mk.el, pts);
+        if (mask === null) {
+          unmeasured++;
+          return x2;
+        }
+        let inside = 0;
+        const paints = effAlpha(x2.mk) >= PILL_MIN_ALPHA;
+        for (let i = 0; i < mask.length; i++) {
+          if (!mask[i]) continue;
+          inside++;
+          if (paints) painted[i] = true;
+        }
+        return { mk: x2.mk, ov: glyphArea * (inside / mask.length) };
+      }).filter((x2) => x2.ov > 0);
+      if (under.length === 0 && boxed.length > 0) report.offFill++;
+      if (under.length === 0) continue;
+      if (unmeasured === 0 && pts.length > 0) {
+        let held = 0;
+        for (let i = 0; i < painted.length; i++) if (painted[i]) held++;
+        if (!backingHoldsGlyph(glyphArea * (held / pts.length), glyphArea)) {
+          report.pageMajority++;
+          continue;
+        }
+      }
+      report.scanned++;
+      const opaqueUnder = under.filter((x2) => effAlpha(x2.mk) >= PILL_OPAQUE_ALPHA);
+      const cellEntry = (opaqueUnder.length ? opaqueUnder : under).reduce((a2, b2) => b2.ov > a2.ov || b2.ov === a2.ov && b2.mk.ord > a2.mk.ord ? b2 : a2);
+      const cell = cellEntry.mk;
+      const pill = under.find((x2) => x2.mk !== cell && isPillBackdropAlpha(effAlpha(x2.mk)) && x2.mk.ord > cell.ord && pillBacksGlyph(x2.ov, glyphArea))?.mk;
+      const cellRGBA = toRGBA(cell.fill);
+      let bgRGB = cellRGBA ? compositeOver([cellRGBA[0], cellRGBA[1], cellRGBA[2], cellRGBA[3] * cell.op], pageRGB) : pageRGB;
+      if (pill) {
+        const pr = toRGBA(pill.fill);
+        if (pr) {
+          bgRGB = compositeOver([pr[0], pr[1], pr[2], 0.9], bgRGB);
+          pill.el.setAttribute("fill", `rgb(${pr[0]}, ${pr[1]}, ${pr[2]})`);
+          pill.el.setAttribute("fill-opacity", "0.9");
+          report.pillsBoosted++;
+        }
+      }
+      const cur = tx.getAttribute("fill") || (win && typeof win.getComputedStyle === "function" ? win.getComputedStyle(tx).fill : "");
+      const normalize = !cellSuppressesNormalize(cell.el.getAttribute("class"));
+      const d = decideLabelColor(cur, `rgb(${bgRGB[0]}, ${bgRGB[1]}, ${bgRGB[2]})`, 1, pageBg, MIN_CONTRAST, normalize);
+      if (d.fix) {
+        tx.setAttribute("fill", d.color);
+        report.fixed++;
+      }
+      if (pill || d.fix) tx.setAttribute(LABEL_CONTRAST_DONE_ATTR, "1");
+    }
+    return report;
+  } catch {
+    report.skipped = "error";
+    return report;
+  }
+}
+
 // src/host.ts
 function sessionViewStateProvider(container) {
   const holder = container;
@@ -2234,6 +2495,7 @@ function createChartHost(container, config) {
   container.classList?.add(HOST_CONTAINER_CLASS);
   ensureAffordanceStyles();
   const fitOpts = config.fit ?? true;
+  const labelContrastOpts = config.labelContrast ?? true;
   const stopAnim = () => {
     const s = container[CONTAINER_SLOT_ANIM_STOP];
     if (typeof s === "function") {
@@ -2273,6 +2535,18 @@ function createChartHost(container, config) {
       } catch (err) {
         throw explainRenderFailure(err, d3);
       }
+      if (labelContrastOpts !== false) {
+        try {
+          const lc = labelContrastOpts === true ? {} : { ...labelContrastOpts };
+          if (!lc.pageBg) {
+            const bg = resolved.backgroundColor ?? resolved.themeBg;
+            if (typeof bg === "string" && bg) lc.pageBg = bg;
+          }
+          const r = applyLabelContrast(container, lc);
+          config.onLabelContrast?.(r);
+        } catch {
+        }
+      }
       ensureCrossfilterHitTargets(container, doc);
       paintSelection();
       try {
@@ -2432,6 +2706,29 @@ export {
   measureContainerBoxes,
   fitReadingFor,
   fitRenderedChart,
+  DARK_TEXT,
+  LIGHT_TEXT,
+  MIN_CONTRAST,
+  WHITE_TEXT_BG_LUM,
+  PILL_MIN_ALPHA,
+  PILL_OPAQUE_ALPHA,
+  PAGE_MATCH_TOLERANCE,
+  isPillBackdropAlpha,
+  PILL_MIN_COVERAGE,
+  pillBacksGlyph,
+  BACKING_MAJORITY,
+  backingHoldsGlyph,
+  cellSuppressesNormalize,
+  toRGBA,
+  compositeOver,
+  relativeLuminance,
+  contrastRatio,
+  decideLabelColor,
+  GLYPH_SAMPLE_N,
+  glyphSampleGrid,
+  LABEL_CONTRAST_DONE_ATTR,
+  LABEL_CONTRAST_CAP,
+  applyLabelContrast,
   sessionViewStateProvider,
   noopViewStateProvider,
   requiredD3Plugins,

package/dist/index.mjs

@@ -11,6 +11,7 @@ import {
   ANIM_PLAY_SPEED_MIN,
   APPROXIMATE_POSITIONS_DEFAULT,
   AXIS_FILTER_CLASS,
+  BACKING_MAJORITY,
   COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT,
   COLOR_SCALE_SELF_CLAMP_PCT_MAX,
   COLOR_SCALE_SELF_CLAMP_PCT_MIN,
@@ -18,21 +19,31 @@ import {
   CONTAINER_SLOT_INITIAL_XF_MARK,
   CONTAINER_SLOT_UI_STATE,
   CONTAINER_SLOT_XF_CLEAR,
+  DARK_TEXT,
   DIM_OPACITY_DEFAULT,
   DIM_OPACITY_VAR,
   FIT_CONTENT_SELECTOR,
   FLIP_MODE_DEFAULT,
   GEO_POINT_PRECISIONS,
+  GLYPH_SAMPLE_N,
   HOST_CONTAINER_CLASS,
   HOST_CONTRACT_VERSION,
   L3,
+  LABEL_CONTRAST_CAP,
+  LABEL_CONTRAST_DONE_ATTR,
   LEGEND_MARK_CLASS,
   LIFT_SELECTED_CLASS,
+  LIGHT_TEXT,
   MARK_CLASS,
   MARK_SELECTED_CLASS,
   MAX_FRAME_GROW_FACTOR,
+  MIN_CONTRAST,
   MIN_HIT_BAND_PX,
+  PAGE_MATCH_TOLERANCE,
   PHANTOM_FRACTION,
+  PILL_MIN_ALPHA,
+  PILL_MIN_COVERAGE,
+  PILL_OPAQUE_ALPHA,
   ROW_IDX_ATTR,
   Rt,
   SCROLL_SLACK_PX,
@@ -41,43 +52,55 @@ import {
   Se,
   Tt,
   VALUE_AXIS_BASELINE_DEFAULT,
+  WHITE_TEXT_BG_LUM,
   XFILTER_REFRESH_EVENT,
+  applyLabelContrast,
+  backingHoldsGlyph,
   blankRenderFlag,
   buildRenderPayload,
+  cellSuppressesNormalize,
   censusHitBands,
   censusMarks,
   chartOwnsTimeline,
   clearGeoCache,
   compileRenderFn,
+  compositeOver,
   contentExtentOf,
+  contrastRatio,
   createChartHost,
   createMarkResolver,
   ctmScaleOf,
+  decideLabelColor,
   ensureCrossfilterHitTargets,
   explainRenderFailure,
   fitReadingFor,
   fitRenderedChart,
   geoAssetFor,
   geoFromCache,
+  glyphSampleGrid,
   hitBandFlag,
   isBlankRender,
   isPhantomBox,
+  isPillBackdropAlpha,
   loadGeo,
   measureContainerBoxes,
   needsScroll,
   noopViewStateProvider,
   periodTickSuppressesFeedback,
+  pillBacksGlyph,
   planFrameGrow,
   registerGeo,
   registerGeoAsset,
+  relativeLuminance,
   requiredD3Plugins,
   resolveOptions,
   scrollFitFor,
   sessionViewStateProvider,
   stripEsmExports,
   svgInkReach,
+  toRGBA,
   ye
-} from "./chunk-D3DERYG3.mjs";
+} from "./chunk-E6P2ZMGC.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -1010,6 +1033,7 @@ export {
   ANIM_PLAY_SPEED_MIN,
   APPROXIMATE_POSITIONS_DEFAULT,
   AXIS_FILTER_CLASS,
+  BACKING_MAJORITY,
   CHOOSER_MIN_HEIGHT_PX,
   CHOOSER_MIN_WIDTH_PX,
   COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT,
@@ -1019,6 +1043,7 @@ export {
   CONTAINER_SLOT_INITIAL_XF_MARK,
   CONTAINER_SLOT_UI_STATE,
   CONTAINER_SLOT_XF_CLEAR,
+  DARK_TEXT,
   DIM_OPACITY_DEFAULT,
   DIM_OPACITY_VAR,
   FILTER_MIN_HEIGHT_PX,
@@ -1028,30 +1053,43 @@ export {
   FIT_CONTENT_SELECTOR,
   FLIP_MODE_DEFAULT,
   GEO_POINT_PRECISIONS,
+  GLYPH_SAMPLE_N,
   HOST_CONTAINER_CLASS,
   HOST_CONTRACT_VERSION,
   INLINE_FILTER_MIN_ROWS,
+  LABEL_CONTRAST_CAP,
+  LABEL_CONTRAST_DONE_ATTR,
   LEGEND_MARK_CLASS,
   LIFT_SELECTED_CLASS,
+  LIGHT_TEXT,
   MARK_CLASS,
   MARK_SELECTED_CLASS,
   MAX_FRAME_GROW_FACTOR,
+  MIN_CONTRAST,
   MIN_HIT_BAND_PX,
+  PAGE_MATCH_TOLERANCE,
   PHANTOM_FRACTION,
+  PILL_MIN_ALPHA,
+  PILL_MIN_COVERAGE,
+  PILL_OPAQUE_ALPHA,
   ROW_IDX_ATTR,
   SCROLL_SLACK_PX,
   SEASONAL_MARKERS_DEFAULT,
   SELECTION_ACTIVE_CLASS,
   VALUE_AXIS_BASELINE_DEFAULT,
+  WHITE_TEXT_BG_LUM,
   XFILTER_REFRESH_EVENT,
   actionFor,
+  applyLabelContrast,
   askApplyImprovements,
+  backingHoldsGlyph,
   bareBase64,
   blankRenderFlag,
   buildRenderPayload,
   buildReviewWire,
   canConfirmLaunch,
   captureSvgSnapshot,
+  cellSuppressesNormalize,
   censusHitBands,
   censusMarks,
   chartOwnsTimeline,
@@ -1059,13 +1097,16 @@ export {
   clearGeoCache,
   compileRenderFn,
   compileTrivialSource,
+  compositeOver,
   computeQualifyFilterView,
   computeSelectionCard,
   confirmLaunch,
   contentExtentOf,
+  contrastRatio,
   createChartHost,
   createMarkResolver,
   ctmScaleOf,
+  decideLabelColor,
   ensureCrossfilterHitTargets,
   explainRenderFailure,
   filterFitsChooser,
@@ -1074,11 +1115,13 @@ export {
   fitRenderedChart,
   geoAssetFor,
   geoFromCache,
+  glyphSampleGrid,
   hasRefusalsToShow,
   hitBandFlag,
   inlineFilterGate,
   isBlankRender,
   isPhantomBox,
+  isPillBackdropAlpha,
   launchFavorStyle,
   launchGenerates,
   listNeedsFilter,
@@ -1092,6 +1135,7 @@ export {
   normalizeFilterTerm,
   orderRefusalsForDisplay,
   periodTickSuppressesFeedback,
+  pillBacksGlyph,
   planFrameGrow,
   planTrivialChart,
   qualifyAuto,
@@ -1109,6 +1153,7 @@ export {
   registerCityTable,
   registerGeo,
   registerGeoAsset,
+  relativeLuminance,
   requiredD3Plugins,
   resolveOptions,
   scrollFitFor,
@@ -1119,5 +1164,6 @@ export {
   stripEsmExports,
   svgInkReach,
   svgNaturalSize,
-  svgToDataUrl
+  svgToDataUrl,
+  toRGBA
 };

package/dist/react.mjs

@@ -4,7 +4,7 @@ import {
   createChartHost,
   geoFromCache,
   loadGeo
-} from "./chunk-D3DERYG3.mjs";
+} from "./chunk-E6P2ZMGC.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 

package/dist/types/host.d.ts

@@ -3,6 +3,7 @@ import { type ResolveOptionsInput } from "./defaults";
 import { type MarkCensus } from "./blankRender";
 import { type HitBandCensus } from "./hitBands";
 import { type FitRenderedChartOptions, type FitRenderedChartResult } from "./fitDom";
+import { type LabelContrastOptions, type LabelContrastReport } from "./labelContrastDom";
 export type RenderFn = (container: HTMLElement, data: any, options: RenderOptions) => void;
 /**
  * THE SESSION PROVIDER — what every host got hard-coded before contract 1.6.0, now named.
@@ -115,6 +116,25 @@ export interface ChartHostConfig {
     fit?: boolean | FitRenderedChartOptions;
     /** The fit result after each render - what was grown, and how the chart measured. */
     onFit?: (result: FitRenderedChartResult) => void;
+    /**
+     * CAN THE LABELS ON THE MARKS BE READ? Runs after every render, BEFORE the hit-target heal
+     * (which injects transparent rects this pass must not mistake for backdrops).
+     *
+     * Generated code picks an in-mark label's colour from the mark's NOMINAL hue; the mark's
+     * ACTUAL rendered fill - a 0.18-opacity band over white, a translucent pill over a tile, an
+     * arc whose hole is canvas - is something else, and only a post-render read of the real DOM
+     * knows it. This resolves which shapes really back each label (geometry, not bounding
+     * boxes), composites the real stack over the page, and recolours to black or white only
+     * where the label would otherwise be unreadable or a tile's labels would read as mixed.
+     *
+     * DEFAULT ON, because the alternative is text nobody can read, and the pass only ever sets a
+     * text's fill. Pass `false` for a host that owns its own label colours, or an options object
+     * to name the page background it composites onto (`pageBg`) - a themed or high-contrast
+     * canvas is not white, and every readability answer is measured against it.
+     */
+    labelContrast?: boolean | LabelContrastOptions;
+    /** What the label-contrast pass did after each render - counts, so a host can log them. */
+    onLabelContrast?: (report: LabelContrastReport) => void;
 }
 export interface ChartHost {
     render(): void;

package/dist/types/index.d.ts

@@ -16,6 +16,8 @@ export { qualifyPick, qualifyAuto, qualifyCancel, launchGenerates, launchFavorSt
 export { normalizeFilterTerm, filterQualifyRows, readQualifyChartRow, readQualifyRefusalRow, filterFitsChooser, listNeedsFilter, qualifyFilterGate, inlineFilterGate, FILTER_MIN_TERM_CHARS, FILTER_ROW_PX, FILTER_MIN_WIDTH_PX, FILTER_MIN_HEIGHT_PX, INLINE_FILTER_MIN_ROWS, computeQualifyFilterView, qualifyFilterCountText, type QualifyFilterTier, type QualifyFilterResult, type QualifyFilterRead, type QualifyFilterGateReason, type QualifyFilterGateInput, type QualifyFilterRow, type QualifyFilterGroup, type QualifyFilterView, type QualifyFilterNoteKind, } from "./qualifyFilter";
 export { computeSelectionCard, normaliseAggregation, type SelectionCardModel, type SelectionCardLine, type SelectionCardOptions, } from "./selectionCard";
 export { ensureCrossfilterHitTargets, type HitTargetReport } from "./hitTargets";
+export { applyLabelContrast, LABEL_CONTRAST_DONE_ATTR, LABEL_CONTRAST_CAP, type LabelContrastOptions, type LabelContrastReport, } from "./labelContrastDom";
+export { decideLabelColor, toRGBA, compositeOver, relativeLuminance, contrastRatio, isPillBackdropAlpha, pillBacksGlyph, backingHoldsGlyph, cellSuppressesNormalize, glyphSampleGrid, DARK_TEXT, LIGHT_TEXT, MIN_CONTRAST, WHITE_TEXT_BG_LUM, PILL_MIN_ALPHA, PILL_OPAQUE_ALPHA, PILL_MIN_COVERAGE, PAGE_MATCH_TOLERANCE, BACKING_MAJORITY, GLYPH_SAMPLE_N, type LabelDecision, } from "./labelContrast";
 export { censusMarks, isBlankRender, blankRenderFlag, type MarkCensus, type BlankVerdictInput } from "./blankRender";
 export { censusHitBands, hitBandFlag, MIN_HIT_BAND_PX, type HitBandCensus } from "./hitBands";
 export { SCROLL_SLACK_PX, MAX_FRAME_GROW_FACTOR, PHANTOM_FRACTION, FIT_CONTENT_SELECTOR, needsScroll, contentExtentOf, scrollFitFor, planFrameGrow, isPhantomBox, type MeasuredBox, type ContentExtent, type ScrollFit, type FrameGrowPlan, } from "./fit";

package/dist/types/labelContrast.d.ts

@@ -0,0 +1,56 @@
+export declare const DARK_TEXT = "#111111";
+export declare const LIGHT_TEXT = "#ffffff";
+export declare const MIN_CONTRAST = 3;
+export declare const WHITE_TEXT_BG_LUM = 0.5;
+export declare const PILL_MIN_ALPHA = 0.05;
+export declare const PILL_OPAQUE_ALPHA = 0.85;
+export declare const PAGE_MATCH_TOLERANCE = 2;
+/** True when a shape's effective alpha lets it act as a label backdrop rather than the cell. */
+export declare function isPillBackdropAlpha(a: number): boolean;
+export declare const PILL_MIN_COVERAGE = 0.6;
+/** True when a candidate backdrop covers enough of the glyph box to be the thing behind it. */
+export declare function pillBacksGlyph(overlapArea: number, glyphArea: number): boolean;
+export declare const BACKING_MAJORITY = 0.5;
+/** True when the painted marks under a glyph hold enough of it to count as its background. */
+export declare function backingHoldsGlyph(backedArea: number, glyphArea: number): boolean;
+export declare function cellSuppressesNormalize(cellClass: string | null | undefined): boolean;
+type RGB = [number, number, number];
+type RGBA = [number, number, number, number];
+/** Parse a colour string to RGBA, covering hex, rgb()/rgba() and a few keywords. */
+export declare function toRGBA(c: string | null | undefined): RGBA | null;
+/** Alpha-composite a foreground RGBA over an opaque RGB background. */
+export declare function compositeOver(fg: RGBA, bg: RGB): RGB;
+/** WCAG relative luminance of an opaque sRGB colour (0..1). */
+export declare function relativeLuminance(rgb: RGB): number;
+/** WCAG contrast ratio (1..21) between two luminances. */
+export declare function contrastRatio(l1: number, l2: number): number;
+export interface LabelDecision {
+    fix: boolean;
+    color: string;
+    reason: string;
+}
+/**
+ * Decide whether an in-mark label needs recolouring for legibility.
+ *
+ * @param textColor    current text colour (any CSS form the SVG carries)
+ * @param fill         the backing mark's fill colour
+ * @param fillOpacity  the backing mark's fill-opacity (0..1)
+ * @param pageBg       the page/visual background the mark sits on (opaque; '' → white)
+ * @param minContrast  trip point; defaults to MIN_CONTRAST
+ */
+export declare function decideLabelColor(textColor: string | null | undefined, fill: string | null | undefined, fillOpacity: number, pageBg: string | null | undefined, minContrast?: number, normalize?: boolean): LabelDecision;
+export declare const GLYPH_SAMPLE_N = 3;
+/**
+ * Evenly-spaced sample points over a glyph box, in the box's own coordinate space.
+ * `n` per side (n² points), each at the centre of its cell so no point lands on an edge.
+ */
+export declare function glyphSampleGrid(box: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, n?: number): {
+    x: number;
+    y: number;
+}[];
+export {};

package/dist/types/labelContrastDom.d.ts

@@ -0,0 +1,33 @@
+/** The attribute a recoloured (or pill-backed) label carries, so a second pass in the same
+ *  render leaves it alone. Generated code that rebuilds its text nodes clears it by construction. */
+export declare const LABEL_CONTRAST_DONE_ATTR = "data-lch-contrast";
+/** How many shapes / texts the pass will consider before declining. Layout reads in a loop, so
+ *  it is a real ceiling: a 5,000-cell heatmap is the size of thing this exists for, a 50,000-node
+ *  scatter is not, and on the latter the pass costs more than the defect it would fix. */
+export declare const LABEL_CONTRAST_CAP = 2000;
+export interface LabelContrastOptions {
+    /** The opaque canvas the marks sit on. Default white; a host with a themed or high-contrast
+     *  background passes it, or every "is this label readable" answer is measured against the
+     *  wrong page. */
+    pageBg?: string;
+    /** Override the DOM ceiling. */
+    cap?: number;
+}
+export interface LabelContrastReport {
+    /** Filled shapes harvested as candidate backings. */
+    rects: number;
+    /** Labels that resolved a backing and were judged. */
+    scanned: number;
+    /** Labels recoloured. `fixed === scanned` is the module's own tell for a pass that is not
+     *  measuring anything - see the incident notes in labelContrast.ts. */
+    fixed: number;
+    /** Translucent backdrops boosted to opaque so they actually back their label. */
+    pillsBoosted: number;
+    /** Labels whose candidates' BOXES contained them but whose FILLS did not - a ring's hole. */
+    offFill: number;
+    /** Labels mostly over the page with one end clipping a mark - handed back to the chart. */
+    pageMajority: number;
+    /** Why the pass did nothing, when it did nothing. */
+    skipped?: "no-container" | "no-shapes" | "too-many-shapes" | "too-many-texts" | "error";
+}
+export declare function applyLabelContrast(container: HTMLElement | null | undefined, opts?: LabelContrastOptions): LabelContrastReport;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.5.73",
+  "version": "0.5.74",
   "description": "Run a BIC-generated D3 chart in any web host: compiles the generated render() function, applies the shared option defaults, resolves mark clicks (through tooltip overlays), owns the selection affordance, and translates row indices between cross-filtered charts. The same contract the BIC Power BI visual implements, minus Power BI. React bindings at @bicharts/chart-host/react.",
   "license": "Apache-2.0",
   "type": "module",