Remaster of the lobby

.claude/skills/add-slot-menu-item/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: add-slot-menu-item
+description: Add an entry to the CustomLobby slot right-click context menu (e.g. Kick, Move to observers, Close slot). Use when the user asks to add, gate, or scaffold a slot context-menu action in the custom lobby. Edits the declarative list in lua/ui/lobby/customlobby/CustomLobbyMenus.lua and, for a new operation, adds a CustomLobbyController intent.
+---
+
+# Adding a slot context-menu item
+
+One edit in most cases: append an entry to the `SlotMenu` list in [CustomLobbyMenus.lua](/lua/ui/lobby/customlobby/CustomLobbyMenus.lua).
+
+```lua
+{
+    label  = "Close slot",   -- example of a NEW action (RequestCloseSlot doesn't exist yet — add it)
+    when   = function(ctx) return ctx.isHost and ctx.isOpen end,
+    action = function(ctx) CustomLobbyController.RequestCloseSlot(ctx.slot) end,
+    -- enabled = function(ctx) ... end,  -- optional; omit for always-enabled. false = greyed, not hidden
+},
+```
+
+(Already wired, for reference: `Move to observers` → `RequestMoveToObserver`, `Eject` → `RequestEject`, ready toggles, `Take this slot` → `RequestTakeSlot`.)
+
+`ctx` (see `SlotContext`): `slot`, `player|false`, `isHost`, `isYou`, `isOpen`.
+
+## Do / Don't
+
+| | Rule |
+|---|------|
+| ✅ | Gate visibility with `when(ctx)` — that's how host vs player / open vs occupied menus differ. Use `enabled` only when you want the item shown-but-greyed. |
+| ✅ | Have `action(ctx)` call a **`CustomLobbyController` intent** (`RequestX`). Keep it one line. |
+| ✅ | If the action is a new operation, add the intent to [CustomLobbyController.lua](/lua/ui/lobby/customlobby/CustomLobbyController.lua) first: host applies + `BroadcastPlayers`; a client `SendData`s a request the host validates (add a typed message in [CustomLobbyMessages.lua](/lua/ui/lobby/customlobby/CustomLobbyMessages.lua) + a `ProcessX` handler). The host stays authoritative. |
+| 🚫 | Write to the model from `action` — read it, mutate via a controller intent. |
+| 🚫 | Touch [CustomLobbyContextMenu.lua](/lua/ui/lobby/customlobby/CustomLobbyContextMenu.lua) — it's a generic renderer and knows nothing about the lobby. |
+| 🚫 | Build the menu in the slot row — the row only calls `BuildSlotMenu(slot)`; definitions live in `CustomLobbyMenus`. |
+| 🚫 | Use the `%` operator (FAF is Lua 5.0 — use `math.mod`). |
+
+## A whole new menu surface (not just a slot item)
+
+The renderer [CustomLobbyContextMenu.lua](/lua/ui/lobby/customlobby/CustomLobbyContextMenu.lua) is generic — slots are just its first caller. To add another surface (lobby background, observer list, options…): add a new entry list + `BuildXMenu(...)` in `CustomLobbyMenus.lua` (its own `ctx` shape), then have that control's right-click call `CustomLobbyContextMenu.Show(CustomLobbyMenus.BuildXMenu(...), event.MouseX, event.MouseY)`. Don't edit the renderer.
+
+## Verify
+
+An empty result simply doesn't show. Right-click a slot in each relevant state (your own / another's / open; as host and as client) and confirm the item appears only `when` it should and its intent round-trips. UI-only check: `import("/lua/ui/lobby/customlobby/customlobbyinterface.lua").OpenDebug()`.

