motely-wasm 17.4.3 → 17.4.4

package/README.md

@@ -11,87 +11,106 @@ npm install motely-wasm
 ## Quick start
 
 ```js
-import motely from "motely-wasm";
-import { Motely } from "motely-wasm/index";
-
-// Boot the runtime, pointing at wherever your package assets are served
-await motely.boot("/node_modules/motely-wasm");
-
-// Subscribe to results before starting
-Motely.onSeedMatch.subscribe(seed => console.log("match:", seed));
+import bootsharp, { Motely } from "motely-wasm";
+
+// Boot the .NET WASM runtime. The argument is the URL path to the package's
+// `bin/` directory (where dotnet.native.wasm is served from).
+await bootsharp.boot("/node_modules/motely-wasm/bin");
+
+// A JAML filter — see https://github.com/OptimusPi/MotelyJAML for the language.
+const jaml = `
+name: WeeMonday
+deck: Erratic
+stake: Black
+must:
+  - joker: WeeJoker
+    antes: [1]
+`;
+
+// Validate before searching — returns "valid" or an error message.
+const status = Motely.validateJaml(jaml);
+if (status !== "valid") throw new Error(status);
+
+// Subscribe to results before starting.
+Motely.onScoredResult.subscribe(r => console.log("match:", r.seed, r.score));
 Motely.onProgress.subscribe(p => console.log(`${p.percentComplete.toFixed(1)}%`));
 
-// Build and run a search
-const search = Motely.createSearch(`
-  ante-1:
-    jokers:
-      - Joker
-`).withSequentialSearch()
-  .createSearch();
+// Build, start, and await a search.
+const search = Motely.createSearch(jaml)
+  .withSequentialSearch()
+  .start();
 
-search.runSearchUntilCompletion();
+await search.waitForCompletionAsync();
+console.log("done:", search.totalSeedsSearched, "searched,", search.matchingSeeds, "matched");
 ```
 
 ## Booting
 
-`boot(resources, options?)` initializes the .NET WASM runtime. Call it once before any `Motely.*` API.
+`bootsharp.boot(binUrl)` initializes the .NET WASM runtime. Call it once before any
+`Motely.*` API. The argument is the URL path to the `bin/` directory that serves
+`dotnet.native.wasm` — e.g. `/node_modules/motely-wasm/bin`, or wherever your bundler
+copies the package's `bin/` folder.
 
 ```js
-import motely, { BootStatus } from "motely-wasm";
+import bootsharp, { BootStatus } from "motely-wasm";
 
-// From a URL base path (all .wasm / assembly files served from there)
-await motely.boot("/assets/motely-wasm");
+if (bootsharp.getStatus() === bootsharp.BootStatus.Standby) {
+  await bootsharp.boot("/node_modules/motely-wasm/bin");
+}
 
-// Check status
-console.log(motely.getStatus()); // BootStatus.Booted
+console.log(bootsharp.getStatus()); // BootStatus.Booted
 ```
 
 ## JAML API
 
 ```js
-import { Motely } from "motely-wasm/index";
+import { Motely } from "motely-wasm";
 
-// Validate a JAML filter string — returns "" on success, error message on failure
-const error = Motely.validateJaml(jaml);
+// Validate a JAML filter string — returns "valid" on success, an error message on failure.
+const status = Motely.validateJaml(jaml);
 
-// Get a human-readable explanation of what a JAML filter does
+// Human-readable explanation of what a JAML filter does.
 const explanation = Motely.explainJaml(jaml);
 
-// Inspect the search plan (tally column count, CSV header, labels)
+// Inspect the search plan (tally column count, CSV header, labels).
 const plan = Motely.createPlan(jaml);
 
-// Analyze specific seeds against a JAML filter
+// Analyze specific seeds against a JAML filter.
 const result = Motely.analyzeJamlSeeds(jaml, ["ABCD1234", "XYZ99"]);
 
-// Engine version string
+// Engine version string.
 console.log(Motely.version());
 ```
 
 ## Running a search
 
