visuals
HTML pages (html_preview, html_render) and native inline charts, positioned diagrams and sortable tables in agent replies.
The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install convergence/visuals@0.2.0
Visuals — official plugin
convergence/visuals provides publish_visual for interactive, native visual
replies. It ships enabled on a fresh install; an existing install keeps the
choice it has, and users can turn it off or on in Settings → Plugins. It starts
only when a reply first contains one of its fences and loads Pele only on the
first Mermaid fence, so a chat without fences pays nothing. Its only requested
permission is tools.provide.
HTML pages (T3 Code's html_preview and html_render)
html.ts holds T3's contract (pingdotgg/t3code b24f0fbb): the tool names,
descriptions, limits (HTML 1–512000 UTF-16 units, title 1–200, preview width
240–1600 with 728 by default, frame height 80–2000), the result shapes and
messages, the frame-height rule, and the theme bootstrap with Divergence's
colours. Both tools are direct, so in code mode they stay tools of their
own and the preview's PNG reaches the agent as an MCP image part.
html_previewsends the themed page tohost/web.preview. With a confined renderer it answers T3's metadata as text and structured content plus the PNG. Without one it is an error,HtmlBackendUnavailable: <raw reason>, with no image: nothing renders unconfined and no screenshot is made up.html_rendersaves the agent's page unchanged as ahtmlv1 transcript artifact (the host stamps the owner) and answers T3'shtmlRenderreference and message. Measuredheightsare not supplied.- Inline (
html-view.ts) the page is live (ui.webDocument): borderless in the reply, as wide as the column and as tall as the page up to the agent's height, with one small glass Open in panel control. The panel is a detail-pane tab (theconvergence/tabsservice): the page live again, its Source, Copy and Save (kernel/copy_text,kernel/save_text, both after a click).
The renderer is the host's: Debian's Chromium in a disposable container of
the local Docker engine, admitted through chrome://sandbox
(crates/host/src/web). Differences from T3 and from a system web view:
pages are offline (remote URLs and local image paths never load;
missingImages lists the paths a page names), fonts and text metrics are
Linux's (DejaVu, Liberation, Noto Color Emoji), there is no GPU, and native
browser menus, pickers, IME composition, accessibility, clipboard and drag
from the page are not available. Without Docker or the built renderer image
the page says why and its source, copy and save still work.
Version 2 supports responsive multi-panel compositions: bar (grouped/stacked/
percent; horizontal/vertical), line, area, scatter/bubble, pie/donut, heatmap,
histogram, range/timeline, waterfall and boxplot, plus metrics, text, typed tables
and positioned diagrams. document.ts defines the strict, bounded JSON schema;
rules.md is the agent-facing reference. Version 1 documents still replay.
Rendering and interaction
Rust/GPUI draws every shape, label, control and floating tooltip. A pinned,
DOM-free D3 math subset computes scales, numeric/UTC ticks and paths inside
QuickJS; there is no browser, JavaScript UI execution, graph auto-layout, network,
file, process or plugin-storage access. math.LICENSES.txt includes provenance
and licenses; scripts/bundle-visuals-math.mjs reproduces the readable bundle.
Charts use the native canvas's onResize({width,height}) logical-pixel measurement,
not a scaled viewBox. Text remains readable as panels grow or wrap. Compact
legends keep original domains, colors and percentage denominators when hidden.
Null breaks paths and stays explicitly missing in shared bar inspection.
Hover opens a clamped floating tooltip; click pins/unpins. Arrow keys, Home/End traverse observations, Enter/Space pin, Escape clears inspection. In the expanded overlay Escape unpins first, then closes. Tables retain stable raw row identity, sort nulls last in either direction, paginate and expose full selected values. Diagram node details remain accessible through a native picker.
State and cached geometry belong to each artifact's ctx.state, with separate
panels and inline/expanded inspection. Hover does not recompute paths. Native
resize reports are change-only and coalesced off-paint. No JavaScript frame loop
or render-time notification runs.
Persistence and compatibility
The host owns immutable transcript artifacts. ctx.artifacts.publish persists
the complete document independently of the surrounding tool result, including
discarded acknowledgements and later code-mode errors. The plugin registers
removable visual renderers for versions 1 and 2; Source retains original input
and Data retains all raw values, including hidden series and nulls.
This plugin requires the updated native host and canvas resize API. Older hosts without artifact support fail with an explicit update message. Invalid persisted documents keep their readable summary and expose a validation error.
Verification
node --import ./plugins/testing/register.mjs --test plugins/visuals/*.test.ts
pnpm -C plugins typecheck
pnpm -C plugins exec prettier --check 'visuals/**/*.{ts,json,md}'
Geometry tests use asymmetric data and independent numeric expectations; view tests exercise real native element factories and handlers. Native desktop checks and app-owned Metal captures supplement these tests; they do not use a browser.
Permissions in 0.2.0
Files
// Actual native factories and handlers: geometry sizing, hover, pinning, replay,
// composition and per-panel isolation. No browser or screenshot approximation.
import assert from "node:assert/strict";
import { test } from "node:test";
import { nodes } from "../sdk/ui-testing.ts";
import { richVisualDocumentSchema } from "./document.ts";
import { renderArtifact } from "./views.ts";
import { artifact, chartDocument, context, diagramDocument, fire, node, tableDocument, textOf } from "./testing.ts";
const reply = richVisualDocumentSchema.parse({
version: 2,
title: "Service health",
summary: "Traffic recovered; one observation is missing.",
columns: 2,
panels: [
{
id: "traffic",
title: "Requests",
body: {
kind: "chart",
chart: "bar",
x: { type: "category", values: ["Mon", "Tue", "Wed"] },
series: [
{ name: "Read", values: [3, null, 9] },
{ name: "Write", values: [1, null, 6] },
],
},
},
{
id: "cost",
body: {
kind: "metric",
label: "Spend",
value: 1250,
format: { style: "currency", currency: "USD" },
comparison: { label: "vs last week", value: -0.08, format: { style: "percent" } },
},
},
{ id: "notes", span: 2, body: { kind: "text", text: "Tuesday is missing, not zero." } },
],
});
const measure = (tree: unknown, id: string, width = 380, height = 250) => fire(tree, id, "onResize", { width, height });
test("inline native charts measure actual pixels once, have no viewBox and keep fixed text size on resize", () => {
const { ctx, updates } = context();
const render = () => renderArtifact(artifact(chartDocument), ctx);
let tree = render();
assert.equal(node(tree, "inline-chart").viewBox, undefined);
assert.equal(updates(), 0, "no render-time notifications");
measure(tree, "inline-chart");
tree = render();
const before = node(tree, "inline-chart").commands;
assert.ok(Array.isArray(before) && before.length > 0);
measure(tree, "inline-chart");
assert.equal(updates(), 1, "identical size is a no-op");
measure(tree, "inline-chart", 740);
tree = render();
const after = node(tree, "inline-chart").commands;
assert.ok(Array.isArray(after));
assert.notDeepEqual(before, after);
assert.deepEqual(
after.filter((c) => c.op === "text").map((c) => c.size),
before.filter((c) => c.op === "text").map((c) => c.size),
);
assert.equal(
nodes(tree).some((n) => n.type === "checkbox" || n.type === "overlay" || n.shadow),
false,
);
});
test("shared floating hover includes missing values, is clamped and does not redraw for the same category", () => {
const { ctx, updates } = context();
const render = () => renderArtifact(artifact(reply), ctx);
measure(render(), "inline-traffic-chart");
fire(render(), "inline-traffic-chart-plot", "onPointerMove", { x: 120, y: 25 });
let tree = render();
const tooltip = node(tree, "inline-traffic-chart-tooltip");
assert.equal(tooltip.position, "absolute");
assert.match(textOf(tooltip), /Read\n3\nWrite\n1/);
assert.ok(Number(tooltip.left) >= 8 && Number(tooltip.left) + Number(tooltip.width) <= 372);
const count = updates();
fire(tree, "inline-traffic-chart-plot", "onPointerMove", { x: 135, y: 90 });
assert.equal(updates(), count);
fire(render(), "inline-traffic-chart-plot", "onPointerMove", { x: 220, y: 20 });
tree = render();
assert.equal(nodes(node(tree, "inline-traffic-chart-tooltip")).filter((n) => n.text === "Missing").length, 2);
fire(tree, "inline-traffic-chart-plot", "onPointerLeave");
assert.equal(
nodes(render()).some((n) => n.id === "inline-traffic-chart-tooltip"),
false,
);
});
test("pinning survives leave and resize; keyboard traversal and Escape unpin before closing expanded view", () => {
const { ctx } = context();
const render = () => renderArtifact(artifact(reply), ctx);
measure(render(), "inline-traffic-chart");
fire(render(), "inline-traffic-chart-plot", "onClick", { x: 120, y: 40 });
fire(render(), "inline-traffic-chart-plot", "onPointerLeave");
measure(render(), "inline-traffic-chart", 600);
assert.match(textOf(node(render(), "inline-traffic-chart-tooltip")), /Mon/);
fire(render(), "inline-traffic-chart-plot", "onKeyDown", { key: "end" });
assert.match(textOf(node(render(), "inline-traffic-chart-tooltip")), /Wed/);
fire(render(), "inline-traffic-chart-plot", "onKeyDown", { key: "escape" });
assert.equal(
nodes(render()).some((n) => n.id === "inline-traffic-chart-tooltip"),
false,
);
fire(render(), "expand-visual");
measure(render(), "expanded-traffic-chart", 800, 340);
fire(render(), "expanded-traffic-chart-plot", "onKeyDown", { key: "home" });
fire(render(), "expanded-traffic-chart-plot", "onKeyDown", { key: "enter" });
const escape = () => {
const keys = node(render(), "visual-overlay").keys as { escape: () => void };
keys.escape();
};
escape();
assert.ok(node(render(), "visual-overlay"));
assert.equal(
nodes(render()).some((n) => n.id === "expanded-traffic-chart-tooltip"),
false,
);
escape();
assert.equal(
nodes(render()).some((n) => n.type === "overlay"),
false,
);
});
test("legends retain original scales, restore all, and isolate artifacts/panels/inline inspection", () => {
const first = context(),
second = context();
const render = () => renderArtifact(artifact(reply), first.ctx);
measure(render(), "inline-traffic-chart");
fire(render(), "inline-traffic-chart-series-0");
assert.equal(node(render(), "inline-traffic-chart-series-0").tooltip, "Show Read");
fire(render(), "inline-traffic-chart-series-1");
assert.match(textOf(render()), /All series hidden/);
fire(render(), "inline-traffic-chart-restore");
assert.equal(node(render(), "inline-traffic-chart-series-0").tooltip, "Hide Read");
fire(render(), "inline-traffic-chart-plot", "onKeyDown", { key: "right" });
fire(render(), "expand-visual");
measure(render(), "expanded-traffic-chart", 380, 340);
assert.equal(nodes(render()).filter((n) => typeof n.id === "string" && n.id.endsWith("-tooltip")).length, 1);
const other = renderArtifact(artifact(reply), second.ctx);
measure(other, "inline-traffic-chart");
assert.equal(node(renderArtifact(artifact(reply), second.ctx), "inline-traffic-chart-series-0").tooltip, "Hide Read");
});
test("compositions use native wrapping, metrics and panel-specific raw Data; Source keeps unmodified input", () => {
const raw = { ...reply, panels: reply.panels.map(({ span, ...panel }) => panel) };
const { ctx } = context();
const value = { ...artifact(reply), data: raw };
const render = () => renderArtifact(value, ctx);
assert.equal(node(render(), "inline-panel-traffic").flexBasis, 300);
assert.match(textOf(render()), /USD 1250.00/);
assert.match(textOf(render()), /-8%/);
fire(render(), "expand-visual");
fire(render(), "visual-tab-data");
assert.equal(node(render(), "data-table-sort-series_0").label, "Read");
fire(render(), "data-panel", "onChange", { value: "cost" });
assert.match(textOf(render()), /1250/);
assert.match(textOf(render()), /-0.08/);
fire(render(), "visual-tab-source");
const source = nodes(render()).find((n) => n.type === "code");
assert.ok(source && typeof source.text === "string");
assert.deepEqual(JSON.parse(source.text), raw, "defaults/normalization must not rewrite Source");
});
test("v1 diagrams and tables replay with pointer/keyboard selection and separate Data sorts", () => {
const { ctx } = context();
const diagram = () => renderArtifact(artifact(diagramDocument), ctx);
fire(diagram(), "inline-diagram", "onClick", { x: 15, y: 25 });
assert.match(textOf(diagram()), /The user-facing client/);
assert.match(textOf(diagram()), /client → service: Request/);
fire(diagram(), "inline-node", "onChange", { value: "service" });
assert.match(textOf(diagram()), /No additional details/);
const other = context();
const table = () => renderArtifact(artifact(tableDocument), other.ctx);
fire(table(), "inline-table-sort-score");
assert.deepEqual(
nodes(table())
.filter((n) => typeof n.id === "string" && n.id.startsWith("inline-table-row-"))
.map((n) => n.id),
["inline-table-row-1", "inline-table-row-3", "inline-table-row-0", "inline-table-row-2"],
);
fire(table(), "inline-table-row-1", "onKeyDown", { key: "enter" });
assert.match(textOf(table()), /Score: 2/);
fire(table(), "expand-visual");
fire(table(), "visual-tab-data");
assert.equal(node(table(), "data-table-sort-score").label, "Score");
fire(table(), "data-table-sort-name");
assert.equal(node(table(), "inline-table-sort-score").label, "Score ↑");
});
test("unsupported/mismatched versions and invalid persisted data show readable errors", () => {
for (const value of [
{ ...artifact(chartDocument), version: 2 },
{ ...artifact(reply), owner: "other" },
{ ...artifact(reply), data: { ...reply, html: "<b>bad</b>" } },
]) {
const tree = renderArtifact(value, context().ctx);
assert.match(textOf(tree), /cannot be rendered/);
assert.equal(
nodes(tree).some((n) => n.type === "canvas"),
false,
);
}
});
test("the inline report is calm: lede summary, unboxed panels, metrics as figures, legend leading the plot", () => {
const { ctx } = context();
const tree = renderArtifact(artifact(reply), ctx);
const all = nodes(tree);
// The summary is the readable lede, not a muted caption.
const lede = all.find((n) => n.text === reply.summary);
assert.ok(lede && lede.tone === undefined, JSON.stringify(lede));
// No panel is a box: no fill, padding or border of its own.
for (const id of ["inline-panel-traffic", "inline-panel-cost", "inline-panel-notes"]) {
const panel = node(tree, id);
assert.equal(panel.background, undefined, id);
assert.equal(panel.border, undefined, id);
assert.ok(panel.padding === undefined || panel.padding === 0, id);
}
// A metric lines up with others as a figure, value before its label.
assert.equal(node(tree, "inline-panel-cost").flexBasis, 150);
const texts = nodes(node(tree, "inline-panel-cost"))
.filter((n) => typeof n.text === "string")
.map((n) => n.text);
assert.deepEqual(texts.slice(0, 2), ["USD 1250.00", "Spend"]);
// The panel title is a quiet label; the legend sits before the plot, at its right.
measure(tree, "inline-traffic-chart");
const traffic = nodes(node(renderArtifact(artifact(reply), ctx), "inline-panel-traffic"));
assert.ok(traffic.some((n) => n.text === "Requests" && n.tone === "muted"));
const legendAt = traffic.findIndex((n) => n.id === "inline-traffic-chart-series-0");
const plotAt = traffic.findIndex((n) => n.id === "inline-traffic-chart-plot");
assert.ok(legendAt >= 0 && plotAt >= 0 && legendAt < plotAt, `${legendAt} ${plotAt}`);
// The interaction hint is for the expanded view only.
assert.ok(!textOf(tree).includes("Hover to inspect"));
fire(tree, "expand-visual");
assert.ok(textOf(renderArtifact(artifact(reply), ctx)).includes("Hover to inspect"));
});
test("titles and figures are medium weight in the app's own face, as the app's headings are", () => {
const { ctx } = context();
const inline = nodes(renderArtifact(artifact(reply), ctx));
const title = inline.find((n) => n.text === reply.title);
assert.deepEqual([title?.weight, title?.size], [500, 15]);
assert.equal(inline.find((n) => n.text === "USD 1250.00")?.weight, 500);
// No text of the report picks its own family or a weight above medium.
for (const n of inline.filter((n) => typeof n.text === "string")) {
assert.equal(n.fontFamily, undefined, String(n.text));
assert.ok(n.weight === undefined || Number(n.weight) <= 500, `${String(n.text)} ${String(n.weight)}`);
}
fire(renderArtifact(artifact(reply), ctx), "expand-visual");
const expanded = nodes(renderArtifact(artifact(reply), ctx)).filter((n) => n.text === reply.title);
assert.ok(expanded.length > 0 && expanded.every((n) => n.weight === 500), JSON.stringify(expanded));
});
test("metrics pack as figures unless spanned, and keep only titles that add to their label", () => {
const document = richVisualDocumentSchema.parse({
version: 2,
title: "Quarter",
summary: "Illustrative figures.",
columns: 2,
panels: [
{ id: "plain", title: "Revenue", body: { kind: "metric", label: "Revenue", value: 12 } },
{ id: "distinct", title: "Europe only", body: { kind: "metric", label: "Revenue", value: 4 } },
{ id: "wide", span: 2, body: { kind: "metric", label: "Customers", value: 300 } },
{ id: "chart", span: 1, body: { kind: "text", text: "Half width." } },
],
});
const { ctx } = context();
const tree = renderArtifact(artifact(document), ctx);
assert.equal(node(tree, "inline-panel-plain").flexBasis, 150);
assert.equal(node(tree, "inline-panel-distinct").flexBasis, 150);
assert.equal(node(tree, "inline-panel-wide").flexBasis, "100%", "an explicit span 2 takes the whole row");
assert.equal(node(tree, "inline-panel-chart").flexBasis, 300);
const texts = (id: string) => nodes(node(tree, id)).filter((n) => typeof n.text === "string").map((n) => n.text);
assert.deepEqual(
texts("inline-panel-plain").filter((t) => t === "Revenue"),
["Revenue"],
"a title that repeats the label is left out",
);
assert.equal(texts("inline-panel-distinct")[0], "Europe only", "a distinct title is kept, as a quiet label");
assert.equal(nodes(node(tree, "inline-panel-distinct")).find((n) => n.text === "Europe only")?.tone, "muted");
});
No comments yet.