static-fire 0.44.0 → 0.54.1

package/web/filter-menu.ts

@@ -1,15 +1,16 @@
 // The Results page's Filter menu and filter tags (#26), as plain data: which sections and values the menu lists,
 // what picking a value sets in the view query, what the search lists and which tags show. The page only draws it.
 // A config facet (Harness, Model, Effort, Profile) takes several values (#31): a pick adds or removes one value and
-// each picked value is its own tag. Judge, Grading version and Date range take one value: a pick replaces it.
+// each picked value is its own tag. Task, Judge, Grading version and Date range take one value: a pick replaces it.
+// Task (#81) is the task view: a task is picked here, not by a button on the page.
 import type { Facets, FacetValue } from "../src/core/facets";
 import { HARNESS_NAME } from "../src/core/label";
 import { CONFIG_FACETS, valueSet } from "../src/core/view-query";
 import type { ConfigFacet, ViewQuery } from "../src/core/view-query";
 
-export type SectionId = "harness" | "model" | "effort" | "profile" | "judge" | "grading" | "dates";
+export type SectionId = "task" | "harness" | "model" | "effort" | "profile" | "judge" | "grading" | "dates";
 export const SECTION_NAMES: Record<SectionId, string> = {
-  harness: "Harness", model: "Model", effort: "Effort", profile: "Profile", judge: "Judge", grading: "Grading version", dates: "Date range",
+  task: "Task", harness: "Harness", model: "Model", effort: "Effort", profile: "Profile", judge: "Judge", grading: "Grading version", dates: "Date range",
 };
 export const EFFORT_NONE = "No effort setting", PROFILE_NONE = "No Profile (user setup only)";
 
@@ -45,11 +46,15 @@ export interface MenuContext {
   facets: Facets | null; query: ViewQuery;
   /** The view's judge: set by the judge filter, or by a picked grading version. */
   judge: { id: string; label: string };
+  /** The title of every task in the project, in the project's order: the Task section lists them all. */
   titles: Record<string, string>;
 }
 
 export const CLEAR_ALL: Patch = { judge: undefined, grading: undefined, harness: undefined, model: undefined, effort: undefined, profile: undefined, since: undefined, until: undefined };
 
+/** What Clear all sets: every filter, and a picked task (back to the index). A suite pick is not a filter: it stays. */
+export const clearAll = (q: ViewQuery): Patch => (q.scope?.kind === "task" ? { ...CLEAR_ALL, scope: undefined } : CLEAR_ALL);
+
 const plural = (n: number, one: string) => `${n} ${one}${n === 1 ? "" : "s"}`;
 const short = (hash: string) => hash.slice(0, 8);
 const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
@@ -95,6 +100,15 @@ function facetSection(id: ConfigFacet, listed: FacetValue[], picked: string[]):
 /** Every section of the menu, in order, for the facets and the query in view. */
 export function menuSections({ facets, query, judge, titles }: MenuContext): MenuSection[] {
   const f = facets;
+  // Task: every task in the project. Picking one opens its task view; picking it again goes back to the index.
+  const taskPicked = query.scope?.kind === "task" ? query.scope.id : undefined;
+  const taskCounts = new Map((f?.scope.tasks ?? []).map((t) => [t.value, t.count]));
+  const taskIds = Object.keys(titles);
+  if (taskPicked && !taskIds.includes(taskPicked)) taskIds.push(taskPicked);   // a URL task the project does not list
+  const taskSection = section("task", taskIds.map((id): MenuValue => ({
+    section: "task", sectionName: SECTION_NAMES.task, key: id, label: titles[id] ?? id, count: taskCounts.get(id) ?? 0, picked: id === taskPicked,
+    set: { scope: { kind: "task", id }, suites: undefined }, clear: { scope: undefined },
+  })), { scope: undefined });
   const config = CONFIG_FACETS.map((k) => facetSection(k, f?.[k] ?? [], query[k] ?? []));
 
   // Judge: a picked grading version sets the view's judge, so that judge shows as picked.
@@ -133,12 +147,29 @@ export function menuSections({ facets, query, judge, titles }: MenuContext): Men
   const range = dateRangeText(query.since, query.until);
   const dates: MenuSection = { id: "dates", name: SECTION_NAMES.dates, summary: range ?? "Any date", picked: !!range, values: [], remove: { since: undefined, until: undefined } };
 
-  return [...config, judgeSection, gradingSection, dates];
+  return [taskSection, ...config, judgeSection, gradingSection, dates];
 }
 
 /** What picking `v` sets: the value, or without it when it is already picked. */
 export const pick = (v: MenuValue): Patch => (v.picked ? v.clear : v.set);
 
