@inflexa-ai/harness 0.17.0 → 0.19.0

package/dist/report-render/render.js

@@ -0,0 +1,125 @@
+/**
+ * The page walk: the document walk, the value-map validation, and the problem collection.
+ *
+ * `renderReportPage` walks the sections in document order. It dispatches each block to its kind renderer,
+ * and it validates the bound value against the shape that the block needs. A missing entry, or an entry of
+ * the wrong shape, becomes one typed problem. The walk collects every problem, thus one render reports each
+ * fault at one time. A page with no problem assembles to one HTML string.
+ *
+ * One shared `ReferenceLedger` threads through the whole walk. Thus a claim marker and a citation marker
+ * count by first appearance across the page, and a reference that two blocks share keeps one number and one
+ * list entry.
+ *
+ * The output is a pure function of the two inputs. The renderer reads no clock, no random value, and no
+ * locale. Thus the same document and the same values give the same bytes.
+ */
+import { err, ok } from "neverthrow";
+import { renderChart } from "./views/chart-view.js";
+import { deriveChartOption } from "./chart.js";
+import { assemblePage, renderReferenceSection } from "./views/page-view.js";
+import { renderClaim, renderNav, renderSection, renderText } from "./views/prose.js";
+import { ReferenceLedger } from "./references.js";
+import { renderCitation, renderFigure, renderMetric, renderTable } from "./views/values.js";
+/**
+ * Render a report document and its value map to one HTML string.
+ *
+ * The walk collects every value problem. When any problem exists, the render returns the problems and no
+ * HTML. When no problem exists, the render assembles the page and returns the string.
+ */
+export function renderReportPage(document, values) {
+    const problems = [];
+    const ledger = new ReferenceLedger();
+    const content = [];
+    for (const section of document.sections) {
+        content.push(renderBlock(section, values, ledger, 0, problems));
+    }
+    if (problems.length > 0) {
+        return err(problems);
+    }
+    const nav = renderNav(document.sections);
+    const references = renderReferenceSection(ledger);
+    return ok(assemblePage(document.title, nav, content.join(""), references));
+}
+/**
+ * Render one block to its HTML, and collect a value problem into `problems`. A block whose value is missing
+ * or of the wrong shape adds one problem and renders nothing. The empty result drops out, because the whole
+ * render fails when any problem exists.
+ */
+function renderBlock(block, values, ledger, depth, problems) {
+    switch (block.kind) {
+        case "text":
+            return renderText(block);
+        case "claim":
+            return renderClaim(block, ledger);
+        case "citation":
+            return renderCitation(block, ledger);
+        case "metric": {
+            const entry = values[block.id];
+            if (entry === undefined) {
+                problems.push(missingValue(block.id, "scalar"));
+                return "";
+            }
+            if (entry.type !== "scalar") {
+                problems.push(wrongShape(block.id, entry.type, "scalar"));
+                return "";
+            }
+            return renderMetric(block, entry);
+        }
+        case "table": {
+            const entry = values[block.id];
+            if (entry === undefined) {
+                problems.push(missingValue(block.id, "table"));
+                return "";
+            }
+            if (entry.type !== "table") {
+                problems.push(wrongShape(block.id, entry.type, "table"));
+                return "";
+            }
+            return renderTable(block, entry);
+        }
+        case "figure": {
+            const entry = values[block.id];
+            if (entry === undefined) {
+                problems.push(missingValue(block.id, "figure"));
+                return "";
+            }
+            if (entry.type !== "figure") {
+                problems.push(wrongShape(block.id, entry.type, "figure"));
+                return "";
+            }
+            return renderFigure(block, entry);
+        }
+        case "chart": {
+            const entry = values[block.id];
+            if (entry === undefined) {
+                problems.push(missingValue(block.id, "table"));
+                return "";
+            }
+            if (entry.type !== "table") {
+                problems.push(wrongShape(block.id, entry.type, "table"));
+                return "";
+            }
+            const option = deriveChartOption(block, entry.rows, entry.columns);
+            if (option.isErr()) {
+                problems.push(option.error);
+                return "";
+            }
+            return renderChart(block, option.value);
+        }
+        case "section": {
+            const parts = [];
+            for (const child of block.blocks) {
+                parts.push(renderBlock(child, values, ledger, depth + 1, problems));
+            }
+            return renderSection(block, depth, parts.join(""));
+        }
+    }
+}
+/** A `missing-value` problem that names the block and the shape that it needs. */
+function missingValue(blockId, expected) {
+    return { blockId, kind: "missing-value", detail: `The block needs a ${expected} value entry.` };
+}
+/** A `wrong-shape` problem that names the block, the shape that arrived, and the shape that it needs. */
+function wrongShape(blockId, actual, expected) {
+    return { blockId, kind: "wrong-shape", detail: `The block needs a ${expected} value entry, but the entry is a ${actual}.` };
+}

