truemap-cli 0.2.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/ui/sdk.js CHANGED
@@ -24,114 +24,142 @@
24
24
  const style = document.createElement('style');
25
25
  style.textContent = `
26
26
  [data-tm-mark="changed"] { outline: 2px dashed var(--tm-changed, #a2690a) !important; outline-offset: 3px; }
27
- [data-tm-mark="broken"] { outline: 2px dashed var(--tm-broken, #b03a2e) !important; outline-offset: 3px; }
27
+ [data-tm-mark="broken"] { outline: 2px dashed var(--tm-broken, #c0392b) !important; outline-offset: 3px; }
28
28
  svg [data-tm-mark] { outline: none !important; }
29
+ .tm-diagram .tm-node[data-tm-mark] { outline: none !important; }
30
+ .tm-diagram .tm-node[data-tm-mark]::before { content: ""; position: absolute; top: 7px; left: -4px; width: 7px; height: 7px; border-radius: 50%; background: var(--tm-changed, #a35f00); box-shadow: 0 0 0 2px var(--tm-paper, #fff); }
31
+ .tm-diagram .tm-node[data-tm-mark="broken"]::before { background: var(--tm-broken, #c0392b); }
29
32
  html[data-tm-annotate] body { cursor: default; }
30
- html[data-tm-annotate] [data-tm-hover] { outline: 1.5px solid var(--tm-route, #2453c4) !important; outline-offset: 3px; cursor: pointer; }
33
+ html[data-tm-annotate] [data-tm-hover] { cursor: pointer; }
31
34
  html[data-tm-annotate] a, html[data-tm-annotate] label { cursor: pointer; }
32
- [data-tm-noted] { outline: 1.5px solid color-mix(in oklab, var(--tm-route, #2453c4) 55%, transparent); outline-offset: 3px; }
33
- [data-tm-active] { outline: 2px solid var(--tm-route, #2453c4) !important; outline-offset: 3px; }
34
- @keyframes tm-flash { 0%,100% { outline-color: transparent } 35% { outline-color: var(--tm-route, #2453c4) } }
35
- [data-tm-flash] { outline: 2px solid var(--tm-route, #2453c4) !important; outline-offset: 4px; animation: tm-flash 1.1s ease 2; }
35
+ @keyframes tm-flash { 0%,100% { outline-color: transparent } 35% { outline-color: var(--tm-route, #141413) } }
36
+ [data-tm-flash] { outline: 2px solid var(--tm-route, #141413) !important; outline-offset: 4px; animation: tm-flash 1.1s ease 2; }
36
37
  @media (prefers-reduced-motion: reduce) { [data-tm-flash] { animation: none; } }
37
- ::highlight(tm-note) { background-color: color-mix(in oklab, var(--tm-route, #2453c4) 20%, transparent); }
38
+ ::highlight(tm-note) { background-color: color-mix(in oklab, var(--tm-route, #141413) 20%, transparent); }
39
+ /* Every box can be opened: click shows its code and connections. */
40
+ .tm-node, .tm-step, [data-src] { cursor: pointer; }
41
+ .tm-node:focus-visible, .tm-step:focus-visible { outline: 2px solid var(--tm-route, #141413); outline-offset: 3px; }
42
+ /* The agent points at the map: everything else steps back. */
43
+ html[data-tm-focusing] .tm-node:not([data-tm-focus]), html[data-tm-focusing] .tm-step:not([data-tm-focus]) { opacity: .34; }
44
+ html[data-tm-focusing] .tm-wire:not(.is-focus), html[data-tm-focusing] .tm-wire-head:not(.is-focus) { opacity: .16; }
45
+ html[data-tm-focusing] .tm-wire-label:not(.is-focus) { opacity: 0; }
46
+ .tm-node, .tm-step, .tm-wire, .tm-wire-head, .tm-wire-label { transition: opacity .18s ease, stroke .12s ease, fill .12s ease; }
47
+ @media (prefers-reduced-motion: reduce) { .tm-node, .tm-step, .tm-wire, .tm-wire-head, .tm-wire-label { transition: none; } }
38
48
  `;
39
49
  (document.head || document.documentElement).appendChild(style);
40
50
 