+/**
+ * The query after the page sets a grading pick (#80, DEC-019). The default set of suites has no exception for a
+ * picked grading version, and a new grading can change which configs have completed a suite, so on the index the
+ * pick also becomes an explicit suite pick: the suites in view (or the picked ones), and the first suite of the
+ * version's task when none of them has it. A view of one task needs no suite. `taskId` comes from the facets.
+ */
+export function withGradingPick(q: ViewQuery, taskId: string | undefined, suitesInView: string[], suites: { id: string; tasks: string[] }[]): ViewQuery {
+  if (!q.grading || q.scope?.kind === "task" || !taskId) return q;
+  const ids = new Set(q.suites?.length ? q.suites : suitesInView);
+  if (!suites.some((s) => ids.has(s.id) && s.tasks.includes(taskId))) {
+    const home = suites.find((s) => s.tasks.includes(taskId));
+    if (home) ids.add(home.id);
+  }
+  const picked = suites.filter((s) => ids.has(s.id)).map((s) => s.id);   // catalog order
+  return picked.length ? { ...q, scope: { kind: "index" }, suites: picked } : q;
+}
+
 /**
  * The search: every value of every section whose section name, name, task or detail line (a grading version's
  * judge) matches the text (case ignored), as one flat list; and whether the date range matches, so it shows as one entry.

package/web/how-it-works.tsx

@@ -0,0 +1,92 @@
+// The How it works page (#79): a short explanation of how Static Fire gets from a trial to a number, in the terms
+// of CONTEXT.md. Static text. Its sections and their order are HOW_IT_WORKS_SECTIONS (web/pages.ts), so another
+// page can link to one section, for example /how-it-works#left-out.
+import { useEffect, type ReactNode } from "react";
+import { HOW_IT_WORKS_SECTIONS, pathOf, type HowItWorksSection } from "./pages";
+
+const BODY: Record<HowItWorksSection, ReactNode> = {
+  trial: <>
+    <p>A <b>trial</b> is one run of one agent config on one task. The agent works in a new folder of its own, with
+      the task's prompt, its input files and its project files, and with your own setup, as it would in real work.
+      It writes its output to the path the task names. Then the output is graded.</p>
+    <p>A trial that could not run (the harness did not start, a login expired, it timed out) is <i>failed</i>. It
+      shows as a failure and is not in any mean.</p>
+  </>,
+  score: <>
+    <ul>
+      <li><b>Gates</b> are yes or no questions that every output must pass, for example "The output file exists". If
+        a gate fails, the task score is 0.</li>
+      <li>A <b>measure</b> is a group of criteria. Its score is the percent of its criteria that passed.</li>
+      <li>The <b>task score</b> is the mean of the measure scores, with each measure's weight (equal by default),
+        from 0 to 100.</li>
+      <li>The <b>Suite Index</b> is the mean task score over the tasks of a suite. A config gets one only when it
+        has a valid score on every task of the suite. Otherwise it is <i>partial</i>.</li>
+      <li>The <b>Agent Performance Index</b> is the mean Suite Index over the suites in view. It also needs a valid
+        score on every task of every suite in view.</li>
+    </ul>
+    <p>A point on a chart is the mean over every valid trial of that config in the view, from any batch, with a 95%
+      confidence interval.</p>
+  </>,
+  graders: <>
+    <p>Each criterion has one grader:</p>
+    <ul>
+      <li>A <b>check</b> is code. It gives the same answer every time: a pattern match, a word count, a field in the
+        file's front matter, or a command.</li>
+      <li>A <b>judge</b> is a model that reads the output and answers the question. The judge configuration in{" "}
+        <code>judges.yaml</code> sets which model it is. A judge does not use your own setup.</li>
+    </ul>
+    <p>A judge answers each question several times (3 by default). Each answer is a <b>vote</b>, with a pass or fail
+      and a reason. The criterion's score is the share of votes that passed, so 2 of 3 votes give 0.67.</p>
+    <p>When a grader cannot decide, its verdict is an error. That trial is left out of the means until a regrade
+      grades it again.</p>
+  </>,
+  levels: <>
+    <p>Each criterion has a level. It tells you how hard the criterion is meant to be:</p>
+    <ul>
+      <li><span className="tag floor">Floor</span> Most configurations should pass.</li>
+      <li><span className="tag strong">Strong</span> Good configurations pass.</li>
+      <li><span className="tag ceiling">Ceiling</span> Only the best configurations pass.</li>
+    </ul>
+    <p>The level does not change the score. A config that fails floor criteria is not ready for the work. Ceiling
+      criteria show which configs are the best.</p>
+  </>,
+  "left-out": <>
+    <p>A chart compares only trials that did the same job and were graded the same way. The Results page counts the
+      trials it leaves out, by reason:</p>
+    <ul>
+      <li><b>Another grading version.</b> The criteria, the references or the grading code changed after the trial
+        was graded. <i>What to do:</i> regrade, which uses judge calls only and runs no agent. Or pick the earlier
+        grading version in the Filter menu to see those trials as they were graded.</li>
+      <li><b>Another task version.</b> The prompt, the output path or the files the agent gets changed, so the
+        trial did a different job. A regrade cannot bring it in. <i>What to do:</i> switch to that version to see
+        its trials, or run new trials on the current one.</li>
+      <li><b>Another judge.</b> The trial was graded by a different judge, and the scores of two judges are never
+        mixed. <i>What to do:</i> pick that judge in the Filter menu, or regrade with the judge in view.</li>
+      <li><b>Not graded yet.</b> The trial has no finished grading. <i>What to do:</i> if its batch is still running,
+        wait. If not, regrade.</li>
+    </ul>
+  </>,
+};
+
+export function HowItWorksPage() {
+  // A link to one section opens the page there.
+  useEffect(() => { if (location.hash) document.getElementById(decodeURIComponent(location.hash.slice(1)))?.scrollIntoView(); }, []);
+  return (
+    <>
+      <section className="hero">
+        <div className="kicker">How it works</div>
+        <h1>From a trial to a number</h1>
+        <p className="page-sub">What each number on the Results page means. Each task's own questions are on the{" "}
+          <a href={pathOf("tasks")}>Tasks</a> page.</p>
+      </section>
+      <section className="card how-it-works">
+        {HOW_IT_WORKS_SECTIONS.map((s) => (
+          <section key={s.id} id={s.id} className="how-section">
+            <h2>{s.title}</h2>
+            {BODY[s.id]}
+          </section>
+        ))}
+      </section>
+    </>
+  );
+}

package/web/index-switches.ts

@@ -0,0 +1,29 @@
+// The index buttons of the Results page (#80): the suites in view are switches, and the title follows them.
+// Kept apart from app.tsx so the rules are tested without a browser.
+import type { Suite } from "../src/core/types";
+import type { Scope } from "../src/core/view-query";
+import { suiteHref, taskHref } from "./pages";
+
+/**
+ * The title of a view: the task's on a task view, the suite's when one suite is in view, else
+ * "Agent Performance Index". It never lists the suites, so it does not grow with them.
+ */
+export const viewTitle = (sel: Scope, suiteIds: string[], suites: Map<string, Suite>, taskTitle: (id: string) => string) =>
+  sel.kind === "task" ? taskTitle(sel.id) : suiteIds.length === 1 ? suites.get(suiteIds[0]!)?.title ?? suiteIds[0]! : "Agent Performance Index";
+
+/**
+ * The suites in view after a click on a suite's switch. On a task view it opens the index on that suite alone.
+ * Otherwise it turns the suite off when it is in view, else on. Null when the click would leave no suite in view.
+ */
+export function toggleSuite(sel: Scope, inView: string[], id: string, catalog: Suite[]): string[] | null {
+  if (sel.kind === "task") return [id];
+  const next = inView.includes(id) ? inView.filter((x) => x !== id) : [...inView, id];
+  return next.length ? catalog.map((s) => s.id).filter((x) => next.includes(x)) : null;
+}
+
+/**
+ * Where the title links (#81): a task view's title to the task's entry on the Tasks page, one suite's to the
+ * suite's entry. The Agent Performance Index over several suites is not a name, so it has no link.
+ */
+export const titleHref = (sel: Scope, suiteIds: string[]): string | null =>
+  sel.kind === "task" ? taskHref(sel.id) : suiteIds.length === 1 ? suiteHref(suiteIds[0]!) : null;

