ample/AmpleWin/Agent.md

Agent Task Audit Log - Ample Windows Port

📅 Session: 2026-06-05 (Session 16)

🎯 Objective: PowerBook Compatibility Fallback & Downloader Acceleration

Addressed upstream MAME 0.288 C++ late-binding bug causing crashes on EASC audio chip Macs, and accelerated the VGM Mod download.

✅ Key Achievements:

1. EASC Crash Fallback Mechanism:
   • Added automatic detection for affected PowerBook models (macpb160, macpb180, macpb165, macpb165c, macpb180c).
   • Implements seamless redirect to mame_0287.exe or mame-vgm.exe (v0.280) if present in the executable folder.
   • Provides user warning with options to auto-download MAME v0.280 (VGM Mod) fallback, force launch under 0.288, or cancel.
2. Downloader Optimization:
   • Switched VGM Mod download mirror to prioritize mirror.ghproxy.com GitHub proxy for faster global asset retrieval.
3. ROM Manager Priority Check:
   • Reordered ROM base URLs to prioritize mdk.cab over callapple.org. This guarantees the latest split set ROMs (like dragon32 with split files) are downloaded correctly, solving the missing files crash on MAME 0.288+.

---

📅 Session: 2026-05-19 (Session 15)

🎯 Objective: Complete Slot Configuration Persistence (MAME Command Line)

Resolved the issue where selecting "None" for a slot in the UI didn't actually disable the device in MAME because empty slot arguments were being omitted from the command line.

✅ Key Achievements:

1. Command-Line Slot Persistence:
   • Modified build_args in mame_launcher.py to allow empty string values (e.g. option is not None instead of if option:).
   • This ensures that -[slot_name] "" is explicitly passed on the command line, preventing MAME from falling back to its internal defaults.
2. Parity: Checked and verified this behavior across both AmpleWin and AmpleLinux ports, ensuring slots explicitly set to "None" are truly disabled when the emulator launches.

---

📅 Session: 2026-05-11 (Session 14)

🎯 Objective: Slot Configuration Consistency Fix

Resolved an issue where slots with defaults could not be set to "None" because UI refreshes would revert them.

✅ Key Achievements:

1. "None-Aware" Slot Initialization:
   • Modified initialize_default_slots to use slot_name not in self.current_slots.
   • Ensured manual "None" selections are preserved while maintaining automated defaults for new card insertion.
2. Upstream Compatibility: Prepared codebase for PR back to original source, ensuring robust slot behavior.

---

📅 Session: 2026-03-02 (Session 13)

🎯 Objective: Upstream Version Bump & Documentation Maintenance

Focused on updating the project to track MAME 0.286 and simplifying documentation maintainability.

✅ Key Achievements:

1. Version Bump: Updated mame_downloader.py to point to the latest MAME 0.286 x64 Windows binary.
2. Documentation Refactoring:
   • Renamed version-specific screenshot files (e.g. screenshot-v0.28x.png to screenshot.png) across all platforms.
   • Updated README.md and README_tw.md to use generic "latest version" terminology to prevent the need for manual text updates upon future MAME releases.

🚀 Current Project Status

The Windows Port is functionally tracking MAME 0.286 and documentation is now future-proofed against minor version increments.

---

📅 Session: 2026-02-16 (Session 12)

🎯 Objective: Linux Port Spinoff

AmpleWin has successfully served as the foundation for a new Linux port.

✅ Key Achievements:

1. Port Creation:
   • AmpleLinux: Created AmpleLinux/ directory based on the AmpleWin codebase.
   • Shared DNA: data_manager.py and rom_manager.py remain identical, while main.py was adapted for Linux (xdg-open, paths, dependencies).
   • Cross-Reference: Added links to AmpleLinux in the README.

🚀 Current Project Status

The project now supports both Windows (AmpleWin) and Linux (AmpleLinux) natively.

---

📅 Session: 2026-02-09 (Session 11)