41
- // ---------- wires: <div class="tm-node" id="orders" data-to="payments payments-db:reads"> ----------
42
- const SVGNS = 'http://www.w3.org/2000/svg';
43
- function drawWires() {
44
- document.documentElement.style.setProperty('--tm-vw', `${document.documentElement.clientWidth}px`);
45
- for (const map of document.querySelectorAll('.tm-map, .tm-blueprint')) {
46
- map.querySelector(':scope > svg.tm-wires')?.remove();
47
- const sources = [...map.querySelectorAll('[data-to]')];
48
- if (!sources.length) continue;
49
- // Coordinates live in the map's scroll space, so wires scroll with the boxes.
50
- const box = map.getBoundingClientRect();
51
- const ox = box.left + map.clientLeft - map.scrollLeft; const oy = box.top + map.clientTop - map.scrollTop;
52
- const w = map.scrollWidth; const h = map.scrollHeight;
53
- const svg = document.createElementNS(SVGNS, 'svg');
54
- svg.setAttribute('class', 'tm-wires'); svg.setAttribute('aria-hidden', 'true');
55
- svg.setAttribute('width', w); svg.setAttribute('height', h);
56
- svg.setAttribute('viewBox', `0 0 ${w} ${h}`);
57
- const rel = (r) => ({ l: r.left - ox, r: r.right - ox, t: r.top - oy, b: r.bottom - oy, cx: (r.left + r.right) / 2 - ox, cy: (r.top + r.bottom) / 2 - oy });
58
- // Collect edges first so wires sharing a box get their own exit, entry and track (no merged lines).
59
- const edges = [];
60
- for (const src of sources) {
61
- for (const spec of src.getAttribute('data-to').split(/\s+/).filter(Boolean)) {
62
- const [id, ...labelParts] = spec.split(':');
63
- const dst = document.getElementById(id);
64
- if (!dst || dst === src || !map.contains(dst)) continue;
65
- edges.push({ src, dst, label: labelParts.join(':').replace(/_/g, ' '), a: rel(src.getBoundingClientRect()), b: rel(dst.getBoundingClientRect()) });
66
- }
67
- }
68
- const down = (e) => e.b.t >= e.a.b - 2;
69
- const slot = (list, e) => { const i = list.indexOf(e); return i - (list.length - 1) / 2; };
70
- const outOf = new Map(); const into = new Map();
71
- for (const e of edges.filter(down)) {
72
- (outOf.get(e.src) || outOf.set(e.src, []).get(e.src)).push(e);
73
- (into.get(e.dst) || into.set(e.dst, []).get(e.dst)).push(e);
74
- }
75
- for (const l of [...outOf.values(), ...into.values()]) l.sort((p, q) => p.b.cx - q.b.cx || p.a.cx - q.a.cx);
76
- for (const e of edges) {
77
- const { src, dst, a, b } = e;
78
- const key = src.classList.contains('is-key') && dst.classList.contains('is-key');
79
- const ext = dst.classList.contains('is-ext') || src.classList.contains('is-ext');
80
- let d; let head; let mid;
81
- const r = 7;
82
- if (down(e)) { // below: leave from the bottom, enter at the top
83
- const so = slot(outOf.get(src), e); const ti = slot(into.get(dst), e);
84
- const sx = a.cx + so * 14; const sy = a.b; const tx = b.cx + ti * 14; const ty = b.t - 6;
85
- const my = sy + Math.max(12, Math.min(22, (ty - sy) / 2)) + ti * 7;
86
- if (Math.abs(tx - sx) < 2) d = `M${sx},${sy} V${ty}`;
87
- else {
88
- const dir = tx > sx ? 1 : -1; const rr = Math.min(r, Math.abs(tx - sx) / 2);
89
- d = `M${sx},${sy} V${my - rr} Q${sx},${my} ${sx + dir * rr},${my} H${tx - dir * rr} Q${tx},${my} ${tx},${my + rr} V${ty}`;
90
- }
91
- head = `M${tx - 4.5},${ty - 1} L${tx + 4.5},${ty - 1} L${tx},${ty + 6} Z`;
92
- // the label sits by the box the wire leaves, so it is clear which wire it names
93
- mid = { x: sx - 2, y: Math.min(sy + 10, my - 6) };
94
- } else if (b.b <= a.t + 2) { // above
95
- const sx = a.cx; const sy = a.t; const tx = b.cx; const ty = b.b + 6;
96
- const my = sy - Math.max(12, Math.min(22, (sy - ty) / 2));
97
- const dir = tx > sx ? 1 : -1;
98
- d = Math.abs(tx - sx) < 2 ? `M${sx},${sy} V${ty}` : `M${sx},${sy} V${my + r} Q${sx},${my} ${sx + dir * r},${my} H${tx - dir * r} Q${tx},${my} ${tx},${my - r} V${ty}`;
99
- head = `M${tx - 4.5},${ty + 1} L${tx + 4.5},${ty + 1} L${tx},${ty - 6} Z`;
100
- mid = { x: tx, y: (my + ty) / 2 };
101
- } else { // same row: side to side
102
- const right = b.l >= a.r;
103
- const sx = right ? a.r : a.l; const tx = right ? b.l - 6 : b.r + 6;
104
- const sy = a.cy; const ty = b.cy; const mx = (sx + tx) / 2;
105
- d = Math.abs(ty - sy) < 2 ? `M${sx},${sy} H${tx}` : `M${sx},${sy} H${mx} V${ty} H${tx}`;
106
- head = right ? `M${tx - 1},${ty - 4.5} L${tx - 1},${ty + 4.5} L${tx + 6},${ty} Z` : `M${tx + 1},${ty - 4.5} L${tx + 1},${ty + 4.5} L${tx - 6},${ty} Z`;
107
- mid = { x: mx, y: ty - 6 };
108
- }
109
- const path = document.createElementNS(SVGNS, 'path');
110
- path.setAttribute('d', d); path.setAttribute('class', `tm-wire${key ? ' is-key' : ''}${ext ? ' is-ext' : ''}`);
111
- const arrow = document.createElementNS(SVGNS, 'path');
112
- arrow.setAttribute('d', head); arrow.setAttribute('class', `tm-wire-head${key ? ' is-key' : ''}`);
113
- svg.appendChild(path);
114
- svg.appendChild(arrow);
115
- if (e.label) {
116
- const t = document.createElementNS(SVGNS, 'text');
117
- t.setAttribute('class', 'tm-wire-label'); t.setAttribute('x', mid.x + 8); t.setAttribute('y', mid.y + 4);
118
- t.textContent = e.label; svg.appendChild(t);
119
- }
51
+ const drawWires = () => { window.truemapDiagram?.draw(); window.truemapWires?.draw(); markWires(); };
52
+ let wireTimer = null;
53
+ const scheduleWires = () => { clearTimeout(wireTimer); wireTimer = setTimeout(() => { drawWires(); placePins(); }, 40); };
54
+
55
+ // ---------- focus: the agent (or a chat link) points at boxes ----------
56
+ let focusSet = []; let focusNote = null; let hotBox = null;
57
+ function findItems(items) {
58
+ const all = [...document.querySelectorAll('[data-src], .tm-node[id], .tm-step[id]')];
59
+ const out = [];
60
+ for (const it of items || []) {
61
+ const s = String(it);
62
+ const el = (/^[\w-]+$/.test(s) && document.getElementById(s))
63
+ || all.find((x) => x.getAttribute('data-src') === s)
64
+ || (!s.includes('#') && all.find((x) => (x.getAttribute('data-src') || '').split('#')[0].replace(/\/$/, '') === s.replace(/\/$/, '')))
65
+ || all.find((x) => (x.getAttribute('data-src') || '').endsWith(`#${s.split('#').pop()}`) && s.includes('#'));
66
+ if (el && !out.includes(el)) out.push(el);
67
+ }
68
+ return out;
69
+ }
70
+ // Classes on wires follow the focused / hovered boxes; re-applied after every redraw.
71
+ function markWires() {
72
+ const ids = new Set(focusSet.map((e) => e.id).filter(Boolean));
73
+ const hot = hotBox?.id;
74
+ for (const w of document.querySelectorAll('.tm-wire, .tm-wire-head')) {
75
+ const { from, to } = w.dataset;
76
+ w.classList.toggle('is-focus', ids.has(from) && ids.has(to));
77
+ w.classList.toggle('is-hot', !!hot && (from === hot || to === hot));
78
+ }
79
+ for (const w of document.querySelectorAll('.tm-dg-edge, .tm-dg-head, .tm-dg-label')) {
80
+ w.classList.toggle('is-focus', ids.has(w.dataset.from) && ids.has(w.dataset.to));
81
+ }
82
+ // labels are placed afresh for what is now visible
83
+ window.truemapWires?.labels?.({ hot: hot || null, focus: [...ids] });
84
+ }
85
+ // Brings elements into view by scrolling the page itself; scrollIntoView would also scroll a map's own
86
+ // clipped box sideways and hide part of it.
87
+ function reveal(els, how = 'center') {
88
+ const rs = els.filter((el) => el.isConnected).map((el) => el.getBoundingClientRect());
89
+ if (!rs.length) return;
90
+ const top = Math.min(...rs.map((r) => r.top)); const bottom = Math.max(...rs.map((r) => r.bottom));
91
+ const smooth = matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth';
92
+ if (how === 'nearest' && top >= 8 && bottom <= innerHeight - 8) return;
93
+ const dy = bottom - top > innerHeight - 80 ? top - 60 : (top + bottom) / 2 - innerHeight / 2;
94
+ window.scrollBy({ top: dy, behavior: smooth });
95
+ }
96
+ function applyFocus(items, note, who, scroll = 'center', transient = false) {
97
+ clearFocus(false);
98
+ for (const btn of document.querySelectorAll('[data-tm-flow]')) btn.setAttribute('aria-pressed', 'false');
99
+ focusSet = findItems(items);
100
+ focusNote = note ? { text: String(note), who: who || 'Agent' } : null;
101
+ if (focusSet.length) {
102
+ document.documentElement.setAttribute('data-tm-focusing', '');
103
+ for (const el of focusSet) el.setAttribute('data-tm-focus', '');
104
+ if (scroll) reveal(focusSet, scroll);
105
+ } else if (focusNote) window.scrollTo({ top: 0 });
106
+ // the page scrolls smoothly to the group: place the note again once it has settled
107
+ markWires(); paintRings(); setTimeout(paintRings, 350); setTimeout(paintRings, 900);
108
+ post({ type: 'focus-state', count: focusSet.length, transient });
109
+ }
110
+ function clearFocus(repaint = true) {
111
+ document.documentElement.removeAttribute('data-tm-focusing');
112
+ for (const el of document.querySelectorAll('[data-tm-focus]')) el.removeAttribute('data-tm-focus');
113
+ if (repaint) for (const btn of document.querySelectorAll('[data-tm-flow]')) btn.setAttribute('aria-pressed', 'false');
114
+ const had = focusSet.length;
115
+ focusSet = []; focusNote = null;
116
+ markWires(); if (repaint) paintRings();
117
+ if (had && repaint) post({ type: 'focus-state', count: 0 });
118
+ }
119
+
120
+ // ---------- peek: click a box to see what it is in the code ----------
121
+ const boxSel = '.tm-node, .tm-step, .tm-card[data-src], [data-src]';
122
+ function boxInfo(el) {
123
+ const txt = (sel) => clean(el.querySelector(sel)?.textContent, 300);
124
+ const nameOf = (n) => clean(n.getAttribute('data-name') || n.querySelector?.('.tm-node-title,b,strong,h3,h4')?.textContent || n.textContent, 60);
125
+ // Same label rules as the map: underscores are spaces, \_ is a real underscore.
126
+ const viaOf = (s) => s.replace(/\\_/g, '\u0001').replace(/_/g, ' ').replace(/\u0001/g, '_');
127
+ const to = [];
128
+ for (const spec of (el.getAttribute('data-to') || '').split(/[\s,]+/).filter(Boolean)) {
129
+ const [id, ...lab] = spec.split(':'); const n = document.getElementById(id);
130
+ if (n) to.push({ id, label: nameOf(n), via: viaOf(lab.join(':')) });
131
+ }
132
+ const from = [];
133
+ if (el.id) {
134
+ for (const n of document.querySelectorAll('[data-to]')) {
135
+ const spec = n.getAttribute('data-to').split(/[\s,]+/).find((x) => x.split(':')[0] === el.id);
136
+ if (spec && n.id) from.push({ id: n.id, label: nameOf(n), via: viaOf(spec.split(':').slice(1).join(':')) });
120
137
  }
121
- // key wires on top, labels above every wire
122
- [...svg.querySelectorAll('.tm-wire.is-key, .tm-wire-head.is-key')].forEach((el) => svg.appendChild(el));
123
- [...svg.querySelectorAll('.tm-wire-label')].forEach((el) => svg.appendChild(el));
124
- map.insertBefore(svg, map.firstChild);
125
- markScroll(map);
126
138
  }
139
+ const href = el.matches('a[href]') ? el.getAttribute('href') : (el.querySelector('a[href$=".html"], a[href*=".html#"]')?.getAttribute('href') || '');
140
+ const det = el.querySelector(':scope > .tm-detail');
141
+ const detail = det ? [...det.querySelectorAll(':scope > p:not(.tm-why), :scope > ul > li, :scope > ol > li')].slice(0, 14).map((n) => ({ t: n.tagName === 'LI' ? 'li' : 'p', text: clean(n.textContent, 500) })) : [];
142
+ return {
143
+ id: el.id || '', label: clean(el.getAttribute('data-name'), 60) || labelOf(el), tag: clean(el.getAttribute('data-tag'), 60), plan: el.getAttribute('data-plan') || '', detail,
144
+ sub: txt('.tm-node-sub'), desc: det ? '' : txt('.tm-node-desc') || (el.matches('.tm-node,.tm-step') ? '' : clean(el.innerText, 300)),
145
+ src: el.closest('[data-src]')?.getAttribute('data-src') || '', href: /^[\w./-]+\.html?(#[\w-]*)?$/i.test(href) ? href : '',
146
+ ext: el.classList.contains('is-ext'), to, from, mark: el.getAttribute('data-tm-mark') || '', planNote: clean(el.getAttribute('data-plan-note'), 400), why: clean(el.getAttribute('data-why') || det?.querySelector('.tm-why')?.textContent, 600),
147
+ };
127
148
  }
128
- // A map wider than the window fades at the edge it can scroll towards.
129
- function markScroll(map) {
130
- map.classList.toggle('tm-scrolls', map.scrollWidth - map.clientWidth - map.scrollLeft > 4);
131
- if (!map.__tmScroll) { map.__tmScroll = true; map.addEventListener('scroll', () => markScroll(map), { passive: true }); }
149
+ let selected = null;
150
+ function select(el) {
151
+ if (selected === el) return;
152
+ selected?.removeAttribute('data-tm-selected');
153
+ selected = el || null; selected?.setAttribute('data-tm-selected', '');
154
+ // the selected box's own lines stay lit while its inspector is open
155
+ for (const w of document.querySelectorAll('.tm-dg-edge, .tm-dg-head, .tm-dg-label')) w.classList.toggle('is-sel', !!el?.id && (w.dataset.from === el.id || w.dataset.to === el.id));
156
+ if (!el && document.activeElement?.matches?.('.tm-node, .tm-step')) document.activeElement.blur();
157
+ }
158
+ function peek(el) {
159
+ select(el);
160
+ const r = el.getBoundingClientRect();
161
+ post({ type: 'peek', page: pagePath(), box: boxInfo(el), rect: { l: r.left, t: r.top, r: r.right, b: r.bottom }, sy: scrollY });
132
162
  }
133
- let wireTimer = null;
134
- const scheduleWires = () => { clearTimeout(wireTimer); wireTimer = setTimeout(() => { drawWires(); placePins(); }, 40); };
135
163
 
136
164
  // ---------- annotate ----------
137
165
  const INTERACTIVE = 'a[href],button,input,select,textarea,label,summary,[contenteditable],[role=button]';
@@ -161,15 +189,86 @@
161
189
  }
162
190
  return parts.join(' > ');
163
191
  }
192
+ let rings = null;
164
193
  function setHover(el) {
165
194
  if (hovered === el) return;
166
195
  hovered?.removeAttribute('data-tm-hover');
167
196
  hovered = el; el?.setAttribute('data-tm-hover', '');
197
+ paintRings();
198
+ }
199
+
200
+ // Highlights are drawn in the top layer, never as CSS outlines, so a scrolling or clipped container
201
+ // can't cut them off. A ring covers the element and everything inside it (a badge that sticks out too).
202
+ function extentOf(el) {
203
+ const r0 = el.getBoundingClientRect();
204
+ let l = r0.left; let t = r0.top; let r = r0.right; let b = r0.bottom;
205
+ const kids = [...el.querySelectorAll('*')].slice(0, 400);
206
+ // Content scrolled out of view inside a scrolling block (a long code line, a map) doesn't count.
207
+ const clips = [el, ...kids].filter((n) => { const s = getComputedStyle(n); return s.overflowX !== 'visible' || s.overflowY !== 'visible'; });
208
+ for (const kid of kids) {
209
+ const k = kid.getBoundingClientRect();
210
+ if (!k.width || !k.height) continue;
211
+ let kl = k.left; let kt = k.top; let kr = k.right; let kb = k.bottom;
212
+ for (const c of clips) {
213
+ if (c === kid || !c.contains(kid)) continue;
214
+ const cr = c.getBoundingClientRect();
215
+ kl = Math.max(kl, cr.left); kt = Math.max(kt, cr.top); kr = Math.min(kr, cr.right); kb = Math.min(kb, cr.bottom);
216
+ }
217
+ if (kr <= kl || kb <= kt) continue;
218
+ l = Math.min(l, kl); t = Math.min(t, kt); r = Math.max(r, kr); b = Math.max(b, kb);
219
+ }
220
+ // An element half scrolled out of its own scrolling parent is cut at that parent's edge too.
221
+ for (let a = el.parentElement; a && a !== document.body; a = a.parentElement) {
222
+ const s = getComputedStyle(a);
223
+ if (s.overflowX === 'visible' && s.overflowY === 'visible') continue;
224
+ const ar = a.getBoundingClientRect();
225
+ l = Math.max(l, ar.left - 2); t = Math.max(t, ar.top - 2); r = Math.min(r, ar.right + 2); b = Math.min(b, ar.bottom + 2);
226
+ }
227
+ return { left: l + scrollX - 4, top: t + scrollY - 4, width: r - l + 8, height: b - t + 8 };
228
+ }
229
+ function paintRings() {
230
+ if (!rings) return;
231
+ rings.innerHTML = '';
232
+ const ring = (el, cls) => {
233
+ if (!el?.isConnected) return;
234
+ mount();
235
+ const x = extentOf(el); const d = document.createElement('div');
236
+ d.className = `ring ${cls}`;
237
+ Object.assign(d.style, { left: `${x.left}px`, top: `${x.top}px`, width: `${x.width}px`, height: `${x.height}px` });
238
+ rings.appendChild(d);
239
+ };
240
+ for (const n of notes.values()) if (n.el && n.el !== card?.target) ring(n.el, 'noted');
241
+ for (const el of focusSet) if (!el.closest('.tm-diagram')) ring(el, 'agent'); // diagram boxes get the highlighter instead
242
+ if (focusNote) {
243
+ mount();
244
+ const b = document.createElement('div'); b.className = 'bubble'; b.setAttribute('role', 'note');
245
+ b.innerHTML = '<div class="bubble-who"></div><div class="bubble-text"></div><button class="bubble-x" type="button" aria-label="Dismiss">×</button>';
246
+ b.querySelector('.bubble-who').textContent = focusNote.who;
247
+ b.querySelector('.bubble-text').textContent = focusNote.text;
248
+ b.querySelector('.bubble-x').onclick = (ev) => { ev.stopPropagation(); clearFocus(); post({ type: 'focus-cleared' }); };
249
+ rings.appendChild(b);
250
+ // The note sits beside the whole lit group (never on one of its boxes): right of it, else below it.
251
+ const vw = document.documentElement.clientWidth; const w = 300;
252
+ const live = focusSet.filter((el) => el.isConnected).map(extentOf);
253
+ if (live.length) {
254
+ const g = { l: Math.min(...live.map((x) => x.left)), t: Math.min(...live.map((x) => x.top)), r: Math.max(...live.map((x) => x.left + x.width)), b: Math.max(...live.map((x) => x.top + x.height)) };
255
+ // right of the group if there is room; otherwise above it (the page's own controls usually sit below
256
+ // a map); below it only when there is no room above.
257
+ const fitsRight = g.r + 14 + w < scrollX + vw - 8;
258
+ const bh = b.offsetHeight || 90;
259
+ const above = g.t - bh - 12 > scrollY + 4;
260
+ b.style.left = `${fitsRight ? g.r + 14 : Math.max(scrollX + 8, Math.min(g.l, scrollX + vw - w - 8))}px`;
261
+ b.style.top = `${fitsRight ? g.t : above ? g.t - bh - 12 : g.b + 12}px`;
262
+ } else { b.style.left = `${scrollX + vw - 320}px`; b.style.top = `${scrollY + 16}px`; }
263
+ }
264
+ if (card?.target) ring(card.target, 'active');
265
+ else if (annotating && hovered) ring(hovered, 'hover');
168
266
  }
169
267
  function setAnnotate(on) {
170
268
  annotating = !!on;
171
269
  document.documentElement.toggleAttribute('data-tm-annotate', annotating);
172
270
  if (!annotating) { setHover(null); }
271
+ paintRings();
173
272
  }
174
273
 
175
274
  // Shadow layer for the comment card, pins and the selection button: page CSS can't touch it.
@@ -180,40 +279,51 @@
180
279
  shadow.innerHTML = `<style>
181
280
  :host { all: initial; }
182
281
  * { box-sizing: border-box; }
183
- .card { position: absolute; width: 340px; background: #fff; color: #17202b; border: 1px solid #c2c8c1; border-radius: 10px;
184
- box-shadow: 0 12px 32px -12px rgba(23,32,43,.28); font: 14px/1.45 "IBM Plex Sans", system-ui, -apple-system, "Segoe UI", sans-serif; padding: 12px; }
282
+ .card { position: absolute; width: 340px; background: #fff; color: #141413; border: 1px solid #d2d2cb; border-radius: 10px;
283
+ box-shadow: 0 12px 32px -12px rgba(20,20,19,.28); font: 14px/1.45 "Instrument Sans", system-ui, -apple-system, "Segoe UI", sans-serif; padding: 12px; }
185
284
  .what { display: flex; align-items: baseline; gap: 8px; min-width: 0; margin: 0 2px 8px; }
186
285
  .what b { font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; }
187
- .what code { font: 11.5px "IBM Plex Mono", ui-monospace, Consolas, monospace; color: #8a939e; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; flex: 1; }
188
- textarea { width: 100%; min-height: 72px; max-height: 220px; resize: none; font: inherit; color: inherit; background: #f6f7f4; border: 1px solid #dde1db; border-radius: 7px; padding: 9px 10px; outline: none; }
189
- textarea:focus { border-color: #2453c4; background: #fff; }
286
+ .what code { font: 11.5px "Commit Mono", ui-monospace, Consolas, monospace; color: #9a9a92; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; flex: 1; }
287
+ textarea { width: 100%; min-height: 72px; max-height: 220px; resize: none; font: inherit; color: inherit; background: #fafaf9; border: 1px solid #e6e6e1; border-radius: 7px; padding: 9px 10px; outline: none; }
288
+ textarea:focus { border-color: #141413; background: #fff; }
190
289
  .suggest { display: flex; flex-wrap: wrap; gap: 4px 14px; margin: 8px 2px 0; }
191
- .suggest button { all: unset; cursor: pointer; font-size: 12.5px; color: #2453c4; }
290
+ .suggest button { all: unset; cursor: pointer; font-size: 12.5px; color: #141413; }
192
291
  .suggest button:hover { text-decoration: underline; text-underline-offset: 3px; }
193
292
  .foot { display: flex; align-items: center; gap: 8px; margin-top: 10px; }
194
- .hint { flex: 1; font-size: 11.5px; color: #8a939e; line-height: 1.3; }
195
- .btn { all: unset; cursor: pointer; font: 500 13px/1 "IBM Plex Sans", system-ui, sans-serif; padding: 8px 11px; border-radius: 6px; color: #5b6573; }
196
- .btn:hover { background: #eef0ec; color: #17202b; }
197
- .btn.primary { background: #2453c4; color: #fff; }
198
- .btn.primary:hover { background: #1b3f96; }
199
- .btn.danger { color: #b03a2e; }
200
- .btn:focus-visible { outline: 2px solid #2453c4; outline-offset: 2px; }
201
- .pin { position: absolute; width: 20px; height: 20px; border-radius: 50%; background: #2453c4; color: #fff;
202
- font: 600 11px/20px "IBM Plex Mono", ui-monospace, Consolas, monospace; text-align: center; cursor: pointer; border: 2px solid #fff; box-shadow: 0 1px 3px rgba(23,32,43,.25); }
203
- .select-btn { position: absolute; all: unset; position: absolute; cursor: pointer; background: #17202b; color: #fff; font: 500 12.5px/1 "IBM Plex Sans", system-ui, sans-serif; padding: 7px 10px; border-radius: 6px; box-shadow: 0 6px 18px -8px rgba(23,32,43,.5); }
204
- .select-btn:hover { background: #2453c4; }
293
+ .hint { flex: 1; font-size: 11.5px; color: #9a9a92; line-height: 1.3; }
294
+ .btn { all: unset; cursor: pointer; font: 500 13px/1 "Instrument Sans", system-ui, sans-serif; padding: 8px 11px; border-radius: 6px; color: #6c6c65; }
295
+ .btn:hover { background: #f2f2ef; color: #141413; }
296
+ .btn.primary { background: #141413; color: #fff; }
297
+ .btn.primary:hover { background: #3a3a36; }
298
+ .btn.danger { color: #c0392b; }
299
+ .btn:focus-visible { outline: 2px solid #141413; outline-offset: 2px; }
300
+ .ring { position: absolute; border: 1.5px solid #141413; border-radius: 8px; pointer-events: none; }
301
+ .ring.active { border-width: 2px; }
302
+ .ring.agent { border: 2px solid #141413; border-radius: 9px; }
303
+ .bubble { position: absolute; width: 300px; background: #141413; color: #fafaf9; border-radius: 10px; padding: 10px 30px 11px 12px; box-shadow: 0 14px 34px -14px rgba(20,20,19,.5); font: 13.5px/1.5 "Instrument Sans", system-ui, -apple-system, "Segoe UI", sans-serif; pointer-events: auto; }
304
+ .bubble-who { font-size: 11.5px; font-weight: 600; color: #ffe27a; margin-bottom: 3px; }
305
+ .bubble-text { white-space: pre-wrap; }
306
+ .bubble-x { all: unset; position: absolute; top: 6px; right: 8px; cursor: pointer; color: #a0a098; font-size: 16px; line-height: 1; padding: 2px 4px; border-radius: 4px; }
307
+ .bubble-x:hover { color: #fff; background: rgba(255,255,255,.1); }
308
+ .ring.noted { border-color: rgba(20, 20, 19, .35); }
309
+ @media (prefers-color-scheme: dark) { .ring { border-color: #f2f2ee; } .ring.noted { border-color: rgba(242, 242, 238, .45); } }
310
+ .pin { position: absolute; width: 20px; height: 20px; border-radius: 50%; background: #ffe27a; color: #141413;
311
+ font: 600 11px/20px "Commit Mono", ui-monospace, Consolas, monospace; text-align: center; cursor: pointer; border: 2px solid #fff; box-shadow: 0 1px 3px rgba(20,20,19,.25); }
312
+ .select-btn { position: absolute; all: unset; position: absolute; cursor: pointer; background: #141413; color: #fff; font: 500 12.5px/1 "Instrument Sans", system-ui, sans-serif; padding: 7px 10px; border-radius: 6px; box-shadow: 0 6px 18px -8px rgba(20,20,19,.5); }
313
+ .select-btn:hover { background: #141413; }
205
314
  @media (prefers-color-scheme: dark) {
206
- .card { background: #191d23; color: #edf0f3; border-color: #3d4651; box-shadow: 0 12px 32px -12px rgba(0,0,0,.6); }
207
- textarea { background: #121519; border-color: #2a3039; }
208
- textarea:focus { background: #121519; border-color: #7ea3ff; }
209
- .suggest button { color: #7ea3ff; }
210
- .btn { color: #9ba4af; } .btn:hover { background: #1f242b; color: #edf0f3; }
211
- .btn.primary { background: #2453c4; color: #fff; }
212
- .pin { border-color: #121519; }
315
+ .card { background: #1b1b1a; color: #f2f2ee; border-color: #44443f; box-shadow: 0 12px 32px -12px rgba(0,0,0,.6); }
316
+ textarea { background: #161615; border-color: #2f2f2c; }
317
+ textarea:focus { background: #161615; border-color: #f2f2ee; }
318
+ .suggest button { color: #f2f2ee; }
319
+ .btn { color: #a0a098; } .btn:hover { background: #252523; color: #f2f2ee; }
320
+ .btn.primary { background: #f2f2ee; color: #141413; }
321
+ .pin { border-color: #161615; }
213
322
  }
214
- </style><div id="pins"></div><div id="slot"></div>`;
323
+ </style><div id="rings"></div><div id="pins"></div><div id="slot"></div>`;
215
324
  const pinsEl = shadow.getElementById('pins');
216
325
  const slot = shadow.getElementById('slot');
326
+ rings = shadow.getElementById('rings');
217
327
  const mount = () => { if (!host.isConnected) document.body.appendChild(host); };
218
328
 
219
329
  let card = null; // { el, target, textRange, noteId }
@@ -228,7 +338,7 @@
228
338
  if (!card) return;
229
339
  card.target?.removeAttribute('data-tm-active');
230
340
  card.el.remove(); card = null;
231
- paintHighlights();
341
+ paintHighlights(); paintRings();
232
342
  }
233
343
  function docRect(r) { return { left: r.left + scrollX, top: r.top + scrollY, right: r.right + scrollX, bottom: r.bottom + scrollY, width: r.width, height: r.height }; }
234
344
 
@@ -265,7 +375,7 @@
265
375
  el.style.left = `${left}px`; el.style.top = `${top}px`;
266
376
  target?.setAttribute('data-tm-active', '');
267
377
  card = { el, target, text, noteId, label, src, rect: r, range };
268
- paintHighlights();
378
+ paintHighlights(); paintRings();
269
379
  const finish = (sendNow) => {
270
380
  const value = ta.value.trim();
271
381
  if (!value) { ta.focus(); return; }
@@ -310,6 +420,7 @@
310
420
  paintHighlights();
311
421
  pinsEl.innerHTML = '';
312
422
  for (const el of document.querySelectorAll('[data-tm-noted]')) el.removeAttribute('data-tm-noted');
423
+ paintRings();
313
424
  if (!notes.size) return;
314
425
  mount();
315
426
  let i = 0;
@@ -317,7 +428,7 @@
317
428
  i++;
318
429
  let r = null;
319
430
  if (n.el && !n.el.isConnected && n.selector) { try { n.el = document.querySelector(n.selector); } catch { n.el = null; } }
320
- if (n.el?.isConnected) { r = docRect(n.el.getBoundingClientRect()); n.el.setAttribute('data-tm-noted', ''); }
431
+ if (n.el?.isConnected) { const x = extentOf(n.el); r = { left: x.left + 4, top: x.top + 4 }; n.el.setAttribute('data-tm-noted', ''); }
321
432
  else if (n.rect) r = n.rect;
322
433
  if (!r) continue;
323
434
  const pin = document.createElement('div');
@@ -348,18 +459,53 @@
348
459
  return t.closest('a.tm-node,a.tm-link') || pickTarget(t);
349
460
  }
350
461
  document.addEventListener('mousemove', (e) => {
351
- if (!annotating || card) return;
352
462
  const t = e.target instanceof Element ? e.target : null;
463
+ if (!annotating) {
464
+ // Reading mode: hovering a box lights up its own wires.
465
+ const box = t?.closest('.tm-map .tm-node, .tm-blueprint .tm-node') || null;
466
+ if (box !== hotBox) { hotBox = box; markWires(); }
467
+ return;
468
+ }
469
+ if (card) return;
353
470
  setHover(annotTarget(t));
354
471
  }, { passive: true });
355
- document.addEventListener('mouseleave', () => setHover(null));
472
+ document.addEventListener('mouseleave', () => { setHover(null); if (hotBox) { hotBox = null; markWires(); } });
356
473
 
357
474
  document.addEventListener('click', (e) => {
358
475
  if (!e.isTrusted) return;
359
476
  if (e.composedPath().includes(host)) return;
360
477
  const t = e.target instanceof Element ? e.target : null;
361
478
  if (card) { closeCard(); if (!annotating) return; }
362
- if (!annotating || !t) return;
479
+ if (!t) return;
480
+ // A flow button lights up a whole path across the map (works in both modes).
481
+ const flow = t.closest('[data-tm-flow]');
482
+ if (flow) {
483
+ e.preventDefault(); e.stopPropagation();
484
+ const ids = flow.getAttribute('data-tm-flow').split(/[\s,]+/).filter(Boolean);
485
+ const same = focusSet.length && ids.every((id) => focusSet.some((el) => el.id === id));
486
+ if (same) clearFocus(); else applyFocus(ids, flow.getAttribute('data-note') || '', clean(flow.textContent, 60));
487
+ for (const b of document.querySelectorAll('[data-tm-flow]')) b.setAttribute('aria-pressed', String(!same && b === flow));
488
+ return;
489
+ }
490
+ if (!annotating) {
491
+ // A box opens the inspector (what it is, its code, its connections). Real links and controls inside work as usual.
492
+ const box = t.closest(boxSel);
493
+ const inner = t.closest('a[href],button,input,select,textarea,label,summary,.tm-ask,[role=tab]');
494
+ if (String(getSelection?.() || '').trim().length > 1) return;
495
+ if (!box) {
496
+ // Empty space: back to the plain map.
497
+ if (!inner) {
498
+ if (focusSet.length || focusNote) { clearFocus(); post({ type: 'focus-cleared' }); }
499
+ if (selected) { select(null); post({ type: 'deselect' }); }
500
+ for (const fig of document.querySelectorAll('figure.tm-diagram[data-flow]')) window.truemapDiagram?.setFlow(fig, null);
501
+ }
502
+ return;
503
+ }
504
+ if (inner && inner !== box && box.contains(inner)) return;
505
+ e.preventDefault(); e.stopPropagation();
506
+ peek(box);
507
+ return;
508
+ }
363
509
  if (String(getSelection?.() || '').trim().length > 1) return;
364
510
  const el = annotTarget(t);
365
511
  if (!el) return;
@@ -380,13 +526,15 @@
380
526
  });
381
527
  document.addEventListener('selectionchange', () => { if (!String(getSelection() || '').trim()) hideSelectBtn(); });
382
528
 
529
+ // Escape anywhere in the page closes the inspector and the workspace's menus.
530
+ document.addEventListener('mouseup', (e) => { if (e.button === 3 || e.button === 4) { e.preventDefault(); post({ type: 'nav', dir: e.button === 3 ? 'back' : 'forward' }); } }, true);
383
531
  document.addEventListener('keydown', (e) => {
532
+ if (e.key === 'Escape') { select(null); post({ type: 'press' }); for (const fig of document.querySelectorAll('figure.tm-diagram[data-flow]')) window.truemapDiagram?.setFlow(fig, null); }
533
+ if (e.altKey && (e.key === 'ArrowLeft' || e.key === 'ArrowRight')) { e.preventDefault(); post({ type: 'nav', dir: e.key === 'ArrowLeft' ? 'back' : 'forward' }); return; }
384
534
  const typing = e.target instanceof Element && e.target.closest('input,textarea,select,[contenteditable]');
385
535
  if (e.key === 'Escape' && card) { closeCard(); return; }
386
- if (e.key === 'Escape' && annotating && !typing && !e.defaultPrevented && !e.composedPath().includes(host)) { post({ type: 'annotate-off' }); return; }
387
- if (!typing && !e.composedPath().includes(host) && !e.ctrlKey && !e.metaKey && !e.altKey && e.key.toLowerCase() === 'a') {
388
- post({ type: 'toggle-annotate' });
389
- }
536
+ if (e.key === 'Escape' && (focusSet.length || focusNote)) { clearFocus(); post({ type: 'focus-cleared' }); return; }
537
+ if ((e.key === 'Enter' || e.key === ' ') && !annotating && e.target instanceof Element && e.target.matches?.('.tm-node, .tm-step') && !typing) { e.preventDefault(); peek(e.target); return; }
390
538
  });
391
539
 
392
540
  // ---------- decisions: <form class="tm-ask" data-tm-ask="question"> ----------
@@ -446,6 +594,48 @@
446
594
  else if (n?.rect) window.scrollTo({ top: n.rect.top - innerHeight / 3, behavior: 'smooth' });
447
595
  } else if (d.type === 'scroll') {
448
596
  window.scrollTo(0, d.y || 0);
597
+ } else if (d.type === 'focus') {
598
+ applyFocus(d.items, d.note, d.who, d.scroll === undefined ? 'center' : d.scroll, !!d.transient);
599
+ } else if (d.type === 'select') {
600
+ select(d.id ? document.getElementById(d.id) : null);
601
+ } else if (d.type === 'plan') {
602
+ // A plan drawn on the map: what it touches, adds (dashed, in its group) and removes.
603
+ for (const el of document.querySelectorAll('[data-plan-overlay], [data-plan-revised]')) { el.removeAttribute('data-plan'); el.removeAttribute('data-plan-note'); el.removeAttribute('data-plan-overlay'); el.removeAttribute('data-plan-revised'); }
604
+ clearFocus();
605
+ const p = d.plan;
606
+ document.documentElement.toggleAttribute('data-tm-plan', !!p);
607
+ const fig = document.querySelector('figure.tm-diagram');
608
+ if (fig && window.truemapDiagram?.setGhosts) window.truemapDiagram.setGhosts(fig, p ? p.add : []);
609
+ else if (p) post({ type: 'plan-unsupported' }); // an old-format map: the plan can't be drawn on it
610
+ const markPlan = (box, kind, note) => {
611
+ const el = findItems([box])[0];
612
+ if (!el || el.getAttribute('data-plan') === 'new') return;
613
+ el.setAttribute('data-plan', kind); el.setAttribute('data-plan-overlay', ''); if (note) el.setAttribute('data-plan-note', note);
614
+ };
615
+ if (p) { for (const t of p.touch || []) markPlan(t.box, 'change', t.what); for (const r of p.remove || []) markPlan(r.box, 'remove', r.why); }
616
+ for (const id of p?.revised || []) findItems([id])[0]?.setAttribute('data-plan-revised', '');
617
+ for (const b of document.querySelectorAll('.tm-node, .tm-step')) { if (!b.hasAttribute('tabindex') && !b.matches('a[href]')) b.setAttribute('tabindex', '0'); }
618
+ markWires();
619
+ } else if (d.type === 'changes') {
620
+ // Review mode: changed boxes carry their +/- lines; the rest of the map goes quiet.
621
+ document.documentElement.toggleAttribute('data-tm-changes', !!d.on);
622
+ for (const el of document.querySelectorAll('[data-tm-change], [data-tm-unbuilt]')) { el.removeAttribute('data-tm-change'); el.removeAttribute('data-tm-delta'); el.removeAttribute('data-tm-unbuilt'); }
623
+ for (const u of d.unbuilt || []) { const el = findItems([u.src || u.box, u.box])[0]; if (el) el.setAttribute('data-tm-unbuilt', ''); }
624
+ const names = [];
625
+ for (const it of d.items || []) {
626
+ for (const el of document.querySelectorAll('[data-src]')) {
627
+ if (el.getAttribute('data-src') !== it.src) continue;
628
+ el.setAttribute('data-tm-change', '');
629
+ el.setAttribute('data-tm-delta', it.add == null ? 'binary' : [it.add ? '+' + it.add : '', it.del ? '−' + it.del : ''].filter(Boolean).join(' ') || '±0');
630
+ names.push({ src: it.src, name: clean(el.getAttribute('data-name'), 60) || labelOf(el) });
631
+ }
632
+ }
633
+ if (names.length) post({ type: 'changes-names', items: names });
634
+ } else if (d.type === 'open-box') {
635
+ const el = d.id ? document.getElementById(d.id) : [...document.querySelectorAll('[data-src]')].find((x) => x.getAttribute('data-src') === d.src);
636
+ if (el) { reveal([el], 'nearest'); peek(el); }
637
+ } else if (d.type === 'clear-focus') {
638
+ clearFocus();
449
639
  } else if (d.type === 'highlight') {
450
640
  const el = [...document.querySelectorAll('[data-src]')].find((x) => x.getAttribute('data-src') === d.src);
451
641
  if (el) { el.scrollIntoView({ block: 'center', behavior: 'smooth' }); el.setAttribute('data-tm-flash', ''); setTimeout(() => el.removeAttribute('data-tm-flash'), 2400); }
@@ -458,9 +648,14 @@
458
648
  scrollTimer = setTimeout(() => post({ type: 'scroll', page: pagePath(), y: window.scrollY }), 120);
459
649
  }, { passive: true });
460
650
  window.addEventListener('resize', scheduleWires);
651
+ // Rings follow their element when anything scrolls, including a map scrolling sideways.
652
+ document.addEventListener('scroll', () => { if (rings && (hovered || card || notes.size)) { placePins(); } }, { capture: true, passive: true });
461
653
 
654
+ window.truemapDiagram?.interact();
462
655
  const ready = () => {
463
656
  drawWires();
657
+ // Boxes are reachable from the keyboard too.
658
+ for (const b of document.querySelectorAll('.tm-node, .tm-step')) { if (!b.hasAttribute('tabindex') && !b.matches('a[href]')) b.setAttribute('tabindex', '0'); }
464
659
  if ('ResizeObserver' in window) new ResizeObserver(scheduleWires).observe(document.body);
465
660
  document.fonts?.ready?.then(scheduleWires);
466
661
  const meta = document.querySelector('meta[name="truemap-annotate"]')?.getAttribute('content');