Audio feedback for difficulty slider interaction

files/docs/milestones/19/PART_3_Update_Godot_export_action_pin_and_configure_Codecov_token.md

@@ -0,0 +1,68 @@
+# Update Godot export action pin and configure Codecov token
+
+## Summary
+
+Update CI workflows to use the latest pinned Godot export action and
+ensure test reports upload correctly to Codecov.
+
+### CI
+
+- Bump the pinned SHA of the firebelley/godot-export GitHub Action
+  across browser tests, CodeQL analysis, and itch.io deployment workflows.
+- Set the Codecov upload step in GUT tests workflow to use the
+  `CODECOV_TOKEN` secret for authenticated report uploads.
+
+### Chores
+
+  - Updated build and export automation dependencies to maintain
+    compatibility and reliability.
+  - Enhanced CI/CD pipeline security by properly configuring token access
+    for automated code coverage reporting.
+
+---
+
+## Reviewer's Guide
+
+Updates CI workflows to use a newer pinned revision of the
+firebelley/godot-export GitHub Action and ensures the Codecov upload step
+has the required token set via environment variables.
+
+
+### File-Level Changes
+
+<!-- markdownlint-disable MD013 MD033 table-column-style -->
+| Change                                                                                                | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Files                                                                                                              |
+|-------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
+| Bump the pinned firebelley/godot-export GitHub Action SHA across workflows to a newer revision.       | <ul><li>Update the godot-export action reference in the browser_test workflow to the new commit SHA while keeping Godot 4.5 download URLs unchanged.</li><li>Update the godot-export action reference in the codeql workflow to the new commit SHA, preserving existing Godot build URLs and comments.</li><li>Update the godot-export action reference in the deploy_to_itch workflow to the new commit SHA, keeping export configuration intact.</li></ul> | `.github/workflows/browser_test.yml`<br/>`.github/workflows/codeql.yml`<br/>`.github/workflows/deploy_to_itch.yml` |
+| Fix Codecov upload configuration so reports are sent with the explicit token from repository secrets. | <ul><li>Set CODECOV_TOKEN environment variable for the Codecov upload step in the gut_tests workflow, sourcing it from GitHub Actions secrets.</li><li>Leave the rest of the test report discovery and upload logic unchanged.</li></ul>                                                                                                                                                                                                                     | `.github/workflows/gut_tests.yml`                                                                                  |
+<!-- markdownlint-enable MD013 MD033 table-column-style -->
+
+---
+
+## Bots/AI Contributions Summary for PR #736
+
+This PR focuses on CI/CD maintenance: updating the pinned SHA for the 
+`firebelley/godot-export` GitHub Action across multiple workflows and
+configuring the `CODECOV_TOKEN` for authenticated coverage uploads.
+It received valuable support from automated bots and AI tools for dependency
+management, summarization, and code quality review.
+
+### Automated Bots & AI Tools
+
+- **@dependabot[bot]**: Initiated and managed the major version bump of `firebelley/godot-export` from 7.0.0 to 8.0.0, including the automated commit and PR creation for the dependency update. This ensured the workflows stayed current with the latest action features and security improvements.
+- **@sourcery-ai**: Generated a clear PR summary and reviewer's guide, highlighting the action version bump across workflows and the Codecov token configuration. Also assisted with title generation and overall review structure.
+- **@coderabbitai**: Provided a focused summary emphasizing CI/CD reliability improvements, security enhancements through proper token handling, and maintenance of build/export automation.
+- **@deepsource-io**: Conducted automated static code analysis and code review on the workflow changes. Provided an overall grade across Security, Reliability, Complexity, and Hygiene categories, along with inline comments and a full review report.
+
+These tools contributed to better documentation, reviewer guidance,
+dependency security, and code health validation.
+
+### Human Maintainers
+
+- **@ikostan**: Primary contributor and PR author. Coordinated the changes,
+  updated the pinned commit SHAs for the Godot export action in `browser_test.yml`,
+  `codeql.yml`, and `deploy_to_itch.yml`, configured the `CODECOV_TOKEN`
+  environment variable in `gut_tests.yml`, added a detailed reviewer's guide with
+  Mermaid flowchart, and integrated the updates into the project milestone.
+
+---

