Skip to content

docs: lead with an example you can see - #12

Merged
chrisdengso merged 1 commit into
mainfrom
docs/clearer-usage-example
Jul 19, 2026
Merged

chrisdengso merged 1 commit into
mainfrom
docs/clearer-usage-example

Conversation

@chrisdengso

Copy link
Copy Markdown
Contributor

Follow-up to #10. The quick-start analyzed a sentence a reader cannot tell is spoofed — good demonstration of the attack, poor demonstration of the library, since input and output look the same on screen.

Now opens with visibly styled text:

const r = analyze('Get 𝐅𝐑𝐄𝐄 ⓒⓡⓨⓟⓣⓞ now');

r.normalized; // 'Get FREE crypto now'

Three different styling systems (fullwidth, math-bold, circled) in one sentence, with now already ASCII and returned untouched — so the before/after is obvious at a glance.

Shows the whole signals object, all five keys, instead of a single field — the previous example only ever showed confusable_word, which made the other four invisible to a reader skimming the API.

The pixel-identical case is now the follow-up, where it reads as the punchline it deserves to be:

lookalike === 'paypal'; // false
[...lookalike].map((c) => c.codePointAt(0).toString(16));
// ['440', '430', '443', '440', '430', '6c']  — Cyrillic, except the final 'l'

Adds an all-signals example — one message carrying a Cyrillic lookalike, an intra-word script mix, a zero-width space, stacked marks and a NUL byte, with all five firing.

Every value above is asserted in test/readme.test.ts (262 tests pass).

Two things worth noting, both caught by that test file:

  • 'раураl' === 'paypal' does not typecheck as a literal comparison (TS2367, "no overlap") — the snippet needed an explicit : string annotation to be copy-pasteable.
  • I nearly used 𝐁𝐈𝐆 in the headline example; its skeleton is BlG, since UTS #39 folds capital-I to lowercase-l. Avoided capital-I words.

Merge this before #11 ("chore: version packages") so 0.2.0 publishes with the current README.

The quick-start analyzed a sentence a reader cannot tell is spoofed — it
demonstrates the attack, but not the library. It now opens with visibly styled
text (fullwidth, math-bold, circled) where input and output obviously differ,
shows the full five-key `signals` object rather than a single field, then makes
the pixel-identical case the follow-up. Adds an example where all five signals
fire at once.

Every value is asserted in test/readme.test.ts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@chrisdengso
chrisdengso merged commit 714bfa7 into main Jul 19, 2026
1 check passed
@chrisdengso
chrisdengso deleted the docs/clearer-usage-example branch July 19, 2026 22:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant