@jossuealcala/madre 1.0.4 → 1.1.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.
Files changed (273) hide show
  1. package/ADDITIONAL-TERMS.md +7 -2
  2. package/CHANGELOG.en.md +152 -1
  3. package/CHANGELOG.md +152 -1
  4. package/CONTRIBUTING.md +2 -2
  5. package/LICENSE +111 -661
  6. package/NOTICE +59 -24
  7. package/README.en.md +36 -204
  8. package/README.md +36 -210
  9. package/SECURITY.md +1 -0
  10. package/TRADEMARKS.en.md +13 -14
  11. package/TRADEMARKS.md +42 -26
  12. package/bin/madre.cjs +2 -2
  13. package/bin/madre.mjs +114 -42
  14. package/docs/REFERENCE.md +53 -6
  15. package/docs/SDK.md +44 -5
  16. package/docs/en/REFERENCE.md +53 -6
  17. package/docs/en/SDK.md +43 -4
  18. package/docs/madre-banner.png +0 -0
  19. package/docs/sdk/hello-module.mjs +3 -0
  20. package/package.json +3 -2
  21. package/public/abduction.js +6 -6
  22. package/public/activity.js +425 -0
  23. package/public/app.js +3519 -647
  24. package/public/assets/abduction-cat-blink.webp +0 -0
  25. package/public/assets/abduction-cat-control-left.webp +0 -0
  26. package/public/assets/abduction-cat-control-right.webp +0 -0
  27. package/public/assets/abduction-cat.webp +0 -0
  28. package/public/assets/manual/shots/en-agents.webp +0 -0
  29. package/public/assets/manual/shots/en-chats.webp +0 -0
  30. package/public/assets/manual/shots/en-code.webp +0 -0
  31. package/public/assets/manual/shots/en-composer.webp +0 -0
  32. package/public/assets/manual/shots/en-connectors.webp +0 -0
  33. package/public/assets/manual/shots/en-continuity.webp +0 -0
  34. package/public/assets/manual/shots/en-coordinator.webp +0 -0
  35. package/public/assets/manual/shots/en-copilot.webp +0 -0
  36. package/public/assets/manual/shots/en-diagnostics.webp +0 -0
  37. package/public/assets/manual/shots/en-home.webp +0 -0
  38. package/public/assets/manual/shots/en-local.webp +0 -0
  39. package/public/assets/manual/shots/en-market.webp +0 -0
  40. package/public/assets/manual/shots/en-memory.webp +0 -0
  41. package/public/assets/manual/shots/en-modes.webp +0 -0
  42. package/public/assets/manual/shots/en-notes.webp +0 -0
  43. package/public/assets/manual/shots/en-settings.webp +0 -0
  44. package/public/assets/manual/shots/en-welcome.webp +0 -0
  45. package/public/assets/manual/shots/en-windows.webp +0 -0
  46. package/public/assets/manual/shots/es-agents.webp +0 -0
  47. package/public/assets/manual/shots/es-chats.webp +0 -0
  48. package/public/assets/manual/shots/es-code.webp +0 -0
  49. package/public/assets/manual/shots/es-composer.webp +0 -0
  50. package/public/assets/manual/shots/es-connectors.webp +0 -0
  51. package/public/assets/manual/shots/es-continuity.webp +0 -0
  52. package/public/assets/manual/shots/es-coordinator.webp +0 -0
  53. package/public/assets/manual/shots/es-copilot.webp +0 -0
  54. package/public/assets/manual/shots/es-diagnostics.webp +0 -0
  55. package/public/assets/manual/shots/es-home.webp +0 -0
  56. package/public/assets/manual/shots/es-local.webp +0 -0
  57. package/public/assets/manual/shots/es-market.webp +0 -0
  58. package/public/assets/manual/shots/es-memory.webp +0 -0
  59. package/public/assets/manual/shots/es-modes.webp +0 -0
  60. package/public/assets/manual/shots/es-notes.webp +0 -0
  61. package/public/assets/manual/shots/es-settings.webp +0 -0
  62. package/public/assets/manual/shots/es-welcome.webp +0 -0
  63. package/public/assets/manual/shots/es-windows.webp +0 -0
  64. package/public/assets/news/1.1/en/chats.webp +0 -0
  65. package/public/assets/news/1.1/en/home.webp +0 -0
  66. package/public/assets/news/1.1/en/maps.webp +0 -0
  67. package/public/assets/news/1.1/en/market.webp +0 -0
  68. package/public/assets/news/1.1/en/permissions.webp +0 -0
  69. package/public/assets/news/1.1/en/privacy.webp +0 -0
  70. package/public/assets/news/1.1/en/welcome.webp +0 -0
  71. package/public/assets/news/1.1/es/chats.webp +0 -0
  72. package/public/assets/news/1.1/es/home.webp +0 -0
  73. package/public/assets/news/1.1/es/maps.webp +0 -0
  74. package/public/assets/news/1.1/es/market.webp +0 -0
  75. package/public/assets/news/1.1/es/permissions.webp +0 -0
  76. package/public/assets/news/1.1/es/privacy.webp +0 -0
  77. package/public/assets/news/1.1/es/welcome.webp +0 -0
  78. package/public/attribution.js +15 -16
  79. package/public/brands.js +2 -2
  80. package/public/code-tools.js +2 -2
  81. package/public/editor.js +13 -13
  82. package/public/en.js +483 -0
  83. package/public/es.js +1817 -598
  84. package/public/hardware.js +2 -2
  85. package/public/i18n.js +47 -9
  86. package/public/icons.js +158 -0
  87. package/public/index.html +68 -51
  88. package/public/inquiry.js +2 -2
  89. package/public/loader.js +271 -2
  90. package/public/macroverso.js +60 -21
  91. package/public/manual-content.js +900 -0
  92. package/public/manual-shots.js +47 -0
  93. package/public/manual.css +246 -0
  94. package/public/manual.html +15 -0
  95. package/public/manual.js +427 -0
  96. package/public/market-art.js +99 -41
  97. package/public/market-view.js +243 -47
  98. package/public/market.js +139 -26
  99. package/public/mcp-catalog.js +62 -0
  100. package/public/neural.js +64 -8
  101. package/public/nostromo-engine.js +709 -40
  102. package/public/page-errors.js +29 -0
  103. package/public/power.js +350 -11
  104. package/public/remedy.js +89 -0
  105. package/public/resay.js +4 -2
  106. package/public/review-ask.js +12 -7
  107. package/public/routing.js +3 -3
  108. package/public/salas-mac.css +875 -48
  109. package/public/salas-mac.html +27 -15
  110. package/public/salas-mac.js +1668 -338
  111. package/public/salas.css +2 -2
  112. package/public/salas.html +3 -3
  113. package/public/salas.js +3 -3
  114. package/public/styles.css +2694 -323
  115. package/public/syntax.js +2 -2
  116. package/public/terms.js +152 -0
  117. package/public/touch.js +2 -2
  118. package/public/tour-chapters.js +100 -92
  119. package/public/tour.js +118 -28
  120. package/public/troubleshooting.js +327 -21
  121. package/public/wallpaper.js +4 -3
  122. package/public/welcome.js +923 -0
  123. package/src/activity.mjs +85 -0
  124. package/src/adapters/claude.mjs +61 -35
  125. package/src/adapters/codex.mjs +18 -5
  126. package/src/adapters/cursor.mjs +60 -9
  127. package/src/adapters/gemini.mjs +17 -4
  128. package/src/adapters/madre.mjs +30 -9
  129. package/src/adapters/opencode.mjs +73 -10
  130. package/src/adapters/process.mjs +19 -15
  131. package/src/adapters/subagents.mjs +159 -0
  132. package/src/asking.mjs +8 -2
  133. package/src/auth-probe.mjs +47 -11
  134. package/src/bridge/devices.mjs +2 -2
  135. package/src/bridge/handoff.mjs +2 -2
  136. package/src/bridge/host.mjs +2 -2
  137. package/src/bridge/network.mjs +2 -2
  138. package/src/bridge/policy.mjs +3 -3
  139. package/src/bridge/qr.mjs +2 -2
  140. package/src/bridge/server.mjs +3 -3
  141. package/src/builtin-updates.mjs +87 -0
  142. package/src/capabilities.mjs +5 -5
  143. package/src/chats.mjs +51 -2
  144. package/src/checkpoint.mjs +67 -9
  145. package/src/choices.mjs +2 -2
  146. package/src/cli-args.mjs +2 -2
  147. package/src/cold.mjs +2 -2
  148. package/src/commands.mjs +2 -2
  149. package/src/config.mjs +2 -2
  150. package/src/conversation-context.mjs +2 -2
  151. package/src/credentials.mjs +80 -18
  152. package/src/dataset.mjs +2 -2
  153. package/src/directives.mjs +2 -2
  154. package/src/distiller.mjs +2 -2
  155. package/src/embeddings.mjs +2 -2
  156. package/src/enlaces.mjs +2 -2
  157. package/src/environment.mjs +147 -0
  158. package/src/event-store.mjs +2 -2
  159. package/src/exam.mjs +2 -2
  160. package/src/extensions.mjs +2 -2
  161. package/src/eyecat-watch.mjs +2 -2
  162. package/src/eyecat.mjs +2 -2
  163. package/src/file-ops.mjs +2 -2
  164. package/src/files.mjs +2 -2
  165. package/src/github.mjs +2 -2
  166. package/src/heartbeat.mjs +2 -2
  167. package/src/history.mjs +76 -0
  168. package/src/i18n.mjs +32 -3
  169. package/src/image-studio.mjs +2 -2
  170. package/src/install-metrics.mjs +109 -0
  171. package/src/json-file.mjs +2 -2
  172. package/src/launch.mjs +2 -2
  173. package/src/lease.mjs +15 -4
  174. package/src/lobby-work.mjs +11 -4
  175. package/src/local-ai.mjs +12 -4
  176. package/src/looks.mjs +19 -7
  177. package/src/market-check.mjs +165 -0
  178. package/src/market-key.mjs +10 -2
  179. package/src/market-license.mjs +104 -0
  180. package/src/market-remote.mjs +71 -13
  181. package/src/maturity.mjs +2 -2
  182. package/src/mcp/connect.mjs +2 -2
  183. package/src/mcp/github-server.mjs +2 -2
  184. package/src/mcp/image-server.mjs +2 -2
  185. package/src/mcp/memory-server.mjs +2 -2
  186. package/src/mcp/proxy.mjs +16 -5
  187. package/src/mcp/smtp-server.mjs +2 -2
  188. package/src/memory-dashboard.mjs +2 -2
  189. package/src/memory-tools.mjs +2 -2
  190. package/src/memory.mjs +2 -2
  191. package/src/models.mjs +115 -12
  192. package/src/module-scope.mjs +2 -2
  193. package/src/modules/ahp.mjs +2 -2
  194. package/src/modules/ash-policy.mjs +2 -2
  195. package/src/modules/ash.mjs +2 -2
  196. package/src/modules/bishop-exam.mjs +2 -2
  197. package/src/modules/bishop-plan.mjs +2 -2
  198. package/src/modules/bishop.mjs +9 -3
  199. package/src/modules/choices.mjs +2 -2
  200. package/src/modules/correo.mjs +2 -2
  201. package/src/modules/enlaces.mjs +2 -2
  202. package/src/modules/git-pulse.mjs +2 -2
  203. package/src/modules/github.mjs +2 -2
  204. package/src/modules/helpers.mjs +2 -2
  205. package/src/modules/image-studio.mjs +2 -2
  206. package/src/modules/index.mjs +92 -5
  207. package/src/modules/intents-calibration.mjs +2 -2
  208. package/src/modules/intents-desk.mjs +4 -3
  209. package/src/modules/intents-observe.mjs +2 -2
  210. package/src/modules/intents-policy.mjs +2 -2
  211. package/src/modules/intents-try.mjs +2 -2
  212. package/src/modules/intents.mjs +2 -2
  213. package/src/modules/local-models.mjs +41 -10
  214. package/src/modules/mcp-connect.mjs +2 -2
  215. package/src/modules/notes.mjs +281 -0
  216. package/src/modules/ollama.mjs +48 -13
  217. package/src/modules/playwright.mjs +16 -5
  218. package/src/modules/reminders.mjs +664 -0
  219. package/src/modules/ripley.mjs +3 -3
  220. package/src/modules/runs.mjs +2 -2
  221. package/src/modules/sdk.mjs +57 -9
  222. package/src/modules/updates.mjs +2 -2
  223. package/src/mother.mjs +13 -3
  224. package/src/npm-launch.mjs +2 -2
  225. package/src/ollama.mjs +8 -6
  226. package/src/opencode-health.mjs +83 -0
  227. package/src/outbound.mjs +35 -3
  228. package/src/override.mjs +27 -22
  229. package/src/ports.mjs +2 -2
  230. package/src/prices.mjs +2 -2
  231. package/src/privacy.mjs +2 -2
  232. package/src/quota-monitor.mjs +2 -2
  233. package/src/quota-sources.mjs +2 -2
  234. package/src/request-guard.mjs +2 -2
  235. package/src/review-ask.mjs +4 -3
  236. package/src/room/archivist.mjs +2 -2
  237. package/src/room/attachments.mjs +2 -2
  238. package/src/room/budget.mjs +2 -2
  239. package/src/room/context.mjs +2 -2
  240. package/src/room/control.mjs +2 -2
  241. package/src/room/copilot.mjs +2 -2
  242. package/src/room/economy.mjs +2 -2
  243. package/src/room/escalation.mjs +2 -2
  244. package/src/room/ghost.mjs +2 -2
  245. package/src/room/guard.mjs +6 -4
  246. package/src/room/prompt.mjs +3 -3
  247. package/src/room/returns.mjs +2 -2
  248. package/src/room/runs.mjs +6 -4
  249. package/src/room/vectors.mjs +2 -2
  250. package/src/room.mjs +144 -36
  251. package/src/router.mjs +2 -2
  252. package/src/runs.mjs +2 -2
  253. package/src/runtime-detection.mjs +36 -6
  254. package/src/salas.mjs +31 -6
  255. package/src/sentinel-errors.mjs +17 -7
  256. package/src/server-sentinel.mjs +2 -2
  257. package/src/server.mjs +980 -139
  258. package/src/setup-trouble.mjs +33 -0
  259. package/src/setup.mjs +4 -4
  260. package/src/smtp.mjs +2 -2
  261. package/src/telemetry.mjs +266 -0
  262. package/src/terms.mjs +43 -0
  263. package/src/tour.mjs +60 -7
  264. package/src/uninstall.mjs +225 -0
  265. package/src/updates.mjs +2 -2
  266. package/src/usage-sentinel.mjs +2 -2
  267. package/src/vault.mjs +2 -2
  268. package/src/verdict.mjs +13 -10
  269. package/src/whats-new.mjs +97 -3
  270. package/public/assets/abduction-cat-blink.png +0 -0
  271. package/public/assets/abduction-cat-control-left.png +0 -0
  272. package/public/assets/abduction-cat-control-right.png +0 -0
  273. package/public/assets/abduction-cat.png +0 -0
