afnm-types 0.6.55 → 0.6.56

package/dist/buff.d.ts

@@ -18,14 +18,17 @@ export type DamageModifier = MultiplyDamageModifier | ReduceDamageModifier | Exp
 interface MultiplyDamageModifier {
     kind: 'multiply';
     value: number;
+    cantUpgrade?: boolean;
 }
 interface ReduceDamageModifier {
     kind: 'reduce';
     percent: number;
+    cantUpgrade?: boolean;
 }
 interface ExpressionDamageModifier {
     kind: 'expression';
     expression: string;
+    cantUpgrade?: boolean;
 }
 interface ChanceTechniqueCondition extends BaseTechniqueCondition {
     kind: 'chance';
@@ -121,7 +124,7 @@ export interface Buff {
             value: number;
         };
         effects?: BuffEffect[];
-        appliesTo: ('damage' | 'barrier' | 'heal')[];
+        appliesTo: ('damage' | 'barrier' | 'heal' | 'tempHealth')[];
     }[];
     /** Amplifies buff creation. Modifies stack count when matching buffs are created on self. */
     buffAmplifierEffects?: {
@@ -317,7 +320,7 @@ export interface TransformationCombatImage {
     animateOnEntity?: boolean;
 }
 export type RepairRule = 'all' | 'lowestHealth' | 'highestHealth';
-export type BuffEffect = DamageEffect | DamageSelfEffect | HealEffect | BarrierEffect | CreateBuffSelfEffect | ConsumeBuffSelfEffect | CreateBuffTargetEffect | ConsumeBuffTargetEffect | NegateEffect | AddEffect | MultiplyEffect | MergeEffect | TriggerEffect | ModifyBuffGroupEffect | CleanseToxicityEffect | SetStateEffect | ConvertSelfEffect | RepairEffect | ConsumeInventoryItemEffect;
+export type BuffEffect = DamageEffect | DamageSelfEffect | HealEffect | BarrierEffect | GiveTemporaryHealthEffect | CreateBuffSelfEffect | ConsumeBuffSelfEffect | CreateBuffTargetEffect | ConsumeBuffTargetEffect | NegateEffect | AddEffect | MultiplyEffect | MergeEffect | TriggerEffect | ModifyBuffGroupEffect | CleanseToxicityEffect | SetStateEffect | ConvertSelfEffect | RepairEffect | ConsumeInventoryItemEffect;
 interface BaseBuff {
     condition?: TechniqueCondition;
     triggerKey?: string;
@@ -349,6 +352,12 @@ interface BarrierEffect extends BaseBuff {
     hits?: Scaling;
     targeting?: EffectTargeting;
 }
+interface GiveTemporaryHealthEffect extends BaseBuff {
+    kind: 'temporaryHealth';
+    amount: Scaling;
+    hits?: Scaling;
+    targeting?: EffectTargeting;
+}
 interface CreateBuffSelfEffect extends BaseBuff {
     kind: 'buffSelf';
     amount: Scaling;

package/dist/character.d.ts

@@ -331,7 +331,7 @@ export interface CharacterRelationshipDefinition {
     tooltip: Translatable;
     followCharacter?: FollowCharacterDefinition;
     dualCultivation?: DualCultivationDefinition;
-    progressionEvent: {
+    progressionEvent?: {
         name: string;
         tooltip: Translatable;
         event: EventStep[];

package/dist/cli/extract-translations/config.js

@@ -3,7 +3,7 @@
  * Configuration constants for the translation extraction script
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REQUIREMENT_STRINGS = exports.CONDITION_TEMPLATES = exports.CONDITION_WORDS = exports.HARDCODED_TEMPLATE_PATTERNS = exports.TIER_ONLY_MAPS = exports.STATIC_MAPS = exports.STATIC_ARRAY_NAMES = exports.TEXT_SHADOW = exports.STYLE_COLORS = exports.ELEMENTS = exports.ELEMENT_TO_NAME = exports.RARITIES = exports.RARITY_TO_TIER = exports.REALMS = exports.REALM_TO_NAME = exports.REALM_TO_TIER = exports.CODE_CHANGE_EXCLUDE_FILES = exports.CODE_CHANGE_EXCLUDE_PATTERNS = exports.EXCLUDE_PATTERNS = exports.NON_TRANSLATABLE_PROPERTIES = exports.MIN_STRING_LENGTH = void 0;
+exports.REQUIREMENT_STRINGS = exports.CONDITION_TEMPLATES = exports.CONDITION_WORDS = exports.HARDCODED_TEMPLATE_PATTERNS = exports.TIER_ONLY_MAPS = exports.STATIC_MAPS = exports.STATIC_ARRAY_NAMES = exports.ENEMY_STANCE_NAMES = exports.TEXT_SHADOW = exports.STYLE_COLORS = exports.ELEMENTS = exports.ELEMENT_TO_NAME = exports.RARITIES = exports.RARITY_TO_TIER = exports.REALMS = exports.REALM_TO_NAME = exports.REALM_TO_TIER = exports.CODE_CHANGE_EXCLUDE_FILES = exports.CODE_CHANGE_EXCLUDE_PATTERNS = exports.EXCLUDE_PATTERNS = exports.NON_TRANSLATABLE_PROPERTIES = exports.MIN_STRING_LENGTH = void 0;
 exports.isTranslatableProperty = isTranslatableProperty;
 exports.isCamelCase = isCamelCase;
 exports.shouldExclude = shouldExclude;
@@ -512,6 +512,33 @@ exports.STYLE_COLORS = {
     num: '#ff877d',
 };
 exports.TEXT_SHADOW = 'textShadow: -1px 1px 0 #000, 1px 1px 0 #000, 1px -1px 0 #000, -1px -1px 0 #000;';
+/** Internal stance name identifiers used by EnemyEntity definitions. Never player-facing. */
+exports.ENEMY_STANCE_NAMES = new Set([
+    'absorb', 'accelerate', 'aggressive', 'agitation', 'amplify', 'animate', 'ascension',
+    'assault', 'assess', 'attack', 'attack1', 'attack2', 'attack3', 'attack4', 'attackBig',
+    'barrier', 'barrierHater', 'barrierMit', 'bigBloat', 'blast', 'block', 'blood', 'blossom',
+    'boil', 'bolt', 'buff', 'buffSelf', 'buffStance', 'buffTarget', 'build', 'burn',
+    'burrowStrike', 'burst', 'cacophonyPhase', 'celestial', 'celestialradiance', 'chaosForge',
+    'charge', 'cleave', 'cloud', 'collapse', 'compliance', 'constrict', 'consume', 'consuming',
+    'control', 'corrupt', 'corrupted_swarm', 'counterattack', 'crownedascension',
+    'crownedgathering', 'crownedradiance', 'crushing', 'damage', 'damageHeavy', 'debuff',
+    'debuffHeal', 'debuffStance', 'defend', 'defending', 'defensive', 'defensiveHeavy',
+    'defensiveStance', 'desertGuardian', 'desperate', 'destabilize', 'dissonancePhase', 'drain',
+    'eclipse', 'emerald', 'endure', 'enhanced_attack', 'enhanced_attack1', 'enhanced_attack2',
+    'enhanced_attack3', 'enhanced_block', 'enhanced_rend', 'escalation1', 'escalation2',
+    'fieldSet', 'finale', 'first', 'firstRound', 'fist', 'float', 'focus', 'forging', 'fortify',
+    'frenzy', 'gathering', 'gore', 'gossamerLight', 'gossamerShadow', 'gossamerVault', 'guard',
+    'harm', 'harmonyPhase', 'heal', 'healDebuff', 'initializing', 'kick', 'lash', 'lethargy',
+    'mend', 'meteor', 'mindlessAttack', 'moon', 'multihits', 'mystic', 'needle', 'offensiveStance',
+    'opener', 'origin', 'overcharged', 'pause', 'peck', 'pierce', 'plumagegathering', 'power',
+    'powerBuildUp', 'preparation', 'prepare', 'pressureAssault', 'pulse', 'punch', 'purge',
+    'recklessness', 'rend', 'ruby', 'sandstorm', 'sap', 'sapphire', 'seal', 'setup', 'setup1',
+    'setup2', 'setup3', 'shatter', 'shroudLight', 'shroudShadow', 'shroudVault', 'siphon', 'soar',
+    'spin', 'stack', 'stacks', 'steal', 'sun', 'surge', 'sustain', 'swarm', 'swarmling',
+    'swarmlord', 'touch', 'turtle', 'twisted_rampage', 'underground', 'unleash', 'unravel',
+    'unstableFury', 'vaultBreak', 'venom', 'venomMaster', 'wail', 'weapon', 'weave',
+    'weaveAttacker', 'weaveHealer', 'weaveLight', 'weaveProtector', 'weaveShadow', 'windDancer',
+]);
 /** Arrays that indicate static map iteration */
 exports.STATIC_ARRAY_NAMES = ['realms', 'techniqueElements'];
 /** Static maps that can be expanded */

package/dist/cli/extract-translations/extractors.js

@@ -653,9 +653,10 @@ function extractFromFile(filePath) {
                 // not player-facing text (e.g., "attack1", "enhanced_attack2", "stack", "power")
                 // Exception: manual items have style/stances with player-facing names like "Defensive Focus"
                 if (propName === 'name' &&
-                    nestedPath &&
-                    ((/\bstances\b/.test(nestedPath) && !/\bstyle\b/.test(nestedPath)) ||
-                        /\bmastery\b/.test(nestedPath))) {
+                    ((nestedPath &&
+                        ((/\bstances\b/.test(nestedPath) && !/\bstyle\b/.test(nestedPath)) ||
+                            /\bmastery\b/.test(nestedPath))) ||
+                        (typescript_1.default.isStringLiteral(node.initializer) && config_js_1.ENEMY_STANCE_NAMES.has(node.initializer.text)))) {
                     typescript_1.default.forEachChild(node, visit);
                     return;
                 }
@@ -923,7 +924,12 @@ function extractFromFile(filePath) {
                     }
                 }
             }
-            if (!isDirectExportedArray) {
+            // Skip arrays that are values of non-translatable properties (e.g., stances: ['attack1', ...])
+            const isInsideNonTranslatableProperty = parent &&
+                typescript_1.default.isPropertyAssignment(parent) &&
+                typescript_1.default.isIdentifier(parent.name) &&
+                !(0, config_js_1.isTranslatableProperty)(parent.name.text);
+            if (!isDirectExportedArray && !isInsideNonTranslatableProperty) {
                 const stringElements = node.elements.filter((el) => typescript_1.default.isStringLiteral(el) || typescript_1.default.isNoSubstitutionTemplateLiteral(el));
                 if (stringElements.length > 0) {
                     const translatableStrings = stringElements

package/dist/combat.d.ts

@@ -0,0 +1,186 @@
+import { Buff, Translatable } from '.';
+import { BreakthroughState } from './breakthrough';
+import { PlayerEntity, CombatEntity, EnemyEntity, CombatEffectTracking, EntityType } from './entity';
+import { ArtefactTechnique, Item } from './item';
+import { InventoryItemState } from './reduxState';
+import { Technique } from './technique';
+import { PhysicalStatistic, SocialStatistic } from './stat';
+export interface CombatLogEffects {
+    source: string;
+    damage?: number;
+    barrier?: number;
+    healing?: number;
+    temporaryHealth?: number;
+    /** Delta toxicity: positive = gained, negative = cleansed */
+    toxicity?: number;
+    buffsCreated?: Record<string, number>;
+    buffsInflicted?: Record<string, number>;
+    buffsConsumed?: Record<string, number>;
+}
+/**
+ * Optional semantic metadata for structured analysis of log entries.
+ * Used by defeatAnalysis and other systems to avoid regex-based string parsing.
+ */
+export interface CombatLogMeta {
+    /** Name of the technique or buff that was executed */
+    techniqueName?: string;
+    /** True when the technique failed to execute */
+    failed?: boolean;
+    /** The resource that was insufficient/excessive when a technique failed */
+    failedResource?: string;
+    /** True when this entry records a self-damage event */
+    selfDamage?: boolean;
+    /** Remaining HP of the target after this damage event */
+    remainingHp?: number;
+    /** True when this entry marks the end of a round */
+    roundEnd?: boolean;
+    /** True when this entry is a turn section header (Player's Turn, Enemy's Turn, etc.) */
+    turnHeader?: boolean;
+}
+export interface CombatEntitySnapshot {
+    hp: number;
+    maxHp: number;
+    barrier: number;
+}
+export interface CombatPartyMemberSnapshot extends CombatEntitySnapshot {
+    partyId?: string;
+}
+export interface CombatStateSnapshot {
+    player?: CombatEntitySnapshot;
+    enemy?: CombatEntitySnapshot;
+    playerParty?: CombatPartyMemberSnapshot[];
+    enemyParty?: CombatPartyMemberSnapshot[];
+}
+export interface CombatLogEntry {
+    path: string;
+    /** Which entity this log entry is about */
+    entity: EntityType;
+    /** UUID of the specific party member — only set when entity is PlayerParty or EnemyParty */
+    partyId?: string;
+    message: string;
+    effects?: CombatLogEffects;
+    meta?: CombatLogMeta;
+    /** Snapshot of HP/barrier for all combat entities at the moment this entry was created */
+    state?: CombatStateSnapshot;
+}
+export interface StanceTracking {
+    techniques: string[];
+    name: string;
+    count: number;
+}
+export interface PlayerStanceData {
+    playerStanceIndex: number;
+    usedPlayerStanceOpeners: boolean[];
+    lastPlayerStance: string;
+    lastCycleKey?: string;
+}
+export interface CurrentCombatState {
+    player: PlayerEntity | undefined;
+    playerState: CombatEntity | undefined;
+    breakthrough: BreakthroughState | undefined;
+    playerStanceData: PlayerStanceData | undefined;
+    enemies: EnemyEntity[];
+    foughtEnemies: EnemyEntity[];
+    enemyState: CombatEntity | undefined;
+    lastEnemyStance: string | undefined;
+    currentPhase: number;
+    allPhases: EnemyEntity[];
+    phaseTransitioning: boolean;
+    roundNum: number;
+    roundState: RoundState | undefined;
+    consumedPills: number;
+    noEnhancement?: boolean;
+    noCrit?: boolean;
+    trainingMode?: boolean;
+    isSpar?: boolean;
+    playerEffectTracking: Record<string, CombatEffectTracking>;
+    enemyEffectTracking: Record<string, CombatEffectTracking>;
+    stanceTracking: Record<string, StanceTracking>;
+    partyStanceTracking: Record<number, Record<string, StanceTracking>>;
+    pillTracking: Record<string, number>;
+    autoUseRowTracking: Record<number, number>;
+    inventoryItems?: InventoryItemState[];
+    loot: Item[];
+    kills: {
+        name: string;
+        displayName?: Translatable;
+    }[];
+    qi: number;
+    combatState: 'victory' | 'defeat' | undefined;
+    combatLog: CombatLogEntry[];
+    gameFlags: Record<string, number>;
+    precalculatedLoot: {
+        items: Item[];
+        qi: number;
+    }[];
+    lootBurstTriggered: boolean;
+    lootBurstQueue: {
+        id: string;
+        loot: Item[];
+        qi: number;
+        enemyPosition: {
+            x: number;
+            y: number;
+        };
+        playerPosition: {
+            x: number;
+            y: number;
+        };
+    }[];
+    previewCallbacks?: {
+        onBuffFailed: (buff: Buff) => void;
+    };
+    /** Permanent stat changes accumulated during combat to be applied to the player on exit. */
+    permanentStatChanges?: Partial<Record<PhysicalStatistic | SocialStatistic, number>>;
+}
+export interface RoundState {
+    player: EntityRoundState;
+    enemy: EntityRoundState;
+    playerArtefacts: ArtefactRoundState[];
+    enemyArtefacts: ArtefactRoundState[];
+    playerParty: EntityRoundState[];
+    enemyParty: EntityRoundState[];
+    roundQueue: RoundStep[];
+    delay: number;
+}
+export type RoundStep = PlayerRoundStep | PlayerArtefactRoundStep | PlayerPartyRoundStep | EnemyRoundStep | EnemyArtefactRoundStep | EnemyPartyRoundStep | BuffsRoundStep | BuffsRoundStartStep | EndRoundStep;
+export interface PlayerRoundStep {
+    kind: 'player';
+}
+export interface PlayerArtefactRoundStep {
+    kind: 'playerArtefact';
+    index: number;
+}
+export interface PlayerPartyRoundStep {
+    kind: 'playerParty';
+    index: number;
+}
+export interface EnemyArtefactRoundStep {
+    kind: 'enemyArtefact';
+    index: number;
+}
+export interface EnemyPartyRoundStep {
+    kind: 'enemyParty';
+    index: number;
+}
+export interface EnemyRoundStep {
+    kind: 'enemy';
+}
+export interface BuffsRoundStep {
+    kind: 'buffs';
+}
+export interface BuffsRoundStartStep {
+    kind: 'buffsStart';
+}
+export interface EndRoundStep {
+    kind: 'end';
+}
+export interface EntityRoundState {
+    techniques: Technique[];
+    used: Technique[];
+    doneUltimate: boolean;
+}
+export interface ArtefactRoundState {
+    techniques: ArtefactTechnique[];
+    used: ArtefactTechnique[];
+}

package/dist/combat.js

@@ -0,0 +1 @@
+export {};

package/dist/entity.d.ts

@@ -14,6 +14,7 @@ export interface CombatEffectTracking {
     damage: number;
     healing: number;
     barrier: number;
+    temphp: number;
     damageTaken: number;
 }
 export declare const entityTypes: readonly ["Player", "Lifeform", "Enemy", "PlayerParty", "EnemyParty", "System"];

package/dist/gameVersion.d.ts

@@ -15,4 +15,4 @@
  *   };
  * }
  */
-export declare const GAME_VERSION = "0.6.55";
+export declare const GAME_VERSION = "0.6.56";

package/dist/gameVersion.js

@@ -15,4 +15,4 @@
  *   };
  * }
  */
-export const GAME_VERSION = "0.6.55";
+export const GAME_VERSION = "0.6.56";

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './calendar';
 export * from './character';
 export * from './CharacterRequestEncounter';
 export * from './components';
+export * from './combat';
 export * from './crafting';
 export * from './craftingBuff';
 export * from './craftingState';

package/dist/index.js

@@ -8,6 +8,7 @@ export * from './calendar';
 export * from './character';
 export * from './CharacterRequestEncounter';
 export * from './components';
+export * from './combat';
 export * from './crafting';
 export * from './craftingBuff';
 export * from './craftingState';

package/dist/keybindings.d.ts

@@ -1,5 +1,5 @@
 export type KeybindingCategory = 'general' | 'navigation' | 'ui' | 'world' | 'combat' | 'crafting' | 'dialogs' | 'gamepad';
-export type KeybindingAction = 'confirm' | 'cancel' | 'pause' | 'alternateConfirm' | 'moveUp' | 'moveDown' | 'moveLeft' | 'moveRight' | 'openInventory' | 'openQuests' | 'openCharacterStats' | 'openTechniques' | 'openCalendar' | 'openWorldMap' | 'combatSelectStance0' | 'combatSelectStance1' | 'combatSelectStance2' | 'combatSelectStance3' | 'combatSelectStance4' | 'combatSelectStance5' | 'combatSelectStance6' | 'combatSelectStance7' | 'combatSelectStance8' | 'combatSelectStance9' | 'combatToggleSpeed' | 'combatToggleLog' | 'combatShowStats' | 'combatAutoBattle' | 'combatUseItem' | 'combatCancel' | 'craftingAction1' | 'craftingAction2' | 'craftingAction3' | 'craftingAction4' | 'craftingAction5' | 'craftingAction6' | 'craftingAction7' | 'craftingAction8' | 'craftingAction9' | 'craftingAction10' | 'craftingAction11' | 'craftingAction12' | 'craftingAction13' | 'craftingAction14' | 'craftingAction15' | 'craftingAction16' | 'craftingAction17' | 'craftingAction18' | 'craftingAction19' | 'craftingAction20' | 'craftingAction21' | 'craftingAction22' | 'craftingAction23' | 'craftingAction24' | 'craftingAction25' | 'craftingAction26' | 'craftingAction27' | 'craftingAction28' | 'craftingAction29' | 'craftingAction30' | 'craftingAction31' | 'craftingAction32' | 'craftingAction33' | 'craftingAction34' | 'craftingAction35' | 'craftingAction36' | 'craftingAction37' | 'craftingAction38' | 'craftingAction39' | 'craftingAction40' | 'craftingAction41' | 'craftingAction42' | 'craftingAction43' | 'craftingAction44' | 'craftingAction45' | 'craftingAction46' | 'craftingAction47' | 'craftingAction48' | 'craftingAction49' | 'craftingAction50' | 'dialogChoice1' | 'dialogChoice2' | 'dialogChoice3' | 'dialogChoice4' | 'dialogChoice5' | 'dialogChoice6' | 'dialogChoice7' | 'dialogChoice8' | 'dialogChoice9' | 'gamepadConfirm' | 'gamepadCancel' | 'gamepadUp' | 'gamepadDown' | 'gamepadLeft' | 'gamepadRight';
+export type KeybindingAction = 'confirm' | 'cancel' | 'pause' | 'alternateConfirm' | 'moveUp' | 'moveDown' | 'moveLeft' | 'moveRight' | 'openInventory' | 'openQuests' | 'openCharacterStats' | 'openTechniques' | 'openCalendar' | 'lockTooltip' | 'openWorldMap' | 'combatSelectStance0' | 'combatSelectStance1' | 'combatSelectStance2' | 'combatSelectStance3' | 'combatSelectStance4' | 'combatSelectStance5' | 'combatSelectStance6' | 'combatSelectStance7' | 'combatSelectStance8' | 'combatSelectStance9' | 'combatToggleSpeed' | 'combatToggleLog' | 'combatShowStats' | 'combatAutoBattle' | 'combatUseItem' | 'combatCancel' | 'craftingAction1' | 'craftingAction2' | 'craftingAction3' | 'craftingAction4' | 'craftingAction5' | 'craftingAction6' | 'craftingAction7' | 'craftingAction8' | 'craftingAction9' | 'craftingAction10' | 'craftingAction11' | 'craftingAction12' | 'craftingAction13' | 'craftingAction14' | 'craftingAction15' | 'craftingAction16' | 'craftingAction17' | 'craftingAction18' | 'craftingAction19' | 'craftingAction20' | 'craftingAction21' | 'craftingAction22' | 'craftingAction23' | 'craftingAction24' | 'craftingAction25' | 'craftingAction26' | 'craftingAction27' | 'craftingAction28' | 'craftingAction29' | 'craftingAction30' | 'craftingAction31' | 'craftingAction32' | 'craftingAction33' | 'craftingAction34' | 'craftingAction35' | 'craftingAction36' | 'craftingAction37' | 'craftingAction38' | 'craftingAction39' | 'craftingAction40' | 'craftingAction41' | 'craftingAction42' | 'craftingAction43' | 'craftingAction44' | 'craftingAction45' | 'craftingAction46' | 'craftingAction47' | 'craftingAction48' | 'craftingAction49' | 'craftingAction50' | 'dialogChoice1' | 'dialogChoice2' | 'dialogChoice3' | 'dialogChoice4' | 'dialogChoice5' | 'dialogChoice6' | 'dialogChoice7' | 'dialogChoice8' | 'dialogChoice9' | 'gamepadConfirm' | 'gamepadCancel' | 'gamepadUp' | 'gamepadDown' | 'gamepadLeft' | 'gamepadRight';
 export interface KeybindingDefinition {
     action: KeybindingAction | string;
     category: KeybindingCategory;
@@ -28,6 +28,7 @@ export declare const MODIFIER_PREFIXES: {
     readonly alt: "Alt+";
     readonly shift: "Shift+";
 };
+export declare const baseKeyToCode: Record<string, string>;
 export declare function getBaseKeyFromEvent(event: KeyboardEvent): string;
 export declare function buildKeybindingString(key: string, modifiers: {
     ctrl?: boolean;

package/dist/keybindings.js

@@ -107,6 +107,14 @@ export const keybindingDefinitions = [
         defaultKey: 'm',
         allowRebind: true,
     },
+    {
+        action: 'lockTooltip',
+        category: 'ui',
+        displayName: 'Lock Tooltip',
+        description: 'Instantly lock the currently shown tooltip when it is overflowing',
+        defaultKey: 'l',
+        allowRebind: true,
+    },
     // World
     {
         action: 'openWorldMap',
@@ -908,6 +916,8 @@ const codeToBaseKey = {
     F11: 'F11',
     F12: 'F12',
 };
+// Build reverse lookup from base key to code for matching KeyboardEvent.code
+export const baseKeyToCode = Object.fromEntries(Object.entries(codeToBaseKey).map(([code, baseKey]) => [baseKey, code]));
 // Get the base key from a keyboard event (uses code for consistent physical key)
 export function getBaseKeyFromEvent(event) {
     // Try to get base key from code first (handles Shift+2 -> '2' instead of '!')

package/dist/mod.d.ts

@@ -49,6 +49,7 @@ import type { Translatable, TranslatableString } from './translatable';
 import type { SaveFileInfo } from './electron';
 import type { KeybindingDefinition, RegisteredKeybind } from './keybindings';
 import { ScreenType } from './GameScreen';
+import { CurrentCombatState, CombatLogEntry, RoundStep } from './combat';
 export type SkipDialogueMode = 'flash' | 'silent';
 export type Sexuality = 'straight' | 'gay' | 'bisexual';
 export interface GameSettingsProps {
@@ -72,8 +73,33 @@ export interface GameSettingsProps {
     setSexuality: (value: Sexuality) => void;
     eventHistoryLimit: number;
     setEventHistoryLimit: (value: number) => void;
+    tooltipLockTimeMs: number;
+    setTooltipLockTimeMs: (value: number) => void;
 }
-export type InjectPosition = 'before' | 'after';
+/**
+ * Where injected content is placed relative to the matched element.
+ *
+ * Sibling insertions:
+ *   'before'          inserted as a sibling immediately before the target
+ *   'after'           inserted as a sibling immediately after the target (default)
+ *
+ * Child insertions:
+ *   'prependChild'    inserted as the first child inside the target
+ *   'appendChild'     inserted as the last child inside the target
+ *   { insertAt: N }   inserted as the Nth child inside the target (0-based)
+ *
+ * Overlay:
+ *   'overlay'         absolutely positioned layer covering the target (target gets position:relative if needed)
+ *
+ * Structural replacements (use with care on React-rendered elements):
+ *   'replaceContents' clears the target's children and renders content inside the target
+ *   'replaceElement'  removes the target entirely and renders content in its place
+ *   'wrapElement'     target becomes a DOM child of the content's outermost element (e.g. a border div wraps around target)
+ *   'wrapContents'    target's existing children are moved inside the content's outermost element, which is then appended to target
+ */
+export type InjectPlacement = 'before' | 'after' | 'prependChild' | 'appendChild' | 'overlay' | 'replaceContents' | 'replaceElement' | 'wrapElement' | 'wrapContents' | {
+    insertAt: number;
+};
 export interface NewGameIntent {
     items: ItemDesc[];
     techniques: string[];
@@ -457,7 +483,6 @@ export interface ModAPI {
                 deadlyFocus: Buff;
                 rippleForce: Buff;
                 transcendentFocus: Buff;
-                weakness: Buff;
                 goldenAura: Buff;
             };
             weapon: {
@@ -1398,7 +1423,7 @@ export interface ModAPI {
          */
         getClothingCharisma: (realm: Realm, mult: number) => number;
         /**
-         * Get max qi the player can hold in a realm.
+         * Get qi amount to be used for qi rewards
          * @param realm - Target realm
          * @param realmProgress - Progress level
          * @returns Qi amount
@@ -1415,6 +1440,15 @@ export interface ModAPI {
          * const qiCost = getBreakthroughQi('coreFormation', 'Late');
          */
         getBreakthroughQi: (realm: Realm, realmProgress: RealmProgress) => number;
+        /**
+         * Get maximum qi the player can hold
+         * @param realm - Player realm
+         * @param realmProgress - Progress level
+         * @returns Max qi pool
+         * @example
+         * const maxQi = getMaxQi('coreFormation', 'Late');
+         */
+        getMaxQi: (realm: Realm, realmProgress: RealmProgress) => number;
         /**
          * Scale a numeric reward amount to a value appropriate for the player's realm and progress.
          * @param base - Base reward amount
@@ -2091,7 +2125,7 @@ export interface ModAPI {
          *   return combatEntity;
          * });
          */
-        onCreatePlayerCombatEntity: (interceptor: (player: PlayerEntity, combatEntity: CombatEntity, breakthrough: BreakthroughState, gameFlags: Record<string, number>) => CombatEntity) => void;
+        onCreatePlayerCombatEntity: (interceptor: (player: PlayerEntity, combatEntity: CombatEntity, breakthrough: BreakthroughState, gameFlags: Record<string, number>) => CombatEntity) => () => void;
         /**
          * Hook into player crafting entity creation to modify stats.
          * @param interceptor - Function to modify crafting entity
@@ -2103,7 +2137,7 @@ export interface ModAPI {
          *   return craftingEntity;
          * });
          */
-        onCreatePlayerCraftingEntity: (interceptor: (player: PlayerEntity, craftingEntity: CraftingEntity, breakthrough: BreakthroughState, characters: CharactersState | undefined, gameFlags: Record<string, number>) => CraftingEntity) => void;
+        onCreatePlayerCraftingEntity: (interceptor: (player: PlayerEntity, craftingEntity: CraftingEntity, breakthrough: BreakthroughState, characters: CharactersState | undefined, gameFlags: Record<string, number>) => CraftingEntity) => () => void;
         /**
          * Hook called before crafting begins to modify recipe, recipe stats, or player.
          * @param interceptor - Function returning modified recipe/stats/player or undefined
@@ -2119,7 +2153,7 @@ export interface ModAPI {
             recipe?: RecipeItem;
             recipeStats?: CraftingRecipeStats;
             player?: CraftingEntity;
-        } | undefined) => void;
+        } | undefined) => () => void;
         /**
          * Hook into enemy combat entity creation to modify stats.
          * @param interceptor - Function to modify combat entity
@@ -2132,7 +2166,7 @@ export interface ModAPI {
          *   return combatEntity;
          * });
          */
-        onCreateEnemyCombatEntity: (interceptor: (enemy: EnemyEntity, combatEntity: CombatEntity, gameFlags: Record<string, number>) => CombatEntity) => void;
+        onCreateEnemyCombatEntity: (interceptor: (enemy: EnemyEntity, combatEntity: CombatEntity, gameFlags: Record<string, number>) => CombatEntity) => () => void;
         /**
          * Hook to modify recipe difficulty calculations.
          * @param interceptor - Function to adjust recipe stats
@@ -2144,7 +2178,7 @@ export interface ModAPI {
          *   return stats;
          * });
          */
-        onDeriveRecipeDifficulty: (interceptor: (recipe: RecipeItem, recipeStats: CraftingRecipeStats, gameFlags: Record<string, number>) => CraftingRecipeStats) => void;
+        onDeriveRecipeDifficulty: (interceptor: (recipe: RecipeItem, recipeStats: CraftingRecipeStats, gameFlags: Record<string, number>) => CraftingRecipeStats) => () => void;
         /**
          * Hook to modify recipe ingredients before crafting calculations.
          * This runs before onDeriveRecipeDifficulty and allows mods to change
@@ -2164,7 +2198,7 @@ export interface ModAPI {
          *   return recipe;
          * });
          */
-        onModifyRecipeIngredients: (interceptor: (recipe: RecipeItem, gameFlags: Record<string, number>) => RecipeItem) => void;
+        onModifyRecipeIngredients: (interceptor: (recipe: RecipeItem, gameFlags: Record<string, number>) => RecipeItem) => () => void;
         /**
          * Hook to add events after combat completion.
          * @param interceptor - Function returning additional event steps
@@ -2176,7 +2210,7 @@ export interface ModAPI {
          *   return [];
          * });
          */
-        onCompleteCombat: (interceptor: (eventStep: CombatStep | FightCharacterStep, victory: boolean, playerCombatState: CombatEntity, foughtEnemies: EnemyEntity[], droppedItems: Item[], gameFlags: Record<string, number>) => EventStep[]) => void;
+        onCompleteCombat: (interceptor: (eventStep: CombatStep | FightCharacterStep, victory: boolean, playerCombatState: CombatEntity, foughtEnemies: EnemyEntity[], droppedItems: Item[], gameFlags: Record<string, number>) => EventStep[]) => () => void;
         /**
          * Hook to add events after tournament completion.
          * @param interceptor - Function returning additional event steps
@@ -2188,7 +2222,7 @@ export interface ModAPI {
          *   return [];
          * });
          */
-        onCompleteTournament: (interceptor: (eventStep: TournamentStep, tournamentState: 'victory' | 'second' | 'defeat', gameFlags: Record<string, number>) => EventStep[]) => void;
+        onCompleteTournament: (interceptor: (eventStep: TournamentStep, tournamentState: 'victory' | 'second' | 'defeat', gameFlags: Record<string, number>) => EventStep[]) => () => void;
         /**
          * Hook to add events after dual cultivation.
          * @param interceptor - Function returning additional event steps
@@ -2200,7 +2234,7 @@ export interface ModAPI {
          *   return [];
          * });
          */
-        onCompleteDualCultivation: (interceptor: (eventStep: DualCultivationStep, success: boolean, gameFlags: Record<string, number>) => EventStep[]) => void;
+        onCompleteDualCultivation: (interceptor: (eventStep: DualCultivationStep, success: boolean, gameFlags: Record<string, number>) => EventStep[]) => () => void;
         /**
          * Hook to add events after crafting completion.
          * @param interceptor - Function returning additional event steps
@@ -2212,7 +2246,7 @@ export interface ModAPI {
          *   return [];
          * });
          */
-        onCompleteCrafting: (interceptor: (eventStep: CraftingStep, item: CraftingResult | undefined, gameFlags: Record<string, number>) => EventStep[]) => void;
+        onCompleteCrafting: (interceptor: (eventStep: CraftingStep, item: CraftingResult | undefined, gameFlags: Record<string, number>) => EventStep[]) => () => void;
         /**
          * Hook to add events after auction completion.
          * @param interceptor - Function returning additional event steps
@@ -2224,12 +2258,12 @@ export interface ModAPI {
          *   return [];
          * });
          */
-        onCompleteAuction: (interceptor: (eventStep: AuctionStep, itemsBought: AuctionItem[], gameFlags: Record<string, number>) => EventStep[]) => void;
+        onCompleteAuction: (interceptor: (eventStep: AuctionStep, itemsBought: AuctionItem[], gameFlags: Record<string, number>) => EventStep[]) => () => void;
         /**
          * Hook to add events after stone cutting.
          * @param interceptor - Function returning additional event steps
          */
-        onCompleteStoneCutting: (interceptor: (eventStep: StoneCuttingStep, gameFlags: Record<string, number>) => EventStep[]) => void;
+        onCompleteStoneCutting: (interceptor: (eventStep: StoneCuttingStep, gameFlags: Record<string, number>) => EventStep[]) => () => void;
         /**
          * Hook to intercept and modify items granted by event steps (addItem, addMultipleItem, dropItem).
          * Return a modified ItemDesc to change the item name or stack count. Return stacks <= 0 to suppress the item entirely.
@@ -2242,7 +2276,7 @@ export interface ModAPI {
          *   return item;
          * });
          */
-        onEventDropItem: (interceptor: (item: ItemDesc, step: AddItemStep | AddMultipleItemStep | DropItemStep, gameFlags: Record<string, number>) => ItemDesc) => void;
+        onEventDropItem: (interceptor: (item: ItemDesc, step: AddItemStep | AddMultipleItemStep | DropItemStep, gameFlags: Record<string, number>) => ItemDesc) => () => void;
         /**
          * Hook to modify the exploration event pool before one is selected.
          * Mods can add, remove, or reorder events. Fired after base-game eligibility
@@ -2256,7 +2290,7 @@ export interface ModAPI {
          *   return events;
          * });
          */
-        onGenerateExploreEvents: (interceptor: (locationId: string, events: LocationEvent[], gameFlags: Record<string, number>) => LocationEvent[]) => void;
+        onGenerateExploreEvents: (interceptor: (locationId: string, events: LocationEvent[], gameFlags: Record<string, number>) => LocationEvent[]) => () => void;
         /**
          * Hook to intercept and modify combat damage after all base reductions.
          * Called for every damage application. Return the new damage value.
@@ -2269,7 +2303,7 @@ export interface ModAPI {
          *   return damage;
          * });
          */
-        onCalculateDamage: (interceptor: (attacker: CombatEntity, defender: CombatEntity, damage: number, damageType: DamageType | undefined, gameFlags: Record<string, number>) => number) => void;
+        onCalculateDamage: (interceptor: (attacker: CombatEntity, defender: CombatEntity, damage: number, damageType: DamageType | undefined, gameFlags: Record<string, number>) => number) => () => void;
         /**
          * Hook fired when the player enters a new location.
          * @param interceptor - Receives the location id and current flags.
@@ -2278,7 +2312,7 @@ export interface ModAPI {
          *   console.log('Player entered', locationId);
          * });
          */
-        onLocationEnter: (interceptor: (locationId: string, gameFlags: Record<string, number>) => void) => void;
+        onLocationEnter: (interceptor: (locationId: string, gameFlags: Record<string, number>) => void) => () => void;
         /**
          * Hook fired when combat loot is distributed to the player after a fight.
          * @param interceptor - Receives the list of items dropped and current flags.
@@ -2287,7 +2321,7 @@ export interface ModAPI {
          *   items.forEach(item => console.log('Got:', item.name));
          * });
          */
-        onLootDrop: (interceptor: (items: Item[], gameFlags: Record<string, number>) => void) => void;
+        onLootDrop: (interceptor: (items: Item[], gameFlags: Record<string, number>) => void) => () => void;
         /**
          * Hook fired when the game advances time (player rests, travels, etc.).
          * @param interceptor - Receives the number of days advanced and current flags.
@@ -2296,7 +2330,7 @@ export interface ModAPI {
          *   console.log('Time passed:', days, 'days');
          * });
          */
-        onAdvanceDay: (interceptor: (days: number, gameFlags: Record<string, number>) => void) => void;
+        onAdvanceDay: (interceptor: (days: number, gameFlags: Record<string, number>) => void) => () => void;
         /**
          * Hook fired once for each month rollover that occurs during a day advance.
          * @param interceptor - Receives the new month, year, and current flags.
@@ -2305,7 +2339,7 @@ export interface ModAPI {
          *   if (month === 3) modAPI.actions.startEvent(mySpringFestivalEvent);
          * });
          */
-        onAdvanceMonth: (interceptor: (month: number, year: number, gameFlags: Record<string, number>) => void) => void;
+        onAdvanceMonth: (interceptor: (month: number, year: number, gameFlags: Record<string, number>) => void) => () => void;
         /**
          * Hook fired before combat is initialized. Allows modifying enemies and the player combat entity.
          * Return modified copies of enemies and playerState. Mutations to the originals are not used.
@@ -2322,7 +2356,16 @@ export interface ModAPI {
         onBeforeCombat: (interceptor: (enemies: EnemyEntity[], playerState: CombatEntity, gameFlags: Record<string, number>) => {
             enemies: EnemyEntity[];
             playerState: CombatEntity;
-        }) => void;
+        }) => () => void;
+        /**
+         * Hook fired when the player consumes a pill, concoction, or combat consumable during combat.
+         * @param interceptor - Receives the item consumed, the target entity, and current flags.
+         * @example
+         * onConsumeItem((item, target, flags) => {
+         *   console.log('Player consumed', item.name, 'targeting', target.name);
+         * });
+         */
+        onConsumeItem: (interceptor: (item: Item, target: CombatEntity, gameFlags: Record<string, number>) => void) => () => void;
         /**
          * Hook fired after every Redux state update. Receives the action type, the
          * state before the action was applied, the state after, and a readonly copy of
@@ -2343,7 +2386,7 @@ export interface ModAPI {
          *   return after;
          * });
          */
-        onReduxAction: (interceptor: (actionType: string, stateBefore: RootState, stateAfter: RootState, payload: Readonly<unknown>) => RootState) => void;
+        onReduxAction: (interceptor: (actionType: string, stateBefore: RootState, stateAfter: RootState, payload: Readonly<unknown>) => RootState) => () => void;
         /**
          * Hook fired before a Redux action is passed to the reducer. Allows
          * intercepting and modifying the action payload, or dropping the action
@@ -2370,22 +2413,31 @@ export interface ModAPI {
          *   return payload;
          * });
          */
-        onReduxActionPayload: (interceptor: (actionType: string, payload: unknown, stateBefore: RootState) => unknown | null) => void;
+        onReduxActionPayload: (interceptor: (actionType: string, payload: unknown, stateBefore: RootState) => unknown | null) => () => void;
         /**
          * Called before the equipment upgrade dialog is shown. Allows mutating upgrade cost items and
-         * result item quality tier (but not base item).
+         * result item quality tier and hidden potential (but not base item).
          *
          * @example
-         * modAPI.hooks.onDeriveEquipmentUpgradeRequirement((baseItem, costItems, resultItemName, resultQualityTier, flags) => {
-         *   // Override the result quality tier
-         *   return { costItems, resultItemName, resultQualityTier: resultQualityTier + 2 };
+         * modAPI.hooks.onDeriveEquipmentUpgradeRequirement((baseItem, costItems, resultItem, flags) => {
+         *   // Override the result quality tier and preserve hidden potential
+         *   return { costItems, resultItem: { ...resultItem, resultQualityTier: resultItem.resultQualityTier + 2 } };
          * });
          */
-        onDeriveEquipmentUpgradeRequirement: (interceptor: (baseItem: Item, costItems: Item[], resultItemName: string, resultQualityTier: number, gameFlags: Record<string, number>) => {
+        onDeriveEquipmentUpgradeRequirement: (interceptor: (baseItem: Item, costItems: Item[], resultItem: {
+            resultItemName: string;
+            resultQualityTier: number;
+            resultHiddenPotential?: number;
+            resultEnchantment?: EnchantmentDesc;
+        }, gameFlags: Record<string, number>) => {
             costItems?: Item[];
-            resultItemName?: string;
-            resultQualityTier?: number;
-        } | undefined) => void;
+            resultItem?: Partial<{
+                resultItemName: string;
+                resultQualityTier: number;
+                resultHiddenPotential: number;
+                resultEnchantment: EnchantmentDesc;
+            }>;
+        } | undefined) => () => void;
         /**
          * Called when an equipment upgrade completes. Read-only: cannot modify the result item.
          * Use onDeriveEquipmentUpgradeRequirement to change the result before the upgrade.
@@ -2395,22 +2447,31 @@ export interface ModAPI {
          *   // React to the upgrade (e.g., trigger a side effect)
          * });
          */
-        onCompleteEquipmentUpgrade: (interceptor: (baseItem: Item, costItems: Item[], resultItem: Item, gameFlags: Record<string, number>) => void) => void;
+        onCompleteEquipmentUpgrade: (interceptor: (baseItem: Item, costItems: Item[], resultItem: Item, gameFlags: Record<string, number>) => void) => () => void;
         /**
          * Called before the equipment reforge dialog is shown. Allows mutating reforge cost items and
-         * result item quality tier (but not base item).
+         * result item quality tier and hidden potential (but not base item).
          *
          * @example
-         * modAPI.hooks.onDeriveEquipmentReforgeRequirement((baseItem, costItems, resultItemName, resultQualityTier, flags) => {
-         *   // Override the result quality tier (e.g., set to max)
-         *   return { costItems, resultItemName, resultQualityTier: 10 };
+         * modAPI.hooks.onDeriveEquipmentReforgeRequirement((baseItem, costItems, resultItem, flags) => {
+         *   // Override the result quality tier (e.g., set to max) and preserve hidden potential
+         *   return { costItems, resultItem: { ...resultItem, resultQualityTier: 10 } };
          * });
          */
-        onDeriveEquipmentReforgeRequirement: (interceptor: (baseItem: Item, costItems: Item[], resultItemName: string, resultQualityTier: number, gameFlags: Record<string, number>) => {
+        onDeriveEquipmentReforgeRequirement: (interceptor: (baseItem: Item, costItems: Item[], resultItem: {
+            resultItemName: string;
+            resultQualityTier: number;
+            resultHiddenPotential?: number;
+            resultEnchantment?: EnchantmentDesc;
+        }, gameFlags: Record<string, number>) => {
             costItems?: Item[];
-            resultItemName?: string;
-            resultQualityTier?: number;
-        } | undefined) => void;
+            resultItem?: Partial<{
+                resultItemName: string;
+                resultQualityTier: number;
+                resultHiddenPotential: number;
+                resultEnchantment: EnchantmentDesc;
+            }>;
+        } | undefined) => () => void;
         /**
          * Called before the completion dialog showing the reforged equipment. Allows mutating reforge cost items and result (but not base item).
          *
@@ -2423,7 +2484,7 @@ export interface ModAPI {
         onCompleteEquipmentReforge: (interceptor: (baseItem: Item, costItems: Item[], resultItem: Item, gameFlags: Record<string, number>) => {
             costItems?: Item[];
             resultItem?: Item;
-        } | undefined) => void;
+        } | undefined) => () => void;
         /**
          * Intercept the full set of changes planned for a new game before they are applied.
          * Return a modified intent to change starting items, techniques, flags, etc.
@@ -2434,35 +2495,71 @@ export interface ModAPI {
          *   flags: { ...intent.flags, my_mod_enabled: 1 },
          * }));
          */
-        onNewGame: (interceptor: (intent: NewGameIntent) => NewGameIntent) => void;
+        onNewGame: (interceptor: (intent: NewGameIntent) => NewGameIntent) => () => void;
+        /**
+         * Called when a saved game is loaded, allowing mods to mutate the initial state.
+         * The interceptor receives the loaded RootState and returns a modified state.
+         * Use this to adjust game state based on loaded save data.
+         * @param interceptor - Receives the loaded state and returns a modified copy
+         * @example
+         * modAPI.hooks.onGameLoad((state) => ({
+         *   ...state,
+         *   player: { ...state.player, flags: { ...state.player.flags, my_mod_flag: 1 } }
+         * }));
+         */
+        onGameLoad: (interceptor: (state: RootState) => RootState) => () => void;
+        /**
+         * Hook fired before combat advances a step
+         * Return a modified context to change combat state, a cancel object (with log message) to skip the step, or `null` to continue as normal.
+         */
+        onCombatBeforeStep: (interceptor: (step: RoundStep, ctx: CurrentCombatState) => CurrentCombatState | {
+            cancel: true;
+            logMessage: string;
+        } | null) => () => void;
+        /**
+         * Hook fired after combat advances a step
+         * Return a modified context to change combat state, or `null` to continue as normal.
+         */
+        onCombatAfterStep: (interceptor: (step: RoundStep, ctx: CurrentCombatState) => CurrentCombatState | null) => () => void;
+        /**
+         * Hook fired before combat starts a new round
+         * Return a modified context to change combat state, or `null` to continue as normal.
+         */
+        onCombatRoundStart: (interceptor: (ctx: CurrentCombatState) => CurrentCombatState | null) => () => void;
+        /**
+         * Hook fired after combat ends a round
+         * Return a modified context to change combat state, or `null` to continue as normal.
+         */
+        onCombatRoundEnd: (interceptor: (ctx: CurrentCombatState) => CurrentCombatState | null) => () => void;
     };
     /**
      * Inject UI into a named slot (dialog title or screen name).
      *
-     * The generator receives (api, element, inject):
+     * The generator receives (api, inject):
      * - api: full ModReduxAPI with game state, actions, and components
-     * - element: root DOM element of the slot; use querySelector to find children
-     * - inject(selector, content, mode?, position?): helper to portal content into the element
-     *   matched by selector. mode is 'overlay' (default, floats over) or 'inline'
-     *   (inserts as a sibling after the target, flowing with the layout).
-     *   position controls where content is placed (see InjectPosition enum).
+     * - inject(selector, content, placement?): places content relative to the matched element.
+     *   selector can be:
+     *     ''           the slot root itself
+     *     '#my-id'     find by id
+     *     '.a .b > .c' find by path (searched within the slot root)
+     *     someElement  a direct HTMLElement reference
+     *   placement controls where content appears (see InjectPlacement).
+     *   Defaults to 'appendChild' when selector is '' (add inside the slot), 'after' otherwise (sibling after the target).
      *
      * Slot names for dialogs are the id (e.g. 'combat-victory'). You can find these by inspecting the DOM in dev mode.
      * Slot names for screens match the ScreenType value (e.g. 'combat').
      *
      * @example
-     * // Add a button to combat victory dialog
-     * modAPI.ui.injectUI('combat-victory', (api, element, inject) => {
-     *   return inject('[aria-live="assertive"]',
+     * modAPI.ui.injectUI('combat-victory', (api, inject) => {
+     *   inject('[aria-live="assertive"]',
      *     <api.components.GameButton onClick={() => api.actions.changeQi(100)}>
      *       Absorb Qi
      *     </api.components.GameButton>,
-     *     'inline',
-     *     InjectPosition.After
+     *     'after'
      *   );
      * });
      */
-    injectUI: (slotName: string, generator: (api: ModReduxAPI, element: HTMLElement | null, inject: (selector: string, content: React.ReactNode, mode?: 'overlay' | 'inline', position?: InjectPosition) => React.ReactNode) => React.ReactNode) => void;
+    injectUI: (slotName: string, generator: (api: ModReduxAPI, inject: (selector: string | HTMLElement, content: React.ReactNode, placement?: InjectPlacement) => void) => void) => void;
     /**
      * Subscribe to any Redux state changes. The callback receives the new state.
      * Returns an unsubscribe function.
@@ -2486,6 +2583,27 @@ export interface ModAPI {
      * if (snap) console.log('Player realm:', snap.player.player.realm);
      */
     getGameStateSnapshot: () => RootState | null;
+    /**
+     * Optional combat sub-object that is only populated during active combat.
+     * Provides direct access to the current combat state for reading and modification.
+     *
+     * @example
+     * // Check if combat is active
+     * if (modAPI.combat) {
+     *   const playerHp = modAPI.combat.getPlayerState()?.hp;
+     *   modAPI.combat.setPlayerHp(500);
+     * }
+     */
+    combat?: {
+        /** Returns the current combat state, or undefined if not in combat */
+        getCombatState: () => CurrentCombatState | undefined;
+        /** Sets the current combat state */
+        setCombatState: (state: CurrentCombatState) => void;
+        /** Returns the combat log entries */
+        getCombatLog: () => CombatLogEntry[];
+        /** Returns true if combat is in progress */
+        isInCombat: () => boolean;
+    };
 }
 export type ModHooks = {
     [K in keyof ModAPI['hooks']]: Parameters<ModAPI['hooks'][K]>[0][];

package/dist/reduxState.d.ts

@@ -64,11 +64,6 @@ export interface InventoryState {
     favour: number;
     favoritedItems?: string[];
 }
-export interface StanceTracking {
-    techniques: string[];
-    name: string;
-    count: number;
-}
 export interface CombatState {
     player: PlayerEntity | undefined;
     playerState: CombatEntity | undefined;

package/dist/soulShardDelve.d.ts

@@ -108,7 +108,6 @@ export interface SoulShardDelveConfig {
     monsters: RegionMonsters;
     /** The boss room fought after all vestige rooms are cleared. */
     boss: DelveRoom;
-    customDropPool: DelveDropPool;
 }
 /** Persistent placed shard entry (survives between sessions). */
 export interface PersistedPlacedShard {
@@ -132,6 +131,8 @@ export interface SoulShardProgression {
     rechargeProgress: number;
     /** How many intensityRewards have already been granted. */
     claimedIntensityRewards: number;
+    /** True once the player has started at least one run on this shard. */
+    hasEnteredRun?: boolean;
 }
 /** Current run state stored in Redux. */
 export interface SoulShardDelveRunState {
@@ -145,6 +146,10 @@ export interface SoulShardDelveRunState {
     curses: string[];
     rewards: PendingReward[];
     openedRewards: boolean[];
+    /** Node rewards held back until the boss is beaten. */
+    nodeRewards: PendingReward[];
+    /** True once the threshold progression event has been played this run. */
+    thresholdEventPlayed?: boolean;
 }
 export interface SoulShardDelveState {
     /** Which soul shard config is currently selected (screen is open). */

package/dist/soulShardDelve.js

@@ -11,5 +11,5 @@ export function getThresholdQither(n) {
  *  +2% HP and power per 1 qither.
  */
 export function getQitherDifficulty(totalQither) {
-    return 1 + totalQither * 0.02;
+    return 1 + totalQither * 0.01;
 }

package/dist/stat.d.ts

@@ -3,7 +3,7 @@ import type { TechniqueElement } from './element';
 export declare const physicalStatistics: readonly ["eyes", "meridians", "dantian", "muscles", "digestion", "flesh"];
 export declare const socialStatistics: readonly ["age", "lifespan", "charisma", "battlesense", "craftskill", "artefactslots", "talismanslots", "condenseEfficiency", "pillsPerRound"];
 export declare const craftingStatistics: readonly ["maxpool", "pool", "maxtoxicity", "toxicity", "resistance", "itemEffectiveness", "control", "intensity", "critchance", "critmultiplier", "pillsPerRound", "poolCostPercentage", "stabilityCostPercentage", "successChanceBonus", "poolCostFlat"];
-export declare const combatStatistics: readonly ["maxhp", "hp", "maxbarrier", "barrier", "maxtoxicity", "toxicity", "resistance", "pillsPerRound", "itemEffectiveness", "power", "artefactpower", "critchance", "defense", "protection", "dr", "barrierMitigation", "lifesteal", "critmultiplier", "vulnerability", "weakness", "fistBoost", "blossomBoost", "weaponBoost", "cloudBoost", "bloodBoost", "celestialBoost", "fistAffinity", "blossomAffinity", "weaponAffinity", "cloudAffinity", "bloodAffinity", "celestialAffinity", "noneAffinity", "qiDroplets", "fistDisabled", "bloodDisabled", "blossomDisabled", "cloudDisabled", "celestialDisabled", "weaponDisabled", "noneDisabled", "pillsDisabled", "dropletsDisabled", "fistResistance", "blossomResistance", "weaponResistance", "cloudResistance", "bloodResistance", "celestialResistance", "damageBoost", "healingBoost", "barrierBoost", "overheal", "barrierBleed", "formationPartRecovery", "overcrit", "cultivatorResistance"];
+export declare const combatStatistics: readonly ["maxhp", "hp", "maxbarrier", "barrier", "maxtoxicity", "toxicity", "resistance", "pillsPerRound", "itemEffectiveness", "power", "artefactpower", "critchance", "defense", "protection", "dr", "barrierMitigation", "lifesteal", "critmultiplier", "vulnerability", "weakness", "fistBoost", "blossomBoost", "weaponBoost", "cloudBoost", "bloodBoost", "celestialBoost", "fistAffinity", "blossomAffinity", "weaponAffinity", "cloudAffinity", "bloodAffinity", "celestialAffinity", "noneAffinity", "qiDroplets", "fistDisabled", "bloodDisabled", "blossomDisabled", "cloudDisabled", "celestialDisabled", "weaponDisabled", "noneDisabled", "pillsDisabled", "dropletsDisabled", "fistResistance", "blossomResistance", "weaponResistance", "cloudResistance", "bloodResistance", "celestialResistance", "damageBoost", "healingBoost", "barrierBoost", "temphpBoost", "overheal", "barrierBleed", "formationPartRecovery", "overcrit", "cultivatorResistance", "temphp"];
 export type PhysicalStatistic = (typeof physicalStatistics)[number];
 export type SocialStatistic = (typeof socialStatistics)[number];
 export type CraftingStatistic = (typeof craftingStatistics)[number];
@@ -32,6 +32,8 @@ export declare const combatStatToName: {
 export declare const combatStatToDescription: {
     [key in CombatStatistic]: string;
 };
+export declare const percentageCombatStats: Set<"pillsPerRound" | "maxtoxicity" | "toxicity" | "resistance" | "itemEffectiveness" | "critchance" | "critmultiplier" | "maxhp" | "hp" | "maxbarrier" | "barrier" | "power" | "artefactpower" | "defense" | "protection" | "dr" | "barrierMitigation" | "lifesteal" | "vulnerability" | "weakness" | "fistBoost" | "blossomBoost" | "weaponBoost" | "cloudBoost" | "bloodBoost" | "celestialBoost" | "fistAffinity" | "blossomAffinity" | "weaponAffinity" | "cloudAffinity" | "bloodAffinity" | "celestialAffinity" | "noneAffinity" | "qiDroplets" | "fistDisabled" | "bloodDisabled" | "blossomDisabled" | "cloudDisabled" | "celestialDisabled" | "weaponDisabled" | "noneDisabled" | "pillsDisabled" | "dropletsDisabled" | "fistResistance" | "blossomResistance" | "weaponResistance" | "cloudResistance" | "bloodResistance" | "celestialResistance" | "damageBoost" | "healingBoost" | "barrierBoost" | "temphpBoost" | "overheal" | "barrierBleed" | "formationPartRecovery" | "overcrit" | "cultivatorResistance" | "temphp">;
+export declare const multiplicativePercentStats: Set<"pillsPerRound" | "maxtoxicity" | "toxicity" | "resistance" | "itemEffectiveness" | "critchance" | "critmultiplier" | "maxhp" | "hp" | "maxbarrier" | "barrier" | "power" | "artefactpower" | "defense" | "protection" | "dr" | "barrierMitigation" | "lifesteal" | "vulnerability" | "weakness" | "fistBoost" | "blossomBoost" | "weaponBoost" | "cloudBoost" | "bloodBoost" | "celestialBoost" | "fistAffinity" | "blossomAffinity" | "weaponAffinity" | "cloudAffinity" | "bloodAffinity" | "celestialAffinity" | "noneAffinity" | "qiDroplets" | "fistDisabled" | "bloodDisabled" | "blossomDisabled" | "cloudDisabled" | "celestialDisabled" | "weaponDisabled" | "noneDisabled" | "pillsDisabled" | "dropletsDisabled" | "fistResistance" | "blossomResistance" | "weaponResistance" | "cloudResistance" | "bloodResistance" | "celestialResistance" | "damageBoost" | "healingBoost" | "barrierBoost" | "temphpBoost" | "overheal" | "barrierBleed" | "formationPartRecovery" | "overcrit" | "cultivatorResistance" | "temphp">;
 export declare const uncommonStatTooltips: Partial<{
     [key in CombatStatistic]: string;
 }>;
@@ -74,6 +76,7 @@ export interface Scaling {
     };
     max?: Scaling;
     divideByStanceLength?: boolean;
+    multiplyByStanceLength?: boolean;
     upgradeKey?: string;
     buff?: Buff;
     increment?: number;

package/dist/stat.js

@@ -87,11 +87,13 @@ export const combatStatistics = [
     'damageBoost',
     'healingBoost',
     'barrierBoost',
+    'temphpBoost',
     'overheal',
     'barrierBleed',
     'formationPartRecovery',
     'overcrit',
     'cultivatorResistance',
+    'temphp',
 ];
 export const baseStatNumber = 10;
 export const expectedHpPerFlesh = 1000;
@@ -158,11 +160,13 @@ export const combatStatToName = {
     damageBoost: 'Damage Boost',
     healingBoost: 'Healing Boost',
     barrierBoost: 'Barrier Boost',
+    temphpBoost: 'Temporary Health Boost',
     overheal: 'Overheal',
     barrierBleed: 'Barrier Bleed',
     formationPartRecovery: 'Formation Part Recovery',
     overcrit: 'Overcrit',
     cultivatorResistance: 'Cultivator Resistance',
+    temphp: 'Temporary Health',
 };
 export const combatStatToDescription = {
     maxhp: 'The amount of damage you can take before you are unable to continue.',
@@ -177,7 +181,7 @@ export const combatStatToDescription = {
     protection: '',
     dr: '',
     lifesteal: '',
-    critchance: 'Your chance to get a critical effect on damage, healing, and barrier. Crit chance over 100% converts to bonus crit multiplier at a 1:3 ratio.',
+    critchance: 'Your chance to get a critical effect on damage, healing, and barrier. Crit Chance above 100% converts to bonus crit multiplier at a 1:3 ratio.',
     critmultiplier: '',
     vulnerability: '',
     weakness: '',
@@ -217,26 +221,66 @@ export const combatStatToDescription = {
     damageBoost: '',
     healingBoost: '',
     barrierBoost: '',
+    temphpBoost: '',
     overheal: '',
     barrierBleed: '',
     formationPartRecovery: '',
     overcrit: '',
     cultivatorResistance: '',
+    temphp: '',
 };
+// Combat stats that are displayed as percentages in tooltips and UI.
+export const percentageCombatStats = new Set([
+    'critchance',
+    'critmultiplier',
+    'dr',
+    'lifesteal',
+    'barrierMitigation',
+    'resistance',
+    'itemEffectiveness',
+    'vulnerability',
+    'weakness',
+    'protection',
+    'overheal',
+    'barrierBleed',
+    'overcrit',
+    'fistBoost',
+    'blossomBoost',
+    'weaponBoost',
+    'cloudBoost',
+    'bloodBoost',
+    'celestialBoost',
+    'damageBoost',
+    'healingBoost',
+    'barrierBoost',
+    'temphpBoost',
+    'fistResistance',
+    'blossomResistance',
+    'weaponResistance',
+    'cloudResistance',
+    'bloodResistance',
+    'celestialResistance',
+    'cultivatorResistance',
+]);
+// Stats whose sources multiply together rather than add.
+// Each source applies as (1 - value/100)^scaleFactor to a running multiplier.
+// The final value is converted back to a percentage: (1 - multiplier) * 100.
+export const multiplicativePercentStats = new Set(['weakness', 'dr']);
 // Uncommon stats that need auxiliary tooltips when they appear on buffs
 // These descriptions only show as aux tooltips in buff tooltips, not in the stats dialog
 export const uncommonStatTooltips = {
-    damageBoost: '<n>Damage Boost</n> increases all non-true damage dealt by a percentage.',
-    healingBoost: '<n>Healing Boost</n> increases all healing received by a percentage.',
-    barrierBoost: '<n>Barrier Boost</n> increases all barrier gained by a percentage.',
+    damageBoost: '<n>Damage Boost</n> modifies all non-true damage dealt by a percentage.',
+    healingBoost: '<n>Healing Boost</n> modifies all healing received by a percentage.',
+    barrierBoost: '<n>Barrier Boost</n> modifies all barrier gained by a percentage.',
+    temphpBoost: '<n>Temporary Health Boost</n> modifies all temporary health gained by a percentage.',
     overheal: '<n>Overheal</n> converts a percentage of healing beyond your maximum health into barrier.',
     protection: '<n>Protection</n> reduces damage taken to your health with diminishing returns. Does not affect damage taken to your barrier.',
-    weakness: '<n>Weakness</n> reduces your power.',
-    vulnerability: '<n>Vulnerability</n> increases damage taken to your <n>health</n>. Does not affect damage taken to your barrier.',
+    weakness: '<n>Weakness</n> reduces your power. Multiple sources multiply together.',
+    vulnerability: '<n>Vulnerability</n> increases damage taken to your <n>health</n>. Does not affect damage taken to your barrier. Multiple sources add together.',
     barrierBleed: '<n>Barrier Bleed</n> causes a percentage of any damage to bypass your barrier and strike your health directly.',
     formationPartRecovery: 'Each point of <n>Formation Part Recovery</n> returns a <n>Formation Part</n> used in combat back to your Spatial Ring after battle.',
-    overcrit: 'Each point of <n>Overcrit</n> allows your excess <n>Crit Chance</n> (above 100%) to roll an additional critical hit, instead of converting to bonus crit damage.',
-    dr: '<n>Damage Resistance</n> reduces damage taken to your health after defense is applied. Each point equals <num>1%</num> reduction. Does not affect damage taken to your barrier.',
+    overcrit: '<n>Overcrit</n> allows critical hits to chain up to <n>9</n> additional times. Your crit chance is multiplied by your overcrit percentage after each chain. Overcrit has a maximum of <n>90%</n>.',
+    dr: '<n>Damage Resistance</n> reduces damage taken to your health. Multiple sources multiply together. Does not affect damage taken to your barrier.',
 };
 export const craftingStatToName = {
     maxpool: 'Max Qi Pool',

package/dist/technique.d.ts

@@ -4,7 +4,7 @@ import type { DamageType } from './DamageType';
 import type { TechniqueElement } from './element';
 import type { Rarity } from './rarity';
 import type { Realm } from './realm';
-import type { PhysicalStatistic, SocialStatistic, Scaling } from './stat';
+import type { PhysicalStatistic, SocialStatistic, CombatStatistic, Scaling } from './stat';
 export declare const techniquePriorities: readonly ["", "Support", "Defensive", "Utility", "Aggressive", "Offensive"];
 export type TechniquePriority = (typeof techniquePriorities)[number];
 export interface KnownTechniqueMastery {
@@ -62,14 +62,17 @@ export interface Technique {
     enhancement?: number;
     i?: number;
 }
-export type TechniqueEffectKind = 'buffSelf' | 'consumeSelf' | 'buffTarget' | 'consumeTarget' | 'damage' | 'damageSelf' | 'barrier' | 'heal' | 'convertSelf' | 'mergeSelf' | 'cleanseToxicity' | 'modifyBuffGroup' | 'trigger' | 'repair' | 'permanentStatChange';
-export type TechniqueEffect = BuffSelfTechniqueEffect | ConsumeSelfTechniqueEffect | BuffTargetTechniqueEffect | ConsumeTargetTechniqueEffect | DamageTechniqueEffect | BarrierTechniqueEffect | HealTechniqueEffect | DamageSelfTechniqueEffect | ConvertSelfTechniqueEffect | MergeSelfTechniqueEffect | CleanseToxicityTechniqueEffect | ModifyBuffGroupEffect | TriggerEffect | RepairTechniqueEffect | PermanentStatChangeTechniqueEffect;
+export type TechniqueEffectKind = 'buffSelf' | 'consumeSelf' | 'buffTarget' | 'consumeTarget' | 'damage' | 'damageSelf' | 'barrier' | 'heal' | 'temporaryHealth' | 'convertSelf' | 'mergeSelf' | 'cleanseToxicity' | 'modifyBuffGroup' | 'trigger' | 'repair' | 'permanentStatChange';
+export type TechniqueEffect = BuffSelfTechniqueEffect | ConsumeSelfTechniqueEffect | BuffTargetTechniqueEffect | ConsumeTargetTechniqueEffect | DamageTechniqueEffect | BarrierTechniqueEffect | HealTechniqueEffect | GiveTemporaryHealthTechniqueEffect | DamageSelfTechniqueEffect | ConvertSelfTechniqueEffect | MergeSelfTechniqueEffect | CleanseToxicityTechniqueEffect | ModifyBuffGroupEffect | TriggerEffect | RepairTechniqueEffect | PermanentStatChangeTechniqueEffect;
 interface BaseTechniqueEffect {
     kind: TechniqueEffectKind;
     condition?: TechniqueCondition;
     triggerKey?: string;
     isAdditionalTooltip?: boolean;
     cantUpgrade?: boolean;
+    statChanges?: Partial<{
+        [key in CombatStatistic]: Scaling;
+    }>;
 }
 export type EffectTargeting = 'self' | 'party' | 'all';
 interface BuffSelfTechniqueEffect extends BaseTechniqueEffect {
@@ -135,6 +138,12 @@ interface HealTechniqueEffect extends BaseTechniqueEffect {
     hits?: Scaling;
     targeting?: EffectTargeting;
 }
+interface GiveTemporaryHealthTechniqueEffect extends BaseTechniqueEffect {
+    kind: 'temporaryHealth';
+    amount: Scaling;
+    hits?: Scaling;
+    targeting?: EffectTargeting;
+}
 interface CleanseToxicityTechniqueEffect extends BaseTechniqueEffect {
     kind: 'cleanseToxicity';
     amount: Scaling;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "afnm-types",
-  "version": "0.6.55",
+  "version": "0.6.56",
   "description": "Type definitions for Ascend From Nine Mountains",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",