@jossuealcala/madre 1.1.2 → 1.1.4

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 (166) hide show
  1. package/CHANGELOG.en.md +40 -1
  2. package/CHANGELOG.md +40 -1
  3. package/README.en.md +3 -3
  4. package/README.md +3 -3
  5. package/SECURITY.md +11 -6
  6. package/TRADEMARKS.md +6 -2
  7. package/bin/madre.mjs +76 -11
  8. package/docs/REFERENCE.md +16 -10
  9. package/docs/SDK.md +36 -9
  10. package/docs/en/REFERENCE.md +12 -8
  11. package/docs/en/SDK.md +34 -8
  12. package/docs/en/training/README.md +1 -1
  13. package/docs/sdk/connector-module.mjs +1 -1
  14. package/docs/sdk/hello-module.mjs +39 -4
  15. package/docs/training/README.md +1 -1
  16. package/docs/training/train.sh +3 -0
  17. package/habilidades/explicamelo-facil/HABILIDAD.md +19 -0
  18. package/habilidades/hojas-de-calculo/HABILIDAD.md +18 -0
  19. package/habilidades/mensajes-a-clientes/HABILIDAD.md +19 -0
  20. package/habilidades/publicaciones-para-redes/HABILIDAD.md +19 -0
  21. package/habilidades/resumen-y-pendientes/HABILIDAD.md +18 -0
  22. package/habilidades/tu-pagina-paso-a-paso/HABILIDAD.md +19 -0
  23. package/package.json +7 -4
  24. package/public/activity.js +66 -22
  25. package/public/app.js +4947 -894
  26. package/public/assets/brand/OFL-SpaceGrotesk.txt +93 -0
  27. package/public/assets/brand/SpaceGrotesk-latin-ext.woff2 +0 -0
  28. package/public/assets/brand/SpaceGrotesk-latin.woff2 +0 -0
  29. package/public/assets/brand/madre-app-180.png +0 -0
  30. package/public/assets/brand/madre-app-192.png +0 -0
  31. package/public/assets/brand/madre-app-512.png +0 -0
  32. package/public/assets/brand/madre-app.svg +1 -1
  33. package/public/assets/brand/madre-favicon.svg +1 -1
  34. package/public/attribution.js +29 -19
  35. package/public/auto-open.js +102 -0
  36. package/public/brands.js +36 -19
  37. package/public/changes.js +63 -0
  38. package/public/en.js +1085 -102
  39. package/public/es.js +2940 -1656
  40. package/public/i18n.js +11 -0
  41. package/public/index.html +31 -27
  42. package/public/loader.js +322 -117
  43. package/public/macroverso.js +57 -355
  44. package/public/manual-content.js +69 -9
  45. package/public/manual.js +21 -6
  46. package/public/market-view.js +298 -84
  47. package/public/market.js +25 -2
  48. package/public/mcp-catalog.js +7 -2
  49. package/public/missions.js +169 -0
  50. package/public/news-scenes.js +292 -0
  51. package/public/nostromo-engine.js +935 -654
  52. package/public/notices.js +78 -0
  53. package/public/notifications.js +119 -0
  54. package/public/power.js +1 -1
  55. package/public/provider-marks.js +170 -0
  56. package/public/provider-pick.js +147 -0
  57. package/public/resay.js +4 -0
  58. package/public/review-ask.js +16 -13
  59. package/public/routing.js +29 -3
  60. package/public/salas-mac.css +467 -47
  61. package/public/salas-mac.html +8 -5
  62. package/public/salas-mac.js +805 -109
  63. package/public/salas.css +2 -2
  64. package/public/salas.html +2 -2
  65. package/public/salas.js +1 -1
  66. package/public/starters.js +128 -0
  67. package/public/styles.css +3036 -340
  68. package/public/subscription.js +303 -0
  69. package/public/terms-field.js +170 -0
  70. package/public/terms.js +117 -19
  71. package/public/tips.js +158 -0
  72. package/public/tour-chapters.js +88 -88
  73. package/public/tour.js +364 -46
  74. package/public/troubleshooting.js +313 -27
  75. package/public/welcome-scene.js +446 -0
  76. package/public/welcome.js +827 -282
  77. package/src/adapters/claude.mjs +2 -1
  78. package/src/adapters/codex.mjs +2 -1
  79. package/src/adapters/cursor.mjs +9 -6
  80. package/src/adapters/gemini-rest.mjs +236 -0
  81. package/src/adapters/gemini.mjs +13 -7
  82. package/src/adapters/grok.mjs +290 -0
  83. package/src/adapters/madre.mjs +71 -23
  84. package/src/adapters/opencode.mjs +15 -2
  85. package/src/adapters/process.mjs +14 -3
  86. package/src/adapters/steps.mjs +176 -0
  87. package/src/app-invite.mjs +90 -0
  88. package/src/auth-probe.mjs +32 -0
  89. package/src/billing-key.mjs +8 -0
  90. package/src/billing.mjs +317 -0
  91. package/src/bridge/policy.mjs +1 -1
  92. package/src/capabilities.mjs +46 -10
  93. package/src/chats.mjs +44 -2
  94. package/src/checkpoint.mjs +119 -1
  95. package/src/codex-route.mjs +113 -0
  96. package/src/commands.mjs +5 -2
  97. package/src/credentials.mjs +46 -8
  98. package/src/dataset.mjs +18 -7
  99. package/src/directives.mjs +1 -0
  100. package/src/event-store.mjs +25 -2
  101. package/src/extensions.mjs +5 -1
  102. package/src/ficha.mjs +158 -0
  103. package/src/files.mjs +36 -2
  104. package/src/image-studio.mjs +13 -3
  105. package/src/install-metrics.mjs +9 -3
  106. package/src/lease.mjs +6 -1
  107. package/src/looks.mjs +4 -1
  108. package/src/market-check.mjs +1 -1
  109. package/src/market-remote.mjs +135 -1
  110. package/src/mcp/image-server.mjs +59 -90
  111. package/src/mcp/memory-server.mjs +10 -0
  112. package/src/memory-tools.mjs +3 -0
  113. package/src/memory.mjs +29 -4
  114. package/src/models.mjs +21 -3
  115. package/src/modules/ahp.mjs +10 -4
  116. package/src/modules/bishop-exam.mjs +41 -12
  117. package/src/modules/bishop.mjs +2 -2
  118. package/src/modules/choices.mjs +12 -10
  119. package/src/modules/fetch-alone.mjs +7 -0
  120. package/src/modules/github.mjs +6 -2
  121. package/src/modules/helpers.mjs +23 -5
  122. package/src/modules/image-providers.mjs +281 -0
  123. package/src/modules/image-studio.mjs +106 -39
  124. package/src/modules/index.mjs +61 -12
  125. package/src/modules/intents-observe.mjs +3 -1
  126. package/src/modules/isolated.mjs +160 -0
  127. package/src/modules/ollama.mjs +35 -6
  128. package/src/modules/playwright.mjs +78 -20
  129. package/src/modules/reminders.mjs +42 -2
  130. package/src/modules/ripley.mjs +2 -1
  131. package/src/modules/run-alone.mjs +122 -0
  132. package/src/modules/runs.mjs +11 -8
  133. package/src/modules/sdk.mjs +10 -3
  134. package/src/notices-key.mjs +8 -0
  135. package/src/notices.mjs +185 -0
  136. package/src/ollama.mjs +57 -15
  137. package/src/opencode-health.mjs +1 -1
  138. package/src/outbound.mjs +124 -13
  139. package/src/quota-sources.mjs +148 -3
  140. package/src/review-ask.mjs +55 -31
  141. package/src/room/archivist.mjs +30 -5
  142. package/src/room/busy.mjs +16 -0
  143. package/src/room/changes.mjs +79 -0
  144. package/src/room/control.mjs +36 -6
  145. package/src/room/economy.mjs +1 -1
  146. package/src/room/guard.mjs +39 -2
  147. package/src/room/prompt.mjs +49 -6
  148. package/src/room/vectors.mjs +7 -1
  149. package/src/room.mjs +181 -49
  150. package/src/router.mjs +1 -1
  151. package/src/runs.mjs +39 -0
  152. package/src/runtime-detection.mjs +46 -6
  153. package/src/salas.mjs +181 -18
  154. package/src/server.mjs +1101 -118
  155. package/src/service.mjs +116 -0
  156. package/src/setup-trouble.mjs +20 -1
  157. package/src/setup.mjs +1 -1
  158. package/src/skill-check.mjs +269 -0
  159. package/src/skills-import.mjs +128 -0
  160. package/src/skills.mjs +502 -0
  161. package/src/terms.mjs +23 -5
  162. package/src/tour.mjs +31 -5
  163. package/src/updates.mjs +47 -4
  164. package/src/web-preview.mjs +181 -0
  165. package/src/whats-new.mjs +121 -1
  166. package/src/rumbo.mjs +0 -337
