ripple-sql 0.1.3__tar.gz → 0.1.5__tar.gz

{ripple_sql-0.1.3 → ripple_sql-0.1.5}/CHANGELOG.md

@@ -6,6 +6,17 @@ Notable changes to Ripple. The format follows
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-09-09
+
+### Added
+- Every column under a model on the page carries the number of models that read it directly, the same number a model chip carries, so the cost of a change shows before the question is asked. A column no link touches (a constant, or one the engine could not trace) is drawn loose, dashed and faint, with "no link found" in the key; r/dataengineering asked for "a clear view of mapped vs unmapped fields (with some kind of legend)", and a traced-looking constant would have been a lie.
+
+## [0.1.4] - 2026-09-09
+
+### Changed
+- A large project opens on an index, not a wall of chips. Past forty models the home page lists where things live (a dbt folder, a schema, a BigQuery dataset) in the order the data flows, each with the models most read by other models in view and the rest behind "more"; hovering a group tints what feeds it and what reads it. Clicking any model opens its own neighbourhood: what feeds it on the left, what reads it on the right, wires between them, another step on request, its columns under it to ask. The address bar carries the model, so Back and a shared link land on the same view. Measured on Mozilla's bigquery-etl (2,365 tables) and a synthetic 5,500-model project: the old page showed 6 percent of the models in a page ten screens tall; the new one shows every group on one screen and any model in one click.
+- The question box finds as you type: models and columns from the map the page already holds, eight at a time, arrows to pick, Enter to go. A datalist did this before and put every column on the page as an option; at 5,500 models that was 99,000 elements and most of a 5.3 MB page. The page is 3.0 MB now, and 1.4 MB for Mozilla.
+
 ## [0.1.3] - 2026-09-09
 
 ### Changed
@@ -243,7 +254,9 @@ First public release.
 ### Removed
 - The dark whole-graph canvas that `ripple serve` used to open (`static/index.html`). Every surface now draws one answer.
 
-[Unreleased]: https://github.com/bteh/ripple/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/bteh/ripple/compare/v0.1.5...HEAD
+[0.1.5]: https://github.com/bteh/ripple/releases/tag/v0.1.5
+[0.1.4]: https://github.com/bteh/ripple/releases/tag/v0.1.4
 [0.1.3]: https://github.com/bteh/ripple/releases/tag/v0.1.3
 [0.1.2]: https://github.com/bteh/ripple/releases/tag/v0.1.2
 [0.1.1]: https://github.com/bteh/ripple/releases/tag/v0.1.1

{ripple_sql-0.1.3 → ripple_sql-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ripple-sql
-Version: 0.1.3
+Version: 0.1.5
 Summary: Offline column-level SQL lineage. See what breaks before you merge.
 Project-URL: Homepage, https://github.com/bteh/ripple
 Project-URL: Repository, https://github.com/bteh/ripple

{ripple_sql-0.1.3 → ripple_sql-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ripple-sql"
-version = "0.1.3"
+version = "0.1.5"
 description = "Offline column-level SQL lineage. See what breaks before you merge."
 readme = "README.md"
 requires-python = ">=3.10"

{ripple_sql-0.1.3 → ripple_sql-0.1.5}/src/ripple/answer_page.py

@@ -24,6 +24,8 @@ TEMPLATE = Path(__file__).parent / "static" / "answer.html"
 STYLE = Path(__file__).parent / "static" / "answer.css"
 TWIN = Path(__file__).parent / "static" / "answer_twin.js"
 EXPLORE = Path(__file__).parent / "static" / "explore.js"
+FOCUS = Path(__file__).parent / "static" / "focus.js"
+FIND = Path(__file__).parent / "static" / "find.js"
 EMBED_BUDGET_ENV = "RIPPLE_EMBED_GRAPH_BYTES"
 DEFAULT_EMBED_BUDGET = 5_000_000
 TRUST_CODE = {"verified": "v", "high_confidence": "h", "moderate": "m", "review_required": "r"}
@@ -161,6 +163,8 @@ def _page(data: dict, title: str) -> str:
         .replace("/*CSS*/", STYLE.read_text(encoding="utf-8"))
         .replace("/*TWIN*/", TWIN.read_text(encoding="utf-8"))
         .replace("/*EXPLORE*/", EXPLORE.read_text(encoding="utf-8"))
+        .replace("/*FOCUS*/", FOCUS.read_text(encoding="utf-8"))
+        .replace("/*FIND*/", FIND.read_text(encoding="utf-8"))
     )
     return html.replace("__TITLE__", _escape(title)).replace("__DATA__", blob)
 

{ripple_sql-0.1.3 → ripple_sql-0.1.5}/src/ripple/home.py

@@ -39,19 +39,6 @@ def starters(edges, limit: int = STARTERS) -> list[dict]:
     return [{"id": cid, "readers": len(models)} for cid, models in ranked[:limit]]
 
 
-def column_ids(edges) -> list[str]:
-    """Every column that takes part in a value link, for the question box's
-    suggestions. Dashboard entries and star placeholders stay out."""
-    ids: set[str] = set()
-    for e in edges:
-        if e.kind != "value":
-            continue
-        for model, column in ((e.src_model, e.src_column), (e.dst_model, e.dst_column)):
-            if column != "*" and not model.startswith(DASHBOARD_PREFIXES):
-                ids.add(f"{model}.{column}")
-    return sorted(ids)
-
-
 def coverage_row(stats: dict, unresolved: list[dict]) -> dict:
     """Rung one: links that need review and the external tables behind them."""
     links = _plural(stats["edges"], "column link")
@@ -143,10 +130,19 @@ def model_map(nodes: list[dict], edges) -> dict:
         }
     fed = {e.dst_model for e in edges}
     seen: dict[str, dict[str, None]] = {}