package/public/tour.js CHANGED
@@ -1,5 +1,5 @@
1
- // SPDX-License-Identifier: AGPL-3.0-only
2
- // MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
1
+ // SPDX-License-Identifier: BUSL-1.1
2
+ // MADRE · © 2026 Jossue Alcalá · Business Source License 1.1: LICENSE
3
3
  // The welcome of MADRE 1.0 (2026-10-11), in Home and in every project: option B of «Recorrido de
4
4
  // MADRE 1.0» — a bonjour, then a window of chapters read at the person's own pace — with two
5
5
  // pieces of option C: a one-line hint the first time someone reaches a place that confuses, and
@@ -17,18 +17,22 @@
17
17
  // assistant that connects agents and adds projects; then the chapters tell the essentials, in the
18
18
  // order they are used (public/tour-chapters.js, ORDER).
19
19
 
20
- import { LOADER_MARK, finishLoader, makeLoader, setLoader } from './loader.js';
21
- import { language, t } from './i18n.js';
20
+ import { LOADER_MARK, MADRE_LOGO, finishLoader, makeLoader, setLoader } from './loader.js';
21
+ import { hostWords, keyWords, language, t } from './i18n.js';
22
22
  import { CHAPTERS, GESTURES, ORDER } from './tour-chapters.js';
