mokosh/.planning/intel/decisions.md

Architectural Decisions (synthesized from SPEC)

The SPEC Тз расширение фаза1.md does not formally label itself as ADR-set, but sections 2 ("Стек"), 7 ("Разрешения в manifest.json"), and 8 ("Важные ограничения и решения") encode binding technical choices that act as architectural decisions for Phase 1. Each decision below is reproduced from the SPEC verbatim where possible and tagged with its origin.

Status legend (synthesized, since SPEC has no formal ADR status field):

• Accepted — SPEC §2/§7/§8 prescribed, no contradicting source
• locked: false everywhere — SPEC is locked: false in classification, so these decisions can still be revised by a future ADR; today they are the authoritative baseline.

---

DEC-001: Chrome Extension Manifest V3

• Source: Тз расширение фаза1.md §2 (Стек), §7 (Разрешения)
• Status: Accepted
• Locked: false
• Scope: Extension platform / packaging
• Decision: The extension MUST be implemented as a Chrome Extension targeting Manifest V3 (Service Worker background, no persistent background page).
• Rationale (from SPEC): Required for modern Chrome compatibility; implied by every API used (chrome.tabCapture, chrome.downloads, chrome.tabs, chrome.alarms).
• Confirming source: README.md §"Технический стек" — "Chrome Extension, Manifest V3".

---

DEC-002: Service Worker as Background Coordinator

• Source: Тз расширение фаза1.md §2, §3 (Структура расширения), §8
• Status: Accepted
• Locked: false
• Scope: Background execution model
• Decision: Background logic runs in a Manifest V3 Service Worker (background/service-worker.js) that coordinates the video buffer and archive packaging.
• Constraint binding: Service Worker is unloaded after ~30 s idle; keepalive MUST be maintained via chrome.alarms firing every 20 seconds (SPEC §8).
• Confirming source: README.md §"Технический стек".

---

DEC-003: Tab Video Capture via chrome.tabCapture

• Source: Тз расширение фаза1.md §2, §4.1, §7
• Status: Accepted
• Locked: false
• Scope: Video acquisition
• Decision: Active-tab video is captured via chrome.tabCapture.capture().
• Codec/bitrate binding: video/webm; codecs=vp9 at 400 000 bps.
• MediaRecorder chunk cadence: 2000 ms.
• Activation constraint: tabCapture is tied to the active tab and requires a user gesture on first invocation; on tab switch the capture re-attaches.
• Confirming source: README.md §"Технический стек".

Amendment (Phase 01-stabilize-video-pipeline, 2026-05-15)

• AMENDED-BY: Phase 01 CONTEXT.md D-01..D-05
• Replace chrome.tabCapture.capture() with navigator.mediaDevices.getDisplayMedia() called from the offscreen document.
• Offscreen document is created with chrome.offscreen.Reason.DISPLAY_MEDIA (replaces USER_MEDIA).
• Codec/bitrate/timeslice binding unchanged: video/webm; codecs=vp9 @ 400 000 bps, MediaRecorder timeslice 2000 ms.
• Trade-off accepted: SPEC §1 "silent operation" is given up — Chrome's permanent "Sharing your screen" indicator is shown while recording. Phase 1 accepts this in exchange for broader capture coverage and elimination of tabCapture user-gesture juggling.
• Tab-switch re-attachment clause is REMOVED — getDisplayMedia captures a screen/window, not a tab. There is nothing to re-attach.
• Manifest permission tabCapture is REPLACED with desktopCapture (the latter is harmless: getDisplayMedia is a web standard API and does NOT actually require desktopCapture, but we declare it for clarity per CONTEXT.md D-05).

---

DEC-004: DOM Capture via rrweb

• Source: Тз расширение фаза1.md §2, §4.2
• Status: Accepted
• Locked: false
• Scope: DOM recording
• Decision: DOM events are captured via the rrweb npm library (rrweb.record()), running in the Content Script, with events forwarded to the Service Worker on archive-export request.
• Sensitive-data binding: rrweb is configured with maskInputSelector to mask input[type=password] and [data-sensitive="true"].
• Buffer cap binding: 5 000 rrweb events maximum; oldest dropped on overflow (SPEC §8).
• Confirming source: README.md §"Технический стек", §"Особенности".

---

DEC-005: Archive Packaging via JSZip