package/dist/report-render/script-json.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The one script sink helper.
+ *
+ * The markup runtime escapes each child and each attribute value. A `<script>` sink is the exception,
+ * because the JSON inside it goes to the page through `raw()`, and `raw()` adds no protection. Thus this
+ * helper is the sole guard of the two JSON sinks.
+ *
+ * A `</script` sequence inside a data cell can close the element too soon. The helper serializes the value,
+ * then it replaces every `<` with `\u003c`. The replacement makes a `</script` sequence unrepresentable,
+ * and the JSON value stays identical, because the JSON parser reads `\u003c` as `<`.
+ */
+/** Serialize a value to JSON that is safe inside a `<script>` element. */
+export declare function scriptJson(value: unknown): string;

package/dist/report-render/script-json.js

@@ -0,0 +1,15 @@
+/**
+ * The one script sink helper.
+ *
+ * The markup runtime escapes each child and each attribute value. A `<script>` sink is the exception,
+ * because the JSON inside it goes to the page through `raw()`, and `raw()` adds no protection. Thus this
+ * helper is the sole guard of the two JSON sinks.
+ *
+ * A `</script` sequence inside a data cell can close the element too soon. The helper serializes the value,
+ * then it replaces every `<` with `\u003c`. The replacement makes a `</script` sequence unrepresentable,
+ * and the JSON value stays identical, because the JSON parser reads `\u003c` as `<`.
+ */
+/** Serialize a value to JSON that is safe inside a `<script>` element. */
+export function scriptJson(value) {
+    return JSON.stringify(value).replace(/</g, "\\u003c");
+}

package/dist/report-render/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The value model that the renderer takes, keyed by block id.
+ *
+ * The renderer declares its own value union. It does not take `ResolvedValue`, because a `ResolvedValue`
+ * can be a file echo of a path and a hash. A page cannot show a path and a hash. The caller owns the
+ * policy that turns the echo into a source string. The string is a data URI, or a URL that the host
+ * serves. Thus a `figure` here carries a ready `src` string, and the renderer holds no policy about the
+ * image bytes.
+ */
+/**
+ * The value that one block resolves to, as a closed union. A `scalar` gives one number or one string. A
+ * `table` gives the rows and the optional column order. A `figure` gives a ready source string. A
+ * `citation` echoes one external id.
+ */
+export type RenderValue = {
+    type: "scalar";
+    value: string | number;
+} | {
+    type: "table";
+    rows: Array<Record<string, string | number>>;
+    columns?: string[];
+} | {
+    type: "figure";
+    src: string;
+} | {
+    type: "citation";
+    id: string;
+};
+/**
+ * One typed fault of a render. `blockId` names the block. `kind` names the class of the fault. `detail`
+ * names what the block expected. The render collects every problem, and it returns them at once.
+ */
+export interface RenderProblem {
+    blockId: string;
+    kind: "missing-value" | "wrong-shape" | "invalid-chart-input";
+    detail: string;
+}
+/** The value map that the renderer takes, keyed by block id. */
+export type RenderValues = Record<string, RenderValue>;

package/dist/report-render/types.js

