lettras 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Artificialss
+
+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.
+
+EXCEPTION: This license does NOT cover the compiled Lettras engine in `npm/engine/`.
+That directory is proprietary and is governed solely by `engine/LICENSE`.
+
+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.
+
+----------------------------------------------------------------------------------------
+The compiled engine in `engine/` is NOT MIT. See `engine/LICENSE`.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# lettras
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Word-search generator for **Spanish, English, Portuguese, French, German and Italian**, with native accented letters
+kept as one cell each. Runs locally (WebAssembly): no network, no API key. Library and CLI.
+
+```bash
+npm install lettras
+```
+
+```js
+import { generate, render } from 'lettras';
+
+const puzzle = generate({ words: ['gato', 'perro', 'piña'], rows: 9, cols: 12, position: 'mixed', seed: 8 });
+console.log(render(puzzle));
+puzzle.grid;        // string[][], one letter per cell, '-' for empty cells
+puzzle.placements;  // where each word is hidden: start (r, c), step (dr, dc), length
+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 --random --accents on
+```
+
+## Options
+
+| Option | Values |
+| --- | --- |
+| `words`, `rows`, `cols` | Word list and grid size (rectangular grids are fine). |
+| `position` | `horizontal`, `vertical` or `mixed` (all 8 directions). |
+| `difficulty` | 1–4, used when `position` is not set. |
+| `clustering` | 0 words apart · 1 words crossing · default 0.5. |
+| `seed` | Same input and seed give the same grid. |
+| `lang` | `es` (default) `en` `pt` `fr` `de` `it`. |
+| `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`.
+
+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.
+
+## License
+
+Wrapper, CLI and types: MIT. The compiled engine in `engine/` is proprietary: use it unmodified through this package;
+see `engine/LICENSE`. Source and issues: <https://github.com/Artificialss/lettras-sdk>.

package/bin/lettras.js

@@ -0,0 +1,81 @@
+#!/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 -] [--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
+
+  lettras --words sol,luna,mar --rows 8 --cols 8 [options]
+
+  --words a,b,c        word bank (comma separated)
+  --rows N --cols N    grid size (rectangular allowed)
+  --position P         horizontal | vertical | mixed (mixed = all 8 directions)
+  --difficulty 1-4     directions when --position is not set
+  --clustering 0-1     0 = words apart, 1 = words crossing (default 0.5)
+  --seed N             same seed, same grid
+  --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', 'random']);
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) throw new Error(`unexpected argument: ${a}`);
+    const key = a.slice(2);
+    if (flags.has(key)) opts[key] = true;
+    else if (i + 1 < argv.length) opts[key] = argv[++i];
+    else throw new Error(`missing value for --${key}`);
+  }
+  return opts;
+}
+
+function main() {
+  const o = parse(process.argv.slice(2));
+  if (o.help) return console.log(HELP);
+  let input;
+  if (o.stdin) {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } else {
+    if (!o.words || !o.rows) { console.log(HELP); process.exit(o.words || o.rows ? 2 : 0); }
+    input = {
+      words: o.words.split(',').map((w) => w.trim()).filter(Boolean),
+      rows: Number(o.rows),
+      cols: Number(o.cols ?? o.rows),
+    };
+    if (o.position) input.position = o.position;
+    if (o.difficulty) input.difficulty = Number(o.difficulty);
+    if (o.clustering) input.clustering = Number(o.clustering);
+    if (o.seed) input.seed = Number(o.seed);
+    if (o.lang) input.lang = o.lang;
+    if (o.classic) input.classicMode = true;
+    if (o.fill) input.fill = o.fill;
+  }
+  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);
+  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'));
+  }
+  console.log(renderPuzzle(outJson));
+}
+
+try { main(); } catch (e) { console.error(`lettras: ${e.message ?? e}`); process.exit(1); }

package/engine/LICENSE

@@ -0,0 +1,19 @@
+Lettras compiled engine: proprietary license
+
+Copyright (c) 2026 Artificialss. All rights reserved.
+
+This directory contains the compiled Lettras word-search engine (WebAssembly and the
+generated loader code). It is NOT covered by the MIT license that applies to the rest of
+this repository.
+
+You may use this engine, unmodified and only as distributed in the `lettras` npm package
+or this repository, to generate puzzles in your own applications, including commercial
+ones, free of charge.
+
+You may not, without written permission from Artificialss:
+  - copy, extract or redistribute the engine separately from the `lettras` package;
+  - modify it, or create derivative works of it;
+  - decompile, disassemble or otherwise attempt to derive its source code or algorithm;
+  - use it to build a competing puzzle-generation service or library.
+
+THE ENGINE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/engine/index.d.ts

@@ -0,0 +1 @@
+export * from './lettras_engine.js';