quickdbd-cli 0.1.4__tar.gz → 0.1.6__tar.gz

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.6}/.gitignore

@@ -220,3 +220,5 @@ __marimo__/
 .streamlit/secrets.toml
 .venv/
 .superpowers/
+site/
+jaffle-erd/

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.1.4
+Version: 0.1.6
 Summary: Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit.
 Project-URL: Homepage, https://github.com/MarkPhamm/quickdbd-cli
 Author: Minh (Mark) Pham
@@ -21,6 +21,9 @@ Provides-Extra: dev
 Requires-Dist: fonttools>=4.50; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
 Description-Content-Type: text/markdown
 
 # quickdbd-cli (`qdbd`)
@@ -44,7 +47,7 @@ pipx install quickdbd-cli        # or: uvx --from quickdbd-cli qdbd ...
 qdbd build schema.txt -o schema.html
 ```
 
-**Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/
+**Docs:** https://markphamm.github.io/quickdbd-cli/ · **Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/demo/
 
 Not affiliated with QuickDBD. It reads the same text syntax, so schemas move freely between the two.
 
@@ -60,6 +63,8 @@ Not affiliated with QuickDBD. It reads the same text syntax, so schemas move fre
   - hover a column to highlight its relationship
   - hover a dotted-underlined table or column to read its `#` doc comments
   - PNG/SVG export buttons, and **draw.io**: an editable diagrams.net file using draw.io's ER table shapes and crow's-foot arrows
+  - **Path finder:** in a table's detail panel, type another table to see the shortest join path, highlighted on the canvas, with a ready-to-paste SQL `JOIN` (also `qdbd path erd/ --from payments --to customers`)
+  - **Regions:** a shaded, labelled area per file or dbt folder (toolbar toggle). `--by-group` on `build` / `export` / `layout` arranges tables so each folder sits together
   - shareable links: the URL keeps the filter, selected table, collapse mode and zoom; **Link** copies it
 - **Live editing:** `qdbd serve` reloads when you save, has a browser editor pane with autosave, and remembers where you drag tables.
 - **Many files, one diagram:** point it at a folder and foreign keys can cross files.
@@ -78,6 +83,8 @@ qdbd build erd/ -o erd.html
 - **Relationships:** `relationships` tests (including dbt_utils `relationships_where`) and `foreign_key` constraints.
 - **Primary keys:** `primary_key` constraints, or else a column with both `unique` and `not_null` tests.
 - **Docs:** model and column descriptions become doc comments, shown as tooltips.
+- **`--infer-fks`:** also links `customer_id`-style columns to the table they name, when no relationship is declared. Ambiguous matches are skipped, never guessed.
+- **`--check`:** in CI, fails when the committed files are out of date.
 - **Options:**
   - `--select 'marts.*'` narrows by name, fqn or path (repeatable)
   - `--package all` includes installed packages
@@ -129,11 +136,12 @@ The selector `diff:modified` (or `diff:added` / `diff:changed`) works like dbt's
 
 ```bash
 qdbd check  PATH... [--strict]                 # validate; "No errors found. Good job!"
-qdbd build  PATH... -o diagram.html            # shareable interactive HTML (positions locked)
+qdbd build  PATH... -o diagram.html            # shareable interactive HTML
 qdbd serve  PATH... [--port 8765]              # live editor + drag-to-arrange
 qdbd export PATH... -o out.png [--focus Customer --depth 1]   # PNG, SVG or .drawio
 qdbd layout PATH... [--reset]                  # (re)write the layout file
 qdbd import dbt target/manifest.json -o erd/   # generate schema files from a dbt project
+qdbd path PATH... --from A --to B              # shortest join path + SQL JOIN snippet
 ```
 
 `PATH` is a `.txt` file or a folder. Every `*.txt` under a folder is read recursively.
@@ -177,7 +185,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.4
+      - uses: MarkPhamm/quickdbd-cli@v0.1.6
         with:
           path: erd/                 # schema file(s) or folder(s)
           output: site/index.html
@@ -201,7 +209,7 @@ Outputs are `html`, `changed` and `diff-file`.
 ```yaml
 repos:
   - repo: https://github.com/MarkPhamm/quickdbd-cli
-    rev: v0.1.4
+    rev: v0.1.6
     hooks:
       - id: qdbd-check
         files: ^erd/.*\.txt$   # point at your schema files

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.6}/README.md

@@ -19,7 +19,7 @@ pipx install quickdbd-cli        # or: uvx --from quickdbd-cli qdbd ...
 qdbd build schema.txt -o schema.html
 ```
 
