ttl3d 0.2.2__py3-none-any.whl

ttl3d/__init__.py

@@ -0,0 +1,2 @@
+"""ttl3d: render any Turtle / RDF graph as a self-contained 2D/3D HTML viewer."""
+__version__ = "0.2.2"

ttl3d/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

ttl3d/cli.py

@@ -0,0 +1,92 @@
+"""Command line entry point: ttl3d FILE [FILE ...] [-o OUT] [--view 3d|2d] [--color-by KEY] ..."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__, graph, layout, load, render
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ttl3d",
+        description="Render Turtle / RDF files as one self-contained 2D/3D HTML viewer.")
+    p.add_argument("files", nargs="+", help="RDF files; the format is guessed from the extension")
+    p.add_argument("-o", "--out",
+                   help="output HTML path (default: <first file stem>-<view>.html in the current directory)")
+    p.add_argument("--color-by", choices=graph.COLOR_KEYS, default="file",
+                   help="what the node colors and legend mean (default: file)")
+    p.add_argument("--layout", choices=layout.LAYOUT_MODES, default="auto",
+                   help=f"stress = pinned Kamada-Kawai (auto up to {layout.STRESS_MAX_NODES} nodes); "
+                        "force = live simulation")
+    p.add_argument("--labels", choices=layout.LABEL_MODES, default="auto",
+                   help=f"permanent labels (auto: nodes up to {layout.LABEL_MAX_NODES}, "
+                        f"edges up to {layout.LABEL_MAX_LINKS}); hover = tooltips only")
+    p.add_argument("--view", choices=render.VIEWS, default="3d",
+                   help="starting view; the page can switch between 3d and 2d (default: 3d)")
+    p.add_argument("--title", help="page title (default: first file stem)")
+    p.add_argument("--lang", default="en",
+                   help="preferred language tag for labels and definitions (default: en); "
+                        "untagged literals rank next, other languages become synonyms"
+                        "; matched exactly (en does not select en-GB)")
+    p.add_argument("--type-links", action="store_true",
+                   help="draw rdf:type as an edge from each instance to its class (default: card only)")
+    p.add_argument("--attribute-preds", action="append", default=[], metavar="PRED[,PRED...]",
+                   help="predicates to show on the card instead of drawing, as prefix:local, full IRIs, "
+                        "or <urn:...> in angle brackets (e.g. foaf:homepage,rdfs:seeAlso); repeatable")
+    p.add_argument("--format", metavar="NAME",
+                   help="rdflib parser name for every input (turtle, xml, nt, n3, json-ld, trig, nquads); "
+                        "default: guess from the extension, then try turtle")
+    p.add_argument("--version", action="version", version=f"ttl3d {__version__}")
+    return p
+
+
+def _fail(problem) -> int:
+    """Print one line to stderr and return the exit code; `problem` is an exception or a string."""
+    print(f"ttl3d: error: {problem}", file=sys.stderr)
+    return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    # stderr already replaces characters it cannot encode; stdout raises instead, and a console
+    # that cannot show the output path (Windows with stdout redirected, an ASCII locale) must
+    # still get the summary line, not a UnicodeEncodeError traceback
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(errors="backslashreplace")
+    args = build_parser().parse_args(argv)
+    first = Path(args.files[0]).stem
+    out = Path(args.out) if args.out else Path.cwd() / f"{first}-{args.view}.html"
+    # by identity, not by spelling: on case-insensitive filesystems Graph.ttl is graph.ttl
+    if out.exists() and any(Path(f).exists() and out.samefile(f) for f in args.files):
+        return _fail(f"output {out} is also an input file; pick another -o path")
+    try:
+        ds = load.load_files(args.files, fmt=args.format)
+        extra = graph.resolve_terms([t for arg in args.attribute_preds for t in arg.split(",") if t],
+                                    ds)
+    except (OSError, ValueError) as e:      # LoadError is a ValueError
+        return _fail(e)
+    data = graph.build(ds, color_by=args.color_by, lang=args.lang,
+                       type_links=args.type_links, attribute_preds=extra)
+    mode = layout.choose_layout(len(data["nodes"]), args.layout)
+    if mode == "stress":
+        notice = layout.stress_notice(len(data["nodes"]))
+        if notice:
+            print(notice, file=sys.stderr)
+        ids = [n["id"] for n in data["nodes"]]
+        pos3 = layout.stress_positions(ids, data["links"], dim=3)
+        pos2 = layout.stress_positions(ids, data["links"], dim=2)
+        for n in data["nodes"]:
+            n["x"], n["y"], n["z"] = pos3[n["id"]]
+            n["x2"], n["y2"] = pos2[n["id"]]
+    labels = layout.choose_labels(len(data["nodes"]), len(data["links"]), args.labels)
+    html = render.render_html(data, title=args.title or first,
+                              pinned=(mode == "stress"), labels=labels, view=args.view)
+    try:
+        render.write_html(html, out)
+    except OSError as e:
+        return _fail(e)
+    shown = "+".join(k for k, v in labels.items() if v) or "hover only"
+    print(f'{len(data["nodes"])} nodes, {len(data["links"])} links -> {out} '
+          f'(view: {args.view}, layout: {mode}, labels: {shown})')
+    return 0

ttl3d/graph.py

@@ -0,0 +1,196 @@
+"""Build the node/link model of a Dataset.
+
+Nodes are every IRI that is a subject of some triple or the object of a link,
+except IRIs of the RDF/RDFS/OWL/XSD vocabularies and ontology headers.
+Links are IRI-to-IRI triples whose predicate describes a relation rather than
+an attribute (rdf:type, imports and provenance go to the node card instead).
+Parallel edges collapse into one link listing every predicate; an edge
+asserted in both directions is one link whose `reverse` list holds the
+predicates pointing back. Each node remembers the file that first declares
+it; each link remembers the file(s) asserting it, so a file that only adds
+edges between other files' nodes still owns something visible.
+
+A node's label is chosen by preference tier: the requested `--lang` language
+first, then untagged literals, then any other language, alphabetical within
+a tier; the same order picks the definition among skos:definition,
+rdfs:comment and dcterms:description. Label and altLabel values that lose
+that pick become synonyms in `alt`, and a definition-slot literal that loses
+its pick stays visible in the property table instead of vanishing. Literal
+`dcterms:source` / `prov:wasDerivedFrom` values land in the property table
+too; only IRI sources appear in the node's `sources` list.
+"""
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+
+from rdflib import Literal, URIRef
+from rdflib.namespace import DCTERMS, OWL, PROV, RDF, RDFS, SKOS, XSD
+
+from .load import Dataset
+
+COLOR_KEYS = ("file", "type", "namespace")
+RESERVED = tuple(str(ns) for ns in (RDF, RDFS, OWL, XSD))
+ATTRIBUTE_PREDS = {RDF.type, OWL.imports, OWL.versionIRI, OWL.priorVersion,
+                   RDFS.isDefinedBy, PROV.wasDerivedFrom, DCTERMS.source}
+LABEL_PREDS = (RDFS.label, SKOS.prefLabel)
+DEFINITION_PREDS = (SKOS.definition, RDFS.comment, DCTERMS.description)
+SOURCE_PREDS = (PROV.wasDerivedFrom, DCTERMS.source)
+
+
+def local(u) -> str:
+    return re.split(r"[/#]", str(u))[-1] or str(u)
+
+
+def namespace_of(u) -> str:
+    s = str(u)
+    return s[:max(s.rfind("#"), s.rfind("/")) + 1]
+
+
+def _literals(g, s, p, lang: str | None) -> list:
+    """Literal objects of (s, p): the requested language first, then untagged,
+    then any other language; alphabetical within a tier."""
+    def rank(o):
+        tag = (o.language or "").lower()
+        tier = 0 if lang and tag == lang.lower() else 1 if not tag else 2
+        return (tier, str(o))
+    return sorted((o for o in g.objects(s, p) if isinstance(o, Literal)), key=rank)
+
+
+def _first(g, s, preds, lang: str | None = None):
+    for p in preds:
+        vals = _literals(g, s, p, lang)
+        if vals:
+            return str(vals[0])
+    return None
+
+
+def _prefix(ds: Dataset, ns: str) -> str:
+    """Prefix bound to a namespace; the empty default prefix shows as ':'.
+    Unbound namespaces fall back to the IRI base itself."""
+    if ns in ds.prefixes:
+        return ds.prefixes[ns] or ":"
+    return ns
+
+
+def resolve_terms(terms, ds: Dataset) -> set:
+    """Turn 'prefix:local', full IRIs, or '<...>'-wrapped IRIs into URIRefs using the
+    dataset's bindings. Angle brackets are the Turtle convention for "this is a full
+    IRI, not a CURIE" -- needed for schemes like urn: or mailto: that have no "://"."""
+    by_prefix: dict = {}
+    for ns, prefix in ds.prefixes.items():
+        by_prefix.setdefault(prefix, ns)
+    out = set()
+    for term in terms:
+        if term.startswith("<") and term.endswith(">"):
+            out.add(URIRef(term[1:-1]))
+            continue
+        if "://" in term:
+            out.add(URIRef(term))
+            continue
+        prefix, _, name = term.partition(":")
+        if prefix not in by_prefix:
+            raise ValueError(f"unknown prefix in {term!r}; bind it in an input file, "
+                             f"or write the full IRI as <{term}>")
+        out.add(URIRef(by_prefix[prefix] + name))
+    return out
+
+
+def build(ds: Dataset, color_by: str = "file", lang: str | None = None,
+          type_links: bool = False, attribute_preds=()) -> dict:
+    if color_by not in COLOR_KEYS:
+        raise ValueError(f"color_by must be one of {COLOR_KEYS}, got {color_by!r}")
+    g = ds.merged
+    headers = set(g.subjects(RDF.type, OWL.Ontology))
+
+    def eligible(t) -> bool:
+        return (isinstance(t, URIRef) and t not in headers
+                and not str(t).startswith(RESERVED))
+
+    attribute = (set(ATTRIBUTE_PREDS) | set(attribute_preds)) - ({RDF.type} if type_links else set())
+
+    def is_link(s, p, o) -> bool:
+        return eligible(s) and eligible(o) and p not in attribute
+
+    node_file: dict = {}          # node -> first file declaring it as a subject
+    mention_file: dict = {}       # node -> first file asserting a link touching it
+    link_files: dict = defaultdict(list)   # unordered pair -> files asserting any predicate
+    for key, fg in ds.graphs.items():
+        for s, p, o in fg:
+            if eligible(s):
+                node_file.setdefault(s, key)
+            if is_link(s, p, o):
+                mention_file.setdefault(s, key)
+                mention_file.setdefault(o, key)
+                pair = tuple(sorted((s, o), key=str))
+                if key not in link_files[pair]:
+                    link_files[pair].append(key)
+
+    merged_links: dict = defaultdict(lambda: {"fwd": set(), "rev": set()})   # pair -> predicates per direction
+    node_ids = set()
+    for s, p, o in g:
+        if eligible(s):
+            node_ids.add(s)
+        if is_link(s, p, o):
+            node_ids.add(o)
+            a, b = sorted((s, o), key=str)
+            merged_links[(a, b)]["fwd" if s == a else "rev"].add(local(p))
+
+    labels = {}
+    for s in node_ids:
+        labels[s] = _first(g, s, LABEL_PREDS, lang) or local(s)
+    src_url = {s: str(o) for s, _, o in g.triples((None, DCTERMS.identifier, None))
+               if str(o).startswith("http")}
+
+    def group_of(n, types) -> str:
+        if color_by == "file":
+            return node_file.get(n) or mention_file.get(n) or "?"
+        if color_by == "type":
+            return types[0] if types else "?"
+        return _prefix(ds, namespace_of(n))
+
+    nodes = []
+    for n in sorted(node_ids, key=str):
+        types = sorted(local(t) for t in g.objects(n, RDF.type) if t != OWL.NamedIndividual)
+        label_vals = [str(o) for p in LABEL_PREDS for o in _literals(g, n, p, lang)]
+        definition = _first(g, n, DEFINITION_PREDS, lang)
+        def_pred = next((p for p in DEFINITION_PREDS if _literals(g, n, p, lang)), None)
+        props = defaultdict(list)
+        for _, p, o in g.triples((n, None, None)):
+            if isinstance(o, Literal):
+                if p in LABEL_PREDS or p == SKOS.altLabel:
+                    continue
+                if p == def_pred and str(o) == definition:
+                    continue
+                props[local(p)].append(str(o))
+            elif isinstance(o, URIRef) and p in attribute and p != RDF.type and p not in SOURCE_PREDS:
+                props[local(p)].append(labels.get(o) or _first(g, o, LABEL_PREDS, lang) or str(o))
+        alt = sorted(({str(o) for o in g.objects(n, SKOS.altLabel)} | set(label_vals)) - {labels[n]})
+        sources = [{"label": label, "url": src_url.get(s)}
+                   for label, s in sorted(
+                       (labels.get(s) or _first(g, s, LABEL_PREDS, lang) or local(s), s)
+                       for p in SOURCE_PREDS for s in g.objects(n, p) if isinstance(s, URIRef))]
+        ns = namespace_of(n)
+        nodes.append({
+            "id": str(n), "label": labels[n], "types": types,
+            "file": node_file.get(n) or mention_file.get(n) or "?",
+            "ns": _prefix(ds, ns),
+            "group": group_of(n, types),
+            "definition": definition,
+            "alt": alt,
+            "props": {k: sorted(v) for k, v in sorted(props.items())},
+            "sources": sources,
+        })
+
+    links = []
+    for (a, b), d in sorted(merged_links.items(), key=lambda kv: (str(kv[0][0]), str(kv[0][1]))):
+        src, tgt, fwd, rev = (a, b, d["fwd"], d["rev"]) if d["fwd"] else (b, a, d["rev"], d["fwd"])
+        files = link_files.get((a, b), [])
+        links.append({"source": str(src), "target": str(tgt), "predicates": sorted(fwd),
+                      "reverse": sorted(rev), "files": files,
+                      "group": (files[0] if files else "?") if color_by == "file" else None})
+
+    groups = {n["group"] for n in nodes}
+    if color_by == "file":
+        groups |= {l["group"] for l in links}
+    return {"nodes": nodes, "links": links, "groups": sorted(groups), "color_by": color_by}

