mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/nbrender/outputs_rich.py

@@ -0,0 +1,906 @@
+"""Group D · rich outputs (D19, D20, D21, D22): DataFrame, figure, rich HTML, JSON viewer.
+
+Routed to from ``document._render_output``.  The DataFrame renderer (D19) parses the pandas HTML
+repr with the stdlib :class:`html.parser.HTMLParser` — never eval, never pass-through — and re-emits
+its own table DOM: index column, signed-numeric coloring with the true minus U+2212, tabular-nums,
+a first-10/last-10 ellipsis row over 20 rows, a frozen index over 15 columns, and a footer caption.
+Rich HTML (D21) is sandboxed by parse-and-rebuild: the untrusted markup is parsed with the stdlib
+``HTMLParser`` and only an allowlist of elements/attributes is re-serialized — everything else is
+dropped (dangerous subtrees discarded, unknown tags unwrapped to escaped text), which structurally
+removes ``on*`` handlers, ``javascript:`` URLs, ``position: fixed``, and forgotten tags rather than
+regex-matching them; Styler gradient backgrounds are remapped to the cobalt tint ramp.  Figures
+(D20) render as a passive image in both cases: a charset-filtered base64 PNG data URI, or the SVG
+payload base64ed into an ``image/svg+xml`` data URI — never inline SVG markup (see the SVG rule
+below).  The JSON viewer (D22) expands two levels and collapses deeper nodes behind ``{n}`` /
+``[n]`` counts.  Every value from notebook JSON is escaped at the point of interpolation through
+:func:`parse.esc`; the D21 body is the one deliberately un-escaped surface, which is why it is
+sandboxed instead.
+
+One rule governs SVG everywhere in this module: **untrusted SVG is only ever a passive image**.
+It is never inlined (D20), and untrusted markup may never name an SVG source of its own
+(``_safe_img_src`` refuses ``data:image/svg+xml`` in D21, keeping that allowlist minimal).  No
+blocklist over raw SVG markup would be sound — ``/`` is a legal attribute separator, and ``href``
+values are entity- and control-char-decoded before the scheme is read, so ``<animate/onbegin=…>``
+and ``&#x6A;avascript:`` slip past any such filter.  Inside ``<img>`` an SVG instead renders in the
+SVG spec's secure static mode: no scripting, no external subresource loads, no interactivity.
+``.nb-fig img`` carries the same ``width: 100%; height: auto; display: block`` sizing an inline
+``<svg>`` would have.
+
+A D19 numeric cell is colored only when it carries an explicit sign — a leading ``+`` (cobalt) or
+``-``/``U+2212`` (rust); any zero renders grey and a bare positive (``34``) stays ink, so a clean,
+no-error DataFrame keeps cobalt to the prompt column alone.
+
+The D19 wide-frame index freeze and the D21 Styler gradient ramp are emitted as hooks only
+(``nb-df--wide``, ``var(--nb-styler-g0..3)``); their rules and hexes live in ``tokens.build_css``.
+"""
+
+from __future__ import annotations
+
+import base64
+import html
+import json
+import re
+from html.parser import HTMLParser
+from typing import Any
+
+from mostlyright.data_harness.nbrender.parse import Output, RenderContext, esc
+from mostlyright.data_harness.nbrender.status import is_status_column, render_status
+
+# The sanctioned iconography (CONTRACT.md).  Kept as named constants so no stray
+# decorative unicode can slip into output and every glyph is auditable.
+_ELLIPSIS = "⋯"  # midline horizontal ellipsis · D19 truncation row
+# true minus · D19 negative numerics (RUF001: U+2212 is required here, never a hyphen)
+_TRUE_MINUS = "−"  # noqa: RUF001
+_CARET_OPEN = "▾"  # down-pointing triangle · D22 expanded node
+_CARET_CLOSED = "▸"  # right-pointing triangle · D22 collapsed node
+# multiplication sign · D19 caption dimensions (RUF001: U+00D7 is required here, never "x")
+_TIMES = "×"  # noqa: RUF001
+_MIDDOT = "·"  # middot · D19 caption separator
+
+_TRUNCATE_ROWS = 20  # over this many rows -> first 10 / last 10 with an ellipsis row
+_HEAD_TAIL = 10
+_FREEZE_COLS = 15  # over this many data columns -> freeze the index column and scroll
+_JSON_EXPAND_LEVELS = 2  # static mode expands two levels; deeper nodes collapse to a count
+
+# ==============================================================================================
+# D19 · DataFrame
+# ==============================================================================================
+
+
+class _TableParser(HTMLParser):
+    """Collect ``thead``/``tbody`` rows as ``(tag, text)`` cells; text is decoded, never trusted.
+
+    Only table structure is honored — any markup inside a cell (a stray ``<script>`` in a value)
+    contributes its text via :meth:`handle_data` and is dropped as a tag, so re-emitting the cell
+    text through :func:`esc` cannot carry an injection through.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.header_rows: list[list[tuple[str, str, str]]] = []
+        self.body_rows: list[list[tuple[str, str, str]]] = []
+        self.header_row_attrs: list[str] = []
+        self.body_row_attrs: list[str] = []
+        self.table_attrs = ""
+        self.thead_attrs = ""
+        self.tbody_attrs = ""
+        self.seen_thead = False
+        self.seen_tbody = False
+        self._section: str | None = None
+        self._row: list[tuple[str, str, str]] | None = None
+        self._row_attrs = ""
+        self._cell: list[Any] | None = None  # [tag, [chunks], serialized attrs]
+        self._suppress = 0  # depth inside a <script>/<style> whose text must be dropped
+        self.table_count = 0
+        self.table_depth = 0
+        self.simple_table = True
+
+    def handle_starttag(self, tag: str, attrs: Any) -> None:
+        if any(name.lower() in ("colspan", "rowspan", "span") for name, _value in attrs):
+            self.simple_table = False
+        if tag == "table":
+            if self.table_depth or self._section is not None or self._row is not None:
+                self.simple_table = False
+            self.table_count += 1
+            self.table_depth += 1
+            self.table_attrs = _serialize_attrs(tag, attrs)
+            if self.table_depth != 1:
+                self.simple_table = False
+        elif tag in ("script", "style"):
+            self.simple_table = False
+            self._suppress += 1
+        elif tag == "thead":
+            if (
+                self.table_depth != 1
+                or self._section is not None
+                or self._row is not None
+                or self.seen_thead
+                or self.seen_tbody
+            ):
+                self.simple_table = False
+            self.seen_thead = True
+            self._section = "thead"
+            self.thead_attrs = _serialize_attrs(tag, attrs)
+        elif tag == "tbody":
+            if (
+                self.table_depth != 1
+                or self._section is not None
+                or self._row is not None
+                or not self.seen_thead
+                or self.seen_tbody
+            ):
+                self.simple_table = False
+            self.seen_tbody = True
+            self._section = "tbody"
+            self.tbody_attrs = _serialize_attrs(tag, attrs)
+        elif tag == "tr":
+            if (
+                self.table_depth != 1
+                or self._section not in ("thead", "tbody")
+                or self._row is not None
+                or self._cell is not None
+            ):
+                self.simple_table = False
+            self._row = []
+            self._row_attrs = _serialize_attrs(tag, attrs)
+        elif tag in ("th", "td") and self._row is not None:
+            if self._cell is not None:
+                self.simple_table = False
+            self._cell = [tag, [], _serialize_attrs(tag, attrs)]
+        elif tag in ("th", "td"):
+            self.simple_table = False
+        elif tag not in ("thead", "tbody", "tr", "th", "td"):
+            self.simple_table = False
+
+    def handle_startendtag(self, tag: str, attrs: Any) -> None:
+        self.simple_table = False
+        if tag in ("th", "td") and self._row is not None:
+            self._row.append((tag, "", _serialize_attrs(tag, attrs)))
+
+    def handle_data(self, data: str) -> None:
+        if self._suppress:
+            return
+        if self._cell is not None:
+            self._cell[1].append(data)
+        elif data.strip():
+            self.simple_table = False
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in ("script", "style"):
+            if self._suppress:
+                self._suppress -= 1
+            return
+        if tag == "table":
+            if self.table_depth != 1 or self._section is not None or self._row is not None:
+                self.simple_table = False
+            self.table_depth = max(0, self.table_depth - 1)
+        elif tag in ("th", "td") and self._cell is not None and self._row is not None:
+            if self._cell[0] != tag:
+                self.simple_table = False
+            self._row.append((self._cell[0], "".join(self._cell[1]), self._cell[2]))
+            self._cell = None
+        elif tag == "tr" and self._row is not None:
+            if self._section not in ("thead", "tbody") or self._cell is not None:
+                self.simple_table = False
+            if self._section == "thead":
+                self.header_rows.append(self._row)
+                self.header_row_attrs.append(self._row_attrs)
+            elif self._section == "tbody":
+                self.body_rows.append(self._row)
+                self.body_row_attrs.append(self._row_attrs)
+            elif not self.header_rows and not self.body_rows:
+                self.header_rows.append(self._row)
+                self.header_row_attrs.append(self._row_attrs)
+            else:
+                self.body_rows.append(self._row)
+                self.body_row_attrs.append(self._row_attrs)
+            self._row = None
+            self._row_attrs = ""
+        elif tag in ("thead", "tbody"):
+            if self._section != tag or self._row is not None or self._cell is not None:
+                self.simple_table = False
+            self._section = None
+        elif tag in ("th", "td", "tr"):
+            self.simple_table = False
+        elif tag not in ("th", "td", "tr"):
+            self.simple_table = False
+
+    def handle_comment(self, data: str) -> None:
+        self.simple_table = False
+
+
+# The multiplication-sign alternative is deliberate: pandas writes the frame caption with U+00D7.
+_FRAME_RE = re.compile(r"(\d+)\s*rows?\s*[×xX]\s*(\d+)\s*column", re.IGNORECASE)  # noqa: RUF001
+_NAN_WORDS = frozenset({"nan", "inf", "-inf", "+inf", "infinity", "-infinity", "+infinity"})
+
+
+def _parse_number(text: str) -> tuple[str, float] | None:
+    """Return ``(original, value)`` when ``text`` is a plain number, else ``None``.
+
+    Commas, a trailing percent, and a true-minus sign are tolerated; ``nan``/``inf`` words are
+    treated as strings so they are not miscolored as signed numerics.
+    """
+    core = text.strip()
+    if not core:
+        return None
+    candidate = core.rstrip("%").replace(",", "").replace(_TRUE_MINUS, "-")
+    if candidate.lower() in _NAN_WORDS:
+        return None
+    try:
+        value = float(candidate)
+    except ValueError:
+        return None
+    return core, value
+
+
+def _cell_render(text: str, column: str = "") -> tuple[str, str]:
+    """Classify one body data cell -> ``(css_class, display_html)``.
+
+    Numeric cells are right-aligned tabular-nums; a *signed* numeric is colored (positive cobalt,
+    negative rust, zero grey) and negatives render with the true minus.  Everything else is a
+    nowrap string cell.
+    """
+    if is_status_column(column):
+        status = render_status(text)
+        if status is not None:
+            return "nb-df-str", status
+    parsed = _parse_number(text)
+    if parsed is None:
+        return "nb-df-str", esc(text.strip())
+    original, value = parsed
+    classes = ["nb-df-num"]
+    display = original
+    if display[:1] == "-":
+        display = _TRUE_MINUS + display[1:]
+    if value == 0:
+        classes.append("nb-df-zero")
+    elif value < 0:
+        classes.append("nb-df-neg")
+    elif original[:1] == "+":
+        classes.append("nb-df-pos")
+    return " ".join(classes), esc(display)
+
+
+def _split_row(row: list[tuple[str, str, str]]) -> tuple[list[str], list[str]]:
+    """Leading ``th`` cells are the index; the rest are data cells."""
+    index: list[str] = []
+    data: list[str] = []
+    seen_data = False
+    for tag, text, _attrs in row:
+        if tag == "th" and not seen_data:
+            index.append(text)
+        else:
+            seen_data = True
+            data.append(text)
+    return index, data
+
+
+def _index_col_count(body_split: list[tuple[list[str], list[str]]]) -> int:
+    """Number of leading index columns, from pandas' structural signal, not a value heuristic.
+
+    Pandas emits each index level as a leading ``<th>`` inside every ``tbody`` row, so the count of
+    leading ``th`` cells is authoritative regardless of whether the index *value* happens to be
+    empty (the old first-cell-empty heuristic misfired on a blank first value). The first body row
+    that carries any leading ``th`` decides the count. Rows containing only ``td`` elements are an
+    index-free frame and therefore have zero index columns.
+    """
+    for index_cells, _data in body_split:
+        if index_cells:
+            return len(index_cells)
+    return 0
+
+
+def render_dataframe(out: Output, ctx: RenderContext) -> str:
+    """D19 · DataFrame — re-emitted table, signed-number coloring, truncation, footer caption."""
+    source = out.text_of("text/html")
+    parser = _TableParser()
+    try:
+        parser.feed(source)
+        parser.close()
+    except Exception:
+        pass
+
+    body_split = [_split_row(row) for row in parser.body_rows]
+    n_index = _index_col_count(body_split)
+
+    header = parser.header_rows[-1] if parser.header_rows else None
+    if header is not None:
+        header_texts = [text for _tag, text, _attrs in header]
+        columns = header_texts[n_index:]
+    else:
+        columns = []
+    if not columns and body_split:
+        columns = ["" for _ in body_split[0][1]]
+    data_col_count = len(columns)
+
+    frame_match = _FRAME_RE.search(source)
+    if frame_match:
+        frame_rows, frame_cols = int(frame_match.group(1)), int(frame_match.group(2))
+    else:
+        frame_rows, frame_cols = len(body_split), data_col_count
+
+    colspan = n_index + data_col_count
+
+    # Truncation · over 20 rows render first 10 / last 10 with a centered ellipsis row.
+    if len(body_split) > _TRUNCATE_ROWS:
+        shown = [*body_split[:_HEAD_TAIL], None, *body_split[-_HEAD_TAIL:]]
+        disp_rows = _HEAD_TAIL * 2
+    else:
+        shown = list(body_split)
+        disp_rows = len(body_split)
+
+    head_cells = "".join("<th></th>" for _ in range(n_index)) + "".join(
+        f"<th>{esc(col)}</th>" for col in columns
+    )
+
+    body_parts: list[str] = []
+    for item in shown:
+        if item is None:
+            body_parts.append(
+                f'<tr><td class="nb-df-ellipsis" colspan="{colspan}">{_ELLIPSIS}</td></tr>'
+            )
+            continue
+        index_cells, data_cells = item
+        idx_html = "".join(f'<td class="nb-df-idx">{esc(v)}</td>' for v in index_cells)
+        rendered_cells = (
+            _cell_render(value, columns[index] if index < len(columns) else "")
+            for index, value in enumerate(data_cells)
+        )
+        cell_html = "".join(f'<td class="{cls}">{disp}</td>' for cls, disp in rendered_cells)
+        body_parts.append(f"<tr>{idx_html}{cell_html}</tr>")
+
+    caption = (
+        f"{disp_rows} rows {_TIMES} {data_col_count} columns {_MIDDOT} "
+        f"{frame_rows} {_TIMES} {frame_cols} in frame"
+    )
+    wide = " nb-df--wide" if data_col_count > _FREEZE_COLS else ""
+
+    return (
+        f'<div class="nb-df{wide}">'
+        f'<div class="nb-df-scroll"><table>'
+        f"<thead><tr>{head_cells}</tr></thead>"
+        f"<tbody>{''.join(body_parts)}</tbody>"
+        f"</table></div>"
+        f'<div class="nb-df-caption">{esc(caption)}</div>'
+        f"</div>"
+    )
+
+
+# ==============================================================================================
+# D20 · Figure output
+# ==============================================================================================
+
+_B64_STRIP_RE = re.compile(r"[^A-Za-z0-9+/=]")
+
+# D20 series line-swatch styles, in series order.  Colors reference CSS variables so no literal hex
+# escapes this module; series 2 is dashed and series 4 dotted so the legend survives grayscale.
+_LEGEND_SWATCHES = (
+    "stroke:var(--nb-cobalt);stroke-width:2",
+    "stroke:var(--nb-ink);stroke-width:2;stroke-dasharray:5 4",
+    "stroke:var(--nb-orange);stroke-width:2",
+    "stroke:var(--nb-faint);stroke-width:2;stroke-dasharray:1 3",
+)
+
+
+def _fig_meta(out: Output) -> dict[str, Any]:
+    """Figure title/subtitle/legend live under ``metadata.mostlyright`` (mr.mpl_style), else
+    flat."""
+    meta = out.metadata if isinstance(out.metadata, dict) else {}
+    nested = meta.get("mostlyright")
+    return nested if isinstance(nested, dict) else meta
+
+
+def _svg_image(svg: str) -> str:
+    """Base64 an SVG payload into a passive ``<img>`` (never inline markup — see the module doc).
+
+    Inside ``<img>`` an SVG renders in the SVG spec's secure static mode: no scripting, no external
+    subresource loads, no interactivity.  Every execution vector — ``<script>``, ``<foreignObject>``
+    handlers, ``on*`` attributes under any separator, and ``javascript:`` in any obfuscation — is
+    therefore inert without the renderer having to enumerate it.  Base64 also makes the payload
+    attribute-safe by construction: the alphabet cannot close the ``src`` quote.
+    """
+    if not svg.strip():
+        return ""
+    blob = base64.b64encode(svg.encode("utf-8", "replace")).decode("ascii")
+    return f'<img src="data:image/svg+xml;base64,{blob}" alt="figure output">'
+
+
+def _clean_base64(value: str) -> str:
+    """Keep only base64 characters so an untrusted PNG blob is attribute-safe in the data URI."""
+    return _B64_STRIP_RE.sub("", value)
+
+
+def _fig_legend(series: Any) -> str:
+    """Render the optional legend from metadata series names, each with its line swatch."""
+    if not isinstance(series, list) or not series:
+        return ""
+    entries: list[str] = []
+    for idx, entry in enumerate(series):
+        label = entry.get("name") if isinstance(entry, dict) else entry
+        style = _LEGEND_SWATCHES[idx] if idx < len(_LEGEND_SWATCHES) else _LEGEND_SWATCHES[-1]
+        swatch = (
+            '<svg width="16" height="8" aria-hidden="true">'
+            f'<line x1="0" y1="4" x2="16" y2="4" style="{style}"/></svg>'
+        )
+        entries.append(
+            '<span style="display:inline-flex;align-items:center;gap:8px">'
+            f"{swatch}{esc(label)}</span>"
+        )
+    return f'<div class="nb-fig-legend">{"".join(entries)}</div>'
+
+
+def render_figure(out: Output, ctx: RenderContext) -> str:
+    """D20 · figure — hoisted title/subtitle, sanitized SVG or base64 PNG, optional legend."""
+    meta = _fig_meta(out)
+    head = ""
+    title = meta.get("title")
+    subtitle = meta.get("subtitle")
+    if title:
+        head += f'<div class="nb-fig-title">{esc(title)}</div>'
+    if subtitle:
+        head += f'<div class="nb-fig-sub">{esc(subtitle)}</div>'
+
+    mimetype = out.primary_mimetype()
+    if mimetype == "image/svg+xml":
+        image = _svg_image(out.text_of("image/svg+xml"))
+    elif mimetype == "image/png":
+        blob = _clean_base64(out.text_of("image/png"))
+        image = f'<img src="data:image/png;base64,{blob}" alt="figure output">'
+    else:
+        image = ""
+
+    legend = _fig_legend(meta.get("legend") or meta.get("series"))
+    return f'<div class="nb-fig">{head}{image}{legend}</div>'
+
+
+# ==============================================================================================
+# D21 · Rich HTML (_repr_html_, Styler)
+# ==============================================================================================
+
+_STYLER_HINTS = ("col_heading", "row_heading", 'id="t_', "id='t_")
+
+# Parse-and-rebuild sandbox (D21).  A blocklist regex is bypassable (slash/backtick attribute
+# separators, entity/whitespace-obfuscated ``javascript:``, and any tag the list forgot); instead
+# we parse the untrusted HTML with the stdlib parser and re-serialize ONLY an allowlist of elements
+# and attributes.  Anything not on the allowlist is dropped — script-bearing containers discard
+# their whole subtree, every other unknown tag is unwrapped to its (escaped) text — so a construct
+# the allowlist does not name cannot reach the page in an active form.
+_ALLOWED_TAGS = frozenset(
+    {
+        "div",
+        "span",
+        "p",
+        "br",
+        "hr",
+        "b",
+        "i",
+        "em",
+        "strong",
+        "u",
+        "s",
+        "sub",
+        "sup",
+        "code",
+        "pre",
+        "blockquote",
+        "h1",
+        "h2",
+        "h3",
+        "h4",
+        "h5",
+        "h6",
+        "ul",
+        "ol",
+        "li",
+        "dl",
+        "dt",
+        "dd",
+        "table",
+        "thead",
+        "tbody",
+        "tfoot",
+        "tr",
+        "th",
+        "td",
+        "caption",
+        "col",
+        "colgroup",
+        "img",
+        "a",
+        "details",
+        "summary",
+        "figure",
+        "figcaption",
+    }
+)
+# HTML void elements — emitted (if allowed) or dropped at the start tag; never pushed as a frame.
+_VOID_TAGS = frozenset(
+    {
+        "area",
+        "base",
+        "br",
+        "col",
+        "embed",
+        "hr",
+        "img",
+        "input",
+        "link",
+        "meta",
+        "param",
+        "source",
+        "track",
+        "wbr",
+    }
+)
+# Non-void elements whose entire subtree is discarded (they can carry executable or style payloads
+# no attribute-stripping would neutralize — e.g. a <script> body or an <object> data island).
+_DROP_TAGS = frozenset(
+    {
+        "script",
+        "style",
+        "iframe",
+        "object",
+        "form",
+        "noscript",
+        "template",
+        "svg",
+        "math",
+        "head",
+        "title",
+        "applet",
+        "frame",
+        "frameset",
+        "canvas",
+        "audio",
+        "video",
+        "button",
+        "select",
+        "textarea",
+        "option",
+    }
+)
+
+_CTRL_RE = re.compile(r"[\x00-\x20\x7f]+")
+_SCHEME_RE = re.compile(r"^[a-z][a-z0-9+.\-]*:")
+_STYLE_HEX_RE = re.compile(r"#([0-9A-Fa-f]{6})")
+
+
+def _ramp_var(hexes: str) -> str:
+    """Map a Styler ``background-color`` hex onto one of four cobalt-ramp CSS variables.
+
+    Darker source colors (higher gradient value) map to more-saturated ramp steps.  The ramp hexes
+    live in ``tokens.build_css`` as ``--nb-styler-g0..3``; no literal color is emitted here — only
+    the variable reference — and the original hex is dropped.
+    """
+    red, green, blue = (int(hexes[i : i + 2], 16) for i in (0, 2, 4))
+    luminance = 0.299 * red + 0.587 * green + 0.114 * blue
+    bucket = min(3, max(0, int((255 - luminance) // 64)))
+    return f"var(--nb-styler-g{bucket})"
+
+
+def _safe_href(value: str) -> str | None:
+    """Return an ``a[href]`` value only when it is http/https or a ``#fragment``, else ``None``.
+
+    Entities are decoded and control/whitespace characters stripped BEFORE the scheme test, so
+    ``&#x6A;avascript:``, ``java\\nscript:``, and leading-space tricks all collapse to a bare
+    scheme that fails the allowlist and is dropped.
+    """
+    decoded = html.unescape(value or "")
+    probe = _CTRL_RE.sub("", decoded).lower()
+    if probe.startswith("#"):
+        return decoded.strip()
+    if probe.startswith("http://") or probe.startswith("https://"):
+        return decoded.strip()
+    return None
+
+
+def _safe_img_src(value: str) -> str | None:
+    """Return an ``img[src]`` value only for a safe raster data URI or a scheme-less relative path.
+
+    ``data:image/svg+xml`` is refused (nested-script risk) — only png/jpeg/gif data URIs pass — as
+    is any explicit scheme (``javascript:``/``data:text/html``/…) or a protocol-relative ``//host``.
+    """
+    decoded = html.unescape(value or "")
+    probe = _CTRL_RE.sub("", decoded).lower()
+    if probe.startswith(("data:image/png", "data:image/jpeg", "data:image/gif")):
+        return decoded.strip()
+    # Browsers normalize backslashes to slashes in URLs, so \\host and /\host are
+    # protocol-relative too — refuse any leading slash/backslash pair.
+    if _SCHEME_RE.match(probe) or probe[:2] in ("//", "\\\\", "/\\", "\\/"):
+        return None
+    return decoded.strip()
+
+
+def _sanitize_style(value: str) -> str:
+    """Keep only ``background``/``background-color`` hex declarations, remapped to the cobalt ramp.
+
+    Every other declaration is discarded — which structurally removes ``position: fixed`` and any
+    ``url(...)`` exfiltration target rather than trying to pattern-match them out.
+    """
+    decls: list[str] = []
+    for chunk in value.split(";"):
+        prop, sep, val = chunk.partition(":")
+        if not sep:
+            continue
+        if prop.strip().lower() in ("background", "background-color"):
+            match = _STYLE_HEX_RE.search(val)
+            if match:
+                decls.append("background-color:" + _ramp_var(match.group(1)))
+    return ";".join(decls)
+
+
+def _serialize_attrs(tag: str, attrs: list[tuple[str, Any]]) -> str:
+    """Serialize only the allowlisted, validated attributes for ``tag`` (leading-space per attr)."""
+    out: list[str] = []
+    for name, raw in attrs:
+        value = "" if raw is None else str(raw)
+        key = name.lower()
+        if key == "class":
+            out.append(f' class="{esc(value)}"')
+        elif key == "style":
+            styled = _sanitize_style(value)
+            if styled:
+                out.append(f' style="{esc(styled)}"')
+        elif key in ("colspan", "rowspan", "scope") and tag in ("th", "td"):
+            out.append(f' {key}="{esc(value)}"')
+        elif key == "span" and tag in ("col", "colgroup"):
+            out.append(f' span="{esc(value)}"')
+        elif key in ("width", "height") and tag == "img":
+            out.append(f' {key}="{esc(value)}"')
+        elif key == "alt" and tag == "img":
+            out.append(f' alt="{esc(value)}"')
+        elif key == "title":
+            out.append(f' title="{esc(value)}"')
+        elif key == "href" and tag == "a":
+            safe = _safe_href(value)
+            if safe is not None:
+                out.append(f' href="{esc(safe)}"')
+    return "".join(out)
+
+
+def _render_void(tag: str, attrs: list[tuple[str, Any]]) -> str:
+    """Serialize an allowlisted void element (dropping a media element that has no safe source)."""
+    if tag not in _ALLOWED_TAGS:
+        return ""
+    if tag == "img":
+        src = next((v for n, v in attrs if n.lower() == "src"), None)
+        safe = _safe_img_src(str(src)) if src is not None else None
+        if safe is None:
+            return ""  # media with no safe source is removed, not left as a broken tag
+        rest = _serialize_attrs("img", [(n, v) for n, v in attrs if n.lower() != "src"])
+        return f'<img src="{esc(safe)}"{rest}>'
+    return f"<{tag}{_serialize_attrs(tag, attrs)}>"
+
+
+class _HtmlSanitizer(HTMLParser):
+    """Parse untrusted HTML into a tree and re-serialize only the allowlist (D21 sandbox)."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self._root: list[str] = []
+        self._stack: list[dict[str, Any]] = []
+
+    def _sink(self) -> list[str]:
+        return self._stack[-1]["children"] if self._stack else self._root
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, Any]]) -> None:
+        tag = tag.lower()
+        if tag in _VOID_TAGS:
+            self._sink().append(_render_void(tag, attrs))
+            return
+        if tag in _ALLOWED_TAGS:
+            mode = "keep"
+        elif tag in _DROP_TAGS:
+            mode = "drop"
+        else:
+            mode = "unwrap"
+        self._stack.append(
+            {"tag": tag, "mode": mode, "attrs": _serialize_attrs(tag, attrs), "children": []}
+        )
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, Any]]) -> None:
+        tag = tag.lower()
+        if tag in _VOID_TAGS:
+            self._sink().append(_render_void(tag, attrs))
+        elif tag in _ALLOWED_TAGS:
+            self._sink().append(f"<{tag}{_serialize_attrs(tag, attrs)}></{tag}>")
+        # a self-closed drop/unwrap element has no content and contributes nothing
+
+    def handle_data(self, data: str) -> None:
+        self._sink().append(esc(data))
+
+    def handle_endtag(self, tag: str) -> None:
+        tag = tag.lower()
+        for depth in range(len(self._stack) - 1, -1, -1):
+            if self._stack[depth]["tag"] == tag:
+                while len(self._stack) > depth:
+                    self._close_top()
+                return
+        # a stray end tag with no open match is ignored
+
+    def _close_top(self) -> None:
+        frame = self._stack.pop()
+        inner = "".join(frame["children"])
+        if frame["mode"] == "keep":
+            rendered = f"<{frame['tag']}{frame['attrs']}>{inner}</{frame['tag']}>"
+        elif frame["mode"] == "unwrap":
+            rendered = inner
+        else:  # drop — the subtree (including any script/style text) is discarded
+            rendered = ""
+        self._sink().append(rendered)
+
+    def result(self) -> str:
+        while self._stack:
+            self._close_top()
+        return "".join(self._root)
+
+
+def _sandbox_html(source: str) -> str:
+    """Neutralize untrusted HTML per D21 by parse-and-rebuild against the element/attr allowlist.
+
+    Unknown or malformed markup degrades to escaped text, never raw pass-through; Styler gradient
+    backgrounds are remapped to the cobalt ramp inside :func:`_sanitize_style`.
+    """
+    parser = _HtmlSanitizer()
+    try:
+        parser.feed(source)
+        parser.close()
+    except Exception:
+        pass
+    return parser.result()
+
+
+def _simple_status_table(source: str) -> str | None:
+    """Re-emit one plain status table with canonical status labels.
+
+    This path is intentionally narrow. Rich, nested, malformed, or multi-table HTML continues
+    through the general D21 sanitizer unchanged.
+    """
+    parser = _TableParser()
+    try:
+        parser.feed(source)
+        parser.close()
+    except Exception:
+        return None
+    if (
+        not parser.simple_table
+        or parser.table_count != 1
+        or parser.table_depth != 0
+        or parser._section is not None
+        or parser._row is not None
+        or parser._cell is not None
+        or not parser.seen_thead
+        or not parser.seen_tbody
+        or len(parser.header_rows) != 1
+        or not parser.body_rows
+    ):
+        return None
+    header = parser.header_rows[0]
+    headers = [text for _tag, text, _attrs in header]
+    status_columns = [i for i, text in enumerate(headers) if is_status_column(text)]
+    if len(status_columns) != 1 or any(len(row) != len(header) for row in parser.body_rows):
+        return None
+    status_column = status_columns[0]
+    head_html = "".join(f"<th{attrs}>{esc(text.strip())}</th>" for _tag, text, attrs in header)
+    rows: list[str] = []
+    for row_index, row in enumerate(parser.body_rows):
+        cells: list[str] = []
+        for index, (tag, text, attrs) in enumerate(row):
+            display = render_status(text) if index == status_column else None
+            cells.append(
+                f"<{tag}{attrs}>{display if display is not None else esc(text.strip())}</{tag}>"
+            )
+        rows.append(f"<tr{parser.body_row_attrs[row_index]}>{''.join(cells)}</tr>")
+    return (
+        f"<table{parser.table_attrs}><thead{parser.thead_attrs}>"
+        f"<tr{parser.header_row_attrs[0]}>{head_html}</tr></thead>"
+        f"<tbody{parser.tbody_attrs}>{''.join(rows)}</tbody></table>"
+    )
+
+
+def _detect_producer(source: str) -> str | None:
+    """Name the producing class when detectable — only pandas Styler is reliably fingerprinted."""
+    lowered = source.lower()
+    if any(hint in lowered for hint in _STYLER_HINTS):
+        return "pandas Styler"
+    return None
+
+
+def render_html(out: Output, ctx: RenderContext) -> str:
+    """D21 · rich HTML / Styler — sandboxed body, mimetype header strip, Styler gradient remap."""
+    mimetype = out.primary_mimetype() or "text/html"
+    source = out.text_of(mimetype)
+    producer = _detect_producer(source)
+    body = _simple_status_table(source) or _sandbox_html(source)
+
+    head = f'<span class="nb-rich-mime">{esc(mimetype)}</span>'
+    if producer:
+        head += f'<span class="nb-rich-cls">{esc(producer)}</span>'
+    return (
+        '<div class="nb-rich">'
+        f'<div class="nb-rich-head">{head}</div>'
+        f'<div class="nb-rich-body">{body}</div>'
+        "</div>"
+    )
+
+
+# ==============================================================================================
+# D22 · JSON viewer
+# ==============================================================================================
+
+
+def _coerce_json(raw: Any) -> Any:
+    """A bundle value may already be a JSON object; a string is parsed, or kept as a string leaf."""
+    if isinstance(raw, str):
+        try:
+            return json.loads(raw)
+        except (ValueError, TypeError):
+            return raw
+    return raw
+
+
+def _json_leaf(value: Any) -> str:
+    if isinstance(value, str):
+        return f'<span class="nb-json-str">"{esc(value)}"</span>'
+    if isinstance(value, bool):
+        return f'<span class="nb-json-num">{"true" if value else "false"}</span>'
+    if value is None:
+        return '<span class="nb-json-num">null</span>'
+    if isinstance(value, (int, float)):
+        return f'<span class="nb-json-num">{esc(value)}</span>'
+    # Any other type (should not occur from json.loads) degrades to an escaped string leaf.
+    return f'<span class="nb-json-str">"{esc(value)}"</span>'
+
+
+def _json_container(
+    open_b: str, close_b: str, items: list[tuple[Any, Any]], depth: int, keyed: bool
+) -> str:
+    rows: list[str] = []
+    last = len(items) - 1
+    for position, (key, value) in enumerate(items):
+        comma = "" if position == last else '<span class="nb-json-punct">,</span>'
+        key_html = (
+            f'<span class="nb-json-key">"{esc(key)}"</span><span class="nb-json-punct">: </span>'
+            if keyed
+            else ""
+        )
+        rows.append(
+            f'<div style="padding-left:22px">{key_html}{_json_node(value, depth + 1)}{comma}</div>'
+        )
+    return (
+        f'<span class="nb-json-caret">{_CARET_OPEN}</span> '
+        f'<span class="nb-json-punct">{open_b}</span>'
+        f"{''.join(rows)}"
+        f'<span class="nb-json-punct">{close_b}</span>'
+    )
+
+
+def _json_node(value: Any, depth: int) -> str:
+    """Render one JSON node; past the expansion depth, containers collapse to a count."""
+    if isinstance(value, dict):
+        if depth >= _JSON_EXPAND_LEVELS:
+            return (
+                f'<span class="nb-json-caret">{_CARET_CLOSED}</span> '
+                f'<span class="nb-json-punct">{{{len(value)}}}</span>'
+            )
+        return _json_container("{", "}", list(value.items()), depth, keyed=True)
+    if isinstance(value, list):
+        if depth >= _JSON_EXPAND_LEVELS:
+            return (
+                f'<span class="nb-json-caret">{_CARET_CLOSED}</span> '
+                f'<span class="nb-json-punct">[{len(value)}]</span>'
+            )
+        return _json_container("[", "]", list(enumerate(value)), depth, keyed=False)
+    return _json_leaf(value)
+
+
+def render_json(out: Output, ctx: RenderContext) -> str:
+    """D22 · JSON viewer — two-level expansion, colored keys/values, deeper levels collapsed."""
+    value = _coerce_json(out.data.get("application/json"))
+    body = _json_node(value, 0)
+    return (
+        '<div class="nb-json">'
+        '<div class="nb-json-head"><span class="nb-rich-mime">application/json</span></div>'
+        f'<div class="nb-json-body">{body}</div>'
+        "</div>"
+    )