files/docs/milestones/19/PART_4_gameplay_settings_audio_interaction_and_asset_tracking.md

@@ -0,0 +1,114 @@
+# 📝 Gameplay Settings Audio Interaction & Asset Tracking Architecture
+
+This technical document records the architecture, behavioral boundaries,
+and runtime asset dependencies introduced by the focus-gated audio
+feedback system within the Gameplay Settings menu. This log ensures
+long-term system maintainability and guards critical assets against
+automated cleanup or build pruning tools.
+
+---
+
+## 🚀 1. UI Architecture & Design Principles
+
+The difficulty adjustment pipeline within `gameplay_settings.gd` utilizes
+real-time interactive audio feedback to improve player responsiveness
+across native and web-exported platforms. To align with the architectural
+design patterns established within the Audio Settings menu, the
+implementation operates under a strict **Mute Signal Isolation and
+Decoupling Pattern**.
+
+### Core Architectural Axioms:
+
+* **Focus-Gated Control:** Audio playback is strictly decoupled from the low-level data engine layer. Sound effects are never permitted to fire automatically from generic value mutation listeners.
+* **Gated Pathway Verification:** Audio execution triggers only when an explicit, user-driven interaction vector is authenticated via the viewport focus system or a verified external API token.
+* **Pipeline Parity:** External interaction vectors (such as HTML5 browser overlays via JavaScript) do not duplicate or independently mutate state; they route safely into the native internal interaction handling pipeline to maintain identical validation rules.
+
+---
+
+## 🔄 2. Interaction Pipelines: Behavioral Division
+
+To maintain deterministic execution states during tests, configuration restoration, and real-time gameplay updates, the system enforces an absolute separation between **Interactive Pathways** (audible) and **Silent Pathways** (programmatic).
+
+### 🟢 Interactive Pathways (Audible Feedback)
+
+The following operations represent intentional human interactions. Each discrete event must invoke exactly one audio playback event via `AudioManager.play_sfx("slider")`:
+
+1. **Mouse Interaction:** Dragging or clicking the physical `DifficultyHSlider` node bar while the control captures active mouse input.
+2. **Keyboard & Controller Navigation:** Utilizing the D-Pad, arrow keys, or analog controls to shift slider increments while the node possesses viewport layout focus (`has_focus()`).
+3. **Gameplay Reset Button:** Pressing the layout `ResetButton` control element. This bypasses localized focus restrictions by explicitly passing an interactive intent flag to reset variables back to default states (`1.0`).
+4. **Verified JS Overlay Interactions:** Incoming signals from the web-assembly runtime browser layout (`_on_change_difficulty_js()`). These bypass localized viewport check gates using an explicit parameter token override since external DOM nodes cannot hold local Godot UI focus.
+
+### 🔴 Silent Pathways (Absolute Silence)
+
+The following operations represent programmatic synchronization, lifecycle state management, or automated testing loops. These blocks **must remain completely silent** and are protected against audio leakage:
+
+1. **Menu Initialization:** Instantiating the scene container and executing `_ready()` loops to synchronize variables with global configuration singletons.
+2. **Save & Configuration Synchronization:** Real-time data updates loading from or saving to disk using the `Globals.settings` configuration serialization layer.
+3. **External Observer Reactivity:** When the underlying settings resource broadcasts a `setting_changed` signal, the UI reacting inside `_on_external_setting_changed()` hooks updates layout positions silently.
+4. **Recursive Loop Mitigation:** Programmatic updates applied to UI controls utilize Godot’s native `set_value_no_signal()` method rather than direct property modification, ensuring that layout changes do not trigger duplicate handlers or audio signals.
+5. **Automated Setup Flows:** Headless test runner executions (such as automated GUT unit suites) mocking environment profiles.
+
+---
+
+## 📦 3. Explicit Runtime Asset Dependency Registration
+
+To prevent automated pruning tools, resource optimization scripts, or export exclusion whitelists from accidentally dropping required audio assets during project compilation, the explicit relationship mapping below is formally registered:
+
+### Dependency Mapping Matrix
+
+```text
+[Dependent UI Script Component]
+ res://scripts/ui/menus/gameplay_settings.gd
+
+       └── Refers to Runtime Identifier: "slider"
+
+[Target Live Audio Asset Resource]
+ res://files/sounds/sfx/slider.wav
+
+```
+
+### Resource Metadata Definitions:
+
+* **Asset Path:** `res://files/sounds/sfx/slider.wav`
+* **Import Profile Configuration:** Controlled via tracking metadata at `res://files/sounds/sfx/slider.wav.import`.
+* **Runtime Deployment Target:** Mapped to the `AudioConstants.BUS_SFX_MENU` mixer channel backend through the centralized pool allocation routing configuration.
+
+---
+
+## 🛡️ 4. Asset Protection & Pruning Safeguards
+
+The sound asset `slider.wav` is flagged as an **actively referenced runtime gameplay UI dependency**.
+
+### Maintenance Directives for Future Contributors:
+
+* **Exclusion from Optimization Sweets:** This file **is unsafe to remove** or exclude during asset compression passes, engine pruning commands, or build export optimization cycles.
+* **No Direct File Tracing Checks:** Pruning tools checking files strictly via direct script `load()` or `preload()` paths will miss this asset, as it is requested dynamically through an abstraction layer string identifier (`"slider"`). Do not delete this asset based solely on a lack of static reference lines inside the codebase.
+* **Deprecation Protection:** If the Gameplay Settings menu layout is altered in future refactors, this asset must remain preserved in storage unless all focus-gated slider workflows across the option menus are completely eliminated.
+
+---
+
+## ⚠️ 5. Regression Prevention Notes
+
+When engineering updates or extending features under this layout ecosystem, future developers must respect these defensive constraints to prevent breaking system stability:
+
+1. **Why Generic `value_changed` Signals Cannot Play Audio:**
+Attaching an audio hook directly to a standard slider signal creates an immediate architectural loop vulnerability. Because code modifications to a slider's layout re-trigger its `value_changed` signal, programmatic setups (like reading a save file) will cause sound effects to blast during initialization or lock the loop into infinite recursion.
+2. **Why JS Overlays Require Explicit Intent Passing:**
+When a game export is displayed in a browser canvas, clicking an HTML overlay button interacts directly with the page DOM, meaning Godot's localized viewport focus tracking returns `false`. By adding `is_interactive: bool = false` parameters, the web overlay can cleanly override the focus gate token, ensuring identical state behavior without splitting the pipeline into separate logic wrappers.
+3. **Why Headless Audio Isolation Matters:**
+Automated unit tests running inside headless CI/CD systems run without physical audio server drivers or sound hardware cards. Isolating audio calls into guarded blocks checking for a valid `AudioManager` prevents testing environments from crashing due to null pointer engine executions.
+
+---
+
+### 📝 Acceptance Criteria Verification Status
+
+* [x] Gameplay Settings audio interaction behavior is documented.
+* [x] Focus-gated interaction architecture is documented.
+* [x] Silent synchronization behavior is documented.
+* [x] JS overlay interaction routing behavior is documented.
+* [x] Explicit dependency mapping to `slider.wav` is recorded.
+* [x] Asset pruning protection notes are added.
+* [x] Documentation reflects actual runtime implementation behavior.
+* [x] Future contributors can identify the dependency relationship without code tracing.
+
+---

