@bicharts/chart-host 0.1.5

package/dist/geo.mjs

@@ -0,0 +1,41 @@
+/*! @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 {
+  US_STATES
+} from "./chunk-NWID6YOP.mjs";
+import {
+  US_ZIP3
+} from "./chunk-MHDS4Q5G.mjs";
+import {
+  WORLD_110M
+} from "./chunk-23GNNTXQ.mjs";
+import {
+  NA_ISO3,
+  NA_LAT_MAX,
+  clipFeatureToLat
+} from "./chunk-22B22PJU.mjs";
+
+// src/geo.ts
+function geoForKind(geoKind) {
+  if (!geoKind) return void 0;
+  const k = geoKind.toLowerCase();
+  if (/^country/.test(k)) return WORLD_110M;
+  if (k === "us-state-code" || k === "us-state-name") return US_STATES;
+  if (k === "us-zip5") return US_ZIP3;
+  if (k === "north-america") return northAmerica();
+  return void 0;
+}
+var _na;
+function northAmerica() {
+  if (!_na) {
+    _na = {
+      type: "FeatureCollection",
+      features: WORLD_110M.features.filter((f) => NA_ISO3.has(f?.id) && f?.geometry && f.geometry.type !== "Point").map((f) => clipFeatureToLat(f, NA_LAT_MAX)).filter((f) => f !== null)
+    };
+  }
+  return _na;
+}
+export {
+  NA_ISO3,
+  geoForKind
+};
+//# sourceMappingURL=geo.mjs.map

package/dist/geo.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/geo.ts"],
+  "sourcesContent": ["import { WORLD_110M } from \"./geoWorld110m.generated\";\nimport { US_STATES } from \"./geoUsStates.generated\";\nimport { US_ZIP3 } from \"./geoUsZip3.generated\";\nimport { NA_ISO3, NA_LAT_MAX, clipFeatureToLat } from \"./geoNaRegions\";\n\n// Geometry the D3 choropleth lanes hand to generated code as `options.geo`\n// (2026-07-22 \u2014 bundled, not fetched: each asset is well under ~180 KB gzipped,\n// so it rides the visual, needs no /geo/ hosting, and renders offline/air-gapped).\n// Moved into @bicharts/chart-host (Phase B) so the Power BI visual AND the MCP client share\n// ONE copy \u2014 MCP no longer reaches into the visual's src/. Keyed by the server-supplied\n// geoKind \u2192 the FeatureCollection whose feature.id is the join key generated code binds\n// against __geoIso__:\n//   country-*                \u2192 WORLD_110M  (feature.id = ISO 3166-1 alpha-3)\n//   us-state-code|name       \u2192 US_STATES   (feature.id = USPS, e.g. \"CA\")\n//   us-zip5                  \u2192 US_ZIP3     (feature.id = 3-digit prefix; the archetype\n//                                           joins __geoIso__.slice(0,3) == feature.id)\n// County / other assets slot in here (own generated modules) as those lanes land.\nexport function geoForKind(geoKind: string | null | undefined): any | undefined {\n    if (!geoKind) return undefined;\n    const k = geoKind.toLowerCase();\n    if (/^country/.test(k)) return WORLD_110M;\n    if (k === \"us-state-code\" || k === \"us-state-name\") return US_STATES;\n    if (k === \"us-zip5\") return US_ZIP3;\n    if (k === \"north-america\") return northAmerica();\n    return undefined;\n}\n\n// North America BASEMAP for point-map (lat/lon) types \u2014 e.g. North America (Bubbles).\n// Not a join target (no __geoIso__): pure grey context polygons. Filtered from the\n// already-bundled world asset at runtime (zero extra bundle bytes); polygons only \u2014\n// the world asset's centroid Point features (micro-island hubs) are join aids for the\n// choropleth and would just clutter a context map. Cached after first build. The\n// server routes this via LLMChartType.GeoAssetKind -> res.GeoKind = \"north-america\".\n// Membership (and the Greenland exclusion + its rationale) lives in geoNaRegions.ts so it can\n// be read without pulling this module's ~1.3 MB of generated geometry. Re-exported for callers\n// that already hold a geo.ts import.\nexport { NA_ISO3 };\nlet _na: any | undefined;\nfunction northAmerica(): any {\n    if (!_na) {\n        // Membership filter, then the northern cutoff. The archetype fitExtent()s to this\n        // collection, so clipping the geometry (rather than only the fit) is what actually\n        // reclaims the frame: land above the cutoff is gone, so it can neither drive the fit\n        // nor spill over the top of the plot area into the header strip.\n        _na = {\n            type: \"FeatureCollection\",\n            features: (WORLD_110M.features as any[])\n                .filter((f: any) => NA_ISO3.has(f?.id) && f?.geometry && f.geometry.type !== \"Point\")\n                .map((f: any) => clipFeatureToLat(f, NA_LAT_MAX))\n                .filter((f: any) => f !== null),\n        };\n    }\n    return _na;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;AAiBO,SAAS,WAAW,SAAqD;AAC5E,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,IAAI,QAAQ,YAAY;AAC9B,MAAI,WAAW,KAAK,CAAC,EAAG,QAAO;AAC/B,MAAI,MAAM,mBAAmB,MAAM,gBAAiB,QAAO;AAC3D,MAAI,MAAM,UAAW,QAAO;AAC5B,MAAI,MAAM,gBAAiB,QAAO,aAAa;AAC/C,SAAO;AACX;AAYA,IAAI;AACJ,SAAS,eAAoB;AACzB,MAAI,CAAC,KAAK;AAKN,UAAM;AAAA,MACF,MAAM;AAAA,MACN,UAAW,WAAW,SACjB,OAAO,CAAC,MAAW,QAAQ,IAAI,GAAG,EAAE,KAAK,GAAG,YAAY,EAAE,SAAS,SAAS,OAAO,EACnF,IAAI,CAAC,MAAW,iBAAiB,GAAG,UAAU,CAAC,EAC/C,OAAO,CAAC,MAAW,MAAM,IAAI;AAAA,IACtC;AAAA,EACJ;AACA,SAAO;AACX;",
+  "names": []
+}

package/dist/geoNaRegions-SAINMZXG.mjs

@@ -0,0 +1,12 @@
+/*! @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 {
+  NA_ISO3,
+  NA_LAT_MAX,
+  clipFeatureToLat
+} from "./chunk-22B22PJU.mjs";
+export {
+  NA_ISO3,
+  NA_LAT_MAX,
+  clipFeatureToLat
+};
+//# sourceMappingURL=geoNaRegions-SAINMZXG.mjs.map

package/dist/geoNaRegions-SAINMZXG.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/geoUsStates.generated-2ZZRXWWJ.mjs

@@ -0,0 +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 {
+  US_STATES
+} from "./chunk-NWID6YOP.mjs";
+export {
+  US_STATES
+};
+//# sourceMappingURL=geoUsStates.generated-2ZZRXWWJ.mjs.map

package/dist/geoUsStates.generated-2ZZRXWWJ.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/geoUsZip3.generated-56OL4TTZ.mjs

@@ -0,0 +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 {
+  US_ZIP3
+} from "./chunk-MHDS4Q5G.mjs";
+export {
+  US_ZIP3
+};
+//# sourceMappingURL=geoUsZip3.generated-56OL4TTZ.mjs.map

package/dist/geoUsZip3.generated-56OL4TTZ.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/geoWorld110m.generated-O2WOIRYY.mjs

@@ -0,0 +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 {
+  WORLD_110M
+} from "./chunk-23GNNTXQ.mjs";
+export {
+  WORLD_110M
+};
+//# sourceMappingURL=geoWorld110m.generated-O2WOIRYY.mjs.map

package/dist/geoWorld110m.generated-O2WOIRYY.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/index.mjs

@@ -0,0 +1,70 @@
+/*! @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 {
+  ANIM_MAX_IDEAL_FRAMES_DEFAULT,
+  ANIM_MAX_IDEAL_FRAMES_MAX,
+  ANIM_MAX_IDEAL_FRAMES_MIN,
+  ANIM_PLAY_SPEED_DEFAULT,
+  ANIM_PLAY_SPEED_MAX,
+  ANIM_PLAY_SPEED_MIN,
+  AXIS_FILTER_CLASS,
+  COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT,
+  COLOR_SCALE_SELF_CLAMP_PCT_MAX,
+  COLOR_SCALE_SELF_CLAMP_PCT_MIN,
+  CONTAINER_SLOT_ANIM_STOP,
+  CONTAINER_SLOT_INITIAL_XF_MARK,
+  CONTAINER_SLOT_XF_CLEAR,
+  DIM_OPACITY_DEFAULT,
+  DIM_OPACITY_VAR,
+  GEO_POINT_PRECISIONS,
+  HOST_CONTAINER_CLASS,
+  HOST_CONTRACT_VERSION,
+  LEGEND_MARK_CLASS,
+  MARK_CLASS,
+  MARK_SELECTED_CLASS,
+  ROW_IDX_ATTR,
+  SELECTION_ACTIVE_CLASS,
+  XFILTER_REFRESH_EVENT,
+  buildRenderPayload,
+  compileRenderFn,
+  createChartHost,
+  createMarkResolver,
+  geoFromCache,
+  loadGeo,
+  registerGeo,
+  resolveOptions
+} from "./chunk-UNH36TGD.mjs";
+export {
+  ANIM_MAX_IDEAL_FRAMES_DEFAULT,
+  ANIM_MAX_IDEAL_FRAMES_MAX,
+  ANIM_MAX_IDEAL_FRAMES_MIN,
+  ANIM_PLAY_SPEED_DEFAULT,
+  ANIM_PLAY_SPEED_MAX,
+  ANIM_PLAY_SPEED_MIN,
+  AXIS_FILTER_CLASS,
+  COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT,
+  COLOR_SCALE_SELF_CLAMP_PCT_MAX,
+  COLOR_SCALE_SELF_CLAMP_PCT_MIN,
+  CONTAINER_SLOT_ANIM_STOP,
+  CONTAINER_SLOT_INITIAL_XF_MARK,
+  CONTAINER_SLOT_XF_CLEAR,
+  DIM_OPACITY_DEFAULT,
+  DIM_OPACITY_VAR,
+  GEO_POINT_PRECISIONS,
+  HOST_CONTAINER_CLASS,
+  HOST_CONTRACT_VERSION,
+  LEGEND_MARK_CLASS,
+  MARK_CLASS,
+  MARK_SELECTED_CLASS,
+  ROW_IDX_ATTR,
+  SELECTION_ACTIVE_CLASS,
+  XFILTER_REFRESH_EVENT,
+  buildRenderPayload,
+  compileRenderFn,
+  createChartHost,
+  createMarkResolver,
+  geoFromCache,
+  loadGeo,
+  registerGeo,
+  resolveOptions
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/react.mjs

@@ -0,0 +1,97 @@
+/*! @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 {
+  buildRenderPayload,
+  createChartHost
+} from "./chunk-UNH36TGD.mjs";
+
+// src/react.tsx
+import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+var Ctx = createContext(null);
+function useBicSelection() {
+  const g = useContext(Ctx);
+  return {
+    rows: g?.selection.rows ?? [],
+    sourceId: g?.selection.sourceId ?? null,
+    clear: () => g?.clear()
+  };
+}
+function BicChartGroup({ rows, columns, geo, point, children }) {
+  const [sel, setSel] = useState({ sourceId: null, rows: [] });
+  const value = useMemo(() => ({
+    rows,
+    columns,
+    geo,
+    point,
+    selection: sel,
+    publish: (id, sourceRowIdxs) => setSel(sourceRowIdxs.length ? { sourceId: id, rows: sourceRowIdxs } : { sourceId: null, rows: [] }),
+    // A chart never filters itself — that is what keeps the gesture reversible:
+    // the origin chart still shows every mark, so there is always something left
+    // to click to change or clear the selection.
+    filterFor: (id) => sel.rows.length && sel.sourceId && sel.sourceId !== id ? sel.rows : null,
+    clear: () => setSel({ sourceId: null, rows: [] })
+  }), [rows, columns, geo, point, sel]);
+  return /* @__PURE__ */ jsx(Ctx.Provider, { value, children });
+}
+function payloadFor(g, sourceIdxs) {
+  const idxs = sourceIdxs ?? g.rows.map((_, i) => i);
+  const subset = idxs.map((i) => g.rows[i]);
+  const p = buildRenderPayload(g.columns, subset, g.geo ?? void 0, g.point ?? void 0);
+  return { payload: p, rowMap: idxs };
+}
+function BicChart(props) {
+  const { code, renderFn, options, d3, geoKind, id, filteredBy, onSelect, className, style } = props;
+  const ref = useRef(null);
+  const hostRef = useRef(null);
+  const rowMapRef = useRef(null);
+  const group = useContext(Ctx);
+  const active = group ? group.selection : null;
+  const filterSel = !group ? null : filteredBy ? active.sourceId === filteredBy ? group.filterFor(id) : null : group.filterFor(id);
+  const built = useMemo(() => {
+    if (!group) return null;
+    return payloadFor(group, filterSel);
+  }, [group, filterSel && filterSel.join(",")]);
+  const data = built ? built.payload : props.data;
+  rowMapRef.current = built ? built.rowMap : null;
+  const onSelectRef = useRef(onSelect);
+  onSelectRef.current = onSelect;
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el || !code && !renderFn || !data) return;
+    const host = createChartHost(el, { code, renderFn, data, options, d3, geoKind });
+    hostRef.current = host;
+    const off = host.selection.onChange((payloadIdxs, source) => {
+      if (source === "host") return;
+      const map = rowMapRef.current;
+      const sourceIdxs = map ? payloadIdxs.map((i) => map[i]).filter((i) => i !== void 0) : payloadIdxs;
+      if (group && id) group.publish(id, sourceIdxs);
+      onSelectRef.current?.(sourceIdxs);
+    });
+    host.render();
+    return () => {
+      off();
+      host.destroy();
+      hostRef.current = null;
+    };
+  }, [code, renderFn, d3, geoKind]);
+  const optKey = useMemo(() => JSON.stringify(options ?? {}), [options]);
+  useEffect(() => {
+    if (hostRef.current && options) hostRef.current.setOptions(options);
+  }, [optKey]);
+  useEffect(() => {
+    if (hostRef.current && data) hostRef.current.setData(data);
+  }, [data]);
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host || !group) return;
+    const mine = group.selection.sourceId === id && group.selection.rows.length > 0;
+    if (!mine && host.selection.current && host.selection.current.length) host.selection.clear();
+  }, [group?.selection, id, group]);
+  return /* @__PURE__ */ jsx("div", { ref, className, style });
+}
+export {
+  BicChart,
+  BicChartGroup,
+  useBicSelection
+};
+//# sourceMappingURL=react.mjs.map

