@inflexa-ai/harness 0.31.0 → 0.32.0

package/dist/report-render/provenance-data.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The data-script carrier of the provenance of one analysis.
+ *
+ * A `fetch` of a local file is refused on a `file://` page, thus the document cannot load the way an image
+ * does. A classic script asset loads on any page, and it registers itself under one global when the browser
+ * runs it. The carrier is the same one that a table payload uses.
+ *
+ * The document and the attestation are opaque text. This module reads no field of them, and it parses
+ * nothing. Thus the format belongs to the writer of the document, and a change of that format costs no
+ * change here.
+ *
+ * The document and the attestation ride separate assets, thus a new attestation over an unchanged document
+ * rewrites the attestation alone. Each name carries the hash of its own bytes, thus two renders of one
+ * document give one name and the sweep of the stage removes a name that the page does not reference.
+ *
+ * The module is pure, and it reads no file. The renderer derives an asset, and the caller writes it.
+ */
+import type { DataAsset } from "./table-data.js";
+/**
+ * The one global that both assets register under.
+ *
+ * The page script reads the same name, thus the carrier and the reader cannot disagree over a rename.
+ */
+export declare const REPORT_PROVENANCE_GLOBAL = "__REPORT_PROV";
+/**
+ * The provenance that the page carries: the document text, and the attestation text where the source holds
+ * one.
+ *
+ * Both are opaque strings. The renderer moves them into the page and never into a parse, thus a document of
+ * any format rides unchanged and the page-side reader owns the format.
+ */
+export interface ProvenanceExport {
+    readonly document: string;
+    readonly attestation?: string;
+}
+/**
+ * The data assets of one provenance export, in load order.
+ *
+ * A source that holds no attestation gives the document asset alone. Thus an unsigned document still rides
+ * the page, and the reader finds no attestation member on the global.
+ */
+export declare function provenanceDataAssets(provenance: ProvenanceExport): DataAsset[];

package/dist/report-render/provenance-data.js

@@ -0,0 +1,62 @@
+/**
+ * The data-script carrier of the provenance of one analysis.
+ *
+ * A `fetch` of a local file is refused on a `file://` page, thus the document cannot load the way an image
+ * does. A classic script asset loads on any page, and it registers itself under one global when the browser
+ * runs it. The carrier is the same one that a table payload uses.
+ *
+ * The document and the attestation are opaque text. This module reads no field of them, and it parses
+ * nothing. Thus the format belongs to the writer of the document, and a change of that format costs no
+ * change here.
+ *
+ * The document and the attestation ride separate assets, thus a new attestation over an unchanged document
+ * rewrites the attestation alone. Each name carries the hash of its own bytes, thus two renders of one
+ * document give one name and the sweep of the stage removes a name that the page does not reference.
+ *
+ * The module is pure, and it reads no file. The renderer derives an asset, and the caller writes it.
+ */
+import { createHash } from "node:crypto";
+import { scriptJson } from "./script-json.js";
+/**
+ * The one global that both assets register under.
+ *
+ * The page script reads the same name, thus the carrier and the reader cannot disagree over a rename.
+ */
+export const REPORT_PROVENANCE_GLOBAL = "__REPORT_PROV";
+/** The member of the global that holds the document text. */
+const DOCUMENT_MEMBER = "document";
+/** The member of the global that holds the attestation text. */
+const ATTESTATION_MEMBER = "attestation";
+/** The count of hash characters in an asset name. It matches a table payload, thus one form reads across the directory. */
+const HASH_CHARS = 12;
+/**
+ * The source text of one member of the global.
+ *
+ * The global takes the null-prototype form, the same as the table registry, thus a member sits as an
+ * ordinary entry. The text rides as a JSON string literal, thus hostile bytes are data and never source. A
+ * `</script` sequence inside the text cannot close the element, because `scriptJson` writes each `<` as its
+ * escape.
+ */
+function memberSource(member, text) {
+    const registry = `window.${REPORT_PROVENANCE_GLOBAL}`;
+    return `${registry}=${registry}||Object.create(null);${registry}.${member}=${scriptJson(text)};\n`;
+}
+/** One member asset: the content-addressed file name under `suffix`, and the source text. */
+function memberAsset(member, suffix, text) {
+    const bytes = memberSource(member, text);
+    const hash = createHash("sha256").update(bytes).digest("hex").slice(0, HASH_CHARS);
+    return { name: `prov-${hash}${suffix}`, bytes };
+}
+/**
+ * The data assets of one provenance export, in load order.
+ *
+ * A source that holds no attestation gives the document asset alone. Thus an unsigned document still rides
+ * the page, and the reader finds no attestation member on the global.
+ */
+export function provenanceDataAssets(provenance) {
+    const assets = [memberAsset(DOCUMENT_MEMBER, ".data.js", provenance.document)];
+    if (provenance.attestation !== undefined) {
+        assets.push(memberAsset(ATTESTATION_MEMBER, ".sig.data.js", provenance.attestation));
+    }
+    return assets;
+}

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