-**Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/
+**Docs:** https://markphamm.github.io/quickdbd-cli/ · **Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/demo/
 
 Not affiliated with QuickDBD. It reads the same text syntax, so schemas move freely between the two.
 
@@ -35,6 +35,8 @@ Not affiliated with QuickDBD. It reads the same text syntax, so schemas move fre
   - hover a column to highlight its relationship
   - hover a dotted-underlined table or column to read its `#` doc comments
   - PNG/SVG export buttons, and **draw.io**: an editable diagrams.net file using draw.io's ER table shapes and crow's-foot arrows
+  - **Path finder:** in a table's detail panel, type another table to see the shortest join path, highlighted on the canvas, with a ready-to-paste SQL `JOIN` (also `qdbd path erd/ --from payments --to customers`)
+  - **Regions:** a shaded, labelled area per file or dbt folder (toolbar toggle). `--by-group` on `build` / `export` / `layout` arranges tables so each folder sits together
   - shareable links: the URL keeps the filter, selected table, collapse mode and zoom; **Link** copies it
 - **Live editing:** `qdbd serve` reloads when you save, has a browser editor pane with autosave, and remembers where you drag tables.
 - **Many files, one diagram:** point it at a folder and foreign keys can cross files.
@@ -53,6 +55,8 @@ qdbd build erd/ -o erd.html
 - **Relationships:** `relationships` tests (including dbt_utils `relationships_where`) and `foreign_key` constraints.
 - **Primary keys:** `primary_key` constraints, or else a column with both `unique` and `not_null` tests.
 - **Docs:** model and column descriptions become doc comments, shown as tooltips.
+- **`--infer-fks`:** also links `customer_id`-style columns to the table they name, when no relationship is declared. Ambiguous matches are skipped, never guessed.
+- **`--check`:** in CI, fails when the committed files are out of date.
 - **Options:**
   - `--select 'marts.*'` narrows by name, fqn or path (repeatable)
   - `--package all` includes installed packages
@@ -104,11 +108,12 @@ The selector `diff:modified` (or `diff:added` / `diff:changed`) works like dbt's
 
 ```bash
 qdbd check  PATH... [--strict]                 # validate; "No errors found. Good job!"
-qdbd build  PATH... -o diagram.html            # shareable interactive HTML (positions locked)
+qdbd build  PATH... -o diagram.html            # shareable interactive HTML
 qdbd serve  PATH... [--port 8765]              # live editor + drag-to-arrange
 qdbd export PATH... -o out.png [--focus Customer --depth 1]   # PNG, SVG or .drawio
 qdbd layout PATH... [--reset]                  # (re)write the layout file
 qdbd import dbt target/manifest.json -o erd/   # generate schema files from a dbt project
+qdbd path PATH... --from A --to B              # shortest join path + SQL JOIN snippet
 ```
 
 `PATH` is a `.txt` file or a folder. Every `*.txt` under a folder is read recursively.
@@ -152,7 +157,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.4
+      - uses: MarkPhamm/quickdbd-cli@v0.1.6
         with:
           path: erd/                 # schema file(s) or folder(s)
           output: site/index.html
