Bidi and Confusable Text Safety

Detects bidirectional control characters and mixed-script confusables that make text display differently from what it contains.

THE SILENT FAILURE. Unicode has invisible characters that REORDER how text is displayed. A string containing a right-to-left override renders in an order different from its byte sequence, so a file named photo_gnp.exe can display as photo_exe.png, and a source comment can visually swallow the line after it. This is the Trojan Source class: reviewed code that reads as safe and compiles as something else. Nothing warns, because the rendering is correct per the Unicode Bidirectional Algorithm. The human is the one being fooled.

The related failure is CONFUSABLES: Cyrillic small a is a different codepoint from Latin small a and renders identically, so a domain, package name or username can be visually identical to a trusted one while being a different string. Every equality check behaves correctly and the human reads the wrong thing.

It reports findings with exact codepoint offsets so a caller can highlight them, and keeps detection SEPARATE from sanitising, because silently rewriting a user's text is its own bug.

IT DOES NOT FLAG ALL BIDI CONTROLS. Arabic and Hebrew use these mechanisms correctly, and a scanner that flags legitimate RTL text is unusable and gets switched off -- after which it catches nothing. It distinguishes balanced, well-formed sequences from unbalanced or overriding ones. Mixed-script detection is a HEURISTIC that cannot decide intent; it surfaces candidates for a human, and the README says exactly that rather than implying more.

VERIFIED: 70 tests. Every mutation was observed FAILING before the source was restored -- a test never seen to fail is a decoration. Independently reviewed by a verifier whose job was to find what is wrong, not to agree.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function splitParagraphs(text: string): Paragraph[];
  export function findParagraphFor(paragraphs: Paragraph[], index: number): Paragraph;
  export function sanitizeBidi(text: string, options: SanitizeOptions = {}): string;
  export function scanBidiControls(text: string): BidiControlFinding[];
  export function findUnbalancedBidiSpans(text: string): UnbalancedSpanFinding[];
  export function findMixedScriptRuns(text: string): MixedScriptFinding[];
  export function findConfusableChars(text: string): ConfusableFinding[];
  export function scanText(text: string): ScanResult;
  export function getScript(char: string): string;
  export function isScriptNeutral(script: string): boolean;

  export type KnownScript = (typeof CANDIDATE_SCRIPTS)[number];
  export type UnbalancedKind = 'unclosed-embed' | 'unclosed-isolate' | 'stray-pdf' | 'stray-pdi';
  export type SanitizeMode = 'strip' | 'escape';
  export type SanitizeScope = 'all' | 'unbalanced-only';