@erpg/dicecore 3.1.0

package/dist/v3/types.d.ts

@@ -0,0 +1,251 @@
+import type { DiceRollError, SourceSpan } from './errors.js';
+import type { DiceLimits } from './runtime/limits.js';
+import type { RandomAlgorithm, ReplayDescriptor, SeedInput } from './runtime/replay.js';
+export type DiceSides = number | 'F';
+export type DiceState = 'compound' | 'critical-failure' | 'critical-success' | 'dropped' | 'exploded' | 'maximum' | 'minimum' | 'penetrated' | 'rerolled' | 'target-failure' | 'target-neutral' | 'target-success' | 'unique-rerolled';
+export type GroupState = 'dropped' | 'sorted-ascending' | 'sorted-descending';
+export interface DiceInspectionCost {
+    readonly staticDice: number;
+    readonly worstCaseGeneratedDice: number;
+    readonly worstCaseRandomCalls: number;
+    readonly totalStaticDice: number;
+    readonly totalWorstCaseGeneratedDice: number;
+    readonly totalWorstCaseRandomCalls: number;
+}
+export interface RollPlanGroup {
+    readonly id: string;
+    readonly sourceNodeId: string;
+    readonly kind: 'dice' | 'expression' | 'function' | 'group';
+    readonly notation: string;
+    readonly span: SourceSpan;
+    readonly childIds: readonly string[];
+}
+export interface RollPlan {
+    readonly type: 'roll-plan';
+    readonly schemaVersion: 3;
+    readonly compilerVersion: 1;
+    readonly planFingerprint: string;
+    readonly input: string;
+    readonly comment: string;
+    readonly notation: string;
+    readonly normalizedNotation: string;
+    readonly isMultiRoll: boolean;
+    readonly rollCount: number;
+    readonly groups: readonly RollPlanGroup[];
+    readonly cost: DiceInspectionCost;
+}
+export interface EntityRange {
+    readonly start: number;
+    readonly count: number;
+}
+export interface ResolvedDie {
+    readonly id: string;
+    readonly sourceNodeId: string;
+    readonly parentDieId: string | null;
+    readonly rollIndex: number;
+    readonly rollDieIndex: number;
+    readonly groupId: string;
+    readonly sides: DiceSides;
+    readonly rawValue: number;
+    readonly value: number;
+    readonly contribution: number;
+    readonly included: boolean;
+    readonly states: readonly DiceState[];
+}
+export interface ResolvedGroup {
+    readonly id: string;
+    readonly sourceNodeId: string;
+    readonly rollIndex: number;
+    readonly kind: 'dice' | 'expression' | 'function' | 'group';
+    readonly notation: string;
+    readonly span: SourceSpan;
+    readonly value: number;
+    readonly contribution: number;
+    readonly included: boolean;
+    readonly states: readonly GroupState[];
+    readonly childIds: readonly string[];
+}
+export interface PoolSummary {
+    readonly successes: number;
+    readonly failures: number;
+    readonly netSuccesses: number;
+}
+interface EventBase {
+    readonly sequence: number;
+    readonly rollIndex: number;
+    readonly sourceNodeId: string;
+}
+interface DieEventBase extends EventBase {
+    readonly subject: 'die';
+    readonly dieId: string;
+    readonly parentDieId: string | null;
+}
+interface GroupEventBase extends EventBase {
+    readonly subject: 'group';
+    readonly groupId: string;
+}
+export interface RollDiceEvent extends DieEventBase {
+    readonly type: 'roll';
+    readonly value: number;
+}
+export interface RerollDiceEvent extends DieEventBase {
+    readonly type: 'reroll';
+    readonly from: number;
+    readonly to: number;
+    readonly reason: 'reroll' | 'reroll-once' | 'unique' | 'unique-once';
+}
+export interface ExplodeDiceEvent extends DieEventBase {
+    readonly type: 'explode';
+    readonly childDieId: string;
+    readonly value: number;
+    readonly reason: 'explode' | 'compound' | 'penetrate';
+}
+export interface TransformDiceEvent extends DieEventBase {
+    readonly type: 'transform';
+    readonly from: number;
+    readonly to: number;
+    readonly reason: 'minimum' | 'maximum' | 'penetrate' | 'compound';
+}
+export interface TransformGroupEvent extends GroupEventBase {
+    readonly type: 'transform';
+    readonly from: readonly string[];
+    readonly to: readonly string[];
+    readonly reason: 'sort-ascending' | 'sort-descending';
+}
+export interface IncludeDiceEvent extends DieEventBase {
+    readonly type: 'include';
+    readonly contribution: number;
+}
+export interface IncludeGroupEvent extends GroupEventBase {
+    readonly type: 'include';
+    readonly value: number;
+    readonly contribution: number;
+}
+export interface ExcludeDiceEvent extends DieEventBase {
+    readonly type: 'exclude';
+    readonly reason: 'drop' | 'keep' | 'compound-absorbed';
+}
+export interface ExcludeGroupEvent extends GroupEventBase {
+    readonly type: 'exclude';
+    readonly value: number;
+    readonly reason: 'drop' | 'keep';
+}
+export interface ClassifyDiceEvent extends DieEventBase {
+    readonly type: 'classify';
+    readonly outcome: 'success' | 'failure' | 'neutral' | 'critical-success' | 'critical-failure';
+}
+export type DiceEvent = RollDiceEvent | RerollDiceEvent | ExplodeDiceEvent | TransformDiceEvent | TransformGroupEvent | IncludeDiceEvent | IncludeGroupEvent | ExcludeDiceEvent | ExcludeGroupEvent | ClassifyDiceEvent;
+export interface ExecutionStats {
+    readonly rolls: number;
+    readonly initialDice: number;
+    readonly generatedDice: number;
+    readonly randomCalls: number;
+    readonly modifierSteps: number;
+    readonly events: number;
+    readonly resolvedGroups: number;
+    readonly resultItems: number;
+}
+export interface ResolvedRoll {
+    readonly index: number;
+    readonly total: number;
+    readonly pool: PoolSummary | null;
+    readonly diceRange: EntityRange;
+    readonly groupRange: EntityRange;
+    readonly eventRange: EntityRange;
+}
+interface RollResultBase {
+    readonly schemaVersion: 3;
+    readonly input: string;
+    readonly notation: string;
+    readonly normalizedNotation: string;
+    readonly comment: string;
+    readonly total: number;
+    readonly replay: ReplayDescriptor;
+    readonly stats: ExecutionStats;
+    readonly pool: PoolSummary | null;
+}
+export interface DiceRollResult extends RollResultBase {
+    readonly type: 'dice-roll';
+    readonly output: string;
+    readonly rolls: readonly ResolvedRoll[];
+    readonly groups: readonly ResolvedGroup[];
+    readonly dice: readonly ResolvedDie[];
+    readonly events: readonly DiceEvent[];
+}
+export interface ResolvedRollSummary {
+    readonly index: number;
+    readonly total: number;
+    readonly pool: PoolSummary | null;
+}
+export interface DiceRollSummary extends RollResultBase {
+    readonly type: 'dice-roll-summary';
+    readonly rolls: readonly ResolvedRollSummary[];
+}
+interface DiceNotationInspectionBase {
+    readonly type: 'dice-notation-inspection';
+    readonly input: string;
+    readonly notation: string;
+    readonly normalizedNotation: string;
+    readonly comment: string;
+}
+interface ValidDiceNotationInspection extends DiceNotationInspectionBase {
+    readonly isValid: true;
+    readonly plan: RollPlan;
+    readonly groups: readonly RollPlanGroup[];
+    readonly cost: DiceInspectionCost;
+    readonly error: null;
+}
+interface InvalidDiceNotationInspection extends DiceNotationInspectionBase {
+    readonly isValid: false;
+    readonly plan: null;
+    readonly groups: readonly RollPlanGroup[];
+    readonly cost: null;
+    readonly error: DiceRollError;
+}
+export type DiceNotationInspection = ValidDiceNotationInspection | InvalidDiceNotationInspection;
+export type FreezeResultsMode = 'development' | 'always' | 'never';
+export interface DiceCacheOptions {
+    readonly maxInputEntries?: number;
+    readonly maxProgramEntries?: number;
+    readonly maxProgramNodes?: number;
+}
+export interface DiceCacheStats {
+    readonly inputEntries: number;
+    readonly programEntries: number;
+    readonly programNodes: number;
+    readonly hits: number;
+    readonly misses: number;
+    readonly evictions: number;
+}
+export interface DiceEngineOptions {
+    readonly limits?: Partial<DiceLimits>;
+    readonly freezeResults?: FreezeResultsMode;
+    readonly cache?: false | DiceCacheOptions;
+    readonly randomAlgorithm?: RandomAlgorithm;
+}
+export interface CompileOptions {
+    readonly limits?: Partial<DiceLimits>;
+}
+type SeededRollOptions = {
+    readonly seed?: SeedInput;
+    readonly replay?: never;
+    readonly randomAlgorithm?: RandomAlgorithm;
+};
+type ReplayRollOptions = {
+    readonly seed?: never;
+    readonly replay: ReplayDescriptor;
+    readonly randomAlgorithm?: never;
+};
+export type RollOptions = CompileOptions & (SeededRollOptions | ReplayRollOptions);
+export interface DiceEngine {
+    readonly limits: DiceLimits;
+    clearCache(): void;
+    compile(input: string, options?: CompileOptions): RollPlan;
+    getCacheStats(): DiceCacheStats;
+    inspect(input: string, options?: CompileOptions): DiceNotationInspection;
+    normalize(input: string): string;
+    roll(input: string | RollPlan, options?: RollOptions): DiceRollResult;
+    rollSummary(input: string | RollPlan, options?: RollOptions): DiceRollSummary;
+    verify(input: string, options?: CompileOptions): boolean;
+}
+export {};

