cizgile 0.1.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <br>
-  <img src=".github/assets/cover.svg?v=1a3fd12" alt="cizgile — Zero-dependency URL slug engine" width="100%">
+  <img src=".github/assets/cover.svg?v=bcfc1d9" alt="cizgile — Zero-dependency URL slug engine" width="100%">
   <br><br>
   <b style="font-size: 2em;">cizgile</b>
   <br><br>
@@ -9,6 +9,7 @@
   Turn any title into a clean URL slug — in any language — and work with URLs the way RFC 3986 and RFC 3987 describe them. Pure TypeScript, works everywhere.
   <br><br>
   <a href="https://npmjs.com/package/cizgile"><img src="https://img.shields.io/npm/v/cizgile?style=flat&colorA=18181B&colorB=34d399" alt="npm version"></a>
+  <a href="https://github.com/productdevbook/cizgile/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/productdevbook/cizgile/ci.yml?style=flat&colorA=18181B&colorB=34d399" alt="ci"></a>
   <a href="https://npmjs.com/package/cizgile"><img src="https://img.shields.io/npm/dm/cizgile?style=flat&colorA=18181B&colorB=34d399" alt="npm downloads"></a>
   <a href="https://bundlephobia.com/result?p=cizgile"><img src="https://img.shields.io/bundlephobia/minzip/cizgile?style=flat&colorA=18181B&colorB=34d399" alt="bundle size"></a>
   <a href="https://github.com/productdevbook/cizgile/blob/main/LICENSE"><img src="https://img.shields.io/github/license/productdevbook/cizgile?style=flat&colorA=18181B&colorB=34d399" alt="license"></a>
@@ -29,23 +30,23 @@ slugify("Straße Über Ärger", { locale: "de" }) // "strasse-ueber-aerger"
 slugify("你好 World", { unicode: true }) // "你好-world"
 ```
 
-No dependencies. ESM only. Node 20+, Bun, Deno, browsers, edge workers.
+No dependencies. ESM only. Node 20+, Bun and Deno are exercised in CI; the code touches no host API, so browsers and edge workers run it as-is.
 
 ## Why cizgile
 
 - **Slugs that are correct by construction.** Every ASCII slug is a valid URL path segment (RFC 3986 `segment-nz-nc`) — no percent-encoding needed, no `.` or `..`, no accidental scheme prefix.
-- **Speaks your language.** 19 locales (`tr`, `de`, `da`, `sv`, `uk`, `bg`, …) and 7 scripts (Latin, Cyrillic, Greek, Arabic, Armenian, Georgian, Dhivehi). `ß` → `ss`, `İ` → `i`, `Щ` → `shch`.
+- **Speaks your language.** 45 locales (`tr`, `de`, `pl`, `sv`, `uk`, `hi`, `ta`, `ja`, `ko`, …) and 19 scripts (Latin, Cyrillic, Greek, Arabic, Armenian, Georgian, Dhivehi, Hebrew, Hangul, kana, Devanagari and the seven other Indic scripts). `ß` → `ss`, `İ` → `i`, `Щ` → `shch`, `서울` → `seoul`.
 - **Unicode slugs when you want them.** `你好-world` stays readable, and `iriToUri` gives you the exact percent-encoded form for the wire.
 - **A real URL toolkit underneath.** Resolve, normalise, compare, validate and relativise URLs by the RFC, cross-checked against the WHATWG `URL` parser.
 - **Small and tree-shakeable.** `import { slugify }` ships the Latin table only; other scripts load only when you import them.
 
 ## Three entry points
 
-| import                  | what you get                                                                                  |
-| ----------------------- | --------------------------------------------------------------------------------------------- |
-| `cizgile`               | `slugify`, `isSlug`, `createSlugger`, `truncateSlug`, `decamelize`, script and bidi guards    |
-| `cizgile/transliterate` | `transliterate`, per-script tables, locales, `defineLocale`                                   |
-| `cizgile/uri`           | percent-encoding, `resolveUri`, `normalizeUri`, `relativize`, validators, IRI ↔ URI, punycode |
+| import                  | what you get                                                                                          |
+| ----------------------- | ----------------------------------------------------------------------------------------------------- |
+| `cizgile`               | `slugify`, `isSlug`, `createSlugger`, `truncateSlug`, `measure`, `decamelize`, script and bidi guards |
+| `cizgile/transliterate` | `transliterate`, per-script tables, locales, `defineLocale`                                           |
+| `cizgile/uri`           | percent-encoding, `resolveUri`, `normalizeUri`, `relativize`, validators, IRI ↔ URI, punycode         |
 
 ## Slugs
 
@@ -61,29 +62,34 @@ slugify("Hello World", { separator: "_" }) // "hello_world"
 slugify("Donald E. Knuth", { lowercase: false }) // "Donald-E-Knuth"
 slugify("getHTTPResponse", { decamelize: true }) // "get-http-response"
 slugify("the quick brown fox", { maxLength: 9 }) // "the-quick"
+slugify("Ünïcödé Büro", { unicode: true, maxLength: 11, maxLengthUnit: "bytes" }) // "ünïcödé"
+slugify("!!!", { fallback: "untitled" }) // "untitled"
 slugify("C++ & Rust", { replacements: [["C++", "cpp"]] }) // "cpp-and-rust"
 ```
 
 ### Languages and scripts
 
