Read a store's config from the registry record

`GET /api/stores` records now carry a `config` field — a store's `config.json` moved
into the record that already said what the store is — and the client applies it
directly. Installing a store no longer depends on a second repository existing and
staying reachable, and a store can be configured from the site's admin alone.

The order is registry config, then a repository's `config.json`, then the engine's
defaults. The middle one is why nothing has to move at once: a registry whose stores
have not been migrated is read exactly as before.

The window cannot supply a config. It is handed stores to show and hands one back to
install, but only as an identity: `RegistryStoreDtoMapper.toModel` drops the config and
`StoreProvisioningService` reads the record again from the registry first. A config
decides where files are written and, through `paths.subfolder`, which subtree the store
may later delete from — not a decision the renderer gets to make, for the same reason a
`GameDto` carries no paths. Tested by installing from a record carrying
`subfolder: "ATTACKER"` and `install_root: "/tmp/pwned"` and finding neither on disk.

A store that has left the registry, or a registry that cannot be re-read, still
installs: it falls back to the engine's defaults rather than refusing.

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.
-VERSION := $(shell python3 -c 'import json; print(json.load(open("package.json"))["version"])')
+# The version is package.json's, so the release tag never drifts from the app. Read with
+# 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 \
         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}'
@@ -74,16 +86,16 @@ uitest: ## Load the window once and report what rendered
 test: smoke uitest ## Both 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 +118,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
-[`warp-engine-desktop-store`](https://git.teletypegames.org/stores/warp-engine-desktop-store):
-the catalog as a grid of cards, one click to install a title into your own
-application menu, one to play it, one to remove it. Linux, macOS and Windows.
+The client for a WarpEngine store: the catalog as a grid of cards, one click to install
+a title into your own 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
-`desktop_store.py`, so there is one catalog logic, one state file and one delete
-guard — the window never touches the filesystem itself.
+**The store engine is part of this application.** Reading the catalog, choosing which
+release fits this machine, unpacking it, writing the menu entry and remembering what
+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
-`curl … | sh`, which Windows does not have; this app downloads the store engine
-itself, into the same folder the shell installer would use.
+That also makes this the only install path that needs nothing of the machine. The shell
+store's installer was `curl … | sh`, which Windows does not have.
 
 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
-  looks for `python3`, `python` and `py -3`, and says so plainly if none answer.
-- Nothing else at runtime. No Node, no package manager, no admin rights: the
-  store installs under your own user account.
+- **Nothing.** No interpreter, no package manager, no admin rights: the app carries its
+  own runtime and 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
-Python does not set the quarantine flag.
+Nothing the store itself downloads is affected: the app fetches those files over its
+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,
@@ -66,33 +65,64 @@ and there is nothing to decide; several and the setup screen shows a picker.
   {
     "name": "Teletype Games",
     "catalogUrl": "https://teletypegames.org",
-    "storeRepositoryUrl": "https://git.teletypegames.org/stores/ttg-desktop-store"
-  }
+    "storeRepositoryUrl": "https://git.teletypegames.org/stores/ttg-desktop-store",
+    "config": { "store": { "id": "ttg" }, "paths": { "subfolder": "teletypegames" } }
+  },
+  { "name": "Some Other Store", "catalogUrl": "https://games.example.org",
+    "storeRepositoryUrl": null, "config": null }
 ]
 ```
 
-From a record the client works out the rest:
+**A store needs nothing of its own.** A name and a catalog are enough: 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 — a
+slug, a name and a catalog URL — and that is exactly what a registry record carries.
+With `config` and `storeRepositoryUrl` both null the client writes a three-section
+config and the store installs.
+
+Where a store's configuration comes from, in the order the client asks:
+
+1. **`config` on the registry record** — the store's own configuration, in the same
+   shape a store's `config.json` had, because it is that file moved into the registry.
+   It costs no request: it arrived with the store list.
+2. **`storeRepositoryUrl` → `…/raw/branch/master/config.json`** — the same thing in its
+   older home, read for a registry whose stores have not moved over yet. A repository
+   **without** a `config.json` is treated as no repository at all.
+3. **the engine's defaults** — when there is neither.
+
+Two fields the record always decides, whatever the config says:
 
-- **`storeRepositoryUrl`** → the store's `config.json`, read from
-  `…/raw/branch/master/config.json`. That file is the authority on how the store
-  behaves: which platforms, which statuses, where things land.
 - **`catalogUrl` and `name`** override the config's own `store.base_url` and
   `store.name`. The registry says which catalog this store is *for*, so it wins.
-- **the store id** — which names the store home and the folder games land in —
-  comes from the repository name: `ttg-desktop-store` becomes `ttg`. A
-  `config.json` that sets its own id keeps it.
+- **the store id** — which names the store home and the folder games land in — comes
+  from the config's `store.id` when it sets one; otherwise from the repository name
+  (`ttg-desktop-store` becomes `ttg`), then the catalog host (`teletypegames.org`
+  becomes `teletypegames`), then the display name.
 
-A repository **without** a `config.json` still works. The engine merges whatever
-it is handed onto its own defaults, so the client writes a three-field config and
-the store behaves like the default one pointed at that catalog.
+**The window never supplies a config.** It is handed stores to show and hands one back
+to install, but only as an identity: `RegistryStoreDtoMapper.toModel` drops the config,
+and `StoreProvisioningService` reads the record again from the registry before
+installing. A config decides where files are written and which subtree the store may
+later delete from, so it must not be something the renderer can set — the same rule as
+`GameDto` carrying no paths.
 
-The registry address is the single thing about a particular site left in the
-client, and `STORES_API` overrides it:
+What the defaults produce, for a record with no repository: the games land in a
+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.
 
@@ -107,8 +137,8 @@ Everything that is not a title lives in the **side menu** on the left, and the
   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
   picker, the same one the first run offers.
-- **Actions** holds **Install all**, which fetches everything the catalog offers
-  for this machine, and **Refresh**, which re-reads the catalog.
+- **Actions** holds **Refresh**, which re-reads the catalog. 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).
@@ -116,6 +146,9 @@ Everything that is not a title lives in the **side menu** on the left, and the
   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 +157,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
-to it are buttons that open the two folders everything lands in.
+**Everything in the catalog is listed, including what this machine cannot install.**
+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.
@@ -167,16 +205,77 @@ 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.
 
+### 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
-version is set. The release is created if it is not there yet, 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.
+This is the **macOS half** of a release; the Linux and Windows packages come from the
+pipeline when the tag is pushed (see above). The tag comes from `package.json`, so
+`npm version patch` is the only place a version is set. The release is created if it is
+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,7 +287,7 @@ 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 contain a space — `WarpEngine Client-1.5.0-arm64.dmg` — so the list of
 files is passed one path per line rather than as one string; splitting it on
 whitespace is what broke the first attempt at publishing 1.1.0.
 
@@ -224,9 +323,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 +346,65 @@ 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
-program. It talks to the CLI through `--json`, which puts data on stdout and the
-human-readable log on stderr. That flag arrived with engine **1.1.0**, and the client
-checks: an older store is met with an offer to refresh it rather than a failed call.
+`NativeStoreCatalogGateway` is the engine behind the `StoreCatalogGateway` port, and
+`src/infrastructure/engine/` is the engine itself: the catalog client, the release
+picker, the host match, the payload installer, the three launcher writers and the state
+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,
-so a second entry is the whole change needed to drive it too — that is why the table is
-there.
+`STORE_ENGINES` has one entry today. A RetroArch store writes playlists rather than
+menu entries, so it would be an entry there and a gateway of its own.
+
+### 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
 
+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,58 @@
-# WarpEngine Store 1.3.0
+# WarpEngine Client 2.1.0
 
-**TypeScript, in layers.** The client was one `main.js`, one `preload.js`, three files
-in `lib/` and one renderer script. It is now a typed application with the dependency
-rule pointing inward: `domain` (models, ports, errors) knows nothing about Electron,
-Node or Python; `application` orchestrates it through those ports; `infrastructure`
-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.
+**A store's configuration now comes from the registry itself.** `GET /api/stores`
+records carry a `config` field — the same thing a store's `config.json` held, moved into
+the record that already says what the store is. The client applies it directly, so
+installing a store no longer depends on a second repository existing and staying
+reachable, and a store can be configured entirely from the site's admin.
 
-Nothing about the window changed. Same side menu, same categories, same switcher, same
-two languages — this release is the inside of the app.
+The old path still works. Where a record has no `config` but names a repository, the
+client reads `…/raw/branch/master/config.json` from it exactly as before, so a registry
+whose stores have not moved over is unaffected. With neither, the engine's defaults
+carry the store, as they always have. The order is: registry config, then repository
+file, then defaults.
 
-Two properties came out of the move, and both are worth having:
+**The window cannot supply a store config.** It is handed stores to show and hands one
+back to install, but only as an identity — the config is dropped on the way in, and the
+main process reads the record again from the registry before installing anything. This
+is not tidiness: a config decides where files are written and, through
+`paths.subfolder`, which subtree the store may later delete from. That is not a decision
+the renderer gets to make, for the same reason a `GameDto` carries no paths.
 
-- **The catalog can be driven with no window and no Electron at all.** `make smoke`
-  assembles the same services against the same ports in a plain Node process. It was a
-  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.
+### Also
 
-**A strict linter, and types everywhere.** `strict` plus
-`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.
+The headless check now reports *which* source configured a store — registry, repository
+or defaults — and names the resulting prune boundary, because "it installed" and "it
+installed where I meant" are different claims.
 
 ### Opening it on macOS
 
 Ad-hoc signed, **not notarised**, so macOS asks first:
 
 ```sh
-xattr -dr com.apple.quarantine "/Applications/WarpEngine Store.app"
+xattr -dr com.apple.quarantine "/Applications/WarpEngine Client.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`).
+The macOS package, built and verified on a Mac, plus the Linux (AppImage, deb) and
+Windows (installer, portable) packages the pipeline builds when the tag is pushed.
 
 ### 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.
+`make check` is clean: typecheck, lint, the headless smoke test and the window
+self-test.
+
+All three configuration sources were exercised end to end against the real serializer
+output, with the client's own classes and a sandbox store root:
+
+| Registry record | What configured the store | Prune boundary written |
+|---|---|---|
+| `config` present | the registry, with no extra request | `teletypegames` |
+| `config: null`, repository given | the repository's `config.json` | `teletypegames` |
+| neither | the engine's defaults | `teletypegames` |
+
+The renderer barrier was tested adversarially rather than assumed: an install started
+from a record carrying `paths.subfolder: "ATTACKER"` and `paths.install_root:
+"/tmp/pwned"` wrote `subfolder: teletypegames` and `install_root: null` to disk, because
+the service re-read the registry and the mapper had already dropped the config.

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,11 +57,15 @@ 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
+      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, HttpStatusError
+    http/                     HttpTextClient, StoreHttpClient, HttpStatusError
     json/                     JsonRecord: reading data that came from elsewhere
