diff --git a/.github/extensions/flint-chart/.mcp.json b/.github/extensions/flint-chart/.mcp.json index a87666b6..3137998f 100644 --- a/.github/extensions/flint-chart/.mcp.json +++ b/.github/extensions/flint-chart/.mcp.json @@ -4,7 +4,7 @@ "command": "npx", "args": [ "--yes", - "flint-chart-mcp@1.0.0" + "flint-chart-mcp@1.0.1" ], "cwd": "${PLUGIN_ROOT}" } diff --git a/.github/extensions/flint-chart/.plugin/plugin.json b/.github/extensions/flint-chart/.plugin/plugin.json index 0ec6cb07..befee487 100644 --- a/.github/extensions/flint-chart/.plugin/plugin.json +++ b/.github/extensions/flint-chart/.plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "flint-chart", "description": "Flint chart authoring MCP, skill, and native interactive chart canvas for Copilot CLI.", - "version": "1.0.0", + "version": "1.0.1", "author": { "name": "Microsoft", "url": "https://github.com/microsoft/flint-chart" diff --git a/.github/extensions/flint-chart/assets/flint-app.html b/.github/extensions/flint-chart/assets/flint-app.html index e950fcd8..f2efeba1 100644 --- a/.github/extensions/flint-chart/assets/flint-app.html +++ b/.github/extensions/flint-chart/assets/flint-app.html @@ -5,18 +5,18 @@ Flint Chart - - diff --git a/.github/extensions/flint-chart/skills/flint-chart-author/SKILL.md b/.github/extensions/flint-chart/skills/flint-chart-author/SKILL.md index 31f06011..abe6f955 100644 --- a/.github/extensions/flint-chart/skills/flint-chart-author/SKILL.md +++ b/.github/extensions/flint-chart/skills/flint-chart-author/SKILL.md @@ -43,22 +43,24 @@ First decide which workflow the user is asking for: `semantic_types` + `chart_spec` pieces. Do not install packages or write renderer code unless asked. - **MCP chart output:** if Flint MCP tools are available, **default to - `create_chart` then `show`** whenever the user asks to see a chart. - `create_chart` checks the spec and returns a report and the chart's id - without drawing; fix what the report asks with `update_chart`, then call - `show` once, which opens an interactive, live-rendered card with a - customization panel. Only fall back to `render_chart` (PNG/SVG) when the host has - no App UI support or the user explicitly wants a static image. Use - `validate_chart` to check a spec without rendering, `compile_chart` when the - user wants backend-native JSON, and `list_chart_types` when you need the - supported chart catalog. -- **DO** pass `updates` beside the input to `create_chart` when the user + `validate_chart` then `show`** whenever the user asks to see a chart. + `validate_chart` checks the spec and returns a report without drawing; fix + what it asks in the spec, then call `show({ "chart": … })` once with the + whole spec, which opens an interactive, live-rendered card with a + customization panel. The server keeps nothing between calls: the spec in + the conversation is the chart. Only fall back to `render_chart` (PNG/SVG) + when the host has no App UI support or the user explicitly wants a static + image. Use `compile_chart` when the user wants backend-native JSON, and + `list_chart_types` when you need the supported chart catalog. +- **DO** pass `updates` beside the input to `validate_chart` and `show` when the user asks the chart to open in a state: rows to stand out, a note on a mark, a framed range. It is a list of ChartUpdate layers, state not behaviour; the shapes are in `flint://interaction-skill` under "Update the chart". To change a - chart in a later turn, call `update_chart` with its id and new `updates`, then - `show` again: a new card shows the new version, earlier cards stay as they were. -- **DO** pass `view: "table"` to `create_chart` when the user wants to see + chart in a later turn, change its spec or `updates` and call `show` again: a + new card shows it, earlier cards stay as they were. The reader's edits in the + card's panel live on that card; its context gives the `chart_spec` that keeps + them, so pass it unless the user asked for something else. +- **DO** pass `view: "table"` to `show` when the user wants to see a chart's numbers: the card opens on the table of the rows the chart draws, and the reader can switch to the chart. When the user wants records listed and no chart at all, use `chartType: "Table"` instead. @@ -594,9 +596,9 @@ Put the three steps into one `ChartAssemblyInput`, with the data bound as in ``` Add `theme_spec`, `chartProperties`, `interaction_spec` or `updates` only when -the request asks for them. With the MCP tools, send it to `create_chart` -directly (it validates; skip `validate_chart`), fix what the report asks with -`update_chart`, then `show`. Without them, run the "Validation checklist". +the request asks for them. With the MCP tools, check it with `validate_chart`, +fix what the report asks in the spec, then pass the whole spec to `show` as +`chart`. Without them, run the "Validation checklist". ## Chart-level properties (`chartProperties`) @@ -860,4 +862,4 @@ Before returning, verify: ## Copilot CLI chart canvas -When this plugin's native **Flint Chart Canvas** is available, prefer it over `create_chart` and `show`. Validate the complete `ChartAssemblyInput` first, then open the canvas with that input, including any theme, options, and `interaction_spec`. Pass resolved inline `data.values`, not a local `data.url`: the canvas cannot read local data files. The canvas owns interactive chart customization; do not recreate that UI or replace it with a browser page. +When this plugin's native **Flint Chart Canvas** is available, prefer it over `validate_chart` and `show`. Validate the complete `ChartAssemblyInput` first, then open the canvas with that input, including any theme, options, and `interaction_spec`. Pass resolved inline `data.values`, not a local `data.url`: the canvas cannot read local data files. The canvas owns interactive chart customization; do not recreate that UI or replace it with a browser page. diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml index b9a75cea..02ad62ed 100644 --- a/.github/workflows/npm-publish.yml +++ b/.github/workflows/npm-publish.yml @@ -75,13 +75,17 @@ jobs: shell: bash run: | set -euo pipefail - for attempt in {1..30}; do - if npm view "flint-chart@${js_version}" version >/dev/null 2>&1; then - npm view "flint-chart@${js_version}" version + # Ask the registry itself: an earlier npm view cached the old packument for ~5 minutes + # (max-age=300), which a plain npm view keeps serving. A large package can also take + # several minutes to spread through npm's CDN, so wait up to 20 minutes. + for attempt in {1..60}; do + if curl -fsS -H 'Cache-Control: no-cache' "https://registry.npmjs.org/flint-chart/${js_version}" >/dev/null 2>&1 \ + && npm view "flint-chart@${js_version}" version --prefer-online >/dev/null 2>&1; then + npm view "flint-chart@${js_version}" version --prefer-online exit 0 fi - echo "Waiting for flint-chart@${js_version} to be visible on npm (${attempt}/30)..." - sleep 10 + echo "Waiting for flint-chart@${js_version} to be visible on npm (${attempt}/60)..." + sleep 20 done echo "::error::flint-chart@${js_version} did not become visible on npm in time." exit 1 @@ -102,13 +106,17 @@ jobs: shell: bash run: | set -euo pipefail - for attempt in {1..30}; do - if npm view "flint-chart-mcp@${mcp_version}" version >/dev/null 2>&1; then - npm view "flint-chart-mcp@${mcp_version}" version + # Ask the registry itself: an earlier npm view cached the old packument for ~5 minutes + # (max-age=300), which a plain npm view keeps serving. A large package can also take + # several minutes to spread through npm's CDN, so wait up to 20 minutes. + for attempt in {1..60}; do + if curl -fsS -H 'Cache-Control: no-cache' "https://registry.npmjs.org/flint-chart-mcp/${mcp_version}" >/dev/null 2>&1 \ + && npm view "flint-chart-mcp@${mcp_version}" version --prefer-online >/dev/null 2>&1; then + npm view "flint-chart-mcp@${mcp_version}" version --prefer-online exit 0 fi - echo "Waiting for flint-chart-mcp@${mcp_version} to be visible on npm (${attempt}/30)..." - sleep 10 + echo "Waiting for flint-chart-mcp@${mcp_version} to be visible on npm (${attempt}/60)..." + sleep 20 done echo "::error::flint-chart-mcp@${mcp_version} did not become visible on npm in time." exit 1 @@ -119,9 +127,9 @@ jobs: set -euo pipefail if [ "${js_needs_publish}" = true ]; then npm dist-tag ls flint-chart - npm view "flint-chart@${js_version}" name version license repository.url + npm view "flint-chart@${js_version}" name version license repository.url --prefer-online fi if [ "${mcp_needs_publish}" = true ]; then npm dist-tag ls flint-chart-mcp - npm view "flint-chart-mcp@${mcp_version}" name version license repository.url bin + npm view "flint-chart-mcp@${mcp_version}" name version license repository.url bin --prefer-online fi \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ac95fa5..dd20223e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- **Breaking (MCP):** the server keeps nothing between calls, so it runs + stateless. `show` takes the spec itself, as `chart` or `board`, and draws it; + `validate_chart` and the new `validate_board` check a spec and return the + same report without drawing. `create_chart`, `create_board`, `add_chart`, + `update_chart`, `remove_chart`, `update_board` and the card-only + `restore_board`, `set_board_theme` and `set_board_layout` are removed. To + change what is on screen, the agent changes the spec and calls `show` again. + The reader's theme, arrangement and panel edits stay on the card, and its + context gives the fields (`theme_spec`, `grid`, `chart_spec`) that keep them in + the next `show`. A card the host draws again without its result calls `show` + with the spec it was given. + +## [1.0.1] - 2026-10-21 + +Released together for `flint-chart`, `flint-chart-mcp`, and the Copilot Canvas plugin. + +### Fixed + +- Plotly: a Line or Area Chart's `chartProperties.interpolate` now outranks the theme's line + curve, an explicit `linear` included. A theme such as Cartoon (`monotone`) or De Stijl (`step`) + only supplies a curve when the chart asks for none (#149). +- MCP: a small chart whose rows were passed inline also rides in `show`'s `structuredContent`, so + a card that VS Code's Agent Host draws again (it drops `_meta`) can still render it. Rows read + from a local `data.url` file never do (microsoft/vscode#343243). +- The npm publish workflow waits up to 20 minutes for a new version and asks the registry + directly, instead of a cached answer. + ## [1.0.0] - 2026-10-19 Released together for `flint-chart`, `flint-chart-mcp`, and the Copilot Canvas plugin. @@ -492,7 +521,8 @@ Released together for `flint-chart`, `flint-chart-mcp`, and the Copilot Canvas p - Treated only lowercase `start` and `end` Waterfall Type values as total anchors in Vega-Lite; other values now remain floating deltas colored by sign. -[Unreleased]: https://github.com/microsoft/flint-chart/compare/1.0.0...HEAD +[Unreleased]: https://github.com/microsoft/flint-chart/compare/1.0.1...HEAD +[1.0.1]: https://github.com/microsoft/flint-chart/compare/1.0.0...1.0.1 [1.0.0]: https://github.com/microsoft/flint-chart/compare/0.5.1...1.0.0 [0.5.1]: https://github.com/microsoft/flint-chart/compare/0.5...0.5.1 [0.5.0]: https://github.com/microsoft/flint-chart/compare/0.4.0...0.5.0 diff --git a/agent-skills/flint-board-author/SKILL.md b/agent-skills/flint-board-author/SKILL.md index b49eda23..0c92b01e 100644 --- a/agent-skills/flint-board-author/SKILL.md +++ b/agent-skills/flint-board-author/SKILL.md @@ -1,17 +1,16 @@ --- name: flint-board-author -description: "Use when: several Flint charts should be read together in one view: a dashboard, KPI tiles over a trend, a side-by-side comparison, an overview with its detail; or a board on screen should change (add, retitle, resize, reconnect a chart). Produce one create_board call whose headline, chart choice, layout and connected fields are decided, refine it from the report, then put it on screen once with show." +description: "Use when: several Flint charts should be read together in one view: a dashboard, KPI tiles over a trend, a side-by-side comparison, an overview with its detail; or a board on screen should change (add, retitle, resize, reconnect a chart). Produce one board spec whose headline, chart choice, layout and connected fields are decided, check and refine it with validate_board, then put it on screen once with show." --- # flint-board: several charts, one view -A board holds several Flint charts under one headline. The agent builds it -with `create_board` and changes it with `add_chart`, `update_chart`, -`remove_chart` and `update_board`; none of these draws anything. `show` -puts the board's current version on screen in a new card, below the -conversation's latest message, and earlier cards keep the version they showed. -So call `show` once a turn, after the board is right. A new -`create_board` starts a second board, so it is only for a second board. +A board holds several Flint charts under one headline. The agent writes it as +one board spec, checks it with `validate_board`, which draws nothing, and puts +it on screen with `show({ "board": … })`, which opens a new card below the +conversation's latest message. The server keeps nothing between calls: the spec +in the conversation is the board. So call `show` once a turn, after the board +is right; to change it later, change the spec and call `show` again. Each chart on a board is a full chart spec (`flint-chart-author`), plus an `id` and a `layout`. This skill covers what a board adds: the headline, which @@ -108,7 +107,7 @@ On a narrow card each chart takes its own row; the layout needs no second versio **`view: "table"`** on a chart opens its cell on the table of the rows the chart draws; the reader can switch it back. Use it when the numbers matter more than -the shape. Changing `view` with `update_chart` keeps the reader's arrangement. +the shape. A `Table` is a table either way. ## Step 5 — connect them @@ -174,8 +173,8 @@ Pick it with `list_themes` as for one chart. ## Step 7 — read the report and refine -`create_board` and every later call return the board as the model must judge -it: +`validate_board` returns the board as the model must judge it, and `show` +returns the same report: - `Layout:` the rows as the card draws them. Check that the lead chart sits where the headline points and no row holds an orphan. @@ -184,27 +183,31 @@ it: - `Review:` what the board should still fix: a missing headline, deck or chart title, too many tiles or charts, themes set per chart. -Each call takes the board's `id` from the report. Fix each `✗` and each review -note with the narrowest call: `update_chart` with `chart_id` for one chart -(pass only the fields that change), `update_board` for the headline, -theme, columns, order or `link_spec`, `remove_chart` for a chart the board does not -need. Then call `show` once. In a later turn, change the board the same -way and show it again: the reader gets a new card at the bottom of the -conversation, and the earlier one stays as it was. - -What the reader then does on the newest card (selections, link emphasis) -reaches the model with their next message, one section per chart. - -The reader can also arrange the board: **Edit layout** lets them move a chart, -swap two, and resize one on a 12-column grid. Their arrangement then replaces the -rows: `Layout:` reads "Arranged by the reader" and lists each chart's columns and -rows. Keep it. `add_chart` places a new chart below it and `update_chart` keeps -it; `layout` on a chart, or `columns` or `order` on the board, drops it and lays -the board out in rows again, so pass those only when the user asks for a new -layout. +Fix each `✗` and each review note in the spec, check it again if the fix was +large, then call `show` once with the same spec. A chart with errors is left +off the report's board, and `show` draws nothing until every chart is valid. + +What the reader then does on the card reaches the model with their next +message: selections and link emphasis, one section per chart. The reader's +changes live on that card only, and the context says how to keep each one in +the next `show`: + +- **A theme** picked in the bar applies to every chart. To keep it, pass that + `theme_spec` on the board and leave it out of the charts. +- **An arrangement** made with **Edit layout** (moving, swapping, resizing + charts on a 12-column grid). To keep it, pass the `grid` the context gives. + `Layout:` then reads "Arranged on a 12-column grid". A chart added to the + spec takes a place below the rest and a chart left out drops its place; + leave `grid` out to lay the board out in rows again, only when the user asks + for a new layout. + +Leave out what the user asked to change, and keep the rest: a `show` without +them gives the reader back the agent's theme and rows. ## Worked example +The board spec, passed as it is to `validate_board`, then as `board` to `show`: + ```json { "title": "Europe carried the third-quarter recovery", @@ -249,4 +252,5 @@ on a region's line lights that region on the bars and the scatter. - [ ] `layout` set where the default is wrong: the lead chart wide, a comparison at equal spans and heights. - [ ] `link_spec.fields` names the shared dimensions; each chart that should take part encodes them and, to send, has the interaction whose subject the reader asks about. - [ ] `theme_spec` on the board only. -- [ ] The report has no `✗` and no review note left but the shared colour field. +- [ ] `validate_board` reports no `✗` and no review note left but the shared colour field. +- [ ] In a later turn: the reader's theme and `grid` from the context are kept unless the user asked to change them. diff --git a/agent-skills/flint-chart-author/SKILL.md b/agent-skills/flint-chart-author/SKILL.md index aaae801a..295f40c7 100644 --- a/agent-skills/flint-chart-author/SKILL.md +++ b/agent-skills/flint-chart-author/SKILL.md @@ -43,22 +43,24 @@ First decide which workflow the user is asking for: `semantic_types` + `chart_spec` pieces. Do not install packages or write renderer code unless asked. - **MCP chart output:** if Flint MCP tools are available, **default to - `create_chart` then `show`** whenever the user asks to see a chart. - `create_chart` checks the spec and returns a report and the chart's id - without drawing; fix what the report asks with `update_chart`, then call - `show` once, which opens an interactive, live-rendered card with a - customization panel. Only fall back to `render_chart` (PNG/SVG) when the host has - no App UI support or the user explicitly wants a static image. Use - `validate_chart` to check a spec without rendering, `compile_chart` when the - user wants backend-native JSON, and `list_chart_types` when you need the - supported chart catalog. -- **DO** pass `updates` beside the input to `create_chart` when the user + `validate_chart` then `show`** whenever the user asks to see a chart. + `validate_chart` checks the spec and returns a report without drawing; fix + what it asks in the spec, then call `show({ "chart": … })` once with the + whole spec, which opens an interactive, live-rendered card with a + customization panel. The server keeps nothing between calls: the spec in + the conversation is the chart. Only fall back to `render_chart` (PNG/SVG) + when the host has no App UI support or the user explicitly wants a static + image. Use `compile_chart` when the user wants backend-native JSON, and + `list_chart_types` when you need the supported chart catalog. +- **DO** pass `updates` beside the input to `validate_chart` and `show` when the user asks the chart to open in a state: rows to stand out, a note on a mark, a framed range. It is a list of ChartUpdate layers, state not behaviour; the shapes are in `flint://interaction-skill` under "Update the chart". To change a - chart in a later turn, call `update_chart` with its id and new `updates`, then - `show` again: a new card shows the new version, earlier cards stay as they were. -- **DO** pass `view: "table"` to `create_chart` when the user wants to see + chart in a later turn, change its spec or `updates` and call `show` again: a + new card shows it, earlier cards stay as they were. The reader's edits in the + card's panel live on that card; its context gives the `chart_spec` that keeps + them, so pass it unless the user asked for something else. +- **DO** pass `view: "table"` to `show` when the user wants to see a chart's numbers: the card opens on the table of the rows the chart draws, and the reader can switch to the chart. When the user wants records listed and no chart at all, use `chartType: "Table"` instead. @@ -594,9 +596,9 @@ Put the three steps into one `ChartAssemblyInput`, with the data bound as in ``` Add `theme_spec`, `chartProperties`, `interaction_spec` or `updates` only when -the request asks for them. With the MCP tools, send it to `create_chart` -directly (it validates; skip `validate_chart`), fix what the report asks with -`update_chart`, then `show`. Without them, run the "Validation checklist". +the request asks for them. With the MCP tools, check it with `validate_chart`, +fix what the report asks in the spec, then pass the whole spec to `show` as +`chart`. Without them, run the "Validation checklist". ## Chart-level properties (`chartProperties`) diff --git a/agent-skills/flint-interaction-author/SKILL.md b/agent-skills/flint-interaction-author/SKILL.md index 7bf7dcea..8091af3a 100644 --- a/agent-skills/flint-interaction-author/SKILL.md +++ b/agent-skills/flint-interaction-author/SKILL.md @@ -23,7 +23,7 @@ other backends leave `interaction_spec` and updates untouched. | A gesture or a behaviour on the chart: "highlight on click", "zoom", "brush a period", "make it interactive", "add behaviour to this chart". | One `interaction_spec`: `{ "interactions": [ ... ] }`, presets only. | Add interactions to the chart | | A change to a chart that is already on screen, from outside: "point out Japan", "frame 2010 to 2020", "note this value", "reorder by value", an agent answering a user with the chart. | One `ChartUpdate`: `{ "id", "ops": [ ... ] }`. | Update the chart | | Code around a chart: "in my app", "on click open the record", "a panel that follows the hover". | TypeScript against `flint-chart/interactive`: mount, presets as factories, `onChange`, `dispatch`. | Use Flint in an application | -| Code across charts or over time: "link these two charts", "a table that follows the selection", "play the years". | `linkCharts` or `useLinkedCharts`; `dispatch` on a timer. On an MCP board, `link_spec` instead (board skill, "Step 5 — connect them"). | Link charts, and drive a chart over time | +| Code across charts or over time: "link these two charts", "a table that follows the selection", "play the years". | `linkCharts` or `useLinkedCharts`; `dispatch` on a timer. On an MCP board, `link_spec` instead (board skill, "Step 5 — connect them"). | Link charts | | A gesture no preset gives: "drag along the path", "draw a guess", "a rule for the box", "a lens the app draws". | A `CanvasInteractionDef`: a trigger, affordances, a handler. | When no preset fits | - **DO** use only the names in this skill: preset types, options, ops, states, @@ -37,14 +37,13 @@ other backends leave `interaction_spec` and updates untouched. ## Which workflow the user is asking for - **Presets through the MCP tools:** put the object beside `chart_spec` as - `interaction_spec` in the input of `create_chart`, which reports its - warnings; `validate_chart` reports the same without rendering, for when you - do not draw. `list_interaction_presets` + `interaction_spec` in the chart input; `validate_chart` reports its warnings + without drawing, and `show` draws it with the same report. `list_interaction_presets` with `chartType` lists the presets that chart type supports, what each does, and its options. - **An update through the MCP tools:** there is no handle on the chart. Pass - the layers as the `updates` argument of `create_chart` or `update_chart`, - beside the input; see "Step 4 — send the layer and read the result". + the layers as the `updates` argument beside the input, to `validate_chart` + and `show`; see "Step 4 — send the layer and read the result". - **Code, only when the user asks for code:** mount with `mountChart`, or `` in React; presets as factory calls, updates with `applyUpdate`, state with `getState` and `onChange`. The programming API @@ -210,8 +209,8 @@ The object is `{ "interactions": [ ... ] }`, beside `chart_spec` as } ``` -`create_chart` checks the object when it builds the chart; `validate_chart` -runs the same check in code or CI. Do not run both for the same chart. A malformed entry +`validate_chart` checks the object without drawing, and `show` runs the same +check when it draws. A malformed entry is an error: an unknown `type`, an option beside `type`, an `id` inside `options`, a bare string entry, a missing required option, an unsupported `reset` gesture, a duplicate `id`. A dropped or yielded entry is a warning @@ -514,7 +513,7 @@ The y axis shows life from 70 to 86. The state is in field terms: what the chart is after the reader's panel edits, each op of your updates as applied (✓) or not and why (✗), what the reader selected, hid or filtered, and the viewport on view when the chart navigates. -`validate_chart`, `create_chart` and `update_chart` return the same report before the +`validate_chart` and `show` return the same report before the reader touches the chart, with `User interactions: none.` From it, decide what the reader should see next: which rows stand out, what one note says, which range frames them. The rows you were given are the source of every value; the chart @@ -654,8 +653,8 @@ it shows: fix an unresolved key or drop an unsupported op before describing the chart. **From the MCP view.** There is no `applyUpdate` to call. Pass the same layers -as the `updates` argument of `create_chart`, beside the chart input, not -inside it: +as the `updates` argument beside the chart input, not inside it, to +`validate_chart` and then to `show` as part of `chart`: ```json { @@ -671,21 +670,20 @@ inside it: ``` `show` opens the chart with the layers applied, with the same look as a -user action. To show the chart in a new state, call `update_chart` with its id -and the layers wanted now, then `show` again. Each `show` opens a new card with +user action. To show the chart in a new state, call `show` again with the same +input and the layers wanted now. Each `show` opens a new card with exactly those layers; earlier cards keep what they showed. The argument is state, and `interaction_spec` is behaviour, so each stays where it is. The reader's own brush or selection does not survive the new view; the context message reports it in field terms, and it is carried as a layer when it still serves the reader. -Call `create_chart` directly; it validates the input and `updates` -itself, so do not call `validate_chart` first. A malformed layer or an invalid -spec is an error and keeps nothing. Otherwise the result is the report above, -one line per op, led by a count when an op did not apply. The chart draws -without a ✗ op: fix it with `update_chart` (a key no row has, an overlay -encoding written as `"x": "start"` instead of `{ "field": "start" }`, a -viewport with no navigation preset) before you call `show`, or tell the reader -what is missing. The +Check the input and `updates` with `validate_chart` first. A malformed layer +or an invalid spec is an error, and `show` draws nothing for it. Otherwise the +result is the report above, one line per op, led by a count when an op did not +apply. The chart draws without a ✗ op: fix it in the layer (a key no row has, +an overlay encoding written as `"x": "start"` instead of `{ "field": "start" }`, +a viewport with no navigation preset) before you call `show`, or tell the +reader what is missing. The reader's later brushes and clicks reach you with their next message, not in the same turn. @@ -834,7 +832,15 @@ canvas interaction, before the chart reacts: `detail.chartId`, a handler gets. It fires for a definition whose `handle` returns `null`, so it is the path for a host that draws its own response to a gesture. -## Link charts, and drive a chart over time +Things the surface holds fixed: no preset changes the layout, so a zoom never +recomputes the bar step, the ticks, or the domain (filter the rows and mount +again for that); the mute level is set at mount; Escape reaches a chart after +a press on it, and only that chart; a preset's toggle (`select`, +`click-highlight`) needs Shift, Ctrl, or Meta, and a plain second click +replaces; a press on an overlay path resolves to no mark, so a `click-none` +reset on the definition that drew the overlay clears it at that press. + +## Link charts `linkCharts` links mounted charts on the fields they share. A selection on one chart (a click, a brush, a group focus, a hover) becomes one condition, a part @@ -911,18 +917,11 @@ source.onChange(({ phase, interactionId, state }) => { }); ``` -`dispatch` is also how an application drives a chart over time: a playback -loop dispatches one frame per animation frame, and the handler returns the -whole layer for that frame. Linked charts share one `theme_spec` so a value -has one colour everywhere. +Linked charts share one `theme_spec` so a value has one colour everywhere. -Things the surface holds fixed: no preset changes the layout, so a zoom never -recomputes the bar step, the ticks, or the domain (filter the rows and mount -again for that); the mute level is set at mount; Escape reaches a chart after -a press on it, and only that chart; a preset's toggle (`select`, -`click-highlight`) needs Shift, Ctrl, or Meta, and a plain second click -replaces; a press on an overlay path resolves to no mark, so a `click-none` -reset on the definition that drew the overlay clears it at that press. +The same `dispatch` drives a chart over time: a playback loop dispatches one +frame per animation frame, and the handler returns the whole layer for that +frame. ## Worked examples @@ -1079,7 +1078,7 @@ For an `interaction_spec`: 4. `groupBy` and `seriesBy` are present where required, and name bound fields. 5. At most one entry owns the plot drag, the double-click, the legend click, and the retained mark focus. -6. `create_chart` (or `validate_chart`, in code or CI) returns no warning. +6. `validate_chart` returns no warning. For a `ChartUpdate`: diff --git a/docs/tutorials/setup-flint-mcp.md b/docs/tutorials/setup-flint-mcp.md index b8f17ac6..9923a99d 100644 --- a/docs/tutorials/setup-flint-mcp.md +++ b/docs/tutorials/setup-flint-mcp.md @@ -17,11 +17,9 @@ opens that chart locally. | Tool | Use it for | |------|------------| -| `create_chart` | Build a chart and return a report of it with its id; nothing is drawn yet. | -| `create_board` | Build a board of several charts under one headline; nothing is drawn yet. | -| `update_chart`, `add_chart`, `remove_chart`, `update_board` | Change a chart or board by its id. | -| `show` | Preferred default when the host supports MCP Apps: open a card with the chart or board, drawn live with chart options. | -| `validate_chart` | Check whether a Flint input is valid and inspect warnings, errors, and computed size. | +| `validate_chart` | Check a chart spec without drawing it: the report, warnings, errors, and computed size. | +| `validate_board` | Check a board of several charts under one headline without drawing it. | +| `show` | Preferred default when the host supports MCP Apps: open a card with the chart or board spec it is given, drawn live with chart options. The server keeps nothing between calls. | | `render_chart` | Render a static PNG or SVG locally when you need an artifact or the host has no MCP App UI. | | `compile_chart` | Return backend-native Vega-Lite, ECharts, or Chart.js JSON. | | `list_chart_types` | Inspect supported chart types, encoding channels, and the interaction presets each chart type supports. | @@ -221,7 +219,7 @@ npx -y flint-chart-mcp --backends vegalite,echarts FLINT_MCP_BACKENDS=vegalite,echarts npx -y flint-chart-mcp ``` -Use `create_chart` then `show` when the user wants to see and iterate on a +Use `validate_chart` then `show` when the user wants to see and iterate on a chart in a host with MCP App support. Use `render_chart` for a static artifact. Use `compile_chart` when the user needs backend-native JSON for another renderer or editor. @@ -241,7 +239,7 @@ Then try a first chart: Use Flint MCP to create a bar chart from these rows: [{"region":"North","revenue":120},{"region":"South","revenue":90}] Use region as Category and revenue as Quantity. -Build it with create_chart and open it with show if this client supports MCP Apps; otherwise render an SVG. +Check it with validate_chart and open it with show if this client supports MCP Apps; otherwise render an SVG. ``` If `list_chart_types` works but a local file chart fails, check that the file diff --git a/docs/zh-CN/tutorials/setup-flint-mcp.md b/docs/zh-CN/tutorials/setup-flint-mcp.md index b873aa92..97b4a305 100644 --- a/docs/zh-CN/tutorials/setup-flint-mcp.md +++ b/docs/zh-CN/tutorials/setup-flint-mcp.md @@ -10,11 +10,9 @@ | 工具 | 用途 | |------|------| -| `create_chart` | 构建一张图表,返回图表报告及其 id;此时尚未绘制。 | -| `create_board` | 在同一标题下构建由多张图表组成的看板;此时尚未绘制。 | -| `update_chart`、`add_chart`、`remove_chart`、`update_board` | 按 id 修改图表或看板。 | -| `show` | 打开一张卡片,实时绘制图表或看板,并提供图表选项。客户端支持 MCP Apps 时优先使用。 | -| `validate_chart` | 检查 Flint 输入,返回警告、错误和计算后的图表尺寸。 | +| `validate_chart` | 不绘制,只检查图表规范,返回报告、警告、错误和计算后的图表尺寸。 | +| `validate_board` | 不绘制,只检查同一标题下由多张图表组成的看板。 | +| `show` | 打开一张卡片,实时绘制传入的图表或看板规范,并提供图表选项。客户端支持 MCP Apps 时优先使用。服务器在调用之间不保存任何内容。 | | `render_chart` | 渲染静态 PNG 或 SVG。客户端不支持 MCP Apps,或需要导出图片时使用。 | | `compile_chart` | 生成可供 Vega-Lite、ECharts 或 Chart.js 直接使用的 JSON 规范。 | | `list_chart_types` | 列出支持的图表类型和编码通道。 | @@ -187,7 +185,7 @@ npx -y flint-chart-mcp --backends vegalite,echarts FLINT_MCP_BACKENDS=vegalite,echarts npx -y flint-chart-mcp ``` -客户端支持 MCP Apps 时,先用 `create_chart` 构建图表,再用 `show` 查看和调整。需要静态图片时使用 `render_chart`。需要在其他渲染器或编辑器中继续使用时,通过 `compile_chart` 生成对应的 JSON 规范。 +客户端支持 MCP Apps 时,先用 `validate_chart` 检查图表,再用 `show` 查看和调整。需要静态图片时使用 `render_chart`。需要在其他渲染器或编辑器中继续使用时,通过 `compile_chart` 生成对应的 JSON 规范。 ## 验证配置 @@ -204,7 +202,7 @@ Then call list_chart_types for the vegalite backend and tell me whether Flint is Use Flint MCP to create a bar chart from these rows: [{"region":"North","revenue":120},{"region":"South","revenue":90}] Use region as Category and revenue as Quantity. -Build it with create_chart and open it with show if this client supports MCP Apps; otherwise render an SVG. +Check it with validate_chart and open it with show if this client supports MCP Apps; otherwise render an SVG. ``` 如果 `list_chart_types` 可用,但无法读取本地文件,请检查文件路径以及是否设置了 `--disable-file-reference`。如果 `show` 不可用,客户端可能不支持 MCP Apps;请改用 `render_chart`。 diff --git a/package-lock.json b/package-lock.json index 04921668..e3be42e7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11194,7 +11194,7 @@ }, "packages/flint-js": { "name": "flint-chart", - "version": "1.0.0", + "version": "1.0.1", "license": "MIT", "dependencies": { "@floating-ui/dom": "^1.7.4", @@ -11258,7 +11258,7 @@ }, "packages/flint-mcp": { "name": "flint-chart-mcp", - "version": "1.0.0", + "version": "1.0.1", "license": "MIT", "dependencies": { "@modelcontextprotocol/ext-apps": "^1.7.4", @@ -11267,7 +11267,7 @@ "@resvg/resvg-js": "^2.6.2", "chart.js": "^4.4.0", "echarts": "^6.0.0", - "flint-chart": "^1.0.0", + "flint-chart": "^1.0.1", "vega": "^6.0.0", "vega-interpreter": "^2.2.1", "vega-lite": "^6.0.0", diff --git a/packages/flint-js/package.json b/packages/flint-js/package.json index 43f89565..23915a33 100644 --- a/packages/flint-js/package.json +++ b/packages/flint-js/package.json @@ -1,6 +1,6 @@ { "name": "flint-chart", - "version": "1.0.0", + "version": "1.0.1", "description": "Semantic-level visualization library that compiles data + semantic types for Vega-Lite, ECharts, Chart.js, Plotly, and Excel.", "keywords": [ "visualization", diff --git a/packages/flint-js/src/plotly/templates/area.ts b/packages/flint-js/src/plotly/templates/area.ts index 2a9fa04c..ce8ded10 100644 --- a/packages/flint-js/src/plotly/templates/area.ts +++ b/packages/flint-js/src/plotly/templates/area.ts @@ -22,8 +22,12 @@ import { makeCartesianPivot } from '../../core/pivot'; const isDiscrete = (type: string | undefined) => type === 'nominal' || type === 'ordinal'; -/** Map the shared `interpolate` property onto Plotly's `line.shape`. */ -function lineShape(interpolate: unknown): 'linear' | 'spline' | 'hv' | 'vh' | 'hvh' { +/** + * Map the shared `interpolate` property onto Plotly's `line.shape`. Undefined when the chart asks for + * no curve, so a theme may supply one; an explicit `linear` stays straight under any theme. + */ +function lineShape(interpolate: unknown): 'linear' | 'spline' | 'hv' | 'vh' | 'hvh' | undefined { + if (interpolate == null || interpolate === '') return undefined; switch (interpolate) { case 'monotone': case 'basis': @@ -98,7 +102,7 @@ export const plAreaChartDef: ChartTemplateDef = { name, x: xVals, y: yVals, - line: { color, shape }, + line: { color, ...(shape ? { shape } : {}) }, fillcolor: fillColor(color, opacity), }; if (colorField && stacked) { diff --git a/packages/flint-js/src/plotly/templates/line.ts b/packages/flint-js/src/plotly/templates/line.ts index 5167c79b..25992691 100644 --- a/packages/flint-js/src/plotly/templates/line.ts +++ b/packages/flint-js/src/plotly/templates/line.ts @@ -23,8 +23,12 @@ import { makeCartesianPivot } from '../../core/pivot'; const isDiscrete = (type: string | undefined) => type === 'nominal' || type === 'ordinal'; -/** Map the shared `interpolate` property onto Plotly's `line.shape`. */ -function lineShape(interpolate: unknown): 'linear' | 'spline' | 'hv' | 'vh' | 'hvh' { +/** + * Map the shared `interpolate` property onto Plotly's `line.shape`. Undefined when the chart asks for + * no curve, so a theme may supply one; an explicit `linear` stays straight under any theme. + */ +function lineShape(interpolate: unknown): 'linear' | 'spline' | 'hv' | 'vh' | 'hvh' | undefined { + if (interpolate == null || interpolate === '') return undefined; switch (interpolate) { case 'monotone': case 'basis': @@ -99,7 +103,7 @@ export const plLineChartDef: ChartTemplateDef = { y: yVals, line: { color: getSeriesColor(palette, colorIndex), - shape, + ...(shape ? { shape } : {}), ...(dashField ? { dash: dashes[dashIndex % dashes.length] } : {}), }, ...(colorField ? { @@ -141,7 +145,7 @@ export const plLineChartDef: ChartTemplateDef = { y: yVals, line: { color: '#cccccc', - shape, + ...(shape ? { shape } : {}), ...(dashField ? { dash: dashes[dashIndex % dashes.length] } : {}), }, hoverinfo: 'skip', diff --git a/packages/flint-js/src/plotly/theme.ts b/packages/flint-js/src/plotly/theme.ts index 7bdbef50..3f91eeb3 100644 --- a/packages/flint-js/src/plotly/theme.ts +++ b/packages/flint-js/src/plotly/theme.ts @@ -1606,8 +1606,9 @@ function applyMarks(figure: any, d: DesignDecisions, table: any[], say: ReportDe ? m.areaEdge?.width ?? Math.min(1, m.strokeWidth) : radarEdge ? Math.min(2.5, m.strokeWidth) : m.strokeWidth; trace.line = { ...(trace.line ?? {}), width }; - if (m.interpolate && !trace._preserveLineShape - && (!trace.line.shape || trace.line.shape === 'linear')) { + // Only a shape the chart left unset: a template sets one when the chart asked for a curve, + // `linear` included, and that choice outranks the house's. + if (m.interpolate && !trace._preserveLineShape && !trace.line.shape) { const shape = plotlyLineShape(m.interpolate); if (shape) trace.line.shape = shape; else say('marks.line.interpolate', 'interpolate-unsupported', `\`${m.interpolate}\` has no Plotly line shape — left straight`); diff --git a/packages/flint-js/tests/theme-plotly.test.ts b/packages/flint-js/tests/theme-plotly.test.ts index 4fd319ab..fc776e3b 100644 --- a/packages/flint-js/tests/theme-plotly.test.ts +++ b/packages/flint-js/tests/theme-plotly.test.ts @@ -207,6 +207,41 @@ describe('semantic geometry survives house styling', () => { expect(String(fig.data[0].mode)).toContain('markers'); }); + it("keeps a line chart's own curve, an explicit linear included, under a house curve (#149)", () => { + const lineInput = (interpolate: string | undefined, theme: string | undefined) => ({ + data: { values: [{ date: '2025-01-01', value: 4 }, { date: '2025-06-01', value: 6 }, { date: '2026-01-01', value: 5 }] }, + semantic_types: { date: 'DateTime', value: 'Quantity' }, + chart_spec: { + chartType: 'Line Chart', + encodings: { x: 'date', y: 'value' }, + ...(interpolate ? { chartProperties: { interpolate } } : {}), + }, + ...(theme ? { theme_spec: theme } : {}), + }); + const shapeOf = (interpolate: string | undefined, theme: string | undefined) => + (assemblePlotly(lineInput(interpolate, theme) as any) as any).data[0].line.shape; + // The table from the issue: the chart's choice wins under every house. + for (const theme of [undefined, 'cartoon', 'de-stijl']) { + expect(shapeOf('linear', theme)).toBe('linear'); + expect(shapeOf('monotone', theme)).toBe('spline'); + expect(shapeOf('step-after', theme)).toBe('hv'); + } + // With no curve asked for, the house still supplies its own. + expect(shapeOf(undefined, 'cartoon')).toBe('spline'); + expect(shapeOf(undefined, 'de-stijl')).toMatch(/^(hv|vh|hvh)$/); + expect(shapeOf(undefined, undefined) ?? 'linear').toBe('linear'); + }); + + it("keeps an area chart's explicit linear under a house curve", () => { + const fig = assemblePlotly({ + data: { values: [{ x: 1, y: 2 }, { x: 2, y: 5 }, { x: 3, y: 3 }] }, + semantic_types: { x: 'Quantity', y: 'Quantity' }, + chart_spec: { chartType: 'Area Chart', encodings: { x: 'x', y: 'y' }, chartProperties: { interpolate: 'linear' } }, + theme_spec: 'cartoon', + } as any) as any; + expect(fig.data[0].line.shape).toBe('linear'); + }); + it('keeps an ECDF stepped when the house prefers curved lines', () => { const fig = assemblePlotly({ data: { values: [{ score: 1 }, { score: 2 }, { score: 3 }] }, diff --git a/packages/flint-mcp/README.md b/packages/flint-mcp/README.md index 257afb4f..93d63ac1 100644 --- a/packages/flint-mcp/README.md +++ b/packages/flint-mcp/README.md @@ -30,10 +30,8 @@ renders **locally**. | `list_interaction_presets` | `chartType?`, `type?` | interaction presets: what each does, what it needs from the chart, reset gestures, and every option it accepts | | `list_themes` | optional preset `id` | shipped visual themes, plus guidance for a selected theme | | `get_flint_skill` | `skill` (`chart`/`theme`/`interaction`/`board`) + `section?` | a bundled skill as markdown, or one `## ` section of it | -| `create_chart` | spec + optional `updates`, `view` | a chart built off screen: its report (✓/✗ per update op) and its id | -| `create_board` | headline, deck, source, `charts`, optional `link_spec` | a board of several charts built off screen: its report, layout, links and review | -| `update_chart`, `add_chart`, `remove_chart`, `update_board` | `id` + the fields to change | the next version's report; nothing is drawn | -| `show` | `id` | a live **UI** card (MCP App) with the chart or board's current version: SVG preview + editing panel, with its ChartUpdate layers applied | +| `validate_board` | headline, deck, source, `charts`, optional `link_spec`, `grid` | a board of several charts checked without drawing: its report, layout, links and review | +| `show` | `chart` (spec + optional `updates`, `view`) or `board` (as `validate_board`) | a live **UI** card (MCP App) with the chart or board: SVG preview + editing panel, with its ChartUpdate layers applied, and the same report | ## Visual themes @@ -63,9 +61,10 @@ for supported fields and merge behavior. ## MCP App: live chart view In hosts that support MCP App UIs (e.g. Claude Desktop), `show` opens a card -with a chart or board built by `create_chart` or `create_board`. The agent fixes -what the report asks before it calls `show`, so each turn shows one card; later -changes open a new card and earlier cards keep the version they showed. The +with the chart or board spec it is given. The agent checks the spec with +`validate_chart` or `validate_board` and fixes what the report asks before it +calls `show`, so each turn shows one card; later changes open a new card and +earlier cards keep what they showed. The card renders the spec live (Vega-Lite → SVG) and shows a customization panel built from Flint's own option model — chart type, channel bindings, chart properties (corner radius, stack mode, donut hole, …), and @@ -74,9 +73,11 @@ run entirely in the host UI; no data leaves the host. The UI is a single self-contained HTML bundle served as the `ui://flint-chart/view.html` resource and built with `npm run build:ui`. -Charts and boards live in the server process's memory between `create_chart` -and `show`, so a deployment behind a load balancer needs one instance or sticky -sessions. +The server keeps nothing between calls: every tool builds the chart or board +again from the spec it is given, so it runs stateless behind any number of +instances. The reader's changes on a card (a theme, an arrangement, panel edits) +stay on that card and reach the agent in the card's context, as the fields to +pass to the next `show`. ## Resources and prompts @@ -96,7 +97,7 @@ The server instructions tell the agent to call `get_flint_skill` before it writes a spec, so the skills reach the agent in hosts that do not surface MCP resources or prompts to the model. You can also include `flint://agent-skill` or run the `author_flint_chart` prompt before asking the agent to call -`create_chart`, `render_chart`, `compile_chart`, or `validate_chart`. +`validate_chart`, `show`, `render_chart`, or `compile_chart`. When creating or substantially customizing a visual theme, load `flint://theme-skill` or run `author_flint_theme`. Use `list_themes` separately diff --git a/packages/flint-mcp/assets/flint-board-author.SKILL.md b/packages/flint-mcp/assets/flint-board-author.SKILL.md index b49eda23..0c92b01e 100644 --- a/packages/flint-mcp/assets/flint-board-author.SKILL.md +++ b/packages/flint-mcp/assets/flint-board-author.SKILL.md @@ -1,17 +1,16 @@ --- name: flint-board-author -description: "Use when: several Flint charts should be read together in one view: a dashboard, KPI tiles over a trend, a side-by-side comparison, an overview with its detail; or a board on screen should change (add, retitle, resize, reconnect a chart). Produce one create_board call whose headline, chart choice, layout and connected fields are decided, refine it from the report, then put it on screen once with show." +description: "Use when: several Flint charts should be read together in one view: a dashboard, KPI tiles over a trend, a side-by-side comparison, an overview with its detail; or a board on screen should change (add, retitle, resize, reconnect a chart). Produce one board spec whose headline, chart choice, layout and connected fields are decided, check and refine it with validate_board, then put it on screen once with show." --- # flint-board: several charts, one view -A board holds several Flint charts under one headline. The agent builds it -with `create_board` and changes it with `add_chart`, `update_chart`, -`remove_chart` and `update_board`; none of these draws anything. `show` -puts the board's current version on screen in a new card, below the -conversation's latest message, and earlier cards keep the version they showed. -So call `show` once a turn, after the board is right. A new -`create_board` starts a second board, so it is only for a second board. +A board holds several Flint charts under one headline. The agent writes it as +one board spec, checks it with `validate_board`, which draws nothing, and puts +it on screen with `show({ "board": … })`, which opens a new card below the +conversation's latest message. The server keeps nothing between calls: the spec +in the conversation is the board. So call `show` once a turn, after the board +is right; to change it later, change the spec and call `show` again. Each chart on a board is a full chart spec (`flint-chart-author`), plus an `id` and a `layout`. This skill covers what a board adds: the headline, which @@ -108,7 +107,7 @@ On a narrow card each chart takes its own row; the layout needs no second versio **`view: "table"`** on a chart opens its cell on the table of the rows the chart draws; the reader can switch it back. Use it when the numbers matter more than -the shape. Changing `view` with `update_chart` keeps the reader's arrangement. +the shape. A `Table` is a table either way. ## Step 5 — connect them @@ -174,8 +173,8 @@ Pick it with `list_themes` as for one chart. ## Step 7 — read the report and refine -`create_board` and every later call return the board as the model must judge -it: +`validate_board` returns the board as the model must judge it, and `show` +returns the same report: - `Layout:` the rows as the card draws them. Check that the lead chart sits where the headline points and no row holds an orphan. @@ -184,27 +183,31 @@ it: - `Review:` what the board should still fix: a missing headline, deck or chart title, too many tiles or charts, themes set per chart. -Each call takes the board's `id` from the report. Fix each `✗` and each review -note with the narrowest call: `update_chart` with `chart_id` for one chart -(pass only the fields that change), `update_board` for the headline, -theme, columns, order or `link_spec`, `remove_chart` for a chart the board does not -need. Then call `show` once. In a later turn, change the board the same -way and show it again: the reader gets a new card at the bottom of the -conversation, and the earlier one stays as it was. - -What the reader then does on the newest card (selections, link emphasis) -reaches the model with their next message, one section per chart. - -The reader can also arrange the board: **Edit layout** lets them move a chart, -swap two, and resize one on a 12-column grid. Their arrangement then replaces the -rows: `Layout:` reads "Arranged by the reader" and lists each chart's columns and -rows. Keep it. `add_chart` places a new chart below it and `update_chart` keeps -it; `layout` on a chart, or `columns` or `order` on the board, drops it and lays -the board out in rows again, so pass those only when the user asks for a new -layout. +Fix each `✗` and each review note in the spec, check it again if the fix was +large, then call `show` once with the same spec. A chart with errors is left +off the report's board, and `show` draws nothing until every chart is valid. + +What the reader then does on the card reaches the model with their next +message: selections and link emphasis, one section per chart. The reader's +changes live on that card only, and the context says how to keep each one in +the next `show`: + +- **A theme** picked in the bar applies to every chart. To keep it, pass that + `theme_spec` on the board and leave it out of the charts. +- **An arrangement** made with **Edit layout** (moving, swapping, resizing + charts on a 12-column grid). To keep it, pass the `grid` the context gives. + `Layout:` then reads "Arranged on a 12-column grid". A chart added to the + spec takes a place below the rest and a chart left out drops its place; + leave `grid` out to lay the board out in rows again, only when the user asks + for a new layout. + +Leave out what the user asked to change, and keep the rest: a `show` without +them gives the reader back the agent's theme and rows. ## Worked example +The board spec, passed as it is to `validate_board`, then as `board` to `show`: + ```json { "title": "Europe carried the third-quarter recovery", @@ -249,4 +252,5 @@ on a region's line lights that region on the bars and the scatter. - [ ] `layout` set where the default is wrong: the lead chart wide, a comparison at equal spans and heights. - [ ] `link_spec.fields` names the shared dimensions; each chart that should take part encodes them and, to send, has the interaction whose subject the reader asks about. - [ ] `theme_spec` on the board only. -- [ ] The report has no `✗` and no review note left but the shared colour field. +- [ ] `validate_board` reports no `✗` and no review note left but the shared colour field. +- [ ] In a later turn: the reader's theme and `grid` from the context are kept unless the user asked to change them. diff --git a/packages/flint-mcp/assets/flint-chart-author.SKILL.md b/packages/flint-mcp/assets/flint-chart-author.SKILL.md index aaae801a..295f40c7 100644 --- a/packages/flint-mcp/assets/flint-chart-author.SKILL.md +++ b/packages/flint-mcp/assets/flint-chart-author.SKILL.md @@ -43,22 +43,24 @@ First decide which workflow the user is asking for: `semantic_types` + `chart_spec` pieces. Do not install packages or write renderer code unless asked. - **MCP chart output:** if Flint MCP tools are available, **default to - `create_chart` then `show`** whenever the user asks to see a chart. - `create_chart` checks the spec and returns a report and the chart's id - without drawing; fix what the report asks with `update_chart`, then call - `show` once, which opens an interactive, live-rendered card with a - customization panel. Only fall back to `render_chart` (PNG/SVG) when the host has - no App UI support or the user explicitly wants a static image. Use - `validate_chart` to check a spec without rendering, `compile_chart` when the - user wants backend-native JSON, and `list_chart_types` when you need the - supported chart catalog. -- **DO** pass `updates` beside the input to `create_chart` when the user + `validate_chart` then `show`** whenever the user asks to see a chart. + `validate_chart` checks the spec and returns a report without drawing; fix + what it asks in the spec, then call `show({ "chart": … })` once with the + whole spec, which opens an interactive, live-rendered card with a + customization panel. The server keeps nothing between calls: the spec in + the conversation is the chart. Only fall back to `render_chart` (PNG/SVG) + when the host has no App UI support or the user explicitly wants a static + image. Use `compile_chart` when the user wants backend-native JSON, and + `list_chart_types` when you need the supported chart catalog. +- **DO** pass `updates` beside the input to `validate_chart` and `show` when the user asks the chart to open in a state: rows to stand out, a note on a mark, a framed range. It is a list of ChartUpdate layers, state not behaviour; the shapes are in `flint://interaction-skill` under "Update the chart". To change a - chart in a later turn, call `update_chart` with its id and new `updates`, then - `show` again: a new card shows the new version, earlier cards stay as they were. -- **DO** pass `view: "table"` to `create_chart` when the user wants to see + chart in a later turn, change its spec or `updates` and call `show` again: a + new card shows it, earlier cards stay as they were. The reader's edits in the + card's panel live on that card; its context gives the `chart_spec` that keeps + them, so pass it unless the user asked for something else. +- **DO** pass `view: "table"` to `show` when the user wants to see a chart's numbers: the card opens on the table of the rows the chart draws, and the reader can switch to the chart. When the user wants records listed and no chart at all, use `chartType: "Table"` instead. @@ -594,9 +596,9 @@ Put the three steps into one `ChartAssemblyInput`, with the data bound as in ``` Add `theme_spec`, `chartProperties`, `interaction_spec` or `updates` only when -the request asks for them. With the MCP tools, send it to `create_chart` -directly (it validates; skip `validate_chart`), fix what the report asks with -`update_chart`, then `show`. Without them, run the "Validation checklist". +the request asks for them. With the MCP tools, check it with `validate_chart`, +fix what the report asks in the spec, then pass the whole spec to `show` as +`chart`. Without them, run the "Validation checklist". ## Chart-level properties (`chartProperties`) diff --git a/packages/flint-mcp/assets/flint-interaction-author.SKILL.md b/packages/flint-mcp/assets/flint-interaction-author.SKILL.md index 7bf7dcea..8091af3a 100644 --- a/packages/flint-mcp/assets/flint-interaction-author.SKILL.md +++ b/packages/flint-mcp/assets/flint-interaction-author.SKILL.md @@ -23,7 +23,7 @@ other backends leave `interaction_spec` and updates untouched. | A gesture or a behaviour on the chart: "highlight on click", "zoom", "brush a period", "make it interactive", "add behaviour to this chart". | One `interaction_spec`: `{ "interactions": [ ... ] }`, presets only. | Add interactions to the chart | | A change to a chart that is already on screen, from outside: "point out Japan", "frame 2010 to 2020", "note this value", "reorder by value", an agent answering a user with the chart. | One `ChartUpdate`: `{ "id", "ops": [ ... ] }`. | Update the chart | | Code around a chart: "in my app", "on click open the record", "a panel that follows the hover". | TypeScript against `flint-chart/interactive`: mount, presets as factories, `onChange`, `dispatch`. | Use Flint in an application | -| Code across charts or over time: "link these two charts", "a table that follows the selection", "play the years". | `linkCharts` or `useLinkedCharts`; `dispatch` on a timer. On an MCP board, `link_spec` instead (board skill, "Step 5 — connect them"). | Link charts, and drive a chart over time | +| Code across charts or over time: "link these two charts", "a table that follows the selection", "play the years". | `linkCharts` or `useLinkedCharts`; `dispatch` on a timer. On an MCP board, `link_spec` instead (board skill, "Step 5 — connect them"). | Link charts | | A gesture no preset gives: "drag along the path", "draw a guess", "a rule for the box", "a lens the app draws". | A `CanvasInteractionDef`: a trigger, affordances, a handler. | When no preset fits | - **DO** use only the names in this skill: preset types, options, ops, states, @@ -37,14 +37,13 @@ other backends leave `interaction_spec` and updates untouched. ## Which workflow the user is asking for - **Presets through the MCP tools:** put the object beside `chart_spec` as - `interaction_spec` in the input of `create_chart`, which reports its - warnings; `validate_chart` reports the same without rendering, for when you - do not draw. `list_interaction_presets` + `interaction_spec` in the chart input; `validate_chart` reports its warnings + without drawing, and `show` draws it with the same report. `list_interaction_presets` with `chartType` lists the presets that chart type supports, what each does, and its options. - **An update through the MCP tools:** there is no handle on the chart. Pass - the layers as the `updates` argument of `create_chart` or `update_chart`, - beside the input; see "Step 4 — send the layer and read the result". + the layers as the `updates` argument beside the input, to `validate_chart` + and `show`; see "Step 4 — send the layer and read the result". - **Code, only when the user asks for code:** mount with `mountChart`, or `` in React; presets as factory calls, updates with `applyUpdate`, state with `getState` and `onChange`. The programming API @@ -210,8 +209,8 @@ The object is `{ "interactions": [ ... ] }`, beside `chart_spec` as } ``` -`create_chart` checks the object when it builds the chart; `validate_chart` -runs the same check in code or CI. Do not run both for the same chart. A malformed entry +`validate_chart` checks the object without drawing, and `show` runs the same +check when it draws. A malformed entry is an error: an unknown `type`, an option beside `type`, an `id` inside `options`, a bare string entry, a missing required option, an unsupported `reset` gesture, a duplicate `id`. A dropped or yielded entry is a warning @@ -514,7 +513,7 @@ The y axis shows life from 70 to 86. The state is in field terms: what the chart is after the reader's panel edits, each op of your updates as applied (✓) or not and why (✗), what the reader selected, hid or filtered, and the viewport on view when the chart navigates. -`validate_chart`, `create_chart` and `update_chart` return the same report before the +`validate_chart` and `show` return the same report before the reader touches the chart, with `User interactions: none.` From it, decide what the reader should see next: which rows stand out, what one note says, which range frames them. The rows you were given are the source of every value; the chart @@ -654,8 +653,8 @@ it shows: fix an unresolved key or drop an unsupported op before describing the chart. **From the MCP view.** There is no `applyUpdate` to call. Pass the same layers -as the `updates` argument of `create_chart`, beside the chart input, not -inside it: +as the `updates` argument beside the chart input, not inside it, to +`validate_chart` and then to `show` as part of `chart`: ```json { @@ -671,21 +670,20 @@ inside it: ``` `show` opens the chart with the layers applied, with the same look as a -user action. To show the chart in a new state, call `update_chart` with its id -and the layers wanted now, then `show` again. Each `show` opens a new card with +user action. To show the chart in a new state, call `show` again with the same +input and the layers wanted now. Each `show` opens a new card with exactly those layers; earlier cards keep what they showed. The argument is state, and `interaction_spec` is behaviour, so each stays where it is. The reader's own brush or selection does not survive the new view; the context message reports it in field terms, and it is carried as a layer when it still serves the reader. -Call `create_chart` directly; it validates the input and `updates` -itself, so do not call `validate_chart` first. A malformed layer or an invalid -spec is an error and keeps nothing. Otherwise the result is the report above, -one line per op, led by a count when an op did not apply. The chart draws -without a ✗ op: fix it with `update_chart` (a key no row has, an overlay -encoding written as `"x": "start"` instead of `{ "field": "start" }`, a -viewport with no navigation preset) before you call `show`, or tell the reader -what is missing. The +Check the input and `updates` with `validate_chart` first. A malformed layer +or an invalid spec is an error, and `show` draws nothing for it. Otherwise the +result is the report above, one line per op, led by a count when an op did not +apply. The chart draws without a ✗ op: fix it in the layer (a key no row has, +an overlay encoding written as `"x": "start"` instead of `{ "field": "start" }`, +a viewport with no navigation preset) before you call `show`, or tell the +reader what is missing. The reader's later brushes and clicks reach you with their next message, not in the same turn. @@ -834,7 +832,15 @@ canvas interaction, before the chart reacts: `detail.chartId`, a handler gets. It fires for a definition whose `handle` returns `null`, so it is the path for a host that draws its own response to a gesture. -## Link charts, and drive a chart over time +Things the surface holds fixed: no preset changes the layout, so a zoom never +recomputes the bar step, the ticks, or the domain (filter the rows and mount +again for that); the mute level is set at mount; Escape reaches a chart after +a press on it, and only that chart; a preset's toggle (`select`, +`click-highlight`) needs Shift, Ctrl, or Meta, and a plain second click +replaces; a press on an overlay path resolves to no mark, so a `click-none` +reset on the definition that drew the overlay clears it at that press. + +## Link charts `linkCharts` links mounted charts on the fields they share. A selection on one chart (a click, a brush, a group focus, a hover) becomes one condition, a part @@ -911,18 +917,11 @@ source.onChange(({ phase, interactionId, state }) => { }); ``` -`dispatch` is also how an application drives a chart over time: a playback -loop dispatches one frame per animation frame, and the handler returns the -whole layer for that frame. Linked charts share one `theme_spec` so a value -has one colour everywhere. +Linked charts share one `theme_spec` so a value has one colour everywhere. -Things the surface holds fixed: no preset changes the layout, so a zoom never -recomputes the bar step, the ticks, or the domain (filter the rows and mount -again for that); the mute level is set at mount; Escape reaches a chart after -a press on it, and only that chart; a preset's toggle (`select`, -`click-highlight`) needs Shift, Ctrl, or Meta, and a plain second click -replaces; a press on an overlay path resolves to no mark, so a `click-none` -reset on the definition that drew the overlay clears it at that press. +The same `dispatch` drives a chart over time: a playback loop dispatches one +frame per animation frame, and the handler returns the whole layer for that +frame. ## Worked examples @@ -1079,7 +1078,7 @@ For an `interaction_spec`: 4. `groupBy` and `seriesBy` are present where required, and name bound fields. 5. At most one entry owns the plot drag, the double-click, the legend click, and the retained mark focus. -6. `create_chart` (or `validate_chart`, in code or CI) returns no warning. +6. `validate_chart` returns no warning. For a `ChartUpdate`: diff --git a/packages/flint-mcp/package.json b/packages/flint-mcp/package.json index 3abe4449..19aff417 100644 --- a/packages/flint-mcp/package.json +++ b/packages/flint-mcp/package.json @@ -1,6 +1,6 @@ { "name": "flint-chart-mcp", - "version": "1.0.0", + "version": "1.0.1", "description": "Model Context Protocol server for Flint — compile, validate, and render semantic chart specs across supported backends.", "keywords": [ "mcp", @@ -69,7 +69,7 @@ "@resvg/resvg-js": "^2.6.2", "chart.js": "^4.4.0", "echarts": "^6.0.0", - "flint-chart": "^1.0.0", + "flint-chart": "^1.0.1", "vega": "^6.0.0", "vega-interpreter": "^2.2.1", "vega-lite": "^6.0.0", diff --git a/packages/flint-mcp/src/board.ts b/packages/flint-mcp/src/board.ts index 757e95c5..284a5582 100644 --- a/packages/flint-mcp/src/board.ts +++ b/packages/flint-mcp/src/board.ts @@ -6,7 +6,7 @@ import { z } from 'zod'; import type { ChartAssemblyInput, ChartLink, ChartUpdate, LinkSpec, ValidateResult } from 'flint-chart'; import { drawsAsTable, validateLinks } from 'flint-chart'; -import { ROW_UNITS, boardColumns, boardRows, colorField, gridItemFor, gridLines, isKpi, layoutLines, sharedColorOrders, type ChartLayout, type GridItem } from './board-layout.js'; +import { ROW_UNITS, boardColumns, boardRows, colorField, gridItemFor, gridLines, gridProblem, isKpi, layoutLines, sharedColorOrders, type ChartLayout, type GridItem } from './board-layout.js'; /** The characters of a chart title that fit on one line per row unit, at the card's heading size. */ const TITLE_CHARS_PER_UNIT = 7.5; @@ -21,6 +21,8 @@ export interface BoardChart { layout?: ChartLayout; /** The view the cell opens in; the reader's switch holds until the agent sets it again. */ view?: ChartView; + /** The rows were read from a local data.url file, so they never passed through the conversation. */ + fromFile?: true; } export interface Board { @@ -37,15 +39,8 @@ export interface Board { theme_spec?: ChartAssemblyInput['theme_spec']; /** Board columns; two once the board holds two charts that are not KPI tiles. */ columns?: number; - /** Where each chart sits once the reader arranged the board; the rows of `columns` and `layout` until then. */ + /** Where each chart sits, as the reader arranged it on a card; the rows of `columns` and `layout` without it. */ grid?: GridItem[]; - /** - * The theme the reader picked for every chart, over the board's and the charts' own; `theme` - * null is Flint's default. Absent while the reader keeps the agent's theme. - */ - reader_theme?: { theme: ChartAssemblyInput['theme_spec'] | null }; - /** One per agent write; a card shows one version, and the reader's changes keep it. */ - version: number; charts: BoardChart[]; /** The fields the charts connect on; none when the charts stand alone. */ link_spec?: LinkSpec; @@ -56,7 +51,7 @@ export interface Board { /** A chart spec as a tool argument: its id, the chart input, and its update layers. */ export type BoardChartArgs = AssemblyInputArgs & { id: string; updates?: ChartUpdate[]; layout?: ChartLayout; view?: ChartView }; -/** The board fields create_board and update_board set. */ +/** The board fields a board spec sets around its charts. */ export type BoardFields = Pick; export const layoutShape = z @@ -80,10 +75,10 @@ type Validate = (input: ChartAssemblyInput, updates: ChartUpdate[] | undefined) export function boardChartShape(assemblyInputShape: Record) { return z.object({ - id: z.string().describe('Names the chart on the board; add_chart, update_chart, remove_chart and link_spec use it.'), + id: z.string().describe('Names the chart on the board; link_spec, grid and the report use it.'), ...assemblyInputShape, updates: updatesShape.updates.describe( - 'ChartUpdate layers the chart shows: state, where interaction_spec is behaviour. update_chart replaces them.', + 'ChartUpdate layers the chart shows: state, where interaction_spec is behaviour.', ), layout: layoutShape.optional(), ...viewShape, @@ -102,45 +97,6 @@ export const linkSpecShape = z }) .describe('How the charts on the board connect: by the fields they share. One selection holds at a time; a new one replaces the last.'); -/** The most boards a store keeps; creating one more drops the oldest. */ -export const BOARD_LIMIT = 200; - -export class BoardStore { - private boards = new Map(); - - create(kind: Board['kind'], fields: BoardFields = {}): Board { - const board: Board = { id: `${kind}-${randomBytes(8).toString('hex')}`, kind, ...fields, version: 1, charts: [] }; - this.boards.set(board.id, board); - if (this.boards.size > BOARD_LIMIT) this.boards.delete(this.boards.keys().next().value!); - return board; - } - - /** Takes back the board a card holds, as a server that restarted lost it; a newer board it holds stays. */ - restore(board: Board): Board { - const held = this.boards.get(board.id); - if (held && held.version >= (board.version ?? 1)) return held; - const kept: Board = { ...board, kind: board.kind ?? 'board', charts: board.charts ?? [], version: board.version ?? 1 }; - this.boards.set(kept.id, kept); - if (this.boards.size > BOARD_LIMIT) this.boards.delete(this.boards.keys().next().value!); - return kept; - } - - get(id: string): Board { - const board = this.boards.get(id); - if (!board) { - throw new Error( - `No chart or board "${id}" on this server; it may have restarted. Call create_chart or create_board to build it again, then show.`, - ); - } - return board; - } - - /** Marks an agent write: the board's next version. */ - touch(board: Board): void { - board.version += 1; - } -} - /** The chart as the model reads it before it is drawn: the same report the drawn chart sends as its context. */ export function chartReport(input: ChartAssemblyInput, updates: readonly ChartUpdate[] | undefined, result: ValidateResult): string { const report = chartContext({ agent: input, shown: input, updates, checks: result.updates, warnings: result.warnings }).text; @@ -168,8 +124,10 @@ export async function prepareChart( validate: Validate, board: Pick, ): Promise<{ chart?: BoardChart; outcome: ChartOutcome; errors?: string }> { - const { id, updates, layout, view, ...rest } = args; + const { id, updates, layout, view, fromFile: keptFromFile, ...rest } = args as BoardChartArgs & { fromFile?: true }; const own = toAssemblyInput(rest as AssemblyInputArgs); + // An update that leaves the data alone rebuilds from rows already read, so the file origin carries over. + const fromFile = typeof own.data?.url === 'string' || keptFromFile === true; const { result, input } = await validate(withBoardTheme(own, board), updates); if (!result.valid) { const errors = result.errors.map((e) => e.message).join('; '); @@ -177,10 +135,13 @@ export async function prepareChart( } const opensAsTable = view === 'table' && !drawsAsTable(input.chart_spec.chartType); const report = chartReport(input, updates, result) + (opensAsTable ? `\n${OPENS_AS_TABLE}` : ''); - // The board's theme stays the board's: a later update_board theme reaches every chart that set none. + // The board's theme stays the board's, so the card's theme switch reaches every chart that set none. const stored = { ...input, theme_spec: own.theme_spec }; return { - chart: { id, input: stored, ...(updates ? { updates } : {}), ...(layout ? { layout } : {}), ...(opensAsTable ? { view } : {}) }, + chart: { + id, input: stored, ...(updates ? { updates } : {}), ...(layout ? { layout } : {}), ...(opensAsTable ? { view } : {}), + ...(fromFile ? { fromFile: true as const } : {}), + }, outcome: { id, drawn: true, text: report }, }; } @@ -200,7 +161,7 @@ function layoutCharts(board: Board) { export function boardLayoutLines(board: Board): string[] { if (board.grid) { return [ - 'Arranged by the reader on a 12-column grid; keep it. Passing layout, columns or order sets the rows again and drops their arrangement.', + 'Arranged on a 12-column grid (grid), as the reader left it; keep passing it. Leave grid out to lay the charts out in rows again.', ...gridLines(board.grid), ]; } @@ -208,17 +169,27 @@ export function boardLayoutLines(board: Board): string[] { return layoutLines(boardRows(charts, boardColumns(charts, board.columns))); } -/** A chart added to an arranged board takes a place below the rest. */ -export function placeAddedChart(board: Board, chart: BoardChart): void { - if (!board.grid) return; - board.grid = [...board.grid, gridItemFor(board.grid, { id: chart.id, chartType: chart.input.chart_spec.chartType, layout: chart.layout })]; -} - -/** Drops the reader's arrangement, and says so, when the agent sets the rows the board is laid out by. */ -export function dropArrangement(board: Board, why: string): string | undefined { +/** + * The arrangement a board spec passes, fitted to its charts: places of charts no longer on the board + * are dropped and new charts take a place below the rest. An arrangement that still does not fit is + * dropped for the rows, and the note says why. + */ +export function fitGrid(board: Board): string | undefined { if (!board.grid) return undefined; - board.grid = undefined; - return `The reader's arrangement was dropped: ${why} sets the board's rows again.`; + const ids = new Set(board.charts.map((chart) => chart.id)); + let grid = board.grid.filter((item) => ids.has(item.id)); + for (const chart of board.charts) { + if (!grid.some((item) => item.id === chart.id)) { + grid = [...grid, gridItemFor(grid, { id: chart.id, chartType: chart.input.chart_spec.chartType, layout: chart.layout })]; + } + } + const problem = gridProblem(grid, board.charts.map((chart) => chart.id)); + if (problem) { + board.grid = undefined; + return `The grid was dropped for the rows: ${problem}.`; + } + board.grid = grid; + return undefined; } /** Chart types that draw one mark per row, so rows that repeat a category stack as slices. */ @@ -242,17 +213,17 @@ function stackedRepeats(input: ChartAssemblyInput): string | undefined { const keys = new Set(rows.map((row) => JSON.stringify(categories.map((field) => row?.[field])))); if (keys.size === rows.length) return undefined; const channel = Object.entries(encodings).find(([, value]) => fieldOf(value) === measure)?.[0] ?? 'x'; - return `draws ${rows.length} rows as ${keys.size} ${categories.join(' × ')} groups, so each mark is a stack of slices, one per row: sum the rows first, or set encodings.${channel}.aggregate to "sum" (update_chart).`; + return `draws ${rows.length} rows as ${keys.size} ${categories.join(' × ')} groups, so each mark is a stack of slices, one per row: sum the rows first, or set encodings.${channel}.aggregate to "sum".`; } /** What the board should still fix to read well; each note says the fix. */ export function boardReview(board: Board): string[] { const notes: string[] = []; - if (!board.title) notes.push('No board title: set title to what the board shows or is for, in words (update_board).'); + if (!board.title) notes.push('No board title: set title to what the board shows or is for, in words.'); if (board.title && board.title.length > 90) notes.push('The board title is long; keep it to one line and move the detail to subtitle.'); - if (!board.subtitle && board.charts.length > 0) notes.push('No subtitle: say the data, its scope, period and units (update_board).'); + if (!board.subtitle && board.charts.length > 0) notes.push('No subtitle: say the data, its scope, period and units.'); const untitled = board.charts.filter((chart) => !isKpi(chart.input.chart_spec.chartType) && !chart.input.chart_spec.title).map((chart) => chart.id); - if (untitled.length > 0) notes.push(`No title on ${untitled.join(', ')}: each cell's heading is its chart title; name what the chart shows (update_chart).`); + if (untitled.length > 0) notes.push(`No title on ${untitled.join(', ')}: each chart draws its title as its heading; name what the chart shows.`); const charts = layoutCharts(board); const units = new Map(boardRows(charts, boardColumns(charts, board.columns)).flatMap((row) => row.charts.map((cell) => [cell.id, cell.units] as const))); const long = board.charts.flatMap((chart) => { @@ -260,7 +231,7 @@ export function boardReview(board: Board): string[] { const limit = Math.round((units.get(chart.id) ?? ROW_UNITS) * TITLE_CHARS_PER_UNIT); return title && title.length > limit ? [`${chart.id} (${title.length} characters, about ${limit} fit)`] : []; }); - if (long.length > 0) notes.push(`Chart titles that wrap at their width: ${long.join(', ')}; shorten each to one line and move detail to its subtitle (update_chart).`); + if (long.length > 0) notes.push(`Chart titles that wrap at their width: ${long.join(', ')}; shorten each to one line and move detail to its subtitle.`); for (const chart of board.charts) { const stacked = stackedRepeats(chart.input); if (stacked) notes.push(`${chart.id} ${stacked}`); @@ -270,7 +241,7 @@ export function boardReview(board: Board): string[] { if (board.charts.length - kpis > 8) notes.push(`${board.charts.length - kpis} charts: a board reads best with up to six; split it or remove the least used.`); const themes = new Set(board.charts.map((chart) => JSON.stringify(chart.input.theme_spec ?? null)).filter((theme) => theme !== 'null')); if (themes.size > 1 || (themes.size === 1 && board.theme_spec !== undefined)) { - notes.push('Charts set their own themes; set theme_spec once on the board (update_board) and drop it from the charts so the board reads as one piece.'); + notes.push('Charts set their own themes; set theme_spec once on the board and drop it from the charts so the board reads as one piece.'); } for (const [field, values] of sharedColorOrders(board.charts.map((chart) => chart.input))) { const users = board.charts.filter((chart) => colorField(chart.input) === field).map((chart) => chart.id); @@ -289,28 +260,23 @@ export function themeName(theme: ChartAssemblyInput['theme_spec'] | null): strin /** What the model reads once a chart or board is on screen. */ export function shownText(board: Board): string { - return `${board.kind === 'chart' ? 'Chart' : 'Board'} ${board.id} version ${board.version} is on screen in a new card; earlier cards keep the versions they showed. What the reader does on it reaches you with their next message.`; + return `The ${board.kind === 'chart' ? 'chart' : 'board'} is on screen in a new card. What the reader does on it reaches you with their next message. ` + + 'To change it, change the spec and call show again: a new card shows it, and earlier cards stay as they were.'; } -/** A chart or board as the model reads it after a write. */ -export function viewReport(board: Board, outcomes: readonly ChartOutcome[], notes: readonly string[] = []): string { - if (board.kind === 'board') return boardReport(board, outcomes, notes); - return [ - `Chart ${board.id}, version ${board.version}, not on screen yet: fix what this report asks with update_chart (never a new create_chart), then call show once.`, - ...notes, - ...outcomes.map((outcome) => outcome.text), - ].join('\n'); +/** A chart or board as the model reads it: the checks of validate_chart or validate_board, or of show. */ +export function viewReport(board: Board, outcomes: readonly ChartOutcome[], notes: readonly string[] = [], shown = false): string { + const next = shown ? shownText(board) : 'Nothing is on screen: fix what this report asks in the spec, then call show with it.'; + if (board.kind === 'board') return boardReport(board, outcomes, notes, next); + return [next, ...notes, ...outcomes.map((outcome) => outcome.text)].join('\n'); } -function boardReport(board: Board, outcomes: readonly ChartOutcome[], notes: readonly string[]): string { +function boardReport(board: Board, outcomes: readonly ChartOutcome[], notes: readonly string[], next: string): string { const lines = [ - `Board ${board.id}${board.title ? ` "${board.title}"` : ''}: ${board.charts.length} chart${board.charts.length === 1 ? '' : 's'} (${board.charts.map((chart) => chart.id).join(', ') || 'none'}).`, - `Version ${board.version}, not on screen yet: fix what this report asks with add_chart, update_chart, remove_chart and update_board (never a new create_board), then call show once.`, + `Board${board.title ? ` "${board.title}"` : ''}: ${board.charts.length} chart${board.charts.length === 1 ? '' : 's'} (${board.charts.map((chart) => chart.id).join(', ') || 'none'}).`, + next, ]; if (notes.length > 0) lines.push('', ...notes); - if (board.reader_theme) { - lines.push('', `The reader picked the theme ${themeName(board.reader_theme.theme)} for every chart; keep it. Passing theme_spec on update_board replaces their pick.`); - } if (board.charts.length > 0) lines.push('', 'Layout:', ...boardLayoutLines(board)); for (const outcome of outcomes) { lines.push('', `## ${outcome.id}`, outcome.text); @@ -324,6 +290,23 @@ function boardReport(board: Board, outcomes: readonly ChartOutcome[], notes: rea } /** The board as the card reads it. */ +/** + * The largest board `show` also returns in structuredContent, in bytes of JSON. VS Code's agent + * sessions rebuild a card's result from content and structuredContent alone, dropping _meta, so a + * card drawn again finds its chart only there; but that copy also reaches the model, so only small + * boards ride along (about 1k tokens at most). + */ +export const RESULT_COPY_LIMIT = 4096; + +/** + * Whether `show` may also put the board in structuredContent: every chart's rows came inline, so they + * are in the conversation already, and the board is small. Rows read from a local file never are. + */ +export function fitsInResult(board: Board): boolean { + if (board.charts.some((chart) => chart.fromFile)) return false; + return Buffer.byteLength(JSON.stringify(board), 'utf8') <= RESULT_COPY_LIMIT; +} + export function boardSnapshot(board: Board): Board { return { ...board, @@ -331,32 +314,49 @@ export function boardSnapshot(board: Board): Board { ...(board.link_spec ? { link_spec: { ...board.link_spec } } : {}), ...(board.linked ? { linked: { ...board.linked } } : {}), ...(board.grid ? { grid: board.grid.map((item) => ({ ...item })) } : {}), - ...(board.reader_theme ? { reader_theme: { ...board.reader_theme } } : {}), }; } -/** The chart input fields update_chart may replace, by tool argument name. */ -export const CHART_INPUT_KEYS = ['data', 'semantic_types', 'chart_spec', 'theme_spec', 'interaction_spec', 'options', 'field_display_names'] as const; - -/** The chart args an update_chart call leaves: the chart's current input with the given fields replaced. */ -export function mergeChartArgs(chart: BoardChart, patch: Partial): BoardChartArgs { - const base = { - id: chart.id, - ...chart.input, - ...(chart.updates ? { updates: chart.updates } : {}), - ...(chart.layout ? { layout: chart.layout } : {}), - ...(chart.view ? { view: chart.view } : {}), - } as unknown as BoardChartArgs; - const next: Record = { ...base }; - for (const key of CHART_INPUT_KEYS) { - if (patch[key] !== undefined) next[key] = patch[key]; +/** + * A chart or board from its spec, every chart checked, nothing kept: validate_chart, validate_board + * and show each build it again from the spec the agent passes. A chart with errors is left off the + * board, and its outcome says why. + */ +export async function assembleBoard( + spec: BoardSpec, + kind: Board['kind'], + validate: Validate, +): Promise<{ board: Board; outcomes: ChartOutcome[]; notes: string[] }> { + const board: Board = { + id: `${kind}-${randomBytes(8).toString('hex')}`, + kind, + ...(spec.title !== undefined ? { title: spec.title } : {}), + ...(spec.subtitle !== undefined ? { subtitle: spec.subtitle } : {}), + ...(spec.source !== undefined ? { source: spec.source } : {}), + ...(spec.theme_spec !== undefined ? { theme_spec: spec.theme_spec } : {}), + ...(spec.columns !== undefined ? { columns: spec.columns } : {}), + ...(spec.grid ? { grid: spec.grid } : {}), + charts: [], + }; + const outcomes: ChartOutcome[] = []; + for (const chartArgs of spec.charts) { + const { chart, outcome } = await prepareChart(chartArgs, validate, board); + outcomes.push(outcome); + if (chart) board.charts.push(chart); } - if (patch.updates !== undefined) next.updates = patch.updates; - if (patch.layout !== undefined) next.layout = patch.layout; - if (patch.view !== undefined) next.view = patch.view; - return next as BoardChartArgs; + if (spec.link_spec) board.link_spec = spec.link_spec; + relink(board); + const notes = [fitGrid(board)].filter((note): note is string => note !== undefined); + return { board, outcomes, notes }; } +/** A board as a tool argument: its fields, its charts, how they connect, and the reader's arrangement. */ +export type BoardSpec = BoardFields & { charts: BoardChartArgs[]; link_spec?: LinkSpec; grid?: GridItem[] }; + +export const gridShape = z + .array(z.object({ id: z.string(), x: z.number(), y: z.number(), w: z.number(), h: z.number() })) + .describe('Where each chart sits on a 12-column grid, as the reader arranged it on a card; the card\'s context gives it. Leave it out for rows.'); + /** The link as the model reads it: what each chart sends, by which interaction, and receives, and what is left out. */ function linkLines(links: Record): string[] { return Object.entries(links).map(([id, link]) => { diff --git a/packages/flint-mcp/src/cli.ts b/packages/flint-mcp/src/cli.ts index 86bee81e..dade65fc 100644 --- a/packages/flint-mcp/src/cli.ts +++ b/packages/flint-mcp/src/cli.ts @@ -43,8 +43,7 @@ Options: -h, --help Print this help and exit. Tools: - create_chart, create_board, add_chart, update_chart, remove_chart, - update_board, show, render_chart, compile_chart, validate_chart, + validate_chart, validate_board, show, render_chart, compile_chart, list_chart_types, list_interaction_presets, list_themes, get_flint_skill Resources: diff --git a/packages/flint-mcp/src/http.ts b/packages/flint-mcp/src/http.ts index 92dd0dff..9ad20c69 100644 --- a/packages/flint-mcp/src/http.ts +++ b/packages/flint-mcp/src/http.ts @@ -4,7 +4,6 @@ import { createServer as createHttpServer, type Server } from 'node:http'; import type { IncomingMessage, ServerResponse } from 'node:http'; import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; -import { BoardStore } from './board.js'; import { createServer, resolveBackends, VERSION, type CreateServerOptions } from './server.js'; /** Default endpoint path the MCP Streamable HTTP transport is served from. */ @@ -89,7 +88,6 @@ export function createMcpRequestListener( // user. Block local file references by default (secure-by-default); pass // disableFileReference:false explicitly to opt back in. disableFileReference: options.disableFileReference ?? true, - boards: new BoardStore(), }; const rebindingProtection = (options.allowedHosts?.length ?? 0) > 0 || (options.allowedOrigins?.length ?? 0) > 0; diff --git a/packages/flint-mcp/src/server.ts b/packages/flint-mcp/src/server.ts index f9e893d1..d59f2023 100644 --- a/packages/flint-mcp/src/server.ts +++ b/packages/flint-mcp/src/server.ts @@ -31,25 +31,18 @@ import type { ChartAssemblyInput, ChartUpdate } from 'flint-chart'; import { VERSION } from './version.js'; import { - BoardStore, + assembleBoard, boardChartShape, boardFieldsShape, - dropArrangement, - placeAddedChart, - themeName, chartReport, viewReport, boardSnapshot, - shownText, + fitsInResult, + gridShape, linkSpecShape, - relink, - mergeChartArgs, - prepareChart, - type Board, type BoardChartArgs, - type ChartOutcome, + type BoardSpec, } from './board.js'; -import { gridProblem } from './board-layout.js'; export { VERSION }; export const AGENT_SKILL_RESOURCE_URI = 'flint://agent-skill'; @@ -101,11 +94,23 @@ function skillSections(text: string): { heading: string; start: number }[] { return sections; } -/** One `## ` section of a skill, from its heading up to the next `## ` heading. */ +/** A heading as it is compared: no `#` marks, case, punctuation or extra spaces. */ +function headingKey(heading: string): string { + return heading.replace(/^#+\s*/, '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim(); +} + +/** + * One `## ` section of a skill, from its heading up to the next `## ` heading. The heading matches + * exactly, or else as the start of one heading only, so a shortened name ("Link charts") finds it. + */ export function skillSection(text: string, heading: string): string { const sections = skillSections(text); - const wanted = heading.replace(/^#+\s*/, '').trim().toLowerCase(); - const index = sections.findIndex((section) => section.heading.toLowerCase() === wanted); + const wanted = headingKey(heading); + let index = sections.findIndex((section) => headingKey(section.heading) === wanted); + if (index < 0 && wanted) { + const starting = sections.flatMap((section, at) => (`${headingKey(section.heading)} `.startsWith(`${wanted} `) ? [at] : [])); + if (starting.length === 1) index = starting[0]; + } if (index < 0) { throw new Error( `No section "${heading}". Sections: ${sections.map((section) => `"${section.heading}"`).join(', ')}.`, @@ -132,8 +137,6 @@ export interface CreateServerOptions { * file the agent references. */ disableFileReference?: boolean; - /** Where charts and boards live; a server that is rebuilt per request passes one store so they outlive the request. */ - boards?: BoardStore; } type JsonContent = { content: { type: 'text'; text: string }[]; isError?: boolean }; @@ -207,11 +210,11 @@ export function createServer(options: CreateServerOptions = {}): McpServer { instructions: 'Flint compiles one semantic chart spec (ChartAssemblyInput) into ' + 'Vega-Lite, ECharts, or Chart.js. By DEFAULT, show a chart whenever the host ' + - 'supports MCP App UIs: build it with create_chart, fix what its report asks with ' + - 'update_chart, then call show once; the card draws the chart live with an editing panel. ' + + 'supports MCP App UIs: check the spec with validate_chart, fix what its report asks, then call ' + + 'show with the spec once; the card draws the chart live with an editing panel. ' + 'For several charts shown together (a dashboard, a comparison, an overview with its detail), ' + - 'call get_flint_skill with skill "board", build it with create_board, change it with add_chart, ' + - 'update_chart, remove_chart and update_board, then call show once. ' + + 'call get_flint_skill with skill "board", check the board with validate_board, then call show with it once. ' + + 'The server keeps nothing between calls: to change a chart, change its spec and call show again. ' + 'The editing panel is not ' + 'interactivity: when the user asks for an interactive chart (hover, ' + 'click, brush, zoom), add an interaction_spec. Fall back to render_chart for a static PNG/SVG artifact only ' + @@ -261,7 +264,7 @@ export function createServer(options: CreateServerOptions = {}): McpServer { description: 'Compile a Flint chart spec for a backend and render it to a STATIC image ' + '(PNG) or vector (SVG), returned inline. Rendering is local/in-process. ' + - 'The chartjs backend supports PNG only. Prefer create_chart and show instead ' + + 'The chartjs backend supports PNG only. Prefer validate_chart and show instead ' + 'when the host supports MCP App UIs; use render_chart for a static ' + 'artifact or when no App UI is available.', inputSchema: { @@ -348,9 +351,8 @@ export function createServer(options: CreateServerOptions = {}): McpServer { 'whether it is valid, all warnings/errors, and the computed layout size. ' + 'With an interaction_spec it also reports the entries the chart would drop. ' + 'With updates it rejects a malformed layer and reports, op by op, whether ' + - 'each will apply (✓) or why not (✗), in the same report create_chart ' + - 'returns. create_chart runs the same checks and keeps nothing on an ' + - 'error, so do not call this before it; use it to check a spec in code or CI.', + 'each will apply (✓) or why not (✗), in the same report show returns. ' + + 'Call it before show and fix what it reports; nothing is kept between calls.', inputSchema: { ...assemblyInputShape, ...updatesShape, backend: backendEnum }, }, async (args: any) => { @@ -427,7 +429,7 @@ export function createServer(options: CreateServerOptions = {}): McpServer { 'matching spec: `chart` for a ChartAssemblyInput, `theme` for a ThemeSpec, ' + '`interaction` for an interaction_spec, ChartUpdate layers, reading a ' + 'mounted chart, linking charts, or a bespoke interaction; `board` for a ' + - 'create_board call: headline, chart choice, layout, links. Pass `section` ' + + 'board spec: headline, chart choice, layout, links. Pass `section` ' + 'with one "## " heading to get only that part; an unknown section lists ' + 'the headings. The same text is served as the flint://agent-skill, ' + 'flint://theme-skill, flint://interaction-skill, and flint://board-skill resources.', @@ -473,253 +475,44 @@ export function createServer(options: CreateServerOptions = {}): McpServer { }, ); - // --- charts and boards: built off screen, drawn by show (MCP App) -------- - const boards = options.boards ?? new BoardStore(); + // --- charts and boards: checked by validate_*, drawn by show (MCP App) --- + // Nothing is kept between calls: every tool builds the chart or board again from the spec it is given. const boardChart = boardChartShape(assemblyInputShape); const boardFields = boardFieldsShape(assemblyInputShape.theme_spec); + const chartSpec = z.object({ ...assemblyInputShape, ...updatesShape, ...viewShape }).describe('One chart: a ChartAssemblyInput with its update layers.'); + const boardSpec = z + .object({ + ...boardFields, + charts: z.array(boardChart).describe('The charts, in reading order: KPI tiles first, then the lead chart, then the charts that explain it.'), + link_spec: linkSpecShape.optional(), + grid: gridShape.optional(), + }) + .describe('A board of several charts under one headline: a dashboard, a comparison, an overview with its detail.'); const validateBoardChart = async (input: ChartAssemblyInput, updates: ChartUpdate[] | undefined) => validateChart(input, 'vegalite', { ...dataSourceOptions, roots: await clientRoots(), updates }); - /** A new board from create_board arguments: each chart checked, the ones with errors left off. */ - const buildBoard = async (args: any): Promise<{ board: Board; outcomes: ChartOutcome[] }> => { - const board = boards.create('board', { - title: args.title, - subtitle: args.subtitle, - source: args.source, - theme_spec: args.theme_spec, - columns: args.columns, - }); - const outcomes: ChartOutcome[] = []; - for (const chartArgs of args.charts as BoardChartArgs[]) { - const { chart, outcome } = await prepareChart(chartArgs, validateBoardChart, board); - outcomes.push(outcome); - if (chart) board.charts.push(chart); - } - board.link_spec = args.link_spec; - relink(board); - return { board, outcomes }; - }; - /** An agent write: the next version, and the report the model judges it by. Nothing is on screen until show. */ - const boardWrite = (fn: (args: any) => Promise<{ board: Board; outcomes: ChartOutcome[]; notes?: (string | undefined)[] }>) => - async (args: any) => { - try { - const { board, outcomes, notes = [] } = await fn(args); - relink(board); - const said = notes.filter((note): note is string => note !== undefined); - return { content: [{ type: 'text' as const, text: viewReport(board, outcomes, said) }] }; - } catch (err) { - return errorResult(err); - } - }; - /** A reader write from the newest card; a card an agent write has passed changes nothing. */ - const readerWrite = (fn: (board: Board, args: any) => void) => - async (args: any) => { - try { - const board = boards.get(args.id); - if (args.version !== board.version) { - return { - content: [{ type: 'text' as const, text: `Error: board ${board.id} is at version ${board.version}, not ${args.version}: change the newest card.` }], - structuredContent: { version: board.version }, - isError: true, - }; - } - fn(board, args); - return { - content: [{ type: 'text' as const, text: `version ${board.version}` }], - structuredContent: { version: board.version, board: boardSnapshot(board) }, - }; - } catch (err) { - return errorResult(err); - } - }; - const cardOnly = { ui: { resourceUri: VIEW_RESOURCE_URI, visibility: ['app' as const] } }; - const viewId = z.string().describe('The id create_chart or create_board returned.'); - /** A board by id; a chart's id is refused with what to call instead. */ - const boardById = (id: string): Board => { - const view = boards.get(id); - if (view.kind === 'chart') { - throw new Error(`${id} is a chart, not a board: change it with update_chart, or call create_board to show several charts together.`); - } - return view; + /** The chart or board a spec describes, checked; a chart spec is a board of one. */ + const assemble = (args: { chart?: unknown; board?: unknown }) => { + if ((args.chart === undefined) === (args.board === undefined)) throw new Error('Pass one of chart or board.'); + return args.chart !== undefined + ? assembleBoard({ charts: [{ ...(args.chart as BoardChartArgs), id: 'chart' }] }, 'chart', validateBoardChart) + : assembleBoard(args.board as BoardSpec, 'board', validateBoardChart); }; - const cardVersion = z.number().describe('The board version the card shows; a newer board refuses the change.'); server.registerTool( - 'create_chart', + 'validate_board', { - title: 'Create chart', + title: 'Validate board', description: - 'Build one Flint chart. Nothing is on screen yet: the result is a report of the chart (its encodings, ' + - 'interactions, and each update op as applied ✓ or not and why ✗) and its id. Fix what the report asks ' + - 'with update_chart, then call show once; the card draws the chart live with an editing panel. ' + - 'The editing panel does not make the chart respond to the reader: for hover, click, brush, or zoom, ' + - 'pass interaction_spec (list_interaction_presets has the presets for each chart type). ' + - 'Pass updates to show the chart in a state (emphasis, a note, a range). In a later turn, change it ' + - 'with update_chart and call show again: a new card shows the new version and earlier cards stay as ' + - 'they were. An invalid spec or update layer is an error and keeps nothing. ' + - 'What the user then does on the chart reaches you with their next message.', - inputSchema: { ...assemblyInputShape, ...updatesShape, ...viewShape }, - }, - boardWrite(async (args) => { - const { chart, outcome, errors } = await prepareChart({ ...args, id: 'chart' } as BoardChartArgs, validateBoardChart, {}); - if (!chart) throw new Error(`Chart spec has errors: ${errors}. Nothing was kept; fix the spec and call create_chart again.`); - const view = boards.create('chart'); - view.charts.push(chart); - return { board: view, outcomes: [outcome] }; - }), - ); - - server.registerTool( - 'create_board', - { - title: 'Create board', - description: - 'Build a board of several Flint charts: a dashboard, a comparison, ' + - 'an overview with its detail. The board has a headline, a deck and a source; each chart ' + - 'is a full chart spec with an id and a layout (span, height). link_spec connects the charts ' + - 'by the fields they share: ' + - 'a selection on one chart emphasizes the marks that share its values on the others. Nothing is on ' + - 'screen yet: fix what the report asks with add_chart, update_chart, remove_chart and update_board, ' + - 'then call show once. Use create_chart for a ' + - 'single chart. Before the first board, call get_flint_skill with skill "board". ' + - 'The result reports the layout, each chart (✓/✗ per update op), what each chart sends and receives, and a review ' + - 'of what the board should still fix; a chart with errors is left off the board.', - inputSchema: { - ...boardFields, - charts: z.array(boardChart).describe('The charts, in reading order: KPI tiles first, then the lead chart, then the charts that explain it.'), - link_spec: linkSpecShape.optional(), - }, - }, - boardWrite(buildBoard), - ); - - server.registerTool( - 'add_chart', - { - title: 'Add chart to board', - description: 'Add a chart to a board, at the end. An id already on the board is an error: use update_chart.', - inputSchema: { id: viewId, chart: boardChart }, - }, - boardWrite(async (args) => { - const board = boardById(args.id); - if (board.charts.some((chart) => chart.id === args.chart.id)) { - throw new Error(`Board ${board.id} already has a chart "${args.chart.id}"; call update_chart to change it.`); - } - const { chart, outcome } = await prepareChart(args.chart as BoardChartArgs, validateBoardChart, board); - if (chart) { - board.charts.push(chart); - placeAddedChart(board, chart); - boards.touch(board); - } - return { board, outcomes: [outcome] }; - }), - ); - - server.registerTool( - 'update_chart', - { - title: 'Update chart', - description: - 'Change a chart, or one chart on a board. Pass only the fields to replace ' + - '(chart_spec, data, interaction_spec, updates, layout, ...); each replaces the chart\'s field whole. ' + - 'A change with errors leaves the chart as it was. Nothing is on screen until show.', - inputSchema: { - id: viewId, - chart_id: z.string().optional().describe('The chart on a board to change; a chart from create_chart needs none.'), - ...boardChart.omit({ id: true }).partial().shape, - }, - }, - boardWrite(async (args) => { - const board = boards.get(args.id); - const charts = board.charts.map((chart) => chart.id).join(', '); - const chartId = args.chart_id ?? (board.kind === 'chart' ? board.charts[0].id : undefined); - if (chartId === undefined) throw new Error(`Board ${board.id} holds several charts: pass chart_id (${charts}).`); - const index = board.charts.findIndex((chart) => chart.id === chartId); - if (index < 0) throw new Error(`Board ${board.id} has no chart "${chartId}"; its charts: ${charts}.`); - const { chart, outcome } = await prepareChart(mergeChartArgs(board.charts[index], args), validateBoardChart, board); - const notes: (string | undefined)[] = []; - if (chart) { - board.charts[index] = chart; - if (args.layout !== undefined) notes.push(dropArrangement(board, `layout on ${chart.id}`)); - boards.touch(board); - } - return { board, outcomes: [outcome], notes }; - }), - ); - - server.registerTool( - 'remove_chart', - { - title: 'Remove chart from board', - description: 'Take a chart off a board.', - inputSchema: { id: viewId, chart_id: z.string() }, - }, - boardWrite(async (args) => { - const board = boardById(args.id); - board.charts = board.charts.filter((chart) => chart.id !== args.chart_id); - if (board.link_spec?.charts?.[args.chart_id]) { - const { [args.chart_id]: _gone, ...charts } = board.link_spec.charts; - board.link_spec = { ...board.link_spec, charts }; - } - if (board.grid) board.grid = board.grid.filter((item) => item.id !== args.chart_id); - boards.touch(board); - return { board, outcomes: [] }; - }), - ); - - server.registerTool( - 'update_board', - { - title: 'Update board', - description: 'Change a board\'s title, subtitle, source, theme, columns, chart order, or link_spec. Each field given replaces the board\'s.', - inputSchema: { - id: viewId, - ...boardFields, - order: z.array(z.string()).optional().describe('Chart ids in the new reading order; charts left out keep their place at the end.'), - link_spec: linkSpecShape.nullable().optional().describe('The fields the charts connect on; null unlinks them.'), - }, - }, - boardWrite(async (args) => { - const board = boardById(args.id); - for (const key of ['title', 'subtitle', 'source', 'theme_spec', 'columns'] as const) { - if (args[key] !== undefined) (board as any)[key] = args[key]; - } - const themeNote = args.theme_spec !== undefined && board.reader_theme - ? `The reader's theme (${themeName(board.reader_theme.theme)}) was replaced: theme_spec sets the board's theme again.` - : undefined; - if (args.theme_spec !== undefined) board.reader_theme = undefined; - if (args.order) { - const rank = (id: string) => { - const at = (args.order as string[]).indexOf(id); - return at < 0 ? Number.MAX_SAFE_INTEGER : at; - }; - board.charts = [...board.charts].sort((a, b) => rank(a.id) - rank(b.id)); - } - if (args.link_spec !== undefined) board.link_spec = args.link_spec ?? undefined; - const notes = [args.columns !== undefined || args.order ? dropArrangement(board, args.order ? 'order' : 'columns') : undefined, themeNote]; - boards.touch(board); - return { board, outcomes: [], notes }; - }), - ); - - registerAppTool( - server, - 'show', - { - title: 'Show chart or board', - description: - 'Put a chart or board on screen: a new card with its current version. Call it once a turn, after ' + - 'create_chart or create_board and any fixes; changes after it stay off screen until the next show. ' + - 'Earlier cards keep the version they showed.', - inputSchema: { id: viewId }, - _meta: { ui: { resourceUri: VIEW_RESOURCE_URI } }, + 'Check a board of several Flint charts without drawing it: the report gives the layout, each chart ' + + '(✓/✗ per update op), what each chart sends and receives under link_spec, and a review of what the ' + + 'board should still fix. Nothing is kept: fix the spec, check it again if needed, then pass the same ' + + 'board to show. Before the first board, call get_flint_skill with skill "board".', + inputSchema: boardSpec.shape, }, async (args: any) => { try { - const board = boards.get(args.id); - return { - content: [{ type: 'text' as const, text: shownText(board) }], - _meta: { flint: { board: boardSnapshot(board) } }, - }; + const { board, outcomes, notes } = await assemble({ board: args }); + return { content: [{ type: 'text' as const, text: viewReport(board, outcomes, notes) }] }; } catch (err) { return errorResult(err); } @@ -728,25 +521,34 @@ export function createServer(options: CreateServerOptions = {}): McpServer { registerAppTool( server, - 'restore_board', + 'show', { - title: 'Restore board', + title: 'Show chart or board', description: - 'For the board card only: the board as this server holds it, given the board the card holds. ' + - 'A server that lost it, as after a restart, takes the card\'s back under its own id; a newer board stays.', + 'Put a chart or a board on screen: pass the full spec as chart or as board, after validate_chart or ' + + 'validate_board report nothing left to fix. The card draws it live with an editing panel; the result ' + + 'is the same report. A spec with errors draws nothing. Nothing is kept: to change what is on screen, ' + + 'change the spec and call show again; a new card shows it and earlier cards stay as they were.', inputSchema: { - board: z.record(z.string(), z.any()).describe('The board as the card holds it, with its id.'), + chart: chartSpec.optional(), + board: boardSpec.optional(), }, - _meta: cardOnly, + _meta: { ui: { resourceUri: VIEW_RESOURCE_URI } }, }, async (args: any) => { try { - if (!args.board?.id || !Array.isArray(args.board.charts)) throw new Error('Nothing to restore: pass the board the card holds.'); - const board = boards.restore(args.board as Board); - relink(board); + const { board, outcomes, notes } = await assemble(args); + const failed = outcomes.filter((outcome) => !outcome.drawn); + if (failed.length > 0) { + const text = `Nothing was drawn: ${failed.map((outcome) => `${outcome.id} ${outcome.text}`).join('; ')}. Fix the spec and call show again.`; + return { content: [{ type: 'text' as const, text }], _meta: { flint: { error: text } }, isError: true }; + } + const snapshot = boardSnapshot(board); return { - content: [{ type: 'text' as const, text: `version ${board.version}` }], - structuredContent: { version: board.version, board: boardSnapshot(board) }, + content: [{ type: 'text' as const, text: viewReport(board, outcomes, notes, true) }], + // A small board also rides in structuredContent, which a host keeps when it draws the card again. + ...(fitsInResult(snapshot) ? { structuredContent: { flint: { board: snapshot } } } : {}), + _meta: { flint: { board: snapshot } }, }; } catch (err) { return errorResult(err); @@ -754,47 +556,6 @@ export function createServer(options: CreateServerOptions = {}): McpServer { }, ); - registerAppTool( - server, - 'set_board_theme', - { - title: 'Set board theme', - description: 'For the board card only: the theme the reader picked for every chart, or reset to go back to the agent\'s.', - inputSchema: { - id: viewId, - version: cardVersion, - theme: z.union([z.string(), z.record(z.string(), z.any()), z.null()]).optional().describe('A preset id, a ThemeSpec, or null for Flint\'s default.'), - reset: z.boolean().optional().describe('Go back to the agent\'s theme.'), - }, - _meta: cardOnly, - }, - readerWrite((board, args) => { - board.reader_theme = args.reset ? undefined : { theme: args.theme ?? null }; - }), - ); - - registerAppTool( - server, - 'set_board_layout', - { - title: 'Set board layout', - description: 'For the board card only: the arrangement the reader made, as a place on a 12-column grid for every chart, or null to go back to the rows.', - inputSchema: { - id: viewId, - version: cardVersion, - grid: z.array(z.object({ id: z.string(), x: z.number(), y: z.number(), w: z.number(), h: z.number() })).nullable(), - }, - _meta: cardOnly, - }, - readerWrite((board, args) => { - if (args.grid) { - const problem = gridProblem(args.grid, board.charts.map((chart) => chart.id)); - if (problem) throw new Error(`The arrangement does not fit the board: ${problem}.`); - } - board.grid = args.grid ?? undefined; - }), - ); - registerAppResource( server, 'view', diff --git a/packages/flint-mcp/src/tools/schemas.ts b/packages/flint-mcp/src/tools/schemas.ts index afa88065..ff3686d0 100644 --- a/packages/flint-mcp/src/tools/schemas.ts +++ b/packages/flint-mcp/src/tools/schemas.ts @@ -205,7 +205,7 @@ export const updatesShape = { ) .optional() .describe( - 'ChartUpdate layers the chart shows at open: state, where interaction_spec is behaviour. Call get_flint_skill with skill "interaction", section "Update the chart", before you write one. To change them, call update_chart with new layers, then show.', + 'ChartUpdate layers the chart shows at open: state, where interaction_spec is behaviour. Call get_flint_skill with skill "interaction", section "Update the chart", before you write one. To change them, pass the chart again with new layers to show.', ), }; diff --git a/packages/flint-mcp/tests/board.test.ts b/packages/flint-mcp/tests/board.test.ts index 5b2c77ca..1bdcf66d 100644 --- a/packages/flint-mcp/tests/board.test.ts +++ b/packages/flint-mcp/tests/board.test.ts @@ -1,8 +1,12 @@ import { describe, it, expect, beforeAll, afterAll } from 'vitest'; +import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'; import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import { VIEW_RESOURCE_URI, createServer } from '../src/server.js'; +import { RESULT_COPY_LIMIT } from '../src/board.js'; const rows = [ { country: 'Japan', region: 'Asia', gdp: 4.2, life: 84 }, @@ -43,49 +47,39 @@ afterAll(async () => { }); const text = (result: any): string => result.content[0].text; -const boardIdOf = (result: any): string => text(result).match(/^Board (board-[0-9a-f]+)/)![1]; - -/** The board as show hands it to its card. */ -async function shown(boardId: string): Promise { - const result: any = await client.callTool({ name: 'show', arguments: { id: boardId } }); - return result._meta.flint.board; -} +const check = (board: Record): Promise => client.callTool({ name: 'validate_board', arguments: board }); +const showBoard = (board: Record): Promise => client.callTool({ name: 'show', arguments: { board } }); describe('board tools', () => { - it('create_board opens the board view with every valid chart and reports what each chart links', async () => { - const result: any = await client.callTool({ - name: 'create_board', - arguments: { title: 'Countries', charts: [scatter, bars], link_spec: { fields: ['country', 'region'] } }, - }); + it('validate_board reports every chart and what each links, and opens no card; show draws the same board', async () => { + const spec = { title: 'Countries', charts: [scatter, bars], link_spec: { fields: ['country', 'region'] } }; + const result: any = await check(spec); expect(result.isError).toBeFalsy(); expect(text(result)).toContain('2 charts (countries, by-country)'); + expect(text(result)).toContain('Nothing is on screen: fix what this report asks in the spec, then call show with it.'); expect(text(result)).toContain('## countries'); expect(text(result)).toContain('Links (fields: country, region; one selection the whole board shares):'); expect(text(result)).toContain('✓ countries: sends region by select; receives region; leaves out country: its marks do not carry country'); expect(text(result)).toContain('✓ by-country: receives country; leaves out region: its marks do not carry region'); expect(text(result)).toContain('sends nothing: no interaction that selects'); expect(result._meta).toBeUndefined(); - const board = await shown(boardIdOf(result)); + + const shown: any = await showBoard(spec); + expect(text(shown)).toContain('The board is on screen in a new card.'); + expect(text(shown)).toContain('✓ countries: sends region by select'); + const board = shown._meta.flint.board; expect(board.charts.map((chart: any) => chart.id)).toEqual(['countries', 'by-country']); expect(board.linked['by-country']).toMatchObject({ sends: [], receives: ['country'] }); - expect(board.version).toBe(1); const { tools } = await client.listTools(); - for (const name of ['create_board', 'add_chart', 'update_chart', 'remove_chart', 'update_board']) { - expect((tools.find((entry) => entry.name === name) as any)._meta?.ui).toBeUndefined(); - } + expect((tools.find((entry) => entry.name === 'validate_board') as any)._meta?.ui).toBeUndefined(); const show = tools.find((tool) => tool.name === 'show') as any; expect(show._meta.ui.resourceUri).toBe(VIEW_RESOURCE_URI); expect(show._meta.ui.visibility).toBeUndefined(); - const restore = tools.find((tool) => tool.name === 'restore_board') as any; - expect(restore._meta.ui.visibility).toEqual(['app']); }); it('marks a chart that joins no field, honours receive: false, and names an unknown chart', async () => { - const result: any = await client.callTool({ - name: 'create_board', - arguments: { charts: [scatter, bars], link_spec: { fields: ['continent', 'region'], charts: { countries: { receive: false }, ghost: {} } } }, - }); + const result: any = await check({ charts: [scatter, bars], link_spec: { fields: ['continent', 'region'], charts: { countries: { receive: false }, ghost: {} } } }); expect(text(result)).toContain('✓ countries: sends region by select; leaves out continent: no field continent in its data; receives nothing (receive: false)'); expect(text(result)).toContain('✗ by-country: not linked; leaves out continent'); expect(text(result)).toContain('✗ ghost: not linked; no chart "ghost" among the linked charts'); @@ -93,84 +87,56 @@ describe('board tools', () => { it('links a chart once its marks carry the field', async () => { const clickable = { ...bars, interaction_spec: { interactions: [{ type: 'click-highlight' }] } }; - const result: any = await client.callTool({ - name: 'create_board', - arguments: { charts: [scatter, clickable], link_spec: { fields: ['country'] } }, - }); + const result: any = await check({ charts: [scatter, clickable], link_spec: { fields: ['country'] } }); expect(text(result)).toContain('✗ countries: not linked; leaves out country: its marks do not carry country; encode it, on detail'); const detailed = { ...scatter, chart_spec: { ...scatter.chart_spec, encodings: { ...scatter.chart_spec.encodings, detail: 'country' } } }; - const fixed: any = await client.callTool({ - name: 'create_board', - arguments: { charts: [detailed, clickable], link_spec: { fields: ['country'] } }, - }); + const fixed: any = await check({ charts: [detailed, clickable], link_spec: { fields: ['country'] } }); expect(text(fixed)).toContain('✓ countries: sends country by select; receives country'); expect(text(fixed)).toContain('✓ by-country: sends country by click-highlight; receives country'); const hovering = { ...detailed, interaction_spec: { interactions: [{ type: 'select' }, { type: 'hover-group-focus', options: { groupBy: 'region' } }] } }; - const both: any = await client.callTool({ - name: 'create_board', - arguments: { charts: [hovering, clickable], link_spec: { fields: ['country', 'region'] } }, - }); + const both: any = await showBoard({ charts: [hovering, clickable], link_spec: { fields: ['country', 'region'] } }); expect(text(both)).toContain('✓ countries: sends country + region by select, region by hover-group-focus (hover); receives country, region'); - expect((await shown(boardIdOf(both))).linked.countries.gestures['hover-group-focus']).toEqual({ preset: 'hover-group-focus', fields: ['region'], hover: true }); + expect(both._meta.flint.board.linked.countries.gestures['hover-group-focus']).toEqual({ preset: 'hover-group-focus', fields: ['region'], hover: true }); }); - it('leaves a chart with errors off the board and says why', async () => { - const result: any = await client.callTool({ - name: 'create_board', - arguments: { charts: [scatter, { ...bars, chart_spec: { ...bars.chart_spec, chartType: 'Not A Chart' } }] }, - }); + it('validate_board leaves a chart with errors off and says why; show draws nothing for it', async () => { + const spec = { charts: [scatter, { ...bars, chart_spec: { ...bars.chart_spec, chartType: 'Not A Chart' } }] }; + const result: any = await check(spec); expect(text(result)).toContain('1 chart (countries)'); expect(text(result)).toMatch(/## by-country\n✗ not drawn: /); + const shown: any = await showBoard(spec); + expect(shown.isError).toBe(true); + expect(text(shown)).toMatch(/^Nothing was drawn: by-country ✗ not drawn: .*Fix the spec and call show again\.$/); + expect(shown._meta.flint.error).toBe(text(shown)); }); - it('add_chart, update_chart, remove_chart and update_board change the board off screen, and show shows its current version', async () => { - const created: any = await client.callTool({ name: 'create_board', arguments: { charts: [scatter] } }); - const id = boardIdOf(created); - expect(text(created)).toContain('Version 1, not on screen yet'); - const first = await shown(id); - - const added: any = await client.callTool({ name: 'add_chart', arguments: { id: id, chart: bars } }); - expect(text(added)).toContain('2 charts (countries, by-country)'); - expect(text(added)).toContain('Version 2, not on screen yet'); - expect(added._meta).toBeUndefined(); - const show: any = await client.callTool({ name: 'show', arguments: { id: id } }); - expect(text(show)).toContain(`Board ${id} version 2 is on screen in a new card`); - expect(show._meta.flint.board.charts).toHaveLength(2); - expect(first.charts).toHaveLength(1); - - const duplicate: any = await client.callTool({ name: 'add_chart', arguments: { id: id, chart: bars } }); - expect(duplicate.isError).toBe(true); - - const updated: any = await client.callTool({ - name: 'update_chart', - arguments: { id: id, chart_id: 'by-country', chart_spec: { ...bars.chart_spec, title: 'Income by country' } }, - }); - expect(text(updated)).toContain('Chart "Income by country"'); - const chart = (await shown(id)).charts.find((entry: any) => entry.id === 'by-country'); - expect(chart.input.chart_spec.title).toBe('Income by country'); - expect(chart.input.data.values).toHaveLength(4); - - const broken: any = await client.callTool({ - name: 'update_chart', - arguments: { id: id, chart_id: 'by-country', chart_spec: { ...bars.chart_spec, chartType: 'Not A Chart' } }, - }); - expect(text(broken)).toContain('✗ not drawn'); - expect((await shown(id)).charts[1].input.chart_spec.title).toBe('Income by country'); - - const reordered: any = await client.callTool({ name: 'update_board', arguments: { id: id, order: ['by-country'], link_spec: { fields: ['country'], charts: { 'by-country': { send: false } } } } }); - expect((await shown(id)).charts.map((entry: any) => entry.id)).toEqual(['by-country', 'countries']); - - const removed: any = await client.callTool({ name: 'remove_chart', arguments: { id: id, chart_id: 'by-country' } }); - expect((await shown(id)).charts.map((entry: any) => entry.id)).toEqual(['countries']); - expect((await shown(id)).link_spec).toEqual({ fields: ['country'], charts: {} }); - expect(Object.keys((await shown(id)).linked)).toEqual(['countries']); + it('keeps nothing between calls: each call builds the board from its spec alone', async () => { + const first: any = await showBoard({ title: 'T', charts: [scatter] }); + const second: any = await showBoard({ title: 'T', charts: [scatter, bars] }); + expect(first._meta.flint.board.charts).toHaveLength(1); + expect(second._meta.flint.board.charts).toHaveLength(2); + expect(second._meta.flint.board.id).not.toBe(first._meta.flint.board.id); + const elsewhere = createServer(); + const [clientSide, serverSide] = InMemoryTransport.createLinkedPair(); + await elsewhere.connect(serverSide); + const other = new Client({ name: 'another-process', version: '0.0.0' }); + await other.connect(clientSide); + try { + const again: any = await other.callTool({ name: 'show', arguments: { board: { title: 'T', charts: [scatter, bars] } } }); + expect(again._meta.flint.board.charts.map((chart: any) => chart.id)).toEqual(['countries', 'by-country']); + } finally { + await other.close(); + await elsewhere.close(); + } }); - it('tells the model to create a board when the id is unknown', async () => { - const result: any = await client.callTool({ name: 'add_chart', arguments: { id: 'board-missing', chart: bars } }); - expect(result.isError).toBe(true); - expect(text(result)).toContain('Call create_chart or create_board to build it again, then show.'); + it('show takes one of chart or board', async () => { + const neither: any = await client.callTool({ name: 'show', arguments: {} }); + expect(neither.isError).toBe(true); + expect(text(neither)).toContain('Pass one of chart or board.'); + const both: any = await client.callTool({ name: 'show', arguments: { chart: { data: bars.data, chart_spec: bars.chart_spec }, board: { charts: [bars] } } }); + expect(both.isError).toBe(true); }); it('reports the layout and what the board should still fix', async () => { @@ -180,11 +146,8 @@ describe('board tools', () => { data: { values: rows.map((row, at) => ({ ...row, year: 2020 + at })) }, chart_spec: { chartType: 'Line Chart', encodings: { x: 'year', y: 'gdp', color: 'region' } }, }; - const result: any = await client.callTool({ - name: 'create_board', - arguments: { charts: [kpi('k1', 'Sales'), kpi('k2', 'Margin'), kpi('k3', 'Churn'), trend, scatter, { ...bars, theme_spec: 'nyt' }] }, - }); - const report = text(result); + const charts = [kpi('k1', 'Sales'), kpi('k2', 'Margin'), kpi('k3', 'Churn'), trend, scatter, { ...bars, theme_spec: 'nyt' }]; + const report = text(await check({ charts })); expect(report).toContain('- row 1, KPI tiles (compact): k1 (a third), k2 (a third), k3 (a third)'); expect(report).toContain('- row 2 (tall): trend (full width)'); expect(report).toContain('- row 3 (standard): countries (half), by-country (half)'); @@ -192,14 +155,10 @@ describe('board tools', () => { expect(report).toContain('- No title on trend:'); expect(report).toContain('- trend, countries colour by region'); - const id = boardIdOf(result); - const themed: any = await client.callTool({ name: 'update_board', arguments: { id: id, title: 'Countries', subtitle: 'GDP and life expectancy', theme_spec: 'economist' } }); - expect(text(themed)).toContain('Charts set their own themes'); - expect((await shown(id)).theme_spec).toBe('economist'); - expect((await shown(id)).charts.find((chart: any) => chart.id === 'countries').input.theme_spec).toBeUndefined(); - - const narrowed: any = await client.callTool({ name: 'update_chart', arguments: { id: id, chart_id: 'trend', layout: { span: 1, height: 'compact' } } }); - expect(text(narrowed)).toContain('- row 2 (standard): trend (half), countries (half)'); + const themed = text(await check({ title: 'Countries', subtitle: 'GDP and life expectancy', theme_spec: 'economist', charts })); + expect(themed).toContain('Charts set their own themes'); + const narrowed = text(await check({ charts: [kpi('k1', 'Sales'), { ...trend, layout: { span: 1, height: 'compact' } }, scatter] })); + expect(narrowed).toContain('- row 2 (standard): trend (half), countries (half)'); }); it('splits five KPI tiles three and two, and leaves a measure on colour alone', async () => { @@ -209,135 +168,72 @@ describe('board tools', () => { data: { values: rows.map((row) => ({ ...row, year: '2025' })) }, chart_spec: { chartType: 'Heatmap', title: id, encodings: { x: 'year', y: 'country', color: 'gdp' } }, }); - const result: any = await client.callTool({ - name: 'create_board', - arguments: { title: 'T', subtitle: 'S', charts: [kpi('a'), kpi('b'), kpi('c'), kpi('d'), kpi('e'), heat('h1'), heat('h2')] }, - }); - const report = text(result); + const report = text(await check({ title: 'T', subtitle: 'S', charts: [kpi('a'), kpi('b'), kpi('c'), kpi('d'), kpi('e'), heat('h1'), heat('h2')] })); expect(report).toContain('- row 1, KPI tiles (compact): a (a third), b (a third), c (a third)'); expect(report).toContain('- row 2, KPI tiles (compact): d (half), e (half)'); expect(report).not.toContain('colour by gdp'); }); - it('keeps the arrangement the reader saves until the agent sets the rows again', async () => { - const created: any = await client.callTool({ name: 'create_board', arguments: { title: 'T', subtitle: 'S', charts: [scatter, bars] } }); - const id = boardIdOf(created); + it('keeps the reader\'s arrangement passed as grid, fitted to the charts the board has now', async () => { const grid = [{ id: 'by-country', x: 0, y: 0, w: 12, h: 17 }, { id: 'countries', x: 0, y: 17, w: 6, h: 17 }]; + const kept: any = await showBoard({ title: 'T', subtitle: 'S', charts: [scatter, bars], grid }); + expect(kept._meta.flint.board.grid).toEqual(grid); + expect(text(kept)).toContain('Arranged on a 12-column grid (grid), as the reader left it; keep passing it.'); + expect(text(kept)).toContain('- by-country: columns 1–12, rows 1–17 (full width, 340px tall)'); - const stale: any = await client.callTool({ name: 'set_board_layout', arguments: { id: id, version: 7, grid } }); - expect(stale.isError).toBe(true); - const clash: any = await client.callTool({ name: 'set_board_layout', arguments: { id: id, version: 1, grid: [grid[0], { ...grid[1], y: 5 }] } }); - expect(text(clash)).toContain('overlaps another chart'); - const missing: any = await client.callTool({ name: 'set_board_layout', arguments: { id: id, version: 1, grid: [grid[0]] } }); - expect(text(missing)).toContain('no place for countries'); - - const saved: any = await client.callTool({ name: 'set_board_layout', arguments: { id: id, version: 1, grid } }); - expect(saved.structuredContent.board.grid).toEqual(grid); - expect(saved.structuredContent.version).toBe(1); - - const added: any = await client.callTool({ name: 'add_chart', arguments: { id: id, chart: { ...bars, id: 'more' } } }); - expect(text(added)).toContain('Arranged by the reader'); - expect(text(added)).toContain('- by-country: columns 1–12, rows 1–17 (full width, 340px tall)'); + const added: any = await check({ title: 'T', subtitle: 'S', charts: [scatter, bars, { ...bars, id: 'more' }], grid }); expect(text(added)).toContain('- more: columns 1–6, rows 35–51'); - const retitled: any = await client.callTool({ name: 'update_chart', arguments: { id: id, chart_id: 'more', chart_spec: { ...bars.chart_spec, title: 'More' } } }); - expect(text(retitled)).toContain('Arranged by the reader'); + const fewer: any = await check({ title: 'T', subtitle: 'S', charts: [scatter], grid }); + expect(text(fewer)).not.toContain('by-country'); + expect(text(fewer)).toContain('- countries: columns 1–6, rows 18–34'); - const removed: any = await client.callTool({ name: 'remove_chart', arguments: { id: id, chart_id: 'more' } }); - expect(text(removed)).not.toContain('- more:'); - const relaid: any = await client.callTool({ name: 'update_chart', arguments: { id: id, chart_id: 'countries', layout: { span: 2 } } }); - expect(text(relaid)).toContain("The reader's arrangement was dropped: layout on countries"); - expect((await shown(id)).grid).toBeUndefined(); + const clash: any = await check({ title: 'T', subtitle: 'S', charts: [scatter, bars], grid: [grid[0], { ...grid[1], y: 5 }] }); + expect(text(clash)).toContain('The grid was dropped for the rows: by-country overlaps another chart.'); + expect(text(clash)).toContain('- row 1 (standard): countries (half), by-country (half)'); }); - it('holds a Table of rows and a chart opened as its table, and a change of view keeps the reader\'s arrangement', async () => { + it('holds a Table of rows and a chart opened as its table', async () => { const table = { id: 'list', data: { values: rows }, chart_spec: { chartType: 'Table', title: 'Countries', encodings: {} } }; - const created: any = await client.callTool({ - name: 'create_board', - arguments: { title: 'T', subtitle: 'S', charts: [table, { ...bars, view: 'table' }], link_spec: { fields: ['country'] } }, - }); - expect(text(created)).toContain('Opens as the table of the rows it draws'); - expect(text(created)).toContain('list: receives country'); - const id = boardIdOf(created); - expect((await shown(id)).charts.map((chart: any) => chart.view)).toEqual([undefined, 'table']); - - const grid = [{ id: 'list', x: 0, y: 0, w: 12, h: 17 }, { id: 'by-country', x: 0, y: 17, w: 6, h: 17 }]; - await client.callTool({ name: 'set_board_layout', arguments: { id: id, version: 1, grid } }); - const back: any = await client.callTool({ name: 'update_chart', arguments: { id: id, chart_id: 'by-country', view: 'chart' } }); - expect(text(back)).toContain('Arranged by the reader'); - const board = (await shown(id)); - expect(board.grid).toEqual(grid); - expect(board.charts.find((chart: any) => chart.id === 'by-country').view).toBeUndefined(); + const shown: any = await showBoard({ title: 'T', subtitle: 'S', charts: [table, { ...bars, view: 'table' }], link_spec: { fields: ['country'] } }); + expect(text(shown)).toContain('Opens as the table of the rows it draws'); + expect(text(shown)).toContain('list: receives country'); + expect(shown._meta.flint.board.charts.map((chart: any) => chart.view)).toEqual([undefined, 'table']); - const encoded: any = await client.callTool({ name: 'add_chart', arguments: { id: id, chart: { ...table, id: 'bad', chart_spec: { chartType: 'Table', encodings: { x: 'country' } } } } }); + const encoded: any = await check({ charts: [{ ...table, id: 'bad', chart_spec: { chartType: 'Table', encodings: { x: 'country' } } }] }); expect(text(encoded)).toContain('Table takes no encodings'); }); - it('keeps the theme the reader picks until the agent sets the board\'s theme', async () => { - const created: any = await client.callTool({ name: 'create_board', arguments: { title: 'T', subtitle: 'S', theme_spec: 'economist', charts: [scatter, bars] } }); - const id = boardIdOf(created); - const picked: any = await client.callTool({ name: 'set_board_theme', arguments: { id: id, version: 1, theme: 'nyt' } }); - expect(picked.structuredContent.board.reader_theme).toEqual({ theme: 'nyt' }); - const added: any = await client.callTool({ name: 'add_chart', arguments: { id: id, chart: { ...bars, id: 'more' } } }); - expect(text(added)).toContain('The reader picked the theme nyt for every chart; keep it.'); - - const plain: any = await client.callTool({ name: 'set_board_theme', arguments: { id: id, version: 2, theme: null } }); - expect(plain.structuredContent.board.reader_theme).toEqual({ theme: null }); - const back: any = await client.callTool({ name: 'set_board_theme', arguments: { id: id, version: 2, reset: true } }); - expect(back.structuredContent.board.reader_theme).toBeUndefined(); - - await client.callTool({ name: 'set_board_theme', arguments: { id: id, version: 2, theme: 'swiss' } }); - const replaced: any = await client.callTool({ name: 'update_board', arguments: { id: id, theme_spec: 'datawrapper' } }); - expect(text(replaced)).toContain("The reader's theme (swiss) was replaced: theme_spec sets the board's theme again."); - expect((await shown(id)).reader_theme).toBeUndefined(); - }); - - it('keeps nothing a passed card sends, and tells it the newest version', async () => { - const created: any = await client.callTool({ name: 'create_board', arguments: { title: 'T', subtitle: 'S', charts: [scatter] } }); - const id = boardIdOf(created); - const first = await shown(id); - await client.callTool({ name: 'add_chart', arguments: { id: id, chart: bars } }); - const theme: any = await client.callTool({ name: 'set_board_theme', arguments: { id: id, version: 1, theme: 'nyt' } }); - expect(theme.isError).toBe(true); - expect(theme.structuredContent).toEqual({ version: 2 }); - const layout: any = await client.callTool({ name: 'set_board_layout', arguments: { id: id, version: 1, grid: null } }); - expect(layout.structuredContent).toEqual({ version: 2 }); - - const held: any = await client.callTool({ name: 'restore_board', arguments: { board: first } }); - expect(held.structuredContent.version).toBe(2); - expect(held.structuredContent.board.charts).toHaveLength(2); - }); - it('flags a chart that stacks repeated rows as slices, and not once it sums them', async () => { const monthly = [1, 2, 3].flatMap((month) => rows.map((row) => ({ ...row, month }))); const sliced = { id: 'sliced', data: { values: monthly }, chart_spec: { chartType: 'Bar Chart', title: 'GDP', encodings: { y: 'country', x: 'gdp', color: 'region' } } }; - const result: any = await client.callTool({ name: 'create_board', arguments: { title: 'T', subtitle: 'S', charts: [sliced] } }); - expect(text(result)).toContain('sliced draws 12 rows as 4 country × region groups, so each mark is a stack of slices, one per row: sum the rows first, or set encodings.x.aggregate to "sum"'); + expect(text(await check({ title: 'T', subtitle: 'S', charts: [sliced] }))).toContain('sliced draws 12 rows as 4 country × region groups, so each mark is a stack of slices, one per row: sum the rows first, or set encodings.x.aggregate to "sum"'); const summed = { ...sliced, chart_spec: { ...sliced.chart_spec, encodings: { y: 'country', x: { field: 'gdp', aggregate: 'sum' }, color: 'region' } } }; - const fixed: any = await client.callTool({ name: 'create_board', arguments: { title: 'T', subtitle: 'S', charts: [summed] } }); - expect(text(fixed)).not.toContain('stack of slices'); + expect(text(await check({ title: 'T', subtitle: 'S', charts: [summed] }))).not.toContain('stack of slices'); }); - it('takes back a board a restarted server lost, under its own id', async () => { - const created: any = await client.callTool({ name: 'create_board', arguments: { title: 'T', subtitle: 'S', charts: [scatter, bars] } }); - const snapshot = await shown(boardIdOf(created)); - const restarted = createServer(); - const [clientSide, serverSide] = InMemoryTransport.createLinkedPair(); - await restarted.connect(serverSide); - const fresh = new Client({ name: 'after-restart', version: '0.0.0' }); - await fresh.connect(clientSide); + it('show also puts a small inline chart in structuredContent, for a host that drops _meta', async () => { + const result: any = await client.callTool({ name: 'show', arguments: { chart: { data: bars.data, semantic_types: bars.semantic_types, chart_spec: bars.chart_spec } } }); + expect(text(result)).toContain('The chart is on screen in a new card.'); + expect(result.structuredContent.flint.board).toEqual(result._meta.flint.board); + expect(result.structuredContent.flint.board.charts[0].input.data.values).toHaveLength(4); + }); + + it('show keeps a large chart, or one read from a local file, out of structuredContent', async () => { + const many = Array.from({ length: 200 }, (_, i) => ({ country: `Country ${i}`, gdp: i * 1000 })); + const big: any = await client.callTool({ name: 'show', arguments: { chart: { data: { values: many }, semantic_types: bars.semantic_types, chart_spec: bars.chart_spec } } }); + expect(JSON.stringify(big._meta.flint.board).length).toBeGreaterThan(RESULT_COPY_LIMIT); + expect(big.structuredContent).toBeUndefined(); + expect(big._meta.flint.board.charts[0].input.data.values).toHaveLength(200); + + const dir = mkdtempSync(join(tmpdir(), 'flint-show-')); try { - const lost: any = await fresh.callTool({ name: 'update_chart', arguments: { id: snapshot.id, chart_id: 'by-country', chart_spec: { ...bars.chart_spec, title: 'X' } } }); - expect(lost.isError).toBe(true); - const back: any = await fresh.callTool({ name: 'restore_board', arguments: { board: snapshot } }); - expect(back.structuredContent.board.id).toBe(snapshot.id); - const updated: any = await fresh.callTool({ name: 'update_chart', arguments: { id: snapshot.id, chart_id: 'by-country', chart_spec: { ...bars.chart_spec, title: 'X' } } }); - expect(updated.isError).toBeFalsy(); - expect(text(updated)).toContain('Chart "X"'); - const nothing: any = await fresh.callTool({ name: 'restore_board', arguments: { board: {} } }); - expect(nothing.isError).toBe(true); + const file = join(dir, 'gdp.json'); + writeFileSync(file, JSON.stringify(rows)); + const local: any = await client.callTool({ name: 'show', arguments: { chart: { data: { url: file }, semantic_types: bars.semantic_types, chart_spec: bars.chart_spec } } }); + expect(local.structuredContent).toBeUndefined(); + expect(local._meta.flint.board.charts[0].input.data.values).toHaveLength(rows.length); } finally { - await fresh.close(); - await restarted.close(); + rmSync(dir, { recursive: true, force: true }); } }); diff --git a/packages/flint-mcp/tests/http.test.ts b/packages/flint-mcp/tests/http.test.ts index 64fc57ce..a6ae4b66 100644 --- a/packages/flint-mcp/tests/http.test.ts +++ b/packages/flint-mcp/tests/http.test.ts @@ -45,35 +45,25 @@ describe('MCP server over HTTP (stateless streamable transport)', () => { const { tools } = await client.listTools(); const names = tools.map((t) => t.name).sort(); expect(names).toEqual([ - 'add_chart', 'compile_chart', - 'create_board', - 'create_chart', 'get_flint_skill', 'list_chart_types', 'list_interaction_presets', 'list_themes', - 'remove_chart', 'render_chart', - 'restore_board', - 'set_board_layout', - 'set_board_theme', 'show', - 'update_board', - 'update_chart', + 'validate_board', 'validate_chart', ]); }); - it('shows a chart built in an earlier request', async () => { - const created: any = await client.callTool({ - name: 'create_chart', - arguments: { data: { values: [{ region: 'East', revenue: 120 }] }, chart_spec: { chartType: 'Bar Chart', encodings: { x: 'region', y: 'revenue' } } }, + it('shows a chart from the spec in the request alone', async () => { + const shown: any = await client.callTool({ + name: 'show', + arguments: { chart: { data: { values: [{ region: 'East', revenue: 120 }] }, chart_spec: { chartType: 'Bar Chart', encodings: { x: 'region', y: 'revenue' } } } }, }); - const id = created.content[0].text.match(/^Chart (chart-[0-9a-f]+)/)[1]; - const shown: any = await client.callTool({ name: 'show', arguments: { id } }); expect(shown.isError).toBeFalsy(); - expect(shown._meta.flint.board).toMatchObject({ id, kind: 'chart', version: 1 }); + expect(shown._meta.flint.board).toMatchObject({ kind: 'chart', charts: [{ id: 'chart' }] }); }); it('renders a chart through the HTTP transport', async () => { diff --git a/packages/flint-mcp/tests/server.test.ts b/packages/flint-mcp/tests/server.test.ts index 5d1eb3e7..53bd144b 100644 --- a/packages/flint-mcp/tests/server.test.ts +++ b/packages/flint-mcp/tests/server.test.ts @@ -7,7 +7,7 @@ import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'; import { ListRootsRequestSchema } from '@modelcontextprotocol/sdk/types.js'; import { pathToFileURL } from 'node:url'; import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { createServer } from '../src/server.js'; +import { createServer, skillSection } from '../src/server.js'; const barChart = { data: { @@ -51,13 +51,11 @@ afterAll(async () => { await server?.close(); }); -/** create_chart, then show: the report, and the chart as the card is handed it. */ +/** show with a chart spec: the report, and the chart as the card is handed it. */ async function drawChart(args: Record, on: Client = client): Promise<{ created: any; chart?: any }> { - const created: any = await on.callTool({ name: 'create_chart', arguments: args }); + const created: any = await on.callTool({ name: 'show', arguments: { chart: args } }); if (created.isError) return { created }; - const id = created.content[0].text.match(/^Chart (chart-[0-9a-f]+)/)[1]; - const shown: any = await on.callTool({ name: 'show', arguments: { id } }); - return { created, chart: shown._meta.flint.board.charts[0] }; + return { created, chart: created._meta.flint.board.charts[0] }; } describe('MCP server with client roots', () => { @@ -93,22 +91,14 @@ describe('MCP server', () => { const { tools } = await client.listTools(); const names = tools.map((t) => t.name).sort(); expect(names).toEqual([ - 'add_chart', 'compile_chart', - 'create_board', - 'create_chart', 'get_flint_skill', 'list_chart_types', 'list_interaction_presets', 'list_themes', - 'remove_chart', 'render_chart', - 'restore_board', - 'set_board_layout', - 'set_board_theme', 'show', - 'update_board', - 'update_chart', + 'validate_board', 'validate_chart', ]); }); @@ -145,6 +135,15 @@ describe('MCP server', () => { expect(bad.content[0].text).toContain('"Update the chart"'); }); + it('skillSection takes a heading by its start, or without case and punctuation, when only one heading fits', () => { + const text = '# Skill\n\n## Step 4 — write the spec\nA\n\n## Link charts, and more\nB\n\n## Update the chart\nC\n\n## Update the board\nD\n'; + expect(skillSection(text, 'step 4 write the spec')).toBe('## Step 4 — write the spec\nA\n'); + expect(skillSection(text, '## Link charts')).toBe('## Link charts, and more\nB\n'); + expect(() => skillSection(text, 'Update')).toThrow('No section "Update"'); + expect(() => skillSection(text, 'Upd')).toThrow('No section "Upd"'); + expect(skillSection(text, 'Update the board')).toBe('## Update the board\nD\n'); + }); + it('render_chart returns inline PNG image content', async () => { const res: any = await client.callTool({ name: 'render_chart', @@ -283,7 +282,7 @@ describe('MCP server', () => { expect(dropped[0].message).toContain('"legend-toggle" requires a discrete legend; Bar Chart has none'); }); - it('validate_chart and create_chart take updates beside the input, and reject a malformed layer', async () => { + it('validate_chart and show take updates beside the input, and reject a malformed layer', async () => { const base = { data: { values: [{ region: 'East', revenue: 120 }, { region: 'West', revenue: 90 }] }, semantic_types: { revenue: 'Quantity' }, @@ -318,13 +317,11 @@ describe('MCP server', () => { const view = await drawChart({ ...base, updates: [layer] }); expect(view.created.isError).toBeFalsy(); expect(view.created.content[0].text).toContain('Agent updates (yours):\n- agent:\n ✓ emphasizes marks where region = East'); - expect(view.created.structuredContent).toBeUndefined(); - expect(view.created._meta).toBeUndefined(); expect(view.chart.updates).toEqual([layer]); const viewBad = await drawChart({ ...base, updates: [{ id: '', ops: [] }] }); expect(viewBad.created.isError).toBe(true); - expect(viewBad.created.content[0].text).toContain('Chart spec has errors: updates[0]: "id" must be a non-empty string.'); - expect(viewBad.created.content[0].text).toContain('Nothing was kept; fix the spec and call create_chart again.'); + expect(viewBad.created.content[0].text).toContain('Nothing was drawn: chart ✗ not drawn: updates[0]: "id" must be a non-empty string.'); + expect(viewBad.created.content[0].text).toContain('Fix the spec and call show again.'); const viewOff = await drawChart({ ...base, updates: [layer, shorthand] }); expect(viewOff.created.isError).toBeFalsy(); expect(viewOff.chart.updates).toEqual([layer, shorthand]); @@ -332,7 +329,7 @@ describe('MCP server', () => { expect(viewOff.created.content[0].text).toContain('✗ overlay "goal"'); }); - it('create_chart opens a chart as its table when asked, and draws a Table chart type as a table', async () => { + it('show opens a chart as its table when asked, and draws a Table chart type as a table', async () => { const data = { values: [{ region: 'East', revenue: 120 }, { region: 'West', revenue: 90 }] }; const bars = { data, chart_spec: { chartType: 'Bar Chart', encodings: { x: 'region', y: 'revenue' } } }; const asTable = await drawChart({ ...bars, view: 'table' }); @@ -346,36 +343,26 @@ describe('MCP server', () => { expect(table.chart.view).toBeUndefined(); }); - it('create_chart keeps nothing for an invalid spec', async () => { + it('show draws nothing for an invalid spec, and the card shows why', async () => { const res: any = await client.callTool({ - name: 'create_chart', - arguments: { ...barChart, chart_spec: { ...barChart.chart_spec, chartType: 'Not A Real Chart' } }, + name: 'show', + arguments: { chart: { ...barChart, chart_spec: { ...barChart.chart_spec, chartType: 'Not A Real Chart' } } }, }); expect(res.isError).toBe(true); expect(res.content[0].text).toContain('Not A Real Chart'); - expect(res.content[0].text).toContain('call create_chart again'); - expect(res._meta).toBeUndefined(); + expect(res.content[0].text).toContain('call show again'); + expect(res._meta).toEqual({ flint: { error: res.content[0].text } }); }); - it('builds a chart off screen, changes it by id, and shows each version in a new card', async () => { - const created: any = await client.callTool({ name: 'create_chart', arguments: barChart }); - expect(created.content[0].text).toMatch(/^Chart chart-[0-9a-f]+, version 1, not on screen yet/); - const id = created.content[0].text.match(/^Chart (chart-[0-9a-f]+)/)[1]; - const first: any = await client.callTool({ name: 'show', arguments: { id } }); - expect(first.content[0].text).toContain(`Chart ${id} version 1 is on screen in a new card`); - expect(first._meta.flint.board).toMatchObject({ id, kind: 'chart', version: 1 }); - - const retitled: any = await client.callTool({ name: 'update_chart', arguments: { id, chart_spec: { ...barChart.chart_spec, title: 'Revenue' } } }); - expect(retitled.content[0].text).toMatch(/^Chart chart-[0-9a-f]+, version 2, not on screen yet/); - const second: any = await client.callTool({ name: 'show', arguments: { id } }); + it('validate_chart checks a chart and keeps nothing; show draws the spec it is given, each in a new card', async () => { + const checked: any = await client.callTool({ name: 'validate_chart', arguments: { ...barChart, backend: 'vegalite' } }); + expect(checked.content[1].text).toContain('Bar Chart'); + const first: any = await client.callTool({ name: 'show', arguments: { chart: barChart } }); + expect(first.content[0].text).toContain('The chart is on screen in a new card.'); + expect(first._meta.flint.board).toMatchObject({ kind: 'chart', charts: [{ id: 'chart' }] }); + const second: any = await client.callTool({ name: 'show', arguments: { chart: { ...barChart, chart_spec: { ...barChart.chart_spec, title: 'Revenue' } } } }); expect(second._meta.flint.board.charts[0].input.chart_spec.title).toBe('Revenue'); expect(first._meta.flint.board.charts[0].input.chart_spec.title).toBe(barChart.chart_spec.title); - - for (const [name, args] of [['add_chart', { id, chart: { id: 'more', ...barChart } }], ['remove_chart', { id, chart_id: 'chart' }], ['update_board', { id, title: 'T' }]] as const) { - const refused: any = await client.callTool({ name, arguments: args }); - expect(refused.isError).toBe(true); - expect(refused.content[0].text).toContain(`${id} is a chart, not a board`); - } }); it('a misshapen op is rejected with its shape, and the schema lists every op shape', async () => { @@ -394,17 +381,16 @@ describe('MCP server', () => { { op: 'set-annotation', annotations: [{ kind: 'rule', x: '2022-12-01', label: 'ChatGPT launch' }] }, ]) { const bad: any = await client.callTool({ - name: 'create_chart', - arguments: { ...base, updates: [{ id: 'agent', ops: [op] }] }, + name: 'show', + arguments: { chart: { ...base, updates: [{ id: 'agent', ops: [op] }] } }, }); expect(bad.isError).toBe(true); expect(bad.content[0].text).toContain('set-annotation has a missing or malformed "target". Shape:'); } const { tools } = await client.listTools(); - const view = tools.find((tool) => tool.name === 'create_chart')!; + const view = tools.find((tool) => tool.name === 'show')!; const schemaText = JSON.stringify(view.inputSchema); expect(schemaText).toContain("set-annotation { target: UpdateTarget, value: { text, anchor?: 'segment' | 'point' } | null }"); - expect(view.description).toContain('pass interaction_spec'); }); it('render_chart surfaces assembly errors as isError', async () => { @@ -579,7 +565,7 @@ describe('MCP server', () => { ); expect(canvasSkill.startsWith(`${repoSkill.trimEnd()}\n\n## Copilot CLI chart canvas\n`)).toBe(true); - expect(canvasSkill).toContain('prefer it over `create_chart` and `show`'); + expect(canvasSkill).toContain('prefer it over `validate_chart` and `show`'); expect(canvasSkill).toContain('resolved inline `data.values`'); }); diff --git a/packages/flint-mcp/ui/src/BoardView.tsx b/packages/flint-mcp/ui/src/BoardView.tsx index c55411e3..0b7871e7 100644 --- a/packages/flint-mcp/ui/src/BoardView.tsx +++ b/packages/flint-mcp/ui/src/BoardView.tsx @@ -4,9 +4,9 @@ /** * The board card: several charts under one headline. * - * Each show call opens a new card with the board's current version; a card - * keeps the version it was handed. The reader arranges and restyles the newest card in - * place; the server keeps nothing the reader changes on an earlier card. Links + * Each show call opens a new card with the board it was given; nothing is kept on the server. + * The reader arranges and restyles the card in place, and the card says what changed in the + * context it sends, as the fields to pass to the next show to keep it. Links * turn a reader's selection on one chart into an emphasis layer on the others, * and the card sends one model context that covers every chart. */ @@ -44,7 +44,6 @@ import { boardPng } from './board-export'; import { SelectionChips, chipText, impliedParts, partText } from './selection-chips'; import { ViewSwitch, useCellViews, useChartTable, type CellView } from './chart-table-view'; import { ActionButton, ThemeControl } from './controls'; -import { STANDING_NOTE, useStanding } from './standing'; import { LINK_LAYER, conditionUpdates, gestureParts, shownFields, type ChartLink, type LinkCondition, type LinkSpec } from 'flint-chart/interactive'; export interface BoardChart { @@ -64,8 +63,6 @@ export interface Board { theme_spec?: ChartAssemblyInput['theme_spec']; columns?: number; grid?: GridItem[]; - reader_theme?: { theme: ChartAssemblyInput['theme_spec'] | null }; - version: number; charts: BoardChart[]; link_spec?: LinkSpec; linked?: Record; @@ -504,8 +501,10 @@ export function BoardView({ app, initial, hostContext }: { app: App; initial: Bo const [board, setBoard] = useState(initial); // The board's one selection, from the chart the reader selected on last, with the layers that hold it there. // The board's one condition, and the chart each part came from, which names its values. - // A theme picked in the bar shows at once; the board the server returns then carries it. - const [pendingTheme, setPendingTheme] = useState<{ theme: ChartAssemblyInput['theme_spec'] | null } | 'reset' | null>(null); + // The theme the reader picked in the bar for every chart; `theme` null is Flint's default. + const [readerTheme, setReaderTheme] = useState<{ theme: ChartAssemblyInput['theme_spec'] | null } | null>(null); + const readerThemeRef = useRef(readerTheme); + readerThemeRef.current = readerTheme; const [exportStatus, setExportStatus] = useState<'idle' | 'working' | 'copied' | 'downloaded' | 'error'>('idle'); // The board's one condition, the chart each part came from, which names its values, and the parts // another part of the same selection implies (a country's region), applied but not shown. @@ -533,25 +532,6 @@ export function BoardView({ app, initial, hostContext }: { app: App; initial: Bo useEffect(() => setBoard(initial), [initial]); - const [standing, setStanding] = useStanding(app, initial, setBoard); - - /** Saves a reader change on the board; false when the server did not keep it. */ - const writeBoard = useCallback(async (name: 'set_board_theme' | 'set_board_layout', args: Record) => { - const current = boardRef.current; - try { - const result = await app.callServerTool({ name, arguments: { id: current.id, version: current.version, ...args } }); - const { board: saved, version } = (result.structuredContent ?? {}) as { board?: Board; version?: number }; - if (!result.isError && saved) { - setBoard(saved); - return true; - } - if (version !== undefined && version > current.version) setStanding('passed'); - } catch { - // Not kept; the caller says so. - } - return false; - }, [app]); - const clearCondition = useCallback(() => { setCondition((current) => (Object.keys(current.parts).length === 0 ? current : EMPTY_CONDITION)); }, []); @@ -642,7 +622,7 @@ export function BoardView({ app, initial, hostContext }: { app: App; initial: Bo const sendContext = useCallback(() => { const current = boardRef.current; const lines = [ - `Board ${current.id} version ${current.version}${current.title ? ` "${current.title}"` : ''}: ${current.charts.length} charts, as the reader sees them now. Change it with add_chart, update_chart, remove_chart and update_board, then show it again with show.`, + `Board${current.title ? ` "${current.title}"` : ''}: ${current.charts.length} charts, as the reader sees them now. To change it, change the board spec and call show again.`, ]; for (const chart of chartsRef.current) { const state = states.current.get(chart.id); @@ -678,15 +658,23 @@ export function BoardView({ app, initial, hostContext }: { app: App; initial: Bo lines.push(`- The board is narrowed to ${said.join(' and ')}.`, `- Each chart shows it on the fields its marks carry: ${shown.join('; ')}.`); } } - if (current.reader_theme) lines.push('', `The reader picked the theme ${themeName(current.reader_theme.theme ?? undefined)} for every chart, over ${themeName(current.theme_spec)}.`); - if (current.grid) lines.push('', 'Layout, as the reader arranged it on a 12-column grid:', ...gridLines(current.grid)); + const picked = readerThemeRef.current; + if (picked) { + lines.push('', picked.theme === null + ? 'The reader picked Flint\'s default theme for every chart. To keep it in the next show, leave theme_spec out of the board and the charts.' + : `The reader picked the theme ${themeName(picked.theme)} for every chart. To keep it in the next show, pass theme_spec: ${JSON.stringify(picked.theme)} on the board and leave it out of the charts.`); + } + if (current.grid) { + lines.push('', 'Layout, as the reader arranged it on a 12-column grid:', ...gridLines(current.grid), + `To keep it in the next show, pass grid: ${JSON.stringify(current.grid)} on the board.`); + } const text = lines.join('\n'); if (text === lastContext.current) return; lastContext.current = text; void app.updateModelContext({ content: [{ type: 'text', text }] }) .catch((err) => console.warn('The host declined the board context', err)); }, [app]); - useEffect(() => sendContext(), [board, charts, condition, sendContext]); + useEffect(() => sendContext(), [board, charts, condition, readerTheme, sendContext]); const handleTable = useCallback((id: string, table: ChartTable | null) => { if (table) tables.current.set(id, table); else tables.current.delete(id); @@ -728,22 +716,15 @@ export function BoardView({ app, initial, hostContext }: { app: App; initial: Bo const layoutCharts = charts.map((chart) => ({ id: chart.id, chartType: chart.input.chart_spec.chartType, layout: chart.layout })); return boardRows(layoutCharts, boardColumns(layoutCharts, board.columns), boardWidth ?? undefined); }, [charts, board.columns, boardWidth]); - const readerTheme = pendingTheme === 'reset' ? undefined : pendingTheme ?? board.reader_theme; const theme = readerTheme ? readerTheme.theme ?? undefined : board.theme_spec; - const drawInputs = useDrawInputs(charts, theme, readerTheme !== undefined); - const pickTheme = useCallback(async (next: ChartAssemblyInput['theme_spec']) => { + const drawInputs = useDrawInputs(charts, theme, readerTheme !== null); + const pickTheme = useCallback((next: ChartAssemblyInput['theme_spec']) => { const reset = JSON.stringify(next ?? null) === JSON.stringify(boardRef.current.theme_spec ?? null); - setPendingTheme(reset ? 'reset' : { theme: next ?? null }); - if (await writeBoard('set_board_theme', reset ? { reset: true } : { theme: next ?? null })) { - setPendingTheme(null); - return; - } - // The server did not keep it: the card still shows it. - setNotice('The theme could not be saved on the board; it shows here until the card reloads.'); - }, [writeBoard]); + setReaderTheme(reset ? null : { theme: next ?? null }); + }, []); // The frame is drawn in the board's theme, the reader's pick, or else the one theme the charts share. const frameTheme = useMemo( - () => (readerTheme !== undefined || theme !== undefined ? theme : sharedChartTheme(charts)), + () => (readerTheme !== null || theme !== undefined ? theme : sharedChartTheme(charts)), [readerTheme, theme, charts], ); const style = useMemo(() => boardStyle(frameTheme), [frameTheme]); @@ -811,10 +792,13 @@ export function BoardView({ app, initial, hostContext }: { app: App; initial: Bo setDraft(board.grid ? board.grid.map((item) => ({ ...item })) : gridFromRows()); }, [board.grid, gridFromRows]); - const save = useCallback(async (next: GridItem[] | null) => { - if (!(await writeBoard('set_board_layout', { grid: next }))) setNotice('The arrangement was not kept.'); + const save = useCallback((next: GridItem[] | null) => { + setBoard((current) => { + const { grid: _grid, ...rest } = current; + return next ? { ...rest, grid: next } : rest; + }); setDraft(null); - }, [writeBoard]); + }, []); const gesture = useRef<{ kind: GridGesture; id: string; x: number; y: number; start: GridItem[] } | null>(null); const onGesture = useCallback((kind: GridGesture, id: string, event: ReactPointerEvent) => { @@ -991,7 +975,6 @@ export function BoardView({ app, initial, hostContext }: { app: App; initial: Bo {topRules.map((rule, at) =>
)} {editing &&

Drag a chart by its handle at the top right: dropped on a chart in its row the two swap; dropped on another row it is inserted there and the rest move down (Shift does the other). Drag the right or bottom edge, or a bottom corner, to resize.

} {notice &&

{notice}

} - {standing !== 'newest' &&

{STANDING_NOTE[standing]}

} {charts.length === 0 ? (
No charts on this board yet.
@@ -1070,18 +1053,18 @@ export function BoardView({ app, initial, hostContext }: { app: App; initial: Bo {editing ? ( - + ) : ( - + - void save(null)}> + save(null)}>
- {standing === 'passed' &&

{STANDING_NOTE.passed}

} {shownError ? (
Could not render chart @@ -870,6 +889,7 @@ export function ChartView({ app, shown, hostContext }: { app: App; shown: Board; expressionInterpreter={expressionInterpreter} chartId="flint-chart-view" width="100%" + height={paned ? '100%' : overCeiling ? APP_PREVIEW_CANVAS_SIZE.height : undefined} fit={autoSize ? 'relayout' : 'scale-down'} fallback={Rendering…} onWarnings={setSurfaceWarnings} @@ -915,5 +935,5 @@ const NO_UPDATES: readonly ChartUpdate[] = []; /** One chart as a shown view, for a card drawn outside a show call. */ export function shownChart(input: ChartAssemblyInput): Board { - return { id: 'chart-example', kind: 'chart', version: 1, charts: [{ id: 'chart', input }] }; + return { id: 'chart-example', kind: 'chart', charts: [{ id: 'chart', input }] }; } diff --git a/packages/flint-mcp/ui/src/FlintApp.tsx b/packages/flint-mcp/ui/src/FlintApp.tsx index fdf31c91..5455d2f8 100644 --- a/packages/flint-mcp/ui/src/FlintApp.tsx +++ b/packages/flint-mcp/ui/src/FlintApp.tsx @@ -18,8 +18,14 @@ declare const __FLINT_MCP_VERSION__: string; /** How long the card waits for its result before it says it cannot be redrawn here. */ const RESULT_WAIT_MS = 6000; -const NOT_REDRAWN = - 'This cannot be redrawn here: the call that showed it did not reach this card again, as can happen when a conversation is reopened. Ask Claude to show it again.'; +const NOT_REDRAWN = 'The chart cannot be redrawn here. Ask the agent to show it again.'; + +/** The board a show result hands the card: in _meta, or in structuredContent where a host kept only that. */ +function boardOf(result: { _meta?: unknown; structuredContent?: unknown }): Board | undefined { + const meta = result._meta as { flint?: { board?: Board } } | undefined; + const structured = result.structuredContent as { flint?: { board?: Board } } | undefined; + return meta?.flint?.board ?? structured?.flint?.board; +} export function FlintApp() { const [shown, setShown] = useState(null); @@ -27,6 +33,8 @@ export function FlintApp() { const [hostContext, setHostContext] = useState(); const shownSeen = useRef(false); shownSeen.current = shown !== null; + // The spec show was called with: a card the host draws again without its result draws it again from this. + const toolInput = useRef | null>(null); const { app, error } = useApp({ appInfo: { name: 'Flint', version: __FLINT_MCP_VERSION__ }, @@ -36,13 +44,16 @@ export function FlintApp() { app.onteardown = async () => ({}); app.onerror = (err) => console.error(err); app.onhostcontextchanged = (params) => setHostContext((prev) => ({ ...prev, ...params })); + app.ontoolinput = (params) => { + toolInput.current = (params.arguments as Record | undefined) ?? null; + }; app.ontoolresult = (result) => { - const { _meta, content } = result as { _meta?: { flint?: { board?: Board } }; content?: { type: string; text?: string }[] }; + const { content } = result as { content?: { type: string; text?: string }[] }; if (result.isError) { setFailed(content?.find((part) => part.type === 'text')?.text ?? ''); return; } - const next = _meta?.flint?.board; + const next = boardOf(result); if (next) { setFailed(null); setShown(next); @@ -55,11 +66,25 @@ export function FlintApp() { if (app) setHostContext(app.getHostContext()); }, [app]); - // A reopened conversation may not hand the card its result again; the card then says so instead of waiting. + // A reopened conversation may not hand the card its result again. The server keeps nothing, so the card + // calls show again with the spec it was called with; without one, or a host that runs no tools, it says so. useEffect(() => { if (!app) return; const handle = window.setTimeout(() => { - if (!shownSeen.current) setFailed((reason) => reason ?? NOT_REDRAWN); + if (shownSeen.current) return; + const args = toolInput.current; + if (!args || !app.getHostCapabilities()?.serverTools) { + setFailed((reason) => reason ?? NOT_REDRAWN); + return; + } + app.callServerTool({ name: 'show', arguments: args }).then( + (result) => { + const next = !result.isError ? boardOf(result) : undefined; + if (next) setShown(next); + else setFailed((reason) => reason ?? NOT_REDRAWN); + }, + () => setFailed((reason) => reason ?? NOT_REDRAWN), + ); }, RESULT_WAIT_MS); return () => window.clearTimeout(handle); }, [app]); diff --git a/packages/flint-mcp/ui/src/standing.ts b/packages/flint-mcp/ui/src/standing.ts deleted file mode 100644 index 6eb2028c..00000000 --- a/packages/flint-mcp/ui/src/standing.ts +++ /dev/null @@ -1,46 +0,0 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT License. - -import type { App } from '@modelcontextprotocol/ext-apps'; -import { useEffect, useState } from 'react'; - -/** Whether the card saves the reader's changes: the newest version does; a passed or offline one does not. */ -export type Standing = 'newest' | 'passed' | 'offline'; - -export const STANDING_NOTE: Record, string> = { - passed: 'An earlier version: the newest is further down the conversation.', - offline: 'Not live: showing it as it was drawn.', -}; - -/** - * The card hands what it shows to the server once: one that restarted takes it back, one past it - * says so, and one that holds it returns it, with what the reader saved since, to `onHeld`. - */ -export function useStanding(app: App, shown: T, onHeld?: (held: T) => void) { - const [standing, setStanding] = useState('newest'); - useEffect(() => { - if (!app.getHostCapabilities()?.serverTools) { - setStanding('offline'); - return; - } - let stopped = false; - app.callServerTool({ name: 'restore_board', arguments: { board: shown } }).then( - (result) => { - if (stopped) return; - const held = (result.structuredContent as { board?: T } | undefined)?.board; - if (result.isError || !held) setStanding('offline'); - else if (held.version > shown.version) setStanding('passed'); - else onHeld?.(held); - }, - () => { - if (!stopped) setStanding('offline'); - }, - ); - return () => { - stopped = true; - }; - // `onHeld` is read once, with the board it answers. - // eslint-disable-next-line react-hooks/exhaustive-deps - }, [app, shown]); - return [standing, setStanding] as const; -} diff --git a/packages/flint-mcp/ui/src/styles.css b/packages/flint-mcp/ui/src/styles.css index 298efc1e..b6d1f2d3 100644 --- a/packages/flint-mcp/ui/src/styles.css +++ b/packages/flint-mcp/ui/src/styles.css @@ -52,7 +52,11 @@ body { display: flex; flex-direction: column; gap: 8px; - padding: 10px; + padding: + calc(10px + var(--inset-top, 0px)) + calc(10px + var(--inset-right, 0px)) + calc(10px + var(--inset-bottom, 0px)) + calc(10px + var(--inset-left, 0px)); align-items: stretch; } @@ -61,19 +65,20 @@ body { min-width: 0; } -/* The chart frame. Its width is measured and handed to the assembler, so the - SVG should already fit across; the `max-*` rules are a backstop for specs - that state their own size and so opt out of the preview's sizing. +/* The chart frame. Its width is measured and the chart is laid out for it, + so the SVG already fits across. - Height is deliberately not fixed. A title, deck, legend and axis can take - 145px before the plot gets any, so pinning a short frame and scaling the - graphic down shrinks the type below the app's own 11px chrome. The frame - grows to the chart instead, up to --chart-max-height. + Height is not fixed inline. A title, deck, legend and axis can take 145px + before the plot gets any, so pinning a short frame and scaling the graphic + down shrinks the type below the app's own 11px chrome, and a fixed tall + frame leaves a band around a chart its house draws short. The frame grows + to the chart instead, up to --chart-max-height; a chart laid out taller is + given that height as its box and scaled into it. In a pane the frame takes + the pane's height and the chart is laid out for it. - That cap is a length, not a percentage, and is repeated on the SVG below. - A percentage `max-height` resolves against the parent's height, and this - parent has none to give — so the SVG would render at full height, the frame - would stop at its cap, and the difference would become a scrollbar. */ + The frame never scrolls: a scrollbar would narrow the chart it measures and + start a relayout loop, and a centred chart taller than a scrolling box loses + its top, title first. */ .chart { background: var(--paper); padding: 6px; @@ -86,7 +91,23 @@ body { margin-inline: auto; justify-content: center; align-items: center; - overflow: auto; + overflow: hidden; +} + +.app-paned { + height: 100vh; +} + +.app-paned .preview { + display: flex; + flex: 1; + flex-direction: column; + min-height: 0; +} + +.app-paned .chart { + flex: 1; + max-height: none; } /* The SVG is the flex item; this wrapper only carries the markup. */ @@ -1218,6 +1239,7 @@ input[type="checkbox"] { } /* A chart type that is a table takes the frame's width and grows to its rows, up to the chart's cap. */ + .table-cell > .flint-table { height: 100%; } diff --git a/scripts/sync-copilot-plugin.mjs b/scripts/sync-copilot-plugin.mjs index f0cfe1db..2984702d 100644 --- a/scripts/sync-copilot-plugin.mjs +++ b/scripts/sync-copilot-plugin.mjs @@ -19,7 +19,7 @@ const outputs = new Map([ [manifestPath, `${JSON.stringify(manifest, null, 2)}\n`], [mcpPath, `${JSON.stringify(mcp, null, 2)}\n`], [resolve(pluginRoot, 'assets/flint-app.html'), await readFile(resolve(root, 'packages/flint-mcp/assets/flint-app.html'), 'utf8')], - [resolve(pluginRoot, 'skills/flint-chart-author/SKILL.md'), `${skill.trimEnd()}\n\n## Copilot CLI chart canvas\n\nWhen this plugin's native **Flint Chart Canvas** is available, prefer it over \`create_chart\` and \`show\`. Validate the complete \`ChartAssemblyInput\` first, then open the canvas with that input, including any theme, options, and \`interaction_spec\`. Pass resolved inline \`data.values\`, not a local \`data.url\`: the canvas cannot read local data files. The canvas owns interactive chart customization; do not recreate that UI or replace it with a browser page.\n`], + [resolve(pluginRoot, 'skills/flint-chart-author/SKILL.md'), `${skill.trimEnd()}\n\n## Copilot CLI chart canvas\n\nWhen this plugin's native **Flint Chart Canvas** is available, prefer it over \`validate_chart\` and \`show\`. Validate the complete \`ChartAssemblyInput\` first, then open the canvas with that input, including any theme, options, and \`interaction_spec\`. Pass resolved inline \`data.values\`, not a local \`data.url\`: the canvas cannot read local data files. The canvas owns interactive chart customization; do not recreate that UI or replace it with a browser page.\n`], ]); for (const [target, content] of outputs) { diff --git a/site/src/components/mcp-embed.tsx b/site/src/components/mcp-embed.tsx index 89ec388e..6b42f4e7 100644 --- a/site/src/components/mcp-embed.tsx +++ b/site/src/components/mcp-embed.tsx @@ -59,32 +59,7 @@ export function useMockApp(onContext?: (text: string) => void) { }), [onContext]); } -/** - * A host for the board card: it answers the board's server tools as the server would, so the card - * stays live and keeps the reader's theme and arrangement. - */ -export function useMockBoardApp(board: Board, onContext?: (text: string) => void) { - return useMemo(() => { - let held: Board = board; - const save = (patch: Partial) => { - held = { ...held, ...patch, version: held.version + 1 }; - return { structuredContent: { board: held, version: held.version } }; - }; - return { - sendMessage: async () => undefined, - updateModelContext: async ({ content }: ModelContext) => { - onContext?.(content.map((part) => part.text).join('\n')); - }, - getHostCapabilities: () => ({ serverTools: {} }), - downloadFile: async () => ({}), - callServerTool: async ({ name, arguments: args }: { name: string; arguments: Record }) => { - if (name === 'restore_board') return { structuredContent: { board: held } }; - if (name === 'set_board_theme') { - return save({ reader_theme: args.reset ? undefined : { theme: (args.theme ?? null) as NonNullable['theme'] } }); - } - if (name === 'set_board_layout') return save({ grid: (args.grid ?? undefined) as Board['grid'] }); - return { isError: true }; - }, - }; - }, [board, onContext]); +/** A host for the board card: the card keeps the reader's theme and arrangement itself, and sends its context. */ +export function useMockBoardApp(onContext?: (text: string) => void) { + return useMockApp(onContext); } diff --git a/site/src/data/usda-coffee-consumption.json b/site/src/data/usda-coffee-consumption.json new file mode 100644 index 00000000..2634dad3 --- /dev/null +++ b/site/src/data/usda-coffee-consumption.json @@ -0,0 +1,745 @@ +{ + "source": "USDA Foreign Agricultural Service, Production, Supply and Distribution (PSD) database, coffee, domestic consumption", + "sourceUrl": "https://apps.fas.usda.gov/psdonline/app/index.html#/app/downloads", + "units": { + "Bags": "million 60-kg bags of green coffee" + }, + "note": "Market years 2005/06 to 2025/26, labelled by starting year. The European Union, reported as one bloc, is left out.", + "values": [ + { + "Year": 2005, + "Country": "United States", + "Bags": 22.07 + }, + { + "Year": 2006, + "Country": "United States", + "Bags": 21.77 + }, + { + "Year": 2007, + "Country": "United States", + "Bags": 21.82 + }, + { + "Year": 2008, + "Country": "United States", + "Bags": 21.83 + }, + { + "Year": 2009, + "Country": "United States", + "Bags": 21.39 + }, + { + "Year": 2010, + "Country": "United States", + "Bags": 22.38 + }, + { + "Year": 2011, + "Country": "United States", + "Bags": 22.95 + }, + { + "Year": 2012, + "Country": "United States", + "Bags": 23.03 + }, + { + "Year": 2013, + "Country": "United States", + "Bags": 23.81 + }, + { + "Year": 2014, + "Country": "United States", + "Bags": 23.57 + }, + { + "Year": 2015, + "Country": "United States", + "Bags": 25.08 + }, + { + "Year": 2016, + "Country": "United States", + "Bags": 25.51 + }, + { + "Year": 2017, + "Country": "United States", + "Bags": 25.56 + }, + { + "Year": 2018, + "Country": "United States", + "Bags": 27.16 + }, + { + "Year": 2019, + "Country": "United States", + "Bags": 26.05 + }, + { + "Year": 2020, + "Country": "United States", + "Bags": 25.92 + }, + { + "Year": 2021, + "Country": "United States", + "Bags": 26.71 + }, + { + "Year": 2022, + "Country": "United States", + "Bags": 24.62 + }, + { + "Year": 2023, + "Country": "United States", + "Bags": 23.55 + }, + { + "Year": 2024, + "Country": "United States", + "Bags": 26.14 + }, + { + "Year": 2025, + "Country": "United States", + "Bags": 25.55 + }, + { + "Year": 2005, + "Country": "Brazil", + "Bags": 15.91 + }, + { + "Year": 2006, + "Country": "Brazil", + "Bags": 16.72 + }, + { + "Year": 2007, + "Country": "Brazil", + "Bags": 17.39 + }, + { + "Year": 2008, + "Country": "Brazil", + "Bags": 18.03 + }, + { + "Year": 2009, + "Country": "Brazil", + "Bags": 18.76 + }, + { + "Year": 2010, + "Country": "Brazil", + "Bags": 19.42 + }, + { + "Year": 2011, + "Country": "Brazil", + "Bags": 20.02 + }, + { + "Year": 2012, + "Country": "Brazil", + "Bags": 20.11 + }, + { + "Year": 2013, + "Country": "Brazil", + "Bags": 20.21 + }, + { + "Year": 2014, + "Country": "Brazil", + "Bags": 20.42 + }, + { + "Year": 2015, + "Country": "Brazil", + "Bags": 20.86 + }, + { + "Year": 2016, + "Country": "Brazil", + "Bags": 21.62 + }, + { + "Year": 2017, + "Country": "Brazil", + "Bags": 22.42 + }, + { + "Year": 2018, + "Country": "Brazil", + "Bags": 23.2 + }, + { + "Year": 2019, + "Country": "Brazil", + "Bags": 22.99 + }, + { + "Year": 2020, + "Country": "Brazil", + "Bags": 22.28 + }, + { + "Year": 2021, + "Country": "Brazil", + "Bags": 22.34 + }, + { + "Year": 2022, + "Country": "Brazil", + "Bags": 22.45 + }, + { + "Year": 2023, + "Country": "Brazil", + "Bags": 22.16 + }, + { + "Year": 2024, + "Country": "Brazil", + "Bags": 21.97 + }, + { + "Year": 2025, + "Country": "Brazil", + "Bags": 22.28 + }, + { + "Year": 2005, + "Country": "Japan", + "Bags": 7.28 + }, + { + "Year": 2006, + "Country": "Japan", + "Bags": 7.37 + }, + { + "Year": 2007, + "Country": "Japan", + "Bags": 7.0 + }, + { + "Year": 2008, + "Country": "Japan", + "Bags": 7.03 + }, + { + "Year": 2009, + "Country": "Japan", + "Bags": 6.89 + }, + { + "Year": 2010, + "Country": "Japan", + "Bags": 7.01 + }, + { + "Year": 2011, + "Country": "Japan", + "Bags": 7.05 + }, + { + "Year": 2012, + "Country": "Japan", + "Bags": 7.57 + }, + { + "Year": 2013, + "Country": "Japan", + "Bags": 7.75 + }, + { + "Year": 2014, + "Country": "Japan", + "Bags": 7.86 + }, + { + "Year": 2015, + "Country": "Japan", + "Bags": 8.06 + }, + { + "Year": 2016, + "Country": "Japan", + "Bags": 8.21 + }, + { + "Year": 2017, + "Country": "Japan", + "Bags": 8.23 + }, + { + "Year": 2018, + "Country": "Japan", + "Bags": 7.9 + }, + { + "Year": 2019, + "Country": "Japan", + "Bags": 7.61 + }, + { + "Year": 2020, + "Country": "Japan", + "Bags": 7.35 + }, + { + "Year": 2021, + "Country": "Japan", + "Bags": 7.21 + }, + { + "Year": 2022, + "Country": "Japan", + "Bags": 6.89 + }, + { + "Year": 2023, + "Country": "Japan", + "Bags": 7.0 + }, + { + "Year": 2024, + "Country": "Japan", + "Bags": 6.53 + }, + { + "Year": 2025, + "Country": "Japan", + "Bags": 6.65 + }, + { + "Year": 2005, + "Country": "Philippines", + "Bags": 1.21 + }, + { + "Year": 2006, + "Country": "Philippines", + "Bags": 1.41 + }, + { + "Year": 2007, + "Country": "Philippines", + "Bags": 1.31 + }, + { + "Year": 2008, + "Country": "Philippines", + "Bags": 1.74 + }, + { + "Year": 2009, + "Country": "Philippines", + "Bags": 2.25 + }, + { + "Year": 2010, + "Country": "Philippines", + "Bags": 2.83 + }, + { + "Year": 2011, + "Country": "Philippines", + "Bags": 3.66 + }, + { + "Year": 2012, + "Country": "Philippines", + "Bags": 4.41 + }, + { + "Year": 2013, + "Country": "Philippines", + "Bags": 3.59 + }, + { + "Year": 2014, + "Country": "Philippines", + "Bags": 4.23 + }, + { + "Year": 2015, + "Country": "Philippines", + "Bags": 6.21 + }, + { + "Year": 2016, + "Country": "Philippines", + "Bags": 7.0 + }, + { + "Year": 2017, + "Country": "Philippines", + "Bags": 6.55 + }, + { + "Year": 2018, + "Country": "Philippines", + "Bags": 6.12 + }, + { + "Year": 2019, + "Country": "Philippines", + "Bags": 6.12 + }, + { + "Year": 2020, + "Country": "Philippines", + "Bags": 6.58 + }, + { + "Year": 2021, + "Country": "Philippines", + "Bags": 7.19 + }, + { + "Year": 2022, + "Country": "Philippines", + "Bags": 6.46 + }, + { + "Year": 2023, + "Country": "Philippines", + "Bags": 6.59 + }, + { + "Year": 2024, + "Country": "Philippines", + "Bags": 6.19 + }, + { + "Year": 2025, + "Country": "Philippines", + "Bags": 6.53 + }, + { + "Year": 2005, + "Country": "China", + "Bags": 0.2 + }, + { + "Year": 2006, + "Country": "China", + "Bags": 0.26 + }, + { + "Year": 2007, + "Country": "China", + "Bags": 0.16 + }, + { + "Year": 2008, + "Country": "China", + "Bags": 0.34 + }, + { + "Year": 2009, + "Country": "China", + "Bags": 1.14 + }, + { + "Year": 2010, + "Country": "China", + "Bags": 1.11 + }, + { + "Year": 2011, + "Country": "China", + "Bags": 1.11 + }, + { + "Year": 2012, + "Country": "China", + "Bags": 1.69 + }, + { + "Year": 2013, + "Country": "China", + "Bags": 2.3 + }, + { + "Year": 2014, + "Country": "China", + "Bags": 2.38 + }, + { + "Year": 2015, + "Country": "China", + "Bags": 2.49 + }, + { + "Year": 2016, + "Country": "China", + "Bags": 2.35 + }, + { + "Year": 2017, + "Country": "China", + "Bags": 2.71 + }, + { + "Year": 2018, + "Country": "China", + "Bags": 2.92 + }, + { + "Year": 2019, + "Country": "China", + "Bags": 3.71 + }, + { + "Year": 2020, + "Country": "China", + "Bags": 4.48 + }, + { + "Year": 2021, + "Country": "China", + "Bags": 4.92 + }, + { + "Year": 2022, + "Country": "China", + "Bags": 5.28 + }, + { + "Year": 2023, + "Country": "China", + "Bags": 5.76 + }, + { + "Year": 2024, + "Country": "China", + "Bags": 5.89 + }, + { + "Year": 2025, + "Country": "China", + "Bags": 6.42 + }, + { + "Year": 2005, + "Country": "Vietnam", + "Bags": 0.67 + }, + { + "Year": 2006, + "Country": "Vietnam", + "Bags": 0.75 + }, + { + "Year": 2007, + "Country": "Vietnam", + "Bags": 0.85 + }, + { + "Year": 2008, + "Country": "Vietnam", + "Bags": 0.95 + }, + { + "Year": 2009, + "Country": "Vietnam", + "Bags": 1.2 + }, + { + "Year": 2010, + "Country": "Vietnam", + "Bags": 1.34 + }, + { + "Year": 2011, + "Country": "Vietnam", + "Bags": 1.67 + }, + { + "Year": 2012, + "Country": "Vietnam", + "Bags": 1.82 + }, + { + "Year": 2013, + "Country": "Vietnam", + "Bags": 2.01 + }, + { + "Year": 2014, + "Country": "Vietnam", + "Bags": 2.22 + }, + { + "Year": 2015, + "Country": "Vietnam", + "Bags": 2.63 + }, + { + "Year": 2016, + "Country": "Vietnam", + "Bags": 2.77 + }, + { + "Year": 2017, + "Country": "Vietnam", + "Bags": 2.88 + }, + { + "Year": 2018, + "Country": "Vietnam", + "Bags": 2.94 + }, + { + "Year": 2019, + "Country": "Vietnam", + "Bags": 3.1 + }, + { + "Year": 2020, + "Country": "Vietnam", + "Bags": 2.72 + }, + { + "Year": 2021, + "Country": "Vietnam", + "Bags": 3.2 + }, + { + "Year": 2022, + "Country": "Vietnam", + "Bags": 3.2 + }, + { + "Year": 2023, + "Country": "Vietnam", + "Bags": 3.9 + }, + { + "Year": 2024, + "Country": "Vietnam", + "Bags": 4.8 + }, + { + "Year": 2025, + "Country": "Vietnam", + "Bags": 4.9 + }, + { + "Year": 2005, + "Country": "Indonesia", + "Bags": 1.7 + }, + { + "Year": 2006, + "Country": "Indonesia", + "Bags": 1.79 + }, + { + "Year": 2007, + "Country": "Indonesia", + "Bags": 1.72 + }, + { + "Year": 2008, + "Country": "Indonesia", + "Bags": 1.89 + }, + { + "Year": 2009, + "Country": "Indonesia", + "Bags": 1.93 + }, + { + "Year": 2010, + "Country": "Indonesia", + "Bags": 1.65 + }, + { + "Year": 2011, + "Country": "Indonesia", + "Bags": 2.12 + }, + { + "Year": 2012, + "Country": "Indonesia", + "Bags": 2.81 + }, + { + "Year": 2013, + "Country": "Indonesia", + "Bags": 2.54 + }, + { + "Year": 2014, + "Country": "Indonesia", + "Bags": 2.9 + }, + { + "Year": 2015, + "Country": "Indonesia", + "Bags": 3.17 + }, + { + "Year": 2016, + "Country": "Indonesia", + "Bags": 3.2 + }, + { + "Year": 2017, + "Country": "Indonesia", + "Bags": 3.56 + }, + { + "Year": 2018, + "Country": "Indonesia", + "Bags": 4.3 + }, + { + "Year": 2019, + "Country": "Indonesia", + "Bags": 4.9 + }, + { + "Year": 2020, + "Country": "Indonesia", + "Bags": 4.45 + }, + { + "Year": 2021, + "Country": "Indonesia", + "Bags": 4.75 + }, + { + "Year": 2022, + "Country": "Indonesia", + "Bags": 4.77 + }, + { + "Year": 2023, + "Country": "Indonesia", + "Bags": 4.78 + }, + { + "Year": 2024, + "Country": "Indonesia", + "Bags": 4.87 + }, + { + "Year": 2025, + "Country": "Indonesia", + "Bags": 4.81 + } + ] +} diff --git a/site/src/i18n/messages/en.json b/site/src/i18n/messages/en.json index fd26940f..f980c8c3 100644 --- a/site/src/i18n/messages/en.json +++ b/site/src/i18n/messages/en.json @@ -613,8 +613,8 @@ "exp": { "simple": { "chartHeading": "An interactive chart, in a theme", - "chartAsk": "Show me how global temperatures have changed since 1880, in a newspaper style. Let me brush across the years.", - "chartReply": "Here's a live chart in a newspaper style. Drag across the years to select a period.", + "chartAsk": "Show me how coffee drinking has changed by country since 2005, in a newspaper style. Let me hover to compare.", + "chartReply": "Here's a live chart in a newspaper style. Hover any year to read every country, or click the legend to hide one.", "boardHeading": "A dashboard, in a theme", "boardAsk": "Build a dashboard from the Gapminder data in the Economist theme, with the charts linked by continent.", "boardReply": "Here's a board of four linked charts in the Economist theme. Click a continent in any of them to see it everywhere." @@ -708,11 +708,11 @@ }, "board": { "title": "Boards", - "body": "Build, change and show dashboards of linked charts." + "body": "Check and show dashboards of linked charts." }, "static": { "title": "Static output", - "body": "Return a PNG or SVG, a backend spec, or a validation report." + "body": "Return a PNG or SVG, or a backend spec." }, "skills": { "title": "Discovery and skills", diff --git a/site/src/i18n/messages/zh-CN.json b/site/src/i18n/messages/zh-CN.json index a6e62fee..582589a8 100644 --- a/site/src/i18n/messages/zh-CN.json +++ b/site/src/i18n/messages/zh-CN.json @@ -613,8 +613,8 @@ "exp": { "simple": { "chartHeading": "带主题的交互式图表", - "chartAsk": "用报纸风格展示 1880 年以来全球气温的变化,并让我可以按年份刷选。", - "chartReply": "这是一张报纸风格的实时图表。拖过年份即可选取一段时期。", + "chartAsk": "用报纸风格展示 2005 年以来各国咖啡消费的变化,并让我可以悬停比较。", + "chartReply": "这是一张报纸风格的实时图表。悬停在任一年份上可读出各国数值,点击图例可隐藏某个国家。", "boardHeading": "带主题的仪表板", "boardAsk": "用 Gapminder 数据做一个 Economist 主题的仪表板,图表按大洲联动。", "boardReply": "这是一个由四张联动图表组成的 Economist 主题仪表板。在任意一张中点击某个大洲,所有图表都会突出显示它。" @@ -708,11 +708,11 @@ }, "board": { "title": "看板", - "body": "创建、修改并展示由联动图表组成的看板。" + "body": "检查并展示由联动图表组成的看板。" }, "static": { "title": "静态输出", - "body": "返回 PNG 或 SVG、后端规范或校验报告。" + "body": "返回 PNG 或 SVG,或后端规范。" }, "skills": { "title": "查询与技能", diff --git a/site/src/playground/DebugGym.tsx b/site/src/playground/DebugGym.tsx index d6c82807..6ed17e66 100644 --- a/site/src/playground/DebugGym.tsx +++ b/site/src/playground/DebugGym.tsx @@ -1,5 +1,5 @@ import { useEffect, useMemo, useRef, useState, type CSSProperties } from 'react'; -import { assembleECharts, assembleVegaLite, type ChartAssemblyInput } from 'flint-chart'; +import { assembleECharts, assemblePlotly, assembleVegaLite, type ChartAssemblyInput } from 'flint-chart'; import { mountChart, type ChartUpdate } from 'flint-chart/interactive'; import { genEChartsSlopeTests, TEST_GENERATORS } from 'flint-chart/test-data'; import { compile } from 'vega-lite'; @@ -609,6 +609,142 @@ function ThemePickingGym() { ); } +// ---------------------------------------------------------------- 1.0.1 fixes +const LAB_ROWS = [ + { date: '2025-01-01', value: 4 }, { date: '2025-03-01', value: 7 }, { date: '2025-05-01', value: 3 }, + { date: '2025-07-01', value: 8 }, { date: '2025-09-01', value: 5 }, { date: '2025-11-01', value: 6 }, +]; +const CURVE_THEMES = [undefined, 'cartoon', 'de-stijl'] as const; +const CURVES = [undefined, 'linear', 'monotone', 'step-after'] as const; +/** What Plotly should draw: the chart's curve when it asks for one, else the theme's. */ +const EXPECTED_SHAPE: Record = { linear: 'linear', monotone: 'spline', 'step-after': 'hv' }; +const THEME_SHAPE: Record = { cartoon: 'spline', 'de-stijl': 'hv|vh|hvh', plain: 'linear' }; + +function curveInput(curve: string | undefined, theme: string | undefined): ChartAssemblyInput { + return { + data: { values: LAB_ROWS }, + semantic_types: { date: 'DateTime', value: 'Quantity' }, + chart_spec: { + chartType: 'Line Chart', + encodings: { x: 'date', y: 'value' }, + baseSize: { width: 240, height: 140 }, + ...(curve ? { chartProperties: { interpolate: curve } } : {}), + }, + ...(theme ? { theme_spec: theme } : {}), + } as ChartAssemblyInput; +} + +function CurveCase({ curve, theme }: { curve: string | undefined; theme: string | undefined }) { + const input = useMemo(() => curveInput(curve, theme), [curve, theme]); + const shape = useMemo(() => String((assemblePlotly(input) as any).data?.[0]?.line?.shape ?? 'linear'), [input]); + const expected = curve ? EXPECTED_SHAPE[curve] : THEME_SHAPE[theme ?? 'plain']; + const passed = new RegExp(`^(${expected})$`).test(shape); + return ( +
+
+ {theme ?? 'no theme'} · interpolate: {curve ?? '(unset)'} +
+ + + +
+ line.shape {shape} {passed ? '✓' : `✗ expected ${expected}`} +
+
+ ); +} + +function PlotlyCurveGym() { + return ( +
+
+

#149 · Plotly keeps the chart's own curve under a theme

+

+ Before the fix, Cartoon (monotone) and De Stijl (step) bent an explicit{' '} + interpolate: "linear" on Plotly. Now the chart's choice wins, and the theme's + curve applies only in the first column, where the chart asks for none. Rows: theme; columns: the chart's + interpolate. Each cell is drawn with Plotly and checks the compiled line.shape. +

+
+
+ {CURVE_THEMES.flatMap((theme) => CURVES.map((curve) => ( + + )))} +
+
+ ); +} + +/** Mirrors RESULT_COPY_LIMIT and fitsInResult in packages/flint-mcp/src/board.ts (which needs Node). */ +const RESULT_COPY_LIMIT = 4096; +type CardCase = { id: string; label: string; rows: Record[]; fromFile?: boolean }; +const CARD_CASES: CardCase[] = [ + { id: 'small', label: 'Small chart, rows passed inline', rows: SPENDING_SAMPLE() }, + { id: 'large', label: '200 rows passed inline', rows: Array.from({ length: 200 }, (_, i) => ({ month: `M${i}`, value: (i * 37) % 101 })) }, + { id: 'file', label: 'Small chart, rows read from a local data.url file', rows: SPENDING_SAMPLE(), fromFile: true }, +]; +function SPENDING_SAMPLE() { + return [{ month: 'Jan', value: 12 }, { month: 'Feb', value: 18 }, { month: 'Mar', value: 9 }, { month: 'Apr', value: 15 }]; +} + +function CardCaseView({ item }: { item: CardCase }) { + const board = useMemo(() => ({ + id: `chart-${item.id}`, kind: 'chart', + charts: [{ + id: 'chart', + input: { + data: { values: item.rows }, + semantic_types: { month: 'Category', value: 'Quantity' }, + chart_spec: { chartType: 'Bar Chart', encodings: { x: 'month', y: 'value' }, baseSize: { width: 260, height: 150 } }, + }, + ...(item.fromFile ? { fromFile: true } : {}), + }], + }), [item]); + const bytes = new TextEncoder().encode(JSON.stringify(board)).length; + const copied = !item.fromFile && bytes <= RESULT_COPY_LIMIT; + // What the Agent Host hands a card it draws again: content and structuredContent, never _meta. + const rebuilt: { structuredContent?: { flint?: { board?: typeof board } } } = copied ? { structuredContent: { flint: { board } } } : {}; + const drawn = rebuilt.structuredContent?.flint?.board; + return ( +
+
{item.label}
+
+ {bytes.toLocaleString()} bytes · structuredContent: {copied ? 'yes' : 'no'} + {item.fromFile ? ' (file rows never enter the conversation)' : !copied ? ` (over ${RESULT_COPY_LIMIT} bytes)` : ''} +
+ {drawn ? ( + + + + ) : ( +
+
Not drawn
Waits for the VS Code fix (microsoft/vscode#343243).
+
+ )} +
+ ); +} + +function McpRedrawGym() { + return ( +
+
+

MCP · cards the Agent Host draws again

+

+ VS Code's Agent Host rebuilds a card's result from content and{' '} + structuredContent and drops _meta, where show puts the chart. Now{' '} + show also puts a small inline chart in structuredContent. Each card simulates that + rebuilt result and the card's read path; the size and file rules mirror fitsInResult in{' '} + packages/flint-mcp/src/board.ts. +

+
+
+ {CARD_CASES.map((item) => )} +
+
+ ); +} + export function DebugGym() { return (
@@ -623,6 +759,8 @@ export function DebugGym() {
+ + diff --git a/site/src/playground/release-examples/application-demos-extensions.tsx b/site/src/playground/release-examples/application-demos-extensions.tsx index 509bcf57..99131234 100644 --- a/site/src/playground/release-examples/application-demos-extensions.tsx +++ b/site/src/playground/release-examples/application-demos-extensions.tsx @@ -46,12 +46,14 @@ const MCP_CHART_INPUT: ChartAssemblyInput = { } as ChartAssemblyInput; const MCP_CHART_CALL = JSON.stringify({ - name: 'create_chart', + name: 'show', arguments: { - interaction_spec: MCP_CHART_INPUT.interaction_spec, - chart_spec: MCP_CHART_INPUT.chart_spec, - semantic_types: MCP_CHART_INPUT.semantic_types, - data: { values: [HEALTH_ROWS[0], `… ${HEALTH_ROWS.length - 1} more rows`] }, + chart: { + interaction_spec: MCP_CHART_INPUT.interaction_spec, + chart_spec: MCP_CHART_INPUT.chart_spec, + semantic_types: MCP_CHART_INPUT.semantic_types, + data: { values: [HEALTH_ROWS[0], `… ${HEALTH_ROWS.length - 1} more rows`] }, + }, }, }, null, 2); diff --git a/site/src/routes/McpExperience.tsx b/site/src/routes/McpExperience.tsx index 80939732..024fc442 100644 --- a/site/src/routes/McpExperience.tsx +++ b/site/src/routes/McpExperience.tsx @@ -134,7 +134,7 @@ const BOARD_WIDTH = 760; /** A board laid out at `BOARD_WIDTH` and zoomed to the chat's width, so it keeps its two columns. */ function BoardCard({ board, editing, onContext }: { board: Board; editing?: boolean; onContext: (text: string) => void }) { - const app = useMockBoardApp(board, onContext); + const app = useMockBoardApp(onContext); const ref = useRef(null); const [zoom, setZoom] = useState(1); // The card has no prop for layout mode, so the story opens it with the card's own button. diff --git a/site/src/routes/McpServer.tsx b/site/src/routes/McpServer.tsx index 40532f29..daf23b0c 100644 --- a/site/src/routes/McpServer.tsx +++ b/site/src/routes/McpServer.tsx @@ -10,9 +10,9 @@ import { McpExperience } from './McpExperience'; const HOSTED_MCP_URL = 'https://flint.data-formulator.ai/mcp'; const SURFACE_GROUPS = [ - { key: 'chart', tools: ['create_chart', 'show'] }, - { key: 'board', tools: ['create_board', 'add_chart', 'update_chart', 'remove_chart', 'update_board'] }, - { key: 'static', tools: ['render_chart', 'compile_chart', 'validate_chart'] }, + { key: 'chart', tools: ['validate_chart', 'show'] }, + { key: 'board', tools: ['validate_board', 'show'] }, + { key: 'static', tools: ['render_chart', 'compile_chart'] }, { key: 'skills', tools: ['list_chart_types', 'list_interaction_presets', 'list_themes', 'get_flint_skill'] }, ] as const; diff --git a/site/src/routes/mcp-experience-data.ts b/site/src/routes/mcp-experience-data.ts index b28809d2..7802911d 100644 --- a/site/src/routes/mcp-experience-data.ts +++ b/site/src/routes/mcp-experience-data.ts @@ -2,6 +2,7 @@ import type { ChartAssemblyInput, ChartUpdate } from 'flint-chart'; import type { Board, BoardChart } from '../../../packages/flint-mcp/ui/src/BoardView'; import { monthRows, yearRows } from './mcp-experience-range'; import { gapminderRows } from '../playground/gapminder-dashboard-data'; +import coffee from '../data/usda-coffee-consumption.json'; /* ------------------------------------------------------------------ */ /* Part 1: one chart, NASA GISTEMP global temperature */ @@ -60,11 +61,56 @@ const editUpdates: ChartUpdate[] = [ ] as ChartUpdate[]; function chartCard(input: ChartAssemblyInput, updates?: ChartUpdate[]): Board { - return { id: 'temperature', kind: 'chart', version: 1, charts: [{ id: 'chart', input, ...(updates ? { updates } : {}) }] }; + return { id: 'temperature', kind: 'chart', charts: [{ id: 'chart', input, ...(updates ? { updates } : {}) }] }; } -/** The MCP page's one chart: themed and brushable from the first ask. */ -export const SIMPLE_CHART = chartCard(themed); +/* ------------------------------------------------------------------ */ +/* The intro: coffee drinking by country, USDA PSD */ +/* ------------------------------------------------------------------ */ + +const coffeeRows = coffee.values; +const bagsIn = (country: string, year: number) => coffeeRows.find((row) => row.Country === country && row.Year === year)!.Bags; +const chinaGrowth = bagsIn('China', 2025) / bagsIn('China', 2010); + +const coffeeByCountry: ChartAssemblyInput = { + data: { values: coffeeRows }, + semantic_types: { Year: 'Year', Bags: 'Quantity', Country: 'Country' }, + field_display_names: { Bags: 'Million 60-kg bags' }, + theme_spec: 'nyt', + chart_spec: { + chartType: 'Line Chart', + encodings: { x: { field: 'Year' }, y: { field: 'Bags' }, color: { field: 'Country' } }, + title: 'Asia is learning to love coffee', + // Wider than tall: the card holds 480px of chart, and the legend takes two rows above the plot. + baseSize: { width: 520, height: 280 }, + subtitle: 'Coffee consumed in each country, million 60-kg bags, 2005–2025', + source: 'USDA Foreign Agricultural Service, PSD database', + }, + interaction_spec: { + interactions: [ + { type: 'inspect-index', options: { axis: 'x', show: 'all', seriesBy: 'Country', displayValue: true } }, + { type: 'legend-toggle' }, + ], + } as ChartAssemblyInput['interaction_spec'], +} as ChartAssemblyInput; + +const coffeeNotes: ChartUpdate[] = [ + { + id: 'agent', + ops: [ + { + op: 'set-annotation', + target: { select: { key: { Year: 2025, Country: 'China' } } }, + value: { text: `China: ${chinaGrowth >= 5.5 ? 'nearly 6×' : `${chinaGrowth.toFixed(1)}×`} since 2010` }, + }, + ], + }, +] as ChartUpdate[]; + +/** The MCP page's one chart: themed and interactive from the first ask. */ +export const SIMPLE_CHART: Board = { + id: 'coffee', kind: 'chart', charts: [{ id: 'chart', input: coffeeByCountry, updates: coffeeNotes }], +}; export type ChartSlideKey = 'create' | 'theme' | 'interact' | 'select' | 'edit'; diff --git a/site/src/talk/data.ts b/site/src/talk/data.ts index a6985210..0367f0b2 100644 --- a/site/src/talk/data.ts +++ b/site/src/talk/data.ts @@ -304,6 +304,11 @@ export const TYPES_FLINT = { type Line = { text: string; hot?: boolean; gap?: boolean }; const j = (v: unknown) => JSON.stringify(v).split('","').join('", "').split('":').join('": ').split(',"').join(', "'); +/** A small object on one line, spaced inside its braces: `{ "type": "rect", "width": 7 }`. */ +const spaced = (v: unknown) => { + const text = j(v); + return text.startsWith('{') && text !== '{}' ? `{ ${text.slice(1, -1)} }` : text; +}; /** * The parts of the compiled Vega-Lite that the three types decided, taken from the real output, with a * comment naming the type behind each. @@ -313,22 +318,29 @@ export function typesCompiled(): Line[] { const { x, y, color } = vl.encoding; const ticks: string[] = x.axis?.values ?? []; const row = vl.data?.values?.[0] ?? {}; + // Broken where an author would break it, so no line wraps inside a pair on the slide. return [ { text: '{' }, - { text: ' // YearMonth: 202101 is read as a month, on a time axis', gap: true }, - { text: ` "data": { "values": [${j({ period: row.period, game: row.game, newUsers_sum: row.newUsers_sum })}, …] },`, hot: true }, + { text: ' // YearMonth: 202101 is read as a month', gap: true }, + { text: ` "data": { "values": [{ "period": ${j(row.period)}, … }, …] },`, hot: true }, { text: ' "encoding": {' }, { text: ` "x": { "field": "period", "type": ${j(x.type)},`, hot: true }, { text: ` "scale": { "type": ${j(x.scale?.type)} },`, hot: true }, - { text: ` "axis": { "values": [${ticks.slice(0, 2).map((t) => j(t.slice(0, 10))).join(', ')}, …], "labelExpr": "… %Y or %B" } },`, hot: true }, - { text: ' // Category: the games keep the order they come in', gap: true }, - { text: ` "y": { "field": "game", "type": ${j(y.type)}, "sort": ${j(y.sort)} },`, hot: true }, - { text: ' // Profit: it can go negative, so the colors diverge around zero', gap: true }, - { text: ` "color": { "field": ${j(color.field)}, "type": ${j(color.type)},`, hot: true }, - { text: ` "scale": { "scheme": ${j(color.scale?.scheme)}, "domainMid": ${j(color.scale?.domainMid)}, "domain": ${j(color.scale?.domain)} } }`, hot: true }, + { text: ' "axis": {', hot: true }, + { text: ` "values": [${ticks.slice(0, 2).map((t) => j(t.slice(0, 10))).join(', ')}, …],`, hot: true }, + { text: ' "labelExpr": "… %Y or %B" } },', hot: true }, + { text: ' // Category: games keep the order they come in', gap: true }, + { text: ` "y": { "field": "game", "type": ${j(y.type)},`, hot: true }, + { text: ` "sort": ${j(y.sort)} },`, hot: true }, + { text: ' // Profit: it can go negative, so colors diverge', gap: true }, + { text: ` "color": { "field": ${j(color.field)},`, hot: true }, + { text: ` "type": ${j(color.type)},`, hot: true }, + { text: ` "scale": { "scheme": ${j(color.scale?.scheme)}, "domainMid": ${j(color.scale?.domainMid)},`, hot: true }, + { text: ` "domain": ${j(color.scale?.domain).replace(',', ', ')} } }`, hot: true }, { text: ' },' }, - { text: ' // The layout engine: a cell size for 60 months and 8 games', gap: true }, - { text: ` "mark": ${j(vl.mark)}, "height": ${j(vl.height)}`, hot: true }, + { text: ' // Layout: a cell size for 60 months and 8 games', gap: true }, + { text: ` "mark": ${spaced(vl.mark)},`, hot: true }, + { text: ` "height": ${spaced(vl.height)}`, hot: true }, { text: '}' }, ]; } diff --git a/site/src/talk/parts.tsx b/site/src/talk/parts.tsx index f27c27f2..fc3bd9a7 100644 --- a/site/src/talk/parts.tsx +++ b/site/src/talk/parts.tsx @@ -217,6 +217,18 @@ export function lineDiff(prev: unknown, next: unknown, width = 60): { plus: numb return { plus, minus: addedLines(b, a).filter(Boolean).length }; } export const plainRows = (rows: CodeRow[]): CodeRow[] => rows.map(({ text, gap }) => ({ text, gap })); + +// Layouts for a code panel: the same rows, laid out for whatever width the panel gives them. +type Layout = (cols: number) => CodeRow[]; +/** A step's spec, its changes marked and unchanged runs folded, at the panel's width. */ +export const stepLayout = (next: unknown, prev?: unknown): Layout => (cols) => stepRows(next, prev, cols); +/** The whole new spec, its changes marked, at the panel's width. */ +export const fullLayout = (next: unknown, prev: unknown): Layout => (cols) => fullRows(next, prev, cols); +/** A spec at the panel's width, the lines matching `hot` marked. */ +export const specLayout = (value: unknown, hot?: RegExp): Layout => (cols) => + specText(value, cols).split('\n').map((text) => (hot?.test(text) ? { text, hot: true } : { text })); +/** A layout with its marks taken off: the previous step, shown plain. */ +export const plainLayout = (layout: Layout): Layout => (cols) => plainRows(layout(cols)); export const textRows = (text: string, hot = false): CodeRow[] => text.trimEnd().split('\n').map((t) => ({ text: t, hot })); const CHAR_W = 0.62, LINE_H = 1.45; @@ -245,17 +257,29 @@ function sampled(rows: CodeRow[], k: number): CodeRow[] { } /** - * Code set at the largest size that fits its box. Long lines wrap under their own indent. When the - * rows still do not fit, each changed run shows its first lines and says how many more it has. + * Rows for a code panel: fixed, or laid out for a width in characters. A spec laid out for the + * panel's own width breaks between its keys, where a fixed layout would be wrapped mid-pair. + */ +export type CodeSource = CodeRow[] | ((cols: number) => CodeRow[]); + +/** The narrowest layout a spec is reflowed to; below it, lines wrap under their indent instead. */ +const MIN_COLS = 28; +const colsAt = (w: number, size: number) => Math.max(8, Math.floor(w / (CHAR_W * size))); + +/** + * Code set at the largest size that fits its box. A spec given as a layout function is reflowed to + * the columns each size allows; fixed rows wrap long lines under their own indent. When the rows + * still do not fit, each changed run shows its first lines and says how many more it has. */ -export function Code({ rows, max = 22, min = 14, tone = 'flint' }: { - rows: CodeRow[]; max?: number; min?: number; +export function Code({ rows: source, max = 22, min = 14, tone = 'flint' }: { + rows: CodeSource; max?: number; min?: number; /** Flint code marks its changes in blue; Vega-Lite code marks them in red, to show what it costs. */ tone?: 'flint' | 'vl'; }) { const ref = useRef(null); - const [fit, setFit] = useState<{ size: number; k: number; shown: number }>({ size: max, k: Infinity, shown: Infinity }); - const key = rows.map((r) => (r.hot ? '+' : r.gap ? '~' : ' ') + r.text).join('\n'); + const [fit, setFit] = useState<{ size: number; k: number; shown: number; cols: number }>({ size: max, k: Infinity, shown: Infinity, cols: 60 }); + const layout = (cols: number) => (typeof source === 'function' ? source(Math.max(MIN_COLS, cols - 1)) : source); + const key = layout(60).map((r) => (r.hot ? '+' : r.gap ? '~' : ' ') + r.text).join('\n'); useEffect(() => { const el = ref.current; if (!el) return; @@ -266,24 +290,29 @@ export function Code({ rows, max = 22, min = 14, tone = 'flint' }: { if (w <= 0 || h <= 0) return; // Screen lines a list of rows takes at a size, wrapping under each row's indent. const lines = (list: CodeRow[], size: number) => { - const cols = Math.max(8, Math.floor(w / (CHAR_W * size))); + const cols = colsAt(w, size); return list.map(({ text }) => { const hang = Math.min(cols - 4, indentOf(text) + 2); return text.length <= cols ? 1 : 1 + Math.ceil((text.length - cols) / (cols - hang)); }); }; const fits = (list: CodeRow[], size: number) => sum(lines(list, size)) <= Math.floor(h / (LINE_H * size)); - let next = { size: min, k: Infinity, shown: Infinity }; + const narrow = colsAt(w, min); + const rows = layout(narrow); + let next = { size: min, k: Infinity, shown: Infinity, cols: narrow }; let found = false; - for (let size = max; size >= min && !found; size -= 0.5) if (fits(rows, size)) { next = { size, k: Infinity, shown: Infinity }; found = true; } - for (let k = rows.length; k >= 1 && !found; k--) if (fits(sampled(rows, k), min)) { next = { size: min, k, shown: Infinity }; found = true; } + for (let size = max; size >= min && !found; size -= 0.5) { + const cols = colsAt(w, size); + if (fits(layout(cols), size)) { next = { size, k: Infinity, shown: Infinity, cols }; found = true; } + } + for (let k = rows.length; k >= 1 && !found; k--) if (fits(sampled(rows, k), min)) { next = { size: min, k, shown: Infinity, cols: narrow }; found = true; } if (!found) { const list = sampled(rows, 1), per = lines(list, min), budget = Math.floor(h / (LINE_H * min)); let used = 1, shown = 0; while (shown < list.length && used + per[shown] <= budget) used += per[shown++]; - next = { size: min, k: 1, shown }; + next = { size: min, k: 1, shown, cols: narrow }; } - setFit((f) => (f.size === next.size && f.k === next.k && f.shown === next.shown ? f : next)); + setFit((f) => (f.size === next.size && f.k === next.k && f.shown === next.shown && f.cols === next.cols ? f : next)); }; measure(); const ro = new ResizeObserver(measure); @@ -291,7 +320,7 @@ export function Code({ rows, max = 22, min = 14, tone = 'flint' }: { return () => ro.disconnect(); // eslint-disable-next-line react-hooks/exhaustive-deps }, [key, max, min]); - const list = sampled(rows, fit.k); + const list = sampled(layout(fit.cols), fit.k); const shown = fit.shown < list.length ? [...list.slice(0, fit.shown), hiddenRow(list.slice(fit.shown))] : list; return (
diff --git a/site/src/talk/slides.tsx b/site/src/talk/slides.tsx
index 9f5e611e..bcfc8dce 100644
--- a/site/src/talk/slides.tsx
+++ b/site/src/talk/slides.tsx
@@ -16,8 +16,8 @@ import {
   penguins, picked, withData, type FlintState,
 } from './data';
 import {
-  Chart, Code, Demo, FitTable, Stable, MINIMAPS, Minimap, Sketch, VegaLite, fullRows, lineDiff, plainRows, specText, stepRows, textRows,
-  type CodeRow,
+  Chart, Code, Demo, FitTable, Stable, MINIMAPS, Minimap, Sketch, VegaLite, fullLayout, lineDiff, plainLayout, specLayout, stepLayout, textRows,
+  type CodeRow, type CodeSource,
 } from './parts';
 import glue from './specs/vl-final-glue.txt?raw';
 
@@ -39,7 +39,7 @@ const Cell = ({ caption, children, framed }: { caption?: string; children: React
 );
 
 /** One step of the traditional way: the code and chart before, then the code and chart after. */
-const Step = ({ before, beforeSpec, after, afterSpec, note }: { before: CodeRow[]; beforeSpec: unknown; after: CodeRow[]; afterSpec: unknown; note?: ReactNode }) => (<>
+const Step = ({ before, beforeSpec, after, afterSpec, note }: { before: CodeSource; beforeSpec: unknown; after: CodeSource; afterSpec: unknown; note?: ReactNode }) => (<>
   
→
@@ -50,11 +50,11 @@ const Step = ({ before, beforeSpec, after, afterSpec, note }: { before: CodeRow[ // Each step's code: the new spec with what changed in red. The next slide starts from it, in black. const ROWS = { - raw: stepRows(STEPS.raw), - parse: stepRows(STEPS.parse, STEPS.raw), - layout: stepRows(STEPS.layout, STEPS.parse), - theme: stepRows(STEPS.theme, STEPS.layout, 72), - final: stepRows(STEPS.final, STEPS.theme, 72), + raw: stepLayout(STEPS.raw), + parse: stepLayout(STEPS.parse, STEPS.raw), + layout: stepLayout(STEPS.layout, STEPS.parse), + theme: stepLayout(STEPS.theme, STEPS.layout), + final: stepLayout(STEPS.final, STEPS.theme), }; const DIFF = { parse: lineDiff(STEPS.raw, STEPS.parse), @@ -116,21 +116,28 @@ const BESPOKE_ROWS: CodeRow[] = [ { text: ' eventSource: lassoTrigger("contain"),', hot: true }, { text: ' affordances: { plot: { cursor: "draw" } },' }, { text: ' handle(event) {', hot: true }, - { text: ' // the stroke arrives as points in the data, not pixels', gap: true }, - { text: ' const guess = extendPath(drawn, event.geometry.domain.points);' }, + { text: ' // the stroke arrives in data units, not pixels', gap: true }, + { text: ' const points = event.geometry.domain.points;' }, + { text: ' const guess = extendPath(drawn, points);' }, { text: ' if (isComplete(guess)) reveal();' }, - { text: ' // answer with an update: draw the guess as an overlay', gap: true }, - { text: ' return { ops: [{ op: "set-overlay", name: "guess", value: guess }] };', hot: true }, + { text: ' // answer with an update: an overlay', gap: true }, + { text: ' return { ops: [', hot: true }, + { text: ' { op: "set-overlay",', hot: true }, + { text: ' name: "guess", value: guess },', hot: true }, + { text: ' ] };', hot: true }, { text: ' },' }, { text: '};' }, { text: '' }, - { text: '' }, + { text: '' }, ]; /** The World Cup demo's own wiring, condensed: the chart says what was clicked, the page does the rest. */ const APP_ROWS: CodeRow[] = [ { text: 'const spec = {' }, - { text: ' data, semantic_types: { Team: "Category", Goals: "Count" },' }, + { text: ' data,' }, + { text: ' semantic_types: {' }, + { text: ' Team: "Category", Goals: "Count" },' }, { text: ' chart_spec: { chartType: "Bar Chart",' }, { text: ' encodings: { x: "Goals", y: "Team" } },' }, { text: ' interaction_spec: { interactions: [' }, @@ -140,7 +147,7 @@ const APP_ROWS: CodeRow[] = [ { text: '' }, { text: ' setTeam(pinnedTeam(change))}', hot: true }, + { text: ' onChange={(c) => setTeam(pinnedTeam(c))}', hot: true }, { text: '/>', hot: true }, { text: '' }, ]; @@ -158,7 +165,7 @@ const SEMANTIC_TYPES: [string, string][] = [ /** The parts of the real "economist" preset that the theme slides talk about. */ const ECON = (THEME_PRESETS as Record }>).economist.spec; -const ECONOMIST_ROWS: CodeRow[] = specText({ +const ECONOMIST_ROWS = specLayout({ id: ECON.id, ink: { series: { @@ -172,12 +179,13 @@ const ECONOMIST_ROWS: CodeRow[] = specText({ axis: { measure: { line: ECON.structure.axis.measure.line, placement: ECON.structure.axis.measure.placement } }, grid: { category: ECON.structure.grid.category, zero: ECON.structure.grid.zero }, }, -}, 84).split('\n').map((text) => ({ text })); +}); const INTERACTION_ROWS: CodeRow[] = [ { text: '"interaction_spec": {' }, { text: ' "interactions": [' }, - { text: ' { "type": "click-group-focus", "options": { "groupBy": "game" } }', hot: true }, + { text: ' { "type": "click-group-focus",', hot: true }, + { text: ' "options": { "groupBy": "game" } }', hot: true }, { text: ' ]' }, { text: '}' }, { text: '' }, @@ -187,8 +195,10 @@ const INTERACTION_ROWS: CodeRow[] = [ { text: '' }, { text: '// the update it can send back', gap: true }, { text: '{ "ops": [' }, - { text: ' { "op": "set-style", "targets": [target], "value": { "state": "emphasized" } },', hot: true }, - { text: ' { "op": "set-annotation", "target": target, "value": { "text": "Launch month" } }', hot: true }, + { text: ' { "op": "set-style", "targets": [target],', hot: true }, + { text: ' "value": { "state": "emphasized" } },', hot: true }, + { text: ' { "op": "set-annotation", "target": target,', hot: true }, + { text: ' "value": { "text": "Launch month" } }', hot: true }, { text: '] }' }, ]; const TYPES_COMPILED = typesCompiled(); @@ -209,7 +219,7 @@ const UPDATE_SLIDES: SlideDef[] = UPDATES.reduce<{ state: FlintState; slides: Sl

"{u.prompt}"

- +
@@ -268,7 +278,7 @@ export const SLIDES: SlideDef[] = [ id: 'ideal', render: () => (<>

Ideally, a chart is a few lines that are easy to change

-
+
), @@ -277,7 +287,7 @@ export const SLIDES: SlideDef[] = [ id: 'ideal-bar', render: () => (<>

Switching to a bar chart is one small edit

-
+
), @@ -313,7 +323,7 @@ export const SLIDES: SlideDef[] = [ id: 'attempt-2', render: () => (<>

Attempt two: five years of months need a new layout

Sixty months crowd the axis with Jan to Dec five times over. We widen the chart, label each year once, give long game names room, and move the legend to the top. That adds {DIFF.layout.plus} lines and changes {DIFF.layout.minus}.} /> @@ -323,7 +333,7 @@ export const SLIDES: SlideDef[] = [ id: 'theme-vl', render: () => (<>

Making it look like The Economist is mostly new work

Fonts and axes go into the config, the house colours into the encoding, and the red tab, headline, and source line become extra views placed by hand. The spec grows by {DIFF.theme.plus} lines.} /> @@ -333,7 +343,7 @@ export const SLIDES: SlideDef[] = [ id: 'interaction-vl', render: () => (<>

Then clicking a game should highlight its row

Selection parameters and conditional styles are woven into the opacity, the stroke, and the axis labels, adding {DIFF.final.plus} lines across the spec.} /> @@ -430,7 +440,7 @@ export const SLIDES: SlideDef[] = [ id: 'flint-version', render: () => (<>

The same chart, written in Flint

-
+

A few lines on the raw data, with the same look. Click a game to try it.

@@ -453,7 +463,7 @@ export const SLIDES: SlideDef[] = [ id: 'a-what', render: () => (<>

Say what each field means, and the compiler does the rest

-
({ text, hot: /YearMonth|Category|Profit|semantic_types/.test(text) }))} />
+
), @@ -464,7 +474,7 @@ export const SLIDES: SlideDef[] = [

And this is what the compiler wrote in Vega-Lite

- ({ text, hot: /YearMonth|Category|Profit|semantic_types/.test(text) }))} /> +

The Flint spec, on the raw rows.

→
@@ -667,7 +677,7 @@ export const SLIDES: SlideDef[] = [

"Create a theme inspired by a Disneyland day out: candy colors, rounded shapes, and a playful font."

- ({ text }))} max={18} /> +
)} /> diff --git a/site/src/talk/specs/vl-final-glue.txt b/site/src/talk/specs/vl-final-glue.txt index 1042fe3f..8675fdce 100644 --- a/site/src/talk/specs/vl-final-glue.txt +++ b/site/src/talk/specs/vl-final-glue.txt @@ -13,10 +13,11 @@ export async function mount(el, spec, rows) { showRows(rows.filter((r) => games.includes(r.game))); }); - // picker -> chart: write a point tuple into the selection's internal store + // picker -> chart: write a tuple into the selection's store gamePicker(rows, async (game) => { const fields = [{ type: 'E', field: 'game' }]; - const tuples = game ? [{ unit: UNIT, fields, values: [game] }] : []; + const tuple = { unit: UNIT, fields, values: [game] }; + const tuples = game ? [tuple] : []; const change = changeset().remove(() => true).insert(tuples); await view.change('pick_store', change).runAsync(); });