motely-wasm 18.1.1 → 18.2.2

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");
@@ -182,24 +179,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();
@@ -211,48 +201,52 @@ console.log(search.isCompleted, search.totalSeedsSearched, search.matchingSeeds)
 search.cancel(); // stop early
 ```
 
-## Stream pagers
+## Stream cursor
 
-Pagers expose Balatro's raw PRNG streams — one packed int per item, no JAML filter needed.
-**Always prefer `getNextChunk(n)` over repeated `getNext()` calls** — each call is a WASM
-interop crossing, so batching is the right default:
+`Motely.createStreamCursor(seed, deck, stake, ante, kind)` returns a stateful cursor over
+one of Balatro's per-ante PRNG streams — one packed int per item, no JAML filter needed.
+The `kind` argument selects which stream; one factory + one enum arg covers every stream
+type:
 
 ```js
-import { Motely, MotelyDeck, MotelyStake } from "motely-wasm";
+import { Motely } from "motely-wasm";
+import { MotelyStreamKind } from "motely-wasm/motely";
+import { MotelyDeck, MotelyStake } from "motely-wasm/motely/enums";
 
-const pager = Motely.createShopPager("AAAAAAAA", MotelyDeck.Red, MotelyStake.White, 1);
-const items = pager.getNextChunk(6); // 6 packed ints, one crossing
+const cursor = Motely.createStreamCursor("AAAAAAAA", MotelyDeck.Red, MotelyStake.White, 1, MotelyStreamKind.Shop);
+const items = cursor.getNextChunk(6); // 6 packed ints, one WASM crossing
 ```
 
-Each factory targets a distinct PRNG stream — these are not the same stream filtered, so there
-is one factory per stream type:
+**Always prefer `getNextChunk(n)` over repeated `getNext()` calls** — each call is a WASM
+interop crossing, so batching is the right default.
 
-| Factory | Stream |
-|---|---|
-| `createShopPager(seed, deck, stake, ante)` | Mixed shop (jokers, tarots, planets, spectrals on Ghost, standard cards with MagicTrick) |
-| `createJokerPager(seed, deck, stake, ante)` | Shop jokers — includes edition + sticker bits |
-| `createTarotPager(seed, deck, stake, ante)` | Shop tarots |
-| `createPlanetPager(seed, deck, stake, ante)` | Shop planets |
-| `createSpectralPager(seed, deck, stake, ante)` | Shop spectrals (non-Ghost returns `SpectralExcludedByStream`) |
-| `createLegendaryJokerPager(seed, deck, stake, ante)` | Legendary fixed-rarity joker stream |
-| `createRareTagJokerPager(seed, deck, stake, ante)` | Rare Tag hand-out joker stream |
-| `createTagPager(seed, deck, stake, ante)` | Tags — value is `MotelyTag` cast to int |
-| `createVoucherPager(seed, deck, stake, ante)` | Vouchers — value is `MotelyVoucher` cast to int |
+| `MotelyStreamKind` value | Stream | Returned int |
+|---|---|---|
+| `Shop` | Mixed shop (jokers, tarots, planets, spectrals on Ghost, standard cards with MagicTrick) | Packed item (`decodeItemType`, `decodeItemCategory`, …) |
+| `Joker` | Shop jokers — includes edition + sticker bits | Packed item |
+| `Tarot` | Shop tarots | Packed item |
+| `Planet` | Shop planets | Packed item |
+| `Spectral` | Shop spectrals (non-Ghost returns `SpectralExcludedByStream`) | Packed item |
+| `LegendaryJoker` | Legendary fixed-rarity joker stream | Packed item |
+| `RareTagJoker` | Rare Tag hand-out joker stream | Packed item |
+| `Tag` | Tags — raw `MotelyTag` enum cast to int. Decoders do not apply; use `MotelyTag[value]`. | `(int)MotelyTag` |
+| `Voucher` | Vouchers — raw `MotelyVoucher` enum cast to int. Uses an empty run state, so odd-indexed (prerequisite-required) vouchers are skipped by the engine. Use `MotelyVoucher[value]`. | `(int)MotelyVoucher` |
 
 ## Packed-int decoders
 
-All pager streams return packed integers. Bit fields are extracted with the decode helpers
-exported from the entry point:
+Stream cursors return packed integers. Bit fields are extracted with the decode helpers
+on `Motely`:
 
 ```js
+import { Motely } from "motely-wasm";
+import { MotelyStreamKind } from "motely-wasm/motely";
 import {
-    Motely,
     MotelyItemType, MotelyItemTypeCategory, MotelyJokerRarity,
     MotelyItemEdition, MotelyItemSeal, MotelyItemEnhancement,
-} from "motely-wasm";
+} from "motely-wasm/motely/enums";
 
-const pager = Motely.createJokerPager("AAAAAAAA", 0, 0, 1);
-const v = pager.getNext();
+const cursor = Motely.createStreamCursor("AAAAAAAA", 0, 0, 1, MotelyStreamKind.Joker);
+const v = cursor.getNext();
 
 const type      = Motely.decodeItemType(v);        // → MotelyItemType value
 const category  = Motely.decodeItemCategory(v);    // → MotelyItemTypeCategory value
@@ -271,11 +265,16 @@ console.log(MotelyJokerRarity[rarity]); // e.g. "Common"
 
 All enum tables (`MotelyItemType`, `MotelyItemTypeCategory`, `MotelyJokerRarity`,
 `MotelyItemEdition`, `MotelyItemSeal`, `MotelyItemEnhancement`, `MotelyTag`,
-`MotelyVoucher`, `MotelyBoosterPack`, `MotelyDeck`, `MotelyStake`) are exported from
-`motely-wasm` and can be used for reverse-lookup by numeric value or forward-lookup by name.
+`MotelyVoucher`, `MotelyBoosterPack`, `MotelyDeck`, `MotelyStake`) live at
+`motely-wasm/motely/enums` and can be used for reverse-lookup by numeric value or
+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 |
@@ -296,7 +295,8 @@ Motely.onScoredResult.unsubscribe(handler);
 | Import path | Contents |
 |---|---|
 | `motely-wasm` | Default export: `boot`, `getStatus`, `BootStatus`. Named export: `Motely` (main API) |
-| `motely-wasm/motely` | Types: `IMotelySearch`, `IMotelySearchSettingsInterop`, `MotelyProgress`, `MotelyScoredSeedResult`, `MotelyDeck`, `MotelyStake`, enums |
+| `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` |
 | `motely-wasm/bootsharp/file-system` | File-system interop (browser OPFS) — `PermissionMode`, `IFileMounter` |