# Phase 1: Stabilize Video Pipeline — Pattern Map

**Mapped:** 2026-05-15
**Files analyzed:** 12 (4 NEW, 4 MODIFIED, 4 DELETED)
**Analogs found:** 11 / 12

> NOTE on line numbers cited in CONTEXT.md: The CONTEXT.md narrative
> references some "decimal-style" approximate line ranges that did not
> match the live file when I read it. The numbers used **below** in
> Pattern Assignments are the verified line numbers from the files as
> they exist on disk on 2026-05-15.

## File Classification

| New / Modified / Deleted File | Role | Data Flow | Closest Analog | Match Quality |
|-------------------------------|------|-----------|----------------|---------------|
| `src/offscreen/recorder.ts` (NEW) | offscreen recorder module | streaming + port + event-driven | `offscreen/index.ts` (dead) + inline string at `vite.config.ts:35-213` + ring-buffer structure at `src/background/index.ts:26-75` | role-match (compose 3 analogs) |
| `src/offscreen/index.html` (NEW) | bundle entry HTML | static asset | `offscreen/index.html` (current) + `src/popup/index.html` (script tag) | exact |
| `src/background/index.ts` (MODIFIED, heavy shrink) | service worker coordinator | request-response + port-host + event-driven | itself (current file) — refactor in place | exact |
| `vite.config.ts` (MODIFIED, heavy reduction) | build config | config | crxjs discussion #919 pattern (cited in RESEARCH.md Example B) | role-match |
| `manifest.json` (MODIFIED, permission swap) | manifest | config | itself | exact |
| `src/shared/types.ts` (MODIFIED, light) | shared types | type-only | itself (current file) — add/verify message types | exact |
| `tests/offscreen/ring-buffer.test.ts` (NEW) | unit test | request-response | none in codebase — Vitest default; structural cousin: `src/background/index.ts:47-75` `cleanupVideoBuffer` (subject under test) | role-only |
| `tests/offscreen/codec-check.test.ts` (NEW) | unit test | request-response | none | role-only |
| `tests/offscreen/handshake.test.ts` (NEW) | unit test | event-driven | none | role-only |
| `tests/offscreen/port.test.ts` (NEW) | unit test | port/event-driven | none | role-only |
| `vitest.config.ts` (NEW) | test runner config | config | `vite.config.ts` (defineConfig + plugin shape) + `tsconfig.json` (path/aliases) | role-only |
| `offscreen/index.ts` (DELETED) | — | — | — | — |
| `offscreen/index.html` (DELETED) | — | — | — | — |
| `vite.config.ts:11-217` inline plugin (DELETED) | — | — | — | — |
| `src/background/index.ts:156-165, 128, 457-473, 482-520` (DELETED in-place) | — | — | — | — |

## Pattern Assignments

### `src/offscreen/recorder.ts` (NEW — offscreen recorder; streaming + port + event-driven)

**Analogs (composed):**
- `offscreen/index.ts` (lines 1-60) — the dead-but-correctly-shaped skeleton: module-level `let mediaRecorder`, `chrome.runtime.onMessage.addListener` with a `switch (message.type)`, `MediaRecorder.ondataavailable` push pattern. Phase 1 KEEPS the shape and REWRITES the body.
- Inline JS string at `vite.config.ts:35-213` — the live offscreen at runtime. This is the source-of-truth for the *current behavior* but is the explicit DELETE target. Use it ONLY as a reference for what NOT to copy (the codec fallback chain at lines 151-172, the IndexedDB plumbing at lines 43-107, the `let mediaRecorder` shadow at line 158).
- `src/background/index.ts:25-75` — ring-buffer structural pattern (currently SW-side). MOVE this to offscreen.
- `src/shared/logger.ts:1-25` — `Logger` class shape. Phase 1 adds an `OffscreenLogger` mirroring this (`[OS:...]` prefix) OR reuses `Logger` with prefix `Offscreen:Main`.

**Skeleton pattern (KEEP shape; rewrite body)** — from `offscreen/index.ts:1-60`:
```typescript
// offscreen/index.ts:1-2 — module-level state declaration (KEEP shape; rename
// `mediaRecorder` → `videoRecorder` per RESEARCH.md anti-pattern fix)
let mediaRecorder: MediaRecorder | null = null;
let videoChunks: Blob[] = [];

// offscreen/index.ts:45-59 — message-listener-with-switch shape (KEEP)
chrome.runtime.onMessage.addListener((message) => {
  switch (message.type) {
    case 'START_RECORDING':
      startRecording(message.streamId);
      break;
    case 'STOP_RECORDING':
      stopRecording();
      break;
    case 'GET_CHUNKS':
      chrome.runtime.sendMessage({
        type: 'CHUNKS_RESPONSE',
        chunks: getChunks()
      });
      break;
  }
});
```

