writetrack 0.10.3 → 0.11.0

package/README.md

@@ -1,8 +1,8 @@
 # WriteTrack
 
-Detect AI-generated and pasted text through keystroke dynamics.
+Capture and analyze the writing process through keystroke dynamics.
 
-WriteTrack analyzes _how_ text was entered, not what was written. Human typing has natural variation in timing, rhythm, and corrections. Pasted or AI-generated text arrives all at once with no behavioral fingerprint. WriteTrack captures the difference.
+WriteTrack is an embeddable SDK that instruments text inputs to record _how_ text was written — timing, rhythm, corrections, clipboard usage, and composition patterns. It gives platforms behavioral evidence of the writing process, not just the finished text.
 
 - **~118KB** gzipped (18KB JS + 100KB WASM)
 - **0** runtime dependencies
@@ -58,7 +58,7 @@ import { WriteTrackPlugin } from 'writetrack/prosemirror';
 import { WriteTrackModule } from 'writetrack/quill';
 import { createWriteTrackLexical } from 'writetrack/lexical';
 import { createWriteTrackSlate } from 'writetrack/slate';
-import { createWriteTrackTinyMCE } from 'writetrack/tinymce';
+import 'writetrack/tinymce'; // registers native TinyMCE plugin
 ```
 
 ## Output Sinks
@@ -77,7 +77,7 @@ tracker
 
 ## What It Captures
 
-WriteTrack instruments your text inputs and records the behavioral signals behind every keystroke:
+WriteTrack instruments text inputs and records the behavioral signals behind every keystroke:
 
 - **Timing intervals** — milliseconds between each keystroke
 - **Rhythm variance** — consistency or erratic cadence
@@ -86,13 +86,29 @@ WriteTrack instruments your text inputs and records the behavioral signals behin
 - **Selection events** — text selections via mouse, keyboard, or programmatic
 - **Composition events** — IME input for CJK and other non-Latin scripts
 
+## What It Produces
+
+WASM-powered analysis returns a `SessionAnalysis` covering seven dimensions:
+
+- **Content origin** — what proportion was typed, pasted, or autocompleted
+- **Timing authenticity** — rhythm consistency, periodicity, entropy
+- **Revision behavior** — corrections, navigation, undo/redo patterns
+- **Session continuity** — focus changes, tab-aways, session structure
+- **Physical plausibility** — impossible sequences, synthetic event markers
+- **Temporal patterns** — speed over time, warmup/fatigue, burst patterns
+- **Writing process** — planning, drafting, and revision phase segmentation
+
+Each dimension produces a machine-readable indicator code and detailed metrics suitable for visualization.
+
 ## Use Cases
 
-**Education** — Flag essays that were pasted rather than composed. Give instructors behavioral context alongside content.
+**Education** — Give instructors behavioral context alongside submitted work. See whether text was composed or pasted.
+
+**Assessment** — Add a behavioral layer to written responses. Distinguish engaged composition from copy-paste submission.
 
-**Research** — Distinguish survey respondents who engaged thoughtfully from those who copy-pasted boilerplate.
+**Compliance** — Know when form attestations were typed versus pasted.
 
-**Compliance** — Add a behavioral layer to form submissions. Know when attestations were typed versus pasted.
+**Research** — Capture writing process data for studies on composition behavior, revision patterns, and typing fluency.
 
 ## API
 
@@ -120,29 +136,30 @@ interface WriteTrackOptions {
 
 ### Methods
 
-| Method                             | Returns                          | Description                                       |
-| ---------------------------------- | -------------------------------- | ------------------------------------------------- |
-| `start()`                          | `void`                           | Begin capturing events                            |
-| `stop()`                           | `void`                           | Stop capturing and clean up                       |
-| `getData()`                        | `WriteTrackDataSchema`           | Export full session data                          |
-| `getText()`                        | `string`                         | Current text content                              |
-| `getRawEvents()`                   | `KeystrokeEvent[]`               | All captured keystroke events                     |
-| `getClipboardEvents()`             | `ClipboardEvent[]`               | Paste/copy/cut events                             |
-| `getSelectionEvents()`             | `SelectionEvent[]`               | Text selection events                             |
-| `getUndoRedoEvents()`              | `UndoRedoEvent[]`                | Undo/redo events                                  |
-| `getCompositionEvents()`           | `CompositionEvent[]`             | IME composition events                            |
-| `getProgrammaticInsertionEvents()` | `ProgrammaticInsertionEvent[]`   | Programmatic insertion events                     |
-| `getSessionDuration()`             | `number`                         | Session duration in ms                            |
-| `getActiveTime()`                  | `number`                         | Active (visible) session time in ms               |
-| `getKeystrokeCount()`              | `number`                         | Total keystrokes captured                         |
-| `getAnalysis()`                    | `Promise<SessionAnalysis\|null>` | WASM-powered session analysis                     |
-| `getSessionReport()`               | `Promise<SessionReport>`         | Combined data + analysis                          |
-| `pipe(sink)`                       | `this`                           | Register an output sink                           |
-| `on(event, handler)`               | `this`                           | Register an event listener (`tick`, `pipe:error`) |
-| `isLicenseValid()`                 | `boolean`                        | Whether license is valid                          |
-| `isLicenseValidated()`             | `boolean`                        | Whether license check has completed               |
-| `isTargetDetached()`               | `boolean`                        | Whether the target element was removed            |
-| `clearPersistedData()`             | `Promise<void>`                  | Clear IndexedDB persisted session                 |
+| Method                             | Returns                          | Description                                      |
+| ---------------------------------- | -------------------------------- | ------------------------------------------------ |
+| `start()`                          | `void`                           | Begin capturing events                           |
+| `stop()`                           | `void`                           | Stop capturing and clean up                      |
+| `stopAndWait()`                    | `Promise<void>`                  | Stop and wait for pending IndexedDB save         |
+| `getData()`                        | `WriteTrackDataSchema`           | Export full session data                         |
+| `getText()`                        | `string`                         | Current text content                             |
+| `getRawEvents()`                   | `KeystrokeEvent[]`               | All captured keystroke events                    |
+| `getClipboardEvents()`             | `ClipboardEvent[]`               | Paste/copy/cut events                            |
+| `getSelectionEvents()`             | `SelectionEvent[]`               | Text selection events                            |
+| `getUndoRedoEvents()`              | `UndoRedoEvent[]`                | Undo/redo events                                 |
+| `getCompositionEvents()`           | `CompositionEvent[]`             | IME composition events                           |
+| `getProgrammaticInsertionEvents()` | `ProgrammaticInsertionEvent[]`   | Programmatic insertion events                    |
+| `getSessionDuration()`             | `number`                         | Session duration in ms                           |
+| `getActiveTime()`                  | `number`                         | Active (visible) session time in ms              |
+| `getKeystrokeCount()`              | `number`                         | Total keystrokes captured                        |
+| `getAnalysis()`                    | `Promise<SessionAnalysis\|null>` | WASM-powered session analysis                    |
+| `getSessionReport()`               | `Promise<SessionReport>`         | Combined data + analysis                         |
+| `pipe(sink)`                       | `this`                           | Register an output sink                          |
+| `on(event, handler)`               | `() => void`                     | Register an event listener (returns unsubscribe) |
+| `isLicenseValid()`                 | `boolean`                        | Whether license is valid                         |
+| `isLicenseValidated()`             | `boolean`                        | Whether license check has completed              |
+| `isTargetDetached()`               | `boolean`                        | Whether the target element was removed           |
+| `clearPersistedData()`             | `Promise<void>`                  | Clear IndexedDB persisted session                |
 
 ### Static Methods
 
@@ -171,24 +188,58 @@ const analysis = await analyzeEvents(data, {
 });
 ```
 
