wuira 0.2.4 → 0.2.6

package/docs/icons.md

@@ -0,0 +1,28 @@
+# Forever icon catalog
+
+`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 { Icons } from "wuira/icons";
+import { Icon } from "wuira/ui";
+
+const image = <Icon width={24} height={24} texture={Icons.BlessingOfFreedom_135968} />;
+```
+
+Every icon has an explicit ID-suffixed member. A readable short alias is generated only when that name maps to one icon. Multiple spells or items may share the same texture; they produce one catalog entry with searchable aliases.
+
+The snapshot combines SpellMisc spell/active icon fields with Item icon fields and ItemSparse names from the pinned client build. It covers every positive icon ID referenced by these tables, including unused records and entries without a readable name; it does not claim to list every texture or atlas in the game. No other client branch is merged into it. The names describe associated spells or items, rather than guessing asset filenames. Unnamed records receive a `Spell <id>` or `Item <id>` label.
+
+The generated enum is erased to numeric literals by TypeScriptToLua. Editor tools can read the packaged `data/icons/forever.json` to create a searchable catalog without constructing every icon in game. A selected texture is saved as a FileDataID, not a spell ID.
+
+Game data belongs to Blizzard Entertainment. Source URLs, row counts, build and SHA-256 hashes are recorded in the snapshot.
+
+## Update
+
+```sh
+npm run icons:update -- --build 1.60.1.70374
+npm run icons:generate
+```
+
+Use `--cached` to regenerate the snapshot from downloaded CSVs. Updating requires the build to match `data/spells/forever.json`. Normal consumers use the committed snapshot and do not download game data during a build.

package/docs/source-converters.md

@@ -0,0 +1,27 @@
+# Source converters
+
+`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 { 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 stop = doubled.BindTo(value => console.log(value));
+
+// On removal:
+stop();
+doubled.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 read their leaf once, including when the data is restricted.
+
+`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 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.
+
+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/datasources/DataSource.d.ts

