@artooi/ag-ui-web-component 0.25.2 → 0.26.0

package/src/core/ag_ui_chat.ts

@@ -1,6 +1,7 @@
 import type { Context, Interrupt, Message, Tool } from "@ag-ui/core";
 import {
   ATTACHMENT_EVENT,
+  CHART_ACTIVITY_TYPE,
   COMPACTION_ACTIVITY_TYPE,
   DEFAULT_ATTACHMENT_MAX_BYTES,
   ICON_ATTACH,
@@ -39,6 +40,9 @@ import {
 import { attachCopyButtons } from "../ui/attach_copy_buttons.js";
 import { renderAttachmentChips } from "../ui/attachment_chips.js";
 import { AttachmentTray } from "../ui/attachment_tray.js";
+import { renderChart } from "../ui/chart_block.js";
+import { chartSpecFrom } from "../ui/chart_spec_from.js";
+import { createChartTool } from "../ui/chart_tool.js";
 import { CheckpointMenu, type CheckpointVerb } from "../ui/checkpoint_menu.js";
 import { type ConfirmationRequest, requestConfirmation } from "../ui/confirmation_card.js";
 import { prettifyToolName } from "../ui/prettify_tool_name.js";
@@ -392,6 +396,15 @@ export class AgUiChat extends HTMLElement {
    * (`TOOL_CALL_RESULT`), so the post-run executeTool sweep doesn't overwrite
    * the real output with the generic "executed on the server" fallback.
    */
+  /** Whether a server-pushed chart activity is drawn. Off unless asked for. */
+  #chartActivity = false;
+
+  /** Card elements by call id, so a rendering handler can find its own card. */
+  readonly #cardElements = new Map<string, HTMLElement>();
+
+  /** Chart blocks by activity message id, so an update redraws in place. */
+  readonly #activityBlocks = new Map<string, HTMLElement>();
+
   readonly #serverSettled = new Set<string>();
   /**
    * Tool calls made during the current interaction, in the order they started,
@@ -1662,6 +1675,8 @@ export class AgUiChat extends HTMLElement {
     this.#hidePending();
     this.#toolCards.clear();
     this.#serverSettled.clear();
+    this.#cardElements.clear();
+    this.#activityBlocks.clear();
     this.#initialMessages = [];
     this.#attachTray?.clear();
     // Keep the empty-state region; everything else clears.
@@ -1822,7 +1837,23 @@ export class AgUiChat extends HTMLElement {
         if (this.#noticeIfSkillLoad(restored)) {
           continue;
         }
-        this.#cardFor(restored);
+        this.#cardElements.set(restored.id, this.#cardFor(restored).element);
+        // Only `render` is replayed, never `handler`. A restored transcript
+        // redraws what the call drew; it must not re-run what the call *did*.
+        const tool = this.#resolveTool(restored.name);
+        if (tool !== null) {
+          this.#renderToolOutput(tool, restored);
+        }
+      }
+      return;
+    }
+    if (message.role === "activity") {
+      // The client materialises a pushed activity as a message of its own, so a
+      // chart's data is in the transcript already and survives a reload. Only
+      // the drawing had to be put back.
+      const activity = message as unknown as { activityType?: unknown; content?: unknown };
+      if (activity.activityType === CHART_ACTIVITY_TYPE && this.#chartActivity) {
+        this.#drawActivityChart(message.id, activity.content);
       }
       return;
     }
@@ -2539,6 +2570,10 @@ export class AgUiChat extends HTMLElement {
     }
     const card = this.#cardFor(call);
     this.#toolCards.delete(call.id);
+    // Kept after the card leaves `#toolCards`: a tool that renders into the
+    // transcript places itself against its own card, and by the time it runs the
+    // card is no longer reachable by id.
+    this.#cardElements.set(call.id, card.element);
     const tool = this.#resolveTool(call.name);
     if (tool === null) {
       // Not a client tool. A server-side tool's real output arrives via
@@ -2613,7 +2648,12 @@ export class AgUiChat extends HTMLElement {
       this.conversationStore.saveCheckpoint(this.#threadId, { toolCallId: call.id });
     }
     try {
-      const result = await tool.handler(call.args);
+      // The call id lets a handler that renders into the transcript find its
+      // own card; handlers that only act on the page ignore it.
+      const result = await tool.handler(call.args, call.id);
+      // Drawn from the arguments rather than the result, so the live path and
+      // the replay path render the same thing from the same input.
+      this.#renderToolOutput(tool, call);
       if (navigates) {
         card.settle(TOOL_CALL_STATUS.DONE, this.#strings.navigating);
         return { content: "", halt: true };
@@ -2775,7 +2815,13 @@ export class AgUiChat extends HTMLElement {
         this.#runTools.push({ id: call.id, name: call.name });
         this.#cardFor(call);
       },
-      onActivity: (activityType, content) => {
+      onActivity: (activityType, content, messageId) => {
+        if (activityType === CHART_ACTIVITY_TYPE) {
+          if (this.#chartActivity) {
+            this.#drawActivityChart(messageId, content);
+          }
+          return;
+        }
         if (activityType !== COMPACTION_ACTIVITY_TYPE) {
           return;
         }
@@ -2811,6 +2857,11 @@ export class AgUiChat extends HTMLElement {
         // that shipped in the same release is what makes showing them safe now.
         this.#showPending();
       },
+      onActivityChanged: (messageId, activityType, content) => {
+        if (activityType === CHART_ACTIVITY_TYPE && this.#chartActivity) {
+          this.#drawActivityChart(messageId, content);
+        }
+      },
       onRunEnd: () => {
         // Per-round end; the button stays on Stop until the whole interaction
         // settles — the user must be able to cancel between tool rounds.
@@ -2983,6 +3034,97 @@ export class AgUiChat extends HTMLElement {
     this.#messages.scrollTop = this.#messages.scrollHeight;
   }
 
+  /**
+   * Turn on chart rendering, by whichever route this consumer wants.
+   *
+   * Both routes converge on one renderer deliberately. Built apart they become
+   * two chart implementations with two sets of bugs, and the choice between them
+   * is about *where the data lives* rather than how a bar should look:
+   *
+   * - `"tool"` registers the built-in `render_chart`. The agent decides a chart
+   *   helps and calls it, so the numbers are in its context and it can discuss
+   *   them afterwards. Costs one model round, and works over any transport.
+   * - `"activity"` draws a server-pushed `ACTIVITY_SNAPSHOT` of type `chart`.
+   *   No round trip, and the data never enters the model's context at all —
+   *   which is what makes it the one for a large or sensitive dataset. Only this
+   *   route can update a chart in place as the server computes.
+   *
+   * Off unless asked for, both of them: a component that renders whatever
+   * arrives is not something to switch on for everybody.
+   */
+  enableCharts(routes: readonly ("tool" | "activity")[] = ["tool", "activity"]): void {
+    if (routes.includes("activity")) {
+      this.#chartActivity = true;
+    }
+    if (routes.includes("tool")) {
+      this.registerTool(createChartTool());
+    }
+  }
+
+  /**
+   * Place a tool's rendered node against its own card.
+   *
+   * Anchored rather than appended because a client tool's handler does not run
+   * until the round is over: appending would put the node after everything the
+   * model said next, visibly detached from the call that produced it, and in a
+   * different order than the same transcript takes on reload. The card was
+   * created inline, in the right place, so anchoring makes *when* the handler
+   * runs stop mattering.
+   */
+  #renderToolOutput(tool: ClientTool, call: AgUiToolCall): void {
+    if (tool.render === undefined) {
+      return;
+    }
+    let node: Node | null;
+    try {
+      node = tool.render(call.args);
+    } catch (error) {
+      // `render` is consumer code and this runs inside the history replay, where
+      // a throw abandons the loop and takes every later turn of the transcript
+      // with it -- silently, and again on every reload. A chart that fails to
+      // draw is worth losing; the rest of the conversation is not. Reported so
+      // the failure is findable rather than merely survived.
+      console.warn(`ag-ui-chat: render failed for tool ${call.name}`, error);
+      return;
+    }
+    if (node === null) {
+      return;
+    }
+    // `after` rather than an insert-or-append branch: both callers set the card
+    // element immediately before calling, and a parentless anchor makes `after`
+    // a no-op, so the alternative would be a branch nothing can reach.
+    this.#cardElements.get(call.id)?.after(node);
+    this.#afterTranscriptGrew();
+  }
+
+  /** Draw, or redraw in place, the chart for one activity message. */
+  #drawActivityChart(messageId: string, content: unknown): void {
+    const spec = chartSpecFrom(content);
+    if (spec === null) {
+      return;
+    }
+    const block = renderChart(spec);
+    if (block === null) {
+      return;
+    }
+    const existing = this.#activityBlocks.get(messageId);
+    if (existing === undefined) {
+      this.#ensureGroup().appendChild(block);
+    } else {
+      // Replaced rather than appended: a server redrawing a chart under the same
+      // id means *this chart changed*, and a second copy below the first would
+      // read as two measurements instead of one that moved.
+      existing.replaceWith(block);
+    }
+    this.#activityBlocks.set(messageId, block);
+    this.#afterTranscriptGrew();
+  }
+
+  #afterTranscriptGrew(): void {
+    this.#updateEmptyState();
+    this.#messages.scrollTop = this.#messages.scrollHeight;
+  }
+
   #cardFor(call: AgUiToolCall): ToolCallCard {
     const existing = this.#toolCards.get(call.id);
     if (existing !== undefined) {

package/src/core/agui_client.ts

@@ -83,7 +83,18 @@ export interface AgUiClientHandlers {
    * as opposed to work the agent asked for. `django-ag-ui` emits one with
    * `activityType: "compaction"` when it condensed the history.
    */
-  onActivity(activityType: string, content: unknown): void;
+  onActivity(activityType: string, content: unknown, messageId: string): void;
+  /**
+   * An activity's content changed in place — a snapshot re-sent under the same
+   * `messageId` with `replace`, or an `ACTIVITY_DELTA` whose JSON patch
+   * `@ag-ui/client` has already applied.
+   *
+   * Reported after the client has updated its own message, so `content` is the
+   * result rather than the instruction. That is the whole reason this is a
+   * separate callback: the raw delta event fires *before* the patch lands, and
+   * a subscriber acting on it would redraw from stale content.
+   */
+  onActivityChanged(messageId: string, activityType: string, content: unknown): void;
   /** Fired when a reasoning model starts emitting its chain-of-thought. */
   onReasoningStart(): void;
   /** Fired on every reasoning token; ``buffer`` is the full reasoning text so far. */
@@ -397,6 +408,9 @@ export class AgUiClient {
   #buildSubscriber(pending: AgUiToolCall[], runState: RunState): AgentSubscriber {
     const h = this.#handlers;
     const closed = this.#closedMessageIds;
+    // Charts whose patch has been dispatched but not yet applied. Scoped to the
+    // subscriber, so it cannot outlive the run that created it.
+    const pendingDeltas = new Set<string>();
     return {
       onRunInitialized() {
         h.onRunStart();
@@ -434,8 +448,42 @@ export class AgUiClient {
       onToolCallResultEvent({ event }) {
         h.onToolResult(event.toolCallId, event.content);
       },
-      onActivitySnapshotEvent({ event }) {
-        h.onActivity(event.activityType, event.content);
+      onActivitySnapshotEvent({ event, messages }) {
+        // A snapshot for an id already in the list is a replacement, not a new
+        // activity: the client has swapped its content in place, and a second
+        // append would leave the superseded one on screen.
+        const known = messages.some(
+          (message) => message.id === event.messageId && message.role === "activity",
+        );
+        if (known) {
+          h.onActivityChanged(event.messageId, event.activityType, event.content);
+          return;
+        }
+        h.onActivity(event.activityType, event.content, event.messageId);
+      },
+      // Deliberately does *not* read the message here. `@ag-ui/client`
+      // dispatches this subscriber **before** applying the patch, so the
+      // message still holds its previous content: redrawing from it would leave
+      // the chart one revision behind for the life of the run, and disagreeing
+      // with what a reload shows. Note which chart moved and read the result on
+      // the change that follows.
+      onActivityDeltaEvent({ event }) {
+        pendingDeltas.add(event.messageId);
+      },
+      // Emitted after the client has written the patched messages, which is the
+      // first moment the result exists. Only the ids marked above are looked at,
+      // so an ordinary text delta does not walk the transcript.
+      onMessagesChanged({ messages }) {
+        if (pendingDeltas.size === 0) {
+          return;
+        }
+        for (const id of pendingDeltas) {
+          const message = messages.find((entry) => entry.id === id);
+          if (message !== undefined && message.role === "activity") {
+            h.onActivityChanged(id, message.activityType, message.content);
+          }
+        }
+        pendingDeltas.clear();
       },
       // `@ag-ui/client` maps the deprecated THINKING_* events onto these
       // REASONING_* callbacks, so the reasoning family alone covers both

package/src/index.ts

@@ -2,6 +2,7 @@
 
 export {
   ATTACHMENT_EVENT,
+  CHART_ACTIVITY_TYPE,
   COMPACTION_ACTIVITY_TYPE,
   ELEMENT_TAG,
   LOAD_CAPABILITY_TOOL,
@@ -129,6 +130,13 @@ export {
   type ApprovalRequest,
   requestApproval,
 } from "./ui/approval_card.js";
+// Charts. `CHART_ACTIVITY_TYPE` above is the wire name a server sets on an
+// ACTIVITY_SNAPSHOT; these are the shape it carries and the renderer itself,
+// for a host building its own visual on the same seam.
+export type { ChartKind, ChartSeries, ChartSpec } from "./ui/chart_block.js";
+export { renderChart } from "./ui/chart_block.js";
+export { chartSpecFrom } from "./ui/chart_spec_from.js";
+export { CHART_TOOL_NAME } from "./ui/chart_tool.js";
 export { CheckpointMenu, type CheckpointVerb } from "./ui/checkpoint_menu.js";
 export {
   type ConfirmationOptions,

package/src/tools/client_tool_registry.ts

@@ -11,7 +11,30 @@ export interface ClientTool {
   name: string;
   description: string;
   parameters: Record<string, unknown>;
-  handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+  /**
+   * Run the tool. `callId` identifies the call being executed, for a handler
+   * that renders into the transcript and needs to place itself against its own
+   * card; handlers that only act on the page ignore it.
+   */
+  handler: (args: Record<string, unknown>, callId?: string) => unknown | Promise<unknown>;
+  /**
+   * Draw this call, from its arguments alone.
+   *
+   * Optional, and **the only half that is replayed**. A restored transcript
+   * redraws by calling `render`; it never calls {@link handler}. That is what
+   * keeps a replayable tool apart from an effectful one *structurally* rather
+   * than by promise: the restore path holds no reference to the half that acts,
+   * so re-running `fill_field` on every reload is not a mistake anyone can make.
+   *
+   * The contract this must keep, because it runs again on every restore:
+   *
+   * - a pure function of `args` — no host state, no network, no clock;
+   * - deterministic, so a reload reproduces what was there before;
+   * - free of effects outside the node it returns, which the component places.
+   *
+   * Return `null` for arguments that say nothing worth drawing.
+   */
+  render?: (args: Record<string, unknown>) => Node | null;
 }
 
 /**

package/src/ui/chart_block.ts

@@ -0,0 +1,349 @@
+/**
+ * Draw a {@link ChartSpec} as SVG.
+ *
+ * Every node is built with `createElement`, never parsed from a string, so this
+ * path never reaches the markdown sanitiser and cannot be widened by model
+ * output. That is the argument for taking a *spec* rather than markup: the model
+ * chooses the numbers, this module chooses the DOM. It is why a chart can be
+ * shown on a surface that keeps `img` off by default, a model-controlled URL
+ * being a zero-click exfiltration channel.
+ *
+ * Hand-rolled rather than a charting library, and the difference is not
+ * marginal: the whole renderer costs single-digit kilobytes where a library
+ * costs roughly half this bundle again, in a component distributed over a CDN.
+ */
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+/** One named series of numbers. */
+export interface ChartSeries {
+  readonly label: string;
+  readonly points: readonly number[];
+}
+
+/** How a spec is drawn. */
+export type ChartKind = "bar" | "line" | "pie" | "scatter" | "stacked";
+
+/** A chart, as data. */
+export interface ChartSpec {
+  readonly kind: ChartKind;
+  readonly title?: string;
+  readonly labels: readonly string[];
+  readonly series: readonly ChartSeries[];
+}
+
+const WIDTH = 480;
+const HEIGHT = 220;
+const PAD = { top: 20, right: 12, bottom: 30, left: 44 };
+const PLOT_W = WIDTH - PAD.left - PAD.right;
+const PLOT_H = HEIGHT - PAD.top - PAD.bottom;
+
+// Read from the host's own palette rather than a fixed ramp: the component
+// themes through custom properties everywhere else, and a chart that ignored
+// that would be the one element a host could not restyle.
+const SERIES_COLORS: readonly string[] = [
+  "var(--ag-ui-chart-1, #4f7cff)",
+  "var(--ag-ui-chart-2, #21b573)",
+  "var(--ag-ui-chart-3, #e0803c)",
+  "var(--ag-ui-chart-4, #b563d8)",
+  "var(--ag-ui-chart-5, #d84f6e)",
+  "var(--ag-ui-chart-6, #3ba7c4)",
+];
+
+/** The colour for series `index`, wrapping when there are more series than colours. */
+export function seriesColor(index: number): string {
+  // Cast rather than a `??` fallback: the modulo guarantees a hit, so a
+  // fallback would be a branch no test could ever reach.
+  return SERIES_COLORS[index % SERIES_COLORS.length] as string;
+}
+
+function el<K extends keyof SVGElementTagNameMap>(
+  name: K,
+  attrs: Record<string, string | number>,
+): SVGElementTagNameMap[K] {
+  const node = document.createElementNS(SVG_NS, name);
+  for (const [key, value] of Object.entries(attrs)) {
+    node.setAttribute(key, String(value));
+  }
+  return node;
+}
+
+function text(value: string, attrs: Record<string, string | number>): SVGTextElement {
+  const node = el("text", {
+    "font-size": 10,
+    fill: "currentColor",
+    "fill-opacity": 0.65,
+    ...attrs,
+  });
+  // `textContent`, so a model-supplied label is text and never markup.
+  node.textContent = value;
+  return node;
+}
+
+/** Every running subtotal a stack passes through, column by column. */
+function stackRunning(spec: ChartSpec): number[] {
+  const seen: number[] = [];
+  spec.labels.forEach((_label, i) => {
+    let running = 0;
+    for (const series of spec.series) {
+      running += series.points[i] ?? 0;
+      seen.push(running);
+    }
+  });
+  return seen;
+}
+
+function extent(spec: ChartSpec): { min: number; max: number } {
+  // A stack's extent has to cover every *running subtotal*, not just the column
+  // totals: with mixed signs the running value swings wider than the total it
+  // ends on, and scaling to the total alone puts segments far off the canvas.
+  const values =
+    spec.kind === "stacked"
+      ? stackRunning(spec)
+      : spec.series.flatMap((series) => [...series.points]);
+  const max = Math.max(0, ...values);
+  const min = Math.min(0, ...values);
+  // A flat series would divide by zero when scaling; give it a nominal span so
+  // it draws as a flat line rather than vanishing.
+  return max === min ? { min, max: max + 1 } : { min, max };
+}
+
+function scaleY(value: number, min: number, max: number): number {
+  return PAD.top + PLOT_H - ((value - min) / (max - min)) * PLOT_H;
+}
+
+function bandCentre(index: number, count: number): number {
+  const step = PLOT_W / count;
+  return PAD.left + step * index + step / 2;
+}
+
+function drawAxes(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number): void {
+  for (const value of [min, max]) {
+    const y = scaleY(value, min, max);
+    svg.appendChild(
+      el("line", {
+        x1: PAD.left,
+        y1: y,
+        x2: WIDTH - PAD.right,
+        y2: y,
+        stroke: "currentColor",
+        "stroke-opacity": value === min ? 0.35 : 0.12,
+      }),
+    );
+    svg.appendChild(
+      text(String(Math.round(value)), { x: PAD.left - 6, y: y + 4, "text-anchor": "end" }),
+    );
+  }
+  spec.labels.forEach((label, i) => {
+    svg.appendChild(
+      text(label, {
+        x: bandCentre(i, spec.labels.length),
+        y: HEIGHT - PAD.bottom + 16,
+        "text-anchor": "middle",
+      }),
+    );
+  });
+}
+
+function drawBars(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number): void {
+  const step = PLOT_W / spec.labels.length;
+  const width = (step * 0.7) / spec.series.length;
+  const base = scaleY(min, min, max);
+  spec.series.forEach((series, s) => {
+    series.points.forEach((value, i) => {
+      const y = scaleY(value, min, max);
+      svg.appendChild(
+        el("rect", {
+          x: PAD.left + step * i + step * 0.15 + width * s,
+          y,
+          width,
+          height: Math.max(1, base - y),
+          fill: seriesColor(s),
+          rx: 2,
+        }),
+      );
+    });
+  });
+}
+
+function drawStacked(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number): void {
+  const step = PLOT_W / spec.labels.length;
+  const width = step * 0.7;
+  // Indexed by the same `i` it was built from, so every read is a hit; cast
+  // rather than defaulting, which would add a branch nothing can reach.
+  const running = spec.labels.map(() => 0);
+  spec.series.forEach((series, s) => {
+    series.points.forEach((value, i) => {
+      const from = running[i] as number;
+      const to = from + value;
+      running[i] = to;
+      const y = scaleY(to, min, max);
+      svg.appendChild(
+        el("rect", {
+          x: PAD.left + step * i + step * 0.15,
+          y,
+          width,
+          height: Math.max(1, scaleY(from, min, max) - y),
+          fill: seriesColor(s),
+        }),
+      );
+    });
+  });
+}
+
+function drawLines(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number): void {
+  spec.series.forEach((series, s) => {
+    const points = series.points
+      .map((value, i) => `${bandCentre(i, spec.labels.length)},${scaleY(value, min, max)}`)
+      .join(" ");
+    svg.appendChild(
+      el("polyline", {
+        points,
+        fill: "none",
+        stroke: seriesColor(s),
+        "stroke-width": 2,
+        "stroke-linejoin": "round",
+      }),
+    );
+  });
+}
+
+function drawScatter(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number): void {
+  spec.series.forEach((series, s) => {
+    series.points.forEach((value, i) => {
+      svg.appendChild(
+        el("circle", {
+          cx: bandCentre(i, spec.labels.length),
+          cy: scaleY(value, min, max),
+          r: 4,
+          fill: seriesColor(s),
+          "fill-opacity": 0.85,
+        }),
+      );
+    });
+  });
+}
+
+/**
+ * Pie draws the **first** series' points as shares of their own total, one
+ * wedge per label — the only kind whose slices are the labels rather than the
+ * series, so a second series has nowhere to go and is ignored rather than
+ * silently summed into the first.
+ */
+function drawPie(svg: SVGSVGElement, points: readonly number[]): void {
+  const total = points.reduce((sum, value) => sum + value, 0);
+  const cx = WIDTH / 2;
+  const cy = PAD.top + PLOT_H / 2;
+  const r = Math.min(PLOT_W, PLOT_H) / 2;
+  if (total === 0) {
+    // Every share is zero, so there is no wedge to draw and a full circle would
+    // claim one slice owns everything. An outline says "nothing here" honestly.
+    svg.appendChild(
+      el("circle", { cx, cy, r, fill: "none", stroke: "currentColor", "stroke-opacity": 0.3 }),
+    );
+    return;
+  }
+  let angle = -Math.PI / 2;
+  points.forEach((value, i) => {
+    const sweep = (value / total) * Math.PI * 2;
+    const end = angle + sweep;
+    // A wedge of the whole circle cannot be drawn as one arc (start and end
+    // coincide, so the path collapses); draw it as a plain circle instead.
+    if (sweep >= Math.PI * 2) {
+      svg.appendChild(el("circle", { cx, cy, r, fill: seriesColor(i) }));
+    } else {
+      const x1 = cx + r * Math.cos(angle);
+      const y1 = cy + r * Math.sin(angle);
+      const x2 = cx + r * Math.cos(end);
+      const y2 = cy + r * Math.sin(end);
+      const large = sweep > Math.PI ? 1 : 0;
+      svg.appendChild(
+        el("path", {
+          d: `M ${cx} ${cy} L ${x1} ${y1} A ${r} ${r} 0 ${large} 1 ${x2} ${y2} Z`,
+          fill: seriesColor(i),
+        }),
+      );
+    }
+    angle = end;
+  });
+}
+
+function buildLegend(entries: readonly string[]): HTMLDivElement | null {
+  if (entries.length < 2) {
+    return null;
+  }
+  const row = document.createElement("div");
+  row.className = "chart-legend";
+  row.setAttribute("part", "chart-legend");
+  entries.forEach((label, i) => {
+    const item = document.createElement("span");
+    item.className = "chart-legend-item";
+    const swatch = document.createElement("span");
+    swatch.className = "chart-legend-swatch";
+    swatch.style.background = seriesColor(i);
+    item.append(swatch, document.createTextNode(label));
+    row.appendChild(item);
+  });
+  return row;
+}
+
+/**
+ * Render one spec as a self-contained block, or `null` when it says nothing.
+ *
+ * A spec with no labels or no series is not drawn: an empty frame reads as
+ * "there is no data" when the truth is "the caller sent nothing", and the two
+ * deserve different answers.
+ */
+export function renderChart(spec: ChartSpec): HTMLDivElement | null {
+  if (spec.labels.length === 0 || spec.series.length === 0) {
+    return null;
+  }
+  const block = document.createElement("div");
+  block.className = "chart-block";
+  block.setAttribute("part", "chart-block");
+
+  if (spec.title !== undefined && spec.title !== "") {
+    const heading = document.createElement("div");
+    heading.className = "chart-title";
+    heading.setAttribute("part", "chart-title");
+    heading.textContent = spec.title;
+    block.appendChild(heading);
+  }
+
+  const svg = el("svg", { viewBox: `0 0 ${WIDTH} ${HEIGHT}`, width: "100%", role: "img" });
+  svg.setAttribute("aria-label", spec.title ?? `${spec.kind} chart`);
+
+  if (spec.kind === "pie") {
+    // `series[0]` is guaranteed by the early return above; a pie's slices are
+    // its labels, so a second series has nowhere to go and is ignored rather
+    // than silently summed into the first. Negative shares are floored, since a
+    // wedge cannot sweep backwards.
+    const first = spec.series[0] as ChartSeries;
+    drawPie(
+      svg,
+      first.points.map((value) => Math.max(0, value)),
+    );
+  } else {
+    const { min, max } = extent(spec);
+    drawAxes(svg, spec, min, max);
+    if (spec.kind === "bar") {
+      drawBars(svg, spec, min, max);
+    } else if (spec.kind === "stacked") {
+      drawStacked(svg, spec, min, max);
+    } else if (spec.kind === "line") {
+      drawLines(svg, spec, min, max);
+    } else {
+      drawScatter(svg, spec, min, max);
+    }
+  }
+  block.appendChild(svg);
+
+  // Pie's slices are its labels; every other kind's are its series.
+  const legend = buildLegend(
+    spec.kind === "pie" ? spec.labels : spec.series.map((series) => series.label),
+  );
+  if (legend !== null) {
+    block.appendChild(legend);
+  }
+  return block;
+}