Match native neighboring block-face visibility and suppression

docs/face-visibility.md

@@ -0,0 +1,41 @@
+# Neighboring model-face visibility
+
+`horizon-world::block_render::FaceVisibility` decides whether to emit a model
+quad with a culling direction beside a neighboring block. It prepares immutable
+face geometry from the pinned raw occlusion shapes, shares faces across states,
+and caches shape-pair subtraction with bounded memory. It is ready for chunk
+meshing; it does not yet replace the development scene's cube-only culling.
+
+The decision preserves the native order: a canonical full neighbor face hides
+the quad, block-specific suppression can hide it, canonical empty faces bypass
+the shape comparison, and partial faces use `ONLY_FIRST` subtraction. Full
+occlusion is computed from geometry, independently of collision or support.
+
+Block-specific suppression covers every method owner in the pinned registry:
+ordinary blocks, same-block glass/ice and powder snow, bars/panes, leaves,
+liquids, and mangrove roots. Bars respect the loaded bars tag, facing connections,
+and the neighbor's boolean property availability. Leaf suppression is controlled
+by the cutout-leaves setting. Liquids compare fluid families, including contained
+water in waterlogged neighbors. Mangrove roots suppress vertical internal faces.
+
+The [native comparison](../benchmarks/rust-face-visibility-2026-10-06/scoped-parity.json)
+calls actual `BlockState.skipRendering` and `Block.shouldRenderFace` with pinned
+tags bound in both reference JARs. It covers all 35,723 states and 1,286 block
+definitions: 1,441,816 ordered state pairs, six directions and two leaf settings
+(17,301,792 direction/setting cases). Every overriding family has exhaustive
+same-block state pairs; bars and panes also have exhaustive cross-material
+connection pairs. Representative and seeded random neighbors exercise partial
+occlusion across the rest of the registry. Both references match 2,883,632 output
+lines, each containing suppression and visibility masks for all six directions.
+
+```sh
+python3 tools/test_face_visibility_parity.py
+cargo clippy --workspace --all-targets --locked -- -D warnings
+```
+
+The private imports contain raw shape grids, definition flags, class-rule
+assignments and tag membership. Rust computes the behavior being compared.
+Unknown state IDs produce errors. Native fixture files, reference JARs and traces
+stay under ignored `.local/`; only hashed reports are committed. Lighting,
+translucent sorting, fluid surfaces, GPU pixels and gameplay remain outside this
+comparison. Native macOS and Windows runs are still required.

docs/native-client.md

@@ -262,3 +262,7 @@ property domains and canonical state order, which the Rust loader checks against
 its imported registry before binding. Each distinct transformed model is baked
 once during gallery preparation and reused across positions. The selected state
 IDs, properties, positions and models are recorded in the startup report.
+
+[Neighbor-face visibility](face-visibility.md) now has native client/server
+coverage across all registered states and suppression-rule families. Integrating
+that result with resident chunk model meshing is the next rendering step.

docs/rust-parity.md

@@ -29,6 +29,8 @@ inspection gallery from registry-bound, selected and transformed models, includi
 cutouts, multipart connections, weighted stone variants and stepped lantern
 animation. All 16 scene selections match native model collection. These are not
 yet gameplay blocks; general chunk model rendering remains unfinished.
+[Neighbor face visibility](face-visibility.md) now matches both reference JARs
+across 1,441,816 state pairs, including all pinned suppression-rule families.
 Animation metadata, frame sequences and tick-state selection now have native
 differential coverage, including all bundled animated texture metadata. GPU
 interpolation and game-loop synchronization remain unfinished.