@vitest-agent/ui 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @vitest-agent/ui
+
+[![npm](https://img.shields.io/npm/v/@vitest-agent/ui?label=npm&color=cb3837)](https://www.npmjs.com/package/@vitest-agent/ui)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+> **Part of the [vitest-agent](https://vitest-agent.dev) ecosystem.** Most users want **[@vitest-agent/plugin](https://www.npmjs.com/package/@vitest-agent/plugin)**, which pulls this package in automatically. Install `@vitest-agent/ui` directly only if you build custom rendering on the primitives.
+
+Pure rendering primitives for vitest-agent. Owns the `RunEvent` reducer, the shape-tailored 12-cell dispatcher matrix, two render paths (agent string and React Ink tree), a PubSub channel for live event transport, and the synthesizers that bridge live Vitest data and stored reports into the event taxonomy. React and Ink are required peer dependencies.
+
+## Features
+
+- **Reducer** — pure `(state, event) => state` fold over the `RunEvent` discriminated union; `reduceRenderStateAll` for one-shot replay
+- **Dispatcher matrix** — `dispatch` and `dispatchInk` route a `DispatchInputs` to the matching `(RunShape, RunOutcome)` cell; `classifyRunShape` and `classifyOutcome` derive the coordinates
+- **Ink components** — `StreamApp` and the supporting primitives (`ModuleHeader`, `TestRow`, `CoverageBlock`, `TrendLine`, `FailureSection`, etc.) for live `stream`-mode frames
+- **PubSub channel** — `RunEventChannel` Effect tag and helpers (`accumulateUntilFinished`, `forEachRenderState`, `renderStateStream`) for live event transport
+- **Synthesizers** — `synthesizeRunEvents` from live Vitest modules; `synthesizeFromAgentReport` from a stored `AgentReport`
+- **Footer builder** — `buildFooter` assembles the L1 MCP-tool-pointer footer; `dominantClassification` picks the most actionable failure class
+
+## Install
+
+```bash
+npm install @vitest-agent/ui
+# or
+pnpm add @vitest-agent/ui
+```
+
+React and Ink are required peers:
+
+```bash
+npm install react ink
+```
+
+## Quick start
+
+```ts
+import { reduceRenderStateAll } from "@vitest-agent/ui";
+import { dispatch } from "@vitest-agent/ui";
+
+const state = reduceRenderStateAll(events);
+// state is a fully reduced RenderState
+
+const agentString = dispatch(buildDispatchInputs(state, input), opts);
+// agentString is the markdown-flavored final-frame string for the run
+```
+
+## Documentation
+
+Package reference at [vitest-agent.dev/ui](https://vitest-agent.dev/ui).
+
+## License
+
+[MIT](LICENSE)

package/dispatcher/cells/single-file-fail.js

@@ -0,0 +1,28 @@
+import { buildFooter } from "../footer.js";
+import { formatDisplayDuration } from "../../format-duration.js";
+import { formatFailure, soleModulePath } from "../helpers.js";
+import { renderAgentStringAsInk } from "../ink-helpers.js";
+
+//#region src/dispatcher/cells/single-file-fail.ts
+const DEFAULT_WIDTH = 80;
+const renderAgent = (inputs) => {
+	const modulePath = soleModulePath(inputs.state);
+	if (modulePath === void 0) return "";
+	const { passCount, failCount, skipCount, durationMs } = inputs.state.totals;
+	const parts = [`${passCount}/${passCount + failCount + skipCount} passed`];
+	if (failCount > 0) parts.push(`${failCount} failed`);
+	if (skipCount > 0) parts.push(`${skipCount} skipped`);
+	const sections = [`${modulePath}: ${parts.join(", ")} (${formatDisplayDuration(durationMs)})`];
+	if (inputs.state.failures.length > 0) {
+		sections.push("Failures:");
+		for (const failure of inputs.state.failures) sections.push(...formatFailure(failure, DEFAULT_WIDTH));
+	}
+	return `${sections.join("\n")}\n${buildFooter(inputs)}`;
+};
+const renderSingleFileFail = {
+	agent: renderAgent,
+	ink: (inputs) => renderAgentStringAsInk(renderAgent(inputs))
+};
+
+//#endregion
+export { renderSingleFileFail };

package/dispatcher/cells/single-file-pass.js

@@ -0,0 +1,19 @@
+import { buildFooter } from "../footer.js";
+import { formatDisplayDuration } from "../../format-duration.js";
+import { soleModulePath } from "../helpers.js";
+import { renderAgentStringAsInk } from "../ink-helpers.js";
+
+//#region src/dispatcher/cells/single-file-pass.ts
+const renderAgent = (inputs) => {
+	const modulePath = soleModulePath(inputs.state);
+	if (modulePath === void 0) return "";
+	const { passCount, durationMs } = inputs.state.totals;
+	return `${modulePath}: ${passCount} ${passCount === 1 ? "test" : "tests"} passed (${formatDisplayDuration(durationMs)})\n${buildFooter(inputs)}`;
+};
+const renderSingleFilePass = {
+	agent: renderAgent,
+	ink: (inputs) => renderAgentStringAsInk(renderAgent(inputs))
+};
+
+//#endregion
+export { renderSingleFilePass };

package/dispatcher/cells/single-file-threshold.js

@@ -0,0 +1,22 @@
+import { buildFooter } from "../footer.js";
+import { formatDisplayDuration } from "../../format-duration.js";
+import { formatCoverageJudgmentLine, soleModulePath } from "../helpers.js";
+import { renderAgentStringAsInk } from "../ink-helpers.js";
+
+//#region src/dispatcher/cells/single-file-threshold.ts
+const renderAgent = (inputs) => {
+	const modulePath = soleModulePath(inputs.state);
+	if (modulePath === void 0) return "";
+	const { passCount, durationMs } = inputs.state.totals;
+	const lines = [`${modulePath}: ${passCount} ${passCount === 1 ? "test" : "tests"} passed (${formatDisplayDuration(durationMs)})`];
+	const coverage = formatCoverageJudgmentLine(inputs.state);
+	if (coverage !== null) lines.push(coverage);
+	return `${lines.join("\n")}\n${buildFooter(inputs)}`;
+};
+const renderSingleFileThreshold = {
+	agent: renderAgent,
+	ink: (inputs) => renderAgentStringAsInk(renderAgent(inputs))
+};
+
+//#endregion
+export { renderSingleFileThreshold };

package/dispatcher/cells/single-project-fail.js

@@ -0,0 +1,34 @@
+import { buildFooter } from "../footer.js";
+import { formatFailure, formatTotals } from "../helpers.js";
+import { renderAgentStringAsInk } from "../ink-helpers.js";
+
+//#region src/dispatcher/cells/single-project-fail.ts
+const DEFAULT_WIDTH = 80;
+const renderAgent = (inputs) => {
+	const sections = [[formatTotals(inputs.state)]];
+	if (inputs.state.failures.length > 0) {
+		const failureLines = ["Failures:"];
+		for (const failure of inputs.state.failures) failureLines.push(...formatFailure(failure, DEFAULT_WIDTH));
+		sections.push(failureLines);
+	}
+	const moduleLines = ["Modules:"];
+	for (const path of inputs.state.moduleOrder) {
+		const m = inputs.state.modules[path];
+		if (!m) continue;
+		const parts = [];
+		if (m.passCount > 0) parts.push(`${m.passCount} passed`);
+		if (m.failCount > 0) parts.push(`${m.failCount} failed`);
+		if (m.skipCount > 0) parts.push(`${m.skipCount} skipped`);
+		const summary = parts.length > 0 ? parts.join(", ") : `status=${m.status}`;
+		moduleLines.push(`- ${m.modulePath}: ${summary}`);
+	}
+	if (moduleLines.length > 1) sections.push(moduleLines);
+	return `${sections.map((section) => section.join("\n")).join("\n\n")}\n${buildFooter(inputs)}`;
+};
+const renderSingleProjectFail = {
+	agent: renderAgent,
+	ink: (inputs) => renderAgentStringAsInk(renderAgent(inputs))
+};
+
+//#endregion
+export { renderSingleProjectFail };

package/dispatcher/cells/single-project-pass.js

@@ -0,0 +1,17 @@
+import { buildFooter } from "../footer.js";
+import { formatTotals } from "../helpers.js";
+import { renderAgentStringAsInk } from "../ink-helpers.js";
+
+//#region src/dispatcher/cells/single-project-pass.ts
+const renderAgent = (inputs) => {
+	const modules = inputs.state.moduleOrder.length;
+	const noun = modules === 1 ? "module" : "modules";
+	return `${[formatTotals(inputs.state), `${modules} ${noun} all-passed.`].join("\n\n")}\n${buildFooter(inputs)}`;
+};
+const renderSingleProjectPass = {
+	agent: renderAgent,
+	ink: (inputs) => renderAgentStringAsInk(renderAgent(inputs))
+};
+
+//#endregion
+export { renderSingleProjectPass };

package/dispatcher/cells/single-project-threshold.js

@@ -0,0 +1,25 @@
+import { buildFooter } from "../footer.js";
+import { formatBelowTargetTable, formatCoverageJudgmentLine, formatTotals, formatTrendLine } from "../helpers.js";
+import { renderAgentStringAsInk } from "../ink-helpers.js";
+
+//#region src/dispatcher/cells/single-project-threshold.ts
+const BELOW_TARGET_LIMIT = 5;
+const renderAgent = (inputs) => {
+	const sections = [[formatTotals(inputs.state)]];
+	const coverage = formatCoverageJudgmentLine(inputs.state);
+	const trend = formatTrendLine(inputs.trend);
+	const summaryLines = [];
+	if (coverage !== null) summaryLines.push(coverage);
+	if (trend !== null) summaryLines.push(trend);
+	if (summaryLines.length > 0) sections.push(summaryLines);
+	const below = formatBelowTargetTable(inputs.belowTarget, BELOW_TARGET_LIMIT);
+	if (below.length > 0) sections.push([...below]);
+	return `${sections.map((section) => section.join("\n")).join("\n\n")}\n${buildFooter(inputs)}`;
+};
+const renderSingleProjectThreshold = {
+	agent: renderAgent,
+	ink: (inputs) => renderAgentStringAsInk(renderAgent(inputs))
+};
+
+//#endregion
+export { renderSingleProjectThreshold };

package/dispatcher/cells/single-test-fail.js

@@ -0,0 +1,22 @@
+import { buildFooter } from "../footer.js";
+import { formatDisplayDuration } from "../../format-duration.js";
+import { formatFailure, formatTestName, soleTest } from "../helpers.js";
+import { renderAgentStringAsInk } from "../ink-helpers.js";
+
+//#region src/dispatcher/cells/single-test-fail.ts
+const DEFAULT_WIDTH = 80;
+const renderAgent = (inputs) => {
+	const test = soleTest(inputs.state);
+	if (test === void 0) return "";
+	const duration = test.durationMs ?? 0;
+	const header = `✗ ${formatTestName(test)} (${formatDisplayDuration(duration)})`;
+	const failure = inputs.state.failures[0];
+	return `${failure === void 0 ? `${header}\n` : `${header}\n${formatFailure(failure, DEFAULT_WIDTH).join("\n")}\n`}${buildFooter(inputs)}`;
+};
+const renderSingleTestFail = {
+	agent: renderAgent,
+	ink: (inputs) => renderAgentStringAsInk(renderAgent(inputs))
+};
+
+//#endregion
+export { renderSingleTestFail };

package/dispatcher/cells/single-test-pass.js

@@ -0,0 +1,19 @@
+import { buildFooter } from "../footer.js";
+import { formatDisplayDuration } from "../../format-duration.js";
+import { formatTestName, soleTest } from "../helpers.js";
+import { renderAgentStringAsInk } from "../ink-helpers.js";
+
+//#region src/dispatcher/cells/single-test-pass.ts
+const renderAgent = (inputs) => {
+	const test = soleTest(inputs.state);
+	if (test === void 0) return "";
+	const duration = test.durationMs ?? 0;
+	return `✓ ${formatTestName(test)} (${formatDisplayDuration(duration)})\n${buildFooter(inputs)}`;
+};
+const renderSingleTestPass = {
+	agent: renderAgent,
+	ink: (inputs) => renderAgentStringAsInk(renderAgent(inputs))
+};
+
+//#endregion
+export { renderSingleTestPass };

package/dispatcher/cells/single-test-threshold.js

@@ -0,0 +1,12 @@
+//#region src/dispatcher/cells/single-test-threshold.ts
+/**
+* No-op cell. The `single-test × threshold-violation` combination has
+* no observable difference from `single-test × all-pass` because a
+* single-test run never exercises the full file's coverage. The cell
+* exists so the dispatcher matrix is total; calling it falls through
+* to the empty string.
+*/
+const renderSingleTestThreshold = { agent: () => "" };
+
+//#endregion
+export { renderSingleTestThreshold };

package/dispatcher/cells/workspace-fail.js

@@ -0,0 +1,27 @@
+import { buildFooter } from "../footer.js";
+import { formatFailure, formatProjectsTable, formatTrendLine, formatWorkspaceTotal } from "../helpers.js";
+import { renderAgentStringAsInk } from "../ink-helpers.js";
+
+//#region src/dispatcher/cells/workspace-fail.ts
+const DEFAULT_WIDTH = 80;
+const renderAgent = (inputs) => {
+	const sections = [];
+	const projects = formatProjectsTable(inputs.projects);
+	if (projects.length > 0) sections.push([...projects]);
+	if (inputs.state.failures.length > 0) {
+		const failureLines = ["Failures:"];
+		for (const failure of inputs.state.failures) failureLines.push(...formatFailure(failure, DEFAULT_WIDTH));
+		sections.push(failureLines);
+	}
+	const trend = formatTrendLine(inputs.trend);
+	if (trend !== null) sections.push([trend]);
+	if (inputs.projects.length > 0) sections.push([formatWorkspaceTotal(inputs.projects)]);
+	return `${sections.map((section) => section.join("\n")).join("\n\n")}\n${buildFooter(inputs)}`;
+};
+const renderWorkspaceFail = {
+	agent: renderAgent,
+	ink: (inputs) => renderAgentStringAsInk(renderAgent(inputs))
+};
+
+//#endregion
+export { renderWorkspaceFail };

package/dispatcher/cells/workspace-pass.js

@@ -0,0 +1,25 @@
+import { buildFooter } from "../footer.js";
+import { formatCoverageJudgmentLine, formatProjectsTable, formatTrendLine, formatWorkspaceTotal } from "../helpers.js";
+import { renderAgentStringAsInk } from "../ink-helpers.js";
+
+//#region src/dispatcher/cells/workspace-pass.ts
+const renderAgent = (inputs) => {
+	const sections = [];
+	const projects = formatProjectsTable(inputs.projects);
+	if (projects.length > 0) sections.push([...projects]);
+	const summaryLines = [];
+	const coverage = formatCoverageJudgmentLine(inputs.state);
+	if (coverage !== null) summaryLines.push(coverage);
+	const trend = formatTrendLine(inputs.trend);
+	if (trend !== null) summaryLines.push(trend);
+	if (summaryLines.length > 0) sections.push(summaryLines);
+	if (inputs.projects.length > 0) sections.push([formatWorkspaceTotal(inputs.projects)]);
+	return `${sections.map((section) => section.join("\n")).join("\n\n")}\n${buildFooter(inputs)}`;
+};
+const renderWorkspacePass = {
+	agent: renderAgent,
+	ink: (inputs) => renderAgentStringAsInk(renderAgent(inputs))
+};
+
+//#endregion
+export { renderWorkspacePass };

package/dispatcher/cells/workspace-threshold.js

@@ -0,0 +1,28 @@
+import { buildFooter } from "../footer.js";
+import { formatBelowTargetTable, formatCoverageJudgmentLine, formatProjectsTable, formatTrendLine, formatWorkspaceTotal } from "../helpers.js";
+import { renderAgentStringAsInk } from "../ink-helpers.js";
+
+//#region src/dispatcher/cells/workspace-threshold.ts
+const BELOW_TARGET_LIMIT = 10;
+const renderAgent = (inputs) => {
+	const sections = [];
+	const projects = formatProjectsTable(inputs.projects);
+	if (projects.length > 0) sections.push([...projects]);
+	const summaryLines = [];
+	const coverage = formatCoverageJudgmentLine(inputs.state);
+	if (coverage !== null) summaryLines.push(coverage);
+	const trend = formatTrendLine(inputs.trend);
+	if (trend !== null) summaryLines.push(trend);
+	if (summaryLines.length > 0) sections.push(summaryLines);
+	const below = formatBelowTargetTable(inputs.belowTarget, BELOW_TARGET_LIMIT);
+	if (below.length > 0) sections.push([...below]);
+	if (inputs.projects.length > 0) sections.push([formatWorkspaceTotal(inputs.projects)]);
+	return `${sections.map((section) => section.join("\n")).join("\n\n")}\n${buildFooter(inputs)}`;
+};
+const renderWorkspaceThreshold = {
+	agent: renderAgent,
+	ink: (inputs) => renderAgentStringAsInk(renderAgent(inputs))
+};
+
+//#endregion
+export { renderWorkspaceThreshold };

package/dispatcher/classify.js

@@ -0,0 +1,48 @@
+//#region src/dispatcher/classify.ts
+/**
+* Compute the run shape from the reduced state plus the per-project
+* aggregates the plugin carries through `DispatchInputs.projects`.
+*
+* The classification follows the state-shape signal described in the
+* UI rewrite spec §7 open question 1:
+*
+* 1. More than one project → `workspace`.
+* 2. One module with exactly one test → `single-test`.
+* 3. One module with more than one test → `single-file`.
+* 4. Otherwise → `single-project`.
+*
+* @param state - the fully-reduced render state
+* @param projects - per-project summaries from the dispatch inputs
+* @returns the run shape classification
+* @public
+*/
+const classifyRunShape = (state, projects) => {
+	if (projects.length > 1) return "workspace";
+	const moduleEntries = Object.values(state.modules);
+	if (moduleEntries.length === 1) {
+		const sole = moduleEntries[0];
+		if (sole && sole.tests.length === 1) return "single-test";
+		return "single-file";
+	}
+	return "single-project";
+};
+/**
+* Compute the outcome class from the reduced state.
+*
+* Precedence: failures win over threshold violations. A run with one
+* failing test and a coverage gap classifies as `some-fail`; the
+* threshold-violation cell is reserved for runs where the test suite
+* itself is clean but coverage policy is not.
+*
+* @param state - the fully-reduced render state
+* @returns the outcome classification
+* @public
+*/
+const classifyOutcome = (state) => {
+	if (state.totals.failCount > 0) return "some-fail";
+	if (state.coverage !== null && state.coverage.violations.length > 0) return "threshold-violation";
+	return "all-pass";
+};
+
+//#endregion
+export { classifyOutcome, classifyRunShape };

package/dispatcher/dispatch.js

@@ -0,0 +1,73 @@
+import { renderSingleFileFail } from "./cells/single-file-fail.js";
+import { renderSingleFilePass } from "./cells/single-file-pass.js";
+import { renderSingleFileThreshold } from "./cells/single-file-threshold.js";
+import { renderSingleProjectFail } from "./cells/single-project-fail.js";
+import { renderSingleProjectPass } from "./cells/single-project-pass.js";
+import { renderSingleProjectThreshold } from "./cells/single-project-threshold.js";
+import { renderSingleTestFail } from "./cells/single-test-fail.js";
+import { renderSingleTestPass } from "./cells/single-test-pass.js";
+import { renderSingleTestThreshold } from "./cells/single-test-threshold.js";
+import { renderWorkspaceFail } from "./cells/workspace-fail.js";
+import { renderWorkspacePass } from "./cells/workspace-pass.js";
+import { renderWorkspaceThreshold } from "./cells/workspace-threshold.js";
+
+//#region src/dispatcher/dispatch.ts
+/**
+* The 4×3 cell table. Exported for the test harness so spy-based
+* routing tests can introspect the wiring without re-deriving it from
+* source.
+*
+* @public
+*/
+const dispatcherTable = {
+	"single-test": {
+		"all-pass": renderSingleTestPass,
+		"some-fail": renderSingleTestFail,
+		"threshold-violation": renderSingleTestThreshold
+	},
+	"single-file": {
+		"all-pass": renderSingleFilePass,
+		"some-fail": renderSingleFileFail,
+		"threshold-violation": renderSingleFileThreshold
+	},
+	"single-project": {
+		"all-pass": renderSingleProjectPass,
+		"some-fail": renderSingleProjectFail,
+		"threshold-violation": renderSingleProjectThreshold
+	},
+	workspace: {
+		"all-pass": renderWorkspacePass,
+		"some-fail": renderWorkspaceFail,
+		"threshold-violation": renderWorkspaceThreshold
+	}
+};
+/**
+* Dispatch to the cell that matches `(inputs.shape, inputs.outcome)`
+* and return its agent-half string output.
+*
+* @param inputs - the classified dispatch inputs
+* @param opts - cell rendering options
+* @returns the agent-string output for the matched cell
+* @public
+*/
+const dispatch = (inputs, opts) => {
+	return dispatcherTable[inputs.shape][inputs.outcome].agent(inputs, opts);
+};
+/**
+* Dispatch to the cell that matches `(inputs.shape, inputs.outcome)`
+* and return its Ink-half React tree. Returns `null` when the matched
+* cell does not expose an `ink` half — callers should fall back to
+* the agent string in that case.
+*
+* @param inputs - the classified dispatch inputs
+* @param opts - cell rendering options
+* @returns the Ink React element, or `null` when the cell has no Ink half
+* @public
+*/
+const dispatchInk = (inputs, opts) => {
+	const cell = dispatcherTable[inputs.shape][inputs.outcome];
+	return cell.ink !== void 0 ? cell.ink(inputs, opts) : null;
+};
+
+//#endregion
+export { dispatch, dispatchInk, dispatcherTable };

package/dispatcher/footer.js

@@ -0,0 +1,55 @@
+//#region src/dispatcher/footer.ts
+const FOOTER_COVERAGE_GAP = "Use `file_coverage` to find uncovered functions.";
+const FOOTER_FAILURE_PERSISTENT = "Use `test_errors` for failure detail; `failure_signature_get` to check known patterns.";
+const FOOTER_FAILURE_FLAKY = "Use `failure_signature_get` to confirm the flakiness signature.";
+const FOOTER_THRESHOLD = "Use `test_coverage` for the workspace coverage breakdown.";
+/**
+* Pick the dominant classification from a state's failure list.
+*
+* Priority order (most actionable first): `new-failure`, `persistent`,
+* `flaky`, `recovered`, `stable`. Returns `null` when the failure list
+* is empty or every failure is unclassified.
+*
+* @param state - the fully-reduced render state
+* @returns the most actionable classification, or `null` when none applies
+* @public
+*/
+const dominantClassification = (state) => {
+	if (state.failures.length === 0) return null;
+	const priority = [
+		"new-failure",
+		"persistent",
+		"flaky",
+		"recovered",
+		"stable"
+	];
+	const present = /* @__PURE__ */ new Set();
+	for (const f of state.failures) if (f.classification !== null) present.add(f.classification);
+	for (const cls of priority) if (present.has(cls)) return cls;
+	return null;
+};
+/**
+* Compose the trailing footer lines for a dispatcher cell. Returns an
+* empty string when no pointer applies. The footer starts with a
+* leading newline so cells can append it directly without crafting
+* their own separator.
+*
+* @param inputs - the classified dispatch inputs
+* @returns the footer string, or an empty string when no pointer applies
+* @public
+*/
+const buildFooter = (inputs) => {
+	const lines = [];
+	if (inputs.outcome === "all-pass" && inputs.belowTarget.length > 0) lines.push(FOOTER_COVERAGE_GAP);
+	if (inputs.outcome === "some-fail") {
+		const cls = dominantClassification(inputs.state);
+		if (cls === "new-failure" || cls === "persistent") lines.push(FOOTER_FAILURE_PERSISTENT);
+		else if (cls === "flaky") lines.push(FOOTER_FAILURE_FLAKY);
+	}
+	if (inputs.outcome === "threshold-violation") lines.push(FOOTER_THRESHOLD);
+	if (lines.length === 0) return "";
+	return `\n${lines.join("\n")}\n`;
+};
+
+//#endregion
+export { buildFooter, dominantClassification };