@@ -0,0 +1,10 @@
+/**
+ * The value model that the renderer takes, keyed by block id.
+ *
+ * The renderer declares its own value union. It does not take `ResolvedValue`, because a `ResolvedValue`
+ * can be a file echo of a path and a hash. A page cannot show a path and a hash. The caller owns the
+ * policy that turns the echo into a source string. The string is a data URI, or a URL that the host
+ * serves. Thus a `figure` here carries a ready `src` string, and the renderer holds no policy about the
+ * image bytes.
+ */
+export {};

package/dist/report-render/value-bridge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The value bridge: a resolved value maps onto a render value, keyed by block id.
+ *
+ * The resolver gives one `ResolvedValue` for each reference. The renderer takes a `RenderValues` map. The
+ * two models agree on a scalar, a table, and a citation, but they part on a figure. A `ResolvedValue`
+ * file echo carries a path and a hash, and a page needs a source string. Thus the bridge takes a
+ * caller-supplied policy that turns a file echo into a `src` string. The preview tool gives the concrete
+ * policy, because the page directory and its asset access are a session concern.
+ *
+ * The bridge is pure. It reads no file, it resolves no reference, and it imports nothing from the state
+ * layer or the tool layer. A block kind that carries no render value maps to no entry. A block kind whose
+ * resolved value has the wrong type becomes one typed mismatch. The bridge collects every mismatch, thus
+ * one call reports each fault at one time.
+ */
+import { type Result } from "neverthrow";
+import type { ResolvedValue } from "../report-model/reference-resolver.js";
+import type { RenderValues } from "./types.js";
+/** The block kinds that carry no render value. Each one renders from the block and the ledger alone. */
+type NoValueKind = "text" | "claim" | "citation" | "section";
+/** The block kinds that carry one render value under the block id in the map. */
+type ValueBearingKind = "metric" | "table" | "chart" | "figure";
+/** The file echo that a figure binding resolves to: a whole-file pin of a path and a hash. */
+export type ResolvedFile = Extract<ResolvedValue, {
+    type: "file";
+}>;
+/** The policy that turns a resolved file echo into a figure `src` string. The caller owns the policy. */
+export type FigureSourcePolicy = (file: ResolvedFile) => string;
+/**
+ * The resolution result of one block: the block id, the block kind, and the resolved value of its binding.
+ *
+ * A value-bearing kind carries the resolved value. A no-value kind carries none, thus a text block with
+ * no binding is representable and a value on it is not.
+ */
+export type BlockResolution = {
+    blockId: string;
+    kind: NoValueKind;
+} | {
+    blockId: string;
+    kind: ValueBearingKind;
+    resolved: ResolvedValue;
+};
+/**
+ * One typed mismatch between a block kind and a resolved value type. `blockId` names the block, and
+ * `blockKind` names the kind that sets the expectation. `expected` names the resolved type that the kind
+ * needs, and `actual` names the resolved type that arrived.
+ */
+export interface BridgeMismatch {
+    blockId: string;
+    blockKind: ValueBearingKind;
+    expected: ResolvedValue["type"];
+    actual: ResolvedValue["type"];
+}
+/**
+ * Map the resolved values of the blocks onto a `RenderValues` map.
+ *
+ * The bridge walks each resolution in order. A no-value kind adds no entry. A value-bearing kind whose
+ * resolved type matches adds one entry. A value-bearing kind whose resolved type does not match adds one
+ * mismatch. A run with a mismatch returns the mismatch list and no map. A run with no mismatch returns the
+ * complete map.
+ */
+export declare function bridgeValues(resolutions: readonly BlockResolution[], figureSrc: FigureSourcePolicy): Result<RenderValues, BridgeMismatch[]>;
+export {};

package/dist/report-render/value-bridge.js