23
+ import { trazo } from './icons.js';
23
24
 
24
25
  const say = (pair) => (typeof pair === 'string' ? pair : pair?.[language()] ?? pair?.es ?? '');
26
+ // The chapters' own words, said of the computer and the keyboard in front of the person: «tu Mac» is
27
+ // the machine's name off a Mac, ⌘ is Ctrl+ there (i18n.js).
28
+ const plain = (text) => hostWords(keyWords(text));
25
29
  const fill = (template, vars) => template.replace(/\{(\w+)\}/g, (whole, name) => (Object.hasOwn(vars, name) ? String(vars[name]) : whole));
26
30
  const still = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
27
31
  // Up, turned for down: the way to a hint whose place is out of view.
28
- const ARROW_UP = '<svg viewBox="0 0 20 20" aria-hidden="true"><path d="M10 15.5V4.5M5.5 9 10 4.5 14.5 9" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/></svg>';
29
- const CLOSE_ICON = '<svg viewBox="0 0 20 20" aria-hidden="true"><path d="M5.5 5.5l9 9M14.5 5.5l-9 9" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>';
32
+ const ARROW_UP = trazo('arrow-up');
33
+ const CLOSE_ICON = trazo('close');
30
34
  const FOLDER = '<svg viewBox="0 0 32 26" aria-hidden="true"><path d="M2 5.5A2.5 2.5 0 0 1 4.5 3h7.2l3 3.2h12.8A2.5 2.5 0 0 1 30 8.7v12.8a2.5 2.5 0 0 1-2.5 2.5h-23A2.5 2.5 0 0 1 2 21.5z" fill="currentColor"/></svg>';
