S3-019: Verify native reactive HUD and event delivery

Parent and ownership

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

Problem and observable result

Preserve keyed controls and focus. Deliver imported-module signals and events. Clean subscriptions on native disposal.

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.

• https://github.com/craft-native/craft/tree/cfde9ae33285d0697182fc794f799e108c11db32
• https://github.com/stacksjs/stx/tree/c5db290664
• https://github.com/home-lang/home-os/tree/151269666bc09aa15a271f1c1f4603f681132e65
• Related existing work: https://github.com/stacksjs/stx/issues/2101

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

• Preserve keyed controls and focus.
• Deliver imported-module signals and events.
• Clean subscriptions on native disposal.
• 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

• Exercise native dynamic lists and focus.
• Repeat mount, mutation, input, and disposal.
• 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/stacksjs/stx/issues/2108
• https://github.com/stacksjs/ts-css/issues/38

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.

Partial source correction published in stx v0.2.638: native document visibility now follows Craft APP_STATE. Imported animation clocks stop during background/inactive states, resume with zero delta, and clean up on unmount.

Implementation: fefd06b. Release: 7a0f6f4, normal main/tag push as Chris without trailers. Exact-source and npm gates passed. Local suite: 16,771 pass, 4 existing skips, 0 fail; native suite: 782 pass. All six public package tarballs and SHA512 identities, clean registry installation and frozen installation passed.

Retained package/CI receipt. The installed lifecycle probe executes a compiled native bundle in a controlled JavaScript VM. It does not prove UIKit/device or native game presentation.

This issue remains open. Full keyed HUD, focus, surface/style integration and actual native host acceptance remain required. Stacks has adopted the verified cohort upstream; its patch release and game adoption remain pending Craft acceptance.

Landed a maintained HUD verification slice in ef95fa0; retained receipt/screenshot in 1d67b36. Version status: unreleased after v0.2.665.

• Public compiler + native protocol: normal/minified bundles, two fresh mounts each, imported module state/events, keyed text editing/reordering, invalid-input feedback, subscription disposal and no post-unmount host mutations: 2 tests passed, 0 failed, 54 assertions.
• Actual UIKit run using an unchanged clean Craft checkout at f6929b7: 1 XCTest passed, 0 failed, 0 skipped on iPhone 17 Pro / iOS 26.5 simulator. Typing, counter/event labels, validation feedback and keyboard/continued typing after keyed reordering are verified. No WebView.
• Broader STX regression cohort: 3,132 passed, 0 failed; lint, format and typecheck passed.

Reproduction and limitations, portable source-hash receipt, inspected UIKit screenshot.

Keeping this issue open. This is a reactivity/ownership fixture, not substitute gameplay. It does not establish native RenderSurface composition (#2108), the ts-css#38 HUD styling acceptance, Android output, device-instrumented subscription teardown, published package adoption or actual game simulation agreement. Former ts-css#39 and Craft#409 were closed as duplicates, not fixed; the canonical blockers are ts-css#38 and Craft#395. Craft code was not changed; its assigned agent still owns the host contract.

Follow-on fix and native evidence: 206d9cf (shared module identity) and c62ab5c (UIKit removal/remount regression and receipt), pushed to main. This fix is not in the v0.2.666 tag; it needs a subsequent patch release.

The stronger HUD fixture exposed a real bug: forced native screen setup inlined user imports, while child component scripts read the page module registry. A screen and child importing the same model therefore held independent state and subscription sets. Native setup now uses the same registry as components.

The maintained fixture now removes and remounts a keyed HUD component twice, with root-owned updates while it is absent. It verifies subscription ownership 1 -> 0 -> 1, no old event callbacks, fresh component-local event state, persisted model drafts and exactly one event per update. Protocol regression: 2 passed / 0 failed / 134 assertions, with two fresh screen mounts in each of normal/minified modes. The full native cohort passed 945 tests / 0 failures. Typecheck, formatting and release preflight (including installed-package smoke and performance budgets) passed.

Actual UIKit execution: 1 XCTest passed / 0 failed / 0 skipped, 56.637 seconds, iPhone 17 Pro / iOS 26.5 simulator, unchanged clean Craft f6929b7. This extends the earlier receipt to instrument real component subscription teardown/remount on the native host; whole-screen teardown remains additionally covered in protocol tests.

Reproduction and explanation, receipt with source/bundle hashes, inspected UIKit screenshot.

Keeping #2109 open: RenderSurface integration (#2108 / Craft #395), ts-css#38, actual game adoption, native Android visual acceptance and the remaining broad style/surface requirements are not established by this fixture. Craft code was not modified.

Published-package follow-up: @stacksjs/stx 0.2.674 is readable from npm, and a clean registry install plus frozen install passes the maintained HUD contract in both normal/minified bundles, with two fresh mounts each. This verifies shipped module identity, keyed draft retention, failure feedback, component removal/remount and subscription cleanup—not just source imports.

The same probe is now part of bun run smoke:install / release preflight, using actual package archives and public installed exports. No source compiler/runtime is copied into the consumer. The fixture/assertion sources are the only copied test inputs. The preflight also passed 319 targeted tests, typecheck, installed-package smoke, export validation and performance budgets.

Implementation: 6406d302a3, retained npm integrity / probe / fixture hashes. CI for this new gate commit is separate from the green release-source run below.

Latest-main slot/HUD/assertion regressions: 15 passed, 0 failed. CI on release source a3bf903 is now green after retrying the failed macOS Pantry provisioning job; lint/typecheck/unit tests were already passing. The unrelated icon-publication and VS Code Marketplace failures do not mean the core STX npm package is unpublished.

Keeping #2109 open. Craft now has UIKit Metal evidence, but still no public JS/native surface bridge usable by STX (#2108 / Craft#395), and ts-css#38 plus actual game integration remain outstanding. Craft code was not modified.