motely-wasm 17.2.3 → 17.3.1

package/Motely.Wasm.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <RuntimeIdentifier>browser-wasm</RuntimeIdentifier>
+    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+    <IsPackable>false</IsPackable>
+    <BootsharpName>motely-wasm</BootsharpName>
+    <BootsharpPublishDirectory>$(MSBuildProjectDirectory)\..\motely-wasm</BootsharpPublishDirectory>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Bootsharp" />
+    <PackageReference Include="Bootsharp.Inject" />
+    <PackageReference Include="Bootsharp.FileSystem" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Motely\Motely.csproj" />
+  </ItemGroup>
+</Project>

package/Program.cs

@@ -0,0 +1,152 @@
+using Bootsharp;
+using Bootsharp.FileSystem;
+using Bootsharp.Inject;
+using Microsoft.Extensions.DependencyInjection;
+using Motely;
+using Motely.Analysis;
+using Motely.Filters;
+using Motely.Filters.Native;
+using System.Reflection;
+using System.Text;
+
+[assembly: Preferences(Space = [@"^Motely\.Wasm\.Program$", "Motely"])]
+
+namespace Motely.Wasm;
+
+public static partial class Program
+{
+    private static IServiceProvider services = null!;
+    private static readonly Dictionary<string, IFileSystem> MountedFileSystems = new(StringComparer.Ordinal);
+    private static readonly MotelyFileWatcher FileWatcher = new();
+
+    [Export]
+    public static event Action<IReadOnlyList<Change>>? OnFileChanges;
+
+    [Export]
+    public static event Action<string>? OnSeedMatch;
+
+    [Export]
+    public static event Action<MotelyScoredSeedResult>? OnScoredResult;
+
+    [Export]
+    public static event Action<MotelyProgress>? OnProgress;
+
+    public static void Main()
+    {
+        services = new ServiceCollection()
+            .AddBootsharp()
+            .BuildServiceProvider();
+    }
+
+    [Export]
+    public static string Version() =>
+        typeof(MotelyDeck).Assembly
+            .GetCustomAttribute<AssemblyInformationalVersionAttribute>()!
+            .InformationalVersion;
+
+    [Export]
+    public static string ValidateJaml(string jaml)
+    {
+        if (!JamlConfigLoader.TryLoad(jaml, out var config, out var error))
+            return error ?? "Invalid JAML.";
+        try
+        {
+            JamlSearchBuilder.EnsureRunnablePlan(config);
+            return "valid";
+        }
+        catch (Exception ex)
+        {
+            return ex.Message;
+        }
+    }
+
+    [Export]
+    public static string ExplainJaml(string jaml)
+    {
+        if (!JamlConfigLoader.TryLoad(jaml, out var config, out var error))
+            throw new InvalidOperationException(error ?? "Invalid JAML.");
+        return config.HasAnyClauses ? JamlSearchBuilder.ExplainPlan(config) : "";
+    }
+
+    [Export]
+    public static JamlSearchPlan CreatePlan(string jaml)
+    {
+        if (!JamlConfigLoader.TryLoad(jaml, out var config, out var error))
+            throw new InvalidOperationException(error ?? "Invalid JAML.");
+        return JamlSearchBuilder.CreatePlan(config);
+    }
+
+    [Export]
+    public static MotelyJamlyzerResult AnalyzeJamlSeeds(string jaml, string[] seeds) =>
+        MotelyJamlyzer.AnalyzeSeeds(new(jaml, seeds));
+
+    [Export]
+    public static IMotelySearchSettingsInterop CreateSearch(string jaml)
+    {
+        if (!JamlConfigLoader.TryLoad(jaml, out var config, out var error))
+            throw new InvalidOperationException(error ?? "Invalid JAML.");
+        return AttachInteropCallbacks(JamlSearchBuilder.CreateSettings(config));
+    }
+
+    [Export]
+    public static IMotelySearchSettingsInterop CreateSearchSettings() =>
+        AttachInteropCallbacks(
+            new MotelySearchSettings<PassthroughFilterDesc.PassthroughFilter>(
+                new PassthroughFilterDesc()
+            )
+        );
+
+    [Export]
+    public static async Task<string?> PickRoot(PickOptions? options = null) =>
+        await Mounter().PickRoot(options);
+
+    [Export]
+    public static async Task<string> MountRoot(string root, MountOptions? options = null)
+    {
+        var fs = await Mounter().Mount(root, FileWatcher, options);
+        MountedFileSystems[root] = fs;
+        return root;
+    }
+
+    [Export]
+    public static async Task UnmountRoot(string root)
+    {
+        MountedFileSystems.Remove(root);
+        await Mounter().Unmount(root);
+    }
+
+    [Export]
+    public static async Task<string> ReadTextFile(string root, string uri)
+    {
+        var bytes = await GetFileSystem(root).ReadFile(uri);
+        return Encoding.UTF8.GetString(bytes);
+    }
+
+    [Export]
+    public static async Task WriteTextFile(string root, string uri, string text) =>
+        await GetFileSystem(root).WriteFile(uri, Encoding.UTF8.GetBytes(text));
+
+    private static IFileMounter Mounter() => services.GetRequiredService<IFileMounter>();
+
+    private static IMotelySearchSettingsInterop AttachInteropCallbacks(IMotelySearchSettings settings) =>
+        (IMotelySearchSettingsInterop)settings
+            .WithSeedMatchCallback(seed => OnSeedMatch?.Invoke(seed))
+            .WithScoredResultCallback(tally =>
+                OnScoredResult?.Invoke(MotelyScoredSeedResult.FromTally(in tally))
+            )
+            .WithProgressCallback(p => OnProgress?.Invoke(p));
+
+    private static IFileSystem GetFileSystem(string root) =>
+        MountedFileSystems.TryGetValue(root, out var fs)
+            ? fs
+            : throw new InvalidOperationException($"File system root '{root}' is not mounted.");
+
+    private sealed class MotelyFileWatcher : IFileWatcher
+    {
+        public Task HandleFileChanges(IReadOnlyList<Change> changes)
+        {
+            OnFileChanges?.Invoke(changes);
+            return Task.CompletedTask;
+        }
+    }
+}

