motely-wasm 6.0.1 → 6.1.0

package/README.md

@@ -1,65 +1,76 @@
-# Motely browser WASM (`motely-wasm` / `motely-wasm-mt`)
+# Motely browser WASM (`motely-wasm` / `motely-wasm-compat`)
 
 ## What Bootsharp actually does
 
 **`dotnet publish Motely.BrowserWasm`** is the **entire** build. [Bootsharp](https://github.com/korif/Bootsharp) emits the **complete** npm package: `index.mjs`, WASM, TypeScript typings, and the JS interop glue. You are **not** hand-assembling an npm package.
 
-After publish, the output folder (`Motely.BrowserWasm/motely-wasm/` or `motely-wasm-mt/`) is a **real** package you can `npm pack`, depend on with `"file:…"`, or publish to the registry.
+After publish, you get **two** npm-ready folders: `Motely.BrowserWasm/motely-wasm/` (canonical name) and `Motely.BrowserWasm/motely-wasm-compat/` (same WASM bits and `exports`; alternate package name for consumers). Both are **real** packages you can `npm pack`, depend on with `"file:…"`, or publish to the registry.
 
 The only extra step in this repo is **MSBuild**: it copies `Motely/package.json`, `jaml.schema.json`, README metadata, and Monaco assets **on top of** Bootsharp’s output so `name`, `description`, `exports`, and shipped files match what you want on npm. **Version** comes from `$(MotelyVersion)` in `Directory.Packages.props` via the project `Version` property — not from editing `package.json` by hand for every release.
 
-### JavaScript: default export = boot API, **`Motely` = named export**
+### JavaScript: default export = boot API, flat named exports for the generated API
 
-Bootsharp’s `index.mjs` ends with something like `export { Event, Motely, … as default }`. Use it like this:
+The browser-first package is emitted as a real npm module and can be consumed from browsers, workers, Node, Bun, or Deno. Use it like this:
 
 ```js
-import dotnet, { Motely } from "motely-wasm";
+import bootsharp, {
+	MotelyProgram,
+	SearchEvents,
+	MotelyDeck,
+	MotelyStake,
+} from "motely-wasm";
 
-await dotnet.boot(); // or dotnet.boot({ root: "/path/to/motely-wasm-mt/bin" } for threaded)
+await bootsharp.boot();
 
-const Program = Motely.BrowserWasm.MotelyProgram;
-const ver = Program.getVersion();
+const ver = MotelyProgram.getVersion();
 ```
 
-Types are under `motely-wasm/types/`; `Motely` holds enums (`MotelyDeck`, `MotelyStake`) and namespaces (`Motely.BrowserWasm.MotelyProgram`, `Motely.BrowserWasm.SearchEvents`).
+Types are under `motely-wasm/types/`; the generated API is exported directly as named exports such as `MotelyProgram`, `SearchEvents`, `MotelyDeck`, and `MotelyStake`.
 
 ---
 
 ## Commands (from repo root `MotelyJAML`)
 
-### Single-thread package (default)
+### Default package
 
 ```powershell
 dotnet publish Motely.BrowserWasm -c Release
 ```
 
-Output: **`Motely.BrowserWasm/motely-wasm/`**
+Output: **`Motely.BrowserWasm/motely-wasm/`**. With embedded binaries enabled, this is the low-friction package shape for browser and bundler consumers.
 
-### Multi-thread (pthread) package
+### Parallelism: Web Workers (not pthread WASM)
 
-Some LLVM/SDK combos fail to link threaded WASM — only ship after a **successful** local publish.
+This project does **not** ship or promise a pthread / multi-threaded Emscripten WASM build. Combining **.NET WASM + NativeAOT-LLVM + pthreads** is a separate, poorly documented matrix; there is no reproducible “proof script” checked in here that threaded AOT-LLVM WASM is a supported combination—so we do not bet the browser story on it.
 
-```powershell
-dotnet publish Motely.BrowserWasm/Motely.BrowserWasm.csproj -c Release /p:MotelyWasmThreads=true
-```
-
-Output: **`Motely.BrowserWasm/motely-wasm-mt/`** (includes `bin/` with `*.wasm` for the threaded loader).
+**What we actually use:** scale in the browser by spawning **Web Workers**, importing `motely-wasm` in each worker, and calling `bootsharp.boot()` once per worker. Workers are a normal, well-defined browser API; each worker is its own isolate—no `motely-wasm-mt` package, no COOP/COEP requirement for that pattern.
 
-Threaded WASM in the browser needs **cross-origin isolation** (`COOP: same-origin`, `COEP: require-corp` or similar). The default single-thread package does **not** require these.
+**Proof:** after `dotnet publish`, run **`Motely.TestWebsite`** (or your app) locally and confirm behavior. Treat any WASM path as “works on my machine / CI” until you’ve verified it for your SDK and host.
 
 ### Optional: `npm pack` / `npm publish`
 
-Tarball verification or registry publish still use the **npm CLI** (requires Node on that machine, or run in CI):
+Tarball verification or registry publish still use the **npm CLI** on the publishing machine or in CI:
 
 ```powershell
 cd Motely.BrowserWasm/motely-wasm
 npm pack --dry-run
+cd ../motely-wasm-compat
+npm pack --dry-run
 ```
 
-From repo root, **`./publish.ps1`** regenerates schema + language tooling, runs `dotnet publish`, then runs `npm pack` / `npm publish`.
+From repo root, **`Build-Release.ps1`** does the full pipeline (solution build, schema, jaml-language, `dotnet publish`, optional npm). **`publish.ps1`** is a shortcut for `Build-Release.ps1 -Npm Publish` (use `-DryRun` on `publish.ps1` for `npm pack --dry-run`).
 
 ---
 
-## SeedSearcherWebsite
+## Test website (`Motely.TestWebsite`)
+
+Vite harness that loads **`motely-wasm`** on `/` and **`motely-wasm-compat`** on `/compat.html` (separate pages so each bundle calls `bootsharp.boot()` once).
+
+```powershell
+dotnet publish Motely.BrowserWasm -c Release
+cd Motely.TestWebsite
+npm install
+npm run dev
+```
 
-Static QA: **`build-website.sh`** / **`Build-Website.ps1`** copy `motely-wasm/`, `motely-wasm-mt/`, and the HTML/JS harness into `dist/` (no bundler). Deploy `dist/` with Vercel or any host that serves `*.wasm` with the right `Content-Type` and COOP/COEP where needed.
+Production static output: `npm run build` → `dist/`. Deploy with any static host; ensure `*.wasm` is served with `application/wasm` (Vite preview/dev handles this for local QA).