-Locale ids for Latin-script languages; Cyrillic locales and other scripts come from `cizgile/transliterate` so they only end up in your bundle when you use them.
+Locale ids for Latin-script languages; Cyrillic locales and other scripts come from `cizgile/transliterate` so they only end up in your bundle when you use them (or register them once with `registerLocale` and use their ids as strings).
 
 ```ts
 import { slugify } from "cizgile"
-import { cyrillic, greek, uk, defineLocale, de } from "cizgile/transliterate"
+import { cyrillic, greek, uk, ja, ko, defineLocale, de } from "cizgile/transliterate"
 
 slugify("Çay & Simit", { locale: "tr" }) // "cay-ve-simit"
 slugify("Fisch & Chips", { locale: "de" }) // "fisch-und-chips"
 slugify("Ærø", { locale: "da" }) // "aeroe"
+slugify("Zażółć & jaźń", { locale: "pl" }) // "zazolc-i-jazn"
 slugify("Київ", { locale: uk }) // "kyiv"
 slugify("Привет мир", { transliterate: [cyrillic] }) // "privet-mir"
 slugify("Καλημέρα", { transliterate: [greek] }) // "kalimera"
+slugify("서울 & 부산", { locale: ko }) // "seoul-mit-busan"
+slugify("とうきょう", { locale: ja }) // "toukyou"
 
 const swiss = defineLocale(de, { id: "de-CH", table: { ß: "ss" } })
 slugify("Straße", { locale: swiss }) // "strasse"
 ```
 
-Locale ids: `az da de es fi fr hu it nb nl pt sv tr vi`. Locale objects: those plus `bg mk ru sr uk`.
+Locale ids: `az ca cs da de es et fi fr hr hu is it lt lv nb nl pl pt ro sk sl sv tr vi`. Locale objects: those plus `be bg kk mk ru sr uk` (Cyrillic) and `el he hi ja ko` (Greek, Hebrew, Devanagari, kana, Hangul), `bn pa gu or ta te kn ml` (Bengali, Gurmukhi, Gujarati, Odia, Tamil, Telugu, Kannada, Malayalam). `registerLocale(ru, uk)` makes those ids usable as strings too. Every Latin and Cyrillic locale spells `&`, `%`, `$` and `£` in its language: `slugify("50% off", { locale: "de" })` is `"50-prozent-off"`, without a locale `"50-off"`.
 
 ### Unicode slugs
 
