mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/nbrender/code_body.py

@@ -0,0 +1,266 @@
+"""Group C · code bodies (C12, C14, C15): code input, LaTeX math, raw cell.
+
+Dispatched from ``document`` (markdown C13 lives in ``markdown_body``).  The six-color syntax theme
+is driven by the stdlib ``tokenize`` module over the cell source — never a pip highlighter — and a
+tokenizer error must fall back to the escaped source, never a raw dump.  Math (C14) renders TeX
+source, not glyphs: no formula renderer is bundled, so the display well shows escaped TeX under the
+mono label ``math · TeX source``.  Every rendered string originates in notebook JSON and must pass
+through :func:`parse.esc`.
+
+Reconstruction discipline — copying a code panel must yield exactly the cell source: the highlighter
+rebuilds the panel text by slicing the original source between token spans, so the concatenated
+text content of the ``<pre>`` is byte-identical to ``cell.source``.  Only the five accent
+categories are wrapped in a span; identifiers, operators, and whitespace stay bare and inherit the
+base ``#CFC9BB`` from ``.nb-code pre``.  Line numbers, when enabled, live in a separate
+``aria-hidden`` element that the copy selection excludes.
+"""
+
+from __future__ import annotations
+
+import tokenize
+from typing import Any
+
+from mostlyright.data_harness.nbrender.parse import Cell, RenderContext, esc
+
+# --- C12 six-color syntax theme ---------------------------------------------------------------
+# Keywords / imports / control flow -> keyword color.  True/False/None are excluded here so they
+# land in the number color, which covers "number, boolean, None".  The ``keyword`` module is not
+# on the stdlib allow-list, so the hard-keyword set is pinned locally; Python's keywords are
+# stable and soft keywords (match/case/type) are intentionally left as identifiers.
+_KEYWORDS = frozenset(
+    {
+        "and",
+        "as",
+        "assert",
+        "async",
+        "await",
+        "break",
+        "class",
+        "continue",
+        "def",
+        "del",
+        "elif",
+        "else",
+        "except",
+        "finally",
+        "for",
+        "from",
+        "global",
+        "if",
+        "import",
+        "in",
+        "is",
+        "lambda",
+        "nonlocal",
+        "not",
+        "or",
+        "pass",
+        "raise",
+        "return",
+        "try",
+        "while",
+        "with",
+        "yield",
+    }
+)
+_CONSTANTS = frozenset({"True", "False", "None"})
+
+# STRING plus the 3.12+ f-string token trio, resolved by name so older/newer runtimes both work.
+_STRING_TYPES = {tokenize.STRING}
+for _name in ("FSTRING_START", "FSTRING_MIDDLE", "FSTRING_END"):
+    _tok = getattr(tokenize, _name, None)
+    if _tok is not None:
+        _STRING_TYPES.add(_tok)
+_STRING_TYPES = frozenset(_STRING_TYPES)
+
+_ENCODING = getattr(tokenize, "ENCODING", None)
+
+_TOK_COMMENT = "nb-tok-com"
+_TOK_STRING = "nb-tok-str"
+_TOK_NUMBER = "nb-tok-num"
+_TOK_KEYWORD = "nb-tok-kw"
+_TOK_FN = "nb-tok-fn"
+
+_MATH_LABEL = "math · TeX source"
+
+
+def _row_slice(lines: list[str], start: tuple[int, int], end: tuple[int, int]) -> str:
+    """Exact source text between two ``(row, col)`` tokenize positions (rows 1-based).
+
+    Out-of-range rows (the EOF ``NEWLINE``/``ENDMARKER`` sit one row past the last line) clamp to
+    an empty string so reconstruction never indexes past the source.
+    """
+    (srow, scol), (erow, ecol) = start, end
+    count = len(lines)
+
+    def row(index: int) -> str:
+        return lines[index - 1] if 1 <= index <= count else ""
+
+    if srow == erow:
+        return row(srow)[scol:ecol]
+    parts = [row(srow)[scol:]]
+    parts.extend(row(index) for index in range(srow + 1, erow))
+    parts.append(row(erow)[:ecol])
+    return "".join(parts)
+
+
+def _is_call(toks: list[Any], index: int) -> bool:
+    """True when the token after ``index`` is an opening paren — a function call name.
+
+    Whitespace is not a token, so the immediate successor is the syntactically adjacent one;
+    ``foo(`` and ``foo (`` both qualify while ``foo.bar`` and ``foo[0]`` do not.
+    """
+    nxt = toks[index + 1] if index + 1 < len(toks) else None
+    return nxt is not None and nxt.type == tokenize.OP and nxt.string == "("
+
+
+def _readline(source: str):
+    """A ``readline`` callable over ``source`` without importing ``io`` (off the allow-list)."""
+    lines = iter(source.splitlines(keepends=True))
+
+    def readline() -> str:
+        return next(lines, "")
+
+    return readline
+
+
+def _highlight(source: str) -> str:
+    """Six-color tokenize highlight of ``source``; any tokenizer fault degrades to escaped text.
+
+    The whole tokenize-and-reconstruct is guarded: a ``TokenError``, ``IndentationError``, a null
+    byte, or any other malformed-source failure returns ``esc(source)`` — highlighted source and
+    the fallback are both exactly the escaped source, so a bad cell never blanks or dumps raw.
+    """
+    if not source:
+        return ""
+    lines = source.splitlines(keepends=True)
+    try:
+        toks = list(tokenize.generate_tokens(_readline(source)))
+        out: list[str] = []
+        last = (1, 0)
+        at_line_start = True
+        in_decorator = False
+        for i, tok in enumerate(toks):
+            ttype = tok.type
+            tstr = tok.string
+            if _ENCODING is not None and ttype == _ENCODING:
+                continue
+            start, end = tok.start, tok.end
+            if start >= last:
+                gap = _row_slice(lines, last, start)
+                if gap:
+                    out.append(esc(gap))
+            text = _row_slice(lines, start, end)
+
+            cls: str | None = None
+            if ttype == tokenize.COMMENT:
+                cls = _TOK_COMMENT
+            elif ttype in _STRING_TYPES:
+                cls = _TOK_STRING
+            elif ttype == tokenize.NUMBER:
+                cls = _TOK_NUMBER
+            elif ttype == tokenize.NAME:
+                if tstr in _KEYWORDS:
+                    cls = _TOK_KEYWORD
+                elif tstr in _CONSTANTS:
+                    cls = _TOK_NUMBER
+                elif in_decorator:
+                    cls = _TOK_FN
+                elif _is_call(toks, i):
+                    cls = _TOK_FN
+            elif ttype == tokenize.OP:
+                if tstr == "@" and at_line_start:
+                    in_decorator = True
+                    cls = _TOK_FN
+                elif in_decorator and tstr == ".":
+                    cls = _TOK_FN
+                elif in_decorator and tstr == "(":
+                    in_decorator = False
+
+            if text:
+                out.append(f'<span class="{cls}">{esc(text)}</span>' if cls else esc(text))
+            if end >= last:
+                last = end
+
+            if ttype in (tokenize.NEWLINE, tokenize.NL):
+                at_line_start = True
+                in_decorator = False
+            elif ttype in (tokenize.INDENT, tokenize.DEDENT, tokenize.COMMENT):
+                pass  # leading trivia keeps the line-start flag for a following decorator
+            else:
+                at_line_start = False
+        return "".join(out)
+    except Exception:
+        return esc(source)
+
+
+def _wants_line_numbers(cell: Cell) -> bool:
+    """Line numbers are off by default; a cell opts in via ``metadata.line_numbers`` (or the
+    ``metadata.jupyter.line_numbers`` nesting)."""
+    meta = cell.metadata if isinstance(cell.metadata, dict) else {}
+    if meta.get("line_numbers") is True:
+        return True
+    jupyter = meta.get("jupyter")
+    return isinstance(jupyter, dict) and jupyter.get("line_numbers") is True
+
+
+def _line_number_column(source: str) -> str:
+    """The right-aligned, copy-excluded line-number rail for the code panel."""
+    count = max(1, len(source.splitlines()))
+    numbers = "\n".join(str(n) for n in range(1, count + 1))
+    return f'<pre class="nb-lineno" aria-hidden="true">{esc(numbers)}</pre>'
+
+
+def render_code_input(cell: Cell, ctx: RenderContext) -> str:
+    """C12 · code input — dark panel, tokenize-driven six-color theme, optional line numbers.
+
+    Returns the panel's inner content (the ``<pre>``, wrapped with a line-number rail when the
+    cell opts in).  The enclosing ``.nb-panel.nb-code`` div — including the welded/head radius and
+    padding modifiers — belongs to ``document``, not to this module.  The ``<pre>`` is
+    ``tabindex=0`` with an accessible name; its text content equals ``cell.source`` exactly so a
+    copy yields the source with prompts and line numbers excluded.
+    """
+    source = cell.source or ""
+    status = "executed" if cell.execution_count is not None else "not executed"
+    label = f"code cell {ctx.cell_index + 1} of {ctx.cell_count}, {status}"
+    pre = f'<pre tabindex="0" aria-label="{esc(label)}">{_highlight(source)}</pre>'
+    if _wants_line_numbers(cell):
+        return f'<div class="nb-code-lines">{_line_number_column(source)}{pre}</div>'
+    return pre
+
+
+def render_math(tex: str, ctx: RenderContext, *, display: bool) -> str:
+    """C14 · LaTeX math — escaped TeX source in the display well, labeled ``math · TeX source``.
+
+    No formula renderer (KaTeX or otherwise) is bundled, so the well shows the escaped TeX source,
+    never rendered glyphs and never a raw dump.  ``display`` distinguishes ``$$…$$`` block math from
+    inline ``$…$`` for the accessible name and a ``data-math`` hook; both use the display well.
+    """
+    kind = "display" if display else "inline"
+    body = esc((tex or "").strip())
+    return (
+        f'<div class="nb-math" data-math="{kind}" role="math" '
+        f'aria-label="{kind} math, TeX source">'
+        f'<span class="nb-math-label">{_MATH_LABEL}</span>'
+        f"<code>{body}</code>"
+        "</div>"
+    )
+
+
+def render_raw(cell: Cell, ctx: RenderContext) -> str:
+    """C15 · raw cell — receding well, mimetype label, escaped pre. Excluded from the outline.
+
+    The mimetype comes from ``metadata.raw_mimetype`` (nbformat) or ``metadata.format`` (legacy),
+    defaulting to ``text/plain``; a non-string value falls back to the default.  The source is
+    emitted verbatim through :func:`parse.esc`.
+    """
+    meta = cell.metadata if isinstance(cell.metadata, dict) else {}
+    mimetype = meta.get("raw_mimetype") or meta.get("format") or "text/plain"
+    if not isinstance(mimetype, str):
+        mimetype = "text/plain"
+    return (
+        '<div class="nb-raw">'
+        f'<span class="nb-raw-label">{esc(mimetype)}</span>'
+        f"<pre>{esc(cell.source or '')}</pre>"
+        "</div>"
+    )

