@bigdreamsweb3/wordbin 1.0.6 → 1.0.8

package/README.md

@@ -1,149 +1,364 @@
-# WordBin – Encode words & short phrases into tiny, reversible binary
-
-![npm](https://img.shields.io/npm/v/@bigdreamsweb3/wordbin) ![license](https://img.shields.io/npm/l/@bigdreamsweb3/wordbin) ![node](https://img.shields.io/node/v/@bigdreamsweb3/wordbin)
-
-**WordBin** is a deterministic, reversible word-to-binary encoder/decoder that compresses short human-readable phrases into **tiny, predictable binary payloads**.
-
-Optimized for **Web3, blockchain, QR codes, IoT, URLs, and other space-sensitive applications**, WordBin ensures short sequences of words can be stored efficiently and recovered reliably.
-
----
-
-## Why WordBin
-
-- Compress short phrases (crypto seeds, tags, keywords) into **2–4 byte IDs per word**.
-- Fully **deterministic & collision-safe** — same dictionary = same encoding.
-- Minimal payload → perfect for **blockchain metadata, NFC/QR codes, and low-bandwidth IoT**.
-- Works in **Node.js & browser**, no runtime dependencies.
-- Bundled **small dictionary (BIP-39)** with optional **large/custom dictionaries**.
-
----
-
-## Quick Install
-
-```bash
-npm install @bigdreamsweb3/wordbin
-```
-
-> The small **v1 (BIP-39)** dictionary is included — ready to encode/decode immediately.
-
----
-
-## Quick Start (Node.js / Browser)
-
-```js
-import { WordBin } from "@bigdreamsweb3/wordbin";
-
-// Use latest dictionary (v1 bundled, v2 if built)
-const wb = await WordBin.create();
-
-const phrase =
-  "pet either learn purse candy leader craft undo spoil forum slot spirit";
-const encoded = await wb.encode(phrase);
-
-console.log("Base64 payload:", encoded.payload);
-// → Base64 payload: Aru6lPEGao2lRWajTRYITVtmNVVD8BWvHGhOtBplWKaJmQ==
-
-console.log("Dictionary Version used (header byte):", encoded.dictVersion);
-// → Dictionary Version used (header byte):: 2
-
-console.log("Encoded bytes:", encoded.encodedBytes);
-// → Encoded bytes: 34
-
-console.log("Original bytes:", encoded.originalBytes);
-// → Original bytes:  70
-
-console.log("Bytes saved:", encoded.bytesSaved);
-// → Bytes saved: 36
-
-const decoded = await wb.decode(encoded.encoded);
-console.log("Decoded:", decoded); // → "pet either learn purse candy leader craft undo spoil forum slot spirit"
-```
-
-### Browser Example
-
-```html
-<script type="module">
-  import { WordBin } from "https://esm.sh/@bigdreamsweb3/wordbin";
-  const wb = await WordBin.create();
-</script>
-```
-
----
-
-## CLI – Build Larger or Custom Dictionaries
-
-```bash
-# Interactive mode
-npx wordbin build
-
-# Direct commands
-npx wordbin build --version 1          # BIP-39 (small, bundled)
-npx wordbin build --version 2          # dwyl/english-words (~466k)
-npx wordbin build --all                # Both v1 + v2
-npx wordbin build --custom https://example.com/mywords.txt
-npx wordbin build --custom ./my-local-words.txt
-```
-
-> All generated files go to `./data/` in your current directory.
-
----
-
-## Dictionary Versions
-
-| Version | Filename              | Words    | Source             | ID bytes | Best for                                |
-| ------- | --------------------- | -------- | ------------------ | -------- | --------------------------------------- |
-| v1      | wordbin-v1-bip39.json | 2,048    | BIP-39 English     | ~2       | Crypto recovery seeds, high reliability |
-| v2      | wordbin-v2-dwyl.json  | ~479,000 | dwyl/english-words | 2–4      | General English, tags, keywords         |
-
----
-
-## How It Works
-
-1. Each word is hashed → first **2–4 bytes** = its fixed ID.
-2. If the ID is in the dictionary → use the short ID.
-   Otherwise → store the word as a compact literal block.
-3. Payload begins with one byte: **dictionary version**.
-4. Decoding uses the same dictionary to reverse IDs → original words.
-5. Backtracking handles any ID length ambiguity → guaranteed correct output.
-
----
-
-## Real-World Use Cases
-
-| Use Case                              | Typical Savings | Dictionary |
-| ------------------------------------- | --------------- | ---------- |
-| Crypto recovery phrases (12–24 words) | 50–65%          | v1         |
-| Short tags / keywords                 | 40–70%          | v2         |
-| Tiny QR codes / NFC labels            | 50–80%          | v1 or v2   |
-| Short links / URL-friendly tags       | 45–65%          | v2         |
-| On-chain metadata (Ethereum, Solana)  | 40–70%          | v2         |
-| LoRa / low-bandwidth IoT labels       | 50–75%          | v2         |
-| Offline phrase storage / search       | 35–60%          | v2         |
-
-> Not suitable for long texts, arbitrary binary files, or when dictionaries cannot be shared reliably.
-
----
-
-## Loading Specific Dictionary Versions
-
-```js
-import { loadDictionaryByVersion } from "@bigdreamsweb3/wordbin";
-
-const dictV1 = await loadDictionaryByVersion(1); // always available
-const wbV1 = new WordBin(dictV1);
-
-const dictV2 = await loadDictionaryByVersion(2); // throws if not built
-```
-
----
-
-## License
-
-MIT
-
----
-
-## Contributing
-
-Want to help improve WordBin?
-Read our [CONTRIBUTING.md](./CONTRIBUTING.md) guide.
+# WordBin — Compact, Reversible Word-Phrase Encoder
+
+[![npm version](https://img.shields.io/npm/v/@bigdreamsweb3/wordbin?style=flat-square)](https://www.npmjs.com/package/@bigdreamsweb3/wordbin)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/node/v/@bigdreamsweb3/wordbin?style=flat-square)](https://nodejs.org)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen?style=flat-square)](https://github.com/bigdreamsweb3/wordbin/actions)
+
+**WordBin** encodes short human-readable phrases — crypto seeds, metadata tags, labels, keywords — into **compact, deterministic binary payloads** that can be perfectly reversed back to the original words.
+
+Designed for **Web3 metadata**, **QR codes**, **blockchain events**, **IoT**, **NFC tags**, **short URLs**, and any **low-bandwidth or storage-constrained** environment where every byte matters.
+
+---
+
+### Real Output
+
+```
+Input  : "stock ridge avoid school honey trap wait wheel worry face differ wedding"
+Words  : 12
+Output : 34 bytes  (original: 72 bytes)
+Saved  : 38 bytes  —  47% of original size
+
+Hex    : 0108c424409e363270f7d64deba55e2e11ba716eba59926de2f50282599fc5afd1a8
+Base58 : 2MepGpLHGPPmnrdzjmpqet2XFQ2YGMSpQoDXDex7toUBdZ
+Base64 : AQjEJECeNjJw99ZN66VeLhG6cW66WZJt4vUCglmfxa/RqA==
+Bin21  : ☺◄Ä$@ž6rp÷ÖMë¥^.►ºqnºY™mâõ☻™Å¯Ñ¨
+
+Decoded: "stock ridge avoid school honey trap wait wheel worry face differ wedding" ✓
+```
+
+---
+
+## Why WordBin?
+
+- **40–70% size reduction** on typical short phrases
+- **Deterministic** — same input + same dictionary = same output, every time
+- **Lossless** — decode is always a perfect round-trip
+- **Universal decoder** — accepts hex, Base58, Base64, Bin21, or raw bytes; format is auto-detected
+- **Resilient** — non-WordBin payloads are never rejected; partial word extraction is attempted before falling back gracefully
+- **No runtime dependencies** — works in Node.js and the browser
+- **Flexible dictionaries** — BIP-39 (v1, bundled), large English (v2), or custom wordlists
+
+---
+
+## Install
+
+```bash
+npm install @bigdreamsweb3/wordbin
+```
+
+> Ships with **v1 (BIP-39, 2048 words)** pre-bundled — works out of the box.
+
+---
+
+## Quick Start
+
+```ts
+import { WordBin } from "@bigdreamsweb3/wordbin";
+
+const wb = await WordBin.create();
+
+const phrase =
+  "stock ridge avoid school honey trap wait wheel worry face differ wedding";
+
+// ── Encode ────────────────────────────────────────────────────────────────────
+const encoded = await wb.encode(phrase);
+
+console.log(encoded.hexPayload); // standard hex string
+console.log(encoded.base58Payload); // Base58 string
+console.log(encoded.base64Payload); // Base64 string
+console.log(encoded.payload); // Bin21 (1 char per byte, most compact printable form)
+console.log(encoded.encodedBytes); // 34
+console.log(encoded.originalBytes); // 72
+console.log(encoded.ratioPercent); // 47.22
+
+// ── Decode — pass any format, it's auto-detected ──────────────────────────────
+const r1 = await wb.decode(encoded.hexPayload); // DetectedFormat: "hex"
+const r2 = await wb.decode(encoded.base58Payload); // DetectedFormat: "base58"
+const r3 = await wb.decode(encoded.base64Payload); // DetectedFormat: "base64"
+const r4 = await wb.decode(encoded.payload); // DetectedFormat: "bin21"
+const r5 = await wb.decode(encoded.encoded); // DetectedFormat: "bytes" (Uint8Array)
+
+console.log(r1.text); // "stock ridge avoid school honey trap..."
+console.log(r1.isWordBin); // true
+```
+
+### Browser (ESM)
+
+```html
+<script type="module">
+  import { WordBin } from "https://esm.sh/@bigdreamsweb3/wordbin";
+  const wb = await WordBin.create();
+  const { hexPayload } = await wb.encode("abandon ability able");
+  const { text } = await wb.decode(hexPayload);
+  console.log(text); // → "abandon ability able"
+</script>
+```
+
+---
+
+## Payload Formats
+
+WordBin produces four interchangeable representations of the same encoded bytes. Pass any of them to `decode()` — the format is detected automatically.
+
+| Format     | Field           | Description                            | Size                             |
+| ---------- | --------------- | -------------------------------------- | -------------------------------- |
+| **Hex**    | `hexPayload`    | Lowercase hex, 2 chars per byte        | 2× raw                           |
+| **Base58** | `base58Payload` | URL-safe, no ambiguous chars (0/O/I/l) | ~1.4× raw                        |
+| **Base64** | `base64Payload` | Standard Base64 with `=` padding       | ~1.33× raw                       |
+| **Bin21**  | `payload`       | Latin-1 string, 1 char per byte        | 1× raw — smallest printable form |
+| **Bytes**  | `encoded`       | Raw `Uint8Array`                       | 1× raw                           |
+
+> **Bin21** is WordBin's signature format: each encoded byte maps to exactly one character. No expansion. A 34-byte payload is a 34-character string.
+
+---
+
+## Decode API
+
+`wb.decode(payload)` always returns a `DecodeResult` — it never throws.
+
+```ts
+interface DecodeResult {
+  text: string; // decoded words, or best-effort extraction
+  isWordBin: boolean; // true = valid WordBin payload, perfectly decoded
+  detectedFormat: PayloadFormat; // "hex" | "base58" | "base64" | "bin21" | "bytes"
+  notice?: string; // present when payload is not a valid WordBin stream
+  rawSegments?: string[]; // unmatched bytes shown as [0xXX], non-WordBin only
+}
+```
+
+### Decode behaviour
+
+```
+Payload received
+      │
+      ▼
+Format detection ──── hex / base58 / base64 / bin21 / bytes
+      │
+      ▼
+Strict WordBin parse (all installed dictionary versions)
+      │                      │
+   Success               Failure
+      │                      │
+  isWordBin: true       Partial scan ── extract words where bytes match
+  text: original            │           preserve unmatched bytes as [0xXX]
+                        isWordBin: false
+                        notice: explains what happened
+```
+
+**Any payload is accepted.** If bytes don't match any dictionary, a partial word extraction is attempted across all installed dictionaries. Remaining bytes are preserved as `[0xXX]` markers so nothing is silently discarded.
+
+```ts
+// Non-WordBin payload — still handled gracefully
+const result = await wb.decode("48656c6c6f20576f726c64"); // "Hello World" as hex
+
+console.log(result.isWordBin); // false
+console.log(result.notice); // "This does not appear to be a valid WordBin payload..."
+console.log(result.rawSegments); // ["[0x48]", "[0x65]", ...] — unmatched bytes
+```
+
+---
+
+## How Encoding Works
+
+1. **Version header** — first byte identifies the dictionary version (`0x01` for v1)
+2. **Dictionary lookup** — each word in the phrase is replaced by its compact binary ID (1–4 bytes)
+3. **Literal fallback** — words not in the dictionary are stored as `varint length + UTF-8 bytes`
+4. **Payload representations** — the raw bytes are encoded into hex, Base58, Base64, and Bin21
+
+Payloads are **self-describing** (the version byte is embedded) and **fully lossless**.
+
+---
+
+## Compression by Use Case
+
+| Use case                   | Words | Original    | Encoded     | Saved |
+| -------------------------- | ----- | ----------- | ----------- | ----- |
+| 12-word BIP-39 seed phrase | 12    | ~72 bytes   | ~34 bytes   | ~53%  |
+| Crypto metadata / labels   | 5–8   | 30–50 bytes | 12–24 bytes | ~55%  |
+| Short tag / keyword list   | 3–6   | 20–40 bytes | 8–18 bytes  | ~60%  |
+| English sentence           | 8–15  | 50–90 bytes | 25–45 bytes | ~50%  |
+
+---
+
+## CLI — Build Dictionaries
+
+```bash
+# Interactive
+npx wordbin build
+
+# Specific version
+npx wordbin build --version 1          # BIP-39 (2048 words, already bundled)
+npx wordbin build --version 2          # dwyl/english-words (~466k words)
+npx wordbin build --all                # Build v1 and v2
+
+# Custom wordlist
+npx wordbin build --custom ./mywords.txt
+npx wordbin build --custom https://example.com/words.txt
+```
+
+Output goes to `./data/`. Load with `loadDictionaryByVersion()` or pass directly to `new WordBin(dict)`.
+
+---
+
+## Dictionary Versions
+
+| Version    | Words    | Source             | Best for                                | Bundled        |
+| ---------- | -------- | ------------------ | --------------------------------------- | -------------- |
+| **v1**     | 2,048    | BIP-39 English     | Crypto seeds, maximum reliability       | ✅ Yes         |
+| **v2**     | ~466,550 | dwyl/english-words | General English, tags, large vocabulary | Build required |
+| **Custom** | Any      | Your wordlist      | Domain-specific vocabulary              | Build required |
+
+---
+
+## Advanced Usage
+
+### Load a specific dictionary version
+
+```ts
+import { loadDictionaryByVersion, WordBin } from "@bigdreamsweb3/wordbin";
+
+const dict = await loadDictionaryByVersion(1);
+const wb = new WordBin(dict);
+```
+
+### Encode with a specific dictionary version
+
+```ts
+const encoded = await wb.encode("abandon ability able", { dictVersion: 1 });
+```
+
+### Encode from an existing EncodeResult or raw bytes
+
+```ts
+// Re-encode a previous result (e.g. to switch dictionary version)
+const reEncoded = await wb.encode(encoded);
+
+// Encode raw bytes
+const fromBytes = await wb.encode(new Uint8Array([1, 2, 3]));
+```
+
+### Build a WordBin instance from a custom wordlist
+
+```ts
+const wb = await WordBin.createFromWords(["apple", "banana", "cherry", ...]);
+```
+
+---
+
+---
+
+## For Contributors — Clone & Run Locally
+
+> This section is for people developing WordBin itself.  
+> If you're just using the package, `npm install @bigdreamsweb3/wordbin` is all you need.
+
+### Prerequisites
+
+- Node.js ≥ 18
+- npm ≥ 9
+
+### Clone and set up
+
+```bash
+git clone https://github.com/bigdreamsweb3/wordbin.git
+cd wordbin
+npm install
+```
+
+### Project layout
+
+```
+wordbin/
+├── src/
+│   ├── core/           # WordBin class — encode, decode, format detection
+│   ├── dict/           # Dictionary loader, builder, and bundled data
+│   ├── utils/          # Buffer helpers (toHex, toBase64, varint, utf8)
+│   └── constants.ts    # LITERAL token and other shared constants
+├── test/
+│   └── test.spec.ts    # Vitest suite — encode, decode, round-trip, non-WordBin
+├── data/               # Built dictionary files (generated, not committed)
+└── dist/               # Compiled output (generated on build)
+```
+
+### Build
+
+```bash
+npm run build        # compile TypeScript → dist/
+```
+
+### Run the tests
+
+```bash
+npm test             # run all test suites once
+npm run test:watch   # watch mode — re-runs on file save
+```
+
+Each suite can be run independently — either flip a flag in `test/test.spec.ts`:
+
+```ts
+const RUN = {
+  ENCODE_ONLY: true, // set false to skip
+  DECODE_ONLY: true,
+  ENCODE_THEN_DECODE: true,
+  NON_WORDBIN_DECODE: true,
+};
+```
+
+Or target a suite by name from the CLI:
+
+```bash
+npx vitest -t "Encode only"
+npx vitest -t "Decode only"
+npx vitest -t "Encode then decode"
+npx vitest -t "Non-WordBin decode"
+```
+
+### Build dictionaries locally
+
+The v1 BIP-39 dictionary is bundled with the package. To build additional versions:
+
+```bash
+npx wordbin build --version 2    # large English (~466k words) → ./data/
+npx wordbin build --all          # v1 + v2
+```
+
+The `./data/` directory is gitignored. Built dictionaries are loaded automatically by `loadLatestDictionary()` at runtime.
+
+### Making changes
+
+The most common contribution points:
+
+| What you want to change                    | Where to look                                            |
+| ------------------------------------------ | -------------------------------------------------------- |
+| Encode / decode logic                      | `src/core/wordbin.ts`                                    |
+| Format detection (hex/base58/base64/bin21) | `detectAndConvert()` in `wordbin.ts`                     |
+| Dictionary loading / versioning            | `src/dict/dictionary-loader.ts`                          |
+| Dictionary building from a wordlist        | `src/dict/builder.ts`                                    |
+| Buffer utilities (varint, hex, utf8)       | `src/utils/buffer.ts`                                    |
+| Add a new payload format                   | `PayloadFormat` type + `detectAndConvert()` + `encode()` |
+
+### Submitting a pull request
+
+1. Fork the repo and create a branch: `git checkout -b my-feature`
+2. Make your changes and ensure all tests pass: `npm test`
+3. Add or update tests for any new behaviour in `test/test.spec.ts`
+4. Open a pull request with a clear description of what changed and why
+
+For larger changes — new dictionary versions, new payload formats, architectural changes — please open an issue first to discuss the approach.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) to add dictionary versions, improve compression, or fix bugs.
+
+---
+
+Enjoy the tiny payloads. We up 🚀

package/dist/{dictionary-D3gr2Ala.js → builder-vFphFQMU.js}

@@ -35,16 +35,6 @@ function toBase64(bytes) {
   }
   return Buffer.from(bytes).toString("base64");
 }
-function fromBase64(base64) {
-  const at = globalThis.atob;
-  if (typeof at === "function") {
-    const binary = at(base64);
-    const out = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
-    return out;
-  }
-  return new Uint8Array(Buffer.from(base64, "base64"));
-}
 function utf8Encode(str) {
   if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(str);
   return new Uint8Array(Buffer.from(str, "utf8"));
@@ -85,10 +75,19 @@ async function buildDictionary(words, options = {}) {
   const normalizedWords = words.map((w) => w.trim().toLowerCase()).filter((w) => w);
   await Promise.all(
     normalizedWords.map(async (word) => {
-      const id = await generateWordId(word);
-      const key = toHex(id);
-      if (!map[key]) map[key] = [];
-      map[key].push(word);
+      let attempt = 0;
+      let key;
+      while (true) {
+        const id = await generateWordId(
+          attempt === 0 ? word : `${word}:${attempt}`
+        );
+        key = toHex(id);
+        if (!map[key]) {
+          map[key] = [word];
+          break;
+        }
+        attempt++;
+      }
     })
   );
   Object.values(map).forEach((collisions) => {
@@ -101,14 +100,12 @@ async function buildDictionary(words, options = {}) {
   };
 }
 export {
-  toHex as a,
+  utf8Decode as a,
   buildDictionary as b,
-  utf8Decode as c,
+  toHex as c,
   decodeVarint as d,
   encodeVarint as e,
-  fromBase64 as f,
-  generateWordId as g,
   toBase64 as t,
   utf8Encode as u
 };
-//# sourceMappingURL=dictionary-D3gr2Ala.js.map
+//# sourceMappingURL=builder-vFphFQMU.js.map

package/dist/builder-vFphFQMU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder-vFphFQMU.js","sources":["../src/core/tiers.ts","../src/core/id.ts","../src/utils/buffer.ts","../src/dict/builder.ts"],"sourcesContent":["export function getIdByteLength(wordLength: number): number {\r\n  if (wordLength <= 4) return 2;\r\n  if (wordLength <= 9) return 3;\r\n  return 4;\r\n}\r\n\r\nexport function getWrapByteLength(wordLength: number): number {\r\n  if (wordLength <= 4) return 2;\r\n  if (wordLength <= 9) return 3;\r\n  return 4;\r\n}\r\n\r\nexport async function getTextEncoder(): Promise<TextEncoder> {\r\n  if (typeof TextEncoder !== \"undefined\") return new TextEncoder();\r\n  const { TextEncoder: NodeTextEncoder } = await import(\"node:util\");\r\n  // @ts-ignore Node typings\r\n  return new NodeTextEncoder();\r\n}\r\n\r\nexport async function wrapBase64(data: string): Promise<Uint8Array> {\r\n  const normalized = data.trim().toLowerCase();\r\n  if (!normalized) throw new Error(\"Cannot generate ID for empty string\");\r\n\r\n  const encoder = await getTextEncoder();\r\n  const result = encoder.encode(normalized);\r\n\r\n  // Browser + Node compatible SHA-256\r\n  let hash: ArrayBuffer;\r\n  const anyCrypto: any = (globalThis as any).crypto;\r\n  if (anyCrypto && anyCrypto.subtle) {\r\n    hash = await anyCrypto.subtle.digest(\"SHA-256\", result);\r\n  } else {\r\n    const { createHash } = await import(\"node:crypto\");\r\n    hash = createHash(\"sha256\").update(Buffer.from(result)).digest().buffer;\r\n  }\r\n\r\n  const hashBytes = new Uint8Array(hash);\r\n  const size = getWrapByteLength(normalized.length);\r\n  return hashBytes.slice(0, size);\r\n}\r\n","import { getIdByteLength } from './tiers.js'\r\n\r\n/**\r\n * Deterministic word \t ID generator\r\n * Same output on browser and node (when using compatible input)\r\n */\r\nexport async function generateWordId(word: string): Promise<Uint8Array> {\r\n  const normalized = word.trim().toLowerCase()\r\n  if (!normalized) throw new Error('Cannot generate ID for empty string')\r\n\r\n  const encoder = await getTextEncoder()\r\n  const data = encoder.encode(normalized)\r\n\r\n  // Browser + Node compatible SHA-256\r\n  let hash: ArrayBuffer\r\n  const anyCrypto: any = (globalThis as any).crypto\r\n  if (anyCrypto && anyCrypto.subtle) {\r\n    hash = await anyCrypto.subtle.digest('SHA-256', data)\r\n  } else {\r\n    const { createHash } = await import('node:crypto')\r\n    hash = createHash('sha256').update(Buffer.from(data)).digest().buffer\r\n  }\r\n\r\n  const hashBytes = new Uint8Array(hash)\r\n  const size = getIdByteLength(normalized.length)\r\n  return hashBytes.slice(0, size)\r\n}\r\n\r\nasync function getTextEncoder(): Promise<TextEncoder> {\r\n  if (typeof TextEncoder !== 'undefined') return new TextEncoder()\r\n  const { TextEncoder: NodeTextEncoder } = await import('node:util')\r\n  // @ts-ignore Node typings\r\n  return new NodeTextEncoder()\r\n}\r\n","export function toHex(bytes: Uint8Array): string {\r\n  return Array.from(bytes)\r\n    .map((b) => b.toString(16).padStart(2, '0'))\r\n    .join('')\r\n}\r\n\r\nexport function fromHex(hex: string): Uint8Array {\r\n  if (hex.length % 2 !== 0) throw new Error('Invalid hex string length')\r\n  const bytes = new Uint8Array(hex.length / 2)\r\n  for (let i = 0; i < hex.length; i += 2) {\r\n    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16)\r\n  }\r\n  return bytes\r\n}\r\n\r\nexport function toBase64(bytes: Uint8Array): string {\r\n  const b64 = (globalThis as any).btoa\r\n  if (typeof b64 === 'function') {\r\n    return b64(String.fromCharCode(...bytes))\r\n  }\r\n  // Node fallback\r\n  return Buffer.from(bytes).toString('base64')\r\n}\r\n\r\nexport function fromBase64(base64: string): Uint8Array {\r\n  const at = (globalThis as any).atob\r\n  if (typeof at === 'function') {\r\n    const binary = at(base64)\r\n    const out = new Uint8Array(binary.length)\r\n    for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i)\r\n    return out\r\n  }\r\n  // Node fallback\r\n  return new Uint8Array(Buffer.from(base64, 'base64'))\r\n}\r\n\r\n// UTF-8 helpers\r\nexport function utf8Encode(str: string): Uint8Array {\r\n  if (typeof TextEncoder !== 'undefined') return new TextEncoder().encode(str)\r\n  // Node fallback\r\n  return new Uint8Array(Buffer.from(str, 'utf8'))\r\n}\r\n\r\nexport function utf8Decode(bytes: Uint8Array): string {\r\n  if (typeof TextDecoder !== 'undefined') return new TextDecoder().decode(bytes)\r\n  // Node fallback\r\n  return Buffer.from(bytes).toString('utf8')\r\n}\r\n\r\n// Varint (LEB128 7-bit groups) helpers\r\nexport function encodeVarint(n: number): Uint8Array {\r\n  if (n < 0) throw new Error('Varint cannot encode negative numbers')\r\n  const out: number[] = []\r\n  do {\r\n    let byte = n & 0x7f\r\n    n >>>= 7\r\n    if (n !== 0) byte |= 0x80\r\n    out.push(byte)\r\n  } while (n !== 0)\r\n  return new Uint8Array(out)\r\n}\r\n\r\nexport function decodeVarint(bytes: Uint8Array, offset: number): { value: number; bytesRead: number } {\r\n  let result = 0\r\n  let shift = 0\r\n  let pos = offset\r\n  while (pos < bytes.length) {\r\n    const byte = bytes[pos++]\r\n    result |= (byte & 0x7f) << shift\r\n    if ((byte & 0x80) === 0) {\r\n      return { value: result, bytesRead: pos - offset }\r\n    }\r\n    shift += 7\r\n    if (shift > 35) throw new Error('Varint too large')\r\n  }\r\n  throw new Error('Truncated varint')\r\n}\r\n","// File: src\\dict\\builder.ts\r\n\r\nimport type { WordBinDictionary } from \"../types\";\r\nimport { generateWordId } from \"../core/id.js\";\r\nimport { toHex } from \"../utils/buffer.js\";\r\n\r\nexport interface BuildDictionaryOptions {\r\n  /**\r\n   * Dictionary version number (used in header and for format compatibility)\r\n   * @default 1\r\n   */\r\n  version?: number;\r\n\r\n  /**\r\n   * Human-readable description of this dictionary\r\n   * @default \"WordBin dictionary v${version}\"\r\n   */\r\n  description?: string;\r\n\r\n  /**\r\n   * Optional: custom prefix or identifier for this dictionary build\r\n   * (can be used in logs, filenames, etc.)\r\n   */\r\n  name?: string;\r\n}\r\n\r\nexport async function buildDictionary(\r\n  words: string[],\r\n  options: BuildDictionaryOptions = {},\r\n): Promise<WordBinDictionary> {\r\n  const { version = 1, description = `WordBin dictionary v${version}` } =\r\n    options;\r\n\r\n  const map: Record<string, string[]> = {};\r\n\r\n  const normalizedWords = words\r\n    .map((w) => w.trim().toLowerCase())\r\n    .filter((w) => w);\r\n\r\n  await Promise.all(\r\n    normalizedWords.map(async (word) => {\r\n      let attempt = 0;\r\n      let key: string;\r\n\r\n      while (true) {\r\n        const id = await generateWordId(\r\n          attempt === 0 ? word : `${word}:${attempt}`,\r\n        );\r\n\r\n        key = toHex(id);\r\n\r\n        // If no collision, break\r\n        if (!map[key]) {\r\n          map[key] = [word];\r\n          break;\r\n        }\r\n\r\n        // Collision detected → try again\r\n        attempt++;\r\n      }\r\n    }),\r\n  );\r\n\r\n  Object.values(map).forEach((collisions) => {\r\n    collisions.sort((a, b) => a.localeCompare(b));\r\n  });\r\n\r\n  return {\r\n    version,\r\n    description,\r\n    words: map,\r\n  };\r\n}\r\n"],"names":[],"mappings":"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"}

package/dist/cli.mjs

@@ -4,7 +4,7 @@ import { resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { stdout, stdin } from "node:process";
 import { wordlists } from "bip39";
-import { b as buildDictionary } from "./dictionary-D3gr2Ala.js";
+import { b as buildDictionary } from "./builder-vFphFQMU.js";
 const rl = createInterface({ input: stdin, output: stdout });
 const help = `
 WordBin CLI – Dictionary Builder

package/dist/core/binary-payload.d.ts

@@ -0,0 +1,6 @@
+export declare function toHexString(bytes: Uint8Array): string;
+export declare function fromHexString(hex: string): Uint8Array | null;
+export declare function generateRandomData(length?: number): Uint8Array;
+export declare function copyToClipboard(text: string): Promise<void>;
+export declare function modernToHex(bytes: Uint8Array): string;
+export declare function modernFromHex(hex: string): Uint8Array | null;

package/dist/core/comp/latin1-compressor.d.ts

@@ -0,0 +1,9 @@
+export declare class SimpleLatinShortener {
+    private manualMap;
+    private reverseMap;
+    constructor();
+    shorten(str: string): string;
+    restore(str: string): string;
+    utf8Bytes(str: string): number;
+    test(input: string): void;
+}

package/dist/core/comp/onebyte-encoder.d.ts

@@ -0,0 +1,2 @@
+export declare function fullEncode(input: string): Uint8Array;
+export declare function fullDecode(data: Uint8Array): string;