@@ -128,41 +134,45 @@ isSlug("hello_world", { separator: "_" }) // true
 isSlug("你好-world", { unicode: true }) // true
 ```
 
-`isSlug` accepts exactly what `slugify` would produce under the same options.
+`isSlug` accepts exactly what `slugify` would produce under the same options, `locale` included.
 
 ### All options
 
-| option                      | default   | what it does                                                                                                                  |
-| --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `separator`                 | `"-"`     | Joins words. Any URL-safe punctuation (`- _ . ~ !$&'()*+,;= @`) or `""`.                                                      |
-| `lowercase`                 | `true`    | `false` keeps the original case.                                                                                              |
-| `unicode`                   | `false`   | Keep letters from every script instead of transliterating to ASCII.                                                           |
-| `locale`                    | —         | Language-specific rules: a locale id or a `Locale` object.                                                                    |
-| `transliterate`             | `true`    | `false` skips the tables (accents still fold); an array adds script tables.                                                   |
-| `decamelize`                | `false`   | `fooBar` → `foo-bar`, `HTMLParser` → `html-parser`.                                                                           |
-| `replacements`              | `[]`      | `[from, to]` pairs applied first; spaces in `to` become separators.                                                           |
-| `remove`                    | `/['’]/g` | Characters to delete rather than turn into separators (`don't` → `dont`).                                                     |
-| `preserveCharacters`        | `[]`      | Extra URL-safe characters to keep, e.g. `["."]` for version numbers.                                                          |
-| `preserveLeadingUnderscore` | `false`   | `_draft` → `_draft`.                                                                                                          |
-| `preserveTrailingSeparator` | `false`   | Keep a trailing separator while the user is still typing.                                                                     |
-| `maxLength`                 | —         | Cut at a word boundary, never inside a character (emoji sequences, combining marks). Counts UTF-16 code units like `.length`. |
-| `scripts`                   | `"any"`   | Unicode mode: UTS #39 mixed-script restriction level.                                                                         |
-| `bidi`                      | `"allow"` | Unicode mode: RFC 3987 §4.2 direction rule — `"encode"` or `"throw"` on violation.                                            |
+| option                      | default   | what it does                                                                                                                                                                       |
+| --------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `separator`                 | `"-"`     | Joins words. Any URL-safe punctuation (`- _ . ~ !$&'()*+,;= @`), several of them (`"--"`), or `""`.                                                                                |
+| `lowercase`                 | `true`    | `false` keeps the original case.                                                                                                                                                   |
+| `unicode`                   | `false`   | Keep letters from every script instead of transliterating to ASCII.                                                                                                                |
+| `locale`                    | —         | Language-specific rules: a locale id or a `Locale` object.                                                                                                                         |
+| `transliterate`             | `true`    | `false` skips the Latin and symbol tables (the locale table and accent folding still apply); `"none"` keeps only accent folding and the symbol words; an array adds script tables. |
+| `decamelize`                | `false`   | `fooBar` → `foo-bar`, `HTMLParser` → `html-parser`.                                                                                                                                |
+| `replacements`              | `[]`      | `[from, to]` pairs applied first; spaces in `to` become separators.                                                                                                                |
+| `remove`                    | `/['’]/g` | A global regex of characters to delete rather than turn into separators (`don't` → `dont`); `false` keeps them.                                                                    |
+| `preserveCharacters`        | `[]`      | Extra URL-safe single characters to keep, e.g. `["."]` for version numbers. The separator or anything outside `segment-nz-nc` throws.                                              |
+| `preserveLeadingUnderscore` | `false`   | `_draft` → `_draft`.                                                                                                                                                               |
+| `preserveTrailingSeparator` | `false`   | Keep a trailing separator while the user is still typing.                                                                                                                          |
+| `maxLength`                 | —         | Cut at a word boundary, never inside a character (emoji sequences, combining marks).                                                                                               |
+| `maxLengthUnit`             | `"units"` | What `maxLength` counts: UTF-16 code units like `.length`, `"code-points"`, `"graphemes"`, or UTF-8 `"bytes"` for a column or filename budget.                                     |
+| `fallback`                  | —         | Used when the result would be `""`: a string or a function of the input, slugified with the same options (`"untitled"`, then `untitled-2` in a slugger).                           |
+| `scripts`                   | `"any"`   | Unicode mode: UTS #39 mixed-script restriction level.                                                                                                                              |
+| `bidi`                      | `"allow"` | Unicode mode: RFC 3987 §4.2 direction rule — `"encode"` or `"throw"` on violation.                                                                                                 |
 
 The pipeline runs in this order: strip control/format characters → NFC → `replacements` → NFKC → `decamelize` → transliterate (locale → your tables → Latin → symbols → strip accents) → lowercase → `remove` → separators → `maxLength` → guards. Output is idempotent: `slugify(slugify(x)) === slugify(x)`.
 
 ## Transliteration on its own
 
 ```ts
-import { transliterate, cyrillic, locales } from "cizgile/transliterate"
+import { transliterate, cyrillic, hangul, kana, devanagari, locales } from "cizgile/transliterate"
 
 transliterate("Straße Ærø") // "Strasse AEro"
 transliterate("Привет", { tables: [cyrillic] }) // "Privet"
 transliterate("Ängsö", { locale: locales.sv }) // "Aengsoe"
-transliterate("你好") // "你好" — unknown scripts are kept (use unknown: "drop" to remove)
+transliterate("서울 ひらがな नमस्ते", { tables: [hangul, kana, devanagari] }) // "seoul hiragana namaste"
+transliterate("नमस्ते 你好") // "नमस्ते 你好" — unknown scripts are kept intact (use unknown: "drop" to remove)
+transliterate("final x² Ⅷ", { nfkc: true }) // "final x2 VIII"
 ```
 
