@tangle-network/charts 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @tangle-network/charts
+
+Benchmark figures as static SVG and HTML tables.
+Five figures cover the decisions a benchmark reader makes:
+
+| Figure | Question |
+|---|---|
+| `rankedRates` | Which setup solves most, and how uncertain is each rate? |
+| `costFrontier` | Which setup gives the most solves per dollar? |
+| `comparisonIntervals` | Is each step in the order real? |
+| `taskMatrix` | Where does each setup succeed and fail? |
+| `breakdown` | Why do attempts fail? |
+
+The library draws and never decides.
+Ranks, intervals, frontier membership, estimate labels and pass counts come from the producer: a board record, a VerticalBench report or an agent-eval lens.
+A figure function returns a `Refusal` in place of a figure it cannot draw honestly, for example a bar over too few units, an interval that names no method, or a frontier the producer did not compute.
+
+It has no runtime dependencies and uses no DOM, so it runs in a Worker, a build step or a browser.
+
+## Use
+
+```ts
+import { isRefusal, rankedRates, renderFigure, renderNotes, renderRefusals } from "@tangle-network/charts";
+import "@tangle-network/charts/figure.css";
+
+const fig = rankedRates(rows, { measure: "solve rate", passTier: "B" });
+const html = isRefusal(fig) ? renderRefusals([fig]) : renderFigure(fig, 1) + renderNotes([fig]);
+```
+
+Each figure returns:
+
+- `finding`, `lede` and `read`: sentences generated from the input. No function accepts heading text.
+- `svg.wide` (720 px) and `svg.narrow` (358 px, or `null` when the table is the phone view).
+- `table`: an HTML table with every number the plot shows.
+- `note`: the method, the n and every exclusion, rendered by `renderNotes`.
+
+## Colour
+
+Marks carry classes, and `figure.css` maps them to the `--chart-*` tokens in `@tangle-network/brand` tokens.css.
+A render contains no colour value, so it follows the page theme.
+A document without brand tokens (a PDF, a sandboxed iframe) embeds `chartTokensCss` and `figureCss` in a `<style>` element.
+`chartTokensCss` is light by default, dark under `prefers-color-scheme: dark` or `data-theme="dark"`, and light in print.
+
+One accent marks the measure a reader decides on.
+One muted grey marks everything secondary.
+An indigo ramp marks App Grade tiers C, B, A and S; F is an outline.
+Identity is carried by direct labels, never by hue.
+
+## Develop
+
+```sh
+pnpm --filter @tangle-network/charts gen:css   # after editing src/figure.css or brand tokens.css
+pnpm --filter @tangle-network/charts build     # fails when src/css.generated.ts is stale
+```
+
+## Release
+
+The package is private until its first npm publish.
+npm trusted publishing needs the package to exist before a trusted publisher can be added, so the first version is published once by an owner, then `npm trust github @tangle-network/charts --file release.yml --repo tangle-network/brand --allow-publish` hands later versions to the release workflow.

package/dist/figure.css