package/public/terms.js CHANGED
@@ -11,6 +11,8 @@
11
11
 
12
12
  import { browserLanguage, language, setLanguage, t } from './i18n.js';
13
13
  import { MADRE_LOGO, playOpening } from './loader.js';
14
+ import { trazo } from './icons.js';
15
+ import { PRELUDE, createTermsField } from './terms-field.js';
14
16
 
15
17
  const el = (tag, className = null, text = null) => {
16
18
  const node = document.createElement(tag);
@@ -27,6 +29,16 @@ const link = (href, words) => {
27
29
  };
28
30
  const pick = (pair) => pair?.[language()] ?? pair?.es ?? '#';
29
31
 
32
+ // The ground over the page while it is drawn (index.html, salas-mac.html: `madre-booting`), put back,
33
+ // with the same way out if nothing takes it away.
34
+ function veilPage() {
35
+ const root = document.documentElement;
36
+ if (root.classList.contains('madre-booting')) return;
37
+ root.classList.remove('madre-arriving');
38
+ root.classList.add('madre-booting');
39
+ setTimeout(() => root.classList.remove('madre-booting'), 6000);
40
+ }
41
+
30
42
  export async function ensureTerms() {
31
43
  if (typeof document === 'undefined' || typeof fetch !== 'function') return;
32
44
  let answer = null;
@@ -44,35 +56,102 @@ function askTerms(answer, done) {
44
56
  // The dialog's first focus goes to the card, never to a link or a key with the browser's ring on it.
45
57
  card.tabIndex = -1;
46
58
  card.setAttribute('autofocus', '');
47
- dialog.append(card);
59
+ // Behind the card, over the window's right half: MADRE at work, in the abstract (terms-field.js).
60
+ const field = createTermsField();
61
+ dialog.append(field.node, card);
48
62
  // Esc is no answer here: without accepting, MADRE does not start.
49
63
  dialog.addEventListener('cancel', (event) => event.preventDefault());
50
64
  let diagnostics = answer.diagnosticsFixed ? false : answer.diagnostics !== false;
51
- const returning = answer.before === true;
65
+ // Inside the desktop app (src/terms.mjs, `kind`) the license is the app's own, closed, and whoever
66
+ // accepted the source code's before is told the app has one of its own.
67
+ const app = answer.kind === 'app';
68
+ const returning = app ? Boolean(answer.previous) : answer.before === true;
52
69
 
70
+ // The logo draws itself in once: drawn again with every change of language, it started over.
71
+ const askLogo = el('div', 'terms-logo');
72
+ askLogo.innerHTML = MADRE_LOGO; // trusted: our own SVG string
53
73
  const paintAsk = () => {
54
74
  card.replaceChildren();
55
- const logo = el('div', 'terms-logo');
56
- logo.innerHTML = MADRE_LOGO; // trusted: our own SVG string
57
- const title = el('h1', 'terms-title', returning ? t('MADRE 1.1 has a new license') : t('Before you start'));
75
+ const logo = askLogo;
76
+ // THE LANGUAGE, by hand (2026-11-11, the author: «whatever language is detected, an ES key in the
77
+ // top right corner»): ES and EN, the one on lit; the card is said again in the other at once,
78
+ // and MADRE keeps it as the person's choice.
79
+ const tongue = el('div', 'terms-lang');
80
+ tongue.setAttribute('role', 'radiogroup');
81
+ tongue.setAttribute('aria-label', 'Idioma · Language');
82
+ for (const [code, word] of [['es', 'ES'], ['en', 'EN']]) {
83
+ const key = el('button', null, word);
84
+ key.type = 'button';
85
+ key.setAttribute('role', 'radio');
86
+ key.setAttribute('aria-checked', String(language() === code));
87
+ key.setAttribute('aria-label', code === 'es' ? 'Español' : 'English');
88
+ key.addEventListener('click', async () => {
89
+ if (language() === code) return;
90
+ setLanguage(code);
91
+ // Drawn in once: put back in the card it would draw itself in again (2026-11-13, the author: the
92
+ // logo «animates as when changing language»), so from here it is the drawn mark, still.
93
+ askLogo.classList.add('still');
94
+ paintAsk();
95
+ await fetch('/api/language', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ language: code }) }).catch(() => null);
96
+ });
97
+ tongue.append(key);
98
+ }
99
+ // Said to be read in seconds and to calm, not to warn (2026-11-13, the author: «I read that and I
100
+ // would not install it»): free, two quick things, and each one's detail one click away.
101
+ const title = el('h1', 'terms-title', returning ? (app ? t('MADRE is an app now') : t('MADRE 1.1 has a new license')) : t('Before you start'));
58
102
  title.id = 'terms-title';
59
- const lead = el('p', 'terms-lead', returning
60
- ? t('It is still free for you and for teams of up to 10 people. To keep using it, accept the license and the privacy notice.')
61
- : t('MADRE is free for you and for teams of up to 10 people, also when you use it to work for your clients.'));
103
+ // Q-26 (2026-11-17, the author): the app never says it is free for you. With the author's switch
104
+ // on (answer.trialDays) it names the first days with everything and the one project after them;
105
+ // with it off it promises nothing either way. The source code keeps its words (BSL).
106
+ const days = Number.isInteger(answer.trialDays) && answer.trialDays > 0 ? answer.trialDays : null;
107
+ const lead = el('p', 'terms-lead', app
108
+ ? (days
109
+ ? (returning
110
+ ? t('The first {days} days you have all of MADRE App; then it stays free with one project. Two quick things and you carry on where you left off.', { days })
111
+ : t('The first {days} days you have all of MADRE App; then it stays free with one project. Two quick things and you are in.', { days }))
112
+ : (returning ? t('Two quick things and you carry on where you left off.') : t('MADRE App is ready. Two quick things and you are in.')))
113
+ : returning
114
+ ? t('It is still free for you and for teams of up to 10 people. Two quick things and you carry on where you left off.')
115
+ : t('MADRE is free for you and for teams of up to 10 people. Two quick things and you are in.'));
62
116
 
117
+ // WHAT MADRE IS, before anything is asked (2026-11-11, the author: «a short description of what
118
+ // MADRE is in the first window, where the license is accepted»): three lines, the same three ideas
119
+ // the opening tells after it.
120
+ const about = el('section', 'terms-about');
121
+ about.append(el('h2', null, t('What MADRE is')));
122
+ const points = el('ul', 'terms-about-list');
123
+ for (const [icon, title, sub] of [
124
+ ['agents', t('Your AIs, together'), t('Claude, ChatGPT, Gemini and more, in one place.')],
125
+ ['folder', t('They work in your folders'), t('You ask the way you would ask someone on your team, and they do it in your files.')],
126
+ ['brain', t('MADRE remembers'), t('What gets decided is kept, so nobody starts from zero.')],
127
+ ]) {
128
+ const item = el('li');
129
+ const mark = el('span', 'terms-about-icon');
130
+ mark.setAttribute('aria-hidden', 'true');
131
+ mark.innerHTML = trazo(icon); // trusted: our own SVG string
132
+ const words = el('span', 'terms-about-words');
133
+ words.append(el('b', null, title), el('small', null, sub));
134
+ item.append(mark, words);
135
+ points.append(item);
136
+ }
137
+ about.append(points);
63
138
  const license = el('section', 'terms-block');
64
139
  license.append(
65
- el('h2', null, t('Personal license')),
66
- el('p', null, t('You can use MADRE, change it and share it; an organization of more than 10 people, or whoever offers MADRE as a service, needs a commercial license.')),
140
+ el('h2', null, app ? t('Your license') : t('Free for you and your team')),
141
+ el('p', null, app
142
+ ? (days
143
+ ? t('A personal license: the first {days} days with everything, then free with one project, or everything with the subscription. What you make with it is yours.', { days })
144
+ : t('A personal license, for your computers and your projects. Everything you make with it is yours.'))
145
+ : t('Use it, change it and share it. Everything you make with it is yours; a company of more than 10 people writes to us for its license.')),
67
146
  link(pick(answer.links?.license), t('Read the license')),
68
147
  );
69
148
 
70
149
  const help = el('section', 'terms-block terms-help');
71
150
  const head = el('div', 'terms-help-head');
72
151
  const words = el('div');
73
- words.append(el('h2', null, t('Help make MADRE better')), el('p', null, returning
74
- ? t('MADRE is made by one person. From this version your copy can share its errors with me anonymously, so the next versions fix first what fails for you. It is optional and you can turn it off whenever you like in Settings.')
75
- : t('MADRE is made by one person. Your copy can share its errors with me anonymously, so each version fixes first what fails for you. It is optional and you can turn it off whenever you like in Settings.')));
152
+ // What it is for and what never leaves, in two lines; what is sent, every detail of it (the daily
153
+ // notice too), is one click away (2026-11-13, the author: «summarise it very quickly»).
154
+ words.append(el('h2', null, t('Help make MADRE better')), el('p', null, t('If something fails, your copy tells me without saying who you are, and I fix it first. Your files and what you write never leave your computer.')));
76
155
  const knob = el('button', 'terms-switch');
77
156
  knob.type = 'button';
78
157
  knob.setAttribute('role', 'switch');
@@ -85,7 +164,7 @@ function askTerms(answer, done) {
85
164
  said.replaceChildren();
86
165
  if (answer.diagnosticsFixed) said.append(t('Off: MADRE was started with PULSE_TELEMETRY=0.'));
87
166
  else if (diagnostics) said.append(link(pick(answer.links?.privacy), t('See what is sent')));
88
- else said.append(t('Off: the author will not know when something fails for you, and it may take longer to fix.'));
167
+ else said.append(t('Off. MADRE works the same; it will just take me longer to find out if something fails for you.'));
89
168
  };
90
169
  knob.addEventListener('click', () => { diagnostics = !diagnostics; paintKnob(); });
91
170
  paintKnob();
@@ -107,19 +186,30 @@ function askTerms(answer, done) {
107
186
  error.textContent = '';
108
187
  const saved = await fetch('/api/terms', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ accept: true, diagnostics }) }).then((response) => response.ok).catch(() => false);
