mokosh/.planning/REQUIREMENTS.md

Requirements: Mokosh

Defined: 2026-05-15 Core Value: When an operator hits a bug, one click produces a self-contained archive that lets support reproduce what happened — in under 5 s, no server, no password leaks.

All requirements below are extracted from the SPEC Тз расширение фаза1.md. The intel files .planning/intel/requirements.md, .planning/intel/constraints.md, and .planning/intel/decisions.md carry the verbatim wording, source citations, and technical bindings; this file is the GSD-shaped projection of those facts.

v1 Requirements

Requirements for the Phase 1 SPEC. Each maps to one phase in ROADMAP.md.

Video

• REQ-video-ring-buffer: The extension maintains an in-memory ring buffer containing the most recent 30 seconds of captured video. AMENDED in Phase 01: video is acquired via navigator.mediaDevices.getDisplayMedia() invoked from the offscreen document (with chrome.offscreen.Reason.DISPLAY_MEDIA), NOT chrome.tabCapture as originally specified. The captured stream is screen-or-window-scoped per the operator's one-time selection in Chrome's native picker, and continues unchanged across tab switches. Encoding is video/webm; codecs=vp9 @ 400 000 bps. Ring-buffer mechanism FURTHER AMENDED in Phase 01 fix-a3 (debug session webm-playback-freeze, resolved 2026-05-15): the original D-09..D-11 single-continuous-MediaRecorder + age-trim approach was retired in favor of D-13 restart-segments — the recorder stop()/start()s every 10 s on the same MediaStream, keeping the last 3 self-contained ~10 s WebM segments (3 × 10 s = 30 s window). Each segment carries its own EBML header + seed VP9 keyframe and is independently decodable, eliminating the orphan-P-frame freeze observed with the trim approach. Bindings: DEC-003 (AMENDED), DEC-009, CON-video-window, CON-video-codec, CON-display-capture-binding (replaces RETIRED CON-tab-capture-binding). CON-webm-header-retention RETIRED in favor of D-13 per-segment header isolation.
  • SPEC §10 acceptance criteria: #2, #3, #7 — all green 2026-05-15 (D-12 ffprobe gate + operator-confirmed Chrome playback + ffmpeg dry-run exit 0 with zero decoder errors against tests/fixtures/last_30sec.webm).

DOM Capture

• REQ-rrweb-dom-buffer: The extension records DOM events via rrweb (rrweb.record()) running in the Content Script over a rolling 10-minute window, capped at 5 000 events (oldest dropped on overflow). Sensitive fields are masked via rrweb v2 maskInputFn covering input[type=password] and [data-sensitive="true"]. Bindings: DEC-004, CON-rrweb-window, CON-sensitive-data-masking.
  • SPEC §10 acceptance criteria: #4.

Event Logging

• REQ-user-event-log: The extension logs user and runtime events over a rolling 10-minute window. Captured types: click (records target selector and element text), input (excludes password fields), navigation (popstate, hashchange, page transitions), js_error (window.onerror, window.onunhandledrejection), network_error (fetch / XMLHttpRequest with response code >= 400). Each entry conforms to the verbatim CON-event-log-schema. Bindings: CON-event-log-window, CON-event-log-schema, CON-sensitive-data-masking.
  • SPEC §10 acceptance criteria: #5, #8.

Export

• REQ-screenshot-on-export: On "Save archive" click, the extension captures a PNG screenshot of the active tab via chrome.tabs.captureVisibleTab() and includes it as screenshot.png in the archive. Binding: DEC-008.

• REQ-popup-ui: The extension exposes a minimal popup with a single button labeled "Сохранить отчёт об ошибке" and a sub-label "Последние 30 сек видео + 10 мин лога". Button state machine: idle → "Сохраняю..." → "Готово! ✓" → idle (3 s revert). On click: (1) capture screenshot, (2) request video buffer + event log from SW, (3) request rrweb snapshots from Content Script, (4) assemble archive, (5) trigger download, (6) display "Готово! ✓". Russian strings are part of the contract and preserved verbatim.

• REQ-archive-layout: The archive is named session_report_YYYY-MM-DD_HH-MM-SS.zip and contains exactly:

  session_report_2025-05-15_14-32-10.zip
  ├── video/
  │   └── last_30sec.webm
  ├── rrweb/
  │   └── session.json
  ├── logs/
  │   └── events.json
  ├── screenshot.png
  └── meta.json
  

  Binding: CON-archive-layout.

  • SPEC §10 acceptance criteria: #7.

• REQ-meta-json-schema: meta.json inside the archive conforms to the verbatim schema:

  {
    "timestamp": "2025-05-15T14:32:10Z",
    "url": "https://...",
    "userAgent": "Chrome/...",
    "extensionVersion": "1.0.0",
    "videoBufferSeconds": 30,
    "logDurationMinutes": 10,
    "totalEvents": 143
  }
  

  All fields required. Binding: CON-meta-json-schema.

