Mark
cb1a729962
Task 2 of Plan 01-11 (Puppeteer UAT harness).
Test hook surface:
- src/test-hooks/types.ts: canonical MokoshTestSurface — handlers
(onClicked, onStartup, notificationOnClicked), notificationCount,
lastNotificationOptions<true>, notificationIds, getCurrentStream,
getSegmentCount. globalThis.__mokoshTest ambient declaration.
- src/test-hooks/sw-hooks.ts: SW-side hook. Monkey-patches addListener
on chrome.action.onClicked / chrome.runtime.onStartup / chrome
.notifications.onClicked to capture handler refs while chaining to
the original. Wraps chrome.notifications.create across all four
overload shapes (id+options+cb, options+cb, id+options→Promise,
options→Promise) to increment notificationCount, save
lastNotificationOptions, push resolved id into notificationIds.
- src/test-hooks/offscreen-hooks.ts: offscreen-side hook. Exports
setCurrentStream + setSegmentCountGetter; the recorder calls both
inside startRecording after the mediaStream + segments assignments.
getCurrentStream getter closes over the cell so the harness reads
the live MediaStream for displaySurface inspection + 'ended'
dispatch (Bug B BLOCKER per RESEARCH §7).
- tests/uat/lib/test-hook-contract.d.ts: manual harness-side mirror of
MokoshTestSurface (decoupled from src/ to keep tests/ import-clean
per RESEARCH §11 resolution 5; drift risk documented inline).
Production-side wires (gated by __MOKOSH_UAT__ token):
- src/background/index.ts top-of-module: `if (__MOKOSH_UAT__) { await
import('../test-hooks/sw-hooks'); }`. MUST run before any chrome.*
addListener call below — top-of-module placement satisfies this.
- src/offscreen/recorder.ts top-of-module: symmetric gated dynamic
import + module-scoped testHooks reference.
- src/offscreen/recorder.ts inside startRecording (after mediaStream
assignment): `if (__MOKOSH_UAT__) { testHooks?.setCurrentStream(stream);
testHooks?.setSegmentCountGetter(() => segments.length); }`
- src/offscreen/recorder.ts inside onUserStoppedSharing (after
mediaStream = null): `if (__MOKOSH_UAT__) { testHooks?.setCurrentStream(null); }`
— T-1-11-05 (Repudiation: stale stream ref) mitigation.
Build-time token wiring:
- vite.config.ts: declares `define: { __MOKOSH_UAT__: 'false' }` (prod
default) + bumps `build.target: 'es2022'` so the top-level await in
the gated dynamic imports compiles (MDN: Chrome 89 / Edge 89 /
Firefox 89 / Safari 15 support TLA; MV3 floor Chrome 88 is
effectively Chrome 89+ in field — comfortably inside the envelope).
- vite.test.config.ts: overrides `define: { __MOKOSH_UAT__: 'true' }`
so the test bundle has the hooks active.
- vitest.config.ts: declares `define: { __MOKOSH_UAT__: 'false' }` for
vitest's own source-loading runs. CRITICAL — without this, vitest
would throw `ReferenceError: __MOKOSH_UAT__ is not defined` when
loading src/background/index.ts; OR if we'd used `import.meta.env.MODE
=== 'test'` (RESEARCH §6's initial guidance), vitest's default
MODE='test' would have ACTIVATED the hooks under unit tests +
clobbered every existing vi.fn() chrome.notifications.create mock.
The dedicated `__MOKOSH_UAT__` token sidesteps both failure modes
cleanly — a refinement on RESEARCH §6 documented in the comment
preambles of all three configs.
- globals.d.ts: declares `__MOKOSH_UAT__: boolean` ambient so
`npx tsc --noEmit` passes without per-file annotations.
- tsconfig.json: include adds `globals.d.ts`.
Notification options generic refinement:
- chrome.notifications.NotificationOptions is declared with a
`<true | false>` generic distinguishing "create" (all required —
true) from "update" (all optional — false). Plan 01-11's production
code always uses the create shape; types.ts + sw-hooks.ts pin to
`NotificationOptions<true>` so the harness reads iconUrl etc. as
definitely-present.
Verification:
- npx tsc --noEmit: exit 0
- npm run build: exit 0
- grep -rln '__mokoshTest\|simulateUserStop\|getSegmentCount\|setCurrentStream\|setSegmentCountGetter' dist/:
ZERO matches (Tier-1 gate stays GREEN)
- npm run build:test: exit 0; dist-test/ emits separate sw-hooks-*.js
+ offscreen-hooks-*.js chunks (the gated dynamic imports survive
tree-shaking when __MOKOSH_UAT__ === true)
- grep -rln '__mokoshTest' dist-test/: 2 matches
(assets/sw-hooks-*.js + assets/offscreen-hooks-*.js)
- SKIP_BUILD=1 npx vitest run: 89/89 GREEN
(83 baseline + 6 Tier-1 hook-leak surfaces)
- sw-bundle-import.test.ts: GREEN (the gated dynamic import does not
break production module init — the `if (false)` branch is never
reachable so the await + import are dead code in dist/)
In-flight bugs auto-fixed (Rule 1 + Rule 3):
- Rule 3: original RESEARCH §6 plan called for `import.meta.env.MODE
=== 'test'` as the gate; switched to `__MOKOSH_UAT__` define-token
after observing vitest contamination (vitest defaults MODE='test'
→ hooks activated under unit tests → 8 existing tests broke with
"Cannot read properties of undefined (reading 'calls')" because the
hook wrapper replaced vi.fn() mocks). Documented in the comment
preambles of all three configs as a refinement on RESEARCH §6.
- Rule 3: esbuild rejected TLA against the default ES2020 target;
bumped to es2022 (Chrome 89+ supports TLA per MDN — inside MV3
envelope). Recorded in vite.config.ts preamble.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
AI Call Recorder - Браузерное расширение для записи сессий операторов
Фаза 1 — Локальная запись + экспорт архива
Установка и запуск
Разработка
# Установка зависимостей
npm install
# Сборка для разработки с HMR
npm run dev
# Сборка для продакшена
npm run build
Установка расширения в Chrome
-
Соберите проект:
npm run build -
Откройте Chrome и перейдите по адресу:
chrome://extensions/ -
Включите "Режим разработчика" (Developer mode) в правом верхнем углу
-
Нажмите кнопку "Загрузить распакованное расширение" (Load unpacked)
-
Выберите папку
distв корне проекта -
Расширение установлено!
Использование
-
При первом открытии popup расширение запросит разрешение на запись экрана
-
Разрешение обязательно для работы расширения
-
Расширение автоматически начнет запись:
- Видео: последние 30 секунд (кольцевой буфер)
- DOM-события через rrweb: последние 10 минут
- Лог действий пользователя: последние 10 минут
-
Для сохранения отчета об ошибке:
- Нажмите на иконку расширения
- Нажмите кнопку "Сохранить отчёт об ошибке"
- Архив автоматически загрузится в папку "Загрузки"
Структура архива
Архив session_report_YYYY-MM-DD_HH-MM-SS.zip содержит:
session_report_2025-05-15_14-32-10.zip
├── video/
│ └── last_30sec.webm # склеенные чанки видеобуфера
├── rrweb/
│ └── session.json # массив DOM-событий rrweb
├── logs/
│ └── events.json # лог действий пользователя
├── screenshot.png # скриншот в момент сохранения
└── meta.json # метаданные сессии
Технический стек
- Тип расширения: Chrome Extension, Manifest V3
- Service Worker: Background script (Manifest V3)
- Захват экрана:
chrome.tabCaptureAPI - Захват DOM:
rrweb(npm: rrweb) - Лог событий: Content Script
- Упаковка архива:
JSZip(npm: jszip) - Сохранение файла:
chrome.downloadsAPI - Хранение буфера: In-memory (Service Worker + Content Script)
- Build: Vite + crxjs + TypeScript
Особенности
Маскирование чувствительных данных
- Пароли (
input[type=password]) маскируются автоматически в rrweb и логах - Поля с атрибутом
data-sensitive="true"также маскируются в rrweb
Записываемые события
Пользовательские события
- click — клик по любому элементу
- input — изменение значения поля (без паролей)
- navigation — переходы по страницам (popstate, hashchange, History API)
- js_error — JavaScript ошибки (window.onerror, unhandledrejection)
- network_error — сетевые ошибки (fetch/XHR с кодом ответа >= 400)
Кольцевой буфер
- Видео: 30 секунд, первый чанк (WebM заголовок) хранится всегда
- rrweb события: 10 минут, максимум 5000 событий
- Пользовательские события: 10 минут
Память
- Ожидаемое потребление: ~5-10 МБ в фоновом режиме
Критерии приёмки Фазы 1
- ✅ Расширение устанавливается в Chrome без ошибок
- ✅ Видеобуфер непрерывно работает на любой вкладке
- ✅ В буфере всегда есть не более 30 секунд видео
- ✅ rrweb пишет DOM-события без ошибок на типовых страницах
- ✅ Лог событий фиксирует клики, навигацию и сетевые ошибки
- ✅ При нажатии кнопки архив скачивается в "Загрузки" за < 5 секунд
- ✅ Архив открывается,
last_30sec.webmвоспроизводится в браузере - ✅ Пароли не попадают в лог и rrweb-снимки
- ✅ RAM-потребление расширения не превышает 50 МБ в фоне
Отладка
Console Logs
Расширение пишет подробные логи в консоль:
- Service Worker: Chrome DevTools → Extensions → Service Worker → Console
- Content Script: Chrome DevTools на любой странице → Console
- Popup: Правый клик по popup → Проверить
Структура проекта
ai-call-extension/
├── src/
│ ├── background/ # Service Worker
│ │ └── index.ts
│ ├── content/ # Content Script
│ │ └── index.ts
│ ├── popup/ # Popup UI
│ │ ├── index.html
│ │ ├── index.ts
│ │ └── style.css
│ └── shared/ # Общие типы и утилиты
│ ├── types.ts
│ └── logger.ts
├── icons/ # Иконки расширения
├── dist/ # Собранные файлы
├── manifest.json # Manifest расширения
├── vite.config.ts # Конфигурация Vite
├── tsconfig.json # Конфигурация TypeScript
└── package.json
Лицензия
MIT
Контакты
Для вопросов и предложений обращайтесь в support.