mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/nbrender/CONTRACT.md

@@ -0,0 +1,212 @@
+# nbrender component contract
+
+`nbrender` turns nbformat 4.x JSON into one self-contained HTML string using the stdlib alone.
+This file records how its modules fit together: which module owns which surface, what shared API
+each may rely on, and the conventions all of them follow. Every hex, size, and geometry of the
+design system lives in `tokens.py`; no other module writes a literal color or pixel value.
+
+Component ids (`A01` through `MR01`) name the individual rendered surfaces — header, gutter prompt,
+DataFrame, traceback, and so on. They appear throughout the code comments and are defined by the
+ownership map below.
+
+## Hard rules
+
+- **stdlib-only**: `json`, `html`, `html.parser`, `tokenize`, `re`, `textwrap`. No pip deps — no
+  nbconvert, pygments, markdown, or webfont fetch.
+- **Escape everything from notebook JSON** through `parse.esc` (or a helper that calls it) at the
+  point of interpolation. Untrusted HTML output (D21) is sandboxed by its owner, not trusted.
+- **No emoji / decorative unicode.** The glyphs `▸ ⋯ ↯ − ·` are the sanctioned iconography.
+- **Terse technical copy** in any user-visible string: one fact per sentence, no fluff.
+- **Sanctioned deviations** — the deliberate limits of this renderer; do not add others:
+  stdlib-only; `static` + `embed` modes (`connected` = CSS/states only, no kernel wiring);
+  C14 renders TeX **source** in the display well labeled `math · TeX source`; D19 omits the
+  "open in table view →" link in static mode; `mr-data view` keeps its SSE reload script.
+
+## Ownership map
+
+Shared layers:
+
+| File | Owns |
+|---|---|
+| `tokens.py` | Every design-system constant; `build_css(mode)` — the **only** stylesheet. |
+| `parse.py` | Model dataclasses, `RenderContext`, and every shared parse/escape helper. |
+| `document.py` | Shell + layout, `.ipynb` -> component routing, pending/unsupported wells. |
+| `__init__.py` | Re-exports `render_notebook`. |
+
+Component modules:
+
+| File | Component IDs | Public functions |
+|---|---|---|
+| `chrome.py` | A01–A05 | `render_header`, `render_toolbar`, `render_kernel_pill`, `render_outline`, `render_footer` |
+| `frame.py` | B06–B11 | `render_prompt`, `cell_state_classes`, `render_hover_toolbar`, `render_collapse_bar`, `render_tags`, `render_exec_meta` |
+| `code_body.py` | C12, C14, C15 | `render_code_input`, `render_math`, `render_raw` |
+| `markdown_body.py` | C13, F29 | `render_markdown`, `render_entity_chip` |
+| `outputs_text.py` | D16, D17, D18, D23, D24 | `render_stdout`, `render_stderr`, `render_result_text`, `render_traceback`, `render_progress` |
+| `outputs_rich.py` | D19, D20, D21, D22 | `render_dataframe`, `render_figure`, `render_html`, `render_json` |
+| `interactive.py` | E25, E26 | `render_widget`, `render_stale_banner` |
+| `mr_components.py` | F27, F28 | `render_provenance`, `render_leakage` |
+| `outputs_data.py` | MR01 | `render_column_profiles` |
+
+Tests live in `tests/nbrender/`: `test_chrome.py`, `test_frame.py`, `test_code_body.py`,
+`test_markdown.py`, `test_outputs_text.py`, `test_outputs_rich.py`, `test_interactive_mr.py`
+(covers both `interactive.py` and `mr_components.py`), `test_acceptance.py` over whole rendered
+documents, and the shared `test_scaffold.py` — do not weaken its assertions.
+
+Every public function returns an **HTML string** (except `cell_state_classes`, which returns a
+space-joined class fragment or `""`). `document._slot` wraps each call and substitutes a pending
+well if a component raises `NotImplementedError`; no module raises it, so that path is a defensive
+fallback, not an expected state.
+
+## How `document` dispatches
+
+Per cell, in the 62px grid:
+
+- **Gutter** = `frame.render_prompt` (B06).
+- **Code cell content** = `[frame.render_hover_toolbar` (B08)`] + code_body.render_code_input` (C12),
+  wrapped in `.nb-panel.nb-code` with `frame.cell_state_classes` (B07) applied; then each output via
+  the output router below; then `frame.render_exec_meta` (B11) for executed cells.
+- **Markdown cell content** = `[frame.render_tags` (B10) when tags present`] + markdown_body.render_markdown`
+  (C13). C13 calls `parse.split_entity_refs` and `markdown_body.render_entity_chip` (F29) for refs,
+  and `code_body.render_math` (C14) for `$…$`/`$$…$$`.
+- **Raw cell content** = `code_body.render_raw` (C15).
+
+The `.nb-io` row owns the 10px (the value `IO_GAP_PX` records) input-to-output gap and resets the
+top margin of every child of its `.nb-io-body`, so the row supplies that one gap and no output adds
+a second — not even an output that renders as several sibling roots, as E26 + E25 does. The one
+exception is the welded first output: a first plain stdout stream (`document._is_weldable_well`)
+is appended outside any row and welds flush to the panel, with no gap at all. D17's own
+`margin-top: 12px` was retired for that uniform 10px (SPEC D17, amended 2026-08-12); the stderr
+well keeps its dashed `border-top` and 11px top padding.
+
+Output router (`document._render_output`), by `Output.kind` then `Output.primary_mimetype()`:
+
+| Condition | Component |
+|---|---|
+| `stream-stdout`, not tqdm | D16 |
+| `stream-stdout`, tqdm pattern | D24 |
+| `stream-stderr` | D17 |
+| `error` | D23 |
+| `text/html` containing `class="dataframe"` | D19 |
+| `text/html` otherwise | D21 |
+| `image/svg+xml` or `image/png` | D20 |
+| `application/json` | D22 |
+| `text/plain`, tqdm pattern | D24 |
+| `text/plain` otherwise | D18 |
+| `application/vnd.jupyter.widget-view+json` | E26 (static/embed) then E25 |
+| `application/vnd.mostlyright.column-profile.v1+json` | MR01 |
+| any other mimetype | unsupported well (owned by `document`) |
+
+Notebook level: F27 once at document top when `notebook.provenance` present; F28 after the cell an
+entry's integer `cell` index names (else trailing).
+
+## `RenderContext` and model reference (`parse.py`)
+
+`RenderContext`: `mode: str` (static/connected/embed) · `cell_index: int` · `cell_count: int` ·
+`prev_execution_count: int | None` (previous **code** cell's count, for B11 out-of-order).
+
+`Notebook`: `nbformat: int` · `nbformat_minor: int` · `metadata: dict` · `cells: list[Cell]` ·
+`.provenance -> dict | None` (F27) · `.leakage -> list[dict]` (F28).
+
+`Cell`: `cell_id: str` (nbformat `id`, or a deterministic parse fallback) · `cell_type: str`
+(markdown/code/raw/unknown) · `source: str` (raw, unescaped) ·
+`metadata: dict` · `execution_count: int | None` · `outputs: list[Output]` ·
+`.tags -> list[str]` (the four known B10 tags, in display order).
+
+`Output`: `kind: str` (stream-stdout/stream-stderr/execute_result/display_data/error/unknown) ·
+`text: str` (raw stream/plain text, ANSI intact) · `data: dict` (normalized mimetype bundle) ·
+`metadata: dict` · `execution_count: int | None` · `ename/evalue: str | None` ·
+`traceback: list[str]` · `.primary_mimetype() -> str | None` · `.text_of(mimetype) -> str`.
+
+## MR01 portable column-profile output
+
+The generator stores the inspector in a normal `display_data` MIME bundle. The structured
+`application/vnd.mostlyright.column-profile.v1+json` member is the rich contract. The same bundle
+must also contain `text/html` and `text/plain` fallbacks so an ordinary Jupyter viewer never shows
+an empty or unsupported output. The structured member is data only; it contains no executable
+markup.
+
+Every Parquet column appears exactly once and records logical type, physical type, declared unit,
+missing count/rate, distinct count/rate and exact-or-sampled status, a type-appropriate summary and
+chart, source column, and transformations. Units come from a sealed Recipe's `output_semantics`.
+The renderer never guesses a unit: older Builds say `Not declared`, while non-measure fields
+with an explicit `unit: none` say `Not applicable`.
+
+The v1 envelope may add an optional `mostlyright.column-semantics.v1` sub-document and additive
+per-column semantic fields. Bump the outer MIME version only when an existing field changes
+meaning or a required field is added or removed. An absent sub-document means “not declared,” not
+an invalid payload. The four unit states are `declared`, `normalized`, `not_applicable`, and
+`unknown`; the legacy `unit.label` must remain a truthful fallback for each state.
+
+The generator may reduce optional rich fields to remain below the 1 MiB MIME bound. The complete
+sealed text remains in the notebook Overview and Data dictionary markdown cells and in the HTML
+and plain-text fallbacks. Every renderer escapes semantic strings and never treats source content
+as approval.
+
+The portable fallbacks carry bounded dataset and column semantic sections independently of any
+rich-MIME reduction. Fixed limits cover text, limitations, categorical definitions, and columns;
+an omitted tail always produces an explicit deterministic truncation notice. Recipe semantics may
+say `approved_recipe` only after the generator has verified the sealed approval digest and current
+Recipe execution/acquisition bindings, never from member names alone.
+
+The interactive semantic banner renders summary, row grain, time/population/completeness coverage,
+and limitations. If the bounded MIME reduction ladder omits semantic detail, `render_scope` remains
+present and the banner explicitly names the omitted field groups and points to the portable
+fallbacks; reduction never silently turns a semantic-bearing payload into a no-semantics payload.
+Large verified string values may produce oversized summary or chart labels. The final rich-profile
+reduction step truncates those derived presentation strings with an explicit `[truncated]` marker,
+while retaining semantic authority and the analytical profile shape, before it may refuse the MIME.
+Portable categorical definitions always include their `complete` or `partial` mapping status.
+
+Semantic evidence references are bounded `source_id` values. The generator accepts them only
+after the table-semantics contract has bound each identifier to a source in the same sealed
+Recipe or local plan; the renderer presents them as references, never as approvals.
+
+`outputs_data.py` escapes every value and emits all profiles into one in-place selector. The
+selector is progressive enhancement owned by the local workbench; without JavaScript the first
+profile and the portable fallbacks remain readable. Charts are passive inline SVG authored only by
+the trusted renderer from escaped scalar values—never notebook-supplied SVG. Distribution-axis
+labels use a deterministic two-row layout and geometry-bounded middle abbreviation. Each bar's
+escaped `<title>` retains the complete label and count, and a visually hidden table exposes the
+same bounded data to assistive technology.
+
+## Helper inventory
+
+`parse.py`:
+- `esc(value) -> str` — HTML-escape any value, quotes included; coerces non-strings.
+- `strip_ansi(value) -> StrippedAnsi(text, bold)` — strip SGR; `bold` flags any SGR-1 seen.
+- `detect_tqdm(text) -> TqdmProgress(fraction, label, stat) | None`.
+- `split_entity_refs(source) -> list[str | EntityRef(type, id)]`.
+- `parse_notebook(nb: dict) -> Notebook` — tolerant; never raises on bad shapes.
+- Constants: `MIMETYPE_PRECEDENCE`, `KNOWN_TAGS`.
+
+`tokens.py`:
+- Color constants (core + viewer-only), `CSS_TOKENS` (css-var name -> hex).
+- `FONT_SANS`, `FONT_MONO`, `TYPE_SCALE` (role -> family/size/weight/line-height/notes).
+- Geometry: `GUTTER_PX`, `CELL_GAP_PX`, `IO_GAP_PX`, `RADIUS`, `SHELL_*`, `OUTLINE_WIDTH_PX`.
+- `KEYFRAMES`, `HOVER_TRANSITION`, `VALID_MODES`.
+- `build_css(mode) -> str` — the whole stylesheet.
+
+## Class-name convention
+
+All classes are `nb-`-prefixed, kebab-case: block `nb-<component>` (e.g. `nb-df`), element
+`nb-<component>-<part>` (e.g. `nb-df-caption`), modifier `nb-<component>--<variant>` (e.g.
+`nb-kernel--busy`). Transient state uses `is-<state>` (e.g. `nb-panel.is-running`). Every class a
+component emits must resolve against a rule in `build_css`.
+
+## Changing shared behavior
+
+`tokens.py` is the single stylesheet: add a rule or a token there rather than inlining a style in a
+component, so one edit reaches every module and the palette cannot drift. The same holds for
+`parse.py` (shared parse and escape helpers) and `document.py` (dispatch and layout) — a component
+that needs new shared behavior gets it added to the shared file rather than copied into its own
+module.
+
+## Notes for a host stylesheet
+
+A host may override `.nb-cell`'s gutter geometry, but it must then re-state `.nb-io` with
+`margin-left` equal to its own gutter track plus its column gap — the row re-enters the gutter by
+that exact distance, so leaving nbrender's base pull-back in place skews `Out [n]` away from
+`In [n]`. Restack the host's notebook rules under `@container`, never `@media`: nbrender's
+breakpoints resolve against `.nb-shell`'s inline size (`container-type: inline-size`), which is
+narrower than the viewport by whatever the host's own layout spends on padding, so a viewport-keyed
+override disagrees with nbrender across a band of widths.

mostlyright/data_harness/nbrender/__init__.py

@@ -0,0 +1,12 @@
+"""Stdlib-only, static-first Jupyter notebook renderer.
+
+nbformat 4.x JSON in, one self-contained HTML string out — no nbconvert, no pygments, no markdown
+library, no webfont fetch.  ``render_notebook`` is the single public entry point; the modules
+behind it are documented in ``CONTRACT.md``.
+"""
+
+from __future__ import annotations
+
+from mostlyright.data_harness.nbrender.document import render_notebook
+
+__all__ = ["render_notebook"]

mostlyright/data_harness/nbrender/chrome.py

@@ -0,0 +1,359 @@
+"""Group A · chrome (A01-A05): header, toolbar, kernel pill, outline rail, repro footer.
+
+Dispatched from ``document.render_notebook``.  Every string interpolated from notebook JSON —
+filename, breadcrumb path, kernelspec, env hash — passes through :func:`parse.esc` at the point of
+interpolation.  Two header strings are fixed design copy rather than notebook data: the "saved"
+line and the kernel pill labels (an exported notebook carries neither a save clock nor a kernel).
+Header height is mode-invariant: in ``static`` the primary button reads "Download .ipynb" rather
+than vanishing.  Toolbar (A02) is emitted only in ``connected``; ``build_css`` already hides
+``.nb-toolbar`` elsewhere.
+
+Class-name convention (CONTRACT.md): every class emitted resolves against a rule in
+``tokens.build_css`` — including the toolbar Run accent, the minimap type tints/heights (the two
+tints ``#E5E9F6``/``#FBE4DA`` are ``--nb-minimap-*`` tokens, the three bar heights are
+``.nb-minimap-h-*`` rules), and the outline "Cells" top gap (``.nb-outline-label--cells``).  No
+styling is inlined here; every design-system value lives in ``tokens``.
+"""
+
+from __future__ import annotations
+
+import re
+
+from mostlyright.data_harness.nbrender.parse import (
+    Notebook,
+    RenderContext,
+    esc,
+    heading_text,
+    slugify,
+)
+
+# --- A03 kernel pill --------------------------------------------------------------------------
+# state key -> label; the key doubles as the ``nb-kernel--<state>`` class modifier.  The labels are
+# fixed design copy, not notebook data — nothing here reads the kernelspec, and the interpreter
+# version and queue depth are literal text.  ``render_header`` only ever asks for ``idle``
+# (connected mode) or ``none``.  The middot and em dash are literal punctuation, not iconography.
+_KERNEL_LABELS: dict[str, str] = {
+    "idle": "python 3.12 · idle",
+    "busy": "python 3.12 · busy",
+    "queued": "python 3.12 · queued (3)",
+    "dead": "kernel dead — restart",
+    "none": "no kernel",
+}
+
+
+def render_kernel_pill(state: str, ctx: RenderContext) -> str:
+    """A03 · kernel status pill — idle/busy/queued/dead/none dot and label. Composed by A01.
+
+    An unknown ``state`` degrades to ``none`` ("no kernel") rather than raising, so a caller that
+    passes a stale kernel status still yields a well-formed pill.
+    """
+    key = state if state in _KERNEL_LABELS else "none"
+    label = _KERNEL_LABELS[key]
+    return (
+        f'<span class="nb-kernel nb-kernel--{key}">'
+        '<span class="nb-kernel-dot" aria-hidden="true"></span>'
+        f"{esc(label)}"
+        "</span>"
+    )
+
+
+# --- A01 header -------------------------------------------------------------------------------
+
+
+def _path_segments(filename: str) -> list[str]:
+    """Split a notebook path into non-empty segments, tolerant of both slash styles."""
+    text = str(filename).replace("\\", "/")
+    return [seg for seg in text.split("/") if seg]
+
+
+def _basename(filename: str) -> str:
+    """Last path segment — the filename shown in the header title line."""
+    segs = _path_segments(filename)
+    return segs[-1] if segs else str(filename)
+
+
+def _brand_mark(size: int = 26) -> str:
+    """The multi-color facet mark: ``--m1`` paper plus the standard orange/yellow/cobalt facets.
+
+    Rendered as inline SVG so no external asset is fetched; facet fills reference palette tokens
+    (``--m1`` == paper) rather than re-declaring hexes.  Decorative, so ``aria-hidden``.
+    """
+    return (
+        f'<svg width="{size}" height="{size}" viewBox="0 0 26 26" '
+        'aria-hidden="true" focusable="false">'
+        '<rect x="0" y="0" width="11" height="11" rx="2" fill="var(--nb-paper)"></rect>'
+        '<rect x="15" y="0" width="11" height="11" rx="2" fill="var(--nb-orange)"></rect>'
+        '<rect x="0" y="15" width="11" height="11" rx="2" fill="var(--nb-yellow)"></rect>'
+        '<rect x="15" y="15" width="11" height="11" rx="2" fill="var(--nb-cobalt)"></rect>'
+        "</svg>"
+    )
+
+
+def _breadcrumb_html(filename: str) -> str:
+    """Breadcrumb trail from the path: ``/`` separators, the deepest crumb highlighted."""
+    segs = _path_segments(filename) or [str(filename)]
+    last = len(segs) - 1
+    pieces: list[str] = []
+    for i, seg in enumerate(segs):
+        if i == last:
+            pieces.append(f'<span class="nb-header-crumb-last">{esc(seg)}</span>')
+        else:
+            pieces.append(f"<span>{esc(seg)}</span>")
+    sep = '<span class="nb-header-crumb-sep"> / </span>'
+    return '<div class="nb-header-crumbs">' + sep.join(pieces) + "</div>"
+
+
+def render_header(nb: Notebook, ctx: RenderContext, filename: str) -> str:
+    """A01 · notebook header — brand mark, breadcrumb + filename block, kernel pill, actions.
+
+    Height is mode-invariant.  In ``connected`` the kernel pill shows ``idle`` and the primary
+    button runs the notebook; in every other mode the pill reads ``no kernel`` and the primary
+    button downloads the source, so the bar never collapses.  The breadcrumb and filename come from
+    ``filename``; the "saved" line below them is fixed copy.
+    """
+    mark = _brand_mark(26)
+    crumbs = _breadcrumb_html(filename)
+    base = _basename(filename)
+    kernel_state = "idle" if ctx.mode == "connected" else "none"
+    pill = render_kernel_pill(kernel_state, ctx)
+    ghost = '<button class="nb-btn-ghost" type="button">Raw</button>'
+    primary_label = "Run all" if ctx.mode == "connected" else "Download .ipynb"
+    primary = f'<button class="nb-btn-primary" type="button">{esc(primary_label)}</button>'
+    return (
+        '<header class="nb-header">'
+        '<div class="nb-header-id">'
+        f"{mark}"
+        '<div class="nb-header-block">'
+        f"{crumbs}"
+        f'<div class="nb-header-file" title="{esc(base)}">{esc(base)}</div>'
+        # Fixed design copy, not a measured value: an exported notebook has no save clock.
+        '<div class="nb-header-saved">saved 4m ago</div>'
+        "</div>"
+        "</div>"
+        '<div class="nb-header-actions">'
+        f"{pill}{ghost}{primary}"
+        "</div>"
+        "</header>"
+    )
+
+
+# --- A02 toolbar (connected only; CSS hides it in static/embed) -------------------------------
+
+
+def render_toolbar(nb: Notebook, ctx: RenderContext) -> str:
+    """A02 · toolbar — run/stop/restart, add-cell, cell count, clear/download.
+
+    Full markup is always produced; visibility is mode-gated in ``build_css`` (hidden in static
+    and embed).  ``document`` only calls this in ``connected``.  The cell count is derived from the
+    notebook: total cells, then code cells carrying an execution count.
+    """
+    total = len(nb.cells)
+    executed = sum(1 for c in nb.cells if c.cell_type == "code" and c.execution_count is not None)
+    count = f"{total} cells · {executed} executed"
+
+    # 9x10 solid play triangle · A02.  Fill references the ink token; the rest accent (ink
+    # color + 6px gap) is carried by the registered `.nb-toolbar-btn--run` rule, no inline style.
+    triangle = (
+        '<svg width="9" height="10" viewBox="0 0 9 10" aria-hidden="true" focusable="false">'
+        '<path d="M0 0 L9 5 L0 10 Z" fill="var(--nb-ink)"></path></svg>'
+    )
+    run = f'<button class="nb-toolbar-btn nb-toolbar-btn--run" type="button">{triangle}Run</button>'
+
+    def btn(label: str) -> str:
+        return f'<button class="nb-toolbar-btn" type="button">{esc(label)}</button>'
+
+    divider = '<span class="nb-toolbar-divider" aria-hidden="true"></span>'
+    return (
+        '<div class="nb-toolbar">'
+        f"{run}{btn('Stop')}{btn('Restart')}"
+        f"{divider}"
+        f"{btn('+ Code')}{btn('+ Markdown')}"
+        '<span class="nb-toolbar-spacer"></span>'
+        f'<span class="nb-toolbar-count">{esc(count)}</span>'
+        f"{divider}"
+        f"{btn('Clear outputs')}{btn('Download .ipynb')}"
+        "</div>"
+    )
+
+
+# --- A04 outline rail -------------------------------------------------------------------------
+
+_HEADING_RE = re.compile(r"^(#{1,6})\s+(.*?)\s*#*\s*$")
+_FENCE_RE = re.compile(r"^\s*(```|~~~)")
+
+
+def _headings(nb: Notebook) -> list[tuple[int, str]]:
+    """ATX headings from markdown cells only, skipping fenced code.  Returns (level, text)."""
+    out: list[tuple[int, str]] = []
+    for cell in nb.cells:
+        if cell.cell_type != "markdown":
+            continue
+        in_fence = False
+        for line in cell.source.splitlines():
+            if _FENCE_RE.match(line):
+                in_fence = not in_fence
+                continue
+            if in_fence:
+                continue
+            m = _HEADING_RE.match(line)
+            if m:
+                text = heading_text(m.group(2))
+                if text:
+                    out.append((len(m.group(1)), text))
+    return out
+
+
+def _minimap_type(cell) -> str:
+    """Minimap stripe/bar class for a cell: md/code/err/raw (unknown recedes to raw)."""
+    if cell.cell_type == "markdown":
+        return "md"
+    if cell.cell_type == "raw":
+        return "raw"
+    if cell.cell_type == "code":
+        if any(o.kind == "error" for o in cell.outputs):
+            return "err"
+        return "code"
+    return "raw"
+
+
+def _length_bucket(source: str) -> str:
+    """Bucket a cell's length into the three minimap bar heights by trimmed source size."""
+    n = len((source or "").strip())
+    if n <= 120:
+        return "short"
+    if n <= 480:
+        return "medium"
+    return "long"
+
+
+def _minimap(nb: Notebook) -> str:
+    """One decorative row per cell: a type stripe plus a length-encoded bar.
+
+    Stripe/bar tints (by cell type) and the three bar heights (by length bucket) are class-driven —
+    the two non-palette tints live as ``--nb-minimap-*`` tokens and the heights as
+    ``.nb-minimap-h-*`` rules — so no styling is inlined here.
+    """
+    rows: list[str] = []
+    for cell in nb.cells:
+        kind = _minimap_type(cell)
+        height = f"nb-minimap-h-{_length_bucket(cell.source)}"
+        rows.append(
+            '<div class="nb-minimap-row" aria-hidden="true">'
+            f'<span class="nb-minimap-stripe nb-minimap-stripe--{kind} {height}"></span>'
+            f'<span class="nb-minimap-bar nb-minimap-bar--{kind} {height}"></span>'
+            "</div>"
+        )
+    return "".join(rows)
+
+
+def render_outline(nb: Notebook, ctx: RenderContext) -> str:
+    """A04 · outline rail — heading tree plus per-cell minimap. Collapses below 1100px (CSS).
+
+    The heading tree is built from markdown cells; depth maps h1->0 through h4+->3 for the indent
+    ramp.  The first heading is marked active as the document-top default.  Anchor targets
+    (``#slug``) match the heading ids ``markdown_body`` emits, because both sides derive them from
+    :func:`parse.slugify` over the same heading text.
+    """
+    headings = _headings(nb)
+    links: list[str] = []
+    for i, (level, text) in enumerate(headings):
+        depth = min(level - 1, 3)
+        cls = "nb-outline-link"
+        if i == 0:
+            cls += " nb-outline-link--active"
+        links.append(
+            f'<a class="{cls}" data-depth="{depth}" href="#{esc(slugify(text))}">{esc(text)}</a>'
+        )
+
+    tree = ""
+    if links:
+        tree = '<div class="nb-outline-label">Outline</div>' + "".join(links)
+
+    # A small top gap before the second label only when a heading tree precedes it — carried by the
+    # registered `.nb-outline-label--cells` rule rather than an inline style.
+    cells_class = "nb-outline-label nb-outline-label--cells" if links else "nb-outline-label"
+    return (
+        '<nav class="nb-outline" aria-label="Notebook outline">'
+        f"{tree}"
+        f'<div class="{cells_class}">Cells</div>'
+        f"{_minimap(nb)}"
+        "</nav>"
+    )
+
+
+# --- A05 repro footer -------------------------------------------------------------------------
+
+
+def _mostlyright_block(nb: Notebook) -> dict:
+    block = nb.metadata.get("mostlyright")
+    return block if isinstance(block, dict) else {}
+
+
+def _kernel_name(nb: Notebook) -> str | None:
+    ks = nb.metadata.get("kernelspec")
+    if not isinstance(ks, dict):
+        return None
+    name = ks.get("display_name") or ks.get("name")
+    return str(name) if name else None
+
+
+def _footer_facts(nb: Notebook) -> list[str]:
+    """Repro facts in display order; absent fields are omitted, never placeholdered.
+
+    ``nbformat`` is always derivable, so the footer never renders empty.  ``kernelspec`` comes from
+    notebook metadata; the env hash, ``mostlyright`` version, and wall time come from
+    ``metadata.mostlyright`` when the run recorded them.
+    """
+    facts: list[str] = []
+    mr = _mostlyright_block(nb)
+    env = mr.get("env") or mr.get("env_hash")
+    if env:
+        facts.append(f"env {env}")
+    version = mr.get("version")
+    if version:
+        facts.append(f"mostlyright {version}")
+    wall = mr.get("wall_time") or mr.get("walltime")
+    if wall:
+        facts.append(f"wall {wall}")
+    kernel = _kernel_name(nb)
+    if kernel:
+        facts.append(kernel)
+    facts.append(f"nbformat {nb.nbformat}.{nb.nbformat_minor}")
+    return facts
+
+
+def _replay_oneliner(nb: Notebook) -> str:
+    """The ``mr.replay(...)`` one-liner the reproduce link carries: env hash, else revision.
+
+    A provenance ``revision`` is display copy carrying a parenthetical tail (the harness emits
+    ``"<digest12> (<manifest_version>)"``), and the tail is not part of the identifier.  Only the
+    leading token is used, so the link reads ``mr.replay("1ef73f4ff396")``.
+    """
+    mr = _mostlyright_block(nb)
+    ident = mr.get("env") or mr.get("env_hash")
+    if not ident:
+        prov = nb.provenance or {}
+        tokens = str(prov.get("revision") or "").split()
+        ident = tokens[0] if tokens else ""
+    if ident:
+        return f'mr.replay("{ident}")'
+    return "mr.replay()"
+
+
+def render_footer(nb: Notebook, ctx: RenderContext) -> str:
+    """A05 · repro footer — env hash, version, wall time, kernel spec, nbformat, replay link.
+
+    The reproduce link stashes the one-liner in ``data-replay``/``title`` so a connected-mode
+    script can copy it; static has no script, so the link is inert by design.
+    """
+    facts = _footer_facts(nb)
+    mid = '<span class="nb-footer-mid" aria-hidden="true">·</span>'
+    fact_html = mid.join(f"<span>{esc(text)}</span>" for text in facts)
+    replay = _replay_oneliner(nb)
+    link = (
+        '<span class="nb-footer-link" role="button" tabindex="0" '
+        f'data-replay="{esc(replay)}" title="{esc(replay)}">reproduce this run →</span>'
+    )
+    return (
+        f'<footer class="nb-footer"><div class="nb-footer-facts">{fact_html}</div>{link}</footer>'
+    )