feat(items): port retail shared cooldown overlays

Preserve public shared-cooldown metadata, resolve the authoritative cooldown enchantment with retail expiry semantics, and project the exact ten DAT-authored radial steps through the shared retained item-slot architecture.

Co-authored-by: Codex <codex@openai.com>

src/AcDream.App/UI/Layout/ItemCooldownAssets.cs

@@ -0,0 +1,56 @@
+using AcDream.Content;
+using DatReaderWriter;
+
+namespace AcDream.App.UI.Layout;
+
+/// <summary>
+/// DAT-authored ten-step radial cooldown art owned by the shared retail
+/// <c>UIElement_UIItem</c> prototype.
+/// </summary>
+public readonly record struct ItemCooldownAssets(IReadOnlyList<uint> Sprites)
+{
+    public const uint CatalogLayoutId = 0x21000037u;
+    public const uint SharedItemPrototypeId = 0x1000033Eu;
+    public const uint FirstOverlayElementId = 0x1000054Fu;
+    public const int OverlayCount = 10;
+
+    public static ItemCooldownAssets? TryLoad(IDatReaderWriter dats)
+    {
+        ArgumentNullException.ThrowIfNull(dats);
+        // 0x1000033E is the common UIItem base inherited by physical item,
+        // container, and shortcut prototypes. The empty-slot prototype
+        // 0x10000341 is only background art and intentionally has no cooldown
+        // children.
+        ElementInfo? prototype = LayoutImporter.ImportInfos(
+            dats,
+            CatalogLayoutId,
+            SharedItemPrototypeId);
+        if (prototype is null)
+            return null;
+
+        var sprites = new uint[OverlayCount];
+        for (int index = 0; index < sprites.Length; index++)
+        {
+            ElementInfo? overlay = Find(
+                prototype,
+                FirstOverlayElementId + (uint)index);
+            if (overlay is null
+                || !overlay.StateMedia.TryGetValue("", out var media)
+                || media.File == 0u)
+                return null;
+            sprites[index] = media.File;
+        }
+
+        return new ItemCooldownAssets(sprites);
+    }
+
+    private static ElementInfo? Find(ElementInfo root, uint id)
+    {
+        if (root.Id == id)
+            return root;
+        foreach (ElementInfo child in root.Children)
+            if (Find(child, id) is { } match)
+                return match;
+        return null;
+    }
+}

src/AcDream.App/UI/Layout/ItemCooldownUiController.cs

@@ -0,0 +1,101 @@
+using AcDream.Core.Items;
+using AcDream.Core.Spells;
+
+namespace AcDream.App.UI.Layout;
+
+/// <summary>
+/// Shared retained-UI owner for retail item cooldowns. It performs the retail
+/// heartbeat before drawing and gives every current and future
+/// <see cref="UiItemSlot"/> the same display projection.
+/// </summary>
+public sealed class ItemCooldownUiController
+{
+    private readonly Spellbook _spellbook;
+    private readonly ClientObjectTable _objects;
+    private readonly Func<double> _currentTime;
+    private readonly List<UiItemList> _lists = new();
+    private readonly Dictionary<uint, int> _stepByItemId = new();
+
+    private ItemCooldownUiController(
+        Spellbook spellbook,
+        ClientObjectTable objects,
+        Func<double> currentTime)
+    {
+        _spellbook = spellbook;
+        _objects = objects;
+        _currentTime = currentTime;
+    }
+
+    public static ItemCooldownUiController Bind(
+        UiElement root,
+        Spellbook spellbook,
+        ClientObjectTable objects,
+        Func<double> currentTime,
+        ItemCooldownAssets assets)
+    {
+        ArgumentNullException.ThrowIfNull(root);
+        ArgumentNullException.ThrowIfNull(spellbook);
+        ArgumentNullException.ThrowIfNull(objects);
+        ArgumentNullException.ThrowIfNull(currentTime);
+
+        var controller = new ItemCooldownUiController(
+            spellbook,
+            objects,
+            currentTime);
+        controller.Configure(root, assets.Sprites);
+        controller.Tick();
+        return controller;
+    }
+
+    public void Tick()
+    {
+        double now = _currentTime();
+        _stepByItemId.Clear();
+
+        // Retail updates cooldown visibility from UIElement_UIItem::DoHeartbeat,
+        // not while drawing. Query each represented item once so an expired
+        // registry node can be removed safely before the render walk.
+        foreach (UiItemList list in _lists)
+        {
+            for (int index = 0; index < list.GetNumUIItems(); index++)
+            {
+                UiItemSlot? cell = list.GetItem(index);
+                if (cell is null)
+                    continue;
+                uint itemId = cell.ItemId;
+                if (itemId == 0u || _stepByItemId.ContainsKey(itemId))
+                    continue;
+
+                int step = 0;
+                ClientObject? item = _objects.Get(itemId);
+                if (item?.CooldownId is { } cooldownId
+                    && item.CooldownDuration is { } duration
+                    && _spellbook.OnCooldown(
+                        cooldownId,
+                        now,
+                        out double remaining))
+                    step = ItemCooldownDisplay.GetOverlayStep(
+                        duration,
+                        remaining);
+
+                _stepByItemId.Add(itemId, step);
+            }
+        }
+    }
+
+    internal int GetOverlayStep(uint itemId)
+        => _stepByItemId.TryGetValue(itemId, out int step) ? step : 0;
+
+    private void Configure(UiElement element, IReadOnlyList<uint> sprites)
+    {
+        if (element is UiItemList list)
+        {
+            _lists.Add(list);
+            list.CooldownSprites = sprites;
+            list.CooldownStepProvider = GetOverlayStep;
+        }
+
+        foreach (UiElement child in element.Children)
+            Configure(child, sprites);
+    }
+}

