@discretion/core 0.1.0

package/src/scripts.ts

@@ -0,0 +1,164 @@
+/**
+ * Script detection using native Unicode property escapes (\p{Script=...}).
+ * No external library.
+ *
+ * Characters are classified by CODE POINT (never by UTF-16 code unit), so
+ * astral-plane characters — e.g. CJK Extension B ideographs — are handled
+ * correctly.
+ */
+import type { ScriptInfo, ScriptName } from './types.js';
+
+/**
+ * Script membership tests, checked in this order. Kana merges Hiragana and
+ * Katakana into one bucket because the pipeline treats Japanese syllabaries
+ * as a unit.
+ */
+const SCRIPT_PATTERNS: ReadonlyArray<readonly [ScriptName, RegExp]> = [
+  ['latin', /\p{Script=Latin}/u],
+  ['cyrillic', /\p{Script=Cyrillic}/u],
+  ['greek', /\p{Script=Greek}/u],
+  ['arabic', /\p{Script=Arabic}/u],
+  ['hebrew', /\p{Script=Hebrew}/u],
+  // Han and Kana use Script_Extensions, not Script: CJK letters like ー
+  // (U+30FC, the prolonged sound mark) and 々 (U+3005, the iteration mark)
+  // have Script=Common but scx of {Hiragana,Katakana} / {Han}. Classifying
+  // them 'other' made them look script-anomalous inside ordinary Japanese
+  // words — and anomalous letters are folding candidates, which is exactly
+  // wrong for these.
+  ['han', /\p{Script_Extensions=Han}/u],
+  ['kana', /[\p{Script_Extensions=Hiragana}\p{Script_Extensions=Katakana}]/u],
+  ['hangul', /\p{Script=Hangul}/u],
+  ['devanagari', /\p{Script=Devanagari}/u],
+  ['thai', /\p{Script=Thai}/u],
+  ['armenian', /\p{Script=Armenian}/u],
+  ['georgian', /\p{Script=Georgian}/u],
+  ['ethiopic', /\p{Script=Ethiopic}/u],
+];
+
+const LETTER = /\p{L}/u;
+
+/** All supported scripts, i.e. every ScriptName except 'other'. */
+const REAL_SCRIPTS = SCRIPT_PATTERNS.map(([name]) => name);
+
+/**
+ * Classification of one code point:
+ *  - 'neutral'   — not a letter (whitespace, digits, punctuation, symbols,
+ *                  combining marks, controls). Ignored for dominance because
+ *                  it would skew the result.
+ *  - a ScriptName — a letter of that script ('other' for unsupported scripts).
+ */
+export type CodePointClass = ScriptName | 'neutral';
+
+/**
+ * Memo of code point → class. Script property lookups go through regexes,
+ * which is too slow to repeat per character on large inputs; real-world text
+ * has few distinct code points, so a memo makes classification ~O(1).
+ * Capped so adversarial input (e.g. fuzzing across the whole Unicode range)
+ * cannot grow it without bound.
+ */
+const classMemo = new Map<number, CodePointClass>();
+const CLASS_MEMO_MAX = 0x10000;
+
+/** Classify a single code point. Exported for use by the fold transform. */
+export function classifyCodePoint(cp: number): CodePointClass {
+  // ASCII fast path — the overwhelmingly common case.
+  if (cp < 0x80) {
+    if ((cp >= 0x41 && cp <= 0x5a) || (cp >= 0x61 && cp <= 0x7a)) return 'latin';
+    return 'neutral';
+  }
+  const memoized = classMemo.get(cp);
+  if (memoized !== undefined) return memoized;
+
+  const char = String.fromCodePoint(cp);
+  let result: CodePointClass = 'neutral';
+  if (LETTER.test(char)) {
+    result = 'other';
+    for (const [name, pattern] of SCRIPT_PATTERNS) {
+      if (pattern.test(char)) {
+        result = name;
+        break;
+      }
+    }
+  }
+  if (classMemo.size < CLASS_MEMO_MAX) classMemo.set(cp, result);
+  return result;
+}
+
+/**
+ * The ScriptName for a single character (the first code point of `char`).
+ * Script-neutral characters and letters of unsupported scripts both report
+ * 'other'.
+ */
+export function getCharScript(char: string): ScriptName {
+  const cp = char.codePointAt(0);
+  if (cp === undefined) return 'other';
+  const cls = classifyCodePoint(cp);
+  return cls === 'neutral' ? 'other' : cls;
+}
+
+/**
+ * Script compatibility groups for token-level dominance decisions (ratified):
+ * ordinary Japanese prose freely mixes Han, Hiragana/Katakana, and embedded
+ * Latin (acronyms, romaji), and Korean prose mixes Hangul with Han (hanja).
+ * Characters of co-occurring scripts within one group are NEVER treated as
+ * script-anomalous with respect to each other, so such text is never a
+ * homoglyph-folding candidate.
+ */
+const COMPATIBLE_GROUPS: ReadonlyArray<ReadonlySet<ScriptName>> = [
+  new Set<ScriptName>(['han', 'kana', 'latin']),
+  new Set<ScriptName>(['hangul', 'han']),
+];
+
+/**
+ * Whether two scripts may legitimately co-occur in one token (same script,
+ * or both members of a compatibility group).
+ */
+export function scriptsCompatible(a: ScriptName, b: ScriptName): boolean {
+  if (a === b) return true;
+  if (a === 'other' || b === 'other') return false;
+  return COMPATIBLE_GROUPS.some((group) => group.has(a) && group.has(b));
+}
+
+function emptyCounts(): Record<ScriptName, number> {
+  const counts = {} as Record<ScriptName, number>;
+  for (const name of REAL_SCRIPTS) counts[name] = 0;
+  counts.other = 0;
+  return counts;
+}
+
+/**
+ * Per-script letter counts, the dominant script, and whether the text mixes
+ * scripts. Whitespace, digits, and punctuation are ignored — they are
+ * script-neutral and would skew dominance.
+ */
+export function detectScripts(text: string): ScriptInfo {
+  const counts = emptyCounts();
+  // for..of iterates CODE POINTS, so surrogate pairs are never split.
+  for (const char of text) {
+    const cls = classifyCodePoint(char.codePointAt(0)!);
+    if (cls === 'neutral') continue;
+    counts[cls] += 1;
+  }
+
+  let dominant: ScriptName | null = null;
+  let best = 0;
+  let tied = false;
+  let present = 0;
+  for (const name of REAL_SCRIPTS) {
+    const count = counts[name];
+    if (count > 0) present += 1;
+    if (count > best) {
+      best = count;
+      dominant = name;
+      tied = false;
+    } else if (count === best && count > 0) {
+      tied = true;
+    }
+  }
+  return {
+    counts,
+    // Dominance requires a strict maximum; a tie means "no dominant script".
+    dominant: tied ? null : dominant,
+    mixed: present > 1,
+  };
+}

