wuira 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+Notable changes to wuira are recorded here, newest first. Add changes to
+`Unreleased` during development, grouped under Added, Changed, Fixed, or Removed
+as appropriate. When releasing, move those entries into a versioned section
+with the release date and highlight breaking changes explicitly.
+
+## Unreleased
+
+No changes yet.
+
+## 0.1.4 — 2026-10-14
+
+### Added
+
+- Class-based stores with optional stable tokens, one-time readonly snapshots,
+  transactional callback updates, and observer subscriptions.
+- Memory-only stores when no token is declared; SavedVariables-backed records
+  when a token and registry persistence configuration are provided.
+- SavedVariables initialization after the owning addon's `ADDON_LOADED` event,
+  default restoration, collision checks, and serializable data validation.
+
+## 0.1.3 — 2026-10-14
+
+### Added
+
+- A maintained changelog included in the npm package.
+- Buff and debuff sources with caster unit information, explicit source availability,
+  and `Aura.isSourceSelf()` returning `undefined` when ownership is unknown.
+- Target and focus unit constants.
+- Group, party, and raid member sources exposing fresh roster unit tokens,
+  with explicit solo behavior and no duplicate player entry in raids.
+- Player-only class and specialization sources, including native talent-point
+  values when available and explicit GUID-checked inspect requests for other players.
+- Shared `UnitSource` references with live identity and `Is.PC` / `Is.Self`
+  predicates, accepted by class, spec, aura, and resource sources.
+
+### Changed
+
+- Resource and aura constructors accept shared `UnitSource` references while
+  retaining support for string unit arguments.
+
+### Validation and limitations
+
+- Mocked Lua tests cover aura ownership and restrictions, solo/party/raid
+  membership, shared unit identity, and inspect responses after target changes.
+- Forever aura and inspect capabilities still require in-game validation.
+  Inspect is explicit, combat-restricted, and not automatically queued or retried.
+
+## 0.1.2 — 2026-10-14
+
+### Added
+
+- A public `Cell` type shared with the mounting API.
+- Support for `wuira.Mount` callbacks returning `void`, allowing addons without
+  a visual tree to initialize without an empty JSX fragment.
+
+### Changed
+
+- Importing `wuira` automatically installs the global WoW console polyfill.
+- The addon template logs its startup message without creating a visual tree.
+
+### Fixed
+
+- Shared TypeScript configuration explicitly uses Node16 module resolution,
+  allowing package imports and their generated declarations to resolve.
+- Global console declarations load through the shared configuration without
+  requiring DOM typings or an explicit polyfill import in application code.
+
+## 0.1.1 — 2026-10-14
+
+### Added
+
+- Public package imports: `wuira`, `wuira/ui`, and `wuira/datasources`.
+- Generated Lua modules and TypeScript declarations distributed in `lib/`.
+- Shared compiler configuration through `wuira/config/tsconfig.json`.
+- Project templates maintained under `templates/addon/`.
+- `wuira.config.mjs` for addon names and relative or absolute output paths.
+- Standalone addon output containing its TOC and required Lua modules.
+- GitHub Actions CI for Linux and Windows and tag-triggered npm publishing.
+- English documentation with component and CLI examples.
+
+### Changed
+
+- Standardized framework, CLI, configuration, and API names to `wuira`.
+- Converted CLI and build tooling to ESM `.mjs` files.
+- Framework sources and build scripts are no longer copied into generated
+  projects; they consume the installed npm package.
+
+### Removed
+
+- The framework repository's playable addon entry, TOC, and PlayerFrame
+  playground. Addon entries are generated in consumer projects instead.
+
+## 0.1.0 — 2026-10-14
+
+### Added
+
+- Initial public npm release with `wuira create` and `wuira build` commands.
+- TypeScriptToLua compilation with separate Lua modules and a WoW module loader.
+- JSX Cells, flow and grid layouts, and native StatusBar progress bars.
+- Background, border, texture, and glow decorations.
+- Health and mana data sources and a local WoW console polyfill.
+- MIT license and addon project scaffolding.

package/README.md

