wuira 0.2.6 → 0.2.7

package/CHANGELOG.md

@@ -7,6 +7,22 @@ with the release date and highlight breaking changes explicitly.
 
 ## Unreleased
 
+## 0.2.7 — 2026-10-16
+
+### Added
+
+- Generic `Nameplates.Apply` / `Replace` registration groups, with global first-match
+  precedence, fresh per-unit JSX factories, reversible native visual helpers,
+  event-driven pooled-frame lifecycle, explicit refresh, and independent disposal.
+  Forbidden/protected frames and secret identities are skipped; secure JSX is rejected.
+- Lua integration coverage for nameplate reuse, rule conflicts, rollback, native
+  restoration and HP subscription cleanup. These are mock tests, not in-game validation.
+
+### Fixed
+
+- Continue unmount cleanup after a binding or decoration disposer throws, so remaining
+  subscriptions and frames are released before the first error is reported.
+
 ## 0.2.6 — 2026-10-16
 
 ### Changed

package/README.md

@@ -76,6 +76,29 @@ Other sources include `AuraTimer`, `GlobalCooldown`, `CastTimer`, `SpellCooldown
 
 Supported action types: `spell`, `item`, `macro`, `action`, and `target`. Actions and units are static mount-time attributes. Protected trees cannot be mounted during combat.
 
+## Nameplates
+
+```tsx
+import { Nameplates, UI } from "wuira";
+import { HP } from "wuira/datasources";
+
+const plates = Nameplates
+    .Apply(p => p.GUID === configuredGUID, p => {
+        if (p.Native.healthBar) p.Size(p.Native.healthBar, 140, 12);
+    })
+    .Replace(() => true, p => (
+        <progress width={140} height={12} source={new HP(p.Unit)} />
+    ));
+
+// plates.Dispose();
+```
+
+The first matching rule wins across Apply and Replace; they do not stack.
+Each factory creates fresh JSX for its unit. Use `Nameplates.Create()` with
+`collection.forEach(...)` to register presets, and `Refresh()` after preset changes.
+See [nameplate lifecycle and cleanup](docs/nameplates.md). Secure nameplate controls
+require a separate lifecycle and are not supported by this visual API.
+
 ## Stores
 
 ```ts
@@ -118,7 +141,7 @@ 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.
 
-Current core includes Cells, flow and grid layouts, progress bars, decorations, health and mana sources, a local console polyfill, and project tooling. Not yet implemented: a complete WoW API surface, click-cast abstractions, nameplate adapters, and preset management.
+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/nameplates.md