🎯 Objective: Upstream Synchronization & Codebase Hygiene

Focused on synchronizing the project with the latest upstream changes from ksherlock/ample, ensuring the roms.plist database is compliant with the official repository, and cleaning up diverging local branches.

✅ Key Achievements:

1. Full Upstream Sync:

   • Repository Alignment: Merged latest upstream/master changes (4 new commits), bringing in the official fix for PowerBook Duo 280 (macpd280) and new definitions like Epson RX-80 (epson_rx80).
   • Deforking roms.plist: Discarded local custom modifications to Ample/Resources/roms.plist. The file is now byte-for-byte identical to the upstream version, ensuring long-term maintainability.
   • Branch Cleanup: Removed the stale fix-missing-roms branch and closed the associated PR #44, as the upstream author has implemented the necessary fixes natively.

2. AmpleWin Verification:

   • Compatibility Verified: Confirmed that AmpleWin correctly parses the new upstream roms.plist without errors.
   • ROM Status: Validated that macpd280 is now natively supported for auto-download via the new upstream definitions. Note: Custom definitions for Pravetz and TK3000 are no longer in roms.plist but remain playable if ROMs are manually provided.

3. Deployment & Distribution:

   • Refactor: Renamed mame_bin to mame across the codebase for better standards compliance.
   • Portable EXE: Created build_exe.bat using PyInstaller (OneDir) to package the application into a standalone executable.
   • Path Logic: Updated main.py with robust sys.frozen detection to ensure resources and downloads work correctly in both Dev and Frozen environments.
   • Documentation: Added build instructions to READMEs.

🚀 Current Project Status

The codebase is now in a "Clean Slate" state. master is fully synced with upstream, with AmpleWin serving as a strictly additive extension.

📅 Session: 2026-02-02 (Session 10)

🎯 Objective: ROM Library Expansion & Advanced Slot Emulation

Focused on expanding the supported ROM library, implementing a robust failover download mechanism, and perfecting nested slot configuration logic for SCSI peripherals.

✅ Key Achievements:

1. ROM Library & Search Expansion:

   • New System Support: Added missing ROM definitions for Macintosh PowerBook Duo 280/280c, Pravetz 8C, and TK3000 //e.
   • Search Parity: Fully synchronized hardware definitions with the latest macOS release, including secondary Pravetz models (82, 8M).

2. Robust ROM Download Failover:

   • Prioritized Multi-Server Support: Implemented a transparent failover mechanism in rom_manager.py. The downloader now prioritizes callapple.org for maximum stability and automatically falls back to mdk.cab for Apple II clones and split sets unreachable on the primary server.
   • Status Integrity: Fixed a bug in the download progress counter to ensure accurate success/failure reporting in the UI.

3. Advanced Slot & Media Emulation:

   • SCSI Sub-Peripheral Detection: Rewrote aggregate_media to recursively detect devices attached to slot cards (e.g., finding the CD-ROM and Hard Disk on an Apple IIgs SCSI card).
   • Nested Slot Defaults: Implemented automatic initialization for sub-slots. Plugging in a SCSI card now automatically populates its sub-slots with default devices (CD-ROM at ID 1, Hard Disk at ID 6), matching Mac parity.
   • Sub-Slot UI Parity: Updated the "Hamburger" popup to show all configurable sub-slots, not just those with media, giving users full control over complex hardware chains.
   • Aggregator Optimization: Refined the media scanner to ignore the global "device library" at the root level, preventing UI clutter and double-counting of unmapped drives.

🚀 Current Project Status

The Windows Port now offers superior hardware configuration capabilities. Complex SCSI and SmartPort chains are handled automatically, and the ROM acquisition system is more reliable than ever.

📅 Session: 2026-02-02 (Session 9)

🎯 Objective: Upstream Synchronization & Feature Parity (MAME 0.286)

