@bicharts/chart-host 0.6.81 → 0.6.82

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/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

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