shortwords 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT LICENSE
+
+Copyright (c) 2026 Timothy T. Joe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# Shortwords
+
+This library generates pronounceable 2, 3, and 4‑letter English words. It is ideal for brainstorming unique project code names, creating short file extensions, or generating random identifiers.
+
+### Installation
+
+```bash
+npm install shortwords
+```
+
+### Usage
+
+Generate random 3‑letter words.
+
+```typescript
+import shortwords from "shortwords";
+
+const results = shortwords(3);
+console.log([...results]);
+// Example output (your results will vary):
+[
+  "fco", "adi", "apq", "imi",
+  "aob", "ajy", "vzu", "rif"...
+]
+```
+
+Apply constraints by chaining methods.
+Here we request exactly 5 words of size 4, following the `CVCV` pattern.
+
+```typescript
+const results = shortwords(4).pattern('cvcv').results(5);
+
+console.log([...results]);
+// Example output (your results will vary):
+['tucu', 'sivu', 'kive', 'rulu', 'gimu'];
+
+// Get first word in list
+console.log(results.get(0));
+// output: tucu
+```
+
+Configure everything in one call using an options object.
+
+```typescript
+
+// Configuration Signature:
+shortwords(
+  size,                   // integer (2, 3, or 4) for word length
+  {
+    results?: number,     // number of words to generate
+    pattern?: string,     // syllable pattern string (e.g., "CVC", "VCV")
+    lock?: boolean        // freeze the instance state
+  }
+)
+
+// Single-call option:
+const results = shortwords(3, { results: 8, pattern: "VCV" });
+
+```
+
+Use `.mix()` to ignore size boundaries and generate a random assortment of 2, 3, or 4‑letter words.
+The result supports native array methods.
+
+```typescript
+const results = shortwords().mix().results(6);
+// Mixed Size Words:
+['veuq', 'iwdu', 'iof', 'qsi', 'oq', 'luiy'];
+
+// Mapped Array (Uppercase):
+results.map((w) => w.toUpperCase());
+// Example output (your results will vary):
+['VEUQ', 'IWDU', 'IOF', 'QSI', 'OQ', 'LUIY'];
+```
+
+Lock a result to prevent further modifications. Attempts to change after `.lock()` are ignored.
+
+```typescript
+const results = shortwords(3).results(3).lock();
+
+results.pattern('vcv').results(10); // ignored
+```
+
+### Global History
+
+Every call to `shortwords()` is recorded in a global history store.  
+You can access either:
+
+- **The previous run** — the last array generated.
+- **The full active history** — all arrays generated during the current lifecycle, in chronological order.
+
+```typescript
+shortwords.prev(); // Returns a single array of words from the most recent run.
+shortwords.history(); // Returns multiple arrays of words, one for each run so far.
+```
+
+### GUI
+
+Shortwords also ships with a simple GUI.  
+Launch it with:
+
+```bash
+npx shortwords gui
+```
+
+This opens a local web interface where you can configure length, patterns, and modes interactively, and copy generated results.
+
+### API
+
+The core `shortwords(size)` function initiates an iterable builder. Omitting `size` generates mixed lengths.
+
+- **`.results(n)`** – Set the number of words to return. See below table for maximum counts.
+- **`.pattern(str)`** – Enforce a syllable pattern (e.g., `"cvc"`). Case-insensitive.
+- **`.get(index)`** – Retrieve a specific word without array bracket notation.
+- **`.mix()`** – Ignore size limits and generate mixed 2, 3, and 4‑letter words.
+- **`.lock()`** – Freeze the current state to prevent further chained modifications.
+
+#### Global State
+
+- **`.prev()`** – Returns a single array of words from the most recent run.
+- **`.history()`** – Returns multiple arrays of words, one for each run so far.
+
+Words are generated using strict Consonant (`C`) and Vowel (`V`) pools to ensure pronounceability.
+
+| Character Type     | Pool                                                          | Total |
+| ------------------ | ------------------------------------------------------------- | ----- |
+| **Vowels (V)**     | a, e, i, o, u                                                 | 5     |
+| **Consonants (C)** | b, c, d, f, g, h, j, k, l, m, n, p, q, r, s, t, v, w, x, y, z | 21    |
+
+| Size  | Default Patterns                               | Result Example   | Max Count |
+| ----- | ---------------------------------------------- | ---------------- | --------- |
+| **2** | CV, VC                                         | to, up           | 210       |
+| **3** | CVC, VCV, CVV, VVC, CCV, VCC                   | cat, ago, bee    | 13,860    |
+| **4** | CVCV, VCVC, CVVC, VCCV, CCVV, VVCC, CCVC, CVCC | code, acid, book | 743,610   |
+