package/README.md

@@ -1,65 +1,144 @@
-# Motely.Wasm
+# motely-wasm
 
-Bootsharp host for the browser/JavaScript Motely package. It keeps all Bootsharp attributes, dependency injection, and JavaScript interop concerns out of the core `Motely` library.
+WebAssembly package for [Motely](https://github.com/nathanialph/jammyseedfinder) — the Balatro seed search engine powered by JAML (Jammy YAML filter language).
 
-## Build
+## Install
 
-```powershell
-dotnet publish Motely.Wasm/Motely.Wasm.csproj -c Debug
+```sh
+npm install motely-wasm
 ```
 
-Debug publishes use the regular .NET browser WASM toolchain and are the quickest way to verify the contract. Release publishes enable Bootsharp's NativeAOT-LLVM path; install Binaryen's `wasm-opt` for fully optimized release output.
+## Quick start
 
-Bootsharp alpha packages are resolved from user-level NuGet feeds. The sponsor-only `Bootsharp.FileSystem` extension is consumed from a local Bootsharp Extra checkout through the `BootsharpExtraRoot` MSBuild property. Set it in your environment or user-local MSBuild props; do not commit personal drive paths.
+```js
+import motely from "motely-wasm";
+import { Motely } from "motely-wasm/index";
+
+// Boot the runtime, pointing at wherever your package assets are served
+await motely.boot("/node_modules/motely-wasm");
+
+// Subscribe to results before starting
+Motely.onSeedMatch.subscribe(seed => console.log("match:", seed));
+Motely.onProgress.subscribe(p => console.log(`${p.percentComplete.toFixed(1)}%`));
+
+// Build and run a search
+const search = Motely.createSearch(`
+  ante-1:
+    jokers:
+      - Joker
+`).withSequentialSearch()
+  .createSearch();
 
-The generated ES module is written to `motely-wasm/`:
+search.runSearchUntilCompletion();
+```
+
+## Booting
 
-- `motely-wasm/index.mjs` and generated bindings
-- `motely-wasm/package.json`
-- `motely-wasm/bin/` runtime and WASM binaries
+`boot(resources, options?)` initializes the .NET WASM runtime. Call it once before any `Motely.*` API.
+
+```js
+import motely, { BootStatus } from "motely-wasm";
 
-Bootsharp writes the ES module package skeleton during publish. `Motely.Wasm/sync-package.mjs` runs immediately afterward to add the Motely npm metadata, version, README, schema export, and publish hooks.
+// From a URL base path (all .wasm / assembly files served from there)
+await motely.boot("/assets/motely-wasm");
 
-## JavaScript Usage
+// Check status
+console.log(motely.getStatus()); // BootStatus.Booted
+```
 
-Bootsharp 0.8's browser boot API takes the runtime resource root directly. File-system imports must be wired before booting when the JAML library APIs are used:
+## JAML API
 
 ```js
-import bootsharp, { Motely } from "./motely-wasm/index.mjs";
-import { IFileMounter } from "./motely-wasm/bootsharp/file-system.g.mjs";
-import * as fs from "@rewaffle/bootsharp-file-system";
-
-fs.init(IFileMounter);
-await bootsharp.boot("/bin");
-
-const version = Motely.version();
-const result = Motely.loadJaml(`
-must:
-  - joker: Blueprint
-    antes: [1]
-`);
-if (!result.ok) console.error(result.error);
+import { Motely } from "motely-wasm/index";
+
+// Validate a JAML filter string — returns "" on success, error message on failure
+const error = Motely.validateJaml(jaml);
+
+// Get a human-readable explanation of what a JAML filter does
+const explanation = Motely.explainJaml(jaml);
+
+// Inspect the search plan (tally column count, CSV header, labels)
+const plan = Motely.createPlan(jaml);
+
+// Analyze specific seeds against a JAML filter
+const result = Motely.analyzeJamlSeeds(jaml, ["ABCD1234", "XYZ99"]);
+
+// Engine version string
+console.log(Motely.version());
 ```
 
-When serving from the repository root, `/bin` must resolve to `motely-wasm/bin`. If the module is hosted under a subpath, pass that subpath's binary root, for example `await bootsharp.boot("/motely-wasm/bin")`.
+## Running a search
 
-Node usage is not supported: Bootsharp boots by `fetch()`ing wasm/assemblies, and Node's built-in `fetch` does not handle `file://`. Serve the package over HTTP, or run in a real browser.
+```js
+import { Motely } from "motely-wasm/index";
+import { MotelyDeck, MotelyStake } from "motely-wasm/motely";
 
-## Exported Contract
+Motely.onSeedMatch.subscribe(seed => { /* handle match */ });
+Motely.onScoredResult.subscribe(result => { /* result.seed, result.score, result.tallies */ });
+Motely.onProgress.subscribe(progress => { /* progress.percentComplete, .seedsPerMillisecond, … */ });
 
-The generated `Motely` namespace currently exposes these JAML helpers:
+const settings = Motely.createSearchSettings()
+  .withDeck(MotelyDeck.Red)
+  .withStake(MotelyStake.White)
+  .withSequentialSearch()          // enumerate all seeds in order
+  // .withRandomSearch(10_000)     // or pick N random seeds
+  // .withListSearch(seeds, count) // or supply a seed list
+  .withProgressReportIntervalMs(500n);
 
-- `version()` → string (assembly informational version)
-- `loadJaml(yaml)` → `{ ok: boolean, error: string | null }`
-- `explainJaml(yaml)` → `{ ok: boolean, error: string | null, explanation: string | null }`
+const search = settings.createSearch();
 
-And these file-system helpers backed by `Bootsharp.FileSystem`:
+// Synchronous (blocks until done — fine in a Worker)
+search.runSearchUntilCompletion();
 
-- `pickRoot(options?)` → `Promise<string | null>`
-- `mountRoot(root, options?)` → `Promise<string>`
-- `unmountRoot(root)` → `Promise<void>`
-- `readTextFile(root, uri)` → `Promise<string>`
-- `writeTextFile(root, uri, text)` → `Promise<void>`
-- `onFileChanges` — event of `Change[]`
+// Async (yields between batches)
+await search.runSearchAsync(undefined);
+```
 
-Search and seed analysis are not yet exported. `analyzeSeed`, `analyzeJamlSeed`, `analyzeJamlSeeds`, and `searchJamlPage` are planned; track them in `Motely.Wasm/Program.cs` before relying on them.
+## Events
+
+| Event | Payload |
+|---|---|
+| `Motely.onSeedMatch` | `string` — matching seed |
+| `Motely.onScoredResult` | `{ seed, score, tallies }` |
+| `Motely.onProgress` | `MotelyProgress` |
+| `Motely.onFileChanges` | `FileSystem.Change[]` |
+
+Subscribe and unsubscribe:
+
+```js
+const handler = seed => console.log(seed);
+Motely.onSeedMatch.subscribe(handler);
+Motely.onSeedMatch.unsubscribe(handler);
+```
+
+## Submodule exports
+
+| Import path | Contents |
+|---|---|
+| `motely-wasm` | `boot`, `exit`, `getStatus`, `BootStatus`, `manifest` |
+| `motely-wasm/index` | `Motely` namespace (main API) |
+| `motely-wasm/motely` | Types: `MotelyDeck`, `MotelyStake`, `MotelyTag`, `MotelyVoucher`, `MotelyBossBlind`, `MotelyBoosterPack`, enums |
+| `motely-wasm/motely/filters` | `JamlAesthetic`, `JamlSearchPlan` |
+| `motely-wasm/motely/analysis` | `MotelyJamlyzerResult` |
+| `motely-wasm/bootsharp/file-system` | File system interop (browser OPFS) |
+
+## Using in a Web Worker
+
+The WASM runtime is single-threaded. For non-blocking UI, run searches in a Worker:
+
+```js
+// worker.js
+import motely from "motely-wasm";
+import { Motely } from "motely-wasm/index";
+
+await motely.boot("/assets/motely-wasm");
+
+Motely.onSeedMatch.subscribe(seed => postMessage({ type: "match", seed }));
+Motely.onProgress.subscribe(p => postMessage({ type: "progress", p }));
+
+self.onmessage = async ({ data }) => {
+  const search = Motely.createSearch(data.jaml).withSequentialSearch().createSearch();
+  await search.runSearchAsync(undefined);
+  postMessage({ type: "done" });
+};
+```