Glyph 0.3.0 — charts for agentic frameworks

Byte-stable rendering, so agents can diff what they drew

Same JSON spec → same SVG bytes on Ubuntu, macOS, Windows, Node 20, Node 22. Snapshot-testable in CI; diffable in git.

An LLM regenerates code on every turn. A renderer that emits a slightly different byte stream every time — fractional rounding, font fallback, random IDs — destroys the agent’s ability to assert “the chart didn’t change.” Glyph emits the same bytes from the same inputs, full stop. That single property unlocks a regression-test pattern that’s normal for code and unusual for graphics: snapshot a chart’s SVG; assert on it.

It also makes the artifact a durable handle. The agent can put the SVG in a git commit, attach it to a PR, embed it in a Markdown comment — the same way it would treat a code file. No CDN, no JavaScript runtime, no embed iframe. Just text.

16 audit rules — guardrails against misleading agent output

A pure-fn linter the agent calls before publishing. glyph_audit_spec returns sorted findings; the compiler can refuse to render when strictness: "error".

The risk an agent-authored chart introduces isn’t that it’s ugly — it’s that it’s subtly wrong in ways no one notices. Truncated bar y-axis. Undisclosed log scale. Pie chart with 14 slices. Bar chart on a continuous axis. v0.3.0 ships five new audit rules bringing the total to 16, every one of them a real misleading-chart pattern the agent stack will eventually emit:

• AUDIT-05 — line or area mark on a categorical x-axis. The connecting stroke implies an ordered progression nominal categories don’t carry; readers see a fake trend.
• AUDIT-12 — pie / donut / arc with more than 7 slices. Angle comparison breaks past ~5 (Cleveland-McGill); past 7 it’s unreadable.
• AUDIT-13 — bar chart on a quantitative x. Usually wants mark: "rect" or histogram semantics.
• AUDIT-14 — more than four overlay layers. Visual overload past 4; suggest small multiples.
• AUDIT-15 — multi-layer chart with no title. A bare multi-series chart has no anchor for what the reader is comparing.

The earlier 11 rules cover truncated y-axes, dual-axis traps, color-blind palette collapse, diverging palettes without midpoints, brand-kit contrast failures, and silent missing-data dropouts. Every rule is pure-fn, deterministic, and emits a stable rule_id the agent can suppress or fix.

// Audit before rendering — same call, same findings, every time.
{
  "tool": "glyph_audit_spec",
  "arguments": { "spec": {...} }
}
// → { count: 1, highSeverity: 1, findings: [{ rule_id: "AUDIT-01", ... }] }

Audit-aware glyph_spec_patch — refinement that can’t silently regress

An agent refining a chart via JSON Patch can no longer introduce a misleading pattern the original didn’t have. The verb diffs audit findings before and after; HIGH-severity introductions are refused unless the caller passes acknowledged: true.

v0.2.0 shipped glyph_spec_patch: an agent can hand a handle and an RFC 6902 patch list and get back a refined chart. Useful — but it bypassed the audit pass. An agent that tweaked a bar chart’s y-domain to [100, 200] for visual emphasis would silently introduce AUDIT-01 (truncated y-axis) without any signal that the refinement had crossed a trustworthiness boundary.

0.3.0 fixes this. After applying the patch, the verb re-runs auditSpec on the patched spec and diffs against the original’s findings (keyed by rule_id + path). If the patch introduces a new HIGH-severity finding, the verb refuses with a structured error:

{
  "error": "audit_regression",
  "message": "Patch would introduce HIGH-severity findings the original spec didn't have.",
  "regressions": [
    { "rule_id": "AUDIT-01", "severity": "high", "path": "/layers/0/encoding/y", ... }
  ]
}

The agent has two responses: fix the patch, or pass acknowledged: true when the regression is intentional (annotating a deviation, emphasizing a known caveat). Pre-existing findings aren’t flagged — only what the patch added. This closes the loop on agentic chart refinement: the iteration cycle has a guardrail.

Provenance verbs — any other agent can verify byte-stable

Every Glyph SVG carries a SHA-256 seal over (spec, rows, schema, library version). glyph_verify recomputes it. v0.3.0 adds glyph_seal — the seal without the SVG.

An MCP-native chart library is interesting in a multi-agent context only if a second agent can verify what the first one drew. Glyph SVGs carry a cryptographic seal: SHA-256 over canonical-JSON-stringified spec + rows + schema + library version. glyph_verify takes the SVG (or just the seal), recomputes the hashes, and tells you whether the bytes you have match the inputs that allegedly produced them.

0.3.0 closes the asymmetry by adding glyph_seal: emits the seal as standalone JSON without rendering an SVG. Useful for a verifier that already has the SVG, a content-addressable cache that wants the hash before the bytes, or an attestation pipeline that signs over (spec, rows, schema) without needing the rendered output. The seal is the same one glyph_verify matches against, so the loop closes:

{
  "tool": "glyph_seal",
  "arguments": { "spec": {...}, "rows": [...], "schema": [...] }
}
// → { "format": "glyph-provenance/1", "specHash": "20b9...", "dataHash": "f1c3...",
//     "libraryVersion": "0.3.0", "rowCount": 120, "scaleDigest": "ba4e..." }

Whyboard templates — a planner doesn’t have to invent the layout

Four canonical diagnostic shapes: root question + three branches (anomaly · decompose · forecast). Pre-rendered compose scenes in the playground; glyph_whyboard emits the same structure live.

A “why is X happening?” investigation is recursive: the agent picks a root question, decomposes it into branches (anomalies, breakdowns, forecasts), and assembles the result as a board. Glyph has shipped glyph_whyboard since 0.0.x — what was missing was a canonical visual layout the agent can hand the user as a starting point.

0.3.0 ships four templates, one per common investigation shape:

• Revenue miss — “Why did Q3 miss target?” (segment breakdown, last 8 quarters, scenario forecast)
• Conversion drop — “Why did the funnel collapse?” (step-by-step funnel, anomaly on the step that broke, root-cause attribution)
• Latency spike — “Why is API latency spiking?” (per-endpoint p50/p95, anomaly bands, recovery ETA)
• Churn spike — “Why did churn spike this month?” (cohort retention, trial-to-paid drop, 3-month forecast)

Each template is a 1200×760 compose scene with the same shape the glyph_whyboard verb returns. A planner that detects “the user is asking why X dropped” picks the closest template, swaps in real data via glyph_spec_patch, and gets back a board with branch summaries the next reasoning hop can chain into.

Story templates — narrative panel chains, ready-to-use

Three canonical 4-panel storyboards: quarterly review, incident retro, A/B test readout. Compose-scene mirrors of what glyph_story emits as a panel chain.

The other half of the agentic-presentation loop: not “why,” but “tell.” A retrospective, a quarterly review, an experiment readout — these are sequence-of-panels, not one-big-chart. glyph_story has shipped multi-scene narrative spec generation since 0.2.0. What 0.3.0 adds is three reference templates the agent can fall back on:

• Quarterly review — revenue trend → segment mix → cohort retention → growth forecast
• Incident retro — latency spike → error budget burn → root-cause attribution → recovery curve
• A/B test readout — traffic split → primary metric lift → secondary metrics → decision matrix

Each panel is a 520×290 raw-svg block with a step badge, caption, subcaption, and chart slot — exactly the shape an LLM can patch field-by-field. A multi-agent stack where one model generates the data narrative and another renders the panels can now share a typed layout instead of negotiating one from scratch on every turn.