,
): string {
diff --git a/src/i18n/topology/de.json b/src/i18n/topology/de.json
index 325a2fac..786e0f34 100644
--- a/src/i18n/topology/de.json
+++ b/src/i18n/topology/de.json
@@ -2,6 +2,8 @@
"title": "Zigbee-Verbindungen",
"toggle": "Zigbee-Verbindungen beim Darüberfahren über ein Gerät anzeigen",
"hint": "Es werden nur beobachtete direkte Nachbarn angezeigt. Beim Darüberfahren werden keine Daten abgerufen.",
+ "help": "Zeigt, mit welchen Zigbee-Geräten jedes Gerät direkt verbunden ist. Die Linienfarbe ist die Verbindungsqualität (LQI) auf derselben Skala wie der LQI-Wert des Geräts: rot bei 40 und darunter, grün bei 180 und darüber. Eine gestrichelte Linie bedeutet, dass die Qualität nicht gemeldet wurde. Ein Pfeil zeigt auf das nächste Gerät auf dem Weg zum Koordinator: ein Pfeil führt hinaus, eingehende Pfeile sind die Geräte, die über dieses Gerät routen. Eine Linie ohne Pfeil ist ein Ersatznachbar. Das ist der Routenbaum, den House Plan bildet, nicht der Weg eines Pakets in diesem Moment: eine Beschriftung am Pfeilende bedeutet, dass das Ziel nicht auf diesem Plan liegt, und ein fehlender Pfeil, dass die Route unbekannt ist. Die Daten stammen aus dem letzten Laden und veralten; Verbindungen sind nur mit der Maus sichtbar.",
+ "help_aria": "Hilfe: Zigbee-Verbindungen",
"admin_only": "Topologiedaten sind nur für Home-Assistant-Administratoren verfügbar.",
"save_first": "Speichere diese Einstellung, bevor Topologiedaten geladen werden.",
"zha": "ZHA",
diff --git a/src/i18n/topology/en.json b/src/i18n/topology/en.json
index 6d88178b..a6cf394f 100644
--- a/src/i18n/topology/en.json
+++ b/src/i18n/topology/en.json
@@ -2,6 +2,8 @@
"title": "Zigbee links",
"toggle": "Show Zigbee links when hovering over a device",
"hint": "Shows observed direct neighbours only. Nothing is fetched while you hover.",
+ "help": "Shows which Zigbee devices each device talks to directly. Line colour is link quality (LQI) on the same scale as the device's LQI reading: red at 40 and below, green at 180 and above. A dashed line means quality was not reported. An arrow points to the next device on the way to the coordinator: one arrow leads out, incoming arrows are the devices that route through this one. A line without an arrow is a spare neighbour. This is the route tree House Plan builds, not the path a packet takes right now: a label at the end of an arrow means its target is not on this plan, and no arrow at all means the route is unknown. Data comes from the last load and goes stale; links are shown with a mouse only.",
+ "help_aria": "Help: Zigbee links",
"admin_only": "Topology data is available to Home Assistant administrators only.",
"save_first": "Save this setting before loading topology data.",
"zha": "ZHA",
diff --git a/src/i18n/topology/fr.json b/src/i18n/topology/fr.json
index 7748d995..1d8a17b9 100644
--- a/src/i18n/topology/fr.json
+++ b/src/i18n/topology/fr.json
@@ -2,6 +2,8 @@
"title": "Liens Zigbee",
"toggle": "Afficher les liens Zigbee au survol d’un appareil",
"hint": "Seuls les voisins directs observés sont affichés. Le survol ne lance aucune requête.",
+ "help": "Montre avec quels appareils Zigbee chaque appareil communique directement. La couleur de la ligne est la qualité du lien (LQI) sur la même échelle que l'indicateur LQI de l'appareil : rouge à 40 et en dessous, vert à 180 et au-dessus. Une ligne pointillée signifie que la qualité n'a pas été communiquée. Une flèche pointe vers l'appareil suivant sur le chemin du coordinateur : une flèche part, les flèches entrantes sont les appareils qui passent par celui-ci. Une ligne sans flèche est un voisin de secours. C'est l'arbre de routes que construit House Plan, pas le trajet d'un paquet à cet instant : une étiquette au bout d'une flèche signifie que sa cible n'est pas sur ce plan, et l'absence de flèche que la route est inconnue. Les données proviennent du dernier chargement et vieillissent ; les liens ne sont visibles qu'à la souris.",
+ "help_aria": "Aide : liens Zigbee",
"admin_only": "Les données de topologie sont réservées aux administrateurs Home Assistant.",
"save_first": "Enregistrez ce réglage avant de charger les données de topologie.",
"zha": "ZHA",
diff --git a/src/i18n/topology/ru.json b/src/i18n/topology/ru.json
index a70a8e0a..c6952727 100644
--- a/src/i18n/topology/ru.json
+++ b/src/i18n/topology/ru.json
@@ -2,6 +2,8 @@
"title": "Связи Zigbee",
"toggle": "Показывать связи Zigbee при наведении на устройство",
"hint": "Показываются только наблюдаемые прямые соседи. Наведение ничего не запрашивает.",
+ "help": "Показывает, с какими устройствами Zigbee каждое связано напрямую. Цвет линии — качество связи (LQI) по той же шкале, что у показателя LQI устройства: красный при 40 и ниже, зелёный при 180 и выше. Пунктир — качество не сообщено. Стрелка ведёт к следующему устройству по пути к координатору: исходящая одна, входящие — те, кто ходит через это устройство. Линия без стрелки — запасной сосед. Это дерево маршрутов, которое строит House Plan, а не путь пакета в эту секунду: подпись на конце стрелки значит, что цель не на этом плане, а отсутствие стрелки — что путь неизвестен. Данные из последней загрузки и устаревают, связи видны только при работе мышью.",
+ "help_aria": "Справка: связи Zigbee",
"admin_only": "Данные топологии доступны только администраторам Home Assistant.",
"save_first": "Сохраните настройку перед загрузкой данных топологии.",
"zha": "ZHA",
diff --git a/test/zigbee-topology.test.mjs b/test/zigbee-topology.test.mjs
index 9d64c147..02c9970f 100644
--- a/test/zigbee-topology.test.mjs
+++ b/test/zigbee-topology.test.mjs
@@ -401,3 +401,106 @@ test('Z2M runtime refuses an unconfirmed base topic without publishing and still
assert.equal(cleanups, 2);
assert.equal(zigbeeTopologyRuntimeSnapshot(hass).states['z2m:zigbee2mqtt'].error, 'timeout');
});
+
+// #459. Подсказка «Связи Zigbee»: легенда живёт в словаре, и её содержание —
+// защитный контракт. Текст, называющий только цвет и пунктир, формально
+// «подсказка есть», но не отвечает ни на один вопрос про стрелки — ради
+// которых задача и ждала #457. Поэтому проверяется КАЖДЫЙ пункт легенды.
+
+const topologyDict = (code) => JSON.parse(readFileSync(
+ new URL(`../src/i18n/topology/${code}.json`, import.meta.url), 'utf8',
+));
+const TOPOLOGY_LANGS = ['en', 'ru', 'de', 'fr'];
+
+test('подсказка называет все шесть пунктов легенды (#459 AC3)', () => {
+ const help = topologyDict('ru').help;
+ const claims = [
+ // шкала LQI — обе границы, и они не выдуманы, а взяты из lqiColor (AC4)
+ [/\bLQI\b/, 'качество связи названо аббревиатурой LQI'],
+ [/\b40\b/, 'нижняя граница шкалы'],
+ [/\b180\b/, 'верхняя граница шкалы'],
+ [/[Пп]унктир/, 'пунктир как отдельное состояние линии'],
+ [/исходящ/i, 'исходящая стрелка'],
+ [/координатор/i, 'исходящая стрелка ведёт к координатору'],
+ [/входящ/i, 'входящие стрелки'],
+ [/без стрелки/i, 'линия без стрелки — запасной сосед'],
+ [/подпись на конце стрелки/i, 'подпись = цель не на этом плане'],
+ [/отсутствие стрелки/i, 'нет стрелки = путь неизвестен'],
+ ];
+ for (const [pattern, why] of claims) {
+ assert.match(help, pattern, `подсказка не называет: ${why}`);
+ }
+});
+
+test('подсказка предупреждает, что стрелки — не путь пакета (#459 AC3b)', () => {
+ // Оговорка унаследована от §6 ТЗ #457: дерево аплинков строим мы, и между
+ // роутерами это приближение. Без неё администратор примет стрелку за истину.
+ const help = topologyDict('ru').help;
+ // `\w` в JS-регулярке ASCII-словесный: «дерев\w+» на кириллице не совпадёт
+ // никогда. Ловушка та же, что с `\b` в счётчике раундов ревью (#454).
+ assert.match(help, /дерево маршрут/i);
+ assert.match(help, /не путь пакета/i);
+});
+
+test('границы шкалы в подсказке — те же, что у lqiColor (#459 AC4)', async () => {
+ const { lqiColor } = await import('../test-build/logic.js');
+ const hueOf = (value) => Number(/hsl\((\d+)/.exec(lqiColor(value))[1]);
+ // Красный край и зелёный край берутся из функции, а не из константы в тесте:
+ // сдвинется реализация — тест назовёт другие числа и подсказка разойдётся.
+ assert.equal(hueOf(40), 0, 'красный край шкалы');
+ assert.equal(hueOf(180), 120, 'зелёный край шкалы');
+ const help = topologyDict('ru').help;
+ assert.match(help, new RegExp(`\\b40\\b`));
+ assert.match(help, new RegExp(`\\b180\\b`));
+});
+
+test('подсказка не полагается на переносы строк (#459 AC5)', () => {
+ // hp-help кладёт .text текстовым узлом: \n схлопнется в пробел.
+ for (const code of TOPOLOGY_LANGS) {
+ const dict = topologyDict(code);
+ assert.ok(!dict.help.includes('\n'), `${code}: перенос строки в help`);
+ assert.ok(dict.help.trim().length > 0, `${code}: пустая подсказка`);
+ assert.ok(dict.help_aria.trim().length > 0, `${code}: пустая подпись для скринридера`);
+ }
+});
+
+test('словари topology несут один и тот же набор ключей (#459 AC6)', () => {
+ // Гейт, которого не было: i18n-dead-keys и i18n.test знают основной словарь,
+ // бэкендные переводы и support, но не namespace topology.
+ const english = Object.keys(topologyDict('en')).sort();
+ const placeholders = (value) => (String(value).match(/\{\w+\}/gu) || []).sort();
+ const en = topologyDict('en');
+ for (const code of TOPOLOGY_LANGS) {
+ const dict = topologyDict(code);
+ assert.deepEqual(Object.keys(dict).sort(), english, `${code}: набор ключей расходится`);
+ for (const key of english) {
+ assert.deepEqual(placeholders(dict[key]), placeholders(en[key]),
+ `${code}: плейсхолдеры расходятся в ${key}`);
+ }
+ }
+});
+
+test('кружок справки не рисуется без подписи для скринридера (#459 AC2)', async () => {
+ const { hasTopologyTranslation } = await import('../test-build/i18n/topology.js');
+ // Проверка идёт по СЛОВАРЮ, а не по строке: topologyT на отсутствующий ключ
+ // отвечает именем ключа, и «help» — вполне непустая строка.
+ assert.equal(hasTopologyTranslation('ru', 'help'), true);
+ assert.equal(hasTopologyTranslation('ru', 'help_aria'), true);
+ assert.equal(hasTopologyTranslation('ru', 'no_such_key'), false);
+ // Английский — слой фолбэка: ключ, которого нет в локали, но есть в en,
+ // доступен, как и в topologyT.
+ assert.equal(hasTopologyTranslation('de', 'help'), true);
+});
+
+test('подсказка вызывается из блока настройки топологии (#459 AC1)', () => {
+ const source = readFileSync(
+ new URL('../src/hp-zigbee-topology-settings.ts', import.meta.url), 'utf8',
+ );
+ // Кружок стоит у ЗАГОЛОВКА функции, а не у тумблера: он объясняет функцию,
+ // а не то, что делает галочка.
+ assert.match(source, /\$\{this\._t\('title'\)\}\$\{this\._help\(\)\}<\/div>/);
+ assert.match(source, /