> For the complete documentation index, see [llms.txt](https://docs.kouch.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kouch.dev/docs/home_library_plan.md). # Home + Library redesign, fit-to-screen, Steam social This is an addendum to [`PLAN_V2.md`](/docs/plan_v2.md), which it does not replace. Written by kouch central on 2026-09-27. * **Source of truth:** the owner's design canvas, . Two pages hold the final designs: * **"Home, final":** boards H1–H21 and the purple spec note; * **"Library, final":** boards LF1–LF21 and the blue spec note. * The "Concepts", "Library" and "Parts" pages are history. The parts files (`TopBar`, `DefaultColumn`, `FriendsWidget`, `GameRow2`, `SystemTile`, `LibTabs`) give exact geometry. * **Owner requests the same day:** * "do not stop until you redesign and have a consistent gui across"; * "needs to have smooth animations and be very smooth"; * "many options for widgets"; * "adjust other guis like the setup screen … automatically resize to fit in a whole screen according to the device"; * "working steam friends and chat". * **How the owner wants this done:** their monitors are off, so the owner doesn't review each step. Every piece is verified by us: CDP screenshots, fit metrics, the Deck perf tour, and the release build under Steam. ## Status | Part | Owner | Status | | ---------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | H0 Plan + contract | central | this file | | H1 Fit-to-screen stage | A | done on A's side: stage + wizard (0a9c942, 09e2798, cf43677), whole-pixel tokens/grids/labels/line heights (7038bcc, abf8bee, ee67822), fit scope instead of zoom, connect screen (1933f9b), panels and sheets scroll above the prompt bar (abf8bee, 0c5be2d). Measured: wizard bands 0.075–0.113; Players, Settings, menus, quick access, Home, Library 0 near misses and 0 sub-pixel boxes at 1280x800–3840x2160. The game page's fill and the Quick Menu went to C | | H2 Data contract v5 | B | done: §2.1 settings (8a506eb), §2.7 480 guard (64a1cd6), §2.2 schema v5 (daef7b4) + sessions (6763406), device\_power (a725063), automatic scans (6eccd77), Quick Menu pause (bb8c166), §2.3 presence (3271544), §2.4 playtime\_summary + hide/finish + disk sizes (c41b944), collections + tags (c8c49b8), emulators\_list update + playtime (0e7c817), captures\_latest (bee9b35), §2.8 mock art + online week (a2cb715), .kod collections (e64e415), Your image picker (0c6e68e), §2.5 tags from gamelist + metadat and SteamGridDB icons (3885f0d), view/sort dropped + has\_saves/sort\_key on Game (39b1693); for H6: light list + ?mock=big\&n= (3bdf965), 10k games \~29–41 ms / 5.3 MB | | H3 Home | A | done: arithmetic layout, WidgetGrid, one FocusRing per region, last-played card in three styles (large, with save, compact banner + row2), 8 row types (HomeRow, placeholders for short rows), strip in all six kinds, the 260 ms fold, first run / unplugged / missing (c72023c, b69d15a, 4273fb3, 14be95a, c8a5aa0); perf phases home\_fold 88.7 / home\_widgets 89.7 fps on the Deck (4babd00) | | H4 Edit Home + widget catalogue | A (+C for social widgets) | done: widget API (ba0e9a1), Edit Home (move/swap, size, remove, card/row/strip sheets; 14be95a), widget settings sheet incl. image pick and the H10 catalogue (0c5be2d); all 26 widgets: C's 19 (573c486, c74c029, 88b86cc, 01f55ee) + A's 7 stats/library (1ddf348) | | H5 Steam friends, lobby peek, chat | C | built: backend + contract (884bfe2, verified read-only live: 135 friends, avatars, shortcut id), friend + chat sheets and quick access (b8586a2, c6d2bf3), social widgets on the widget API (573c486; WidgetGrid wiring is A's). Open live checks: chat send, invites, a peeked lobby + Join (needs a second account) | | H6 Library views | A | done: section shell with LB/RB and a breadcrumb, Systems tiles with LF12 states, Grid A–Z (virtual, pooled, steered from azLayout; 10k games keep \~35 covers mounted), All games, order and filter per system incl. Has saves, unplugged banner + details, Shelf, Playtime view, View picker, Classic/Carousel/List retired (b58a89d, a50f279, c7a3f0c, 4260101, 8d2a802, 13b10ef); perf phases library\_systems / library\_az / library\_shelf / library\_playtime | | H7 Tags, metadata, collections | B (data) + A (UI) | done: tags, libretro metadata and SteamGridDB icons, collections with `.kod` sharing (B, contract v5); C's Collections section (from tags, Emulators last); the tags sheet; the card menu's Tags… / Add to collection… / finished / hide (A, d66c44a); the game page's Details lists tags (0d00eb9) | | H8 Playtime section | C (UI, moved from A) + B (data) | done by C on A's section slot (faff177, a5067d4); A's per-system Playtime view reuses C's PlaytimeRow | | H9 Verification + Deck perf | central | **Release candidate 6e58762 accepted 2026-09-27** (installed release build under Steam: boot, Home with the empty card's ring, Library, quick access, the report with neutral controller classes, exit code 0 with no Steam socket left open; db9921e before it found those three); the full-app UI sweep is all green, 0 of 938 cells failing (C, `docs/UI_SWEEP.md`); the Deck gate passes in Game Mode (below). Continuous. `scripts/ui-shoot.mjs` `fit:` + `align:`; v5 migration run on a copy of the owner's real library.db (half-migrated v1, 8 games, preserved); Deck Game Mode round at c6d2bf3: library 85.4 / Home 87.3 / connect 85.2 / sheet 87.2 / ambient 89.8 fps (no regression from the stage), Quick Menu pause T while open, S after Deck round with the new Home (4babd00+): home\_fold 88.7 fps (p95 12 ms, pass; a fold step 7 ms press to screen), home\_widgets 89.7, connect 86.1, sheet 86.9, ambient 90; the old library 84.4 until H6 replaces it. Deck round with the Library (a8595f2, Deck library + 2,000 games): library\_systems 86.8/86.6, library\_shelf 87.4/87.6, library\_playtime 88.7/87.9, home\_fold 88.8/88.7, home\_widgets 89.7/88.4 pass; **library\_az 83.7/83.3 (steps 30 ms, focus up to 91 ms on letter jumps) and sheet 82.4/82.0 (was \~87) fail, sent to A**; pause reaches the stand-in's wrapper too (T/Ts+). **Startup (B, bc93265), Windows release, 5 boots, medians before → after the split:** boot JS 827 → 610 kB (Settings 112 kB, Edit Home 22, Setup 15 load on demand; the mock no longer ships); webview navigation start → DOMContentLoaded 478 → 344 ms; bundle execution 183 → 123 ms; launch → Home interactive 3,709 → 3,306 ms; first nav 21 → 15 ms. Launch → navigation start (Rust + WebView2) 450–900 ms; DOMContentLoaded → Home interactive 2.53 s is Boot's fixed 2.5 s hold (sent to A; 8ccafea now advances when Home's data is in, 700 ms minimum, and the mock shell is up by 1.3 s). **With 8ccafea (B, Windows release, 5 boots):** launch → Home interactive median **3,306 → 1,562 ms**. **Where the time before the first frame goes (2885e64, grep a log for `startup`):** plugins ready \~30 ms; main page load starts 540–680 ms (WebView2 environment + webview creation inside Tauri's build); `setup()` only 21–31 ms (library open 10–16, the Quick Menu's click-through 6–10); first paint 650–830 ms; Home interactive 1,455–1,641 ms. Not creating the Quick Menu's webview at start gains nothing on Windows (built asynchronously); the Deck's WebKitGTK may differ. **Deck round at 855946a (the split + A's 86d5c6f):** first paint unchanged, 1,725 ms on the first launch after a deploy (GStreamer registry warm-up), then 1,090 / 1,072 ms (was 1,732 / 1,077 / 1,078): the boot bundle is not the Deck's bottleneck. library\_az 82.8/82.6 and sheet 81.9/81.9 still fail (letter jumps: focus 70–94 ms, to\_frame \~200 ms; the order sheet drops \~13 frames per open + close); connect 84.7/85.4 and library\_systems 86.0/85.2 borderline; shelf, playtime, home\_fold, home\_widgets and ambient pass. Being profiled with a source-mapped build. **Deck WebKit profile + fixes (2026-09-27 afternoon):** opening a system sorted 2,000 titles twice with `localeCompare(…, options)` (a collator per call in JavaScriptCore) and lettered them with a whole-title NFD per title; A's fb500d0 (one `Intl.Collator`, a value-keyed list memo, letters from `sort_key`) and 48838b6 (every whole-pixel helper on one batched frame job, no mount-time `measure()`), 98ad7ce (prompt bars stay built) took the sheet from 81.9 to 88.2–88.8. **The Deck tour had measured the wrong screens:** the test settings remembered `library.section: "all"` and `views.standin: "playtime"`, and all 2,000 test titles began "Sample game" (one letter, so no letter jumps). Fixed: the Deck's stand-in files now have 29 first letters, and the tour starts on the Systems tiles and restores what it changed (48838b6, e6482c8). **Real Grid A–Z (6891a73): 84.8 / 83.2**; up/down steps 12–17 ms to frame (two frames at 90 Hz), letter jumps 33–70 ms (JS \~10 ms, the rest paints the new covers); with A. connect 85.6–85.8 (C). **Startup:** creating the Quick Menu's webview after first paint (B, 6891a73) saves nothing on the Deck or Windows but is kept (the early open after a `--launch` start works in Game Mode). The AppImage's squashfs costs \~470 ms of first paint per warm launch: extracted, first paint is 1,109–1,136 ms vs 1,583–1,586 (2,163 cold), and exec → Quick Menu ready 1,585 vs 2,306–3,028 ms. So the Linux Steam depot ships the extracted tree (B), and AppRun must set `APPDIR` itself outside the mount. **The extracted tree in Game Mode (B's 19e3cbb dev build, `--appimage-extract`, the shortcut on its AppRun):** first paint 1,144–1,168 ms since launch warm (1,669 on the first launch after deploy); sound works (`phase=audio … keep_alive=1 web_audio=1`); no GStreamer plugin copy in `~/.cache/kouch`; the Quick Menu is pinned over a game and pauses it, including an early open after `--launch`. Same round: library\_systems 89.7 / 89.8 (the tour no longer walks the tabs), connect 84.2 / 86.3 with C's fitDown fix (a79a07e), sheet 86.1 / 85.9, shelf 86.2 / 86.7, playtime 87.4 / 87.5, Home 88.6–89.8, ambient 89.9. Grid A–Z was 83.7 / 83.7; a CSS A/B at 90 Hz showed hiding the A–Z focus ring gives 86.5 fps (hitches 67–79 → 38), while compositing hints, instant scroll, no cover images and no plates each moved it by < 1 fps. **With A's 39c2f7f (the ring snaps when a step scrolls), Game Mode, extracted tree: library\_az 86.3 / 86.1 (hitches 35–36), library\_systems 89.8 / 89.8, shelf 86.4 / 86.8, playtime 87.2 / 87.3, home\_fold 88.5 / 88.0, home\_widgets 89.8 / 88.7, ambient 89.9 / 89.8, sheet 86.8 / 86.3: every phase over 85.5 fps in both tours except connect 86.2 / 84.5 (C, alpha-acceptable).** **Windows, the release build under Steam with its perf tour (`rcperf`, 2,000 stand-in games, 2560×1440 on a 480 Hz monitor, 6e58762):** every phase holds the display rate, 478–480 fps, p50 2.1 ms, p95 2.2 ms; up/down steps 1.3–3.3 ms to frame, letter jumps 5.3–6.6 ms; first paint 596 ms after launch. Connect, A/Bs on the Deck (C's switches): FLIP off 87.2, the silhouette on its own layer (shipped, 2d80b84) \~+1.5, and no change from deferring the FLIP a frame, translate-only, box layers or any easing. The rest is up to 8 concurrent box animations on WebKitGTK; 84–86 is accepted for the alpha. **Connect pop (owner 2026-09-28, C):** seat changes now pop out and back in instead of sliding (DESIGN.md §10e); Game Mode vs the slide, two rounds each: connect 85.1 / 84.0 vs 85.4 / 86.1, every other phase unchanged (az 86.1–86.7, shelf 85.8–86.4, playtime \~87.5, home\_fold \~88.4, sheet 86.3–88.2); per-box animation delays cost \~10 fps on WebKitGTK, so the stagger lives inside each box's keyframes (`DECK_UI_PLAN`). p95 15–17 ms two-frame spikes stay accepted for the alpha; the View-switch max frame (\~100 ms, the new view mounting during the sheet's slide-out) is A's post-RC item. | Update this table as parts land. *** ## 0. Rules for every part * **Design system.** * The DESIGN.md rules still hold: tokens only, no gradients, no shadows, no `:hover`. * Motion is transform and opacity only, with FLIP for re-layout. Reduced motion becomes a ≤100 ms crossfade or nothing. * **There is one gliding focus ring per focus region** (§4.1). Cards change state instantly. * DESIGN.md §4, §4b and §5 are rewritten for the new Home and Library as the parts land. * **One prompt bar.** It sits bottom-right in the canonical order (`lib/promptOrder.ts`, 4fb24e6). * **The A label is contextual:** Open / Resume / Play / Rescan / Details / Look again / Choose / Add. The boards list the label for each state. * **LB/RB, View, X and Y are overloaded by context, exactly as drawn.** In a system's Grid A–Z, LB/RB jump a letter; in the Playtime section, View changes the time range. The prompt bar always names the current meaning. * **Deck frame budget.** At 90 Hz the bar is ≥ 85.5 fps (95 %), with p95 two-frame spikes accepted as today. * Every new motion adds a perf-tour phase (§9). * At most one layer per animated block. `will-change` only while moving. Layout is never measured during an animation. Pooled or windowed DOM is used for anything that can exceed \~60 items. * **Brand-free.** Placeholder names in tests and mocks: "Sample game NN", "System A", "Emulator One". Steam is Kouch's own platform and may be named. * **Ground rule 2.** Metadata, tags, art and collections refer to games by hash or stable id. Nothing ever moves a game file. Shared collections list games; they never carry them. * **Test selectors.** The redesign replaces `.k-home*`, `.k-shelf*` and the classic/carousel/list Library views. Their tests move with them; don't delete coverage. *** ## 1. Fit-to-screen stage (H1, A) — every screen, first **The problem.** Today's screens are laid out in fixed px. At 3840×2160 the setup wizard leaves about a third of the screen empty below the drive cards, and its text sits in a narrow column (`scratchpad fit/` shots, 2026-09-27). Ultrawide leaves bands on the side. **The rule.** Every screen fills the display it's on, at any size, and re-fits live on resize. Nothing scrolls unless the content is genuinely longer than the screen (a long list), and then only that list scrolls. **Mechanism (`lib/stage.ts` + `theme/tokens.css`):** 1. **The reference is the canvas: 1440×900.** A single `--k-scale` is written on `` by a ResizeObserver on the window, at most once per frame. It is not written during an animation. * `--k-scale` = clamp(0.75, min(innerWidth/1440, innerHeight/900), 3). * `settings.display.text_scale` multiplies the type tokens only, on top of `--k-scale`. 2. **Densities.** * `data-density="compact"` when the window is ≤ 1366 wide or ≤ 820 tall (the Deck, small windows). It uses the handheld metrics from the boards: outer gutter 56 instead of 72, column gap 24 instead of 32, Home left column 360 instead of 432 (H15, LF13). * `regular` otherwise. `large` from 2560 wide at 16:9, which only changes line lengths. 3. **Tokens.** Every spacing, radius and type token becomes `calc( * var(--k-scale))`. * Components use tokens, never raw px (design-lint already enforces tokens; extend it to reject raw `px` in component CSS except 1px hairlines). 4. **Extra width becomes content, not bigger UI.** For 21:9 and 32:9 (owner direction 2026-09-26: "ultrawide = more columns"): * `--k-scale` follows the height. * Library grids gain columns. * Home's right column widens and shows more row cards. * The setup wizard's drive grid gains columns. 5. **Vertical fill.** Each screen is a CSS grid: `header / content 1fr / footer`. The content area centres its block vertically when it's shorter, and card grids size their rows to fill the height (the `gridFit` idea from LibraryGrid, generalised into `lib/fit.ts`). **Screens to convert.** Every row below is its own commit, each with screenshots. | Screen | What fitting means for it | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Boot | logo and progress centred, scaled | | Top bar | 112 px at 1440×900, scaled; battery added (§3.1) | | Home, Library | the new layouts (H3, H6) are built on the stage from the start | | Setup wizard (5 steps) | drive cards grow and gain columns to fill the width; content block centred vertically; Look/Emulators/Ready steps scale; step dots and bottom buttons scaled | | Players / connect | the hero/1×4/2×4 boxes scale to fill the height (box size from height, not a fixed px) | | Settings (every category) | the two-pane layout fills the height; lists scroll inside their pane only | | Game page | hero, tabs and body scale; body pane fills the height | | Downloads | the list fills; rows scale | | Sheets and side panels | width a share of the screen (e.g. 600/1440), full height | | On-screen keyboard | key size from the stage | | Quick Menu (overlay window) | the panel stays the same share of the screen as today; content scales | | Toasts, first-run tips, profile import, Steam profile sheet | scaled | **Verification, a new check by central (`fitcheck.mjs`).** For each screen, at 1280×800, 1366×768, 1920×1080, 2560×1080, 3440×1440, 3840×2160 and at 150 % text: * the page has no horizontal or vertical scroll; * no element's content overflows its box, and no text is clipped; * the main content block covers ≥ 70 % of the viewport height (or is a list that fills its pane); * it passes in both Black and White. Numbers are written to a JSON file per run, and the screenshots are read back. *** ## 2. Data contract v5 (H2, B) — starts now, in parallel with H1 Every change below goes through B: `payloads.rs` ↔ `types.ts`, plus the mock in `transport.ts` with realistic sample data (§2.8). Contract changes ship with mock support in the same commit, so A can build against the mock straight away. ### 2.1 Settings `settings_set` spells out every top-level key as its own parameter, and unknown keys are dropped silently. **Add `home` there.** ``` home: { widgets: [ { id, type, x, y, w, h, config } ], // 2 × 4 grid, (x, y) in cells, w/h in cells card_style: "large" | "save" | "banner", // H9, default "large" row: { type, system_id?, collection_id?, count: 5 | 8 | 12, skip_last: bool, hide_finished: bool }, row2: null | { …same… }, // the extra row "banner" style frees (H9) strip: { type: "week" | "couch" | "friends" | "downloads" | "row" | "none", stats: [3 of: hours_week, streak, online_nights, games_played, total_hours, captures, top_system, couch_coop], range: "week" | "month" | "off" }, } row.type: "recent" | "friends_online" | "couch" | "favorites" | "most_played" | "not_played" | "system" | "collection" ``` * **Defaults (H1):** * Friends online L at (0,0), 2×2. * Controllers S at (0,2) and Storage S at (1,2). * Downloads M at (0,3), 2×1. * `card_style: large`. * `row: friends_online, count 8, skip_last true, hide_finished false`. * `strip: week` with stats `hours_week, streak, online_nights` and range `week`. * **Validation:** widgets can't overlap and must stay in the grid; unknown widget types are dropped with a log. `library` gains: ``` library: { …existing…, section: "systems" | "collections" | "playtime" | "all", // where Library opens: systems views: { "": "az" | "shelf" | "playtime" }, // default az orders: { "|all": { order: "az" | "last_played" | "most_played" | "added", filters: [ "favorites" | "not_played" | "friends_online" | "players2" | "has_saves" ], show_hidden: bool } }, az_everywhere: bool, // LF5 "Use Grid A–Z for every system" hide_offline: bool // LF16 X "Hide them" } ``` **Migration.** `library.view` `grid|classic|list|carousel` → drop the field, and every system opens in `az`. `library.sort` → `orders.all.order`, with `title → az`, `recent → last_played` and `most_played → most_played`. The theme extra `library_view` is ignored from now on. ### 2.2 Library schema v5 (`crates/kouch-library`, one transactional migration like v1→v2) * **`roms`** gains: * `added_at` — unix seconds, set when a row is first inserted. The migration sets existing rows to the migration time, so they all count as "not new". * `hidden` (the game page's "Hide", LF6 "Show hidden games"). * `finished` (feeds the automatic "Finished" collection). * `icon_path` (square icon, §2.5). * `playtime_s` (a cached total, updated when a session ends). * **`sessions`:** `id, rom_id, stable_id, profile_id, system_id, started_at, ended_at, seconds, kind (local | netplay | remote_play), lobby_id, peers JSON [{steam_id, name}], seats` (the local players seated). * One row per play session, written when the session ends (natural exit or quit) from `SessionState.started_at`. Sessions under 20 s are dropped. * `mark_played` moves from "spawned" to "window found". * This is the only playtime source. Every playtime number, week chart, streak and "played with friends online" item comes from it. * **`tags`:** `(stable_id, tag, source: info | user, hidden)`. * Keyed by `stable_id`, so tags survive a rescan or a moved folder. * Namespaced values: `genre:racing`, `players:2-4`, `year:1998`, `mode:split-screen`, `style:arcade`, and `user:`. * Info tags can be hidden, not deleted (LF20). * **`collections`:** `id, name, kind (manual | rules | shared | finished), rules JSON, owner_steam_id, owner_name, source (null | kod | workshop), updated_at, position`. * `collection_items(collection_id, stable_id, title, system_id, added_at)`. Title and system are copied in, so a shared collection can list games you don't have (LF8). * **`scan_roots`** gains `volume_id` (Windows volume serial, Linux fs UUID) and `volume_label`. * **Offline is distinct from missing.** * A game is *offline* when its root's volume isn't present: it is greyed, keeps its place, and shows "SD card" (LF16). * A game is *missing* when its drive is present but the file is gone. * `Game` gains `offline: bool` and `volume_label: string | null`. ### 2.3 Presence without a rescan * A light `library_presence` check runs at startup, every 10 s while the window is visible, and on the Windows `WM_DEVICECHANGE` / Linux udev hint if cheap. It looks only at each root's volume, never walks it. * **When a volume comes or goes:** update `offline` for its rows, emit `library:presence { roots: [{path, present, label}] }`, and when a volume comes back, run a scan of that root only. This fixes the gap where an unplugged drive looked normal until someone pressed Rescan. ### 2.4 Commands and events (names final; payloads in `types.ts`) **Library and play:** * `library_list`: `Game` adds `added_at, playtime_s, icon, tags: string[], hidden, finished, offline, volume_label`. * `playtime_summary { range: week|month|all, system_id?, profile_id? }` returns: * `{ total_s, week_s, games: [{id, seconds, last_played, friends: [{steam_id, name, seconds}]}], by_system, by_emulator, days: [7 × seconds], streak_days, online_nights, couch_sessions }`. * `game_set_hidden`, `game_set_finished`. * `tags_get { game_id }`, `tags_add`, `tags_remove`, `tags_hide`, `tags_vocabulary` (for the rule editor's pickers). **Collections:** * `collections_list` returns `[{id, name, kind, count, owned_count, owner_name, rules, updated_at, preview: [3 game ids]}]`. Emulators is not a DB collection; the UI appends it last (LF18). * `collection_items { id }`, `collections_create`, `collections_update`, `collections_delete`. * `collection_add { id, game_id }`, `collection_remove`. * `collections_copy { id }` (a shared collection becomes yours). * `collections_match { rules }` returns `{count, systems, preview}` for LF21's live count. * `collections_export { id }` returns a `.kod` of kind `collection`. * Import is through the existing `.kod` path: `kind` is derived from contents; a new `collections/` folder in the zip. **Devices and captures:** * `emulators_list`: each profile adds `update: { latest, available, checked_at } | null` and `playtime_s`. The 6-hour updater task stores its result instead of only toasting. * `device_power` returns `{ battery_percent, charging, time_left_s } | null` (host battery: Windows `GetSystemPowerStatus`, Linux `/sys/class/power_supply`; null on a desktop), plus a `device:power` event on change. It is used by the top bar and the Handheld battery widget. * `captures_latest { limit }` returns `[{path, game_id, taken_at}]`. * It indexes each profile's `screenshots` folder on session end and at startup. * Serve them through `kmedia`: add the resolved cloud/screenshots folders to the served scope, but never `system`/`bios`. * `library:progress` stays. New events: `library:presence`, `playtime:changed` (after a session is written), `collections:changed`. ### 2.5 Metadata and tags: where they come from (B) 1. **`gamelist.xml`** (existing import; ES-DE/EmuDeck trees have them) gives genre, players, release date, developer and publisher. 2. **The libretro database** (no key, matched by CRC32 or serial, name as fallback): `metadat` data per system gives genre, max users and release year. That is enough for `genre:*`, `players:*` and `year:*`. * The per-system dat name comes from the profile's `systems[].art.thumbnails` name, the same mapping the thumbnail index already uses. **Kouch code names no platform.** 3. **Optional, with the user's key,** like SteamGridDB: a metadata provider that adds modes and style (`mode:split-screen`, `style:arcade`). This is later and not needed for the alpha. 4. **SteamGridDB icons** (`/icons/game/{id}`): they fill `icon_path` for the square icons that every list uses (LF4, LF9, the Playtime rows, Emulators). Fetched with the rest of the art, same key, same create-only cache. * **Tagging runs with the art job:** `art_refresh` fills tags and icons alongside the art. Rows show tags as they arrive (`library:art` progress). * **Hashing:** CRC32 is computed during the art job, only for files under 512 MB. Bigger games match by name. ### 2.6 Played with friends online, and friend dots * **Played with friends online** (row type, default Home row) = games with a `sessions` row of kind `netplay` that has peers, newest first. Never couch co-op (local seats), and never Remote Play guests (those are `remote_play`). * **Friend dots on playtime bars:** * When Kouch peers share a netplay lobby, each sets lobby member data `hours=`. * The session row stores each peer's hours at that time. * The dot for a friend is placed at their last known hours on the same bar scale, as "where a friend is, in their hours". Friends you never played with online have no dot. * This works under 480 lobbies and needs nothing from Valve. ### 2.7 The 480 guard (urgent, sent to B separately) A shortcut-launched release build runs Steam as 480. Workshop, Cloud, Remote Play Together and rich presence must be off under 480 and the borrowed id. Lobbies stay on. ### 2.8 Mock data (the redesign is built against it) The mock gains: * `added_at`, `playtime_s` and sessions (a plausible week, with 3 friends online and 2 couch sessions); * tags on every game, 5 collections (1 shared, 2 from tag rules, Finished, 1 manual); * 2 volumes, one offline under `?mock=offline-sd`; * emulators with one update available and one needing system files; * `device_power` (76 %, 2 h 10); * 3 captures; * friends in every state (§5), a joinable lobby, an incoming invite and chat messages. **Art for the mock: the redesign must be judged with real-looking covers.** * Generate neutral procedural covers, heroes, logos and square icons (shapes and colour fields, no text art) as static files under `app/ui/public/mock-art/` via a script. * The mock serves them for every game. Tests keep using nulls where they need Covers. *** ## 3. Home (H3, A) ### 3.1 Layout (H1, H15) **Top bar** (unchanged, plus a battery): 112 px at 1440×900. * It shows seated player dots, **battery `76%` from `device_power`** (hidden on a desktop without one), avatar and name, clock, and quick access. * The title follows the screen ("Home", "Edit Home" …). **Two columns:** left 432, gap 32, right 832. Handheld: 360 / 24 / 784, with a 56 px gutter. * **Left column:** a 2 × 4 widget grid, gap 16, row height `(h−48)/4`. * **Right column:** * The **last-played card** (832×300, radius 24): eyebrow `LAST PLAYED`, title 48/800, meta 17. * A **game row** (eyebrow + sub-label + hint; the first card 320×200, the others 140×200, gap 14). * The **bottom strip** (832×116, radius 20). * On ultrawide the right column widens and shows more row cards (§1.4). * **Home opens with focus on the last-played card** (H17). ### 3.2 Last-played card, three styles (H9) | Style | What it shows | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Large art (default) | hero art, eyebrow, title, meta "System A · Emulator One · 42 min today" | | With save + time | the above, plus a "Slot 2 · 18:01" badge top-right, "42 min today · 31 h in total", and a progress bar with the caption "58% by your own marker · resumes from the 18:01 save" | | Compact banner | 76 px card: icon, title, "10 min ago". The freed height makes the row taller (150×150) and adds a second row (`home.row2`, default Favorites) | * The card can't be removed. * Its A label is **Resume**; the card focused at first run is **Add an emulator**; an offline game's card says **Look again** (H14, H21). * "With save" is shown only when the profile can tell the last save slot and time. Otherwise that style falls back to the time lines, without the badge. ### 3.3 The row (H8) * **8 types:** Recent games · All; Played with friends online (default); On the couch (games for the players seated now: the `players:*` tag ≥ seats); Favorites; Most played; Not played yet; a system; a collection. * **Settings:** cards 5 / 8 / 12, skip the last-played game (on), hide finished (off). * Its A label is Play, or "Play online" on the friends row (H5). X is Favorite, or "Invite them" on the friends row. ### 3.4 The bottom strip (H18, H19) * **Your week** (default): a 7-bar mini chart plus 3 stats picked from 8 (§2.1); range week / month / off. It never shows the user's name or avatar. * **Players on the couch:** seat cards (controller class, battery, "Press A on a controller to join"). * **Friends online:** a one-line face strip. * **Downloads:** the active item, then "then …". * **A second game row.** * **Nothing:** its 116 px go to the row above. ### 3.5 Right from the big card: fold and widen, 260 ms (H4, H12, H20) **What happens:** the next recent game becomes the big card, both rows widen into the room the widgets give up, and the widgets fold into a rail of glances (88 px wide, one 64 px glance per widget). Left past the first card, or B, reverses it. Every card is the same size except the focused one. **The top row is an accordion (owner 2026-09-28, replacing the fixed big slot; board "ExpandedRight"):** the recent games stay in order, earlier ones on the left. Right/Left move focus one card: the new card widens where it stands and the old one narrows, and the focus ring travels with it. The row scrolls only as far as it must to keep the wide card whole with a neighbour peeking on each side, and never past either end (`home/layout.ts` `topRowScroll`, which keeps the previous scroll). Narrow cards carry their day label ("Last played" for the first) and, when last played online with friends, the first friend's dot at top right. **Choreography (H20):** * **0–140 ms:** widgets fade out and move 24 px left. * **100–260 ms:** glances fade in from −12 px, staggered 20 ms from top to bottom. * **The whole 260 ms:** the top row FLIPs. * The old big card shrinks to normal and the next one grows into the big slot. * The rows below slide to their new left edge. Existing cards keep their size; new cards slide in from the right. * The focus ring glides on the same curve (ease-out). * **Reduced motion:** a single 100 ms crossfade. **Implementation (A):** * Both layouts are computed arithmetically from the stage size (no DOM measuring) and cached per size. * Each block is one absolutely positioned layer moved by `transform`. * A card's size change is a FLIP scale of its art layer only; its title and meta are a separate layer that crossfades at the end, so text never scales. * WAAPI animations with `composite: "replace"`, no `transform-origin` in keyframes (it forces main-thread animation on WebKitGTK; see memory `webkitgtk-perf-lessons`). * At most \~14 animated elements. * A new perf-tour phase `home_fold` (§9) must hold the bar on the Deck. ### 3.6 Widgets: framework and catalogue (H3 + H4, A; social widgets C) **Framework (`app/ui/src/home/`):** * `widgets/registry.ts`: one entry per widget type: * `type`, `name`, `group` (social | play | stats); * `sizes: ("S" | "M" | "T" | "L" | "C2x3" | "C2x4")[]`, `defaultSize`; * `config` schema (e.g. which system, which collection, which image); * `component` (full view), `glance` (rail view), `focus: "single" | "list"`, `prompts(state)`. * `WidgetGrid.svelte`: a CSS grid 2 × 4 with `grid-area` per widget. It registers one focus group whose items are the widgets (list widgets like Friends host an inner column group; Up/Down walks rows first, then the next widget — H17). * `WidgetFrame.svelte`: radius, padding, eyebrow, the edit chrome (§3.7). **Catalogue: 26 widgets.** The owner asked for "many options". The boards' 16 are marked •, and ten more are added in the same style. | Group | Widget | Sizes | Data | | ----------------- | ------------------------------------------------------- | ---------------------- | ------------------------------------------------------ | | Social | • Friends online | L 2×2, 2×3, column 2×4 | §5 friends feed, lobby peek, invites | | Social | • Lobby (yours, or friends' open lobbies) | M, L | netplay state, lobby peek | | Social | • Chat | M, T, L | §5.3 chat | | Social | • Activity (friends' Kouch activity, sessions together) | M, T | sessions, lobby peek | | Social | Invites (pending, with countdown) | S, M | invite events | | Social | Nearby PCs (LAN peers) | S, M | `lan:peers` | | Play | • Controllers | S, M | players | | Play | • Handheld battery | S | `device_power` (hidden from the catalogue on desktops) | | Play | • Latest screenshot | S, M | `captures_latest` | | Play | Captures (a grid of recent ones) | M, L | `captures_latest` | | Play | • Your image | S, M, T, L | a user-picked image (copied into `/home/`) | | Play | Quick resume (last game, its save) | S, M | last session | | Play | Surprise me (a random pick with a filter) | S, M | library | | Play | On the couch (seats + join) | M, L | players | | Play | • Downloads | S, M | downloads store | | Play | Emulator updates | S, M | `emulators_list.update` | | Play | Music (Kouch's background music: play/pause, volume) | S, M | sounds/music | | Play | Quick settings (Black/White, sounds, fullscreen) | S, M | settings | | Stats and library | • This week (chart) | M, L | `playtime_summary` | | Stats and library | • Play streak | S, M | `playtime_summary` | | Stats and library | • A system | S, M | system + collage + state (LF12) | | Stats and library | • A collection | S, M, T | collections | | Stats and library | Recently added | M, T | `added_at` | | Stats and library | Most played | M, T | `playtime_summary` | | Stats and library | • Storage | S, M | storage state + presence ("SD card (E:) is out", H21) | | Stats and library | • Clock | S, M | — | * **Every widget has a glance** (H4, H12). Examples: * Friends: avatar dots with presence colours, a join badge, "N online". * Controllers: dots plus the lowest battery. * Storage: free space. * Downloads: % plus a small bar plus "N queued". * Battery: "76% · 2 h 10". * Chat: "3 new". * **Every widget has an empty or error state.** Friends has four (§5.2). ### 3.7 Edit Home (H7, H10) * Y from anywhere on Home opens Edit Home. The title becomes "Edit Home", with the instruction line "A picks a block up and puts it down · Y changes its size or type · X removes it · B saves". * Blocks show dashed borders, a kind chip ("M · Downloads" + Y) and an ×. * **Moving:** A picks a block up. The d-pad moves it cell by cell and neighbours reflow with a FLIP (180 ms). A puts it down. * **Y cycles** size (only sizes that fit) or opens a type/style sheet for the card, the row and the strip (H8, H9, H18). * **X removes a widget** and leaves a dashed "Free: 2 × 1" slot. The card can't be removed. * **"+ Add a widget"** opens the catalogue sheet (H10): grouped, a preview per widget, size chips, and "On Home" tags. * B saves (`settings.home`), and Home animates back. ### 3.8 States * **First run (H14):** "WELCOME TO KOUCH / Your last game will live here" with the "Add an emulator" CTA, which goes straight to import (8b8b1af). The row shows dashed placeholders with its explanation, and the strip shows zeroes. * **Unplugged (H21):** the big card is greyed with the pill "On the SD card (E:) · not connected" and "Plug the card back in and it's ready. Right still walks your other recent games." The A label is Look again. The Storage widget names the card. * **Steam offline:** the Friends, Lobby, Chat and Activity widgets show "Friends need Steam online / Everything else works offline…" with A to try again (H13). ### 3.9 Focus map (H17) * The card is the start. * Up goes to the top bar. Left goes to the widget column (Friends first); Right from anywhere in the column comes back to the card. * Right from the card folds (§3.5). Down goes to the row, then the strip. * Y is Edit Home. B does nothing at Home (root). Start opens the main menu; View opens quick access. *** ## 4. Library (H6, A; data from H2/H7) ### 4.1 Sections (LibTabs) * A 52 px bar: `LB [Systems][Collections][Playtime][All games] RB` plus a subtitle. It opens on Systems. * Inside a system, the bar is replaced by a breadcrumb ("Systems › System A" + meta), not shown alongside it. ### 4.2 Systems (LF1, LF12) * Tiles 3 across: 416×300 at 1440 (376×266 compact), gap 24 (20), radius 24. * A collage: one big and two small covers (grid `2fr 1fr / 1fr 1fr`). * The name, the emulator, a count, and one status line. * **States:** | State | Badge | Line | A | | ----------- | ------------------- | -------------------------------------- | -------- | | offline | Drive not connected | Plug in Games (D:), then A to rescan | Rescan | | scanning | Scanning… | Found 12 so far in roms/systemc | — | | empty | No games yet | Put games in roms/systemd, then rescan | — | | no emulator | Needs an emulator | A adds an emulator for System E | adds one | | new | 12 new | 12 added since yesterday (`added_at`) | — | * Focus: Up goes to the tabs; A opens the system in its remembered view; B comes back to the same tile (LF15). ### 4.3 A system's views: View button, remembered per system (LF2–LF5) * **Grid A–Z (default):** * A big letter (44/800, accent) with a count, and covers 6 across (7 in All games) with a gap of 18. A letter rail sits on the right; letters without games are dimmed and skipped. LB/RB jump a letter. * Built on LibraryGrid's windowing, recycling pool and steering, with letter headers as full-width rows in the same virtual list, and one gliding ring. * Letters and the rail show only when the order is A–Z. * **Shelf:** * Spines 52 px wide with a 38 px square icon on top and a rotated title, in named shelves ("Played recently", "Not played yet"). * The focused spine pulls out into a 150×266 cover (a transform: the spine's own layer scales and translates; neighbours slide by a transform), with an info line under the shelves. * Windowed horizontally for big systems. * **Playtime:** rows 60 px (icon 44, name, hours bar, hours, last played, friend dots, star), always most played first, windowed. * **The view picker (LF5)** is a sheet with a preview per view, plus "Use Grid A–Z for every system" (`az_everywhere`). ### 4.4 Order and filter (Y, LF6) * A right sheet, 600 wide. * **Order:** A–Z · Last played · Most played · Recently added. * **Show only:** Everything · Favorites · Not played yet · Played with friends online · 2 players or more · Has saves. * **Toggles:** Show hidden games, and "Remember for System A" (on). * A live "142 games match" count at the bottom. X resets. ### 4.5 All games (LF11) Grid A–Z across every system: 7 columns, a system badge on each card, and a 40 px letter. ### 4.6 Collections (LF7, LF8, LF18–LF21) * **Order:** yours, then shared, then "FROM TAGS · FILL THEMSELVES", then "EMULATORS · ALWAYS LAST". The tiles reuse SystemTile, with the attribution line in the emulator slot. There is a "+ New collection" tile. * **Shared (LF8):** "shared by Mika · 12 games · updated yesterday · you have 10 of them". Games you don't have get a dashed border and a "Not in your library" badge. X copies the collection to yours. * **Until Kouch has its own app id,** shared collections arrive as `.kod` (kind `collection`) by file, link or LAN. * **With the id:** Workshop items with friends-only visibility (a "created by friends" query). The UI is the same. * **From tags (LF21):** * Sentence rules: "Games tagged \[Racing] and \[2–4 players] on \[any system]", plus rule types tag, system, players, year and played state. * AND-joined as drawn. OR is a later addition, noted in DESIGN.md. * A live "11 games match · from 3 systems" count with a thumbnail strip. Y saves. * **Finished:** automatic, from `finished`. * **Emulators (LF19):** one card per emulator: * an abstract numbered swatch, never a logo; * "version X.Y · N h played in it"; * the systems it serves, as pills; * a state: "Up to date · motion set up · DSU on", "Version 1.0 ready · X to update", a progress bar "Updating · 41%", or amber "Needs your system files in bios\emulator-four". * A opens it, X updates, Y opens its settings. The last card is "+ Add an emulator / from a .kod file or a link". ### 4.7 Tags (LF20) * A right sheet with three parts: * **"FROM ITS INFO · FILLED IN WITH THE ART":** hideable chips. * **"YOUR TAGS":** "+ Add a tag", typed with the controller keyboard. * **"IN THESE COLLECTIONS":** each with a why line ("added by hand", "because of the tag Racing", …). * The footer says: "A tag you add fills every collection that looks for it. Info tags can be hidden, not deleted." * The sheet opens from the game page and from a card's X/Y menu (LF15). ### 4.8 Playtime section (LF9, LF10) * **Filter chips:** When (View: This week / This month / All time), System (Y), Emulator (X). * **The header:** "212 h in 96 games · 6 h 40 this week". * **The rows:** a system and emulator column, and friend dots placed along the bar (§2.6). * **Per emulator (LF10):** a stacked bar by system with a legend. ### 4.9 Unplugged drive (LF16, LF17) * The banner: "SD card (E:) isn't connected. 38 of System A's games live on it, so they're greyed until it's back in." X hides them (`hide_offline`). * Greyed tiles carry an "SD card" badge, and their A label is **Details**. * The details sheet: "On the SD card (E:), which isn't connected. Kouch can't reach the game until the card is back in. Plug it in and it lights up again on its own." Then "Your saves are safe: they live on Games (D:)." and "Last seen today at 09:40 · 2 h played.", with the actions \[Look again] and \[Game page]. ### 4.10 What is retired * The Classic 5×3 view, the Carousel view, the old List view and the old sort sheet are replaced by §4.3 and §4.4. Their tests move to the new views, their settings migrate (§2.1), and their code is deleted. * LibraryGrid's windowing, pooling and steering are kept and generalised. *** ## 5. Steam friends, lobby peek and chat that work (H5, C) The owner asked for "working steam friends and chat". **Everything here must work under a non-Steam shortcut (Steam API as 480) today.** Anything that needs Kouch's own id is marked and degrades to a clear note. ### 5.1 Friends feed * **`kouch-steam::profile` reads more:** * the nickname; * the medium avatar (64 px); * `GetFriendGamePlayed` with the full game id. This fixes the 24-bit truncation that turns shortcuts into "0" today: keep the 64-bit id, and treat "a shortcut" as "In a game". * the friend's lobby id (dropped today); * persona state (online / away / snooze / busy). * **Push, not pull:** a `steam:friends` event whenever the snapshot changes (the 2 s poll plus persona callbacks), up to 200 friends. Avatars are sent once, then referenced by hash. * **Presence dot:** green in a game, blue online, amber away. * **The status line:** * "Playing Sample game 12 · Mika's lobby" when their lobby is Kouch's (§5.2); * "In a game" for other games, since Steam gives no names for other apps without Web API; * "Online", or "Away · 20 min" (from last-online data where available). ### 5.2 Lobby peek, Join chip, friend sheet (H2, H3, H13) * **Peek:** * Add `request_lobby_data(lobby_id)` plus the `LobbyDataUpdate` callback to `kouch-steam`, the one sanctioned place for new `unsafe` FFI. * For each friend whose `GetFriendGamePlayed` has a lobby, request its data. If it carries the `kouch` key, read the game title, the game hash, the mods, `players.max` and the live member count (`GetNumLobbyMembers`, fixing the stale `players.now`). * Under 480 this works between Kouch users (same app id). * **The Join chip** appears when there's a free seat. * **The join planner runs before joining** (hash, mods, emulator, version) against the peeked data, so the friend sheet can show the three checks: "You have Sample game 12, the same version", "Same mods (2): they turn on for this session", "Emulator Two is installed". Fix `can_install_version` so a version mismatch offers the updater's pinned version instead of blocking. * **The friend sheet (H3):** * avatar, presence, "Hosting a lobby · online now"; * the lobby card with a 2×2 seat grid (host, members, "Your seat", "Open"); * the checks; * actions: Join Mika's lobby / Invite Mika to / Message / Profile on Steam; * "Played together 9 h this week · Last: yesterday, online", from sessions. * **Invites:** * **Per-friend invite** is `InviteUserToLobby` (works under 480 among Kouch users). * **An invite received** shows as a toast plus the persistent inline card with a countdown (H13). * A cold-start `+connect_lobby` argument is handled at boot. * The Steam client's own "Join game" launching Kouch needs Kouch's own id (under 480 it would start Spacewar). Mark this. * **The four Friends widget states (H13)** are all built: an invite arrives, nobody online (with "X Invite someone to Kouch" through the overlay invite dialog), Steam offline, and many online (grouped "CAN JOIN / PLAYING / ONLINE", A opens a group). ### 5.3 Chat 1. **Friends chat inside Kouch.** * `ISteamFriends::SetListenForFriendsMessages(true)` plus the `GameConnectedFriendChatMsg_t` callback, `GetFriendMessage` and `ReplyToFriendMessage`. This is Steam's supported way for a game to show and send friends chat inline. * Wrap it in `kouch-steam` (a callback on the thread that runs Steam callbacks, the input thread). Publish messages as a `steam:chat` event and send them through a command `steam_chat_send { steam_id, text }` routed as an `InputCmd` (so the Steam call stays on the Steam thread). * **The chat sheet:** * a conversation list (friends with messages this session, then online friends); * a thread view; * typing through Steam's floating keyboard, else Kouch's controller keyboard (`TextRow` / `OnScreenKeyboard`); * a toast on a new message while you're elsewhere in Kouch; * none while a game runs, unless the Quick Menu is open. * **Messages are not stored on disk,** matching Steam's own scope for a game session. * **To verify live:** whether listening under 480/shortcut delivers messages, and whether Steam's own chat window still shows them (expected: yes). This goes in the live checklist in §9. 2. **Lobby chat** for people in the same lobby: `SendLobbyChatMsg` plus `LobbyChatMsg`. This is the Chat widget's "lobby" tab and the lobby's chat in the Quick Menu's netplay row. 3. **Fallback:** "Open in Steam chat" through the overlay (`ActivateGameOverlayToUser("chat", id)`), or `steam://friends/message/` when the overlay isn't attached (a shortcut; Early Test 13 records which works). ### 5.4 Rich presence (own id only) * Once Kouch has its id: * Kouch sets `steam_display` (localization tokens uploaded with the app) and `connect` (a lobby join string), so friends outside Kouch see "Playing Sample game 12 on Kouch" and can join from Steam. * The code is written behind `has_own_app_id()` now and tested with a fake. * Until then, the status line comes from the lobby peek (§5.2). *** ## 6. Migration and removal * **Settings:** see §2.1, one `Settings::migrate` step with tests. Existing favorites stay (a flag); they show as a row type, a filter and a widget. * **Home:** the old hero plus shelves Home is replaced. Its "See all" jump becomes "A system" widgets and Library › Systems. * **Library:** see §4.10. * **Theme extras `library_view` and `card_shape`:** `card_shape` still applies to covers; `library_view` is ignored (documented in THEME\_FORMAT.md). *** ## 7. Order of work and hand-offs ```mermaid graph LR H0[H0 plan + contract] --> H1[H1 stage, A] H0 --> H2[H2 data v5 + mock, B] H0 --> H5[H5 friends + chat, C] H1 --> H3[H3 Home, A] H2 --> H3 H3 --> H4[H4 Edit Home + widgets, A + C] H5 --> H4 H1 --> H6[H6 Library, A] H2 --> H6 H2 --> H7[H7 tags + collections, B + A] H6 --> H7 H6 --> H8[H8 Playtime, A + B] H3 & H4 & H6 & H7 & H8 --> H9[H9 verification, central] ``` * **Parallel start:** * A starts H1 (stage) with the setup wizard first, then top bar, Players, Settings. * B starts H2 (with the 480 guard first). * C starts H5 (friends feed + lobby peek + chat backend), and afterwards builds the social widgets and the friend/chat sheets inside A's widget framework. * **A** then does H3 → H4 → H6 → H8, and B does H7's data side while A builds H6. * **Every commit** passes the full gate (CLAUDE.md). A UI commit also adds CDP screenshots at the stage sizes (§1) in Black and White. * **Contract changes** go only through B. A and C request them by message, with the exact field. *** ## 8. Tests * **Rust:** * the v5 migration (with a v4 fixture), sessions from a watcher exit and from `session_quit`, presence (a fake volume), tags merge and hide; * collection rules evaluation and live count, shared-collection import (a `.kod` fixture); * `playtime_summary` maths (week, streak, online nights); * the 480 guard; * the lobby-peek parser, the chat command routing, and the settings migration. * **UI (vitest):** * the widget grid (placement, no overlap, move/resize/remove, catalogue add), the Home focus map (H17) and the fold state machine (Right/Left/B, reduced motion); * Grid A–Z letters, rail and LB/RB jumps, Shelf pull-out focus, the Playtime order; * the order/filter sheet (per-system memory), system tile states, the unplugged banner and sheet; * the collections rule editor, the tags sheet, the friend sheet checks, the chat sheet, and the prompt labels per state. * **Fit (§1):** `fitcheck.mjs` metrics per screen and size, checked in to `docs/` as a summary table. ## 9. Verification and perf (central, continuous) * **CDP screenshots** of every new screen and state at the §1 sizes in Black and White, read back. * **New perf-tour phases:** | Phase | What it does | Bar (fps) | | ------------------ | ----------------------------------------------- | --------- | | `home_fold` | Right ×6, Left ×6 on Home, 260 ms moves | ≥ 85.5 | | `home_widgets` | Down/Up through the column and the Friends list | ≥ 85.5 | | `library_systems` | tiles | ≥ 85.5 | | `library_az` | 20 steps + 6 letter jumps in a 500-game system | ≥ 85.5 | | `library_shelf` | 20 steps, pull-out | ≥ 85.5 | | `library_playtime` | list steps | ≥ 85.5 | Update `tests/lib/perf-tour.test.ts` with the phases. Run each on the Deck in Game Mode (`gm-run.sh`), with an A/B against the previous build for every motion change. * **Live under Steam** (the Kouch Lab `rc` route, release build, as testers run it): * friends appear with presence; * a second Steam account's Kouch lobby shows a Join chip (needs a second account on the Deck or a friend; otherwise lobbies on 480 with two accounts); * chat both ways; * the overlay chat/profile under a shortcut (Early Test 13); * the battery on the Deck, unplugging an SD card or USB stick (LF16/H21), a session writing playtime. ## 10. Decisions taken for the owner (recorded, not asked) The owner's screens are off and they asked for autonomy. These decisions are ours, recorded here, and easy to reverse: 1. **The stage scales everything from the canvas's 1440×900 reference.** Extra width on ultrawide becomes more columns or cards, not bigger UI. 2. **The tag-rule editor is AND-only,** as drawn. OR comes later. 3. **Shared collections travel as `.kod` files** until Kouch has its own app id, then through the Workshop (friends-only). 4. **Friend dots use hours shared in Kouch lobbies,** so they only exist for friends you've played with online in Kouch. 5. **Chat history is not kept on disk.** 6. **Classic, Carousel and List views are retired.** Every system starts in Grid A–Z. 7. **Ten more widgets beyond the canvas,** for "many options for widgets", in the same visual language and all removable. 8. **"With save + time" shows its badge only when the emulator tells us the save.** Otherwise it falls back to time only. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kouch.dev/docs/home_library_plan.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.