@staticcanvas/typeflow 0.34.0

package/src/typeflow-debug.d.ts

@@ -0,0 +1,34 @@
+/**
+ * TypeFlow Debug - Diagnostic Tracing and LogCAD Integration.
+ */
+export interface TypeFlowDebugOptions {
+  logcad?: boolean;
+  console?: boolean;
+  maxHistory?: number;
+  traceFrames?: boolean;
+}
+
+export interface TypeFlowDebugEntry {
+  timestamp: string;
+  level: 'info' | 'warn' | 'error' | 'debug' | 'trace';
+  message: string;
+  data: Record<string, any>;
+}
+
+export class TypeFlowDebug {
+  static enabled: boolean;
+  static options: TypeFlowDebugOptions;
+  static history: TypeFlowDebugEntry[];
+
+  static enable(options?: TypeFlowDebugOptions): void;
+  static disable(): void;
+  static log(
+    level: 'info' | 'warn' | 'error' | 'debug' | 'trace',
+    message: string,
+    data?: Record<string, any>
+  ): void;
+  static trace<T>(controller: T, label?: string): T;
+  static getHistory(): TypeFlowDebugEntry[];
+  static clearHistory(): void;
+  static exportLog(): string;
+}

package/src/typeflow-debug.js

@@ -0,0 +1,223 @@
+/** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+ * @description TypeFlow Debug - Diagnostic Tracing and LogCAD Integration.
+ * Provides lifecycle telemetry, animation step timings, event hooks, and structured
+ * logger integration for TypeFlow applications.
+ *
+ * @module @staticcanvas/typeflow/debug
+ */
+
+export class TypeFlowDebug {
+  static enabled = false;
+  static options = {
+    logcad: true,
+    console: true,
+    maxHistory: 200,
+    traceFrames: false,
+  };
+  static history = [];
+  static originalType = null;
+  static originalErase = null;
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Enables diagnostic telemetry tracing across TypeFlow animation lifecycles.
+   * @param {Object} [opts={}] - Configuration options for the debug session.
+   * @returns {void}
+   *
+   * -------------
+   *
+   * @Properties
+   * @param {boolean} [opts.logcad=true] - Whether to route logs through @staticcanvas/logcad if available.
+   * @param {boolean} [opts.console=true] - Whether to output styled colored logs to the browser console.
+   * @param {number}  [opts.maxHistory=200] - Maximum number of recent log entries to retain in memory.
+   * @param {boolean} [opts.traceFrames=false] - Whether to log every individual frame render tick.
+   *
+   * -------------
+   *
+   * @example
+   *
+   * // Enable debugging with default settings
+   * TypeFlowDebug.enable();
+   *
+   * // Enable with custom history size and disabled console output
+   * TypeFlowDebug.enable({
+   *   logcad: true,
+   *   console: false,
+   *   maxHistory: 500,
+   * });
+   */
+  static enable(opts = {}) {
+    TypeFlowDebug.options = { ...TypeFlowDebug.options, ...opts };
+    TypeFlowDebug.enabled = true;
+    TypeFlowDebug.log('info', 'TypeFlowDebug enabled', { options: TypeFlowDebug.options });
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Disables diagnostic tracing and halts active logging.
+   * @returns {void}
+   *
+   * -------------
+   *
+   * @example
+   * TypeFlowDebug.disable();
+   */
+  static disable() {
+    TypeFlowDebug.enabled = false;
+    TypeFlowDebug.log('info', 'TypeFlowDebug disabled');
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Internal logging bridge supporting @staticcanvas/logcad and styled console messages.
+   * @param {'info' | 'warn' | 'error' | 'debug' | 'trace'} level - Severity level of the log entry.
+   * @param {string} message - Human-readable summary of the event.
+   * @param {Object} [data={}] - Contextual payload data to associate with the event.
+   * @returns {void}
+   *
+   * -------------
+   *
+   * @Properties
+   * @param {string} level - Severity level ('info', 'warn', 'error', 'debug', 'trace').
+   * @param {string} message - The message text to record.
+   * @param {Object} [data={}] - Arbitrary metadata object (timings, diffs, controllers).
+   *
+   * -------------
+   *
+   * @example
+   * TypeFlowDebug.log('info', 'Sequence step completed', { step: 1, duration: 45 });
+   * TypeFlowDebug.log('warn', 'Frame drop detected', { expectedMs: 16, actualMs: 34 });
+   */
+  static log(level, message, data = {}) {
+    if (!TypeFlowDebug.enabled && level !== 'error') return;
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      data,
+    };
+
+    TypeFlowDebug.history.push(entry);
+    if (TypeFlowDebug.history.length > TypeFlowDebug.options.maxHistory) {
+      TypeFlowDebug.history.shift();
+    }
+
+    // 1. Integration with @staticcanvas/logcad if available globally or via module
+    if (TypeFlowDebug.options.logcad && typeof globalThis !== 'undefined' && globalThis.logcad) {
+      try {
+        const logger = globalThis.logcad.getLogger?.('TypeFlow') || globalThis.logcad;
+        if (typeof logger[level] === 'function') {
+          logger[level](message, data);
+          return;
+        }
+      } catch {
+        // Fallback to console
+      }
+    }
+
+    // 2. Structured fallback console output with CSS colors
+    if (TypeFlowDebug.options.console && typeof console !== 'undefined') {
+      const colors = {
+        info: 'color: #38bdf8; font-weight: bold;',
+        warn: 'color: #f59e0b; font-weight: bold;',
+        error: 'color: #ef4444; font-weight: bold;',
+        debug: 'color: #ff6b2b; font-weight: bold;',
+        trace: 'color: #94a3b8; font-weight: normal;',
+      };
+
+      const tag = `%c[TypeFlow:${level.toUpperCase()}]`;
+      const style = colors[level] || colors.info;
+
+      if (Object.keys(data).length > 0) {
+        console[level === 'trace' ? 'debug' : level] || console.log(tag, style, message, data);
+      } else {
+        console[level === 'trace' ? 'debug' : level] || console.log(tag, style, message);
+      }
+    }
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Tracks a specific TypeFlow animation controller and logs lifecycle events upon resolution or rejection.
+   * @param {Object} controller - Active TypeFlow controller instance.
+   * @param {string} [label='Animation'] - Descriptive name for the tracked target.
+   * @returns {Object} The passed-in controller for chaining.
+   *
+   * -------------
+   *
+   * @Properties
+   * @param {Object} controller - The TypeFlow controller returned by TypeFlow.type() / TypeFlow.erase().
+   * @param {Promise} controller.promise - The underlying completion promise.
+   * @param {Function} controller.stop - Method to abort the animation.
+   * @param {string} [label='Animation'] - Label displayed in log output.
+   *
+   * -------------
+   *
+   * @example
+   * const ctrl = TypeFlow.type('#headline', 'Hello World');
+   * TypeFlowDebug.trace(ctrl, 'Hero Headline');
+   */
+  static trace(controller, label = 'Animation') {
+    if (!TypeFlowDebug.enabled || !controller) return controller;
+
+    const start = performance.now();
+    TypeFlowDebug.log('debug', `[${label}] Started animation`, { controller });
+
+    if (controller.promise) {
+      controller.promise.then(
+        (res) => {
+          const duration = (performance.now() - start).toFixed(2);
+          TypeFlowDebug.log('info', `[${label}] Resolved (${duration}ms)`, res);
+        },
+        (err) => {
+          const duration = (performance.now() - start).toFixed(2);
+          TypeFlowDebug.log('error', `[${label}] Rejected (${duration}ms)`, err);
+        }
+      );
+    }
+
+    return controller;
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Returns a shallow copy of the recorded event history.
+   * @returns {Array<Object>} List of history entry objects.
+   *
+   * -------------
+   *
+   * @example
+   * const history = TypeFlowDebug.getHistory();
+   * console.log('Total recorded events:', history.length);
+   */
+  static getHistory() {
+    return [...TypeFlowDebug.history];
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Clears the current event history ring buffer.
+   * @returns {void}
+   *
+   * -------------
+   *
+   * @example
+   * TypeFlowDebug.clearHistory();
+   */
+  static clearHistory() {
+    TypeFlowDebug.history = [];
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Exports recorded telemetry event history as a formatted JSON string.
+   * @returns {string} Serialized JSON representation of debug history.
+   *
+   * -------------
+   *
+   * @example
+   * const jsonReport = TypeFlowDebug.exportLog();
+   * navigator.clipboard.writeText(jsonReport);
+   */
+  static exportLog() {
+    return JSON.stringify(TypeFlowDebug.history, null, 2);
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.TypeFlowDebug = TypeFlowDebug;
+}

package/src/typeflow-extchars.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TypeFlow ExtChars - Extended Unicode Glyph Presets & Scramble Pools.
+ */
+export const EXT_CHARSETS: {
+  hieroglyphs: string;
+  runic: string;
+  ogham: string;
+  coptic: string;
+  katakana: string;
+  cyberMatrix: string;
+  blocks: string;
+  boxDrawing: string;
+  mathSymbols: string;
+  braille: string;
+  astronomical: string;
+  geometric: string;
+  glitch: string;
+};
+
+export class TypeFlowExtChars {
+  static charsets: Record<string, string>;
+  static getCharset(name: string): string;
+  static registerCharset(name: string, glyphs: string): void;
+  static combineCharsets(...names: string[]): string;
+  static randomGlyph(charsetOrName: string): string;
+}
+
+export function getExtendedCharset(name: string): string;

package/src/typeflow-extchars.js

@@ -0,0 +1,132 @@
+/** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+ * @description TypeFlow ExtChars - Extended Unicode Glyph Presets & Scramble Pools.
+ * Provides specialized ancient alphabets, mathematical operators, Katakana,
+ * box-drawing frames, astrological runes, and cyber glitch character sets.
+ *
+ * @module @staticcanvas/typeflow/extchars
+ */
+
+export const EXT_CHARSETS = {
+  // Ancient & Sacred Scripts
+  hieroglyphs: '𓀀𓀁𓀂𓀃𓀄𓀅𓀆𓀇𓀈𓀉𓀊𓀋𓀌𓀍𓀎𓀏𓀐𓀑𓀒𓀓𓀔𓀕𓀖𓀗𓀘𓀙𓀚𓀛𓀜𓀝𓀞𓀟𓀠𓀡𓀢𓀣𓀤𓀥𓀦𓀧𓀨𓀩𓀪𓀫𓀬𓀭𓀮𓀯𓀰𓀱𓀲𓀳𓀴𓀵𓀶𓀷𓀸𓀹𓀺𓀻',
+  runic: 'ᚠᚡᚢᚣᚤᚥᚦᚧᚨᚩᚪᚫᚬᚭᚮᚯᚰᚱᚲᚳᚴᚵᚶᚷᚸᚹᚺᚻᚼᚽᚾᚿᛀᛁᛂᛃᛄᛅᛆᛇᛈᛉᛊᛋᛌᛍᛎᛏᛐᛑᛒᛓᛔᛕᛖᛗᛘᛙᛚᛛᛜᛝᛞᛟᛠᛡᛢᛣᛤᛥᛦᛧᛨᛩᛪ',
+  ogham: 'ᚁᚂᚃᚄᚅᚆᚇᚈᚉᚊᚋᚌᚍᚎᚏᚐᚑᚒᚓᚔᚕᚖᚗᚘᚙᚚ',
+  coptic: 'ⲀⲂⲄⲆⲈⲊⲌⲎⲐⲒⲔⲖⲘⲚⲜⲞⲠⲢⲤⲦⲨPhiⲬⲮⲰϢϤϦϨϪϬϮ',
+
+  // Cyber & Terminal
+  katakana: 'ｦｧｨｩｪｫｬｭｮｯｰｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝ',
+  cyberMatrix: '01010101_#@!<>[]{}/*+=~-ｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄ01',
+  blocks: '█▓▒░▀▄▌▐■□▢▣▤▥▦▧▨▩',
+  boxDrawing:
+    '─━│┃┄┅┆┇┈┉┊┋┌┍┎┏┐┑┒┓└┕┖┗┘┙┚┛├┝┞┟┠┡┢┣┤┥┦┧┨┩┪┫┬┭┮┯┰┱┲┳┴┵┶┷┸┹┺┻┼┽┾┿╀╁╂╃╄╅╆╇╈╉╊╋═║╔╗╚╝╠╣╦╩╬',
+
+  // Mathematical & Technical
+  mathSymbols:
+    '∀∁∂∃∄∅∆∇∈∉∊∋∌∍∎∏∐∑−∓∔∕∖∗∘∙√∛∜∝∞∟∠∡∢∣∤∥∦∧∨∩∪∫∬∭∮∯∰∱∲∳∴∵∶∷∸∹∺∻∼∽∾∿≀≁≂≃≄≅≆≇≈≉≊≋≌≍≎≏≐≑≒≓≔≕≖≗≘≙≚≛≜≝≞≟≠≡≢≣≤≥≦≧≨≩≪≫≬≭≮≯',
+  braille: '⠁⠂⠃⠄⠅⠆⠇⠈⠉⠊⠋⠌⠍⠎⠏⠐⠑⠒⠓⠔⠕⠖⠗⠘⠙⠚⠛⠜⠝⠞⠟⠠⠡⠢⠣⠤⠥⠦⠧⠨⠩⠪⠫⠬⠭⠮⠯⠰⠱⠲⠳⠴⠵⠶⠷⠸⠹⠺⠻⠼⠽⠾⠿',
+  astronomical: '☉☽☿♀♁♂♃♄♅♆♇♈♉♊♋♌♍♎♏♐♑♒♓☄★☆⚡',
+  geometric: '▲▼◀▶▲▼◀▶◆◇◈◉◊○●◎◐◑◒◓◔◕◖◗◘◙◜◝◞◟◠◡◢◣◤◥',
+
+  // Glitch
+  glitch: '!<>-_\\/[]{}—=+*^?#________̷̸̡̢̧̨̛̖̗̘̙̜̝̞̟̠',
+};
+
+export class TypeFlowExtChars {
+  static charsets = { ...EXT_CHARSETS };
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Retrieves a character set string by preset name.
+   * @param {string} name - The charset identifier ('hieroglyphs', 'runic', 'ogham', 'coptic', 'katakana', 'boxDrawing', 'mathSymbols', 'braille', 'astronomical', 'geometric', 'glitch').
+   * @returns {string} String of glyph characters.
+   *
+   * -------------
+   *
+   * @Properties
+   * @param {string} name - Name of the charset.
+   *
+   * -------------
+   *
+   * @example
+   * const runes = TypeFlowExtChars.getCharset('runic');
+   * console.log('Runic runes:', runes);
+   */
+  static getCharset(name) {
+    return TypeFlowExtChars.charsets[String(name).toLowerCase()] || EXT_CHARSETS.cyberMatrix;
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Registers a new custom charset preset globally.
+   * @param {string} name - Unique identifier for the custom charset.
+   * @param {string} glyphs - Pool of characters to associate with this preset.
+   * @returns {void}
+   *
+   * -------------
+   *
+   * @Properties
+   * @param {string} name - Identifier name.
+   * @param {string} glyphs - String of characters.
+   *
+   * -------------
+   *
+   * @example
+   * TypeFlowExtChars.registerCharset('alchemy', '🜁🜂🜃🜄🜅🜆🜇🜈🜉🜊');
+   * const alchemy = TypeFlowExtChars.getCharset('alchemy');
+   */
+  static registerCharset(name, glyphs) {
+    if (typeof name === 'string' && typeof glyphs === 'string') {
+      TypeFlowExtChars.charsets[name.toLowerCase()] = glyphs;
+    }
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Combines multiple charsets into a single merged pool.
+   * @param {...string} names - Charset names to concatenate.
+   * @returns {string} Merged character string.
+   *
+   * -------------
+   *
+   * @example
+   * const cyberRunes = TypeFlowExtChars.combineCharsets('cyberMatrix', 'runic', 'katakana');
+   */
+  static combineCharsets(...names) {
+    return names.map((n) => TypeFlowExtChars.getCharset(n)).join('');
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Selects a random single glyph from a charset string or preset name.
+   * @param {string} charsetOrName - Charset string or registered name.
+   * @returns {string} Random single character glyph.
+   *
+   * -------------
+   *
+   * @example
+   * const rune = TypeFlowExtChars.randomGlyph('runic');
+   */
+  static randomGlyph(charsetOrName) {
+    const pool =
+      TypeFlowExtChars.charsets[charsetOrName] || charsetOrName || EXT_CHARSETS.cyberMatrix;
+    const chars = Array.from(pool);
+    return chars[Math.floor(Math.random() * chars.length)] || '#';
+  }
+}
+
+/** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+ * @description Helper function returning an extended charset string by name.
+ * @param {string} name - Charset identifier.
+ * @returns {string}
+ *
+ * -------------
+ *
+ * @example
+ * import { getExtendedCharset } from '@staticcanvas/typeflow/extchars';
+ * const hieroglyphs = getExtendedCharset('hieroglyphs');
+ */
+export function getExtendedCharset(name) {
+  return TypeFlowExtChars.getCharset(name);
+}
+
+if (typeof window !== 'undefined') {
+  window.TypeFlowExtChars = TypeFlowExtChars;
+  window.EXT_CHARSETS = EXT_CHARSETS;
+  window.getExtendedCharset = getExtendedCharset;
+}

package/src/typeflow-keystroke.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TypeFlow Keystroke - Human Cadence, Finger Distance & Typo Simulation Engine.
+ */
+export interface KeystrokeDelayOptions {
+  baseSpeed?: number;
+  fatigueIndex?: number;
+  fatigueRate?: number;
+}
+
+export interface HumanizeOptions {
+  errorRate?: number;
+  hesitationMs?: number;
+}
+
+export interface HumanizeAction {
+  type: 'type' | 'erase' | 'pause';
+  char?: string;
+  count?: number;
+  duration?: number;
+  isTypo?: boolean;
+}
+
+export function calculateKeyDistance(keyA: string, keyB: string): number;
+
+export class TypeFlowKeystroke {
+  static getDelay(prevChar: string, nextChar: string, options?: KeystrokeDelayOptions): number;
+  static humanize(text: string, options?: HumanizeOptions): HumanizeAction[];
+}

package/src/typeflow-keystroke.js

@@ -0,0 +1,220 @@
+/** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+ * @description TypeFlow Keystroke - Human Cadence, Finger Distance & Typo Simulation Engine.
+ * Models physical QWERTY coordinate finger travel, burstiness, thought pauses,
+ * fatigue deceleration, and realistic typo injection with backspace auto-correction.
+ *
+ * @module @staticcanvas/typeflow/keystroke
+ */
+
+// QWERTY keyboard physical coordinates (row, col)
+const QWERTY_COORDS = {
+  '`': [0, 0],
+  1: [0, 1],
+  2: [0, 2],
+  3: [0, 3],
+  4: [0, 4],
+  5: [0, 5],
+  6: [0, 6],
+  7: [0, 7],
+  8: [0, 8],
+  9: [0, 9],
+  0: [0, 10],
+  '-': [0, 11],
+  '=': [0, 12],
+  q: [1, 1.5],
+  w: [1, 2.5],
+  e: [1, 3.5],
+  r: [1, 4.5],
+  t: [1, 5.5],
+  y: [1, 6.5],
+  u: [1, 7.5],
+  i: [1, 8.5],
+  o: [1, 9.5],
+  p: [1, 10.5],
+  '[': [1, 11.5],
+  ']': [1, 12.5],
+  a: [2, 1.8],
+  s: [2, 2.8],
+  d: [2, 3.8],
+  f: [2, 4.8],
+  g: [2, 5.8],
+  h: [2, 6.8],
+  j: [2, 7.8],
+  k: [2, 8.8],
+  l: [2, 9.8],
+  ';': [2, 10.8],
+  "'": [2, 11.8],
+  z: [3, 2.2],
+  x: [3, 3.2],
+  c: [3, 4.2],
+  v: [3, 5.2],
+  b: [3, 6.2],
+  n: [3, 7.2],
+  m: [3, 8.2],
+  ',': [3, 9.2],
+  '.': [3, 10.2],
+  '/': [3, 11.2],
+  ' ': [4, 6.0],
+};
+
+// Adjacent key neighborhood for realistic typo generation
+const QWERTY_NEIGHBORS = {
+  a: ['s', 'q', 'z', 'w'],
+  b: ['v', 'g', 'h', 'n'],
+  c: ['x', 'd', 'f', 'v'],
+  d: ['s', 'e', 'r', 'f', 'c', 'x'],
+  e: ['w', 's', 'd', 'r'],
+  f: ['d', 'r', 't', 'g', 'v', 'c'],
+  g: ['f', 't', 'y', 'h', 'b', 'v'],
+  h: ['g', 'y', 'u', 'j', 'n', 'b'],
+  i: ['u', 'j', 'k', 'o'],
+  j: ['h', 'u', 'i', 'k', 'm', 'n'],
+  k: ['j', 'i', 'o', 'l', 'm'],
+  l: ['k', 'o', 'p', ';'],
+  m: ['n', 'j', 'k'],
+  n: ['b', 'h', 'j', 'm'],
+  o: ['i', 'k', 'l', 'p'],
+  p: ['o', 'l', '['],
+  q: ['1', '2', 'w', 'a'],
+  r: ['e', 'd', 'f', 't'],
+  s: ['a', 'w', 'e', 'd', 'x', 'z'],
+  t: ['r', 'f', 'g', 'y'],
+  u: ['y', 'h', 'j', 'i'],
+  v: ['c', 'f', 'g', 'b'],
+  w: ['q', 'a', 's', 'e'],
+  x: ['z', 's', 'd', 'c'],
+  y: ['t', 'g', 'h', 'u'],
+  z: ['a', 's', 'x'],
+};
+
+/** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+ * @description Calculates Euclidean physical key distance on a standard QWERTY keyboard layout.
+ * @param {string} keyA - Starting character or key.
+ * @param {string} keyB - Target character or key.
+ * @returns {number} Physical distance in key coordinate units (approx 1.0 to 12.0).
+ *
+ * -------------
+ *
+ * @Properties
+ * @param {string} keyA - First key name or character.
+ * @param {string} keyB - Second key name or character.
+ *
+ * -------------
+ *
+ * @example
+ * const distAdjacent = calculateKeyDistance('e', 'r'); // ~1.0
+ * const distFar = calculateKeyDistance('q', 'p'); // ~9.0
+ */
+export function calculateKeyDistance(keyA, keyB) {
+  const a = QWERTY_COORDS[String(keyA).toLowerCase()] || [2, 5];
+  const b = QWERTY_COORDS[String(keyB).toLowerCase()] || [2, 5];
+  const dy = b[0] - a[0];
+  const dx = b[1] - a[1];
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+export class TypeFlowKeystroke {
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Computes dynamic typing delay between two consecutive characters based on physical distance, fatigue, and punctuation.
+   * @param {string} prevChar - Previously typed character.
+   * @param {string} nextChar - Character about to be typed.
+   * @param {Object} [options={}] - Cadence calculation options.
+   * @returns {number} Calculated delay in milliseconds.
+   *
+   * -------------
+   *
+   * @Properties
+   * @param {string} prevChar - The last typed character.
+   * @param {string} nextChar - The next character to type.
+   * @param {number} [options.baseSpeed=45] - Base typing speed in milliseconds per unit.
+   * @param {number} [options.fatigueIndex=0] - Character index counter in active passage.
+   * @param {number} [options.fatigueRate=0.0001] - Gradual deceleration coefficient per character.
+   *
+   * -------------
+   *
+   * @example
+   * const delay = TypeFlowKeystroke.getDelay('a', 'b', { baseSpeed: 40 });
+   * const pauseAfterPeriod = TypeFlowKeystroke.getDelay('.', 'T', { baseSpeed: 40 });
+   */
+  static getDelay(prevChar, nextChar, options = {}) {
+    const base = options.baseSpeed || 45;
+    const fatigue = 1 + (options.fatigueIndex || 0) * (options.fatigueRate || 0.0001);
+
+    // 1. Distance multiplier (farther keys take slightly longer)
+    const dist = calculateKeyDistance(prevChar, nextChar);
+    const distFactor = 1 + Math.min(0.6, dist * 0.06);
+
+    // 2. Natural Punctuation Hesitations
+    let pause = 0;
+    if (prevChar === '.' || prevChar === '!' || prevChar === '?') pause = 240;
+    else if (prevChar === ',' || prevChar === ';' || prevChar === ':') pause = 120;
+    else if (prevChar === ' ' || prevChar === '\n') pause = 35;
+
+    // 3. Random Gaussian jitter (±15%)
+    const jitter = 0.85 + Math.random() * 0.3;
+
+    return Math.round((base * distFactor * fatigue + pause) * jitter);
+  }
+
+  /** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+   * @description Transforms plain text into a sequence of typing, hesitation pauses, adjacent-key typos, and backspace corrections.
+   * @param {string} text - Source text string to humanize.
+   * @param {Object} [options={}] - Typo and cadence simulation settings.
+   * @returns {Array<Object>} List of step actions ({ type: 'type' | 'erase' | 'pause', char?, duration?, isTypo? }).
+   *
+   * -------------
+   *
+   * @Properties
+   * @param {string} text - The input text.
+   * @param {number} [options.errorRate=0.04] - Probability of introducing an adjacent-key typo (0.04 = 4%).
+   * @param {number} [options.hesitationMs=180] - Pause duration in ms when a typo is made before backspacing.
+   *
+   * -------------
+   *
+   * @example
+   * const actions = TypeFlowKeystroke.humanize('Fast, resilient, zero dependencies.', {
+   *   errorRate: 0.05,
+   *   hesitationMs: 200,
+   * });
+   */
+  static humanize(text, options = {}) {
+    const errorRate = options.errorRate ?? 0.04;
+    const actions = [];
+
+    for (let i = 0; i < text.length; i++) {
+      const char = text[i];
+      const lower = char.toLowerCase();
+      const neighbors = QWERTY_NEIGHBORS[lower];
+
+      // Introduce typo if character has neighbors and probability hits
+      if (
+        neighbors &&
+        neighbors.length > 0 &&
+        Math.random() < errorRate &&
+        char !== ' ' &&
+        char !== '\n'
+      ) {
+        const typoChar = neighbors[Math.floor(Math.random() * neighbors.length)];
+        const isUpper = char !== lower;
+        const insertedTypo = isUpper ? typoChar.toUpperCase() : typoChar;
+
+        // 1. Type the typo
+        actions.push({ type: 'type', char: insertedTypo, isTypo: true });
+        // 2. Realize mistake hesitation
+        actions.push({ type: 'pause', duration: options.hesitationMs || 180 });
+        // 3. Backspace typo
+        actions.push({ type: 'erase', count: 1 });
+        // 4. Type correct character
+        actions.push({ type: 'type', char, isTypo: false });
+      } else {
+        actions.push({ type: 'type', char, isTypo: false });
+      }
+    }
+
+    return actions;
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.TypeFlowKeystroke = TypeFlowKeystroke;
+}