+### Analysis Helpers
+
+Convenience functions for extracting commonly needed values from a `SessionAnalysis`:
+
+| Function                              | Returns                                                    | Description                      |
+| ------------------------------------- | ---------------------------------------------------------- | -------------------------------- |
+| `getSessionDurationMs(analysis)`      | `number`                                                   | Session duration in milliseconds |
+| `getTypingSpeed(analysis)`            | `{ cpm: number; wpm: number }`                             | Characters and words per minute  |
+| `getContentOriginBreakdown(analysis)` | `{ typed: number; pasted: number; autocompleted: number }` | Content origin ratios (0-1 each) |
+
+```typescript
+import { getTypingSpeed, getContentOriginBreakdown } from 'writetrack';
+
+const analysis = await tracker.getAnalysis();
+if (analysis) {
+  const { wpm } = getTypingSpeed(analysis);
+  const { typed, pasted } = getContentOriginBreakdown(analysis);
+}
+```
+
+### Testing Utilities
+
+The `writetrack/testing` subpath export provides framework-agnostic factories for creating mock WriteTrack instances and `SessionAnalysis` objects in consumer tests:
+
+```typescript
+import { createMockAnalysis, createMockTracker } from 'writetrack/testing';
+
+const analysis = createMockAnalysis({ keydownCount: 500 });
+const tracker = createMockTracker({ analysis });
+```
+
+| Function                         | Returns           | Description                                        |
+| -------------------------------- | ----------------- | -------------------------------------------------- |
+| `createMockAnalysis(overrides?)` | `SessionAnalysis` | Complete mock analysis with deep-partial overrides |
+| `createMockTracker(options?)`    | `MockWriteTrack`  | Mock tracker with configurable analysis and data   |
+
 ### Exported Types
 
 Full type definitions are included in the package:
 
 **Functions:** `analyzeEvents`, `createSessionReport`, `formatIndicator`, `getHighResolutionTime`
 
