The app has an icon

Every build so far shipped the default Electron one. electron-builder said so on
every run — "default Electron icon is used, reason=application icon is not set" —
in a line that is very easy to read past. A store people install games with
should not look like a framework demo in the Dock.

The mark is a W with three lines running into it: the product's initial, and what
it is doing. It uses the window's own palette, so the icon and the application it
opens are the same object. Drawn for the smallest size first, which is what
settled it — at 32px the W still reads and the lines survive as motion rather
than as noise, where a ring, an outline or fine detail did not. A portal, a play
triangle and a send arrow were each drawn and each discarded: they already mean a
loading spinner, a media player and a submit button.

`resources/icon.svg` is the source and the only file anybody should edit.
`make icons` renders the rest. Three committed binaries with no way to regenerate
them is how an icon becomes something nobody dares change, so the ICO is written
here rather than shelling out to ImageMagick — the container is a header and 16
bytes per image, which is not worth a build dependency this machine does not
have.

`directories.buildResources` had to move off the default: electron-builder looks
in `build/`, which this project uses for compiled output and wipes on `make
clean`, so the icons would have been deleted before every package.

The window picks it up when run from source too, where there is otherwise nothing
to carry an icon and a dev run looks like a different application. Guarded on
`app.isPackaged`, because `resources/` is not inside the package and pointing at
it there would be a path that does not exist.

Verified by reading the icon back out of the built bundle rather than trusting
the config: extracted from `WarpEngine Client.app/Contents/Resources/icon.icns`
and looked at, and the ICO parsed entry by entry — 7 images, 16 to 256, each a
valid PNG.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.woodpecker.yaml

@@ -0,0 +1,68 @@
+# The pipeline lives in the repository rather than in the update server's
+# `/build/config` extension. That extension serves game-platform pipelines, which
+# build a cartridge and publish it into the site's catalog; this one builds a desktop
+# application and publishes it to a Gitea release. Different product, different target.
+#
+# What CI can and cannot do here: Linux and Windows packages are built in containers —
+# Windows through Wine — while the **macOS package stays a local build**, because
+# Apple's toolchain and its signing exist only on a Mac. A release therefore gets its
+# Linux and Windows assets from this pipeline and its macOS assets from `make release`.
+when:
+  - event: [push, manual]
+    branch: master
+  - event: tag
+
+variables:
+  # The official electron-builder images: Node with the packaging tools, and the same
+  # image plus Wine, which is what lets a Windows installer be built on Linux.
+  - &node_image 'electronuserland/builder:22'
+  - &wine_image 'electronuserland/builder:22-wine'
+
+steps:
+  - name: check
+    image: *node_image
+    commands:
+      - node --version
+      - npm ci
+      - npm run typecheck
+      - npm run lint
+      # The window test wants a display and a store on the machine; that check belongs
+      # where there is one. The bridge check runs here unconditionally — it needs nothing
+      # but Node, now that the store engine is part of the application.
+      - npm run smoke
+
+  # A quarter of a gigabyte of packages is not worth building on every push, so the
+  # two builds run when a release is being cut — or when asked for by hand.
+  - name: linux
+    image: *node_image
+    commands:
+      - npm run dist:linux
+      - scripts/ci-verify-packages.sh '*.AppImage' '*.deb'
+    when:
+      - event: [tag, manual]
+
+  - name: windows
+    image: *wine_image
+    commands:
+      - npm run dist:win
+      - scripts/ci-verify-packages.sh '*.exe'
+    when:
+      - event: [tag, manual]
+
+  # Only on a tag, and only what this pipeline built: the macOS assets are uploaded
+  # from the Mac that can sign them.
+  - name: release
+    image: alpine
+    environment:
+      # Needed. Woodpecker does hand steps a forge credential — a manual build printed
+      # one — but a build started by the tag webhook does not get it: the first tag build
+      # died here with no credential at all. So the token is a repository secret, and the
+      # script still falls back to the forge credential when it is there.
+      GITEA_TOKEN:
+        from_secret: gitea_token
+    commands:
+      - apk add --no-cache curl jq
+      # No globs on the command line: the package names have spaces in them.
+      - scripts/ci-upload.sh
+    when:
+      - event: tag

Makefile

@@ -1,4 +1,4 @@
-# WarpEngine Store GUI — the front door to the npm scripts.
+# WarpEngine Client — the front door to the npm scripts.
 #
 # Everything here is a thin wrapper: the app is an Electron project, so npm still
 # does the work. The Makefile exists so the useful sequences have names, and so
@@ -18,17 +18,29 @@ SHELL := /bin/sh
 SCRIPTS := scripts
 NODE_MIN := 22
 
-# The version is package.json's, so the release tag never drifts from the app.
+# The version is package.json's, so the release tag never drifts from the app. Read with
-VERSION := $(shell python3 -c 'import json; print(json.load(open("package.json"))["version"])')
+# node, which this project already requires — nothing here needs an interpreter the app
+# itself no longer depends on.
+VERSION := $(shell node -p 'require("./package.json").version')
 TAG ?= v$(VERSION)
 
+# Which site's store registry a packaged build reads. Empty means the default in
+# package.json (ours); set it to build a client for somebody else's catalog:
+#
+#   make dist STORES_API=https://games.example.org/api/stores
+#
+# It is baked into the package's own package.json, so the built app carries it. A runtime
+# STORES_API still overrides it, which is for trying something out rather than shipping.
+STORES_API ?=
+BUILDER_ARGS := $(if $(STORES_API),-- --config.extraMetadata.warpEngine.registryUrl=$(STORES_API),)
+
 .DEFAULT_GOAL := help
 
-.PHONY: help setup node-check build typecheck lint lint-fix check start smoke uitest test \
+.PHONY: help setup node-check build typecheck lint lint-fix check start smoke uitest storetest icons test \
         dist dist-mac dist-win dist-linux release publish clean distclean version
 
 help: ## List available targets
-	@echo "WarpEngine Store GUI $(VERSION) — usage: make <target>"
+	@echo "WarpEngine Client $(VERSION) — usage: make <target>"
 	@echo
 	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | \
 		awk 'BEGIN {FS = ":.*?## "}; {printf "  %-12s %s\n", $$1, $$2}'
@@ -60,7 +72,7 @@ lint-fix: ## Lint and fix what can be fixed automatically
 
 # The order is deliberate: a type error explains a lint error, and both explain a
 # failing test, so the cheapest check that can fail runs first.
-check: typecheck lint test ## Type-check, lint, and run both test suites
+check: typecheck lint test ## Type-check, lint, and run every test suite
 
 start: ## Run the app against whatever store is installed
 	npm start
@@ -71,19 +83,25 @@ smoke: ## Drive the store bridge with no window at all
 uitest: ## Load the window once and report what rendered
 	npm run uitest
 
-test: smoke uitest ## Both checks
+icons: ## Render every icon format from resources/icon.svg
+	npm run icons
+
+storetest: ## Add and remove a store in a sandbox (the only code that deletes a tree)
+	npm run storetest
+
+test: smoke storetest uitest ## All three checks
 
 dist: node-check ## Package for this machine
-	npm run dist
+	npm run dist $(BUILDER_ARGS)
 
 dist-mac: node-check ## Package for macOS (ad-hoc signed, see the README)
-	npm run dist:mac
+	npm run dist:mac $(BUILDER_ARGS)
 
 dist-win: node-check ## Package for Windows
-	npm run dist:win
+	npm run dist:win $(BUILDER_ARGS)
 
 dist-linux: node-check ## Package for Linux
-	npm run dist:linux
+	npm run dist:linux $(BUILDER_ARGS)
 
 publish: ## Upload the packages already in dist/ to the Gitea release
 	@TAG=$(TAG) $(SCRIPTS)/release.sh
@@ -106,4 +124,5 @@ version: ## Show the versions involved
 	@printf "typescript "; npx tsc --version 2>/dev/null || echo "missing"
 	@printf "eslint     "; npx eslint --version 2>/dev/null || echo "missing"
 	@printf "tea        "; tea --version 2>/dev/null | head -1 || echo "missing — devarea: make tea"
-	@printf "python3    "; python3 --version 2>/dev/null || echo "missing"
+	@printf "registry   "; node -p 'require("./package.json").warpEngine.registryUrl'
+	@if [ -n "$(STORES_API)" ]; then printf "  build override: %s\n" "$(STORES_API)"; fi

README.md

@@ -1,17 +1,18 @@
-# warp-engine-desktop-gui — a window for the desktop store
+# warp-engine-client — the WarpEngine Client app
 
-A graphical client for
+The client for a WarpEngine store: the catalog as a grid of cards, one click to install
-[`warp-engine-desktop-store`](https://git.teletypegames.org/stores/warp-engine-desktop-store):
+a title into your own application menu, one to play it, one to remove it. Linux, macOS
-the catalog as a grid of cards, one click to install a title into your own
+and Windows.
-application menu, one to play it, one to remove it. Linux, macOS and Windows.
 
-The CLI stays the product; this is its front door. Every action here runs
+**The store engine is part of this application.** Reading the catalog, choosing which
-`desktop_store.py`, so there is one catalog logic, one state file and one delete
+release fits this machine, unpacking it, writing the menu entry and remembering what
-guard — the window never touches the filesystem itself.
+went where all happen in process — there is no interpreter to find and no child process
+to parse. What lands on disk has not changed: `config.json` and `state.json` keep the
+shape the shell engine wrote, so a machine whose library was installed by the CLI keeps
+it, and the engine's own defaults still decide everything a store does not configure.
 
-It is also **the Windows install path**. The store's own installer is
+That also makes this the only install path that needs nothing of the machine. The shell
-`curl … | sh`, which Windows does not have; this app downloads the store engine
+store's installer was `curl … | sh`, which Windows does not have.
-itself, into the same folder the shell installer would use.
 
 Which store it installs is not baked in: the client asks a registry — `GET
 /api/stores` on the site — and each record says what the store is called, which
@@ -19,10 +20,8 @@ catalog it serves and where its configuration lives.
 
 ## What it needs
 
-- **Python 3** on the machine, because the store is a Python program. The app
+- **Nothing.** No interpreter, no package manager, no admin rights: the app carries its
-  looks for `python3`, `python` and `py -3`, and says so plainly if none answer.
+  own runtime and the store installs under your own user account.
-- Nothing else at runtime. No Node, no package manager, no admin rights: the
-  store installs under your own user account.
 
 To *develop* it you also need **Node 22 or newer** — see below — and nothing else: the
 toolchain (TypeScript, ESLint, esbuild, electron-builder) installs with `make setup`.
@@ -30,7 +29,7 @@ toolchain (TypeScript, ESLint, esbuild, electron-builder) installs with `make se
 ## Install
 
 Grab the package for your machine from the
-[releases](https://git.teletypegames.org/stores/warp-engine-desktop-gui/releases)
+[releases](https://git.teletypegames.org/stores/warp-engine-client/releases)
 and open it. On first run, if there is no store on the machine yet, the window
 offers to download one — that is the whole setup.
 
@@ -40,15 +39,15 @@ The build is ad-hoc signed but **not notarised**, so macOS asks before running a
 copy that came from a browser. The reliable way through:
 
 ```sh
-xattr -dr com.apple.quarantine "/Applications/WarpEngine Store.app"
+xattr -dr com.apple.quarantine "/Applications/WarpEngine Client.app"
 ```
 
 If macOS offers *Open Anyway* under **System Settings ▸ Privacy & Security** after
 a blocked attempt, that works as well. Notarisation is the only thing that removes
 the step entirely, and it needs a paid Apple Developer ID.
 
-Nothing the store itself downloads is affected: Python fetches those files, and
+Nothing the store itself downloads is affected: the app fetches those files over its
-Python does not set the quarantine flag.
+own HTTP client, which does not set the quarantine flag.
 
 **v1.0.0 could not be opened at all** — it reported *"is damaged"*. The bundle had
 never been signed; only its main executable carried the linker's ad-hoc signature,
@@ -56,6 +55,45 @@ so there was no resource seal and Gatekeeper refused it outright rather than
 asking. `scripts/after-pack.js` signs the bundle during the build now, and the
 result verifies as `valid on disk`.
 
+## Signing in, and titles that cost money
+
+**Nothing in this client knows anything about a particular store.** What a title costs,
+whether it needs an account, where to buy it and where to sign in all arrive from the
+catalog's own server — WarpEngine 0.5 answers `GET /api/service` with what it offers, and
+puts an `access` block on every catalog entry. A client that carried those facts would
+work for exactly one shop; this one asks.
+
+Where the server offers no sign-in — every WarpEngine before 0.5, and any store that
+sells nothing — the window shows none, and behaves exactly as it always did.
+
+Where it does:
+
+- the side menu grows an **Account** block: *Sign in…*, and *Sign out* once you are;
+- signing in shows a **short code**. Your browser opens on the store's own page and you
+  type the code there; approving it signs this device in. Nothing is typed into this
+  window, and no password ever reaches it — that is the whole reason for the detour;
+- the token is kept in the **OS keychain** (Keychain, libsecret, DPAPI) through
+  Electron's `safeStorage`, one per store. Where no keychain is available it is not
+  stored at all rather than written out in the clear: the cost is signing in again next
+  run.
+
+On a card, what you may do with a title is separate from what this machine can run:
+
+- **owned** or free → *Install*, as before;
+- **not owned** → the **price** on the card and a **Buy** button, which opens the store's
+  page in your browser. Buying happens there, not here — a checkout rebuilt in this
+  window would be a second place to get card handling wrong. **Refresh** afterwards and
+  the card becomes an *Install*;
+- **signed out, catalog gates it** → *Sign in to install*, because the catalog cannot say
+  whether it is yours until it knows who is asking.
+
+Two new categories go with it: **Owned** and **To buy**. Owning something is not the
+same as having installed it, which is the point of the first one.
+
+A title nobody has bought is **not** dimmed. That treatment belongs to what this
+*machine* cannot do — an unsupported platform, no build for this architecture — and
+there is nothing wrong with the machine here.
+
 ## Which store it installs
 
 On first run the client fetches the registry and offers what it finds. One store
@@ -63,36 +101,52 @@ and there is nothing to decide; several and the setup screen shows a picker.
 
 ```json
 [
-  {
+  { "name": "Teletype Games", "catalogUrl": "https://teletypegames.org" },
-    "name": "Teletype Games",
+  { "name": "Some Other Store", "catalogUrl": "https://games.example.org" }
-    "catalogUrl": "https://teletypegames.org",
-    "storeRepositoryUrl": "https://git.teletypegames.org/stores/ttg-desktop-store"
-  }
 ]
 ```
 
+**A name and a catalog are the whole record.** The store engine's built-in defaults
+already cover the host-to-asset mapping, the install modes, the platforms and the
+behaviour, so what is actually missing from them is identity — and identity is all a
+registry says. Nothing a record carries decides where files go: how a store behaves is
+fixed per installed client, which knows its own machine, and a copy of that on a server
+would be a second authority over decisions this side has already made.
+
 From a record the client works out the rest:
 
-- **`storeRepositoryUrl`** → the store's `config.json`, read from
+- **the store id** — which names the store home and the folder games land in — is a slug
-  `…/raw/branch/master/config.json`. That file is the authority on how the store
+  of the catalog host (`teletypegames.org` becomes `teletypegames`), or of the display
-  behaves: which platforms, which statuses, where things land.
+  name if that fails. Derived from the *catalog* on purpose: the catalog is what a store
-- **`catalogUrl` and `name`** override the config's own `store.base_url` and
+  is, so two records naming the same one are the same store and land in the same place.
-  `store.name`. The registry says which catalog this store is *for*, so it wins.
+  Reinstalling therefore never orphans what is already installed.
-- **the store id** — which names the store home and the folder games land in —
+- **the games folder** is that same slug inside the OS's usual place for programs, and it
-  comes from the repository name: `ttg-desktop-store` becomes `ttg`. A
+  is the only subtree this store will ever delete from. That is the whole of how two
-  `config.json` that sets its own id keeps it.
+  stores on one machine stay out of each other's files: a subfolder, derived here.
+- **released, archived and demo** titles are listed, where the engine alone would show
+  released and archived only — a catalog that publishes a demo means it to be played.
 
-A repository **without** a `config.json` still works. The engine merges whatever
+Because a record has no paths in it and no config, there is nothing for the window to
-it is handed onto its own defaults, so the client writes a three-field config and
+tamper with: `RegistryStoreDtoMapper.toModel` can take its choice at face value, and the
-the store behaves like the default one pointed at that catalog.
+config that lands on disk is written by the installer from the engine's own defaults.
 
-The registry address is the single thing about a particular site left in the
+What the defaults produce, for a record with no repository: the games land in a
-client, and `STORES_API` overrides it:
+folder named after the store id, and released, archived **and demo** titles are
+listed — a catalog that publishes a demo means it to be played.
+
+The registry address is the single thing about a particular site left in the client,
+and it is decided in three places, most specific first:
 
 ```sh
-STORES_API=http://127.0.0.1:8731/stores npm start
+STORES_API=http://127.0.0.1:8731/stores npm start   # runtime: for trying something out
+make dist STORES_API=https://games.example.org/api/stores   # build: for shipping it
 ```
 
+The build variant is baked into the packaged app's own `package.json`
+(`warpEngine.registryUrl`, written by `electron-builder --config.extraMetadata`), so a
+client built for somebody else's catalog needs no source change and no environment on the
+user's machine. With neither set, the address is ours.
+
 Adding a store is therefore a database row on the site — see its ActiveAdmin
 panel — and not a release of this app.
 
@@ -105,17 +159,28 @@ Everything that is not a title lives in the **side menu** on the left, and the
   another switches to it: the grid, the categories and the folders all follow, and
   the client reopens on that store next time. Two stores installed from the same
   catalog into different folders show their folder instead of their id, because
-  the id would not tell them apart. **Add a store…** brings up the registry
+  the id would not tell them apart. Hovering a row shows a **bin**, which takes that
-  picker, the same one the first run offers.
+  store off the machine — see below.
-- **Actions** holds **Install all**, which fetches everything the catalog offers
+- **+**, beside Refresh, brings up the picker: the stores the registry offers, and a
-  for this machine, and **Refresh**, which re-reads the catalog.
+  field for **any catalog address of your own**. A bare host is enough (`https` is
+  assumed) and the name is taken from it. This is the same screen the first run shows,
+  so a machine with no store yet can also start from a typed address rather than only
+  from the list.
+- **Account** appears only where the catalog offers a sign-in, and holds *Sign in…* or
+  *Sign out* — see above.
+- **Actions** holds **Refresh**, which re-reads the catalog, and **+** to add one. Titles are installed
+  one at a time from their own cards; there is no install-everything button.
 - **Categories** narrows the grid, one category at a time, with the count next to
   each: *Everything*, *Installed*, *Updates*, *Not installed*, then a row per
   **platform** (`godot`, `tic80`, `love`, …) and per **kind** (native or hosted).
+  Where the catalog gates anything, **Owned** and **To buy** join them.
   The axes are built from what the catalog actually contains — a platform with no
   titles is not listed, and a category that disappears under you falls back to
   *Everything* rather than leaving an empty grid. There is no genre in a
   WarpEngine catalog, so these are the categories there are.
+- **Log** opens the store's own output — its words, verbatim — together with the two
+  folders everything lands in. Off screen until asked for: the window has no footer,
+  because a permanent bar of absolute paths is not what a store is for.
 - **Language** follows the system and can be switched; **English and Hungarian**.
 
 In the grid, a card's button is **Install**, **Update**, or **Play** / **Open**
@@ -124,8 +189,13 @@ once it is there. **Remove** takes a title back out. Each card says whether it i
 build the catalog serves rather than packages, so its entry opens a page and needs
 the network.
 
-The **Log** drawer at the bottom carries the store's own output verbatim, and next
+**Everything in the catalog is listed, including what this machine cannot install.**
-to it are buttons that open the two folders everything lands in.
+Those cards are dimmed, carry an *unsupported platform* or *no build for this machine*
+badge with the engine's own explanation under it, and have nothing to press. A store
+that hides them leaves you wondering whether the catalog is small or your machine is
+unusual; this way it says which. They have a category of their own — *Not for this
+machine* — and they are left out of the native/hosted counts, because a title with no
+build has no mode to be counted under.
 
 Every card carries a band of box art the same height — the first letter of the
 title when the catalog has no image — so titles and buttons line up across a row.
@@ -137,6 +207,13 @@ While the store is working, only the things that would start a second call are
 disabled: the menu, the log drawer and the category filters keep working, because
 they change what is on screen and nothing on disk.
 
+**Removing a store uninstalls what it installed.** The bin on a store row asks first,
+and says how many titles will go with it. That is not a convenience — a store's
+`state.json` is the only record of which payloads, icons and menu entries belong to it,
+so leaving the games behind would leave orphans nothing could ever identify, least of
+all a later install of the same store into the same folder. The catalog cache, the
+settings and any sign-in token go too.
+
 Anything installed from the window is a normal menu entry, so it also shows up in
 your launcher, Dock or Start menu — the app does not have to be running to play.
 
@@ -151,9 +228,12 @@ names. `make` on its own lists everything.
 | `make build` | compile TypeScript, bundle the preload and the renderer |
 | `make typecheck` | type-check everything, emitting nothing |
 | `make lint` | the strict rule set (`lint-fix` fixes what it can) |
-| `make check` | **typecheck, lint and both test suites** — the gate |
+| `make check` | **typecheck, lint and every test suite** — the gate |
 | `make start` | run the app against whatever store is installed |
+| `make icons` | render every icon format from `resources/icon.svg` |
 | `make smoke` | drive the store with no window and no Electron at all |
+| `make storetest` | add and remove a store in a sandbox — the only code that deletes a tree |
+| `SMOKE_HOME=<dir> SMOKE_TOKEN=<bearer> npm run smoke` | the same, against a sandbox store and as a signed-in person |
 | `make uitest` | load the window once and report what rendered |
 | `SELFTEST_SHOT=shot.png npm run uitest` | the same, and the window photographs itself into that file |
 | `make test` | both test suites |
@@ -167,16 +247,94 @@ The npm scripts still work directly (`npm start`, `npm run dist:mac`) — the
 Makefile adds no logic of its own beyond the release step. Every script that runs the
 app builds first, so there is no way to test a stale bundle.
 
+### The icon
+
+`resources/icon.svg` is the source and the only file to edit; `make icons` renders the
+rest — `icon.png`, `icon.ico`, `icon.icns` and the `icons/` directory Linux packages
+want. Three committed binaries with no way to regenerate them is how an icon becomes
+something nobody dares change, so the render is a script rather than a memory.
+
+It needs `rsvg-convert` (`brew install librsvg`, `apt install librsvg2-bin`). The
+`.icns` step additionally needs `iconutil`, which exists only on macOS — elsewhere it
+is skipped with a warning and the committed `.icns` stands, which is what a mac build
+uses anyway.
+
+The mark is a **W with three lines running into it**: the product's initial, and what
+it is doing. It was drawn for the smallest size first — at 32px the W still reads and
+the lines survive as motion rather than as noise. A portal, a play triangle and a send
+arrow were all tried and all discarded: each already means something else.
+
+### Continuous integration
+
+`.woodpecker.yaml` builds the **Linux and Windows** packages, and on a tag attaches
+them to the Gitea release. The pipeline is in this repository rather than served by the
+update server's `/build/config` extension: that extension serves game-platform
+pipelines, which build a cartridge and publish it into the site's catalog, and this
+builds an application and publishes to a release.
+
+| Step | Image | What it does |
+|---|---|---|
+| `check` | `electronuserland/builder:22` | `npm ci`, type-check, lint, and the smoke test |
+| `linux` | `electronuserland/builder:22` | AppImage and deb |
+| `windows` | `electronuserland/builder:22-wine` | the NSIS installer and the portable exe, built through Wine |
+| `release` | `alpine` | on a tag only: **creates the release** and attaches what this pipeline built |
+
+**macOS stays a local build.** Apple's toolchain and its signing only exist on a Mac.
+So the whole of a release is:
+
+1. bump the version, commit, and push the tag: `git tag v1.4.0 && git push origin v1.4.0`;
+2. the pipeline builds Linux and Windows, **creates the release** with `RELEASE_NOTES.md`
+   as its body, and attaches those four packages;
+3. on a Mac, `make release` builds the macOS package and pushes it onto the same release.
+
+The window test is local as well: it needs a display and a store on the machine.
+
+The `release` step needs a **`gitea_token`** repository secret — a Gitea token with
+write access to this repository:
+
+```sh
+woodpecker-cli repo secret add --repository stores/warp-engine-client \
+  --name gitea_token --value <token> --event tag
+```
+
+Woodpecker does hand steps a forge credential of its own, and the script uses it when the
+secret is absent, but that is not something to rely on: a **manual** build has it and a
+build started by the **tag webhook** does not, which is how the first tag build failed —
+after building all four packages. Gitea takes either credential as `token …` or
+`Bearer …` depending on how it was issued, so the script probes which of the two `/user`
+accepts instead of assuming, and logs which one it used.
+
+There are two publishers on purpose: `scripts/release.sh` drives `tea`, which is logged
+in on a workstation, and `scripts/ci-upload.sh` speaks the API with whatever credential
+CI has. Each is short enough to read in full; one script with two ways to authenticate
+would not be.
+
+Both build steps end by checking what they produced: a package under 10 MB did not
+finish. That check exists because a half-finished Wine build leaves a stub *named* like
+the real installer — 162 KB of it — and `ls` is perfectly happy with that.
+
+**The Windows step cannot be rehearsed on an Apple Silicon Mac.** Wine assumes 4 KB
+memory pages and this host has 16 KB ones, so an emulated amd64 container dies with
+`anon_mmap_fixed: Assertion failed`. It is a property of the machine, not of the
+pipeline; the x86_64 runner is where that step is proven. The Linux step was rehearsed
+locally in the same image and produced both packages.
+
+The Windows installer is **not signed**: Windows will warn about an unknown publisher
+until there is a code-signing certificate. Linux packages carry no signature by
+convention.
+
 ### Publishing a release
 
 ```sh
 make release
 ```
 
-The tag comes from `package.json`, so `npm version patch` is the only place a
+This is the **macOS half** of a release; the Linux and Windows packages come from the
-version is set. The release is created if it is not there yet, and an attachment
+pipeline when the tag is pushed (see above). The tag comes from `package.json`, so
-whose name is already on it is **replaced** rather than refused — so a rebuild and
+`npm version patch` is the only place a version is set. The release is created if it is
-a second `make publish` lands rather than erroring.
+not there yet — either half can go first — and an attachment whose name is already on it
+is **replaced** rather than refused, so a rebuild and a second `make publish` lands
+rather than erroring.
 
 Release notes come from `RELEASE_NOTES.md` when the file is present, otherwise the
 release gets a one-line note. The repository is read from `origin`, so a fork
@@ -188,9 +346,14 @@ on its own: publishing 1.2.0 got *"invalid username, password or token"* on the
 second package while the first had just gone up with the same token, and the same
 command succeeded immediately afterwards.
 
-Package names contain a space — `WarpEngine Store-1.2.0-arm64.dmg` — so the list of
+Package names have no spaces in them — `WarpEngineClient-2.3.0-arm64.dmg` — because a
-files is passed one path per line rather than as one string; splitting it on
+space in a release asset is a space in every `curl`, script and shell command that ever
-whitespace is what broke the first attempt at publishing 1.1.0.
+touches it. The app itself is still called **WarpEngine Client**: that name is what
+appears in the Dock and in `/Applications`, and only the file names were the problem.
+
+The list of files is still passed one path per line rather than as one string, since a
+path given on the command line can contain a space even when a built one cannot;
+splitting it on whitespace is what broke the first attempt at publishing 1.1.0.
 
 It needs `tea` installed and logged in — the devarea repo has `make tea` for that.
 Overridable: `TAG`, `REPO`, `TEA_LOGIN`, `NOTES`, `DIST`.
@@ -208,14 +371,19 @@ own runtime.
 single-instance lock. Otherwise a copy the user already has open swallows the test
 process, which exits 0 and reads as a pass.
 
-Both test scripts accept a sandbox store instead of the real one, which is how
+The test scripts accept a sandbox store instead of the real one, which is how this
-this repository is tested without touching a working installation:
+repository is tested without touching a working installation:
 
 ```sh
 STORE_ROOT=/tmp/sandbox-root npm start
 SMOKE_HOME=/tmp/sandbox-root/ttg-desktop npm run smoke
 ```
 
+**`STORE_ROOT` replaces the search path rather than being added to the front of it.**
+It used to prepend, so a "sandboxed" run still listed the real stores and could switch
+to one; now that a store can also be *removed*, a sandbox that can reach a working
+installation is not a sandbox. `make storetest` relies on this.
+
 ### How it is put together
 
 TypeScript, in layers, with the dependency rule pointing inward. **[STRUCTURE.md](STRUCTURE.md)
@@ -224,9 +392,9 @@ is the map** — the layers, every pattern in use, and the naming rules. The sho
 | Layer | What lives there |
 |---|---|
 | `src/shared/` | the IPC channel table, the bridge contract, the DTOs, the two message bundles |
-| `src/domain/` | models, ports and errors — no Electron, no Node, no Python |
+| `src/domain/` | models, ports and errors — no Electron, no Node |
 | `src/application/` | services and the domain → DTO mappers |
-| `src/infrastructure/` | the adapters: the Python CLI, HTTP, the filesystem, Electron itself |
+| `src/infrastructure/` | the adapters: the store engine, HTTP, the archive reader, the filesystem, Electron itself |
 | `src/main/` | the window, the IPC controllers, the composition root, the self-test |
 | `src/preload/` | the bridge, bundled into one file — a sandboxed preload cannot require modules |
 | `src/renderer/` | the state store, the views and the renderer controllers |
@@ -247,17 +415,77 @@ Two properties are worth stating because they are what the layers buy:
 CSP that allows only its own script and stylesheet plus images over HTTPS. Links open
 in the real browser; the window itself never navigates.
 
-`PythonStoreCatalogGateway` is the only class that knows the store is a Python
+`NativeStoreCatalogGateway` is the engine behind the `StoreCatalogGateway` port, and
-program. It talks to the CLI through `--json`, which puts data on stdout and the
+`src/infrastructure/engine/` is the engine itself: the catalog client, the release
-human-readable log on stderr. That flag arrived with engine **1.1.0**, and the client
+picker, the host match, the payload installer, the three launcher writers and the state
-checks: an older store is met with an offer to refresh it rather than a failed call.
+file. Above the port nothing knows any of that exists, which is the point — a second
+host would be a second gateway, not a second code path.
 
-`STORE_ENGINES` has one entry today. The RetroArch store has the same command shape,
+`STORE_ENGINES` has one entry today. A RetroArch store writes playlists rather than
-so a second entry is the whole change needed to drive it too — that is why the table is
+menu entries, so it would be an entry there and a gateway of its own.
-there.
+
+### Reading a zip without a dependency
+
+Node has no zip reader and this application has **no runtime dependencies**, so
+`src/infrastructure/archive/ZipArchive.ts` is one over `node:zlib` — about 150 lines that
+walk the central directory, inflate `stored` and `deflate` entries, and restore the
+executable bit from each entry's external attributes. That last part is not a detail: the
+archive records it, and without it nothing the store installs can start.
+
+It reads what our own release pipeline produces and refuses the rest: a zip64 archive, an
+unknown compression method and a path that would escape the destination are all errors
+rather than best guesses.
+
+### Which WarpEngine served the catalog
+
+Every WarpEngine API response carries a `WarpEngine-Version` header, so the client knows
+the engine's age without asking. `SUPPORTED_WARP_ENGINE_VERSIONS` lists the versions this
+client is written against, and `selectCatalogDialect` maps each one to the `CatalogDialect`
+that reads its catalog shape.
+
+The switch over that list is exhaustive, which is the whole mechanism: adding a version to
+the array stops the build — in the type checker *and* in the linter — until somebody says
+what it reads like. A new engine version cannot arrive silently.
+
+| What the header says | What happens |
+|---|---|
+| a supported version | its dialect reads the catalog, and the log names it |
+| nothing at all | read as the oldest supported version, which is what an engine older than 0.4.0 is |
+| older than anything supported | the same, and the log says so |
+| newer than anything supported | the newest dialect is tried anyway, with a warning that titles may be missed |
+
+Three versions share one dialect today, because the catalog's shape has not changed
+across them. One class serving three versions is the honest way to say that.
 
 ## Verified, and not
 
+**2.2.0** — the registry record was cut back to a name and a catalog, so the whole
+install path was measured again against a local registry serving exactly that. The slug
+came out `teletypegames` from the catalog host, the home `teletypegames-desktop`, the
+games subfolder `teletypegames`, and installing the same record twice landed in the same
+home. A record carrying `config` and `storeRepositoryUrl` — the fields a stale client or a
+tampering renderer might still send — changed nothing, because neither exists in the model
+any more. The site side was migrated and its specs re-run; the frontend was built, which
+first required removing a dead `engines` list that had been failing `vue-tsc` on master.
+
+Older entries below describe what was verified for the version they name, and some of
+them predate the store engine moving into this application.
+
+The pipeline's commands were run in the same containers it uses, before the pipeline was
+committed: `electronuserland/builder:22` installs, type-checks, lints, passes the smoke
+test (registry reached, store skipped as it should be on a machine that has none) and
+produces the AppImage (128 MB) and the deb (100 MB). The Wine step could not be
+rehearsed here — see above — and the size check that guards it was tested against both
+outcomes: it rejects the 162 KB stub the failed Wine build left and accepts the two real
+Linux packages.
+
+A store with no repository was installed end to end from a local registry serving
+one record with `storeRepositoryUrl: null`: the id came out as `teletypegames`, the
+engine and the shared core downloaded, the written config had the three sections,
+engine 1.1.0 accepted it, and it listed the same ten titles the configured store
+does — then a hosted title synced into a sandbox and its menu entry appeared. The
+setup gate was also photographed on a machine with no store at all.
+
 The 1.3.0 refactor was measured rather than trusted: `make check` is clean — no type
 errors, no lint findings, both test suites green — the window was photographed before
 and after and the two are the same picture, and the packaged 1.3.0 bundle was run from

RELEASE_NOTES.md

@@ -1,63 +1,23 @@
-# WarpEngine Store 1.3.0
+# WarpEngine Client 2.5.1
 
-**TypeScript, in layers.** The client was one `main.js`, one `preload.js`, three files
+**The app has an icon.** Until now every build shipped the default Electron one —
-in `lib/` and one renderer script. It is now a typed application with the dependency
+`electron-builder` said so on every run, in a line easy to read past: *"default Electron
-rule pointing inward: `domain` (models, ports, errors) knows nothing about Electron,
+icon is used, reason=application icon is not set"*. A store you install games with
-Node or Python; `application` orchestrates it through those ports; `infrastructure`
+should not look like a framework demo in the Dock.
-holds the adapters — the Python CLI, HTTP, the filesystem, Electron itself — and the
-hosts (`main`, `preload`, `renderer`) sit on top. **[STRUCTURE.md](STRUCTURE.md)** is
-the map: every layer, every pattern in use, and the naming rules, written to be read
-before adding anything.
 
-Nothing about the window changed. Same side menu, same categories, same switcher, same
+The mark is a **W with three lines running into it**: the product's initial, and what it
-two languages — this release is the inside of the app.
+is doing. It uses the window's own palette, so the icon and the application it opens are
+the same object. It was drawn for the smallest size first — at 32px the W still reads
+and the lines survive as motion rather than as noise. A portal, a play triangle and a
+send arrow were each tried and each discarded: they already mean a loading spinner, a
+media player and a submit button.
 
-Two properties came out of the move, and both are worth having:
+`resources/icon.svg` is the source and the only file to edit. `make icons` renders the
+`.png`, the `.ico`, the `.icns` and the Linux size directory from it — three committed
+binaries with no way to regenerate them is how an icon becomes something nobody dares
+touch.
 
-- **The catalog can be driven with no window and no Electron at all.** `make smoke`
+The window also picks it up when run from source, where there is otherwise no icon to
-  assembles the same services against the same ports in a plain Node process. It was a
+carry and a dev run looks like a different application from the one being built.
-  script that reimplemented the bridge before; now it is a second composition root.
-- **The window never receives a filesystem path.** A title crosses the bridge without
-  one, and launching is asked for *by name* — the main process resolves what that means
-  from the store's own state. Nothing in the renderer can be talked into opening a path.
 
-**A strict linter, and types everywhere.** `strict` plus
+Nothing else changed: same store handling, same catalog, same sign-in.
-`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride`,
-`noPropertyAccessFromIndexSignature` and friends; typescript-eslint's
-`strictTypeChecked` and `stylisticTypeChecked` sets; explicit return types, parameter
-types and property types required even where inference would manage; exhaustive
-switches; no `any`, no `!`, no casts on foreign data — engine output and the registry
-go through readers that turn `unknown` into typed values. The naming patterns are
-enforced by `naming-convention` rather than trusted.
-
-Two things the types now catch that a person used to: a translation with a missing key
-does not compile, and a channel the preload does not implement does not compile.
-
-**New make targets:** `make build`, `make typecheck`, `make lint`, `make lint-fix` and
-`make check` — the gate, which runs the type-check, the linter and both test suites in
-that order, cheapest failure first. Every script that runs the app builds first, so a
-stale bundle cannot be tested.
-
-### Opening it on macOS
-
-Ad-hoc signed, **not notarised**, so macOS asks first:
-
-```sh
-xattr -dr com.apple.quarantine "/Applications/WarpEngine Store.app"
-```
-
-*Open Anyway* under **System Settings ▸ Privacy & Security** works as well.
-
-### What is attached
-
-**macOS arm64 only**, the machine this was built and verified on. Windows and Linux
-packages need a build on those platforms (`make dist-win` / `make dist-linux`).
-
-### Verified
-
-`make check` is clean: no type errors, no lint findings, the smoke test green against
-the real store and against a sandbox one, and the window test green with one store and
-with two — where it clicks the store that is not open and checks that the bar, the grid
-and the categories follow. The window was photographed before and after the refactor
-and the two are the same picture. The packaged app was run from the built bundle, not
-from a dev launch.

STRUCTURE.md

@@ -12,9 +12,9 @@ that reaches the window is a safety question, not a style one.
 
 ```
 shared      ← contracts and strings both sides need (no logic, no I/O)
-domain      ← models, ports, errors. Knows nothing about Electron, Node or Python
+domain      ← models, ports, errors. Knows nothing about Electron or Node
 application ← services and DTO mappers. Orchestrates the domain through its ports
-infrastructure ← adapters: the Python CLI, HTTP, the filesystem, Electron itself
+infrastructure ← adapters: the store engine, HTTP, the filesystem, Electron itself
 main        ← the Electron host: window, IPC controllers, composition root
 preload     ← the bridge, and only the bridge
 renderer    ← the window: state store, views, controllers
@@ -57,12 +57,19 @@ src/
     services/                 CatalogService, StoreSelectionService, …
     mappers/                  domain → DTO
   infrastructure/
-    process/                  Python: locating it, running it, reading its streams
+    engine/                   the store engine: catalog, releases, install, state
+      dialects/               one per WarpEngine version's catalog shape
+      ServiceDescriptorClient what the catalog's server says it offers (GET /api/service)
+      DeviceSignInClient      the device authorization grant, client side
+      launchers/              .desktop, .app bundle, .lnk — the three hosts
+    archive/                  ZipArchive: a zip reader over node:zlib
+    files/                    StoreFileSystem: atomic writes and the delete guard
     repositories/             the port implementations
-    mappers/                  engine JSON → domain
+    http/                     HttpTextClient, StoreHttpClient, HttpStatusError
-    http/                     HttpTextClient, HttpStatusError
     json/                     JsonRecord: reading data that came from elsewhere
-    electron/                 ApplicationEnvironment and GameLauncher adapters
+    config/                   BuildConfiguration: what was decided when this was packaged
+    electron/                 ApplicationEnvironment, GameLauncher, and the keychain
+                              credential store
   main/
     main.ts                   the entry point: one line of work
     ElectronApplication.ts    lifecycle, single instance, self-test mode
@@ -94,9 +101,13 @@ on this list, it belongs on this list.
 ### Ports and adapters
 
 `domain/ports/*` are interfaces; `infrastructure/*` implements them; the composition
-root is the only file that knows which implementation is in use. This is what makes
+root is the only file that knows which implementation is in use. This is what makes the
-the Python CLI, the registry HTTP call and Electron's `shell` replaceable — by a stub
+store engine, the registry HTTP call and Electron's `shell` replaceable — by a stub in a
-in a test, by a local endpoint in development, by a second engine later.
+test, by a local endpoint in development, by a second host's engine later.
+
+It has already paid for itself once: the engine used to be a Python CLI driven as a child
+process, and replacing it with one that runs in process was a new adapter behind the same
+port. Nothing in `application`, `main` or `renderer` changed shape for it.
 
 ### Repository and Gateway
 
@@ -104,8 +115,10 @@ Both are ports; the distinction is what is behind them.
 
 - **Repository** — a store of records this application owns the shape of:
   `InstalledStoreRepository`, `PreferencesRepository`, `StoreRegistryRepository`.
-- **Gateway** — another program or service with its own protocol:
+- **Gateway** — something with a protocol of its own, whether or not it is another
-  `StoreCatalogGateway` (the engine).
+  process: `StoreCatalogGateway` (the store engine), which today is
+  `NativeStoreCatalogGateway` in this application and was a Python CLI before it. The port
+  stays async because the work is: it downloads and unpacks.
 
 ### Service
 
@@ -118,8 +131,11 @@ controller or a view.
 Data crossing a boundary is a DTO, and a mapper converts. Two boundaries, two
 directions:
 
-- `infrastructure/mappers/Engine*Mapper` — engine JSON (snake_case) → domain model.
+- `infrastructure/engine/dialects/*` — catalog JSON → typed catalog records. These are
-  These are the only files that know the engine's field names.
+  the only files that know a WarpEngine version's field names.
+- `infrastructure/engine/StoreConfigurationReader`, `StoreStateRepository` — the two
+  snake_case files on disk → domain models. These are the only files that know the on-disk
+  field names, which are the shell engine's and stay that way.
 - `application/mappers/*DtoMapper` — domain model → DTO for the bridge. Decisions the
   window must not make live here: the absolute box-art URL, whether a title can be
   launched at all.
@@ -161,6 +177,11 @@ after what it changes and notifies afterwards; `RendererApplication` re-renders
 view from the new state. Views never read each other and never hold state, so a
 listing can be thrown away and rebuilt.
 
+Screens are state, not calls. The setup screen lives in the state as
+`gate: GatePresentation | null`, and that one field decides whether the gate or the
+grid is drawn. While it was two imperative calls the two disagreed: the gate went up
+and the empty-catalog line stayed on screen underneath it.
+
 ### Passive view
 
 `renderer/views/*` — a view takes its DOM nodes and callbacks in the constructor and
@@ -170,8 +191,8 @@ never calls the bridge.
 ### Error hierarchy with codes
 
 `DomainError` is abstract with a `code`; subclasses name a single failure
-(`PythonMissingError`, `StoreMissingError`, `EngineInvocationError`,
+(`StoreMissingError`, `EngineInvocationError`, `RegistryUnavailableError`, `BusyError`).
-`RegistryUnavailableError`, `BusyError`). The code is what crosses the bridge.
+The code is what crosses the bridge.
 
 ### Frozen constant tables
 
@@ -179,9 +200,18 @@ never calls the bridge.
 type, so a typo is a compile error and adding an entry is the whole change. This is
 the extension point for a second engine.
 
+### Build-time configuration
+
+`infrastructure/config/BuildConfiguration.ts` reads the packaged `package.json`, which is
+where a build records the registry it was made for (`warpEngine.registryUrl`, set by
+`make dist STORES_API=…`). Precedence is runtime environment, then build, then the
+built-in default — most specific first, and each one is a different audience: someone
+trying it out, someone shipping a client for another site, us.
+
 ### Untrusted-data readers
 
-Anything parsed from outside — engine stdout, the registry — goes through
+Anything parsed from outside — the catalog, a store's config, the state file, the
+registry — goes through
 `infrastructure/json/JsonRecord.ts`: `unknown` in, a typed value with a stated
 fallback out. No `as` casts on foreign data.
 
@@ -205,7 +235,7 @@ The names are a pattern, not a preference, and are checked by
 |---|---|---|
 | Domain model | plain noun, no suffix | `Game`, `InstalledStore` |
 | Port | `<Subject>Repository` / `Gateway` / `Locator` / `Installer` / `Launcher` | `StoreCatalogGateway` |
-| Adapter | `<Technology><Port>` | `PythonStoreCatalogGateway`, `HttpStoreRegistryRepository`, `FileSystemInstalledStoreRepository` |
+| Adapter | `<Technology><Port>` | `NativeStoreCatalogGateway`, `HttpStoreRegistryRepository`, `FileSystemInstalledStoreRepository` |
 | Service | `<Area>Service` | `CatalogService` |
 | Mapper | `<Subject>Mapper` / `<Subject>DtoMapper` | `EngineGameMapper`, `GameDtoMapper` |
 | Wire type | `<Subject>Dto` | `CatalogListingDto` |
@@ -213,7 +243,7 @@ The names are a pattern, not a preference, and are checked by
 | Renderer controller | `<Area>Controller` | `StoreController` |
 | View | `<Region>View` | `SideMenuView`, `GameCardView` |
 | Factory | `<Product>Factory` | `MainWindowFactory` |
-| Error | `<Cause>Error` | `PythonMissingError` |
+| Error | `<Cause>Error` | `StoreMissingError` |
 | Callback bag | `<Owner>Callbacks` | `SideMenuViewCallbacks` |
 | Type parameter | `T`-prefixed | `TResult`, `TElement` |
 
@@ -267,12 +297,18 @@ dependencies are declared here, and that is worth more than being strippable by
 the implementation to `preload.ts`, a `handle…` method to the right controller, and the
 behaviour to a service. The compiler names every file you missed.
 
-**A new engine (e.g. RetroArch).** Add an entry to `STORE_ENGINES`. The store
+**A new engine (e.g. RetroArch).** Add an entry to `STORE_ENGINES` — the store discovery,
-discovery, the home suffix and the launcher name all read from that table; the CLI has
+the home suffix and the launcher name all read from that table — and a `StoreCatalogGateway`
-the same command shape, so `PythonStoreCatalogGateway` is unchanged.
+implementation for that host. Everything above the port is unchanged.
 
-**A new field from the engine.** `EngineGameMapper` reads it into the model, `GameDto`
+**A new WarpEngine version.** Add it to `SUPPORTED_WARP_ENGINE_VERSIONS`. The build then
-and `GameDtoMapper` carry it across if the window needs it, and a view renders it.
+fails in `selectCatalogDialect` until the switch says which `CatalogDialect` reads it:
+either an existing one, when the catalog's shape did not change, or a new one beside
+`SoftwareListCatalogDialect`.
+
+**A new field from the catalog.** The dialect reads it into `CatalogSoftware`,
+`CatalogRelease` or `CatalogAsset`; `SelectedGame` and `Game` carry it if the survey or the
+window needs it; `GameDto` and `GameDtoMapper` take it across the bridge.
 
 **A new language.** Add `<Language>Messages.ts` typed as `MessageBundle`, add the code
 to `LOCALES` and the bundle to `TranslationCatalog`. A missing key will not compile.

package-lock.json

@@ -1,12 +1,12 @@
 {
-  "name": "warp-engine-desktop-gui",
+  "name": "warp-engine-client",
-  "version": "1.2.0",
+  "version": "2.5.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "warp-engine-desktop-gui",
+      "name": "warp-engine-client",
-      "version": "1.2.0",
+      "version": "2.5.1",
       "license": "MIT",
       "devDependencies": {
         "@types/node": "^26.2.0",

package.json

@@ -1,11 +1,11 @@
 {
-  "name": "warp-engine-desktop-gui",
+  "name": "warp-engine-client",
-  "productName": "WarpEngine Store",
+  "productName": "WarpEngine Client",
-  "version": "1.3.0",
+  "version": "2.5.1",
-  "description": "Graphical client for a WarpEngine desktop store: install the catalog into your own application menu.",
+  "description": "Graphical client for WarpEngine stores: install a catalog into your own application menu.",
   "license": "MIT",
   "author": "Teletype Games <games@teletype.hu>",
-  "homepage": "https://git.teletypegames.org/stores/warp-engine-desktop-gui",
+  "homepage": "https://git.teletypegames.org/stores/warp-engine-client",
   "main": "build/main/main.js",
   "engines": {
     "node": ">=22"
@@ -21,7 +21,10 @@
     "dist": "npm run build && electron-builder",
     "dist:mac": "npm run build && electron-builder --mac",
     "dist:win": "npm run build && electron-builder --win",
-    "dist:linux": "npm run build && electron-builder --linux"
+    "dist:linux": "npm run build && electron-builder --linux",
+    "storetest": "npm run build && node build/scripts/StoreLifecycleTest.js",
+    "test": "npm run smoke && npm run storetest && npm run uitest",
+    "icons": "node scripts/build-icons.mjs"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
@@ -34,7 +37,7 @@
   },
   "build": {
     "appId": "org.teletypegames.warpstore.gui",
-    "productName": "WarpEngine Store",
+    "productName": "WarpEngine Client",
     "files": [
       "build/**/*",
       "package.json"
@@ -44,25 +47,47 @@
       "target": [
         "dmg",
         "zip"
-      ]
+      ],
+      "artifactName": "WarpEngineClient-${version}-${arch}-mac.${ext}",
+      "icon": "resources/icon.icns"
+    },
+    "dmg": {
+      "artifactName": "WarpEngineClient-${version}-${arch}.${ext}"
     },
     "win": {
       "target": [
         "nsis",
         "portable"
-      ]
+      ],
+      "icon": "resources/icon.ico"
+    },
+    "nsis": {
+      "artifactName": "WarpEngineClient-Setup-${version}-${arch}.${ext}"
+    },
+    "portable": {
+      "artifactName": "WarpEngineClient-Portable-${version}-${arch}.${ext}"
     },
     "linux": {
       "category": "Game",
       "target": [
         "AppImage",
         "deb"
-      ]
+      ],
+      "icon": "resources/icons"
     },
-    "afterPack": "scripts/after-pack.js"
+    "appImage": {
+      "artifactName": "WarpEngineClient-${version}-${arch}.${ext}"
+    },
+    "afterPack": "scripts/after-pack.js",
+    "directories": {
+      "buildResources": "resources"
+    }
   },
   "allowScripts": {
     "electron@43.4.0": true,
     "esbuild@0.28.2": true
+  },
+  "warpEngine": {
+    "registryUrl": "https://teletypegames.org/api/stores"
   }
 }

