# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Alta Video Player (WebAVP)** — a web-based surveillance video player for Alta/Ava Security camera exports. Users drag-drop video files or ZIP archives (including AES-256 encrypted ones) and get a multi-camera synchronized playback experience with timeline, digital zoom, and cryptographic integrity verification.

## Running the App

Desktop mode:

```bash
npm install
npm start
```

Web/Python mode:

```bash
python3 app.py
# Serves on http://0.0.0.0:5152
```

The Python server uses only stdlib modules. Electron dependencies are managed through `package.json` and `package-lock.json`.

Checks:

```bash
npm run check
xvfb-run -a npm run smoke
```

## Architecture

### Backend (`app.py`)

Minimal HTTP server with three routes:
- `GET /` — serves `templates/index.html`
- `GET /static/*` — serves static files with path traversal protection
- `GET /api/verify-cert?serial=...&certificateHash=...` — proxies certificate verification to `https://aware.avasecurity.com/api/v1/public/verifyServerCertificate`

### Frontend (`templates/index.html`)

Single self-contained HTML file (~4000 lines) with inline CSS and JavaScript in an IIFE. This is the entire application — there is no framework, no build system, no separate JS modules.

**State model:** Global `channels` Map keyed by channel name. Each channel holds segments (video blobs + time ranges), metadata, DOM references, color, and zoom state. Global timeline state (`globalStart`, `globalEnd`, `currentTime`) synchronizes all cameras.

**Key subsystems:**
- **File ingestion** — drag-drop files/folders, ZIP extraction (JSZip for plain, custom AES-256-CTR for encrypted), metadata pairing by base filename, concurrent import guard (`isImporting` flag)
- **Multi-camera grid** — responsive CSS grid (1–9 cameras), drag-to-reorder, click-to-expand
- **Playback engine** — `requestAnimationFrame` tick loop, per-channel segment visibility management, variable speed (0.25x–8x), frame stepping
- **Timeline** — interactive scrub bar with zoom (mouse wheel), minimap, per-channel segment indicators with color-coded dots
- **Digital zoom** — per-camera scroll-to-zoom (up to 10x) with click-drag panning
- **Magnifier tool** — draw rectangle to zoom into region
- **Slideshow mode** — animated grid showing only currently active feeds with transitions
- **Integrity verification** — offline X.509 certificate parsing, RSASSA-PKCS1-v1_5 and ECDSA signature verification via Web Crypto API, optional cloud verification through `/api/verify-cert`
- **Session persistence** — IndexedDB caching of video blobs and metadata for page refresh survival

**External dependency:** `/static/jszip.min.js` (vendored, for unencrypted ZIP parsing).

Motion analytics were intentionally removed. Keep future work focused on core video player behavior unless the product direction changes.

## Memory Management

Video elements must be properly destroyed to avoid browser memory exhaustion:
- **`destroyVideoEl(videoEl)`** — pauses video, removes `src`, calls `.load()` to force browser to release buffered data. Must be called before removing video elements from DOM.
- **`video.preload = 'metadata'`** — all playback videos use metadata-only preloading to avoid buffering entire files into RAM.
- **`newSession()`** — comprehensive teardown: destroys all video elements, revokes all blob URLs, nulls blob references, releases WebGL contexts, clears all state.
- **`isImporting` guard** — prevents concurrent file imports which could cause race conditions and duplicate segments.
- Slideshow video elements are destroyed on pane transitions and when slideshow is toggled off.

## Key Conventions

- All frontend code lives in `templates/index.html` — CSS at top, then the IIFE script block
- Video elements are created on-demand and hidden (not removed) for performance
- Segment visibility is recalculated every animation frame during playback
- The `batchingSegments` flag defers rendering during bulk file imports
- Keyboard shortcuts are defined inline (Space=play/pause, arrows=seek, S=slideshow, M=magnifier, F=fullscreen, [/]=speed, 0=reset zoom)
- Right-side panel (log) is the only slide-out; opening it does not affect other panels