@bicharts/chart-mcp 0.6.90 → 0.6.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-mcp",
-  "version": "0.6.90",
+  "version": "0.6.92",
   "description": "MCP (Model Context Protocol) stdio server for BIC AI charts: profile a dataset locally, then generate chart code that has passed the BIC backend's render gates. Works with any MCP-capable client (Claude Code, Claude Desktop, Cursor, Copilot Studio). An account pays to author charts; the code it writes is yours and runs with no licence.",
   "keywords": [
     "mcp",
@@ -47,8 +47,8 @@
   },
   "// dependencies": "NONE, deliberately. dist/ bundles every module the server uses, so a runtime dependency installs nothing it needs - it only makes npx fetch that package (and its tree) before the first start. Everything the bundle carries is a devDependency; scripts/verify-package.mjs fails the release if a dependency appears or a shipped file imports anything but Node's built-ins.",
   "devDependencies": {
-    "@bicharts/chart-host": "^0.6.90",
-    "@bicharts/shape-core": "^0.6.90",
+    "@bicharts/chart-host": "^0.6.92",
+    "@bicharts/shape-core": "^0.6.92",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@types/node": "^20.0.0",
     "@types/papaparse": "^5.3.14",

package/skills/bic-charts/CHART-SHAPES.md

@@ -33,6 +33,7 @@ on the same picture, not a looser one.
 | Bivariate World Choropleth | 1 categorical, 2 continuous, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 400x300 px | D3 | Best for two country-level measures that might disagree: wealth vs inequality, revenue vs margin, cases vs deaths - at least 24 countries and two measures that do not simply track each other |
 | Box plot | 1 continuous | needs 460x340 px | D3, Matplotlib, Plotly, Seaborn | Requires one continuous variable (plus optional category) |
 | Bubble chart | 3 continuous | needs 520x380 px | D3, Matplotlib, Plotly, Seaborn | Three continuous variables (x, y, size); one mark per row on continuous axes. If you want both axes grouped into bands with one aggregated bubble per cell, pick Binned bubble matrix instead |
+| Budget allocator | 1 categorical, 2 continuous | needs 560x380 px | D3 | One spend measure and one outcome by channel and period - monthly spend and signups for five marketing channels, budget and sales by region - with at least eight periods per channel |
 | Bullet chart | 1 continuous, a reference value | needs 220x120 px | D3, PLOTLY | Best for actual-vs-target KPIs with thresholds (revenue vs goal, SLA vs target) — a denser, clearer replacement for gauges |
 | Bump chart | 1 categorical, 1 continuous, 3+ time points | <=15 categories, needs 320x280 px | D3, PLOTLY | Best for leaderboard/position dynamics: how a handful of regions, products, or teams change rank quarter to quarter |
 | Calendar heatmap | 1 continuous, 60+ time points | needs 600x420 px | D3, Matplotlib, Plotly, Seaborn | Requires daily datetime data with associated numeric values; best for activity/contribution tracking over time |
@@ -46,6 +47,7 @@ on the same picture, not a looser one.
 | Clustered heatmap | 2 categorical, 1 continuous | <=50 categories, needs 320x320 px | Plotly | Requires two variables for matrix values |
 | Connected scatterplot | 2 continuous, 6+ time points | needs 300x300 px | D3, PLOTLY | Best for the joint trajectory of two related metrics over time (e.g. units vs revenue, unemployment vs inflation) where the path shape is the insight |
 | Custom small multiples | 1 categorical, 1 continuous | <=16 categories, needs 320x240 px | D3, Matplotlib, Plotly, Seaborn | Best when comparing patterns across categories |
+| Cutoff tuner | 1 continuous | needs 560x360 px | D3 | One row per case with a model score or rating and the actual yes/no outcome - churn, fraud, default, conversion - when the question is where to draw the line and what each choice costs |
 | Cycle plot | 1 continuous, 24+ time points | needs 320x280 px | D3, PLOTLY | Best for multi-year monthly/quarterly/weekly data where the question is seasonality vs trend ('is Q4 always highest, and is each Q4 growing?') |
 | Delta KPI | 2 continuous | needs 200x120 px | D3 | Two comparable measures, or one measure at two points in time - this period against last, actual against plan, after against before |
 | Dendrogram (tree diagram) | 2 categorical, 1 continuous | <=60 leaves, needs 320x240 px | D3, Plotly | Best for 2-4 hierarchy levels with ≤ ~80 leaves |

package/skills/bic-charts/SKILL.md

@@ -42,7 +42,7 @@ those which defaulted, paying attention to credit score"* wants `LoanId`, `Defau
 `CreditScore`, filtered to six months.
 
 **A highlight is a COLUMN, not a styling note.** "Highlighting those which defaulted" means
-`Defaulted` travels as its own categorical column. There is no instruction channel that can colour
+`Defaulted` travels as its own categorical column. There is no instruction channel that can color
 rows the data does not distinguish.
 
 **GRAIN is a choice, and the default is usually wrong for these charts.** Almost every BI query
@@ -59,7 +59,7 @@ question, and nothing downstream will flag it. Ask yourself which you meant:
 
 **Aim with `CHART-SHAPES.md`** (beside this file). It lists every chart the engine can build and
 what each one needs — minimum columns by role, category ceilings, draw caps, viewport floors,
-which renderers can draw it. It is GENERATED from the chart catalogue, so it cannot drift from what
+which renderers can draw it. It is GENERATED from the chart catalog, so it cannot drift from what
 the engine will actually accept. Read the LIMITS column carefully: **the units differ** — a sankey
 is capped on EDGES and a chord on NODES, so `<=80 edges` is the tighter constraint on the same
 picture, not the looser one.
@@ -118,7 +118,7 @@ npm install -D esbuild
   `npm init -y` line again before retrying.
 - **`global.json`** pins the build to the newest installed .NET 10 SDK. Without it a machine that
   also has a newer or preview SDK builds with that one.
-- These blocks are written against `@bicharts/chart-host` 0.6.33 or later; every name they import
+- These blocks are written against `@bicharts/chart-host` 0.6.86 or later; every name they import
   is exported there.
 - npm 11 may warn that esbuild's postinstall is "not yet covered by allowScripts". The build doesn't
   need it: esbuild's platform binary arrives as an ordinary dependency, and the bundling target runs.
@@ -169,7 +169,7 @@ correction:
 | Parameter | Use it when |
 | --- | --- |
 | `rows_policy: "all"` | every source row must appear — a row-per-entity table, a point per location. Without it the engine may legitimately show a Top-N with an "Other" rollup. |
-| `required_columns: [...]` | a field must be visible because your app's interactions depend on it (e.g. the column you colour or filter by). |
+| `required_columns: [...]` | a field must be visible because your app's interactions depend on it (e.g. the column you color or filter by). |
 | `forbid_derived_columns: true` | your app owns the analytics; the chart is only the display. Stops per-capita / share-of-total / rank columns being added. |
 
 Asking for these in `prompt` prose instead is the most expensive mistake available here: it
@@ -189,7 +189,7 @@ engine picked, what was dropped), for a client that shows only the text. `engine
 the server reported what it picked; when it is `unavailable` the engine may have picked where a row
 reads `default`, so never tell the user it picked nothing. Most settings are
 passed only when the user has said them in their own words: a title, data labels, a legend position,
-a limit, a date grain, an overlay, a font. A few are worth one question when they matter and the user
+a limit, a date grain, an overlay, a font. Three are worth one question whenever the user
 hasn't said: `chart_style` (which family of charts to consider: the familiar forms or the other types), `level_of_detail` (how much of
 the data they want to see: every observation, a distribution, or one mark per category) and
 `culture` (their language and region), and, once the chart is drawn, the live options
@@ -226,10 +226,13 @@ Import the generated code as raw text and the sample payload as JSON:
 ```tsx
 import * as d3 from "d3";
 import { BicChart, BicChartGroup } from "@bicharts/chart-host/react";
