# Keystroke Dynamics: Full Implementation Plan

## Context

The existing Svelte app captures raw digraph timing (6 metrics) and displays averages + a table. It has no persistence, no profile building, no comparison logic, and no human-ness analysis. The goal is to build a complete keystroke dynamics research tool that can:

1. Build typing signatures from free-text sessions

2. Store and manage user profiles

3. Compare sessions against profiles (same-user verification)

4. Score whether a typing session appears human or bot-generated

Based on research from the keystroke dynamics survey (arxiv 2303.04605v2), the approach uses digraph aggregation, Scaled Manhattan Distance for comparison, and multi-factor human-ness scoring.

**Decisions:**

- Keep legacy Svelte `$:` reactive syntax (no runes migration)

- Build all 4 tabs from the start with placeholders for unbuilt phases

- Track paste events and factor into human-ness analysis

---

## Step 0: Refactor & Extract Components

Extract the monolithic `App.svelte` into a component architecture. Keystroke capture stays at the window level (always active regardless of tab).

**Files to create:**

- `src/lib/types.ts` — all TypeScript interfaces (RawDigraph, DigraphAggregation, MetricStats, Profile, ComparisonResult, HumannessResult, etc.)

- `src/lib/utils.ts` — extract `round()`, `avg()`, add `std()` helper

- `src/lib/components/CapturePanel.svelte` — textarea + raw digraph table + JSON export (extracted from App.svelte)

- `src/lib/components/StatsBar.svelte` — the 6-metric averages bar

- `src/lib/components/TabBar.svelte` — tab navigation (Capture | Profile | Compare | Human-ness)

**Refactor `App.svelte`** into orchestrator: holds canonical `digraphs[]` array and `sessionMetadata`, manages tab state, keeps `svelte:window` keydown/keyup handlers so capture works on all tabs.

**Tab setup:** All 4 tabs visible from the start. Non-implemented tabs show a placeholder until their phase is built.

**Key gotcha:** Don't conditionally render CapturePanel with `{#if}` — either always render it (hide with CSS) or keep the `svelte:window` bindings in App.svelte. Recommended: keep handlers in App.svelte.

---

## Step 1: Per-Digraph Aggregation & Profile Building

**New file: `src/lib/aggregation.ts`**

- `groupDigraphs(digraphs)` — group by normalized key pair (lowercase key1 + key2)

- `computeMetricStats(values[])` — returns `{ mean, std, min, max, count }` for a number array

- `aggregateDigraphs(digraphs)` — for each group, compute MetricStats for all 6 metrics, sort by count descending

**Session metadata tracking (add to App.svelte handlers):**

- `totalKeystrokes` — increment on every keydown (not just digraph-forming)

- `backspaceCount` — increment when `e.key === 'Backspace'`

- `pauseCount` — gaps > 500ms between consecutive keydowns (track `lastKeydownTime`)

- `avgTypingSpeed` — chars/min from total keystrokes and session duration

- `sessionDurationMs` — first keydown to last keyup

**New component: `src/lib/components/ProfileSummary.svelte`**

- Table of top 15 digraphs by frequency: `keys | count | HT1 (mean +/- std) | ... all 6 metrics`

- "Show all" toggle

- Session metadata summary row

**Case normalization:** Treat `'A'` and `'a'` as the same key when grouping digraphs. Include Backspace and Enter in aggregation (they carry signature), exclude arrow/navigation keys.

---

## Step 2: Profile Storage & Management

**New file: `src/lib/storage.ts`**

- localStorage key: `"kd_profiles"`

- `saveProfile(profile: Profile)` — JSON stringify, append to stored array

- `loadProfiles(): Profile[]` — parse with try/catch, validate shape

- `deleteProfile(id: string)` — filter and re-save

- `exportProfile(profile: Profile)` — Blob + URL.createObjectURL for JSON file download

- `importProfile(file: File): Profile` — FileReader, JSON.parse, validate

**Profile interface stores aggregations (not raw digraphs)** to keep localStorage size manageable.

**New component: `src/lib/components/ProfileManager.svelte`**