package/licence.txt

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 - 2021 GreenImp Limited <greenimp.co.uk>
+Copyright (c) 2021 - present GreenImp Media Limited <greenimp.co.uk>
+Copyright (c) 2026 Arkanus
+
+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/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@erpg/dicecore",
+  "description": "ERPG dice core with ergonomic RPG notation, grouped rolls, structured UI data, deterministic replay, and safe parse-only inspection.",
+  "author": "Arkanus",
+  "version": "3.1.0",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "licence.txt",
+    "readme.md"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arkanus-app/rpg-dice-roller.git"
+  },
+  "bugs": {
+    "url": "https://github.com/arkanus-app/rpg-dice-roller/issues"
+  },
+  "homepage": "https://github.com/arkanus-app/rpg-dice-roller",
+  "keywords": [
+    "dice",
+    "roller",
+    "rpg",
+    "roll",
+    "d&d",
+    "dnd",
+    "random",
+    "prng",
+    "roleplay",
+    "pathfinder",
+    "notation"
+  ],
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@eslint/js": "^9.39.2",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^24.0.0",
+    "@vitest/browser-playwright": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^9.39.2",
+    "fast-check": "^4.0.0",
+    "globals": "^16.0.0",
+    "jiti": "^2.0.0",
+    "publint": "^0.3.0",
+    "playwright": "^1.61.1",
+    "random-js": "^2.1.0",
+    "rollup": "^4.60.3",
+    "tslib": "^2.8.1",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.63.0",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {},
+  "engines": {
+    "node": ">=22.0"
+  },
+  "scripts": {
+    "build": "npm run build:clean && npm run build:prepare && npm run build:bundle && npm run build:declaration",
+    "build:clean": "tsx ./scripts/clean.ts",
+    "build:prepare": "npm run typecheck && npm run lint",
+    "build:declaration": "tsx ./scripts/build-declarations.ts",
+    "build:bundle": "rollup --config=./rollup.config.mjs",
+    "benchmark": "node --expose-gc --import tsx ./scripts/benchmark.ts",
+    "benchmark:check": "npm run build && npm run benchmark -- --check --json",
+    "watch": "rollup --config=./rollup.config.mjs --watch",
+    "typecheck": "npm run typecheck:legacy && npm run typecheck:v3 && npm run typecheck:public-api && npm run typecheck:tooling",
+    "typecheck:legacy": "tsc -p tsconfig.json --pretty false",
+    "typecheck:v3": "tsc -p tsconfig.v3.json --pretty false",
+    "typecheck:public-api": "tsc -p tsconfig.type-tests.json --pretty false",
+    "typecheck:tooling": "tsc -p tsconfig.tools.json --pretty false",
+    "lint": "eslint . --max-warnings=0",
+    "lint:fix": "eslint . --fix --max-warnings=0",
+    "pretest": "npm run build:prepare",
+    "test": "vitest run",
+    "pretest:coverage": "npm run build:prepare",
+    "test:coverage": "vitest run --coverage",
+    "test:browser": "vitest run --config ./vitest.browser.config.ts",
+    "test:watch": "vitest",
+    "package:check": "npm run build && publint run . --strict && tsx ./scripts/check-package.ts",
+    "check": "npm run test:coverage && npm run package:check",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run check"
+  }
+}