scripts/ui/menus/gameplay_settings.gd

@@ -209,7 +209,8 @@ func _unset_gameplay_settings_window_callbacks() -> void:
 ## Handles Gameplay Settings reset button press.
 func _on_gameplay_reset_button_pressed() -> void:
 	Globals.log_message("Gameplay Settings reset pressed.", Globals.LogLevel.DEBUG)
-	_on_difficulty_value_changed(_default_difficulty)
+	# Route through standard handler with explicit interaction override set to true
+	_on_difficulty_value_changed(_default_difficulty, true)
 
 
 func _on_gameplay_reset_js(_args: Array) -> void:
@@ -284,19 +285,19 @@ func _on_gameplay_back_button_pressed_js(args: Array) -> void:
 
 
 # Change: Separate handler for signal (float value)
-func _on_difficulty_value_changed(value: float) -> void:
+func _on_difficulty_value_changed(value: float, is_interactive: bool = false) -> void:
 	## Handles changes to the difficulty slider from the signal.
 	##
 	## Updates global difficulty, label text, logs the change, and saves settings.
+	## Gates slider.wav playback behind UI focus verification or explicit external
+	## interaction overrides.
 	##
 	## :param value: The new slider value.
 	## :type value: float
+	## :param is_interactive: True if the event was triggered by a verified external human
+	## interaction vector.
+	## :type is_interactive: bool
 	## :rtype: void
