writetrack 0.10.3 → 0.12.0

package/README.md

@@ -1,10 +1,10 @@
 # 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)
+- **~142KB** gzipped (20KB JS + 122KB WASM)
 - **0** runtime dependencies
 - **<1ms** per keystroke
 - **100%** client-side
@@ -15,12 +15,14 @@ WriteTrack analyzes _how_ text was entered, not what was written. Human typing h
 npm install writetrack
 ```
 
-Then register for a free trial:
+Optionally, register for a free trial license:
 
 ```bash
-npx writetrack init
+npx writetrack init  # starts a 28-day trial and writes the key to .env
 ```
 
+A license is required for production domains. On `localhost`, all features work without a license key.
+
 ## Quick Start
 
 ```typescript
@@ -29,7 +31,6 @@ import { WriteTrack } from 'writetrack';
 const responseField = document.getElementById('response-field')!;
 const tracker = new WriteTrack({
   target: responseField,
-  license: process.env.WRITETRACK_LICENSE_KEY, // omit for localhost evaluation
 });
 
 tracker.start();
@@ -45,6 +46,51 @@ tracker.stop();
 
 Works with any text input, textarea, or contenteditable element. TypeScript definitions included.
 
+> **Note:** WriteTrack uses WASM, which requires an HTTP server — `file://` won't work. Any bundler (Vite, webpack, etc.) handles this automatically. For a no-bundler setup, see the [vanilla JS guide](https://writetrack.dev/docs/vanilla-js/).
+
+### React / Next.js
+
+```tsx
+import { useRef } from 'react';
+import { useWriteTrack } from 'writetrack/react';
+
+function ResponseForm() {
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const { tracker } = useWriteTrack(textareaRef);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (tracker) {
+      const data = tracker.getData();
+      const analysis = await tracker.getAnalysis();
+      console.log('Session:', data.quality, analysis);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <textarea ref={textareaRef} rows={10} />
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+For App Router, Server Actions, and dev-mode WASM setup, see the [Next.js guide](https://writetrack.dev/docs/nextjs/).
+
+## Production
+
+Add your license key to enable analysis on production domains:
+
+```typescript
+const tracker = new WriteTrack({
+  target: textarea,
+  license: process.env.WRITETRACK_LICENSE_KEY,
+});
+```
+
+On `localhost`, all features work without a key. See the [licensing guide](https://writetrack.dev/docs/license/) for trial setup, domain binding, and expiration details.
+
 ## Framework Integrations
 
 First-party bindings available as subpath exports:
@@ -58,7 +104,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 +123,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 +132,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 +182,54 @@ 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 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             |
+
+`getData()` returns a `WriteTrackDataSchema` with four top-level fields: `version`, `metadata` (session context, user/content IDs, custom fields), `session` (raw events and text), and `quality` (completeness score, validation status). See the [API reference](https://writetrack.dev/docs/api-reference#getdata) for the full shape.
+
+### Events
+
+The `on(event, handler)` method supports the following events:
+
+| Event        | Payload                                                          | Description                                                     |
+| ------------ | ---------------------------------------------------------------- | --------------------------------------------------------------- |
+| `change`     | `{ eventCount: number; keystrokeCount: number }`                 | Fires on any data mutation (keystroke, paste, selection, etc.)  |
+| `tick`       | `{ activeTime: number; totalTime: number; tracker: WriteTrack }` | Fires every ~1s while session is active                         |
+| `analysis`   | `SessionAnalysis`                                                | Fires when analysis updates (lazy-loads WASM on first listener) |
+| `ready`      | _(none)_                                                         | Fires when tracker is ready (late listeners auto-fire)          |
+| `wasm:ready` | _(none)_                                                         | Fires when WASM binary loads successfully                       |
+| `wasm:error` | `Error`                                                          | Fires if WASM binary fails to load                              |
+| `stop`       | _(none)_                                                         | Fires when `stop()` is called                                   |
+| `pipe:error` | `Error, WriteTrackSink`                                          | Fires when an output sink fails                                 |
+
+```typescript
+const unsub = tracker.on('change', ({ eventCount, keystrokeCount }) => {
+  console.log(`${keystrokeCount} keystrokes, ${eventCount} total events`);
+});
+// Later: unsub();
+```
 
 ### Static Methods
 
@@ -171,24 +258,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`
+**Functions:** `analyzeEvents`, `createSessionReport`, `formatIndicator`, `getHighResolutionTime`, `WriteTrackController`
 
-**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`, `BaseBindingOptions`, `OnTickData`, `ControllerState`, `ControllerOptions`
 
 ## 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