package/src/transforms/foldDigits.ts

@@ -0,0 +1,138 @@
+/**
+ * Transform 5: DECIMAL DIGIT FOLDING.
+ *
+ * Every Unicode decimal digit is folded to its ASCII equivalent: Arabic-Indic
+ * ٠١٢, Extended Arabic-Indic ۰۱۲, Devanagari ०१२, Bengali ০১২, Thai ๐๑๒,
+ * Tamil, Telugu, Myanmar, Khmer, and the rest.
+ *
+ * WHY THIS EXISTS. NFKC folds FULLWIDTH digits, because those are
+ * compatibility variants of ASCII — but Arabic-Indic and Devanagari digits are
+ * not compatibility variants of anything. They are the ordinary digits of
+ * living scripts, and NFKC leaves them exactly as they are, correctly.
+ *
+ * The consequence for this pipeline was silent un-redaction. Every Stage 1
+ * detector matches `\d` or an explicit `[0-9]` class, so before this transform
+ * existed a Turkish national identity number written `٣٠٢١٤٥٦٤٦٤١٢`, an
+ * Iranian phone number in Extended Arabic-Indic, a Hindi Aadhaar number in
+ * Devanagari, a Thai national ID and a Bengali credit card were ALL reported
+ * as clean documents — measured, not assumed. That is the same class of
+ * failure as an identifier hidden inside HTML markup, and it landed on
+ * precisely the Arabic, Persian, Urdu, Hindi, Bengali and Thai users the
+ * multilingual work exists to serve.
+ *
+ * WHERE IT RUNS, and why last. After homoglyph folding, not before. Folding
+ * digits changes a token's script census — Arabic-Indic digits are Arabic,
+ * ASCII digits are not — so folding them earlier would alter the
+ * dominant-script decision that homoglyph folding depends on, and could flip
+ * a fold that D3 deliberately declines to make. Running afterwards leaves
+ * that decision on the original scripts. ASCII digits are NFKC-stable, so no
+ * further normalization pass is owed.
+ *
+ * THE USER'S TEXT IS NOT REWRITTEN. Folding happens in the NORMALIZED text
+ * only; masking edits the ORIGINAL through the offset map, so a Persian user
+ * sees their own digits back. That separation is the entire point of the
+ * offset-map contract.
+ */
+
+import { MappedTextBuilder, type StepChange, type TransformStepResult } from '../offsetMap.js';
+
+/**
+ * The first code point of every Unicode decimal-digit block.
+ *
+ * Each block is ten consecutive code points whose first has value zero, so a
+ * digit's value is `codePoint - blockZero`. Generated by scanning the whole
+ * code space for `\p{Nd}` runs of ten; 72 blocks in the Unicode version
+ * shipped with the runtime. Sorted, which `blockZeroFor` relies on.
+ */
+const DIGIT_BLOCK_ZEROS: readonly number[] = [
+  0x30, 0x660, 0x6f0, 0x7c0, 0x966, 0x9e6, 0xa66, 0xae6,
+  0xb66, 0xbe6, 0xc66, 0xce6, 0xd66, 0xde6, 0xe50, 0xed0,
+  0xf20, 0x1040, 0x1090, 0x17e0, 0x1810, 0x1946, 0x19d0, 0x1a80,
+  0x1a90, 0x1b50, 0x1bb0, 0x1c40, 0x1c50, 0xa620, 0xa8d0, 0xa900,
+  0xa9d0, 0xa9f0, 0xaa50, 0xabf0, 0xff10, 0x104a0, 0x10d30, 0x10d40,
+  0x11066, 0x110f0, 0x11136, 0x111d0, 0x112f0, 0x11450, 0x114d0, 0x11650,
+  0x116c0, 0x116d0, 0x11730, 0x118e0, 0x11950, 0x11bf0, 0x11c50, 0x11d50,
+  0x11da0, 0x11de0, 0x11f50, 0x16130, 0x16a60, 0x16ac0, 0x16b50, 0x16d70,
+  0x1ccf0, 0x1d7ce, 0x1e140, 0x1e2f0, 0x1e4f0, 0x1e5f1, 0x1e950, 0x1fbf0,
+];
+
+/** ASCII '0', whose block is skipped: it is already what we fold to. */
+const ASCII_ZERO = 0x30;
+
+/**
+ * The zero of the decimal-digit block containing `codePoint`, or undefined.
+ * Binary search over the sorted block list.
+ */
+function blockZeroFor(codePoint: number): number | undefined {
+  let low = 0;
+  let high = DIGIT_BLOCK_ZEROS.length - 1;
+  while (low <= high) {
+    const mid = (low + high) >> 1;
+    const zero = DIGIT_BLOCK_ZEROS[mid]!;
+    if (codePoint < zero) high = mid - 1;
+    else if (codePoint > zero + 9) low = mid + 1;
+    else return zero;
+  }
+  return undefined;
+}
+
+/** The ASCII digit for a code point, or undefined if it is not a decimal digit. */
+export function asciiDigitFor(codePoint: number): string | undefined {
+  const zero = blockZeroFor(codePoint);
+  if (zero === undefined || zero === ASCII_ZERO) return undefined;
+  return String.fromCharCode(ASCII_ZERO + (codePoint - zero));
+}
+
+/**
+ * Fold every non-ASCII decimal digit to ASCII.
+ *
+ * Most blocks are BMP and fold one code unit to one, leaving offsets
+ * untouched. A few are astral (Osmanya, Brahmi, mathematical digits) and fold
+ * a surrogate PAIR to a single character, so this is not a 1:1 transform and
+ * goes through `MappedTextBuilder` rather than assuming equal lengths — the
+ * same machinery NFKC's expansions use.
+ */
+export function foldDigits(text: string): TransformStepResult | null {
+  // Fast path: the overwhelming majority of text has no non-ASCII digit, and
+  // must not pay for a builder or a map.
+  let first = -1;
+  for (let i = 0; i < text.length; i += 1) {
+    const cp = text.codePointAt(i)!;
+    if (cp > 0xffff) i += 1;
+    if (cp !== ASCII_ZERO && asciiDigitFor(cp) !== undefined) {
+      first = i - (cp > 0xffff ? 1 : 0);
+      break;
+    }
+  }
+  if (first === -1) return null;
+
+  const builder = new MappedTextBuilder();
+  const changes: StepChange[] = [];
+  let cursor = 0;
+
+  for (let i = first; i < text.length; i += 1) {
+    const codePoint = text.codePointAt(i)!;
+    const width = codePoint > 0xffff ? 2 : 1;
+    const replacement = asciiDigitFor(codePoint);
+    if (replacement === undefined) {
+      i += width - 1;
+      continue;
+    }
+
+    builder.copyVerbatim(text, cursor, i);
+    builder.replaceRange(replacement, i, i + width);
+    changes.push({
+      kind: 'fold-digits',
+      start: i,
+      end: i + width,
+      before: text.slice(i, i + width),
+      after: replacement,
+    });
+    cursor = i + width;
+    i += width - 1;
+  }
+
+  builder.copyVerbatim(text, cursor, text.length);
+  const { text: out, map } = builder.finish(text.length);
+  return { text: out, map, changes };
+}