31
- const ROBOT = '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="5" y="8" width="14" height="11" rx="3.5" fill="none" stroke="currentColor" stroke-width="1.8"/><path d="M12 4.5V8M3 13v2M21 13v2" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/><circle cx="9.5" cy="13.5" r="1.3" fill="currentColor"/><circle cx="14.5" cy="13.5" r="1.3" fill="currentColor"/></svg>';
35
+ const ROBOT = trazo('robot');
32
36
 
33
37
  function el(tag, className = null, text = null) {
34
38
  const node = document.createElement(tag);
@@ -137,6 +141,14 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
137
141
  // Three people (src/tour.mjs): new, back from 0.7.2, or back from 1.0 (`since`).
138
142
  const path = () => state?.path ?? (info?.from === '1.0' ? 'since' : info?.returning ? 'back' : 'new');
139
143
  const chapters = () => (ORDER[path()] ?? ORDER.new).filter((id) => !hidden().includes(id)).map((id) => CHAPTERS.find((chapter) => chapter.id === id)).filter((chapter) => chapter && (!chapter.only || chapter.only === language()));
144
+ // Who meets MADRE now and who knew it before (src/tour.mjs: `met`, written on the bonjour, and the
145
+ // version whose news this code tells). Whoever knew it is told only what is new — the cards of
146
+ // news, and for whoever came from 0.7.2 what «Connections» means now — never again what each key
147
+ // is (2026-10-21): they were shown cards of things they had used for months.
148
+ const below = (a, b) => { const x = String(a).split('.').map(Number); const y = String(b).split('.').map(Number); for (let i = 0; i < 3; i += 1) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) < (y[i] ?? 0); return false; };
149
+ const returning = () => Boolean(state?.bonjourAt) && (!state.met || (Boolean(info?.level) && below(state.met, info.level)));
150
+ const newcomer = () => Boolean(state?.bonjourAt) && !returning();
151
+ const forThem = (id) => !returning() || id.startsWith('new-') || (id === 'links' && path() === 'back');
140
152
  const busyWith = () => Boolean(windowNode?.open || sheetNode?.open || document.querySelector('dialog.tour-bonjour[open]'));
