wuira 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,16 @@ with the release date and highlight breaking changes explicitly.
 
 ## Unreleased
 
+## 0.2.1 — 2026-10-15
+
+### Changed
+
+- Make Wuira the static accessor for the addon's WuiraApp instance, which owns
+  mounted trees and their lifecycle. Keep wuira as a compatibility alias.
+- Move the renderer out of ui/mount.ts into WuiraApp and focused rendering
+  helpers for geometry, widgets, visibility, decorations and updates.
+- Generate new addon entry points using Wuira.Mount.
+
 ## 0.2.0 — 2026-10-15
 
 ### Removed

package/README.md

@@ -8,7 +8,7 @@ wuira is a UI framework and addon toolchain for developers who want to describe
 
 An interface should be easy to understand by reading its source. A health display can be a progress bar inside a layout; a player display can be a composition of bars, labels, and icons rather than a special unit-frame class. wuira provides the foundations for that approach, with TypeScript checking your component props before the addon reaches the game.
 
-The snippets below use the lowercase JSX primitives. In a generated project, import `{ UI, wuira }` from `wuira` before mounting a view. Each view example is independent.
+The snippets below use the lowercase JSX primitives. In a generated project, import `{ UI, Wuira }` from `wuira` before mounting a view. Each view example is independent. Wuira is a static accessor; Wuira.App is the current addon's WuiraApp instance and owns its mounted trees and cleanup. Separate addons keep independent application state. The lowercase wuira export remains available for existing addons.
 
 ### JSX composition
 
@@ -29,7 +29,7 @@ function App() {
     );
 }
 
-wuira.Mount(App);
+Wuira.Mount(App);
 ```
 
 ### Native widgets
@@ -48,7 +48,7 @@ const view = (
     />
 );
 
-wuira.Mount(view);
+Wuira.Mount(view);
 ```
 
 ### Layout primitives
@@ -65,7 +65,7 @@ const view = (
     </flow>
 );
 
-wuira.Mount(view);
+Wuira.Mount(view);
 ```
 
 For rows and columns, use `<grid columns={2} gap={8}>` with an explicit width and height.
@@ -91,7 +91,7 @@ function App() {
     );
 }
 
-wuira.Mount(App);
+Wuira.Mount(App);
 ```
 
 ### Conditional sources and health predictions
@@ -145,9 +145,9 @@ cleans up the overlays and resource subscriptions on unmount.
 ### Slash commands
 
 ```ts
-import { wuira } from "wuira";
+import { Wuira } from "wuira";
 
-const unregister = wuira.registerCommand("/myaddon", (...args: string[]) => {
+const unregister = Wuira.registerCommand("/myaddon", (...args: string[]) => {
     console.log("Arguments:", ...args);
 });
 
@@ -324,10 +324,10 @@ also available for applications that manage their own persistence and lifecycle.
 decorations and one child. Mount it like any other component:
 
 ```tsx
-import { UI, wuira } from "wuira";
+import { UI, Wuira } from "wuira";
 import { SecureButton, Label } from "wuira/ui";
 