src/AcDream.App/UI/RetailUiRuntime.cs

@@ -198,6 +198,7 @@ public sealed class RetailUiRuntime : IDisposable
     private RetailItemConfirmationController? _itemConfirmationController;
     private RetailSkillTrainingConfirmationController? _skillTrainingConfirmationController;
     private UiShortcutDigitGraphics? _shortcutDigitGraphics;
+    private ItemCooldownUiController? _itemCooldownController;
     private VividTargetIndicatorController? _vividTargetIndicator;
     private ResourceShutdownTransaction? _shutdown;
     private bool _disposed;
@@ -242,6 +243,7 @@ public sealed class RetailUiRuntime : IDisposable
         MountPlugins();
         MountInventory();
         MountExternalContainer();
+        MountItemCooldowns();
         Host.WindowManager.WindowVisibilityChanged += OnWindowVisibilityChanged;
         BindToolbarPanelButtons();
         SyncToolbarWindowButtons();
@@ -346,6 +348,7 @@ public sealed class RetailUiRuntime : IDisposable
         JumpPowerbarController?.Tick();
         SelectedObjectController?.Tick(deltaSeconds);
         ExternalContainerController?.Tick();
+        _itemCooldownController?.Tick();
         DialogFactory?.Tick();
         Host.Tick(deltaSeconds);
         _automation?.Tick(deltaSeconds);
@@ -1760,6 +1763,29 @@ public sealed class RetailUiRuntime : IDisposable
             "[D.2b] retail external-container strip mounted from LayoutDesc 0x21000008.");
     }
 
