S3-011: Implement native Metal surfaces on macOS and iOS

Parent and ownership

Parent epic: https://github.com/stacksjs/the-settlers-iii-remake/issues/6 Source owner: craft-native/craft. Master roadmap: https://github.com/stacksjs/the-settlers-iii-remake/issues/4.

Problem and observable result

Present real animated native frames without WebViews. Handle resize and display scale. Recover or report suspension and device failure.

The current application is a browser prototype. Passing the Riverlands campaign does not establish original-game or native parity. This issue is complete only when its stated behavior has retained evidence.

Evidence and interfaces

Craft owns graphics, native hosting, and platform capabilities. stx owns compilation/reactivity. ts-css owns style semantics. Stacks owns build and release orchestration. The game consumes published contracts.

Pin the inspected revisions and fixture hashes in the implementation evidence. Original-game observations govern rules and timing. JSettlers is implementation evidence, not an authoritative balance specification. Unknown values remain explicitly unverified.

Acceptance criteria

Present real animated native frames without WebViews.
Handle resize and display scale.
Recover or report suspension and device failure.
The visible result agrees with the underlying simulation or platform state, including failure paths.
Tests exercise the maintained public interface and retain reproducible fixtures or execution receipts.

Test matrix

Capture macOS and iOS native pixels.
Repeat create, resize, suspend, and dispose.
Exercise invalid input, cancellation or interruption, and repeated execution where this interface permits them.
Verify determinism/conservation for simulation changes and resource ownership/disposal for platform changes.
Run owning-repository lint, relevant type checks and tests. Capture actual native output for native capability claims.

Scope constraints

Implement this behavior as a complete verifiable slice. Do not silently expand into adjacent tickets or substitute simplified gameplay. Keep the shared TypeScript simulation, shared stx signals, and ts-css conventions. Native gameplay and HUD must not depend on a WebView. HomeOS reuse must not introduce a kernel dependency into the game. Existing unrelated edits and authored guidance must be preserved.

Blocked by

https://github.com/craft-native/craft/issues/391

Upstream release and adoption

Fix and test the owning source repository, run its existing bun run release:patch when it is a Bun package repository, verify published artifacts, then install into Stacks and release Stacks when affected. Update the game from verified published packages. HomeOS uses its own build/source provenance.

No node_modules edits, copied runtimes, generated-source string patches, fabricated globals, successful no-op implementations, or skipped release gates. Push tested conventional commits as Chris to the owning origin/main without coauthor trailers or force pushes.

Completion evidence

Implementation commits and relevant upstream issue links.
Exact checks and results, fixture hashes, and screenshots/native execution evidence where applicable.
Published package versions, downstream lockfile identity, and release receipts when affected.
Remaining limitations stated explicitly. Partial work does not close this issue.

Verified completion on 2026-10-24

Craft 0.0.330 at 5407363b43b6240377c56ceed75e308a39554cf8 is consumed through Stacks 0.75.294 and game commit 5a161f283bcafafc12d3a35e0e4ee897022f464f.

Original native Metal publication evidence: one actual macOS native UI test and two actual iOS native tests passed without failures/skips. Original artifact bytes, ZIP CRCs and exact committed fixture/surface hashes were verified; all six original captures were personally inspected. Fixtures exercise animated drawable pixels, native scale/resize, suspension/background resume, wrong-thread rejection and disposal through the maintained Metal surface.
Executed installed-consumer acceptance: all 95 original installed package trees, exact source/release jobs and seven application checks passed.
Hosted game CI passed frozen installation, lint, types, units, original asset verification, production build, 58 campaign steps and four nine-step control-frame scenarios. Original diagnostic artifact 12572516145, 5406 bytes, SHA-256 15b03daf4260a68f030ee93b5d0a2d49778c50dfa3505c5440cae3eb668a15a7, matched GitHub's digest and archive CRC.
Shared-engine CLI receipt separately verifies the original published Craft executable, Bun and real browser on one five-tick save/restore/replay fixture.

This completes the native Metal surface slice. Full native game rendering, clocks/input integration, RenderSurface/HUD delivery, other native platforms, original Gold behavior/content and redistribution permission remain separate unfinished issues. The browser prototype is not an original-game parity claim. Subsequent command-runner hardening and Win32 acceptance are tracked at their owning sources and do not replace the retained original Metal evidence above.