-wuira.Mount(() => (
+Wuira.Mount(() => (
     <SecureButton width={80} height={24}
         action={{ type: "spell", spell: 635, unit: "player" }}>
         <Label text="Holy Light" align="CENTER" />
@@ -479,12 +479,12 @@ track; native API declarations and reads remain in wuira.
 ### Swing timers
 
 ```tsx
-import { UI, wuira } from "wuira";
+import { UI, Wuira } from "wuira";
 import { ProgressBar } from "wuira/ui";
 import { SwingTimer, SwingHand } from "wuira/datasources";
 
 const mainHand = new SwingTimer(SwingHand.MainHand);
-const view = wuira.Mount(<ProgressBar width={200} height={12} source={mainHand} />);
+const view = Wuira.Mount(<ProgressBar width={200} height={12} source={mainHand} />);
 
 // Other choices: SwingHand.OffHand and SwingHand.Ranged.
 // mainHand.Value: remaining seconds; Max.Value: duration; Percent.Value: remaining percent.
@@ -610,7 +610,7 @@ const view = (
     }} />
 );
 
-wuira.Mount(view);
+Wuira.Mount(view);
 ```
 
 ### Addon tooling
@@ -679,7 +679,7 @@ Alternatively, install globally with `npm install -g wuira`, then use `wuira cre
 
 ```tsx
 import "wuira/console-polyfill";
-import { UI, wuira } from "wuira";
+import { UI, Wuira } from "wuira";
 
 
 function App() {
@@ -687,14 +687,14 @@ function App() {
     return <></>;
 }
 
-wuira.Mount(App);
+Wuira.Mount(App);
 ```
 
 An empty fragment creates no native frame. Only empty fragments are currently supported; use a layout for multiple visual elements.
 
 `console.log/info/warn/error` use a global WoW console polyfill. Output goes to the local chat window, never to other players. The addon uses no Node.js runtime or stdin/stdout. `console.error` does not throw. Arguments are formatted with Lua `tostring`; objects are not deeply inspected. The CLI uses its own Node.js terminal console.
 
-Importing `wuira` installs the global console polyfill automatically. The shared TypeScript config loads its global declarations and uses Node16 module resolution for package exports; DOM typings are not required. `wuira.Mount` accepts a `Cell`, no value, or a function returning `Cell | void`, so addons without a visual tree can simply log and return.
+Importing `wuira` installs the global console polyfill automatically. The shared TypeScript config loads its global declarations and uses Node16 module resolution for package exports; DOM typings are not required. `Wuira.Mount` accepts a `Cell`, no value, or a function returning `Cell | void`, so addons without a visual tree can simply log and return.
 
 ## Build and distribution
 

package/lib/WuiraApp.d.ts

@@ -0,0 +1,12 @@
+import type { Cell } from "./ui/Cell";
+import type { Anchor } from "./types/Position";
+import type { CommandCallback } from "./platform/SlashCommands";
+/** Owns one application's native UI trees, bindings and cleanup. */
+export declare class WuiraApp {
+    private readonly mountedFrames;
+    private readonly mountedTrees;
+    registerCommand(command: string, callback: CommandCallback): () => void;
+    Mount(component: Cell | void | (() => Cell | void), anchor?: Anchor, parent?: wuiraNativeFrame): wuiraNativeFrame | undefined;
+    Unmount(frame: wuiraNativeFrame): void;
+    private Protect;
+}

package/lib/WuiraApp.lua

@@ -0,0 +1,425 @@
+--[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]
+-- Lua Library inline imports
+local function __TS__Class(self)
+    local c = {prototype = {}}
+    c.prototype.__index = c.prototype
+    c.prototype.constructor = c
+    return c
+end
+
+local __TS__Symbol, Symbol
+do
+    local symbolMetatable = {__tostring = function(self)
+        return ("Symbol(" .. (self.description or "")) .. ")"
+    end}
+    function __TS__Symbol(description)
+        return setmetatable({description = description}, symbolMetatable)
+    end
+    Symbol = {
+        asyncDispose = __TS__Symbol("Symbol.asyncDispose"),
+        dispose = __TS__Symbol("Symbol.dispose"),
+        iterator = __TS__Symbol("Symbol.iterator"),
+        hasInstance = __TS__Symbol("Symbol.hasInstance"),
+        species = __TS__Symbol("Symbol.species"),
+        toStringTag = __TS__Symbol("Symbol.toStringTag")
+    }
+end
+
+local __TS__Iterator
+do
+    local function iteratorGeneratorStep(self)
+        local co = self.____coroutine
+        local status, value = coroutine.resume(co)
+        if not status then
+            error(value, 0)
+        end
+        if coroutine.status(co) == "dead" then
+            return
+        end
+        return true, value
+    end
+    local function iteratorIteratorStep(self)
+        local result = self:next()
+        if result.done then
+            return
+        end
+        return true, result.value
+    end
+    local function iteratorStringStep(self, index)
+        index = index + 1
+        if index > #self then
+            return
+        end
+        return index, string.sub(self, index, index)
+    end
+    function __TS__Iterator(iterable)
+        if type(iterable) == "string" then
+            return iteratorStringStep, iterable, 0
+        elseif iterable.____coroutine ~= nil then
+            return iteratorGeneratorStep, iterable
+        elseif iterable[Symbol.iterator] then
+            local iterator = iterable[Symbol.iterator](iterable)
+            return iteratorIteratorStep, iterator
+        else
+            return ipairs(iterable)
+        end
+    end
+end
+
+local Map
+do
+    Map = __TS__Class()
+    Map.name = "Map"
+    function Map.prototype.____constructor(self, entries)
+        self[Symbol.toStringTag] = "Map"
+        self.items = {}
+        self.size = 0
+        self.nextKey = {}
+        self.previousKey = {}
+        if entries == nil then
+            return
+        end
+        local iterable = entries
+        if iterable[Symbol.iterator] then
+            local iterator = iterable[Symbol.iterator](iterable)
+            while true do
+                local result = iterator:next()
+                if result.done then
+                    break
+                end
+                local value = result.value
+                self:set(value[1], value[2])
+            end
+        else
+            local array = entries
+            for ____, kvp in ipairs(array) do
+                self:set(kvp[1], kvp[2])
+            end
+        end
+    end
+    function Map.prototype.clear(self)
+        self.items = {}
+        self.nextKey = {}
+        self.previousKey = {}
+        self.firstKey = nil
+        self.lastKey = nil
+        self.size = 0
+    end
+    function Map.prototype.delete(self, key)
+        local contains = self:has(key)
+        if contains then
+            self.size = self.size - 1
+            local next = self.nextKey[key]
+            local previous = self.previousKey[key]
+            if next ~= nil and previous ~= nil then
+                self.nextKey[previous] = next
+                self.previousKey[next] = previous
+            elseif next ~= nil then
+                self.firstKey = next
+                self.previousKey[next] = nil
+            elseif previous ~= nil then
+                self.lastKey = previous
+                self.nextKey[previous] = nil
+            else
+                self.firstKey = nil
+                self.lastKey = nil
+            end
+            self.nextKey[key] = nil
+            self.previousKey[key] = nil
+        end
+        self.items[key] = nil
+        return contains
+    end
+    function Map.prototype.forEach(self, callback)
+        for ____, key in __TS__Iterator(self:keys()) do
+            callback(nil, self.items[key], key, self)
+        end
+    end
+    function Map.prototype.get(self, key)
+        return self.items[key]
+    end
+    function Map.prototype.has(self, key)
+        return self.nextKey[key] ~= nil or self.lastKey == key
+    end
+    function Map.prototype.set(self, key, value)
+        local isNewValue = not self:has(key)
+        if isNewValue then
+            self.size = self.size + 1
+        end
+        self.items[key] = value
+        if self.firstKey == nil then
+            self.firstKey = key
+            self.lastKey = key
+        elseif isNewValue then
+            self.nextKey[self.lastKey] = key
+            self.previousKey[key] = self.lastKey
+            self.lastKey = key
+        end
+        return self
+    end
+    Map.prototype[Symbol.iterator] = function(self)
+        return self:entries()
+    end
+    function Map.prototype.entries(self)
+        local function getFirstKey()
+            return self.firstKey
+        end
+        local items = self.items
+        local nextKey = self.nextKey
+        local key
+        local started = false
+        return {
+            [Symbol.iterator] = function(self)
+                return self
+            end,
+            next = function(self)
+                if not started then
+                    started = true
+                    key = getFirstKey(nil)
+                else
+                    key = nextKey[key]
+                end
+                return {done = not key, value = {key, items[key]}}
+            end
+        }
+    end
+    function Map.prototype.keys(self)
+        local function getFirstKey()
+            return self.firstKey
+        end
+        local nextKey = self.nextKey
+        local key
+        local started = false
+        return {
+            [Symbol.iterator] = function(self)
+                return self
+            end,
+            next = function(self)
+                if not started then
+                    started = true
+                    key = getFirstKey(nil)
+                else
+                    key = nextKey[key]
+                end
+                return {done = not key, value = key}
+            end
+        }
+    end
+    function Map.prototype.values(self)
+        local function getFirstKey()
+            return self.firstKey
+        end
+        local items = self.items
+        local nextKey = self.nextKey
+        local key
+        local started = false
+        return {
+            [Symbol.iterator] = function(self)
+                return self
+            end,
+            next = function(self)
+                if not started then
+                    started = true
+                    key = getFirstKey(nil)
+                else
+                    key = nextKey[key]
+                end
+                return {done = not key, value = items[key]}
+            end
+        }
+    end
+    Map[Symbol.species] = Map
+end
+
+local function __TS__New(target, ...)
+    local instance = setmetatable({}, target.prototype)
+    instance:____constructor(...)
+    return instance
+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
+-- End of Lua Library inline imports
+local ____exports = {}
+local ____layout = require("rendering.layout")
+local prepareLayout = ____layout.prepareLayout
+local createFrames = ____layout.createFrames
+local resolveAnchors = ____layout.resolveAnchors
+local applyPosition = ____layout.applyPosition
+local ____visibility = require("rendering.visibility")
+local bindVisibility = ____visibility.bindVisibility
+local ____widgets = require("rendering.widgets")
+local renderWidget = ____widgets.renderWidget
+local ____decorations = require("rendering.decorations")
+local renderDecorations = ____decorations.renderDecorations
+local ____updates = require("rendering.updates")
+local startUpdates = ____updates.startUpdates
+local ____SlashCommands = require("platform.SlashCommands")
+local registerCommand = ____SlashCommands.registerCommand
+--- Owns one application's native UI trees, bindings and cleanup.
+____exports.WuiraApp = __TS__Class()
+local WuiraApp = ____exports.WuiraApp
+WuiraApp.name = "WuiraApp"
+function WuiraApp.prototype.____constructor(self)
+    self.mountedFrames = __TS__New(Map)
+    self.mountedTrees = __TS__New(Map)
+end
+function WuiraApp.prototype.registerCommand(self, command, callback)
+    return registerCommand(nil, command, callback)
+end
+function WuiraApp.prototype.Mount(self, component, anchor, parent)
+    if parent == nil then
+        parent = UIParent
+    end
+    local ____temp_0
+    if type(component) == "function" then
+        ____temp_0 = component(nil)
+    else
+        ____temp_0 = component
+    end
+    local view = ____temp_0
+    if view == nil or view.kind == "empty" then
+        return nil
+    end
+    local ____prepareLayout_result_1 = prepareLayout(nil, view, parent, self.mountedFrames)
+    local measured = ____prepareLayout_result_1.measured
+    local protectedTree = ____prepareLayout_result_1.protectedTree
+    local ____createFrames_result_2 = createFrames(nil, measured, parent, self.mountedFrames)
+    local root = ____createFrames_result_2.root
+    local pending = ____createFrames_result_2.pending
+    local frames = ____createFrames_result_2.frames
+    local tree = {
+        frames = __TS__ArrayMap(
+            pending,
+            function(____, item) return item.frame end
+        ),
+        cells = __TS__ArrayMap(
+            pending,
+            function(____, item) return item.cell end
+        ),
+        decorations = {},
+        bindings = {},
+        protected = protectedTree,
+        pendingUnmount = false,
+        visibility = {}
+    }
+    self.mountedTrees:set(root, tree)
+    do
+        local function ____catch(failure)
+            self:Unmount(root)
+            error(failure, 0)
+        end
+        local ____try, ____hasReturned = pcall(function()
+            local anchors = resolveAnchors(nil, pending, frames)
+            local updates = {}
+            self:Protect(root, tree)
+            for ____, item in ipairs(pending) do
+                local visibility = bindVisibility(
+                    nil,
+                    item,
+                    tree,
+                    updates,
+                    function() return self:Protect(root, tree) end
+                )
+                applyPosition(
+                    nil,
+                    item,
+                    anchors,
+                    root,
+                    anchor
+                )
+                renderWidget(
+                    nil,
+                    item,
+                    tree,
+                    updates,
+                    visibility.onActiveChange
+                )
+                renderDecorations(nil, item, tree)
+                self.mountedFrames:set(item.cell.props, item.frame)
+                visibility:refresh()
+                local ____this_4
+                ____this_4 = item.cell.props
+                local ____opt_3 = ____this_4.onMount
+                local cleanup = ____opt_3 and ____opt_3(____this_4, item.frame)
+                if cleanup ~= nil then
+                    local ____tree_bindings_5 = tree.bindings
+                    ____tree_bindings_5[#____tree_bindings_5 + 1] = cleanup
+                end
+                if visibility.dynamic then
+                    updates[#updates + 1] = visibility.refresh
+                end
+            end
+            startUpdates(nil, parent, tree, updates)
+        end)
+        if not ____try then
+            ____catch(____hasReturned)
+        end
+    end
+    return root
+end
+function WuiraApp.prototype.Unmount(self, frame)
+    local tree = self.mountedTrees:get(frame)
+    if tree == nil then
+        return
+    end
+    if self:Protect(frame, tree) and InCombatLockdown() then
+        tree.pendingUnmount = true
+        return
+    end
+    for ____, dispose in ipairs(tree.bindings) do
+        dispose(nil)
+    end
+    for ____, decoration in ipairs(tree.decorations) do
+        decoration:dispose()
+    end
+    for ____, child in ipairs(tree.frames) do
+        child:UnregisterAllEvents()
+        child:SetScript("OnEvent", nil)
+        child:SetScript("OnUpdate", nil)
+        child:Hide()
+    end
+    for ____, cell in ipairs(tree.cells) do
+        self.mountedFrames:delete(cell.props)
+    end
+    self.mountedTrees:delete(frame)
+end
+function WuiraApp.prototype.Protect(self, root, tree)
+    local ____temp_8 = not tree.protected
+    if ____temp_8 then
+        local ____this_7
+        ____this_7 = root
+        local ____opt_6 = ____this_7.IsProtected
+        ____temp_8 = (____opt_6 and ____opt_6(____this_7)) ~= true
+    end
+    if ____temp_8 then
+        return false
+    end
+    tree.protected = true
+    if tree.listener == nil then
+        local listener = CreateFrame("Frame", nil, UIParent)
+        tree.listener = listener
+        local ____tree_frames_9 = tree.frames
+        ____tree_frames_9[#____tree_frames_9 + 1] = listener
+        listener:RegisterEvent("PLAYER_REGEN_ENABLED")
+        listener:SetScript(
+            "OnEvent",
+            function()
+                if tree.pendingUnmount then
+                    self:Unmount(root)
+                else
+                    for ____, refresh in ipairs(tree.visibility) do
+                        refresh(nil)
+                    end
+                end
+            end
+        )
+    end
+    return true
+end
+return ____exports

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 /// <reference path="./platform/forever.d.ts" />
 import "./console-polyfill";
-export { wuira } from "./wuira";
+export { Wuira, wuira } from "./wuira";
+export { WuiraApp } from "./WuiraApp";
 export type { CommandCallback } from "./platform/SlashCommands";
 export { AddonSettings } from "./platform/AddonSettings";
 export { Encoding } from "./platform/Encoding";

package/lib/index.lua

@@ -3,8 +3,13 @@ local ____exports = {}
 require("console-polyfill")
 do
     local ____wuira = require("wuira")
+    ____exports.Wuira = ____wuira.Wuira
     ____exports.wuira = ____wuira.wuira
 end
+do
+    local ____WuiraApp = require("WuiraApp")
+    ____exports.WuiraApp = ____WuiraApp.WuiraApp
+end
 do
     local ____AddonSettings = require("platform.AddonSettings")
     ____exports.AddonSettings = ____AddonSettings.AddonSettings

package/lib/rendering/decorations.d.ts

@@ -0,0 +1,2 @@
+import type { MountedTree, RenderedCell } from "./types";
+export declare function renderDecorations(item: RenderedCell, tree: MountedTree): void;

package/lib/rendering/decorations.lua

@@ -0,0 +1,42 @@
+--[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]
+-- Lua Library inline imports
+local function __TS__New(target, ...)
+    local instance = setmetatable({}, target.prototype)
+    instance:____constructor(...)
+    return instance
+end
+-- End of Lua Library inline imports
+local ____exports = {}
+local ____Background = require("ui.decorations.Background")
+local Background = ____Background.Background
+local ____Border = require("ui.decorations.Border")
+local Border = ____Border.Border
+function ____exports.renderDecorations(self, item, tree)
+    local decorations = item.cell.props.decorations
+    local function attach(self, decoration)
+        if decoration ~= nil then
+            decoration:mount(item.frame, item.width, item.height)
+            local ____tree_decorations_0 = tree.decorations
+            ____tree_decorations_0[#____tree_decorations_0 + 1] = decoration
+        end
+    end
+    local progress = item.cell.kind == "progress" and item.cell.props or nil
+    local ____attach_8 = attach
+    local ____temp_7
+    if (progress and progress.background) == false then
+        ____temp_7 = nil
+    else
+        ____temp_7 = (progress and progress.background) ~= nil and __TS__New(Background, progress.background) or decorations and decorations.background
+    end
+    ____attach_8(nil, ____temp_7)
+    local ____attach_16 = attach
+    local ____temp_15
+    if (progress and progress.backdrop) == false then
+        ____temp_15 = nil
+    else
+        ____temp_15 = (progress and progress.backdrop) ~= nil and __TS__New(Border, progress.backdrop) or decorations and decorations.border
+    end
+    ____attach_16(nil, ____temp_15)
+    attach(nil, decorations and decorations.glow)
+end
+return ____exports

package/lib/rendering/layout.d.ts

@@ -0,0 +1,16 @@
+import type { CellProps } from "../ui/Cell";
+import type { Element } from "../ui/primitives/jsx";
+import type { Anchor } from "../types/Position";
+import { MeasuredCell } from "../ui/layout/measureLayout";
+import type { RenderedCell } from "./types";
+export declare function prepareLayout(element: Element, parent: wuiraNativeFrame, mountedFrames: ReadonlyMap<CellProps, wuiraNativeFrame>): {
+    measured: MeasuredCell;
+    protectedTree: boolean;
+};
+export declare function createFrames(measured: MeasuredCell, parent: wuiraNativeFrame, mountedFrames: ReadonlyMap<CellProps, wuiraNativeFrame>): {
+    root: wuiraNativeFrame;
+    pending: RenderedCell[];
+    frames: Map<CellProps, wuiraNativeFrame>;
+};
+export declare function resolveAnchors(pending: RenderedCell[], frames: ReadonlyMap<CellProps, wuiraNativeFrame>): Map<wuiraNativeFrame, wuiraNativeFrame>;
+export declare function applyPosition(item: RenderedCell, anchors: ReadonlyMap<wuiraNativeFrame, wuiraNativeFrame>, root: wuiraNativeFrame, rootAnchor?: Anchor): void;