@@ -18,7 +18,20 @@ import { type Result } from "neverthrow";
 import type { ReportDocument } from "../contracts/report-blocks.js";
 import { type CitationRecords } from "../report-model/reference-resolver.js";
 import { type DerivationChain } from "./references.js";
+import { type ProvenanceExport } from "./provenance-data.js";
 import type { RenderedPage, RenderProblem, RenderValues } from "./types.js";
+/**
+ * The optional inputs of one render: the bibliography of the pin, the chains of the session, and the frozen
+ * provenance of the analysis.
+ *
+ * Each member is absent on its own, and a caller gives the members that it holds. A positional tail of
+ * three optional inputs made a caller of the last one pad the two before it, thus the three ride one bag.
+ */
+export interface RenderOptions {
+    readonly records?: CitationRecords;
+    readonly derivations?: readonly DerivationChain[];
+    readonly provenance?: ProvenanceExport;
+}
 /**
  * Render a report document, its value map, and the pinned citation records to one page and its data assets.
  *
@@ -34,10 +47,16 @@ import type { RenderedPage, RenderProblem, RenderValues } from "./types.js";
  * byte-identically with the chains and without them. A chain carries the relative source of its staged
  * script and of its derived file as data, thus the entry links both and this module stages nothing.
  *
+ * The provenance is the frozen document of the analysis, and it is optional too. The renderer moves the
+ * opaque text into two data assets that register one page global, and it parses no byte of it. Each
+ * grounded block then stamps its keys, and its marker carries the control that opens the chain. A caller
+ * that passes none renders the page byte for byte without the provenance script, without a stamp, and
+ * without a control.
+ *
  * The renderer writes no file. The data assets ride the result, and the caller stages them beside the page.
  * Thus the render stays pure, and two renders of one document give byte-identical assets.
  *
  * One artifact gives one payload. A table block and a chart block that bind it read that one asset, and a
  * chart under the inline bound carries its rows in its own option and registers none.
  */
-export declare function renderReportPage(document: ReportDocument, values: RenderValues, records?: CitationRecords, derivations?: readonly DerivationChain[]): Result<RenderedPage, RenderProblem[]>;
+export declare function renderReportPage(document: ReportDocument, values: RenderValues, { records, derivations, provenance }?: RenderOptions): Result<RenderedPage, RenderProblem[]>;

package/dist/report-render/render.js

@@ -22,6 +22,7 @@ import { deriveChartRender } from "./chart.js";
 import { assemblePage, renderBand, renderReferenceSection } from "./views/page-view.js";
 import { renderClaim, renderNav, renderSection, renderText } from "./views/prose.js";
 import { citationKeyOf, derivationChains, ReferenceLedger } from "./references.js";
+import { provenanceDataAssets } from "./provenance-data.js";
 import { encodeTablePayload, tableDataAsset } from "./table-data.js";
 import { renderCitation, renderFigure, renderMetric, renderMetricGrid, renderTable, tableColumns, tableDisplay } from "./views/values.js";
 /**
@@ -39,16 +40,22 @@ import { renderCitation, renderFigure, renderMetric, renderMetricGrid, renderTab
  * byte-identically with the chains and without them. A chain carries the relative source of its staged
  * script and of its derived file as data, thus the entry links both and this module stages nothing.
  *
+ * The provenance is the frozen document of the analysis, and it is optional too. The renderer moves the
+ * opaque text into two data assets that register one page global, and it parses no byte of it. Each
+ * grounded block then stamps its keys, and its marker carries the control that opens the chain. A caller
+ * that passes none renders the page byte for byte without the provenance script, without a stamp, and
+ * without a control.
+ *
  * The renderer writes no file. The data assets ride the result, and the caller stages them beside the page.
  * Thus the render stays pure, and two renders of one document give byte-identical assets.
  *
  * One artifact gives one payload. A table block and a chart block that bind it read that one asset, and a
  * chart under the inline bound carries its rows in its own option and registers none.
  */
