@staticcanvas/typeflow 0.34.0

package/jsr.jsonc

@@ -0,0 +1,27 @@
+{
+  // URL to the schema. This gives you autocompletion and validation in VS Code.
+  "$schema": "https://jsr.io/schema/config-file.v1.json",
+  // ---------------------------------------------------------
+  // PACKAGE IDENTITY
+  // ---------------------------------------------------------
+  // The name must be scoped with an '@' (e.g. @username/pkgname)
+  "name": "@staticcanvas/typeflow",
+  // Must be a valid SemVer version (e.g. 0.1.0, 1.0.0-rc.1)
+  "version": "0.34.0",
+  // ---------------------------------------------------------
+  // EXPORTS
+  // ---------------------------------------------------------
+  // Defines what files users can import.
+  // "." is the default import
+  "exports": {
+    ".": "./src/typeflow.js"
+  },
+  // ---------------------------------------------------------
+  // PUBLISHING CONTROLS
+  // ---------------------------------------------------------
+  // Controls which files are uploaded to JSR.
+  "publish": {
+    "include": ["src/**", "dist/**", "package.json", "README.md", "LICENSE"],
+    "exclude": ["src/**/*.test.js"],
+  },
+}

package/package.json

@@ -0,0 +1,133 @@
+{
+  "name": "@staticcanvas/typeflow",
+  "version": "0.34.0",
+  "description": "Typeflow library.",
+  "type": "module",
+  "main": "./dist/typeflow.cjs",
+  "module": "./dist/typeflow.mjs",
+  "browser": "./dist/typeflow.js",
+  "types": "./src/typeflow.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/typeflow.mjs",
+      "require": "./dist/typeflow.cjs",
+      "default": "./dist/typeflow.js"
+    },
+    "./metrics": {
+      "import": "./dist/typeflow-metrics.mjs",
+      "require": "./dist/typeflow-metrics.cjs",
+      "default": "./dist/typeflow-metrics.js"
+    },
+    "./debug": {
+      "import": "./dist/typeflow-debug.mjs",
+      "require": "./dist/typeflow-debug.cjs",
+      "default": "./dist/typeflow-debug.js"
+    },
+    "./caret": {
+      "import": "./dist/typeflow-caret.mjs",
+      "require": "./dist/typeflow-caret.cjs",
+      "default": "./dist/typeflow-caret.js"
+    },
+    "./webaudio": {
+      "types": "./src/typeflow-webaudio.d.ts",
+      "import": "./dist/typeflow-webaudio.mjs",
+      "require": "./dist/typeflow-webaudio.cjs",
+      "default": "./dist/typeflow-webaudio.js"
+    },
+    "./parallel": {
+      "types": "./src/typeflow-parallel.d.ts",
+      "import": "./dist/typeflow-parallel.mjs",
+      "require": "./dist/typeflow-parallel.cjs",
+      "default": "./dist/typeflow-parallel.js"
+    },
+    "./keystroke": {
+      "types": "./src/typeflow-keystroke.d.ts",
+      "import": "./dist/typeflow-keystroke.mjs",
+      "require": "./dist/typeflow-keystroke.cjs",
+      "default": "./dist/typeflow-keystroke.js"
+    },
+    "./extchars": {
+      "types": "./src/typeflow-extchars.d.ts",
+      "import": "./dist/typeflow-extchars.mjs",
+      "require": "./dist/typeflow-extchars.cjs",
+      "default": "./dist/typeflow-extchars.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "branding",
+    "README.md",
+    "LICENSE",
+    "jsr.jsonc"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "serve:demo": "vite --open docs/static/webutil/index.html",
+    "docs:build": "npm run build && hugo --source docs",
+    "docs:serve": "npm run build && hugo server --source docs --buildDrafts --disableFastRender --ignoreCache --noHTTPCache --gc",
+    "build": "vite build && npm_config_mode=metrics vite build --config vite.optional.config.js && npm_config_mode=debug vite build --config vite.optional.config.js && npm_config_mode=caret vite build --config vite.optional.config.js && npm_config_mode=webaudio vite build --config vite.optional.config.js && npm_config_mode=parallel vite build --config vite.optional.config.js && npm_config_mode=keystroke vite build --config vite.optional.config.js && npm_config_mode=extchars vite build --config vite.optional.config.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:bun": "bun test",
+    "test:coverage:bun": "bun test --coverage",
+    "test:e2e": "npm run build && playwright test",
+    "test:e2e:ui": "npm run build && playwright test --ui",
+    "benchmark": "node --expose-gc scripts/run-benchmark.mjs",
+    "benchmark:quick": "node --expose-gc scripts/run-benchmark.mjs --quick",
+    "benchmark:md": "node --expose-gc scripts/run-benchmark.mjs --markdown",
+    "benchmark:json": "node --expose-gc scripts/run-benchmark.mjs --json",
+    "benchmark:browser": "npm run build && hugo --source docs --baseURL=http://127.0.0.1/ --gc && node scripts/run-browser-benchmark.mjs",
+    "benchmark:browser:quick": "npm run build && hugo --source docs --baseURL=http://127.0.0.1/ --gc && node scripts/run-browser-benchmark.mjs --quick",
+    "benchmark:profile": "npm run build && hugo --source docs --baseURL=http://127.0.0.1/ --gc && node scripts/profile-runtime.mjs",
+    "check:size": "node scripts/check-bundle-size.mjs",
+    "validate:docs-data": "node scripts/validate-doc-data.mjs",
+    "validate:doc-links": "hugo --source docs --gc && node scripts/validate-doc-links.mjs",
+    "release:docs:preview": "pwsh -NoProfile -File scripts/update-release-docs.ps1",
+    "release:docs": "pwsh -NoProfile -File scripts/update-release-docs.ps1 -Apply",
+    "release:docs:rebuild:preview": "pwsh -NoProfile -File scripts/update-release-docs.ps1 -Rebuild",
+    "release:docs:rebuild": "pwsh -NoProfile -File scripts/update-release-docs.ps1 -Rebuild -Apply",
+    "validate:release": "node scripts/validate-release.mjs",
+    "check:quality": "npm run validate:docs-data && npm run build && npm run check:size && npm test"
+  },
+  "keywords": [
+    "staticcanvas",
+    "esm"
+  ],
+  "author": "Garvey K. Snow",
+  "license": "MIT",
+  "peerDependencies": {
+    "@staticcanvas/logcad": "^0.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@staticcanvas/logcad": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/staticcanvas/typeflow.git"
+  },
+  "homepage": "https://staticcanvas.gitlab.io/typeflow",
+  "bugs": {
+    "url": "https://gitlab.com/staticcanvas/typeflow/-/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.20.0",
+    "@playwright/test": "^1.62.1",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@vitest/coverage-v8": "^3.2.7",
+    "eslint": "^9.20.0",
+    "eslint-config-prettier": "^10.0.1",
+    "globals": "^15.14.0",
+    "jsdom": "^26.0.0",
+    "prettier": "^3.5.0",
+    "rollup-plugin-copy": "^3.5.0",
+    "vite": "^6.1.0",
+    "vitest": "^3.0.5"
+  }
+}

