motely-wasm 18.2.1 → 18.2.3

package/README.md

@@ -34,14 +34,11 @@ must:
 const status = Motely.validateJaml(jaml);
 if (status !== "valid") throw new Error(status);
 
-// Subscribe to results before starting.
+// One callback set per WASM load — subscribe after boot, before .start().
 Motely.onScoredResult.subscribe(r => console.log("match:", r.seed, r.score));
 Motely.onProgress.subscribe(p => console.log(`${p.percentComplete.toFixed(1)}%`));
 
-// Build, start, and await a search.
-const search = Motely.createSearch(jaml)
-  .withSequentialSearch()
-  .start();
+const search = Motely.fromJaml(jaml).withSequentialSearch().start();
 
 await search.waitForCompletionAsync();
 console.log("done:", search.totalSeedsSearched, "searched,", search.matchingSeeds, "matched");
@@ -61,9 +58,7 @@ Pass the URL path your host serves the package's `bin/` directory at (where
 | --- | --- | --- |
 | Vite / Storybook `staticDirs` | `/motely-wasm/bin` | `boot("/motely-wasm/bin")` |
 | Next.js route handler | `/motely-wasm/bin/[...path]` | `boot("/motely-wasm/bin")` |
-| Static page in `node_modules/motely-wasm/` | `/bin` | `boot("/bin")` |
-| Raw node_modules served as static | `/node_modules/motely-wasm/bin` | `boot("/node_modules/motely-wasm/bin")` |
-| Public CDN | `https://unpkg.com/motely-wasm/bin` | `boot("https://unpkg.com/motely-wasm/bin")` |
+| Public CDN (pinned version) | `https://unpkg.com/motely-wasm@<version>/bin` | `boot("https://unpkg.com/motely-wasm@18.2.2/bin")` |
 
 Web Workers must boot from the **same** URL as the main thread — absolute paths
 in a worker resolve against the page origin, so whichever URL serves the WASM
@@ -81,29 +76,23 @@ console.log(bootsharp.getStatus()); // BootStatus.Booted
 
 ### Node / Bun / Deno
 
-There's no URL to fetch from — read `dotnet.native.wasm` off disk and hand its
-bytes to `boot`:
+Same ESM import as the browser. Point `boot()` at the published `bin/` directory
+(Node `fetch` accepts `file://` URLs):
 
 ```js
-import { readFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
-import bootsharp from "motely-wasm";
+import bootsharp, { Motely } from "motely-wasm";
 
-const wasmUrl = new URL("../bin/dotnet.native.wasm", import.meta.resolve("motely-wasm"));
-const wasmBytes = await readFile(fileURLToPath(wasmUrl));
+const binRoot = new URL("bin/", import.meta.resolve("motely-wasm/package.json")).href;
+await bootsharp.boot(binRoot);
 
-await bootsharp.boot({
-  wasm: wasmBytes.buffer.slice(
-    wasmBytes.byteOffset,
-    wasmBytes.byteOffset + wasmBytes.byteLength
-  ),
-});
+const status = Motely.validateJaml(jaml);
 ```
 
-Requires Node ≥ 20.6 (sync `import.meta.resolve`). Node 22 LTS is the recommended floor.
+Requires Node ≥ 20.6 (`import.meta.resolve`). Node 22 LTS is the recommended floor.
 
-`Motely.Wasm/motely.test.mjs` in the source repo is the executable reference for
-this path — if Node boot breaks, that suite catches it first.
+**Publish gate (repo):** after `dotnet publish Motely.Wasm -c Release`, run
+`node Motely.Wasm/motely.test.mjs` and `node Motely.Wasm/pack-consumer-smoke.mjs`
+(`npm pack` → fresh `npm install` → same boot path).
 
 ## JAML API
 
@@ -182,24 +171,17 @@ returns a human-readable plan; `Motely.createPlan(jaml)` returns the scoring str
 
 ## Running a search
 