-export function renderReportPage(document, values, records, derivations) {
+export function renderReportPage(document, values, { records, derivations, provenance } = {}) {
     const problems = [];
     const ledger = new ReferenceLedger();
-    const data = { payloads: new Map(), mounts: 0 };
+    const data = { payloads: new Map(), mounts: 0, view: { lineage: provenance !== undefined } };
     const content = [];
     for (const [index, section] of document.sections.entries()) {
         content.push(renderBand(index, renderBlock(section, values, ledger, records, data, 0, problems)));
@@ -56,10 +63,16 @@ export function renderReportPage(document, values, records, derivations) {
     if (problems.length > 0) {
         return err(problems);
     }
-    const dataAssets = [...data.payloads.values()].map((entry) => tableDataAsset(entry.ids, entry.payload));
+    const tableAssets = [...data.payloads.values()].map((entry) => tableDataAsset(entry.ids, entry.payload));
+    // The two asset groups stay apart in the skeleton, because the table decoder answers for a table payload
+    // alone. Thus a page that carries the provenance and no table loads no decoder.
+    const provenanceAssets = provenance === undefined ? [] : provenanceDataAssets(provenance);
     const nav = renderNav(document.sections);
     const references = renderReferenceSection(ledger, document.sections.length, records, derivationChains(derivations));
-    return ok({ html: assemblePage(document.title, nav, content.join(""), references, dataAssets, data.mounts > 0), dataAssets });
+    return ok({
+        html: assemblePage(document.title, nav, content.join(""), references, { dataAssets: tableAssets, grids: data.mounts > 0, provenanceAssets }),
+        dataAssets: [...provenanceAssets, ...tableAssets],
+    });
 }
 /**
  * Register the payload of one bound artifact, and name this block as a reader of it.
@@ -86,9 +99,9 @@ function renderBlock(block, values, ledger, records, data, depth, problems) {
         case "text":
             return renderText(block);
         case "claim":
-            return renderClaim(block, ledger);
+            return renderClaim(block, ledger, data.view);
         case "citation":
-            return renderCitation(block, ledger, citationRecordOf(records, citationKeyOf(block.binding)));
+            return renderCitation(block, ledger, citationRecordOf(records, citationKeyOf(block.binding)), data.view);
         case "metric": {
             const entry = values[block.id];
             if (entry === undefined) {
@@ -99,7 +112,7 @@ function renderBlock(block, values, ledger, records, data, depth, problems) {
                 problems.push(wrongShape(block.id, entry.type, "scalar"));
                 return "";
             }
-            return renderMetric(block, ledger, entry);
+            return renderMetric(block, ledger, entry, data.view);
         }
         case "table": {
             const entry = values[block.id];
@@ -117,7 +130,7 @@ function renderBlock(block, values, ledger, records, data, depth, problems) {
             const columns = tableColumns(entry);
             data.mounts += 1;
             registerPayload(data, block.binding, block.id, () => payloadOf(block.binding, entry, columns));
-            return renderTable(block, ledger, entry.rows.length, entry.total);
+            return renderTable(block, ledger, entry.rows.length, entry.total, data.view);
         }
         case "figure": {
             const entry = values[block.id];
@@ -129,7 +142,7 @@ function renderBlock(block, values, ledger, records, data, depth, problems) {
                 problems.push(wrongShape(block.id, entry.type, "figure"));
                 return "";
             }
-            return renderFigure(block, ledger, entry);
+            return renderFigure(block, ledger, entry, data.view);
         }
         case "chart": {
             const entry = values[block.id];
@@ -154,7 +167,7 @@ function renderBlock(block, values, ledger, records, data, depth, problems) {
             if (derived.value.readsPayload) {
                 registerPayload(data, block.binding, block.id, () => payloadOf(block.binding, entry, columns));
             }
-            return renderChart(block, ledger, derived.value.option);
+            return renderChart(block, ledger, derived.value.option, data.view);
         }
         case "section":
             return renderSection(block, depth, renderChildren(block.blocks, values, ledger, records, data, depth + 1, problems));

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

@@ -47,6 +47,9 @@ export type RenderValues = Record<string, RenderValue>;
  *
  * The renderer writes no file. Thus it gives the asset bytes back to the caller, and the caller stages
  * them beside the page. A document with no table gives an empty list, and its page references none.
+ *
+ * The list holds the provenance assets of the render beside the table payloads, thus one stage writes each
+ * file that the page loads and the caller sorts nothing.
  */
 export interface RenderedPage {
     html: string;

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

@@ -11,11 +11,15 @@
 import type { ChartBlock } from "../../contracts/report-blocks.js";
 import type { EchartOption } from "../chart.js";
 import type { ReferenceLedger } from "../references.js";
+import { type ViewOptions } from "./lineage.js";
 /**
  * Render the card markup for a chart.
  *
  * The whole-table binding joins the reference ladder, thus the title line carries the marker and the
  * appendix names the artifact that the chart plots. A chart with no title still shows its marker on the
  * same line.
+ *
+ * `view.lineage` states that the page carries a provenance document. The card then stamps its keys, and the
+ * marker carries the control that opens the chain.
  */
-export declare function renderChart(block: ChartBlock, ledger: ReferenceLedger, option: EchartOption): string;
+export declare function renderChart(block: ChartBlock, ledger: ReferenceLedger, option: EchartOption, view?: ViewOptions): string;

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

@@ -10,6 +10,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
  * height, because the chart runtime measures the container and a container with no height shows no chart.
  */
 import { raw } from "hono/html";
+import { DEFAULT_VIEW_OPTIONS, lineagePlace, lineageStamp } from "./lineage.js";
 import { Marker } from "./references-view.js";
 import { scriptJson } from "../script-json.js";
 /**
@@ -18,15 +19,18 @@ import { scriptJson } from "../script-json.js";
  * The whole-table binding joins the reference ladder, thus the title line carries the marker and the
  * appendix names the artifact that the chart plots. A chart with no title still shows its marker on the
  * same line.
+ *
+ * `view.lineage` states that the page carries a provenance document. The card then stamps its keys, and the
+ * marker carries the control that opens the chain.
  */
-export function renderChart(block, ledger, option) {
+export function renderChart(block, ledger, option, view = DEFAULT_VIEW_OPTIONS) {
     const n = ledger.mark(block.binding);
     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("div", { class: "report-chart", children: [_jsxs("div", { class: "report-chart-title", children: [block.title, _jsx(Marker, { n: n })] }), _jsxs("div", { class: "report-chart-card corner-accents", children: [_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: "report-caption", children: block.caption }) : null] }));
+    return String(_jsxs("div", { class: "report-chart", ...lineageStamp(view.lineage, block.id, [block.binding]), children: [_jsxs("div", { class: "report-chart-title", children: [block.title, _jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, block.binding) })] }), _jsxs("div", { class: "report-chart-card corner-accents", children: [_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: "report-caption", children: block.caption }) : null] }));
 }
 /** The container id derives from the block id, thus the id stays stable across renders. */
 function chartContainerId(blockId) {

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

@@ -0,0 +1,93 @@
+/**
+ * The lineage keys of a grounded block, and the control that opens the chain of one key.
+ *
+ * A grounded block stamps its identity into the markup: the block id, and one key for each reference that
+ * it binds, in marker order. The page script reads the stamp when a reader clicks a control. Thus the
+ * markup is the one contract between the renderer and the script, and neither side holds a copy of the
+ * other.
+ *
+ * A key is a pin or an external record. A pin names one immutable file by `path` and `hash`, and the walk
+ * resolves the node of those bytes. A citation names a paper, which no data chain reaches, thus its key
+ * carries the identity of the record instead.
+ *
+ * A reference that pins no single file gives no key. A derivation computes over two inputs, thus it names
+ * no file of its own and the marker of such a reference carries no control.
+ *
+ * The stamp is empty while the page carries no provenance document. Thus such a page holds no lineage
+ * attribute, no control, and the markup that it held before the stamp existed.
+ *
+ * The module also declares `ViewOptions`. Each view of the page reads that bag, and the lineage condition
+ * is the one truth that it holds today.
+ */
+import type { Reference } from "../../contracts/report-reference.js";
+/**
+ * The page-wide truths of one render.
+ *
+ * A truth of this kind is constant across the whole page, thus each view of one page decides it alike. The
+ * bag threads one time through the view layer. Thus the next truth joins this interface, and no view
+ * signature grows one more parameter for it.
+ *
+ * `lineage` states that the page carries a provenance document. Each grounded block then stamps its keys
+ * and shows its control, and a page with no document carries neither.
+ */
+export interface ViewOptions {
+    readonly lineage: boolean;
+}
+/**
+ * The options that a view takes when the caller gives none. Each truth is off, thus the view renders its
+ * plain form.
+ */
+export declare const DEFAULT_VIEW_OPTIONS: ViewOptions;
+/** The attribute that names the block of one stamp. The page script reads the same name. */
+export declare const LINEAGE_BLOCK_ATTRIBUTE = "data-lineage-block";
+/** The attribute that carries the keys of one stamp, as a JSON array in marker order. */
+export declare const LINEAGE_KEYS_ATTRIBUTE = "data-lineage-keys";
+/** The attribute of one control: the place of its key in the key list of the block. */
+export declare const LINEAGE_KEY_ATTRIBUTE = "data-lineage-key";
+/** The class of the control that opens the chain of one reference. */
+export declare const LINEAGE_CONTROL_CLASS = "report-lineage";
+/** The pin of one artifact: the analysis-relative path, and the content hash of the bytes. */
+export interface LineagePin {
+    readonly path: string;
+    readonly hash: string;
+}
+/** The identity of one external record: the identifier space, and the identifier inside it. */
+export interface LineageRecord {
+    readonly idKind: string;
+    readonly id: string;
+}
+/** One key of a stamp. A reference that pins no single file gives `null` in place of a key. */
+export type LineageKey = LineagePin | LineageRecord;
+/**
+ * The key of one reference, or `null` where the reference pins no single file.
+ *
+ * A derivation is the one artifact-side kind that gives `null`. It computes over two inputs, thus the
+ * document holds no node of its own bytes and one pin cannot address it.
+ */
+export declare function lineageKeyOf(reference: Reference): LineageKey | null;
+/**
+ * The stamp attributes of one block, or an empty object while the page carries no provenance.
+ *
+ * The caller spreads the result onto the container element of the block. Thus a page with no provenance
+ * emits no attribute at all, and the spread is the one place that decides it.
+ *
+ * The key list keeps one entry for each binding, in marker order. Thus the place of a control indexes the
+ * bindings directly, and a binding that gives no key keeps its place as `null`.
+ */
+export declare function lineageStamp(on: boolean, blockId: string, references: readonly Reference[]): Record<string, string>;
+/**
+ * The place of the control of one reference, or `undefined` where the page carries no provenance or the
+ * reference pins nothing.
+ *
+ * A block that binds one reference passes no index, because its one key sits at the first place.
+ */
+export declare function lineagePlace(on: boolean, reference: Reference, index?: number): number | undefined;
+/**
+ * The control beside one marker. A click opens the chain of the key that sits at `place`.
+ *
+ * The control names its place and never its key. The stamp of the block holds the keys, thus one page
+ * carries one copy of each key and a claim of several bindings repeats none of them.
+ */
+export declare function LineageControl({ place }: {
+    place: number;
+}): import("hono/jsx/jsx-dev-runtime").JSX.Element;

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

@@ -0,0 +1,86 @@
+import { jsx as _jsx, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
+/**
+ * The options that a view takes when the caller gives none. Each truth is off, thus the view renders its
+ * plain form.
+ */
+export const DEFAULT_VIEW_OPTIONS = { lineage: false };
+/** The attribute that names the block of one stamp. The page script reads the same name. */
+export const LINEAGE_BLOCK_ATTRIBUTE = "data-lineage-block";
+/** The attribute that carries the keys of one stamp, as a JSON array in marker order. */
+export const LINEAGE_KEYS_ATTRIBUTE = "data-lineage-keys";
+/** The attribute of one control: the place of its key in the key list of the block. */
+export const LINEAGE_KEY_ATTRIBUTE = "data-lineage-key";
+/** The class of the control that opens the chain of one reference. */
+export const LINEAGE_CONTROL_CLASS = "report-lineage";
+/** The name of the control for a reader who hears the page instead of seeing it. */
+const LINEAGE_CONTROL_LABEL = "Show the lineage of this reference";
+/** The class of the glyph inside the control. The design sheet holds the matching rule. */
+const LINEAGE_GLYPH_CLASS = "report-lineage-glyph";
+/**
+ * The glyph of the control: a branch of three nodes on the 16px grid.
+ *
+ * The drawing reads as a chain that divides, which is what the panel behind it shows. A text glyph reads
+ * as a disclosure of more prose, and a bracket form would give the page two notations that look alike and
+ * mean different things.
+ *
+ * The stroke takes the current color, thus the muted color of the button and its primary color on hover
+ * both reach the drawing and the sheet holds one color for the two states. The glyph is decoration, thus
+ * it hides from a reader who hears the page and the label of the button answers instead.
+ */
+function LineageGlyph() {
+    return (_jsxs("svg", { class: LINEAGE_GLYPH_CLASS, width: "13", height: "13", viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", "stroke-width": "1.5", "aria-hidden": "true", children: [_jsx("circle", { cx: "4", cy: "4", r: "2" }), _jsx("circle", { cx: "4", cy: "12", r: "2" }), _jsx("circle", { cx: "12", cy: "12", r: "2" }), _jsx("path", { d: "M4 6v4" }), _jsx("path", { d: "M6 12h4" }), _jsx("path", { d: "M12 10V8a4 4 0 0 0-4-4H6" })] }));
+}
+/**
+ * The key of one reference, or `null` where the reference pins no single file.
+ *
+ * A derivation is the one artifact-side kind that gives `null`. It computes over two inputs, thus the
+ * document holds no node of its own bytes and one pin cannot address it.
+ */
+export function lineageKeyOf(reference) {
+    switch (reference.kind) {
+        case "citation":
+            return { idKind: reference.idKind, id: reference.id };
+        case "derivation":
+            return null;
+        default:
+            return { path: reference.path, hash: reference.hash };
+    }
+}
+/**
+ * The stamp attributes of one block, or an empty object while the page carries no provenance.
+ *
+ * The caller spreads the result onto the container element of the block. Thus a page with no provenance
+ * emits no attribute at all, and the spread is the one place that decides it.
+ *
+ * The key list keeps one entry for each binding, in marker order. Thus the place of a control indexes the
+ * bindings directly, and a binding that gives no key keeps its place as `null`.
+ */
+export function lineageStamp(on, blockId, references) {
+    if (!on) {
+        return {};
+    }
+    // The JSON rides an attribute value, and the markup runtime escapes each attribute value. Thus a
+    // hostile path reaches the page as text and it cannot leave its slot.
+    return {
+        [LINEAGE_BLOCK_ATTRIBUTE]: blockId,
+        [LINEAGE_KEYS_ATTRIBUTE]: JSON.stringify(references.map(lineageKeyOf)),
+    };
+}
+/**
+ * The place of the control of one reference, or `undefined` where the page carries no provenance or the
+ * reference pins nothing.
+ *
+ * A block that binds one reference passes no index, because its one key sits at the first place.
+ */
+export function lineagePlace(on, reference, index = 0) {
+    return on && lineageKeyOf(reference) !== null ? index : undefined;
+}
+/**
+ * The control beside one marker. A click opens the chain of the key that sits at `place`.
+ *
+ * The control names its place and never its key. The stamp of the block holds the keys, thus one page
+ * carries one copy of each key and a claim of several bindings repeats none of them.
+ */
+export function LineageControl({ place }) {
+    return (_jsx("button", { type: "button", class: LINEAGE_CONTROL_CLASS, "aria-label": LINEAGE_CONTROL_LABEL, "aria-expanded": "false", [LINEAGE_KEY_ATTRIBUTE]: String(place), children: _jsx(LineageGlyph, {}) }));
+}

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

@@ -37,6 +37,18 @@ export declare function renderBand(index: number, inner: string): string;
  * such a path states it.
  */
 export declare function renderReferenceSection(ledger: ReferenceLedger, index: number, records?: CitationRecords, chains?: DerivationChains): string;
+/**
+ * What one page loads: the table payloads, the grid condition, and the provenance assets.
+ *
+ * The two asset groups carry one type, and they land in different places of the skeleton. A positional pair
+ * of one type takes no fault at the build when a caller swaps the two. Thus the group rides one bag, and
+ * each member of it carries its own name.
+ */
+export interface PageAssets {
+    readonly dataAssets: readonly DataAsset[];
+    readonly grids: boolean;
+    readonly provenanceAssets: readonly DataAsset[];
+}
 /**
  * Assemble the page from the title, the navigation, the main content, the reference frame, and the data
  * assets. The title passes through the runtime as text, and the runtime escapes it. The reference frame is
@@ -46,7 +58,16 @@ export declare function renderReferenceSection(ledger: ReferenceLedger, index: n
  * of them. Thus every payload is registered before any reader looks. A page with no asset carries no tag
  * and no decoder.
  *
+ * The provenance assets lead the group, and they stand before each bootstrap. Thus a reader of the global
+ * finds the document whichever script asks for it first. A page with no provenance carries no such tag, and
+ * the rest of the skeleton is what it was.
+ *
+ * The provenance also gates the library reference and the lineage popover. The library stands in the head,
+ * beside the other two runtimes, and the popover script reads it when a reader clicks a control. Thus the
+ * place of the script in the order is free and it stands last. A page with no provenance carries no stamp
+ * and no control, thus neither the library nor the script would find anything to open.
+ *
  * `grids` states that the content holds a grid mount. The grid runtime weighs about two megabytes, thus a
  * page whose only payload feeds a chart references neither the runtime nor the grid boot.
  */
-export declare function assemblePage(title: string, nav: string, content: string, references: string, dataAssets: readonly DataAsset[], grids: boolean): string;
+export declare function assemblePage(title: string, nav: string, content: string, references: string, { dataAssets, grids, provenanceAssets }: PageAssets): string;

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

@@ -18,7 +18,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
  * one width, and the title over them sits on the same left edge.
  */
 import { raw } from "hono/html";
-import { ASSET_HEAD, CHART_BOOTSTRAP, FADE_IN_OBSERVER, GRID_ASSET_HEAD, GRID_BOOTSTRAP, SECTION_SPY, TABLE_DATA_DECODER } from "../page.js";
+import { ASSET_HEAD, CHART_BOOTSTRAP, FADE_IN_OBSERVER, GRID_ASSET_HEAD, GRID_BOOTSTRAP, LINEAGE_ASSET_HEAD, LINEAGE_POPOVER, SECTION_SPY, TABLE_DATA_DECODER, } from "../page.js";
 import { stagedSource } from "../assets.js";
 import { DESIGN_CSS, ECHARTS_THEME, ECHARTS_THEME_NAME } from "../design.js";
 import { renderReferences } from "./references-view.js";
@@ -82,10 +82,19 @@ export function renderReferenceSection(ledger, index, records, chains) {
  * of them. Thus every payload is registered before any reader looks. A page with no asset carries no tag
  * and no decoder.
  *
+ * The provenance assets lead the group, and they stand before each bootstrap. Thus a reader of the global
+ * finds the document whichever script asks for it first. A page with no provenance carries no such tag, and
+ * the rest of the skeleton is what it was.
+ *
+ * The provenance also gates the library reference and the lineage popover. The library stands in the head,
+ * beside the other two runtimes, and the popover script reads it when a reader clicks a control. Thus the
+ * place of the script in the order is free and it stands last. A page with no provenance carries no stamp
+ * and no control, thus neither the library nor the script would find anything to open.
+ *
  * `grids` states that the content holds a grid mount. The grid runtime weighs about two megabytes, thus a
  * page whose only payload feeds a chart references neither the runtime nor the grid boot.
  */
-export function assemblePage(title, nav, content, references, dataAssets, grids) {
+export function assemblePage(title, nav, content, references, { dataAssets, grids, provenanceAssets }) {
     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(ASSET_HEAD), grids ? raw(GRID_ASSET_HEAD) : null, _jsx("style", { children: raw(DESIGN_CSS) })] }), _jsxs("body", { children: [raw(nav), _jsx("header", { class: "report-hero texture-noise", children: _jsx("div", { class: "report-container", children: _jsxs("div", { class: "report-content", children: [_jsx("p", { class: "report-eyebrow", children: HERO_EYEBROW }), _jsx("h1", { class: "report-display", children: title })] }) }) }), _jsxs("main", { children: [raw(content), references.length > 0 ? raw(references) : null] }), _jsx("footer", { class: "report-footer", children: _jsx("div", { class: "report-container", children: _jsxs("div", { class: "report-content report-footer-row", children: [_jsx("span", { class: "report-footer-title", children: title }), _jsx("span", { class: "report-footer-note", children: FOOTER_NOTE })] }) }) }), dataAssets.map((asset) => (_jsx("script", { src: stagedSource(asset.name) }))), dataAssets.length > 0 ? _jsx("script", { children: raw(TABLE_DATA_DECODER) }) : null, _jsx("script", { children: raw(THEME_REGISTRATION) }), _jsx("script", { children: raw(FADE_IN_OBSERVER) }), grids ? _jsx("script", { children: raw(GRID_BOOTSTRAP) }) : null, _jsx("script", { children: raw(CHART_BOOTSTRAP) }), _jsx("script", { children: raw(SECTION_SPY) })] })] })));
+        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(ASSET_HEAD), grids ? raw(GRID_ASSET_HEAD) : null, provenanceAssets.length > 0 ? raw(LINEAGE_ASSET_HEAD) : null, _jsx("style", { children: raw(DESIGN_CSS) })] }), _jsxs("body", { children: [raw(nav), _jsx("header", { class: "report-hero texture-noise", children: _jsx("div", { class: "report-container", children: _jsxs("div", { class: "report-content", children: [_jsx("p", { class: "report-eyebrow", children: HERO_EYEBROW }), _jsx("h1", { class: "report-display", children: title })] }) }) }), _jsxs("main", { children: [raw(content), references.length > 0 ? raw(references) : null] }), _jsx("footer", { class: "report-footer", children: _jsx("div", { class: "report-container", children: _jsxs("div", { class: "report-content report-footer-row", children: [_jsx("span", { class: "report-footer-title", children: title }), _jsx("span", { class: "report-footer-note", children: FOOTER_NOTE })] }) }) }), provenanceAssets.map((asset) => (_jsx("script", { src: stagedSource(asset.name) }))), dataAssets.map((asset) => (_jsx("script", { src: stagedSource(asset.name) }))), dataAssets.length > 0 ? _jsx("script", { children: raw(TABLE_DATA_DECODER) }) : null, _jsx("script", { children: raw(THEME_REGISTRATION) }), _jsx("script", { children: raw(FADE_IN_OBSERVER) }), grids ? _jsx("script", { children: raw(GRID_BOOTSTRAP) }) : null, _jsx("script", { children: raw(CHART_BOOTSTRAP) }), _jsx("script", { children: raw(SECTION_SPY) }), provenanceAssets.length > 0 ? _jsx("script", { children: raw(LINEAGE_POPOVER) }) : null] })] })));
 }

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

