Results

Every result kind a tool can return, its attributes, and an example of each.

Generated from packages/sdk/src/types.ts

A tool's run returns one result. The runtime draws it: a tool never writes HTML. Every result is an object with a kind, and a group holds several.

Kinds

Kind	Use it for	Required	Since
`fields`	Label and value pairs, optionally grouped	`fields`	v1
`text`	Prose, or preformatted text	`text`	v1
`code`	Source with a language, painted by the host's highlighter	`lang` `source`	v1
`table`	Rows and typed columns, optionally linked to a chart	`columns` `rows`	v1
`series`	Line, area, bar, scatter, box and other x/y charts	`chart`	v1
`heatmap`	A value over two dimensions	`heatmap`	v4
`pie`	Parts of a whole, or a donut with its total	`pie`	v4
`radar`	A profile across several measures	`radar`	v4
`treemap`	A hierarchy sized by value	`treemap`	v4
`venn`	How two or three sets overlap	`venn`	v4
`graph`	Nodes and edges, laid out by the runtime	`graph`	v7
`group`	Several results in one answer	`parts`	v1
`bytes`	Hex dump with offsets, a printable gutter and named ranges	`bytes`	v2
`error`	The input was wrong, and the tool says which one	`message`	v1

Common attributes

Any result, or any part of a group, may carry these.

Attribute	Type	Required	Since	Notes
`role`	`string`	no	v5	What this part is to the reader, `"verdict"` or `"stats"` say, rendered as `data-role` on the part's root element for host CSS and tests to find it by name rather than by position.
`id`	`string`	no	v5	A name for this one part, unique within the result, rendered as `data-part`, so a page can link to it: `host.reveal(id)` opens it if it is collapsed, scrolls to it and moves focus there. Where `role` says what kind of part this is, `id` says which one.

JSON

{  "kind": "fields",  "id": "stats",  "role": "stats",  "fields": [    {"label": "Fields that are data", "value": "6 of 8"},    {"label": "Accept any text", "value": "2", "note": "1 high risk"},    {"label": "Tools checked", "value": "4"}  ]}

A part of what bench/fixtures/styled-output returns, named stats for a host stylesheet.

fields

Attribute	Type	Required	Since	Notes
`fields`	`Field[]`	yes	v1	Shown in order as a list of labels and values, grouped by `group`. A card shows the first `cardFields`.

Field

A label and a value. The plainest thing a tool can say.

Attribute	Type	Required	Default	Since	Notes
`label`	`string`	yes		v1	What the value is: the term the value is listed under.
`value`	`string`	yes		v1	The value, shown as the tool formatted it.
`note`	`string`	no		v1	A qualifier shown beside the value: a unit, a caveat, "(dynamic)".
`group`	`string`	no		v1	Fields sharing a group are rendered together under its name.
`tone`	`TextTone`	no		v1	Draws attention without inventing a severity scale, or `muted` to let a routine value recede.
`role`	`string`	no		v5	A name for this one field, rendered as `data-role`, so a host stylesheet can find "the verdict" without counting rows. The runtime gives it no meaning.
`mono`	`boolean`	no	`true`	v8	Set the value, and its note, in the monospace face, for an address, a hex string or a header the reader compares character by character. `false` for a sentence or a plain number with a unit, which read like terminal output in it. Rendered as `.tb-mono` on the `<dd>`, the class a table cell uses.

Example

JSON

{  "kind": "fields",  "fields": [    {"label": "count", "value": "20"},    {"label": "p50", "value": "28"},    {"label": "p99", "value": "1200"}  ]}

What tools/percentiles returns. Long arrays are cut to their first three items.

text

Attribute	Type	Required	Default	Since	Notes
`text`	`string`	yes		v1	Shown as a paragraph, or preformatted when `mono` is set.
`mono`	`boolean`	no	`false`	v1	Monospace and preformatted, keeping spaces and line breaks.

Example

JSON

{"kind": "text", "text": "Matched once, at 0-6."}

What tools/regex-explainer returns.

code

Attribute	Type	Required	Since	Notes
`lang`	`string`	yes	v1	Passed to the host's `highlight(source, lang)` hook and set as `data-lang`. A single token also becomes the `language-<lang>` class.
`source`	`string`	yes	v1	Shown as is, and what Copy copies even when a highlighter adds line numbers.

Example

JSON