Focused on synchronizing with the upstream Ample (macOS) v0.286 release, updating the core emulator backend, and implementing new UI search capabilities.

✅ Key Achievements:

1. Upstream Repository Synchronization:

   • Merge & Push: Successfully merged latest commits from upstream/master (ksherlock/ample).
   • Resource Alignment: Synchronized latest hardware definitions and slot configurations from original project.
   • A2retroNET Integration: Inherited support for a2retronet hardware, enabling up to 8 SmartPort disk images.

2. MAME Core Update:

   • Version Upgrade: Updated mame_downloader.py to point to the official MAME 0.286 Windows x64 binary.
   • Download Engine Parity: Users can now auto-download the latest MAME core directly from the Settings menu.

3. ROM Manager Enhancements:

   • Search Filter: Implemented a real-time search field in the RomManagerDialog header (matching macOS feature parity).
   • Filtering Logic: Updated refresh_list to filter ROMs by description or shortcode, allowing users to quickly find specific system firmwares.

🚀 Current Project Status

The Windows Port is now fully synchronized with Ample (macOS) v0.286 resources. It supports the latest MAME core and offers improved ROM management tools.

---

📅 Session: 2026-01-24 (Session 8)

🎯 Objective: Path robustness & UI Interactivity

Focused on fixing "No such file" errors when launching custom ROM paths and improving the user experience for file selection in secondary tabs.

✅ Key Achievements:

1. Command Line Robustness:

   • Quote Handling: Patched the shlex logic in main.py to handle Windows paths correctly. Manually stripping outer quotes ensures subprocess doesn't double-escape them, fixing the critical "No such file or directory" error when launching files with spaces in their path.

2. File Selection UX:

   • A/V Path Selectors: Implemented mousePressEvent on the A/V tab input fields (AVI, WAV, VGM). Clicking these text boxes now opens a native QFileDialog ("Save As") with appropriate extension filters, saving users from manual typing.
   • Path Normalization: Updated the "Shared Directory" directory selector to automatically normalize paths (e.g., converting / to \), ensuring visual consistency and compatibility with Windows command line expectations.

🚀 Current Project Status

The application is now highly resilient to typical Windows path complexities. Users can easily select output destinations and shared folders without worrying about path syntax errors.

---

📅 Session: 2026-01-22 (Session 7)

🎯 Objective: User Freedom & flexible Command Control

Focused on giving the user complete control over the MAME launch command and ensuring a cleaner default state for machine slots.

✅ Key Achievements:

1. Editable Command Console:

   • Unlocked Preview: The "Command Preview" text box is no longer read-only.
   • Source of Truth: The Launch button now executes exactly what is typed in this box. Users can manually add, remove, or edit arguments (e.g., adding -verbose or removing unwanted flags) before launching.

2. Launch Engine Integrity:

   • Absolute Path Resolution: Implemented shlex parsing to read the user's manual command string. It automatically detects the command (mame or mame-vgm) and resolves it to the absolute system path to fix [WinError 2] on Windows.
   • VGM Pathing: Logic retains awareness of VGM Mod capabilities even when launching from a custom text string.

3. Cleaner Default State:

   • Slot Neutrality: Removed the aggressive fallback logic that forced the first available option for slots without a default value.
   • Phantom Args Clarified: This eliminates confusing arguments like -fdc:0 525 appearing automatically, ensuring MAME starts with its internal defaults unless the local configuration explicitly overrides them.

🚀 Current Project Status

The app now respects "Power User" workflows. You can use the UI for quick setup, then fine-tune the command line manually. The codebase structure is being finalized.

---

📅 Session: 2026-01-21 (Session 6)

🎯 Objective: VGM Mod Stability & Extraction Safety

Focused on fixing critical bugs in the VGM recording workflow, ensuring extraction safety, and improving UI feedback for the modded binary.

✅ Key Achievements:

1. VGM Mod Extraction Safety:

   • Anti-Overwrite Workflow: Implemented a temporary directory strategy (_vgm_temp) during VGM Mod extraction. This ensures that the mod's mame.exe (v0.280) never accidentally overwrites the main official mame.exe (v0.284).
   • Atomic Renaming: The modded binary is now safely extracted, renamed to mame-vgm.exe, and moved to the destination in a single, non-destructive step.

2. Command Line & UI Parity:

   • Explicit Recording Toggle: Fixed a bug where -vgmwrite 1 was missing from the console launch command. Recording is now correctly activated when using the modded binary.
   • Dynamic UI Preview: The 4-line console preview now correctly displays mame-vgm as the target executable when VGM recording is enabled and the mod is detected, matching actual runtime behavior.

3. Thread & Lifecycle Stability:

   • Remove Safety: Fixed a ValueError: list.remove(x): x not in list in the worker cleanup logic, ensuring the thread-safe management of background tasks even if signals fire twice.
   • Worker Refactoring: Rewrote the VgmModDownloadWorker and VgmPostProcessWorker logic to handle edge cases in file movement and process termination more gracefully.

4. Shared Directory & UI Refinement:

   • Logic Completion: Fixed a missing link in the launch engine where the "Shared Directory" path from the UI wasn't being passed to the actual MAME process.
   • Standardized Argument: Updated from -share to the official -share_directory for maximum compatibility.
   • UI Bugfix: Removed duplicate "Paths" tab initialization in the main window.
   • Click-to-Browse: Implemented a pop-up directory selector when clicking the Shared Directory path box, replacing manual entry.

5. Smart Slot Validation (Mac Parity):

   • Disabled State Support: Ported the disabled logic from the Mac version. Slot options that are technically defined but marked as unsupported in the plist (e.g., specific SCSI cards on Apple IIgs) are now visually grayed out and unselectable in the dropdown menu.
   • Prevention: Prevents users from accidentally selecting incompatible hardware configurations that would cause MAME to crash or behave unexpectedly.

🚀 Current Project Status

The VGM and Shared Directory workflows are now "Production Ready." The UI has reached a high level of fidelity with the Mac original, including subtle behaviors like smart slot validation and intuitive path selection.

---

📅 Session: 2026-01-21 (Session 5)

🎯 Objective: MAME Core Logic & Command Line Robustness

Focused on improving the reliability of the MAME launch engine, specifically regarding dynamic slot media (CFFA2), multi-drive support, and shell-safe command construction.

✅ Key Achievements:

1. Relaxed Parameter Validation:

   • Dynamic Media Parity: Removed strict listmedia validation in MameLauncher to allow secondary media types (like hard1, hard2) that only appear when a specific card (e.g., CFFA2) is plugged in.
   • Internal Filter: Implemented logic to automatically skip internal MAME node names starting with a colon (e.g., -:prn) to prevent "unknown option" errors.

2. Multi-Drive & Storage Support:

   • Capping Removal: Fixed a self-imposed limitation in main.py that forced hard, cdrom, and cassette counts to 1.
   • CFFA2 Ready: AmpleWin now correctly supports machines/cards with multiple hard drives (-hard1, -hard2).

3. Shell Integrity & Quoting:

   • Robust Quoting: Integrated subprocess.list2cmdline for both the UI Command Preview and the actual process execution.
   • Space Handling: Guaranteed that file paths containing spaces are automatically wrapped in quotes (""), preventing launch failures on Windows.
   • Path Normalization: Implemented os.path.normpath for all MAME arguments (-hard, -rompath, etc.), ensuring consistent Windows-style backslashes (\).
   • Command Line Streamlining: Automated mame.ini generation via mame -cc upon MAME detection. This allows removing redundant path arguments (-hashpath, -artpath, etc.) from the command line, resulting in a much cleaner and more readable preview.
   • VGM Support (Advanced): Since modern MAME removed VGM support, AmpleWin implements a robust background workflow to download and configure the MAME-VGM Mod (v0.280). It uses a non-destructive extraction process (mame-vgm.exe) to preserve your main MAME core while restoring high-fidelity music recording, and automatically moves the resulting .vgm files to the user's desired path upon MAME exit.

