sessionsnap 0.0.3 → 0.0.4

package/README.md

@@ -10,13 +10,14 @@ Designed for test automation, internal tooling, and any workflow that requires p
 
 - **Human-in-the-loop** — You log in manually (CAPTCHA / 2FA friendly)
 - **Persistent profiles** — Sessions saved to disk and reusable across runs
-- **Auto-detect login completion** — URL and cookie heuristics
+- **Auto-detect login completion** — URL and cookie heuristics, optional regex target
 - **Session auto-update** — Session snapshot is refreshed when the browser closes
-- **Automatic screenshots** — Captures a PNG after login and on session open
-- **Action recording** — Inject a recorder to capture clicks, inputs, navigations
-- **Action replay** — Replay recorded actions with configurable speed
+- **Automatic screenshots** — Captures a PNG after login, on session open, and on record
+- **Interactive recording** — On-page overlay UI with start/stop controls and named recordings
+- **Named recordings** — Save recordings with names, replay by name
+- **Action replay** — Replay recorded actions with configurable speed and visual cursor
 - **Desktop viewport** — 1440×900 default for realistic rendering
-- **Dual runner support** — Puppeteer (bundled) and Playwright (optional)
+- **Dual runner support** — Puppeteer (via puppeteer-core) and Playwright (optional)
 - **Works for any website** — SaaS dashboards, admin panels, internal tools
 
 ## Install
@@ -25,15 +26,15 @@ Designed for test automation, internal tooling, and any workflow that requires p
 npm install
 ```
 
-Puppeteer is included as a direct dependency. For Playwright support, install it separately:
+`puppeteer-core` is included as a direct dependency and uses your system's Chrome/Chromium. For Playwright support, install it separately:
 
 ```bash
 npm install playwright
 ```
 
-## CLI Usage
+## CLI Commands
 
-### Capture a session
+### `capture` — Capture a session
 
 Launch a headed browser, log in manually, and save the session:
 
@@ -43,10 +44,11 @@ sessionsnap capture <url> \
   [--runner puppeteer|playwright] \
   [--out <file>] \
   [--wait <minutes>] \
-  [--record]
+  [--target <regex>]
 ```
 
-`--runner` defaults to `puppeteer` since it is bundled as a direct dependency.
+- `--runner` defaults to `puppeteer`
+- `--target` allows specifying a regex pattern for the post-login URL (e.g. `"/dashboard"` or `"^https://.*/app"`)
 
 **Example:**
 
@@ -62,13 +64,18 @@ The tool will:
 5. Take a screenshot of the post-login state
 6. Capture cookies and save a session snapshot
 
-### Open a URL with a saved session
+With a specific target URL pattern:
+
+```bash
+sessionsnap capture https://app.acmecorp.io/login --profile acme --target "/dashboard"
+```
+
+### `open` — Open a URL with a saved session
 
 ```bash
 sessionsnap open <url> \
   --profile <name> \
-  [--runner puppeteer|playwright] \
-  [--record]
+  [--runner puppeteer|playwright]
 ```
 
 **Example:**
@@ -79,183 +86,121 @@ sessionsnap open https://app.acmecorp.io/dashboard --profile acme
 
 When you close the browser, the session snapshot is automatically updated with the latest cookies.
 
-### List all profiles
-
-```bash
-sessionsnap list [--json]
-```
-
-Shows all saved profiles with a summary: runner, URL, relative date, screenshot/recording counts.
-
-**Example output:**
-
-```
-[sessionsnap] 2 profile(s) found:
-
-  acme     [puppeteer]  https://app.acmecorp.io/dashboard  (2h ago)  📸 3  🔴 2
-  staging  [playwright]  https://staging.acmecorp.io/home   (1d ago)  📸 1
-```
-
-Use `--json` for machine-readable output (useful for scripting).
+### `record` — Record user actions
 