package/readme.md

@@ -0,0 +1,255 @@
+# @erpg/dicecore 3.0.0
+
+Núcleo de dados do ERPG para compilar, inspecionar e resolver notações de dados. A V3 é escrita em TypeScript estrito, não mantém estado global de RNG e entrega resultados `readonly`, JSON-safe e próprios para frontend, backend, automações e visualização 3D.
+
+> A versão `3.0.0` está implementada neste repositório, mas este documento não indica que a publicação no npm ou a criação da tag já tenham ocorrido.
+
+## Requisitos e formatos
+
+- Node.js 22 ou mais recente;
+- browsers com ES2022 e `globalThis.crypto.getRandomValues`;
+- ESM, CommonJS e declarações TypeScript;
+- zero dependências de runtime no pacote publicado.
+
+```bash
+npm install @erpg/dicecore
+```
+
+```ts
+import { rollRpgDice } from '@erpg/dicecore';
+
+const result = rollRpgDice('2d6+3', { seed: 'encontro-42' });
+console.log(result.total, result.replay);
+```
+
+```js
+const { rollRpgDice } = require('@erpg/dicecore');
+
+const result = rollRpgDice('1d20+5', { seed: 'ataque-1' });
+```
+
+Imports profundos, global UMD e as classes internas da V2 não fazem parte da API pública.
+
+## API pública
+
+```ts
+import {
+  compileRpgDice,
+  createDiceEngine,
+  inspectRpgDiceNotation,
+  isDiceRollError,
+  isDiceRollErrorData,
+  normalizeRpgDiceNotation,
+  rollRpgDice,
+  rollRpgDiceSummary,
+  verifyRpgDiceNotation,
+} from '@erpg/dicecore';
+
+const plan = compileRpgDice('2#4d6kh3 [atributos]');
+const result = rollRpgDice(plan, { seed: 'personagem-42' });
+
+const inspection = inspectRpgDiceNotation('5d10>=8f=1');
+if (inspection.isValid && inspection.plan) {
+  console.log(inspection.cost, rollRpgDice(inspection.plan).pool);
+}
+
+console.log(verifyRpgDiceNotation('d20+5')); // true
+console.log(normalizeRpgDiceNotation('d + 2f')); // d20+2dF
+
+try {
+  rollRpgDice('10001d6');
+} catch (error: unknown) {
+  if (isDiceRollError(error)) {
+    console.error(error.code, error.span, error.details);
+  }
+}
+```
+
+As funções públicas são:
+
+- `compileRpgDice(input, options?)`: normaliza, valida e compila uma vez para um `RollPlan` imutável;
+- `createDiceEngine(options?)`: cria limites, cache de planos e política de congelamento isolados;
+- `inspectRpgDiceNotation(input, options?)`: valida sem rolar e retorna plano, grupos e estimativa de custo;
+- `rollRpgDice(inputOrPlan, options?)`: resolve a fórmula e sempre inclui um descritor de replay;
+- `rollRpgDiceSummary(inputOrPlan, options?)`: resolve total, rolls, pool, replay e stats sem materializar dados, grupos, eventos ou output;
+- `verifyRpgDiceNotation(input, options?)`: atalho booleano de validação;
+- `normalizeRpgDiceNotation(input)`: aplica os atalhos de escrita do ERPG;
+- `isDiceRollError(error)`: type guard para os erros estruturados da V3.
+- `isDiceRollErrorData(value)`: valida erros transportados por JSON; restaure-os com `DiceRollError.fromJSON()`.
+
+Um engine é indicado quando a aplicação precisa definir tetos próprios ou reutilizar planos com frequência:
+
+```ts
+const dice = createDiceEngine({
+  limits: {
+    maxRolls: 20,
+    maxInitialDice: 500,
+    maxGeneratedDice: 1_000,
+  },
+  cache: {
+    maxInputEntries: 300,
+    maxProgramEntries: 100,
+    maxProgramNodes: 50_000,
+  },
+  randomAlgorithm: 'mt19937',
+  freezeResults: 'development',
+});
+
+const plan = dice.compile('3#2d20kh1+5');
+const result = dice.roll(plan, {
+  seed: 'combate-17',
+  limits: { maxRolls: 3 },
+});
+```
+
+Limites informados em uma chamada podem apenas reduzir os tetos do engine. O plano original reutiliza a representação compilada; cópias via JSON ou spread são validadas e recompiladas pelo engine de destino antes da execução.
+
+## Limites de segurança
+
+As opções usam `limits`, tanto no engine quanto por chamada:
+
+```ts
+const result = rollRpgDice('3#2d6!', {
+  seed: 'teste-de-carga',
+  limits: {
+    maxInputLength: 4_096,
+    maxAstDepth: 64,
+    maxAstNodes: 10_000,
+    maxRolls: 3,
+    maxInitialDice: 100,
+    maxGeneratedDice: 500,
+    maxRandomCalls: 2_000,
+    maxEvents: 2_000,
+    maxSides: 4_294_967_296,
+    maxSeedLength: 1_024,
+    maxModifierSteps: 10_000,
+    maxResolvedGroups: 10_000,
+    maxResultItems: 25_000,
+    maxOutputLength: 100_000,
+  },
+});
+```
+
+Os padrões completos estão em `DEFAULT_DICE_LIMITS`. A inspeção calcula custo estático e pior caso; parser e executor também aplicam orçamentos duros durante a construção e a execução.
+
+## Resultado V3
+
+```ts
+interface DiceRollResult {
+  readonly type: 'dice-roll';
+  readonly schemaVersion: 3;
+  readonly input: string;
+  readonly notation: string;
+  readonly normalizedNotation: string;
+  readonly comment: string;
+  readonly total: number;
+  readonly output: string;
+  readonly replay: ReplayDescriptor;
+  readonly stats: ExecutionStats;
+  readonly rolls: readonly ResolvedRoll[];
+  readonly groups: readonly ResolvedGroup[];
+  readonly dice: readonly ResolvedDie[];
+  readonly events: readonly DiceEvent[];
+  readonly pool: PoolSummary | null;
+}
+```
+
+- `rolls` separa cada execução de `N#formula` por ranges contíguos (`diceRange`, `groupRange`, `eventRange`); o `total` raiz é a soma de seus totais;
+- `groups` resolve dados, expressões, funções e grupos com IDs e `SourceSpan` estáveis;
+- `dice` separa face inicial (`rawValue`), valor final (`value`), contribuição e inclusão;
+- `events` registra rolls, rerolls, explosões, transformações, inclusão, exclusão e classificação de dados e grupos na ordem do executor. Consumidores visuais devem reconstruir dependências por ID: o `roll` de um filho explosivo é registrado antes do evento `explode` que o liga ao pai;
+- `pool` é `null` sem target e agrega sucessos/falhas quando a notação usa um target.
+
+Veja o contrato completo em [docs/API_V3.md](docs/API_V3.md) e a atualização de consumidores em [docs/MIGRATION_V3.md](docs/MIGRATION_V3.md).
+
+## Seed e replay
+
+Toda rolagem retorna:
+
+```ts
+interface ReplayDescriptor {
+  readonly schemaVersion: 2;
+  readonly algorithm: 'mt19937' | 'xoshiro128ss';
+  readonly algorithmVersion: 1;
+  readonly executionVersion: 1;
+  readonly mathProfile: 'decimal12-v1';
+  readonly origin: 'provided-number' | 'provided-string' | 'crypto';
+  readonly seedMaterial: string;    // 32 hex, sem a seed textual
+  readonly planFingerprint: string; // 32 hex
+}
+```
+
+Com `seed: string | number`, a mesma fórmula, seed de entrada e versão do core produzem a mesma sequência. Sem seed, o core gera 128 bits com `crypto.getRandomValues`; não há fallback para `Math.random`. O descritor retornado pode reproduzir exatamente qualquer uma das duas origens:
+
+```ts
+const first = rollRpgDice('2d20kh1');
+const repeated = rollRpgDice('2d20kh1', { replay: first.replay });
+```
+
+`seed` e `replay` são mutuamente exclusivos. O replay já é vinculado ao fingerprint da fórmula; outra fórmula falha com `REPLAY_PLAN_MISMATCH`. MT19937 permanece o padrão e `xoshiro128ss` é opt-in.
+
+## Notação ERPG
+
+A normalização preserva atalhos comuns:
+
+- `d` → `d20`, `2d` → `2d20`;
+- `f` → `4dF`, `2f` → `2dF`, `df` → `dF`;
+- `ei6` → `!>=6`;
+- `km` → `kl`, e `k`, `kh` ou `kl` sem quantidade recebem `1`;
+- combinações simples como `+-`, `-+`, `++` e `--` são limpas;
+- `N#formula` executa rolagens independentes; `N` também pode ser uma expressão matemática determinística, como `(3-1)#1d20` (com `()`, `{}` ou `[]` para agrupamento);
+- comentários podem usar `[texto]`, `//`, `#` ou `/* ... */` conforme o contexto.
+
+A sintaxe inclui dados padrão, percentuais e Fudge; aritmética e funções; grupos; keep/drop; reroll/unique; explode/compound/penetrate; min/max; critical; sort; e targets de sucesso/falha.
+
+```ts
+rollRpgDice('4d6kh3');
+rollRpgDice('1d%+2dF');
+rollRpgDice('5d10>=8f=1');
+rollRpgDice('{1d8,1d10}kh1');
+rollRpgDice('ceil(1d6/2)+pow(2,3)');
+```
+
+## Integração com dice3dview
+
+O `dicecore` decide o resultado; o `dice3dview` apenas o apresenta. A API de timeline recebe definições visuais e o journal resolvido sem interpretar a notação novamente:
+
+```ts
+const result = rollRpgDice('2d6!kh2', { seed: 'cena-9' });
+const supportedSides = new Set([2, 4, 6, 8, 10, 12, 20, 100]);
+const visualDice = result.dice.filter(
+  (die) => typeof die.sides === 'number' && supportedSides.has(die.sides),
+);
+const visualIds = new Set(visualDice.map((die) => die.id));
+
+await dice3dview.displayTimeline({
+  id: 'cena-9',
+  seed: 'cena-9',
+  dice: visualDice.map((die) => ({ id: die.id, sides: die.sides })),
+  events: result.events.filter(
+    (event) => event.subject === 'die' && visualIds.has(event.dieId),
+  ),
+});
+
+const scoring = result.dice.map((die) => ({
+  id: die.id,
+  parentDieId: die.parentDieId,
+  value: die.value,
+  included: die.included,
+  contribution: die.contribution,
+}));
+```
+
+O viewer pré-compila o journal inteiro porque o `roll` de um filho aparece antes do `explode` correspondente. Dados excluídos ainda podem ser animados, mas `included` e `contribution` governam a pontuação. `parentDieId` liga uma explosão ao dado que a originou. `transform` representa valor semântico: compound pode ultrapassar o número de faces e penetrate pode chegar a zero, portanto esses valores nunca devem ser usados como face física.
+
+## Desenvolvimento da V3
+
+O parser e o MT19937 da V3 são implementações TypeScript do próprio pacote. Vitest, o perfil TypeScript estrito e as verificações do tarball fazem parte da toolchain. `dist/` é sempre gerado e não é versionado.
+
+O núcleo V2 não é exportado pelo pacote V3. Ele permanece no repositório apenas como corpus de compatibilidade durante o desenvolvimento e pode ser removido quando a migração for encerrada.
+
+## Atribuição e licença
+
+Este pacote é um derivado mantido pelo ERPG a partir do projeto open source `@dice-roller/rpg-dice-roller`, de GreenImp. A V3 substitui o parser e o runtime publicados por implementações próprias em TypeScript, mantendo o crédito e o aviso original em `licence.txt`.
+
+Licença MIT.