crewforth 3.2.0-rc.1 → 3.2.0-rc.3

package/kit/studio/web/chat.js

@@ -48,10 +48,76 @@ export function quickReplies(text) {
   return (opts.length >= 2 && opts.length <= 5 && /\?/.test(text)) ? opts : [];
 }
 
+/* ============================================== every open conversation === */
+
+/**
+ * One connection for every open conversation. A pane per EventSource reached the browser's six connections to a
+ * host at five panes beside the page's own stream, and from there a message sent and every request the page made
+ * waited for a pane to close (measured on Windows). The panes register here; the stream is opened again, with
+ * each session's last event number, whenever the set changes or the connection drops, so nothing is replayed
+ * twice and nothing is missed.
+ */
+export class OwnedStream {
+  constructor(api, { EventSourceImpl = globalThis.EventSource, retryMs = 1500 } = {}) {
+    this.api = api;
+    this.ES = EventSourceImpl;
+    this.retryMs = retryMs;
+    this.panes = new Map();     // session id -> pane
+    this.seq = new Map();       // session id -> the last event number taken
+    this.source = null;
+    this.timer = null;
+  }
+
+  attach(pane) { this.panes.set(pane.id, pane); this.#soon(0); }
+
+  detach(pane) {
+    if (this.panes.get(pane.id) !== pane) return;
+    this.panes.delete(pane.id); this.seq.delete(pane.id); this.#soon(0);
+  }
+
+  /** The URL the stream is opened at now: what a reconnect resumes from. */
+  url() {
+    const ids = [...this.panes.keys()];
+    const after = ids.map((id) => `${id}:${this.seq.get(id) ?? 0}`).join(',');
+    return this.api(`/api/owned-events?ids=${encodeURIComponent(ids.join(','))}&after=${encodeURIComponent(after)}`);
+  }
+
+  // Panes opened together (a page restoring its tabs) cost one reconnect, not one each.
+  #soon(ms) { clearTimeout(this.timer); this.timer = setTimeout(() => this.#open(), ms); }
+
+  #open() {
+    if (this.source) { this.source.close(); this.source = null; }
+    if (!this.panes.size) return;
+    const src = new this.ES(this.url());
+    const data = (e) => { try { return JSON.parse(e.data); } catch { return null; } };
+    src.addEventListener('state', (e) => { const d = data(e); if (d) this.panes.get(d.id)?.takeState(d.session); });
+    src.addEventListener('event', (e) => {
+      const d = data(e); const pane = d && this.panes.get(d.id);
+      if (!pane || !d.ev) return;
+      if (Number.isFinite(d.ev.seq)) {
+        if (d.ev.seq <= (this.seq.get(d.id) ?? 0)) return;    // already taken before a reconnect
+        this.seq.set(d.id, d.ev.seq);
+      }
+      pane.takeEvent(d.ev);
+    });
+    src.addEventListener('gone', (e) => { const d = data(e); if (d) this.panes.get(d.id)?.streamLost(); });
+    // The browser would reconnect at the same URL, from the same event numbers, and replay what was taken since.
+    // So the stream is closed and opened again here, from where each session is now.
+    src.onerror = () => {
+      if (this.source !== src) return;
+      for (const pane of this.panes.values()) pane.streamLost();
+      this.#soon(this.retryMs);
+    };
+    this.source = src;
+  }
+
+  close() { clearTimeout(this.timer); if (this.source) { this.source.close(); this.source = null; } this.panes.clear(); this.seq.clear(); }
+}
+
 /* ========================================================== one session === */
 
 class Pane {
-  constructor(session, { api, headers, onChange, onPermissions, hooks = {}, readOnly = false }) {
+  constructor(session, { api, headers, onChange, onPermissions, hub = null, hooks = {}, readOnly = false }) {
     this.api = api;
     this.headers = headers;
     this.onChange = onChange;
@@ -62,7 +128,8 @@ class Pane {
     this.readOnly = readOnly;
     this.session = session;
     this.id = session.sessionId;
-    this.source = null;
+    this.hub = hub;
+    this.connected = false;
     this.messages = [];
     this.streaming = null;
     this.permissions = [];
@@ -141,6 +208,7 @@ class Pane {
       this.note(`History not read: ${e.message}`, 'bad');
       return;
     }
+    if (conv?.transcriptsHidden) { this.note('Transcripts are hidden on this link', 'muted'); return; }
     if (conv?.measured === false) { this.note(`History not measured — ${conv.reason}`, 'bad'); return; }
 
     const frag = document.createDocumentFragment();
@@ -163,25 +231,22 @@ class Pane {
   }
 
   connect() {
-    if (this.source) return;
-    this.source = new EventSource(this.api(`/api/owned/${encodeURIComponent(this.id)}/events`));
-    this.source.addEventListener('state', (e) => {
-      try { this.session = JSON.parse(e.data); } catch { return; }
-      this.paintState();
-      this.onChange(this);
-    });
-    this.source.addEventListener('event', (e) => {
-      let ev;
-      try { ev = JSON.parse(e.data); } catch { return; }
-      this.absorb(ev.rec);
-    });
-    this.source.onerror = () => { this.streamBroken = true; this.onChange(this); };
+    if (this.connected || !this.hub) return;
+    this.connected = true;
+    this.hub.attach(this);
   }
 
   disconnect() {
-    if (this.source) { this.source.close(); this.source = null; }
+    if (!this.connected) return;
+    this.connected = false;
+    this.hub.detach(this);
   }
 
+  // What the shared stream hands this pane.
+  takeState(session) { if (!session) return; this.session = session; this.streamBroken = false; this.paintState(); this.onChange(this); }
+  takeEvent(ev) { this.streamBroken = false; this.absorb(ev.rec); }
+  streamLost() { this.streamBroken = true; this.onChange(this); }
+
   /* --------------------------------------------------------- ingestion */
 
   absorb(rec) {
@@ -495,9 +560,12 @@ class Pane {
     cont.type = 'button';
     cont.addEventListener('click', () => this.hooks.onContinue?.(this, cont));
     const contRow = el('div', 'chat-ro-row');
-    contRow.append(cont, el('span', 'sub',
-      'Continues it in Studio. If it is still open somewhere else, Studio starts a copy instead: '
-      + 'the original does not see this, and messages here never reach your terminal.'));
+    // Said before the press, from the server's own check (the one Continue here acts on): the same session, or a copy.
+    // Until the server answers, and if it cannot: the sentence true of both outcomes.
+    const FALLBACK = 'Continues it in Studio. If it is still open somewhere else, Studio starts a copy instead: '
+      + 'the original does not see this, and messages here never reach your terminal.';
+    const contText = el('span', 'sub', FALLBACK);
+    contRow.append(cont, contText);
 
     const term = el('button', 'btn sm', 'Open in terminal');
     term.type = 'button';
@@ -508,13 +576,34 @@ class Pane {
     const termRow = el('div', 'chat-ro-row');
     termRow.append(term, termText);
 
-    this.roEl.replaceChildren(lead, contRow, termRow);
+    // Back to the desktop app: the command, to copy and run where the app is.
+    const deskLine = el('code', 'chat-ro-cmd');
+    const deskCopy = el('button', 'btn sm', 'Copy');
+    deskCopy.type = 'button';
+    deskCopy.addEventListener('click', () => { if (deskLine.dataset.cmd) navigator.clipboard?.writeText(deskLine.dataset.cmd).then(() => { deskCopy.textContent = 'Copied'; }, () => {}); });
+    const deskText = el('span', 'sub');
+    deskText.append('Open it in the desktop app again: ', deskLine);
+    const deskRow = el('div', 'chat-ro-row');
+    deskRow.append(deskCopy, deskText);
+
+    this.roEl.replaceChildren(lead, contRow, termRow, deskRow);
 
-    // The command is the server's, read before anything runs. One that could not be worked out is said so.
+    // The commands are the server's, read before anything runs. One that could not be worked out is said so.
     fetch(this.api(`/api/session/${encodeURIComponent(this.id)}/terminal`), { cache: 'no-store' })
       .then((r) => r.json())
-      .then((r) => { line.textContent = r?.plan?.line ?? 'not measured — no working directory recorded'; })
-      .catch((e) => { line.textContent = `not read — ${e.message}`; });
+      .then((r) => {
+        line.textContent = r?.plan?.line ?? 'not measured — no working directory or session id recorded';
+        // On Windows the command is a PowerShell line (no one line works in cmd and PowerShell 5.1 both): say so.
+        deskLine.textContent = r?.desktop?.line ?? 'not measured — no working directory or session id recorded';
+        if (r?.desktop?.line) deskLine.dataset.cmd = r.desktop.line; else deskCopy.disabled = true;
+        if (r?.desktop?.shell === 'PowerShell') deskText.append(' (in PowerShell)');
+        contText.textContent = r?.continueAs === 'same'
+          ? 'Continues this same session in Studio: its id and history stay, and the desktop app or a terminal that opens it later sees what you add here. Nothing else has it open now.'
+          : r?.continueAs === 'copy'
+            ? 'It is open somewhere else right now, so Studio starts a copy: the original does not see this, and messages here never reach your terminal or the desktop app.'
+            : FALLBACK;
+      })
+      .catch((e) => { line.textContent = `not read — ${e.message}`; deskLine.textContent = `not read — ${e.message}`; deskCopy.disabled = true; });
   }
 
   paintState() {
@@ -591,6 +680,7 @@ export class Chat {
     this.headers = headers;
     this.hooks = hooks;
     this.panes = new Map();
+    this.hub = new OwnedStream(api);
     this.activeId = null;
     this.onActivate = () => {};
     // (pane, { pending }) — a session's waiting requests changed.
@@ -654,7 +744,7 @@ export class Chat {
     }
     if (!pane) {
       pane = new Pane(session, {
-        api: this.api, headers: this.headers, hooks: this.hooks, onChange: () => this.paintTabs(),
+        api: this.api, headers: this.headers, hooks: this.hooks, onChange: () => this.paintTabs(), hub: this.hub,
         onPermissions: (p, rec) => this.onPermissions(p, rec),
       });
       this.panesEl.append(pane.root);

package/kit/studio/web/graph-plan.js

@@ -276,8 +276,9 @@ export function tallestFor(paneHeight) {
   return Math.max(AUTO.tallest, fits);
 }
 
-/** A session's card: one line taller while it has commands running in the background, and never wider. */
-export const sessionHeight = (n) => SIZE.session.h + (n?.backgroundNow?.length ? SIZE.session.line : 0);
+/** A session's card: one line taller for commands running in the background, one for refused agent calls. */
+export const sessionHeight = (n) => SIZE.session.h + (n?.backgroundNow?.length ? SIZE.session.line : 0)
+  + (n?.refusedCalls?.length ? SIZE.session.line : 0);
 
 /* ----------------------------------------------------------------- plan --- */
 

package/kit/studio/web/liveness.js

@@ -64,3 +64,17 @@ function clock(ms) {
   const two = (n) => String(n).padStart(2, '0');
   return `${two(d.getHours())}:${two(d.getMinutes())}`;
 }
+
+/**
+ * Is the server older than the files it serves? The page is read from disk on every load; the server keeps the
+ * code it started with. After an update the two disagree, and a view the old server has no route for answered
+ * 404 (seen as "Not read — HTTP 404" on the Map view). /api/health says `code.changed` when the server's files
+ * changed since it started; a server with no `code` at all predates the field, and is older than this page.
+ * Returns the sentence to show, or null.
+ */
+export const RESTART_NOTE = 'Studio was updated after this server started, so it is running the old code. Restart it: stop it where it runs (Ctrl-C), then /crew-studio.';
+export function staleServerNote(health) {
+  if (!health || typeof health !== 'object') return null;
+  if (!health.code || typeof health.code !== 'object') return RESTART_NOTE;
+  return health.code.changed === true ? RESTART_NOTE : null;
+}

package/kit/studio/web/map-plan.js

@@ -1,14 +1,24 @@
 // What the Map view draws, worked out from a crew map. No page in it.
 //
 // The map is Crewforth's (server/lib/crew-map.js reads it). This file puts each node in a band, says which lines
-// a selection lights, orders the findings and words them. It invents no layer: a module whose place the map does
-// not show goes to "Unplaced", and a finding the scanner hides by default stays hidden until asked for.
+// a selection lights, orders the findings and words them. It invents no layer: a module's layer is the one /crew-map
+// wrote for it (citing the lines it rests on); without one, its band is what the scan shows of it, and a module whose
+// place the scan does not show goes to "Unplaced". A finding the scanner hides by default stays hidden until asked.
 
+// The layers /crew-map may write (eval/lib/crew-map/narrative.mjs LAYERS), set between the bands the scan alone
+// gives, so a map with no layer is drawn in the same order as before.
+export const LAYER_KEYS = ['ui', 'api', 'service', 'data', 'infra', 'tool', 'library'];
 export const BANDS = [
+  ['ui', 'UI'],
   ['clients', 'Clients'],
+  ['api', 'API'],
   ['entry', 'Entry points'],
+  ['service', 'Service'],
   ['core', 'Core'],
+  ['data', 'Data'],
   ['infra', 'Infrastructure'],
+  ['library', 'Library'],
+  ['tool', 'Tools'],
   ['external', 'External'],
   ['unplaced', 'Unplaced'],
 ];
@@ -37,8 +47,10 @@ export function findingModules(f, modules) {
  *   one that only calls endpoints → Clients
  *   one another module of this project references → Core · one with an entry point and nothing above → Entry points
  *   anything else → Unplaced, so a guess is never drawn as a fact.
+ * A module /crew-map gave a layer goes to that layer's band first.
  */
 export function bandOf(node, doc) {
+  if (node.kind === 'module' && LAYER_KEYS.includes(node.narrative?.layer)) return node.narrative.layer;
   if (node.kind === 'external') return 'external';
   if (node.kind === 'service') return 'infra';
   if (node.kind === 'client') return 'clients';
@@ -201,6 +213,52 @@ export function cardSub(node, doc) {
   return [tech || node.stack, provided ? `${provided} ${provided === 1 ? 'endpoint' : 'endpoints'}` : null].filter(Boolean).join(' · ');
 }
 
+/**
+ * What a module's card says, as the Map draws it: a kind line (its domain, else its stack, and how many endpoints it
+ * provides), up to three of what it is built with, and the outside services it calls, folded into one line under it.
+ */
+export const CARD_CHIPS = 3;
+export function cardOf(node, doc) {
+  const provided = (doc.provides?.endpoints ?? []).filter((e) => e.module === node.id).length;
+  const kind = [node.narrative?.domain ?? node.stack ?? null, provided ? `${provided} ${provided === 1 ? 'endpoint' : 'endpoints'}` : null].filter(Boolean).join(' · ');
+  const tech = (node.tech ?? []).map((t) => t.replace(/@.*$/, ''));
+  return { kind, chips: tech.slice(0, CARD_CHIPS), more: Math.max(0, tech.length - CARD_CHIPS), outside: outsideOf(node, doc) };
+}
+
+/** The outside services a module calls, by name, in the order they are named: what its card folds under it. */
+export function outsideOf(node, doc) {
+  const byId = new Map((doc.nodes ?? []).map((n) => [n.id, n]));
+  const names = [];
+  for (const e of doc.edges ?? []) {
+    if (e.from !== node.id) continue;
+    const to = byId.get(e.to);
+    if (to?.kind !== 'external') continue;
+    const name = to.label && to.label !== 'unknown' ? to.label : (to.hosts ?? [])[0] ?? to.id.replace(/^ext:[^:]+:/, '');
+    if (!names.includes(name)) names.push(name);
+  }
+  return names.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/** The tour /crew-map wrote, the stops whose node is on this map, each with the node's name. */
+export function tourOf(doc) {
+  const byId = new Map((doc.nodes ?? []).map((n) => [n.id, n]));
+  return (Array.isArray(doc.tour) ? doc.tour : []).filter((s) => s && byId.has(s.node) && typeof s.text === 'string')
+    .map((s) => ({ node: s.node, name: byId.get(s.node).name ?? byId.get(s.node).label ?? s.node, text: s.text, cites: (s.cites ?? []).filter((c) => typeof c === 'string') }));
+}
+
+/**
+ * The nodes a search names: by name, folder, what they are built with, their domain, the folders inside them and
+ * what their README says. Case does not matter; an empty search names none.
+ */
+export function searchOf(query, nodes) {
+  const q = String(query ?? '').trim().toLowerCase();
+  if (!q) return new Set();
+  const hay = (n) => [n.name, n.label, n.path, n.stack, ...(n.tech ?? []), ...(n.hosts ?? []), n.narrative?.domain, n.narrative?.layer,
+    ...(n.structure?.folders ?? []).map((f) => f.folder), ...(n.about?.evidence ?? []).map((e) => e.text)]
+    .filter((x) => typeof x === 'string').join('\n').toLowerCase();
+  return new Set(nodes.filter((n) => hay(n).includes(q)).map((n) => n.id));
+}
+
 /** The summary pills: what the map holds, and how many findings the list shows. */
 export function summaryOf(doc, findings) {
   const n = (k) => (doc.nodes ?? []).filter((x) => x.kind === k).length;
@@ -247,6 +305,16 @@ export function inspectOf(node, doc, edges, findings) {
     narrative: typeof node.narrative?.text === 'string' ? node.narrative.text : null,
     narrativeCites: Array.isArray(node.narrative?.cites) ? node.narrative.cites.filter((c) => typeof c === 'string') : [],
     narrativeNote: 'Not written yet: this map holds no description of the module, only what its files show.',
+    // /crew-map's layer and domain, when it wrote them; the band is the layer's (bandOf).
+    layer: LAYER_KEYS.includes(node.narrative?.layer) ? (BANDS.find(([k]) => k === node.narrative.layer)?.[1] ?? null) : null,
+    domain: typeof node.narrative?.domain === 'string' ? node.narrative.domain : null,
+    // What is inside it: the entry point the scan found, its folders with how many source files each holds, tests apart.
+    inside: node.kind === 'module' ? {
+      entry: node.entryPoint?.evidence?.[0] ? `${node.entryPoint.evidence[0].file}:${node.entryPoint.evidence[0].line}` : (node.entryPoint?.file ?? null),
+      folders: (node.structure?.folders ?? []).map((f) => ({ folder: f.folder, files: f.files })),
+      other: node.structure?.otherFiles ?? 0,
+      tests: node.structure?.testFiles ?? 0,
+    } : null,
     connectsTo: out,
     connections: { out, in: into },
     byKind: Object.entries(byKind).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
@@ -274,7 +342,8 @@ export function emptyNote(data) {
   return null;
 }
 
-export const CARD = { module: [200, 64], service: [200, 64], client: [200, 64], external: [104, 52] };
+// A module card holds its name and kind, a row of what it is built with, and the line of outside services under it.
+export const CARD = { module: [280, 104], service: [280, 104], client: [280, 104], group: [280, 104], external: [104, 52] };
 const GAP_X = 24;
 const GAP_Y = 20;
 const LEFT = 140;      // the band's label sits in this column

package/kit/studio/web/map.js

@@ -1,14 +1,16 @@
 // The Map view: the project as Crewforth's crew map shows it.
 //
-// Bands from the clients down to the external resources, on a pane that pans and zooms like the graph's (the
-// shared viewport.js). Lines are solid where a file proves them, dotted where they are inferred, dashed with their
+// Bands from the layers /crew-map wrote (UI, API, Service, Data, Infrastructure, …), or from what the scan shows
+// where it wrote none, on a pane that pans and zooms like the graph's (the shared viewport.js). A module's card
+// carries what it is built with and folds the outside services it calls into one line under it; a search dims the
+// cards it does not name, and the tour /crew-map wrote steps through the map one stop at a time. Lines are solid where a file proves them, dotted where they are inferred, dashed with their
 // own mark where the model proposed them. A card can be placed by hand and stays placed for that project; modules
 // that share a folder can be folded into one card. Under the pane, the findings; beside it, the inspector. On a
 // phone the pane gives way to the findings and a list of the modules. It reads the map the server sends and writes
 // nothing; what leaves the page is copied text: a finding as a task, or a file:line.
 import {
   nodesOf, edgesOf, edgeKey, litEdges, findingsOf, findingCounts, cardSub, summaryOf, sourceOf, inspectOf, taskOf,
-  emptyNote, layoutOf, pathOf, chipsOf, resourceWord, inferredOnly, groupsOf, foldView, placed, BANDS,
+  emptyNote, layoutOf, pathOf, chipsOf, inferredOnly, groupsOf, foldView, placed, BANDS, cardOf, tourOf, searchOf, resourceWord,
 } from './map-plan.js';
 import { Viewport, draggable, swallowClick } from './viewport.js';
 
@@ -30,6 +32,8 @@ const BAND_ORDER = Object.fromEntries(BANDS.map(([k], i) => [k, i]));
 const BAND_WORD = Object.fromEntries(BANDS);
 
 const LAYERS = [['modules', 'Modules'], ['external', 'External'], ['endpoints', 'Endpoints'], ['findings', 'Findings']];
+// How a line between two modules is named on the map.
+const EDGE_WORD = { references: 'uses', calls: 'calls', builds: 'builds' };
 
 export class MapView {
   /**
@@ -51,6 +55,8 @@ export class MapView {
     this.groupOf = {};
     this.lay = null;
     this.fitted = false;
+    this.query = '';
+    this.tourAt = -1;      // the stop shown, or -1 when the tour is off
     this.root.classList.add('mp');
     this.#build();
   }
@@ -61,8 +67,11 @@ export class MapView {
     this.pane = mk('div', 'mp-canvas-pane');
     this.layer = mk('div', 'mp-canvas');
     this.pane.append(this.layer);
+    this.tourBox = mk('div', 'mp-tour');
+    this.tourBox.hidden = true;
+    this.pane.append(this.tourBox);
     this.vp = new Viewport(this.pane, this.layer, {
-      skip: (t) => Boolean(t.closest?.('.mp-card') || t.closest?.('.mp-group-fold')),
+      skip: (t) => Boolean(t.closest?.('.mp-card') || t.closest?.('.mp-group-fold') || t.closest?.('.mp-tour')),
       onApply: () => this.hooks.onZoom?.(this.vp.view.k),
     });
     this.below = mk('div', 'mp-below');
@@ -90,7 +99,7 @@ export class MapView {
 
   setData(data) {
     if (data?.cwd !== this.data?.cwd) {
-      this.selected = null; this.tab = 'overview'; this.fitted = false; this.layWidth = null;
+      this.selected = null; this.tab = 'overview'; this.fitted = false; this.layWidth = null; this.query = ''; this.tourAt = -1;
       this.#restore(data?.cwd);
     }
     this.data = data;
@@ -109,6 +118,7 @@ export class MapView {
   /** Esc closes the legend first, then lets the selection go. Returns whether it had something to close. */
   escape() {
     if (this.legendOpen) { this.legendOpen = false; this.render(); return true; }
+    if (this.tourAt >= 0) { this.tourAt = -1; this.render(); return true; }
     if (!this.selected) return false;
     this.selected = null; this.render(); return true;
   }
@@ -133,6 +143,14 @@ export class MapView {
     return true;
   }
 
+  /** Step the tour to a stop (clamped), selecting its node and bringing it to the middle; -1 ends it. */
+  tour(at) {
+    const stops = this.data?.doc ? tourOf(this.data.doc) : [];
+    if (at < 0 || !stops.length) { this.tourAt = -1; this.render(); return; }
+    this.tourAt = Math.min(at, stops.length - 1);
+    this.select(stops[this.tourAt].node, { reveal: true });
+  }
+
   toggleGroup(id) {
     if (this.folded.has(id)) this.folded.delete(id); else this.folded.add(id);
     this.#persist();
@@ -155,7 +173,8 @@ export class MapView {
     const counts = this.layers.findings ? findingCounts(findings.shown) : {};
     const allEdges = edgesOf(doc, d.compare);
     const all = nodesOf(doc, d.compare);
-    let nodes = all.filter((n) => (n.kind === 'external' ? this.layers.external : this.layers.modules));
+    // An outside service is not a card: it is named on the line under the cards of the modules that call it.
+    let nodes = all.filter((n) => n.kind !== 'external' && this.layers.modules);
     const groups = groupsOf(nodes);
     this.groupOf = {};
     for (const g of Object.values(groups)) for (const m of g.members) if (this.folded.has(g.id)) this.groupOf[m] = g.id;
@@ -179,6 +198,7 @@ export class MapView {
     const lay = this.lay;
     const shownSel = this.selected ? (lay.pos[this.selected] ? this.selected : this.groupOf[this.selected] ?? null) : null;
     const lit = litEdges(edges, shownSel);
+    const found = searchOf(this.query, nodes);
 
     this.top.replaceChildren(this.#head(doc, findings), this.#toolbar(d), this.#source(d));
 
@@ -220,6 +240,7 @@ export class MapView {
       if (shownSel) path.dataset.lit = String(lit.has(edgeKey(e)));
       lines.append(path);
       const tags = [];
+      if (EDGE_WORD[e.kind] && !e.calls) tags.push(mk('span', 'mp-badge', EDGE_WORD[e.kind]));
       if (e.line === 'model') { const m = mk('span', 'mp-pill', 'model'); m.dataset.tone = 'model'; m.title = 'Proposed by the model, not shown by a file'; tags.push(m); }
       if (e.calls) {
         tags.push(mk('span', 'mp-pill', `${e.calls} ${e.calls === 1 ? 'call' : 'calls'}`));
@@ -233,10 +254,15 @@ export class MapView {
       }
     }
     parts.push(lines, ...labels);
-    for (const n of nodes) parts.push(this.#card(n, doc, lay.pos[n.id], counts[n.id] ?? 0, chips[n.id], edges, shownSel));
+    for (const n of nodes) {
+      const card = this.#card(n, doc, lay.pos[n.id], counts[n.id] ?? 0, chips[n.id], edges, shownSel);
+      if (this.query.trim()) card.dataset.match = String(found.has(n.id));
+      parts.push(card);
+    }
     this.layer.replaceChildren(...parts);
     if (!this.fitted) { this.fitted = true; this.fit(); } else this.vp.apply();
 
+    this.#tourBox(doc);
     this.below.replaceChildren(...(this.layers.findings ? [this.#findings(findings)] : []));
     this.#modList(all, counts);
     const picked = this.selected ? all.find((n) => n.id === this.selected) ?? null : null;
@@ -261,6 +287,26 @@ export class MapView {
       bar.append(b);
     }
     bar.append(mk('span', 'row-fill'));
+    const search = mk('input', 'mp-search');
+    search.type = 'search';
+    search.placeholder = 'Search files and modules';
+    search.setAttribute('aria-label', 'Search files and modules');
+    search.value = this.query;
+    search.addEventListener('input', () => { this.query = search.value; this.render(); this.top.querySelector('.mp-search')?.focus(); });
+    search.addEventListener('keydown', (e) => {
+      if (e.key !== 'Enter') return;
+      const first = [...searchOf(this.query, nodesOf(d.doc, d.compare))][0];
+      if (first) this.select(first, { reveal: true });
+    });
+    bar.append(search);
+    if (tourOf(d.doc).length) {
+      const t = mk('button', 'mp-tog', 'Tour');
+      t.type = 'button';
+      t.setAttribute('aria-pressed', String(this.tourAt >= 0));
+      t.title = 'The stops /crew-map wrote for someone new to the project, in order';
+      t.addEventListener('click', () => this.tour(this.tourAt >= 0 ? -1 : 0));
+      bar.append(t);
+    }
     const pick = mk('select', 'mp-compare');
     pick.setAttribute('aria-label', 'Compare with');
     const none = mk('option', null, d.others?.length ? 'Compare with…' : 'Compare with: no other project has a map');
@@ -322,10 +368,29 @@ export class MapView {
       if (!card.title) card.title = (n.hosts ?? []).join(', ');
     } else {
       const top = mk('span', 'mp-row');
-      top.append(mk('span', 'mp-name', n.name ?? n.id), mk('span', 'row-fill'));
+      const name = mk('span', 'mp-name', n.name ?? n.id);
+      name.title = n.name ?? n.id;
+      top.append(name);
       if (count) { const f = mk('span', 'mp-fb', String(count)); f.title = `${count} ${count === 1 ? 'finding' : 'findings'}`; top.append(f); }
-      const sub = n.kind === 'group' ? `${n.members.length} modules · click to open` : cardSub(n, doc);
-      card.append(top, mk('span', 'sub', sub));
+      top.append(mk('span', 'row-fill'));
+      if (n.kind === 'group') { card.append(top, mk('span', 'sub', `${n.members.length} modules · click to open`)); }
+      else if (n.kind !== 'module') { card.append(top, mk('span', 'sub', cardSub(n, doc))); }
+      else {
+        const c = cardOf(n, doc);
+        if (c.kind) top.append(mk('span', 'mp-kind', c.kind));
+        card.append(top);
+        if (c.chips.length) {
+          const row = mk('span', 'mp-chips');
+          for (const t of c.chips) row.append(mk('span', 'mp-chip', t));
+          if (c.more) { const m = mk('span', 'mp-chip', `+${c.more}`); m.title = (n.tech ?? []).slice(3).map((t) => t.replace(/@.*$/, '')).join(', '); row.append(m); }
+          card.append(row);
+        }
+        if (this.layers.external) {
+          const fold = mk('span', `mp-fold${c.outside.length ? '' : ' none'}`, c.outside.length ? `▸ ${c.outside.join(' · ')}` : 'no outside calls');
+          if (c.outside.length) fold.title = c.outside.join('\n');
+          card.append(fold);
+        }
+      }
       if (chips?.length) { const c = mk('span', 'mp-chips'); for (const t of chips) c.append(mk('span', 'mp-chip', t)); card.append(c); }
     }
     draggable(card, {
@@ -402,6 +467,12 @@ export class MapView {
       close.addEventListener('click', () => this.select(null));
       top.append(mk('span', 'mp-name', v.title), mk('span', 'row-fill'), close);
       parts.push(top);
+      if (v.layer || v.domain) {
+        const pills = mk('div', 'mp-row');
+        if (v.layer) pills.append(mk('span', 'mp-pill', `Layer · ${v.layer}`));
+        if (v.domain) pills.append(mk('span', 'mp-pill', `Domain · ${v.domain}`));
+        parts.push(pills);
+      }
       if (v.path) parts.push(mk('code', 'sub', v.path));
       if (v.chips.length) { const c = mk('div', 'mp-chips'); for (const t of v.chips) c.append(mk('span', 'mp-chip', t)); parts.push(c); }
       const tabs = mk('nav', 'mp-tabs');
@@ -417,6 +488,13 @@ export class MapView {
       if (this.tab === 'overview') {
         sec.append(mk('span', 'lbl', 'What it is for'), mk('p', v.narrative ? null : 'sub', v.narrative ?? v.narrativeNote));
         if (v.narrative && v.narrativeCites.length) sec.append(mk('p', 'sub mp-cites', `From ${v.narrativeCites.join(', ')}`));
+        if (v.inside && (v.inside.entry || v.inside.folders.length)) {
+          sec.append(mk('span', 'lbl', 'Inside'));
+          if (v.inside.entry) { const r = mk('div', 'mp-conn mp-inside'); r.append(this.#cite(v.inside.entry), mk('span', 'mp-ev', 'entry point')); sec.append(r); }
+          for (const f of v.inside.folders) { const r = mk('div', 'mp-conn mp-inside'); r.append(mk('span', 'mp-file', `${f.folder === '.' ? '(root)' : `${f.folder}/`}`), mk('span', 'mp-ev', `${f.files} ${f.files === 1 ? 'file' : 'files'}`)); sec.append(r); }
+          if (v.inside.other) sec.append(mk('p', 'sub', `${v.inside.other} more files in other folders`));
+          if (v.inside.tests) sec.append(mk('p', 'sub', `${v.inside.tests} test ${v.inside.tests === 1 ? 'file' : 'files'}`));
+        }
         sec.append(mk('span', 'lbl', 'Connects to'));
         if (!v.connectsTo.length) sec.append(mk('p', 'sub', 'Nothing on this map.'));
         for (const c of v.connectsTo) sec.append(this.#conn(c));
@@ -459,6 +537,21 @@ export class MapView {
     this.side.replaceChildren(...parts);
   }
 
+  /** The tour's stop, over the bottom of the pane: which of how many, what to look at, and the way on. */
+  #tourBox(doc) {
+    const stops = tourOf(doc);
+    if (this.tourAt < 0 || !stops.length) { this.tourBox.hidden = true; return; }
+    const s = stops[Math.min(this.tourAt, stops.length - 1)];
+    const head = mk('div', 'mp-row');
+    head.append(mk('span', 'lbl', `Tour · ${this.tourAt + 1} of ${stops.length}`), mk('span', 'mp-name', s.name), mk('span', 'row-fill'));
+    const nav = (label, at, off) => { const b = mk('button', 'btn sm ghost', label); b.type = 'button'; b.disabled = off; b.addEventListener('click', () => this.tour(at)); return b; };
+    head.append(nav('Back', this.tourAt - 1, this.tourAt === 0), nav(this.tourAt === stops.length - 1 ? 'Done' : 'Next', this.tourAt === stops.length - 1 ? -1 : this.tourAt + 1, false));
+    const body = [head, mk('p', null, s.text)];
+    if (s.cites.length) body.push(mk('p', 'sub mp-cites', `From ${s.cites.join(', ')}`));
+    this.tourBox.replaceChildren(...body);
+    this.tourBox.hidden = false;
+  }
+
   /** A file:line the viewer can copy. */
   #cite(text) {
     const b = mk('button', 'mp-ev mp-cite', text);