+`Motely.createSearch(jaml)` returns a settings builder. Chain a search-mode method,
+then call `.start()` to get a running `IMotelySearch`.
+
 ```js
-import { Motely } from "motely-wasm/index";
-import { MotelyDeck, MotelyStake } from "motely-wasm/motely";
+import { Motely } from "motely-wasm";
 
-Motely.onSeedMatch.subscribe(seed => { /* handle match */ });
-Motely.onScoredResult.subscribe(result => { /* result.seed, result.score, result.tallies */ });
-Motely.onProgress.subscribe(progress => { /* progress.percentComplete, .seedsPerMillisecond, … */ });
+Motely.onSeedMatch.subscribe(seed => { /* matching seed string */ });
+Motely.onScoredResult.subscribe(r => { /* r.seed, r.score, r.tallies */ });
+Motely.onProgress.subscribe(p => { /* p.percentComplete, p.seedsSearched, p.seedsPerMillisecond, … */ });
 
-const settings = Motely.createSearchSettings()
-  .withDeck(MotelyDeck.Red)
-  .withStake(MotelyStake.White)
+const settings = Motely.createSearch(jaml)
   .withSequentialSearch()          // enumerate all seeds in order
   // .withRandomSearch(10_000)     // or pick N random seeds
-  // .withListSearch(seeds, count) // or supply a seed list
+  // .withListSearch(seeds, seeds.length) // or supply a seed list
+  // .withAestheticSearch(0)       // or a JamlAesthetic mode
   .withProgressReportIntervalMs(500n);
 
-const search = settings.createSearch();
+const search = settings.start();
 
-// Synchronous (blocks until done — fine in a Worker)
-search.runSearchUntilCompletion();
+// Async (yields between batches — good on the main thread or in a Worker)
+await search.waitForCompletionAsync();
 
-// Async (yields between batches)
-await search.runSearchAsync(undefined);
+// or synchronous (blocks until done — only inside a Worker)
+// search.runSearchUntilCompletion();
+
+console.log(search.isCompleted, search.totalSeedsSearched, search.matchingSeeds);
+search.cancel(); // stop early
 ```
 
 ## Events
@@ -100,45 +119,93 @@ await search.runSearchAsync(undefined);
 |---|---|
 | `Motely.onSeedMatch` | `string` — matching seed |
 | `Motely.onScoredResult` | `{ seed, score, tallies }` |
-| `Motely.onProgress` | `MotelyProgress` |
-| `Motely.onFileChanges` | `FileSystem.Change[]` |
+| `Motely.onProgress` | `MotelyProgress` — `percentComplete`, `seedsSearched`, `matchingSeeds`, `seedsPerMillisecond`, `elapsedMilliseconds` |
+| `Motely.onFileChanges` | `Change[]` (browser file-system mounts) |
 
 Subscribe and unsubscribe:
 
 ```js
-const handler = seed => console.log(seed);
-Motely.onSeedMatch.subscribe(handler);
-Motely.onSeedMatch.unsubscribe(handler);
+const handler = r => console.log(r.seed);
+Motely.onScoredResult.subscribe(handler);
+Motely.onScoredResult.unsubscribe(handler);
 ```
 
 ## Submodule exports
 
 | Import path | Contents |
 |---|---|
-| `motely-wasm` | `boot`, `exit`, `getStatus`, `BootStatus`, `manifest` |
-| `motely-wasm/index` | `Motely` namespace (main API) |
-| `motely-wasm/motely` | Types: `MotelyDeck`, `MotelyStake`, `MotelyTag`, `MotelyVoucher`, `MotelyBossBlind`, `MotelyBoosterPack`, enums |
+| `motely-wasm` | Default export: `boot`, `getStatus`, `BootStatus`. Named export: `Motely` (main API) |
+| `motely-wasm/motely` | Types: `IMotelySearch`, `IMotelySearchSettingsInterop`, `MotelyProgress`, `MotelyScoredSeedResult`, `MotelyDeck`, `MotelyStake`, enums |
 | `motely-wasm/motely/filters` | `JamlAesthetic`, `JamlSearchPlan` |