resources/icon.svg

@@ -0,0 +1,44 @@
+<!--
+  The WarpEngine Client mark.
+
+  A W, and three lines running into it. The W is the product's initial; the lines are
+  what the W is doing — motion, read left to right, which is also why they are dimmer
+  than it is. Together they say "warp" without a spaceship, a portal or a play triangle,
+  each of which was tried and each of which turned out to mean something else already:
+  a send arrow, a loading spinner, a media player.
+
+  Drawn for the smallest size first. At 32px the W still reads and the lines survive as
+  a stack of motion rather than as noise; anything with an outline, a ring or fine
+  detail did not. The palette is the window's own, taken from src/renderer/style.css,
+  so the icon and the application it opens are the same object.
+
+  This file is the source. `npm run icons` renders every format from it; nothing here is
+  hand-edited binary.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024">
+  <defs>
+    <linearGradient id="tile" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#1e2937"/>
+      <stop offset="1" stop-color="#0d1116"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.5" cy="0.42" r="0.6">
+      <stop offset="0" stop-color="#37b98a" stop-opacity="0.24"/>
+      <stop offset="1" stop-color="#37b98a" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+
+  <!-- Inset by 7%: a macOS icon is a rounded tile with air around it, and the same
+       shape is what Windows and the Linux menus get. -->
+  <rect x="72" y="72" width="880" height="880" rx="200" fill="url(#tile)"/>
+  <rect x="72" y="72" width="880" height="880" rx="200" fill="url(#glow)"/>
+  <rect x="72" y="72" width="880" height="880" rx="200" fill="none" stroke="#2a3440" stroke-width="8"/>
+
+  <g stroke="#2c8f6c" stroke-width="48" stroke-linecap="round">
+    <path d="M196 400 H286"/>
+    <path d="M172 512 H274"/>
+    <path d="M196 624 H286"/>
+  </g>
+
+  <path d="M366 348 L462 676 L588 456 L714 676 L810 348" fill="none" stroke="#37b98a"
+        stroke-width="82" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

scripts/build-icons.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Render every icon format from resources/icon.svg.
+//
+// The point of this script is that the icon stays *editable*. Three committed binaries
+// with no way to regenerate them is how an icon becomes something nobody dares touch;
+// here the SVG is the source and everything else is output, so changing the mark is
+// changing one file and running this.
+//
+//   npm run icons
+//
+// Needs `rsvg-convert` (brew install librsvg). The .icns additionally needs `iconutil`,
+// which only exists on macOS — on Linux that step is skipped with a warning, because CI
+// builds Linux and Windows there and the committed .icns is what a mac build uses.
+
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const ROOT = path.resolve(import.meta.dirname, '..')
+const RESOURCES = path.join(ROOT, 'resources')
+const SOURCE = path.join(RESOURCES, 'icon.svg')
+
+/** Windows wants these; anything larger than 256 cannot go in an ICO as PNG anyway. */
+const ICO_SIZES = [16, 24, 32, 48, 64, 128, 256]
+
+/** What macOS asks for in an iconset, with the @2x names it insists on. */
+const ICNS_ENTRIES = [
+  [16, 'icon_16x16.png'], [32, 'icon_16x16@2x.png'],
+  [32, 'icon_32x32.png'], [64, 'icon_32x32@2x.png'],
+  [128, 'icon_128x128.png'], [256, 'icon_128x128@2x.png'],
+  [256, 'icon_256x256.png'], [512, 'icon_256x256@2x.png'],
+  [512, 'icon_512x512.png'], [1024, 'icon_512x512@2x.png']
+]
+
+function render (size, target) {
+  execFileSync('rsvg-convert', ['-w', String(size), '-h', String(size), SOURCE, '-o', target])
+}
+
+/**
+ * An ICO holding PNGs.
+ *
+ * The format allows it since Vista and every tool this project's packages reach has
+ * supported it for longer than that. Writing the container by hand is a few lines and
+ * saves a dependency on ImageMagick, which is not installed here and is not worth
+ * making a build requirement for 22 bytes of header per image.
+ */
+function writeIco (pngs, target) {
+  const header = Buffer.alloc(6)
+  header.writeUInt16LE(0, 0)
+  header.writeUInt16LE(1, 2) // 1 = icon
+  header.writeUInt16LE(pngs.length, 4)
+
+  const directory = Buffer.alloc(16 * pngs.length)
+  let offset = header.length + directory.length
+
+  pngs.forEach(({ size, data }, index) => {
+    const at = index * 16
+    // 0 means 256 in this field, which is the whole reason 256 is the largest size here.
+    directory.writeUInt8(size >= 256 ? 0 : size, at)
+    directory.writeUInt8(size >= 256 ? 0 : size, at + 1)
+    directory.writeUInt8(0, at + 2) // palette: none
+    directory.writeUInt8(0, at + 3) // reserved
+    directory.writeUInt16LE(1, at + 4) // colour planes
+    directory.writeUInt16LE(32, at + 6) // bits per pixel
+    directory.writeUInt32LE(data.length, at + 8)
+    directory.writeUInt32LE(offset, at + 12)
+    offset += data.length
+  })
+
+  fs.writeFileSync(target, Buffer.concat([header, directory, ...pngs.map((p) => p.data)]))
+}
+
+function buildIco () {
+  const temporary = fs.mkdtempSync(path.join(RESOURCES, '.ico-'))
+  try {
+    const pngs = ICO_SIZES.map((size) => {
+      const file = path.join(temporary, `${size}.png`)
+      render(size, file)
+      return { size, data: fs.readFileSync(file) }
+    })
+    writeIco(pngs, path.join(RESOURCES, 'icon.ico'))
+    console.log(`  icon.ico    ${ICO_SIZES.join(', ')}`)
+  } finally {
+    fs.rmSync(temporary, { recursive: true, force: true })
+  }
+}
+
+function buildIcns () {
+  const iconset = path.join(RESOURCES, 'icon.iconset')
+  fs.rmSync(iconset, { recursive: true, force: true })
+  fs.mkdirSync(iconset)
+  try {
+    for (const [size, name] of ICNS_ENTRIES) render(size, path.join(iconset, name))
+    execFileSync('iconutil', ['-c', 'icns', iconset, '-o', path.join(RESOURCES, 'icon.icns')])
+    console.log('  icon.icns   16 … 512@2x')
+  } finally {
+    fs.rmSync(iconset, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Linux takes a directory of sizes; electron-builder reads whatever is in it.
+ *
+ * Named `<size>x<size>.png`, which is the convention it expects and also what a
+ * `.desktop` entry's icon lookup walks.
+ */
+function buildLinuxIcons () {
+  const directory = path.join(RESOURCES, 'icons')
+  fs.rmSync(directory, { recursive: true, force: true })
+  fs.mkdirSync(directory)
+  const sizes = [16, 32, 48, 64, 128, 256, 512, 1024]
+  for (const size of sizes) render(size, path.join(directory, `${size}x${size}.png`))
+  console.log(`  icons/      ${sizes.join(', ')}`)
+}
+
+function main () {
+  if (!fs.existsSync(SOURCE)) {
+    console.error(`no ${path.relative(ROOT, SOURCE)} — the icon source is missing`)
+    process.exit(1)
+  }
+  try {
+    execFileSync('rsvg-convert', ['--version'], { stdio: 'ignore' })
+  } catch {
+    console.error('rsvg-convert is not installed (brew install librsvg / apt install librsvg2-bin)')
+    process.exit(1)
+  }
+
+  console.log('rendering icons from resources/icon.svg')
+  render(1024, path.join(RESOURCES, 'icon.png'))
+  console.log('  icon.png    1024')
+  buildLinuxIcons()
+  buildIco()
+
+  if (process.platform === 'darwin') {
+    buildIcns()
+  } else {
+    // Not fatal: the committed .icns is what a mac build uses, and only a Mac can make
+    // one. Saying so is better than a build that quietly ships the Electron default.
+    console.warn('  icon.icns   skipped — iconutil is macOS only; the committed one stands')
+  }
+}
+
+main()

scripts/ci-upload.sh

@@ -0,0 +1,115 @@
+#!/bin/sh
+# Attach built packages to the Gitea release for this tag.
+#
+# The local publisher (scripts/release.sh) drives `tea`, which is logged in
+# interactively on a workstation. CI has no such session: it has a token and curl. The
+# two are deliberately separate scripts rather than one with two ways to authenticate —
+# each is short enough to read in full.
+#
+#   scripts/ci-upload.sh                  every package in dist/
+#   scripts/ci-upload.sh dist/one.deb     just these
+#
+# Authenticates with the `gitea_token` secret when there is one, and otherwise with the
+# credential Woodpecker gives every step for cloning — so a release needs no secret.
+#
+# Creates the release when the tag has none, with RELEASE_NOTES.md as its body. That is
+# the flow: a `vX.Y.Z` tag starts this pipeline, which publishes the release with the
+# Linux and Windows packages in it, and the macOS package is pushed on top afterwards by
+# `make release` from a Mac.
+set -eu
+
+FORGE="${FORGE_API:-https://git.teletypegames.org/api/v1}"
+REPO="${REPO:-${CI_REPO:-}}"
+TAG="${TAG:-${CI_COMMIT_TAG:-}}"
+DIST="${DIST:-dist}"
+NOTES="${NOTES:-RELEASE_NOTES.md}"
+
+say() { echo "[ci-upload] $*"; }
+die() { echo "[ci-upload] error: $*" >&2; exit 1; }
+
+# Who to be. A `gitea_token` secret wins when there is one; otherwise the credential
+# Woodpecker already hands every step for cloning is used, which is an access token of
+# the repository's owner — so publishing needs no secret of its own. Gitea accepts a
+# personal access token as `token …` and an OAuth one as `Bearer …`, and which of the two
+# this is depends on how Woodpecker was set up, so the scheme is probed once rather than
+# assumed.
+TOKEN="${GITEA_TOKEN:-${CI_NETRC_PASSWORD:-}}"
+[ -n "$TOKEN" ] || die "no credential: set GITEA_TOKEN, or run this where Woodpecker provides CI_NETRC_PASSWORD"
+[ -n "$REPO" ] || die "cannot work out the repository — set REPO=owner/name"
+[ -n "$TAG" ] || die "cannot work out the tag — set TAG=v1.2.3"
+
+AUTH=""
+for scheme in token Bearer; do
+  if curl -fsS -H "Authorization: $scheme $TOKEN" "$FORGE/user" >/dev/null 2>&1; then
+    AUTH="Authorization: $scheme $TOKEN"
+    say "authenticated with the $scheme scheme"
+    break
+  fi
+done
+[ -n "$AUTH" ] || die "the credential was refused by $FORGE — it cannot read /user"
+
+api() {
+  method="$1"; path="$2"; shift 2
+  curl -fsS -X "$method" -H "$AUTH" "$FORGE$path" "$@"
+}
+
+# The list lives one path per line in a file and is read with `while IFS= read -r`. The
+# built package names have no spaces in them any more, but a path given on the command
+# line still can — and a single variable looped over with $list splits on the space and
+# uploads nothing, which is a silent way to publish a release with no assets.
+LIST="$(mktemp)"
+trap 'rm -f "$LIST"' EXIT
+if [ "$#" -gt 0 ]; then
+  for given in "$@"; do printf '%s\n' "$given"; done > "$LIST"
+else
+  # What this pipeline builds. The macOS packages are attached from the Mac that can
+  # sign them, so they are not listed here even when they happen to be present.
+  find "$DIST" -maxdepth 1 -type f \
+    \( -name '*.AppImage' -o -name '*.deb' -o -name '*.exe' \) 2>/dev/null | sort > "$LIST" || true
+fi
+[ -s "$LIST" ] || die "no Linux or Windows packages in $DIST"
+
+say "$REPO $TAG"
+
+# `curl -f` fails on the 404 a missing release answers, so the lookup is allowed to
+# fail and judged by what came back rather than by its exit status.
+release_id="$(curl -sS -H "$AUTH" "$FORGE/repos/$REPO/releases/tags/$TAG" | jq -r '.id // empty')"
+
+if [ -z "$release_id" ]; then
+  say "no release for $TAG yet — creating it"
+  title="$(jq -r '(.productName // .name) + " " + (.version)' package.json)"
+  notes=''
+  [ -f "$NOTES" ] && notes="$(cat "$NOTES")"
+  # The body goes through jq rather than string concatenation: release notes are
+  # markdown with quotes and newlines in them.
+  payload="$(jq -n --arg tag "$TAG" --arg title "$title" --arg body "$notes" \
+    '{tag_name: $tag, name: $title, body: $body, draft: false, prerelease: false}')"
+  release_id="$(api POST "/repos/$REPO/releases" \
+    -H 'Content-Type: application/json' -d "$payload" | jq -r '.id // empty')"
+  [ -n "$release_id" ] || die "the release for $TAG could not be created"
+else
+  say "the release already exists"
+fi
+
+while IFS= read -r asset; do
+  [ -n "$asset" ] || continue
+  [ -f "$asset" ] || die "no such file: $asset"
+  name="$(basename "$asset")"
+  encoded="$(printf '%s' "$name" | jq -sRr @uri)"
+
+  # Replace rather than refuse, so re-running a build lands.
+  existing="$(api GET "/repos/$REPO/releases/$release_id/assets" |
+    jq -r --arg name "$name" '.[] | select(.name == $name) | .id')"
+  for id in $existing; do
+    say "replacing $name"
+    api DELETE "/repos/$REPO/releases/$release_id/assets/$id" >/dev/null
+  done
+
+  say "uploading $name"
+  api POST "/repos/$REPO/releases/$release_id/assets?name=$encoded" \
+    -F "attachment=@$asset" >/dev/null
+done < "$LIST"
+
+say "done:"
+api GET "/repos/$REPO/releases/$release_id" |
+  jq -r '.assets[] | "  \(.name)  \(.size / 1000000 | floor) MB"'

scripts/ci-verify-packages.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+# Fail on a package that is too small to be one.
+#
+# Written after a Wine build died halfway and left a 162 KB stub named like the real
+# installer: `ls` was happy, the step passed, and the release would have carried a file
+# that cannot be run. An Electron package is ~100 MB — anything under a tenth of that
+# did not finish.
+#
+#   scripts/ci-verify-packages.sh '*.AppImage' '*.deb'
+set -eu
+
+DIST="${DIST:-dist}"
+MIN_BYTES="${MIN_BYTES:-10000000}"
+
+die() { echo "[verify] error: $*" >&2; exit 1; }
+
+[ "$#" -gt 0 ] || die "no patterns given"
+
+for pattern in "$@"; do
+  found=0
+  # One path per line: package names contain spaces.
+  find "$DIST" -maxdepth 1 -type f -name "$pattern" | sort > /tmp/verify-list
+  while IFS= read -r file; do
+    [ -n "$file" ] || continue
+    found=1
+    size="$(wc -c < "$file" | tr -d ' ')"
+    if [ "$size" -lt "$MIN_BYTES" ]; then
+      die "$file is only $size bytes — the build did not finish"
+    fi
+    echo "[verify] $(basename "$file"): $size bytes"
+  done < /tmp/verify-list
+  [ "$found" -eq 1 ] || die "no $pattern in $DIST"
+done
+
+rm -f /tmp/verify-list

scripts/release.sh

@@ -20,23 +20,14 @@ say() { echo "[release] $*"; }
 die() { echo "[release] error: $*" >&2; exit 1; }
 
 command -v tea >/dev/null 2>&1 || die "tea is not installed — see the devarea repo, 'make tea'"
-command -v python3 >/dev/null 2>&1 || die "python3 is required"
+command -v node >/dev/null 2>&1 || die "node is required"
 [ -f package.json ] || die "run this from the repository root"
 
-# Version and title in one go, through a heredoc rather than a quoted one-liner:
+# Version and title from package.json, read with node. This project needs no interpreter
-# nesting python quoting inside shell quoting inside a command substitution is how
+# beyond the one it already builds with — the app itself carries no Python any more, and
-# this produced an empty title on its first outing.
+# neither should the script that ships it.
-VERSION="$(python3 - <<'PY'
+VERSION="$(node -p 'require("./package.json").version')"
-import json
+TITLE="$(node -p 'const d = require("./package.json"); (d.productName || d.name) + " " + d.version')"
-print(json.load(open("package.json"))["version"])
-PY
-)"
-TITLE="$(python3 - <<'PY'
-import json
-d = json.load(open("package.json"))
-print((d.get("productName") or d["name"]) + " " + d["version"])
-PY
-)"
 TAG="${TAG:-v$VERSION}"
 [ -n "$VERSION" ] || die "cannot read the version from package.json"
 [ -n "$TITLE" ] || die "cannot work out a release title"
@@ -52,9 +43,10 @@ REPO="${REPO:-$(git remote get-url origin 2>/dev/null |
 #
 #   - the version filter, because dist/ keeps whatever earlier builds left there
 #     and a release would quietly get the previous version's files attached;
-#   - the spaces. "WarpEngine Store-1.1.0-arm64.dmg" has one, so the list lives one
+#   - the spaces. The built names have none since 2.3.0 — `WarpEngineClient-2.3.0-arm64.dmg`
-#     path per line in a file and is read with `while IFS= read -r`. Holding it in
+#     — but a path given as an argument still can, so the list stays one path per line in
-#     a single variable and looping over $list splits it on the space.
+#     a file, read with `while IFS= read -r`. Holding it in a single variable and looping
+#     over $list splits it on the space, and publishes nothing.
 LIST="$(mktemp)"
 trap 'rm -f "$LIST"' EXIT
 if [ "$#" -gt 0 ]; then
@@ -71,12 +63,12 @@ say "$REPO $TAG (version $VERSION), login $LOGIN"
 # The release id, or empty when there is no such tag. `tea api` exits 0 even for a
 # 404 — it answers {"message":"not found"} — so the body is what has to be read.
 release_id() {
-  tea api "/repos/$REPO/releases/tags/$TAG" 2>/dev/null | python3 -c '
+  tea api "/repos/$REPO/releases/tags/$TAG" 2>/dev/null | node -e '
-import json, sys
+try {
-try:
+  console.log(JSON.parse(require("fs").readFileSync(0, "utf8")).id || "")
-    print(json.load(sys.stdin).get("id") or "")
+} catch {
-except Exception:
+  // Not JSON, or no such release: an empty answer is the "no release yet" case.
-    pass
+}
 '
 }
 
