wuira 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ with the release date and highlight breaking changes explicitly.
 
 ## Unreleased
 
+## 0.3.0 — 2026-10-17
+
+### Breaking
+
+- The package root exports only the addon shell: `Wuira`, `wuira`, `WuiraApp`, `AddonSettings`, `Encoding`, `Store`, and `StoreRegistry`.
+- Import widgets, including `UI`, `HoverTracker`, and `unitPortrait`, from `wuira/ui`.
+- Import `BlizzardUI` and `ActionBars` from `wuira/platform`.
+- Import `Nameplates` and `MicroBar` from `wuira/skins`. Spell and icon enums stay on `wuira/spells` and `wuira/icons`.
+
+### Added
+
+- `unitPortrait` mounts a unit portrait and a protected target/menu button without coupling resource widgets to that button.
+
+## 0.2.8 — 2026-10-17
+
+### Fixed
+
+- `UnitSource("target").onChange` invalidates on `PLAYER_TARGET_CHANGED`, including
+  combat and target removal, without reading secret identities or notifying other
+  unit sources. Event subscriptions stop with the last consumer.
+- Add `onTokenChange` for secure consumers that should only rewrite bindings after
+  an explicit `Retarget`, not when a stable target address points to another unit.
+
 ## 0.2.7 — 2026-10-16
 
 ### Added

package/README.md

@@ -7,7 +7,8 @@ Build WoW Forever interfaces with TypeScript and JSX.
 wuira is a UI framework and addon toolchain for developers who want to describe interfaces in code, compose reusable components, and keep game data separate from presentation. Write TypeScript, arrange native widgets with JSX, and compile your addon to Lua.
 
 ```tsx
-import { UI, wuira } from "wuira";
+import { wuira } from "wuira";
+import { UI } from "wuira/ui";
 
 function ResourceBar({ current }: { current: number }) {
     return <progress width="inherit" height={24} min={0} max={100} current={current} />;
@@ -79,7 +80,8 @@ Supported action types: `spell`, `item`, `macro`, `action`, and `target`. Action
 ## Nameplates
 
 ```tsx
-import { Nameplates, UI } from "wuira";
+import { UI } from "wuira/ui";
+import { Nameplates } from "wuira/skins";
 import { HP } from "wuira/datasources";
 
 const plates = Nameplates
@@ -141,6 +143,8 @@ For global installation, use `npm install -g wuira`. To test unpublished changes
 
 wuira is an early framework. It is not a complete UI replacement, an in-game visual editor, or a WeakAuras replacement. JSX describes widgets; there is no React runtime or automatic reactive rendering layer. Combat restrictions and secret-value rules still apply and cannot be bypassed by the framework.
 
+Import widgets from `wuira/ui` (including `unitPortrait`), native adapters from `wuira/skins`, and `BlizzardUI` / `ActionBars` from `wuira/platform`. The package root is the addon shell.
+
 Current core includes Cells, layouts, progress bars, decorations, unit sources, native nameplate adapters, and project tooling. Not yet implemented: a complete WoW API surface, nameplate click-cast abstractions, and preset management. Nameplate lifecycle tests use a mock Lua runtime; real-client validation is still required.
 
 The target client is WoW Forever. Compatibility with Retail or other Classic clients is not promised without verification.

package/docs/icons.md

