@bicharts/chart-host 0.5.26 → 0.5.28

package/dist/{chunk-PAX7FM4P.mjs → chunk-5DV7OOBW.mjs}

@@ -425,20 +425,20 @@ function A3(n) {
   if (r && i && c3(r) !== i && (r = null), n.city !== void 0 && n.city !== null) {
     let a2 = u(String(n.city)), s = O(a2), f = s ? F(s, n.mapKind) : null;
     if (f && f.length) {
-      let d = n.state === void 0 || n.state === null ? "" : String(n.state).trim(), R = d ? u(d) : "", g = d ? Y(d) : null, S = [], m2 = -1;
+      let d = n.state === void 0 || n.state === null ? "" : String(n.state).trim(), R = d ? u(d) : "", g = d ? Y(d) : null, S2 = [], m2 = -1;
       for (let c of f) {
         let l = c.row, A = 0;
         if (d && l.a1 !== "") if (g && l.a1 === g || u(l.a1) === R) A++;
         else continue;
         if (i) if (T(l.cc) === i) A++;
         else continue;
-        A > m2 ? (m2 = A, S = [c]) : A === m2 && S.push(c);
+        A > m2 ? (m2 = A, S2 = [c]) : A === m2 && S2.push(c);
       }
-      S.some((c) => c.primary) && (S = S.filter((c) => c.primary));
+      S2.some((c) => c.primary) && (S2 = S2.filter((c) => c.primary));
       let p2 = /* @__PURE__ */ new Map();
-      for (let c of S) p2.set(c.row.lon.toFixed(2) + "," + c.row.lat.toFixed(2), c.row);
+      for (let c of S2) p2.set(c.row.lon.toFixed(2) + "," + c.row.lat.toFixed(2), c.row);
       if (p2.size === 1) {
-        let c = S[0].row;
+        let c = S2[0].row;
         return { lat: c.lat, lon: c.lon, precision: "city" };
       }
       if (p2.size > 1) return { ambiguous: true, matches: p2.size };
@@ -461,7 +461,7 @@ function A3(n) {
 var G = { latlon: 0, city: 1, zip3: 2, state: 3, country: 4 };
 var x = 8;
 function y3(n, e) {
-  let t = new Array(n.length), o = new Array(n.length), i = new Array(n.length), r = /* @__PURE__ */ new Set(), a2 = [], s = /* @__PURE__ */ new Set(), f = [], d = /* @__PURE__ */ new Set(), R = [], g = { latlon: 0, city: 0, zip3: 0, state: 0, country: 0 }, S = 0, m2 = 0, p2 = null;
+  let t = new Array(n.length), o = new Array(n.length), i = new Array(n.length), r = /* @__PURE__ */ new Set(), a2 = [], s = /* @__PURE__ */ new Set(), f = [], d = /* @__PURE__ */ new Set(), R = [], g = { latlon: 0, city: 0, zip3: 0, state: 0, country: 0 }, S2 = 0, m2 = 0, p2 = null;
   for (let l = 0; l < n.length; ++l) {
     let A = n[l], C2 = A3({ ...A, mapKind: e });
     if (S3(C2)) {
@@ -469,7 +469,7 @@ function y3(n, e) {
       let M = K(A);
       M && !d.has(M.toLowerCase()) && (d.add(M.toLowerCase()), R.length < x && R.push(M));
     } else if (C2) {
-      if (t[l] = C2.lat, o[l] = C2.lon, i[l] = C2.precision, S++, g[C2.precision]++, (p2 === null || G[C2.precision] > G[p2]) && (p2 = C2.precision), G[C2.precision] > G.city) {
+      if (t[l] = C2.lat, o[l] = C2.lon, i[l] = C2.precision, S2++, g[C2.precision]++, (p2 === null || G[C2.precision] > G[p2]) && (p2 = C2.precision), G[C2.precision] > G.city) {
         let M = K(A);
         M && !s.has(M.toLowerCase()) && (s.add(M.toLowerCase()), f.length < x && f.push(M));
       }
@@ -480,7 +480,7 @@ function y3(n, e) {
     }
   }
   let c = !n3() && n.some((l) => l.city !== null && l.city !== void 0 && String(l.city).trim() !== "");
-  return { lat: t, lon: o, precisions: i, precision: p2, precisionCounts: g, coarseExamples: f, unmatched: a2, ambiguousRows: m2, ambiguousExamples: R, matchedRows: S, totalRows: n.length, ...c ? { cityTableMissing: true } : {} };
+  return { lat: t, lon: o, precisions: i, precision: p2, precisionCounts: g, coarseExamples: f, unmatched: a2, ambiguousRows: m2, ambiguousExamples: R, matchedRows: S2, totalRows: n.length, ...c ? { cityTableMissing: true } : {} };
 }
 function K(n) {
   let e = [n.city, n.state, n.zip, n.country].filter((t) => t != null && String(t).trim() !== "").map((t) => String(t).trim()).join(", ");
@@ -561,11 +561,11 @@ function wn(n) {
 }
 function Kn(n, s) {
   let i = new Array(n.length), r = /* @__PURE__ */ new Set(), A = [], y2 = 0;
-  for (let S = 0; S < n.length; ++S) {
-    let O3 = hn(n[S], s);
-    if (i[S] = O3, O3 !== null) y2++;
+  for (let S2 = 0; S2 < n.length; ++S2) {
+    let O3 = hn(n[S2], s);
+    if (i[S2] = O3, O3 !== null) y2++;
     else {
-      let C2 = n[S];
+      let C2 = n[S2];
       if (C2 != null) {
         let d = String(C2).trim();
         if (d.length > 0) {
@@ -612,14 +612,14 @@ function E2(r) {
   for (let s of n) N2(s) && e++;
   return Math.round(e / n.length * 1e3) / 10;
 }
-function v2(r) {
+function S(r) {
   let n = P2(r);
   if (n.length === 0) return 0;
   let e = 0;
   for (let s of n) Y(s) && e++;
   return Math.round(e / n.length * 1e3) / 10;
 }
-function B2(r) {
+function D2(r) {
   let n = /* @__PURE__ */ new Set();
   for (let e of r) {
     if (e == null) continue;
@@ -629,16 +629,16 @@ function B2(r) {
   return Array.from(n);
 }
 function O2(r) {
-  let n = B2(r);
+  let n = D2(r);
   if (n.length === 0) return 0;
   let e = 0;
   for (let s of n) Z(s).length > 0 && e++;
   return Math.round(e / n.length * 1e3) / 10;
 }
 function Z2(r, n) {
-  return p(n, en) ? true : B2(r).some((e) => /^\d{5}(-\d{4})?$/.test(e.replace(/\.0+$/, "")));
+  return p(n, en) ? true : D2(r).some((e) => /^\d{5}(-\d{4})?$/.test(e.replace(/\.0+$/, "")));
 }
-function zt(r, n) {
+function Gt(r, n) {
   let e = P2(r);
   if (e.length === 0) return 0;
   let s = 0;
@@ -650,13 +650,13 @@ function $2(r, n) {
   for (let s of P2(r)) n(s) && e++;
   return e;
 }
-function Gt(r, n) {
+function _t(r, n) {
   let e = 0;
-  for (let s of B2(r)) n(s) && e++;
+  for (let s of D2(r)) n(s) && e++;
   return e;
 }
-function _t(r, n, e, s) {
-  let l = [], c = [], o = {}, T2 = {}, k2 = new Set(r), u2 = (t) => n.map((i) => i[t]);
+function wt(r, n, e, s) {
+  let l = [], c = [], o = {}, v2 = {}, k2 = new Set(r), u2 = (t) => n.map((i) => i[t]);
   for (let t of ["city", "lat", "lon", "country"]) {
     let i = e?.[t];
     i && k2.has(i) && (o[t] = i);
@@ -669,25 +669,25 @@ function _t(r, n, e, s) {
   let m2 = e?.state;
   if (m2 && k2.has(m2)) {
     let t = u2(m2), i = P2(t);
-    i.length > 0 && i.every((a2) => q2(a2, s)) ? c.push(`state=${m2} (every value is "CA", which is both Canada and California)`) : C(t) ? (c.push(`state=${m2} (every value is a country, not a state)`), o.country || (o.country = m2)) : v2(t) < 95 ? c.push(`state=${m2} (only ${v2(t)}% of values are states/provinces)`) : o.state = m2;
+    i.length > 0 && i.every((a2) => q2(a2, s)) ? c.push(`state=${m2} (every value is "CA", which is both Canada and California)`) : C(t) ? (c.push(`state=${m2} (every value is a country, not a state)`), o.country || (o.country = m2)) : S(t) < 95 ? c.push(`state=${m2} (only ${S(t)}% of values are states/provinces)`) : o.state = m2;
   }
-  let d = new Set(Object.values(o).filter(Boolean)), b2 = r.filter((t) => !d.has(t) && !t.startsWith("__"));
+  let d = new Set(Object.values(o).filter(Boolean)), x2 = r.filter((t) => !d.has(t) && !t.startsWith("__"));
   if (!o.state) {
     let t = null;
-    for (let i of b2) {
+    for (let i of x2) {
       let a2 = u2(i);
       if (C(a2)) continue;
-      let f = v2(a2);
+      let f = S(a2);
       if (f < 95) continue;
-      let z2 = $2(a2, (R) => !!Y(R)), W2 = $2(a2, (R) => !!Y(R) && !q2(R, s));
+      let z2 = $2(a2, (b2) => !!Y(b2)), W2 = $2(a2, (b2) => !!Y(b2) && !q2(b2, s));
       z2 < w && W2 < 1 || (!t || f > t.pct) && (t = { name: i, pct: f });
     }
     t && (o.state = t.name, d.add(t.name), l.push(`state=${t.name} (${t.pct}% states/provinces)`));
   }
-  if (!o.zip) for (let t of b2) {
+  if (!o.zip) for (let t of x2) {
     if (d.has(t)) continue;
     let i = u2(t), a2 = O2(i);
-    if (!(a2 < 95) && Z2(i, t) && !(Gt(i, (f) => Z(f).length > 0) < w)) {
+    if (!(a2 < 95) && Z2(i, t) && !(_t(i, (f) => Z(f).length > 0) < w)) {
       o.zip = t, d.add(t), l.push(`zip=${t} (${a2}% ZIP codes)`);
       break;
     }
@@ -695,27 +695,27 @@ function _t(r, n, e, s) {
   let h2 = o.country;
   if (!h2 || !C(u2(h2))) {
     let t = null;
-    for (let i of b2) {
+    for (let i of x2) {
       if (d.has(i) || !C(u2(i))) continue;
       let a2 = E2(u2(i));
       (!t || a2 > t.pct) && (t = { name: i, pct: a2 });
     }
-    t && (h2 && (c.push(`country=${h2} (only ${E2(u2(h2))}% of values are country identifiers; using ${t.name} instead)`), T2.country = h2), o.country = t.name, d.add(t.name), l.push(`country=${t.name}`));
+    t && (h2 && (c.push(`country=${h2} (only ${E2(u2(h2))}% of values are country identifiers; using ${t.name} instead)`), v2.country = h2), o.country = t.name, d.add(t.name), l.push(`country=${t.name}`));
   }
   if (!o.city) {
     let t = null;
-    for (let i of b2) {
+    for (let i of x2) {
       if (d.has(i)) continue;
-      let a2 = u2(i), f = zt(a2, s);
+      let a2 = u2(i), f = Gt(a2, s);
       f < m3 || $2(a2, (z2) => p3(z2, s)) < w || (!t || f > t.pct) && (t = { name: i, pct: f });
     }
     t && (o.city = t.name, l.push(`city=${t.name} (${t.pct}% known cities)`));
   }
-  let D2 = o.country ? u2(o.country) : [], I2 = !!o.country && C(D2), U2 = I2 ? new Set(D2.map((t) => E(t == null ? null : String(t))).filter(Boolean)).size : 0, F2 = I2 && U2 >= 2, L2 = !!(o.lat && o.lon) && n.some((t) => {
+  let B2 = o.country ? u2(o.country) : [], I2 = !!o.country && C(B2), U2 = I2 ? new Set(B2.map((t) => E(t == null ? null : String(t))).filter(Boolean)).size : 0, F2 = I2 && U2 >= 2, L2 = !!(o.lat && o.lon) && n.some((t) => {
     let i = +String(t[o.lat] ?? "").trim(), a2 = +String(t[o.lon] ?? "").trim();
     return isFinite(i) && isFinite(a2) && i >= -90 && i <= 90 && a2 >= -180 && a2 <= 180 && String(t[o.lat] ?? "").trim() !== "" && String(t[o.lon] ?? "").trim() !== "";
   });
-  return o.lat && o.lon && !L2 && c.push(`lat/lon=${o.lat}/${o.lon} (no row holds a usable coordinate pair)`), o.country && !F2 && !(o.city || o.state || o.zip || L2) && c.push(I2 ? `country=${o.country} (every row resolves to the same country - nothing to place apart)` : `country=${o.country} (values are not country identifiers)`), { bind: !!(o.city || o.state || o.zip || F2 || L2) ? o : null, backfilled: l, refused: c, ...Object.keys(T2).length ? { labelFallback: T2 } : {} };
+  return o.lat && o.lon && !L2 && c.push(`lat/lon=${o.lat}/${o.lon} (no row holds a usable coordinate pair)`), o.country && !F2 && !(o.city || o.state || o.zip || L2) && c.push(I2 ? `country=${o.country} (every row resolves to the same country - nothing to place apart)` : `country=${o.country} (values are not country identifiers)`), { bind: !!(o.city || o.state || o.zip || F2 || L2) ? o : null, backfilled: l, refused: c, ...Object.keys(v2).length ? { labelFallback: v2 } : {} };
 }
 
 // src/payload.ts
@@ -730,7 +730,7 @@ function resolvePointChannel(cols, rowObjs, point) {
   let labelCol;
   if (bind) {
     const dims = cols.filter((c) => !c.isMeasure).map((c) => c.name);
-    const res = _t(dims, rowObjs, bind, point?.mapKind);
+    const res = wt(dims, rowObjs, bind, point?.mapKind);
     bind = res.bind;
     rolesBackfilled = res.backfilled;
     rolesRefused = res.refused;
@@ -798,11 +798,11 @@ function buildRenderPayload(cols, rowObjs, geo, point, destination) {
     const row = rowObjs[r];
     const a2 = new Array(cols.length + extra);
     for (let c = 0; c < cols.length; c++) {
-      const v3 = row[colNames[c]];
-      if (v3 instanceof Date) {
-        a2[c] = v3.toISOString();
+      const v2 = row[colNames[c]];
+      if (v2 instanceof Date) {
+        a2[c] = v2.toISOString();
       } else {
-        a2[c] = v3 ?? null;
+        a2[c] = v2 ?? null;
       }
     }
     let k2 = cols.length;
@@ -1071,7 +1071,7 @@ function createChartHost(container, config) {
   let data = config.data;
   {
     const stamped = config.data?.meta?.hostContract;
-    const major = (v3) => (v3 || "").split(".")[0];
+    const major = (v2) => (v2 || "").split(".")[0];
     if (stamped && major(stamped) !== major(HOST_CONTRACT_VERSION)) {
       try {
         (win?.console ?? console)?.warn(

package/dist/index.mjs

@@ -42,7 +42,7 @@ import {
   requiredD3Plugins,
   resolveOptions,
   stripEsmExports
-} from "./chunk-PAX7FM4P.mjs";
+} from "./chunk-5DV7OOBW.mjs";
 import "./chunk-A2GMXZP7.mjs";
 
 // src/trivial.ts
@@ -317,6 +317,135 @@ function histogramSource(idx, name) {
 }`;
 }
 
+// src/snapshot.ts
+var DEFAULT_TIMEOUT_MS = 2e3;
+function svgToDataUrl(svg) {
+  const cloned = svg.cloneNode(true);
+  const w = svg.clientWidth || svg.getBoundingClientRect && svg.getBoundingClientRect().width || 600;
+  const h = svg.clientHeight || svg.getBoundingClientRect && svg.getBoundingClientRect().height || 400;
+  cloned.setAttribute("width", String(Math.round(w)));
+  cloned.setAttribute("height", String(Math.round(h)));
+  if (!cloned.getAttribute("xmlns")) cloned.setAttribute("xmlns", "http://www.w3.org/2000/svg");
+  const svgStr = new XMLSerializer().serializeToString(cloned);
+  const bytes = new TextEncoder().encode(svgStr);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return "data:image/svg+xml;base64," + btoa(binary);
+}
+function svgNaturalSize(svg) {
+  const w = svg.clientWidth || svg.getBoundingClientRect && svg.getBoundingClientRect().width || 600;
+  const h = svg.clientHeight || svg.getBoundingClientRect && svg.getBoundingClientRect().height || 400;
+  return { width: Math.round(w), height: Math.round(h) };
+}
+function rasterizeSvgToPngDataUrl(svgDataUrl, width, height, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return new Promise((resolve) => {
+    let img;
+    try {
+      img = new Image();
+    } catch (e) {
+      opts.onWarn?.("snapshot-no-image", e instanceof Error ? e.message : String(e));
+      resolve(null);
+      return;
+    }
+    const timer = setTimeout(() => {
+      opts.onWarn?.("snapshot-raster-timeout", { width, height, timeoutMs });
+      resolve(null);
+    }, timeoutMs);
+    img.onload = () => {
+      clearTimeout(timer);
+      try {
+        const cap = opts.maxSide && opts.maxSide > 0 ? opts.maxSide : Math.max(width, height);
+        const scale = Math.min(1, cap / Math.max(width, height));
+        const cw = Math.max(1, Math.round(width * scale));
+        const ch = Math.max(1, Math.round(height * scale));
+        const canvas = document.createElement("canvas");
+        canvas.width = cw;
+        canvas.height = ch;
+        const c2d = canvas.getContext("2d");
+        if (!c2d) {
+          resolve(null);
+          return;
+        }
+        c2d.fillStyle = "white";
+        c2d.fillRect(0, 0, cw, ch);
+        c2d.drawImage(img, 0, 0, cw, ch);
+        resolve(canvas.toDataURL("image/png"));
+      } catch (e) {
+        opts.onWarn?.("snapshot-raster-draw", e instanceof Error ? e.message : String(e));
+        resolve(null);
+      }
+    };
+    img.onerror = () => {
+      clearTimeout(timer);
+      opts.onWarn?.("snapshot-raster-decode", { width, height });
+      resolve(null);
+    };
+    img.src = svgDataUrl;
+  });
+}
+async function captureSvgSnapshot(root, opts = {}) {
+  if (!root) return null;
+  const svg = root instanceof SVGSVGElement ? root : root.querySelector("svg");
+  if (!svg) return null;
+  let svgUrl;
+  try {
+    svgUrl = svgToDataUrl(svg);
+  } catch (e) {
+    opts.onWarn?.("snapshot-serialize", e instanceof Error ? e.message : String(e));
+    return null;
+  }
+  const { width, height } = svgNaturalSize(svg);
+  try {
+    const png = await rasterizeSvgToPngDataUrl(svgUrl, width, height, opts);
+    return png || svgUrl;
+  } catch (e) {
+    opts.onWarn?.("snapshot-raster-unexpected", e instanceof Error ? e.message : String(e));
+    return svgUrl;
+  }
+}
+
+// src/review.ts
+function shouldReview(g) {
+  if (!g.enabled) return false;
+  if (!g.modeLicensed) return false;
+  if (!g.firstRenderAfterGenerate) return false;
+  if (!g.codeVersion || g.codeVersion <= 0) return false;
+  if (g.inFlight) return false;
+  if (g.reviewedVersions.has(g.codeVersion)) return false;
+  return true;
+}
+function bareBase64(dataUrlOrB64) {
+  const m = /^data:([^;,]+);base64,(.*)$/s.exec(dataUrlOrB64 || "");
+  if (m) return { b64: m[2], mediaType: m[1] };
+  return { b64: dataUrlOrB64 || "", mediaType: "image/png" };
+}
+function buildReviewWire(input) {
+  const { b64, mediaType } = bareBase64(input.capture);
+  return {
+    request: input.request,
+    imageBase64: b64,
+    imageMediaType: mediaType,
+    version: input.version,
+    originalAsk: (input.originalAsk ?? "").toString(),
+    codeSummary: (input.codeSummary ?? "").toString(),
+    chartType: (input.chartType ?? "").toString(),
+    correlationId: (input.correlationId ?? "").toString()
+  };
+}
+function actionFor(v) {
+  if (!v) return { kind: "keep", reason: "no verdict returned", userVisible: false };
+  if (v.status === "PROPOSED") {
+    const instr = (v.instruction ?? "").toString().trim();
+    if (instr === "") return { kind: "keep", reason: "reviewer proposed no actionable change", userVisible: false };
+    return { kind: "propose", instruction: instr, reason: (v.verdictReason ?? "").toString().trim() };
+  }
+  if (v.status === "OK" && v.fix) return { kind: "apply-fix", fix: v.fix, reason: v.verdictReason ?? "" };
+  if (v.status === "NOCHANGE") return { kind: "keep", reason: v.verdictReason ?? "the chart renders as asked", userVisible: false };
+  if (v.status === "REFUSED") return { kind: "keep", reason: v.errorMessage ?? "review not available", userVisible: false };
+  return { kind: "keep", reason: v.errorMessage ?? v.verdictReason ?? "review failed", userVisible: false };
+}
+
 // src/index.ts
 function registerCityTable(packed) {
   L3(packed);
@@ -349,7 +478,11 @@ export {
   ROW_IDX_ATTR,
   SELECTION_ACTIVE_CLASS,
   XFILTER_REFRESH_EVENT,
+  actionFor,
+  bareBase64,
   buildRenderPayload,
+  buildReviewWire,
+  captureSvgSnapshot,
   clearGeoCache,
   compileRenderFn,
   compileTrivialSource,
@@ -360,10 +493,14 @@ export {
   geoFromCache,
   loadGeo,
   planTrivialChart,
+  rasterizeSvgToPngDataUrl,
   registerCityTable,
   registerGeo,
   registerGeoAsset,
   requiredD3Plugins,
   resolveOptions,
-  stripEsmExports
+  shouldReview,
+  stripEsmExports,
+  svgNaturalSize,
+  svgToDataUrl
 };

package/dist/react.mjs

@@ -4,7 +4,7 @@ import {
   createChartHost,
   geoFromCache,
   loadGeo
-} from "./chunk-PAX7FM4P.mjs";
+} from "./chunk-5DV7OOBW.mjs";
 import "./chunk-A2GMXZP7.mjs";
 
 // src/react.tsx

package/dist/types/index.d.ts

@@ -8,3 +8,5 @@ export { buildRenderPayload, type RenderPayload, type GeoPointBinding } from "./
 export { createChartHost, compileRenderFn, stripEsmExports, requiredD3Plugins, explainRenderFailure, type ChartHost, type ChartHostConfig, type RenderFn } from "./host";
 export { createMarkResolver, type MarkResolver, type MarkResolverEnv } from "./selection";
 export { planTrivialChart, compileTrivialSource, type TrivialPlan, type TrivialShapeKind } from "./trivial";
+export { captureSvgSnapshot, svgToDataUrl, svgNaturalSize, rasterizeSvgToPngDataUrl, type SnapshotOptions } from "./snapshot";
+export { shouldReview, buildReviewWire, bareBase64, actionFor, type ReviewGate, type ReviewWire, type ReviewVerdict, type ReviewAction } from "./review";

package/dist/types/review.d.ts

@@ -0,0 +1,89 @@
+/** The facts a "should we review this render?" decision needs, named so policy reads in one place. */
+export interface ReviewGate {
+    /** The user's settings toggle. Reviews are strictly opt-in. */
+    enabled: boolean;
+    /** Licensed accounts only — the host checks its own credential shape and says so here. */
+    modeLicensed: boolean;
+    /**
+     * True when THIS render is the first paint after a generate this session. A cached
+     * restore, a resize, a cross-filter repaint — none of these are "the first render from a
+     * generate", and reviewing them would judge the same pixels twice.
+     */
+    firstRenderAfterGenerate: boolean;
+    /** The version on screen. 0/undefined = nothing to review. */
+    codeVersion: number | null | undefined;
+    /**
+     * Versions this session already submitted. Guards re-entrancy: an applied fix's own first
+     * render must not trigger a second review of the fix — a fix of a fix of a fix is a
+     * billing loop.
+     */
+    reviewedVersions: ReadonlySet<number>;
+    /** A review already in flight for this instance. */
+    inFlight: boolean;
+}
+/** Should a review fire for this render? Every clause is a reason NOT to, because the free
+ *  direction is "no review". */
+export declare function shouldReview(g: ReviewGate): boolean;
+/** The review endpoint's wire body. `request` is the SAME generate request the host would send
+ *  for a modify of the reviewed version — the service writes the fix intent into it, so an
+ *  applied fix is provably an ordinary modify of exactly this request. */
+export interface ReviewWire {
+    request: unknown;
+    imageBase64: string;
+    imageMediaType: string;
+    version: number;
+    originalAsk: string;
+    codeSummary: string;
+    chartType: string;
+    correlationId: string;
+    /**
+     * THE SECOND HALF of the propose/accept round-trip. Absent on the judging call; set to the
+     * proposal's instruction — verbatim — when the user accepted. Its presence is the whole
+     * difference between a free judgement and a billed modify.
+     */
+    applyInstruction?: string;
+}
+/** Strip a data-URL prefix if the capture produced one; the wire carries bare base64. */
+export declare function bareBase64(dataUrlOrB64: string): {
+    b64: string;
+    mediaType: string;
+};
+export declare function buildReviewWire(input: {
+    request: unknown;
+    capture: string;
+    version: number;
+    originalAsk: string | null | undefined;
+    codeSummary: string | null | undefined;
+    chartType: string | null | undefined;
+    correlationId: string | null | undefined;
+}): ReviewWire;
+/** What the service answers, camelCase on the wire. */
+export interface ReviewVerdict {
+    status: "PROPOSED" | "OK" | "NOCHANGE" | "REFUSED" | "ERROR" | string;
+    verdictReason?: string | null;
+    /** Set only on PROPOSED: the judge's instruction, sent back verbatim if the user accepts. */
+    instruction?: string | null;
+    /** A full generate result when status === "OK": the fix IS a modify. */
+    fix?: unknown;
+    errorMessage?: string | null;
+}
+/** How the host should react to a verdict:
+ *  - propose   → ASK THE USER; nothing has been charged and declining stays free;
+ *  - apply-fix → the accepted round-trip answered with a finished result — apply and re-render;
+ *  - keep      → chart untouched; log the reason. A REFUSED never surfaces as a user error:
+ *                the toggle was on for an account that cannot use the feature, and the chart
+ *                is fine. */
+export type ReviewAction = {
+    kind: "propose";
+    instruction: string;
+    reason: string;
+} | {
+    kind: "apply-fix";
+    fix: unknown;
+    reason: string;
+} | {
+    kind: "keep";
+    reason: string;
+    userVisible: boolean;
+};
+export declare function actionFor(v: ReviewVerdict | null | undefined): ReviewAction;

package/dist/types/snapshot.d.ts

@@ -0,0 +1,32 @@
+export interface SnapshotOptions {
+    /**
+     * Cap the raster's longest side, preserving aspect. Keeps a giant viewport from producing
+     * a multi-megabyte PNG. 0 = no cap (raster at the SVG's natural size).
+     */
+    maxSide?: number;
+    /** Deadline for the SVG decode, in ms. Past it the raster resolves null. */
+    timeoutMs?: number;
+    /** Diagnostic sink for the silent-failure paths. */
+    onWarn?: (event: string, detail?: unknown) => void;
+}
+/**
+ * Serialize an SVG element to a `data:image/svg+xml;base64,` URL, with intrinsic
+ * width/height inlined on a clone so a later Image() load knows its size.
+ */
+export declare function svgToDataUrl(svg: SVGSVGElement): string;
+/** The measured drawing size of an SVG, with the same fallbacks svgToDataUrl inlines. */
+export declare function svgNaturalSize(svg: SVGSVGElement): {
+    width: number;
+    height: number;
+};
+/**
+ * Rasterize an SVG data URL to a PNG data URL. Resolves null on any failure — decode error,
+ * deadline, tainted canvas — and never rejects.
+ */
+export declare function rasterizeSvgToPngDataUrl(svgDataUrl: string, width: number, height: number, opts?: SnapshotOptions): Promise<string | null>;
+/**
+ * Capture the first <svg> under `root` (or the element itself) as a PNG data URL, falling
+ * back to the SVG data URL when rasterizing is unavailable, and to null only when there is
+ * genuinely nothing on the canvas to capture.
+ */
+export declare function captureSvgSnapshot(root: Element | null | undefined, opts?: SnapshotOptions): Promise<string | null>;

package/package.json

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