## July 28, 2026 (All 101 remaining charms regenerated — bold-icon 古惑仔)
- The 101 charm icons that predated the locked bold-icon style (the original generic batch + the muddy full-scene batch) are all regenerated in the house style: one centred subject, high contrast, readable at 26px. Every charm, consumable, voucher, pack, bane and hot zone now shares one visual language.

## July 13, 2026 (Title 歲 · tall tile faces · bamboo 6/7/8 · boss-card Close · UI glyph art)
- TITLE FIX: the landing title's second character 歲 was mis-drawn (missing the 止 radical — read like 威). Replaced with the true DFKai-SB (kaiu.ttf) glyph rendered in the same red-with-black-outline style. Structurally correct by construction.
- TILE FACES are now TALL (100×135 face area, was a 37px square): dots, bamboo, and the White Dragon all fill the tile's portrait aspect.
- WHITE DRAGON 白板: frame pattern is now a tall rectangle matching the tile aspect (never a square).
- BAMBOO 6/7/8 fixed to traditional stick arrangements: 6 = 3+3, 7 = 1/3/3, 8 = 4+4 (previously reused the dot grids: 2×3 / 1+2×3 / 2×4).
- BOSS CARD from the cheat menu's boss list is a preview — its button now says "✖ Close 關閉" instead of the misleading "⚔ Fight 開戰" (real boss intros still say Fight).
- NEW ART: WALL button (tile-wall icon), Dragon TAIL button (dragon-tail icon), and all 8 flower/season tile faces (梅蘭菊竹春夏秋冬) — emoji only as fallback. DRAW button bird now uses the sparrow art.

## July 13, 2026 (Flower reveal — duplicate flower fix)
- FIX: at blind start you could see a flower already sitting on the board while "another one" animated toward it. Cause: when the opening hand had no valid start group, the anti-dead-hand redeal (_ensurePlayableHand) created tile divs AND laid the flowers out — then the dealer (init) unconditionally created a second div for every tile, orphaning the first set in the DOM. The orphaned flower stayed visibly parked at the flower row underneath its animated twin, and survived across blinds (init only removed meshMap-tracked divs).
- _ensurePlayableHand is now data-only (no divs, no layout — the dealer builds all visuals), init() removes a stale div before creating a tile's new one, and blind start sweeps ALL .tile2d from the scene so no untracked orphan can ever persist.