{  "kind": "code",  "lang": "json",  "source": "{\n  \"matchCount\": 1,\n  \"matches\": [\n    {\n      \"text\": \"user 42\",\n      \"index\": 0,\n      \"groups\": [\n        \"user\",\n        \"42\"\n      ]\n    }\n  ]\n}"}

What tools/regex-explainer returns.

See it live: Code, painted by the host

table

Attribute	Type	Required	Since	Notes
`columns`	`Column[]`	yes	v1	The header row. Each row's cells line up with these in order.
`rows`	`Cell[][]`	yes	v1	One array of cells per row, in column order.
`caption`	`string`	no	v1	Shown above the table, except on a card.
`link`	`{ chart: string; keys: (number \| string \| null)[] }`	no	v4	Link these rows to a chart in the same result: `keys[i]` is the chart x that row i describes, `null` for a row with none. Pointing at the chart highlights the matching rows, and pointing at a row moves the chart's readout to it.

Column

Attribute	Type	Required	Default	Since	Notes
`label`	`string`	yes		v1	The header text, also set on each cell as `data-label` so host CSS can name a value on a narrow screen.
`align`	`"start" \| "end"`	no	`"start"`	v1	Alignment of the header and the column's cells. Without it, a cell given as a number aligns to the end and every other cell to the start.
`mono`	`boolean`	no		v1	Monospace, for anything the reader will compare digit by digit.
`wrap`	`"prose" \| "none"`	no		v8	How the column's text wraps, rendered as `data-wrap` on its header and every cell, so a narrow layout knows which columns are sentences: `prose` may wrap and wants a reading width, `none` is a short token (a hash, a date, a status word) kept on one line. A cell's own `wrap` overrides it. Absent makes no claim, and no attribute is written.
`rowHeader`	`boolean`	no	`false`	v8	The column names each row: its cells render as `<th scope="row">` instead of `<td>`, so a screen reader announces the row's name with every cell, and on a narrow tool the column stays in view while the rest scrolls. Opt-in, because a host selector such as `td:first-child` stops matching those cells.

Example

JSON

{  "kind": "table",  "caption": "The same data under both definitions. A comparison across systems using different ones means nothing.",  "columns": [    {"label": "", "mono": true},    {"label": "Nearest rank", "align": "end", "mono": true},    {"label": "Linear", "align": "end", "mono": true},    {"label": "Difference", "align": "end", "mono": true}  ],  "rows": [    [      {"text": "p50", "mono": true},      {"text": "28", "mono": true},      {"text": "29.5", "mono": true},      {"text": "+5.4%", "mono": true, "tone": "warn"}    ],    [      {"text": "p90", "mono": true},      {"text": "220", "mono": true},      {"text": "246.0", "mono": true},      {"text": "+11.8%", "mono": true, "tone": "warn"}    ],    [      {"text": "p95", "mono": true},      {"text": "480", "mono": true},      {"text": "516.0", "mono": true},      {"text": "+7.5%", "mono": true, "tone": "warn"}    ]  ]}

What tools/percentiles returns. Long arrays are cut to their first three items.

See it live: Copy a result

series

Attribute	Type	Required	Since	Notes
`chart`	`Chart`	yes	v1	The chart: its axes, its series and how it answers a pointer.

Chart