141
153
 
142
154
  // ---- One tab at a time. The tab that shows the bonjour or the chapters holds the tour and says
@@ -236,6 +248,20 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
236
248
  if (fresh?.state) state = fresh.state;
237
249
  if (!fresh?.owed) return false;
238
250
  if (heldElsewhere(fresh.state)) { elsewhere(); return false; }
251
+ // Someone new in Home meets the welcome itself (2026-10-28, public/welcome.js), with no bonjour
252
+ // before it to put off: it is what leaves MADRE ready, and its last step leads to the chapters.
253
+ // Whoever updated from a MADRE before 1.1.0 is not new (2026-10-30): the board of news, with
254
+ // MADRE's opening, is their way in (salas-mac.js, homeNews); no welcome, no bonjour on top of it.
255
+ if (info?.upgraded) {
256
+ await keep({ path: path() === 'new' ? 'back' : path(), bonjour: true });
257
+ return false;
258
+ }
259
+ if (page === 'home' && path() === 'new' && welcome?.instead) {
260
+ await keep({ path: 'new', bonjour: true });
261
+ void fetch('/api/whats-new/seen', { method: 'POST' }).catch(() => null);
262
+ welcome.open(() => openChapters('home'));
263
+ return true;
264
+ }
239
265
  showBonjour();
240
266
  return true;
241
267
  }
@@ -251,14 +277,14 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
251
277
  const title = el('h1', 'tour-hello', back || since ? t('Hello again.') : t('Hello.'));
252
278
  title.id = 'tour-bonjour-title';
253
279
  const body = el('p', 'tour-hello-says', since
254
- ? t('Since 1.0, Home became a board you arrange, with widgets; the local AI is chosen project by project, and MADRE speaks more plainly. I tell you what changed, at your own pace.')
280
+ ? t('Since 1.0, Home became a board you arrange, with widgets; the local AI is chosen project by project, and MADRE speaks more plainly. Here is what changed.')
255
281
  : back
256
- ? t('MADRE changed a lot since 0.7.2. First I bring your projects to Home; then I tell you what is new, at your own pace.')
257
- : t('This is MADRE: all your AI agents in one place, with your projects, their memory and your permissions.'));
282
+ ? t('MADRE changed a lot since 0.7.2. First I bring your projects to Home; then I tell you what is new.')
283
+ : t('This is MADRE. Here you work with the AIs you already use: you write to them, they read your project, and you decide what they may change.'));
258
284
  const note = el('p', 'tour-hello-note');
259
285
  if (since) note.textContent = t('Nothing you set up changed: your projects, agents and permissions are as you left them.');
260
286
  else if (back) note.innerHTML = t('<code>madre</code> now opens Home; <code>madre start</code> still opens the project in the folder.'); // trusted: our own catalogue
261
- else note.textContent = page === 'home' && welcome?.needed?.() ? t('First we get an agent and a project ready; then I tell you the essentials, at your own pace.') : t('I tell you the essentials in a few short chapters, at your own pace.');
287
+ else note.textContent = page === 'home' && welcome?.needed?.() ? t('First we get an agent and a project ready; then I show you the basics, whenever you like.') : t('I show you the basics in a few short chapters. You can stop and pick it up later.');
262
288
  const acts = el('div', 'tour-hello-acts');