+    readers: dict[tuple[str, str], set[str]] = {}
+    linked: set[tuple[str, str]] = set()
     for e in edges:
         for model, column in ((e.src_model, e.src_column), (e.dst_model, e.dst_column)):
             if _is_column(column):
                 seen.setdefault(model, {})[column] = None
+        if e.kind != "value" or not (_is_column(e.src_column) and _is_column(e.dst_column)):
+            continue
+        linked.add((e.src_model, e.src_column))
+        linked.add((e.dst_model, e.dst_column))
+        # a dashboard number is not a reader; only models count (as in starters)
+        if not e.dst_model.startswith(DASHBOARD_PREFIXES):
+            readers.setdefault((e.src_model, e.src_column), set()).add(e.dst_model)
     for name in sorted({e.src_model for e in edges} | fed):
         if name in members:
             known = members[name]["columns"]
@@ -164,10 +160,108 @@ def model_map(nodes: list[dict], edges) -> dict:
             "status": None,
             "path": None,
         }
+    for m in members.values():
+        # per column, aligned with `columns`: how many models read it directly;
+        # -1 when no link touches it at all (a constant, or one the engine
+        # could not trace), so the page never draws such a column as traced
+        m["reads"] = [
+            len(readers.get((m["id"], c), ())) if (m["id"], c) in linked else -1
+            for c in m["columns"]
+        ]
     links = _links(edges)
     layers = _layers(members, links)
     models = [{**m, "layer": layers[m["id"]]} for m in members.values()]
