@tangle-network/charts 0.7.0 → 0.9.0

package/dist/timeline-CNHABOS1.d.ts

@@ -0,0 +1,293 @@
+//#region src/types.d.ts
+/**
+ * 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;
+  /** Wide and phone renders; vertical columns retain a readable minimum width. Null means the phone view uses the table. */
+  svg: {
+    wide: string;
+    narrow: string | null;
+    interactive?: boolean;
+  };
+  /** 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;
+//#endregion
+//#region src/axis.d.ts
+/** One column of an ordinal x axis. Points sit at a category's `at`; `weight` scales its width (default 1). */
+interface XCategory {
+  at: number;
+  label: string;
+  weight?: number;
+}
+/** A recorded goal on the y axis, such as a paper's bar: a band from `from` to `to`, or a line when they are equal. */
+interface YTarget {
+  from: number;
+  to: number;
+  label: string;
+  kind: "target" | "stretch";
+}
+/** A caller-named gridline, such as a check stage. */
+interface YTick {
+  at: number;
+  label: string;
+}
+type YScale = "linear" | "log";
+//#endregion
+//#region src/svg.d.ts
+/** Point shapes: the second channel that keeps series distinct without colour. */
+type MarkerShape = "circle" | "square" | "triangle" | "diamond";
+//#endregion
+//#region src/events.d.ts
+/**
+ * `pass` is solid, `deadline` dashed, `died` ends in a cross and `event` is dotted. `release`, `steer`, `ruling` and
+ * `wake` carry a head shape (diamond, triangle, square, circle), so every kind reads without colour.
+ */
+type MarkKind = "pass" | "deadline" | "died" | "event" | "release" | "steer" | "ruling" | "wake";
+/** A recorded verdict, such as a release tag's check: pass and fail take the status tones, unknown the muted tone. */
+type MarkVerdict = "pass" | "fail" | "unknown";
+interface ChartMark {
+  at: number;
+  label: string;
+  kind: MarkKind;
+  verdict?: MarkVerdict;
+  /** Who made the event, such as the operator or the keeper for a steer. Shown with the label and in the table. */
+  source?: string;
+  /** `timeline` only: the lane the event belongs to. It is drawn on that lane instead of across every lane. */
+  lane?: string;
+}
+/**
+ * `missing` is hatched: a span with no data is never drawn as zero. `blocked` is a system-wide wall, such as a quota
+ * window. `group` labels a run of positions in a header row above the data, such as one run's release tags, with a
+ * rule at each edge; a group may cover a single position (`from` equal to `to`).
+ */
+type BandKind = "after-pass" | "idle" | "missing" | "blocked" | "group";
+interface ChartBand {
+  from: number;
+  to: number;
+  label: string;
+  kind: BandKind;
+}
+//#endregion
+//#region src/points.d.ts
+/** A status glyph beside a mark: `check` for a solve, `cross` for a failing candidate. */
+type PointGlyph = "check" | "cross";
+interface PointFields {
+  /**
+   * A recorded verdict: `pass` draws a filled mark (solved, contract held), `fail` an outline (not solved, contract
+   * failed), `unknown` a dashed outline (undecided). A verdict with a null value is drawn in the strip under the plot.
+   */
+  verdict?: MarkVerdict;
+  /** How many recorded rows this mark stands for. Above 1 it carries a `×n` badge. */
+  count?: number;
+  /** Epoch milliseconds of the first and last recorded row, shown on hover and in the table. */
+  firstAt?: number;
+  lastAt?: number;
+  /** Whether the value can be compared with the goal: false is an outline with `*`, null (unknown) an outline with `?`. */
+  comparable?: boolean | null;
+  glyph?: PointGlyph;
+  /** This mark's shape, such as a diamond for a gate among circles for checks. Default: the series' shape. */
+  marker?: MarkerShape;
+  /** A short direct label beside the mark, such as `9/15`. */
+  label?: string;
+}
+//#endregion
+//#region src/outcomes.d.ts
+/**
+ * The fixed palettes every Discovery view shares: attempt outcomes (stack order) and check versions (checkers).
+ * The colours live once, as `--chart-outcome-*` and `--chart-checker-*` custom properties in `figure.css`, each a
+ * `light-dark()` pair chosen by the page's `color-scheme`. `node scripts/palette-check.mjs <validate_palette.js>`
+ * runs both palettes through the dataviz validator on the light surface and on #161616.
+ */
+/**
+ * How one recorded attempt ended. `ok` succeeded; every other outcome counts as failed. `lost` is a turn the
+ * platform lost without a kill (a sandbox that vanished), distinct from `oom`, a turn killed for memory.
+ */
+type TickOutcome = "ok" | "quota" | "lost" | "rate-limit" | "oom" | "refused" | "aborted" | "other";
+/**
+ * Outcomes in stack order. Adjacent outcomes pass the colour-vision checks in both themes in this order, so a stacked
+ * bar keeps it; `aborted` and `other` share the neutral tone and always carry a label. An attempt still running is
+ * `open` and is drawn hatched, never as an outcome.
+ */
+declare const OUTCOME_ORDER: readonly TickOutcome[];
+/** The CSS colour of each outcome, for a caller that paints its own marks (a legend, a stacked bar). */
+declare const OUTCOME_COLORS: Readonly<Record<TickOutcome, string>>;
+/** How many checkers have their own hue. Index 0 is the current checker; later indexes are older checkers. */
+declare const CHECKER_HUES = 4;
+/** The CSS colour of checker `index` (0 is current). Indexes past the fourth hue fold into the muted tone. */
+declare function checkerColor(index: number): string;
+//#endregion
+//#region src/timeline.d.ts
+/** Epoch milliseconds. `end: null` is an open span; it needs the figure's `now`. */
+interface TimelineSpan {
+  start: number;
+  end: number | null;
+  state: string;
+  note?: string;
+}
+/** One recorded attempt on a lane, such as a driver turn, at the time it ended. `note` (an error line) shows on hover. */
+interface TimelineTick {
+  at: number;
+  outcome: TickOutcome;
+  note?: string;
+}
+interface TimelineLane {
+  id: string;
+  label: string;
+  spans: TimelineSpan[];
+  /** The lane that started this one. The lane is drawn under its parent with a tree connector. */
+  parent?: string;
+  /** Tree depth: 0 for a root. Defaults to the parent's depth plus one, or 0 without a parent. */
+  depth?: number;
+  /** Recorded attempts, drawn as ticks with ok and failed counts at the lane's end. Omit when attempts are not recorded. */
+  ticks?: TimelineTick[];
+  /** Caller-composed facts, one per hover line on the lane and each of its spans: profile, model, status, attempts, cost, top error. */
+  detail?: string[];
+}
+interface TimelineOptions {
+  measure: string;
+  /**
+   * The recorded window; defaults to the extent of the data (spans, ticks and `now`). Spans, ticks and `now` must fall
+   * inside it. Marks outside it, such as a later deadline, are named at the edge they fall past; bands are clipped.
+   */
+  start?: number;
+  end?: number;
+  /** The time an open span is drawn to. Required when any span is open. */
+  now?: number;
+  marks?: ChartMark[];
+  bands?: ChartBand[];
+  /** States drawn hatched because their time has no data. Default: missing, untraced. */
+  hatch?: string[];
+  /** States drawn in the muted tone, such as idle. Default: idle. */
+  muted?: string[];
+  /**
+   * Lane ids whose subtrees are folded: descendants are hidden and the lane's ticks and counts include them. Passing
+   * it, even empty, makes each parent lane's label a fold toggle (`data-toggle`), which React `TimelineView` wires up.
+   * Ids that name no lane are ignored, so a fold state can outlive the lanes it was made for.
+   */
+  collapsed?: string[];
+  formatTime?: (ms: number) => string;
+  id?: string;
+}
+declare function timeline(lanes: TimelineLane[], o: TimelineOptions): Figure | Refusal;
+//#endregion
+export { IntervalMethod as A, BreakdownInput as C, Exclusion as D, Estimate as E, Tier as F, TierCounts as I, isRefusal as L, RateRow as M, Refusal as N, Figure as O, Setup as P, YTick as S, CostBasis as T, MarkVerdict as _, timeline as a, YScale as b, OUTCOME_ORDER as c, PointFields as d, PointGlyph as f, MarkKind as g, ChartMark as h, TimelineTick as i, MatrixCell as j, Interval as k, TickOutcome as l, ChartBand as m, TimelineOptions as n, CHECKER_HUES as o, BandKind as p, TimelineSpan as r, OUTCOME_COLORS as s, TimelineLane as t, checkerColor as u, MarkerShape as v, ComparisonRow as w, YTarget as x, XCategory as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/charts",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Static SVG and HTML figures for benchmarks and operational timing. Draws from producer data and refuses what it cannot draw honestly.",
   "type": "module",
   "license": "MIT",