Cross-platform support: platform-aware update pipeline, POSIX updater ops, and native macOS app build

.gitignore

@@ -39,4 +39,5 @@ src/Data/TimelessJewelData/*.bin
 runtime/imgui.ini
 runtime/SimpleGraphic/SimpleGraphic.log
 
-src/poe_api_response.json
+src/poe_api_response.json
+build/

CONTRIBUTING.md

@@ -67,7 +67,7 @@ The easiest way to make and test changes is by setting up a development installa
        cd PathOfBuilding
 
 3. Start Path of Building from the repository by running `./runtime/Path{space}of{space}Building.exe`.
-   * <ins>Note for Linux users:</ins> The executable files should automatically have the correct permissions when cloned fresh. If you still encounter permission issues, run once: `chmod +x ./runtime/Path{space}of{space}Building-PoE2.exe`
+   * <ins>Note for Linux users:</ins> The executable files should automatically have the correct permissions when cloned fresh. If you still encounter permission issues, run once: `chmod +x ./runtime/Path{space}of{space}Building.exe`
 You can now use the shortcut to run the program from the repository. Running the program in this manner automatically enables "Dev Mode", which has some handy debugging feature:
 * `F5` restarts the program in-place (this is what usually happens when an update is applied).
 * `Ctrl` + `~` toggles the console (Note that this does not work with all keyboard layouts. US layout is a safe bet though).
@@ -210,6 +210,34 @@ If you're using linux you can run the ./runtime/Path{space}of{space}Building.exe
 Z:\home\dev\.vscode\extensions\tangzx.emmylua-0.8.20-linux-x64\debugger\emmy\windows\x64\
 ```
 
+See [docs/crossPlatform.md](docs/crossPlatform.md) for how platform support is
+structured and what native Linux/macOS support requires.
+
+### macOS
+
+A native arm64 app can be built from source:
+
+1. Install prerequisites: Xcode, plus `brew install cmake ninja`.
+2. Clone the host repo as a sibling:
+   `git clone https://github.com/PathOfBuildingCommunity/PathOfBuilding-SimpleGraphic.git ../PathOfBuilding-SimpleGraphic`
+   then run `git submodule update --init --recursive`. The macOS build also
+   needs the `feat/macos-build` changes, which are not yet merged upstream —
+   see [docs/crossPlatform.md](docs/crossPlatform.md) for their status; until
+   they land, use a checkout that already contains them.
+3. From this repo: `make macos-app` (first run builds all native
+   dependencies via vcpkg — expect 30-60 minutes), then `make run-macos`.
+
+The app runs in dev mode from your checkout: update with `git pull`, user
+data lives in `src/`. Override the checkout with `POB_SCRIPT_PATH` or the
+host clone location with `make SG_DIR=/path/to/clone macos-app`.
+
+Known limitations of the local app: `pob://` links launch the app but URL
+delivery into the running program is best-effort (links to an
+already-running instance are not received); and the app writes some runtime
+state (`imgui.ini`, logs) inside its own bundle, which is discarded on the
+next `make macos-app`. Build/character data is unaffected — it lives in
+`src/` in your checkout.
+
 ## Testing
 
 PoB uses the [Busted](https://lunarmodules.github.io/busted/) framework to run its tests. Tests are stored under `spec/System` and run automatically when a PR is modified.

Makefile

@@ -0,0 +1,40 @@
+# Path of Building — developer entry points.
+# macOS app targets require a sibling clone of PathOfBuilding-SimpleGraphic
+# (branch feat/macos-build); override SG_DIR if yours lives elsewhere.
+
+SG_DIR ?= $(HOME)/dev/thirdparty/PathOfBuilding-SimpleGraphic
+SG_DIST := $(SG_DIR)/build/dist
+BUILD_DIR := build/macos
+APP_NAME := Path of Building.app
+TEST_IMAGE := ghcr.io/pathofbuildingcommunity/pathofbuilding-tests:latest
+
+.PHONY: test test-python manifest macos-runtime macos-app run-macos clean-macos
+
+test:
+	docker run --rm --platform linux/amd64 -e HOME=/tmp -v "$(CURDIR)":/workdir:ro -w /workdir $(TEST_IMAGE) busted --lua=luajit
+
+test-python:
+	python3 -m pytest tests/ -v
+
+manifest:
+	python3 update_manifest.py --in-place
+
+$(SG_DIR)/CMakeLists.txt:
+	@echo "error: SimpleGraphic clone not found at $(SG_DIR)"; \
+	echo "  git clone https://github.com/PathOfBuildingCommunity/PathOfBuilding-SimpleGraphic.git $(SG_DIR)"; \
+	echo "  (then check out branch feat/macos-build and init submodules)"; \
+	exit 1
+
+macos-runtime: $(SG_DIR)/CMakeLists.txt
+	cmake -B "$(SG_DIR)/build" -S "$(SG_DIR)" -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_OSX_ARCHITECTURES=arm64 -DVCPKG_TARGET_TRIPLET=arm64-osx
+	cmake --build "$(SG_DIR)/build"
+	cmake --install "$(SG_DIR)/build" --prefix "$(SG_DIST)"
+
+macos-app: macos-runtime
+	SG_DIST="$(SG_DIST)" BUILD_DIR="$(BUILD_DIR)" POB_ROOT="$(CURDIR)" bash scripts/build-macos-app.sh
+
+run-macos: macos-app
+	open "$(BUILD_DIR)/$(APP_NAME)"
+
+clean-macos:
+	rm -rf "$(BUILD_DIR)"

docs/crossPlatform.md

@@ -0,0 +1,66 @@
+# Cross-platform architecture
+
+Path of Building is a pure-Lua application (`src/`) that runs on a native host.
+The host API contract is specified, in executable form, by
+[`src/HeadlessWrapper.lua`](../src/HeadlessWrapper.lua): any host that provides
+those globals (rendering, input, filesystem search, clipboard, subscripts,
+`Inflate`/`Deflate`, path helpers) can run the app. The shipping host is
+SimpleGraphic (built from
+[PathOfBuilding-SimpleGraphic](https://github.com/PathOfBuildingCommunity/PathOfBuilding-SimpleGraphic)),
+which renders through GLFW + ANGLE (OpenGL ES) and is delivered into `runtime/`
+by the `update-simple-graphic` workflow.
+
+## Platform identity
+
+A client learns its platform from the `platform` attribute of the `<Version>`
+element in its local `manifest.xml` (e.g. `win32`). The updater
+(`src/UpdateCheck.lua`) then:
+
+- includes a remote `<File>` iff it has no `platform` attribute or its
+  `platform` matches the local platform;
+- downloads each part from `<Source part="..." platform="...">` matching the
+  local platform, falling back to the platform-less source.
+
+`update_manifest.py` generates these attributes from `manifest.cfg`: a section
+with a `platform` option tags its source and every file it contains with that
+platform. A section may set `part` to publish under a shared part name, so a
+future `[runtime-linux64]` section (with `part = runtime`,
+`platform = linux64`) ships an alternative runtime bundle without any client
+code changes.
+
+## Update ops
+
+`UpdateCheck.lua` stages downloads and writes an ops file that
+`UpdateApply.lua` executes (`move`, `delete`, `chmod`, `start`). On non-win32
+platforms, updated runtime files without a file extension (the POSIX
+executables) get a `chmod` op so they stay executable after being rewritten.
+Runtime files are applied by a second, minimal host (`runtime/Update` /
+`Update.exe`) because the main host's own binaries cannot replace themselves
+while running.
+
+## Host expectations
+
+Hosts are not required to provide every global: `GetCloudProvider` is optional,
+and `jit.opt` tuning is skipped when unavailable. Asset paths are
+case-sensitive on Linux/macOS; `spec/System/TestAssetCase_spec.lua` enforces
+that all `Assets/` references match on-disk casing exactly.
+
+## Status
+
+Native Linux/macOS support additionally requires (tracked as follow-on plans):
+
+1. A POSIX/macOS system layer in PathOfBuilding-SimpleGraphic publishing
+   `SimpleGraphicDLLs-<arch>-<os>.tar` release assets (the Windows asset
+   already follows this naming).
+2. Per-platform runtime bundles in this repo (`[runtime-<platform>]` manifest
+   sections), ingestion workflow updates, and packaging. Until then, Linux
+   users run the Windows build under Wine or use community hosts such as
+   pobfrontend.
+
+On macOS, a native app can be built locally today: `make macos-app` builds
+the SimpleGraphic host from a sibling clone (branch `feat/macos-build`, currently local-only, pending upstream submission) and
+assembles `build/macos/Path of Building.app`, a dev-mode app running
+`src/Launch.lua` from this checkout. Auto-updates are disabled by design:
+the published manifest has no macOS runtime section yet, so an
+update-enabled macOS install would delete its own native runtime (see
+"Update ops" above).

manifest.cfg

@@ -5,6 +5,7 @@ include-directories =
 
 [runtime]
 path = runtime
+platform = win32
 exclude-files = lua-profiler.lua,msvcr100.dll,SimpleGraphic.cfg,Update.exe,imgui.ini,SimpleGraphic.log
 exclude-directories =