Attribute	Type	Required	Default	Since	Notes
`xLabel`	`string`	yes		v1	The x axis title, with `xUnit` in parentheses. Also heads the data table's x column.
`yLabel`	`string`	yes		v1	The left y axis title, with `yUnit` in parentheses.
`x`	`(number \| string)[]`	yes		v1	One position per value. Numbers for a quantity; text for named things, "Mesh", "SFU", "p99", which are drawn as evenly spaced categories in the order given. If any value is text, all are read as text.
`series`	`Series[]`	yes		v1	Every line, bar or area, drawn in order, each in the next of six series colours. A legend is shown when there is more than one.
`xUnit`	`string`	no		v1	Shown after `xLabel` in parentheses, on the axis and in the data table.
`yUnit`	`string`	no		v1	Shown after `yLabel` in parentheses.
`annotations`	`{ x: number \| string; label: string }[]`	no		v1	A vertical marker with a name: "the knee", "capacity", "p99".
`thresholds`	`{ y: number; label: string; axis?: "left" \| "right"; tone?: Tone }[]`	no		v4	A labelled horizontal rule at a y value: a budget, an SLO, a limit. Not a series, so it adds no legend entry, no data-table column and no readout row, and the y scale widens to show it. `tone` lets a limit read as one.
`yLabelRight`	`string`	no		v1	Second axis label, required if any series sets `axis: "right"`.
`readout`	`Readout`	no		v4	How the chart answers a pointer or keyboard focus. Default: a crosshair and every series at the nearest x.
`id`	`string`	no		v4	A name a `table` in the same result can link to with `link.chart`. Unique within a result.
`orientation`	`"vertical" \| "horizontal"`	no		v4	`horizontal` draws bars growing rightward, one row per x, for long category names and budgets read left to right. Bar series only: other shapes are not drawn on a horizontal chart, and the data table's caption says so.
`mirror`	`boolean`	no		v4	On a horizontal bar chart: series the tool gives as negative values are drawn to the left, and every label (ticks, readout, data table) shows the magnitude. For back-to-back comparisons and pyramids, where both sides are quantities and neither is negative.
`yScale`	`"linear" \| "log"`	no		v4	`log` draws an axis in powers of ten, for values spanning orders of magnitude: latency distributions, loss from 0.01% to 10%. A log axis cannot show zero or a negative, so those points are left out and the data table's caption says so; bars are not drawn on a log y axis, because a bar's length means nothing there.
`xScale`	`"linear" \| "log"`	no	`"linear"`	v4	`log` draws the x axis in powers of ten, as `yScale` does for y. Ignored when `x` is text.

Series

One line, bar or area on a chart.

