geojson-diff 0.1.0__py3-none-any.whl

geojson_diff/render/__init__.py

@@ -0,0 +1,146 @@
+"""Output formats: text, JSON, Markdown, GeoJSON diff layer and HTML."""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+from ..core import DiffResult, FeatureChange
+
+__all__ = [
+    "FORMATS",
+    "describe_change",
+    "format_area",
+    "format_distance",
+    "format_value",
+    "render",
+]
+
+FORMATS = ("text", "json", "md", "geojson", "html")
+
+
+def format_value(value: Any, limit: int = 60) -> str:
+    """Compact JSON rendering of a property value, truncated to ``limit`` characters."""
+    text = json.dumps(value, ensure_ascii=False, sort_keys=True, default=str)
+    if len(text) > limit:
+        text = text[: limit - 3] + "..."
+    return text
+
+
+def format_distance(value: float | None, units: str = "m") -> str:
+    if value is None or not math.isfinite(value):
+        return "n/a"
+    if units != "m":
+        return f"{value:.4g} units"
+    if abs(value) >= 1000.0:
+        return f"{value / 1000.0:.3g} km"
+    if abs(value) >= 1.0:
+        return f"{value:.1f} m"
+    return f"{value:.3g} m"
+
+
+def _signed(text: str, value: float) -> str:
+    return ("+" if value > 0 else "") + text
+
+
+def format_area(value: float, units: str = "m", signed: bool = False, sup: bool = False) -> str:
+    sq = "²" if sup else "2"
+    if units != "m":
+        text = f"{value:.4g} units{sq}"
+    elif abs(value) >= 1e6:
+        text = f"{value / 1e6:.3g} km{sq}"
+    elif abs(value) >= 1e4:
+        text = f"{value / 1e4:.3g} ha"
+    else:
+        text = f"{value:.1f} m{sq}"
+    return _signed(text, value) if signed else text
+
+
+def format_length(value: float, units: str = "m", signed: bool = False) -> str:
+    text = format_distance(value, units)
+    return _signed(text, value) if signed else text
+
+
+def describe_change(change: FeatureChange, sup: bool = False, arrow: str = "->") -> list[str]:
+    """Human-readable detail lines for one change (shared by all text formats)."""
+    lines: list[str] = []
+    for prop in change.properties:
+        if prop.op == "add":
+            lines.append(f"+ {prop.name}: {format_value(prop.new)}")
+        elif prop.op == "remove":
+            lines.append(f"- {prop.name}: {format_value(prop.old)}")
+        else:
+            line = f"{prop.name}: {format_value(prop.old)} {arrow} {format_value(prop.new)}"
+            if prop.type_changed:
+                line += f" ({prop.old_type} {arrow} {prop.new_type})"
+            lines.append(line)
+    geom = change.geometry
+    if geom is not None and geom.changed:
+        units = geom.units
+        if geom.type_changed:
+            lines.append(f"geometry type: {geom.old_type} {arrow} {geom.new_type}")
+        parts = []
+        if geom.hausdorff is not None:
+            parts.append(f"Hausdorff {format_distance(geom.hausdorff, units)}")
+        if geom.centroid_shift is not None:
+            parts.append(f"centroid shift {format_distance(geom.centroid_shift, units)}")
+        vertex = []
+        if geom.vertices_moved:
+            vertex.append(f"{geom.vertices_moved} moved")
+        if geom.vertices_added:
+            vertex.append(f"{geom.vertices_added} added")
+        if geom.vertices_removed:
+            vertex.append(f"{geom.vertices_removed} removed")
+        if vertex:
+            parts.append(
+                f"vertices {', '.join(vertex)} ({geom.vertices_old} {arrow} {geom.vertices_new})"
+            )
+        if geom.area_old or geom.area_new:
+            parts.append(f"area {format_area(geom.area_delta, units, True, sup)}")
+        if geom.length_old or geom.length_new:
+            parts.append(f"length {format_length(geom.length_delta, units, True)}")
+        if geom.symmetric_difference_area is not None:
+            parts.append(
+                f"symmetric difference {format_area(geom.symmetric_difference_area, units, sup=sup)}"
+            )
+        lines.append("geometry: " + ", ".join(parts))
+    if change.status in ("added", "removed"):
+        props = change.feature.get("properties") or {}
+        shown = [f"{k}: {format_value(v, 40)}" for k, v in list(props.items())[:3]]
+        if len(props) > 3:
+            shown.append(f"... {len(props) - 3} more")
+        lines.extend(shown)
+    return lines
+
+
+def render(result: DiffResult, fmt: str = "text", **kwargs: Any) -> str:
+    """Render ``result`` as ``text``, ``json``, ``md``, ``geojson`` or ``html``."""
+    fmt = {"markdown": "md", "txt": "text", "htm": "html"}.get(fmt, fmt)
+    if fmt == "text":
+        from .text import render_text
+
+        return render_text(result, **kwargs)
+    if fmt == "json":
+        from .machine import render_json
+
+        return render_json(result, **kwargs)
+    if fmt == "md":
+        from .markdown import render_markdown
+
+        return render_markdown(result, **kwargs)
+    if fmt == "geojson":
+        from .layer import render_layer
+
+        return render_layer(result, **kwargs)
+    if fmt == "html":
+        from .html import render_html
+
+        return render_html(result, **kwargs)
+    raise ValueError(f"unknown format {fmt!r}; choose from {', '.join(FORMATS)}")
+
+
+def summary_counts(result: DiffResult) -> dict[str, int]:
+    return {
+        k: result.counts.get(k, 0) for k in ("added", "removed", "modified", "moved", "unchanged")
+    }

