From 665d5579d2f9bff5029d23f646f044def9b4bc71 Mon Sep 17 00:00:00 2001
From: Nick Shirokov <nick_4312@mail.ru>
Date: Sun, 1 Mar 2026 15:06:12 +0300
Subject: [PATCH] docs(web-test): add highlight API to recording docs and
 guides

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .claude/skills/web-test/SKILL.md     |  4 ++-
 .claude/skills/web-test/recording.md | 40 ++++++++++++++++++++++++++--
 docs/web-test-guide.md               |  4 +++
 3 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/.claude/skills/web-test/SKILL.md b/.claude/skills/web-test/SKILL.md
index cd864d55..c3f225a1 100644
--- a/.claude/skills/web-test/SKILL.md
+++ b/.claude/skills/web-test/SKILL.md
@@ -286,8 +286,10 @@ Clear filters. Without arguments clears all, with `{ field }` clears specific ba
 #### `showCaption(text, opts?)` / `hideCaption()` → text overlay on page
 #### `showTitleSlide(text, opts?)` / `hideTitleSlide()` → full-screen title card (intro/outro)
 #### `isRecording()` → boolean
+#### `setHighlight(on)` / `isHighlightMode()` → auto-highlight mode for video
+#### `highlight(text)` / `unhighlight()` → manual element highlighting
 
-See [recording.md](recording.md) for setup (ffmpeg), API details, and examples.
+See [recording.md](recording.md) for setup (ffmpeg), highlight mode, API details, and examples.
 If `.v8-project.json` has `ffmpegPath`, pass it to `startRecording({ ffmpegPath })`.
 
 ## Common patterns
diff --git a/.claude/skills/web-test/recording.md b/.claude/skills/web-test/recording.md
index b189ba34..afd05780 100644
--- a/.claude/skills/web-test/recording.md
+++ b/.claude/skills/web-test/recording.md
@@ -112,7 +112,39 @@ The overlay covers the entire viewport with `z-index: 999999` and `pointer-event
 
 Remove the title slide overlay.
 
-## Example: Record a workflow with title slide and captions
+### `setHighlight(on)`
+
+Enable or disable auto-highlight mode. When enabled, action functions (`navigateSection`, `openCommand`, `clickElement`, `selectValue`, `fillFields`) automatically highlight the target element for 500ms before performing the action.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `on` | boolean | `true` to enable, `false` to disable |
+
+**How it works**: each action highlights the element → waits 500ms (viewer reads) → removes highlight → performs the action. This prevents the highlight overlay from interfering with modals, dropdowns, or focus changes caused by the action.
+
+**Search priority**: form elements (buttons, links, fields, grid rows) are searched first. Sections and commands are used as fallback only if the element is not found in the current form. This avoids false matches (e.g., "ОК" matching section "Покупки" via substring).
+
+### `isHighlightMode()` → boolean
+
+Check if auto-highlight mode is active.
+
+### `highlight(text)`
+
+Manually highlight a UI element by name (fuzzy match). Places a semi-transparent blue overlay (`rgba(0,100,255,0.25)`) with a border on the element. The overlay tracks element position via `requestAnimationFrame`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | string | Element name — button, link, field, section, or command |
+
+- Fuzzy match order: exact → startsWith → includes
+- Searches form elements first, then sections/commands
+- `pointer-events: none` — does not block clicks
+
+### `unhighlight()`
+
+Remove the highlight overlay.
+
+## Example: Record a workflow with highlight, title slide, and captions
 
 ```js
 await startRecording('recordings/create-order.mp4');
@@ -121,8 +153,9 @@ await startRecording('recordings/create-order.mp4');
 await showTitleSlide('Создание заказа клиента', { subtitle: 'Демонстрация' });
 await wait(4);
 await hideTitleSlide();
+setHighlight(true); // enable auto-highlight for all actions
 
-// Steps: caption → pause → action
+// Steps: caption → pause → action (highlight is automatic)
 await showCaption('Шаг 1. Переходим в раздел «Продажи»');
 await wait(1.5);
 await navigateSection('Продажи');
@@ -142,12 +175,15 @@ await fillFields({ 'Организация': 'Конфетпром', 'Контр
 await wait(1);
 
 await hideCaption();
+setHighlight(false);
 const result = await stopRecording();
 console.log(`Recorded ${result.duration}s, ${(result.size / 1024 / 1024).toFixed(1)} MB`);
 ```
 
 **Caption timing**: show the caption *before* the action with a `wait(1.5)` pause — the viewer reads what will happen, then sees it happen. Add `wait()` *after* the action only when the next step needs the result to load (e.g., form opening).
 
+**Highlight timing**: `setHighlight(true)` enables auto-mode — each action function highlights the target for 500ms, then removes the highlight before performing the action. No manual `highlight()`/`unhighlight()` calls needed. Enable after title slide, disable before `stopRecording()`.
+
 ## Troubleshooting
 
 | Problem | Solution |
diff --git a/docs/web-test-guide.md b/docs/web-test-guide.md
index 941791aa..744c50ef 100644
--- a/docs/web-test-guide.md
+++ b/docs/web-test-guide.md
@@ -258,6 +258,10 @@ await closeForm({ save: false });
 | `showTitleSlide(text, opts?)` | Полноэкранный титульный слайд (`\n` → перенос, `subtitle`, `background`) |
 | `hideTitleSlide()` | Убрать титульный слайд |
 | `isRecording()` | Идёт ли запись (boolean) |
+| `setHighlight(on)` | Включить/выключить авто-выделение элементов при действиях |
+| `isHighlightMode()` | Активен ли режим авто-выделения (boolean) |
+| `highlight(text)` | Ручное выделение элемента (по имени, fuzzy match) |
+| `unhighlight()` | Снять выделение |
 
 ## Клавиатурные сочетания