package/web/levels.tsx

@@ -0,0 +1,15 @@
+// A criterion's level where the dashboard shows one (#68), with the engine's names (DEC-014 of #71): a tag whose
+// tooltip says what it means, and a one-line legend next to a list of tags.
+
+const LEVEL_TEXT: Record<string, string> = { floor: "Floor", strong: "Strong", ceiling: "Ceiling" };
+/** What each level means. */
+export const LEVEL_MEANING: Record<string, string> = { floor: "most configurations should pass", strong: "good ones pass", ceiling: "only the best pass" };
+
+export const LevelTag = ({ level }: { level: string }) => (
+  <span className={`tag ${level}`} title={`${LEVEL_TEXT[level] ?? level}: ${LEVEL_MEANING[level] ?? ""}`}>{LEVEL_TEXT[level] ?? level}</span>
+);
+
+/** One line that says what the levels mean, next to where they are shown. */
+export const LevelLegend = () => (
+  <p className="level-legend"><span className="k">Levels</span>{Object.keys(LEVEL_TEXT).map((l) => <span key={l}><LevelTag level={l} /> {LEVEL_MEANING[l]}</span>)}</p>
+);

package/web/notices.ts

@@ -0,0 +1,74 @@
+// The words of the Results page's one alert and its details (#82, DEC-023): what a view does not show, why, and
+// what to do. Display only: which trials a view leaves out comes from the view (src/core/view.ts LeftOut), and
+// the regrade is the server's. The How it works page's #left-out section says the same in full.
+
+/** A count of trials not shown and of the configs they belong to. */
+export interface Counted { trials: number; configs: number }
+
+/** One item of the details: what is not shown and why, then what to do. */
+export interface NoticeItem { what: string; todo: string }
+
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** The alert's short count, for example "3 trials and 2 configs not shown". Null when nothing is left out. */
+export function alertText(trials: number, configs: number): string | null {
+  const parts = [trials ? plural(trials, "trial") : "", configs ? plural(configs, "config") : ""].filter(Boolean);
+  return parts.length ? `${parts.join(" and ")} not shown` : null;
+}
+
+const fromConfigs = (c: Counted) => `${plural(c.trials, "trial")} from ${plural(c.configs, "config")}`;
+
+/**
+ * Trials graded only under another grading version. `current`: every task in view is on its current version, so
+ * the view offers Regrade. `ungraded`: how many trials not graded yet the same Regrade button covers.
+ */
+export function gradingItem(c: Counted, { current, ungraded }: { current: boolean; ungraded: number }): NoticeItem {
+  const them = c.trials === 1 ? "it" : "them", their = c.trials === 1 ? "its" : "their";
+  return {
+    what: `${fromConfigs(c)} ${c.trials === 1 ? "was" : "were"} graded under ${current ? "earlier" : "other"} criteria or by another judge.`,
+    todo: current
+      ? `Regrade ${them} with the button below${ungraded ? " (it also grades the trials not graded yet)" : ""}, or pick ${their} grading version in the Filter menu.`
+      : `Pick ${their} grading version in the Filter menu.`,
+  };
+}
+
+/** Trials with no finished grading. `otherGrading`: how many trials of the other item the same button covers. */
+export function ungradedItem(c: Counted, { current, otherGrading }: { current: boolean; otherGrading: number }): NoticeItem {
+  const one = c.trials === 1;
+  const wait = `If ${one ? "its" : "their"} batch is still running, wait.`;
+  return {
+    what: `${fromConfigs(c)} ${one ? "is" : "are"} not graded yet.`,
+    todo: current
+      ? `${wait} If not, regrade ${one ? "it" : "them"} with the ${otherGrading ? "same button below: one regrade covers both lists" : "button below"}.`
+      : wait,
+  };
+}
+
+/** Under the Regrade button: what it does, and no more (#80: with nothing picked, it covers the suites in view only). */
+export function regradeNote(trials: number, suitesLeftOut: boolean): string {
+  return `Judge calls only. It grades the ${plural(trials, "trial")} above again and runs no agent.${suitesLeftOut ? " Suites left out of the index are not regraded." : ""}`;
+}
+
+/** A config the chart cannot plot: the suites in view it has not completed, and its score (null: no valid score). */
+export interface NotPlotted { label: string; partial: { suite: string; have: number; of: number }[]; score: number | null }
+
+/** The configs the chart cannot plot, under one reason. */
+export interface NotPlottedGroup { why: string; configs: string[]; todo: string }
+
+/**
+ * The configs the chart cannot plot, grouped by reason: one group per suite they have not completed (in the order
+ * met), then no valid score, then no cost data (a score but no cost). A config partial in two suites is in both.
+ */
+export function notPlottedGroups(list: NotPlotted[]): NotPlottedGroup[] {
+  const suites = new Map<string, string[]>();
+  const noScore: string[] = [], noCost: string[] = [];
+  for (const c of list) {
+    if (c.partial.length) for (const p of c.partial) suites.set(p.suite, [...(suites.get(p.suite) ?? []), `${c.label} (${p.have} of ${p.of} tasks)`]);
+    else (c.score == null ? noScore : noCost).push(c.label);
+  }
+  return [
+    ...[...suites].map(([suite, configs]) => ({ why: `No score on every task of ${suite}`, configs, todo: "Run the tasks they miss." })),
+    ...(noScore.length ? [{ why: "No valid score", configs: noScore, todo: "Open their trials to see why." }] : []),
+    ...(noCost.length ? [{ why: "No cost data", configs: noCost, todo: "Check the costs in pricing.yaml." }] : []),
+  ];
+}

