bc-deeplib 1.1.1 → 1.1.3

package/dist/deeplib.d.ts

@@ -1,15 +1,82 @@
 declare module 'bc-deeplib/base/base_module' {
   import { BaseSettingsModel, Subscreen } from 'bc-deeplib/deeplib';
+  /**
+   * An abstract foundation for modular systems that require:
+   *  - Optional settings screens
+   *  - Persistent settings storage per module
+   *  - Default settings registration
+   *  - Lifecycle hooks for loading, running, and unloading
+   *
+   * ### Responsibilities
+   * This class defines the base contract for all modules in the system:
+   *  - Provides a standardized interface for retrieving and storing settings
+   *  - Ensures default settings are registered if missing
+   *  - Integrates with the module storage system (`modStorage`)
+   *  - Offers overridable lifecycle methods (`init`, `load`, `run`, `unload`)
+   *
+   * **Subclass Requirements:**
+   *  - Must extend `BaseModule`
+   *  - Should override `defaultSettings` to define defaults for its settings, if any
+   *  - May override `settingsScreen` to provide a UI component
+   *  - May override lifecycle methods as needed
+   */
   export abstract class BaseModule {
+      /**
+       * An optional UI screen for configuring this module's settings.
+       * Subclasses can override this getter to provide a `Subscreen` instance.
+       * Modules with screens are automatically registered to the main menu.
+       */
       get settingsScreen(): Subscreen | null;
+      /**
+       * The storage key under which this module's settings will be saved.
+       * Defaults to the class name.
+       *
+       * Subclasses can override this if they require a custom storage key.
+       */
       get settingsStorage(): string | null;
+      /**
+       * Retrieves the current settings for this module.
+       * If no settings exist yet, registers default settings first.
+       */
       get settings(): BaseSettingsModel;
+      /**
+       * Persists new settings for this module.
+       * Automatically initializes storage and defaults if they don't exist.
+       */
       set settings(value: BaseSettingsModel);
+      /**
+       * Initializes the module.
+       * Default implementation registers default settings immediately.
+       * Subclasses can override to perform additional setup.
+       */
       init(): void;
+      /**
+       * Registers default settings for this module in persistent storage.
+       * Only runs if a storage key and default settings are defined.
+       *
+       * If some settings already exist, they will be merged with defaults.
+       * Existing values will NOT be overwritten.
+       */
       registerDefaultSettings(): void;
+      /**
+       * Provides default settings for this module.
+       * Subclasses should override this getter to return their defaults.
+       */
       get defaultSettings(): BaseSettingsModel | null;
+      /**
+       * Called when the module is loaded into the system.
+       * Subclasses should override to perform data loading or initialization.
+       */
       load(): void;
+      /**
+       * By default doesn't get called each frame, only once when the module is loaded.
+       * Subclasses can override to implement runtime logic.
+       */
       run(): void;
+      /**
+       * Called when the module is being removed.
+       * Subclasses can override to perform cleanup or save final state.
+       */
       unload(): void;
   }
 
@@ -17,33 +84,123 @@ declare module 'bc-deeplib/base/base_module' {
 declare module 'bc-deeplib/base/base_subscreen' {
   import { BaseModule, BaseSettingsModel } from 'bc-deeplib/deeplib';
   import { SettingElement } from 'bc-deeplib/base/elements_typings';
+  /** Optional configuration flags for a `BaseSubscreen` instance. */
   type SubscreenOptions = {
+      /**
+       * If `true`, the subscreen will draw the player's character model
+       * in the UI when `run()` is called.
+       * Also shift the UI to the right to make room for the character.
+       */
       drawCharacter?: boolean;
   };
+  /**
+   * Represents a constructor type for a subscreen.
+   * Allows dynamic instantiation of subscreen classes with optional
+   * configuration options and a parent module reference.
+   */
   export type Subscreen = new (subscreenOptions?: SubscreenOptions, module?: BaseModule) => BaseSubscreen;
-  export function getCurrentSubscreen(): BaseSubscreen | null;
+  /** Switches the active subscreen in the global `GUI` instance. */
   export function setSubscreen(subscreen: BaseSubscreen | string | null): BaseSubscreen | null;
+  /**
+   * Abstract base class for creating settings/configuration subscreens in a module.
+   *
+   * ### Responsibilities
+   * This class defines the base contract for all modules in the system:
+   *  - Provides a standardized interface for retrieving and storing settings
+   *  - Ensures default settings are registered if missing
+   *  - Integrates with the module storage system (`modStorage`)
+   *  - Offers overridable lifecycle methods (`init`, `load`, `run`, `unload`)
+   *
+   * **Subclass Requirements:**
+   *  - Must extend `BaseSubscreen`
+   *  - Should override `name`, `icon` to define subscreen metadata
+   *  - May override `pageStructure` to define UI layout and controls
+   *  - May override lifecycle methods as needed
+   */
   export abstract class BaseSubscreen {
+      /** Global registry of currently rendered elements and their definitions. */
       static currentElements: [HTMLElement, SettingElement][];
+      /** Tracks the currently visible page number (1-based index). */
       static currentPage: number;
+      /** Runtime options for this subscreen. */
       readonly options: SubscreenOptions;
+      /** Reference to the module this subscreen belongs to. */
       readonly module: BaseModule;
       constructor(subscreenOptions?: SubscreenOptions, module?: BaseModule);
+      /**
+       * Logical name of this subscreen.
+       * Used for localization key resolution in `load()`.
+       * Subclasses should override this with a meaningful identifier.
+       */
       get name(): string;
+      /**
+       * Path to or Base64 data for an icon representing this subscreen.
+       * Defaults to empty string (no icon).
+       */
       get icon(): string;
-      get subscreenName(): string;
+      /** Changes the currently active subscreen. */
       setSubscreen(screen: BaseSubscreen | string | null): BaseSubscreen | null;
+      /** Gets this subscreen's settings object from its parent module. */
       get settings(): BaseSettingsModel;
+      /** Updates this subscreen's settings in its parent module. */
       set settings(value: BaseSettingsModel);
+      /**
+       * Defines the paginated layout of the subscreen's settings UI.
+       * Each element in the outer array is a page; each page contains `SettingElement`s.
+       *
+       * Subclasses should override to define their actual UI structure.
+       */
       get pageStructure(): SettingElement[][];
+      /** Gets the currently visible page's settings elements. */
       get currentPage(): SettingElement[];
+      /**
+       * Changes the visible page in a multi-page subscreen.
+       * Automatically wraps around when going past the first or last page.
+       */
       changePage(page: number, setLabel: (label: string) => void): void;
+      /**
+       * Updates the DOM to show only elements belonging to the current page.
+       * All elements on other pages are hidden.
+       */
       managePageElementsVisibility(): void;
+      /**
+       * Called when this subscreen is first displayed.
+       * Builds the layout, initializes navigation, and renders all settings elements.
+       *
+       * Handles:
+       *  - Ensuring each module with a settings screen has its defaults loaded
+       *  - Creating navigation menus and back/next page controls
+       *  - Building and appending UI elements based on `pageStructure`
+       *  - Setting up exit button and tooltip
+       *  - Resetting to page 1
+       */
       load(): void;
+      /**
+       * Called each frame while this subscreen is active.
+       * Default behavior draws the player's character if `drawCharacter` is enabled.
+       */
       run(): void;
+      /**
+       * Handles mouse clicks *on canvas* while the subscreen is active.
+       * Default implementation is empty — subclasses may override.
+       */
       click(): void;
+      /**
+       * Exits this subscreen, returning to the main menu.
+       * Also saves persistent storage changes.
+       * Called after the `unload`.
+       */
       exit(): void;
+      /**
+       * Called when the window is resized.
+       * Also checks for overflow in the settings div and applies styling accordingly.
+       */
       resize(onLoad?: boolean): void;
+      /**
+       * Called when this subscreen is being removed.
+       * Resets the static element registry and removes the subscreen from the layout.
+       * Called before `exit`.
+       */
       unload(): void;
   }
   export {};
@@ -101,33 +258,137 @@ declare module 'bc-deeplib/base/elements_typings' {
 
 }
 declare module 'bc-deeplib/base/initialization' {
-  import { BaseModule, ModSdkManager, BaseMigrator, ModStorage, MainMenuOptions } from 'bc-deeplib/deeplib';
+  import { BaseModule, ModSdkManager, BaseMigrator, ModStorage, MainMenuOptions, TranslationOptions } 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.
+       */
       modInfo: {
           info: ModSDKModInfo;
           options?: ModSDKModOptions;
       };
+      /**
+       * List of modules (`BaseModule` subclasses) to register with the mod system.
+       * Modules are initialized, loaded, and run in order.
+       */
       modules?: BaseModule[];
+      /**
+       * List of data migration handlers to register with the `VersionModule`.
+       * Each `BaseMigrator` handles upgrading data from one version to another.
+       */
       migrators?: BaseMigrator[];
+      /** Configuration for customizing the main menu when the mod is active. */
       mainMenuOptions?: MainMenuOptions;
+      /**
+       * Optional hook executed *before* login when the player is not yet authenticated.
+       * Useful for pre-login setup or display changes.
+       */
       beforeLogin?: () => (void);
+      /**
+       * Optional async/sync function run after modules and translations are initialized.
+       * Can be used to perform additional setup tasks.
+       */
       initFunction?: () => (void | Promise<void>);
-      pathToTranslationsFolder?: string;
+      /** Options for initializing the localization/translation system. */
+      translationOptions?: TranslationOptions;
   }
+  /**
+   * Global storage handler for mod.
+   * Initialized by `initMod()` and mod data loaded by `init()`.
+   */
   export let modStorage: ModStorage;
+  /**
+   * Entry point for initializing a mod. Handles:
+   *  - Setting up the Mod SDK
+   *  - Preparing persistent storage
+   *  - Injecting required styles
+   *  - Delaying initialization until login (if necessary)
+   */
   export function initMod(options: InitOptions): {
       sdk: ModSdkManager;
   };
+  /**
+   * Fully initializes the mod after login.
+   * Handles:
+   *  - Preventing double-load
+   *  - Loading mod data
+   *  - Initializing localization
+   *  - Registering modules and migrators
+   *  - Running optional init functions
+   *  - Applying main menu changes
+   *  - Merging default settings into module settings
+   *
+   * @param options {InitOptions} Configuration for mod initialization.
+   */
   export function init(options: InitOptions): Promise<void>;
+  /**
+   * Cleans up and removes the mod from memory.
+   * Calls `unload()` on all modules and removes the global loaded flag.
+   */
   export function unloadMod(): true;
   export {};
 
 }
 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>;
+  /**
+   * Retrieves all registered module instances.
+   *
+   * @returns An array containing every module currently stored in {@link modulesMap}.
+   *
+   * @remarks
+   * The returned array is a **shallow copy** of the `Map` values, meaning that
+   * changes to the array do not affect the registry itself.
+   *
+   * @example
+   * ```ts
+   * for (const mod of modules()) {
+   *   mod.run();
+   * }
+   * ```
+   */
   export function modules(): BaseModule[];
+  /**
+   * Registers a module instance in the global registry.
+   *
+   * @returns The same module instance passed in, for chaining or immediate use.
+   *
+   * @remarks
+   * - If a module with the same constructor name already exists, it will be **overwritten**.
+   * - Keys are based on the class name (`module.constructor.name`), so name collisions are possible
+   *   if two different classes share the same name.
+   *
+   * @example
+   * ```ts
+   * registerModule(new MyGlobalModule());
+   * ```
+   */
   export function registerModule<T extends BaseModule>(module: T): T;
+  /**
+   * Retrieves a registered module by its type name.
+   *
+   * @returns The matching module instance cast to type `T`, or `undefined` if not found.
+   *
+   * @remarks
+   * This function does not perform runtime type checks. If the type parameter `T`
+   * does not match the actual module type, you may get runtime errors when using the result.
+   *
+   * @example
+   * ```ts
+   * const themeModule = getModule<ThemeModule>('ThemeModule');
+   * themeModule?.reloadTheme();
+   * ```
+   */
   export function getModule<T extends BaseModule>(moduleType: string): T;
 
 }
@@ -145,9 +406,9 @@ declare module 'bc-deeplib/deeplib' {
   export * from 'bc-deeplib/screens/main_menu';
   export * from 'bc-deeplib/screens/import_export';
   export * from 'bc-deeplib/utilities/data';
-  export * from 'bc-deeplib/utilities/elements/advanced_elements';
-  export * from 'bc-deeplib/utilities/elements/element_helpers';
-  export * from 'bc-deeplib/utilities/elements/layout_elements';
+  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/common';
   export * from 'bc-deeplib/utilities/logger';
   export * from 'bc-deeplib/utilities/messages';
@@ -157,15 +418,50 @@ declare module 'bc-deeplib/deeplib' {
 
 }
 declare module 'bc-deeplib/migrators/base_migrator' {
+  /**
+   * Abstract base class for versioned migration handlers.
+   *
+   * A migrator is responsible for upgrading or transforming stored data
+   * when the mod version changes. Each migrator targets a specific version
+   * and executes its {@link Migrate} method once when needed.
+   *
+   * @remarks
+   * To create a new migrator:
+   * 1. Extend `BaseMigrator`.
+   * 2. Implement the {@link MigrationVersion} getter to return the target version string.
+   * 3. Implement {@link Migrate} with the migration logic (e.g., data structure changes).
+   */
   export abstract class BaseMigrator {
+      /**
+       * Gets the target version string for this migration.
+       *
+       * @remarks
+       * - This should exactly match the version format used by the mod
+       * - Used by the migration system to determine if this migration should be executed.
+       */
       abstract get MigrationVersion(): string;
-      abstract Migrate(): boolean;
+      /**
+       * Executes the migration logic for this version.
+       *
+       * @remarks
+       * - Called once when upgrading from a version earlier than {@link MigrationVersion}.
+       * - Should handle any necessary data transformations, cleanup, or initialization
+       *   to bring the mod's state up to date with the new version.
+       * - Must be idempotent — running it multiple times should not cause data corruption.
+       */
+      abstract Migrate(): void;
   }
 
 }
 declare module 'bc-deeplib/models/base' {
+  /**
+   * Represents the base settings structure for a mod.
+   * Present for all mods.
+   */
   export type BaseSettingsModel = {
+      /** Whether the mod is currently active. */
       modEnabled: boolean;
+      /** Whether to display a notification when a new version is detected. */
       doShowNewVersionMessage: boolean;
   };
 
@@ -181,28 +477,69 @@ declare module 'bc-deeplib/models/settings' {
 }
 declare module 'bc-deeplib/modules/gui' {
   import { BaseModule, BaseSubscreen, MainMenu } from 'bc-deeplib/deeplib';
+  /** Options for configuring a mod's main button in the extensions menu. */
   type ModButtonOptions = {
+      /**
+       * Unique identifier for the mod's settings button.
+       * Used internally by the preference system to track the button.
+       */
       Identifier: string;
+      /**
+       * The label displayed on the settings button.
+       * Can be a string or a function that returns a string dynamically.
+       */
       ButtonText: string | (() => 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);
-      load?: () => void;
-      click?: () => void;
-      run?: () => void;
-      unload?: () => void;
-      exit?: () => boolean | void;
   };
+  /**
+   * Central mod GUI controller that manages all subscreens.
+   *
+   * This module is responsible for:
+   * - Registering the mod's settings button in the game's preferences.
+   * - Managing subscreens (including settings screens for all registered modules).
+   * - Routing lifecycle events (load, run, click, exit, unload) to the active subscreen.
+   */
   export class GUI extends BaseModule {
+      /** The singleton instance of the GUI controller. */
       static instance: GUI | null;
+      /** All subscreens managed by this GUI, including the main menu and module settings screens. */
       private _subscreens;
+      /** The mod's main menu screen. */
       private _mainMenu;
+      /** The currently active subscreen, or `null` if none is active. */
       private _currentSubscreen;
+      /** Options defining how the mod's settings button is displayed and behaves. */
       private _modButtonOptions;
+      /** Returns all registered subscreens. */
       get subscreens(): BaseSubscreen[];
+      /** Returns the main menu subscreen instance. */
       get mainMenu(): MainMenu;
+      /** Returns the currently active subscreen. */
       get currentSubscreen(): BaseSubscreen | null;
+      /**
+       * Sets the current subscreen.
+       * Accepts either a `BaseSubscreen` instance or the `name` of a subscreen.
+       *
+       * @throws If a string is provided but no subscreen with that name exists.
+       */
       set currentSubscreen(subscreen: BaseSubscreen | string | null);
+      /**
+       * Creates the GUI instance and initializes the main menu.
+       *
+       * @throws If another `GUI` instance already exists.
+       */
       constructor(modButtonOptions: ModButtonOptions);
-      get defaultSettings(): null;
+      /**
+       * Loads the GUI and registers the mod's settings button in the extensions menu.
+       *
+       * - Creates subscreens for each module's settings screen.
+       * - Registers lifecycle callbacks for subscreens events.
+       * - Sets up the main menu and its subscreens.
+       */
       load(): void;
   }
   export {};
@@ -210,19 +547,64 @@ declare module 'bc-deeplib/modules/gui' {
 }
 declare module 'bc-deeplib/modules/version' {
   import { BaseMigrator, BaseModule } from 'bc-deeplib/deeplib';
+  /**
+   * Handles version tracking, new version detection, and version-based migrations
+   * for the mod. Also manages displaying a "new version" message to players and
+   * executing registered migration routines when an update occurs.
+   *
+   * **Key Responsibilities:**
+   * - Track and store the current mod version in persistent player storage.
+   * - Detect if the mod has been updated since the last session.
+   * - Run version-specific migrations via registered `BaseMigrator` instances.
+   * - Optionally display a message to the user upon detecting a new version.
+   */
   export class VersionModule extends BaseModule {
+      /** Whether the current session is running a new version compared to stored data */
       private static isItNewVersion;
+      /** The current mod version (retrieved from `ModSdkManager.ModInfo.version`) */
       static Version: string;
+      /** Message to display when a new version is detected */
       static NewVersionMessage: string;
+      /** List of registered migration handlers, sorted by version */
       private static Migrators;
+      /**
+       * Initializes the module on load:
+       * - Stores the current mod version.
+       * - Hooks into `ChatRoomSync` to show a "new version" message when applicable.
+       */
       load(): void;
+      /**
+       * Checks if the stored version differs from the current version.
+       * If a new version is detected:
+       * - Flags the session as updated.
+       * - Runs applicable migrations.
+       * - Updates stored version in player data.
+       * - Saves `modStorage`.
+       */
       static checkVersionUpdate(): void;
+      /**
+       * Executes migrations for all registered migrators whose `MigrationVersion`
+       * is newer than the previously stored version.
+       */
       private static checkVersionMigration;
+      /**
+       * Registers a new migrator for handling version-specific changes.
+       * Migrators are sorted by their `MigrationVersion` in ascending order.
+       */
       static registerMigrator(migrator: BaseMigrator): void;
+      /** Sets the message that will be displayed when a new version is detected. */
       static setNewVersionMessage(newVersionMessage: string): void;
+      /** Sends the currently configured "new version" message to the local player. */
       static sendNewVersionMessage(): void;
+      /**
+       * Determines if a given `candidate` version is newer than the `current` version.
+       *
+       * Version strings are expected in `MAJOR.MINOR.PATCH` format.
+       */
       private static isNewVersion;
+      /** Saves the current mod version into persistent player storage. */
       private static saveVersion;
+      /** Loads the stored mod version from persistent player storage. */
       private static loadVersion;
   }
 
@@ -238,23 +620,47 @@ declare module 'bc-deeplib/screens/debug' {
 }
 declare module 'bc-deeplib/screens/import_export' {
   import { BaseSubscreen } from 'bc-deeplib/deeplib';
+  /**
+   * Configuration options for the {@link GuiImportExport} class.
+   */
   export type ImportExportOptions = {
+      /**
+       * A custom save file extension (e.g., ".mydata").
+       * If it doesn't start with a dot, it will be automatically prefixed.
+       */
       customFileExtension: string;
+      /** Optional callback invoked after data has been successfully imported. */
       onImport?: () => void;
+      /** Optional callback invoked after data has been successfully exported. */
       onExport?: () => void;
   };
+  /**
+   * Possible data transfer methods for import/export operations.
+   * - `clipboard`: Uses the system clipboard.
+   * - `file`: Uses file save/load dialogs.
+   */
   type DataTransferMethod = 'clipboard' | 'file';
+  /**
+   * GUI screen for importing and exporting mod data.
+   * Provides buttons to import/export data either via file or clipboard.
+   */
   export class GuiImportExport extends BaseSubscreen {
       private importExportOptions;
       get name(): string;
       constructor(importExportOptions: ImportExportOptions);
       load(): void;
       resize(): void;
+      /** Exports the mod data using the specified method. */
       dataExport(transferMethod: DataTransferMethod): Promise<void>;
+      /** Imports mod data using the specified method. */
       dataImport(transferMethod: DataTransferMethod): Promise<void>;
+      /** Saves data to a file using the browser's save dialog. */
       exportToFile(data: string, defaultFileName: string): Promise<void>;
+      /** Opens a file picker and reads the selected file's contents, importing the data. */
       importFromFile(): Promise<string | null>;
+      /** Copies the given data to the clipboard. */
       exportToClipboard(data: string): Promise<void>;
+      /** Prompts the user to enter data and returns it. */
       importFromClipboard(): Promise<string | null>;
   }
   export {};
@@ -263,10 +669,30 @@ declare module 'bc-deeplib/screens/import_export' {
 declare module 'bc-deeplib/screens/main_menu' {
   import { BaseSubscreen, GUI } from 'bc-deeplib/deeplib';
   import { GuiImportExport } from 'bc-deeplib/screens/import_export';
+  /**
+   * Configuration options for the main menu.
+   *
+   * If these are defined, new button for each option will be added to the main menu.
+   */
   export type MainMenuOptions = {
+      /**
+       * Optional URL to the project's repository.
+       * Example: "https://github.com/user/project"
+       */
       repoLink?: string;
+      /**
+       * Optional URL to the project's wiki or documentation.
+       * Example: "https://github.com/user/project/wiki"
+       */
       wikiLink?: string;
+      /**
+       * Optional subscreen to use for the "reset" action.
+       */
       resetSubscreen?: BaseSubscreen;
+      /**
+       * Optional subscreen for import/export functionality.
+       * Provides tools to import or export data to or from the mod.
+       */
       importExportSubscreen?: GuiImportExport;
   };
   export class MainMenu extends BaseSubscreen {
@@ -284,18 +710,52 @@ declare module 'bc-deeplib/screens/main_menu' {
 
 }
 declare module 'bc-deeplib/utilities/common' {
+  /**
+   * Deeply merges properties from `source` into `target`.
+   * - If both target and source properties are arrays, concatenates them.
+   * - If both are objects, recursively merges them.
+   * - Otherwise, source overwrites target.
+   */
   export function deepMerge(target: any, source: any): any;
+  /**
+   * Returns a new array with elements of the input array shuffled.
+   * Uses something-something shuffle algorithm by splicing from a cloned array.
+   */
   export function shuffleArray(array: string[]): string[];
+  /**
+   * Exports a value to the global object under a nested namespace path.
+   * Creates intermediate objects if they do not exist.
+   *
+   * Example: `exportToGlobal('MyMod.Utils', value)` creates `globalThis.MyMod.Utils = value`.
+   */
   export function exportToGlobal(name: string, value: any): void;
+  /**
+   * Deeply merges only matching properties from `mergeFrom` into `mergeTo`.
+   * Properties not present in `mergeTo` are ignored.
+   * Objects are recursively merged, primitive properties overwritten.
+   */
   export function deepMergeMatchingProperties<T extends object>(mergeTo: T, mergeFrom: T): T;
+  /** Checks if the given property has a getter defined on the object or its prototype chain. */
   export function hasGetter<T extends object>(obj: T, prop: keyof T | string): boolean;
+  /** Checks if the given property has a setter defined on the object or its prototype chain. */
   export function hasSetter<T extends object>(obj: T, prop: keyof T | string): boolean;
 
 }
 declare module 'bc-deeplib/utilities/data' {
   import { SettingsModel } from 'bc-deeplib/deeplib';
+  /**
+   * ModStorage is a singleton class responsible for managing
+   * mod-specific persistent storage both in player settings
+   * and in browser localStorage.
+   *
+   * It provides methods to load and save mod data compressed
+   * as base64 strings, and exposes typed accessors for
+   * playerStorage and extensionStorage.
+   */
   export class ModStorage<T extends SettingsModel = SettingsModel> {
+      /** Singleton instance of ModStorage */
       private static _instance;
+      /** The unique mod identifier used as key prefix in storage */
       private modName;
       constructor(modName: string);
       get playerStorage(): T;
@@ -311,9 +771,13 @@ declare module 'bc-deeplib/utilities/data' {
   }
 
 }
-declare module 'bc-deeplib/utilities/elements/advanced_elements' {
+declare module 'bc-deeplib/utilities/elements/elements' {
   import { Button, Checkbox, Custom, Input, Label } from 'bc-deeplib/base/elements_typings';
-  export const advancedElement: {
+  /**
+   * Collection of element creation utilities.
+   * Provides convenience wrappers for generating commonly used UI elements.
+   */
+  export const advElement: {
       createButton: typeof elementCreateButton;
       createCheckbox: typeof elementCreateCheckbox;
       createInput: typeof elementCreateInput;
@@ -347,57 +811,123 @@ declare module 'bc-deeplib/utilities/elements/advanced_elements' {
   }
   function elementPrevNext(options: PrevNext): HTMLElement;
   export type ModalButton<T extends string = string> = {
+      /** Button label text. */
       text: string;
+      /** Action identifier returned when the button is clicked. */
       action: T;
+      /** Whether the button is disabled. */
       disabled?: boolean;
   };
   export type ModalInputOptions = {
+      /** Default input value. */
       defaultValue?: string;
+      /** Makes the input read-only if true. */
       readOnly?: boolean;
+      /** Placeholder text. */
       placeholder?: string;
+      /** Input type. */
       type: 'input' | 'textarea';
+      /** Validation callback to check if the input value is valid. */
       validate?: (value: string) => string | null;
   };
   export type ModalOptions<T extends string = string> = {
+      /** Content or DOM node displayed in the modal header. */
       prompt: string | Node;
+      /** Optional input configuration. */
       input?: ModalInputOptions;
+      /** Buttons to display in the modal. */
       buttons?: ModalButton<T>[];
-      custom?: readonly (string | Node | HTMLOptions<keyof HTMLElementTagNameMap> | null | undefined)[] | undefined;
+      /** Whether clicking backdrop closes the modal (default: true). */
       closeOnBackdrop?: boolean;
+      /** Auto-close timeout in milliseconds. */
       timeoutMs?: number;
   };
+  /**
+   * Modal dialog implementation with queuing, buttons, optional input, and focus trapping.
+   * Multiple modals are queued to ensure only one is visible at a time.
+   */
   export class Modal<T extends string = string> {
       private opts;
       private dialog;
       private blocker;
       private inputEl?;
       private timeoutId?;
+      /** Static modal queue. */
       private static queue;
+      /** Flag to indicate if a modal is currently being shown. */
       private static processing;
       constructor(opts: ModalOptions<T>);
+      /**
+       * Displays the modal and resolves with the chosen action and input value.
+       */
       show(): Promise<[T, string | null]>;
+      /**
+       * Shows a simple alert modal with a single "OK" button.
+       */
       static alert(msg: string, timeoutMs?: number): Promise<void>;
+      /**
+       * Shows a confirmation modal with "Cancel" and "OK" buttons.
+       * Returns true if "OK" is clicked.
+       */
       static confirm(msg: string): 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: string, defaultValue?: string): Promise<string | null>;
+      /** Creates the input element for the modal, applying configuration and validation. */
       private renderInput;
+      /** Creates modal action buttons from configuration. */
       private renderButtons;
+      /** Creates the modal backdrop blocker with optional click-to-close behavior. */
       private createBlocker;
+      /** Implements a focus trap to keep keyboard navigation inside the modal. */
       private setupFocusTrap;
+      /** Closes the modal, cleans up DOM, resolves promise, and shows next queued modal. */
       private close;
+      /**
+       * An internal function where we will save promise function.
+       */
       private resolve;
+      /** A function that adds a modal to the queue and returns a promise */
       private static enqueue;
+      /** A function that processes the queue, removing the first modal */
       private static dequeue;
   }
   export {};
 
 }
-declare module 'bc-deeplib/utilities/elements/element_helpers' {
+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;
@@ -412,12 +942,12 @@ declare module 'bc-deeplib/utilities/elements/element_helpers' {
   export {};
 
 }
-declare module 'bc-deeplib/utilities/elements/layout_elements' {
-  export const layoutElement: {
-      createSubscreenDiv: typeof elementCreateSubscreenDiv;
-      getSubscreenDiv: typeof elementGetSubscreenDiv;
-      appendToSubscreenDiv: typeof elementAppendToSubscreenDiv;
-      removeSubscreenDiv: typeof elementRemoveSubscreenDiv;
+declare module 'bc-deeplib/utilities/elements/layout' {
+  export const layout: {
+      createSubscreen: typeof elementCreateSubscreenDiv;
+      getSubscreen: typeof elementGetSubscreenDiv;
+      appendToSubscreen: typeof elementAppendToSubscreenDiv;
+      removeSubscreen: typeof elementRemoveSubscreenDiv;
       createSettingsDiv: typeof elementCreateSettingsDiv;
       getSettingsDiv: typeof elementGetSettingsDiv;
       appendToSettingsDiv: typeof elementAppendToSettingsDiv;
@@ -470,6 +1000,10 @@ declare module 'bc-deeplib/utilities/messages' {
 
 }
 declare module 'bc-deeplib/utilities/sdk' {
+  /**
+   * Defines priority levels for hooking functions.
+   * Hooks with higher priority are called first in hook chain.
+   */
   export const HookPriority: {
       Observe: number;
       AddBehavior: number;
@@ -477,7 +1011,12 @@ declare module 'bc-deeplib/utilities/sdk' {
       OverrideBehavior: number;
       Top: number;
   };
+  /** Type alias representing module of hook? */
   export type ModuleCategory = number | string;
+  /**
+   * Interface representing data about a patched function,
+   * including the function name and all hooks applied to it.
+   */
   interface IPatchedFunctionData {
       name: string;
       hooks: {
@@ -487,16 +1026,41 @@ declare module 'bc-deeplib/utilities/sdk' {
           removeCallback: () => void;
       }[];
   }
+  /**
+   * Manager class for mod SDK integration,
+   * provides methods to register mods, hook functions, and manage patches.
+   */
   export class ModSdkManager {
       private static SDK;
       private static patchedFunctions;
       static ModInfo: ModSDKModInfo;
+      /** 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. */
       initPatchableFunction(target: string): IPatchedFunctionData;
+      /**
+       * Hooks a function with a callback at a given priority.
+       *
+       * Prevents duplicate hooks.
+       */
       hookFunction<TargetName extends string>(target: TargetName, priority: number, hook: PatchHook<GetDotedPathType<typeof globalThis, TargetName>>, module?: ModuleCategory | null): () => void;
+      /**
+       * Applies patches to a target function.
+       *
+       * **This method is DANGEROUS** to use and has high potential to conflict with other mods.
+       */
       patchFunction(target: string, patches: Record<string, string>): void;
+      /**
+       * Removes all patches from a target function.
+       */
       unpatchFunction(target: string): void;
+      /**
+       * Removes all hooks associated with a specific module from a target function.
+       */
       removeHookByModule(target: string, module: ModuleCategory): boolean;
+      /**
+       * Removes all hooks associated with a specific module across all patched functions.
+       */
       removeAllHooksByModule(module: ModuleCategory): boolean;
   }
   export {};
@@ -504,32 +1068,79 @@ declare module 'bc-deeplib/utilities/sdk' {
 }
 declare module 'bc-deeplib/utilities/style' {
   export const Style: {
+      /**
+       * Injects a CSS style block directly into the document head using a <style> tag.
+       * If a style element with the same `styleId` already exists, it won't inject again.
+       */
       injectInline(styleId: string, styleSource: string): void;
+      /**
+       * Injects a CSS stylesheet link into the document head using a <link> tag.
+       * If a link element with the same `styleId` already exists, it won't inject again.
+       */
       injectEmbed(styleId: string, styleLink: string): void;
+      /**
+       * Removes a style element from the document head by its ID.
+       * Does nothing if the element is not found.
+       */
       eject(id: string): void;
+      /**
+       * Reloads an inline style by removing the existing style element (if any)
+       * and injecting the new styles inline again.
+       */
       reload(styleId: string, styleSource: string): void;
+      /** Fetches the text content of a stylesheet or any resource at the given link. */
       fetch(link: string): Promise<string>;
   };
 
 }
 declare module 'bc-deeplib/utilities/translation' {
-  interface InitOptions {
-      pathToTranslationsFolder: string;
+  /**
+   * Options for initializing the Localization system.
+   */
+  export interface TranslationOptions {
+      /** The path to the folder where the translations are stored. */
+      pathToTranslationsFolder?: string;
+      /** The default language to use. */
+      defaultLanguage?: string;
+      /** If true, the localization will be fixed to the default language, ignoring user language settings. */
+      fixedLanguage?: boolean;
   }
+  /**
+   * Localization class handles loading and retrieving translation strings
+   * from library and mod-specific language files.
+   */
   export class Localization {
       private static LibTranslation;
       private static ModTranslation;
       private static PathToModTranslation;
       private static PathToLibTranslation;
+      private static DefaultLanguage;
+      /** Flag to prevent re-initialization */
       private static initialized;
-      static init(initOptions: InitOptions): Promise<void>;
+      /** Initialize the localization system by loading translation files. */
+      static init(initOptions?: TranslationOptions): Promise<void>;
+      /** Get a translated string from mod translations by source tag. */
       static getTextMod(srcTag: string): string | undefined;
+      /** Get a translated string from library translations by source tag. */
       static getTextLib(srcTag: string): string | undefined;
+      /**
+       * Fetch and parse a language file from the given base URL and language code.
+       * Falls back to default language if the requested language file is unavailable.
+       */
       private static fetchLanguageFile;
+      /**
+       * Parse the raw content of a language file into a TranslationDict.
+       * Ignores empty lines and comments starting with '#'.
+       */
       private static parseLanguageFile;
   }
+  /**
+   * Retrieve a localized string for the given source tag.
+   * First attempts to get the mod-specific translation,
+   * then falls back to the library translation,
+   * and if neither exist, returns the source tag itself.
+   */
   export const getText: (srcTag: string) => string;
-  export {};
 
 }
 declare module 'bc-deeplib' {