4. Resolution Scaling & Visual Parity:

   • Window Mode Scaling: Implemented -resolution generation for scaling modes (2x, 3x, 4x) and -nomax for Window 1x mode to ensure consistent default sizing.
   • Aspect Ratio Heuristic: Integrated a 4:3 correction heuristic for non-square pixel machines (e.g., Apple II: 560x192 -> 1120x840 at 2x) to match macOS Ample behavior.
   • Square Pixel Mode: Implemented integer scaling for Apple II machines (e.g., 1120x768 at 2x) while adding -nounevenstretch to prevent pixel shimmering and maintain clarity.
   • UI Expansion: Added "Window 4x" option to the Video settings tab.
   • Disk Sound Effects Integration: Linked the "Disk Sound Effects" checkbox to the -nosamples argument, allowing MAME samples to load when sound effects are enabled.
   • CPU Speed & Throttle UI Alignment: Merged the Throttle checkbox into the CPU Speed dropdown as a "No Throttle" option, perfectly matching the original macOS Ample interface and logic.

5. BGFX Effect Synchronization:

   • Enhanced Effects List: Updated the video effects selection to support a standardized set of BGFX screen chains: Unfiltered, HLSL, CRT Geometry, CRT Geometry Deluxe, LCD Grid, and Fighters.
   • Chain Mapping: Implemented precise mapping between UI selection and MAME's -bgfx_screen_chains internal identifiers.

🚀 Current Project Status

The MAME launch engine is now significantly more robust and "intelligent." It handles complex slot configurations and multi-disk setups like CFFA2 without manual parameter tweaking, while maintaining a clean, error-free command line preview.

---

📅 Session: 2026-01-19 (Session 4)

🎯 Objective: Real-time Adaptive Theming & UI Resilience

Focused on implementing a native Windows theme detection engine and ensuring 100% visibility/aesthetic parity across both Light and Dark modes without requiring application restarts. Refined the command console for long parameter strings.

✅ Key Achievements:

1. Adaptive Theme Engine:

   • Registry-Level Detection: Implemented winreg polling to detect AppsUseLightTheme changes in real-time.
   • Live Synchronization: Added a 2-second polling timer (QTimer) that triggers a global UI restyle, allowing the app to switch between Light and Dark modes on-the-fly.
   • Cross-Window Propagation: Ensured theme changes flow correctly into child dialogs (ROM Manager) and dynamic overlays (Software Search, Sub-slot popups).

2. UI Polish & Visibility Fixes:

   • Light Mode "Ghosting" Elimination: Fixed unreadable text by moving critical UI colors (Slot Labels, Media Headers) from hardcoded Python strings to the global adaptive stylesheet.
   • Themed Popups: Rewrote SoftwarePopup and sub-slot bubble painting to dynamically adjust background colors and "triangle" indicators based on the system theme.
   • ROM Manager Parity: Fully themed the ROM download dialog, ensuring status labels (found/missing) maintain high contrast in both modes.

3. Command Console Expansion:

   • Multi-line Preview: Replaced the single-line QLineEdit with a 4-line QTextEdit console footer.
   • Parameter Visibility: This allows users to review the entire MAME command line, including long software list paths and slot configurations, without horizontal scrolling.

4. Stability & Bug Squashing:

   • ROM Manager Reliability: Corrected @Slot decorators and converted the dialog to .exec() (Modal) to prevent interaction conflicts.
   • Logic Errors: Fixed several NameError bugs in the rendering engine and addressed stylesheet inheritance issues that caused transparent list views.

