Party Portraits Unit Frame/Buff Reminder Bar

Zomar's Party Portraits Bar - Changelog
=====================================================

v4.5 (Phase 5.3 – Totem Combat-Safety, Cluster Stability & Icon Persistence)
---------------------------------------------------------------------------
- Fixed [ADDON_ACTION_BLOCKED] Button:ClearAllPoints() taint in combat:
    • All layout-changing logic now routed through a combat-safe reanchor queue.
    • Anchor changes attempted during combat are deferred until PLAYER_REGEN_ENABLED.
    • Prevents Blizzard protected-call violations when totems update mid-combat.

- Cluster layout stability improvements:
    • Added layout-locking during combat to stop icons from shifting, shrinking, or reanchoring.
    • Ensures 2×2 grid remains perfectly aligned beside the portrait under all combat conditions.
    • Improved cell spacing and top-right/top-left fill order consistency.

- Fake test icon improvements (/pptotems test):
    • Fake totem icons no longer vanish when combat starts.
    • Test mode now fully isolated from live totem events.
    • Fake icons remain visible until /pptotems clear is used.
    • Allows accurate alignment testing without needing a Shaman or Druid present.

- Layout switching polish (horizontal / vertical / cluster):
    • Fixed lingering anchors when switching between layout modes.
    • Ensured uniform spacing and offsets across all layouts.
    • Holder frame is now auto-created when needed before layout or test mode.

- Global combat-protection system for Totem module:
    • All anchor updates, size changes, and frame clearing flow through CombatSafeRun().
    • Zero taint during totem expiration, replacement, testing, or mode switching.
    • Guarantees full compatibility with secure Blizzard UI behavior.

- Developer & debug improvements:
    • Added clear debug messages for deferred operations.
    • Added confirmation messages when deferred operations apply post-combat.
    • Simplified internal tracking for testing state, active icons, layouts, and pending reanchors.

v4.4 (Phase 5.2 – Portrait & Bar Border Visual Overhaul)
---------------------------------------------------------
- New dual-border system around portraits:
    • Outer ring: thicker, highly visible class-colored border for fast class identification.
    • Inner ring: thin Blizzard-style metallic ring for clean portrait framing.
    • Layered cleanly above portrait textures without interfering with overlays or icons.

- Matching class-themed borders for health & resource bars:
    • Bars now use Blizzard-style rectangular borders similar to Quickslot UI elements.
    • Outer border uses class color; inner trim uses polished metallic shading.
    • Aligns visually with the dual portrait border for a unified style.

- Enhanced class-color readability:
    • Increased saturation and clarity of class-colored outer border.
    • Tuned values to avoid neon look while remaining clear in peripheral vision.
    • Offline/dead/ghost portrait states remain readable with full border color.

- Bar alignment and spacing improvements:
    • Adjusted vertical offsets to prevent bar overlap with portrait rings.
    • Ensured consistent spacing between portrait, internal ring, and beneath bar group.
    • Cleaned up anchor logic to avoid rare bar “nudging” during UI reloads.

- Technical improvements:
    • Consolidated all border creation into a shared border-helper function.
    • Borders are created once per frame and persist for performance and stability.
    • Verified compatibility across Overlay, Beneath, Above, combat/resting icons, and secure click-cast layers.

v4.3 (Phase 5.1 – Totem Cluster Integration + Developer Test Mode)
- Introduced full Totem module expansion and refinement:
    • Added compact 2×2 “Cluster” layout (default) for player totem, mushroom, or statue tracking.
        - Layout fills top-right first for balanced alignment beside the portrait.
        - Grid pattern: [ICON3][ICON1]
                        [ICON4][ICON2]
    • Added persistent layout selection and state saving across sessions.
    • Integrated seamlessly with player portrait frame on the left-hand side.

- Expanded `/pptotems` command set:
    • `/pptotems horizontal` – Classic row layout (icons flow right→left beside portrait).
    • `/pptotems vertical`   – Column layout (icons stack top→bottom beside portrait).
    • `/pptotems cluster`    – 2×2 cube layout (default).
    • `/pptotems`            – Prints current layout and help command list.
    • `/pptotems test`       – Spawns four fake totem icons using the current layout for alignment testing.
    • `/pptotems clear`      – Hides fake icons created in test mode.
    • Persistent `ICON_SPACING` value ensures visual consistency across all modes.

