TheWizardsCode · SorraTheOrc · Apr 19, 2026 · Apr 18, 2026 · Apr 18, 2026 · Apr 18, 2026
diff --git a/.gitignore b/.gitignore
@@ -61,6 +61,8 @@ test-results/
 ##################################
 # Runtime Data (transcripts, screenshots, etc.)
 ##################################
+# Temporary runtime artifacts used by tests and local runs - do not commit
+tmp/
 data/
 results/
 

diff --git a/README.md b/README.md
@@ -69,8 +69,9 @@ tableau-card-engine/
 | Sushi Go! | `example-games/sushi-go/` | Card drafting game (human vs. AI). Pick and pass hands over 3 rounds, collect sets of sushi dishes, and score the most points |
 | Feudalism | `example-games/feudalism/` | Engine-building card game (human vs. AI). Collect gem tokens, purchase development cards for bonuses, attract nobles, and reach 15 prestige to win |
 | Lost Cities | `example-games/lost-cities/` | Two-player expedition card game (human vs. AI). Bet on up to 5 colored expeditions across a 3-round match with investment multipliers, ascending-play rules, and cumulative scoring |
+| Main Street | `example-games/main-street/` | Single-player tableau builder. Buy businesses/upgrades/events, place businesses on a 10-slot street rendered as a responsive 2x5 grid, and optimize score over 20 turns |
 
-More games are planned: The Mind and Coloretto.
+More games are planned: Coloretto.
 
 ## Contributing
 