-**Types:** `WriteTrackOptions`, `PersistedSessionInfo`, `KeystrokeEvent`, `ClipboardEvent`, `SelectionEvent`, `UndoRedoEvent`, `CompositionEvent`, `ProgrammaticInsertionEvent`, `ModifierState`, `InputSource`, `WriteTrackDataSchema`, `DataQualityMetrics`, `SessionMetadata`, `SessionAnalysis`, `SessionReport`, `IndicatorOutput`, `ContentOriginAnalysis`, `TimingAuthenticityAnalysis`, `SessionContinuityAnalysis`, `PhysicalPlausibilityAnalysis`, `RevisionBehaviorAnalysis`, `TemporalPatternsAnalysis`, `AnalyzeEventsOptions`, `WriteTrackSink`, `WebhookOptions`, `DatadogOptions`, `DatadogClient`, `SegmentOptions`, `SegmentClient`, `OpenTelemetryOptions`, `OTelTracer`, `OTelSpan`
+**Types:** `WriteTrackOptions`, `PersistedSessionInfo`, `KeystrokeEvent`, `ClipboardEvent`, `SelectionEvent`, `UndoRedoEvent`, `CompositionEvent`, `ProgrammaticInsertionEvent`, `ModifierState`, `InputSource`, `WriteTrackDataSchema`, `DataQualityMetrics`, `SessionMetadata`, `SessionAnalysis`, `SessionReport`, `IndicatorOutput`, `ContentOriginAnalysis`, `TimingAuthenticityAnalysis`, `SessionContinuityAnalysis`, `PhysicalPlausibilityAnalysis`, `RevisionBehaviorAnalysis`, `TemporalPatternsAnalysis`, `WritingProcessAnalysis`, `WritingProcessSegment`, `PhaseTransition`, `WindowFeatures`, `AnalyzeEventsOptions`, `WriteTrackSink`, `WebhookOptions`, `DatadogOptions`, `DatadogClient`, `SegmentOptions`, `SegmentClient`, `OpenTelemetryOptions`, `OTelTracer`, `OTelSpan`
 
 ## Browser Support
 
 | Browser | Version |
 | ------- | ------- |
-| Chrome  | 62+     |
-| Firefox | 56+     |
-| Safari  | 14.1+   |
-| Edge    | 79+     |
-
-All features including license verification work at these versions. License validation uses ECDSA P-256 via `crypto.subtle`, which has been supported since Chrome 37+, Firefox 34+, Safari 11+, and Edge 79+.
+| Chrome  | 90+     |
+| Firefox | 88+     |
+| Safari  | 14+     |
+| Edge    | 90+     |
 
 ## Privacy