motely-wasm 20.0.0 → 20.0.2

package/README.md

@@ -0,0 +1,113 @@
+# motely-wasm
+
+WebAssembly build of [MotelyJAML](https://github.com/OptimusPi/MotelyJAML) — the SIMD Balatro seed search engine with JAML filter support. Powers [seedfinder.app](https://seedfinder.app).
+
+## Install
+
+```sh
+npm install motely-wasm
+```
+
+## Boot
+
+The WASM binary is **embedded** in the JS module — no extra files to serve.
+
+```js
+import bootsharp from "motely-wasm";
+
+await bootsharp.boot();
+```
+
+Guard re-boots with `bootsharp.getStatus() === bootsharp.BootStatus.Standby`.
+
+## Imports
+
+```js
+// Main API — the C# Program class, renamed to Motely
+import { Program as Motely } from "motely-wasm/dist/generated/modules/motely/wasm.g.mjs";
+
+// Enums — MotelyDeck, MotelyStake, etc.
+import * as enums from "motely-wasm/dist/generated/modules/motely/enums.g.mjs";
+
+// Types — MotelyProgress, IMotelySearch, MotelyScoredSeedResult, etc.
+import * as types from "motely-wasm/dist/generated/modules/motely.g.mjs";
+```
+
+## Quick start
+
+```js
+// Optional [Import] hook — surface WASM-side errors. Bind BEFORE boot:
+// Bootsharp snapshots [Import] bindings at boot().
+Motely.reportWasmError = (msg) => console.error("[WASM]", msg);
+
+// Subscribe to events
+Motely.onSeedMatch.subscribe(seed => console.log("match:", seed));
+Motely.onProgress.subscribe(p => console.log(`${p.percentComplete.toFixed(1)}%`));
+
+// Parse a JAML filter. JAML is YAML, and YAML is a JSON superset — a JSON
+// object string parses too, which is what makes it round-trip cleanly over MCP.
+const config = Motely.parseJaml(`
+name: WeeMonday
+deck: Erratic
+stake: Black
+must:
+  - joker: WeeJoker
+    antes: [1]
+`);
+
+// Run a search (blocks until complete — run in a Worker for non-blocking UI).
+const search = Motely.runSequentialSearch(config);
+console.log(search.matchingSeeds, "matches out of", search.totalSeedsSearched);
+```
+
+## API
+
+```js
+Motely.parseJaml(jaml)                       // string → JamlConfig (throws on invalid JAML)
+Motely.explainJaml(config)                   // human-readable plan summary
+Motely.createPlan(config)                    // JamlSearchPlan (tally columns, CSV header)
+Motely.jamlToJson(jaml)                       // JAML string → JSON string
+Motely.jsonToJaml(json)                       // JSON string → JAML string
+Motely.jamlyzer(seed, lens)                   // analyze ONE seed through a JamlConfig lens → JamlyzerSnapshot
+Motely.nativeFilterNames()                    // built-in native filter names
+
+Motely.runSequentialSearch(config, ...)       // sequential seed search
+Motely.runRandomSearch(config, count)         // random seed sample
+Motely.runSeedListSearch(config)              // search only config.seeds
+Motely.runAestheticSearch(config, aesthetic)  // aesthetic / scored search
+Motely.runNativeListSearch(name, seeds)       // named native filter over a seed list
+Motely.runPassthroughListSearch(seeds)        // no filter, just iterate seeds
+```
+
+## Events
+
+```js
+Motely.onSeedMatch.subscribe(seed => {})       // string — each matching seed
+Motely.onScoredResult.subscribe(result => {})  // MotelyScoredSeedResult { seed, score, tallies }
+Motely.onProgress.subscribe(p => {})           // MotelyProgress
+Motely.onFileChanges.subscribe(changes => {})  // file system changes (browser OPFS)
+```
+
+## File system (browser)
+
+`Motely.pickRoot`, `mountRoot`, `unmountRoot`, `readTextFile`, `writeTextFile` use the browser File System Access API via `Bootsharp.FileSystem`. Initialize the JS extension before booting:
+
+```js
+import * as fs from "@rewaffle/bootsharp-file-system";
+import { Bootsharp } from "motely-wasm/dist/generated/modules/bootsharp/file-system.g.mjs";
+
+fs.init(Bootsharp.FileSystem.FileMounter);
+await bootsharp.boot();
+```
+
+## Jimmolate
+
+Scalar predicate filtering after the base SIMD pass. Bind the predicate **before** boot (Bootsharp snapshots `[Import]` bindings at boot), then enable it:
+
+```js
+Motely.jimmolatePredicate = (result) => {
+    // result is MotelyScoredSeedResult — { seed, score, tallies }
+    return result.score > 0; // return true to keep the seed
+};
+Motely.jimmolateEnabled = true;
+```

package/RELEASE.md

@@ -0,0 +1,139 @@
+# Releasing motely-wasm to npm — the real pipeline
+
+This is the finished reasoning for "how do you update the README and the package
+without hand-editing anything," grounded in the Bootsharp docs and the actual
+state of this repo. It replaces the don't-touch comment in `Motely.Wasm.csproj`
+with an *understanding* of why that comment exists and what the correct fix is.
+
+## What ships, and from where
+
+`npm publish` runs from **`motely-wasm/`** (this directory). npm packs three
+things from here, regardless of any `files` field:
+
+| File | Owner today | Owner it should have |
+|------|-------------|----------------------|
+| `package.json` | hand-maintained | **npm** owns the version; structure hand-authored |
+| `README.md`    | hand-created (was *missing* for 20 weeks) | authored here, single source |
+| `dist/`        | Bootsharp build output (`BootsharpPublishDirectory`) | Bootsharp, regenerated on build |
+
+`dist/bin/motely-wasm.wasm` is the sideloaded runtime (`BootsharpBinariesDirectory`
+is set → separate `.wasm`, not base64-embedded → `boot()` MUST be told where it is;
+that is the whole reason for the boot section in `README.md`).
+
+## The root bug: two version sources, already drifted
+
+There are **two** places a version lives, and they are out of sync right now:
+
+- `Directory.Packages.props` → `<MotelyVersion>20.0.0</MotelyVersion>` — the **.NET
+  assembly version**, consumed solution-wide (`Motely.csproj`, `Motely.Wasm.csproj`
+  both do `<Version>$(MotelyVersion)</Version>`).
+- `motely-wasm/package.json` → `"version": "20.0.1"` — the **npm package version**,
+  the one users actually `npm install`.
+
+The published `20.0.1` is the `20.0.0` engine + a fixed README. That patch bump is
+*semantically correct* (docs-only fix), but it was done by **hand-typing `20.0.1`
+into package.json**, which is exactly the foot-gun: a human typing a version is a
+human introducing drift.
+
+These two versions are genuinely different concerns and **may** legitimately
+diverge (a README-only npm patch should not force an engine version bump). The fix
+is not "force them equal" — it's "make each one bumped by a tool, never by hand."
+
+## Why Bootsharp can't own package.json
+
+Bootsharp regenerates `package.json` on every build with a **bare** template — look
+at `Motely.Wasm/obj/package.json` (where it's currently parked):
+
+```json
+{ "name": "motely-wasm", "type": "module", "exports": {...}, "browser": {...} }
+```
+
+No `version`, no `main`, no `types`, no `author`, no `license`, no `description`.
+Publishing that fails (`npm publish` with no version → the `reading 'prerelease'`
+crash the csproj comment warns about). Per the Bootsharp docs, `BootsharpPackageDirectory`
+defaults to the project dir and Bootsharp **overwrites** the file there on every
+build. So pointing it at the real npm root clobbers the rich manifest every build.
+
+The current mitigation — redirect `BootsharpPackageDirectory` to `obj/` and
+hand-author `motely-wasm/package.json` — is **correct**. Don't undo it. The bare
+template genuinely lacks what npm needs, and Bootsharp offers no hook to enrich it.
+
+## The correct ownership split
+
+```
+Directory.Packages.props : MotelyVersion   — engine/assembly version, bump for ENGINE releases
+motely-wasm/package.json : "version"        — npm package version, bump with `npm version patch`
+motely-wasm/package.json : everything else  — stable, hand-authored, rarely changes
+motely-wasm/README.md                       — authored HERE (package root), single source
+motely-wasm/dist/                           — Bootsharp output, never hand-touched
+Motely.Wasm/obj/package.json                — Bootsharp's throwaway bare template, ignored
+```
+
+The "no hand-editing" rule applies to the **version field specifically**. You never
+type a version again — `npm version patch` does. The rest of package.json (exports
+map with types, browser shims, author) is a small stable file; authoring it once by
+hand is fine and *better* than a generator that drops the fields npm requires.
+
+## The release command (zero hand-edits)
+
+From `motely-wasm/`:
+
+```sh
+npm version patch    # 20.0.1 -> 20.0.2 in package.json AND creates the git tag v20.0.2
+npm publish          # packs package.json + README.md + dist/, pushes to npm
+```
+
+`npm version patch` is the tool that "knows" — it edits the version *and* tags git
+atomically. Never open package.json to change the version.
+
+### Make it bulletproof with npm lifecycle scripts (the real automation)
+
+Add to `motely-wasm/package.json` so a stale `dist/` can never ship:
+
+```json
+"scripts": {
+  "build": "dotnet publish ../Motely.Wasm/Motely.Wasm.csproj -c Release",
+  "prepublishOnly": "npm run build"
+}
+```
+
+`prepublishOnly` runs **after** `npm version patch` bumps the version and **before**
+the tarball is packed — so `npm publish` always ships a freshly built `dist/` that
+matches. (`dotnet publish` in Release is the Bootsharp path that emits `dist/` +
+the sideloaded wasm; see Bootsharp `getting-started.md` / `build-config.md`.)
+
+> Not yet wired — this is the one concrete edit the next session should make and
+> test with `npm publish --dry-run`. Left undone tonight on purpose (handoff, not
+> a 2am publish).
+
+## The README: one source, here
+
+`Motely.Wasm/README.md` (the C# project dir) is **stale v19** — it documents the
+removed `jimmolateProbe` / `MotelySingleSearchContext`. It is NOT what ships and
+should be deleted or treated as dead. The shipping README is **`motely-wasm/README.md`**
+(this dir), authored against the live v20 surface. Keep exactly one. Don't add a
+build "copy README" step that creates a second source to drift — author it where it
+ships.
+
+## What's drifted right now (reconcile when clear-headed)
+
+- `MotelyVersion` is `20.0.0`; npm is `20.0.1`. The published wasm reports `20.0.0`
+  internally. Cosmetic, not breaking. If you want them re-aligned, bump
+  `MotelyVersion` to match at the next engine touch and rebuild — don't republish
+  just for this.
+- The `Motely.Wasm.csproj` comment block says "DO NOT re-add a FinalizeNpmPackage
+  target." That advice is still right (Bootsharp's bare template can't be the
+  source), but the *reason* is now written down here instead of as a scar.
+
+## Docs citations
+
+- Bootsharp `build-config.md`: `BootsharpPackageDirectory` (default = project dir,
+  "Directory to publish package.json"), `BootsharpPublishDirectory`,
+  `BootsharpBinariesDirectory`.
+- Bootsharp `sideloading.md`: binaries dir **set** → separate `.wasm`, `boot()` takes
+  a root URL or `{ wasm }` bytes (the v20 boot contract — see `README.md`).
+- Bootsharp `getting-started.md`: `dotnet publish` (Release) produces the module +
+  `package.json`; Release auto-enables NativeAOT-LLVM + trimming.
+- npm: `package.json` / `README.md` / `LICENSE` always ship regardless of `files`;
+  `npm version <patch|minor|major>` bumps version + tags git; `npm publish --dry-run`
+  to verify the tarball before pushing.