uesp-eso-build-wrapper 0.3.0 → 0.5.0

package/README.md

@@ -1,21 +1,53 @@
 # uesp-eso-build-wrapper
 
 [![CI](https://github.com/srtomy/uesp-eso-build-wrapper/actions/workflows/ci.yml/badge.svg)](https://github.com/srtomy/uesp-eso-build-wrapper/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/srtomy/uesp-eso-build-wrapper/graph/badge.svg)](https://codecov.io/gh/srtomy/uesp-eso-build-wrapper)
 [![npm](https://img.shields.io/npm/v/uesp-eso-build-wrapper.svg)](https://www.npmjs.com/package/uesp-eso-build-wrapper)
+[![Docs](https://img.shields.io/badge/docs-online-2564eb)](https://srtomy.github.io/uesp-eso-build-wrapper/)
+[![Bundlephobia](https://img.shields.io/bundlephobia/minzip/uesp-eso-build-wrapper)](https://bundlephobia.com/package/uesp-eso-build-wrapper)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Node >=20.12](https://img.shields.io/badge/node-%3E%3D20.12-brightgreen)](https://nodejs.org/en/download/)
+[![Node >=24](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org/en/download/)
+
+> **Leia em [Português (BR)](README.pt-BR.md).**
 
 A Node.js/TypeScript wrapper around the [UESP ESO Build Editor](https://github.com/uesp/uesp-esochardata) math engine.
 
 Calculate Elder Scrolls Online **Computed Character Statistics** — Health, Magicka, Stamina, mitigation, crit chance, regeneration, and 200+ more — using UESP's own formulas. No formula reimplementation.
 
-## Features
+## What is this?
+
+This is **not an HTTP client for UESP**. It runs the vendored UESP build calculation engine **locally, inside your Node.js process**, and exposes the results through a typed API:
+
+```text
+Application
+    ↓
+uesp-eso-build-wrapper (TypeScript API)
+    ↓
+Node.js compatibility layer (browser-like globals + minimal DOM)
+    ↓
+UESP esoEditBuild.js (executed in-process via vm.runInThisContext)
+    ↓
+UESP calculation functions → ComputedStats
+```
+
+You inject the inputs, UESP's own code computes every stat, you read back one typed object.
+
+## Why this library?
 
-- ✅ **100% UESP formulas** — same engine powering [esobuilds.uesp.net](https://esobuilds.uesp.net)
-- ✅ **221 computed stats** — all `Computed Character Statistics` from the build editor
-- ✅ **Zero runtime dependencies** — pure Node.js
-- ✅ **Full TypeScript types** — typed inputs and outputs
-- ✅ **Singleton loader** — loads the engine once per process, fast on subsequent calls
+- **Reference accuracy** — same `esoEditBuild.js` engine that powers [esobuilds.uesp.net](https://esobuilds.uesp.net), kept up to date by UESP every patch.
+- **No formula reimplementation** — the wrapper contains zero ESO math. When a stat looks wrong after a patch, the fix is always in the game *data* fed to the engine, never in wrapper code. That is what keeps it correct across patches.
+- **Local and synchronous** — `calculateBuild()` performs no network requests. The engine runs in-process; game data and items are supplied by your application (file, database, generated data).
+- **Accepts UESP item data directly** — gear in the [`exportJson.php?table=minedItem`](https://esolog.uesp.net) format plugs straight into `BuildInput.items`.
+- **TypeScript-native** — typed inputs/outputs, TSDoc-documented [API Reference](https://srtomy.github.io/uesp-eso-build-wrapper/api/), plus runtime catalog functions (`listAvailableBuffs`, `listRacialPassives`, …) to discover valid names.
+
+## Key properties
+
+- Runs the vendored UESP calculation engine locally (`vendor/uesp-esochardata`)
+- **No network required for build calculations** — see [Does it require an internet connection?](https://srtomy.github.io/uesp-eso-build-wrapper/architecture#does-it-require-an-internet-connection)
+- Does not reimplement ESO stat formulas
+- Synchronous API; engine initializes once per process (singleton, subsequent calls are no-ops)
+- Zero runtime dependencies — pure Node.js
+- 221 computed stats per build
 
 ## Installation
 
@@ -25,21 +57,18 @@ npm install uesp-eso-build-wrapper
 
 ## Quick Start
 
-Game data is not bundled in the npm package — you supply it via `initEsoEngineFromData`.  
-The bundled `vendor/uesp-data/uesp-game-data.json` (committed to this repo) is the canonical source.
+Game data is not bundled in the npm package — you supply it via `initEsoEngineFromData` (see [Getting Started](https://srtomy.github.io/uesp-eso-build-wrapper/getting-started)).
 
 ```ts
 import fs from 'fs';
 import { initEsoEngineFromData, calculateBuild } from 'uesp-eso-build-wrapper';
 import type { UespInitData } from 'uesp-eso-build-wrapper';
 
-// Load game data generated by: npm run generate-data -- --db /path/to/local.db
 const initData = JSON.parse(
-  fs.readFileSync('vendor/uesp-data/uesp-game-data.json', 'utf-8')
+  fs.readFileSync('uesp-game-data.json', 'utf-8'),
 ) as UespInitData;
 
-// Initialize once per process (no-op on subsequent calls)
-initEsoEngineFromData({ initData });
+initEsoEngineFromData({ initData }); // once per process
 
 const stats = calculateBuild({
   character: {
@@ -52,260 +81,37 @@ const stats = calculateBuild({
 
 console.log(stats.Health);       // 16000
 console.log(stats.Magicka);      // 19104
-console.log(stats.MagickaRegen); // 514
 console.log(stats.SpellDamage);  // 1000
 ```
 
-## With Equipped Items
-
-Items are passed directly as returned by the [UESP public item API](https://esolog.uesp.net/exportJson.php?table=minedItem&id=70&level=50&quality=5).
-
-```ts
-const res = await fetch(
-  'https://esolog.uesp.net/exportJson.php?table=minedItem&id=70&level=50&quality=5',
-);
-const data = await res.json();
-const item = data.minedItem[0];
-
-const stats = calculateBuild({
-  character: {
-    race: 'Nord',
-    class: 'Dragonknight',
-    level: 50,
-    attributes: { health: 64, magicka: 0, stamina: 0 },
-  },
-  items: {
-    Chest: item,
-  },
-});
-
-console.log(stats.Health); // includes item enchant + set bonus
-```
-
-## With Passives, Buffs, and Skill Bars
-
-```ts
-const stats = calculateBuild({
-  character: {
-    race: 'High Elf',
-    class: 'Sorcerer',
-    level: 50,
-    attributes: { health: 0, magicka: 64, stamina: 0 },
-    mundusStone: 'The Apprentice',
-    championPoints: 160,
-  },
-  // Auto-inject all racial passives at highest rank (mirrors UESP "Auto Purchase Racial Passives")
-  autoPassives: true,
-  // Named buffs from the UESP buff catalog
-  activeBuffs: ['Major Prophecy', 'Minor Slayer', 'Major Sorcery'],
-  // Active skills slotted on bars (affects conditional set bonuses and skill-line passives)
-  skillBars: {
-    bar1: [
-      { skillId: 28807, morphIndex: 2 }, // Crystal Fragments
-      { skillId: 24322 },                 // Mages' Fury
-    ],
-  },
-});
-```
-
-## API
-
-### `initEsoEngineFromData(options)`
-
-Initializes the UESP math engine from a `UespInitData` object. **Must be called once** before `calculateBuild()`.
+## How it works
 
-Safe to call multiple times — only executes on the first call.
+1. `initEsoEngineFromData({ initData })` prepares browser-like globals, seeds the engine with your game data, and executes the vendored UESP scripts via `vm.runInThisContext` — once per process.
+2. `calculateBuild(input)` writes your build into the engine state, runs the engine's own `UpdateEsoComputedStatsList_Real()`, and reads results from `g_EsoComputedStats` into a typed `ComputedStats` object.
 
-| Option     | Type           | Description                                    |
-| ---------- | -------------- | ---------------------------------------------- |
-| `initData` | `UespInitData` | Parsed game data (see `vendor/uesp-data/`)     |
-
----
-
-### `calculateBuild(input: BuildInput): ComputedStats`
-
-Runs the UESP engine and returns the computed stats.
-
-#### `BuildInput`
-
-```ts
-interface BuildInput {
-  character: {
-    race: string;           // "High Elf" | "Nord" | "Breton" | "Khajiit" | ...
-    class: string;          // "Sorcerer" | "Dragonknight" | "Nightblade" | ...
-    level: number;          // 1–50
-    attributes: {
-      health: number;       // attribute points (max 64 total)
-      magicka: number;
-      stamina: number;
-    };
-    mundusStone?: string;   // "The Thief" | "The Apprentice" | ...
-    mundusStone2?: string;  // second Mundus Stone (requires Twice-Born Star set)
-    cyrodiil?: boolean;     // Battle Spirit (PvP)
-    vampireStage?: number;  // 0–4
-    werewolfStage?: number; // 0 or 1
-    championPoints?: number; // 0–3600
-    rulesVersion?: string;  // "Live" (default) | "PTS"
-  };
-  items?: Partial<Record<EquipSlot, UespItemApiData>>;
-  championPointNodes?: Record<string | number, ChampionPointNode>;
-  activeBuffs?: string[];     // named buffs — see listAvailableBuffs()
-  toggleSkills?: string[];    // toggled skills — see listAvailableToggleSkills()
-  skillBars?: {
-    bar1?: SkillSlot[];
-    bar2?: SkillSlot[];
-  };
-  activeWeaponBar?: 1 | 2;   // which weapon bar is active (default: 1)
-  passiveSkills?: number[];   // ability IDs of unlocked passive skills
-  autoPassives?: boolean;     // auto-inject racial passives (default: false)
-  enchantOverrides?: Partial<Record<string, { enchantDesc: string; enchantName?: string }>>;
-  toggledSetBonuses?: string[];
-}
-```
-
-#### `EquipSlot`
-
-```
-Head | Shoulders | Chest | Hands | Legs | Waist | Feet |
-Neck | Ring1 | Ring2 |
-MainHand1 | OffHand1 | MainHand2 | OffHand2 |
-Poison1 | Poison2 | Food | Potion
-```
+Details: [Architecture](https://srtomy.github.io/uesp-eso-build-wrapper/architecture) · [Getting Started](https://srtomy.github.io/uesp-eso-build-wrapper/getting-started) · [Reading the Output](https://srtomy.github.io/uesp-eso-build-wrapper/output).
 
-#### `ComputedStats`
+## Documentation
 
-Key stats returned (see [`types.ts`](src/lib/eso-engine/types.ts) for the full list):
+Full documentation is available in **English** and **Português (BR)** at
+[**srtomy.github.io/uesp-eso-build-wrapper**](https://srtomy.github.io/uesp-eso-build-wrapper/):
 
-| Property                                               | Description                               |
-| ------------------------------------------------------ | ----------------------------------------- |
-| `Health` / `Magicka` / `Stamina`                       | Maximum resource pools                    |
-| `HealthRegen` / `MagickaRegen` / `StaminaRegen`        | Out-of-combat regeneration                |
-| `WeaponDamage` / `SpellDamage`                         | Base damage                               |
-| `WeaponCrit` / `SpellCrit`                             | Critical chance                           |
-| `PhysicalResist` / `SpellResist` / `CritResist`        | Resistances                               |
-| `PhysicalPenetration` / `SpellPenetration`             | Armor penetration                         |
-| `DefensePhysicalMitigation` / `DefenseSpellMitigation` | Effective mitigation %                    |
-| `HealingDone` / `HealingTaken`                         | Healing modifiers                         |
-| `RunSpeed` / `SprintSpeed`                             | Movement speed                            |
-| `raw`                                                  | All 221 stats as `Record<string, number>` |
-
-> All stat IDs match `g_EsoComputedStats` from the UESP engine (version 49+).
-
----
-
-### Catalog Functions
-
-| Function | Returns | Description |
-|---|---|---|
-| `listAvailableBuffs(group?)` | `BuffInfo[]` | 164 named buffs; filter by group `"Major"` \| `"Minor"` \| `"Set"` \| `"Target"` \| … |
-| `listRacialPassives(race)` | `PassiveSkillInfo[]` | All passive ranks for a given race |
-| `listClassPassives(cls)` | `PassiveSkillInfo[]` | All passive ranks for a given class (3 skill lines) |
-| `listPassivesBySkillLine(line)` | `PassiveSkillInfo[]` | Passives for any skill line (Heavy Armor, Undaunted, etc.) |
-| `listAvailableSkillLines()` | `string[]` | All available skill line names |
-| `listAvailableToggleSkills()` | `ToggleSkillInfo[]` | 105 toggle skills; `requiresCyrodiil` marks PvP-only |
-
-```ts
-// Example: see all Major buffs
-const buffs = listAvailableBuffs('Major');
-// Example: find racial passive IDs for a High Elf build
-const passives = listRacialPassives('High Elf');
-const ids = passives.map(p => p.abilityId);
-```
-
----
-
-## Game Data
-
-Game data (`UespInitData`) is extracted from the UESP SQL dumps and stored in `vendor/uesp-data/uesp-game-data.json`.  
-This file is committed to the repo but **not bundled in the npm package** — consumers are expected to supply their own copy or generate it.
-
-### Generating game data
-
-Requires Node.js ≥ 22 (uses `node:sqlite`).
-
-```bash
-npm run generate-data -- --db /path/to/local.db [--version 50]
-```
-
-The script reads from `local.db` and writes to `vendor/uesp-data/uesp-game-data.json`.  
-To populate `local.db`, use the seed script from [eso-build-editor](https://github.com/srtomy/eso-build-editor).
-
-### Scripts
-
-| Command | Description |
-|---|---|
-| `npm run generate-data -- --db <path>` | Generate `vendor/uesp-data/uesp-game-data.json` from a SQLite DB |
-| `npm run test:db-init [json] [db] [version]` | Validate committed JSON matches a live DB |
-| `npm run test:build <export.json>` | Print all computed stats for a UESP build export |
-| `npm run test:explore` | Interactive engine exploration script |
-
----
-
-## Validating Against the UESP Browser
-
-The `scripts/browser-export-build.js` script runs inside the UESP Build Editor DevTools console and exports the full build — inputs and expected stats — as a JSON file.
-
-**How to use:**
-
-1. Open [esobuilds.uesp.net](https://esobuilds.uesp.net), configure your build
-2. Open DevTools (F12) → Console, paste and run `browser-export-build.js`
-3. A `uesp-build-export.json` file is downloaded
-
-**Explore stats interactively:**
-
-```bash
-npm run test:build path/to/uesp-build-export.json
-```
-
-**Add as a golden regression fixture:**
-
-```bash
-cp path/to/uesp-build-export.json tests/fixtures/my-build.json
-npm test
-```
-
-`tests/build-fixtures.test.ts` auto-discovers all `.json` files in `tests/fixtures/` and asserts every stat in `expectedStats` against the wrapper output.
-
----
-
-## Updating Formulas After a New ESO Patch
-
-```bash
-# 1. Update the UESP engine submodule
-cd vendor/uesp-esochardata
-git fetch upstream && git merge upstream/master
-cd ../..
-
-# 2. Regenerate game data from an up-to-date local.db
-#    (populate local.db first via eso-build-editor's npm run db:seed)
-npm run generate-data -- --db /path/to/local.db --version <patch>
-
-# 3. Commit the updated game data
-git add vendor/uesp-data/uesp-game-data.json
-
-# 4. Run tests — update any golden values that changed intentionally
-npm test
-```
-
-## Framework Integration
-
-### Next.js (Vercel / serverless)
-
-The vendor JS files (`esobuilddata.js`, `esoEditBuild.js`) are loaded at runtime via `fs.readFileSync` with a dynamic path. Next.js's output file tracer (`@vercel/nft`) cannot detect them automatically, so they must be declared explicitly in `next.config.ts`:
-
-```ts
-// next.config.ts
-const nextConfig: NextConfig = {
-  serverExternalPackages: ['uesp-eso-build-wrapper'],
-  outputFileTracingIncludes: {
-    '/**': ['./node_modules/uesp-eso-build-wrapper/vendor/**'],
-  },
-};
-```
+| Section | Description |
+| --- | --- |
+| [Introduction](https://srtomy.github.io/uesp-eso-build-wrapper/) | What it is, why it exists, key properties |
+| [Architecture](https://srtomy.github.io/uesp-eso-build-wrapper/architecture) | Local engine, network policy, data flow |
+| [Getting Started](https://srtomy.github.io/uesp-eso-build-wrapper/getting-started) | Install, game data, first calculation |
+| [Guides](https://srtomy.github.io/uesp-eso-build-wrapper/guides/character) | Character, items, Champion Points, buffs, skills |
+| [Reading the Output](https://srtomy.github.io/uesp-eso-build-wrapper/output) | All 221 computed stats, `debugBuild()` |
+| [API Reference](https://srtomy.github.io/uesp-eso-build-wrapper/api/) | Generated from source TSDoc |
+| [Troubleshooting](https://srtomy.github.io/uesp-eso-build-wrapper/troubleshooting) | Common integration issues (Next.js/serverless, wrong stats...) |
+| [Contributing](https://srtomy.github.io/uesp-eso-build-wrapper/contributing) | Dev setup, tests, updating after an ESO patch |
 
-Without this, the engine will throw at runtime in any serverless environment (Vercel, AWS Lambda, etc.) because the vendor files are not included in the deployment bundle.
+## Limitations
 
----
+- Behavior follows the vendored UESP engine version — updating ESO patch support means updating the vendored scripts + game data and running the tests.
+- The engine was written for browsers around global state; the wrapper adapts it to Node.js (singleton init, synchronous calls). No concurrency guarantees beyond what the engine itself provides — see [Troubleshooting](https://srtomy.github.io/uesp-eso-build-wrapper/troubleshooting).
+- Requires Node.js >= 24. Bundlers/serverless need explicit `vendor/**` inclusion (documented in Troubleshooting).
 
 ## License
 

package/README.pt-BR.md

@@ -0,0 +1,122 @@
+# uesp-eso-build-wrapper
+
+[![CI](https://github.com/srtomy/uesp-eso-build-wrapper/actions/workflows/ci.yml/badge.svg)](https://github.com/srtomy/uesp-eso-build-wrapper/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/srtomy/uesp-eso-build-wrapper/graph/badge.svg)](https://codecov.io/gh/srtomy/uesp-eso-build-wrapper)
+[![npm](https://img.shields.io/npm/v/uesp-eso-build-wrapper.svg)](https://www.npmjs.com/package/uesp-eso-build-wrapper)
+[![Docs](https://img.shields.io/badge/docs-online-2564eb)](https://srtomy.github.io/uesp-eso-build-wrapper/pt/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node >=24](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org/en/download/)
+
+> **Read in [English](README.md).**
+
+Um wrapper Node.js/TypeScript em torno do motor de cálculo do [UESP ESO Build Editor](https://github.com/uesp/uesp-esochardata).
+
+Calcule as **Computed Character Statistics** de Elder Scrolls Online — Health, Magicka, Stamina, mitigação, chance de crítico, regeneração e mais de 200 — usando as fórmulas da própria UESP. Sem reimplementar nenhuma fórmula.
+
+## O que é?
+
+Isto **não é um cliente HTTP da UESP**. A biblioteca executa o motor de cálculo da UESP **localmente, dentro do seu processo Node.js**, e expõe os resultados numa API tipada:
+
+```text
+Aplicação
+    ↓
+uesp-eso-build-wrapper (API TypeScript)
+    ↓
+Camada de compatibilidade Node.js (globals de browser + DOM mínimo)
+    ↓
+UESP esoEditBuild.js (executado in-process via vm.runInThisContext)
+    ↓
+Funções de cálculo UESP → ComputedStats
+```
+
+Você injeta os inputs, o próprio código da UESP calcula cada stat, você lê de volta um objeto tipado.
+
+## Por que esta biblioteca?
+
+- **Precisão de referência** — o mesmo motor `esoEditBuild.js` do [esobuilds.uesp.net](https://esobuilds.uesp.net), mantido pela UESP e atualizado a cada patch.
+- **Sem reimplementar fórmulas** — o wrapper contém zero matemática de ESO. Quando um stat parece errado depois de um patch, a correção está sempre nos *dados* do jogo alimentados ao motor, nunca no código do wrapper. É isso que mantém a precisão entre patches.
+- **Local e síncrono** — `calculateBuild()` não faz nenhuma requisição de rede. O motor roda in-process; os dados do jogo e os itens são fornecidos pela sua aplicação (arquivo, banco de dados, dados gerados).
+- **Aceita item data da UESP diretamente** — equipamentos no formato [`exportJson.php?table=minedItem`](https://esolog.uesp.net) plugam direto em `BuildInput.items`.
+- **Nativo TypeScript** — inputs/outputs tipados, [API Reference](https://srtomy.github.io/uesp-eso-build-wrapper/api/) documentada com TSDoc, além de funções de catálogo em runtime (`listAvailableBuffs`, `listRacialPassives`, …) para descobrir nomes válidos.
+
+## Propriedades principais
+
+- Executa o motor de cálculo UESP vendored localmente (`vendor/uesp-esochardata`)
+- **Sem rede para calcular builds** — ver [Precisa de internet?](https://srtomy.github.io/uesp-eso-build-wrapper/pt/architecture#precisa-de-conexao-com-a-internet)
+- Não reimplementa as fórmulas de stats do ESO
+- API síncrona; o motor inicializa uma vez por processo (singleton, chamadas seguintes são no-op)
+- Zero dependências de runtime — Node.js puro
+- 221 computed stats por build
+
+## Instalação
+
+```bash
+npm install uesp-eso-build-wrapper
+```
+
+## Quick Start
+
+Os game data não vêm no pacote npm — você os fornece via `initEsoEngineFromData` (ver [Primeiros Passos](https://srtomy.github.io/uesp-eso-build-wrapper/pt/getting-started)).
+
+```ts
+import fs from 'fs';
+import { initEsoEngineFromData, calculateBuild } from 'uesp-eso-build-wrapper';
+import type { UespInitData } from 'uesp-eso-build-wrapper';
+
+const initData = JSON.parse(
+  fs.readFileSync('uesp-game-data.json', 'utf-8'),
+) as UespInitData;
+
+initEsoEngineFromData({ initData }); // uma vez por processo
+
+const stats = calculateBuild({
+  character: {
+    race: 'High Elf',
+    class: 'Sorcerer',
+    level: 50,
+    attributes: { health: 0, magicka: 64, stamina: 0 },
+  },
+});
+
+console.log(stats.Health);       // 16000
+console.log(stats.Magicka);      // 19104
+console.log(stats.SpellDamage);  // 1000
+```
+
+## Como funciona
+
+1. `initEsoEngineFromData({ initData })` prepara globals de browser, semeia o motor com seus game data e executa os scripts vendored da UESP via `vm.runInThisContext` — uma vez por processo.
+2. `calculateBuild(input)` escreve sua build no estado do motor, roda o próprio `UpdateEsoComputedStatsList_Real()` do motor e lê os resultados de `g_EsoComputedStats` num objeto tipado `ComputedStats`.
+
+Detalhes: [Arquitetura](https://srtomy.github.io/uesp-eso-build-wrapper/pt/architecture) · [Primeiros Passos](https://srtomy.github.io/uesp-eso-build-wrapper/pt/getting-started) · [Lendo o Resultado](https://srtomy.github.io/uesp-eso-build-wrapper/pt/output).
+
+## Documentação
+
+Documentação completa em **Português (BR)** e **English** em
+[**srtomy.github.io/uesp-eso-build-wrapper**](https://srtomy.github.io/uesp-eso-build-wrapper/pt/):
+
+| Seção | Descrição |
+| --- | --- |
+| [Introdução](https://srtomy.github.io/uesp-eso-build-wrapper/pt/) | O que é, por que existe, propriedades principais |
+| [Arquitetura](https://srtomy.github.io/uesp-eso-build-wrapper/pt/architecture) | Motor local, política de rede, fluxo de dados |
+| [Primeiros Passos](https://srtomy.github.io/uesp-eso-build-wrapper/pt/getting-started) | Instalação, game data, primeiro cálculo |
+| [Guias](https://srtomy.github.io/uesp-eso-build-wrapper/pt/guides/character) | Personagem, itens, Champion Points, buffs, skills |
+| [Lendo o Resultado](https://srtomy.github.io/uesp-eso-build-wrapper/pt/output) | Os 221 computed stats, `debugBuild()` |
+| [API Reference](https://srtomy.github.io/uesp-eso-build-wrapper/api/) | Gerada a partir do TSDoc (em inglês) |
+| [Solução de Problemas](https://srtomy.github.io/uesp-eso-build-wrapper/pt/troubleshooting) | Problemas comuns (Next.js/serverless, stats errados...) |
+| [Contribuindo](https://srtomy.github.io/uesp-eso-build-wrapper/pt/contributing) | Setup dev, testes, atualização após patch do ESO |
+
+## Limitações
+
+- O comportamento segue a versão vendored do motor UESP — suportar um patch novo do ESO significa atualizar os scripts vendored + game data e rodar os testes.
+- O motor foi escrito para browsers em torno de estado global; o wrapper adapta isso para Node.js (init singleton, chamadas síncronas). Sem garantias de concorrência além das que o próprio motor oferece — ver [Solução de Problemas](https://srtomy.github.io/uesp-eso-build-wrapper/pt/troubleshooting).
+- Requer Node.js >= 24. Bundlers/serverless precisam incluir `vendor/**` explicitamente (documentado em Solução de Problemas).
+
+## Licença
+
+MIT © srtomy
+
+Este pacote inclui arquivos de [uesp/uesp-esochardata](https://github.com/uesp/uesp-esochardata) (MIT).  
+Ver [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES) para detalhes.
+
+Elder Scrolls Online é marca registrada de ZeniMax Media Inc. Este projeto não é afiliado nem endossado pela ZeniMax Media Inc.

package/dist/lib/eso-engine/calculator.d.ts

@@ -1,39 +1,49 @@
 /**
- * Motor de cálculo de builds do ESO.
+ * ESO build calculation engine.
  *
- * Implementa a ideia central da arquitetura:
+ * Implements the core architecture idea:
  *
- *   1. Injetar dados do personagem nos elementos mock do DOM
- *      (jQuery vai ler via $("#esotbRace").val(), etc.)
+ *   1. Inject character data into the mock DOM elements
+ *      (jQuery will read via $("#esotbRace").val(), etc.)
  *
- *   2. Injetar dados dos itens DIRETAMENTE em g_EsoBuildItemData[slot]
- *      — sem precisar mockar jQuery para cada campo de item.
- *      Os campos vêm exatamente no formato da API pública da UESP:
+ *   2. Inject item data DIRECTLY into g_EsoBuildItemData[slot]
+ *      — no need to mock jQuery for each item field.
+ *      Fields come exactly in the UESP public API format:
  *      GET https://esolog.uesp.net/exportJson.php?table=minedItem&id=<id>&level=<lv>&quality=<q>
  *
- *   3. Chamar UpdateEsoComputedStatsList_Real(null, true)
- *      — o parâmetro `noUpdate=true` faz o motor calcular tudo mas pular
- *      as atualizações de DOM (DisplayEsoAllComputedStats, UpdateReadOnlyStats, etc.)
+ *   3. Call UpdateEsoComputedStatsList_Real(null, true)
+ *      — the `noUpdate=true` parameter makes the engine compute everything but skip
+ *      the DOM updates (DisplayEsoAllComputedStats, UpdateReadOnlyStats, etc.)
  *
- *   4. Ler os resultados de g_EsoComputedStats[statId].value
+ *   4. Read the results from g_EsoComputedStats[statId].value
  */
-import type { BuffInfo, BuildInput, ComputedStats, PassiveSkillInfo, ToggleSkillInfo } from './types';
+import type { BuffInfo, BuildInput, ComputedStats, PassiveSkillInfo, ToggleSkillInfo } from './types.js';
 export declare function cacheStatObjects(): void;
 /**
- * Calcula os Computed Character Statistics para a build fornecida.
+ * Calculates the Computed Character Statistics for the given build.
+ *
+ * Each call starts from a clean engine state (previous items, buffs, CP nodes
+ * and skill bars are reset), so builds never bleed into each other.
+ *
+ * @param input - The build to calculate: character sheet, items, champion
+ *   point nodes, buffs, toggle skills, skill bars and passives.
+ * @returns All computed stats — named keys (Health, Magicka, SpellDamage, ...)
+ *   plus `raw` with the full 221-stat `g_EsoComputedStats` record.
+ * @throws If the engine has not been initialized with
+ *   `initEsoEngineFromData()` first.
  *
  * @example
  * ```ts
- * import { calculateBuild } from './src/lib/eso-engine';
+ * import { calculateBuild } from 'uesp-eso-build-wrapper';
  *
  * const stats = calculateBuild({
  *   character: { race: 'High Elf', class: 'Sorcerer', level: 50,
  *                attributes: { health: 0, magicka: 64, stamina: 0 } },
  *   items: {
- *     Chest: chestItemFromUespApi,  // objeto retornado por esolog.uesp.net/exportJson.php
+ *     Chest: chestItemFromUespApi,  // object returned by esolog.uesp.net/exportJson.php
  *   },
  * });
- * console.log(stats.MaxMagicka, stats.SpellDamage);
+ * console.log(stats.Magicka, stats.SpellDamage);
  * ```
  */
 export declare function calculateBuild(input: BuildInput): ComputedStats;

package/dist/lib/eso-engine/calculator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calculator.d.ts","sourceRoot":"","sources":["../../../src/lib/eso-engine/calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EAEV,aAAa,EAEb,gBAAgB,EAEhB,eAAe,EAEhB,MAAM,SAAS,CAAC;AAMjB,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC;AAqCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CAwf/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,CA6B7D;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAKnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAKvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAK7E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CASlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,IAAI,eAAe,EAAE,CA6B7D"}
+{"version":3,"file":"calculator.d.ts","sourceRoot":"","sources":["../../../src/lib/eso-engine/calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EAEV,aAAa,EAEb,gBAAgB,EAEhB,eAAe,EAEhB,MAAM,YAAY,CAAC;AAMpB,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC;AAwDD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CAygB/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,CA6B7D;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAKnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAKvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAK7E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CASlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,IAAI,eAAe,EAAE,CA6B7D"}