truemap-cli 0.5.1 → 0.5.2

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/README.md CHANGED
@@ -20,6 +20,7 @@ Coding agents write code faster than anyone can read it. Review is the bottlenec
20
20
  - **Many projects.** Every project with truemap running is one click away, and the tab tells you when another one needs you (a plan to review, a new reply).
21
21
  - **Any agent.** Claude Code, Codex, OpenCode, Cursor CLI, or agents inside hosts such as T3 Code: anything that can run a shell command.
22
22
  - **It stays in the repo.** Maps live in `.truemap/`. Plain HTML files you commit, diff and share.
23
+ - **Your look.** Light, dark or follow the system. Ask the agent for other colours or fonts ("a blue accent", "like our brand"): it writes `.truemap/assets/theme.css`, every page and the workspace follow, and `truemap theme` checks that everything stays readable.
23
24
 
24
25
  ## Install
25
26
 
package/kit/tokens.css ADDED
@@ -0,0 +1,65 @@
1
+ /* truemap tokens: every colour and font the pages and the workspace use. truemap serves them first, then
2
+ .truemap/assets/theme.css, so a project (or its user) can restyle everything by overriding these. */
3
+
4
+ @font-face { font-family: "Instrument Sans"; font-weight: 400; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-400-normal.woff2") format("woff2"); }
5
+ @font-face { font-family: "Instrument Sans"; font-weight: 500; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-500-normal.woff2") format("woff2"); }
6
+ @font-face { font-family: "Instrument Sans"; font-weight: 600; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-600-normal.woff2") format("woff2"); }
7
+ @font-face { font-family: "Commit Mono"; font-weight: 400; font-display: swap; src: url("/__truemap/fonts/commit-mono-latin-400-normal.woff2") format("woff2"); }
8
+
9
+ /* One fixed system. Neutrals and ink carry structure; --tm-accent (ink unless the project has its own
10
+ colour) marks the primary action; a highlighter marks what the agent points at; status colours mean
11
+ status only. */
12
+ :root {
13
+ --tm-paper: #ffffff; /* page background */
14
+ --tm-sheet: #ffffff; /* boxes on the map */
15
+ --tm-wash: #f2f2ef; /* quiet fills, groups */
16
+ --tm-ink: #141413; /* titles, the main path, selection */
17
+ --tm-text: #2b2b28; /* body text */
18
+ --tm-graphite: #6c6c65; /* secondary text */
19
+ --tm-pencil: #9a9a92; /* hints */
20
+ --tm-rule: #e6e6e1;
21
+ --tm-rule-strong: #d2d2cb;
22
+ --tm-accent: #141413; /* the primary action; the project's own colour when truemap finds one */
23
+ --tm-accent-text: #ffffff; /* text on the accent */
24
+ --tm-chrome: #fafaf9; /* the workspace bars and panel */
25
+ --tm-mark: #ffe27a; /* the agent points here */
26
+ --tm-route: var(--tm-ink); /* v0.4 name for the key path and links */
27
+ --tm-route-ink: var(--tm-ink);
28
+ --tm-route-wash: #f2f2ef;
29
+ --tm-action: var(--tm-accent);
30
+ --tm-changed: #a35f00;
31
+ --tm-changed-wash: #fbf1df;
32
+ --tm-broken: #c0392b;
33
+ --tm-broken-wash: #fbe9e6;
34
+ --tm-fine: #2f7a4f;
35
+ --tm-fine-wash: #e6f1ea;
36
+ --tm-radius: 8px;
37
+ --tm-font: "Instrument Sans", system-ui, -apple-system, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
38
+ --tm-code: "Commit Mono", ui-monospace, "SF Mono", "Cascadia Mono", Consolas, monospace;
39
+ color-scheme: light dark;
40
+ }
41
+
42
+ @media (prefers-color-scheme: dark) {
43
+ :root {
44
+ --tm-paper: #161615;
45
+ --tm-sheet: #161615;
46
+ --tm-wash: #222220;
47
+ --tm-ink: #f2f2ee;
48
+ --tm-text: #dadad4;
49
+ --tm-graphite: #a0a098;
50
+ --tm-pencil: #75756e;
51
+ --tm-rule: #2f2f2c;
52
+ --tm-rule-strong: #44443f;
53
+ --tm-accent: #f2f2ee;
54
+ --tm-accent-text: #141413;
55
+ --tm-chrome: #1b1b1a;
56
+ --tm-mark: #6b5a12;
57
+ --tm-route-wash: #222220;
58
+ --tm-changed: #e0a548;
59
+ --tm-changed-wash: #2c2414;
60
+ --tm-broken: #ef8574;
61
+ --tm-broken-wash: #321b18;
62
+ --tm-fine: #7cc49c;
63
+ --tm-fine-wash: #16271e;
64
+ }
65
+ }
package/kit/truemap.css CHANGED
@@ -1,64 +1,5 @@
1
- /* truemap page kit. truemap serves this file to every page in .truemap/ (assets/truemap.css).
2
- To match a project's own look, put token overrides in .truemap/assets/theme.css – truemap appends it here. */
3
-
4
- @font-face { font-family: "Instrument Sans"; font-weight: 400; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-400-normal.woff2") format("woff2"); }
5
- @font-face { font-family: "Instrument Sans"; font-weight: 500; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-500-normal.woff2") format("woff2"); }
6
- @font-face { font-family: "Instrument Sans"; font-weight: 600; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-600-normal.woff2") format("woff2"); }
7
- @font-face { font-family: "Commit Mono"; font-weight: 400; font-display: swap; src: url("/__truemap/fonts/commit-mono-latin-400-normal.woff2") format("woff2"); }
8
-
9
- /* One fixed system. Neutrals and ink carry structure; --tm-accent (ink unless the project has its own
10
- colour) marks the primary action; a highlighter marks what the agent points at; status colours mean
11
- status only. */
12
- :root {
13
- --tm-paper: #ffffff; /* page background */
14
- --tm-sheet: #ffffff; /* boxes on the map */
15
- --tm-wash: #f2f2ef; /* quiet fills, groups */
16
- --tm-ink: #141413; /* titles, the main path, selection */
17
- --tm-text: #2b2b28; /* body text */
18
- --tm-graphite: #6c6c65; /* secondary text */
19
- --tm-pencil: #9a9a92; /* hints */
20
- --tm-rule: #e6e6e1;
21
- --tm-rule-strong: #d2d2cb;
22
- --tm-accent: #141413; /* the primary action; the project's own colour when truemap finds one */
23
- --tm-mark: #ffe27a; /* the agent points here */
24
- --tm-route: var(--tm-ink); /* v0.4 name for the key path and links */
25
- --tm-route-ink: var(--tm-ink);
26
- --tm-route-wash: #f2f2ef;
27
- --tm-action: var(--tm-accent);
28
- --tm-changed: #a35f00;
29
- --tm-changed-wash: #fbf1df;
30
- --tm-broken: #c0392b;
31
- --tm-broken-wash: #fbe9e6;
32
- --tm-fine: #2f7a4f;
33
- --tm-fine-wash: #e6f1ea;
34
- --tm-radius: 8px;
35
- --tm-font: "Instrument Sans", system-ui, -apple-system, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
36
- --tm-code: "Commit Mono", ui-monospace, "SF Mono", "Cascadia Mono", Consolas, monospace;
37
- color-scheme: light dark;
38
- }
39
-
40
- @media (prefers-color-scheme: dark) {
41
- :root {
42
- --tm-paper: #161615;
43
- --tm-sheet: #161615;
44
- --tm-wash: #222220;
45
- --tm-ink: #f2f2ee;
46
- --tm-text: #dadad4;
47
- --tm-graphite: #a0a098;
48
- --tm-pencil: #75756e;
49
- --tm-rule: #2f2f2c;
50
- --tm-rule-strong: #44443f;
51
- --tm-accent: #f2f2ee;
52
- --tm-mark: #6b5a12;
53
- --tm-route-wash: #222220;
54
- --tm-changed: #e0a548;
55
- --tm-changed-wash: #2c2414;
56
- --tm-broken: #ef8574;
57
- --tm-broken-wash: #321b18;
58
- --tm-fine: #7cc49c;
59
- --tm-fine-wash: #16271e;
60
- }
61
- }
1
+ /* truemap page kit: the components. Colours and fonts come from kit/tokens.css (served first) and
2
+ .truemap/assets/theme.css (served last). */
62
3
 
63
4
  /* ---------- base ---------- */
64
5
  *, *::before, *::after { box-sizing: border-box; }
@@ -238,7 +179,7 @@ html[data-tm-focusing] .tm-wire-label:not(.is-focus) { opacity: 0; }
238
179
  .tm-badge.is-bad { background: var(--tm-broken-wash); color: var(--tm-broken); }
239
180
 
240
181
  code, kbd, samp { font-family: var(--tm-code); font-size: 0.88em; }
241
- :not(pre) > code { background: var(--tm-wash); color: var(--tm-ink); padding: 1px 5px; border-radius: 4px; }
182
+ :not(pre) > code { background: var(--tm-wash); color: var(--tm-ink); padding: 1px 5px; border-radius: 4px; overflow-wrap: anywhere; }
242
183
  pre { font-family: var(--tm-code); font-size: 13px; line-height: 1.6; background: var(--tm-sheet); color: var(--tm-text); border: 1px solid var(--tm-rule); border-radius: var(--tm-radius); padding: 14px 16px; overflow-x: auto; margin: 18px 0; max-width: 100%; }
243
184
  .tm-path { font-family: var(--tm-code); font-size: 12.5px; color: var(--tm-graphite); }
244
185
 
@@ -282,7 +223,7 @@ pre { font-family: var(--tm-code); font-size: 13px; line-height: 1.6; background
282
223
  .tm-option:has(input:checked) { border-color: var(--tm-route); background: var(--tm-route-wash); }
283
224
  .tm-ask textarea { width: 100%; min-height: 64px; resize: vertical; font: 14.5px/1.5 var(--tm-font); color: var(--tm-text); background: var(--tm-paper); border: 1px solid var(--tm-rule); border-radius: var(--tm-radius); padding: 10px 12px; }
284
225
  .tm-ask textarea:focus { outline: none; border-color: var(--tm-route); }
285
- .tm-btn { display: inline-flex; align-items: center; gap: 8px; margin-top: 14px; font: 500 14.5px/1 var(--tm-font); padding: 11px 18px; border-radius: var(--tm-radius); border: 1px solid var(--tm-action); background: var(--tm-action); color: #fff; cursor: pointer; }
226
+ .tm-btn { display: inline-flex; align-items: center; gap: 8px; margin-top: 14px; font: 500 14.5px/1 var(--tm-font); padding: 11px 18px; border-radius: var(--tm-radius); border: 1px solid var(--tm-action); background: var(--tm-action); color: var(--tm-accent-text); cursor: pointer; }
286
227
  .tm-btn:hover { filter: brightness(0.92); }
287
228
  .tm-btn.is-quiet { background: transparent; color: var(--tm-route); }
288
229
  [data-tm-sent] .tm-btn { background: var(--tm-wash); border-color: var(--tm-rule); color: var(--tm-graphite); cursor: default; }
@@ -377,7 +318,7 @@ html[data-tm-changes] .tm-node[data-tm-change]:not(.tm-diagram .tm-node) { outli
377
318
  .tm-diagram .tm-node[data-plan="new"] { border: 1.5px dashed var(--dg-ink); }
378
319
  .tm-diagram .tm-node[data-plan="change"] { border-color: var(--dg-ink); box-shadow: 0 0 0 1px var(--dg-ink); }
379
320
  .tm-diagram .tm-node[data-plan="remove"] .tm-dg-name { text-decoration: line-through; }
380
- .tm-diagram .tm-node[data-plan]:not([data-tm-delta])::after { display: block; position: absolute; top: -9px; right: -8px; font: 500 12px/17px var(--dg-font); padding: 0 8px; border-radius: 9px; background: var(--dg-bg); color: var(--dg-ink); border: 1px solid var(--dg-ink); white-space: nowrap; pointer-events: none; }
321
+ .tm-diagram .tm-node[data-plan]:not([data-tm-delta])::after { display: block; position: absolute; top: -14px; right: -8px; font: 500 12px/17px var(--dg-font); padding: 0 8px; border-radius: 9px; background: var(--dg-bg); color: var(--dg-ink); border: 1px solid var(--dg-ink); white-space: nowrap; pointer-events: none; }
381
322
  .tm-diagram .tm-node[data-plan="new"]:not([data-tm-delta])::after { content: "Plan: new"; }
382
323
  /* a draft sketching an idea: a proposed box, not a plan under review */
383
324
  .tm-diagram .tm-node[data-plan="new"]:not([data-ghost]):not([data-tm-delta])::after { content: "Proposed"; }
@@ -410,4 +351,4 @@ html[data-tm-plan]:not([data-tm-changes]) .tm-diagram .tm-node:not([data-plan])
410
351
  /* the agent points here: a highlighter, not a colour code */
411
352
  .tm-diagram .tm-node[data-tm-focus] { background: var(--dg-mark); border-color: var(--dg-ink); }
412
353
  /* a box whose code was created this turn */
413
- .tm-diagram .tm-node[data-tm-new][data-tm-delta]::after { background: var(--tm-fine); color: #fff; }
354
+ .tm-diagram .tm-node[data-tm-new][data-tm-delta]::after { background: var(--tm-fine); color: var(--tm-paper); }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "truemap-cli",
3
- "version": "0.5.1",
3
+ "version": "0.5.2",
4
4
  "description": "Agents explain your project with living HTML pages that stay true to the code. Click, ask, and decide right on the page.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: truemap
3
- description: Explain code on a page that opens in the user's browser instead of answering only in the terminal. Use this whenever the user asks you to explain, walk through or make clear any code, in any language ("how does X work", "explain X to me", "I don't get X"), even a single function or file; no project map is needed. Also use it before a change that touches 3+ parts (show the plan, wait for approval), after editing code (show what changed), and when asked to show the project. Skip it only for short factual answers (which file, which flag, yes or no).
3
+ description: Explain code on a page that opens in the user's browser instead of answering only in the terminal. Use this whenever the user asks you to explain or make clear any code, however it is phrased and in any language ("explain this", "can you just explain this", "how does X work", "what does this do", "walk me through", "break it down", "I don't get X"), even a single function or file; no project map is needed. Also use it before a change that touches 3+ parts (show the plan, wait for approval), after editing code (show what changed), and when asked to show the project. A question about what code does or how it works is a request to explain, not a short factual question. Skip it only for lookups (which file, which flag, yes or no).
4
4
  allowed-tools: Bash(npx -y truemap-cli:*), Bash(npx truemap-cli:*), Bash(truemap:*)
5
5
  license: MIT
6
6
  ---
@@ -16,7 +16,7 @@ Current instructions live in the CLI – this file stays short so it never goes
16
16
  - `npx -y truemap-cli guide` – how to write maps, plans and anchors
17
17
 
18
18
  Flow:
19
- - Explaining something, big or small (how X works, "explain this function", "I don't get this", an idea): `npx -y truemap-cli draft "<name>"`, write the page, open it with `npx -y truemap-cli drafts/<file>`; keep the chat answer to a line or two. No map is needed first, and don't build one unless asked.
19
+ - Explaining something, big or small (how X works, "explain this function", "I don't get this", an idea): `npx -y truemap-cli draft "<name>"`, show it in the form that makes it obvious (a traced example, a drawing, a timeline, a side-by-side, something to try; not necessarily a diagram, never a wall of text), open it with `npx -y truemap-cli drafts/<file>`; keep the chat answer to a line or two. No map is needed first, and don't build one unless asked.
20
20
  - The project map: `.truemap/index.html`; update it when the structure changes, run `npx -y truemap-cli <page>`, then follow the `next_step` it prints.
21
21
  - Before a larger change: `npx -y truemap-cli plan --file plan.json`, wait for the approval.
22
22
  - After editing code: `npx -y truemap-cli changes`.
package/src/cli.js CHANGED
@@ -9,7 +9,8 @@ import {
9
9
  } from './common.js';
10
10
  import { checkAll, listPages, markOk, pageInFolder } from './check.js';
11
11
  import { outline } from './outline.js';
12
- import { exportPage } from './export.js';
12
+ import { exportPage, tokensCss } from './export.js';
13
+ import { contrastNotes } from './contrast.js';
13
14
  import { writeFileSync } from 'node:fs';
14
15
 
15
16
  const CMD = process.env.TRUEMAP_CMD || 'npx -y truemap-cli';
@@ -123,6 +124,12 @@ function resolvePage(root, arg) {
123
124
  else if (existsSync(join(dir, arg))) candidate = arg;
124
125
  else if (existsSync(abs)) throw new Error(`${arg} is outside ${FOLDER}/. Save pages inside ${FOLDER}/ so they stay with the project.`);
125
126
  else candidate = arg.replace(new RegExp(`^${FOLDER}[\\\\/]`), '');
127
+ const byNum = candidate.match(/^drafts[\\/](\d{1,3})$/);
128
+ if (byNum) {
129
+ const want = byNum[1].padStart(3, '0');
130
+ const hit = (existsSync(join(dir, 'drafts')) ? readdirSync(join(dir, 'drafts')) : []).find((x) => x.startsWith(want + '-') && x.endsWith('.html'));
131
+ if (hit) candidate = `drafts/${hit}`;
132
+ }
126
133
  const rel = pageInFolder(root, candidate);
127
134
  if (!rel) throw new Error(`${arg} is outside ${FOLDER}/.`);
128
135
  return rel;
@@ -469,11 +476,12 @@ function cmdDraft(root, args, opts) {
469
476
  <header class="tm-header">
470
477
  <nav class="tm-crumb">${hasMap ? '<a href="../index.html">Map</a> / ' : ''}Draft ${n}</nav>
471
478
  <h1 class="tm-title">${esc(title)}</h1>
472
- <p class="tm-lede">One or two sentences: what this draft explains or proposes.</p>
479
+ <p class="tm-lede">One sentence: what this shows.</p>
473
480
  </header>
481
+ <!-- Show it in the form that makes it obvious: a real example traced step by step, a drawing, a timeline,
482
+ options side by side, something to try, or the map component. Any HTML, inline SVG, <style>, <script>;
483
+ colours through var(--tm-…). Words only as captions. -->
474
484
  <section class="tm-section">
475
- <h2>…</h2>
476
- <p>…</p>
477
485
  </section>
478
486
  </main></body>
479
487
  </html>
@@ -481,7 +489,7 @@ function cmdDraft(root, args, opts) {
481
489
  out('status: draft_created');
482
490
  out(`draft: ${q(file)} # .truemap/${file}`);
483
491
  block('next_step', [
484
- `Write the draft: replace the placeholder sections in .truemap/${file}. Free form: any mix of short text, a <figure class="tm-diagram"> (data-plan="new" draws a proposed box dashed), steps, a comparison table, a small interactive bit, or an <iframe> of the running dev server.${hasMap ? ' Link boxes on the map as <a href="../index.html#runs">Runs</a>.' : ' No map is needed for this.'}`,
492
+ `Write the draft in .truemap/${file}. Show it, don't write it: ask what would make this obvious at a glance and build that, in any form (a real input traced to its output, a drawing, a timeline, options side by side, something to try, the map component). No fixed sections; words only as captions. See \`${CMD} guide\`, DRAFTS.${hasMap ? ' Link boxes on the map as <a href="../index.html#runs">Runs</a>.' : ''}`,
485
493
  `Then show it: \`${CMD} ${file}\` (the user's tab switches to it and it is added to their drafts), and answer in one or two lines with \`${CMD} reply "…" --listen\` pointing to it.`,
486
494
  ].join('\n'));
487
495
  }
@@ -504,6 +512,8 @@ async function cmdCheck(root, args, opts) {
504
512
  }
505
513
  const pages = args.length ? args.map((a) => resolvePage(root, a)) : undefined;
506
514
  const { gitRepo, results } = checkAll(root, pages);
515
+ const live = await liveState(root);
516
+ if (live) await call(live, 'POST', '/api/check', {}).catch(() => {});
507
517
  out(`status: checked ${results.length} page(s)${gitRepo ? '' : ' (no git: only missing paths/names are checked)'}`);
508
518
  let changed = 0; let broken = 0; let wires = 0;
509
519
  for (const r of results) {
@@ -518,6 +528,9 @@ async function cmdCheck(root, args, opts) {
518
528
  if (wires) steps.push('Some map wires point at ids that are not on the page, so they are not drawn. Fix the data-to values (ids separated by spaces).');
519
529
  const layout = results.reduce((n, r) => n + (r.layout || []).length, 0);
520
530
  if (layout) steps.push('Map notes: fix each one; they are what keeps a map readable at a glance (see `' + CMD + ' guide`, THE MAP).');
531
+ const faint = contrastNotes(tokensCss(root));
532
+ for (const n of faint) out(`hard to read: ${n}`);
533
+ if (faint.length) steps.push(`The theme has colours that are hard to read (above): fix .truemap/assets/theme.css, then \`${CMD} theme\`.`);
521
534
  if (!broken && !changed && !wires && !layout) steps.push('All pages match the code.');
522
535
  block('next_step', steps.join('\n'));
523
536
  }
@@ -552,6 +565,22 @@ function cmdOutline(root) {
552
565
  block('next_step', `Read the manifests and entry points (not every file), then write ${FOLDER}/index.html with one <figure class="tm-diagram">: 3-5 groups by responsibility in the order a request travels, 7-12 small boxes (data-name, data-tag, data-src), data-to connections with a verb, 1-3 flows. Run \`${CMD} guide\` for the format if you have not.`);
553
566
  }
554
567
 
568
+ // The user's look: colours and fonts for every page and the workspace, kept in .truemap/assets/theme.css.
569
+ function cmdTheme(root) {
570
+ const file = join(root, FOLDER, 'assets', 'theme.css');
571
+ const has = existsSync(file);
572
+ out(`theme: ${has ? `${FOLDER}/assets/theme.css` : 'none (truemap defaults)'}`);
573
+ const notes = contrastNotes(tokensCss(root));
574
+ for (const n of notes) out(`hard to read: ${n}`);
575
+ block('next_step', [
576
+ has ? 'Edit .truemap/assets/theme.css to change the look.' : 'To change the look, create .truemap/assets/theme.css.',
577
+ 'Override --tm-* tokens in :root for light, and again inside @media (prefers-color-scheme: dark) { :root { … } } for dark. The tokens and their defaults: ' + join(PKG_DIR, 'kit', 'tokens.css'),
578
+ 'Colours and fonts only; never restyle components. Keep the three status colours (--tm-changed, --tm-broken, --tm-fine) easy to tell apart.',
579
+ 'Every open page and the workspace update by themselves. Run this command again to check contrast.',
580
+ notes.length ? 'Some colours are hard to read (above). Fix them, or tell the user which ones and let them decide.' : 'Contrast is fine in light and dark.',
581
+ ].join('\n'));
582
+ }
583
+
555
584
  function cmdGuide() {
556
585
  out(readFileSync(join(PKG_DIR, 'src', 'guide.md'), 'utf8').replaceAll('{{CMD}}', CMD));
557
586
  }
@@ -575,6 +604,7 @@ usage:
575
604
  ${CMD} ask "<question>" --option "A | why" --option "B | why"
576
605
  ask the user to choose, only when you are blocked on a real trade-off
577
606
  ${CMD} draft "<name>" a new numbered draft page that explains one thing (then open it with truemap <file>)
607
+ ${CMD} theme the user's colours and fonts (.truemap/assets/theme.css), with a contrast check
578
608
  ${CMD} plan --file plan.json before a change that touches 3+ boxes or adds one: show the plan on the map for review
579
609
  ${CMD} plan --approve|--done the user said "go" in the terminal / the plan is built
580
610
  ${CMD} changes [--base turn|plan|head|main]
@@ -621,7 +651,7 @@ function parseArgs(argv) {
621
651
  export async function main(argv) {
622
652
  const { args, opts } = parseArgs(argv);
623
653
  if (opts.version) return out(VERSION);
624
- const commands = { listen: cmdListen, reply: cmdReply, check: cmdCheck, stop: cmdStop, guide: cmdGuide, progress: cmdProgress, outline: cmdOutline, export: cmdExport, show: cmdShow, ask: cmdAsk, changes: cmdChanges, plan: cmdPlan, draft: cmdDraft, help };
654
+ const commands = { listen: cmdListen, reply: cmdReply, check: cmdCheck, stop: cmdStop, guide: cmdGuide, progress: cmdProgress, outline: cmdOutline, export: cmdExport, show: cmdShow, ask: cmdAsk, changes: cmdChanges, plan: cmdPlan, draft: cmdDraft, theme: cmdTheme, help };
625
655
  const name = args[0] && commands[args[0]] ? args.shift() : null;
626
656
  if (opts.help || name === 'help') return help();
627
657
  const root = findRoot();
@@ -0,0 +1,93 @@
1
+ // Can people read it? The colour tokens a project ends up with (kit + .truemap/assets/theme.css), light and
2
+ // dark, and the pairs that must stay readable.
3
+
4
+ const NAMED = {
5
+ black: '#000000', white: '#ffffff', gray: '#808080', grey: '#808080', silver: '#c0c0c0', lightgray: '#d3d3d3',
6
+ lightgrey: '#d3d3d3', darkgray: '#a9a9a9', darkgrey: '#a9a9a9', dimgray: '#696969', dimgrey: '#696969',
7
+ gainsboro: '#dcdcdc', whitesmoke: '#f5f5f5', snow: '#fffafa', ivory: '#fffff0', beige: '#f5f5dc', linen: '#faf0e6',
8
+ red: '#ff0000', darkred: '#8b0000', maroon: '#800000', crimson: '#dc143c', tomato: '#ff6347', coral: '#ff7f50',
9
+ orange: '#ffa500', darkorange: '#ff8c00', gold: '#ffd700', yellow: '#ffff00', khaki: '#f0e68c',
10
+ green: '#008000', darkgreen: '#006400', lime: '#00ff00', olive: '#808000', teal: '#008080', seagreen: '#2e8b57',
11
+ blue: '#0000ff', navy: '#000080', darkblue: '#00008b', royalblue: '#4169e1', steelblue: '#4682b4',
12
+ skyblue: '#87ceeb', lightblue: '#add8e6', dodgerblue: '#1e90ff', cyan: '#00ffff', aqua: '#00ffff',
13
+ purple: '#800080', indigo: '#4b0082', violet: '#ee82ee', magenta: '#ff00ff', fuchsia: '#ff00ff', pink: '#ffc0cb',
14
+ brown: '#a52a2a', chocolate: '#d2691e', tan: '#d2b48c', slategray: '#708090', slategrey: '#708090',
15
+ };
16
+ /** [r, g, b] 0-255 for hex, rgb(), hsl() and named colours; null when it can't be read. */
17
+ function hex(c) {
18
+ let v = String(c ?? '').trim().toLowerCase();
19
+ if (NAMED[v]) v = NAMED[v];
20
+ const m = v.match(/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/);
21
+ if (m) {
22
+ const h = m[1].length <= 4 ? [...m[1].slice(0, 3)].map((x) => x + x).join('') : m[1].slice(0, 6);
23
+ return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
24
+ }
25
+ const num = (x, max) => (x.endsWith('%') ? (parseFloat(x) / 100) * max : parseFloat(x));
26
+ const r = v.match(/^rgba?\(\s*([\d.]+%?)[\s,]+([\d.]+%?)[\s,]+([\d.]+%?)/);
27
+ if (r) return [r[1], r[2], r[3]].map((x) => Math.round(Math.min(255, num(x, 255))));
28
+ const h = v.match(/^hsla?\(\s*([\d.]+)(?:deg)?[\s,]+([\d.]+)%[\s,]+([\d.]+)%/);
29
+ if (h) {
30
+ const H = (+h[1] % 360) / 360; const S = +h[2] / 100; const L = +h[3] / 100;
31
+ const q = L < 0.5 ? L * (1 + S) : L + S - L * S; const p = 2 * L - q;
32
+ const t = (x) => { x = (x + 1) % 1; return x < 1 / 6 ? p + (q - p) * 6 * x : x < 1 / 2 ? q : x < 2 / 3 ? p + (q - p) * (2 / 3 - x) * 6 : p; };
33
+ return [t(H + 1 / 3), t(H), t(H - 1 / 3)].map((x) => Math.round(x * 255));
34
+ }
35
+ return null;
36
+ }
37
+ const lum = (rgb) => {
38
+ const [r, g, b] = rgb.map((v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; });
39
+ return 0.2126 * r + 0.7152 * g + 0.0722 * b;
40
+ };
41
+ export function ratio(a, b) {
42
+ const x = hex(a); const y = hex(b);
43
+ if (!x || !y) return null;
44
+ const [hi, lo] = [lum(x), lum(y)].sort((p, q) => q - p);
45
+ return (hi + 0.05) / (lo + 0.05);
46
+ }
47
+
48
+ /** The --tm-* values in effect, for light and for dark (later rules win, dark builds on light). */
49
+ export function tokens(css) {
50
+ const light = {}; const dark = {};
51
+ const take = (body, into) => { for (const m of body.matchAll(/(--tm-[\w-]+)\s*:\s*([^;}]+)/g)) into[m[1]] = m[2].trim(); };
52
+ const plain = css.replace(/\/\*[\s\S]*?\*\//g, '');
53
+ const re = /@media\s*\(\s*prefers-color-scheme\s*:\s*dark\s*\)\s*\{/g;
54
+ let at = 0; let m;
55
+ while ((m = re.exec(plain))) {
56
+ for (const r of plain.slice(at, m.index).matchAll(/:root[^{]*\{([^}]*)\}/g)) take(r[1], light);
57
+ let depth = 1; let i = re.lastIndex;
58
+ for (; i < plain.length && depth; i++) { if (plain[i] === '{') depth++; else if (plain[i] === '}') depth--; }
59
+ for (const r of plain.slice(re.lastIndex, i).matchAll(/:root[^{]*\{([^}]*)\}/g)) take(r[1], dark);
60
+ at = i; re.lastIndex = i;
61
+ }
62
+ for (const r of plain.slice(at).matchAll(/:root[^{]*\{([^}]*)\}/g)) take(r[1], light);
63
+ return { light, dark: { ...light, ...dark } };
64
+ }
65
+
66
+ const PAIRS = [
67
+ ['--tm-text', '--tm-paper', 4.5, 'body text on the page'],
68
+ ['--tm-ink', '--tm-sheet', 4.5, 'box titles'],
69
+ ['--tm-ink', '--tm-mark', 4.5, 'text on the highlighter'],
70
+ ['--tm-text', '--tm-wash', 4.5, 'text on quiet fills'],
71
+ ['--tm-ink', '--tm-chrome', 4.5, 'the workspace bar'],
72
+ ['--tm-graphite', '--tm-paper', 4.5, 'secondary text'],
73
+ ['--tm-pencil', '--tm-paper', 2.5, 'hints'],
74
+ ['--tm-accent-text', '--tm-accent', 4.5, 'text on the primary button'],
75
+ ['--tm-changed', '--tm-paper', 3, '"changed" marks'],
76
+ ['--tm-broken', '--tm-paper', 3, '"broken" marks'],
77
+ ['--tm-fine', '--tm-paper', 3, '"fine" and "new" marks'],
78
+ ['--tm-rule-strong', '--tm-paper', 1.3, 'box borders'],
79
+ ];
80
+
81
+ /** Pairs that are too faint to read, as plain notes. */
82
+ export function contrastNotes(css) {
83
+ const t = tokens(css); const notes = [];
84
+ for (const [mode, vals] of [['light', t.light], ['dark', t.dark]]) {
85
+ const val = (k) => { let v = vals[k]; for (let n = 0; n < 4 && /^var\(/.test(v || ''); n++) v = vals[(v.match(/var\(\s*(--tm-[\w-]+)/) || [])[1]]; return v; };
86
+ for (const [fg, bg, min, what] of PAIRS) {
87
+ const r = ratio(val(fg), val(bg));
88
+ if (r == null) { notes.push(`${mode}: ${what}: can't read ${hex(val(fg)) ? bg + ' ' + val(bg) : fg + ' ' + val(fg)}; use hex, rgb() or hsl() so it can be checked`); continue; }
89
+ if (r < min) notes.push(`${mode}: ${what} (${fg} ${val(fg)} on ${bg} ${val(bg)}) contrast ${r.toFixed(1)}:1, needs ${min}:1`);
90
+ }
91
+ }
92
+ return notes;
93
+ }
package/src/export.js CHANGED
@@ -21,14 +21,19 @@ export function insideFile(dir, rel) {
21
21
  } catch { return null; }
22
22
  }
23
23
 
24
- /** The page kit as served: a repo's own assets/truemap.css wins; assets/theme.css is appended. */
24
+ /** The project's theme (.truemap/assets/theme.css), or nothing. */
25
+ export function themeCss(root) {
26
+ const theme = insideFile(join(root, FOLDER), 'assets/theme.css');
27
+ return theme ? `\n/* .truemap/assets/theme.css */\n${readFileSync(theme, 'utf8')}` : '';
28
+ }
29
+ /** Colours and fonts in effect: truemap's tokens, then the project's theme. The workspace uses these too. */
30
+ export function tokensCss(root) {
31
+ return readFileSync(join(KIT_DIR, 'tokens.css'), 'utf8') + themeCss(root);
32
+ }
33
+ /** The page kit as served: tokens, components, theme. A repo's own assets/truemap.css (older setups) replaces the first two. */
25
34
  export function kitCss(root) {
26
- const folder = join(root, FOLDER);
27
- const own = insideFile(folder, 'assets/truemap.css');
28
- let css = readFileSync(own || join(KIT_DIR, 'truemap.css'), 'utf8');
29
- const theme = insideFile(folder, 'assets/theme.css');
30
- if (theme) css += `\n/* .truemap/assets/theme.css */\n${readFileSync(theme, 'utf8')}`;
31
- return css;
35
+ const own = insideFile(join(root, FOLDER), 'assets/truemap.css');
36
+ return (own ? readFileSync(own, 'utf8') : readFileSync(join(KIT_DIR, 'tokens.css'), 'utf8') + '\n' + readFileSync(join(KIT_DIR, 'truemap.css'), 'utf8')) + themeCss(root);
32
37
  }
33
38
 
34
39
  export function exportPage(root, page) {
package/src/guide.md CHANGED
@@ -19,8 +19,9 @@ FOLDER RULES
19
19
  (payments.html, auth-flow.html). index.html is the blueprint; link module pages from it and back.
20
20
  - Write pages in the user's language.
21
21
  - Link the kit and nothing else: <link rel="stylesheet" href="assets/truemap.css"> (from a subfolder
22
- ../assets/truemap.css). No frameworks, no CDNs, no web fonts, no build step, no inline colours.
23
- The look is fixed on purpose so every map reads the same; .truemap/assets/theme.css may set --tm-accent only.
22
+ ../assets/truemap.css). No frameworks, no CDNs, no web fonts, no build step. Colours only through the kit's
23
+ tokens (var(--tm-ink), var(--tm-accent), …) so the user's light, dark and theme apply.
24
+ The components are fixed; colours and fonts belong to the user (see THE USER'S LOOK).
24
25
 
25
26
  ANCHORS (this is what keeps pages true)
26
27
  - Put data-src="path#name" on every box that stands for real code. path = file or folder relative to the repo
@@ -145,19 +146,43 @@ SHOW WHAT YOU CHANGED (after you edited code)
145
146
  `{{CMD}} check --ok index.html --box <id>`. "Map may be out of date" should only appear for code the map
146
147
  hasn't caught up with, not after every turn of yours.
147
148
 
149
+ THE USER'S LOOK (colours and fonts)
150
+ - When the user asks for other colours or fonts ("warmer", "blue accent", "like our brand", "bigger code font"),
151
+ write .truemap/assets/theme.css: override --tm-* tokens in :root for light and again inside
152
+ @media (prefers-color-scheme: dark) { :root { ... } } for dark. `{{CMD}} theme` lists where the tokens are.
153
+ - It restyles every page, every draft and the workspace around them at once; open tabs update by themselves.
154
+ - Colours and fonts only: never restyle components (boxes, wires, badges). Keep --tm-changed, --tm-broken and
155
+ --tm-fine easy to tell apart; they mean status. Fonts: only ones installed on the machine (no web fonts).
156
+ - Then run `{{CMD}} theme`: it checks contrast in light and dark. If something is hard to read, fix it or tell the
157
+ user which colour and let them decide.
158
+
148
159
  DRAFTS (the everyday way to explain)
149
- - When the user asks how something works, says they don't understand, or you have an idea or a design to show,
150
- draw a draft instead of a long chat answer:
160
+ - When the user asks you to explain something, make a draft and open it:
151
161
  {{CMD}} draft "how a message is routed" creates .truemap/drafts/NNN-how-a-message-is-routed.html
152
162
  Write it, then `{{CMD}} drafts/NNN-….html`: the user's tab switches to it at once and it joins their numbered
153
163
  drafts (the record of what you explained). Keep the chat reply to one or two lines pointing to it.
154
- - A draft is free form, a whole scrolling page if needed: short text, a <figure class="tm-diagram"> (data-plan="new"
155
- draws a proposed box dashed), numbered steps, a comparison table, a decision with its trade-offs, a small
156
- interactive bit, even an <iframe> of the running dev server. Pick what makes this one thing clear.
164
+ - Show it, don't write it. First ask: what would make this obvious at a glance? Then build exactly that, in any
165
+ form HTML can take. The form follows the thing, for example:
166
+ a function one real input traced to its output, with the actual values at each step
167
+ a data structure drawn (inline SVG or plain HTML boxes) with a real example in it
168
+ something over time a timeline or sequence: one lane per actor, what happens when
169
+ a choice the options side by side, what each one costs
170
+ a bug what happens next to what should, at the point where they split
171
+ logic with knobs something to try: an input or a step button running the same logic
172
+ architecture the map component, <figure class="tm-diagram">
173
+ Nothing is required: no fixed sections, no diagram for its own sake. If a picture would not help, the code
174
+ itself with a few notes beside it can be the whole draft.
175
+ - Words are captions and the one line of "why". A draft that is mostly paragraphs should be a picture or a chat
176
+ answer instead.
177
+ - Any HTML, inline <svg>, <style> and <script> are fine; nothing loaded from the network. Colours only through
178
+ these tokens (there are no others):
179
+ --tm-paper (page) --tm-sheet (cards, boxes) --tm-wash (quiet fills) --tm-rule, --tm-rule-strong (lines)
180
+ --tm-ink (titles, emphasis) --tm-text (body) --tm-graphite (secondary) --tm-pencil (hints)
181
+ --tm-accent, --tm-accent-text (the primary action) --tm-mark (highlighter)
182
+ --tm-changed, --tm-broken, --tm-fine (+ -wash) (status only) --tm-font, --tm-code (fonts)
157
183
  - Link boxes on the map from a draft as <a href="../index.html#runs">Runs</a>: the map opens with that box lit.
158
184
  - Drafts are kept; don't delete them. A draft worth keeping for good can move to .truemap/ as a page.
159
- - A request to explain gets a draft, even for a single point: one function can be a short page with its inputs,
160
- what it does step by step, and its edge cases. Short factual questions still get a short chat answer.
185
+ - Short factual questions (which file, which flag, yes or no) still get a short chat answer.
161
186
 
162
187
  POINTING AT THE MAP
163
188
  - While you explain, light up what you are talking about:
package/src/server.js CHANGED
@@ -1,6 +1,7 @@
1
1
  // The local truemap server: one per repo, started on demand by the CLI, invisible to the user.
2
2
  // Serves the workspace UI, the .truemap pages (with the SDK injected), a chat queue between
3
3
  // the browser and the agent's CLI (listen/reply), and live updates over Server-Sent Events.
4
+ import { spawn } from 'node:child_process';
4
5
  import { createServer, request as httpRequest } from 'node:http';
5
6
  import { randomBytes } from 'node:crypto';
6
7
  import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, watch } from 'node:fs';
@@ -10,7 +11,7 @@ import { FOLDER, PKG_DIR, VERSION, addrPath, appendPrivate, buildId, stateHome,
10
11
  import { changes, fileDiff, snapshotTree } from './changes.js';
11
12
  import { cleanPlan, currentPlan, parseReport, planCheck, planMessage, planWarnings, readPlan, savePlan, srcOfBox, stepCheck } from './plan.js';
12
13
  import { checkAll, listPages } from './check.js';
13
- import { exportPage, kitCss } from './export.js';
14
+ import { exportPage, kitCss, tokensCss } from './export.js';
14
15
  import { snippet } from './snippet.js';
15
16
 
16
17
  const root = resolve(process.argv[2] || process.cwd());
@@ -369,6 +370,10 @@ function serveKit(res) {
369
370
  }
370
371
 
371
372
  function serveUi(res, name) {
373
+ if (name === 'tokens.css') {
374
+ res.writeHead(200, { 'Content-Type': 'text/css; charset=utf-8', 'Cache-Control': 'no-store' });
375
+ return res.end(themeable(tokensCss(root)));
376
+ }
372
377
  const file = safeFile(UI_DIR, name);
373
378
  if (!file) return sendText(res, 404, 'not found');
374
379
  const type = MIME[extname(file).toLowerCase()] || 'application/octet-stream';
@@ -656,8 +661,7 @@ const content = createServer((req, res) => {
656
661
  const p = new URL(req.url, `http://127.0.0.1:${contentPort}`).pathname;
657
662
  try {
658
663
  if (p === '/__truemap/sdk.js') {
659
- const themeSrc = readFileSync(new URL('./theme.js', import.meta.url), 'utf8').replace(/^export /m, '');
660
- const js = `const tmThemeable = (() => {\n${themeSrc}\nreturn themeable;\n})();\n` + [join(UI_DIR, 'wires.js'), join(UI_DIR, 'diagram.js')].map((f) => readFileSync(f, 'utf8')).join('\n;\n')
664
+ const js = [join(UI_DIR, 'wires.js'), join(UI_DIR, 'diagram.js')].map((f) => readFileSync(f, 'utf8')).join('\n;\n')
661
665
  + '\n' + readFileSync(join(UI_DIR, 'sdk.js'), 'utf8').replace('__TRUEMAP_PARENT__', `http://127.0.0.1:${port}`);
662
666
  res.writeHead(200, { 'Content-Type': 'text/javascript; charset=utf-8', 'Cache-Control': 'no-store' });
663
667
  return res.end(js);
@@ -704,5 +708,22 @@ setInterval(() => {
704
708
  if (!listener && (agentState === 'working' || agentState === 'idle') && Date.now() - lastAgentActivity > 20 * 60 * 1000) setAgentState('offline');
705
709
  }, 60_000).unref();
706
710
 
711
+ // truemap's own files can change under a running server (an upgrade in place, a local build). New files
712
+ // served by old code break pages, so the server hands over to a fresh one on the same address at once;
713
+ // open tabs reconnect and reload, and a waiting listen returns 'timeout' so the agent simply listens again.
714
+ let handingOver = false;
715
+ setInterval(() => {
716
+ if (handingOver || buildId() === BUILD) return;
717
+ handingOver = true;
718
+ finishListen({ status: 'timeout' });
719
+ broadcast({ type: 'closing', restart: true });
720
+ try { const st = JSON.parse(readFileSync(statePath, 'utf8')); if (st.pid === process.pid) rmSync(statePath, { force: true }); } catch { /* ignore */ }
721
+ for (const srv of [server, content]) { srv.close(); srv.closeAllConnections?.(); }
722
+ setTimeout(() => {
723
+ spawn(process.execPath, [join(PKG_DIR, 'src', 'server.js'), root], { detached: true, stdio: 'ignore', windowsHide: true, cwd: root }).unref();
724
+ process.exit(0);
725
+ }, 300);
726
+ }, 2000).unref();
727
+
707
728
  process.on('SIGTERM', shutdown);
708
729
  process.on('SIGINT', shutdown);
package/src/theme.js CHANGED
@@ -1,7 +1,6 @@
1
1
  // Dark mode follows the system unless the user picks one. The stylesheets keep plain
2
2
  // `@media (prefers-color-scheme: dark)` blocks; this turns each into rules that also answer to a choice:
3
3
  // <html data-theme="dark"> always dark <html data-theme="light"> always light
4
- // For a shadow root, the host carries the choice as a class instead (tm-dark / tm-light).
5
4
 
6
5
  function blocks(css) {
7
6
  // top-level `@media (prefers-color-scheme: dark) { ... }` blocks, with their positions
@@ -23,24 +22,26 @@ function scopeRules(body, pick) {
23
22
  }
24
23
 
25
24
  /** CSS for a document: dark when chosen, or when the system is dark and light was not chosen. */
26
- export function themeable(css, { host = false } = {}) {
25
+ export function themeable(css) {
27
26
  const found = blocks(css);
28
27
  if (!found.length) return css;
29
- const on = host ? ':host(.tm-dark)' : ':root[data-theme="dark"]';
30
- const notOff = host ? ':host(:not(.tm-light))' : ':root:not([data-theme="light"])';
31
28
  const scope = (prefix) => (sel) => {
32
29
  if (!sel) return '';
33
- if (!host && sel.startsWith(':root')) return prefix + sel.slice(5);
34
- if (!host && /^html\b/.test(sel)) return prefix.replace(':root', 'html') + sel.slice(4);
30
+ if (sel.startsWith(':root')) return prefix + sel.slice(5);
31
+ if (/^html\b/.test(sel)) return prefix.replace(':root', 'html') + sel.slice(4);
35
32
  return `${prefix} ${sel}`;
36
33
  };
37
34
  let out = ''; let at = 0; const forced = [];
38
35
  for (const b of found) {
39
36
  const body = css.slice(b.bodyStart, b.end - 1);
40
- out += css.slice(at, b.bodyStart) + scopeRules(body, scope(notOff)) + '}';
41
- forced.push(scopeRules(body, scope(on)));
37
+ out += css.slice(at, b.bodyStart) + scopeRules(body, scope(':root:not([data-theme="light"])')) + '}';
38
+ forced.push(scopeRules(body, scope(':root[data-theme="dark"]')));
42
39
  at = b.end;
43
40
  }
44
- const scheme = host ? '' : ':root[data-theme="light"] { color-scheme: light; }\n:root[data-theme="dark"] { color-scheme: dark; }\n';
45
- return `${out}${css.slice(at)}\n/* the user's choice */\n${scheme}${forced.join('\n')}\n`;
41
+ return `${out}${css.slice(at)}
42
+ /* the user's choice */
43
+ :root[data-theme="light"] { color-scheme: light; }
44
+ :root[data-theme="dark"] { color-scheme: dark; }
45
+ ${forced.join('\n')}
46
+ `;
46
47
  }
package/src/ui/sdk.js CHANGED
@@ -274,7 +274,7 @@
274
274
  b.style.top = `${fitsRight ? g.t : above ? g.t - bh - 12 : g.b + 12}px`;
275
275
  } else { b.style.left = `${scrollX + vw - 320}px`; b.style.top = `${scrollY + 16}px`; }
276
276
  }
277
- if (card?.target) ring(card.target, 'active');
277
+ if (card?.target && !card.target.closest('.tm-diagram')) ring(card.target, 'active'); // a map box shows its own selection
278
278
  else if (annotating && hovered) ring(hovered, 'hover');
279
279
  }
280
280
  function setAnnotate(on) {
@@ -292,80 +292,61 @@
292
292
  shadow.innerHTML = `<style>
293
293
  :host { all: initial; }
294
294
  * { box-sizing: border-box; }
295
- .card { position: absolute; z-index: 10; width: 360px; background: #fff; color: #141413; border: 1px solid #d2d2cb; border-radius: 10px;
296
- 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; }
295
+ .card { position: absolute; z-index: 10; width: 360px; background: var(--tm-sheet, #fff); color: var(--tm-ink, #141413); border: 1px solid var(--tm-rule-strong, #d2d2cb); border-radius: 10px;
296
+ box-shadow: 0 12px 32px -12px rgba(20,20,19,.28); font: 14px/1.45 var(--tm-font, system-ui, sans-serif); padding: 12px; }
297
297
  .what { display: flex; align-items: baseline; gap: 8px; min-width: 0; margin: 0 2px 6px; }
298
298
  .card.viewing { width: 320px; }
299
299
  .card.viewing textarea, .card.viewing .suggest, .card.viewing [data-act="add"], .card.viewing [data-act="cancel"], .card.viewing .hint { display: none; }
300
300
  .card:not(.viewing) [data-act="comment"] { display: none; }
301
301
  .card.viewing .foot { justify-content: flex-start; margin-top: 4px; }
302
302
  .card.viewing .sum { margin-bottom: 6px; }
303
- .sum { margin: 0 2px 10px; font-size: 13px; line-height: 1.45; color: #4a4a45; }
304
- .sum .flag { margin-top: 4px; font-size: 12px; color: #a35f00; }
305
- @media (prefers-color-scheme: dark) { .sum { color: #c4c4bd; } .sum .flag { color: #e0a548; } }
303
+ .sum { margin: 0 2px 10px; font-size: 13px; line-height: 1.45; color: var(--tm-graphite, #6c6c65); }
304
+ .sum .flag { margin-top: 4px; font-size: 12px; color: var(--tm-changed, #a35f00); }
306
305
  .what b { font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; }
307
- .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; }
308
- 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; }
309
- textarea:focus { border-color: #141413; background: #fff; }
306
+ .what code { font: 11.5px var(--tm-code, ui-monospace, Consolas, monospace); color: var(--tm-pencil, #9a9a92); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; flex: 1; }
307
+ textarea { width: 100%; min-height: 72px; max-height: 220px; resize: none; font: inherit; color: inherit; background: color-mix(in oklab, var(--tm-wash, #f2f2ef) 45%, var(--tm-sheet, #fff)); border: 1px solid var(--tm-rule, #e6e6e1); border-radius: 7px; padding: 9px 10px; outline: none; }
308
+ textarea:focus { border-color: var(--tm-ink, #141413); background: var(--tm-sheet, #fff); }
310
309
  .suggest { display: flex; flex-wrap: wrap; gap: 4px 14px; margin: 8px 2px 0; }
311
- .suggest button { all: unset; cursor: pointer; font-size: 12.5px; color: #141413; }
310
+ .suggest button { all: unset; cursor: pointer; font-size: 12.5px; color: var(--tm-ink, #141413); }
312
311
  .suggest button:hover { text-decoration: underline; text-underline-offset: 3px; }
313
312
  .foot { display: flex; align-items: center; gap: 8px; margin-top: 10px; }
314
313
  .foot .btn { white-space: nowrap; }
315
314
  .foot [data-act="details"] { padding-left: 2px; text-decoration: underline; text-underline-offset: 3px; }
316
- .hint { flex: 1; font-size: 11.5px; color: #9a9a92; line-height: 1.3; }
317
- .btn { all: unset; cursor: pointer; font: 500 13px/1 "Instrument Sans", system-ui, sans-serif; padding: 8px 11px; border-radius: 6px; color: #6c6c65; }
318
- .btn:hover { background: #f2f2ef; color: #141413; }
319
- .btn.primary { background: #141413; color: #fff; }
320
- .btn.primary:hover { background: #3a3a36; }
321
- .btn.danger { color: #c0392b; }
322
- .btn:focus-visible { outline: 2px solid #141413; outline-offset: 2px; }
323
- .ring { position: absolute; border: 1.5px solid #141413; border-radius: 8px; pointer-events: none; }
315
+ .hint { flex: 1; font-size: 11.5px; color: var(--tm-pencil, #9a9a92); line-height: 1.3; }
316
+ .btn { all: unset; cursor: pointer; font: 500 13px/1 var(--tm-font, system-ui, sans-serif); padding: 8px 11px; border-radius: 6px; color: var(--tm-graphite, #6c6c65); }
317
+ .btn:hover { background: var(--tm-wash, #f2f2ef); color: var(--tm-ink, #141413); }
318
+ .btn.primary { background: var(--tm-accent, #141413); color: var(--tm-accent-text, #fff); }
319
+ .btn.primary:hover { background: color-mix(in oklab, var(--tm-accent, #141413) 84%, var(--tm-sheet, #fff)); }
320
+ .btn.danger { color: var(--tm-broken, #c0392b); }
321
+ .btn:focus-visible { outline: 2px solid var(--tm-ink, #141413); outline-offset: 2px; }
322
+ .ring { position: absolute; border: 1.5px solid var(--tm-ink, #141413); border-radius: 8px; pointer-events: none; }
324
323
  .ring.active { border-width: 2px; }
325
- .ring.agent { border: 2px solid #141413; border-radius: 9px; }
326
- .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; }
327
- .bubble-who { font-size: 11.5px; font-weight: 600; color: #ffe27a; margin-bottom: 3px; }
324
+ .ring.agent { border: 2px solid var(--tm-ink, #141413); border-radius: 9px; }
325
+ .bubble { position: absolute; width: 300px; background: var(--tm-ink, #141413); color: var(--tm-paper, #fff); border-radius: 10px; padding: 10px 30px 11px 12px; box-shadow: 0 14px 34px -14px rgba(20,20,19,.5); font: 13.5px/1.5 var(--tm-font, system-ui, sans-serif); pointer-events: auto; }
326
+ .bubble-who { font-size: 11.5px; font-weight: 600; color: color-mix(in oklab, var(--tm-paper, #fff) 70%, var(--tm-mark, #ffe27a)); margin-bottom: 3px; }
328
327
  .bubble-text { white-space: pre-wrap; }
329
- .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; }
330
- .bubble-x:hover { color: #fff; background: rgba(255,255,255,.1); }
331
- .ring.noted { border-color: rgba(20, 20, 19, .35); }
332
- @media (prefers-color-scheme: dark) { .ring { border-color: #f2f2ee; } .ring.noted { border-color: rgba(242, 242, 238, .45); } }
333
- .pin { position: absolute; width: 20px; height: 20px; border-radius: 50%; background: #ffe27a; color: #141413;
334
- 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); }
335
- .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); }
336
- .select-btn:hover { background: #141413; }
337
- @media (prefers-color-scheme: dark) {
338
- .card { background: #1b1b1a; color: #f2f2ee; border-color: #44443f; box-shadow: 0 12px 32px -12px rgba(0,0,0,.6); }
339
- textarea { background: #161615; border-color: #2f2f2c; }
340
- textarea:focus { background: #161615; border-color: #f2f2ee; }
341
- .suggest button { color: #f2f2ee; }
342
- .btn { color: #a0a098; } .btn:hover { background: #252523; color: #f2f2ee; }
343
- .btn.primary { background: #f2f2ee; color: #141413; }
344
- .pin { border-color: #161615; }
345
- }
346
- .planact { position: absolute; display: flex; gap: 4px; padding: 4px; background: #fff; border: 1px solid #d2d2cb; border-radius: 999px; box-shadow: 0 8px 22px -10px rgba(20,20,19,.4); pointer-events: auto; z-index: 3; animation: pa-in .22s cubic-bezier(.2,.8,.3,1.2) both; }
328
+ .bubble-x { all: unset; position: absolute; top: 6px; right: 8px; cursor: pointer; color: color-mix(in oklab, var(--tm-paper, #fff) 60%, var(--tm-ink, #141413)); font-size: 16px; line-height: 1; padding: 2px 4px; border-radius: 4px; }
329
+ .bubble-x:hover { color: var(--tm-paper, #fff); background: color-mix(in oklab, var(--tm-paper, #fff) 12%, transparent); }
330
+ .ring.noted { border-color: color-mix(in oklab, var(--tm-ink, #141413) 40%, transparent); }
331
+ .pin { position: absolute; width: 20px; height: 20px; border-radius: 50%; background: var(--tm-mark, #ffe27a); color: var(--tm-ink, #141413);
332
+ font: 600 11px/20px var(--tm-code, ui-monospace, Consolas, monospace); text-align: center; cursor: pointer; border: 2px solid var(--tm-sheet, #fff); box-shadow: 0 1px 3px rgba(20,20,19,.25); }
333
+ .select-btn { position: absolute; all: unset; position: absolute; cursor: pointer; background: var(--tm-accent, #141413); color: var(--tm-accent-text, #fff); font: 500 12.5px/1 var(--tm-font, system-ui, sans-serif); padding: 7px 10px; border-radius: 6px; box-shadow: 0 6px 18px -8px rgba(20,20,19,.5); }
334
+ .select-btn:hover { background: var(--tm-accent, #141413); }
335
+ .planact { position: absolute; display: flex; gap: 4px; padding: 4px; background: var(--tm-sheet, #fff); border: 1px solid var(--tm-rule-strong, #d2d2cb); border-radius: 999px; box-shadow: 0 8px 22px -10px rgba(20,20,19,.4); pointer-events: auto; z-index: 3; animation: pa-in .22s cubic-bezier(.2,.8,.3,1.2) both; }
347
336
  @keyframes pa-in { from { opacity: 0; transform: translateY(4px) scale(.92); } to { opacity: 1; transform: none; } }
348
- .planact button { all: unset; display: grid; place-items: center; width: 26px; height: 26px; border-radius: 50%; cursor: pointer; color: #141413; transition: transform .12s ease, background-color .12s ease; }
349
- .planact button:hover { background: #f2f2ef; transform: scale(1.1); }
350
- .planact button.ok { background: #141413; color: #fff; }
351
- .planact button.ok:hover { background: #3a3a36; }
352
- .planact button:focus-visible { outline: 2px solid #141413; outline-offset: 2px; }
337
+ .planact button { all: unset; display: grid; place-items: center; width: 26px; height: 26px; border-radius: 50%; cursor: pointer; color: var(--tm-ink, #141413); transition: transform .12s ease, background-color .12s ease; }
338
+ .planact button:hover { background: var(--tm-wash, #f2f2ef); transform: scale(1.1); }
339
+ .planact button.ok { background: var(--tm-accent, #141413); color: var(--tm-accent-text, #fff); }
340
+ .planact button.ok:hover { background: color-mix(in oklab, var(--tm-accent, #141413) 84%, var(--tm-sheet, #fff)); }
341
+ .planact button:focus-visible { outline: 2px solid var(--tm-ink, #141413); outline-offset: 2px; }
353
342
  .planact svg { width: 14px; height: 14px; fill: none; stroke: currentColor; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; }
354
- .planact .wait { display: grid; place-items: center; width: 26px; height: 26px; border-radius: 50%; color: #2f7a4f; }
355
- .planact .wait.revise { color: #6c6c65; animation: pa-pulse 1.4s ease-in-out infinite; }
343
+ .planact .wait { display: grid; place-items: center; width: 26px; height: 26px; border-radius: 50%; color: var(--tm-fine, #2f7a4f); }
344
+ .planact .wait.revise { color: var(--tm-graphite, #6c6c65); animation: pa-pulse 1.4s ease-in-out infinite; }
356
345
  @keyframes pa-pulse { 50% { opacity: .35; } }
357
346
  @media (prefers-reduced-motion: reduce) { .planact, .planact .wait.revise { animation: none; } .planact button { transition: none; } }
358
- @media (prefers-color-scheme: dark) {
359
- .planact { background: #1b1b1a; border-color: #44443f; }
360
- .planact button { color: #f2f2ee; } .planact button:hover { background: #252523; }
361
- .planact button.ok { background: #f2f2ee; color: #141413; }
362
- .planact .wait { color: #7cc49c; }
363
- }
364
347
  </style><div id="rings"></div><div id="pins"></div><div id="slot"></div><div id="planact"></div>`;
365
- { const st = shadow.querySelector('style'); if (typeof tmThemeable === 'function') st.textContent = tmThemeable(st.textContent, { host: true }); }
366
348
  const applyTheme = (t) => {
367
349
  if (t === 'light' || t === 'dark') document.documentElement.setAttribute('data-theme', t); else document.documentElement.removeAttribute('data-theme');
368
- host.classList.toggle('tm-dark', t === 'dark'); host.classList.toggle('tm-light', t === 'light');
369
350
  };
370
351
  applyTheme(document.documentElement.getAttribute('data-theme'));
371
352
  const pinsEl = shadow.getElementById('pins');
@@ -489,7 +470,7 @@ el.querySelector('.hint').textContent = ''; el.querySelector('[data-act="add"]')
489
470
  el.addEventListener('click', (e) => {
490
471
  const act = e.target.closest('[data-act]')?.dataset.act;
491
472
  if (act === 'add') finish(planComment);
492
- else if (act === 'details') peek(target);
473
+ else if (act === 'details') { closeCard(); peek(target); }
493
474
  else if (act === 'comment') { el.classList.remove('viewing'); el.setAttribute('aria-label', 'Comment'); ta.focus({ preventScroll: true }); }
494
475
  else if (act === 'cancel') closeCard();
495
476
  else if (act === 'remove') { removeNote(noteId, true); closeCard(); }
@@ -1,39 +1,24 @@
1
- @font-face { font-family: "Instrument Sans"; font-weight: 400; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-400-normal.woff2") format("woff2"); }
2
- @font-face { font-family: "Instrument Sans"; font-weight: 500; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-500-normal.woff2") format("woff2"); }
3
- @font-face { font-family: "Instrument Sans"; font-weight: 600; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-600-normal.woff2") format("woff2"); }
4
- @font-face { font-family: "Commit Mono"; font-weight: 400; font-display: swap; src: url("/__truemap/fonts/commit-mono-latin-400-normal.woff2") format("woff2"); }
5
-
6
- /* One fixed system: neutrals and ink carry structure and selection. The accent (ink by default, the
7
- project's own colour when truemap finds one) marks the primary action. A highlighter marks what the
8
- agent points at. Status colours mean status and nothing else. */
1
+ /* Colours and fonts come from /__truemap/tokens.css (truemap's tokens, then the project's theme.css),
2
+ so the workspace and the pages always share one look. These names are the workspace's shorthand. */
9
3
  :root {
10
- --bg: #ffffff;
11
- --chrome: #fafaf9;
12
- --surface: #f2f2ef;
13
- --line: #e6e6e1;
14
- --line-strong: #d2d2cb;
15
- --ink: #141413;
16
- --text: #2b2b28;
17
- --muted: #6c6c65;
18
- --faint: #9a9a92;
19
- --accent: #141413;
20
- --accent-text: #ffffff;
21
- --mark: #ffe27a;
22
- --changed: #a35f00;
23
- --broken: #c0392b;
24
- --fine: #2f7a4f;
25
- --font: "Instrument Sans", system-ui, -apple-system, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
26
- --code: "Commit Mono", ui-monospace, "SF Mono", "Cascadia Mono", Consolas, monospace;
4
+ --bg: var(--tm-paper);
5
+ --chrome: var(--tm-chrome);
6
+ --surface: var(--tm-wash);
7
+ --line: var(--tm-rule);
8
+ --line-strong: var(--tm-rule-strong);
9
+ --ink: var(--tm-ink);
10
+ --text: var(--tm-text);
11
+ --muted: var(--tm-graphite);
12
+ --faint: var(--tm-pencil);
13
+ --accent: var(--tm-accent);
14
+ --accent-text: var(--tm-accent-text);
15
+ --mark: var(--tm-mark);
16
+ --changed: var(--tm-changed);
17
+ --broken: var(--tm-broken);
18
+ --fine: var(--tm-fine);
19
+ --font: var(--tm-font);
20
+ --code: var(--tm-code);
27
21
  --panel-w: 420px;
28
- color-scheme: light dark;
29
- }
30
- @media (prefers-color-scheme: dark) {
31
- :root {
32
- --bg: #161615; --chrome: #1b1b1a; --surface: #252523; --line: #2f2f2c; --line-strong: #44443f;
33
- --ink: #f2f2ee; --text: #dadad4; --muted: #a0a098; --faint: #75756e;
34
- --accent: #f2f2ee; --accent-text: #141413; --mark: #6b5a12;
35
- --changed: #e0a548; --broken: #ef8574; --fine: #7cc49c;
36
- }
37
22
  }
38
23
 
39
24
  * { box-sizing: border-box; }
@@ -6,6 +6,7 @@
6
6
  <meta name="referrer" content="no-referrer">
7
7
  <title>truemap</title>
8
8
  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns=%27http://www.w3.org/2000/svg%27 viewBox=%270 0 20 20%27%3E%3Cpath d=%27M10 2.2 15.6 17.6 10 14.4 4.4 17.6z%27 fill=%27%23fff%27 stroke=%27%2317202b%27 stroke-width=%271.5%27 stroke-linejoin=%27round%27/%3E%3Cpath d=%27M10 2.2V14.4L4.4 17.6z%27 fill=%27%23141413%27/%3E%3C/svg%3E">
9
+ <link rel="stylesheet" href="/__truemap/tokens.css" id="tokensCss">
9
10
  <link rel="stylesheet" href="/__truemap/workspace.css">
10
11
  <script>window.TRUEMAP_TOKEN = "__TRUEMAP_TOKEN__"; window.TRUEMAP_CONTENT = "__TRUEMAP_CONTENT__";</script>
11
12
  </head>
@@ -151,6 +151,20 @@
151
151
  });
152
152
  $('recheck').onclick = () => { api('/api/check'); closeMenu(); };
153
153
 
154
+ // ---------- browser translation ----------
155
+ // Chrome's page translation translates text it sees appear. A menu written in the HTML and shown later only
156
+ // changes its hidden attribute, so it would stay untranslated: give its text to the translator again.
157
+ const translating = () => /\btranslated-(ltr|rtl)\b/.test(document.documentElement.className);
158
+ new MutationObserver((ms) => {
159
+ if (!translating()) return;
160
+ for (const m of ms) {
161
+ if (m.target.hidden) continue;
162
+ const walk = document.createTreeWalker(m.target, NodeFilter.SHOW_TEXT); const nodes = [];
163
+ while (walk.nextNode()) if (walk.currentNode.nodeValue.trim() && !walk.currentNode.parentElement.closest('code, [translate="no"]')) nodes.push(walk.currentNode);
164
+ for (const n of nodes) n.replaceWith(document.createTextNode(n.nodeValue));
165
+ }
166
+ }).observe(document.body, { subtree: true, attributes: true, attributeFilter: ['hidden'] });
167
+
154
168
  // ---------- more menu: the page file, export, end the conversation ----------
155
169
  const more = $('moreMenu');
156
170
  const filePath = () => {
@@ -284,7 +298,7 @@
284
298
  function renderAll() {
285
299
  msgsEl.innerHTML = ''; lastRole = null;
286
300
  if (!state.history.length) {
287
- msgsEl.innerHTML = `<div class="intro"><p>Ask about anything on the page. <b>Click a box</b> to see what it is; <b>double-click</b> it to write a comment right there. Comments go out together, each with the code it points to.</p></div>`;
301
+ msgsEl.innerHTML = `<div class="intro"><p>Ask about anything on the page. <b>Click a box</b> to light up what it connects to; <b>double-click</b> it to see what it is and comment right there. Comments go out together, each with the code it points to.</p></div>`;
288
302
  }
289
303
  for (const e of state.history) appendEntry(e, false);
290
304
  renderWorking();
@@ -349,17 +363,26 @@
349
363
  }
350
364
  const scrollChat = () => { msgsEl.scrollTop = msgsEl.scrollHeight; };
351
365
  let hoverLit = null;
366
+ let pinnedFocus = null;
367
+ const endPreview = () => {
368
+ msgsEl.querySelector('li.lit')?.classList.remove('lit');
369
+ const keep = pinnedFocus && pinnedFocus.page === state.page ? pinnedFocus.msg : null;
370
+ hoverLit = keep ? '__pinned' : null;
371
+ toFrame(keep ? { ...keep, scroll: false } : { type: 'clear-focus' });
372
+ };
373
+ const unpin = () => { pinnedFocus = null; if (hoverLit === '__pinned') hoverLit = null; };
352
374
  msgsEl.addEventListener('mouseover', (e) => {
353
375
  const host = e.target.closest('li.has-ref, a.ref');
354
376
  const ids = host ? [...new Set([...(host.matches('a.ref') ? [host] : host.querySelectorAll('a.ref'))].flatMap((r) => r.dataset.focus.split(',')).filter(Boolean))] : null;
355
377
  const key = ids ? ids.join(',') : null;
356
378
  if (key === hoverLit || (!key && (hoverLit === '__pinned' || !hoverLit))) return;
379
+ if (!ids) return endPreview();
357
380
  msgsEl.querySelector('li.lit')?.classList.remove('lit');
358
381
  hoverLit = key;
359
- if (ids) { if (host.matches('li')) host.classList.add('lit'); toFrame({ type: 'focus', items: ids, note: '', who: '', scroll: false, transient: true }); }
360
- else toFrame({ type: 'clear-focus' });
382
+ if (host.matches('li')) host.classList.add('lit');
383
+ toFrame({ type: 'focus', items: ids, note: '', who: '', scroll: false, transient: true });
361
384
  });
362
- msgsEl.addEventListener('mouseleave', () => { if (hoverLit && hoverLit !== '__pinned') { hoverLit = null; msgsEl.querySelector('li.lit')?.classList.remove('lit'); toFrame({ type: 'clear-focus' }); } });
385
+ msgsEl.addEventListener('mouseleave', () => { if (hoverLit && hoverLit !== '__pinned') endPreview(); });
363
386
  msgsEl.addEventListener('click', (e) => {
364
387
  const cc = e.target.closest('.cc-row');
365
388
  if (cc) { if (cc.dataset.page !== state.page) { state.pendingOpen = cc.dataset.src; go(cc.dataset.page); } else toFrame({ type: 'open-box', src: cc.dataset.src }); return; }
@@ -385,6 +408,7 @@
385
408
  function pointAt(items, note, who, page) {
386
409
  const target = page && state.pages.some((p) => p.page === page) ? page : state.page;
387
410
  const msg = { type: 'focus', items, note: note || '', who: who || agentName() };
411
+ pinnedFocus = { page: target, msg }; hoverLit = '__pinned';
388
412
  if (target && target !== state.page) { state.pendingFocus = msg; go(target); } else toFrame(msg);
389
413
  }
390
414
 
@@ -503,10 +527,15 @@
503
527
  else if (act === 'links') pointAt([box.id, ...box.to.map((c) => c.id), ...box.from.map((c) => c.id)], '', '');
504
528
  };
505
529
  }
530
+ // Escape lets go of a highlight (the chip's, a clicked link's), wherever the cursor is.
531
+ document.addEventListener('keydown', (e) => {
532
+ if (e.key !== 'Escape' || inspecting() || !menu.hidden || !$('moreMenu').hidden || (!pinnedFocus && $('litPill').hidden)) return;
533
+ unpin(); toFrame({ type: 'clear-focus' }); $('litPill').hidden = true;
534
+ });
506
535
  document.addEventListener('keydown', (e) => {
507
536
  if (e.key !== 'Escape' || !inspecting() || !menu.hidden || !$('moreMenu').hidden) return;
508
537
  if (e.target.closest?.('.insp-comment') && e.target.value) return;
509
- closeInspector(); toFrame({ type: 'clear-focus' }); e.stopPropagation();
538
+ closeInspector(); unpin(); toFrame({ type: 'clear-focus' }); e.stopPropagation();
510
539
  }, true);
511
540
 
512
541
  // "Ask about this": the box goes along with the next message.
@@ -859,7 +888,7 @@
859
888
  pointAt(stale.map((a) => a.src), broken ? 'These boxes no longer match the code.' : 'The code under these boxes changed after this page was written.', 'truemap');
860
889
  setPanel(true); setTab('convo');
861
890
  if (!input.value.trim()) { input.value = `The code under ${stale.map((a) => a.src.split('#')[1] || a.path).join(', ')} changed. Check whether the map still says the right thing about ${stale.length > 1 ? 'them' : 'it'}: fix what is wrong, confirm the rest.`; autosize(); }
862
- input.focus();
891
+ input.focus(); requestAnimationFrame(scrollChat);
863
892
  };
864
893
 
865
894
  // A decision only counts as the user's if the user actually moved focus into the page.
@@ -903,7 +932,7 @@
903
932
  $('litPill').hidden = !n || !!d.transient;
904
933
  $('litText').textContent = n === 1 ? '1 box lit' : `${n} boxes lit`;
905
934
  } else if (d.type === 'focus-cleared') {
906
- $('litPill').hidden = true;
935
+ $('litPill').hidden = true; unpin();
907
936
  } else if (d.type === 'plan-act') {
908
937
  if (d.act === 'approve') {
909
938
  if (state.notes.length || input.value.trim()) { const t = input.value; input.value = ''; autosize(); await send(t, { approving: true }); }
@@ -928,7 +957,7 @@
928
957
  }
929
958
  });
930
959
 
931
- $('litClear').onclick = () => { toFrame({ type: 'clear-focus' }); $('litPill').hidden = true; };
960
+ $('litClear').onclick = () => { unpin(); toFrame({ type: 'clear-focus' }); $('litPill').hidden = true; };
932
961
 
933
962
  // ---------- live events from the server ----------
934
963
  let closedTimer = null;
@@ -985,6 +1014,7 @@
985
1014
  else if (state.page && !state.pages.some((p) => p.page === state.page)) state.pages[0] ? go(state.pages[0].page) : showEmpty();
986
1015
  } else if (d.type === 'changed') {
987
1016
  const files = d.files || [];
1017
+ if (files.some((f) => !f || f.startsWith('assets/'))) $('tokensCss').href = `/__truemap/tokens.css?v=${Date.now()}`;
988
1018
  if (state.page && files.some((f) => !f || f === state.page || f.startsWith('assets/'))) reloadFrame();
989
1019
  } else if (d.type === 'check') {
990
1020
  state.check = d.check || { results: [] }; renderHeader(); sendMarks(); if (!menu.hidden) renderMenu();
@@ -993,10 +1023,10 @@
993
1023
  if (d.page && state.pages.some((p) => p.page === d.page)) go(d.page, { force: true });
994
1024
  renderHeader();
995
1025
  } else if (d.type === 'show') {
996
- if (d.clear) toFrame({ type: 'clear-focus' });
1026
+ if (d.clear) { unpin(); toFrame({ type: 'clear-focus' }); }
997
1027
  else pointAt(d.focus || [], d.note || '', AGENTS[d.agent] || agentName(), d.page);
998
1028
  } else if (d.type === 'plan') {
999
- if (hoverLit && hoverLit !== '__pinned') { hoverLit = null; msgsEl.querySelector('li.lit')?.classList.remove('lit'); toFrame({ type: 'clear-focus' }); }
1029
+ msgsEl.querySelector('li.lit')?.classList.remove('lit'); unpin();
1000
1030
  $('litPill').hidden = true; toFrame({ type: 'clear-focus' });
1001
1031
  state.plan = d.plan || null; renderPlan(); sendPlan(); renderNotes();
1002
1032
  } else if (d.type === 'changes-base') {