@@ -0,0 +1,89 @@
+# Nameplates
+
+Import `Nameplates` from `wuira` or `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.
+
+`NativeSkin` remains the adapter for fixed named frames. Nameplates use a separate
+event-driven manager because both carriers and unit visuals are dynamically pooled.
+
+## Rules and ownership
+
+`Nameplates.Apply(selector, customize)` and `Nameplates.Replace(selector, render)`
+start independent groups. Chained calls append to that same group. `Nameplates.Create()`
+starts an empty group, useful for collections:
+
+```tsx
+const plates = Nameplates.Create();
+collection.forEach(component => {
+    plates.Replace(p => component.matches(p.Unit, p.GUID), p => component.render(p));
+});
+// When preset data changes:
+plates.Refresh();
+// On addon feature shutdown:
+plates.Dispose();
+```
+
+Rules are ordered by registration time across all groups. **The first matching
+rule wins, regardless of whether it is Apply or Replace.** Apply rules do not
+accumulate before/after a replacement. Put specific rules before fallbacks.
+Disposing a losing group leaves the winning binding intact. Disposing a winning
+group restores its changes and then activates the next matching rule, if any.
+Dispose is idempotent; adding rules to a disposed group is an error.
+
+Selectors receive `Unit`, public `GUID`, engine-owned `Frame`, and native visual
+`Native` (with optional `healthBar` / `castBar`). Restricted identities/frames
+never reach selectors. A selector error or secret result leaves the plate native;
+it does not activate a less specific fallback. Callback errors go to WoW's error
+handler. A failing winner is retried on refresh or the next relevant native event.
+Callbacks must not add/dispose/refresh groups while reconciliation is running.
+
+## Apply
+
+Apply reuses Blizzard's visuals and bars. The context exposes reversible
+`Alpha(frame, value)`, `Scale(frame, value)`, `Size(frame, width, height)`, and
+`BarColor(bar, r, g, b, a?)`. These accept the native visual or its accessible,
+unprotected descendants; the engine-owned carrier is excluded.
+
+Cleanup restores a property only if it still equals the value this binding wrote,
+so a later external write is preserved. Blizzard or another addon can overwrite
+Apply styling; it is reapplied on relevant identity/faction/target/world events or
+explicit refresh, rather than continuously polled. Direct native writes through
+`Frame`/`Native` are outside rollback ownership and should be avoided.
+
+Register each owned subscription immediately with `p.OnDispose(stop)` before
+doing more work that could throw. Disposers run in reverse order, and a failing
+disposer cannot prevent the remaining cleanup operations.
+
+## Replace
+
+Replace mounts the factory's fresh visual JSX under the native carrier, centered
+on it, and suppresses native UnitFrame alpha only after mounting succeeds. It
+keeps native scripts and events registered. A dormant hook per pooled UnitFrame
+maintains suppression and remembers subsequent public native alpha writes for
+restoration. This does not arbitrate competing nameplate addons that also hide,
+reparent or replace native visuals.
+
+Factories run per unit binding. Do not return one cached JSX instance for several
+plates: mounting rejects simultaneous reuse. Bind sources inside the factory,
+for example `new HP(p.Unit)`; mounting owns their widget subscriptions. Register
+additional manual subscriptions through `OnDispose`.
+
+Nameplate add/remove events, GUID changes and reuse of either carrier or UnitFrame
+dispose the previous binding before a fresh factory runs. Already visible plates
+are discovered on registration and world entry. Name/faction/target events and
+`Refresh()` reevaluate selection and visuals. Health events are handled by data
+sources, without polling selectors. Refresh also rebuilds matching views so edited
+preset values take effect. Protected/forbidden frames and secret GUIDs are skipped.
+
+Native positioning, movement, click bounds and ordinary targeting stay with the
+engine. This API does not resize the carrier or alter native click areas. Ordinary
+unprotected visuals can mount/unmount during combat. Secure JSX is rejected,
+including outside combat: secure nameplate buttons need a separate design for
+combat-time creation, positioning and correct targeting. Fixed arena secure cells
+do not establish that dynamic nameplate buttons are safe.
+
+The Lua integration tests exercise the compiled framework with mock WoW APIs,
+including actual HP source subscription cleanup and mounting failures. They do
+not establish real-client behavior or compatibility with other nameplate addons.

package/lib/WuiraApp.lua

@@ -372,22 +372,58 @@ function WuiraApp.prototype.Unmount(self, frame)
         tree.pendingUnmount = true
         return
     end
+    local failed = false
+    local failure
+    local function attempt(____, action)
+        do
+            local function ____catch(caught)
+                if not failed then
+                    failed = true
+                    failure = caught
+                end
+            end
+            local ____try, ____hasReturned = pcall(function()
+                action(nil)
+            end)
+            if not ____try then
+                ____catch(____hasReturned)
+            end
+        end
+    end
     for ____, dispose in ipairs(tree.bindings) do
-        dispose(nil)
+        attempt(nil, dispose)
     end
     for ____, decoration in ipairs(tree.decorations) do
-        decoration:dispose()
+        attempt(
+            nil,
+            function() return decoration:dispose() end
+        )
     end
     for ____, child in ipairs(tree.frames) do
-        child:UnregisterAllEvents()
-        child:SetScript("OnEvent", nil)
-        child:SetScript("OnUpdate", nil)
-        child:Hide()
+        attempt(
+            nil,
+            function() return child:UnregisterAllEvents() end
+        )
+        attempt(
+            nil,
+            function() return child:SetScript("OnEvent", nil) end
+        )
+        attempt(
+            nil,
+            function() return child:SetScript("OnUpdate", nil) end
+        )
+        attempt(
+            nil,
+            function() return child:Hide() end
+        )
     end
     for ____, cell in ipairs(tree.cells) do
         self.mountedFrames:delete(cell.props)
     end
     self.mountedTrees:delete(frame)
+    if failed then
+        error(failure, 0)
+    end
 end
 function WuiraApp.prototype.Protect(self, root, tree)
     local ____temp_8 = not tree.protected

package/lib/index.d.ts

@@ -16,6 +16,8 @@ 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";

package/lib/index.lua

@@ -38,6 +38,12 @@ 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/forever.d.ts

@@ -35,6 +35,8 @@ interface wuiraNativeFrame {
     SetScript(script: "OnMouseWheel", handler: ((this: void, frame: wuiraNativeFrame, delta: number) => void) | undefined): void;
     GetName(): string | undefined;
     IsProtected?(): boolean;
+    IsForbidden?(): boolean;
+    GetAlpha(): number;
     GetParent(): wuiraNativeFrame;
     GetNumPoints(): number;
     GetPoint(index: number): wuiraNativeReturns<[wuiraAnchor, wuiraNativeFrame, wuiraAnchor, number, number]>;
@@ -95,6 +97,7 @@ declare const UIParent: wuiraNativeFrame;
 declare const _G: Record<string, unknown>;
 declare const SlashCmdList: Record<string, (this: void, message: string) => void>;
 interface wuiraNativeStatusBar extends wuiraNativeFrame {
+    GetStatusBarColor(): wuiraNativeReturns<[number, number, number, number]>;
     GetStatusBarTexture(): wuiraNativeTexture;
     SetMinMaxValues(min: number, max: number): void;
     SetValue(value: number): void;

package/lib/skins/Nameplates.d.ts

@@ -0,0 +1,56 @@
+import type { Cell } from "../ui/Cell";
+export interface NativeNameplate extends wuiraNativeFrame {
+    readonly UnitFrame?: NativeNameplateVisual;
+    readonly namePlateUnitToken?: string;
+    GetUnit?(): string | undefined;
+}
+export interface NativeNameplateVisual extends wuiraNativeFrame {
+    readonly healthBar?: wuiraNativeStatusBar;
+    readonly castBar?: wuiraNativeStatusBar;
+}
+export interface NameplateInfo {
+    readonly Unit: string;
+    readonly GUID: string;
+    /** Engine-owned carrier. Do not mutate it or attach secure controls through this API. */
+    readonly Frame: NativeNameplate;
+    readonly Native: NativeNameplateVisual;
+}
+export type NameplateSelector = (this: void, plate: NameplateInfo) => boolean;
+export type NameplateCustomize = (this: void, plate: NameplateContext) => void;
+export type NameplateRender = (this: void, plate: NameplateContext) => Cell;
+/** One unit binding. Use the reversible methods; direct native writes are not tracked. */
+export declare class NameplateContext implements NameplateInfo {
+    readonly Unit: string;
+    readonly GUID: string;
+    readonly Frame: NativeNameplate;
+    readonly Native: NativeNameplateVisual;
+    private active;
+    private readonly cleanup;
+    constructor(Unit: string, GUID: string, Frame: NativeNameplate, Native: NativeNameplateVisual);
+    /** Register owned subscriptions/sources immediately, before subsequent work can throw. */
+    OnDispose(cleanup: () => void): void;
+    private check;
+    Alpha(frame: wuiraNativeFrame, value: number): void;
+    Scale(frame: wuiraNativeFrame, value: number): void;
+    Size(frame: wuiraNativeFrame, width: number, height: number): void;
+    BarColor(bar: wuiraNativeStatusBar, r: number, g: number, b: number, a?: number): void;
+    /** Internal lifecycle endpoint; cleanup failures cannot prevent other restorations. */
+    Dispose(): void;
+}
+/** An independently disposable ordered registration group. First matching rule wins globally. */
+export declare class NameplateRules {
+    private disposed;
+    private add;
+    Apply(selector: NameplateSelector, customize: NameplateCustomize): this;
+    Replace(selector: NameplateSelector, render: NameplateRender): this;
+    /** Re-evaluate after external preset/selector data changes; native events handle unit changes. */
+    Refresh(): void;
+    Dispose(): void;
+}
+/** Each entry call creates a new group; chained calls append to that group. */
+export declare class Nameplates {
+    private constructor();
+    static Apply(selector: NameplateSelector, customize: NameplateCustomize): NameplateRules;
+    static Replace(selector: NameplateSelector, render: NameplateRender): NameplateRules;
+    static Create(): NameplateRules;
+}