motely-wasm 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) OptimusPi
+
+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.
+
+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.

package/README.md

@@ -1,26 +1,368 @@
-# Motely.WASM
+# motely-wasm
 
-MotelyJAML WebAssembly build.
+**Browser-only** Balatro seed analyzer and searcher — WebAssembly (SIMD + optional multi-threading). Analyze a seed or search seeds with a JAML filter. No server required.
 
-## Dev
+---
+
+## Quick start (TypeScript website, out of the box)
 
 ```bash
-npm run dev
+npm install motely-wasm
+```
+
+That’s it. The package copies its WASM build to `public/motely-wasm` on install (postinstall). Your app must serve that folder as static files (e.g. `public/` in Vite/Next/CRA). To use a different path: `npx motely-wasm-prepare public/your-path`.
+
+In your TypeScript code:
+
+```typescript
+import { loadMotely } from 'motely-wasm';
+import type { MotelyWasmApi, SeedAnalysisResult, ErrorResult } from 'motely-wasm';
+
+// Load the API (path = where you served the WASM, default /motely-wasm)
+const api: MotelyWasmApi = await loadMotely('/motely-wasm');
+
+const json = await api.AnalyzeSeed('TACO1111', 'Red', 'White', 1, 8, '{}');
+const result = JSON.parse(json) as SeedAnalysisResult | ErrorResult;
+if ('error' in result) {
+  console.error(result.error);
+} else {
+  console.log(result.seed, result.antes);
+}
 ```
-Opens http://localhost:3333
 
