wuira 0.2.4 → 0.2.5

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,34 @@
+# 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.
+
+```ts
+import { ClassSource, SourceConverter, CaseConverter, HP, MathConverter, Unit } from "wuira/datasources";
+
+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.
+
+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.
+
+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.
+
+Converters produce data. They do not grant permission to change protected buttons or their actions during combat.

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

@@ -0,0 +1,6 @@
+import { SourceConverter } from "./SourceConverter";
+import type { ValueSource } from "./SourceConverter";
+export declare class MathConverter extends SourceConverter<number, number> {
+    constructor(input: ValueSource<number>, expression: string);
+    static Validate(expression: string): void;
+}

package/lib/datasources/MathConverter.lua

@@ -0,0 +1,61 @@
+--[[ 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 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
+
+local function __TS__New(target, ...)
+    local instance = setmetatable({}, target.prototype)
+    instance:____constructor(...)
+    return instance
+end
+-- End of Lua Library inline imports
+local ____exports = {}
+local ____SourceConverter = require("datasources.SourceConverter")
+local SourceConverter = ____SourceConverter.SourceConverter
+local ____MathExpression = require("datasources.MathExpression")
+local MathExpression = ____MathExpression.MathExpression
+____exports.MathConverter = __TS__Class()
+local MathConverter = ____exports.MathConverter
+MathConverter.name = "MathConverter"
+__TS__ClassExtends(MathConverter, SourceConverter)
+function MathConverter.prototype.____constructor(self, input, expression)
+    local formula = __TS__New(MathExpression, expression)
+    SourceConverter.prototype.____constructor(
+        self,
+        input,
+        function(____, value) return formula:Evaluate(value) end
+    )
+end
+function MathConverter.Validate(self, expression)
+    __TS__New(MathExpression, expression)
+end
+return ____exports

package/lib/datasources/MathExpression.d.ts

@@ -0,0 +1,16 @@
+/** Small bounded arithmetic grammar. Expressions cannot call functions or execute Lua. */
+export declare class MathExpression {
+    private readonly text;
+    private offset;
+    private token;
+    private tokens;
+    private readonly tree;
+    constructor(text: string);
+    private Next;
+    private Depth;
+    private Add;
+    private Multiply;
+    private Unary;
+    private Primary;
+    Evaluate(input: number): number;
+}

package/lib/datasources/MathExpression.lua

@@ -0,0 +1,281 @@
+--[[ 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 function __TS__StringAccess(self, index)
+    if index >= 0 and index < #self then
+        return string.sub(self, index + 1, index + 1)
+    end
+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__StringSlice(self, start, ____end)
+    if start == nil or start ~= start then
+        start = 0
+    end
+    if ____end ~= ____end then
+        ____end = 0
+    end
+    if start >= 0 then
+        start = start + 1
+    end
+    if ____end ~= nil and ____end < 0 then
+        ____end = ____end - 1
+    end
+    return string.sub(self, start, ____end)
+end
+
+local function __TS__Number(value)
+    local valueType = type(value)
+    if valueType == "number" then
+        return value
+    elseif valueType == "string" then
+        local numberValue = tonumber(value)
+        if numberValue then
+            return numberValue
+        end
+        if value == "Infinity" then
+            return math.huge
+        end
+        if value == "-Infinity" then
+            return -math.huge
+        end
+        local stringWithoutSpaces = string.gsub(value, "%s", "")
+        if stringWithoutSpaces == "" then
+            return 0
+        end
+        return 0 / 0
+    elseif valueType == "boolean" then
+        return value and 1 or 0
+    else
+        return 0 / 0
+    end
+end
+
+local function __TS__NumberIsFinite(value)
+    return type(value) == "number" and value == value and value ~= math.huge and value ~= -math.huge
+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
+-- End of Lua Library inline imports
+local ____exports = {}
+--- Small bounded arithmetic grammar. Expressions cannot call functions or execute Lua.
+____exports.MathExpression = __TS__Class()
+local MathExpression = ____exports.MathExpression
+MathExpression.name = "MathExpression"
+function MathExpression.prototype.____constructor(self, text)
+    self.text = text
+    self.offset = 0
+    self.token = ""
+    self.tokens = 0
+    if issecretvalue(text) or type(text) ~= "string" or #text == 0 or #text > 256 then
+        error("MathConverter: expression must contain 1–256 characters")
+    end
+    self:Next()
+    self.tree = self:Add(0)
+    if self.token ~= "" then
+        error("MathConverter: unexpected token " .. self.token)
+    end
+end
+function MathExpression.prototype.Next(self)
+    local ____self_0, ____tokens_1 = self, "tokens"
+    local ____self_tokens_2 = ____self_0[____tokens_1] + 1
+    ____self_0[____tokens_1] = ____self_tokens_2
+    if ____self_tokens_2 > 128 then
+        error("MathConverter: expression is too complex")
+    end
+    while __TS__StringIncludes(
+        " \t\r\n",
+        __TS__StringAccess(self.text, self.offset) or "\0"
+    ) do
+        self.offset = self.offset + 1
+    end
+    local char = __TS__StringAccess(self.text, self.offset)
+    if char == nil then
+        self.token = ""
+        return
+    end
+    if __TS__StringSlice(self.text, self.offset, self.offset + 5) == "input" then
+        self.offset = self.offset + 5
+        self.token = "input"
+        return
+    end
+    if __TS__StringIncludes("0123456789.", char) then
+        local ____self_3, ____offset_4 = self, "offset"
+        local ____self_offset_5 = ____self_3[____offset_4]
+        ____self_3[____offset_4] = ____self_offset_5 + 1
+        local start = ____self_offset_5
+        while __TS__StringIncludes(
+            "0123456789.",
+            __TS__StringAccess(self.text, self.offset) or "\0"
+        ) do
+            self.offset = self.offset + 1
+        end
+        if __TS__StringAccess(self.text, self.offset) == "e" or __TS__StringAccess(self.text, self.offset) == "E" then
+            self.offset = self.offset + 1
+            if __TS__StringAccess(self.text, self.offset) == "+" or __TS__StringAccess(self.text, self.offset) == "-" then
+                self.offset = self.offset + 1
+            end
+            while __TS__StringIncludes(
+                "0123456789",
+                __TS__StringAccess(self.text, self.offset) or "\0"
+            ) do
+                self.offset = self.offset + 1
+            end
+        end
+        self.token = __TS__StringSlice(self.text, start, self.offset)
+        if not __TS__NumberIsFinite(__TS__Number(self.token)) then
+            error("MathConverter: invalid number")
+        end
+        return
+    end
+    if __TS__StringIncludes("+-*/%^()", char) then
+        self.offset = self.offset + 1
+        self.token = char
+        if char == "*" and __TS__StringAccess(self.text, self.offset) == "*" then
+            self.offset = self.offset + 1
+            self.token = "^"
+        end
+        return
+    end
+    error("MathConverter: only input, numbers and arithmetic operators are allowed")
+end
+function MathExpression.prototype.Depth(self, depth)
+    if depth > 32 then
+        error("MathConverter: expression nesting is too deep")
+    end
+end
+function MathExpression.prototype.Add(self, depth)
+    local left = self:Multiply(depth)
+    while self.token == "+" or self.token == "-" do
+        local operator = self.token
+        self:Next()
+        left = {
+            kind = "binary",
+            operator = operator,
+            left = left,
+            right = self:Multiply(depth)
+        }
+    end
+    return left
+end
+function MathExpression.prototype.Multiply(self, depth)
+    local left = self:Unary(depth)
+    while __TS__ArrayIncludes({"*", "/", "%"}, self.token) do
+        local operator = self.token
+        self:Next()
+        left = {
+            kind = "binary",
+            operator = operator,
+            left = left,
+            right = self:Unary(depth)
+        }
+    end
+    return left
+end
+function MathExpression.prototype.Unary(self, depth)
+    self:Depth(depth)
+    if self.token == "+" or self.token == "-" then
+        local sign = self.token == "-" and -1 or 1
+        self:Next()
+        return {
+            kind = "unary",
+            sign = sign,
+            child = self:Unary(depth + 1)
+        }
+    end
+    local left = self:Primary(depth)
+    if self.token == "^" then
+        self:Next()
+        left = {
+            kind = "binary",
+            operator = "^",
+            left = left,
+            right = self:Unary(depth + 1)
+        }
+    end
+    return left
+end
+function MathExpression.prototype.Primary(self, depth)
+    self:Depth(depth)
+    if self.token == "input" then
+        self:Next()
+        return {kind = "input"}
+    end
+    if self.token == "(" then
+        self:Next()
+        local value = self:Add(depth + 1)
+        if self.token ~= ")" then
+            error("MathConverter: missing closing parenthesis")
+        end
+        self:Next()
+        return value
+    end
+    if self.token ~= "" and __TS__NumberIsFinite(__TS__Number(self.token)) then
+        local value = __TS__Number(self.token)
+        self:Next()
+        return {kind = "number", value = value}
+    end
+    error("MathConverter: expected input, a number or parentheses")
+end
+function MathExpression.prototype.Evaluate(self, input)
+    if issecretvalue(input) or type(input) ~= "number" or not __TS__NumberIsFinite(input) then
+        error("MathConverter: input must be a readable finite number")
+    end
+    local read
+    read = function(____, node)
+        if node.kind == "input" then
+            return input
+        end
+        if node.kind == "number" then
+            return node.value
+        end
+        if node.kind == "unary" then
+            return node.sign * read(nil, node.child)
+        end
+        local left = read(nil, node.left)
+        local right = read(nil, node.right)
+        if (node.operator == "/" or node.operator == "%") and right == 0 then
+            error("MathConverter: division by zero")
+        end
+        local result = node.operator == "+" and left + right or (node.operator == "-" and left - right or (node.operator == "*" and left * right or (node.operator == "/" and left / right or (node.operator == "%" and left % right or left ^ right))))
+        if not __TS__NumberIsFinite(result) then
+            error("MathConverter: result must be finite")
+        end
+        return result
+    end
+    return read(nil, self.tree)
+end
+return ____exports

package/lib/datasources/SourceConverter.d.ts

@@ -0,0 +1,39 @@
+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;
+}
+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);
+}