package/src/transforms/graphemes.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared grapheme-cluster segmenter. Grapheme segmentation (UAX #29) is
+ * locale-independent, so one instance serves the whole library.
+ */
+export const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });

package/src/transforms/homoglyphFold.ts

@@ -0,0 +1,221 @@
+/**
+ * Transform 3: SELECTIVE HOMOGLYPH FOLDING.
+ *
+ * THE RULE — and why it is selective:
+ * Blanket folding would be a severe bug: folding every Cyrillic а to Latin a
+ * would turn an entire Russian document into unreadable Latin nonsense and
+ * destroy detection for every non-Latin user. A character is folded ONLY when
+ * it is script-anomalous within its own token:
+ *
+ *   1. Split the text into tokens on whitespace and punctuation.
+ *   2. Determine each token's dominant script (strict majority of its
+ *      letters; neutral characters don't count).
+ *   3. Fold a character only if its script differs from the token's dominant
+ *      script AND the confusables table gives it a mapping into that script.
+ *
+ * A token that is wholly Cyrillic / Greek / Arabic / … has no anomalous
+ * characters and is left completely untouched.
+ *
+ *   • "pаssword" (Cyrillic а in a Latin token) → folds to "password".
+ *   • "пароль"   (ordinary Cyrillic word)      → byte-identical.
+ *
+ * Mapping INTO the dominant script works in both directions:
+ *   - directly: the character's Unicode skeleton is in the dominant script
+ *     (Cyrillic а → skeleton "a", Latin) — replace with the skeleton;
+ *   - via equivalence: some character OF the dominant script shares the same
+ *     skeleton (Latin o inside a Greek token → Greek ο, whose skeleton is
+ *     also "o") — replace with that character.
+ *
+ * Replacements are restricted to letters/marks/digits: a replacement that
+ * introduced punctuation or whitespace would change tokenization on a second
+ * pass and break idempotency.
+ *
+ * This transform runs AFTER NFKC, so the confusables data's skeletons are
+ * NFKC-normalized at generation time; normalize() additionally re-runs NFKC
+ * after folding (see normalization.ts) so a folded character can compose
+ * with a following combining mark exactly as it would have in pass one.
+ */
+import { CONFUSABLES, type ConfusableEntry } from '@discretion/data';
+import { classifyCodePoint, scriptsCompatible } from '../scripts.js';
+import type { ScriptName } from '../types.js';
+import { MappedTextBuilder, type TransformStepResult, type StepChange } from '../offsetMap.js';
+
+/** Tokens are maximal runs of characters that are neither whitespace nor punctuation. */
+const TOKEN = /[^\s\p{P}]+/gu;
+
+/** Replacements may only contain letters, combining marks, and digits. */
+const SAFE_REPLACEMENT = /^[\p{L}\p{M}\p{N}]+$/u;
+
+/**
+ * skeleton → script → representative character of that script sharing the
+ * skeleton. Built lazily on first use from the confusables table (plus each
+ * skeleton itself as the representative of its own script). Where several
+ * characters of one script share a skeleton, the lowest code point wins so
+ * regeneration of the data cannot reorder results.
+ */
+let skeletonIndex: Map<string, Map<ScriptName, string>> | null = null;
+
+function getSkeletonIndex(): Map<string, Map<ScriptName, string>> {
+  if (skeletonIndex) return skeletonIndex;
+  const index = new Map<string, Map<ScriptName, string>>();
+  const consider = (skeleton: string, script: ScriptName, repr: string): void => {
+    if (script === 'other') return;
+    // A representative becomes replacement text, so it must survive the rest
+    // of the pipeline unchanged: NFKC-stable (U+037A GREEK YPOGEGRAMMENI, for
+    // instance, decomposes to space + combining mark and would smuggle
+    // whitespace into a token) and free of punctuation/whitespace that would
+    // change tokenization on a second pass.
+    if (repr.normalize('NFKC') !== repr) return;
+    if (!SAFE_REPLACEMENT.test(repr)) return;
+    let byScript = index.get(skeleton);
+    if (!byScript) {
+      byScript = new Map<ScriptName, string>();
+      index.set(skeleton, byScript);
+    }
+    const existing = byScript.get(script);
+    if (existing === undefined || repr.codePointAt(0)! < existing.codePointAt(0)!) {
+      byScript.set(script, repr);
+    }
+  };
+  for (const [cp, entry] of CONFUSABLES) {
+    // The confusable character itself represents its script for this skeleton…
+    consider(entry.skeleton, entry.sourceScript, String.fromCodePoint(cp));
+    // …and the skeleton represents its own script (preferred when reachable:
+    // for single-char skeletons it is usually the lowest code point anyway).
+    consider(entry.skeleton, entry.skeletonScript, entry.skeleton);
+  }
+  skeletonIndex = index;
+  return index;
+}
+
+/** Test hook: drop the memoized index (e.g. around mocked data). */
+export function resetSkeletonIndexForTests(): void {
+  skeletonIndex = null;
+}
+
+/**
+ * The replacement for folding `cp` into `dominant`, or null when the
+ * confusables table offers no mapping into that script.
+ */
+function foldTarget(cp: number, dominant: ScriptName): string | null {
+  const entry: ConfusableEntry | undefined = CONFUSABLES.get(cp);
+  // A character absent from the table is its own skeleton: it can still be
+  // the skeleton OF characters in the dominant script — e.g. Latin 'o' has
+  // no entry, but inside a Greek token it folds to Greek omicron, whose
+  // skeleton is 'o' (the equivalence direction).
+  const skeleton = entry ? entry.skeleton : String.fromCodePoint(cp);
+  let replacement: string | undefined;
+  if (entry && entry.skeletonScript === dominant) {
+    replacement = entry.skeleton;
+  } else {
+    replacement = getSkeletonIndex().get(skeleton)?.get(dominant);
+  }
+  if (replacement === undefined) return null;
+  if (replacement === String.fromCodePoint(cp)) return null; // no-op
+  // Defense in depth (the index already filters its representatives, and
+  // generated skeletons are NFKC-normalized): a replacement must not change
+  // tokenization or decay under the NFKC re-pass, or folding would not be
+  // idempotent.
+  if (!SAFE_REPLACEMENT.test(replacement)) return null;
+  if (replacement.normalize('NFKC') !== replacement) return null;
+  return replacement;
+}
+
+interface Fold {
+  /** Offset of the character within the token. */
+  offset: number;
+  /** Length of the character in code units. */
+  length: number;
+  before: string;
+  after: string;
+}
+
+const ZWNJ = String.fromCharCode(0x200c);
+
+/** Compute the folds for one token; empty when the token is not mixed-script. */
+function computeFolds(token: string): Fold[] {
+  // A ZWNJ surviving the strip stage marks joining-script morphology
+  // (Persian, Hindi, …). Folding inside such a token could change the script
+  // of a ZWNJ neighbor and flip the preservation decision on the next pass —
+  // so these tokens are never folding candidates.
+  if (token.includes(ZWNJ)) return [];
+
+  // First pass: per-script letter counts to find the token's dominant script.
+  const counts = new Map<ScriptName, number>();
+  for (const char of token) {
+    const cls = classifyCodePoint(char.codePointAt(0)!);
+    if (cls === 'neutral' || cls === 'other') continue;
+    counts.set(cls, (counts.get(cls) ?? 0) + 1);
+  }
+  let dominant: ScriptName | null = null;
+  let best = 0;
+  let tied = false;
+  for (const [script, count] of counts) {
+    if (count > best) {
+      best = count;
+      dominant = script;
+      tied = false;
+    } else if (count === best) {
+      tied = true;
+    }
+  }
+  // No dominant script (all-neutral, unsupported-script, or tied token):
+  // be conservative and leave the token alone. The tie rule is ratified —
+  // an evenly split token gives no evidence of which script is "home".
+  if (dominant === null || tied) return [];
+
+  // Second pass: fold script-anomalous characters that can map into `dominant`.
+  const folds: Fold[] = [];
+  let offset = 0;
+  for (const char of token) {
+    const cp = char.codePointAt(0)!;
+    const cls = classifyCodePoint(cp);
+    // Neutral characters (digits, marks) are never anomalous. Letters of the
+    // dominant script — or of a script COMPATIBLE with it (Han/Kana/Latin in
+    // Japanese text, Hangul/Han in Korean; see scriptsCompatible) — are at
+    // home. Everything else, including letters of unsupported scripts like
+    // Cherokee (classified 'other'), is anomalous and folds if mappable.
+    if (cls !== 'neutral' && !scriptsCompatible(cls, dominant)) {
+      const after = foldTarget(cp, dominant);
+      if (after !== null) {
+        folds.push({ offset, length: char.length, before: char, after });
+      }
+    }
+    offset += char.length;
+  }
+  return folds;
+}
+
+export function foldHomoglyphs(text: string): TransformStepResult | null {
+  const builder = new MappedTextBuilder();
+  const changes: StepChange[] = [];
+  let cursor = 0;
+
+  TOKEN.lastIndex = 0;
+  for (const match of text.matchAll(TOKEN)) {
+    const token = match[0];
+    const tokenStart = match.index!;
+    const folds = computeFolds(token);
+    if (folds.length === 0) continue;
+    // Copy everything between the previous fold and this token, then splice
+    // the folds in at their exact offsets.
+    for (const fold of folds) {
+      const foldStart = tokenStart + fold.offset;
+      builder.copyVerbatim(text, cursor, foldStart);
+      builder.replaceRange(fold.after, foldStart, foldStart + fold.length);
+      changes.push({
+        kind: 'homoglyph-fold',
+        start: foldStart,
+        end: foldStart + fold.length,
+        before: fold.before,
+        after: fold.after,
+      });
+      cursor = foldStart + fold.length;
+    }
+  }
+  if (changes.length === 0) return null;
+
+  builder.copyVerbatim(text, cursor, text.length);
+  const { text: out, map } = builder.finish(text.length);
+  return { text: out, map, changes };
+}

