writetrack 0.11.0 → 0.12.0

package/README.md

@@ -4,7 +4,7 @@ Capture and analyze the writing process through keystroke dynamics.
 
 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 is an embeddable SDK that instruments text inputs to record _how_ tex
 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:
@@ -136,30 +182,54 @@ interface WriteTrackOptions {
 
 ### Methods
 
-| 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                |
+| 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
 
@@ -228,9 +298,9 @@ const tracker = createMockTracker({ analysis });
 
 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`, `WritingProcessAnalysis`, `WritingProcessSegment`, `PhaseTransition`, `WindowFeatures`, `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