-Tables: `latin symbols cyrillic cyrillicUk cyrillicBg cyrillicMk cyrillicSr greek arabic persian urdu pashto armenian georgian dhivehi`, plus `allScripts`. Where a letter is spelled differently at the start of a word (Armenian `ե`, Ukrainian `є ї й ю я`), the capital carries the word-initial form. `defineLocale` and `mergeTables` return new objects — nothing global is ever mutated.
+Tables: `latin symbols cyrillic cyrillicUk cyrillicBg cyrillicMk cyrillicSr greek arabic persian urdu pashto armenian georgian dhivehi hebrew devanagari bengali gurmukhi gujarati oriya tamil telugu kannada malayalam hangul kana`, plus `allScripts`. Where a letter is spelled differently at the start of a word (Armenian `ե`, Ukrainian `є ї й ю я`), the capital carries the word-initial form. Devanagari and the other Indic scripts are romanised syllable by syllable (inherent `a`, no vowel length, no schwa deletion: `भारत` is `bharata`), Hangul jamo by jamo (Revised Romanization without sound-change rules, so `한국어` is `hangukeo`), kana with Hepburn (the long-vowel mark and sokuon are dropped); kanji and Han are left as they are. `defineLocale` and `mergeTables` return new objects — nothing global is ever mutated.
 
 ## URL toolkit
 
@@ -181,12 +191,18 @@ import {
   isAbsoluteUri,
   isIPv6Address,
   extractUri,
+  getOrigin,
+  sortQuery,
+  joinPaths,
   iriToUri,
   uriToIri,
   domainToAscii,
 } from "cizgile/uri"
 
 resolveUri("http://a/b/c/d;p?q", "../../g") // "http://a/g"
+getOrigin("HTTP://Example.com:80/a?b") // "http://example.com"
+sortQuery("http://a/p?b=2&a=1") // "http://a/p?a=1&b=2"
+joinPaths("/api/", "/v1", "../v2/") // "/api/v2/"
 relativize("http://a/b/c/d;p?q", "http://a/b/g") // "../g"
 normalizeUri("HTTP://www.EXAMPLE.com:80/%7e%41/./b/../c") // "http://www.example.com/~A/c"
 equivalentUris("http://example.com", "http://example.com:80/") // true
@@ -208,13 +224,14 @@ iriToUri("http://例え.jp/résumé", { host: "punycode" }) // "http://xn--r8jz4
 `encodePathSegment(seg, { noColon })`, `encodePath(path, { relative })`, `encodeQuery`, `encodeFragment`, `encodeForm`.
 
 **Hosts (§3.2.2)**
-`isIPv4Address` `isIPv6Address` `isIPvFuture` `isIPLiteral` `isRegName` `isHost` `parseHost` `parseAuthority` `serializeAuthority`. `0x7f.0.0.1` and `2130706433` are registered names, not addresses (§7.4).
+`isIPv4Address` `isIPv6Address` `isIPvFuture` `isIPLiteral` `isRegName` `isHost` `parseHost` `parseAuthority` `serializeAuthority` `normalizeIPv6Address` (RFC 5952). `0x7f.0.0.1` and `2130706433` are registered names, not addresses (§7.4).
 
 **Parsing and validation (§4, Appendix A/B)**
-`parseUri` `serializeUri` — components stay distinct from "absent"; the serializer inserts `/.` or `./` where the grammar requires it.
+`parseUri(uri, { authority })` `serializeUri` — components stay distinct from "absent"; `authority: true` also gives `userinfo`, `host`, `port` and `portNumber`, and the serializer accepts those in place of `authority` and inserts `/.` or `./` where the grammar requires it.
 `isUriReference` `isUri` `isAbsoluteUri` `isRelativeReference` `classifyReference` `pathForm` — validating parser built from the ABNF.
 `isIriReference` `isIri` `isIunreserved` `isIpchar` — the same for IRIs (RFC 3987 §2.2).
-`extractUri(text)` — Appendix C: strips `<>`, quotes, `URL:` prefixes, trailing punctuation and line-wrap whitespace.
+`extractUri(text)` — Appendix C: strips `<>`, quotes, `URL:` prefixes, trailing punctuation and line-wrap whitespace; a markdown link or an `href`/`src` attribute yields its URL.
+`findUris(text)` — the URIs in ordinary prose (`scheme://`, `www.`, `mailto:` and friends) with their offsets, trailing punctuation trimmed.
 
 **Resolution (§5)**
 `resolveUri(base, ref, { strict, allowRelativeBase })` — every §5.4 example passes; strict by default (`http:g` stays `http:g`).