Attribute	Type	Required	Default	Since	Notes
`label`	`string`	yes		v1	The series' name in the legend, the readout and the data table.
`points`	`(number \| null)[]`	yes		v1	One value per x. A `null` is a gap, not a zero, and the distinction matters on a chart.
`unit`	`string`	no		v1	Shown after each value in the readout, and after `label` in the legend and the data table. The first right-axis series' unit also goes beside `yLabelRight`.
`shape`	`"line" \| "area" \| "bar" \| "points" \| "step" \| "band" \| "box"`	no		v1	`points` draws a marker at each value and no line between them: for an x of separate items (frames, requests, runs) where nothing exists between two of them, so a joining line would invent a slope. `step` holds each value until the next x, then rises or falls straight to the next: for state sampled on events (a buffer's depth, a configured rate), where a sloped line invents a gradual change.
`boxes`	`({ low: number; q1: number; median: number; q3: number; high: number; outliers?: number[] } \| null)[]`	no		v4	The summary each `box` draws, one per x: whiskers from `low` to `high`, a box from `q1` to `q3`, a rule at `median`, and `outliers` as points. The tool computes it, so what the whiskers mean (1.5 IQR, min to max, p5 to p95) is the tool's and belongs in the chart's labels. Set `points` to the medians, which is what the readout, links and scale read where they read one value.
`lower`	`(number \| null)[]`	no		v4	The lower edge of a `band`, one per x, with `points` as the upper edge: a spread such as p5 to p95, or a min-to-max envelope, filled between the two under every other series. A `null` in either edge breaks the band.
`markers`	`boolean`	no		v4	Draw a marker at each value of a `line` or `area`, so every real point is visible and a series under an identical one can still be found. Each series gets its own marker shape.
`stack`	`string`	no		v4	Bar series sharing a `stack` id are stacked at each x, in series order, bottom to top, so a reader sees each part and the total. Positive and negative values stack away from zero separately. Bar series without one are grouped beside the stack as before.
`x`	`number[]`	no		v4	This series' own x values, one per point, instead of the chart's shared `x`: for measurements that do not share x positions, a scatter of (delay, cut-off) pairs say. The x scale covers every series. Usually with `shape: "points"`.
`sizes`	`(number \| null)[]`	no		v4	A third measure per point, drawn as the AREA of a bubble on a `points` series. By area, not radius, so a value twice as large looks twice as large. `sizeLabel` names it in the key and the readout: "Calls".
`sizeLabel`	`string`	no	`"Size"`	v4	The name of `sizes` in the key, the readout and the data table.
`axis`	`"left" \| "right"`	no	`"left"`	v1	`right` draws the series against a second y scale on the right, titled by the chart's `yLabelRight`.
`notes`	`(string \| null)[]`	no		v4	What the readout says for this series at each point, replacing the formatted value there: "250 ms, 60 ms late". `null` keeps the default for that point. Same length as `points`.

Readout

How a chart answers a pointer or keyboard focus. Omit it for the default: a crosshair at the nearest x and a card listing every series there.

Attribute	Type	Required	Since	Notes
`mode`	`"x" \| "point" \| "none"`	no	v1	`x`: every series at the nearest x (default). `point`: only the nearest point. `none`: no readout.
`crosshair`	`"x" \| "y" \| "both" \| "none"`	no	v1	Which crosshair lines to draw. Default `x`.
`titles`	`(string \| null)[]`	no	v1	A heading per x, replacing "<xLabel> <x>": "Frame 6 (lost)". `null` keeps the default. Same length as `x`.
`highlightTable`	`boolean`	no	v1	Highlight the matching row of this chart's own data table as the readout moves.

Example

JSON

{  "kind": "series",  "chart": {    "xLabel": "Bin midpoint",    "yLabel": "Count",    "yLabelRight": "Cumulative",    "x": [3, 5, 7],    "series": [      {"label": "Count", "points": [3, 7, 5], "shape": "bar"},      {        "label": "Cumulative",        "points": [15, 50, 75],        "unit": "%",        "shape": "line",        "axis": "right"      }    ]  }}

What tools/histogram returns. Long arrays are cut to their first three items.

See it live: every chart kind

heatmap

A value over two dimensions, one coloured cell each.

Attribute	Type	Required	Since	Notes
`heatmap`	`Heatmap`	yes	v4	The grid of values and its row and column labels.

Heatmap

A value over two dimensions: latency by hour and weekday, loss by bitrate and delay.

Attribute	Type	Required	Since	Notes
`xLabel`	`string`	yes	v4	The title under the columns.
`yLabel`	`string`	yes	v4	The title above the row labels.
`label`	`string`	yes	v4	What a cell's value is, for the key and the readout: "p95 latency".
`unit`	`string`	no	v4	Shown after each value in the readout, and after `label` in the key and the data table's caption.
`x`	`(number \| string)[]`	yes	v4	The column labels, left to right.
`y`	`(number \| string)[]`	yes	v4	The row labels, top to bottom.
`values`	`(number \| null)[][]`	yes	v4	`values[row][column]`. A `null` or missing cell has no value and is drawn hatched.
`scale`	`"sequential" \| "diverging"`	no	v4	`sequential` (default) is one hue, light to dark: how much. `diverging` is two hues either side of `midpoint`.
`midpoint`	`number`	no	v4	The neutral value of a diverging scale. Default 0.

Example

JSON

{  "kind": "heatmap",  "heatmap": {    "xLabel": "Hour",    "yLabel": "Day",    "label": "Packet loss",    "unit": "%",    "x": ["00:00", "02:00", "04:00"],    "y": ["Mon", "Tue", "Wed"],    "values": [[0.2, 0.2, 0.2], [0.2, 0.2, 0.2], [0.2, 0.2, 0.2]]  }}

What bench/fixtures/discrete-series returns for {"case":"heatmap"}. Long arrays are cut to their first three items.

See it live: every chart kind

pie

Parts of a whole, every slice labelled with its name and share.

Attribute	Type	Required	Since	Notes
`pie`	`Pie`	yes	v4	The whole and its slices.

Pie

Parts of a whole. Built so the known ways a pie misleads cannot happen: every slice is labelled with its share, slices are drawn in the order given from 12 o'clock clockwise, more than six fold into "Other", and a negative or zero total draws a message rather than a chart.

Attribute	Type	Required	Since	Notes
`label`	`string`	yes	v4	What the whole is: "Traffic by codec".
`unit`	`string`	no	v4	Shown after each value in the readout and in the data table's Value column.
`slices`	`{ label: string; value: number; tone?: Tone; explode?: boolean }[]`	yes	v4	`explode` pulls a slice out a little to point at it. A slice pulled out looks bigger than it is, so use it for the one part the surrounding text is about, not for decoration.
`donut`	`boolean`	no	v4	A ring rather than a disc, with `total` in its centre.
`total`	`string`	no	v4	The donut's centre text: "48 kb/s".

Example

JSON

{  "kind": "pie",  "pie": {    "label": "One voice stream, 48 kb/s",    "unit": "kb/s",    "slices": [      {"label": "Opus audio", "value": 32},      {"label": "RTP headers", "value": 4.8},      {"label": "UDP headers", "value": 3.2},      {"label": "IPv4 headers", "value": 8}    ]  }}

What bench/fixtures/discrete-series returns for {"case":"pie"}.

See it live: every chart kind

radar

A profile across several measures, one spoke each.

Attribute	Type	Required	Since	Notes
`radar`	`Radar`	yes	v4	The axes and the series drawn across them.

Radar

A profile across several measures: one spoke per axis, clockwise from 12 o'clock, each series a closed shape. All spokes share one scale from zero unless an axis gives its own max. At most four series are drawn, since more overlap past reading.

Attribute	Type	Required	Since	Notes
`label`	`string`	yes	v4	What the chart is: its accessible name and the data table's caption.
`unit`	`string`	no	v4	Shown after each value in the readout, and after each series' name in the legend and the data table.
`axes`	`{ label: string; max?: number }[]`	yes	v4	One spoke per axis, clockwise from 12 o'clock. An axis `max` gives that spoke its own scale; otherwise every spoke shares one, rounded up from the largest value to 1, 2 or 5 times a power of ten. Values are clamped between zero and the scale's top.
`series`	`{ label: string; values: (number \| null)[] }[]`	yes	v4	One value per axis; a `null` breaks the shape at that spoke rather than drawing it at the centre.

Example

JSON

{  "kind": "radar",  "radar": {    "label": "Network quality, out of 10",    "axes": [{"label": "Latency"}, {"label": "Jitter"}, {"label": "Loss"}],    "series": [      {"label": "Fibre", "values": [9, 9, 9]},      {"label": "Mobile", "values": [6, 5, 6]},      {"label": "Satellite", "values": [2, 6, 7]}    ]  }}

What bench/fixtures/discrete-series returns for {"case":"radar"}. Long arrays are cut to their first three items.

See it live: every chart kind

treemap

A hierarchy of sizes as nested rectangles.

Attribute	Type	Required	Since	Notes
`treemap`	`Treemap`	yes	v4	The hierarchy, from its root.

Treemap

A hierarchy of sizes: areas proportional to values, at most three levels drawn.

Attribute	Type	Required	Since	Notes
`label`	`string`	yes	v4	What the whole is: its accessible name and the data table's caption.
`unit`	`string`	no	v4	Shown after each value on a rectangle, in the readout and in the data table.
`root`	`TreemapNode`	yes	v4	The whole. Not drawn itself: its children are the top level, each in its own series colour.

TreemapNode

One node of a treemap: a leaf has a value, a branch has children.

Attribute	Type	Required	Since	Notes
`label`	`string`	yes	v4	Drawn on the rectangle where it fits, cut at 18 characters, and always in the readout and the data table.
`value`	`number`	no	v4	A leaf's size. A negative counts as zero, and a node of zero is not drawn. On a branch the children's sum is drawn instead, and the data table's caption says the two differed.
`children`	`TreemapNode[]`	no	v4	Drawn inside this node's rectangle, largest first. Past the third level they fold into their parent.
`tone`	`Tone`	no	v4	Replaces the colour this node's top-level group gives it. `normal` keeps the group's colour.

Example

JSON

{  "kind": "treemap",  "treemap": {    "label": "Monthly cost",    "unit": "k$",    "root": {      "label": "All",      "children": [        {          "label": "Media",          "children": [            {              "label": "Relays",              "children": [                {"label": "Europe", "value": 38},                {"label": "Americas", "value": 52},                {"label": "Asia Pacific", "value": 30}              ]            },            {"label": "TURN", "value": 22},            {"label": "Recording", "value": 14}          ]        },        {          "label": "Speech",          "children": [            {"label": "Recognition", "value": 64},            {"label": "Synthesis", "value": 41}          ]        },        {          "label": "Model",          "children": [            {"label": "Inference", "value": 120},            {"label": "Caching", "value": 9}          ]        },        {"label": "Signalling", "value": 11}      ]    }  }}

What bench/fixtures/discrete-series returns for {"case":"treemap"}.

See it live: every chart kind

venn

The overlap of two or three sets.

Attribute	Type	Required	Since	Notes
`venn`	`Venn`	yes	v4	The sets and their overlaps.

Venn

The overlap of two or three sets. Two sets are drawn with exact areas. Three cannot in general be, so every region is labelled with its count and the caption says the areas are approximate. More than three sets, or an overlap larger than a set, draws a message instead.

Attribute	Type	Required	Since	Notes
`label`	`string`	yes	v4	What the diagram is: its accessible name and the data table's caption.
`unit`	`string`	no	v4	Shown after each count in the readout and in the data table's Count column.
`sets`	`{ label: string; size: number }[]`	yes	v4	Two or three sets, each `size` above zero and counting every member, including those in an overlap. Any other number of sets draws a message instead.
`overlaps`	`{ sets: number[]; size: number }[]`	yes	v4	`sets` are indices into `sets`: [0, 1], or [0, 1, 2] for the middle of three.

Example

JSON

{  "kind": "venn",  "venn": {    "label": "Users by client",    "sets": [{"label": "Web", "size": 100}, {"label": "Mobile", "size": 100}],    "overlaps": [{"sets": [0, 1], "size": 50}]  }}

What bench/fixtures/discrete-series returns for {"case":"venn-two"}.

See it live: every chart kind

graph

Nodes and edges, laid out by the runtime, with every edge also in a table.

Attribute	Type	Required	Since	Notes
`graph`	`Graph`	yes	v7	The nodes, edges, groups and lanes, and how to lay them out.

Graph

Nodes and edges, laid out and drawn by the runtime: flowcharts, state machines, dependency graphs, org charts, networks, entity-relationship diagrams.

Attribute	Type	Required	Since	Notes
`label`	`string`	yes	v7	What the graph is: "Order lifecycle". The figure's accessible name.
`layout`	`"layered" \| "tree" \| "radial" \| "force" \| "manual"`	no	v7	Default `layered`: ranks along `direction`, for anything with a flow. `tree` and `radial` for a hierarchy, `force` for a network with no direction, `manual` to place every node at its `x` and `y`.
`direction`	`"LR" \| "RL" \| "TB" \| "BT"`	no	v7	Default `LR` for layered, `TB` for tree.
`routing`	`"orthogonal" \| "spline" \| "straight" \| "polyline"`	no	v7	Default `orthogonal` for layered and tree, `straight` for force and manual, `spline` for radial. An edge a straight line cannot draw without crossing a node is drawn as a polyline instead.
`directed`	`boolean`	no	v7	Default true.
`merge`	`"none" \| "source" \| "target"`	no	v7	Default `none`: no two edges ever share a stretch of line. `source` lets the edges leaving one node share a trunk, the bus of an org chart; `target` the edges arriving at one.
`seed`	`number`	no	v7	Force layout only. Default 1. The same seed gives the same picture everywhere.
`spacing`	`"compact" \| "normal" \| "loose"`	no	v7	Default `normal`.
`nodes`	`GraphNode[]`	yes	v7	Every node, ids unique. At least one, or the graph is listed instead of drawn.
`edges`	`GraphEdge[]`	yes	v7	Every edge, each end naming a node. All are also listed in a table under the picture.
`groups`	`GraphGroup[]`	no	v7	Boxes drawn around their members in any layout. A node joins one with `group`.
`lanes`	`GraphLane[]`	no	v7	Swimlanes, in order. Layered layouts only. A node joins one with `lane`.
`highlight`	`string[]`	no	v7	A path to emphasise, as node ids in order.
`limits`	`{ nodes?: number; edges?: number }`	no	v7	The tool's own limits. Past either, the runtime shows the edge table and says why instead of drawing. No default: without one, any size is drawn.
`interaction`	`{ /** Whether a reader can collapse and open groups. Default true. / collapse?: boolean; /* What pointing at or focusing a node emphasises. Default` neighbours`. / focus?: "neighbours" \| "none"; /* Whether picking two nodes highlights the shortest path between them. Default true. */ paths?: boolean; }`	no	v7	What a reader can do with the picture. Every part is on by default.

GraphNode

Attribute	Type	Required	Since	Notes
`id`	`string`	yes	v7	Unique within the graph. What edges, `highlight` and the edge table name.
`label`	`string`	no	v7	Default: the id.
`note`	`string`	no	v7	A second, muted line under the label.
`shape`	`GraphShape`	no	v7	Default `rounded`.
`tone`	`Tone`	no	v7	Status: the border and tint of the tone. Wins over `color`.
`color`	`GraphColor`	no	v7	Category: a series colour or a named token.
`badge`	`string`	no	v7	A few characters over the top-right corner: a count, a version.
`rows`	`GraphRow[]`	no	v7	The rows of a `record` node.
`group`	`string`	no	v7	The innermost group this node belongs to. Groups nest through `parent`.
`lane`	`string`	no	v7	Layered layouts only: the swimlane.
`rank`	`number`	no	v7	Layered layouts only: pin this node to a rank, 0 being the first.
`x`	`number`	no	v7	`manual` layout: the centre. `force` layout: pins the node here.
`y`	`number`	no	v7	`manual` layout: the centre's y, in the same units as `x`; a missing one counts as 0. `force` layout: pins the node only with `x` set too.
`role`	`string`	no	v7	Rendered as `data-role`, for host stylesheets. The runtime gives it no meaning.

GraphEdge

Attribute	Type	Required	Since	Notes
`from`	`string`	yes	v7	The id of the node the edge leaves. Must name a node, or the graph is listed instead of drawn.
`to`	`string`	yes	v7	The id of the node the edge arrives at. Must name a node; the same as `from` draws a loop.
`fromPort`	`string`	no	v7	A row id on the `from` node, a `record`: the edge attaches at that row. Must name one of its rows.
`toPort`	`string`	no	v7	A row id on the `to` node, a `record`: the edge attaches at that row. Must name one of its rows.
`fromSide`	`GraphSide`	no	v7	The side of the `from` node the edge must use. Default: the side facing the other end.
`toSide`	`GraphSide`	no	v7	The side of the `to` node the edge must use. Default: the side facing the other end.
`label`	`string`	no	v7	Drawn on the line at `labelAt`, and shown in the edge table and the keyboard readout.
`labelAt`	`"start" \| "middle" \| "end"`	no	v7	Where along the edge the label sits. Default `middle`.
`line`	`"solid" \| "dashed" \| "dotted"`	no	v7	Default `solid`.
`width`	`"thin" \| "normal" \| "thick"`	no	v7	Default `normal`.
`tone`	`Tone`	no	v7	Status: the line in the tone's colour. Wins over `color`, except `normal`.
`color`	`GraphColor`	no	v7	Category: a series colour or a named token for the line. An unknown value draws the default colour.
`head`	`GraphMarker`	no	v7	At `to`. Default `arrow` when the graph is directed, else `none`.
`tail`	`GraphMarker`	no	v7	At `from`. Default `none`.
`role`	`string`	no	v7	Rendered as `data-role`, for host stylesheets. The runtime gives it no meaning.

GraphGroup

Attribute	Type	Required	Since	Notes
`id`	`string`	yes	v7	Unique among groups and nodes, because a collapsed group is drawn as a node with this id. What a node's `group` names.
`label`	`string`	yes	v7	The title at the group's top-left corner, which collapses the group when pressed. Also the collapsed node's label.
`parent`	`string`	no	v7	The enclosing group. Groups nest to any depth; a cycle of parents is refused.
`collapsed`	`boolean`	no	v7	Drawn as one node standing for its members until a reader opens it. Default false.
`color`	`GraphColor`	no	v7	The box's colour, and the colour of the node standing for the group when collapsed. Default: the plain border.
`role`	`string`	no	v7	Rendered as `data-role` on the box and on the collapsed node, for host stylesheets. The runtime gives it no meaning.

GraphLane

A swimlane: a straight band across a layered layout. A group may not span two.

Attribute	Type	Required	Since	Notes
`id`	`string`	yes	v7	Unique among lanes. What a node's `lane` names.
`label`	`string`	yes	v7	The title at the start of the band.
`role`	`string`	no	v7	Rendered as `data-role` on the band, for host stylesheets. The runtime gives it no meaning.

GraphRow

One row of a record node: a column of a table, with a port of its own an edge can name.

Attribute	Type	Required	Since	Notes
`id`	`string`	yes	v7	Unique within the node; what `fromPort` and `toPort` name.
`label`	`string`	yes	v7	The row's text, after `tag` and before `detail`.
`detail`	`string`	no	v7	Right-aligned and muted: a column type, a value.
`tag`	`string`	no	v7	A short tag before the label, such as PK or FK.

Example

JSON

{  "kind": "graph",  "graph": {    "label": "Package dependencies",    "direction": "BT",    "nodes": [      {"id": "app", "badge": "4"},      {"id": "admin", "badge": "4"},      {"id": "api-client", "badge": "3"}    ],    "edges": [      {"from": "api-client", "to": "app"},      {"from": "ui-kit", "to": "app"},      {"from": "api-client", "to": "admin"}    ],    "highlight": ["core", "http", "api-client", "app"]  }}

What tools/build-order returns. Long arrays are cut to their first three items.

See it live: graph layouts and families

group

Attribute	Type	Required	Since	Notes
`parts`	`Output[]`	yes	v1	Rendered in order, each by its own kind, and may nest. A host's `cardParts` caps how many are shown.

Example

JSON

{  "kind": "group",  "parts": [    {      "kind": "fields",      "fields": [        {"label": "Bytes", "value": "19"},        {          "label": "Characters",          "value": "11",          "note": "code points, not UTF-16 units"        },        {"label": "Encoding", "value": "4 multi-byte"},        {          "label": "Overhead",          "value": "8 bytes",          "note": "what UTF-8 costs over one byte per character"        }      ]    },    {      "kind": "bytes",      "bytes": [72, 195, 169],      "caption": "Highlighted runs are one character each",      "highlight": [        {"at": 1, "len": 2, "label": "U+00E9 é"},        {"at": 8, "len": 3, "label": "U+4E16 世"},        {"at": 11, "len": 3, "label": "U+754C 界"},        {"at": 15, "len": 4, "label": "U+1F44B 👋"}      ]    }  ]}

What tools/utf8-bytes returns. Long arrays are cut to their first three items.

bytes

Raw bytes, as a reader of a wire format wants to see them: offsets down the side, hex in the middle, printable characters in a gutter, and named ranges over the top.

Attribute	Type	Required	Default	Since	Notes
`bytes`	`number[]`	yes		v2	One number per byte, 0 to 255, drawn sixteen to a row. A card shows the first four rows.
`offset`	`number`	no	`0`	v2	What the first byte is labelled in the offset column and the legend.
`highlight`	`ByteRange[]`	no		v2	Named ranges, each coloured over its bytes and listed in a legend. Where two overlap, the later one wins.
`caption`	`string`	no		v2	Shown above the grid, on a card too.

ByteRange

A run of bytes worth calling out inside a bytes output: a header field, a length prefix, the region an error points at.

Attribute	Type	Required	Since	Notes
`at`	`number`	yes	v2	Offset from the start of `bytes`, not from `offset`.
`len`	`number`	yes	v2	How many bytes, from `at`. Bytes past the end of `bytes` are not marked.
`label`	`string`	yes	v2	Named in the legend with its length and offset, and the hover title of each of its bytes.
`tone`	`Tone`	no	v2	Default: the next of six series colours, counted over ranges without a tone, so neighbouring ranges differ.

Example

JSON

{  "kind": "bytes",  "bytes": [72, 195, 169],  "caption": "Highlighted runs are one character each",  "highlight": [    {"at": 1, "len": 2, "label": "U+00E9 é"},    {"at": 8, "len": 3, "label": "U+4E16 世"},    {"at": 11, "len": 3, "label": "U+754C 界"},    {"at": 15, "len": 4, "label": "U+1F44B 👋"}  ]}

What tools/utf8-bytes returns. Long arrays are cut to their first three items.

See it live: Bytes

error

The INPUT was wrong, and the tool worked correctly by saying so. input names the control at fault so a generated form can mark it invalid and point a screen reader at the message. Without it, an error can only ever float unattached.

Attribute	Type	Required	Since	Notes
`message`	`string`	yes	v1	Shown in full, never truncated, and announced. Also read as the description of the input named by `input`.
`input`	`string`	no	v1	The id of the input at fault: that control is marked `aria-invalid` and points its description at the message.
`at`	`number`	no	v1	Where in that input's value the problem starts, shown after the message. The tools here give a character offset.
`len`	`number`	no	v1	How far the problem runs from `at`, shown as a range after the message.
`row`	`number`	no	v9	For a `rows` input, the index of the row at fault, 0 for the first: the message is shown under that row, named "Limits, row 2: ...", and its cells are marked invalid.

Example

JSON

{  "kind": "error",  "message": "\"three\" is not a number.",  "input": "values",  "at": 4,  "len": 5}

What tools/histogram returns for {"values":"1 2 three"}.

See it live: Failure modes