@bicharts/chart-host 0.6.81 → 0.6.83

package/README.md

@@ -278,6 +278,79 @@ made for: every word shares a comment with many others, so the default lit most
 click. The cross-filter sent out is the same under both rules. `onSelectionPaint` reports how each
 paint of a declaring chart decided, including when no mark matched and the default was used.
 
+## Remembering what the reader did
+
+A chart keeps its resting state (a sort, an expanded row, a 3D camera angle) in a small bag. It
+reads the bag from `options.uiState` and writes it through `options.setUiState`, and generated code
+never learns where the bag goes. Where it goes is your host's choice, and so is which keys may
+outlive what: a redraw, a close and reopen, or a new version of the chart.
+
+`createChartHost` still takes one `viewState` provider, as before. When your host needs more than
+one store, describe it with a `ViewStateService`:
+
+```ts
+import { sessionViewStateProvider, type ViewStateService } from "@bicharts/chart-host";
+
+const viewState: ViewStateService = {
+    viewing: sessionViewStateProvider(el),   // survives a redraw; a page switch starts clean
+    durable: workbookStore,                  // optional: survives close and reopen
+    policy: {                                // the keys your host scopes, by name
+        camera: { lifetime: "durable", dropOnNewVersion: true, dropOnFreshViewing: false, durableWhen: "rememberView" },
+        userStopped: { lifetime: "durable", dropOnNewVersion: false, dropOnFreshViewing: true },
+    },
+    versionKey: "cameraVersion",             // optional: how a version change is noticed
+};
+```
+
+**What you provide.** `viewing` and `policy` are required (`policy: {}` is fine). Everything else is
+optional, and leaving it out says something about your host:
+
+- no `durable` store: the host can't remember across a close (a static preview, a server-side
+  render). `viewStateIsDurable(service)` is the one definition of "remembers the view", so it can't
+  be claimed without a store to back it. `noopViewStateService()` says "nothing is stored" out loud.
+- no `chartKeys`: keys your policy doesn't name belong to the chart. They're kept, durably, through a
+  new version and a fresh viewing, and the chart validates what it reads. Set `chartKeys` to give
+  them another rule. A host that forgets everything when its chart changes sets `dropOnNewVersion`.
+- no `versionKey`: you apply the version rule yourself, where you learn the chart changed.
+- no `durableMaxChars`: the durable store accepts any size.
+
+**What a key can be.** `lifetime: "viewing"` keeps a key out of the durable store; `"durable"` puts it
+in both. `dropOnNewVersion` drops it when the chart on screen is another version (a camera is aimed
+at one chart's axes). `dropOnFreshViewing` drops it when the bag is read at the start of a viewing
+instead of in the one that wrote it. `durableWhen` names a preference that must be on for the key to
+reach the durable store; the viewing store keeps it either way.
+
+**The rules are plain functions** in `@bicharts/chart-host/view-state`, with no DOM, timers or
+storage of their own:
+
+```ts
+import { resolveViewState, commitViewState } from "@bicharts/chart-host/view-state";
+
+const { bag, dropped } = resolveViewState(viewState, { codeVersion, freshViewing });   // before a render
+commitViewState(next, viewState, prefs);                                               // when the chart writes
+```
+
+`resolveViewState` builds the bag the chart is handed: the viewing store, else the durable one, with
+the policy applied. `commitViewState` decides what a write reaches: the viewing store gets all of
+it, the durable store gets what the policy allows. Both report what they did and neither throws.
+`viewStateAfterSwap(service, bag)` applies the version rule for a host that sees the swap itself.
+
+**Check your stores** with the conformance suite in the testing subpath. It confirms `load` never
+throws and reads `{}` when empty, that `save` replaces, that nested values round-trip, that the
+viewing store survives your host being re-created on the same element, and that the durable store
+holds what it's given across a reopen:
+
+```ts
+import { assertViewStateConformance } from "@bicharts/chart-host/testing";
+
+const report = await assertViewStateConformance(service, {
+    recreate: () => buildService(sameElement),   // the host drawing again
+    reopen: () => buildService(newElement),      // a new viewing over the same saved file
+    settle: () => flushPendingWrites(),          // only if your durable save is debounced
+});
+expect(report.skipped).toEqual([]);              // nothing went unchecked
+```
+
 ## 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-7HPVGRQ2.mjs";
-import "./chunk-ZRSEKV4I.mjs";
+} from "./chunk-4KCSAHL5.mjs";
+import "./chunk-2XWE6YFO.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/selectionCardChrome.ts

package/dist/{chunk-ZRSEKV4I.mjs → chunk-2XWE6YFO.mjs}