@@ -103,13 +95,12 @@ RELEASE_ID="$(release_id)"
 # refusing is what makes a rebuild-and-upload repeatable. Called before every
 # attempt, so a retry cannot leave two copies behind.
 drop_existing() {
-  ids="$(tea api "/repos/$REPO/releases/$RELEASE_ID/assets" | python3 -c "
+  ids="$(tea api "/repos/$REPO/releases/$RELEASE_ID/assets" | node -e '
-import json, sys
+const name = process.argv[1]
-name = sys.argv[1]
+for (const asset of JSON.parse(require("fs").readFileSync(0, "utf8"))) {
-for a in json.load(sys.stdin):
+  if (asset.name === name) console.log(asset.id)
-    if a['name'] == name:
+}
-        print(a['id'])
+' -- "$1")"
-" "$1")"
   for id in $ids; do
     say "replacing $1"
     tea api -X DELETE "/repos/$REPO/releases/$RELEASE_ID/assets/$id" >/dev/null
@@ -120,7 +111,7 @@ while IFS= read -r asset; do
   [ -n "$asset" ] || continue
   [ -f "$asset" ] || die "no such file: $asset"
   name="$(basename "$asset")"
-  size="$(python3 -c "import os,sys; print(f'{os.path.getsize(sys.argv[1])/1e6:.0f} MB')" "$asset")"
+  size="$(node -e 'console.log((require("fs").statSync(process.argv[1]).size / 1e6).toFixed(0) + " MB")' -- "$asset")"
 
   # Retried, because a 100 MB upload does fail on its own: publishing 1.2.0 got
   # "invalid username, password or token" on the second package while the first
@@ -140,9 +131,10 @@ while IFS= read -r asset; do
 done < "$LIST"
 
 say "done:"
-tea api "/repos/$REPO/releases/$RELEASE_ID" | python3 -c "
+tea api "/repos/$REPO/releases/$RELEASE_ID" | node -e '
-import json, sys
+const release = JSON.parse(require("fs").readFileSync(0, "utf8"))
-r = json.load(sys.stdin)
+for (const asset of release.assets || []) {
-for a in r.get('assets') or []:
+  console.log(`  ${asset.name}  ${(asset.size / 1e6).toFixed(0)} MB`)
-    print(f\"  {a['name']}  {a['size']/1e6:.0f} MB\")
+}
-print(f\"  {r['html_url']}\")"
+console.log(`  ${release.html_url}`)
+'

src/application/mappers/EngineVersionDtoMapper.ts

@@ -1,8 +0,0 @@
-import type { EngineVersion } from '../../domain/models/EngineVersion'
-import type { EngineVersionDto } from '../../shared/contracts/dto/EngineVersionDto'
-
-export class EngineVersionDtoMapper {
-  public toDto (version: EngineVersion): EngineVersionDto {
-    return { text: version.text, supported: version.supported }
-  }
-}

src/application/mappers/GameDtoMapper.ts

@@ -1,3 +1,4 @@
+import { readAccessVerdict, type CatalogPrice } from '../../domain/models/CatalogAccess'
 import type { Game } from '../../domain/models/Game'
 import type { GameDto } from '../../shared/contracts/dto/GameDto'
 
@@ -6,10 +7,11 @@ const ABSOLUTE_URL = /^https?:\/\//
 /**
  * A title as the window may see it.
  *
- * Two decisions live here rather than in the renderer: the box art is resolved
+ * Three decisions live here rather than in the renderer: the box art is resolved
- * against the catalog's base URL, and whether a title can be launched is answered
+ * against the catalog's base URL, whether a title can be launched is answered here —
- * here — so the window never receives a filesystem path it could be talked into
+ * so the window never receives a filesystem path it could be talked into opening —
- * opening.
+ * and the catalog's access block is reduced to a verdict and a printed price, because
+ * a view that had to reason about entitlement is a view with a rule in it.
  */
 export class GameDtoMapper {
   public toDto (game: Game, catalogBaseUrl: string): GameDto {
@@ -26,7 +28,13 @@ export class GameDtoMapper {
       installed: game.installed,
       updateAvailable: game.updateAvailable,
       installedVersion: game.installedVersion,
-      launchable: this.isLaunchable(game)
+      launchable: this.isLaunchable(game),
+      installable: game.installable,
+      unavailableReason: game.unavailableReason,
+      unavailableDetail: game.unavailableDetail,
+      accessVerdict: readAccessVerdict(game.access),
+      priceLabel: formatPrice(game.access?.price ?? null),
+      purchaseUrl: game.access?.purchaseUrl ?? null
     }
   }
 
@@ -46,3 +54,25 @@ export class GameDtoMapper {
     return game.menuEntryPath !== null || game.executablePath !== null
   }
 }
+
+/**
+ * A price as a person reads it, in the currency the catalog named.
+ *
+ * `Intl` with the *catalog's* currency and the system locale: the store decides what it
+ * charges in, the reader's machine decides where the symbol and the separators go.
+ * There is no conversion here and there must not be — inventing an exchange rate would
+ * be quoting a price nobody agreed to.
+ */
+function formatPrice (price: CatalogPrice | null): string | null {
+  if (price === null) return null
+  if (price.amountCents <= 0) return null
+
+  try {
+    return new Intl.NumberFormat(undefined, {
+      style: 'currency', currency: price.currency
+    }).format(price.amountCents / 100)
+  } catch {
+    // An unknown currency code: better the number and the code than nothing at all.
+    return `${(price.amountCents / 100).toFixed(2)} ${price.currency}`
+  }
+}

src/application/mappers/RegistryStoreDtoMapper.ts

@@ -7,7 +7,6 @@ export class RegistryStoreDtoMapper {
     return {
       name: store.name,
       catalogUrl: store.catalogUrl,
-      storeRepositoryUrl: store.storeRepositoryUrl,
       storeId: deriveStoreId(store)
     }
   }
@@ -18,10 +17,6 @@ export class RegistryStoreDtoMapper {
 
   /** The window hands a record straight back when asking for an install. */
   public toModel (dto: RegistryStoreDto): RegistryStore {
-    return {
+    return { name: dto.name, catalogUrl: dto.catalogUrl }
-      name: dto.name,
-      catalogUrl: dto.catalogUrl,
-      storeRepositoryUrl: dto.storeRepositoryUrl
-    }
   }
 }

src/application/services/AccountService.ts

@@ -0,0 +1,112 @@
+import {
+  NO_ACCOUNT, type SignInOutcome, type SignInPrompt, type StoreAccount
+} from '../../domain/models/StoreAccount'
+import type { StoreCatalogGateway } from '../../domain/ports/StoreCatalogGateway'
+import type { StoreSelectionService } from './StoreSelectionService'
+
+/** A sign-in that is under way: what to show, and how it ended. */
+export interface SignInSession {
+  readonly prompt: SignInPrompt
+  readonly finished: Promise<SignInResult>
+}
+
+export interface SignInResult {
+  readonly outcome: SignInOutcome
+  readonly account: StoreAccount
+}
+
+/**
+ * Signing in to the store that is open, and out of it again.
+ *
+ * The waiting lives here rather than in the gateway because it is orchestration: a loop
+ * with a cancel and a deadline in it, over a port that only knows how to ask once. That
+ * split is also what keeps the port testable without a clock.
+ *
+ * One sign-in at a time, per application rather than per store: a second one started
+ * while the first is waiting would leave two loops racing to write the same token, and
+ * a person can only be at one browser tab anyway.
+ */
+export class AccountService {
+  private cancelled = false
+  private active: SignInSession | null = null
+
+  public constructor (
+    private readonly catalogGateway: StoreCatalogGateway,
+    private readonly selection: StoreSelectionService
+  ) {}
+
+  /** Null where no store is open — the window asks before anything is chosen. */
+  public async readAccount (): Promise<StoreAccount> {
+    const store = this.selection.findCurrentStore()
+    if (store === null) return NO_ACCOUNT
+
+    return await this.catalogGateway.readAccount(store)
+  }
+
+  /**
+   * Ask the store for a code, then keep polling until somebody answers.
+   *
+   * Returns as soon as there is something to show: the code has to be on screen while
+   * the polling happens, and a person cannot answer a code they have not seen yet.
+   */
+  public async beginSignIn (clientName: string): Promise<SignInSession> {
+    if (this.active !== null) return this.active
+
+    const store = this.selection.requireCurrentStore()
+    const prompt = await this.catalogGateway.requestSignIn(store, clientName)
+    this.cancelled = false
+
+    const session: SignInSession = { prompt, finished: this.awaitAnswer(prompt) }
+    this.active = session
+    return session
+  }
+
+  /** Give up waiting. The code stays valid at the server until it expires by itself. */
+  public cancelSignIn (): void {
+    this.cancelled = true
+  }
+
+  public async signOut (): Promise<StoreAccount> {
+    const store = this.selection.findCurrentStore()
+    if (store === null) return NO_ACCOUNT
+
+    this.cancelSignIn()
+    return await this.catalogGateway.signOut(store)
+  }
+
+  private isCancelled (): boolean {
+    return this.cancelled
+  }
+
+  private async awaitAnswer (prompt: SignInPrompt): Promise<SignInResult> {
+    const store = this.selection.requireCurrentStore()
+    const deadline = Date.now() + prompt.expiresInSeconds * 1000
+
+    try {
+      while (!this.isCancelled()) {
+        await delay(prompt.intervalSeconds * 1000)
+        // Read through a method, not the field: cancelling happens *during* the delay
+        // above, and a flow analysis that only sees the loop condition concludes this
+        // can never be true.
+        if (this.isCancelled()) break
+        // The server's own expiry is the authority; this one only stops the loop when
+        // the server has stopped answering at all.
+        if (Date.now() > deadline) return { outcome: 'expired', account: await this.readAccount() }
+
+        const result = await this.catalogGateway.pollSignIn(store, prompt.deviceCode)
+        if (result.state === 'approved') return { outcome: 'signedIn', account: result.account }
+        if (result.state === 'denied') return { outcome: 'denied', account: result.account }
+        if (result.state === 'expired') return { outcome: 'expired', account: result.account }
+      }
+      return { outcome: 'cancelled', account: await this.readAccount() }
+    } finally {
+      this.active = null
+    }
+  }
+}
+
+async function delay (milliseconds: number): Promise<void> {
+  await new Promise<void>((resolve: () => void): void => {
+    setTimeout((): void => { resolve() }, milliseconds)
+  })
+}

src/application/services/ApplicationStateService.ts

@@ -1,10 +1,7 @@
-import { MINIMUM_ENGINE_VERSION, formatVersion } from '../../domain/models/EngineVersion'
 import type { InstalledStore } from '../../domain/models/InstalledStore'
 import type { ApplicationEnvironment } from '../../domain/ports/ApplicationEnvironment'
-import type { PythonRuntimeLocator } from '../../domain/ports/PythonRuntimeLocator'
 import type { AppStateDto } from '../../shared/contracts/dto/AppStateDto'
 import { TranslationCatalog } from '../../shared/i18n/TranslationCatalog'
-import { EngineVersionDtoMapper } from '../mappers/EngineVersionDtoMapper'
 import { InstalledStoreDtoMapper } from '../mappers/InstalledStoreDtoMapper'
 import type { PreferencesService } from './PreferencesService'
 import type { StoreProvisioningService } from './StoreProvisioningService'
@@ -13,39 +10,32 @@ import type { StoreSelectionService } from './StoreSelectionService'
 /**
  * Everything the window needs before it can paint anything, in one answer.
  *
- * One call rather than six, because the first frame should not be a sequence of
+ * One call rather than six, because the first frame should not be a sequence of round
- * round trips — and because the decisions the window makes from it (no Python, no
+ * trips. There is one decision left in it — whether a store is set up yet — now that
- * store, an engine too old) all depend on each other.
+ * the engine ships with the application and cannot be missing or out of date.
  */
 export class ApplicationStateService {
   public constructor (
     private readonly preferences: PreferencesService,
     private readonly selection: StoreSelectionService,
     private readonly provisioning: StoreProvisioningService,
-    private readonly pythonLocator: PythonRuntimeLocator,
     private readonly environment: ApplicationEnvironment,
     private readonly translations: TranslationCatalog = new TranslationCatalog(),
-    private readonly storeMapper: InstalledStoreDtoMapper = new InstalledStoreDtoMapper(),
+    private readonly storeMapper: InstalledStoreDtoMapper = new InstalledStoreDtoMapper()
-    private readonly engineMapper: EngineVersionDtoMapper = new EngineVersionDtoMapper()
   ) {}
 
   public readState (): AppStateDto {
     const locale = this.preferences.readLocale()
     const stores = this.selection.listStores()
     const current: InstalledStore | null = this.selection.findCurrentStore()
-    const engine = current === null ? null : this.selection.findEngineVersion(current)
-    const runtime = this.pythonLocator.findRuntime()
 
     return {
       locale,
       locales: this.translations.locales,
       messages: this.translations.readBundle(locale),
       navigationOpen: this.preferences.readNavigationOpen(),
-      pythonVersion: runtime === null ? null : runtime.version,
       currentStore: current === null ? null : this.storeMapper.toDto(current),
       stores: this.storeMapper.toDtoList(stores),
-      engine: engine === null ? null : this.engineMapper.toDto(engine),
-      minimumEngineVersion: formatVersion(MINIMUM_ENGINE_VERSION),
       registryUrl: this.provisioning.registryUrl,
       defaultStoreRoot: this.selection.readDefaultStoreRoot(),
       appVersion: this.environment.readVersion()

src/application/services/PreferencesService.ts

@@ -45,6 +45,18 @@ export class PreferencesService {
     this.merge({ storeHome: home })
   }
 
+  /**
+   * Stop remembering a store, for when it is no longer on the machine.
+   *
+   * The key is removed rather than blanked: an empty string would be a remembered home
+   * that matches nothing, and every reader would have to know to treat it as absent.
+   */
+  public forgetStoreHome (): void {
+    const { storeHome, ...rest } = this.repository.read()
+    void storeHome
+    this.repository.write(rest)
+  }
+
   private merge (changes: Preferences): void {
     this.repository.write({ ...this.repository.read(), ...changes })
   }

src/application/services/StoreProvisioningService.ts

@@ -4,6 +4,7 @@ import type { RegistryStore } from '../../domain/models/RegistryStore'
 import { deriveStoreId } from '../../domain/models/StoreIdentity'
 import type { InstalledStoreRepository } from '../../domain/ports/InstalledStoreRepository'
 import type { StoreEngineInstaller } from '../../domain/ports/StoreEngineInstaller'
+import type { StoreCatalogGateway } from '../../domain/ports/StoreCatalogGateway'
 import type { StoreRegistryRepository } from '../../domain/ports/StoreRegistryRepository'
 import type { StoreSelectionService } from './StoreSelectionService'
 
@@ -19,7 +20,8 @@ export class StoreProvisioningService {
     private readonly registry: StoreRegistryRepository,
     private readonly installer: StoreEngineInstaller,
     private readonly stores: InstalledStoreRepository,
-    private readonly selection: StoreSelectionService
+    private readonly selection: StoreSelectionService,
+    private readonly catalogGateway: StoreCatalogGateway
   ) {}
 
   public get registryUrl (): string {
@@ -30,6 +32,14 @@ export class StoreProvisioningService {
     return this.registry.listStores()
   }
 
+  /**
+   * Install the chosen store.
+   *
+   * The window's choice is taken at face value, which is safe because a record is only a
+   * name and a catalog: there is no path in it and nothing that decides what may be
+   * deleted. The store's own configuration is written by the installer from the engine's
+   * defaults, so the renderer cannot influence where anything lands.
+   */
   public async installStore (
     store: RegistryStore,
     progress?: EngineProgressListener
@@ -38,4 +48,80 @@ export class StoreProvisioningService {
     const installed = await this.installer.installEngine(home, store, progress)
     return this.selection.adoptStore(installed)
   }
+
+  /**
+   * A catalog the registry does not offer.
+   *
+   * Nothing about installing changes — a record is still a name and a catalog, and the
+   * configuration still comes from the engine's defaults. What differs is only where
+   * the two fields came from, which is why this hands the same record to the same
+   * method rather than growing a second path.
+   *
+   * The name is derived from the host when none is given: it is a label for the picker,
+   * and asking somebody to invent one before they can try a URL is a question with no
+   * useful answer.
+   */
+  public async installCatalog (
+    catalogUrl: string,
+    name: string | null = null,
+    progress?: EngineProgressListener
+  ): Promise<InstalledStore> {
+    const url = normaliseCatalogUrl(catalogUrl)
+    const chosen: RegistryStore = { name: name?.trim() ?? '', catalogUrl: url }
+    return await this.installStore(
+      chosen.name.length > 0 ? chosen : { ...chosen, name: readHostName(url) },
+      progress
+    )
+  }
+
+  /**
+   * Remove a store: everything it installed, then the store itself.
+   *
+   * Whichever store is open afterwards is decided by re-reading the disk rather than
+   * guessed at here — removing the open one has to leave the window pointing at
+   * something that exists, and that answer lives in one place.
+   */
+  public async removeStore (store: InstalledStore, progress?: EngineProgressListener): Promise<void> {
+    await this.catalogGateway.removeStore(store, progress)
+    this.selection.forgetStore(store)
+  }
+}
+
+/**
+ * What somebody typed, as a URL this can be used as.
+ *
+ * Two liberties taken on purpose, because both are what a person means: a bare host
+ * gets https, and a trailing slash goes. Anything still unparseable is refused here
+ * rather than at the first fetch — a store home written for a bad URL is a directory
+ * somebody has to find and delete.
+ */
+function normaliseCatalogUrl (value: string): string {
+  const trimmed = value.trim()
+  if (trimmed.length === 0) throw new Error('a catalog address is needed')
+
+  const withScheme = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`
+  let parsed: URL
+  try {
+    parsed = new URL(withScheme)
+  } catch {
+    throw new Error(`not a usable address: ${value}`)
+  }
+  // A URL can parse and still have no host — `http://` does. That one used to slip
+  // through and become a store called "http", because the trailing slashes were being
+  // stripped *before* the scheme was checked, turning `http://` into `http:` and then
+  // into `https://http:`.
+  if (parsed.hostname.length === 0) throw new Error(`not a usable address: ${value}`)
+
+  // Rebuilt from the parsed URL rather than from the string: it drops the query and
+  // the fragment — a catalog is a base address, not a request — and settles the
+  // trailing slash in one place instead of at every call site that appends a path.
+  return `${parsed.origin}${parsed.pathname}`.replace(/\/+$/, '')
+}
+
+function readHostName (catalogUrl: string): string {
+  try {
+    return new URL(catalogUrl).hostname.replace(/^www\./, '')
+  } catch {
+    return catalogUrl
+  }
 }

src/application/services/StoreSelectionService.ts

@@ -1,8 +1,6 @@
 import { StoreMissingError } from '../../domain/errors/StoreMissingError'
-import type { EngineVersion } from '../../domain/models/EngineVersion'
 import type { InstalledStore } from '../../domain/models/InstalledStore'
 import type { InstalledStoreRepository } from '../../domain/ports/InstalledStoreRepository'
-import type { StoreCatalogGateway } from '../../domain/ports/StoreCatalogGateway'
 import type { PreferencesService } from './PreferencesService'
 
 /**
@@ -18,7 +16,6 @@ export class StoreSelectionService {
 
   public constructor (
     private readonly stores: InstalledStoreRepository,
-    private readonly catalogGateway: StoreCatalogGateway,
     private readonly preferences: PreferencesService
   ) {}
 
@@ -43,6 +40,13 @@ export class StoreSelectionService {
     return store
   }
 
+  /** The store at this home, or an error naming it. Does not change what is open. */
+  public requireStoreAt (home: string): InstalledStore {
+    const store = this.stores.findByHome(home)
+    if (store === null) throw new StoreMissingError(home)
+    return store
+  }
+
   public selectStore (home: string): InstalledStore {
     const store = this.stores.findByHome(home)
     if (store === null) throw new StoreMissingError(home)
@@ -59,12 +63,17 @@ export class StoreSelectionService {
   }
 
   /**
-   * The engine version of a store, checked per store rather than once: two stores
+   * Forget a store that is no longer on the machine.
-   * on one machine can be at different versions, and the one being switched to may
+   *
-   * be the older one.
+   * The next store is not chosen here: `findCurrentStore` re-reads the disk and applies
+   * the same rule it always does, so "which store is open" has exactly one answer in
+   * one place. Clearing the remembered home first is what stops it choosing the one
+   * that has just been deleted.
    */
-  public findEngineVersion (store: InstalledStore): EngineVersion | null {
+  public forgetStore (store: InstalledStore): void {
-    return this.catalogGateway.readEngineVersion(store)
+    if (this.preferences.readStoreHome() === store.home) this.preferences.forgetStoreHome()
+    if (this.current?.home === store.home) this.current = null
+    this.findCurrentStore()
   }
 
   public readDefaultStoreRoot (): string {

src/domain/errors/PythonMissingError.ts

@@ -1,9 +0,0 @@
-import { DomainError } from './DomainError'
-
-export class PythonMissingError extends DomainError {
-  public override readonly code: string = 'PYTHON_MISSING'
-
-  public constructor () {
-    super('python3 was not found on this machine')
-  }
-}

src/domain/models/CatalogAccess.ts

@@ -0,0 +1,42 @@
+/**
+ * What a catalog says about getting one title.
+ *
+ * The vocabulary is the engine's and deliberately generic — `gated`, `entitled`, a
+ * price. One client reads many catalogs, so a field named after what a particular shop
+ * calls the thing it sells is a field that works in exactly one shop.
+ *
+ * Absent (`null` where this appears) is its own answer: an engine too old to have an
+ * opinion. That is not the same as "not gated", and only one of the two is a reason to
+ * offer somebody a sign-in.
+ */
+export interface CatalogAccess {
+  /** Downloading needs an entitlement. */
+  readonly gated: boolean
+  /** For the signed-in caller; null when nobody was signed in to ask about. */
+  readonly entitled: boolean | null
+  readonly price: CatalogPrice | null
+  /** Where a person goes to get it. Absolute — it opens in their own browser. */
+  readonly purchaseUrl: string | null
+  /** Where a hosted build is played, when the catalog serves it somewhere of its own. */
+  readonly webUrl: string | null
+}
+
+export interface CatalogPrice {
+  readonly amountCents: number
+  readonly currency: string
+}
+
+/**
+ * Can this caller install this title?
+ *
+ * Three answers, because the middle one is real: yes; no, and here is where to buy it;
+ * and "the catalog would tell you if you signed in". A client that collapsed the last
+ * two would either hide a title somebody owns or offer to sell them one they have.
+ */
+export type AccessVerdict = 'open' | 'entitled' | 'purchasable' | 'signInRequired'
+
+export function readAccessVerdict (access: CatalogAccess | null): AccessVerdict {
+  if (access?.gated !== true) return 'open'
+  if (access.entitled === true) return 'entitled'
+  return access.entitled === false ? 'purchasable' : 'signInRequired'
+}

src/domain/models/CatalogListing.ts

@@ -1,4 +1,5 @@
 import type { Game } from './Game'
+import type { StoreAccount } from './StoreAccount'
 import type { StorePaths } from './StorePaths'
 
 /** One reading of a store's catalog. */
@@ -6,4 +7,13 @@ export interface CatalogListing {
   readonly games: readonly Game[]
   readonly skipped: readonly string[]
   readonly paths: StorePaths | null
+  /**
+   * Where this machine stands with the store, as of this reading.
+   *
+   * Part of the listing rather than a call of its own because it is the same answer
+   * from the same request: the catalog was fetched with whatever credential we hold,
+   * and what it said about entitlements is only meaningful next to whether anybody was
+   * signed in when it said it.
+   */
+  readonly account: StoreAccount
 }

src/domain/models/DesktopLayout.ts

@@ -0,0 +1,39 @@
+/**
+ * The three places a desktop store writes, resolved for this machine.
+ *
+ * `installRoot` holds the payloads and `menuDirectory` the launchers the user
+ * actually sees. `sources` records where each answer came from — a default, the
+ * config or an override — because "why is my menu entry there" is the first
+ * question anyone asks of a store that writes outside its own folder.
+ */
+export interface DesktopLayout {
+  readonly operatingSystem: string
+  readonly installRoot: string
+  readonly menuDirectory: string
+  readonly iconDirectory: string | null
+  readonly sources: Readonly<Record<string, string>>
+}
+
+/** Where each OS keeps installed programs and its application menu. */
+export const OPERATING_SYSTEM_PATHS: Readonly<Record<string, Readonly<Record<string, string | null>>>> = {
+  linux: {
+    installRoot: '$XDG_DATA_HOME|~/.local/share',
+    menuDirectory: '$XDG_DATA_HOME|~/.local/share/applications',
+    iconDirectory: '$XDG_DATA_HOME|~/.local/share/icons'
+  },
+  darwin: {
+    installRoot: '~/Library/Application Support',
+    menuDirectory: '~/Applications',
+    iconDirectory: null
+  },
+  windows: {
+    installRoot: '$LOCALAPPDATA|~/AppData/Local',
+    menuDirectory: '$APPDATA|~/AppData/Roaming/Microsoft/Windows/Start Menu/Programs',
+    iconDirectory: null
+  }
+}
+
+/** A file name the OS will accept, from a human title. */
+export function toSafeFileName (text: string): string {
+  return text.trim().replace(/[\\/:*?"<>|]/g, '_') || 'game'
+}

src/domain/models/EngineVersion.ts

@@ -1,34 +0,0 @@
-/**
- * The engine version this client found, and whether it can drive it.
- *
- * `--json` arrived with engine 1.1.0. An older engine is not broken, it simply
- * cannot be driven from a window — and it will be met in the wild, because the CLI
- * shipped before this client did.
- */
-export interface EngineVersion {
-  readonly text: string
-  readonly numbers: readonly number[] | null
-  readonly supported: boolean
-}
-
-export const MINIMUM_ENGINE_VERSION: readonly number[] = [1, 1, 0]
-
-export function parseVersionNumbers (text: string): readonly number[] | null {
-  const match = /(\d+)\.(\d+)\.(\d+)/.exec(text)
-  return match ? match.slice(1, 4).map((part: string): number => Number(part)) : null
-}
-
-export function isAtLeast (version: readonly number[] | null, minimum: readonly number[]): boolean {
-  if (version === null) return false
-  for (let index = 0; index < minimum.length; index += 1) {
-    const found = version[index] ?? 0
-    const needed = minimum[index] ?? 0
-    if (found > needed) return true
-    if (found < needed) return false
-  }
-  return true
-}
-
-export function formatVersion (numbers: readonly number[]): string {
-  return numbers.join('.')
-}

src/domain/models/Game.ts

@@ -1,6 +1,17 @@
+import type { CatalogAccess } from './CatalogAccess'
+
 /** How a title runs: unpacked on this machine, or served as a web build. */
 export type GameMode = 'app' | 'web'
 
+/**
+ * Why a title cannot be installed here, as the engine codes it.
+ *
+ * `platformOff` is the store not carrying that platform at all — a C64 cartridge on a
+ * desktop — and the other three are about this machine or this catalog: no asset kind
+ * for the os and architecture, no release carrying it, or the adapter refusing it.
+ */
+export type UnavailableReason = 'platformOff' | 'hostAsset' | 'noAsset' | 'vetoed'
+
 /**
  * A catalog entry, with what the store did about it on this machine.
  *
@@ -24,4 +35,20 @@ export interface Game {
   readonly menuEntryPath: string | null
   readonly executablePath: string | null
   readonly hostedUrl: string | null
+  /**
+   * False for a title this machine cannot install. It is still listed: a catalog that
+   * hides what your machine cannot run leaves you wondering which of the two is small.
+   */
+  readonly installable: boolean
+  readonly unavailableReason: UnavailableReason | null
+  /** The engine's sentence for it, for a tooltip or the log. */
+  readonly unavailableDetail: string | null
+  /**
+   * What the catalog says about getting it, or null where it said nothing.
+   *
+   * Kept separate from `installable`: that one is about this machine — no build for
+   * this architecture — and this one is about this person. A title can be perfectly
+   * installable and still not yours.
+   */
+  readonly access: CatalogAccess | null
 }

src/domain/models/HostMachine.ts

@@ -0,0 +1,65 @@
+/**
+ * The machine the store is running on, and how a config value depends on it.
+ *
+ * A native binary only starts on the architecture it was built for, so the release
+ * picker has to know: an x86_64 build installs on a Raspberry Pi and then does
+ * nothing, which is worse than not offering it at all.
+ */
+export interface HostMachine {
+  readonly operatingSystem: string
+  readonly architecture: string
+}
+
+/**
+ * A config value that may differ per machine.
+ *
+ * A plain value is the same everywhere — that is how a `cartridge` is described,
+ * being data for an emulator. Where it differs, the value is a map keyed by host.
+ */
+export type HostSpecific<TValue> = TValue | Readonly<Record<string, TValue>>
+
+/**
+ * Resolve a host-specific value; the most specific key wins.
+ *
+ *     {"linux-aarch64": …, "aarch64": …, "linux": …, "*": …}
+ *
+ * With no matching key and no `*` the answer is `null`, and the caller reports the
+ * title as unavailable rather than installing something that cannot run.
+ */
+export function resolveForHost<TValue> (
+  value: HostSpecific<TValue> | null | undefined,
+  host: HostMachine
+): TValue | null {
+  if (value === null || value === undefined) return null
+  if (!isHostMap(value)) return value
+  for (const key of hostKeys(host)) {
+    const found = value[key]
+    if (found !== undefined) return found
+  }
+  return null
+}
+
+export function hostKeys (host: HostMachine): readonly string[] {
+  return [
+    `${host.operatingSystem}-${host.architecture}`,
+    host.architecture,
+    host.operatingSystem,
+    '*'
+  ]
+}
+
+export function describeHost (host: HostMachine): string {
+  return `${host.operatingSystem}/${host.architecture}`
+}
+
+/**
+ * A host map, as opposed to a value that happens to be an object.
+ *
+ * Only plain objects are maps: an array is a value here — `kind` may be a list of
+ * asset kinds in order of preference, and that is not keyed by anything.
+ */
+function isHostMap<TValue> (
+  value: HostSpecific<TValue>
+): value is Readonly<Record<string, TValue>> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

src/domain/models/InstalledRecord.ts

@@ -0,0 +1,64 @@
+import type { SelectedGame } from './SelectedGame'
+
+/**
+ * One title as it exists on this machine: what was written, and where.
+ *
+ * This is the shape `state.json` carries, keyed `<scope>:<name>`. Every path in it
+ * is something the store put there and may therefore delete — which is why an
+ * uninstall reads the record rather than guessing at paths.
+ *
+ * The catalog's `access` block is deliberately *not* part of it. Whether somebody may
+ * download a title is the server's answer to a question asked now; a copy of it on disk
+ * would go stale the moment a purchase or a refund happened, and a stale "yes" is the
+ * dangerous direction. What is installed stays installed either way.
+ */
+export interface InstalledRecord extends Omit<SelectedGame, 'access'> {
+  /** The unpacked archive's directory; null for a hosted entry, which has none. */
+  readonly payload: string | null
+  readonly executable: string | null
+  /** `bundle` for a macOS `.app` the archive already contained, `exe` for a binary. */
+  readonly executableKind: string | null
+  readonly icon: string | null
+  /** The menu entry actually written, which is not always the one intended. */
+  readonly menuEntry: string | null
+  readonly url: string | null
+}
+
+/**
+ * The scope a state record belongs to.
+ *
+ * `scope` is what the engine writes today. `system` is what the Batocera store
+ * wrote before the shared core existed, and there the two were the same string —
+ * so an installed machine keeps working without a migration.
+ */
+export function recordScope (scope: string | null, system: string | null): string {
+  return scope ?? system ?? ''
+}
+
+/** Two scopes may both carry a game called `foo` — key on both. */
+export function gameKey (record: { readonly name: string; readonly scope: string }): string {
+  return `${record.scope}:${record.name}`
+}
+
+/** Resolve user-typed `name` or `scope:name` arguments to state keys. */
+export function matchStateKeys (
+  installed: ReadonlyMap<string, InstalledRecord>,
+  names: readonly string[]
+): readonly string[] {
+  const wanted = new Set(names.map((name: string): string => name.toLowerCase()))
+  const keys: string[] = []
+  for (const [key, record] of installed) {
+    if (wanted.has(key.toLowerCase()) || wanted.has(record.name.toLowerCase())) keys.push(key)
+  }
+  return keys
+}
+
+/** Keep only the games the user named, by bare name or `scope:name`. */
+export function limitToNames (
+  games: readonly SelectedGame[],
+  names: readonly string[]
+): readonly SelectedGame[] {
+  const wanted = new Set(names.map((name: string): string => name.toLowerCase()))
+  return games.filter((game: SelectedGame): boolean =>
+    wanted.has(game.name.toLowerCase()) || wanted.has(gameKey(game).toLowerCase()))
+}

src/domain/models/InstalledStore.ts

@@ -1,9 +1,14 @@
-/** A store engine installed on this machine, with everything needed to run it. */
+/**
+ * A store set up on this machine.
+ *
+ * A home and a config, which is all a store is now that the engine is part of this
+ * application: the home holds the state and the catalog cache, and the config says
+ * what the store offers and where its games go.
+ */
 export interface InstalledStore {
   readonly id: string
   readonly name: string
   readonly home: string
-  readonly scriptPath: string
   readonly configPath: string
   readonly engine: string
 }

src/domain/models/PythonRuntime.ts

@@ -1,6 +0,0 @@
-/** The Python 3 this machine has, and how to invoke it. */
-export interface PythonRuntime {
-  readonly command: string
-  readonly arguments: readonly string[]
-  readonly version: string
-}

src/domain/models/RegistryStore.ts

@@ -1,11 +1,15 @@
 /**
- * A store the site's registry offers.
+ * A store the site's registry offers: a name and a catalog.
  *
- * Three fields, because that is what a record is: what it is called, which
+ * That is the whole record, and it is enough. How a store behaves is not the registry's
- * catalog it serves, and where its configuration lives.
+ * business — this client carries its own store engine, whose defaults cover the
+ * host-to-asset mapping, the install modes, the platforms and the behaviour — so what
+ * was actually missing from those defaults is identity, and identity is all this is.
+ *
+ * Keeping two stores on one machine out of each other's files is a subfolder, derived
+ * here from the store's own slug rather than told to us by a server.
  */
 export interface RegistryStore {
   readonly name: string
   readonly catalogUrl: string
-  readonly storeRepositoryUrl: string
 }

src/domain/models/SelectedGame.ts

@@ -0,0 +1,62 @@
+import type { CatalogAccess } from './CatalogAccess'
+import type { UnavailableReason } from './Game'
+
+/**
+ * A catalog entry the store can install here, with the release it chose.
+ *
+ * `scope` is how the host groups its library — for a desktop that is the catalog
+ * platform. It is what `state.json` is keyed by (`<scope>:<name>`), so two scopes
+ * can carry a game of the same name without colliding.
+ */
+export interface SelectedGame {
+  readonly name: string
+  readonly scope: string
+  readonly platform: string
+  readonly kind: string
+  readonly version: string
+  readonly asset: string
+  /**
+   * The catalog-side path, kept because not every asset is a download: an `html`
+   * build is a hosted directory, and the entry is a link to it.
+   */
+  readonly assetPath: string
+  readonly title: string
+  readonly description: string
+  readonly author: string
+  readonly imageUrl: string | null
+  readonly createdAt: string | null
+  /** `app` for a native archive, `web` for a hosted page. */
+  readonly mode: string
+  /** What the catalog says about getting it; null from an engine that cannot say. */
+  readonly access: CatalogAccess | null
+}
+
+/**
+ * A title the store offers but this machine cannot install.
+ *
+ * A store that hides these is lying about its catalog by omission: "there is
+ * nothing for your machine" is an answer, and an absent entry is not. Titles the
+ * store *chooses* not to offer — the wrong status, an `only`/`exclude` list — are
+ * not here, because that is editorial rather than a limitation of the machine.
+ */
+export interface UnavailableEntry {
+  readonly name: string
+  readonly title: string
+  readonly platform: string
+  readonly description: string
+  readonly author: string
+  readonly imageUrl: string | null
+  readonly version: string
+  readonly reason: UnavailableReason
+  /** The sentence behind the code, for a tooltip or the log. */
+  readonly detail: string
+  /** Carried here too: a title with no build for this machine can still have a price. */
+  readonly access: CatalogAccess | null
+}
+
+/** What a survey of the catalog found: installable, why not, and what was skipped. */
+export interface CatalogSurvey {
+  readonly games: readonly SelectedGame[]
+  readonly skipped: readonly string[]
+  readonly unavailable: readonly UnavailableEntry[]
+}

src/domain/models/ServiceDescriptor.ts

@@ -0,0 +1,43 @@
+/**
+ * What one catalog's server says about itself.
+ *
+ * This is how the client stops being built for a particular store. Whether there is a
+ * sign-in here, where it lives, whether any title can be gated — all of it used to be
+ * knowledge the client would have had to carry, and a client that carries it works for
+ * exactly one catalog. Now the server answers, and the same binary serves any of them.
+ *
+ * Every field is optional in practice: an engine older than 0.5 has no descriptor at
+ * all, and `DEFAULT_SERVICE_DESCRIPTOR` is what that means — a plain catalog, nothing
+ * gated, nobody to sign in as. That is what this client always assumed.
+ */
+export interface ServiceDescriptor {
+  readonly engineVersion: string | null
+  /** Whether any title in this catalog can require an entitlement. */
+  readonly catalogGated: boolean
+  /** Null where the server offers no sign-in, which is most of them. */
+  readonly auth: AuthDescriptor | null
+}
+
+export interface AuthDescriptor {
+  /** The device authorization grant, for a client with no browser of its own. */
+  readonly device: DeviceAuthDescriptor
+}
+
+export interface DeviceAuthDescriptor {
+  /** Where to ask for a code pair. */
+  readonly authorizeUrl: string
+  /** Where to poll for the token. */
+  readonly tokenUrl: string
+  /** Where to throw the token away again. */
+  readonly revokeUrl: string | null
+  /** Where a person takes the code, opened in their own browser. */
+  readonly verificationUrl: string
+  /** Seconds the server asks the client to wait between polls. */
+  readonly interval: number
+}
+
+export const DEFAULT_SERVICE_DESCRIPTOR: ServiceDescriptor = {
+  engineVersion: null,
+  catalogGated: false,
+  auth: null
+}

src/domain/models/StoreAccount.ts

@@ -0,0 +1,28 @@
+/**
+ * Whether this machine is signed in to one store, and whether it could be.
+ *
+ * Two booleans rather than one, because the interesting case is the first being false:
+ * most catalogs have no sign-in at all, and a client that shows a greyed-out "Sign in"
+ * on them is telling people about a door that does not exist.
+ */
+export interface StoreAccount {
+  readonly signInAvailable: boolean
+  readonly signedIn: boolean
+}
+
+export const NO_ACCOUNT: StoreAccount = { signInAvailable: false, signedIn: false }
+
+/** What to show a person while they finish signing in somewhere else. */
+export interface SignInPrompt {
+  /** Opaque to the window: it is the client's half of the exchange, not the person's. */
+  readonly deviceCode: string
+  /** The short one, shown on screen and typed into a browser. */
+  readonly userCode: string
+  /** Opened in the person's own browser. */
+  readonly verificationUrl: string
+  readonly intervalSeconds: number
+  readonly expiresInSeconds: number
+}
+
+/** How a sign-in ended. `cancelled` is this side giving up, `denied` is the person. */
+export type SignInOutcome = 'signedIn' | 'denied' | 'expired' | 'cancelled'

src/domain/models/StoreConfiguration.ts

@@ -0,0 +1,141 @@
+import type { HostSpecific } from './HostMachine'
+
+/**
+ * How one store behaves: what it offers, where things land, how it talks to the API.
+ *
+ * This is the shape of a store's `config.json` after it has been merged onto the
+ * defaults below. On disk the file is snake_case, which is the format the store
+ * repositories publish; `StoreConfigurationReader` is the only place that knows it.
+ */
+export interface StoreConfiguration {
+  readonly store: StoreDescriptor
+  readonly paths: PathsConfiguration
+  readonly install: InstallConfiguration
+  readonly catalog: CatalogConfiguration
+  /** Which catalog platforms this store offers at all, by platform name. */
+  readonly platforms: Readonly<Record<string, PlatformConfiguration>>
+  readonly behavior: BehaviorConfiguration
+}
+
+export interface StoreDescriptor {
+  /** Short slug: names the store home, the log prefix and the launcher files. */
+  readonly id: string
+  /** Human-readable: the Start-menu folder on Windows, and what the user sees. */
+  readonly name: string
+  readonly baseUrl: string
+  readonly api: ApiConfiguration
+}
+
+export interface ApiConfiguration {
+  readonly catalog: string
+  readonly download: string
+}
+
+export interface PathsConfiguration {
+  /** All null means "work it out from the OS"; set one to pin it. */
+  readonly installRoot: string | null
+  readonly menuDirectory: string | null
+  readonly iconDirectory: string | null
+  /**
+   * Our own folder inside the install root: the prune boundary, and what keeps two
+   * stores on one machine out of each other's files.
+   */
+  readonly subfolder: string
+}
+
+export interface AssetSpecification {
+  /** One kind, or several in order of preference. */
+  readonly kind: HostSpecific<string | readonly string[]> | null
+  readonly extension: HostSpecific<string> | null
+}
+
+export interface InstallConfiguration {
+  /** Tried in this order; the first that has an asset wins. */
+  readonly modes: readonly string[]
+  readonly specifications: Readonly<Record<string, AssetSpecification>>
+}
+
+export interface CatalogConfiguration {
+  readonly statuses: readonly string[]
+  readonly ownerId: number | null
+  readonly only: readonly string[]
+  readonly exclude: readonly string[]
+}
+
+export interface PlatformConfiguration {
+  readonly enabled: boolean
+}
+
+export interface BehaviorConfiguration {
+  readonly prune: boolean
+  /** Seconds. */
+  readonly timeout: number
+  readonly insecure: boolean
+}
+
+export const APP_MODE = 'app'
+export const WEB_MODE = 'web'
+
+/**
+ * What a store gets when its config says nothing.
+ *
+ * These were the desktop engine's own defaults, and they stay the defaults: a store
+ * that publishes no `config.json` installs on the strength of this table alone, so
+ * what a store actually has to supply is identity — a slug, a name and a catalog.
+ */
+export const DEFAULT_STORE_CONFIGURATION: StoreConfiguration = {
+  store: {
+    id: 'warp',
+    name: 'WarpEngine Store',
+    baseUrl: 'https://example.org',
+    api: { catalog: '/api/software', download: '/api/download' }
+  },
+  paths: {
+    installRoot: null,
+    menuDirectory: null,
+    iconDirectory: null,
+    subfolder: 'warp'
+  },
+  install: {
+    modes: [APP_MODE, WEB_MODE],
+    specifications: {
+      // Which asset to unpack, per host. The most specific key wins; a list is
+      // tried in order of preference. On Apple Silicon `mac_universal` comes first
+      // and `mac_x64` last, because that one needs Rosetta.
+      [APP_MODE]: {
+        kind: {
+          'linux-x86_64': 'linux_x64',
+          'linux-aarch64': 'linux_arm64',
+          'linux-armhf': 'linux_armhf',
+          'linux-x86': 'linux_x86',
+          'windows-x86_64': ['win_x64', 'win_x86'],
+          'windows-x86': 'win_x86',
+          'darwin-aarch64': ['mac_universal', 'mac_arm64', 'mac_x64'],
+          'darwin-x86_64': ['mac_universal', 'mac_x64']
+        },
+        extension: '.zip'
+      },
+      // A browser build is hosted, not downloaded: there is no archive for it, so
+      // the entry opens the published page. It needs the network to play.
+      [WEB_MODE]: { kind: 'html', extension: '' }
+    }
+  },
+  catalog: {
+    statuses: ['released', 'archived'],
+    ownerId: null,
+    only: [],
+    exclude: []
+  },
+  platforms: {
+    ebitengine: { enabled: true },
+    godot: { enabled: true },
+    love: { enabled: true },
+    bevy: { enabled: true },
+    tic80: { enabled: true },
+    phaser: { enabled: true },
+    // A cartridge is data for an emulator: nothing a desktop menu can launch. The
+    // Batocera and RetroArch stores are where those belong.
+    c64: { enabled: false }
+  },
+  behavior: { prune: true, timeout: 60, insecure: false }
+}

src/domain/models/StoreEngine.ts

@@ -1,13 +1,16 @@
 /**
  * A store engine this client knows how to drive.
  *
- * There is one today. The table exists because the RetroArch store has the same
+ * There is one today: the desktop engine, which is the code in
- * command shape, so a second entry — not a second code path — is what adding it
+ * `infrastructure/engine`. The table stays because a second host — RetroArch
- * would take.
+ * playlists rather than menu entries — would be a second entry and a second
+ * `StoreCatalogGateway`, not a second code path through the application.
+ *
+ * `homeSuffix` is load-bearing rather than cosmetic: it is how an existing store
+ * home is recognised, so it has to keep saying `-desktop`.
  */
 export interface StoreEngine {
   readonly id: string
-  readonly scriptFileName: string
   /** The installer names a store home `<store id><homeSuffix>`. */
   readonly homeSuffix: string
   readonly launcherSuffix: string
@@ -15,7 +18,6 @@ export interface StoreEngine {
 
 export const DESKTOP_STORE_ENGINE: StoreEngine = {
   id: 'desktop',
-  scriptFileName: 'desktop_store.py',
   homeSuffix: '-desktop',
   launcherSuffix: '-desktop-store'
 }

src/domain/models/StoreIdentity.ts

@@ -1,15 +1,33 @@
 import type { RegistryStore } from './RegistryStore'
 
 /**
- * A store id from its repository name: `ttg-desktop-store` becomes `ttg`.
+ * A store id, from whatever the registry gave us.
  *
- * The id names the store home and the folder games land in, so it has to be short
+ * The id names the store home, the folder games land in and the launcher files, so it
- * and filesystem-safe. The repository name is the best source available before
+ * has to be short and filesystem-safe. Two sources, in order of how much they were
- * anything is downloaded; the store's own config.json overrides it once it is.
+ * meant to be a name:
+ *
+ *   1. the catalog host — `https://teletypegames.org` becomes `teletypegames`;
+ *   2. the display name, slugged, as a last resort.
+ *
+ * Derived rather than carried, and derived from the catalog: the catalog is what a store
+ * *is*, so two records naming the same catalog are the same store and land in the same
+ * place, which is what keeps a reinstall from orphaning what is already there.
  */
 export function deriveStoreId (store: RegistryStore): string {
-  const lastSegment = store.storeRepositoryUrl.replace(/\/+$/, '').split('/').pop() ?? ''
+  return toSlug(readHostLabel(store.catalogUrl)) || toSlug(store.name) || 'store'
-  const base = lastSegment.replace(/-(desktop-)?store$/, '') || store.name
+}
-  const slug = base.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
+
-  return slug || 'store'
+/** `https://www.teletypegames.org/x` -> `teletypegames`. */
+function readHostLabel (catalogUrl: string): string {
+  try {
+    const host = new URL(catalogUrl).hostname.replace(/^www\./, '')
+    return host.split('.')[0] ?? ''
+  } catch {
+    return ''
+  }
+}
+
+function toSlug (value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
 }

src/domain/models/WarpEngineVersion.ts

@@ -0,0 +1,109 @@
+/**
+ * Which WarpEngine a catalog is served by, and whether this client knows it.
+ *
+ * Every WarpEngine API response carries the engine's version in a header, set before
+ * the action runs so that even an error response has it. That is what lets a client
+ * branch on the engine's age without a round trip to ask — and this file is where the
+ * branching starts.
+ */
+
+/** `WarpEngine::VERSION_HEADER` on the server side. */
+export const WARP_ENGINE_VERSION_HEADER = 'warpengine-version'
+
+/**
+ * The engine versions this client is written against, oldest first.
+ *
+ * Minor precision, because that is the granularity the engine changes its API at: a
+ * patch release fixes something behind the same shapes. Adding an entry here is a
+ * compile error until `selectCatalogDialect` says which dialect it gets, which is the
+ * point — a new engine version should not be able to arrive silently.
+ */
+export const SUPPORTED_WARP_ENGINE_VERSIONS = ['0.2', '0.3', '0.4', '0.5'] as const
+
+export type SupportedWarpEngineVersion = typeof SUPPORTED_WARP_ENGINE_VERSIONS[number]
+
+/**
+ * Why the version this client will use is not simply the one the server named.
+ *
+ *   - `exact`   — the header named a version in the supported list;
+ *   - `absent`  — no header at all. An engine older than 0.4.0 does not send one, so
+ *                 this means "old", not "broken", and the oldest dialect is the honest
+ *                 reading of it;
+ *   - `older`   — a version below everything here: same treatment, but it said so;
+ *   - `newer`   — a version above everything here. The newest dialect is tried anyway,
+ *                 because listing nothing is worse than listing what still parses, but
+ *                 this is the case worth putting in the log.
+ */
+export type WarpEngineVersionMatch = 'exact' | 'absent' | 'older' | 'newer'
+
+export interface WarpEngineVersion {
+  /** As the header spelled it, or null when there was none. */
+  readonly text: string | null
+  /** The supported version whose dialect will be used. Never null: one always applies. */
+  readonly resolved: SupportedWarpEngineVersion
+  readonly match: WarpEngineVersionMatch
+  readonly supported: boolean
+}
+
+const OLDEST: SupportedWarpEngineVersion = SUPPORTED_WARP_ENGINE_VERSIONS[0]
+const NEWEST: SupportedWarpEngineVersion =
+  SUPPORTED_WARP_ENGINE_VERSIONS[SUPPORTED_WARP_ENGINE_VERSIONS.length - 1] ?? OLDEST
+
+/**
+ * Read the header into a decision.
+ *
+ * An unparseable value is treated as an absent one: a header that does not look like a
+ * version tells us nothing about the engine, and guessing from a malformed string is
+ * worse than admitting we do not know.
+ */
+export function readWarpEngineVersion (headerValue: string | null): WarpEngineVersion {
+  if (headerValue === null || headerValue.trim().length === 0) {
+    return { text: null, resolved: OLDEST, match: 'absent', supported: false }
+  }
+  const text = headerValue.trim()
+  const numbers = parseVersion(text)
+  if (numbers === null) {
+    return { text, resolved: OLDEST, match: 'absent', supported: false }
+  }
+
+  const key = `${String(numbers[0])}.${String(numbers[1])}`
+  const exact = SUPPORTED_WARP_ENGINE_VERSIONS
+    .find((candidate: SupportedWarpEngineVersion): boolean => candidate === key)
+  if (exact !== undefined) {
+    return { text, resolved: exact, match: 'exact', supported: true }
+  }
+
+  const newer = compareVersions(numbers, parseVersion(NEWEST) ?? [0, 0]) > 0
+  return newer
+    ? { text, resolved: NEWEST, match: 'newer', supported: false }
+    : { text, resolved: OLDEST, match: 'older', supported: false }
+}
+
+/** One sentence for the log, which is where an unsupported engine has to show up. */
+export function describeWarpEngineVersion (version: WarpEngineVersion): string {
+  const supported = SUPPORTED_WARP_ENGINE_VERSIONS.join(', ')
+  switch (version.match) {
+    case 'exact':
+      return `WarpEngine ${version.text ?? ''}`
+    case 'absent':
+      return 'the catalog sent no WarpEngine-Version header — reading it as ' +
+        `${OLDEST}, which is what an engine older than 0.4.0 is`
+    case 'older':
+      return `WarpEngine ${version.text ?? ''} is older than anything this client knows ` +
+        `(${supported}) — reading it as ${OLDEST}`
+    case 'newer':
+      return `WarpEngine ${version.text ?? ''} is newer than this client knows ` +
+        `(${supported}) — reading it as ${NEWEST}, so some titles may be missed`
+  }
+}
+
+function parseVersion (text: string): readonly [number, number] | null {
+  const match = /(\d+)\.(\d+)/.exec(text)
+  if (match === null) return null
+  return [Number(match[1]), Number(match[2])]
+}
+
+function compareVersions (left: readonly [number, number], right: readonly [number, number]): number {
+  if (left[0] !== right[0]) return left[0] - right[0]
+  return left[1] - right[1]
+}

src/domain/ports/CredentialRepository.ts

@@ -0,0 +1,16 @@
+/**
+ * Where a store's sign-in token is kept between runs.
+ *
+ * One token per store, keyed by store id, because the client serves several stores at
+ * once and being signed in to one says nothing about the others.
+ *
+ * A port rather than a file path because the storage is the host's business: on a
+ * desktop it is the OS keychain, in a test it is a map. Nothing above this layer knows
+ * which, and nothing above it should — the token is the one value in this application
+ * that must not end up somewhere it can be read by looking.
+ */
+export interface CredentialRepository {
+  readToken: (storeId: string) => string | null
+  writeToken: (storeId: string, token: string) => void
+  clearToken: (storeId: string) => void
+}

src/domain/ports/InstalledStoreRepository.ts

@@ -7,4 +7,9 @@ export interface InstalledStoreRepository {
   /** The roots that are searched, in the order the shell installer would use them. */
   readRoots: () => readonly string[]
   resolveDefaultHome: (storeId: string) => string
+  /**
+   * Delete a store home. Only a directory this repository would have *found* is
+   * accepted, so a caller cannot name an arbitrary path and have it removed.
+   */
+  removeHome: (home: string) => void
 }

src/domain/ports/PythonRuntimeLocator.ts

@@ -1,5 +0,0 @@
-import type { PythonRuntime } from '../models/PythonRuntime'
-
-export interface PythonRuntimeLocator {
-  findRuntime: () => PythonRuntime | null
-}

src/domain/ports/StoreCatalogGateway.ts

@@ -1,19 +1,44 @@
 import type { CatalogListing } from '../models/CatalogListing'
 import type { EngineProgressListener } from '../models/EngineProgress'
-import type { EngineVersion } from '../models/EngineVersion'
 import type { InstalledStore } from '../models/InstalledStore'
+import type { SignInPrompt, StoreAccount } from '../models/StoreAccount'
 import type { StorePaths } from '../models/StorePaths'
 
 /**
  * The store engine, as an interface.
  *
- * Every catalog operation this client performs is one call on this port; the CLI
+ * Every catalog operation this client performs is one call on this port. The engine
- * behind it stays the product, and nothing above this line knows it is Python.
+ * behind it runs in this process, but nothing above this line knows that either —
+ * the port is what let it stop being a child process without a change up here.
  */
 export interface StoreCatalogGateway {
   listGames: (store: InstalledStore, progress?: EngineProgressListener) => Promise<CatalogListing>
   readPaths: (store: InstalledStore, progress?: EngineProgressListener) => Promise<StorePaths>
   syncGames: (store: InstalledStore, names: readonly string[], progress?: EngineProgressListener) => Promise<void>
   removeGame: (store: InstalledStore, name: string, progress?: EngineProgressListener) => Promise<void>
-  readEngineVersion: (store: InstalledStore) => EngineVersion | null
+  /**
+   * Take a whole store off this machine: everything it installed, then its own home.
+   *
+   * The games go first and deliberately so. A store's `state.json` is the only record
+   * of what it put where, so deleting the home first would strip the one thing that
+   * knows which payloads, icons and menu entries belong to it — leaving a library of
+   * orphans nothing can ever clean up.
+   */
+  removeStore: (store: InstalledStore, progress?: EngineProgressListener) => Promise<void>
+
+  /** Whether this store offers a sign-in, and whether we are holding a token for it. */
+  readAccount: (store: InstalledStore) => Promise<StoreAccount>
+  /**
+   * Ask the store for a code pair. The *waiting* is not here: polling is a loop with a
+   * cancel in it, which is orchestration, and orchestration belongs above this port.
+   */
+  requestSignIn: (store: InstalledStore, clientName: string) => Promise<SignInPrompt>
+  /** One poll. Returns the account once it is answered, or null while it is not. */
+  pollSignIn: (store: InstalledStore, deviceCode: string) => Promise<SignInPollResult>
+  signOut: (store: InstalledStore) => Promise<StoreAccount>
+}
+
+export interface SignInPollResult {
+  readonly state: 'pending' | 'approved' | 'denied' | 'expired'
+  readonly account: StoreAccount
 }

src/infrastructure/archive/ZipArchive.ts

@@ -0,0 +1,168 @@
+import { inflateRawSync } from 'node:zlib'
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * A zip reader over `node:zlib`, because Node has no zip and this client has no
+ * runtime dependencies.
+ *
+ * Only what the store actually needs to read: the archives come from our own
+ * release pipeline, so `stored` and `deflate` are the only compression methods
+ * that occur and there is no encryption to support. What is *not* optional is the
+ * unix mode — the archive records the executable bit and without it nothing we
+ * install can start, so every entry is read from the central directory, which is
+ * the only place that carries it.
+ *
+ * Symlinks are written as regular files holding their target path. That is also
+ * what Python's `ZipFile.extractall` does, so an archive that installed before
+ * installs the same way now.
+ */
+
+const END_OF_CENTRAL_DIRECTORY = 0x06054b50
+const CENTRAL_FILE_HEADER = 0x02014b50
+const LOCAL_FILE_HEADER = 0x04034b50
+
+const END_OF_CENTRAL_DIRECTORY_SIZE = 22
+const CENTRAL_FILE_HEADER_SIZE = 46
+const LOCAL_FILE_HEADER_SIZE = 30
+
+/** A zip comment is a u16 length, so the record cannot start further back than this. */
+const MAX_COMMENT_SIZE = 0xffff
+
+const STORED = 0
+const DEFLATED = 8
+
+/** The u16/u32 sentinels a zip64 archive puts in the fields it has outgrown. */
+const ZIP64_U16 = 0xffff
+const ZIP64_U32 = 0xffffffff
+
+const DEFAULT_FILE_MODE = 0o644
+const DEFAULT_DIRECTORY_MODE = 0o755
+const EXECUTABLE_BITS = 0o111
+
+export interface ZipEntry {
+  readonly fileName: string
+  readonly directory: boolean
+  readonly compressionMethod: number
+  readonly compressedSize: number
+  readonly uncompressedSize: number
+  /** From the external attributes' high word; 0 when the archive carries no unix mode. */
+  readonly unixMode: number
+  readonly localHeaderOffset: number
+}
+
+export class ZipArchive {
+  private constructor (
+    private readonly buffer: Buffer,
+    public readonly entries: readonly ZipEntry[]
+  ) {}
+
+  public static open (archivePath: string): ZipArchive {
+    const buffer = fs.readFileSync(archivePath)
+    return new ZipArchive(buffer, readCentralDirectory(buffer, archivePath))
+  }
+
+  /**
+   * Unpack everything into `destination`, restoring the executable bit.
+   *
+   * Every entry path is resolved and checked against the destination before it is
+   * written: a zip may name `../` and this store writes into the user's own data
+   * directory.
+   */
+  public extractAll (destination: string): void {
+    const root = path.resolve(destination)
+    fs.mkdirSync(root, { recursive: true })
+
+    for (const entry of this.entries) {
+      const target = path.resolve(root, entry.fileName)
+      if (target !== root && !target.startsWith(root + path.sep)) {
+        throw new Error(`${entry.fileName} would be written outside ${root}`)
+      }
+      if (entry.directory) {
+        fs.mkdirSync(target, { recursive: true, mode: DEFAULT_DIRECTORY_MODE })
+        continue
+      }
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      fs.writeFileSync(target, this.readEntry(entry), { mode: this.fileMode(entry) })
+    }
+  }
+
+  /** One entry's bytes, decompressed. */
+  public readEntry (entry: ZipEntry): Buffer {
+    const signature = this.buffer.readUInt32LE(entry.localHeaderOffset)
+    if (signature !== LOCAL_FILE_HEADER) {
+      throw new Error(`${entry.fileName}: no local header at ${String(entry.localHeaderOffset)}`)
+    }
+    // The local header's own sizes may be zero when a data descriptor follows, so
+    // the lengths come from the central directory and only the two variable-length
+    // fields are read here.
+    const nameLength = this.buffer.readUInt16LE(entry.localHeaderOffset + 26)
+    const extraLength = this.buffer.readUInt16LE(entry.localHeaderOffset + 28)
+    const start = entry.localHeaderOffset + LOCAL_FILE_HEADER_SIZE + nameLength + extraLength
+    const raw = this.buffer.subarray(start, start + entry.compressedSize)
+
+    if (entry.compressionMethod === STORED) return Buffer.from(raw)
+    if (entry.compressionMethod === DEFLATED) return inflateRawSync(raw)
+    throw new Error(`${entry.fileName}: unsupported compression method ${String(entry.compressionMethod)}`)
+  }
+
+  /**
+   * The mode to write a file with.
+   *
+   * A zip made on Windows carries no unix mode at all, and there the archive
+   * simply cannot tell us — 0644 is the safe answer, and `find_program` looks for
+   * `.exe` on that host anyway rather than for the executable bit.
+   */
+  private fileMode (entry: ZipEntry): number {
+    if (entry.unixMode === 0) return DEFAULT_FILE_MODE
+    const permissions = entry.unixMode & 0o7777
+    if (permissions === 0) return DEFAULT_FILE_MODE
+    return (permissions & EXECUTABLE_BITS) === 0 ? permissions : permissions | EXECUTABLE_BITS
+  }
+}
+
+function readCentralDirectory (buffer: Buffer, archivePath: string): readonly ZipEntry[] {
+  const end = findEndOfCentralDirectory(buffer, archivePath)
+  const entryCount = buffer.readUInt16LE(end + 10)
+  const directoryOffset = buffer.readUInt32LE(end + 16)
+
+  if (entryCount === ZIP64_U16 || directoryOffset === ZIP64_U32) {
+    throw new Error(`${archivePath} is a zip64 archive, which this reader does not support`)
+  }
+
+  const entries: ZipEntry[] = []
+  let cursor = directoryOffset
+  for (let index = 0; index < entryCount; index += 1) {
+    if (cursor + CENTRAL_FILE_HEADER_SIZE > buffer.length) {
+      throw new Error(`${archivePath}: the central directory ends mid-entry`)
+    }
+    if (buffer.readUInt32LE(cursor) !== CENTRAL_FILE_HEADER) {
+      throw new Error(`${archivePath}: no central directory entry at ${String(cursor)}`)
+    }
+    const nameLength = buffer.readUInt16LE(cursor + 28)
+    const extraLength = buffer.readUInt16LE(cursor + 30)
+    const commentLength = buffer.readUInt16LE(cursor + 32)
+    const fileName = buffer.toString('utf8', cursor + CENTRAL_FILE_HEADER_SIZE, cursor + CENTRAL_FILE_HEADER_SIZE + nameLength)
+
+    entries.push({
+      fileName,
+      directory: fileName.endsWith('/'),
+      compressionMethod: buffer.readUInt16LE(cursor + 10),
+      compressedSize: buffer.readUInt32LE(cursor + 20),
+      uncompressedSize: buffer.readUInt32LE(cursor + 24),
+      unixMode: buffer.readUInt32LE(cursor + 38) >>> 16,
+      localHeaderOffset: buffer.readUInt32LE(cursor + 42)
+    })
+    cursor += CENTRAL_FILE_HEADER_SIZE + nameLength + extraLength + commentLength
+  }
+  return entries
+}
+
+/** The record is at the end, behind a comment of unknown length, so scan backwards. */
+function findEndOfCentralDirectory (buffer: Buffer, archivePath: string): number {
+  const earliest = Math.max(0, buffer.length - END_OF_CENTRAL_DIRECTORY_SIZE - MAX_COMMENT_SIZE)
+  for (let offset = buffer.length - END_OF_CENTRAL_DIRECTORY_SIZE; offset >= earliest; offset -= 1) {
+    if (buffer.readUInt32LE(offset) === END_OF_CENTRAL_DIRECTORY) return offset
+  }
+  throw new Error(`${archivePath} is not a zip archive`)
+}

src/infrastructure/config/BuildConfiguration.ts

@@ -0,0 +1,49 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { asRecord, readRecord, readString } from '../json/JsonRecord'
+
+/**
+ * What was decided when this package was built.
+ *
+ * The registry address is the one thing about a particular site left in the client, and
+ * a build for a different site should not need a different source tree. So it is a field
+ * in `package.json`, which `electron-builder` can overwrite at packaging time:
+ *
+ *   make dist STORES_API=https://staging.example.org/api/stores
+ *
+ * Read from the package.json that ships inside the app, so a packaged build answers with
+ * what it was built with. A runtime `STORES_API` still wins over it — that is for trying
+ * something out, this is for shipping it.
+ */
+export class BuildConfiguration {
+  private cached: Readonly<Record<string, unknown>> | null = null
+
+  public readRegistryUrl (): string | null {
+    const section = readRecord(this.read(), 'warpEngine')
+    if (section === null) return null
+    const url = readString(section, 'registryUrl').trim()
+    return url.length > 0 ? url : null
+  }
+
+  private read (): Readonly<Record<string, unknown>> {
+    if (this.cached !== null) return this.cached
+    // build/infrastructure/config → the package root, packaged or not.
+    const candidates = [
+      path.join(__dirname, '..', '..', '..', 'package.json'),
+      path.join(__dirname, '..', '..', 'package.json')
+    ]
+    for (const candidate of candidates) {
+      try {
+        const parsed = asRecord(JSON.parse(fs.readFileSync(candidate, 'utf8')))
+        if (parsed !== null) {
+          this.cached = parsed
+          return parsed
+        }
+      } catch {
+        // Try the next one; a missing package.json is only fatal if none is found.
+      }
+    }
+    this.cached = {}
+    return this.cached
+  }
+}

src/infrastructure/electron/SafeStorageCredentialRepository.ts

@@ -0,0 +1,94 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { safeStorage } from 'electron'
+import type { CredentialRepository } from '../../domain/ports/CredentialRepository'
+import type { ApplicationEnvironment } from '../../domain/ports/ApplicationEnvironment'
+
+const FILE_NAME = 'credentials.json'
+
+/**
+ * Tokens in the OS keychain's own encryption, in the application's data directory.
+ *
+ * Not in the store home next to `config.json` and `state.json`: those two are the
+ * store's public description of itself and its record of what it installed, both
+ * meant to be read and both copied around when somebody moves a library. A password
+ * does not belong in either.
+ *
+ * `safeStorage` is Electron's wrapper over the platform keychain (Keychain on macOS,
+ * libsecret on Linux, DPAPI on Windows). Where it is unavailable — a Linux box with no
+ * secret service — this stores nothing at all rather than falling back to plain text.
+ * The cost is signing in again next run; the alternative is a readable token on disk
+ * for somebody who thought it was encrypted.
+ */
+export class SafeStorageCredentialRepository implements CredentialRepository {
+  public constructor (private readonly environment: ApplicationEnvironment) {}
+
+  public readToken (storeId: string): string | null {
+    if (!this.available()) return null
+    const encoded = this.readAll()[storeId]
+    if (typeof encoded !== 'string') return null
+
+    try {
+      return safeStorage.decryptString(Buffer.from(encoded, 'base64'))
+    } catch {
+      // A token encrypted under a keychain this machine no longer has. Signing in
+      // again is the only way through, and an unreadable entry is not worth an error.
+      return null
+    }
+  }
+
+  public writeToken (storeId: string, token: string): void {
+    if (!this.available()) return
+
+    const all = { ...this.readAll() }
+    all[storeId] = safeStorage.encryptString(token).toString('base64')
+    this.writeAll(all)
+  }
+
+  public clearToken (storeId: string): void {
+    const all = this.readAll()
+    if (!(storeId in all)) return
+
+    // Rebuilt without the key rather than deleted from a copy: the linter forbids a
+    // dynamic delete, and this says the same thing without pretending the object was
+    // ever mutable.
+    const remaining = Object.fromEntries(
+      Object.entries(all).filter(([key]: readonly [string, unknown]): boolean => key !== storeId)
+    )
+    this.writeAll(remaining)
+  }
+
+  public available (): boolean {
+    try {
+      return safeStorage.isEncryptionAvailable()
+    } catch {
+      return false
+    }
+  }
+
+  private readAll (): Record<string, unknown> {
+    try {
+      const parsed: unknown = JSON.parse(fs.readFileSync(this.filePath(), 'utf8'))
+      return typeof parsed === 'object' && parsed !== null ? parsed as Record<string, unknown> : {}
+    } catch {
+      return {}
+    }
+  }
+
+  private writeAll (all: Record<string, unknown>): void {
+    try {
+      const target = this.filePath()
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      // 0600 as well as the encryption: defence in depth costs one argument here, and
+      // the file is only ever read by this application.
+      fs.writeFileSync(target, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 })
+    } catch {
+      // A token that could not be saved means signing in again next run, which is not
+      // worth stopping the application for.
+    }
+  }
+
+  private filePath (): string {
+    return this.environment.resolveUserDataPath(FILE_NAME)
+  }
+}

src/infrastructure/engine/CatalogClient.ts

@@ -0,0 +1,135 @@
+import type { StoreConfiguration } from '../../domain/models/StoreConfiguration'
+import {
+  WARP_ENGINE_VERSION_HEADER, describeWarpEngineVersion, readWarpEngineVersion,
+  type WarpEngineVersion
+} from '../../domain/models/WarpEngineVersion'
+import { describe, type StoreFileSystem } from '../files/StoreFileSystem'
+import { StoreHttpClient } from '../http/StoreHttpClient'
+import { asRecord } from '../json/JsonRecord'
+
+const CLIENT_VERSION = '2.0.0'
+
+const IMAGE_EXTENSIONS: Readonly<Record<string, string>> = {
+  'image/png': '.png',
+  'image/jpeg': '.jpg',
+  'image/webp': '.webp',
+  'image/gif': '.gif'
+}
+
+export interface DownloadedImage {
+  readonly body: Buffer
+  readonly extension: string
+}
+
+/** A catalog, and which engine served it. */
+export interface FetchedCatalog {
+  readonly catalog: unknown
+  readonly engineVersion: WarpEngineVersion
+}
+
+/**
+ * The catalog API, as this store talks to it.
+ *
+ * Every URL the store fetches is built here, and the catalog is cached next to the
+ * config so a sync survives an outage — the machine that lost its network still has
+ * a library, and being told what is installed matters more than being current.
+ */
+export class CatalogClient {
+  private readonly http: StoreHttpClient
+
+  public constructor (
+    private readonly configuration: StoreConfiguration,
+    private readonly files: StoreFileSystem,
+    private readonly cachePath: string,
+    private readonly log: (line: string) => void,
+    /**
+     * The bearer token to send, asked for per request rather than held.
+     *
+     * Every call this client makes goes to the catalog's own host, so the credential
+     * belongs on all of them: the catalog needs it to say what this person owns, and
+     * the download needs it to be allowed at all.
+     */
+    bearerToken: () => string | null = (): null => null
+  ) {
+    this.http = new StoreHttpClient({
+      userAgent: `warp-engine-client/${CLIENT_VERSION} (${configuration.store.id})`,
+      timeout: configuration.behavior.timeout,
+      insecure: configuration.behavior.insecure,
+      bearerToken
+    })
+  }
+
+  /** The same HTTP client, for the service descriptor and the sign-in flow. */
+  public httpClient (): StoreHttpClient {
+    return this.http
+  }
+
+  public apiUrl (endpoint: 'catalog' | 'download', parameters?: Readonly<Record<string, string>>): string {
+    const { baseUrl, api } = this.configuration.store
+    const url = `${baseUrl}/${api[endpoint].replace(/^\/+/, '')}`
+    if (parameters === undefined) return url
+    return `${url}?${new URLSearchParams(parameters).toString()}`
+  }
+
+  /** `GET /api/download` rather than `/file/`, so downloads are counted. */
+  public downloadUrl (asset: string): string {
+    return this.apiUrl('download', { path: asset })
+  }
+
+  /**
+   * The catalog, and the version of the engine that served it.
+   *
+   * The version comes from the response header, so it costs no extra request. A cache
+   * hit has no header — the cache file holds the catalog exactly as the engine sent it,
+   * which is the format the shell engine wrote and worth keeping — and then the version
+   * is reported as absent, which resolves to the oldest dialect this client knows.
+   */
+  public async fetchCatalog (): Promise<FetchedCatalog> {
+    const ownerId = this.configuration.catalog.ownerId
+    const url = this.apiUrl('catalog', ownerId === null ? undefined : { owner_id: String(ownerId) })
+    try {
+      const { body, headers } = await this.http.readBytes(url)
+      const catalog = asRecord(JSON.parse(body.toString('utf8')))
+      if (catalog === null) throw new Error('the catalog is not a JSON object')
+      this.files.writeJson(this.cachePath, catalog)
+
+      const engineVersion = readWarpEngineVersion(headers[WARP_ENGINE_VERSION_HEADER] ?? null)
+      const sentence = describeWarpEngineVersion(engineVersion)
+      if (engineVersion.supported) this.log(sentence)
+      else this.log(`warning: ${sentence}`)
+      return { catalog, engineVersion }
+    } catch (error: unknown) {
+      const cached = asRecord(this.files.readJson(this.cachePath))
+      if (cached === null) throw new Error(`cannot fetch the catalog from ${url}: ${describe(error)}`)
+      this.log(`warning: catalog fetch failed (${describe(error)}) — using the cached copy`)
+      return { catalog: cached, engineVersion: readWarpEngineVersion(null) }
+    }
+  }
+
+  public async downloadAsset (asset: string, destination: string): Promise<number> {
+    return await this.http.download(this.downloadUrl(asset), destination)
+  }
+
+  /**
+   * Box art, or null if it cannot be had.
+   *
+   * Missing box art is not a reason to fail an install: the menu entry gets the
+   * generic icon and the game still starts.
+   */
+  public async downloadImage (imageUrl: string, name: string): Promise<DownloadedImage | null> {
+    try {
+      const { body, contentType } = await this.http.readBytes(this.absoluteImageUrl(imageUrl))
+      const mediaType = contentType.split(';')[0]?.trim().toLowerCase() ?? ''
+      return { body, extension: IMAGE_EXTENSIONS[mediaType] ?? '.png' }
+    } catch (error: unknown) {
+      this.log(`warning: box art for ${name} failed: ${describe(error)}`)
+      return null
+    }
+  }
+
+  /** The catalog gives a server-relative `imageUrl`; absolute ones pass through. */
+  public absoluteImageUrl (imageUrl: string): string {
+    if (imageUrl.startsWith('http://') || imageUrl.startsWith('https://')) return imageUrl
+    return this.configuration.store.baseUrl + imageUrl
+  }
+}

src/infrastructure/engine/CatalogSurveyor.ts

@@ -0,0 +1,193 @@
+import { describeHost, resolveForHost, type HostMachine } from '../../domain/models/HostMachine'
+import type { UnavailableReason } from '../../domain/models/Game'
+import { gameKey } from '../../domain/models/InstalledRecord'
+import type {
+  CatalogSurvey, SelectedGame, UnavailableEntry
+} from '../../domain/models/SelectedGame'
+import type { AssetSpecification, StoreConfiguration } from '../../domain/models/StoreConfiguration'
+import type { CatalogEntry, CatalogSoftware } from './dialects/CatalogDialect'
+import { pickRelease } from './ReleasePicker'
+
+/**
+ * The catalog, turned into what this machine can and cannot install.
+ *
+ * Two decisions layered on each other. The inner one asks, per install mode, "which
+ * titles have *this* asset for this host"; the outer one asks it once per mode and
+ * merges the answers in the config's mode order, so a title with no native build for
+ * this machine is still installable as a hosted page. That fallback is what makes a
+ * desktop store the only one that can carry the whole catalog.
+ *
+ * A title counts as unavailable only when every mode failed it, and then the *first*
+ * mode's verdict is the one kept: `app` comes first, so a person is told "no native
+ * build for this machine" rather than the web mode's complaint about the same title.
+ *
+ * The entries arrive already typed, from whichever `CatalogDialect` the serving engine
+ * version selected — nothing here knows what the catalog's JSON looks like.
+ */
+export class CatalogSurveyor {
+  public constructor (
+    private readonly configuration: StoreConfiguration,
+    private readonly log: (line: string) => void
+  ) {}
+
+  public survey (entries: readonly CatalogEntry[], host: HostMachine): CatalogSurvey {
+    const chosen = new Map<string, SelectedGame>()
+    const unmet = new Map<string, UnavailableEntry>()
+    const reasonsByName = new Map<string, string[]>()
+
+    for (const mode of this.configuration.install.modes) {
+      const specification = this.configuration.install.specifications[mode]
+      if (specification === undefined) {
+        this.log(`warning: install mode '${mode}' has no asset spec — ignoring it`)
+        continue
+      }
+      const pass = this.surveyMode(entries, host, mode, specification)
+
+      for (const game of pass.games) {
+        const key = gameKey(game)
+        if (!chosen.has(key)) chosen.set(key, game)
+      }
+      for (const [name, reason] of pass.reasons) {
+        const collected = reasonsByName.get(name) ?? []
+        collected.push(`${mode}: ${reason}`)
+        reasonsByName.set(name, collected)
+      }
+      for (const entry of pass.unavailable) {
+        if (!unmet.has(entry.name)) unmet.set(entry.name, entry)
+      }
+    }
+
+    // A title that some later mode could serve is not skipped at all: nobody needs to
+    // hear that the native build was missing when the game installed anyway.
+    const installedNames = new Set([...chosen.values()].map((game: SelectedGame): string => game.name))
+    const skipped = [...reasonsByName.entries()]
+      .filter(([name]: readonly [string, readonly string[]]): boolean => !installedNames.has(name))
+      .map(([name, reasons]: readonly [string, readonly string[]]): string =>
+        `${name}: ${reasons.join('; ')}`)
+
+    return {
+      games: [...chosen.values()],
+      skipped,
+      unavailable: [...unmet.values()]
+        .filter((entry: UnavailableEntry): boolean => !installedNames.has(entry.name))
+    }
+  }
+
+  /** One pass over the catalog, asking for one mode's asset. */
+  private surveyMode (
+    entries: readonly CatalogEntry[],
+    host: HostMachine,
+    mode: string,
+    specification: AssetSpecification
+  ): ModeSurvey {
+    const { statuses, only, exclude } = this.filters()
+    const games: SelectedGame[] = []
+    const reasons: [string, string][] = []
+    const unavailable: UnavailableEntry[] = []
+
+    for (const entry of entries) {
+      const software = entry.software
+      const name = software.name
+
+      // Editorial filters: a title excluded here is in none of the three lists, because
+      // that is the store's choice rather than a limit of the machine.
+      if (statuses.size > 0 && !statuses.has(software.status.toLowerCase())) continue
+      if (only.size > 0 && !only.has(name.toLowerCase())) continue
+      if (exclude.has(name.toLowerCase())) continue
+
+      const platform = this.configuration.platforms[software.platform]
+      if (platform?.enabled !== true) {
+        // Reported rather than hidden: to somebody looking at a catalog, a platform
+        // switched off reads as "not supported here".
+        unavailable.push(toUnavailable(entry, 'platformOff',
+          `${software.platform} is not carried by this store`))
+        continue
+      }
+
+      const wanted = readKinds(resolveForHost(specification.kind, host))
+      if (wanted.length === 0) {
+        const reason = `${software.platform} has no asset kind for ${describeHost(host)}`
+        reasons.push([name, reason])
+        unavailable.push(toUnavailable(entry, 'hostAsset', reason))
+        continue
+      }
+      const extension = resolveForHost(specification.extension, host) ?? ''
+
+      const release = pickRelease(entry.releaseCandidates, wanted, extension)
+      if (release === null) {
+        const reason = `no '${wanted.join('/')}' asset in any release`
+        reasons.push([name, reason])
+        unavailable.push(toUnavailable(entry, 'noAsset', reason))
+        continue
+      }
+
+      games.push({
+        name,
+        scope: software.platform,
+        platform: software.platform,
+        kind: release.kind,
+        version: release.version,
+        asset: release.assetName,
+        assetPath: release.assetPath,
+        title: software.title,
+        description: software.description,
+        author: software.author,
+        imageUrl: software.imageUrl,
+        createdAt: release.createdAt,
+        mode,
+        access: entry.access
+      })
+    }
+    return { games, reasons, unavailable }
+  }
+
+  private filters (): CatalogFilters {
+    const lower = (values: readonly string[]): ReadonlySet<string> =>
+      new Set(values.map((value: string): string => value.toLowerCase()))
+    return {
+      statuses: lower(this.configuration.catalog.statuses),
+      only: lower(this.configuration.catalog.only),
+      exclude: lower(this.configuration.catalog.exclude)
+    }
+  }
+}
+
+interface CatalogFilters {
+  readonly statuses: ReadonlySet<string>
+  readonly only: ReadonlySet<string>
+  readonly exclude: ReadonlySet<string>
+}
+
+interface ModeSurvey {
+  readonly games: readonly SelectedGame[]
+  /** `[name, reason]`, kept per name so several modes' complaints can be joined. */
+  readonly reasons: readonly (readonly [string, string])[]
+  readonly unavailable: readonly UnavailableEntry[]
+}
+
+/** One unavailable record, with enough for a client to draw a card. */
+function toUnavailable (
+  entry: CatalogEntry,
+  reason: UnavailableReason,
+  detail: string
+): UnavailableEntry {
+  const software: CatalogSoftware = entry.software
+  return {
+    access: entry.access,
+    name: software.name,
+    title: software.title,
+    platform: software.platform,
+    description: software.description,
+    author: software.author,
+    imageUrl: software.imageUrl,
+    version: entry.latestRelease?.version ?? '',
+    reason,
+    detail
+  }
+}
+
+function readKinds (value: string | readonly string[] | null): readonly string[] {
+  if (value === null) return []
+  const kinds = typeof value === 'string' ? [value] : value
+  return kinds.filter((kind: string): boolean => kind.length > 0)
+}

src/infrastructure/engine/DesktopLayoutResolver.ts

@@ -0,0 +1,78 @@
+import path from 'node:path'
+import {
+  OPERATING_SYSTEM_PATHS, toSafeFileName, type DesktopLayout
+} from '../../domain/models/DesktopLayout'
+import type { InstalledRecord } from '../../domain/models/InstalledRecord'
+import type { SelectedGame } from '../../domain/models/SelectedGame'
+import type { StoreConfiguration } from '../../domain/models/StoreConfiguration'
+import { expandHome, expandPathSpecification } from '../files/StoreFileSystem'
+import type { HostMachineDetector } from './HostMachineDetector'
+
+/**
+ * Where this store writes on this machine.
+ *
+ * The XDG and Windows environment variables are the correct answer when they are
+ * set, and a hardcoded path is only the fallback: a machine that moved its data
+ * directory should still get its own menu. A value pinned in the config beats both.
+ */
+export class DesktopLayoutResolver {
+  public constructor (
+    private readonly configuration: StoreConfiguration,
+    private readonly hosts: HostMachineDetector
+  ) {}
+
+  public resolveLayout (): DesktopLayout {
+    const operatingSystem = this.hosts.findHost().operatingSystem
+    const defaults = OPERATING_SYSTEM_PATHS[operatingSystem]
+    if (defaults === undefined) {
+      throw new Error(
+        `no desktop layout is known for '${operatingSystem}' — set paths.install_root and paths.menu_dir`)
+    }
+    const sources: Record<string, string> = { os: operatingSystem }
+
+    const pick = (key: 'installRoot' | 'menuDirectory' | 'iconDirectory'): string | null => {
+      const configured = this.configuration.paths[key]
+      if (configured !== null && configured.length > 0) {
+        sources[key] = 'config'
+        return path.resolve(expandHome(configured))
+      }
+      sources[key] = 'default'
+      return expandPathSpecification(defaults[key] ?? null)
+    }
+
+    const installRoot = pick('installRoot')
+    const menuDirectory = pick('menuDirectory')
+    const iconDirectory = pick('iconDirectory')
+    if (installRoot === null || menuDirectory === null) {
+      throw new Error(`cannot resolve the install root or menu directory for '${operatingSystem}'`)
+    }
+    return { operatingSystem, installRoot, menuDirectory, iconDirectory, sources }
+  }
+
+  /** The only payload subtree this store may delete from. */
+  public ownedRoot (layout: DesktopLayout): string {
+    return path.join(layout.installRoot, this.configuration.paths.subfolder)
+  }
+
+  public payloadDirectory (layout: DesktopLayout, game: SelectedGame | InstalledRecord): string {
+    return path.join(this.ownedRoot(layout), game.name)
+  }
+
+  /**
+   * Box art path.
+   *
+   * Kept inside our own folder rather than the shared icon theme, so an uninstall
+   * never has to reach into it.
+   */
+  public iconPath (layout: DesktopLayout, game: SelectedGame | InstalledRecord): string {
+    return path.join(this.ownedRoot(layout), 'icons', `${game.name}.png`)
+  }
+
+  /** Windows puts programs in a Start-menu folder; the others do not. */
+  public menuGroup (layout: DesktopLayout): string {
+    if (layout.operatingSystem === 'windows') {
+      return path.join(layout.menuDirectory, toSafeFileName(this.configuration.store.name))
+    }
+    return layout.menuDirectory
+  }
+}

src/infrastructure/engine/DeviceSignInClient.ts

@@ -0,0 +1,117 @@
+import type { DeviceAuthDescriptor } from '../../domain/models/ServiceDescriptor'
+import type { StoreHttpClient } from '../http/StoreHttpClient'
+import { asRecord, readNumber, readOptionalString, readString } from '../json/JsonRecord'
+
+/** What the server said when asked for a code pair. */
+export interface DeviceCodeRequest {
+  readonly deviceCode: string
+  /** Short enough to read off this screen and type into a browser. */
+  readonly userCode: string
+  readonly verificationUrl: string
+  readonly intervalSeconds: number
+  readonly expiresInSeconds: number
+}
+
+export type DeviceSignInState = 'pending' | 'approved' | 'denied' | 'expired'
+
+export interface DevicePollResult {
+  readonly state: DeviceSignInState
+  /** Present exactly once: on the poll that finds the grant newly approved. */
+  readonly token: string | null
+}
+
+/**
+ * The device authorization grant, client side.
+ *
+ * The client has no browser of its own, so it cannot host a login form without asking
+ * somebody to type a password into a window that is not one. Instead it asks for a pair
+ * of codes, shows the short one, sends the person to the server's own page, and polls
+ * with the long one until it is answered.
+ *
+ * Every address comes from the service descriptor rather than from here. That is the
+ * point: this class knows the *shape* of the flow, which is the engine's, and nothing
+ * about any particular store's addresses.
+ */
+export class DeviceSignInClient {
+  public constructor (
+    private readonly http: StoreHttpClient,
+    private readonly device: DeviceAuthDescriptor
+  ) {}
+
+  public async requestCode (clientName: string): Promise<DeviceCodeRequest> {
+    const { json } = await this.http.requestJson(this.device.authorizeUrl, {
+      method: 'POST',
+      payload: { client_name: clientName }
+    })
+    const record = asRecord(json)
+    if (record === null) throw new Error('the server did not answer with a device code')
+
+    const deviceCode = readOptionalString(record, 'deviceCode')
+    const userCode = readOptionalString(record, 'userCode')
+    if (deviceCode === null || userCode === null) {
+      throw new Error('the server did not answer with a device code')
+    }
+
+    return {
+      deviceCode,
+      userCode,
+      verificationUrl: readOptionalString(record, 'verificationUrl') ?? this.device.verificationUrl,
+      // The server's own pacing wins over the descriptor's: it knows what it can take.
+      intervalSeconds: Math.max(1, readNumber(record, 'interval', this.device.interval)),
+      expiresInSeconds: Math.max(1, readNumber(record, 'expiresIn', 600))
+    }
+  }
+
+  public async poll (deviceCode: string): Promise<DevicePollResult> {
+    // 404 is a real answer here — the grant was swept or never existed — so it is read
+    // rather than thrown, and reported as expired: from the client's side those are the
+    // same situation, and both mean start again.
+    const { json, statusCode } = await this.http.requestJson(this.device.tokenUrl, {
+      method: 'POST',
+      payload: { device_code: deviceCode },
+      accept: [ 404, 410 ]
+    })
+    if (statusCode !== 200) return { state: 'expired', token: null }
+
+    const record = asRecord(json)
+    if (record === null) return { state: 'pending', token: null }
+
+    return {
+      state: toState(readString(record, 'state')),
+      token: readOptionalString(record, 'token')
+    }
+  }
+
+  /**
+   * Signing out: the token this client carries is revoked at the server.
+   *
+   * There is no token argument because there is nowhere to put one — the credential
+   * rides on the request as a bearer header, from the same supplier every other call
+   * uses. Best effort on purpose: the token is thrown away locally either way, and a
+   * server that cannot be reached must not leave somebody stuck signed in.
+   */
+  public async revoke (): Promise<boolean> {
+    if (this.device.revokeUrl === null) return false
+
+    try {
+      const { statusCode } = await this.http.requestJson(this.device.revokeUrl, {
+        method: 'DELETE',
+        accept: [ 204, 401 ]
+      })
+      return statusCode === 204
+    } catch {
+      return false
+    }
+  }
+}
+
+function toState (value: string): DeviceSignInState {
+  switch (value) {
+    case 'approved':
+    case 'denied':
+    case 'expired':
+      return value
+    default:
+      return 'pending'
+  }
+}

src/infrastructure/engine/GameInstaller.ts

@@ -0,0 +1,216 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { DesktopLayout } from '../../domain/models/DesktopLayout'
+import type { EngineProgressListener } from '../../domain/models/EngineProgress'
+import { gameKey, type InstalledRecord } from '../../domain/models/InstalledRecord'
+import type { SelectedGame } from '../../domain/models/SelectedGame'
+import { APP_MODE, type StoreConfiguration } from '../../domain/models/StoreConfiguration'
+import { describe, type StoreFileSystem } from '../files/StoreFileSystem'
+import type { CatalogClient } from './CatalogClient'
+import type { DesktopLayoutResolver } from './DesktopLayoutResolver'
+import type { LauncherWriter } from './launchers/LauncherWriter'
+import type { PayloadInstaller } from './PayloadInstaller'
+
+/**
+ * Installing and uninstalling one title, and the sweep over all of them.
+ *
+ * The rule the whole class turns on: an install writes three things — a payload, an
+ * icon and a menu entry — and the record of what was written is what an uninstall
+ * reads. Nothing is ever deleted by reconstructing a path from a name, because a
+ * path built from a name is a guess and this runs inside the user's home directory.
+ */
+export class GameInstaller {
+  public constructor (
+    private readonly configuration: StoreConfiguration,
+    private readonly layouts: DesktopLayoutResolver,
+    private readonly payloads: PayloadInstaller,
+    private readonly launchers: LauncherWriter,
+    private readonly catalog: CatalogClient,
+    private readonly files: StoreFileSystem,
+    private readonly log: (line: string) => void
+  ) {}
+
+  /**
+   * Install every game in `games`, updating `installed` in place.
+   *
+   * Returns whether anything changed, which is what decides between "done" and
+   * "already up to date" — a sync that rewrites nothing should say so.
+   */
+  public async installAll (
+    layout: DesktopLayout,
+    games: readonly SelectedGame[],
+    installed: Map<string, InstalledRecord>,
+    prune: boolean,
+    progress: EngineProgressListener
+  ): Promise<boolean> {
+    let changed = false
+    let failed = 0
+    progress.onEvent?.({ event: 'plan', count: games.length })
+
+    for (const game of games) {
+      const key = gameKey(game)
+      let previous = installed.get(key) ?? null
+
+      // A different asset or a different mode is not an update in place: the old
+      // payload and the old kind of menu entry both have to go first.
+      if (previous !== null && (previous.asset !== game.asset || previous.mode !== game.mode)) {
+        this.log(`${game.name}: ${previous.version} (${previous.mode}) -> ` +
+          `${game.version} (${game.mode}), removing the old install`)
+        this.removeGame(layout, previous)
+        previous = null
+        changed = true
+      }
+
+      progress.onEvent?.({ event: 'begin', name: game.name, title: game.title })
+      try {
+        const result = await this.installGame(layout, game, previous)
+        progress.onEvent?.({
+          event: 'installed', name: game.name, title: game.title, changed: result.changed
+        })
+        if (result.changed || !sameRecord(installed.get(key) ?? null, result.record)) changed = true
+        installed.set(key, result.record)
+      } catch (error: unknown) {
+        failed += 1
+        const reason = describe(error)
+        this.log(`warning: ${game.name} failed: ${reason}`)
+        progress.onEvent?.({ event: 'failed', name: game.name, error: reason })
+      }
+    }
+
+    if (prune) {
+      const keep = new Set(games.map((game: SelectedGame): string => gameKey(game)))
+      for (const [key, record] of [...installed]) {
+        if (keep.has(key)) continue
+        this.log(`pruning ${key} (no longer in the catalog or filtered out)`)
+        this.removeGame(layout, record)
+        progress.onEvent?.({ event: 'pruned', name: record.name })
+        installed.delete(key)
+        changed = true
+      }
+    }
+
+    progress.onEvent?.({ event: 'finished', installed: installed.size, failed })
+    return changed
+  }
+
+  /** Install one title in its chosen mode. */
+  public async installGame (
+    layout: DesktopLayout,
+    game: SelectedGame,
+    previous: InstalledRecord | null
+  ): Promise<{ readonly record: InstalledRecord; readonly changed: boolean }> {
+    const payloadDirectory = this.layouts.payloadDirectory(layout, game)
+    let changed = false
+    let payload: string | null = null
+    let executable: string | null = null
+    let executableKind: string | null = null
+    let url: string | null = null
+
+    if (game.mode === APP_MODE) {
+      if (previous !== null && isStillInstalled(previous, game, payloadDirectory)) {
+        executable = previous.executable
+        executableKind = previous.executableKind
+      } else {
+        const size = await this.payloads.unpack(game, payloadDirectory)
+        changed = true
+        const program = this.payloads.findProgram(payloadDirectory, game.name, layout.operatingSystem)
+        if (program === null) {
+          fs.rmSync(payloadDirectory, { recursive: true, force: true })
+          throw new Error(`no program was found inside ${game.asset}`)
+        }
+        executable = program.executablePath
+        executableKind = program.kind
+        this.log(`installed ${game.name} ${game.version} (${String(size)} bytes) -> ${payloadDirectory}`)
+      }
+      payload = payloadDirectory
+    } else {
+      // Nothing to unpack: the browser build is hosted, so the entry is a link.
+      url = this.launchers.webUrl(game)
+      if (previous?.url !== url) {
+        changed = true
+        this.log(`added ${game.name} ${game.version} as a web entry -> ${url}`)
+      }
+    }
+
+    const withoutMenu: InstalledRecord = {
+      ...game,
+      payload,
+      executable,
+      executableKind,
+      icon: await this.installIcon(layout, game),
+      menuEntry: null,
+      url
+    }
+    const menuEntry = this.launchers.writeLauncher(layout, withoutMenu)
+    if ((previous?.menuEntry ?? null) !== menuEntry) changed = true
+
+    return { record: { ...withoutMenu, menuEntry }, changed }
+  }
+
+  /** Delete one title's payload, icon and menu entry — and nothing else. */
+  public removeGame (layout: DesktopLayout, record: InstalledRecord): void {
+    const owned = this.layouts.ownedRoot(layout)
+    for (const target of [record.payload, record.icon]) {
+      if (target !== null) this.files.removeWithin(target, owned)
+    }
+    if (record.menuEntry !== null) {
+      this.files.removeWithin(record.menuEntry, layout.menuDirectory)
+    }
+  }
+
+  /** Remove everything this store installed, folders included. */
+  public purge (layout: DesktopLayout, installed: Map<string, InstalledRecord>): void {
+    for (const [key, record] of [...installed]) {
+      this.removeGame(layout, record)
+      installed.delete(key)
+    }
+    const owned = this.layouts.ownedRoot(layout)
+    this.files.pruneEmptyDirectories([path.join(owned, 'icons'), owned], layout.installRoot)
+    if (layout.operatingSystem === 'windows') {
+      this.files.pruneEmptyDirectories([this.layouts.menuGroup(layout)], layout.menuDirectory)
+    }
+  }
+
+  private async installIcon (layout: DesktopLayout, game: SelectedGame): Promise<string | null> {
+    if (game.imageUrl === null) return null
+    const iconPath = this.layouts.iconPath(layout, game)
+    if (hasContent(iconPath)) return iconPath
+
+    const image = await this.catalog.downloadImage(game.imageUrl, game.name)
+    if (image === null) return null
+    // The name says .png because that is what a desktop entry and `sips` expect; a
+    // non-PNG cover still displays on Linux, which sniffs the content.
+    this.files.writeAtomic(iconPath, image.body)
+    return iconPath
+  }
+}
+
+/**
+ * Whether the previous install is still there and still the right one.
+ *
+ * All four conditions matter: the same asset, a payload directory that exists, a
+ * recorded executable, and that executable still on disk. A user who deleted the
+ * folder by hand should get a reinstall rather than a menu entry that does nothing.
+ */
+function isStillInstalled (
+  previous: InstalledRecord,
+  game: SelectedGame,
+  payloadDirectory: string
+): boolean {
+  return previous.asset === game.asset &&
+    fs.existsSync(payloadDirectory) &&
+    previous.executable !== null &&
+    fs.existsSync(previous.executable)
+}
+
+function hasContent (filePath: string): boolean {
+  try {
+    return fs.statSync(filePath).size > 0
+  } catch {
+    return false
+  }
+}
+
+function sameRecord (left: InstalledRecord | null, right: InstalledRecord): boolean {
+  return left !== null && JSON.stringify(left) === JSON.stringify(right)
+}

src/infrastructure/engine/HostMachineDetector.ts

@@ -0,0 +1,47 @@
+import type { HostMachine } from '../../domain/models/HostMachine'
+
+/**
+ * This machine, as the release picker needs to know it.
+ *
+ * Node already normalises what `uname -m` reports, but not to the names the catalog
+ * uses, and the catalog's names are the ones the asset kinds are keyed by.
+ */
+export class HostMachineDetector {
+  private cached: HostMachine | null = null
+
+  public findHost (): HostMachine {
+    this.cached ??= {
+      operatingSystem: readOperatingSystem(),
+      architecture: readArchitecture()
+    }
+    return this.cached
+  }
+}
+
+/**
+ * Node's names for the architectures the catalog has a name for.
+ *
+ * Anything not in the table passes through unchanged: it will match no asset kind,
+ * and the survey then reports the titles as unavailable on this machine — which is
+ * the honest answer for a host nobody has built for.
+ */
+const ARCHITECTURE_NAMES: Readonly<Record<string, string>> = {
+  x64: 'x86_64',
+  arm64: 'aarch64',
+  arm: 'armhf',
+  ia32: 'x86'
+}
+
+const OPERATING_SYSTEM_NAMES: Readonly<Record<string, string>> = {
+  darwin: 'darwin',
+  win32: 'windows',
+  linux: 'linux'
+}
+
+function readArchitecture (): string {
+  return ARCHITECTURE_NAMES[process.arch] ?? process.arch
+}
+
+function readOperatingSystem (): string {
+  return OPERATING_SYSTEM_NAMES[process.platform] ?? process.platform
+}

src/infrastructure/engine/NativeStoreCatalogGateway.ts

@@ -0,0 +1,440 @@
+import path from 'node:path'
+import type { CatalogListing } from '../../domain/models/CatalogListing'
+import type { DesktopLayout } from '../../domain/models/DesktopLayout'
+import type { EngineProgressListener } from '../../domain/models/EngineProgress'
+import type { Game, GameMode } from '../../domain/models/Game'
+import {
+  gameKey, limitToNames, matchStateKeys, type InstalledRecord
+} from '../../domain/models/InstalledRecord'
+import type { InstalledStore } from '../../domain/models/InstalledStore'
+import type {
+  CatalogSurvey, SelectedGame, UnavailableEntry
+} from '../../domain/models/SelectedGame'
+import type { ServiceDescriptor } from '../../domain/models/ServiceDescriptor'
+import type { SignInPrompt, StoreAccount } from '../../domain/models/StoreAccount'
+import { APP_MODE, WEB_MODE, type StoreConfiguration } from '../../domain/models/StoreConfiguration'
+import type { StorePaths } from '../../domain/models/StorePaths'
+import type { CredentialRepository } from '../../domain/ports/CredentialRepository'
+import type { InstalledStoreRepository } from '../../domain/ports/InstalledStoreRepository'
+import type { SignInPollResult, StoreCatalogGateway } from '../../domain/ports/StoreCatalogGateway'
+import { StoreFileSystem } from '../files/StoreFileSystem'
+import { CatalogClient, type FetchedCatalog } from './CatalogClient'
+import { CatalogSurveyor } from './CatalogSurveyor'
+import type { CatalogEntry } from './dialects/CatalogDialect'
+import { selectCatalogDialect } from './dialects/CatalogDialectSelector'
+import { DesktopLayoutResolver } from './DesktopLayoutResolver'
+import { DeviceSignInClient } from './DeviceSignInClient'
+import { GameInstaller } from './GameInstaller'
+import { HostMachineDetector } from './HostMachineDetector'
+import { LauncherWriter } from './launchers/LauncherWriter'
+import { PayloadInstaller } from './PayloadInstaller'
+import { ServiceDescriptorClient } from './ServiceDescriptorClient'
+import { StoreConfigurationReader } from './StoreConfigurationReader'
+import { StoreStateRepository } from './StoreStateRepository'
+
+const STATE_FILE_NAME = 'state.json'
+const CATALOG_CACHE_FILE_NAME = 'catalog.json'
+
+/**
+ * The store engine, in process.
+ *
+ * This is the whole of what used to be `desktop_store.py` and `warpstore.py` driven
+ * as a child process: the catalog, the release choice, the host match, the unpacking,
+ * the menu entry and the state. Nothing is serialised to JSON lines and parsed back,
+ * so the progress events below are the typed events the window already expects, and
+ * a `Game` is built rather than read out of somebody else's field names.
+ *
+ * What has *not* changed is what lands on disk. `config.json` and `state.json` keep
+ * the shell engine's snake_case shape, so a machine whose library was installed by
+ * the CLI keeps it.
+ */
+export class NativeStoreCatalogGateway implements StoreCatalogGateway {
+  private readonly hosts = new HostMachineDetector()
+
+  /**
+   * The credentials are injected because they are the host's to keep: on a desktop the
+   * OS keychain, in the smoke test a map in memory. Nothing here knows which.
+   */
+  public constructor (
+    private readonly credentials: CredentialRepository = NO_CREDENTIALS,
+    private readonly stores: InstalledStoreRepository = NO_STORES
+  ) {}
+
+  public async listGames (
+    store: InstalledStore,
+    progress: EngineProgressListener = {}
+  ): Promise<CatalogListing> {
+    const engine = this.openStore(store, progress)
+    const host = this.hosts.findHost()
+    engine.log(`host: ${host.operatingSystem}/${host.architecture}`)
+
+    const [ descriptor, entries ] = await Promise.all([
+      engine.service.fetchDescriptor(), this.readEntries(engine)
+    ])
+    const survey = engine.surveyor.survey(entries, host)
+    const installed = engine.state.readState()
+
+    // One list, both kinds: a client that hides what it cannot install leaves the
+    // visitor wondering whether the catalog is small or their machine is unusual.
+    const games = [
+      ...survey.games.map((game: SelectedGame): Game => this.toGame(engine, game, installed)),
+      ...survey.unavailable.map((entry: UnavailableEntry): Game => toUnavailableGame(entry))
+    ].sort((left: Game, right: Game): number =>
+      left.title.toLowerCase().localeCompare(right.title.toLowerCase()))
+
+    return {
+      games,
+      skipped: survey.skipped,
+      paths: this.toPaths(engine),
+      account: toAccount(descriptor, this.credentials.readToken(store.id))
+    }
+  }
+
+  /**
+   * Where this store's things go.
+   *
+   * Synchronous work behind an async port, which is deliberate: the port was shaped
+   * for a child process and stays shaped for one, so a future engine that has to go
+   * to the network for this needs no change above.
+   */
+  public readPaths (
+    store: InstalledStore,
+    progress: EngineProgressListener = {}
+  ): Promise<StorePaths> {
+    return Promise.resolve(this.toPaths(this.openStore(store, progress)))
+  }
+
+  public async syncGames (
+    store: InstalledStore,
+    names: readonly string[],
+    progress: EngineProgressListener = {}
+  ): Promise<void> {
+    const engine = this.openStore(store, progress)
+    const survey: CatalogSurvey = engine.surveyor.survey(
+      await this.readEntries(engine), this.hosts.findHost())
+    for (const reason of survey.skipped) engine.log(`skipped ${reason}`)
+
+    const wanted = names.length > 0 ? limitToNames(survey.games, names) : survey.games
+    const installed = engine.state.readState()
+    // Pruning is for a full sync only: asked for two titles, the store must not take
+    // the absence of the rest as a reason to uninstall them.
+    const prune = engine.configuration.behavior.prune && names.length === 0
+
+    const changed = await engine.installer.installAll(
+      engine.layout, wanted, installed, prune, progress)
+    engine.state.writeState(installed)
+    if (!changed) {
+      engine.log('already up to date')
+      return
+    }
+    engine.launchers.refreshMenu(engine.layout)
+    engine.log(`done — the games are in ${engine.layouts.menuGroup(engine.layout)}`)
+  }
+
+  public removeGame (
+    store: InstalledStore,
+    name: string,
+    progress: EngineProgressListener = {}
+  ): Promise<void> {
+    const engine = this.openStore(store, progress)
+    const installed = engine.state.readState()
+    const keys = matchStateKeys(installed, [name])
+    if (keys.length === 0) {
+      engine.log(`not installed: ${name}`)
+      return Promise.resolve()
+    }
+    for (const key of keys) {
+      const record = installed.get(key)
+      if (record === undefined) continue
+      engine.installer.removeGame(engine.layout, record)
+      progress.onEvent?.({ event: 'removed', name: record.name })
+      installed.delete(key)
+    }
+    engine.state.writeState(installed)
+    engine.launchers.refreshMenu(engine.layout)
+    return Promise.resolve()
+  }
+
+  /**
+   * Take a whole store off this machine.
+   *
+   * The order is the whole of it. `state.json` is the only record of what this store
+   * put where — which payload, which icon, which menu entry — so the games have to go
+   * *before* the home does. Delete the home first and every one of those files is an
+   * orphan nothing will ever be able to identify, least of all a later install of the
+   * same store into the same folder.
+   *
+   * The token goes too: a credential for a store that is no longer here is a secret
+   * kept for nothing.
+   */
+  public removeStore (store: InstalledStore, progress: EngineProgressListener = {}): Promise<void> {
+    const engine = this.openStore(store, progress)
+    const installed = engine.state.readState()
+    const count = installed.size
+
+    engine.installer.purge(engine.layout, installed)
+    engine.state.writeState(installed)
+    engine.launchers.refreshMenu(engine.layout)
+    engine.log(`removed ${String(count)} installed title(s)`)
+
+    this.credentials.clearToken(store.id)
+    this.stores.removeHome(store.home)
+    engine.log(`removed the store home ${store.home}`)
+    return Promise.resolve()
+  }
+
+  public async readAccount (store: InstalledStore): Promise<StoreAccount> {
+    const engine = this.openStore(store, {})
+    const descriptor = await engine.service.fetchDescriptor()
+    return toAccount(descriptor, this.credentials.readToken(store.id))
+  }
+
+  public async requestSignIn (store: InstalledStore, clientName: string): Promise<SignInPrompt> {
+    const { client } = await this.openSignIn(store)
+    const requested = await client.requestCode(clientName)
+    return {
+      deviceCode: requested.deviceCode,
+      userCode: requested.userCode,
+      verificationUrl: requested.verificationUrl,
+      intervalSeconds: requested.intervalSeconds,
+      expiresInSeconds: requested.expiresInSeconds
+    }
+  }
+
+  /**
+   * One poll. The token is written here, on the single answer that carries it — a
+   * caller that had to remember to save it would eventually forget.
+   */
+  public async pollSignIn (store: InstalledStore, deviceCode: string): Promise<SignInPollResult> {
+    const { client, descriptor, log } = await this.openSignIn(store)
+    const result = await client.poll(deviceCode)
+    if (result.state === 'approved' && result.token !== null) {
+      this.credentials.writeToken(store.id, result.token)
+      log('signed in')
+    }
+    return {
+      state: result.state,
+      account: toAccount(descriptor, this.credentials.readToken(store.id))
+    }
+  }
+
+  /**
+   * Sign out: tell the server, then forget the token locally regardless.
+   *
+   * The local half is what matters and must not depend on the network — somebody
+   * signing out on a train has to actually be signed out.
+   */
+  public async signOut (store: InstalledStore): Promise<StoreAccount> {
+    const engine = this.openStore(store, {})
+    const descriptor = await engine.service.fetchDescriptor()
+    if (descriptor.auth !== null && this.credentials.readToken(store.id) !== null) {
+      await new DeviceSignInClient(engine.catalog.httpClient(), descriptor.auth.device).revoke()
+    }
+    this.credentials.clearToken(store.id)
+    engine.log('signed out')
+    return toAccount(descriptor, null)
+  }
+
+  /** The sign-in client for one store, or a clear error if the store offers none. */
+  private async openSignIn (store: InstalledStore): Promise<SignInContext> {
+    const engine = this.openStore(store, {})
+    const descriptor = await engine.service.fetchDescriptor()
+    if (descriptor.auth === null) {
+      throw new Error(`${store.name} does not offer signing in`)
+    }
+    return {
+      client: new DeviceSignInClient(engine.catalog.httpClient(), descriptor.auth.device),
+      descriptor,
+      log: engine.log
+    }
+  }
+
+  /**
+   * Fetch the catalog and read it with the dialect its engine version calls for.
+   *
+   * This is the one place a WarpEngine version turns into behaviour: the header decides
+   * which dialect parses the response, and everything downstream sees typed entries.
+   */
+  private async readEntries (engine: StoreEngineContext): Promise<readonly CatalogEntry[]> {
+    const fetched: FetchedCatalog = await engine.catalog.fetchCatalog()
+    return selectCatalogDialect(fetched.engineVersion.resolved).listEntries(fetched.catalog)
+  }
+
+  /**
+   * Assemble the engine for one store.
+   *
+   * Per call rather than cached: the config on disk is the authority and the user may
+   * have edited it, and a store's home is cheap to read.
+   */
+  private openStore (store: InstalledStore, progress: EngineProgressListener): StoreEngineContext {
+    const log = (line: string): void => { progress.onLog?.(`[${store.id}-store] ${line}`) }
+    const files = new StoreFileSystem(`${store.id}-store`, log)
+    const configuration = new StoreConfigurationReader(files).readConfiguration(store.configPath)
+
+    const layouts = new DesktopLayoutResolver(configuration, this.hosts)
+    const layout = layouts.resolveLayout()
+    const catalog = new CatalogClient(
+      configuration, files, path.join(store.home, CATALOG_CACHE_FILE_NAME), log,
+      (): string | null => this.credentials.readToken(store.id))
+    const launchers = new LauncherWriter(configuration, layouts, files, log)
+
+    return {
+      configuration,
+      layout,
+      layouts,
+      catalog,
+      launchers,
+      log,
+      service: new ServiceDescriptorClient(catalog.httpClient(), configuration.store.baseUrl, log),
+      surveyor: new CatalogSurveyor(configuration, log),
+      state: new StoreStateRepository(files, path.join(store.home, STATE_FILE_NAME), log),
+      installer: new GameInstaller(
+        configuration, layouts,
+        new PayloadInstaller(catalog, files, log),
+        launchers, catalog, files, log)
+    }
+  }
+
+  private toGame (
+    engine: StoreEngineContext,
+    game: SelectedGame,
+    installed: ReadonlyMap<string, InstalledRecord>
+  ): Game {
+    const record = installed.get(gameKey(game)) ?? null
+    return {
+      name: game.name,
+      title: game.title,
+      platform: game.platform,
+      version: game.version,
+      mode: toMode(game.mode),
+      kind: game.kind,
+      description: game.description,
+      author: game.author,
+      imagePath: game.imageUrl,
+      installed: record !== null,
+      updateAvailable: record !== null && record.asset !== game.asset,
+      installedVersion: record?.version ?? null,
+      menuEntryPath: record?.menuEntry ?? null,
+      executablePath: record?.executable ?? null,
+      // The catalog's own play address wins where it gives one: a store that gates its
+      // web builds serves them from a page that knows how to ask somebody to sign in,
+      // and the raw /file/ directory under it does not.
+      hostedUrl: game.mode === WEB_MODE
+        ? game.access?.webUrl ?? engine.launchers.webUrl(game)
+        : null,
+      installable: true,
+      unavailableReason: null,
+      unavailableDetail: null,
+      access: game.access
+    }
+  }
+
+  private toPaths (engine: StoreEngineContext): StorePaths {
+    const host = this.hosts.findHost()
+    return {
+      operatingSystem: engine.layout.operatingSystem,
+      architecture: host.architecture,
+      installRoot: engine.layout.installRoot,
+      menuDirectory: engine.layout.menuDirectory,
+      storeFolder: engine.layouts.ownedRoot(engine.layout),
+      menuGroup: engine.layouts.menuGroup(engine.layout),
+      catalogBaseUrl: engine.configuration.store.baseUrl,
+      storeName: engine.configuration.store.name,
+      storeId: engine.configuration.store.id
+    }
+  }
+}
+
+/** Everything one store's operations need, assembled from its home. */
+interface StoreEngineContext {
+  readonly configuration: StoreConfiguration
+  readonly layout: DesktopLayout
+  readonly layouts: DesktopLayoutResolver
+  readonly catalog: CatalogClient
+  readonly service: ServiceDescriptorClient
+  readonly launchers: LauncherWriter
+  readonly surveyor: CatalogSurveyor
+  readonly state: StoreStateRepository
+  readonly installer: GameInstaller
+  readonly log: (line: string) => void
+}
+
+/**
+ * A title this machine cannot install, in the same shape as an installable one.
+ *
+ * The mode is `app` for want of a truer answer: a title with no build has no mode,
+ * and nothing reads this one because `installable` is false.
+ */
+function toUnavailableGame (entry: UnavailableEntry): Game {
+  return {
+    name: entry.name,
+    title: entry.title,
+    platform: entry.platform,
+    version: entry.version,
+    mode: APP_MODE,
+    kind: '',
+    description: entry.description,
+    author: entry.author,
+    imagePath: entry.imageUrl,
+    installed: false,
+    updateAvailable: false,
+    installedVersion: null,
+    menuEntryPath: null,
+    executablePath: null,
+    hostedUrl: null,
+    installable: false,
+    unavailableReason: entry.reason,
+    unavailableDetail: entry.detail,
+    access: entry.access
+  }
+}
+
+interface SignInContext {
+  readonly client: DeviceSignInClient
+  readonly descriptor: ServiceDescriptor
+  readonly log: (line: string) => void
+}
+
+/**
+ * Holding a token for a store that has no sign-in is not being signed in.
+ *
+ * It happens: a store can lose its identity configuration, or a client can keep a token
+ * from before. Reporting it as signed in would offer a "sign out" for a door that is no
+ * longer there.
+ */
+function toAccount (descriptor: ServiceDescriptor, token: string | null): StoreAccount {
+  const available = descriptor.auth !== null
+  return { signInAvailable: available, signedIn: available && token !== null }
+}
+
+/**
+ * Removing a store needs the repository that found it; nothing else here does.
+ *
+ * The default refuses rather than pretending. A gateway assembled without one — the
+ * smoke test — reads catalogs perfectly well, and should say so plainly if somebody
+ * asks it to delete something, instead of silently doing nothing.
+ */
+const NO_STORES: InstalledStoreRepository = {
+  findAll: (): readonly [] => [],
+  findByHome: (): null => null,
+  readRoots: (): readonly [] => [],
+  resolveDefaultHome: (storeId: string): string => storeId,
+  removeHome: (): never => { throw new Error('this gateway was built without a store repository') }
+}
+
+/**
+ * A client with nowhere to keep a token is a client that is never signed in.
+ *
+ * The two writers throw nothing away and record nothing: this is the shape the smoke
+ * test runs in, where there is no Electron and therefore no keychain, and a store with
+ * no sign-in behaves exactly as it always did.
+ */
+const NO_CREDENTIALS: CredentialRepository = {
+  readToken: (): null => null,
+  writeToken: (storeId: string, token: string): void => { void storeId; void token },
+  clearToken: (storeId: string): void => { void storeId }
+}
+
+function toMode (mode: string): GameMode {
+  return mode === WEB_MODE ? WEB_MODE : APP_MODE
+}

src/infrastructure/engine/PayloadInstaller.ts

@@ -0,0 +1,159 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { SelectedGame } from '../../domain/models/SelectedGame'
+import { ZipArchive } from '../archive/ZipArchive'
+import type { StoreFileSystem } from '../files/StoreFileSystem'
+import type { CatalogClient } from './CatalogClient'
+
+/** Files that are never the program: data, libraries and documentation. */
+const NEVER_A_PROGRAM: readonly string[] =
+  ['.txt', '.md', '.json', '.so', '.dll', '.dylib', '.pck', '.dat']
+
+export type ExecutableKind = 'bundle' | 'exe'
+
+export interface FoundProgram {
+  readonly kind: ExecutableKind
+  readonly executablePath: string
+}
+
+/**
+ * Getting a native build onto the disk and finding what to launch in it.
+ *
+ * The archive is downloaded to a part file beside the payload and unpacked only once
+ * it is complete, and the payload directory is replaced rather than merged: a build
+ * that dropped a file between releases would otherwise keep the old one around and
+ * the game would load it.
+ */
+export class PayloadInstaller {
+  public constructor (
+    private readonly catalog: CatalogClient,
+    private readonly files: StoreFileSystem,
+    private readonly log: (line: string) => void
+  ) {}
+
+  /** Download and unpack into `destination`. Returns bytes downloaded. */
+  public async unpack (game: SelectedGame, destination: string): Promise<number> {
+    const parent = path.dirname(destination)
+    fs.mkdirSync(parent, { recursive: true })
+    const archivePath = this.files.temporaryPath(parent, game.name, '.zip')
+
+    try {
+      const size = await this.catalog.downloadAsset(game.asset, archivePath)
+      fs.rmSync(destination, { recursive: true, force: true })
+      fs.mkdirSync(destination, { recursive: true })
+      ZipArchive.open(archivePath).extractAll(destination)
+      return size
+    } finally {
+      fs.rmSync(archivePath, { force: true })
+    }
+  }
+
+  /**
+   * The thing to launch inside an unpacked payload.
+   *
+   * A `bundle` is a macOS `.app` the archive already contained — a LÖVE or Godot
+   * build ships one — and then it *is* the launcher rather than something to wrap.
+   * Otherwise the answer is a single executable, and "single" is the whole
+   * difficulty: an archive holding one candidate is unambiguous, and where there are
+   * several the one named after the game wins. Anything else is reported as not
+   * found, because launching the wrong binary is worse than failing the install.
+   */
+  public findProgram (root: string, name: string, operatingSystem: string): FoundProgram | null {
+    if (operatingSystem === 'darwin') {
+      const bundle = this.findBundle(root)
+      if (bundle !== null) return { kind: 'bundle', executablePath: bundle }
+    }
+
+    const executables: string[] = []
+    const namedAfterTheGame: string[] = []
+
+    this.walk(root, (filePath: string): void => {
+      const fileName = path.basename(filePath)
+      const lowered = fileName.toLowerCase()
+      if (NEVER_A_PROGRAM.some((extension: string): boolean => lowered.endsWith(extension))) return
+
+      if (operatingSystem === 'windows') {
+        if (lowered.endsWith('.exe')) executables.push(filePath)
+      } else if (isExecutable(filePath)) {
+        executables.push(filePath)
+      }
+      if (stem(fileName) === name) namedAfterTheGame.push(filePath)
+    })
+
+    for (const candidates of [executables, namedAfterTheGame]) {
+      if (candidates.length === 1 && candidates[0] !== undefined) {
+        return { kind: 'exe', executablePath: candidates[0] }
+      }
+      const exact = candidates.filter((candidate: string): boolean =>
+        stem(path.basename(candidate)) === name)
+      if (exact.length === 1 && exact[0] !== undefined) {
+        return { kind: 'exe', executablePath: exact[0] }
+      }
+    }
+    this.log(`found no single program to launch inside ${root}`)
+    return null
+  }
+
+  /** The shallowest `.app`, without descending into one we have already found. */
+  private findBundle (root: string): string | null {
+    let level = [root]
+    while (level.length > 0) {
+      const next: string[] = []
+      for (const directory of level) {
+        const bundles = readDirectories(directory)
+          .filter((entry: string): boolean => entry.endsWith('.app')).sort()
+        const first = bundles[0]
+        if (first !== undefined) return path.join(directory, first)
+        for (const entry of readDirectories(directory)) next.push(path.join(directory, entry))
+      }
+      level = next
+    }
+    return null
+  }
+
+  /** Every file under `root`, never entering a `.app` bundle. */
+  private walk (root: string, visit: (filePath: string) => void): void {
+    const pending = [root]
+    while (pending.length > 0) {
+      const directory = pending.pop()
+      if (directory === undefined) continue
+      let entries: fs.Dirent[]
+      try {
+        entries = fs.readdirSync(directory, { withFileTypes: true })
+      } catch {
+        continue
+      }
+      for (const entry of entries) {
+        const full = path.join(directory, entry.name)
+        if (entry.isDirectory()) {
+          if (!entry.name.endsWith('.app')) pending.push(full)
+        } else if (entry.isFile()) {
+          visit(full)
+        }
+      }
+    }
+  }
+}
+
+function readDirectories (directory: string): readonly string[] {
+  try {
+    return fs.readdirSync(directory, { withFileTypes: true })
+      .filter((entry: fs.Dirent): boolean => entry.isDirectory())
+      .map((entry: fs.Dirent): string => entry.name)
+  } catch {
+    return []
+  }
+}
+
+function isExecutable (filePath: string): boolean {
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function stem (fileName: string): string {
+  return path.basename(fileName, path.extname(fileName))
+}

src/infrastructure/engine/ReleasePicker.ts

@@ -0,0 +1,55 @@
+import path from 'node:path'
+import type { CatalogRelease } from './dialects/CatalogDialect'
+
+export interface PickedRelease {
+  readonly version: string
+  readonly createdAt: string | null
+  readonly assetName: string
+  readonly kind: string
+  readonly assetPath: string
+}
+
+/** `/file/blessingofra-2.0.0.prg` -> `blessingofra-2.0.0.prg`. */
+export function assetBasename (assetPath: string): string {
+  return path.posix.basename(assetPath.replace(/\/+$/, ''))
+}
+
+/**
+ * The newest non-dev release that carries an asset kind we can use.
+ *
+ * The candidates arrive newest-first from the dialect, which is where knowing that the
+ * API sorts them lives. Two rules decide the rest:
+ *
+ * **Release order wins over kind order.** The newest release that has *any* acceptable
+ * kind is taken, and within it the most preferred kind. That is what a desktop host
+ * wants: on Apple Silicon `mac_universal` beats `mac_x64`, which would need Rosetta,
+ * but not at the price of installing an older release.
+ *
+ * **A `dev-` build is never taken.** It is a moving target, and installing one would
+ * leave a menu entry pointing at an archive that is replaced without a version change.
+ */
+export function pickRelease (
+  candidates: readonly CatalogRelease[],
+  kinds: readonly string[],
+  extension: string
+): PickedRelease | null {
+  for (const release of candidates) {
+    if (release.version.startsWith('dev-')) continue
+    for (const kind of kinds) {
+      for (const asset of release.assets) {
+        if (asset.kind !== kind) continue
+        const assetName = assetBasename(asset.path)
+        if (assetName.length === 0) continue
+        if (extension.length > 0 && !assetName.toLowerCase().endsWith(extension.toLowerCase())) continue
+        return {
+          version: release.version,
+          createdAt: release.createdAt,
+          assetName,
+          kind,
+          assetPath: asset.path
+        }
+      }
+    }
+  }
+  return null
+}

src/infrastructure/engine/ServiceDescriptorClient.ts

@@ -0,0 +1,89 @@
+import {
+  DEFAULT_SERVICE_DESCRIPTOR, type AuthDescriptor, type DeviceAuthDescriptor,
+  type ServiceDescriptor
+} from '../../domain/models/ServiceDescriptor'
+import { HttpStatusError } from '../http/HttpTextClient'
+import type { StoreHttpClient } from '../http/StoreHttpClient'
+import { asRecord, readBoolean, readNumber, readOptionalString, readRecord } from '../json/JsonRecord'
+
+const SERVICE_PATH = '/api/service'
+
+/**
+ * `GET /api/service`: what this catalog's server is, asked before anything else.
+ *
+ * A missing descriptor is an answer, not a failure. Every WarpEngine before 0.5 has no
+ * such endpoint, so a 404 means "an older engine" — a plain catalog with nothing gated
+ * and nobody to sign in as, which is exactly what this client assumed for its whole
+ * life before now. Same for a network that is simply down: the store still works
+ * offline from its cached catalog, and refusing to open because we could not ask the
+ * server about itself would be a worse client than the one we had.
+ */
+export class ServiceDescriptorClient {
+  public constructor (
+    private readonly http: StoreHttpClient,
+    private readonly baseUrl: string,
+    private readonly log: (line: string) => void
+  ) {}
+
+  public async fetchDescriptor (): Promise<ServiceDescriptor> {
+    const url = `${this.baseUrl}${SERVICE_PATH}`
+    try {
+      const { json } = await this.http.requestJson(url)
+      const record = asRecord(json)
+      if (record === null) return DEFAULT_SERVICE_DESCRIPTOR
+
+      const descriptor: ServiceDescriptor = {
+        engineVersion: readOptionalString(record, 'version'),
+        catalogGated: readBoolean(readRecord(record, 'catalog') ?? {}, 'gated', false),
+        auth: readAuth(record, this.baseUrl)
+      }
+      this.log(describe(descriptor))
+      return descriptor
+    } catch (error: unknown) {
+      if (error instanceof HttpStatusError && error.statusCode === 404) {
+        this.log('the catalog has no service descriptor — an engine older than 0.5')
+      } else {
+        this.log(`warning: could not read ${url} — carrying on as a plain catalog`)
+      }
+      return DEFAULT_SERVICE_DESCRIPTOR
+    }
+  }
+}
+
+function readAuth (record: Readonly<Record<string, unknown>>, baseUrl: string): AuthDescriptor | null {
+  const auth = readRecord(record, 'auth')
+  if (auth === null) return null
+
+  const device = readRecord(auth, 'device')
+  if (device === null) return null
+
+  const authorizeUrl = absolute(readOptionalString(device, 'authorizeUrl'), baseUrl)
+  const tokenUrl = absolute(readOptionalString(device, 'tokenUrl'), baseUrl)
+  const verificationUrl = absolute(readOptionalString(device, 'verificationUrl'), baseUrl)
+  // Two of the three are the flow itself and the third is where a person goes. Without
+  // all three there is no sign-in to offer, and half a flow is worse than none.
+  if (authorizeUrl === null || tokenUrl === null || verificationUrl === null) return null
+
+  const descriptor: DeviceAuthDescriptor = {
+    authorizeUrl,
+    tokenUrl,
+    revokeUrl: absolute(readOptionalString(device, 'revokeUrl'), baseUrl),
+    verificationUrl,
+    interval: Math.max(1, readNumber(device, 'interval', 5))
+  }
+  return { device: descriptor }
+}
+
+/** A server may answer with a path; it knows its own address better than we do. */
+function absolute (value: string | null, baseUrl: string): string | null {
+  if (value === null || value.length === 0) return null
+  if (value.startsWith('http://') || value.startsWith('https://')) return value
+  return `${baseUrl.replace(/\/+$/, '')}/${value.replace(/^\/+/, '')}`
+}
+
+function describe (descriptor: ServiceDescriptor): string {
+  const version = descriptor.engineVersion ?? 'an unnamed version'
+  const gated = descriptor.catalogGated ? 'some titles need an entitlement' : 'nothing is gated'
+  const auth = descriptor.auth === null ? 'no sign-in' : 'sign-in available'
+  return `catalog served by WarpEngine ${version} — ${gated}, ${auth}`
+}

src/infrastructure/engine/StoreConfigurationReader.ts

@@ -0,0 +1,148 @@
+import type { HostSpecific } from '../../domain/models/HostMachine'
+import {
+  APP_MODE, DEFAULT_STORE_CONFIGURATION, WEB_MODE,
+  type AssetSpecification, type BehaviorConfiguration, type CatalogConfiguration,
+  type InstallConfiguration, type PathsConfiguration, type PlatformConfiguration,
+  type StoreConfiguration, type StoreDescriptor
+} from '../../domain/models/StoreConfiguration'
+import {
+  asRecord, readBoolean, readNumber, readOptionalString, readRecord, readString,
+  readStringArray, type JsonRecord
+} from '../json/JsonRecord'
+import type { StoreFileSystem } from '../files/StoreFileSystem'
+
+/**
+ * A store's `config.json`, read onto the defaults.
+ *
+ * The file is **snake_case** and this is the only place that knows it: that is the
+ * format the store repositories publish, and it stays the format on disk so a store
+ * config written for the shell engine is still a valid config here. Rename a field
+ * there and this reader is the single file that follows.
+ *
+ * Reading replaces the deep merge the shell engine did: every field states its own
+ * default, so a config that omits a section gets the whole section rather than a
+ * half-populated one.
+ */
+export class StoreConfigurationReader {
+  public constructor (private readonly files: StoreFileSystem) {}
+
+  public readConfiguration (configPath: string): StoreConfiguration {
+    const record = asRecord(this.files.readJson(configPath)) ?? {}
+    return {
+      store: readStore(readRecord(record, 'store') ?? {}),
+      paths: readPaths(readRecord(record, 'paths') ?? {}),
+      install: readInstall(readRecord(record, 'install') ?? {}),
+      catalog: readCatalog(readRecord(record, 'catalog') ?? {}),
+      platforms: readPlatforms(readRecord(record, 'platforms')),
+      behavior: readBehavior(readRecord(record, 'behavior') ?? {})
+    }
+  }
+}
+
+function readStore (record: JsonRecord): StoreDescriptor {
+  const defaults = DEFAULT_STORE_CONFIGURATION.store
+  const api = readRecord(record, 'api') ?? {}
+  return {
+    id: readString(record, 'id', defaults.id),
+    name: readString(record, 'name', defaults.name),
+    // Trailing slashes are stripped once, here, so every URL built from it joins
+    // with exactly one separator.
+    baseUrl: readString(record, 'base_url', defaults.baseUrl).replace(/\/+$/, ''),
+    api: {
+      catalog: readString(api, 'catalog', defaults.api.catalog),
+      download: readString(api, 'download', defaults.api.download)
+    }
+  }
+}
+
+function readPaths (record: JsonRecord): PathsConfiguration {
+  const defaults = DEFAULT_STORE_CONFIGURATION.paths
+  return {
+    installRoot: readOptionalString(record, 'install_root'),
+    menuDirectory: readOptionalString(record, 'menu_dir'),
+    iconDirectory: readOptionalString(record, 'icon_dir'),
+    subfolder: readString(record, 'subfolder', defaults.subfolder)
+  }
+}
+
+function readInstall (record: JsonRecord): InstallConfiguration {
+  const defaults = DEFAULT_STORE_CONFIGURATION.install
+  const modes = readStringArray(record, 'modes')
+  const specifications: Record<string, AssetSpecification> = {}
+
+  for (const [key, value] of Object.entries(record)) {
+    if (key === 'modes') continue
+    const specification = asRecord(value)
+    if (specification === null) continue
+    specifications[key] = {
+      kind: readAssetKind(specification['kind']),
+      extension: readHostSpecificString(specification['ext'])
+    }
+  }
+  for (const mode of [APP_MODE, WEB_MODE]) {
+    specifications[mode] ??= defaults.specifications[mode] ?? { kind: null, extension: null }
+  }
+
+  return { modes: modes.length > 0 ? modes : defaults.modes, specifications }
+}
+
+function readCatalog (record: JsonRecord): CatalogConfiguration {
+  const defaults = DEFAULT_STORE_CONFIGURATION.catalog
+  const statuses = readStringArray(record, 'statuses')
+  const ownerId = record['owner_id']
+  return {
+    // An explicit empty list means "every status", so only a missing key falls back.
+    statuses: record['statuses'] === undefined ? defaults.statuses : statuses,
+    ownerId: typeof ownerId === 'number' && Number.isFinite(ownerId) ? ownerId : null,
+    only: readStringArray(record, 'only'),
+    exclude: readStringArray(record, 'exclude')
+  }
+}
+
+function readPlatforms (record: JsonRecord | null): Readonly<Record<string, PlatformConfiguration>> {
+  if (record === null) return DEFAULT_STORE_CONFIGURATION.platforms
+  const platforms: Record<string, PlatformConfiguration> = {}
+  for (const [name, value] of Object.entries(record)) {
+    const entry = asRecord(value)
+    platforms[name] = { enabled: entry === null ? true : readBoolean(entry, 'enabled', true) }
+  }
+  return platforms
+}
+
+function readBehavior (record: JsonRecord): BehaviorConfiguration {
+  const defaults = DEFAULT_STORE_CONFIGURATION.behavior
+  return {
+    prune: readBoolean(record, 'prune', defaults.prune),
+    timeout: readNumber(record, 'timeout', defaults.timeout),
+    insecure: readBoolean(record, 'insecure', defaults.insecure)
+  }
+}
+
+/** `"linux_x64"`, `["win_x64", "win_x86"]`, or either of those keyed by host. */
+function readAssetKind (value: unknown): HostSpecific<string | readonly string[]> | null {
+  if (typeof value === 'string') return value
+  if (Array.isArray(value)) return readStrings(value)
+  const record = asRecord(value)
+  if (record === null) return null
+  const map: Record<string, string | readonly string[]> = {}
+  for (const [key, entry] of Object.entries(record)) {
+    if (typeof entry === 'string') map[key] = entry
+    else if (Array.isArray(entry)) map[key] = readStrings(entry)
+  }
+  return map
+}
+
+function readHostSpecificString (value: unknown): HostSpecific<string> | null {
+  if (typeof value === 'string') return value
+  const record = asRecord(value)
+  if (record === null) return null
+  const map: Record<string, string> = {}
+  for (const [key, entry] of Object.entries(record)) {
+    if (typeof entry === 'string') map[key] = entry
+  }
+  return map
+}
+
+function readStrings (values: readonly unknown[]): readonly string[] {
+  return values.filter((item: unknown): item is string => typeof item === 'string')
+}

src/infrastructure/engine/StoreStateRepository.ts

@@ -0,0 +1,114 @@
+import {
+  gameKey, recordScope, type InstalledRecord
+} from '../../domain/models/InstalledRecord'
+import {
+  asRecord, readOptionalString, readString, type JsonRecord
+} from '../json/JsonRecord'
+import type { StoreFileSystem } from '../files/StoreFileSystem'
+
+/** Bumped when the on-disk shape changes. v1 keyed `installed` by bare software name. */
+const STATE_VERSION = 2
+
+/**
+ * `state.json`: what this store put on this machine, and where.
+ *
+ * The file is **snake_case**, and deliberately so: it is the same file the shell
+ * store engine wrote, so a machine that installed games through the CLI keeps its
+ * library when the client takes over. This class is the only place that knows the
+ * on-disk field names — everything above it sees `InstalledRecord`.
+ *
+ * A `version: 1` file, keyed by bare software name, is re-keyed on first read.
+ */
+export class StoreStateRepository {
+  public constructor (
+    private readonly files: StoreFileSystem,
+    private readonly statePath: string,
+    private readonly log: (line: string) => void
+  ) {}
+
+  public readState (): Map<string, InstalledRecord> {
+    const state = asRecord(this.files.readJson(this.statePath))
+    if (state === null) return new Map<string, InstalledRecord>()
+    const installed = asRecord(state['installed'])
+    if (installed === null) return new Map<string, InstalledRecord>()
+
+    const version = state['version']
+    if (version === 1) return this.migrateFromVersionOne(installed)
+    if (version !== STATE_VERSION) return new Map<string, InstalledRecord>()
+
+    const records = new Map<string, InstalledRecord>()
+    for (const [key, value] of Object.entries(installed)) {
+      const record = asRecord(value)
+      if (record !== null) records.set(key, toRecord(record))
+    }
+    return records
+  }
+
+  public writeState (installed: ReadonlyMap<string, InstalledRecord>): void {
+    const serialised: Record<string, JsonRecord> = {}
+    for (const [key, record] of installed) serialised[key] = fromRecord(record)
+    this.files.writeJson(this.statePath, { version: STATE_VERSION, installed: serialised })
+  }
+
+  private migrateFromVersionOne (installed: JsonRecord): Map<string, InstalledRecord> {
+    const records = new Map<string, InstalledRecord>()
+    for (const value of Object.values(installed)) {
+      const raw = asRecord(value)
+      if (raw === null) continue
+      const record = toRecord(raw)
+      if (record.name.length > 0 && record.scope.length > 0) records.set(gameKey(record), record)
+    }
+    this.log(`migrated ${String(records.size)} state entries to the per-scope key format`)
+    return records
+  }
+}
+
+function toRecord (raw: JsonRecord): InstalledRecord {
+  return {
+    name: readString(raw, 'name'),
+    // `system` is what the Batocera store wrote before the shared core existed, and
+    // there the two were the same string — so an installed machine needs no migration.
+    scope: recordScope(readOptionalString(raw, 'scope'), readOptionalString(raw, 'system')),
+    platform: readString(raw, 'platform'),
+    kind: readString(raw, 'kind'),
+    version: readString(raw, 'version'),
+    asset: readString(raw, 'asset'),
+    assetPath: readString(raw, 'asset_path'),
+    title: readString(raw, 'title'),
+    description: readString(raw, 'desc'),
+    author: readString(raw, 'author'),
+    imageUrl: readOptionalString(raw, 'image_url'),
+    createdAt: readOptionalString(raw, 'created_at'),
+    mode: readString(raw, 'mode'),
+    payload: readOptionalString(raw, 'payload'),
+    executable: readOptionalString(raw, 'exe'),
+    executableKind: readOptionalString(raw, 'exe_kind'),
+    icon: readOptionalString(raw, 'icon'),
+    menuEntry: readOptionalString(raw, 'menu'),
+    url: readOptionalString(raw, 'url')
+  }
+}
+
+function fromRecord (record: InstalledRecord): JsonRecord {
+  return {
+    name: record.name,
+    scope: record.scope,
+    platform: record.platform,
+    kind: record.kind,
+    version: record.version,
+    asset: record.asset,
+    asset_path: record.assetPath,
+    title: record.title,
+    desc: record.description,
+    author: record.author,
+    image_url: record.imageUrl,
+    created_at: record.createdAt,
+    mode: record.mode,
+    payload: record.payload,
+    exe: record.executable,
+    exe_kind: record.executableKind,
+    icon: record.icon,
+    menu: record.menuEntry,
+    url: record.url
+  }
+}

src/infrastructure/engine/dialects/AccessAwareCatalogDialect.ts

@@ -0,0 +1,57 @@
+import {
+  readBoolean, readNumber, readOptionalString, readRecord, readString, type JsonRecord
+} from '../../json/JsonRecord'
+import type { CatalogAccess, CatalogPrice } from '../../../domain/models/CatalogAccess'
+import { SoftwareListCatalogDialect } from './SoftwareListCatalogDialect'
+
+/**
+ * The catalog as WarpEngine 0.5 serves it: the same entries, plus what they cost.
+ *
+ * 0.5 is the first engine that can say a title is not yours. Every entry carries an
+ * `access` block — even in a catalog that gates nothing, so that "this store is open"
+ * and "this store did not say" stay tellable apart. Everything else about the shape is
+ * unchanged, which is why this is the older dialect with one field added rather than a
+ * parser of its own.
+ *
+ * The words are the engine's, not any store's. A client reads more than one catalog,
+ * and a field named after what one shop calls its wares is a field that only works
+ * there.
+ */
+export class AccessAwareCatalogDialect extends SoftwareListCatalogDialect {
+  protected override readAccess (entry: JsonRecord): CatalogAccess | null {
+    const access = readRecord(entry, 'access')
+    // An entry with no block at all: possible from a 0.5 engine whose policy failed to
+    // answer. Reading it as "open" would be inventing the friendlier of two answers.
+    if (access === null) return null
+
+    return {
+      gated: readBoolean(access, 'gated', false),
+      entitled: readNullableBoolean(access, 'entitled'),
+      price: readPrice(access),
+      purchaseUrl: readOptionalString(access, 'purchaseUrl'),
+      webUrl: readOptionalString(access, 'webUrl')
+    }
+  }
+}
+
+/**
+ * Three states, not two: yes, no, and nobody asked.
+ *
+ * A client that is not signed in gets null, and that is the case worth keeping
+ * separate — it is the difference between "you do not own this" and "there is no you",
+ * and only the second is a reason to offer signing in.
+ */
+function readNullableBoolean (record: JsonRecord, key: string): boolean | null {
+  const value = record[key]
+  return typeof value === 'boolean' ? value : null
+}
+
+/** A price with no currency is not a price anybody can be shown. */
+function readPrice (access: JsonRecord): CatalogPrice | null {
+  const price = readRecord(access, 'price')
+  if (price === null) return null
+
+  const currency = readString(price, 'currency')
+  if (currency.length === 0) return null
+  return { amountCents: readNumber(price, 'amountCents'), currency }
+}

src/infrastructure/engine/dialects/CatalogDialect.ts

@@ -0,0 +1,66 @@
+import type { CatalogAccess } from '../../../domain/models/CatalogAccess'
+import type { SupportedWarpEngineVersion } from '../../../domain/models/WarpEngineVersion'
+
+/**
+ * How one WarpEngine version's catalog is shaped.
+ *
+ * The catalog is the one thing this client reads that it does not own the shape of, so
+ * it is the one thing an engine version can change under it. A dialect turns that
+ * foreign JSON into the typed records below, and everything downstream — the survey,
+ * the release choice — sees only those. When a future engine renames a field or nests a
+ * release differently, a new dialect is the whole change.
+ */
+export interface CatalogDialect {
+  readonly version: SupportedWarpEngineVersion
+  /** One entry per title in the catalog. */
+  listEntries: (catalog: unknown) => readonly CatalogEntry[]
+}
+
+export interface CatalogEntry {
+  readonly software: CatalogSoftware
+  /**
+   * What the catalog says about getting this title, or null where it says nothing.
+   *
+   * Null is not "free": it is an engine too old to have an opinion, and a store that
+   * never gated anything reads the same as one that could not say. Both mean the same
+   * thing in practice — try the download — but only one of them is worth offering a
+   * sign-in for.
+   */
+  readonly access: CatalogAccess | null
+  /**
+   * The release the catalog itself calls newest-and-stable, or null when it names none.
+   *
+   * Kept separate from the candidates because it is also what an unavailable title's
+   * card shows a version from — and a catalog with releases but no `latestRelease` has
+   * nothing to show there.
+   */
+  readonly latestRelease: CatalogRelease | null
+  /**
+   * Every release worth trying, newest first and deduplicated.
+   *
+   * `latestRelease` comes first where there is one, then the rest, so that a game whose
+   * newest build is missing an asset still installs from an older one.
+   */
+  readonly releaseCandidates: readonly CatalogRelease[]
+}
+
+export interface CatalogSoftware {
+  readonly name: string
+  readonly title: string
+  readonly platform: string
+  readonly status: string
+  readonly description: string
+  readonly author: string
+  readonly imageUrl: string | null
+}
+
+export interface CatalogRelease {
+  readonly version: string
+  readonly createdAt: string | null
+  readonly assets: readonly CatalogAsset[]
+}
+
+export interface CatalogAsset {
+  readonly kind: string
+  readonly path: string
+}

src/infrastructure/engine/dialects/CatalogDialectSelector.ts

@@ -0,0 +1,26 @@
+import type { SupportedWarpEngineVersion } from '../../../domain/models/WarpEngineVersion'
+import { AccessAwareCatalogDialect } from './AccessAwareCatalogDialect'
+import type { CatalogDialect } from './CatalogDialect'
+import { SoftwareListCatalogDialect } from './SoftwareListCatalogDialect'
+
+/**
+ * Which dialect reads a catalog served by which engine version.
+ *
+ * The switch is exhaustive over `SUPPORTED_WARP_ENGINE_VERSIONS`, which is the whole
+ * mechanism: adding a version to that list stops compiling here until somebody decides
+ * what it reads like. Three versions share one dialect because the catalog's shape did
+ * not change across them — and one class serving three versions is the honest way to
+ * say that, rather than three identical ones pretending otherwise.
+ *
+ * 0.5 gets its own, because that is the engine that started saying what a title costs.
+ */
+export function selectCatalogDialect (version: SupportedWarpEngineVersion): CatalogDialect {
+  switch (version) {
+    case '0.2':
+    case '0.3':
+    case '0.4':
+      return new SoftwareListCatalogDialect(version)
+    case '0.5':
+      return new AccessAwareCatalogDialect(version)
+  }
+}

src/infrastructure/engine/dialects/SoftwareListCatalogDialect.ts

@@ -0,0 +1,126 @@
+import type { SupportedWarpEngineVersion } from '../../../domain/models/WarpEngineVersion'
+import {
+  asRecord, readOptionalString, readRecord, readString, type JsonRecord
+} from '../../json/JsonRecord'
+import type { CatalogAccess } from '../../../domain/models/CatalogAccess'
+import type {
+  CatalogAsset, CatalogDialect, CatalogEntry, CatalogRelease, CatalogSoftware
+} from './CatalogDialect'
+
+/**
+ * The catalog as every WarpEngine from 0.2 to 0.4 serves it.
+ *
+ * `{ softwares: [ { software: {…}, latestRelease: {…}, releases: [ { assets: [] } ] } ] }`,
+ * camelCase throughout. The three versions differ in what they *contain* — 0.3 added
+ * the `linux_arm64` asset kinds, so an older engine simply has fewer kinds to offer,
+ * and that needs no code: an absent kind is a title reported as unavailable on this
+ * machine, which is already the honest answer.
+ *
+ * The version is carried rather than assumed, so a log line can name which dialect read
+ * a catalog even while one class serves several.
+ */
+export class SoftwareListCatalogDialect implements CatalogDialect {
+  public constructor (public readonly version: SupportedWarpEngineVersion) {}
+
+  public listEntries (catalog: unknown): readonly CatalogEntry[] {
+    const record = asRecord(catalog)
+    if (record === null) return []
+    const entries = record['softwares']
+    if (!Array.isArray(entries)) return []
+
+    const found: CatalogEntry[] = []
+    for (const item of entries) {
+      const entry = asRecord(item)
+      if (entry === null) continue
+      const software = this.readSoftware(entry)
+      if (software === null) continue
+      found.push({
+        software,
+        access: this.readAccess(entry),
+        latestRelease: this.readLatestRelease(entry),
+        releaseCandidates: this.readCandidates(entry)
+      })
+    }
+    return found
+  }
+
+  /**
+   * What the catalog says about getting this title. Nothing, at these versions.
+   *
+   * An engine older than 0.5 has no opinion to report, and inventing one here would be
+   * worse than admitting it: "not gated" and "could not say" are different answers, and
+   * only the first is safe to act on. The subclass that can read it overrides this.
+   */
+  protected readAccess (entry: JsonRecord): CatalogAccess | null {
+    void entry
+    return null
+  }
+
+  /** A title with no name is not a title: nothing could be keyed by it. */
+  protected readSoftware (entry: JsonRecord): CatalogSoftware | null {
+    const software = readRecord(entry, 'software')
+    if (software === null) return null
+    const name = readOptionalString(software, 'name')
+    if (name === null) return null
+    return {
+      name,
+      title: readOptionalString(software, 'title') ?? name,
+      platform: readString(software, 'platform'),
+      status: readString(software, 'status'),
+      description: readString(software, 'desc').trim(),
+      author: readString(software, 'author').trim(),
+      imageUrl: readOptionalString(software, 'imageUrl')
+    }
+  }
+
+  protected readLatestRelease (entry: JsonRecord): CatalogRelease | null {
+    const latest = readRecord(entry, 'latestRelease')
+    return latest === null ? null : this.readRelease(latest)
+  }
+
+  /**
+   * The releases to try, newest first and without repeats.
+   *
+   * `releases` arrives newest-first from the API and `latestRelease` is usually its
+   * first element, so identity is settled on the release's own id where it has one.
+   */
+  protected readCandidates (entry: JsonRecord): readonly CatalogRelease[] {
+    const records: JsonRecord[] = []
+    const latest = readRecord(entry, 'latestRelease')
+    if (latest !== null) records.push(latest)
+    const releases = entry['releases']
+    if (Array.isArray(releases)) {
+      for (const item of releases) {
+        const record = asRecord(item)
+        if (record !== null) records.push(record)
+      }
+    }
+
+    const seen = new Set<string>()
+    const candidates: CatalogRelease[] = []
+    for (const record of records) {
+      const identity = JSON.stringify(record['id'] ?? null)
+      if (seen.has(identity)) continue
+      seen.add(identity)
+      candidates.push(this.readRelease(record))
+    }
+    return candidates
+  }
+
+  protected readRelease (release: JsonRecord): CatalogRelease {
+    const assets: CatalogAsset[] = []
+    const listed = release['assets']
+    if (Array.isArray(listed)) {
+      for (const item of listed) {
+        const asset = asRecord(item)
+        if (asset === null) continue
+        assets.push({ kind: readString(asset, 'kind'), path: readString(asset, 'path') })
+      }
+    }
+    return {
+      version: readString(release, 'version'),
+      createdAt: readOptionalString(release, 'createdAt'),
+      assets
+    }
+  }
+}

src/infrastructure/engine/launchers/DesktopEntryWriter.ts

@@ -0,0 +1,45 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { InstalledRecord } from '../../../domain/models/InstalledRecord'
+import { WEB_MODE } from '../../../domain/models/StoreConfiguration'
+import type { StoreFileSystem } from '../../files/StoreFileSystem'
+import { quoteForShell } from './ShellQuoting'
+
+const LAUNCHER_MODE = 0o755
+const COMMENT_LIMIT = 120
+
+/**
+ * Linux: an XDG desktop entry.
+ *
+ * `Path=` is what gives the game its working directory — a Godot or LÖVE build
+ * looks for its `.pck` next to the binary, and started from anywhere else it exits
+ * without a window and without a message.
+ */
+export class DesktopEntryWriter {
+  public constructor (
+    private readonly storeId: string,
+    private readonly files: StoreFileSystem
+  ) {}
+
+  public write (record: InstalledRecord, entryPath: string, webUrl: string): string {
+    const lines: string[] = ['[Desktop Entry]', 'Type=Application', 'Version=1.0', `Name=${record.title}`]
+
+    if (record.description.length > 0) {
+      // One line only, and short: the menu shows it as a tooltip.
+      const firstLine = record.description.split('\n')[0] ?? ''
+      lines.push(`Comment=${firstLine.slice(0, COMMENT_LIMIT)}`)
+    }
+    if (record.mode === WEB_MODE) {
+      lines.push(`Exec=xdg-open ${quoteForShell(webUrl)}`)
+    } else if (record.executable !== null) {
+      lines.push(`Exec=${quoteForShell(record.executable)}`)
+      lines.push(`Path=${quoteForShell(path.dirname(record.executable))}`)
+    }
+    if (record.icon !== null) lines.push(`Icon=${record.icon}`)
+    lines.push('Terminal=false', 'Categories=Game;', `X-WarpStore=${this.storeId}`, '')
+
+    fs.mkdirSync(path.dirname(entryPath), { recursive: true })
+    this.files.writeAtomic(entryPath, Buffer.from(lines.join('\n'), 'utf8'), LAUNCHER_MODE)
+    return entryPath
+  }
+}

src/infrastructure/engine/launchers/LauncherWriter.ts

@@ -0,0 +1,85 @@
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import type { DesktopLayout } from '../../../domain/models/DesktopLayout'
+import { toSafeFileName } from '../../../domain/models/DesktopLayout'
+import type { InstalledRecord } from '../../../domain/models/InstalledRecord'
+import type { SelectedGame } from '../../../domain/models/SelectedGame'
+import type { StoreConfiguration } from '../../../domain/models/StoreConfiguration'
+import type { StoreFileSystem } from '../../files/StoreFileSystem'
+import type { DesktopLayoutResolver } from '../DesktopLayoutResolver'
+import { DesktopEntryWriter } from './DesktopEntryWriter'
+import { MacBundleWriter } from './MacBundleWriter'
+import { WindowsShortcutWriter } from './WindowsShortcutWriter'
+
+const REFRESH_TIMEOUT_MS = 30_000
+
+/**
+ * The menu entry, in whichever form this machine's desktop understands.
+ *
+ * This is the whole point of a desktop store, and the one place where the three
+ * hosts genuinely differ rather than merely differing in paths.
+ */
+export class LauncherWriter {
+  private readonly desktopEntries: DesktopEntryWriter
+  private readonly macBundles: MacBundleWriter
+  private readonly windowsShortcuts: WindowsShortcutWriter
+
+  public constructor (
+    private readonly configuration: StoreConfiguration,
+    private readonly layouts: DesktopLayoutResolver,
+    files: StoreFileSystem,
+    private readonly log: (line: string) => void
+  ) {
+    this.desktopEntries = new DesktopEntryWriter(configuration.store.id, files)
+    this.macBundles = new MacBundleWriter(configuration.store.id, files, log)
+    this.windowsShortcuts = new WindowsShortcutWriter(files, log)
+  }
+
+  /**
+   * The published page of a browser build.
+   *
+   * The catalog serves these as a directory rather than an archive, so the entry is
+   * a link to it — which also means a web title needs the network.
+   */
+  public webUrl (game: SelectedGame | InstalledRecord): string {
+    const assetPath = game.assetPath.length > 0 ? game.assetPath : `/file/${game.asset}`
+    return `${this.configuration.store.baseUrl}/${assetPath.replace(/^\/+|\/+$/g, '')}/`
+  }
+
+  public launcherPath (layout: DesktopLayout, game: SelectedGame | InstalledRecord): string {
+    const group = this.layouts.menuGroup(layout)
+    if (layout.operatingSystem === 'linux') {
+      return path.join(group, `${this.configuration.store.id}-${game.name}.desktop`)
+    }
+    if (layout.operatingSystem === 'darwin') {
+      return path.join(group, `${toSafeFileName(game.title)}.app`)
+    }
+    return path.join(group, `${toSafeFileName(game.title)}.lnk`)
+  }
+
+  /**
+   * Write the menu entry. Returns the path actually written.
+   *
+   * Not always the path we intended: on Windows a `.lnk` can fall back to a `.cmd`,
+   * and the state has to record what really exists or an uninstall would leave it
+   * behind.
+   */
+  public writeLauncher (layout: DesktopLayout, record: InstalledRecord): string {
+    const entryPath = this.launcherPath(layout, record)
+    const url = this.webUrl(record)
+    if (layout.operatingSystem === 'linux') return this.desktopEntries.write(record, entryPath, url)
+    if (layout.operatingSystem === 'darwin') return this.macBundles.write(record, entryPath, url)
+    return this.windowsShortcuts.write(record, entryPath, url)
+  }
+
+  /** Ask the desktop to notice the change, where that is a thing we can do. */
+  public refreshMenu (layout: DesktopLayout): void {
+    if (layout.operatingSystem !== 'linux') return
+    try {
+      spawnSync('update-desktop-database', [layout.menuDirectory], { timeout: REFRESH_TIMEOUT_MS })
+    } catch {
+      // Not every Linux has it, and a menu that updates on next login is fine.
+      this.log('update-desktop-database is not available — the menu may need a re-login')
+    }
+  }
+}

src/infrastructure/engine/launchers/MacBundleWriter.ts

@@ -0,0 +1,148 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import type { InstalledRecord } from '../../../domain/models/InstalledRecord'
+import { WEB_MODE } from '../../../domain/models/StoreConfiguration'
+import type { StoreFileSystem } from '../../files/StoreFileSystem'
+import { escapeForXml, quoteForShell } from './ShellQuoting'
+
+const RUNNER_MODE = 0o755
+const PLIST_MODE = 0o644
+const ICON_SIZE = '512'
+const SIPS_TIMEOUT_MS = 60_000
+const NAME_LIMIT = 255
+
+/**
+ * macOS: link the archive's own bundle, or wrap a bare binary in one.
+ *
+ * A LÖVE or Godot build already ships a signed `.app`; copying it again would double
+ * the disk use and lose nothing but the icon, so it is symlinked instead. A TIC-80
+ * export is a bare executable, and for that a four-file bundle is what makes it
+ * double-clickable and Dock-able.
+ */
+export class MacBundleWriter {
+  public constructor (
+    private readonly storeId: string,
+    private readonly files: StoreFileSystem,
+    private readonly log: (line: string) => void
+  ) {}
+
+  public write (record: InstalledRecord, bundlePath: string, webUrl: string): string {
+    replaceExisting(bundlePath)
+
+    if (record.mode !== WEB_MODE && record.executableKind === 'bundle' && record.executable !== null) {
+      fs.mkdirSync(path.dirname(bundlePath), { recursive: true })
+      fs.symlinkSync(record.executable, bundlePath)
+      return bundlePath
+    }
+
+    const contents = path.join(bundlePath, 'Contents')
+    const macOsDirectory = path.join(contents, 'MacOS')
+    const resources = path.join(contents, 'Resources')
+    fs.mkdirSync(macOsDirectory, { recursive: true })
+    fs.mkdirSync(resources, { recursive: true })
+
+    this.files.writeAtomic(
+      path.join(macOsDirectory, 'run'),
+      Buffer.from(this.runnerScript(record, webUrl), 'utf8'),
+      RUNNER_MODE
+    )
+
+    const iconWritten = this.writeIcon(record.icon, path.join(resources, 'icon.icns'))
+    this.files.writeAtomic(
+      path.join(contents, 'Info.plist'),
+      Buffer.from(this.infoPlist(record, iconWritten), 'utf8'),
+      PLIST_MODE
+    )
+    return bundlePath
+  }
+
+  private runnerScript (record: InstalledRecord, webUrl: string): string {
+    if (record.mode === WEB_MODE || record.executable === null) {
+      return `#!/bin/sh\nexec open ${quoteForShell(webUrl)}\n`
+    }
+    const directory = path.dirname(record.executable)
+    const program = `./${path.basename(record.executable)}`
+    return `#!/bin/sh\ncd ${quoteForShell(directory)} || exit 1\nexec ${quoteForShell(program)} "$@"\n`
+  }
+
+  /**
+   * The bundle's `Info.plist`.
+   *
+   * Keys are emitted in alphabetical order because that is what wrote these files
+   * before — `plistlib` sorts a dict — and a plist dict is unordered, so sorting costs
+   * nothing and makes a bundle regenerated by either engine the same file.
+   */
+  private infoPlist (record: InstalledRecord, iconWritten: boolean): string {
+    const version = record.version.length > 0 ? record.version : '1.0'
+    const name = record.title.slice(0, NAME_LIMIT)
+    const entries: readonly (readonly [string, string])[] = [
+      ['CFBundleName', `<string>${escapeForXml(name)}</string>`],
+      ['CFBundleDisplayName', `<string>${escapeForXml(name)}</string>`],
+      ['CFBundleExecutable', '<string>run</string>'],
+      ['CFBundleIdentifier', `<string>org.${this.storeId}.store.${record.name}</string>`],
+      ['CFBundleInfoDictionaryVersion', '<string>6.0</string>'],
+      ['CFBundlePackageType', '<string>APPL</string>'],
+      ['CFBundleShortVersionString', `<string>${escapeForXml(version)}</string>`],
+      ['CFBundleVersion', `<string>${escapeForXml(version)}</string>`],
+      ['NSHighResolutionCapable', '<true/>'],
+      ...(iconWritten ? [['CFBundleIconFile', '<string>icon</string>'] as const] : [])
+    ]
+    const body = [...entries]
+      .sort((left: readonly [string, string], right: readonly [string, string]): number =>
+        left[0] < right[0] ? -1 : 1)
+      .map(([key, value]: readonly [string, string]): string => `\t<key>${key}</key>\n\t${value}`)
+      .join('\n')
+    return [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+      '<plist version="1.0">',
+      '<dict>',
+      body,
+      '</dict>',
+      '</plist>',
+      ''
+    ].join('\n')
+  }
+
+  /**
+   * Box art → `.icns` with `sips`, which needs a square source first.
+   *
+   * Without this a generated bundle gets the generic application icon. `sips` is part
+   * of macOS, so there is nothing to install; if it fails we simply go without.
+   */
+  private writeIcon (iconPath: string | null, destination: string): boolean {
+    if (iconPath === null || !fs.existsSync(iconPath)) return false
+    const square = `${destination}.square.png`
+    try {
+      const steps: readonly (readonly string[])[] = [
+        ['-z', ICON_SIZE, ICON_SIZE, iconPath, '--out', square],
+        ['-s', 'format', 'icns', square, '--out', destination]
+      ]
+      for (const step of steps) {
+        const result = spawnSync('sips', [...step], { timeout: SIPS_TIMEOUT_MS })
+        if (result.status !== 0) {
+          this.log('sips could not convert the box art — the bundle gets the generic icon')
+          return false
+        }
+      }
+      return fs.existsSync(destination)
+    } catch {
+      return false
+    } finally {
+      fs.rmSync(square, { force: true })
+    }
+  }
+}
+
+/** A bundle is a directory, so replacing one is not a plain overwrite. */
+function replaceExisting (bundlePath: string): void {
+  let stats: fs.Stats | null = null
+  try {
+    stats = fs.lstatSync(bundlePath)
+  } catch {
+    return
+  }
+  if (stats.isDirectory() && !stats.isSymbolicLink()) fs.rmSync(bundlePath, { recursive: true, force: true })
+  else fs.rmSync(bundlePath, { force: true })
+}

src/infrastructure/engine/launchers/ShellQuoting.ts

@@ -0,0 +1,26 @@
+/**
+ * Quoting for the two shells a desktop launcher goes through.
+ *
+ * A game title is user data that ends up inside an `Exec=` line and a `/bin/sh`
+ * script, and titles contain apostrophes. These are the same rules Python's
+ * `shlex.quote` and a PowerShell single-quoted string follow.
+ */
+
+const SAFE_UNQUOTED = /^[A-Za-z0-9_@%+=:,./-]+$/
+
+export function quoteForShell (value: string): string {
+  if (value.length === 0) return "''"
+  if (SAFE_UNQUOTED.test(value)) return value
+  return `'${value.replace(/'/g, "'\"'\"'")}'`
+}
+
+export function quoteForPowerShell (value: string): string {
+  return `'${value.replace(/'/g, "''")}'`
+}
+
+export function escapeForXml (value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}

src/infrastructure/engine/launchers/WindowsShortcutWriter.ts

@@ -0,0 +1,78 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import type { InstalledRecord } from '../../../domain/models/InstalledRecord'
+import { WEB_MODE } from '../../../domain/models/StoreConfiguration'
+import type { StoreFileSystem } from '../../files/StoreFileSystem'
+import { quoteForPowerShell } from './ShellQuoting'
+
+const POWERSHELL_TIMEOUT_MS = 60_000
+const DESCRIPTION_LIMIT = 250
+
+/**
+ * Windows: a real `.lnk` through PowerShell, or a `.cmd` if that is missing.
+ *
+ * A `.lnk` is the only artifact that carries a working directory *and* shows up the
+ * way users expect, but it is a binary format with no writer in the standard library
+ * of any language here — PowerShell's `WScript.Shell` is the one tool every Windows
+ * has. When even that is unavailable a `.cmd` still appears in the Start menu, which
+ * is worth more than a correct file nobody can see.
+ */
+export class WindowsShortcutWriter {
+  public constructor (
+    private readonly files: StoreFileSystem,
+    private readonly log: (line: string) => void
+  ) {}
+
+  public write (record: InstalledRecord, shortcutPath: string, webUrl: string): string {
+    const target = record.mode === WEB_MODE ? webUrl : record.executable ?? ''
+    const workingDirectory = record.mode === WEB_MODE || record.executable === null
+      ? ''
+      : path.dirname(record.executable)
+
+    fs.mkdirSync(path.dirname(shortcutPath), { recursive: true })
+    if (this.writeShortcut(record, shortcutPath, target, workingDirectory)) return shortcutPath
+    return this.writeCommandFile(record, shortcutPath, target, workingDirectory)
+  }
+
+  private writeShortcut (
+    record: InstalledRecord,
+    shortcutPath: string,
+    target: string,
+    workingDirectory: string
+  ): boolean {
+    const script = [
+      `$s = (New-Object -ComObject WScript.Shell).CreateShortcut(${quoteForPowerShell(shortcutPath)});`,
+      `$s.TargetPath = ${quoteForPowerShell(target)};`,
+      workingDirectory.length > 0 ? `$s.WorkingDirectory = ${quoteForPowerShell(workingDirectory)};` : '',
+      `$s.Description = ${quoteForPowerShell(record.title.slice(0, DESCRIPTION_LIMIT))};`,
+      '$s.Save()'
+    ].join('')
+
+    try {
+      const result = spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+        timeout: POWERSHELL_TIMEOUT_MS
+      })
+      if (result.status === 0 && fs.existsSync(shortcutPath)) return true
+      this.log(`powershell could not write ${shortcutPath}`)
+    } catch {
+      this.log('powershell is not available — falling back to a .cmd launcher')
+    }
+    return false
+  }
+
+  private writeCommandFile (
+    record: InstalledRecord,
+    shortcutPath: string,
+    target: string,
+    workingDirectory: string
+  ): string {
+    const commandPath = `${shortcutPath.slice(0, shortcutPath.length - path.extname(shortcutPath).length)}.cmd`
+    const body = record.mode === WEB_MODE || workingDirectory.length === 0
+      ? `@echo off\r\nstart "" "${target}"\r\n`
+      : `@echo off\r\ncd /d "${workingDirectory}"\r\nstart "" "${target}"\r\n`
+    this.files.writeAtomic(commandPath, Buffer.from(body, 'utf8'))
+    this.log(`wrote a .cmd launcher instead of a .lnk: ${commandPath}`)
+    return commandPath
+  }
+}

src/infrastructure/files/StoreFileSystem.ts

@@ -0,0 +1,194 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * The mode an atomic write lands on when the caller names none.
+ *
+ * The shell engine's writes went through `mkstemp`, which creates at 0600, and its
+ * `state.json` and box art carry that mode on every machine this store has ever run
+ * on. Matching it keeps "the same files, in the same shape" literally true — and for
+ * a state file that records what is installed under someone's home directory, the
+ * more private of the two defaults is the better one anyway.
+ */
+const PRIVATE_FILE_MODE = 0o600
+
+/**
+ * The filesystem rules a store writes by.
+ *
+ * Three of them are safety rather than taste, and they are the reason this is one
+ * class instead of scattered `fs` calls:
+ *
+ *   - **nothing is written in place.** A store interrupted mid-sync would otherwise
+ *     leave a half-written menu entry, which is worse than an old one;
+ *   - **every delete is guarded by `within`.** A store may only remove files from
+ *     the subtree it owns, never from the user's own library;
+ *   - **only empty directories are pruned.** One surprise file is enough to keep a
+ *     directory.
+ */
+export class StoreFileSystem {
+  public constructor (
+    private readonly tag: string,
+    private readonly log: (line: string) => void
+  ) {}
+
+  public readJson (filePath: string): unknown {
+    try {
+      return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+    } catch (error: unknown) {
+      if (isMissingFile(error)) return null
+      this.log(`warning: cannot read ${filePath}: ${describe(error)}`)
+      return null
+    }
+  }
+
+  public writeJson (filePath: string, data: unknown): void {
+    this.writeAtomic(filePath, Buffer.from(`${JSON.stringify(data, null, 2)}\n`, 'utf8'))
+  }
+
+  /** Write bytes via a temp file in the same directory, then rename over the target. */
+  public writeAtomic (filePath: string, blob: Buffer, mode: number = PRIVATE_FILE_MODE): string {
+    const directory = path.dirname(filePath)
+    fs.mkdirSync(directory, { recursive: true })
+    const temporary = path.join(directory, `.${this.tag}-${process.pid.toString(36)}-${counter()}.tmp`)
+    try {
+      fs.writeFileSync(temporary, blob, { mode })
+      // The mode is set again: `writeFileSync` applies the umask to it, and a launcher
+      // that is not executable is not a launcher.
+      fs.chmodSync(temporary, mode)
+      fs.renameSync(temporary, filePath)
+    } catch (error: unknown) {
+      fs.rmSync(temporary, { force: true })
+      throw error
+    }
+    return filePath
+  }
+
+  /**
+   * Remove a file, a symlink or a directory tree — but only inside `root`.
+   *
+   * Returns whether anything went. A symlink is unlinked rather than followed: on
+   * macOS a menu entry may be a link to the archive's own `.app`, and removing the
+   * store's entry must not touch what it points at.
+   */
+  public removeWithin (target: string, root: string): boolean {
+    if (!within(target, root)) {
+      this.log(`warning: refusing to delete ${target} (outside ${root})`)
+      return false
+    }
+    const stats = statOrNull(target)
+    if (stats === null) return false
+    if (stats.isDirectory() && !stats.isSymbolicLink()) {
+      fs.rmSync(target, { recursive: true, force: true })
+    } else {
+      fs.rmSync(target, { force: true })
+    }
+    return true
+  }
+
+  /**
+   * Remove those of `directories` that are now empty, deepest first.
+   *
+   * A store that has uninstalled everything should not leave its folders behind.
+   */
+  public pruneEmptyDirectories (directories: readonly string[], root: string): void {
+    const ordered = [...new Set(directories.filter((entry: string): boolean => entry.length > 0)
+      .map((entry: string): string => path.resolve(entry)))]
+      .sort((left: string, right: string): number => depth(right) - depth(left))
+
+    for (const directory of ordered) {
+      if (!within(directory, root)) {
+        this.log(`warning: refusing to remove ${directory} (outside ${root})`)
+        continue
+      }
+      const stats = statOrNull(directory)
+      if (stats?.isDirectory() !== true) continue
+      if (fs.readdirSync(directory).length > 0) continue
+      try {
+        fs.rmdirSync(directory)
+      } catch {
+        // A directory that will not go is not a failure worth reporting: the next
+        // sync finds it again, and an uninstall has already done its real work.
+      }
+    }
+  }
+
+  public temporaryPath (directory: string, label: string, suffix: string): string {
+    return path.join(directory, `.${this.tag}-${label}${suffix}`)
+  }
+}
+
+/**
+ * True when `target` is `root` or sits inside it.
+ *
+ * Every delete a store performs is guarded by this.
+ */
+export function within (target: string, root: string): boolean {
+  if (target.length === 0 || root.length === 0) return false
+  const resolvedTarget = path.resolve(target)
+  const resolvedRoot = path.resolve(root)
+  return resolvedTarget === resolvedRoot || resolvedTarget.startsWith(resolvedRoot + path.sep)
+}
+
+/** `$XDG_DATA_HOME|~/.local/share/applications` or a plain `~`-path, resolved. */
+export function expandPathSpecification (specification: string | null): string | null {
+  if (specification === null || specification.length === 0) return null
+  let remaining = specification
+  if (remaining.startsWith('$')) {
+    const [variable, fallback] = splitOnce(remaining.slice(1), '|')
+    // `$XDG_DATA_HOME|~/.local/share/applications` — the tail after the fallback's
+    // own prefix is what gets appended to the variable.
+    const [name, tail] = splitOnce(variable, '/')
+    const value = process.env[name]
+    if (value !== undefined && value.length > 0) {
+      const base = expandHome(value)
+      return path.resolve(tail.length > 0 ? path.join(base, tail) : base)
+    }
+    remaining = fallback
+  }
+  if (remaining.length === 0) return null
+  return path.resolve(expandVariables(expandHome(remaining)))
+}
+
+export function expandHome (value: string): string {
+  return value === '~' || value.startsWith(`~${path.sep}`) || value.startsWith('~/')
+    ? path.join(os.homedir(), value.slice(2))
+    : value
+}
+
+function expandVariables (value: string): string {
+  return value.replace(/\$(\w+)|\$\{(\w+)\}/g, (match: string, bare: string | undefined, braced: string | undefined): string =>
+    process.env[bare ?? braced ?? ''] ?? match)
+}
+
+function splitOnce (value: string, separator: string): readonly [string, string] {
+  const index = value.indexOf(separator)
+  return index < 0 ? [value, ''] : [value.slice(0, index), value.slice(index + separator.length)]
+}
+
+function statOrNull (target: string): fs.Stats | null {
+  try {
+    return fs.lstatSync(target)
+  } catch {
+    return null
+  }
+}
+
+function depth (value: string): number {
+  return value.split(path.sep).length
+}
+
+function isMissingFile (error: unknown): boolean {
+  return typeof error === 'object' && error !== null &&
+    (error as { readonly code?: unknown }).code === 'ENOENT'
+}
+
+export function describe (error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+let sequence = 0
+function counter (): string {
+  sequence += 1
+  return sequence.toString(36)
+}

src/infrastructure/http/HttpTextClient.ts

@@ -3,7 +3,7 @@ import https from 'node:https'
 
 const REQUEST_TIMEOUT_MS = 60_000
 const MAX_REDIRECTS = 5
-const USER_AGENT = 'warp-engine-desktop-gui'
+const USER_AGENT = 'warp-engine-client'
 
 /** A response that arrived but said no. The status matters: 404 is not a failure everywhere. */
 export class HttpStatusError extends Error {

src/infrastructure/http/StoreHttpClient.ts

@@ -0,0 +1,218 @@
+import fs from 'node:fs'
+import http from 'node:http'
+import https from 'node:https'
+import path from 'node:path'
+import { pipeline } from 'node:stream/promises'
+import { HttpStatusError } from './HttpTextClient'
+
+const MAX_REDIRECTS = 5
+
+export interface HttpResponseBody {
+  readonly body: Buffer
+  readonly contentType: string
+  /** Lower-cased names, as Node delivers them. The engine version arrives in one. */
+  readonly headers: Readonly<Record<string, string>>
+  readonly statusCode: number
+}
+
+export interface StoreHttpOptions {
+  readonly userAgent: string
+  /** Seconds, as the store config states it. */
+  readonly timeout: number
+  readonly insecure: boolean
+  /**
+   * The bearer token to send, asked for per request.
+   *
+   * A function rather than a value because the token changes under a long-lived
+   * client — signing in and out do not rebuild it — and because there is no reason
+   * to hold the secret in a field that outlives the request that needs it.
+   */
+  readonly bearerToken?: () => string | null
+}
+
+interface RequestOptions {
+  readonly method?: string
+  readonly body?: string
+  readonly contentType?: string
+  /** Statuses to hand back rather than throw on. */
+  readonly accept?: readonly number[]
+}
+
+/**
+ * The store's own HTTP: bytes rather than text, and a streaming download.
+ *
+ * Separate from `HttpTextClient` because the two have different jobs — that one
+ * fetches a config file and wants a string, this one fetches a catalog and a
+ * multi-megabyte archive and must not hold the archive in memory. It also honours
+ * the store config's `timeout` and `insecure`, which are per-store settings rather
+ * than properties of this application.
+ */
+export class StoreHttpClient {
+  public constructor (private readonly options: StoreHttpOptions) {}
+
+  public async readBytes (url: string, request: RequestOptions = {}): Promise<HttpResponseBody> {
+    return await this.request(url, MAX_REDIRECTS, request, async (
+      response: http.IncomingMessage
+    ): Promise<HttpResponseBody> => {
+      const chunks: Buffer[] = []
+      for await (const chunk of response) chunks.push(Buffer.from(chunk as Buffer))
+      return {
+        body: Buffer.concat(chunks),
+        contentType: response.headers['content-type'] ?? '',
+        headers: readHeaders(response),
+        statusCode: response.statusCode ?? 0
+      }
+    })
+  }
+
+  /** A JSON request and a JSON answer — the shape every auth endpoint speaks. */
+  public async requestJson (
+    url: string,
+    request: RequestOptions & { readonly payload?: unknown } = {}
+  ): Promise<{ readonly json: unknown, readonly statusCode: number }> {
+    const { payload, ...rest } = request
+    const response = await this.readBytes(url, {
+      ...rest,
+      ...(payload === undefined
+        ? {}
+        : { body: JSON.stringify(payload), contentType: 'application/json' })
+    })
+    const text = response.body.toString('utf8')
+    return {
+      json: text.trim().length === 0 ? null : JSON.parse(text),
+      statusCode: response.statusCode
+    }
+  }
+
+  /**
+   * Stream `url` into `destination` atomically. Returns bytes written.
+   *
+   * A part file next to the target, then a rename: a download interrupted halfway
+   * must not look like a complete archive to the next sync.
+   */
+  public async download (url: string, destination: string): Promise<number> {
+    const directory = path.dirname(destination)
+    fs.mkdirSync(directory, { recursive: true })
+    const partial = `${destination}.part`
+    let written = 0
+
+    try {
+      await this.request(url, MAX_REDIRECTS, {}, async (response: http.IncomingMessage): Promise<void> => {
+        response.on('data', (chunk: Buffer): void => { written += chunk.length })
+        await pipeline(response, fs.createWriteStream(partial))
+      })
+      if (written === 0) throw new Error(`${url} returned an empty response`)
+      fs.renameSync(partial, destination)
+    } catch (error: unknown) {
+      fs.rmSync(partial, { force: true })
+      throw error
+    }
+    return written
+  }
+
+  private async request<TResult> (
+    url: string,
+    redirectsLeft: number,
+    request: RequestOptions,
+    consume: (response: http.IncomingMessage) => Promise<TResult>,
+    origin: string = originOf(url)
+  ): Promise<TResult> {
+    const response = await this.open(url, request, origin)
+    const status = response.statusCode ?? 0
+    const location = response.headers.location
+
+    if (status >= 300 && status < 400 && location !== undefined) {
+      response.resume()
+      if (redirectsLeft <= 0) throw new Error(`too many redirects for ${url}`)
+      const next = new URL(location, url).toString()
+      // The origin travels with the redirect chain, not with each hop: a gated
+      // download answers 302 to a signed storage URL, and *that* host must not be
+      // sent our bearer token. It is somebody else's server, and a presigned URL is
+      // refused outright by some object stores when an Authorization header rides
+      // along with the signature. A redirect back to the catalog keeps the token,
+      // because that is the server that issued it.
+      return await this.request(next, redirectsLeft - 1, redirectedRequest(request), consume, origin)
+    }
+    if (status !== 200 && !(request.accept ?? []).includes(status)) {
+      response.resume()
+      throw new HttpStatusError(url, status)
+    }
+    return await consume(response)
+  }
+
+  private async open (
+    url: string,
+    request: RequestOptions,
+    origin: string
+  ): Promise<http.IncomingMessage> {
+    return new Promise<http.IncomingMessage>((
+      resolve: (response: http.IncomingMessage) => void,
+      reject: (error: Error) => void
+    ): void => {
+      const secure = !url.startsWith('http://')
+      const client = secure ? https : http
+      const outgoing = client.request(url, {
+        method: request.method ?? 'GET',
+        headers: this.buildHeaders(url, request, origin),
+        ...(secure && this.options.insecure ? { rejectUnauthorized: false } : {})
+      }, resolve)
+
+      outgoing.setTimeout(Math.max(1, this.options.timeout) * 1000, (): void => {
+        outgoing.destroy(new Error(`${url} timed out`))
+      })
+      outgoing.on('error', reject)
+      if (request.body !== undefined) outgoing.write(request.body)
+      outgoing.end()
+    })
+  }
+
+  private buildHeaders (
+    url: string,
+    request: RequestOptions,
+    origin: string
+  ): Record<string, string> {
+    const headers: Record<string, string> = { 'User-Agent': this.options.userAgent }
+    if (request.contentType !== undefined) headers['Content-Type'] = request.contentType
+    if (request.body !== undefined) {
+      headers['Content-Length'] = String(Buffer.byteLength(request.body))
+    }
+
+    const token = originOf(url) === origin ? this.options.bearerToken?.() ?? null : null
+    if (token !== null && token.length > 0) headers['Authorization'] = `Bearer ${token}`
+    return headers
+  }
+}
+
+/**
+ * A redirect is followed as a GET without the body.
+ *
+ * That is what every client does with 301/302 after a POST, and what the servers
+ * answering them expect. `accept` travels on, because it describes what the caller
+ * is willing to read rather than anything about one hop.
+ */
+function redirectedRequest (request: RequestOptions): RequestOptions {
+  return request.accept === undefined ? {} : { accept: request.accept }
+}
+
+function originOf (url: string): string {
+  try {
+    return new URL(url).origin
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * The response headers as plain strings.
+ *
+ * Node gives a repeated header as an array; the ones this client reads are single-valued,
+ * and joining is a truer answer than picking the first.
+ */
+function readHeaders (response: http.IncomingMessage): Readonly<Record<string, string>> {
+  const headers: Record<string, string> = {}
+  for (const [name, value] of Object.entries(response.headers)) {
+    if (value === undefined) continue
+    headers[name.toLowerCase()] = Array.isArray(value) ? value.join(', ') : value
+  }
+  return headers
+}

src/infrastructure/mappers/EngineGameMapper.ts

@@ -1,36 +0,0 @@
-import type { Game, GameMode } from '../../domain/models/Game'
-import {
-  readBoolean, readOptionalString, readString, type JsonRecord
-} from '../json/JsonRecord'
-
-/**
- * One engine JSON entry to one domain model.
- *
- * The engine speaks snake_case and this is the only place that knows it: rename a
- * field there and this mapper is the single file that follows.
- */
-export class EngineGameMapper {
-  public toModel (record: JsonRecord): Game {
-    return {
-      name: readString(record, 'name'),
-      title: readString(record, 'title'),
-      platform: readString(record, 'platform'),
-      version: readString(record, 'version'),
-      mode: this.toMode(readString(record, 'mode')),
-      kind: readString(record, 'kind'),
-      description: readString(record, 'desc'),
-      author: readString(record, 'author'),
-      imagePath: readOptionalString(record, 'image_url'),
-      installed: readBoolean(record, 'installed'),
-      updateAvailable: readBoolean(record, 'update_available'),
-      installedVersion: readOptionalString(record, 'installed_version'),
-      menuEntryPath: readOptionalString(record, 'menu_entry'),
-      executablePath: readOptionalString(record, 'exe'),
-      hostedUrl: readOptionalString(record, 'url')
-    }
-  }
-
-  private toMode (value: string): GameMode {
-    return value === 'web' ? 'web' : 'app'
-  }
-}

src/infrastructure/mappers/EngineStorePathsMapper.ts

@@ -1,20 +0,0 @@
-import type { StorePaths } from '../../domain/models/StorePaths'
-import { readRecord, readString, type JsonRecord } from '../json/JsonRecord'
-
-/** The engine's `paths` answer to one domain model. */
-export class EngineStorePathsMapper {
-  public toModel (record: JsonRecord): StorePaths {
-    const store = readRecord(record, 'store')
-    return {
-      operatingSystem: readString(record, 'os'),
-      architecture: readString(record, 'arch'),
-      installRoot: readString(record, 'install_root'),
-      menuDirectory: readString(record, 'menu_dir'),
-      storeFolder: readString(record, 'store_folder'),
-      menuGroup: readString(record, 'menu_group'),
-      catalogBaseUrl: store === null ? '' : readString(store, 'base_url'),
-      storeName: store === null ? '' : readString(store, 'name'),
-      storeId: store === null ? '' : readString(store, 'id')
-    }
-  }
-}

src/infrastructure/process/PythonEngineProcessRunner.ts

@@ -1,128 +0,0 @@
-import { spawn, spawnSync } from 'node:child_process'
-import { EngineInvocationError } from '../../domain/errors/EngineInvocationError'
-import { PythonMissingError } from '../../domain/errors/PythonMissingError'
-import type { EngineProgressListener } from '../../domain/models/EngineProgress'
-import type { InstalledStore } from '../../domain/models/InstalledStore'
-import type { PythonRuntimeLocator } from '../../domain/ports/PythonRuntimeLocator'
-import type { SyncEventDto } from '../../shared/contracts/dto/SyncEventDto'
-import { asRecord, type JsonRecord } from '../json/JsonRecord'
-
-const VERSION_PROBE_TIMEOUT_MS = 15_000
-
-/**
- * Runs one engine command and reads its two streams.
- *
- * The engine's contract with any client is `--json`: data on stdout, one JSON
- * object per line, and the human-readable log on stderr. So nothing here parses a
- * sentence meant for a person, and a line that is not JSON is handed to the log
- * rather than crashing the call.
- */
-export class PythonEngineProcessRunner {
-  public constructor (private readonly runtimeLocator: PythonRuntimeLocator) {}
-
-  public async runCommand (
-    store: InstalledStore,
-    commandArguments: readonly string[],
-    progress: EngineProgressListener = {}
-  ): Promise<readonly JsonRecord[]> {
-    const runtime = this.runtimeLocator.findRuntime()
-    if (runtime === null) throw new PythonMissingError()
-
-    const argv = [
-      ...runtime.arguments,
-      store.scriptPath,
-      '--config', store.configPath,
-      '--json',
-      ...commandArguments
-    ]
-
-    return new Promise<readonly JsonRecord[]>((
-      resolve: (records: readonly JsonRecord[]) => void,
-      reject: (error: Error) => void
-    ): void => {
-      const child = spawn(runtime.command, argv, {
-        env: { ...process.env, DESKTOP_STORE_HOME: store.home }
-      })
-      const records: JsonRecord[] = []
-      let stdoutRest = ''
-      let stderrRest = ''
-
-      const takeStdout = (chunk: string): void => {
-        stdoutRest += chunk
-        const parts = stdoutRest.split('\n')
-        stdoutRest = parts.pop() ?? ''
-        for (const part of parts) this.consumeStdoutLine(part, records, progress)
-      }
-
-      const takeStderr = (chunk: string): void => {
-        stderrRest += chunk
-        const parts = stderrRest.split('\n')
-        stderrRest = parts.pop() ?? ''
-        for (const part of parts) {
-          if (part.trim().length > 0) progress.onLog?.(part)
-        }
-      }
-
-      child.stdout.setEncoding('utf8')
-      child.stderr.setEncoding('utf8')
-      child.stdout.on('data', takeStdout)
-      child.stderr.on('data', takeStderr)
-      child.on('error', (error: Error): void => {
-        reject(new EngineInvocationError(error.message))
-      })
-      child.on('close', (code: number | null): void => {
-        takeStdout('\n')
-        takeStderr('\n')
-        if (code === 0) resolve(records)
-        else reject(new EngineInvocationError(`the store exited with code ${String(code)}`, code))
-      })
-    })
-  }
-
-  /** The engine's `--version`, read synchronously because it gates the first paint. */
-  public readVersionText (store: InstalledStore): string | null {
-    const runtime = this.runtimeLocator.findRuntime()
-    if (runtime === null) return null
-    try {
-      const probe = spawnSync(runtime.command, [...runtime.arguments, store.scriptPath, '--version'], {
-        encoding: 'utf8',
-        timeout: VERSION_PROBE_TIMEOUT_MS
-      })
-      const text = `${probe.stdout}${probe.stderr}`.trim()
-      return probe.status === 0 && text.length > 0 ? text : null
-    } catch {
-      return null
-    }
-  }
-
-  private consumeStdoutLine (
-    line: string,
-    records: JsonRecord[],
-    progress: EngineProgressListener
-  ): void {
-    if (line.trim().length === 0) return
-    let parsed: unknown
-    try {
-      parsed = JSON.parse(line)
-    } catch {
-      // Not ours to interpret — hand it on as a log line rather than fail the call.
-      progress.onLog?.(line)
-      return
-    }
-    const record = asRecord(parsed)
-    if (record === null) return
-    records.push(record)
-    const event = this.asSyncEvent(record)
-    if (event !== null) progress.onEvent?.(event)
-  }
-
-  /**
-   * A progress line, or null for the final result object.
-   *
-   * The engine tags its stream events with `event`; the listing and paths answers
-   * carry no such field, which is exactly the difference.
-   */
-  private asSyncEvent (record: JsonRecord): SyncEventDto | null {
-    return typeof record['event'] === 'string' ? (record as unknown as SyncEventDto) : null
-  }
-}

src/infrastructure/process/SystemPythonRuntimeLocator.ts

@@ -1,63 +0,0 @@
-import { spawnSync } from 'node:child_process'
-import type { PythonRuntime } from '../../domain/models/PythonRuntime'
-import type { PythonRuntimeLocator } from '../../domain/ports/PythonRuntimeLocator'
-
-interface RuntimeCandidate {
-  readonly command: string
-  readonly arguments: readonly string[]
-}
-
-/** `py -3` is the Windows launcher, and often the only Python on PATH there. */
-const WINDOWS_CANDIDATES: readonly RuntimeCandidate[] = [
-  { command: 'py', arguments: ['-3'] },
-  { command: 'python', arguments: [] },
-  { command: 'python3', arguments: [] }
-]
-
-const POSIX_CANDIDATES: readonly RuntimeCandidate[] = [
-  { command: 'python3', arguments: [] },
-  { command: 'python', arguments: [] }
-]
-
-const PROBE_TIMEOUT_MS = 10_000
-
-/**
- * Finds the Python 3 the store needs.
- *
- * The answer is cached: the probe spawns processes, and the window asks for it on
- * every state read.
- */
-export class SystemPythonRuntimeLocator implements PythonRuntimeLocator {
-  private cached: PythonRuntime | null = null
-  private probed = false
-
-  public findRuntime (): PythonRuntime | null {
-    if (this.probed) return this.cached
-    this.probed = true
-    const candidates = process.platform === 'win32' ? WINDOWS_CANDIDATES : POSIX_CANDIDATES
-    for (const candidate of candidates) {
-      const runtime = this.probeCandidate(candidate)
-      if (runtime !== null) {
-        this.cached = runtime
-        return runtime
-      }
-    }
-    return null
-  }
-
-  private probeCandidate (candidate: RuntimeCandidate): PythonRuntime | null {
-    try {
-      const probe = spawnSync(candidate.command, [...candidate.arguments, '--version'], {
-        encoding: 'utf8',
-        timeout: PROBE_TIMEOUT_MS
-      })
-      const output = `${probe.stdout}${probe.stderr}`
-      if (probe.status === 0 && output.includes('Python 3.')) {
-        return { command: candidate.command, arguments: candidate.arguments, version: output.trim() }
-      }
-    } catch {
-      // An absent interpreter is the normal case, not an error worth reporting.
-    }
-    return null
-  }
-}

src/infrastructure/repositories/FileSystemInstalledStoreRepository.ts

@@ -10,11 +10,13 @@ const STORE_DIRECTORY_NAME = 'warp-engine-store'
 const CONFIG_FILE_NAME = 'config.json'
 
 /**
- * Finds stores where the shell installers put them.
+ * Finds stores where they were put.
  *
- * The roots are searched in the installers' own order, and `STORE_ROOT` comes
+ * The roots are searched in the shell installers' own order — those homes are still
- * first so a sandbox can be driven without touching a working installation — which
+ * valid stores. `STORE_ROOT` replaces the lot: a sandbox has to be a sandbox, and it
- * is how this repository is tested.
+ * only prepended before, so a "sandboxed" run still listed the real stores, could
+ * switch to one, and — now that stores can be removed — could delete one. The README
+ * always said "instead of the real one"; this is the behaviour catching up.
  */
 export class FileSystemInstalledStoreRepository implements InstalledStoreRepository {
   public findAll (): readonly InstalledStore[] {
@@ -34,10 +36,11 @@ export class FileSystemInstalledStoreRepository implements InstalledStoreReposit
   }
 
   public readRoots (): readonly string[] {
+    const override = process.env['STORE_ROOT']
+    if (override !== undefined && override.length > 0) return [override]
+
     const home = os.homedir()
     const roots: string[] = []
-    const override = process.env['STORE_ROOT']
-    if (override !== undefined && override.length > 0) roots.push(override)
     const xdgDataHome = process.env['XDG_DATA_HOME']
     if (xdgDataHome !== undefined && xdgDataHome.length > 0) {
       roots.push(path.join(xdgDataHome, STORE_DIRECTORY_NAME))
@@ -58,6 +61,22 @@ export class FileSystemInstalledStoreRepository implements InstalledStoreReposit
     return path.join(root, `${storeId}${DESKTOP_STORE_ENGINE.homeSuffix}`)
   }
 
+  /**
+   * Remove a store home, and only one this repository actually found.
+   *
+   * The check is the point. This is the one call in the application that deletes a
+   * directory tree the *window* named, and the window is the least trusted thing here;
+   * resolving the path against what a scan returns means a caller can ask for the
+   * removal of a store, never of a path.
+   */
+  public removeHome (home: string): void {
+    const known = this.findByHome(home)
+    if (known === null) {
+      throw new Error(`not a store home on this machine: ${home}`)
+    }
+    fs.rmSync(known.home, { recursive: true, force: true })
+  }
+
   private readDirectories (root: string): readonly string[] {
     try {
       return fs.readdirSync(root, { withFileTypes: true })
@@ -69,20 +88,20 @@ export class FileSystemInstalledStoreRepository implements InstalledStoreReposit
     }
   }
 
+  /**
+   * A store home, recognised by its config and its directory name.
+   *
+   * The config is the only file that has to be there. It used to be the config *and*
+   * the engine script, and dropping that condition is what lets a home provisioned by
+   * an older client keep working after its scripts are cleared out.
+   */
   private readStoreAt (home: string, directoryName: string): InstalledStore | null {
+    const configPath = path.join(home, CONFIG_FILE_NAME)
+    if (!fs.existsSync(configPath)) return null
     for (const engine of STORE_ENGINES) {
-      const scriptPath = path.join(home, engine.scriptFileName)
+      if (!directoryName.endsWith(engine.homeSuffix)) continue
-      const configPath = path.join(home, CONFIG_FILE_NAME)
+      const id = directoryName.slice(0, directoryName.length - engine.homeSuffix.length)
-      if (!fs.existsSync(scriptPath) || !fs.existsSync(configPath)) continue
+      return { id, name: this.readStoreName(configPath, id), home, configPath, engine: engine.id }
-      const id = directoryName.replace(engine.homeSuffix, '')
-      return {
-        id,
-        name: this.readStoreName(configPath, id),
-        home,
-        scriptPath,
-        configPath,
-        engine: engine.id
-      }
     }
     return null
   }
@@ -90,9 +109,8 @@ export class FileSystemInstalledStoreRepository implements InstalledStoreReposit
   /**
    * The store's own name, from the config the installer wrote.
    *
-   * Read here rather than asked of the engine: the switcher lists every store on
+   * Read here rather than asked of the engine: the switcher lists every store on the
-   * the machine, and starting a Python process per entry to learn its name would
+   * machine, and assembling an engine per entry to learn its name would be absurd.
-   * be absurd.
    */
   private readStoreName (configPath: string, fallback: string): string {
     try {

src/infrastructure/repositories/HttpStoreEngineInstaller.ts

@@ -1,117 +0,0 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import type { EngineProgressListener } from '../../domain/models/EngineProgress'
-import type { InstalledStore } from '../../domain/models/InstalledStore'
-import type { RegistryStore } from '../../domain/models/RegistryStore'
-import { DESKTOP_STORE_ENGINE } from '../../domain/models/StoreEngine'
-import { deriveStoreId } from '../../domain/models/StoreIdentity'
-import type { StoreEngineInstaller } from '../../domain/ports/StoreEngineInstaller'
-import { asRecord, readString } from '../json/JsonRecord'
-import { HttpStatusError, type HttpTextClient } from '../http/HttpTextClient'
-
-const CONFIG_FILE_NAME = 'config.json'
-const SCRIPT_MODE = 0o755
-const PYTHON_SHEBANG = '#!/usr/bin/env python3'
-const DEFAULT_FORGE_BASE = 'https://git.teletypegames.org'
-const DEFAULT_BRANCH = 'master'
-
-/**
- * Downloads the engine, the shared core and a store config into a store home.
- *
- * The same three files, in the same folder, the shell installer would place — so
- * the CLI and this client stay one installation, and running install.sh afterwards
- * only adds the launcher script. No launcher is written here: the window is it.
- */
-export class HttpStoreEngineInstaller implements StoreEngineInstaller {
-  private readonly forgeBase: string
-
-  public constructor (private readonly httpClient: HttpTextClient, forgeBase?: string) {
-    const configured = process.env['FORGE_BASE']
-    this.forgeBase = forgeBase ?? (configured !== undefined && configured.length > 0
-      ? configured
-      : DEFAULT_FORGE_BASE)
-  }
-
-  public async installEngine (
-    home: string,
-    store: RegistryStore,
-    progress: EngineProgressListener = {}
-  ): Promise<InstalledStore> {
-    fs.mkdirSync(home, { recursive: true })
-
-    for (const [fileName, url] of Object.entries(this.engineSources())) {
-      progress.onLog?.(`downloading ${fileName}`)
-      const body = await this.httpClient.readText(url)
-      if (!body.startsWith(PYTHON_SHEBANG)) {
-        throw new Error(`${fileName} does not look like the store engine — refusing to install it`)
-      }
-      fs.writeFileSync(path.join(home, fileName), body, { mode: SCRIPT_MODE })
-    }
-
-    const config = await this.readStoreConfig(store, progress)
-    const configPath = path.join(home, CONFIG_FILE_NAME)
-    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`)
-
-    progress.onLog?.(`${store.name} is set up in ${home}`)
-    const configStore = asRecord(config['store'])
-    return {
-      id: configStore === null ? deriveStoreId(store) : readString(configStore, 'id', deriveStoreId(store)),
-      name: store.name,
-      home,
-      scriptPath: path.join(home, DESKTOP_STORE_ENGINE.scriptFileName),
-      configPath,
-      engine: DESKTOP_STORE_ENGINE.id
-    }
-  }
-
-  /** Where the engine itself comes from: this client's own machinery, not the registry's. */
-  private engineSources (): Readonly<Record<string, string>> {
-    return {
-      [DESKTOP_STORE_ENGINE.scriptFileName]:
-        `${this.forgeBase}/stores/warp-engine-desktop-store/raw/branch/${DEFAULT_BRANCH}/${DESKTOP_STORE_ENGINE.scriptFileName}`,
-      'warpstore.py': `${this.forgeBase}/engines/warpstore/raw/branch/${DEFAULT_BRANCH}/warpstore.py`
-    }
-  }
-
-  /**
-   * The store's configuration.
-   *
-   * Its repository is the authority on how the store behaves — which platforms,
-   * which statuses, where things land. A repository without a config.json still
-   * works: the engine merges whatever it is given onto its own defaults, so a
-   * three-field config is a complete one. The registry wins on identity and on
-   * which catalog to read.
-   */
-  private async readStoreConfig (
-    store: RegistryStore,
-    progress: EngineProgressListener
-  ): Promise<Record<string, unknown>> {
-    const storeId = deriveStoreId(store)
-    let config: Record<string, unknown>
-    try {
-      progress.onLog?.(`reading the store config from ${store.storeRepositoryUrl}`)
-      const body = await this.httpClient.readText(this.configUrl(store.storeRepositoryUrl))
-      config = { ...(asRecord(JSON.parse(body)) ?? {}) }
-    } catch (error: unknown) {
-      if (!(error instanceof HttpStatusError) || error.statusCode !== 404) throw error
-      progress.onLog?.('no config.json in the store repository — using the engine defaults')
-      config = {
-        paths: { subfolder: storeId },
-        catalog: { statuses: ['released', 'archived', 'demo'] }
-      }
-    }
-
-    const existing = asRecord(config['store']) ?? {}
-    config['store'] = {
-      ...existing,
-      id: readString(existing, 'id', storeId),
-      name: store.name,
-      base_url: store.catalogUrl
-    }
-    return config
-  }
-
-  private configUrl (repositoryUrl: string, branch: string = DEFAULT_BRANCH): string {
-    return `${repositoryUrl.replace(/\/+$/, '')}/raw/branch/${branch}/${CONFIG_FILE_NAME}`
-  }
-}

src/infrastructure/repositories/HttpStoreRegistryRepository.ts

@@ -2,6 +2,7 @@ import { RegistryUnavailableError } from '../../domain/errors/RegistryUnavailabl
 import type { RegistryStore } from '../../domain/models/RegistryStore'
 import type { StoreRegistryRepository } from '../../domain/ports/StoreRegistryRepository'
 import { asRecord, readString, type JsonRecord } from '../json/JsonRecord'
+import { BuildConfiguration } from '../config/BuildConfiguration'
 import type { HttpTextClient } from '../http/HttpTextClient'
 
 const DEFAULT_REGISTRY_URL = 'https://teletypegames.org/api/stores'
@@ -9,18 +10,29 @@ const DEFAULT_REGISTRY_URL = 'https://teletypegames.org/api/stores'
 /**
  * The registry: `GET /api/stores` on the site.
  *
- * The one address this client knows, and even that is overridable — `STORES_API`
+ * The one address this client knows, and it is decided in three places, most specific
- * points it at another site or at a local endpoint. Records missing any of the
+ * first: a runtime `STORES_API` (for trying something out), the `warpEngine.registryUrl`
- * three fields are dropped rather than half-used.
+ * field a build was packaged with (for shipping a client for another site), and finally
+ * the address of ours.
+ *
+ * A name and a catalog URL make a store, and are all a record carries. Anything else it
+ * happens to say is ignored: how a store behaves is this client's own business, decided
+ * by the engine it ships with. Records missing either field are dropped rather than
+ * half-used.
  */
 export class HttpStoreRegistryRepository implements StoreRegistryRepository {
   public readonly sourceUrl: string
 
-  public constructor (private readonly httpClient: HttpTextClient, sourceUrl?: string) {
+  public constructor (
-    const configured = process.env['STORES_API']
+    private readonly httpClient: HttpTextClient,
-    this.sourceUrl = sourceUrl ?? (configured !== undefined && configured.length > 0
+    sourceUrl?: string,
-      ? configured
+    buildConfiguration: BuildConfiguration = new BuildConfiguration()
-      : DEFAULT_REGISTRY_URL)
+  ) {
+    const fromEnvironment = process.env['STORES_API']
+    this.sourceUrl = sourceUrl
+      ?? (fromEnvironment !== undefined && fromEnvironment.length > 0 ? fromEnvironment : null)
+      ?? buildConfiguration.readRegistryUrl()
+      ?? DEFAULT_REGISTRY_URL
   }
 
   public async listStores (): Promise<readonly RegistryStore[]> {
@@ -32,16 +44,13 @@ export class HttpStoreRegistryRepository implements StoreRegistryRepository {
     return parsed
       .map((row: unknown): JsonRecord | null => asRecord(row))
       .filter((row: JsonRecord | null): row is JsonRecord => row !== null)
+      // Both spellings, because a registry is someone else's API: ours answers
+      // camelCase, and a hand-rolled one may not.
       .map((row: JsonRecord): RegistryStore => ({
         name: readString(row, 'name').trim(),
-        // Both spellings, because a registry is someone else's API: ours answers
+        catalogUrl: (readString(row, 'catalogUrl') || readString(row, 'catalog_url')).trim()
-        // camelCase, and a hand-rolled one may not.
-        catalogUrl: (readString(row, 'catalogUrl') || readString(row, 'catalog_url')).trim(),
-        storeRepositoryUrl: (
-          readString(row, 'storeRepositoryUrl') || readString(row, 'store_repository_url')
-        ).trim()
       }))
       .filter((store: RegistryStore): boolean =>
-        store.name.length > 0 && store.catalogUrl.length > 0 && store.storeRepositoryUrl.length > 0)
+        store.name.length > 0 && store.catalogUrl.length > 0)
   }
 }

src/infrastructure/repositories/NativeStoreEngineInstaller.ts

@@ -0,0 +1,84 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { EngineProgressListener } from '../../domain/models/EngineProgress'
+import type { InstalledStore } from '../../domain/models/InstalledStore'
+import type { RegistryStore } from '../../domain/models/RegistryStore'
+import { DESKTOP_STORE_ENGINE } from '../../domain/models/StoreEngine'
+import { deriveStoreId } from '../../domain/models/StoreIdentity'
+import type { StoreEngineInstaller } from '../../domain/ports/StoreEngineInstaller'
+
+const CONFIG_FILE_NAME = 'config.json'
+
+/** What an install used to leave in a store home, back when the engine was a script. */
+const RETIRED_ENGINE_FILES: readonly string[] = ['desktop_store.py', 'warpstore.py']
+
+/**
+ * Setting up a store where there is none.
+ *
+ * Nothing is downloaded and nothing is asked of a server. The engine ships in this
+ * application and its defaults already cover the host-to-asset mapping, the install
+ * modes, the platforms and the behaviour; what a registry record adds is identity — a
+ * name, a catalog and a slug — and that is what gets written.
+ *
+ * The config is written to disk rather than kept in memory because it is the store's
+ * own record of itself: `StoreConfigurationReader` reads it on every operation, an
+ * existing store home is recognised by it, and a person can look at it.
+ */
+export class NativeStoreEngineInstaller implements StoreEngineInstaller {
+  public installEngine (
+    home: string,
+    store: RegistryStore,
+    progress: EngineProgressListener = {}
+  ): Promise<InstalledStore> {
+    fs.mkdirSync(home, { recursive: true })
+
+    const storeId = deriveStoreId(store)
+    const configPath = path.join(home, CONFIG_FILE_NAME)
+    fs.writeFileSync(configPath, `${JSON.stringify(this.buildConfig(store, storeId), null, 2)}\n`)
+    this.removeRetiredEngine(home, progress)
+
+    progress.onLog?.(`${store.name} is set up in ${home}`)
+    return Promise.resolve({
+      id: storeId,
+      name: store.name,
+      home,
+      configPath,
+      engine: DESKTOP_STORE_ENGINE.id
+    })
+  }
+
+  /**
+   * The store's configuration: its identity, and the two things worth stating.
+   *
+   * Everything absent from this falls to the engine's defaults, which is most of it. The
+   * subfolder is named after the store so two stores on one machine cannot reach into
+   * each other's files — it is the prune boundary, so it has to be the store's own.
+   * Demo titles are listed because a catalog that publishes them means them to be
+   * played; the engine defaults to released and archived only, which is the safer
+   * default for a store nobody configured.
+   */
+  private buildConfig (store: RegistryStore, storeId: string): Record<string, unknown> {
+    return {
+      store: { id: storeId, name: store.name, base_url: store.catalogUrl },
+      paths: { subfolder: storeId },
+      catalog: { statuses: ['released', 'archived', 'demo'] }
+    }
+  }
+
+  /**
+   * Clear out the scripts an older client downloaded here.
+   *
+   * A store home provisioned by 1.5.0 or by a shell installer holds two Python files
+   * that nothing reads any more. They are harmless, but a directory that still looks
+   * like it holds the engine invites someone to run it against a state file this
+   * application is also writing.
+   */
+  private removeRetiredEngine (home: string, progress: EngineProgressListener): void {
+    for (const fileName of RETIRED_ENGINE_FILES) {
+      const filePath = path.join(home, fileName)
+      if (!fs.existsSync(filePath)) continue
+      fs.rmSync(filePath, { force: true })
+      progress.onLog?.(`removed the retired ${fileName}`)
+    }
+  }
+}

src/infrastructure/repositories/PythonStoreCatalogGateway.ts

@@ -1,87 +0,0 @@
-import type { CatalogListing } from '../../domain/models/CatalogListing'
-import type { EngineProgressListener } from '../../domain/models/EngineProgress'
-import {
-  MINIMUM_ENGINE_VERSION, isAtLeast, parseVersionNumbers, type EngineVersion
-} from '../../domain/models/EngineVersion'
-import type { Game } from '../../domain/models/Game'
-import type { InstalledStore } from '../../domain/models/InstalledStore'
-import type { StorePaths } from '../../domain/models/StorePaths'
-import type { StoreCatalogGateway } from '../../domain/ports/StoreCatalogGateway'
-import { readRecord, readRecordArray, readStringArray, type JsonRecord } from '../json/JsonRecord'
-import { EngineGameMapper } from '../mappers/EngineGameMapper'
-import { EngineStorePathsMapper } from '../mappers/EngineStorePathsMapper'
-import type { PythonEngineProcessRunner } from '../process/PythonEngineProcessRunner'
-
-/**
- * The store engine, driven as a child process.
- *
- * The only adapter that knows the CLI exists. Everything above it sees the port.
- */
-export class PythonStoreCatalogGateway implements StoreCatalogGateway {
-  public constructor (
-    private readonly runner: PythonEngineProcessRunner,
-    private readonly gameMapper: EngineGameMapper = new EngineGameMapper(),
-    private readonly pathsMapper: EngineStorePathsMapper = new EngineStorePathsMapper()
-  ) {}
-
-  public async listGames (
-    store: InstalledStore,
-    progress?: EngineProgressListener
-  ): Promise<CatalogListing> {
-    const records = await this.runner.runCommand(store, ['list'], progress)
-    const answer = this.lastRecord(records)
-    if (answer === null) return { games: [], skipped: [], paths: null }
-    const games: readonly Game[] = readRecordArray(answer, 'games')
-      .map((record: JsonRecord): Game => this.gameMapper.toModel(record))
-    const paths = readRecord(answer, 'paths')
-    return {
-      games,
-      skipped: readStringArray(answer, 'skipped'),
-      paths: paths === null ? null : this.pathsMapper.toModel(paths)
-    }
-  }
-
-  public async readPaths (
-    store: InstalledStore,
-    progress?: EngineProgressListener
-  ): Promise<StorePaths> {
-    const records = await this.runner.runCommand(store, ['paths'], progress)
-    const answer = this.lastRecord(records)
-    return this.pathsMapper.toModel(answer ?? {})
-  }
-
-  public async syncGames (
-    store: InstalledStore,
-    names: readonly string[],
-    progress?: EngineProgressListener
-  ): Promise<void> {
-    await this.runner.runCommand(store, ['sync', ...names], progress)
-  }
-
-  public async removeGame (
-    store: InstalledStore,
-    name: string,
-    progress?: EngineProgressListener
-  ): Promise<void> {
-    await this.runner.runCommand(store, ['remove', name], progress)
-  }
-
-  public readEngineVersion (store: InstalledStore): EngineVersion | null {
-    const text = this.runner.readVersionText(store)
-    if (text === null) return null
-    const numbers = parseVersionNumbers(text)
-    return { text, numbers, supported: isAtLeast(numbers, MINIMUM_ENGINE_VERSION) }
-  }
-
-  /**
-   * The result object is the last line: the stream events come first, and both
-   * arrive on the same pipe.
-   */
-  private lastRecord (records: readonly JsonRecord[]): JsonRecord | null {
-    for (let index = records.length - 1; index >= 0; index -= 1) {
-      const record = records[index]
-      if (record !== undefined && typeof record['event'] !== 'string') return record
-    }
-    return null
-  }
-}

src/main/ElectronApplication.ts

@@ -6,7 +6,7 @@ import { SelfTestRunner } from './diagnostics/SelfTestRunner'
 
 const SELFTEST_FLAG = '--selftest'
 const SELFTEST_USER_DATA_DIRECTORY = 'warpstore-gui-selftest'
-const PRODUCT_NAME = 'WarpEngine Store'
+const PRODUCT_NAME = 'WarpEngine Client'
 
 /**
  * The application's lifecycle.

src/main/MainWindowFactory.ts

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import { BrowserWindow, shell, type BrowserWindowConstructorOptions } from 'electron'
+import { app, BrowserWindow, shell, type BrowserWindowConstructorOptions } from 'electron'
 
 const WINDOW_OPTIONS: BrowserWindowConstructorOptions = {
   width: 1040,
@@ -7,7 +7,23 @@ const WINDOW_OPTIONS: BrowserWindowConstructorOptions = {
   minWidth: 760,
   minHeight: 520,
   backgroundColor: '#11151c',
-  title: 'WarpEngine Store'
+  title: 'WarpEngine Client'
+}
+
+/**
+ * The window icon, in development only.
+ *
+ * A packaged app carries its icon in the bundle, the .exe and the .desktop entry, and
+ * `resources/` is not inside the package at all — pointing at it there would be a path
+ * that does not exist. Run from source there is nothing to carry the icon, so the
+ * window and the taskbar show Electron's own, which makes a dev run look like a
+ * different application from the one being built. macOS ignores this either way: the
+ * Dock icon comes from the bundle.
+ */
+function developmentIcon (): Pick<BrowserWindowConstructorOptions, 'icon'> {
+  if (app.isPackaged) return {}
+
+  return { icon: path.join(__dirname, '..', '..', 'resources', 'icons', '512x512.png') }
 }
 
 /**
@@ -23,6 +39,7 @@ export class MainWindowFactory {
   public createWindow (): BrowserWindow {
     const window = new BrowserWindow({
       ...WINDOW_OPTIONS,
+      ...developmentIcon(),
       webPreferences: {
         preload: path.join(__dirname, '..', 'preload', 'preload.js'),
         contextIsolation: true,

src/main/composition/ServiceContainer.ts

@@ -1,4 +1,5 @@
 import type { App, IpcMain, Shell } from 'electron'
+import { AccountService } from '../../application/services/AccountService'
 import { ApplicationStateService } from '../../application/services/ApplicationStateService'
 import { CatalogService } from '../../application/services/CatalogService'
 import { GameLaunchService } from '../../application/services/GameLaunchService'
@@ -7,14 +8,14 @@ import { StoreProvisioningService } from '../../application/services/StoreProvis
 import { StoreSelectionService } from '../../application/services/StoreSelectionService'
 import { ElectronApplicationEnvironment } from '../../infrastructure/electron/ElectronApplicationEnvironment'
 import { ElectronGameLauncher } from '../../infrastructure/electron/ElectronGameLauncher'
+import { SafeStorageCredentialRepository } from '../../infrastructure/electron/SafeStorageCredentialRepository'
+import { NativeStoreCatalogGateway } from '../../infrastructure/engine/NativeStoreCatalogGateway'
 import { HttpTextClient } from '../../infrastructure/http/HttpTextClient'
-import { PythonEngineProcessRunner } from '../../infrastructure/process/PythonEngineProcessRunner'
-import { SystemPythonRuntimeLocator } from '../../infrastructure/process/SystemPythonRuntimeLocator'
 import { FileSystemInstalledStoreRepository } from '../../infrastructure/repositories/FileSystemInstalledStoreRepository'
-import { HttpStoreEngineInstaller } from '../../infrastructure/repositories/HttpStoreEngineInstaller'
+import { NativeStoreEngineInstaller } from '../../infrastructure/repositories/NativeStoreEngineInstaller'
 import { HttpStoreRegistryRepository } from '../../infrastructure/repositories/HttpStoreRegistryRepository'
 import { JsonFilePreferencesRepository } from '../../infrastructure/repositories/JsonFilePreferencesRepository'
-import { PythonStoreCatalogGateway } from '../../infrastructure/repositories/PythonStoreCatalogGateway'
+import { AccountIpcController } from '../ipc/AccountIpcController'
 import { AppIpcController } from '../ipc/AppIpcController'
 import { CatalogIpcController } from '../ipc/CatalogIpcController'
 import { IpcRouter } from '../ipc/IpcRouter'
@@ -37,6 +38,7 @@ export class ServiceContainer {
   public readonly provisioning: StoreProvisioningService
   public readonly state: ApplicationStateService
   public readonly launching: GameLaunchService
+  public readonly accounts: AccountService
 
   private readonly controllers: readonly { register: (router: IpcRouter) => void }[]
 
@@ -46,28 +48,31 @@ export class ServiceContainer {
 
     const environment = new ElectronApplicationEnvironment(app)
     const httpClient = new HttpTextClient()
-    const pythonLocator = new SystemPythonRuntimeLocator()
-    const engineRunner = new PythonEngineProcessRunner(pythonLocator)
 
     const stores = new FileSystemInstalledStoreRepository()
-    const catalogGateway = new PythonStoreCatalogGateway(engineRunner)
+    const credentials = new SafeStorageCredentialRepository(environment)
+    const catalogGateway = new NativeStoreCatalogGateway(credentials, stores)
     const registry = new HttpStoreRegistryRepository(httpClient)
-    const installer = new HttpStoreEngineInstaller(httpClient)
+    const installer = new NativeStoreEngineInstaller()
     const preferencesRepository = new JsonFilePreferencesRepository(environment)
 
     const preferences = new PreferencesService(preferencesRepository, environment)
-    this.selection = new StoreSelectionService(stores, catalogGateway, preferences)
+    this.selection = new StoreSelectionService(stores, preferences)
     this.catalog = new CatalogService(catalogGateway, this.selection)
-    this.provisioning = new StoreProvisioningService(registry, installer, stores, this.selection)
+    this.accounts = new AccountService(catalogGateway, this.selection)
+    this.provisioning = new StoreProvisioningService(
+      registry, installer, stores, this.selection, catalogGateway
+    )
     this.launching = new GameLaunchService(new ElectronGameLauncher(shell), this.catalog)
     this.state = new ApplicationStateService(
-      preferences, this.selection, this.provisioning, pythonLocator, environment
+      preferences, this.selection, this.provisioning, environment
     )
 
     this.controllers = [
       new AppIpcController(this.state, preferences, this.launching),
       new CatalogIpcController(this.catalog, this.launching, this.guard, this.streams),
-      new StoreIpcController(this.provisioning, this.selection, this.guard, this.streams)
+      new StoreIpcController(this.provisioning, this.selection, this.guard, this.streams),
+      new AccountIpcController(this.accounts, this.streams)
     ]
   }
 

src/main/diagnostics/SelfTestRunner.ts

@@ -4,7 +4,20 @@ import {
   asRecord, readBoolean, readNumber, readOptionalString, readString, readStringArray
 } from '../../infrastructure/json/JsonRecord'
 
-const SETTLE_DELAY_MS = 6_000
+/**
+ * How long to keep waiting for the window to have something on it.
+ *
+ * This used to be a flat six-second sleep, which is a guess about somebody else's
+ * machine: on a cold start — a freshly built app, Gatekeeper checking it, a first DNS
+ * lookup and the catalog still in flight — six seconds is sometimes not enough, and the
+ * run reported an empty window as a failure. It was not a failure; it was a stopwatch.
+ *
+ * Now it polls for a settled window and only gives up at the ceiling, so the common
+ * case is *faster* than the old fixed wait and the cold case still passes.
+ */
+const SETTLE_POLL_MS = 400
+const SETTLE_CEILING_MS = 30_000
+const SETTLE_DELAY_MS = 1_000
 const SWITCH_SETTLE_DELAY_MS = 8_000
 const SHOT_FRAME_DELAY_MS = 400
 
@@ -26,6 +39,10 @@ interface SelfTestReport {
   readonly paths: string
   readonly logLines: number
   readonly locales: readonly string[]
+  /** `<accessible name>:<glyph count>` per icon-only control in the footer. */
+  readonly iconControls: readonly string[]
+  /** `<title> [current|newer] Upgrade:on|off Uninstall:on|off` per installed card. */
+  readonly cardMenus: readonly string[]
 }
 
 /** What changed after clicking a store that was not open. */
@@ -51,12 +68,14 @@ export class SelfTestRunner {
     private readonly shotPath: string | null = process.env['SELFTEST_SHOT'] ?? null
   ) {}
 
+  /** A short first wait; `run` does the rest of the waiting itself. */
   public get settleDelayMs (): number {
     return SETTLE_DELAY_MS
   }
 
   /** True when the window is in a state a user could work with. */
   public async run (): Promise<boolean> {
+    await this.awaitSettled()
     const report = await this.readReport()
     console.log(JSON.stringify(report, null, 2))
 
@@ -65,10 +84,24 @@ export class SelfTestRunner {
 
     if (this.shotPath !== null) await this.captureShot(this.shotPath)
 
-    const rendered = report.locales.length > 1 && (
+    // A gate passes on having something to do, not on having a picker: the picker
+    // only appears when the registry offers more than one store, and one store is
+    // the ordinary case. Requiring choices here failed a perfectly good window.
+    // Every footer icon must be named and drawn. There are three — refresh, add a
+    // store, and the language picker — and none of them has a label, so an unnamed one
+    // is a button nobody can identify and the failure is silent because the glyph still
+    // draws. The count is a floor rather than an equality: a fourth control is somebody
+    // adding one, which this should not fail on; a missing one is what it guards.
+    const iconsNamed = report.iconControls.length >= 3 &&
+      report.iconControls.every((control: string): boolean => /^.+:1$/.test(control))
+    // Every installed card offers both actions, and Upgrade is enabled exactly when the
+    // version line says there is something newer. Uninstall is always available.
+    const menusAgree = report.cardMenus.every((entry: string): boolean =>
+      /\[newer\] \S+:on \S+:on$/.test(entry) || /\[current\] \S+:off \S+:on$/.test(entry))
+    const rendered = report.locales.length > 1 && iconsNamed && menusAgree && (
       (report.cards > 0 && !report.gateVisible && report.stores.length > 0 &&
         report.categories.length > 0 && report.activeCategory !== null) ||
-      (report.gateVisible && report.gateChoices.length > 0 && report.gateAction.length > 0))
+      (report.gateVisible && report.gateAction.length > 0))
     const switchedWell = switched === null || (
       switched.storeId.length > 0 && switched.storeId !== report.storeId &&
       switched.cards > 0 && switched.categories > 0)
@@ -78,6 +111,27 @@ export class SelfTestRunner {
     return passed
   }
 
+  /**
+   * Wait until the window is showing something, or until the ceiling.
+   *
+   * "Something" is a card or the gate: those are the two states a person could act on,
+   * and between them they cover every way this application legitimately ends up. Timing
+   * out is not treated as a failure here — the report is taken anyway, and the checks
+   * below decide, so a genuinely empty window still fails for the right reason rather
+   * than as a timeout with no detail.
+   */
+  private async awaitSettled (): Promise<void> {
+    const deadline = Date.now() + SETTLE_CEILING_MS
+    while (Date.now() < deadline) {
+      const ready = await this.evaluate(
+        "String(document.querySelectorAll('.card').length > 0 || " +
+        "!document.getElementById('gate').hidden)"
+      )
+      if (ready === 'true') return
+      await delay(SETTLE_POLL_MS)
+    }
+  }
+
   private async readReport (): Promise<SelfTestReport> {
     const record = asRecord(JSON.parse(await this.evaluate(`JSON.stringify({
       cards: document.querySelectorAll('.card').length,
@@ -95,7 +149,25 @@ export class SelfTestRunner {
       activeCategory: (document.querySelector('#cats .cat.is-active') || {}).textContent || null,
       paths: document.getElementById('log-paths').textContent.slice(0, 120),
       logLines: document.querySelectorAll('.log-line').length,
-      locales: [...document.getElementById('locale').options].map((option) => option.value)
+      locales: [...document.getElementById('locale').options].map((option) => option.value),
+      // The two icon-only controls: a glyph with no accessible name is a button nobody
+      // can identify, and the failure is silent because the icon still draws.
+      // One entry per installed card: its title, whether the version line shows an
+      // upgrade, and the menu's two items with their disabled state. This is the only
+      // way to see that Upgrade is offered exactly when there is something newer —
+      // a screenshot shows a closed menu.
+      cardMenus: [...document.querySelectorAll('.card.is-installed')].map((card) => {
+        const items = [...card.querySelectorAll('.menu-item')]
+          .map((item) => item.textContent + (item.disabled ? ':off' : ':on'))
+        const arrow = card.querySelector('.version.has-update') === null ? 'current' : 'newer'
+        return (card.querySelector('h2') || {}).textContent + ' [' + arrow + '] ' + items.join(' ')
+      }),
+      iconControls: [...document.querySelectorAll('.side-tools .icon-btn')]
+        .map((control) => {
+          const named = control.getAttribute('aria-label') || control.getAttribute('title') ||
+            (control.querySelector('[aria-label]') || {}).ariaLabel || ''
+          return named + ':' + control.querySelectorAll('svg.icon').length
+        })
     })`))) ?? {}
 
     return {
@@ -114,7 +186,9 @@ export class SelfTestRunner {
       activeCategory: readOptionalString(record, 'activeCategory'),
       paths: readString(record, 'paths'),
       logLines: readNumber(record, 'logLines'),
-      locales: readStringArray(record, 'locales')
+      locales: readStringArray(record, 'locales'),
+      iconControls: readStringArray(record, 'iconControls'),
+      cardMenus: readStringArray(record, 'cardMenus')
     }
   }
 
@@ -125,9 +199,12 @@ export class SelfTestRunner {
    */
   private async switchStore (): Promise<StoreSwitchReport> {
     const record = asRecord(JSON.parse(await this.evaluate(`(async () => {
+      // The row is a wrapper now; the part that switches stores is the button inside
+      // it. Clicking the wrapper did nothing at all, and a click that does nothing is
+      // exactly the kind of silent break this test exists for.
       const other = [...document.querySelectorAll('#store-list .store-row')]
         .find((row) => !row.classList.contains('is-active'))
-      other.click()
+      other.querySelector('.store-row-open').click()
       await new Promise((done) => setTimeout(done, ${String(SWITCH_SETTLE_DELAY_MS)}))
       return JSON.stringify({
         storeId: document.getElementById('store-id').textContent,
@@ -171,3 +248,9 @@ export class SelfTestRunner {
     return typeof result === 'string' ? result : JSON.stringify(result ?? null)
   }
 }
+
+async function delay (milliseconds: number): Promise<void> {
+  await new Promise<void>((resolve: () => void): void => {
+    setTimeout((): void => { resolve() }, milliseconds)
+  })
+}

src/main/ipc/AccountIpcController.ts

@@ -0,0 +1,80 @@
+import os from 'node:os'
+import type { AccountService, SignInResult } from '../../application/services/AccountService'
+import type { StoreAccount } from '../../domain/models/StoreAccount'
+import { IPC_CHANNELS } from '../../shared/contracts/IpcChannels'
+import type { AccountDto, SignInPromptDto } from '../../shared/contracts/dto/AccountDto'
+import type { WindowStreamBroadcaster } from '../streams/WindowStreamBroadcaster'
+import type { IpcRouter } from './IpcRouter'
+
+/**
+ * Signing in and out.
+ *
+ * Deliberately outside the single-flight guard: signing in takes as long as somebody
+ * takes to find their browser, and holding the store busy for that would stop them
+ * doing anything else meanwhile. Nothing here writes to the library.
+ *
+ * `beginSignIn` answers with the code as soon as there is one and lets the waiting run
+ * on; the end arrives on the sign-in stream. A reply that only came back minutes later
+ * would be a request the window had to keep alive for no reason.
+ */
+export class AccountIpcController {
+  public constructor (
+    private readonly accounts: AccountService,
+    private readonly streams: WindowStreamBroadcaster
+  ) {}
+
+  public register (router: IpcRouter): void {
+    router.handle(IPC_CHANNELS.accountRead, async (): Promise<AccountDto> =>
+      toDto(await this.accounts.readAccount()))
+    router.handle(IPC_CHANNELS.accountBeginSignIn, async (): Promise<SignInPromptDto> =>
+      this.handleBeginSignIn())
+    router.handle(IPC_CHANNELS.accountCancelSignIn, (): Promise<void> => {
+      this.accounts.cancelSignIn()
+      return Promise.resolve()
+    })
+    router.handle(IPC_CHANNELS.accountSignOut, async (): Promise<AccountDto> =>
+      toDto(await this.accounts.signOut()))
+  }
+
+  private async handleBeginSignIn (): Promise<SignInPromptDto> {
+    const session = await this.accounts.beginSignIn(clientName())
+
+    session.finished.then((result: SignInResult): void => {
+      this.streams.publishSignInFinished({
+        outcome: result.outcome, account: toDto(result.account)
+      })
+    }, (error: unknown): void => {
+      // A sign-in that fell over is a sign-in that did not happen; the window needs to
+      // stop showing a code either way.
+      this.streams.publishSignInFinished({
+        outcome: 'expired', account: { signInAvailable: true, signedIn: false }
+      })
+      this.streams.publishLog(`sign-in failed: ${describe(error)}`)
+    })
+
+    return {
+      userCode: session.prompt.userCode,
+      verificationUrl: session.prompt.verificationUrl,
+      expiresInSeconds: session.prompt.expiresInSeconds
+    }
+  }
+}
+
+function toDto (account: StoreAccount): AccountDto {
+  return { signInAvailable: account.signInAvailable, signedIn: account.signedIn }
+}
+
+/**
+ * What this device calls itself on the person's account page.
+ *
+ * The machine's own name, because that is what somebody looking at a list of signed-in
+ * devices needs in order to recognise which one to remove.
+ */
+function clientName (): string {
+  const hostname = os.hostname()
+  return hostname.length > 0 ? `WarpEngine Client (${hostname})` : 'WarpEngine Client'
+}
+
+function describe (error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

src/main/ipc/CatalogIpcController.ts

@@ -46,7 +46,11 @@ export class CatalogIpcController {
       return {
         games: this.gameMapper.toDtoList(listing.games, baseUrl),
         skipped: listing.skipped,
-        paths: listing.paths === null ? null : this.pathsMapper.toDto(listing.paths)
+        paths: listing.paths === null ? null : this.pathsMapper.toDto(listing.paths),
+        account: {
+          signInAvailable: listing.account.signInAvailable,
+          signedIn: listing.account.signedIn
+        }
       }
     })
   }

src/main/ipc/IpcArguments.ts

@@ -30,11 +30,10 @@ export function requireRegistryStore (value: unknown): RegistryStoreDto {
   const store: RegistryStoreDto = {
     name: readString(record, 'name'),
     catalogUrl: readString(record, 'catalogUrl'),
-    storeRepositoryUrl: readString(record, 'storeRepositoryUrl'),
     storeId: readString(record, 'storeId')
   }
-  if (store.name.length === 0 || store.catalogUrl.length === 0 || store.storeRepositoryUrl.length === 0) {
+  if (store.name.length === 0 || store.catalogUrl.length === 0) {
-    throw new TypeError('a store record needs a name, a catalog URL and a repository URL')
+    throw new TypeError('a store record needs a name and a catalog URL')
   }
   return store
 }

src/main/ipc/StoreIpcController.ts

@@ -1,5 +1,4 @@
 import { InstalledStoreDtoMapper } from '../../application/mappers/InstalledStoreDtoMapper'
-import { EngineVersionDtoMapper } from '../../application/mappers/EngineVersionDtoMapper'
 import { RegistryStoreDtoMapper } from '../../application/mappers/RegistryStoreDtoMapper'
 import type { StoreProvisioningService } from '../../application/services/StoreProvisioningService'
 import type { StoreSelectionService } from '../../application/services/StoreSelectionService'
@@ -20,8 +19,7 @@ export class StoreIpcController {
     private readonly guard: SingleFlightGuard,
     private readonly streams: WindowStreamBroadcaster,
     private readonly registryMapper: RegistryStoreDtoMapper = new RegistryStoreDtoMapper(),
-    private readonly storeMapper: InstalledStoreDtoMapper = new InstalledStoreDtoMapper(),
+    private readonly storeMapper: InstalledStoreDtoMapper = new InstalledStoreDtoMapper()
-    private readonly engineMapper: EngineVersionDtoMapper = new EngineVersionDtoMapper()
   ) {}
 
   public register (router: IpcRouter): void {
@@ -29,8 +27,12 @@ export class StoreIpcController {
       this.handleListRegistry())
     router.handle(IPC_CHANNELS.storeInstallStore, async (store: unknown): Promise<InstalledStoreDto> =>
       this.handleInstallStore(store))
+    router.handle(IPC_CHANNELS.storeInstallCatalog, async (url: unknown): Promise<InstalledStoreDto> =>
+      this.handleInstallCatalog(requireString(url, 'catalogUrl')))
     router.handle(IPC_CHANNELS.storeSelectStore, (home: unknown): StoreSelectionDto =>
       this.handleSelectStore(requireString(home, 'home')))
+    router.handle(IPC_CHANNELS.storeRemoveStore, async (home: unknown): Promise<void> =>
+      this.handleRemoveStore(requireString(home, 'home')))
   }
 
   /**
@@ -62,12 +64,39 @@ export class StoreIpcController {
     })
   }
 
+  /**
+   * A catalog somebody typed, rather than one the registry offered.
+   *
+   * Only the address crosses the bridge. The name is derived from it and the
+   * configuration comes from the engine's defaults, so a typed URL can no more decide
+   * where files land than a registry record can.
+   */
+  private async handleInstallCatalog (catalogUrl: string): Promise<InstalledStoreDto> {
+    return this.guard.run(async (): Promise<InstalledStoreDto> => {
+      const installed = await this.provisioning.installCatalog(
+        catalogUrl, null, this.streams.asProgressListener()
+      )
+      return this.storeMapper.toDto(installed)
+    })
+  }
+
   private handleSelectStore (home: string): StoreSelectionDto {
-    const store = this.selection.selectStore(home)
+    return { store: this.storeMapper.toDto(this.selection.selectStore(home)) }
-    const engine = this.selection.findEngineVersion(store)
+  }
-    return {
+
-      store: this.storeMapper.toDto(store),
+  /**
-      engine: engine === null ? null : this.engineMapper.toDto(engine)
+   * Remove a store by its home.
-    }
+   *
+   * The home is resolved against the stores actually on this machine before anything
+   * is deleted — the window names a store, never a path. Guarded, because it uninstalls
+   * every title the store put here and a second engine call across that would be
+   * working on files this one is removing.
+   */
+  private async handleRemoveStore (home: string): Promise<void> {
+    await this.guard.run(async (): Promise<void> => {
+      await this.provisioning.removeStore(
+        this.selection.requireStoreAt(home), this.streams.asProgressListener()
+      )
+    })
   }
 }

src/main/streams/WindowStreamBroadcaster.ts

@@ -1,10 +1,12 @@
 import type { BrowserWindow } from 'electron'
 import type { EngineProgressListener } from '../../domain/models/EngineProgress'
 import { IPC_CHANNELS } from '../../shared/contracts/IpcChannels'
+import type { SignInFinishedDto } from '../../shared/contracts/dto/AccountDto'
 import type { SyncEventDto } from '../../shared/contracts/dto/SyncEventDto'
 
 /**
- * The three one-way streams to the window: log lines, progress events, busy state.
+ * The one-way streams to the window: log lines, progress events, busy state, and how a
+ * sign-in ended.
  *
  * Holds no window of its own — the reference is handed in when one exists and
  * cleared when it does not, so a stream that outlives the window is a no-op rather
@@ -33,6 +35,14 @@ export class WindowStreamBroadcaster {
     this.send(IPC_CHANNELS.streamBusyChanged, busy)
   }
 
+  /**
+   * A sign-in finishes minutes after the call that started it returned, and in another
+   * window entirely — so it arrives as an event rather than as a reply.
+   */
+  public publishSignInFinished (result: SignInFinishedDto): void {
+    this.send(IPC_CHANNELS.streamSignInFinished, result)
+  }
+
   /** A progress listener wired to these streams, for handing to the engine. */
   public asProgressListener (): EngineProgressListener {
     return {

src/preload/preload.ts

@@ -3,6 +3,9 @@ import {
   BRIDGE_GLOBAL_NAME, type BridgeApi, type StreamListener
 } from '../shared/contracts/BridgeApi'
 import { IPC_CHANNELS } from '../shared/contracts/IpcChannels'
+import type {
+  AccountDto, SignInFinishedDto, SignInPromptDto
+} from '../shared/contracts/dto/AccountDto'
 import type { AppStateDto } from '../shared/contracts/dto/AppStateDto'
 import type { CatalogListingDto } from '../shared/contracts/dto/CatalogListingDto'
 import type { InstalledStoreDto } from '../shared/contracts/dto/InstalledStoreDto'
@@ -40,12 +43,25 @@ const bridge: BridgeApi = {
   launchGame: async (name: string): Promise<boolean> =>
     ipcRenderer.invoke(IPC_CHANNELS.catalogLaunchGame, name) as Promise<boolean>,
 
+  readAccount: async (): Promise<AccountDto> =>
+    ipcRenderer.invoke(IPC_CHANNELS.accountRead) as Promise<AccountDto>,
+  beginSignIn: async (): Promise<SignInPromptDto> =>
+    ipcRenderer.invoke(IPC_CHANNELS.accountBeginSignIn) as Promise<SignInPromptDto>,
+  cancelSignIn: async (): Promise<void> =>
+    ipcRenderer.invoke(IPC_CHANNELS.accountCancelSignIn) as Promise<void>,
+  signOut: async (): Promise<AccountDto> =>
+    ipcRenderer.invoke(IPC_CHANNELS.accountSignOut) as Promise<AccountDto>,
+
   listRegistryStores: async (): Promise<RegistryResultDto> =>
     ipcRenderer.invoke(IPC_CHANNELS.storeListRegistry) as Promise<RegistryResultDto>,
   installStore: async (store: RegistryStoreDto): Promise<InstalledStoreDto> =>
     ipcRenderer.invoke(IPC_CHANNELS.storeInstallStore, store) as Promise<InstalledStoreDto>,
+  installCatalog: async (catalogUrl: string): Promise<InstalledStoreDto> =>
+    ipcRenderer.invoke(IPC_CHANNELS.storeInstallCatalog, catalogUrl) as Promise<InstalledStoreDto>,
   selectStore: async (home: string): Promise<StoreSelectionDto> =>
     ipcRenderer.invoke(IPC_CHANNELS.storeSelectStore, home) as Promise<StoreSelectionDto>,
+  removeStore: async (home: string): Promise<void> =>
+    ipcRenderer.invoke(IPC_CHANNELS.storeRemoveStore, home) as Promise<void>,
 
   openFolder: async (directory: string): Promise<boolean> =>
     ipcRenderer.invoke(IPC_CHANNELS.appOpenFolder, directory) as Promise<boolean>,
@@ -66,6 +82,12 @@ const bridge: BridgeApi = {
     ipcRenderer.on(IPC_CHANNELS.streamBusyChanged, (_event: IpcRendererEvent, busy: boolean): void => {
       listener(busy)
     })
+  },
+  onSignInFinished: (listener: StreamListener<SignInFinishedDto>): void => {
+    ipcRenderer.on(
+      IPC_CHANNELS.streamSignInFinished,
+      (_event: IpcRendererEvent, payload: SignInFinishedDto): void => { listener(payload) }
+    )
   }
 }
 

src/renderer/RendererApplication.ts

@@ -1,5 +1,6 @@
 import type { BridgeApi } from '../shared/contracts/BridgeApi'
 import { requireBridge } from './BridgeAccess'
+import { AccountController } from './controllers/AccountController'
 import { CatalogController } from './controllers/CatalogController'
 import { EngineStreamController } from './controllers/EngineStreamController'
 import { PreferencesController } from './controllers/PreferencesController'
@@ -11,6 +12,7 @@ import { GameCardView } from './views/GameCardView'
 import { GateView } from './views/GateView'
 import { LogDrawerView } from './views/LogDrawerView'
 import { SideMenuView } from './views/SideMenuView'
+import { SignInView } from './views/SignInView'
 import { TopBarView } from './views/TopBarView'
 
 /**
@@ -28,10 +30,12 @@ export class RendererApplication {
   private readonly grid: CatalogGridView
   private readonly topBar: TopBarView
   private readonly sideMenu: SideMenuView
+  private readonly signInPanel: SignInView
   private readonly catalog: CatalogController
   private readonly stores: StoreController
   private readonly preferences: PreferencesController
   private readonly streams: EngineStreamController
+  private readonly accounts: AccountController
 
   public constructor (bridge: BridgeApi = requireBridge()) {
     this.bridge = bridge
@@ -41,29 +45,60 @@ export class RendererApplication {
     })
     this.gate = new GateView((url: string): void => { void this.bridge.openUrl(url) })
     this.catalog = new CatalogController(this.bridge, this.store, this.log)
-    this.stores = new StoreController(this.bridge, this.store, this.gate, this.log, this.catalog)
+    this.stores = new StoreController(this.bridge, this.store, this.log, this.catalog)
     this.preferences = new PreferencesController(this.bridge, this.store)
     this.streams = new EngineStreamController(this.bridge, this.store, this.log)
+    this.accounts = new AccountController(
+      this.bridge, this.store, this.log,
+      async (): Promise<void> => { await this.catalog.refresh() }
+    )
 
     this.grid = new CatalogGridView(new GameCardView({
       onInstall: (name: string): void => { void this.catalog.syncGames([name]) },
+      // The same call as an install: a sync of one name fetches whatever the catalog
+      // now has for it, and the engine replaces the old payload and menu entry.
+      onUpgrade: (name: string): void => { void this.catalog.syncGames([name]) },
       onLaunch: (name: string): void => { void this.catalog.launchGame(name) },
-      onRemove: (name: string): void => { void this.catalog.removeGame(name) }
+      onRemove: (name: string): void => { void this.catalog.removeGame(name) },
+      onPurchase: (name: string): void => { void this.purchase(name) },
+      onSignIn: (): void => { void this.accounts.signIn() }
     }))
+    this.signInPanel = new SignInView({
+      onOpenPage: (): void => { void this.accounts.openVerificationPage() },
+      onCancel: (): void => { void this.accounts.cancelSignIn() }
+    })
     this.topBar = new TopBarView({
       onToggleNavigation: (): void => { void this.preferences.toggleNavigation() }
     })
     this.sideMenu = new SideMenuView({
       onSelectStore: (home: string): void => { void this.stores.selectStore(home) },
+      onRemoveStore: (home: string, name: string): void => { void this.stores.removeStore(home, name) },
       onAddStore: (): void => { void this.stores.offerStores() },
-      onSyncAll: (): void => { void this.catalog.syncGames([]) },
       onRefresh: (): void => { void this.catalog.refresh() },
       onSelectCategory: (filter: CategoryFilter): void => { this.store.applyFilter(filter) },
-      onSelectLocale: (locale: string): void => { void this.preferences.selectLocale(locale) }
+      onSelectLocale: (locale: string): void => { void this.preferences.selectLocale(locale) },
+      onSignIn: (): void => { void this.accounts.signIn() },
+      onSignOut: (): void => { void this.accounts.signOut() }
     })
 
     this.store.subscribe((state: AppState): void => { this.render(state) })
     this.streams.subscribe()
+    this.accounts.subscribe()
+  }
+
+  /**
+   * Buying happens in a browser.
+   *
+   * A checkout rebuilt in this window would be a second place to get card handling
+   * wrong, and the store's own pages already do it. What this side owes afterwards is
+   * a refresh, which the Refresh button is for.
+   */
+  private async purchase (name: string): Promise<void> {
+    const url = this.store.readState().games
+      .find((candidate): boolean => candidate.name === name)?.purchaseUrl ?? null
+    if (url === null) return
+
+    await this.bridge.openUrl(url)
   }
 
   /** Decides what the window is showing, then hands over to the views. */
@@ -71,19 +106,11 @@ export class RendererApplication {
     this.store.applyAppState(await this.bridge.readState())
     const state = this.store.readState()
 
-    if (state.pythonVersion === null) {
-      this.stores.showMissingPythonGate()
-      return
-    }
     if (state.currentStore === null) {
       await this.stores.offerStores()
       return
     }
-    if (state.engine !== null && !state.engine.supported) {
+    this.store.applyGate(null)
-      this.stores.showOutdatedEngineGate()
-      return
-    }
-    this.gate.hide()
     await this.catalog.refresh()
   }
 
@@ -97,10 +124,19 @@ export class RendererApplication {
     }
 
     document.body.classList.toggle('nav-closed', !state.navigationOpen)
+    this.signInPanel.render(state)
     this.topBar.render(state)
     this.sideMenu.render(state)
     this.log.render(state)
-    if (this.gate.visible) this.grid.hide()
+
-    else this.grid.render(state)
+    // The gate and the grid are alternatives, decided by one field, so they cannot
+    // both be on screen — which is what happened while this was two imperative calls.
+    if (state.gate === null) {
+      this.gate.hide()
+      this.grid.render(state)
+    } else {
+      this.gate.show(state.gate, state.messages)
+      this.grid.hide()
+    }
   }
 }