wuira 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -7,6 +7,35 @@ 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
+
+- Keep wuira source conversion callback-based. Case mappings and arithmetic
+  formula factories now belong to LumaUI's builder layer.
+
+### Removed
+
+- **Breaking:** Remove the `CaseConverter` and `MathConverter` APIs introduced in
+  0.2.5, including the expression parser. Use `new SourceConverter(source,
+  value => ...)` in wuira code; LumaUI owns its editable case/math definitions.
+
 ## 0.2.5 — 2026-10-16
 
 ### Added

package/README.md

@@ -30,7 +30,7 @@ wuira.Mount(App);
 - **Native widgets** — Cells mount to WoW frames; progress bars use the native StatusBar widget.
 - **Layout primitives** — Arrange children with `flow` and `grid`.
 - **Data sources** — HP, Mana, auras, cooldowns, casts, swings, group members, class/spec, spellbook.
-- **Source converters** — Compose checked value transformations, case mappings and arithmetic expressions. See [source converters](docs/source-converters.md).
+- **Source converters** — Transform checked values with typed callbacks. See [source converters](docs/source-converters.md).
 - **Slash commands** — Register commands with quoting and escaping support.
 - **Windows and settings** — `Window`, `AddonSettings`, `FrameMover`, `KeybindCapture`.
 - **Secure buttons** — Spell, item, macro, action, and target actions with `SecureButton`.
@@ -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/docs/source-converters.md

@@ -1,34 +1,27 @@
 # Source converters
 
-`SourceConverter` transforms a readable source value. It consumes the input's change notifications, shares one upstream subscription across its observers, and does not create a timer or dispose the shared input. Sources without notifications remain available as checked one-time reads.
+`SourceConverter` transforms a readable source with a typed callback. It consumes change notifications, shares one upstream subscription across observers, and does not create a timer or dispose the shared input. Sources without notifications remain available as checked one-time reads.
 
 ```ts
-import { ClassSource, SourceConverter, CaseConverter, HP, MathConverter, Unit } from "wuira/datasources";
+import { SourceConverter, HP, ClassSource, Unit } from "wuira/datasources";
 
+const hp = new HP(Unit.Player);
+const doubled = new SourceConverter(hp, value => value * 2);
 const characterClass = new ClassSource(Unit.Player);
 const token = new SourceConverter(characterClass, info => info?.token);
-const color = new CaseConverter(token, [
-    { equals: "PALADIN", value: { r: 1, g: 0.5, b: 0.7, a: 1 } },
-    { equals: "MAGE", value: { r: 0.4, g: 0.8, b: 1, a: 1 } },
-], { r: 0.35, g: 0.4, b: 0.45, a: 1 });
-
-const hp = new HP(Unit.Player);
-const doubled = new MathConverter(hp, "2 * input");
 const stop = doubled.BindTo(value => console.log(value));
+
 // On removal:
 stop();
 doubled.Dispose();
-color.Dispose();
 token.Dispose();
 characterClass.Dispose();
 ```
 
-`Value` and `Compute()` are checked reads. `TryCompute()` performs one checked read and returns `{ readable: false }` for restricted data, without invoking the callback. Converter chains use it to avoid repeated leaf reads. `onChange()` observes future readable output changes; `BindTo()` also applies the current readable value immediately. Scalar outputs with the same value do not emit again. `When()` filters emissions without changing the checked `Value` getter. Call `Dispose()` when the converter is no longer owned by a component.
-
-Cases compare strings, finite numbers and booleans with strict equality; `1` and `"1"` are different keys. Duplicate keys are rejected. Unmatched values return the supplied default, or `undefined` when none was provided. Case outputs can be colors, texture IDs, text or other data.
+`Value` and `Compute()` are checked reads. `TryCompute()` performs one checked read and returns `{ readable: false }` for restricted data without invoking the callback. Converter chains use it to read their leaf once, including when the data is restricted.
 
-Math expressions support `input`, finite numeric literals, parentheses, unary signs, `+`, `-`, `*`, `/`, `%`, and exponentiation (`^` or `**`). Exponents associate to the right; `-input^2` means `-(input^2)`. The bounded parser runs once at construction. It does not evaluate JavaScript or Lua, access globals, or call functions. Invalid syntax, division by zero and non-finite results throw errors. `MathConverter.Validate(expression)` checks syntax without reading the input.
+`onChange()` observes future readable output changes; `BindTo()` also applies the current readable value immediately. Identical scalar outputs do not emit again. `When()` filters emissions without changing the checked getter. `Dispose()` releases observers while leaving the input available to other consumers.
 
-Restricted values, including nested secret fields, never reach a conversion callback. Restrictions are checked when values are consumed; combat alone does not mark a value secret. ClassSource subscriptions follow unit identity changes and relevant native events, and release those listeners when the last consumer unsubscribes.
+Restricted values, including nested secret fields, never reach a conversion callback. Restrictions are checked when consumed; combat alone does not mark a value secret. ClassSource subscriptions follow unit identity changes and native events, releasing listeners when the last consumer unsubscribes.
 