package/dist/react.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/react.tsx"],
+  "sourcesContent": ["// React binding for @bicharts/chart-host \u2014 <BicChart> and <BicChartGroup>.\n//\n// This is ~150 lines that every consumer would otherwise write, and get subtly wrong in the\n// same four ways:\n//\n//   1. StrictMode double-mounts effects (React 19, dev). Without destroy() in cleanup an\n//      animated chart leaks a running timer per mount \u2014 on every hot reload.\n//   2. Prop changes must not RECOMPILE. `options` -> setOptions (live restyle), `data` ->\n//      setData; only new code/module tears down and rebuilds. A naive useEffect([deps])\n//      recompiles on every prop change and throws away animation state.\n//   3. d3 must be INJECTED. There is no global in a bundler app, so `d3` is a required prop.\n//   4. The chart OWNS its container's DOM. React must never render children into it.\n//\n// Cross-chart filtering lives in <BicChartGroup> for a reason that is not cosmetic: rowIdx\n// values are positions WITHIN THE PAYLOAD A CHART RECEIVED. Filter the rows for chart B and\n// its payload renumbers from zero, so the same integers now denote different records \u2014\n// silently. The group owns the source table, builds each chart's payload, keeps the\n// payload-row -> source-row map, and translates selections across it. Consumers never see it.\nimport { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from \"react\";\nimport type { ReactNode } from \"react\";\nimport { createChartHost, type ChartHost, type ChartHostConfig } from \"./host\";\nimport type { ResolveOptionsInput } from \"./defaults\";\nimport { buildRenderPayload, type GeoPointBinding } from \"./payload\";\n\nexport interface BicChartProps {\n    /** Generated render() source (an ES module's `code` export, or the raw string). */\n    code?: string;\n    /** Pre-compiled render function \u2014 the alternative to `code`. */\n    renderFn?: ChartHostConfig[\"renderFn\"];\n    /** The payload: { columns, rows, geoUnmatched?, geoPoint? } \u2014 MCP's data.sample.json verbatim. */\n    data?: ChartHostConfig[\"data\"];\n    /** Raw options; shared defaults/clamps are applied by resolveOptions. */\n    options?: ResolveOptionsInput;\n    /** REQUIRED: the d3 v7 namespace. There is no global in a bundled app. */\n    d3: any;\n    /** Attach the bundled geometry for this kind as options.geo (choropleth or basemap). */\n    geoKind?: string;\n    /** Identity within a <BicChartGroup> \u2014 the key other charts filter by. */\n    id?: string;\n    /** Take this group member's selection as a filter on THIS chart's rows. */\n    filteredBy?: string;\n    /** Selection callback in SOURCE row indices (group) or payload indices (standalone). */\n    onSelect?: (rowIdxs: number[]) => void;\n    className?: string;\n    style?: React.CSSProperties;\n}\n\n// \u2500\u2500 Group coordination \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// ONE active selection for the group, tagged with which chart produced it \u2014 the same\n// model every BI tool uses. Every OTHER chart filters to it; the originating chart does\n// not (it keeps showing all its marks, with the selected ones highlighted, so the user\n// can see what they picked in context and click again to change it). That single rule\n// gives mutual cross-filtering for free: click a bubble and the table filters, click a\n// table row and the map filters, with no possibility of a feedback loop.\ninterface GroupSelection { sourceId: string | null; rows: number[] }\ninterface GroupCtx {\n    /** Source rows as objects, shared by every member. */\n    rows: Record<string, any>[];\n    columns: any[];\n    geo?: { column: string; kind: string } | null;\n    point?: GeoPointBinding | null;\n    /** Publish a member's selection, already translated to SOURCE row indices. */\n    publish(id: string, sourceRowIdxs: number[]): void;\n    /** The filter `id` should APPLY (null = show everything). Never its own selection. */\n    filterFor(id: string | undefined): number[] | null;\n    /** The whole group's active selection, whoever produced it. */\n    selection: GroupSelection;\n    clear(): void;\n}\nconst Ctx = createContext<GroupCtx | null>(null);\n\n/** Read the group's selection from a page \u2014 for a \"clear\" button or a count. */\nexport function useBicSelection() {\n    const g = useContext(Ctx);\n    return {\n        rows: g?.selection.rows ?? [],\n        sourceId: g?.selection.sourceId ?? null,\n        clear: () => g?.clear(),\n    };\n}\n\nexport interface BicChartGroupProps {\n    /** The ONE source table. Every member's payload is derived from it. */\n    rows: Record<string, any>[];\n    columns: any[];\n    /** Choropleth join binding, applied when building each member's payload. */\n    geo?: { column: string; kind: string } | null;\n    /** Point-map geocoding binding (city/state/zip/lat/lon column names). */\n    point?: GeoPointBinding | null;\n    children: ReactNode;\n}\n\n/**\n * Owns the source table and the selection bus. Members declare `id` and optionally\n * `filteredBy`; the group re-derives the filtered member's payload and translates row\n * indices in both directions, so a click in one chart filters another CORRECTLY.\n */\nexport function BicChartGroup({ rows, columns, geo, point, children }: BicChartGroupProps) {\n    const [sel, setSel] = useState<GroupSelection>({ sourceId: null, rows: [] });\n    const value = useMemo<GroupCtx>(() => ({\n        rows, columns, geo, point,\n        selection: sel,\n        publish: (id, sourceRowIdxs) =>\n            setSel(sourceRowIdxs.length ? { sourceId: id, rows: sourceRowIdxs }\n                                        : { sourceId: null, rows: [] }),\n        // A chart never filters itself \u2014 that is what keeps the gesture reversible:\n        // the origin chart still shows every mark, so there is always something left\n        // to click to change or clear the selection.\n        filterFor: (id) => (sel.rows.length && sel.sourceId && sel.sourceId !== id) ? sel.rows : null,\n        clear: () => setSel({ sourceId: null, rows: [] }),\n    }), [rows, columns, geo, point, sel]);\n    return <Ctx.Provider value={value}>{children}</Ctx.Provider>;\n}\n\n/** Build a payload for a subset of source rows, keeping the payload->source index map. */\nfunction payloadFor(g: GroupCtx, sourceIdxs: number[] | null) {\n    const idxs = sourceIdxs ?? g.rows.map((_, i) => i);\n    const subset = idxs.map(i => g.rows[i]);\n    const p = buildRenderPayload(g.columns, subset, g.geo ?? undefined, g.point ?? undefined);\n    // p.rows[k] corresponds to source row idxs[k]. __rowIdx__ inside the payload was\n    // re-based to 0..n-1 by the builder \u2014 THIS map is what makes the indices comparable\n    // across charts, and it is exactly what a hand-rolled integration forgets.\n    return { payload: p, rowMap: idxs };\n}\n\nexport function BicChart(props: BicChartProps) {\n    const { code, renderFn, options, d3, geoKind, id, filteredBy, onSelect, className, style } = props;\n    const ref = useRef<HTMLDivElement | null>(null);\n    const hostRef = useRef<ChartHost | null>(null);\n    const rowMapRef = useRef<number[] | null>(null);\n    const group = useContext(Ctx);\n\n    // Resolve this chart's payload: from the group (filtered + mapped) or the raw prop.\n    // `filteredBy` narrows this to ONE partner when a page wants explicit one-way wiring;\n    // omit it and the chart responds to whichever sibling published \u2014 mutual by default.\n    const active = group ? group.selection : null;\n    const filterSel = !group ? null\n        : (filteredBy ? (active!.sourceId === filteredBy ? group.filterFor(id) : null)\n                      : group.filterFor(id));\n    const built = useMemo(() => {\n        if (!group) return null;\n        return payloadFor(group, filterSel);\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [group, filterSel && filterSel.join(\",\")]);\n    const data = built ? built.payload : props.data;\n    rowMapRef.current = built ? built.rowMap : null;\n\n    // Keep the newest callback without making it a rebuild trigger.\n    const onSelectRef = useRef(onSelect);\n    onSelectRef.current = onSelect;\n\n    // BUILD/TEARDOWN \u2014 only when the code identity changes. useLayoutEffect so the chart\n    // paints before the browser does, avoiding a flash of empty container.\n    useLayoutEffect(() => {\n        const el = ref.current;\n        if (!el || (!code && !renderFn) || !data) return;\n        const host = createChartHost(el, { code, renderFn, data, options, d3, geoKind });\n        hostRef.current = host;\n        const off = host.selection.onChange((payloadIdxs, source) => {\n            // \"host\" = a programmatic clear WE issued (below) to drop a stale highlight.\n            // Publishing it would overwrite the selection another chart just made \u2014 the\n            // feedback loop that makes mutual cross-filtering fight itself.\n            if (source === \"host\") return;\n            const map = rowMapRef.current;\n            // Translate to SOURCE indices before anything leaves this chart.\n            const sourceIdxs = map ? payloadIdxs.map(i => map[i]).filter(i => i !== undefined) : payloadIdxs;\n            if (group && id) group.publish(id, sourceIdxs);\n            onSelectRef.current?.(sourceIdxs);\n        });\n        host.render();\n        return () => {\n            // StrictMode double-mount and every unmount land here: stop the timer, drop the\n            // listeners, clear the DOM. Skipping this is the animated-chart leak.\n            off();\n            host.destroy();\n            hostRef.current = null;\n        };\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [code, renderFn, d3, geoKind]);\n\n    // LIVE RESTYLE \u2014 options change without recompiling (colour scale, aggregation,\n    // animMaxIdealFrames, maxMapPoints\u2026). This is the whole point of setOptions.\n    const optKey = useMemo(() => JSON.stringify(options ?? {}), [options]);\n    useEffect(() => {\n        if (hostRef.current && options) hostRef.current.setOptions(options);\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [optKey]);\n\n    // DATA change (including a cross-filter re-derive) \u2014 repaint, never recompile.\n    useEffect(() => {\n        if (hostRef.current && data) hostRef.current.setData(data);\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [data]);\n\n    // Drop a STALE highlight: once the group's selection belongs to someone else (or was\n    // cleared), this chart must stop showing its own marks as selected. Without it a\n    // \"Clear\" button empties the filter while the origin chart stays visibly dimmed.\n    useEffect(() => {\n        const host = hostRef.current;\n        if (!host || !group) return;\n        const mine = group.selection.sourceId === id && group.selection.rows.length > 0;\n        if (!mine && host.selection.current && host.selection.current.length) host.selection.clear();\n    }, [group?.selection, id, group]);\n\n    // No children: the chart owns this element's contents.\n    return <div ref={ref} className={className} style={style} />;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/types/contract.d.ts

@@ -0,0 +1,69 @@
+export declare const HOST_CONTRACT_VERSION = "1.0.0";
+export type GeoPointPrecision = "latlon" | "city" | "zip3" | "state";
+/** Every valid tier, ordered most precise → coarsest. Runtime form of GeoPointPrecision. */
+export declare const GEO_POINT_PRECISIONS: readonly GeoPointPrecision[];
+export declare const MARK_CLASS = "d3-mark";
+export declare const LEGEND_MARK_CLASS = "d3-legend-mark";
+export declare const AXIS_FILTER_CLASS = "d3-axis-filter";
+export declare const ROW_IDX_ATTR = "data-row-idx";
+export declare const XFILTER_REFRESH_EVENT = "llm-xfilter-refresh";
+export declare const CONTAINER_SLOT_ANIM_STOP = "__llmAnimStop";
+export declare const CONTAINER_SLOT_XF_CLEAR = "__llmXfClear";
+export declare const CONTAINER_SLOT_INITIAL_XF_MARK = "__llmInitialXfMark";
+export declare const HOST_CONTAINER_CLASS = "bic-chart-host";
+export declare const SELECTION_ACTIVE_CLASS = "lch-has-selection";
+export declare const MARK_SELECTED_CLASS = "lch-mark-selected";
+export declare const DIM_OPACITY_VAR = "--lch-dim-opacity";
+export declare const DIM_OPACITY_DEFAULT = 0.25;
+export declare const ANIM_PLAY_SPEED_DEFAULT = 1000;
+export declare const ANIM_PLAY_SPEED_MIN = 250;
+export declare const ANIM_PLAY_SPEED_MAX = 5000;
+export declare const ANIM_MAX_IDEAL_FRAMES_DEFAULT = 60;
+export declare const ANIM_MAX_IDEAL_FRAMES_MIN = 3;
+export declare const ANIM_MAX_IDEAL_FRAMES_MAX = 500;
+export declare const COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT = 95;
+export declare const COLOR_SCALE_SELF_CLAMP_PCT_MIN = 50;
+export declare const COLOR_SCALE_SELF_CLAMP_PCT_MAX = 100;
+export type TimelineStyle = "" | "line" | "boxes";
+export type ColorScaleScope = "" | "frame" | "self";
+export interface RenderOptions {
+    width: number;
+    height: number;
+    palette: string[];
+    geoUnmatched?: {
+        count: number;
+        examples: string[];
+    } | null;
+    geo?: any;
+    geoPoint?: {
+        precision: GeoPointPrecision | null;
+        unplaced: number;
+        unplacedExamples: string[];
+        ambiguousRows: number;
+    } | null;
+    maxMapPoints?: number;
+    colorScaleLow?: string;
+    colorScaleHigh?: string;
+    colorScaleScope?: ColorScaleScope;
+    colorScaleSelfClampPct?: number;
+    geoLandColor?: string;
+    geoNoDataColor?: string;
+    aggregation?: string;
+    uiState?: unknown;
+    setUiState?: (s: unknown) => void;
+    backgroundColor?: string;
+    themeBg?: string;
+    themeFg?: string;
+    isHighContrast?: boolean;
+    themeAccent?: string;
+    cultureCode?: string;
+    allowTooltips?: boolean;
+    noDataText?: string;
+    animAutoPlay?: boolean;
+    animPlaySpeedMs?: number;
+    animMaxIdealFrames?: number;
+    animStopAtEnd?: boolean;
+    filtersDuringPlay?: boolean;
+    animTimelineStyle?: TimelineStyle;
+    onSelect?: (rowIdxs: number[]) => void;
+}

package/dist/types/defaults.d.ts

@@ -0,0 +1,5 @@
+import { type RenderOptions } from "./contract";
+export type ResolveOptionsInput = {
+    [K in keyof RenderOptions]?: any;
+};
+export declare function resolveOptions(p: ResolveOptionsInput): RenderOptions;

package/dist/types/geo.d.ts

@@ -0,0 +1,3 @@
+import { NA_ISO3 } from "./geoNaRegions";
+export declare function geoForKind(geoKind: string | null | undefined): any | undefined;
+export { NA_ISO3 };

package/dist/types/geoLazy.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Load (and cache) the geometry for a geoKind. Per-asset dynamic import: requesting a US
+ * state map never downloads the 810 KB zip3 asset. Resolves to undefined for an unknown
+ * kind — callers treat that exactly like "no geometry", same as the sync path.
+ */
+export declare function loadGeo(geoKind: string | null | undefined): Promise<any | undefined>;
+/** Synchronous cache read — what createChartHost uses, so render() stays sync. Returns
+ *  undefined until loadGeo() has resolved for this kind (or a provider supplied it). */
+export declare function geoFromCache(geoKind: string | null | undefined): any | undefined;
+/** Seed the cache from geometry the caller already holds — e.g. the MCP's data.geo.json,
+ *  or the sync geoForKind from the "@bicharts/chart-host/geo" subpath. */
+export declare function registerGeo(geoKind: string, geo: any): void;

package/dist/types/geoNaRegions.d.ts

@@ -0,0 +1,3 @@
+export declare const NA_ISO3: Set<string>;
+export declare const NA_LAT_MAX = 75;
+export declare function clipFeatureToLat(feature: any, latMax: number): any | null;

package/dist/types/geoUsStates.generated.d.ts

@@ -0,0 +1 @@
+export declare const US_STATES: any;

package/dist/types/geoUsZip3.generated.d.ts

@@ -0,0 +1 @@
+export declare const US_ZIP3: any;

package/dist/types/geoWorld110m.generated.d.ts

@@ -0,0 +1 @@
+export declare const WORLD_110M: any;

package/dist/types/host.d.ts

@@ -0,0 +1,61 @@
+import { type RenderOptions } from "./contract";
+import { type ResolveOptionsInput } from "./defaults";
+export type RenderFn = (container: HTMLElement, data: any, options: RenderOptions) => void;
+export interface ChartHostConfig {
+    data: {
+        columns: any[];
+        rows: any[][];
+        geoUnmatched?: {
+            count: number;
+            examples: string[];
+        };
+        geoPoint?: RenderOptions["geoPoint"];
+        /** Provenance the MCP stamps into data.sample.json. `hostContract` is checked
+         *  against HOST_CONTRACT_VERSION so a major-version drift is LOUD, not silent. */
+        meta?: {
+            hostContract?: string;
+            chart?: string;
+        };
+    };
+    /** Generated render() source — compiled exactly like the visual/preview/exec-gate. */
+    code?: string;
+    /** Pre-compiled alternative to `code`. */
+    renderFn?: RenderFn;
+    /** Partial raw options; resolveOptions applies the shared defaults/clamps. */
+    options?: ResolveOptionsInput;
+    /** D3 v7 instance handed to the compiled code. Default: (globalThis as any).d3. */
+    d3?: any;
+    /** Attach geometry for this geoKind as options.geo (choropleths / basemaps). Resolved
+     *  from `geoProvider` or the geoLazy cache — see `loadGeo`. NOT eagerly bundled. */
+    geoKind?: string;
+    /** Supply geometry for a geoKind synchronously. The escape hatch for a host that
+     *  already holds its assets (e.g. `geoForKind` from "@bicharts/chart-host/geo", or the
+     *  data.geo.json the MCP wrote next to the chart). */
+    geoProvider?: (geoKind: string) => any | undefined;
+}
+export interface ChartHost {
+    render(): void;
+    /** Merge raw option changes and re-render — the live-restyle path (colour scale,
+     *  aggregation, animMaxIdealFrames, timeline style…). Never a regeneration. */
+    setOptions(partial: ResolveOptionsInput): void;
+    setData(data: ChartHostConfig["data"]): void;
+    readonly options: RenderOptions;
+    selection: {
+        /** Subscribe to cross-filter changes (mark clicks + the chart's own
+         *  llm-xfilter-refresh dispatches). rowIdxs = [] means cleared. */
+        onChange(cb: (rowIdxs: number[], source: string) => void): () => void;
+        /** Clear the chart's own selection (calls __llmXfClear when the chart set it). */
+        clear(): void;
+        readonly current: number[] | null;
+    };
+    animation: {
+        /** Stop playback (calls __llmAnimStop when set). Call before unmount. */
+        stop(): void;
+    };
+    /** The mark the chart nominated as its initial filter (__llmInitialXfMark), if any. */
+    initialMark(): Element | null;
+    destroy(): void;
+}
+export declare function explainRenderFailure(err: unknown, d3: any): unknown;
+export declare function compileRenderFn(code: string, win: any, doc: any, d3: any): RenderFn;
+export declare function createChartHost(container: HTMLElement, config: ChartHostConfig): ChartHost;

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./contract";
+export { resolveOptions, type ResolveOptionsInput } from "./defaults";
+export { loadGeo, geoFromCache, registerGeo } from "./geoLazy";
+export { buildRenderPayload, type RenderPayload, type GeoPointBinding } from "./payload";
+export { createChartHost, compileRenderFn, type ChartHost, type ChartHostConfig, type RenderFn } from "./host";
+export { createMarkResolver, type MarkResolver, type MarkResolverEnv } from "./selection";

package/dist/types/payload.d.ts

@@ -0,0 +1,31 @@
+import type { GeoPointPrecision } from "./contract";
+/** Which columns hold the place parts a coordinate can be resolved from. Any subset;
+ *  the cascade uses the most precise tier available per row. */
+export interface GeoPointBinding {
+    city?: string;
+    state?: string;
+    zip?: string;
+    lat?: string;
+    lon?: string;
+}
+export interface RenderPayload {
+    columns: any[];
+    rows: any[][];
+    geoUnmatched?: {
+        count: number;
+        examples: string[];
+    };
+    geoUnmatchedDistinct?: number;
+    geoPoint?: {
+        precision: GeoPointPrecision | null;
+        unplaced: number;
+        unplacedExamples: string[];
+        ambiguousRows: number;
+    };
+}
+export declare function buildRenderPayload(cols: Array<{
+    name: string;
+} & Record<string, any>>, rowObjs: Array<Record<string, any>>, geo?: {
+    column: string;
+    kind: string;
+} | null, point?: GeoPointBinding | null): RenderPayload;

package/dist/types/react.d.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from "react";
+import { type ChartHostConfig } from "./host";
+import type { ResolveOptionsInput } from "./defaults";
+import { type GeoPointBinding } from "./payload";
+export interface BicChartProps {
+    /** Generated render() source (an ES module's `code` export, or the raw string). */
+    code?: string;
+    /** Pre-compiled render function — the alternative to `code`. */
+    renderFn?: ChartHostConfig["renderFn"];
+    /** The payload: { columns, rows, geoUnmatched?, geoPoint? } — MCP's data.sample.json verbatim. */
+    data?: ChartHostConfig["data"];
+    /** Raw options; shared defaults/clamps are applied by resolveOptions. */
+    options?: ResolveOptionsInput;
+    /** REQUIRED: the d3 v7 namespace. There is no global in a bundled app. */
+    d3: any;
+    /** Attach the bundled geometry for this kind as options.geo (choropleth or basemap). */
+    geoKind?: string;
+    /** Identity within a <BicChartGroup> — the key other charts filter by. */
+    id?: string;
+    /** Take this group member's selection as a filter on THIS chart's rows. */
+    filteredBy?: string;
+    /** Selection callback in SOURCE row indices (group) or payload indices (standalone). */
+    onSelect?: (rowIdxs: number[]) => void;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/** Read the group's selection from a page — for a "clear" button or a count. */
+export declare function useBicSelection(): {
+    rows: number[];
+    sourceId: string;
+    clear: () => void;
+};
+export interface BicChartGroupProps {
+    /** The ONE source table. Every member's payload is derived from it. */
+    rows: Record<string, any>[];
+    columns: any[];
+    /** Choropleth join binding, applied when building each member's payload. */
+    geo?: {
+        column: string;
+        kind: string;
+    } | null;
+    /** Point-map geocoding binding (city/state/zip/lat/lon column names). */
+    point?: GeoPointBinding | null;
+    children: ReactNode;
+}
+/**
+ * Owns the source table and the selection bus. Members declare `id` and optionally
+ * `filteredBy`; the group re-derives the filtered member's payload and translates row
+ * indices in both directions, so a click in one chart filters another CORRECTLY.
+ */
+export declare function BicChartGroup({ rows, columns, geo, point, children }: BicChartGroupProps): import("react").JSX.Element;
+export declare function BicChart(props: BicChartProps): import("react").JSX.Element;

package/dist/types/selection.d.ts

@@ -0,0 +1,15 @@
+export interface MarkResolverEnv {
+    root: HTMLElement;
+    doc: Document;
+    log: (tag: string, data: object) => void;
+}
+export interface MarkResolver {
+    isInvisibleStrokePath(el: Element): boolean;
+    distToPathCenterline(el: SVGPathElement, x: number, y: number): number;
+    refineHitCorridor(mark: HTMLElement | null, x: number, y: number, sel: string): HTMLElement | null;
+    findMark(target: EventTarget | null, sel?: string, ev?: MouseEvent): HTMLElement | null;
+    rowIdxsFromMark(el: Element | null): number[];
+    penetrateOverlayAt(x: number, y: number, sel: string): HTMLElement | null;
+    resolveByGeometry(x: number, y: number, sel: string): HTMLElement | null;
+}
+export declare function createMarkResolver(env: MarkResolverEnv): MarkResolver;