-	# Update the resource first (this triggers clamping in the setter)
-	#Globals.settings.difficulty = value
-	# Update the UI components using the ALREADY CLAMPED value from the resource
-	#difficulty_slider.value = Globals.settings.difficulty
-	#difficulty_label.text = "{" + str(Globals.settings.difficulty) + "}"
 	var settings_res := Globals.settings if is_instance_valid(Globals) else null
 
 	# FIX: Use the local reference exclusively
@@ -307,12 +308,23 @@ func _on_difficulty_value_changed(value: float) -> void:
 		)
 		return
 
+	# Evaluate focus validation before updating UI structures
+	var slider_has_focus: bool = false
+	if is_instance_valid(difficulty_slider):
+		slider_has_focus = difficulty_slider.has_focus()
+
+	# Gate audio playback on explicit intent token or validated UI focus
+	var should_play_audio: bool = is_interactive or slider_has_focus
+
 	settings_res.difficulty = value
 	if is_instance_valid(difficulty_slider):
 		difficulty_slider.set_value_no_signal(settings_res.difficulty)
 	if is_instance_valid(difficulty_label):
 		difficulty_label.text = "{" + str(settings_res.difficulty) + "}"
 
+	if should_play_audio:
+		_play_slider_sfx()
+
 
 # New: JS-specific callback (exactly one Array arg, no default)
 func _on_change_difficulty_js(args: Array) -> void:
@@ -376,8 +388,8 @@ func _on_change_difficulty_js(args: Array) -> void:
 		"JS difficulty callback called with valid value: " + str(value), Globals.LogLevel.DEBUG
 	)
 
-	# Pass the validated value to the standard handler
-	_on_difficulty_value_changed(value)
+	# Pass the validated value to the standard handler with the interactive flag explicitly overridden
+	_on_difficulty_value_changed(value, true)
 
 
 ## GS-JS: Helper to extract a potential value from diverse JS bridge payloads.
@@ -430,3 +442,17 @@ func _grab_initial_focus() -> void:
 		[difficulty_slider, gameplay_back_button, gameplay_reset_button],
 		"Gameplay Settings Menu"
 	)
+
+
+## Helper to cleanly trigger interactive feedback via the global AudioManager
+## Prevents engine-level environment execution faults during headless unit testing pipelines.
+##
+## :rtype: void
+func _play_slider_sfx() -> void:
+	if is_instance_valid(AudioManager) and AudioManager.has_method("play_sfx"):
+		AudioManager.play_sfx("slider")
+	elif is_instance_valid(Globals):
+		Globals.log_message(
+			"Gameplay Settings: AudioManager unavailable or missing play_sfx method.",
+			Globals.LogLevel.DEBUG
+		)