Mokosh

What This Is

Mokosh is a Chrome Manifest V3 browser extension that silently and continuously records an operator's browser session — the last 30 seconds of active-tab video, the last 10 minutes of DOM events (via rrweb), and the last 10 minutes of user and runtime events — and, on a single button press, packages everything plus a screenshot into a self-contained ZIP delivered to the user's "Downloads" folder for handoff to support.

The name is taken from Mokosh (Мокошь), the Slavic goddess of fate and weaving: each operator session is a thread she weaves into the archive.

Core Value

When an operator hits a bug, one click MUST produce a self-contained archive that lets support reproduce what happened — in under five seconds, with no server involved, and with the operator's passwords never appearing in the output.

Requirements

Validated

(None yet — Phase 1 of the SPEC ships from a partially-broken first attempt; nothing is validated until SPEC §10 acceptance passes.)

Active

Continuous 30 s active-tab video ring buffer (REQ-video-ring-buffer)
10 min / 5 000-event rrweb DOM buffer with sensitive masking (REQ-rrweb-dom-buffer)
10 min user/runtime event log with password filtering (REQ-user-event-log)
One-shot screenshot at export time (REQ-screenshot-on-export)
Russian-language popup with idle → "Сохраняю..." → "Готово! ✓" state machine (REQ-popup-ui)
ZIP archive layout session_report_YYYY-MM-DD_HH-MM-SS.zip (REQ-archive-layout)
meta.json schema (REQ-meta-json-schema)
Exact manifest permission set per SPEC §7 (REQ-manifest-permissions)
Click-to-download latency < 5 s (REQ-archive-export-latency)
Passwords never appear in rrweb snapshots or event log (REQ-password-confidentiality)
Extension installs unpacked into Chrome without errors (REQ-install-clean)

Out of Scope

Server upload of captured data — SPEC §9; reserved for Phase 2.
AI-driven diagnostics — SPEC §9; reserved for Phase 2.
Automatic ticket creation — SPEC §9; reserved for Phase 2.
Analytics dashboard — SPEC §9; reserved for Phase 2.
Audio recording — SPEC §9; reserved for Phase 2.
Persisting rolling buffers to chrome.storage / IndexedDB — CON-buffer-storage; buffers are in-memory only in Phase 1.

Context

Source documents: Russian-authored SPEC (Тз расширение фаза1.md) and a Russian-authored README. All user-facing UI strings ("Сохранить отчёт об ошибке", "Последние 30 сек видео + 10 мин лога", "Сохраняю...", "Готово! ✓") are part of the contract and MUST be preserved verbatim. Section identifiers and code use Latin script.
Codebase state: A partially-broken first attempt at the SPEC already exists under src/ (background service worker, content script, popup) and offscreen/. An external audit identified 7 P0 defects that prevent SPEC §10 acceptance. Phase 1 of this roadmap is remediation against the SPEC, not greenfield. See ROADMAP.md.
Operator context (SPEC §1): Operators work inside a browser and periodically make mistakes that are hard to diagnose after the fact. The extension runs silently in the background; the operator only interacts with it when they need to file a report.
Build toolchain (DOC-only): Vite + the crxjs plugin in TypeScript. The SPEC does not prescribe a build tool, so this is auto-overridable by a future ADR/SPEC.

Constraints

