motely-wasm 14.0.2 → 14.2.0

package/README.md

@@ -0,0 +1,100 @@
+# motely-wasm
+
+Find Balatro seeds with plain-language JAML filters — Jimbo's Ante Markup Language. SIMD-vectorized seed search (Motely engine, C# → NativeAOT-LLVM WASM). Browser + Node.
+
+## Install
+
+```bash
+npm install motely-wasm
+```
+
+## Boot & Search
+
+```ts
+import motely, { MotelyWasm, MotelyWasmEvents } from "motely-wasm";
+
+await motely.boot();
+
+const jaml = `
+name: Blueprint Copy Engine
+deck: Red
+stake: White
+must:
+  - rareJoker: Blueprint
+    antes: [1, 2, 3]
+should:
+  - rareJoker: Brainstorm
+    score: 80
+`;
+
+MotelyWasmEvents.onResult.subscribe((seed, score) => console.log(seed, score));
+MotelyWasmEvents.onProgress.subscribe((searched, matching) => { /* … */ });
+MotelyWasmEvents.onComplete.subscribe((status, searched, matched) => { /* … */ });
+
+const search = MotelyWasm.startRandomSearch(jaml, 10000);
+// later: search.cancel();
+```
+
+## CDN Delivery (recommended for MCP Apps / single-file bundles)
+
+Every published version of `motely-wasm` is mirrored to a public CDN:
+
+```
+https://cdn.seedfinder.app/motely-wasm/<version>/index.mjs
+```
+
+Use this when your build can't (or shouldn't) bundle the WASM payload inline — for example:
+
+- **MCP Apps** bundled as a single HTML resource: dynamic `import(cdn)` keeps the HTML small and the browser caches the engine across tool invocations.
+- **Vercel Functions / Cloudflare Workers**: dynamic import avoids bundling ~11MB of WASM into every deployment artifact.
+- **CDN-hosted static sites**: one cached copy of the engine per version, shared across all pages.
+
+Example — load the engine from CDN inside a Web Worker:
+
+```ts
+// searchWorker.ts
+const mod = await import(/* @vite-ignore */
+  `https://cdn.seedfinder.app/motely-wasm/12.4.1/index.mjs`);
+await mod.default.boot();
+const { MotelyWasm, MotelyWasmEvents } = mod;
+```
+
+Version must be pinned explicitly — the CDN serves immutable, versioned paths for long-term caching (`Cache-Control: max-age=31536000`).
+
+### Content Security Policy
+
+When embedding in a sandboxed iframe (MCP Apps), allow both script loading and fetch/import:
+
+```
+script-src https://cdn.seedfinder.app
+connect-src https://cdn.seedfinder.app
+```
+
+For MCP App servers using `@modelcontextprotocol/ext-apps`:
+
+```ts
+{
+  ui: {
+    csp: {
+      resourceDomains: ["https://cdn.seedfinder.app"],
+      connectDomains: ["https://cdn.seedfinder.app"],
+    },
+  },
+}
+```
+
+## Build
+
+NativeAOT-LLVM + SIMD. Verify "LLVM compilation to IR finished" in build output.
+
+```xml
+<BootsharpLlvm>true</BootsharpLlvm>
+<WasmEnableSIMD>true</WasmEnableSIMD>
+<EmccFlags>-msimd128</EmccFlags>
+```
+
+The `MONO_WASM:` prefix in console logs is Bootsharp's glue log string — this is **not** a Mono runtime build. Motely is NativeAOT-LLVM.
+
+## License
+
+MIT