@@ -3,7 +3,7 @@
 `Icons` contains native texture **FileDataIDs** from the same verified Forever build as the spell enums. Icon identity is independent of spell or item actions.
 
 ```ts
-import { UI } from "wuira";
+import { UI } from "wuira/ui";
 import { Icons } from "wuira/icons";
 import { Icon } from "wuira/ui";
 

package/docs/nameplates.md

@@ -1,6 +1,6 @@
 # Nameplates
 
-Import `Nameplates` from `wuira` or `wuira/skins`. Wuira owns native access,
+Import `Nameplates` from `wuira/skins`. Wuira owns native access,
 events, unit bindings and visual cleanup. Preset selection, NPC rules, editor
 data and component collections belong to the consuming addon (for example LumaUI).
 No class or mob presets are built into Wuira.

package/lib/datasources/UnitSource.d.ts

@@ -20,11 +20,16 @@ export declare class UnitSource extends DataSource<UnitIdentity | undefined> {
     readonly Is: UnitPredicates;
     private restricted;
     private readonly listeners;
+    private readonly tokenListeners;
+    private events?;
     constructor(token: string);
     get Token(): string;
     /** Keep source objects/subscriptions while a stable identity moves to another unit slot. */
     Retarget(token: string): void;
+    /** Secure consumers only need notification when the actual unit address changes. */
+    onTokenChange(listener: () => void): () => void;
     onChange(listener: () => void): () => void;
+    private UpdateEvents;
     protected HasSecretFields(): boolean;
     protected GetValue(): UnitIdentity | undefined;
 }

package/lib/datasources/UnitSource.lua

@@ -506,32 +506,76 @@ function UnitSource.prototype.____constructor(self, token)
     self.token = token
     self.restricted = false
     self.listeners = __TS__New(Set)
+    self.tokenListeners = __TS__New(Set)
     self.Is = __TS__New(
         ____exports.UnitPredicates,
         function() return self.Token end
     )
 end
 function UnitSource.prototype.Retarget(self, token)
+    if issecretvalue(token) or type(token) ~= "string" or __TS__StringTrim(token) == "" then
+        error("UnitSource: expected a public unit token")
+    end
     if token == self.token then
         return
     end
     if InCombatLockdown() then
         error("UnitSource: retarget after combat so secure actions and displayed data stay aligned")
     end
-    if issecretvalue(token) or type(token) ~= "string" or __TS__StringTrim(token) == "" then
-        error("UnitSource: expected a public unit token")
-    end
     self.token = token
+    self:UpdateEvents()
+    for ____, listener in __TS__Iterator(self.tokenListeners) do
+        listener(nil)
+    end
     for ____, listener in __TS__Iterator(self.listeners) do
         listener(nil)
     end
 end
+function UnitSource.prototype.onTokenChange(self, listener)
+    self.tokenListeners:add(listener)
+    return function()
+        self.tokenListeners:delete(listener)
+    end
+end
 function UnitSource.prototype.onChange(self, listener)
     self.listeners:add(listener)
+    self:UpdateEvents()
     return function()
         self.listeners:delete(listener)
+        self:UpdateEvents()
     end
 end
+function UnitSource.prototype.UpdateEvents(self)
+    local ____opt_2 = self.events
+    if ____opt_2 ~= nil then
+        ____opt_2:UnregisterAllEvents()
+    end
+    if self.listeners.size == 0 or self.token ~= "target" then
+        local ____opt_4 = self.events
+        if ____opt_4 ~= nil then
+            ____opt_4:SetScript("OnEvent", nil)
+        end
+        local ____opt_6 = self.events
+        if ____opt_6 ~= nil then
+            ____opt_6:Hide()
+        end
+        self.events = nil
+        return
+    end
+    if self.events == nil then
+        self.events = CreateFrame("Frame", nil, UIParent)
+    end
+    local frame = self.events
+    frame:RegisterEvent("PLAYER_TARGET_CHANGED")
+    frame:SetScript(
+        "OnEvent",
+        function()
+            for ____, listener in __TS__Iterator(self.listeners) do
+                listener(nil)
+            end
+        end
+    )
+end
 function UnitSource.prototype.HasSecretFields(self)
     return self.restricted
 end

package/lib/index.d.ts

@@ -5,20 +5,5 @@ export { WuiraApp } from "./WuiraApp";
 export type { CommandCallback } from "./platform/SlashCommands";
 export { AddonSettings } from "./platform/AddonSettings";
 export { Encoding } from "./platform/Encoding";
-export { DruidSpells, GeneralSpells, HunterSpells, MageSpells, PaladinSpells, PetSpells, PriestSpells, ProfessionSpells, RacialSpells, RogueSpells, ShamanSpells, WarlockSpells, WarriorSpells, WorldSpells, BindingActions, } from "./spells/index";
-export { Icons } from "./icons/index";
-export { BlizzardUI } from "./platform/BlizzardUI";
-export { ActionBars } from "./platform/ActionBars";
-export type { ActionSlot, EmptyActionBarsOptions } from "./platform/ActionBars";
-export type { BlizzardUIOptions } from "./platform/BlizzardUI";
-export type { MicroMenuSkinOptions } from "./platform/MicroMenu";
-export { UI } from "./ui/primitives/jsx";
-export { HoverTracker } from "./ui/HoverTracker";
-export type { HoverTrackerOptions, HoverFrame } from "./ui/HoverTracker";
-export { MicroBar } from "./skins/MicroBar";
-export { Nameplates, NameplateRules, NameplateContext } from "./skins/Nameplates";
-export type { NameplateInfo, NameplateSelector, NameplateCustomize, NameplateRender, NativeNameplate, NativeNameplateVisual } from "./skins/Nameplates";
-export type { Element, Component } from "./ui/primitives/jsx";
-export type { Cell } from "./ui/Cell";
 export { Store, StoreRegistry } from "./store/index";
 export type { StoreClass, ReadonlyData, SavedStoreOptions } from "./store/index";

package/lib/index.lua

@@ -18,32 +18,6 @@ do
     local ____Encoding = require("platform.Encoding")
     ____exports.Encoding = ____Encoding.Encoding
 end
-do
-    local ____BlizzardUI = require("platform.BlizzardUI")
-    ____exports.BlizzardUI = ____BlizzardUI.BlizzardUI
-end
-do
-    local ____ActionBars = require("platform.ActionBars")
-    ____exports.ActionBars = ____ActionBars.ActionBars
-end
-do
-    local ____jsx = require("ui.primitives.jsx")
-    ____exports.UI = ____jsx.UI
-end
-do
-    local ____HoverTracker = require("ui.HoverTracker")
-    ____exports.HoverTracker = ____HoverTracker.HoverTracker
-end
-do
-    local ____MicroBar = require("skins.MicroBar")
-    ____exports.MicroBar = ____MicroBar.MicroBar
-end
-do
-    local ____Nameplates = require("skins.Nameplates")
-    ____exports.Nameplates = ____Nameplates.Nameplates
-    ____exports.NameplateRules = ____Nameplates.NameplateRules
-    ____exports.NameplateContext = ____Nameplates.NameplateContext
-end
 do
     local ____index = require("store.index")
     ____exports.Store = ____index.Store

package/lib/platform/index.d.ts

@@ -0,0 +1,5 @@
+export { BlizzardUI } from "./BlizzardUI";
+export type { BlizzardUIOptions } from "./BlizzardUI";
+export { ActionBars } from "./ActionBars";
+export type { ActionSlot, EmptyActionBarsOptions } from "./ActionBars";
+export type { MicroMenuSkinOptions } from "./MicroMenu";

package/lib/platform/index.lua

@@ -0,0 +1,11 @@
+--[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]
+local ____exports = {}
+do
+    local ____BlizzardUI = require("platform.BlizzardUI")
+    ____exports.BlizzardUI = ____BlizzardUI.BlizzardUI
+end
+do
+    local ____ActionBars = require("platform.ActionBars")
+    ____exports.ActionBars = ____ActionBars.ActionBars
+end
+return ____exports

package/lib/ui/UnitPortrait.d.ts

@@ -0,0 +1,3 @@
+import type { UnitInput } from "../datasources/UnitSource";
+import type { CellProps } from "./Cell";
+export declare function unitPortrait(props: Partial<CellProps>, input: UnitInput, crop?: readonly number[], preview?: boolean): import("./primitives/jsx").Element;

package/lib/ui/UnitPortrait.lua

@@ -0,0 +1,233 @@
+--[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]
+-- Lua Library inline imports
+local function __TS__StringTrim(self)
+    local result = string.gsub(self, "^[%s ]*(.-)[%s ]*$", "%1")
+    return result
+end
+
+local function __TS__StringIncludes(self, searchString, position)
+    if not position then
+        position = 1
+    else
+        position = position + 1
+    end
+    local index = string.find(self, searchString, position, true)
+    return index ~= nil
+end
+
+local function __TS__ObjectAssign(target, ...)
+    local sources = {...}
+    for i = 1, #sources do
+        local source = sources[i]
+        if type(source) == "table" then
+            for key in pairs(source) do
+                target[key] = source[key]
+            end
+        end
+    end
+    return target
+end
+-- End of Lua Library inline imports
+local ____exports = {}
+local ____UnitSource = require("datasources.UnitSource")
+local resolveUnit = ____UnitSource.resolveUnit
+local ____jsx = require("ui.primitives.jsx")
+local UI = ____jsx.UI
+function ____exports.unitPortrait(self, props, input, crop, preview)
+    if preview == nil then
+        preview = false
+    end
+    if issecretvalue(input) or type(input) == "string" and __TS__StringTrim(input) == "" then
+        error("Unit portrait requires a public unit token", 0)
+    end
+    local target = resolveUnit(nil, input)
+    return UI:createElement(
+        "cell",
+        __TS__ObjectAssign(
+            {},
+            props,
+            {
+                clickThrough = true,
+                onMount = function(____, frame)
+                    local host = frame
+                    local ____preview_0
+                    if preview then
+                        ____preview_0 = nil
+                    else
+                        ____preview_0 = CreateFrame("Button", nil, UIParent, "SecureActionButtonTemplate")
+                    end
+                    local button = ____preview_0
+                    local owner = button or host
+                    local texture = owner:CreateTexture(nil, "OVERLAY")
+                    texture:SetAllPoints(owner)
+                    local buttonUnit = target.Token
+                    local stopUnit
+                    local stopped = false
+                    local stopping = false
+                    local elapsed = 0
+                    local lastX
+                    local lastY
+                    local lastWidth
+                    local lastHeight
+                    local lastStrata
+                    local lastLevel
+                    local lastAlpha
+                    local function draw()
+                        if stopped or stopping then
+                            return
+                        end
+                        SetPortraitTexture(texture, target.Token, true)
+                        local uv = crop or ({0, 1, 0, 1})
+                        texture:SetTexCoord(uv[1], uv[2], uv[3], uv[4])
+                    end
+                    local function cleanup()
+                        if stopped then
+                            return
+                        end
+                        stopped = true
+                        if stopUnit ~= nil then
+                            stopUnit(nil)
+                        end
+                        stopUnit = nil
+                        host:SetScript("OnUpdate", nil)
+                        owner:UnregisterAllEvents()
+                        owner:SetScript("OnEvent", nil)
+                        if button ~= nil then
+                            button:SetAttribute("type1", nil)
+                            button:SetAttribute("type2", nil)
+                            button:EnableMouse(false)
+                            button:Hide()
+                        end
+                    end
+                    local function sync()
+                        if button == nil or stopped or stopping or InCombatLockdown() then
+                            return
+                        end
+                        if buttonUnit ~= target.Token then
+                            button:SetAttribute("unit", target.Token)
+                            buttonUnit = target.Token
+                        end
+                        if not host:IsVisible() then
+                            if button:IsShown() then
+                                button:Hide()
+                            end
+                            return
+                        end
+                        local x, y = host:GetCenter()
+                        if x == nil or y == nil then
+                            return
+                        end
+                        local scale = host:GetEffectiveScale() / UIParent:GetEffectiveScale()
+                        local width = host:GetWidth() * scale
+                        local height = host:GetHeight() * scale
+                        local cx = x * scale
+                        local cy = y * scale
+                        if cx ~= lastX or cy ~= lastY or width ~= lastWidth or height ~= lastHeight then
+                            button:ClearAllPoints()
+                            button:SetPoint(
+                                "CENTER",
+                                UIParent,
+                                "BOTTOMLEFT",
+                                cx,
+                                cy
+                            )
+                            button:SetSize(width, height)
+                            lastX = cx
+                            lastY = cy
+                            lastWidth = width
+                            lastHeight = height
+                        end
+                        local strata = host:GetFrameStrata()
+                        local level = host:GetFrameLevel() + 2
+                        local alpha = host:GetEffectiveAlpha()
+                        if strata ~= lastStrata then
+                            button:SetFrameStrata(strata)
+                            lastStrata = strata
+                        end
+                        if level ~= lastLevel then
+                            button:SetFrameLevel(level)
+                            lastLevel = level
+                        end
+                        if alpha ~= lastAlpha then
+                            button:SetAlpha(alpha)
+                            lastAlpha = alpha
+                        end
+                        if not button:IsShown() then
+                            button:Show()
+                        end
+                    end
+                    do
+                        local function ____catch(failure)
+                            cleanup(nil)
+                            error(failure, 0)
+                        end
+                        local ____try, ____hasReturned = pcall(function()
+                            if button ~= nil then
+                                button:RegisterForClicks("LeftButtonUp", "RightButtonUp")
+                                button:SetID(0)
+                                button:SetAttribute("useOnKeyDown", false)
+                                button:SetAttribute("unit", target.Token)
+                                button:SetAttribute("type1", "target")
+                                button:SetAttribute("type2", "togglemenu")
+                                button:EnableMouse(true)
+                                host:SetScript(
+                                    "OnUpdate",
+                                    function(_frame, delta)
+                                        elapsed = elapsed + delta
+                                        if elapsed >= 0.05 then
+                                            elapsed = 0
+                                            sync(nil)
+                                        end
+                                    end
+                                )
+                                host:HookScript("OnShow", sync)
+                                host:HookScript("OnHide", sync)
+                                owner:RegisterEvent("PLAYER_REGEN_ENABLED")
+                            end
+                            for ____, event in ipairs({"UNIT_PORTRAIT_UPDATE", "UNIT_MODEL_CHANGED", "PORTRAITS_UPDATED", "PLAYER_ENTERING_WORLD"}) do
+                                owner:RegisterEvent(event)
+                            end
+                            if __TS__StringIncludes(target.Token, "target") then
+                                owner:RegisterEvent("PLAYER_TARGET_CHANGED")
+                            end
+                            if __TS__StringIncludes(target.Token, "focus") then
+                                owner:RegisterEvent("PLAYER_FOCUS_CHANGED")
+                            end
+                            owner:SetScript(
+                                "OnEvent",
+                                function(_frame, event, eventUnit)
+                                    if event == "PLAYER_REGEN_ENABLED" then
+                                        if stopping then
+                                            cleanup(nil)
+                                        else
+                                            sync(nil)
+                                        end
+                                    elseif event ~= "UNIT_PORTRAIT_UPDATE" and event ~= "UNIT_MODEL_CHANGED" or eventUnit == target.Token then
+                                        draw(nil)
+                                    end
+                                end
+                            )
+                            stopUnit = target:onTokenChange(function()
+                                draw(nil)
+                                sync(nil)
+                            end)
+                            draw(nil)
+                            sync(nil)
+                        end)
+                        if not ____try then
+                            ____catch(____hasReturned)
+                        end
+                    end
+                    return function()
+                        stopping = true
+                        if button ~= nil and InCombatLockdown() then
+                            return
+                        end
+                        cleanup(nil)
+                    end
+                end
+            }
+        )
+    )
+end
+return ____exports

package/lib/ui/index.d.ts

@@ -30,3 +30,4 @@ export { Label } from "./Label";
 export type { LabelProps } from "./Label";
 export { Icon } from "./Icon";
 export type { IconProps } from "./Icon";
+export { unitPortrait } from "./UnitPortrait";

package/lib/ui/index.lua

@@ -80,4 +80,8 @@ do
     local ____Icon = require("ui.Icon")
     ____exports.Icon = ____Icon.Icon
 end
+do
+    local ____UnitPortrait = require("ui.UnitPortrait")
+    ____exports.unitPortrait = ____UnitPortrait.unitPortrait
+end
 return ____exports

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "git+https://github.com/KerimCETINBAS/wuira.git"
   },
-  "version": "0.2.7",
+  "version": "0.3.0",
   "author": {
     "name": "Kerim Cetinbas",
     "email": "a.cetinbas@icloud.com"
@@ -32,6 +32,10 @@
       "types": "./lib/skins/index.d.ts",
       "default": "./lib/skins/index.lua"
     },
+    "./platform": {
+      "types": "./lib/platform/index.d.ts",
+      "default": "./lib/platform/index.lua"
+    },
     "./spells": {
       "types": "./lib/spells/index.d.ts",
       "default": "./lib/spells/index.lua"
@@ -66,6 +70,9 @@
       "skins": [
         "lib/skins/index.d.ts"
       ],
+      "platform": [
+        "lib/platform/index.d.ts"
+      ],
       "spells": [
         "lib/spells/index.d.ts"
       ],