novac 2.0.1 → 2.2.0

package/kits/kitregex++/kitdef.js

@@ -0,0 +1,1353 @@
+'use strict';
+
+// ============================================================
+//  kitregex++.js  —  Regex, but 3000% better.
+//  module.exports = { kitdef: { ...all exports } }
+// ============================================================
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 1: INTERNAL HELPERS
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Escape a string for literal use inside a RegExp.
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Coerce a value to a RegExp.
+ * Accepts: RegExp | string (raw pattern) | KitPattern
+ */
+function _toRegex(pat, flags = '') {
+  if (pat instanceof RegExp) return pat;
+  if (pat instanceof KitPattern) return pat.toRegex();
+  if (typeof pat === 'string') return new RegExp(pat, flags);
+  throw new TypeError('kitregex++: pattern must be RegExp, string, or KitPattern');
+}
+
+/**
+ * Merge regex flags, deduplicating.
+ */
+function _mergeFlags(...flagSets) {
+  return [...new Set(flagSets.join('').split(''))].join('');
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 2: PATTERN REGISTRY
+// ────────────────────────────────────────────────────────────
+
+const _registry = new Map();
+
+/**
+ * Register a named pattern for later reuse.
+ * @param {string} name
+ * @param {RegExp|string|KitPattern} pattern
+ * @param {string} [description]
+ */
+function registerPattern(name, pattern, description = '') {
+  _registry.set(name, { pattern, description });
+}
+
+/**
+ * Retrieve a registered pattern by name.
+ * @param {string} name
+ * @returns {RegExp|string|KitPattern}
+ */
+function getPattern(name) {
+  const entry = _registry.get(name);
+  if (!entry) throw new Error(`kitregex++: no pattern registered as "${name}"`);
+  return entry.pattern;
+}
+
+/**
+ * List all registered pattern names.
+ * @returns {Array<{name: string, description: string}>}
+ */
+function listPatterns() {
+  return [..._registry.entries()].map(([name, { description }]) => ({ name, description }));
+}
+
+/**
+ * Unregister a named pattern.
+ * @param {string} name
+ */
+function unregisterPattern(name) {
+  _registry.delete(name);
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 3: BUILT-IN PATTERN PACKS
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Raw pattern sources (as strings, so they can be composed).
+ * Accessed via Patterns.PACK.NAME
+ */
+const Patterns = {
+
+  // ── Internet ───────────────────────────────────────────
+  internet: {
+    EMAIL:        /^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$/,
+    EMAIL_LOOSE:  /[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}/g,
+    URL:          /https?:\/\/(www\.)?[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_+.~#?&/=]*)/,
+    URL_LOOSE:    /https?:\/\/[^\s"'>]+/g,
+    URL_ANY:      /(https?:\/\/|www\.)[^\s"'>]+/g,
+    IPV4:         /\b((25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)\b/,
+    IPV6:         /([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}/,
+    MAC:          /\b([0-9a-fA-F]{2}[:\-]){5}[0-9a-fA-F]{2}\b/,
+    DOMAIN:       /\b([a-zA-Z0-9\-]+\.)+[a-zA-Z]{2,}\b/,
+    SLUG:         /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+    PORT:         /\b(6553[0-5]|655[0-2]\d|65[0-4]\d{2}|6[0-4]\d{3}|[1-5]\d{4}|[1-9]\d{1,3}|[1-9])\b/,
+    QUERY_STRING: /\?([^#]*)/,
+    HASH_FRAG:    /#(.*)/,
+  },
+
+  // ── Dates & Times ─────────────────────────────────────
+  datetime: {
+    DATE_ISO:     /\b\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])\b/,
+    DATE_US:      /\b(?:0?[1-9]|1[0-2])\/(?:0?[1-9]|[12]\d|3[01])\/\d{2,4}\b/,
+    DATE_EU:      /\b(?:0?[1-9]|[12]\d|3[01])\.(?:0?[1-9]|1[0-2])\.\d{2,4}\b/,
+    TIME_24:      /\b([01]?\d|2[0-3]):([0-5]\d)(?::([0-5]\d))?\b/,
+    TIME_12:      /\b(0?[1-9]|1[0-2]):([0-5]\d)(?::([0-5]\d))?\s*([AaPp][Mm])\b/,
+    DATETIME_ISO: /\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])[T ]\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})?/,
+    UNIX_TS:      /\b\d{10}(?:\d{3})?\b/,
+    YEAR:         /\b(19|20)\d{2}\b/,
+    MONTH_NAME:   /\b(January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\b/i,
+    DURATION_ISO: /P(?:\d+Y)?(?:\d+M)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+S)?)?/,
+  },
+
+  // ── Numbers ───────────────────────────────────────────
+  numbers: {
+    INTEGER:      /^-?\d+$/,
+    FLOAT:        /^-?\d+\.\d+$/,
+    NUMBER:       /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/,
+    HEX:          /^0x[0-9a-fA-F]+$/,
+    OCTAL:        /^0o[0-7]+$/,
+    BINARY:       /^0b[01]+$/,
+    CURRENCY_VAL: /[+-]?[$€£¥]?\s?\d{1,3}(?:[,. ]\d{3})*(?:[.,]\d{2})?/,
+    PERCENT:      /\b\d+(?:\.\d+)?%/,
+    SCIENTIFIC:   /-?\d+(?:\.\d+)?[eE][+-]?\d+/,
+    FRACTION:     /\b\d+\/\d+\b/,
+    RANGE:        /\b\d+\s*[-–—]\s*\d+\b/,
+  },
+
+  // ── Identifiers / Code ────────────────────────────────
+  code: {
+    IDENTIFIER:   /\b[a-zA-Z_$][a-zA-Z0-9_$]*\b/,
+    CAMEL_CASE:   /\b[a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*\b/,
+    PASCAL_CASE:  /\b[A-Z][a-zA-Z0-9]+\b/,
+    SNAKE_CASE:   /\b[a-z]+(_[a-z0-9]+)+\b/,
+    KEBAB_CASE:   /\b[a-z]+(-[a-z0-9]+)+\b/,
+    CONST_CASE:   /\b[A-Z][A-Z0-9]*(_[A-Z0-9]+)+\b/,
+    HEX_COLOR:    /#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/,
+    CSS_CLASS:    /\.[a-zA-Z_-][a-zA-Z0-9_-]*/g,
+    CSS_ID:       /#[a-zA-Z_-][a-zA-Z0-9_-]*/g,
+    HTML_TAG:     /<\/?[a-zA-Z][a-zA-Z0-9]*(?:\s[^>]*)?\/?>/g,
+    HTML_COMMENT: /<!--[\s\S]*?-->/g,
+    JS_COMMENT_LINE:  /\/\/[^\n]*/g,
+    JS_COMMENT_BLOCK: /\/\*[\s\S]*?\*\//g,
+    SEMVER:       /\bv?(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9.\-]+))?(?:\+([a-zA-Z0-9.\-]+))?\b/,
+    UUID:         /\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/i,
+    JWT:          /\beyJ[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\b/,
+    TEMPLATE_LIT: /`[^`]*`/g,
+    IMPORT_STMT:  /import\s+(?:[\w*{},\s]+from\s+)?['"][^'"]+['"]/g,
+    REQUIRE_STMT: /require\s*\(\s*['"][^'"]+['"]\s*\)/g,
+  },
+
+  // ── Personal / Contact ────────────────────────────────
+  personal: {
+    PHONE_US:     /\b(?:\+1\s?)?(?:\(\d{3}\)|\d{3})[\s.\-]?\d{3}[\s.\-]?\d{4}\b/,
+    PHONE_INTL:   /\+\d{1,3}[\s\-]?\d{1,4}[\s\-]?\d{1,4}[\s\-]?\d{1,9}/,
+    SSN:          /\b\d{3}-\d{2}-\d{4}\b/,
+    ZIP_US:       /\b\d{5}(?:-\d{4})?\b/,
+    ZIP_UK:       /\b[A-Z]{1,2}\d[A-Z\d]?\s?\d[A-Z]{2}\b/i,
+    POSTAL_CA:    /\b[A-Z]\d[A-Z]\s?\d[A-Z]\d\b/i,
+    CREDIT_CARD:  /\b(?:4\d{12}(?:\d{3})?|5[1-5]\d{14}|3[47]\d{13}|3(?:0[0-5]|[68]\d)\d{11}|6(?:011|5\d{2})\d{12})\b/,
+    USERNAME:     /\b[a-zA-Z0-9_]{3,20}\b/,
+    HASHTAG:      /#[a-zA-Z]\w*/g,
+    MENTION:      /@[a-zA-Z0-9_.]+/g,
+  },
+
+  // ── Filesystem / Paths ────────────────────────────────
+  fs: {
+    FILE_EXT:     /\.([a-zA-Z0-9]+)$/,
+    FILEPATH_WIN: /[a-zA-Z]:\\(?:[^\\/:*?"<>|\r\n]+\\)*[^\\/:*?"<>|\r\n]*/,
+    FILEPATH_UNIX:/(?:\/[^/\0]+)+\/?/,
+    MIME_TYPE:    /\b[a-z]+\/[a-z0-9\-+.]+\b/,
+    ENV_VAR:      /\$\{?[A-Z_][A-Z0-9_]*\}?/g,
+  },
+
+  // ── Text / Prose ──────────────────────────────────────
+  text: {
+    WORD:         /\b\w+\b/g,
+    SENTENCE:     /[^.!?]*[.!?]+/g,
+    PARAGRAPH:    /[^\n]+(?:\n(?!\n)[^\n]+)*/g,
+    WHITESPACE:   /\s+/g,
+    BLANK_LINE:   /^\s*$/gm,
+    REPEATED_WS:  /[ \t]{2,}/g,
+    QUOTED_SINGLE:/'[^'\\]*(?:\\.[^'\\]*)*'/g,
+    QUOTED_DOUBLE:/"[^"\\]*(?:\\.[^"\\]*)* "/g,
+    EMOJI:        /[\u{1F300}-\u{1FFFF}]/gu,
+    DIACRITICS:   /[\u0300-\u036f]/g,
+    NON_ASCII:    /[^\x00-\x7F]/g,
+    CONTROL_CHARS:/[\x00-\x1F\x7F]/g,
+    NEWLINES:     /\r?\n/g,
+    CRLF:         /\r\n/g,
+  },
+};
+
+// Auto-register all built-in patterns into the registry
+(function _autoRegister() {
+  for (const [pack, entries] of Object.entries(Patterns)) {
+    for (const [name, pat] of Object.entries(entries)) {
+      registerPattern(`${pack}.${name}`, pat, `Built-in: ${pack} / ${name}`);
+    }
+  }
+})();
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 4: FLAG PRESETS
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Commonly used flag combinations.
+ */
+const Flags = {
+  DEFAULT:        '',
+  GLOBAL:         'g',
+  MULTILINE:      'm',
+  INSENSITIVE:    'i',
+  DOTALL:         's',
+  UNICODE:        'u',
+  STICKY:         'y',
+  GM:             'gm',
+  GI:             'gi',
+  GIM:            'gim',
+  GS:             'gs',
+  GIMS:           'gims',
+  GISU:           'gisu',
+};
+
+/**
+ * Apply a flag preset (or raw flags) to a regex.
+ * @param {RegExp|string} pattern
+ * @param {string} flags - flag string or key from Flags
+ * @returns {RegExp}
+ */
+function withFlags(pattern, flags) {
+  const f = Flags[flags] !== undefined ? Flags[flags] : flags;
+  const r = _toRegex(pattern);
+  return new RegExp(r.source, f);
+}
+
+/**
+ * Add flags to an existing regex without removing existing ones.
+ * @param {RegExp} re
+ * @param {string} flags
+ * @returns {RegExp}
+ */
+function addFlags(re, flags) {
+  return new RegExp(re.source, _mergeFlags(re.flags, flags));
+}
+
+/**
+ * Remove specific flags from a regex.
+ * @param {RegExp} re
+ * @param {string} flags - flags to remove
+ * @returns {RegExp}
+ */
+function removeFlags(re, flags) {
+  const newFlags = re.flags.split('').filter(f => !flags.includes(f)).join('');
+  return new RegExp(re.source, newFlags);
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 5: BUILDER API  (KitPattern)
+// ────────────────────────────────────────────────────────────
+
+/**
+ * KitPattern — human-readable, chainable regex builder.
+ *
+ * Build patterns without writing raw regex strings.
+ *
+ * @example
+ * const pat = new KitPattern()
+ *   .startAnchor()
+ *   .literal('Hello')
+ *   .whitespace()
+ *   .capture(p => p.word().oneOrMore())
+ *   .endAnchor()
+ *   .flags('i')
+ *   .toRegex();
+ */
+class KitPattern {
+  constructor() {
+    this._parts = [];
+    this._flags = '';
+  }
+
+  /** Clone this builder. */
+  clone() {
+    const p = new KitPattern();
+    p._parts = [...this._parts];
+    p._flags = this._flags;
+    return p;
+  }
+
+  // ── Anchors ─────────────────────────────────────────
+
+  startAnchor()     { this._parts.push('^');       return this; }
+  endAnchor()       { this._parts.push('$');        return this; }
+  wordBoundary()    { this._parts.push('\\b');      return this; }
+  nonWordBoundary() { this._parts.push('\\B');      return this; }
+
+  // ── Literals ─────────────────────────────────────────
+
+  /** Match a literal string (auto-escaped). */
+  literal(str)      { this._parts.push(escapeRegex(str)); return this; }
+  /** Raw regex fragment (not escaped). */
+  raw(str)          { this._parts.push(str);        return this; }
+
+  // ── Character classes ────────────────────────────────
+
+  digit()           { this._parts.push('\\d');      return this; }
+  nonDigit()        { this._parts.push('\\D');      return this; }
+  word()            { this._parts.push('\\w');      return this; }
+  nonWord()         { this._parts.push('\\W');      return this; }
+  whitespace()      { this._parts.push('\\s');      return this; }
+  nonWhitespace()   { this._parts.push('\\S');      return this; }
+  anyChar()         { this._parts.push('.');         return this; }
+  tab()             { this._parts.push('\\t');      return this; }
+  newline()         { this._parts.push('\\n');      return this; }
+  carriageReturn()  { this._parts.push('\\r');      return this; }
+
+  /**
+   * Custom character class, e.g. charClass('a-z0-9_')
+   * @param {string} chars
+   * @param {boolean} [negate=false]
+   */
+  charClass(chars, negate = false) {
+    this._parts.push(`[${negate ? '^' : ''}${chars}]`);
+    return this;
+  }
+
+  /** Any one of the given characters. */
+  oneOf(...chars) {
+    this._parts.push(`[${chars.map(escapeRegex).join('')}]`);
+    return this;
+  }
+
+  /** None of the given characters. */
+  noneOf(...chars) {
+    this._parts.push(`[^${chars.map(escapeRegex).join('')}]`);
+    return this;
+  }
+
+  // ── Quantifiers ──────────────────────────────────────
+
+  optional()              { this._parts.push('?');          return this; }
+  zeroOrMore(lazy=false)  { this._parts.push(lazy?'*?':'*'); return this; }
+  oneOrMore(lazy=false)   { this._parts.push(lazy?'+?':'+'); return this; }
+  exactly(n)              { this._parts.push(`{${n}}`);     return this; }
+  atLeast(n)              { this._parts.push(`{${n},}`);    return this; }
+  between(min, max, lazy=false) {
+    this._parts.push(`{${min},${max}}${lazy?'?':''}`);
+    return this;
+  }
+
+  // ── Groups ────────────────────────────────────────────
+
+  /**
+   * Capturing group. Accepts a builder callback or a raw string.
+   * @param {function(KitPattern):KitPattern|string} inner
+   */
+  capture(inner) {
+    const src = _resolveInner(inner);
+    this._parts.push(`(${src})`);
+    return this;
+  }
+
+  /**
+   * Named capturing group.
+   * @param {string} name
+   * @param {function(KitPattern):KitPattern|string} inner
+   */
+  namedCapture(name, inner) {
+    const src = _resolveInner(inner);
+    this._parts.push(`(?<${name}>${src})`);
+    return this;
+  }
+
+  /**
+   * Non-capturing group.
+   */
+  group(inner) {
+    const src = _resolveInner(inner);
+    this._parts.push(`(?:${src})`);
+    return this;
+  }
+
+  /**
+   * Alternation: match any of the given patterns.
+   * @param {...(function|string|KitPattern|RegExp)} alts
+   */
+  either(...alts) {
+    const src = alts.map(a => _resolveInner(a)).join('|');
+    this._parts.push(`(?:${src})`);
+    return this;
+  }
+
+  // ── Lookahead / lookbehind ────────────────────────────
+
+  /** Positive lookahead. */
+  lookahead(inner) {
+    this._parts.push(`(?=${_resolveInner(inner)})`);
+    return this;
+  }
+  /** Negative lookahead. */
+  negativeLookahead(inner) {
+    this._parts.push(`(?!${_resolveInner(inner)})`);
+    return this;
+  }
+  /** Positive lookbehind. */
+  lookbehind(inner) {
+    this._parts.push(`(?<=${_resolveInner(inner)})`);
+    return this;
+  }
+  /** Negative lookbehind. */
+  negativeLookbehind(inner) {
+    this._parts.push(`(?<!${_resolveInner(inner)})`);
+    return this;
+  }
+
+  // ── Backreferences ────────────────────────────────────
+
+  /** Numeric backreference. */
+  backref(n)       { this._parts.push(`\\${n}`);     return this; }
+  /** Named backreference. */
+  namedBackref(name) { this._parts.push(`\\k<${name}>`); return this; }
+
+  // ── Composition ──────────────────────────────────────
+
+  /**
+   * Append another KitPattern, RegExp, or string.
+   * @param {KitPattern|RegExp|string} other
+   */
+  append(other) {
+    if (other instanceof KitPattern) {
+      this._parts.push(...other._parts);
+    } else if (other instanceof RegExp) {
+      this._parts.push(other.source);
+    } else {
+      this._parts.push(String(other));
+    }
+    return this;
+  }
+
+  // ── Flags ─────────────────────────────────────────────
+
+  /**
+   * Set flags for the final regex.
+   * @param {string} flags - raw flags or key from Flags
+   */
+  flags(flags) {
+    this._flags = Flags[flags] !== undefined ? Flags[flags] : flags;
+    return this;
+  }
+
+  /** Add flags without replacing existing. */
+  addFlags(flags) {
+    this._flags = _mergeFlags(this._flags, flags);
+    return this;
+  }
+
+  // ── Output ────────────────────────────────────────────
+
+  /** Get the assembled source string. */
+  get source() {
+    return this._parts.join('');
+  }
+
+  /** Build and return the final RegExp. */
+  toRegex() {
+    return new RegExp(this.source, this._flags);
+  }
+
+  /** Human-readable description of the pattern parts. */
+  describe() {
+    return `/${this.source}/${this._flags}`;
+  }
+
+  toString() { return this.describe(); }
+}
+
+function _resolveInner(inner) {
+  if (typeof inner === 'function') {
+    const p = new KitPattern();
+    const result = inner(p);
+    return (result instanceof KitPattern ? result : p).source;
+  }
+  if (inner instanceof KitPattern) return inner.source;
+  if (inner instanceof RegExp) return inner.source;
+  return String(inner);
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 6: COMPOSITION HELPERS
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Concatenate multiple patterns into one.
+ * @param {...(RegExp|string|KitPattern)} patterns
+ * @param {string} [flags='']
+ * @returns {RegExp}
+ */
+function concat(...args) {
+  let flags = '';
+  const pats = [...args];
+  if (typeof pats[pats.length - 1] === 'string' && /^[gimsuy]*$/.test(pats[pats.length - 1]) && !(pats[pats.length - 1] instanceof RegExp)) {
+    flags = pats.pop();
+  }
+  const source = pats.map(p => {
+    if (p instanceof KitPattern) return p.source;
+    if (p instanceof RegExp) return p.source;
+    return String(p);
+  }).join('');
+  return new RegExp(source, flags);
+}
+
+/**
+ * Alternate: match any one of the given patterns.
+ * @param {...(RegExp|string|KitPattern)} patterns
+ * @param {string} [flags='']
+ * @returns {RegExp}
+ */
+function alternate(...args) {
+  let flags = '';
+  const pats = [...args];
+  if (typeof pats[pats.length - 1] === 'string' && /^[gimsuy]*$/.test(pats[pats.length - 1])) {
+    flags = pats.pop();
+  }
+  const source = pats.map(p => {
+    if (p instanceof KitPattern) return p.source;
+    if (p instanceof RegExp) return `(?:${p.source})`;
+    return `(?:${escapeRegex(String(p))})`;
+  }).join('|');
+  return new RegExp(source, flags);
+}
+
+/**
+ * Wrap a pattern in a non-capturing group with a quantifier.
+ * @param {RegExp|string|KitPattern} pattern
+ * @param {string} quantifier - e.g. '+', '*', '?', '{2,5}'
+ * @returns {RegExp}
+ */
+function quantify(pattern, quantifier, flags = '') {
+  const src = _resolveInner(pattern);
+  return new RegExp(`(?:${src})${quantifier}`, flags);
+}
+
+/**
+ * Wrap a pattern in a capturing group.
+ */
+function capture(pattern, flags = '') {
+  const src = _resolveInner(pattern);
+  return new RegExp(`(${src})`, flags);
+}
+
+/**
+ * Wrap a pattern in a named capturing group.
+ */
+function namedCapture(name, pattern, flags = '') {
+  const src = _resolveInner(pattern);
+  return new RegExp(`(?<${name}>${src})`, flags);
+}
+
+/**
+ * Make a pattern optional.
+ */
+function optional(pattern, flags = '') {
+  const src = _resolveInner(pattern);
+  return new RegExp(`(?:${src})?`, flags);
+}
+
+/**
+ * Wrap a pattern with anchors.
+ */
+function anchored(pattern, flags = '') {
+  const src = _resolveInner(pattern);
+  return new RegExp(`^(?:${src})$`, flags);
+}
+
+/**
+ * Surround a pattern with lookahead/lookbehind fences.
+ * @param {RegExp|string} pattern - the core pattern
+ * @param {object} [fences]
+ * @param {string} [fences.before] - positive lookbehind
+ * @param {string} [fences.after]  - positive lookahead
+ */
+function fenced(pattern, fences = {}, flags = '') {
+  let src = _resolveInner(pattern);
+  if (fences.before) src = `(?<=${_resolveInner(fences.before)})${src}`;
+  if (fences.after)  src = `${src}(?=${_resolveInner(fences.after)})`;
+  return new RegExp(src, flags);
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 7: EXTRACT / TRANSFORM / REPLACE
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Extract all matches from a string.
+ * @param {string} input
+ * @param {RegExp|string|KitPattern} pattern
+ * @param {object} [options]
+ * @param {boolean} [options.groups=false]  - include capture groups
+ * @param {boolean} [options.named=false]   - include named groups
+ * @param {boolean} [options.index=false]   - include match indices
+ * @returns {Array}
+ */
+function extract(input, pattern, options = {}) {
+  const re = addFlags(_toRegex(pattern), 'g');
+  const results = [];
+  let m;
+  const reWithIdx = options.index ? addFlags(re, 'd') : re;
+  while ((m = reWithIdx.exec(input)) !== null) {
+    const entry = { match: m[0] };
+    if (options.groups && m.length > 1) entry.groups = m.slice(1);
+    if (options.named && m.groups) entry.named = { ...m.groups };
+    if (options.index) entry.index = m.index;
+    results.push(entry);
+  }
+  return results;
+}
+
+/**
+ * Extract and transform matches in one pass.
+ * @param {string} input
+ * @param {RegExp|string|KitPattern} pattern
+ * @param {function(match: string, groups: string[], named: object, index: number): *} transform
+ * @returns {Array}
+ */
+function extractMap(input, pattern, transform) {
+  const re = addFlags(_toRegex(pattern), 'g');
+  const results = [];
+  let m;
+  while ((m = re.exec(input)) !== null) {
+    results.push(transform(m[0], m.slice(1), m.groups || {}, m.index));
+  }
+  return results;
+}
+
+/**
+ * Replace matches using a pattern + transform function or string.
+ * Essentially a power version of String.replace with richer callbacks.
+ *
+ * @param {string} input
+ * @param {RegExp|string|KitPattern} pattern
+ * @param {string|function(match, groups, named, index, input): string} replacer
+ * @param {object} [options]
+ * @param {boolean} [options.global=true]
+ * @returns {string}
+ */
+function replace(input, pattern, replacer, options = {}) {
+  const global = options.global !== false;
+  let re = _toRegex(pattern);
+  if (global && !re.flags.includes('g')) re = addFlags(re, 'g');
+
+  if (typeof replacer === 'string') {
+    return input.replace(re, replacer);
+  }
+  return input.replace(re, (match, ...rest) => {
+    const groups = rest.slice(0, rest.length - 2);
+    const index  = rest[rest.length - 2];
+    const namedG = (typeof rest[rest.length - 1] === 'object' && rest[rest.length - 1]) || {};
+    return replacer(match, groups, namedG, index, input);
+  });
+}
+
+/**
+ * Extract-then-replace: apply a transform in place.
+ * Like replace() but you return undefined to keep the original match.
+ */
+function transform(input, pattern, transformer) {
+  return replace(input, pattern, (match, groups, named, index) => {
+    const result = transformer(match, groups, named, index);
+    return result === undefined ? match : String(result);
+  });
+}
+
+/**
+ * Split a string on a pattern, keeping delimiter groups.
+ * @param {string} input
+ * @param {RegExp|string|KitPattern} pattern
+ * @param {object} [options]
+ * @param {boolean} [options.keepDelimiters=false]
+ * @param {number} [options.limit]
+ * @returns {string[]}
+ */
+function splitOn(input, pattern, options = {}) {
+  const re  = _toRegex(pattern);
+  const lim = options.limit;
+  if (!options.keepDelimiters) {
+    return lim !== undefined ? input.split(re, lim) : input.split(re);
+  }
+  // Keep delimiters via capture group
+  const src = re.source.startsWith('(') ? re.source : `(${re.source})`;
+  const reCap = new RegExp(src, _mergeFlags(re.flags, 'g'));
+  const parts = input.split(reCap);
+  return lim !== undefined ? parts.slice(0, lim) : parts;
+}
+
+/**
+ * Find the first match with full details.
+ * @param {string} input
+ * @param {RegExp|string|KitPattern} pattern
+ * @returns {{ match: string, index: number, groups: string[], named: object }|null}
+ */
+function findFirst(input, pattern) {
+  const re = removeFlags(_toRegex(pattern), 'g');
+  const m = re.exec(input);
+  if (!m) return null;
+  return { match: m[0], index: m.index, groups: m.slice(1), named: m.groups || {} };
+}
+
+/**
+ * Find all matches with full details.
+ * @param {string} input
+ * @param {RegExp|string|KitPattern} pattern
+ * @returns {Array<{ match: string, index: number, groups: string[], named: object }>}
+ */
+function findAll(input, pattern) {
+  return extract(input, pattern, { groups: true, named: true, index: true });
+}
+
+/**
+ * Count the number of matches.
+ */
+function countMatches(input, pattern) {
+  const re = addFlags(_toRegex(pattern), 'g');
+  return (input.match(re) || []).length;
+}
+
+/**
+ * Test whether a string fully matches a pattern.
+ */
+function test(input, pattern) {
+  return _toRegex(pattern).test(input);
+}
+
+/**
+ * Test whether a string contains a pattern anywhere.
+ */
+function contains(input, pattern) {
+  return removeFlags(addFlags(_toRegex(pattern), ''), 'g').test(input);
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 8: VALIDATION ENGINE
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Validation rule: a named test with a custom error message.
+ * @typedef {{ pattern: RegExp|KitPattern, message: string, name?: string }} ValidationRule
+ */
+
+/**
+ * Validate a string against one or more rules.
+ * Returns detailed pass/fail results per rule.
+ *
+ * @param {string} input
+ * @param {ValidationRule[]} rules
+ * @returns {{ valid: boolean, errors: string[], results: Array<{name, passed, message}> }}
+ */
+function validate(input, rules) {
+  const results = rules.map(rule => {
+    const re = _toRegex(rule.pattern);
+    const passed = re.test(input);
+    return {
+      name:    rule.name || re.toString(),
+      passed,
+      message: passed ? null : rule.message || `Failed: ${re}`,
+    };
+  });
+  const errors = results.filter(r => !r.passed).map(r => r.message);
+  return { valid: errors.length === 0, errors, results };
+}
+
+/**
+ * Pre-built validators that return { valid, errors, results }.
+ */
+const Validators = {
+  email:      (s) => validate(s, [
+    { name: 'format',    pattern: Patterns.internet.EMAIL, message: 'Invalid email format' },
+  ]),
+  url:        (s) => validate(s, [
+    { name: 'format',    pattern: Patterns.internet.URL,   message: 'Invalid URL format' },
+  ]),
+  ipv4:       (s) => validate(s, [
+    { name: 'format',    pattern: anchored(Patterns.internet.IPV4), message: 'Invalid IPv4 address' },
+  ]),
+  semver:     (s) => validate(s, [
+    { name: 'format',    pattern: anchored(Patterns.code.SEMVER),   message: 'Invalid semver (expected x.y.z)' },
+  ]),
+  uuid:       (s) => validate(s, [
+    { name: 'format',    pattern: anchored(Patterns.code.UUID),     message: 'Invalid UUID' },
+  ]),
+  dateISO:    (s) => validate(s, [
+    { name: 'format',    pattern: anchored(Patterns.datetime.DATE_ISO), message: 'Invalid ISO date (expected YYYY-MM-DD)' },
+  ]),
+  hexColor:   (s) => validate(s, [
+    { name: 'format',    pattern: anchored(Patterns.code.HEX_COLOR),message: 'Invalid hex color' },
+  ]),
+  phoneUS:    (s) => validate(s, [
+    { name: 'format',    pattern: anchored(Patterns.personal.PHONE_US), message: 'Invalid US phone number' },
+  ]),
+  creditCard: (s) => validate(s, [
+    { name: 'format',    pattern: anchored(Patterns.personal.CREDIT_CARD), message: 'Invalid credit card number' },
+  ]),
+  slug:       (s) => validate(s, [
+    { name: 'format',    pattern: anchored(Patterns.internet.SLUG), message: 'Invalid slug (lowercase letters, numbers, hyphens only)' },
+  ]),
+
+  /**
+   * Password strength validator.
+   * @param {string} s
+   * @param {object} [opts]
+   * @param {number} [opts.minLength=8]
+   * @param {boolean} [opts.requireUpper=true]
+   * @param {boolean} [opts.requireLower=true]
+   * @param {boolean} [opts.requireDigit=true]
+   * @param {boolean} [opts.requireSpecial=true]
+   */
+  password: (s, opts = {}) => {
+    const min     = opts.minLength     !== undefined ? opts.minLength     : 8;
+    const upper   = opts.requireUpper  !== undefined ? opts.requireUpper  : true;
+    const lower   = opts.requireLower  !== undefined ? opts.requireLower  : true;
+    const digit   = opts.requireDigit  !== undefined ? opts.requireDigit  : true;
+    const special = opts.requireSpecial!== undefined ? opts.requireSpecial: true;
+    const rules = [
+      { name: 'minLength', pattern: new RegExp(`.{${min},}`),        message: `Must be at least ${min} characters` },
+    ];
+    if (upper)   rules.push({ name: 'uppercase', pattern: /[A-Z]/,           message: 'Must contain an uppercase letter' });
+    if (lower)   rules.push({ name: 'lowercase', pattern: /[a-z]/,           message: 'Must contain a lowercase letter' });
+    if (digit)   rules.push({ name: 'digit',     pattern: /\d/,              message: 'Must contain a digit' });
+    if (special) rules.push({ name: 'special',   pattern: /[!@#$%^&*(),.?":{}|<>]/, message: 'Must contain a special character' });
+    return validate(s, rules);
+  },
+
+  /**
+   * Build a custom validator from a rules array.
+   */
+  custom: (rules) => (s) => validate(s, rules),
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 9: TOKENIZER / LEXER
+// ────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {{ type: string, pattern: RegExp|string|KitPattern, transform?: function }} TokenRule
+ */
+
+/**
+ * Tokenize an input string using an ordered list of token rules.
+ * Rules are tried in order; first match wins.
+ *
+ * @param {string} input
+ * @param {TokenRule[]} rules
+ * @param {object} [options]
+ * @param {boolean} [options.skipUnknown=false] - skip unrecognized chars instead of error token
+ * @param {boolean} [options.includePositions=false]
+ * @returns {Array<{ type: string, value: string, raw: string, line?: number, col?: number }>}
+ */
+function tokenize(input, rules, options = {}) {
+  const compiled = rules.map(r => ({
+    ...r,
+    re: new RegExp('^(?:' + _toRegex(r.pattern).source + ')', _mergeFlags(_toRegex(r.pattern).flags, '')),
+  }));
+
+  const tokens = [];
+  let pos = 0;
+  let line = 1;
+  let col = 1;
+
+  while (pos < input.length) {
+    let matched = false;
+    const remaining = input.slice(pos);
+
+    for (const rule of compiled) {
+      const m = rule.re.exec(remaining);
+      if (m) {
+        const raw = m[0];
+        let value = raw;
+        if (rule.transform) value = rule.transform(raw, m.slice(1), m.groups || {});
+
+        const tok = { type: rule.type, value, raw };
+        if (options.includePositions) { tok.line = line; tok.col = col; }
+
+        // Update line/col
+        for (const ch of raw) {
+          if (ch === '\n') { line++; col = 1; }
+          else { col++; }
+        }
+
+        tokens.push(tok);
+        pos += raw.length;
+        matched = true;
+        break;
+      }
+    }
+
+    if (!matched) {
+      if (options.skipUnknown) {
+        pos++;
+      } else {
+        const ch = input[pos];
+        const tok = { type: 'UNKNOWN', value: ch, raw: ch };
+        if (options.includePositions) { tok.line = line; tok.col = col; }
+        tokens.push(tok);
+        col++;
+        pos++;
+      }
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Pre-built lexer for common programming language tokens.
+ */
+const CodeLexer = {
+  /**
+   * JavaScript-like token rules.
+   */
+  JS: [
+    { type: 'COMMENT_BLOCK', pattern: /\/\*[\s\S]*?\*\// },
+    { type: 'COMMENT_LINE',  pattern: /\/\/[^\n]*/ },
+    { type: 'STRING_DOUBLE', pattern: /"(?:[^"\\]|\\.)*"/ },
+    { type: 'STRING_SINGLE', pattern: /'(?:[^'\\]|\\.)*'/ },
+    { type: 'TEMPLATE',      pattern: /`(?:[^`\\]|\\.)*`/ },
+    { type: 'NUMBER',        pattern: /0x[0-9a-fA-F]+|0b[01]+|0o[0-7]+|\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/ },
+    { type: 'KEYWORD',       pattern: /\b(?:var|let|const|function|return|if|else|for|while|do|switch|case|break|continue|new|delete|typeof|instanceof|in|of|class|extends|import|export|default|async|await|try|catch|finally|throw|void|null|undefined|true|false|this|super)\b/ },
+    { type: 'IDENTIFIER',    pattern: /[a-zA-Z_$][a-zA-Z0-9_$]*/ },
+    { type: 'OPERATOR',      pattern: /===|!==|=>|<=|>=|&&|\|\||[+\-*/%^&|~<>!=?:.]/ },
+    { type: 'PUNCTUATION',   pattern: /[{}[\]();,]/ },
+    { type: 'WHITESPACE',    pattern: /\s+/ },
+  ],
+
+  /**
+   * Simple expression tokenizer (numbers, ops, parens, identifiers).
+   */
+  EXPR: [
+    { type: 'NUMBER',     pattern: /-?\d+(?:\.\d+)?/ },
+    { type: 'IDENTIFIER', pattern: /[a-zA-Z_]\w*/ },
+    { type: 'OPERATOR',   pattern: /[+\-*/%^]/ },
+    { type: 'LPAREN',     pattern: /\(/ },
+    { type: 'RPAREN',     pattern: /\)/ },
+    { type: 'COMMA',      pattern: /,/ },
+    { type: 'WHITESPACE', pattern: /\s+/ },
+  ],
+
+  /**
+   * CSV tokenizer.
+   */
+  CSV: [
+    { type: 'QUOTED',    pattern: /"(?:[^"\\]|\\.)*"/, transform: v => v.slice(1, -1).replace(/""/g, '"') },
+    { type: 'VALUE',     pattern: /[^,\n\r"]+/ },
+    { type: 'COMMA',     pattern: /,/ },
+    { type: 'NEWLINE',   pattern: /\r?\n/ },
+  ],
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 10: FUZZY / APPROXIMATE MATCHING
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Levenshtein distance between two strings.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) =>
+    Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0))
+  );
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i-1] === b[j-1]
+        ? dp[i-1][j-1]
+        : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
+    }
+  }
+  return dp[m][n];
+}
+
+/**
+ * Similarity score 0–1 based on Levenshtein.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function similarity(a, b) {
+  const maxLen = Math.max(a.length, b.length);
+  if (maxLen === 0) return 1;
+  return 1 - levenshtein(a, b) / maxLen;
+}
+
+/**
+ * Build a regex that allows up to `maxErrors` character substitutions/insertions/deletions
+ * via pattern expansion (works well for short patterns, up to ~30 chars).
+ *
+ * Strategy: generate alternations with deletions and substitutions.
+ * For fuzzy matching of longer text, use fuzzySearch() instead.
+ *
+ * @param {string} word
+ * @param {number} [maxErrors=1]
+ * @param {string} [flags='i']
+ * @returns {RegExp}
+ */
+function fuzzyPattern(word, maxErrors = 1, flags = 'i') {
+  if (maxErrors === 0) return new RegExp(escapeRegex(word), flags);
+  // Generate all variants with up to maxErrors single-char edits
+  const variants = new Set();
+  variants.add(escapeRegex(word));
+
+  function _edits1(w) {
+    const res = new Set();
+    // Deletions
+    for (let i = 0; i < w.length; i++)
+      res.add(escapeRegex(w.slice(0, i) + w.slice(i + 1)));
+    // Substitutions (use . to match any char in place)
+    for (let i = 0; i < w.length; i++)
+      res.add(escapeRegex(w.slice(0, i)) + '.' + escapeRegex(w.slice(i + 1)));
+    // Insertions (one extra any-char)
+    for (let i = 0; i <= w.length; i++)
+      res.add(escapeRegex(w.slice(0, i)) + '.?' + escapeRegex(w.slice(i)));
+    // Transpositions
+    for (let i = 0; i < w.length - 1; i++)
+      res.add(escapeRegex(w.slice(0, i) + w[i+1] + w[i] + w.slice(i + 2)));
+    return res;
+  }
+
+  let frontier = new Set([word]);
+  for (let e = 0; e < maxErrors; e++) {
+    const next = new Set();
+    for (const w of frontier) { for (const v of _edits1(w)) { variants.add(v); next.add(v); } }
+    frontier = next;
+  }
+
+  const src = [...variants].join('|');
+  return new RegExp(`(?:${src})`, flags);
+}
+
+/**
+ * Fuzzy search: find all approximate matches of `query` in `text`.
+ * Uses a sliding window + Levenshtein distance.
+ *
+ * @param {string} text
+ * @param {string} query
+ * @param {object} [options]
+ * @param {number} [options.maxErrors=1]       - max edit distance
+ * @param {number} [options.minSimilarity]     - alternative: min similarity 0-1
+ * @returns {Array<{ match: string, index: number, distance: number, similarity: number }>}
+ */
+function fuzzySearch(text, query, options = {}) {
+  const maxErr = options.maxErrors !== undefined ? options.maxErrors : 1;
+  const minSim = options.minSimilarity;
+  const qlen   = query.length;
+  const results = [];
+  const seen    = new Set();
+
+  // Try windows of sizes qlen-maxErr to qlen+maxErr
+  for (let wlen = Math.max(1, qlen - maxErr); wlen <= qlen + maxErr; wlen++) {
+    for (let i = 0; i <= text.length - wlen; i++) {
+      const candidate = text.slice(i, i + wlen);
+      const dist = levenshtein(candidate.toLowerCase(), query.toLowerCase());
+      const sim  = 1 - dist / Math.max(candidate.length, query.length);
+      const key  = `${i}:${i + wlen}`;
+      if (dist <= maxErr && (minSim === undefined || sim >= minSim) && !seen.has(key)) {
+        seen.add(key);
+        results.push({ match: candidate, index: i, distance: dist, similarity: parseFloat(sim.toFixed(4)) });
+      }
+    }
+  }
+
+  // Sort by distance, then index
+  results.sort((a, b) => a.distance - b.distance || a.index - b.index);
+  return results;
+}
+
+/**
+ * Fuzzy filter: filter a list of strings to those approximately matching a query.
+ * @param {string[]} list
+ * @param {string} query
+ * @param {object} [options]
+ * @param {number} [options.maxErrors=1]
+ * @param {number} [options.minSimilarity=0.5]
+ * @returns {Array<{ item: string, distance: number, similarity: number }>}
+ */
+function fuzzyFilter(list, query, options = {}) {
+  const maxErr = options.maxErrors  !== undefined ? options.maxErrors  : 1;
+  const minSim = options.minSimilarity !== undefined ? options.minSimilarity : 0.5;
+  return list
+    .map(item => {
+      const dist = levenshtein(item.toLowerCase(), query.toLowerCase());
+      const sim  = 1 - dist / Math.max(item.length, query.length);
+      return { item, distance: dist, similarity: parseFloat(sim.toFixed(4)) };
+    })
+    .filter(r => r.distance <= maxErr || r.similarity >= minSim)
+    .sort((a, b) => b.similarity - a.similarity || a.distance - b.distance);
+}
+
+/**
+ * Highlight fuzzy matches in a string using a wrapper function.
+ * @param {string} text
+ * @param {string} query
+ * @param {function(match: string): string} [highlighter] - default wraps in **
+ * @param {object} [options]
+ * @returns {string}
+ */
+function fuzzyHighlight(text, query, highlighter, options = {}) {
+  const wrap  = highlighter || (m => `**${m}**`);
+  const matches = fuzzySearch(text, query, options);
+  if (!matches.length) return text;
+
+  // Build non-overlapping replacement ranges
+  const ranges = [];
+  for (const m of matches) {
+    const end = m.index + m.match.length;
+    if (!ranges.some(r => m.index < r.end && end > r.start)) {
+      ranges.push({ start: m.index, end });
+    }
+  }
+  ranges.sort((a, b) => a.start - b.start);
+
+  let result = '';
+  let cursor = 0;
+  for (const { start, end } of ranges) {
+    result += text.slice(cursor, start) + wrap(text.slice(start, end));
+    cursor = end;
+  }
+  result += text.slice(cursor);
+  return result;
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 11: UTILITY FUNCTIONS
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Highlight all regex matches in a string.
+ * @param {string} input
+ * @param {RegExp|string|KitPattern} pattern
+ * @param {function(match: string): string} [highlighter]
+ * @returns {string}
+ */
+function highlight(input, pattern, highlighter) {
+  const wrap = highlighter || (m => `[${m}]`);
+  return replace(input, pattern, (match) => wrap(match));
+}
+
+/**
+ * Redact all matches with a mask string.
+ * @param {string} input
+ * @param {RegExp|string|KitPattern} pattern
+ * @param {string} [mask='[REDACTED]']
+ * @returns {string}
+ */
+function redact(input, pattern, mask = '[REDACTED]') {
+  return replace(input, pattern, mask);
+}
+
+/**
+ * Get a named group from the first match.
+ * @param {string} input
+ * @param {RegExp|string|KitPattern} pattern
+ * @param {string} groupName
+ * @returns {string|null}
+ */
+function namedGroup(input, pattern, groupName) {
+  const m = _toRegex(pattern).exec(input);
+  return m && m.groups ? (m.groups[groupName] || null) : null;
+}
+
+/**
+ * Explain a regex pattern in plain English (best-effort).
+ * @param {RegExp|string|KitPattern} pattern
+ * @returns {string}
+ */
+function explain(pattern) {
+  const re = _toRegex(pattern);
+  const src = re.source;
+  const flags = re.flags;
+
+  const flagDesc = {
+    g: 'global (find all matches)',
+    i: 'case-insensitive',
+    m: 'multiline (^ and $ match line boundaries)',
+    s: 'dotAll (. matches newlines)',
+    u: 'unicode',
+    y: 'sticky (match from lastIndex)',
+  };
+
+  const parts = [];
+  if (flags) {
+    parts.push('Flags: ' + flags.split('').map(f => flagDesc[f] || f).join(', '));
+  }
+
+  // Simple token-by-token explanation
+  const tokenMap = [
+    [/^\^/,             () => 'Start of string'],
+    [/^\$/,             () => 'End of string'],
+    [/^\\b/,            () => 'Word boundary'],
+    [/^\\B/,            () => 'Non-word boundary'],
+    [/^\\d/,            () => 'Any digit [0-9]'],
+    [/^\\D/,            () => 'Any non-digit'],
+    [/^\\w/,            () => 'Any word character [a-zA-Z0-9_]'],
+    [/^\\W/,            () => 'Any non-word character'],
+    [/^\\s/,            () => 'Any whitespace'],
+    [/^\\S/,            () => 'Any non-whitespace'],
+    [/^\\n/,            () => 'Newline'],
+    [/^\\t/,            () => 'Tab'],
+    [/^\./,             () => 'Any character (except newline)'],
+    [/^\?\?/,           () => 'Zero or one (lazy)'],
+    [/^\?/,             () => 'Zero or one (optional)'],
+    [/^\*\?/,           () => 'Zero or more (lazy)'],
+    [/^\*/,             () => 'Zero or more'],
+    [/^\+\?/,           () => 'One or more (lazy)'],
+    [/^\+/,             () => 'One or more'],
+    [/^\{(\d+),(\d+)\}\?/, m => `Between ${m[1]} and ${m[2]} times (lazy)`],
+    [/^\{(\d+),(\d+)\}/,   m => `Between ${m[1]} and ${m[2]} times`],
+    [/^\{(\d+),\}/,        m => `At least ${m[1]} times`],
+    [/^\{(\d+)\}/,         m => `Exactly ${m[1]} times`],
+    [/^\(\?<([^>]+)>/,     m => `Named capture group "${m[1]}"`],
+    [/^\(\?:/,          () => 'Non-capturing group: ('],
+    [/^\(\?=/,          () => 'Positive lookahead: ('],
+    [/^\(\?!/,          () => 'Negative lookahead: ('],
+    [/^\(\?<=/,         () => 'Positive lookbehind: ('],
+    [/^\(\?<!/,         () => 'Negative lookbehind: ('],
+    [/^\(/,             () => 'Capturing group: ('],
+    [/^\)/,             () => 'End group: )'],
+    [/^\|/,             () => 'OR'],
+    [/^\[(\^)?([^\]]+)\]/, m => `Character class${m[1] ? ' NOT' : ''}: [${m[2]}]`],
+    [/^\\(.)/,             m => `Literal "${m[1]}"`],
+    [/^([a-zA-Z0-9 ])/,    m => `Literal "${m[1]}"`],
+  ];
+
+  const tokenParts = [];
+  let remaining = src;
+  let safety = 0;
+  while (remaining.length && safety++ < 500) {
+    let found = false;
+    for (const [re, fn] of tokenMap) {
+      const m = re.exec(remaining);
+      if (m) {
+        tokenParts.push(fn(m));
+        remaining = remaining.slice(m[0].length);
+        found = true;
+        break;
+      }
+    }
+    if (!found) { tokenParts.push(`"${remaining[0]}"`); remaining = remaining.slice(1); }
+  }
+
+  if (tokenParts.length) parts.push('Pattern: ' + tokenParts.join(' → '));
+  return parts.join('\n');
+}
+
+/**
+ * Benchmark: measure how long a pattern takes on a given input (N iterations).
+ * @param {string} input
+ * @param {RegExp|string|KitPattern} pattern
+ * @param {number} [iterations=10000]
+ * @returns {{ ms: number, perOpNs: number, opsPerSec: number }}
+ */
+function benchmark(input, pattern, iterations = 10000) {
+  const re = addFlags(_toRegex(pattern), 'g');
+  const start = Date.now();
+  for (let i = 0; i < iterations; i++) { re.lastIndex = 0; while (re.exec(input)) {} }
+  const ms = Date.now() - start;
+  const perOpNs  = (ms * 1e6) / iterations;
+  const opsPerSec = Math.round(1e9 / perOpNs);
+  return { ms, perOpNs: parseFloat(perOpNs.toFixed(2)), opsPerSec };
+}
+
+// ────────────────────────────────────────────────────────────
+//  EXPORTS
+// ────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+    // ── Utilities ───────────────────────────────────
+    escapeRegex,
+    withFlags,
+    addFlags,
+    removeFlags,
+    Flags,
+
+    // ── Pattern Registry ────────────────────────────
+    registerPattern,
+    unregisterPattern,
+    getPattern,
+    listPatterns,
+
+    // ── Built-in Pattern Packs ──────────────────────
+    Patterns,
+
+    // ── Builder API ─────────────────────────────────
+    KitPattern,
+
+    // ── Composition ─────────────────────────────────
+    concat,
+    alternate,
+    quantify,
+    capture,
+    namedCapture,
+    optional,
+    anchored,
+    fenced,
+
+    // ── Extract / Transform / Replace ───────────────
+    extract,
+    extractMap,
+    replace,
+    transform,
+    splitOn,
+    findFirst,
+    findAll,
+    countMatches,
+    test,
+    contains,
+    highlight,
+    redact,
+    namedGroup,
+
+    // ── Validation ──────────────────────────────────
+    validate,
+    Validators,
+
+    // ── Tokenizer / Lexer ───────────────────────────
+    tokenize,
+    CodeLexer,
+
+    // ── Fuzzy Matching ──────────────────────────────
+    levenshtein,
+    similarity,
+    fuzzyPattern,
+    fuzzySearch,
+    fuzzyFilter,
+    fuzzyHighlight,
+
+    // ── Dev Tools ───────────────────────────────────
+    explain,
+    benchmark,
+  }
+};