@@ -0,0 +1,82 @@
+/**
+ * The value bridge: a resolved value maps onto a render value, keyed by block id.
+ *
+ * The resolver gives one `ResolvedValue` for each reference. The renderer takes a `RenderValues` map. The
+ * two models agree on a scalar, a table, and a citation, but they part on a figure. A `ResolvedValue`
+ * file echo carries a path and a hash, and a page needs a source string. Thus the bridge takes a
+ * caller-supplied policy that turns a file echo into a `src` string. The preview tool gives the concrete
+ * policy, because the page directory and its asset access are a session concern.
+ *
+ * The bridge is pure. It reads no file, it resolves no reference, and it imports nothing from the state
+ * layer or the tool layer. A block kind that carries no render value maps to no entry. A block kind whose
+ * resolved value has the wrong type becomes one typed mismatch. The bridge collects every mismatch, thus
+ * one call reports each fault at one time.
+ */
+import { err, ok } from "neverthrow";
+/**
+ * Map the resolved values of the blocks onto a `RenderValues` map.
+ *
+ * The bridge walks each resolution in order. A no-value kind adds no entry. A value-bearing kind whose
+ * resolved type matches adds one entry. A value-bearing kind whose resolved type does not match adds one
+ * mismatch. A run with a mismatch returns the mismatch list and no map. A run with no mismatch returns the
+ * complete map.
+ */
+export function bridgeValues(resolutions, figureSrc) {
+    const values = {};
+    const mismatches = [];
+    for (const resolution of resolutions) {
+        switch (resolution.kind) {
+            case "text":
+            case "claim":
+            case "citation":
+            case "section":
+                break;
+            case "metric": {
+                const value = resolution.resolved;
+                if (value.type !== "scalar") {
+                    mismatches.push(mismatch(resolution.blockId, "metric", "scalar", value.type));
+                    break;
+                }
+                values[resolution.blockId] = { type: "scalar", value: value.value };
+                break;
+            }
+            case "table":
+            case "chart": {
+                const value = resolution.resolved;
+                if (value.type !== "table") {
+                    mismatches.push(mismatch(resolution.blockId, resolution.kind, "table", value.type));
+                    break;
+                }
+                values[resolution.blockId] = tableValue(value);
+                break;
+            }
+            case "figure": {
+                const value = resolution.resolved;
+                if (value.type !== "file") {
+                    mismatches.push(mismatch(resolution.blockId, "figure", "file", value.type));
+                    break;
+                }
+                values[resolution.blockId] = { type: "figure", src: figureSrc(value) };
+                break;
+            }
+        }
+    }
+    if (mismatches.length > 0) {
+        return err(mismatches);
+    }
+    return ok(values);
+}
+/**
+ * Map a resolved table onto a render table. The explicit column order carries through when it is present,
+ * and it stays absent otherwise, thus the renderer keeps its first-row order as the default.
+ */
+function tableValue(value) {
+    if (value.columns !== undefined) {
+        return { type: "table", rows: value.rows, columns: value.columns };
+    }
+    return { type: "table", rows: value.rows };
+}
+/** Make one mismatch that names the block, its kind, the resolved type that it needs, and the type that arrived. */
+function mismatch(blockId, blockKind, expected, actual) {
+    return { blockId, blockKind, expected, actual };
+}

package/dist/report-render/views/chart-view.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The chart container markup.
+ *
+ * The bootstrap in `page.ts` reads the option from the next element sibling of the container. Thus the
+ * `<script type="application/json">` element MUST follow the container div with no element between them.
+ * The title renders above the container, and the caption renders below.
+ */
+import type { ChartBlock } from "../../contracts/report-blocks.js";
+import type { EchartOption } from "../chart.js";
+/** Render the container markup for a chart. */
+export declare function renderChart(block: ChartBlock, option: EchartOption): string;