package/web/output-view.ts

@@ -0,0 +1,61 @@
+// How the trial drawer shows a trial's output (#68). An output is agent output and is not trusted (DEC-012 of #71):
+// it never goes into the dashboard's own page. An HTML page runs in a sandboxed frame that may run the page's own
+// scripts but has an opaque origin, so it cannot read or change the dashboard or run code on its origin. Markdown and
+// other text are rendered into a frame that runs no code at all. The API refuses changes from such a frame
+// (src/api.ts), since a sandboxed page can still send a request.
+
+export type OutputKind = "image" | "html" | "markdown" | "text";
+
+/**
+ * How to show an output: by the server's media type for an image, else by the extension of the task's output path.
+ * Text that is neither HTML nor Markdown is shown as Markdown, as before, but named "text" so its second view is "Source".
+ */
+export function outputKind(outputPath: string, contentType: string | null): OutputKind {
+  if (contentType?.startsWith("image/")) return "image";
+  const ext = /\.([^./\\]+)$/.exec(outputPath)?.[1]?.toLowerCase();
+  return ext === "html" || ext === "htm" ? "html" : ext === "md" || ext === "markdown" ? "markdown" : "text";
+}
+
+/** The name of the second view, which shows the output's text as it is. */
+export const sourceLabel = (kind: OutputKind) => (kind === "markdown" ? "Markdown" : "Source");
+
+/** The HTML frame may run the page's own scripts. No allow-same-origin, forms, popups, modals or top navigation. */
+export const HTML_SANDBOX = "allow-scripts";
+/** The Markdown and text frame runs no code. */
+export const PROSE_SANDBOX = "";
+
+/** The rendered Markdown's frame loads only its styles and the dashboard's fonts: no script, image, frame or request. */
+const PROSE_POLICY = "default-src 'none'; style-src 'unsafe-inline' https://fonts.googleapis.com; font-src https://fonts.gstatic.com";
+const FONTS = "https://fonts.googleapis.com/css2?family=Hanken+Grotesk:wght@400..900&family=IBM+Plex+Mono:wght@400;500;600&display=swap";
+
+/** The dashboard's tokens the prose styles use; their values are read from the dashboard's page (web/brand). */
+export const PROSE_TOKENS = [
+  "--fg", "--fg-2", "--outline", "--color-sky", "--surface", "--line", "--accent", "--outline-width", "--radius-xs", "--spacing-12", "--spacing-16", "--spacing-24",
+  "--font-text", "--font-heading", "--font-mono", "--weight-heading-card", "--leading-text", "--text-sm",
+] as const;
+
+const PROSE_CSS = `
+html, body { margin: 0; background: transparent; color: var(--fg); font-family: var(--font-text); font-size: 15px; line-height: var(--leading-text); -webkit-font-smoothing: antialiased; }
+.prose { line-height: 1.65; max-width: 680px; padding: var(--spacing-16) var(--spacing-16) var(--spacing-24); }
+.prose h1, .prose h2, .prose h3 { font-family: var(--font-heading); font-weight: var(--weight-heading-card); letter-spacing: -0.02em; line-height: 1.15; }
+.prose code { font-family: var(--font-mono); font-size: 0.9em; background: var(--surface); padding: 1px 5px; border-radius: 6px; }
+.prose pre { background: var(--surface); border: var(--outline-width) solid var(--line); padding: var(--spacing-12); border-radius: var(--radius-xs); overflow-x: auto; }
+.prose pre code { background: none; padding: 0; }
+.prose blockquote { border-left: 4px solid var(--accent); margin: 0; padding-left: var(--spacing-16); color: var(--fg-2); }
+.prose img { display: none; }
+.prose table { font-size: var(--text-sm); border-collapse: collapse; }
+.prose td, .prose th { border: 1px solid var(--line); padding: 4px 8px; }
+.img-ph { display: inline-block; background: var(--color-sky); border: var(--outline-width) dashed var(--outline); border-radius: var(--radius-xs); padding: 2px 8px; font-size: var(--text-sm); }
+`;
+
+/**
+ * The document for the Markdown and text frame: its policy first, so the output cannot loosen it, then the prose
+ * styles with the dashboard's token values, then the rendered output. A token value that could end the style
+ * element is left out.
+ */
+export function proseDoc(html: string, tokens: Record<string, string>): string {
+  const vars = Object.entries(tokens).filter(([, v]) => !/[<>{};]/.test(v)).map(([k, v]) => `${k}: ${v};`).join(" ");
+  return `<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="${PROSE_POLICY}">`
+    + `<link rel="stylesheet" href="${FONTS}"><style>:root { ${vars} }${PROSE_CSS}</style></head>`
+    + `<body><div class="prose">${html}</div></body></html>`;
+}