ttl3d/layout.py

@@ -0,0 +1,108 @@
+"""Scale rules and the pinned stress layout (one per view: 3D and 2D).
+
+Kamada-Kawai is quadratic in nodes and the label sprites die past a few
+thousand scene objects, so the automatic modes degrade: above
+STRESS_MAX_NODES the page runs the live force simulation instead of a
+precomputed layout, and past the label thresholds the sprites are not
+created (hover tooltips still work).
+"""
+from __future__ import annotations
+
+import math
+
+STRESS_MAX_NODES = 1000
+LABEL_MAX_NODES = 800
+LABEL_MAX_LINKS = 800
+LAYOUT_MODES = ("auto", "stress", "force")
+LABEL_MODES = ("auto", "always", "hover")
+
+SEED = 0   # networkx seeds 3-D Kamada-Kawai from a random layout; fix it so a rebuild keeps the picture
+ISLAND_GAP = 60.0        # clearance between components, in scene units (about one rest length)
+ISLANDS_PER_ROW = 10     # islands are shelved left to right, then a new row starts
+PROGRESS_MIN_NODES = 200   # below this the stress layout is instant; say nothing
+
+
+def choose_layout(n_nodes: int, mode: str = "auto") -> str:
+    if mode not in LAYOUT_MODES:
+        raise ValueError(f"layout must be one of {LAYOUT_MODES}, got {mode!r}")
+    if mode == "auto":
+        return "stress" if n_nodes <= STRESS_MAX_NODES else "force"
+    return mode
+
+
+def choose_labels(n_nodes: int, n_links: int, mode: str = "auto") -> dict:
+    if mode not in LABEL_MODES:
+        raise ValueError(f"labels must be one of {LABEL_MODES}, got {mode!r}")
+    if mode == "always":
+        return {"node": True, "edge": True}
+    if mode == "hover":
+        return {"node": False, "edge": False}
+    return {"node": n_nodes <= LABEL_MAX_NODES, "edge": n_links <= LABEL_MAX_LINKS}
+
+
+def stress_notice(n_nodes: int) -> str | None:
+    """One stderr line before the stress layouts that will take a while (None when they won't).
+    Kamada-Kawai is quadratic and runs twice (3D and 2D): ~1.2 s at 200 nodes, ~5 s at 500,
+    ~18 s at 1000."""
+    if n_nodes <= PROGRESS_MIN_NODES:
+        return None
+    msg = f"computing stress layouts (3D and 2D) for {n_nodes} nodes..."
+    if n_nodes > STRESS_MAX_NODES:
+        msg += (f" (more than {STRESS_MAX_NODES}: this is quadratic and may take minutes;"
+                " --layout force skips it)")
+    return msg
+
+
+def _kk(G, dim: int = 3) -> dict:
+    """`dim`-D Kamada-Kawai positions for one connected graph, identical in every
+    process for the same input: a subgraph view iterates in set order (which
+    follows Python's per-process hash seed), so the nodes and edges are handed
+    to networkx in sorted order and the start positions are seeded. A single
+    node sits at the origin."""
+    import networkx as nx
+    nodes = sorted(G, key=str)
+    if len(nodes) == 1:
+        return {nodes[0]: [0.0] * dim}
+    S = nx.Graph()
+    S.add_nodes_from(nodes)
+    S.add_edges_from(sorted((min(u, v, key=str), max(u, v, key=str)) for u, v in G.edges()))
+    return nx.kamada_kawai_layout(S, dim=dim, pos=nx.random_layout(S, dim=dim, seed=SEED))
+
+
+def _scaled(p: dict, links: list[dict]) -> dict[str, list[float]]:
+    """Scale raw positions so the mean edge length is about 60 (the live rest length)."""
+    lens = [d for d in (math.dist(p[l["source"]], p[l["target"]])
+                        for l in links if l["source"] in p and l["target"] in p) if d > 0]
+    scale = 60 / (sum(lens) / len(lens)) if lens else 60
+    return {n: [round(float(c) * scale, 2) for c in xyz] for n, xyz in p.items()}
+
+
+def stress_positions(node_ids: list[str], links: list[dict], dim: int = 3) -> dict[str, list[float]]:
+    """Kamada-Kawai positions per connected component, in `dim` (3 or 2) dimensions.
+    The largest component sits at the origin; every other component gets its own
+    layout and is shelved to the right of the main body, ISLANDS_PER_ROW per row,
+    with ISLAND_GAP of clearance between components. Only coordinates 0 and 1 are
+    shifted by the packing, so the same code serves both views."""
+    import networkx as nx
+    if not node_ids:
+        return {}
+    H = nx.Graph()
+    H.add_nodes_from(node_ids)
+    H.add_edges_from((l["source"], l["target"]) for l in links if l["source"] != l["target"])
+    comps = sorted(nx.connected_components(H), key=lambda c: (-len(c), min(c)))
+    pos = _scaled(_kk(H.subgraph(comps[0]), dim), links)
+    reach = max((abs(c) for xyz in pos.values() for c in xyz), default=0.0)
+    x_start = reach + ISLAND_GAP
+    x, row_y, row_h, col = x_start, 0.0, 0.0, 0
+    for comp in comps[1:]:
+        island = _scaled(_kk(H.subgraph(comp), dim), links)
+        xs = [q[0] for q in island.values()]
+        ys = [q[1] for q in island.values()]
+        if col == ISLANDS_PER_ROW:
+            x, row_y, row_h, col = x_start, row_y + row_h + ISLAND_GAP, 0.0, 0
+        for n, p in island.items():
+            pos[n] = [round(p[0] - min(xs) + x, 2), round(p[1] - min(ys) + row_y, 2), *p[2:]]
+        x += max(xs) - min(xs) + ISLAND_GAP
+        row_h = max(row_h, max(ys) - min(ys))
+        col += 1
+    return pos