-### Show profile status
+Open a browser with a saved session and record user actions via an on-page overlay UI:
 
 ```bash
-sessionsnap status --profile <name>
-```
-
-Prints profile details including directory path, session metadata, cookie/origin counts, and a list of saved screenshots and recordings.
-
-**Example output:**
-
-```
-Profile:      acme
-Directory:    /Users/you/.sessionsnap/profiles/acme
-Runner:       puppeteer
-Captured at:  2026-02-09T12:00:00.000Z
-Updated at:   2026-02-09T12:05:00.000Z
-Start URL:    https://app.acmecorp.io/login
-Final URL:    https://app.acmecorp.io/dashboard
-Cookies:      12
-Origins:      0
-Screenshots:
-  - capture-2026-02-09T12-00-00-000Z.png
-  - open-2026-02-09T12-05-00-000Z.png
-Recordings:
-  - actions-capture-2026-02-09T12-00-00-000Z.json
+sessionsnap record <url> \
+  --profile <name> \
+  [--runner puppeteer|playwright] \
+  [--name <recording-name>]
 ```
 
-## Snapshot Format
-
-```json
-{
-  "meta": {
-    "runner": "puppeteer",
-    "profile": "acme",
-    "capturedAt": "2026-02-09T12:00:00.000Z",
-    "startUrl": "https://app.acmecorp.io/login",
-    "finalUrl": "https://app.acmecorp.io/dashboard"
-  },
-  "cookies": [
-    {
-      "name": "session_token",
-      "value": "abc123",
-      "domain": ".acmecorp.io",
-      "path": "/",
-      "expires": 1700000000,
-      "httpOnly": true,
-      "secure": true,
-      "sameSite": "Lax"
-    }
-  ],
-  "origins": []
-}
-```
+**Interactive mode** (no `--name`):
+1. Browser opens with an overlay showing a **"Start Recording"** button
+2. Click Start → overlay switches to recording mode (timer + action counter + Stop button)
+3. Perform your actions on the page
+4. Click Stop → a dialog prompts you for a recording name
+5. Enter a name and click Save → recording saved to disk
 
-After using `open`, an `updatedAt` field is added to `meta`.
+**Pre-named mode** (`--name` provided):
+1. Recording starts automatically with the given name
+2. Click Stop when done → recording saved immediately
 
-## Screenshots
+**Examples:**
 
-Screenshots are automatically saved to the profile directory on every `capture` and `open` command:
+```bash
+# Interactive: name the recording when you stop
+sessionsnap record https://app.acmecorp.io/dashboard --profile acme
 
+# Pre-named: recording starts immediately as "checkout-flow"
+sessionsnap record https://app.acmecorp.io/dashboard --profile acme --name "checkout-flow"
 ```
-~/.sessionsnap/profiles/acme/
-  snapshot.json
-  capture-2026-02-09T12-00-00-000Z.png
-  open-2026-02-09T12-05-00-000Z.png
-```
-
-- **capture** — taken right after login is detected
-- **open** — taken after the page loads with the saved session
-
-## Action Recording
 
-Use `--record` on `capture` or `open` to inject a lightweight recorder into the page. It captures 11 action types:
+The recorder captures 12 action types:
 
 | Action | What it records | Replay |
 |--------|----------------|--------|
 | **click** | selector, tag, text, coordinates | CSS selector → text → coordinates fallback |
 | **dblclick** | selector, tag, text, coordinates | Same 3-tier fallback as click |
-| **hover** | selector, tag, text | `page.hover(selector)` with text fallback |
+| **hover** | selector, tag, text, coordinates | CSS selector → text → coordinates fallback |
+| **mousemove** | x, y coordinates | `page.mouse.move(x, y)` |
 | **input** | selector, value (passwords masked) | Clear + type / fill |
 | **select** | selector, selected value & text | `page.select` / `selectOption` |
-| **checkbox** | selector, checked state, type (checkbox/radio) | Smart toggle (checks current state) |
-| **keydown** | key, combo (Ctrl/Meta/Alt+key), selector | `page.keyboard.press` with modifiers |
+| **checkbox** | selector, checked state, type | Smart toggle (checks current state) |
+| **keydown** | key, combo (Ctrl/Meta/Alt+key) | `page.keyboard.press` with modifiers |
 | **submit** | form selector, action, method | `form.requestSubmit()` / Enter fallback |
-| **scroll** | scrollX, scrollY, scrollHeight, viewportHeight | `window.scrollTo(x, y)` |
-| **file** | selector, file names, file count | Log only (cannot replay file selection) |
+| **scroll** | scroll position (window + inner elements) | `window.scrollTo` / `element.scrollTo` |
+| **file** | selector, file names, count | Log only (cannot replay file selection) |
 | **navigation** | from/to URLs (SPA & traditional) | `page.goto(url)` |
 
-Noise reduction: hover is debounced (200ms, interactive elements only), scroll is debounced (400ms), keydown only captures special keys (Enter/Escape/Tab/arrows/F-keys) and modifier combos (Ctrl+key, Meta+key).
+Noise reduction: hover debounced (150ms, interactive elements only), scroll debounced (400ms), mousemove throttled (~60fps), keydown only captures special keys and modifier combos.
 
-Recorded actions are saved as timestamped JSON files in the profile directory:
+Named recordings are tracked in `recordings.json` inside the profile directory:
 
 ```
 ~/.sessionsnap/profiles/acme/