.claude/skills/customlobby-model-choice/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: customlobby-model-choice
+description: Decide which of the three CustomLobby models new state belongs in — Launch (shared + launched), Session (shared, lobby-room only), or Local (per-peer, never synced) — and keep hot-reload working. Use when adding a field/state to the custom lobby, or unsure where lobby state should live.
+---
+
+# Which CustomLobby model does this state go in?
+
+Three reactive singletons, chosen by two questions: **is it shared (host-dictated → broadcast to everyone)?** and **does it get launched (becomes part of the game)?**
+
+| Put it in… | Shared? | Launched? | Examples |
+|---|---|---|---|
+| **[CustomLobbyLaunchModel.lua](/lua/ui/lobby/customlobby/CustomLobbyLaunchModel.lua)** | ✅ | ✅ | players (per-slot), observers, scenario, game options, mods, auto-teams, spawn-mex. |
+| **[CustomLobbySessionModel.lua](/lua/ui/lobby/customlobby/CustomLobbySessionModel.lua)** | ✅ | ❌ | slot count, closed slots (later: lobby title, password, kick log). |
+| **[CustomLobbyLocalModel.lua](/lua/ui/lobby/customlobby/CustomLobbyLocalModel.lua)** | ❌ | — | identity (`LocalPeerId` / `HostID` / `IsHost`), CPU benchmarks (later: ping). |
+
+**Decide with two litmus questions:**
+1. *Does the launched game consume this?* → **Launch**. (A closed slot is just empty at launch and slot count is map-derived presentation — neither reaches the scenario, so they're **Session**, not Launch.)
+2. *Is it this client's own state?* → **Local**. Identity is per-peer (the host's `IsHost` is true, a client's is false); broadcasting it would corrupt the receiver — it never goes on the wire.
+
+Everything else host-dictated that isn't launched is **Session**.
+
+**Not all state is a model.** *Reference data* — identical on every peer and derived from disk
+or computed from synced inputs — belongs in **neither**. It's a cached module, not a LazyVar
+singleton on the wire. Examples: the **map catalog** ([CustomLobbyMapCatalog.lua](/lua/ui/lobby/customlobby/mapselect/CustomLobbyMapCatalog.lua),
+enumerated scenarios), and the upcoming **option schema** (derived from `ScenarioFile` + `GameMods`).
+Only the host's *choice* (the `ScenarioFile` / `GameMods` / `GameOptions` values in Launch) syncs;
+each peer recomputes the catalog/schema locally. Filter/search state in a picker is per-peer UI
+preference (component-local + Prefs), not a model either.
+
+## Sync mapping (host → clients)
+
+| Model | Message(s) | Broadcast by |
+|---|---|---|
+| Launch | `SetPlayers` (players + observers) and `SentLaunchInfo` (scenario / options / mods / teams / spawn) | `BroadcastPlayers` / `BroadcastLaunchInfo` |
+| Session | `SetSessionState` | `BroadcastSessionState` |
+| Local | — (never synced; set on the connection handshake) | — |
+
+The host pushes **whole snapshots** on join and on change. Adding a synced field means adding it to the relevant broadcast *and* its `Process*` handler in the controller.
+
+## Adding a field — also touch OnReload
+
+Each model hand-copies its LazyVars in `__moduleinfo.OnReload` so a hot-reload doesn't reset live state. When you add a field:
+
+1. add it to that model's `SetupSingleton` (a `Create(...)` with its default), and
+2. **add a matching copy line in that model's `OnReload`** — miss this and the field silently resets on every save-reload (exactly when you're iterating).
+
+## Gotchas — do / don't
+
+| | Rule |
+|---|------|
+| ✅ | Route every write through the owning model's helpers (`SetPlayer`, `SetGameOption`, `AddObserver`, `SetClosed`, `SetCpuBenchmark`, …) — they keep the copy-then-`Set` discipline. |
+| ✅ | Add the matching `OnReload` copy line whenever you add a field (see above). |
+| ✅ | Write the shared (Launch / Session) models **only from the controller**, after the host validates; clients send a request message. |
+| 🚫 | Put ping / CPU / connection churn in **Launch** or **Session** — its dirtying would ride along with a synced snapshot. It's **Local**. |
+| 🚫 | Put launch-affecting state in **Session** (it won't reach the game) or **Local** (it won't be shared). If the game needs it and all peers must agree → **Launch**. |
+| 🚫 | Broadcast anything from **Local** — identity/connectivity is per-peer; sending it corrupts the receiver. |
+| 🚫 | Mutate a LazyVar's held table in place — always `table.copy` → mutate → `:Set` (a new table), or dependents never go dirty. |
+| 🚫 | Write any model from a view/component — views read via `Derive` only; the controller is the sole writer. |
+| 🚫 | Use the `%` operator (FAF is Lua 5.0 — use `math.mod`). |

init_faf.lua

