@bigdreamsweb3/wordbin 1.0.8 → 1.1.7

package/CONTRIBUTING.md

@@ -1,12 +1,15 @@
+Here's the **CONTRIBUTING.md** file ready for you to download and use in your project.
+
+You can copy the content below and save it as `CONTRIBUTING.md` in the root of your repository.
+
+```markdown
 # Contributing to WordBin
 
 Thank you for your interest in contributing to WordBin!  
-We welcome all kinds of help — bug reports, documentation improvements, new features, dictionary variants, tests, or small fixes.
+We welcome all kinds of help — bug reports, documentation improvements, new features, dictionary variants, tests, or even small fixes.
 
 This guide explains how to contribute effectively and what would be most valuable to the project right now.
 
----
-
 ## Table of Contents
 
 - [Code of Conduct](#code-of-conduct)
@@ -16,22 +19,15 @@ This guide explains how to contribute effectively and what would be most valuabl
   - [Submitting Pull Requests](#submitting-pull-requests)
   - [Good First Issues](#good-first-issues)
 - [Development Setup](#development-setup)
-- [Project Layout](#project-layout)
-- [Running Tests](#running-tests)
-- [Where Things Live](#where-things-live)
 - [Current Priorities (2026)](#current-priorities-2026)
 - [Code Style & Conventions](#code-style--conventions)
 - [License](#license)
 
----
-
 ## Code of Conduct
 
 This project follows the [Contributor Covenant Code of Conduct v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).  
 Be respectful, inclusive, and constructive in all interactions.
 
----
-
 ## How to Contribute
 
 ### Reporting Bugs
@@ -40,72 +36,66 @@ If you find a bug:
 
 1. Check if it's already reported in [existing issues](https://github.com/bigdreamsweb3/wordbin/issues).
 2. If not, open a new issue and include:
-   - A clear, descriptive title
+   - Clear, descriptive title
    - Steps to reproduce
-   - Expected vs actual behaviour
-   - Node.js version (`node -v`)
-   - Dictionary version used (v1 / v2 / custom)
-   - The payload format involved (hex / base58 / base64 / bin21 / bytes)
-   - A minimal code snippet or failing test case
+   - Expected vs actual behavior
+   - Node.js / browser version
+   - Dictionary version used (v1/v2/custom)
+   - Minimal code snippet or test case
+
+Use the **Bug report** template when available.
 
 ### Suggesting Features or Improvements
 
-Open an issue with:
+Have an idea for a new feature, better performance, UX improvement, or new dictionary type?
 
-- The problem or opportunity you're addressing
-- Your proposed solution (as detailed as you like)
-- Any alternatives you considered
-- Rough estimate of impact
+Open an issue with:
+- Problem or opportunity you're addressing
+- Proposed solution (as detailed as you want)
+- Any alternatives you've considered
+- Rough estimate of impact/benefit
 
-For larger architectural changes — new payload formats, new dictionary structures, changes to the encode/decode pipeline — please open an issue to discuss before writing code.
+Use the **Feature request** template if it exists.
 
 ### Submitting Pull Requests
 
+Want to submit code? Awesome!
+
 1. **Fork** the repository and **clone** your fork
-2. Create a focused branch:
-   ```bash
-   git checkout -b fix/decode-bin21-format
-   # or
-   git checkout -b feat/add-top-20k-dictionary
-   ```
+2. Create a new branch:  
+   `git checkout -b fix/lowercase-normalization`  
+   or `feat/add-top-20k-dictionary`
 3. Make your changes
-4. Add or update tests in `test/test.spec.ts` for any new behaviour
-5. Run the full test suite and confirm everything passes:
-   ```bash
-   npm test
-   ```
-6. Commit with clear, semantic messages:
-   ```
-   fix: correct bin21 format detection in detectAndConvert
-   feat: add partialScan fallback for non-WordBin payloads
-   docs: update decode API in README
-   test: add round-trip cases for base58 and bin21 formats
-   ```
+4. Add or update tests if applicable
+5. Run the test suite:  
+   `npm test` or `npm run vitest`
+6. Commit with clear messages (semantic style preferred):  
+   `fix: normalize words to lowercase in buildDictionary`  
+   `feat: add CLI flag for lowercase normalization`  
+   `docs: improve contributing guide`  
+   `test: add cases for empty input and literals`
 7. Push your branch and open a pull request against `main`
 
-Small, focused PRs are merged quickly. For larger changes, open a draft PR early — it's easier to align on approach before a lot of code is written.
+Small, focused PRs are usually merged quickly.  
+Larger changes might be reviewed in stages — feel free to open a draft PR early to discuss.
 
 ### Good First Issues
 
-Looking for an easy entry point? These are beginner-friendly:
+Looking for an easy entry point? These tasks are beginner-friendly:
 
-- Fix documentation or README examples
-- Add case normalisation (lowercase) to dictionary building
+- Improve/fix documentation or README examples
+- Add case normalization (lowercase) to dictionary building
 - Create a smaller curated dictionary (e.g. top 10k–50k English words)
 - Add more helpful messages or progress indicators to the CLI
-- Write tests for edge cases (empty strings, very long phrases, single-word inputs)
-- Build a simple browser demo (CodeSandbox, StackBlitz, or a static HTML page)
-
-Look for issues labelled **[good first issue]** on GitHub.
+- Write tests for edge cases (empty strings, very long phrases, invalid base64)
+- Create a simple browser demo (CodeSandbox, StackBlitz, or static HTML)
 
----
+Look for issues labeled **[good first issue]** on GitHub.
 
 ## Development Setup
 
-**Prerequisites:** Node.js ≥ 18, npm ≥ 9
-
 ```bash