-  actions-capture-2026-02-09T12-00-00-000Z.json
-  actions-open-2026-02-09T12-05-00-000Z.json
-```
-
-**Example:**
-
-```bash
-sessionsnap capture https://app.acmecorp.io/login --profile acme --record
+  recordings.json              # metadata: name → file mapping
+  actions-checkout-flow.json   # named recording
+  actions-recording-2026-...json  # unnamed recording
 ```
 
-### Replaying actions
-
-Replay a previously recorded session:
+### `replay` — Replay recorded actions
 
 ```bash
 sessionsnap replay \
   --profile <name> \
-  [--runner puppeteer|playwright] \
+  [--name <recording-name>] \
   [--file <actions-file>] \
+  [--runner puppeteer|playwright] \
   [--speed <multiplier>] \
   [--headless] \
-  [--bail]
+  [--bail] \
+  [--visual]
 ```
 
 **Examples:**
 
 ```bash
-# Replay the latest recording at normal speed
+# Replay a named recording
+sessionsnap replay --profile acme --name "checkout-flow"
+
+# Replay the latest recording
 sessionsnap replay --profile acme
 
-# Replay at 2x speed
-sessionsnap replay --profile acme --speed 2
+# Replay at 2x speed with visual cursor
+sessionsnap replay --profile acme --name "checkout-flow" --speed 2 --visual
 
-# Replay a specific recording file
-sessionsnap replay --profile acme --file actions-capture-2026-02-09T12-00-00-000Z.json
+# Replay a specific file
+sessionsnap replay --profile acme --file actions-recording-2026-02-09T12-00-00-000Z.json
 
-# Replay in headless mode (no visible browser)
-sessionsnap replay --profile acme --headless
+# Replay in headless mode
+sessionsnap replay --profile acme --name "checkout-flow" --headless
 
 # Fail fast — stop on first failure (exit code 1)
-sessionsnap replay --profile acme --bail
+sessionsnap replay --profile acme --name "checkout-flow" --bail
 ```
 
 The replayer:
 1. Launches a browser with the saved session profile
 2. Navigates to the starting URL from the recording
-3. Executes each action in order (click, dblclick, hover, type, select, checkbox, keydown, submit, scroll, navigate)
+3. Executes each action in order
 4. Uses real timing from the recording (clamped to 50ms–5s per action)
 5. Takes a screenshot after replay completes
 6. Password fields are skipped during replay for security
 
 #### Error handling
 
-By default, replay is **fault-tolerant**. If an individual action fails (element not found, timeout, etc.), it is logged as `FAILED` and the replay **continues with the next action** — the whole flow does not crash.
+By default, replay is **fault-tolerant**. If an individual action fails (element not found, timeout, etc.), it is logged as `FAILED` and the replay **continues with the next action**.
 
-Use `--bail` for **fail-fast** mode: the replay stops immediately on the first failure and exits with code `1`. This is useful in CI/CD pipelines or when you need strict action accuracy.
+Use `--bail` for **fail-fast** mode: the replay stops immediately on the first failure and exits with code `1`. Useful in CI/CD pipelines.
 
 For click actions, there is a 3-step fallback strategy:
 1. **CSS selector** — tries the recorded selector (2s timeout)
 2. **Text content** — searches all visible elements for matching text
 3. **Coordinates** — clicks at the recorded x/y position
 
-If all three strategies fail, the action is logged as `FAILED` and skipped.
-
 ```
 [sessionsnap] [1/5] click: #submit-btn "Submit"
 [sessionsnap] [2/5] click FAILED: Element not found: #old-selector (text: "Gone")
