Official

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.2

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_preview sends the themed page to host/web.preview. With a web view 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, and no screenshot is made up.
  • html_render saves the agent's page unchanged as a html v1 transcript artifact (the host stamps the owner) and answers T3's htmlRender reference and message. Measured heights are 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 (the convergence/tabs service): the page live again, its Source, Copy and Save (kernel/copy_text, kernel/save_text, both after a click).

The renderer is the system's WKWebView on macOS (crates/host/src/web), so a page behaves as it would in Safari, with the Mac's fonts, the GPU, text input, the clipboard and native pickers. The difference from T3 is that pages are offline: remote URLs and local image paths never load (missingImages lists the paths a page names). On Linux and Windows, which have no web view in this version, the page says so 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.2

  • Provide agent tools tools.provideMediumGives tools to agents.Let agents preview and publish HTML pages and bounded visual replies into the current chat

Files

html.test.ts11.8 KB
// The HTML contract helpers and the saved-page view, through the real native element factories.
import assert from "node:assert/strict";
import { test } from "node:test";
import type { Api, PluginArtifact } from "convergence";
import { readFileSync } from "node:fs";
import {
  FONT_FACES,
  HTML_PREVIEW_DESCRIPTION,
  HTML_RENDER_DESCRIPTION,
  HTML_RENDER_DESIGN_GUIDE,
  HTML_RENDER_INSTRUCTION,
  HTML_RENDER_THEME_GUIDE,
  htmlRenderFileName,
  htmlRenderFrameHeight,
  injectThemeBootstrap,
  missingImages,
  themeVariables,
} from "./html.ts";
import { FRAME_GROUP, htmlRenderer, newPanelState, renderPanel } from "./html-view.ts";
import type { PanelPage } from "./html-view.ts";
import { context, fire, node, textOf } from "./testing.ts";
import { nodes } from "../sdk/ui-testing.ts";

test("the theme goes first in the head and never into comments, scripts or templates", () => {
  const page =
    "<!-- <head> --><html><head><title>x</title></head><body><template><head></head></template></body></html>";
  const themed = injectThemeBootstrap(page, "dark");
  const head = themed.indexOf("<html><head>") + "<html><head>".length;
  assert.ok(
    themed
      .slice(head)
      .startsWith(
        '<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style id="divergence-theme">',
      ),
  );
  assert.ok(themed.startsWith("<!-- <head> --><html><head><meta charset"), themed.slice(0, 80));
  assert.equal(themed.split('id="divergence-theme"').length, 2);
  assert.equal(injectThemeBootstrap("<p>bare</p>", "light").slice(0, 21), "<!doctype html><head>");
  assert.ok(
    !injectThemeBootstrap('<meta charset="utf-8"><p>x</p>', "light").includes('<meta charset="utf-8"><meta charset'),
  );
  const variables = themeVariables("dark");
  assert.equal(variables["--background"], "#0a1224");
  assert.equal(Object.keys(variables).filter((name) => name.startsWith("--chart-")).length, 6);
});

test("frame height, file names and missing images follow T3", () => {
  const page = { html: "x", title: "T", height: 300 };
  assert.equal(htmlRenderFrameHeight(page, 728), 300);
  assert.equal(htmlRenderFrameHeight(page, 728, 120), 120);
  const measured = {
    ...page,
    height: 2000,
    heights: [
      [320, 900],
      [728, 500],
      [1000, 400],
    ] as [number, number][],
  };
  assert.equal(htmlRenderFrameHeight(measured, 728), 500);
  assert.equal(htmlRenderFrameHeight(measured, 600), 900, "the taller neighbour wins between measured widths");
  assert.equal(htmlRenderFrameHeight({ ...measured, height: 200 }, 728), 200, "a smaller agent height caps the frame");
  assert.equal(htmlRenderFileName(' a/b:c*?"<>| '), "a b c.html");
  assert.equal(htmlRenderFileName("///"), "Page.html");
  assert.deepEqual(
    missingImages(
      `<img src="/a/b.png"><div style="background:url(/c/d.webp)"></div><img src="https://x/y.png"><img src="/a/b.png">`,
    ),
    ["/a/b.png", "/c/d.webp"],
  );
  assert.match(
    HTML_RENDER_INSTRUCTION,
    /^When a chart, table, diagram, image collage, or mockup would say more than prose/,
  );
});