@@ -223,17 +240,20 @@ iriToUri("http://例え.jp/résumé", { host: "punycode" }) // "http://xn--r8jz4
 `isSameDocumentReference(base, ref, { normalize })`.
 
 **Normalisation and comparison (§6)**
-`normalizeUri(uri, { defaultPorts, schemeBased, userinfo })` — case, percent-encoding, dot segments, default ports, empty path → `/`; `userinfo: "strip-password" | "strip"` for logs.
+`normalizeUri(uri, { defaultPorts, schemeBased, userinfo, trailingSlash, emptyQuery, emptyFragment, host, strict })` — case, percent-encoding, dot segments, default ports, empty path → `/`, IPv6 hosts in RFC 5952 form (`[0:0:0:0:0:0:0:1]` → `[::1]`); `userinfo: "strip-password" | "strip"` for logs; `trailingSlash: "add" | "remove"`, `emptyQuery`/`emptyFragment: "remove"`, `host: "idna" | "unicode"` and `strict` (throw on a bad host or port) are opt-in.
+`getOrigin(uri)` `isSameOrigin(a, b)` — RFC 6454 origins with default-port elision. `stripFragment(uri)`.
+`parseQuery(query)` `stringifyQuery(pairs)` `sortQuery(uri)` — `application/x-www-form-urlencoded` pairs in order, and a URI with its parameters sorted by name then value.
+`joinPaths(...pieces)` — single slashes, no dot segments, the first piece's leading and the last piece's trailing slash kept.
 `normalizePath(path, { trailingSlash })`.
-`equivalentUris(a, b, { level, base, ignoreFragment })` — `"simple"`, `"syntax"` or `"scheme"` (default). Never maps IRIs to URIs (RFC 3987 §5.3.1).
+`equivalentUris(a, b, { level, base, ignoreFragment, defaultPorts })` — `"simple"`, `"syntax"` or `"scheme"` (default). Never maps IRIs to URIs (RFC 3987 §5.3.1).
 
 **IRIs (RFC 3987)**
 `isUcschar` `isIprivate` `isBidiControl` `hasBidiControls`.
-`iriToUri(iri, { bidi, nfc, strict, host })` — percent-encodes without altering characters (§3.1 step 1c); `host: "punycode"` converts the domain; `strict` rejects characters no IRI may contain.
+`iriToUri(iri, { bidi, nfc, strict, host })` — percent-encodes without altering characters (§3.1 step 1c); `bidi: "throw" | "strip"` handles direction controls; `host: "punycode"` converts the domain; `strict` rejects characters no IRI may contain.
 `uriToIri(uri)` — decodes only what §3.2 allows, per component.
-`punycodeEncode` `punycodeDecode` `domainToAscii` `domainToUnicode` — RFC 3492, no dependencies.
+`punycodeEncode` `punycodeDecode` `domainToAscii` `domainToUnicode` — RFC 3492, no dependencies. `domainToAscii` maps and lowercases labels the way UTS #46 does, then rejects what no DNS name may carry: empty labels, labels over 63 octets, names over 253, leading or trailing hyphens, non-LDH characters and `xn--` labels that do not round-trip.
 
-Deliberately not implemented: RFC 6874 IPv6 zone identifiers (reverted by RFC 9844) and the network-based normalisation of §6.2.4.
+Deliberately not implemented: RFC 6874 IPv6 zone identifiers (reverted by RFC 9844), the network-based normalisation of §6.2.4, and the UTS #46 status table, CONTEXTJ/CONTEXTO and the RFC 5893 bidi rule for domains.
 
 </details>
 
@@ -244,7 +264,7 @@ If you are an assistant writing code with this library, these are the facts that
 - Import paths: `cizgile` (slugs), `cizgile/transliterate` (tables, locales), `cizgile/uri` (URLs). ESM only, no default exports, no side effects, no runtime dependencies.
 - `slugify(text, options?)` returns `""` for input with nothing usable — it never throws on ordinary text. It throws `RangeError`/`TypeError` only for invalid options (`separator: "/"`, `preserveCharacters` containing the separator, a non-global `remove` regex, a negative `maxLength`) and, in unicode mode, when `scripts` or `bidi: "throw"` rejects the result.
 - The ASCII output is always a valid path segment; put it in a URL as-is. For `unicode: true` output, call `iriToUri(slug)` before putting it on the wire.
