Madeira/docs/LIBRARY.md

# Library front end

Madeira starts in a game library. The original diagnostic screen (the
"developer interface") is still there: **Settings › Interface › Use developer
interface** switches to it, and its **Use New Interface** button switches back.
Either change applies at the next start (close Madeira in the app switcher and
open it again).

The code is `app/Madeira/Library.swift` and `app/Madeira/GuestDisplay.swift`
(the virtual monitor and its layout), plus the wiring in `ContentView.swift`
(`launchLibraryEntry`, `runWineFullSequence(profile:)`, `sessionBody`, the
library HUD inside `TouchControlsOverlay`, and `MetalBackedView`'s layout and
touch mapping).

## Adding games

Copy a game's whole folder into **Madeira › wine › drive_c** with the Files app,
tap **+** and choose its `.exe`. Only x86 and x64 PE executables inside drive_c
can be added; the library stores the path relative to drive_c, so a changed
app container path does not break entries. Adding an entry installs nothing.

The library reads the executable's PE imports (and those of the DLLs next to
it, plus bounded scans for dynamically loaded renderer DLL names) to show a
graphics-API badge, and measures the install folder's size. The badge names an
API only when exactly one is found: it describes what the files import, not
which renderer a game picks at run time.

Library data is written atomically to `Documents/madeira-library.json`
(version 1); covers chosen from Files are stored as thumbnails in
`Documents/madeira-art/`. A library file that cannot be read, or that has a
newer version, is left untouched and cannot be overwritten from the UI.
Removing an entry never removes the game's files or saves.

## Library screen

- Layouts: cards, compact cards, list and compact list (one short row per
  game). Sort by last played, name, date added or folder size. Search by title.