const artifact = (data: unknown, item?: string): PluginArtifact & { item?: string } => ({
  owner: "visuals",
  type: "html",
  version: 1,
  title: "Counter",
  summary: "HTML page: Counter",
  data,
  ...(item ? { item } : {}),
});
const settled = () => new Promise<void>((resolve) => setImmediate(resolve));

function panelApi() {
  const kernel: { method: string; params: unknown }[] = [];
  const api = {
    host: {
      kernel: async (method: string, params: unknown) => {
        kernel.push({ method, params });
        return method === "save_text" ? { saved: true } : {};
      },
    },
  } as unknown as Api;
  return { api, kernel };
}

test("inline the page is live and borderless, with Open in panel only where the item is known", () => {
  const opened: PanelPage[] = [];
  const render = htmlRenderer((page) => opened.push(page));
  const doc = { html: "<p>x</p>", title: "Counter", height: 240 };
  const tree = render(artifact(doc, "artifact-1"), context().ctx);
  // A native button named "Open in panel", hidden at rest; the frame's hover group or keyboard
  // focus inside its wrapper shows it.
  const frame = nodes(tree).find((n) => n.group === FRAME_GROUP);
  assert.ok(frame, "the frame is the hover group");
  const button = node(tree, "html-open-panel");
  assert.equal(button.type, "button");
  assert.equal(button.tooltip, "Open in panel");
  assert.equal(button.icon, "maximize-2");
  const chrome = node(tree, "html-open-panel-chrome");
  assert.equal(chrome.opacity, 0);
  assert.deepEqual(chrome.groupHover, { group: FRAME_GROUP, opacity: 1 });
  assert.deepEqual(chrome.focusWithin, { opacity: 1 });
  assert.ok(nodes(chrome).includes(button), "the button is inside the revealed wrapper");
  fire(tree, "html-open-panel");
  assert.deepEqual(opened, [{ item: "artifact-1", document: doc }]);
  assert.ok(nodes(tree).some((n) => n.type === "web_document" && n.height === 240));
  const older = render(artifact(doc), context().ctx);
  assert.ok(!nodes(older).some((n) => n.id === "html-open-panel"), "an older app names no item");
});

test("the panel copies, saves and shows the source of the open page", async () => {
  const page = "<!doctype html><button onclick='n++'>+</button>";
  const { api, kernel } = panelApi();
  const state = newPanelState();
  const { ctx } = context();
  assert.match(textOf(renderPanel(api, state, ctx)), /No HTML page is open/);
  state.page = { item: "artifact-1", document: { html: page, title: "Counter", height: 240 } };
  let tree = renderPanel(api, state, ctx);
  fire(tree, "html-panel-copy");
  fire(tree, "html-panel-save");
  await settled();
  assert.deepEqual(kernel, [
    { method: "copy_text", params: { text: page } },
    { method: "save_text", params: { text: page, name: "Counter.html" } },
  ]);
  fire(tree, "html-panel-source");
  tree = renderPanel(api, state, ctx);
  const code = nodes(tree).find((n) => n.type === "code");
  assert.ok(code && JSON.stringify(code).includes("n++"));
});

test("a page that fails validation keeps its title and summary readable", () => {
  const tree = htmlRenderer(() => {})(artifact({ html: "", title: "Counter", height: 10 }), context().ctx);
  assert.match(textOf(tree), /Counter[\s\S]*HTML page: Counter[\s\S]*cannot be shown/);
});

test("both HTML tools and the rules carry the calm-report design direction", () => {
  for (const description of [HTML_PREVIEW_DESCRIPTION, HTML_RENDER_DESCRIPTION])
    assert.match(description, /design/i);
  assert.ok(HTML_RENDER_DESCRIPTION.includes(HTML_RENDER_DESIGN_GUIDE));
  assert.match(HTML_RENDER_DESIGN_GUIDE, /calm inline report/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /only when selecting or filtering does real work/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /illustrative/);
  const rules = readFileSync(new URL("./rules.md", import.meta.url), "utf8");
  assert.ok(rules.startsWith("# HTML pages\n\nWhen a chart, table, diagram, image collage, or mockup would say more than prose"));
  assert.match(rules, /By default, make pages look like part of the reply rather than a dashboard/);
});