-- Cyrillic and other non-Latin scripts are opt-in: pass `transliterate: [cyrillic]` or a locale object such as `uk` from `cizgile/transliterate`. Without them, Cyrillic text produces `""` in ASCII mode.
+- Cyrillic and other non-Latin scripts are opt-in: pass `transliterate: [cyrillic]` or a locale object such as `uk`, `ja` or `ko` from `cizgile/transliterate`. Without them, Cyrillic text produces `""` in ASCII mode. `transliterate()` keeps scripts it has no table for intact; `allScripts` loads every table.
 - `createSlugger()` is the way to get unique slugs in a document or import job; do not append counters yourself.
 - Use `resolveUri`, `normalizeUri` and `equivalentUris` instead of string concatenation or `new URL()` when you need RFC behaviour (strict scheme handling, no special-scheme rewriting, no host IDNA unless you ask for it).
 - Every exported function has an explicit TypeScript signature; the `.d.mts` files in `dist/` are the authoritative API.
@@ -262,8 +282,9 @@ Measured with `bun run bench` (vitest bench, Node 24, one core of a desktop CPU)
 | 2.5 KB of mixed text                  | **6.4k ops/s** | 4.3k                    | 3.4k              |
 | `isSlug`                              | 3.7M ops/s     | —                       | —                 |
 
-`resolveUri` runs at ~0.8M ops/s (the built-in `URL` parser: ~1M), `removeDotSegments` at 2M,
-`percentEncode` at 0.5M (`encodeURIComponent`: 3.3M — it is native), `normalizeUri` at 0.3M.
+`resolveUri` runs at ~0.8M ops/s (the built-in `URL` parser: ~0.9M), `removeDotSegments` at 2M,
+`percentEncode` at 0.9M on mixed text and 3.6M on a pure-ASCII segment (`encodeURIComponent`: 3.1M and 4.7M — it is native),
+`normalizeUri` at 0.37M, `iriToUri` at 0.66M.
 Options objects are resolved once and cached structurally, so inline `{ locale: "tr" }` literals cost
 nothing after the first call.
 
@@ -283,7 +304,11 @@ nothing after the first call.
 
 ## Specifications
 