-## API
+Types resolve automatically; no extra config. For multi-threading, your server must send [COOP/COEP headers](#multi-threading-coopcoep) (see below).
+
+### Optional: DuckDB-WASM results storage
+
+If you want browser-side persistence of search results, initialize DuckDB-WASM before running a search:
+
+```typescript
+import { loadMotely, initDuckDbWasmResults } from 'motely-wasm';
+
+await initDuckDbWasmResults({ tableName: 'motely_results' });
+const api = await loadMotely('/motely-wasm');
+
+// Now SearchSeeds will also stream results into DuckDB-WASM
+await api.SearchSeeds(jamlJson, null, 4, 1000);
+```
+
+`initDuckDbWasmResults` hooks into `globalThis.MotelyWasmOnResult` and streams each result into DuckDB-WASM.
+
+---
+
+## Setup (other workflows)
+
+Copy runs automatically on `npm install`. To copy again or to a different path:
+
+```bash
+npx motely-wasm-prepare
+# or
+npx motely-wasm-prepare public/my-wasm
+```
+
+Or use `require('motely-wasm').getDistPath()` in your own build step.
+
+**Docs:** [Next.js](docs/NEXTJS_INTEGRATION.md)
+
+---
+
+## Installation
+
+```bash
+npm install motely-wasm
+```
+
+## Load the API in the browser (no bundler)
+
+If you're not using a bundler, load the runtime directly from your public path:
 
 ```js
-await MotelyWasm.AnalyzeSeed(seed, deck, stake, minAnte, maxAnte, optionsJson)
-await MotelyWasm.SearchSeeds(jamlJson, seedList, threads)
-await MotelyWasm.ValidateJaml(jamlString)
+const { dotnet } = await import('/motely-wasm/_framework/dotnet.js');
+const { getAssemblyExports, getConfig } = await dotnet.create();
+const exports = await getAssemblyExports(getConfig().mainAssemblyName);
+const api = exports.Motely.WASM.MotelyWasm;
+
+const result = await api.AnalyzeSeed("TACO1111", "Red", "White", 1, 8, "{}");
+console.log(JSON.parse(result));
+```
+
+### Multi-threading (COOP/COEP)
+
+Your server MUST send these headers for WASM multi-threading to work:
+
+```
+Cross-Origin-Embedder-Policy: require-corp
+Cross-Origin-Opener-Policy: same-origin
+```
+
+Without these headers, the WASM will still load but run single-threaded.
+
+**Other frameworks:** Run `npx motely-wasm-prepare` or use `getDistPath()` in your own script so your app can serve the WASM; then load `/motely-wasm/_framework/dotnet.js` in the browser as above.
+
+## API Reference
+
+**Browser API:** After loading the WASM module, use `exports.Motely.WASM.MotelyWasm`. All 9 methods are exported from C# (JSExport); SearchSeeds optionally calls your JS callbacks (JSImport) for progress and results. All methods are async and return JSON strings; parse with `JSON.parse()`.
+
+| Method | Description |
+|--------|-------------|
+| `AnalyzeSeed(seed, deck, stake, minAnte, maxAnte, optionsJson)` | Analyze one seed; returns ante data. |
+| `SearchSeeds(jamlFilterJson, seedList, threadCount, maxResults?)` | Search seeds matching a JAML filter. Optional: set `globalThis.MotelyWasmOnProgress`, `MotelyWasmOnResult`, `MotelyWasmOnComplete` before calling. |
+| `ValidateJaml(jamlString)` | Validate JAML without searching. |
+| `CancelSearch()` | Cancel in-progress search. |
+| `IsSearchRunning()` | Returns whether a search is running. |
+| `GetSearchProgress()` | Current progress JSON (alternative to callbacks). |
+| `GetLastSearchResult()` | Last search result JSON (cleared after read). |
+| `GetProcessorCount()` | Number of threads (use for `threadCount`). |
+| `GetVersion()` | Version info JSON. |
+
+### AnalyzeSeed
+
+Analyze a specific seed and return all ante data.
+
+```typescript
+await MotelyWasm.AnalyzeSeed(
+  seed: string,        // e.g., "TACO1111"
+  deck: string,        // "Red", "Blue", "Yellow", "Green", "Black", "Magic", "Nebula", "Ghost", etc.
+  stake: string,       // "White", "Red", "Green", "Black", "Blue", "Purple", "Orange", "Gold"
+  minAnte: number,     // 1-8
+  maxAnte: number,     // 1-8
+  optionsJson: string  // "{}" (reserved for future options)
+): Promise<string>     // Returns SeedAnalysisResult or ErrorResult JSON
+```
+
+**Response:**
+```typescript
+interface SeedAnalysisResult {
+  seed: string;
+  deck: string;
+  stake: string;
+  erraticDeckComposition: string[];
+  twos: number;
+  antes: AnteAnalysis[];
+}
+
+interface AnteAnalysis {
+  ante: number;
+  boss: string;
+  voucher: string;
+  smallBlindTag: string;
+  bigBlindTag: string;
+  drawOrder: string;
+  shopQueue: { id: string; name: string }[];
+  packs: { type: string; items: string[] }[];
+}
+```
+
+### SearchSeeds
+
+Search for seeds matching a JAML filter.
+
+```typescript
+await MotelyWasm.SearchSeeds(
+  jamlFilterJson: string,  // JAML filter as string
+  seedList: string | null, // Comma-separated seeds to search, or null for sequential
+  threadCount: number,     // Number of threads (use GetProcessorCount())
+  maxResults?: number      // Max results to return (default 1000)
+): Promise<string>         // Returns SearchResponse or ErrorResult JSON
+```
+
+**Callbacks:** Set these on `globalThis` BEFORE calling SearchSeeds:
+
+```javascript
+// Progress updates (called every ~200ms)
+globalThis.MotelyWasmOnProgress = (progressJson) => {
+  const progress = JSON.parse(progressJson);
+  console.log(`Searched: ${progress.searchedCount}, Found: ${progress.foundCount}`);
+};
+
+// Each matching seed as it's found
+globalThis.MotelyWasmOnResult = (seed, score, talliesStr) => {
+  const tallies = talliesStr ? talliesStr.split(',').map(Number) : [];
+  console.log(`Found: ${seed} (score: ${score})`);
+};
+
+// Search complete
+globalThis.MotelyWasmOnComplete = (resultJson) => {
+  const result = JSON.parse(resultJson);
+  console.log(`Search complete! Found ${result.foundCount} seeds.`);
+};
+```
+
+**Response:**
+```typescript
+interface SearchResponse {
+  results: SearchHit[];    // Empty if using callbacks
+  totalSearched: number;
+  foundCount: number;
+  cancelled: boolean;
+}
+
+interface SearchProgress {
+  searchedCount: number;
+  foundCount: number;
+  status: string;
+  percentComplete: number;
+  seedsPerSecond: number;
+  threadCount: number;
+}
+```
+
+### ValidateJaml
+
+Validate a JAML filter without running a search.
+
+```typescript
+await MotelyWasm.ValidateJaml(jamlString: string): Promise<string>
+```
+
+**Response:**
+```typescript
+interface ValidateResult {
+  valid: boolean;
+  error?: string;
+  name?: string;
+  deck?: string;
+  stake?: string;
+}
+```
+
+### CancelSearch
+
+Cancel an in-progress search.
+
+```typescript
+await MotelyWasm.CancelSearch(): Promise<void>
+```
+
+### IsSearchRunning
+
+Check if a search is currently running.
+
+```typescript
+await MotelyWasm.IsSearchRunning(): Promise<boolean>
 ```
 
-## Headers
+### GetSearchProgress
+
+Get current search progress (alternative to callbacks).
 
-Server needs for multi-threading:
+```typescript
+await MotelyWasm.GetSearchProgress(): Promise<string>  // Returns SearchProgress JSON
+```
+
+### GetLastSearchResult
+
+Get the last search result JSON (cleared after retrieval). Use as an alternative to `MotelyWasmOnComplete` when not using callbacks.
+
+```typescript
+await MotelyWasm.GetLastSearchResult(): Promise<string>  // Returns SearchResponse or empty
+```
+
+### GetProcessorCount
+
+Get the number of processors/threads available.
+
+```typescript
+await MotelyWasm.GetProcessorCount(): Promise<number>
+```
+
+### GetVersion
+
+Get version information.
+
+```typescript
+await MotelyWasm.GetVersion(): Promise<string>
+// Returns: { version: "1.0.1", runtime: "browser-wasm", features: [...] }
+```
+
+## JAML Filter Format
+
+JAML (JSON-Augmented Markup Language) is a YAML-based format for defining seed search filters.
+
+```yaml
+name: My Filter
+deck: Red
+stake: White
+
+must:
+  - joker: Blueprint
+    antes: [1, 2]
+  - voucher: Overstock
+    antes: [1]
+
+should:
+  - joker: Showman
+    score: 10
+  - spectralCard: Aura
+    antes: [1, 2]
+```
+
+## Example: Next.js Integration
+
+```typescript
+// lib/motely.ts
+let motelyWasm: any = null;
+
+export async function getMotely() {
+  if (motelyWasm) return motelyWasm;
+  
+  const { dotnet } = await import('/motely-wasm/_framework/dotnet.js');
+  const { getAssemblyExports, getConfig } = await dotnet.create();
+  const exports = await getAssemblyExports(getConfig().mainAssemblyName);
+  
+  motelyWasm = exports.Motely.WASM.MotelyWasm;
+  return motelyWasm;
+}
+
+// Usage in component
+const api = await getMotely();
+const result = JSON.parse(await api.AnalyzeSeed("TACO1111", "Red", "White", 1, 8, "{}"));
+```
+
+## Troubleshooting
+
+### "SharedArrayBuffer is not defined"
+
+Your server is missing COOP/COEP headers. Add:
 ```
 Cross-Origin-Embedder-Policy: require-corp
 Cross-Origin-Opener-Policy: same-origin
 ```
+
+### Search runs slowly
+
+Make sure COOP/COEP headers are set for multi-threading. Without them, WASM runs single-threaded.
+
+### Module not found
+
+Ensure the `dist/_framework/` folder is copied to your public directory and accessible at the URL you're importing from.
+
+## Development (maintainers)
+
+Run all commands from the **Motely.WASM** directory (where package.json lives).
+
+```bash
+# Build WASM and copy publish output to dist/
+npm run build
+
+# Local dev server with COOP/COEP (serves dist/ on http://localhost:3333)
+npm run dev
+```
+
+## Publishing (maintainers)
+
+**Do not use `npm publish --ignore-scripts`.** The package must include a built `dist/` with WASM files; scripts build and verify that.
+
+1. From repo root, build the solution so dependencies are ready: `dotnet build`
+2. `cd Motely.WASM`
+3. `npm run build` — wait until it finishes (dotnet publish + copy to dist). If it fails, fix the build before publishing.
+4. Confirm `dist/_framework` exists and has files (e.g. `dotnet.js`, `.wasm` files).
+5. `npm publish` (run `npm login` first if needed).
+
+**Verify before publish:** Run `npm pack` in Motely.WASM. Unpack the `.tgz` and confirm `package/dist/_framework` has files. If it doesn’t, the published package will be broken for users.
+
+**Verify after install (consumer):** After `npm install motely-wasm`, check that `node_modules/motely-wasm/dist/_framework` exists and has files. If it’s missing or empty, the publish didn’t include the build.
+
+## License
+
+MIT

package/dist/_framework/dotnet.boot.js

@@ -1,7 +1,7 @@
 export const config = /*json-start*/{
   "mainAssemblyName": "Motely.WASM.dll",
   "resources": {
-    "hash": "sha256-cDJnXzaPfQLxYzeJMQ3QMtPpMQ6D1Fg+S2a70/P3PmA=",
+    "hash": "sha256-aO+i4xVT6oSLeZsLATfmhfC9XLzPc42IiCXTueNj4KA=",
     "jsModuleWorker": [
       {
         "name": "dotnet.native.worker.mjs"
@@ -20,75 +20,55 @@ export const config = /*json-start*/{
     "wasmNative": [
       {
         "name": "dotnet.native.wasm",
-        "integrity": "sha256-pynCW3cr4SOL8S0g2SgxVJdm027gQXLogx93leFlEPc="
+        "integrity": "sha256-LaKjhruOfm5MO3UQ7YNQAZTGJFZD0qIaVuC5Wlj1aKw="
       }
     ],
     "coreAssembly": [
-      {
-        "virtualPath": "DuckDB.NET.Bindings.wasm",
-        "name": "DuckDB.NET.Bindings.wasm",
-        "integrity": "sha256-wqxaaQM497E3IjjC7jdl4C41iuXUgt3CIC+L39iZ/lE="
-      },
-      {
-        "virtualPath": "DuckDB.NET.Data.wasm",
-        "name": "DuckDB.NET.Data.wasm",
-        "integrity": "sha256-tTXnng0Nm7oyHXPf4U7D6XLpQEQJg8lOA67bZgdD5Wg="
-      },
-      {
-        "virtualPath": "Motely.DB.wasm",
-        "name": "Motely.DB.wasm",
-        "integrity": "sha256-mgKeRITKQ7qNH/7nIdWmL/DQzfDBWlRAtanEw/QrI7E="
-      },
       {
         "virtualPath": "Motely.wasm",
         "name": "Motely.wasm",
-        "integrity": "sha256-9dvjpkffXLEStr9R5cbo/H2PEGOihiZKxENaFYZ9RZ8="
+        "integrity": "sha256-gIFYClf0DXpm7HsvvQ0jR2MGwd4lKuOOZN01OyMSHg8="
+      },
+      {
+        "virtualPath": "Motely.Orchestration.Browser.wasm",
+        "name": "Motely.Orchestration.Browser.wasm",
+        "integrity": "sha256-ve/7dyF3t4Rn7A79Axesc9rzflRKTS3jSzHBUF0B9tY="
       },
       {
         "virtualPath": "Motely.Orchestration.wasm",
         "name": "Motely.Orchestration.wasm",
-        "integrity": "sha256-lFpy94SjuTIso9jHlQvFuIFtxLXqu3sxDvR/3cq5tPA="
+        "integrity": "sha256-PUBCdVNXQ3w4qOx4zRL4ejhOg/H1clsXYu1K9sn7cMQ="
+      },
+      {
+        "virtualPath": "Motely.Repository.wasm",
+        "name": "Motely.Repository.wasm",
+        "integrity": "sha256-jirHMql3tGeV89AxSWy9UMSTy+D5YxXi4ZIE2FRJSuM="
       },
       {
         "virtualPath": "Motely.WASM.wasm",
         "name": "Motely.WASM.wasm",
-        "integrity": "sha256-ExNs1gtYpHl6jbIIU9lY1Uv9sn5/CqJZLYnfPqSHX8w="
+        "integrity": "sha256-inefOwfugLkyVJ9BLwS48DdoFCHMj8tnPcj0nHljNaA="
       },
       {
         "virtualPath": "System.Collections.Concurrent.wasm",
         "name": "System.Collections.Concurrent.wasm",
-        "integrity": "sha256-CWu7OvQpoj42ejCs1HpqnzisMWgXXobaaOjjtZQS7OQ="
+        "integrity": "sha256-AFZxuyv5C7gl+Zq58wcA2OWTXvGnnOtUjDmJ8K3ZZ0Q="
       },
       {
         "virtualPath": "System.Collections.wasm",
         "name": "System.Collections.wasm",
-        "integrity": "sha256-pQmhSB7BWqrKN53pAlqPyERgHOsjfLoAboW+KrJ+wwk="
+        "integrity": "sha256-DsUmQwaER2ZIB1lKEDfcCg8JiVComy+nW2ft5TwReUY="
       },
       {
         "virtualPath": "System.ComponentModel.Primitives.wasm",
         "name": "System.ComponentModel.Primitives.wasm",
-        "integrity": "sha256-A4tZOdQlsq0vrR94Kgo+0cG+pd60w/RVYcnKOLj1xgE="
-      },
-      {
-        "virtualPath": "System.ComponentModel.TypeConverter.wasm",
-        "name": "System.ComponentModel.TypeConverter.wasm",
-        "integrity": "sha256-R9CyKUM1Yc/xacERK46upAkz+nBtTnFvWidNXqgBsl8="
+        "integrity": "sha256-4jl7fheYZfslgTS9+Tb5swIW4WyeIxC7CYIAUmZSkqw="
       },
       {
         "virtualPath": "System.Console.wasm",
         "name": "System.Console.wasm",
         "integrity": "sha256-RwubalytojFWDevPivMJVmaTy1f1LuUTYxJv6sgNaiU="
       },
-      {
-        "virtualPath": "System.Data.Common.wasm",
-        "name": "System.Data.Common.wasm",
-        "integrity": "sha256-oPkIp+I4fIjVPA9YDJ90yCc0asSTrmj0kkZ3c6aVdGw="
-      },
-      {
-        "virtualPath": "System.wasm",
-        "name": "System.wasm",
-        "integrity": "sha256-YabWgbCEFJ/C33k/i+7FudaFKYcs5tDuAf9sQAhhC2A="
-      },
       {
         "virtualPath": "System.IO.Pipelines.wasm",
         "name": "System.IO.Pipelines.wasm",
@@ -97,12 +77,7 @@ export const config = /*json-start*/{
       {
         "virtualPath": "System.Linq.wasm",
         "name": "System.Linq.wasm",
-        "integrity": "sha256-zgqOTRaSyGZESi7fSOQenqDDuaT3TdAHN2y5bhBeS/Y="
-      },
-      {
-        "virtualPath": "System.Linq.Expressions.wasm",
-        "name": "System.Linq.Expressions.wasm",
-        "integrity": "sha256-q2RyKG/0tx8nJ4QiKD4vTNYlLhrfSAtbHgxfHK0p5+Q="
+        "integrity": "sha256-FpqCpQ9wcwctxGL/d8AREWyZDt5gDZG0Ect7VaxuSmA="
       },
       {
         "virtualPath": "System.Memory.wasm",
@@ -112,28 +87,23 @@ export const config = /*json-start*/{
       {
         "virtualPath": "System.ObjectModel.wasm",
         "name": "System.ObjectModel.wasm",
-        "integrity": "sha256-X18I4bR7MFPCBc/6qDmAvYmBRZqWKoycYhsKhacbEjc="
+        "integrity": "sha256-53tJJYiS7ZklSNA64xArxUXeHucwKEMDeM2BdSs1ud0="
       },
       {
         "virtualPath": "System.Private.CoreLib.wasm",
         "name": "System.Private.CoreLib.wasm",
-        "integrity": "sha256-o6w5niLXm/C+zWNkSaysklzXKEtEu3dQE0fJ531Jb7c="
+        "integrity": "sha256-OeYdMfIeVa/xGdtFOcCjtDu2KBN152SkvOdvvEcHSdk="
       },
       {
         "virtualPath": "System.Private.Uri.wasm",
         "name": "System.Private.Uri.wasm",
-        "integrity": "sha256-TWTo87XjocKFIRkOBcm0RG7FbzwHSsxYSg9SlSPveXs="
+        "integrity": "sha256-iZHFmCnpe0uSpmPJK8HMBqJ/TJEu39sbYQ6bGAwu4zs="
       },
       {
         "virtualPath": "System.Runtime.InteropServices.JavaScript.wasm",
         "name": "System.Runtime.InteropServices.JavaScript.wasm",
         "integrity": "sha256-kMfuIHajm5NGI4GIVJI0/8O+C2k7ZW+oogCwkyMRpk8="
       },
-      {
-        "virtualPath": "System.Runtime.Numerics.wasm",
-        "name": "System.Runtime.Numerics.wasm",
-        "integrity": "sha256-gSb0Gu2r6r7VBStSEVMfeoKYpKIGZkGT+2c0QzmO5D8="
-      },
       {
         "virtualPath": "System.Security.Cryptography.wasm",
         "name": "System.Security.Cryptography.wasm",
@@ -147,17 +117,17 @@ export const config = /*json-start*/{
       {
         "virtualPath": "System.Text.Json.wasm",
         "name": "System.Text.Json.wasm",
-        "integrity": "sha256-sdGrRV1ZiwO/kR8Tl5tK4iX3ojCyc7oXXP/PnJb/ilI="
+        "integrity": "sha256-0YO5kydtFOl8SwOv9skKooBIxosKDEvD14rqyO8H4M4="
       },
       {
         "virtualPath": "System.Text.RegularExpressions.wasm",
         "name": "System.Text.RegularExpressions.wasm",
-        "integrity": "sha256-LivmUKsgqtW1rHzuKpfx+TjhO8yz/sJ2POGrenby/nQ="
+        "integrity": "sha256-fMJntAuv6fs8Acy7cl7DCii3G37WR7OK/3P0iG+GNoU="
       },
       {
         "virtualPath": "System.Threading.Channels.wasm",
         "name": "System.Threading.Channels.wasm",
-        "integrity": "sha256-2EgxriwFFANyHLTavSVnZRryibA+Mmh+X5tpb753RzM="
+        "integrity": "sha256-9wxtrvceNdYncnllXgzowxFSLkUDvySzFbgdIwpspbg="
       },
       {
         "virtualPath": "System.Threading.wasm",
@@ -167,7 +137,7 @@ export const config = /*json-start*/{
       {
         "virtualPath": "YamlDotNet.wasm",
         "name": "YamlDotNet.wasm",
-        "integrity": "sha256-Daw6C2JGNfcVFjWBMQMfBtMOVoH5M1f8TiJbAxdlOOA="
+        "integrity": "sha256-ym2r8OJPp9GcsZ2CIDDUlC81V6rrarojAsdiVRLFV3s="
       },
       {
         "virtualPath": "aot-instances.wasm",