@bicharts/chart-host 0.5.27 → 0.5.28

package/dist/index.mjs

@@ -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/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.27",
+  "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",