-# 1. Fork and clone
+# 1. Fork & clone the repo
 git clone https://github.com/bigdreamsweb3/wordbin.git
 cd wordbin
 
@@ -115,130 +105,51 @@ npm install
 # 3. Build the library
 npm run build
 
-# 4. Run the tests
+# 4. Run tests
 npm test
-```
-
----
+# or watch mode:
+npm run vitest
 
-## Project Layout
-
-```
-wordbin/
-├── src/
-│   ├── core/
-│   │   └── wordbin.ts          # WordBin class — encode(), decode(), format detection
-│   ├── dict/
-│   │   ├── dictionary-loader.ts # loadLatestDictionary, loadDictionaryByVersion
-│   │   ├── builder.ts           # buildDictionary() — constructs dict from a wordlist
-│   │   └── data/                # Bundled v1 (BIP-39) dictionary JSON
-│   ├── utils/
-│   │   └── buffer.ts            # toHex, toBase64, encodeVarint, decodeVarint, utf8*
-│   └── constants.ts             # LITERAL token value and other shared constants
-├── test/
-│   └── test.spec.ts             # Vitest suites — encode, decode, round-trip, non-WordBin
-├── data/                        # Built dictionary files — generated, gitignored
-└── dist/                        # Compiled output — generated on build, not committed
+# 5. Build dictionaries (optional)
+npx wordbin build --version 2
+# or interactive mode:
+npx wordbin build
 ```
 
----
-
-## Running Tests
-
-The test suite is organised into four independently-controllable suites.
-
-```bash
-npm test                          # run everything once
-npm run test:watch                # watch mode — re-runs on save
-```
-
-### Run a single suite via CLI
-
-```bash
-npx vitest -t "Encode only"
-npx vitest -t "Decode only"
-npx vitest -t "Encode then decode"
-npx vitest -t "Non-WordBin decode"
-```
-
-### Toggle suites without touching the CLI
-
-At the top of `test/test.spec.ts`:
-
-```ts
-const RUN = {
-  ENCODE_ONLY: true, // encode text → verify all payload representations
-  DECODE_ONLY: true, // decode a pre-built payload → verify result
-  ENCODE_THEN_DECODE: true, // full round-trip across all 5 formats
-  NON_WORDBIN_DECODE: true, // arbitrary payloads → graceful fallback behaviour
-};
-```
-
-Set any flag to `false` to skip that suite entirely. Skipped suites are reported as skipped — they are never silently removed.
-
-### What each suite covers
-
-| Suite                  | What it tests                                                                                |
-| ---------------------- | -------------------------------------------------------------------------------------------- |
-| **Encode only**        | All payload formats (hex, base58, base64, bin21), compression ratio, format validity         |
-| **Decode only**        | Known hex payload, known base64 payload, non-WordBin fallback                                |
-| **Encode then decode** | Full round-trip for hex, base58, base64, bin21, and raw `Uint8Array`                         |
-| **Non-WordBin decode** | 4 foreign payloads — verifies `isWordBin: false`, `notice` is set, `text` is always a string |
-
----
-
-## Where Things Live
-
-| What you want to change                                  | File                                 |
-| -------------------------------------------------------- | ------------------------------------ |
-| Encode / decode logic                                    | `src/core/wordbin.ts`                |
-| Payload format detection (hex / base58 / base64 / bin21) | `detectAndConvert()` in `wordbin.ts` |
-| `DecodeResult` type or `PayloadFormat` union             | top of `wordbin.ts`                  |
-| Partial scan / best-effort fallback                      | `partialScan()` in `wordbin.ts`      |
-| Dictionary loading and versioning                        | `src/dict/dictionary-loader.ts`      |
-| Building a dictionary from a wordlist                    | `src/dict/builder.ts`                |
-| Buffer utilities (varint, hex, utf8)                     | `src/utils/buffer.ts`                |
-| Shared constants (LITERAL byte value)                    | `src/constants.ts`                   |
-| Tests                                                    | `test/test.spec.ts`                  |
-
----
+Main source code lives in `src/`.  
+Generated dictionaries appear in `data/`.
 
 ## Current Priorities (2026)
 
 These improvements would have the biggest impact right now:
 
-- **Case-insensitive dictionaries** — normalise to lowercase during dictionary building so `"Hello"` and `"hello"` encode identically
-- **Smaller curated dictionaries** — top 10k–50k common English words, programming keywords, domain-specific lists (DeFi, medical, etc.)
-- **Bin21 safety** — audit which Latin-1 characters survive common transports (databases, JSON fields) without corruption; document safe subsets
-- **Performance benchmarks** — encode/decode throughput across dictionary sizes and phrase lengths
-- **Browser demo** — a minimal CodeSandbox or static HTML page showing encode/decode live
-- **CLI enhancements** — progress bars, `--lowercase` flag, `--output-dir`, improved help text
-- **Error messages** — clearer messages when a dictionary is missing, input is invalid, or a version mismatch is detected
+- Case-insensitive dictionaries (normalize to lowercase during build)
+- Smaller curated dictionaries (top 10k–50k words, programming keywords, domain-specific lists…)
+- Performance & compression benchmarks across dictionaries and phrase lengths
+- Interactive browser demo (CodeSandbox / StackBlitz / simple HTML page)
+- CLI enhancements (progress bars, `--lowercase`, `--output-dir`, better help)
+- Better error handling & messages (missing dictionary, invalid input, etc.)
 
-If you're unsure where to begin, open an issue or a draft PR — we're happy to help you find a good starting point.
-
----
+If you're unsure where to begin — feel free to ask in an issue or draft PR!
 
 ## Code Style & Conventions
 
-- **ESM** — `import` / `export` throughout, no CommonJS
-- **TypeScript** — all source files, strict mode preferred
-- **Vitest** — for all tests; no Jest
-- **async/await** — preferred over `.then()` chains
-- **Small, focused functions** — each function does one thing
-- **JSDoc** on all public methods and exported types
+- ESM syntax (`import` / `export`)
+- TypeScript where possible
+- Vitest for testing
+- Prefer async/await
+- Small, focused functions
+- JSDoc comments for public APIs
 
-Run these before committing:
+We use **Prettier** + **ESLint** — run these before committing:
 
 ```bash
 npm run lint
 npm run format
 ```
 
----
-
 ## License
 
-By contributing code to this project, you agree that your contribution will be licensed under the same [MIT License](./LICENSE) as the rest of the project.
+By contributing your code to this project, you agree that it will be licensed under the same [MIT License](./LICENSE) as the rest of the project.
 
-Thank you for helping make WordBin better — we up 🚀
+Thank you for helping make WordBin better!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigdreamsweb3/wordbin",
-  "version": "1.0.8",
+  "version": "1.1.7",
   "description": "WordBin – Encode words & short text into tiny, reversible binary for storage, URLs, IoT, QR codes, metadata, blockchain, or Web3 apps.",
   "author": "Agbaka Daniel Ugonna <99cratson@gmail.com>",
   "license": "MIT",