- New `/pp` module commands:
    • `/pp totems on`  – Enables the Totem module (shows totem icons beside portrait).
    • `/pp totems off` – Disables the Totem module (hides icons immediately).

- Quality of life improvements:
    • Added safe state flag preventing test icons from being auto-cleared by normal updates.
    • Default module state is now enabled for all new users.
    • Proper cleanup logic when toggled off to prevent lingering icons.
    • Test mode icons remain visible until cleared manually.
    • Fully compatible with Blizzard totem events and Druid/Mage/Monk single-slot equivalents.

- Developer utilities:
    • Added internal flag for testing mode (`testing = true`) for visual debugging.
    • Integrated safety check to auto-create the holder frame if `/pptotems test` is used before attachment.
    • Fully combat-safe, no protected function taint.

- Marks the beginning of Phase 5.1 enhancements focused on modular add-on developer tools and layout flexibility.

v4.2 (Phase 5.0 – Player Resting & Combat Icon Integration)
- Introduced dedicated player-only state icon system, mirroring Blizzard’s default behavior:
    • Displays Resting icon when in an inn/city (replaces level text and ring).
    • Displays Combat icon when in combat (replaces level text and ring).
    • Automatically restores level indicator when neither state is active.
- Added independent topmost overlay frame to render icons above all UI layers:
    • FrameStrata set to DIALOG to ensure visibility over health bars and portrait rings.
    • Overlay dynamically follows the player’s level ring position each frame.
- Implemented secure, event-driven listener for:
    • PLAYER_UPDATE_RESTING
    • PLAYER_REGEN_DISABLED
    • PLAYER_REGEN_ENABLED
    • PLAYER_ENTERING_WORLD
- Optimized performance:
    • Listener permanently attached to player frame to prevent garbage collection.
    • Event-based updates only; no polling or excessive OnUpdate work.
- Added debug output for event tracing (optional; commented by default).
- Fully compatible with Overlay, Beneath, and Above modules.
- Verified complete combat safety (no protected function taint).
- Visual polish:
    • Icon size scaled to 30×30.
    • Precise offset tuning for alignment above health bar borders.
- Marks the beginning of Phase 5 foundation updates (v5.0).

v4.1b (Phase 4.1b – Overlay Target Restore Hotfix)
- Fixed issue where left-click targeting stopped working after toggling Overlay Off (Portrait Mode) until reload:
    • Corrected attribute assignment to `frame.__pp_button` (secure click layer) instead of parent frame.
    • Targeting is now immediately restored after `/pp over off` toggle.
    • Deferred rebinding logic added for safe restoration after combat (`PLAYER_REGEN_ENABLED`).
- Maintains full combat-safety compliance with secure templates.
- Verified no interaction issues between Portrait Mode and Overlay Mode toggles.
- Included required media folder in upload(oops)

v4.1 (Phase 4.1 – Final Pre-Config Polish)
- Added combat-safe guard for `EnableMouse()` calls to prevent rare `[ADDON_ACTION_BLOCKED]` taint:
    • Patched gear button mouse-enable logic with `InCombatLockdown()` check (line ~223, PartyPortraits.lua).
    • Prevents protected function errors when party members die or disconnect during combat.
- Added Phase 5 placeholder comment block for future buff-equivalence groups:
    • Example pair: Mark of the Wild (1126) ↔ Legacy of the Emperor (115921).
    • No behavioral change yet—serves as documentation for next-phase user-configurable system.
- Verified overlay stability, click-casting responsiveness, and hover logic unchanged from 4.0.
- Minor documentation and internal comment cleanup.

v4.0 (Phase 4.0 – Core Rebuild + Expanded Systems)
- Complete internal rewrite of PartyPortraits architecture for modularity, maintainability, and security.
- Introduced four logical layers:
    • **PartyPortraits.lua** – Core foundation (anchor frames, saved variables, slash commands).
    • **PartyPortraits_Overlay.lua** – Buff reminder overlay and click-casting layer.
    • **PartyPortraits_Beneath.lua** – Health & resource bar module (under-portrait bars).
    • **PartyPortraits_Above.lua** – Debuff indicator and role icon overlay system.