+    private void MountItemCooldowns()
+    {
+        ItemCooldownAssets? assets;
+        lock (_bindings.Assets.DatLock)
+            assets = ItemCooldownAssets.TryLoad(_bindings.Assets.Dats);
+
+        if (assets is null)
+        {
+            Console.WriteLine(
+                "[UI] shared UIItem cooldown overlays missing from LayoutDesc 0x21000037.");
+            return;
+        }
+
+        _itemCooldownController = ItemCooldownUiController.Bind(
+            Host.Root,
+            _bindings.Magic.Spellbook,
+            _bindings.Magic.Objects,
+            _bindings.Magic.ServerTime,
+            assets.Value);
+        Console.WriteLine(
+            "[UI] retail shared item cooldown overlays ready (10 DAT-authored steps).");
+    }
+
     public void Dispose()
     {
         if (_disposed)

src/AcDream.App/UI/UiItemList.cs

@@ -39,6 +39,30 @@ public sealed class UiItemList : UiElement
 
     public Func<uint, (uint tex, int w, int h)>? SpriteResolve { get; set; }
 
+    private IReadOnlyList<uint>? _cooldownSprites;
+    public IReadOnlyList<uint>? CooldownSprites
+    {
+        get => _cooldownSprites;
+        set
+        {
+            _cooldownSprites = value;
+            foreach (UiItemSlot cell in _cells)
+                cell.CooldownSprites = value;
+        }
+    }
+
+    private Func<uint, int>? _cooldownStepProvider;
+    public Func<uint, int>? CooldownStepProvider
+    {
+        get => _cooldownStepProvider;
+        set
+        {
+            _cooldownStepProvider = value;
+            foreach (UiItemSlot cell in _cells)
+                cell.CooldownStepProvider = value;
+        }
+    }
+
     /// <summary>
     /// Optional non-weenie catalog drop target. Used by retail spell shortcuts;
     /// physical-item drops continue through <see cref="DragHandler"/>.
@@ -92,6 +116,8 @@ public sealed class UiItemList : UiElement
     public void AddItem(UiItemSlot cell)
     {
         cell.SpriteResolve ??= SpriteResolve;
+        cell.CooldownSprites ??= _cooldownSprites;
+        cell.CooldownStepProvider ??= _cooldownStepProvider;
         if (_cellEmptySprite != 0) cell.EmptySprite = _cellEmptySprite;
         // The list lays cells out procedurally (grid offset + scroll clip), so cells must be
         // EXEMPT from the parent anchor pass — UiElement.DrawSelfAndChildren runs ApplyAnchor
@@ -271,6 +297,8 @@ public sealed class UiItemList : UiElement
         {
             UiItemSlot cell = EmptySlotFactory?.Invoke() ?? new UiItemSlot();
             cell.SpriteResolve ??= SpriteResolve;
+            cell.CooldownSprites ??= _cooldownSprites;
+            cell.CooldownStepProvider ??= _cooldownStepProvider;
             if (_cellEmptySprite != 0) cell.EmptySprite = _cellEmptySprite;
             cell.Anchors = AnchorEdges.None;
             _cells.Add(cell);

src/AcDream.App/UI/UiItemSlot.cs

@@ -103,6 +103,18 @@ public class UiItemSlot : UiElement
     /// <summary>RenderSurface id -> (GL texture, w, h). Set by the factory/controller.</summary>
     public Func<uint, (uint tex, int w, int h)>? SpriteResolve { get; set; }
 
+    /// <summary>
+    /// DAT-authored 10%..100% radial cooldown overlays from element ids
+    /// <c>0x1000054F..0x10000558</c>.
+    /// </summary>
+    public IReadOnlyList<uint>? CooldownSprites { get; set; }
+
+    /// <summary>
+    /// Bound by the shared cooldown controller. Returns 0 for hidden or 1..10
+    /// for the exact retail overlay step.
+    /// </summary>
+    public Func<uint, int>? CooldownStepProvider { get; set; }
+
     public void SetItem(
         uint itemId,
         uint iconTexture,
@@ -387,6 +399,28 @@ public class UiItemSlot : UiElement
                     ctx.DrawSprite(tex, 0f, 0f, Width, Height, 0f, 0f, 1f, 1f, Vector4.One);
             }
         }
+
+        // UIElement_UIItem::UpdateCooldownDisplay @ 0x004E1E20 selects exactly
+        // one of ten authored radial overlays. The shared prototype gives these
+        // children ReadOrder 8, above shortcut, waiting, selection, trade, and
+        // drag-accept layers, so the countdown is the final UIItem draw.
+        uint cooldownSprite = ActiveCooldownSprite();
+        if (cooldownSprite != 0u && SpriteResolve is not null)
+        {
+            var (texture, _, _) = SpriteResolve(cooldownSprite);
+            if (texture != 0u)
+                ctx.DrawSprite(
+                    texture,
+                    0f,
+                    0f,
+                    Width,
+                    Height,
+                    0f,
+                    0f,
+                    1f,
+                    1f,
+                    Vector4.One);
+        }
     }
 
     /// <summary>Draws the shared retail shortcut-number layer. Catalog spell cells
@@ -409,4 +443,17 @@ public class UiItemSlot : UiElement
         if (texture != 0)
             ctx.DrawSprite(texture, 0f, 0f, Width, Height, 0f, 0f, 1f, 1f, Vector4.One);
     }
+
+    internal uint ActiveCooldownSprite()
+    {
+        if (ItemId == 0u
+            || CooldownSprites is null
+            || CooldownStepProvider is null)
+            return 0u;
+
+        int step = CooldownStepProvider(ItemId);
+        return step is >= 1 and <= 10 && step <= CooldownSprites.Count
+            ? CooldownSprites[step - 1]
+            : 0u;
+    }
 }