package/bin/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import http from "http";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import open from "open";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const args = process.argv.slice(2);
+
+const guiPath = path.join(__dirname, "../gui");
+const distPath = path.join(__dirname, "../dist");
+
+function serveFile(filePath, res) {
+  const ext = path.extname(filePath).toLowerCase();
+  fs.readFile(filePath, (err, content) => {
+    if (err) {
+      res.writeHead(404);
+      res.end("Not found");
+    } else {
+      const type =
+        ext === ".css" ? "text/css" :
+          ext === ".js" ? "application/javascript" :
+            "text/html";
+      res.writeHead(200, { "Content-Type": type });
+      res.end(content);
+    }
+  });
+}
+
+if (args[0] === "gui") {
+  const server = http.createServer((req, res) => {
+    let filePath;
+    if (req.url.startsWith("/dist/")) {
+      filePath = path.join(distPath, req.url.replace("/dist/", ""));
+    } else {
+      filePath = path.join(guiPath, req.url === "/" ? "index.html" : req.url);
+    }
+    serveFile(filePath, res);
+  });
+
+  const port = 5555;
+  server.listen(port, () => {
+    console.log(`Shortwords GUI running at http://localhost:${port}`);
+    open(`http://localhost:${port}`);
+  });
+} else {
+  console.log("Usage: shortwords gui");
+}

package/dist/builder.d.ts