5. Visual Documentation & Networking Guide:

   • README Screenshots: Embedded screenshot-v0.284.png in READMEs to match original aesthetics.
   • Networking Parity Section: Added a specialized section in READMEs explaining Npcap requirements for Uthernet II simulation, clarifying that the macOS "Fix Permissions" is unnecessary on Windows.

🚀 Current Project Status

The Windows Port is now a "State-of-the-Art" adaptive application. It feels native on both Light and Dark Windows setups, offers robust command line verification, and maintains the premium "Apple-inspired" aesthetic consistently.

---

📅 Session: 2026-01-19 (Session 3)

🎯 Objective: Documentation Standardization & UI Finalization

This session focused on finalizing the project's documentation (internationalization), organizing the file structure to stay clean relative to the upstream repository, and refining the primary toolbar functions.

✅ Key Achievements:

1. Documentation Internationalization:

   • Dual-Language Support: Created README.md (English) and README_tw.md (Traditional Chinese) in the AmpleWin directory.
   • Mutual Linking: Implemented language-switching headers in both README files for a professional GitHub experience.
   • Parity Verification: Deep-dived into original macOS Objective-C source code to ensure the comparison table is 100% accurate regarding ROM downloading, bookmarked machine persistence, and technical differences.

2. UI Finalization & Utility Tools:

   • Ample Dir Integration: Renamed "Disk Images" to "📂 Ample Dir". It now acts as a shortcut to open the application directory in Windows Explorer.
   • Redirected Help: Linked the "📖 Help" button directly to the official project GitHub sub-folder for instant user support.

3. Project Structure Hygiene:

   • Namespace Isolation: Relocated all Windows-specific overhead files (README_tw.md, AmpleWin.bat, requirements.txt, Agent.md) into the AmpleWin subdirectory.
   • Upstream Integrity: Restored the root directory to its original state, ensuring a clean "1 commit ahead" status for easy upstream maintenance.
   • Script Resilience: Updated AmpleWin.bat to handle the new directory structure, allowing execution directly from within the AmpleWin folder.

🚀 Current Project Status

The Windows Port is now a "ready-to-ship" localized product. The documentation is verified against the original Mac source code, the UI buttons serve practical Windows-specific needs, and the project stays respectful to the original repository's file structure.

---

📅 Session: 2026-01-18 (Session 2)

🎯 Objective: Deployment, Performance & Path Robustness

This session focused on making the application portable, optimizing the download engine for "instant" ROM acquisition, and improving the first-run user experience with guided setup.

✅ Key Achievements:

1. Deployment & Portability:

   • Auto-Launcher: Created ample_win.bat to automate dependency installation and app execution.
   • Dynamic Paths: Replaced hardcoded absolute paths with a robust search algorithm that detects the Ample/Resources folder relative to the script location.
   • Environment Isolation: Forced MAME working directory to mame_bin, ensuring nvram, cfg, and diff folders stay within the emulator directory and out of the project root.

2. Explosive Download Engine:

   • Threading Mastery: Transitioned to QThreadPool for manageable concurrency.
   • Performance Leap: Increased parallel download threads from 1 to 50.
   • Small File Optimization: For ROM files (<64KB), switched from streaming to direct requests.content I/O, resulting in near-instant mass downloads.
   • Anti-Throttling: Added browser-masking User-Agent headers.

3. User Experience (UX):

   • Startup Wizard: Implemented sequential logic: Check MAME -> Guided Download -> Check ROMs -> Guided Download.
   • Sticky Software (Smart Carry-over):
     • Selections and filters now persist across compatible machines.
     • Compatibility Logic: Automatically clears selection if the new machine doesn't support the current software list.
     • Full Name Display: The search box now displays the full, descriptive software name instead of the short MAME ID.
     • UI Cleanliness: Software lists stay collapsed during machine switches for a sleeker look.
   • Windows 10 Fixes: Applied global CSS overrides for QMessageBox and QDialog to fix unreadable grey-on-white text issues on Windows 10.

