@bigdreamsweb3/wordbin 1.0.7 → 1.1.0

package/dist/core/index.d.ts

@@ -0,0 +1,58 @@
+import { EncodeResult, WordBinDictionary } from '../types.js';
+type PayloadFormat = "bytes" | "base58" | "base64" | "hex" | "bin21";
+export interface DecodeResult {
+    /** The decoded text — words for WordBin payloads, best-effort for others. */
+    text: string;
+    /** True only when the payload was a valid, fully-parsed WordBin stream. */
+    isWordBin: boolean;
+    /** Auto-detected wire format of the input. */
+    detectedFormat: PayloadFormat;
+    /**
+     * Human-readable notice when the payload is not a valid WordBin stream.
+     * Includes information about what the decoder did as a fallback.
+     */
+    notice?: string;
+    /**
+     * Present when partial scanning was used (non-WordBin payloads).
+     * Lists raw byte sequences that had no dictionary match, in order.
+     */
+    rawSegments?: string[];
+}
+export declare class WordBin {
+    private primaryDictVersion;
+    private log;
+    constructor(initialDict?: WordBinDictionary, options?: {
+        debug?: boolean;
+    });
+    static createFromWords(words: string[]): Promise<WordBin>;
+    static createFromJson(dictJson: WordBinDictionary): Promise<WordBin>;
+    static create(options?: {
+        debug?: boolean;
+    }): Promise<WordBin>;
+    private getMapsForVersion;
+    encode(text: string | EncodeResult | Uint8Array, options?: {
+        dictVersion?: number;
+    }): Promise<EncodeResult>;
+    /**
+     * Decodes any supported payload format back to human-readable text.
+     *
+     * For valid WordBin payloads:  returns the exact original words.
+     * For non-WordBin payloads:    scans byte-by-byte, extracts dictionary words
+     *                               wherever possible, and preserves unrecognised
+     *                               bytes as "[0xXX]" markers.
+     */
+    decode(payload: Uint8Array | string): Promise<DecodeResult>;
+    /**
+     * O(n) longest-match-first decode. Returns null if any byte has no match.
+     * This is the fast path; tryDecode is used as a backtracking fallback.
+     */
+    private greedyDecode;
+    /**
+     * Scans through the buffer extracting any recognised dictionary words.
+     * Unrecognised bytes are collected as raw segments and rendered as [0xXX].
+     * Always consumes the entire buffer — never returns null.
+     */
+    private partialScan;
+    private tryDecode;
+}
+export {};

package/dist/data/wordbin-v1-bip39.json

@@ -446,15 +446,15 @@
     "988180": [
       "offer"
     ],
-    "b0ad": [
-      "able"
-    ],
     "df864c": [
       "abandon"
     ],
     "bcffaa": [
       "ability"
     ],
+    "b0ad": [
+      "able"
+    ],
     "a4262e": [
       "about"
     ],
@@ -1647,8 +1647,7 @@
       "crush"
     ],
     "58a6": [
-      "cry",
-      "math"
+      "cry"
     ],
     "60a0f7": [
       "crystal"
@@ -2574,24 +2573,24 @@
     "5a5770": [
       "furnace"
     ],
-    "f44a": [
-      "fury"
-    ],
     "ebb3de": [
       "future"
     ],
+    "f44a": [
+      "fury"
+    ],
     "4e5aa6": [
       "gadget"
     ],
     "66dd": [
       "gain"
     ],
-    "eba4ae": [
-      "galaxy"
-    ],
     "ce387d": [
       "gallery"
     ],
+    "eba4ae": [
+      "galaxy"
+    ],
     "6ca5": [
       "game"
     ],
@@ -6143,6 +6142,9 @@
     ],
     "24fe": [
       "zoo"
+    ],
+    "ad06fa": [
+      "math"
     ]
   }
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { MAGIC } from './constants.js';
+export { MAGIC } from './constants';
 export { buildDictionary } from './dict/builder';
