@bicharts/chart-host 0.6.85 → 0.6.87

package/README.md

@@ -351,6 +351,30 @@ const report = await assertViewStateConformance(service, {
 expect(report.skipped).toEqual([]);              // nothing went unchecked
 ```
 
+**A zoomed or panned view** is not in the bag: d3-zoom keeps it on the DOM node, and every redraw
+(a resize, a cross-filter, a restyle) opens the chart at full extent again. `@bicharts/chart-host/zoom-memory`
+remembers it. You supply where the view lives; the hook does the rest on every render:
+
+```ts
+import { createZoomMemoryHook, type ZoomMemoryHost } from "@bicharts/chart-host/zoom-memory";
+
+const zoomHost: ZoomMemoryHost = {
+    liveZoomState: null, zoomWatchKey: "", zoomWatchAttached: false, zoomSettleTimer: 0, zoomContainer: el,
+    rememberAcrossSessions: () => prefs.rememberZoom,             // the persisted tier is on now?
+    readPersistedZoom: () => localStorage.getItem("chart-zoom"),
+    persistZoom: json => localStorage.setItem("chart-zoom", json), // "" forgets
+    log: () => {},
+};
+const zoomMemory = createZoomMemoryHook(zoomHost);   // once per container, reused by every host on it
+const host = createChartHost(el, { code, data, d3, zoomMemory });
+```
+
+The view survives every redraw in the session whatever the preference says, and a close and reopen
+only while `rememberAcrossSessions()` is true. It is keyed by the chart's code and the viewport size
+(to the nearest 32 px), so a regenerated chart or a real resize opens at full extent instead of
+somewhere arbitrary. A chart with several zoomable panels is left alone. In React, pass the hook as
+the `zoomMemory` prop of `<BicChart>`.
+
 ## Keeping a drawn chart readable inside its frame
 
 A generated chart cannot know how wide its own legend text will come out, where its tick labels will
@@ -394,6 +418,27 @@ a throw must never fail a chart that already drew. The geometry behind each phas
 `planAxisTickThin`, `planFrameFit`, ...) is exported as plain functions over boxes, for a host that
 measures on its own terms.
 
+**Running them after every render.** `createLegendFitPass()` is both passes in the order that works
+(the legend first, then the frame fit, which measures what the legend pass left), with nothing to log
+and no policy. Hand it to the host as `layoutPass`, and the host runs it after every render, re-render
+and async settle, after the label colors are fixed and before anything measures the marks or the
+frame:
+
+```ts
+import { createChartHost } from "@bicharts/chart-host";
+import { createLegendFitPass } from "@bicharts/chart-host/legend-fit";
+
+const layoutPass = createLegendFitPass({
+    legend: true,            // or "narrow" to act only on large overlaps, or false
+    frameFit: true,
+    onReport: r => console.debug(r.legend, r.frame),   // what each run did; log what you like
+});
+const host = createChartHost(el, { code, data, d3, layoutPass });
+```
+
+In React it is the `layoutPass` prop of `<BicChart>`. Build the pass once, at module scope or in a
+`useMemo`: a new function on every render is a new host config, and the chart is rebuilt.
+
 ## Architecture — three layers, and why it matters if you contribute
 
 Read this before adding code. The package has **three** concerns, and they are independent.

package/dist/card.mjs

@@ -1,8 +1,8 @@
 /*! @bicharts/chart-host — Apache-2.0. Bundled reference data: GeoNames (https://www.geonames.org/) CC BY 4.0; Natural Earth and US Census/TIGER (public domain). Full text: NOTICE in this package. */
 import {
   computeSelectionCard
-} from "./chunk-GG4U66E4.mjs";
-import "./chunk-2ZUUIZWL.mjs";
+} from "./chunk-Z6OZDX4Z.mjs";
+import "./chunk-KQN5C7SZ.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/selectionCardChrome.ts

package/dist/{chunk-CDWNZHIN.mjs → chunk-HZNMMRQ3.mjs}

@@ -3,13 +3,6 @@ import {
   LASSO_OUTLINE_CLASS,
   installLasso
 } from "./chunk-QIRLWJBI.mjs";
-import {
-  Fn,
-  J3,
-  X,
-  Xn,
-  Yn
-} from "./chunk-2ZUUIZWL.mjs";
 import {
   censusHitBands,
   ensureCrossfilterHitTargets
@@ -33,6 +26,13 @@ import {
   fitRenderedChart,
   unpinScrolledAxis
 } from "./chunk-BQFG5HWZ.mjs";
+import {
+  Fn,
+  J3,
+  X,
+  Xn,
+  Yn
+} from "./chunk-KQN5C7SZ.mjs";
 import {
   NA_ISO3,
   NA_LAT_MAX,
@@ -2015,6 +2015,7 @@ function createChartHost(container, config) {
   const doc = container.ownerDocument;
   const win = doc?.defaultView ?? globalThis;
   const d3 = config.d3 ?? globalThis.d3 ?? win?.d3;
+  const chartD3 = writableD3(d3);
   let data = config.data;
   {
     const stamped = config.data?.meta?.hostContract;
@@ -2285,7 +2286,24 @@ function createChartHost(container, config) {
       }
     }
   };
+  const zoomMemory = config.zoomMemory ?? null;
+  let zoomCap = null;
+  let zoomKey = "";
+  const flushZoom = () => {
+    if (zoomMemory) {
+      try {
+        zoomMemory.flush();
+      } catch {
+      }
+    }
+  };
   const runPostRenderPasses = () => {
+    if (zoomMemory && zoomCap) {
+      try {
+        zoomMemory.restore(container, zoomCap, zoomKey, chartD3);
+      } catch {
+      }
+    }
     try {
       const r = scopeChartIds(container, idScope);
       if (r.collisions.length && !warnedIds) {
@@ -2312,6 +2330,12 @@ function createChartHost(container, config) {
       } catch {
       }
     }
+    if (config.layoutPass) {
+      try {
+        config.layoutPass(container);
+      } catch {
+      }
+    }
     ensureCrossfilterHitTargets(container, doc);
     paintSelection();
     try {
@@ -2398,10 +2422,11 @@ function createChartHost(container, config) {
       const seq2 = ++renderSeq;
       stopAnim();
       disposeLasso();
+      flushZoom();
       container.innerHTML = "";
       if (!renderFn) {
         if (!config.code) throw new Error("createChartHost: provide code or renderFn");
-        renderFn = compileRenderFn(config.code, win, doc, d3);
+        renderFn = compileRenderFn(config.code, win, doc, chartD3);
       }
       if (resolved.geo === void 0 && config.geoKind) {
         const g = config.geoProvider?.(config.geoKind) ?? geoFromCache(config.geoKind);
@@ -2421,8 +2446,28 @@ function createChartHost(container, config) {
       if (resolved.geoPointDest === void 0 && data.geoPointDest) resolved = { ...resolved, geoPointDest: data.geoPointDest };
       if (resolved.dateCellsAreUtcDays === void 0 && data.dateCellsAreUtcDays) resolved = { ...resolved, dateCellsAreUtcDays: true };
       let outcome;
+      zoomCap = null;
+      if (zoomMemory && config.code && !config.renderFn) {
+        try {
+          zoomKey = zoomMemory.keyFor(
+            config.code,
+            resolved.width ?? container.clientWidth,
+            resolved.height ?? container.clientHeight
+          );
+          zoomCap = zoomMemory.capture(chartD3);
+        } catch {
+          zoomCap = null;
+        }
+      }
       try {
-        outcome = renderFn(container, { columns: data.columns, rows: data.rows }, resolved);
+        try {
+          outcome = renderFn(container, { columns: data.columns, rows: data.rows }, resolved);
+        } finally {
+          try {
+            zoomCap?.release();
+          } catch {
+          }
+        }
       } catch (err) {
         const fatal = renderFailure(err);
         if (fatal) {
@@ -2537,6 +2582,7 @@ function createChartHost(container, config) {
       subs.clear();
       annotationLayer.destroy();
       unpinScrolledAxis(container);
+      flushZoom();
       container.innerHTML = "";
     }
   };

package/dist/{chunk-2ZUUIZWL.mjs → chunk-KQN5C7SZ.mjs}

@@ -841,6 +841,12 @@ var N = /[^\p{L}\p{M}\p{N}\x00-\x7F]/gu;
 function f(n) {
   return n ? String(n).normalize("NFC").replace(F2, "$1 $2").replace(S, " ").replace(N, " ").toLowerCase().split(/\s+/).filter((e) => e.length > 0) : [];
 }
+function B2(n) {
+  if (!n) return 0;
+  let e = 0xcbf29ce484222325n, t = 0x100000001b3n, r2 = e;
+  for (let o2 = 0; o2 < n.length; o2++) r2 ^= BigInt(n.charCodeAt(o2)), r2 = r2 * t & 0xFFFFFFFFFFFFFFFFn;
+  return Number(r2 & 0x1FFFFFFFFFFFFFn);
+}
 function Z(n) {
   let e = Date.parse(n);
   if (isNaN(e)) return null;
@@ -1275,6 +1281,7 @@ var Vr2 = Object.freeze(["open", "generate", "version", "rebind", "data", "sampl
 var Ae = 2 ** 31 - 1;
 
 export {
+  B2 as B,
   Z,
   g2 as g,
   X2 as X,

package/dist/{chunk-GG4U66E4.mjs → chunk-Z6OZDX4Z.mjs}

@@ -6,7 +6,7 @@ import {
   ii,
   ni,
   xt
-} from "./chunk-2ZUUIZWL.mjs";
+} from "./chunk-KQN5C7SZ.mjs";
 
 // src/sourceDateFormat.ts
 function formatSourceDate(raw, opts = {}) {

package/dist/index.mjs

@@ -5,7 +5,7 @@ import {
   formatSourceDateFor,
   isExcelDateFormat,
   normaliseAggregation
-} from "./chunk-GG4U66E4.mjs";
+} from "./chunk-Z6OZDX4Z.mjs";
 import {
   captureSvgSnapshot,
   chartSvgOf,
@@ -97,7 +97,7 @@ import {
   toRGBA,
   toSourceRows,
   valuePlacementFlag
-} from "./chunk-CDWNZHIN.mjs";
+} from "./chunk-HZNMMRQ3.mjs";
 import {
   LASSO_AXES_SLOT,
   LASSO_COUNT_CLASS,
@@ -123,11 +123,6 @@ import {
   pointInShape,
   registerLassoAction
 } from "./chunk-QIRLWJBI.mjs";
-import {
-  _3,
-  l,
-  o
-} from "./chunk-2ZUUIZWL.mjs";
 import {
   MIN_HIT_BAND_PX,
   censusHitBands,
@@ -185,6 +180,11 @@ import {
   svgInkReach,
   unpinScrolledAxis
 } from "./chunk-BQFG5HWZ.mjs";
+import {
+  _3,
+  l,
+  o
+} from "./chunk-KQN5C7SZ.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import {
   ACTIVE_TICK_CLASS,

package/dist/legend-fit.mjs

@@ -1,6 +1,7 @@
 /*! @bicharts/chart-host — Apache-2.0. Bundled reference data: GeoNames (https://www.geonames.org/) CC BY 4.0; Natural Earth and US Census/TIGER (public domain). Full text: NOTICE in this package. */
 import {
-  chartSvgOf
+  chartSvgOf,
+  tableHostOf
 } from "./chunk-ZGQURBRJ.mjs";
 import {
   FIT_CONTENT_SELECTOR,
@@ -1554,6 +1555,36 @@ function reconcileBottomTextPhase(svg) {
   }
   return { applied: true, bt: `moved${moved} dy${Math.round(maxDy)}` };
 }
+
+// src/legendFit/pass.ts
+var NARROW = { minOverlap: 16, maxGutterFraction: 0.2 };
+var errorText = (e) => String(e?.message ?? e).slice(0, 120);
+function createLegendFitPass(opts = {}) {
+  const legendOn = opts.legend ?? true;
+  const frameOn = opts.frameFit ?? true;
+  return (container) => {
+    const report = { legend: { skipped: "off" }, frame: { skipped: "off" } };
+    if (legendOn !== false) {
+      try {
+        const svg = chartSvgOf(container);
+        report.legend = svg ? reconcileLegendInSvg(svg, legendOn === "narrow" ? NARROW : {}) : { skipped: "no-svg" };
+      } catch (e) {
+        report.legend = { error: errorText(e) };
+      }
+    }
+    if (frameOn) {
+      try {
+        report.frame = tableHostOf(container) ? { skipped: "table-lane" } : fitTextToFrame(container) ?? { skipped: "nothing-to-measure" };
+      } catch (e) {
+        report.frame = { error: errorText(e) };
+      }
+    }
+    try {
+      opts.onReport?.(report);
+    } catch {
+    }
+  };
+}
 export {
   AXIS_THIN_GAP,
   AXIS_THIN_MIN_TICKS,
@@ -1583,6 +1614,7 @@ export {
   colorbarProbePoints,
   colorbarReconcileSide,
   colorbarSitsOnMarks,
+  createLegendFitPass,
   cutToFit,
   findColorbarFurniture,
   findSignatureLegendGroups,

package/dist/react.mjs

@@ -22,12 +22,12 @@ import {
   loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-CDWNZHIN.mjs";
+} from "./chunk-HZNMMRQ3.mjs";
 import "./chunk-QIRLWJBI.mjs";
-import "./chunk-2ZUUIZWL.mjs";
 import "./chunk-7HKVV5T5.mjs";
 import "./chunk-IURROJT7.mjs";
 import "./chunk-BQFG5HWZ.mjs";
+import "./chunk-KQN5C7SZ.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-MR6TL7QZ.mjs";
 import "./chunk-GHODWOAL.mjs";
@@ -67,8 +67,10 @@ function BicChart(props) {
     d3,
     geoKind,
     viewState,
+    zoomMemory,
     labelContrast,
     onLabelContrast,
+    layoutPass,
     onInvalidSentinel,
     id,
     filteredBy,
@@ -149,7 +151,9 @@ function BicChart(props) {
       d3,
       geoKind,
       viewState,
+      zoomMemory,
       labelContrast,
+      layoutPass,
       onLabelContrast: (r) => onLabelContrastRef.current?.(r),
       // A GETTER, not a wrapper: the host decides whether to
       // swallow the sentinel throw by whether this is SET, so
@@ -181,7 +185,7 @@ function BicChart(props) {
       host.destroy();
       hostRef.current = null;
     };
-  }, [code, renderFn, d3, geoKind, labelContrast, controls]);
+  }, [code, renderFn, d3, geoKind, labelContrast, layoutPass, controls]);
   useLayoutEffect(() => {
     const host = hostRef.current;
     if (!host || !selects) return;
@@ -207,7 +211,7 @@ function BicChart(props) {
       b.detach();
       if (bindingRef.current === b) bindingRef.current = null;
     };
-  }, [selects, code, renderFn, d3, geoKind, labelContrast]);
+  }, [selects, code, renderFn, d3, geoKind, labelContrast, layoutPass]);
   useEffect(() => {
     if (!hostRef.current || !options) return;
     if (builtWithRef.current?.optKey === optKey) return;

package/dist/types/host.d.ts

@@ -18,6 +18,7 @@ import { type FitRenderedChartOptions, type FitRenderedChartResult } from "./fit
 import { type LabelContrastOptions, type LabelContrastReport } from "./labelContrastDom";
 import { type IdScopeReport } from "./idScope";
 import { type MarkAnnotation, type AnnotationReport } from "./annotations";
+import type { ZoomMemoryHook } from "./zoomMemory/zoomMemoryDom";
 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.
@@ -73,6 +74,14 @@ export interface ChartHostConfig {
      *  session store parked on the container — the behaviour every host had before 1.6.0.
      *  A raw `options.setUiState` still wins over this, so an existing caller is untouched. */
     viewState?: ViewStateProvider;
+    /**
+     * REMEMBER THE READER'S ZOOM AND PAN on a chart that calls d3.zoom(), across every re-render (and across a
+     * close and reopen, if the host's store says so). Build it with createZoomMemoryHook() from
+     * "@bicharts/chart-host/zoom-memory", ONCE per container, and hand the same hook to every host created on
+     * that container. Absent (the default), d3.zoom is never wrapped and nothing is listened for. It applies to a
+     * chart compiled from `code` only: a precompiled `renderFn` closed over its own d3.
+     */
+    zoomMemory?: ZoomMemoryHook | null;
     /** D3 v7 instance handed to the compiled code. Default: (globalThis as any).d3. */
     d3?: any;
     /** Attach geometry for this geoKind as options.geo (choropleths / basemaps). Resolved
@@ -190,6 +199,15 @@ export interface ChartHostConfig {
     labelContrast?: boolean | LabelContrastOptions;
     /** What the label-contrast pass did after each render - counts, so a host can log them. */
     onLabelContrast?: (report: LabelContrastReport) => void;
+    /**
+     * A LAYOUT PASS the host brings, run after every render (both the synchronous and the promise lane, and every
+     * setOptions / setData re-render) AFTER the label-contrast pass and BEFORE the hit-target heal, the selection
+     * repaint, the censuses and the fit - the order a pass that moves the legend or grows the viewBox needs, because
+     * the fit must measure the final layout. Absent by default: the main entry carries no such pass. Build one with
+     * createLegendFitPass() from "@bicharts/chart-host/legend-fit". It must not throw (a throw is swallowed and the
+     * render stands); it reports through its own callback, never through this host.
+     */
+    layoutPass?: (container: HTMLElement) => void;
     /**
      * What the id-scoping pass did after each render: how many of the chart's ids got this host's suffix, and which
      * of them also existed elsewhere in the page (a clash it prevented - two same-size charts naming one clip path).

package/dist/types/legendFit/index.d.ts

@@ -2,3 +2,4 @@ export { MIN_OVERLAP, MAX_GUTTER_FRACTION, COLORBAR_ON_PLOT_COVER, MAX_FIT_FRACT
 export { FRAME_PAD, MAX_EXTEND_FRACTION, FIT_TYPE_FLOOR, FIT_SHRINK_FLOOR, planFrameFit, viewBoxAttr, labelRoom, labelFitDecision, cutToFit, type FrameFitPlan, type TextAnchor, type LabelFitDecision, } from "./frameFit";
 export { reconcileLegendInSvg, findSignatureLegendGroups, findColorbarFurniture, smallestRenderedTextPx, styleDeclaresScroll, type LegendReconcileResult, type AxisThinReport, } from "./legendReconcileDom";
 export { FRAME_FIT_TEXT_CAP, fitTextToFrame, fitDeferredLabels, fitLabelToRoom, isClippedOrScrolled, type FrameFitOutcome, type DeferredLabelFitReport, } from "./frameFitDom";
+export { createLegendFitPass, type LegendFitPassOptions, type LegendFitReport, type LegendFitStrictness } from "./pass";

package/dist/types/legendFit/pass.d.ts

@@ -0,0 +1,29 @@
+import { type LegendReconcileResult } from "./legendReconcileDom";
+import { type FrameFitOutcome } from "./frameFitDom";
+/** "smart" acts on smaller overlaps with larger moves; "narrow" only on large, unambiguous ones. */
+export type LegendFitStrictness = "smart" | "narrow";
+export interface LegendFitPassOptions {
+    /** Run the legend reconcile (legend slide, colorbar, axis and label-row thinning, bottom-text push, content fit). Default true. */
+    legend?: boolean | LegendFitStrictness;
+    /** Run the frame fit (viewBox growth for text just past the frame, then shrink-and-cut of the labels it deferred). Default true. */
+    frameFit?: boolean;
+    /** What each run did. Counts and reasons only; the host decides what to log. */
+    onReport?: (report: LegendFitReport) => void;
+}
+export interface LegendFitReport {
+    legend: LegendReconcileResult | {
+        skipped: "off" | "no-svg";
+    } | {
+        error: string;
+    };
+    frame: FrameFitOutcome | {
+        skipped: "off" | "table-lane" | "nothing-to-measure";
+    } | {
+        error: string;
+    };
+}
+/**
+ * Build the pass once (module scope, or a memo) and hand it to createChartHost as `layoutPass`: a new function
+ * on every render is a new host config. Each run never throws; a pass that fails reports `{ error }`.
+ */
+export declare function createLegendFitPass(opts?: LegendFitPassOptions): (container: HTMLElement) => void;

package/dist/types/react.d.ts

@@ -32,6 +32,13 @@ export interface BicChartProps {
      * default could pick between them, which is why this is a prop rather than a flag.
      */
     viewState?: ChartHostConfig["viewState"];
+    /**
+     * REMEMBER THE READER'S ZOOM AND PAN on a chart that calls d3.zoom(), across re-renders and, if
+     * the hook's store keeps it, across a reload. Build it with createZoomMemoryHook() from
+     * "@bicharts/chart-host/zoom-memory", once per chart (module scope or useMemo) with somewhere to
+     * keep the view. Absent, nothing is remembered. See createChartHost's `zoomMemory`.
+     */
+    zoomMemory?: ChartHostConfig["zoomMemory"];
     /**
      * CAN THE LABELS ON THE MARKS BE READ? Default on: after every render a label sitting on a
      * mark it cannot be read against is recoloured black or white. Pass `false` for a page that
@@ -41,6 +48,13 @@ export interface BicChartProps {
     labelContrast?: ChartHostConfig["labelContrast"];
     /** What the label-contrast pass did after each render - counts, for a page that logs. */
     onLabelContrast?: ChartHostConfig["onLabelContrast"];
+    /**
+     * A LAYOUT PASS run after every render, after label contrast and before the fit - e.g.
+     * `createLegendFitPass()` from "@bicharts/chart-host/legend-fit", which slides a legend clear of
+     * the plot and fits text to the frame. Absent by default. Build it ONCE (module scope or useMemo):
+     * a new function each render rebuilds the host. See createChartHost's `layoutPass`.
+     */
+    layoutPass?: ChartHostConfig["layoutPass"];
     /**
      * THE CHART STOPPED BECAUSE THE DATA LACKS A COLUMN IT IS BUILT ON. Supplied: the chart's
      * container is left empty and this is called with the chart's reason, instead of the throw

package/dist/types/zoomMemory/index.d.ts

@@ -0,0 +1,2 @@
+export { zoomStateKey, viewportBucket, isUsableTransform, isIdentity, transformsDiffer, serializeZoomState, parseZoomState, isZoomStateUsable, readNodeTransform, findZoomedNodes, soleZoomedNode, type ZoomTransform, type ZoomState, } from "./zoomMemory";
+export { captureZoomBehaviors, restoreZoomForRender, attachZoomWatcher, captureCurrentZoom, flushPendingZoom, forgetZoom, createZoomMemoryHook, type ZoomMemoryHost, type ZoomCapture, type ZoomMemoryHook, } from "./zoomMemoryDom";

package/dist/types/zoomMemory/zoomMemory.d.ts

@@ -0,0 +1,59 @@
+/** A d3-zoom transform, reduced to the three numbers that define it. */
+export interface ZoomTransform {
+    k: number;
+    x: number;
+    y: number;
+}
+/** What gets persisted: the transform plus what it was captured against. */
+export interface ZoomState extends ZoomTransform {
+    /** Identity of the chart + viewport this transform is meaningful for. */
+    key: string;
+}
+/** Identity is not identity across a resize (see viewportBucket) or a regeneration. */
+export declare function zoomStateKey(codeHash: string | number, width: number, height: number): string;
+/** Round a dimension so ordinary 1-2px reflow jitter does not discard a good transform,
+ *  while a real resize (which changes the fitted frame the transform was chosen against)
+ *  does. 32px is a bucket the reader cannot hit by accident and cannot miss on purpose. */
+export declare function viewportBucket(px: number): number;
+/** A transform we are willing to APPLY.
+ *
+ *  A PERSISTED TRANSFORM IS UNTRUSTED: it round-trips through a saved file that a person can hand-edit,
+ *  and it was captured against a geometry that may no longer exist. The floor here is only "these are
+ *  three real numbers and the scale is not nonsense".
+ *
+ *  NOTE ON WHO CLAMPS. `zoom.transform` does NOT constrain - d3-zoom applies `constrain()` in its
+ *  wheel/drag/touch handlers and then assigns the result, but the programmatic `zoom.transform` path sets
+ *  `__zoom` to exactly what it is given. So the host must clamp before applying, and it does it with the
+ *  BEHAVIOR'S OWN accessors (scaleExtent(), extent(), translateExtent(), constrain()) rather than
+ *  re-deriving the limits here - see constrainToBehavior in zoomMemoryDom.ts. That keeps one source of
+ *  truth: the chart that built the zoom owns what a legal view is, and the host only asks it. */
+export declare function isUsableTransform(t: unknown): t is ZoomTransform;
+/** k=1 with no offset is the identity - the state a chart is already in after a fresh
+ *  render. Storing or restoring it is pure noise, and persisting it would write to the
+ *  saved file every time somebody zoomed out again. */
+export declare function isIdentity(t: ZoomTransform): boolean;
+/** Sub-pixel differences are re-render noise, not the reader's intent. Without this, restoring a
+ *  transform would itself look like a change and write straight back - a persist loop. */
+export declare function transformsDiffer(a: ZoomTransform | null, b: ZoomTransform | null): boolean;
+export declare function serializeZoomState(t: ZoomTransform, key: string): string;
+/** Never throws. A blob that will not parse is treated as absent, which is the same
+ *  outcome as never having saved one. */
+export declare function parseZoomState(raw: string | null | undefined): ZoomState | null;
+/** A remembered transform is only meaningful for the chart + viewport that produced it.
+ *  A regeneration changes the code hash; a real resize changes the viewport bucket. Either
+ *  way the old transform describes a frame that no longer exists, and the honest thing is
+ *  to open at identity rather than somewhere arbitrary. */
+export declare function isZoomStateUsable(state: ZoomState | null, currentKey: string): boolean;
+/** Read d3-zoom's stored transform off a node, defensively.
+ *  `node.__zoom` is a d3 ZoomTransform instance; only its three numbers are wanted. */
+export declare function readNodeTransform(node: any): ZoomTransform | null;
+/** Every element under `root` (inclusive) that d3-zoom has attached to.
+ *
+ *  Nearly always exactly one - the map's pan-catcher rect or the SVG itself. More than one
+ *  means a composite chart with independently zoomable panels; those are deliberately NOT
+ *  remembered, because pairing several transforms to several panels across a re-render
+ *  needs an identity there is none of, and restoring them to the WRONG panels would be worse
+ *  than not restoring at all. */
+export declare function findZoomedNodes(root: Element | null): Element[];
+/** The single zoomed node worth remembering, or null. See findZoomedNodes on why >1 opts out. */
+export declare function soleZoomedNode(root: Element | null): Element | null;

package/dist/types/zoomMemory/zoomMemoryDom.d.ts

@@ -0,0 +1,74 @@
+import { type ZoomState } from "./zoomMemory";
+/**
+ * WHAT A HOST SUPPLIES: where the remembered view lives, and whether it may outlive the session.
+ * One per chart container, kept for as long as the container is, so it outlives a host that is destroyed
+ * and re-created on the same element (a redraw on every resize, say).
+ */
+export interface ZoomMemoryHost {
+    /** The in-session tier, always on: survives every re-render, never written anywhere. */
+    liveZoomState: ZoomState | null;
+    /** The key the watcher stamps on what it records (the latest render's). */
+    zoomWatchKey: string;
+    /** Whether the watcher's listeners are on zoomContainer (they attach once). */
+    zoomWatchAttached: boolean;
+    /** The pending settle timer, 0 when none. */
+    zoomSettleTimer: number;
+    /** The element the chart draws into; it outlives each render, so listeners attach to it once. Null until
+     *  known: createZoomMemoryHook's restore adopts the render's container then. */
+    zoomContainer: Element | null;
+    /** Is the persisted tier on NOW? Read on every restore and every write, so a change applies to the next. */
+    rememberAcrossSessions(): boolean;
+    /** The persisted blob, or null. Read only while rememberAcrossSessions() is true; `key` is the current
+     *  render's, for a host that wants to say why a saved view did not apply. */
+    readPersistedZoom(key: string): string | null;
+    /** Write the persisted blob; "" forgets it. Called only while rememberAcrossSessions() is true. */
+    persistZoom(json: string): void;
+    /** Diagnostics: a tag and a small payload. Never transform data beyond the three numbers and the key. */
+    log(tag: string, data?: Record<string, unknown>): void;
+}
+/** What captureZoomBehaviors hands back: the behaviors the chart created, and the unwrap. */
+export interface ZoomCapture {
+    behaviors: any[];
+    release: () => void;
+}
+/** Wrap `d3.zoom` so every behavior the generated code creates is recorded.
+ *
+ *  This works BECAUSE d3's chainable setters mutate and return the same object:
+ *  `d3.zoom().scaleExtent([1,8]).translateExtent(...)` hands back the very object captured, so the
+ *  reference stays live no matter how the chart configures it. (Wrapping the returned object instead
+ *  would NOT work - the first chained call would unwrap it.) */
+export declare function captureZoomBehaviors(d3: any, host: ZoomMemoryHost): ZoomCapture;
+/** Put the remembered view back. Called synchronously after render() returned and before the browser
+ *  paints - which is what makes this a restore rather than a visible jump - and before any pass that
+ *  measures the chart, so they measure the view the reader will see. */
+export declare function restoreZoomForRender(d3: any, host: ZoomMemoryHost, capture: ZoomCapture, key: string): void;
+/** Record the transform after interaction settles.
+ *
+ *  Listeners are attached ONCE to the container (which outlives individual renders) and read the key
+ *  from the host object, so a re-render does not stack another set. Capture phase, because the chart's
+ *  own handlers may stop propagation. */
+export declare function attachZoomWatcher(host: ZoomMemoryHost, key: string): void;
+/** Read the live transform off the DOM and remember it. */
+export declare function captureCurrentZoom(host: ZoomMemoryHost): void;
+/** A gesture that has not settled yet is recorded NOW. Call it before the chart's DOM goes away (a
+ *  redraw, a teardown): the pending timer would otherwise fire over an empty container and lose it. */
+export declare function flushPendingZoom(host: ZoomMemoryHost): void;
+/** Drop the session view and any pending gesture, and persist nothing - for a host that swaps in a
+ *  different chart, where a timer armed on the old one must not write after the swap. */
+export declare function forgetZoom(host: ZoomMemoryHost): void;
+/** WHAT createChartHost TAKES as `zoomMemory`: the functions above bound to one ZoomMemoryHost. */
+export interface ZoomMemoryHook {
+    /** The key a render's view is remembered under: the code's hash and the viewport's 32px bucket. */
+    keyFor(code: string, width: number, height: number): string;
+    /** Wrap d3.zoom on the d3 the chart is handed, for the duration of its run. */
+    capture(d3: any): ZoomCapture;
+    /** Put the remembered view back, then attach the watcher (once) under this render's key. */
+    restore(container: Element, capture: ZoomCapture, key: string, d3: any): void;
+    /** flushPendingZoom: record a gesture still settling. */
+    flush(): void;
+    /** forgetZoom: drop the session view and a pending gesture. */
+    forget(): void;
+}
+/** Bind the zoom memory to one host object. Build it once per container and hand the same hook to every
+ *  host created on that container, so the session tier outlives each one. */
+export declare function createZoomMemoryHook(host: ZoomMemoryHost): ZoomMemoryHook;

package/dist/zoom-memory.mjs

@@ -0,0 +1,276 @@
+/*! @bicharts/chart-host — Apache-2.0. Bundled reference data: GeoNames (https://www.geonames.org/) CC BY 4.0; Natural Earth and US Census/TIGER (public domain). Full text: NOTICE in this package. */
+import {
+  B
+} from "./chunk-KQN5C7SZ.mjs";
+import "./chunk-GHODWOAL.mjs";
+
+// src/zoomMemory/zoomMemory.ts
+function zoomStateKey(codeHash, width, height) {
+  return `${codeHash}:${viewportBucket(width)}x${viewportBucket(height)}`;
+}
+function viewportBucket(px) {
+  if (!isFiniteNumber(px) || px <= 0) return 0;
+  return Math.round(px / 32);
+}
+function isFiniteNumber(v) {
+  return typeof v === "number" && isFinite(v);
+}
+function isUsableTransform(t) {
+  if (!t || typeof t !== "object") return false;
+  const c = t;
+  if (!isFiniteNumber(c.k) || !isFiniteNumber(c.x) || !isFiniteNumber(c.y)) return false;
+  if (c.k <= 0 || c.k > 1e6) return false;
+  if (Math.abs(c.x) > 1e7 || Math.abs(c.y) > 1e7) return false;
+  return true;
+}
+function isIdentity(t) {
+  return t.k === 1 && t.x === 0 && t.y === 0;
+}
+function transformsDiffer(a, b) {
+  if (!a || !b) return a !== b;
+  return Math.abs(a.k - b.k) > 1e-6 || Math.abs(a.x - b.x) > 0.5 || Math.abs(a.y - b.y) > 0.5;
+}
+function serializeZoomState(t, key) {
+  return JSON.stringify({
+    k: Math.round(t.k * 1e4) / 1e4,
+    x: Math.round(t.x * 100) / 100,
+    y: Math.round(t.y * 100) / 100,
+    key
+  });
+}
+function parseZoomState(raw) {
+  if (!raw || typeof raw !== "string") return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isUsableTransform(parsed)) return null;
+  const key = typeof parsed.key === "string" ? parsed.key : "";
+  if (!key) return null;
+  return { k: parsed.k, x: parsed.x, y: parsed.y, key };
+}
+function isZoomStateUsable(state, currentKey) {
+  return !!state && !!currentKey && state.key === currentKey && isUsableTransform(state);
+}
+function readNodeTransform(node) {
+  if (!node) return null;
+  const z = node.__zoom;
+  if (!z) return null;
+  const t = { k: z.k, x: z.x, y: z.y };
+  return isUsableTransform(t) ? t : null;
+}
+function findZoomedNodes(root) {
+  if (!root) return [];
+  const out = [];
+  if (root.__zoom) out.push(root);
+  let all;
+  try {
+    all = root.querySelectorAll("*");
+  } catch {
+    return out;
+  }
+  for (let i = 0; i < all.length; i++) {
+    if (all[i].__zoom) out.push(all[i]);
+  }
+  return out;
+}
+function soleZoomedNode(root) {
+  const nodes = findZoomedNodes(root);
+  return nodes.length === 1 ? nodes[0] : null;
+}
+
+// src/zoomMemory/zoomMemoryDom.ts
+var SETTLE_MS = 350;
+function captureZoomBehaviors(d3, host) {
+  const noop = { behaviors: [], release: () => void 0 };
+  if (!d3 || typeof d3.zoom !== "function") return noop;
+  const behaviors = [];
+  const original = d3.zoom;
+  try {
+    const wrapped = function(...args) {
+      const b = original.apply(this, args);
+      try {
+        if (b) behaviors.push(b);
+      } catch {
+      }
+      return b;
+    };
+    try {
+      for (const k of Object.keys(original)) wrapped[k] = original[k];
+    } catch {
+    }
+    d3.zoom = wrapped;
+  } catch (e) {
+    host.log("zoom-capture-wrap-failed", { message: e instanceof Error ? e.message : String(e) });
+    return noop;
+  }
+  return {
+    behaviors,
+    release: () => {
+      try {
+        d3.zoom = original;
+      } catch {
+      }
+    }
+  };
+}
+function constrainToBehavior(d3, behavior, node, t) {
+  let out = d3.zoomIdentity.translate(t.x, t.y).scale(t.k);
+  try {
+    const scaleExtent = typeof behavior.scaleExtent === "function" ? behavior.scaleExtent() : null;
+    if (scaleExtent && scaleExtent.length === 2) {
+      const k = Math.max(scaleExtent[0], Math.min(scaleExtent[1], t.k));
+      out = d3.zoomIdentity.translate(t.x, t.y).scale(k);
+    }
+  } catch {
+  }
+  try {
+    const constrain = typeof behavior.constrain === "function" ? behavior.constrain() : null;
+    const extentFn = typeof behavior.extent === "function" ? behavior.extent() : null;
+    const translateExtent = typeof behavior.translateExtent === "function" ? behavior.translateExtent() : null;
+    if (typeof constrain === "function" && translateExtent) {
+      const extent = typeof extentFn === "function" ? extentFn.apply(node, [node && node.__data__]) : extentFn;
+      if (extent) out = constrain(out, extent, translateExtent);
+    }
+  } catch {
+  }
+  return out;
+}
+function rememberedFor(host, key) {
+  if (isZoomStateUsable(host.liveZoomState, key)) return host.liveZoomState;
+  if (!rememberAcrossSessions(host)) return null;
+  let raw = null;
+  try {
+    raw = host.readPersistedZoom(key);
+  } catch {
+    raw = null;
+  }
+  const persisted = parseZoomState(raw);
+  return isZoomStateUsable(persisted, key) ? persisted : null;
+}
+function rememberAcrossSessions(host) {
+  try {
+    return !!host.rememberAcrossSessions();
+  } catch {
+    return false;
+  }
+}
+function restoreZoomForRender(d3, host, capture, key) {
+  try {
+    const state = rememberedFor(host, key);
+    if (!state) return;
+    const node = soleZoomedNode(host.zoomContainer);
+    if (!node) return;
+    const current = readNodeTransform(node);
+    if (current && !transformsDiffer(current, state)) return;
+    const behavior = capture.behaviors.length === 1 ? capture.behaviors[0] : null;
+    if (!behavior || typeof behavior.transform !== "function") {
+      host.log("zoom-restore-no-behavior", { behaviors: capture.behaviors.length });
+      return;
+    }
+    if (!d3 || !d3.zoomIdentity || typeof d3.select !== "function") return;
+    const t = constrainToBehavior(d3, behavior, node, state);
+    d3.select(node).call(behavior.transform, t);
+    host.log("zoom-restored", { k: round(t.k), x: round(t.x), y: round(t.y), key });
+  } catch (e) {
+    host.log("zoom-restore-ex", { message: e instanceof Error ? e.message : String(e) });
+  }
+}
+function round(n) {
+  return Math.round(n * 100) / 100;
+}
+function attachZoomWatcher(host, key) {
+  host.zoomWatchKey = key;
+  const ctr = host.zoomContainer;
+  if (host.zoomWatchAttached || !ctr) return;
+  const settle = () => {
+    if (host.zoomSettleTimer) clearTimeout(host.zoomSettleTimer);
+    host.zoomSettleTimer = setTimeout(() => {
+      host.zoomSettleTimer = 0;
+      captureCurrentZoom(host);
+    }, SETTLE_MS);
+  };
+  for (const evt of ["wheel", "pointerup", "pointercancel", "click", "dblclick", "keyup"]) {
+    try {
+      ctr.addEventListener(evt, settle, true);
+    } catch {
+    }
+  }
+  host.zoomWatchAttached = true;
+  host.log("zoom-watcher-attached", {});
+}
+function captureCurrentZoom(host) {
+  try {
+    const key = host.zoomWatchKey;
+    if (!key) return;
+    const node = soleZoomedNode(host.zoomContainer);
+    if (!node) return;
+    const t = readNodeTransform(node);
+    if (!t) return;
+    if (isIdentity(t)) {
+      if (host.liveZoomState) {
+        host.liveZoomState = null;
+        persist(host, "");
+        host.log("zoom-forgotten", { key });
+      }
+      return;
+    }
+    const previous = host.liveZoomState;
+    if (previous && previous.key === key && !transformsDiffer(previous, t)) return;
+    host.liveZoomState = { k: t.k, x: t.x, y: t.y, key };
+    persist(host, serializeZoomState(t, key));
+    host.log("zoom-remembered", { k: round(t.k), x: round(t.x), y: round(t.y), key });
+  } catch (e) {
+    host.log("zoom-capture-ex", { message: e instanceof Error ? e.message : String(e) });
+  }
+}
+function persist(host, json) {
+  if (!rememberAcrossSessions(host)) return;
+  host.persistZoom(json);
+}
+function flushPendingZoom(host) {
+  if (!host.zoomSettleTimer) return;
+  clearTimeout(host.zoomSettleTimer);
+  host.zoomSettleTimer = 0;
+  captureCurrentZoom(host);
+}
+function forgetZoom(host) {
+  if (host.zoomSettleTimer) clearTimeout(host.zoomSettleTimer);
+  host.zoomSettleTimer = 0;
+  host.liveZoomState = null;
+}
+function createZoomMemoryHook(host) {
+  return {
+    keyFor: (code, width, height) => zoomStateKey(B(String(code ?? "")), width, height),
+    capture: (d3) => captureZoomBehaviors(d3, host),
+    restore: (container, capture, key, d3) => {
+      if (!host.zoomContainer) host.zoomContainer = container;
+      restoreZoomForRender(d3, host, capture, key);
+      attachZoomWatcher(host, key);
+    },
+    flush: () => flushPendingZoom(host),
+    forget: () => forgetZoom(host)
+  };
+}
+export {
+  attachZoomWatcher,
+  captureCurrentZoom,
+  captureZoomBehaviors,
+  createZoomMemoryHook,
+  findZoomedNodes,
+  flushPendingZoom,
+  forgetZoom,
+  isIdentity,
+  isUsableTransform,
+  isZoomStateUsable,
+  parseZoomState,
+  readNodeTransform,
+  restoreZoomForRender,
+  serializeZoomState,
+  soleZoomedNode,
+  transformsDiffer,
+  viewportBucket,
+  zoomStateKey
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.6.85",
+  "version": "0.6.87",
   "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",
@@ -64,6 +64,11 @@
       "import": "./dist/legend-fit.mjs",
       "default": "./dist/legend-fit.mjs"
     },
+    "./zoom-memory": {
+      "types": "./dist/types/zoomMemory/index.d.ts",
+      "import": "./dist/zoom-memory.mjs",
+      "default": "./dist/zoom-memory.mjs"
+    },
     "./dax": {
       "types": "./dist/types/dax.d.ts",
       "import": "./dist/dax.mjs",