lettras 0.1.0 → 0.2.1

package/README.md

@@ -7,6 +7,8 @@ kept as one cell each. Runs locally (WebAssembly): no network, no API key. Libra
 npm install lettras
 ```
 
+[npm package](https://www.npmjs.com/package/lettras) · [source and docs](https://github.com/Artificialss/lettras-sdk)
+
 ```js
 import { generate, render } from 'lettras';
 
@@ -17,8 +19,16 @@ puzzle.placements;  // where each word is hidden: start (r, c), step (dr, dc), l
 puzzle.unplaced;    // words that did not fit
 ```
 
+```js
+import { generate, fill, render } from 'lettras';
+
+const puzzle = generate({ words: ['gato', 'perro', 'piña'], rows: 9, cols: 12, position: 'mixed', seed: 8 });
+const done = fill(puzzle, { lang: 'es', accents: true }); // random letters in the empty cells
+console.log(done.grid.map((row) => row.join(' ')).join('\n'));
+```
+
 ```bash
-npx lettras --words gato,perro,piña --rows 9 --cols 12 --position mixed
+npx lettras --words gato,perro,piña --rows 9 --cols 12 --position mixed --random --accents on
 ```
 
 ## Options
@@ -34,12 +44,67 @@ npx lettras --words gato,perro,piña --rows 9 --cols 12 --position mixed
 | `classicMode` | Strip accents in the grid. |
 | `fill` | Empty-cell character, default `-`. |
 
+`generate` leaves empty cells as `-`. **`fill(puzzleOrGrid, { lang, accents, seed })`** completes them: letters follow the
+language's letter frequency, `accents: false` limits them to A-Z, and without a `seed` every call is different. Passing the
+puzzle (instead of a bare matrix) also protects its words from accidental extra copies. CLI: `--random` and `--accents on|off`.
+
+**Example.** The same puzzle before and after `fill` (Spanish, seed 5):
+
+```js
+const puzzle = generate({ words: ['gato', 'perro', 'piña', 'mono', 'cebra'], rows: 8, cols: 10, position: 'mixed', seed: 8 });
+const done = fill(puzzle, { lang: 'es', accents: true, seed: 5 });
+```
+
+`puzzle.grid` has `-` in every empty cell; `done.grid` replaces them (58 cells here):
+
+```
+C E B R A - O - - -
+- - - - - - - T O -
+- - - - M - - R A -
+- - - O - - R - - G
+- - N - - E - - - -
+- O - - P - - - - -
+- - - - - - - - - -
+- - - - - - A Ñ I P
+```
+```
+C E B R A R O G G J
+D R A E E R C T O D
+B Ó E E M Í M R A Ñ
+T S C O N R R A E G
+T R N E A E R O E M
+I O O E P S N P A O
+O C O O A P P A U A
+I R E A A S A Ñ I P
+```
+
+With `accents: false` the filler uses plain A-Z only (the one `Ñ` left is the hidden word *piña*, which keeps its spelling):
+
+```
+C E B R A R O G G I
+D Q A E E P C T O D
+B Y E E M X M R A N
+S R C O N R R A E G
+S R N E A E R O E M
+I O O E P S N O A O
+O B O O A P O A T A
+H R E A A S A Ñ I P
+```
+
+Same grid, language, accents and `seed` always give the same filler on every platform. Without a `seed` the wrappers
+pick a random one, so every call gives different letters.
+
 CLI flags mirror these: `--words a,b,c --rows N --cols N --position P --difficulty N --clustering N --seed N --lang xx
 --classic --fill C`, plus `--json`, `--solution` and `--stdin`.
 
 `generate` throws on invalid input (for example zero rows). Words that cannot be placed are listed in `unplaced`;
 words that are refused (spaces, digits, duplicates) are listed in `rejected` with a reason.
 
+## Module format
+
+The package is ESM only: use `import { generate, fill } from 'lettras'`. From CommonJS use `const { generate } = await import('lettras')`.
+It needs Node 20 or newer (or any modern browser bundler) and ships its own TypeScript types.
+
 ## License
 
 Wrapper, CLI and types: MIT. The compiled engine in `engine/` is proprietary: use it unmodified through this package;

package/bin/lettras.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 // lettras --words sol,luna,mar --rows 8 --cols 8 [--position horizontal|vertical|mixed] [--seed 7]
-//         [--difficulty 1-4] [--clustering 0-1] [--lang es] [--classic] [--fill -] [--json] [--solution]
+//         [--difficulty 1-4] [--clustering 0-1] [--lang es] [--classic] [--fill -] [--random] [--accents on|off]
+//         [--json] [--solution]
 // or:     echo '{"words":["sol"],"rows":6,"cols":6}' | lettras --stdin
 import { readFileSync } from 'node:fs';
 import { generate, renderPuzzle } from '../engine/index.js';
+import { fill } from '../src/index.js';
 
 const HELP = `lettras: word-search generator
 
@@ -18,12 +20,14 @@ const HELP = `lettras: word-search generator
   --lang xx            es en pt fr de it
   --classic            strip accents in the grid
   --fill C             empty-cell character (default -)
+  --random             fill the empty cells with random letters
+  --accents on|off     with --random: use the language's accented letters (default on; off with --classic)
   --json               print the JSON result
   --solution           show only the hidden words
   --stdin              read the JSON input from stdin`;
 
 function parse(argv) {
-  const flags = new Set(['classic', 'json', 'solution', 'stdin', 'help']);
+  const flags = new Set(['classic', 'json', 'solution', 'stdin', 'help', 'random']);
   const opts = {};
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -57,9 +61,16 @@ function main() {
     if (o.classic) input.classicMode = true;
     if (o.fill) input.fill = o.fill;
   }
-  const outJson = generate(JSON.stringify(input));
+  let outJson = generate(JSON.stringify(input));
+  let out = JSON.parse(outJson);
+  if (o.random) {
+    if (o.accents !== undefined && !['on', 'off'].includes(o.accents)) throw new Error('--accents must be on or off');
+    const accents = o.accents ? o.accents === 'on' : !input.classicMode;
+    const filled = fill(out, { lang: input.lang, accents, seed: input.seed });
+    out = { ...out, grid: filled.grid };
+    outJson = JSON.stringify(out);
+  }
   if (o.json) return console.log(outJson);
-  const out = JSON.parse(outJson);
   if (o.solution) {
     const hidden = new Set(out.placements.flatMap((p) => Array.from({ length: p.length }, (_, i) => `${p.r + p.dr * i},${p.c + p.dc * i}`)));
     return console.log(out.grid.map((row, r) => row.map((ch, c) => (hidden.has(`${r},${c}`) ? ch : '·')).join(' ')).join('\n'));