@bicharts/chart-host 0.6.86 → 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

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-MXL5SK7X.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) {
@@ -2404,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);
@@ -2427,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) {
@@ -2543,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-MXL5SK7X.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/react.mjs

@@ -22,12 +22,12 @@ import {
   loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-MXL5SK7X.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,6 +67,7 @@ function BicChart(props) {
     d3,
     geoKind,
     viewState,
+    zoomMemory,
     labelContrast,
     onLabelContrast,
     layoutPass,
@@ -150,6 +151,7 @@ function BicChart(props) {
       d3,
       geoKind,
       viewState,
+      zoomMemory,
       labelContrast,
       layoutPass,
       onLabelContrast: (r) => onLabelContrastRef.current?.(r),

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

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

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.86",
+  "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",