4. Project Hygiene:

   • Updated .gitignore to exclude MAME runtime artifacts (nvram/, cfg/, sta/, etc.).
   • Updated README_win.md with the new one-click launch instructions.

🚀 Current Project Status

Ample Windows is now highly portable and user-friendly. The download system is exceptionally fast, and the environment stays clean during emulation sessions.

📅 Session: 2026-01-18 (Session 1)

🎯 Objective: Software List Integration & Final UI Polish

This session focused on implementing the MAME Software List feature and refining the UI to achieve 100% aesthetic parity with the macOS version, including functional improvements to the MAME launch engine for Windows.

✅ Key Achievements:

1. Software List Feature:

   • XML Parsing: Enhanced DataManager to parse MAME's hash/*.xml files.
   • Intelligent Discovery: Implemented a search-based software browser with autocomplete-style show/hide logic.
   • Auto-Detection: Integrated software list selection into the MAME launch command with optimized argument ordering.

2. MAME Launch Engine:

   • Argument Ordering: Fixed Windows-specific software list resolution issues by placing software list items immediately after the machine name.
   • Path Isolation: Standardized -hashpath, -bgfx_path, and -rompath to be relative to the application's mame_bin directory.
   • Resource Management: Centralized ROM storage to mame_bin\roms.

3. UI Aesthetic Refinement:

   • Apple Launch Button: Replicated the Mac-style 🍎 icon inside the Launch button with left-aligned icon and right-aligned text.
   • Full-Width Console: Moved the Command Preview to a full-width footer with a console-style (black background, monospace) styling.
   • Clean Mode: Removed "Use Samples" checkbox and hardcoded -nosamples for authenticity.
   • Proportional Layout: Expanded the options area to comfortably display long software names (60+ characters).

4. Stability & Initialization:

   • Graceful Shutdown: Improved thread termination logic in closeEvent.
   • Safe Initialization: Fixed attribute and name errors in DataManager and AmpleMainWindow during early startup phases.

🚀 Current Project Status

The Windows Port is now functionally on par with the original Mac version, including the Software List feature. The UI is pixel-perfect and the launch engine is robust against common Windows path and argument pitfalls.

---

Handover Notes for Future Agents

1. UI Implementation Strategy (CRITICAL)

• Custom Combo Boxes: Do NOT attempt to use native QComboBox::down-arrow CSS for the blue ↕ icon. Windows Qt has rendering issues (white dots/flicker). We use a stacked overlay strategy:
  • A QWidget container holds the QComboBox.
  • A QLabel with Qt.WA_TransparentForMouseEvents is positioned on top of the combo's right edge.
  • This label has an opaque background (#3b7ee1) to mask the native Windows combo indicator dots.
• Alignment: The global fixed width for slot combos is 160px. The arrow overlay is 20px wide.

2. Adaptive Theming

• Real-time Detection: The app polls the Windows Registry every 2 seconds for theme changes.
• Centralized CSS: Most UI colors are defined in apply_premium_theme using Python f-strings, allowing instant restyling of all common widgets.
• Persistent IDs: Labels and special widgets use setObjectName to inherit styles from the global stylesheet, avoiding contrast issues during theme transitions.

3. State Management

• Sub-Slot Popups: Tracked via self.active_popup in AmpleMainWindow.
• Toggle Logic: Uses time.time() threshold (0.3s) and id(data) check in show_sub_slots() to prevent the "immediate reopening" bug when clicking the hamburger button to close the popup.

4. Data Processing

• data_manager.py handles the heavy lifting of parsing original Ample .plist files.
• Slot changes trigger self.refresh_ui(), which rebuilds the dynamic slots layout from scratch to handle nested slot dependencies.

5. Known Mantras

• Visual Parity is King: Every margin, font size (mostly 11px/12px), and color was cross-referenced with macOS high-res screenshots.
• Authorship: This Windows Port is a collaboration between anomixer and Antigravity.