@pixerate/editor 0.161.0 → 0.162.1

package/dist/vector/index.js

@@ -38,7 +38,7 @@ import {
   reverseMorphContour,
   subpathToMorphContour,
   turnMorphContour
-} from "../chunk-WNAAWLZ5.js";
+} from "../chunk-QY4KUDMY.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -507,8 +507,8 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-6UPGM3JB.js";
-import "../chunk-A5UCR2TO.js";
+} from "../chunk-SET6KJOP.js";
+import "../chunk-YXKLVD56.js";
 import {
   createProvenance
 } from "../chunk-M6DNZNVY.js";
@@ -566,11 +566,12 @@ import {
   HistoryManager
 } from "../chunk-RNSANXPT.js";
 import "../chunk-5UJHB3BW.js";
-import "../chunk-KY3FYKP3.js";
+import "../chunk-BQWGN5WH.js";
 import {
   hexToRgba
 } from "../chunk-2WPNAGHI.js";
-import "../chunk-AA34BA7G.js";
+import "../chunk-QYZGBVNC.js";
+import "../chunk-4VU4CP7R.js";
 import "../chunk-6ONMQ6WF.js";
 
 // src/vector/trace.ts

package/dist/video-editor/index.cjs

@@ -168,14 +168,15 @@ require('../chunk-2BSBFBOA.cjs');
 var _chunkFJ2MSI43cjs = require('../chunk-FJ2MSI43.cjs');
 
 
-var _chunkSUF6WRXRcjs = require('../chunk-SUF6WRXR.cjs');
+var _chunkGTELFJREcjs = require('../chunk-GTELFJRE.cjs');
 
 
 
 var _chunkDWJJI6RTcjs = require('../chunk-DWJJI6RT.cjs');
-require('../chunk-LEUZ4FRC.cjs');
+require('../chunk-CIPIESX4.cjs');
 require('../chunk-A6QWKBJP.cjs');
-require('../chunk-UKCJ43YL.cjs');
+require('../chunk-ES3UEVUT.cjs');
+require('../chunk-S6X2QRVU.cjs');
 require('../chunk-IPJ3TEYR.cjs');
 
 // src/video-editor/parse.ts
@@ -3356,7 +3357,7 @@ var VideoEditorController = (_class7 = class _VideoEditorController {
     this.readOnly = _nullishCoalesce(options.readOnly, () => ( false));
     this.previewScale = checkPreviewScale(_nullishCoalesce(options.previewScale, () => ( "auto")));
     this.onChange = options.onChange;
-    this.player = new (0, _chunkSUF6WRXRcjs.AnimationPlayer)({ clock: options.clock, duration: () => _chunk3OSXHLITcjs.videoProjectDuration.call(void 0, this.project), loop: "none" });
+    this.player = new (0, _chunkGTELFJREcjs.AnimationPlayer)({ clock: options.clock, duration: () => _chunk3OSXHLITcjs.videoProjectDuration.call(void 0, this.project), loop: "none" });
     this.state = this.computeState();
     this.connect();
   }

package/dist/video-editor/index.js

@@ -168,14 +168,15 @@ import {
 } from "../chunk-RNSANXPT.js";
 import {
   AnimationPlayer
-} from "../chunk-AY65VQSU.js";
+} from "../chunk-H3OEM3Q2.js";
 import {
   CUBIC_BEZIER_PRESETS,
   evaluateEasing
 } from "../chunk-5UJHB3BW.js";
-import "../chunk-KY3FYKP3.js";
+import "../chunk-BQWGN5WH.js";
 import "../chunk-2WPNAGHI.js";
-import "../chunk-AA34BA7G.js";
+import "../chunk-QYZGBVNC.js";
+import "../chunk-4VU4CP7R.js";
 import "../chunk-6ONMQ6WF.js";
 
 // src/video-editor/parse.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.161.0",
+  "version": "0.162.1",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",
@@ -244,6 +244,16 @@
         "default": "./dist/color/index.cjs"
       }
     },
