feat: add generated preloaded menu preview

[MichaelFisher1997]

Summary

• redesign the menu screens with responsive keyboard-accessible controls
• render the main-menu backdrop from a real generated world using player graphics, chunk-distance, horizon, LOD, and shadow settings
• keep the initial window hidden until generated chunks are rendered and startup queues are drained
• update the Nix shell for current mesa and optional validation layers

Verification

• nix develop --command zig build
• nix develop --command zig build -Doptimize=ReleaseFast
• nix develop --command zig build test
• normal hidden-window menu preload run
• repository pre-push formatting and test checks

[github-actions]

kcov coverage

Line coverage ran for this PR and uploaded a non-blocking report artifact named kcov-report. Codecov upload is configured as non-blocking while the project captures a stable baseline.

[github-actions]

📋 Summary

No linked issues are mentioned in the PR description (no Fixes #, Closes #, or Resolves # references).

This PR redesigns the menu screens with responsive keyboard navigation, adds a live generated world backdrop behind the main menu, hides the initial window until the preview world has rendered chunks, and updates the Nix shell for newer mesa and validation-layer handling. The changes are broad but focused on UI/presentation, with the new isReadyForPresentation screen hook being the main architectural addition. The code generally follows existing conventions and the shader validation pipeline runs.

📌 Review Metadata

• Reviewed Commit SHA: 998c0567df56107c7805360eb848ddf1e7a033b6
• Reviewed PR: feat: add generated preloaded menu preview #915

🔴 Critical Issues (Must Fix - Blocks Merge)

[CRITICAL] modules/game-ui/src/screens/home.zig:33 - HomeScreen leaks its own allocation if the menu preview fails to initialize
Confidence: High
Description: HomeScreen.init allocates self with allocator.create and then tries to initialize the embedded WorldScreen preview. If WorldScreen.initMenuPreview fails, self is never freed because there is no errdefer allocator.destroy(self);.
Impact: A memory leak on every failed HomeScreen initialization (e.g., world preview init failure) that violates the project's strict allocator/defer memory-management guidelines.
Suggested Fix: Add errdefer allocator.destroy(self); immediately after the successful allocator.create call, before the self.* = ... assignment.

⚠️ High Priority Issues (Should Fix)

None identified.

💡 Medium Priority Issues (Nice to Fix)

None identified.

ℹ️ Low Priority Suggestions (Optional)

[LOW] modules/game-ui/src/screens/home.zig:162 - Dead code: drawOuterGlow and drawPanelNoise are no longer used
Confidence: High
Description: The helper functions drawOuterGlow and drawPanelNoise are defined but no longer called after the menu redesign.
Impact: Minor clutter and future maintainer confusion.
Suggested Fix: Remove the unused drawOuterGlow and drawPanelNoise functions.

[LOW] flake.nix:337 - Vulkan validation layers removed rather than made optional
Confidence: Medium
Description: The PR summary says "update the Nix shell for current mesa and optional validation layers", but vulkan-validation-layers is removed from all dev shells instead of being provided in an optional shell.
Impact: Developers lose easy access to Vulkan validation layers from the Nix environment, reducing GPU-debugging capability.
Suggested Fix: Either restore vulkan-validation-layers in the default/CI shells or add a separate devShells.with-validation shell that includes them.

📊 SOLID Principles Score

Principle	Score	Notes
Single Responsibility	6/10	The PR bundles UI redesign, menu preview rendering, window lifecycle, and Nix updates together.
Open/Closed	7/10	Adds a new optional isReadyForPresentation hook to IScreen and extends WorldScreen with a preview mode.
Liskov Substitution	7/10	WorldScreen is reused as a preview via the menu_preview flag; screens with optional hooks fall back sensibly.
Interface Segregation	8/10	isReadyForPresentation is optional and defaults to true, so existing screens are unaffected.
Dependency Inversion	6/10	HomeScreen directly depends on the concrete WorldScreen type rather than an abstract renderer.
Average	6.8

🎯 Final Assessment

Overall Confidence Score: 70%

How to interpret: 61-80%: Minor concerns, mostly ready with some fixes.

Confidence Breakdown:

• Code Quality: 75% (generally clean, but the memory leak and dead code lower the score)
• Completeness: 85% (the described menu preview, redesign, and window-reveal features are implemented)
• Risk Level: 60% (new feature runs a full world in the menu; has some surface area for hidden state issues)
• Test Coverage: 70% (menu theme tests updated, but no integration tests for the preview/window-reveal flow)

Merge Readiness:

• All critical issues resolved
• SOLID average score >= 6.0
• Overall confidence >= 60%
• No security concerns
• Tests present and passing (formatting verified; test compilation/shader validation succeeded; full zig build test result was not captured during the review run)

Verdict:

MERGE WITH FIXES

Fix the HomeScreen.init memory leak before merging; the dead code and validation-layer shell handling are optional clean-ups.

Machine Readable Verdict

{
  "reviewed_sha": "998c0567df56107c7805360eb848ddf1e7a033b6",
  "critical_issues": 1,
  "high_priority_issues": 0,
  "medium_priority_issues": 0,
  "overall_confidence_score": 70,
  "recommendation": "MERGE WITH FIXES"
}

opencode session  |  github run

[github-actions]

📋 Summary

No linked issues are mentioned in the PR description (no Fixes #, Closes #, or Resolves # references).

This PR redesigns the menu screens with responsive keyboard navigation, adds a live generated world backdrop behind the main menu via WorldScreen.initMenuPreview, hides the initial window until the preview world has rendered chunks, and updates the Nix shell. The only previous critical finding (a memory leak on failed HomeScreen initialization) has been fixed in the follow-up commit. Code follows existing conventions, and both nix develop --command zig build test and nix develop --command zig fmt --check src/ pass.

📌 Review Metadata

• Reviewed Commit SHA: b40b508e8a0de390f5f6a719ef5b280b2e0f8a25
• Reviewed PR: feat: add generated preloaded menu preview #915

🔴 Critical Issues (Must Fix - Blocks Merge)

✅ [FIXED] Previous issue: HomeScreen.init leaked its allocation if WorldScreen.initMenuPreview failed (missing errdefer allocator.destroy(self)). Commit b40b508 added the required errdefer at modules/game-ui/src/screens/home.zig:34.

No new critical issues identified.

⚠️ High Priority Issues (Should Fix)

None identified.

💡 Medium Priority Issues (Nice to Fix)

None identified.

ℹ️ Low Priority Suggestions (Optional)

[LOW] modules/game-ui/src/screens/home.zig:163 - Dead code: drawOuterGlow and drawPanelNoise are unused
Confidence: High
Description: The helper functions drawOuterGlow and drawPanelNoise are defined but never called after the menu redesign.
Impact: Minor clutter and future maintainer confusion.
Suggested Fix: Remove the unused drawOuterGlow and drawPanelNoise functions.

[LOW] flake.nix:337 - Vulkan validation layers removed rather than made optional
Confidence: Medium
Description: The PR summary says "update the Nix shell for current mesa and optional validation layers", but vulkan-validation-layers is removed from all dev shells instead of being provided as an option.
Impact: Developers lose easy access to Vulkan validation layers from the Nix environment, reducing GPU-debugging capability.
Suggested Fix: Either restore vulkan-validation-layers in the default/CI shells or add a separate devShells.with-validation shell that includes them.

📊 SOLID Principles Score

Principle	Score	Notes
Single Responsibility	6/10	Bundles UI redesign, menu preview rendering, window lifecycle, and Nix updates together.
Open/Closed	7/10	Adds a new optional isReadyForPresentation hook and extends WorldScreen with a preview mode.
Liskov Substitution	7/10	WorldScreen is reused as a preview via the menu_preview flag; existing behavior remains unchanged.
Interface Segregation	8/10	isReadyForPresentation is optional and defaults to true, so existing screens are unaffected.
Dependency Inversion	6/10	HomeScreen directly depends on the concrete WorldScreen type rather than an abstract renderer.
Average	6.8

🎯 Final Assessment

Overall Confidence Score: 80%

Confidence Breakdown:

• Code Quality: 80% (clean, follows conventions, memory leak fixed)
• Completeness: 85% (menu redesign, preview, hidden-window reveal, and Nix updates are implemented)
• Risk Level: 55% (full world running in menu is non-trivial but isolated behind the menu_preview flag)
• Test Coverage: 75% (menu theme tests updated, full zig build test passes, but no integration test for the preview/window-reveal flow)

Merge Readiness:

• All critical issues resolved
• SOLID average score >= 6.0
• Overall confidence >= 60%
• No security concerns
• Tests present and passing (zig build test and zig fmt --check src/ both pass)

Verdict:

MERGE

The critical memory leak from the first review has been resolved. The remaining two items are optional clean-ups (dead code and Nix validation-layer handling) and do not block merging.

Machine Readable Verdict

{
  "reviewed_sha": "b40b508e8a0de390f5f6a719ef5b280b2e0f8a25",
  "critical_issues": 0,
  "high_priority_issues": 0,
  "medium_priority_issues": 0,
  "overall_confidence_score": 80,
  "recommendation": "MERGE"
}

opencode session  |  github run