test("the calm report is a default that yields to a design the user asks for", () => {
  assert.match(HTML_RENDER_DESIGN_GUIDE, /when the user gives no visual direction, default to a calm inline report/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /By default keep surfaces flat/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /these defaults never override a requested design/);
  assert.doesNotMatch(HTML_RENDER_DESIGN_GUIDE, /(^|\. )Keep surfaces flat/, "no unconditional ban on cards or gradients");
  const rules = readFileSync(new URL("./rules.md", import.meta.url), "utf8");
  assert.match(rules, /When the user asks for a specific look \(a dashboard, a card layout, a mockup/);
  assert.doesNotMatch(rules, /\bNo stacked or nested cards/);
});

test("the theme guide pairs each surface tint with a readable text colour", () => {
  // A model put --warning-foreground (dark text for solid --warning) on --warning-surface: unreadable in dark.
  assert.match(HTML_RENDER_THEME_GUIDE, /--warning-foreground on --warning\)/);
  assert.match(HTML_RENDER_THEME_GUIDE, /text on --destructive-surface or --warning-surface uses --foreground/);
  assert.ok(HTML_RENDER_DESCRIPTION.includes(HTML_RENDER_THEME_GUIDE));
});

test("the design guide carries the narrow-width, filter-scope and empty-state checks", () => {
  // A real report kept naming a filtered-out service, crowded its caption at 360px and asked the reader to select from nothing.
  assert.match(HTML_RENDER_DESIGN_GUIDE, /put a section's caption or unit on its own line directly under its heading \(left-aligned, not pushed to the right edge\)/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /every tick sits on its gridline/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /keep --accent-surface for the selected row or a small badge, never a large panel/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /pass the contentHeight html_preview reported/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /temporary script that drives its own controls/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /recompute the takeaway and key figures for what is visible or label them as overall/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /never let a sentence name an item the filter hides: a takeaway that stays fixed must say it is overall/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /The outermost element still has no horizontal padding at any width/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /offer a button that clears the filter/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /any caption or hint that offers an action included, then tells the reader to change or clear the filter/);
  // A retained page split "184 / ms" in its inspector and kept "Select a row" above an empty table.
  assert.match(HTML_RENDER_DESIGN_GUIDE, /keep each number with its unit on one line \(white-space: nowrap\)/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /the usual hint returns when items do/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /preview at the default width and again with width 360/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /these defaults never override a requested design/);
  const rules = readFileSync(new URL("./rules.md", import.meta.url), "utf8");
  assert.match(rules, /make the takeaway and figures follow it or label them as overall/);
  assert.match(rules, /Preview at the default width and at width 360/);
});

test("pages get the app's own faces offline and quiet medium headings by default", () => {
  // Pages were set in the renderer's DejaVu with 650-weight, tightly tracked headings beside an Inter app.
  assert.equal(FONT_FACES.match(/@font-face/g)?.length, 12);
  assert.ok(
    FONT_FACES.startsWith(
      '@font-face{font-family:"Inter";font-style:normal;font-weight:400;src:url(http://page.localhost/fonts/Inter-Regular.otf)}',
    ),
  );
  assert.match(FONT_FACES, /font-family:"Inter";font-style:normal;font-weight:500;src:url\(http:\/\/page\.localhost\/fonts\/Inter-Medium\.otf\)/);
  const themed = injectThemeBootstrap("<html><head></head><body><style>h1{font-family:Georgia}</style></body></html>", "dark");
  assert.ok(themed.includes(FONT_FACES) && themed.indexOf(FONT_FACES) < themed.indexOf("h1{font-family:Georgia}"), "an explicit family still wins");
  assert.equal(themeVariables("light")["--font-sans"]?.startsWith('"Inter"'), true);
  assert.match(HTML_RENDER_THEME_GUIDE, /--font-sans is the app's own interface face \(Inter\)/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /natural letter spacing \(no negative tracking, no spaced or uppercase labels\)/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /both medium weight \(500\)/);
  assert.doesNotMatch(HTML_RENDER_DESIGN_GUIDE, /semibold/);
  assert.match(HTML_RENDER_DESIGN_GUIDE, /these defaults never override a requested design/);
  const rules = readFileSync(new URL("./rules.md", import.meta.url), "utf8");
  assert.match(rules, /served offline as `--font-sans` \(Inter\)/);
  assert.match(rules, /medium-weight \(500\) headings/);
});

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.2latestNov 21, 2026>=2 <4349.5 KB1 permissionListed
0.2.1Oct 25, 2026>=2 <4349.2 KB1 permissionListed
0.2.0Oct 23, 2026>=2 <4349.3 KB1 permissionListed

Reviews and comments

0 threads · 0 reviews

No comments yet.