**dataavailable pattern (KEEP behavior; chunk Blob is now pushed to ring buffer with timestamp+isHeader, NOT forwarded via `chrome.runtime.sendMessage`)** — from `offscreen/index.ts:18-27`:
```typescript
mediaRecorder.ondataavailable = (event) => {
  if (event.data && event.data.size > 0) {
    videoChunks.push(event.data);
    chrome.runtime.sendMessage({  // ← REMOVE: this is the broken-Blob-over-sendMessage path
      type: 'VIDEO_CHUNK',
      data: event.data,
      timestamp: Date.now()
    });
  }
};
```

**Ring-buffer pattern (MOVE from SW to offscreen, verbatim)** — from `src/background/index.ts:47-75`:
```typescript
function cleanupVideoBuffer() {
  const now = Date.now();
  const beforeCount = videoBuffer.length;

  logger.log(`Cleaning up buffer, current size: ${beforeCount}`);

  // Всегда сохраняем первый чанк (WebM заголовок, помечен как isFirst)
  // Остальные чанки фильтруем по времени (старше 30 секунд удаляем)
  videoBuffer = videoBuffer.filter(chunk => {
    // Всегда оставляем первый чанк (заголовок)
    if (chunk.isFirst) {
      return true;
    }
    // Остальные - только если моложе 30 секунд
    const age = now - chunk.timestamp;
    const keep = age < VIDEO_BUFFER_DURATION_MS;
    if (!keep) {
      logger.log(`Removing chunk, age: ${age}ms, limit: ${VIDEO_BUFFER_DURATION_MS}ms`);
    }
    return keep;
  });

  const removed = beforeCount - videoBuffer.length;
  if (removed > 0) {
    logger.log(`Removed ${removed} old video chunks, buffer: ${videoBuffer.length}`);
  } else {
    logger.log(`No chunks removed, buffer: ${videoBuffer.length}`);
  }
}
```

**Header-pin add pattern (MOVE from SW to offscreen)** — from `src/background/index.ts:26-45`:
```typescript
function addVideoChunkFromBlob(blob: Blob) {
  logger.log(`Processing video chunk from Blob, size: ${blob.size} bytes, type: ${blob.type}`);

  const chunk: VideoChunk = {
    data: blob,
    timestamp: Date.now(),
    isFirst: !firstChunkSaved   // Первый чанк помечаем как isFirst
  };

  if (!firstChunkSaved) {
    firstChunkSaved = true;
    logger.log(`This is the FIRST video chunk (WebM header), size: ${blob.size} bytes`);
  }

  videoBuffer.push(chunk);
  cleanupVideoBuffer();
}
```

**Constants pattern** — from `src/background/index.ts:12-13`:
```typescript
// Константы
const VIDEO_BUFFER_DURATION_MS = 30 * 1000; // 30 секунд
```
Add for the new module:
```typescript
const TIMESLICE_MS = 2000;             // CON-video-codec / SPEC §4.1 (was 200ms)
const VIDEO_MIME = 'video/webm;codecs=vp9';
const VIDEO_BITRATE = 400_000;         // CON-video-codec
const PORT_NAME = 'video-keepalive';
const PORT_PING_MS = 25_000;           // < 30s SW idle threshold
const PORT_RECONNECT_MS = 290_000;     // pre-empt the ~5min port cap
```

**getDisplayMedia call pattern** — from RESEARCH.md Example A (canonical):
```typescript
async function startRecording(): Promise<void> {
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    audio: false,        // SPEC §9 — Phase 2/CAP-01 territory
  });
  // Codec strict-mode — RESEARCH.md Example E
  if (!MediaRecorder.isTypeSupported(VIDEO_MIME)) {
    const err = `vp9 unsupported. UA=${navigator.userAgent}`;
    chrome.runtime.sendMessage({ type: 'RECORDING_ERROR', error: err });
    throw new Error(err);
  }
  videoRecorder = new MediaRecorder(stream, {
    mimeType: VIDEO_MIME,
    videoBitsPerSecond: VIDEO_BITRATE,
  });
  videoRecorder.ondataavailable = onDataAvailable;
  videoRecorder.start(TIMESLICE_MS);
  // RESEARCH.md Example F — track.ended for "Stop sharing" recovery
  stream.getTracks().forEach((track) => {
    track.addEventListener('ended', onUserStoppedSharing, { once: true });
  });
}
```

