@bicharts/chart-host 0.5.101 → 0.5.103

package/dist/{chunk-LJU47KQS.mjs → chunk-EFOEZN4D.mjs}

@@ -1440,7 +1440,7 @@ function Wt(n, s) {
   return { iso: i, unmatched: M4, matchedRows: h3, totalRows: n.length };
 }
 
-// ../shape-core/dist/chunk-EZ56V64J.mjs
+// ../shape-core/dist/chunk-3IYFLQQR.mjs
 var import_papaparse = __toESM(require_papaparse_min(), 1);
 /*! @bicharts/shape-core — Apache-2.0. Bundled reference data: GeoNames (https://www.geonames.org/) CC BY 4.0; US Census/TIGER (public domain). Full text: NOTICE in this package. */
 var Ae = { "north-america": "AG AI AW BB BL BM BQ BS BZ CA CR CU CW DM DO GD GL GP GT HN HT JM KN KY LC MF MQ MS MX NI PA PM PR SV SX TC TT US VC VG VI", "south-america": "AR BO BR CL CO EC FK GF GY PE PY SR UY VE", europe: "AD AL AT AX BA BE BG BY CH CY CZ DE DK EE ES FI FO FR GB GG GI GR HR HU IE IM IS IT JE LI LT LU LV MC MD ME MK MT NL NO PL PT RO RS RU SE SI SJ SK SM UA VA", africa: "AO BF BI BJ BW CD CF CG CI CM CV DJ DZ EG EH ER ET GA GH GM GN GQ GW KE KM LR LS LY MA MG ML MR MU MW MZ NA NE NG RE RW SC SD SH SL SN SO SS ST SZ TD TG TN TZ UG YT ZA ZM ZW", asia: "AE AF AM AZ BD BH BN BT CC CN CX GE HK ID IL IN IO IQ IR JO JP KG KH KP KR KW KZ LA LB LK MM MN MO MV MY NP OM PH PK PS QA SA SG SY TH TJ TL TM TR TW UZ VN YE", oceania: "AS AU CK FJ FM GU KI MH MP NC NF NR NU NZ PF PG PN PW SB TK TO TV UM VU WF WS", antarctica: "AQ BV GS HM TF" };
@@ -1456,8 +1456,8 @@ function He(n) {
   }
 }
 He(N);
