typos

Make a few misstakes.

Give your website a small, deliberate imperfection. Agent instructions and a tiny JavaScript library with no runtime dependencies for adding readable typos to ordinary English copy.

Give this to your agent

Read https://raw.githubusercontent.com/visualizevalue/typos/main/skills/typos/SKILL.md
as Markdown, then use it to add a few subtle, deliberate typos to my website.
Inspect the project and make the changes. Keep the meaning clear, protect
functional and sensitive text, and show me the words you changed.

The instructions are ordinary text to read, not a script to execute. Start with SKILL.md. llms.txt indexes the repository; AGENTS.md covers work on this package.

For a handful of authored sentences, direct copy edits are usually all you need. The library is useful when you want repeatable changes across more text.

Install from GitHub

Requires Node.js 22 or newer for the CLI and development. This package is distributed through GitHub, not the npm registry.

npm install github:visualizevalue/typos

Text

import { typoText } from '@visualizevalue/typos';

const result = typoText('A little imperfection makes something interesting.', {
  rate: 0.15,
  seed: 'my-website',
  maxChanges: 2,
});

console.log(result.text);
console.log(result.changes); // [{ index, from, to, type }]

The same text, seed, and options produce the same result. index is the original UTF-16 character offset. from and to contain the original and changed word.

Option	Default	Meaning
rate	0.02	Chance of changing each eligible word, from 0 to 1.
seed	'typos'	Seed for repeatable changes.
maxChanges	Infinity	Maximum number of changed words per call.
minWordLength	4	Minimum length of an eligible word.
types	['transpose', 'omit', 'duplicate']	Allowed mutations.
excludeWords	[]	Words to leave alone.

transpose swaps adjacent interior letters. omit removes an interior letter. duplicate repeats one. The first and last character stay intact.

Only whole ASCII English words are eligible. URLs, email addresses, numbers, code-like identifiers, acronyms, Unicode words, and compound words are protected. The function cannot understand legal meaning, product names, or your content policy: pass it only suitable prose and use excludeWords for additional protection. A low rate may produce zero changes on short text.

A static page

Use an explicit container of ordinary prose. Import this module through your bundler.

<article data-typos>
  <p>A little imperfection makes something interesting.</p>
  <p data-no-typos>Keep this sentence exactly as written.</p>
</article>

import { typoWebsite } from '@visualizevalue/typos/browser';

const article = document.querySelector('[data-typos]');

if (article) {
  const result = typoWebsite(article, {
    rate: 0.02,
    seed: 'my-website',
    maxChanges: 3,
    exclude: '.keep-exact',
  });

  console.log(result.changes); // [{ node, original, text, changes }]
  // Later: result.restore();
}

typoWebsite(root, options) requires an Element. It accepts the text options plus an optional exclude CSS selector and caps changes across the selected root. It changes text nodes, never HTML or attributes.

It skips scripts, styles, code, preformatted text, forms, controls, labels, summaries, links, SVG, MathML, editable content, [hidden], [inert], [aria-hidden="true"], and [data-no-typos]. It also preserves elements with roles or accessible-name attributes, plus text referenced by aria-labelledby or aria-describedby. CSS visibility is not inspected. Choose the root carefully and review the copy.

restore() restores only nodes that still contain this call's generated text and returns the number restored. It leaves later edits alone. The browser helper runs once and does not watch rerenders. In React, SSR, and similar frameworks, prefer direct copy edits or typoText during rendering with a stable seed and identical server/client input.

Command line

npx --package=github:visualizevalue/typos typos --text 'Make something interesting.' --rate 1 --max-changes 1
npx --package=github:visualizevalue/typos typos --file copy.txt --seed homepage --json
printf '%s\n' 'A little imperfection.' | npx --package=github:visualizevalue/typos typos --rate 0.1

Choose --text, --file, or standard input. The CLI writes the resulting text to standard output; it never edits the input file. --json returns the full { text, changes } result.

Options: --rate, --seed, --max-changes, --types transpose,omit,duplicate, repeatable --exclude-word WORD, --json, --help, and --version.

Develop

git clone https://github.com/visualizevalue/typos.git
cd typos
npm ci
npm test

MIT licensed. Made by Visualize Value.