S3-013: Expose typed persistent JavaScript hosting
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
Retain callbacks and typed buffers in a persistent realm. Propagate errors with bounded ownership. Dispose safely without per-frame generated source strings.
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
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
- Retain callbacks and typed buffers in a persistent realm.
- Propagate errors with bounded ownership.
- Dispose safely without per-frame generated source strings.
- 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 callbacks, GC, and buffer lifetime.
- Stress repeated frames and exceptions.
- 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
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.