package/src/typeflow-audio-presets.js

@@ -0,0 +1,137 @@
+export const AUDIO_PRESET_SCHEMA_VERSION = 1;
+
+const freeze = (value) => {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.values(value).forEach(freeze);
+    Object.freeze(value);
+  }
+  return value;
+};
+
+const layer = (oscillator, start, end, gain, duration, extras = {}) => ({
+  oscillator,
+  frequency: { start, end },
+  gain: { start: gain, end: 0.001 },
+  duration,
+  filter: extras.filter ?? null,
+  detune: { base: extras.detune ?? 0, variance: extras.variance ?? 0.06 },
+});
+
+const preset = (type, erase) => ({
+  version: AUDIO_PRESET_SCHEMA_VERSION,
+  actions: { type, erase: erase ?? type },
+});
+
+export const AUDIO_PRESETS = freeze({
+  'mechanical-blue': preset(
+    [layer('triangle', 3400, 900, 0.18, 0.008), layer('sine', 200, 50, 0.32, 0.035)],
+    [layer('triangle', 900, 180, 0.12, 0.025)]
+  ),
+  'mechanical-red': preset(
+    [layer('sine', 220, 70, 0.26, 0.028)],
+    [layer('sine', 150, 55, 0.12, 0.022)]
+  ),
+  'mechanical-brown': preset(
+    [layer('triangle', 240, 75, 0.27, 0.032)],
+    [layer('triangle', 170, 60, 0.13, 0.024)]
+  ),
+  'soft-keyboard': preset(
+    [
+      layer('sine', 520, 280, 0.08, 0.018, {
+        filter: { type: 'lowpass', frequency: 1200, q: 0.7 },
+      }),
+    ],
+    [layer('sine', 320, 180, 0.06, 0.016)]
+  ),
+  typewriter: preset(
+    [layer('square', 320, 90, 0.17, 0.022)],
+    [layer('square', 180, 70, 0.13, 0.026)]
+  ),
+  'terminal-beep': preset(
+    [layer('square', 880, 880, 0.08, 0.025)],
+    [layer('square', 440, 330, 0.06, 0.03)]
+  ),
+  synth: preset(
+    [layer('sawtooth', 950, 180, 0.12, 0.045)],
+    [layer('sawtooth', 420, 120, 0.09, 0.04)]
+  ),
+  correction: preset(
+    [layer('triangle', 360, 110, 0.1, 0.035)],
+    [layer('triangle', 260, 80, 0.14, 0.045)]
+  ),
+});
+
+export const AUDIO_PRESET_ALIASES = freeze({
+  clicky: 'mechanical-blue',
+  mechanical: 'mechanical-red',
+  tactile: 'mechanical-brown',
+  teletype: 'typewriter',
+  vintage: 'typewriter',
+  'terminal-8bit': 'terminal-beep',
+  '8bit': 'terminal-beep',
+  beep: 'terminal-beep',
+  'cyber-synth': 'synth',
+  neon: 'synth',
+  bubble: 'soft-keyboard',
+  pop: 'soft-keyboard',
+});
+
+export function validateAudioPreset(config) {
+  if (
+    !config ||
+    config.version !== AUDIO_PRESET_SCHEMA_VERSION ||
+    !config.actions ||
+    typeof config.actions !== 'object'
+  ) {
+    throw new TypeError(
+      `TypeFlowWebAudio: preset must use schema version ${AUDIO_PRESET_SCHEMA_VERSION}.`
+    );
+  }
+  const output = { version: AUDIO_PRESET_SCHEMA_VERSION, actions: {} };
+  for (const action of ['type', 'erase']) {
+    const layers = config.actions[action];
+    if (!Array.isArray(layers) || layers.length === 0 || layers.length > 4) {
+      throw new TypeError(
+        `TypeFlowWebAudio: actions.${action} must contain 1-4 oscillator layers.`
+      );
+    }
+    output.actions[action] = layers.map((candidate) => {
+      const oscillator = String(candidate.oscillator ?? 'sine');
+      if (!['sine', 'square', 'sawtooth', 'triangle'].includes(oscillator))
+        throw new RangeError('TypeFlowWebAudio: invalid oscillator type.');
+      const duration = Number(candidate.duration);
+      const start = Number(candidate.frequency?.start);
+      const end = Number(candidate.frequency?.end);
+      const gainStart = Number(candidate.gain?.start);
+      const gainEnd = Number(candidate.gain?.end);
+      if (!(duration >= 0.001 && duration <= 2))
+        throw new RangeError('TypeFlowWebAudio: duration must be 0.001-2 seconds.');
+      if (!(start >= 20 && start <= 20000 && end >= 20 && end <= 20000))
+        throw new RangeError('TypeFlowWebAudio: frequency must be 20-20000 Hz.');
+      if (!(gainStart >= 0 && gainStart <= 1 && gainEnd > 0 && gainEnd <= 1))
+        throw new RangeError('TypeFlowWebAudio: gain must be within safe bounds.');
+      const variance = Number(candidate.detune?.variance ?? 0);
+      if (!(variance >= 0 && variance <= 0.5))
+        throw new RangeError('TypeFlowWebAudio: detune variance must be 0-0.5.');
+      const filter =
+        candidate.filter === null || candidate.filter === undefined
+          ? null
+          : {
+              type: String(candidate.filter.type ?? 'lowpass'),
+              frequency: Math.max(20, Math.min(20000, Number(candidate.filter.frequency) || 1000)),
+              q: Math.max(0.0001, Math.min(1000, Number(candidate.filter.q) || 1)),
+            };
+      if (filter && !['lowpass', 'highpass', 'bandpass', 'notch'].includes(filter.type))
+        throw new RangeError('TypeFlowWebAudio: invalid filter type.');
+      return {
+        oscillator,
+        frequency: { start, end },
+        gain: { start: gainStart, end: gainEnd },
+        duration,
+        filter,
+        detune: { base: Number(candidate.detune?.base) || 0, variance },
+      };
+    });
+  }
+  return freeze(output);
+}

