LUHJLVTYKV

Author: OptimusPi

.claude/settings.local.json

@@ -25,7 +25,9 @@
       "Bash(grep -E \"\\\\.\\(ps1|sh|mjs\\)$\")",
       "Bash(dotnet run:*)",
       "Bash(dotnet-script /tmp/test_gameplay.cs)",
-      "Bash(\"X:/JammySeedFinder/src/MotelyJAML/.cursorignore\")"
+      "Bash(\"X:/JammySeedFinder/src/MotelyJAML/.cursorignore\")",
+      "Bash(pnpm update:*)",
+      "Bash(pnpm ls:*)"
     ]
   }
 }

.cursor/rules/nextjs-react-generalist-cursor-rules.mdc

@@ -0,0 +1,23 @@
+---
+alwaysApply: true
+---
+
+You are an expert in Web development, including JavaScript, TypeScript, CSS, React, Tailwind, Node.js, and Next.js. You excel at selecting and choosing the best tools, avoiding unnecessary duplication and complexity.
+
+      When making a suggestion, you break things down into discrete changes and suggest a small test after each stage to ensure things are on the right track.
+
+      Produce code to illustrate examples, or when directed to in the conversation. If you can answer without code, that is preferred, and you will be asked to elaborate if it is required. Prioritize code examples when dealing with complex logic, but use conceptual explanations for high-level architecture or design patterns.
+
+      Before writing or suggesting code, you conduct a deep-dive review of the existing code and describe how it works between <CODE_REVIEW> tags. Once you have completed the review, you produce a careful plan for the change in <PLANNING> tags. Pay attention to variable names and string literals—when reproducing code, make sure that these do not change unless necessary or directed. If naming something by convention, surround in double colons and in ::UPPERCASE::.
+
+      Finally, you produce correct outputs that provide the right balance between solving the immediate problem and remaining generic and flexible.
+
+      You always ask for clarification if anything is unclear or ambiguous. You stop to discuss trade-offs and implementation options if there are choices to make.
+
+      You are keenly aware of security, and make sure at every step that we don't do anything that could compromise data or introduce new vulnerabilities. Whenever there is a potential security risk (e.g., input handling, authentication management), you will do an additional review, showing your reasoning between <SECURITY_REVIEW> tags.
+
+      Additionally, consider performance implications, efficient error handling, and edge cases to ensure that the code is not only functional but also robust and optimized.
+
+      Everything produced must be operationally sound. We consider how to host, manage, monitor, and maintain our solutions. You consider operational concerns at every step and highlight them where they are relevant.
+
+      Finally, adjust your approach based on feedback, ensuring that your suggestions evolve with the project's needs.

AGENTS.md

@@ -4,6 +4,12 @@
 
 A .NET library + WASM/Node packages for Balatro seed analysis. It predicts what items, jokers, tags, vouchers, etc. a given seed will produce using Balatro's PRNG system.
 
+### Call it JAML
+
+Filter documents are **JAML** (`.jaml`). In user-facing prose and comments, prefer **JAML** over “YAML” — *YAML Ain’t Motely’s Language.* (YamlDotNet is still the parser; that’s implementation.)
+
+Optional top-level **`aesthetics`** (e.g. `- palindrome`) is parsed from the JAML document and merged in `MotelySearchOrchestrator.PrepareSearch` when it doesn’t conflict with the host’s seeds / keywords / random mode.
+
 ## Architecture: Two Thin Hosts, One Brain
 
 ```
@@ -18,6 +24,16 @@ motely-node/   ← Node.js native addon output (published to npm)
 
 Both are **OUTPUT DIRECTORIES**. They are populated by `build-and-pack.ps1`.
 
+### JAML JSON schema — no hand edits, no drift
+
+`jaml.schema.json`, `jaml-schema.js`, and `jaml-schema.d.ts` are **generated from C#** by `Motely.CLI`:
+
+```bash
+dotnet run --project Motely.CLI/Motely.CLI.csproj -- --write-jaml-schema
+```
+
+`JamlSchemaGenerator` writes the same content to every mirror path (repo root, `public/`, `Motely.NodeAddon/`, `motely-wasm/`, `motely-node/`). `build-and-pack.ps1` runs this step after version bump so packs stay consistent. Do **not** edit those files manually: you will fork copies, break the npm pipeline, and fight the next generator run. New JAML surface area (e.g. `JamlAesthetic` values) belongs in **`Motely.CLI/JamlSchemaGenerator.cs`** and in the parser/enum in **`Motely`**, then regenerate.
+
 ### The Layering Rule
 
 ```