package/web/pages.ts

@@ -5,6 +5,8 @@ export const PAGES = [
   { id: "results", path: "/", title: "Results" },
   { id: "runs", path: "/runs", title: "Runs" },
   { id: "compare", path: "/compare", title: "Compare" },
+  { id: "tasks", path: "/tasks", title: "Tasks" },
+  { id: "how", path: "/how-it-works", title: "How it works" },
 ] as const;
 
 export type PageId = (typeof PAGES)[number]["id"];
@@ -14,3 +16,27 @@ export const pageOf = (pathname: string): PageId =>
   PAGES.find((p) => p.path === (pathname.replace(/\/+$/, "") || "/"))?.id ?? "results";
 
 export const pathOf = (id: PageId): string => PAGES.find((p) => p.id === id)!.path;
+
+// Addresses inside a page, so another page can link to one entry (#79). An entry's element id is its fragment.
+/** The element id of a suite on the Tasks page. */
+export const suiteAnchor = (id: string) => `suite-${id}`;
+/** The element id of a task on the Tasks page. */
+export const taskAnchor = (id: string) => `task-${id}`;
+/** The address of a suite on the Tasks page: `/tasks#suite-<id>`. */
+export const suiteHref = (id: string) => `${pathOf("tasks")}#${encodeURIComponent(suiteAnchor(id))}`;
+/** The address of a task on the Tasks page: `/tasks#task-<id>`. */
+export const taskHref = (id: string) => `${pathOf("tasks")}#${encodeURIComponent(taskAnchor(id))}`;
+
+/** The sections of the How it works page, in reading order. A section's address is `/how-it-works#<id>`. */
+export const HOW_IT_WORKS_SECTIONS = [
+  { id: "trial", title: "A trial" },
+  { id: "score", title: "How a score is made" },
+  { id: "graders", title: "Checks and judges" },
+  { id: "levels", title: "Levels" },
+  { id: "left-out", title: "Why trials are left out of a chart" },
+] as const;
+
+export type HowItWorksSection = (typeof HOW_IT_WORKS_SECTIONS)[number]["id"];
+
+/** The address of a section of the How it works page, for example `/how-it-works#left-out`. */
+export const howItWorksHref = (section: HowItWorksSection) => `${pathOf("how")}#${section}`;

package/web/styles.css