@@ -656,4 +656,7 @@ MountDirectory(SHGetFolderPath('LOCAL_APPDATA') .. 'Gas Powered Games/Supreme Co
 MountDirectory(fa_path .. "/movies", '/movies')
 MountDirectory(fa_path .. "/sounds", '/sounds')
 MountDirectory(fa_path .. "/maps", '/maps')
-MountDirectory(fa_path .. "/fonts", '/fonts')
+MountDirectory(fa_path .. "/fonts", '/fonts')
+
+-- support for custom backgrounds in the lobby
+MountDirectory(InitFileDir .. '/../gamedata/custom-lobby-backgrounds', '/textures/ui/common/lobby/custom-backgrounds')

init_fafbeta.lua

@@ -642,5 +642,8 @@ MountDirectory(fa_path .. "/sounds", '/sounds')
 MountDirectory(fa_path .. "/maps", '/maps')
 MountDirectory(fa_path .. "/fonts", '/fonts')
 
+-- support for custom backgrounds in the lobby
+MountDirectory(InitFileDir .. '/../gamedata/custom-lobby-backgrounds', '/textures/ui/common/lobby/custom-backgrounds')
+
 -- Allows developers to embed code to debug a replay
 table.insert(path, 1, { dir = InitFileDir .. '\\..\\Debug', mountpoint = '/' })

init_fafdevelop.lua

@@ -642,5 +642,8 @@ MountDirectory(fa_path .. "/sounds", '/sounds')
 MountDirectory(fa_path .. "/maps", '/maps')
 MountDirectory(fa_path .. "/fonts", '/fonts')
 
+-- support for custom backgrounds in the lobby
+MountDirectory(InitFileDir .. '/../gamedata/custom-lobby-backgrounds', '/textures/ui/common/lobby/custom-backgrounds')
+
 -- Allows developers to embed code to debug a replay
 table.insert(path, 1, { dir = InitFileDir .. '\\..\\Debug', mountpoint = '/' })

lua/lazyvar.lua

@@ -9,7 +9,7 @@ local setmetatable = setmetatable
 
 -- Set this true to get tracebacks in error messages. It slows down lazyvars a lot,
 -- so don't use except when debugging.
-local ExtendedErrorMessages = false
+local ExtendedErrorMessages = true
 local EvalContext = nil
 local WeakKeyMeta = { __mode = 'k' }
 

lua/ui/CLAUDE.md

@@ -184,6 +184,32 @@ end,
 
 `TrashBag` is a weak table for values, so an item already destroyed elsewhere drops out automatically — `Destroy()` should always be idempotent. See [trashbag.lua:30-50](../system/trashbag.lua#L1-L50) for the contract.
 
+### ⚠️ A `Trash:Add(Derive(...))` with no strong reference gets garbage-collected
+
+This is the load-bearing reason the canonical pattern assigns to `self.Observer` **and** passes through `Trash:Add` — the two references do different jobs:
+
+- `self.Observer = …` is the **strong** reference that keeps the derived LazyVar alive.
+- `self.Trash:Add(…)` registers it for **teardown**, nothing more.
+
+`Trash:Add` does **not** keep its contents alive: `TrashBag` is `__mode = 'v'` (weak *values*, [trashbag.lua:40](../system/trashbag.lua#L40)), and a LazyVar's `used_by` (the subscriber list a source walks on `:Set`) is `__mode = 'k'` (weak *keys*, [lazyvar.lua:306](../lazyvar.lua#L306)). So a derived observer reachable **only** through those two tables has no strong referrer and is eligible for collection.
+
+```lua
+-- ❌ BUG: nothing holds the derived LazyVar strongly. It fires once on creation,
+--    then a GC pass collects it and it silently stops reacting to source changes.
+self.Trash:Add(LazyVarDerive(model.IsHost, function(isHostLazy)
+    self:OnHostChanged(isHostLazy())
+end))
+
+-- ✅ CORRECT: the self field is the strong ref; Trash:Add still handles teardown.
+self.IsHostObserver = self.Trash:Add(LazyVarDerive(model.IsHost, function(isHostLazy)
+    self:OnHostChanged(isHostLazy())
+end))
+```
+
+The failure mode is nasty because it's **timing-dependent and silent**: the observer's first synchronous fire works (before any GC), so initial render looks correct; only a *later* `source:Set` — after a GC cycle — fails to propagate, with no error. (Real example: a tab's host-only gear that stayed hidden because its visibility observer was collected before `IsHost` flipped to `true` at hosting time. The source's own `OnDirty` still fired — the source was strongly held by its model singleton — but the orphaned derived observer was already gone.)
+
+If you build observers in a loop (per row / per tab) and have no natural `self.X` name for each, keep them in a strong list field — `self.Observers = self.Observers or {}; table.insert(self.Observers, self.Trash:Add(Derive(...)))` — so the list holds them and the `Trash` still tears them down.
+
 ---
 
 ## 4. Layout — Fluent Layouter
@@ -224,6 +250,46 @@ self.SomeLine.Top:Set(scaled(20))
 
 If you find yourself reaching for `ScaleNumber` a lot, that's usually a sign you should be using `Layouter` instead.
 
+### Standard asset sizes — look them up, don't guess
+
+A `Button` (and most textured controls) sizes to its art by default, so the texture's width *is* the
+control width unless you override it. Don't eyeball these. Most textures' native (unscaled) sizes are
+dumped in [`/textures/texture-dimensions.csv`](/textures/texture-dimensions.csv)
+(`RelativePath, Width, Height, Format`) — grep it for the resolved path. **The `/BUTTON/` tree is not
+in that CSV**; read those from the DDS header instead (`od -An -t u4 -j 12 -N 8 <file>` → `height width`).
+`SkinnableFile` resolves `/BUTTON/`, `/scx_menu/`, `/dialogs/` to the active **faction** skin (`common`
+is only the fallback, and loads differently); `CreateButtonStd`/`CreateButtonWithDropshadow` append
+`_btn_{up,…}.dds`. Verified standard buttons (unscaled W × H): `/BUTTON/large/` **296 × 80**,
+`/BUTTON/medium/` **132 × 44** (these two are the lobby's Launch/Leave buttons — **there is no
+`/BUTTON/small/`**, referencing it makes the button invisible), `/scx_menu/small-btn/small` **200 × 72**
+(the map/mod dialogs' button), `/dialogs/close_btn/close` and gear menu-btns **24 × 24**. Don't confuse
+`/BUTTON/<size>/` with the separate `widgets/<size>_btn` family in the CSV (392/276/152 wide). Pre-scale —
+multiply by the UI scale.
+
+### Scrollbars — reserve the gutter on the content, not the bar
+
+`UIUtil.CreateVertScrollbarFor(content, offset_right)` sets `bar.Left = content.Right + offset_right` (`AnchorToRight`). The convention here: **inset the content's right edge by the gutter and attach the bar at offset 0** — the bar then sits in that reserved strip.
+
+```lua
+Layouter(self.Content):AtLeftIn(self, 6):AtRightIn(self, 32):End()  -- 32px gutter on the right
+self.Scrollbar = UIUtil.CreateVertScrollbarFor(self.Content)        -- offset 0 → bar sits in it
+```
+
+The standard gutter is **32px** (`/lua/ui/lobby/customlobby` is aligned to this). For a fixed-width grid the same reservation goes into the width math (`width = panelW - leftInset - 32`); right-aligned cell content (a value dropdown) then clears the bar automatically.
+
+- **Don't double-reserve.** Use *either* a content inset *or* a negative `offset_right` (e.g. `-32` on a full-width control), never both — combined they push the bar over the content.
+- **Pooled/virtualised lists** that attach the bar to themselves (`CreateVertScrollbarFor(self)`, rows full-width) put the bar just *outside* the list's right edge instead — a deliberate different idiom; a negative `offset_right` is the only way to inset those.
+- **TextArea**: bind `Width` in `Initialize` (post-mount), not `__post_init` — see the TextArea gotcha in the lobby CLAUDE.md.
+
+**The wheel only scrolls over the bar by default.** The engine routes `WheelRotation` to the scrollbar itself, so spinning the wheel over the *content* does nothing unless the content forwards it. Use `UIUtil.ForwardWheelToScroll(content, scrollable)` (chains any existing `HandleEvent`) right after creating the bar:
+
+```lua
+self.Scrollbar = UIUtil.CreateVertScrollbarFor(self.Grid)
+UIUtil.ForwardWheelToScroll(self.Grid, self.Grid)   -- wheel over the rows now scrolls too
+```
+
+It forwards with the explicit `"Vert"` axis: a native `Grid` indexes its scroll state by axis (a `nil` axis errors in [grid.lua](../maui/grid.lua) `ScrollLines`); single-axis scrollables (`ItemList`/`TextArea`, custom lists) ignore the argument. Wheel events bubble from rows/cells to the parent `Grid`/`ItemList`, so attaching to the scrollable itself is enough — and a child that consumes the wheel (e.g. a `Combo` adjusting its value) still wins, which is what you want.
+
 ### Reusing layout files
 
 `LayoutHelpers.*RelativeTo` reads positions from a layout `.lua` table — used by older skinned screens. New code generally prefers fluent anchors against siblings; reach for layout files only when matching an existing skinned design.