+    "./typography": {
+      "import": {
+        "types": "./dist/typography/index.d.ts",
+        "default": "./dist/typography/index.js"
+      },
+      "require": {
+        "types": "./dist/typography/index.d.cts",
+        "default": "./dist/typography/index.cjs"
+      }
+    },
     "./gradient": {
       "import": {
         "types": "./dist/gradient/index.d.ts",
@@ -361,7 +371,7 @@
     "prosemirror-markdown": "^1.13.9"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.137.0",
+    "@anthropic-ai/sdk": "1.1.0",
     "@dagrejs/dagre": "^1.1.8",
     "@tiptap/core": "^2.27.3",
     "@tiptap/pm": "^2.27.3",
@@ -369,7 +379,7 @@
     "@types/markdown-it": "^14.2.0",
     "@types/node": "^26.6.5",
     "assemblyscript": "0.28.20",
-    "fast-check": "^3.23.2",
+    "fast-check": "^4.10.2",
     "mermaid": "12.2.0",
     "tiptap-markdown": "^0.8.10",
     "tsup": "^9.0.0",

package/skills/README.md

@@ -25,6 +25,7 @@ that uses the tools can load the matching skill.
 | [`pixerate-tokens`](pixerate-tokens/SKILL.md) | Design tokens: collections, modes, variables and aliases, through the whole-set document tools. |
 | [`pixerate-effect-authoring`](pixerate-effect-authoring/SKILL.md) | Authoring shaders and procedural effects: inspecting parameters and source code, setting values and presets, keyframing animation tracks, playback timing, and previewing. |
 | [`pixerate-color`](pixerate-color/SKILL.md) | Colour inspection, WCAG accessibility and contrast optimization, CVD simulation, palette audits, harmonies, and OKLab/OKLCH blends. |
+| [`pixerate-typography`](pixerate-typography/SKILL.md) | Fonts and fallback stacks, font loading, modular type scales and hierarchies, fluid sizes, readability and type-aware contrast audits, text segmentation, the font picker. |
 
 ## Using them
 

package/skills/pixerate-chart/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixerate-chart
-description: How to build, edit and check charts in the Pixerate chart editor through its agent tools and chart.* commands - bar, column, line, area, scatter, bubble, pie, donut, radar, waterfall, histogram, box plot, funnel and treemap charts; series, categories, stacking, secondary axis, log axis, number formats, data labels, legend, trendline, error bars, colour palettes and colour-blind checks, CSV and Mermaid import, Office chart XML export, and reading charts out of open .xlsx, .pptx and .docx files. Use when a chart editor's tools (get_chart, update_chart, set_chart_values, list_file_charts...) are available or the user asks to make, restyle, fix or explain a chart.
+description: How to build, edit and check charts in the Pixerate chart editor through its agent tools and chart.* commands - bar, column, line, area, scatter, bubble, pie, donut, radar, waterfall, histogram, box plot, funnel, treemap (flat or grouped), sunburst, slope, Likert (survey) and parliament charts; series, categories, stacking, secondary axis, log axis, number formats, data labels, legend, trendline, error bars, reference lines and target bands, callouts, highlighting, footnotes, colour palettes and colour-blind checks, CSV and Mermaid import, Office chart XML export, and reading charts out of open .xlsx, .pptx and .docx files. Use when a chart editor's tools (get_chart, update_chart, set_chart_values, list_file_charts...) are available or the user asks to make, restyle, fix or explain a chart.
 ---
 
 # Charts
@@ -10,10 +10,19 @@ A chart editor holds one `ChartSpec`: a `type`, `title` / `subtitle`, `xAxis` /
 a list of `categories` (strings, in order) and a list of `series`. Each series has an `id`
 (such as `series-1`), a `name` and one value per category (`null` is a gap), plus optional
 per-series settings (type for combos, secondary axis, marker, colour, format, trendlines,
-error bars). Tools take a series by id or exact name and a category by 0-based index or
-exact label; `get_chart` returns both. Pie, donut, funnel and treemap draw only the first
-visible series, one slice per category; histogram and box read every value of the visible
-series.
+error bars, callouts). Annotations sit on the spec: `note` (footnote), `highlight` (names of
+categories and series to keep bright), `referenceLines`, `referenceBands` and `varyColors`. Tools take a series by id or exact name and a category by 0-based index or
+exact label; `get_chart` returns both. Pie, donut, funnel, treemap and parliament draw only
+the first visible series, one slice (or group of seats) per category; histogram and box read
+every value of the visible series. A slope chart joins the first series (before) to the
+second (after) for each category; a Likert chart reads each category as a question and the
+series as its answers, ordered from most negative to most positive.
+
+Grouped data lives in `spec.tree` (items `{name, value}`, groups `{name, children}`, up to 6
+levels). When a tree is set it *is* the data: the categories are its top-level group names
+and the first series their totals, so a treemap nests the groups, a sunburst draws them as
+rings, and any other type draws the totals. Nodes are addressed by `path`, the names from the
+top down (`["Europe", "France"]`); `get_chart` returns them as `treeTable`.
 
 Read `pixerate-agent-tools` first for tool naming, errors and `run_commands` batching.
 Charts inside a rich-text document are not edited with these tools: use `insert_chart`,
@@ -34,10 +43,15 @@ Charts inside a rich-text document are not edited with these tools: use `insert_
 4. **Style in one call.** Put type, titles, axes, legend, stacking and labels in a single
    `update_chart`; it is all-or-nothing and one undo step. Use `apply_chart_preset` for a
    coherent layout or colour scheme, `update_chart_series` for per-series settings.
-5. **Check.** Read the `warnings` that `get_chart` and `render_chart` return (hidden or
+5. **Point the reader at the message.** Once the data and style are right, annotate:
+   `add_chart_reference_line` for a target or average, `add_chart_reference_band` for a
+   normal or target range, `set_chart_callout` on the one or two points the title talks
+   about, `highlight_chart` to mute what does not matter, and `note` (in `update_chart`) for
+   the source.
+6. **Check.** Read the `warnings` that `get_chart` and `render_chart` return (hidden or
    thinned labels, crowded legend, skipped values) and run `check_chart_colors`. Fix every
    problem.
-6. **Look once.** `render_chart` with `format: "png"` after a batch of edits, at the size
+7. **Look once.** `render_chart` with `format: "png"` after a batch of edits, at the size
    the chart will be shown, to check overlap and legibility. Use `undo_chart` for your own
    mistakes.
 
@@ -49,7 +63,15 @@ Charts inside a rich-text document are not edited with these tools: use `insert_
   stacked bar or `stacking: "percent"` for shares across groups; pie or donut only for one
   whole with few parts. Distribution: histogram (`bins`, default the square root of n) or
   box. Relationship: scatter with `series.x`, bubble with `sizes` for a third measure.
-  Running totals and bridges: waterfall (`showTotal`). Staged drop-off: funnel.
+  Running totals and bridges: waterfall (`showTotal`). Staged drop-off: funnel. What rose
+  and what fell between two points in time: slope (two series, the names are the column
+  captions). Agree-to-disagree survey answers: likert (`likertSort: "positive"` ranks the
+  questions; `likertNeutral: "separate"` keeps the middle answer out of the comparison).
+  Parts of parts (regions → countries, budget → departments → teams): a treemap with grouped
+  data for comparing sizes, a sunburst for showing the levels (`sunburstLabel` captions the
+  total in the middle). Load the levels with `import_chart_tree_csv` or `set_chart_tree`.
+  Seats or votes per group with a majority: parliament (`parliamentMajority`,
+  `parliamentArc`, `parliamentLabel`).
 - **Bars start at zero.** Bar length encodes the value, so never set a non-zero `min` on the
   value axis of a bar, column or area chart. Line and scatter charts may zoom to the data
   range when the change, not the magnitude, is the point.
@@ -81,6 +103,19 @@ Charts inside a rich-text document are not edited with these tools: use `insert_
   (`showR2`) and read it with `get_chart_trendline` before describing the trend; label any
   `forward` forecast as a projection. Exponential, power and log fits need positive values;
   category charts fit against x = 1, 2, 3.
+- **Annotate sparingly.** One or two reference lines, one band and a couple of callouts at
+  most; every label competes with the data. Label every reference line (`label`) so the
+  reader knows what it is, and keep callouts to a few words that say *why* the point
+  matters ("Launch", "Strike"), not its value (that is what data labels are for).
+- **Highlight instead of recolouring.** To show one bar or series against the rest, use
+  `highlight_chart` (it mutes the rest and keeps the palette) rather than greying series by
+  hand. Name categories to pick bars or points, series to pick whole lines. Clear it with
+  `names: []`.
+- **One series, many categories:** `varyColors: true` gives each bar its own palette colour
+  and a category legend. Use it only when colour carries meaning (brands, teams); a ranked
+  bar chart reads better in one colour.
+- **Cite the source** in `note` ("Source: ONS, 2025"); it sits under the chart, apart from
+  the title.
 - **Error bars:** say what they are (standard deviation, standard error, confidence) in the
   title or subtitle.
 
@@ -109,7 +144,7 @@ it changed.
 
 | Tool | Use it to |
 | --- | --- |
-| `update_chart` | Change presentation in one all-or-nothing call: `type`, `title`, `subtitle`, `xAxis` / `yAxis` / `yAxis2` (show, title, min, max, step, gridlines, format, kind `"date"`, scale `"log"`, logBase, reverse), `legend` (show, position top / bottom / left / right), `stacking` (none / stacked / percent), `orientation`, `curve`, `points`, `dataLabels`, `labelPosition`, `palette`, `innerRadius` (donut hole, 0-0.9), `gapWidth`, `overlap`, `bins`, `showTotal`, `radarTicks` (radar ring count 1-50, null for round numbers), `radarGraticule` (radar rings as `polygon` or `circle`). Invalid values change nothing and come back as sentences. Returns the spec. |
+| `update_chart` | Change presentation in one all-or-nothing call: `type`, `title`, `subtitle`, `xAxis` / `yAxis` / `yAxis2` (show, title, min, max, step, gridlines, format, kind `"date"`, scale `"log"`, logBase, reverse), `legend` (show, position top / bottom / left / right), `stacking` (none / stacked / percent), `orientation`, `curve`, `points`, `dataLabels`, `labelPosition`, `palette`, `innerRadius` (donut hole, 0-0.9), `gapWidth`, `overlap`, `bins`, `showTotal`, `radarTicks` (radar ring count 1-50, null for round numbers), `radarGraticule` (radar rings as `polygon` or `circle`), `note` (footnote, "" for none), `highlight` (whole list of names), `referenceLines` / `referenceBands` (whole lists; prefer the add tools), `varyColors` (one colour per category on a one-series chart), `likertNeutral` (`split` / `separate`), `likertSort` (`none` / `positive` / `negative`), `parliamentArc` (90-360 degrees), `parliamentMajority` (seats, null for half plus one), `parliamentLabel` (caption under the total), `sunburstLabel` (caption under a sunburst's total). Invalid values change nothing and come back as sentences. Returns the spec. |
 | `set_chart_data` | Replace `categories` and / or all `series` (each with `name`, `values` and optional settings). Values are padded with gaps to the categories. Use for whole tables and for re-sorting. Returns the table and series ids. |
 | `set_chart_values` | Set individual `cells` (`series`, `category`, `value`) all-or-nothing. Values may be numbers, numeric text (`"1,200"`, `"12%"`, `"$40"`, `"(3)"`) or `null` for a gap. Returns the stored values. Acted out with a cursor when the host has a director. |
 | `add_chart_series` | Add a series (`name` required; `values`, `color`, `type` for a combo, `axis: "secondary"`, `x` / `sizes` for scatter and bubble, marker, format, error bars, `id`, `at`). Selects it and returns its id. |
@@ -123,6 +158,19 @@ it changed.
 | `load_file_chart` | Replace the editor's chart with one from an Office file (`file` or `data`, `chartId`). Returns the spec, read problems and the features the editor could not keep; tell the user about any. |
 | `add_chart_trendline` | Fit a trendline to a series (`type`: linear, exponential, logarithmic, power, polynomial with `order` 2-6, moving-average with `period`; `forward` / `backward` in x units, `intercept`, `showEquation`, `showR2`). Unstacked bar, line, area, scatter and bubble charts only. Returns its index, coefficients, R2 and equation. |
 | `remove_chart_trendline` | Delete a trendline by `series` and `index`. |
+| `add_chart_reference_line` | Draw a dashed line across the plot at `value` (a target, floor or average) with an optional `label`, `color` and `axis` (`y` default, `y2` for the secondary axis, `x` for numeric x on scatter and bubble). Bar, line, area, scatter and bubble charts; the axis grows to keep it in view. Returns its `index`. |
+| `update_chart_reference_line` | Change a reference line by `index` (from `add_chart_reference_line` or `spec.referenceLines`); `null` removes the label, colour or axis. Returns the line as stored. |
+| `remove_chart_reference_line` | Delete a reference line by `index`; later ones move up. Returns the rest. |
+| `add_chart_reference_band` | Shade a range from `from` to `to` (a target or normal range) under the data, with an optional `label`, `color` and `axis`. Same charts as reference lines. Returns its `index`. |
+| `update_chart_reference_band` | Change a reference band by `index`; `null` removes the label, colour or axis. |
+| `remove_chart_reference_band` | Delete a reference band by `index`. Returns the rest. |
+| `set_chart_callout` | Pin a short `label` to one bar or point (`series`, `category`) with a leader line; `label: null` removes it. The point needs a value. Bar, line, area, scatter and bubble charts. Selects the point. |
+| `highlight_chart` | Keep the named categories and series (`names`) bright and mute everything else; `[]` clears it. Unknown names change nothing and are listed. Returns the matched category indexes and series ids. |
+| `set_chart_tree` | Replace the data with grouped data (`tree`: items `{name, value}`, groups `{name, children}`, up to 6 levels, sibling names unique) for grouped treemaps and sunbursts; `[]` goes back to plain data and keeps the totals. Returns the tree, group totals and depth. |
+| `import_chart_tree_csv` | Replace the data with grouped data from CSV / TSV: names in every column but the last (group, ..., item), the value last; a blank group name repeats the one above. The quickest way to load a spreadsheet's hierarchy. |
+| `add_chart_tree_node` | Add an item or a group (`node`) under the group at `parent` (a path; `[]` for the top level) at `at`. Returns its `path` and the parent's new total. |
+| `update_chart_tree_node` | Rename a node, set an item's `value`, or set a node's `color` (null for the palette) by `path`. Groups have no value of their own. Returns the path (new after a rename). |
+| `remove_chart_tree_node` | Delete a node and everything under it by `path`. Returns the group totals left. |
 | `apply_chart_preset` | Apply a quick `layout` and / or a `colors` scheme from `list_chart_presets` in one step. |
 | `transpose_chart` | Swap series and categories. Drops per-series colours and settings, so restyle afterwards. |
 | `select_chart_element` | Select part of the chart (`kind`: none, chart, title, subtitle, legend, axis, series, point, category, trendline) for the user to see or before `press_chart_key`. |
@@ -166,6 +214,19 @@ several charts may register them with another prefix.
 | `chart.removeCategory` | Delete a category by index or label. |
 | `chart.addTrendline` | Fit a trendline (as `add_chart_trendline`). |
 | `chart.removeTrendline` | Delete a trendline. |
+| `chart.addReferenceLine` | Add a reference line (as `add_chart_reference_line`). |
+| `chart.updateReferenceLine` | Change a reference line by index. |
+| `chart.removeReferenceLine` | Delete a reference line by index. |
+| `chart.addReferenceBand` | Add a reference band (as `add_chart_reference_band`). |
+| `chart.updateReferenceBand` | Change a reference band by index. |
+| `chart.removeReferenceBand` | Delete a reference band by index. |
+| `chart.setCallout` | Pin or remove a point's callout (as `set_chart_callout`). |
+| `chart.highlight` | Highlight categories and series (as `highlight_chart`). |
+| `chart.setTree` | Replace the grouped data (as `set_chart_tree`). |
+| `chart.importTreeCsv` | Replace the data with grouped data from CSV / TSV. |
+| `chart.addTreeNode` | Add an item or group; returns its path. |
+| `chart.updateTreeNode` | Rename, revalue or recolour a node by path. |
+| `chart.removeTreeNode` | Delete a node by path. |
 | `chart.applyPreset` | Apply a quick layout and / or colour scheme. |
 | `chart.transpose` | Swap series and categories. |
 | `chart.importCsv` | Replace data from CSV / TSV (no automatic chart type). |
@@ -190,6 +251,28 @@ several charts may register them with another prefix.
 - Percent-stacked charts, pies and gaps cannot be dragged; use `set_chart_values`.
 - Radar needs at least three categories (it draws as a line chart until then); trendlines
   are refused on stacked charts, pies and the other single-series families.
+- Likert answers must be entered in order, most negative first: the chart puts the first
+  half left of the centre line and colours them orange, the last half right in purple.
+  Values are counts or shares; each question is scaled to its own total.
+- A slope chart needs exactly two visible series; with one it draws a line chart (a
+  `type-fallback` warning), and a third is not drawn. Hide the extra series or move them.
+- Parliament seats are rounded to whole numbers; more than 2,000 seats are not drawn.
+- While a chart has grouped data, cell edits (`set_chart_values`, adding, renaming or deleting
+  categories, `transpose_chart`) are refused, because the totals come from the tree. Edit the
+  nodes, or replace the data (`set_chart_data`, `import_chart_csv`), which clears the tree.
+- Highlight, selection and colours work per top-level group: every item in a group selects
+  and highlights that group. Give a node its own `color` with `update_chart_tree_node`.
+- Office export writes a grouped treemap or sunburst as a pie or doughnut of the group totals
+  (DrawingML has no hierarchy); Office chartex imports keep the levels.
+- Reference lines, bands and callouts are drawn on bar, line, area, scatter and bubble
+  charts only. Switching to another type keeps them in the spec but leaves them out of the
+  drawing (an `annotations-skipped` warning says so); they come back when you switch back.
+- Reference values on a log axis must be above 0, and `axis: "y2"` needs a visible series on
+  the secondary axis. A line outside a fixed `min` / `max` is not drawn.
+- Callouts and highlight names follow the data: removing a category drops its callouts and
+  its highlight entry, renaming a category or series keeps it highlighted.
+- Office export has no reference lines, bands, callouts, highlight or note; `export_chart_ooxml`
+  lists them as not written. `varyColors` is kept.
 - Radar `radarTicks` and `radarGraticule` are Mermaid's `ticks` and `graticule`. A
   `radar-beta` block with no `graticule` line imports as `circle`, because that is what
   Mermaid draws; set `radarGraticule: "polygon"` if the user wants the editor's default look.

package/skills/pixerate-paint-editor/SKILL.md

@@ -420,8 +420,6 @@ for the controls and presets.
 | `export_psd` | Export a PSD with every layer, the paper as a locked bottom layer, and the composite. Pigment and painterly modes are written as their nearest standard mode (`list_blend_modes` `psd`). Returns base64, size, `psb` and `warnings`. |
 | `export_time_lapse` | Repaint the painting from its recorded strokes and events as a time-lapse: `frames` (about how many), `fps`, `maxSide`, `wetStepsPerFrame` (frames while wet paint flows), `holdMs`. Returns a contact sheet image, the frame count, size, duration, a video project of the frames and the ffmpeg command that renders `timelapse.mp4`; `includeFrames` adds every frame as base64 PNG. Changes nothing. |
 | `export_high_res` | Repaint the painting from its strokes at `scale` 1..8 (brushes, grain, fills and wet events scaled): a PNG with real detail instead of upscaled pixels. Returns base64, size. Layers not painted with strokes come out empty. |
-| `save_document` | Deprecated, kept for one minor version: use `get_paint_document` or `save_paint_document`. Returns the document JSON with PNG data URLs inline (large). |
-| `open_document` | Deprecated, kept for one minor version: use `load_paint_document` or `open_saved_paint_document`. Opens a document JSON from `save_document`, clearing the undo history. |
 
 ### Save and open
 

package/skills/pixerate-typography/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: pixerate-typography
+description: How to choose and load fonts, build resilient font-family fallback stacks, generate modular type scales and heading hierarchies, compute fluid clamp() sizes, audit body text for line length and line spacing, check text contrast with the real font size and weight, split text into letters, words or lines for animation, and drive a font picker. Use when asked to pick or pair fonts, set up type tokens, check readability or legibility, or animate live text.
+---
+
+# Typography tools
+
+The typography module is DOM-free: it works on numbers (px sizes, unitless line-heights, em
+tracking) and family names, never on rendered pixels. Fonts come from a **font provider** the
+host supplies (installed system fonts, a web font service, a design system's families); by
+default it is a catalog of common system fonts, which says what is *usually* installed, not
+what this machine has.
+
+## Mental model
+
+- A **font spec** is `{ family, weight, style, size (px), lineHeight (unitless), letterSpacing (em) }`.
+- A **type scale** multiplies a base size by a ratio per step (`16 × 1.25² = 25`). A **hierarchy**
+  names the steps: `caption` (−2), `body-sm`, `body` (0), `h4`, `h3`, `h2`, `h1`, `display` (5).
+- A **fallback stack** is the `font-family` value: your family, then a tested cross-platform stack
+  for its category, ending in a generic family, so text still renders when the font is missing.
+- **Large text** under WCAG 2 is 24px, or 18.67px (14pt) at weight 700+. It needs 3:1 contrast
+  for AA instead of 4.5:1. The accessibility tool decides this from the spec for you.
+
+## Working method
+
+1. **Find fonts.** `list_fonts` with `category`, `weight`, `style` or `query`. Only use families it
+   returns (or that the user names), and always ship them inside a stack from `resolve_font_stack`.
+2. **Load before rendering.** `load_font` before drawing or capturing text in a web font, so the
+   first frame does not use the fallback. `loaded: false` means the fallback will show.
+3. **Set up the scale.** `generate_type_hierarchy` for named tokens and ready CSS custom
+   properties; `suggest_type_scale` for arbitrary steps. Smaller ratios (minor/major third) suit
+   dense UI; larger ones (perfect fourth/fifth, golden) suit editorial and marketing pages.
+4. **Make it fluid (optional).** `compute_fluid_type_size` for headings that grow between two
+   viewport widths. Bounds are in rem so browser zoom and font-size settings still work.
+5. **Audit the body text.** `audit_text_readability` with the real text, `fontSize`, `lineHeight`
+   and the column `width`: fix `lineLength.status` (45–75 characters) and `lineSpacing`
+   (at least 1.5) before polishing anything else.
+6. **Check contrast with the type.** `check_typography_accessibility` with foreground, background,
+   `fontSize` and `fontWeight`. Use `suggestion` when `passesAA` is false. For pure colour work
+   (palettes, dual colours) use the `pixerate-color` tools.
+7. **Animate live text.** `segment_text` splits into `grapheme`, `word` (with `wordsOnly`),
+   `sentence` or `line` (with `maxCharacters` to wrap) and returns UTF-16 `start` / `end`
+   offsets, so letters and words can be staggered without converting text to outlines.
+8. **Drive the on-screen picker.** When a font picker is mounted, `get_font_selection` shows what
+   is chosen, `list_picker_fonts` what it offers, and `set_font_selection` changes any fields in
+   one step and returns the new selection.
+
+## Best practices
+
+- **Two families are usually enough**: one for text, optionally one for headings. Pair by contrast
+  of category (serif headings with sans text, or the reverse), not by two similar sans-serifs.
+- **Body text at 16px or more**, line-height 1.5–1.7, about 66 characters per line
+  (`max-width: 66ch`). Headings get tighter leading (1.1–1.3) and slightly negative tracking; small
+  captions slightly positive tracking. The scale tools already recommend these.
+- **Use weight 400+ below 24px.** Thin weights lower effective contrast even when the ratio passes.
+- **Avoid long runs of capitals** for body text; keep all-caps to short labels.
+- **Prefer rem and clamp()** over fixed px for type on the web, so user settings apply.
+- **Never assume a font is installed.** A system font in the catalog may be missing on Linux or
+  Android; the fallback stack is what makes that safe.
+
+## Tool reference
+
+| Tool | When to use | Returns |
+| --- | --- | --- |
+| `list_fonts` | Discover families the host offers; filter by `category`, `source`, `weight`, `style`, `query`; `limit` default 50 | `{ fonts: [{ family, category, weights, styles, isVariable?, source }], total, truncated }` |
+| `resolve_font_stack` | Turn a family (or stack) into a resilient `font-family` value for its category; also says if the provider lists it | `{ stack, families, category, available }` |
+| `suggest_type_scale` | Sizes for arbitrary integer `steps` (-12…12) from `baseSize` (px, default 16) and `ratio` (name or number, default major-third) | `{ ratio, baseSize, steps: [{ name, step, size, lineHeight, letterSpacing }] }` |
+| `generate_type_hierarchy` | Named tokens caption…display on one scale, with CSS custom properties (`prefix`, `selector`) | `{ ratio, ratioName?, baseSize, steps: { body, h1, … }, css }` |
+| `compute_fluid_type_size` | A size that grows from `minSize` at `minViewport` to `maxSize` at `maxViewport` (all px) | `{ clampCss, slope, intercept, samples }` |
+| `audit_text_readability` | Check body text: line length (own lines, or `width` + `fontSize`), line spacing, capitals, tiny or tight type, reading time | `{ lineLength, lineSpacing, allCaps, wordCount, estimatedReadingTimeSeconds, issues }` |
+| `check_typography_accessibility` | Contrast for text of a given `fontSize` (px) and `fontWeight`, deciding large text itself; suggests a passing foreground | `{ ratio, large, level, passesAA, passesAAA, required, suggestion?, largeTextMinSize, issues }` |
+| `segment_text` | Split text into graphemes, words, sentences or lines with offsets, for staggered animation | `{ segments: [{ text, start, end, index, isWordLike? }], count }` |
+| `load_font` | Load a family's face (`weight`, `style`) before rendering or capturing; only listed when the provider can load | `{ family, weight, style, loaded }` |
+| `get_font_selection` | Read the mounted font picker's value, CSS and the chosen family's weights and styles | `{ value, css, availableWeights, availableStyles }` |
+| `list_picker_fonts` | Families the mounted picker offers (by `category`, `query`), plus recent families | `{ fonts, recent, total, truncated }` |
+| `set_font_selection` | Change the picker's family, weight, style, size, lineHeight or letterSpacing in one validated step; weights snap to what the family has | `{ value, css, availableWeights, availableStyles }` |
+
+## Pitfalls
+
+- **Sizes are CSS px.** 12pt is 16px; 18pt is 24px. Convert before calling the tools.
+- **lineHeight is a multiplier**, not px: 24px leading on 16px text is `1.5`. When it is omitted
+  the audit assumes the browser's `normal` (about 1.2) and says so with `assumed: true`.
+- **`line` segmentation does not know the renderer's wrapping.** Without `maxCharacters` it only
+  splits on line breaks; with it, it wraps by character count, which approximates proportional
+  fonts.
+- **A one-line string is not a measure.** `too-short` on a single heading is expected; pass the
+  column `width` and `fontSize` to estimate how paragraphs will wrap.
+- **The system catalog is not detection.** Without the host opting into Local Font Access,
+  `list_fonts` lists commonly installed fonts. Always use `resolve_font_stack` output.
+- **Picker fonts may differ from `list_fonts`.** `set_font_selection` only accepts families the
+  picker lists; check with `list_picker_fonts`.