namespace-guard 0.22.0 → 0.23.0

package/dist/index.d.ts

@@ -1,3 +1,47 @@
+/*! namespace-guard, MIT License, copyright (c) 2026 Paul Wood FRSA (@paultendo).
+ * Includes data from Unicode confusables.txt (2026-08-06, 01:05:35 GMT), copyright 1991-Present Unicode, Inc., Unicode License v3
+ * (https://www.unicode.org/terms_of_use.html), and from confusable-vision measurements by Paul Wood FRSA (@paultendo),
+ * CC BY 4.0 (https://github.com/paultendo/confusable-vision). */
+/** Unicode confusables.txt version these maps were built from. */
+declare const CONFUSABLES_DATE = "2026-08-06, 01:05:35 GMT";
+/**
+ * Non-ASCII characters that look like Latin letters or digits, to their lowercase prototype, for pipelines that run
+ * NFKC first and for rejecting names that contain one: Unicode's mappings, Latin small capitals, and confusable-vision's
+ * strict-tier lookalikes Unicode does not map. 1018 entries.
+ */
+declare const CONFUSABLE_MAP: Record<string, string>;
+/**
+ * Every character that looks like Latin letters or digits, to its lowercase prototype: all of Unicode's mappings to
+ * Latin (including multi-character targets such as m -> rn and the ASCII entries 1 -> l, 0 -> o, | -> l), Latin small
+ * capitals, and confusable-vision's measured lookalikes. Case matters: look a character up as typed. 2216 entries.
+ */
+declare const CONFUSABLE_MAP_FULL: Record<string, string>;
+/** ASCII capitals Unicode maps to another letter, used where case is preserved (capital I looks like l). */
+declare const CONFUSABLE_MAP_CASED: Record<string, string>;
+/** One measured lookalike: the letter or digit it passes for, its prototype, and where it holds. */
+type MeasuredConfusable = {
+    /** The ASCII letter(s) or digit(s) it was measured against. */
+    letter: string;
+    /** namespace-guard's lowercase prototype of that letter. */
+    target: string;
+    /** strict: as alike as the median accepted confusable in that context; broad: as alike as the least alike one;
+     *  design: alike to the letter as another common font draws it. */
+    tier: "strict" | "broad" | "design";
+    /** Where it holds: font and size (px), set between neighbours with the platform's fallback. */
+    contexts: string[];
+};
+/**
+ * confusable-vision's in-place measurements: each character found alike to an ASCII letter or digit, with the best
+ * letter it passes for and where. 974 characters.
+ */
+declare const MEASURED_CONFUSABLES: Record<string, MeasuredConfusable>;
+
+/*! Data licensing:
+ * - TR39-derived mappings: Unicode confusables.txt, copyright 1991-Present Unicode, Inc.,
+ *   Unicode License v3 (https://www.unicode.org/license.txt)
+ * - confusable-vision-derived weights: CC-BY-4.0 (https://creativecommons.org/licenses/by/4.0/).
+ *   Attribution: Paul Wood FRSA (@paultendo), confusable-vision
+ *   (https://github.com/paultendo/confusable-vision). */
 type LlmConfusableSource = "tr39" | "novel";
 type LlmConfusableMapEntry = {
     latin: string;
@@ -12,13 +56,18 @@ type LlmConfusableMapEntry = {
 };
 type LlmConfusableMap = Readonly<Record<string, readonly LlmConfusableMapEntry[]>>;
 declare const LLM_CONFUSABLE_MAP: LlmConfusableMap;
-declare const LLM_CONFUSABLE_MAP_PAIR_COUNT = 1591;
-declare const LLM_CONFUSABLE_MAP_CHAR_COUNT = 1556;
+declare const LLM_CONFUSABLE_MAP_PAIR_COUNT = 2326;
+declare const LLM_CONFUSABLE_MAP_CHAR_COUNT = 2219;
 declare const LLM_CONFUSABLE_MAP_SOURCE_COUNTS: Readonly<{
-    tr39: 1425;
-    novel: 166;
+    tr39: 2016;
+    novel: 310;
 }>;
 
+/*! namespace-guard, MIT License, copyright (c) 2026 Paul Wood FRSA (@paultendo).
+ * Includes data from Unicode confusables.txt, copyright 1991-Present Unicode, Inc.,
+ * under the Unicode License v3 (https://www.unicode.org/license.txt), and from confusable-vision measurements by
+ * Paul Wood FRSA (@paultendo), CC BY 4.0 (https://github.com/paultendo/confusable-vision). */
+
 /** A database table or model to check for slug/handle collisions. */
 type NamespaceSource = {
     /** Table/model name (must match the adapter's lookup key) */
@@ -37,8 +86,11 @@ type NamespaceValidatorResult = {
     available: false;
     message: string;
 } | null;
-/** Async validator hook type used by `NamespaceConfig.validators`. */
-type NamespaceValidator = (value: string) => Promise<NamespaceValidatorResult>;
+/** Async validator hook type used by `NamespaceConfig.validators`. Receives the normalized value, and the identifier
+ *  as typed (before lowercasing), since whether a character looks like a letter can depend on its case. */
+type NamespaceValidator = (value: string, context?: {
+    identifier: string;
+}) => Promise<NamespaceValidatorResult>;
 /** Configuration for a namespace guard instance. */
 type NamespaceConfig = {
     /** Reserved names - flat list, Set, or categorized record */
@@ -83,10 +135,13 @@ type NamespaceConfig = {
     };
     /** Default risk policy for `checkRisk()` / `enforceRisk()` */
     risk?: {
-        /** Include reserved names as protected targets by default (default: true) */
+        /** Include reserved names as protected targets by default (default: true). A reserved name that is not in
+         *  `protect` is matched by lookalikes only. */
         includeReserved?: boolean;
         /** Default protected targets when none are passed to `checkRisk`/`enforceRisk` (default: none). */
         protect?: string[];
+        /** Count leetspeak swaps (4 for a, 1 for i, 5 for s) as lookalikes (default: false) */
+        leetspeak?: boolean;
         /** Number of top matches returned by default (default: 3) */
         maxMatches?: number;
         /** Default warn threshold for score/action mapping (default: 45) */
@@ -133,18 +188,27 @@ type ProfanityVariantProfile = "balanced" | "aggressive";
 type ProfanityValidatorOptions = {
     /** Custom rejection message (default: "That name is not allowed."). */
     message?: string;
-    /** Check if identifier contains a blocked word as a substring (default: `true`). */
+    /** Also refuse names that contain a listed word, not only names that are one (default: `true`). Short entries,
+     *  entries of several words and entries common inside English words are matched there only as whole words. */
     checkSubstrings?: boolean;
     /** `basic`: lowercase matching only. `evasion`: Unicode+substitute folding (default: `evasion`). */
     mode?: ProfanityValidationMode;
     /** Variant strictness for evasion mode (default: `balanced`). */
     variantProfile?: ProfanityVariantProfile;
-    /** Minimum blocked-word length for substring checks (default: `4`). Exact matches are always checked. */
+    /** Fewest letters (digits count, spaces and symbols don't) an entry needs to be looked for inside longer words
+     *  (default: `4`). Shorter entries are matched as whole words: the whole name, or a part between separators or digits. */
     minSubstringLength?: number;
     /** Confusable map used for evasion folding (default: `CONFUSABLE_MAP_FULL`). */
     map?: Record<string, string>;
     /** Max folded candidates generated per value in evasion mode (default: `64`). */
     maxFoldVariants?: number;
+    /** Words that contain a listed word but are fine, such as names and places: `["scunthorpe", "dickson"]`. A listed
+     *  word found only inside one of these doesn't count, wherever the allowed word appears in the name
+     *  ("scunthorpe-fc"), while a listed word outside it still does. Case and lookalike letters are folded as for the
+     *  list, but a digit in the name is not read as an allowed word's letter ("scunth0rpe" is refused). An allowed word
+     *  that is itself a listed word lets that word through. An entry written with separators ("chorlton-cum-hardy")
+     *  is exact: it lets through only a name that is exactly it, separators included. (default: none) */
+    allowlist?: readonly string[];
 };
 /** Options for `createInvisibleCharacterValidator()`. */
 type InvisibleCharacterValidatorOptions = {
@@ -157,9 +221,20 @@ type InvisibleCharacterValidatorOptions = {
     /** Reject combining marks (Unicode category `M*`) often used for visual obfuscation (default: `false`). */
     rejectCombiningMarks?: boolean;
 };
-/** Options for `canonicalise()` LLM preprocessing. */
+/**
+ * Options for `canonicalise()` LLM preprocessing.
+ *
+ * A word is rewritten when it shows a sign of tampering: it mixes Latin with another script, it has a letter not in
+ * modern use that is built on a Latin letter (ɦ, ꞡ, ɏ; a fullwidth or mathematical letter), or it has Latin letters
+ * and a listed lookalike scoring at least `threshold`. In such a word every lookalike is replaced: listed lookalikes
+ * whatever their score, and any letter built on a Latin letter (ŧ, İ) by its base letter, in the case of the word
+ * around it. A word with no such sign is left as it is, so Turkish İstanbul or Russian Москва pass through.
+ */
 type CanonicaliseOptions = {
-    /** Minimum visual score required for replacement (default: `0.7`). */
+    /**
+     * The visual score at which a listed lookalike on its own marks a word as tampered (default: `0.7`). When you set it,
+     * it is also a floor: lookalikes scoring below it are never replaced.
+     */
     threshold?: number;
     /** Include confusable-vision novel discoveries in addition to TR39 mappings (default: `true`). */
     includeNovel?: boolean;
@@ -168,14 +243,15 @@ type CanonicaliseOptions = {
     /**
      * Canonicalisation strategy (default: `"mixed"`).
      *
-     * - `"mixed"` -- only replace confusable characters inside tokens that already
-     *   contain Latin letters. Standalone non-Latin words (e.g. "Москва") are
-     *   preserved.  Safe for multilingual text.
+     * - `"mixed"` -- only rewrite words that show a sign of tampering (see above).
+     *   Standalone non-Latin words (e.g. "Москва") and ordinary accented words
+     *   (e.g. "İstanbul") are preserved.  Safe for multilingual text.
      *
      * - `"all"` -- replace every confusable character regardless of surrounding
-     *   context.  Use this when the document is known to be Latin-script (e.g.
-     *   an English contract) and you want to catch attackers who substitute
-     *   every character in a word.
+     *   context, and fold every letter built on a Latin letter (ŧ, İ, ö) to it.
+     *   Use this when the document is known to be Latin-script (e.g. an English
+     *   contract) and you want to catch attackers who substitute every character
+     *   in a word.
      */
     strategy?: "mixed" | "all";
     /**
@@ -206,10 +282,13 @@ type ScanFinding = {
     script: string;
     /** Canonical Latin equivalent selected by the lookup table. */
     latinEquivalent: string;
-    /** Visual similarity score for this mapping (0–1, from RaySpace measurement). */
+    /** Visual similarity score for this mapping (0–1, from RaySpace measurement; 0 for a `fold`). */
     visualScore: number;
-    /** Mapping source (`tr39` baseline or `novel` discovery). */
-    source: "tr39" | "novel";
+    /**
+     * Mapping source: `tr39` baseline, `novel` discovery, or `fold`, a letter built on a Latin letter (ŧ, ɦ, İ) folded
+     * to it in a word that shows tampering.
+     */
+    source: "tr39" | "novel" | "fold";
     /** UTF-16 code-unit offset in the input string. */
     index: number;
     /** Token/word containing this character. */
@@ -244,6 +323,10 @@ type SkeletonOptions = {
      *  Default: `CONFUSABLE_MAP_FULL` (complete TR39 map, no NFKC filtering).
      *  Pass `CONFUSABLE_MAP` if your pipeline runs NFKC before calling skeleton(). */
     map?: Record<string, string>;
+    /** Treat the input as shown with its case, so ASCII capitals Unicode maps to another letter count as that letter
+     *  (capital I as l: "paypaI" has the skeleton of "paypal"). For names displayed as typed. Default `false`: names
+     *  compare without case ("ADMIN" is "admin"). `areConfusable()` checks both. */
+    preserveCase?: boolean;
     /** Also remove diacritics (the combining marks of the Combining Diacritical Marks blocks, such as a dot below,
      *  an accent or a hook), so `ạ` matches `a` and `ẹ` matches `e`. TR39 keeps them, but a small mark is easy to
      *  miss, and Chromium removes Latin diacritics when it checks a domain against top domains. Marks that scripts
@@ -253,11 +336,11 @@ type SkeletonOptions = {
 /** Options for `areConfusable()` with optional weight-based matching. */
 type AreConfusableOptions = SkeletonOptions & {
     /** Optional measured visual weights for weight-based confusable matching.
-     *  When provided, character pairs in the weight table are also considered confusable. */
+     *  When provided, a measured pair at the same position also counts as alike. */
     weights?: ConfusableWeights;
     /** Filter weights by deployment context.
-     *  - `'identifier'`: only apply weights for XID_Continue sources
-     *  - `'domain'`: only apply weights for IDNA PVALID sources
+     *  - `'identifier'`: only apply pairs whose two characters are both XID_Continue
+     *  - `'domain'`: only apply pairs whose two characters are both IDNA PVALID
      *  - `'all'` (default): apply all weights regardless of properties */
     context?: "identifier" | "domain" | "all";
 };
@@ -290,8 +373,8 @@ type ConfusableDistanceOptions = {
      *  and novel pairs (not in TR39 map) use their visual-weight cost. */
     weights?: ConfusableWeights;
     /** Filter weights by deployment context.
-     *  - `'identifier'`: only apply weights for XID_Continue sources
-     *  - `'domain'`: only apply weights for IDNA PVALID sources
+     *  - `'identifier'`: only apply pairs whose two characters are both XID_Continue
+     *  - `'domain'`: only apply pairs whose two characters are both IDNA PVALID
      *  - `'all'` (default): apply all weights regardless of properties */
     context?: "identifier" | "domain" | "all";
 };
@@ -366,6 +449,14 @@ type RiskReason = {
 type RiskLevel = "low" | "medium" | "high";
 /** Policy action derived from the configured thresholds. */
 type RiskAction = "allow" | "warn" | "block";
+/**
+ * How a name matched a protected target:
+ * - `exact`: it is the target.
+ * - `lookalike`: it differs only by lookalikes and invisible characters, or its skeleton collides. Can block.
+ * - `lookalike-extension`: it spells the whole target with a lookalike and adds letters. Warns at most.
+ * - `typo`: one letter changed, added, dropped or swapped, not a lookalike, from a name in `protect`. Warns at most.
+ */
+type RiskMatchEvidence = "exact" | "lookalike" | "lookalike-extension" | "typo";
 /** A nearest protected target returned by risk scoring. */
 type RiskMatch = {
     target: string;
@@ -373,14 +464,20 @@ type RiskMatch = {
     distance: number;
     chainDepth: number;
     skeletonEqual: boolean;
+    /** How the name matched the target. */
+    evidence: RiskMatchEvidence;
     reasons: string[];
 };
 /** Options for `guard.checkRisk()`. */
 type CheckRiskOptions = {
     /** Additional high-value identifiers to protect against confusable variants. */
     protect?: string[];
-    /** Include configured reserved names in the protected target set (default: true). */
+    /** Include configured reserved names in the protected target set (default: true). A reserved name that is not in
+     *  `protect` is matched by lookalikes only, not by a one-letter typo. */
     includeReserved?: boolean;
+    /** Count leetspeak swaps (4 for a, 1 for i, 5 for s, $ for s) as lookalikes, so p4ypal or adm1n can block
+     *  (default: false). The table is the profanity matcher's aggressive one. */
+    leetspeak?: boolean;
     /** Confusable map used for skeletoning and distance scoring (default: `CONFUSABLE_MAP_FULL`). */
     map?: Record<string, string>;
     /** Number of highest-risk matches to return (default: 3). */
@@ -397,6 +494,9 @@ type RiskCheckResult = {
     score: number;
     level: RiskLevel;
     action: RiskAction;
+    /** False when the name shows nothing visual: no lookalike or exact match of a protected target, and no lookalike,
+     *  invisible or mixed-script characters. Its score is then held below the block threshold, whatever it is. */
+    canBlock: boolean;
     reasons: RiskReason[];
     matches: RiskMatch[];
 };
@@ -452,6 +552,8 @@ type NamespaceProfileName = "consumer-handle" | "org-slug" | "developer-id";
 type NamespaceProfilePreset = {
     description: string;
     pattern: RegExp;
+    /** The message for a name that doesn't match `pattern`, used unless you set `messages.invalid` or your own pattern */
+    invalidMessage?: string;
     normalizeUnicode: boolean;
     allowPurelyNumeric: boolean;
     risk: Required<NonNullable<NamespaceConfig["risk"]>>;
@@ -504,16 +606,24 @@ declare function createPredicateValidator(predicate: (value: string) => boolean
 /**
  * Create a validator that rejects identifiers containing profanity or offensive words.
  *
- * Supply your own word list - no words are bundled with the library.
+ * Supply your own word list, or the English list from `namespace-guard/profanity-en`.
  * The returned function is compatible with `config.validators`.
  *
+ * An entry of one word with at least `minSubstringLength` letters is looked for anywhere in a name ("shitposter").
+ * Other entries are matched as whole words: the whole name, or a part of it between separators, digits or its ends,
+ * with or without separators between its letters. These are shorter entries ("ass" refuses "my-ass", not "class"),
+ * entries written as several words ("h e l l", "blow job"), and entries whose letters are common inside ordinary
+ * English words (122 sequences measured from the English list, such as anal, rape and cock). Words on `allowlist`
+ * shield the listed words inside them: with `allowlist: ["scunthorpe"]`, "scunthorpe-fc" and "scun-thorpe" pass, and
+ * "xcuntx" and "s-cunt-horpe" don't, since a part of a name that is a listed word on its own still counts.
+ *
  * @param words - Array of words to block
  * @param options - Optional settings
  * @param options.message - Custom rejection message (default: "That name is not allowed.")
- * @param options.checkSubstrings - Check if identifier contains a blocked word as a substring (default: true)
+ * @param options.checkSubstrings - Also refuse names that contain a listed word, not only names that are one (default: true)
  * @param options.mode - `basic` (lowercase only) or `evasion` (Unicode/substitute folding) (default: `evasion`)
  * @param options.variantProfile - `balanced` (precision-first) or `aggressive` (broader substitutes) (default: `balanced`)
- * @param options.minSubstringLength - Minimum blocked-word length used in substring checks (default: `4`)
+ * @param options.minSubstringLength - Fewest letters an entry needs to be looked for inside longer words (default: `4`)
  * @param options.map - Confusable map used by `mode: "evasion"` (default: `CONFUSABLE_MAP_FULL`)
  * @param options.maxFoldVariants - Max folded candidates considered in evasion mode (default: 64)
  * @returns An async validator function for use in `config.validators`
@@ -532,39 +642,6 @@ declare function createPredicateValidator(predicate: (value: string) => boolean
  * ```
  */
 declare function createProfanityValidator(words: readonly string[], options?: ProfanityValidatorOptions): NamespaceValidator;
-/**
- * Mapping of visually confusable Unicode characters to their Latin/digit equivalents.
- * Generated from Unicode TR39 confusables.txt + supplemental Latin small capitals.
- * Covers every single-character mapping to a lowercase Latin letter or digit,
- * excluding characters already handled by NFKC normalization (either collapsed
- * to the same target, or mapped to a different valid Latin char/digit).
- * Regenerate: `npx tsx scripts/generate-confusables.ts`
- *
- * Data source: Unicode confusables.txt (https://unicode.org/Public/security/latest/confusables.txt)
- * Copyright 1991-Present Unicode, Inc. Licensed under the Unicode License v3.
- * See https://www.unicode.org/terms_of_use.html
- */
-declare const CONFUSABLE_MAP: Record<string, string>;
-/**
- * Complete TR39 confusable mapping: every single-character mapping to a
- * lowercase Latin letter or digit from confusables.txt, with no NFKC filtering.
- *
- * Use this when your pipeline does NOT run NFKC normalization before confusable
- * detection (which is most real-world systems: TR39 skeleton uses NFD, Chromium
- * uses NFD, Rust uses NFC, django-registration uses no normalization at all).
- *
- * Includes ~1,400 entries vs CONFUSABLE_MAP's ~613 NFKC-deduped entries.
- * The additional entries cover characters that NFKC normalization would handle
- * (mathematical alphanumerics, fullwidth forms, etc.) plus the 31 entries where
- * TR39 and NFKC disagree on the target letter.
- *
- * Regenerate: `npx tsx scripts/generate-confusables.ts`
- *
- * Data source: Unicode confusables.txt (https://unicode.org/Public/security/latest/confusables.txt)
- * Copyright 1991-Present Unicode, Inc. Licensed under the Unicode License v3.
- * See https://www.unicode.org/terms_of_use.html
- */
-declare const CONFUSABLE_MAP_FULL: Record<string, string>;
 /**
  * Derive the set of characters where TR39 prototype mapping and NFKC lowercase
  * mapping disagree on single ASCII letter/digit outcomes.
@@ -576,7 +653,7 @@ declare function deriveNfkcTr39DivergenceVectors(map?: Record<string, string>):
  */
 declare const NFKC_TR39_DIVERGENCE_VECTORS: NfkcTr39DivergenceVector[];
 /** Named composability regression suite (TR39-full vs NFKC lowercase). */
-declare const COMPOSABILITY_VECTOR_SUITE = "nfkc-tr39-divergence-v1";
+declare const COMPOSABILITY_VECTOR_SUITE = "nfkc-tr39-divergence-v2";
 /** Named alias for `NFKC_TR39_DIVERGENCE_VECTORS` for cross-library regression tests. */
 declare const COMPOSABILITY_VECTORS: readonly ComposabilityVector[];
 /** Number of vectors in the composability regression suite. */
@@ -586,9 +663,10 @@ declare const COMPOSABILITY_VECTORS_COUNT: number;
  *
  * Catches spoofing attacks where characters from other scripts are substituted for
  * visually identical Latin characters (e.g., Cyrillic "а" for Latin "a" in "admin").
- * Uses a comprehensive mapping of 613 character pairs generated from Unicode TR39
- * confusables.txt, covering Cyrillic, Greek, Armenian, Cherokee, IPA, Latin small
- * capitals, Canadian Syllabics, Georgian, Lisu, Coptic, and many other scripts.
+ * Uses `CONFUSABLE_MAP` (1,018 characters): Unicode's confusables.txt with NFKC's own
+ * mappings left out, plus the lookalikes confusable-vision found alike in place. It
+ * refuses any name containing one of these characters, including names written wholly
+ * in another script (москва) and Latin letters listed as lookalikes (í, ı).
  *
  * @param options - Optional settings
  * @param options.message - Custom rejection message (default: "That name contains characters that could be confused with other letters.")
@@ -639,14 +717,16 @@ declare function canonicalise(text: string, options?: CanonicaliseOptions): stri
  */
 declare function scan(text: string, options?: ScanOptions): ScanResult;
 /**
- * Fast gate for LLM pipelines.
+ * Fast gate for LLM pipelines: `true` exactly when `canonicalise()` with the
+ * same options would leave the text unchanged.
  *
- * With the default `strategy: "mixed"`, returns `false` as soon as a
- * mixed-script confusable substitution is found.  Standalone non-Latin
+ * With the default `strategy: "mixed"`, returns `false` as soon as a word
+ * that shows a sign of tampering has a character to rewrite (see
+ * `CanonicaliseOptions`).  Standalone non-Latin words and ordinary accented
  * words do not fail this gate.
  *
- * With `strategy: "all"`, returns `false` if any confusable character is
- * found, regardless of surrounding context.
+ * With `strategy: "all"`, returns `false` if any confusable character or
+ * letter built on a Latin letter is found, regardless of surrounding context.
  */
 declare function isClean(text: string, options?: ScanOptions): boolean;
 /**
@@ -689,8 +769,9 @@ declare function confusableDistance(a: string, b: string, options?: ConfusableDi
  * Check whether two strings are visually confusable.
  *
  * Without `weights`, compares TR39 skeletons only (backward compatible).
- * With `weights`, also checks whether any character pair in `a` x `b`
- * has a measured visual weight, enabling cross-script confusable detection.
+ * With `weights`, also lines the two strings up character by character: they are confusable when each position's
+ * characters share a skeleton or are a measured pair (in `context`), in order, with one character allowed to stand
+ * for several (m for rn). This finds pairs no standard lists, such as two non-Latin scripts.
  *
  * @param a - First string
  * @param b - Second string
@@ -701,8 +782,8 @@ declare function confusableDistance(a: string, b: string, options?: ConfusableDi
  * ```ts
  * areConfusable("paypal", "\u0440\u0430ypal")           // true (skeleton match)
  * areConfusable("hello", "world")                        // false
- * areConfusable("\u1175", "\u4E28", { weights })         // true (cross-script weight)
- * areConfusable("\u1175", "\u4E28")                      // false (no weights = skeleton only)
+ * areConfusable("\u3163", "\u4E28", { weights })         // true: Hangul \u3163 and Han \u4E28, a measured pair
+ * areConfusable("\u3163", "\u4E28")                      // false (no weights = skeleton only)
  * ```
  */
 declare function areConfusable(a: string, b: string, options?: AreConfusableOptions): boolean;
@@ -739,7 +820,7 @@ type CrossScriptRiskResult = {
  * @example
  * ```ts
  * detectCrossScriptRisk("hello")                          // riskLevel: "none"
- * detectCrossScriptRisk("\u1175\u4E28", { weights })      // riskLevel: "high"
+ * detectCrossScriptRisk("\u3163\u4E28", { weights })      // riskLevel: "high", scripts: ["han", "hangul"]
  * ```
  */
 declare function detectCrossScriptRisk(identifier: string, options?: {
@@ -801,8 +882,8 @@ type DomainSpoofOptions = {
  *   character in the target, verified against the confusable map and optional
  *   measured weights.
  *
- * Mixed-script substitutions are deliberately excluded because registrars
- * reject them.
+ * Mixed-script substitutions are left out because most registries refuse them
+ * (some registered ones exist; d0ma1n finds those).
  *
  * @param label  - The suspicious domain label to check (e.g. Cyrillic "раураl")
  * @param target - The legitimate domain label (e.g. "paypal")
@@ -817,9 +898,9 @@ type DomainSpoofOptions = {
  * // Full-Cyrillic lookalike — realistic, registrable spoof
  * isDomainSpoof("\u0440\u0430\u0443\u0440\u0430\u04cf", "paypal",
  *   { weights: CONFUSABLE_WEIGHTS });
- * // { spoof: true, script: "cyrillic", danger: 0.91, substitutions: [...] }
+ * // { spoof: true, script: "cyrillic", danger: 0.781, substitutions: [...] }
  *
- * // Mixed-script — cannot be registered, not a spoof
+ * // Mixed-script — most registries refuse it, so it isn't checked
  * isDomainSpoof("\u0440aypal", "paypal",
  *   { weights: CONFUSABLE_WEIGHTS });
  * // { spoof: false }
@@ -904,4 +985,4 @@ declare function createNamespaceGuard(config: NamespaceConfig, adapter: Namespac
 /** The guard instance returned by `createNamespaceGuard`. */
 type NamespaceGuard = ReturnType<typeof createNamespaceGuard>;
 
-export { type AreConfusableOptions, type AssertClaimableOptions, COMPOSABILITY_VECTORS, COMPOSABILITY_VECTORS_COUNT, COMPOSABILITY_VECTOR_SUITE, CONFUSABLE_MAP, CONFUSABLE_MAP_FULL, type CanonicaliseOptions, type CheckManyOptions, type CheckResult, type CheckRiskOptions, type ClaimOptions, type ClaimResult, type ComposabilityVector, type ConfusableDistanceOptions, type ConfusableDistanceResult, type ConfusableDistanceStep, type ConfusableWeight, type ConfusableWeights, type CrossScriptRiskResult, DEFAULT_PROTECTED_TOKENS, type DomainSpoofOptions, type DomainSpoofResult, type DomainSpoofSubstitution, type EnforceRiskOptions, type EnforceRiskResult, type FindOneOptions, type InvisibleCharacterValidatorOptions, LLM_CONFUSABLE_MAP, LLM_CONFUSABLE_MAP_CHAR_COUNT, LLM_CONFUSABLE_MAP_PAIR_COUNT, LLM_CONFUSABLE_MAP_SOURCE_COUNTS, NAMESPACE_PROFILES, NFKC_TR39_DIVERGENCE_VECTORS, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceProfileName, type NamespaceProfilePreset, type NamespaceSource, type NamespaceValidator, type NamespaceValidatorResult, type NfkcTr39DivergenceVector, type OwnershipScope, type PredicateValidatorOptions, type ProfanityValidationMode, type ProfanityValidatorOptions, type ProfanityVariantProfile, type RiskAction, type RiskCheckResult, type RiskLevel, type RiskMatch, type RiskReason, type RiskReasonCode, type ScanFinding, type ScanOptions, type ScanResult, type SkeletonOptions, type SuggestStrategyName, type UniqueViolationDetector, areConfusable, canonicalise, confusableDistance, createHomoglyphValidator, createInvisibleCharacterValidator, createNamespaceGuard, createNamespaceGuardWithProfile, createPredicateValidator, createProfanityValidator, deriveNfkcTr39DivergenceVectors, detectCrossScriptRisk, isClean, isDomainSpoof, isLikelyUniqueViolationError, normalize, scan, skeleton };
+export { type AreConfusableOptions, type AssertClaimableOptions, COMPOSABILITY_VECTORS, COMPOSABILITY_VECTORS_COUNT, COMPOSABILITY_VECTOR_SUITE, CONFUSABLES_DATE, CONFUSABLE_MAP, CONFUSABLE_MAP_CASED, CONFUSABLE_MAP_FULL, type CanonicaliseOptions, type CheckManyOptions, type CheckResult, type CheckRiskOptions, type ClaimOptions, type ClaimResult, type ComposabilityVector, type ConfusableDistanceOptions, type ConfusableDistanceResult, type ConfusableDistanceStep, type ConfusableWeight, type ConfusableWeights, type CrossScriptRiskResult, DEFAULT_PROTECTED_TOKENS, type DomainSpoofOptions, type DomainSpoofResult, type DomainSpoofSubstitution, type EnforceRiskOptions, type EnforceRiskResult, type FindOneOptions, type InvisibleCharacterValidatorOptions, LLM_CONFUSABLE_MAP, LLM_CONFUSABLE_MAP_CHAR_COUNT, LLM_CONFUSABLE_MAP_PAIR_COUNT, LLM_CONFUSABLE_MAP_SOURCE_COUNTS, type LlmConfusableMapEntry, MEASURED_CONFUSABLES, type MeasuredConfusable, NAMESPACE_PROFILES, NFKC_TR39_DIVERGENCE_VECTORS, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceProfileName, type NamespaceProfilePreset, type NamespaceSource, type NamespaceValidator, type NamespaceValidatorResult, type NfkcTr39DivergenceVector, type OwnershipScope, type PredicateValidatorOptions, type ProfanityValidationMode, type ProfanityValidatorOptions, type ProfanityVariantProfile, type RiskAction, type RiskCheckResult, type RiskLevel, type RiskMatch, type RiskMatchEvidence, type RiskReason, type RiskReasonCode, type ScanFinding, type ScanOptions, type ScanResult, type SkeletonOptions, type SuggestStrategyName, type UniqueViolationDetector, areConfusable, canonicalise, confusableDistance, createHomoglyphValidator, createInvisibleCharacterValidator, createNamespaceGuard, createNamespaceGuardWithProfile, createPredicateValidator, createProfanityValidator, deriveNfkcTr39DivergenceVectors, detectCrossScriptRisk, isClean, isDomainSpoof, isLikelyUniqueViolationError, normalize, scan, skeleton };