@@ -176,7 +181,7 @@ Outputs are `html`, `changed` and `diff-file`.
 ```yaml
 repos:
   - repo: https://github.com/MarkPhamm/quickdbd-cli
-    rev: v0.1.4
+    rev: v0.1.6
     hooks:
       - id: qdbd-check
         files: ^erd/.*\.txt$   # point at your schema files

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.1.4"
+version = "0.1.6"
 description = "Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit."
 readme = "README.md"
 license = "Apache-2.0"
@@ -25,6 +25,7 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = ["pytest>=8", "ruff>=0.6", "fonttools>=4.50"]
+docs = ["mkdocs>=1.6,<2", "mkdocs-material>=9.5,<10"]
 
 [project.scripts]
 qdbd = "quickdbd_cli.cli:main"

quickdbd_cli-0.1.6/src/quickdbd_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.6"

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.6}/src/quickdbd_cli/assets/render.js

@@ -178,6 +178,41 @@
     };
   }
 
+  /* ------------------------------------------------------------------ regions: one shaded area per group */
+  var REGION_COLORS = ["#4c78a8", "#59a14f", "#e15759", "#b07aa1", "#f28e2b", "#76b7b2", "#9c755f", "#edc948"];
+  var REGION_PAD = 28, REGION_LABEL = 30;
+  function regions(model, pos, mode) {
+    var geo = geometry(model, mode), groups = {}, names = [];
+    model.tables.forEach(function (t) {
+      var g = t.group || "", p = pos[t.id];
+      if (!g || !p) return;
+      if (!groups[g]) { groups[g] = [Infinity, Infinity, -Infinity, -Infinity]; names.push(g); }
+      var b = groups[g], tg = geo[t.id];
+      b[0] = Math.min(b[0], p[0]); b[1] = Math.min(b[1], p[1]);
+      b[2] = Math.max(b[2], p[0] + tg.w); b[3] = Math.max(b[3], p[1] + tg.h);
+    });
+    var all = {};
+    model.tables.forEach(function (t) { if (t.group) all[t.group] = true; });
+    var order = Object.keys(all).sort();
+    return names.sort().map(function (g) {
+      var b = groups[g];
+      return {
+        name: g,
+        color: REGION_COLORS[order.indexOf(g) % REGION_COLORS.length],
+        x: b[0] - REGION_PAD, y: b[1] - REGION_PAD - REGION_LABEL,
+        w: b[2] - b[0] + 2 * REGION_PAD, h: b[3] - b[1] + 2 * REGION_PAD + REGION_LABEL,
+      };
+    });
+  }
+  function renderRegions(model, pos, mode) {
+    return regions(model, pos, mode).map(function (r) {
+      return '<g class="rg" data-g="' + esc(r.name) + '"><rect x="' + n(r.x) + '" y="' + n(r.y) + '" width="' + n(r.w) + '" height="' + n(r.h) +
+        '" rx="14" fill="' + r.color + '" fill-opacity="0.07" stroke="' + r.color + '" stroke-opacity="0.45" stroke-width="1.5"/>' +
+        '<text x="' + n(r.x + 16) + '" y="' + n(r.y + 22) + '" fill="' + r.color + '" font-family="' + FONT +
+        '" font-size="16" font-weight="bold">' + esc(r.name) + "</text></g>";
+    }).join("");
+  }
+
   function renderEdges(model, pos, mode, geo) {
     geo = geo || geometry(model, mode);
     return model.rels.map(function (r) { return renderEdge(model, geo, pos, r); }).join("");
@@ -186,8 +221,9 @@
   /* opts.docMarks: underline tables/columns that have doc comments (viewer only, not exports). */
   function renderInner(model, pos, mode, opts) {
     var geo = geometry(model, mode), marks = !!(opts && opts.docMarks);
+    var rg = opts && opts.regions ? '<g class="regions">' + renderRegions(model, pos, mode) + "</g>" : "";
     var tables = model.tables.map(function (t) { return pos[t.id] ? renderTable(model, t, geo[t.id], pos[t.id], marks) : ""; }).join("");
-    return '<g class="edges">' + renderEdges(model, pos, mode, geo) + '</g><g class="tables">' + tables + "</g>";
+    return rg + '<g class="edges">' + renderEdges(model, pos, mode, geo) + '</g><g class="tables">' + tables + "</g>";
   }
 
   function bounds(model, pos, mode) {
@@ -208,11 +244,16 @@
     var mode = opts.mode || "full", m = subset(model, opts.only), pad = opts.pad == null ? 40 : opts.pad;
     var edgePad = 60;
     var b = bounds(m, pos, mode);
+    if (opts.regions) {
+      regions(m, pos, mode).forEach(function (r) {
+        b = [Math.min(b[0], r.x), Math.min(b[1], r.y), Math.max(b[2], r.x + r.w), Math.max(b[3], r.y + r.h)];
+      });
+    }
     var x0 = b[0] - pad - edgePad, y0 = b[1] - pad, w = b[2] - b[0] + 2 * (pad + edgePad), h = b[3] - b[1] + 2 * pad;
     var style = opts.fontCss ? "<style>" + opts.fontCss + "</style>" : "";
     return '<svg xmlns="http://www.w3.org/2000/svg" width="' + n(w) + '" height="' + n(h) + '" viewBox="' + n(x0) + " " + n(y0) + " " + n(w) + " " + n(h) + '">' +
       style + '<rect x="' + n(x0) + '" y="' + n(y0) + '" width="' + n(w) + '" height="' + n(h) + '" fill="' + C.bg + '"/>' +
-      renderInner(m, pos, mode) + "</svg>";
+      renderInner(m, pos, mode, { regions: opts.regions }) + "</svg>";
   }
 
   /* Tables within `depth` relationship hops of `focus`. */
@@ -252,6 +293,15 @@
     }
     function n2(v) { return Math.round(v); }
     var b = bounds(m, pos, mode);
+    if (opts.regions) {
+      regions(m, pos, mode).forEach(function (r) {
+        cells.push(cell({
+          id: id(), value: r.name, vertex: "1", parent: "1",
+          style: "rounded=1;arcSize=4;whiteSpace=wrap;html=0;fillColor=" + r.color + ";opacity=12;strokeColor=" + r.color +
+            ";verticalAlign=top;align=left;spacingLeft=12;spacingTop=4;fontStyle=1;fontSize=16;fontColor=" + r.color + ";",
+        }, g(r.x - b[0] + 40, r.y - b[1] + 40, r.w + KEYW, r.h)));
+      });
+    }
     m.tables.forEach(function (t) {
       var p = pos[t.id];
       if (!p) return;
@@ -377,8 +427,70 @@
     return model.tables.filter(function (t) { return (inc === null || inc[t.id]) && !exc[t.id]; }).map(function (t) { return t.id; });
   }
 
+  /* ------------------------------------------------------------------ path finder
+   * Shortest chain of relationships between two tables (relationships are walked in either
+   * direction). Each step says which columns join. */
+  function findPath(model, from, to) {
+    if (from === to) return [];
+    var adj = {};
+    model.rels.forEach(function (r, i) {
+      (adj[r.a.t] = adj[r.a.t] || []).push({ to: r.b.t, i: i, fwd: true });
+      (adj[r.b.t] = adj[r.b.t] || []).push({ to: r.a.t, i: i, fwd: false });
+    });
+    var prev = {}, queue = [from], seen = {};
+    seen[from] = true;
+    while (queue.length) {
+      var cur = queue.shift();
+      if (cur === to) break;
+      (adj[cur] || []).forEach(function (e) {
+        if (seen[e.to]) return;
+        seen[e.to] = true;
+        prev[e.to] = { from: cur, e: e };
+        queue.push(e.to);
+      });
+    }
+    if (!seen[to]) return null;
+    var steps = [], at = to;
+    while (at !== from) {
+      var pv = prev[at], r = model.rels[pv.e.i];
+      var here = pv.e.fwd ? r.a : r.b, there = pv.e.fwd ? r.b : r.a; // here = side of pv.from
+      steps.unshift({ rel: pv.e.i, from: { t: pv.from, c: here.c, card: here.card }, to: { t: at, c: there.c, card: there.card } });
+      at = pv.from;
+    }
+    return steps;
+  }
+
+  var SQL_RESERVED = ("all and any as asc between by case check column constraint create cross default delete desc distinct " +
+    "drop else end exists foreign from full grant group having in index inner insert intersect into is join key left like " +
+    "limit not null offset on or order outer primary references right select set table then to union unique update user " +
+    "using values view when where with").split(" ");
+  function sqlIdent(name) {
+    var plain = /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && SQL_RESERVED.indexOf(name.toLowerCase()) < 0;
+    return plain ? name : '"' + name.replace(/"/g, '""') + '"';
+  }
+
+  /* SQL FROM/JOIN clause following a path. */
+  function pathSql(model, from, steps) {
+    var byId = {};
+    model.tables.forEach(function (t) { byId[t.id] = t; });
+    function col(t, c) {
+      var x = byId[t].cols.filter(function (k) { return k.id === c; })[0];
+      return x ? sqlIdent(x.name) : null;
+    }
+    var lines = ["FROM " + sqlIdent(byId[from].name)];
+    steps.forEach(function (s) {
+      var a = byId[s.from.t].name, b = byId[s.to.t].name, ca = col(s.from.t, s.from.c), cb = col(s.to.t, s.to.c);
+      if (ca && cb) lines.push("JOIN " + sqlIdent(b) + " ON " + sqlIdent(b) + "." + cb + " = " + sqlIdent(a) + "." + ca);
+      else lines.push("JOIN " + sqlIdent(b) + " ON ...  -- table-level relationship: join columns not specified");
+    });
+    return lines.join("\n");
+  }
+
   root.qdbd = {
+    findPath: findPath,
+    pathSql: pathSql,
     renderDrawio: renderDrawio,
+    regions: regions,
     select: select,
     subset: subset,
     colors: C,
@@ -394,5 +506,7 @@
   root.qdbdRenderSvg = renderSvg;
   root.qdbdSelect = select;
   root.qdbdRenderDrawio = renderDrawio;
+  root.qdbdFindPath = findPath;
+  root.qdbdPathSql = pathSql;
   root.qdbdNeighbourhood = neighbourhood;
 })(typeof window !== "undefined" ? window : globalThis);

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.6}/src/quickdbd_cli/assets/style.css

@@ -22,14 +22,15 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
 .r.hl .rb { fill: #dbe6f6; fill-opacity: 1; }
 .r:hover .rb { fill: #eef3fa; fill-opacity: 1; }
 .t.flash .tb { stroke: #f0a020; stroke-width: 3; }
-.t { cursor: pointer; }
-.serve .t { cursor: move; }
+.t { cursor: grab; }
+#canvas.panning .t { cursor: grabbing; }
 
 /* toolbar (top right, like QuickDBD's zoom controls) */
 .bar { position: absolute; top: 14px; right: 16px; display: flex; gap: 6px; align-items: center; }
 .bar button, .seg button { border: 0; background: transparent; color: #555; font: inherit; cursor: pointer;
   padding: 6px 9px; border-radius: 4px; }
 .bar button:hover, .seg button:hover { background: #e4e7ea; }
+.bar button.on { background: #fff; color: var(--blue); box-shadow: 0 1px 2px rgba(0,0,0,.12); }
 .zoomval { min-width: 48px; text-align: center; color: #666; font-variant-numeric: tabular-nums; }
 .seg { display: flex; background: #e9ecee; border-radius: 6px; padding: 2px; }
 .seg button.on { background: #fff; color: var(--blue); box-shadow: 0 1px 2px rgba(0,0,0,.12); }
@@ -110,6 +111,20 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
   padding: 8px 14px; border-radius: 6px; font-size: 12px; opacity: 0; transition: opacity .2s; pointer-events: none; z-index: 6; }
 .toast.open { opacity: 1; }
 
+/* path finder (in the details panel) */
+.details .pathbox { display: flex; gap: 6px; margin: 10px 0 4px; }
+.details .pathbox input { flex: 1; min-width: 0; padding: 5px 8px; border: 1px solid var(--line); border-radius: 5px; font: inherit; outline: none; }
+.details .pathbox input:focus { border-color: var(--blue); }
+.details .pathres ol { margin: 6px 0 8px 18px; padding: 0; }
+.details .pathres li { border: 0; padding: 2px 0; }
+.details .pathres pre { background: #f6f8fa; border: 1px solid #eceff2; border-radius: 6px; padding: 8px; font-size: 11px;
+  overflow-x: auto; margin: 6px 0; }
+.details .pathres .acts a { margin-right: 12px; font-size: 12px; }
+.details .pathres .none { margin-top: 6px; }
+.e.ph .ep { stroke: #f0a020; stroke-width: 3; }
+.e.ph path, .e.ph circle { stroke: #f0a020; }
+.t.ph .tb { stroke: #f0a020; stroke-width: 2.5; }
+
 /* diff banner (build --diff-base) */
 .diffbar { position: absolute; top: 58px; left: 50%; transform: translateX(-50%); background: #fff; border: 1px solid var(--line);
   border-radius: 8px; padding: 6px 12px; font-size: 12px; box-shadow: 0 4px 14px rgba(0,0,0,.06); display: none; z-index: 2;
@@ -165,3 +180,13 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
 .CodeMirror-cursor { border-left-color: #fff !important; }
 .CodeMirror-selected { background: #4a525a !important; }
 .lineerr { background: rgba(229,115,115,.18); }
+
+/* narrow screens and embedded frames: toolbar to the bottom, smaller minimap */
+@media (max-width: 900px) {
+  .bar { top: auto; bottom: 12px; right: auto; left: 12px; flex-wrap: wrap; max-width: calc(100% - 24px);
+    background: rgba(255,255,255,.92); border-radius: 8px; padding: 2px; box-shadow: 0 2px 10px rgba(0,0,0,.08); }
+  .hint { display: none; }
+  .minimap { width: 140px; height: 100px; bottom: auto; top: 14px; right: 12px; }
+  .explorer { max-width: calc(100% - 180px); }
+  .details { left: 12px; right: 12px; width: auto; top: 12px; bottom: 64px; }
+}

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.6}/src/quickdbd_cli/assets/viewer.js

@@ -14,6 +14,8 @@
     filter: "",
     vm: data.model, // view model: the tables/relationships left after the filter
     shown: {},
+    regions: !!data.model.regions,
+    path: null, // {to: id, steps: [...]} from the selected table
   };
   var svg = document.getElementById("canvas");
   var vp = document.getElementById("vp");
@@ -27,7 +29,7 @@
 
   /* ------------------------------------------------------------- render */
   function render() {
-    vp.innerHTML = Q.renderInner(S.vm, S.pos, S.mode, { docMarks: true });
+    vp.innerHTML = Q.renderInner(S.vm, S.pos, S.mode, { docMarks: true, regions: S.regions });
     applyFocus();
     drawMinimap();
   }
@@ -51,11 +53,15 @@
     return [r.width || 800, r.height || 600];
   }
 
-  function fit() {
-    var b = Q.bounds(S.vm, 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);
+  function fit(only) {
+    var b = Q.bounds(only ? Q.subset(S.vm, only) : S.vm, S.pos, S.mode), sz = stageSize(), pad = 40;
+    if (S.regions && !only) b = [b[0] - 30, b[1] - 60, b[2] + 30, b[3] + 30]; // room for region borders and labels
+    if (only) sz = [sz[0] - (details.classList.contains("open") ? 400 : 0), sz[1]]; // keep clear of the details panel
+    // Keep clear of the floating search box / toolbar at the top and, on narrow screens, the toolbar at the bottom.
+    var top = 70, bottom = sz[0] < 900 ? 70 : pad, availH = sz[1] - top - bottom;
+    var k = Math.min((sz[0] - 2 * pad) / (b[2] - b[0]), availH / (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 };
+    S.view = { k: k, x: (sz[0] - (b[2] - b[0]) * k) / 2 - b[0] * k, y: top + (availH - (b[3] - b[1]) * k) / 2 - b[1] * k };
     applyView();
   }
 
@@ -94,6 +100,28 @@
   }
 
   function applyFocus() {
+    vp.querySelectorAll(".ph").forEach(function (el) { el.classList.remove("ph"); });
+    if (S.path && S.focus && S.path.steps) {
+      var on = {}, edges = [];
+      on[S.focus] = true;
+      S.path.steps.forEach(function (st) { on[st.to.t] = true; edges.push(st); });
+      svg.classList.add("focus");
+      vp.querySelectorAll(".t").forEach(function (el) {
+        var id = el.getAttribute("data-id");
+        el.classList.toggle("dim", !on[id]);
+        el.classList.toggle("ph", !!on[id]);
+      });
+      vp.querySelectorAll(".e").forEach(function (el) {
+        var a = el.getAttribute("data-a"), ac = el.getAttribute("data-ac"), b = el.getAttribute("data-b"), bc = el.getAttribute("data-bc");
+        var hit = edges.some(function (st) {
+          return (st.from.t === a && st.from.c === ac && st.to.t === b && st.to.c === bc) ||
+            (st.from.t === b && st.from.c === bc && st.to.t === a && st.to.c === ac);
+        });
+        el.classList.toggle("dim", !hit);
+        el.classList.toggle("ph", hit);
+      });
+      return;
+    }
     if (!S.focus || !byId[S.focus]) {
       S.focus = null;
       svg.classList.remove("focus");
@@ -180,12 +208,13 @@
     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) {
+    if (drag.table) { // tables are draggable everywhere; only `qdbd serve` saves the new position
       drag.start = S.pos[drag.table].slice();
+      tEl.parentNode.appendChild(tEl); // bring the grabbed table to the front
     } else {
       drag.view = { x: S.view.x, y: S.view.y };
-      svg.classList.add("panning");
     }
+    svg.classList.add("panning");
     svg.setPointerCapture(ev.pointerId);
   });
   var raf = null;
@@ -215,6 +244,7 @@
       return;
     }
     if (d.start) {
+      if (S.regions) render(); // regions are sized from table positions
       drawMinimap();
       var name = byId[d.table].name, body = {};
       body[name] = S.pos[d.table];
@@ -235,13 +265,28 @@
   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.getElementById("zfit").onclick = function () { fit(); };
   document.querySelectorAll("#modes button").forEach(function (b) {
     b.onclick = function () {
       setMode(b.getAttribute("data-mode"));
     };
   });
 
+  var regionBtn = document.getElementById("xregions");
+  function groupCount() {
+    var g = {};
+    S.model.tables.forEach(function (t) { if (t.group) g[t.group] = true; });
+    return Object.keys(g).length;
+  }
+  function setRegions(on) {
+    S.regions = !!on && groupCount() > 0;
+    regionBtn.classList.toggle("on", S.regions);
+    regionBtn.style.display = groupCount() > 1 ? "" : "none";
+    render();
+    scheduleHash();
+  }
+  regionBtn.onclick = function () { setRegions(!S.regions); };
+
   function setMode(mode) {
     S.mode = ["full", "keys", "header"].indexOf(mode) >= 0 ? mode : "full";
     document.querySelectorAll("#modes button").forEach(function (o) { o.classList.toggle("on", o.getAttribute("data-mode") === S.mode); });
@@ -251,6 +296,7 @@
 
   /* ------------------------------------------------------------- selection: focus + details */
   function select(id, opts) {
+    if ((id || null) !== S.focus) S.path = null;
     S.focus = id && byId[id] ? id : null;
     scheduleHash();
     applyFocus();
@@ -431,6 +477,10 @@
     if (t.file) meta.push(Q.esc(t.file) + ":" + t.line);
     if (meta.length) out.push('<div class="meta">' + meta.join(" &middot; ") + "</div>");
     if (t.doc) out.push('<div class="doc">' + Q.esc(t.doc) + "</div>");
+    out.push('<div class="pathbox"><input id="pathto" list="pathlist" placeholder="Path to another table…" autocomplete="off" value="' +
+      (S.path && byId[S.path.to] ? Q.esc(byId[S.path.to].name) : "") + '"></div><datalist id="pathlist">' +
+      S.vm.tables.filter(function (x) { return x.id !== id; }).map(function (x) { return '<option value="' + Q.esc(x.name) + '">'; }).join("") +
+      '</datalist><div class="pathres" id="pathres">' + pathHtml(id) + "</div>");
     if (t.diff && t.diff.state === "changed") {
       var base = (S.model.diff && S.model.diff.base) || "base", ch = [];
       t.cols.forEach(function (c) {
@@ -460,6 +510,47 @@
     details.classList.add("open");
     document.getElementById("stage").classList.add("has-details");
   }
+  /* ------------------------------------------------------------- path finder */
+  function pathHtml(id) {
+    if (!S.path) return "";
+    var to = byId[S.path.to];
+    if (!S.path.steps) return '<div class="none">No relationship path from ' + Q.esc(byId[id].name) + " to " + Q.esc(to.name) + " (with the current filter).</div>";
+    var items = S.path.steps.map(function (st) {
+      return "<li>" + link(st.from.t, st.from.c) + " &rarr; " + link(st.to.t, st.to.c) +
+        '<span class="card">' + CARD[st.from.card] + ":" + CARD[st.to.card] + "</span></li>";
+    }).join("");
+    return "<h3>Path to " + Q.esc(to.name) + " (" + S.path.steps.length + " join" + (S.path.steps.length === 1 ? "" : "s") + ")</h3><ol>" + items +
+      "</ol><pre>" + Q.esc(Q.pathSql(S.vm, id, S.path.steps)) + '</pre><div class="acts"><a id="pathsql">Copy SQL</a><a id="pathonly">Show only this path</a><a id="pathclear">Clear</a></div>';
+  }
+  function findPathTo(name) {
+    var target = null;
+    S.vm.tables.forEach(function (t) { if (t.name.toLowerCase() === String(name).trim().toLowerCase()) target = t.id; });
+    if (!S.focus || !target || target === S.focus) return false;
+    S.path = { to: target, steps: Q.findPath(S.vm, S.focus, target) };
+    showDetails(S.focus);
+    applyFocus();
+    if (S.path.steps && !applyingHash) fit([S.focus].concat(S.path.steps.map(function (st) { return st.to.t; })));
+    scheduleHash();
+    return true;
+  }
+  dbody.addEventListener("keydown", function (ev) {
+    if (ev.target.id === "pathto" && ev.key === "Enter") findPathTo(ev.target.value);
+    if (ev.target.id === "pathto" && ev.key === "Escape") ev.stopPropagation();
+  });
+  dbody.addEventListener("change", function (ev) { if (ev.target.id === "pathto") findPathTo(ev.target.value); });
+  dbody.addEventListener("click", function (ev) {
+    if (ev.target.id === "pathclear") { S.path = null; showDetails(S.focus); applyFocus(); scheduleHash(); }
+    else if (ev.target.id === "pathonly" && S.path && S.path.steps) {
+      var names = [byId[S.focus].name].concat(S.path.steps.map(function (st) { return byId[st.to.t].name; }));
+      // Selector syntax treats spaces, commas, + and a leading ! specially; match those characters with "?".
+      applyFilter(names.map(function (n) { return n.replace(/[\s,+!]/g, "?"); }).join(" "));
+    } else if (ev.target.id === "pathsql" && S.path && S.path.steps) {
+      var sql = Q.pathSql(S.vm, S.focus, S.path.steps);
+      if (navigator.clipboard && window.isSecureContext) navigator.clipboard.writeText(sql).then(function () { showToast("SQL copied"); });
+      else window.prompt("Copy SQL:", sql);
+    }
+  });
+
   function closeDetails() {
     details.classList.remove("open");
     document.getElementById("stage").classList.remove("has-details");
@@ -519,14 +610,14 @@
   }
   function exportSvg() {
     var only = S.focus ? Object.keys(neighbours(S.focus)) : null;
-    return Q.renderSvg(S.vm, S.pos, { mode: S.mode, only: only, fontCss: document.getElementById("qdbd-font").textContent });
+    return Q.renderSvg(S.vm, S.pos, { mode: S.mode, only: only, regions: S.regions, fontCss: document.getElementById("qdbd-font").textContent });
   }
   document.getElementById("xsvg").onclick = function () {
     download((data.title || "diagram") + ".svg", new Blob([exportSvg()], { type: "image/svg+xml" }));
   };
   document.getElementById("xdrawio").onclick = function () {
     var only = S.focus ? Object.keys(neighbours(S.focus)) : null;
-    var xml = Q.renderDrawio(S.vm, S.pos, { mode: S.mode, only: only, title: data.title || "ERD" });
+    var xml = Q.renderDrawio(S.vm, S.pos, { mode: S.mode, only: only, title: data.title || "ERD", regions: S.regions });
     download((data.title || "diagram") + ".drawio", new Blob([xml], { type: "application/xml" }));
   };
   document.getElementById("xpng").onclick = function () {
@@ -564,6 +655,9 @@
 
   index();
   if (S.serve) document.body.classList.add("serve");
+  if (stageSize()[0] < 900) explorer.classList.add("collapsed"); // small screens / embedded frames
+  regionBtn.classList.toggle("on", S.regions);
+  regionBtn.style.display = groupCount() > 1 ? "" : "none";
   computeView();
   render();
   drawTree();
@@ -597,7 +691,9 @@
     var p = new URLSearchParams(), v = S.view, sz = stageSize();
     if (S.filter) p.set("f", S.filter);
     if (S.focus && byId[S.focus]) p.set("t", byId[S.focus].name);
+    if (S.path && byId[S.path.to]) p.set("p", byId[S.path.to].name);
     if (S.mode !== "full") p.set("m", S.mode);
+    if (S.regions !== !!S.model.regions) p.set("r", S.regions ? "1" : "0");
     p.set("z", String(Math.round(v.k * 1000) / 1000));
     p.set("c", Math.round((sz[0] / 2 - v.x) / v.k) + "," + Math.round((sz[1] / 2 - v.y) / v.k));
     return "#" + p.toString();
@@ -615,10 +711,12 @@
     applyingHash = true;
     try {
       if (p.has("m")) setMode(p.get("m"));
+      if (p.has("r")) setRegions(p.get("r") === "1");
       applyFilter(p.get("f") || "", true);
       var name = p.get("t"), id = null;
       if (name) S.model.tables.forEach(function (t) { if (t.name === name) id = t.id; });
       select(id && S.shown[id] ? id : null);
+      if (p.get("p") && S.focus) findPathTo(p.get("p"));
       var z = parseFloat(p.get("z")), c = (p.get("c") || "").split(",").map(Number);
       if (z > 0 && c.length === 2 && !isNaN(c[0]) && !isNaN(c[1])) {
         var sz = stageSize();