@@ -94,6 +94,92 @@ function App() {
 wuira.Mount(App);
 ```
 
+### Group members
+
+```ts
+import { GroupMembers, PartyMembers, RaidMembers, Buffs } from "wuira/datasources";
+
+const group = new GroupMembers();
+for (const unit of group.Value) {
+    const buffs = new Buffs(unit);
+    // Apply your own buff-tracking rules to buffs.Value when readable.
+}
+
+const party = new PartyMembers();
+const raid = new RaidMembers();
+```
+
+`GroupMembers` returns `["player"]` while solo, `player` plus `partyN` tokens
+in a party, and `raidN` tokens in a raid. `PartyMembers` is empty outside a
+party; `RaidMembers` is empty outside a raid. The player is included once.
+Offline members are retained. Each `.Value` access reads the current roster;
+there is no automatic subscription, polling, or UI rerender. Read again when
+handling `GROUP_ROSTER_UPDATE`. Tokens may refer to different members after
+roster changes and should not be used as persistent identities.
+
+### Player class and specialization
+
+```ts
+import { UnitSource, ClassSource, SpecSource, Unit } from "wuira/datasources";
+
+const target = new UnitSource(Unit.Target);
+const playerClass = new ClassSource(target);
+const specs = new SpecSource(target);
+
+console.log(target.Is.PC); // boolean | undefined when restricted
+console.log(playerClass.Value?.token);
+specs.RequestInspect();
+// Later, after INSPECT_READY: specs.Value contains native specialization data.
+// Each entry exposes id, name, icon, role, and pointsSpent when provided.
+// Call specs.Dispose() when the owning feature is removed or cancels the request.
+```
+
+These sources accept real players only; NPCs produce no data or inspect request.
+The same `UnitSource` can be passed to `Buffs`, `Debuffs`, `HP`, and `Mana`.
+Its `Value` contains the current token and GUID, rather than a cached identity.
+`Is.PC` and `Is.Self` return `undefined` when their native result is secret.
+String unit tokens are still supported as a convenience shorthand.
+Own specialization data is read directly. Other players require an explicit,
+out-of-combat inspect request and a matching response GUID. An unknown result
+remains `undefined`, and a changed unit token cannot expose another player's
+cached result. Secret values are guarded by the datasource API. Requests are
+not globally queued or automatically retried; callers own cancellation and
+request timing. Inspect permission, range, hostile-player support, and the
+meaning of talent-point fields must be verified on Forever. Being a player
+does not by itself guarantee inspect access.
+
+### Aura ownership
+
+Buff and debuff sources expose fresh snapshots with caster information. Application
+code decides which blessings or other effects should be displayed.
+
+```ts
+import { Buffs, Debuffs, Unit } from "wuira/datasources";
+
+const buffs = new Buffs(Unit.Target);
+const debuffs = new Debuffs(Unit.Target);
+
+buffs.Compute(auras => {
+    for (const aura of auras) {
+        if (aura.isSourceSelf() === true) {
+            console.log(aura.name, "applied by me");
+        } else if (aura.isSourceSelf() === false) {
+            console.log(aura.name, "applied by", aura.sourceUnit);
+        }
+        // undefined means ownership is unknown, not that another player cast it.
+    }
+});
+```
+
+`sourceStatus` is `known`, `unknown`, or `restricted`. Restricted caster values
+are not exposed. Secret spell/name/icon data blocks `.Value` and `.Compute` through
+the normal datasource guard; `.IsSecret()` reports it. Missing native API support
+raises an explicit error instead of returning an apparently empty list. Reads do
+not install event listeners or poll automatically. The current adapter requires
+`C_UnitAuras.GetAuraDataByIndex`; Forever availability and restrictions still need
+in-game verification. Unit tokens refer to snapshot time and are not persistent
+caster identities. No Paladin-specific spell catalog or filtering is built in.
+
 ### Visual styling
 
 <!-- Screenshot: a dark Cell with a thin colored border. -->
@@ -223,6 +309,75 @@ Relative output paths resolve from the project directory. Absolute paths can tar
 
 The CLI, configuration, and build plugin use ESM (`.mjs`). Only Lua and TOC files are needed in game. `npm run build` in the framework repository generates distributable Lua modules and TypeScript declarations in `lib/`; addon builds include the framework modules they import.
 
+## Stores
+
+Use data classes to define defaults. Without a static token, records live only
+in memory and are keyed by the class itself:
+
+```ts
+import { Store, StoreRegistry } from "wuira/store";
+
+class SessionSettings extends Store {
+    CastSpellId = 1232;
+}
+
+const store = new StoreRegistry();
+const snapshot = store.get(SessionSettings); // One-time, deeply readonly copy.
+
+const unsubscribe = store.subscribe(SessionSettings, settings => {
+    console.log("New spell:", settings.CastSpellId);
+});
+
+store.set(SessionSettings, settings => {
+    settings.CastSpellId = 635;
+    return settings;
+});
+
+unsubscribe();
+```
+
+`get()` does not subscribe. `subscribe()` observes future commits and returns an
+unsubscribe function; call `get()` for initial data. Each subscriber receives an
+independent snapshot. `set()` works on a detached draft, validates the returned
+data, commits it, and sends one notification per observer. If the updater throws,
+the previous record is preserved. Stores contain data fields, not class methods.
+
+For persistence, declare a stable token and the owning addon's SavedVariables:
+
+```toc
+## SavedVariables: LumaUIDB
+```
+
+```ts
+class LumaSettings extends Store {
+    static readonly Token = "luma.settings";
+    CastSpellId = 1232;
+    Width = 220;
+}
+
+const store = new StoreRegistry({ addon: "LumaUI", variable: "LumaUIDB" });
+store.onReady(() => {
+    console.log(store.get(LumaSettings).Width);
+    store.set(LumaSettings, settings => {
+        settings.Width = 240;
+        return settings;
+    });
+});
+```
+
+Add the TOC declaration to the addon's `addon.toc.in`. The registry waits for
+`ADDON_LOADED` before opening persistent records. Tokenless records can still be
+used immediately. WoW writes the saved table on normal logout/reload; `set()`
+does not force a disk flush. Keep tokens stable across versions. New default
+fields are filled in and incompatible saved field types fall back to defaults;
+renaming keys or changing schema meaning still requires an application migration.
+
+Supported values are finite numbers, strings, booleans, arrays, and nested data
+objects. Functions, cycles, and secret values cannot be saved. Two classes cannot
+claim the same token within a registry. Share one registry instance per database.
+`Dispose()` removes its observers and pending initialization listener. Profile
+selection, schema migrations, and reactive widget binding are separate features.
+
 ## Development
 
 ```sh
@@ -240,6 +395,9 @@ Licensed under MIT; see [LICENSE](LICENSE).
 
 ## Releases
 
+See [CHANGELOG.md](CHANGELOG.md) for release history. Record new changes under
+`Unreleased`, then move them into a dated version section before publishing.
+
 The first version is published. To publish the next version locally, validate the project, increment the patch version, and publish:
 
 ```sh

package/lib/datasources/Auras.d.ts

@@ -0,0 +1,32 @@
+import { DataSource } from "./DataSource";
+import { UnitSource } from "./UnitSource";
+import type { UnitInput } from "./UnitSource";
+export type AuraSourceStatus = "known" | "unknown" | "restricted";
+/** Readable aura snapshot. Unit tokens describe the source at snapshot time. */
+export declare class Aura {
+    readonly spellId: number;
+    readonly name: string;
+    readonly icon: number;
+    readonly sourceUnit: string | undefined;
+    readonly sourceStatus: AuraSourceStatus;
+    private readonly sourceSelf;
+    constructor(spellId: number, name: string, icon: number, sourceUnit: string | undefined, sourceStatus: AuraSourceStatus, sourceSelf: boolean | undefined);
+    /** Undefined means ownership could not be established; it does not mean another caster. */
+    isSourceSelf(): boolean | undefined;
+}
+/** Reads a fresh snapshot on access; it does not install listeners or poll. */
+export declare abstract class AuraSource extends DataSource<readonly Aura[]> {
+    private readonly filter;
+    private restricted;
+    readonly target: UnitSource;
+    protected constructor(unit: UnitInput, filter: "HELPFUL" | "HARMFUL");
+    get unit(): string;
+    protected HasSecretFields(): boolean;
+    protected GetValue(): readonly Aura[];
+}
+export declare class Buffs extends AuraSource {
+    constructor(unit: UnitInput);
+}
+export declare class Debuffs extends AuraSource {
+    constructor(unit: UnitInput);
+}

package/lib/datasources/Auras.lua

@@ -0,0 +1,284 @@
+--[[ 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
+
+local function __TS__CloneDescriptor(____bindingPattern0)
+    local value
+    local writable
+    local set
+    local get
+    local configurable
+    local enumerable
+    enumerable = ____bindingPattern0.enumerable
+    configurable = ____bindingPattern0.configurable
+    get = ____bindingPattern0.get
+    set = ____bindingPattern0.set
+    writable = ____bindingPattern0.writable
+    value = ____bindingPattern0.value
+    local descriptor = {enumerable = enumerable == true, configurable = configurable == true}
+    local hasGetterOrSetter = get ~= nil or set ~= nil
+    local hasValueOrWritableAttribute = writable ~= nil or value ~= nil
+    if hasGetterOrSetter and hasValueOrWritableAttribute then
+        error("Invalid property descriptor. Cannot both specify accessors and a value or writable attribute.", 0)
+    end
+    if get or set then
+        descriptor.get = get
+        descriptor.set = set
+    else
+        descriptor.value = value
+        descriptor.writable = writable == true
+    end
+    return descriptor
+end
+
+local __TS__DescriptorGet
+do
+    local getmetatable = _G.getmetatable
+    local ____rawget = _G.rawget
+    function __TS__DescriptorGet(self, metatable, key)
+        while metatable do
+            local rawResult = ____rawget(metatable, key)
+            if rawResult ~= nil then
+                return rawResult
+            end
+            local descriptors = ____rawget(metatable, "_descriptors")
+            if descriptors then
+                local descriptor = descriptors[key]
+                if descriptor ~= nil then
+                    if descriptor.get then
+                        return descriptor.get(self)
+                    end
+                    return descriptor.value
+                end
+            end
+            metatable = getmetatable(metatable)
+        end
+    end
+end
+
+local __TS__DescriptorSet
+do
+    local getmetatable = _G.getmetatable
+    local ____rawget = _G.rawget
+    local rawset = _G.rawset
+    function __TS__DescriptorSet(self, metatable, key, value)
+        while metatable do
+            local descriptors = ____rawget(metatable, "_descriptors")
+            if descriptors then
+                local descriptor = descriptors[key]
+                if descriptor ~= nil then
+                    if descriptor.set then
+                        descriptor.set(self, value)
+                    else
+                        if descriptor.writable == false then
+                            error(
+                                ((("Cannot assign to read only property '" .. key) .. "' of object '") .. tostring(self)) .. "'",
+                                0
+                            )
+                        end
+                        descriptor.value = value
+                    end
+                    return
+                end
+            end
+            metatable = getmetatable(metatable)
+        end
+        rawset(self, key, value)
+    end
+end
+
+local __TS__SetDescriptor
+do
+    local getmetatable = _G.getmetatable
+    local function descriptorIndex(self, key)
+        return __TS__DescriptorGet(
+            self,
+            getmetatable(self),
+            key
+        )
+    end
+    local function descriptorNewIndex(self, key, value)
+        return __TS__DescriptorSet(
+            self,
+            getmetatable(self),
+            key,
+            value
+        )
+    end
+    function __TS__SetDescriptor(target, key, desc, isPrototype)
+        if isPrototype == nil then
+            isPrototype = false
+        end
+        local ____isPrototype_0
+        if isPrototype then
+            ____isPrototype_0 = target
+        else
+            ____isPrototype_0 = getmetatable(target)
+        end
+        local metatable = ____isPrototype_0
+        if not metatable then
+            metatable = {}
+            setmetatable(target, metatable)
+        end
+        if not isPrototype and not rawget(metatable, "_isOwnDescriptorMetatable") then
+            local instanceMetatable = {}
+            instanceMetatable._isOwnDescriptorMetatable = true
+            setmetatable(instanceMetatable, metatable)
+            setmetatable(target, instanceMetatable)
+            metatable = instanceMetatable
+        end
+        local value = rawget(target, key)
+        if value ~= nil then
+            rawset(target, key, nil)
+        end
+        if not rawget(metatable, "_descriptors") then
+            metatable._descriptors = {}
+        end
+        metatable._descriptors[key] = __TS__CloneDescriptor(desc)
+        metatable.__index = descriptorIndex
+        metatable.__newindex = descriptorNewIndex
+    end
+end
+-- End of Lua Library inline imports
+local ____exports = {}
+local ____DataSource = require("datasources.DataSource")
+local DataSource = ____DataSource.DataSource
+local ____UnitSource = require("datasources.UnitSource")
+local resolveUnit = ____UnitSource.resolveUnit
+--- Readable aura snapshot. Unit tokens describe the source at snapshot time.
+____exports.Aura = __TS__Class()
+local Aura = ____exports.Aura
+Aura.name = "Aura"
+function Aura.prototype.____constructor(self, spellId, name, icon, sourceUnit, sourceStatus, sourceSelf)
+    self.spellId = spellId
+    self.name = name
+    self.icon = icon
+    self.sourceUnit = sourceUnit
+    self.sourceStatus = sourceStatus
+    self.sourceSelf = sourceSelf
+end
+function Aura.prototype.isSourceSelf(self)
+    return self.sourceSelf
+end
+--- Reads a fresh snapshot on access; it does not install listeners or poll.
+____exports.AuraSource = __TS__Class()
+local AuraSource = ____exports.AuraSource
+AuraSource.name = "AuraSource"
+__TS__ClassExtends(AuraSource, DataSource)
+function AuraSource.prototype.____constructor(self, unit, filter)
+    DataSource.prototype.____constructor(self, {})
+    self.filter = filter
+    self.restricted = false
+    self.target = resolveUnit(nil, unit)
+end
+function AuraSource.prototype.HasSecretFields(self)
+    return self.restricted
+end
+function AuraSource.prototype.GetValue(self)
+    self.restricted = false
+    local read = C_UnitAuras and C_UnitAuras.GetAuraDataByIndex
+    if read == nil then
+        error("AuraSource: this client does not expose C_UnitAuras.GetAuraDataByIndex")
+    end
+    local result = {}
+    do
+        local index = 1
+        while index <= 1024 do
+            local raw = read(self.unit, index, self.filter)
+            if issecretvalue(raw) then
+                self.restricted = true
+                return {}
+            end
+            if raw == nil then
+                return result
+            end
+            if issecretvalue(raw.spellId) or issecretvalue(raw.name) or issecretvalue(raw.icon) then
+                self.restricted = true
+                return {}
+            end
+            local sourceUnit
+            local sourceSelf
+            local status = "unknown"
+            if issecretvalue(raw.sourceUnit) then
+                status = "restricted"
+            elseif raw.sourceUnit ~= nil then
+                sourceUnit = raw.sourceUnit
+                status = "known"
+                local ____self = UnitIsUnit(sourceUnit, "player")
+                if not issecretvalue(____self) then
+                    sourceSelf = ____self
+                end
+            end
+            result[#result + 1] = __TS__New(
+                ____exports.Aura,
+                raw.spellId,
+                raw.name,
+                raw.icon,
+                sourceUnit,
+                status,
+                sourceSelf
+            )
+            index = index + 1
+        end
+    end
+    error("AuraSource: aura enumeration exceeded its safety limit")
+end
+__TS__SetDescriptor(
+    AuraSource.prototype,
+    "unit",
+    {get = function(self)
+        return self.target.Token
+    end},
+    true
+)
+____exports.Buffs = __TS__Class()
+local Buffs = ____exports.Buffs
+Buffs.name = "Buffs"
+__TS__ClassExtends(Buffs, ____exports.AuraSource)
+function Buffs.prototype.____constructor(self, unit)
+    Buffs.____super.prototype.____constructor(self, unit, "HELPFUL")
+end
+____exports.Debuffs = __TS__Class()
+local Debuffs = ____exports.Debuffs
+Debuffs.name = "Debuffs"
+__TS__ClassExtends(Debuffs, ____exports.AuraSource)
+function Debuffs.prototype.____constructor(self, unit)
+    Debuffs.____super.prototype.____constructor(self, unit, "HARMFUL")
+end
+return ____exports

package/lib/datasources/GroupMembers.d.ts

@@ -0,0 +1,18 @@
+import { DataSource } from "./DataSource";
+export type GroupScope = "auto" | "party" | "raid";
+/** Fresh roster tokens, including offline members. Tokens are not persistent identities. */
+export declare class GroupMembers extends DataSource<readonly string[]> {
+    readonly scope: GroupScope;
+    private restricted;
+    constructor(scope?: GroupScope);
+    protected HasSecretFields(): boolean;
+    protected GetValue(): readonly string[];
+}
+/** Includes the player in a party; empty when solo or in a raid. */
+export declare class PartyMembers extends GroupMembers {
+    constructor();
+}
+/** Includes the player through their raidN token; empty outside a raid. */
+export declare class RaidMembers extends GroupMembers {
+    constructor();
+}