-| `motely-wasm/motely/analysis` | `MotelyJamlyzerResult` |
-| `motely-wasm/bootsharp/file-system` | File system interop (browser OPFS) |
+| `motely-wasm/motely/analysis` | `MotelyJamlyzerResult`, `MotelySeedAnalysis` |
+| `motely-wasm/bootsharp/file-system` | File-system interop (browser OPFS) — `PermissionMode`, `IFileMounter` |
 
 ## Using in a Web Worker
 
-The WASM runtime is single-threaded. For non-blocking UI, run searches in a Worker:
+The WASM runtime is single-threaded. For a non-blocking UI, boot a runtime inside a
+Worker and drive it with messages. This mirrors the proven setup in the `jaml-ui`
+package's `searchWorker.ts`.
 
 ```js
-// worker.js
-import motely from "motely-wasm";
-import { Motely } from "motely-wasm/index";
-
-await motely.boot("/assets/motely-wasm");
+// search-worker.js
+import bootsharp, { Motely } from "motely-wasm";
 
-Motely.onSeedMatch.subscribe(seed => postMessage({ type: "match", seed }));
-Motely.onProgress.subscribe(p => postMessage({ type: "progress", p }));
+let currentSearch = null;
 
 self.onmessage = async ({ data }) => {
-  const search = Motely.createSearch(data.jaml).withSequentialSearch().createSearch();
-  await search.runSearchAsync(undefined);
-  postMessage({ type: "done" });
+  if (data.type === "stop") {
+    currentSearch?.cancel();
+    self.postMessage({ type: "cancelled" });
+    return;
+  }
+  if (data.type !== "start") return;
+
+  try {
+    if (bootsharp.getStatus() === bootsharp.BootStatus.Standby) {
+      await bootsharp.boot("/node_modules/motely-wasm/bin");
+    }
+
+    const onResult = r =>
+      self.postMessage({ type: "result", seed: r.seed, score: r.score });
+    const onProgress = p =>
+      self.postMessage({ type: "progress", percent: p.percentComplete });
+    Motely.onScoredResult.subscribe(onResult);
+    Motely.onProgress.subscribe(onProgress);
+
+    try {
+      currentSearch = Motely.createSearch(data.jaml)
+        .withThreadCount(1)
+        .withSequentialSearch()
+        .start();
+      await currentSearch.waitForCompletionAsync();
+      self.postMessage({
+        type: "complete",
+        total: Number(currentSearch.totalSeedsSearched),
+        matched: Number(currentSearch.matchingSeeds),
+      });
+    } finally {
+      Motely.onScoredResult.unsubscribe(onResult);
+      Motely.onProgress.unsubscribe(onProgress);
+      currentSearch = null;
+    }
+  } catch (error) {
+    self.postMessage({ type: "error", message: String(error?.message ?? error) });
+  }
+};
+
+self.postMessage({ type: "ready" });
+```
+
+```js
+// main thread
+const worker = new Worker(new URL("./search-worker.js", import.meta.url), { type: "module" });
+
+worker.onmessage = ({ data }) => {
+  if (data.type === "result") console.log("match:", data.seed, data.score);
+  if (data.type === "progress") console.log(`${data.percent.toFixed(1)}%`);
+  if (data.type === "complete") console.log("done:", data.total, data.matched);
 };
+
+worker.postMessage({ type: "start", jaml });
+// worker.postMessage({ type: "stop" }); // cancel early
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "motely-wasm",
-    "version": "17.4.3",
+    "version": "17.4.4",
     "type": "module",
     "exports": {
         ".": "./dist/index.mjs",