@@ -40,7 +56,6 @@ Platform hosts (WASM/Node)  →  MotelySearchOrchestrator  →  Motely (core lib
 - Any file authored by TacoDiva (the Motely library author)
 
 ### Files YOU should edit:
-- `Motely/MotelyGameplayState.cs` — our game state wrapper
 - `Motely.Orchestration/MotelySearchOrchestrator.cs` — all search logic lives here
 - `Motely.Orchestration/MotelySearchSession.cs` — browser instance handles / cancellation
 - `Motely.BrowserWasm/Interop/` — Bootsharp interfaces + implementation (calls orchestrator)
@@ -81,37 +96,35 @@ Every PRNG stream's state is ultimately a `double`. `MotelySinglePrngStream(doub
 
 ### ref struct vs struct
 
-Some stream types are `ref struct` (stack-only, cannot be stored on the heap). When you need to store a `ref struct` as a class field, decompose its fields into a storage struct (they're just doubles and strings), then reconstruct on demand. See `StreamCache` in `MotelyGameplayState.cs`.
+Some stream types are `ref struct` (stack-only, cannot be stored on the heap). When you need to store a `ref struct` as a class field, decompose its fields into a storage struct (they're just doubles and strings), then reconstruct on demand.
 
 Do NOT change `ref struct` to `struct` in core Motely files. Work around it.
 
-### The Parked Filter Pattern
-
-`MotelyGameplayState` uses the search pipeline as a **context factory**. It parks a filter on a background thread via semaphores, keeping a `MotelySingleSearchContext` alive on the stack indefinitely. This is the ONLY way to get a context for single-seed analysis.
-
-**DO NOT touch the parked filter code** (`ParkedFilterDesc`, `ParkedFilter`, `CheckSeed`, the semaphore dance). It is correct.
+### analyzeSeed Returns a Fixed Snapshot
 
-**DO NOT touch the `Cmd<T>` delegate dispatch.** It is correct.
+`MotelySeedAnalyzer.AnalyzeToDto()` pre-computes a fixed set of items for antes 1-8: boss, voucher, tags, draw order, shop queue, packs. This is NOT infinite — it's a snapshot. The shop queue list is finite and exhaustible.
 
 ### One Ante At A Time
 
 The game state represents sequential gameplay. One ante at a time. When the ante changes, reset streams. Do NOT use `Dictionary<int, StreamType>` to cache per-ante.
 
-### MotelyGameplayState IS the Single Seed Context
+### TODO: MotelyGameplayState (Not Yet Implemented)
 
-It's a stateful object that wraps `MotelySingleSearchContext` for one seed. You create it, call `NextShopItem(ante)` repeatedly, and it advances the PRNG. Infinite scroll. Don't pre-compute, don't batch, don't wrap the analyzer.
+Infinite shop item streaming requires a stateful C# object that wraps `MotelySingleSearchContext` for one seed, advancing the shop PRNG on each call (e.g. `createSeedContext → nextShopItem(ante)`). This does NOT exist yet. Today, infinite shop streaming only works on the TypeScript Game path. Building this on the Motely/WASM side requires:
+1. A new C# class (`MotelyGameplayState`) that holds live PRNG state
+2. New WASM exports: `createSeedContext(seed, deck, stake)` → contextId, `nextShopItem(contextId, ante)` → item
+3. JS glue in `motelyWasm.ts` to manage context lifecycle
 
 ## Common Pitfalls
 
 1. **"Let me redesign the architecture"** — No. Make the minimal fix. Use what exists.
 2. **"Let me add a shared interop API class"** — No. Both hosts call orchestrator directly.
-3. **"Let me wrap the analyzer output"** — No. The analyzer pre-computes a fixed set. GameState is infinite scroll.
+3. **"Let me wrap the analyzer output"** — No. The analyzer pre-computes a fixed snapshot. It is not infinite.
 4. **"Let me add a Dictionary for caching"** — No. One ante at a time. Direct fields, reset on ante change.
-5. **"Let me create a new search/filter"** — No. The parked filter IS the mechanism. Use it.
-6. **"Let me edit MotelySingleSearchContext"** — No. Use Motely. Don't edit it.
-7. **"Let me edit the output JS/CJS files"** — No. They're build output.
-8. **"These stream types should be struct not ref struct"** — Don't change core Motely types.
-9. **"Let me hand-roll PRNG logic"** — No. Motely provides high-level stream interfaces. Use them.
+5. **"Let me edit MotelySingleSearchContext"** — No. Use Motely. Don't edit it.
+6. **"Let me edit the output JS/CJS files"** — No. They're build output.
+7. **"These stream types should be struct not ref struct"** — Don't change core Motely types.
+8. **"Let me hand-roll PRNG logic"** — No. Motely provides high-level stream interfaces. Use them.
 
 ## Build
 

Directory.Packages.props

@@ -1,7 +1,7 @@
 <Project>
   <PropertyGroup>
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
-    <MotelyVersion>4.0.1</MotelyVersion>
+    <MotelyVersion>4.0.2</MotelyVersion>
   </PropertyGroup>
   <ItemGroup>
     <PackageVersion Include="Bootsharp" Version="0.7.0" />

Motely.BrowserWasm/Interop/IMotelyWasmBackend.cs

@@ -34,4 +34,10 @@ Task<string> StartPalindromeSearch(
 
     Task<bool> ValidateJaml(string jamlContent);
     Task<string> ValidateJamlWithError(string jamlContent);
+
+    /// <summary>
+    /// Infinite shop item stream: get <paramref name="count"/> items starting at <paramref name="offset"/>
+    /// for a given seed/deck/stake/ante. Deterministic and stateless — same inputs always produce same output.
+    /// </summary>
+    Task<string> GetShopItems(string seed, string deck, string stake, int ante, int offset, int count);
 }

Motely.BrowserWasm/Interop/MotelyWasmBackend.cs

@@ -114,6 +114,19 @@ public Task<string> ValidateJamlWithError(string jamlContent)
         return Task.FromResult(error ?? "Unknown validation error");
     }
 
+    public Task<string> GetShopItems(string seed, string deck, string stake, int ante, int offset, int count)
+    {
+        try
+        {
+            var json = MotelyShopItemProvider.GetShopItems(seed, deck, stake, ante, offset, count);
+            return Task.FromResult(json);
+        }
+        catch (Exception ex)
+        {
+            return Task.FromResult($"{{\"error\":\"{ex.Message}\"}}");
+        }
+    }
+
     private async Task<string> RunSearch(int instanceId, string jamlContent, MotelySearchRequest request)
     {
         var session = MotelySearchSession.Get(instanceId);

Motely.CLI/JamlSchemaGenerator.cs

@@ -9,7 +9,7 @@ internal static class JamlSchemaGenerator
 {
     private static readonly string[] RankValues = ["2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Jack", "Q", "Queen", "K", "King", "A", "Ace"];
     private static readonly string[] SuitValues = ["Hearts", "Diamonds", "Clubs", "Spades"];
-    private static readonly string[] MetadataKeys = ["name", "author", "dateCreated", "description", "deck", "stake", "seeds"];
+    private static readonly string[] MetadataKeys = ["name", "author", "dateCreated", "description", "deck", "stake", "seeds", "aesthetics"];
     private static readonly string[] SectionKeys = ["defaults", "must", "should", "mustNot"];
     private static readonly string[] ClauseTypeKeys = [
         "joker", "jokers",
@@ -152,14 +152,29 @@ private static JsonObject Generate(string version)
                 ["deck"] = EnumStringProperty(EnumNames<MotelyDeck>(), "Balatro deck to search with", "Red"),
                 ["stake"] = EnumStringProperty(EnumNames<MotelyStake>(), "Balatro stake level", "White"),
                 ["seeds"] = StringArrayProperty("Known seed examples associated with this filter."),
+                ["aesthetics"] = new JsonObject
+                {
+                    ["type"] = "array",
+                    ["description"] =
+                        "Optional seed-space constraints from JamlAesthetic (see definitions/JamlAesthetic). Merged in MotelySearchOrchestrator when compatible; conflicts with host seeds, keywords, or random mode.",
+                    ["items"] = new JsonObject { ["$ref"] = "#/definitions/JamlAesthetic" },
+                },
                 ["defaults"] = BuildDefaultsProperty(),
                 ["must"] = ClauseArray("Required clauses. All listed clauses must match."),
                 ["should"] = ClauseArray("Scored clauses. Matching clauses add score but do not gate the seed by themselves."),
                 ["mustNot"] = ClauseArray("Rejected clauses. If any listed clause matches, the seed is rejected.")
             },
             ["definitions"] = new JsonObject
             {
-                ["clause"] = BuildClauseDefinition()
+                ["clause"] = BuildClauseDefinition(),
+                ["JamlAesthetic"] = new JsonObject
+                {
+                    ["title"] = "JamlAesthetic",
+                    ["description"] =
+                        "Named constraint on which seeds participate in search. Motely: see JamlAesthetics for enumeration and Matches(); seed alphabet is MotelyCore.SeedDigits, max length MotelyCore.MaxSeedLength.",
+                    ["type"] = "string",
+                    ["enum"] = ToJsonArray(JamlAestheticParser.KnownJamlStringsForSchema()),
+                },
             },
             ["additionalProperties"] = false
         };
@@ -532,6 +547,7 @@ private static Dictionary<string, string[]> BuildValueSets()
     {
         return new()
         {
+            ["aesthetics"] = JamlAestheticParser.KnownJamlStringsForSchema(),
             ["deck"] = EnumNames<MotelyDeck>(),
             ["stake"] = EnumNames<MotelyStake>(),
             ["joker"] = EnumNames<MotelyJoker>(),

Motely.NodeAddon/MotelyNodeExports.cs

@@ -88,4 +88,12 @@ public static BlockSearchResultDto RunPalindromeSearchAsync(string jamlContent)
             BatchCharCount = ProcessBlockRunner.BatchCharCount,
             Palindrome = true,
         });
+
+    /// <summary>
+    /// Infinite shop item stream: get <paramref name="count"/> items starting at <paramref name="offset"/>.
+    /// Stateless and deterministic — same inputs always produce same output.
+    /// Returns JSON array of {id, name} objects.
+    /// </summary>
+    public static string GetShopItems(string seed, string deck, string stake, int ante, int offset, int count) =>
+        MotelyShopItemProvider.GetShopItems(seed, deck, stake, ante, offset, count);
 }

Motely.NodeAddon/jaml-schema.js

@@ -1,8 +1,8 @@
-export const JAML_SCHEMA_VERSION = "4.0.1";
+export const JAML_SCHEMA_VERSION = "4.0.2";
 export const jamlSchema = {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://seedfinder.app/jaml.schema.json",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "title": "JAML - Jimbo\u0027s Ante Markup Language",
   "description": "Schema for Balatro seed filter configuration files (.jaml)",
   "type": "object",
@@ -68,6 +68,13 @@ export const jamlSchema = {
       },
       "description": "Known seed examples associated with this filter."
     },
+    "aesthetics": {
+      "type": "array",
+      "description": "Optional seed-space constraints from JamlAesthetic (see definitions/JamlAesthetic). Merged in MotelySearchOrchestrator when compatible; conflicts with host seeds, keywords, or random mode.",
+      "items": {
+        "$ref": "#/definitions/JamlAesthetic"
+      }
+    },
     "defaults": {
       "type": "object",
       "description": "Default values applied to clauses when a clause does not specify its own values.",
@@ -1700,6 +1707,14 @@ export const jamlSchema = {
       ],
       "additionalProperties": false,
       "minProperties": 1
+    },
+    "JamlAesthetic": {
+      "title": "JamlAesthetic",
+      "description": "Named constraint on which seeds participate in search. Motely: see JamlAesthetics for enumeration and Matches(); seed alphabet is MotelyCore.SeedDigits, max length MotelyCore.MaxSeedLength.",
+      "type": "string",
+      "enum": [
+        "palindrome"
+      ]
     }
   },
   "additionalProperties": false
@@ -1711,7 +1726,8 @@ export const METADATA_KEYS = [
   "description",
   "deck",
   "stake",
-  "seeds"
+  "seeds",
+  "aesthetics"
 ];
 export const SECTION_KEYS = [
   "defaults",
@@ -1808,6 +1824,9 @@ export const SOURCE_KEYS = [
 ];
 
 const VALUE_SETS = {
+  "aesthetics": [
+    "palindrome"
+  ],
   "deck": [
     "Red",
     "Blue",

Motely.NodeAddon/jaml.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://seedfinder.app/jaml.schema.json",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "title": "JAML - Jimbo\u0027s Ante Markup Language",
   "description": "Schema for Balatro seed filter configuration files (.jaml)",
   "type": "object",
@@ -67,6 +67,13 @@
       },
       "description": "Known seed examples associated with this filter."
     },
+    "aesthetics": {
+      "type": "array",
+      "description": "Optional seed-space constraints from JamlAesthetic (see definitions/JamlAesthetic). Merged in MotelySearchOrchestrator when compatible; conflicts with host seeds, keywords, or random mode.",
+      "items": {
+        "$ref": "#/definitions/JamlAesthetic"
+      }
+    },
     "defaults": {
       "type": "object",
       "description": "Default values applied to clauses when a clause does not specify its own values.",
@@ -1699,6 +1706,14 @@
       ],
       "additionalProperties": false,
       "minProperties": 1
+    },
+    "JamlAesthetic": {
+      "title": "JamlAesthetic",
+      "description": "Named constraint on which seeds participate in search. Motely: see JamlAesthetics for enumeration and Matches(); seed alphabet is MotelyCore.SeedDigits, max length MotelyCore.MaxSeedLength.",
+      "type": "string",
+      "enum": [
+        "palindrome"
+      ]
     }
   },
   "additionalProperties": false