-`Motely.createSearch(jaml)` returns a settings builder. Chain a search-mode method,
-then call `.start()` to get a running `IMotelySearch`.
+Use `Motely.createSearchSettings()`, `Motely.createNativeSearchSettings(name)`, or
+`Motely.fromJaml(jaml)` — then chain modes. Callbacks are registered once per WASM load on `Motely`.
 
 ```js
 import { Motely } from "motely-wasm";
 
-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, … */ });
+Motely.onSeedMatch.subscribe(seed => { /* … */ });
+Motely.onScoredResult.subscribe(r => { /* … */ });
+Motely.onProgress.subscribe(p => { /* … */ });
 
-const settings = Motely.createSearch(jaml)
-  .withSequentialSearch()          // enumerate all seeds in order
-  // .withRandomSearch(10_000)     // or pick N random seeds
-  // .withListSearch(seeds, seeds.length) // or supply a seed list
-  // .withAestheticSearch(0)       // or a JamlAesthetic mode
-  .withProgressReportIntervalMs(500n);
-
-const search = settings.start();
+const search = Motely.fromJaml(jaml).withSequentialSearch().start();
 
 // Async (yields between batches — good on the main thread or in a Worker)
 await search.waitForCompletionAsync();
@@ -281,6 +263,10 @@ forward-lookup by name. `MotelyStreamKind` lives at `motely-wasm/motely`.
 
 ## Events
 
+Callbacks are registered on `Motely` once per `bootsharp.boot()` — not on each settings
+chain. Every search started from that WASM load shares the same handlers; run one search at
+a time or use separate worker boots if you need isolated callbacks.
+
 | Event | Payload |
 |---|---|
 | `Motely.onSeedMatch` | `string` — matching seed |
@@ -301,7 +287,7 @@ Motely.onScoredResult.unsubscribe(handler);
 | Import path | Contents |
 |---|---|
 | `motely-wasm` | Default export: `boot`, `getStatus`, `BootStatus`. Named export: `Motely` (main API) |
-| `motely-wasm/motely` | `IMotelySearch`, `IMotelySearchSettingsInterop`, `IMotelyStreamCursor`, `MotelyProgress`, `MotelyScoredSeedResult`, `MotelyStreamKind` |
+| `motely-wasm/motely` | `IMotelySearch`, `SearchSettings`, `IMotelyStreamCursor`, `MotelyProgress`, `MotelyScoredSeedResult`, `MotelyStreamKind` |
 | `motely-wasm/motely/enums` | All Balatro enums — `MotelyItemType`, `MotelyItemTypeCategory`, `MotelyJokerRarity`, `MotelyItemEdition`, `MotelyItemSeal`, `MotelyItemEnhancement`, `MotelyTag`, `MotelyVoucher`, `MotelyBoosterPack`, `MotelyDeck`, `MotelyStake`, `MotelyBossBlind`, etc. |
 | `motely-wasm/motely/filters` | `JamlAesthetic`, `JamlSearchPlan` |
 | `motely-wasm/motely/analysis` | `MotelyJamlyzerResult`, `MotelySeedAnalysis` |

package/dist/bcl/cancellation.d.mts

@@ -0,0 +1,14 @@
+import { Event } from "./event.mjs";
+/** JavaScript counterpart of the C# <c>System.Threading.CancellationToken</c> specialization.
+ *  Hand-rolled instances are constructed in user code and passed across the interop boundary;
+ *  instances received from C# are wrapped into generated proxies that expose the same shape. */
+export declare class CancellationToken {
+    private cancelled;
+    /** Fires when the token is cancelled. */
+    readonly onCancellationRequested: Event<[]>;
+    /** Whether cancellation has been requested. */
+    get isCancellationRequested(): boolean;
+    /** Signal cancellation: flips <see cref="isCancellationRequested"/> and broadcasts
+     *  <see cref="onCancellationRequested"/>. Idempotent. */
+    cancel(): void;
+}

package/dist/bcl/cancellation.mjs

@@ -0,0 +1,21 @@
+import { Event } from "./event.mjs";
+/** JavaScript counterpart of the C# <c>System.Threading.CancellationToken</c> specialization.
+ *  Hand-rolled instances are constructed in user code and passed across the interop boundary;
+ *  instances received from C# are wrapped into generated proxies that expose the same shape. */
+export class CancellationToken {
+    cancelled = false;
+    /** Fires when the token is cancelled. */
+    onCancellationRequested = new Event();
+    /** Whether cancellation has been requested. */
+    get isCancellationRequested() {
+        return this.cancelled;
+    }
+    /** Signal cancellation: flips <see cref="isCancellationRequested"/> and broadcasts
+     *  <see cref="onCancellationRequested"/>. Idempotent. */
+    cancel() {
+        if (this.cancelled)
+            return;
+        this.cancelled = true;
+        this.onCancellationRequested.broadcast();
+    }
+}

package/dist/bcl/collection.d.mts

@@ -0,0 +1,22 @@
+/** JavaScript counterpart of the C# <c>Bootsharp.Collection&lt;T&gt;</c> specialization of
+ *  <c>System.Collections.Generic.ICollection&lt;T&gt;</c>. Hand-rolled instances are constructed in
+ *  user code and passed across the interop boundary; instances received from C# are wrapped into
+ *  generated proxies that expose the same shape. */
+export declare class Collection<T> {
+    private readonly items;
+    constructor(items?: Iterable<T>);
+    /** Number of items in the collection. */
+    get count(): number;
+    /** Adds the specified item to the collection. */
+    add(item: T): void;
+    /** Removes the first occurrence of the specified item from the collection.
+     *  @returns true when the item was removed; false when it wasn't found. */
+    remove(item: T): boolean;
+    /** Removes all items from the collection. */
+    clear(): void;
+    /** Whether the collection contains the specified item. */
+    contains(item: T): boolean;
+    /** Returns a fresh array with a snapshot of the current items. */
+    copy(): T[];
+    [Symbol.iterator](): IterableIterator<T>;
+}

package/dist/bcl/collection.mjs

@@ -0,0 +1,42 @@
+/** JavaScript counterpart of the C# <c>Bootsharp.Collection&lt;T&gt;</c> specialization of
+ *  <c>System.Collections.Generic.ICollection&lt;T&gt;</c>. Hand-rolled instances are constructed in
+ *  user code and passed across the interop boundary; instances received from C# are wrapped into
+ *  generated proxies that expose the same shape. */
+export class Collection {
+    items;
+    constructor(items) {
+        this.items = items != null ? Array.from(items) : [];
+    }
+    /** Number of items in the collection. */
+    get count() {
+        return this.items.length;
+    }
+    /** Adds the specified item to the collection. */
+    add(item) {
+        this.items.push(item);
+    }
+    /** Removes the first occurrence of the specified item from the collection.
+     *  @returns true when the item was removed; false when it wasn't found. */
+    remove(item) {
+        const idx = this.items.indexOf(item);
+        if (idx < 0)
+            return false;
+        this.items.splice(idx, 1);
+        return true;
+    }
+    /** Removes all items from the collection. */
+    clear() {
+        this.items.length = 0;
+    }
+    /** Whether the collection contains the specified item. */
+    contains(item) {
+        return this.items.indexOf(item) >= 0;
+    }
+    /** Returns a fresh array with a snapshot of the current items. */
+    copy() {
+        return this.items.slice();
+    }
+    [Symbol.iterator]() {
+        return this.copy()[Symbol.iterator]();
+    }
+}

package/dist/bcl/index.d.mts

@@ -0,0 +1,3 @@
+export * from "./event.mjs";
+export * from "./collection.mjs";
+export * from "./cancellation.mjs";

package/dist/bcl/index.mjs

@@ -0,0 +1,3 @@
+export * from "./event.mjs";
+export * from "./collection.mjs";
+export * from "./cancellation.mjs";

package/dist/boot.d.mts

@@ -24,11 +24,11 @@ export type BootOptions = {
 };
 /** Returns current runtime module lifecycle state. */
 export declare function getStatus(): BootStatus;
-/** Initializes the runtime and binds C# APIs.
+/** Initializes the runtime. When not in embedded mode, resources parameter has to be specified.
  *  @param resources Either URL to the boot resources root (eg, <code>/bin</code>) or the preloaded content.
  *  @param options Allows customizing the boot process and the runtime behaviour.
  *  @return Promise that resolves into the runtime instance when the initialization is finished. */
-export declare function boot(resources: string | BootResources, options?: BootOptions): Promise<RuntimeAPI>;
+export declare function boot(resources?: string | BootResources, options?: BootOptions): Promise<RuntimeAPI>;
 /** Terminates the runtime and removes WASM module from memory.
  *  @param code Exit code; will use 0 (normal exit) by default.
  *  @param reason Exit reason description (optional). */

package/dist/boot.mjs

@@ -19,7 +19,7 @@ let status = BootStatus.Standby;
 export function getStatus() {
     return status;
 }
-/** Initializes the runtime and binds C# APIs.
+/** Initializes the runtime. When not in embedded mode, resources parameter has to be specified.
  *  @param resources Either URL to the boot resources root (eg, <code>/bin</code>) or the preloaded content.
  *  @param options Allows customizing the boot process and the runtime behaviour.
  *  @return Promise that resolves into the runtime instance when the initialization is finished. */
@@ -37,7 +37,7 @@ export async function boot(resources, options) {
  *  @param code Exit code; will use 0 (normal exit) by default.
  *  @param reason Exit reason description (optional). */
 export async function exit(code, reason) {
-    /* v8 ignore start -- @preserve */ // Uncoverable, as exit terminates the host test process.
+    /* v8 ignore start -- uncoverable, as exit terminates the host test process */
     if (status !== BootStatus.Booted)
         throw Error("Failed to exit the C# runtime: not booted.");
     try {
@@ -47,10 +47,10 @@ export async function exit(code, reason) {
     finally {
         status = BootStatus.Standby;
     }
-    /* v8 ignore stop -- @preserve */
+    /* v8 ignore stop */
 }
 async function createRuntime(res, opt) {
-    const cfg = opt.config ?? buildConfig(typeof res === "string" ? await fetchResources(res) : res);
+    const cfg = opt.config ?? buildConfig(typeof res === "object" ? res : await fetchResources(res));
     const runtime = await opt.create?.(cfg) || await app.dotnet.withConfig(cfg).create();
     setRuntime(runtime);
     if (opt.import)

package/dist/config.mjs

@@ -21,11 +21,12 @@ export function buildConfig(resources) {
         return { name, moduleExports: exports };
     }
     function resolveAsset(res) {
-        return { name: res.name, virtualPath: res.name, buffer: res.content };
+        const buffer = resolveBinary(res.content);
+        return { name: res.name, virtualPath: res.name, buffer };
     }
     function resolveSymbols(res) {
         // Use 'resolveAsset<SymbolsAsset>()' once https://github.com/dotnet/runtime/pull/127087 is merged.
-        const txt = new TextDecoder("utf-8").decode(res.content);
+        const txt = new TextDecoder("utf-8").decode(resolveBinary(res.content));
         return {
             name: res.name,
             pendingDownload: {
@@ -42,4 +43,9 @@ export function buildConfig(resources) {
             return "all";
         return "sharded";
     }
+    function resolveBinary(content) {
+        if (typeof content !== "string")
+            return content;
+        return Uint8Array.fromBase64(content).buffer;
+    }
 }