-Converters produce data. They do not grant permission to change protected buttons or their actions during combat.
+The SDK accepts TypeScript callbacks. Editable case rules and math formulas are LumaUI builder factories, implemented using this generic source. Converters produce data; protected button actions remain subject to native combat restrictions.

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/datasources/SourceConverter.d.ts

@@ -28,12 +28,3 @@ export declare class SourceConverter<TInput, TOutput> extends DataSource<TOutput
     BindTo(apply: (value: TOutput) => void): () => void;
     Dispose(): void;
 }
-export type CaseKey = string | number | boolean;
-export interface SourceCase<T> {
-    readonly equals: CaseKey;
-    readonly value: T;
-}
-/** Strict equality, first matching case, then the optional default value. */
-export declare class CaseConverter<TInput, TOutput> extends SourceConverter<TInput, TOutput | undefined> {
-    constructor(input: ValueSource<TInput>, cases: readonly SourceCase<TOutput>[], fallback?: TOutput);
-}

package/lib/datasources/SourceConverter.lua

@@ -319,62 +319,6 @@ local function __TS__ClassExtends(target, base)
         target.prototype.__tostring = base.prototype.__tostring
     end
 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
-
-local function __TS__ArrayMap(self, callbackfn, thisArg)
-    local result = {}
-    for i = 1, #self do
-        result[i] = callbackfn(thisArg, self[i], i - 1, self)
-    end
-    return result
-end
-
-local function __TS__TypeOf(value)
-    local luaType = type(value)
-    if luaType == "table" then
-        return "object"
-    elseif luaType == "nil" then
-        return "undefined"
-    else
-        return luaType
-    end
-end
-
-local function __TS__ArrayIncludes(self, searchElement, fromIndex)
-    if fromIndex == nil then
-        fromIndex = 0
-    end
-    local len = #self
-    local k = fromIndex
-    if fromIndex < 0 then
-        k = len + fromIndex
-    end
-    if k < 0 then
-        k = 0
-    end
-    for i = k + 1, len do
-        if self[i] == searchElement then
-            return true
-        end
-    end
-    return false
-end
-
-local function __TS__NumberIsFinite(value)
-    return type(value) == "number" and value == value and value ~= math.huge and value ~= -math.huge
-end
 -- End of Lua Library inline imports
 local ____exports = {}
 local ____DataSource = require("datasources.DataSource")
@@ -528,41 +472,4 @@ function SourceConverter.prototype.Dispose(self)
     self.stop = nil
     self.listeners:clear()
 end
---- Strict equality, first matching case, then the optional default value.
-____exports.CaseConverter = __TS__Class()
-local CaseConverter = ____exports.CaseConverter
-CaseConverter.name = "CaseConverter"
-__TS__ClassExtends(CaseConverter, ____exports.SourceConverter)
-function CaseConverter.prototype.____constructor(self, input, cases, fallback)
-    local entries = __TS__ArrayMap(
-        cases,
-        function(____, entry) return __TS__ObjectAssign({}, entry) end
-    )
-    local seen = __TS__New(Set)
-    for ____, entry in ipairs(entries) do
-        local key = entry.equals
-        if issecretvalue(key) or not __TS__ArrayIncludes(
-            {"string", "number", "boolean"},
-            __TS__TypeOf(key)
-        ) or type(key) == "number" and not __TS__NumberIsFinite(key) then
-            error("CaseConverter: invalid match value")
-        end
-        if seen:has(key) then
-            error("CaseConverter: duplicate match value")
-        end
-        seen:add(key)
-    end
-    CaseConverter.____super.prototype.____constructor(
-        self,
-        input,
-        function(____, value)
-            for ____, entry in ipairs(entries) do
-                if value == entry.equals then
-                    return entry.value
-                end
-            end
-            return fallback
-        end
-    )
-end
 return ____exports

package/lib/datasources/index.d.ts

@@ -1,9 +1,8 @@
 /// <reference path="../platform/forever.d.ts" />
 export { DataSource } from "./DataSource";
 export type { ReadResult } from "./DataSource";
-export { SourceConverter, CaseConverter } from "./SourceConverter";
-export type { ValueSource, CaseKey, SourceCase } from "./SourceConverter";
-export { MathConverter } from "./MathConverter";
+export { SourceConverter } from "./SourceConverter";
+export type { ValueSource } from "./SourceConverter";
 export { EditModeLayouts } from "./EditModeLayouts";
 export type { EditModeLayout, EditModeLayoutSnapshot, EditModeLayoutsStatus } from "./EditModeLayouts";
 export { ProgressSource } from "./ProgressSource";

package/lib/datasources/index.lua

@@ -7,11 +7,6 @@ end
 do
     local ____SourceConverter = require("datasources.SourceConverter")
     ____exports.SourceConverter = ____SourceConverter.SourceConverter
-    ____exports.CaseConverter = ____SourceConverter.CaseConverter
-end
-do
-    local ____MathConverter = require("datasources.MathConverter")
-    ____exports.MathConverter = ____MathConverter.MathConverter
 end
 do
     local ____EditModeLayouts = require("datasources.EditModeLayouts")

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;
+}