jaml-ui 0.31.0 → 0.32.2

package/README.md

@@ -1,30 +1,104 @@
 # jaml-ui
 
-React components, UI tokens, sprites, and utilities for Balatro/JAML apps.
+React components, UI tokens, sprites, and utilities for Balatro/JAML seed-finder apps.
+
+Wraps [motely-wasm](https://www.npmjs.com/package/motely-wasm) — the Bootsharp-built WebAssembly port of the C# Motely seed engine — and ships a Balatro-styled design system called **Jimbo**.
 
 ## Install
 
 ```bash
-npm install jaml-ui react react-dom
+npm install jaml-ui motely-wasm react react-dom
 ```
 
+The CSS is loaded automatically as a side-effect import. No PostCSS, no Tailwind, no config.
+
+## Boot motely-wasm before rendering
+
+`motely-wasm` is a Bootsharp module. Boot it once at app startup, before React mounts. Two requirements:
+
+1. Top-level `await bootsharp.boot(<bin path>)` in your entry point.
+2. The `motely-wasm/bin/*` files must be served at that path. Copy them into your `public/` (Vite) or wire a static route (Next.js).
+
+```ts
+// src/main.tsx
+import "jaml-ui/jimbo.css"; // already side-effect-imported by jaml-ui; safe either way
+import { createRoot } from "react-dom/client";
+import bootsharp from "motely-wasm";
+import App from "./App";
+
+await bootsharp.boot("/motely-wasm/bin");
+createRoot(document.getElementById("root")!).render(<App />);
+```
+
+Vite serves `/motely-wasm/bin` if you copy `node_modules/motely-wasm/bin` into `public/motely-wasm/bin/`. See `examples/seed-finder` for a working setup.
+
+> If you can't use top-level await (legacy Webpack, server components), the hooks (`useSearch`, `useAnalyzer`, `useJamlLibrary`) inline a Standby-guard and will boot lazily on first call. The top-level pattern is still preferred — it removes the boot wait from the first interaction.
+
+## Quick start — a real seed finder in ~30 lines
+
+```tsx
+import { useState } from "react";
+import { JamlIde, useSearch, type JamlIdeSearchResult } from "jaml-ui";
+
+const STARTER_JAML = `must:\n  - joker: Blueprint\n    antes: [1,2,3,4,5,6,7,8]\ndeck: Red\nstake: White\n`;
+
+export default function App() {
+  const [jaml, setJaml] = useState(STARTER_JAML);
+  const search = useSearch();
+
+  const results: JamlIdeSearchResult[] = search.results.map((r) => ({
+    seed: r.seed,
+    score: r.score,
+    tallyColumns: r.tallyColumns,
+  }));
+
+  return (
+    <JamlIde
+      jaml={jaml}
+      onChange={setJaml}
+      searchResults={results}
+      isSearching={search.status === "running"}
+      onSearch={() => search.startAesthetic(jaml, /* aesthetic */ 0)}
+    />
+  );
+}
+```
+
+That's the whole integration. `useSearch` handles boot guarding, search lifecycle, progress events, and result accumulation; `JamlIde` renders the editor, visual filter, results column, and toolbar.
+
 ## Package exports
 
-| Entry | Contents |
-| ----- | -------- |
-| `jaml-ui` | Game card components, JAML IDE, hooks |
-| `jaml-ui/ui` | Jimbo design system — JimboPanel, JimboButton, JimboModal, tokens |
-| `jaml-ui/core` | Pure asset helpers, sprite metadata, decode utilities (no React) |
-| `jaml-ui/motely` | motely-wasm decode helpers (requires `motely-wasm` peer) |
-| `jaml-ui/r3f` | 3D card component via React Three Fiber (requires r3f peers) |
+Five subpath entries, each a barrel. The public API is exactly what they re-export.
 
-## Quick start
+| Entry | What's in it | When you import it |
+| ----- | ------------ | ------------------ |
+| `jaml-ui` | Game cards, JAML IDE, search hooks | The default surface — most apps only need this |
+| `jaml-ui/ui` | Jimbo design system (JimboPanel, JimboButton, JimboModal, tokens) | Building custom Balatro-styled UI |
+| `jaml-ui/core` | Sprite metadata, asset URLs, canvas `Layer` — pure, **no React, no motely-wasm** | Next.js server components, server-side rendering |
+| `jaml-ui/motely` | Re-exports `bootsharp` + `Motely` from motely-wasm, plus item-decode helpers and `useJamlLibrary` | Direct motely-wasm access, file-system mount |
+| `jaml-ui/r3f` | 3D card via React Three Fiber | Optional, has its own peer deps |
 
 ```tsx
-import { JamlGameCard, JamlIde } from "jaml-ui";
-import { JimboPanel, JimboButton } from "jaml-ui/ui";
+import { JamlGameCard, useSearch } from "jaml-ui";
+import { JimboPanel, JimboButton, JimboColorOption } from "jaml-ui/ui";
+import { resolveJamlAssetUrl, SPRITE_SHEETS } from "jaml-ui/core";
+import { Motely, decodeMotelyItemName } from "jaml-ui/motely";
+```
+
+## Examples
+
+| Path | What it shows |
+| ---- | ------------- |
+| `examples/seed-finder` | End-to-end Vite app: boots motely-wasm, renders `JamlIde`, runs real searches. Copy it, point it at your published `jaml-ui`, ship. |
+
+```bash
+cd examples/seed-finder
+pnpm install
+pnpm dev
 ```
 
+## Core components
+
 ### Game card
 
 ```tsx
@@ -36,21 +110,10 @@ import { JamlGameCard } from "jaml-ui";
 />
 ```
 
-### Jimbo UI (Balatro design system)
-
-```tsx
-import { JimboPanel, JimboButton, JimboModal } from "jaml-ui/ui";
-import { JimboColorOption } from "jaml-ui/ui";
-
-<JimboPanel sway onBack={() => setOpen(false)}>
-  <JimboButton variant="primary" onClick={handleSearch}>Search</JimboButton>
-</JimboPanel>
-```
-
-Available variants: `primary`, `secondary`, `danger`, `back`, `ghost`
-
 ### JAML IDE
 
+The full editor — code view, visual filter, results column, toolbar — in one component:
+
 ```tsx
 import { JamlIde } from "jaml-ui";
 
@@ -63,7 +126,15 @@ import { JamlIde } from "jaml-ui";
 />
 ```
 
-### JAML Map Preview
+### Standalone code editor
+
+```tsx
+import { JamlCodeEditor } from "jaml-ui";
+
+<JamlCodeEditor value={jaml} onChange={setJaml} />
+```
+
+### JAML map preview
 
 ```tsx
 import { JamlMapPreview } from "jaml-ui";
@@ -71,73 +142,134 @@ import { JamlMapPreview } from "jaml-ui";
 <JamlMapPreview jaml={jaml} />
 ```
 
-## Core utilities
+### Jimbo UI primitives
 
-```ts
-import { SPRITE_SHEETS, getSpriteData, resolveJamlAssetUrl } from "jaml-ui/core";
+```tsx
+import { JimboPanel, JimboButton, JimboModal } from "jaml-ui/ui";
+
+<JimboPanel sway onBack={() => setOpen(false)}>
+  <JimboButton variant="primary" onClick={handleSearch}>Search</JimboButton>
+</JimboPanel>
 ```
 
-## Motely decode helpers
+Button variants: `primary`, `secondary`, `danger`, `back`, `ghost`.
+
+## Hooks
+
+All hooks lazily boot motely-wasm on first call if you skipped the top-level `bootsharp.boot()`.
+
+### `useSearch()` — run JAML filter searches
 
 ```ts
-import { decodeMotelyItemName, motelyItemTypeName } from "jaml-ui/motely";
+import { useSearch } from "jaml-ui";
+
+const {
+  results,           // SearchResult[]
+  status,            // "idle" | "running" | "completed" | "cancelled" | "error"
+  totalSearched,     // bigint
+  matchingSeeds,     // bigint
+  seedsPerSecond,    // number
+  error,             // string | null
+  startAesthetic,    // (jaml, aesthetic) => Promise<void>
+  startSeedList,     // (jaml, seeds[]) => Promise<void>
+  startRandom,       // (jaml, count) => Promise<void>
+  cancel,
+  reset,
+  clearError,
+} = useSearch();
 ```
 
-## 3D card (optional)
+### `useAnalyzer()` — analyze a known seed
 
-```bash
-npm install three @react-three/fiber @react-three/drei @react-spring/three
+```ts
+import { useAnalyzer } from "jaml-ui";
+const { status, result, error, analyze } = useAnalyzer();
+await analyze(jaml, "ALEEB");
 ```
 
+### `useSearchPool()` — multi-worker parallel search
+
+For long searches, spreads work across a pool of web workers.
+
+### `useJamlLibrary()` — browser file picker for `.jaml` files
+
 ```tsx
-import { Card3D } from "jaml-ui/r3f";
+import { useJamlLibrary } from "jaml-ui/motely";
 
-<Card3D itemName="Blueprint" />
+const library = useJamlLibrary();
+await library.mount();                              // prompts user to pick a folder
+const source = await library.loadFile(library.files[0]);
+await library.saveFile("filters/example.jaml", source);
 ```
 
-## Next.js
+Requires `@rewaffle/bootsharp-file-system` (optional peer). When absent, `status === "unsupported"`.
 
-Import pure helpers from `jaml-ui/core` for server components. For local workspace installs add:
+## Core utilities (no React)
 
 ```ts
-// next.config.ts
-const nextConfig = { transpilePackages: ["jaml-ui"] };
+import { SPRITE_SHEETS, getSpriteData, resolveJamlAssetUrl, Layer } from "jaml-ui/core";
 ```
 
-## Search Worker Architecture
+`resolveJamlAssetUrl(key)` returns a bundled asset URL — Vite imports the PNGs at build time, so consumers don't have to wire any base URL.
 
-The library provides `useSearch` and `useAnalyzer` helpers that use `motely-wasm`'s Bootsharp-generated ES module directly. Bootsharp handles the runtime bridge: import the generated package, boot the package `bin/` directory, then call `Motely`.
+## Motely decode helpers
 
 ```ts
-import bootsharp, { Motely } from "motely-wasm";
+import {
+  decodeMotelyItem,
+  decodeMotelyItemName,
+  motelyItemDisplayName,
+  motelyItemTypeName,
+} from "jaml-ui/motely";
+```
 
-await bootsharp.boot("/motely-wasm/bin");
-const status = Motely.validateJaml(jaml);
+## 3D card (optional)
+
+```bash
+npm install three @react-three/fiber @react-three/drei @react-spring/three
 ```
 
 ```tsx
-import { useSearch, useJamlLibrary } from "jaml-ui/motely";
+import { Card3D } from "jaml-ui/r3f";
 
-// result: { seed: string, score: number, tallyColumns?: number[] }
+<Card3D itemName="Blueprint" />
 ```
 
-`useJamlLibrary` wires Bootsharp.FileSystem when `@rewaffle/bootsharp-file-system` is available, letting browser users pick a local JAML folder and read/write files through Motely's generated WASM API:
+## Next.js
 
-```tsx
-const library = useJamlLibrary();
-await library.mount();
+- Use `jaml-ui/core` from server components — it has no React and no motely-wasm imports.
+- Use `jaml-ui` / `jaml-ui/motely` only from client components (mark the file with `"use client"`).
+- Serve `motely-wasm/bin` at `/motely-wasm/bin` via a public folder or a catch-all route, then call `await bootsharp.boot("/motely-wasm/bin")` from a client component or your client entry script.
+- If you're consuming this as a workspace package:
 
-const source = await library.loadFile(library.files[0]);
-await library.saveFile("filters/example.jaml", source);
-```
+  ```ts
+  // next.config.ts
+  const nextConfig = { transpilePackages: ["jaml-ui"] };
+  ```
 
 ## Peer dependencies
 
-| Peer | Required for |
-| ---- | ------------ |
-| `react`, `react-dom` | All components |
-| `react-icons` | Components that render icons (optional peer) |
-| `@rewaffle/bootsharp-file-system` | Optional JAML library folder mount support |
-| `three`, `@react-three/fiber`, `@react-three/drei`, `@react-spring/three` | `jaml-ui/r3f` only |
+| Peer | Required for | Optional? |
+| ---- | ------------ | --------- |
+| `react`, `react-dom` | All components | No |
+| `motely-wasm` | All search/analyzer/decode functionality | No (direct dep) |
+| `react-icons` | Components that render icons | Yes |
+| `@rewaffle/bootsharp-file-system` | `useJamlLibrary` folder mount | Yes |
+| `three`, `@react-three/fiber`, `@react-three/drei`, `@react-spring/three` | `jaml-ui/r3f` only | Yes |
+
+## Troubleshooting
+
+- **"Motely is not initialized"** — you didn't call `bootsharp.boot()` before rendering, and the lazy guard hasn't fired yet. Add `await bootsharp.boot("/motely-wasm/bin")` to your entry point.
+- **`404 /motely-wasm/bin/...`** — copy `node_modules/motely-wasm/bin/` into `public/motely-wasm/bin/` (Vite) or add a static route (Next.js).
+- **CSS not applied** — make sure you imported from `jaml-ui` or `jaml-ui/ui` at least once. Both pull in `jimbo.css` as a side effect. If your bundler strips side-effect imports, add `import "jaml-ui/jimbo.css"`.
+- **Storybook hangs on boot** — Storybook's `staticDirs` already serves `motely-wasm/bin`; see `.storybook/main.ts` for the pattern.
+
+## Fonts
+
+Jimbo UI uses **m6x11** and **m6x11plus** (`.ttf` in `assets/fonts/`). Fonts by [Daniel Linssen](https://managore.itch.io/) — free to use with attribution. If you ship an app that shows this UI, include that credit in your README or notices.
+
+Code blocks use **JetBrains Mono** / system monospace via `--j-font-code`, not the pixel fonts.
+
+## License
 
-`motely-wasm` is a direct dependency (currently `^17.7.0`) — it ships with `jaml-ui` rather than as a peer, but is externalized from the bundle so consumers control how the Bootsharp runtime is served (see *Search Worker Architecture* above).
+MIT — see [LICENSE](LICENSE). Font files are separate third-party assets; attribution to Daniel Linssen is required when redistributing or displaying the pixel fonts.

package/assets/fonts/README.md

@@ -0,0 +1,14 @@
+# Fonts
+
+| File | Family | Notes |
+|------|--------|--------|
+| `m6x11.ttf` | `m6x11` | Base pixel font. Prefer sizes 16, 32, 48, … |
+| `m6x11plus.ttf` | `m6x11plus` | Extended charset (+6 width, taller metrics). Prefer 18, 36, 54, … |
+
+`m6x11plusplus.otf` is a legacy bundle copy; **do not use** for new work — use the `.ttf` files above.
+
+## Attribution
+
+UI fonts by [Daniel Linssen](https://managore.itch.io/) — free to use with attribution.
+
+Include credit in your app README or notices when shipping jaml-ui consumers (for example: “UI fonts by Daniel Linssen — https://managore.itch.io/”).