## July 13, 2026 (Packs & everything else — emoji fully replaced with art)
- All remaining emoji item-surfaces now render generated 古惑仔 art (emoji only as missing-file fallback):
  - Pack draft screen: pack chest icons + every item preview line; pack opening overlay (title, item cards, bane card, bane notice); Devil's Bargain confirm dialog.
  - Shop: booster-pack cards and the sell-a-charm cards.
  - Discard-a-charm picker, dice hot zones, Next Challenge stake card/button, and the ⓘ card-info popup (now shows the item's art large).
- NEW ART (22 icons, house 古惑仔 bold-icon style): 7 pack chests (Copper Chest, Gilded Coffer, Treasure Trove, Bronze Vault, Silver Archive, Golden Hoard, Cursed Tomb), 9 banes (Blood Tax, Heavy Air, Dry Well, Cracked Tile, Short Table, Stuck, Fading, Rent Due, Loan Shark 大耳窿), 5 dice hot zones (Flower Garden, Dragon's Nest, Honour Vein, Cursed Stretch, Golden Seam), and the Wild Tile pack item.
- Pack defs + the Wild Tile pack item gained ids (pack_<tier>, wild_tile) so the shared _icHTML image pipeline keys them.
- Not converted (by design): <select> dropdown options (HTML can't put images in options) and transient text toasts.

## July 13, 2026 (White Dragon tile + Draw button badge)
- FIX: the White Dragon (白板) tile was drawn as the character 白. It's not a word — traditionally it's a blank tile marked only by a blue rectangular frame. Now rendered as a carved blue double-stroke frame pattern (mjTileFace special-cases tile.dragon==='white' → _mjWhiteDragonSVG). Red 中 and Green 發 dragons unchanged.
- FIX: the Draw button's remaining-tile count badge was clipped at the top-right corner. When a deck back is active the button uses overflow:hidden to contain the art, which cut off the badge (it sat at negative top/right). The badge is now pulled inside the corner (top/right 2px, !important to beat the small-screen rule) so the number is always fully visible.

## July 13, 2026 (Cheat menu — real art instead of emoji)
- The debug / cheat menu (long-press the top-right 🔧) was still drawing placeholder emoji in three tabs while the rest of the game shows generated art. Wired them to the real images:
  - Consumables tab: gems / runes / scrolls / spirits now show their ic_<id>.webp icons (was c.icon emoji).
  - Vouchers tab: each voucher shows its ic_<id>.webp icon (was v.icon emoji).
  - Bosses tab: each boss shows a cropped boss_<id>.webp portrait thumbnail (was a generic 👿 / boss.icon emoji).
  - Sigil section header now shows the sigil's icon image.
  All fall back to the original emoji only if an image is missing. Verified in-browser: 39 boss thumbnails, 66 consumable icons, 31 voucher icons render as images, 0 emoji. Audited every item/wall/stake/edition/sigil/boss set — all have art on disk, nothing missing to regenerate. Wiki already uses images throughout; tutorial emoji are click/celebration cues (left as-is).

## July 11, 2026 (Bag fix — WILD tiles now shown)
- FIX: the Tiles bag / Tile Collection (showTileCollection → buildTileCollection) never displayed WILD tiles. Wild Tile 萬能牌 and the 145th Tile are `joker:true` with `num:0` and no fixed suit, so they matched none of the suit/honour/flower filters and were silently dropped from the view. Added a "🃏 Wild" row that lists every joker tile across pool / hand / board / scored with the same status colour-coding (the 145th Tile shows as "145"). Bag count was already correct (pool.length includes wilds) — only the grid was missing them.

## July 10, 2026 (Charm icons — readable bold-icon restyle · PARTIAL, billing-blocked)
- ART: charms read badly because the full-scene 古惑仔 art turned to muddy blobs at the ~26px icon size (and ~108 Common/Uncommon charms were still emoji). Switched to a BOLD ICON style — a single subject filling the frame, thick ink linework, high contrast, ONE vivid spot colour, simple dark vignette — that stays readable as a thumbnail. Prompts auto-built from each charm's JOKER_POOL name.
- THIS WAVE (installed + deployed): 34 Common charms + 4 style samples (god_gamblers, guan_yu, lucky_cat, red_lantern — 2 Legendaries improved).
- BLOCKED: mid-batch the OpenAI account hit its BILLING HARD LIMIT (billing_hard_limit_reached) — all further gpt-image calls 400. Remaining ~110 charms + 31 vouchers + 7 runes will resume once the hard limit is raised in the OpenAI billing settings. Gems/Spirits stay on the earlier full-scene 古惑仔; enhancements stay material-tiles.

## July 10, 2026 (Dev wiki: design-comparison page)
- DEV WIKI: added comparison.html — a contributor-only design-comparison reference (system-by-system + a sibling-project side-by-side), linked from dev.html's page tiles. Deliberately kept OUT of the player-facing wiki and NOT deployed to the public site (the public wiki/changelog stay genre-neutral). View it locally via the dev wiki over Tailscale.

## July 9, 2026 (古惑仔 Gems + Spirits — restyle cont.)
- ART: continued the 古惑仔 icon restyle — all 12 GEMS (4 gemstones + 8 秘笈 manuals; ruby landed earlier) and all 20 SPIRIT consumables re-generated in the gritty inked-manhua style (images/ic_<id>.webp, 256²). The Spirits especially benefit — horror-ink hungry ghosts, weeping banshees, altar mediums. Painted set is now 古惑仔 across Legendary + Rare charms + Gems + Spirits (~68 icons). REMAINING on the old/other styles: the 11 tile enhancements (kept as distinct material-swatch renders) and ~100 Common/Uncommon jokers (still emoji) — both pending explicit go-ahead.

## July 9, 2026 (古惑仔 charm icons — art-direction restyle)
- ART: began restyling item icons from the glossy painterly look to the gritty 1990s HK 古惑仔 (Young & Dangerous) inked-manhua style that matches the boss posters — heavy black linework, cross-hatching, chiaroscuro, desaturated sepia + one spot colour, distressed texture. This batch: all 36 CHARMS (8 Legendary + 28 Rare) — god_gamblers/heavenly_queen/pure_heart landed earlier as style samples, the other 33 this pass (images/ic_<id>.webp, 256²). Same filenames so game + wiki pick them up automatically. STILL to restyle: Gems, Spirits, tile enhancements (the rest of the painted set); Common/Uncommon jokers remain emoji pending go-ahead.

## July 9, 2026 (Calligraphic carved faces · corrected 歲 logo)
- TILE FACES: reworked to look hand-carved / brush-calligraphic instead of clean-font. Characters (numerals, 萬, 東南西北中發白) now render in DFKai-SB / KaiTi 楷書 with an engraved letterpress emboss; 筒 became carved coins (dark rim + blue ring + red pip + highlight) and 索 became carved bamboo stalks with a node band + leaf sprig. Still correct-by-construction (real font + code-drawn counts) — matches the boss art's brush aesthetic.
- 太歲 WIKI LOGO: the 歲 was malformed. Re-made the logo by compositing the correct 太 / 歲 from the real KaiTi font (C:\Windows\Fonts\kaiu.ttf = DFKai-SB) onto fresh blank carved ivory tiles, carved-red. Character correctness now guaranteed — no AI-rendered text.

## July 9, 2026 (Painterly tile-enhancement icons)
- ICONS: the Bronze Vault (and every pack/shop) no longer shows emoji for tile ENHANCEMENTS — added painterly blank-tile icons for all remaining enhancements: Bonus 賞牌, Mult 倍牌, Gold 金牌, Color-Wild 萬色牌, Porcelain 瓷牌, Steel 鋼牌, Stone 石牌, Lucky 幸運牌, Gilded 鍍金牌, Pearl 珠牌 (images/ic_enh_<enh>.webp, 256²) — joining Foil 箔牌 from earlier today. Each depicts a blank material tile (porcelain/steel/stone/gold/pearl/…) so there are no garbled characters. No code change — _icHTML keys enhancements by enh_<enh>. NOTE: Common/Uncommon JOKERS (e.g. Tail Whip, Flower Bed, Chow Chef, Ghost Tile) still fall back to emoji — that large set remains intentionally deferred.

## July 9, 2026 (Deck-themed tile backs)
- TILE BACKS: the draw pile now shows a painterly tile-back themed to the run's chosen deck — its Chinese name + a matching motif in the deck's colour (街枱 bamboo-lattice ivory, 龍門 gold dragon on red, 茶樓 lantern+teapot gold, 磨牌 jade lotus/ensō, 花墟 pink blossoms, 風水 purple bagua, 赤腳 straw-sandal amber, 大食 noodle-bowl pink). images/back_<deckid>.webp, 8 total. The DRAW label sits in a bottom scrim strip so the deck name shows; the count badge stays top-right. Applied in updateUI keyed to wallType, preloaded so a missing image falls back to the classic green pattern.

## July 9, 2026 (Traditional engraved tile faces)
- TILES: replaced the flat Unicode mahjong glyphs (🀇… — which render emoji-like on Windows) with crisp code-drawn faces via new mjTileFace(): 筒 shows EXACT drilled dots (blue ring + red pip), 索 shows EXACT bamboo sticks, 萬 shows the stacked numeral(blue)+萬(red), and honours show real 東南西北 / 中(red)·發(green)·白(blue) characters. Counts/characters are code-driven so they are always correct at any size. Kept the suit color top-bar, the corner number, and the 1-索 bird image. Honour tiles drop the redundant bottom label (the big character is enough). No gameplay logic touched — makeTileDiv face markup only.

## July 9, 2026 (UI polish · authentic dice · Foil/Snowball icons · wiki logo)
- LANDING: lifted the primary actions ([❓ How to Play][▶ New Game][⟳ Continue Run][⚙️ Settings]) higher by reserving bottom padding in #ls-inner, so they no longer overlap the bottom-right dev/meta cluster (Wiki · Auto · Stress · Changelog). Landscape breakpoint bumped to match.
- PLAY SPACE: removed the faint bird watermark from the felt background (#felt::before now inert).
- DICE: replaced the flat cream pip-dice with authentic bone-white mahjong dice — glossy ivory cube, concave drilled pips, and the traditional RED 1 & RED 4 (black on all other faces). Pure CSS so pip counts are always exact.
- ICONS: Foil Tile 箔牌 and Snowball 雪球 no longer show emoji in the Bronze Vault. _icHTML now keys tile ENHANCEMENTS by enh_<enh> (they have no id), so ic_enh_foil.webp (holographic foil-wrapped tile) applies; ic_snowball.webp (snowballing orb of tiles+coins) applies to the joker automatically. Both painterly HK-manhua, 256².
- WIKI: added a 太歲 logo top-left — two carved ivory mahjong tiles (太 · 歲) engraved and red-inked, gold-rimmed (images/wiki_logo_taisui.webp).

## July 9, 2026 (Painterly icons — Rare charms · Spirits · Gems)
- ART: replaced the procedural tile-cards for 60 more items with painterly 1990s HK-manhua illustrations (images/ic_<id>.webp, 256²) — matching the 8 Legendary hero icons. Coverage now: all 28 RARE charms, all 20 SPIRIT consumables, and all 12 GEM consumables (4 gemstones + 8 kung-fu 秘笈 manuals). No code change needed — _icHTML (game) and icon() (wiki) already load ic_<id>.webp by filename, so both surfaces pick these up automatically; emoji stays the auto-fallback. Uncommon/Common charms, runes, and scrolls keep the procedural tile-cards for now.

## July 8, 2026 (Loan Shark reroll)
- LOAN SHARK: re-rolled boss_loan_shark per art direction — fanning a thick stack of Hong Kong banknotes (HK$1000/HK$100), heavy gold cuban chain, gold aviator sunglasses, gold Rolex, chunky gold finger rings, cigarette, cold triad-boss smirk in a seedy dark backroom with NO mahjong anywhere. Vertical 大耳窿 calligraphy right, distressed red "Loan Shark" across the bottom. 古惑仔 style. Installed 560×840.

## July 8, 2026 (Landing menu reflow)
- Primary actions now read [❓ How to Play][▶ New Game][⟳ Continue Run][⚙️ Settings], centered. How to Play + Settings are matched small buttons flanking the New/Continue pair (Settings restyled to match Help; both 11px, 7×14 padding).
- Dev/meta cluster (📖 Wiki · 🤖 Auto · 🧪 Stress · 📋 Changelog) grouped and pinned bottom-RIGHT of the bar (absolute) so it no longer covers the bottom-LEFT seed chip. Changelog moved out of the primary row into this cluster. Portrait/mobile: the cluster returns to normal centered flow so it can't overlap the stacked column.

## July 8, 2026 (Painterly Legendary icons · Six-Finger user art · Lady Meng text)
- HERO ICONS: replaced the 8 Legendary charm tile-cards with painterly gpt-image illustrations (god_gamblers, guan_yu, empty_hand, immortal_wall, eight_flowers, tile_145, mahjong_saint, heaven_earth) → images/ic_<id>.webp (256², no text). The other 257 items keep the procedural tile-cards; the _icHTML helper needs no change (same filenames). Judge the style before we commit budget to more sets.
- SIX-FINGER MASTER: replaced with user-supplied art (C:\Users\Alan\Downloads\SixFingerMaster.png) → boss_six_finger_master.webp — already has vertical 六指琴魔 + English bottom + the six-fingered guqin hand.
- LADY MENG: kept the composition, re-rolled to enforce the title (孟婆 vertical, "Lady Meng" red bottom). Installed 560×840.

## July 8, 2026 (Rules audit · Balatro purge · non-emoji icons · 5 boss rerolls)
- REMOVED the Rummikub-legacy "first play ≥30 pts" rule — it was actively enforced (initialMet gates) but is NOT a HK Mahjong rule. Now initialMet defaults true so all ≥30 filters are inert; kept _ensurePlayableHand() (anti-dead-hand, unconditional). Removed the rule from the wiki + the stale flash message.
- BALATRO PURGE: removed all 51 mentions of "Balatro" across game, tutorial, wiki, dev wiki, economy sim, STEAM_PLAN, ASSETS, package.json, and a script — including code comments and the JS variable `balatro`→`genreBench`. Replaced with genre-neutral phrasing ("roguelite", "the genre"). Verified 0 remaining.
- WIKI TEXT: added a Self-draw 自摸 & Chicken hands 雞糊 section (self-draw ALWAYS applies = +1番 baseline on every win; chicken = valid win below the Wind's min-fan gate). Corrected the scoring modifier list (fan/charms/gems/scrolls/editions/sigils). "Draft Budget" renamed to "Starting Gold 起始金" in-game + wiki.
- ICONS NOT EMOJI: re-enabled the generated mahjong-tile icon art (images/ic_<id>.webp) in BOTH game and wiki so items are no longer emoji and the two stay consistent (the earlier id-collision bug is fixed; emoji remains the auto-fallback). Verified 266 icons render, 0 broken.
- BOSS REROLLS (古惑仔 style, no "teddyboy" in prompts): stone_wall (no foreground people, temple bg), ox_horse (titled), tyrant_tung (no child in bg), six_finger_master (grounded reinterpret), master_fahai (golden monk, scroll + bowl). Installed 560×840.

## July 8, 2026 (6 more boss rerolls)
- tree_demon (removed the human figures in front — tree spirit alone), grey_judge (title added), nine_fox + old_fung (vertical-title layout enforced), tiger_spirit (fierce white tiger, titled), six_finger_master (per request, prompted with ONLY the title text + house Teddyboy style — GPT re-interpreted freely: a grounded young gangster instead of the over-evil demon). All titles verified, installed 560×840. Spend ~$0.35.

## July 8, 2026 (11 boss rerolls — vertical-title layout enforced)
- Regenerated 11 portraits with the vertical-Chinese / English-bottom Teddyboy rule: the_water (English title added, bigger 水鬼), tyrant_tung (fresh imperial-chancellor take), eunuch, tree_demon (text added), six_finger_master (full reroll — demonic clawed hands + purple aura), the_taxman (dense HK high-rise skyline bg), one_eyed (Kowloon Walled City bg), black_wind (golden filigree added to attire), stone_wall (text fixed), the_jiangshi (text fixed), loan_shark (reroll — HK triad sunglasses, gold chains, cash). All titles verified spelled correctly on a contact sheet; installed 560×840. Spend ~$0.63.
- Known minor: stone_wall has a small stray "義氣" mark bottom-left; six_finger hand-count reads 5–6 (stylized claws). Re-roll on request.

## July 8, 2026 (Six-Finger + Twin Blades rerolls · vertical-Chinese title rule)
- NEW ART DIRECTION RULE (all future boss posters): Chinese title VERTICAL down the side in calligraphy, English in distressed red at the BOTTOM.
- six_finger_master fully redone: both raised hands show six clawed fingers over the guqin, purple demonic aura, vertical 六指琴魔. twin_blades rerolled: correct five-finger grips, compact butterfly knives (smaller), vertical 雙刀仔. Verified on sheet, installed 560×840.

## July 8, 2026 (9 boss portraits redone via gpt-image-2)
- Regenerated per art direction (existing portraits used as style refs): twin_blades = ONE fighter with two butterfly swords; stone_wall = English title added + HK temple background (red pillars/incense coils/lanterns); ox_horse = English bottom title; old_fung = smirking grin; nine_fox = nine tails now sprout from her tailbone; tyrant_tung = English title added; the_taxman = looming low-angle presence filling the frame; lady_meng = full Meng Po rework (golden embroidered robe, glowing bowl of 孟婆湯, Naihe Bridge over the river of souls, Fengdu); six_finger_master = right hand clearly six clawed fingers on the guqin.
- All 9 verified on a contact sheet (titles spelled correctly EN+中文), resized 1024x1536 → 560×840 webp, installed to images/boss_*.webp. imagegen server was down — restarted (port 5511). Spend: ~$0.57, total $25.47/40.

## July 8, 2026 (Rules audit fix · boss scaling ranges · dev buttons right · mobile game-over fit)
- RULES AUDIT (vs code, not memory): the wiki's "first play EACH BLIND must total ≥30 points" was WRONG — initialMet resets only at run init (line ~9200), so the ≥30 rule applies once per RUN (wilds excluded, tracked t.num of non-joker tiles). Wiki corrected. Audited every other How-to-Play claim: pair-required-to-eat ✓ (enforced), min-fan ramp per ante ✓ (MIN_FAN_RAMP + stake minFanBonus), 6 draws/3 discards ✓, discard caps 8/12 ✓, discards removed-from-game ✓ (go to discardPile — fixed a stale code comment claiming they return to the bag).
- BOSS SCALING RANGES: builder now also evaluates descFn at Ante 8 and exports powerMax when it differs; wiki shows "↗ scales — by Ante 8: …" under the entry-ante power. 26/39 bosses scale.
- Landing dev buttons (Wiki/Auto/Stress): pushed to the right edge of the bar (margin-left:auto), shrunk 11px/8px-pad → 9px/4px-pad, slightly dimmed.
- MOBILE: game-over/win screen (#reveal.fullscreen) compacted on short landscape screens (34px hero number, tighter stats grid) so it fits without vertical scrolling.

## July 8, 2026 (Wiki: boss powers + portrait lightbox)
- BOSS POWERS in the wiki: build-wiki.js now extracts the boss helper functions (bossLerp/lateCF/cfTxt) and bakes each boss's live effect text — descFn(minAnte, scale(minAnte)), the same string the in-game banner shows — into wiki-data.json as `power`. Sanity checks fail the build on empty/mangled power text. Boss cards show Tier + entry Ante and the power in a red effect box (⚔). Verified 39/39 non-empty.
- PORTRAIT LIGHTBOX: click any boss portrait for the full-size art; click anywhere (or Esc) closes. Hover zoom cue on thumbnails.

## July 7, 2026 (Item-used pop · equal landing buttons · edge-to-edge poster)
- CONSUMABLE FEEDBACK: using an item now shows a centre pop card — icon, name, "✓ USED 已使用", and the item's effect text — with a scale-in/fade animation (1.7s, pointer-events:none, auto-removes; an item's own flash still adds specifics). New G._itemUsedFX() + #item-used-fx CSS.
- LANDING BUTTONS: New Game and Continue now share one rule (13px, same padding, min-height:52px, flex-centred) — Continue's two-line save summary fits the same box instead of making it much larger.
- LANDING POSTER: removed the 12px felt frame from #landing-screen (and its 14px mobile override — setup screen keeps its frame) so the hero art bleeds edge-to-edge with no blue felt showing.
- Verified: FX renders with iufx-pop animation, landing border 0/none, both buttons same computed rule, inline syntax clean, no console errors.

## July 7, 2026 (Art correction: wiki + game show the game's ACTUAL icons)
- User verdict: the generated glyph-tile item cards read as wrong art in the wiki. Reverted BOTH wiki and game to render the game's actual icon art (the icon field the game has always used; bosses keep painted portraits) so wiki and game always match.
- Infrastructure KEPT dormant for the future painterly upgrade: G._icHTML() still routes all 10 card surfaces (one function re-enables image art), the 265 images/ic_*.webp stay deployed, and tools/gen-icons.py now namespaces sigils (ic_sigil_*) fixing the 'gold' stake/sigil id collision.

## July 7, 2026 (Emoji → generated item art · wiki upgrades · rebuild spec)
- ITEM ART: NEW tools/gen-icons.py (PIL, deterministic, zero-cost) renders all 265 charms/consumables/vouchers/walls/stakes/editions/sigils as mahjong-tile-style cards (ivory tile face, rarity/color frame + accent bar, the item's Chinese glyphs in JhengHei Bold) → images/ic_<id>.webp (~4KB each, top-level so deploy picks them up).
- GAME WIRING: new G._icHTML(item) helper — generated icon <img> with the old emoji as automatic fallback (onerror). Swapped into all 10 card surfaces: charm row (jcard), consumable slots (ccard), shop cards (charm/consumable/voucher), run-setup wall+stake cards, card-info popup, collection cards, edition picker. Bosses keep their painted portraits. Flash TEXT messages keep glyphs (text context, not art) — cheap to sweep later if wanted.
- PLAYER WIKI (wiki.html): cards now use the generated icon art (emoji fallback); nav gains "Economy Simulator 模擬器" (sparrow-economy.html) + Developer Wiki links; boss list drops emoji (portraits are the art); item-type headers de-emojied (bilingual text). Verified live: 266 icon imgs, 0 broken; 39 portraits, 0 broken.
- DEV WIKI (dev.html): NEW "Rebuild From Scratch — full tech-stack spec" — stack table, all data schemas w/ counts, core algorithms (seeded RNG, validate incl. the [].every() guard, fan-table scoring, blind/economy formulas, charm phase-hook engine, save blob), 7-milestone rebuild order, and per-asset regeneration commands. A new dev/LLM can rebuild the game from this + wiki-data.json alone.
- Verified: inline syntax clean, G._icHTML sample+fallback correct, zero console errors on game + wiki.

## July 7, 2026 (Final Fable audit → OPUS handoff)
- AUDIT: re-verified everything fresh — smoke 46/46, qa-data 20/20, inline syntax clean, 8 steam art files, electron/ complete incl. icon.png+icon.ico, 8 music rooms, 13 tools, game+imagegen servers up.
- STEAM_PLAN.md corrected to audited reality: capsules/app-icon/charm+consumable QA marked DONE with artifact paths; Definition-of-Done checkboxes updated (next action = electron build; top risk = save-version guard); added the headless-bot rAF-throttling trap to the QA section; bed count 7→8.
- dev.html tools table updated (qa-data.js, check-syntax.js, make_steam_art.py; 46 checks; 8 beds).
- NEW OPUS_HANDOFF.md — the pick-up-and-go doc for the next model/session: verified-state table with re-run commands, first three tasks in order (electron build → save guard → boss QA matrix), the non-negotiable session ritual, and every trap this project already hit (port 5502 dance, headless bot stall, .ogg MIME→drone fallback, autoplay policy, unlock()-is-a-sound, secrets rules, no-python-alias, single-file-is-deliberate).

## July 6, 2026 (QA pass: charms/consumables verified · credits music · Steam art)
- QA (automated): NEW tools/qa-data.js (20 deep static checks — rarity spec C56/U52/R28/L8, unique ids, fx/apply presence, voucher require-chains, cross-pool collisions) + in-page behavioral sweep. RESULTS: 144/144 charm fx() calls pass on live tiles (0 crashes, 0 bad return shapes); 66/66 consumable apply() pass (62 applied, 4 legit guarded no-targets); 0 console errors. Findings + method + outstanding manual items recorded in QA_MATRIX.md. Legendary charms confirmed cost:0 by design.
- Exposed window.__POOLS (JOKER_POOL etc.) next to window.G for QA automation — pools were scope-private.
- CREDITS MUSIC: new m_credits.ogg (110s) — defeat's warmer sibling: bittersweet solo piano slowly resolving hopeful, erhu + guzheng passages, seamless loop. Added 'credits' room to audio.js + test bench.
- STEAM ART (generated via local imagegen): app icon (太歲 tile face, red calligraphy, gold trim) → electron/icon.png + multi-size icon.ico; wide capsule master (Teddyboy pair + boss lineup over HK harbour, NO text) → steam/ with all sizes: main 616×353, small 231×87, header 460×215, vertical 374×448, library hero 1232×706, library capsule 600×900, screenshot bg 1920×1080, library logo 1280×720 (transparent, brush titles composed). Builder: tools/make_steam_art.py.

## July 6, 2026 (Suggest (N) inline · landing-music autoplay fix · somber blind track)
- SUGGEST COUNT: now renders inline as "Suggest (N)" (mobile: 💡N) instead of a floating chip, and N mirrors EXACTLY what pressing Suggest would offer at this moment — narrowed to the current selection when tiles are selected (that mismatch was why the old number read wrong), ≥30-pt filter honoured pre-initial. Refreshes on every selection/board change (_updatePlayBtn) plus updateUI; dead badge CSS removed.
- LANDING MUSIC FIX: music('title') fires on page load, but browsers REJECT el.play() before the first user gesture — the engine had already faded the fallback pad out, leaving silence. audio.js now only swaps to the file bed once play() actually succeeds, and retries on the first pointerdown otherwise. (Silence until the first click is browser policy; after one click/tap the title bed starts.)
- BLIND (gameplay) MUSIC: regenerated more lofi/somber/relaxing per feedback — 66 BPM muffled dusty boom-bap, NO bright hi-hats/cymbals, warm Rhodes, deep soft bass, sparse sad piano + occasional guzheng, heavy vinyl crackle (150s seamless loop). Prompt updated in tools/gen_music.py.
- Cache-busts: audio.js now loaded as ?v=20260707a in game + bench; bench MUSIC_V bumped. Smoke test extended to 46 checks (settings fab present, autoplay-retry present, suggest wiring).

## July 6, 2026 (Settings everywhere + consumables flush-right)
- SETTINGS FROM ANY SCREEN: added a floating ⚙️ button (fixed bottom-right, next to the 🔊 mute toggle) that opens the Settings overlay from anywhere — landing, gameplay, shop, draft. Settings modal z-index raised 300→20001 (backdrop 20000) so it sits above every game screen (shop/help/collection ~9999, changelog 10001). Music/SFX/Master volume is now adjustable mid-run.
- CONSUMABLES PANEL: #right-panel is now fixed at top:42px right:12px — right edge flush with the felt's outer right edge, dropped below the ❓/🔧 corner buttons (they end ~y34) so nothing overlaps. Mobile-landscape keeps its own verified layout (top:2 right:90, !important override). Verified: gear click opens/closes modal, computed pos fixed/42px/12px, no console errors, inline scripts parse clean.

## July 6, 2026 (Release prep: wikis, tools, Electron scaffold, long music, fixes)
- FIX (exploit): the Tiles-bag button's Tile Collection offered the "Apply Sigils" list — free sigils during play. Sigil application is now cheat-menu-only (tc-sigil-section hidden + not built from the bag view).
- SUGGEST BADGE: the Suggest button now shows a live count of available plays (purple chip, greys at 0) — key for mobile where scanning the hand is hard. Debounced recount on every updateUI; honours the ≥30-pts first-play rule.
- MUSIC v4: regenerated all 7 beds MUCH longer (blind 150s, title/shop/boss 90s, pack 24s, victory 30s, defeat 40s) with SEAMLESS LOOPS — each track's tail equal-power-crossfades into its pre-head material so looping never cuts abruptly. Generator promoted to a permanent tool: tools/gen_music.py + gen-music.bat (args = single-track re-roll).
- PLAYER WIKI (wiki.html): Balatro-style reference — rules/fan primer, 8 decks, 8 stakes, 144 charms (search + rarity filter), 31 vouchers, 66 items by type, editions/sigils, all 39 bosses with portraits + lore, ante table. Data auto-extracted from sparrow.html via tools/build-wiki.js → wiki-data.json (cannot drift from code; validates counts + portraits). 📖 Wiki button added to the landing bottom row.
- DEV WIKI (dev.html): architecture map, golden rules (backup/changelog/deploy/secrets), tools table, QA hooks, asset pipelines, links to the game / player wiki / audio bench / economy simulator / changelog.
- STEAM_PLAN.md: full 0.1 (Steam PC) → 0.2 (macOS/Mobile) plan written for ANY LLM/dev to execute — PM/Engineering/Design/Art/QA role analyses, milestones, Definition of Done, LLM handoff ritual, perf budget (60fps @1280×800 Steam-Deck class).
- TOOLS (tools/): start-server.bat (auto-restart dev server), deploy.bat (smoke-test-gated deploy), backup.bat, build-wiki.bat, smoke-test.js/.bat (43 checks: syntax, assets, 7 music beds, data integrity incl. 144-charm/66-item field completeness, boss portraits, server MIME/Range config, secret-leak scan, regression guards), gen-music.bat, art-manifest.json (machine-readable asset list for local generators: Steam capsules, 43 tile faces, 144 charm icons, 66 item icons, UI chrome, app icon).
- ELECTRON scaffold (electron/): main.js (1280×800, fullscreen toggle, bg-throttling off), package.json (electron-builder win/mac), build-app.bat (stages game bundle → smoke test → .exe), README with Steam Deck perf targets. Mirrors the Melder Steam approach.
- Deploy now also pushes wiki.html, wiki-data.json, dev.html.

## July 6, 2026 (FIX: .ogg served as octet-stream → music "Error" / droney pad fallback)
- ROOT CAUSE of the bench "Error" on every track AND the long-standing "droney/all-the-same" music: serve-mahjong.js had no .ogg MIME type, so OGGs were sent as application/octet-stream. Browsers' <audio> refuse that ("Error"), and the game's music engine (which loads the same OGGs) silently fell back to its procedural drone PAD for every room — so the generated MusicGen tracks were never actually heard.
- FIX: added audio MIME types (.ogg→audio/ogg, .oga/.opus/.m4a/.aac/.flac/.wav) to serve-mahjong.js + HTTP Range support (206 Partial Content, Accept-Ranges) so media loads and the scrub bar can seek. Verified: OGG now returns Content-Type audio/ogg + 206 on range. Added .htaccess (AddType audio/ogg etc.) so the web/SFTP host serves audio correctly too; deploy now pushes it.

## July 6, 2026 (Distinct-genre music via musicgen-large + scrub timeline)
- MUSIC redo #3: previous beds still sounded same-y/droney. Regenerated all 7 with the LARGE MusicGen model (RTX 5090) and a DISTINCT GENRE per track so they can't blur together: title=chill lo-fi hip-hop, blind=melancholic jazz piano trio, shop=bright funk 112BPM, boss=dark cinematic trap 808/half-time, pack=marimba/vibraphone sting, victory=big-band swing fanfare, defeat=solo piano ballad. Verified rhythmic (envelope CV 0.25–0.54, 50–114 onsets/track — not drones) and distinct loudness/dynamics.
- SCRUB TIMELINE: audio-test.html music section now uses native <audio controls> players (built-in seek bar to jump ahead), one-at-a-time playback, STOP pauses all, cache-busted src so regenerated tracks load fresh.

## July 6, 2026 (Lose SFX + groovier jazz-hop music)
- NEW 'lose' SFX: three descending "sad" notes into a low gong thud. The bench's fail button used to call A.fail() (only bends the current music bed → silent with no music playing); now it plays the 'lose' sting (+ still bends the bed). Wired _gameOver → sfx('lose') + music('defeat'). 'lose' added to the Stingers group + complete-library.
- MUSIC redo (7 beds): previous set rendered as sustained "long notes" (bowed erhu/ambient prompts). Regenerated leading with DRUMS + groove + explicit BPM + plucked/chord instruments (Rhodes comping, upright bass, plucked guzheng) so it's real rhythmic Balatro-style jazz-hop, Chinese instruments as accents. Moods: blind somber ~72BPM, shop exciting ~92BPM funky, boss mysterious ~84BPM tense, title cool ~82BPM, victory triumphant ~96BPM, defeat mournful ~66BPM. Loudness profile matches intent (shop/victory loudest, boss darkest). Sampling temp 1.0 / cfg 3.5 for more musical output.

## July 6, 2026 (Audio bench: stop the unlock-arpeggio on every button)
- ROOT CAUSE of "a default sound plays instead of the SFX": the bench called A.unlock() on every button to "unlock audio", but in this engine A.unlock() is itself a SOUND (a 7-note ascending arpeggio, ~14 oscillators) — not a silent context-resume. So that arpeggio fired on every press. Added a silent resume() helper (resumes the AudioContext, no sound) and swapped every gesture-unlock to it; kept A.unlock() only on the dedicated "unlock 🔓" test button. Verified via oscillator counts: click/coin/hover=1, boss=4, kong=8, unlock-test=14 (intended) — previously every button was +14.

## July 6, 2026 (Audio test bench: no doubled click · complete-library panel)
- FIX: on the audio test bench every button press played a generic 'click' SFX ON TOP of the button's intended sound (the audio.js delegated auto-click handler). Added an opt-out — window.__gosNoAutoSfx (and per-element data-no-auto-sfx) — set on audio-test.html so bench buttons play only their intended sound. Verified: a 'coin' click now fires one sound, not coin+click. Game buttons keep their click feedback (flag unset there).
- Bench also gains a self-verifying "Complete library" panel (auto-lists every sfxNames() sound + count), a "Play ALL sound FX" audition, and a cache-busted engine include so a stale copy can't hide sounds.

## July 6, 2026 (Mahjong tile SFX · 7 fused music beds · uniform setup tiles)
- TILE SOUNDS: added a clack() synth (sharp click transient + woody resonant knock + low thud) so tiles sound like real mahjong on felt. tile_place = firm double-tap clack; kong 槓 = four rapid rising clacks; tile_select/tile_flip/draw reworked to match.
- MUSIC (regenerated, 7 beds): Balatro-style lo-fi jazz FUSED with traditional Chinese instruments (guzheng, erhu, dizi flute, pipa, taiko/gong). Every screen now has a track — title/blind/boss/shop/pack PLUS new victory (bright) and defeat (mournful erhu) beds. Wired _winGame→music('victory'), _gameOver→music('defeat'); added both rooms to audio.js + the test bench. Crossfade lengthened 1.0/1.2→1.6s for smoother fades.
- SETUP TILES UNIFORM: deck/stake selection cards forced to strict equal aspect boxes (min-height:0; overflow:hidden), names clamped to 2 lines, icon/name/tier sized down on the 8-across PC row so a long name can't stretch a card taller than its neighbours.
- Audio test bench (audio-test.html) now lists all 7 music rooms; verified all beds present (green dots), 9 gameplay hooks attached, no console errors.

## July 5, 2026 (Stakes single row · Starting Pack compaction · full audio hookup)
- RUN SETUP: the Stake (difficulty) picker now uses the same PC single-row grid as the Wall/deck picker — all 8 stakes on one row (min-width:760px; 4-col fallback on narrow screens).
- STARTING PACK: another pass of size reductions to kill vertical scroll on PC — pack icon 38→30px, card 178→162px & tighter padding, name/picks/preview fonts down (preview 11→10px, line-height 1.5→1.34), econ buttons 9→6px pad, budget number 18→15px, section margins trimmed, inner padding 14→10px.
- AUDIO HOOKUP (expanded): added stingers/beds at the moments that were still silent — blind beaten → threshold bass-drop + ascending clear bells (_advanceBlind); Kong 槓 stinger when an eaten meld is a 4-tile set (finishRound); boss reveal sting (_showBossIntro); dice-roll (_showDiceRoll); game over → bend the current bed + low shake (_gameOver); sell relic/consumable → sell (sellJoker); gameplay music on New Game / Continue (_newGame/_continueGame); pack music + pack_open on the draft screen (_showStarterScreen). All guarded no-ops if audio.js is absent. Verified 12 hooks attach with no console errors.

## July 5, 2026 (Audio test bench + Settings panel with per-channel volume)
- NEW audio-test.html — a God of Sparrow audition bench (mirrors the Melder one): buttons for every procedural SFX (tiles/economy/UI/stingers), the scoring cascade (meld ladder → ×mult ka-ching → bass drop → final tally), winHand/fail/unlock, and the 5 music rooms with live file-presence dots (green = OGG present). Master/Music/SFX sliders share the game's persisted volumes. Deployed alongside index.html.
- audio.js: added independent bus volumes — setMusicVolume/setSfxVolume (+ getters), stopMusic(), sfxNames(); music & SFX buses now seed from localStorage (gos_musicvol / gos_sfxvol) so they persist. Master mute/volume unchanged.
- NEW in-game Settings (⚙️ Settings 設定 on the landing menu): overlay with Mute-all toggle + Master / Music / SFX volume sliders (live % + Test SFX/Music/Stop buttons + link to the bench). Wiring attaches on DOMContentLoaded with a retry so load order never matters. All controls read/write the same localStorage the engine uses, so changes carry into a live run.

## July 4, 2026 (Somber music beds + landing/setup polish)
- MUSIC: generated 5 original somber, Balatro-flavoured lo-fi/noir beds via MusicGen (title/blind/boss/shop/pack), 32kHz OGG in audio/music/. The audio.js room manager already auto-swaps these in over the procedural pads on crossfade — SFX were already fully wired via the hook layer. Boss bed is a dark brooding taiko/low-strings underscore; title/blind/shop are smoky after-midnight mahjong-parlour jazz. Deploy (sync-once.ps1) now mirrors audio/music/*.ogg to W: and SFTP.
- LANDING TITLE: regenerated the "GOD OF SPARROW" wordmark (clean dripping-brush Teddyboy lettering, keyed to transparent yellow with dark outline), centred it to ~button-bar width, and lowered it. 太歲 brush shrunk ~19% (height 52→42%) and lowered to match; recoloured red.
- SAVE UX: removed the big "No save found" box — folded the save summary into the Continue Run button as a small second line ("No run in progress" when disabled; Ante/blind/beaten/gold when a save exists).
- RUN SETUP: on PC the Wall (deck) picker is now a single 8-across row (min-width:760px; 4-col fallback on narrow screens). Starting Pack draft screen tightened (trimmed section margins, 50→38px pack icons, slimmer pack padding) to cut the vertical scroll.

## June 30, 2026 (Boss rename — Thirteen Eyes → The Judge of Extremes 極判官)
- Renamed the tier-4 finisher (id stays 'thirteen_eyes' internally to avoid breaking saves/refs): 🀄 Thirteen Eyes 十三太保 → 🖋️ The Judge of Extremes 極判官 (col #a16207). "Thirteen Eyes" read too heroic for a villain; the new one is a cold corrupt magistrate who only scores the extremes (honours/terminals) and strikes everything between from the ledger. Effect unchanged (onlyHonourTerminalFan). New lore + descFn written. Updated BOSSES.md (table + lore + saved the portrait art-prompt for the gen pipeline). Simulator has no boss refs (nothing to fix there); tutorial doesn't name it. Verified in the cheat boss viewer: renders 極判官 / new lore / no stale "Thirteen" refs, no console errors.

## June 30, 2026 (Wild-tile counter-play: boss reskin + duplication guard)
- REPLACED (not added) a boss: Crooked Mouth Fai 歪嘴輝 (🃏, tier 2) — its old falseWinPenalty (0-fan meld halves score) is retired; it now does wildsScore0 = your Wild tiles score 0 chips this blind. Wired at the wild-chip source (baseChips += enhChips + wildChips, gated on bossEffect.wildsScore0) + its scoring flash. Verified: all-wild hand 9,280 → 2,560 under this boss (only meld base survives); normal 1–2-wild-filler hands barely feel it. Lore + descFn rewritten to match. lucky_rooster 吉雞 charm now nullifies wildsScore0 (was falseWinPenalty) so "immune to Crooked Mouth Fai" still holds. (falseWinPenalty scoring code left inert — no boss sets it.)
- DUPLICATION AUDIT (can't cheaply multiply wilds → no re-break of the all-wild hand): spirit_cryptid 山神 (the only tile-duplicator) already filtered !t.joker; made the wild exclusion explicit in its description + comment. blueprint/mirror_pond/forgery copy CHARM effects, not tiles (no wild-tile cloning). So the ONLY way to amass wilds is buying them — expensive, and now beatable/counterable.

## June 30, 2026 (Wild-hand exploit fixed — empty-array .every() bug)
- ROOT CAUSE of the 1.2B all-wild hand: the 字一色 All-Honours and 清老頭 All-Terminals limit-hand checks used `numbered.every(...)`, and [].every() returns TRUE — so an all-WILD hand (numbered=[]) falsely triggered 字一色 = MAX_FAN (20). That was the whole exploit, NOT the wild economy.
- FIX: guard both with `numbered.length > 0`. An all-wild hand now scores only what it really is: All Pongs 碰碰糊 +3 + self-draw +1 = fan 4. Verified: 14 wilds 1.2B → 9,280 (fan 4), while a real complete flush is 25,600 (fan 8). So committed hands beat the lazy all-wild buy — wilds are no longer OP and keep their intended role as flexible meld-fillers (adopting the meld's real identity). No shop cap needed.

## June 30, 2026 (5 QA fixes — wilds, cheat tiles, volume, seed, boss card)
- WILDS: an all-wildcard meld (3–4 pure jokers) was rejected by validate() (numberedTiles.length===0 → ok:false), so 14 wild tiles couldn't win. Now an all-wild meld is a valid Pung/Kong. Verified: 14 wilds → valid winning hand, fan 21, ~1.2B score.
- CHEAT TILES were the legacy 4-colour gem system (red/blue/orange/black × 1–13) — not mahjong. Rewrote _cheatBuildTiles + added _cheatMakeTile + fixed _cheatTileAdj to build real mahjong tiles: 3 suits 萬/筒/索 × 1–9 (27) + 7 honours 東南西北中發白 (34 cells total). Grid trimmed to 9 columns.
- VOLUME button (audio.js) moved from bottom-left to bottom-RIGHT.
- SEED now clearly visible: #seed-display restyled (fixed bottom-left, 10px gold on a chip, was 7px dim grey) for QA; added a clickable-to-copy 🎲 SEED display in the cheat menu top row (updates on open).
- BOSS CARD (cheat viewer) was oversized + janky on iOS Safari. Added a landscape-mobile block: icon 96→40px, name 30→15px, zh 42→20px, tighter padding (fits the screen), swapped the bossShake+bossSlamIn scale animation for a simple fade, removed backdrop-filter and the screen-shake on mobile. Verified card fits (h329/390) with no console errors.

## June 30, 2026 (Item slots charm-sized; help/cheat moved right of items)
- Item slots enlarged to 58×76 (matching the .jcard charms, was 32×44), sitting in the top band just above the Tail button (items end y78, Tail starts y78 — no overlap).
- Arrangement per user: cluster reads [items][❓help][🔧cheat] left→right, right-aligned as a group to the felt edge (cheat right 834≈832). Items at right:90px (left of the corner); help/cheat keep the top-right corner (right:44/10px), i.e. to the RIGHT of the items. All above the Tail button. Verified every pairwise overlap false (items/help/cheat/tail), no console errors.

## June 30, 2026 (Item slots repositioned — right-aligned to felt)
- Item slots (#right-panel) moved from a floating center-top spot to the TOP-RIGHT, right-aligned to the felt's right edge (item right 830 ≈ felt right 832), in the top charm band. Positioned above the Tail button (items end y49, Tail starts y78 — 29px clear), so no Tail-button adjustment was needed. Verified: right-aligned, no overlap, no console errors.

## June 30, 2026 (Mobile UI bug fixes — meld tiles, flowers, left panel, item slots)
- MELD SLOT tiles: all tiles shared zIndex=3, so overlapping tiles stacked by paint order and the MIDDLE tile hid behind its neighbours. Fixed in layoutBoard → zIndex = 3 + i (fan left→right; verified z=3,4,5).
- FLOWER overlapping the player hand on landscape mobile: flowers were full-size (scale 0.7) below the pair-box and crowded the hand. Now scale 0.5 on landscape-mobile → tested with 4 flowers, no overlap (they sit right of the hand).
- LEFT PANEL scrolled on mobile (content 407 > 370). Tightened gap 3→1px, dividers margin 0, score number 24→20px, scorebox padding, and hid the static wall/stake line (like the already-hidden tail). Now overflow:hidden with content 370 = clientH 370 — zero scroll, nothing clipped.
- RIGHT ITEM SLOTS (#right-panel / #consumables) were display:none on mobile. Now shown compactly (32×44 ccards) to the right of the charm row in the topbar — verified visible.

## June 30, 2026 (Art style → Chinese ink painting; FLUX LoRA installed & working)
- User rejected the ornate gold/jade SDXL look; switched the art direction to CHINESE INK PAINTING via the Jonjew/ChineseInkPainting LoRA (Liu Jiyou gongbi style, trigger word "liujiyou").
- Stood up the full FLUX pipeline locally & AUTONOMOUSLY (no HF token needed): found the LoRA is FLUX.1-dev-only; ComfyUI had zero FLUX base; pulled the UNGATED Comfy-Org fp8 repack (flux1-dev-fp8.safetensors, 17.2GB) + installed the LoRA into comfyui/models/loras. Debugged ComfyUI launch (suite's /comfyui/start deadlocks on stdout pipe; system python missing sqlalchemy → must use .venv python; reach via 127.0.0.1 not localhost).
- Built a working FLUX+LoRA ComfyUI workflow (CheckpointLoaderSimple→LoraLoader→CLIPTextEncode→FluxGuidance 3.5→KSampler euler/simple cfg1 22steps→VAEDecode→SaveImage), ~13s/image. Generated gallery-quality ink test art (dragon, old-gambler boss portrait) — style direction confirmed. Full repeatable recipe documented in ASSET_GENERATION.md §0. Ink look is ideal for painterly heroes; tiny UI icons need higher strength / simpler subjects (noted).

## June 30, 2026 (Audio engine + asset pipeline — research & first build)
- ASSET MANIFEST (ASSETS.md): full art+audio spec mapped to live content counts (144 charms, 39 bosses, 8 walls, 8 stakes, 72 consumables, 31 vouchers, 42 tile faces). ~380 art pieces + ~80 audio files. Power-of-2 only needed for a future native/GPU port (web is SVG-first); one SVG+2×PNG master set serves both.
- Researched Balatro's audio (one motif → per-room arrangements, runtime slow+pitch-down on loss, pitch-escalating scoring "ensemble"). Locked direction with user: painterly bosses/packs + vector icons, wuxia/HK-cinema orchestral music.
- LOCAL GENERATOR INTEGRATION: confirmed the local suite at :5173 exposes live FLUX + SDXL (image) and AudioGen (music/sfx) over REST. Proved tap-in end-to-end (SDXL 1024² in 13.1s, correct gold/jade/navy style). Wrote ASSET_GENERATION.md — executable prompt/job guide (exact endpoints, style bible, per-family prompts, batch order) that I can run directly or hand to the companion Claude.
- AUDIO ENGINE (audio.js): pure Web Audio, procedural SFX (zero files needed) + music room-manager (drone-pad placeholder that auto-swaps to /audio/music/m_<room>.ogg when generated) + the scoring ensemble (pitch-escalating chip ticks, ka-ching, threshold bass-drop, final cha-ching + coins). Self-injects a 🔊 mute toggle, auto-wires UI click/hover SFX via delegation, and hooks game moments (playGroup→tile, endTurn→score, openShop→shop music, _winGame→win, unlock fanfare, boss-intro→boss music). Included via <script src="audio.js">; verified loads clean, AudioContext runs, hooks attach, no console errors. Added audio.js to sync-once.ps1.

## June 30, 2026 (Starter pack — fits 844×390 with bigger readable text)
- Mobile-landscape compaction redone after the bigger fonts pushed packs past the screen. Final settings: icon 26px, name 12px, "items · choose 1" picks line 11px (bright #f1f5f9 bold), tier 8px, preview items 11px (bright #fafafa bold), line-height 1.35. Pack horizontal padding bumped 6 → 14px for breathing room.
- Cursed-pack bane row was the overflow culprit (218px content vs 200 cap, ~18px clipped). Tightened: label 8→7px, text 9.5→9px, clamped 2 lines → 1, padding/margins halved. Now contentH 191 / slot 200 — no clip on any pack.
- Verified across all 4 archetype packs (Scholar/Hunter/Starter/Cursed): every pack content fits within its 200px slot, no scroll on 844×390. starterFits: true.

## June 30, 2026 (Run Setup polish — selection bug + green check + back fix)
- BUG: clicking a wall/stake card made the selected ring flash on then off — visible only on subsequent hover. Cause: a leftover duplicate `card.onclick` that called `_renderRunSetup()` was firing AFTER my new direct-toggle handler, full-rebuilding the grid mid-click and tossing the .selected class with it. Removed the duplicate. Clicks now toggle .selected directly on the clicked card and update the hidden <select> — no re-render, no flash.
- NEW: green ✓ badge at bottom-right of any selected card so the choice is unmistakable. CSS ::after pseudo-element, 22px circle on desktop / 16px on landscape mobile, green #16a34a with white ring + green glow shadow.
- BACK BUTTON FIX: Run Setup's "← Back" was just hiding the setup overlay — if the landing wasn't underneath (which could happen mid-flow), you'd land on an empty play space. Now the Back handler explicitly re-shows the landing screen, so you always return to the front door.

## June 30, 2026 (Cheat menu Sim link + Simulator Back-to-Game)
- Cheat menu top row gains a teal 🧮 Sim 模擬 button — opens sparrow-economy.html for what-if scoring exploration.
- Simulator header gains a prominent purple "← Back to Game · 返回遊戲" anchor in the top-right of the title row, so the player can always get back to the game. CSS-only; no JS.
- Cheat menu audit: every tab (Charms / Tiles / Consumables / Vouchers / Editions / Bosses) is auto-populated from the same pools the game uses (JOKER_POOL, CONSUMABLE_POOL, VOUCHER_POOL, EDITION_TYPES, BOSS_POOL) — so all recent content additions (4 chip-gems, 8 Hand Manuals, scaling charms, Four Heavenly Kings/7788 reworks, Old Fung/Grey Judge bosses, etc.) are auto-available. The "🔓 Unlock Walls & Stakes" cheat works against the same sparrow_unlocked / sparrow_max_stake keys the new card UI reads.

## June 30, 2026 (Felt borders applied to all major panels)
- The decorative felt-image borders previously only framed the in-game #felt. Now applied uniformly to landing-screen, ls-setup-screen, left-panel, sp-inner (starter pack), and shop-inner. Pattern: `border:36px solid transparent; border-image:var(--felt-img) 120 fill stretch` (36px desktop, slimmer on landscape mobile so the bottom border doesn't clip — 14px landing/setup, 12px starter, 10px left-panel).
- Replaces the prior `background:var(--felt-img) center/cover` which was CROPPING the top and bottom of the felt's decorative woven texture on most viewports. The border-image technique slices the image's outer 120px as the visible frame and stretches the middle to fill — so the decorative edges are preserved while the inside still shows the felt.

## June 30, 2026 (Run Setup redesigned — full-page roguelite card UI)
- Was: small modal with dropdowns. Now: full-page screen with horizontal card grids (4×2 on desktop, 8×1 single row on landscape mobile) showing every wall and stake as a card with icon + name. Click a card to select; ⓘ button in the corner opens a centered popup with the full description, tier, reward, and lock conditions.
- ROGUELITE PROGRESSION: walls grayed/🔒 until first victory (sparrow_unlocked='1'); stakes chain-unlock — each tier locked until the previous has been beaten (sparrow_max_stake). Locked cards show their unlock condition ("Beat X to unlock") and a small 🔒 in the corner. All cards always visible so the player can SEE the variety (Slay-the-Spire / Hades pattern).
- WALLS reduced 10 → 8: consolidated the three mechanically-identical dragon walls (Red/Green/White) into one "Dragon Court 龍門" that surfaces the same commit-to-one-dragon mechanic with sharper flavor. Other 7 walls rewritten with more evocative prose ("Tea House: You arrive flush. Start +$10…", "Flower Market: Build a 花滿樓.", etc.).
- STAKES gained a 🏆 REWARD line on every card showing what beating it unlocks (next stake by name; the final Heavenly Game promises the eternal title 太歲尊號). Descriptions rewritten with flavor + the mechanical add-on. Tier label on each card.
- NO VERTICAL SCROLL — verified at desktop 1280×720 and landscape mobile 844×390 (single-row cards, icon+name only on mobile, info popup for full details).

## June 30, 2026 (Landing simplified + Run Setup is now its own page)
- Landing page de-cluttered: removed seed input, wall selector, stake selector — those moved to the new Run Setup screen. Landing is now: logo + (optional save-info) + ▶ New Game (primary purple CTA) + ⟳ Continue Run + ❓ How to Play + 📋 Changelog + 🤖 Auto / 🧪 Stress.
- "New Game" no longer starts a run immediately — it opens the new Run Setup overlay so the player can pick seed/wall/stake first. Setup's "▶ Start Run 開局" runs G._newGame() (which still reads the hidden selects). "← Back" returns to the landing.
- Logo upsized +20% to 528px max-width desktop / 460px landscape mobile (from prior 440/380), since seed/wall/stake are no longer competing for column space.

## June 30, 2026 (Landing — landscape two-column UX)
- Single tall column at 320px was overflowing on 844×390 landscape (~606px content). Restructured into a flex row: logo column (left, big drop-shadowed image) + actions column (right, stacked buttons in a sub-wrapper #ls-actions). Single column on truly portrait (<600px wide) via media query.
- Typography pass: primary CTA 14px (was 10), other buttons 12px, wall/stake labels 10px (was illegible 7px), seed input 11px, descriptions brightened (#9ca3af → #e2e8f0).
- Landing-screen .show now defaults to display:flex and the inner is grid-then-flex so logo+actions size predictably; landscape-mobile compaction hides save-info-when-empty + seed-description to save vertical.

## June 30, 2026 (New landing logo + tightened front buttons)
- Replaced the bird emoji 🐦 + separate 太歲 / "God of Sparrow" text DIVs with a single framed PNG (images/T_LandingLogo.png) that contains both names already painted in gold calligraphy. ls-logo is now an <img>, centered with a drop-shadow. CSS for the old text title removed.
- Front buttons were stretching to the full felt width and feeling soggy. Constrained #ls-inner to min(96%, 320px) so buttons naturally narrow to ~264px — tighter, more deliberate.

## June 30, 2026 (Solver tuning + completion-solver attempt + honest limits)
- SOLVER bug: meldVal undercounted 4-tile honour pungs as 40 (should be 80, kong). Now mirrors the game's meldBaseValue. Affects S.best() projections and shop charm-value estimates.
- BOT v4 (replaces v2/v3): kong-upgrade pass (board pong + 4th in hand → upgrade for +1 fan, +40 chips); smaller discard batches (≤4 vs 8) to preserve useful tiles; broader keep set (singleton honours/terminals/dragons/winds + chow neighbors); fan-source triplets placed first (locks per-meld fan); plain triplets after fishing; pair as eyes prefers non-fan tile (saves honour pair for pong fishing). Tested across many seeds.
- HONEST RESULT: the bot improvements help (kong upgrades, fan-source priorities, better keep) but it still loses Ante 1 consistently. Diagnosis: greedy heuristic fundamentally can't guarantee a high-fan completion — completing 4 chows + pair gives fan 2 (≤320 pts vs 500 target), and the bot can't reliably FORM a high-fan pong (1 lone dragon + 6 random draws ≈ 5% chance of pairing up). Beating the treadmill targets requires either a real lookahead solver (probabilistic draw modeling, multi-step planning, archetype switching with abandonment) — a substantial engineering project — OR softer Ante-1 targets. Sync the improvements either way.

## June 29, 2026 (Bot decision-making upgrade + completion diagnosis)
- Bot shop AI now builds an ENGINE: applies held gems/manuals immediately, buys gems + Hand Manuals (prefers 清一色 manual for its flush line, then chip gems) alongside best-value charms — was charms-only.
- Bot pack-opening rewritten to pick the BEST items via the game API (_draftChosen + _draftConfirmPicks) — fixed a synthetic-click toggle oscillation that hung the opening overlay.
- Added G._autoTurbo(maxTicks): synchronous tick pump so a full campaign can be tested in one call (defeats background-tab setTimeout throttling).
- DIAGNOSIS (proven): the autoplay caps at Ante 1 purely on hand COMPLETION, not balance/scoring. The bot eats "best effort 3/4" partials (~60 pts) vs the 500 target; a COMPLETE flush scores 25,600 (clears trivially), a complete chicken 320. So the game is beatable by a human; the bot needs a stronger completion solver (assemble the 4th meld + a fan source). Scoring re-verified correct (the transient "flush=0" was a test artifact from the bot's running flag, not a bug).

## June 29, 2026 (Full end-to-end verification)
- Regression-tested the day's changes together (no console errors, game loads clean). Scoring suite all-pass: complete flush 25,600 (fan8) · partial 2-kong 2,560 (soft un-gate) · chicken 200 · Kong-manual 4,400 (per-kong) · Pong-gem chips 480 · flush-manual 33,670 · Old Fung cap→10 286,720 · Grey Judge strips flush→200 · Heavy Air fan-tax fan8→6 6,400.
- Flows exercised by the bot with zero errors: starter pack open → shop → dice → play. Draft packs build (4). New bosses render with lore (Old Fung the Capper 封頂佬, Grey Judge 灰判官). Help/tutorial shows the new 半糊 Partial row + corrected meld base (Chow 20/Pong 40/Kong 80).
- SIMULATOR aligns with the game: same flush hand = 25,600 in both; +×2 charm = 51,200 in both (positional pipeline). Constants match (meld 20/40/80, gem 30/30/60/20 chips, manual mults, FAN cap 40). Fixed: the faithful-calculator fan slider maxed at 20 — raised to 40 so it can reach the cap / limit hands (verified fan40 → 109.95T = 100×2^40).

## June 29, 2026 (Shop — true no-scroll, Balatro-style single buy row)
- Finished the shop: the buy column's 3 stacked sections (Charms / Consumables / Vouchers) now collapse into ONE wrapping row of cards. Done in CSS: #shop-buy-col → flex-wrap; the section labels hidden; the row wrappers (#shop-jokers-row/#shop-consumables-row/#shop-vouchers-row) set to display:contents so their cards become direct flex children and flow together. Added align-items:flex-start + .shop-card{flex:0 0 auto} to stop the content-height cards collapsing to 0 in the wrap row (the circular-stretch bug I hit first).
- Verified on 844×390: 7 buy cards in 2 wrapping rows (112px, fully visible), shop content 321px, overflow 0, Next/exit button visible — no scroll anywhere. (display:contents confirmed working via an isolated test first.)

## June 29, 2026 (Starter-pack + shop readability / no-scroll pass)
- ROOT CAUSE found: the mobile-landscape rules (@media max-height:480) for the starter pack are defined BEFORE the base starter CSS in the file, so on equal specificity the base WON and the mobile compaction never applied (icon stayed 50px, text 7px, etc.). Forced the mobile rules with !important.
- STARTER PACK now fits one screen with NO scroll on landscape mobile (verified 0 overflow, Open button visible): each charm name on its OWN line (display:block, no wrap), brighter readable text (preview #9ca3af→#e2e8f0, 7px→10px), compact icon (24px) + tight chrome, inline descriptions dropped (tap an item for the full popup), economy notes hidden, and the cursed-pack bane text clamped to 2 lines. Base .dp-preview-item is now block/one-per-line everywhere; .dp-slot-preview brighter.
- SHOP compacted for landscape mobile (new @media block placed AFTER the base shop CSS so it wins): smaller cards (130→80px), 2-line desc clamp, rarity line hidden (shown via border), tighter headers/labels/gaps, brighter desc. Cut content height ~773→~479px. Kept overflow-y:auto as a SAFETY so the Next/exit button is always reachable (never clipped). NOTE: a true single-screen no-scroll shop (Balatro-style one item row) still needs a layout redesign — the 3 stacked sections are the structural cost.

## June 29, 2026 (SOFT UN-GATE — partial hands now score)
- Removed the all-or-nothing cliff: an incomplete hand (pair + fewer than 4 melds) used to score a hard 0. Now it scores what you built — meld base + gems + the Kong manual + per-meld fan (2^fanMelds). A COMPLETE 4-meld+pair still additionally unlocks the whole-hand patterns (清一色/碰碰糊/limit…), flower fan, the +1 self-draw baseline, and the whole-hand manuals — so completing is always the bigger payoff, but a small hand of strong melds (e.g. 2 dragon Kongs) now beats a complete hand of junk.
- Mechanic: fanMelds (per-meld fan) now counts toward fanTotal even when not winning; baseMult = 2^fanTotal always (was isWinning?…:1); the !isWinning branch scores s.chips×s.mult×cf instead of 0. The Kong manual moved to a per-meld pass that fires on any hand; the other manuals (patterns) stay gated to complete hands. The "need a pair to Eat" floor (雀頭) is kept — that's the mahjong eyes requirement.
- Verified: 2 dragon-Kongs + pair (incomplete) 0→2,560; +Kong manual →4,400; plain 1-pong+pair →40; complete flush still 25,600 (fan 8, full patterns). Help table updated (📋 Incomplete 0 → 🧩 Partial 半糊 Base×2^meld-fan; meld base 2/4/8 → 20/40/80).

## June 29, 2026 (Kong Manual — per-Kong instead of "exactly one")
- 孤槓 Lone Kong Manual → 槓秘笈 Kong Manual: now pays +30 Chips & +2 Mult PER Kong scored (was: only when exactly one kong). addHL gained a `times` param; key renamed loneKong→kong (scoring, consumable, level tracker). Verified: 1 kong +30/+2, 2 kongs +60/+4, 4 kongs +120/+8.

## June 29, 2026 (Level tracker UI + simulator roster refresh)
- IN-GAME TRACKER: new 📚 寶石/秘笈 strip on the left panel shows owned leveling progress — 寶石 (gem chip bonuses per meld type: 上/碰/槓/副 +N籌) and 秘笈 (Hand Manual levels: 清一色 Lv2 · 雞糊 Lv3 …). Renders from _pBonus + _handLevels in updateUI, shows only non-zero entries, hides when you own none. Verified live.
- SIMULATOR: refreshed sparrow-economy.html roster to match the consolidated economy — 4 chip-gems (Cinnabar/Lapis/Amber/Carnelian) + 8 Hand Manuals (replacing the stale +mult gem entries), and rewrote the "charms & gems by type" reference table (chip-gems / manuals as the two planet axes, scaling charms, fan-disruption bosses, Porcelain/Pearl tiles, fan cap 40).

## June 29, 2026 (Leveling consolidation — two slim axes, ~12 total like Balatro)
- The leveling pool was bloated (10 meld-type gems + 8 hand manuals = 18) and overlapping (All-Pongs manual vs Pong gem both fired on the same hand). Consolidated to two NON-overlapping axes, 12 total:
  • GEMS (4) — raw CHIP economy only (mult stripped): Cinnabar 朱砂 +30 chips/Chow, Lapis 青金 +30/Pong, Amber 琥珀 +60/Kong, Carnelian 紅瑪瑙 +20/group. (Removed Malachite/Amethyst/Crystal/Mother-of-Pearl/Obsidian/Jade — their mult role now belongs to manuals.)
  • HAND MANUALS (8) — pattern PAYOFF (chips+mult), unchanged.
- Now gems grow the Chips side, manuals grow the Mult side — never the same lever twice, and the pool is small enough to actually find/build (Balatro has 12 planets, 1:1 with hands; we now match). Scorer's leftover pb.*Mult reads are harmless dead code (no gem sets them). Verified: Pong gem 240→480, Kong gem unaffected with no kongs, All gem 240→440, all chips-only.

## June 29, 2026 (Hand Manuals 秘笈 — planet cards for HAND PATTERNS)
- NEW consumable line (type 'gem', joins the planet pool): permanently LEVEL UP a whole hand pattern — Balatro-planet style, +chips & +mult each time that pattern scores, stacking. Stored in a new run-state field _handLevels (mirrors _pBonus: default/reset/save/load all wired). Scoring reads it inside the pattern block and folds hlChips→baseChips, hlMult→s.mult (chips before mult).
- Legit patterns: Full Flush 清一色秘笈 (+30/+3), All Pongs 碰碰糊秘笈 (+25/+2), All Chows 平糊秘笈 (+20/+2), Dragons 三元秘笈 (+30/+3).
- JOKE hands (invest to make the worthless worthwhile): 雞糊秘笈 Chicken (a hand with NO pattern at all, +45/+4), 無舌頭秘笈 Nonsense (all THREE suits present — "makes no sense", +35/+3), 孤槓秘笈 Lone Kong (exactly one kong, +30/+2), 斷么九秘笈 All-Middles (only 2-8 tiles, no terminals/honours, +35/+3).
- Each shows "Lv.N" in the scoring breakdown. Gated correctly: a manual only credits when its pattern is actually present (verified: Full Flush manual 25,600→33,670; Chicken manual 200→2,280; Chicken manual does NOT touch a flush). Distinct from the gem cards, which level meld TYPES (Pong/Kong/Chow) rather than whole hand patterns.

## June 29, 2026 (De-Balatro'd tile enhancement names)
- Renamed the two Balatro-named tile enhancements (display only — internal ids 'glass'/'prismatic' kept so all scoring/badges/refs still work): Glass Tile 玻璃牌 → Porcelain Tile 瓷牌 🫙 (fragile fine china, ×2 Mult, 25% shatter — the shatter now fits the name), Prismatic Tile 七彩牌 → Pearl Tile 珠牌 🦪 (×1.5 Mult). Updated both apply-scrolls (Glass Beads → Porcelain Glaze 瓷釉; Rainbow Charm → Pearl Lustre 珠光 🦪), the score-step labels (🫙 Porcelain× / 🦪 Pearl×), the shatter flash, and the apply flashes. Also renamed the 'Prismatic Trove' shop pack → 'Treasure Trove 七彩寶藏' 💠 (dropped the Balatro word; internal tier key 'prism' unchanged).
- Verified ids intact: Porcelain still ×2 (240→480), Pearl still ×1.5 (240→360). (Other enhancement names — Foil/Bonus/Mult/Steel/Gold/Lucky — are also Balatro-derived; left as-is unless you want a fuller pass.)

## June 29, 2026 (Engine-gate D fix + bane/starter-pack audit)
- D — FIXED a balance bug I'd shipped: Old Fung's fanCap DECREASED with ante (9→8→7) while targets RISE, making his Ante-7 blind mathematically unbeatable (needs fan ~9-11, capped at 7). Modeled fan-needed-per-ante vs cap and flipped it: fanCap now = min(13, ante+4) → 9/10/11 at antes 5/6/7. This still guts limit-hand cheese (20→capped) but is clearable by a built engine (chips × charms × a normal fan hand) — exactly the engine-gate intent. No gem buff needed; the engine reaches targets under the softened cap.
- BANE AUDIT: 'Slow Hands 慢手 (−1 play)' was DEAD — the plays system was removed, and its handler secretly applied −1 draw, making it an exact duplicate of 'Dry Well'. Repurposed to **Heavy Air 濁氣** (bane type 'fantax'): −1 fan on every scored hand, all run — a real curse in the new fan economy, using the reserved _jState.fanTax hook. Wired the handler (recomputed each blind, cleared by Absolution). Verified: full-flush fan 8 → 7. Fixed the charm tooltip that mislabeled every non-gold bane as "play".
- STARTER PACKS reviewed: opening always offers 3 safe archetypes (Starter/Scholar/Hunter) + an opt-in Cursed pack (free Rare+U+gem+wild with a random bane). Sound risk/reward, no forced bane. The bane fix improves the Cursed pool quality.

## June 29, 2026 (Fan-disruption bosses — challenge layer B)
- Two new scoring hooks counter the uncapped-fan engine: bossEffect.fanCap (clamps total fan this blind) and bossEffect.noPatternFan (flush/all-pongs/dragons/limit patterns score 0 fan — only per-meld + self-draw remain). Plus a _jState.fanTax hook reserved for future run-long banes.
- Two new bosses with full bilingual lore:
  • Old Fung the Capper 封頂佬 (Tier 3, ante 5+) — fanCap = max(6, 9−(ante−5)): enforces the traditional HK house fan-limit, so a big hand alone won't clear — you must win on chips/charms. (Thematic nod to the real-world fan ceiling.) Verified: 大三元 fan 12 → skimmed to 6.
  • The Grey Judge 灰判官 (Tier 4 finisher, ante 7+) — noPatternFan: sees through grand hands; only plain per-meld fan (kongs, dragon/wind/terminal pongs) counts. Verified: pattern fan stripped.
- These join the existing fan-disruptors (The Mute = no wind fan, Madam Fa = no flower fan, Thirteen Eyes = only honour/terminal fan, Fei = melds need honours → blocks flushes).

## June 29, 2026 (Treadmill targets — blinds scale ~3.6×/ante to match uncapped fan)
- Reworked ANTE_BASE to an exponential curve so uncapped fan can't trivialize the run (a lone flush ~20k now dies by Ante 4; Ante 8 demands a built engine). Approved curve: 500 / 1.8k / 6.5k / 23k / 84k / 300k / 1.1M / 4M (×1/1.5/2 per Small/Big/Boss). Ante-8 boss = 8M; a limit hand (~16M) still clears it.
- Endless (ante > 8) continues via anteBaseTarget() formula at ×3.6/ante (Ante 9 boss = 28.8M, …) instead of reading off the end of the array. _computeBlindTarget now calls anteBaseTarget(ante). Verified all antes 1-9.
- Still pending (the B+D of the plan, targets-first per request): fan-blocking bosses/banes for disruption, and confirming late targets reward the chip engine (gems) not just fan.

## June 28, 2026 (Fan uncapped — 2^fan no longer clipped at 10)
- FAN_MULT_CAP 10 → 40 (and MAX_FAN limit-hand award 10 → 20). No real hand reaches 40 fan, so practical play is now effectively uncapped, while 2^40≈1.1e12 stays far under float64's 1.8e308 even after charm ×Mult stacking. Solver fan cap matched (10→40) and the economy simulator's FAN_CAP too.
- Effect: high-fan hands finally pay off. Verified — 大三元 (fan 15) now scores 160×2^15 = 5,242,880 (was clipped to 160×2^10 = 163,840).

## June 28, 2026 (Scaling charms + economy simulator)
- NEW charm family — SCALING (Balatro-style permanent growth), replacing 4 weak/redundant commons (144 count preserved): Abacus 算盤 (was Quick Sort) +0.3 Mult/Pong-Kong permanently; Tally Sticks 竹籌 (was Even Keel) +0.2 Mult/Chow; Prayer Beads 念珠 (was Middle Path) +0.25 Mult per hand completed; Dragon Ledger 龍冊 (was Jade Pendant — which was nearly dead since scored melds never contain pairs) +0.6 Mult per Dragon Pong/Kong. They start weak and grow into monsters over a run.
- Mechanic: scaling state lives in G._jState (resets per RUN, not per blind) so it accumulates all run; the solver snapshots/restores _jState, so bot projections read the current value but don't corrupt it. Verified: Abacus grew 0.6→1.2→1.8 over 3 hands; solver eval bumped 5.0→5.3 then reverted to 5.0.
- NEW TOOL: sparrow-economy.html — God of Sparrow mult-economy simulator (open /sparrow-economy.html). Tab 1 faithful calculator (real 2^fan base, meld 20/40/80, a reorderable charm list that proves positional ordering, +Mult-vs-×Mult breakeven, and a dropdown of the real 23-entry charm/gem roster). Tab 2 design sandbox (log-space, uncapped fan + retrigger loops, shows how far short of Balatro's 7.14e2665 we are and the 3 missing pieces). Sim-only — does not change the game.

## June 28, 2026 (Scoring: melds score as WHOLES — tiles no longer add their rank)
- DESIGN FIX (per feedback): individual tiles were adding their NUMBER as chips (a 4-5-6 Chow popped +4+5+6 and folded into the score — a leftover from the Balatro-parity rebalance). Reverted: tile ranks contribute ZERO. A meld now scores as a whole, regardless of which tiles compose it.
- Raised meld base values so whole-meld scoring is meaningful: Chow 上 = 20, Pong 碰 = 40, Kong 槓 = 80 (was 2/4/8); pair = 0. baseChips = Σ meld values + charm/gem/enhancement bonuses only.
- Removed the `s.chips += runChips` tile-rank fold; rewrote the scoring animation so each MELD pops its whole value and individual tiles pop ONLY a wild/enhancement bonus (plain tiles don't pop). Solver evalScore + live Eat-preview updated to whole-meld values too.
- Verified in-engine: 大三元 (4 Pongs) → base 160 (4×40) × 2^10 = 163,840. Two Chows of 7-8-9 + two of 1-2-3 → identical base 80 (4×20) — high vs low tiles score the SAME, confirming ranks no longer inflate.

## June 28, 2026 (Flower numbering split: Flowers Arabic, Seasons Chinese)
- Per feedback, half the flower tiles show Arabic and half Chinese numerals: Flowers 梅蘭菊竹 → 1 2 3 4; Seasons 春夏秋冬 → 一 二 三 四. (Both still map 1=East…4=North for the seat-match flower fan.) Verified all 8.

## June 28, 2026 (Flower tiles: correct HK numbering + number spacing)
- HK correctness: flowers AND seasons are both numbered 1-4 (matching seat winds 1=East…4=North). Seasons were showing Chinese numerals 一二三四 while flowers showed Arabic 1-4 — inconsistent. Now both show Arabic 1-4 (seasons = stored num−4). Verified the full set: Plum 1梅🌸 · Orchid 2蘭🌺 · Chrysanthemum 3菊🌼 · Bamboo 4竹🎋 · Spring 1春🌱 · Summer 2夏🌞 · Autumn 3秋🍁 · Winter 4冬❄️ — number, name character and picto all paired correctly.
- The big number was jammed against the top edge / colour bar. Moved it down (top 1→12px·scale, font 23→20) so it clears the t-bar; picto re-centred, name at the bottom. Verified on a real tile: number starts 12px from top, no overlap.

## June 28, 2026 (7788 reworked → hold-in-hand pairs)
- 7788 七七八八 was nearly useless: its ×2 fired only at "tenpai", but a complete winning hand clears the tenpai flag, so it never triggered on an actual win. Reworked into a HOLD-IN-HAND charm (joins Four Heavenly Kings): keep ≥2 PAIRS unplayed in your hand at scoring → ×2 Mult; ≥3 pairs → ×3. Literal to the name (七七八八 = pairs of 7s/8s) and now works on winning hands. fx reads G.hand; honour pairs and the pair inside a triplet both count. Verified ×1/×2/×3 at 1/2/3 held pairs. (The old _tenpai/_computeTenpai machinery is now unused but left in place — harmless.)

## June 28, 2026 (Meld caption above slot + flower pictograph)
- Meld-type caption (上 Chow / 碰 Pong / 槓 Kong / 雜 Junk) moved ABOVE the dotted slot instead of inside it (top:-15px, centered) — the placed tiles were covering it. Verified the badge now sits above the slot top edge.
- Flower tiles now show an actual flower/season PICTOGRAPH in the middle (was missing): 🌸🌺🌼🎋 for the four flowers, 🌱🌞🍁❄️ for the four seasons, with the big number on top and the small Chinese name (梅/蘭/菊/竹·春/夏/秋/冬) at the bottom.

## June 28, 2026 (Flower fan nerf — authentic SEAT rule)
- BALANCE: flowers no longer give a free +1 fan EACH (the biggest skill-less fan leak). Now a flower/season scores +1 fan ONLY if its number matches your SEAT wind: East=1 (Plum/Spring) · South=2 (Orchid/Summer) · West=3 (Chrys/Autumn) · North=4 (Bamboo/Winter). Seat is set by the dice each blind, so a hand now earns 0–2 flower fan instead of a flat +(flower count). The 7+ flowers = MAX fan jackpot still uses the full collected count, and the wall/charm flower-fan doublers still apply to the seat-matched count. Help text + scoring comment updated. Verified seat-match counts (East→Plum+Spring=2, South→Summer=1, West→0, North→Bamboo=1).
- Rationale: score = baseChips × 2^fan, so cutting ~2–4 free fan divides typical scores by ~4–16× — far more impactful than trimming the (linear) chip base. Holding the chip-base reduction in reserve until this is playtested, to avoid overcorrecting back toward unwinnable.

## June 28, 2026 (Empty status pill fix + Four Heavenly Kings = hold-in-hand charm)
- BUG: an empty dark rounded "box" showed in the middle of the table with no text. Cause: #status-text has a permanent background+border+padding, so when flash() cleared its text to '' the styled pill stayed visible (a ~33×11 empty box dead-centre). Fix: `#status-text:empty { display:none; }` — the pill only renders when it actually has a message. Verified: empty → display:none, with text → block.
- CHARM REWORK — Four Heavenly Kings 四大天王 is now a HOLD-IN-HAND charm (Balatro-style retention): instead of needing Wind Pong/Kong on the board, you get +2 Mult per DISTINCT wind (東南西北) kept UNPLAYED in your hand at scoring, ×2 Mult if you hold all four. You only need 1 of each — no carving them into melds. This creates a real tension: those 4 hand slots can't also be melds, so you choose. fx now reads G.hand (winds left in hand after placing). Note: the only prior hold-in-hand mechanic was the Steel tile enhancement (×1.5 Mult per steel tile held); Four Heavenly Kings is the first CHARM to use the idea.

## June 28, 2026 (Mobile layout: pair/tail overlap, readable flowers, bigger charms, lower board)
- FIX (mobile): the Pair box was hidden UNDER the Dragon-Tail draw button. Both lived in the top-right (pair box at the right end of the board row, the Tail/Wall/Draw button column also top-right). Measured the collision on a 844×390 landscape viewport (pair x638–791 vs tail x773–820). Fix: narrowed #board-wrap on mobile (right:64px) so the meld-slot row + pair box end at x752, clearing the x773 button column. Verified collides:false.
- Meld slots moved LOWER: #board-wrap top 48→92px (abs y64→y108), filling the dead vertical band that sat between the board and the hand. Verified board bottom 184 < hand top 223 (no overlap), and clear of the charm bar (charms now end ~y82).
- Charms BIGGER & readable: .jcard 42×56 → 56×76 on mobile, icon 18→24, name 7→8; #jokers max-width 55→58%, overlap -14→-18 so 6 still fit.
- Flower tiles redesigned for readability: dropped the tiny/blank unicode flower glyph. New face = BIG number on top (1–4 for flowers, 一二三四 for seasons) + the flower/season character large in the middle (梅/蘭/菊/竹 · 春/夏/秋/冬), tinted to the flower's colour. Flower tile scale 0.58→0.70. Verified the larger flowers tuck under the pair box (x638+) without clipping the hand (hand right edge 631 → flowerHandCollision:false).

## June 28, 2026 (SCORING REBALANCE: tile ranks are the chip base — Balatro parity)
- ROOT-CAUSE FIX for "the autoplay can't beat even Ante 1." Diagnosed: real score = baseChips × 2^fan, but baseChips was ONLY the sum of meld values (Chow 2 / Pong 4 / Kong 8) ≈ 12–20 for a whole hand. Ante-1 targets are Small 300 / Big 450 / Boss 600, so clearing ANY blind required fan ≥ 5–6 (a full flush) every single time — mathematically out of reach even for perfect play. The strong solver duly stalled at Ante 1.
- The code already computed Balatro-style per-tile chips (runChips += tile.num + foil/bonus/stone, with retriggers) and ANIMATED them popping — but that total was never added to the scored s.chips (it only drove the animation + a base-snap delta). So tile ranks contributed ZERO to the real score.
- FIX: fold the per-tile total into the scored chips. New helpers tileChipVal(t)/tileChipSum(groups) next to meldBaseValue. Real scorer now does s.chips += runChips before the base snap, so the meld-value base lands on top of the tile-rank base (animation reads naturally now: tiles pop up, then base snaps on). The live Eat-preview estimate and the solver's evalScore() were updated the same way so previews and bot decisions stay consistent.
- RESULT (verified in-engine): a completed normal hand now scores hundreds–thousands instead of ~12–50; a 大三元 limit hand scored 74,752 at Ante 1. The autoplay now completes 4-meld hands and clears the Small blind (was: "Eat best effort 2/4" → instant loss). Early antes are clearable by normal play; fan/flush remain the path to the big late-ante targets. Wilds = +30 chips, honours score their num, flowers excluded.

## June 28, 2026 (碰 = Pong everywhere)
- Renamed every player-facing "Pung" → "Pong" (HK Cantonese romanisation the user prefers). Covers: meld badges (碰 Pong), the help/tutorial fan table & examples, the reveal banner (Pong 碰! ✦), and charm names + descriptions — Pong Drummer 碰鼓, Coin Pong 錢碰, All-Pong Banner 碰碰旗, Wind/Dragon Pong wording, Jade Dragon set ("Dragon Pongs score as Kongs"). Internal variable names (hasPung, dragonPungs, allPung) and code comments left as-is — not shown to the player.
- The 碰碰糊 fan ("All Pongs") already read Pong; unchanged.

## June 26, 2026 (Meld badges: clear on reset + Chinese; no more eat-selection)
- BUG: meld type badges (CHOW/PONG…) persisted into the next blind. init() was removing ".slot-type-label" but the badge class is ".slot-type-badge" — wrong selector. Fixed to remove .slot-type-badge on board reset. Verified: badge present → cleared after reset.
- Badges now bilingual: 上 Chow / 碰 Pung / 槓 Kong / 雜 Junk (was bare CHOW/PONG/KONG/JUNK).
- EAT SELECTION REMOVED: with only 4 meld slots + 1 pair there's nothing to choose, so endTurn now auto-selects every meld on the board + the pair and scores immediately — no clicking meld slots. Removed the toggleEatSlot onclick from slots and the pair box. Kept the single 'no melds placed' confirm guard. Verified: eat scores with an empty _eatSelection.
- (Pung vs Pong: used 碰 Pung to match the rest of the app's wording — say the word if you prefer 碰 Pong.)

## June 26, 2026 (Fix double-tap select on touch — hover peek now mouse-only)
- BUG: on mobile, unselecting a hand tile took two taps. Cause: the card-stacking hover-peek (scale 1.18 + lift) used :hover, which STICKS after a tap on touch devices. When you tapped to unselect, the tile lost .sel and the sticky :hover immediately applied the pop — the tile jumped/enlarged instead of settling, looking still-selected, so it took another tap. (toggleSel itself is a clean single toggle — verified 0→1→0.)
- FIX: wrapped all the hover-peek rules (.tile2d.hov, .mj-tile:hover pop, .sel:hover) in @media (hover: hover) and (pointer: fine). PC/mouse keeps the hover-peek; touch devices get no hover effect at all, so a tap cleanly selects/deselects with no scale interference. The JS .hov class can still be set on touch but now has zero visual effect. Fixes it across the board.

## June 26, 2026 (Draft pack: tighter item hit-box + hover-bold)
- Starter/draft packs: each item line (.dp-preview-item) was display:block, so its hit box filled the whole row — clicking anywhere on the line opened the item info popup instead of selecting the pack. Changed to inline-block and made .dp-slot-preview a flex column with align-items:flex-start, so each item hugs JUST its text. The rest of the row + slot is now pack-clickable (the pack onclick already ignores clicks landing on an item). Applied on desktop and mobile.
- PC hover: items now bold + subtle highlight on hover so it's clear when you're over the item vs the pack.
- (Couldn't pixel-verify in the headless preview — the starter screen renders at 0×0 there, the same flakiness that breaks screenshots — but the CSS is logically sound.)

## June 26, 2026 (4 meld slots, charm position, flowers, dynamic score font)
- BOARD 9 → 4 meld slots + pair. Scoring only ever uses 4 melds (selectedMelds.slice(0,4)); you can't build >7 melds from a hand; even Thirteen Orphans fits in 4 junk groups + pair. So 9 was wasted space. MELD_SLOTS=4, HTML trimmed to 4 slots, grid repeat(3,1fr)→repeat(4,1fr) (one row). Frees ~180px of felt — the board is now a single tidy row.
- CHARMS were halfway down the felt: mobile #topbar kept margin-top:50px, dropping the charm row onto the board. Set margin-top:2 on mobile and moved the board below the charms (board-wrap mobile top 6→48; desktop 64→84). Verified no overlap on mobile (charms 6–62, board 64–138) and desktop (+16px gap).
- TILES re-enlarged now that the board is 1 row: mobile scale factor 1.15→1.34 → 45×66 (vs the cramped 39×56). Full layout fits: charms (top) → board (1 row) → hand (2 rows, 45×66) → controls, all clear.
- FLOWERS: scale 0.7→0.58 (more compact) and excluded from the hover-pop (they're set-aside, not read-interactive).
- SELECT double-scale FIX: the hover-pop scale was stacking on top of the selection lift. Hover peek now applies only to :not(.sel):not(.mj-flower); selected tiles just lift (no second scale).
- LEFT SCORE FONT — evaluated the min supported sizes (Press Start 2P ≈ 1em/glyph; left panel usable ~129–148px): at the old fixed 24px, 7–8-char scientific values (2.50e22 = 168px, 1.00e308 = 192px) overflowed. Added _fitText() dynamic sizing (with !important to beat the mobile font rule): normal scores stay 24px; 2.50e22 → 18px (126px), 1.00e308 → 16px (128px) — every value now fits, down to the e308 worst case. Applied to the running score + the win-panel/animation score updates.

## June 26, 2026 (Mobile layout fit — tiles were too big, overlapping board)
- ROOT CAUSE found by measuring rects (screenshot tool unusable — times out on this page all session): the felt has a 60px decorative border, so on a 375-tall phone only ~255px was usable, and the 3-row meld-slot board alone was 242px → the hand overlapped the board by 120px at 48×70 tiles.
- FIXES (mobile landscape):
  - Felt frame thinned 60px → 16px border (reclaims ~90px vertical + width; usable height 255 → 343).
  - Mobile tile scale factor 1.42 → 1.15 (cap 0.66): tiles now 39×56 (was an over-sized 48×70; original 28×41) — readable and they fit.
  - Board-wrap mobile top 22 → 6 to nudge the board up.
  - Result (measured, 18-tile hand): board 22–222, hand 229–327 → +7px gap (NO overlap); hand sits 4px above the controls bar; board(3 rows)+hand(2 rows)+controls all fit the 375 felt.
  - Buttons follow --tile-w so they’re now 39×56 too (still match tiles, 30px stack gaps from prior fix).
- Flowers: set-aside flowers render small in the side panel (~16×22), not as felt tiles, so they don’t affect the felt fit — verified no overlap.
- Desktop unchanged (h>540 keeps the normal scale → 65×94; 720 felt has ample room).

## June 26, 2026 (Right-button spacing; confirmed tiles = draw-button size)
- BUTTON SPACING: the three right-edge buttons (Draw / Wall / Tail) stacked with only 16px/10px gaps, so with the bigger tiles the Wall button collided with the Draw button's count badge (badge sticks out top:-9px). Widened to a uniform 30px gap (BTN_GAP) between each. Measured: 30px Draw↔Wall and Wall↔Tail, no overlap.
- TILE SIZE CONFIRMED: forced an 18-tile deal and measured — hand tiles render 48×70, identical to the Draw button's 48×70 on phone-landscape. Tiles already match the button. If they still LOOK small on a device it's (a) browser cache — hard-refresh; or (b) viewing in PORTRAIT, where the whole landscape game scales down to fit width and everything shrinks. The game is mobile-landscape; rotate the phone.

## June 26, 2026 (Mobile tiles actually big now — diagnosed the squish)
- DIAGNOSIS: the +20% base bump WAS applied (mobile tiles measured 28→34px), but mobile-landscape applies a global tileScale ≈ h/720 ≈ 0.52, so a 20% bump on an already-tiny tile (6px) was barely perceptible. The squish was the real problem, not the bump.
- FIX: tileScale() now BOOSTS on short screens (h ≤ 540): scale = min(0.82, h/720 × 1.42). On a 375-tall phone-landscape, mobile tiles are now 48×70px — measured +71% vs the original 28×41 — clearly readable. Desktop (h=720) is unaffected (still 65×94 from the +20% base).
- BUTTONS on mobile were hard-pinned 38×54 !important; changed to var(--tile-w)/var(--tile-h) so Draw/Wall/Tail buttons match the (now larger) tiles on mobile too (48×70).
- ROW_SPLIT 20 → 11: with big tiles a long hand was cramming into one heavily-overlapped row; now it splits into 2 clean rows past 11 tiles (e.g. 18 → 9+9, each within the non-overlap capacity). Still 2 rows max (no 3rd). Verified an 18-tile hand fits vertically (top 257 / bottom 327 on a 375-tall felt, no overflow).
- NOTE: if it still "looks unchanged" on a device, it's browser cache — hard-refresh (the LAN node server sends no-store, but the production/SFTP copy or a cached tab may serve stale).

## June 26, 2026 (+20% tile size, parity, card-peek hover, tile-sized buttons)
- TILES +20% on BOTH platforms (feature parity): TILE_W_BASE/TILE_H_BASE 54×78 → 65×94. Everything that sizes off --tile-w/--tile-h scales up: hand tiles, board meld slots, pair box, and the Draw/Wall/Tail buttons. Desktop renders 65×94; mobile-landscape scales to ~34×49.
- BUTTONS now match tile size. They used --tile-w/h already but had `transition:all .15s`, which animated the width change and left them visually stuck at the old 58×82. Changed to `transition:box-shadow/transform/opacity` so size applies instantly → Draw/Wall/Tail buttons now render exactly tile-sized (65×94).
- GENTLER OVERLAP: hand-row compression floor 0.45×TILE_W → 0.58×TILE_W, so a crowded hand fans less aggressively (tiles stay readable). Still 2 rows only (no 3rd row), splitting past 20 tiles. Realistic peak hands (deal 18–22 + draws) fit without clipping.
- CARD-PEEK: hovering any tile now pops it up + scales 1.2× above its neighbours (z-index 900) so partially-overlapped tiles can be read — same affordance as charm cards. On touch, tapping a hand tile selects+lifts it for the same reveal. (No hover/tap spread-out widget; just per-tile pop.)
- Non-overlap capacity at +20%: desktop ~28 across two rows, mobile ~30 — both comfortably exceed the max hand a player holds.

## June 26, 2026 (Fan-archetype planning + wild-tile fan note)
- NEW: multi-draw FAN-ARCHETYPE planning (G._SOLVE.chooseArchetype + archetype-aware keepers). The bot now commits to a high-fan SHAPE across the blind's draws instead of just completing "any 4 melds":
  - Flush 清一色/混一色: on a genuine suit lean (≥8 of one suit AND ≥12 of 14 usable counting wilds+honours), it commits to that suit and DISCARDS off-suit tiles first, then draws to fill — building toward +7/+3 fan.
  - Honours 字一色: commits when honour+wild ≥12.
  - Wilds (joker tiles) count as flex fillers toward any shape (they're excluded from flush checks, so they never break it).
  - Safety valve: only commits while ≥2 draws remain; with ≤1 draw left it bails to plain completion so a half-built flush still finishes as a chicken hand rather than an incomplete 0.
  - Tuned conservative after an initial loose threshold caused incomplete (3/4) losses — commitment now only fires on hands that can clearly support it.
- WILD-TILE FAN (answer to "14 wilds = how many fan?"): wilds are filtered out of all fan-pattern checks, so an all-wild hand makes `numbered` empty and the All Honours 字一色 check (`numbered.every(isHonour)`) passes VACUOUSLY → MAX fan (10, ×1024), plus +30 chips per wild (+420 for 14). Effectively an auto-max win. NOTE: this is a vacuous-truth edge case, not deliberate design — flag for review. The achievable real play is a few wilds + one suit = Full Flush (+7), since wilds don't break the single-suit check.
- RESULT: solver verified strong (flush-commit test passes; charm-aware eval; optimal decomposition) but with the $10 start it still caps ~ante 1 — Small clears (~320) but Big (450) falls short on fan/charm-mult, and sampled seeds lacked flush leans. The $10 economy nerf is now the binding constraint on how far it climbs.

## June 26, 2026 (Strong solver: max-meld search + charm-aware scoring + economy)
- ECONOMY: Reduced starting draft budget $20 → $10 (harder early economy; makes the starter draft a real choice and forces economy play). Tunable.
- SOLVER (G._SOLVE): replaced greedy meld-finder with a real OPTIMAL search:
  - suitMelds(): per-numbered-suit max-meld decomposition via memoized DP (finds the most pungs+chows extractable from a suit).
  - decompose(): honour pungs/kongs + per-suit DP → all disjoint melds. Auto-forms kongs from 4-of-a-kind.
  - best(): tries every candidate pair, decomposes the rest, and picks the (pair + ≤4 melds) that MAXIMIZES projected score.
- CHARM-AWARE SCORING (the key ask): evalScore() runs every owned charm's REAL fx(s, gs, G) over the candidate hand (plus editions), exactly like finishRound — so charms, relics, editions, flowers and fan are all weighed, not just melds. _jState is snapshot/restored so eval has no side-effects. Verified: a hand scores 20 with no charms → 60 with Lucky Cat (+20 chips); a 4-dragon-pung hand evaluates to fan 19 / score 16384.
- FAN model: full per-meld (dragon/seat/prevailing-wind/terminal/kong) + patterns (碰碰糊/平糊/清一色/混一色/大三元/小三元) + flowers + 自摸 baseline.
- ECONOMY BUYING: shop picks the best-VALUE affordable charm (charmValue heuristic: mult/chip scalers > resource > economy, rarity-weighted) and keeps a $10 interest cushion unless the charm is strong.
- THROTTLE FIXES: deal animation and dice roll resolve INSTANTLY in bot mode (they used setInterval/setTimeout that background tabs throttle to ~1/sec, stalling inter-blind transitions).
- RESULT: the bot now plays optimally and considers charms/economy, but with the $10 start it still caps ~ante 1 — Small-blind hands clear, Big-blind (450) falls just short on fan/charm-mult. Reaching the final boss/ante-9 would need deeper multi-draw fan-archetype planning (commit-and-build a flush/dragon hand across draws) and/or a less-nerfed economy.

## June 25, 2026 (Solver autoplay + crash-proof server + seed campaign)
- SERVER: Replaced flaky `npx serve` for the Mahjong preview with a dedicated crash-proof Node static server (Mahjong/serve-mahjong.js): single long-lived process, no-store cache headers, uncaughtException/clientError guards so it never dies on a bad request. launch.json mahjong config now runs `node serve-mahjong.js`. Fixes the every-1-3-minute server deaths that were wiping in-page state.
- AUTOPLAY → SOLVER: Replaced the old rigid flush bot strategy (which left hands incomplete) with a gather-to-completion + fan-aware solver:
  - DRAW-FIRST gather: draw out the hand, THEN cycle only true-junk tiles with discards (preserves meld/pair potential instead of churning it away).
  - planWin(): tries each candidate pair, finds the best disjoint 4-meld decomposition in the rest (pung/dragon-weighted for fan), reserves the PAIR before placing so hands don't end pairless.
  - findMelds(): tries pung-first AND chow-first orderings, keeps whichever yields more melds.
  - Runs the entire blind SYNCHRONOUSLY in one tick (immune to background-tab setTimeout throttling), yielding only for the eat/score panel.
- BOT MODE: animations disabled while the bot runs (no-anim style + scoring step timers cut to ~6ms), so no more renderer hangs / eval timeouts. Tick 500ms → 140ms. Stuck-animation recovery: if _animating is true for several ticks with no overlay showing, force-clear so a hung score animation can't deadlock the bot.
- SEED CAMPAIGN (persisted in localStorage, survives reloads/crashes): plays a fixed seed; on a loss, records best ante reached and retries the SAME seed up to 10 times; after 10 fails, bumps to the next seed and resets. Stops + flags on an Ante-8 victory. Spends gold on charms in the shop each visit.
- Verified the solver completes 4-meld hands and clears blinds (e.g. seed 88888 Small blind: 4 melds + pair, 680 pts), flows through shop → next blind → boss intro (auto ⚔ Fight) without hanging, and the campaign auto-retries/auto-bumps seeds unattended.

## June 24, 2026 (Cheat menu: Bosses page — view every boss card)
- NEW: 👿 Bosses 終局 tab in the cheat menu. Lists all 37 bosses grouped by tier (I Openers / II Mid / III Late / IV Finishers), each tagged with its earliest ante (A1–A8, FINAL for ante-8). Click any boss to open its full intro card — name, TIER badge, powers, and the full story paragraph — exactly as it appears before a fight.
- Pure viewer: clicking ⚔ Fight or the backdrop just closes the card and returns to the cheat menu (_bossIntroResume set null). No gameplay effects fire, no boss state set — verified bossEffect stays null and phase unchanged. Card renders above the cheat panel (z-index 9500 vs 65).
- Implemented via _cheatBuildBosses() + _cheatShowBoss(id), which inline-resolves the boss (scale at its minAnte + descFn) without touching the active run, then reuses the existing _showBossIntro card.

## June 24, 2026 (Boss story cards + endless escalation + autoplay deadlock fixes)
- LORE: Rewrote all 37 BOSS_LORE entries from one-liners into full bilingual STORY PARAGRAPHS (who they are → their grudge → what they do to you). The pre-fight boss card already renders these — verified Crooked Mouth Fai shows a 343-char paragraph with name, TIER badge, powers, and story, then ⚔ Fight 開戰. No bosses renamed (per user) — every name kept; the story carries the folklore.
- NEW: Endless escalation. Beating Ante 8 no longer dead-ends — _winGame() now introduces the NEXT stake deck (perks/banes) on a "CHALLENGE CLEARED 過關" card showing its level, name, and modifiers. The restart button becomes "▶ Next Challenge: <stake>", restart() applies the queued stake, and the landing screen pre-selects it. Verified bronze→silver advance. Climbs Casual Table → Parlor → Pearl → Night → Hard Slates → Boss's Cut → God of Gamblers → Heavenly Game, then a GRAND VICTORY 圓滿 ending. Highest stake cleared persisted to localStorage (sparrow_max_stake).
- CHARM AUDIT (144 intact, sacred count verified):
  - FIXED 'empty_hand' 空手 (Legendary) — was 'Chicken hands (0 fan) +5 Mult', dead since self-draw +1 makes 0-fan impossible (and chicken path ignores mult anyway). Repurposed to 'All-Chow hands 平糊 (no pungs/kongs): +5 Mult' — now live on the multiplier path.
  - FIXED dead 'playsBonus' references (plays system was removed): 'Slow Hands 磨牌' wall (+2 draws/-1 play → +2 draws/start $8 poorer, a real tradeoff); 'God of Gamblers 賭神' and 'Heavenly Game 天場' stakes ('-1 play' → '-1 more draw, -2 total', a real penalty via drawsBonus:-2).
  - Vestigial seltzer/countdown-retrigger consumer code confirmed dead-but-harmless (no charm uses it).
  - Runtime audit: multi-run autoplay produced 0 charm fx errors.
- AUTOPLAY FIXES (two deadlocks that blocked end-to-end runs):
  - Score panel: the bot's 'if(_animating) return' guard ran BEFORE the score-stage handler, but _animating stays true while the panel awaits the "Take Money" click — so the bot bailed every tick and never dismissed it. Moved score-stage (and win/over reveal) dismissal BEFORE the animating guard. (Humans were never affected — the button onclick runs regardless.)
  - Boss intro: the bot had NO boss-card handling and would stall at every boss blind. Added ⚔ Fight (bi-fight-btn) click. Verified bot dismisses both.
- STRESS TEST: re-verified — 'Stress test complete ✓', 0 errors, expands to 12 charm slots + speed-advances antes.
- TUTORIAL/RULES: updated for the +1番 self-draw baseline, new chicken definition (below the Wind's min fan, not 0 fan), the uncapped fan tier display (MAX/超凡/神級/超現實), charm drag-to-reorder (neighbour charms), boss story cards, and endless stake escalation.

## June 23, 2026 (38 三八 peek-panel no longer covers hand)
- FIX: When the player owns charm 38 三八 (peek next 3 wall tiles), the peek panel that hangs to the LEFT of the Draw button was overlapping the rightmost hand tiles. layoutHand now adds 84px to the right-reserve when this charm is held, shifting all hand tiles left by ~84px so the peek panel sits in clear space. Verified: rightmost tile X 1140px → 1056px when 38 is added.

## June 23, 2026 (Boss Intro Fight button fix)
- FIX: ⚔ Fight 開戰 button on Boss Intro popup was unclickable. #boss-intro lives inside #ui (which has pointer-events:none for click pass-through to scene tiles), and boss-intro didn't override it — so clicks passed through to whatever was behind. Added pointer-events:auto on #boss-intro. Verified: button now sits on top at its own center coordinates instead of #shop-vouchers-row.

## June 21, 2026 (UX polish: silent self-draw, board gap, tap target, flash dismiss)
- CHANGE: Self-Draw +1番 baseline is now silent — since every win in this solo game is structurally a self-draw, labelling it was redundant. The +1 still applies; just no "🎯 自摸 Self-Draw" entry in patternNames or help text.
- LAYOUT: Closed the gap between charm bar and board. #board-wrap top 92px → 64px (desktop), 152px → 22px (mobile via media query). Board now sits much closer to the charms above.
- LAYOUT: Board grid z-index raised 1 → 3 (above charm bar). Top-row meld slots get a 12px (18px mobile) ::after click extender pseudo-element so taps slightly above the visible border still register — addresses the "top row hard to select on mobile" issue.
- FLASH: Default duration reduced 2000ms → 1500ms. Status warnings now also dismiss on click (cursor changes to pointer while a flash is showing). Eliminates lingering "Kong 槓!" / "轉運 Changing Luck" middle-screen banners.

## June 21, 2026 (Self-Draw 自摸 +1番 rule + partial-selection bug fix)
- RULE: Every winning hand now starts at 🎯 自摸 Self-Draw +1番 baseline. Since this game has no opponents to discard, every win is structurally a self-draw — we surface it explicitly per HK tradition. Shown as the first entry in the patternNames flash and the win-panel breakdown.
- FIX: Partial-selection "Incomplete" bug. Previously: if you clicked 4 meld slots to highlight them for Eat but didn't also click the pair box, the hand was rejected as Incomplete even though the pair sat right there on the board. Now: if a pair exists on the board, it's auto-included when meld selections are made.
- REDEFINED: isChicken — true 0-fan wins are now impossible (self-draw guarantees ≥1番). "Chicken hand" now means: a hand qualified as winning but fell below the Wind's minimum-fan gate (only matters at W5+). Animation panel label now reads "🐔 N番 < Mff番 min — base meld value only" so the player understands why their valid win didn't multiply.
- AUDIT: Confirmed no charm/boss interactions broken. Crooked Mouth Fai targets per-meld 0-fan (chows specifically), not hand totals — unaffected. The Bone 自摸骨 is unrelated to fan. All pattern-fan charms add on top of the +1 baseline as expected.
- HELP TEXT: Updated to explain the self-draw baseline rule and that "below gate" hands still score base meld value.

## June 21, 2026 (Status flash auto-clear fix)
- FIX: flash() now also clears textContent on timeout (was only resetting color), so messages like "轉運 Changing Luck!" or "Kong 槓!" no longer linger on the middle status line indefinitely.
- Uses a flashId guard so a newer flash that arrives before the older timer fires won't get prematurely wiped by the older timer.

## June 21, 2026 (Balatro-style score + uncapped fan tiers + charm-bar squeeze)
- NEW: fmtBig() formatter — score chip and blind target now display as 4,321 → 12.35M → 1.5B → 314Q → 2.50e22 (scientific past quadrillion).
- NEW: Score chip tier classes — score-mega (≥1M pink), score-giga (≥1B purple pulse), score-tera (≥1T cyan pulse), score-broken (≥1Q rainbow shimmer with "naninf" Balatro homage past Number.MAX_SAFE_INTEGER).
- NEW: Fan tier system (display only — scoring multiplier still capped at FAN_MULT_CAP=10 to prevent overflow). Tiers: 1-4番 gold, 5-7番 warm, 8-9番 red pulse, 10番 rainbow shimmer + "MAX 滿" plaque, 15番+ "超凡 TRANSCENDENT" gold radial, 20番+ "神級 GODLIKE" tri-color storm, 25番+ "超現實 UNREAL" with score reading "naninf".
- NEW: this._lastFanTrue tracks uncapped fan total for tier display (e.g. with Big Three Dragons + All Pongs + dragon kongs + winds you can hit 18番 truly; multiplier is still ×1024 but the plaque shows TRANSCENDENT).
- NEW: Score-stage win panel now shows true 番 with "(capped N)" note and applies the tier class to the +score number.
- FIX: Preview score ("~X pts · Eat 食糊!") also formatted with fmtBig and shows fan tier label.
- NEW: Charm bar (#jokers) now squeezes adaptively based on data-count attribute. Margins: 7 charms -8px, 8 -18px, 9 -22px, 10 -26px, 11 -30px, 12-16 -34px. Verified 12-charm row fits in 322px of a 1280px viewport. Max-width raised from 55% → 65% to give charms more room before consumables.
- SLOTS ANALYSIS: Documented every charm-slot source. Permanent voucher cap = 7 (Paint Brush + Antimatter), but Negative-edition charms each add +1 (uncapped), and Folding Table / Long Bench / Nesting Box keep +1 to +2 empty slots beyond current count. Realistic absurd max ≈ 16 charms.

## June 21, 2026 (Charm reordering always-on)
- CHANGE: Charms in the top charm bar can now be dragged to reorder at any time before Place / Eat.
  - Previously gated behind a never-active "hasArranger" flag (legacy Arranger charm hook).
  - Enables tactical positioning for neighbor-affect charms like Blueprint (copies charm to its right) and Mirror Pond (copies charm to its left), and any future left/right-relative charms.
  - Drag visuals already wired: grab cursor + dashed purple outline on drop targets + "🔀 Relic order updated!" flash on commit.

## June 20, 2026 (Boss Intro popup + Guided Play foundation)
- NEW: Boss Intro popup — dramatic pre-fight cinema fires before every Boss Blind. Shows:
  - Tier badge (TIER I/II/III/IV · 等級一/二/三/四, with "FINAL BOSS 最終" tag for ante-8)
  - 96px boss icon with colored glow
  - Boss name (English Cinzel + 中文 in huge gold serif)
  - One-line lore (italic, bilingual)
  - POWERS 招式 box listing the live ante-scaled effect description
  - Pulsing red "⚔ Fight 開戰" button
  - Hint: "[ click Fight or tap backdrop · 按開戰或點背景 ]"
  - Screen-shake event on appearance (body shakes via boss-shaking class), card slams in with a 0.42s bounce
  - Backdrop tap also dismisses
  Architecture: _startBossBlind now picks the boss + resolves effect for preview, shows intro, then queues the actual boss-effect-apply for after the user clicks Fight (via this._bossIntroResume callback → _startBossBlindFight). All 37 boss effects continue to fire as before — just gated behind the intro.
- NEW: BOSS_LORE constant — one-line backstory for every one of the 37 bosses (bilingual). Examples:
  - tyrant_tung: "The grand chancellor of corruption. He caps your draws — make every one count. 董太師封抽數,每抽都要算盡。"
  - lady_meng: "Old crone at the Bridge of Forgetfulness. Her soup makes you forget a suit — play from memory. 孟婆湯令你忘記一色。"
  - blood_demon: "Ancient demon of Zu Mountain. Corrupted Blood spreads — at 5 marks, the hand halves; at 7, it implodes. 血魔毒血漫延。"
- NEW: Guided Play 引導對局 — FTUE foundation:
  - "▶ Start Guided Play 開始引導" button inside the How to Play overlay (always available, never forced)
  - CSS: full-screen dim spotlight with 9999px box-shadow cutout, pulsing yellow border, callout bubble with arrow, pause/resume button bottom-right
  - JS controllers: _startGuidedPlay, _guidedShowStep (with step state machine), _guidedAdvance, _guidedSkip (pause/resume — lets player play freely without ending tutorial), _guidedComplete, _guidedStackHand (forces a pong-friendly opening)
  - Fixed seed: GUIDED01 (reproducible)
  - Pre-built charm trio: Lucky Cat 招財貓 + Pung Drummer 碰鼓 + Mrs. Mak 麥太
  - 8-step script defined (welcome → suggest → place → eat → take money → next blind → big blind hint)
  KNOWN GAP: the FTUE init currently invokes restart() which lands on the title/starter-pack screen instead of dropping the player straight into a dealt blind — so the spotlight has no #hand element to anchor to. Next-pass fix: skip dice roll, skip starter pack, and call init+_dealAnimation directly. The plumbing (CSS, HTML, JS controllers, charm injection, hand-stacker) is all in place; just needs the bypass wiring.
- Tutorial Help overlay updated to reflect 37 bosses, 8 stakes, Walls/Stakes unlock, Take Money button, popup tap-to-see — text-only.
- Cheat menu polish: bilingual labels everywhere, fixed stale "MYTHIC" rarity → "LEGENDARY 傳奇".

## June 20, 2026 (consumables HK-themed rename + cheat menu polish)
- Cheat menu — bilingual + corrected:
  - Title/Resume/New buttons all bilingual (🏠 Title 標題 / ▶ Resume 繼續 / ▶ New 新局)
  - "Unlock Walls & Stakes 解鎖牆與注", "Wild Tiles 萬能牌 · in hand now · 手中"
  - Vouchers and Editions explainers translated 中文
  - FIXED rarity label: was "MYTHIC" — we don't have Mythic charms, it was a stale Rummikub holdover. Now "LEGENDARY 傳奇" (matches actual rarity tier in JOKER_POOL).

- Consumables rename — Western tarot / generic terminology replaced with HK / Mahjong / Chinese cultural names. Ids unchanged so all wiring intact, only display names changed.

  **Runes (7)** — Western tarot → HK fortune / temple symbols:
  - The Star 星宿 → Big Dipper 北斗七星
  - The Moon 月光 → Mid-Autumn Moon 中秋月
  - The Sun 太陽 → Lunar New Year Sun 新年陽
  - The World 天地 → Eight Trigrams 八卦
  - Rune of Power 力量符 → Tiger Talisman 老虎符
  - Rune of Abundance 豐收符 → Lucky Bamboo 富貴竹
  - Rune of Sight 明察符 → Fortune Mirror 照妖鏡

  **Scrolls (22)** — "Scroll of X" pattern replaced with HK paper-charm / temple names:
  - Shimmer → Joss Paper 金紙
  - Valor → Hero's Charm 英雄符
  - Fury → Wrath Talisman 怒符
  - Chaos → Trickster Paper 玩笑符
  - Fragility → Glass Beads 玻璃珠
  - Iron → Iron Will 鐵心
  - Earth → Mountain Stone 山石
  - Midas → Golden Touch 點金術
  - Fortune → Lucky Star 福星
  - Prism → Rainbow Charm 七彩符
  - Gilding → Gold Leaf 金箔
  - Dyeing → Dye Pot 染缸
  - Strength → Iron Strength 鐵力
  - Decay → Death Note 死符
  - Hermit → Hermit Master 隱仙
  - Judgement → Yama's Verdict 閻王令 (Yama = Chinese underworld judge)
  - Fool → Fool's Coin 傻仔錢
  - Flame → Bonfire 火堆
  - Swap → Tile Trade 換牌
  - Tower → Demolish 拆樓
  - Lovers → Yuan Fen 緣分 (fated love)
  - Wheel → Wheel of Fortune 風水輪

  **Spirits (12 of 19)** — HK ghost / hungry ghost festival entities:
  - Phantom 幻影 → Hungry Spirit 餓鬼魂
  - Specter 幽靈 → Yin Spirit 陰魂
  - Banshee 哭靈 → Wailing Ghost 哭婆
  - Money Misprint 假錢 → Hell Money 冥鈔 (joss paper money)
  - Poltergeist 鬧鬼 → Restless Spirit 不安魂
  - Eclipse 蝕影 → Solar Eclipse 日蝕
  - Sigil of Gold 金印 → Wealth Seal 財印
  - Sigil of Fire 火印 → Vermillion Seal 朱印 (Taoist protective)
  - Sigil of Water 水印 → Dragon Seal 龍印
  - Cryptid 神獸 → Mountain Spirit 山神
  - Black Hole 黑洞 → Black Pit 無底洞
  - Medium 通靈 → Spirit Medium 通靈人
  (Kept: Wraith 怨靈, Revenant 亡魂, Apparition 顯靈, Soul 魂魄, Aura 靈氣, Trance 出神, Sigil of Shadow 影印 — all already HK-feel.)

  **Vouchers (12 of 28)** — HK market / parlor / temple terms:
  - Overstock 多備 → Tea House Stock 茶樓存貨
  - Wasteful 浪費 → Spendthrift 散財童子
  - Paint Brush 畫筆 → Calligraphy Brush 書畫筆
  - Clearance Sale 清貨 → Year-End Sale 年尾清貨
  - Telescope 望遠鏡 → Fortune Teller's Glass 算命鏡
  - Seed Money 種子金 → Lai See Money 利市本金 (red packet money)
  - Gem Merchant 寶石商 → Jade Dealer 玉商
  - Scroll Merchant 符商 → Temple Vendor 廟販
  - Magic Trick 魔術 → Sleight of Hand 變戲法
  - Hieroglyph 古文 → Oracle Bone 甲骨文 (Chinese oracle script)
  - Nacho Tong 雙拼 → Dim Sum Two 點心雙拼 (HK dim sum culture)
  - Glow Up 鍍光 → Polish 拋光
  (Kept: Grabber, Palette, Crystal Ball, Blank, Omen Globe, Observatory, Recyclomancy, Antimatter, Liquidation, Money Tree 搖錢樹, Casting Call 選角 — already on-theme or universal terms.)

  (Known follow-up: a handful of flash messages in apply() funcs still reference the old item names like "The Star: x2 Chips this turn!" — they fire briefly during item use and will be swept in a follow-up pass.)

## June 19, 2026 (batch 5 — complete bilingual descs)
Every `desc:` string in the game now bilingual (English · 中文). The popup _showCardInfo displays the desc text as-is, so charm/consumable/voucher/scroll/spirit/bane descriptions all show 中文 automatically — no engine change needed. Totals translated this batch:
- 52 Uncommon charm descs (Scaling, Win-Style, Wind Manipulation, Economy+, Retrigger, Defensive, Slot)
- 28 Rare charm descs (Build-Defining, Copy/Clone, Special Tile Sets — Jade/Phoenix/Kirin, Chaos)
- 8 Legendary charm descs (God of Gamblers, Guan Yu's Blade, Empty Hand, Immortal Wall, Eight Flowers, 145th Tile, Mahjong Saint, Heaven and Earth)
- 28 Voucher descs (all Tier 1 + Tier 2 — Overstock, Wasteful, Paint Brush, Clearance, Telescope, Seed Money, Gem/Scroll Merchant, Hone, Grabber, Palette, Casting Call, Magic Trick, Hieroglyph, +2 variants, Crystal Ball, Blank, Omen Globe, Observatory, Nacho Tong, Recyclomancy II, Antimatter, Liquidation, Money Tree, Glow Up, Planetarium, Periscope, Recasting, Nacho Plus)
- 7 Rune descs (The Star, The Moon, The Sun, The World, Power, Abundance, Sight)
- 22 Scroll descs (Shimmer/Valor/Fury/Chaos/Fragility/Iron/Earth/Midas/Fortune/Prism/Gilding/Dyeing/Strength/Decay/Hermit/Judgement/Fool/Flame/Swap/Tower/Lovers/Wheel)
- 19 Spirit descs (Phantom/Wraith/Specter/Banshee/Money Misprint/Revenant/Poltergeist/Apparition/Eclipse/4 Sigils/Cryptid/Black Hole/Soul/Aura/Trance/Medium)
- 5 Mahjong Fortune Stick descs (Seat Swap, Paper Fan, Dice Fortune, Deep Gaze, Wall Shake, Mama Pays)
- 9 Bane descs (Blood Tax, Slow Hands, Dry Well, Cracked Tile, Short Table, Stuck, Fading, Rent Due, Loan Shark)

Pattern is consistent: `<English> · <中文 summary>`. Total items: ~178 descriptions translated this batch alone, on top of ~110 from earlier passes. Every popup, every shop card, every preview tooltip now shows both languages.

## June 19, 2026 (front page polish + tile enhancement descs + popup hint)
- Front page (Landing screen) overhaul:
  - 太歲 enlarged from 18px → 56px (Cantonese hero, gold with glow)
  - God of Sparrow enlarged from 11px → 28px Press Start 2P
  - ls-btn vertical padding 11px → 6px (more compact stack)
  - All landing buttons bilingual:
    - ▶ New Game 新局
    - ⟳ Continue Run 繼續
    - ❓ How to Play 玩法
    - 📋 Changelog 更新
    - 🤖 Auto 自動
    - 🧪 Stress 壓測
  - Seed input placeholder: "5-digit seed 種子 (or blank)" · random-seed button tooltip 隨機種子
  - Seed label: "Seeded runs produce identical games for the same seed · 同種子產生相同遊戲"
- Card-info popup hint: "[ tap anywhere to close · 點任何位置關閉 ]"
- Tile Enhancements (Gold Tile etc.) — all 11 descriptions now bilingual via replace_all (covers both definition sites: shop pool + spirit/scroll application descs):
  - Foil Tile 箔牌, Bonus Tile 賞牌, Mult Tile 倍牌, Gold Tile 金牌, Color-Wild 萬色牌, Glass 玻璃牌, Steel 鋼牌, Stone 石牌, Lucky 幸運牌, Gilded 鍍金牌, Prismatic 七彩牌 — each desc now ends with · 中文 summary.

## June 19, 2026 (rename + charm desc translation)
- Game renamed: **Sparrow → God of Sparrow**, with **太歲** above the title on the landing screen. Browser tab now reads "God of Sparrow 太歲".
- Charm DESCRIPTIONS: all 56 Common-tier charms now bilingual (English description · 中文 summary). Examples:
  - "Red Dragon tiles +15 Chips · 紅中 +15籌"
  - "+1 draw per blind; +5 Chips per unused draw · +1抽,每未用抽 +5籌"
  - "Sell charms for 50% more gold · 賣護符 +50%"
  - "+1 Mult when you score both a chow and pung in the same round · 同回合有上同碰 +1倍"
  - Wind/region rows: 東圈 +1抽, 南圈 +1棄, 西圈商店 -20%, 北圈 +25籌
  All 56 Common descs touched in this turn. Each line follows the "English · 中文" pattern used elsewhere in the game so the popup _showCardInfo just displays both halves automatically — no engine change required.
- (Remaining: ~88 Uncommon/Rare/Legendary charm descs + ~25 voucher descs + ~22 scroll descs + ~19 spirit descs + ~9 bane descs + 11 tile-enhancement descs. Same mechanical translation, just hasn't been done yet.)

## June 19, 2026 (batch 3 bilingual + popup dismiss fix v2)
- Card info popup: removed the stopPropagation on the inner panel so the displayed hint "tap anywhere to close" actually works. The user kept hitting the description (inner panel) — taps were being eaten. Now ANY tap on the popup (inner panel, hint, backdrop) dismisses cleanly. preventDefault + 300ms grace window kept so the dismiss-click can't bubble to anything underneath.
- Help / How-to-Play overlay — bilingual sweep:
  - Title: HOW TO PLAY 玩法
  - Section headers: 🀄 Goal 目標, 🎯 Meld Types 牌型, 💎 Scoring 計分 — Three Tiers 三級, 🔄 Blind Flow 局流, 🏰 Game Structure 結構, ⚡ Key Concepts 要點, 🎮 Controls 操作
  - Scoring table headers: Hand Type 牌型, Score 分, When 條件
  - "Incomplete 未糊" row + 中文 conditions inline
  - Blind Flow paragraph: Small 小盲 / Big 大盲 / Boss 終局, 144 tiles, 18-tile deal, 6 draws / 3 discards — Chinese inline
  - Game Structure: "8 Winds 八圈", "each with 3 blinds 每圈三局", trailing rationale in 中文
  - Key Concepts each line: Flowers 花牌, Charms 護符, Gems 寶石, Vouchers 優惠券, Dice Roll 擲骰, Boss Blinds 終局
  - Controls table: Key 鍵 / Action 動作, every action gets · 中文
- Game-over / victory screen — bilingual labels:
  - Best Hand 最佳牌型, Run Stats 戰績, Defeated By 敗於
  - Stat rows: Tiles Played 出牌, Tiles Drawn 抽牌, Groups Played 落副, Ante 圈, Blinds Beaten 過局, Run Score 總分, Gold Earned 金錢, Seed 種子
  - Titles: GAME OVER 終局, VICTORY 勝利
  - Victory subtitle: "All 8 Antes Cleared! · 八圈全勝!"
  - Restart button: ▶ Play Again 再玩
- Wall & Stake landing-screen dropdown headers already bilingual (WALL 牆 / STAKE 注) — no change needed; verified.
- Charm-slot "EMPTY" — no actual text to translate; empty state is purely visual (dashed border, low opacity).

## June 19, 2026 (batch 2 bilingual)
- Shop screen: all visible labels now bilingual
  - Heading 🛒 Shop 商店, gold display (icon already universal), Reroll 重抽
  - Buy column: 🛍 Buy 買, Charms 護符, Consumables 消耗品, Vouchers & Wild Tile · 優惠券與萬能牌
  - Sell column: 💰 Sell 賣, Your Wilds 你的萬能牌, Your Charms 你的護符
  - Sub-hints: "sell for $2 · 賣$2", "drag to reorder · half price · 拖動排序 · 半價"
  - Pack store first-visit subtitle: "Open a pack to upgrade your run · individual items available from your next shop onward · 開包升級 · 單品從下次商店起出售"
  - Empty state: "All packs opened! → Proceed to next blind · 全部已開 · 進入下一局"
  - Next Blind 下一局, Pack Store — First Visit · 首次包店
  - Shop info label: "+$X blind 局獎", "+$X interest 利息", "+$X unused draws 未用抽"
- Left panel (in-game topbar): Score 分, Target 目標, Draws 抽, Disc 棄, Small Blind 小盲 / Big Blind 大盲 / Boss Blind 終局, pool "tiles 牌", "in hand 手"
- Left-panel blind type badge: SMALL 小 / BIG 大 / BOSS 終
- Boss banner: "Tier 等級 I/II/III/IV · …"
- Cheat menu tabs: 🏺 Charms 護符 / 🎴 Tiles 牌 / ✨ Consumables 消耗品 / 🎫 Vouchers 優惠券 / 💿 Editions 版式
- Dice roll subtitle: "Wind 風 1 — Round 局: 東 East"
- Pack-opening pick counter: "Choose 選 0 / N" (was "Choose 0 / N")
- Relic overflow panel: ⚠ RELIC OVERFLOW 寶物過多, "click to discard the ones you don't want · 點擊要捨棄的", Start Run 開始
- BLIND_NAMES constant updated so dynamically-set labels propagate everywhere (advance flash, shop heading, save panel, etc.).

## June 19, 2026 (later still)
- Starter-screen popup-dismiss bug FIXED: on mobile the touchend→synthesized-click chain was leaking past the dismissed popup and toggling the pack underneath. Fix: ontouchend now bound on the popup overlay too, _closeCardInfo calls preventDefault+stopPropagation, popup keeps pointer-events for 250ms after dismiss, and the pack-card onclick gates a 300ms grace window against `_popupClosedAt`. Verified end-to-end: clicking a preview item opens the popup, backdrop click dismisses it cleanly, and the pack underneath does NOT toggle selection.
- Starter screen bilingual UI pass:
  - Pack names: Copper Chest 銅箱, Gilded Coffer 鎏金櫃, Prismatic Trove 七彩寶藏, The Bronze Vault 青銅寶庫, The Silver Archive 白銀典藏, The Golden Hoard 黃金寶藏, The Cursed Tomb 詛咒古墓
  - Pack tiers: Standard 普通, Jumbo 大號, Mega 特大, Balanced 均衡, Strategic 策略, Aggressive 進攻, ☠ Cursed 詛咒
  - Pack descs: "4 items · choose 1 (四選一)" etc., flavor lines also bilingual
  - Title: "Choose Your Starting Pack 選擇起始包"
  - Budget row: "Draft Budget 預算" / "unspent gold carries into the run · 剩餘金錢帶入"
  - Buttons: 🔄 Refresh 重置, ⬆ Upgrade 升級, 🌟 Premium 頂級, ✌️ Open Two 開兩個, Open Pack 開包, Take Items 取物
  - Button notes also bilingual (Reroll all pack items · 重抽包內物品, etc.)
  - Footer hints: "← Click a pack to select it · 選一個包", "Pack selected! Click Open Pack → 已選,按開包", "Pick 2nd pack to open · 選第二包", "⚠ Cursed Tomb 詛咒古墓 selected — bane 詛咒: ... Proceed? 繼續?"
- Rarity & item-type labels now bilingual across all rLbl maps (3 spots) and inline rarity labels (5 spots):
  - Common 普通, Uncommon 罕有, Rare 稀有, Legendary 傳奇, Wild 萬能 / Wild Tile 萬能牌, Enhancement 改造
  - Item types: Planet 寶石, Rune 符文, Charm 護身符, Spirit 靈, Scroll 符
  - Pack-preview tier chip: "Relic 寶物 · Uncommon 罕有" (was "Relic (Uncommon)")
- (Remaining audit scope, not yet touched: shop section headers "Buy/Sell", in-game topbar labels "Draws/Disc/Gold/Ante/Blind", boss banner "Tier I/II/III/IV" labels, tutorial overlay copy, dice roll subtitles, charm slot-empty placeholder text. These are smaller pockets — list them and I can sweep in a follow-up.)

## June 19, 2026 (later)
- Seat Wind on left panel now shows EN heading: an "EAST SEAT" line (cyan) above the existing 座 東風. Matches the round-wind block's bilingual style. (`lp-seat-wind-en` element + JS hook in updateUI.)
- Comprehensive bilingual rename — every consumable/voucher/edition/sigil/tile-enhancement now carries a Cantonese 中文 name alongside English. Touched roughly 80 items, ids and effects unchanged:
  - 7 Runes (The Star 星宿, The Moon 月光, The Sun 太陽, The World 天地, Rune of Power 力量符, Rune of Abundance 豐收符, Rune of Sight 明察符)
  - 22 Scrolls (Shimmer 閃光符, Valor 勇氣符, Fury 怒火符, Chaos 混亂符, Fragility 易碎符, Iron 鐵符, Earth 大地符, Midas 點金符, Fortune 福運符, Prism 棱鏡符, Gilding 鎏金符, Dyeing 染色符, Strength 力符, Decay 衰敗符, Hermit 隱者符, Judgement 審判符, Fool 愚者符, Flame 火焰符, Swap 互換符, Tower 高塔符, Lovers 戀人符, Wheel 命運輪)
  - 19 Spirits (Phantom 幻影, Wraith 怨靈, Specter 幽靈, Banshee 哭靈, Money Misprint 假錢, Revenant 亡魂, Poltergeist 鬧鬼, Apparition 顯靈, Eclipse 蝕影, Sigils 金/火/水/影印, Cryptid 神獸, Black Hole 黑洞, Soul 魂魄, Aura 靈氣, Trance 出神, Medium 通靈)
  - 28 Vouchers (Overstock 多備, Wasteful 浪費, Paint Brush 畫筆, Clearance Sale 清貨, Telescope 望遠鏡, Seed Money 種子金, Gem Merchant 寶石商, Scroll Merchant 符商, Hone 磨礪, Grabber 抓手, Palette 調色盤, Magic Trick 魔術, Hieroglyph 古文, Crystal Ball 水晶球, Blank 空白符, Omen Globe 兆示球, Observatory 天文台, Nacho Tong 雙拼, plus tier-2 variants 多備加備 / 重生術 / 反物質 / 清算 / 搖錢樹 / 鍍光 / 加調色盤 / 雙拼+ / 行星館 / 潛望鏡)
  - 5 Editions (Polished 拋光, Holographic 全像, Chromatic 七彩, Negative 反相, Gilded 鎏金)
  - 4 Sigils (Gold 金印, Red 朱印, Blue 青印, Purple 紫印)
  - 11 Tile Enhancements (Foil 箔牌, Bonus 賞牌, Mult 倍牌, Gold 金牌, Color-Wild 萬色牌, Glass 玻璃牌, Steel 鋼牌, Stone 石牌, Lucky 幸運牌, Gilded 鍍金牌, Prismatic 七彩牌)
  - Wild Tile shop item → Wild Tile 萬能牌

## June 19, 2026
- Gem consumables (planet cards) renamed to Chinese-centric materials with bilingual names — same ids, icons, and effects:
  - Ruby → Cinnabar 朱砂 (red; Runs of 3)
  - Sapphire → Lapis 青金 (blue; Sets of 3)
  - Emerald → Malachite 孔雀石 (green; Long Runs 4+)
  - Topaz → Amber 琥珀 (yellow; Sets of 4)
  - Amethyst → Amethyst 紫晶 (purple; ALL groups +10/+0.5)
  - Diamond → Crystal 水晶 (clear; mixed set+run turns)
  - Opal → Mother-of-Pearl 螺鈿 (iridescent; 5+ tile groups)
  - Obsidian → Obsidian 黑曜石 (added 中文)
  - Garnet → Carnelian 紅瑪瑙 (red-brown; all-groups chip boost)
  - Jade → Jade 翡翠 (added 中文; all-groups mult)
  Tile-color labels (GEM_COLORS + cheat-menu) updated to match: red=朱砂, blue=青金, orange=琥珀, black=黑曜石.

## June 17, 2026 (latest — Final Boss promotion pass)
- Final Boss alignment with source file (5 of 9 source Final Bosses now in our ante-8 pool):
  - Asia the Invincible 東方不敗 promoted from Tier IV minAnte 7 → minAnte 8 (true Final Boss as the source bills it). Scaling base bumped from 2.0 → 2.2 since it's now ante-8 only.
  - Existing Six Finger Master `six_finger` (Tier II, shifting winds) renamed to Wind Caller 風使 to free the iconic name.
  - NEW finisher: Six-Finger Master 六指琴魔 🎹 (`six_finger_master`) — "Requiem: single-suit hands (清一色 / 混一色) score ×0.5 unless a Dragon meld is held as counter-harmony." Direct counter to flush builds; rewards mixing in a dragon pong. (NEW lever flushCounter.)
  - NEW finisher: Tree Demon 樹妖 🌳 (`tree_demon`) — "Soul Ownership: 2–4 hand tiles are owned by the demon; scoring them DRAINS (their value × 2) from your blind instead of adding." Owned tiles get a green visual filter. (NEW lever treeDemonOwned.)
  - NEW finisher: Blood Demon 血魔 🩸 (`blood_demon`) — "Corrupt Blood: every 2 draws taints a hand tile. 5 corrupted = blind ×0.5; 7+ = blind ×0 (effectively a fail)." Corrupted tiles get a red visual filter; pressure-cooker tempo finisher. (NEW levers corruptionCounter + corruptionEvery.)
  Pool: 34 → 37 bosses. Ante 8 picks from 9 random finishers (Tyrant Tung, Stranger, Tax Man, Madam Mo, Lady Meng, Master Fahai, Asia the Invincible, Six-Finger Master, Tree Demon, Blood Demon — 10 total, no-repeat per run).

## June 17, 2026 (later)
- Boss roster ROUND 2 — deeper import from HK folklore/cinema brief (pool 26 → 34):
  Added 8 new bosses across all tiers with 7 new effect levers (cursedTilesCount, cursedSuit, escortAtStart, stealBestTile, tailEscalation, lowestMeldZero, forbidCategory):
  - Tier I: White Tiger Cub 白虎幼獸 🐯 — marks 1–3 random hand tiles cursed (each scores ×0.95-stacking penalty).
  - Tier II: One-Armed Swordsman's Shadow 獨臂刀影 🗡️ — random suit (萬/筒/索) entirely cursed (hand AND pool).
  - Tier III: Ox-Head & Horse-Face 牛頭馬面 👹 — 2–4 random hand tiles permanently removed at blind start.
  - Tier III: Black Wind Witch 黑風大王 🌪️ — highest-value hand tile stolen at blind start.
  - Tier III: Nine-Tailed Fox 九尾狐 🦊 — every Nth draw is poisoned (cursed); N tightens from 4 to 2 with ante.
  - Tier IV: White Tiger Spirit 白虎煞星 🐅 (minAnte 7) — combines cursedSuit AND 2 cursedTiles, with lateness cut.
  - Tier IV: Eunuch Warlord 九千歲 ⚔️ (minAnte 7) — your lowest-scoring meld contributes 0 pts at Eat.
  - Ante-8 finisher: Master Fahai 法海 📿 — at blind start, ONE tile category (honour / 1s / 9s) is forbidden; using ANY of those in a scored meld halves the entire blind.
  All cursed tiles get a sepia/violet visual filter so the player can see them. Cursed scoring is stacking ×0.95 per cursed tile (so 4 cursed = ×0.81). Pool now 34 bosses; ante-8 picks from 6 random finishers.

## June 17, 2026
- Boss roster refresh (HK folklore/cinema flavor — pool 25 → 26):
  - Reskin: Brother Brick → The Jiangshi 殭屍 🧟 (same draw-loss effect, "rigor mortis" theme)
  - Reskin: Iron Magistrate → Asia the Invincible 東方不敗 🥷 (same dual squeeze, "Forbidden Scripture" flavor)
  - Reskin: The Tooth → Bride of Drowning Pool 新娘池女鬼 👰 (same per-tile handPenalty, "she's still waiting")
  - SWAP: Beggar Bo → The Insatiable 不饜鬼 👻 (boss, distinct from the existing Hungry Ghost CHARM — NEW lever discardCost: each discard action costs $2–$5 scaling with ante; refused if you can't pay even with debt). Replaces the duplicate % score-skim with real economy pressure.
  - NEW finisher (ante-8): Lady Meng 孟婆 🍵 — Soup of Forgetfulness: one random numbered suit displays as ??? for the entire blind. Scoring is unaffected; pure cognitive memory challenge. (NEW lever suitBlackout, hooked in tileGlyph.)
  - Updated Wall Repair charm desc + boss-counter reference (brother_brick→the_jiangshi).
  - The Tooth's flash msg updated to "新娘池: −X pts (tile left in hand)".
  Pool now 26 bosses across 4 tiers; Tyrant Tung promoted to minAnte:8 so ante 8 picks randomly from 5 finishers (Tyrant Tung, The Stranger, The Tax Man, Madam Mo, Lady Meng) — no two finishers can repeat across a run.

- Stake ramp doubled from 4 → 8 (Balatro-style stacking — each step adds ONE thing on top of all prior):
  1. Bronze 散枱 — Casual Table (baseline)
  2. Silver 雀館 — Parlor Game (+25% shop)
  3. Pearl 珠戰 — Pearl Game (+10% Small Blind)
  4. Gold 夜場 — Night Game (banes permanent)
  5. Onyx 硬石 — Hard Slates (−1 draw)
  6. Sapphire 抽水 — Boss's Cut (+30% Boss target)
  7. Jade 賭神 — God of Gamblers (+1 min fan, −1 play)
  8. Crimson 天場 — Heavenly Game (+50% shop OVERRIDE, first drafted charm is eternal)
  draftLockOne wired in _applyDraftItems; all other mod keys already supported.
- 3 new Ante-8 finishers (boss pool 22 → 25, ante 8 now random across 4 finishers, no-repeat per run):
  - The Stranger 過路客 — All score ×0.5, +2 draws (tempo race).
  - The Tax Man 收稅佬 — Pay $1–$2 per meld placed (economy or bust); placement is refused if you can't afford even with debt.
  - Madam Mo 摩太 — Wall is closed, no replacements; win from the 18 you're dealt (closedWall + lateness cut).
  _startBossBlind ante-8 picker rewritten: picks random finisher (minAnte:8) with no-repeat preference; minAnte!==8 bosses are now correctly excluded from ante-8 to keep finishers exclusive.
- closedWall + tributePerMeld effect levers wired in _startBossBlind and _commitGroup respectively.

## June 16, 2026
- Mobile card readability:
  - Every card in the starting-pack opener (.dp-item) and the shop (.shop-card — pack store, charms, consumables, vouchers) now has a small ⓘ button in the top-left corner.
  - Tap ⓘ → a large bilingual popup appears centered on screen: tier chip, big 76px icon, 24px name, 16px full description, with the card's rarity color around the border.
  - Tap anywhere outside the popup (or on the popup's "tap anywhere to close" hint) to dismiss. The inner panel swallows clicks so accidental dismissal doesn't happen while reading.
  - The card body itself still toggles selection/buy as before — the info popup is additive, not in the way.
  - Mobile in-card font sizes also bumped (dp-item-name 9→12px, dp-item-desc 8.5→11px, shop sc-name/desc 9–10px) and text color brightened to #cbd5e1 so it's actually readable at a glance even without opening the popup.
- Scoring screen UX overhaul:
  - The score panel now STAYS UP after the animation — no more auto-dismiss timer.
  - On a WON blind: pulsing gold "💰 Take Money 收錢" button appears; click it (or anywhere on the panel) to advance to the shop.
  - On a FAILED blind: muted "Click to Continue" button appears; the final score turns red. Click to proceed to game-over.
  - The final score number is now much larger (118px Press Start 2P) so it reads as the headline of the screen.
  - Hand name is now its own big, bilingual line at the top of the panel:
    - Cantonese 中文 first (gold #fbbf24, brighter on a full win), separated by a thin gray dot, then the English name (purple #a78bfa on a chicken / loss, green #6ee7b7 on a winning hand).
    - Failed hands show "未糊 · Incomplete" in gray. Chicken hands keep the gold zh but use a muted yellow English. Full wins glow green.
  - Click-to-skip during the animation still works; once the final reveal is on screen, the click finishes and advances.
  - Safety auto-finish (14s) now only fires DURING the animation — once you're at the final reveal, the panel waits for your click as long as you want.
- New themed charms (replacements — pool stays at 144):
  - Four Heavenly Kings 四大天王 👑 (replaces Four Winds Coat) — +2 Mult per Wind Pung/Kong, +5 Mult if all four winds present.
  - Heavenly Queen 天后 👸 (replaces Dragon Throne) — +3 Mult per Dragon Pung/Kong, ×2 Mult on all-three-dragons (大三元).
  - Mrs. Mak 麥太 👩 (replaces the old Loan Shark debt charm) — clears any debt each blind, grants a $20 debt spending limit, and cancels Loan Shark / Rent banes.
- New bane: Loan Shark 大耳窿 🦈 (Cursed Tomb) — escalating interest into debt each blind ($3 → $6 → …); countered by Mrs. Mak.
- 38 三八 now actually PEEKS: a single pinned panel (left of the Draw/Wall column) shows the next 3 wall tiles and updates as you draw. It's one id'd element keyed off owning the charm, so it can never duplicate/crowd the space even with copy charms. (The +Chips bonus already worked.)
- Wired the last 6 unimplemented Rare/Legendary charms:
  - 7788 七七八八 — added tenpai detection (_computeTenpai): x2 Mult when 1 tile/group from a complete hand.
  - Eternal Wall 永恆牆 — once per Wind, restocks up to 3 tiles from the discard pile + grants 3 draws when the wall runs dry.
  - Wheel of Heaven 天輪 — at each Wind (ante), transforms into a random Rare charm you don't already own.
  - God of Gamblers 賭神 — once per blind, a free full-hand redraw when you're out of draws (its +3 Mult already worked).
  - Immortal Wall 不死牆 — draws never run out (Draw never decrements/blocks), but blind targets are +50%.
  - The 145th Tile 第145張 — seeds one special wild into the wall each blind; drawing it is an instant FREE WIN.
- BUG FIX: a 4-tile run (e.g. 1-2-3-4) validated as a Chow and Suggest would auto-place it. A mahjong Chow is EXACTLY 3 tiles — validate() now caps runs (and Chimera mixed-suit runs) at 3. Pungs (3) and Kongs (4) unaffected.
- Audited the Rare/Legendary charm set: most work; flagged 6 still-unimplemented (7788 tenpai, eternal_wall, wheel_heaven, god_gamblers redraw, immortal_wall, tile_145) for a future wiring pass.
- Wired the 6 Defensive / Boss-Tech charms (were description-only, no effect) via a new _applyBossCounters() pass that runs after the boss is resolved:
  - Umbrella 雨傘 — negates the first boss effect met per run (consumed).
  - Windbreaker 防風 — cancels The Mute (wind fan) & Six Finger Master (shifting winds).
  - Lucky Rooster 吉雞 — nullifies Crooked Mouth Fai's 0-fan penalty.
  - Snake Wine 蛇酒 — removes Snake Boy Keung's poisoned-draw effect.
  - Flower Armour 花甲 — restores flower fan against Madam Fa.
  - Wall Repair 修牆 — halves Brother Brick's draw loss, negates Sister Scissors' flower-block.
  - Suit Breaker 破封 — 50% chance to draw through Mr. Nine's locked suit.
  - (Counters work generically against the new ante-scaled bosses.)
- Validated the Slot set (folding_table/long_bench/nesting_box/absolution — all already wired) and FIXED nesting_box 巢箱: it promised "can't be sold" but sellJoker didn't enforce it — now it does.
- BUG FIX (Kirin / Chimera): the 9 "SET:" charm bonuses were referenced in descriptions but NEVER implemented — that's why a Kirin mixed-suit Chow (e.g. 2-sok 3-sok 1-wan) failed and fell to Junk. Implemented the SET-bonus system (hasRelicSet) and all 3 sets:
  - Chimera Hand (Kirin ×3: Hoof+Horn+Heart) — runs may now MIX suits (consecutive numbers across any numbered suits). Requires the full set; a single Kirin piece does not enable it (clarified in descriptions).
  - Phoenix ×3 (Dawn+Dusk+Crest) — the first failed blind per run is forgiven (you rise again and advance).
  - Jade Dragon ×3 (Head+Body+Tail) — Dragon Pungs score as Kongs (+1 kong fan each).
  - Wired Jade Tail's individual effect (Kongs grant +1 extra draw); fixed all 9 SET-charm descriptions to state the real bonus.
- Boss overhaul — tiered + ante-scaling (Balatro gating × Slay-the-Spire "scales with depth"):
  - Expanded pool from 14 → 22 bosses across 4 tiers (Tier I gentle → Tier IV finishers), gated by minAnte (1/3/5/7).
  - Each boss now SCALES with the ante it appears at: numeric bosses scale their magnitude (e.g. Brother Brick 1 fewer draw at ante 1 → 4 at ante 7; Snake Boy every 6th draw → every 4th; Big Spender ×2.0 → ×2.3), and binary-effect bosses gain a "lateness" score-cut (0% at first appearance, up to ~−22% if met late) via _resolveBoss(boss, ante).
  - New bosses: Pickpocket Pinky 三隻手 (fewer discards), Beggar Bo 乞兒波 (score skim), One-Eyed Lung 獨眼龍 (one meld type per turn), Stone Buddha 石佛 (heavy draw loss), Loan Shark 大耳窿 (heavy score cut), The Tooth 獠牙 (penalty per leftover hand tile), The Water Ghost 水鬼 (drawing disabled — finisher), Iron Magistrate 鐵判官 (×target + fewer draws — finisher).
  - Bosses no longer repeat within a run until the eligible pool is exhausted. Banner now shows the tier (I–IV) and the live ante-scaled description.
  - Added discardPenalty lever (mirrors drawPenalty).
- FIXED mobile (landscape) layout: the felt background was shoved into the right half (left:calc(50%+55px)) while the JS positions tiles/board against PANEL_LEFT=172px — so felt, charm slots, meld slots and hand tiles were all misaligned. Felt now anchors at 172px and fills to the right edge; left panel widened to 160px and the charm row shifted onto the felt. Verified at 812×375 and 667×375.
- Cheat menu: added a "🔓 Unlock Walls & Stakes" button (with Locked/✓Unlocked status) to unlock the real game without beating the final boss — for testing/skipping the first win
- Wall & Stake selection is now LOCKED until you beat the final boss (ante 8) once. First victory shows a "🎉 THE REAL GAME UNLOCKED!" spectacle on the win screen and permanently reveals Wall/Stake on the title screen (persisted in localStorage 'sparrow_unlocked'). Locked play always uses the neutral Street Game wall + Casual Table stake.
- Added 3 Dragon Walls (the first 3 wall options once unlocked): Red Dragon 紅中, Green Dragon 發財, White Dragon 白板. Each gives +1 fan per Pong/Kong of its OWN dragon and −1 fan per Pong/Kong of either OTHER dragon, stacking per meld. fan total is floored at 0 so penalties can't produce a fractional score.
- BUG FIX: dragon detection was checking tile.col (always "black") instead of tile.dragon — so dragon Pongs gave no +1 fan and 大三元/小三元 NEVER triggered. Now fixed: dragon Pong/Kong +1 fan works, and Big/Small Three Dragons detect correctly.
- Special limit hands now score: Thirteen Orphans 十三幺 (13 unique terminals/honours + pair, placed as junk groups + pair box — detected automatically at Eat, MAX fan) and Nine Gates 九蓮寶燈 (pure-suit 1112345678999+1, now MAX instead of scoring as plain Full Flush). Junk is allowed by design precisely so 十三幺 can be laid out.
- Added a _detectSpecialHand() scan over all board tiles (junk slots + pair box) so no-meld winning hands are recognised; LIMIT_BASE=16 gives them a base before the ×2^fan multiplier (十三幺 ≈ 16384 pts, 九蓮 ≈ 12288 pts)
- Tutorial fan table now lists Thirteen Orphans with a how-to note
- Junk groups now warn BEFORE placement: the Place button reads "Place Junk ⚠" (amber) and the status bar explains "not a valid meld · 0 pts, can't win"; placing requires a confirming second press. Bot bypasses the confirm so it never stalls. (Junk stays allowed by design — needed for future no-meld special hands like Thirteen Orphans 十三幺.)
- Scoring panel now displays the actual hand name (e.g. 清一色 Full Flush, 平糊, 碰碰糊) instead of a generic "Winning Hand" label — the name was previously only a fleeting flash
- Incomplete hands now explain WHY: e.g. "Only 3/4 valid melds (junk groups score 0)" or "Need a pair 雀頭" — a chow placed with non-consecutive tiles becomes a junk group worth 0, which was the hidden cause of surprise "incomplete" results
- Verified HK scoring: all-one-suit hand with chows + pongs + pair = 清一色 Full Flush (7番), a valid winning hand (per HK mahjong scoring rules)
- Charm/Item row moved up and meld grid moved down so the charm slots no longer overlap the empty meld slots
- Hand tiles: added more padding so tiles don't touch the gold felt border on left/right
- Meld slots: moved grid higher (top:8px), reduced slot height and gap for tighter layout
- Renamed mahjong.html → sparrow.html
- Created deploy.bat and sync-sparrow.ps1 for automated backup + SFTP deploy
- Moved all timestamped backups into revisions/ folder
- Pair box CSS: filled state uses neutral white border instead of yellow (was confusing players)
- Board grid moved higher (top:28px from top:172px) so meld slots aren't buried

## June 14, 2026
- Bot strategy rewrite: flush-first approach targeting Half Flush (+3 fan)
  - pickTargetSuit() locks to board's dominant suit
  - Aggressive off-suit discard phase (dump all non-matching numbered tiles)
  - meldScore() weighs on-suit, honour, dragon, wind bonuses
- Bot now respects all action locks (_animating, _playLock, _discardLock)
- Bot pair finder no longer excludes tiles with 3+ copies
- Bot eat guard: won't attempt eat without pair on board (prevents infinite loop)
- Dice animation changed from infinite to 20 iterations (fixes CDP screenshot freeze)

## June 13, 2026
- Mahjong Mechanics & Scoring Overhaul (Steps 1-7):
  - 18-tile starting hand, 6 draws, 3 discards per blind
  - 9 fixed meld slots (3x3 grid) + dedicated pair box
  - Place-to-slot mechanic with locked melds
  - Kong upgrade with tail draw (轉運 Changing Luck event)
  - Eat (食糊) scoring: chicken = base meld value, winning = base × 2^fan
  - Full HK fan table: All Chows, All Pongs, Half/Full Flush, Dragons, Winds, etc.
  - Discarded tiles leave the game permanently
  - Full blind reset each round
  - Tutorial rewritten with new rules + fan table
  - Charm/voucher audit for removed playsLeft system

08/05/2026 05:33 - Title art replaced: new uniform dry-brush 太歲 calligraphy (user-approved gen), white keyed to transparent (744x1522); old dry-brush version backed up to imagegen/out/title_taisui_prev_drybrush.png
08/05/2026 06:02 - Neon-noir art pass: landing_hero.webp swapped to neon-noir style (high-res gen, all 7 cameo CJK labels verified, 3 English typo labels font-patched: Bride's Pool / Ox-Head / Eunuch); ic_btn_wall + ic_btn_tail regenerated in neon-noir (fake hanzi on wall tiles replaced with real kaiu 發); imagegen local budget cap disabled (limits now on OpenAI account). Backups in imagegen/out/*_prev*
08/05/2026 06:25 - Landing hero decluttered: all prominent neon signboards removed (edges now quiet dark city) so the 太歲 title stands out; 5 label spots re-verified and font-patched (Bride's Pool, Ox-Head &, Horse-Face, Eunuch, Warlord + junk-hull garbage text erased). Previous busy version: imagegen/out/landvar_neonnoir_patched.png
08/05/2026 06:41 - UI overhaul: (1) Boss intro card now LANDSCAPE (poster left, info right) — fits without scrolling on PC + mobile landscape; lore line-clamped. (2) Balatro-style shop: cards are big icon (72px) + Buy/Sell $price only; name/rarity/desc moved to tap-anywhere-on-card info popup; shop fits one screen, no vertical scrolling; shop-inner self-scrolls only as fallback. Backup: revisions/*_presession.html
08/05/2026 08:25 - Icon art completion pass: all 96 remaining text-on-tile placeholder icons regenerated as proper 古惑仔 bold-icon art (vouchers, scrolls, runes, sticks, seals/editions, decks; incl. hand-written subjects for Periscope/YuanFen/HeavenlyGame/PurpleSigil). Old tiles backed up to imagegen/out/placeholder_tiles_backup. ~$4.50 gen cost.
08/05/2026 22:53 - Landing page swap completed: 太歲 dry-brush title baked into the decluttered neon-noir hero (42% scale, upper-left) — landing screen shows the full approved composition again
08/05/2026 23:25 - Removed baked-in 太歲 from landing_hero.webp (it duplicated the existing #ls-title-zh overlay) — hero restored to clean decluttered neon-noir; title renders only via the DOM overlay
08/11/2026 13:08 - QoL+bugfix: (1) Auto-sort hand — new-hand deals and discard-redraws re-sort automatically using the player's last chosen Sort mode (# or colour; default colour), via new G._applySort. (2) EAT/scoring lock — G._animating now mirrors to body.anim-lock: while scoring or deal animation runs, ALL control buttons, draw/tail/wall, tiles, meld slots and keyboard shortcuts are inert (fixes EAT double-press and background-button presses during scoring); 25s watchdog prevents soft-lock.
08/11/2026 14:20 - Guided play fix: tutorial callout no longer blocks selections — (1) callout body is click-through (only Next button interactive), (2) placement now measures real callout size and tries below/above/right/left, picking the first spot that doesn't overlap the spotlighted target, else docks in the farthest corner, (3) positioning runs after content is set so measurements are accurate
08/22/2026 09:35 - New wiki pages: wiki/index.html (How the Game Works — full mechanics reference written from live code: tiles/wall, blind flow, 3-tier scoring + fan tables, run structure w/ real ANTE_BASE targets, dice omens + hot zones, bosses, economy/shop, items, walls/stakes, controls, saves/seeds) + wiki/art-review.html (Art, Sound & Music Review — all 364 images captioned from wiki-data.json w/ orphan detection, 8 music beds w/ players, 29 SFX table; generated by new tools/build-art-review.py). Linked from wiki.html nav + dev.html; sync-once.ps1 now deploys wiki/ (W: + SFTP). NOTE: in-game Help modal targets/fan-cap text is stale vs code (documented in wiki).
08/22/2026 19:58 - ART DIRECTION CHANGE (pilot): new house style is 年畫 'Lucky Print' — Chinese New Year folk woodblock: bold even-weight ink outlines, FLAT colour (no gradients/shadows), strict 5-colour palette (ivory cream / cinnabar / jade / imperial gold / ink brown), paper grain, no baked text. Replaces the 古惑仔 gritty manhua direction, which failed at real icon sizes (18-72px) and mismatched the game's folk-supernatural content. PILOT SCOPE: 8 deck backs (back_*.webp, now bold symmetrical emblems + key-fret border, text-free — old ones were 8 near-identical dark text blobs at the 58x82 draw-button size) + landing_hero.webp (ensemble poster, candidate H1, now native 16:9 1536x864 so the 1280x720 canvas no longer crops away 44%). Style bible: imagegen/style-nianhua.md. New tools: restyle-pilot.py (dry-run + cost ceiling + separate install step), style-contact-sheet.py (judges art at TRUE display size). Old art backed up to imagegen/out/restyle_backup_manhua/. Cost $1.00. Icons + bosses NOT yet restyled.