feat: add random confusable replacement functions

- Add getRandomConfusable() for single character random replacement
- Add randomizeConfusables() for string random replacement
- Add RandomConfusableOptions interface for flexible configuration
- Support type filtering, character exclusion, and probability control
- Update README with usage examples and feature documentation

Author: DemoMacro

packages/unconfusables/README.md

@@ -13,6 +13,7 @@ UTS #39 defines security mechanisms for handling Unicode characters, including c
 
 - 🔍 **Confusable Detection**: Identify characters that can be visually confused with others
 - 🔧 **String Normalization**: Convert strings to their canonical forms
+- 🎲 **Random Replacement**: Replace characters with random confusable alternatives
 - 🛡️ **Security Applications**: Detect potential phishing attacks and homograph attacks
 - 🌐 **Unicode Support**: Comprehensive support for Unicode confusable mappings
 - ⚡️ **High Performance**: Efficient lookup algorithms with 6296+ confusable mappings
@@ -42,6 +43,8 @@ import {
   normalizeString,
   areConfusable,
   getConfusableVariations,
+  getRandomConfusable,
+  randomizeConfusables,
 } from "unconfusables";
 
 // Character confusable lookup
@@ -64,6 +67,19 @@ console.log(areConfusable("google", "goog1e")); // true
 // Generate confusable variations
 const variations = getConfusableVariations("admin");
 console.log(variations); // ["admin", "adrin", "adnin"]
+
+// Random character replacement
+console.log(getRandomConfusable("a")); // Random confusable of "a"
+console.log(getRandomConfusable("0")); // "O" or other confusable
+
+// With options: only MA type, exclude certain characters
+console.log(
+  getRandomConfusable("a", { type: "MA", exclude: new Set(["a", "A"]) }),
+);
+
+// Random string replacement (30% probability)
+const randomized = randomizeConfusables("paypal", { probability: 0.3 });
+console.log(randomized); // "paypal" with some characters randomly replaced
 ```
 
 ## 🔧 Advanced Usage
@@ -100,14 +116,40 @@ console.log(detectPhishingUrl("g00gle.com"));
 ### 🎭 String Variation Generation
 
 ```typescript
-import { getConfusableVariations, getConfusableSources } from "unconfusables";
+import {
+  getConfusableVariations,
+  getConfusableSources,
+  getRandomConfusable,
+  randomizeConfusables,
+} from "unconfusables";
 
 // Generate all possible confusable variations
 const text = "admin";
 const variations = getConfusableVariations(text);
 console.log(`"${text}" has ${variations.length} confusable variations:`);
 variations.forEach((v) => console.log(`  - ${v}`));
 
+// Random character replacement
+const randomChar = getRandomConfusable("a");
+console.log(`Random confusable for "a": ${randomChar}`);
+
+// With options: only MA type
+const randomMA = getRandomConfusable("a", { type: "MA" });
+console.log(`Random MA confusable for "a": ${randomMA}`);
+
+// Excluding specific characters
+const randomExcluded = getRandomConfusable("a", {
+  exclude: new Set(["a", "A"]),
+});
+console.log(`Random confusable for "a" excluding "a"/"A": ${randomExcluded}`);
+
+// Randomize entire string with options
+const randomString = randomizeConfusables("paypal", {
+  type: "MA",
+  probability: 0.4,
+});
+console.log(`Randomized "paypal" (40% probability, MA only): ${randomString}`);
+
 // Check what characters can be confused with a target character
 const sources = getConfusableSources("O");
 console.log(

packages/unconfusables/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unconfusables",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "Unicode confusable characters detection and string normalization library based on UTS #39",
   "main": "dist/index.mjs",
   "types": "dist/index.d.ts",

packages/unconfusables/src/types.ts

@@ -25,3 +25,9 @@ export interface ConfusableMetadata {
     X: number;
   };
 }
+
+export interface RandomConfusableOptions {
+  type?: ConfusableType;
+  exclude?: Set<string>;
+  probability?: number;
+}

packages/unconfusables/src/utils.ts

@@ -2,7 +2,11 @@
  * Unicode Confusables Utility Functions
  */
 
-import type { ConfusableRecord, ConfusableType } from "./types";
+import type {
+  ConfusableRecord,
+  ConfusableType,
+  RandomConfusableOptions,
+} from "./types";
 import { confusables } from "./data";
 
 // Get confusable mapping for a character
@@ -95,6 +99,48 @@ export function getConfusableVariations(
   return Array.from(variations);
 }
 
+// Replace character with random confusable
+export function getRandomConfusable(
+  char: string,
+  options: RandomConfusableOptions = {},
+): string {
+  if (char.length === 0) return char;
+
+  const confusable = confusables.confusables[char];
+  if (!confusable || confusable.target.length === 0) return char;
+
+  // Filter by type if specified
+  if (options.type && confusable.type !== options.type) return char;
+
+  // Filter out excluded characters
+  let targets = confusable.target;
+  if (options.exclude) {
+    targets = targets.filter((target) => !options.exclude!.has(target));
+    if (targets.length === 0) return char;
+  }
+
+  const randomIndex = Math.floor(Math.random() * targets.length);
+  return targets[randomIndex];
+}
+
+// Randomly replace characters in string
+export function randomizeConfusables(
+  text: string,
+  options: RandomConfusableOptions & { probability?: number } = {},
+): string {
+  const probability = options.probability ?? 0.5;
+
+  return text
+    .split("")
+    .map((char) => {
+      if (Math.random() < probability) {
+        return getRandomConfusable(char, options);
+      }
+      return char;
+    })
+    .join("");
+}
+
 // Get metadata about the confusables dataset
 export function getMetadata() {
   const typeStats = { MA: 0, MI: 0, X: 0 };