+    config/                   BuildConfiguration: what was decided when this was packaged
     electron/                 ApplicationEnvironment and GameLauncher adapters
   main/
     main.ts                   the entry point: one line of work
@@ -94,9 +98,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
-the Python CLI, the registry HTTP call and Electron's `shell` replaceable — by a stub
-in a test, by a local endpoint in development, by a second engine later.
+root is the only file that knows which implementation is in use. This is what makes the
+store engine, the registry HTTP call and Electron's `shell` replaceable — by a stub in a
+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 +112,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:
-  `StoreCatalogGateway` (the engine).
+- **Gateway** — something with a protocol of its own, whether or not it is another
+  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 +128,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.
-  These are the only files that know the engine's field names.
+- `infrastructure/engine/dialects/*` — catalog JSON → typed catalog records. These are
+  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 +174,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 +188,8 @@ never calls the bridge.
 ### Error hierarchy with codes
 
 `DomainError` is abstract with a `code`; subclasses name a single failure
-(`PythonMissingError`, `StoreMissingError`, `EngineInvocationError`,
-`RegistryUnavailableError`, `BusyError`). The code is what crosses the bridge.
+(`StoreMissingError`, `EngineInvocationError`, `RegistryUnavailableError`, `BusyError`).
+The code is what crosses the bridge.
 
 ### Frozen constant tables
 
@@ -179,9 +197,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 +232,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 +240,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 +294,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
-discovery, the home suffix and the launcher name all read from that table; the CLI has
-the same command shape, so `PythonStoreCatalogGateway` is unchanged.
+**A new engine (e.g. RetroArch).** Add an entry to `STORE_ENGINES` — the store discovery,
+the home suffix and the launcher name all read from that table — and a `StoreCatalogGateway`
+implementation for that host. Everything above the port is unchanged.
 
-**A new field from the engine.** `EngineGameMapper` reads it into the model, `GameDto`
-and `GameDtoMapper` carry it across if the window needs it, and a view renders it.
+**A new WarpEngine version.** Add it to `SUPPORTED_WARP_ENGINE_VERSIONS`. The build then
+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,11 +1,11 @@
 {
-  "name": "warp-engine-desktop-gui",
+  "name": "warp-engine-client",
   "version": "1.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "warp-engine-desktop-gui",
+      "name": "warp-engine-client",
       "version": "1.2.0",
       "license": "MIT",
       "devDependencies": {

package.json

@@ -1,11 +1,11 @@
 {
-  "name": "warp-engine-desktop-gui",
-  "productName": "WarpEngine Store",
-  "version": "1.3.0",
-  "description": "Graphical client for a WarpEngine desktop store: install the catalog into your own application menu.",
+  "name": "warp-engine-client",
+  "productName": "WarpEngine Client",
+  "version": "2.1.0",
+  "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"
@@ -34,7 +34,7 @@
   },
   "build": {
     "appId": "org.teletypegames.warpstore.gui",
-    "productName": "WarpEngine Store",
+    "productName": "WarpEngine Client",
     "files": [
       "build/**/*",
       "package.json"
@@ -64,5 +64,8 @@
   "allowScripts": {
     "electron@43.4.0": true,
     "esbuild@0.28.2": true
+  },
+  "warpEngine": {
+    "registryUrl": "https://teletypegames.org/api/stores"
   }
 }

scripts/ci-upload.sh

@@ -0,0 +1,114 @@
+#!/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" "$@"
+}
+
+# Package names contain spaces — "WarpEngine Client Setup 1.5.0.exe" does — so the list
+# lives one path per line in a file and is read with `while IFS= read -r`. A single
+# variable looped over with $list splits on the space and uploads nothing.
+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:
-# nesting python quoting inside shell quoting inside a command substitution is how
-# this produced an empty title on its first outing.
-VERSION="$(python3 - <<'PY'
-import json
-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
-)"
+# Version and title from package.json, read with node. This project needs no interpreter
+# beyond the one it already builds with — the app itself carries no Python any more, and
+# neither should the script that ships it.
+VERSION="$(node -p 'require("./package.json").version')"
+TITLE="$(node -p 'const d = require("./package.json"); (d.productName || d.name) + " " + d.version')"
 TAG="${TAG:-v$VERSION}"
 [ -n "$VERSION" ] || die "cannot read the version from package.json"
 [ -n "$TITLE" ] || die "cannot work out a release title"
@@ -52,7 +43,7 @@ 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. "WarpEngine Client-1.5.0-arm64.dmg" has one, so the list lives one
 #     path per line in a file and is read with `while IFS= read -r`. Holding it in
 #     a single variable and looping over $list splits it on the space.
 LIST="$(mktemp)"
@@ -71,12 +62,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 '
-import json, sys
-try:
-    print(json.load(sys.stdin).get("id") or "")
-except Exception:
-    pass
+  tea api "/repos/$REPO/releases/tags/$TAG" 2>/dev/null | node -e '
+try {
+  console.log(JSON.parse(require("fs").readFileSync(0, "utf8")).id || "")
+} catch {
+  // Not JSON, or no such release: an empty answer is the "no release yet" case.
+}
 '
 }
 
@@ -103,13 +94,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 "
-import json, sys
-name = sys.argv[1]
-for a in json.load(sys.stdin):
-    if a['name'] == name:
-        print(a['id'])
-" "$1")"
+  ids="$(tea api "/repos/$REPO/releases/$RELEASE_ID/assets" | node -e '
+const name = process.argv[1]
+for (const asset of JSON.parse(require("fs").readFileSync(0, "utf8"))) {
+  if (asset.name === name) console.log(asset.id)
+}
+' -- "$1")"
   for id in $ids; do
     say "replacing $1"
     tea api -X DELETE "/repos/$REPO/releases/$RELEASE_ID/assets/$id" >/dev/null
@@ -120,7 +110,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 +130,10 @@ while IFS= read -r asset; do
 done < "$LIST"
 
 say "done:"
-tea api "/repos/$REPO/releases/$RELEASE_ID" | python3 -c "
-import json, sys
-r = json.load(sys.stdin)
-for a in r.get('assets') or []:
-    print(f\"  {a['name']}  {a['size']/1e6:.0f} MB\")
-print(f\"  {r['html_url']}\")"
+tea api "/repos/$REPO/releases/$RELEASE_ID" | node -e '
+const release = JSON.parse(require("fs").readFileSync(0, "utf8"))
+for (const asset of release.assets || []) {
+  console.log(`  ${asset.name}  ${(asset.size / 1e6).toFixed(0)} MB`)
+}
+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

@@ -26,7 +26,10 @@ 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
     }
   }
 

src/application/mappers/RegistryStoreDtoMapper.ts

@@ -16,12 +16,20 @@ export class RegistryStoreDtoMapper {
     return stores.map((store: RegistryStore): RegistryStoreDto => this.toDto(store))
   }
 
-  /** The window hands a record straight back when asking for an install. */
+  /**
+   * The window hands a record back when asking for an install — as an identity only.
+   *
+   * There is no `config` here on purpose. A store's config decides where files are
+   * written and which subtree the store may delete from, so it must not be something
+   * the window can supply; `StoreProvisioningService` reads the real record from the
+   * registry instead. That is the same rule as `GameDto` carrying no paths.
+   */
   public toModel (dto: RegistryStoreDto): RegistryStore {
     return {
       name: dto.name,
       catalogUrl: dto.catalogUrl,
-      storeRepositoryUrl: dto.storeRepositoryUrl
+      storeRepositoryUrl: dto.storeRepositoryUrl,
+      config: null
     }
   }
 }

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
- * round trips — and because the decisions the window makes from it (no Python, no
- * store, an engine too old) all depend on each other.
+ * One call rather than six, because the first frame should not be a sequence of round
+ * trips. There is one decision left in it — whether a store is set up yet — now that
+ * 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 engineMapper: EngineVersionDtoMapper = new EngineVersionDtoMapper()
+    private readonly storeMapper: InstalledStoreDtoMapper = new InstalledStoreDtoMapper()
   ) {}
 
   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/StoreProvisioningService.ts

@@ -31,11 +31,44 @@ export class StoreProvisioningService {
   }
 
   public async installStore (
-    store: RegistryStore,
+    chosen: RegistryStore,
     progress?: EngineProgressListener
   ): Promise<InstalledStore> {
+    const store = await this.resolveFromRegistry(chosen, progress)
     const home = this.stores.resolveDefaultHome(deriveStoreId(store))
     const installed = await this.installer.installEngine(home, store, progress)
     return this.selection.adoptStore(installed)
   }
+
+  /**
+   * The registry's own record for the store that was chosen.
+   *
+   * The window is handed stores to display and hands one back to install, but what it
+   * hands back is not what gets used. A store's config decides where files are written
+   * and which subtree the store may later delete from, so it cannot be something the
+   * window supplies — the choice is treated as an identity, a name and a catalog, and
+   * the record behind it is read again here.
+   *
+   * A store that has since left the registry, or a registry that cannot be reached, is
+   * not a reason to refuse the install: it proceeds on the engine's defaults, which is
+   * what a store with no config gets anyway.
+   */
+  private async resolveFromRegistry (
+    chosen: RegistryStore,
+    progress?: EngineProgressListener
+  ): Promise<RegistryStore> {
+    try {
+      const listed = await this.registry.listStores()
+      const found = listed.find((store: RegistryStore): boolean =>
+        store.catalogUrl === chosen.catalogUrl && store.name === chosen.name)
+      if (found !== undefined) return found
+      progress?.onLog?.(
+        `${chosen.name} is no longer in the registry — installing on the engine's defaults`)
+    } catch (error: unknown) {
+      const reason = error instanceof Error ? error.message : String(error)
+      progress?.onLog?.(
+        `the registry could not be read again (${reason}) — installing on the engine's defaults`)
+    }
+    return { ...chosen, config: null }
+  }
 }

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
   ) {}
 
@@ -58,15 +55,6 @@ export class StoreSelectionService {
     return store
   }
 
