From a2b418b78aadc246737783f7763c5cdc37bb1bc7 Mon Sep 17 00:00:00 2001
From: Ivan Fontosh <ifontosh@it-aces.com>
Date: Tue, 28 Jul 2026 12:13:53 +0800
Subject: [PATCH] feat(help): traps/tokens/grid sections and clickable
 cross-links

Add instruction pages for traps, non-player tokens, and grid generator, and turn section mentions into in-modal navigation links.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 app/renderer/editor/EditorApp.module.css      |  18 +++
 .../editor/about/EditorAboutModals.tsx        |  41 ++++++-
 app/renderer/editor/help/helpLinkify.test.ts  |  82 +++++++++++++
 app/renderer/editor/help/helpLinkify.ts       | 115 ++++++++++++++++++
 app/renderer/editor/help/helpSections.ts      |   3 +
 app/renderer/editor/i18n/editorMessages.ts    |  44 +++++--
 package.json                                  |   2 +-
 7 files changed, 289 insertions(+), 16 deletions(-)
 create mode 100644 app/renderer/editor/help/helpLinkify.test.ts
 create mode 100644 app/renderer/editor/help/helpLinkify.ts

diff --git a/app/renderer/editor/EditorApp.module.css b/app/renderer/editor/EditorApp.module.css
index 5dd61c3..d966fc8 100644
--- a/app/renderer/editor/EditorApp.module.css
+++ b/app/renderer/editor/EditorApp.module.css
@@ -495,6 +495,24 @@
   margin-bottom: 0;
 }
 
