S3-036: Implement exploration and player-specific visibility

Parent and ownership

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

Problem and observable result

Track discovered and visible areas separately. Filter hidden entities from player views. Update visibility from actual units and buildings.

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

Ordered commands advance an integer-tick world. Goods have locations and reservations, people have identities and jobs, and a player view renders only actual simulation state.

• https://github.com/JakeSteam/settlers/blob/8426388935b436e65b0697ac401c4247ab097364/en/ec_basic/basics.htm
• https://github.com/JakeSteam/settlers/blob/8426388935b436e65b0697ac401c4247ab097364/en/ec_build/building.htm

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

• Track discovered and visible areas separately.
• Filter hidden entities from player views.
• Update visibility from actual units and buildings.
• 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

• Move scouts into and out of sight.
• Inspect hidden-state leakage in views.
• 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/the-settlers-iii-remake/issues/29

Upstream release and adoption

Application behavior belongs here. If a reproduction identifies a framework defect, repair and release its owning source first, update Stacks where affected, then install the verified packages here.

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.

Completed: exploration and player-specific visibility

• Each player has an explored layer (permanent) and a visible layer recomputed from its settlers' and buildings' sight on a fixed cadence.
• view() and the render scene() include foreign settlers, buildings and piles only on tiles the player currently sees; foreign diagnostics, shortages and work areas are withheld; unexplored ownership is masked.

Tests: a pioneer walks into sight of a rival castle and its settlers appear; removing the pioneer hides them again while the explored map stays; scenes for each player contain only what that player may see. Sight radii are placeholders.

Evidence base for this update (all on main, authored as Chris):

• 3ca4847 deterministic session, rules profile, routing, goods, carriers, construction, production, territory, visibility, saves and replays
• da2a104 reference building geometry and the delivery livelock fix
• b2efc1f the browser game on the engine, expanded original-media import
• 7b1cc36 worlds from decoded original maps
• a495e7a, 0a3ff46, 0e7889e, e5c1a53, f3b71ce, ed1dc8f controls, missions, render scene, save migration, checkpoints, audit and statistics

Checks: ./buddy lint (0 problems), bun run typecheck (app, tools, stx), ./buddy test --unit (106 tests, 0 failures), bun run assets:verify, bun run content:verify, and the production browser scenario. CI passed on 0e7889e and 9e2ba7c (which contains f3b71ce), including the production Chrome check.

Rule values are the roman-engineering 0.2.0 profile (resources/game/engine/rules.ts). Every value names its evidence class: manual candidates (M) from the pinned manual, reference-remake geometry (E), or placeholders (U) that name their owning issue. qualificationGaps() lists them and the profile cannot qualify a release. Adopting observed original values remains with S3-002/S3-007; nothing here is an original-executable observation.

A further presentation-fidelity gap is reproduced and tracked in #222. A real scout discovers land and leaves; an enemy then converts that unseen desert to grass through a normal intervention. The viewer remains visible=0, explored=1, but the dimmed ground changes immediately. The pinned reference retains hidden landscape, height and map-object snapshots instead.

The reproduction uses public setup and commands, normal temple-supplied manna and the production renderer. No sight, faith, terrain or clock state is directly patched. Existing foreign-entity filtering does not cover this remembered-world behavior. #222 is linked under #88 and follows the terrain material correction in #220; original Gold fog timing remains unqualified.