+import { createLegendFitPass } from "@bicharts/chart-host/legend-fit";   // chart-host 0.6.86 or later
 import mapCode from "./charts/map/chart.js?raw";
 import tableCode from "./charts/table/chart.js?raw";
 import payload from "./charts/map/data.sample.json";
 
+const LAYOUT_PASS = createLegendFitPass();   // once, at module scope: a new function on each render rebuilds the host
+
 // data.sample.json rows are POSITIONAL arrays; the group wants row OBJECTS.
 const columns = payload.columns;
 const rows = payload.rows.map(r =>
@@ -240,8 +243,8 @@ const rows = payload.rows.map(r =>
 
 ```tsx
 <BicChartGroup columns={columns} rows={rows} point={{ city: "City", state: "StateOrProvince" }}>
-  <BicChart id="map"   code={mapCode}   d3={d3} geoKind="north-america" respondsWith="highlight" />
-  <BicChart id="table" code={tableCode} d3={d3} />
+  <BicChart id="map"   code={mapCode}   d3={d3} geoKind="north-america" respondsWith="highlight" layoutPass={LAYOUT_PASS} />
+  <BicChart id="table" code={tableCode} d3={d3} layoutPass={LAYOUT_PASS} />
 </BicChartGroup>
 ```
 
@@ -277,9 +280,10 @@ Ctrl/Cmd/Shift-click adds or removes one mark, and a click on empty canvas clear
 ```js
 import * as d3base from "d3";
 import { assembleD3, createChartGroup, createChartHost, loadGeo } from "@bicharts/chart-host";
+import { createLegendFitPass } from "@bicharts/chart-host/legend-fit";
 
 const d3 = assembleD3(d3base);                           // + any plugins a chart's contract names
-const at = (path) => new URL(path, document.baseURI);   // honours <base href> on a sub-path host
+const at = (path) => new URL(path, document.baseURI);   // honors <base href> on a sub-path host
 async function text(path) {
     const r = await fetch(at(path));
     if (!r.ok) throw new Error(`${path}: HTTP ${r.status}`);
@@ -310,14 +314,21 @@ export async function createGroup(sampleUrl, dotnet) {
     const group = createChartGroup(cols, rows);
     const off = group.onChange(sel => dotnet.invokeMethodAsync("OnSelectionChanged", sel.sourceId, [...sel.rows]));
     return {
-        async mount(el, spec) {                          // spec: { id, dir, height, respondsWith, geoKind }
+        async mount(el, spec) {                          // spec: { id, dir, height, respondsWith, geoKind, lasso }
             const code = await text(`${spec.dir}/chart.js`);   // TEXT: chart-host compiles it and injects d3
             if (spec.geoKind) await loadGeo(spec.geoKind);     // BEFORE the first render: render() is synchronous
             const opts = spec.respondsWith ? { respondsWith: spec.respondsWith } : {};
+            // The host lasso, for a chart whose generate_chart result carries capabilities.lasso (spec.lasso): a drag around
+            // marks selects the ones inside, through the group's own selection, so there is no handler to write. `capable` is
+            // the server's word for this chart; without it there is no lasso.
+            const lasso = spec.lasso
+                ? { capable: true, enabled: true, ...(spec.lasso.rowCap > 0 ? { rowCap: spec.lasso.rowCap } : {}) }
+                : null;
             const host = createChartHost(el, {
                 code, d3, geoKind: spec.geoKind || undefined,
                 data: group.memberPayload(spec.id, opts).payload,
-                options: { width: Math.floor(el.getBoundingClientRect().width), height: spec.height, ...theme(el) },
+                options: { width: Math.floor(el.getBoundingClientRect().width), height: spec.height, ...theme(el), ...(lasso ? { lasso } : {}) },
+                layoutPass: createLegendFitPass(),             // after every render: a legend slid clear of the plot, text brought inside the frame
             });
             host.render();
             const member = group.attach(spec.id, host, opts);  // its clicks publish SOURCE rows
@@ -423,6 +434,10 @@ export async function createGroup(sampleUrl, dotnet) {
     [Parameter] public string? RespondsWith { get; set; }
     /// <summary>A map's geo.kind from the generate_chart result (e.g. "us-state-name").</summary>
     [Parameter] public string? GeoKind { get; set; }
+    /// <summary>True when the generate_chart result carries capabilities.lasso: a drag around marks selects the ones inside.</summary>
+    [Parameter] public bool Lasso { get; set; }
+    /// <summary>capabilities.lasso.rowCap from the same result, when it gives one: the most rows in view that still get a lasso.</summary>
+    [Parameter] public int? LassoRowCap { get; set; }
 
     ElementReference el;
     IJSObjectReference? chart;
@@ -432,7 +447,8 @@ export async function createGroup(sampleUrl, dotnet) {
         if (!firstRender) return;
         var group = await Group.Ready;
         chart = await group.InvokeAsync<IJSObjectReference>("mount", el,
-            new { id = Id, dir = Dir, height = Height, respondsWith = RespondsWith, geoKind = GeoKind });
+            new { id = Id, dir = Dir, height = Height, respondsWith = RespondsWith, geoKind = GeoKind,
+                  lasso = Lasso ? new { rowCap = LassoRowCap } : null });
     }
 
     /// <summary>A live restyle: merged into the chart's options and repainted.</summary>
@@ -475,7 +491,7 @@ Add `@using MyCharts.Components` to `_Imports.razor`, then on a page:
   the tool resolved.
 - **Restyle** - a chart honours only the options its code reads, so a live restyle control has to
   set one of those. The generate result's `optionsRead` lists them for that chart, and its
-  `integrationContract` says what each does. The common ones: `palette` (a categorical colour
+  `integrationContract` says what each does. The common ones: `palette` (a categorical color
   list), `colorScaleLow`/`colorScaleHigh` (a sequential ramp's ends, what a choropleth reads),
   `maxMapPoints` (a point map's cap). An option not in `optionsRead` does nothing on that chart.
 - **Hover drop lines** - a 3D scatter can draw, on hover, a line from a point to each back wall of
@@ -485,6 +501,9 @@ Add `@using MyCharts.Components` to `_Imports.razor`, then on a page:
   `dropLines` says which applies: `ask` carries the question, `on`/`off` means the user already
   answered (the client asked them) and the generated component applies it. Keep the answer when
   the chart is regenerated; never ask again.
+- **Lasso** - when the result's `capabilities.lasso` is present, pass `Lasso="true"` (and `LassoRowCap` with its
+  `rowCap`): a drag around marks then selects the ones inside through the group's own selection, with no handler to
+  write. A chart whose result has none takes neither parameter and has no lasso.
 - **GeoKind** - the result's `geo.kind` (the text reply's `Geo:` line). Without it a map draws
   its marks over no land. `loadGeo` takes that geometry from chart-host itself, so the
   `data.geo.json` the tool also writes beside a map is the same shapes as a file: the page never
@@ -498,7 +517,7 @@ Add `@using MyCharts.Components` to `_Imports.razor`, then on a page:
   `.bic-chart` its width in CSS (a block element in a sized column); the height is the
   `Height` parameter. A `display:none` container measures 0 and draws nothing.
 - **Light and dark** - `theme(el)` reads the background the chart sits on, so the chart follows the
-  PAGE. For a page that follows the reader, switch the page's own colours in CSS
+  PAGE. For a page that follows the reader, switch the page's own colors in CSS
   (`@media (prefers-color-scheme: dark) { ... }` on `body` or the chart's card) and the charts follow
   on the next `change` of the media query.
 
@@ -559,7 +578,7 @@ chart's grain.
 **4. Ask before choosing, then choose what answers the question.** `list_eligible_charts` on that
 data. Pass `chart_type` to `generate_chart` only for a type the person named; when they only asked for a chart, leave it
 unset and the engine chooses from what fits. A type the person described without naming it counts as named once you have
-matched it to the catalogue. The catalogue goes past the template's own charts, and these are the ones people describe
+matched it to the catalog. The catalog goes past the template's own charts, and these are the ones people describe
 without naming:
 
 | the request sounds like | ask for |
@@ -581,7 +600,7 @@ slider sets the rate anyway.
 queries at run time (`useSemanticModelQuery`), so the payload is rebuilt from live rows every time -
 never hand-built. **With `out_dir`, a D3 chart arrives with `chart.component.tsx` beside `chart.js`: a component that
 already does all of this** - the columns, the binding (`geo`, `point`, `destination`), the geometry kind, the
-d3 plugins the chart calls, and `rowsFromTable`, which maps a DAX result's `Table[Column]` and `[Measure]`
+d3 plugins the chart calls, the host's legend and frame fit (`layoutPass`), and `rowsFromTable`, which maps a DAX result's `Table[Column]` and `[Measure]`
 headers onto the chart's plain names. Use it as it is:
 
 ```tsx
@@ -608,6 +627,7 @@ host by hand instead - `generate_chart` returns `binding`; pass all three:
 ```tsx
 import * as d3 from "d3";
 import { BicChart, BicChartGroup } from "@bicharts/chart-host/react";
+import { createLegendFitPass } from "@bicharts/chart-host/legend-fit";
 import code from "@/charts/occupancy-map/chart.js?raw";
 // Saved from the generate_chart result: columns = data.columns, binding = binding, geoKind = geo.kind.
 import { columns, binding, geoKind } from "@/charts/occupancy-map/meta";
@@ -616,6 +636,8 @@ import { columns, binding, geoKind } from "@/charts/occupancy-map/meta";
 const RENAME = { "Geography[CountryIso3]": "CountryIso3", "Geography[CountryName]": "CountryName",
                  "[Average Daily Rate]": "AverageDailyRate", "[Occupancy %]": "Occupancy" };
 
+const LAYOUT_PASS = createLegendFitPass();        // once, at module scope: a new function on each render rebuilds the host
+
 function CountryMap({ table, onPick }) {          // table = the live query result
   const rows = table.rows.map(r => Object.fromEntries(
     table.columns.map((c, i) => [RENAME[c.name] ?? c.name, r[i]])));
@@ -623,7 +645,7 @@ function CountryMap({ table, onPick }) {          // table = the live query resu
     <BicChartGroup columns={columns} rows={rows}
                    geo={binding.geo} point={binding.point} destination={binding.destination}>
       <BicChart id="map" code={code} d3={d3} geoKind={geoKind}
-                options={{ width, height }}
+                options={{ width, height }} layoutPass={LAYOUT_PASS}
                 onSelect={idxs => onPick(idxs.length ? rows[idxs[0]].CountryIso3 : null)} />
     </BicChartGroup>
   );
@@ -636,6 +658,14 @@ function CountryMap({ table, onPick }) {          // table = the live query resu
   basemap but no join, so its `binding.geo` is null.
 - **`<BicChartGroup destination>` needs `@bicharts/chart-host` 0.6.50 or later.** Before it, a flow
   map's far end is not built.
+- **`LAYOUT_PASS` is built once, at module scope, and needs `@bicharts/chart-host` 0.6.86 or later.** After
+  every render it slides a legend clear of the plot and brings text that runs past the frame back inside; the
+  chart component `generate_chart` writes does the same, and a new function on each render would rebuild the host.
+- **The result's `capabilities.lasso` means the chart takes chart-host's lasso (`@bicharts/chart-host` 0.6.84 or later).**
+  Pass `lasso: { capable: true, enabled: true }` in that chart's `options` (add `rowCap` when the result gives one), and a
+  drag around marks selects the ones inside through the same `onSelect` / `selects` a click uses: the gesture and the
+  selection are the host's, so there is no handler to write. The component `generate_chart` writes passes it already.
+  Without `capabilities.lasso` the chart has no lasso, and `lasso: { enabled: false }` turns it off.
 
 **Layout: a chart is never clipped or squashed.** Charts sit in cards, and a card is where they get cut off.
 - Render every chart inside `BicChartPanel`. It sizes the chart from its cell, never from the chart.
@@ -708,7 +738,7 @@ Anything saved against a mark - a note, a flag - is keyed the same way, never by
 More the page gets from the same filters, each one line:
 - A link that opens the page as it was: `useBicUrlState()` in the page component (after its `useBicFilter` /
   `useBicControls` calls) keeps every filter and every chart's controls in `?view=`. `useBicView()` gives `save()` /
-  `restore(view)` for a saved view of your own (a user's favourite), and `token()` for a link.
+  `restore(view)` for a saved view of your own (a user's favorite), and `token()` for a link.
 - Linked hover: `useBicFilter("CountryIso3", { hover: true })` - hovering a mark lights the same key's marks on every
   chart bound to that filter (a glow, never a selection).
 - A filter that narrows a query to nothing: `<BicChartPanel ... onClearFilters={country.clear}>` says so with a Clear,
@@ -835,7 +865,7 @@ chart in a `BicChartPanel`), draws every chart together, and compares the stack
 the line and the call to use instead; fix the ERRORs in the app's own files before deploying.
 You don't need to deploy to check a chart. The template's `validate:visual` checks `VegaVisual` factories; a
 RegiaBI chart's check is `check_chart` - don't list it there. `check_chart` and `check_app` check the charts and how
-the app uses them; the template's app-validation in the portal embed still applies. Then `npx tsc -b` and the tests. To test the page's behaviour,
+the app uses them; the template's app-validation in the portal embed still applies. Then `npx tsc -b` and the tests. To test the page's behavior,
 `@bicharts/chart-host/testing` has a reader's gestures - `clickMark`, `clickEmpty`, `selectedRows` - for the checks
 worth keeping: a second click on a mark clears its filter, and a page Clear clears the chart's marks. Deploying (`npx rayfin up`), on Rayfin 1.36.1:
 - Signed in? `npx rayfin login status` (a subcommand, not a `--status` flag); `npx rayfin login` if not.