**OFFSCREEN_READY handshake (Pattern 4)** — from RESEARCH.md (matches `src/shared/types.ts:18` declared but unused message type):
```typescript
// at the bottom of recorder.ts, after the onMessage listener is registered:
chrome.runtime.onMessage.addListener((msg) => { /* ... */ });
chrome.runtime.sendMessage({ type: 'OFFSCREEN_READY' });
```

**Port keepalive pattern (Pattern 5)** — from RESEARCH.md lines 600-628:
```typescript
const port = chrome.runtime.connect({ name: PORT_NAME });
setInterval(() => port.postMessage({ type: 'PING' }), PORT_PING_MS);
port.onMessage.addListener((msg) => {
  if (msg.type === 'REQUEST_BUFFER') {
    port.postMessage({ type: 'BUFFER', chunks: videoBuffer });
  }
});
port.onDisconnect.addListener(() => {
  // Pitfall 4 — 5-minute port cap, reconnect
  reconnectPort();
});
```

**Russian-comment style (KEEP)** — observed throughout `src/background/index.ts:12, 25, 47, 52-54, 156`:
```typescript
// Константы
// Кольцевой буфер видео
// Очистка старых событий
// Keepalive для предотвращения выгрузки Service Worker
```
New code in `src/offscreen/recorder.ts` SHOULD include Russian section headers (matches project provenance from CONTEXT.md "Established patterns").

**Imports pattern (KEEP project shape)** — from `src/background/index.ts:1-8`:
```typescript
import { Logger } from '../shared/logger';
import type {
  Message,
  VideoChunk,
  SessionMetadata,
  VideoBufferResponse
} from '../shared/types';
import JSZip from 'jszip';
```
For the new offscreen recorder:
```typescript
import { Logger } from '../shared/logger';
import type { Message, VideoChunk } from '../shared/types';
```

---

### `src/offscreen/index.html` (NEW — bundle entry HTML, static asset)

**Analog:** `offscreen/index.html` (current) — DELETE and recreate.

**Current pattern** — `offscreen/index.html:1-10`:
```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Offscreen Page</title>
</head>
<body>
  <script src="./index.ts" type="module"></script>
</body>
</html>
```

**Popup-side analog (same shape, references TS via crxjs)** — `src/popup/index.html:1-21`:
```html
<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>AI Call Recorder</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  ...
  <script type="module" src="index.ts"></script>
</body>
</html>
```

