writetrack 0.1.0

package/dist/react/index.d.ts

@@ -0,0 +1,326 @@
+import { RefObject } from 'react';
+
+/**
+ * Raw Event Data Structures
+ *
+ * Defines the structure for raw input events collected during typing sessions.
+ * This is the foundation layer containing unprocessed user interaction data.
+ */
+/**
+ * Raw session data containing all collected events
+ */
+interface RawEventData {
+    /** Primary keystroke events */
+    events: KeystrokeEvent[];
+    /** Clipboard operation events (optional) */
+    clipboardEvents?: ClipboardEvent[];
+    /** Undo/redo operation events (optional) */
+    undoRedoEvents?: UndoRedoEvent[];
+    /** Text selection events (optional) */
+    selectionEvents?: SelectionEvent[];
+    /** Final text that was typed */
+    rawText: string;
+    /** Session start time (unix timestamp) */
+    sessionStartTime: number;
+    /** Session end time (unix timestamp) */
+    sessionEndTime: number;
+}
+/**
+ * Individual keystroke event
+ */
+interface KeystrokeEvent {
+    /** Key identifier (character or key name) */
+    key: string;
+    /** Physical key code */
+    code: string;
+    /** Event type */
+    type: 'keydown' | 'keyup';
+    /** High-precision timestamp (performance.now()) */
+    timestamp: number;
+    /** Key hold duration (for keyup events) */
+    dwellTime?: number;
+    /** Time to next key press (for keydown events) */
+    flightTime?: number;
+    /** Whether this keystroke was part of a correction */
+    isCorrection?: boolean;
+    /** Whether this keystroke was part of a typing burst */
+    isBurst?: boolean;
+    /** Window focus state at time of keystroke */
+    windowFocused: boolean;
+    /** Time since last mouse interaction */
+    timeSinceLastMouse: number;
+    /** Character position in text at time of keystroke */
+    cursorPosition?: number;
+    /** Modifier key states */
+    modifiers?: ModifierState;
+}
+/**
+ * Modifier key states
+ */
+interface ModifierState {
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+}
+/**
+ * Clipboard operation event
+ */
+interface ClipboardEvent {
+    /** Clipboard operation type */
+    type: 'copy' | 'paste' | 'cut';
+    /** Event timestamp */
+    timestamp: number;
+    /** Text position where operation occurred */
+    position: number;
+    /** Length of text affected */
+    length: number;
+    /** Keyboard shortcut used */
+    shortcut: string;
+    /** Actual clipboard content (optional for privacy) */
+    content?: string;
+    /** Text state before operation (optional) */
+    beforeText?: string;
+    /** Text state after operation (optional) */
+    afterText?: string;
+    /** Text that was replaced by paste (optional) */
+    replacedText?: string;
+    /** Range of text replaced by paste (optional) */
+    replacedRange?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * Text selection event
+ */
+interface SelectionEvent {
+    /** Event type */
+    type: 'select';
+    /** Event timestamp */
+    timestamp: number;
+    /** Start position of selection */
+    startPosition: number;
+    /** End position of selection */
+    endPosition: number;
+    /** Length of selected text */
+    selectedLength: number;
+    /** Selected text content (optional for privacy) */
+    selectedText?: string;
+    /** How the selection was made */
+    method: 'mouse' | 'keyboard' | 'programmatic';
+}
+/**
+ * Undo/Redo operation event
+ */
+interface UndoRedoEvent {
+    /** Operation type */
+    type: 'undo' | 'redo';
+    /** Event timestamp */
+    timestamp: number;
+    /** Keyboard shortcut used */
+    shortcut: string;
+    /** Text state before operation */
+    beforeText: string;
+    /** Text state after operation */
+    afterText: string;
+}
+
+/**
+ * Session Metadata Data Structures
+ *
+ * Defines metadata for the capture session context.
+ */
+/**
+ * Session metadata returned by getData()
+ */
+interface SessionMetadata {
+    /** Tool identification and version */
+    tool: ToolInfo;
+    /** Target element type (e.g., 'textarea', 'input', 'div') */
+    targetElement: string;
+    /** Collection timestamp (ISO8601) */
+    timestamp: string;
+    /** Session duration in milliseconds */
+    duration: number;
+}
+/**
+ * Tool identification
+ */
+interface ToolInfo {
+    /** Tool name */
+    name: string;
+    /** Tool version */
+    version: string;
+    /** Tool category (internal use — set by training pipeline, not capture SDK) */
+    category?: 'human' | 'selenium' | 'playwright' | 'puppeteer' | 'cypress' | 'webdriverio' | 'other';
+}
+
+/**
+ * WriteTrack Data Schema v2.0.0 - Main Schema Definition
+ *
+ * This is the unified, versioned schema for all WriteTrack data structures.
+ * It provides a single source of truth for data formats across the entire system.
+ */
+
+/**
+ * Main WriteTrack Data Schema Interface
+ * This is the top-level structure for all WriteTrack data exports
+ */
+interface WriteTrackDataSchema {
+    /** Schema version for compatibility and migration */
+    version: '2.0.0';
+    /** Session metadata */
+    metadata: SessionMetadata;
+    /** Raw session data (keystrokes, clipboard, selection events) */
+    session: RawEventData;
+    /** Data quality metrics and validation status */
+    quality: DataQualityMetrics;
+    /** True when data was captured without a valid license (production use) */
+    unlicensed?: boolean;
+}
+/**
+ * Data Quality Assessment
+ */
+interface DataQualityMetrics {
+    /** Overall data quality score (0-1) */
+    overallScore: number;
+    /** Data completeness percentage */
+    completeness: number;
+    /** Event sequence consistency validation */
+    sequenceValid: boolean;
+    /** Timing data integrity status */
+    timingValid: boolean;
+    /** Session duration in milliseconds */
+    sessionDuration: number;
+    /** Total number of events collected */
+    eventCount: number;
+    /** Quality assessment level */
+    qualityLevel: 'POOR' | 'FAIR' | 'GOOD' | 'EXCELLENT';
+    /** Quality issues identified */
+    issues: string[];
+    /** Validation timestamp */
+    validatedAt: string;
+}
+
+interface WriteTrackOptions {
+    target: HTMLElement;
+    license?: string;
+}
+declare class WriteTrack {
+    protected keystrokeEvents: KeystrokeEvent[];
+    protected clipboardEvents: ClipboardEvent[];
+    protected undoRedoEvents: UndoRedoEvent[];
+    protected selectionEvents: SelectionEvent[];
+    private pendingKeydowns;
+    protected lastMouseActivity: number;
+    protected sessionStartTime: number;
+    protected lastKeyTime: number;
+    protected lastKeyUpTime: number;
+    protected repeatedKeyTracker: Map<string, number[]>;
+    private focusStartTime;
+    private lastSelection;
+    protected readonly BURST_THRESHOLD = 150;
+    protected readonly PAUSE_THRESHOLD = 1000;
+    protected readonly CORRECTION_KEYS: Set<string>;
+    private readonly targetType;
+    protected readonly target: HTMLElement;
+    private readonly license?;
+    /**
+     * Create a WriteTrack instance
+     * @param optionsOrTarget - Either an HTMLElement (demo mode) or WriteTrackOptions object
+     */
+    constructor(optionsOrTarget: WriteTrackOptions | HTMLElement);
+    private validateLicenseAsync;
+    private setupEventListeners;
+    /**
+     * Technique 6: Observe target's parent for childList changes.
+     * If target is removed from DOM, stop recording.
+     */
+    private setupTargetObserver;
+    private isRecordingEnabled;
+    private recordKeydown;
+    private recordKeyup;
+    private recordMouseActivity;
+    private recordWindowFocus;
+    private detectKeyboardShortcuts;
+    private recordClipboardEvent;
+    private recordSelection;
+    private checkSelectionAfterMouse;
+    private recordSelectionChange;
+    private getSelection;
+    private getSelectedTextLength;
+    private recordVisibilityChange;
+    private getShortcutString;
+    private getCurrentCursorPosition;
+    private isMacPlatform;
+    private trackRepeatedKey;
+    /**
+     * Check if the license is valid
+     */
+    isLicenseValid(): boolean;
+    /**
+     * Check if license validation has completed
+     */
+    isLicenseValidated(): boolean;
+    /**
+     * Check if the target element was detached from the DOM
+     */
+    isTargetDetached(): boolean;
+    start(): void;
+    stop(): void;
+    getRawEvents(): KeystrokeEvent[];
+    getClipboardEvents(): ClipboardEvent[];
+    getUndoRedoEvents(): UndoRedoEvent[];
+    getSelectionEvents(): SelectionEvent[];
+    getSessionDuration(): number;
+    getKeystrokeCount(): number;
+    getText(): string;
+    getData(): WriteTrackDataSchema;
+}
+
+interface UseWriteTrackOptions {
+    /** Auto-start tracking when element is available (default: true) */
+    autoStart?: boolean;
+}
+interface UseWriteTrackReturn {
+    /** Reset the tracker and clear state */
+    reset: () => void;
+    /** Start tracking (if autoStart was false) */
+    start: () => void;
+    /** Stop tracking */
+    stop: () => void;
+    /** Whether the tracker is currently active */
+    isTracking: boolean;
+    /** Access to the underlying WriteTrack instance */
+    tracker: WriteTrack | null;
+}
+/**
+ * React hook for WriteTrack keystroke analysis
+ *
+ * @example
+ * ```tsx
+ * function EssayForm() {
+ *   const textareaRef = useRef<HTMLTextAreaElement>(null);
+ *   const { tracker, isTracking } = useWriteTrack(textareaRef);
+ *
+ *   const handleSubmit = (e: FormEvent) => {
+ *     e.preventDefault();
+ *     if (tracker) {
+ *       const features = tracker.getBehavioralFeatures();
+ *       console.log('Features:', features);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <textarea ref={textareaRef} />
+ *       <button type="submit">Submit</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+declare function useWriteTrack(ref: RefObject<HTMLElement | null>, options?: UseWriteTrackOptions): UseWriteTrackReturn;
+
+export { type UseWriteTrackOptions, type UseWriteTrackReturn, useWriteTrack };

package/dist/react/index.js

@@ -0,0 +1 @@
+import{useEffect as l,useRef as f,useCallback as s,useState as p}from"react";import{WriteTrack as a}from"writetrack";function T(e,o={}){let{autoStart:u=!0}=o,r=f(null),[t,c]=p(!1);l(()=>{if(e.current)return r.current=new a(e.current),u&&(r.current.start(),c(!0)),()=>{var n;(n=r.current)==null||n.stop(),r.current=null,c(!1)}},[e,u]);let i=s(()=>{r.current&&!t&&(r.current.start(),c(!0))},[t]),k=s(()=>{r.current&&t&&(r.current.stop(),c(!1))},[t]);return{reset:s(()=>{var n;e.current&&((n=r.current)==null||n.stop(),r.current=new a(e.current),t&&r.current.start())},[e,t]),start:i,stop:k,isTracking:t,tracker:r.current}}export{T as useWriteTrack};

package/dist/vue/index.d.ts

@@ -0,0 +1,328 @@
+import { Ref, ShallowRef } from 'vue';
+
+/**
+ * Raw Event Data Structures
+ *
+ * Defines the structure for raw input events collected during typing sessions.
+ * This is the foundation layer containing unprocessed user interaction data.
+ */
+/**
+ * Raw session data containing all collected events
+ */
+interface RawEventData {
+    /** Primary keystroke events */
+    events: KeystrokeEvent[];
+    /** Clipboard operation events (optional) */
+    clipboardEvents?: ClipboardEvent[];
+    /** Undo/redo operation events (optional) */
+    undoRedoEvents?: UndoRedoEvent[];
+    /** Text selection events (optional) */
+    selectionEvents?: SelectionEvent[];
+    /** Final text that was typed */
+    rawText: string;
+    /** Session start time (unix timestamp) */
+    sessionStartTime: number;
+    /** Session end time (unix timestamp) */
+    sessionEndTime: number;
+}
+/**
+ * Individual keystroke event
+ */
+interface KeystrokeEvent {
+    /** Key identifier (character or key name) */
+    key: string;
+    /** Physical key code */
+    code: string;
+    /** Event type */
+    type: 'keydown' | 'keyup';
+    /** High-precision timestamp (performance.now()) */
+    timestamp: number;
+    /** Key hold duration (for keyup events) */
+    dwellTime?: number;
+    /** Time to next key press (for keydown events) */
+    flightTime?: number;
+    /** Whether this keystroke was part of a correction */
+    isCorrection?: boolean;
+    /** Whether this keystroke was part of a typing burst */
+    isBurst?: boolean;
+    /** Window focus state at time of keystroke */
+    windowFocused: boolean;
+    /** Time since last mouse interaction */
+    timeSinceLastMouse: number;
+    /** Character position in text at time of keystroke */
+    cursorPosition?: number;
+    /** Modifier key states */
+    modifiers?: ModifierState;
+}
+/**
+ * Modifier key states
+ */
+interface ModifierState {
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+}
+/**
+ * Clipboard operation event
+ */
+interface ClipboardEvent {
+    /** Clipboard operation type */
+    type: 'copy' | 'paste' | 'cut';
+    /** Event timestamp */
+    timestamp: number;
+    /** Text position where operation occurred */
+    position: number;
+    /** Length of text affected */
+    length: number;
+    /** Keyboard shortcut used */
+    shortcut: string;
+    /** Actual clipboard content (optional for privacy) */
+    content?: string;
+    /** Text state before operation (optional) */
+    beforeText?: string;
+    /** Text state after operation (optional) */
+    afterText?: string;
+    /** Text that was replaced by paste (optional) */
+    replacedText?: string;
+    /** Range of text replaced by paste (optional) */
+    replacedRange?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * Text selection event
+ */
+interface SelectionEvent {
+    /** Event type */
+    type: 'select';
+    /** Event timestamp */
+    timestamp: number;
+    /** Start position of selection */
+    startPosition: number;
+    /** End position of selection */
+    endPosition: number;
+    /** Length of selected text */
+    selectedLength: number;
+    /** Selected text content (optional for privacy) */
+    selectedText?: string;
+    /** How the selection was made */
+    method: 'mouse' | 'keyboard' | 'programmatic';
+}
+/**
+ * Undo/Redo operation event
+ */
+interface UndoRedoEvent {
+    /** Operation type */
+    type: 'undo' | 'redo';
+    /** Event timestamp */
+    timestamp: number;
+    /** Keyboard shortcut used */
+    shortcut: string;
+    /** Text state before operation */
+    beforeText: string;
+    /** Text state after operation */
+    afterText: string;
+}
+
+/**
+ * Session Metadata Data Structures
+ *
+ * Defines metadata for the capture session context.
+ */
+/**
+ * Session metadata returned by getData()
+ */
+interface SessionMetadata {
+    /** Tool identification and version */
+    tool: ToolInfo;
+    /** Target element type (e.g., 'textarea', 'input', 'div') */
+    targetElement: string;
+    /** Collection timestamp (ISO8601) */
+    timestamp: string;
+    /** Session duration in milliseconds */
+    duration: number;
+}
+/**
+ * Tool identification
+ */
+interface ToolInfo {
+    /** Tool name */
+    name: string;
+    /** Tool version */
+    version: string;
+    /** Tool category (internal use — set by training pipeline, not capture SDK) */
+    category?: 'human' | 'selenium' | 'playwright' | 'puppeteer' | 'cypress' | 'webdriverio' | 'other';
+}
+
+/**
+ * WriteTrack Data Schema v2.0.0 - Main Schema Definition
+ *
+ * This is the unified, versioned schema for all WriteTrack data structures.
+ * It provides a single source of truth for data formats across the entire system.
+ */
+
+/**
+ * Main WriteTrack Data Schema Interface
+ * This is the top-level structure for all WriteTrack data exports
+ */
+interface WriteTrackDataSchema {
+    /** Schema version for compatibility and migration */
+    version: '2.0.0';
+    /** Session metadata */
+    metadata: SessionMetadata;
+    /** Raw session data (keystrokes, clipboard, selection events) */
+    session: RawEventData;
+    /** Data quality metrics and validation status */
+    quality: DataQualityMetrics;
+    /** True when data was captured without a valid license (production use) */
+    unlicensed?: boolean;
+}
+/**
+ * Data Quality Assessment
+ */
+interface DataQualityMetrics {
+    /** Overall data quality score (0-1) */
+    overallScore: number;
+    /** Data completeness percentage */
+    completeness: number;
+    /** Event sequence consistency validation */
+    sequenceValid: boolean;
+    /** Timing data integrity status */
+    timingValid: boolean;
+    /** Session duration in milliseconds */
+    sessionDuration: number;
+    /** Total number of events collected */
+    eventCount: number;
+    /** Quality assessment level */
+    qualityLevel: 'POOR' | 'FAIR' | 'GOOD' | 'EXCELLENT';
+    /** Quality issues identified */
+    issues: string[];
+    /** Validation timestamp */
+    validatedAt: string;
+}
+
+interface WriteTrackOptions {
+    target: HTMLElement;
+    license?: string;
+}
+declare class WriteTrack {
+    protected keystrokeEvents: KeystrokeEvent[];
+    protected clipboardEvents: ClipboardEvent[];
+    protected undoRedoEvents: UndoRedoEvent[];
+    protected selectionEvents: SelectionEvent[];
+    private pendingKeydowns;
+    protected lastMouseActivity: number;
+    protected sessionStartTime: number;
+    protected lastKeyTime: number;
+    protected lastKeyUpTime: number;
+    protected repeatedKeyTracker: Map<string, number[]>;
+    private focusStartTime;
+    private lastSelection;
+    protected readonly BURST_THRESHOLD = 150;
+    protected readonly PAUSE_THRESHOLD = 1000;
+    protected readonly CORRECTION_KEYS: Set<string>;
+    private readonly targetType;
+    protected readonly target: HTMLElement;
+    private readonly license?;
+    /**
+     * Create a WriteTrack instance
+     * @param optionsOrTarget - Either an HTMLElement (demo mode) or WriteTrackOptions object
+     */
+    constructor(optionsOrTarget: WriteTrackOptions | HTMLElement);
+    private validateLicenseAsync;
+    private setupEventListeners;
+    /**
+     * Technique 6: Observe target's parent for childList changes.
+     * If target is removed from DOM, stop recording.
+     */
+    private setupTargetObserver;
+    private isRecordingEnabled;
+    private recordKeydown;
+    private recordKeyup;
+    private recordMouseActivity;
+    private recordWindowFocus;
+    private detectKeyboardShortcuts;
+    private recordClipboardEvent;
+    private recordSelection;
+    private checkSelectionAfterMouse;
+    private recordSelectionChange;
+    private getSelection;
+    private getSelectedTextLength;
+    private recordVisibilityChange;
+    private getShortcutString;
+    private getCurrentCursorPosition;
+    private isMacPlatform;
+    private trackRepeatedKey;
+    /**
+     * Check if the license is valid
+     */
+    isLicenseValid(): boolean;
+    /**
+     * Check if license validation has completed
+     */
+    isLicenseValidated(): boolean;
+    /**
+     * Check if the target element was detached from the DOM
+     */
+    isTargetDetached(): boolean;
+    start(): void;
+    stop(): void;
+    getRawEvents(): KeystrokeEvent[];
+    getClipboardEvents(): ClipboardEvent[];
+    getUndoRedoEvents(): UndoRedoEvent[];
+    getSelectionEvents(): SelectionEvent[];
+    getSessionDuration(): number;
+    getKeystrokeCount(): number;
+    getText(): string;
+    getData(): WriteTrackDataSchema;
+}
+
+interface UseWriteTrackOptions {
+    /** Auto-start tracking when element is available (default: true) */
+    autoStart?: boolean;
+}
+interface UseWriteTrackReturn {
+    /** Reset the tracker and clear state */
+    reset: () => void;
+    /** Start tracking (if autoStart was false) */
+    start: () => void;
+    /** Stop tracking */
+    stop: () => void;
+    /** Whether the tracker is currently active */
+    isTracking: Ref<boolean>;
+    /** Access to the underlying WriteTrack instance */
+    tracker: ShallowRef<WriteTrack | null>;
+}
+/**
+ * Vue 3 composable for WriteTrack keystroke analysis
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { ref } from 'vue';
+ * import { useWriteTrack } from 'writetrack/vue';
+ *
+ * const textareaRef = ref<HTMLTextAreaElement | null>(null);
+ * const { tracker, isTracking } = useWriteTrack(textareaRef);
+ *
+ * function handleSubmit() {
+ *   if (tracker.value) {
+ *     const features = tracker.value.getBehavioralFeatures();
+ *     console.log('Features:', features);
+ *   }
+ * }
+ * </script>
+ *
+ * <template>
+ *   <form @submit.prevent="handleSubmit">
+ *     <textarea ref="textareaRef" />
+ *     <button type="submit">Submit</button>
+ *   </form>
+ * </template>
+ * ```
+ */
+declare function useWriteTrack(elementRef: Ref<HTMLElement | null>, options?: UseWriteTrackOptions): UseWriteTrackReturn;
+
+export { type UseWriteTrackOptions, type UseWriteTrackReturn, useWriteTrack };

package/dist/vue/index.js

@@ -0,0 +1 @@
+import{ref as v,onMounted as k,onUnmounted as p,shallowRef as T}from"vue";import{WriteTrack as u}from"writetrack";function W(r,o={}){let{autoStart:n=!0}=o,e=T(null),t=v(!1);function l(){r.value&&(e.value=new u(r.value),n&&(e.value.start(),t.value=!0))}function a(){e.value&&(e.value.stop(),e.value=null,t.value=!1)}k(()=>{l()}),p(()=>{a()});function i(){e.value&&!t.value&&(e.value.start(),t.value=!0)}function s(){e.value&&t.value&&(e.value.stop(),t.value=!1)}function c(){if(!r.value)return;let f=t.value;a(),e.value=new u(r.value),f&&(e.value.start(),t.value=!0)}return{reset:c,start:i,stop:s,isTracking:t,tracker:e}}export{W as useWriteTrack};