-export { WordBin } from './core.js';
+export { WordBin } from './core/index';
 export type { EncodeResult, WordBinDictionary } from './types';

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { b as buildDictionary, t as toBase64, u as utf8Encode, e as encodeVarint, f as fromBase64, d as decodeVarint, a as utf8Decode, c as toHex } from "./builder-e2OwBYJh.js";
+import { b as buildDictionary, t as toBase64, u as utf8Encode, e as encodeVarint, d as decodeVarint, a as utf8Decode, c as toHex } from "./builder-vFphFQMU.js";
 import fs from "fs/promises";
 import path from "path";
 import { fileURLToPath } from "url";
@@ -81,9 +81,174 @@ async function loadLatestDictionary() {
   );
   return loadDictionaryByVersion(latestVersion);
 }
+function base(ALPHABET2) {
+  if (ALPHABET2.length >= 255) {
+    throw new TypeError("Alphabet too long");
+  }
+  const BASE_MAP = new Uint8Array(256);
+  for (let j = 0; j < BASE_MAP.length; j++) {
+    BASE_MAP[j] = 255;
+  }
+  for (let i = 0; i < ALPHABET2.length; i++) {
+    const x = ALPHABET2.charAt(i);
+    const xc = x.charCodeAt(0);
+    if (BASE_MAP[xc] !== 255) {
+      throw new TypeError(x + " is ambiguous");
+    }
+    BASE_MAP[xc] = i;
+  }
+  const BASE = ALPHABET2.length;
+  const LEADER = ALPHABET2.charAt(0);
+  const FACTOR = Math.log(BASE) / Math.log(256);
+  const iFACTOR = Math.log(256) / Math.log(BASE);
+  function encode(source) {
+    if (source instanceof Uint8Array) ;
+    else if (ArrayBuffer.isView(source)) {
+      source = new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+    } else if (Array.isArray(source)) {
+      source = Uint8Array.from(source);
+    }
+    if (!(source instanceof Uint8Array)) {
+      throw new TypeError("Expected Uint8Array");
+    }
+    if (source.length === 0) {
+      return "";
+    }
+    let zeroes = 0;
+    let length = 0;
+    let pbegin = 0;
+    const pend = source.length;
+    while (pbegin !== pend && source[pbegin] === 0) {
+      pbegin++;
+      zeroes++;
+    }
+    const size = (pend - pbegin) * iFACTOR + 1 >>> 0;
+    const b58 = new Uint8Array(size);
+    while (pbegin !== pend) {
+      let carry = source[pbegin];
+      let i = 0;
+      for (let it1 = size - 1; (carry !== 0 || i < length) && it1 !== -1; it1--, i++) {
+        carry += 256 * b58[it1] >>> 0;
+        b58[it1] = carry % BASE >>> 0;
+        carry = carry / BASE >>> 0;
+      }
+      if (carry !== 0) {
+        throw new Error("Non-zero carry");
+      }
+      length = i;
+      pbegin++;
+    }
+    let it2 = size - length;
+    while (it2 !== size && b58[it2] === 0) {
+      it2++;
+    }
+    let str = LEADER.repeat(zeroes);
+    for (; it2 < size; ++it2) {
+      str += ALPHABET2.charAt(b58[it2]);
+    }
+    return str;
+  }
+  function decodeUnsafe(source) {
+    if (typeof source !== "string") {
+      throw new TypeError("Expected String");
+    }
+    if (source.length === 0) {
+      return new Uint8Array();
+    }
+    let psz = 0;
+    let zeroes = 0;
+    let length = 0;
+    while (source[psz] === LEADER) {
+      zeroes++;
+      psz++;
+    }
+    const size = (source.length - psz) * FACTOR + 1 >>> 0;
+    const b256 = new Uint8Array(size);
+    while (psz < source.length) {
+      const charCode = source.charCodeAt(psz);
+      if (charCode > 255) {
+        return;
+      }
+      let carry = BASE_MAP[charCode];
+      if (carry === 255) {
+        return;
+      }
+      let i = 0;
+      for (let it3 = size - 1; (carry !== 0 || i < length) && it3 !== -1; it3--, i++) {
+        carry += BASE * b256[it3] >>> 0;
+        b256[it3] = carry % 256 >>> 0;
+        carry = carry / 256 >>> 0;
+      }
+      if (carry !== 0) {
+        throw new Error("Non-zero carry");
+      }
+      length = i;
+      psz++;
+    }
+    let it4 = size - length;
+    while (it4 !== size && b256[it4] === 0) {
+      it4++;
+    }
+    const vch = new Uint8Array(zeroes + (size - it4));
+    let j = zeroes;
+    while (it4 !== size) {
+      vch[j++] = b256[it4++];
+    }
+    return vch;
+  }
+  function decode(string) {
+    const buffer = decodeUnsafe(string);
+    if (buffer) {
+      return buffer;
+    }
+    throw new Error("Non-base" + BASE + " character");
+  }
+  return {
+    encode,
+    decodeUnsafe,
+    decode
+  };
+}
+var ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const bs58 = base(ALPHABET);
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function detectAndConvert(payload) {
+  if (/^[0-9a-fA-F]+$/.test(payload) && payload.length % 2 === 0) {
+    const bytes2 = Uint8Array.from(
+      payload.match(/.{1,2}/g).map((h) => parseInt(h, 16))
+    );
+    return { buffer: bytes2, detectedFormat: "hex" };
+  }
+  const base58Re = /^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$/;
+  if (base58Re.test(payload)) {
+    try {
+      return { buffer: bs58.decode(payload), detectedFormat: "base58" };
+    } catch {
+    }
+  }
+  const b64Re = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$/;
+  const b64urlRe = /^(?:[A-Za-z0-9\-_]{4})*(?:[A-Za-z0-9\-_]{2}(?:==)?|[A-Za-z0-9\-_]{3}=?|[A-Za-z0-9\-_]{4})$/;
+  const norm = payload.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = norm + (norm.length % 4 ? "=".repeat(4 - norm.length % 4) : "");
+  if (b64Re.test(payload) || b64urlRe.test(payload)) {
+    try {
+      const bin = atob(padded);
+      return {
+        buffer: Uint8Array.from(bin, (c) => c.charCodeAt(0)),
+        detectedFormat: "base64"
+      };
+    } catch {
+    }
+  }
+  const bytes = new Uint8Array(payload.length);
+  for (let i = 0; i < payload.length; i++) bytes[i] = payload.charCodeAt(i);
+  return { buffer: bytes, detectedFormat: "bin21" };
+}
 class WordBin {
   constructor(initialDict, options) {
-    this.primaryDictVersion = initialDict?.version ?? 2;
+    this.primaryDictVersion = initialDict?.version ?? 1;
     this.log = options?.debug ? (...args) => console.log("[WordBin]", ...args) : () => {
     };
   }
@@ -91,15 +256,13 @@ class WordBin {
     console.warn(
       "Building dictionary from scratch – consider using pre-built files"
     );
-    const dict = await buildDictionary(words);
-    return new WordBin(dict);
+    return new WordBin(await buildDictionary(words));
   }
   static async createFromJson(dictJson) {
     return new WordBin(dictJson);
   }
   static async create(options) {
-    const latestDict = await loadLatestDictionary();
-    return new WordBin(latestDict, options);
+    return new WordBin(await loadLatestDictionary(), options);
   }
   async getMapsForVersion(version) {
     const dict = await loadDictionaryByVersion(version);
@@ -119,9 +282,13 @@ class WordBin {
       reverseMap.set(hex, word);
       forwardMap.set(word, bytes);
     }
-    const sortedIdLengths = Array.from(idLengths).sort((a, b) => b - a);
-    return { reverseMap, forwardMap, sortedIdLengths };
+    return {
+      reverseMap,
+      forwardMap,
+      sortedIdLengths: Array.from(idLengths).sort((a, b) => b - a)
+    };
   }
+  // ── encode ──────────────────────────────────────────────────────────────────
   async encode(text, options) {
     let textStr;
     if (typeof text === "string") {
@@ -129,7 +296,7 @@ class WordBin {
     } else if (text instanceof Uint8Array) {
       textStr = toBase64(text);
     } else {
-      textStr = text.encodedBase64;
+      textStr = text.base64Payload;
     }
     const trimmed = textStr.trim();
     if (!trimmed) {
@@ -138,19 +305,21 @@ class WordBin {
         dictVersion: this.primaryDictVersion,
         encoded: new Uint8Array(0),
         payload: "",
-        encodedBase64: "",
+        bin21: "",
+        bin21Payload: "",
+        base64Payload: "",
+        hexPayload: "",
+        base58Payload: "",
         originalBytes: 0,
         encodedBytes: 0,
         bytesSaved: 0,
         ratioPercent: 100
       };
     }
-    const words = trimmed.split(/\s+/).filter(Boolean);
     const useVersion = options?.dictVersion ?? this.primaryDictVersion;
-    const header = new Uint8Array([useVersion]);
-    const chunks = [header];
     const { forwardMap } = await this.getMapsForVersion(useVersion);
-    for (const w of words) {
+    const chunks = [new Uint8Array([useVersion])];
+    for (const w of trimmed.split(/\s+/).filter(Boolean)) {
       const id = forwardMap.get(w);
       if (id) {
         chunks.push(id);
@@ -172,65 +341,220 @@ class WordBin {
       offset += chunk.length;
     }
     const originalBytes = new TextEncoder().encode(textStr).length;
-    const base64Result = toBase64(result);
+    const hexPayload = bytesToHex(result);
+    const bin21Payload = Array.from(result).map((b) => String.fromCharCode(b)).join("");
+    const base64Payload = toBase64(result);
+    const base58Payload = bs58.encode(result);
     return {
       originalText: textStr,
       dictVersion: useVersion,
       encoded: result,
-      payload: base64Result,
-      encodedBase64: base64Result,
+      bin21: bin21Payload,
+      payload: bin21Payload,
+      bin21Payload,
+      hexPayload,
+      base64Payload,
+      base58Payload,
       originalBytes,
-      encodedBytes: totalLength,
-      bytesSaved: originalBytes - totalLength,
-      ratioPercent: totalLength === 0 ? 100 : Math.round(totalLength / originalBytes * 100 * 100) / 100
+      encodedBytes: bin21Payload.length,
+      bytesSaved: originalBytes - bin21Payload.length,
+      ratioPercent: Math.round(bin21Payload.length / originalBytes * 1e4) / 100
     };
   }
-  async decode(data) {
+  // ── decode ───────────────────────────────────────────────────────────────────
+  /**
+   * Decodes any supported payload format back to human-readable text.
+   *
+   * For valid WordBin payloads:  returns the exact original words.
+   * For non-WordBin payloads:    scans byte-by-byte, extracts dictionary words
+   *                               wherever possible, and preserves unrecognised
+   *                               bytes as "[0xXX]" markers.
+   */
+  async decode(payload) {
     let buffer;
-    if (typeof data === "string") {
-      buffer = fromBase64(data);
+    let detectedFormat;
+    if (payload instanceof Uint8Array) {
+      buffer = payload;
+      detectedFormat = "bytes";
     } else {
-      buffer = data;
+      ({ buffer, detectedFormat } = detectAndConvert(payload));
     }
+    this.log(
+      `[decode] format=${detectedFormat} bufLen=${buffer.length} firstBytes=[${Array.from(buffer.slice(0, 8)).join(",")}]`
+    );
     if (buffer.length < 1) {
-      throw new Error("Data too short to contain version byte");
-    }
-    const version = buffer[0];
-    let pos = 1;
-    const { reverseMap, sortedIdLengths } = await this.getMapsForVersion(version);
-    const result = [];
-    const decoded = this.tryDecode(
-      pos,
-      buffer,
-      reverseMap,
-      result,
-      0,
-      sortedIdLengths
+      return {
+        text: "",
+        isWordBin: false,
+        detectedFormat,
+        notice: "Payload is empty — nothing to decode."
+      };
+    }
+    const availableVersions = await getAllAvailableDictionaryVersions();
+    const versionByte = buffer[0];
+    const versionIsHeader = availableVersions.includes(versionByte);
+    this.log(
+      `[decode] availableVersions=[${availableVersions.join(",")}] versionByte=${versionByte} isKnownHeader=${versionIsHeader}`
     );
-    if (decoded === null) {
-      throw new Error(
-        "Decode failed — possible data corruption, wrong dictionary version, or unsupported format"
+    const tryOrder = versionIsHeader ? [versionByte, ...availableVersions.filter((v) => v !== versionByte)] : [...availableVersions];
+    for (const ver of tryOrder) {
+      let maps;
+      try {
+        maps = await this.getMapsForVersion(ver);
+      } catch (err) {
+        this.log(`[decode] v${ver}: getMapsForVersion threw — ${err}`);
+        continue;
+      }
+      const { reverseMap, sortedIdLengths } = maps;
+      const r1 = this.greedyDecode(buffer, 1, reverseMap, sortedIdLengths) ?? this.tryDecode(1, buffer, reverseMap, [], 0, sortedIdLengths);
+      this.log(
+        `[decode] v${ver} strict(pos=1): ${r1 !== null ? `"${r1}"` : "null"}`
+      );
+      if (r1 !== null) {
+        const notice2 = versionByte === ver ? void 0 : `Byte[0]=${versionByte} is not a recognised version header but decoded successfully with dictionary v${ver}.`;
+        return { text: r1, isWordBin: true, detectedFormat, notice: notice2 };
+      }
+      const r0 = this.greedyDecode(buffer, 0, reverseMap, sortedIdLengths) ?? this.tryDecode(0, buffer, reverseMap, [], 0, sortedIdLengths);
+      this.log(
+        `[decode] v${ver} strict(pos=0): ${r0 !== null ? `"${r0}"` : "null"}`
       );
+      if (r0 !== null) {
+        return {
+          text: r0,
+          isWordBin: true,
+          detectedFormat,
+          notice: `Payload had no version header. Decoded using dictionary v${ver}.`
+        };
+      }
+    }
+    this.log(`[decode] strict parse failed — falling back to partial scan`);
+    if (availableVersions.length > 0) {
+      const scanVersion = availableVersions[availableVersions.length - 1];
+      try {
+        const { reverseMap, sortedIdLengths } = await this.getMapsForVersion(scanVersion);
+        const scan1 = this.partialScan(buffer, 1, reverseMap, sortedIdLengths);
+        const scan0 = this.partialScan(buffer, 0, reverseMap, sortedIdLengths);
+        const best = scan1.wordCount >= scan0.wordCount ? scan1 : scan0;
+        this.log(
+          `[decode] partial scan(pos=1) words=${scan1.wordCount} raw=${scan1.rawSegments.length} | scan(pos=0) words=${scan0.wordCount} raw=${scan0.rawSegments.length}`
+        );
+        const notice2 = `This does not appear to be a valid WordBin payload. Partial scan using dictionary v${scanVersion} extracted ${best.wordCount} word(s); ${best.rawSegments.length} byte sequence(s) had no dictionary match and are shown as [0xXX] markers.`;
+        return {
+          text: best.text,
+          isWordBin: false,
+          detectedFormat,
+          rawSegments: best.rawSegments,
+          notice: notice2
+        };
+      } catch {
+      }
     }
-    return decoded;
+    const notice = `Could not decode with any available dictionary (tried: ${availableVersions.join(", ") || "none"}). Falling back to UTF-8 text decoding.`;
+    this.log(`[decode] ${notice}`);
+    return {
+      text: new TextDecoder("utf-8", { fatal: false }).decode(buffer),
+      isWordBin: false,
+      detectedFormat,
+      notice
+    };
   }
-  tryDecode(pos, buffer, reverseMap, result, depth, sortedIdLengths) {
-    if (pos === buffer.length) {
-      return result.join(" ");
+  // ── Private: greedy linear decode ────────────────────────────────────────────
+  /**
+   * O(n) longest-match-first decode. Returns null if any byte has no match.
+   * This is the fast path; tryDecode is used as a backtracking fallback.
+   */
+  greedyDecode(buffer, startPos, reverseMap, sortedIdLengths) {
+    const words = [];
+    let pos = startPos;
+    while (pos < buffer.length) {
+      if (buffer[pos] === LITERAL) {
+        const { value: byteLen, bytesRead } = decodeVarint(buffer, pos + 1);
+        if (byteLen > 1e6 || byteLen < 0) return null;
+        const start = pos + 1 + bytesRead;
+        const end = start + byteLen;
+        if (end > buffer.length) return null;
+        words.push(utf8Decode(buffer.subarray(start, end)));
+        pos = end;
+        continue;
+      }
+      let matched = false;
+      for (const len of sortedIdLengths) {
+        if (pos + len > buffer.length) continue;
+        const key = toHex(buffer.subarray(pos, pos + len));
+        if (reverseMap.has(key)) {
+          words.push(reverseMap.get(key));
+          pos += len;
+          matched = true;
+          break;
+        }
+      }
+      if (!matched) return null;
+    }
+    return words.join(" ");
+  }
+  // ── Private: partial / best-effort scan ──────────────────────────────────────
+  /**
+   * Scans through the buffer extracting any recognised dictionary words.
+   * Unrecognised bytes are collected as raw segments and rendered as [0xXX].
+   * Always consumes the entire buffer — never returns null.
+   */
+  partialScan(buffer, startPos, reverseMap, sortedIdLengths) {
+    const parts = [];
+    const rawSegments = [];
+    let wordCount = 0;
+    let pos = startPos;
+    while (pos < buffer.length) {
+      if (buffer[pos] === LITERAL && pos + 1 < buffer.length) {
+        try {
+          const { value: byteLen, bytesRead } = decodeVarint(buffer, pos + 1);
+          if (byteLen > 0 && byteLen <= 1e6) {
+            const start = pos + 1 + bytesRead;
+            const end = start + byteLen;
+            if (end <= buffer.length) {
+              const word = utf8Decode(buffer.subarray(start, end));
+              parts.push(word);
+              wordCount++;
+              pos = end;
+              continue;
+            }
+          }
+        } catch {
+        }
+      }
+      let matched = false;
+      for (const len of sortedIdLengths) {
+        if (pos + len > buffer.length) continue;
+        const key = toHex(buffer.subarray(pos, pos + len));
+        if (reverseMap.has(key)) {
+          parts.push(reverseMap.get(key));
+          wordCount++;
+          pos += len;
+          matched = true;
+          break;
+        }
+      }
+      if (!matched) {
+        const marker = `[0x${buffer[pos].toString(16).padStart(2, "0")}]`;
+        parts.push(marker);
+        rawSegments.push(marker);
+        this.log(
+          `[decode] partial scan: no match at pos=${pos} byte=${buffer[pos]}`
+        );
+        pos++;
+      }
     }
+    return { text: parts.join(" "), wordCount, rawSegments };
+  }
+  // ── Private: backtracking decode ─────────────────────────────────────────────
+  tryDecode(pos, buffer, reverseMap, result, depth, sortedIdLengths) {
+    if (pos === buffer.length) return result.join(" ");
     if (buffer[pos] === LITERAL) {
       const { value: byteLen, bytesRead } = decodeVarint(buffer, pos + 1);
-      if (byteLen > 1e6 || byteLen < 0) {
-        return null;
-      }
+      if (byteLen > 1e6 || byteLen < 0) return null;
       const start = pos + 1 + bytesRead;
       const end = start + byteLen;
-      if (end > buffer.length) {
-        return null;
-      }
-      const literalBytes = buffer.subarray(start, end);
-      const word = utf8Decode(literalBytes);
-      result.push(word);
+      if (end > buffer.length) return null;
+      result.push(utf8Decode(buffer.subarray(start, end)));
       const res = this.tryDecode(
         end,
         buffer,
@@ -244,11 +568,9 @@ class WordBin {
     }
     for (const len of sortedIdLengths) {
       if (pos + len > buffer.length) continue;
-      const slice = buffer.subarray(pos, pos + len);
-      const key = toHex(slice);
+      const key = toHex(buffer.subarray(pos, pos + len));
       if (reverseMap.has(key)) {
-        const word = reverseMap.get(key);
-        result.push(word);
+        result.push(reverseMap.get(key));
         const res = this.tryDecode(
           pos + len,
           buffer,