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

package/src/ui/chart_block.ts

@@ -0,0 +1,354 @@
+/**
+ * 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) => {
+      // `?? 0` rather than a cast: `renderChart` is exported, so a caller can
+      // hand it a series carrying more points than there are labels, which
+      // `chartSpecFrom` would have refused. The cast that used to be here
+      // claimed that could not happen and wrote `y="NaN"` into the DOM when it
+      // did.
+      const from = running[i] ?? 0;
+      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;
+}

package/src/ui/chart_spec_from.ts

@@ -0,0 +1,125 @@
+/**
+ * Narrow untrusted input into a {@link ChartSpec}.
+ *
+ * Both arrival routes are untrusted in the same way — a model writes one, a
+ * server the other — so neither is taken on shape. Kept out of the renderer
+ * because the renderer's job is drawing, and a value that reaches it has
+ * already been vouched for.
+ */
+
+import type { ChartKind, ChartSpec } from "./chart_block.js";
+
+const KINDS: readonly ChartKind[] = ["bar", "line", "pie", "scatter", "stacked"];
+
+/**
+ * Most points a spec may carry, across every series.
+ *
+ * Not a taste limit. `Math.max(0, ...values)` throws `RangeError` on a large
+ * enough spread, and the renderer runs inside the history replay, where a throw
+ * abandons the replay and takes every later turn of the transcript with it —
+ * permanently, on every reload. A chart nobody can read is a far smaller
+ * problem than a conversation that silently loses its tail.
+ */
+const MAX_POINTS = 20_000;
+
+/**
+ * Whether a spec's *labels* are cheap enough to draw.
+ *
+ * `MAX_POINTS` bounds the data; this bounds the DOM. Every label produces an
+ * axis text node whatever the series count, so a spec well inside the point
+ * budget can still emit tens of thousands of nodes and block the main thread —
+ * again on every reload, since it is in the transcript. Kept separate because
+ * the two limits answer different questions and a single number cannot.
+ */
+const MAX_LABELS = 2_000;
+
+/**
+ * Largest magnitude a point may carry.
+ *
+ * `Number.isFinite` is not enough on its own: two finite extremes still give an
+ * infinite *range*, and `(value - min) / Infinity` is `NaN`, which reaches the
+ * DOM as `y="NaN"`. Bounding the values bounds the range.
+ */
+const MAX_MAGNITUDE = 1e15;
+
+function asKind(value: unknown): ChartKind {
+  // Anything unrecognised falls back to `bar` rather than refusing the spec: an
+  // unknown kind is a caller reaching for a chart type we do not draw, and the
+  // data is still worth showing.
+  return KINDS.includes(value as ChartKind) ? (value as ChartKind) : "bar";
+}
+
+function asNumbers(value: unknown): number[] | null {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  const out: number[] = [];
+  for (const item of value) {
+    // `Number.isFinite` rather than `typeof === "number"`: JSON encoders render
+    // NaN and Infinity as nulls or strings depending on the encoder, and either
+    // would scale into a chart with no visible extent.
+    if (typeof item !== "number" || !Number.isFinite(item)) {
+      return null;
+    }
+    if (Math.abs(item) > MAX_MAGNITUDE) {
+      return null;
+    }
+    out.push(item);
+  }
+  return out;
+}
+
+function asStrings(value: unknown): string[] | null {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  // `every` over an index range rather than `Array.prototype.some`, which skips
+  // holes: a sparse array passed the old check and drew a chart with blank axis
+  // labels, which reads as a rendering bug rather than bad input.
+  for (let i = 0; i < value.length; i += 1) {
+    if (typeof value[i] !== "string") {
+      return null;
+    }
+  }
+  return value as string[];
+}
+
+/** A well-formed spec, or `null` for anything that cannot be drawn honestly. */
+export function chartSpecFrom(value: unknown): ChartSpec | null {
+  if (typeof value !== "object" || value === null) {
+    return null;
+  }
+  const raw = value as Record<string, unknown>;
+  const labels = asStrings(raw["labels"]);
+  if (labels === null || !Array.isArray(raw["series"])) {
+    return null;
+  }
+
+  const series: { label: string; points: number[] }[] = [];
+  for (const entry of raw["series"]) {
+    if (typeof entry !== "object" || entry === null) {
+      return null;
+    }
+    const item = entry as Record<string, unknown>;
+    const points = asNumbers(item["points"]);
+    // A series with a different number of points than there are labels would
+    // silently misalign every value after the gap. A chart that is subtly wrong
+    // still reads as authoritative, which is worse than no chart at all.
+    if (points === null || points.length !== labels.length) {
+      return null;
+    }
+    series.push({ label: typeof item["label"] === "string" ? item["label"] : "", points });
+  }
+  if (series.length === 0) {
+    return null;
+  }
+  if (series.length * labels.length > MAX_POINTS || labels.length > MAX_LABELS) {
+    return null;
+  }
+
+  const kind = asKind(raw["kind"]);
+  const title = raw["title"];
+  // The key is omitted rather than set to `undefined`: `title` is genuinely
+  // optional and this tsconfig distinguishes absent from present-and-undefined.
+  return typeof title === "string" ? { kind, title, labels, series } : { kind, labels, series };
+}