package/src/typeflow-caret.d.ts

@@ -0,0 +1,65 @@
+/**
+ * TypeFlow Caret - Interactive Cursor Positioning & Mid-String Editing.
+ */
+export interface TypeFlowCaretConfig {
+  /** Initial text. Defaults to the target's current text content. */
+  text?: string;
+  /** Initial caret index in graphemes. Defaults to the end of the text. */
+  position?: number;
+  /** Cursor glyph. Empty string hides it. Default: '|' */
+  cursor?: string;
+  /** Default: true */
+  cursorBlink?: boolean;
+  /** Default ms per character for `insert()`. Default: 40 */
+  speed?: number;
+  /** Instantly complete `insert()` instead of animating if the user prefers reduced motion. Default: true */
+  respectReducedMotion?: boolean;
+}
+
+export interface TypeFlowCaretInsertConfig {
+  /** Ms per character. Defaults to the speed passed to the constructor. */
+  speed?: number;
+  respectReducedMotion?: boolean;
+  onStart?: () => void;
+  onComplete?: (text: string) => void;
+  onInterrupt?: () => void;
+}
+
+export interface TypeFlowCaretResult {
+  completed: boolean;
+  text: string;
+}
+
+export interface TypeFlowCaretController {
+  stop: () => void;
+  promise: Promise<TypeFlowCaretResult>;
+}
+
+export class TypeFlowCaret {
+  constructor(target: Element | string, config?: TypeFlowCaretConfig);
+
+  /** Current plain-text content, cursor excluded. */
+  readonly text: string;
+  /** Current caret index, in graphemes, from the start of the text. */
+  readonly position: number;
+  /** Total number of graphemes in the current text. */
+  readonly length: number;
+
+  /** Moves the caret to an absolute grapheme index, clamped to bounds. */
+  jump(position: number): this;
+  /** Moves the caret by a relative number of graphemes (positive = right, negative = left). */
+  move(delta: number): this;
+  /** Deletes one grapheme at the caret: 'backward' (Backspace, default) or 'forward' (Delete). */
+  deleteChar(direction?: "backward" | "forward"): this;
+  /** Deletes the whitespace-delimited word adjacent to the caret. */
+  deleteWord(direction?: "backward" | "forward"): this;
+  /** Types `text` at the current caret position, shifting following content to the right. */
+  insert(text: string, config?: TypeFlowCaretInsertConfig): TypeFlowCaretController;
+  /** Stops an in-flight `insert()`, if any. */
+  stop(): this;
+  /** Stops any in-flight `insert()` and clears the blink interval. */
+  destroy(): this;
+}
+
+/** Factory form of `new TypeFlowCaret(target, config)`. */
+export function Caret(target: Element | string, config?: TypeFlowCaretConfig): TypeFlowCaret;