-  /**
-   * The engine version of a store, checked per store rather than once: two stores
-   * on one machine can be at different versions, and the one being switched to may
-   * be the older one.
-   */
-  public findEngineVersion (store: InstalledStore): EngineVersion | null {
-    return this.catalogGateway.readEngineVersion(store)
-  }
-
   public readDefaultStoreRoot (): string {
     return this.stores.readRoots()[0] ?? ''
   }

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/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,15 @@
 /** 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 +33,12 @@ 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
 }

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,59 @@
+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.
+ */
+export interface InstalledRecord extends SelectedGame {
+  /** 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,24 @@
 /**
  * A store the site's registry offers.
  *
- * Three fields, because that is what a record is: what it is called, which
- * catalog it serves, and where its configuration lives.
+ * A name and a catalog are what make a store; the other two fields are optional.
+ *
+ * `config` is how that store behaves — which platforms it offers, which release
+ * statuses it shows, where its games land — in the same shape a store's `config.json`
+ * had, because it is the same thing moved into the registry. With none, the engine's
+ * defaults cover all of it and this record covers the identity, which is why a store
+ * needs nothing of its own to be installable.
+ *
+ * `storeRepositoryUrl` is where the store's own repository is, when it has one. It is
+ * still read as a config source for a registry that has not moved its stores over yet.
  */
 export interface RegistryStore {
   readonly name: string
   readonly catalogUrl: string
-  readonly storeRepositoryUrl: string
+  readonly storeRepositoryUrl: string | null
+  /**
+   * Deliberately not `JsonRecord`: `domain` imports nothing from `infrastructure`, and
+   * a JSON object is describable without it.
+   */
+  readonly config: Readonly<Record<string, unknown>> | null
 }

src/domain/models/SelectedGame.ts

@@ -0,0 +1,57 @@
+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
+}
+
+/**
+ * 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
+}
+
+/** 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/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
- * command shape, so a second entry — not a second code path — is what adding it
- * would take.
+ * There is one today: the desktop engine, which is the code in
+ * `infrastructure/engine`. The table stays because a second host — RetroArch
+ * 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,39 @@
 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
- * and filesystem-safe. The repository name is the best source available before
- * anything is downloaded; the store's own config.json overrides it once it is.
+ * The id names the store home, the folder games land in and the launcher files, so
+ * it has to be short and filesystem-safe. Three sources, in order of how much they
+ * were meant to be a name:
+ *
+ *   1. the repository name — `ttg-desktop-store` becomes `ttg`;
+ *   2. the catalog host — `https://teletypegames.org` becomes `teletypegames`;
+ *   3. the display name, slugged, as a last resort.
+ *
+ * The store's own config.json overrides all of it whenever one exists.
  */
 export function deriveStoreId (store: RegistryStore): string {
-  const lastSegment = store.storeRepositoryUrl.replace(/\/+$/, '').split('/').pop() ?? ''
-  const base = lastSegment.replace(/-(desktop-)?store$/, '') || store.name
-  const slug = base.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
-  return slug || 'store'
+  const fromRepository = store.storeRepositoryUrl === null
+    ? ''
+    : (lastSegment(store.storeRepositoryUrl).replace(/-(desktop-)?store$/, ''))
+  return toSlug(fromRepository) || toSlug(readHostLabel(store.catalogUrl)) || toSlug(store.name) || 'store'
+}
+
+function lastSegment (url: string): string {
+  return url.replace(/\/+$/, '').split('/').pop() ?? ''
+}
+
+/** `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'] 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/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,18 @@
 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 { StorePaths } from '../models/StorePaths'
 
 /**
  * The store engine, as an interface.
  *
- * Every catalog operation this client performs is one call on this port; the CLI
- * behind it stays the product, and nothing above this line knows it is Python.
+ * Every catalog operation this client performs is one call on this port. The engine
+ * 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
 }

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/engine/CatalogClient.ts

@@ -0,0 +1,121 @@
+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
+  ) {
+    this.http = new StoreHttpClient({
+      userAgent: `warp-engine-client/${CLIENT_VERSION} (${configuration.store.id})`,
+      timeout: configuration.behavior.timeout,
+      insecure: configuration.behavior.insecure
+    })
+  }
+
+  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,191 @@
+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
+      })
+    }
+    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 {
+    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/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,267 @@
+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 { APP_MODE, WEB_MODE, type StoreConfiguration } from '../../domain/models/StoreConfiguration'
+import type { StorePaths } from '../../domain/models/StorePaths'
+import type { 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 { GameInstaller } from './GameInstaller'
+import { HostMachineDetector } from './HostMachineDetector'
+import { LauncherWriter } from './launchers/LauncherWriter'
+import { PayloadInstaller } from './PayloadInstaller'
+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()
+
+  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 survey = engine.surveyor.survey(await this.readEntries(engine), 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) }
+  }
+
+  /**
+   * 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()
+  }
+
+  /**
+   * 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)
+    const launchers = new LauncherWriter(configuration, layouts, files, log)
+
+    return {
+      configuration,
+      layout,
+      layouts,
+      catalog,
+      launchers,
+      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,
+      hostedUrl: game.mode === WEB_MODE ? engine.launchers.webUrl(game) : null,
+      installable: true,
+      unavailableReason: null,
+      unavailableDetail: null
+    }
+  }
+
+  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 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
+  }
+}
+
+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/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/CatalogDialect.ts

@@ -0,0 +1,56 @@
+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
+  /**
+   * 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,21 @@
+import type { SupportedWarpEngineVersion } from '../../../domain/models/WarpEngineVersion'
+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 today because the catalog's
+ * shape has not changed across them — and one class serving three versions is the
+ * honest way to say that, rather than three identical ones pretending otherwise.
+ */
+export function selectCatalogDialect (version: SupportedWarpEngineVersion): CatalogDialect {
+  switch (version) {
+    case '0.2':
+    case '0.3':
+    case '0.4':
+      return new SoftwareListCatalogDialect(version)
+  }
+}

src/infrastructure/engine/dialects/SoftwareListCatalogDialect.ts