@@ -265,20 +210,417 @@ If all three strategies fail, the action is logged as `FAILED` and skipped.
 [sessionsnap] Replay complete.
 ```
 
-Each action entry includes a `type`, `timestamp`, `url`, and type-specific fields:
+### `recordings` — List recordings for a profile
+
+```bash
+sessionsnap recordings --profile <name> [--json]
+```
+
+Shows all recordings with name (if named), action count, age, action type summary, and a replay hint:
+
+```
+[sessionsnap] 3 recording(s) for profile "acme":
+
+  1. checkout-flow (actions-checkout-flow.json)
+     42 actions  (2h ago)  replay: --name "checkout-flow"
+     click:12  input:8  navigation:3  hover:15  scroll:4
+
+  2. actions-recording-2026-02-11T14-30-00-000Z.json
+     18 actions  (1d ago)  replay: --file "actions-recording-2026-02-11T14-30-00-000Z.json"
+     click:6  input:4  navigation:2  mousemove:6
+```
+
+### `list` — List all profiles
+
+```bash
+sessionsnap list [--json]
+```
+
+Shows all saved profiles with runner, URL, relative date, screenshot/recording counts:
+
+```
+[sessionsnap] 2 profile(s) found:
+
+  acme     [puppeteer]  https://app.acmecorp.io/dashboard  (2h ago)  📸 3  🔴 2
+  staging  [playwright]  https://staging.acmecorp.io/home   (1d ago)  📸 1
+```
+
+### `status` — Show profile details
+
+```bash
+sessionsnap status --profile <name>
+```
+
+Prints profile details: directory path, session metadata, cookie/origin counts, screenshots and recordings.
+
+### `clean` — Delete a profile
+
+```bash
+sessionsnap clean --profile <name> [--force]
+```
+
+Deletes a profile and all its data (snapshot, screenshots, recordings). Prompts for confirmation unless `--force` is used.
+
+## Typical Workflow
+
+```bash
+# 1. Capture — log in and save the session
+sessionsnap capture https://app.acmecorp.io/login --profile acme
+
+# 2. Record — open with saved session, record a user flow
+sessionsnap record https://app.acmecorp.io/dashboard --profile acme --name "checkout-flow"
+
+# 3. Replay — replay the recorded flow
+sessionsnap replay --profile acme --name "checkout-flow"
+
+# 4. Open — browse with saved session (no recording)
+sessionsnap open https://app.acmecorp.io/settings --profile acme
+
+# 5. List recordings
+sessionsnap recordings --profile acme
+
+# 6. Clean up
+sessionsnap clean --profile acme --force
+```
+
+## Snapshot Format
 
 ```json