Manifest & Install

• REQ-manifest-permissions: manifest.json declares exactly the permission set in DEC-011 (tabCapture, activeTab, downloads, scripting, storage; host_permissions: ["<all_urls>"]) and requests a user gesture for tabCapture on first activation. Binding: DEC-011, CON-manifest-permissions.

  • SPEC §10 acceptance criteria: #1.

• REQ-install-clean: The extension installs in Chrome without errors via the unpacked-extension load flow.

  • SPEC §10 acceptance criteria: #1.

Performance & Security

• REQ-archive-export-latency: From the moment the user clicks the export button, the ZIP archive lands in the "Downloads" folder in under 5 seconds. Binding: CON-archive-export-latency.

  • SPEC §10 acceptance criteria: #6.

• REQ-password-confidentiality: Passwords do not appear in rrweb snapshots OR the user event log. Masking is enforced via rrweb v2 maskInputFn AND explicit value filtering in the event logger for password fields. Binding: CON-sensitive-data-masking.

  • SPEC §10 acceptance criteria: #8.

v2 Requirements

Deferred to a future phase per SPEC §9 ("Что НЕ входит в Фазу 1"). Tracked but not in current roadmap.

Server & Diagnostics

• SRV-01: Upload captured archives to a remote server.
• SRV-02: AI-driven diagnostics of captured sessions.
• SRV-03: Automatic ticket creation from captured reports.
• SRV-04: Analytics dashboard summarising captured sessions.

Capture

• CAP-01: Audio recording in addition to video.

Out of Scope

Explicitly excluded in Phase 1. Documented to prevent scope creep.

Feature	Reason
Server upload	SPEC §9 — Phase 2 work. Phase 1 is local-only via chrome.downloads.
AI diagnostics	SPEC §9 — Phase 2 work.
Automatic ticketing	SPEC §9 — Phase 2 work.
Analytics dashboard	SPEC §9 — Phase 2 work.
Audio recording	SPEC §9 — Phase 2 work.
chrome.storage / IndexedDB persistence of rolling buffers	CON-buffer-storage — buffers are in-memory only in Phase 1.
Recording inactive tabs	CON-tab-capture-binding — chrome.tabCapture is active-tab-bound by design.

Phase 1 Acceptance Criteria (SPEC §10 verbatim)

For traceability, all SPEC §10 acceptance criteria are listed once here, each cross-referenced to its supporting REQ-* entries. The developer-facing success metric for the whole project is "all 9 pass".

1. The extension installs in Chrome without errors. → REQ-install-clean, REQ-manifest-permissions
2. The video buffer runs continuously on any tab. → REQ-video-ring-buffer
3. The buffer always contains no more than 30 seconds of video. → REQ-video-ring-buffer
4. rrweb records DOM events without errors on typical pages (forms, tables, modal windows). → REQ-rrweb-dom-buffer
5. The event log captures clicks, navigation, and network errors. → REQ-user-event-log
6. On button press, the archive is downloaded to "Downloads" in < 5 seconds. → REQ-archive-export-latency
7. The archive opens; last_30sec.webm plays back in a browser. → REQ-archive-layout, REQ-video-ring-buffer
8. Passwords do not appear in the log or rrweb snapshots. → REQ-password-confidentiality
9. Extension RAM consumption does not exceed 50 MB in the background. → CON-ram-ceiling (NFR, not a functional REQ).

Traceability

Which phase covers which requirement. See ROADMAP.md for phase details.

Requirement	Phase	Status
REQ-video-ring-buffer	Phase 1	Complete
REQ-rrweb-dom-buffer	Phase 2	Pending
REQ-user-event-log	Phase 2	Pending
REQ-password-confidentiality	Phase 2	Pending
REQ-popup-ui	Phase 3	Pending
REQ-screenshot-on-export	Phase 3	Pending
REQ-archive-layout	Phase 3	Pending
REQ-meta-json-schema	Phase 3	Pending
REQ-archive-export-latency	Phase 3	Pending
REQ-manifest-permissions	Phase 3	Pending
REQ-install-clean	Phase 4	Pending

Coverage:

• v1 requirements: 11 total
• Mapped to phases: 11
• Unmapped: 0 ✓

Note on CON-ram-ceiling (SPEC §10 #9): tracked as a non-functional constraint verified in Phase 4 (smoke verification) rather than as a standalone functional REQ, per the intel synthesis. Phase 4 success criteria include the RAM-ceiling check.

---

Requirements defined: 2026-05-15 Last updated: 2026-05-15 — REQ-video-ring-buffer marked Complete on Phase 1 closure