# `english-wikipedia` — top English Wikipedia tokens

## Purpose

Frequency-ranked dictionary of the most common English tokens observed in
Wikipedia. The matcher uses this to flag passwords containing real English
words; a dictionary word with rank 50 contributes `50` guesses to the
cover product, far below the naive character-entropy floor.

## Features

- Frozen `ReadonlyMap<string, number>` keyed by lowercase token
- Default 100 entries — covers high-frequency stopwords plus common nouns
- Swappable at runtime via `loadDictionaries({ english_wikipedia: <fullMap> })`

## Usage: Basic Example

```ts
import { ENGLISH_WIKIPEDIA_DICTIONARY } from "@suaveplan/password-strength/dicts/en";

console.log(ENGLISH_WIKIPEDIA_DICTIONARY.get("the")); // 1
```

## Usage: Advanced Example

```ts
import { assess, loadDictionaries } from "@suaveplan/password-strength";
import { ENGLISH_WIKIPEDIA_DICTIONARY } from "@suaveplan/password-strength/dicts/en";

const dicts = loadDictionaries({ english_wikipedia: ENGLISH_WIKIPEDIA_DICTIONARY });
const result = assess("hello-world!", { dictionaries: dicts });
console.log(result.score);
```

## API Reference

- `ENGLISH_WIKIPEDIA_DICTIONARY: ReadonlyMap<string, number>` — frozen
  frequency-ranked English Wikipedia dictionary.

## Implementation Notes

The default 100-entry list is intentionally a subset of the published
zxcvbn frequency list. Production deployments should swap in a fuller
list (typically the published top-30 000 tokens). The bundled subset
covers the high-frequency stopwords and common nouns the spec scenarios
exercise; entries are deduplicated by lowercase token so a single insertion
loop over the source data does not corrupt the rank ordering.

## Additional Implementation Notes

The implementation follows the canonical zxcvbn algorithm from Wheeler 2016 with
the suaveplan-style additions described in the package proposal: structured error
codes via the `defineCodes` registry, Zod boundaries at every public entry
point, OTel histograms and counters keyed to low-cardinality attributes, and
a strict input-length guard at 200 characters. Consumers integrate with their
existing observability stack by installing a meter provider before importing
the package, and with their i18n stack via the `MessageResolver` callback type
declared in `@suaveplan/types`. The bundled data tables are intentionally
small to keep the package bundle compact; production deployments should swap
in fuller frequency-ranked tables via `loadDictionaries`. The default English
dictionary set is a frozen `DictionarySet` that the matcher never mutates;
caller-supplied dictionaries override defaults by name.