crewforth 3.2.0-rc.2 → 3.2.0-rc.4

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);

package/kit/studio/web/qr.js

@@ -0,0 +1,200 @@
+// qr.js — a QR code for a viewer's link, made in the page: no dependency, no request.
+//
+// Byte mode, error correction level M (a phone reads it off a laptop screen at an angle), versions 1 to 10: up to
+// 213 bytes, which a Wi-Fi link with a token (about 70) fits in with room to spare. The construction is ISO/IEC
+// 18004's, in the order Project Nayuki's reference implementation lays it out: data and padding, Reed–Solomon error
+// correction per block, interleaving, the function patterns, the codewords in their zigzag, the eight masks scored by
+// the standard's four penalty rules, and the format (and, from version 7, version) bits. Checked against an
+// independent decoder (OpenCV's QRCodeDetector) on every version and mask; the self-check pins the result.
+
+const ECC_M = { perBlock: [-1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26], blocks: [-1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5], formatBits: 0 };
+const MAX_VERSION = 10;
+
+function rawModules(ver) {
+  let n = (16 * ver + 128) * ver + 64;
+  if (ver >= 2) {
+    const align = Math.floor(ver / 7) + 2;
+    n -= (25 * align - 10) * align - 55;
+    if (ver >= 7) n -= 36;
+  }
+  return n;
+}
+const dataCodewords = (ver) => Math.floor(rawModules(ver) / 8) - ECC_M.perBlock[ver] * ECC_M.blocks[ver];
+
+// GF(256) with the QR polynomial x^8 + x^4 + x^3 + x^2 + 1.
+function mul(x, y) {
+  let z = 0;
+  for (let i = 7; i >= 0; i--) { z = (z << 1) ^ ((z >>> 7) * 0x11d); z ^= ((y >>> i) & 1) * x; }
+  return z & 0xff;
+}
+function divisor(degree) {
+  const r = new Array(degree).fill(0); r[degree - 1] = 1;
+  let root = 1;
+  for (let i = 0; i < degree; i++) {
+    for (let j = 0; j < r.length; j++) { r[j] = mul(r[j], root); if (j + 1 < r.length) r[j] ^= r[j + 1]; }
+    root = mul(root, 0x02);
+  }
+  return r;
+}
+function remainder(data, div) {
+  const r = div.map(() => 0);
+  for (const b of data) {
+    const f = b ^ r.shift(); r.push(0);
+    div.forEach((c, i) => { r[i] ^= mul(c, f); });
+  }
+  return r;
+}
+
+function alignmentPositions(ver) {
+  if (ver === 1) return [];
+  const n = Math.floor(ver / 7) + 2;
+  const size = ver * 4 + 17;
+  const step = Math.ceil((ver * 4 + 4) / (n * 2 - 2)) * 2;
+  const out = [6];
+  for (let pos = size - 7; out.length < n; pos -= step) out.splice(1, 0, pos);
+  return out;
+}
+
+/** The bytes of `text` (UTF-8) as the codewords of the smallest version that holds them, error correction included. */
+function codewords(bytes) {
+  let ver = 1;
+  for (; ver <= MAX_VERSION; ver++) {
+    const cap = dataCodewords(ver) * 8;
+    if (4 + (ver < 10 ? 8 : 16) + bytes.length * 8 <= cap) break;
+  }
+  if (ver > MAX_VERSION) throw new Error(`qr: ${bytes.length} bytes do not fit version ${MAX_VERSION}`);
+  const bits = [];
+  const put = (v, n) => { for (let i = n - 1; i >= 0; i--) bits.push((v >>> i) & 1); };
+  put(0b0100, 4); put(bytes.length, ver < 10 ? 8 : 16);
+  for (const b of bytes) put(b, 8);
+  const cap = dataCodewords(ver) * 8;
+  put(0, Math.min(4, cap - bits.length));
+  put(0, (8 - (bits.length % 8)) % 8);
+  for (let pad = 0xec; bits.length < cap; pad ^= 0xec ^ 0x11) put(pad, 8);
+  const data = [];
+  for (let i = 0; i < bits.length; i += 8) data.push(bits.slice(i, i + 8).reduce((a, b) => (a << 1) | b, 0));
+
+  const nBlocks = ECC_M.blocks[ver]; const eccLen = ECC_M.perBlock[ver];
+  const raw = Math.floor(rawModules(ver) / 8);
+  const nShort = nBlocks - (raw % nBlocks); const shortLen = Math.floor(raw / nBlocks);
+  const div = divisor(eccLen);
+  const blocks = [];
+  for (let i = 0, k = 0; i < nBlocks; i++) {
+    const d = data.slice(k, k + shortLen - eccLen + (i < nShort ? 0 : 1)); k += d.length;
+    const e = remainder(d, div);
+    if (i < nShort) d.push(0);                   // a placeholder, skipped when interleaving
+    blocks.push(d.concat(e));
+  }
+  const out = [];
+  for (let i = 0; i < blocks[0].length; i++) {
+    blocks.forEach((b, j) => { if (i !== shortLen - eccLen || j >= nShort) out.push(b[i]); });
+  }
+  return { ver, out };
+}
+
+const MASKS = [
+  (x, y) => (x + y) % 2 === 0, (x, y) => y % 2 === 0, (x) => x % 3 === 0, (x, y) => (x + y) % 3 === 0,
+  (x, y) => (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0, (x, y) => ((x * y) % 2) + ((x * y) % 3) === 0,
+  (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 === 0, (x, y) => (((x + y) % 2) + ((x * y) % 3)) % 2 === 0,
+];
+
+/**
+ * The QR code for `text`: { size, modules } where modules[y][x] is true for a dark module, quiet zone not included.
+ * `mask` forces one of the eight masks (the self-check reads every one); otherwise the one the penalty rules pick.
+ */
+export function qr(text, { mask = null } = {}) {
+  const bytes = [...new TextEncoder().encode(String(text))];
+  const { ver, out } = codewords(bytes);
+  const size = ver * 4 + 17;
+  const m = Array.from({ length: size }, () => new Array(size).fill(false));
+  const fn = Array.from({ length: size }, () => new Array(size).fill(false));
+  const set = (x, y, dark) => { m[y][x] = dark; fn[y][x] = true; };
+
+  for (let i = 0; i < size; i++) { set(6, i, i % 2 === 0); set(i, 6, i % 2 === 0); }
+  for (const [cx, cy] of [[3, 3], [size - 4, 3], [3, size - 4]]) {
+    for (let dy = -4; dy <= 4; dy++) for (let dx = -4; dx <= 4; dx++) {
+      const x = cx + dx; const y = cy + dy;
+      if (x >= 0 && x < size && y >= 0 && y < size) { const d = Math.max(Math.abs(dx), Math.abs(dy)); set(x, y, d !== 2 && d !== 4); }
+    }
+  }
+  const al = alignmentPositions(ver);
+  al.forEach((ax, i) => al.forEach((ay, j) => {
+    if ((i === 0 && j === 0) || (i === 0 && j === al.length - 1) || (i === al.length - 1 && j === 0)) return;
+    for (let dy = -2; dy <= 2; dy++) for (let dx = -2; dx <= 2; dx++) set(ax + dx, ay + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1);
+  }));
+  const format = (mk) => {
+    const d = (ECC_M.formatBits << 3) | mk;
+    let r = d; for (let i = 0; i < 10; i++) r = (r << 1) ^ ((r >>> 9) * 0x537);
+    const b = ((d << 10) | r) ^ 0x5412; const bit = (i) => ((b >>> i) & 1) === 1;
+    for (let i = 0; i <= 5; i++) set(8, i, bit(i));
+    set(8, 7, bit(6)); set(8, 8, bit(7)); set(7, 8, bit(8));
+    for (let i = 9; i < 15; i++) set(14 - i, 8, bit(i));
+    for (let i = 0; i < 8; i++) set(size - 1 - i, 8, bit(i));
+    for (let i = 8; i < 15; i++) set(8, size - 15 + i, bit(i));
+    set(8, size - 8, true);
+  };
+  format(0);                                       // reserves the format area before the data is drawn
+  if (ver >= 7) {
+    let r = ver; for (let i = 0; i < 12; i++) r = (r << 1) ^ ((r >>> 11) * 0x1f25);
+    const b = (ver << 12) | r;
+    for (let i = 0; i < 18; i++) { const dark = ((b >>> i) & 1) === 1; const a = size - 11 + (i % 3); const c = Math.floor(i / 3); set(a, c, dark); set(c, a, dark); }
+  }
+
+  let i = 0;
+  for (let right = size - 1; right >= 1; right -= 2) {
+    if (right === 6) right = 5;
+    for (let v = 0; v < size; v++) for (let j = 0; j < 2; j++) {
+      const x = right - j; const up = ((right + 1) & 2) === 0; const y = up ? size - 1 - v : v;
+      if (!fn[y][x] && i < out.length * 8) { m[y][x] = ((out[i >>> 3] >>> (7 - (i & 7))) & 1) === 1; i++; }
+    }
+  }
+
+  const apply = (mk) => { for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) if (!fn[y][x] && MASKS[mk](x, y)) m[y][x] = !m[y][x]; };
+  let chosen = mask;
+  if (chosen === null) {
+    let best = Infinity;
+    for (let mk = 0; mk < 8; mk++) {
+      apply(mk); format(mk);
+      const p = penalty(m, size);
+      if (p < best) { best = p; chosen = mk; }
+      apply(mk);
+    }
+  }
+  apply(chosen); format(chosen);
+  return { size, version: ver, mask: chosen, modules: m };
+}
+
+// The standard's four penalty rules: runs of five or more, 2x2 blocks, finder-like patterns, dark/light balance.
+function penalty(m, size) {
+  let p = 0;
+  const line = (get) => {
+    let run = 0; let prev = null; const hist = [];
+    for (let i = 0; i < size; i++) {
+      const c = get(i);
+      if (c === prev) { run++; if (run === 5) p += 3; else if (run > 5) p += 1; } else { run = 1; prev = c; }
+      hist.push(c ? 1 : 0);
+    }
+    const s = hist.join('');
+    for (const pat of ['10111010000', '00001011101']) { let k = s.indexOf(pat); while (k !== -1) { p += 40; k = s.indexOf(pat, k + 1); } }
+  };
+  for (let y = 0; y < size; y++) line((x) => m[y][x]);
+  for (let x = 0; x < size; x++) line((y) => m[y][x]);
+  let dark = 0;
+  for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+    if (m[y][x]) dark++;
+    if (x < size - 1 && y < size - 1 && m[y][x] === m[y][x + 1] && m[y][x] === m[y + 1][x] && m[y][x] === m[y + 1][x + 1]) p += 3;
+  }
+  const total = size * size;
+  p += Math.floor(Math.abs(dark * 20 - total * 10) / total) * 10;
+  return p;
+}
+
+/** The code as an SVG string: one path and a quiet zone of four modules. Its two colours are tokens.css's
+ *  --qr-dark and --qr-light, the same in both themes: a camera reads contrast, not the palette. */
+export function qrSvg(text, { px = 4 } = {}) {
+  const { size, modules } = qr(text);
+  const q = 4; const n = size + q * 2;
+  let d = '';
+  for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) if (modules[y][x]) d += `M${x + q} ${y + q}h1v1h-1z`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${n} ${n}" width="${n * px}" height="${n * px}" shape-rendering="crispEdges" role="img" aria-label="QR code of the viewer link"><rect class="qr-light" width="${n}" height="${n}"/><path class="qr-dark" d="${d}"/></svg>`;
+}