- Restored and stabilized **left-click casting** behavior:
    • Now functions in both Portrait Mode and Overlay Mode.
    • Secure click attributes set dynamically; re-applied safely after combat lockdown.
- Added **health and mana/resource bars** beneath each portrait:
    • Displays accurate current HP/resource for all visible party members.
    • Bars update smoothly via OnUpdate interval loop (default 0.5s).
    • Fully compatible with locked/unlocked state, solo mode, and overlay toggle.
- Added **new visual layer above portraits** for debuffs, role icons, and custom indicators:
    • Compact 13px grid (3 columns × 5 rows) with Y-offset lift above ring.
    • Tooltip hover support and debug overlays for development.
    • Planned future use for crowd control and role display.
- Added **Slash Command Expansion**:
    • `/pp overlay on/off` – Toggle buff reminder overlays.
    • `/pp beneath on/off` – Toggle health/resource bar module.
    • `/pp roles on/off/debug` – Toggle and debug role icon overlays.
    • `/pp reset`, `/pp lock`, `/pp unlock`, `/pp hide`, `/pp show` retained.
- Implemented **robust SavedVariable defaults** and persistence for all module states:
    • OverlayEnabled, BeneathEnabled, ShowWhenSolo, Locked, AnchorPoint, and coordinates.
    • Automatic seeding of missing keys to prevent nil errors after patch updates.
- Introduced **secure toggle management**:
    • All protected calls (`EnableMouse`, `SetAttribute`, `Show`, `Hide`) now wrapped or deferred during combat.
    • Deferred queue automatically executes on `PLAYER_REGEN_ENABLED`.
- Added **debug utilities**:
    • `/pp roles debug` cycles through role icon display (HEALER, TANK, DAMAGER, NONE) even without party.
    • Tooltip overlay for above-layer icons aids in layout verification.
- Improved **visual and performance polish**:
    • Class-colored rings preserved with additive blending.
    • Smooth alpha fade and glow overlay updates.
    • Y-offset adjustments for better readability of icons above and beneath portraits.
    • Reduced redundant OnUpdate calls; single timer drives all visual updates.
- Introduced **internal debug mode** (`debugMode = false` toggle) for advanced testing.
- Established **modular namespace** structure:
    • `ns.Above`, `ns.Beneath`, `ns.Overlay`, and `ns.DB` tables safely separated.
    • Prevents cross-file pollution and allows optional file loading.
- Prepared groundwork for **Phase 5 – Config System Overhaul**:
    • Placeholder comments in Overlay for user-selectable spells.
    • Planned equivalence group support and in-game configuration UI (PartyPortraits_Config.lua).

v3.7
- Added full support for Monk – Legacy of the Emperor (115921).
- Monk portraits now correctly display overlay icons, glow effects, and click-casting.
- Overlay and click-cast logic fully class-complete across six buffing classes.

v3.6
- Fixed rare C stack overflow errors caused by recursive EnableMouse() calls.
- Hover and gear logic completely refactored for performance and combat safety:
    • Gear buttons remain mouse-enabled at all times; hidden via alpha instead of mouse toggles.
    • Overlay hover hooks now attach once per frame (prevents handler duplication).
- Secure attribute changes (spell/unit) are deferred during combat and safely applied on PLAYER_REGEN_ENABLED.
- Removed protected function calls that caused [ADDON_ACTION_BLOCKED] taint in dungeons/raids.
- Fixed tooltip stability and eliminated UNKNOWN() taint trigger when hovering during combat.
- Optimized visual update loop (0.5s interval) for smoother refresh and reduced CPU use.

v3.5
- Added automatic gear visibility sync between Portraits Mode and Overlay Mode.
- Gear icon and tooltip now hidden entirely when Overlay Mode is disabled.
- Fixed logic so re-enabling Overlay Mode (/pp overlay on) restores gear hover functionality.
- Corrected ghost tooltip issue when logging in with Overlay disabled.
- Improved fade-out timing and tooltip anchoring for natural hover feel.