-var Ke = ["rate", "ratio", "pct", "percent", "percentage", "rating", "share", "score", "index", "nps", "csat", "margin", "yield", "coverage", "utilization", "z[_-]?score", "average", "avg", "mean", "median", "stddev", "variance", "gpa", "percentile", "quantile", "efficiency", "accuracy", "probability", "multiplier", "coefficient", "correlation", "occupancy", "age", "bmi", "temperature", "density", "pressure", "humidity", "ph", "velocity", "speed", "elevation", "altitude", "latency", "throughput", "bandwidth", "iops", "temperatuur", "temperatur", "temperatura", "teplota", "lampotila", "homerseklet", "sicaklik", "pression", "presion", "pressao", "pressione", "druck", "tryck", "tlak", "paine", "nyomas", "presiune", "humidite", "humedad", "umidade", "umidita", "feuchtigkeit", "vochtigheid", "kosteus", "vlhkost", "vitesse", "velocidad", "velocidade", "velocita", "geschwindigkeit", "snelheid", "hastighet", "hastighed", "rychlost", "nopeus", "sebesseg", "brzina", "predkosc", "densite", "densidad", "densidade", "densita", "dichte", "dichtheid", "hustota", "tiheys", "gustoca", "moyenne", "mediane", "promedio", "mediana", "gemiddelde", "durchschnitt", "mittelwert", "genomsnitt", "gennemsnit", "gjennomsnitt", "keskiarvo", "atlag", "ortalama", "prosjek", "srednia", "prumer", "priemer", "medie", "taux", "tasa", "taxa", "tasso", "verhaltnis", "verhouding", "aandeel", "anteil", "andel", "osuus", "podil", "udzial", "udio", "pourcentage", "porcentaje", "percentual", "prozent", "procent", "prosentti", "szazalek", "yuzde", "participacion", "participacao", "pondere", "omjer", "arany", "oran", "rata", "leeftijd", "edad", "idade", "wiek", "eletkor", "varsta", "puntuacion", "pontuacao", "punteggio", "betyg", "ocena", "indice", "indeks", "wskaznik", "puan"];
-var $e = ["pct", "percent", "percentage", "rate", "ratio", "rating", "share", "score", "index", "nps", "csat", "margin", "yield", "coverage", "utilization", "gpa", "percentile", "quantile", "bmi", "density", "pressure", "humidity", "velocity", "efficiency", "occupancy", "latency", "throughput", "bandwidth", "iops"];
+var Ke = ["rate", "ratio", "pct", "percent", "percentage", "rating", "share", "score", "index", "nps", "csat", "margin", "yield", "coverage", "utilization", "z[_-]?score", "average", "avg", "mean", "median", "stddev", "variance", "gpa", "percentile", "quantile", "efficiency", "accuracy", "probability", "multiplier", "coefficient", "correlation", "occupancy", "age", "bmi", "temperature", "density", "pressure", "humidity", "ph", "velocity", "speed", "elevation", "altitude", "latency", "throughput", "bandwidth", "iops", "ppm", "ppb", "dpmo", "bps", "temperatuur", "temperatur", "temperatura", "teplota", "lampotila", "homerseklet", "sicaklik", "pression", "presion", "pressao", "pressione", "druck", "tryck", "tlak", "paine", "nyomas", "presiune", "humidite", "humedad", "umidade", "umidita", "feuchtigkeit", "vochtigheid", "kosteus", "vlhkost", "vitesse", "velocidad", "velocidade", "velocita", "geschwindigkeit", "snelheid", "hastighet", "hastighed", "rychlost", "nopeus", "sebesseg", "brzina", "predkosc", "densite", "densidad", "densidade", "densita", "dichte", "dichtheid", "hustota", "tiheys", "gustoca", "moyenne", "mediane", "promedio", "mediana", "gemiddelde", "durchschnitt", "mittelwert", "genomsnitt", "gennemsnit", "gjennomsnitt", "keskiarvo", "atlag", "ortalama", "prosjek", "srednia", "prumer", "priemer", "medie", "taux", "tasa", "taxa", "tasso", "verhaltnis", "verhouding", "aandeel", "anteil", "andel", "osuus", "podil", "udzial", "udio", "pourcentage", "porcentaje", "percentual", "prozent", "procent", "prosentti", "szazalek", "yuzde", "participacion", "participacao", "pondere", "omjer", "arany", "oran", "rata", "leeftijd", "edad", "idade", "wiek", "eletkor", "varsta", "puntuacion", "pontuacao", "punteggio", "betyg", "ocena", "indice", "indeks", "wskaznik", "puan"];
+var $e = ["pct", "percent", "percentage", "rate", "ratio", "rating", "share", "score", "index", "nps", "csat", "margin", "yield", "coverage", "utilization", "gpa", "percentile", "quantile", "bmi", "density", "pressure", "humidity", "velocity", "efficiency", "occupancy", "latency", "throughput", "bandwidth", "iops", "ppm", "ppb", "dpmo", "bps"];
 var Ze = ["latitude", "longitude"];
 var Xe = ["latitude", "longitude"];
 function j2(n) {
@@ -2926,7 +2926,7 @@ function hexToRGB(hex2) {
 // src/labelContrastDom.ts
 var LABEL_CONTRAST_DONE_ATTR = "data-lch-contrast";
 var LABEL_CONTRAST_CAP = 2e3;
-var EMPTY5 = { rects: 0, scanned: 0, fixed: 0, pillsBoosted: 0, offFill: 0, pageMajority: 0 };
+var EMPTY5 = { rects: 0, scanned: 0, fixed: 0, pillsBoosted: 0, offFill: 0, pageMajority: 0, paintedOver: 0 };
 function backedSamples(el, pts) {
   try {
     const ge = el;
@@ -2948,6 +2948,20 @@ function backedSamples(el, pts) {
     return null;
   }
 }
+var DOC_POSITION_FOLLOWING = 4;
+function paintRoot(el, container) {
+  let root = null;
+  for (let n = el.parentElement; n; n = n.parentElement) {
+    if (String(n.tagName || "").toLowerCase() === "svg") root = n;
+    if (n === container) break;
+  }
+  return root;
+}
+function drawnBeneath(shape, text, textRoot) {
+  if (!shape.root || shape.root !== textRoot) return true;
+  if (typeof shape.el.compareDocumentPosition !== "function") return true;
+  return (shape.el.compareDocumentPosition(text) & DOC_POSITION_FOLLOWING) !== 0;
+}
 function applyLabelContrast(container, opts = {}) {
   const report = { ...EMPTY5 };
   if (!container) {
@@ -2972,7 +2986,15 @@ function applyLabelContrast(container, opts = {}) {
       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++ });
+      rects.push({
+        r,
+        fill,
+        op: isFinite(op) ? op : 1,
+        area: r.width * r.height,
+        el,
+        ord: ord++,
+        root: paintRoot(el, container)
+      });
     };
     const shapeEls = container.querySelectorAll("rect, path");
     if (shapeEls.length === 0) {
@@ -3008,7 +3030,15 @@ function applyLabelContrast(container, opts = {}) {
       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((x3) => x3.ov > 0);
+      const txRoot = paintRoot(tx, container);
+      let over = 0;
+      const boxed = rects.map((mk) => ({ mk, ov: ovArea(mk.r) })).filter((x3) => {
+        if (!(x3.ov > 0)) return false;
+        if (drawnBeneath(x3.mk, tx, txRoot)) return true;
+        if (effAlpha(x3.mk) >= PILL_MIN_ALPHA) over++;
+        return false;
+      });
+      if (over > 0) report.paintedOver++;
       const pts = glyphSampleGrid({ left: tr.left, top: tr.top, width: tr.width, height: tr.height });
       const painted = pts.map(() => false);
       let unmeasured = 0;
@@ -3308,7 +3338,16 @@ function createChartHost(container, config) {
     if (!el) el = resolver.penetrateOverlayAt(e?.clientX, e?.clientY, clickSel);
     if (!el) el = resolver.resolveByGeometry(e?.clientX, e?.clientY, clickSel);
     if (!el) {
-      if (current && current.length) notify([], "user");
+      if (current && current.length) {
+        const slot = container[CONTAINER_SLOT_XF_CLEAR];
+        if (typeof slot === "function") {
+          try {
+            slot();
+          } catch {
+          }
+        }
+        if (current && current.length) notify([], "user");
+      }
       return;
     }
     const rows = parseRowIdxs(el.getAttribute(ROW_IDX_ATTR));

package/dist/index.mjs

@@ -128,7 +128,7 @@ import {
   unpinScrolledAxis,
   valuePlacementFlag,
   x
-} from "./chunk-LJU47KQS.mjs";
+} from "./chunk-EFOEZN4D.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -2114,6 +2114,88 @@ function sweepCandidates(seedHex) {
   return out;
 }
 
+// src/pendingGenerate.ts
+var PENDING_RECOVERY_WINDOW_MS = 9e5;
+var PENDING_RECOVERY_POLL_MS = 15e3;
+var PENDING_RECOVERY_FIRST_POLL_MS = 2e3;
+var PENDING_RECOVERY_FAST_PHASE_MS = 12e4;
+var PENDING_RECOVERY_MID_POLL_MS = 3e4;
+var PENDING_RECOVERY_SLOW_PHASE_MS = 3e5;
+var PENDING_RECOVERY_SLOW_POLL_MS = 6e4;
+function pendingRecoveryNextDelayMs(elapsedMs) {
+  if (elapsedMs < PENDING_RECOVERY_FAST_PHASE_MS) return PENDING_RECOVERY_POLL_MS;
+  if (elapsedMs < PENDING_RECOVERY_SLOW_PHASE_MS) return PENDING_RECOVERY_MID_POLL_MS;
+  return PENDING_RECOVERY_SLOW_POLL_MS;
+}
+function encodePendingGenerate(m2) {
+  const o2 = { v: m2.v, t: m2.t, c: m2.c, p: m2.p ?? "" };
+  if (Number.isFinite(m2.h)) o2.h = Math.max(0, Math.floor(m2.h));
+  return JSON.stringify(o2);
+}
+function parsePendingGenerate(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  try {
+    const o2 = JSON.parse(raw);
+    const v2 = Number(o2?.v), t2 = Number(o2?.t);
+    if (!Number.isFinite(v2) || v2 <= 0 || !Number.isFinite(t2) || t2 <= 0) return null;
+    const h2 = Number(o2?.h);
+    const m2 = { v: Math.floor(v2), t: Math.floor(t2), c: typeof o2.c === "string" ? o2.c : "", p: typeof o2.p === "string" ? o2.p : "" };
+    if (Number.isFinite(h2) && h2 >= 0) m2.h = Math.floor(h2);
+    return m2;
+  } catch {
+    return null;
+  }
+}
+function markerArmedBlind(m2) {
+  if (!m2) return false;
+  return (m2.h ?? m2.v - 1) <= 0;
+}
+function isBlindMarker(m2) {
+  if (!m2) return false;
+  return typeof m2.c !== "string" || m2.c.trim() === "";
+}
+function servedCorrelationProves(m2, served) {
+  if (!m2 || typeof m2.c !== "string" || m2.c.trim() === "") return false;
+  if (typeof served !== "string" || served.trim() === "") return false;
+  return served.trim().toLowerCase() === m2.c.trim().toLowerCase();
+}
+function sameMarker(a2, b2) {
+  if (!a2 || !b2) return false;
+  if (typeof a2.c !== "string" || typeof b2.c !== "string") return false;
+  const ca = a2.c.trim().toLowerCase(), cb = b2.c.trim().toLowerCase();
+  if (ca === "" || cb === "") return false;
+  return ca === cb;
+}
+function decidePendingRecovery(m2, nowMs, persistedVersion) {
+  if (!m2) return "none";
+  if ((persistedVersion ?? 0) >= m2.v) return "delivered";
+  if (nowMs - m2.t > PENDING_RECOVERY_WINDOW_MS) return "expired";
+  if (isBlindMarker(m2)) return "blind";
+  return "poll";
+}
+function recoveryPollRunning(d2) {
+  return d2 === "poll";
+}
+function recoveryOwnsTheSentence(trigger) {
+  return trigger !== "transport-lost";
+}
+function latePickupAction(m2, triedThisInstance) {
+  if (!m2 || isBlindMarker(m2)) return "clear";
+  return triedThisInstance ? "keep" : "fetch";
+}
+function latePickupKeepsMarker(outcome) {
+  return outcome === "transport";
+}
+function pollGiveUpKeepsMarker(outcome, m2) {
+  return outcome === "window-closed" && !!m2 && !isBlindMarker(m2);
+}
+function pendingRecoveryRemainingMs(m2, nowMs) {
+  return Math.max(0, m2.t + PENDING_RECOVERY_WINDOW_MS - nowMs);
+}
+function transportFailureShouldRecover(headersReceived, genNew) {
+  return headersReceived && genNew;
+}
+
 // src/index.ts
 function registerCityTable(packed) {
   L3(packed);
@@ -2177,6 +2259,13 @@ export {
   MIN_HIT_BAND_PX,
   MIN_RAMP_FILLS,
   PAGE_MATCH_TOLERANCE,
+  PENDING_RECOVERY_FAST_PHASE_MS,
+  PENDING_RECOVERY_FIRST_POLL_MS,
+  PENDING_RECOVERY_MID_POLL_MS,
+  PENDING_RECOVERY_POLL_MS,
+  PENDING_RECOVERY_SLOW_PHASE_MS,
+  PENDING_RECOVERY_SLOW_POLL_MS,
+  PENDING_RECOVERY_WINDOW_MS,
   PHANTOM_FRACTION,
   PILL_MIN_ALPHA,
   PILL_MIN_COVERAGE,
@@ -2229,7 +2318,9 @@ export {
   createMarkResolver,
   ctmScaleOf,
   decideLabelColor,
+  decidePendingRecovery,
   deltaEHex,
+  encodePendingGenerate,
   ensureCrossfilterHitTargets,
   explainRenderFailure,
   filterFitsChooser,
@@ -2245,14 +2336,18 @@ export {
   hitBandFlag,
   inlineFilterGate,
   isBlankRender,
+  isBlindMarker,
   isHorizontalLabelRow,
   isPhantomBox,
   isPillBackdropAlpha,
   labelBand,
+  latePickupAction,
+  latePickupKeepsMarker,
   launchFavorStyle,
   launchGenerates,
   listNeedsFilter,
   loadGeo,
+  markerArmedBlind,
   measureContainerBoxes,
   needsScroll,
   newQualifyGroupState,
@@ -2262,6 +2357,9 @@ export {
   normalizeFilterTerm,
   orderMostDistinct,
   orderRefusalsForDisplay,
+  parsePendingGenerate,
+  pendingRecoveryNextDelayMs,
+  pendingRecoveryRemainingMs,
   periodTickSuppressesFeedback,
   pickDistinctColorFromSeed,
   pillBacksGlyph,
@@ -2269,6 +2367,7 @@ export {
   planAxisPin,
   planFrameGrow,
   planTrivialChart,
+  pollGiveUpKeepsMarker,
   qualifyAuto,
   qualifyCancel,
   qualifyFailureFallsOpen,
@@ -2281,6 +2380,8 @@ export {
   rasterizeSvgToPngDataUrl,
   readQualifyChartRow,
   readQualifyRefusalRow,
+  recoveryOwnsTheSentence,
+  recoveryPollRunning,
   refusalIsSelectable,
   registerCityTable,
   registerGeo,
@@ -2289,7 +2390,9 @@ export {
   requiredD3Plugins,
   resolveAutoColorScale,
   resolveOptions,
+  sameMarker,
   scrollFitFor,
+  servedCorrelationProves,
   sessionViewStateProvider,
   shouldOpenChooserOnGenerate,
   shouldOpenInlineChooserOnGenerate,
@@ -2299,6 +2402,7 @@ export {
   svgNaturalSize,
   svgToDataUrl,
   toRGBA,
+  transportFailureShouldRecover,
   unpinScrolledAxis,
   valuePlacementFlag,
   vegaSpecReadsDatesInLocalTime

package/dist/react.mjs

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

package/dist/types/index.d.ts

@@ -32,3 +32,4 @@ export { pinScrolledAxis, unpinScrolledAxis, type AxisPinReport } from "./fitDom
 export { MIN_DELTA_E, pickDistinctColorFromSeed, buildPalette, buildPaletteFromSeed, orderMostDistinct, LEGIBLE_LIGHTNESS, type PaletteResult, type SeedForSlot, type PaletteOptions, } from "./palette";
 export { deltaEHex } from "./deltaE";
 export { resolveAutoColorScale, autoRampMinStep, autoRampCanvas, AUTO_RAMP_CLASSES, AUTO_RAMP_DRAWN_OPACITY, AUTO_RAMP_MIN_STEP_DELTA_E, type AutoColorScale, type AutoColorScaleInput } from "./autoRamp";
+export { PENDING_RECOVERY_WINDOW_MS, PENDING_RECOVERY_POLL_MS, PENDING_RECOVERY_FIRST_POLL_MS, PENDING_RECOVERY_FAST_PHASE_MS, PENDING_RECOVERY_MID_POLL_MS, PENDING_RECOVERY_SLOW_PHASE_MS, PENDING_RECOVERY_SLOW_POLL_MS, pendingRecoveryNextDelayMs, encodePendingGenerate, parsePendingGenerate, markerArmedBlind, isBlindMarker, servedCorrelationProves, sameMarker, decidePendingRecovery, recoveryPollRunning, recoveryOwnsTheSentence, latePickupAction, latePickupKeepsMarker, pollGiveUpKeepsMarker, pendingRecoveryRemainingMs, transportFailureShouldRecover, type PendingGenerateMarker, type PendingRecoveryDecision, type LatePickupAction, } from "./pendingGenerate";

package/dist/types/labelContrastDom.d.ts

@@ -27,6 +27,9 @@ export interface LabelContrastReport {
     offFill: number;
     /** Labels mostly over the page with one end clipping a mark - handed back to the chart. */
     pageMajority: number;
+    /** Labels with a painting shape over their box that was set aside because it is drawn ON TOP
+     *  of them - an occluder, never a background. See drawnBeneath. */
+    paintedOver: number;
     /** Why the pass did nothing, when it did nothing. */
     skipped?: "no-container" | "no-shapes" | "too-many-shapes" | "too-many-texts" | "error";
 }

package/dist/types/pendingGenerate.d.ts

@@ -0,0 +1,163 @@
+export interface PendingGenerateMarker {
+    /** The version this generate will produce: (version in hand || 0) + 1.
+     *  Diagnostic only - see "WHY `v` IS NOT A PREDICTION" below before trusting it. */
+    v: number;
+    /** Epoch ms when the generate started (client clock). */
+    t: number;
+    /** Correlation id of the generate - the ONLY safe handle for recovering it. */
+    c: string;
+    /** The explicit chart-type pick the user made for this generate ("" = none). */
+    p: string;
+    /** The version the host actually HELD when the generate started (0 = none).
+     *  Absent on markers written by older builds. Diagnostics, plus the blind test. */
+    h?: number;
+}
+export declare const PENDING_RECOVERY_WINDOW_MS = 900000;
+/** Poll cadence for the first {@link PENDING_RECOVERY_FAST_PHASE_MS}. Each poll is one
+ *  cheap fetch (and one server log row), so this is deliberately slow: the cost of finding the
+ *  chart 15 s late is nothing next to the cost of a second generation. */
+export declare const PENDING_RECOVERY_POLL_MS = 15000;
+/** First poll after a re-mount fires quickly - the service may already be done. */
+export declare const PENDING_RECOVERY_FIRST_POLL_MS = 2000;
+/** Up to here the poll runs at {@link PENDING_RECOVERY_POLL_MS} - covers production's p50. */
+export declare const PENDING_RECOVERY_FAST_PHASE_MS = 120000;
+/** ...then at this cadence up to {@link PENDING_RECOVERY_SLOW_PHASE_MS}. */
+export declare const PENDING_RECOVERY_MID_POLL_MS = 30000;
+export declare const PENDING_RECOVERY_SLOW_PHASE_MS = 300000;
+/** ...and at this one for the rest of the window. */
+export declare const PENDING_RECOVERY_SLOW_POLL_MS = 60000;
+/**
+ * How long to wait before the NEXT poll, given how long the generate has been running.
+ *
+ * Tripling the window would have tripled the poll count at a flat 15 s (60 requests, 60 server log
+ * rows), and every one of them after the first couple of minutes is asking about a generate that is
+ * plainly slow. So the cadence backs off with age while leaving the FAST phase exactly as it was - a
+ * chart that lands inside production's normal range is still picked up within 15 s of finishing,
+ * which is the case that actually happens.
+ *
+ *   0 - 2 min   every 15 s   (9 polls)   production p50 82 s lands here
+ *   2 - 5 min   every 30 s   (6 polls)   production p99 383 s lands here
+ *   5 - 15 min  every 60 s   (10 polls)  the long tail
+ *
+ * ~25 polls across 15 minutes, against 60 for a flat cadence over the same window.
+ */
+export declare function pendingRecoveryNextDelayMs(elapsedMs: number): number;
+export declare function encodePendingGenerate(m: PendingGenerateMarker): string;
+export declare function parsePendingGenerate(raw: unknown): PendingGenerateMarker | null;
+export type PendingRecoveryDecision = "none" | "delivered" | "expired" | "blind" | "poll";
+/**
+ * What to do with a marker found at mount (or after a transport failure).
+ * @param persistedVersion the version the host HAS, 0/null = none
+ */
+/**
+ * Was this marker armed holding NO version? If so its `v` is 1, which the service reads as "the
+ * shape's first chart" rather than "this host's first chart". `h` is the explicit signal; the
+ * `v - 1` fallback says the same thing for markers written by older builds.
+ */
+export declare function markerArmedBlind(m: PendingGenerateMarker | null | undefined): boolean;
+/**
+ * Can this marker be recovered AT ALL? Only by CORRELATION, so only if it carries one.
+ *
+ * A version number is never a safe handle, not even when we held one: the number we hold came FROM
+ * the service and is therefore a shape version, so "mine + 1" is still a guess about what everyone
+ * else did next. The poll consequently asks by correlation ALONE and sends no version at all - which
+ * is also what makes this safe against a service too old to understand the field, because such a
+ * service refuses a fetchOnly request with no version and can serve nothing. A marker with no
+ * correlation (written by an older build) has no usable handle and is not polled.
+ *
+ * One definition, shared by the mount-time decision and the transport-lost message.
+ */
+export declare function isBlindMarker(m: PendingGenerateMarker | null | undefined): boolean;
+/**
+ * Does `served` (the service's statement of whose generation it returned) prove this marker's
+ * chart? Absence is REFUSAL, not assent: an older service says nothing here, and a recovery that
+ * cannot tell your chart from a stranger's is worse than no recovery.
+ */
+export declare function servedCorrelationProves(m: PendingGenerateMarker | null | undefined, served: string | null | undefined): boolean;
+/**
+ * Are these the SAME pending generate? By correlation, never by version.
+ *
+ * Found 2026-08-30, and the log showed the bug in two adjacent lines. A poll was running for one
+ * correlation when the user clicked Generate again, arming a second. The poll's "has the marker
+ * changed under me?" guard compared `m.v` - and EVERY marker armed by a host holding no chart is
+ * `v: 1`, so `1 !== 1` was false and the stale poll did not notice it had been superseded. Four
+ * minutes later its window closed and it cleared the marker belonging to the generate that was
+ * still running:
+ *
+ *     pending-gen-poll-end  {"outcome":"window-closed","c":"<the first correlation>"}
+ *     pending-gen-cleared   {"reason":"poll-window-closed","c":"<the second correlation>"}
+ *
+ * The live generate lost its recovery marker 35 s after starting, and the user was told "nothing
+ * was delivered" about a chart that was still being written. The same lesson as `v` above: a shape
+ * version that the whole account moves can never identify one host's request. The correlation can.
+ *
+ * Two markers with no correlation are never "the same" - there is nothing to compare, and a false
+ * match here is what clears a stranger's marker.
+ */
+export declare function sameMarker(a: PendingGenerateMarker | null | undefined, b: PendingGenerateMarker | null | undefined): boolean;
+export declare function decidePendingRecovery(m: PendingGenerateMarker | null, nowMs: number, persistedVersion: number | null | undefined): PendingRecoveryDecision;
+/**
+ * Did the recovery actually START A PICKUP? Only "poll" does - "expired", "delivered", "blind" and
+ * "none" all clear the marker and walk away.
+ *
+ * ONE definition, because the caller's SENTENCE has to agree with it. Found 2026-08-28: a generate
+ * ran nearly seventeen minutes, the transport died, and the transport-lost branch chose its wording
+ * from `isBlindMarker` alone - true enough on its own terms, the marker did carry a correlation -
+ * while the recovery had already returned "expired" against the window and polled for nothing. The
+ * user was told the chart was being checked for and would appear, with nothing checking for
+ * anything. A property of the MARKER cannot answer a question about the DECISION; only the decision
+ * can.
+ */
+export declare function recoveryPollRunning(d: PendingRecoveryDecision): boolean;
+/**
+ * Does the RECOVERY PATH own the sentence for this trigger, or does its caller?
+ *
+ * On "transport-lost" the host's retry loop is mid-render and already owns the message, which it
+ * words from the decision (recoveryPollRunning above). Anything the recovery says on top of that
+ * stacks a second sentence stating the same fact, and when both are painted the reader sees it twice
+ * in slightly different words - seen 2026-09-04, where the connection-dropped explanation appeared
+ * back to back with itself.
+ *
+ * On a MOUNT (or any other trigger) nothing else speaks, so the recovery must.
+ */
+export declare function recoveryOwnsTheSentence(trigger: string): boolean;
+/**
+ * THE ONE-SHOT LATE PICKUP.
+ *
+ * An EXPIRED marker used to be cleared on sight. But "expired" is a fact about the POLL WINDOW, not
+ * about the chart: the service writes the generation when it finishes and serves it by correlation
+ * for good. Seen in production: a corporate egress proxy cut the stream at 66 s, the poll armed, the
+ * host stopped reporting within seconds, the service finished at 75 s - and a reader who reopened
+ * the report later would have found the marker, called it expired, and cleared a finished, charged
+ * chart.
+ *
+ * So a MOUNT that finds an expired marker with a correlation fetches ONCE before letting go:
+ *   "fetch"  - a correlation to ask by, and this host instance has not asked for it yet;
+ *   "keep"   - this instance already asked (its own poll ran out, or a pickup already tried), so the
+ *              marker waits for the NEXT mount - a data refresh seconds after the window closed must not
+ *              spend the one fetch before a slow generate has finished;
+ *   "clear"  - no marker, or no correlation to ask by (a version is never a safe handle).
+ */
+export type LatePickupAction = "fetch" | "keep" | "clear";
+export declare function latePickupAction(m: PendingGenerateMarker | null | undefined, triedThisInstance: boolean): LatePickupAction;
+/**
+ * After the late pickup's one fetch: only a TRANSPORT failure keeps the marker - the question never
+ * reached the service, so a later mount may still ask. An answer of not-found, or a definitive
+ * refusal, is the service saying there is nothing to deliver, and the marker goes.
+ */
+export declare function latePickupKeepsMarker(outcome: "found" | "not-yet" | "hard-error" | "transport"): boolean;
+/**
+ * When the 15-minute poll runs out ("window-closed"), the marker STAYS for the next mount's late
+ * pickup, as long as it carries a correlation. A definitive refusal ("hard-error") still clears it.
+ */
+export declare function pollGiveUpKeepsMarker(outcome: string, m: PendingGenerateMarker | null | undefined): boolean;
+/** Milliseconds left in the recovery window from `nowMs`, floored at 0. */
+export declare function pendingRecoveryRemainingMs(m: PendingGenerateMarker, nowMs: number): number;
+/**
+ * Whether a transport failure on a generate should hand off to the recovery poll (true) or fall back
+ * to the ordinary retry (false). The discriminator is whether the service ACCEPTED the request: a
+ * streaming endpoint commits its 200 headers the moment it starts, so headers-received plus a later
+ * failure means the generate is running server-side and a retry would make a SECOND chart. No
+ * headers means the service never saw it, and retrying is the right move.
+ */
+export declare function transportFailureShouldRecover(headersReceived: boolean, genNew: boolean): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.5.101",
+  "version": "0.5.103",
   "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",