@@ -0,0 +1,112 @@
+import type { SupportedWarpEngineVersion } from '../../../domain/models/WarpEngineVersion'
+import {
+  asRecord, readOptionalString, readRecord, readString, type JsonRecord
+} from '../../json/JsonRecord'
+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,
+        latestRelease: this.readLatestRelease(entry),
+        releaseCandidates: this.readCandidates(entry)
+      })
+    }
+    return found
+  }
+
+  /** A title with no name is not a title: nothing could be keyed by it. */
+  private 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')
+    }
+  }
+
+  private 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.
+   */
+  private 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
+  }
+
+  private 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,130 @@
+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>>
+}
+
+export interface StoreHttpOptions {
+  readonly userAgent: string
+  /** Seconds, as the store config states it. */
+  readonly timeout: number
+  readonly insecure: boolean
+}
+
+/**
+ * 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): Promise<HttpResponseBody> {
+    return await this.request(url, MAX_REDIRECTS, 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)
+      }
+    })
+  }
+
+  /**
+   * 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,
+    consume: (response: http.IncomingMessage) => Promise<TResult>
+  ): Promise<TResult> {
+    const response = await this.open(url)
+    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}`)
+      return await this.request(new URL(location, url).toString(), redirectsLeft - 1, consume)
+    }
+    if (status !== 200) {
+      response.resume()
+      throw new HttpStatusError(url, status)
+    }
+    return await consume(response)
+  }
+
+  private async open (url: 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 request = client.get(url, {
+        headers: { 'User-Agent': this.options.userAgent },
+        ...(secure && this.options.insecure ? { rejectUnauthorized: false } : {})
+      }, resolve)
+
+      request.setTimeout(Math.max(1, this.options.timeout) * 1000, (): void => {
+        request.destroy(new Error(`${url} timed out`))
+      })
+      request.on('error', reject)
+    })
+  }
+}
+
+/**
+ * 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,11 @@ 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
- * first so a sandbox can be driven without touching a working installation — which
- * is how this repository is tested.
+ * The roots are searched in the shell installers' own order — those homes are still
+ * valid stores — and `STORE_ROOT` comes first so a sandbox can be driven without
+ * touching a working installation, which is how this repository is tested.
  */
 export class FileSystemInstalledStoreRepository implements InstalledStoreRepository {
   public findAll (): readonly InstalledStore[] {
@@ -69,20 +69,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 {
-    for (const engine of STORE_ENGINES) {
-      const scriptPath = path.join(home, engine.scriptFileName)
     const configPath = path.join(home, CONFIG_FILE_NAME)
-      if (!fs.existsSync(scriptPath) || !fs.existsSync(configPath)) continue
-      const id = directoryName.replace(engine.homeSuffix, '')
-      return {
-        id,
-        name: this.readStoreName(configPath, id),
-        home,
-        scriptPath,
-        configPath,
-        engine: engine.id
-      }
+    if (!fs.existsSync(configPath)) return null
+    for (const engine of STORE_ENGINES) {
+      if (!directoryName.endsWith(engine.homeSuffix)) continue
+      const id = directoryName.slice(0, directoryName.length - engine.homeSuffix.length)
+      return { id, name: this.readStoreName(configPath, id), home, configPath, engine: engine.id }
     }
     return null
   }
@@ -90,9 +90,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
-   * the machine, and starting a Python process per entry to learn its name would
-   * be absurd.
+   * Read here rather than asked of the engine: the switcher lists every store on the
+   * machine, and assembling an engine per entry to learn its name would 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

@@ -1,7 +1,8 @@
 import { RegistryUnavailableError } from '../../domain/errors/RegistryUnavailableError'
 import type { RegistryStore } from '../../domain/models/RegistryStore'
 import type { StoreRegistryRepository } from '../../domain/ports/StoreRegistryRepository'
-import { asRecord, readString, type JsonRecord } from '../json/JsonRecord'
+import { asRecord, readRecord, 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`
- * points it at another site or at a local endpoint. Records missing any of the
- * three fields are dropped rather than half-used.
+ * The one address this client knows, and it is decided in three places, most specific
+ * first: a runtime `STORES_API` (for trying something out), the `warpEngine.registryUrl`
+ * field a build was packaged with (for shipping a client for another site), and finally
+ * the address of ours.
+ *
+ * A record needs a name and a catalog URL; those two make a store. The config and the
+ * repository are both optional and arrive as null when absent — a store configured by
+ * nothing but this record installs on the engine's defaults. Records missing either of
+ * the two required fields are dropped rather than half-used.
  */
 export class HttpStoreRegistryRepository implements StoreRegistryRepository {
   public readonly sourceUrl: string
 
-  public constructor (private readonly httpClient: HttpTextClient, sourceUrl?: string) {
-    const configured = process.env['STORES_API']
-    this.sourceUrl = sourceUrl ?? (configured !== undefined && configured.length > 0
-      ? configured
-      : DEFAULT_REGISTRY_URL)
+  public constructor (
+    private readonly httpClient: HttpTextClient,
+    sourceUrl?: string,
+    buildConfiguration: BuildConfiguration = new BuildConfiguration()
+  ) {
+    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,20 @@ export class HttpStoreRegistryRepository implements StoreRegistryRepository {
     return parsed
       .map((row: unknown): JsonRecord | null => asRecord(row))
       .filter((row: JsonRecord | null): row is JsonRecord => row !== null)
-      .map((row: JsonRecord): RegistryStore => ({
-        name: readString(row, 'name').trim(),
+      .map((row: JsonRecord): RegistryStore => {
         // Both spellings, because a registry is someone else's API: ours answers
         // camelCase, and a hand-rolled one may not.
-        catalogUrl: (readString(row, 'catalogUrl') || readString(row, 'catalog_url')).trim(),
-        storeRepositoryUrl: (
+        const repository = (
           readString(row, 'storeRepositoryUrl') || readString(row, 'store_repository_url')
         ).trim()
-      }))
+        return {
+          name: readString(row, 'name').trim(),
+          catalogUrl: (readString(row, 'catalogUrl') || readString(row, 'catalog_url')).trim(),
+          storeRepositoryUrl: repository.length > 0 ? repository : null,
+          config: readRecord(row, 'config')
+        }
+      })
       .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,160 @@
+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 DEFAULT_FORGE_BASE = 'https://git.teletypegames.org'
+const DEFAULT_BRANCH = 'master'
+
+/** 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.
+ *
+ * Since the engine moved into this application there is nothing to download but the
+ * store's own configuration, so an install is one HTTP call and one file. The store
+ * home stays where it was and keeps its name, because the state and the catalog cache
+ * beside that config are what make an existing library recognisable.
+ */
+export class NativeStoreEngineInstaller 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 })
+
+    const config = await this.readStoreConfig(store, progress)
+    const configPath = path.join(home, CONFIG_FILE_NAME)
+    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`)
+    this.removeRetiredEngine(home, progress)
+
+    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,
+      configPath,
+      engine: DESKTOP_STORE_ENGINE.id
+    }
+  }
+
+  /**
+   * Clear out the scripts an older client downloaded here.
+   *
+   * A store home provisioned by 1.5.0 or by the 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}`)
+    }
+  }
+
+  /**
+   * The store's configuration.
+   *
+   * Four cases, and all of them install:
+   *
+   *   - **a config on the registry record** — the authority on how the store behaves:
+   *     which platforms it offers, which statuses it shows, where things land. No
+   *     request at all, because it arrived with the store list;
+   *   - **a repository with a config.json** — the same thing in its older home, read
+   *     for a registry whose stores have not moved over yet;
+   *   - **a repository without one** (404) — the engine's defaults, as below;
+   *   - **neither** — the same defaults, without the round trip.
+   *
+   * The engine's built-in defaults already cover the host-to-asset mapping, the
+   * modes, the platforms and the behaviour, so what a store actually has to supply is
+   * identity: a slug, a name and a catalog. That is exactly what a registry record
+   * carries, which is why a store needs no repository of its own. The registry always
+   * wins on those three, whatever a config file says.
+   */
+  private async readStoreConfig (
+    store: RegistryStore,
+    progress: EngineProgressListener
+  ): Promise<Record<string, unknown>> {
+    const storeId = deriveStoreId(store)
+    const config = await this.readPublishedConfig(store, storeId, progress)
+
+    const existing = asRecord(config['store']) ?? {}
+    config['store'] = {
+      ...existing,
+      id: readString(existing, 'id', storeId),
+      name: store.name,
+      base_url: store.catalogUrl
+    }
+    return config
+  }
+
+  private async readPublishedConfig (
+    store: RegistryStore,
+    storeId: string,
+    progress: EngineProgressListener
+  ): Promise<Record<string, unknown>> {
+    // The registry's own answer wins, and needs no request: a store's configuration is
+    // part of its record now rather than a file in a repository that has to exist and
+    // stay reachable.
+    if (store.config !== null) {
+      progress.onLog?.(`${store.name} is configured by the registry`)
+      return { ...store.config }
+    }
+    const repositoryUrl = store.storeRepositoryUrl
+    if (repositoryUrl === null) {
+      progress.onLog?.(`${store.name} has no store repository — using the engine defaults`)
+      return this.defaultConfig(storeId)
+    }
+    try {
+      progress.onLog?.(`reading the store config from ${repositoryUrl}`)
+      const body = await this.httpClient.readText(this.configUrl(repositoryUrl))
+      return { ...(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')
+      return this.defaultConfig(storeId)
+    }
+  }
+
+  /**
+   * What a store gets when nothing else says otherwise.
+   *
+   * Two fields, on top of the identity added by the caller. The subfolder keeps two
+   * stores on one machine out of each other's files, and it is the prune boundary, so
+   * it must 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 defaultConfig (storeId: string): Record<string, unknown> {
+    return {
+      paths: { subfolder: storeId },
+      catalog: { statuses: ['released', 'archived', 'demo'] }
+    }
+  }
+
+  private configUrl (repositoryUrl: string, branch: string = DEFAULT_BRANCH): string {
+    return `${repositoryUrl.replace(/\/+$/, '')}/raw/branch/${branch}/${CONFIG_FILE_NAME}`
+  }
+}

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

@@ -7,7 +7,7 @@ const WINDOW_OPTIONS: BrowserWindowConstructorOptions = {
   minWidth: 760,
   minHeight: 520,
   backgroundColor: '#11151c',
-  title: 'WarpEngine Store'
+  title: 'WarpEngine Client'
 }
 
 /**

src/main/composition/ServiceContainer.ts

@@ -7,14 +7,12 @@ 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 { 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 { AppIpcController } from '../ipc/AppIpcController'
 import { CatalogIpcController } from '../ipc/CatalogIpcController'
 import { IpcRouter } from '../ipc/IpcRouter'
@@ -46,22 +44,20 @@ 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 catalogGateway = new NativeStoreCatalogGateway()
     const registry = new HttpStoreRegistryRepository(httpClient)
-    const installer = new HttpStoreEngineInstaller(httpClient)
+    const installer = new NativeStoreEngineInstaller(httpClient)
     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.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 = [

src/main/diagnostics/SelfTestRunner.ts

@@ -26,6 +26,8 @@ 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[]
 }
 
 /** What changed after clicking a store that was not open. */
@@ -65,10 +67,17 @@ 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.
+    // Both footer icons must be present, named and drawn: refresh and the language
+    // picker are the only way to reach those two actions now that neither has a label.
+    const iconsNamed = report.iconControls.length === 2 &&
+      report.iconControls.every((control: string): boolean => /^.+:1$/.test(control))
+    const rendered = report.locales.length > 1 && iconsNamed && (
       (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)
@@ -95,7 +104,15 @@ 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.
+      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 +131,8 @@ 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')
     }
   }
 

src/main/ipc/IpcArguments.ts

@@ -27,14 +27,16 @@ export function requireStringArray (value: unknown, name: string): readonly stri
 export function requireRegistryStore (value: unknown): RegistryStoreDto {
   const record = asRecord(value)
   if (record === null) throw new TypeError('a store record is required')
+  const repository = readString(record, 'storeRepositoryUrl')
   const store: RegistryStoreDto = {
     name: readString(record, 'name'),
     catalogUrl: readString(record, 'catalogUrl'),
-    storeRepositoryUrl: readString(record, 'storeRepositoryUrl'),
+    // Optional: a store with no repository installs on the engine's defaults.
+    storeRepositoryUrl: repository.length > 0 ? repository : null,
     storeId: readString(record, 'storeId')
   }
-  if (store.name.length === 0 || store.catalogUrl.length === 0 || store.storeRepositoryUrl.length === 0) {
-    throw new TypeError('a store record needs a name, a catalog URL and a repository URL')
+  if (store.name.length === 0 || store.catalogUrl.length === 0) {
+    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 engineMapper: EngineVersionDtoMapper = new EngineVersionDtoMapper()
+    private readonly storeMapper: InstalledStoreDtoMapper = new InstalledStoreDtoMapper()
   ) {}
 
   public register (router: IpcRouter): void {
@@ -63,11 +61,6 @@ export class StoreIpcController {
   }
 
   private handleSelectStore (home: string): StoreSelectionDto {
-    const store = this.selection.selectStore(home)
-    const engine = this.selection.findEngineVersion(store)
-    return {
-      store: this.storeMapper.toDto(store),
-      engine: engine === null ? null : this.engineMapper.toDto(engine)
-    }
+    return { store: this.storeMapper.toDto(this.selection.selectStore(home)) }
   }
 }

src/renderer/RendererApplication.ts

@@ -41,7 +41,7 @@ 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)
 
@@ -56,7 +56,6 @@ export class RendererApplication {
     this.sideMenu = new SideMenuView({
       onSelectStore: (home: string): void => { void this.stores.selectStore(home) },
       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) }
@@ -71,19 +70,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.stores.showOutdatedEngineGate()
-      return
-    }
-    this.gate.hide()
+    this.store.applyGate(null)
     await this.catalog.refresh()
   }
 
@@ -100,7 +91,15 @@ export class RendererApplication {
     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()
+    }
   }
 }

src/renderer/controllers/StoreController.ts

@@ -1,7 +1,6 @@
 import type { BridgeApi } from '../../shared/contracts/BridgeApi'
 import type { RegistryStoreDto } from '../../shared/contracts/dto/RegistryStoreDto'
 import type { AppStore } from '../state/AppStore'
-import type { GateView } from '../views/GateView'
 import type { LogDrawerView } from '../views/LogDrawerView'
 import type { CatalogController } from './CatalogController'
 