package/dist/report-render/views/chart-view.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
+/**
+ * The chart container markup.
+ *
+ * The bootstrap in `page.ts` reads the option from the next element sibling of the container. Thus the
+ * `<script type="application/json">` element MUST follow the container div with no element between them.
+ * The title renders above the container, and the caption renders below.
+ */
+import { raw } from "hono/html";
+import { scriptJson } from "../script-json.js";
+/** Render the container markup for a chart. */
+export function renderChart(block, option) {
+    const containerId = chartContainerId(block.id);
+    // The JSON goes to the page through `raw()`, thus `scriptJson` is the sole guard of this sink. It
+    // replaces every `<` with `\u003c`, thus a `</script` sequence in a string cell cannot close the
+    // element early. The JSON parser reads `\u003c` as `<`, thus the option value stays exact.
+    const json = scriptJson(option);
+    return String(_jsxs(_Fragment, { children: [block.title !== undefined ? _jsx("p", { class: "chart-title", children: block.title }) : null, _jsx("div", { id: containerId, "data-echarts-id": block.id, class: "chart-container" }), _jsx("script", { type: "application/json", children: raw(json) }), block.caption !== undefined ? _jsx("p", { class: "chart-caption", children: block.caption }) : null] }));
+}
+/** The container id derives from the block id, thus the id stays stable across renders. */
+function chartContainerId(blockId) {
+    return `chart-${blockId}`;
+}

package/dist/report-render/views/page-view.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The page assembly.
+ *
+ * The skeleton inlines the style rules in the head, and it puts the two scripts at the end of the body.
+ * The theme registration runs before the chart bootstrap, thus each chart finds its theme. The
+ * navigation, the main content, and the reference frame arrive as already-escaped markup strings, thus
+ * `raw()` inserts them byte for byte.
+ */
+import type { ReferenceLedger } from "../references.js";
+/**
+ * Wrap the reference list in one fixed frame. An empty ledger gives an empty string, thus the page shows
+ * no empty reference frame.
+ */
+export declare function renderReferenceSection(ledger: ReferenceLedger): string;
+/**
+ * Assemble the page from the title, the navigation, the main content, and the reference frame. The title
+ * passes through the runtime as text, and the runtime escapes it. The reference frame is optional, thus
+ * an empty frame adds no markup.
+ */
+export declare function assemblePage(title: string, nav: string, content: string, references: string): string;