geojson_diff/render/html.py

@@ -0,0 +1,237 @@
+"""Self-contained HTML report with a Leaflet before/after map."""
+
+from __future__ import annotations
+
+import html
+import json
+import re
+from typing import Any
+
+from ..core import STATUSES, DiffResult
+from . import describe_change, format_area, format_length
+from .layer import STYLE, diff_layer
+
+__all__ = ["DEFAULT_TILES", "OSM_ATTRIBUTION", "render_html", "script_json"]
+
+LEAFLET_VERSION = "1.9.4"
+_LEAFLET_JS = f"https://unpkg.com/leaflet@{LEAFLET_VERSION}/dist/leaflet.js"
+_LEAFLET_CSS = f"https://unpkg.com/leaflet@{LEAFLET_VERSION}/dist/leaflet.css"
+_LEAFLET_JS_SRI = "sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo="
+_LEAFLET_CSS_SRI = "sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY="
+
+DEFAULT_TILES = "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
+OSM_ATTRIBUTION = (
+    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
+)
+
+
+def script_json(value: Any) -> str:
+    """JSON that is safe inside ``<script type="application/json">``.
+
+    ``<``, ``>`` and ``&`` are written as Unicode escapes, so a value such as
+    ``</script><script>alert(1)</script>`` cannot terminate the element.
+    """
+    text = json.dumps(value, ensure_ascii=False, allow_nan=False, default=str)
+    return (
+        text.replace("&", "\\u0026")
+        .replace("<", "\\u003c")
+        .replace(">", "\\u003e")
+        .replace("
", "\\u2028")
+        .replace("
", "\\u2029")
+    )
+
+
+_MARKER = re.compile("@@[A-Z_]+@@")
+
+
+def _e(value: Any) -> str:
+    return html.escape(str(value), quote=True)
+
+
+_TEMPLATE = """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="strict-origin-when-cross-origin">
+<title>@@TITLE@@</title>
+<link rel="stylesheet" href="@@LEAFLET_CSS@@" integrity="@@LEAFLET_CSS_SRI@@" crossorigin="">
+<style>
+:root { --fg:#1f2328; --muted:#59636e; --bg:#ffffff; --panel:#f6f8fa; --border:#d1d9e0; }
+@media (prefers-color-scheme: dark) {
+  :root { --fg:#e6edf3; --muted:#9198a1; --bg:#0d1117; --panel:#151b23; --border:#3d444d; }
+}
+* { box-sizing: border-box; }
+body { margin:0; font:14px/1.5 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif; color:var(--fg); background:var(--bg); }
+header, main { max-width:1200px; margin:0 auto; padding:16px; }
+h1 { font-size:20px; margin:0 0 4px; word-break:break-all; }
+.meta { color:var(--muted); }
+.cards { display:flex; flex-wrap:wrap; gap:8px; margin:12px 0; }
+.card { background:var(--panel); border:1px solid var(--border); border-radius:6px; padding:8px 12px; min-width:96px; }
+.card b { display:block; font-size:22px; }
+.swatch { display:inline-block; width:10px; height:10px; border-radius:2px; margin-right:6px; }
+#map { height:480px; border:1px solid var(--border); border-radius:6px; }
+.nomap { padding:24px; background:var(--panel); border:1px solid var(--border); border-radius:6px; }
+.table-wrap { overflow-x:auto; }
+table { border-collapse:collapse; width:100%; margin-top:16px; }
+th, td { text-align:left; vertical-align:top; padding:6px 8px; border-bottom:1px solid var(--border); }
+td.details { font-family:ui-monospace,SFMono-Regular,Consolas,monospace; font-size:12px; word-break:break-word; }
+.popup div { font-family:ui-monospace,Consolas,monospace; font-size:12px; }
+footer { color:var(--muted); font-size:12px; padding:16px; text-align:center; }
+</style>
+</head>
+<body>
+<header>
+<h1>@@TITLE@@</h1>
+<div class="meta">@@META@@</div>
+<div class="cards">@@CARDS@@</div>
+</header>
+<main>
+@@MAP@@
+<div class="table-wrap"><table>
+<thead><tr><th>Change</th><th>Feature</th><th>Geometry</th><th>Details</th></tr></thead>
+<tbody>
+@@ROWS@@
+</tbody>
+</table></div>
+</main>
+<footer>Generated by geojson-diff @@VERSION@@</footer>
+<script id="gjd-data" type="application/json">@@DATA@@</script>
+<script src="@@LEAFLET_JS@@" integrity="@@LEAFLET_JS_SRI@@" crossorigin=""></script>
+<script>
+(function () {
+  "use strict";
+  var data = JSON.parse(document.getElementById("gjd-data").textContent);
+  var el = document.getElementById("map");
+  if (!el || typeof L === "undefined") { return; }
+  var map = L.map(el);
+  L.tileLayer(data.tiles, { maxZoom: 19, attribution: data.attribution }).addTo(map);
+  function style(f) {
+    var p = f.properties, before = p["diff:role"] === "before";
+    return { color: p.stroke, weight: before ? 2 : 3, opacity: p["stroke-opacity"],
+             fillColor: p.fill, fillOpacity: p["fill-opacity"], dashArray: before ? "5 5" : null };
+  }
+  function popup(f) {
+    var box = document.createElement("div");
+    box.className = "popup";
+    var head = document.createElement("strong");
+    head.textContent = f.properties.title;
+    box.appendChild(head);
+    (f.properties["diff:details"] || []).forEach(function (line) {
+      var row = document.createElement("div");
+      row.textContent = line;
+      box.appendChild(row);
+    });
+    return box;
+  }
+  function layer(role) {
+    return L.geoJSON(data.layer, {
+      filter: function (f) { return f.properties["diff:role"] === role; },
+      style: style,
+      pointToLayer: function (f, latlng) {
+        var s = style(f);
+        s.radius = role === "before" ? 5 : 7;
+        s.fillOpacity = role === "before" ? 0.2 : 0.8;
+        return L.circleMarker(latlng, s);
+      },
+      onEachFeature: function (f, lyr) { lyr.bindPopup(popup(f)); }
+    });
+  }
+  var before = layer("before").addTo(map);
+  var after = layer("change").addTo(map);
+  L.control.layers(null, { "Before (old geometry of moved features)": before,
+                           "After / added / removed": after }, { collapsed: false }).addTo(map);
+  var b = data.bbox;
+  if (b) {
+    if (b[0] === b[2] && b[1] === b[3]) { map.setView([b[1], b[0]], 17); }
+    else { map.fitBounds([[b[1], b[0]], [b[3], b[2]]], { padding: [24, 24], maxZoom: 18 }); }
+  } else { map.setView([0, 0], 2); }
+})();
+</script>
+</body>
+</html>
+"""
+
+
+def render_html(
+    result: DiffResult,
+    title: str = "",
+    tiles: str = DEFAULT_TILES,
+    attribution: str = OSM_ATTRIBUTION,
+    max_rows: int = 2000,
+) -> str:
+    """A single HTML file: summary cards, a Leaflet map and a table of changes.
+
+    Leaflet is loaded from unpkg with Subresource Integrity; OpenStreetMap
+    tiles are attributed. Every data value is HTML-escaped in the table and
+    embedded as escaped JSON for the map, whose popups use ``textContent``.
+    """
+    from .. import __version__
+
+    heading = title or f"GeoJSON diff: {result.old_name} → {result.new_name}"
+    units = result.units
+    meta = (
+        f"{result.old_count} → {result.new_count} features · matched by "
+        f"{', '.join(result.options.strategies())} · tolerance {result.options.tolerance}"
+    )
+    if result.has_changes:
+        meta += (
+            f" · area Δ {format_area(result.area_delta, units, True, True)}"
+            f" · length Δ {format_length(result.length_delta, units, True)}"
+        )
+    cards = "".join(
+        f'<div class="card"><span class="swatch" style="background:{STYLE[s]}"></span>'
+        f"{_e(s)}<b>{result.counts.get(s, 0)}</b></div>"
+        for s in STATUSES
+    )
+    rows: list[str] = []
+    changed = result.changed
+    for change in changed[:max_rows]:
+        details = "<br>".join(_e(d) for d in describe_change(change, sup=True, arrow="→"))
+        rows.append(
+            "<tr>"
+            f'<td><span class="swatch" style="background:{STYLE[change.status]}"></span>'
+            f"{_e(change.status)}</td>"
+            f"<td>{_e(change.key)}</td>"
+            f"<td>{_e(change.geometry_type or '-')}</td>"
+            f'<td class="details">{details or "-"}</td>'
+            "</tr>"
+        )
+    if len(changed) > max_rows:
+        rows.append(f'<tr><td colspan="4">… {len(changed) - max_rows} more changes</td></tr>')
+    if not changed:
+        rows.append('<tr><td colspan="4">No feature changes.</td></tr>')
+
+    layer = diff_layer(result, include_properties=False)
+    for feature in layer["features"]:
+        props: dict[str, Any] = feature["properties"]
+        props["diff:details"] = [d for d in str(props.pop("description", "")).split("; ") if d]
+    if units == "m":
+        map_html = '<div id="map" role="region" aria-label="Map of changed features"></div>'
+    else:
+        map_html = (
+            '<div class="nomap">Map not shown: the coordinates are not longitude/latitude '
+            "(RFC 7946).</div>"
+        )
+    box = result.bbox
+    data = {
+        "layer": layer,
+        "bbox": list(box) if box else None,
+        "tiles": tiles,
+        "attribution": attribution,
+    }
+    replacements = {
+        "@@TITLE@@": _e(heading),
+        "@@META@@": _e(meta),
+        "@@CARDS@@": cards,
+        "@@MAP@@": map_html,
+        "@@ROWS@@": "\n".join(rows),
+        "@@VERSION@@": _e(__version__),
+        "@@LEAFLET_CSS@@": _LEAFLET_CSS,
+        "@@LEAFLET_CSS_SRI@@": _LEAFLET_CSS_SRI,
+        "@@LEAFLET_JS@@": _LEAFLET_JS,
+        "@@LEAFLET_JS_SRI@@": _LEAFLET_JS_SRI,
+    }
+    replacements["@@DATA@@"] = script_json(data)
+    # One pass, so marker-like text inside data values is never substituted.
+    return _MARKER.sub(lambda m: replacements[m.group(0)], _TEMPLATE)

geojson_diff/render/layer.py

@@ -0,0 +1,111 @@
+"""GeoJSON "diff layer": features styled by change type (simplestyle-spec)."""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+from ..core import DiffResult, FeatureChange
+from . import describe_change
+
+__all__ = ["STYLE", "diff_layer", "render_layer"]
+
+STYLE: dict[str, str] = {
+    "added": "#2e7d32",
+    "removed": "#c62828",
+    "modified": "#ef6c00",
+    "moved": "#1565c0",
+    "unchanged": "#9e9e9e",
+    "before": "#757575",
+}
+"""Colours per change type (and for the ``before`` outline of moved features)."""
+
+_SIMPLESTYLE = {
+    "title",
+    "description",
+    "marker-size",
+    "marker-symbol",
+    "marker-color",
+    "stroke",
+    "stroke-opacity",
+    "stroke-width",
+    "fill",
+    "fill-opacity",
+}
+
+
+def _styled(
+    change: FeatureChange,
+    source: dict[str, Any] | None,
+    role: str,
+    include_properties: bool,
+) -> dict[str, Any]:
+    color = STYLE["before"] if role == "before" else STYLE[change.status]
+    props: dict[str, Any] = {}
+    if include_properties and source is not None:
+        for key, value in (source.get("properties") or {}).items():
+            if key not in _SIMPLESTYLE and not str(key).startswith("diff:"):
+                props[key] = value
+    details = describe_change(change)
+    props.update(
+        {
+            "diff:status": change.status,
+            "diff:role": role,
+            "diff:key": change.key,
+            "diff:changed": [p.name for p in change.properties],
+            "title": f"{change.status}: {change.key}" + (" (before)" if role == "before" else ""),
+            "description": "; ".join(details),
+            "stroke": color,
+            "stroke-width": 1 if role == "before" else 2,
+            "stroke-opacity": 0.6 if role == "before" else 1.0,
+            "fill": color,
+            "fill-opacity": 0.05 if role == "before" else 0.35,
+            "marker-color": color,
+            "marker-size": "small" if role == "before" else "medium",
+        }
+    )
+    if change.geometry is not None and math.isfinite(change.geometry.hausdorff or math.nan):
+        props["diff:hausdorff"] = round(change.geometry.hausdorff or 0.0, 3)
+    feature: dict[str, Any] = {
+        "type": "Feature",
+        "properties": props,
+        "geometry": (source or {}).get("geometry"),
+    }
+    if source is not None and source.get("id") is not None:
+        feature["id"] = source["id"] if role == "change" else f"{source['id']}:before"
+    return feature
+
+
+def diff_layer(
+    result: DiffResult, include_properties: bool = True, include_unchanged: bool = False
+) -> dict[str, Any]:
+    """Build a FeatureCollection that visualises the diff.
+
+    Added, modified and moved features carry their new geometry, removed
+    features their old one; moved features also get a grey ``before``
+    feature. Styling uses the simplestyle-spec properties that GitHub's map
+    renderer understands; ``diff:*`` properties describe the change.
+    """
+    features: list[dict[str, Any]] = []
+    for change in result.changes:
+        if change.status == "unchanged" and not include_unchanged:
+            continue
+        if change.status == "removed":
+            features.append(_styled(change, change.old, "change", include_properties))
+            continue
+        if change.status == "moved":
+            features.append(_styled(change, change.old, "before", include_properties))
+        features.append(_styled(change, change.new, "change", include_properties))
+    return {"type": "FeatureCollection", "features": features}
+
+
+def render_layer(
+    result: DiffResult,
+    include_properties: bool = True,
+    include_unchanged: bool = False,
+    indent: int | None = None,
+) -> str:
+    """Serialise :func:`diff_layer` as GeoJSON text."""
+    layer = diff_layer(result, include_properties, include_unchanged)
+    return json.dumps(layer, indent=indent, ensure_ascii=False) + "\n"

geojson_diff/render/machine.py

@@ -0,0 +1,20 @@
+"""Machine-readable, JSON-Patch-like output."""
+
+from __future__ import annotations
+
+import json
+
+from ..core import DiffResult
+
+__all__ = ["render_json"]
+
+
+def render_json(result: DiffResult, include_features: bool = True, indent: int = 2) -> str:
+    """Serialise ``result`` as JSON.
+
+    Property changes use JSON Patch vocabulary (``add`` / ``remove`` /
+    ``replace`` with RFC 6901 paths) plus ``old``, ``old_type`` and
+    ``new_type`` members; geometry changes add a ``replace`` of
+    ``/geometry`` and a ``geometry`` block of metrics.
+    """
+    return json.dumps(result.to_dict(include_features), indent=indent, ensure_ascii=False) + "\n"

geojson_diff/render/markdown.py

@@ -0,0 +1,143 @@
+"""Markdown summary for pull-request comments and CI job summaries."""
+
+from __future__ import annotations
+
+import json
+
+from ..core import DiffResult
+from . import describe_change, format_area, format_length
+
+__all__ = ["escape_markdown", "render_markdown"]
+
+_ESCAPES = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    "|": "&#124;",
+    "@": "&#64;",  # never ping users from data values
+    "#": "&#35;",  # never auto-link issues from data values
+    "\\": "&#92;",
+    "`": "&#96;",
+    "*": "&#42;",
+    "_": "&#95;",
+    "[": "&#91;",
+    "]": "&#93;",
+    "~": "&#126;",
+    "!": "&#33;",
+    "$": "&#36;",
+}
+
+
+def escape_markdown(text: str) -> str:
+    """Escape ``text`` for a GitHub-flavoured Markdown table cell.
+
+    Every character with Markdown or HTML meaning becomes an HTML entity and
+    line breaks become spaces, so data values cannot inject markup, links,
+    mentions or table columns.
+    """
+    out = "".join(_ESCAPES.get(ch, ch) for ch in text)
+    return " ".join(out.splitlines())
+
+
+_LABELS = {
+    "added": "added",
+    "removed": "removed",
+    "modified": "modified",
+    "moved": "moved",
+    "unchanged": "unchanged",
+}
+
+
+def render_markdown(
+    result: DiffResult,
+    max_rows: int = 100,
+    title: str = "",
+    include_map: bool = False,
+    map_limit: int = 60_000,
+) -> str:
+    """Markdown summary: counts table plus a collapsible table of changes.
+
+    ``include_map`` appends the diff layer as a ```` ```geojson ```` block,
+    which GitHub renders as an interactive map, when it fits in ``map_limit``
+    characters.
+    """
+    c = result.counts
+    heading = title or f"GeoJSON diff: {result.old_name} → {result.new_name}"
+    lines: list[str] = [f"### {escape_markdown(heading)}", ""]
+    total = sum(c.get(s, 0) for s in ("added", "removed", "modified", "moved"))
+    strategies = ", ".join(result.options.strategies())
+    if total:
+        lines.append(
+            f"**{total} feature change{'s' if total != 1 else ''}** "
+            f"({result.old_count} → {result.new_count} features; matched by "
+            f"{escape_markdown(strategies)}; tolerance {result.options.tolerance})"
+        )
+    else:
+        lines.append(
+            f"**No feature changes** ({result.old_count} → {result.new_count} features; "
+            f"matched by {escape_markdown(strategies)}; tolerance {result.options.tolerance})"
+        )
+    lines += [
+        "",
+        "| Added | Removed | Modified | Moved | Unchanged |",
+        "|---:|---:|---:|---:|---:|",
+        "| "
+        + " | ".join(
+            str(c.get(s, 0)) for s in ("added", "removed", "modified", "moved", "unchanged")
+        )
+        + " |",
+        "",
+    ]
+    for warning in result.warnings:
+        lines.append(f"> **Warning:** {escape_markdown(warning)}")
+        lines.append("")
+    if total:
+        units = result.units
+        box = result.bbox
+        facts = []
+        if box:
+            facts.append("bbox of changes " + ", ".join(f"{v:.6f}" for v in box))
+        facts.append(f"area Δ {format_area(result.area_delta, units, True, True)}")
+        facts.append(f"length Δ {format_length(result.length_delta, units, True)}")
+        lines.append(" · ".join(facts))
+        lines.append("")
+        changed = result.changed
+        opened = " open" if len(changed) <= 20 else ""
+        lines.append(f"<details{opened}><summary>Feature changes ({len(changed)})</summary>")
+        lines.append("")
+        lines.append("| Change | Feature | Geometry | Details |")
+        lines.append("|---|---|---|---|")
+        for change in changed[:max_rows]:
+            details = "<br>".join(
+                escape_markdown(d) for d in describe_change(change, sup=True, arrow="→")
+            )
+            lines.append(
+                f"| {_LABELS[change.status]} | {escape_markdown(change.key)} | "
+                f"{escape_markdown(change.geometry_type or '-')} | {details or '-'} |"
+            )
+        if len(changed) > max_rows:
+            lines.append(f"| … | {len(changed) - max_rows} more | | |")
+        lines.append("")
+        lines.append("</details>")
+        lines.append("")
+        if include_map:
+            from .layer import diff_layer
+
+            layer = json.dumps(diff_layer(result, include_properties=False), ensure_ascii=False)
+            # Unicode escapes keep data from closing the fence or carrying markup.
+            for char, code in (
+                ("`", "\\u0060"),
+                ("<", "\\u003c"),
+                (">", "\\u003e"),
+                ("&", "\\u0026"),
+            ):
+                layer = layer.replace(char, code)
+            if len(layer) <= map_limit:
+                lines += ["```geojson", layer, "```", ""]
+            else:
+                lines += [
+                    f"_Map omitted: the diff layer exceeds {map_limit} characters._",
+                    "",
+                ]
+    lines.append("<sub>Generated by geojson-diff</sub>")
+    return "\n".join(lines) + "\n"