Performance: Click-to-archive-on-disk < 5 s (CON-archive-export-latency, SPEC §10 #6) — drives synchronous Blob assembly and avoidance of base64 data URLs.
Memory: Background RAM ceiling 50 MB (CON-ram-ceiling, SPEC §10 #9). Expected steady-state is ~3–10 MB; the ceiling is a hard upper bound, not a target.
Video format: video/webm; codecs=vp9 @ 400 000 bps, MediaRecorder timeslice 2000 ms, single continuous recorder (CON-video-codec). The first chunk (WebM header) MUST be retained indefinitely (CON-webm-header-retention, DEC-009) — without it, the assembled file is not playable.
Buffer windows: Video 30 s rolling, rrweb 10 min / 5 000 events whichever is tighter, user-event log 10 min (CON-video-window, CON-rrweb-window, CON-event-log-window).
Sensitive data: input[type=password] and [data-sensitive="true"] MUST be masked in rrweb (via v2 maskInputFn) AND the event logger MUST drop password field values (CON-sensitive-data-masking).
Service Worker lifecycle: MV3 SW unloads after ~30 s idle; a chrome.alarms alarm fires every 20 s to keep it alive (CON-service-worker-keepalive).
Tab capture binding: chrome.tabCapture is tied to the active tab, requires a user gesture on first invocation, and MUST re-attach on tab activation/update events (CON-tab-capture-binding).
Manifest permissions: tabCapture, activeTab, downloads, scripting, storage; host_permissions: ["<all_urls>"] — exactly this set, no more, no less (CON-manifest-permissions).
Storage strategy: All Phase 1 rolling buffers live in memory only (CON-buffer-storage). chrome.storage is permitted but MUST NOT be used to persist rolling buffers.
Network: No server upload in Phase 1 (CON-no-server-upload). All export is local-only via chrome.downloads.

Key Decisions

Decision	Rationale	Outcome	Status
DEC-001: Chrome Extension Manifest V3	SPEC §2, §7 — required for `chrome.tabCapture`, `chrome.downloads`, `chrome.alarms`.	— Pending	locked (Phase 1)
DEC-002: Service Worker as background coordinator	SPEC §2, §3, §8 — MV3 has no persistent background page; SW coordinates video buffer + archive packaging.	— Pending	locked (Phase 1)
DEC-003: Tab video via `chrome.tabCapture` (vp9 / 400 kbps / 2000 ms)	SPEC §2, §4.1, §7 — only API that captures active-tab video; codec/bitrate/timeslice locked.	— Pending	locked (Phase 1)
DEC-004: DOM capture via rrweb with `maskInputSelector` + 5 000-event cap	SPEC §2, §4.2 — rrweb is the only mature DOM-recording option; masking + cap are part of the privacy/memory contract.	— Pending	locked (Phase 1)
DEC-005: Archive packaging via JSZip	SPEC §2, §3, §6 — only ZIP library bundled per SPEC.	— Pending	locked (Phase 1)
DEC-006: File download via `chrome.downloads`	SPEC §2, §5, §7 — no server upload in Phase 1 (SPEC §9).	— Pending	locked (Phase 1)
DEC-007: In-memory buffers only (no Phase 1 persistence)	SPEC §2, §4.1–§4.3 — rolling buffers in SW (video) and Content Script (rrweb + log).	— Pending	locked (Phase 1)
DEC-008: Screenshot via `chrome.tabs.captureVisibleTab`	SPEC §4.4, §5 — captured at export time, not continuously.	— Pending	locked (Phase 1)
DEC-009: WebM header chunk retained indefinitely	SPEC §4.1, §8 — WebM without its header is not playable.	— Pending	locked (Phase 1)
DEC-010: Service Worker keepalive via `chrome.alarms` (20 s)	SPEC §8 — MV3 SW unloads at ~30 s idle; 20 s alarm cadence keeps it alive.	— Pending	locked (Phase 1)
DEC-011: Manifest permissions set	SPEC §7 — `tabCapture`, `activeTab`, `downloads`, `scripting`, `storage` + `host_permissions: ["<all_urls>"]`.	— Pending	locked (Phase 1)
DEC-012: Vite + crxjs + TypeScript build toolchain	README §"Технический стек" — DOC-level only; SPEC does not prescribe.	— Pending	locked (Phase 1) — auto-overridable by future ADR

Success Metric (Developer-Facing)

Phase 1 is "done" when all 9 SPEC §10 acceptance criteria pass against an unpacked load of the build into Chrome:

Extension installs in Chrome without errors.
Video buffer runs continuously on any tab.
Buffer never holds more than 30 s of footage.
rrweb records DOM events without errors on typical pages (forms, tables, modals).
Event log captures clicks, navigation, and network errors.
Archive downloads to "Downloads" in < 5 s after button press.
Archive opens cleanly; last_30sec.webm plays back in a browser.
Passwords do not appear in the event log or rrweb snapshots.
Extension RAM consumption does not exceed 50 MB in the background.

The verbatim list lives in REQUIREMENTS.md under "Phase 1 Acceptance Criteria (SPEC §10 verbatim)".

Last updated: 2026-05-15 after initial bootstrap from intel synthesis

9.0 KiB Raw Blame History Unescape Escape