ttl3d/load.py

@@ -0,0 +1,70 @@
+"""Parse one or more RDF files into a merged graph that remembers which file said what."""
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from rdflib import Graph
+from rdflib.util import guess_format
+
+
+class LoadError(ValueError):
+    """An input file could not be parsed; the message names the file."""
+
+
+@dataclass
+class Dataset:
+    files: list[Path]
+    graphs: dict[str, Graph]      # file key -> that file's own triples, in input order
+    merged: Graph                 # union of all files
+    prefixes: dict[str, str]      # namespace IRI -> prefix, first binding wins
+
+    @property
+    def stems(self) -> list[str]:
+        return list(self.graphs)
+
+
+def _unique_key(stem: str, taken: dict) -> str:
+    key, i = stem, 2
+    while key in taken:
+        key = f"{stem}~{i}"
+        i += 1
+    return key
+
+
+def _parse(f: Path, fmt: str | None = None) -> Graph:
+    """Parse one file. Without an explicit format the extension decides; if that
+    parser rejects the file, try Turtle once (Turtle saved as .owl is common)."""
+    g = Graph()
+    guessed = fmt or guess_format(str(f)) or "turtle"
+    try:
+        g.parse(f, format=guessed)
+    except Exception as e:  # every rdflib parser plugin raises its own class
+        if fmt is None and guessed != "turtle":
+            try:
+                return _parse(f, "turtle")
+            except LoadError:
+                pass
+        # collapse whitespace: rdflib's BadSyntax (and others) embed literal
+        # newlines, and the message must stay on one stderr line
+        detail = " ".join(str(e).split())
+        raise LoadError(f"{f}: cannot parse as {guessed}: {detail}") from e
+    return g
+
+
+def load_files(paths: Iterable[str | Path], fmt: str | None = None) -> Dataset:
+    files = [Path(p) for p in paths]
+    graphs: dict[str, Graph] = {}
+    merged = Graph()
+    prefixes: dict[str, str] = {}
+    for f in files:
+        if not f.is_file():
+            raise FileNotFoundError(f)
+        g = _parse(f, fmt)
+        graphs[_unique_key(f.stem, graphs)] = g
+        for triple in g:
+            merged.add(triple)
+        for prefix, ns in g.namespaces():
+            prefixes.setdefault(str(ns), prefix)
+    return Dataset(files, graphs, merged, prefixes)