-RFC 3986 (with errata 2033, 4547, 4789, 5428), RFC 3987, RFC 3492, RFC 8820, RFC 9844, the WHATWG URL Standard's percent-encode sets, Unicode UTS #39 restriction levels and UAX #29 grapheme boundaries, Google Search Central's URL guidance. The test suite runs every example those documents contain.
+RFC 3986 (with errata 2033, 4547, 4789, 5428), RFC 3987, RFC 3492 (all nineteen §7.1 sample strings), RFC 8820, RFC 9844, the UTS #46 mapping step, the WHATWG URL Standard's percent-encode sets, Unicode UTS #39 restriction levels and UAX #29 grapheme boundaries, Google Search Central's URL guidance. The test suite runs every example those documents contain.
+
+## Changelog
+
+Release notes live on the [GitHub Releases page](https://github.com/productdevbook/cizgile/releases); each release lists the commits since the previous tag. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to work on the library and [SECURITY.md](SECURITY.md) for reporting a vulnerability.
 
 ## Development
 
@@ -292,6 +317,8 @@ bun install
 bun run test      # oxlint, oxfmt, tsc, vitest under node, then vitest under bun
 bun run build     # rolldown → dist/*.mjs + dist/*.d.mts
 bun run coverage
+bun run bench     # vitest bench against @sindresorhus/slugify, simov/slugify and the built-ins
+bun run bench:baseline  # write bench/baseline.json locally; the Bench workflow compares each run with the last successful one on main
 bun run release   # bumpp: bump, tag, push — the tag publishes to npm
 ```
 
@@ -300,7 +327,7 @@ bun run release   # bumpp: bump, tag, push — the tag publishes to npm
 - [simov/slugify](https://github.com/simov/slugify) — the charmap + per-locale override idea and most Cyrillic, Greek, Arabic and symbol values.
 - [sindresorhus/slugify](https://github.com/sindresorhus/slugify) and [sindresorhus/transliterate](https://github.com/sindresorhus/transliterate) — `decamelize`, custom replacements, the counter slugger, and the Armenian, Georgian and Dhivehi tables.
 - [Django](https://github.com/django/django) and [Rails](https://github.com/rails/rails) — the reference behaviours the parity tests are written against.
-- The [WHATWG URL Standard](https://url.spec.whatwg.org/) — percent-encode sets and the parser every result is cross-checked with.
+- The [WHATWG URL Standard](https://url.spec.whatwg.org/) — percent-encode sets and the parser every result is cross-checked with, and the RFC 3986-compatible subset of its [`urltestdata.json`](https://github.com/web-platform-tests/wpt/blob/master/url/resources/urltestdata.json) (web-platform-tests, BSD 3-Clause) vendored as a fixture.
 - [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) by Berners-Lee, Fielding and Masinter, and [RFC 3987](https://datatracker.ietf.org/doc/html/rfc3987) by Duerst and Suignard.
 - [Rolldown](https://rolldown.rs), [Oxc](https://oxc.rs), [Vitest](https://vitest.dev), [Bun](https://bun.sh) and [TypeScript](https://www.typescriptlang.org).
 

package/dist/index.d.mts

@@ -1,55 +1,102 @@
-import { a as TransliterationTable, i as LocaleId, n as LatinLocaleId, r as Locale } from "./shared/types-C1iMvUXh.mjs";
+import { i as LocaleId, n as LatinLocaleId, o as TransliterationTable, r as Locale } from "./shared/types-B3EVWvDh.mjs";
 //#region src/slug/bidi.d.ts
+/** RFC 3987 section 4.2: whether `text` can be a URL component without mixing text directions in a way that renders ambiguously. */
 export declare function isBidiSafeComponent(text: string): boolean;
 //#endregion
 //#region src/slug/decamelize.d.ts
+/** Inserts spaces at camelCase and acronym boundaries: `"getHTTPResponse"` becomes `"get HTTP Response"`. */
 export declare function decamelize(input: string): string;
 //#endregion
 //#region src/slug/scripts.d.ts
+/** UTS #39 mixed-script restriction levels, from a single script (`"single"`) to no restriction (`"any"`). */
 type ScriptRestriction = "single" | "highly-restrictive" | "moderately-restrictive" | "any";
+/** The result of `checkScripts`. */
 interface ScriptCheck {
+  /** Whether the text stays within the requested restriction level. */
   readonly ok: boolean;
+  /** The Unicode scripts found in the text. */
   readonly scripts: readonly string[];
 }
+/** The Unicode script names used by `text`, ignoring Common and Inherited characters. */
 export declare function detectScripts(text: string): string[];
+/** Applies a UTS #39 restriction `level` to the scripts in `text`; `ok` is false when the mix exceeds it. */
 export declare function checkScripts(text: string, level?: ScriptRestriction): ScriptCheck;
 //#endregion
+//#region src/slug/truncate.d.ts
+/** How `maxLength` counts: UTF-16 code units (like `.length`), code points, grapheme clusters, or UTF-8 bytes. */
+type LengthUnit = "units" | "code-points" | "graphemes" | "bytes";
+/** The length of `text` in the given unit. */
+export declare function measure(text: string, unit?: LengthUnit): number;
+/** Cuts `slug` to at most `maxLength` in the given `unit` (UTF-16 code units by default) at a `separator` boundary, never inside a grapheme cluster. */
+export declare function truncateSlug(slug: string, maxLength: number, separator?: string, unit?: LengthUnit): string;
+//#endregion
 //#region src/slug/options.d.ts
+/** Options for `slugify` and `createSlugger`. Every option has a default; an empty object is the everyday call. */
 interface SlugifyOptions {
+  /** Joins words; `"-"` by default. Any URL-safe punctuation (`- _ . ~ ! $ & ' ( ) * + , ; = @`) or `""`. */
   readonly separator?: string;
+  /** Lowercases the result; `true` by default. */
   readonly lowercase?: boolean;
+  /** Keeps letters from every script instead of transliterating to ASCII; `false` by default. */
   readonly unicode?: boolean;
-  readonly locale?: LatinLocaleId | Locale;
-  readonly transliterate?: boolean | readonly TransliterationTable[];
+  /** Language rules: a Latin locale id such as `"tr"`, the id of a locale passed to `registerLocale`, or a `Locale` object from `cizgile/transliterate`. */
+  readonly locale?: LatinLocaleId | (string & {}) | Locale;
+  /** `false` skips the Latin and symbol tables (the locale table and accent folding still apply); `"none"` skips every letter table and keeps only accent folding and the symbol words; an array adds script tables such as `cyrillic`. */
+  readonly transliterate?: boolean | "none" | readonly TransliterationTable[];
+  /** Splits camelCase before slugging: `"fooBar"` becomes `"foo-bar"`; `false` by default. */
   readonly decamelize?: boolean;
+  /** `[from, to]` pairs applied before anything else; spaces in `to` become separators. */
   readonly replacements?: ReadonlyArray<readonly [string, string]>;
+  /** A global regex of characters to delete rather than turn into separators; apostrophes by default, `false` for none. */
   readonly remove?: RegExp | false;
+  /** Extra URL-safe single characters to keep, such as `["."]` for version numbers. */
   readonly preserveCharacters?: readonly string[];
+  /** Keeps a leading `_`: `"_draft"` stays `"_draft"`. */
   readonly preserveLeadingUnderscore?: boolean;
+  /** Keeps a trailing separator, for input still being typed. */
   readonly preserveTrailingSeparator?: boolean;
+  /** Cuts at a word boundary, never inside a grapheme cluster. Counts in `maxLengthUnit`, UTF-16 code units like `.length` by default. */
   readonly maxLength?: number;
+  /** What `maxLength` counts: `"units"` (default), `"code-points"`, `"graphemes"` or UTF-8 `"bytes"`. */
+  readonly maxLengthUnit?: LengthUnit;
+  /** Used when the result would be `""`: a string, or a function of the input; the value is slugified with the same options. */
+  readonly fallback?: string | ((input: string) => string);
+  /** Unicode mode only: the UTS #39 restriction level the result must satisfy; `"any"` by default. */
   readonly scripts?: ScriptRestriction;
+  /** Unicode mode only: what to do when the result mixes text directions (RFC 3987 section 4.2); `"allow"` by default. */
   readonly bidi?: "allow" | "encode" | "throw";
 }
