diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
new file mode 100644
index 0000000..4b0dfd1
--- /dev/null
+++ b/.github/workflows/deploy.yml
@@ -0,0 +1,56 @@
+name: Deploy to GitHub Pages
+
+on:
+ push:
+ branches:
+ - main
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+concurrency:
+ group: pages
+ cancel-in-progress: false
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup pnpm
+ uses: pnpm/action-setup@v4
+ with:
+ version: 10
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: 20
+ cache: pnpm
+
+ - name: Install dependencies
+ run: pnpm install --frozen-lockfile
+
+ - name: Build
+ run: pnpm build
+
+ - name: Upload Pages artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: dist
+
+ deploy:
+ needs: build
+ runs-on: ubuntu-latest
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..7dbbeb6
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.vite/
+coverage/
+*.local
diff --git a/README.md b/README.md
index 04e41b0..3f4cf64 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,81 @@
-# replay
\ No newline at end of file
+# replay
+
+A single-page web app that loads a JSON recording produced by `jsPsych.getSessionRecording()` (`record_session: true`) and reconstructs a visual replay of the participant's session.
+
+## Overview
+
+The replayer is purely observational — it applies recorded DOM mutations and visualizes recorded input events. It does not re-run plugin code.
+
+**Schema contract:** recordings with `schema_version: 1` are supported. Any other version is rejected.
+
+## Features
+
+- **Load recordings** via file picker or drag-and-drop
+- **Trial sidebar** — list of all trials with plugin name; click to jump
+- **Trial data viewer** — see the recorded `trial_data` JSON for the selected trial
+- **DOM replay** — reconstructs `initial_dom` at each trial's `on_load` state
+- **Event playback** — applies mutations, mouse/touch/keyboard input events in real time
+- **Player controls** — play, pause, restart, prev/next trial
+- **Scrub bar** — seek anywhere within a trial (applies events synchronously up to the target)
+- **Speed control** — 0.25×, 0.5×, 1×, 2×, 4×
+- **Cursor overlay** — tracks `mouse.move` / `touch` positions
+- **Keystroke indicator** — last 3 keys shown on-screen
+- **Focus/blur overlay** — shows when the window was blurred during the session
+- **Viewport resizing** — iframe resizes to match `viewport` / `viewport_changes`
+
+## Getting Started
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open `http://localhost:5173`. The sample recording in `public/examples/sample-recording.json` loads automatically.
+
+## Build
+
+```bash
+pnpm build
+```
+
+Output is in `dist/` — a static SPA that can be served from any web server or opened locally.
+
+## Tests
+
+```bash
+pnpm test
+```
+
+Unit tests (vitest) cover:
+- `validate()` — schema version checking, field validation, JSON string input
+- `instantiateDom()` — element/text/comment node creation, id map registration, security (no `on*` attrs), recursive children
+- `ReplayEngine.applyEventsSync()` — `dom.text`, `dom.attr`, security, empty events
+
+## Architecture
+
+```
+src/
+├── main.ts # bootstrap: file picker, wires sidebar + player
+├── schema/
+│ └── types.ts # schema types + validate()
+├── replay/
+│ ├── dom.ts # instantiateDom(), removeFromMap()
+│ ├── engine.ts # ReplayEngine: scheduling + event dispatch
+│ └── viewport.ts # ViewportManager: iframe sizing
+└── ui/
+ ├── player.ts # Player: play/pause/seek/speed/trial nav
+ ├── sidebar.ts # Sidebar: trial list + trial_data viewer
+ └── overlay.ts # cursor dot + keystroke indicator + focus overlay
+```
+
+The replay stage is an `
+
+
+
+
+
+
+
+
+
+