109
188
  if (!saved) { yes.disabled = false; no.disabled = false; error.textContent = t('It could not be saved. Try again.'); return; }
110
- // Whoever updated meets MADRE's opening here, before Home is drawn behind it (2026-10-30): drawn
111
- // first and the opening over it, it looked like a jump. Someone new meets it in the welcome.
112
- if (returning) { card.style.visibility = 'hidden'; await playOpening(dialog, { skipLabel: t('Skip') }); }
189
+ // MADRE's opening plays here, before Home is drawn behind it (2026-10-30): drawn first and the
190
+ // opening over it, it looked like a jump. Since 2026-11-10 for someone new too: the page's veil
191
+ // had gone while they read the license (loader.js, six seconds), so Home showed and the opening
192
+ // came after it, with the welcome. The veil goes back over the page until the welcome opens or
193
+ // Home is drawn (bootDone); the welcome does not play the opening again (openingPlayed).
194
+ card.style.visibility = 'hidden';
195
+ // The opening takes up the smoke where it is (terms-field.js), and condenses it.
196
+ await playOpening(dialog, { skipLabel: t('Skip'), from: field.smoke?.() ?? null });
197
+ veilPage();
113
198
  dialog.classList.add('leaving');
114
- setTimeout(() => { dialog.close(); dialog.remove(); done(); }, 260);
199
+ setTimeout(() => { field.stop(); dialog.close(); dialog.remove(); done(); }, 260);
115
200
  });