263
289
  const later = key('tour-btn quiet', t('Later'), async () => {
264
290
  await keep({ path: path(), bonjour: true, closed: true });
@@ -284,7 +310,7 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
284
310
  node.addEventListener('close', () => { letGoIfDone(); setTimeout(() => node.remove(), 400); });
285
311
  document.body.append(node);
286
312
  node.showModal();
287
- onward.focus();
313
+ focusQuietly(onward);
288
314
  }
289
315
 
290
316
  // ---- 0.7.2: the projects Home cannot list, brought back one by one, the loader saying how far.
@@ -320,7 +346,7 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
320
346
  acts.append(key('tour-btn primary', t('See what is new'), () => { node.close(); openChapters('moved'); }));
321
347
  done.append(acts);
322
348
  stage.replaceChildren(done);
323
- acts.firstChild.focus();
349
+ focusQuietly(acts.firstChild);
324
350
  }
325
351
 
326
352
  // ---- The chapters.
@@ -341,7 +367,11 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
341
367
  const words = el('div', 'tour-head-words');
342
368
  const title = el('h2');
343
369
  title.id = 'tour-window-title';
344
- words.append(el('span', 'wn-eyebrow'), title);
370
+ // MADRE's own logo over the chapters (2026-10-28), as the welcome wears it.
371
+ const logo = el('span', 'tour-logo');
372
+ logo.setAttribute('aria-hidden', 'true');
373
+ logo.innerHTML = MADRE_LOGO; // trusted: our own SVG string
374
+ words.append(logo, el('span', 'wn-eyebrow'), title);
345
375
  const close = key('tour-close', null, () => windowNode.close());
346
376
  close.innerHTML = CLOSE_ICON; // trusted: our own SVG string
347
377
  close.setAttribute('aria-label', t('Close'));
@@ -375,7 +405,7 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
375
405
  const back = path() === 'back';
376
406
  const since = path() === 'since';
377
407
  windowNode.querySelector('.tour-head .wn-eyebrow').textContent = since ? t('What is new since 1.0') : back ? t('The tour of MADRE 1.0') : t('Getting to know MADRE');
378
- windowNode.querySelector('#tour-window-title').textContent = since ? t('What changed, at your pace') : back ? t('Everything new, at your pace') : t('The essentials, at your pace');
408
+ windowNode.querySelector('#tour-window-title').textContent = since ? t('What changed since 1.0') : back ? t('What is new since 0.7.2') : t('The basics of MADRE');
379
409
  void keep({ chapter: chapter.id, at: chapter.id });
380
410
  if (!state.done.includes(chapter.id)) state.done = [...state.done, chapter.id];
381
411
  const list = chapters();
@@ -408,7 +438,7 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
408
438
  if (back && chapter.news) {
409
439
  const news = el('p', `tour-news ${chapter.news.kind}`);
410
440
  const said = el('span');
411
- said.innerHTML = say(chapter.news); // trusted: our own copy
441
+ said.innerHTML = plain(say(chapter.news)); // trusted: our own copy
412
442
  news.append(el('b', 'tour-news-tag', chapter.news.kind === 'new' ? t('New in 1.0') : t('Changed in 1.0')), said);
413
443
  words.append(news);
414
444
  }
@@ -416,21 +446,21 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
416
446
  if (since && chapter.since) {
417
447
  const news = el('p', `tour-news ${chapter.since.kind}`);
418
448
  const said = el('span');
419
- said.innerHTML = say(chapter.since); // trusted: our own copy
449
+ said.innerHTML = plain(say(chapter.since)); // trusted: our own copy
420
450
  news.append(el('b', 'tour-news-tag', chapter.since.kind === 'new' ? t('New since 1.0') : t('Changed since 1.0')), said);
421
451
  words.append(news);
422
452
  }
423
- words.append(el('p', 'tour-lead', say(chapter.lead)));
453
+ words.append(el('p', 'tour-lead', plain(say(chapter.lead))));
424
454
  const points = chapter.points?.[language()] ?? chapter.points?.es ?? [];
425
455
  if (points.length) {
426
456
  const ul = el('ul', 'tour-points');
427
- for (const point of points) { const item = el('li'); item.innerHTML = point; ul.append(item); } // trusted: our own copy
457
+ for (const point of points) { const item = el('li'); item.innerHTML = plain(point); ul.append(item); } // trusted: our own copy
428
458
  words.append(ul);
429
459
  }
430
460
  if (chapter.id === 'gestures') words.append(gestureGrid());
431
461
  else if (chapter.keys?.length) {
432
462
  const keys = el('dl', 'tour-keys');
433
- for (const [what, how] of chapter.keys) keys.append(el('dt', null, say(what)), el('dd', null, say(how)));
463
+ for (const [what, how] of chapter.keys) keys.append(el('dt', null, say(what)), el('dd', null, keyWords(say(how))));
434
464
  words.append(keys);
435
465
  }