@@ -0,0 +1,42 @@
+import { Size, Options } from './types.js';
+/**
+ * A chainable builder that wraps generated word lists.
+ */
+export declare class Builder implements Iterable<string> {
+    #private;
+    constructor(size?: Size, options?: Options, onGenerate?: (words: string[]) => void);
+    /**
+     * Returns the number of words.
+     */
+    get length(): number;
+    /**
+     * Retrieves a specific word by index without array bracket notation.
+     */
+    get(index: number): string | undefined;
+    /**
+     * Ignores size limits and generates mixed 2, 3, and 4-letter words.
+     */
+    mix(): this;
+    /**
+     * Sets the number of words to return.
+     */
+    results(number: number): this;
+    /**
+     * Enforces a syllable pattern (case-insensitive).
+     */
+    pattern(patternString: string): this;
+    /**
+     * Freezes the current state to prevent further chained modifications.
+     */
+    lock(): this;
+    /**
+     * Returns a standard array copy of the generated words.
+     */
+    toArray(): string[];
+    /**
+     * Maps over the generated words array.
+     */
+    map<U>(callbackfn: (value: string, index: number, array: string[]) => U): U[];
+    [Symbol.iterator](): Iterator<string>;
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAW,OAAO,EAAC,MAAM,YAAY,CAAC;AAGlD;;GAEG;AACH,qBAAa,OAAQ,YAAW,QAAQ,CAAC,MAAM,CAAC;;IAQ9C,YACE,IAAI,CAAC,EAAE,IAAI,EACX,OAAO,CAAC,EAAE,OAAO,EACjB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,EAqBvC;IAUD;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAErC;IAED;;OAEG;IACH,GAAG,IAAI,IAAI,CAKV;IAED;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAQ5B;IAED;;OAEG;IACH,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAanC;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,CAGX;IAED;;OAEG;IACH,OAAO,IAAI,MAAM,EAAE,CAElB;IAED;;OAEG;IACH,GAAG,CAAC,CAAC,EACH,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAC/D,CAAC,EAAE,CAEL;IAEA,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAIrC;CACF"}

package/dist/builder.js

@@ -0,0 +1,112 @@
+import { genWords, InternalError } from './utils.js';
+/**
+ * A chainable builder that wraps generated word lists.
+ */
+export class Builder {
+    #words = [];
+    #size;
+    #count = 20;
+    #pattern;
+    #isLocked = false;
+    #onGenerate;
+    constructor(size, options, onGenerate) {
+        this.#size = size;
+        if (onGenerate) {
+            this.#onGenerate = onGenerate;
+        }
+        if (options) {
+            if (options.results !== undefined) {
+                if (!Number.isInteger(options.results) || options.results < 0) {
+                    throw new InternalError('Results count must be a non-negative integer.');
+                }
+                this.#count = options.results;
+            }
+            if (options.pattern !== undefined)
+                this.#pattern = options.pattern;
+            if (options.lock !== undefined)
+                this.#isLocked = options.lock;
+        }
+        this.#execute();
+    }
+    #execute() {
+        if (this.#isLocked)
+            return;
+        this.#words = genWords(this.#size, this.#pattern, this.#count);
+        if (this.#onGenerate) {
+            this.#onGenerate(this.#words);
+        }
+    }
+    /**
+     * Returns the number of words.
+     */
+    get length() {
+        return this.#words.length;
+    }
+    /**
+     * Retrieves a specific word by index without array bracket notation.
+     */
+    get(index) {
+        return this.#words[index];
+    }
+    /**
+     * Ignores size limits and generates mixed 2, 3, and 4-letter words.
+     */
+    mix() {
+        if (this.#isLocked)
+            return this;
+        this.#size = undefined;
+        this.#execute();
+        return this;
+    }
+    /**
+     * Sets the number of words to return.
+     */
+    results(number) {
+        if (this.#isLocked)
+            return this;
+        if (!Number.isInteger(number) || number < 0) {
+            throw new InternalError('Results count must be a non-negative integer.');
+        }
+        this.#count = number;
+        this.#execute();
+        return this;
+    }
+    /**
+     * Enforces a syllable pattern (case-insensitive).
+     */
+    pattern(patternString) {
+        if (this.#isLocked)
+            return this;
+        const normalized = patternString.toUpperCase();
+        if (this.#size && normalized.length !== this.#size) {
+            throw new InternalError(`Pattern "${patternString}" length does not match size ${this.#size}`);
+        }
+        this.#pattern = normalized;
+        this.#execute();
+        return this;
+    }
+    /**
+     * Freezes the current state to prevent further chained modifications.
+     */
+    lock() {
+        this.#isLocked = true;
+        return this;
+    }
+    /**
+     * Returns a standard array copy of the generated words.
+     */
+    toArray() {
+        return [...this.#words];
+    }
+    /**
+     * Maps over the generated words array.
+     */
+    map(callbackfn) {
+        return this.#words.map(callbackfn);
+    }
+    *[Symbol.iterator]() {
+        for (const word of this.#words) {
+            yield word;
+        }
+    }
+}

package/dist/history.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tracks historical outputs using weak references to prevent memory leaks.
+ */
+export declare class History {
+    #private;
+    add(wordsArray: string[]): void;
+    getHistory(): string[][];
+}
+//# sourceMappingURL=history.d.ts.map

package/dist/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,OAAO;;IAGlB,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAE9B;IAED,UAAU,IAAI,MAAM,EAAE,EAAE,CAavB;CACF"}

package/dist/history.js

@@ -0,0 +1,21 @@
+/**
+ * Tracks historical outputs using weak references to prevent memory leaks.
+ */
+export class History {
+    #records = [];
+    add(wordsArray) {
+        this.#records.push(new WeakRef(wordsArray));
+    }
+    getHistory() {
+        const activeRecords = [];
+        this.#records = this.#records.filter((ref) => {
+            const dereferenced = ref.deref();
+            if (dereferenced !== undefined) {
+                activeRecords.push(dereferenced);
+                return true;
+            }
+            return false;
+        });
+        return activeRecords;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { Size, Options } from './types.js';
+import { Builder } from './builder.js';
+/**
+ * Initiates an iterable builder for generating pronounceable words.
+ * Omitting size generates mixed lengths.
+ */
+declare function generate(size?: Size, options?: Options): Builder;
+declare const shortwords: typeof generate & {
+    /**
+     * Returns a single array of words from the most recent run.
+     */
+    prev(): string[] | undefined;
+    /**
+     * Returns multiple arrays of words, one for each run so far.
+     */
+    history(): string[][];
+};
+export default shortwords;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAE,OAAO,EAAC,MAAM,YAAY,CAAC;AACzC,OAAO,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAMrC;;;GAGG;AACH,iBAAS,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAKzD;AAED,QAAA,MAAM,UAAU;IACd;;OAEG;YACK,MAAM,EAAE,GAAG,SAAS;IAI5B;;OAEG;eACQ,MAAM,EAAE,EAAE;CAGrB,CAAC;eAEY,UAAU"}

package/dist/index.js

@@ -0,0 +1,29 @@
+import { Builder } from './builder.js';
+import { History } from './history.js';
+const history = new History();
+let reference = null;
+/**
+ * Initiates an iterable builder for generating pronounceable words.
+ * Omitting size generates mixed lengths.
+ */
+function generate(size, options) {
+    return new Builder(size, options, (generation) => {
+        history.add(generation);
+        reference = new WeakRef(generation);
+    });
+}
+const shortwords = Object.assign(generate, {
+    /**
+     * Returns a single array of words from the most recent run.
+     */
+    prev() {
+        return reference?.deref();
+    },
+    /**
+     * Returns multiple arrays of words, one for each run so far.
+     */
+    history() {
+        return history.getHistory();
+    }
+});
+export default shortwords;

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Character length constraints supported by the library.
+ */
+export type Size = 2 | 3 | 4;
+/**
+ * Valid syllable structures.
+ * 'C' represents a Consonant, and 'V' represents a Vowel.
+ */
+export type Pattern = 'CV' | 'VC' | 'CVC' | 'VCV' | 'CVV' | 'VVC' | 'CCV' | 'VCC' | 'CVCV' | 'VCVC' | 'CVVC' | 'VCCV' | 'CCVV' | 'VVCC' | 'CCVC' | 'CVCC';
+/**
+ * Single-call configuration parameters passed as an alternative to chaining.
+ */
+export interface Options {
+    /** The total number of words to generate. */
+    results?: number;
+    /** A strict Consonant/Vowel layout constraint. */
+    pattern?: Pattern;
+    /** When true, freezes the generated results from further alterations. */
+    lock?: boolean;
+}
+export declare const VOWELS: readonly ['a', 'e', 'i', 'o', 'u'];
+export declare const CONSONANTS: readonly ['b', 'c', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'm', 'n', 'p', 'q', 'r', 's', 't', 'v', 'w', 'x', 'y', 'z'];
+/**
+ * Syllable structures grouped by word size.
+ * Used when no explicit pattern is specified.
+ */
+export declare const DEFAULTS: Record<Size, Pattern[]>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE7B;;;GAGG;AACH,MAAM,MAAM,OAAO,GACf,IAAI,GACJ,IAAI,GACJ,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,eAAO,MAAM,MAAM,YAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAEzD,eAAO,MAAM,UAAU,YACrB,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,CACK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,CAI5C,CAAC"}

package/dist/types.js

@@ -0,0 +1,33 @@
+export const VOWELS = ['a', 'e', 'i', 'o', 'u'];
+export const CONSONANTS = [
+    'b',
+    'c',
+    'd',
+    'f',
+    'g',
+    'h',
+    'j',
+    'k',
+    'l',
+    'm',
+    'n',
+    'p',
+    'q',
+    'r',
+    's',
+    't',
+    'v',
+    'w',
+    'x',
+    'y',
+    'z'
+];
+/**
+ * Syllable structures grouped by word size.
+ * Used when no explicit pattern is specified.
+ */
+export const DEFAULTS = {
+    2: ['CV', 'VC'],
+    3: ['CVC', 'VCV', 'CVV', 'VVC', 'CCV', 'VCC'],
+    4: ['CVCV', 'VCVC', 'CVVC', 'VCCV', 'CCVV', 'VVCC', 'CCVC', 'CVCC']
+};

package/dist/utils.d.ts

@@ -0,0 +1,9 @@
+import { Size, Pattern } from './types.js';
+export declare class InternalError extends Error {
+    constructor(message: string);
+}
+/**
+ * Generates pronounceable 2, 3, and 4-letter English words.
+ */
+export declare function genWords(size: Size | undefined, pattern: Pattern | undefined, count: number): string[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAE,OAAO,EAA+B,MAAM,YAAY,CAAC;AAEvE,qBAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAuBD;;GAEG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,IAAI,GAAG,SAAS,EACtB,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,GACZ,MAAM,EAAE,CAoCV"}

package/dist/utils.js

@@ -0,0 +1,60 @@
+import { VOWELS, CONSONANTS, DEFAULTS } from './types.js';
+export class InternalError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InternalError';
+    }
+}
+function pickLetter(arr) {
+    if (!arr || arr.length === 0) {
+        throw new InternalError('Expected a non-empty array of letters.');
+    }
+    return arr[Math.floor(Math.random() * arr.length)];
+}
+function genPattern(pattern) {
+    let word = '';
+    for (const char of pattern.toUpperCase()) {
+        if (char === 'C') {
+            word += pickLetter(CONSONANTS);
+        }
+        else if (char === 'V') {
+            word += pickLetter(VOWELS);
+        }
+        else {
+            throw new InternalError(`Invalid structural token "${char}" in pattern.`);
+        }
+    }
+    return word;
+}
+/**
+ * Generates pronounceable 2, 3, and 4-letter English words.
+ */
+export function genWords(size, pattern, count) {
+    if (!Number.isInteger(count) || count < 0) {
+        throw new InternalError('Results count must be a non-negative integer.');
+    }
+    if (!pattern && size !== undefined && !(size in DEFAULTS)) {
+        throw new InternalError(`Invalid size "${size}". Expected 2, 3, or 4.`);
+    }
+    if (pattern) {
+        for (const char of pattern.toUpperCase()) {
+            if (char !== 'C' && char !== 'V') {
+                throw new InternalError(`Invalid structural token "${char}" in pattern.`);
+            }
+        }
+    }
+    const results = [];
+    for (let i = 0; i < count; i++) {
+        let activePattern;
+        if (pattern) {
+            activePattern = pattern;
+        }
+        else {
+            const activeSize = size || pickLetter([2, 3, 4]);
+            const availablePatterns = DEFAULTS[activeSize];
+            activePattern = pickLetter(availablePatterns);
+        }
+        results.push(genPattern(activePattern));
+    }
+    return results;
+}

package/gui/app.js

@@ -0,0 +1,43 @@
+import shortwords from "../dist/index.js";
+
+const lengthInput = document.getElementById("length");
+const patternInput = document.getElementById("pattern");
+const modeRadios = document.getElementsByName("mode");
+const generateBtn = document.getElementById("generate");
+const resultArea = document.getElementById("result");
+const copyBtn = document.getElementById("copy");
+const feedback = document.getElementById("feedback");
+
+generateBtn.addEventListener("click", () => {
+  const size = parseInt(lengthInput.value, 10);
+  const pattern = patternInput.value.trim().toUpperCase();
+  const mode = [...modeRadios].find(r => r.checked).value;
+
+  let results;
+  try {
+    if (mode === "mix") {
+      results = shortwords().mix().results(10);
+    } else if (pattern) {
+      if (pattern.length !== size) {
+        feedback.textContent = `Pattern "${pattern}" length (${pattern.length}) does not match size ${size}`;
+        resultArea.value = "";
+        return;
+      }
+      results = shortwords(size).pattern(pattern).results(10);
+    } else {
+      results = shortwords(size).results(10);
+    }
+    resultArea.value = [...results].join("\n");
+    feedback.textContent = "";
+  } catch (err) {
+    feedback.textContent = err.message;
+    resultArea.value = "";
+  }
+});
+
+copyBtn.addEventListener("click", () => {
+  resultArea.select();
+  document.execCommand("copy");
+  feedback.textContent = "Copied!";
+  setTimeout(() => feedback.textContent = "", 2000);
+});

package/gui/index.html

@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Shortwords GUI</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <nav class="navbar">
+    <div class="nav-left">
+      <h1>shortwords</h1>
+      <p class="tagline">Generate pronounceable short words</p>
+    </div>
+    <div class="nav-right">
+      <a href="https://www.npmjs.com/package/shortwords">npm</a>
+      <a href="https://github.com/timtjoe/shortwords">GitHub</a>
+      <a href="https://github.com/timtjoe/shortwords/issues/new">Create Issue</a>
+    </div>
+  </nav>
+
+  <main class="content">
+    <header class="toolbar">
+      <label>Length <input id="length" type="number" min="2" max="4" value="3"></label>
+      <label>Pattern <input id="pattern" list="patterns"></label>
+      <datalist id="patterns">
+        <option value="CVC">
+        <option value="VCV">
+        <option value="CVV">
+        <option value="CVCV">
+      </datalist>
+      <div class="radio-group">
+        <label><input type="radio" name="mode" value="random" checked> Random</label>
+        <label><input type="radio" name="mode" value="mix"> Mix</label>
+      </div>
+      <button id="generate">Generate</button>
+    </header>
+
+    <section class="output">
+      <h2>Output</h2>
+      <textarea id="result" readonly></textarea>
+      <button id="copy">Copy</button>
+      <span id="feedback" class="feedback"></span>
+    </section>
+  </main>
+
+  <footer class="footer">
+    <p>Author: <a href="https://github.com/timtjoe">Timothy T. Joe</a></p>
+    <p>&copy; <a href="https://opensource.org/licenses/MIT">MIT License</a></p>
+  </footer>
+
+  <script type="module" src="app.js"></script>
+</body>
+</html>

package/gui/style.css

@@ -0,0 +1,100 @@
+body {
+  margin: 0;
+  font-family: system-ui, sans-serif;
+  background: #fff;
+  color: #222;
+}
+
+.navbar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 12px 20px;
+  background: #111;
+  color: #fff;
+}
+
+.nav-left h1 {
+  margin: 0;
+  font-size: 20px;
+}
+
+.nav-left .tagline {
+  margin: 0;
+  font-size: 12px;
+  color: #aaa;
+}
+
+.nav-right a {
+  margin-left: 15px;
+  color: #4da3ff;
+  text-decoration: none;
+}
+
+.content {
+  max-width: 700px;
+  margin: 20px auto;
+  padding: 0 20px;
+}
+
+.toolbar {
+  display: flex;
+  gap: 12px;
+  flex-wrap: wrap;
+  background: #f5f5f5;
+  padding: 12px;
+  border-radius: 6px;
+}
+
+.toolbar label {
+  display: flex;
+  flex-direction: column;
+  font-size: 14px;
+}
+
+.radio-group {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+}
+
+button {
+  background: #007bff;
+  color: #fff;
+  border: none;
+  padding: 8px 14px;
+  cursor: pointer;
+  border-radius: 4px;
+}
+
+button:hover {
+  background: #0056b3;
+}
+
+.output {
+  margin-top: 20px;
+}
+
+textarea {
+  width: 100%;
+  height: 200px;
+  font-family: monospace;
+}
+
+.feedback {
+  margin-left: 10px;
+  color: green;
+  font-size: 14px;
+}
+
+.footer {
+  text-align: center;
+  padding: 20px;
+  background: #f5f5f5;
+  font-size: 14px;
+}
+
+.footer a {
+  color: #007bff;
+  text-decoration: none;
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "shortwords",
+  "version": "0.1.0",
+  "description": "This library generates pronounceable sets of 2, 3, and 4-letter English words based on a given pattern.",
+  "author": "Timothy T. Joe <timtjoe@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "bin": {
+    "shortwords": "./bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "gui",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://github.com/timtjoe/shortwords#readme",
+  "bugs": {
+    "url": "https://github.com/timtjoe/shortwords/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timtjoe/shortwords.git"
+  },
+  "engines": {
+    "node": ">=18",
+    "npm": ">=9"
+  },
+  "scripts": {
+    "build": "tsc --build --force",
+    "prepack": "npm run build",
+    "pack": "npm pack",
+    "test": "vitest run",
+    "test:types": "vitest --typecheck",
+    "format": "prettier --write .",
+    "lint": "prettier --check .",
+    "knip": "knip",
+    "release:patch": "npm version patch -m \"Release %s\" && npm publish --access public",
+    "release:minor": "npm version minor -m \"Release %s\" && npm publish --access public",
+    "release:major": "npm version major -m \"Release %s\" && npm publish --access public"
+  },
+  "keywords": [
+    "word generator",
+    "short words",
+    "english words",
+    "word pattern"
+  ],
+  "dependencies": {
+    "open": "^9.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "knip": "^6.27.0",
+    "prettier": "^3.9.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}