-    return {"models": _ordered(models, links), "links": links}
+    _name_groups(models)
+    ordered = _ordered(models, links)
+    return {"models": ordered, "links": links, "groups": _groups(ordered, links)}
+
+
+def group_of(member: dict) -> str:
+    """Where a model lives, as a person would say it: the folder of a model,
+    the schema of a source table, "dashboards" for a dashboard number.
+
+    A file named after its model sits in its folder (`models/marts/orders.sql`
+    is in `models/marts`). A file with a generic name names its folder as the
+    table (`telemetry_derived/clients_v1/query.sql`), so the group is the
+    folder above. A model with no path is in "models"."""
+    if member["kind"] == "dashboard":
+        return "dashboards"
+    if member["kind"] == "source":
+        schema, dot, _ = member["id"].rpartition(".")
+        return schema if dot else "sources"
+    path = member.get("path")
+    if not path:
+        return "models"
+    parts = path.replace("\\", "/").split("/")
+    stem = parts[-1].rsplit(".", 1)[0]
+    folders = parts[:-1]
+    if folders and stem != member["id"]:
+        folders = folders[:-1]
+    return "/".join(folders) or "models"
+
+
+def _shorten(names: set[str], sep: str) -> dict[str, str]:
+    """Drop the leading segments every name shares, so `models/staging` and
+    `models/marts` read as `staging` and `marts`. A lone name keeps itself."""
+    parts = {n: n.split(sep) for n in names}
+    while True:
+        deep = [p for p in parts.values() if len(p) > 1]
+        if len(deep) < 2 or len({p[0] for p in deep}) != 1:
+            break
+        parts = {n: p[1:] if len(p) > 1 else p for n, p in parts.items()}
+    return {n: sep.join(p) for n, p in parts.items()}
+
+
+SOURCE_SCHEMAS = 6
+
+
+def _name_groups(models: list[dict]) -> None:
+    """Set each model's group, shortened per kind, in place. A project that
+    reads from more than a handful of schemas gets one "sources" group: a
+    row per schema would be a page of one-table rows, and the chip already
+    carries the schema in its name."""
+    raw = {m["id"]: group_of(m) for m in models}
+    short: dict[str, str] = {}
+    for kind, sep in (("model", "/"), ("source", ".")):
+        names = {raw[m["id"]] for m in models if m["kind"] == kind}
+        if kind == "source" and len(names) > SOURCE_SCHEMAS:
+            short.update({n: "sources" for n in names})
+            continue
+        short.update(_shorten(names, sep))
+    for m in models:
+        m["group"] = short.get(raw[m["id"]], raw[m["id"]])
+
+
+GROUP_RANK = {"source": 0, "model": 1, "dashboard": 2}
+
+
+def _groups(models: list[dict], links: list[dict]) -> list[dict]:
+    """The groups in the order the data flows: source schemas, then model
+    folders by the mean layer of their models, then dashboards. Each carries
+    how many models it holds and how many models outside it read one of its."""
+    by: dict[str, dict] = {}
+    of: dict[str, str] = {}
+    for m in models:
+        g = by.setdefault(
+            m["group"],
+            {"id": m["group"], "kind": m["kind"], "n": 0, "readers": set(), "layers": []},
+        )
+        g["n"] += 1
+        g["layers"].append(m["layer"])
+        if GROUP_RANK[m["kind"]] > GROUP_RANK[g["kind"]]:
+            g["kind"] = m["kind"]
+        of[m["id"]] = m["group"]
+    for link in links:
+        src, dst = of.get(link["src"]), of.get(link["dst"])
+        if src and dst and src != dst:
+            by[src]["readers"].add(link["dst"])
+    out = sorted(
+        by.values(),
+        key=lambda g: (GROUP_RANK[g["kind"]], sum(g["layers"]) / len(g["layers"]), g["id"]),
+    )
+    return [
+        {"id": g["id"], "kind": g["kind"], "n": g["n"], "readers": len(g["readers"])} for g in out
+    ]
 
 
 def _ordered(models: list[dict], links: list[dict]) -> list[dict]:

{ripple_sql-0.1.3 → ripple_sql-0.1.5}/src/ripple/server.py

@@ -117,7 +117,6 @@ def home_page(service) -> str:
         "review": stats["review_required_edges"],
         "ladder": home.ladder_rows(stats, graph.unresolved_tables(), read_store(root)),
         "starters": home.starters(graph.edges),
-        "columns": home.column_ids(graph.edges),
         "map": home.model_map(graph.to_dict()["nodes"], graph.edges),
     }
     return answer_page.render_live(info, live)

{ripple_sql-0.1.3 → ripple_sql-0.1.5}/src/ripple/static/answer.css

@@ -28,7 +28,8 @@ h1 code{font:500 24px/1 var(--mono); letter-spacing:0}
 
 .ask{display:flex; flex-wrap:wrap; gap:8px; align-items:center; margin:28px 0 0; padding:16px 0 14px; border-top:1px solid var(--line); border-bottom:1px solid var(--line)}
 .ask input,.ask select{font:400 14px var(--mono); padding:8px 10px; border:1px solid var(--line-strong); border-radius:var(--r); background:var(--surface); color:var(--ink); min-width:0; height:36px}
