motely-wasm 11.2.0 → 11.3.1

package/README.md

@@ -0,0 +1,114 @@
+# motely-wasm
+
+**Balatro seed searcher compiled to browser WASM**, from [`MotelyJAML`](https://github.com/OptimusPi/MotelyJAML). NativeAOT-LLVM + Bootsharp (SIMD-vectorized, AOT-trimmed, embedded binaries, single ES module).
+
+Node 20+ / modern browsers. Single-threaded in the browser runtime.
+
+## Install
+
+```bash
+npm i motely-wasm
+# or
+pnpm add motely-wasm
+```
+
+## Usage
+
+```ts
+import bootsharp, { MotelyWasm, Motely, Filters } from "motely-wasm";
+
+// 1. Boot the WASM runtime (one-time).
+await bootsharp.boot();
+
+// 2. Call the exported IMotelyWasm surface.
+console.log(MotelyWasm.getVersion());           // "11.3.0"
+console.log(MotelyWasm.validateJaml(jamlText)); // "valid" or error string
+
+// 3. Run a search. JAML (YAML) comes in as a string. Parse / generate it with `yaml`.
+const search = MotelyWasm.startRandomSearch(jamlText, 100_000);
+const done = await search.waitForCompletion();
+const hits = search.drainResults(1000);
+search.dispose();
+```
+
+## JAML is just YAML
+
+JAML (Jimbo's Ante Markup Language) is **YAML, 1:1**. There is nothing exotic here — a JAML document is a YAML document. To work with it in JS:
+
+```ts
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+const doc = parseYaml(jamlText);                 // normal JS object
+jamlText = stringifyYaml({ ...doc, stake: "Gold" });
+```
+
+**Do not regex-parse JAML.** Use the `yaml` package (already a dep in most stacks) or the built-in `MotelyWasm.parseJamlContext(jaml)` for the canonical deck/stake/aesthetics extraction.
+
+JSON Schema for JAML: https://raw.githubusercontent.com/OptimusPi/MotelyJAML/master/jaml.schema.json
+
+## Recommended UI consumers
+
+- **[`jaml-ui`](https://www.npmjs.com/package/jaml-ui)** — React components + shared Motely/JAML TypeScript surface over this package. Prefer `jaml-ui` display helpers / filter components over rolling your own.
+- **[`jimbo-ui`](https://www.npmjs.com/package/jimbo-ui)** — Balatro-themed visual components (cards, sprites, aesthetics). Pair with `jaml-ui`.
+
+If a Motely name / enum / formatted string is missing from `motely-wasm` and you'd otherwise hand-roll it in TS, **open an issue** on [MotelyJAML](https://github.com/OptimusPi/MotelyJAML/issues) asking for the export — that's the canonical way to extend `IMotelyWasm`.
+
+## Package shape
+
+This is a single embedded-binaries ES module ("compat" shape — everything in one bundle, no sideload):
+
+```
+motely-wasm/
+  index.mjs            ~10–11 MB — single-file ESM with .NET runtime + Motely binaries embedded
+  package.json
+  types/
+    index.d.ts         main entry; re-exports the useful surface
+    bindings.g.d.ts    generated from C# IMotelyWasm + all DTO/enum types (MotelyBoosterPack, MotelyVoucher, MotelyBossBlind, MotelyTag, MotelyDeck, MotelyStake, …)
+    boot.d.ts          boot / exit / getStatus / BootStatus / BootOptions
+    event.d.ts         Event<T> (subscribe / unsubscribe)
+    modules.d.ts       getMain / getNative / getRuntime
+    config.d.ts        buildConfig
+    instances.d.ts     interop-instance helpers
+    resources.d.ts     resource / BinaryResource types
+    (…)
+```
+
+The `types/` split is emitted by Bootsharp and **re-exports cleanly** through `types/index.d.ts`, so consumers just do `import { Motely, Filters, MotelyWasm } from "motely-wasm"` and TypeScript resolves everything.
+
+## Threading
+
+All search methods internally set `threadCount = 1`. Browser WASM is single-threaded — this is not a knob. Use [`Motely.CLI`](https://github.com/OptimusPi/MotelyJAML) for configurable parallel / AVX-512 native throughput.
+
+## CDN / script-tag mirror
+
+In addition to npm, this package is mirrored on the MotelyJAML CDN so you can `import` straight from an HTML page (no bundler required):
+
+```html
+<script type="module">
+  import bootsharp, { MotelyWasm } from "https://cdn.seedfinder.app/motely-wasm/11.3.0/index.mjs";
+  await bootsharp.boot();
+  console.log(MotelyWasm.getVersion());
+</script>
+```
+
+A `latest` alias tracks the most recent release:
+
+```
+https://cdn.seedfinder.app/motely-wasm/latest/index.mjs
+```
+
+(CDN is served from the same infra as `jammy.seedfinder.app` / `mcp.seedfinder.app`. Versioned URLs are immutable; `latest` moves on each release.)
+
+Fallbacks that "just work" without any setup:
+
+```
+https://unpkg.com/motely-wasm@11.3.0/index.mjs
+https://cdn.jsdelivr.net/npm/motely-wasm@11.3.0/index.mjs
+```
+
+## Versioning
+
+Single source of truth: `<MotelyVersion>` in [`Directory.Packages.props`](https://github.com/OptimusPi/MotelyJAML/blob/master/Directory.Packages.props). On `dotnet publish Motely.Wasm`, an MSBuild target stamps that into `motely-wasm/package.json`.
+
+## License
+
+MIT — © pifreak & MotelyJAML contributors.