- Sections, as in the fork's library: when Madeira Dock is available,
  **Steam** (the Steam games being downloaded and the games Steam has
  installed, with their count; a **Sign in to Steam** card when signed out),
  its **Not installed** group (the account's other games, with their count),
  then **Other games** (the games you added; **+** in the navigation bar adds one). Tapping
  **Steam** or **Other games** collapses it; **Not installed** folds on its
  own, open by default; each state is remembered. Search, the layout and, for
  installed games, Sort by apply to every section. Pull down to read the
  Steam install records and the account's library again. Without Madeira
  Dock the games you added are one grid.
- Grid cards: a game that is not installed shows its artwork darkened, with a
  download glyph on a soft circle of blur. Every grid card throws ambient
  light on the page around it, like an LED strip behind a TV: its artwork's own
  colours, with arcs of the ring brightening and falling into shadow and the
  colours travelling around it as if a film were playing (fainter and less vivid
  for a game that is not installed; held still with Reduce Motion). Pressing a
  card shrinks its artwork, and its light draws in with crisp rays and goes out
  behind it like a spotlight's aperture closing; on release the artwork springs
  back and the light opens again slowly. The width a row of cards leaves goes
  into the gaps between them, so each card's light keeps to its own space.
- **Desktop** opens the Wine desktop (explorer and services in a virtual
  desktop) with its own profile; its Resolution is the desktop's size.
- The build label (`MadeiraBuild` in Info.plist, else the bundle version) is
  shown in Settings (Ready to play) and in the developer interface's status row.
- **Settings**: JIT and memory status, Enable JIT, extended logging, pointer
  mode (Absolute, Relative or Touch) and touch sensitivity, **Display** (hold
  the display at its maximum rate, off by default), **Memory & sync** (swap tier
  Off/1/2/4 GB, off by default; sync engine, Fastsync by default), the interface
  switch and **Credits** (the last section). Display applies from the next session or FPS limit change; Memory &
  sync after a restart. They write `env.MADEIRA_PROMOTE`, `swap-mb`,
  `inproc-sync` and `env.MADEIRA_FASTSYNC` in `Documents/madeira.cfg`, keeping
  every other line. With neither sync key set the engine is fastsync
  (`madeira_cfg_sync_engine` in `build/madeira_cfg.h`); `inproc-sync = 1` selects
  madsync.

## Game details

Tapping a game opens its details page; it stays up until the session's
starting screen takes over (or an error is shown). A profile holds:

- title and cover image;
- **Resolution**: the size of the Windows screen (the virtual monitor) the game
  renders for: 640×480 to 2560×1440, plus **Screen shape**, this device's own
  aspect ratio at 720 lines (for example 1560×720 on a 19.5:9 phone), so a game
  fills the screen without bars. It is exported as the session default
  (`MADEIRA_SCREEN_W/H`, `MADEIRA_SCREEN_SRC=knob`), which win32u reports for
  the session. New entries use 1024×768, the size main uses for every launch;
- **Aspect & scaling**: how that screen is shown. **Fit** letterboxes it,
  **Fill** covers the screen and crops, **Stretch** fills it exactly, **Aspect**
  letterboxes the shape the game actually draws (its back buffer) and **Fill
  height** keeps that shape at full height. Touches are mapped through the same
  rectangle, so input lines up in every mode;
- FPS limit: 60, the display maximum or uncapped (the same presentation
  pacing modes as the FPS pill in the developer interface), and 30 when DXMT
  has its 30 FPS cap (willfaust/dxmt#1; DXMT without it would present mode 3
  uncapped, so the choice is hidden and a saved 30 runs as 60);
- reduced-precision x87: off by default, as in FEX; only an explicit choice
  exports `FEX_X87REDUCEDPRECISION=1`;
- **CPU cores reported** (Automatic, 1, 2, 4 or 6) and **D3D9 anisotropic
  filtering** (Application default, up to 1×, 2×, 4× or 8×): only a choice
  other than the default exports `MADEIRA_CPU_COUNT` (wine) or
  `DXMT_D9_ANISO_LIMIT` (DXMT); the defaults export nothing. The library
  exports no other engine switch;
- launch arguments (double-quoted tokens, at most 64 and 4 KB in total; not
  for Steam games, which Madeira Dock starts with Steam's own launch option);
- performance overlay, live logs and touch controls for the session, with the
  controls' **opacity** and overall **size**. The touch layout itself is saved
  per game from the in-game editor.

A game you added starts directly. A Steam game's page (`docs/STEAM_LIBRARY.md`)
adds a **Steam** section under the library details: **Start with** Madeira
Dock (the default) or **The game** (its own program without Steam, from Steam's
launch configuration or chosen under **Program**), Dock's per-launch pool
choice, **One-time installs**, updates, **Repair
installed files**, App ID, free space and **Uninstall**; its **Executable**
section shows the install folder, and it has no **Remove from library** (the
entry goes with **Uninstall**).

## Sessions

Play applies the profile and runs the same `runWineFullSequence` as the
developer interface's buttons. The game is shown full screen in either
orientation. A starting screen with the game's cover stays until the first
frames arrive (Metal presents or a desktop surface); after 30 seconds it offers
**Show game view**. A Madeira Dock start keeps it, with the Dock's status,
until the game's own window is shown, and adds **Show desktop**
(`docs/MADEIRA_DOCK.md`, "Starting screen"). A row of round glyph-only buttons (their words are
VoiceOver labels) holds **Show live log**, which shows the most recent log lines.

The small menu button (drag to move; it fades after three seconds) opens the
in-game menu:

1. touch controls on/off, their **Controller layout** (the built-in Xbox
   controller, the user's custom layouts, **Create new layout**; remembered per
   game), their **Opacity** and **Size**, **Edit controls**
   (the existing editor) and the **Keyboard** (its own key window, with an
   Esc/Ctrl/Shift/Alt/Tab/Enter/arrow row; modifiers latch);
2. the FPS limit, **Aspect & scaling**, and the mouse and pointer settings;
3. the performance overlay and its fields (FPS, average frame time, memory
   footprint, battery);
4. **Quit game** in red. Quit asks the program to close with Alt+F4 through
   the normal input queue, so it can save; the session ends when it exits.

Changes made in the menu (FPS limit, Aspect & scaling, controls, overlay) are
saved to the game's profile.

**Pointer modes.** Absolute drags the pointer like a trackpad, Relative sends
finger movement as mouse movement (mouse-look), and **Touch** clicks where the
finger is: tap to click, hold or move to drag, a two- or three-finger tap for a
right or middle click, a two-finger drag to scroll. Touch works in direct and
desktop sessions.

When the session ends Madeira returns to the library, restores the touch layout
it had before, and hides the ended session's surfaces. If the session ended by
itself and the program Madeira launched exited with a Windows error status
(for example `0xC0000005`, memory access violation), a message says so. The
status comes from one weak hook in ntdll's common exit wrapper
(`wine_launched_process_did_exit` in `build/ntdll-unix/server_ios.c`), called
only for the session's initial process, the one the app handed to
`__wine_main`; helpers and processes the program starts are never reported.
The hook takes one integer, does not allocate and does not log; the app keeps
only the last error status. No program names are involved.

One Wine session runs per app run: a second one cannot start in the same
process (the wineserver's permanent objects from the first session remain and
the registry initialisation aborts). The library asks to restart Madeira
instead.

## Steam setup

The code is `app/Madeira/Onboarding.swift`. It uses Steam sign-in
(`docs/STEAM_SIGNIN.md`) and Madeira Dock (`docs/MADEIRA_DOCK.md`) through
their public pieces only: `SteamSignInModel`/`SteamSignInView` for signing in
and out (the token stays in sign-in's Keychain store), and
`MadeiraDockModel.prepareClient()`/`MadeiraDockView` for Dock.

**First-run setup.** On a new install the library opens a full-screen setup
once: welcome, **Sign in to Steam**, **Prepare Madeira Dock** (Valve's client
components, about 73 MB, only when Dock is available), done. Every step has
**Set up later**, and the welcome page has **Skip setup**. Finishing or
skipping stores `madeiraOnboardingDone` in the app's UserDefaults, which iOS
removes with the app. Setup opens only when there is something to set up: the
sign-in page needs Steam sign-in or Dock, and without either setup never
opens. It never opens over a running session.

Setup is app UI only. It starts no Wine session, and the component download
runs Dock's own verified download without Wine. It changes no JIT pool, engine
switch or configuration default.

**Settings › Steam** shows the signed-in account with **Sign out of Steam**
(or **Sign in to Steam**), **Madeira Dock** (Dock's sheet, with the last Dock
result under it) and **Run setup again**. A game started from the Dock sheet
here runs as a library session: full-screen view, starting screen, in-game
menu, and the one-session-per-run rule. That session is not added to the
library.

**Steam games in the library** (`app/Madeira/SteamGames.swift`). When Madeira
Dock is available, the library shows a **Steam** section above **Other
games**, the games you added. It lists the games Steam has installed in the
prefix, exactly as Dock's own discovery finds them (`appmanifest_<appid>.acf`
in `C:\Program Files (x86)\Steam\steamapps` and the other C: libraries its
`libraryfolders.vdf` lists), and, once you are signed in, under **Not
installed**, the account's owned games that are not installed yet, which are
installed from their download sheet (`docs/STEAM_LIBRARY.md`); a game being
downloaded moves up to the installed games. The section follows the library's
search and layout and collapses like Other games. Artwork comes from Steam's
public store CDN.
An installed game opens its **Game details** page (above): the game is a
library entry with its own settings, listed only in the Steam section, and its
**Play** goes through Dock's launch path with the entry as its launch profile,
as a library session. When a download finishes, the sheet's button reads
**Open** and opens that page. Play starts only a game Steam marks fully
installed (and not being downloaded), with Valve's client components present
and a Steam sign-in. Reading install records never
writes Steam files; only the downloads and **Uninstall** of `docs/STEAM_LIBRARY.md`
do, and only in Madeira Dock's own library folder. Controller focus does not
reach the section yet.

Log tags: `[onboarding]` (`shown reason=… steps=…`, `step=…`, `done`,
`skipped`), `[steam-games]` (counts and App IDs), `[library-sections]`
(`native-steam=… sections=… collapse=…`, flags only) and the library and download
tags of `docs/STEAM_LIBRARY.md`. No account name, token or path is logged.

## Controllers

Player 1's controller navigates the library through `GamepadInput`: D-pad or
left stick moves the focus, A opens and plays, B goes back, Y adds a game and
the shoulder buttons switch between Library and Settings. In a session,
Back+Start opens the in-game menu and B closes it. While the library or its
menu owns input, the game sees a connected pad at rest.

## Switches

`env.NAME = 0` in `Documents/madeira.cfg` (or `NAME=0` in `madeira-env.txt`):

| Switch | Default | `0` means |
| --- | --- | --- |
| `MADEIRA_FRONTEND_DEFAULT_NEW` | on | the developer interface is the default |
| `MADEIRA_FRONTEND` | unset | `env.MADEIRA_FRONTEND = 0/1` picks the interface when nothing was chosen in the app |
| `MADEIRA_FRONTEND_CONTROLLER` | on | no controller navigation |
| `MADEIRA_ONE_SESSION_PER_RUN` | on | a second session is attempted anyway |
| `MADEIRA_EXIT_REPORT` | on | no message when a session ends by itself |
| `MADEIRA_LIBRARY_HIDE_ENDED_DESKTOP` | on | the ended desktop's surface is left as it was |
| `MADEIRA_BUILD_LABEL` | on | no build label (the `[build]` log line stays) |
| `MADEIRA_UI_LOG_IDLE` | on | the log view keeps parsing while hidden |
| `MADEIRA_LOG_VIA_STDERR` | on | Swift log lines use their own file handle |
| `MADEIRA_RUNTIME_SETTINGS` | on | no Display and Memory & sync sections in Settings |
| `MADEIRA_SESSION_TOOLS` | on | no Aspect & scaling in the in-game menu, and a session does not save it |
| `MADEIRA_SCREEN_SHAPE_RESOLUTION` | on | no Screen shape resolution choice |
| `MADEIRA_FRONTEND_KEYBOARD` | on | Keyboard opens the game view's own keyboard instead of the key window |
| `MADEIRA_ONBOARDING` | on | first-run setup never opens, and Settings › Steam has no **Run setup again** |
| `MADEIRA_LIBRARY_COLLAPSE` | on | the **Steam** and **Other games** titles do not collapse (**Not installed** still folds) |
| `MADEIRA_LIBRARY_AMBIENT` | on | no ambient light around the library's grid cards |

Opt-in (`env.NAME = 1`), off by default:

| Switch | `1` means |
| --- | --- |
| `MADEIRA_PROMOTE` | the display link also holds the panel at its maximum rate in the 60 FPS cap (Settings › Display) |
| `MADEIRA_DEVICE_STATS` | a `[device-load]` line (thermal state, low power, screen capture) every 10 s while Wine runs |

Log tags: `[frontend]`, `[display]`, `[display-shape]`, `[frontend-pointer]`, `[launch-view]`, `[startup-log]`, `[exit-report]`,
`[session-once]`, `[library-surface]`, `[library-metadata]`, `[onboarding]`,
`[frontend-controller]`, `[frontend-keyboard]`, `[device-load]`, `[promote]`.

## Tests

`tests/host/check-frontend.py` (profiles incl. resolution and scaling,
the engine switches a profile exports, the 30 FPS fallback, the display layout
math, controller commands, the exit hook, and the presence of the details and
in-game menu options), `tests/host/check-runtime-settings.py`
(`MadeiraConfig.set` and the Settings defaults) and
`tests/host/check-library-api.py` (renderer detection and the badge).
`tests/host/check-onboarding.py` covers Steam setup: the pages with and
without Dock, the done key, the `MADEIRA_ONBOARDING` switch, and the wiring
(no Wine session, no pool or engine switch, sign-in and Dock only through
their public pieces).
`tests/host/check-steam-games.py` covers the library's Steam section: Dock's
discovery on a synthetic drive_c laid out as Steam writes it, the merge of
installed and owned games, the section, status, card pill, search, Play and
artwork rules, the program an installed game's pills describe, the groups of the
library's sections and their Sort by order, and that Play uses only Dock's launch
path. `tests/host/check-library-sections.py` covers the library page's
sections (order, texts, collapsing, search, layout, pull to refresh).
`tests/host/check-steam-library.py`
covers the owned library and downloads (`docs/STEAM_LIBRARY.md`).