- Text input + "Save Profile" button (default name: "Session - {date}")

- List of saved profiles: name, date, digraph count, delete button

- Export button per profile (JSON file download)

- Import button (hidden file input)

---

## Step 3: Session Comparison (Scaled Manhattan Distance)

**New file: `src/lib/comparison.ts`**

**Algorithm: Scaled Manhattan Distance**

1. Build lookup maps from both session and profile aggregations

2. Find shared digraph types (by normalized key pair)

3. For each shared digraph, for each of 6 metrics:

   - `distance = |mean_session - mean_profile| / std_profile`

   - If `std_profile < epsilon`: use `|mean_session - mean_profile| / max(mean_profile * 0.1, 1.0)` as fallback

4. `overallDistance = sum(all distances) / (sharedCount * 6)`

5. `similarityPercent = max(0, 100 * (1 - overallDistance / 3.0))` — distance of 3 std devs = 0% similar

6. Confidence: `shared >= 15` high, `>= 10` medium, `>= 5` low, `< 5` insufficient

**New component: `src/lib/components/ComparisonView.svelte`**

- Dropdown to select a saved profile

- "Compare" button (disabled if insufficient overlap)

- Results: large similarity %, confidence badge, raw distance score

- Per-digraph breakdown table sorted by distance (worst first), with color-coded match quality bars

- Note in UI: comparing prose vs code sessions for the same user will produce poor matches

---

## Step 4: Human-ness Detection

**New file: `src/lib/humanness.ts`**

Six sub-scores (0-100 each), combined via weighted average:

| Sub-score | Weight | What it measures | Human signal |

|-----------|--------|-----------------|-------------|

| Timing Variance | 0.20 | CV (std/mean) of pressPress per digraph | Humans CV > 0.15, bots < 0.05 |

| Correction Rate | 0.15 | backspaceCount / totalKeystrokes | Humans 5-15%, zero is suspicious |

| Pause Distribution | 0.20 | Presence/variance of gaps > 500ms, > 1s | Humans have thinking pauses |

| Distribution Shape | 0.15 | Skewness of timing arrays | Human timing is right-skewed (log-normal) |

| Flight Time Negativity | 0.15 | % of digraphs with releasePress < 0 | Humans overlap keys, bots don't |

| Burst Patterns | 0.15 | Variance of "burst" lengths (consecutive digraphs < 300ms gap) | Humans type in bursts of 3-15 keys |

**Composite verdict:** score >= 60 "likely human", 40-60 "uncertain", < 40 "likely bot"

**Minimum requirement:** 20 digraphs before computing. Show "keep typing..." below that.

**New component: `src/lib/components/HumannessView.svelte`**

- Large score display (0-100) with verdict text and color

- 6 horizontal bars showing each sub-score with label

- Brief explanation under each bar

**Paste detection:** Add `on:paste` handler to textarea. Track `pasteCount` and `pastedCharCount` in session metadata. Factor into human-ness score — a session where most content was pasted (high paste ratio vs keystrokes) scores lower. Not inherently disqualifying, but a signal.

---

## Implementation Order

```

Step 0 (refactor)  -->  Step 1 (aggregation)  -->  Step 2 (storage)

                                                       |

                                                   Step 3 (comparison)

                                                       |

                                                   Step 4 (human-ness)

```