• Source: Тз расширение фаза1.md §2, §3, §6
• Status: Accepted
• Locked: false
• Scope: Archive assembly
• Decision: ZIP packaging uses the jszip npm library bundled as libs/jszip.min.js (or the Vite-bundled equivalent).
• Archive layout binding: see REQ-archive-layout in requirements.md.
• Confirming source: README.md §"Технический стек".

---

DEC-006: File Download via chrome.downloads

• Source: Тз расширение фаза1.md §2, §5, §7
• Status: Accepted
• Locked: false
• Scope: File delivery
• Decision: The assembled ZIP is delivered to the user's "Downloads" folder via chrome.downloads.download(). No server upload in Phase 1.
• Confirming source: README.md §"Технический стек".

---

DEC-007: In-Memory Buffers in Service Worker + Content Script

• Source: Тз расширение фаза1.md §2, §4.1, §4.2, §4.3
• Status: Accepted
• Locked: false
• Scope: Storage strategy
• Decision: All recorded data (video chunks, rrweb events, user-event log) is held in memory only — video chunks in the Service Worker, rrweb events and user-event log in the Content Script. No chrome.storage / IndexedDB persistence for the rolling buffers in Phase 1.
• Confirming source: README.md §"Технический стек" — "In-memory (Service Worker + Content Script)".

---

DEC-008: Screenshot via chrome.tabs.captureVisibleTab

• Source: Тз расширение фаза1.md §4.4, §5
• Status: Accepted
• Locked: false
• Scope: Screenshot capture
• Decision: A single PNG screenshot is captured via chrome.tabs.captureVisibleTab() at the moment the user clicks "Save archive". The screenshot is bundled as screenshot.png inside the ZIP.

---

DEC-009: WebM Header Retention

• Source: Тз расширение фаза1.md §4.1, §8
• Status: Accepted
• Locked: false
• Scope: Video container integrity
• Decision: The first chunk emitted by MediaRecorder (which contains the WebM container header) MUST be retained in the ring buffer indefinitely; only subsequent chunks rotate out by the 30-second TTL rule.
• Rationale (from SPEC §8): WebM without its header is not playable.

---

DEC-010: Service Worker Keepalive via chrome.alarms

• Source: Тз расширение фаза1.md §8
• Status: Accepted
• Locked: false
• Scope: Service Worker lifecycle
• Decision: To prevent the 30 s idle unload of MV3 Service Workers, a chrome.alarms alarm fires every 20 seconds to keep the worker alive.

Amendment (Phase 01-stabilize-video-pipeline, 2026-05-15)

• AMENDED-BY: Phase 01 CONTEXT.md D-17..D-18
• Replace chrome.alarms-driven 20 s keepalive with a long-lived chrome.runtime.connect port opened from the offscreen document to the Service Worker. The port emits a PING message every 25 s; both directions of traffic reset the SW's 30 s idle timer per Chrome 110+ semantics (developer.chrome.com/blog/longer-esw-lifetimes).
• The alarms permission is removed from manifest.json (it is no longer used by Phase 1; Phase 2 / 3 may re-add if needed).
• Port lifetime cap (~5 minutes per Chromium-extensions community gist sunnyguan/f94058f66fab89e59e75b1ac1bf1a06e) is mitigated by reconnecting on onDisconnect and pre-emptively at ~290 s.
• See .planning/phases/01-stabilize-video-pipeline/01-RESEARCH.md Pattern 5 for the canonical implementation.

---

DEC-011: Manifest Permissions Set

• Source: Тз расширение фаза1.md §7
• Status: Accepted
• Locked: false
• Scope: Manifest configuration
• Decision: manifest.json requests exactly:
  • permissions: tabCapture, activeTab, downloads, scripting, storage
  • host_permissions: <all_urls>
• Note: tabCapture requires explicit user gesture on first activation.

---

DEC-012: Vite + crxjs + TypeScript Build Toolchain

• Source: README.md §"Технический стек"
• Status: Accepted (DOC-level — not asserted by SPEC)
• Locked: false
• Scope: Build tooling
• Decision: The extension is built with Vite + the crxjs plugin in TypeScript. The SPEC does not prescribe a build tool, so this is a DOC-level decision not contradicted by any higher-precedence source.
• Provenance caveat: If a future ADR/SPEC selects a different toolchain, this DEC is auto-overridden.