package/kit/studio/web/style.css

@@ -417,6 +417,19 @@ mark { background: color-mix(in srgb, var(--studio-accent) 30%, transparent); co
 .rv-give .rv-say { padding: 0; }
 .rv-url { font-size: 12px; line-height: 16px; overflow-wrap: anywhere; user-select: all; color: var(--ink); }
 .rv-acts { display: flex; gap: var(--space-2); }
+/* The QR code is dark on white whatever the theme: a phone's camera reads contrast, not the palette. */
+.rv-qr { align-self: center; line-height: 0; border-radius: var(--radius-md); overflow: hidden; }
+.rv-qr svg { display: block; width: 168px; height: auto; max-width: 100%; }
+.rv-qr .qr-light { fill: var(--qr-light); }
+.rv-qr .qr-dark { fill: var(--qr-dark); }
+.rv-opt { display: flex; align-items: center; gap: var(--space-1); padding: var(--space-1); font-size: 12px; color: var(--ink-dim); }
+/* A viewer link past its eight hours: the page is covered, with what happened and what to do. */
+.expired {
+  position: fixed; inset: 0; z-index: 100; display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: var(--space-2); padding: var(--space-4); text-align: center; background: var(--surface); color: var(--ink);
+}
+.expired h1 { margin: 0; font-size: 20px; }
+.expired p { margin: 0; max-width: 34ch; color: var(--ink-dim); }
 /* A viewer's page offers no way to start a session: the server refuses it, and a button that only fails is noise. */
 body[data-role="viewer"] #new-session { display: none; }
 
@@ -666,6 +679,25 @@ body[data-role="viewer"] #new-session { display: none; }
 .mp-cite:hover { color: var(--ink); text-decoration: underline; }
 .mp-pill[data-tone="model"] { color: var(--studio-accent); background: color-mix(in srgb, var(--studio-accent) 14%, transparent); }
 /* A phone shows the findings and a list of the modules in place of the pane (spec §11). */
+/* CM3: a module card names itself in full (the kind line gives way), carries what it is built with, and folds the
+   outside services it calls into one line under it. A search dims what it does not name; the tour sits over the
+   bottom of the pane. */
+.mp-mod { gap: 6px; }
+.mp-mod .mp-row .mp-name { flex: none; overflow: visible; }
+.mp-mod .mp-row .mp-kind { flex: 0 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.mp-fold { font-family: var(--font-mono); font-size: 12px; color: var(--ink-dim); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.mp-fold.none { color: var(--ink-faint); }
+.mp-card[data-match="false"] { opacity: 0.3; }
+.mp-card[data-match="true"] { border-color: var(--studio-accent); }
+.mp-search { height: 30px; min-width: 200px; padding: 0 10px; border-radius: var(--radius-md); border: 1px solid var(--line); background: var(--surface); color: var(--ink); font: inherit; font-size: 12px; }
+.mp-search::placeholder { color: var(--ink-dim); }
+.mp-tour { position: absolute; left: 16px; right: 16px; bottom: 14px; z-index: 6; padding: 10px 12px; display: flex; flex-direction: column; gap: 6px; border: 1px solid var(--studio-accent); border-radius: var(--radius-md); background: var(--surface-raised); cursor: default; }
+.mp-tour p { margin: 0; font-size: 14px; line-height: 21px; }
+.mp-tour[hidden] { display: none; }
+.mp-inside { flex-direction: row; align-items: center; gap: 10px; }
+.mp-inside .mp-ev { margin-left: auto; }
+.mp-inside .mp-cite, .mp-inside .mp-file { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.mp-inside .mp-ev:last-child { flex: none; }
 .mp-modlist { display: none; flex-direction: column; gap: 2px; padding: 10px 14px; border-top: 1px solid var(--line); }
 .mp-mrow { display: flex; align-items: center; gap: 8px; min-height: 36px; padding: 0 8px; border: 0; border-radius: var(--radius-md); background: transparent; color: var(--ink); font: inherit; text-align: left; cursor: pointer; }
 .mp-mrow:hover { background: var(--surface-raised); }
@@ -1210,6 +1242,8 @@ button.tl-lab { cursor: pointer; }
    and do not shrink. */
 .cv-sub { font-size: 12px; line-height: 16px; color: var(--ink-dim); white-space: nowrap; flex: 0 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
 .cv-sub[hidden] { display: none; }
+/* Agent calls the model gate refused: no agent started, so this line is the only trace on the canvas. */
+.cv-refused { color: var(--status-waiting); }
 .cv-node > .cv-row, .cv-node > .cv-under, .cv-node > .cv-name, .cv-node > .cv-sub { max-width: 100%; }
 .cv-word { font-size: 11px; color: var(--ink-dim); white-space: nowrap; flex: none; }
 

package/kit/studio/web/tokens.css

@@ -10,6 +10,8 @@
   --ink: #e6e9f0;
   --ink-dim: #9aa7cc;
   --ink-faint: #5c6472;
+  --qr-dark: #000000;
+  --qr-light: #ffffff;
   --accent: #A78BFA;
   --on-accent: #0B1020;
   --wordmark-ink: #FFFFFF;
@@ -86,6 +88,8 @@
     --ink: #1a1d24;
     --ink-dim: #5c6472;
     --ink-faint: #8d95a3;
+    --qr-dark: #000000;
+    --qr-light: #ffffff;
     --accent: #6D28D9;
     --on-accent: #ffffff;
     --wordmark-ink: #0F172A;
@@ -113,6 +117,8 @@
   --ink: #1a1d24;
   --ink-dim: #5c6472;
   --ink-faint: #8d95a3;
+  --qr-dark: #000000;
+  --qr-light: #ffffff;
   --accent: #6D28D9;
   --on-accent: #ffffff;
   --wordmark-ink: #0F172A;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewforth",
-  "version": "3.2.0-rc.2",
+  "version": "3.2.0-rc.4",
   "description": "Crewforth — your engineering crew for Claude Code: agents, skills and tool-level gates, in any stack.",
   "bin": {
     "crewforth": "bin/cli.js"