Steps 3 and 4 are independent of each other (both depend on Step 1's aggregation). Step 2 must come before Step 3 (comparison needs saved profiles to compare against).

---

## File Summary

| File | Action |

|------|--------|

| `src/App.svelte` | Refactor into orchestrator |

| `src/lib/types.ts` | New — all interfaces |

| `src/lib/utils.ts` | New — shared math helpers |

| `src/lib/aggregation.ts` | New — digraph grouping + stats |

| `src/lib/storage.ts` | New — localStorage profile CRUD |

| `src/lib/comparison.ts` | New — Scaled Manhattan Distance |

| `src/lib/humanness.ts` | New — 6-factor human-ness scoring |

| `src/lib/components/CapturePanel.svelte` | New — extracted capture UI |

| `src/lib/components/StatsBar.svelte` | New — extracted stats bar |

| `src/lib/components/TabBar.svelte` | New — tab navigation |

| `src/lib/components/ProfileSummary.svelte` | New — aggregated digraph view |

| `src/lib/components/ProfileManager.svelte` | New — save/load/export profiles |

| `src/lib/components/ComparisonView.svelte` | New — comparison results |

| `src/lib/components/HumannessView.svelte` | New — human-ness score display |

| `src/app.css` | Minor additions for tabs, score displays |

---

## Verification

After each step:

1. `bun run dev` — app loads without errors

2. Type in textarea — digraphs still captured correctly

3. Step 1: Verify aggregated stats appear in Profile tab, digraph grouping works with repeated pairs

4. Step 2: Save a profile, reload page, profile persists. Export/import round-trips correctly.

5. Step 3: Save a profile, type new session, compare — similarity score and per-digraph breakdown appear. Test with same content (should be high similarity) and different content (lower but non-zero for same user).

6. Step 4: Type naturally — should score > 60. Test edge case: very short session shows "keep typing" message.

  import { round } from './lib/utils';

  import TabBar from './lib/components/TabBar.svelte';

  import CapturePanel from './lib/components/CapturePanel.svelte';

  let activeTab = 'capture';

      const label = (k) => (k === ' ' ? '\u2423' : k);

          keys: `${label(k1.key)} \u2192 ${label(k2.key)}`,

  <TabBar bind:activeTab />

  {#if activeTab === 'capture'}

    <CapturePanel bind:digraphs bind:typedText />

    {#if digraphs.length > 0}

      <button class="clear-btn" on:click={clear}>clear session</button>

    {/if}

  {:else if activeTab === 'profile'}

    <div class="placeholder">

      <p>profile builder</p>

      <span class="placeholder-sub">coming in step 1</span>

  {:else if activeTab === 'compare'}

    <div class="placeholder">

      <p>session comparison</p>

      <span class="placeholder-sub">coming in step 3</span>

  {:else if activeTab === 'humanness'}

    <div class="placeholder">

      <p>human-ness analysis</p>

      <span class="placeholder-sub">coming in step 4</span>

  .clear-btn {

    align-self: flex-end;

    font-size: 12px;

    padding: 4px 8px;

  .placeholder {

    justify-content: center;

    padding: 4rem 2rem;

    border: 1px dashed #333;

    gap: 0.5rem;

  .placeholder p {

  .placeholder-sub {

    font-size: 11px;

    color: #555;

<script>

  import StatsBar from './StatsBar.svelte';

  export let digraphs = [];

  export let typedText = '';

  let copied = false;

  function copyJson() {

    navigator.clipboard.writeText(jsonData);

    copied = true;

    setTimeout(() => (copied = false), 2000);

  }

  $: jsonData = JSON.stringify(

    digraphs.map((d) => ({

      keys: d.keys,

      key_1: d.key1,

      key_2: d.key2,

      hold_time_1_ms: d.holdTime1,

      hold_time_2_ms: d.holdTime2,

      press_press_ms: d.pressPress,

      release_release_ms: d.releaseRelease,

      press_release_ms: d.pressRelease,

      release_press_ms: d.releasePress,

    })),

    null,

    2

  );

</script>

<textarea

  bind:value={typedText}

  placeholder="start typing..."

  rows="4"

></textarea>

{#if digraphs.length > 0}

  <StatsBar {digraphs} />

  <div class="digraph-table-wrap">

    <table class="digraph-table">

      <thead>

        <tr>

          <th>keys</th>

          <th>HT1</th>

          <th>HT2</th>

          <th>PP</th>

          <th>RR</th>

          <th>PR</th>

          <th>RP</th>

        </tr>

      </thead>

      <tbody>

        {#each digraphs as d (d.id)}

          <tr>

            <td class="keys-cell">{d.keys}</td>

            <td>{d.holdTime1}</td>

            <td>{d.holdTime2}</td>

            <td>{d.pressPress}</td>

            <td>{d.releaseRelease}</td>

            <td>{d.pressRelease}</td>

            <td>{d.releasePress}</td>

          </tr>

        {/each}

      </tbody>

    </table>

  </div>

  <div class="json-section">

    <div class="json-header">

      <span>data</span>

      <div class="json-actions">

        <button on:click={copyJson}>{copied ? 'copied!' : 'copy'}</button>

      </div>

    </div>

    <pre class="json-output">{jsonData}</pre>

  </div>

{/if}

<style>

  textarea {

    width: 100%;

    border: 1px solid #333;

    background: transparent;

    color: inherit;

    font-family: inherit;

    font-size: 14px;

    padding: 1rem;

    resize: vertical;

    outline: none;

    box-sizing: border-box;

  }

  textarea::placeholder {

    color: #888;

  }

  textarea:focus {

    border-color: #888;

  }

  .digraph-table-wrap {

    border: 1px solid #333;

    max-height: 300px;

    overflow-y: auto;

  }

  .digraph-table {

    width: 100%;

    border-collapse: collapse;

    font-size: 12px;

  }

  .digraph-table th,

  .digraph-table td {

    padding: 0.4rem 0.5rem;

    text-align: center;

    border-bottom: 1px solid #333;

  }

  .digraph-table th {

    position: sticky;

    top: 0;

    background: #121113;

    color: #888;

    font-weight: 400;

    font-size: 10px;

    text-transform: uppercase;

    letter-spacing: 0.05em;

  }

  .digraph-table .keys-cell {

    text-align: left;

    font-weight: 700;

  }

  .json-section {

    display: flex;

    flex-direction: column;

    gap: 0.5rem;

  }

  .json-header {

    display: flex;

    justify-content: space-between;

    align-items: center;

    font-size: 12px;

    color: #888;

  }

  .json-actions {

    display: flex;

    gap: 0.5rem;

  }

  .json-actions button {

    font-size: 12px;

    padding: 4px 8px;

  }

  .json-output {

    font-size: 12px;

    line-height: 1.5;

    color: #ffffff;

    border: 1px solid #333;

    padding: 1rem;

    overflow-x: auto;

    white-space: pre;

    max-height: 400px;

    overflow-y: auto;

  }

</style>

<script>

  import { avg } from '../utils';

  export let digraphs = [];

  $: avgHT1 = avg(digraphs, (d) => d.holdTime1);

  $: avgHT2 = avg(digraphs, (d) => d.holdTime2);

  $: avgPP = avg(digraphs, (d) => d.pressPress);

  $: avgRR = avg(digraphs, (d) => d.releaseRelease);

  $: avgPR = avg(digraphs, (d) => d.pressRelease);

  $: avgRP = avg(digraphs, (d) => d.releasePress);

</script>

<div class="stats-bar">

  <div class="stat">

    <span class="stat-val">{avgHT1}<span class="unit-sm">ms</span></span>

    <span class="stat-label">hold time 1</span>

  </div>

  <div class="stat">

    <span class="stat-val">{avgHT2}<span class="unit-sm">ms</span></span>

    <span class="stat-label">hold time 2</span>

  </div>

  <div class="stat">

    <span class="stat-val">{avgPP}<span class="unit-sm">ms</span></span>

    <span class="stat-label">press-press</span>

  </div>

  <div class="stat">

    <span class="stat-val">{avgRR}<span class="unit-sm">ms</span></span>

    <span class="stat-label">release-release</span>

  </div>

  <div class="stat">

    <span class="stat-val">{avgPR}<span class="unit-sm">ms</span></span>

    <span class="stat-label">press-release</span>

  </div>

  <div class="stat">

    <span class="stat-val">{avgRP}<span class="unit-sm">ms</span></span>

    <span class="stat-label">release-press</span>

  </div>

</div>

<style>

  .stats-bar {

    display: grid;

    grid-template-columns: repeat(6, 1fr);

    border: 1px solid #333;

  }

  .stat {

    display: flex;

    flex-direction: column;

    align-items: center;

    padding: 0.75rem 0.5rem;

    border-right: 1px solid #333;

  }

  .stat:last-child {

    border-right: none;

  }

  .stat-val {

    font-size: 14px;

    font-weight: 700;

  }

  .stat-label {

    font-size: 10px;

    color: #888;

    margin-top: 0.15rem;

  }

  .unit-sm {

    font-size: 10px;

    color: #888;

    font-weight: 400;

  }

  @media (max-width: 480px) {

    .stats-bar {

      grid-template-columns: repeat(3, 1fr);

    }

    .stat:nth-child(3) {

      border-right: none;

    }

    .stat:nth-child(1),

    .stat:nth-child(2),

    .stat:nth-child(3) {

      border-bottom: 1px solid #333;

    }

  }

</style>

<script>

  export let activeTab = 'capture';

  const tabs = [

    { id: 'capture', label: 'capture' },

    { id: 'profile', label: 'profile' },

    { id: 'compare', label: 'compare' },

    { id: 'humanness', label: 'human-ness' },

  ];

</script>

<nav class="tab-bar">

  {#each tabs as tab}

    <button

      class="tab"

      class:active={activeTab === tab.id}

      on:click={() => (activeTab = tab.id)}

    >

      {tab.label}

    </button>

  {/each}

</nav>

<style>

  .tab-bar {

    display: flex;

    gap: 0;

    border: 1px solid #333;

  }

  .tab {

    flex: 1;

    padding: 0.5rem 1rem;

    font-size: 12px;

    letter-spacing: 0.05em;

    border: none;

    border-right: 1px solid #333;

    background: transparent;

    color: #888;

    cursor: pointer;

  }

  .tab:last-child {

    border-right: none;

  }

  .tab:hover {

    color: #fff;

    opacity: 1;

  }

  .tab.active {

    color: #fff;

    background: #1a1a1a;

  }

</style>

export interface RawDigraph {

  id: number;

  keys: string;

  key1: string;

  key2: string;

  holdTime1: number;

  holdTime2: number;

  pressPress: number;

  releaseRelease: number;

  pressRelease: number;

  releasePress: number;

}

export interface MetricStats {

  mean: number;

  std: number;

  min: number;

  max: number;

  count: number;

}

export interface DigraphAggregation {

  normalizedKeys: string;

  count: number;

  holdTime1: MetricStats;

  holdTime2: MetricStats;

  pressPress: MetricStats;

  releaseRelease: MetricStats;

  pressRelease: MetricStats;

  releasePress: MetricStats;

}

export interface SessionMetadata {

  totalKeystrokes: number;

  backspaceCount: number;

  pauseCount: number;

  avgTypingSpeed: number;

  sessionDurationMs: number;

  pasteCount: number;

  pastedCharCount: number;

}

export interface Profile {

  id: string;

  name: string;

  createdAt: string;

  digraphCount: number;

  aggregations: DigraphAggregation[];

  metadata: SessionMetadata;

}

export interface ComparisonResult {

  overallDistance: number;

  similarityPercent: number;

  confidence: 'high' | 'medium' | 'low' | 'insufficient';

  sharedCount: number;

  perDigraph: PerDigraphComparison[];

}

export interface PerDigraphComparison {

  normalizedKeys: string;

  distance: number;

  matchPercent: number;

}

export interface HumannessResult {

  score: number;

  verdict: 'likely human' | 'uncertain' | 'likely bot';

  subScores: {

    timingVariance: number;

    correctionRate: number;

    pauseDistribution: number;

    distributionShape: number;

    flightTimeNegativity: number;

    burstPatterns: number;

  };

}

export type TabId = 'capture' | 'profile' | 'compare' | 'humanness';

export function round(v: number): number {

  return Math.round(v * 10) / 10;

}

export function avg(arr: any[], fn: (d: any) => number): string {

  if (arr.length === 0) return '\u2014';

  return (arr.reduce((s, d) => s + fn(d), 0) / arr.length).toFixed(1);

}

export function std(values: number[]): number {

  if (values.length < 2) return 0;

  const m = values.reduce((s, v) => s + v, 0) / values.length;

  const variance = values.reduce((s, v) => s + (v - m) ** 2, 0) / (values.length - 1);

  return Math.sqrt(variance);

}