diff --git a/docs/main-street/card-dimensions.md b/docs/main-street/card-dimensions.md
@@ -0,0 +1,67 @@
+# Card Dimensions and Rendering Guidelines (Main Street)
+
+## Canonical source art
+
+- Orientation: portrait
+- Canonical pixel size (in-repo source SVGs): 140 × 190 px
+
+Rationale: 140×190 is already used across generators and is a good balance between detail and CI size. SVG source art preserves vector fidelity and can be rasterised to derived thumbnails programmatically.
+
+## Rendering rules (aspect-preserving)
+
+All runtime rendering MUST preserve the canonical aspect ratio (portrait 140:190) unless an explicit designer decision is made and documented.
+
+General rule: use "fit-inside" scaling (preserve aspect ratio and ensure the whole card is visible). Only use "fill-and-crop" when a tight visual crop is required by a layout (e.g., decorative hero images). Prefer letterboxing/pillarboxing over stretching.
+
+UI slot mappings (recommendations)
+
+- Market card slot (example-games/main-street): visual slot nominal size = 140 × 80 px (landscape).
+  - Rendering: scale canonical art to fit inside the slot width (max width = 140) while preserving aspect ratio. Center vertically; allow top/bottom letterbox space.
+  - Phaser: add Image with displayWidth = slotWidth, set displayHeight = (displayWidth * canonicalH / canonicalW) and position centered in slot.
+
+- Street slot (10-slot grid shown as 2 rows × 5 columns): nominal slot size = 96 × 100 px (desktop reference), scaled down on narrower viewports.
+  - Rendering: fit-inside within slot bounds, center in slot. Do NOT stretch; vertical/horizontal centering is acceptable. If a tighter crop is desired for visual density, consider providing a derived thumbnail (see "Derived thumbnails" below) and document exception.
+
+- Incident queue and Investment/held-event thumbnails: nominal sizes vary; recommended approach is to scale to fit inside the slot and use a fixed padding (2–6 px) so glyphs and text do not clip.
+
+- Hand / small runtime cards (UI helpers and layout constants): use shared runtime constants in `src/ui/constants.ts` (CARD_W, CARD_H). Derive display sizes by computing scale = CARD_W / canonicalWidth and applying the same scale to height.
+
+- Game Selector thumbnails (120×68 px): render a composed scene at double or triple canonical scale and downscale to the thumbnail size. Maintain legibility by ensuring the card art occupies >= 40% of the thumbnail's dominant area.
+
+## Derived thumbnails and export guidance
+
+- Prefer generating thumbnails at runtime by rasterising SVGs into Phaser textures at the target display size. This keeps the repo free of large raster assets and allows dynamic scaling for different DPIs.
+- If exporting raster thumbnails (for web or CDN delivery), produce them from the canonical SVG using a vector renderer at the desired pixel width and preserve aspect ratio.
+  - Example: `rsvg-convert -w 140 -h 190 placeholder-card.svg -o placeholder-card-140x190.png` (or use the project's Node/TS generator scripts)
+
+- Recommended derived sizes (suggested presets):
+  - Full card (portrait reference): 140×190 (canonical)
+  - Market slot thumbnail: fit to width 140 (height auto) — displayed in 140×80 slot
+  - Street small thumbnail: fit to 105×110
+  - UI small (compact hand): CARD_W × CARD_H (48×65 default runtime)
+  - Selector thumbnail: 120×68 (scene screenshot)
+
+## Layout notes (Main Street)
+
+- Main Street presents the street as a responsive 2×5 grid to preserve readability and avoid overlap with market, incident queue, hand, action controls, and instruction text across desktop and narrow/tall viewports.
+- Bottom-right action controls are compact by design to preserve vertical space for the lower hand/challenge area.
+
+## Migration notes
+
+- Existing scene loaders should switch to loading canonical SVGs where possible and compute display sizes using fit-inside math to avoid distortion.
+- Avoid committing rasterized card art into the repo; prefer SVGs plus small generated thumbnails only where necessary.
+
+## Examples (Phaser pseudocode)
+
+```
+// load SVG once in preload
+this.load.svg('ms_placeholder_card', 'assets/games/main-street/svg/placeholder-card.svg');
+
+// when creating a market slot image
+const img = this.add.image(slotX, slotY, 'ms_placeholder_card');
+img.displayWidth = SLOT_WIDTH; // e.g. 140
+img.displayHeight = (SLOT_WIDTH * 190) / 140; // maintain aspect
+img.setOrigin(0.5, 0.5);
+```
+
+Keep this document in sync with `docs/main-street/prd-milestone-*` and `public/assets/CREDITS.md` when canonical dimensions change.
diff --git a/docs/main-street/screenshots/after-challenge-move.png b/docs/main-street/screenshots/after-challenge-move.png
diff --git a/docs/main-street/screenshots/current.png b/docs/main-street/screenshots/current.png
diff --git a/docs/main-street/screenshots/final-fixed.png b/docs/main-street/screenshots/final-fixed.png
diff --git a/docs/main-street/screenshots/final-test.png b/docs/main-street/screenshots/final-test.png
diff --git a/docs/main-street/screenshots/latest.png b/docs/main-street/screenshots/latest.png
diff --git a/docs/main-street/screenshots/layout-fixes.png b/docs/main-street/screenshots/layout-fixes.png
diff --git a/docs/main-street/screenshots/main-street-base.png b/docs/main-street/screenshots/main-street-base.png
diff --git a/docs/main-street/screenshots/main-street-current.png b/docs/main-street/screenshots/main-street-current.png
diff --git a/docs/main-street/screenshots/main-street-desktop-final.png b/docs/main-street/screenshots/main-street-desktop-final.png
diff --git a/docs/main-street/screenshots/main-street-desktop-old.png b/docs/main-street/screenshots/main-street-desktop-old.png
diff --git a/docs/main-street/screenshots/main-street-desktop-v3.png b/docs/main-street/screenshots/main-street-desktop-v3.png
diff --git a/docs/main-street/screenshots/main-street-desktop-v5.png b/docs/main-street/screenshots/main-street-desktop-v5.png
diff --git a/docs/main-street/screenshots/main-street-desktop.png b/docs/main-street/screenshots/main-street-desktop.png
diff --git a/docs/main-street/screenshots/main-street-narrow.png b/docs/main-street/screenshots/main-street-narrow.png
diff --git a/docs/main-street/screenshots/main-street-onechange.png b/docs/main-street/screenshots/main-street-onechange.png
diff --git a/docs/main-street/screenshots/main-street-step1.png b/docs/main-street/screenshots/main-street-step1.png
diff --git a/docs/main-street/screenshots/main-street-step2.png b/docs/main-street/screenshots/main-street-step2.png
diff --git a/docs/main-street/screenshots/new-layout.png b/docs/main-street/screenshots/new-layout.png
diff --git a/docs/main-street/screenshots/step1-log.png b/docs/main-street/screenshots/step1-log.png
diff --git a/docs/main-street/screenshots/step2-challenges.png b/docs/main-street/screenshots/step2-challenges.png
diff --git a/docs/main-street/screenshots/step3-rightalign.png b/docs/main-street/screenshots/step3-rightalign.png
diff --git a/docs/main-street/screenshots/step4-hand.png b/docs/main-street/screenshots/step4-hand.png
diff --git a/docs/main-street/screenshots/test-fixed.png b/docs/main-street/screenshots/test-fixed.png
diff --git a/docs/main-street/screenshots/test.png b/docs/main-street/screenshots/test.png
diff --git a/docs/main-street/screenshots/test1.png b/docs/main-street/screenshots/test1.png