436
466
  const acts = el('div', 'tour-acts');
@@ -457,14 +487,26 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
457
487
  acts.querySelector('.tour-btn.primary')?.focus({ preventScroll: true });
458
488
  }
459
489
 
460
- // ---- `?`: the sheet of gestures, anywhere.
490
+ // The key that goes on holds the focus, so ↵ presses it, without wearing the focus ring nobody
491
+ // asked for: the browser drew it in its own blue around the first key of the welcome, as if it had
492
+ // been chosen. The ring comes back the moment the keyboard is used (2026-10-20).
493
+ function focusQuietly(button) {
494
+ if (!button) return;
495
+ button.classList.add('quiet-focus');
496
+ const wake = () => button.classList.remove('quiet-focus');
497
+ button.addEventListener('keydown', wake, { once: true });
498
+ button.addEventListener('blur', wake, { once: true });
499
+ button.focus({ focusVisible: false });
500
+ }
501
+ // ---- `?`: the sheet of gestures, anywhere. Its keys are the keyboard's in front of the person:
502
+ // ⌘ on a Mac, Ctrl+ anywhere else.
461
503
  function gestureGrid() {
462
504
  const grid = el('div', 'tour-gestures');
463
505
  for (const [group, rows] of GESTURES) {
464
506
  const box = el('section', 'tour-gesture-group');
465
507
  box.append(el('h4', null, say(group)));
466
508
  const keys = el('dl', 'tour-keys');
467
- for (const [what, how] of rows) keys.append(el('dt', null, say(what)), el('dd', null, say(how)));
509
+ for (const [what, how] of rows) keys.append(el('dt', null, say(what)), el('dd', null, keyWords(say(how))));
468
510
  box.append(keys);
469
511
  grid.append(box);
470
512
  }
@@ -508,35 +550,51 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
508
550
  // ---- The hints: one line, once, the first time someone reaches a place that confuses. Never
509
551
  // two at once, never over the bonjour or the chapters, never before the bonjour was seen.
510
552
  // `inside`: the hint goes into that box, at its top (a window that is modal, where a card
511
- // floating over the page could not be pressed); it counts as seen when the box closes.
512
- async function hint(id, anchor, { title, text, inside = false }) {
553
+ // floating over the page could not be pressed). A hint is kept as seen the moment it shows, not
554
+ // when it is put away: one left open and the page reloaded came back every time (2026-10-21).
555
+ // `step` of `of`: one of a short walk (Home's, salas-mac.js), said as «2 of 4» with «Next»;
556
+ // `skip` puts the rest of the walk away, `then` comes after this one is put away.
557
+ async function hint(id, anchor, { title, text, inside = false, step = 0, of = 0, skip = null, then = null }) {
513
558
  const answer = await loaded;
514
- if (phone || !answer || !state?.bonjourAt || state.hints?.[id] || hintNode || busyWith()) return false;
559
+ // Nor over a card of the room's news (app.js, .hint-card): two at once covered each other.
560
+ if (phone || !answer || !state?.bonjourAt || state.hints?.[id] || !forThem(id) || hintNode || busyWith() || document.querySelector('.hint-card')) return false;
515
561
  if (!anchor?.isConnected) return false;
516
562
  const box = anchor.getBoundingClientRect();
517
563
  if (!inside && !box.width && !box.height) return false;
518
564
  const card = el('section', `tour-hint${inside ? ' inline' : ''}`);
519
565
  card.setAttribute('role', 'note');
520
- card.append(el('span', 'tour-hint-eyebrow', t('The first time')), el('b', null, title), el('p', null, text));
566
+ const walking = step > 0 && of > 1;
567
+ const eyebrow = el('span', 'tour-hint-eyebrow', walking ? t('{n} of {total}', { n: step, total: of }) : t('The first time'));
568
+ // Inside a window its words go together, so its key can sit beside them or, where the window is
569
+ // narrow, under them — never squeezing the words into a column (2026-10-28, #4's key).
570
+ if (inside) { const words = el('div', 'tour-hint-words'); words.append(eyebrow, el('b', null, title), el('p', null, text)); card.append(words); }
571
+ else card.append(eyebrow, el('b', null, title), el('p', null, text));
521
572
  let spot = null;
522
573
  let away = null;
523
574
  let follow = null;
575
+ let skipped = false;
576
+ let coverTimer = 0;
524
577
  const done = () => {
525
578
  if (!hintNode) return;
526
- void keep({ hint: id });
579
+ clearInterval(coverTimer);
527
580
  spot?.remove();
528
581
  card.remove();
529
582
  away?.remove();
530
583
  hintNode = null;
531
584
  document.removeEventListener('keydown', onKey, true);
532
585
  if (follow) { window.removeEventListener('scroll', follow, true); window.removeEventListener('resize', follow); }
586
+ if (!skipped) then?.();
533
587
  };
534
588
  // Esc puts away the hint in sight, or the one its way-there key speaks of; one hidden under a
535
589
  // layer (the Project map) is not the one meant.
536
590
  const shown = (node) => Boolean(node?.isConnected) && getComputedStyle(node).display !== 'none';
537
591
  const onKey = (event) => { if (event.key === 'Escape' && hintNode && !inside && (shown(card) || shown(away))) { event.stopPropagation(); done(); } };
538
- card.append(key('tour-btn small primary', t('Got it'), done));
592
+ const keys = el('div', 'tour-hint-keys');
593
+ if (walking && step < of && skip) keys.append(key('tour-btn small quiet', t('Skip the tips'), () => { skipped = true; skip(); done(); }));
594
+ keys.append(key('tour-btn small primary', walking && step < of ? t('Next') : t('Got it'), done));
595
+ card.append(keys);
539
596
  hintNode = card;
597
+ void keep({ hint: id });
540
598
  if (inside) {
541
599
  anchor.prepend(card);
542
600
  anchor.closest('dialog')?.addEventListener('close', done, { once: true });
@@ -563,6 +621,25 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
563
621
  away.append(el('b', null, title), el('span', null, up ? t('Scroll up to see it') : t('Scroll down to see it')));
564
622
  away.setAttribute('aria-label', `${title} · ${up ? t('Scroll up to see it') : t('Scroll down to see it')}`);
565
623
  };
624
+ // Under a window (2026-10-28): a window opened over the page covers what the hint speaks of — the
625
+ // Market over Home's cards — and the hint, in the top layer, was drawn over that window pointing
626
+ // at nothing anyone could see. While its place is covered, the hint and its ring wait out of
627
+ // sight, and come back when the window closes.
628
+ const covered = () => {
629
+ const at = anchor.getBoundingClientRect();
630
+ const x = at.left + at.width / 2;
631
+ const y = at.top + Math.min(at.height / 2, 24);
632
+ // Out of view is said by the key at the edge (place), and a place that lets clicks through
633
+ // cannot be asked what covers it.
634
+ if (x < 0 || y < 0 || x >= window.innerWidth || y >= window.innerHeight || getComputedStyle(anchor).pointerEvents === 'none') return false;
635
+ const top = document.elementsFromPoint(x, y).find((node) => !card.contains(node) && !away.contains(node) && node !== spot?.node);
636
+ return Boolean(top) && top !== anchor && !anchor.contains(top) && !top.contains(anchor);
637
+ };
638
+ const watchCover = () => {
639
+ if (!anchor.isConnected) return;
640
+ const hide = covered();
641
+ for (const node of [card, away, spot?.node]) node?.toggleAttribute('data-covered', hide);
642
+ };
566
643
  const place = () => {
567
644
  if (!anchor.isConnected) { done(); return; }
568
645
  const at = anchor.getBoundingClientRect();
@@ -577,11 +654,18 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
577
654
  const below = at.bottom + 10 + height < window.innerHeight;
578
655
  Object.assign(card.style, { left: `${left}px`, top: `${below ? at.bottom + 10 : Math.max(12, at.top - height - 10)}px` });
579
656
  };
657
+ // A step of a walk takes the page to what it speaks of, instead of asking to scroll there.
658
+ if (walking) {
659
+ const at = anchor.getBoundingClientRect();
660
+ if (at.top < 60 || at.bottom > window.innerHeight - 40) anchor.scrollIntoView?.({ block: 'center', behavior: still() ? 'auto' : 'smooth' });
661
+ }
580
662
  spot = spotlight(anchor);
581
663
  follow = () => place();
582
664
  window.addEventListener('scroll', follow, true);
583
665
  window.addEventListener('resize', follow);
584
666
  place();
667
+ watchCover();
668
+ coverTimer = setInterval(watchCover, 350);
585
669
  // Where it points: on the page, or on a layer over it (Home's Project map). A layer opened over
586
670
  // the page hides the hints that point under it, and they come back when it closes (salas-mac.css).
587
671
  const layer = anchor.closest?.('.mv') ? 'map' : 'page';
@@ -619,6 +703,12 @@ export function startTour({ page, go = {}, ready = () => true, phone = false, de
619
703
  openChapters,
620
704
  openGestures,
621
705
  hint,
706
+ returning,
707
+ newcomer,
708
+ // Updated from a MADRE before 1.1.0 (src/terms.mjs): never the welcome of someone new.
709
+ upgraded: () => Boolean(info?.upgraded),
710
+ // A card the page shows itself (app.js: first touches and news) is kept as seen here, per person.
711
+ seen: (id) => keep({ hint: id }),
622
712
  state: () => state,
623
713
  path,
624
714
  };