package/src/ui/chart_tool.ts

@@ -0,0 +1,72 @@
+/**
+ * The built-in `render_chart` tool: the agent-called route to a chart.
+ *
+ * A thin thing on purpose. It carries no `handler` of its own beyond reporting
+ * back to the model, because everything it does is drawing — which lives in
+ * `render`, the half the component replays. A consumer wanting charts gets this
+ * without writing a renderer; a consumer wanting something else writes their own
+ * tool against the same seam.
+ */
+
+import type { ClientTool } from "../tools/client_tool_registry.js";
+import { renderChart } from "./chart_block.js";
+import { chartSpecFrom } from "./chart_spec_from.js";
+
+/** The name the built-in chart tool registers under. */
+export const CHART_TOOL_NAME = "render_chart";
+
+function draw(args: Record<string, unknown>): HTMLDivElement | null {
+  const spec = chartSpecFrom(args);
+  return spec === null ? null : renderChart(spec);
+}
+
+/** Whether these arguments would produce a chart, without producing one. */
+function drawable(args: Record<string, unknown>): boolean {
+  const spec = chartSpecFrom(args);
+  return spec !== null && spec.labels.length > 0 && spec.series.length > 0;
+}
+
+const REJECTED =
+  "chart not rendered: expected labels (strings) and series, each with one finite number per label";
+
+/** The built-in chart tool. */
+export function createChartTool(): ClientTool {
+  return {
+    name: CHART_TOOL_NAME,
+    description:
+      "Show a chart in the conversation. Supply the data and the page draws it. " +
+      "Every series must have exactly one point per label.",
+    parameters: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: ["bar", "line", "pie", "scatter", "stacked"] },
+        title: { type: "string" },
+        labels: { type: "array", items: { type: "string" } },
+        series: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              label: { type: "string" },
+              points: { type: "array", items: { type: "number" } },
+            },
+            required: ["points"],
+          },
+        },
+      },
+      required: ["labels", "series"],
+      "x-summary": "Draw a chart",
+    },
+    // Says what happened and nothing else; the drawing is `render`'s job. Told
+    // plainly when the arguments are unusable, because the model can fix that
+    // and retry — a silent no-op would leave it believing the chart is on screen.
+    // Answers on what will actually be drawn, not on what validated: a spec can
+    // pass validation and still have nothing to show, and reporting success
+    // then would leave the model believing a chart is on screen. Asks the
+    // question without building the chart, because `render` is about to build
+    // the same one a moment later and drawing it twice is pure waste on a spec
+    // large enough to matter.
+    handler: (args: Record<string, unknown>) => (drawable(args) ? "chart rendered" : REJECTED),
+    render: draw,
+  };
+}

package/src/ui/styles.ts

@@ -1528,6 +1528,50 @@ export const STYLES = `
   margin-top: 6px;
 }
 
+/* Charts.
+ *
+ * The SVG scales to the column and carries no colours of its own beyond the
+ * series palette, so a host restyles it the same way it restyles everything
+ * else. Series colours are custom properties with fallbacks rather than fixed
+ * values, and the axis furniture inherits currentColor at low opacity so it
+ * reads correctly in either theme without a second palette.
+ */
+.chart-block {
+  align-self: stretch;
+  max-width: 100%;
+  margin: 6px 0;
+  color: var(--_fg);
+}
+
+.chart-title {
+  margin-bottom: 2px;
+  font-size: 0.85em;
+  font-weight: 600;
+  opacity: 0.85;
+}
+
+.chart-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px 12px;
+  margin-top: 4px;
+  font-size: 0.78em;
+  opacity: 0.75;
+}
+
+.chart-legend-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.chart-legend-swatch {
+  width: 9px;
+  height: 9px;
+  border-radius: 2px;
+  flex: 0 0 auto;
+}
+
 .run-notice {
   display: inline-flex;
   align-items: center;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.25.2";
+export const VERSION: string = "0.26.1";