writetrack 0.5.0 → 0.6.0

package/README.md

@@ -4,8 +4,8 @@ Detect AI-generated and pasted text 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.
 
-- **<16KB** gzipped
-- **0** dependencies
+- **~100KB** gzipped (15KB JS + 86KB WASM)
+- **0** runtime dependencies
 - **<1ms** per keystroke
 - **100%** client-side
 
@@ -15,28 +15,64 @@ WriteTrack analyzes _how_ text was entered, not what was written. Human typing h
 npm install writetrack
 ```
 
+Then register for a free trial:
+
+```bash
+npx writetrack init
+```
+
 ## Quick Start
 
 ```typescript
 import { WriteTrack } from 'writetrack';
 
 const responseField = document.getElementById('response-field')!;
-const tracker = new WriteTrack(responseField);
+const tracker = new WriteTrack({
+  target: responseField,
+  license: process.env.WRITETRACK_LICENSE_KEY, // omit for dev/demo mode
+});
 
 tracker.start();
 
 // User types...
 
 // Collect captured data
-const events = tracker.getRawEvents();
-const pastes = tracker.getClipboardEvents();
+const data = tracker.getData();
+const analysis = await tracker.getAnalysis();
 
 tracker.stop();
 ```
 
-Works with any text input, textarea, or contenteditable element. First-party integrations for React, Vue, TipTap, CKEditor 5, ProseMirror, and Quill. Output sinks for webhooks, Datadog, Segment, and OpenTelemetry. TypeScript definitions included.
+Works with any text input, textarea, or contenteditable element. TypeScript definitions included.
+
+## Framework Integrations
+
+First-party bindings available as subpath exports:
+
+```typescript
+import { useWriteTrack } from 'writetrack/react';
+import { useWriteTrack } from 'writetrack/vue';
+import { WriteTrackExtension } from 'writetrack/tiptap';
+import { WriteTrackPlugin } from 'writetrack/ckeditor';
+import { WriteTrackPlugin } from 'writetrack/prosemirror';
+import { WriteTrackModule } from 'writetrack/quill';
+```
+
+## Output Sinks
+
+Stream session data to your analytics stack via `.pipe()`:
 
-## What it captures
+```typescript
+import { webhook, datadog, segment, opentelemetry } from 'writetrack/pipes';
+
+tracker
+  .pipe(webhook({ url: '/api/writetrack' }))
+  .pipe(datadog({ client: dd }))
+  .pipe(segment({ client: analytics }))
+  .pipe(opentelemetry({ tracer }));
+```
+
+## What It Captures
 
 WriteTrack instruments your text inputs and records the behavioral signals behind every keystroke:
 
@@ -45,8 +81,9 @@ WriteTrack instruments your text inputs and records the behavioral signals behin
 - **Correction patterns** — backspaces, rewrites, hesitation
 - **Clipboard events** — paste, copy, cut with content and context
 - **Selection events** — text selections via mouse, keyboard, or programmatic
+- **Composition events** — IME input for CJK and other non-Latin scripts
 
-## Use cases
+## Use Cases
 
 **Education** — Flag essays that were pasted rather than composed. Give instructors behavioral context alongside content.
 
@@ -62,6 +99,20 @@ WriteTrack instruments your text inputs and records the behavioral signals behin
 new WriteTrack(options: WriteTrackOptions | HTMLElement)
 ```
 
+### Options
+
+```typescript
+interface WriteTrackOptions {
+  target: HTMLElement;
+  license?: string; // Omit for development/demo mode
+  userId?: string; // Opaque user identifier, included in output metadata
+  contentId?: string; // Opaque document identifier, included in output metadata
+  metadata?: Record<string, unknown>; // Arbitrary metadata, included in output
+  wasmUrl?: string; // Custom URL for the WASM analysis binary
+  persist?: boolean; // Enable IndexedDB persistence (requires contentId)
+}
+```
+
 ### Methods
 
 | Method                             | Returns                          | Description                            |
@@ -74,6 +125,7 @@ new WriteTrack(options: WriteTrackOptions | HTMLElement)
 | `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                 |
 | `getKeystrokeCount()`              | `number`                         | Total keystrokes captured              |
@@ -83,18 +135,36 @@ new WriteTrack(options: WriteTrackOptions | HTMLElement)
 | `on(event, handler)`               | `this`                           | Register an event listener             |
 | `isLicenseValid()`                 | `boolean`                        | Whether license is valid               |
 | `isLicenseValidated()`             | `boolean`                        | Whether license check has completed    |
-| `wasmReady`                        | `boolean`                        | Whether WASM module is loaded (getter) |
+| `isTargetDetached()`               | `boolean`                        | Whether the target element was removed |
+| `clearPersistedData()`             | `Promise<void>`                  | Clear IndexedDB persisted session      |
 
-### Types
+### Properties
+
+| Property    | Type            | Description                                 |
+| ----------- | --------------- | ------------------------------------------- |
+| `wasmReady` | `boolean`       | Whether WASM module is loaded (getter)      |
+| `ready`     | `Promise<void>` | Resolves when persisted session is restored |
+
+### Server-Side Analysis
+
+Analyze previously captured data without a DOM element:
 
 ```typescript
-interface WriteTrackOptions {
-  target: HTMLElement;
-  license?: string; // Omit for development/demo mode
-}
+import { analyzeEvents } from 'writetrack';
+
+const data = JSON.parse(savedSessionJson); // from your API, database, etc.
+const analysis = await analyzeEvents(data, {
+  licenseKey: process.env.WRITETRACK_LICENSE_KEY,
+});
 ```
 
-Full type definitions for `KeystrokeEvent`, `ClipboardEvent`, `SelectionEvent`, and `UndoRedoEvent` are included in the package.
+### Exported Types
+
+Full type definitions are included in the package:
+
+**Functions:** `analyzeEvents`, `formatIndicator`, `getHighResolutionTime`
+
+**Types:** `KeystrokeEvent`, `ClipboardEvent`, `SelectionEvent`, `UndoRedoEvent`, `CompositionEvent`, `ProgrammaticInsertionEvent`, `ModifierState`, `WriteTrackDataSchema`, `DataQualityMetrics`, `SessionMetadata`, `SessionAnalysis`, `SessionReport`, `IndicatorOutput`, `AnalyzeEventsOptions`, `WriteTrackSink`
 
 ## Browser Support
 
@@ -109,7 +179,11 @@ All features including license verification work at these versions. License vali
 
 ## Privacy
 
-WriteTrack runs entirely client-side. Keystroke data never leaves the browser. No servers, no tracking, no external requests.
+WriteTrack runs entirely client-side. No servers, no tracking, no external requests. Event data (including paste content and selected text) stays in the browser unless you explicitly export it via `getData()` or an output sink.
+
+## Documentation
+
+Full documentation at [writetrack.dev/docs](https://writetrack.dev/docs).
 
 ## License