-type IsSlugOptions = Pick<SlugifyOptions, "separator" | "lowercase" | "unicode" | "preserveCharacters" | "preserveLeadingUnderscore" | "preserveTrailingSeparator" | "maxLength" | "scripts" | "bidi">;
+/** The `slugify` options that shape what a valid slug looks like. */
+type IsSlugOptions = Pick<SlugifyOptions, "separator" | "lowercase" | "unicode" | "locale" | "preserveCharacters" | "preserveLeadingUnderscore" | "preserveTrailingSeparator" | "maxLength" | "maxLengthUnit" | "scripts" | "bidi">;
 //#endregion
 //#region src/slug/is-slug.d.ts
+/** Whether `input` is exactly what `slugify` would produce under the same options. */
 export declare function isSlug(input: string, options?: IsSlugOptions): boolean;
 //#endregion
 //#region src/slug/slugger.d.ts
+/** A `slugify` that remembers what it handed out; see `createSlugger`. */
 interface Slugger {
+  /** Slugifies `input`, appending `-2`, `-3`, ... when the slug was already handed out. */
   (input: string, options?: SlugifyOptions): string;
+  /** Forgets every slug handed out or reserved so far. */
   reset(): void;
+  /** Whether `slug` has already been handed out or reserved. */
   has(slug: string): boolean;
+  /** Marks `slug` as taken so it is never handed out again. */
   reserve(slug: string): void;
 }
+/** A slugger that never repeats a slug: the second `"Hello"` becomes `"hello-2"`. `defaults` apply to every call. */
 export declare function createSlugger(defaults?: SlugifyOptions): Slugger;
+/** Alias of `createSlugger`, under the name `@sindresorhus/slugify` uses. */
 export declare const slugifyWithCounter: (defaults?: SlugifyOptions) => Slugger;
 //#endregion
 //#region src/slug/slugify.d.ts
+/**
+ * Turns text into a URL slug: an RFC 3986 `segment-nz-nc` in ASCII mode, NFKC letters, digits and marks in unicode mode.
+ * Returns `""` when nothing usable remains and never throws on ordinary text.
+ * @throws {TypeError} when `input` is not a string or an option is malformed (`preserveCharacters`, a non-global `remove`, an unknown locale id).
+ * @throws {RangeError} for an invalid `separator` or `maxLength`, and in unicode mode when `scripts` or `bidi: "throw"` rejects the result.
+ */
 export declare function slugify(input: string, options?: SlugifyOptions): string;
 //#endregion
-//#region src/slug/truncate.d.ts
-export declare function truncateSlug(slug: string, maxLength: number, separator?: string): string;
-//#endregion
-export type { IsSlugOptions, LatinLocaleId, Locale, LocaleId, ScriptCheck, ScriptRestriction, Slugger, SlugifyOptions, TransliterationTable };
+export type { IsSlugOptions, LatinLocaleId, LengthUnit, Locale, LocaleId, ScriptCheck, ScriptRestriction, Slugger, SlugifyOptions, TransliterationTable };