wuira 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Uira contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,255 @@
-# Temporary Holding Version
+# wuira
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build WoW Forever interfaces with TypeScript and JSX.
+
+wuira is a UI framework and addon toolchain for developers who want to describe their interface in code, compose reusable components, and keep game data separate from presentation. Write TypeScript, arrange native widgets with JSX, and compile your addon to Lua.
+
+## Why wuira?
+
+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.
+
+### JSX composition
+
+<!-- Screenshot: a reusable ResourceBar component inside a Cell. -->
+
+Describe UI trees with components and reusable functions. No separate XML view files are required.
+
+```tsx
+function ResourceBar({ current }: { current: number }) {
+    return <progress width="inherit" height={24} min={0} max={100} current={current} />;
+}
+
+function App() {
+    return (
+        <cell width={200} height={40} padding={8}>
+            <ResourceBar current={75} />
+        </cell>
+    );
+}
+
+wuira.Mount(App);
+```
+
+### Native widgets
+
+<!-- Screenshot: a native StatusBar with a dark background. -->
+
+Cells mount to WoW frames, and progress bars use the game's native StatusBar widget.
+
+```tsx
+const view = (
+    <progress
+        width={200} height={24}
+        min={0} max={100} current={65}
+        foreground={{ color: { r: 0.1, g: 0.75, b: 0.4 } }}
+        background={{ color: { r: 0.08, g: 0.08, b: 0.08 } }}
+    />
+);
+
+wuira.Mount(view);
+```
+
+### Layout primitives
+
+<!-- Screenshot: two vertically stacked progress bars with a gap. -->
+
+Flow and grid layouts arrange children, with spacing and sizing options shared across components.
+
+```tsx
+const view = (
+    <flow width={200} height={56} direction="vertical" gap={8}>
+        <progress height={24} min={0} max={100} current={80} />
+        <progress height={24} min={0} max={100} current={45} />
+    </flow>
+);
+
+wuira.Mount(view);
+```
+
+For rows and columns, use `<grid columns={2} gap={8}>` with an explicit width and height.
+
+### Data sources
+
+<!-- Screenshot: live player health and mana bars. -->
+
+Connect health and mana values to progress bars without writing a separate resource-specific container class.
+
+```tsx
+import { HP, Mana, Unit } from "wuira/datasources";
+
+function App() {
+    const hp = new HP(Unit.Player);
+    const mana = new Mana(Unit.Player);
+
+    return (
+        <flow width={200} height={52} direction="vertical" gap={4}>
+            <progress height={24} source={hp} />
+            <progress height={24} source={mana} />
+        </flow>
+    );
+}
+
+wuira.Mount(App);
+```
+
+### Visual styling
+
+<!-- Screenshot: a dark Cell with a thin colored border. -->
+
+Configure backgrounds, borders, textures, and glow through reusable decoration objects.
+
+```tsx
+import { Background, Border } from "wuira/ui";
+
+
+const view = (
+    <cell width={200} height={64} decorations={{
+        background: new Background({ color: { r: 0.06, g: 0.08, b: 0.1 } }),
+        border: new Border({ thickness: 1, color: { r: 0.3, g: 0.8, b: 0.7 } }),
+    }} />
+);
+
+wuira.Mount(view);
+```
+
+### Addon tooling
+
+<!-- Screenshot: creating and building an addon in the terminal. -->
+
+Create a project, compile TypeScriptToLua, and generate the TOC and module-loading files through one CLI.
+
+```sh
+npx wuira@latest create MyAddon
+cd MyAddon
+npm install
+npm run build
+```
+
+### Readable Lua output
+
+<!-- Screenshot: source files alongside their emitted Lua modules. -->
+
+Emitted modules remain split across files following the source structure.
+
+```text
+src/index.tsx            → dist/index.lua
+src/components/Panel.tsx → dist/components/Panel.lua
+wuira/ui dependency     → dist/lua_modules/wuira/lib/ui/index.lua
+
+MyAddon.toc loads the module registry, emitted files, and startup entry.
+```
+
+Use wuira when you want to build and distribute an addon UI in TypeScript, share visual components, and let the toolchain handle Lua module loading. Node.js runs during development; the game loads the generated Lua files without a JavaScript runtime.
+
+## Scope and current status
+
+wuira is an early framework for addon authors. 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.
+
+The current core includes Cells, flow and grid layouts, progress bars, decorations, health and mana sources, a local console polyfill, and project tooling. A complete WoW API surface, secure action and click-cast abstractions, nameplate adapters, and preset management are not implemented yet. Combat restrictions and secret-value rules still apply; framework abstractions cannot bypass them.
+
+The target client is WoW Forever. Compatibility with Retail or other Classic clients is not promised without verification. Expect API changes while the framework takes shape.
+
+## Getting started
+
+The framework, npm package, CLI command, and public API are named `wuira`. Future extension packages can use the `@wuira/` organization scope once that organization is registered.
+
+Available on npm as [`wuira`](https://www.npmjs.com/package/wuira):
+
+```sh
+npx wuira create MyAddon
+```
+
+A TypeScript and JSX UI framework for WoW Forever. TypeScriptToLua emits separate Lua files following the source directory structure. No Rollup or single-file Lua bundle is required.
+
+## CLI
+
+Create an addon with Node.js 22.13 or newer:
+
+```sh
+npx wuira@latest create MyAddon
+cd MyAddon
+npm install
+npm run build
+```
+
+Alternatively, install globally with `npm install -g wuira`, then use `wuira create MyAddon`. To test unpublished changes, run `npm install` and `npm link` in this repository, or invoke `node /path/to/wuira/cli/wuira.mjs create MyAddon` directly. Templates reflect the installed CLI version; repository changes become available through npm after the next release.
+
+`create` refuses to overwrite an existing directory. It generates TypeScriptToLua configuration, addon metadata, a module loader, an MIT license, and this minimal `src/index.tsx`:
+
+```tsx
+import "wuira/console-polyfill";
+import { UI, wuira } from "wuira";
+
+
+function App() {
+    console.log("MyAddon loaded");
+    return <></>;
+}
+
+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.
+
+## Build and distribution
+
+`wuira build` transpiles through `tsconfig.json`. It writes a standalone addon directory containing individual Lua modules, a loader, a startup file, and `<addonName>.toc`. The default output directory is `dist/`. The addon name lives in `wuira.config.mjs`; Interface version and other metadata live in `addon.toc.in`. The default Interface version, 16001, targets the Forever playground.
+
+Copy the contents of `dist/` to `Interface/AddOns/<addonName>/`, or configure the build to output there directly. No Node.js runtime or separate wuira addon is required in game. Module registries are isolated by addon name.
+
+Framework code and generated `.d.ts` declarations come from the installed npm package. Import UI components from `wuira/ui`, data sources from `wuira/datasources`, and the mounting API from `wuira`. No framework source files or build scripts are copied into addon projects. This repository contains only the framework and CLI; addon entry points and TOC metadata are generated in consumer projects.
+
+Project templates live in `templates/addon/`. Generated projects depend on `wuira` and extend `wuira/config/tsconfig.json`. Shared settings and the TSTL module plugin stay in the installed package; build scripts are not copied into projects. Project-local `rootDir`, `outDir`, and source includes remain in the generated `tsconfig.json`.
+
+`npm run build` resolves the locally installed `wuira` command automatically. Use `npx wuira build` when invoking the CLI directly.
+
+Configure the addon output in `wuira.config.mjs`:
+
+```js
+export default {
+    name: "MyAddon",
+    outDir: "./dist",
+    // Or: outDir: "G:/Games/WoW/Interface/AddOns/MyAddon",
+};
+```
+
+Relative output paths resolve from the project directory. Absolute paths can target the game's addon directory, keeping the development project elsewhere. Builds compile into a temporary staging directory before copying successful output to the destination. Existing files with matching names are overwritten; unrelated files are retained. The emitted TOC uses paths relative to the output folder, so the entire folder can be moved independently.
+
+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.
+
+## Development
+
+```sh
+npm ci
+npm run build
+npm run check
+npm test
+```
+
+`.github/workflows/ci.yml` runs type checks, builds, tests, and a package dry run on pushes and pull requests, on both Linux and Windows with Node.js 22. CI does not publish packages and requires no npm token.
+
+Cell is the basic visual box. FlowLayout and GridLayout arrange children. ProgressBar uses a native StatusBar, while data sources connect values to presentation. Behavior from other WoW versions must be verified against the Forever API before use.
+
+Licensed under MIT; see [LICENSE](LICENSE).
+
+## Releases
+
+The first version is published. To publish the next version locally, validate the project, increment the patch version, and publish:
+
+```sh
+npm run check
+npm run build
+npm test
+npm version patch --no-git-tag-version
+npm publish --access public
+```
+
+Publishing requires npm authentication and 2FA, or a granular access token with write access and Bypass 2FA enabled. Commit both `package.json` and `package-lock.json` after changing the version. npm versions cannot be published twice.
+
+For future automated releases, every pushed Git tag triggers `.github/workflows/publish.yml`. It checks types, builds, tests, and publishes to npm. Tags must match `package.json` version, optionally prefixed with `v`. Do not push a release tag for a version already published locally; the workflow would attempt to publish it again.
+
+To enable automated publishing, configure the GitHub repository secret `NPM_TOKEN` with an npm granular access token authorized to publish `wuira` and bypass 2FA. Never commit the token. GitHub Actions must be enabled. Local setup does not publish a package or push a tag.

package/cli/wuira.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const require = createRequire(import.meta.url);
+const root = path.resolve(import.meta.dirname, "..");
+
+export function create(name, cwd = process.cwd()) {
+  if (!name || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) throw new Error("Use an addon name containing letters, numbers, underscores or hyphens, starting with a letter.");
+  const target = path.join(cwd, name);
+  if (fs.existsSync(target)) throw new Error(`Destination already exists: ${target}`);
+  fs.mkdirSync(target, { recursive: true });
+  const version = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+  const variables = { addonName: name, packageName: name.toLowerCase(), frameworkVersion: version };
+  const template = path.join(root, "templates/addon");
+  for (const entry of fs.readdirSync(template, { recursive: true, withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const source = path.join(entry.parentPath, entry.name);
+    const relative = path.relative(template, source);
+    const destination = path.join(target, relative === "gitignore" ? ".gitignore" : relative);
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    const content = fs.readFileSync(source, "utf8").replace(/\{\{(\w+)\}\}/g, (_, key) => {
+      if (!(key in variables)) throw new Error(`Unknown template variable: ${key}`);
+      return variables[key];
+    });
+    fs.writeFileSync(destination, content);
+  }
+  fs.copyFileSync(path.join(root, "LICENSE"), path.join(target, "LICENSE"));
+  return target;
+}
+
+export async function build(cwd = process.cwd()) {
+  if (!fs.existsSync(path.join(cwd, "tsconfig.json"))) throw new Error("Run wuira build inside an addon project.");
+  const configFile = path.join(cwd, "wuira.config.mjs");
+  const config = fs.existsSync(configFile) ? (await import(pathToFileURL(configFile).href + `?updated=${fs.statSync(configFile).mtimeMs}`)).default : {};
+  if (config === null || typeof config !== "object") throw new Error("wuira.config.mjs must export a configuration object.");
+  if (config.outDir !== undefined && (typeof config.outDir !== "string" || config.outDir.trim() === "")) throw new Error("outDir must be a nonempty path.");
+  const output = path.resolve(cwd, config.outDir ?? "dist");
+  if (output === path.parse(output).root || output === path.resolve(cwd)) throw new Error("Choose a dedicated addon output directory.");
+  const stage = fs.mkdtempSync(path.join(os.tmpdir(), "wuira-build-"));
+  const compiler = require.resolve("typescript-to-lua/dist/tstl.js", { paths: [cwd, root] });
+  try {
+    const result = spawnSync(process.execPath, [compiler, "-p", "tsconfig.json", "--outDir", stage], {
+      cwd, stdio: "inherit", env: { ...process.env, WUIRA_STANDALONE: "1", ...(config.name ? { WUIRA_ADDON_NAME: config.name } : {}) },
+    });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw new Error("Addon build failed.");
+    fs.mkdirSync(output, { recursive: true });
+    fs.cpSync(stage, output, { recursive: true });
+    console.log(`Built addon: ${output}`);
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const [command, name] = process.argv.slice(2);
+    if (command === "create") console.log(`Created ${create(name)}\nNext: cd ${name}, npm install, wuira build`);
+    else if (command === "build") await build();
+    else if (!command || command === "--help") console.log("wuira create <addonName>\nwuira build");
+    else throw new Error(`Unknown command: ${command}`);
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/config/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://raw.githubusercontent.com/TypeScriptToLua/TypeScriptToLua/master/tsconfig-schema.json",
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": [
+      "ESNext"
+    ],
+    "types": [],
+    "jsx": "react",
+    "jsxFactory": "UI.createElement",
+    "jsxFragmentFactory": "UI.Fragment",
+    "strict": true,
+    "noEmitOnError": true
+  },
+  "tstl": {
+    "luaTarget": "universal",
+    "luaLibImport": "inline",
+    "noImplicitGlobalVariables": true,
+    "luaPlugins": [
+      {
+        "name": "wuira/tools/wow-modules.mjs"
+      }
+    ]
+  }
+}

package/lib/Console.d.ts

@@ -0,0 +1,5 @@
+/** Local client output only; never sends chat messages to other players. */
+export declare class Console {
+    private constructor();
+    static Echo(message: string): void;
+}

package/lib/Console.lua

@@ -0,0 +1,20 @@
+--[[ 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
+-- End of Lua Library inline imports
+local ____exports = {}
+--- Local client output only; never sends chat messages to other players.
+____exports.Console = __TS__Class()
+local Console = ____exports.Console
+Console.name = "Console"
+function Console.prototype.____constructor(self)
+end
+function Console.Echo(self, message)
+    print("|cff60d9c5[wuira]|r " .. message)
+end
+return ____exports

package/lib/console-polyfill.d.ts

@@ -0,0 +1,9 @@
+declare global {
+    const console: {
+        log(this: void, ...values: unknown[]): void;
+        info(this: void, ...values: unknown[]): void;
+        warn(this: void, ...values: unknown[]): void;
+        error(this: void, ...values: unknown[]): void;
+    };
+}
+export {};

package/lib/console-polyfill.lua

@@ -0,0 +1,39 @@
+--[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]
+-- Lua Library inline imports
+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 function write(self, color, values)
+    print((color .. table.concat(
+        __TS__ArrayMap(
+            values,
+            function(____, value) return tostring(value) end
+        ),
+        " "
+    )) .. "|r")
+end
+_G.console = {
+    log = function(...)
+        local values = {...}
+        write(nil, "|cffffffff", values)
+    end,
+    info = function(...)
+        local values = {...}
+        write(nil, "|cff60d9c5", values)
+    end,
+    warn = function(...)
+        local values = {...}
+        write(nil, "|cffffcc00", values)
+    end,
+    error = function(...)
+        local values = {...}
+        write(nil, "|cffff5555", values)
+    end
+}
+return ____exports

package/lib/datasources/DataSource.d.ts

@@ -0,0 +1,17 @@
+/** A value-producing source. Secrecy describes data, not native frame protection. */
+export declare abstract class DataSource<T> {
+    private value;
+    private secret;
+    protected constructor(value: T, secret?: boolean);
+    /** Checked when consumed, rather than inferred from combat state. */
+    IsSecret(): boolean;
+    get Value(): T;
+    Compute<TResult>(compute: (value: T) => TResult): TResult;
+    protected GetValue(): T;
+    private IsValueSecret;
+    /** Replace the value and its explicit restriction together, clearing stale flags. */
+    protected SetValue(value: T, secret?: boolean): void;
+    /** Aggregate sources override this to check known fields without comparing them. */
+    protected HasSecretFields(_value: T): boolean;
+    private AssertReadable;
+}

package/lib/datasources/DataSource.lua

@@ -0,0 +1,199 @@
+--[[ 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__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 = {}
+--- A value-producing source. Secrecy describes data, not native frame protection.
+____exports.DataSource = __TS__Class()
+local DataSource = ____exports.DataSource
+DataSource.name = "DataSource"
+function DataSource.prototype.____constructor(self, value, secret)
+    if secret == nil then
+        secret = false
+    end
+    self.value = value
+    self.secret = secret
+end
+function DataSource.prototype.IsSecret(self)
+    return self:IsValueSecret(self:GetValue())
+end
+function DataSource.prototype.Compute(self, compute)
+    local value = self:GetValue()
+    self:AssertReadable(value)
+    return compute(nil, value)
+end
+function DataSource.prototype.GetValue(self)
+    return self.value
+end
+function DataSource.prototype.IsValueSecret(self, value)
+    return issecretvalue(value) or self.secret or self:HasSecretFields(value)
+end
+function DataSource.prototype.SetValue(self, value, secret)
+    if secret == nil then
+        secret = false
+    end
+    self.value = value
+    self.secret = secret
+end
+function DataSource.prototype.HasSecretFields(self, _value)
+    return false
+end
+function DataSource.prototype.AssertReadable(self, value)
+    if self:IsValueSecret(value) then
+        error("DataSource: secret data cannot be read or used in computations")
+    end
+end
+__TS__SetDescriptor(
+    DataSource.prototype,
+    "Value",
+    {get = function(self)
+        local value = self:GetValue()
+        self:AssertReadable(value)
+        return value
+    end},
+    true
+)
+return ____exports

package/lib/datasources/NativeNumberSource.d.ts

@@ -0,0 +1,7 @@
+import { DataSource } from "./DataSource";
+/** Read-only API value; no cached assignment or game-state mutation. */
+export declare class NativeNumberSource extends DataSource<number> {
+    private readonly read;
+    constructor(read: () => number);
+    protected GetValue(): number;
+}