@@ -10,6 +10,7 @@
  */
 import type { ClaimBlock, SectionBlock, TextBlock } from "../../contracts/report-blocks.js";
 import type { ReferenceLedger } from "../references.js";
+import { type ViewOptions } from "./lineage.js";
 /**
  * Render a text block as escaped paragraphs, and then its list.
  *
@@ -23,8 +24,13 @@ export declare function renderText(block: TextBlock): string;
  * 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. An artifact binding and a citation binding read the same
  * bracket, because one ladder counts them both.
+ *
+ * `view.lineage` states that the page carries a provenance document. The claim renders as paragraphs and it
+ * has no container of its own, thus one wrapper takes the stamp of the whole block. The wrapper carries no
+ * class, thus it adds no rule to the design sheet and each paragraph keeps its own spacing. A page with no
+ * document renders the paragraphs alone.
  */
-export declare function renderClaim(block: ClaimBlock, ledger: ReferenceLedger): string;
+export declare function renderClaim(block: ClaimBlock, ledger: ReferenceLedger, view?: ViewOptions): 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

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

@@ -10,6 +10,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "hono/jsx/jsx-
  * item takes the same escape as a paragraph, thus no item reaches the page as markup.
  */
 import { raw } from "hono/html";
+import { DEFAULT_VIEW_OPTIONS, lineagePlace, lineageStamp } from "./lineage.js";
 import { Marker } from "./references-view.js";
 /** The paragraph class of a text block and a claim block. The paragraph fills the content column. */
 const PARAGRAPH_CLASS = "report-prose";