-[
-  { "type": "click", "selector": "#login-button", "tag": "button", "text": "Sign In", "x": 720, "y": 450 },
-  { "type": "dblclick", "selector": ".cell", "tag": "td", "text": "Edit me", "x": 300, "y": 200 },
-  { "type": "hover", "selector": "nav > .dropdown", "tag": "button", "text": "Menu" },
-  { "type": "input", "selector": "input[name=\"email\"]", "tag": "input", "inputType": "email", "value": "user@example.com" },
-  { "type": "checkbox", "selector": "input[name=\"remember\"]", "inputType": "checkbox", "checked": true },
-  { "type": "keydown", "key": "Escape", "combo": "Escape", "selector": ".modal", "tag": "div" },
-  { "type": "scroll", "scrollX": 0, "scrollY": 800, "scrollHeight": 3200, "viewportHeight": 900 },
-  { "type": "file", "selector": "input[type=\"file\"]", "fileNames": ["photo.jpg"], "fileCount": 1 },
-  { "type": "navigation", "from": "/login", "to": "/dashboard" }
-]
+{
+  "meta": {
+    "runner": "puppeteer",
+    "profile": "acme",
+    "capturedAt": "2026-02-09T12:00:00.000Z",
+    "startUrl": "https://app.acmecorp.io/login",
+    "finalUrl": "https://app.acmecorp.io/dashboard"
+  },
+  "cookies": [
+    {
+      "name": "session_token",
+      "value": "abc123",
+      "domain": ".acmecorp.io",
+      "path": "/",
+      "expires": 1700000000,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Lax"
+    }
+  ],
+  "origins": []
+}
+```
+
+After using `open`, an `updatedAt` field is added to `meta`.
+
+## Architecture
+
+### High-Level Overview
+
+```mermaid
+graph TB
+  subgraph CLI["CLI Layer — bin/sessionsnap.js"]
+    CMD_CAPTURE["capture"]
+    CMD_OPEN["open"]
+    CMD_RECORD["record"]
+    CMD_REPLAY["replay"]
+    CMD_LIST["list"]
+    CMD_RECORDINGS["recordings"]
+    CMD_STATUS["status"]
+    CMD_CLEAN["clean"]
+  end
+
+  subgraph RUNNERS["Runner Layer — Puppeteer / Playwright"]
+    subgraph PUPPETEER["puppeteer/"]
+      P_BROWSER["browser.js\n(Chrome discovery)"]
+      P_CAPTURE["capture.js"]
+      P_OPEN["open.js"]
+      P_RECORD["record.js"]
+      P_REPLAY["replay.js"]
+    end
+    subgraph PLAYWRIGHT["playwright/"]
+      PW_CAPTURE["capture.js"]
+      PW_OPEN["open.js"]
+      PW_RECORD["record.js"]
+      PW_REPLAY["replay.js"]
+    end
+  end
+
+  subgraph CORE["Core Layer — Shared Logic"]
+    SNAPSHOT["snapshot.js\n(normalize cookies,\ncreate/update snapshot)"]
+    HEURISTICS["heuristics.js\n(login detection:\nURL + cookie + regex)"]
+    RECORDER["recorder.js\n(overlay UI + action\ncapture + writeFileSync)"]
+    REPLAYER["replayer.js\n(action execution +\nvisual cursor + fallback)"]
+    CSS_GEN["css-selector-generator\n(robust CSS selectors)"]
+  end
+
+  subgraph STORAGE["Storage Layer — store.js"]
+    PROFILES["~/.sessionsnap/profiles/"]
+    SNAP_FILE["snapshot.json"]
+    SCREENSHOTS["*.png"]
+    ACTIONS["actions-*.json"]
+    REC_META["recordings.json"]
+  end
+
+  subgraph BROWSER["Browser"]
+    PAGE["Browser Page"]
+    OVERLAY["Recording Overlay UI"]
+    CDP["CDP / storageState"]
+  end
+
+  CMD_CAPTURE --> P_CAPTURE & PW_CAPTURE
+  CMD_OPEN --> P_OPEN & PW_OPEN
+  CMD_RECORD --> P_RECORD & PW_RECORD
+  CMD_REPLAY --> P_REPLAY & PW_REPLAY
+  CMD_LIST & CMD_RECORDINGS & CMD_STATUS & CMD_CLEAN --> STORAGE
+
+  P_CAPTURE & P_OPEN & P_RECORD & P_REPLAY --> P_BROWSER
+  P_BROWSER --> PAGE
+
+  P_CAPTURE --> HEURISTICS & SNAPSHOT
+  P_OPEN --> SNAPSHOT
+  P_RECORD --> RECORDER
+  P_REPLAY --> REPLAYER
+
+  PW_CAPTURE --> HEURISTICS & SNAPSHOT
+  PW_OPEN --> SNAPSHOT
+  PW_RECORD --> RECORDER
+  PW_REPLAY --> REPLAYER
+
+  RECORDER --> CSS_GEN
+  RECORDER --> OVERLAY
+  RECORDER --> PAGE
+  REPLAYER --> PAGE
+
+  HEURISTICS --> CDP
+  SNAPSHOT --> STORAGE
+
+  P_CAPTURE & P_OPEN & P_RECORD & P_REPLAY --> STORAGE
+  PW_CAPTURE & PW_OPEN & PW_RECORD & PW_REPLAY --> STORAGE
+
+  STORAGE --> SNAP_FILE & SCREENSHOTS & ACTIONS & REC_META
+
+  style CLI fill:#1e293b,stroke:#475569,color:#f8fafc
+  style CORE fill:#1e3a5f,stroke:#3b82f6,color:#f8fafc
+  style RUNNERS fill:#1a2e1a,stroke:#22c55e,color:#f8fafc
+  style STORAGE fill:#3b1f0b,stroke:#f97316,color:#f8fafc
+  style BROWSER fill:#3b0764,stroke:#a855f7,color:#f8fafc
+```
+
+### Capture Flow
+
+```mermaid
+sequenceDiagram
+  actor User
+  participant CLI as CLI (commander)
+  participant Runner as Runner (Puppeteer/Playwright)
+  participant Browser as Headed Browser
+  participant Heuristics as heuristics.js
+  participant Store as store.js
+  participant Disk as ~/.sessionsnap/profiles/
+
+  User->>CLI: sessionsnap capture <url> --profile acme
+  CLI->>Store: ensureProfileDir("acme")
+  Store->>Disk: mkdir ~/.sessionsnap/profiles/acme/
+  CLI->>Runner: capture(url, opts)
+  Runner->>Browser: launch (headed, 1440×900)
+  Runner->>Browser: page.goto(url)
+  Browser-->>User: Login page displayed
+  User->>Browser: Manual login (CAPTCHA, 2FA, etc.)
+  
+  loop Every 2 seconds
+    Runner->>Heuristics: waitForLoginComplete(page)
+    Heuristics->>Browser: Check URL pattern + cookie count
+    alt --target regex provided
+      Heuristics->>Browser: Check URL matches regex
+    end
+  end
+  
+  Heuristics-->>Runner: Login detected ✓
+  Runner->>Browser: waitForNetworkIdle()
+  Runner->>Browser: page.screenshot()
+  Runner->>Store: saveScreenshot(capture-*.png)
+  Runner->>Browser: getAllCookies (CDP) / context.cookies()
+  Runner->>Store: createSnapshot + saveSnapshot
+  Store->>Disk: Write snapshot.json + screenshot
+  Runner->>Browser: browser.close()
+  CLI-->>User: Profile saved ✓
+```
+
+### Record & Replay Flow
+
+```mermaid
+sequenceDiagram
+  actor User
+  participant CLI as CLI
+  participant Runner as Runner
+  participant Browser as Browser Page
+  participant Recorder as recorder.js
+  participant Replayer as replayer.js
+  participant Store as store.js
+  participant Disk as Disk
+
+  Note over User,Disk: ── RECORD PHASE ──
+
+  User->>CLI: sessionsnap record <url> --profile acme
+  CLI->>Store: loadSnapshot("acme") — verify session exists
+  CLI->>Runner: record(url, opts)
+  Runner->>Browser: launch with userDataDir
+  Runner->>Recorder: setupRecorder(page, runner, dir)
+  Recorder->>Browser: inject css-selector-generator lib
+  Recorder->>Browser: inject action listener script
+  Recorder->>Browser: inject overlay UI (Start/Stop)
+  Recorder->>Browser: exposeFunction(__sessionsnap_report_action)
+  Runner->>Browser: page.goto(url)
+  Browser-->>User: Page with overlay displayed
+  
+  User->>Browser: Click "Start Recording"
+  Browser->>Recorder: __sessionsnap_start_recording()
+  
+  User->>Browser: Interact (click, type, hover, scroll...)
+  loop Each user action
+    Browser->>Recorder: __sessionsnap_report_action(action)
+    Recorder->>Disk: writeFileSync (crash-safe)
+    Recorder-->>CLI: Log: [click] #btn "Submit"
+  end
+  
+  User->>Browser: Click "Stop"
+  Browser->>Browser: Show name dialog
+  User->>Browser: Enter "checkout-flow" → Save
+  Browser->>Recorder: __sessionsnap_stop_recording("checkout-flow")
+  Recorder->>Disk: Write actions-checkout_flow.json
+  Recorder->>Store: saveRecordingMetadata
+  Store->>Disk: Update recordings.json
+
+  Note over User,Disk: ── REPLAY PHASE ──
+
+  User->>CLI: sessionsnap replay --profile acme --name "checkout-flow"
+  CLI->>Store: loadRecordingByName("acme", "checkout-flow")
+  Store-->>CLI: actions[] (N actions)
+  CLI->>Runner: replay(actions, opts)
+  Runner->>Browser: launch with userDataDir
+  Runner->>Browser: goto(startUrl)
+  Runner->>Replayer: replayActions(page, actions)
+  
+  loop Each action
+    Replayer->>Replayer: Calculate delay from timestamps
+    alt click / dblclick
+      Replayer->>Browser: mouse.move(x, y) → CSS / text / coords fallback
+    else input
+      Replayer->>Browser: clear + type(value)
+    else hover
+      Replayer->>Browser: mouse.move(x, y) → hover(selector)
+    else navigation
+      Replayer->>Browser: page.goto(url) → waitForNetworkIdle
+    else scroll
+      Replayer->>Browser: scrollTo(x, y)
+    end
+    Replayer-->>CLI: Log: [1/N] action description
+  end
+  
+  Replayer-->>Runner: Replay complete
+  Runner->>Browser: screenshot()
+  Runner->>Store: saveScreenshot(replay-*.png)
+  Runner->>Browser: browser.close()
+  CLI-->>User: Replay finished ✓
+```
+
+### Storage Structure
+
+```mermaid
+graph LR
+  subgraph HOME["~/.sessionsnap/"]
+    subgraph PROFILES["profiles/"]
+      subgraph ACME["acme/"]
+        SNAP["snapshot.json\n(cookies, meta, origins)"]
+        REC_JSON["recordings.json\n(name → file mapping)"]
+        CAP_PNG["capture-2026-*.png"]
+        OPEN_PNG["open-2026-*.png"]
+        REPLAY_PNG["replay-2026-*.png"]
+        RECORD_PNG["record-2026-*.png"]
+        ACTIONS1["actions-checkout_flow.json"]
+        ACTIONS2["actions-recording-*.json"]
+        USERDATA["Chrome userDataDir\n(cookies, localStorage,\nindexedDB, cache)"]
+      end
+      subgraph STAGING["staging/"]
+        SNAP2["snapshot.json"]
+        OTHER["..."]
+      end
+    end
+  end
+
+  style HOME fill:#1c1917,stroke:#78716c,color:#f5f5f4
+  style PROFILES fill:#292524,stroke:#a8a29e,color:#f5f5f4
+  style ACME fill:#1e3a5f,stroke:#3b82f6,color:#f8fafc
+  style STAGING fill:#1e3a5f,stroke:#3b82f6,color:#f8fafc
+```
+
+### Action Recording Pipeline
+
+```mermaid
+flowchart LR
+  subgraph PAGE["Browser Page Context"]
+    EVENTS["DOM Events\nclick · input · hover\nscroll · keydown\ndblclick · submit\ncheckbox · file\nmousemove"]
+    CSS["css-selector-generator\n(robust selectors)"]
+    DEBOUNCE["Debounce / Throttle\nhover: 150ms\nscroll: 400ms\nmousemove: ~16ms"]
+    OVERLAY["Overlay UI\nStart ⏺ / Stop ⏹\nTimer · Counter"]
+    FILTER["Filter\n- isOverlayEvent?\n- isRecording?\n- noise reduction"]
+  end
+
+  subgraph BRIDGE["Page ↔ Node.js Bridge"]
+    EXPOSE["page.exposeFunction\n__sessionsnap_report_action"]
+  end
+
+  subgraph NODEJS["Node.js Process"]
+    HANDLER["Action Handler\n(log + accumulate)"]
+    SYNC_WRITE["writeFileSync\n(crash-safe)"]
+    METADATA["saveRecordingMetadata\n(recordings.json)"]
+  end
+
+  EVENTS --> CSS --> DEBOUNCE --> FILTER --> EXPOSE
+  OVERLAY -.->|start/stop| FILTER
+  EXPOSE --> HANDLER --> SYNC_WRITE
+  HANDLER --> METADATA
+
+  style PAGE fill:#3b0764,stroke:#a855f7,color:#f8fafc
+  style BRIDGE fill:#713f12,stroke:#eab308,color:#f8fafc
+  style NODEJS fill:#1e3a5f,stroke:#3b82f6,color:#f8fafc
+```
+
+### Replay Fallback Strategy
+
+```mermaid
+flowchart TD
+  START["Replay Action"] --> TYPE{Action Type?}
+  
+  TYPE -->|click / dblclick| MOVE["mouse.move(x, y)"]
+  MOVE --> SEL{"CSS Selector\nfound?"}
+  SEL -->|Yes| CLICK_SEL["Click via selector ✓"]
+  SEL -->|No / timeout| TEXT{"Text content\nmatch?"}
+  TEXT -->|Yes| CLICK_TEXT["Click via text ✓"]
+  TEXT -->|No| COORDS{"Coordinates\navailable?"}
+  COORDS -->|Yes| CLICK_XY["Click at (x, y) ✓"]
+  COORDS -->|No| FAIL["FAILED ✗"]
+  
+  TYPE -->|input| INPUT["Clear field → type value"]
+  TYPE -->|hover| HOVER["mouse.move → hover(selector)"]
+  TYPE -->|navigation| NAV["page.goto → waitForNetworkIdle"]
+  TYPE -->|scroll| SCROLL["window.scrollTo / element.scrollTo"]
+  TYPE -->|keydown| KEY["keyboard.press with modifiers"]
+  TYPE -->|checkbox| CHECK["Check state → toggle if needed"]
+  TYPE -->|submit| SUBMIT["requestSubmit / Enter key"]
+  TYPE -->|mousemove| MMOVE["mouse.move(x, y) per point"]
+  
+  FAIL --> BAIL{--bail?}
+  BAIL -->|Yes| EXIT["Exit code 1"]
+  BAIL -->|No| NEXT["Continue to next action"]
+
+  style START fill:#1e3a5f,stroke:#3b82f6,color:#f8fafc
+  style FAIL fill:#7f1d1d,stroke:#ef4444,color:#f8fafc
+  style EXIT fill:#7f1d1d,stroke:#ef4444,color:#f8fafc
+  style CLICK_SEL fill:#14532d,stroke:#22c55e,color:#f8fafc
+  style CLICK_TEXT fill:#14532d,stroke:#22c55e,color:#f8fafc
+  style CLICK_XY fill:#14532d,stroke:#22c55e,color:#f8fafc
+  style NEXT fill:#713f12,stroke:#eab308,color:#f8fafc
 ```
 
 ## Project Structure
@@ -291,17 +633,20 @@ sessionsnap/
     core/
       snapshot.js           # Canonical session format & normalization
       heuristics.js         # Login detection logic (URL + cookie polling)
-      recorder.js           # Injected script for recording user actions
+      recorder.js           # Injected script + overlay UI for recording
       replayer.js           # Replay engine for recorded actions
     puppeteer/
+      browser.js            # Chrome/Chromium executable discovery
       capture.js            # Capture session via CDP
       open.js               # Open URL with saved profile + update on close
+      record.js             # Record user actions via Puppeteer
       replay.js             # Replay recorded actions via Puppeteer
     playwright/
       capture.js            # Capture session via storageState
       open.js               # Open URL with saved profile + update on close
+      record.js             # Record user actions via Playwright
       replay.js             # Replay recorded actions via Playwright
-    store.js                # Profile directory & JSON I/O
+    store.js                # Profile directory, metadata & JSON I/O
   test/
     store.test.js
     snapshot.test.js