ttl3d/render.py

@@ -0,0 +1,170 @@
+"""Render the node/link model as one self-contained HTML page.
+
+The vendored bundle (3d-force-graph + force-graph + three-spritetext over one
+shared three.js) is inlined, so the page works offline with zero installs and
+never fetches from a CDN. The viewer's CSS and JS live next to this file
+(viewer.css; viewer.js shared by both views plus one renderer file per view)
+and are inlined at render time. Nodes are shaded spheres with optional
+permanent labels, links are colored by the file asserting them (file mode)
+with predicate labels at their midpoints, the legend filters inclusively, and
+a card opens on click with the node's definition, synonyms, literal
+properties, relations and sources.
+"""
+from __future__ import annotations
+
+import html as _html
+import json
+import re
+from collections import Counter
+from pathlib import Path
+
+VENDOR_JS = Path(__file__).parent / "vendor" / "fg-bundle.min.js"
+VIEWER_CSS = Path(__file__).parent / "viewer.css"
+VIEWER_JS = Path(__file__).parent / "viewer.js"          # shared app
+VIEWER_3D_JS = Path(__file__).parent / "viewer-3d.js"    # one renderer file per view, appended after it
+VIEWER_2D_JS = Path(__file__).parent / "viewer-2d.js"
+# saturated-on-white categorical palette
+PALETTE = ["#ca8a04", "#dc2626", "#2563eb", "#7c3aed", "#16a34a", "#0891b2",
+           "#ea580c", "#db2777", "#4d7c0f", "#b45309", "#0f766e", "#111827"]
+UNKNOWN_COLOR = "#9ca3af"
+OTHER_COLOR = "#94a3b8"
+MAX_COLORED_GROUPS = 11   # past len(PALETTE) groups, only the largest keep a colour
+VIEWS = ("3d", "2d")      # the starting view; the page switches between them
+
+
+def group_counts(data: dict) -> dict:
+    """Nodes per group; in file mode a file also counts the links it asserts."""
+    counts = Counter(n["group"] for n in data["nodes"])
+    if data.get("color_by") == "file":
+        counts.update(l["group"] for l in data["links"] if l["group"])
+    return dict(counts)
+
+
+def rank_groups(groups, counts=None) -> tuple[set, list]:
+    """(groups that get their own colour, groups bucketed as "other")."""
+    counts = counts or {}
+    named = [g for g in groups if g != "?"]
+    if len(named) <= len(PALETTE):
+        return set(named), []
+    ranked = sorted(named, key=lambda g: (-counts.get(g, 0), g))
+    return set(ranked[:MAX_COLORED_GROUPS]), ranked[MAX_COLORED_GROUPS:]
+
+
+def assign_colors(groups, counts=None) -> dict:
+    top, rest = rank_groups(groups, counts)
+    colors = {g: PALETTE[i] for i, g in enumerate(sorted(top))}
+    colors.update({g: OTHER_COLOR for g in rest})
+    colors["?"] = UNKNOWN_COLOR
+    return colors
+
+
+def _legend(groups, colors, counts) -> str:
+    esc = lambda s: _html.escape(str(s), quote=True)
+    top, rest = rank_groups(groups, counts)
+    rows = [f'<div class="row grp" data-group="{esc(g)}"><span class="dot" '
+            f'style="background:{colors.get(g, UNKNOWN_COLOR)}"></span>{esc(g)}</div>'
+            for g in groups if g in top or g == "?"]
+    if rest:
+        rows.append(f'<div class="row grp" data-groups="{esc(json.dumps(rest))}"><span class="dot" '
+                    f'style="background:{OTHER_COLOR}"></span>other ({len(rest)} groups)</div>')
+    return "".join(rows)
+
+
+def _bundle() -> str:
+    lib = _read(VENDOR_JS)
+    if "</script" in lib:  # would break the inline embedding
+        raise ValueError("vendored bundle contains a closing script tag")
+    return "\n".join(l for l in lib.splitlines() if not l.startswith("//# sourceMappingURL"))
+
+
+def _read(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+_PLACEHOLDER = re.compile(r"__[A-Z]+__")
+
+
+def script_safe(value) -> str:
+    """JSON that is safe inside a <script> block: every '<', '>' and '&' becomes a
+    JS unicode escape, so no label, title or IRI can open or close a tag or an
+    HTML comment (the HTML5 tokenizer treats "<!--" + "<script" specially)."""
+    return (json.dumps(value).replace("<", "\\u003c").replace(">", "\\u003e")
+            .replace("&", "\\u0026"))
+
+
+def fill(template: str, values: dict[str, str]) -> str:
+    """Substitute every known __KEY__ in one pass. Unknown tokens (the vendor bundle
+    contains __THREE__) are left alone, and substituted text is never rescanned,
+    so data containing a placeholder name cannot be substituted a second time."""
+    return _PLACEHOLDER.sub(lambda m: values.get(m.group(), m.group()), template)
+
+
+def viewer_source() -> str:
+    """The app script with its placeholders intact: the shared viewer followed by one
+    renderer file per view. The renderer files hold function declarations only, so the
+    shared top-level code can call them through hoisting; the page and the JavaScript
+    syntax test both go through here so they never disagree on the order."""
+    return "\n".join(_read(p) for p in (VIEWER_JS, VIEWER_3D_JS, VIEWER_2D_JS))
+
+
+def render_html(data: dict, *, title: str, pinned: bool, labels: dict, view: str = "3d") -> str:
+    if view not in VIEWS:
+        raise ValueError(f"view must be one of {VIEWS}, got {view!r}")
+    esc = lambda s: _html.escape(str(s), quote=True)
+    counts = group_counts(data)
+    colors = assign_colors(data["groups"], counts)
+    legend = _legend(data["groups"], colors, counts)
+    config = {"title": title, "colorBy": data.get("color_by", "file"),
+              "pinned": bool(pinned), "labels": {"node": bool(labels["node"]),
+                                                 "edge": bool(labels["edge"])},
+              "view": view}
+    app = fill(viewer_source(), {"__DATA__": script_safe(data),
+                                 "__COLORS__": script_safe(colors),
+                                 "__CONFIG__": script_safe(config)})
+    return fill(HTML_TEMPLATE, {
+        "__CSS__": _read(VIEWER_CSS), "__LIB__": _bundle(), "__APP__": app,
+        "__LEGEND__": legend, "__TITLE__": esc(title), "__COLORBY__": esc(config["colorBy"]),
+        "__COUNTS__": f'{len(data["nodes"])} nodes / {len(data["links"])} links'})
+
+
+def write_html(html: str, out: Path | str) -> Path:
+    out = Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(html, encoding="utf-8", newline="\n")   # LF on Windows too: same bytes everywhere
+    return out
+
+
+HTML_TEMPLATE = """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>__TITLE__</title>
+<style>
+__CSS__</style>
+</head>
+<body>
+<div id="panel">
+  <h1>__TITLE__</h1>
+  <div class="sub">__COUNTS__ · colored by __COLORBY__</div>
+  __LEGEND__
+  <input id="q" placeholder="search labels…" autocomplete="off">
+  <div class="row views">view
+    <label><input type="radio" name="view" value="3d"> 3D</label>
+    <label><input type="radio" name="view" value="2d"> 2D</label></div>
+  <label class="tog"><input type="checkbox" id="nodelabels"> node labels</label>
+  <label class="tog"><input type="checkbox" id="edgelabels"> edge relation labels</label>
+  <label class="tog"><input type="checkbox" id="physics"> free-float physics
+    <span title="off = pinned stress-minimized layout (Kamada-Kawai); on = live force simulation" style="color:#9ca3af">?</span></label>
+  <button id="clear">clear filters</button>
+  <div id="hint">click legend rows to light a group's nodes, their neighbors, and the edges it asserts ·
+    edges wear the color of the file asserting them when coloring by file ·
+    <span id="nav"></span> · click a node for details</div>
+</div>
+<div id="detail"><button id="close">×</button><div id="detail-body"></div></div>
+<div id="graph"></div>
+<script>__LIB__</script>
+<script>
+__APP__</script>
+</body>
+</html>
+"""