-.ask input{flex:1 1 280px}
+.ask .findwrap{flex:1 1 280px; position:relative; min-width:0}
+.ask .findwrap input{width:100%}
 .ask input::placeholder{color:var(--faint)}
 .ask select{font-family:var(--sans); padding-right:28px; appearance:none; -webkit-appearance:none;
   background-image:linear-gradient(45deg,transparent 50%,var(--muted) 50%),linear-gradient(135deg,var(--muted) 50%,transparent 50%);
@@ -76,6 +77,7 @@ h1 code{font:500 24px/1 var(--mono); letter-spacing:0}
 .key i.r{border-top-style:dashed; border-color:var(--review)}
 .key s{display:inline-block; width:11px; height:11px; border-radius:2px; background:var(--ink); border:1px solid var(--ink); text-decoration:none}
 .key s.src{background:var(--well); border:1px dashed var(--line-strong)}
+.key s.unk{background:transparent; border:1px dashed var(--faint)}
 .key small.n{font:400 11.5px/1 var(--sans); color:var(--faint); border:1px solid var(--line-strong); border-radius:var(--r); padding:2px 5px; background:var(--surface)}
 .hint{margin-left:auto; font-size:12.5px; color:var(--faint)}
 .rows{padding:0 22px 14px; font-size:13.5px; color:var(--muted)}
@@ -109,6 +111,9 @@ pre{margin:0; padding:16px 22px 18px; overflow-x:auto; font:400 13px/1.65 var(--
 .cols{display:flex; flex-direction:column; gap:5px; margin:0 0 6px 10px; padding-left:10px; border-left:1px solid var(--line)}
 .cols .gname{max-width:36ch; white-space:normal; line-height:1.45; padding-top:2px}
 .cols .node{cursor:pointer}
+.cols .node small{font:400 11px/1 var(--sans); color:var(--faint); margin-left:5px}
+.cols .node.unk{color:var(--muted)}
+.cols .node.unk:hover{border-color:var(--accent)}
 .cols .node:hover{border-color:var(--accent); color:var(--accent-strong)}
 .more-chips{font:500 12.5px var(--sans); color:var(--accent); background:none; border:0; padding:4px 0; cursor:pointer; text-align:left}
 .more-chips:hover{text-decoration:underline}
@@ -120,19 +125,63 @@ pre{margin:0; padding:16px 22px 18px; overflow-x:auto; font:400 13px/1.65 var(--
 .key s.up{background:#E4F1F4; border:1px solid var(--accent)}
 .key s.sel{background:var(--accent); border-color:var(--accent)}
 .key s.down{background:var(--well); border:1px solid var(--ink)}
-/* compact: the map of a large project, layers as wrapped grids, no wires */
-.map.compact .board{overflow-x:visible; padding:18px 22px 8px}
-.map.compact .board-inner{flex-direction:column; gap:22px; min-width:0}
-.map.compact .wires{display:none}
-.map.compact .lvl{min-width:0; gap:10px}
-.map.compact .chips{display:flex; flex-wrap:wrap; gap:6px 8px; align-items:flex-start}
-.map.compact .grp{display:contents}
-.map.compact .grp.open{display:flex; flex-basis:100%; flex-direction:column; gap:6px}
-.map.compact .grp.miss{display:none}
-.map.compact .mdl{max-width:100%; overflow-wrap:anywhere; text-align:left; line-height:1.25}
+/* the index: a large project as rows of where things live, hubs first */
+.map.compact .board{overflow-x:visible; padding:6px 22px 10px}
+.map.compact .board-inner{display:block; min-width:0}
+.map.compact.focused .board{overflow-x:auto; padding:22px 22px 20px}
+.map.compact.focused .board-inner{display:flex; gap:32px; align-items:flex-start; min-width:max-content}
+.index{display:grid; grid-template-columns:minmax(150px,220px) 1fr; column-gap:22px}
+.grow{display:contents}
+.grow > *{padding:12px 0 11px; border-top:1px solid var(--line)}
+.grow:first-child > *{border-top:0}
+.grow.miss{display:none}
+.gcell{display:flex; flex-direction:column; align-items:flex-start; gap:3px; margin:0; padding-left:8px; padding-right:8px; margin-left:-8px; font:400 13px/1.3 var(--mono); color:var(--ink); background:none; border:0; border-top:1px solid var(--line); border-radius:var(--r); text-align:left; cursor:pointer; overflow-wrap:anywhere; transition:background .12s var(--ease)}
+.grow:first-child .gcell{border-top:0}
+.gcell .gid{display:block}
+.gcell .gpath{display:block; font-size:11.5px; color:var(--faint)}
+.gcell small{font:400 12px/1.3 var(--sans); color:var(--muted)}
+.grow.sel .gpath{color:rgba(255,255,255,.72)}
+.gcell:hover{background:var(--well)}
+.grow.sel .gcell{background:var(--accent); color:#fff}
+.grow.sel .gcell small{color:rgba(255,255,255,.72)}
+.grow.up .gcell{background:#E4F1F4; box-shadow:inset 3px 0 0 var(--accent)}
+.grow.down .gcell{background:var(--well); box-shadow:inset 3px 0 0 var(--ink)}
+.index .chips{display:flex; flex-wrap:wrap; gap:6px 8px; align-items:center}
+.index .mdl{max-width:100%; overflow-wrap:anywhere; text-align:left; line-height:1.25}
+.index .gname{flex-basis:100%}
 .map.compact .cols{flex-direction:row; flex-wrap:wrap; gap:6px 8px; margin:0 0 8px 14px; padding:8px 0 8px 10px}
 .map.compact .cols .gname{flex-basis:100%; max-width:60ch}
 .map.compact.focus .mdl:not(.on){opacity:.28}
+/* focus: one model between what feeds it and what reads it */
+.map-head{display:flex; flex-wrap:wrap; align-items:baseline; gap:4px 8px; padding:12px 22px 0; font:400 13px var(--sans); color:var(--muted)}
+.crumb-home{font:500 13px var(--sans); color:var(--accent); background:none; border:0; padding:0; cursor:pointer}
+.crumb-home:hover{text-decoration:underline}
+.crumb-sep{color:var(--faint)}
+.crumb-group{font:400 13px var(--mono); color:var(--muted)}
+.crumb-here{font:500 13px var(--mono); color:var(--ink); overflow-wrap:anywhere}
+.crumb-counts{margin-left:auto; color:var(--faint); font-variant-numeric:tabular-nums}
+.map.compact.focused .lvl{min-width:150px; max-width:300px}
+.map.compact.focused .lvl.asked{max-width:330px}
+.map.compact.focused .lvl.up .lhead{color:var(--accent)}
+.map.compact.focused .lvl.asked .lhead{color:var(--muted); font-weight:500; border-bottom-color:var(--line)}
+.map.compact.focused .grp.open{display:flex; flex-direction:column}
+.mdl.anchor{position:relative; font-weight:500}
+.mdl.anchor::before,.mdl.anchor::after{content:""; position:absolute; inset:-5px; border:1px solid var(--accent-ring); border-radius:7px; pointer-events:none}
+.mdl.anchor::after{inset:-10px; border-radius:11px; border-color:rgba(10,124,147,.14)}
+.map.compact.focused .cols{flex-direction:row; flex-wrap:wrap; gap:6px 8px; margin:4px 0 6px 10px; padding:6px 0 0 10px; max-width:320px}
+.map.compact.focused .cols .gname{flex-basis:100%; max-width:40ch}
+.hop{align-self:flex-start; display:inline-flex; align-items:baseline; gap:6px; font:500 12.5px var(--sans); color:var(--accent); background:none; border:1px dashed var(--line-strong); border-radius:var(--r); padding:6px 9px; margin-top:2px; cursor:pointer; white-space:nowrap}
+.hop small{font:400 11.5px var(--sans); color:var(--faint)}
+.hop:hover{border-color:var(--accent)}
+.more-groups{padding:14px 0 4px}
+.wires path.o{stroke:var(--accent-soft); stroke-width:1.5}
+/* the question box finds as you type */
+.find{position:absolute; z-index:20; left:0; right:0; top:calc(100% + 4px); margin:0; padding:4px 0; list-style:none; background:var(--surface); border:1px solid var(--line-strong); border-radius:var(--r); box-shadow:0 8px 24px rgba(14,27,38,.10)}
+.find li{display:flex; align-items:baseline; justify-content:space-between; gap:12px; padding:7px 10px; font:400 13px var(--mono); color:var(--ink); cursor:pointer}
+.find li b{font-weight:600; color:var(--accent-strong)}
+.find li small{font:400 12px var(--sans); color:var(--faint); white-space:nowrap}
+.find li[aria-selected="true"]{background:var(--well)}
+.find .fid{overflow-wrap:anywhere}
 .map .hidden-note{color:var(--muted)}
 
 .ladder{margin:26px 0 0; display:grid; grid-template-columns:max-content 1fr; gap:12px 20px; align-items:baseline}
@@ -166,6 +215,10 @@ pre{margin:0; padding:16px 22px 18px; overflow-x:auto; font:400 13px/1.65 var(--
   .lvl{min-width:0}
   .lvl+.lvl::before{content:'↓'; color:var(--faint); font-size:14px; margin-top:-14px}
   .hint{margin-left:0; flex-basis:100%}
+  .index{grid-template-columns:1fr}
+  .grow > *{border-top:0; padding:6px 0}
+  .grow .gcell{border-top:1px solid var(--line); padding-top:12px}
+  .crumb-counts{margin-left:0; flex-basis:100%}
   .ladder{grid-template-columns:1fr; gap:4px 0}
   .ladder .rung{margin-top:10px}
 }

{ripple_sql-0.1.3 → ripple_sql-0.1.5}/src/ripple/static/answer.html

@@ -18,8 +18,7 @@
   <div class="change" id="change" hidden><span class="lab">In this change</span></div>
 
   <form class="ask" id="ask" hidden>
-    <input id="q" list="cols" placeholder="ask about another column: model.column" autocomplete="off" spellcheck="false">
-    <datalist id="cols"></datalist>
+    <div class="findwrap"><input id="q" placeholder="ask about another column: model.column" autocomplete="off" spellcheck="false"><ul class="find" id="find" hidden></ul></div>
     <select id="dir" aria-label="direction"><option value="breaks">what breaks</option><option value="trace">where it comes from</option></select>
     <button type="submit">Ask</button>
     <p class="fine" id="askfine">Answered inside this file. Nothing sent.</p>
@@ -27,6 +26,7 @@
   </form>
 
   <section class="map" id="map" hidden aria-label="every model in this project">
+    <div class="map-head" id="maphead" hidden></div>
     <div class="board"><div class="board-inner" id="mapboard"><svg class="wires" id="mapwires" aria-hidden="true"></svg></div></div>
     <div class="board-foot">
       <span class="key" id="key-feeds"><i></i> feeds</span>
@@ -35,6 +35,7 @@
       <span class="key"><i class="r"></i> needs review</span>
       <span class="key" id="key-chain" hidden><s class="up"></s> feeds it <s class="sel"></s> chosen <s class="down"></s> reads it</span>
       <span class="key"><small class="n">3</small> models that read it</span>
+      <span class="key"><s class="unk"></s> no link found</span>
       <span class="hidden-note" id="maphidden" hidden></span>
       <span class="hint" id="maphint">Hover lights the chain. Click a model for its columns, a column to ask.</span>
     </div>
@@ -76,6 +77,10 @@
 
   /*EXPLORE*/
 
+  /*FOCUS*/
+
+  /*FIND*/
+
   function show(a, text){
     current = a;
     demo.hidden = false;
@@ -223,12 +228,14 @@
   }
 
   // SERVE START
-  var LIVE_FINE = 'Answered from your files as they are now, on this machine.';
+  var LIVE_FINE = 'Read from your SQL files as they are now, on this machine. No warehouse login, nothing sent.';
   // ripple serve: the question box asks the local server, which answers from
   // the files as they are now. Relative path only; the file page never runs this.
+  var HINT_SMALL = 'Hover lights the chain. Click a model for its columns, a column to ask.';
+  var HINT_INDEX = 'Hover a group to see what it feeds. Click a model for what feeds it and what reads it; type to find anything.';
+  var HINT_FOCUS = 'Click a model to move to it, a column to ask. Esc goes back to all models.';
+  function hint(text){ document.getElementById('maphint').textContent = text; }
   if (L){
-    var list0 = document.getElementById('cols');
-    L.columns.forEach(function(id){ var o = document.createElement('option'); o.value = id; list0.appendChild(o); });
     var form0 = document.getElementById('ask'); form0.hidden = false;
     var strip0 = document.getElementById('starters');
     if (L.starters.length){
@@ -242,17 +249,38 @@
     }
     if (L.map && L.map.models.length){
       var hiddenNote = document.getElementById('maphidden');
-      mapApi = renderMap(mapEl, L.map, {esc: esc,
+      mapApi = renderMap(mapEl, L.map, {esc: esc, reduce: reduce,
         onAsk: function(id){ document.getElementById('q').value = id; ask(id, document.getElementById('dir').value); },
+        onFocus: function(id){ go(id, true); },
+        onHome: function(){ goHome(true); },
         onFilter: function(n){ hiddenNote.hidden = !n; hiddenNote.textContent = n ? plural(n, 'model') + ' hidden by the filter' : ''; }});
       if (mapApi.compact){
         document.getElementById('key-feeds').hidden = true;
         document.getElementById('key-chain').hidden = false;
-        document.getElementById('maphint').textContent = 'Hover lights the chain, click keeps it. Click a column to ask; type to narrow the map.';
       }
       document.getElementById('q').addEventListener('input', function(){ if (!mapEl.hidden) mapApi.filter(this.value.trim()); });
-      document.getElementById('tomap').addEventListener('click', function(){ home(); history.replaceState(null, '', location.pathname); });
+      document.getElementById('tomap').addEventListener('click', function(){ goHome(true); });
     }
+    // the question box finds models and columns from the map as you type
+    var found = null;
+    attachFind(document.getElementById('q'), {esc: esc, list: document.getElementById('find'),
+      candidates: function(){
+        if (found) return found;
+        found = [];
+        if (!L.map) return found;
+        var feeds = {};
+        L.map.links.forEach(function(l){ feeds[l.src] = (feeds[l.src] || 0) + 1; });
+        L.map.models.forEach(function(m){
+          found.push({id: m.id, kind: m.kind, feeds: feeds[m.id] || 0});
+          if (m.kind !== 'dashboard') m.columns.forEach(function(c){ found.push({id: m.id + '.' + c, kind: 'column', feeds: feeds[m.id] || 0}); });
+        });
+        return found;
+      },
+      onPick: function(c){
+        if (c.kind === 'column' || !mapApi){ ask(c.id, document.getElementById('dir').value); return; }
+        document.getElementById('q').value = '';
+        go(c.id, true);
+      }});
     var ladder = document.getElementById('ladder'); ladder.hidden = false;
     ['Coverage', 'Usage'].forEach(function(name, i){
       var row = L.ladder[i], p = document.createElement('p');
@@ -269,10 +297,34 @@
     form0.addEventListener('submit', function(ev){
       ev.preventDefault();
       var target = document.getElementById('q').value.trim();
-      if (target) ask(target, document.getElementById('dir').value);
+      if (!target) return;
+      if (mapApi && !/\./.test(target) && mapApi.focus(target)){ document.getElementById('q').value = ''; go(target, true); return; }
+      ask(target, document.getElementById('dir').value);
     });
   }
-  function ask(target, dir){
+  // one model's neighbourhood, the index of all models, or an answer: the
+  // address bar says which, so Back and a shared link land on the same view
+  function go(id, push){
+    if (current || mapEl.hidden) home();
+    if (!mapApi.focus(id)){ fine.textContent = 'No model called ' + id + ' in this project.'; return; }
+    hint(mapApi.compact ? HINT_FOCUS : HINT_SMALL);
+    if (push) history.pushState({m: id}, '', '?m=' + encodeURIComponent(id));
+  }
+  function goHome(push){
+    if (current || mapEl.hidden) home();
+    if (mapApi){ mapApi.home(); hint(mapApi.compact ? HINT_INDEX : HINT_SMALL); requestAnimationFrame(mapApi.draw); }
+    if (push) history.pushState({}, '', location.pathname);
+  }
+  function route(params){
+    var q = params.get('q'), m = params.get('m');
+    if (q){
+      document.getElementById('q').value = q;
+      document.getElementById('dir').value = params.get('dir') === 'trace' ? 'trace' : 'breaks';
+      ask(q, document.getElementById('dir').value, true);
+    } else if (m && mapApi) go(m, false);
+    else goHome(false);
+  }
+  function ask(target, dir, silent){
     fine.textContent = 'asking the local server…';
     fetch(L.api + '/' + dir + '?target=' + encodeURIComponent(target), {cache: 'no-store'}).then(function(r){
       return r.json().then(function(j){ return [r.ok, j]; });
@@ -286,7 +338,7 @@
       }
       fine.textContent = LIVE_FINE;
       show(j.answer, j.text);
-      history.replaceState(null, '', '?q=' + encodeURIComponent(target) + '&dir=' + dir);
+      if (!silent) history.pushState({q: target}, '', '?q=' + encodeURIComponent(target) + '&dir=' + dir);
     }).catch(function(){ fine.textContent = 'The local server did not answer. Is ripple serve still running?'; });
   }
   // SERVE END
@@ -295,22 +347,29 @@
   var G = DATA.graph, index = G ? buildIndex(G) : null;
   function offline(target, dir){ return dir === 'trace' ? computeTrace(index, target, noun) : computeBreaks(index, target, noun); }
   if (G){
-    var list = document.getElementById('cols');
-    Object.keys(index.ids).sort().forEach(function(id){ if (id.indexOf('(') < 0 && id.slice(-2) !== '.*'){ var o = document.createElement('option'); o.value = id; list.appendChild(o); } });
     var form = document.getElementById('ask'); form.hidden = false;
     document.getElementById('q').value = '';
-    form.addEventListener('submit', function(ev){
-      ev.preventDefault();
-      var target = document.getElementById('q').value.trim(), dir = document.getElementById('dir').value;
-      if (!target) return;
-      var found = resolveTarget(index, target), fine2 = document.getElementById('askfine');
-      if (!found.id){
-        fine2.textContent = found.error + '.' + (found.candidates && found.candidates.length ? ' Did you mean: ' + found.candidates.join(', ') + '?' : '');
+    var ids0 = null;
+    attachFind(document.getElementById('q'), {esc: esc, list: document.getElementById('find'),
+      candidates: function(){
+        if (!ids0) ids0 = Object.keys(index.ids).sort().filter(function(id){ return id.indexOf('(') < 0 && id.slice(-2) !== '.*'; }).map(function(id){ return {id: id, kind: 'column'}; });
+        return ids0;
+      },
+      onPick: function(c){ askOffline(c.id, document.getElementById('dir').value); }});
+    function askOffline(target, dir){
+      var hit = resolveTarget(index, target), fine2 = document.getElementById('askfine');
+      if (!hit.id){
+        fine2.textContent = hit.error + '.' + (hit.candidates && hit.candidates.length ? ' Did you mean: ' + hit.candidates.join(', ') + '?' : '');
         return;
       }
       fine2.textContent = 'Answered inside this file. Nothing sent.';
-      var a = offline(found.id, dir);
+      var a = offline(hit.id, dir);
       show(a, dir === 'trace' ? traceText(a) : breaksText(a));
+    }
+    form.addEventListener('submit', function(ev){
+      ev.preventDefault();
+      var target = document.getElementById('q').value.trim();
+      if (target) askOffline(target, document.getElementById('dir').value);
     });
   }
 
@@ -355,8 +414,8 @@
   var dir0 = params.get('dir') === 'trace' ? 'trace' : 'breaks';
   var linked = (G && asked) ? resolveTarget(index, asked) : null;
   if (L){
-    home();
-    if (asked){ document.getElementById('q').value = asked; document.getElementById('dir').value = dir0; ask(asked, dir0); }
+    route(params);
+    window.addEventListener('popstate', function(){ route(new URLSearchParams(location.search)); });
   } else if (linked && linked.id){
     document.getElementById('q').value = asked; document.getElementById('dir').value = dir0;
     var a0 = offline(linked.id, dir0);