@@ -57,15 +58,18 @@ export function renderText(block) {
  * 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. An artifact binding and a citation binding read the same
  * bracket, because one ladder counts them both.
+ *
+ * `view.lineage` states that the page carries a provenance document. The claim renders as paragraphs and it
+ * has no container of its own, thus one wrapper takes the stamp of the whole block. The wrapper carries no
+ * class, thus it adds no rule to the design sheet and each paragraph keeps its own spacing. A page with no
+ * document renders the paragraphs alone.
  */
-export function renderClaim(block, ledger) {
-    const markers = block.bindings.map((reference) => _jsx(Marker, { n: ledger.mark(reference) }));
+export function renderClaim(block, ledger, view = DEFAULT_VIEW_OPTIONS) {
+    const markers = block.bindings.map((reference, index) => _jsx(Marker, { n: ledger.mark(reference), lineage: lineagePlace(view.lineage, reference, index) }));
     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] }))) }));
+    const body = paragraphs.length === 0 ? (_jsx("p", { class: PARAGRAPH_CLASS, children: markers })) : (_jsx(_Fragment, { children: paragraphs.map((paragraph, index) => (_jsxs("p", { class: PARAGRAPH_CLASS, children: [paragraph, index === last ? markers : null] }))) }));
+    return String(view.lineage ? _jsx("div", { ...lineageStamp(view.lineage, block.id, block.bindings), children: body }) : body);
 }
 /** The heading class of a section, by heading level. A heading uses the sans family, never the mono family. */
 function headingClass(level) {