mostlyright/data_harness/nbrender/document.py

@@ -0,0 +1,407 @@
+"""Top-level assembly: raw nbformat JSON to one self-contained HTML string.
+
+This module owns the shell and layout and the ``.ipynb`` -> component routing.  It renders no
+component itself — it dispatches through the routing below and wraps each call so a component that
+raises ``NotImplementedError`` degrades to a visible pending well instead of blanking the cell.  No
+component in this package raises it, so that well is a defensive fallback rather than an expected
+state.  Unknown mimetypes and cell types resolve to the labeled unsupported well here, never a raw
+dump.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from mostlyright.data_harness.nbrender import (
+    chrome,
+    code_body,
+    frame,
+    interactive,
+    markdown_body,
+    mr_components,
+    outputs_data,
+    outputs_rich,
+    outputs_source,
+    outputs_stage,
+    outputs_text,
+    tokens,
+)
+from mostlyright.data_harness.nbrender.parse import (
+    Cell,
+    Notebook,
+    Output,
+    RenderContext,
+    coalesce_stream_outputs,
+    detect_tqdm,
+    esc,
+    parse_notebook,
+)
+
+_WIDGET_MIME = "application/vnd.jupyter.widget-view+json"
+_COLUMN_PROFILE_MIME = "application/vnd.mostlyright.column-profile.v1+json"
+_STAGE_OBSERVATION_MIMES = frozenset(outputs_stage.MIMES)
+_SOURCE_OBSERVATION_MIME = outputs_source.MIME
+_STALE_WIDGET_MSG = "Widget state is frozen — no live kernel in this export."
+
+
+def _pending_well(component_id: str) -> str:
+    """Placeholder for a component that reported itself unimplemented."""
+    return (
+        f'<div class="nb-pending" data-component="{esc(component_id)}">'
+        f"component pending: {esc(component_id)}</div>"
+    )
+
+
+def _unsupported_well(label: str) -> str:
+    """Labeled well for an unknown mimetype or cell type — never a raw dump."""
+    return f'<div class="nb-unsupported">unsupported output · {esc(label)}</div>'
+
+
+def _slot(component_id: str, fn: Callable[..., str], *args: Any, **kwargs: Any) -> str:
+    """Call a component, substituting a pending well if it raises ``NotImplementedError``.
+
+    Only ``NotImplementedError`` is caught; any real fault surfaces instead of hiding behind a
+    well.  No component raises it, so this guard is a fallback, not a routine path.
+    """
+    try:
+        return fn(*args, **kwargs)
+    except NotImplementedError:
+        return _pending_well(component_id)
+
+
+def _attr_slot(fn: Callable[..., str], *args: Any, **kwargs: Any) -> str:
+    """Call a component yielding an attribute/class fragment; unimplemented falls back to ``''``."""
+    try:
+        return fn(*args, **kwargs)
+    except NotImplementedError:
+        return ""
+
+
+def _render_output(out: Output, ctx: RenderContext) -> str:
+    """Route one output to its component by kind then mimetype, else the unsupported well."""
+    if out.kind == "stream-stderr":
+        return _slot("D17", outputs_text.render_stderr, out, ctx)
+    if out.kind == "stream-stdout":
+        if detect_tqdm(out.text) is not None:
+            return _slot("D24", outputs_text.render_progress, out, ctx)
+        return _slot("D16", outputs_text.render_stdout, out, ctx)
+    if out.kind == "error":
+        return _slot("D23", outputs_text.render_traceback, out, ctx)
+    if out.kind in ("execute_result", "display_data"):
+        mimetype = out.primary_mimetype()
+        if mimetype is None:
+            return _unsupported_well("(empty output)")
+        if mimetype == _WIDGET_MIME:
+            html = ""
+            if ctx.mode in ("static", "embed"):
+                html += _slot(
+                    "E26", interactive.render_stale_banner, ctx, message=_STALE_WIDGET_MSG
+                )
+            return html + _slot("E25", interactive.render_widget, out, ctx)
+        if mimetype == _COLUMN_PROFILE_MIME:
+            if outputs_data.is_valid_column_profiles_payload(out.data.get(_COLUMN_PROFILE_MIME)):
+                return _slot("MR01", outputs_data.render_column_profiles, out, ctx)
+            # Custom MIME is an enhancement, never a single point of failure. Strip only the bad
+            # representation and route the same normal Jupyter output through its portable HTML or
+            # text fallback. With neither fallback, show a labeled well rather than a blank cell.
+            fallback = Output(
+                kind=out.kind,
+                text=out.text,
+                data={key: value for key, value in out.data.items() if key != _COLUMN_PROFILE_MIME},
+                metadata=out.metadata,
+                execution_count=out.execution_count,
+            )
+            return (
+                _render_output(fallback, ctx)
+                if fallback.primary_mimetype() is not None
+                else _unsupported_well("invalid column inspector")
+            )
+        if mimetype == _SOURCE_OBSERVATION_MIME:
+            if outputs_source.valid_payload(out.data.get(mimetype)):
+                return _slot("MR03", outputs_source.render_source_observation, out, ctx)
+            fallback = Output(
+                kind=out.kind,
+                text=out.text,
+                data={key: value for key, value in out.data.items() if key != mimetype},
+                metadata=out.metadata,
+                execution_count=out.execution_count,
+            )
+            return (
+                _render_output(fallback, ctx)
+                if fallback.primary_mimetype() is not None
+                else _unsupported_well("invalid source evidence")
+            )
+        if mimetype in _STAGE_OBSERVATION_MIMES:
+            if outputs_stage.valid_payload(out.data.get(mimetype)):
+                return _slot(
+                    "MR02", outputs_stage.render_stage_observation, out, ctx, mimetype=mimetype
+                )
+            fallback = Output(
+                kind=out.kind,
+                text=out.text,
+                data={key: value for key, value in out.data.items() if key != mimetype},
+                metadata=out.metadata,
+                execution_count=out.execution_count,
+            )
+            return (
+                _render_output(fallback, ctx)
+                if fallback.primary_mimetype() is not None
+                else _unsupported_well("invalid stage observation")
+            )
+        if mimetype == "text/html":
+            source = out.text_of("text/html")
+            if 'class="dataframe"' in source or "class='dataframe'" in source:
+                return _slot("D19", outputs_rich.render_dataframe, out, ctx)
+            return _slot("D21", outputs_rich.render_html, out, ctx)
+        if mimetype in ("image/svg+xml", "image/png"):
+            return _slot("D20", outputs_rich.render_figure, out, ctx)
+        if mimetype == "application/json":
+            return _slot("D22", outputs_rich.render_json, out, ctx)
+        if mimetype == "text/plain":
+            if detect_tqdm(out.text_of("text/plain")) is not None:
+                return _slot("D24", outputs_text.render_progress, out, ctx)
+            return _slot("D18", outputs_text.render_result_text, out, ctx)
+        return _unsupported_well(mimetype)
+    return _unsupported_well("(unknown output)")
+
+
+def _output_prompt_variant(out: Output, cell: Cell) -> tuple[str | None, int | None]:
+    """Pick the B06 gutter variant + count for an output row.
+
+    ``execute_result``/``display_data`` -> ``Out [n]`` (orange, n from the output's or the cell's
+    execution count); a widget bundle -> ``Wgt`` (grey); a stream -> ``Out [*]`` (grey); an error ->
+    ``Err`` (rust).  An ``unknown`` record carries no prompt.
+    """
+    if out.kind in ("stream-stdout", "stream-stderr"):
+        return "stream", None
+    if out.kind == "error":
+        return "err", None
+    if out.kind in ("execute_result", "display_data"):
+        if out.primary_mimetype() == _WIDGET_MIME:
+            return "wgt", None
+        count = out.execution_count if out.execution_count is not None else cell.execution_count
+        return "out", count
+    return None, None
+
+
+def _io_row(prompt: str, output_html: str) -> str:
+    """Re-enter an output into the 62px gutter grid so its ``Out`` prompt aligns under ``In [n]``.
+
+    The ``.nb-io`` wrapper pulls back ``margin-left: -62px`` and re-establishes the
+    ``[62px][content]`` grid, so ``In [n]`` and ``Out [n]`` share one pixel-aligned
+    column across every output type.  The prompt column is ``aria-hidden`` and ``user-select:
+    none`` (excluded from copy).
+    """
+    return (
+        '<div class="nb-io">'
+        f'<div class="nb-io-gutter" aria-hidden="true">{prompt}</div>'
+        f'<div class="nb-io-body">{output_html}</div>'
+        "</div>"
+    )
+
+
+def _content_row(content: str, modifier: str) -> str:
+    """Place a document-level block in the content column with an empty gutter cell."""
+    return (
+        f'<section class="nb-cell nb-cell--{esc(modifier)}">'
+        '<div class="nb-gutter" aria-hidden="true"></div>'
+        f'<div class="nb-content">{content}</div>'
+        "</section>"
+    )
+
+
+def _is_weldable_well(out: Output) -> bool:
+    """A first output welds flush to the code panel only when it is a stdout well (D16).
+
+    stderr (D17) carries its own dashed-separator rule and the rich containers (df/fig/json/
+    traceback) own a top border, so only a non-tqdm stdout stream is the ``.nb-well`` that welds
+    directly beneath the panel.  Every other output re-enters the gutter inside ``.nb-io``, which
+    owns the 10px input-to-output gap and zeroes the top margin of every child of its body, so the
+    gap is the same for every output shape — including one that renders as several sibling roots.
+    The weld itself is expressed by
+    the ``.nb-code--welded + .nb-well`` adjacency rule in ``build_css`` — the well's own markup is
+    left pristine, so this is a panel-class decision here, not a rewrite of the output.
+    """
+    return out.kind == "stream-stdout" and detect_tqdm(out.text) is None
+
+
+def _render_code_cell(cell: Cell, ctx: RenderContext) -> tuple[str, str]:
+    """Return (gutter_html, content_html) for a code cell.
+
+    Consecutive stdout/stderr stream records are coalesced (D16) before routing; a panel header is
+    always present (B08 copy), so the panel takes ``nb-code--head`` for the 16px 18px pre padding;
+    and when the first output is a stdout well the panel takes ``nb-code--welded`` so the shared
+    adjacency rule squares the panel's bottom and drops the well's top seam — the two read as one
+    dark-to-paper unit.  Every other output re-enters the gutter grid (``.nb-io``) with its B06
+    ``Out``/``Err``/``Wgt`` prompt so ``In [n]`` and ``Out [n]`` share the one 62px column; the
+    welded first stdout is the single exception (it reads as a panel continuation, with no prompt).
+    """
+    activity = cell.research_activity
+    gutter = _slot(
+        "B06",
+        frame.render_prompt,
+        cell,
+        ctx,
+        variant="running" if activity == "executing" else None,
+    )
+    state = _attr_slot(
+        frame.cell_state_classes,
+        cell,
+        ctx,
+        state="running" if activity == "executing" else None,
+    )
+    panel_head = _slot("B08", frame.render_hover_toolbar, cell, ctx)
+    activity_chip = _slot("B10", frame.render_research_activity, cell, ctx)
+    if activity_chip:
+        panel_head = panel_head.replace(
+            '<div class="nb-panel-actions">',
+            f'{activity_chip}<div class="nb-panel-actions">',
+            1,
+        )
+    code = _slot("C12", code_body.render_code_input, cell, ctx)
+
+    outputs = coalesce_stream_outputs(cell.outputs)
+    welded = bool(outputs) and _is_weldable_well(outputs[0])
+
+    classes = ["nb-panel", "nb-code"]
+    if panel_head:
+        classes.append("nb-code--head")
+    if welded:
+        classes.append("nb-code--welded")
+    if state:
+        classes.append(state)
+    panel = f'<div class="{esc(" ".join(classes))}">{panel_head}{code}</div>'
+
+    parts = [panel]
+    for index, out in enumerate(outputs):
+        rendered = _render_output(out, ctx)
+        if index == 0 and welded:
+            parts.append(rendered)  # flush beneath the panel, no gutter re-entry
+            continue
+        variant, count = _output_prompt_variant(out, cell)
+        prompt = (
+            _slot("B06", frame.render_prompt, cell, ctx, variant=variant, count=count)
+            if variant is not None
+            else ""
+        )
+        parts.append(_io_row(prompt, rendered))
+    if cell.execution_count is not None:
+        metadata = _slot("B11", frame.render_exec_meta, cell, ctx)
+        if metadata:
+            parts.append(metadata.replace(">", " data-cell-exec-meta>", 1))
+    return gutter, "".join(parts)
+
+
+def _render_markdown_cell(cell: Cell, ctx: RenderContext) -> tuple[str, str]:
+    gutter = _slot("B06", frame.render_prompt, cell, ctx)
+    tags = _slot("B10", frame.render_tags, cell, ctx) if cell.tags else ""
+    body = _slot("C13", markdown_body.render_markdown, cell, ctx)
+    activity = _slot("B10", frame.render_research_activity, cell, ctx)
+    return gutter, activity + tags + body
+
+
+def _render_raw_cell(cell: Cell, ctx: RenderContext) -> tuple[str, str]:
+    gutter = _slot("B06", frame.render_prompt, cell, ctx)
+    return gutter, _slot("C15", code_body.render_raw, cell, ctx)
+
+
+def _render_cell(cell: Cell, ctx: RenderContext) -> str:
+    if cell.cell_type == "code":
+        gutter, content = _render_code_cell(cell, ctx)
+    elif cell.cell_type == "markdown":
+        gutter, content = _render_markdown_cell(cell, ctx)
+    elif cell.cell_type == "raw":
+        gutter, content = _render_raw_cell(cell, ctx)
+    else:
+        gutter, content = "", _unsupported_well(f"cell · {cell.cell_type}")
+    label = f"cell {ctx.cell_index + 1} of {ctx.cell_count}"
+    cell_id = cell.cell_id or f"cell-{ctx.cell_index}"
+    activity = cell.research_activity
+    activity_attr = f' data-research-activity="{esc(activity)}"' if activity else ""
+    activity_class = f" is-{activity}" if activity else ""
+    return (
+        f'<section class="nb-cell nb-cell--{esc(cell.cell_type)}{activity_class}" '
+        f'data-cell-id="{esc(cell_id)}" aria-label="{esc(label)}"{activity_attr}>'
+        f'<div class="nb-gutter" data-cell-gutter aria-hidden="true">{gutter}</div>'
+        f'<div class="nb-content">{content}</div>'
+        "</section>"
+    )
+
+
+def _leakage_placement(
+    nb: Notebook,
+) -> tuple[dict[int, list[dict[str, Any]]], list[dict[str, Any]]]:
+    """Split leakage entries into per-cell (by integer ``cell`` index) and trailing groups."""
+    by_cell: dict[int, list[dict[str, Any]]] = {}
+    trailing: list[dict[str, Any]] = []
+    for entry in nb.leakage:
+        index = entry.get("cell")
+        if isinstance(index, int) and not isinstance(index, bool):
+            by_cell.setdefault(index, []).append(entry)
+        else:
+            trailing.append(entry)
+    return by_cell, trailing
+
+
+def render_notebook(nb: dict[str, Any], mode: str = "static", filename: str = "table.ipynb") -> str:
+    """Render a notebook to one HTML string: shell > A01 > [A04 | cells] > A05.
+
+    ``mode`` is one of static/connected/embed; embed drops all chrome.  The result is always
+    well-formed even against a malformed notebook — the parser degrades bad records and every
+    component call is guarded.
+    """
+    if mode not in tokens.VALID_MODES:
+        raise ValueError(f"unknown render mode: {mode!r} (expected one of {tokens.VALID_MODES})")
+
+    model = parse_notebook(nb)
+    doc_ctx = RenderContext(mode=mode, cell_index=-1, cell_count=len(model.cells))
+    css = tokens.build_css(mode)
+
+    body_parts: list[str] = []
+    if model.provenance is not None:
+        body_parts.append(_slot("F27", mr_components.render_provenance, model, doc_ctx))
+
+    by_cell, trailing_leakage = _leakage_placement(model)
+    prev_exec: int | None = None
+    for index, cell in enumerate(model.cells):
+        ctx = RenderContext(
+            mode=mode,
+            cell_index=index,
+            cell_count=len(model.cells),
+            prev_execution_count=prev_exec,
+        )
+        body_parts.append(_render_cell(cell, ctx))
+        for entry in by_cell.get(index, []):
+            body_parts.append(
+                _content_row(_slot("F28", mr_components.render_leakage, entry, ctx), "leak")
+            )
+        if cell.cell_type == "code" and cell.execution_count is not None:
+            prev_exec = cell.execution_count
+    for entry in trailing_leakage:
+        body_parts.append(
+            _content_row(_slot("F28", mr_components.render_leakage, entry, doc_ctx), "leak")
+        )
+
+    document = f'<div class="nb-document">{"".join(body_parts)}</div>'
+
+    outline = ""
+    if mode != "embed":
+        outline = _slot("A04", chrome.render_outline, model, doc_ctx)
+    body = f'<div class="nb-body">{outline}{document}</div>'
+
+    chrome_top = ""
+    chrome_bottom = ""
+    if mode != "embed":
+        chrome_top += _slot("A01", chrome.render_header, model, doc_ctx, filename)
+    if mode == "connected":
+        chrome_top += _slot("A02", chrome.render_toolbar, model, doc_ctx)
+    if mode != "embed":
+        chrome_bottom = _slot("A05", chrome.render_footer, model, doc_ctx)
+
+    return (
+        f'<div class="nb-shell nb-shell--{esc(mode)}">'
+        f"<style>{css}</style>"
+        f"{chrome_top}{body}{chrome_bottom}"
+        "</div>"
+    )