v3.4
- Introduced distinct operating modes:
    • Portraits Mode (overlay disabled)
    • Overlay Mode (buff reminders enabled)
- Added internal safety wrapper (SafeEnableMouse) to prevent recursive mouse toggling.
- Updated slash commands to explicitly toggle between Portraits and Overlay modes.
- Integrated gear-icon right-click context menu (secure Blizzard menu).
- Gear icon now hidden in Portraits Mode; visible in Overlay Mode only.
- Added red lock indicator during combat (gear temporarily disabled for right-clicks).
- Re-organized code for maintainability and security compliance.

v3.3
- Gear icon now appears on portrait hover and remains functional under overlay.
- Tooltip displays class-colored name + “Right-click: Unit Menu” in gold.
- Fixed gear disappearance when hovering directly over the icon.
- Corrected erroneous gear visibility on empty portrait slots.
- Added fallback hover logic when overlay is disabled on login.

v3.2
- Fixed right-click context menu interference with overlay frames.
- Added secure gear button as dedicated right-click target.
- Refined hover states to support overlay or portrait layers safely.
- Integrated tooltips and frame highlight support.
- Improved unit existence checks and event updates.

v3.1
- Structural cleanup of overlay–foundation communication.
- Improved layering and frame level management for portrait + overlay.
- Added safe frame updates in combat using pending queues.

v3.0
- Foundation rebuild with overlay integration.
- Introduced full modular split (PartyPortraits.lua + PartyPortraits_Overlay.lua).
- Added secure click-casting system.
- Added faint anchor background for unlock mode.
- Added stored anchor position + proper restore/reset logic.
- Overlays show based on range and buff status.
- Offline indicator bolt added.
- All frames now created with Secure templates (no taint).

v2.1
- Fixed Lua [ADDON_ACTION_BLOCKED] error occurring in instances during combat.
- Click casting now works properly during combat.

v2.0
- Added slash commands:
        /pp            - List usage
        /pp reset      - Reset position to default
        /pp lock       - Lock frames
        /pp unlock     - Unlock frames
        /pp hide       - Hide when solo
        /pp show       - Show when solo
        /pp off        - Disable addon
        /pp on         - Enable addon
- Polished visuals: desaturate icon before coloring orange or blue.
- Added buff reminder system for 5 classes:
    [21562]  - Power Word: Fortitude (Priest)
    [1126]   - Mark of the Wild (Druid)
    [1459]   - Arcane Brilliance (Mage)
    [19740]  - Blessing of Might (Paladin)
    [109773] - Dark Intent (Warlock)

v1.9
- Added version headers to Lua files for clarity.
- Buff reminder overlays now allow click-casting the configured spell directly on party members.
- Corrected range check to use actual spell range instead of interact distance.
- Removed grey spell overlay for disconnected/dead units (portraits + bolt used instead).
- Fixed .toc to remove README.txt reference (syntax safety).
- Updated README.txt with documentation details.

v1.8
- Added Blizzard-style overlay glow for buff reminders when in range.
- Introduced PartyPortraits_Overlay.lua as separate module.
- Added configurable spell ID for buff overlays.

v1.7
- Restored square portrait rings.
- Finalized locked/unlocked states with faint blue anchor background.
- Added /pportraits hide and /pportraits show with persistence.
- Class rings preserved for disconnected players.
- Added offline bolt indicator.
- Reset restores default position and locks by default.
- Default reset position: center (Y offset 318).

v1.6
- Enlarged red disconnect bolt overlay (1.95x portrait size).
- Cleaned up debug code.

v1.5
- Added offline handling:
  * Portrait desaturates when disconnected.
  * Red disconnect bolt overlay appears.
- Retained class-colored rings.

v1.4
- Added /pportraits hide and /pportraits show commands (persistent).

v1.3
- Reset now defaults to locked state.
- Unlock state shows faint blue background.

v1.2
- Added initial offline portrait handling.

v1.1
- Added slash commands:
  * /pportraits reset
  * /pportraits lock
  * /pportraits unlock

v1.0
- Initial release:
  * Movable portraits for player + party1–party4.
  * Class-colored ring borders.
  * Saved position across sessions.