@@ -1,3 +1,9 @@
+export type ReadResult<T> = {
+    readonly readable: true;
+    readonly value: T;
+} | {
+    readonly readable: false;
+};
 /** A value-producing source. Secrecy describes data, not native frame protection. */
 export declare abstract class DataSource<T> {
     private value;
@@ -8,6 +14,8 @@ export declare abstract class DataSource<T> {
     IsSecret(): boolean;
     get Value(): T;
     Compute<TResult>(compute: (value: T) => TResult): TResult;
+    /** One checked read, without exposing a restricted value or invoking its callback. */
+    TryCompute<TResult>(compute: (value: T) => TResult): ReadResult<TResult>;
     protected GetValue(): T;
     /** Filters native binding emissions; Value remains a checked, fresh snapshot. */
     When(condition: (value: T) => boolean): this;

package/lib/datasources/DataSource.lua

@@ -165,6 +165,13 @@ function DataSource.prototype.Compute(self, compute)
     self:AssertReadable(value)
     return compute(nil, value)
 end
+function DataSource.prototype.TryCompute(self, compute)
+    local value = self:GetValue()
+    return self:IsValueSecret(value) and ({readable = false}) or ({
+        readable = true,
+        value = compute(nil, value)
+    })
+end
 function DataSource.prototype.GetValue(self)
     return self.value
 end

package/lib/datasources/SourceConverter.d.ts

@@ -0,0 +1,30 @@
+import { DataSource } from "./DataSource";
+import type { ReadResult } from "./DataSource";
+/** Structural contract: converters can consume a shared source without owning it. */
+export interface ValueSource<T> {
+    readonly Value: T;
+    IsSecret(): boolean;
+    TryCompute?<TResult>(compute: (value: T) => TResult): ReadResult<TResult>;
+    onChange?(listener: (value: T) => void): () => void;
+}
+/** Checked value transformation. No timers, native widgets or ownership of the input. */
+export declare class SourceConverter<TInput, TOutput> extends DataSource<TOutput> {
+    private readonly input;
+    private readonly convert;
+    private readonly listeners;
+    private stop?;
+    private disposed;
+    private blocked;
+    private previous?;
+    private readable;
+    constructor(input: ValueSource<TInput>, convert: (value: TInput) => TOutput);
+    protected GetValue(): TOutput;
+    private Convert;
+    protected HasSecretFields(value: TOutput): boolean;
+    /** Future readable changes. The first observer attaches one upstream subscription. */
+    onChange(listener: (value: TOutput) => void): () => void;
+    private Refresh;
+    /** One immediate readable value, followed by event-driven changes when supported. */
+    BindTo(apply: (value: TOutput) => void): () => void;
+    Dispose(): void;
+}

package/lib/datasources/SourceConverter.lua

@@ -0,0 +1,475 @@
+--[[ 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 function __TS__New(target, ...)
+    local instance = setmetatable({}, target.prototype)
+    instance:____constructor(...)
+    return instance
+end
+
+local Set
+do
+    Set = __TS__Class()
+    Set.name = "Set"
+    function Set.prototype.____constructor(self, values)
+        self[Symbol.toStringTag] = "Set"
+        self.size = 0
+        self.nextKey = {}
+        self.previousKey = {}
+        if values == nil then
+            return
+        end
+        local iterable = values
+        if iterable[Symbol.iterator] then
+            local iterator = iterable[Symbol.iterator](iterable)
+            while true do
+                local result = iterator:next()
+                if result.done then
+                    break
+                end
+                self:add(result.value)
+            end
+        else
+            local array = values
+            for ____, value in ipairs(array) do
+                self:add(value)
+            end
+        end
+    end
+    function Set.prototype.add(self, value)
+        local isNewValue = not self:has(value)
+        if isNewValue then
+            self.size = self.size + 1
+        end
+        if self.firstKey == nil then
+            self.firstKey = value
+            self.lastKey = value
+        elseif isNewValue then
+            self.nextKey[self.lastKey] = value
+            self.previousKey[value] = self.lastKey
+            self.lastKey = value
+        end
+        return self
+    end
+    function Set.prototype.clear(self)
+        self.nextKey = {}
+        self.previousKey = {}
+        self.firstKey = nil
+        self.lastKey = nil
+        self.size = 0
+    end
+    function Set.prototype.delete(self, value)
+        local contains = self:has(value)
+        if contains then
+            self.size = self.size - 1
+            local next = self.nextKey[value]
+            local previous = self.previousKey[value]
+            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[value] = nil
+            self.previousKey[value] = nil
+        end
+        return contains
+    end
+    function Set.prototype.forEach(self, callback)
+        for ____, key in __TS__Iterator(self:keys()) do
+            callback(nil, key, key, self)
+        end
+    end
+    function Set.prototype.has(self, value)
+        return self.nextKey[value] ~= nil or self.lastKey == value
+    end
+    Set.prototype[Symbol.iterator] = function(self)
+        return self:values()
+    end
+    function Set.prototype.entries(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, key}}
+            end
+        }
+    end
+    function Set.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 Set.prototype.values(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 Set.prototype.union(self, other)
+        local result = __TS__New(Set, self)
+        for ____, item in __TS__Iterator(other) do
+            result:add(item)
+        end
+        return result
+    end
+    function Set.prototype.intersection(self, other)
+        local result = __TS__New(Set)
+        for ____, item in __TS__Iterator(self) do
+            if other:has(item) then
+                result:add(item)
+            end
+        end
+        return result
+    end
+    function Set.prototype.difference(self, other)
+        local result = __TS__New(Set, self)
+        for ____, item in __TS__Iterator(other) do
+            result:delete(item)
+        end
+        return result
+    end
+    function Set.prototype.symmetricDifference(self, other)
+        local result = __TS__New(Set, self)
+        for ____, item in __TS__Iterator(other) do
+            if self:has(item) then
+                result:delete(item)
+            else
+                result:add(item)
+            end
+        end
+        return result
+    end
+    function Set.prototype.isSubsetOf(self, other)
+        for ____, item in __TS__Iterator(self) do
+            if not other:has(item) then
+                return false
+            end
+        end
+        return true
+    end
+    function Set.prototype.isSupersetOf(self, other)
+        for ____, item in __TS__Iterator(other) do
+            if not self:has(item) then
+                return false
+            end
+        end
+        return true
+    end
+    function Set.prototype.isDisjointFrom(self, other)
+        for ____, item in __TS__Iterator(self) do
+            if other:has(item) then
+                return false
+            end
+        end
+        return true
+    end
+    Set[Symbol.species] = Set
+end
+
+local function __TS__ObjectValues(obj)
+    local result = {}
+    local len = 0
+    for key in pairs(obj) do
+        len = len + 1
+        result[len] = obj[key]
+    end
+    return result
+end
+
+local function __TS__ClassExtends(target, base)
+    target.____super = base
+    local staticMetatable = setmetatable({__index = base}, base)
+    setmetatable(target, staticMetatable)
+    local baseMetatable = getmetatable(base)
+    if baseMetatable then
+        if type(baseMetatable.__index) == "function" then
+            staticMetatable.__index = baseMetatable.__index
+        end
+        if type(baseMetatable.__newindex) == "function" then
+            staticMetatable.__newindex = baseMetatable.__newindex
+        end
+    end
+    setmetatable(target.prototype, base.prototype)
+    if type(base.prototype.__index) == "function" then
+        target.prototype.__index = base.prototype.__index
+    end
+    if type(base.prototype.__newindex) == "function" then
+        target.prototype.__newindex = base.prototype.__newindex
+    end
+    if type(base.prototype.__tostring) == "function" then
+        target.prototype.__tostring = base.prototype.__tostring
+    end
+end
+-- End of Lua Library inline imports
+local ____exports = {}
+local ____DataSource = require("datasources.DataSource")
+local DataSource = ____DataSource.DataSource
+local function restricted(self, value, seen, depth)
+    if seen == nil then
+        seen = __TS__New(Set)
+    end
+    if depth == nil then
+        depth = 0
+    end
+    if issecretvalue(value) or depth > 32 then
+        return true
+    end
+    if type(value) ~= "table" or value == nil or seen:has(value) then
+        return false
+    end
+    seen:add(value)
+    for ____, child in ipairs(__TS__ObjectValues(value)) do
+        if restricted(nil, child, seen, depth + 1) then
+            return true
+        end
+    end
+    return false
+end
+--- Checked value transformation. No timers, native widgets or ownership of the input.
+____exports.SourceConverter = __TS__Class()
+local SourceConverter = ____exports.SourceConverter
+SourceConverter.name = "SourceConverter"
+__TS__ClassExtends(SourceConverter, DataSource)
+function SourceConverter.prototype.____constructor(self, input, convert)
+    DataSource.prototype.____constructor(self, nil)
+    self.input = input
+    self.convert = convert
+    self.listeners = __TS__New(Set)
+    self.disposed = false
+    self.blocked = false
+    self.readable = false
+end
+function SourceConverter.prototype.GetValue(self)
+    if self.disposed then
+        error("SourceConverter is disposed")
+    end
+    if self.input.TryCompute ~= nil then
+        local result = self.input:TryCompute(function(____, value) return self:Convert(value) end)
+        if not result.readable then
+            self.blocked = true
+            return nil
+        end
+        return result.value
+    end
+    self.blocked = self.input:IsSecret()
+    if self.blocked then
+        return nil
+    end
+    return self:Convert(self.input.Value)
+end
+function SourceConverter.prototype.Convert(self, value)
+    self.blocked = restricted(nil, value)
+    local ____table_blocked_0
+    if self.blocked then
+        ____table_blocked_0 = nil
+    else
+        ____table_blocked_0 = self:convert(value)
+    end
+    return ____table_blocked_0
+end
+function SourceConverter.prototype.HasSecretFields(self, value)
+    return self.blocked or restricted(nil, value)
+end
+function SourceConverter.prototype.onChange(self, listener)
+    if self.disposed then
+        error("SourceConverter is disposed")
+    end
+    if self.listeners.size == 0 then
+        local value = self:GetValue()
+        self.readable = not self:HasSecretFields(value)
+        local ____table_readable_1
+        if self.readable then
+            ____table_readable_1 = value
+        else
+            ____table_readable_1 = nil
+        end
+        self.previous = ____table_readable_1
+    end
+    self.listeners:add(listener)
+    if self.listeners.size == 1 then
+        do
+            local function ____catch(failure)
+                self.listeners:delete(listener)
+                error(failure, 0)
+            end
+            local ____try, ____hasReturned = pcall(function()
+                local ____this_3
+                ____this_3 = self.input
+                local ____opt_2 = ____this_3.onChange
+                self.stop = ____opt_2 and ____opt_2(
+                    ____this_3,
+                    function() return self:Refresh() end
+                )
+            end)
+            if not ____try then
+                ____catch(____hasReturned)
+            end
+        end
+    end
+    return function()
+        self.listeners:delete(listener)
+        if self.listeners.size == 0 then
+            local ____opt_4 = self.stop
+            if ____opt_4 ~= nil then
+                ____opt_4(self)
+            end
+            self.stop = nil
+        end
+    end
+end
+function SourceConverter.prototype.Refresh(self)
+    local value = self:GetValue()
+    if self:HasSecretFields(value) then
+        self.readable = false
+        return
+    end
+    local same = self.readable and value == self.previous
+    self.previous = value
+    self.readable = true
+    if not same and self:CanEmit(value) then
+        for ____, listener in __TS__Iterator(self.listeners) do
+            listener(nil, value)
+        end
+    end
+end
+function SourceConverter.prototype.BindTo(self, apply)
+    if not self:IsSecret() then
+        local value = self.Value
+        if self:CanEmit(value) then
+            apply(nil, value)
+        end
+    end
+    return self:onChange(apply)
+end
+function SourceConverter.prototype.Dispose(self)
+    if self.disposed then
+        return
+    end
+    self.disposed = true
+    local ____opt_6 = self.stop
+    if ____opt_6 ~= nil then
+        ____opt_6(self)
+    end
+    self.stop = nil
+    self.listeners:clear()
+end
+return ____exports

package/lib/datasources/UnitInfo.d.ts

@@ -8,11 +8,17 @@ export interface ClassInfo {
 }
 export declare class ClassSource extends DataSource<ClassInfo | undefined> {
     private restricted;
+    private readonly listeners;
+    private events?;
+    private stopUnit?;
     readonly target: UnitSource;
     constructor(unit: UnitInput);
     get unit(): string;
     protected HasSecretFields(): boolean;
     protected GetValue(): ClassInfo | undefined;
+    onChange(listener: (value: ClassInfo | undefined) => void): () => void;
+    private StopListening;
+    Dispose(): void;
 }
 export interface SpecializationInfo {
     readonly id: number;