novac 2.0.1 → 2.2.0

package/novac/kits/kitformat/kitdef.js

@@ -0,0 +1,1485 @@
+'use strict';
+
+// ============================================================
+//  kitformat.js  —  A comprehensive formatting utility module
+//  module.exports = { kitdef: { ...all exports } }
+// ============================================================
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 1: CUSTOM FORMAT SPEC REGISTRY
+//  Register/unregister custom % specifiers globally
+// ────────────────────────────────────────────────────────────
+
+const _customSpecs = new Map();
+
+/**
+ * Register a custom printf-style format specifier.
+ * @param {string} char - Single character (e.g. 'q')
+ * @param {function(value, flags, width, precision): string} handler
+ */
+function registerSpec(char, handler) {
+  if (typeof char !== 'string' || char.length !== 1)
+    throw new TypeError('registerSpec: char must be a single character');
+  if (typeof handler !== 'function')
+    throw new TypeError('registerSpec: handler must be a function');
+  _customSpecs.set(char, handler);
+}
+
+/**
+ * Unregister a custom format specifier.
+ * @param {string} char
+ */
+function unregisterSpec(char) {
+  _customSpecs.delete(char);
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 2: PRINTF-STYLE FORMATTING
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Internal: apply width/precision/flags padding to a formatted string chunk.
+ */
+function _applyWidth(str, flags, width, leftAlign) {
+  if (width !== null && str.length < width) {
+    const pad = flags.includes('0') && !leftAlign ? '0' : ' ';
+    if (leftAlign) {
+      str = str.padEnd(width, ' ');
+    } else {
+      if (pad === '0' && (str[0] === '-' || str[0] === '+' || str[0] === ' ')) {
+        str = str[0] + str.slice(1).padStart(width - 1, '0');
+      } else {
+        str = str.padStart(width, pad);
+      }
+    }
+  }
+  return str;
+}
+
+/**
+ * printf(fmt, ...args) — C/C++ style printf formatting.
+ *
+ * Supported specifiers:
+ *   %d / %i  — signed decimal integer
+ *   %u       — unsigned decimal integer
+ *   %f       — fixed-point float
+ *   %e / %E  — scientific notation
+ *   %g / %G  — shorter of %f / %e
+ *   %s       — string
+ *   %S       — string UPPERCASE
+ *   %c       — character (number → char)
+ *   %x / %X  — hex (lower/upper)
+ *   %o       — octal
+ *   %b       — binary
+ *   %p       — "pointer" style (0x + hex)
+ *   %j       — JSON.stringify
+ *   %%       — literal %
+ *
+ * Flags: -, +, ' ' (space), 0, #
+ * Width & precision supported.
+ * Custom specs registered via registerSpec() also work here.
+ *
+ * @param {string} fmt
+ * @param {...*} args
+ * @returns {string}
+ */
+function printf(fmt, ...args) {
+  let argIdx = 0;
+  // Regex: %[flags][width][.precision]specifier
+  return fmt.replace(/%(\d+\$)?([-+ #0]*)(\*|\d+)?(?:\.(\*|\d+))?([%diufFeEgGsSscxXobpj]|.)/g,
+    (match, argPos, flagsStr, widthStr, precStr, spec) => {
+      if (spec === '%') return '%';
+
+      const flags = flagsStr || '';
+      const leftAlign = flags.includes('-');
+
+      // Width
+      let width = null;
+      if (widthStr === '*') { width = Number(args[argIdx++]); }
+      else if (widthStr) { width = parseInt(widthStr, 10); }
+
+      // Precision
+      let prec = null;
+      if (precStr === '*') { prec = Number(args[argIdx++]); }
+      else if (precStr !== undefined && precStr !== null) { prec = parseInt(precStr, 10); }
+
+      // Positional arg index (%1$d style)
+      let val;
+      if (argPos) {
+        val = args[parseInt(argPos) - 1];
+      } else {
+        val = args[argIdx++];
+      }
+
+      let out = '';
+
+      // Custom spec?
+      if (_customSpecs.has(spec)) {
+        out = String(_customSpecs.get(spec)(val, flags, width, prec));
+        return _applyWidth(out, flags, width, leftAlign);
+      }
+
+      switch (spec) {
+        case 'd': case 'i': {
+          let n = Math.trunc(Number(val));
+          const sign = n < 0 ? '-' : flags.includes('+') ? '+' : flags.includes(' ') ? ' ' : '';
+          out = Math.abs(n).toString(10);
+          if (prec !== null) out = out.padStart(prec, '0');
+          out = sign + out;
+          break;
+        }
+        case 'u': {
+          let n = Math.trunc(Math.abs(Number(val)));
+          out = n.toString(10);
+          if (prec !== null) out = out.padStart(prec, '0');
+          break;
+        }
+        case 'f': {
+          const p = prec !== null ? prec : 6;
+          let n = Number(val);
+          const sign = n < 0 ? '-' : flags.includes('+') ? '+' : flags.includes(' ') ? ' ' : '';
+          out = sign + Math.abs(n).toFixed(p);
+          break;
+        }
+        case 'e': case 'E': {
+          const p = prec !== null ? prec : 6;
+          let n = Number(val);
+          const sign = n < 0 ? '-' : flags.includes('+') ? '+' : flags.includes(' ') ? ' ' : '';
+          out = sign + Math.abs(n).toExponential(p);
+          if (spec === 'E') out = out.toUpperCase();
+          break;
+        }
+        case 'g': case 'G': {
+          const p = prec !== null ? (prec || 1) : 6;
+          let n = Number(val);
+          const sign = n < 0 ? '-' : flags.includes('+') ? '+' : flags.includes(' ') ? ' ' : '';
+          const abs = Math.abs(n);
+          const exp = Math.floor(Math.log10(abs || 1));
+          out = sign + (exp < -4 || exp >= p ? abs.toExponential(p - 1) : abs.toPrecision(p));
+          // strip trailing zeros unless # flag
+          if (!flags.includes('#')) out = out.replace(/(\.\d*?)0+(e|$)/, '$1$2').replace(/\.$/, '');
+          if (spec === 'G') out = out.toUpperCase();
+          break;
+        }
+        case 's': {
+          out = String(val == null ? '' : val);
+          if (prec !== null) out = out.slice(0, prec);
+          break;
+        }
+        case 'S': {
+          out = String(val == null ? '' : val).toUpperCase();
+          if (prec !== null) out = out.slice(0, prec);
+          break;
+        }
+        case 'c': {
+          out = typeof val === 'number' ? String.fromCharCode(val) : String(val)[0] || '';
+          break;
+        }
+        case 'x': case 'X': {
+          let n = Math.trunc(Math.abs(Number(val)));
+          out = n.toString(16);
+          if (prec !== null) out = out.padStart(prec, '0');
+          if (flags.includes('#')) out = '0x' + out;
+          if (spec === 'X') out = out.toUpperCase();
+          break;
+        }
+        case 'o': {
+          let n = Math.trunc(Math.abs(Number(val)));
+          out = n.toString(8);
+          if (prec !== null) out = out.padStart(prec, '0');
+          if (flags.includes('#') && out[0] !== '0') out = '0' + out;
+          break;
+        }
+        case 'b': {
+          let n = Math.trunc(Math.abs(Number(val)));
+          out = n.toString(2);
+          if (prec !== null) out = out.padStart(prec, '0');
+          if (flags.includes('#')) out = '0b' + out;
+          break;
+        }
+        case 'p': {
+          let n = Math.trunc(Math.abs(Number(val)));
+          out = '0x' + n.toString(16).toUpperCase().padStart(8, '0');
+          break;
+        }
+        case 'j': {
+          out = JSON.stringify(val);
+          if (prec !== null) out = out.slice(0, prec);
+          break;
+        }
+        default:
+          out = match; // unknown spec → pass through
+      }
+
+      return _applyWidth(out, flags, width, leftAlign);
+    }
+  );
+}
+
+/**
+ * sprintf alias — same as printf.
+ * @param {string} fmt
+ * @param {...*} args
+ * @returns {string}
+ */
+const sprintf = printf;
+
+/**
+ * fmt`template ${val}` — tagged template literal using printf under the hood.
+ * Each interpolation is treated as %s by default, but you can prefix the
+ * placeholder with a format string:  fmt`${'%05d' + n}`  isn't ideal, so
+ * instead use: fmt(['%d', '%s'], n, s)  syntax (see fmtArr).
+ */
+function fmt(strings, ...values) {
+  let result = '';
+  strings.forEach((str, i) => {
+    result += str;
+    if (i < values.length) result += String(values[i]);
+  });
+  return result;
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 3: STRING PADDING / ALIGNMENT / TRUNCATION
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Pad a string on the left to a given width.
+ * @param {string} str
+ * @param {number} width
+ * @param {string} [char=' ']
+ * @returns {string}
+ */
+function padLeft(str, width, char = ' ') {
+  return String(str).padStart(width, char);
+}
+
+/**
+ * Pad a string on the right to a given width.
+ */
+function padRight(str, width, char = ' ') {
+  return String(str).padEnd(width, char);
+}
+
+/**
+ * Center a string within a given width.
+ * @param {string} str
+ * @param {number} width
+ * @param {string} [char=' ']
+ * @returns {string}
+ */
+function padCenter(str, width, char = ' ') {
+  str = String(str);
+  if (str.length >= width) return str;
+  const total = width - str.length;
+  const left = Math.floor(total / 2);
+  const right = total - left;
+  return char.repeat(left) + str + char.repeat(right);
+}
+
+/**
+ * Truncate a string to maxLen, appending ellipsis if truncated.
+ * @param {string} str
+ * @param {number} maxLen
+ * @param {string} [ellipsis='…']
+ * @returns {string}
+ */
+function truncate(str, maxLen, ellipsis = '…') {
+  str = String(str);
+  if (str.length <= maxLen) return str;
+  return str.slice(0, Math.max(0, maxLen - ellipsis.length)) + ellipsis;
+}
+
+/**
+ * Truncate from the left side.
+ */
+function truncateLeft(str, maxLen, ellipsis = '…') {
+  str = String(str);
+  if (str.length <= maxLen) return str;
+  return ellipsis + str.slice(str.length - maxLen + ellipsis.length);
+}
+
+/**
+ * Truncate in the middle.
+ */
+function truncateMid(str, maxLen, ellipsis = '…') {
+  str = String(str);
+  if (str.length <= maxLen) return str;
+  const half = Math.floor((maxLen - ellipsis.length) / 2);
+  return str.slice(0, half) + ellipsis + str.slice(str.length - (maxLen - ellipsis.length - half));
+}
+
+/**
+ * Wrap a string to a given line width, breaking at word boundaries.
+ * @param {string} str
+ * @param {number} width
+ * @param {string} [newline='\n']
+ * @returns {string}
+ */
+function wordWrap(str, width, newline = '\n') {
+  const words = str.split(/\s+/);
+  const lines = [];
+  let current = '';
+  for (const word of words) {
+    if (!current) {
+      current = word;
+    } else if (current.length + 1 + word.length <= width) {
+      current += ' ' + word;
+    } else {
+      lines.push(current);
+      current = word;
+    }
+  }
+  if (current) lines.push(current);
+  return lines.join(newline);
+}
+
+/**
+ * Repeat a string n times.
+ */
+function repeat(str, n) {
+  return String(str).repeat(n);
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 4: NUMBER FORMATTING
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Format a number with thousands separators.
+ * @param {number} n
+ * @param {string} [sep=',']
+ * @param {string} [dec='.']
+ * @returns {string}
+ */
+function thousands(n, sep = ',', dec = '.') {
+  const [intPart, fracPart] = String(Number(n)).split('.');
+  const formatted = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, sep);
+  return fracPart !== undefined ? formatted + dec + fracPart : formatted;
+}
+
+/**
+ * Format a number as currency.
+ * @param {number} n
+ * @param {string} [symbol='$']
+ * @param {number} [decimals=2]
+ * @param {string} [thousandsSep=',']
+ * @param {string} [decSep='.']
+ * @returns {string}
+ */
+function currency(n, symbol = '$', decimals = 2, thousandsSep = ',', decSep = '.') {
+  const neg = n < 0;
+  const abs = Math.abs(Number(n)).toFixed(decimals);
+  const [intPart, fracPart] = abs.split('.');
+  const formatted = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, thousandsSep);
+  const result = symbol + formatted + decSep + fracPart;
+  return neg ? '-' + result : result;
+}
+
+/**
+ * Format a number in scientific notation.
+ * @param {number} n
+ * @param {number} [precision=4]
+ * @returns {string}
+ */
+function scientific(n, precision = 4) {
+  return Number(n).toExponential(precision);
+}
+
+/**
+ * Format bytes into human-readable size.
+ * @param {number} bytes
+ * @param {number} [decimals=2]
+ * @param {boolean} [si=false] - true=1000-based, false=1024-based
+ * @returns {string}
+ */
+function fileSize(bytes, decimals = 2, si = false) {
+  const base = si ? 1000 : 1024;
+  const units = si
+    ? ['B', 'kB', 'MB', 'GB', 'TB', 'PB']
+    : ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB'];
+  if (Math.abs(bytes) < base) return bytes + ' B';
+  let u = -1;
+  let n = bytes;
+  do { n /= base; u++; } while (Math.abs(n) >= base && u < units.length - 2);
+  return n.toFixed(decimals) + ' ' + units[u + 1];
+}
+
+/**
+ * Format a number as percentage.
+ * @param {number} n - value between 0 and 1 (or 0–100 if raw=true)
+ * @param {number} [decimals=1]
+ * @param {boolean} [raw=false]
+ * @returns {string}
+ */
+function percent(n, decimals = 1, raw = false) {
+  const val = raw ? Number(n) : Number(n) * 100;
+  return val.toFixed(decimals) + '%';
+}
+
+/**
+ * Format a number with a fixed number of decimal places.
+ * @param {number} n
+ * @param {number} [decimals=2]
+ * @returns {string}
+ */
+function fixed(n, decimals = 2) {
+  return Number(n).toFixed(decimals);
+}
+
+/**
+ * Format a number in compact notation (1K, 2.5M, etc).
+ * @param {number} n
+ * @param {number} [decimals=1]
+ * @returns {string}
+ */
+function compact(n, decimals = 1) {
+  const abs = Math.abs(Number(n));
+  const sign = n < 0 ? '-' : '';
+  if (abs >= 1e12) return sign + (abs / 1e12).toFixed(decimals) + 'T';
+  if (abs >= 1e9)  return sign + (abs / 1e9).toFixed(decimals) + 'B';
+  if (abs >= 1e6)  return sign + (abs / 1e6).toFixed(decimals) + 'M';
+  if (abs >= 1e3)  return sign + (abs / 1e3).toFixed(decimals) + 'K';
+  return sign + abs.toFixed(decimals);
+}
+
+/**
+ * Format as ordinal (1st, 2nd, 3rd, 4th…).
+ * @param {number} n
+ * @returns {string}
+ */
+function ordinal(n) {
+  n = Math.trunc(Number(n));
+  const abs = Math.abs(n);
+  const mod100 = abs % 100;
+  const mod10 = abs % 10;
+  if (mod100 >= 11 && mod100 <= 13) return n + 'th';
+  if (mod10 === 1) return n + 'st';
+  if (mod10 === 2) return n + 'nd';
+  if (mod10 === 3) return n + 'rd';
+  return n + 'th';
+}
+
+/**
+ * Format as Roman numerals (1–3999).
+ * @param {number} n
+ * @returns {string}
+ */
+function roman(n) {
+  n = Math.trunc(Number(n));
+  if (n < 1 || n > 3999) return String(n);
+  const vals = [1000,900,500,400,100,90,50,40,10,9,5,4,1];
+  const syms = ['M','CM','D','CD','C','XC','L','XL','X','IX','V','IV','I'];
+  let out = '';
+  for (let i = 0; i < vals.length; i++) {
+    while (n >= vals[i]) { out += syms[i]; n -= vals[i]; }
+  }
+  return out;
+}
+
+/**
+ * Format a number in a given radix with optional prefix.
+ * @param {number} n
+ * @param {number} radix
+ * @param {string} [prefix='']
+ * @param {number} [minWidth=0]
+ * @returns {string}
+ */
+function radixFmt(n, radix, prefix = '', minWidth = 0) {
+  const out = Math.trunc(Math.abs(Number(n))).toString(radix).toUpperCase();
+  return prefix + out.padStart(minWidth, '0');
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 5: DATE / TIME FORMATTING
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Format a Date using a strftime-like format string.
+ *
+ * Tokens:
+ *   %Y  4-digit year          %y  2-digit year
+ *   %m  month 01-12           %n  month 1-12 (no pad)
+ *   %B  full month name       %b  short month name
+ *   %d  day 01-31             %e  day 1-31 (no pad)
+ *   %A  full weekday name     %a  short weekday name
+ *   %H  hour 00-23            %I  hour 01-12
+ *   %M  minute 00-59          %S  second 00-59
+ *   %L  milliseconds 000-999
+ *   %p  AM/PM                 %P  am/pm
+ *   %Z  timezone offset (+HH:MM)
+ *   %s  Unix timestamp (seconds)
+ *   %j  day of year 001-366
+ *   %W  week of year 00-53
+ *   %q  quarter (1-4)
+ *   %%  literal %
+ *
+ * @param {Date|number|string} date
+ * @param {string} fmt
+ * @param {object} [options]
+ * @param {string} [options.locale='en'] - locale for month/day names
+ * @returns {string}
+ */
+function dateFormat(date, fmt, options = {}) {
+  const d = date instanceof Date ? date : new Date(date);
+  const locale = options.locale || 'en';
+
+  const MONTHS_LONG  = _monthNames(locale, 'long');
+  const MONTHS_SHORT = _monthNames(locale, 'short');
+  const DAYS_LONG    = _dayNames(locale, 'long');
+  const DAYS_SHORT   = _dayNames(locale, 'short');
+
+  const Y  = d.getFullYear();
+  const M  = d.getMonth();       // 0-based
+  const D  = d.getDate();
+  const wd = d.getDay();         // 0=Sun
+  const H  = d.getHours();
+  const min= d.getMinutes();
+  const sec= d.getSeconds();
+  const ms = d.getMilliseconds();
+
+  const h12 = H % 12 || 12;
+  const dayOfYear = Math.floor((d - new Date(Y, 0, 0)) / 86400000);
+  const weekOfYear= Math.floor(dayOfYear / 7);
+  const quarter   = Math.floor(M / 3) + 1;
+
+  const offset = -d.getTimezoneOffset();
+  const offSign = offset >= 0 ? '+' : '-';
+  const offH = String(Math.floor(Math.abs(offset) / 60)).padStart(2, '0');
+  const offM = String(Math.abs(offset) % 60).padStart(2, '0');
+
+  return fmt.replace(/%%|%[YymnBbdteAaHIMSLpPZsjWq]/g, (tok) => {
+    switch (tok) {
+      case '%%': return '%';
+      case '%Y': return String(Y);
+      case '%y': return String(Y).slice(-2);
+      case '%m': return String(M + 1).padStart(2, '0');
+      case '%n': return String(M + 1);
+      case '%B': return MONTHS_LONG[M];
+      case '%b': return MONTHS_SHORT[M];
+      case '%d': return String(D).padStart(2, '0');
+      case '%e': return String(D);
+      case '%A': return DAYS_LONG[wd];
+      case '%a': return DAYS_SHORT[wd];
+      case '%H': return String(H).padStart(2, '0');
+      case '%I': return String(h12).padStart(2, '0');
+      case '%M': return String(min).padStart(2, '0');
+      case '%S': return String(sec).padStart(2, '0');
+      case '%L': return String(ms).padStart(3, '0');
+      case '%p': return H < 12 ? 'AM' : 'PM';
+      case '%P': return H < 12 ? 'am' : 'pm';
+      case '%Z': return offSign + offH + ':' + offM;
+      case '%s': return String(Math.floor(d.getTime() / 1000));
+      case '%j': return String(dayOfYear).padStart(3, '0');
+      case '%W': return String(weekOfYear).padStart(2, '0');
+      case '%q': return String(quarter);
+      default:   return tok;
+    }
+  });
+}
+
+/**
+ * Format a duration (milliseconds) into human-readable text.
+ * @param {number} ms  - duration in milliseconds
+ * @param {object} [options]
+ * @param {'short'|'long'} [options.style='short']
+ * @param {boolean} [options.leading=false] - include zero units
+ * @returns {string}
+ */
+function duration(ms, options = {}) {
+  const style   = options.style || 'short';
+  const leading = options.leading || false;
+  const neg = ms < 0;
+  let t = Math.abs(ms);
+
+  const parts = [
+    { val: Math.floor(t / 86400000), short: 'd',  long: ' day' },
+    { val: Math.floor((t % 86400000) / 3600000), short: 'h',  long: ' hour' },
+    { val: Math.floor((t % 3600000) / 60000),   short: 'm',  long: ' minute' },
+    { val: Math.floor((t % 60000) / 1000),       short: 's',  long: ' second' },
+    { val: t % 1000,                             short: 'ms', long: ' millisecond' },
+  ];
+
+  let out = parts
+    .filter(p => leading ? true : p.val > 0)
+    .map(p => {
+      const unit = style === 'long'
+        ? p.long + (p.val !== 1 ? 's' : '')
+        : p.short;
+      return p.val + unit;
+    })
+    .join(style === 'long' ? ', ' : ' ');
+
+  if (!out) out = style === 'long' ? '0 milliseconds' : '0ms';
+  return neg ? '-' + out : out;
+}
+
+/**
+ * Relative time ("3 hours ago", "in 2 days").
+ * @param {Date|number|string} date
+ * @param {Date|number|string} [base=Date.now()]
+ * @returns {string}
+ */
+function relativeTime(date, base = Date.now()) {
+  const d = date instanceof Date ? date.getTime() : new Date(date).getTime();
+  const b = base instanceof Date ? base.getTime() : new Date(base).getTime();
+  const diff = d - b;
+  const abs  = Math.abs(diff);
+  const past = diff < 0;
+
+  const units = [
+    { limit: 60000,       div: 1000,    unit: 'second' },
+    { limit: 3600000,     div: 60000,   unit: 'minute' },
+    { limit: 86400000,    div: 3600000, unit: 'hour' },
+    { limit: 2592000000,  div: 86400000,unit: 'day' },
+    { limit: 31536000000, div: 2592000000, unit: 'month' },
+    { limit: Infinity,    div: 31536000000, unit: 'year' },
+  ];
+
+  if (abs < 1000) return 'just now';
+
+  for (const { limit, div, unit } of units) {
+    if (abs < limit) {
+      const n = Math.round(abs / div);
+      const s = n !== 1 ? 's' : '';
+      return past ? `${n} ${unit}${s} ago` : `in ${n} ${unit}${s}`;
+    }
+  }
+}
+
+function _monthNames(locale, type) {
+  try {
+    return Array.from({ length: 12 }, (_, i) =>
+      new Date(2000, i, 1).toLocaleString(locale, { month: type })
+    );
+  } catch { return ['January','February','March','April','May','June','July','August','September','October','November','December']; }
+}
+
+function _dayNames(locale, type) {
+  try {
+    return Array.from({ length: 7 }, (_, i) =>
+      new Date(2000, 0, i + 2).toLocaleString(locale, { weekday: type })
+    );
+  } catch { return ['Sunday','Monday','Tuesday','Wednesday','Thursday','Friday','Saturday']; }
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 6: ANSI / TERMINAL COLOR CODES
+// ────────────────────────────────────────────────────────────
+
+const ANSI = {
+  reset:     '\x1b[0m',
+  bold:      '\x1b[1m',
+  dim:       '\x1b[2m',
+  italic:    '\x1b[3m',
+  underline: '\x1b[4m',
+  blink:     '\x1b[5m',
+  inverse:   '\x1b[7m',
+  hidden:    '\x1b[8m',
+  strike:    '\x1b[9m',
+
+  black:   '\x1b[30m', red:     '\x1b[31m', green:  '\x1b[32m',
+  yellow:  '\x1b[33m', blue:    '\x1b[34m', magenta:'\x1b[35m',
+  cyan:    '\x1b[36m', white:   '\x1b[37m', gray:   '\x1b[90m',
+
+  bgBlack:   '\x1b[40m',  bgRed:     '\x1b[41m', bgGreen:  '\x1b[42m',
+  bgYellow:  '\x1b[43m',  bgBlue:    '\x1b[44m', bgMagenta:'\x1b[45m',
+  bgCyan:    '\x1b[46m',  bgWhite:   '\x1b[47m', bgGray:   '\x1b[100m',
+
+  brightBlack:   '\x1b[90m',  brightRed:   '\x1b[91m', brightGreen:  '\x1b[92m',
+  brightYellow:  '\x1b[93m',  brightBlue:  '\x1b[94m', brightMagenta:'\x1b[95m',
+  brightCyan:    '\x1b[96m',  brightWhite: '\x1b[97m',
+};
+
+/**
+ * Wrap a string with ANSI color/style codes.
+ * @param {string} str
+ * @param {...string} codes - keys from ANSI or raw escape codes
+ * @returns {string}
+ */
+function ansi(str, ...codes) {
+  const open  = codes.map(c => ANSI[c] || c).join('');
+  return open + str + ANSI.reset;
+}
+
+/**
+ * Strip all ANSI escape codes from a string.
+ * @param {string} str
+ * @returns {string}
+ */
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*[mGKHF]/g, '');
+}
+
+/**
+ * 256-color foreground.
+ * @param {string} str
+ * @param {number} code - 0-255
+ * @returns {string}
+ */
+function color256(str, code) {
+  return `\x1b[38;5;${code}m${str}${ANSI.reset}`;
+}
+
+/**
+ * RGB foreground color (true color terminals).
+ * @param {string} str
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @returns {string}
+ */
+function colorRGB(str, r, g, b) {
+  return `\x1b[38;2;${r};${g};${b}m${str}${ANSI.reset}`;
+}
+
+/**
+ * RGB background color.
+ */
+function bgColorRGB(str, r, g, b) {
+  return `\x1b[48;2;${r};${g};${b}m${str}${ANSI.reset}`;
+}
+
+/**
+ * Hex color string (#RRGGBB or #RGB) to RGB foreground.
+ */
+function colorHex(str, hex) {
+  hex = hex.replace('#', '');
+  if (hex.length === 3) hex = hex.split('').map(c => c + c).join('');
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  return colorRGB(str, r, g, b);
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 7: TABLE / ASCII GRID FORMATTING
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Format data as an ASCII table.
+ *
+ * @param {Array<object|Array>} rows  - array of objects or arrays
+ * @param {object} [options]
+ * @param {string[]} [options.headers]    - column headers
+ * @param {'left'|'right'|'center'|Array} [options.align='left']
+ * @param {'simple'|'box'|'rounded'|'double'|'minimal'|'markdown'} [options.style='box']
+ * @param {number} [options.padding=1]
+ * @param {boolean} [options.borders=true]
+ * @param {number[]} [options.maxWidths]  - max column widths (truncates)
+ * @returns {string}
+ */
+function table(rows, options = {}) {
+  const style   = options.style   || 'box';
+  const padding = options.padding !== undefined ? options.padding : 1;
+  const align   = options.align   || 'left';
+  const maxWids = options.maxWidths || [];
+
+  // Normalize rows to array of arrays
+  let headers = options.headers || null;
+  let data = rows.map(r => Array.isArray(r) ? r : Object.values(r));
+  if (!headers && rows.length && !Array.isArray(rows[0])) {
+    headers = Object.keys(rows[0]);
+  }
+
+  const allRows = headers ? [headers, ...data] : [...data];
+  const cols = Math.max(...allRows.map(r => r.length));
+
+  // Pad rows to equal columns
+  const normalized = allRows.map(r => {
+    const row = Array.from({ length: cols }, (_, i) => String(r[i] != null ? r[i] : ''));
+    return row;
+  });
+
+  // Compute column widths
+  let colWidths = Array.from({ length: cols }, (_, ci) =>
+    Math.max(...normalized.map(r => r[ci].length))
+  );
+
+  // Apply maxWidths truncation
+  colWidths = colWidths.map((w, i) =>
+    maxWids[i] ? Math.min(w, maxWids[i]) : w
+  );
+
+  // Truncate cells to maxWidths
+  const cells = normalized.map(row =>
+    row.map((cell, ci) =>
+      maxWids[ci] && cell.length > maxWids[ci] ? truncate(cell, maxWids[ci]) : cell
+    )
+  );
+
+  // Alignment helper
+  function alignCell(str, width, colIdx) {
+    const a = Array.isArray(align) ? (align[colIdx] || 'left') : align;
+    if (a === 'right')  return padLeft(str, width);
+    if (a === 'center') return padCenter(str, width);
+    return padRight(str, width);
+  }
+
+  const pad = ' '.repeat(padding);
+
+  // Border styles
+  const styles = {
+    box:      { tl:'┌', tr:'┐', bl:'└', br:'┘', h:'─', v:'│', ml:'├', mr:'┤', mt:'┬', mb:'┴', mx:'┼', sep:true },
+    rounded:  { tl:'╭', tr:'╮', bl:'╰', br:'╯', h:'─', v:'│', ml:'╞', mr:'╡', mt:'┬', mb:'┴', mx:'┼', sep:true },
+    double:   { tl:'╔', tr:'╗', bl:'╚', br:'╝', h:'═', v:'║', ml:'╠', mr:'╣', mt:'╦', mb:'╩', mx:'╬', sep:true },
+    simple:   { tl:'', tr:'', bl:'', br:'', h:'-', v:'|', ml:'', mr:'', mt:'', mb:'', mx:'+', sep:true },
+    minimal:  { tl:'', tr:'', bl:'', br:'', h:' ', v:' ', ml:'', mr:'', mt:'', mb:'', mx:' ', sep:false },
+    markdown: { tl:'', tr:'', bl:'', br:'', h:'-', v:'|', ml:'', mr:'', mt:'', mb:'', mx:'|', sep:true },
+  };
+  const B = styles[style] || styles.box;
+  const isMarkdown = style === 'markdown';
+
+  function makeLine(left, mid, right, fill) {
+    const inner = colWidths.map(w => fill.repeat(w + padding * 2)).join(mid);
+    return left + inner + right;
+  }
+
+  const lines = [];
+  const topLine    = makeLine(B.tl, B.mt, B.tr, B.h);
+  const sepLine    = makeLine(B.ml, B.mx, B.mr, B.h);
+  const bottomLine = makeLine(B.bl, B.mb, B.br, B.h);
+
+  if (!isMarkdown && topLine.trim()) lines.push(topLine);
+
+  cells.forEach((row, ri) => {
+    const rowStr = B.v + row.map((cell, ci) =>
+      pad + alignCell(cell, colWidths[ci]) + pad
+    ).join(B.v) + B.v;
+    lines.push(rowStr);
+
+    if (ri === 0 && headers) {
+      // separator after header
+      if (isMarkdown) {
+        const mdSep = '|' + colWidths.map(w => '-'.repeat(w + padding * 2)).join('|') + '|';
+        lines.push(mdSep);
+      } else if (B.sep && sepLine.trim()) {
+        lines.push(sepLine);
+      }
+    }
+  });
+
+  if (!isMarkdown && bottomLine.trim()) lines.push(bottomLine);
+
+  return lines.join('\n');
+}
+
+/**
+ * Format a key-value list as an aligned two-column display.
+ * @param {object|Array<[string,any]>} obj
+ * @param {object} [options]
+ * @param {string} [options.separator='  ']
+ * @param {'left'|'right'} [options.keyAlign='right']
+ * @returns {string}
+ */
+function kvList(obj, options = {}) {
+  const sep      = options.separator || '  ';
+  const keyAlign = options.keyAlign  || 'right';
+  const pairs    = Array.isArray(obj) ? obj : Object.entries(obj);
+  const maxKey   = Math.max(...pairs.map(([k]) => String(k).length));
+  return pairs.map(([k, v]) => {
+    const key = keyAlign === 'right'
+      ? padLeft(String(k), maxKey)
+      : padRight(String(k), maxKey);
+    return key + sep + String(v);
+  }).join('\n');
+}
+
+/**
+ * Render a simple horizontal progress bar.
+ * @param {number} value   - current value
+ * @param {number} max     - max value
+ * @param {number} [width=40]
+ * @param {object} [options]
+ * @param {string} [options.filled='█']
+ * @param {string} [options.empty='░']
+ * @param {boolean} [options.showPercent=true]
+ * @returns {string}
+ */
+function progressBar(value, max, width = 40, options = {}) {
+  const filled  = options.filled  || '█';
+  const empty   = options.empty   || '░';
+  const showPct = options.showPercent !== false;
+  const ratio   = Math.max(0, Math.min(1, value / max));
+  const n       = Math.round(ratio * width);
+  const bar     = filled.repeat(n) + empty.repeat(width - n);
+  return showPct ? `[${bar}] ${percent(ratio)}` : `[${bar}]`;
+}
+
+/**
+ * Render a tree structure from a nested object/array.
+ * @param {object|Array} node
+ * @param {string} [label='']
+ * @param {string} [prefix='']
+ * @returns {string}
+ */
+function treeView(node, label = '', prefix = '') {
+  const lines = [];
+  if (label) lines.push(prefix + label);
+  const entries = Array.isArray(node)
+    ? node.map((v, i) => [String(i), v])
+    : Object.entries(node || {});
+  entries.forEach(([key, val], i) => {
+    const isLast   = i === entries.length - 1;
+    const branch   = isLast ? '└── ' : '├── ';
+    const childPfx = prefix + (isLast ? '    ' : '│   ');
+    if (val && typeof val === 'object') {
+      lines.push(prefix + branch + key + '/');
+      lines.push(treeView(val, '', childPfx));
+    } else {
+      lines.push(prefix + branch + key + ': ' + String(val));
+    }
+  });
+  return lines.filter(Boolean).join('\n');
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 8: JSON / OBJECT PRETTY-PRINT
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Pretty-print a value as JSON.
+ * @param {*} val
+ * @param {object} [options]
+ * @param {number} [options.indent=2]
+ * @param {boolean} [options.color=false] - ANSI-color key types
+ * @param {number} [options.maxDepth]     - truncate deeper objects
+ * @returns {string}
+ */
+function prettyJSON(val, options = {}) {
+  const indent   = options.indent   !== undefined ? options.indent : 2;
+  const colorize = options.color    || false;
+  const maxDepth = options.maxDepth !== undefined ? options.maxDepth : Infinity;
+
+  function _serialize(v, depth) {
+    if (depth > maxDepth) return colorize ? ansi('"..."', 'gray') : '"..."';
+    if (v === null)      return colorize ? ansi('null',  'magenta') : 'null';
+    if (v === undefined) return colorize ? ansi('undefined', 'gray') : 'undefined';
+    if (typeof v === 'boolean') return colorize ? ansi(String(v), 'yellow') : String(v);
+    if (typeof v === 'number')  return colorize ? ansi(String(v), 'cyan')   : String(v);
+    if (typeof v === 'string') {
+      const s = JSON.stringify(v);
+      return colorize ? ansi(s, 'green') : s;
+    }
+    if (Array.isArray(v)) {
+      if (v.length === 0) return '[]';
+      const pad = ' '.repeat((depth + 1) * indent);
+      const close = ' '.repeat(depth * indent);
+      const items = v.map(item => pad + _serialize(item, depth + 1));
+      return '[\n' + items.join(',\n') + '\n' + close + ']';
+    }
+    if (typeof v === 'object') {
+      const keys = Object.keys(v);
+      if (keys.length === 0) return '{}';
+      const pad = ' '.repeat((depth + 1) * indent);
+      const close = ' '.repeat(depth * indent);
+      const items = keys.map(k => {
+        const key = colorize ? ansi(JSON.stringify(k), 'blue') : JSON.stringify(k);
+        return pad + key + ': ' + _serialize(v[k], depth + 1);
+      });
+      return '{\n' + items.join(',\n') + '\n' + close + '}';
+    }
+    return String(v);
+  }
+  return _serialize(val, 0);
+}
+
+/**
+ * Diff two objects and return a formatted string of changes.
+ * @param {object} before
+ * @param {object} after
+ * @param {object} [options]
+ * @param {boolean} [options.color=false]
+ * @returns {string}
+ */
+function diffObjects(before, after, options = {}) {
+  const colorize = options.color || false;
+  const lines = [];
+  const allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);
+
+  for (const key of allKeys) {
+    const bVal = JSON.stringify(before[key]);
+    const aVal = JSON.stringify(after[key]);
+    if (!(key in before)) {
+      const line = `+ ${key}: ${aVal}`;
+      lines.push(colorize ? ansi(line, 'green') : line);
+    } else if (!(key in after)) {
+      const line = `- ${key}: ${bVal}`;
+      lines.push(colorize ? ansi(line, 'red') : line);
+    } else if (bVal !== aVal) {
+      const rm  = `- ${key}: ${bVal}`;
+      const add = `+ ${key}: ${aVal}`;
+      lines.push(colorize ? ansi(rm, 'red') : rm);
+      lines.push(colorize ? ansi(add, 'green') : add);
+    }
+  }
+  return lines.join('\n');
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 9: LOCALE / I18N SUPPORT
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Format a number using the Intl API for locale-aware output.
+ * @param {number} n
+ * @param {string} [locale='en']
+ * @param {object} [intlOptions] - passed to Intl.NumberFormat
+ * @returns {string}
+ */
+function localeNumber(n, locale = 'en', intlOptions = {}) {
+  return new Intl.NumberFormat(locale, intlOptions).format(n);
+}
+
+/**
+ * Format a date using the Intl API.
+ * @param {Date|number|string} date
+ * @param {string} [locale='en']
+ * @param {object} [intlOptions] - passed to Intl.DateTimeFormat
+ * @returns {string}
+ */
+function localeDate(date, locale = 'en', intlOptions = {}) {
+  const d = date instanceof Date ? date : new Date(date);
+  return new Intl.DateTimeFormat(locale, intlOptions).format(d);
+}
+
+/**
+ * Format a number as currency using Intl.
+ * @param {number} n
+ * @param {string} [currencyCode='USD']
+ * @param {string} [locale='en']
+ * @returns {string}
+ */
+function localeCurrency(n, currencyCode = 'USD', locale = 'en') {
+  return new Intl.NumberFormat(locale, { style: 'currency', currency: currencyCode }).format(n);
+}
+
+/**
+ * Get a list separator for a locale (e.g. English = ', ' / Arabic = '، ').
+ * @param {string} [locale='en']
+ * @returns {string}
+ */
+function localeSeparator(locale = 'en') {
+  // Use Intl.ListFormat if available
+  if (typeof Intl !== 'undefined' && Intl.ListFormat) {
+    const lf = new Intl.ListFormat(locale, { type: 'conjunction' });
+    // Extract the separator from a test format
+    const parts = lf.formatToParts(['A', 'B', 'C']);
+    const sep = parts.find(p => p.type === 'literal');
+    return sep ? sep.value : ', ';
+  }
+  return ', ';
+}
+
+/**
+ * Format a list of items into a natural language list.
+ * @param {string[]} items
+ * @param {'conjunction'|'disjunction'|'unit'} [type='conjunction']
+ * @param {string} [locale='en']
+ * @returns {string}
+ */
+function listFormat(items, type = 'conjunction', locale = 'en') {
+  if (typeof Intl !== 'undefined' && Intl.ListFormat) {
+    return new Intl.ListFormat(locale, { style: 'long', type }).format(items);
+  }
+  if (items.length === 0) return '';
+  if (items.length === 1) return items[0];
+  const conj = type === 'disjunction' ? 'or' : 'and';
+  return items.slice(0, -1).join(', ') + ', ' + conj + ' ' + items[items.length - 1];
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 10: MISC UTILITIES
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Convert camelCase / PascalCase to different cases.
+ * @param {string} str
+ * @param {'snake'|'kebab'|'title'|'upper'|'camel'|'pascal'|'dot'} to
+ * @returns {string}
+ */
+function changeCase(str, to) {
+  // Split into words
+  const words = str
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/[-_.\s]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .map(w => w.toLowerCase());
+
+  switch (to) {
+    case 'snake':  return words.join('_');
+    case 'kebab':  return words.join('-');
+    case 'dot':    return words.join('.');
+    case 'upper':  return words.join('_').toUpperCase();
+    case 'title':  return words.map(w => w[0].toUpperCase() + w.slice(1)).join(' ');
+    case 'camel':  return words[0] + words.slice(1).map(w => w[0].toUpperCase() + w.slice(1)).join('');
+    case 'pascal': return words.map(w => w[0].toUpperCase() + w.slice(1)).join('');
+    default:       return str;
+  }
+}
+
+/**
+ * Pluralize a word based on count.
+ * @param {number} count
+ * @param {string} singular
+ * @param {string} [plural]  - defaults to singular + 's'
+ * @param {boolean} [includeCount=true]
+ * @returns {string}
+ */
+function pluralize(count, singular, plural, includeCount = true) {
+  plural = plural || singular + 's';
+  const word = count === 1 ? singular : plural;
+  return includeCount ? `${count} ${word}` : word;
+}
+
+/**
+ * Slugify a string (URL-safe lowercase with hyphens).
+ * @param {string} str
+ * @returns {string}
+ */
+function slugify(str) {
+  return str
+    .toString()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Mask a string, showing only last N characters.
+ * @param {string} str
+ * @param {number} [show=4]
+ * @param {string} [maskChar='*']
+ * @returns {string}
+ */
+function mask(str, show = 4, maskChar = '*') {
+  str = String(str);
+  if (str.length <= show) return maskChar.repeat(str.length);
+  return maskChar.repeat(str.length - show) + str.slice(-show);
+}
+
+/**
+ * Convert a number to its spelled-out English word.
+ * Supports integers up to 999 quadrillion.
+ * @param {number} n
+ * @returns {string}
+ */
+function numberWords(n) {
+  n = Math.trunc(Number(n));
+  if (n === 0) return 'zero';
+  const neg = n < 0;
+  n = Math.abs(n);
+
+  const ones = ['','one','two','three','four','five','six','seven','eight','nine',
+                 'ten','eleven','twelve','thirteen','fourteen','fifteen','sixteen',
+                 'seventeen','eighteen','nineteen'];
+  const tens = ['','','twenty','thirty','forty','fifty','sixty','seventy','eighty','ninety'];
+
+  function _below1000(n) {
+    if (n < 20) return ones[n];
+    if (n < 100) return tens[Math.floor(n/10)] + (n%10 ? '-' + ones[n%10] : '');
+    return ones[Math.floor(n/100)] + ' hundred' + (n%100 ? ' ' + _below1000(n%100) : '');
+  }
+
+  const chunks = [];
+  const scales = ['', ' thousand', ' million', ' billion', ' trillion', ' quadrillion'];
+  let idx = 0;
+  while (n > 0) {
+    const chunk = n % 1000;
+    if (chunk) chunks.unshift(_below1000(chunk) + scales[idx]);
+    n = Math.floor(n / 1000);
+    idx++;
+  }
+  const result = chunks.join(', ');
+  return (neg ? 'negative ' : '') + result;
+}
+
+/**
+ * Format a hex color string.
+ * @param {number|string} r - red 0-255 or full '#RRGGBB'
+ * @param {number} [g]
+ * @param {number} [b]
+ * @returns {string}
+ */
+function hexColor(r, g, b) {
+  if (typeof r === 'string') return r.startsWith('#') ? r.toUpperCase() : '#' + r.toUpperCase();
+  const toHex = n => Math.max(0, Math.min(255, Math.trunc(n))).toString(16).padStart(2, '0').toUpperCase();
+  return '#' + toHex(r) + toHex(g) + toHex(b);
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 11: CHAINABLE FORMATTER CLASS
+// ────────────────────────────────────────────────────────────
+
+/**
+ * KitFormatter — chainable formatting class.
+ *
+ * Start with KitFormatter.of(value) and chain methods.
+ * Call .toString() or .value to get the final string.
+ *
+ * @example
+ * const s = KitFormatter.of(1234567.89)
+ *   .currency('$')
+ *   .ansiStyle('bold', 'green')
+ *   .toString();
+ */
+class KitFormatter {
+  constructor(value) {
+    this._val = String(value != null ? value : '');
+  }
+
+  /** Create a new KitFormatter from any value. */
+  static of(value) {
+    return new KitFormatter(value);
+  }
+
+  /** Get the current formatted string. */
+  get value() { return this._val; }
+  toString()  { return this._val; }
+  valueOf()   { return this._val; }
+
+  // ── String ops ──────────────────────────────────────
+
+  /** Pad left. */
+  padLeft(width, char = ' ') {
+    return new KitFormatter(padLeft(this._val, width, char));
+  }
+  /** Pad right. */
+  padRight(width, char = ' ') {
+    return new KitFormatter(padRight(this._val, width, char));
+  }
+  /** Center. */
+  padCenter(width, char = ' ') {
+    return new KitFormatter(padCenter(this._val, width, char));
+  }
+  /** Truncate right. */
+  truncate(maxLen, ellipsis = '…') {
+    return new KitFormatter(truncate(this._val, maxLen, ellipsis));
+  }
+  /** Truncate left. */
+  truncateLeft(maxLen, ellipsis = '…') {
+    return new KitFormatter(truncateLeft(this._val, maxLen, ellipsis));
+  }
+  /** Word wrap. */
+  wordWrap(width) {
+    return new KitFormatter(wordWrap(this._val, width));
+  }
+  /** To upper case. */
+  upper() {
+    return new KitFormatter(this._val.toUpperCase());
+  }
+  /** To lower case. */
+  lower() {
+    return new KitFormatter(this._val.toLowerCase());
+  }
+  /** Trim. */
+  trim() {
+    return new KitFormatter(this._val.trim());
+  }
+  /** Slugify. */
+  slug() {
+    return new KitFormatter(slugify(this._val));
+  }
+  /** Change case. */
+  toCase(caseName) {
+    return new KitFormatter(changeCase(this._val, caseName));
+  }
+  /** Strip ANSI codes. */
+  stripAnsi() {
+    return new KitFormatter(stripAnsi(this._val));
+  }
+  /** Repeat. */
+  repeat(n) {
+    return new KitFormatter(repeat(this._val, n));
+  }
+  /** Replace via regex or string. */
+  replace(pattern, replacement) {
+    return new KitFormatter(this._val.replace(pattern, replacement));
+  }
+  /** Prepend a string. */
+  prepend(str) {
+    return new KitFormatter(String(str) + this._val);
+  }
+  /** Append a string. */
+  append(str) {
+    return new KitFormatter(this._val + String(str));
+  }
+  /** Mask sensitive data. */
+  mask(show = 4, char = '*') {
+    return new KitFormatter(mask(this._val, show, char));
+  }
+
+  // ── Number ops (parses _val as number) ──────────────
+
+  /** Format as thousands-separated. */
+  thousands(sep = ',', dec = '.') {
+    return new KitFormatter(thousands(this._val, sep, dec));
+  }
+  /** Format as currency. */
+  currency(symbol = '$', decimals = 2) {
+    return new KitFormatter(currency(Number(this._val), symbol, decimals));
+  }
+  /** Fixed decimals. */
+  fixed(n = 2) {
+    return new KitFormatter(fixed(this._val, n));
+  }
+  /** Compact notation. */
+  compact(n = 1) {
+    return new KitFormatter(compact(this._val, n));
+  }
+  /** Percent. */
+  percent(decimals = 1, raw = false) {
+    return new KitFormatter(percent(Number(this._val), decimals, raw));
+  }
+  /** File size. */
+  fileSize(decimals = 2, si = false) {
+    return new KitFormatter(fileSize(Number(this._val), decimals, si));
+  }
+  /** Ordinal. */
+  ordinal() {
+    return new KitFormatter(ordinal(Number(this._val)));
+  }
+  /** Roman numerals. */
+  roman() {
+    return new KitFormatter(roman(Number(this._val)));
+  }
+  /** Number in words. */
+  words() {
+    return new KitFormatter(numberWords(Number(this._val)));
+  }
+  /** printf-style format. */
+  printf(fmt) {
+    return new KitFormatter(printf(fmt, this._val));
+  }
+
+  // ── ANSI / color ops ────────────────────────────────
+
+  /** Apply ANSI styles. */
+  ansiStyle(...codes) {
+    return new KitFormatter(ansi(this._val, ...codes));
+  }
+  /** 256-color. */
+  color256(code) {
+    return new KitFormatter(color256(this._val, code));
+  }
+  /** RGB color. */
+  colorRGB(r, g, b) {
+    return new KitFormatter(colorRGB(this._val, r, g, b));
+  }
+  /** Hex color. */
+  colorHex(hex) {
+    return new KitFormatter(colorHex(this._val, hex));
+  }
+
+  // ── Date ops (parses _val as Date) ─────────────────
+
+  /** Format as date. */
+  dateFormat(fmt, opts) {
+    return new KitFormatter(dateFormat(this._val, fmt, opts));
+  }
+  /** Relative time. */
+  relativeTime(base) {
+    return new KitFormatter(relativeTime(this._val, base));
+  }
+
+  // ── Misc ────────────────────────────────────────────
+
+  /** Pretty JSON. */
+  prettyJSON(opts) {
+    try {
+      const parsed = JSON.parse(this._val);
+      return new KitFormatter(prettyJSON(parsed, opts));
+    } catch {
+      return new KitFormatter(prettyJSON(this._val, opts));
+    }
+  }
+  /** Apply an arbitrary transform function. */
+  pipe(fn) {
+    return new KitFormatter(fn(this._val));
+  }
+}
+
+// ────────────────────────────────────────────────────────────
+//  EXPORTS
+// ────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+    // Printf / sprintf
+    printf,
+    sprintf,
+    fmt,
+
+    // Custom spec registry
+    registerSpec,
+    unregisterSpec,
+
+    // String formatting
+    padLeft,
+    padRight,
+    padCenter,
+    truncate,
+    truncateLeft,
+    truncateMid,
+    wordWrap,
+    repeat,
+
+    // Number formatting
+    thousands,
+    currency,
+    scientific,
+    fileSize,
+    percent,
+    fixed,
+    compact,
+    ordinal,
+    roman,
+    radixFmt,
+    numberWords,
+    hexColor,
+
+    // Date / time formatting
+    dateFormat,
+    duration,
+    relativeTime,
+
+    // ANSI / color
+    ANSI,
+    ansi,
+    stripAnsi,
+    color256,
+    colorRGB,
+    bgColorRGB,
+    colorHex,
+
+    // Table / grid
+    table,
+    kvList,
+    progressBar,
+    treeView,
+
+    // JSON / object
+    prettyJSON,
+    diffObjects,
+
+    // Locale / i18n
+    localeNumber,
+    localeDate,
+    localeCurrency,
+    localeSeparator,
+    listFormat,
+
+    // Misc utilities
+    changeCase,
+    pluralize,
+    slugify,
+    mask,
+
+    // Chainable formatter class
+    KitFormatter,
+  }
+};