package/src/transforms/nfkc.ts

@@ -0,0 +1,48 @@
+/**
+ * Transform 2: UNICODE NFKC, applied PER GRAPHEME CLUSTER.
+ *
+ * Normalizing cluster-by-cluster is what makes an exact offset map possible:
+ * each cluster's output is recorded against that cluster's input range as we
+ * go. (Normalizing the whole string at once and reconstructing the alignment
+ * afterwards is guesswork — expansions, contractions and reorderings make the
+ * aligned diff ambiguous — so it is deliberately NOT done that way.)
+ *
+ * Cluster-local NFKC is sound because canonical composition only happens
+ * between a base and its combining marks, and UAX #29 never splits a base
+ * from its marks (nor a Hangul jamo sequence) across cluster boundaries.
+ *
+ * Expansions (fi → "fi", ½ → "1⁄2"): every output unit maps to the cluster
+ * start. Contractions (e + U+0301 → é): the single output unit maps to the
+ * cluster start and the sentinel/next cluster provides the end.
+ */
+import { MappedTextBuilder, type TransformStepResult, type StepChange } from '../offsetMap.js';
+import { graphemeSegmenter } from './graphemes.js';
+
+export function nfkcByGrapheme(text: string): TransformStepResult | null {
+  // Fast path: already NFKC-normalized (covers pure ASCII instantly).
+  if (text.normalize('NFKC') === text) return null;
+
+  const builder = new MappedTextBuilder();
+  const changes: StepChange[] = [];
+
+  for (const { segment, index } of graphemeSegmenter.segment(text)) {
+    const segmentEnd = index + segment.length;
+    const normalized = segment.normalize('NFKC');
+    if (normalized === segment) {
+      builder.copyVerbatim(text, index, segmentEnd);
+    } else {
+      builder.replaceRange(normalized, index, segmentEnd);
+      changes.push({
+        kind: 'nfkc',
+        start: index,
+        end: segmentEnd,
+        before: segment,
+        after: normalized,
+      });
+    }
+  }
+
+  if (changes.length === 0) return null;
+  const { text: out, map } = builder.finish(text.length);
+  return { text: out, map, changes };
+}