Optimize display hot paths with opt-in rollout controls

[Arbousier1]

Summary

This PR optimizes high-volume display work while keeping behavior-changing Phase 2 paths explicitly opt-in.

• reduce dropped-item scan and cramping costs with primitive spatial indexes and batched viewer/item work
• add packet-only stationary virtual items, per-player visibility smoothing, and event-driven block refresh paths
• avoid unchanged display/text updates and cache repeated legacy text parsing
• add deterministic benchmarks, runtime/packet A/B harnesses, offline analyzers, provenance checks, and regression tests
• preserve the measured client/server evidence boundary in docs/phase2-evidence-b93d990.md

Rollout safety

The behavior-changing paths are disabled in the bundled configuration:

Setting	Default
Settings.Performance.VirtualItems.StaticAnchorDuringAnimation	false
Settings.Performance.VirtualItems.PacketOnlyStatic	false
Settings.Performance.VisibilityRateLimit.Enabled	false
Settings.Performance.BlockUpdates.EventDriven	false
Entities.Item.Options.VisibilityCulling.Enabled	false
Entities.Item.Options.VisibilityRateLimit.Enabled	false

Commit e25627e adds the two explicit dropped-label gates. With both disabled, dropped labels retain the legacy server-side label lifecycle, immediate eligible-player show/hide behavior, and viewRange=1.0. Hot reload clears pending per-player state when returning to that path. IV_PERF now records the effective dropped-label culling/limiter configuration.

These defaults make the implementations reviewable without claiming that the experimental paths are approved for production rollout.

Validation

Current HEAD e25627e

All PR checks pass:

• Java 25 build/check/production JAR
• Paper 26.1.2 A/B benchmark
• four-run packet ABBA smoke
• four-run clean-runtime ABBA smoke

Local CI-equivalent validation also passed: clean check shadowJar benchmarkJar, Paper 26.1/26.2 compilation, 102 tests with zero failures, all six PowerShell analyzer self-tests, Git Bash syntax checks, Node syntax checks, and 19/19 evidence-manifest hashes.

Measured ancestor b93d990

• formal 12-run clean-runtime A/B passed for the isolated legacy-text-component-cache / block-active factor: mean MSPT 5.0411 -> 3.8049 ms (23.85% lower)
• the packet-only static four-run smoke observed Minecraft protocol events 7168 -> 2048 and Bukkit entity spawns 1024 -> 0; this remains smoke evidence, not a 12-run packet conclusion
• the fixed true-false-true local client experiment observed Present FPS 1098.02 -> 1310.50 (+19.42%, paired 95% CI +15.55% to +23.30%), display FPS 234.43 -> 239.20, and 1% low 117.94 -> 177.53

See the evidence snapshot and frame-file hash manifest. The raw local frame CSVs are not committed, so the client result is not presented as self-contained formal evidence.

Remaining gates

Before merging:

• complete an independent review focused on production code and obtain approval

Before enabling any experimental path in production:

• run the corresponding formal 12-run packet/runtime factor
• complete dropped-label V2 re-entry, multi-viewer, pending-cancel, and ghost validation
• complete target Leaf plus ProtocolLib/PacketEvents/Via/proxy compatibility checks
• retain the raw capture/client artifacts required by docs/phase2-performance-validation.md

The PR remains Draft. No production deployment, restart, or merge was performed.

[TypeThe0ry]

Phase 2 validation update

Implemented and pushed the three experimental paths, all default-off:

• packet-only stationary item displays
• per-player visibility token bucket
• event-driven furnace/smoker/blast-furnace/beehive/bee-nest refresh

CI

• Java 25 build/check/shadowJar passed
• benchmark workflow passed

Client compatibility smoke tests

• 512 packet-only items: visual parity with the tracker-anchor baseline, 512 virtual spawn bundles, 0 Bukkit entity spawns, no ghost after clear.
• 512 visibility-limited items: 512 queued / 512 drained; hide stayed immediate, full restore completed after the intended short wave.
• World switch lifecycle: virtual items disappeared on unload, recreated on return, and cleared without ghosts.
• Furnace, blast furnace, smoker, beehive and bee nest displays were checked in a real 26.1.2 client; front orientation and lifecycle remained correct.

Preliminary block-update comparison

30-second steady samples:

Mode	checks	plugin block-update time
legacy A1	300	68.674 ms
legacy A2	302	51.738 ms
event B1	8	4.383 ms
event B2	8	8.137 ms

This is 97.3% fewer block checks and 84.3–93.6% lower measured plugin block-update time. B1 also reduced mean MSPT from 4.115 to 2.921 ms versus A1, but B2 had to run with a 1 GiB heap after host native-memory pressure, so whole-tick MSPT is not treated as a valid paired conclusion.

Remaining merge gates

• administrator-run PktMon wire capture
• PresentMon FPS capture (current desktop session returns access denied)
• formal same-heap, randomized ABBA rerun

Keeping the PR draft until those separate capture/compatibility gates are complete.

[Arbousier1]

Phase 2 validation update (head 6c37b29)

GitHub-only verification:

• Java 25 build/check/JAR: PASS ? https://github.com/EllanServer/InteractionVisualizer/actions/runs/29232333549
• Paper 26.1.2 A/B benchmark: PASS ? https://github.com/EllanServer/InteractionVisualizer/actions/runs/29232333440
• Result integrity: completion marker 1618 == 1618 JSONL rows; all 1608 visibility rows contain 42 baseline + 42 candidate raw rounds.
• Existing 72-block production comparison: 702/702 median wins, 702/702 both order-strata wins, 702/702 p95 wins.
• New production 64/80 range comparison: 102/102 median wins, 102/102 both order-strata wins, 102/102 p95 wins.
  • range 64 median speedup: diagonal miss 5.641x, late hit 1.440x, uniform guard 2.897x
  • range 80 median speedup: diagonal miss 6.225x, late hit 1.508x, uniform guard 4.210x
• Cost-model paths matched the intended guards: diagonal-miss and uniform probes built no grid; deterministic center and +/-4 boundary fixtures covered build/reject thresholds. Two random short boundary rows correctly stayed linear and still won (R64/v128 1.294x, R80/v191 1.238x).
• The first range-80 run exposed an invalid diagonal fixture (21 real hits); the fixture was corrected to use range-relative offsets. Production index correctness was not the failure.

Packet evidence tooling:

• Added an offline pcapng/pcap/fields-CSV analyzer for server/client direction, TCP payload/frame bytes, epoch-aligned 50ms/1s peaks, retransmission/error flags, evidence hashes and formal-evidence guards.
• Its parser and self-test now run in GitHub CI. Missing TCP-analysis fields force formalEvidenceReady=false.

Still pending before ready/merge:

• elevated PktMon capture plus tshark analysis on an isolated test server;
• capture-off/on overhead calibration;
• real-client F3+L/PresentMon and visual ghost/orientation/lifecycle checks;
• Paper/target Leaf and production protocol-plugin/proxy compatibility matrix;
• formal restart-per-run 12-run ABBA evidence.

The PR remains draft. No local Java build and no production-server deployment/restart were performed.