@@ -16,7 +15,6 @@ export class StoreController {
   public constructor (
     private readonly bridge: BridgeApi,
     private readonly store: AppStore,
-    private readonly gate: GateView,
     private readonly log: LogDrawerView,
     private readonly catalog: CatalogController
   ) {}
@@ -26,12 +24,8 @@ export class StoreController {
     const messages = this.store.readState().messages
     try {
       const selection = await this.bridge.selectStore(home)
-      this.store.applySelectedStore(selection.store, selection.engine)
-      if (selection.engine !== null && !selection.engine.supported) {
-        this.showOutdatedEngineGate()
-        return
-      }
-      this.gate.hide()
+      this.store.applySelectedStore(selection.store)
+      this.store.applyGate(null)
       await this.catalog.refresh()
     } catch (error: unknown) {
       this.log.appendLine(`${messages.switchFailed}: ${error instanceof Error ? error.message : String(error)}`)
@@ -48,23 +42,23 @@ export class StoreController {
     const result = await this.bridge.listRegistryStores()
 
     if (result.error !== null) {
-      this.gate.show({
+      this.store.applyGate({
         title: messages.registryFailed,
         body: `${result.sourceUrl}\n\n${result.error}`,
         action: { label: messages.registryRetry, perform: (): void => { void this.offerStores() } }
-      }, messages)
+      })
       return
     }
 
     if (result.stores.length === 0) {
-      this.gate.show({
+      this.store.applyGate({
         title: messages.setupTitle,
         body: `${messages.registryEmpty}\n\n${result.sourceUrl}`
-      }, messages)
+      })
       return
     }
 
-    this.gate.show({
+    this.store.applyGate({
       title: messages.setupTitle,
       body: `${messages.setupBody}\n\n${state.defaultStoreRoot}`,
       action: {
@@ -74,26 +68,7 @@ export class StoreController {
         }
       },
       choices: result.stores
-    }, messages)
-  }
-
-  public showOutdatedEngineGate (): void {
-    const state = this.store.readState()
-    const engineText = state.engine === null ? '' : state.engine.text
-    this.gate.show({
-      title: state.messages.oldEngineTitle,
-      body: `${state.messages.oldEngineBody}\n\n${engineText} → ${state.minimumEngineVersion}`,
-      action: { label: state.messages.oldEngineAction, perform: (): void => { void this.offerStores() } }
-    }, state.messages)
-  }
-
-  public showMissingPythonGate (): void {
-    const messages = this.store.readState().messages
-    this.gate.show({
-      title: messages.noPythonTitle,
-      body: messages.noPythonBody,
-      link: { label: messages.pythonLink, url: 'https://www.python.org/downloads/' }
-    }, messages)
+    })
   }
 
   private async installStore (chosen: RegistryStoreDto): Promise<void> {
@@ -102,7 +77,7 @@ export class StoreController {
     try {
       await this.bridge.installStore(chosen)
       this.store.applyAppState(await this.bridge.readState())
-      this.gate.hide()
+      this.store.applyGate(null)
       await this.catalog.refresh()
       await this.catalog.syncGames([])
     } catch (error: unknown) {

src/renderer/index.html

@@ -6,7 +6,7 @@
        runs: the app ships its own script and stylesheet. -->
   <meta http-equiv="Content-Security-Policy"
         content="default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' https: data:; font-src 'self'; connect-src 'none'">
-  <title>WarpEngine Store</title>
+  <title>WarpEngine Client</title>
   <link rel="stylesheet" href="style.css">
 </head>
 <body>
@@ -16,8 +16,10 @@
     </button>
     <div class="bar-title">
       <span class="logo" aria-hidden="true">▚</span>
-      <span id="app-name">WarpEngine Store</span>
-      <span class="store-id" id="store-id"></span>
+      <span id="app-name">WarpEngine Client</span>
+      <!-- Kept for the window check, which reads it to see which store is open; the
+           side menu is where a person reads that. -->
+      <span class="store-id" id="store-id" hidden></span>
     </div>
     <div class="bar-actions">
       <span class="progress" id="progress" hidden></span>
@@ -34,22 +36,40 @@
         <button id="add-store" class="btn btn-ghost btn-wide"></button>
       </section>
 
-      <section class="side-block">
-        <h2 class="side-head" id="head-actions"></h2>
-        <button id="sync-all" class="btn btn-primary btn-wide" disabled></button>
-        <button id="refresh" class="btn btn-wide" disabled></button>
-      </section>
-
       <section class="side-block side-cats">
         <h2 class="side-head" id="head-cats"></h2>
         <nav class="cats" id="cats"></nav>
       </section>
 
       <section class="side-block side-foot">
-        <label class="side-lang">
-          <span id="head-lang"></span>
-          <select id="locale" class="select" aria-label="Language"></select>
+        <button id="log-toggle" class="side-quiet" aria-expanded="false" aria-controls="log-panel"></button>
+        <!--
+          Two icons and nothing else. Both carry their name in `title` and `aria-label`,
+          set from the message bundle, so the tooltip and the screen reader stay
+          translated while the button stays the size of its glyph.
+        -->
+        <div class="side-tools">
+          <button id="refresh" class="icon-btn" disabled>
+            <svg class="icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false">
+              <path d="M13.5 8a5.5 5.5 0 1 1-1.61-3.89" />
+              <path d="M13.5 2v3h-3" />
+            </svg>
+          </button>
+          <!--
+            The select is still a real `<select>`, stretched over the icon and invisible:
+            the native dropdown knows how to open upward in a cramped window and is
+            already keyboard- and screen-reader-navigable, which a hand-rolled menu would
+            have to earn back.
+          -->
+          <label class="icon-btn side-lang" id="locale-control">
+            <svg class="icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false">
+              <circle cx="8" cy="8" r="6" />
+              <path d="M2 8h12" />
+              <path d="M8 2c1.8 1.6 2.8 3.8 2.8 6S9.8 12.4 8 14C6.2 12.4 5.2 10.2 5.2 8S6.2 3.6 8 2Z" />
+            </svg>
+            <select id="locale" class="locale-select"></select>
           </label>
+        </div>
       </section>
     </aside>
 
@@ -72,11 +92,11 @@
 
       <section id="empty" class="empty" hidden></section>
 
-      <footer class="log">
-        <button id="log-toggle" class="log-toggle" aria-expanded="false"></button>
-        <div class="log-lines" id="log-lines" hidden></div>
+      <!-- Only on screen while the log is open; the window has no permanent footer. -->
+      <section class="log-panel" id="log-panel" hidden>
+        <div class="log-lines" id="log-lines"></div>
         <div class="log-paths" id="log-paths"></div>
-      </footer>
+      </section>
     </div>
   </div>
 

src/renderer/state/AppStore.ts

@@ -1,11 +1,11 @@
 import type { AppStateDto } from '../../shared/contracts/dto/AppStateDto'
-import type { EngineVersionDto } from '../../shared/contracts/dto/EngineVersionDto'
 import type { GameDto } from '../../shared/contracts/dto/GameDto'
 import type { InstalledStoreDto } from '../../shared/contracts/dto/InstalledStoreDto'
 import type { StorePathsDto } from '../../shared/contracts/dto/StorePathsDto'
 import { ENGLISH_MESSAGES } from '../../shared/i18n/EnglishMessages'
 import type { Locale, MessageBundle } from '../../shared/i18n/MessageBundle'
 import { ALL_CATEGORIES, type CategoryFilter } from './CategoryFilter'
+import type { GatePresentation } from './GatePresentation'
 
 /** How far a running sync has got, for the counter in the bar. */
 export interface SyncProgress {
@@ -20,11 +20,8 @@ export interface AppState {
   readonly locales: readonly Locale[]
   readonly messages: MessageBundle
   readonly navigationOpen: boolean
-  readonly pythonVersion: string | null
   readonly stores: readonly InstalledStoreDto[]
   readonly currentStore: InstalledStoreDto | null
-  readonly engine: EngineVersionDto | null
-  readonly minimumEngineVersion: string
   readonly registryUrl: string
   readonly defaultStoreRoot: string
   readonly games: readonly GameDto[]
@@ -32,6 +29,8 @@ export interface AppState {
   readonly filter: CategoryFilter
   readonly busy: boolean
   readonly progress: SyncProgress | null
+  /** Non-null while the setup screen is up, which is also what hides the grid. */
+  readonly gate: GatePresentation | null
 }
 
 const INITIAL_STATE: AppState = {
@@ -39,18 +38,16 @@ const INITIAL_STATE: AppState = {
   locales: ['en'],
   messages: ENGLISH_MESSAGES,
   navigationOpen: true,
-  pythonVersion: null,
   stores: [],
   currentStore: null,
-  engine: null,
-  minimumEngineVersion: '',
   registryUrl: '',
   defaultStoreRoot: '',
   games: [],
   paths: null,
   filter: ALL_CATEGORIES,
   busy: false,
-  progress: null
+  progress: null,
+  gate: null
 }
 
 export type AppStateListener = (state: AppState) => void
@@ -81,11 +78,8 @@ export class AppStore {
       locales: dto.locales,
       messages: dto.messages,
       navigationOpen: dto.navigationOpen,
-      pythonVersion: dto.pythonVersion,
       stores: dto.stores,
       currentStore: dto.currentStore,
-      engine: dto.engine,
-      minimumEngineVersion: dto.minimumEngineVersion,
       registryUrl: dto.registryUrl,
       defaultStoreRoot: dto.defaultStoreRoot
     }
@@ -107,8 +101,13 @@ export class AppStore {
     this.notify()
   }
 
-  public applySelectedStore (store: InstalledStoreDto, engine: EngineVersionDto | null): void {
-    this.state = { ...this.state, currentStore: store, engine, games: [], paths: null, filter: ALL_CATEGORIES }
+  public applySelectedStore (store: InstalledStoreDto): void {
+    this.state = { ...this.state, currentStore: store, games: [], paths: null, filter: ALL_CATEGORIES }
+    this.notify()
+  }
+
+  public applyGate (gate: GatePresentation | null): void {
+    this.state = { ...this.state, gate }
     this.notify()
   }
 

src/renderer/state/CategoryFilter.ts

@@ -30,7 +30,9 @@ export function matchesFilter (game: GameDto, filter: CategoryFilter): boolean {
     case 'platform':
       return game.platform === filter.value
     case 'mode':
-      return game.mode === filter.value
+      // A title this machine cannot install has no mode worth filtering on: the engine
+      // sends none, and counting it as native would put a C64 cartridge under "native".
+      return game.installable && game.mode === filter.value
     case 'group':
       return matchesGroup(game, filter.value)
   }
@@ -43,7 +45,9 @@ function matchesGroup (game: GameDto, group: string): boolean {
     case 'updates':
       return game.updateAvailable
     case 'available':
-      return !game.installed
+      return game.installable && !game.installed
+    case 'unsupported':
+      return !game.installable
     default:
       return true
   }
@@ -68,7 +72,8 @@ export function buildCategorySections (
     { kind: 'group', value: 'all', label: messages.catAll, count: games.length },
     { kind: 'group', value: 'installed', label: messages.catInstalled, count: count((game: GameDto): boolean => game.installed) },
     { kind: 'group', value: 'updates', label: messages.catUpdates, count: count((game: GameDto): boolean => game.updateAvailable) },
-    { kind: 'group', value: 'available', label: messages.catAvailable, count: count((game: GameDto): boolean => !game.installed) }
+    { kind: 'group', value: 'available', label: messages.catAvailable, count: count((game: GameDto): boolean => game.installable && !game.installed) },
+    { kind: 'group', value: 'unsupported', label: messages.catUnsupported, count: count((game: GameDto): boolean => !game.installable) }
   ]
   sections.push({
     title: null,
@@ -90,7 +95,8 @@ export function buildCategorySections (
     })
   }
 
-  const modes = [...new Set(games.map((game: GameDto): string => game.mode))]
+  const installable = games.filter((game: GameDto): boolean => game.installable)
+  const modes = [...new Set(installable.map((game: GameDto): string => game.mode))]
   if (modes.length > 1) {
     sections.push({
       title: messages.catMode,
@@ -98,7 +104,7 @@ export function buildCategorySections (
         kind: 'mode',
         value: mode,
         label: mode === 'web' ? messages.hosted : messages.native,
-        count: count((game: GameDto): boolean => game.mode === mode)
+        count: count((game: GameDto): boolean => game.installable && game.mode === mode)
       }))
     })
   }

src/renderer/state/GatePresentation.ts

@@ -0,0 +1,27 @@
+import type { RegistryStoreDto } from '../../shared/contracts/dto/RegistryStoreDto'
+
+/** A button on the gate, and what choosing it does. */
+export interface GateAction {
+  readonly label: string
+  readonly perform: (chosen: RegistryStoreDto | null) => void
+}
+
+export interface GateLink {
+  readonly label: string
+  readonly url: string
+}
+
+/**
+ * What the gate is showing.
+ *
+ * Part of the state rather than a call on a view: whether the gate is up decides
+ * whether the grid is drawn, and the two disagreed when this was imperative — the
+ * gate went up and the empty-catalog line stayed underneath it.
+ */
+export interface GatePresentation {
+  readonly title: string
+  readonly body: string
+  readonly action?: GateAction
+  readonly link?: GateLink
+  readonly choices?: readonly RegistryStoreDto[]
+}

src/renderer/style.css

@@ -14,6 +14,27 @@
 
 * { box-sizing: border-box; }
 
+/* The scrollbars are part of the theme too: the platform's own are light, and a white
+   track down the side menu of a dark window looks like a mistake. */
+* {
+  scrollbar-width: thin;
+  scrollbar-color: #33414f transparent;
+}
+::-webkit-scrollbar { width: 10px; height: 10px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb {
+  background: #33414f;
+  border: 3px solid transparent;
+  border-radius: 999px;
+  background-clip: content-box;
+}
+::-webkit-scrollbar-thumb:hover { background: #46586b; background-clip: content-box; }
+
+/* An explicit `display` beats the browser's own [hidden] rule, and most of the
+   regions here have one — the gate's store picker showed as an empty stub because
+   of exactly that. This makes `hidden` mean hidden everywhere. */
+[hidden] { display: none !important; }
+
 body {
   margin: 0;
   background: var(--bg);
@@ -60,7 +81,15 @@ body.nav-closed .side { margin-left: calc(-1 * var(--side-width)); }
 
 .side-block { display: flex; flex-direction: column; gap: 6px; flex: none; }
 .side-cats { flex: 1; min-height: 0; }
-.side-foot { padding-top: 12px; border-top: 1px solid var(--line); }
+.side-foot {
+  padding-top: 12px;
+  border-top: 1px solid var(--line);
+  gap: 8px;
+  flex-direction: row;
+  align-items: center;
+}
+/* The icons sit at the end of the footer row, away from the log toggle. */
+.side-tools { display: flex; align-items: center; gap: 4px; margin-left: auto; }
 .side-head {
   font-size: 11px;
   font-weight: 700;
@@ -142,8 +171,51 @@ body.nav-closed .side { margin-left: calc(-1 * var(--side-width)); }
   padding: 8px 10px 2px;
 }
 
-.side-lang { display: flex; align-items: center; gap: 8px; font-size: 12px; color: var(--ink-dim); }
-.side-lang .select { margin-left: auto; }
+/*
+ * An icon-only control: a square the size of its glyph, quiet until pointed at.
+ * `position: relative` is what lets the language picker put its <select> on top.
+ */
+.icon-btn {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  background: transparent;
+  color: var(--ink-dim);
+  cursor: pointer;
+}
+.icon-btn:hover:not(:disabled) { color: var(--ink); background: var(--panel-2); border-color: var(--line); }
+.icon-btn:active:not(:disabled) { transform: scale(.94); }
+.icon-btn:disabled { opacity: .4; cursor: default; }
+/* The select swallows focus, so the ring has to be drawn on the label around it. */
+.icon-btn:focus-visible,
+.icon-btn:focus-within { color: var(--ink); border-color: var(--accent); outline: none; }
+
+.icon { width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 1.5;
+  stroke-linecap: round; stroke-linejoin: round; }
+
+/*
+ * The real <select>, stretched over the icon and invisible. It keeps the native
+ * dropdown — and its keyboard and screen-reader behaviour — while only the glyph shows.
+ */
+.locale-select {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  opacity: 0;
+  cursor: pointer;
+  appearance: none;
+  font: inherit;
+}
 
 /* --- top bar ------------------------------------------------------------ */
 .bar {
@@ -198,7 +270,7 @@ body.nav-closed .side { margin-left: calc(-1 * var(--side-width)); }
 }
 .link { color: var(--accent); cursor: pointer; text-decoration: underline; }
 
-/* --- gate (no python, or no store yet) ---------------------------------- */
+/* --- gate (no store yet) ---------------------------------- */
 .gate {
   margin: auto;
   max-width: 520px;
@@ -239,6 +311,12 @@ body.nav-closed .side { margin-left: calc(-1 * var(--side-width)); }
   flex-direction: column;
 }
 .card.is-installed { border-color: #2f5a49; }
+/* Listed, but not for this machine: dimmed rather than hidden, and it says why. */
+.card.is-unavailable { opacity: .55; }
+.card.is-unavailable:hover { opacity: .8; }
+.card.is-unavailable .art { filter: grayscale(1); }
+.badge-unavailable { color: var(--ink-dim); border-color: var(--line); border-style: dashed; }
+.actions-note { font-size: 12px; color: var(--ink-dim); margin-top: auto; }
 
 .art {
   /* One height for every card, art or not, so the titles and the buttons line up
@@ -279,23 +357,29 @@ body.nav-closed .side { margin-left: calc(-1 * var(--side-width)); }
 }
 .actions { display: flex; gap: 8px; margin-top: auto; }
 
-/* --- log ---------------------------------------------------------------- */
-.log {
+/* --- log ----------------------------------------------------------------
+   No permanent footer: the panel is in the flow only while it is open, and the
+   switch for it sits in the side menu with everything else that is not a title. */
+.log-panel {
   flex: none;
   background: var(--panel);
   border-top: 1px solid var(--line);
   padding: 8px 18px 10px;
 }
-.log-toggle {
+.side-quiet {
   font: inherit;
   font-size: 12px;
-  font-weight: 600;
   color: var(--ink-dim);
   background: none;
   border: 0;
-  padding: 0 0 4px;
+  border-radius: 6px;
+  padding: 4px 6px;
+  margin-left: -6px;
+  text-align: left;
   cursor: pointer;
 }
+.side-quiet:hover { color: var(--ink); background: var(--panel-2); }
+.side-quiet.is-active { color: var(--accent); }
 .log-lines {
   max-height: 150px;
   overflow-y: auto;

src/renderer/views/GameCardView.ts

@@ -20,6 +20,7 @@ export class GameCardView {
   public createCard (game: GameDto, messages: MessageBundle, busy: boolean): HTMLElement {
     const card = createElement('article', 'card')
     if (game.installed) card.classList.add('is-installed')
+    if (!game.installable) card.classList.add('is-unavailable')
     card.appendChild(this.createArt(game))
     card.appendChild(this.createBody(game, messages, busy))
     return card
@@ -54,10 +55,21 @@ export class GameCardView {
 
   private createMeta (game: GameDto, messages: MessageBundle): HTMLElement {
     const meta = createElement('div', 'meta')
+    if (game.installable) {
       const mode = createElement('span', `badge badge-${game.mode}`,
         game.mode === 'web' ? messages.hosted : messages.native)
       mode.title = game.mode === 'web' ? messages.hostedHint : messages.nativeHint
       meta.appendChild(mode)
+    } else {
+      // Which of the two it is matters: a platform this store does not carry is a
+      // different disappointment from a game with no build for your machine.
+      const label = game.unavailableReason === 'platformOff'
+        ? messages.unsupportedPlatform
+        : messages.unsupportedBuild
+      const badge = createElement('span', 'badge badge-unavailable', label)
+      badge.title = game.unavailableDetail ?? label
+      meta.appendChild(badge)
+    }
     meta.appendChild(createElement('span', 'badge badge-plain', game.platform))
     meta.appendChild(createElement('span', 'version',
       game.installed && game.installedVersion !== null
@@ -68,6 +80,15 @@ export class GameCardView {
 
   private createActions (game: GameDto, messages: MessageBundle, busy: boolean): HTMLElement {
     const actions = createElement('div', 'actions')
+
+    // Nothing to offer, so nothing to press: a disabled Install would invite a click
+    // that can never work. The badge above says why.
+    if (!game.installable) {
+      actions.appendChild(createElement('span', 'actions-note',
+        game.unavailableDetail ?? messages.unsupportedPlatform))
+      return actions
+    }
+
     const primary = createElement('button', 'btn btn-primary')
     primary.disabled = busy
 

src/renderer/views/GateView.ts

@@ -1,25 +1,7 @@
 import type { RegistryStoreDto } from '../../shared/contracts/dto/RegistryStoreDto'
 import { createElement, requireElement, setHidden, setText } from '../dom/Dom'
 import type { MessageBundle } from '../../shared/i18n/MessageBundle'
-
-/** A button on the gate, and what choosing it does. */
-export interface GateAction {
-  readonly label: string
-  readonly perform: (chosen: RegistryStoreDto | null) => void
-}
-
-export interface GateLink {
-  readonly label: string
-  readonly url: string
-}
-
-export interface GatePresentation {
-  readonly title: string
-  readonly body: string
-  readonly action?: GateAction
-  readonly link?: GateLink
-  readonly choices?: readonly RegistryStoreDto[]
-}
+import type { GateLink, GatePresentation } from '../state/GatePresentation'
 
 /**
  * The screen shown instead of the grid when there is nothing to drive: no Python, no
@@ -50,10 +32,6 @@ export class GateView {
     setHidden(this.section, true)
   }
 
-  public get visible (): boolean {
-    return !this.section.hidden
-  }
-
   /** Only shown when the registry offers more than one store; with a single one there is nothing to decide. */
   private renderChoices (choices: readonly RegistryStoreDto[], messages: MessageBundle): void {
     setHidden(this.choice, choices.length < 2)

src/renderer/views/LogDrawerView.ts

@@ -1,4 +1,4 @@
-import { createElement, requireElement, setText } from '../dom/Dom'
+import { createElement, requireElement, setHidden, setText } from '../dom/Dom'
 import type { AppState } from '../state/AppStore'
 
 const MAX_LOG_LINES = 400
@@ -7,17 +7,23 @@ export interface LogDrawerViewCallbacks {
   readonly onOpenFolder: (directory: string) => void
 }
 
-/** The store's own output, verbatim, and the folders everything lands in. */
+/**
+ * The store's own output, verbatim, and the folders everything lands in.
+ *
+ * Off screen until asked for. The window used to carry a footer with a toggle and a
+ * line of absolute paths at all times; both were clutter next to the one thing the
+ * window is for, which is the titles. The switch lives in the side menu with the rest
+ * of what is not a title, and the panel appears above the grid only while it is on.
+ */
 export class LogDrawerView {
   private readonly toggle = requireElement('log-toggle', HTMLButtonElement)
+  private readonly panel = requireElement('log-panel', HTMLElement)
   private readonly lines = requireElement('log-lines', HTMLElement)
   private readonly pathsBox = requireElement('log-paths', HTMLElement)
+  private open = false
 
   public constructor (private readonly callbacks: LogDrawerViewCallbacks) {
-    this.toggle.addEventListener('click', (): void => {
-      this.lines.hidden = !this.lines.hidden
-      this.toggle.setAttribute('aria-expanded', String(!this.lines.hidden))
-    })
+    this.toggle.addEventListener('click', (): void => { this.setOpen(!this.open) })
   }
 
   public render (state: AppState): void {
@@ -40,6 +46,19 @@ export class LogDrawerView {
     }
   }
 
+  private setOpen (open: boolean): void {
+    this.open = open
+    setHidden(this.panel, !open)
+    this.toggle.setAttribute('aria-expanded', String(open))
+    this.toggle.classList.toggle('is-active', open)
+    if (open) this.lines.scrollTop = this.lines.scrollHeight
+  }
+
+  /**
+   * A line arriving while the panel is shut does not open it: the store logs on every
+   * refresh, and a window that unfolded a panel by itself would be worse than one that
+   * kept quiet. The lines are kept, so opening it later shows what happened.
+   */
   public appendLine (line: string): void {
     this.lines.appendChild(createElement('div', 'log-line', line))
     while (this.lines.childElementCount > MAX_LOG_LINES) {

src/renderer/views/SideMenuView.ts

@@ -9,7 +9,6 @@ import type { AppState } from '../state/AppStore'
 export interface SideMenuViewCallbacks {
   readonly onSelectStore: (home: string) => void
   readonly onAddStore: () => void
-  readonly onSyncAll: () => void
   readonly onRefresh: () => void
   readonly onSelectCategory: (filter: CategoryFilter) => void
   readonly onSelectLocale: (locale: string) => void
@@ -22,31 +21,32 @@ export interface SideMenuViewCallbacks {
  */
 export class SideMenuView {
   private readonly storesHead = requireElement('head-stores', HTMLElement)
-  private readonly actionsHead = requireElement('head-actions', HTMLElement)
   private readonly categoriesHead = requireElement('head-cats', HTMLElement)
-  private readonly languageHead = requireElement('head-lang', HTMLElement)
   private readonly storeList = requireElement('store-list', HTMLElement)
   private readonly addStore = requireElement('add-store', HTMLButtonElement)
-  private readonly syncAll = requireElement('sync-all', HTMLButtonElement)
   private readonly refresh = requireElement('refresh', HTMLButtonElement)
   private readonly categories = requireElement('cats', HTMLElement)
   private readonly locale = requireElement('locale', HTMLSelectElement)
+  /** The square around the select: it is what a pointer hovers, so the tooltip is its. */
+  private readonly localeControl = requireElement('locale-control', HTMLElement)
 
   public constructor (private readonly callbacks: SideMenuViewCallbacks) {
     this.addStore.addEventListener('click', callbacks.onAddStore)
-    this.syncAll.addEventListener('click', callbacks.onSyncAll)
     this.refresh.addEventListener('click', callbacks.onRefresh)
     this.locale.addEventListener('change', (): void => { callbacks.onSelectLocale(this.locale.value) })
   }
 
   public render (state: AppState): void {
     setText(this.storesHead, state.messages.stores)
-    setText(this.actionsHead, state.messages.actions)
     setText(this.categoriesHead, state.messages.categories)
-    setText(this.languageHead, state.messages.language)
     setText(this.addStore, state.messages.addStore)
-    setText(this.syncAll, state.messages.syncAll)
-    setText(this.refresh, state.messages.refresh)
+    // Refresh and the language picker are icons: naming them is all the view does, and
+    // writing text into them would replace the glyph.
+    describeControl(this.refresh, state.messages.refresh)
+    // The picker is two elements: the invisible select takes the focus and the reader's
+    // name, the square around it takes the hover and the tooltip.
+    describeControl(this.locale, state.messages.language)
+    this.localeControl.title = state.messages.language
 
     this.renderStores(state)
     this.renderCategories(state)
@@ -116,9 +116,19 @@ export class SideMenuView {
    */
   private renderEnabled (state: AppState): void {
     const hasStore = state.currentStore !== null
-    this.syncAll.disabled = state.busy || !hasStore
     this.refresh.disabled = state.busy || !hasStore
     this.addStore.disabled = state.busy
     for (const row of this.storeList.querySelectorAll('button')) row.disabled = state.busy
   }
 }
+
+/**
+ * Name an icon-only control.
+ *
+ * `title` is the tooltip a mouse finds and `aria-label` is what a screen reader reads;
+ * an icon button needs both, and they are the same sentence.
+ */
+function describeControl (element: HTMLElement, name: string): void {
+  element.title = name
+  element.setAttribute('aria-label', name)
+}

src/renderer/views/TopBarView.ts

@@ -18,6 +18,9 @@ export class TopBarView {
 
   public render (state: AppState): void {
     setText(this.appName, state.messages.appName)
+    // The bar names the app, not the store: which store is open is what the switcher in
+    // the side menu says, and saying it twice made the title read like a breadcrumb. The
+    // element stays in the page, hidden, because the window check reads it.
     setText(this.storeId, state.currentStore === null ? '' : state.currentStore.id)
     this.navToggle.title = state.messages.menu
     this.navToggle.setAttribute('aria-label', state.messages.menu)

src/scripts/SmokeTest.ts

@@ -6,12 +6,10 @@ 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 { 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 { HttpStoreRegistryRepository } from '../infrastructure/repositories/HttpStoreRegistryRepository'
-import { PythonStoreCatalogGateway } from '../infrastructure/repositories/PythonStoreCatalogGateway'
 import type { GameDto } from '../shared/contracts/dto/GameDto'
 import { ENGLISH_MESSAGES } from '../shared/i18n/EnglishMessages'
 import { HUNGARIAN_MESSAGES } from '../shared/i18n/HungarianMessages'
@@ -20,6 +18,9 @@ import { LOCALES } from '../shared/i18n/MessageBundle'
 /**
  * Drives the store with no window and no Electron at all.
  *
+ * Since the engine is part of this application, this exercises the real thing rather
+ * than a child process: a bad release choice or a broken menu entry fails here.
+ *
  * This is the second composition root, and the reason the layers are worth having:
  * the same services the window uses are assembled here against the same ports, so an
  * integration mistake shows up in a terminal rather than in a screenshot.
@@ -31,18 +32,14 @@ class SmokeTest {
   private failed = false
 
   private readonly stores = new FileSystemInstalledStoreRepository()
-  private readonly pythonLocator = new SystemPythonRuntimeLocator()
-  private readonly catalogGateway = new PythonStoreCatalogGateway(
-    new PythonEngineProcessRunner(this.pythonLocator)
-  )
+  private readonly catalogGateway = new NativeStoreCatalogGateway()
   private readonly httpClient = new HttpTextClient()
   private readonly registry = new HttpStoreRegistryRepository(this.httpClient)
   private readonly gameMapper = new GameDtoMapper()
 
   public async run (): Promise<number> {
-    console.log('warp-engine-desktop-gui smoke test')
+    console.log('warp-engine-client smoke test')
 
-    if (!this.checkPython()) return 1
     this.checkMessages()
     await this.checkRegistry()
 
@@ -53,16 +50,6 @@ class SmokeTest {
     return this.failed ? 1 : 0
   }
 
-  private checkPython (): boolean {
-    const runtime = this.pythonLocator.findRuntime()
-    if (runtime === null) {
-      this.reportBad('python', 'not found — the store cannot run')
-      return false
-    }
-    this.reportOk('python', runtime.version)
-    return true
-  }
-
   /** The bundles are typed against one key set, so this only counts them. */
   private checkMessages (): void {
     const english = Object.keys(ENGLISH_MESSAGES).length
@@ -89,20 +76,43 @@ class SmokeTest {
   }
 
   /**
-   * A store repository without a config.json still installs — the engine merges what
-   * it is given onto its defaults — so an absent file is reported, not failed.
+   * Where this store's configuration would come from, in the order the installer asks.
+   *
+   * A store needs no config and no repository: either way the engine's defaults carry
+   * it, so every absence here is reported rather than failed. What is worth seeing is
+   * *which* source answered — a store still being configured by a repository is a store
+   * that has not moved over to the registry yet.
    */
   private async checkStoreConfig (store: RegistryStore): Promise<void> {
+    if (store.config !== null) {
+      const subfolder = this.readSubfolder(store.config)
+      this.reportOk('  config', `${String(Object.keys(store.config).length)} sections ` +
+        `from the registry${subfolder === null ? '' : `, subfolder ${subfolder}`}`)
+      return
+    }
+    if (store.storeRepositoryUrl === null) {
+      this.reportOk('  config', 'none, and no repository — the engine defaults would be used')
+      return
+    }
     const url = `${store.storeRepositoryUrl.replace(/\/+$/, '')}/raw/branch/master/config.json`
     try {
       const config: unknown = JSON.parse(await this.httpClient.readText(url))
       const sections = typeof config === 'object' && config !== null ? Object.keys(config).length : 0
-      this.reportOk('  config.json', `${String(sections)} sections`)
+      this.reportOk('  config.json', `${String(sections)} sections from the repository ` +
+        '(not yet moved to the registry)')
     } catch (error: unknown) {
       this.reportOk('  config.json', `absent (${this.describe(error)}) — defaults would be used`)
     }
   }
 
+  /** The prune boundary, which is the field worth seeing at a glance. */
+  private readSubfolder (config: Readonly<Record<string, unknown>>): string | null {
+    const paths = config['paths']
+    if (typeof paths !== 'object' || paths === null) return null
+    const subfolder = (paths as Readonly<Record<string, unknown>>)['subfolder']
+    return typeof subfolder === 'string' ? subfolder : null
+  }
+
   private findStore (): InstalledStore | null {
     const sandbox = process.env['SMOKE_HOME']
     if (sandbox !== undefined && sandbox.length > 0) {
@@ -111,16 +121,13 @@ class SmokeTest {
         id: path.basename(home).replace(DESKTOP_STORE_ENGINE.homeSuffix, ''),
         name: path.basename(home),
         home,
-        scriptPath: path.join(home, DESKTOP_STORE_ENGINE.scriptFileName),
         configPath: path.join(home, 'config.json'),
         engine: DESKTOP_STORE_ENGINE.id
       }
-      for (const file of [store.scriptPath, store.configPath]) {
-        if (!fs.existsSync(file)) {
-          this.reportBad('SMOKE_HOME', `${file} is missing`)
+      if (!fs.existsSync(store.configPath)) {
+        this.reportBad('SMOKE_HOME', `${store.configPath} is missing`)
         return null
       }
-      }
       this.reportOk('store (SMOKE_HOME)', store.home)
       return store
     }
@@ -139,11 +146,6 @@ class SmokeTest {
     const logLines: string[] = []
     const progress = { onLog: (line: string): void => { logLines.push(line) } }
 
-    const engine = this.catalogGateway.readEngineVersion(store)
-    if (engine === null) this.reportBad('engine', 'the store did not answer --version')
-    else if (!engine.supported) this.reportBad('engine', `${engine.text} is too old for this client`)
-    else this.reportOk('engine', engine.text)
-
     const paths = await this.catalogGateway.readPaths(store, progress)
     if (paths.operatingSystem.length > 0 && paths.storeFolder.length > 0) {
       this.reportOk('paths', `${paths.operatingSystem} → ${paths.storeFolder}`)
@@ -163,9 +165,22 @@ class SmokeTest {
   }
 
   private reportListing (games: readonly GameDto[]): void {
-    const native = games.filter((game: GameDto): boolean => game.mode === 'app').length
-    const hosted = games.length - native
-    this.reportOk('list', `${String(games.length)} titles (app:${String(native)}, web:${String(hosted)})`)
+    const installable = games.filter((game: GameDto): boolean => game.installable)
+    const native = installable.filter((game: GameDto): boolean => game.mode === 'app').length
+    const hosted = installable.length - native
+    this.reportOk('list', `${String(games.length)} titles ` +
+      `(app:${String(native)}, web:${String(hosted)}, unavailable:${String(games.length - installable.length)})`)
+
+    // The listing is supposed to carry what it cannot install, with a reason on each.
+    const unavailable = games.filter((game: GameDto): boolean => !game.installable)
+    const unexplained = unavailable.filter((game: GameDto): boolean => game.unavailableReason === null)
+    if (unexplained.length > 0) this.reportBad('unavailable', `${String(unexplained.length)} have no reason`)
+    else if (unavailable.length > 0) {
+      const first = unavailable[0]
+      if (first !== undefined) {
+        this.reportOk('unavailable', `${String(unavailable.length)}, e.g. ${first.name}: ${first.unavailableReason ?? ''}`)
+      }
+    }
 
     const withoutTitle = games.filter((game: GameDto): boolean =>
       game.name.length === 0 || game.title.length === 0 || game.platform.length === 0)

src/shared/contracts/dto/AppStateDto.ts

@@ -1,6 +1,5 @@
 import type { Locale } from '../../i18n/MessageBundle'
 import type { MessageBundle } from '../../i18n/MessageBundle'
-import type { EngineVersionDto } from './EngineVersionDto'
 import type { InstalledStoreDto } from './InstalledStoreDto'
 
 /** Everything the window needs before it can paint anything. */
@@ -9,12 +8,8 @@ export interface AppStateDto {
   readonly locales: readonly Locale[]
   readonly messages: MessageBundle
   readonly navigationOpen: boolean
-  /** The Python 3 version string, or null when there is none to drive the store. */
-  readonly pythonVersion: string | null
   readonly currentStore: InstalledStoreDto | null
   readonly stores: readonly InstalledStoreDto[]
-  readonly engine: EngineVersionDto | null
-  readonly minimumEngineVersion: string
   readonly registryUrl: string
   readonly defaultStoreRoot: string
   readonly appVersion: string

src/shared/contracts/dto/EngineVersionDto.ts

@@ -1,5 +0,0 @@
-/** The installed engine's version, and whether this client can drive it. */
-export interface EngineVersionDto {
-  readonly text: string
-  readonly supported: boolean
-}

src/shared/contracts/dto/GameDto.ts

@@ -1,6 +1,9 @@
 /** How a title runs: unpacked on this machine, or served as a web build. */
 export type GameModeDto = 'app' | 'web'
 
+/** Why a title cannot be installed on this machine. */
+export type UnavailableReasonDto = 'platformOff' | 'hostAsset' | 'noAsset' | 'vetoed'
+
 /**
  * A catalog entry as the window needs it.
  *
@@ -23,4 +26,8 @@ export interface GameDto {
   readonly updateAvailable: boolean
   readonly installedVersion: string | null
   readonly launchable: boolean
+  /** False for a title this machine cannot install; it is listed all the same. */
+  readonly installable: boolean
+  readonly unavailableReason: UnavailableReasonDto | null
+  readonly unavailableDetail: string | null
 }

src/shared/contracts/dto/RegistryStoreDto.ts

@@ -2,7 +2,8 @@
 export interface RegistryStoreDto {
   readonly name: string
   readonly catalogUrl: string
-  readonly storeRepositoryUrl: string
-  /** Derived from the repository name, so the picker can show what it will become. */
+  /** Null when the store has no repository of its own; the engine's defaults are then used. */
+  readonly storeRepositoryUrl: string | null
+  /** Derived from the repository, the catalog host or the name — what the store will be called on disk. */
   readonly storeId: string
 }

src/shared/contracts/dto/StoreSelectionDto.ts

@@ -1,8 +1,6 @@
-import type { EngineVersionDto } from './EngineVersionDto'
 import type { InstalledStoreDto } from './InstalledStoreDto'
 
-/** The answer to a store switch: which store is open, and can it be driven. */
+/** The answer to a store switch: which store is now open. */
 export interface StoreSelectionDto {
   readonly store: InstalledStoreDto
-  readonly engine: EngineVersionDto | null
 }

src/shared/i18n/EnglishMessages.ts

@@ -5,8 +5,7 @@
  * translation is a compile error rather than a blank label at runtime.
  */
 export const ENGLISH_MESSAGES = {
-  appName: 'WarpEngine Store',
-  syncAll: 'Install all',
+  appName: 'WarpEngine Client',
   refresh: 'Refresh',
   install: 'Install',
   update: 'Update',
@@ -19,17 +18,19 @@ export const ENGLISH_MESSAGES = {
   hostedHint: 'Opens in your browser — needs the network',
   nativeHint: 'Installed on this machine — works offline',
   updateAvailable: 'update available',
+  unsupportedPlatform: 'unsupported platform',
+  unsupportedBuild: 'no build for this machine',
   log: 'Log',
   menu: 'Menu',
   stores: 'Stores',
   addStore: 'Add a store…',
   switchFailed: 'That store could not be opened',
-  actions: 'Actions',
   categories: 'Categories',
   catAll: 'Everything',
   catInstalled: 'Installed',
   catUpdates: 'Updates',
   catAvailable: 'Not installed',
+  catUnsupported: 'Not for this machine',
   catPlatform: 'Platform',
   catMode: 'Kind',
   language: 'Language',
@@ -43,12 +44,6 @@ export const ENGLISH_MESSAGES = {
   registryFailed: 'The list of stores could not be fetched',
   registryEmpty: 'The list of stores came back empty. Nothing to install from yet.',
   registryRetry: 'Try again',
-  oldEngineTitle: 'The store needs refreshing',
-  oldEngineBody: 'The store engine on this machine is older than this client can drive. Refreshing it downloads the current engine and keeps your settings and installed games.',
-  oldEngineAction: 'Refresh the store',
-  noPythonTitle: 'Python 3 is required',
-  noPythonBody: 'The store is a Python program, so Python 3 has to be installed. Install it, then reopen this window.',
-  pythonLink: 'python.org/downloads',
   paths: 'Where things go',
   openStoreFolder: 'Open the store folder',
   openMenuFolder: 'Open the menu folder',

src/shared/i18n/HungarianMessages.ts

@@ -5,8 +5,7 @@ import type { MessageBundle } from './MessageBundle'
  * arrives from the store as it was published.
  */
 export const HUNGARIAN_MESSAGES: MessageBundle = {
-  appName: 'WarpEngine Store',
-  syncAll: 'Mind telepítése',
+  appName: 'WarpEngine Client',
   refresh: 'Frissítés',
   install: 'Telepítés',
   update: 'Frissítés',
@@ -19,17 +18,19 @@ export const HUNGARIAN_MESSAGES: MessageBundle = {
   hostedHint: 'A böngészőben nyílik meg — internet kell hozzá',
   nativeHint: 'Erre a gépre telepítve — internet nélkül is megy',
   updateAvailable: 'frissítés elérhető',
+  unsupportedPlatform: 'nem támogatott platform',
+  unsupportedBuild: 'ehhez a géphez nincs build',
   log: 'Napló',
   menu: 'Menü',
   stores: 'Store-ok',
   addStore: 'Store hozzáadása…',
   switchFailed: 'Ez a store nem nyitható meg',
-  actions: 'Műveletek',
   categories: 'Kategóriák',
   catAll: 'Minden',
   catInstalled: 'Telepítve',
   catUpdates: 'Frissítés',
   catAvailable: 'Nincs telepítve',
+  catUnsupported: 'Erre a gépre nem',
   catPlatform: 'Platform',
   catMode: 'Fajta',
   language: 'Nyelv',
@@ -43,12 +44,6 @@ export const HUNGARIAN_MESSAGES: MessageBundle = {
   registryFailed: 'A store-ok listája nem érhető el',
   registryEmpty: 'A store-ok listája üresen jött vissza. Egyelőre nincs miből telepíteni.',
   registryRetry: 'Újra',
-  oldEngineTitle: 'A store frissítésre vár',
-  oldEngineBody: 'A gépen lévő store-motor régebbi, mint amit ez a kliens vezérelni tud. A frissítés letölti a mostani motort, a beállításaid és a telepített játékok pedig megmaradnak.',
-  oldEngineAction: 'Store frissítése',
-  noPythonTitle: 'Python 3 kell hozzá',
-  noPythonBody: 'A store egy Python program, tehát Python 3 kell a gépre. Telepítsd, majd nyisd meg újra ezt az ablakot.',
-  pythonLink: 'python.org/downloads',
   paths: 'Hova kerül',
   openStoreFolder: 'Store könyvtár megnyitása',
   openMenuFolder: 'Menü könyvtár megnyitása',