lettras 0.1.0 → 0.2.0

package/engine/lettras_engine.d.ts

@@ -15,6 +15,21 @@ export interface GenerateInput {
     fill?: string;
 }
 export interface Placement { word: string; r: number; c: number; dr: number; dc: number; length: number }
+export interface FillInput {
+    grid: string[][];
+    lang?: string;
+    accents?: boolean;
+    seed?: number;
+    empty?: string;
+    words?: string[];
+}
+export interface FillOutput {
+    grid: string[][];
+    filled: number;
+    seed: number;
+    ambiguous: string[];
+    engineVersion: string;
+}
 export interface GenerateOutput {
     grid: string[][];
     placements: Placement[];
@@ -27,6 +42,11 @@ export interface GenerateOutput {
 
 
 
+/**
+ * `fill(inputJson) -> outputJson`: random letters for the empty cells of a grid. Throws on invalid input.
+ */
+export function fill(input_json: string): string;
+
 /**
  * `generate(inputJson) -> outputJson`. Throws on invalid input.
  */
@@ -41,6 +61,7 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly fill: (a: number, b: number, c: number) => void;
     readonly generate: (a: number, b: number, c: number) => void;
     readonly renderPuzzle: (a: number, b: number, c: number) => void;
     readonly __wbindgen_add_to_stack_pointer: (a: number) => number;

package/engine/lettras_engine.js

@@ -1,5 +1,37 @@
 /* @ts-self-types="./lettras_engine.d.ts" */
 
+/**
+ * `fill(inputJson) -> outputJson`: random letters for the empty cells of a grid. Throws on invalid input.
+ * @param {string} input_json
+ * @returns {string}
+ */
+export function fill(input_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(input_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.fill(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr2 = r0;
+        var len2 = r1;
+        if (r3) {
+            ptr2 = 0; len2 = 0;
+            throw takeObject(r2);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * `generate(inputJson) -> outputJson`. Throws on invalid input.
  * @param {string} input_json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lettras",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Word-search generator for 6 languages with native accented letters (es, en, pt, fr, de, it). Runs locally via WebAssembly. Library and CLI.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.d.ts

@@ -1,9 +1,21 @@
-import type { GenerateInput, GenerateOutput, Placement, Position } from '../engine/index.js';
+import type { FillInput, FillOutput, GenerateInput, GenerateOutput, Placement, Position } from '../engine/index.js';
 
-export type { GenerateInput, GenerateOutput, Placement, Position };
+export type { FillInput, FillOutput, GenerateInput, GenerateOutput, Placement, Position };
+
+/** Options for {@link fill}: everything in {@link FillInput} except the grid. */
+export type FillOptions = Omit<FillInput, 'grid'>;
 
 /** Generate a word-search puzzle locally (WebAssembly). Same input and seed give the same grid. */
 export function generate(input: GenerateInput): GenerateOutput;
 
+/**
+ * Fill the empty cells with random letters, in the given language, with accents on or off.
+ * Pass the puzzle from `generate()` to protect its words from accidental copies. Without a `seed` the
+ * filler is different every call.
+ */
+export function fill(puzzle: GenerateOutput, options?: FillOptions): FillOutput;
+export function fill(grid: string[][], options?: FillOptions): FillOutput;
+export function fill(input: FillInput, options?: FillOptions): FillOutput;
+
 /** Plain-text view of a puzzle (grid and word bank). */
 export function render(output: GenerateOutput): string;

package/src/index.js

@@ -1,8 +1,9 @@
-import { generate as generateRaw, renderPuzzle as renderRaw } from '../engine/index.js';
+import { generate as generateRaw, fill as fillRaw, renderPuzzle as renderRaw } from '../engine/index.js';
 
 /**
  * Generate a word-search puzzle. Runs locally (WebAssembly), no network needed.
- * Deterministic: the same input and seed give the same grid.
+ * Deterministic: the same input and seed give the same grid. Empty cells hold `-` (or `fill`);
+ * pass the result to `fill()` to complete it with random letters.
  * @param {import('../engine/index.js').GenerateInput} input
  * @returns {import('../engine/index.js').GenerateOutput}
  */
@@ -10,6 +11,31 @@ export function generate(input) {
   return JSON.parse(generateRaw(JSON.stringify(input)));
 }
 
+function randomSeed() {
+  return globalThis.crypto.getRandomValues(new Uint32Array(1))[0];
+}
+
+/**
+ * Fill the empty cells of a grid with random letters.
+ *
+ * Pass the puzzle from `generate()` (its hidden words are then protected from accidental copies), or just a
+ * matrix. Letters follow the language's letter frequency; `accents: false` limits them to A-Z. Without a `seed`
+ * the filler is different every call; with one it is repeatable.
+ *
+ * @param {string[][] | import('../engine/index.js').GenerateOutput | import('../engine/index.js').FillInput} source
+ * @param {Omit<import('../engine/index.js').FillInput, 'grid'>} [options]
+ * @returns {import('../engine/index.js').FillOutput}
+ */
+export function fill(source, options = {}) {
+  let base;
+  if (Array.isArray(source)) base = { grid: source };
+  else if ('placements' in source) base = { grid: source.grid, words: source.words }; // a puzzle: keep its own seed out of it
+  else base = { ...source };
+  const input = { ...base, ...options };
+  if (input.seed === undefined) input.seed = randomSeed();
+  return JSON.parse(fillRaw(JSON.stringify(input)));
+}
+
 /**
  * Plain-text view of a puzzle (grid and word bank), for terminals and logs.
  * @param {import('../engine/index.js').GenerateOutput} output