@@ -0,0 +1,295 @@
+/* @tangle-network/charts — figure block and mark styles.
+ *
+ * Every colour is a --chart-* token from @tangle-network/brand tokens.css, so a
+ * figure follows the page theme. A standalone document without brand tokens
+ * embeds `chartTokensCss` first. Fonts fall back to Inter and JetBrains Mono.
+ *
+ * Each figure carries a 720 px and a 358 px render. The swap follows the
+ * figure's own width (a container query), so a narrow column shows the phone
+ * render even on a wide screen. */
+
+.tgc-figure {
+  margin: 32px 0 0;
+  padding: 0;
+  max-width: 720px;
+  color: var(--chart-ink);
+  font-family: var(--font-sans, Inter, ui-sans-serif, system-ui, sans-serif);
+}
+
+.tgc-finding {
+  margin: 0 0 8px;
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 600;
+  color: var(--chart-ink);
+}
+
+.tgc-noteref {
+  margin-left: 2px;
+  font-size: 12px;
+  font-weight: 400;
+  color: var(--chart-ink-muted);
+  text-decoration: none;
+  font-family: var(--font-mono, "JetBrains Mono", ui-monospace, monospace);
+}
+.tgc-noteref:hover,
+.tgc-noteref:focus-visible {
+  color: var(--chart-accent);
+  text-decoration: underline;
+}
+
+.tgc-lede {
+  margin: 0 0 16px;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--text-secondary, var(--chart-ink));
+}
+
+.tgc-plot {
+  container-type: inline-size;
+}
+.tgc-wide svg,
+.tgc-narrow svg {
+  display: block;
+  overflow: visible;
+}
+.tgc-narrow {
+  display: none;
+}
+.tgc-narrow svg {
+  max-width: 100%;
+  height: auto;
+}
+@container (max-width: 719.98px) {
+  .tgc-wide {
+    display: none;
+  }
+  .tgc-narrow {
+    display: block;
+  }
+}
+
+.tgc-read {
+  margin: 8px 0 0;
+  font-size: 12px;
+  line-height: 16px;
+  color: var(--chart-ink-muted);
+}
+
+.tgc-data {
+  margin: 8px 0 0;
+  font-size: 12px;
+  line-height: 16px;
+}
+.tgc-data > summary {
+  cursor: pointer;
+  color: var(--chart-ink-muted);
+  width: fit-content;
+}
+.tgc-data > summary:hover {
+  color: var(--chart-ink);
+}
+.tgc-data[open] > summary {
+  margin-bottom: 8px;
+}
+
+.tgc-scroll {
+  overflow-x: auto;
+}
+.tgc-scroll:focus-visible {
+  outline: 2px solid var(--chart-accent);
+  outline-offset: 2px;
+}
+
+.tgc-table {
+  border-collapse: collapse;
+  min-width: 100%;
+  font-size: 12px;
+  line-height: 16px;
+  color: var(--chart-ink);
+  /* A host page's table rules must not restyle the figure's table. */
+  border: 0;
+  border-radius: 0;
+  background: none;
+}
+.tgc-table caption {
+  text-align: left;
+  padding: 0 0 8px;
+  color: var(--chart-ink-muted);
+}
+.tgc-table th,
+.tgc-table td {
+  padding: 6px 12px 6px 0;
+  border-bottom: 1px solid var(--chart-rule);
+  text-align: left;
+  vertical-align: top;
+  font-weight: 400;
+  font-size: inherit;
+  color: inherit;
+  background: none;
+  text-transform: none;
+  letter-spacing: normal;
+}
+.tgc-table thead th {
+  color: var(--chart-ink-muted);
+  white-space: nowrap;
+}
+.tgc-table tbody th {
+  position: sticky;
+  left: 0;
+  background: var(--chart-canvas, var(--depth-1, transparent));
+}
+.tgc-table .tgc-n {
+  font-family: var(--font-mono, "JetBrains Mono", ui-monospace, monospace);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+.tgc-table thead .tgc-n {
+  font-family: inherit;
+}
+.tgc-table tbody tr:hover {
+  background: var(--chart-shade);
+}
+.tgc-narrow-table .tgc-table {
+  display: block;
+  overflow-x: auto;
+}
+
+.tgc-notes {
+  margin: 16px 0 0;
+  padding-left: 20px;
+  font-size: 12px;
+  line-height: 16px;
+  color: var(--chart-ink-muted);
+}
+.tgc-notes li {
+  margin: 0 0 8px;
+  padding-left: 4px;
+}
+.tgc-notes li:target {
+  color: var(--chart-ink);
+}
+.tgc-backlink {
+  color: var(--chart-ink-muted);
+  text-decoration: none;
+}
+
+.tgc-refusals {
+  margin: 8px 0 0;
+  padding-left: 20px;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--chart-ink-muted);
+}
+
+/* Marks */
+.tgc-svg {
+  font-family: var(--font-sans, Inter, ui-sans-serif, system-ui, sans-serif);
+}
+.tgc-svg .tgc-num {
+  font-family: var(--font-mono, "JetBrains Mono", ui-monospace, monospace);
+  font-variant-numeric: tabular-nums;
+}
+.tgc-ink {
+  fill: var(--chart-ink);
+}
+.tgc-ink-muted {
+  fill: var(--chart-ink-muted);
+}
+.tgc-bar,
+.tgc-ci,
+.tgc-pt-front {
+  fill: var(--chart-accent);
+}
+.tgc-gridline {
+  stroke: var(--chart-grid);
+  stroke-width: 1;
+}
+.tgc-rule {
+  stroke: var(--chart-rule);
+  stroke-width: 1;
+}
+.tgc-axis,
+.tgc-zero {
+  stroke: var(--chart-muted);
+  stroke-width: 1;
+}
+.tgc-whisker,
+.tgc-tick {
+  stroke: var(--chart-ink);
+  stroke-width: 1.5;
+  stroke-linecap: round;
+}
+.tgc-threshold {
+  stroke: var(--chart-ink);
+  stroke-width: 1.5;
+  stroke-dasharray: 3 3;
+}
+.tgc-front-line {
+  fill: none;
+  stroke: var(--chart-ink);
+  stroke-width: 1.5;
+  stroke-linejoin: round;
+}
+.tgc-pt,
+.tgc-open {
+  fill: none;
+  stroke: var(--chart-muted);
+  stroke-width: 1.5;
+}
+.tgc-pt-est {
+  fill: none;
+  stroke: var(--chart-accent);
+  stroke-width: 2;
+}
+.tgc-pt-ci,
+.tgc-strike {
+  stroke: var(--chart-muted);
+  stroke-width: 1.5;
+}
+.tgc-leader {
+  stroke: var(--chart-muted);
+  stroke-width: 1;
+}
+.tgc-ci-exact,
+.tgc-dot {
+  fill: var(--chart-muted);
+}
+.tgc-dashed {
+  stroke-dasharray: 2 2;
+}
+.tgc-tier-c {
+  fill: var(--chart-tier-c);
+}
+.tgc-tier-b {
+  fill: var(--chart-tier-b);
+}
+.tgc-tier-a {
+  fill: var(--chart-tier-a);
+}
+.tgc-tier-s {
+  fill: var(--chart-tier-s);
+}
+/* Neutral tint for counts: never the accent, capped at half strength so ink keeps 6:1. */
+.tgc-tint {
+  fill: color-mix(in srgb, var(--chart-muted) calc(var(--s, 0) * 50%), transparent);
+}
+
+@media print {
+  .tgc-plot {
+    container-type: normal;
+  }
+  .tgc-wide {
+    display: block;
+  }
+  .tgc-narrow {
+    display: none;
+  }
+  .tgc-wide svg {
+    width: 100%;
+    height: auto;
+  }
+  .tgc-figure {
+    break-inside: avoid;
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Inputs and outputs of the figure functions.
+ *
+ * The library draws and never decides. Ranks, intervals, frontier membership,
+ * estimate labels and pass counts arrive from the producer (a board record, a
+ * VerticalBench report, an agent-eval lens). A figure function returns a
+ * `Refusal` instead of a figure it cannot draw honestly.
+ */
+/** agent-eval `SearchEstimateMethod`, the same strings: what a unit count supports. */
+type Estimate = "none" | "insufficient" | "descriptive" | "bootstrap";
+type IntervalMethod = "task-cluster-bootstrap" | "mcnemar-exact" | "wilson";
+/**
+ * A confidence interval as the producer recorded it. `level` and `method` are
+ * nullable because real records omit them; a figure refuses to draw an
+ * interval that does not name both.
+ */
+interface Interval {
+    lower: number;
+    upper: number;
+    level: number | null;
+    method: IntervalMethod | null;
+}
+/** The App Grade ladder, lowest first. U (unable to measure) is not on it. */
+type Tier = "F" | "C" | "B" | "A" | "S";
+type TierCounts = Record<Tier, number>;
+/** Where a cost comes from. Only `receipts` is billed spend. */
+type CostBasis = "receipts" | "estimated" | "unknown";
+/** A column or row identity: an AgentProfile, a model, a judge, a search node. */
+interface Setup {
+    id: string;
+    label: string;
+    /** Null when the order is a sort, not a ranking backed by comparisons. */
+    rank: number | null;
+}
+/** One setup's rate. Field names follow the board record's `BoardProfile`. */
+interface RateRow extends Setup {
+    solved: number;
+    attempts: number;
+    rate: number;
+    /** The producer's label for what `attempts` supports; the library holds no threshold. */
+    estimate: Estimate;
+    interval: Interval | null;
+    tiers: TierCounts | null;
+    cost: {
+        perSolvedUsd: number | null;
+        basis: CostBasis;
+        receipts: number | null;
+    };
+    medianWallMs: number | null;
+    /** Null when the producer computed no frontier. */
+    onFront: boolean | null;
+}
+/** One task × setup cell. */
+interface MatrixCell {
+    task: string;
+    setup: string;
+    /** Attempts that count; null when the cell never ran. */
+    attempts: number | null;
+    /** Attempts that passed; null when no pass rule applies. */
+    solved: number | null;
+    /** Attempts graded on the App Grade ladder. */
+    tiers: TierCounts | null;
+    /** Attempts graded U: no floor check failed, but one could not be observed. */
+    unmeasured?: number;
+    /** Attempts whose grade failed an integrity check and awaits human review. */
+    flagged?: number;
+    /** A lens cell's mean score; null when the setup never scored the task. */
+    mean: number | null;
+    costUsd: number | null;
+}
+interface ComparisonRow {
+    /** Setup ids. */
+    favored: string;
+    other: string;
+    pairs: number | null;
+    minimumEffect: number | null;
+    /** The clustered interval on the difference, in the measure's units. */
+    interval: Interval | null;
+    /** The exact interval, drawn under the clustered one when present. */
+    exactInterval: Interval | null;
+}
+interface BreakdownInput {
+    reasons: string[];
+    setups: Array<{
+        id: string;
+        label: string;
+        n: number | null;
+    }>;
+    counts: Array<{
+        reason: string;
+        setup: string;
+        count: number | null;
+    }>;
+    excluded: {
+        count: number;
+        why: string;
+    } | null;
+    /** True when one attempt can count under several reasons. */
+    overlapping?: boolean;
+}
+/** Attempts left out of a figure, stated in its note. */
+interface Exclusion {
+    count: number;
+    why: string;
+}
+interface Figure {
+    id: string;
+    /** Generated from the input; no function accepts heading text. */
+    finding: string;
+    /** One quantified sentence. */
+    lede: string;
+    /** How to read the marks. */
+    read: string;
+    /** 720 px and 358 px renders; a null narrow render means the table is the phone view. */
+    svg: {
+        wide: string;
+        narrow: string | null;
+    };
+    /** An HTML table with every number the plot shows. */
+    table: string;
+    note: {
+        method: string;
+        n: string;
+        exclusions: string[];
+    };
+}
+interface Refusal {
+    id: string;
+    refused: string;
+}
+declare function isRefusal(value: Figure | Refusal): value is Refusal;
+
+/**
+ * The figure block: one markup for every figure on every surface.
+ *
+ * In order: the finding as a heading with a note reference, a one-sentence
+ * lede, the plot (both widths, swapped by `figure.css` on the figure's own
+ * width), a reading line, and the data table in a disclosure. Notes render
+ * once per page, numbered, each with a way back to its figure.
+ */
+
+declare function renderFigure(f: Figure, noteNumber: number): string;
+/** Numbered notes for `figures`, in the order their blocks were numbered (1-based). */
+declare function renderNotes(figures: Figure[]): string;
+/** What a page leaves out, and why. */
+declare function renderRefusals(refusals: Refusal[]): string;
+
+/**
+ * `breakdown`: why attempts fail.
+ *
+ * Rows are reasons (a failure layer, cause or check); columns are setups with
+ * `n=` under each name. Each cell prints its count over a neutral tint of
+ * count / n, capped at 50% so ink keeps its contrast. The accent never marks a
+ * failure. On a phone the table is the view.
+ *
+ * Refuses: a share without its column n (the count prints with no tint);
+ * counting excluded attempts (they are stated in the note); hiding a zero.
+ */
+
+interface BreakdownOptions {
+    /** What a row counts, lower case: "failed checks". */
+    measure: string;
+    id?: string;
+}
+declare function breakdown(input: BreakdownInput, o: BreakdownOptions): Figure | Refusal;
+
+/**
+ * `comparisonIntervals`: is each step in an order real.
+ *
+ * One row per comparison, "{favored} over {other}", with the pair count. x is
+ * the difference in points with a muted zero line. The clustered interval is a
+ * 6 px accent bar, the exact interval a 2 px muted bar under it, and a dashed
+ * ink tick marks the row's registered minimum effect. There is no point
+ * estimate, because the record carries none.
+ *
+ * Refuses: a row whose interval names no level or method, or that has no pair
+ * count or no registered minimum effect (each is listed in the note); the
+ * whole figure when no row can be drawn.
+ */
+
+interface ComparisonIntervalsOptions {
+    /** The measure the difference is in, lower case: "solve rate". */
+    measure: string;
+    id?: string;
+}
+declare function comparisonIntervals(rows: ComparisonRow[], setups: Setup[], o: ComparisonIntervalsOptions): Figure | Refusal;
+
+/**
+ * `costFrontier`: which setup gives the most passes per dollar.
+ *
+ * y is the measure on a fixed 0–1 axis. x is cost per pass on a log
+ * scale, reversed so cheaper sits right and better is always up and right. A
+ * point on the producer's frontier is an accent disc; any other point is a
+ * hollow muted circle, and an estimated cost is never a filled disc. An ink
+ * line joins frontier points. Every point is labelled directly; a label that
+ * collides everywhere becomes a number listed in the table. A setup with no
+ * pass or an unknown cost is listed under the axis, never placed at an
+ * origin a log axis does not have. On a phone the plot becomes a list sorted
+ * by the measure, with the same point marks, a rate bar and the cost as text.
+ *
+ * Refuses: the whole figure when fewer than two setups have a cost per pass; the frontier line unless two or more rows carry `onFront: true` (it
+ * never computes dominance itself).
+ */
+
+interface CostFrontierOptions {
+    /** The y measure, lower case: "solve rate". */
+    measure: string;
+    id?: string;
+}
+declare function costFrontier(rows: RateRow[], o: CostFrontierOptions): Figure | Refusal;
+
+/** The figure block and mark styles (src/figure.css), for documents that inline their CSS. */
+declare const figureCss: string;
+/** --chart-* resolved per theme, for documents without brand tokens: light, dark by preference or [data-theme="dark"], light in print. */
+declare const chartTokensCss: string;
+
+/**
+ * `rankedRates`: which setup passes most, and how uncertain is each rate.
+ *
+ * One row per setup: rank (only when every row is ranked), label, an accent
+ * bar on a shared 0–1 axis with the interval as an ink whisker, `passed/n`,
+ * cost per pass and median run. An App Grade grader adds a tier strip under
+ * the bar with a tick at the pass tier. Ranked rows keep their rank order;
+ * unranked rows sort by rate, and the finding says no comparison backs it.
+ *
+ * Refuses: a bar when the producer labels the estimate `none` or
+ * `insufficient` (the row prints its count only); a whisker whose interval
+ * names no level or method; a rank number unless every row carries one; any
+ * cost it was not given. It never prints "winner", "best" or "#1".
+ */
+
+interface RankedRatesOptions {
+    /** What the rate measures, lower case: "solve rate". */
+    measure: string;
+    /** The App Grade tier a pass needs; marks the tier strip. */
+    passTier?: Tier;
+    /** Singular, lower-case nouns: what one unit of `attempts` is, and what a row is. */
+    nouns?: {
+        attempt: string;
+        setup: string;
+    };
+    id?: string;
+    excluded?: Exclusion[];
+}
+declare function rankedRates(input: RateRow[], o: RankedRatesOptions): Figure | Refusal;
+
+/**
+ * `taskMatrix`: where each setup succeeds and fails.
+ *
+ * Rows are tasks in the given (registered) order; columns are setups in rank
+ * order when every setup is ranked, otherwise in the given order. Each cell
+ * draws one 12 px tile per attempt, best first, then `solved/attempts`.
+ * App Grade tiles fill by tier and F is an outline; U (unable to measure) is a
+ * dashed outline and an integrity-flagged grade is a struck outline. Runner
+ * verification fills solved tiles with the accent. A lens matrix (`show:
+ * "means"`) prints each mean with a bar on one shared scale.
+ *
+ * Refuses: a fill for an attempt without a grade (outline with a dot); a zero
+ * for a cell that never ran ("·"); counts that do not add up; any column order
+ * but the given rank.
+ */
+
+interface TaskMatrixOptions {
+    /** The App Grade tier a pass needs; named in the legend. */
+    passTier?: Tier;
+    /** "attempts" draws a tile per attempt; "means" draws one tinted cell per mean. */
+    show?: "attempts" | "means";
+    /** Singular, lower-case nouns for rows, columns and one attempt. */
+    nouns?: {
+        task: string;
+        setup: string;
+        attempt?: string;
+    };
+    /** The columns grade the same attempts (judges on one set of plants): the finding reports agreement. */
+    agreement?: boolean;
+    id?: string;
+    excluded?: Exclusion[];
+}
+declare function taskMatrix(tasks: string[], setupsIn: Setup[], cells: MatrixCell[], o?: TaskMatrixOptions): Figure | Refusal;
+
+export { type BreakdownInput, type BreakdownOptions, type ComparisonIntervalsOptions, type ComparisonRow, type CostBasis, type CostFrontierOptions, type Estimate, type Exclusion, type Figure, type Interval, type IntervalMethod, type MatrixCell, type RankedRatesOptions, type RateRow, type Refusal, type Setup, type TaskMatrixOptions, type Tier, type TierCounts, breakdown, chartTokensCss, comparisonIntervals, costFrontier, figureCss, isRefusal, rankedRates, renderFigure, renderNotes, renderRefusals, taskMatrix };