package/src/typeflow-caret.js

@@ -0,0 +1,303 @@
+/** * * * * * * * * * * * * * * * * * * * * * * * * * * **
+ * @description TypeFlow Caret - Interactive Cursor Positioning & Mid-String Editing.
+ * A persistent, editable cursor bound to an element's text: jump or move to any
+ * grapheme index, delete a character or whole word at that position, and type
+ * new text in with the usual character-by-character animation. Zero
+ * dependencies; opportunistically defers to a page-global TypeFlow so starting
+ * a `TypeFlow.type()`/`erase()` on the same element interrupts an in-flight
+ * caret edit, without requiring a hard import of the core engine.
+ *
+ * @module @staticcanvas/typeflow/caret
+ */
+
+const CURSOR_BLINK_INTERVAL = 530;
+const WHITESPACE_UNIT = /^\s+$/u;
+
+function segmentGraphemes(text) {
+  if (typeof Intl !== 'undefined' && Intl.Segmenter) {
+    return Array.from(
+      new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(text),
+      (s) => s.segment
+    );
+  }
+  return Array.from(text);
+}
+
+function prefersReducedMotion() {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}
+
+/** Stops any animation the page-global TypeFlow engine may have active on `el`, if present. */
+function stopPageTypeFlow(el) {
+  if (typeof window !== 'undefined') window.TypeFlow?.stop?.(el);
+}
+
+function clampCaretIndex(position, max) {
+  const value = position === undefined || position === null ? max : Number(position);
+  if (!Number.isFinite(value)) return max;
+  return Math.max(0, Math.min(Math.round(value), max));
+}
+
+function createCursorSpan(cursorChar) {
+  const span = document.createElement('span');
+  span.className = 'tf-cursor';
+  span.setAttribute('aria-hidden', 'true');
+  span.textContent = cursorChar;
+  return span;
+}
+
+/**
+ * Interactive, stateful cursor bound to an element's text content.
+ *
+ * Unlike `TypeFlow.type()`/`erase()`, which run once from start to finish, a
+ * Caret is persistent: `jump()`, `move()`, `deleteChar()`, and `deleteWord()`
+ * edit `text`/`position` and re-render immediately; `insert()` is animated
+ * and returns a `{ stop, promise }` controller.
+ */
+export class TypeFlowCaret {
+  /**
+   * @param {Element | string} target - Element or CSS selector.
+   * @param {object} [config={}]
+   * @param {string} [config.text] - Initial text. Defaults to the target's current text content.
+   * @param {number} [config.position] - Initial caret index in graphemes. Defaults to the end of the text.
+   * @param {string} [config.cursor='|'] - Cursor glyph. Empty string hides it.
+   * @param {boolean} [config.cursorBlink=true]
+   * @param {number} [config.speed=40] - Default ms per character for `insert()`.
+   * @param {boolean} [config.respectReducedMotion=true]
+   *
+   * @example
+   * const caret = new TypeFlowCaret('#terminal', { text: 'git commit -m "wip"' });
+   * caret.jump(3).deleteWord('forward').insert('push');
+   * // "git push -m "wip""
+   */
+  constructor(target, config = {}) {
+    this.el = typeof target === 'string' ? document.querySelector(target) : target;
+    if (!this.el) throw new Error('TypeFlowCaret: target element not found.');
+    stopPageTypeFlow(this.el);
+
+    this.cursor = config.cursor ?? '|';
+    this.cursorBlink = config.cursorBlink ?? true;
+    this.speed = config.speed ?? 40;
+    this.respectReducedMotion = config.respectReducedMotion ?? true;
+    this.units = segmentGraphemes(config.text ?? this.el.textContent ?? '');
+    this.index = clampCaretIndex(config.position ?? this.units.length, this.units.length);
+    this._blinkInterval = null;
+    this._activeInsert = null;
+    this._render();
+  }
+
+  /** Current plain-text content, cursor excluded. */
+  get text() {
+    return this.units.join('');
+  }
+
+  /** Current caret index, in graphemes, from the start of the text. */
+  get position() {
+    return this.index;
+  }
+
+  /** Total number of graphemes in the current text. */
+  get length() {
+    return this.units.length;
+  }
+
+  /** Moves the caret to an absolute grapheme index, clamped to bounds. */
+  jump(position) {
+    this._stopInsert();
+    this.index = clampCaretIndex(position, this.units.length);
+    this._render();
+    return this;
+  }
+
+  /** Moves the caret by a relative number of graphemes (positive = right, negative = left). */
+  move(delta) {
+    return this.jump(this.index + (Number(delta) || 0));
+  }
+
+  /**
+   * Deletes one grapheme at the caret.
+   * @param {'backward'|'forward'} [direction='backward'] - `'backward'` removes the character before the caret (Backspace); `'forward'` removes the character at/after it (Delete).
+   */
+  deleteChar(direction = 'backward') {
+    this._stopInsert();
+    if (direction === 'forward') {
+      if (this.index < this.units.length) this.units.splice(this.index, 1);
+    } else if (this.index > 0) {
+      this.units.splice(this.index - 1, 1);
+      this.index -= 1;
+    }
+    this._render();
+    return this;
+  }
+
+  /**
+   * Deletes the whitespace-delimited word adjacent to the caret.
+   * @param {'backward'|'forward'} [direction='backward'] - `'backward'` removes the word (and any whitespace immediately before it) that precedes the caret; `'forward'` removes the word (and any whitespace immediately after it) that follows.
+   */
+  deleteWord(direction = 'backward') {
+    this._stopInsert();
+    if (direction === 'forward') {
+      let end = this.index;
+      let ateLeadingSpace = false;
+      while (end < this.units.length && WHITESPACE_UNIT.test(this.units[end])) {
+        end += 1;
+        ateLeadingSpace = true;
+      }
+      while (end < this.units.length && !WHITESPACE_UNIT.test(this.units[end])) end += 1;
+      if (!ateLeadingSpace) {
+        while (end < this.units.length && WHITESPACE_UNIT.test(this.units[end])) end += 1;
+      }
+      if (end === this.index) return this;
+      this.units.splice(this.index, end - this.index);
+    } else {
+      let start = this.index;
+      while (start > 0 && WHITESPACE_UNIT.test(this.units[start - 1])) start -= 1;
+      while (start > 0 && !WHITESPACE_UNIT.test(this.units[start - 1])) start -= 1;
+      if (start === this.index) return this;
+      this.units.splice(start, this.index - start);
+      this.index = start;
+    }
+    this._render();
+    return this;
+  }
+
+  /**
+   * Types `text` at the current caret position, one grapheme at a time,
+   * shifting any following content to the right as it goes.
+   *
+   * @param {string} text
+   * @param {object} [config={}]
+   * @param {number} [config.speed] - Ms per character. Defaults to the speed passed to the constructor.
+   * @param {boolean} [config.respectReducedMotion]
+   * @param {() => void} [config.onStart]
+   * @param {(text: string) => void} [config.onComplete]
+   * @param {() => void} [config.onInterrupt]
+   * @returns {{ stop: () => void, promise: Promise<{completed: boolean, text: string}> }}
+   */
+  insert(text, config = {}) {
+    this._stopInsert();
+    const insertUnits = segmentGraphemes(text === null || text === undefined ? '' : String(text));
+    const speed = Math.max(0, Number(config.speed ?? this.speed) || 0);
+    const startIndex = this.index;
+
+    let settled = false;
+    let timeoutId = null;
+    let resolveFn = null;
+    const settle = (completed) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutId !== null) clearTimeout(timeoutId);
+      this._activeInsert = null;
+      if (completed) config.onComplete?.(this.text);
+      else config.onInterrupt?.();
+      resolveFn?.({ completed, text: this.text });
+    };
+    const controller = {
+      stop: () => settle(false),
+      promise: new Promise((resolve) => {
+        resolveFn = resolve;
+      }),
+    };
+    this._activeInsert = controller;
+
+    if (insertUnits.length === 0) {
+      settle(true);
+      return controller;
+    }
+
+    const respectReducedMotion = config.respectReducedMotion ?? this.respectReducedMotion;
+    if (respectReducedMotion === true && prefersReducedMotion()) {
+      this.units.splice(startIndex, 0, ...insertUnits);
+      this.index = startIndex + insertUnits.length;
+      this._render();
+      settle(true);
+      return controller;
+    }
+
+    config.onStart?.();
+    let step = 0;
+    const tick = () => {
+      this.units.splice(startIndex + step, 0, insertUnits[step]);
+      this.index = startIndex + step + 1;
+      this._render();
+      step += 1;
+      if (step >= insertUnits.length) {
+        settle(true);
+        return;
+      }
+      timeoutId = setTimeout(tick, speed);
+    };
+    timeoutId = setTimeout(tick, speed);
+    return controller;
+  }
+
+  /** Stops an in-flight `insert()`, if any. */
+  stop() {
+    this._stopInsert();
+    return this;
+  }
+
+  /** Stops any in-flight `insert()` and clears the blink interval. Call when done with a caret. */
+  destroy() {
+    this._stopInsert();
+    if (this._blinkInterval !== null) {
+      clearInterval(this._blinkInterval);
+      this._blinkInterval = null;
+    }
+    return this;
+  }
+
+  _stopInsert() {
+    this._activeInsert?.stop();
+    stopPageTypeFlow(this.el);
+  }
+
+  _render() {
+    if (this._blinkInterval !== null) {
+      clearInterval(this._blinkInterval);
+      this._blinkInterval = null;
+    }
+    const before = this.units.slice(0, this.index).join('');
+    const after = this.units.slice(this.index).join('');
+    this.el.replaceChildren(document.createTextNode(before));
+
+    if (this.cursor) {
+      const cursorSpan = createCursorSpan(this.cursor);
+      this.el.appendChild(cursorSpan);
+      if (this.cursorBlink) {
+        let visible = true;
+        this._blinkInterval = setInterval(() => {
+          visible = !visible;
+          cursorSpan.style.visibility = visible ? 'visible' : 'hidden';
+        }, CURSOR_BLINK_INTERVAL);
+        this._blinkInterval.unref?.();
+      }
+    }
+
+    this.el.appendChild(document.createTextNode(after));
+  }
+}
+
+/**
+ * Factory form of `new TypeFlowCaret(target, config)`.
+ *
+ * @param {Element | string} target
+ * @param {object} [config]
+ * @returns {TypeFlowCaret}
+ *
+ * @example
+ * const caret = Caret('#terminal', { text: 'git commit' });
+ * caret.move(-6).insert('push --force ');
+ */
+export function Caret(target, config) {
+  return new TypeFlowCaret(target, config);
+}
+
+if (typeof window !== 'undefined') {
+  window.TypeFlowCaret = TypeFlowCaret;
+  window.Caret = Caret;
+}