predictygraph 0.1.0__tar.gz

predictygraph-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.1
+Name: predictygraph
+Version: 0.1.0
+Summary: Predictable graphs: a readable, CSS-styled diagram DSL with per-group layouts, rendered to SVG/APNG
+Author-Email: Reza Jelveh <git@jelveh.me>
+License: GPL-3.0-or-later
+Requires-Python: >=3.11
+Requires-Dist: tinycss2>=1.5.1
+Requires-Dist: typer>=0.26.8
+Requires-Dist: pillow>=11.0.0
+Provides-Extra: apng
+Requires-Dist: cairosvg>=2.7; extra == "apng"
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: 2026 The predictygraph Authors
+
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+# predictygraph
+
+**Predictable graphs.** A readable diagram DSL with per-group layouts ("balancing styles"),
+plain-CSS styling, and static or animated SVG/APNG output (no browser).
+Spec: [docs/SPEC.md](docs/SPEC.md). Docs: [predictygraph.github.io](https://predictygraph.github.io/).
+Editor support: [tree-sitter-pdg](https://github.com/predictygraph/tree-sitter-pdg).
+Rendered examples and the gallery: [predictygraph.github.io](https://predictygraph.github.io/). This repo keeps
+only `.pdg` sources; images live in the docs repo (git-lfs).
+
+```bash
+uv run pdg examples/hami_flow.pdg                    # -> examples/hami_flow.svg (not committed)
+uv run pdg diagram.pdg --css theme.css -o out.svg
+uv run pdg diagram.pdg -o out.png                    # animated PNG (APNG)
+uv run pdg diagram.pdg --check                       # validate only
+uv run pdg diagram.pdg --target web                  # size labels to fit any browser font
+```
+
+`pdg` is the short alias of the `predictygraph` command.
+
+## Credits
+
+This project stands on the shoulders of two giants.
+
+**[Graphviz](https://graphviz.org/) (dot)** taught a generation that diagrams can be
+text. Its layered layout algorithm is still the reference for graph drawing, and
+we are grateful for decades of work on it. But dot optimises for the whole graph
+at once: you describe nodes and edges, and the engine decides where they go.
+Nudging one cluster without disturbing the rest means fighting `rank`, `weight`
+and invisible edges. Styling lives in attributes rather than CSS, and the output
+often looks like a paper figure rather than a slide.
+
+**[Mermaid](https://mermaid.js.org/)** made text diagrams mainstream by putting
+them in Markdown, READMEs and docs sites. Its syntax is friendly and we borrowed
+from its spirit. But it renders through a browser and JavaScript, leaves little
+control over layout, and the same source can render differently across versions
+and hosts.
+
+predictygraph keeps what we love from both (diagrams as readable text) and adds what we
+missed: per-group layouts, plain-CSS styling, and deterministic static SVG with no
+browser in the loop.

predictygraph-0.1.0/README.md

@@ -0,0 +1,46 @@
+<!--
+SPDX-FileCopyrightText: 2026 The predictygraph Authors
+
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+# predictygraph
+
+**Predictable graphs.** A readable diagram DSL with per-group layouts ("balancing styles"),
+plain-CSS styling, and static or animated SVG/APNG output (no browser).
+Spec: [docs/SPEC.md](docs/SPEC.md). Docs: [predictygraph.github.io](https://predictygraph.github.io/).
+Editor support: [tree-sitter-pdg](https://github.com/predictygraph/tree-sitter-pdg).
+Rendered examples and the gallery: [predictygraph.github.io](https://predictygraph.github.io/). This repo keeps
+only `.pdg` sources; images live in the docs repo (git-lfs).
+
+```bash
+uv run pdg examples/hami_flow.pdg                    # -> examples/hami_flow.svg (not committed)
+uv run pdg diagram.pdg --css theme.css -o out.svg
+uv run pdg diagram.pdg -o out.png                    # animated PNG (APNG)
+uv run pdg diagram.pdg --check                       # validate only
+uv run pdg diagram.pdg --target web                  # size labels to fit any browser font
+```
+
+`pdg` is the short alias of the `predictygraph` command.
+
+## Credits
+
+This project stands on the shoulders of two giants.
+
+**[Graphviz](https://graphviz.org/) (dot)** taught a generation that diagrams can be
+text. Its layered layout algorithm is still the reference for graph drawing, and
+we are grateful for decades of work on it. But dot optimises for the whole graph
+at once: you describe nodes and edges, and the engine decides where they go.
+Nudging one cluster without disturbing the rest means fighting `rank`, `weight`
+and invisible edges. Styling lives in attributes rather than CSS, and the output
+often looks like a paper figure rather than a slide.
+
+**[Mermaid](https://mermaid.js.org/)** made text diagrams mainstream by putting
+them in Markdown, READMEs and docs sites. Its syntax is friendly and we borrowed
+from its spirit. But it renders through a browser and JavaScript, leaves little
+control over layout, and the same source can render differently across versions
+and hosts.
+
+predictygraph keeps what we love from both (diagrams as readable text) and adds what we
+missed: per-group layouts, plain-CSS styling, and deterministic static SVG with no
+browser in the loop.

predictygraph-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "predictygraph"
+dynamic = []
+description = "Predictable graphs: a readable, CSS-styled diagram DSL with per-group layouts, rendered to SVG/APNG"
+authors = [
+    { name = "Reza Jelveh", email = "git@jelveh.me" },
+]
+dependencies = [
+    "tinycss2>=1.5.1",
+    "typer>=0.26.8",
+    "pillow>=11.0.0",
+]
+requires-python = ">=3.11"
+readme = "README.md"
+version = "0.1.0"
+
+[project.license]
+text = "GPL-3.0-or-later"
+
+[project.optional-dependencies]
+apng = [
+    "cairosvg>=2.7",
+]
+
+[project.scripts]
+predictygraph = "predictygraph.cli:app"
+pdg = "predictygraph.cli:app"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm.version]
+source = "scm"
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

predictygraph-0.1.0/src/predictygraph/__init__.py

@@ -0,0 +1,108 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Predictygraph: readable diagram DSL -> Scene IR -> SVG / APNG.
+
+Pipeline (mirrors slidr):
+
+    text --parse--> AST (model.Document)
+         --style--> styled AST            (CSS, theme, @target blocks)
+         --layout + route (iterated until channels fit)--> laid-out AST
+         --build--> Scene IR (ir.Scene)
+         --writers--> render/svg.py, render/apng.py
+
+Labels are measured with the fonts of the render *target* (see fonts.py): the platform
+or viewer the SVG is made for. Showing it somewhere else can make labels overflow.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .fonts import TARGETS, FontWarning
+from .ir import Scene
+from .layout import layout
+from .parser import PdgSyntaxError, parse, parse_file
+from .render import write_apng, write_svg
+from .route import Router
+from .scene import SceneBuilder
+from .style import apply_styles
+from .text import use_target
+from .theme import ThemeError, list_themes, theme_css
+
+__all__ = ["render", "render_file", "build_scene", "scene_from_file", "parse", "parse_file",
+           "write_svg", "write_apng", "Scene", "PdgSyntaxError", "ThemeError", "FontWarning",
+           "TARGETS", "list_themes"]
+
+MAX_PASSES = 4
+
+
+def resolve_target(doc, target: str | None) -> str | None:
+    """Explicit target wins over `graph target=`; None means measure with this machine's fonts."""
+    name = target or doc.root.attrs.get("target")
+    if name and name not in TARGETS:
+        raise ValueError(f"unknown target {name!r} (choose from: {', '.join(TARGETS)})")
+    return None if name in (None, "host") else name
+
+
+def _style(doc, extra_css, theme, target):
+    name = theme or doc.root.attrs.get("theme")
+    if name:
+        doc.stylesheets.insert(0, (theme_css(name, doc.base_dir), doc.base_dir))
+    for css in extra_css or []:
+        doc.stylesheets.append((css, doc.base_dir))
+    apply_styles(doc, target)
+    return doc
+
+
+def _layout_and_route(doc) -> Router:
+    """Lay out, route; if a channel between two ranks is too narrow for its lanes,
+    widen exactly that gap and lay out again."""
+    router = None
+    for _ in range(MAX_PASSES):
+        layout(doc)
+        router = Router(doc).route()
+        if not router.needs:
+            break
+        for (gid, rank), need in router.needs.items():
+            g = doc.root if gid == doc.root.id else doc.items[gid]
+            extra = getattr(g, "extra_gap", {})
+            extra[rank] = extra.get(rank, 0.0) + need
+            g.extra_gap = extra
+    return router
+
+
+def build_scene(doc, extra_css: list[str] | None = None, theme: str | None = None,
+                target: str | None = None) -> Scene:
+    """Style, then iterate layout -> route -> scene until edges clear the group titles
+    (a crossed title that cannot slide asks for a wider group)."""
+    target = resolve_target(doc, target)
+    with use_target(target):
+        _style(doc, extra_css, theme, target)
+        scene = None
+        for _ in range(MAX_PASSES):
+            router = _layout_and_route(doc)
+            builder = SceneBuilder(doc, router)
+            scene = builder.build()
+            if not builder.title_needs:
+                break
+            for gid, need in builder.title_needs.items():
+                g = doc.items[gid]
+                g.extra_w = getattr(g, "extra_w", 0.0) + need
+    return scene
+
+
+def scene_from_file(path: str | Path, extra_css: list[str] | None = None, theme: str | None = None,
+                    allow_outside: bool = False, target: str | None = None) -> Scene:
+    return build_scene(parse_file(path, allow_outside), extra_css, theme, target)
+
+
+def render(text: str, base_dir: str = ".", extra_css: list[str] | None = None, theme: str | None = None,
+           t: float | None = None, allow_outside: bool = False, target: str | None = None) -> str:
+    """SVG text. t=None: animated (SMIL) SVG; t=seconds: static frame at that time."""
+    return write_svg(build_scene(parse(text, base_dir, allow_outside), extra_css, theme, target), t)
+
+
+def render_file(path: str | Path, extra_css: list[str] | None = None, theme: str | None = None,
+                t: float | None = None, allow_outside: bool = False, target: str | None = None) -> str:
+    return write_svg(scene_from_file(path, extra_css, theme, allow_outside, target), t)

predictygraph-0.1.0/src/predictygraph/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from .cli import app
+
+app()

predictygraph-0.1.0/src/predictygraph/anim.py

@@ -0,0 +1,91 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Animation tracks: format-independent keyframe descriptions.
+
+Every animated property is a looping linear keyframe track ``(attr, values, dur)``
+attached to a Scene IR element. The first keyframe always equals the static value, so
+writers that cannot animate (PDF, PNG, ODP) just use it. Writers that can animate
+(SVG via SMIL) emit the track; frame writers (APNG) sample it with ``Track.at(t)``.
+"""
+from __future__ import annotations
+
+import math
+import re
+
+from .safe import NUM, numbers
+
+FLOW_MODES = ("forward", "reverse", "both", "auto")
+BORDER_MODES = ("march", "pulse", "glow")
+
+
+def seconds(v, default: float = 1.0) -> float:
+    if v is None:
+        return default
+    m = re.match(rf"\s*({NUM})\s*(ms|s)?\s*$", str(v))
+    if not m:
+        return default
+    n = float(m.group(1))
+    n = n / 1000 if m.group(2) == "ms" else n
+    return min(3600.0, max(0.05, n)) if n == n else default
+
+
+def dash_len(dash: str) -> float:
+    nums = [abs(x) for x in numbers(dash)]
+    if not nums:
+        return 0.0
+    if len(nums) % 2:
+        nums = nums * 2  # SVG repeats odd-length dash lists
+    return sum(nums)
+
+
+class Track:
+    """A looping linear keyframe track over evenly spaced keyframes."""
+
+    def __init__(self, attr: str, values: list[float], dur: float):
+        if not values:
+            raise ValueError("track needs at least one value")
+        values = values if len(values) > 1 else values * 2
+        dur = dur if dur > 0 else 1.0
+        self.attr, self.values, self.dur = attr, values, dur
+
+    def at(self, t: float) -> float:
+        vs = self.values
+        ph = (t % self.dur) / self.dur * (len(vs) - 1)
+        i = min(int(ph), len(vs) - 2)
+        f = ph - i
+        return vs[i] + (vs[i + 1] - vs[i]) * f
+
+    def shifted(self, delta: float) -> "Track":
+        return Track(self.attr, [v + delta for v in self.values], self.dur)
+
+
+def flow_tracks(dash: str, dur: float, reverse: bool) -> list[Track]:
+    L = dash_len(dash) or 10.0
+    # offset L -> 0 moves the dash pattern towards the path's end
+    return [Track("stroke-dashoffset", [0.0, L] if reverse else [L, 0.0], dur)]
+
+
+def border_tracks(mode: str, sw: float, dash: str | None, dur: float) -> list[Track]:
+    if mode == "march":
+        return [Track("stroke-dashoffset", [dash_len(dash) or 10.0, 0.0], dur)]
+    if mode == "pulse":
+        return [Track("stroke-opacity", [1.0, 0.35, 1.0], dur),
+                Track("stroke-width", [sw, sw * 2.2, sw], dur)]
+    if mode == "glow":  # applied to a halo copy behind the shape
+        return [Track("stroke-width", [sw, sw + 10, sw + 10], dur),
+                Track("stroke-opacity", [0.7, 0.0, 0.0], dur)]
+    return []
+
+
+def loop_length(durations: list[float], cap: float = 12.0) -> float:
+    """Shortest time after which every track is back at its start (LCM on a 10 ms grid)."""
+    if not durations:
+        return 1.0
+    l = 1
+    for d in durations:
+        c = max(1, round(d * 100))
+        l = l * c // math.gcd(l, c)
+    lcm = l / 100
+    return lcm if lcm <= cap else min(max(durations), cap)

predictygraph-0.1.0/src/predictygraph/cli.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""predictygraph CLI: .pdg -> Scene IR -> .svg (animated or static) or .png (APNG)."""
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+
+import typer
+
+from . import FontWarning, list_themes, scene_from_file, write_apng, write_svg
+
+app = typer.Typer(add_completion=False, help="Render Predictygraph diagrams to SVG or APNG.")
+
+
+@app.command()
+def main(
+    src: Path = typer.Argument(None, help="Input .pdg file"),
+    out: Path | None = typer.Option(None, "-o", "--out", help="Output .svg or .png (default: <src>.svg)"),
+    css: list[Path] = typer.Option([], "--css", help="Extra stylesheet(s), applied after the file's own"),
+    theme: str | None = typer.Option(None, "--theme", help="Theme name or .toml path (overrides graph theme=)"),
+    target: str | None = typer.Option(None, "--target",
+                                      help="Where the SVG will be shown: web, linux, macos, windows or host "
+                                           "(overrides graph target=). Labels are measured with that "
+                                           "platform's fonts"),
+    themes: bool = typer.Option(False, "--list-themes", help="List bundled themes and exit"),
+    check: bool = typer.Option(False, "--check", help="Parse, lay out and route only; report errors"),
+    static: bool = typer.Option(False, "--static", help="SVG without animation (first frame)"),
+    at: float | None = typer.Option(None, "--at", help="SVG frozen at this time (seconds)"),
+    fps: int = typer.Option(20, "--fps", help="APNG frames per second"),
+    seconds: float | None = typer.Option(None, "--seconds", help="APNG length (default: one full loop)"),
+    scale: float = typer.Option(2.0, "--scale", help="APNG pixel scale"),
+    allow_outside: bool = typer.Option(False, "--allow-outside",
+                                       help="Let image= and css \"...\" read files outside the input's directory"),
+) -> None:
+    if themes:
+        typer.echo("\n".join(list_themes()))
+        return
+    if src is None or not src.exists():
+        typer.echo("missing input file", err=True)
+        raise typer.Exit(2)
+    dest = out or src.with_suffix(".svg")
+    try:
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always", FontWarning)
+            scene = scene_from_file(src, [p.read_text() for p in css], theme, allow_outside, target)
+        for w in caught:
+            typer.echo(f"{src}: warning: {w.message}", err=True)
+        if check:
+            typer.echo(f"{src}: ok")
+            return
+        if dest.suffix.lower() in (".png", ".apng"):
+            write_apng(scene, dest, fps, scale, seconds)
+        else:
+            t = at if at is not None else (0.0 if static else None)
+            dest.write_text(write_svg(scene, t), encoding="utf-8")
+    except (ValueError, OSError, RuntimeError) as exc:
+        typer.echo(f"{src}: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(str(dest))

predictygraph-0.1.0/src/predictygraph/default.css

@@ -0,0 +1,16 @@
+/*
+ * SPDX-FileCopyrightText: 2026 The predictygraph Authors
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * Base layer. Cascade: default.css < theme < css in the .pdg file < --css.
+ */
+
+graph { font-family: Roboto, Arial, "Helvetica Neue", sans-serif; font-size: 14px; color: #1f2937;
+        fill: none; padding: 16px; }
+node  { fill: #ffffff; stroke: #374151; stroke-width: 1.5; border-radius: 6px;
+        padding: 8px 14px; color: #111827; min-width: 40px; min-height: 28px; }
+group { fill: #f3f4f6; stroke: #9ca3af; stroke-width: 1; border-radius: 10px;
+        padding: 14px; color: #374151; font-size: 12px; font-weight: bold;
+        label-position: top; }
+edge  { stroke: #4b5563; stroke-width: 1.5; color: #374151; font-size: 11px; }

predictygraph-0.1.0/src/predictygraph/fonts.py

@@ -0,0 +1,167 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Pick the font file used to measure a label, for a given render target.
+
+Text is measured to size boxes, but drawn later by whatever displays the SVG. If the two
+use different fonts, labels overflow or leave gaps. A *target* says where the SVG will be
+shown, so we can measure with the font that viewer will actually use:
+
+- ``linux`` / ``macos`` / ``windows``: the first font in the CSS list that this platform ships.
+- ``web``: every font in the list; boxes are sized for the widest, so any choice fits.
+- ``host`` (default when no target is set): whatever this machine resolves via fontconfig.
+
+Bundled metric fonts (no outlines, widths and kerning only) stand in for common fonts,
+including proprietary ones with identical widths (Liberation Sans = Arial/Helvetica,
+Liberation Serif = Times New Roman, Carlito = Calibri).
+"""
+from __future__ import annotations
+
+import functools
+import subprocess
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+
+BUNDLED = Path(__file__).parent / "fonts"
+
+# family (lower case) -> bundled file stem (regular, bold)
+METRIC = {
+    "dejavu sans": ("DejaVuSans", "DejaVuSans-Bold"),
+    "liberation sans": ("LiberationSans-Regular", "LiberationSans-Bold"),
+    "liberation serif": ("LiberationSerif-Regular", "LiberationSerif-Bold"),
+    "liberation mono": ("LiberationMono-Regular", "LiberationMono-Bold"),
+    "carlito": ("Carlito-Regular", "Carlito-Bold"),
+}
+# Proprietary or common fonts with identical advance widths to a bundled one.
+ALIASES = {
+    "arial": "liberation sans", "helvetica": "liberation sans", "helvetica neue": "liberation sans",
+    "arimo": "liberation sans",
+    "times new roman": "liberation serif", "times": "liberation serif", "tinos": "liberation serif",
+    "courier new": "liberation mono", "courier": "liberation mono", "cousine": "liberation mono",
+    "calibri": "carlito",
+    "bitstream vera sans": "dejavu sans", "verdana": "dejavu sans",
+}
+
+# Fonts each platform ships, and what the generic CSS families resolve to there.
+PLATFORMS = {
+    "linux": {
+        "has": {"dejavu sans", "liberation sans", "liberation serif", "liberation mono", "carlito"},
+        "generic": {"sans-serif": "dejavu sans", "serif": "liberation serif", "monospace": "liberation mono",
+                    "system-ui": "dejavu sans"},
+    },
+    "macos": {
+        "has": {"helvetica", "helvetica neue", "arial", "times", "times new roman", "courier", "courier new",
+                "verdana"},
+        "generic": {"sans-serif": "helvetica", "serif": "times", "monospace": "courier",
+                    "system-ui": "helvetica neue"},
+    },
+    "windows": {
+        "has": {"arial", "times new roman", "courier new", "calibri", "verdana"},
+        "generic": {"sans-serif": "arial", "serif": "times new roman", "monospace": "courier new",
+                    "system-ui": "arial"},
+    },
+}
+TARGETS = ("host", "web", *PLATFORMS)
+GENERIC = {"sans-serif", "serif", "monospace", "system-ui", "cursive", "fantasy", "ui-sans-serif"}
+
+
+class FontWarning(UserWarning):
+    """A requested font could not be measured exactly; widths may not match the viewer."""
+
+
+def families(css: str) -> list[str]:
+    """CSS font-family list -> lower-case names, quotes stripped."""
+    out = [f.strip().strip("\"'").strip().lower() for f in (css or "").split(",")]
+    return [f for f in out if f and not f.startswith("-")] or ["sans-serif"]
+
+
+@dataclass(frozen=True)
+class FontChoice:
+    path: str | None      # file to measure with; None = Pillow's built-in default
+    family: str           # the family the viewer is expected to draw with
+    exact: bool           # True if widths are known to match that family
+
+
+def bundled(family: str, bold: bool) -> str | None:
+    key = ALIASES.get(family, family)
+    stems = METRIC.get(key)
+    if not stems:
+        return None
+    p = BUNDLED / f"{stems[1 if bold else 0]}.ttf"
+    return str(p) if p.exists() else None
+
+
+@functools.lru_cache(maxsize=64)
+def fontconfig(family: str, bold: bool) -> tuple[str | None, str | None]:
+    """(file, resolved family) from fc-match, or (None, None) without fontconfig."""
+    pattern = family + (":bold" if bold else "")
+    try:
+        out = subprocess.run(["fc-match", "-f", "%{file}\t%{family[0]}", "--", pattern],
+                             capture_output=True, text=True, timeout=5, check=False).stdout.strip()
+    except (OSError, subprocess.SubprocessError):
+        return None, None
+    path, _, fam = out.partition("\t")
+    return (path or None), (fam.lower() or None)
+
+
+class FontResolver:
+    def __init__(self, target: str = "host"):
+        if target not in TARGETS:
+            raise ValueError(f"unknown target {target!r} (choose from: {', '.join(TARGETS)})")
+        self.target = target
+        self.warned: set[str] = set()
+
+    def warn(self, msg: str) -> None:
+        if msg not in self.warned:
+            self.warned.add(msg)
+            warnings.warn(msg, FontWarning, stacklevel=4)
+
+    def platform(self, name: str, fams: list[str], bold: bool) -> FontChoice:
+        plat = PLATFORMS[name]
+        for fam in fams:
+            fam = plat["generic"].get(fam, fam)
+            if fam in plat["has"]:
+                path = bundled(fam, bold)
+                if path:
+                    return FontChoice(path, fam, True)
+                return self.approximate(fam, bold, f"{name} ships {fam!r}, but predictygraph has no metric copy")
+        return self.approximate(fams[0], bold, f"none of {fams} is available on {name}")
+
+    def approximate(self, fam: str, bold: bool, why: str) -> FontChoice:
+        """Widest bundled sans as a safe stand-in (text then fits, possibly with spare room)."""
+        self.warn(f"font {fam!r}: {why}; measuring with DejaVu Sans, labels may not fit exactly")
+        return FontChoice(bundled("dejavu sans", bold), fam, False)
+
+    def host(self, fams: list[str], bold: bool) -> FontChoice:
+        for fam in fams:
+            if fam in GENERIC:
+                path, got = fontconfig(fam, bold)
+                return FontChoice(path, got or fam, path is not None)
+            path, got = fontconfig(fam, bold)
+            if path and got == fam:
+                return FontChoice(path, fam, True)
+            if (b := bundled(fam, bold)):
+                return FontChoice(b, fam, True)
+        path, got = fontconfig(fams[0], bold)
+        self.warn(f"font {fams[0]!r} is not installed; measuring with {got or 'a default font'} instead. "
+                  f"Set a target (e.g. --target web) or install the font")
+        return FontChoice(path, got or fams[0], False)
+
+    @functools.lru_cache(maxsize=256)
+    def choose(self, css_family: str, bold: bool) -> list[FontChoice]:
+        """Fonts to measure with; the caller takes the widest result."""
+        fams = families(css_family)
+        if self.target == "host":
+            return [self.host(fams, bold)]
+        if self.target in PLATFORMS:
+            return [self.platform(self.target, fams, bold)]
+        # web: any font in the list may be used by some browser; generic families mean "anything"
+        out = [FontChoice(bundled(f, bold), f, True) for f in fams if bundled(f, bold)]
+        unknown = [f for f in fams if not bundled(f, bold) and f not in GENERIC]
+        for f in unknown:
+            self.warn(f"font {f!r} has no metric copy; web target sizes boxes without it")
+        if any(f in GENERIC for f in fams) or not out:
+            out += [FontChoice(bundled(f, bold), f, True) for f in ("dejavu sans", "liberation sans")]
+        return out