+.instructionsInlineLink {
+  display: inline;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  color: var(--accent, #a78bfa);
+  font: inherit;
+  font-weight: 700;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  cursor: pointer;
+}
+
+.instructionsInlineLink:hover {
+  color: var(--text0);
+}
+
 .instructionsNav {
   min-height: 0;
   overflow: auto;
diff --git a/app/renderer/editor/about/EditorAboutModals.tsx b/app/renderer/editor/about/EditorAboutModals.tsx
index e6b0611..fca2ec7 100644
--- a/app/renderer/editor/about/EditorAboutModals.tsx
+++ b/app/renderer/editor/about/EditorAboutModals.tsx
@@ -1,9 +1,10 @@
-import React, { useEffect, useState } from 'react';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 
 import { APP_DISPLAY_NAME_EN, APP_DISPLAY_NAME_RU } from '../../../shared/appBranding';
 import { Button } from '../../shared/ui/controls';
 import styles from '../EditorApp.module.css';
+import { buildHelpLinkCatalog, splitHelpTextWithLinks } from '../help/helpLinkify';
 import {
   HELP_SECTION_IDS,
   helpSectionBodyKey,
@@ -107,6 +108,8 @@ function InstructionsModalBody({
 }) {
   const { t } = useEditorI18n();
   const [activeId, setActiveId] = useState<HelpSectionId>(initialSection);
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  const navRef = useRef<HTMLElement | null>(null);
 
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
@@ -116,9 +119,24 @@ function InstructionsModalBody({
     return () => window.removeEventListener('keydown', onKey);
   }, [onClose]);
 
+  useEffect(() => {
+    contentRef.current?.scrollTo({ top: 0 });
+    const activeNav = navRef.current?.querySelector<HTMLElement>('[aria-current="true"]');
+    activeNav?.scrollIntoView({ block: 'nearest' });
+  }, [activeId]);
+
+  const linkCatalog = useMemo(
+    () => buildHelpLinkCatalog((id) => t(helpSectionTitleKey(id))),
+    [t],
+  );
+
   const body = t(helpSectionBodyKey(activeId));
   const paragraphs = body.split('\n\n').filter((p) => p.trim() !== '');
 
+  const goToSection = (id: HelpSectionId) => {
+    setActiveId(id);
+  };
+
   return createPortal(
     <>
       <button
@@ -140,15 +158,28 @@ function InstructionsModalBody({
           </button>
         </div>
         <div className={styles.instructionsLayout}>
-          <div className={styles.instructionsContent}>
+          <div ref={contentRef} className={styles.instructionsContent}>
             <div className={styles.instructionsContentTitle}>{t(helpSectionTitleKey(activeId))}</div>
             {paragraphs.map((p, i) => (
               <p key={i} className={styles.instructionsParagraph}>
-                {p}
+                {splitHelpTextWithLinks(p, linkCatalog).map((part, j) =>
+                  part.type === 'text' ? (
+                    <React.Fragment key={j}>{part.value}</React.Fragment>
+                  ) : (
+                    <button
+                      key={j}
+                      type="button"
+                      className={styles.instructionsInlineLink}
+                      onClick={() => goToSection(part.id)}
+                    >
+                      {part.value}
+                    </button>
+                  ),
+                )}
               </p>
             ))}
           </div>
-          <nav className={styles.instructionsNav} aria-label={t('help.navAria')}>
+          <nav ref={navRef} className={styles.instructionsNav} aria-label={t('help.navAria')}>
             {HELP_SECTION_IDS.map((id) => (
               <button
                 key={id}
@@ -160,7 +191,7 @@ function InstructionsModalBody({
                   .filter(Boolean)
                   .join(' ')}
                 aria-current={id === activeId ? 'true' : undefined}
-                onClick={() => setActiveId(id)}
+                onClick={() => goToSection(id)}
               >
                 {t(helpSectionTitleKey(id))}
               </button>
diff --git a/app/renderer/editor/help/helpLinkify.test.ts b/app/renderer/editor/help/helpLinkify.test.ts
new file mode 100644
index 0000000..2afac61
--- /dev/null
+++ b/app/renderer/editor/help/helpLinkify.test.ts
@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import type { HelpSectionId } from './helpSections';
+import { buildHelpLinkCatalog, findHelpLinkRanges, splitHelpTextWithLinks } from './helpLinkify';
+
+const RU_TITLES: Record<HelpSectionId, string> = {
+  overview: 'Обзор приложения',
+  license: 'Лицензия и первый запуск',
+  projects: 'Проекты',
+  scenes: 'Сцены',
+  graph: 'Граф сцен',
+  sideStorylines: 'Побочные сюжетные линии',
+  sceneProps: 'Свойства сцены',
+  sceneEditor: 'Редактор сцены',
+  grid: 'Генератор сетки',
+  traps: 'Ловушки',
+  tokens: 'Неигровые токены',
+  campaignAudio: 'Аудио игры',
+  materials: 'Материалы',
+  npcs: 'НПС',
+  session: 'Запуск сессии',
+  controlPanel: 'Пульт управления',
+  transitions: 'Переходы между сценами',
+  music: 'Музыка на пульте',
+  effects: 'Эффекты поля и действий',
+  presentation: 'Экран презентации',
+  importExport: 'Импорт и экспорт',
+  settings: 'Настройки, язык и обновления',
+};
+
+void test('findHelpLinkRanges: «Ловушки» и алиас «Эффекты»', () => {
+  const catalog = buildHelpLinkCatalog((id) => RU_TITLES[id]);
+  const text =
+    'см. «Ловушки» и кистью (см. «Эффекты»). Также разделы «Генератор сетки», «Неигровые токены».';
+  const ranges = findHelpLinkRanges(text, catalog);
+  assert.deepEqual(
+    ranges.map((r) => r.id),
+    ['traps', 'effects', 'grid', 'tokens'],
+  );
+});
+
+void test('findHelpLinkRanges: длинный title предпочитается короткому алиасу', () => {
+  const catalog = buildHelpLinkCatalog((id) => RU_TITLES[id]);
+  const text = 'Откройте «Редактор сцены» и «Генератор сетки».';
+  const ranges = findHelpLinkRanges(text, catalog);
+  assert.equal(ranges.length, 2);
+  assert.equal(ranges[0]?.id, 'sceneEditor');
+  assert.equal(ranges[1]?.id, 'grid');
+});
+
+void test('splitHelpTextWithLinks: EN see Scene editor / Traps', () => {
+  const getTitle = (id: HelpSectionId): string => {
+    const map: Partial<Record<HelpSectionId, string>> = {
+      sceneEditor: 'Scene editor',
+      traps: 'Traps',
+      tokens: 'Non-player tokens',
+      grid: 'Grid generator',
+      effects: 'Field and action effects',
+      controlPanel: 'Control panel',
+    };
+    return map[id] ?? id;
+  };
+  const catalog = buildHelpLinkCatalog(getTitle);
+  const parts = splitHelpTextWithLinks(
+    'For details, see Grid generator, Traps, and Non-player tokens. Also see Effects.',
+    catalog,
+  );
+  const links = parts.filter((p) => p.type === 'link');
+  assert.deepEqual(
+    links.map((p) => (p.type === 'link' ? p.id : null)),
+    ['grid', 'traps', 'tokens', 'effects'],
+  );
+});
+
+void test('findHelpLinkRanges: полное «Пульт управления» не режется до «Пульт»', () => {
+  const catalog = buildHelpLinkCatalog((id) => RU_TITLES[id]);
+  const ranges = findHelpLinkRanges('см. «Пульт управления»', catalog);
+  assert.equal(ranges.length, 1);
+  assert.equal(ranges[0]?.id, 'controlPanel');
+  assert.equal(ranges[0]?.text, '«Пульт управления»');
+});
diff --git a/app/renderer/editor/help/helpLinkify.ts b/app/renderer/editor/help/helpLinkify.ts
new file mode 100644
index 0000000..4dd5a7f
--- /dev/null
+++ b/app/renderer/editor/help/helpLinkify.ts
@@ -0,0 +1,115 @@
+import { HELP_SECTION_IDS, type HelpSectionId } from './helpSections';
+
+/**
+ * Короткие имена разделов в перекрёстных ссылках
+ * (когда в тексте не полное title, напр. «Эффекты» вместо «Эффекты поля и действий»).
+ */
+export const HELP_SECTION_LINK_ALIASES: Partial<Record<HelpSectionId, readonly string[]>> = {
+  effects: ['Эффекты', 'Effects'],
+  presentation: ['Презентация', 'Presentation'],
+  grid: ['Сетка', 'Grid'],
+  controlPanel: ['Пульт'],
+};
+
+export type HelpLinkCatalogEntry = {
+  id: HelpSectionId;
+  label: string;
+};
+
+export type HelpLinkRange = {
+  start: number;
+  end: number;
+  id: HelpSectionId;
+  text: string;
+};
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Каталог подписей → id, длинные первыми. */
+export function buildHelpLinkCatalog(getTitle: (id: HelpSectionId) => string): HelpLinkCatalogEntry[] {
+  const byLabel = new Map<string, HelpSectionId>();
+  for (const id of HELP_SECTION_IDS) {
+    const title = getTitle(id).trim();
+    if (title) byLabel.set(title, id);
+    for (const alias of HELP_SECTION_LINK_ALIASES[id] ?? []) {
+      const a = alias.trim();
+      if (a) byLabel.set(a, id);
+    }
+  }
+  return [...byLabel.entries()]
+    .map(([label, id]) => ({ id, label }))
+    .sort((a, b) => b.label.length - a.label.length || a.label.localeCompare(b.label));
+}
+
+function isBoundaryChar(ch: string | undefined): boolean {
+  if (ch === undefined) return true;
+  if (/^[\p{L}\p{N}]$/u.test(ch)) return false;
+  return true;
+}
+
+function collectMatches(text: string, label: string, id: HelpSectionId): HelpLinkRange[] {
+  const out: HelpLinkRange[] = [];
+  if (!label) return out;
+
+  const quoted = new RegExp(`«${escapeRegExp(label)}»`, 'g');
+  for (const m of text.matchAll(quoted)) {
+    if (m.index === undefined) continue;
+    out.push({ start: m.index, end: m.index + m[0].length, id, text: m[0] });
+  }
+
+  const bare = new RegExp(escapeRegExp(label), 'g');
+  for (const m of text.matchAll(bare)) {
+    if (m.index === undefined) continue;
+    const start = m.index;
+    const end = start + m[0].length;
+    const before = text[start - 1];
+    const after = text[end];
+    if (!isBoundaryChar(before) || !isBoundaryChar(after)) continue;
+    if (before === '«' && after === '»') continue;
+    out.push({ start, end, id, text: m[0] });
+  }
+  return out;
+}
+
+export function findHelpLinkRanges(text: string, catalog: readonly HelpLinkCatalogEntry[]): HelpLinkRange[] {
+  const candidates: HelpLinkRange[] = [];
+  for (const entry of catalog) {
+    candidates.push(...collectMatches(text, entry.label, entry.id));
+  }
+  candidates.sort(
+    (a, b) => a.start - b.start || b.end - b.start - (a.end - a.start),
+  );
+
+  const selected: HelpLinkRange[] = [];
+  let cursor = 0;
+  for (const range of candidates) {
+    if (range.start < cursor) continue;
+    selected.push(range);
+    cursor = range.end;
+  }
+  return selected;
+}
+
+export function splitHelpTextWithLinks(
+  text: string,
+  catalog: readonly HelpLinkCatalogEntry[],
+): Array<{ type: 'text'; value: string } | { type: 'link'; id: HelpSectionId; value: string }> {
+  const ranges = findHelpLinkRanges(text, catalog);
+  if (ranges.length === 0) return [{ type: 'text', value: text }];
+  const parts: Array<{ type: 'text'; value: string } | { type: 'link'; id: HelpSectionId; value: string }> =
+    [];
+  let cursor = 0;
+  for (const range of ranges) {
+    if (range.start > cursor) {
+      parts.push({ type: 'text', value: text.slice(cursor, range.start) });
+    }
+    parts.push({ type: 'link', id: range.id, value: range.text });
+    cursor = range.end;
+  }
+  if (cursor < text.length) {
+    parts.push({ type: 'text', value: text.slice(cursor) });
+  }
+  return parts;
+}
diff --git a/app/renderer/editor/help/helpSections.ts b/app/renderer/editor/help/helpSections.ts
index 39555ac..e627b8f 100644
--- a/app/renderer/editor/help/helpSections.ts
+++ b/app/renderer/editor/help/helpSections.ts
@@ -8,6 +8,9 @@ export const HELP_SECTION_IDS = [
   'sideStorylines',
   'sceneProps',
   'sceneEditor',
+  'grid',
+  'traps',
+  'tokens',
   'campaignAudio',
   'materials',
   'npcs',
diff --git a/app/renderer/editor/i18n/editorMessages.ts b/app/renderer/editor/i18n/editorMessages.ts
index 3bfe40b..89bf700 100644
--- a/app/renderer/editor/i18n/editorMessages.ts
+++ b/app/renderer/editor/i18n/editorMessages.ts
@@ -171,11 +171,23 @@ export const EDITOR_MESSAGES: Record<EditorLocale, Record<string, string>> = {
 
     'help.section.sceneProps.title': 'Свойства сцены',
     'help.section.sceneProps.body':
-      'Выберите сцену в списке слева — справа откроются её свойства.\n\n«Название сцены» — для мастера. «Описание» — заметки мастера с форматированием: рядом с подписью нажмите карандаш, откроется редактор (жирный, курсив, заголовки, списки, ссылки). Под подписью видно фрагмент текста или «описание отсутствует», если поле пустое. Во время сессии описание открывается с пульта в отдельном окне (см. «Пульт управления»), а не в блоке «Сюжетная линия».\n\nЕсли у сцены на карте есть карточка с синей меткой «ПОБОЧНАЯ», появится поле «Название побочной линии».\n\nКартинка или видео для игроков:\n\n1) В «Превью сцены» нажмите «Загрузить» или «Изменить».\n\n2) Выберите файл (PNG, JPG, WebP, GIF и др.).\n\n3) Для картинки можно «Повернуть» (шаг 90°). «Очистить» — убрать превью.\n\n4) Для картинки можно включить «Затемнить сцену»: при показе игроки сначала увидят карту в полной темноте, а вы снимете её с пульта «Кистью Открытия» (см. «Эффекты»).\n\n5) Для картинки доступна кнопка «Редактор сцены» — расстановка ловушек на карте (см. «Редактор сцены и ловушки»).\n\nДля видео включите «Автостарт», если ролик должен сам начаться на экране игроков. На видео-сценах эффекты кистью и редактор сцены недоступны.\n\n«Аудио сцены» — музыка и звуки этого эпизода. «Загрузить» добавляет файлы. У каждого трека: «Авто» (играть при входе в сцену) и «Цикл». Корзина удаляет трек.\n\nСвязи между сценами задаются на карте, а не здесь — см. «Граф сцен».',
+      'Выберите сцену в списке слева — справа откроются её свойства.\n\n«Название сцены» — для мастера. «Описание» — заметки мастера с форматированием: рядом с подписью нажмите карандаш, откроется редактор (жирный, курсив, заголовки, списки, ссылки). Под подписью видно фрагмент текста или «описание отсутствует», если поле пустое. Во время сессии описание открывается с пульта в отдельном окне (см. «Пульт управления»), а не в блоке «Сюжетная линия».\n\nЕсли у сцены на карте есть карточка с синей меткой «ПОБОЧНАЯ», появится поле «Название побочной линии».\n\nКартинка или видео для игроков:\n\n1) В «Превью сцены» нажмите «Загрузить» или «Изменить».\n\n2) Выберите файл (PNG, JPG, WebP, GIF и др.).\n\n3) Для картинки можно «Повернуть» (шаг 90°). «Очистить» — убрать превью.\n\n4) Для картинки можно включить «Затемнить сцену»: при показе игроки сначала увидят карту в полной темноте, а вы снимете её с пульта «Кистью Открытия» (см. «Эффекты»).\n\n5) Для картинки доступна кнопка «Редактор сцены» — сетка, ловушки и неигровые токены на карте (см. «Редактор сцены», «Генератор сетки», «Ловушки», «Неигровые токены»).\n\nДля видео включите «Автостарт», если ролик должен сам начаться на экране игроков. На видео-сценах эффекты кистью и редактор сцены недоступны.\n\n«Аудио сцены» — музыка и звуки этого эпизода. «Загрузить» добавляет файлы. У каждого трека: «Авто» (играть при входе в сцену) и «Цикл». Корзина удаляет трек.\n\nСвязи между сценами задаются на карте, а не здесь — см. «Граф сцен».',
 
-    'help.section.sceneEditor.title': 'Редактор сцены и ловушки',
+    'help.section.sceneEditor.title': 'Редактор сцены',
     'help.section.sceneEditor.body':
-      '«Редактор сцены» — отдельное окно, где на картинке сцены расставляют ловушки. Он доступен только для сцен с изображением (не с видео).\n\nОткрыть:\n\n1) Выберите сцену в списке слева.\n\n2) В «Свойствах сцены» загрузите картинку, если её ещё нет.\n\n3) Нажмите «Редактор сцены».\n\nСлева — палитра «Ловушки», справа — карта сцены.\n\nРасставить ловушку:\n\n1) Перетащите тип из палитры на нужное место карты.\n\n2) Перетащите маркер, чтобы сдвинуть его; потяните за уголок выделенного маркера — изменить размер.\n\n3) Delete / Backspace или кнопка «Удалить» — убрать выбранную ловушку.\n\nНавигация по карте: колесо мыши — зум; средняя кнопка мыши или Space+ЛКМ — сдвиг вида.\n\nТипы ловушек: Мимик, Взрыв, Яд, Пропасть, Стрела, Лазер и Свободная (универсальный маркер). Расстановка сохраняется в проекте вместе со сценой.\n\nВо время сессии:\n\n1) На пульте в «Предпросмотр экрана» вы видите все ловушки текущей сцены. Пока они скрыты от игроков, маркеры у вас слегка приглушены.\n\n2) На презентации маркеры появляются только после проявления или срабатывания.\n\n3) Правый клик по маркеру на пульте:\n• «Проявить» — показать игрокам без срабатывания.\n• «Активировать» — проявить и запустить эффект: у Мимика, Пропасти, Стрелы и Лазера — анимация и звук; у Яда и Взрыва — как соответствующие эффекты с пульта (облако яда / взрыв); у Свободной — короткая вспышка.\n• «Обезвредить» — показать как обезвреженную.\n\nСостояние ловушек (проявлены / сработали / обезврежены) сбрасывается при новом запуске сессии. Сами маркеры на карте остаются.',
+      '«Редактор сцены» — отдельное окно для подготовки карты: сетка боя, ловушки и неигровые токены. Доступен только для сцен с изображением (не с видео).\n\nОткрыть:\n\n1) Выберите сцену в списке слева.\n\n2) В «Свойствах сцены» загрузите картинку, если её ещё нет.\n\n3) Нажмите «Редактор сцены».\n\nСлева — аккордеоны «Сетка», «Неигровые токены» и «Ловушки»; справа — карта сцены.\n\nНавигация по карте: колесо мыши — зум; средняя кнопка мыши или Space+ЛКМ — сдвиг вида. Delete / Backspace убирает выделенный маркер на карте.\n\nПод аккордеонами кнопка «Очистить сцену» убирает с текущей карты все ловушки и токены (пул токенов приложения не трогает).\n\nПодробнее: разделы «Генератор сетки», «Ловушки» и «Неигровые токены».',
+
+    'help.section.grid.title': 'Генератор сетки',
+    'help.section.grid.body':
+      'Генератор сетки накладывает на картинку сцены боевую сетку — квадратную или гексагональную. Сетка помогает ориентироваться по клеткам во время боя и видна и вам на пульте, и игрокам на презентации.\n\nНастроить:\n\n1) Откройте «Редактор сцены» для сцены с изображением (см. «Редактор сцены»).\n\n2) Раскройте аккордеон «Сетка» слева.\n\n3) Включите «Наложить сетку» — линии появятся поверх карты.\n\n4) «Тип» — «Квадратная» или «Гексогональная».\n\n5) «Цвет» — оттенок линий (удобно подобрать контраст к карте).\n\n6) «Размер» — ползунок ячейки: чем больше значение, тем крупнее клетки.\n\nПока сетка выключена, тип, цвет и размер недоступны для изменения, но запомненные значения сохраняются и вернутся при повторном включении.\n\nНастройки сетки хранятся в проекте вместе со сценой. На видео-сценах генератор недоступен — только на картинках. Сетка рисуется под маркерами ловушек и токенов и не мешает их расставлять.',
+
+    'help.section.traps.title': 'Ловушки',
+    'help.section.traps.body':
+      'Ловушки — маркеры на карте сцены для скрытых угроз и сюрпризов. Расстановка хранится в проекте вместе со сценой; во время игры вы решаете, когда их показать игрокам.\n\nВ редакторе сцены:\n\n1) Откройте «Редактор сцены» для сцены с картинкой (см. «Редактор сцены»).\n\n2) Раскройте аккордеон «Ловушки» слева.\n\n3) Перетащите тип из палитры на нужное место карты.\n\n4) Перетащите маркер, чтобы сдвинуть его; потяните за уголок выделенного маркера — изменить размер.\n\n5) Delete / Backspace — убрать выделенную ловушку. «Очистить сцену» снимает все маркеры сразу.\n\nТипы: Мимик, Взрыв, Яд, Пропасть, Стрела, Лазер и Метка (универсальный маркер без особого эффекта).\n\nВо время сессии:\n\n1) На пульте в «Предпросмотр экрана» видны все ловушки текущей сцены. Пока они скрыты от игроков, маркеры у вас слегка приглушены.\n\n2) На презентации маркеры появляются только после проявления или срабатывания.\n\n3) Правый клик по маркеру на пульте:\n• «Проявить» — показать игрокам без срабатывания.\n• «Активировать» — проявить и запустить эффект: у Мимика, Пропасти, Стрелы и Лазера — анимация и звук; у Яда и Взрыва — как соответствующие эффекты с пульта (облако яда / взрыв); у Метки — короткая вспышка.\n• «Обезвредить» — показать как обезвреженную.\n\nСостояние ловушек (проявлены / сработали / обезврежены) сбрасывается при новом запуске сессии. Сами маркеры на карте остаются.',
+
+    'help.section.tokens.title': 'Неигровые токены',
+    'help.section.tokens.body':
+      'Неигровые токены — картинки существ, предметов и маркеров, которые вы ставите на карту сцены. Библиотека токенов хранится в приложении на этом компьютере (не внутри файла проекта). На сцене сохраняется только расстановка: какой токен, где стоит, размер и поворот.\n\nВ редакторе сцены:\n\n1) Откройте «Редактор сцены» для сцены с картинкой (см. «Редактор сцены»).\n\n2) Раскройте «Неигровые токены».\n\n3) «Добавить» — задайте уникальное название и изображение (кнопка выбора или перетаскивание файла).\n\n4) В поиске можно быстро найти токен по имени.\n\n5) Меню «⋮» у плитки — «Изменить» или «Удалить» (с подтверждением). Удаление из пула также убирает этот токен с текущей сцены.\n\n6) Перетащите плитку на карту, чтобы поставить токен. Выделите маркер: перетаскивание — сдвиг, уголок — размер, ручка поворота — угол. Delete / Backspace или ПКМ по маркеру — убрать с карты. «Очистить сцену» снимает все токены и ловушки со сцены.\n\nВо время сессии:\n\n1) На пульте в «Предпросмотр экрана» токены видны сразу (в отличие от ловушек их не нужно проявлять).\n\n2) Перетаскивайте токены левой кнопкой — новая позиция запоминается до конца текущей сессии, в том числе если вы возвращаетесь к сцене через «Сюжетную линию». При новом «Запустить» позиции снова берутся из редактора.\n\n3) На экране презентации токены только отображаются: клики и перетаскивание для игроков недоступны.\n\nПри экспорте и импорте сюжетных линий нужные файлы токенов упаковываются вместе с линией, чтобы на другом компьютере расстановка не «теряла» картинки.',
 
     'help.section.campaignAudio.title': 'Аудио игры',
     'help.section.campaignAudio.body':
@@ -195,7 +207,7 @@ export const EDITOR_MESSAGES: Record<EditorLocale, Record<string, string>> = {
 
     'help.section.controlPanel.title': 'Пульт управления',
     'help.section.controlPanel.body':
-      'Пульт — ваш стол во время игры. Игроки смотрят на презентацию, вы управляете всем отсюда.\n\nСлева сверху — «Инструменты», затем эффекты и ход сюжета; справа — мини-копия экрана игроков, варианты переходов и музыка.\n\nВ «Инструменты» кнопка с книгой открывает отдельное окно с оформленным описанием текущей сцены. Если описания нет, кнопка неактивна — при наведении подсказка «Описание отсутствует». Кнопка материалов (иконка карты) открывает окно со списком материалов кампании — подробнее в разделе «Материалы». Кнопка НПС (цветная иконка человека) открывает окно персонажей — см. раздел «НПС».\n\n«Предпросмотр экрана» показывает то же, что видят игроки. На сценах с картинкой здесь же рисуют эффекты — они сразу появляются на большом экране. Если на сцене расставлены ловушки, они видны на предпросмотре: правый клик по маркеру — проявить, активировать или обезвредить (см. «Редактор сцены и ловушки»).\n\n«Сюжетная линия» — цепочка пройденных эпизодов. Текущая сцена помечена «ТЕКУЩАЯ СЦЕНА». Клик по прошлому шагу переносит партию к тому месту на карте и добавляет новый шаг в историю.\n\n«Выключить демонстрацию» — закончить показ и вернуться в редактор.',
+      'Пульт — ваш стол во время игры. Игроки смотрят на презентацию, вы управляете всем отсюда.\n\nСлева сверху — «Инструменты», затем эффекты и ход сюжета; справа — мини-копия экрана игроков, варианты переходов и музыка.\n\nВ «Инструменты» кнопка с книгой открывает отдельное окно с оформленным описанием текущей сцены. Если описания нет, кнопка неактивна — при наведении подсказка «Описание отсутствует». Кнопка материалов (иконка карты) открывает окно со списком материалов кампании — подробнее в разделе «Материалы». Кнопка НПС (цветная иконка человека) открывает окно персонажей — см. раздел «НПС».\n\n«Предпросмотр экрана» показывает то же, что видят игроки. На сценах с картинкой здесь же рисуют эффекты — они сразу появляются на большом экране. Если на сцене расставлены ловушки, они видны на предпросмотре: правый клик по маркеру — проявить, активировать или обезвредить (см. «Ловушки»). Неигровые токены тоже видны на предпросмотре и их можно двигать до конца сессии (см. «Неигровые токены»).\n\n«Сюжетная линия» — цепочка пройденных эпизодов. Текущая сцена помечена «ТЕКУЩАЯ СЦЕНА». Клик по прошлому шагу переносит партию к тому месту на карте и добавляет новый шаг в историю.\n\n«Выключить демонстрацию» — закончить показ и вернуться в редактор.',
 
     'help.section.transitions.title': 'Переходы между сценами',
     'help.section.transitions.body':
@@ -211,7 +223,7 @@ export const EDITOR_MESSAGES: Record<EditorLocale, Record<string, string>> = {
 
     'help.section.presentation.title': 'Экран презентации',
     'help.section.presentation.body':
-      '«Презентация» — то, что видят игроки: картинка сцены (с учётом поворота из редактора) или видео по вашим настройкам.\n\nЭффекты с пульта накладываются поверх. Меню и кнопки мастера здесь не показываются.\n\nЕсли у сцены включено «Затемнить сцену», игроки сначала видят полностью чёрный экран. Мастер открывает карту «Кистью Открытия» на пульте.\n\nПри смене сцены с пульта картинка обновляется сама. Перенесите окно на экран для игроков и при необходимости спрячьте панель задач.\n\nПустой или тёмный экран — скорее всего, у сцены нет превью. Добавьте картинку в свойствах сцены в редакторе.',
+      '«Презентация» — то, что видят игроки: картинка сцены (с учётом поворота из редактора) или видео по вашим настройкам.\n\nЭффекты с пульта накладываются поверх. Меню и кнопки мастера здесь не показываются — клики по карте, ловушкам и токенам для игроков недоступны.\n\nЕсли у сцены включено «Затемнить сцену», игроки сначала видят полностью чёрный экран. Мастер открывает карту «Кистью Открытия» на пульте.\n\nПри смене сцены с пульта картинка обновляется сама. Перенесите окно на экран для игроков и при необходимости спрячьте панель задач.\n\nПустой или тёмный экран — скорее всего, у сцены нет превью. Добавьте картинку в свойствах сцены в редакторе.',
 
     'help.section.importExport.title': 'Импорт и экспорт',
     'help.section.importExport.body':
@@ -720,11 +732,23 @@ export const EDITOR_MESSAGES: Record<EditorLocale, Record<string, string>> = {
 
     'help.section.sceneProps.title': 'Scene properties',
     'help.section.sceneProps.body':
-      'Select a scene in the left list — its properties open on the right.\n\nScene title is for the GM. Description is GM notes with formatting: click the pencil next to the label to open the editor (bold, italic, headings, lists, links). Below the label you see a text preview, or “no description” when empty. During a session, open the description from the control panel in a separate window (see Control panel) — it is not shown inside the Storyline list.\n\nIf the scene has a graph card with a blue SIDE badge, a Side storyline title field appears.\n\nImage or video for players:\n\n1) Under Scene preview, click Upload or Change.\n\n2) Pick a file (PNG, JPG, WebP, GIF, etc.).\n\n3) For images, use Rotate (90° steps). Clear removes the preview.\n\n4) For images, enable Darken scene so players start in full darkness and you reveal the map with the Opening brush on the control panel (see Effects).\n\n5) For images, Scene editor opens trap placement on the map (see Scene editor and traps).\n\nFor video, enable Autostart if the clip should start on its own on the player screen. Brush effects and the scene editor are not available on video scenes.\n\nScene audio — music and sounds for this episode. Upload adds files. Per track: Auto (play when entering the scene) and Loop. The trash icon removes a track.\n\nLinks between scenes are drawn on the map, not here — see Scene graph.',
+      'Select a scene in the left list — its properties open on the right.\n\nScene title is for the GM. Description is GM notes with formatting: click the pencil next to the label to open the editor (bold, italic, headings, lists, links). Below the label you see a text preview, or “no description” when empty. During a session, open the description from the control panel in a separate window (see Control panel) — it is not shown inside the Storyline list.\n\nIf the scene has a graph card with a blue SIDE badge, a Side storyline title field appears.\n\nImage or video for players:\n\n1) Under Scene preview, click Upload or Change.\n\n2) Pick a file (PNG, JPG, WebP, GIF, etc.).\n\n3) For images, use Rotate (90° steps). Clear removes the preview.\n\n4) For images, enable Darken scene so players start in full darkness and you reveal the map with the Opening brush on the control panel (see Effects).\n\n5) For images, Scene editor opens the battle grid, traps, and non-player tokens on the map (see Scene editor, Grid generator, Traps, and Non-player tokens).\n\nFor video, enable Autostart if the clip should start on its own on the player screen. Brush effects and the scene editor are not available on video scenes.\n\nScene audio — music and sounds for this episode. Upload adds files. Per track: Auto (play when entering the scene) and Loop. The trash icon removes a track.\n\nLinks between scenes are drawn on the map, not here — see Scene graph.',
 
-    'help.section.sceneEditor.title': 'Scene editor and traps',
+    'help.section.sceneEditor.title': 'Scene editor',
     'help.section.sceneEditor.body':
-      'Scene editor is a separate window for placing traps on the scene image. It is available only for image scenes (not video).\n\nOpen it:\n\n1) Select a scene in the left list.\n\n2) In Scene properties, upload an image if the scene has none yet.\n\n3) Click Scene editor.\n\nOn the left is the Traps palette; on the right is the scene map.\n\nPlace a trap:\n\n1) Drag a type from the palette onto the map.\n\n2) Drag a marker to move it; drag the corner handle of the selected marker to resize.\n\n3) Delete / Backspace or the Delete button removes the selected trap.\n\nMap navigation: mouse wheel zooms; middle mouse button or Space+left-drag pans the view.\n\nTrap types: Mimic, Explosion, Poison, Pit, Arrow, Laser, and Freeform (a generic marker). Placement is saved with the scene in the project.\n\nDuring a session:\n\n1) On the control panel Screen preview you see every trap on the current scene. While still hidden from players, markers look slightly muted on your side.\n\n2) On presentation, markers appear only after reveal or activation.\n\n3) Right-click a marker on the control panel:\n• Reveal — show it to players without triggering.\n• Activate — reveal and play the effect: Mimic, Pit, Arrow, and Laser play animation and sound; Poison and Explosion use the matching control-panel effects (poison cloud / explosion); Freeform shows a short flash.\n• Disarm — show it as disarmed.\n\nTrap runtime state (revealed / triggered / disarmed) resets when you start a new session. Markers placed on the map remain.',
+      'Scene editor is a separate window for preparing the map: battle grid, traps, and non-player tokens. It is available only for image scenes (not video).\n\nOpen it:\n\n1) Select a scene in the left list.\n\n2) In Scene properties, upload an image if the scene has none yet.\n\n3) Click Scene editor.\n\nOn the left are the Grid, Non-player tokens, and Traps accordions; on the right is the scene map.\n\nMap navigation: mouse wheel zooms; middle mouse button or Space+left-drag pans the view. Delete / Backspace removes the selected marker on the map.\n\nUnder the accordions, Clear scene removes every trap and token from the current map (it does not delete tokens from the app library).\n\nFor details, see Grid generator, Traps, and Non-player tokens.',
+
+    'help.section.grid.title': 'Grid generator',
+    'help.section.grid.body':
+      'The grid generator overlays a battle grid on the scene image — square or hexagonal. It helps track cells in combat and is visible both on your control panel and on the players’ presentation.\n\nSet it up:\n\n1) Open Scene editor for an image scene (see Scene editor).\n\n2) Expand the Grid accordion on the left.\n\n3) Enable Overlay grid — lines appear over the map.\n\n4) Type — Square or Hexagonal.\n\n5) Color — line tint (pick contrast that suits the map).\n\n6) Size — cell size slider: higher values mean larger cells.\n\nWhile the grid is off, type, color, and size stay disabled, but the saved values return when you turn it back on.\n\nGrid settings are stored with the scene in the project. The generator is not available on video scenes — only on images. The grid draws under trap and token markers and does not block placing them.',
+
+    'help.section.traps.title': 'Traps',
+    'help.section.traps.body':
+      'Traps are markers on the scene map for hidden threats and surprises. Placement is stored with the scene in the project; during play you decide when players see them.\n\nIn the scene editor:\n\n1) Open Scene editor for an image scene (see Scene editor).\n\n2) Expand the Traps accordion on the left.\n\n3) Drag a type from the palette onto the map.\n\n4) Drag a marker to move it; drag the corner handle of the selected marker to resize.\n\n5) Delete / Backspace removes the selected trap. Clear scene removes all markers at once.\n\nTypes: Mimic, Explosion, Poison, Pit, Arrow, Laser, and Marker (a generic marker without a special effect).\n\nDuring a session:\n\n1) On the control panel Screen preview you see every trap on the current scene. While still hidden from players, markers look slightly muted on your side.\n\n2) On presentation, markers appear only after reveal or activation.\n\n3) Right-click a marker on the control panel:\n• Reveal — show it to players without triggering.\n• Activate — reveal and play the effect: Mimic, Pit, Arrow, and Laser play animation and sound; Poison and Explosion use the matching control-panel effects (poison cloud / explosion); Marker shows a short flash.\n• Disarm — show it as disarmed.\n\nTrap runtime state (revealed / triggered / disarmed) resets when you start a new session. Markers placed on the map remain.',
+
+    'help.section.tokens.title': 'Non-player tokens',
+    'help.section.tokens.body':
+      'Non-player tokens are images of creatures, props, and markers you place on the scene map. The token library lives in the app on this computer (not inside the project file). The scene only stores placements: which token, where it stands, size, and rotation.\n\nIn the scene editor:\n\n1) Open Scene editor for an image scene (see Scene editor).\n\n2) Expand Non-player tokens.\n\n3) Add — enter a unique name and an image (choose file or drop one).\n\n4) Use search to find a token by name.\n\n5) The ⋮ menu on a tile opens Edit or Delete (with confirmation). Deleting from the library also removes that token from the current scene.\n\n6) Drag a tile onto the map to place it. Select a marker: drag to move, corner handle to resize, rotate handle to turn. Delete / Backspace or right-click the marker removes it from the map. Clear scene removes all tokens and traps from the scene.\n\nDuring a session:\n\n1) On the control panel Screen preview, tokens are visible right away (unlike traps, they do not need revealing).\n\n2) Drag tokens with the left button — the new position is kept until the current session ends, including when you return to the scene via Storyline. A new Run resets positions to what you set in the editor.\n\n3) On the presentation screen tokens are display-only: players cannot click or drag them.\n\nWhen you export or import storylines, the needed token files are packed with the line so placements keep their images on another computer.',
 
     'help.section.campaignAudio.title': 'Game audio',
     'help.section.campaignAudio.body':
@@ -744,7 +768,7 @@ export const EDITOR_MESSAGES: Record<EditorLocale, Record<string, string>> = {
 
     'help.section.controlPanel.title': 'Control panel',
     'help.section.controlPanel.body':
-      'The control panel is your desk during play. Players watch presentation; you run everything from here.\n\nTop-left: Tools, then effects and storyline. On the right: a mini copy of the player screen, branch options, and music.\n\nUnder Tools, the book button opens a separate window with the current scene’s formatted description. If there is no description, the button is disabled — the tooltip reads “No description”. The materials button (map icon) opens a window with the campaign materials list — see the Materials section for details. The NPCs button (colored person icon) opens the characters window — see the NPCs section.\n\nScreen preview shows what players see. On image scenes, paint effects here — they appear on the big screen right away. If the scene has traps, they appear on the preview: right-click a marker to reveal, activate, or disarm (see Scene editor and traps).\n\nStoryline lists episodes you have visited. The current scene is marked CURRENT SCENE. Click an earlier step to move the party back to that spot and add a new history entry.\n\nStop presentation ends the show and unlocks the editor.',
+      'The control panel is your desk during play. Players watch presentation; you run everything from here.\n\nTop-left: Tools, then effects and storyline. On the right: a mini copy of the player screen, branch options, and music.\n\nUnder Tools, the book button opens a separate window with the current scene’s formatted description. If there is no description, the button is disabled — the tooltip reads “No description”. The materials button (map icon) opens a window with the campaign materials list — see the Materials section for details. The NPCs button (colored person icon) opens the characters window — see the NPCs section.\n\nScreen preview shows what players see. On image scenes, paint effects here — they appear on the big screen right away. If the scene has traps, they appear on the preview: right-click a marker to reveal, activate, or disarm (see Traps). Non-player tokens are also visible on the preview and can be moved until the session ends (see Non-player tokens).\n\nStoryline lists episodes you have visited. The current scene is marked CURRENT SCENE. Click an earlier step to move the party back to that spot and add a new history entry.\n\nStop presentation ends the show and unlocks the editor.',
 
     'help.section.transitions.title': 'Scene transitions',
     'help.section.transitions.body':
@@ -760,7 +784,7 @@ export const EDITOR_MESSAGES: Record<EditorLocale, Record<string, string>> = {
 
     'help.section.presentation.title': 'Presentation screen',
     'help.section.presentation.body':
-      'Presentation is what players see: the scene image (with rotation from the editor) or video according to your settings.\n\nEffects from the control panel draw on top. There are no GM menus or buttons here.\n\nIf Darken scene is enabled, players first see a fully black screen. The GM reveals the map with the Opening brush on the control panel.\n\nWhen you switch scenes from the control panel, the image updates automatically. Move the window to the display players watch and hide the taskbar if needed.\n\nA blank or dark screen usually means the scene has no preview — add one in scene properties in the editor.',
+      'Presentation is what players see: the scene image (with rotation from the editor) or video according to your settings.\n\nEffects from the control panel draw on top. There are no GM menus or buttons here — players cannot click the map, traps, or tokens.\n\nIf Darken scene is enabled, players first see a fully black screen. The GM reveals the map with the Opening brush on the control panel.\n\nWhen you switch scenes from the control panel, the image updates automatically. Move the window to the display players watch and hide the taskbar if needed.\n\nA blank or dark screen usually means the scene has no preview — add one in scene properties in the editor.',
 
     'help.section.importExport.title': 'Import and export',
     'help.section.importExport.body':
diff --git a/package.json b/package.json
index e62745d..967bbd6 100644
--- a/package.json
+++ b/package.json
@@ -10,7 +10,7 @@
     "build:obfuscate": "node scripts/build.mjs --production --obfuscate",
     "lint": "eslint . --max-warnings 0",
     "typecheck": "tsc -p tsconfig.eslint.json --noEmit",
-    "test": "tsx --test app/renderer/shared/ui/controls.tooltip.test.ts app/renderer/editor/state/projectState.race.test.ts app/renderer/editor/fileDrop.test.ts app/shared/graph/sceneListOrder.test.ts app/renderer/editor/graph/sceneCardById.test.ts app/renderer/editor/i18n/editorMessages.locale.test.ts app/renderer/editor/sceneDescriptionHtml.test.ts app/shared/graph/storylineExportImport.test.ts app/shared/foundry/foundryGraph.test.ts app/shared/ipc/contracts.mediaRemoval.test.ts app/shared/effectEraserHitTest.test.ts app/shared/fieldEffectEraser.test.ts app/renderer/control/controlApp.effectsPanel.test.ts app/renderer/control/controlApp.audioPerf.networkRegression.test.ts app/renderer/control/controlApp.brushPerf.networkRegression.test.ts app/renderer/shared/useAssetImageUrl.cache.test.ts app/main/sessionIpc.phase6.networkRegression.test.ts app/renderer/shared/sceneOverlay/sceneOverlayHost.test.ts app/renderer/shared/effects/PxiEffectsOverlay.pointer.test.ts app/renderer/shared/traps/trapActivation.test.ts app/main/windows/createWindows.editorClose.test.ts app/main/safeConsole.test.ts app/main/windows/bootWindow.test.ts app/main/effects/effectsStore.test.ts app/main/effects/sceneDarknessStore.test.ts app/main/sceneTraps/sceneTrapsStore.test.ts app/main/project/assetPrune.test.ts app/main/project/optimizeImageImport.test.ts app/main/project/scenePreviewThumbnail.test.ts app/main/project/fsRetry.test.ts app/main/project/zipRead.test.ts app/main/project/replaceFileAtomic.test.ts app/main/project/zipStore.legacyContract.test.ts app/shared/package.build.test.ts app/shared/license/canonicalJson.test.ts app/shared/license/productKey.test.ts app/shared/license/licenseService.networkRegression.test.ts app/shared/video/videoPlaybackPerf.networkRegression.test.ts app/shared/video/videoPlaybackLoop.networkRegression.test.ts app/main/license/verifyLicenseToken.test.ts app/main/license/machineFingerprint.test.ts && node --test scripts/build-env.test.mjs scripts/obfuscate-main.test.mjs scripts/release-mac-prep.test.mjs",
+    "test": "tsx --test app/renderer/shared/ui/controls.tooltip.test.ts app/renderer/editor/state/projectState.race.test.ts app/renderer/editor/fileDrop.test.ts app/shared/graph/sceneListOrder.test.ts app/renderer/editor/graph/sceneCardById.test.ts app/renderer/editor/i18n/editorMessages.locale.test.ts app/renderer/editor/help/helpLinkify.test.ts app/renderer/editor/sceneDescriptionHtml.test.ts app/shared/graph/storylineExportImport.test.ts app/shared/foundry/foundryGraph.test.ts app/shared/ipc/contracts.mediaRemoval.test.ts app/shared/effectEraserHitTest.test.ts app/shared/fieldEffectEraser.test.ts app/renderer/control/controlApp.effectsPanel.test.ts app/renderer/control/controlApp.audioPerf.networkRegression.test.ts app/renderer/control/controlApp.brushPerf.networkRegression.test.ts app/renderer/shared/useAssetImageUrl.cache.test.ts app/main/sessionIpc.phase6.networkRegression.test.ts app/renderer/shared/sceneOverlay/sceneOverlayHost.test.ts app/renderer/shared/effects/PxiEffectsOverlay.pointer.test.ts app/renderer/shared/traps/trapActivation.test.ts app/main/windows/createWindows.editorClose.test.ts app/main/safeConsole.test.ts app/main/windows/bootWindow.test.ts app/main/effects/effectsStore.test.ts app/main/effects/sceneDarknessStore.test.ts app/main/sceneTraps/sceneTrapsStore.test.ts app/main/project/assetPrune.test.ts app/main/project/optimizeImageImport.test.ts app/main/project/scenePreviewThumbnail.test.ts app/main/project/fsRetry.test.ts app/main/project/zipRead.test.ts app/main/project/replaceFileAtomic.test.ts app/main/project/zipStore.legacyContract.test.ts app/shared/package.build.test.ts app/shared/license/canonicalJson.test.ts app/shared/license/productKey.test.ts app/shared/license/licenseService.networkRegression.test.ts app/shared/video/videoPlaybackPerf.networkRegression.test.ts app/shared/video/videoPlaybackLoop.networkRegression.test.ts app/main/license/verifyLicenseToken.test.ts app/main/license/machineFingerprint.test.ts && node --test scripts/build-env.test.mjs scripts/obfuscate-main.test.mjs scripts/release-mac-prep.test.mjs",
     "format": "prettier . --check",
     "format:write": "prettier . --write",
     "postinstall": "patch-package",