@@ -19,7 +19,7 @@ code { font-family: var(--font-mono); font-size: 0.9em; }
 .spacer { flex: 1; }
 
 /* page navigation (#24): one pill per page, the current one filled */
-.nav { display: flex; gap: var(--spacing-4, 4px); }
+.nav { display: flex; flex-wrap: wrap; gap: var(--spacing-4, 4px); }
 .nav a { font-weight: 800; color: var(--fg-3); text-decoration: none; border: var(--outline-width) solid transparent; border-radius: var(--radius-pill); padding: 4px var(--spacing-16); }
 .nav a:hover { color: var(--fg); }
 .nav a.on { color: var(--fg); background: var(--accent); border-color: var(--outline); }
@@ -36,6 +36,8 @@ select, .btn, input[type="number"] { border: var(--outline-width) solid var(--ou
 /* hero */
 .hero { margin-bottom: var(--spacing-24); }
 .hero h1 { font-family: var(--font-display); font-weight: var(--weight-display); letter-spacing: var(--tracking-display); line-height: var(--leading-display); font-size: clamp(2rem, 5vw, var(--text-5xl)); margin: var(--spacing-8) 0 var(--spacing-12); }
+.hero h1 .title-link { color: inherit; text-decoration: none; }
+.hero h1 .title-link:hover, .hero h1 .title-link:focus-visible { text-decoration: underline; text-decoration-thickness: 3px; text-underline-offset: 6px; }
 .meta { display: flex; flex-wrap: wrap; gap: var(--spacing-8) var(--spacing-24); color: var(--fg-3); font-size: var(--text-sm); margin-bottom: var(--spacing-16); }
 .meta b { color: var(--fg); }
 .progress { display: flex; align-items: center; gap: var(--spacing-12); }
@@ -99,6 +101,7 @@ select, .btn, input[type="number"] { border: var(--outline-width) solid var(--ou
 .grid3 .card { margin-bottom: 0; }
 @media (max-width: 900px) { .grid3 { grid-template-columns: 1fr; } }
 .note { color: var(--fg-3); font-size: var(--text-sm); margin: var(--spacing-12) 0 0; }
+.note.coverage { margin: 0 0 var(--spacing-8); }   /* the one line under the index buttons: what the index covers (#80) */
 .empty { text-align: center; padding: var(--spacing-64) var(--spacing-24); }
 .empty .kicker { justify-content: center; }
 .empty h1 { font-family: var(--font-display); font-weight: var(--weight-display); letter-spacing: var(--tracking-display); font-size: var(--text-4xl); margin: var(--spacing-8) 0; }
@@ -179,11 +182,21 @@ td.q .tag { margin-left: var(--spacing-8); }
 .drawer { position: fixed; top: 0; right: 0; bottom: 0; width: min(1120px, 100vw); background: var(--ground); border-left: var(--outline-width) solid var(--outline); z-index: 11; display: flex; flex-direction: column; }
 .drawer-head { padding: var(--spacing-16) var(--spacing-24); border-bottom: var(--outline-width) solid var(--outline); display: flex; align-items: flex-start; gap: var(--spacing-12); background: var(--raised); }
 .drawer-head h2 { font-family: var(--font-heading); font-weight: var(--weight-heading); letter-spacing: var(--tracking-heading); font-size: var(--text-2xl); margin: 4px 0 0; }
-.drawer-body { flex: 1; overflow: hidden; display: grid; grid-template-columns: minmax(0, 1.2fr) minmax(0, 1fr); }
-@media (max-width: 800px) { .drawer-body { grid-template-columns: 1fr; overflow-y: auto; } .drawer-body > div { overflow: visible !important; } }
-.drawer-body > div { overflow-y: auto; padding: var(--spacing-24); }
-.drawer-body > div + div { border-left: var(--outline-width) solid var(--line); background: var(--surface); }
-.drawer-body h3 { font-family: var(--font-heading); font-weight: var(--weight-heading); letter-spacing: var(--tracking-heading); font-size: var(--text-xl); margin: 0 0 var(--spacing-12); }
+/* Three tabs under the head (#68); each panel takes the drawer's whole width and scrolls on its own. */
+.drawer-tabs { display: flex; gap: var(--spacing-4, 4px); padding: var(--spacing-8) var(--spacing-24) 0; border-bottom: var(--outline-width) solid var(--outline); background: var(--raised); }
+.drawer-tab { border: var(--outline-width) solid transparent; border-bottom: none; background: none; border-radius: var(--radius-xs) var(--radius-xs) 0 0; padding: var(--spacing-8) var(--spacing-16); font-weight: 800; color: var(--fg-3); margin-bottom: calc(-1 * var(--outline-width)); }
+.drawer-tab:hover { color: var(--fg); }
+.drawer-tab.on { color: var(--fg); background: var(--ground); border-color: var(--outline); }
+.drawer-panel { flex: 1; min-height: 0; overflow-y: auto; padding: var(--spacing-24); }
+.drawer-panel.output { display: flex; flex-direction: column; }
+.drawer-panel.output > * { flex-shrink: 0; }
+/* An output in a sandboxed frame (web/output-view.ts): it fills the rest of the panel, like a browser window. */
+.output-frame { display: block; width: 100%; flex: 1 0 480px !important; border: var(--outline-width) solid var(--outline); border-radius: var(--radius-xs); background: #fff; }
+.output-frame.prose-frame { background: var(--ground); border-color: var(--line); }
+.level-legend { display: flex; flex-wrap: wrap; align-items: center; gap: var(--spacing-8) var(--spacing-16); font-size: var(--text-sm); color: var(--fg-2); margin: 0 0 var(--spacing-16); }
+.level-legend .k { font-family: var(--font-kicker); font-weight: var(--weight-kicker); text-transform: uppercase; letter-spacing: var(--tracking-kicker); font-size: 11px; color: var(--fg-3); }
+.level-legend .tag { margin-left: 0; }
+.drawer-panel h3 { font-family: var(--font-heading); font-weight: var(--weight-heading); letter-spacing: var(--tracking-heading); font-size: var(--text-xl); margin: 0 0 var(--spacing-12); }
 .stats { display: flex; gap: var(--spacing-24); flex-wrap: wrap; margin-top: var(--spacing-8); }
 .stat .k { color: var(--fg-3); font-size: 12px; }
 .stat .v { font-size: var(--text-lg); font-weight: 800; font-variant-numeric: tabular-nums; }
@@ -191,16 +204,7 @@ td.q .tag { margin-left: var(--spacing-8); }
 .tabs { display: flex; gap: 6px; margin-bottom: var(--spacing-16); }
 .tab { border: var(--outline-width) solid var(--outline); background: var(--raised); border-radius: var(--radius-pill); padding: 2px var(--spacing-12); font-size: var(--text-sm); font-weight: 700; }
 .tab.on { background: var(--accent); }
-.prose { line-height: 1.65; max-width: 680px; }
-.prose h1, .prose h2, .prose h3 { font-family: var(--font-heading); font-weight: var(--weight-heading-card); letter-spacing: -0.02em; line-height: 1.15; }
-.prose code { background: var(--surface); padding: 1px 5px; border-radius: 6px; }
-.prose pre { background: var(--surface); border: var(--outline-width) solid var(--line); padding: var(--spacing-12); border-radius: var(--radius-xs); overflow-x: auto; }
-.prose pre code { background: none; padding: 0; }
-.prose blockquote { border-left: 4px solid var(--accent); margin: 0; padding-left: var(--spacing-16); color: var(--fg-2); }
-.prose img { display: none; }
-.prose table { font-size: var(--text-sm); }
-.prose td, .prose th { border: 1px solid var(--line); }
-/* An image output in the trial drawer: never wider than the drawer column. */
+/* An image output in the trial drawer: never wider than the drawer. The rendered Markdown is styled in its frame (web/output-view.ts). */
 .output-image { display: block; max-width: 100%; height: auto; border: var(--outline-width) solid var(--outline); border-radius: var(--radius-xs); }
 pre.raw { white-space: pre-wrap; font-family: var(--font-mono); font-size: 12.5px; }
 .verdict-group { margin-bottom: var(--spacing-24); }
@@ -245,7 +249,6 @@ pre.raw { white-space: pre-wrap; font-family: var(--font-mono); font-size: 12.5p
 .envelope { background: var(--surface); border: var(--outline-width) solid var(--outline); border-radius: var(--radius-sm); padding: var(--spacing-12) var(--spacing-16); margin-bottom: var(--spacing-16); font-size: var(--text-sm); }
 .envelope .k { font-family: var(--font-kicker); font-weight: var(--weight-kicker); text-transform: uppercase; letter-spacing: var(--tracking-kicker); font-size: 11px; color: var(--fg-3); margin-top: 4px; }
 .envelope .subject { font-weight: 800; font-size: var(--text-lg); }
-.img-ph { display: inline-block; background: var(--color-sky); border: var(--outline-width) dashed var(--outline); border-radius: var(--radius-xs); padding: 2px var(--spacing-8); font-size: var(--text-sm); }
 
 /* batches panel (#13) */
 .batches { margin-bottom: var(--spacing-24); }
@@ -277,15 +280,26 @@ pre.raw { white-space: pre-wrap; font-family: var(--font-mono); font-size: 12.5p
 .status.done { color: var(--fg); }
 .status.failed, .status.invalid { font-weight: 700; }
 
-/* left-out notice (under the chart) */
-.left-out { margin-top: var(--spacing-12); }
-.left-out .btn-quiet { margin-top: var(--spacing-8); }
-.left-out .error { margin-top: var(--spacing-8); }
-.empty .left-out { text-align: left; max-width: 72ch; margin: var(--spacing-24) auto 0; }
+/* the one alert in the chart card (#82): a button, and details that float over the page so the card does not grow */
+.notice { position: relative; margin-top: var(--spacing-12); }
+.notice-btn { display: inline-flex; align-items: center; gap: var(--spacing-8); font: inherit; font-size: var(--text-sm); font-weight: 700; color: var(--fg); background: var(--color-cream); border: var(--outline-width) solid var(--outline); border-radius: var(--radius-sm); padding: 4px var(--spacing-12); cursor: pointer; }
+.notice-btn:hover, .notice-btn.on { background: var(--surface); }
+.notice-btn:focus-visible { outline: 2px solid var(--fg); outline-offset: 2px; }
+.notice-more { font-weight: 400; color: var(--fg-3); text-decoration: underline; }
+.notice-details { position: absolute; z-index: 20; top: calc(100% + 8px); left: 0; width: min(560px, calc(100vw - 32px)); max-height: min(60vh, 520px); overflow: auto; box-sizing: border-box; background: var(--raised); border: var(--outline-width) solid var(--outline); border-radius: var(--radius-sm); box-shadow: var(--shadow-md); padding: var(--spacing-12) var(--spacing-16); font-size: var(--text-sm); text-align: left; }
+.notice-details > ul { margin: 0; padding-left: 1.2em; display: grid; gap: var(--spacing-8); }
+.notice-details .notice-action { list-style: none; margin-left: -1.2em; }
+.notice-details .notice-action .btn-quiet { margin-top: 0; }
+.notice-details .notice-action .note { margin-top: 4px; }
+.notice-details .error { margin-top: 4px; }
+.notice-groups { margin: 4px 0; padding-left: 1.2em; }
+.notice-how { display: inline-block; margin-top: var(--spacing-12); color: var(--fg); }
+.empty .notice { text-align: left; max-width: 72ch; margin: var(--spacing-24) auto 0; }
 .linkish { background: none; border: 0; padding: 0; font: inherit; color: var(--fg); text-decoration: underline; cursor: pointer; }
 
 /* chart card: Chart / Table toggle and the config table */
 .card-head { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: var(--spacing-8) var(--spacing-16); }
+.card-head .task-menu { max-width: 360px; font-weight: 700; font-size: var(--text-sm); }
 .view-toggle { display: inline-flex; border: var(--outline-width) solid var(--outline); border-radius: var(--radius-pill); overflow: hidden; background: var(--raised); }
 .view-toggle button { font: inherit; font-weight: 700; font-size: var(--text-sm); color: var(--fg); border: 0; background: transparent; padding: 4px var(--spacing-16); cursor: pointer; }
 .view-toggle button + button { border-left: var(--outline-width) solid var(--outline); }
@@ -331,3 +345,24 @@ table.configs .why { color: var(--fg-3); font-size: 12px; margin-top: 2px; }
 .run-status .mini { flex: none; width: 70px; height: 7px; border: 1.5px solid var(--outline); border-radius: 4px; overflow: hidden; background: var(--raised); }
 .run-status .mini b { display: block; height: 100%; background: var(--color-sun); transition: width .4s ease; }
 .run-status-count { white-space: nowrap; font-variant-numeric: tabular-nums; }
+
+/* Tasks and How it works pages (#79) */
+.page-sub { color: var(--fg-3); margin: 0; max-width: 72ch; }
+.task-entry { padding-top: var(--spacing-24); margin-top: var(--spacing-24); border-top: 2px solid var(--line); scroll-margin-top: var(--spacing-16); }
+.task-entry h3 { font-size: var(--text-xl); }
+.task-entry h4 { font-size: var(--text-sm); text-transform: uppercase; letter-spacing: var(--tracking-kicker); color: var(--fg-3); margin: var(--spacing-16) 0 var(--spacing-8); }
+.task-version { font-size: var(--text-sm); font-weight: 500; }
+.task-desc { margin: var(--spacing-4, 4px) 0 0; max-width: 72ch; }
+.task-prompt { white-space: pre-wrap; font-family: var(--font-mono); font-size: 13px; background: var(--surface); border: 1.5px solid var(--line); border-radius: var(--radius-xs); padding: var(--spacing-12); margin: 0; max-width: 90ch; }
+.task-facts { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: 6px var(--spacing-16); margin: var(--spacing-12) 0 0; font-size: var(--text-sm); }
+.task-facts dt { font-weight: 700; color: var(--fg-3); }
+.task-facts dd { margin: 0; display: flex; flex-wrap: wrap; gap: 4px var(--spacing-8); overflow-wrap: anywhere; }
+.task-criteria td.question { text-align: left; }
+.task-criteria .group-note { text-transform: none; letter-spacing: 0; font-family: var(--font-text); font-weight: 500; }
+.task-suite, .how-section { scroll-margin-top: var(--spacing-16); }
+.how-it-works { max-width: 80ch; }
+.how-section + .how-section { margin-top: var(--spacing-24); padding-top: var(--spacing-16); border-top: 2px solid var(--line); }
+.how-section p, .how-section li { line-height: 1.55; }
+.how-section ul { padding-left: var(--spacing-24); }
+.how-section li + li { margin-top: 6px; }
+.how-section .tag { margin: 0 var(--spacing-8) 0 0; }

package/web/task-card.ts

@@ -0,0 +1,6 @@
+// The per-task cards of the Results page (#81, DEC-022 of #71): "Where the points come from" and "Trials" are
+// one card each, with a menu of the tasks in view, so the page does not grow with the number of tasks.
+
+/** The task a card shows: the picked one while it is in view, else the first task in view. */
+export const shownTask = (taskIds: string[], picked: string | null): string | null =>
+  picked && taskIds.includes(picked) ? picked : taskIds[0] ?? null;