quickdbd-cli 0.1.0__py3-none-any.whl

quickdbd_cli/assets/viewer.js

@@ -0,0 +1,337 @@
+/* qdbd interactive viewer: pan/zoom, search, minimap, focus, collapse, FK hover, export.
+ * In serve mode (data.serve) tables can also be dragged; positions are POSTed to the server. */
+(function () {
+  "use strict";
+  var Q = window.qdbd;
+  var data = JSON.parse(document.getElementById("qdbd-data").textContent);
+  var S = {
+    model: data.model,
+    pos: data.positions,
+    mode: "full",
+    focus: null,
+    view: { x: 0, y: 0, k: 1 },
+    serve: !!data.serve,
+  };
+  var svg = document.getElementById("canvas");
+  var vp = document.getElementById("vp");
+  var zoomval = document.getElementById("zoomval");
+  var byId = {};
+
+  function index() {
+    byId = {};
+    S.model.tables.forEach(function (t) { byId[t.id] = t; });
+  }
+
+  /* ------------------------------------------------------------- render */
+  function render() {
+    vp.innerHTML = Q.renderInner(S.model, S.pos, S.mode);
+    applyFocus();
+    drawMinimap();
+  }
+
+  function renderEdges() {
+    var g = vp.querySelector(".edges");
+    if (g) g.innerHTML = Q.renderEdges(S.model, S.pos, S.mode);
+    applyFocus();
+  }
+
+  function applyView() {
+    var v = S.view;
+    vp.setAttribute("transform", "translate(" + v.x + "," + v.y + ") scale(" + v.k + ")");
+    zoomval.textContent = Math.round(v.k * 100) + "%";
+    drawViewportRect();
+  }
+
+  function stageSize() {
+    var r = svg.getBoundingClientRect();
+    return [r.width || 800, r.height || 600];
+  }
+
+  function fit() {
+    var b = Q.bounds(S.model, S.pos, S.mode), sz = stageSize(), pad = 40;
+    var k = Math.min((sz[0] - 2 * pad) / (b[2] - b[0]), (sz[1] - 2 * pad) / (b[3] - b[1]), 1.5);
+    k = Math.max(k, 0.05);
+    S.view = { k: k, x: (sz[0] - (b[2] - b[0]) * k) / 2 - b[0] * k, y: (sz[1] - (b[3] - b[1]) * k) / 2 - b[1] * k };
+    applyView();
+  }
+
+  function zoomAt(factor, cx, cy) {
+    var v = S.view, k = Math.min(4, Math.max(0.03, v.k * factor));
+    S.view = { k: k, x: cx - (cx - v.x) * (k / v.k), y: cy - (cy - v.y) * (k / v.k) };
+    applyView();
+  }
+
+  function centerOn(id) {
+    var t = byId[id], p = S.pos[id];
+    if (!t || !p) return;
+    var g = Q.geometry(S.model, S.mode)[id], sz = stageSize();
+    var k = Math.max(S.view.k, 0.9);
+    S.view = { k: k, x: sz[0] / 2 - (p[0] + g.w / 2) * k, y: sz[1] / 2 - (p[1] + g.h / 2) * k };
+    applyView();
+    var el = vp.querySelector('.t[data-id="' + cssEsc(id) + '"]');
+    if (el) {
+      el.classList.add("flash");
+      setTimeout(function () { el.classList.remove("flash"); }, 1200);
+    }
+  }
+
+  function cssEsc(s) { return window.CSS && CSS.escape ? CSS.escape(s) : s.replace(/"/g, '\\"'); }
+
+  /* ------------------------------------------------------------- focus + hover */
+  function neighbours(id) {
+    var set = {};
+    set[id] = true;
+    S.model.rels.forEach(function (r) {
+      if (r.a.t === id) set[r.b.t] = true;
+      if (r.b.t === id) set[r.a.t] = true;
+    });
+    return set;
+  }
+
+  function applyFocus() {
+    if (!S.focus || !byId[S.focus]) {
+      S.focus = null;
+      svg.classList.remove("focus");
+      return;
+    }
+    var set = neighbours(S.focus);
+    svg.classList.add("focus");
+    vp.querySelectorAll(".t").forEach(function (el) { el.classList.toggle("dim", !set[el.getAttribute("data-id")]); });
+    vp.querySelectorAll(".e").forEach(function (el) {
+      var a = el.getAttribute("data-a"), b = el.getAttribute("data-b");
+      el.classList.toggle("dim", !(a === S.focus || b === S.focus));
+    });
+  }
+
+  function clearHover() {
+    vp.querySelectorAll(".hl").forEach(function (el) { el.classList.remove("hl"); });
+  }
+
+  vp.addEventListener("mouseover", function (ev) {
+    var row = ev.target.closest && ev.target.closest(".r");
+    clearHover();
+    if (!row) return;
+    var tid = row.closest(".t").getAttribute("data-id"), cid = row.getAttribute("data-c");
+    vp.querySelectorAll(".e").forEach(function (e) {
+      var a = e.getAttribute("data-a"), ac = e.getAttribute("data-ac"), b = e.getAttribute("data-b"), bc = e.getAttribute("data-bc");
+      var other = null;
+      if (a === tid && ac === cid) other = [b, bc];
+      else if (b === tid && bc === cid) other = [a, ac];
+      if (!other) return;
+      e.classList.add("hl");
+      row.classList.add("hl");
+      var t = vp.querySelector('.t[data-id="' + cssEsc(other[0]) + '"] .r[data-c="' + cssEsc(other[1]) + '"]');
+      if (t) t.classList.add("hl");
+    });
+  });
+  vp.addEventListener("mouseleave", clearHover);
+
+  /* ------------------------------------------------------------- pointer: pan, click, drag */
+  var drag = null;
+  svg.addEventListener("pointerdown", function (ev) {
+    if (ev.button !== 0) return;
+    var tEl = ev.target.closest && ev.target.closest(".t");
+    drag = { sx: ev.clientX, sy: ev.clientY, moved: false, table: tEl ? tEl.getAttribute("data-id") : null, el: tEl };
+    if (drag.table && S.serve) {
+      drag.start = S.pos[drag.table].slice();
+    } else {
+      drag.view = { x: S.view.x, y: S.view.y };
+      svg.classList.add("panning");
+    }
+    svg.setPointerCapture(ev.pointerId);
+  });
+  var raf = null;
+  svg.addEventListener("pointermove", function (ev) {
+    if (!drag) return;
+    var dx = ev.clientX - drag.sx, dy = ev.clientY - drag.sy;
+    if (Math.abs(dx) + Math.abs(dy) > 3) drag.moved = true;
+    if (!drag.moved) return;
+    if (drag.start) {
+      var p = [Math.round(drag.start[0] + dx / S.view.k), Math.round(drag.start[1] + dy / S.view.k)];
+      S.pos[drag.table] = p;
+      drag.el.setAttribute("transform", "translate(" + p[0] + "," + p[1] + ")");
+      if (!raf) raf = requestAnimationFrame(function () { raf = null; renderEdges(); });
+    } else if (drag.view) {
+      S.view.x = drag.view.x + dx;
+      S.view.y = drag.view.y + dy;
+      applyView();
+    }
+  });
+  svg.addEventListener("pointerup", function () {
+    if (!drag) return;
+    svg.classList.remove("panning");
+    var d = drag;
+    drag = null;
+    if (!d.moved) {
+      S.focus = d.table && S.focus !== d.table ? d.table : null;
+      applyFocus();
+      return;
+    }
+    if (d.start) {
+      drawMinimap();
+      var name = byId[d.table].name, body = {};
+      body[name] = S.pos[d.table];
+      if (window.qdbdServe) window.qdbdServe.saveLayout(body);
+    }
+  });
+  svg.addEventListener("wheel", function (ev) {
+    ev.preventDefault();
+    var r = svg.getBoundingClientRect();
+    var factor = Math.exp(-ev.deltaY * (ev.ctrlKey ? 0.01 : 0.0015));
+    zoomAt(factor, ev.clientX - r.left, ev.clientY - r.top);
+  }, { passive: false });
+  document.addEventListener("keydown", function (ev) {
+    if (ev.key === "Escape") { S.focus = null; applyFocus(); }
+  });
+
+  /* ------------------------------------------------------------- toolbar */
+  function center() { var s = stageSize(); return [s[0] / 2, s[1] / 2]; }
+  document.getElementById("zin").onclick = function () { var c = center(); zoomAt(1.25, c[0], c[1]); };
+  document.getElementById("zout").onclick = function () { var c = center(); zoomAt(0.8, c[0], c[1]); };
+  document.getElementById("zfit").onclick = fit;
+  document.querySelectorAll("#modes button").forEach(function (b) {
+    b.onclick = function () {
+      S.mode = b.getAttribute("data-mode");
+      document.querySelectorAll("#modes button").forEach(function (o) { o.classList.toggle("on", o === b); });
+      render();
+    };
+  });
+
+  /* ------------------------------------------------------------- search */
+  var input = document.getElementById("q"), results = document.getElementById("results"), sel = 0, hits = [];
+  function search() {
+    var q = input.value.trim().toLowerCase();
+    hits = !q ? [] : S.model.tables.filter(function (t) {
+      return t.name.toLowerCase().indexOf(q) >= 0 || t.aliases.some(function (a) { return a.toLowerCase().indexOf(q) >= 0; });
+    }).slice(0, 50);
+    sel = 0;
+    results.innerHTML = hits.map(function (t, i) {
+      return '<div data-i="' + i + '"' + (i === 0 ? ' class="sel"' : "") + ">" + Q.esc(t.name) +
+        (t.aliases.length ? "<small>as " + Q.esc(t.aliases.join(", ")) + "</small>" : "") + "</div>";
+    }).join("");
+    results.classList.toggle("open", hits.length > 0);
+  }
+  function pick(i) {
+    var t = hits[i];
+    if (!t) return;
+    results.classList.remove("open");
+    input.blur();
+    centerOn(t.id);
+  }
+  input.addEventListener("input", search);
+  input.addEventListener("keydown", function (ev) {
+    if (ev.key === "ArrowDown" || ev.key === "ArrowUp") {
+      sel = Math.max(0, Math.min(hits.length - 1, sel + (ev.key === "ArrowDown" ? 1 : -1)));
+      results.querySelectorAll("div").forEach(function (d, i) { d.classList.toggle("sel", i === sel); });
+      ev.preventDefault();
+    } else if (ev.key === "Enter") pick(sel);
+    else if (ev.key === "Escape") { input.value = ""; search(); input.blur(); }
+  });
+  results.addEventListener("mousedown", function (ev) {
+    var d = ev.target.closest("div[data-i]");
+    if (d) pick(+d.getAttribute("data-i"));
+  });
+  document.addEventListener("keydown", function (ev) {
+    if ((ev.key === "/" || (ev.key === "f" && (ev.metaKey || ev.ctrlKey))) && document.activeElement.tagName !== "TEXTAREA" &&
+        !(document.activeElement.closest && document.activeElement.closest(".CodeMirror"))) {
+      ev.preventDefault();
+      input.focus();
+    }
+  });
+
+  /* ------------------------------------------------------------- minimap */
+  var mini = document.getElementById("mini"), miniB = null;
+  function drawMinimap() {
+    miniB = Q.bounds(S.model, S.pos, S.mode);
+    var pad = 40, b = miniB;
+    mini.setAttribute("viewBox", (b[0] - pad) + " " + (b[1] - pad) + " " + (b[2] - b[0] + 2 * pad) + " " + (b[3] - b[1] + 2 * pad));
+    var geo = Q.geometry(S.model, S.mode), parts = [];
+    S.model.tables.forEach(function (t) {
+      var p = S.pos[t.id];
+      if (p) parts.push('<rect x="' + p[0] + '" y="' + p[1] + '" width="' + geo[t.id].w + '" height="' + geo[t.id].h + '" fill="#2b5797" opacity=".55"/>');
+    });
+    parts.push('<rect class="vpr" id="vpr"/>');
+    mini.innerHTML = parts.join("");
+    drawViewportRect();
+  }
+  function drawViewportRect() {
+    var r = document.getElementById("vpr");
+    if (!r) return;
+    var sz = stageSize(), v = S.view;
+    r.setAttribute("x", -v.x / v.k);
+    r.setAttribute("y", -v.y / v.k);
+    r.setAttribute("width", sz[0] / v.k);
+    r.setAttribute("height", sz[1] / v.k);
+  }
+  function miniPan(ev) {
+    var pt = mini.createSVGPoint();
+    pt.x = ev.clientX;
+    pt.y = ev.clientY;
+    var m = pt.matrixTransform(mini.getScreenCTM().inverse()), sz = stageSize();
+    S.view.x = sz[0] / 2 - m.x * S.view.k;
+    S.view.y = sz[1] / 2 - m.y * S.view.k;
+    applyView();
+  }
+  var miniDrag = false;
+  mini.addEventListener("pointerdown", function (ev) { miniDrag = true; mini.setPointerCapture(ev.pointerId); miniPan(ev); });
+  mini.addEventListener("pointermove", function (ev) { if (miniDrag) miniPan(ev); });
+  mini.addEventListener("pointerup", function () { miniDrag = false; });
+
+  /* ------------------------------------------------------------- export */
+  function download(name, blob) {
+    var a = document.createElement("a");
+    a.href = URL.createObjectURL(blob);
+    a.download = name;
+    document.body.appendChild(a);
+    a.click();
+    setTimeout(function () { URL.revokeObjectURL(a.href); a.remove(); }, 1000);
+  }
+  function exportSvg() {
+    var only = S.focus ? Object.keys(neighbours(S.focus)) : null;
+    return Q.renderSvg(S.model, S.pos, { mode: S.mode, only: only, fontCss: data.fontCss });
+  }
+  document.getElementById("xsvg").onclick = function () {
+    download((data.title || "diagram") + ".svg", new Blob([exportSvg()], { type: "image/svg+xml" }));
+  };
+  document.getElementById("xpng").onclick = function () {
+    var text = exportSvg();
+    var m = /width="([\d.]+)" height="([\d.]+)"/.exec(text);
+    var w = +m[1], h = +m[2], scale = Math.min(2, 16000 / Math.max(w, h));
+    var img = new Image();
+    img.onload = function () {
+      var c = document.createElement("canvas");
+      c.width = Math.round(w * scale);
+      c.height = Math.round(h * scale);
+      var ctx = c.getContext("2d");
+      ctx.scale(scale, scale);
+      ctx.drawImage(img, 0, 0, w, h);
+      c.toBlob(function (b) { download((data.title || "diagram") + ".png", b); }, "image/png");
+    };
+    img.src = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(text);
+  };
+
+  /* ------------------------------------------------------------- public API (serve mode) */
+  window.qdbdViewer = {
+    setData: function (model, positions) {
+      S.model = model;
+      S.pos = positions;
+      index();
+      render();
+      applyView();
+    },
+    state: S,
+  };
+
+  index();
+  if (S.serve) document.body.classList.add("serve");
+  render();
+  if (S.model.zoom) {
+    var k = S.model.zoom / 100, p = S.model.position || [0, 0];
+    S.view = { k: k, x: -p[0] * k, y: -p[1] * k };
+    applyView();
+    if (!S.model.position) fit();
+  } else {
+    fit();
+  }
+  window.addEventListener("resize", drawViewportRect);
+})();

quickdbd_cli/cli.py

@@ -0,0 +1,169 @@
+"""`qdbd` command line."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .model import Schema
+from .project import Project
+
+OK = "No errors found. Good job!"
+
+
+def _print_diagnostics(schema: Schema, strict: bool) -> bool:
+    """Print diagnostics; returns True when the schema is usable."""
+    for d in schema.diagnostics:
+        print(d.format(), file=sys.stderr)
+    failed = bool(schema.errors) or (strict and bool(schema.warnings))
+    if failed:
+        n_e, n_w = len(schema.errors), len(schema.warnings)
+        print(f"{n_e} error(s), {n_w} warning(s)", file=sys.stderr)
+    return not failed
+
+
+def _open(args) -> Project:
+    return Project.open([Path(p) for p in args.paths], Path(args.layout) if getattr(args, "layout", None) else None)
+
+
+def _title(project: Project) -> str:
+    if len(project.inputs) == 1:
+        p = project.inputs[0]
+        return p.stem if p.is_file() else (p.resolve().name or "diagram")
+    return "diagram"
+
+
+def cmd_check(args) -> int:
+    project = _open(args)
+    schema = project.compile()
+    ok = _print_diagnostics(schema, args.strict)
+    if ok and not schema.diagnostics:
+        print(OK)
+    elif ok:
+        print(f"No errors found ({len(schema.warnings)} warning(s)).")
+    return 0 if ok else 1
+
+
+def cmd_build(args) -> int:
+    from .html import render_page
+
+    project = _open(args)
+    schema = project.compile()
+    if not _print_diagnostics(schema, args.strict):
+        return 1
+    model, pos = project.build(schema)
+    out = Path(args.output)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(render_page(model, pos, _title(project)), encoding="utf-8")
+    print(f"Wrote {out} ({len(model['tables'])} tables, {len(model['rels'])} relationships)")
+    return 0
+
+
+def cmd_export(args) -> int:
+    from . import export
+
+    project = _open(args)
+    schema = project.compile()
+    if not _print_diagnostics(schema, args.strict):
+        return 1
+    model, pos = project.build(schema)
+    only = None
+    if args.focus:
+        t = export.find_table(model, args.focus)
+        if t is None:
+            print(f"error: table '{args.focus}' not found", file=sys.stderr)
+            return 1
+        only = export.focus_ids(model, t["id"], args.depth)
+        pos = export.focus_positions(model, pos, only)
+    out = Path(args.output)
+    fmt = out.suffix.lower().lstrip(".")
+    if fmt not in ("svg", "png"):
+        print("error: output must end in .svg or .png", file=sys.stderr)
+        return 2
+    svg = export.render_svg(model, pos, only=only, mode=args.mode, embed_font=(fmt == "svg"))
+    out.parent.mkdir(parents=True, exist_ok=True)
+    if fmt == "svg":
+        out.write_text(svg, encoding="utf-8")
+    else:
+        out.write_bytes(export.svg_to_png(svg, args.scale))
+    print(f"Wrote {out} ({len(only) if only else len(model['tables'])} tables)")
+    return 0
+
+
+def cmd_layout(args) -> int:
+    project = _open(args)
+    schema = project.compile()
+    if not _print_diagnostics(schema, False):
+        return 1
+    model, pos = project.build(schema, reset=args.reset)
+    project.save_positions(model, pos)
+    print(f"Wrote {project.sidecar} ({len(pos)} tables)")
+    return 0
+
+
+def cmd_serve(args) -> int:
+    from .serve import serve
+
+    project = _open(args)
+    return serve(project, port=args.port, open_browser=not args.no_open)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="qdbd", description="Compile QuickDBD schema files into interactive ER diagrams.")
+    p.add_argument("--version", action="version", version=f"qdbd {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def paths(sp):
+        sp.add_argument("paths", nargs="+", metavar="PATH", help="schema .txt file(s) or folder(s) (recursive)")
+
+    sp = sub.add_parser("check", help="validate schema files")
+    paths(sp)
+    sp.add_argument("--strict", action="store_true", help="treat warnings (QuickDBD incompatibilities) as errors")
+    sp.set_defaults(func=cmd_check)
+
+    sp = sub.add_parser("build", help="write an interactive HTML diagram")
+    paths(sp)
+    sp.add_argument("-o", "--output", default="diagram.html")
+    sp.add_argument("--layout", help="layout sidecar file (default: next to the schema)")
+    sp.add_argument("--strict", action="store_true")
+    sp.set_defaults(func=cmd_build)
+
+    sp = sub.add_parser("export", help="write a PNG or SVG image")
+    paths(sp)
+    sp.add_argument("-o", "--output", required=True, help="out.png or out.svg")
+    sp.add_argument("--focus", metavar="TABLE", help="only this table and its neighbours")
+    sp.add_argument("--depth", type=int, default=1, help="relationship hops around --focus (default 1)")
+    sp.add_argument("--mode", choices=["full", "keys", "header"], default="full", help="collapse mode")
+    sp.add_argument("--scale", type=float, default=2.0, help="PNG pixel scale (default 2)")
+    sp.add_argument("--layout")
+    sp.add_argument("--strict", action="store_true")
+    sp.set_defaults(func=cmd_export)
+
+    sp = sub.add_parser("layout", help="write table positions to the layout sidecar")
+    paths(sp)
+    sp.add_argument("--reset", action="store_true", help="discard saved positions and auto-layout everything")
+    sp.add_argument("--layout")
+    sp.set_defaults(func=cmd_layout)
+
+    sp = sub.add_parser("serve", help="live editor: reload on save, drag tables to arrange")
+    paths(sp)
+    sp.add_argument("--port", type=int, default=8765)
+    sp.add_argument("--layout")
+    sp.add_argument("--no-open", action="store_true", help="don't open a browser")
+    sp.set_defaults(func=cmd_serve)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

quickdbd_cli/export.py

@@ -0,0 +1,79 @@
+"""Static SVG / PNG export via render.js (in V8) and resvg."""
+
+from __future__ import annotations
+
+import base64
+from functools import cache
+from importlib import resources
+
+from . import layout
+from .jsrt import runtime
+
+
+def _asset_bytes(name: str) -> bytes:
+    return resources.files("quickdbd_cli").joinpath(f"assets/{name}").read_bytes()
+
+
+@cache
+def font_css() -> str:
+    out = []
+    for weight, name in (("normal", "Inter-Regular.woff2"), ("bold", "Inter-Bold.woff2")):
+        b64 = base64.b64encode(_asset_bytes(name)).decode("ascii")
+        out.append(
+            f"@font-face{{font-family:Inter;font-weight:{weight};"
+            f"src:url(data:font/woff2;base64,{b64}) format('woff2');}}"
+        )
+    return "".join(out)
+
+
+def find_table(model: dict, name: str) -> dict | None:
+    for key in ("name", "id"):
+        for t in model["tables"]:
+            if t[key] == name:
+                return t
+    low = name.lower()
+    for t in model["tables"]:
+        if t["name"].lower() == low or low in (a.lower() for a in t["aliases"]):
+            return t
+    return None
+
+
+def focus_ids(model: dict, table_id: str, depth: int) -> list[str]:
+    rt = runtime()
+    rt.load("render.js")
+    return rt.call("qdbdNeighbourhood", model, table_id, depth)
+
+
+def render_svg(
+    model: dict, positions: dict, only: list[str] | None = None, mode: str = "full", embed_font: bool = True
+) -> str:
+    rt = runtime()
+    rt.load("render.js")
+    opts = {"mode": mode, "only": only}
+    if embed_font:
+        opts["fontCss"] = font_css()
+    return rt.call("qdbdRenderSvg", model, positions, opts)
+
+
+def focus_positions(model: dict, positions: dict, ids: list[str]) -> dict:
+    """Fresh compact ELK layout for a focus subset, so the image isn't mostly empty space."""
+    keep = set(ids)
+    tables = [t for t in model["tables"] if t["id"] in keep]
+    rels = [r for r in model["rels"] if r["a"]["t"] in keep and r["b"]["t"] in keep]
+    pos = layout.elk_layout(tables, rels)
+    return {k: [v[0], v[1]] for k, v in pos.items()}
+
+
+def svg_to_png(svg: str, scale: float = 2.0) -> bytes:
+    import resvg_py
+
+    fonts_dir = resources.files("quickdbd_cli").joinpath("assets")
+    font_files = [str(fonts_dir.joinpath(n)) for n in ("Inter-Regular.ttf", "Inter-Bold.ttf")]
+    data = resvg_py.svg_to_bytes(
+        svg_string=svg,
+        font_files=font_files,
+        skip_system_fonts=True,
+        sans_serif_family="Inter",
+        zoom=scale,
+    )
+    return bytes(data)

quickdbd_cli/html.py

@@ -0,0 +1,97 @@
+"""Self-contained HTML page: model + positions + renderer + viewer, all inline."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+
+from .export import font_css
+
+CODEMIRROR = "https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16"
+
+
+def _asset(name: str) -> str:
+    return resources.files("quickdbd_cli").joinpath(f"assets/{name}").read_text(encoding="utf-8")
+
+
+def _json_for_script(obj) -> str:
+    # Safe inside <script type="application/json">: no "</" sequences.
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).replace("</", "<\\/")
+
+
+def _escape(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;")
+
+
+BODY = """
+<div id="app">
+  {side}
+  <div id="stage">
+    <svg id="canvas" xmlns="http://www.w3.org/2000/svg"><g id="vp"></g></svg>
+    <div class="search">
+      <input id="q" type="search" placeholder="Search {count} tables  ( / )" autocomplete="off" spellcheck="false">
+      <div id="results" class="results"></div>
+    </div>
+    <div class="bar">
+      <div class="seg" id="modes" title="Collapse tables">
+        <button data-mode="full" class="on">Full</button>
+        <button data-mode="keys">Keys</button>
+        <button data-mode="header">Names</button>
+      </div>
+      <div class="sep"></div>
+      <button id="xsvg" title="Export SVG">SVG</button>
+      <button id="xpng" title="Export PNG">PNG</button>
+      <div class="sep"></div>
+      <button id="zout" title="Zoom out">&#8722;</button>
+      <span class="zoomval" id="zoomval">100%</span>
+      <button id="zin" title="Zoom in">+</button>
+      <button id="zfit" title="Fit to screen">&#9678;</button>
+    </div>
+    <div class="minimap">
+      <svg id="mini" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid meet"></svg>
+    </div>
+    <div class="hint">{hint}</div>
+  </div>
+</div>
+"""
+
+SIDE = """
+<div id="side">
+  <div class="tabs" id="tabs"></div>
+  <div class="banner" id="banner">File changed on disk while you have unsaved edits.
+    <button id="keepmine">Keep mine</button><button id="reload">Reload from disk</button></div>
+  <div id="editor"></div>
+  <div id="problems"></div>
+</div>
+"""
+
+
+def render_page(model: dict, positions: dict, title: str, serve: bool = False) -> str:
+    data = {"model": model, "positions": positions, "serve": serve, "title": title, "fontCss": font_css()}
+    hint = (
+        "Drag tables to move them (saved). Click a table to focus. Esc clears."
+        if serve
+        else "Click a table to focus its relationships. Esc clears. Scroll to zoom, drag to pan."
+    )
+    body = BODY.format(side=SIDE if serve else "", count=len(model["tables"]), hint=hint)
+    head_extra = ""
+    scripts = ""
+    if serve:
+        head_extra = f'<link rel="stylesheet" href="{CODEMIRROR}/codemirror.min.css">'
+        scripts = (
+            f'<script src="{CODEMIRROR}/codemirror.min.js"></script>'
+            f'<script src="{CODEMIRROR}/addon/mode/simple.min.js"></script>'
+            f"<script>{_asset('editor.js')}</script>"
+        )
+    return (
+        '<!doctype html>\n<html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        '<meta name="generator" content="qdbd">'
+        f"<title>{_escape(title)}</title>"
+        f"<style>{font_css()}{_asset('style.css')}</style>{head_extra}</head><body>"
+        f"{body}"
+        f'<script type="application/json" id="qdbd-data">{_json_for_script(data)}</script>'
+        f"<script>{_asset('render.js')}</script>"
+        f"<script>{_asset('viewer.js')}</script>"
+        f"{scripts}</body></html>\n"
+    )