bc-deeplib 2.4.2 → 4.0.0

package/dist/deeplib.d.ts

@@ -38,15 +38,14 @@ declare module 'bc-deeplib/base/base_module' {
        * Retrieves the current settings for this module.
        * If no settings exist yet, registers default settings first.
        */
-      get settings(): BaseSettingsModel;
+      get settings(): BaseSettingsModel | null;
       /**
        * Persists new settings for this module.
        * Automatically initializes storage and defaults if they don't exist.
        */
-      set settings(value: BaseSettingsModel);
+      set settings(value: BaseSettingsModel | null);
       /**
        * Initializes the module.
-       * Default implementation registers default settings immediately.
        * Subclasses can override to perform additional setup.
        */
       init(): void;
@@ -257,9 +256,9 @@ declare module 'bc-deeplib/base/elements_typings' {
   export type SettingElement = Button | Checkbox | Input | Label | Dropdown | Custom;
   export type BaseElementModel = {
       id: string;
-      size?: [width: number | null, height: number | null] | (() => [width: number | null, height: number | null]);
-      position?: [x: number, y: number] | (() => [x: number, y: number]);
-      disabled?: boolean | (() => boolean);
+      size?: Thunk<[width: number | null, height: number | null]>;
+      position?: Thunk<[x: number, y: number, anchor?: ElementHelp.AnchorXY]>;
+      disabled?: Thunk<boolean>;
   };
   export type Button = Prettify<{
       id: Parameters<typeof ElementButton.Create>[0];
@@ -271,7 +270,7 @@ declare module 'bc-deeplib/base/elements_typings' {
   export type Checkbox = Prettify<{
       type: 'checkbox';
       label?: string;
-      description?: string;
+      description?: ElementButton.StaticNode;
       setElementValue?: () => boolean;
       setSettingValue?: (val: boolean) => void;
       htmlOptions?: Partial<Record<'container' | 'checkbox' | 'label', Omit<HTMLOptions<any>, 'tag'>>> | null | undefined;
@@ -279,7 +278,7 @@ declare module 'bc-deeplib/base/elements_typings' {
   export type Input = Prettify<{
       type: 'text' | 'number' | 'color';
       label?: string;
-      description?: string;
+      description?: ElementButton.StaticNode;
       setElementValue?: () => string;
       setSettingValue?: (val: string) => void;
       htmlOptions?: Partial<Record<'container' | 'input' | 'label', Omit<HTMLOptions<any>, 'tag'>>> | null | undefined;
@@ -288,7 +287,7 @@ declare module 'bc-deeplib/base/elements_typings' {
       id: Parameters<typeof ElementCreateDropdown>[0];
       type: 'dropdown';
       label?: string;
-      description?: string;
+      description?: ElementButton.StaticNode;
       optionsList: Parameters<typeof ElementCreateDropdown>[1];
       setElementValue?: () => string;
       setSettingValue?: (val: string) => void;
@@ -302,7 +301,7 @@ declare module 'bc-deeplib/base/elements_typings' {
   export type Label = Prettify<{
       type: 'label';
       label?: string;
-      description?: string;
+      description?: ElementButton.StaticNode;
       htmlOptions?: Omit<HTMLOptions<any>, 'tag'>;
   } & BaseElementModel>;
   export type Custom = Prettify<{
@@ -312,25 +311,29 @@ declare module 'bc-deeplib/base/elements_typings' {
 
 }
 declare module 'bc-deeplib/base/initialization' {
-  import { BaseModule, ModSdkManager, ModStorage, MainMenuOptions, TranslationOptions, Logger } from 'bc-deeplib/deeplib';
+  import { ModSdkManager, ModStorage, MainMenuOptions, TranslationOptions, Logger, ModulesList } from 'bc-deeplib/deeplib';
   /** Configuration object for initializing a mod via `initMod`. */
   interface InitOptions {
       /**
-       * Information about the mod being initialized.
-       * - `info`    — Required metadata describing the mod.
-       * - `options` — Optional runtime configuration for the Mod SDK.
+       * Name of the mod.
+       * Used to identify the mod in the Mod SDK and storage.
        */
-      modInfo: {
-          info: ModSDKModInfo;
-          options?: ModSDKModOptions;
-      };
+      modName: string;
+      /**
+       * Repository URL for the mod.
+       * Used to register the mod with the Mod SDK and display in the main menu.
+       */
+      modRepository?: string;
       /**
        * List of modules (`BaseModule` subclasses) to register with the mod system.
        * Modules are initialized, loaded, and run in order.
        */
-      modules?: BaseModule[];
-      /** Configuration for customizing the main menu when the mod is active. */
-      mainMenuOptions?: MainMenuOptions;
+      modules?: Partial<ModulesList>;
+      /**
+       * Configuration for customizing the main menu when the mod is active.
+       * Does nothing if GUI module is not loaded.
+       */
+      mainMenuOptions?: Prettify<Omit<MainMenuOptions, 'repoLink'>>;
       /**
        * Optional hook executed *before* login when the player is not yet authenticated.
        * Useful for pre-login setup or display changes.
@@ -358,7 +361,8 @@ declare module 'bc-deeplib/base/initialization' {
    * Mod specific logger instance.
    * Initialized by `initMod()`.
    */
-  export let logger: Logger;
+  export let modLogger: Logger;
+  export let MOD_NAME: string;
   /**
    * Entry point for initializing a mod. Handles:
    *  - Setting up the Mod SDK
@@ -376,14 +380,14 @@ declare module 'bc-deeplib/base/initialization' {
 
 }
 declare module 'bc-deeplib/base/modules' {
-  import { BaseModule } from 'bc-deeplib/deeplib';
-  /**
-   * Global registry of all loaded modules, keyed by their class name.
-   *
-   * The map is populated via {@link registerModule} and accessed via {@link modules} or {@link getModule}.
-   * This is the central storage for active `BaseModule` instances during the mod lifecycle.
-   */
-  export const modulesMap: Map<string, BaseModule>;
+  import { GUI, VersionModule } from 'bc-deeplib/deeplib';
+  import { DebugModule } from 'bc-deeplib/modules/debug';
+  export interface ModulesList {
+      VersionModule: VersionModule;
+      GUI: GUI;
+      DebugModule: DebugModule;
+  }
+  export type ModuleKey = Prettify<keyof ModulesList>;
   /**
    * Retrieves all registered module instances.
    *
@@ -400,7 +404,7 @@ declare module 'bc-deeplib/base/modules' {
    * }
    * ```
    */
-  export function modules(): BaseModule[];
+  export function modules(): ModulesList[ModuleKey][];
   /**
    * Registers a module instance in the global registry.
    *
@@ -416,7 +420,7 @@ declare module 'bc-deeplib/base/modules' {
    * registerModule(new MyGlobalModule());
    * ```
    */
-  export function registerModule<T extends BaseModule>(module: T): T;
+  export function registerModule<K extends ModuleKey>(key: K, module: ModulesList[K]): ModulesList[K];
   /**
    * Retrieves a registered module by its type name.
    *
@@ -432,7 +436,7 @@ declare module 'bc-deeplib/base/modules' {
    * themeModule?.reloadTheme();
    * ```
    */
-  export function getModule<T extends BaseModule>(moduleType: string): T;
+  export function getModule<K extends ModuleKey>(key: K): ModulesList[K];
 
 }
 declare module 'bc-deeplib/deeplib' {
@@ -446,6 +450,7 @@ declare module 'bc-deeplib/deeplib' {
   export * from 'bc-deeplib/models/settings';
   export * from 'bc-deeplib/modules/gui';
   export * from 'bc-deeplib/modules/version';
+  export * from 'bc-deeplib/modules/debug';
   export * from 'bc-deeplib/screens/debug';
   export * from 'bc-deeplib/screens/main_menu';
   export * from 'bc-deeplib/screens/import_export';
@@ -453,6 +458,7 @@ declare module 'bc-deeplib/deeplib' {
   export * from 'bc-deeplib/utilities/elements/elements';
   export * from 'bc-deeplib/utilities/elements/helpers';
   export * from 'bc-deeplib/utilities/elements/layout';
+  export * from 'bc-deeplib/utilities/elements/modal';
   export * from 'bc-deeplib/utilities/common';
   export * from 'bc-deeplib/utilities/logger';
   export * from 'bc-deeplib/utilities/messages';
@@ -519,6 +525,29 @@ declare module 'bc-deeplib/models/settings' {
       Version: string;
   };
 
+}
+declare module 'bc-deeplib/modules/debug' {
+  import { BaseModule } from 'bc-deeplib/deeplib';
+  interface DebugSettings {
+      showRawTranslations: boolean;
+      showFileNames: boolean;
+      showIncomingServerTransactions: boolean;
+      incomingMessageFilterMode: 'include' | 'exclude';
+      incomingMessageTypes: string;
+      showOutcomingServerTransactions: boolean;
+      outcomingMessageFilterMode: 'include' | 'exclude';
+      outcomingMessageTypes: string;
+      showRawActivityNames: boolean;
+      showRawAssetNames: boolean;
+  }
+  export class DebugModule extends BaseModule {
+      debugSettings: DebugSettings;
+      load(): void;
+      unload(): void;
+      saveDebugSettings(): void;
+  }
+  export {};
+
 }
 declare module 'bc-deeplib/modules/gui' {
   import { BaseModule, BaseSubscreen, MainMenu } from 'bc-deeplib/deeplib';
@@ -533,12 +562,12 @@ declare module 'bc-deeplib/modules/gui' {
        * The label displayed on the settings button.
        * Can be a string or a function that returns a string dynamically.
        */
-      buttonText: string | (() => string);
+      buttonText: Thunk<string>;
       /**
        * The path to or Base64 data of the icon for the settings button.
        * Can be a string or a function that returns a string dynamically.
        */
-      image: string | (() => string);
+      image: Thunk<string>;
       /**
        * The main menu screen for the mod.
        */
@@ -625,7 +654,7 @@ declare module 'bc-deeplib/modules/version' {
       private static afterEach?;
       private static beforeAll?;
       private static afterAll?;
-      constructor(options: VersionModuleOptions);
+      constructor(options?: VersionModuleOptions);
       /**
        * Initializes the module on load:
        * - Stores the current mod version.
@@ -664,9 +693,12 @@ declare module 'bc-deeplib/modules/version' {
 declare module 'bc-deeplib/screens/debug' {
   import { SettingElement } from 'bc-deeplib/base/elements_typings';
   import { BaseSubscreen, SubscreenOptions } from 'bc-deeplib/deeplib';
+  import { DebugModule } from 'bc-deeplib/modules/debug';
   export class GuiDebug extends BaseSubscreen {
       protected static subscreenOptions: SubscreenOptions;
+      readonly module: DebugModule;
       get pageStructure(): SettingElement[][];
+      exit(): void;
   }
 
 }
@@ -714,6 +746,9 @@ declare module 'bc-deeplib/screens/import_export' {
       exportToClipboard(data: string): Promise<void>;
       /** Prompts the user to enter data and returns it. */
       importFromClipboard(): Promise<string | null>;
+      private getSelectedModules;
+      private buildExportPayload;
+      private applyImportPayload;
   }
   export {};
 
@@ -799,6 +834,17 @@ declare module 'bc-deeplib/utilities/common' {
    * Converts bytes to kilobytes.
    */
   export const byteToKB: (nByte: number) => number;
+  export type Ok<T> = {
+      ok: true;
+      value: T;
+  };
+  export type Err<E = unknown> = {
+      ok: false;
+      error: E;
+  };
+  export type Result<T, E = unknown> = Ok<T> | Err<E>;
+  export function tryCatch<T, E = unknown>(fn: () => T, mapError?: (e: unknown) => E): Result<T, E>;
+  export function tryCatchAsync<T, E = unknown>(fn: () => Promise<T>, mapError?: (e: unknown) => E): Promise<Result<T, E>>;
 
 }
 declare module 'bc-deeplib/utilities/data' {
@@ -821,11 +867,12 @@ declare module 'bc-deeplib/utilities/data' {
       get playerStorage(): T;
       set playerStorage(value: T);
       get extensionStorage(): string;
-      set extensionStorage(value: string);
+      private set extensionStorage(value);
       setLocalStorage(key: string, value: object): void;
       getLocalStorage(key: string): object | null;
       load(): void;
       save(): void;
+      storageSize(): number;
       static dataDecompress<T = object>(string: string): T | null;
       static dataCompress(object: object): string;
       static measureSize(data: unknown): number;
@@ -851,14 +898,14 @@ declare module 'bc-deeplib/utilities/elements/elements' {
       createBackNext: typeof elementPrevNext;
   };
   function elementCreateButton(options: Omit<Button, 'type'>): HTMLButtonElement;
-  function elementCreateCheckbox(options: Omit<Checkbox, 'type'>): HTMLElement;
+  function elementCreateCheckbox(options: Omit<Checkbox, 'type'>): HTMLLabelElement;
   function elementCreateCustom(options: Omit<Custom, 'type'>): HTMLElement;
-  function elementCreateInput(options: Input): HTMLElement;
-  function elementCreateLabel(options: Omit<Label, 'type'>): HTMLElement;
-  function elementCreateDropdown(options: Omit<Dropdown, 'type'>): HTMLLabelElement | HTMLDivElement;
+  function elementCreateInput(options: Input): HTMLLabelElement;
+  function elementCreateLabel(options: Omit<Label, 'type'>): HTMLLabelElement;
+  function elementCreateDropdown(options: Omit<Dropdown, 'type'>): HTMLLabelElement;
   function elementCreateTooltip(): HTMLDivElement;
   function elementGetTooltip(): HTMLElement | undefined;
-  function elementSetTooltip(text: string): boolean;
+  function elementSetTooltip(text: ElementButton.StaticNode, position?: 'top' | 'bottom'): boolean;
   interface PrevNext {
       id: string;
       initialLabel?: string;
@@ -873,6 +920,85 @@ declare module 'bc-deeplib/utilities/elements/elements' {
       setNextTooltip: (tooltip: string) => void;
   }
   function elementPrevNext(options: PrevNext): HTMLElement;
+  export {};
+
+}
+declare module 'bc-deeplib/utilities/elements/helpers' {
+  import { SettingElement } from 'bc-deeplib/base/elements_typings';
+  export const domUtil: {
+      /**
+       * Automatically sets the position of the element based on the given position.
+       * The position can be either a [x, y] tuple or a function returning such a tuple.
+       * If both x and y are defined, the element's position is updated accordingly.
+       */
+      autoSetPosition: typeof autoSetPosition;
+      /**
+       * Automatically sets the size of the element based on the given size.
+       * The size can be either a [width, height] tuple or a function returning such a tuple.
+       * If both width and height are defined, the element's size is updated accordingly.
+       */
+      autoSetSize: typeof autoSetSize;
+      /**
+       * Hides the element by setting its CSS display property to 'none'.
+       * If the element cannot be found, the function does nothing.
+       */
+      hide: typeof hide;
+      /**
+       * Unhides the element by clearing its CSS display property (sets it to '').
+       * If the element cannot be found, the function does nothing.
+       */
+      unhide: typeof unhide;
+      /**
+       * Checks if the element has overflow content.
+       * Returns an object indicating if there is any overflow,
+       * and specifically if there is vertical or horizontal overflow.
+       * Returns null if the element is not found.
+       */
+      hasOverflow: typeof hasOverflow;
+      /**
+       * Checks if two rectangles overlap.
+       * Returns true if the rectangles overlap, false otherwise.
+       */
+      doRectsOverlap: typeof doRectsOverlap;
+  };
+  function autoSetPosition(_: ElementHelp.ElementOrId, position: SettingElement['position']): void;
+  function autoSetSize(_: ElementHelp.ElementOrId, size: SettingElement['size']): void;
+  function hide(_: ElementHelp.ElementOrId): void;
+  function unhide(_: ElementHelp.ElementOrId): void;
+  function hasOverflow(el: ElementHelp.ElementOrId): {
+      any: boolean;
+      vertical: boolean;
+      horizontal: boolean;
+  } | null;
+  function doRectsOverlap(rect1: DOMRect, rect2: DOMRect): boolean;
+  export {};
+
+}
+declare module 'bc-deeplib/utilities/elements/layout' {
+  export const layout: {
+      getSubscreen: typeof elementGetSubscreenDiv;
+      appendToSubscreen: typeof elementAppendToSubscreenDiv;
+      removeSubscreen: typeof elementRemoveSubscreenDiv;
+      getSettingsDiv: typeof elementGetSettingsDiv;
+      appendToSettingsDiv: typeof elementAppendToSettingsDiv;
+      removeSettingsDiv: typeof elementRemoveSettingsDiv;
+      getMiscDiv: typeof elementGetMiscDiv;
+      appendToMiscDiv: typeof elementAppendToMiscDiv;
+      removeMiscDiv: typeof elementRemoveMiscDiv;
+  };
+  function elementGetSubscreenDiv(): HTMLElement;
+  function elementRemoveSubscreenDiv(): void;
+  function elementAppendToSubscreenDiv(...element: HTMLElement[]): void;
+  function elementGetSettingsDiv(): HTMLElement;
+  function elementAppendToSettingsDiv(...element: HTMLElement[]): void;
+  function elementRemoveSettingsDiv(): void;
+  function elementGetMiscDiv(): HTMLElement;
+  function elementAppendToMiscDiv(...element: HTMLElement[]): void;
+  function elementRemoveMiscDiv(): void;
+  export {};
+
+}
+declare module 'bc-deeplib/utilities/elements/modal' {
   export type ModalButton<T extends string = string> = {
       /** Button label text. */
       text: string;
@@ -908,7 +1034,24 @@ declare module 'bc-deeplib/utilities/elements/elements' {
       escapeAction?: T;
       /** Action sent when Enter key is pressed. */
       enterAction?: T;
+      /** Modal ID. */
+      modalId?: string;
   };
+  export interface AlertOptions {
+      /** Auto-close timeout in milliseconds. */
+      timeoutMs?: number;
+      /** Modal ID. */
+      modalId?: string;
+  }
+  export interface ConfirmOptions {
+      /** Modal ID. */
+      modalId?: string;
+  }
+  export interface PromptOptions {
+      defaultValue?: string;
+      /** Modal ID. */
+      modalId?: string;
+  }
   /**
    * Modal dialog implementation with queuing, buttons, optional input, and focus trapping.
    * Multiple modals are queued to ensure only one is visible at a time.
@@ -931,17 +1074,17 @@ declare module 'bc-deeplib/utilities/elements/elements' {
       /**
        * Shows a simple alert modal with a single "OK" button.
        */
-      static alert(msg: ElementButton.StaticNode, timeoutMs?: number): Promise<void>;
+      static alert(msg: ElementButton.StaticNode, opts?: AlertOptions): Promise<void>;
       /**
        * Shows a confirmation modal with "Cancel" and "OK" buttons.
        * Returns true if "OK" is clicked.
        */
-      static confirm(msg: ElementButton.StaticNode): Promise<boolean>;
+      static confirm(msg: ElementButton.StaticNode, opts?: ConfirmOptions): Promise<boolean>;
       /**
        * Shows a prompt modal with an input field and "Submit"/"Cancel" buttons.
        * Returns the input value if submitted, otherwise null.
        */
-      static prompt(msg: ElementButton.StaticNode, defaultValue?: string): Promise<string | null>;
+      static prompt(msg: ElementButton.StaticNode, opts?: PromptOptions): Promise<string | null>;
       /** Creates the input element for the modal, applying configuration and validation. */
       private renderInput;
       /** Creates modal action buttons from configuration. */
@@ -961,76 +1104,6 @@ declare module 'bc-deeplib/utilities/elements/elements' {
       /** A function that processes the queue, removing the first modal */
       private static dequeue;
   }
-  export {};
-
-}
-declare module 'bc-deeplib/utilities/elements/helpers' {
-  import { SettingElement } from 'bc-deeplib/base/elements_typings';
-  export const domUtil: {
-      /**
-       * Automatically sets the position of the element based on the given position.
-       * The position can be either a [x, y] tuple or a function returning such a tuple.
-       * If both x and y are defined, the element's position is updated accordingly.
-       */
-      autoSetPosition: typeof autoSetPosition;
-      /**
-       * Automatically sets the size of the element based on the given size.
-       * The size can be either a [width, height] tuple or a function returning such a tuple.
-       * If both width and height are defined, the element's size is updated accordingly.
-       */
-      autoSetSize: typeof autoSetSize;
-      /**
-       * Hides the element by setting its CSS display property to 'none'.
-       * If the element cannot be found, the function does nothing.
-       */
-      hide: typeof hide;
-      /**
-       * Unhides the element by clearing its CSS display property (sets it to '').
-       * If the element cannot be found, the function does nothing.
-       */
-      unhide: typeof unhide;
-      /**
-       * Checks if the element has overflow content.
-       * Returns an object indicating if there is any overflow,
-       * and specifically if there is vertical or horizontal overflow.
-       * Returns null if the element is not found.
-       */
-      hasOverflow: typeof hasOverflow;
-  };
-  function autoSetPosition(_: ElementHelp.ElementOrId, position: SettingElement['position']): void;
-  function autoSetSize(_: ElementHelp.ElementOrId, size: SettingElement['size']): void;
-  function hide(_: ElementHelp.ElementOrId): void;
-  function unhide(_: ElementHelp.ElementOrId): void;
-  function hasOverflow(el: ElementHelp.ElementOrId): {
-      any: boolean;
-      vertical: boolean;
-      horizontal: boolean;
-  } | null;
-  export {};
-
-}
-declare module 'bc-deeplib/utilities/elements/layout' {
-  export const layout: {
-      getSubscreen: typeof elementGetSubscreenDiv;
-      appendToSubscreen: typeof elementAppendToSubscreenDiv;
-      removeSubscreen: typeof elementRemoveSubscreenDiv;
-      getSettingsDiv: typeof elementGetSettingsDiv;
-      appendToSettingsDiv: typeof elementAppendToSettingsDiv;
-      removeSettingsDiv: typeof elementRemoveSettingsDiv;
-      getMiscDiv: typeof elementGetMiscDiv;
-      appendToMiscDiv: typeof elementAppendToMiscDiv;
-      removeMiscDiv: typeof elementRemoveMiscDiv;
-  };
-  function elementGetSubscreenDiv(): HTMLElement;
-  function elementRemoveSubscreenDiv(): void;
-  function elementAppendToSubscreenDiv(...element: HTMLElement[]): void;
-  function elementGetSettingsDiv(): HTMLElement;
-  function elementAppendToSettingsDiv(...element: HTMLElement[]): void;
-  function elementRemoveSettingsDiv(): void;
-  function elementGetMiscDiv(): HTMLElement;
-  function elementAppendToMiscDiv(...element: HTMLElement[]): void;
-  function elementRemoveMiscDiv(): void;
-  export {};
 
 }
 declare module 'bc-deeplib/utilities/event_channel' {
@@ -1131,9 +1204,8 @@ declare module 'bc-deeplib/utilities/sdk' {
    * provides methods to register mods, hook functions, and manage patches.
    */
   export class ModSdkManager {
-      private static SDK;
-      private static patchedFunctions;
-      static ModInfo: ModSDKModInfo;
+      private SDK;
+      private patchedFunctions;
       /** Registers a mod with the SDK and stores mod information. */
       constructor(info: ModSDKModInfo, options?: ModSDKModOptions);
       /** Retrieves or initializes patch data for a given target function. */
@@ -1162,6 +1234,10 @@ declare module 'bc-deeplib/utilities/sdk' {
        * Removes all hooks associated with a specific module across all patched functions.
        */
       removeAllHooksByModule(module: ModuleCategory): boolean;
+      /**
+       * Unloads the mod removing all hooks and patches by it.
+       */
+      unload(): void;
   }
   export {};