@@ -1140,7 +1140,7 @@ function F3(e) {
 function N2(e) {
   let t = F3(e);
   if (t.length === 0 || ne2(e) < 95) return false;
-  let n = t.filter((l2) => te(l2) && !t3(l2)).length, o2 = t.filter((l2) => !te(l2) && !!t3(l2)).length;
+  let n = t.filter((u4) => te(u4) && !t3(u4)).length, o2 = t.filter((u4) => !te(u4) && !!t3(u4)).length;
   return n >= 1 && n >= o2;
 }
 function ce(e, t) {
@@ -1185,7 +1185,7 @@ function Yn2(e, t) {
   let n = F3(e);
   if (n.length === 0) return 0;
   let o2 = 0;
-  for (let l2 of n) j3(l2, t) && o2++;
+  for (let u4 of n) j3(u4, t) && o2++;
   return Math.round(o2 / n.length * 1e3) / 10;
 }
 function ee(e, t) {
@@ -1198,13 +1198,13 @@ function Qn(e, t) {
   for (let o2 of oe(e)) t(o2) && n++;
   return n;
 }
-function Xn(e, t, n, o2, l2) {
-  let u4 = [], a3 = [], i = {}, h4 = {}, C = new Set(e), y2 = (s2) => t.map((d2) => d2[s2]);
+function Xn(e, t, n, o2, u4) {
+  let l2 = [], a3 = [], i = {}, h4 = {}, C = new Set(e), y2 = (s2) => t.map((d2) => d2[s2]);
   for (let s2 of ["city", "country"]) {
     let d2 = n?.[s2];
     d2 && C.has(d2) && (i[s2] = d2);
   }
-  let g5 = new Set(l2 ?? e);
+  let g5 = new Set(u4 ?? e);
   for (let s2 of ["lat", "lon"]) {
     let d2 = n?.[s2];
     d2 && g5.has(d2) && (i[s2] = d2);
@@ -1230,13 +1230,13 @@ function Xn(e, t, n, o2, l2) {
       let K3 = ee(S2, (G4) => !!t3(G4)), Ne2 = ee(S2, (G4) => !!t3(G4) && !ce(G4, o2));
       K3 < Z2 && Ne2 < 1 || (!s2 || O4 > s2.pct) && (s2 = { name: d2, pct: O4 });
     }
-    s2 && (i.state = s2.name, p4.add(s2.name), u4.push(`state=${s2.name} (${s2.pct}% states/provinces)`));
+    s2 && (i.state = s2.name, p4.add(s2.name), l2.push(`state=${s2.name} (${s2.pct}% states/provinces)`));
   }
   if (!i.zip) for (let s2 of b4) {
     if (p4.has(s2)) continue;
     let d2 = y2(s2), S2 = re2(d2);
     if (!(S2 < 95) && de(d2, s2) && !(Qn(d2, (O4) => r3(O4).length > 0) < Z2)) {
-      i.zip = s2, p4.add(s2), u4.push(`zip=${s2} (${S2}% ZIP codes)`);
+      i.zip = s2, p4.add(s2), l2.push(`zip=${s2} (${S2}% ZIP codes)`);
       break;
     }
   }
@@ -1248,7 +1248,7 @@ function Xn(e, t, n, o2, l2) {
       let S2 = ne2(y2(d2));
       (!s2 || S2 > s2.pct) && (s2 = { name: d2, pct: S2 });
     }
-    s2 && (T2 && (a3.push(`country=${T2} (only ${ne2(y2(T2))}% of values are country identifiers; using ${s2.name} instead)`), h4.country = T2), i.country = s2.name, p4.add(s2.name), u4.push(`country=${s2.name}`));
+    s2 && (T2 && (a3.push(`country=${T2} (only ${ne2(y2(T2))}% of values are country identifiers; using ${s2.name} instead)`), h4.country = T2), i.country = s2.name, p4.add(s2.name), l2.push(`country=${s2.name}`));
   }
   if (!i.city) {
     let s2 = null;
@@ -1257,13 +1257,13 @@ function Xn(e, t, n, o2, l2) {
       let S2 = y2(d2), O4 = Yn2(S2, o2);
       O4 < D3 || ee(S2, (K3) => j3(K3, o2)) < Z2 || (!s2 || O4 > s2.pct) && (s2 = { name: d2, pct: O4 });
     }
-    s2 && (i.city = s2.name, u4.push(`city=${s2.name} (${s2.pct}% known cities)`));
+    s2 && (i.city = s2.name, l2.push(`city=${s2.name} (${s2.pct}% known cities)`));
   }
   let L4 = i.country ? y2(i.country) : [], R4 = !!i.country && N2(L4), A = R4 ? new Set(L4.map((s2) => k(s2 == null ? null : String(s2))).filter(Boolean)).size : 0, x3 = R4 && A >= 2, w4 = !!(i.lat && i.lon) && t.some((s2) => {
     let d2 = +String(s2[i.lat] ?? "").trim(), S2 = +String(s2[i.lon] ?? "").trim();
     return isFinite(d2) && isFinite(S2) && d2 >= -90 && d2 <= 90 && S2 >= -180 && S2 <= 180 && String(s2[i.lat] ?? "").trim() !== "" && String(s2[i.lon] ?? "").trim() !== "";
   });
-  return i.lat && i.lon && !w4 && a3.push(`lat/lon=${i.lat}/${i.lon} (no row holds a usable coordinate pair)`), i.country && !x3 && !(i.city || i.state || i.zip || w4) && a3.push(R4 ? `country=${i.country} (every row resolves to the same country - nothing to place apart)` : `country=${i.country} (values are not country identifiers)`), { bind: !!(i.city || i.state || i.zip || x3 || w4) ? i : null, backfilled: u4, refused: a3, ...Object.keys(h4).length ? { labelFallback: h4 } : {} };
+  return i.lat && i.lon && !w4 && a3.push(`lat/lon=${i.lat}/${i.lon} (no row holds a usable coordinate pair)`), i.country && !x3 && !(i.city || i.state || i.zip || w4) && a3.push(R4 ? `country=${i.country} (every row resolves to the same country - nothing to place apart)` : `country=${i.country} (values are not country identifiers)`), { bind: !!(i.city || i.state || i.zip || x3 || w4) ? i : null, backfilled: l2, refused: a3, ...Object.keys(h4).length ? { labelFallback: h4 } : {} };
 }
 var r = (e, ...t) => ({ part: e, langs: Object.freeze(t) });
 var ie = Object.freeze({ jaar: r("year", "nl"), kwartaal: r("quarter", "nl"), maand: r("month", "nl"), dag: r("day", "nl", "sv", "da", "nb"), jahr: r("year", "de"), quartal: r("quarter", "de"), monat: r("month", "de"), tag: r("day", "de"), ann\u00E9e: r("year", "fr"), mois: r("month", "fr"), jour: r("day", "fr"), trimestre: r("quarter", "fr", "es", "pt", "it"), a\u00F1o: r("year", "es"), mes: r("month", "es"), d\u00EDa: r("day", "es"), ano: r("year", "pt"), m\u00EAs: r("month", "pt"), dia: r("day", "pt"), anno: r("year", "it"), mese: r("month", "it"), giorno: r("day", "it"), \u0433\u043E\u0434: r("year", "ru"), \u043C\u0435\u0441\u044F\u0446: r("month", "ru"), \u0440\u0456\u043A: r("year", "uk"), \u043C\u0456\u0441\u044F\u0446\u044C: r("month", "uk"), \u043A\u0432\u0430\u0440\u0442\u0430\u043B: r("quarter", "ru", "uk"), \u0434\u0435\u043D\u044C: r("day", "ru", "uk"), rok: r("year", "pl", "cs", "sk"), kwarta\u0142: r("quarter", "pl"), miesi\u0105c: r("month", "pl"), dzie\u0144: r("day", "pl"), \u010Dtvrtlet\u00ED: r("quarter", "cs"), m\u011Bs\u00EDc: r("month", "cs"), den: r("day", "cs"), \u0161tvr\u0165rok: r("quarter", "sk"), mesiac: r("month", "sk"), de\u0148: r("day", "sk"), \u00E5r: r("year", "sv", "da", "nb"), kvartal: r("quarter", "sv", "da", "nb"), m\u00E5nad: r("month", "sv"), m\u00E5ned: r("month", "da", "nb"), vuosi: r("year", "fi"), vuosinelj\u00E4nnes: r("quarter", "fi"), kuukausi: r("month", "fi"), p\u00E4iv\u00E4: r("day", "fi"), \u00E9v: r("year", "hu"), negyed\u00E9v: r("quarter", "hu"), h\u00F3nap: r("month", "hu"), nap: r("day", "hu"), y\u0131l: r("year", "tr"), \u00E7eyrek: r("quarter", "tr"), ay: r("month", "tr"), g\u00FCn: r("day", "tr"), \u03AD\u03C4\u03BF\u03C2: r("year", "el"), \u03C4\u03C1\u03AF\u03BC\u03B7\u03BD\u03BF: r("quarter", "el"), \u03BC\u03AE\u03BD\u03B1\u03C2: r("month", "el"), \u03B7\u03BC\u03AD\u03C1\u03B1: r("day", "el"), an: r("year", "ro"), trimestru: r("quarter", "ro"), lun\u0103: r("month", "ro"), zi: r("day", "ro"), godina: r("year", "hr"), tromjese\u010Dje: r("quarter", "hr"), mjesec: r("month", "hr"), dan: r("day", "hr"), \u5E74: r("year", "ja", "zh"), \u56DB\u534A\u671F: r("quarter", "ja"), \u5B63\u5EA6: r("quarter", "zh"), \u6708: r("month", "ja", "zh"), \u65E5: r("day", "ja", "zh"), \uC5F0\uB3C4: r("year", "ko"), \uBD84\uAE30: r("quarter", "ko"), \uC6D4: r("month", "ko"), \uC77C: r("day", "ko"), tahun: r("year", "id"), kuartal: r("quarter", "id"), triwulan: r("quarter", "id"), bulan: r("month", "id"), hari: r("day", "id"), n\u0103m: r("year", "vi"), qu\u00FD: r("quarter", "vi"), th\u00E1ng: r("month", "vi"), ng\u00E0y: r("day", "vi"), \u0E1B\u0E35: r("year", "th"), \u0E44\u0E15\u0E23\u0E21\u0E32\u0E2A: r("quarter", "th"), \u0E40\u0E14\u0E37\u0E2D\u0E19: r("month", "th"), \u0E27\u0E31\u0E19: r("day", "th"), \u0627\u0644\u0633\u0646\u0629: r("year", "ar"), \u0633\u0646\u0629: r("year", "ar"), \u0627\u0644\u0639\u0627\u0645: r("year", "ar"), \u0639\u0627\u0645: r("year", "ar"), \u0627\u0644\u0631\u0628\u0639: r("quarter", "ar"), \u0631\u0628\u0639: r("quarter", "ar"), "\u0631\u0628\u0639 \u0627\u0644\u0633\u0646\u0629": r("quarter", "ar"), \u0627\u0644\u0634\u0647\u0631: r("month", "ar"), \u0634\u0647\u0631: r("month", "ar"), \u0627\u0644\u064A\u0648\u0645: r("day", "ar"), \u064A\u0648\u0645: r("day", "ar"), \u05E9\u05E0\u05D4: r("year", "he"), \u05E8\u05D1\u05E2\u05D5\u05DF: r("quarter", "he"), \u05D7\u05D5\u05D3\u05E9: r("month", "he"), \u05D9\u05D5\u05DD: r("day", "he"), \u0935\u0930\u094D\u0937: r("year", "hi"), \u0938\u093E\u0932: r("year", "hi"), \u0924\u093F\u092E\u093E\u0939\u0940: r("quarter", "hi"), \u092E\u0939\u0940\u0928\u093E: r("month", "hi"), \u092E\u093E\u0939: r("month", "hi"), \u0926\u093F\u0928: r("day", "hi"), \u0633\u0627\u0644: r("year", "fa"), \u0645\u0627\u0647: r("month", "fa"), \u0631\u0648\u0632: r("day", "fa") });

package/dist/{chunk-7HPVGRQ2.mjs → chunk-4KCSAHL5.mjs}

@@ -6,7 +6,7 @@ import {
   ht,
   kr,
   pt
-} from "./chunk-ZRSEKV4I.mjs";
+} from "./chunk-2XWE6YFO.mjs";
 
 // src/sourceDateFormat.ts
 function formatSourceDate(raw, opts = {}) {

package/dist/{chunk-MP5S6MVW.mjs → chunk-CJNONH6V.mjs}

@@ -5,7 +5,7 @@ import {
   X,
   Xn,
   Yn
-} from "./chunk-ZRSEKV4I.mjs";
+} from "./chunk-2XWE6YFO.mjs";
 import {
   censusHitBands,
   createMarkResolver,

package/dist/index.mjs

@@ -5,7 +5,7 @@ import {
   formatSourceDateFor,
   isExcelDateFormat,
   normaliseAggregation
-} from "./chunk-7HPVGRQ2.mjs";
+} from "./chunk-4KCSAHL5.mjs";
 import {
   ANNOTATION_CLASS,
   ANNOTATION_LAYER_CLASS,
@@ -111,12 +111,12 @@ import {
   toSourceRows,
   unpinScrolledAxis,
   valuePlacementFlag
-} from "./chunk-MP5S6MVW.mjs";
+} from "./chunk-CJNONH6V.mjs";
 import {
   _3,
   l,
   o
-} from "./chunk-ZRSEKV4I.mjs";
+} from "./chunk-2XWE6YFO.mjs";
 import {
   MIN_HIT_BAND_PX,
   SELECTION_GLYPH_CLASS,
@@ -2073,6 +2073,11 @@ function markerArmedBlind(m2) {
   if (!m2) return false;
   return (m2.h ?? m2.v - 1) <= 0;
 }
+function markerArmedAtMs(m2) {
+  if (!m2) return void 0;
+  const t2 = Math.floor(m2.t);
+  return Number.isFinite(t2) && t2 > 0 ? t2 : void 0;
+}
 function isBlindMarker(m2) {
   if (!m2) return false;
   return typeof m2.c !== "string" || m2.c.trim() === "";
@@ -2131,10 +2136,11 @@ function recoveryFinalOutcome(r2) {
   if (!r2) return null;
   const o3 = String(r2.pollOutcome ?? "").trim().toLowerCase();
   if (r2.isGenerationCancelled === true || r2.isPollFinal === true && o3 === "cancelled") return "cancelled";
-  if (r2.isPollFinal === true) return o3 === "not-received" ? "not-received" : "failed";
+  if (r2.isPollFinal === true) return o3 === "not-received" ? "not-received" : o3 === "lost-in-restart" ? "lost-in-restart" : "failed";
   if (r2.isPollFinal == null && r2.isVersionNotFound === true) {
     const c2 = String(r2.errorCode ?? "").trim().toUpperCase();
     if (c2 === "GENERATION_NOT_RECEIVED") return "not-received";
+    if (c2 === "GENERATION_LOST_IN_RESTART") return "lost-in-restart";
     if (c2 === "GENERATION_FAILED") return "failed";
     if (c2 === "GENERATION_CANCELLED") return "cancelled";
   }
@@ -2152,11 +2158,12 @@ function recoveryLooksUnreachable(transportFailuresInARow, everAnswered) {
 }
 var GENERATION_NOT_RECEIVED_MESSAGE = "The charting service has no record of that request, so nothing was generated and nothing was charged. Generate again.";
 var GENERATION_FAILED_MESSAGE = "That chart didn't finish on the server, so there's nothing to show. Generate again.";
+var GENERATION_LOST_IN_RESTART_MESSAGE = "The charting service restarted while your chart was being built, so nothing was delivered. Click Generate to build it again.";
 var RECOVERY_UNREACHABLE_MESSAGE = "We couldn't reach the charting service to check on your chart - it may be offline, or blocked on this network. Try again in a moment.";
 function recoveryFinalMessage(o3, serverMessage) {
   const s2 = String(serverMessage ?? "").trim();
   if (s2 !== "") return s2;
-  return o3 === "cancelled" ? GENERATION_CANCELLED_MESSAGE : o3 === "not-received" ? GENERATION_NOT_RECEIVED_MESSAGE : GENERATION_FAILED_MESSAGE;
+  return o3 === "cancelled" ? GENERATION_CANCELLED_MESSAGE : o3 === "not-received" ? GENERATION_NOT_RECEIVED_MESSAGE : o3 === "lost-in-restart" ? GENERATION_LOST_IN_RESTART_MESSAGE : GENERATION_FAILED_MESSAGE;
 }
 
 // src/chartPick.ts
@@ -2339,6 +2346,7 @@ export {
   FLIP_MODE_DEFAULT,
   GENERATION_CANCELLED_MESSAGE,
   GENERATION_FAILED_MESSAGE,
+  GENERATION_LOST_IN_RESTART_MESSAGE,
   GENERATION_NOT_RECEIVED_MESSAGE,
   GEO_POINT_PRECISIONS,
   GLYPH_SAMPLE_N,
@@ -2498,6 +2506,7 @@ export {
   loadGeo,
   markDefaultModel,
   markKeyOf,
+  markerArmedAtMs,
   markerArmedBlind,
   measureContainerBoxes,
   minContrastOver,

package/dist/react.mjs

@@ -22,8 +22,8 @@ import {
   loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-MP5S6MVW.mjs";
-import "./chunk-ZRSEKV4I.mjs";
+} from "./chunk-CJNONH6V.mjs";
+import "./chunk-2XWE6YFO.mjs";
 import "./chunk-MGAO2DR7.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-7JWL6LYE.mjs";

package/dist/testing.mjs

@@ -100,9 +100,186 @@ async function assertMarkerStoreConformance(store) {
   }
   done();
 }
+function isPlainBag(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function canonical(v) {
+  return JSON.stringify(v, (_k, val) => isPlainBag(val) ? Object.fromEntries(Object.keys(val).sort().map((k) => [k, val[k]])) : val);
+}
+function isProvider(p) {
+  return !!p && typeof p.load === "function" && typeof p.save === "function";
+}
+function policyEntryFailures(where, entry) {
+  if (!isPlainBag(entry)) return [`${where} is not an object`];
+  const out = [];
+  if (entry.lifetime !== "viewing" && entry.lifetime !== "durable") {
+    out.push(`${where}.lifetime is ${JSON.stringify(entry.lifetime)}, not "viewing" or "durable"`);
+  }
+  if (typeof entry.dropOnNewVersion !== "boolean") out.push(`${where}.dropOnNewVersion is not a boolean`);
+  if (typeof entry.dropOnFreshViewing !== "boolean") out.push(`${where}.dropOnFreshViewing is not a boolean`);
+  if (entry.durableWhen !== void 0 && (typeof entry.durableWhen !== "string" || !entry.durableWhen)) {
+    out.push(`${where}.durableWhen is not a preference name`);
+  }
+  if (entry.lifetime === "viewing" && entry.durableWhen !== void 0) {
+    out.push(`${where} has a durableWhen but a "viewing" lifetime, so the preference could never matter`);
+  }
+  return out;
+}
+function shapeFailures(service) {
+  if (!service || typeof service !== "object") return ["the service is missing"];
+  const out = [];
+  if (!isProvider(service.viewing)) out.push("viewing is missing, or has no load() or save()");
+  if (service.durable != null && !isProvider(service.durable)) out.push("durable has no load() or save()");
+  if (!isPlainBag(service.policy)) out.push("policy is missing, or is not an object keyed by view-state key");
+  else for (const k of Object.keys(service.policy)) out.push(...policyEntryFailures(`policy.${k}`, service.policy[k]));
+  if (service.chartKeys != null) out.push(...policyEntryFailures("chartKeys", service.chartKeys));
+  if (service.versionKey != null && (typeof service.versionKey !== "string" || !service.versionKey)) {
+    out.push("versionKey is not a key name");
+  }
+  if (service.durableMaxChars != null && !(typeof service.durableMaxChars === "number" && Number.isInteger(service.durableMaxChars) && service.durableMaxChars > 0)) {
+    out.push("durableMaxChars is not a positive whole number");
+  }
+  return out;
+}
+var PROBE_FIRST = {
+  __bicharts_conformance_view_a__: 1,
+  nested: { list: [1, "two", { three: 3 }], flag: true, none: null },
+  text: 'caf\xE9 "quoted"'
+};
+var PROBE_SECOND = { __bicharts_conformance_view_b__: ["only", "this"] };
+async function assertViewStateConformance(service, options = {}) {
+  const failures = [];
+  const checked = [];
+  const skipped = [];
+  const finish = () => {
+    if (failures.length) throw new ConformanceError("ViewStateService", failures);
+    return { checked, skipped };
+  };
+  const broken = shapeFailures(service);
+  if (broken.length) {
+    failures.push(...broken);
+    finish();
+  }
+  checked.push("shape");
+  const flush = async (durable) => {
+    if (durable && options.settle) await options.settle();
+  };
+  const expectBag = (label, what, got, want) => {
+    if (!isPlainBag(got)) failures.push(`${label}: ${what} returned ${canonical(got) ?? String(got)}, not an object`);
+    else if (canonical(got) !== canonical(want)) {
+      failures.push(`${label}: ${what} returned ${canonical(got)}, not ${canonical(want)}`);
+    }
+  };
+  const checkStore = async (label, store, durable) => {
+    let before = "{}";
+    try {
+      const held = store.load();
+      if (!isPlainBag(held)) failures.push(`${label}: load() of a store with nothing set returned ${String(held)}, not an object`);
+      else before = canonical(held);
+    } catch (e) {
+      failures.push(`${label}: load() threw, and it must never: ${describeThrow(e)}`);
+      return;
+    }
+    try {
+      store.save({});
+      await flush(durable);
+      expectBag(label, "load() after save({})", store.load(), {});
+      store.save(JSON.parse(canonical(PROBE_FIRST)));
+      await flush(durable);
+      expectBag(label, "load() after save()", store.load(), PROBE_FIRST);
+      store.save(JSON.parse(canonical(PROBE_SECOND)));
+      await flush(durable);
+      const replaced = store.load();
+      if (isPlainBag(replaced) && canonical(replaced) !== canonical(PROBE_SECOND)) {
+        failures.push(`${label}: a second save() did not replace the first (a save takes the whole bag): load() returned ${canonical(replaced)}`);
+      } else if (!isPlainBag(replaced)) {
+        failures.push(`${label}: load() after a second save() returned ${String(replaced)}, not an object`);
+      }
+      store.save({});
+      await flush(durable);
+      const emptied = store.load();
+      if (!isPlainBag(emptied) || Object.keys(emptied).length) {
+        failures.push(`${label}: save({}) did not empty the store: load() returned ${canonical(emptied)}`);
+      }
+    } catch (e) {
+      failures.push(`${label}: threw during an ordinary load() or save(): ${describeThrow(e)}`);
+    } finally {
+      try {
+        store.save(JSON.parse(before));
+        await flush(durable);
+      } catch {
+      }
+    }
+  };
+  await checkStore("viewing", service.viewing, false);
+  checked.push("viewing: load, save, replace, round trip");
+  if (service.durable) {
+    await checkStore("durable", service.durable, true);
+    checked.push("durable: load, save, replace, round trip");
+  }
+  if (!options.recreate) {
+    skipped.push("the viewing store survives a host re-created on the same element (pass options.recreate)");
+  } else {
+    let before = "{}";
+    try {
+      before = canonical(service.viewing.load());
+      service.viewing.save(JSON.parse(canonical(PROBE_FIRST)));
+      const again = options.recreate();
+      if (!again || !isProvider(again.viewing)) failures.push("viewing: recreate() did not return a service with a viewing store");
+      else expectBag("viewing", "load() on a service re-created over the same element", again.viewing.load(), PROBE_FIRST);
+    } catch (e) {
+      failures.push(`viewing: threw while checking a re-created service: ${describeThrow(e)}`);
+    } finally {
+      try {
+        service.viewing.save(JSON.parse(before));
+      } catch {
+      }
+    }
+    checked.push("viewing: survives a host re-created on the same element");
+  }
+  if (service.durable) {
+    if (!options.reopen) {
+      skipped.push("the durable store survives a reopen and the viewing store starts clean (pass options.reopen)");
+    } else {
+      let before = "{}";
+      let viewingBefore = "{}";
+      try {
+        before = canonical(service.durable.load());
+        viewingBefore = canonical(service.viewing.load());
+        service.viewing.save(JSON.parse(canonical(PROBE_SECOND)));
+        service.durable.save(JSON.parse(canonical(PROBE_FIRST)));
+        await flush(true);
+        const reopened = options.reopen();
+        if (!reopened || !isProvider(reopened.durable)) {
+          failures.push("durable: reopen() did not return a service with a durable store");
+        } else {
+          expectBag("durable", "load() on a service reopened over the same saved file", reopened.durable.load(), PROBE_FIRST);
+        }
+        if (reopened && isProvider(reopened.viewing)) {
+          expectBag("viewing", "load() after a reopen (a viewing starts clean)", reopened.viewing.load(), {});
+        }
+      } catch (e) {
+        failures.push(`durable: threw while checking a reopened service: ${describeThrow(e)}`);
+      } finally {
+        try {
+          service.durable.save(JSON.parse(before));
+          await flush(true);
+        } catch {
+        }
+        try {
+          service.viewing.save(JSON.parse(viewingBefore));
+        } catch {
+        }
+      }
+      checked.push("durable: survives a reopen; viewing: starts clean after one");
+    }
+  }
+  return finish();
+}
 export {
   ConformanceError,
   assertMarkerStoreConformance,
+  assertViewStateConformance,
   chartContainers,
   clickEmpty,
   clickMark,

package/dist/types/host/services.d.ts

@@ -1,4 +1,4 @@
-import type { RenderOptions } from "../contract";
+import type { RenderOptions, ViewStateProvider } from "../contract";
 /** Signs an encoded request body. See @bicharts/shape-core's host/services.ts. */
 export interface WireSigner {
     sign(encodedBody: string): string;
@@ -112,6 +112,71 @@ export interface ThumbnailConsent {
 export interface SnapshotTarget {
     svg(): SVGSVGElement | null;
 }
+/**
+ * How one key of the view-state bag lives and dies. A chart reads and writes its resting state
+ * (a sort, a frame, a 3D camera) through `options.uiState` / `options.setUiState`; the host
+ * decides what each key is allowed to outlive. A key that is not named in a service's `policy`
+ * is the chart's own, and follows `ViewStateService.chartKeys`.
+ */
+export interface ViewStateKeyPolicy {
+    /**
+     * `"viewing"`: kept for this viewing only (it survives a redraw, never reaches the durable
+     * store, and a durable store that happens to hold it is not believed). `"durable"`: kept in
+     * the viewing store AND the durable store, so it survives a close and reopen.
+     */
+    lifetime: "viewing" | "durable";
+    /**
+     * Drop the key when the chart on screen is a different version from the one the key was set
+     * on. A 3D camera is aimed at one chart's axes; the next chart has no use for it.
+     */
+    dropOnNewVersion: boolean;
+    /**
+     * Drop the key when the bag is read at the start of a fresh viewing (a page opened, a file
+     * opened) instead of in the viewing that wrote it. A manual "stop" on an animation belongs
+     * to the viewing that made it, though the durable store may hold it.
+     */
+    dropOnFreshViewing: boolean;
+    /**
+     * A preference that must read true for this key to reach the durable store. When it reads
+     * anything else, the key still lives in the viewing store (the reader keeps their view while
+     * the page is open) and stays out of the durable one. An unset preference reads as off.
+     */
+    durableWhen?: string;
+}
+/**
+ * Where a host keeps a chart's resting view-state, and what each key may outlive. "Render"
+ * lifetime is the absence of a store: anything not saved dies with the redraw.
+ *
+ * `viewing` is required; `durable` is optional, and a host that has none (a static preview, a
+ * server-side render) is saying it cannot remember across a close. Every member besides the two
+ * stores is a rule the shared view-state functions apply; the stores themselves stay dumb.
+ */
+export interface ViewStateService {
+    /** Survives a redraw (a resize, a cross-filter, a settings change). A page switch or a reopen starts clean. */
+    viewing: ViewStateProvider;
+    /** Survives close and reopen (a report file, a workbook). Absent or null: this host cannot. */
+    durable?: ViewStateProvider | null;
+    /** The keys the HOST writes or scopes, by name. */
+    policy: Readonly<Record<string, ViewStateKeyPolicy>>;
+    /**
+     * The rule for every key not named in `policy`: the ones the chart's own code writes.
+     * Absent: they are the chart's to keep (durable, and they survive a new version and a fresh
+     * viewing), because the chart validates what it reads. A host that forgets everything when
+     * the chart changes sets `dropOnNewVersion` here.
+     */
+    chartKeys?: ViewStateKeyPolicy | null;
+    /**
+     * The key under which the bag records the chart version it was last read for, so a version
+     * change is noticed even by a host that never saw the swap. Absent: the host applies the
+     * version rule itself, at the swap.
+     */
+    versionKey?: string | null;
+    /**
+     * The most characters of JSON the durable store accepts. A larger write is refused whole:
+     * nothing is saved, in either store, so the next read sees the state before it. Absent: no limit.
+     */
+    durableMaxChars?: number | null;
+}
 /**
  * The whole services object a host constructs and passes to shared logic.
  *
@@ -128,6 +193,9 @@ export interface SnapshotTarget {
  * - theme: visual, add-in; a web page when it reads the browser's scheme; not the MCP server.
  * - thumbnails and snapshot: visual, add-in; not the MCP server (no DOM) or a demo page.
  * - diagnostics: visual, add-in; not the MCP server (stdio) or a demo page.
+ * - viewState: visual, add-in and a web page that passes a provider; the MCP preview passes an
+ *   explicit no-op service. A host can remember across a close exactly when `viewState.durable`
+ *   is present (see `viewStateIsDurable` in "@bicharts/chart-host/view-state").
  */
 export interface HostServices {
     signer: WireSigner;
@@ -142,4 +210,5 @@ export interface HostServices {
     thumbnails?: ThumbnailConsent | null;
     snapshot?: SnapshotTarget | null;
     diagnostics?: DiagnosticsSink | null;
+    viewState?: ViewStateService | null;
 }

package/dist/types/index.d.ts

@@ -44,7 +44,7 @@ export { pinScrolledAxis, unpinScrolledAxis, type AxisPinReport } from "./fitDom
 export { MIN_DELTA_E, pickDistinctColorFromSeed, buildPalette, buildPaletteFromSeed, orderMostDistinct, LEGIBLE_LIGHTNESS, type PaletteResult, type SeedForSlot, type PaletteOptions, } from "./palette";
 export { deltaEHex } from "./deltaE";
 export { resolveAutoColorScale, autoRampMinStep, autoRampCanvas, AUTO_RAMP_CLASSES, AUTO_RAMP_DRAWN_OPACITY, AUTO_RAMP_MIN_STEP_DELTA_E, type AutoColorScale, type AutoColorScaleInput } from "./autoRamp";
-export { PENDING_RECOVERY_WINDOW_MS, PENDING_RECOVERY_POLL_MS, PENDING_RECOVERY_FIRST_POLL_MS, PENDING_RECOVERY_FAST_PHASE_MS, PENDING_RECOVERY_MID_POLL_MS, PENDING_RECOVERY_SLOW_PHASE_MS, PENDING_RECOVERY_SLOW_POLL_MS, pendingRecoveryNextDelayMs, encodePendingGenerate, parsePendingGenerate, markerArmedBlind, isBlindMarker, servedCorrelationProves, sameMarker, decidePendingRecovery, recoveryPollRunning, recoveryOwnsTheSentence, latePickupAction, latePickupKeepsMarker, pollGiveUpKeepsMarker, pendingRecoveryRemainingMs, transportFailureShouldRecover, TRANSPORT_LOST_CHECKING_MESSAGE, GENERATION_CANCELLED_MESSAGE, recoveryAnswerIsCancelled, generationCancelledMessage, recoveryFinalOutcome, recoveryProvesNothingCharged, recoveryGiveUpRefunds, recoveryLooksUnreachable, recoveryFinalMessage, PENDING_RECOVERY_UNREACHABLE_POLLS, GENERATION_NOT_RECEIVED_MESSAGE, GENERATION_FAILED_MESSAGE, RECOVERY_UNREACHABLE_MESSAGE, type PendingGenerateMarker, type PendingRecoveryDecision, type LatePickupAction, type RecoveryFinalOutcome, } from "./pendingGenerate";
+export { PENDING_RECOVERY_WINDOW_MS, PENDING_RECOVERY_POLL_MS, PENDING_RECOVERY_FIRST_POLL_MS, PENDING_RECOVERY_FAST_PHASE_MS, PENDING_RECOVERY_MID_POLL_MS, PENDING_RECOVERY_SLOW_PHASE_MS, PENDING_RECOVERY_SLOW_POLL_MS, pendingRecoveryNextDelayMs, encodePendingGenerate, parsePendingGenerate, markerArmedBlind, markerArmedAtMs, isBlindMarker, servedCorrelationProves, sameMarker, decidePendingRecovery, recoveryPollRunning, recoveryOwnsTheSentence, latePickupAction, latePickupKeepsMarker, pollGiveUpKeepsMarker, pendingRecoveryRemainingMs, transportFailureShouldRecover, TRANSPORT_LOST_CHECKING_MESSAGE, GENERATION_CANCELLED_MESSAGE, recoveryAnswerIsCancelled, generationCancelledMessage, recoveryFinalOutcome, recoveryProvesNothingCharged, recoveryGiveUpRefunds, recoveryLooksUnreachable, recoveryFinalMessage, PENDING_RECOVERY_UNREACHABLE_POLLS, GENERATION_NOT_RECEIVED_MESSAGE, GENERATION_FAILED_MESSAGE, GENERATION_LOST_IN_RESTART_MESSAGE, RECOVERY_UNREACHABLE_MESSAGE, type PendingGenerateMarker, type PendingRecoveryDecision, type LatePickupAction, type RecoveryFinalOutcome, } from "./pendingGenerate";
 export { stripJsComments } from "./codeComments";
 export { reconcileChartPick, type ChartPickReconciliation } from "./chartPick";
 export { isDuplicateGenerate, armGenerateGuard, DUPLICATE_GENERATE_WINDOW_MS, type GenerateGuardKey, type GenerateGuardState, } from "./duplicateGenerateGuard";
@@ -53,4 +53,4 @@ export { isNarrowedByFilter, isEmptiedByFilter, updateRowHighWater, type Narrowi
 export { shouldCaptureThumbnail, type ThumbnailGate, type ThumbnailDecision } from "./thumbnailPolicy";
 export { isPickableModelCode, markDefaultModel, defaultModelFirst, reconcileModelPick, DEFAULT_MODEL_SUFFIX, } from "./modelPicker";
 export { stableFingerprintOptions, fingerprintComponentDigest, type ClientIdSource } from "./clientIdentity";
-export type { HostServices, MarkerStore, PreferenceSource, HostTheme, ThemeSource, ThumbnailConsent, SnapshotTarget, WireSigner, WireTransport, WireResponse, CredentialTriple, CredentialSource, ViewportSource, Clock, DiagnosticEntry, DiagnosticsSink, RendererId, } from "./host/services";
+export type { HostServices, MarkerStore, PreferenceSource, HostTheme, ThemeSource, ThumbnailConsent, SnapshotTarget, WireSigner, WireTransport, WireResponse, CredentialTriple, CredentialSource, ViewportSource, Clock, DiagnosticEntry, DiagnosticsSink, RendererId, ViewStateKeyPolicy, ViewStateService, } from "./host/services";

package/dist/types/pendingGenerate.d.ts

@@ -55,6 +55,17 @@ export type PendingRecoveryDecision = "none" | "delivered" | "expired" | "blind"
  * `v - 1` fallback says the same thing for markers written by older builds.
  */
 export declare function markerArmedBlind(m: PendingGenerateMarker | null | undefined): boolean;
+/**
+ * WHEN THIS MARKER'S GENERATE STARTED, as a recovery poll states it: the marker's own `t`, epoch milliseconds on
+ * this host's clock, as a whole number - the `fetchArmedAtMs` a poll by correlation passes to `fetchFields`.
+ *
+ * With it the server can tell a generate that died with a server restart (started before the running process,
+ * no record of it) from one still running, and say so at the first poll instead of after the whole window.
+ * Nothing is shifted or checked against the clock here: a slow or fast host clock is the server's margin to
+ * absorb, and a future time it reads as absent. undefined for no marker or a time that is not a positive
+ * number, so the poll sends exactly what it always sent.
+ */
+export declare function markerArmedAtMs(m: PendingGenerateMarker | null | undefined): number | undefined;
 /**
  * Can this marker be recovered AT ALL? Only by CORRELATION, so only if it carries one.
  *
@@ -198,7 +209,7 @@ export declare function generationCancelledMessage(serverMessage: string | null
  * beside it for older hosts, so this is read FIRST. null = not final. A final answer with an outcome
  * this build does not know reads as "failed": it is final, and it claims nothing about charges.
  */
-export type RecoveryFinalOutcome = "cancelled" | "failed" | "not-received";
+export type RecoveryFinalOutcome = "cancelled" | "failed" | "not-received" | "lost-in-restart";
 export declare function recoveryFinalOutcome(r: {
     isPollFinal?: boolean | null;
     pollOutcome?: string | null;
@@ -207,7 +218,8 @@ export declare function recoveryFinalOutcome(r: {
     errorCode?: string | null;
 } | null | undefined): RecoveryFinalOutcome | null;
 /** Did the server PROVE nothing was charged? Only a cancel and a request it never received do; a
- *  failed generation's charge is its own, and a host claims nothing about it. */
+ *  failed generation's charge is its own, and a generate that died with a restart may have been charged
+ *  before its record was written, so a host claims nothing about either. */
 export declare function recoveryProvesNothingCharged(o: string | null | undefined): boolean;
 /** Does a recovery that ended this way send the refund? Only when it ended with NOTHING PAINTED and
  *  nothing proven - the window closed, the poll itself was refused, or the service could not be
@@ -222,6 +234,10 @@ export declare function recoveryLooksUnreachable(transportFailuresInARow: number
  *  localises by code. */
 export declare const GENERATION_NOT_RECEIVED_MESSAGE = "The charting service has no record of that request, so nothing was generated and nothing was charged. Generate again.";
 export declare const GENERATION_FAILED_MESSAGE = "That chart didn't finish on the server, so there's nothing to show. Generate again.";
+/** The process that was building the chart is gone, so nothing will arrive. Says what happened and what to
+ *  do, and claims nothing about a charge: a free-tier meter can be charged before the generation's record
+ *  exists, so a restart in between can leave a charge that no record shows. */
+export declare const GENERATION_LOST_IN_RESTART_MESSAGE = "The charting service restarted while your chart was being built, so nothing was delivered. Click Generate to build it again.";
 /** Neither the generate's answer nor any check reached us. Claims nothing about a charge: behind a
  *  proxy the generate may have arrived when the checks did not. */
 export declare const RECOVERY_UNREACHABLE_MESSAGE = "We couldn't reach the charting service to check on your chart - it may be offline, or blocked on this network. Try again in a moment.";

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

@@ -1,4 +1,4 @@
-import type { MarkerStore } from "../host/services";
+import type { MarkerStore, ViewStateService } from "../host/services";
 /** Thrown by every conformance check. `failures` names each property the adapter broke. */
 export declare class ConformanceError extends Error {
     readonly contract: string;
@@ -12,4 +12,43 @@ export declare class ConformanceError extends Error {
  * before returning, whether or not the check passed.
  */
 export declare function assertMarkerStoreConformance(store: MarkerStore): Promise<void>;
+/** What a host can hand `assertViewStateConformance` so it can exercise more of the contract. */
+export interface ViewStateConformanceOptions {
+    /**
+     * Flushes a durable write that is debounced or asynchronous (a fake-timer tick, an awaited save),
+     * and is called after every write to the durable store before the check reads it back. A host whose
+     * durable `save()` lands synchronously omits it.
+     */
+    settle?: () => void | Promise<void>;
+    /**
+     * Builds the service again over the same element, the way the host does on a redraw. A viewing
+     * store must read there what the first one saved. Without it that property goes unchecked, and the
+     * report says so.
+     */
+    recreate?: () => ViewStateService;
+    /**
+     * Builds the service as a new viewing over the same saved file or workbook (a page switch, a
+     * reopen). The durable store must read what was saved, and the viewing store must start clean.
+     * Without it that property goes unchecked when there is a durable store, and the report says so.
+     */
+    reopen?: () => ViewStateService;
+}
+/** What a passing run covered. A failing run throws instead. */
+export interface ViewStateConformanceReport {
+    checked: readonly string[];
+    /** Properties that need an option the caller did not pass. A host's own test can require this to be empty. */
+    skipped: readonly string[];
+}
+/**
+ * Checks a ViewStateService against the contract. A bag's store: `load()` never throws and reads `{}`
+ * when nothing is stored; `save()` takes the WHOLE bag and replaces what was there; nested values come
+ * back as written. The viewing store must survive the host being re-created on the same element (pass
+ * `recreate`). The durable store, when there is one, must hold what it was given, including across a
+ * reopen (pass `reopen`) where the viewing store starts clean. The policy must be well formed.
+ *
+ * Whatever the stores held before the check is put back before it returns, whether or not it passed.
+ * Resolves to a report of what was covered and what needed an option that was not passed; throws a
+ * ConformanceError listing every broken property otherwise.
+ */
+export declare function assertViewStateConformance(service: ViewStateService, options?: ViewStateConformanceOptions): Promise<ViewStateConformanceReport>;
 export { chartContainers, marksOf, findMark, clickMark, clickEmpty, selectedRows } from "./interact";

package/dist/types/viewState.d.ts

@@ -0,0 +1,125 @@
+import type { ViewStateKeyPolicy, ViewStateService } from "./host/services";
+/**
+ * A service that stores nothing: a static preview, a server-side render, a thumbnail capture,
+ * where remembering would be wrong rather than merely absent (a thumbnail must be the same picture
+ * every time it is taken). Saying so out loud differs from passing no service at all, which leaves
+ * the choice to the host. The viewing store reads `{}` always and there is no durable store.
+ */
+export declare function noopViewStateService(): ViewStateService;
+/**
+ * Whether this host can remember a chart's view across a close and reopen. This is the one
+ * definition of "remembers the view": it is derived from the service, never declared beside it, so
+ * a host cannot claim it without a durable store to back the claim.
+ */
+export declare function viewStateIsDurable(service: ViewStateService | null | undefined): boolean;
+/**
+ * The rule for a key the chart's own code writes, when a service names no other. The chart keeps it:
+ * it reaches the durable store, and it survives a new version of the chart and a fresh viewing.
+ * Such a key can be stale (a sort on a column the new chart doesn't have), and that is the chart's to
+ * handle: whatever it reads from the bag is untrusted, and it validates it.
+ */
+export declare const CHART_OWNED_KEY_POLICY: Readonly<ViewStateKeyPolicy>;
+/** A key a rule took out of the bag a chart is handed, and why. */
+export interface ViewStateDrop {
+    key: string;
+    reason: "fresh-viewing" | "new-version";
+}
+export interface ResolveViewStateOptions {
+    /** The version of the chart about to draw. Compared with what the bag recorded under `versionKey`. */
+    codeVersion?: number | string | null;
+    /**
+     * True when this viewing has not yet written a bag of its own (a page just opened, a file just
+     * opened). False when it has, which makes the viewing store the bag even if it reads empty, so a
+     * chart that cleared its state is not handed the older state the durable store still holds.
+     * Absent: a bag read from the durable store is a fresh viewing, and one read from the viewing store is not.
+     */
+    freshViewing?: boolean;
+}
+export interface ResolvedViewState {
+    /** The bag to hand the chart as `options.uiState`. The caller's own copy: nothing in a store aliases it. */
+    bag: Record<string, unknown>;
+    /** Where the bag was read from. `"none"`: neither store held anything. */
+    source: "viewing" | "durable" | "none";
+    /** Every key a rule took out, in the order the rules ran, so a host can log what it did. */
+    dropped: ViewStateDrop[];
+}
+/**
+ * BUILD THE BAG A CHART IS HANDED.
+ *
+ * Read order: the viewing store when it holds anything (or when the viewing has already written, see
+ * `freshViewing`), otherwise the durable store, otherwise nothing. The viewing store is the newer of
+ * the two within a viewing: a durable store can lag its own writes by a round trip, and a redraw in
+ * that window must see the write, not the state before it. A key whose lifetime is `"viewing"` is
+ * never believed from the durable store.
+ *
+ * Then two rules run, in this order, each over the keys a service's policy names (and, for the keys
+ * it doesn't, over `chartKeys`):
+ * - a fresh viewing drops every key marked `dropOnFreshViewing` whose value is set. A value that is
+ *   already off (false, 0, "") stays: dropping it would change nothing the chart can tell.
+ * - a version change drops every key marked `dropOnNewVersion` that is present, and then records the
+ *   current version under `versionKey` so the bag no longer reads as another chart's. Only when
+ *   the service has a `versionKey`; a host without one applies the rule itself, with
+ *   `viewStateAfterSwap`, wherever it learns the chart changed.
+ *
+ * The stamp is part of the bag the chart receives. The chart's own write carries it forward; a write
+ * that replaces the bag without it reads as another chart's on the next call.
+ *
+ * Never throws, and never changes a store: the bag is a copy the caller may let the chart mutate.
+ * A saved value that is not an object (a number, an array) is handed on as saved, with no rule run.
+ */
+export declare function resolveViewState(service: ViewStateService, options?: ResolveViewStateOptions): ResolvedViewState;
+/**
+ * WHEN THE CHART CHANGES UNDER A BAG THAT KEPT NO VERSION. Returns a copy of `bag` without the keys the
+ * policy marks `dropOnNewVersion` (and, if `chartKeys` marks it, without every key the chart wrote). A
+ * host that sees the swap itself (a regenerate, a version load, a cleared chart) calls it where it
+ * learns of it and saves what comes back. `versionKey` is left as it is: the next `resolveViewState`
+ * brings it up to date. A bag that is not an object, or nothing, comes back as `{}`.
+ */
+export declare function viewStateAfterSwap(service: ViewStateService, bag: unknown): Record<string, unknown>;
+/** What `commitViewState` did. */
+export interface CommitViewStateResult {
+    /**
+     * `"saved"`: handed to the stores. `"ignored"`: not an object (or not serializable), so nothing was
+     * saved anywhere. `"too-large"`: the durable payload exceeded the service's `durableMaxChars`, so
+     * nothing was saved anywhere and the next read sees the state before this write.
+     */
+    outcome: "saved" | "ignored" | "too-large";
+    /** The viewing store's `save` ran without throwing. */
+    viewingSaved: boolean;
+    /** The durable store's `save` ran without throwing. False too when the service has no durable store. */
+    durableSaved: boolean;
+    /** Keys kept out of the durable store because their `durableWhen` preference is off, in policy order. */
+    withheld: string[];
+    /** Characters of JSON in the durable payload, measured only when the service sets a limit. */
+    durableChars: number | null;
+    /** A store that threw. The other store is still written, and the write never throws out of the chart. */
+    errors: Array<{
+        store: "viewing" | "durable";
+        error: unknown;
+    }>;
+}
+/**
+ * What the commit asks of a preference source: the value behind a switch's name. A host's own
+ * `PreferenceSource` (HostServices.prefs) satisfies it; so does `{ get: name => settings[name] }`.
+ */
+export interface ViewStatePreferences {
+    get(key: string): unknown;
+}
+/**
+ * DECIDE WHAT A CHART'S WRITE REACHES.
+ *
+ * `next` is the whole bag the chart wrote (a write replaces; the chart merges its own siblings). The
+ * viewing store always gets all of it, so a reader who turns a 3D cube keeps their angle while the page
+ * is open whatever they have chosen to share. The durable store gets the same bag less the keys that
+ * must not reach it: a `"viewing"` lifetime, or a `durableWhen` preference that doesn't read true. The
+ * preference is read now, when the chart writes, not when the render began; an unset preference, a
+ * missing source or a source that throws all read as off, so a view is never shared by accident.
+ *
+ * The viewing store is written first and unconditionally, so a durable store that skips a write that
+ * changes nothing in its own payload (a camera-only change with the camera withheld) cannot cost the
+ * session the new pose. The one case where neither store is written is a refusal: a durable payload
+ * over `durableMaxChars` is dropped whole, so the next read sees the state before it.
+ *
+ * Never throws. A store that throws is reported in `errors` and the other store is still written.
+ */
+export declare function commitViewState(next: unknown, service: ViewStateService, prefs?: ViewStatePreferences | null): CommitViewStateResult;

package/dist/view-state.mjs

@@ -0,0 +1,171 @@
+/*! @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 "./chunk-GHODWOAL.mjs";
+
+// src/viewState.ts
+function noopViewStateService() {
+  const nowhere = { load: () => ({}), save: () => {
+  } };
+  return { viewing: nowhere, durable: null, policy: {} };
+}
+function viewStateIsDurable(service) {
+  return !!service && !!service.durable;
+}
+var CHART_OWNED_KEY_POLICY = Object.freeze({
+  lifetime: "durable",
+  dropOnNewVersion: false,
+  dropOnFreshViewing: false
+});
+var own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+function isBag(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function holds(v) {
+  return isBag(v) ? Object.keys(v).length > 0 : !!v;
+}
+function loadOrEmpty(store) {
+  try {
+    const bag = store ? store.load() : void 0;
+    return bag == null ? {} : bag;
+  } catch {
+    return {};
+  }
+}
+function put(into, key, value) {
+  Object.defineProperty(into, key, { value, enumerable: true, writable: true, configurable: true });
+}
+function copyOf(v, depth = 0) {
+  if (v === null || typeof v !== "object" || depth > 64) return v;
+  if (Array.isArray(v)) return v.map((x) => copyOf(x, depth + 1));
+  const proto = Object.getPrototypeOf(v);
+  if (proto !== Object.prototype && proto !== null) return v;
+  const out = {};
+  for (const k of Object.keys(v)) put(out, k, copyOf(v[k], depth + 1));
+  return out;
+}
+function policyFor(service, key) {
+  if (service.policy && own(service.policy, key)) return service.policy[key];
+  return service.chartKeys ?? CHART_OWNED_KEY_POLICY;
+}
+function resolveViewState(service, options = {}) {
+  const viewed = loadOrEmpty(service.viewing);
+  let source;
+  let raw;
+  if (holds(viewed) || options.freshViewing === false) {
+    source = "viewing";
+    raw = holds(viewed) ? viewed : {};
+  } else {
+    const stored = loadOrEmpty(service.durable);
+    source = holds(stored) ? "durable" : "none";
+    raw = holds(stored) ? stored : {};
+    if (isBag(raw)) {
+      const believed = {};
+      for (const k of Object.keys(raw)) if (policyFor(service, k).lifetime !== "viewing") put(believed, k, raw[k]);
+      raw = believed;
+    }
+  }
+  const bag = copyOf(raw);
+  const dropped = [];
+  if (!isBag(bag)) return { bag, source, dropped };
+  const versionKey = service.versionKey || null;
+  const fresh = options.freshViewing ?? source !== "viewing";
+  if (fresh) {
+    for (const key of Object.keys(bag)) {
+      if (key === versionKey) continue;
+      if (policyFor(service, key).dropOnFreshViewing && bag[key]) {
+        delete bag[key];
+        dropped.push({ key, reason: "fresh-viewing" });
+      }
+    }
+  }
+  if (versionKey) {
+    const version = options.codeVersion ?? null;
+    if (bag[versionKey] !== version) {
+      for (const key of Object.keys(bag)) {
+        if (key === versionKey) continue;
+        if (policyFor(service, key).dropOnNewVersion) {
+          delete bag[key];
+          dropped.push({ key, reason: "new-version" });
+        }
+      }
+      put(bag, versionKey, version);
+    }
+  }
+  return { bag, source, dropped };
+}
+function viewStateAfterSwap(service, bag) {
+  const copy = copyOf(bag);
+  if (!isBag(copy)) return {};
+  const versionKey = service.versionKey || null;
+  for (const key of Object.keys(copy)) {
+    if (key !== versionKey && policyFor(service, key).dropOnNewVersion) delete copy[key];
+  }
+  return copy;
+}
+function preferenceOn(prefs, name) {
+  try {
+    return !!(prefs && prefs.get(name));
+  } catch {
+    return false;
+  }
+}
+function commitViewState(next, service, prefs) {
+  const result = {
+    outcome: "saved",
+    viewingSaved: false,
+    durableSaved: false,
+    withheld: [],
+    durableChars: null,
+    errors: []
+  };
+  if (next == null || typeof next !== "object") return { ...result, outcome: "ignored" };
+  const bag = next;
+  const durable = service.durable || null;
+  let forFile = bag;
+  if (durable && isBag(bag)) {
+    let trimmed = null;
+    const withheld = /* @__PURE__ */ new Set();
+    for (const key of Object.keys(bag)) {
+      const policy = policyFor(service, key);
+      const keep = policy.lifetime !== "viewing" && (policy.durableWhen === void 0 || preferenceOn(prefs, policy.durableWhen));
+      if (keep) continue;
+      trimmed ??= { ...bag };
+      delete trimmed[key];
+      if (policy.lifetime !== "viewing") withheld.add(key);
+    }
+    if (trimmed) forFile = trimmed;
+    const declared = Object.keys(service.policy || {});
+    result.withheld = [...declared.filter((k) => withheld.has(k)), ...[...withheld].filter((k) => !declared.includes(k))];
+  }
+  if (durable && service.durableMaxChars) {
+    try {
+      result.durableChars = JSON.stringify(forFile).length;
+    } catch (error) {
+      result.errors.push({ store: "durable", error });
+      return { ...result, outcome: "ignored" };
+    }
+    if (result.durableChars > service.durableMaxChars) return { ...result, outcome: "too-large" };
+  }
+  try {
+    service.viewing.save(bag);
+    result.viewingSaved = true;
+  } catch (error) {
+    result.errors.push({ store: "viewing", error });
+  }
+  if (durable) {
+    try {
+      durable.save(forFile);
+      result.durableSaved = true;
+    } catch (error) {
+      result.errors.push({ store: "durable", error });
+    }
+  }
+  return result;
+}
+export {
+  CHART_OWNED_KEY_POLICY,
+  commitViewState,
+  noopViewStateService,
+  resolveViewState,
+  viewStateAfterSwap,
+  viewStateIsDurable
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.6.81",
+  "version": "0.6.83",
   "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",
@@ -49,6 +49,11 @@
       "import": "./dist/card.mjs",
       "default": "./dist/card.mjs"
     },
+    "./view-state": {
+      "types": "./dist/types/viewState.d.ts",
+      "import": "./dist/view-state.mjs",
+      "default": "./dist/view-state.mjs"
+    },
     "./adapters": {
       "types": "./dist/types/adapters/index.d.ts",
       "import": "./dist/adapters.mjs",