package/dist/report-render/views/page-view.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
+/**
+ * The page assembly.
+ *
+ * The skeleton inlines the style rules in the head, and it puts the two scripts at the end of the body.
+ * The theme registration runs before the chart bootstrap, thus each chart finds its theme. The
+ * navigation, the main content, and the reference frame arrive as already-escaped markup strings, thus
+ * `raw()` inserts them byte for byte.
+ */
+import { raw } from "hono/html";
+import { CDN_HEAD, CHART_BOOTSTRAP, ECHARTS_THEME, ECHARTS_THEME_NAME, PAGE_CSS } from "../page.js";
+import { renderReferenceList } from "./references-view.js";
+import { scriptJson } from "../script-json.js";
+/**
+ * The theme object as script-safe JSON. `scriptJson` replaces every `<` with `\u003c`, thus a later edit
+ * that adds a `<` to the theme stays safe inside the script sink. The JSON parser reads `\u003c` as `<`, thus
+ * the theme value stays exact.
+ */
+const THEME_JSON = scriptJson(ECHARTS_THEME);
+/**
+ * The registration script for the ECharts theme. It runs before the chart bootstrap, thus each chart
+ * reads the registered theme by its name. The guard skips the call when the ECharts runtime did not load.
+ */
+const THEME_REGISTRATION = `(function () {
+  if (typeof echarts === "undefined") {
+    return;
+  }
+  echarts.registerTheme(${JSON.stringify(ECHARTS_THEME_NAME)}, ${THEME_JSON});
+})();`;
+/**
+ * Wrap the reference list in one fixed frame. An empty ledger gives an empty string, thus the page shows
+ * no empty reference frame.
+ */
+export function renderReferenceSection(ledger) {
+    const list = renderReferenceList(ledger);
+    if (list === "") {
+        return "";
+    }
+    return String(_jsxs("section", { class: "report-references-section mt-16 pt-8 border-t border-slate-200", children: [_jsx("h2", { class: "text-xl font-semibold tracking-tight text-slate-900 mb-4", children: "References" }), raw(list)] }));
+}
+/**
+ * Assemble the page from the title, the navigation, the main content, and the reference frame. The title
+ * passes through the runtime as text, and the runtime escapes it. The reference frame is optional, thus
+ * an empty frame adds no markup.
+ */
+export function assemblePage(title, nav, content, references) {
+    return ("<!doctype html>" +
+        String(_jsxs("html", { lang: "en", children: [_jsxs("head", { children: [_jsx("meta", { charset: "utf-8" }), _jsx("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }), _jsx("title", { children: title }), raw(CDN_HEAD), _jsx("style", { children: raw(PAGE_CSS) })] }), _jsxs("body", { children: [raw(nav), _jsxs("main", { class: "report-main mx-auto max-w-4xl px-6 py-10", children: [_jsx("h1", { class: "report-title text-4xl font-bold tracking-tight text-slate-900 mb-8", children: title }), raw(content), references.length > 0 ? raw(references) : null] }), _jsx("script", { children: raw(THEME_REGISTRATION) }), _jsx("script", { children: raw(CHART_BOOTSTRAP) })] })] })));
+}

package/dist/report-render/views/prose.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The prose markup: the text block, the claim block, the section wrapper, and the page navigation.
+ *
+ * The runtime escapes every interpolated string, thus hostile prose reaches the page as text. A text
+ * block and a claim block split the prose on a blank line, and each part becomes one paragraph. A claim
+ * adds one marker for each binding, and the markers number through the shared ledger.
+ */
+import type { ClaimBlock, SectionBlock, TextBlock } from "../../contracts/report-blocks.js";
+import type { ReferenceLedger } from "../references.js";
+/** Render a text block as escaped paragraphs. */
+export declare function renderText(block: TextBlock): string;
+/**
+ * Render a claim block as escaped paragraphs plus evidence markers. The markers attach to the last
+ * paragraph, thus they sit at the end of the claim text. The ledger marks each binding, thus a shared
+ * reference keeps one number across the page.
+ */
+export declare function renderClaim(block: ClaimBlock, ledger: ReferenceLedger): string;
+/**
+ * Render a section wrapper around its rendered children. The heading level is `h2` at depth 0, `h3` at
+ * depth 1, and `h4` at depth 2 or deeper. The walk renders the children first, and it passes the markup
+ * as one already-escaped string, thus `raw()` inserts it byte for byte.
+ */
+export declare function renderSection(section: SectionBlock, depth: number, childrenHtml: string): string;
+/**
+ * Render the fixed left navigation. Each anchor targets one top-level section by its block id, with a
+ * numeric badge for its position. The brand row stays, and the mobile toggle and the icon slot drop out.
+ */
+export declare function renderNav(topSections: SectionBlock[]): string;

package/dist/report-render/views/prose.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
+/**
+ * The prose markup: the text block, the claim block, the section wrapper, and the page navigation.
+ *
+ * The runtime escapes every interpolated string, thus hostile prose reaches the page as text. A text
+ * block and a claim block split the prose on a blank line, and each part becomes one paragraph. A claim
+ * adds one marker for each binding, and the markers number through the shared ledger.
+ */
+import { raw } from "hono/html";
+import { Marker } from "./references-view.js";
+/** The paragraph class of a text block and a claim block. */
+const PARAGRAPH_CLASS = "report-paragraph mb-4 leading-relaxed text-slate-600";
+/**
+ * Split prose into paragraphs on a blank line. A run of blank lines makes one split. An empty part drops
+ * out, thus a leading or a trailing blank line adds no empty paragraph.
+ */
+function splitParagraphs(prose) {
+    const parts = prose.split(/\n[ \t]*\n/);
+    const paragraphs = [];
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (trimmed.length > 0) {
+            paragraphs.push(trimmed);
+        }
+    }
+    return paragraphs;
+}
+/** Render a text block as escaped paragraphs. */
+export function renderText(block) {
+    const paragraphs = splitParagraphs(block.content.prose);
+    return String(_jsx(_Fragment, { children: paragraphs.map((paragraph) => (_jsx("p", { class: PARAGRAPH_CLASS, children: paragraph }))) }));
+}
+/**
+ * Render a claim block as escaped paragraphs plus evidence markers. The markers attach to the last
+ * paragraph, thus they sit at the end of the claim text. The ledger marks each binding, thus a shared
+ * reference keeps one number across the page.
+ */
+export function renderClaim(block, ledger) {
+    const markerNumbers = block.bindings.map((reference) => ledger.mark(reference));
+    const markers = markerNumbers.map((n) => _jsx(Marker, { n: n }));
+    const paragraphs = splitParagraphs(block.content.prose);
+    if (paragraphs.length === 0) {
+        return String(_jsx("p", { class: PARAGRAPH_CLASS, children: markers }));
+    }
+    const last = paragraphs.length - 1;
+    return String(_jsx(_Fragment, { children: paragraphs.map((paragraph, index) => (_jsxs("p", { class: PARAGRAPH_CLASS, children: [paragraph, index === last ? markers : null] }))) }));
+}
+/** The heading class of a section, by heading level. */
+function headingClass(level) {
+    switch (level) {
+        case 2:
+            return "text-3xl font-semibold tracking-tight text-slate-900 mb-4";
+        case 3:
+            return "text-2xl font-semibold tracking-tight text-slate-900 mb-3";
+        default:
+            return "text-xl font-semibold tracking-tight text-slate-900 mb-2";
+    }
+}
+/**
+ * Render a section wrapper around its rendered children. The heading level is `h2` at depth 0, `h3` at
+ * depth 1, and `h4` at depth 2 or deeper. The walk renders the children first, and it passes the markup
+ * as one already-escaped string, thus `raw()` inserts it byte for byte.
+ */
+export function renderSection(section, depth, childrenHtml) {
+    const level = Math.min(depth + 2, 4);
+    const Heading = `h${level}`;
+    return String(_jsxs("section", { id: section.id, class: "report-section mb-10", children: [_jsx(Heading, { class: headingClass(level), children: section.title }), raw(childrenHtml)] }));
+}
+/**
+ * Render the fixed left navigation. Each anchor targets one top-level section by its block id, with a
+ * numeric badge for its position. The brand row stays, and the mobile toggle and the icon slot drop out.
+ */
+export function renderNav(topSections) {
+    return String(_jsxs("aside", { id: "report-sidebar", class: "fixed top-0 left-0 z-40 h-screen w-60 flex flex-col border-r border-slate-200 bg-white/95 backdrop-blur", "aria-label": "Report navigation", children: [_jsx("div", { class: "flex items-center gap-2 px-5 py-5 border-b border-slate-200", children: _jsx("span", { class: "font-mono text-sm font-semibold tracking-wider text-primary-500", children: "inflexa" }) }), _jsx("nav", { class: "flex-1 overflow-y-auto py-3", "aria-label": "Report sections", children: topSections.map((section, index) => (_jsxs("a", { href: `#${section.id}`, "data-sidebar-link": "", class: "sidebar-link flex items-center gap-3 px-5 py-2 text-sm text-slate-500 hover:text-slate-900 hover:bg-slate-50 transition-colors", children: [_jsx("span", { class: "font-mono text-[10px] font-semibold tracking-wider text-slate-300 shrink-0 w-4 text-right", children: index + 1 }), _jsx("span", { class: "truncate", children: section.title })] }))) })] }));
+}

package/dist/report-render/views/references-view.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The reference markup: the evidence marker and the ordered reference list.
+ *
+ * The runtime escapes each child and each attribute value, thus a hostile path, a hostile id, or a
+ * hostile operation reaches the page as text. The list keeps the first-appearance order of the ledger,
+ * thus the ordinal of each item matches its marker.
+ */
+import type { ReferenceLedger } from "../references.js";
+/**
+ * One evidence marker as a superscript that links to the list entry. The number comes from the ledger as
+ * an integer.
+ */
+export declare function Marker({ n }: {
+    n: number;
+}): import("hono/jsx/jsx-dev-runtime").JSX.Element;
+/**
+ * The ordered reference list for the end of the page. An empty ledger gives an empty string, thus the
+ * page shows no empty list.
+ */
+export declare function renderReferenceList(ledger: ReferenceLedger): string;

package/dist/report-render/views/references-view.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
+/**
+ * One evidence marker as a superscript that links to the list entry. The number comes from the ledger as
+ * an integer.
+ */
+export function Marker({ n }) {
+    return (_jsx("sup", { class: "report-marker font-mono text-[10px] text-primary-500", children: _jsx("a", { href: `#ref-${n}`, children: n }) }));
+}
+/** The kind label of one reference entry. */
+function RefKind({ children }) {
+    return _jsx("span", { class: "report-ref-kind font-mono text-[11px] uppercase tracking-wider text-slate-400", children: children });
+}
+/** A path in a monospace code span. */
+function PathCode({ children }) {
+    return _jsx("code", { class: "font-mono text-primary-700", children: children });
+}
+/** A plain detail such as a locator or an external id. */
+function Detail({ children }) {
+    return _jsx("span", { class: "text-slate-500", children: children });
+}
+/**
+ * Describe a locator as plain text: the column and the one row selector. The refine of the schema admits
+ * exactly one of `row` or `rowFilter`, thus the two branches cover a valid locator.
+ */
+function describeLocator(locator) {
+    if (locator.row !== undefined) {
+        return `column ${locator.column}, row ${locator.row}`;
+    }
+    const filter = locator.rowFilter;
+    if (filter !== undefined) {
+        return `column ${locator.column}, row where ${filter.column} ${filter.op} ${String(filter.value)}`;
+    }
+    return `column ${locator.column}`;
+}
+/**
+ * The inner markup of one list entry. An artifact entry names its path, and it adds the locator when the
+ * reference pins one cell. A citation entry names its identifier space and its id. A derivation entry
+ * names its operation and its two inputs, each by path and locator.
+ */
+function ReferenceEntry({ reference }) {
+    switch (reference.kind) {
+        case "artifact-value":
+            return (_jsxs(_Fragment, { children: [_jsx(RefKind, { children: "Artifact value" }), " ", _jsx(PathCode, { children: reference.path }), " ", _jsx(Detail, { children: describeLocator(reference.locator) })] }));
+        case "artifact-table":
+            return (_jsxs(_Fragment, { children: [_jsx(RefKind, { children: "Artifact table" }), " ", _jsx(PathCode, { children: reference.path })] }));
+        case "artifact-file":
+            return (_jsxs(_Fragment, { children: [_jsx(RefKind, { children: "Artifact file" }), " ", _jsx(PathCode, { children: reference.path })] }));
+        case "citation":
+            return (_jsxs(_Fragment, { children: [_jsx(RefKind, { children: "Citation" }), " ", _jsx(Detail, { children: `${reference.idKind}:${reference.id}` })] }));
+        case "derivation":
+            return (_jsxs(_Fragment, { children: [_jsx(RefKind, { children: `Derivation (${reference.op})` }), " ", reference.inputs.map((input, index) => (_jsxs(_Fragment, { children: [index > 0 ? " and " : "", _jsx(PathCode, { children: input.path }), " ", _jsx(Detail, { children: describeLocator(input.locator) })] })))] }));
+    }
+}
+/**
+ * The ordered reference list for the end of the page. An empty ledger gives an empty string, thus the
+ * page shows no empty list.
+ */
+export function renderReferenceList(ledger) {
+    const entries = ledger.entries();
+    if (entries.length === 0) {
+        return "";
+    }
+    return String(_jsx("ol", { class: "report-references list-decimal pl-6", children: entries.map((reference, index) => (_jsx("li", { id: `ref-${index + 1}`, class: "report-ref-item mb-2 text-sm text-slate-600", children: _jsx(ReferenceEntry, { reference: reference }) }))) }));
+}