116
201
  actions.append(no, yes);
117
- card.append(logo, title, lead, license, help, foot, error, actions);
202
+ // The language key belongs to the window's top right corner, never to the card (2026-11-13, the
203
+ // author): inside the card, the card's own movement as it arrives carried it next to the title.
204
+ dialog.querySelector(':scope > .terms-lang')?.remove();
205
+ dialog.append(tongue);
206
+ card.append(logo, title, lead, ...(returning ? [] : [about]), license, help, foot, error, actions);
118
207
  setTimeout(() => card.focus({ preventScroll: true }), 0);
119
208
  };
120
209
 
121
210
  const paintDeclined = () => {
122
211
  card.replaceChildren();
212
+ dialog.querySelector(':scope > .terms-lang')?.remove();
123
213
  const logo = el('div', 'terms-logo');
124
214
  logo.innerHTML = MADRE_LOGO; // trusted: our own SVG string
125
215
  const title = el('h1', 'terms-title', t('MADRE cannot start without it'));
@@ -149,4 +239,12 @@ function askTerms(answer, done) {
149
239
  paintAsk();
150
240
  document.body.append(dialog);
151
241
  if (typeof dialog.showModal === 'function') dialog.showModal(); else dialog.setAttribute('open', '');
242
+ // The story begins before the card (2026-11-13, the author): the AIs come as points of light and open
243
+ // into the smoke, one line says where it all starts, and then the card arrives over the smoke.
244
+ dialog.classList.add('prelude');
245
+ const story = el('p', 'terms-prelude', t('It all starts with your AIs.'));
246
+ story.setAttribute('aria-hidden', 'true');
247
+ dialog.append(story);
248
+ const born = field.start({ prelude: true });
249
+ setTimeout(() => { dialog.classList.remove('prelude'); setTimeout(() => story.remove(), 900); }, born ? (PRELUDE.done - 0.55) * 1000 : 0);
152
250
  }
package/public/tips.js ADDED
@@ -0,0 +1,158 @@
1
+ // SPDX-License-Identifier: BUSL-1.1
2
+ // MADRE · © 2026 Jossue Alcalá · Business Source License 1.1: LICENSE
3
+ // TIPS (2026-11-07): one small, solid label for every key that explains itself, in Home and in every
4
+ // project, instead of the browser's own (late, and drawn differently by each one). A key keeps
5
+ // saying what it says through `title`: the moment the pointer reaches it or the keyboard lands on it,
6
+ // the words move to `data-tip` until the pointer leaves (so the browser's own tip, which comes
7
+ // sooner, never shows first: 2026-11-10) and go back after. Anything with a `title` gets MADRE's tip,
8
+ // not only keys. A key with no words of its own keeps them as its accessible name.
9
+ //
10
+ // One element for the whole page, under the key or over it when there is no room, never under the
11
+ // pointer's way, gone at the first press, scroll or key. Nothing shows on touch.
12
+
13
+ // ms resting on a key before its tip shows (2026-11-10, the author: 380 was too eager). A part of the
14
+ // page can ask for longer with `data-tip-after` (the box's agent, mode, model, effort and copilot).
15
+ const SHOW_AFTER = 2000;
16
+ const AGAIN_WITHIN = 600; // ms after one hides in which the next shows at once
17
+ const GAP = 7;
18
+
19
+ let tip = null;
20
+ let current = null;
21
+ let timer = null;
22
+ let hiddenAt = 0;
23
+ let pending = null; // the key a tip is waiting to show for
24
+ let held = []; // the keys around it, their `title` kept aside meanwhile
25
+
26
+ // A key that already shows its own label (an agent's sphere in the crew's column) says `data-tip-off`.
27
+ const keyOf = (target) => {
28
+ const key = target?.closest?.('[title]:not(iframe, html, body), [data-tip]') ?? null;
29
+ return key && !key.closest('[data-tip-off]') ? key : null;
30
+ };
31
+
32
+ function ensure() {
33
+ if (tip?.isConnected) return tip;
34
+ tip = document.createElement('div');
35
+ tip.className = 'madre-tip';
36
+ tip.setAttribute('role', 'tooltip');
37
+ tip.hidden = true;
38
+ document.body.append(tip);
39
+ return tip;
40
+ }
41
+
42
+ function words(key) {
43
+ const said = key.getAttribute('title');
44
+ if (said) {
45
+ // The words leave `title` while the tip is up, and the key keeps a name if it had none.
46
+ key.dataset.tip = said;
47
+ key.removeAttribute('title');
48
+ if (!key.getAttribute('aria-label') && !key.textContent.trim()) key.setAttribute('aria-label', said);
49
+ }
50
+ return key.dataset.tip ?? '';
51
+ }
52
+
53
+ function restore(key) {
54
+ if (!key?.dataset?.tip) return;
55
+ // Words the page gave it while the pointer was on it win over the ones it had.
56
+ if (!key.hasAttribute('title')) key.setAttribute('title', key.dataset.tip);
57
+ delete key.dataset.tip;
58
+ }
59
+
60
+ // A key inside another that has words too (UNDO inside the card of changes, the card inside its row
61
+ // of notices): with only the inner one's `title` gone, the browser showed the outer one's under
62
+ // MADRE's tip (2026-11-12, the author: «the tips double»). The ones around it keep theirs aside too,
63
+ // until the pointer leaves.
64
+ function holdAround(key) {
65
+ for (let up = key.parentElement?.closest?.('[title]'); up && up !== document.body && up !== document.documentElement; up = up.parentElement?.closest?.('[title]')) {
66
+ up.dataset.tipHeld = up.getAttribute('title') ?? '';
67
+ up.removeAttribute('title');
68
+ held.push(up);
69
+ }
70
+ }
71
+ function releaseAround() {
72
+ for (const up of held) {
73
+ if (!up.hasAttribute('title') && 'tipHeld' in up.dataset) up.setAttribute('title', up.dataset.tipHeld);
74
+ delete up.dataset.tipHeld;
75
+ }
76
+ held = [];
77
+ }
78
+
79
+ function place(key) {
80
+ const node = ensure();
81
+ const box = key.getBoundingClientRect();
82
+ node.hidden = false;
83
+ node.classList.remove('shown');
84
+ const own = node.getBoundingClientRect();
85
+ const below = box.bottom + GAP + own.height <= window.innerHeight - 4;
86
+ const top = below ? box.bottom + GAP : box.top - GAP - own.height;
87
+ const left = Math.min(Math.max(4, box.left + box.width / 2 - own.width / 2), window.innerWidth - own.width - 4);
88
+ node.style.transform = `translate(${Math.round(left)}px, ${Math.round(top)}px)`;
89
+ node.dataset.side = below ? 'below' : 'above';
90
+ requestAnimationFrame(() => node.classList.add('shown'));
91
+ }
92
+
93
+ function show(key) {
94
+ // A key gone from the page, or with no size (a row of notices opened under the pointer while the
95
+ // tip waited), has no place to point at: its tip came up in the window's top corner (2026-11-13).
96
+ const box = key.isConnected ? key.getBoundingClientRect() : null;
97
+ if (!box || (!box.width && !box.height)) { restore(key); return; }
98
+ const said = words(key);
99
+ if (!said) return;
100
+ current = key;
101
+ const node = ensure();
102
+ node.textContent = said;
103
+ place(key);
104
+ }
105
+
106
+ export function hideTip() {
107
+ clearTimeout(timer);
108
+ timer = null;
109
+ if (pending) restore(pending);
110
+ pending = null;
111
+ if (current) { restore(current); hiddenAt = performance.now(); }
112
+ current = null;
113
+ releaseAround();
114
+ if (tip) { tip.classList.remove('shown'); tip.hidden = true; }
115
+ }
116
+
117
+ function arm(key) {
118
+ if (key === current) return;
119
+ hideTip();
120
+ const soon = performance.now() - hiddenAt < AGAIN_WITHIN;
121
+ // Its words leave `title` now, not when the tip shows: the browser's would come first.
122
+ if (!words(key)) return;
123
+ holdAround(key);
124
+ pending = key;
125
+ const after = Number(key.closest('[data-tip-after]')?.dataset.tipAfter) || SHOW_AFTER;
126
+ timer = setTimeout(() => { pending = null; show(key); }, soon ? 0 : after);
127
+ }
128
+
129
+ export function installTips(root = globalThis.document) {
130
+ // A page without a document or events (the tests' stand-in window) has no tips to show.
131
+ if (!root || typeof root.addEventListener !== 'function' || typeof globalThis.window?.addEventListener !== 'function' || root.__madreTips) return;
132
+ root.__madreTips = true;
133
+ root.addEventListener('pointerover', (event) => {
134
+ if (event.pointerType === 'touch') return;
135
+ const key = keyOf(event.target);
136
+ if (key) arm(key);
137
+ });
138
+ root.addEventListener('pointerout', (event) => {
139
+ const key = keyOf(event.target);
140
+ if (!key || key.contains(event.relatedTarget)) return;
141
+ hideTip();
142
+ });
143
+ root.addEventListener('focusin', (event) => {
144
+ const key = keyOf(event.target);
145
+ if (key && key.matches(':focus-visible')) arm(key);
146
+ });
147
+ root.addEventListener('focusout', () => hideTip());
148
+ for (const type of ['pointerdown', 'keydown', 'wheel']) root.addEventListener(type, () => hideTip(), { capture: true, passive: true });
149
+ // Only a scroll that moves the key hides its tip: the room has rows that scroll on their own (the
150
+ // suggestions), and every one of their steps used to hide the tip before it ever showed.
151
+ window.addEventListener('scroll', (event) => {
152
+ const key = current ?? pending;
153
+ if (!key) return;
154
+ const moved = event.target === document || event.target === document.documentElement || event.target?.contains?.(key);
155
+ if (moved) hideTip();
156
+ }, { capture: true, passive: true });
157
+ window.addEventListener('blur', () => hideTip());
158
+ }