**Pattern to copy** — RESEARCH.md Example A (crxjs discussion #919):
```html
<!doctype html>
<html>
<head><meta charset="UTF-8"><title>Mokosh Recorder</title></head>
<body>
  <script type="module" src="./recorder.ts"></script>
</body>
</html>
```

---

### `src/background/index.ts` (MODIFIED — service worker coordinator; shrinks substantially)

**Analog:** itself. Refactor in place.

**DELETE blocks (verified line numbers as of 2026-05-15):**

| Block | Current Lines | Reason |
|-------|---------------|--------|
| `addVideoChunkFromBlob` | 26-45 | MOVE to offscreen (D-16) |
| `cleanupVideoBuffer` | 47-75 | MOVE to offscreen (D-16) |
| `getMediaStreamId` call inside `startVideoCapture` | 126-131 | Replaced by `getDisplayMedia` in offscreen (D-01) |
| `setupKeepalive` function | 156-165 | Replaced by port keepalive (D-18) |
| `VIDEO_CHUNK` case in onMessage | 457-466 | Buffer no longer travels via sendMessage (D-19) |
| `VIDEO_CHUNK_SAVED` case in onMessage | 468-473 | IndexedDB path is dead (D-19) |
| `loadChunkFromIndexedDB` function | 482-505 | IndexedDB path is dead (D-19) |
| `openIndexedDB` function | 507-520 | IndexedDB path is dead (D-19) |
| `setupKeepalive()` call inside `initialize` | 525 | Paired with deletion of `setupKeepalive` |

**Auth/Guard pattern (sender.id validation — RESEARCH.md security recommendation)** — currently MISSING:
The SW's onMessage listener at `src/background/index.ts:427-479` does NOT validate `sender.id`. Phase 1 SHOULD add `if (_sender.id !== chrome.runtime.id) return false;` at the top of the new port and onMessage handlers (low-effort hardening; per RESEARCH.md security domain table). Rename `_sender` → `sender` since it is now used.

**onMessage handler pattern (KEEP shape, modify cases)** — from `src/background/index.ts:427-479`:
```typescript
chrome.runtime.onMessage.addListener((message: Message, _sender, sendResponse) => {
  logger.log('Received message:', message.type, message);

  switch (message.type) {
    case 'REQUEST_PERMISSIONS':
      checkPermissions().then(async (hasPermissions) => {
        if (hasPermissions) {
          if (!isRecording) {
            await startVideoCapture();
          }
          sendResponse({ granted: true });
        } else {
          requestPermissions().then(granted => {
            sendResponse({ granted });
          });
        }
      });
      return true;     // ← async response convention

    case 'GET_VIDEO_BUFFER':
      sendResponse(getVideoBuffer());
      return false;    // ← sync response convention

    case 'SAVE_ARCHIVE':
      saveArchive().then(result => {
        sendResponse(result);
      });
      return true;

    default:
      logger.warn('Unknown message type:', message.type);
      return false;
  }
});
```
Phase 1 modifications:
- `REQUEST_PERMISSIONS`: replace `startVideoCapture` body with new `ensureOffscreenAndStart()` (offscreen + DISPLAY_MEDIA reason).
- `GET_VIDEO_BUFFER`: replace `getVideoBuffer()` with an over-port request to offscreen (return `true`, resolve via port message handler).
- `SAVE_ARCHIVE`: same — `getVideoBuffer()` inside `saveArchive()` (line 332) becomes a port-request to offscreen.
- Add a new `case 'OFFSCREEN_READY'` to resolve the handshake Promise (Pattern 4).

**ensureOffscreen pattern (REPLACE reason)** — from `src/background/index.ts:78-104`:
```typescript
async function ensureOffscreen() {
  if (offscreenCreated) {
    logger.log('Offscreen already created');
    return;
  }

  try {
    const url = chrome.runtime.getURL('offscreen/index.html');      // ← path may change to 'src/offscreen/index.html'; verify after first build
    logger.log('Creating offscreen document at:', url);

    await chrome.offscreen.createDocument({
      url: url,
      reasons: ['USER_MEDIA'] as any,         // ← REPLACE: ['DISPLAY_MEDIA']; drop the `as any` once @types/chrome is bumped
      justification: 'Need to record video from tab for error reporting'  // ← OPTIONAL: update copy to match RESEARCH.md Example C
    });
    offscreenCreated = true;
    logger.log('Offscreen document created successfully');
  } catch (error) {
    if ((error as any).message?.includes('already exists')) {
      offscreenCreated = true;
      logger.log('Offscreen document already exists');
    } else {
      logger.error('Failed to create offscreen document:', error);
      throw error;
    }
  }
}
```
Anti-pattern note: the `as any` on line 90 maps to audit P1 #13 and the CLAUDE.md "no @ts-ignore / no as any" rule. The fix is `chrome.offscreen.Reason.DISPLAY_MEDIA` after bumping `@types/chrome` from `^0.0.268` to `^0.1.42` (RESEARCH.md Standard Stack). The bump is OPTIONAL in this phase but recommended.

**ADD: onConnect handler for video-keepalive port (NEW)** — RESEARCH.md Pattern 5, lines 609-617:
```typescript
let videoPort: chrome.runtime.Port | null = null;
chrome.runtime.onConnect.addListener((p) => {
  if (p.name !== 'video-keepalive') return;
  videoPort = p;
  p.onMessage.addListener((msg) => {
    if (msg.type === 'BUFFER') { /* resolve pending export */ }
  });
  p.onDisconnect.addListener(() => { videoPort = null; });
});
```

**ADD: one-shot deletion of orphaned IndexedDB on install** — RESEARCH.md Runtime State Inventory:
The `chrome.runtime.onInstalled.addListener` at `src/background/index.ts:530-533` is the natural site to call `indexedDB.deleteDatabase('VideoRecorderDB')` to clean up old browser profiles. Add inside that listener.

**`saveArchive` pattern (MODIFY to fetch buffer via port)** — `src/background/index.ts:314-387`:
```typescript
async function saveArchive() {
  // ... unchanged up to line 332 ...
  const videoBuffer = getVideoBuffer();    // ← REPLACE: await getVideoBufferFromOffscreen()
  // ... unchanged thereafter ...
}
```

---

### `vite.config.ts` (MODIFIED — heavy reduction)

**Analog:** crxjs discussion #919 working pattern (cited in RESEARCH.md Example B).

**DELETE the entire inline plugin block** — `vite.config.ts:13-216` (the object literal starting `{ name: 'copy-offscreen', generateBundle() { ... } }`).

**Final shape (REPLACE existing file body)** — RESEARCH.md Example B:
```typescript
import { defineConfig } from 'vite';
import { crx } from '@crxjs/vite-plugin';
import manifest from './manifest.json';

export default defineConfig({
  plugins: [
    crx({ manifest, contentScripts: { injectCss: false } }),
  ],
  build: {
    rollupOptions: {
      input: {
        offscreen: 'src/offscreen/index.html',
      },
    },
  },
});
```

**Current `crx` invocation pattern (KEEP)** — `vite.config.ts:5-12`:
```typescript
crx({
  manifest,
  contentScripts: {
    injectCss: false,
  },
}),
```
This invocation form is correct and is retained verbatim; only the second plugin entry (the inline `copy-offscreen`) is deleted, and `rollupOptions.input` for the offscreen HTML entry is added per RESEARCH.md Pitfall 5.

**Pitfall 5 note (per RESEARCH.md):** Inspect `dist/` after the first `npm run build` to verify the emitted path matches what `src/background/index.ts:85` passes to `createDocument`. If crxjs strips the `src/` prefix, change the SW's `chrome.runtime.getURL` arg accordingly.

---

### `manifest.json` (MODIFIED — permission swap)

**Analog:** itself.

**Current permissions block** — `manifest.json:6-14`:
```json
"permissions": [
  "tabCapture",
  "activeTab",
  "downloads",
  "scripting",
  "storage",
  "alarms",
  "offscreen"
],
```

**Patch per D-A6:**
- Replace `"tabCapture"` with `"desktopCapture"`.
- KEEP `"activeTab"` (screenshot path: `chrome.tabs.captureVisibleTab`, see `src/background/index.ts:190`).
- Drop `"alarms"` (no longer used after `setupKeepalive` deletion). [OPTIONAL but consistent with D-18.]
- KEEP `"downloads"` (used at `src/background/index.ts:305`).
- KEEP `"storage"` (used by rrweb? — not used in current code; can drop, but out of scope for this phase).
- KEEP `"scripting"` (content script).
- KEEP `"offscreen"` (required to call `chrome.offscreen.createDocument`).

Final shape:
```json
"permissions": [
  "desktopCapture",
  "activeTab",
  "downloads",
  "scripting",
  "storage",
  "offscreen"
],
```

---

### `src/shared/types.ts` (MODIFIED — light; verify message types)

**Analog:** itself.

**Status check** — `src/shared/types.ts:3-18`:
```typescript
export type MessageType =
  | 'REQUEST_PERMISSIONS'
  | 'PERMISSIONS_GRANTED'
  | 'PERMISSIONS_DENIED'
  | 'GET_VIDEO_BUFFER'
  | 'VIDEO_BUFFER_RESPONSE'
  | 'GET_RRWEB_EVENTS'
  | 'RRWEB_EVENTS_RESPONSE'
  | 'SAVE_ARCHIVE'
  | 'ARCHIVE_SAVED'
  | 'START_RECORDING'
  | 'STOP_RECORDING'
  | 'RECORDING_ERROR'
  | 'VIDEO_CHUNK'
  | 'VIDEO_CHUNK_SAVED'
  | 'OFFSCREEN_READY';
```
- `OFFSCREEN_READY` is present (line 18). ✓
- `RECORDING_ERROR` is present (line 15). ✓
- `VIDEO_CHUNK` and `VIDEO_CHUNK_SAVED` should be **REMOVED** (lines 16-17) since their handlers are deleted in Phase 1.

**Phase 1 additions:**
- Add port-message string types if planner chooses to type the port traffic:
  ```typescript
  // Port message types (offscreen ↔ SW over 'video-keepalive' port)
  export type PortMessageType =
    | 'PING'
    | 'REQUEST_BUFFER'
    | 'BUFFER';
  export interface PortMessage<T = unknown> {
    type: PortMessageType;
    chunks?: VideoChunk[];
    payload?: T;
  }
  ```

**`VideoChunk` interface (KEEP as-is)** — `src/shared/types.ts:27-31`:
```typescript
export interface VideoChunk {
  data: Blob;
  timestamp: number;
  isFirst?: boolean;
}
```
This shape is exactly what the offscreen ring buffer needs. Reuse unchanged.

---

### `tests/offscreen/ring-buffer.test.ts` (NEW — unit test)

**Analog:** none in codebase (no tests directory exists yet).

**Subject under test** — the relocated `addVideoChunkFromBlob` + `cleanupVideoBuffer` from `src/background/index.ts:26-75`. Tests assert:
1. First chunk is pinned with `isFirst: true`.
2. Subsequent chunks have `isFirst: false`.
3. After 30+ seconds, non-header chunks are evicted but the header survives.
4. Buffer length stays ≤ N for N chunks added within 30 s.

**Skeleton (standard Vitest)** — pattern inferred from RESEARCH.md Validation Architecture:
```typescript
import { describe, it, expect, beforeEach } from 'vitest';
import { addChunk, trimAged, getBuffer, resetBuffer } from '../../src/offscreen/recorder';
// NB: planner must export these pure functions from recorder.ts to make them testable.

describe('ring buffer', () => {
  beforeEach(() => resetBuffer());

  it('first chunk is header', () => {
    addChunk({ size: 1024 } as Blob, 1_000);
    expect(getBuffer()[0].isFirst).toBe(true);
  });

  it('trim 30s — keeps header, evicts aged tail', () => {
    addChunk({ size: 1024 } as Blob, 0);          // header at t=0
    addChunk({ size: 512 } as Blob, 10_000);      // t=10s
    addChunk({ size: 512 } as Blob, 35_000);      // t=35s — header now 35s old, tail 25s
    trimAged(/* now= */ 40_000);                  // header age 40s; first chunk 30s; last chunk 5s
    const buf = getBuffer();
    expect(buf[0].isFirst).toBe(true);            // header survives unconditionally
    expect(buf.length).toBeGreaterThanOrEqual(2); // header + at least the t=35s chunk
  });
});
```

---

### `tests/offscreen/codec-check.test.ts` (NEW — unit test)

**Analog:** none. Subject under test = the codec strict-mode error path (RESEARCH.md Pattern 6 / Example E).

**Skeleton:**
```typescript
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';

describe('codec strict mode', () => {
  let originalIsTypeSupported: typeof MediaRecorder.isTypeSupported;
  beforeEach(() => {
    originalIsTypeSupported = (globalThis as any).MediaRecorder?.isTypeSupported;
    (globalThis as any).MediaRecorder = {
      isTypeSupported: vi.fn().mockReturnValue(false),
    };
    (globalThis as any).chrome = { runtime: { sendMessage: vi.fn() } };
  });
  afterEach(() => {
    if (originalIsTypeSupported) {
      (globalThis as any).MediaRecorder = { isTypeSupported: originalIsTypeSupported };
    }
  });

  it('throws on unsupported vp9 and emits RECORDING_ERROR', async () => {
    const { assertCodecSupported } = await import('../../src/offscreen/recorder');
    expect(() => assertCodecSupported()).toThrow(/vp9 unsupported/);
    expect((globalThis as any).chrome.runtime.sendMessage).toHaveBeenCalledWith(
      expect.objectContaining({ type: 'RECORDING_ERROR' })
    );
  });
});
```

---

### `tests/offscreen/handshake.test.ts` (NEW — unit test)

**Analog:** none. Subject under test = `OFFSCREEN_READY` Promise resolution (RESEARCH.md Pattern 4).

**Skeleton:**
```typescript
import { describe, it, expect, vi } from 'vitest';

describe('OFFSCREEN_READY handshake', () => {
  it('sends OFFSCREEN_READY after listener registration', async () => {
    const calls: any[] = [];
    (globalThis as any).chrome = {
      runtime: {
        sendMessage: (m: unknown) => { calls.push(m); },
        onMessage: { addListener: vi.fn() },
        connect: () => ({
          name: 'video-keepalive',
          postMessage: vi.fn(),
          onMessage: { addListener: vi.fn() },
          onDisconnect: { addListener: vi.fn() },
          disconnect: vi.fn(),
        }),
      },
    };
    await import('../../src/offscreen/recorder');
    expect(calls).toEqual(expect.arrayContaining([
      expect.objectContaining({ type: 'OFFSCREEN_READY' }),
    ]));
  });
});
```

---

### `tests/offscreen/port.test.ts` (NEW — unit test)

**Analog:** none. Subject under test = port reconnect on disconnect (RESEARCH.md Pitfall 4).

**Skeleton:**
```typescript
import { describe, it, expect, vi } from 'vitest';

describe('port reconnect', () => {
  it('reconnects when port disconnects', () => {
    const disconnectListeners: Array<() => void> = [];
    let connectCount = 0;
    (globalThis as any).chrome = {
      runtime: {
        sendMessage: vi.fn(),
        onMessage: { addListener: vi.fn() },
        connect: () => {
          connectCount++;
          return {
            name: 'video-keepalive',
            postMessage: vi.fn(),
            onMessage: { addListener: vi.fn() },
            onDisconnect: {
              addListener: (fn: () => void) => disconnectListeners.push(fn),
            },
            disconnect: vi.fn(),
          };
        },
      },
    };
    // After import, the module connects exactly once
    return import('../../src/offscreen/recorder').then(() => {
      expect(connectCount).toBe(1);
      // Fire the disconnect — module should reconnect
      disconnectListeners.forEach((fn) => fn());
      expect(connectCount).toBeGreaterThanOrEqual(2);
    });
  });
});
```

---

### `vitest.config.ts` (NEW — test runner config)

**Analogs:** `vite.config.ts` (defineConfig shape) + `tsconfig.json` (compiler-options alignment).

**Pattern to copy** — RESEARCH.md Wave 0 Gaps + Vitest standard:
```typescript
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'node',     // node-only; Blob is shimmed by Vitest 3+ via undici
    include: ['tests/**/*.test.ts'],
    reporters: 'dot',
    typecheck: {
      enabled: false,        // tsc --noEmit runs separately in `npm run build`
    },
  },
});
```

**`package.json` script ADD** — companion to vitest.config.ts:
```json
"scripts": {
  "dev": "vite",
  "build": "tsc && vite build",
  "preview": "vite preview",
  "test": "vitest run"          // ← ADD
}
```

---

## Shared Patterns

### Logging
**Source:** `src/shared/logger.ts:1-25` (Logger class) and `src/shared/logger.ts:28-51` (ContentLogger class).

**Apply to:** All new and modified source files.

```typescript
// src/shared/logger.ts:1-25
export class Logger {
  private context: string;

  constructor(context: string) {
    this.context = context;
  }

  private logWithLevel(level: 'log' | 'warn' | 'error', ...args: any[]) {
    const timestamp = new Date().toISOString();
    console[level](`[SW:${this.context}] ${timestamp}`, ...args);
  }

  log(...args: any[]) { this.logWithLevel('log', ...args); }
  warn(...args: any[]) { this.logWithLevel('warn', ...args); }
  error(...args: any[]) { this.logWithLevel('error', ...args); }
}
```

**For the new offscreen file:** Either (a) reuse `Logger` with constructor argument `'Offscreen:Main'`, producing `[SW:Offscreen:Main]` (slightly misleading since the runtime is the offscreen, not the SW), or (b) ADD an `OffscreenLogger` class mirroring `ContentLogger` with prefix `[OS:${context}]`. Planner picks; CONTEXT.md "Reusable assets" section permits either.

Recommendation: add `OffscreenLogger` for consistency with the existing `Logger` / `ContentLogger` split. ~25 lines, matches the shape exactly:
```typescript
// New OffscreenLogger class to add to src/shared/logger.ts
export class OffscreenLogger {
  private context: string;
  constructor(context: string) { this.context = context; }
  private logWithLevel(level: 'log' | 'warn' | 'error', ...args: any[]) {
    const timestamp = new Date().toISOString();
    console[level](`[OS:${this.context}] ${timestamp}`, ...args);
  }
  log(...args: any[]) { this.logWithLevel('log', ...args); }
  warn(...args: any[]) { this.logWithLevel('warn', ...args); }
  error(...args: any[]) { this.logWithLevel('error', ...args); }
}
```

### Message handling (sender validation)
**Source:** RESEARCH.md Security Domain table (currently MISSING in codebase).
**Apply to:** New `chrome.runtime.onMessage` and `chrome.runtime.onConnect` handlers in both `src/background/index.ts` and `src/offscreen/recorder.ts`.

Current code does NOT validate `sender.id`. Phase 1 SHOULD add:
```typescript
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (sender.id !== chrome.runtime.id) return false;
  // ... existing dispatch ...
});

chrome.runtime.onConnect.addListener((port) => {
  if (port.sender?.id !== chrome.runtime.id) {
    port.disconnect();
    return;
  }
  // ... existing handling ...
});
```

### Async response convention
**Source:** `src/background/index.ts:427-479`.
**Apply to:** All `onMessage` handlers that perform `await`/`then` before `sendResponse`.

The convention in the existing code is consistent and correct:
- `return true;` — when the handler will call `sendResponse` asynchronously (after a Promise resolves).
- `return false;` — when the handler returns synchronously or does not respond.

Preserve this convention verbatim in the modified background and the new offscreen recorder.

### Russian inline comments
**Source:** `src/background/index.ts:12, 25, 47, 156` and `src/content/index.ts:14-18, 20-23, 27`.
**Apply to:** New `src/offscreen/recorder.ts`.

Project convention: Russian comments are kept as section markers / explanations for business logic.
Example:
```typescript
// Константы
const TIMESLICE_MS = 2000;
// Кольцевой буфер видео
let videoBuffer: VideoChunk[] = [];
// Keepalive порт (заменяет chrome.alarms)
let keepalivePort: chrome.runtime.Port | null = null;
```
TypeScript identifiers stay English (per CLAUDE.md naming rules); only comments are Russian.

### Module-level state pattern
**Source:** `src/background/index.ts:15-22` and `src/content/index.ts:20-24`.
**Apply to:** New `src/offscreen/recorder.ts`.

Single-instance modules use top-level `let` state declarations (not classes / singletons):
```typescript
// src/background/index.ts:15-22
let videoBuffer: VideoChunk[] = [];
let firstChunkSaved = false;
let isRecording = false;
let offscreenCreated = false;
let lastScreenshotTime = 0;
let cachedScreenshot: Blob | null = null;
```
For `src/offscreen/recorder.ts`, mirror this shape:
```typescript
let videoRecorder: MediaRecorder | null = null;   // RENAMED from 'mediaRecorder' to break the audit P0 #1 shadow
let videoBuffer: VideoChunk[] = [];
let firstChunkSaved = false;
let mediaStream: MediaStream | null = null;
let keepalivePort: chrome.runtime.Port | null = null;
let pingIntervalId: number | null = null;
```

## No Analog Found

| File | Role | Data Flow | Reason |
|------|------|-----------|--------|
| `tests/offscreen/*.test.ts` (4 files) | unit test | request-response | No test directory exists in the project yet. Pattern comes from Vitest defaults + RESEARCH.md Validation Architecture. |

`vitest.config.ts` has a partial analog in `vite.config.ts` (defineConfig shape) and is listed under Pattern Assignments rather than here.

## Metadata

**Analog search scope:**
- `/home/parf/projects/work/repremium/src/` (all subdirectories)
- `/home/parf/projects/work/repremium/offscreen/`
- `/home/parf/projects/work/repremium/vite.config.ts`
- `/home/parf/projects/work/repremium/manifest.json`
- `/home/parf/projects/work/repremium/tsconfig.json`
- `/home/parf/projects/work/repremium/package.json`

**Files scanned:** 10 source files; 4 config files.

**Verified line numbers** (read on 2026-05-15):
- `src/background/index.ts` — 536 lines total. Verified delete-target ranges: 26-45 (addVideoChunkFromBlob), 47-75 (cleanupVideoBuffer), 126-131 (getMediaStreamId), 156-165 (setupKeepalive), 457-473 (VIDEO_CHUNK + VIDEO_CHUNK_SAVED cases), 482-520 (loadChunkFromIndexedDB + openIndexedDB).
- `vite.config.ts` — 227 lines total. Verified inline plugin range: 13-216 (the `copy-offscreen` object starts at line 13 with `name:` on line 14 inside a plugins array; the embedded JS string template ends at line 213; the trailing build/rollupOptions block at 218-226 also collapses per RESEARCH.md Example B).
- `offscreen/index.ts` — 60 lines, intact. DELETE target.
- `offscreen/index.html` — 10 lines, intact. DELETE target.
- `manifest.json:7` — `"tabCapture"` token to replace.
- `src/shared/types.ts:18` — `'OFFSCREEN_READY'` declared, ready to wire up.

**Pattern extraction date:** 2026-05-15