### Target Selection API

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

Provides an interactive targeting interface for spells and abilities that require target selection. It allows checking targeting needs, starting the selection process, and displaying range indicators.

```APIDOC
## Target Selection API

### Description
The target selector provides an interactive targeting interface for spells and abilities that require target selection. It facilitates checking if targeting is needed, initiating the selection process, and managing visual range indicators.

### Method
`api.needsTargeting(item, activity)`
`api.startTargetSelection(options)`
`api.showRangeIndicator(options)`
`api.hideRangeIndicator()`

### Endpoint
N/A (Methods on API object)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
// Start target selection for an item
const api = ui.BG3HOTBAR.api;

// Check if item needs targeting
if (api.needsTargeting(item, activity)) {
    // Start interactive target selection
    const targets = await api.startTargetSelection({
        token: canvas.tokens.controlled[0],
        item: item,
        activity: activity // optional for multi-activity items
    });

    if (targets.length > 0) {
        // Proceed with item use
        await item.use({ targets });
    }
}

// Show range indicator without activating full selector
api.showRangeIndicator({
    token: sourceToken,
    item: spell,
    activity: null
});

// Hide range indicator
api.hideRangeIndicator();

// Adapter targeting rules implementation
const adapter = {
    targetingRules: {
        needsTargeting({ item, activity }) {
            const target = activity?.target || item.system.target;
            return target?.type === 'creature' || target?.type === 'enemy';
        },

        getTargetRequirements({ item, activity }) {
            return {
                minTargets: 1,
                maxTargets: activity?.target?.count || 1,
                range: item.system.range?.value || null,
                targetType: 'creature', // 'creature', 'ally', 'enemy', 'self', 'any'
                hasTemplate: item.system.target?.type === 'cone'
            };
        },

        calculateRange({ item, activity, actor }) {
            return {
                range: item.system.range?.value || 0,
                unit: 'ft'
            };
        },

        isValidTargetType({ sourceToken, targetToken, requirements }) {
            if (requirements.targetType === 'enemy') {
                const isEnemy = sourceToken.document.disposition !== targetToken.document.disposition;
                return { valid: isEnemy, reason: isEnemy ? null : 'Target must be an enemy' };
            }
            return { valid: true, reason: null };
        }
    }
};
```

### Response
#### Success Response (200)
- **targets** (Array<Token>) - A list of selected target tokens.

#### Response Example
```json
{
  "example": "[selected token objects]"
}
```
```

--------------------------------

### Target Selection API for Spells and Abilities (JavaScript)

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

This section covers the Target Selection API, which provides an interactive targeting interface for spells and abilities. It includes functions to start target selection, show/hide range indicators, and implement custom targeting rules via an adapter.

```javascript
// Start target selection for an item
const api = ui.BG3HOTBAR.api;

// Check if item needs targeting
if (api.needsTargeting(item, activity)) {
    // Start interactive target selection
    const targets = await api.startTargetSelection({
        token: canvas.tokens.controlled[0],
        item: item,
        activity: activity // optional for multi-activity items
    });

    if (targets.length > 0) {
        // Proceed with item use
        await item.use({ targets });
    }
}

// Show range indicator without activating full selector
api.showRangeIndicator({
    token: sourceToken,
    item: spell,
    activity: null
});

// Hide range indicator
api.hideRangeIndicator();

// Adapter targeting rules implementation
const adapter = {
    targetingRules: {
        needsTargeting({ item, activity }) {
            const target = activity?.target || item.system.target;
            return target?.type === 'creature' || target?.type === 'enemy';
        },

        getTargetRequirements({ item, activity }) {
            return {
                minTargets: 1,
                maxTargets: activity?.target?.count || 1,
                range: item.system.range?.value || null,
                targetType: 'creature', // 'creature', 'ally', 'enemy', 'self', 'any'
                hasTemplate: item.system.target?.type === 'cone'
            };
        },

        calculateRange({ item, activity, actor }) {
            return {
                range: item.system.range?.value || 0,
                unit: 'ft'
            };
        },

        isValidTargetType({ sourceToken, targetToken, requirements }) {
            if (requirements.targetType === 'enemy') {
                const isEnemy = sourceToken.document.disposition !== targetToken.document.disposition;
                return { valid: isEnemy, reason: isEnemy ? null : 'Target must be an enemy' };
            }
            return { valid: true, reason: null };
        }
    }
};
```

--------------------------------

### Registering a System Adapter

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

This section explains how system adapters can register themselves with the core BG3 HUD module. It covers the necessary hooks, methods to implement within the adapter, and how to register custom tooltip renderers.

```APIDOC
## Registering a System Adapter

System adapters must register with the core module to provide system-specific functionality. The adapter should implement required methods for item transformation, click handling, and tooltip rendering.

### Method
`Hooks.on('bg3HudReady', (api) => { ... });`

### Parameters
#### `api` Object
- **`registerAdapter(adapter, options)`** (Function) - Registers a system adapter.
  - `adapter` (Object) - An instance of your system adapter class.
  - `options` (Object) - Optional configuration for the adapter.
    - **`tooltipClassBlacklist`** (Array<string>) - Optional. A list of CSS classes to exclude from tooltips.
- **`registerTooltipRenderer(systemId, rendererFunction)`** (Function) - Registers a custom tooltip renderer.
  - `systemId` (string) - The unique identifier for your system.
  - `rendererFunction` (Function) - An async function that returns tooltip content, classes, and direction.

### Request Example (Adapter Registration)
```javascript
// In your adapter module's ready hook
Hooks.on('bg3HudReady', (api) => {
    // Create your adapter instance
    const adapter = new MySystemAdapter();

    // Register the adapter with required properties
    api.registerAdapter(adapter, {
        tooltipClassBlacklist: ['my-system-tooltip-class']
    });

    // Register system-specific tooltip renderer
    api.registerTooltipRenderer('my-system-id', async (item, options) => {
        const html = await renderTemplate('modules/my-adapter/templates/tooltip.hbs', {
            item: item,
            name: item.name,
            description: item.system.description
        });
        return {
            content: html,
            classes: ['my-system-tooltip'],
            direction: 'UP'
        };
    });

    // Signal that registration is complete
    Hooks.callAll('bg3HudRegistrationComplete');
});

// Adapter class implementation
class MySystemAdapter {
    MODULE_ID = 'bg3-hud-mysystem';
    systemId = 'mysystem';

    // Transform item data for hotbar cell display
    async transformItemToCellData(item) {
        return {
            uuid: item.uuid,
            name: item.name,
            img: item.img,
            type: item.type,
            quantity: item.system.quantity || null,
            uses: item.system.uses?.value || null,
            usesMax: item.system.uses?.max || null
        };
    }

    // Handle item click/use
    async handleItemUse(item, options = {}) {
        return item.use(options);
    }

    // Get display settings for hotbar
    getDisplaySettings() {
        return {
            showItemNames: game.settings.get(this.MODULE_ID, 'showItemNames'),
            showItemUses: game.settings.get(this.MODULE_ID, 'showItemUses')
        };
    }
}
```

### Response
No direct response, but registration is confirmed by subsequent module functionality and potentially `bg3HudRegistrationComplete` hook.
```

--------------------------------

### Register System Adapter and Tooltip Renderer - JavaScript

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

This snippet demonstrates how to register a system adapter with the BG3 Inspired HUD Core module. It includes implementing required methods for item transformation, click handling, and tooltip rendering, along with registering a custom tooltip renderer.

```javascript
Hooks.on('bg3HudReady', (api) => {
    // Create your adapter instance
    const adapter = new MySystemAdapter();

    // Register the adapter with required properties
    api.registerAdapter(adapter, {
        tooltipClassBlacklist: ['my-system-tooltip-class']
    });

    // Register system-specific tooltip renderer
    api.registerTooltipRenderer('my-system-id', async (item, options) => {
        const html = await renderTemplate('modules/my-adapter/templates/tooltip.hbs', {
            item: item,
            name: item.name,
            description: item.system.description
        });
        return {
            content: html,
            classes: ['my-system-tooltip'],
            direction: 'UP'
        };
    });

    // Signal that registration is complete
    Hooks.callAll('bg3HudRegistrationComplete');
});

// Adapter class implementation
class MySystemAdapter {
    MODULE_ID = 'bg3-hud-mysystem';
    systemId = 'mysystem';

    // Transform item data for hotbar cell display
    async transformItemToCellData(item) {
        return {
            uuid: item.uuid,
            name: item.name,
            img: item.img,
            type: item.type,
            quantity: item.system.quantity || null,
            uses: item.system.uses?.value || null,
            usesMax: item.system.uses?.max || null
        };
    }

    // Handle item click/use
    async handleItemUse(item, options = {}) {
        return item.use(options);
    }

    // Get display settings for hotbar
    getDisplaySettings() {
        return {
            showItemNames: game.settings.get(this.MODULE_ID, 'showItemNames'),
            showItemUses: game.settings.get(this.MODULE_ID, 'showItemUses')
        };
    }
}
```

--------------------------------

### Creating Settings Submenus (JavaScript)

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

This code demonstrates how to use the `createSettingsSubmenu` factory to generate organized settings dialogs. It allows for defining sections with toggles and action buttons, and then registering these menus with the game's settings system.

```javascript
import { createSettingsSubmenu } from './api/SettingsSubmenu.js';

// Create a settings submenu class
const MySettingsMenu = createSettingsSubmenu({
    moduleId: 'my-module-id',
    titleKey: 'my-module.Settings.MenuTitle',
    sections: [
        {
            legend: 'my-module.Settings.DisplaySection',
            keys: ['showNames', 'showUses', 'showQuantity']
        },
        {
            legend: 'my-module.Settings.BehaviorSection',
            keys: ['autoPopulate', 'confirmDelete'],
            buttons: [
                {
                    id: 'openConfig',
                    name: 'my-module.Settings.ConfigButton.Name',
                    label: 'my-module.Settings.ConfigButton.Label',
                    icon: 'fas fa-cog',
                    hint: 'my-module.Settings.ConfigButton.Hint',
                    onClick: () => new MyConfigDialog().render(true)
                }
            ]
        }
    ]
});

// Register the menu
game.settings.registerMenu('my-module-id', 'mySettingsMenu', {
    name: 'my-module.Settings.Name',
    label: 'my-module.Settings.Label',
    hint: 'my-module.Settings.Hint',
    icon: 'fas fa-sliders-h',
    type: MySettingsMenu,
    restricted: false
});
```

--------------------------------

### Manage Tooltips with TooltipManager (JavaScript)

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

Illustrates the usage of the `TooltipManager` for displaying simple and rich tooltips, including pin/unpin functionality. It covers showing, hiding, pinning, and dismissing tooltips, as well as registering custom renderers for specific game systems like PF2e. This requires access to `ui.BG3HOTBAR.tooltipManager`.

```javascript
// Access tooltip manager
const tooltipManager = ui.BG3HOTBAR.tooltipManager;

// Show simple tooltip
tooltipManager.showSimpleTooltip(
    targetElement,           // HTMLElement to anchor tooltip to
    '<b>Tooltip</b> content', // HTML content
    'UP',                    // Direction: 'UP', 'DOWN', 'LEFT', 'RIGHT'
    ['my-tooltip-class'],    // Additional CSS classes
    'unique-id'              // Optional UUID for tracking pinned tooltips
);

// Show rich tooltip (uses registered renderer)
await tooltipManager.showRichTooltip(
    targetElement,
    item,                    // Item document to render
    'dnd5e',                 // System ID for renderer lookup
    { showDescription: true }, // Renderer options
    item.uuid                // UUID for tracking
);

// Hide tooltip
tooltipManager.hideTooltip();

// Pin current tooltip (makes it draggable)
tooltipManager.pinTooltip();

// Dismiss a locked/pinned tooltip
tooltipManager.dismissLockedTooltip(tooltipElement);

// Register custom tooltip renderer for a system
tooltipManager.registerRenderer('pf2e', async (item, options) => {
    const template = await renderTemplate('modules/bg3-hud-pf2e/templates/tooltip.hbs', {
        item: item,
        traits: item.system.traits?.value || [],
        actions: item.system.actions
    });

    return {
        content: template,
        classes: ['pf2e-tooltip', 'bg3-rich-tooltip'],
        direction: 'UP'
    };
});
```

--------------------------------

### Registering Menu Builders

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

Allows for the registration of custom menu builders to provide system-specific context menus for hotbar cells. This enables dynamic context-sensitive options for items.

```APIDOC
## Registering Menu Builders

### Description
Menu builders provide system-specific context menus for hotbar cells. This allows for dynamic and context-sensitive options to be displayed when interacting with hotbar items.

### Method
`Hooks.on('bg3HudReady', (api) => { ... });`

### Endpoint
N/A (Event Listener)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
Hooks.on('bg3HudReady', (api) => {
    api.registerMenuBuilder('dnd5e', DnD5eMenuBuilder, { adapter: myAdapter });
});

// Menu builder implementation
class DnD5eMenuBuilder extends MenuBuilder {
    buildCellMenu(cell, item) {
        return [
            {
                label: 'Use Item',
                icon: 'fas fa-hand-pointer',
                callback: () => this.adapter.handleItemUse(item)
            },
            {
                label: 'Edit Item',
                icon: 'fas fa-edit',
                callback: () => item.sheet.render(true)
            },
            {
                label: 'Remove from Hotbar',
                icon: 'fas fa-trash',
                callback: () => cell.clearItem()
            }
        ];
    }
}
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Display Standardized Dialogs with Foundry's DialogV2 (JavaScript)

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

Provides utility functions for showing standardized dialogs using Foundry's DialogV2. These functions simplify the creation of selection dialogs, pill selection dialogs, configuration dialogs, and view creation dialogs. They handle input validation and return structured data based on user selections.

```javascript
import {
    showSelectionDialog,
    showPillSelectionDialog,
    showAutoPopulateConfigDialog,
    showViewDialog,
    showButtonChoiceDialog
} from './utils/dialogs.js';

// Selection dialog with checkboxes
const selectedIds = await showSelectionDialog({
    title: 'Select Spells',
    description: 'Choose which spells to display on the hotbar',
    items: [
        { id: 'spell1', label: 'Fireball', img: 'icons/magic/fire/beam.webp', selected: false },
        { id: 'spell2', label: 'Magic Missile', img: 'icons/magic/light/beam.webp', selected: true },
        { id: 'spell3', label: 'Shield', img: 'icons/magic/defense/shield.webp', selected: false }
    ],
    maxSelections: 5,
    footerToggles: [
        { key: 'includeCantrips', label: 'Include Cantrips', checked: true }
    ]
});
// Returns: { selectedIds: ['spell1', 'spell3'], toggles: { includeCantrips: true } }

// Pill selection dialog with toggleable buttons
const selectedTypes = await showPillSelectionDialog({
    title: 'Select Item Types',
    description: 'Choose item types to auto-populate',
    choices: [
        { group: 'Weapons', choices: [
            { value: 'melee', label: 'Melee' },
            { value: 'ranged', label: 'Ranged' }
        ]},
        { group: 'Magic', choices: [
            { value: 'spell', label: 'Spells' },
            { value: 'scroll', label: 'Scrolls' }
        ]}
    ]
});
// Returns: ['melee', 'spell']

// Auto-populate configuration dialog
const config = await showAutoPopulateConfigDialog({
    title: 'Configure Auto-Populate',
    description: 'Assign item types to hotbar grids',
    choices: [
        { value: 'weapon', label: 'Weapons' },
        { value: 'spell', label: 'Spells' },
        { value: 'consumable', label: 'Consumables' }
    ],
    configuration: {
        grid0: ['weapon'],
        grid1: ['spell'],
        grid2: [],
        options: { excludeEquipped: false }
    },
    toggleOptions: [
        { key: 'excludeEquipped', label: 'Exclude Equipped Items', hint: 'Skip items already equipped' }
    ]
});
// Returns: { grid0: ['weapon'], grid1: ['spell', 'consumable'], grid2: [], options: { excludeEquipped: true } }

// View creation dialog
const viewData = await showViewDialog({
    title: 'Create New View',
    buttonLabel: 'Create',
    name: 'Combat Spells',
    icon: 'fa-wand-magic'
});
// Returns: { name: 'Combat Spells', icon: 'fa-wand-magic' }

```

--------------------------------

### Extend BG3Component for Custom UI Elements (JavaScript)

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

Demonstrates how to create a custom UI component by extending the base BG3Component class. This involves overriding lifecycle methods like `render` and `destroy` for custom element creation, content rendering, event handling, and cleanup. It assumes the existence of `BG3Component` and related utility functions.

```javascript
import { BG3Component } from './components/BG3Component.js';

class MyCustomContainer extends BG3Component {
    constructor(options = {}) {
        super(options);
        this.actor = options.actor;
        this.token = options.token;
    }

    async render() {
        // Create element on first render
        if (!this.element) {
            this.element = this.createElement('div', ['my-custom-container']);
        }

        // Update content
        this.element.innerHTML = `
            <div class="header">${this.actor.name}</div>
            <div class="content">
                ${this._renderContent()}
            </div>
        `;

        // Add event listeners (tracked for cleanup)
        const button = this.element.querySelector('.action-button');
        if (button) {
            this.addEventListener(button, 'click', this._handleClick.bind(this));
        }

        return this.element;
    }

    _renderContent() {
        return this.actor.items
            .filter(i => i.type === 'spell')
            .map(spell => `<div class="spell">${spell.name}</div>`)
            .join('');
    }

    _handleClick(event) {
        // Handle click
    }

    destroy() {
        // Custom cleanup before calling parent
        this._customCleanup();
        super.destroy(); // Removes all event listeners and DOM element
    }
}
```

--------------------------------

### Registering Container Components

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

This section details how system adapters can register custom container components to extend or replace core UI elements like portraits, filters, action buttons, and weapon sets.

```APIDOC
## Registering Container Components

System adapters can register custom container components to extend or replace core containers like portraits, filters, and action buttons.

### Method
`Hooks.on('bg3HudReady', (api) => { ... });`

### Parameters
#### `api` Object
- **`registerPortraitContainer(ContainerClass)`** (Function) - Registers a custom portrait container.
- **`registerFilterContainer(ContainerClass)`** (Function) - Registers a custom filter container.
- **`registerActionButtonsContainer(ContainerClass)`** (Function) - Registers a custom action buttons container.
- **`registerWeaponSetContainer(ContainerClass)`** (Function) - Registers a custom weapon set container.
- **`registerInfoContainer(ContainerClass)`** (Function) - Registers a custom info container.
- **`registerContainer(name, ContainerClass)`** (Function) - Registers an additional named container.
  - `name` (string) - The unique name for the container.
  - `ContainerClass` (Class) - The class definition for your custom container.

### Request Example (Custom Filter Container Registration)
```javascript
Hooks.on('bg3HudReady', (api) => {
    // Register custom portrait container
    api.registerPortraitContainer(MyCustomPortraitContainer);

    // Register custom filter container
    api.registerFilterContainer(MySystemFilterContainer);

    // Register custom action buttons container
    api.registerActionButtonsContainer(MyActionButtonsContainer);

    // Register custom weapon set container
    api.registerWeaponSetContainer(MyWeaponSetContainer);

    // Register custom info container
    api.registerInfoContainer(MyInfoContainer);

    // Register additional named containers
    api.registerContainer('situationalBonuses', MySituationalBonusesContainer);
    api.registerContainer('cprGenericActions', MyCPRActionsContainer);
});

// Example custom filter container
class MySystemFilterContainer extends FilterContainer {
    getFilters() {
        return [
            {
                id: 'spells',
                icon: 'fas fa-wand-magic',
                label: 'Spells',
                filter: (item) => item.type === 'spell',
                alwaysShow: true
            },
            {
                id: 'items',
                icon: 'fas fa-box',
                label: 'Items',
                filter: (item) => item.type === 'item'
            },
            {
                type: 'group',
                id: 'actions',
                icon: 'fas fa-hand-fist',
                label: 'Actions',
                children: [
                    { id: 'attack', label: 'Attacks', filter: (item) => item.system.actionType === 'attack' },
                    { id: 'utility', label: 'Utility', filter: (item) => item.system.actionType === 'utility' }
                ]
            }
        ];
    }
}
```

### Response
No direct response, but registration is confirmed by the appearance and functionality of the registered custom components within the HUD.
```

--------------------------------

### Creating Settings Submenus

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

A factory function to create organized settings dialogs with sections, toggles, and action buttons. This simplifies the creation and registration of complex settings interfaces.

```APIDOC
## Creating Settings Submenus

### Description
The `createSettingsSubmenu` factory creates organized settings dialogs with sections, toggles, and action buttons. This utility simplifies the process of building and registering custom settings menus within the game.

### Method
`createSettingsSubmenu(options)`

### Endpoint
N/A (Factory Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **moduleId** (string) - The unique identifier for the module.
- **titleKey** (string) - The localization key for the menu title.
- **sections** (Array<Object>) - An array of section configurations.
  - **legend** (string) - The localization key for the section header.
  - **keys** (Array<string>) - An array of setting keys belonging to this section.
  - **buttons** (Array<Object>) - Optional array of button configurations for the section.
    - **id** (string) - The unique identifier for the button.
    - **name** (string) - The localization key for the button's name.
    - **label** (string) - The localization key for the button's visible label.
    - **icon** (string) - The CSS class for the button's icon.
    - **hint** (string) - The localization key for the button's tooltip hint.
    - **onClick** (Function) - The callback function to execute when the button is clicked.

### Request Example
```javascript
import { createSettingsSubmenu } from './api/SettingsSubmenu.js';

// Create a settings submenu class
const MySettingsMenu = createSettingsSubmenu({
    moduleId: 'my-module-id',
    titleKey: 'my-module.Settings.MenuTitle',
    sections: [
        {
            legend: 'my-module.Settings.DisplaySection',
            keys: ['showNames', 'showUses', 'showQuantity']
        },
        {
            legend: 'my-module.Settings.BehaviorSection',
            keys: ['autoPopulate', 'confirmDelete'],
            buttons: [
                {
                    id: 'openConfig',
                    name: 'my-module.Settings.ConfigButton.Name',
                    label: 'my-module.Settings.ConfigButton.Label',
                    icon: 'fas fa-cog',
                    hint: 'my-module.Settings.ConfigButton.Hint',
                    onClick: () => new MyConfigDialog().render(true)
                }
            ]
        }
    ]
});

// Register the menu
game.settings.registerMenu('my-module-id', 'mySettingsMenu', {
    name: 'my-module.Settings.Name',
    label: 'my-module.Settings.Label',
    hint: 'my-module.Settings.Hint',
    icon: 'fas fa-sliders-h',
    type: MySettingsMenu,
    restricted: false
});
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Manage HUD State with Persistence Manager API (JavaScript)

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

The Persistence Manager API provides functionalities for loading, saving, and managing HUD state with automatic multi-user synchronization. It allows for granular updates to individual cells, entire containers, and grid configurations, as well as comprehensive view management.

```javascript
// Access persistence manager from hotbar app
const persistence = ui.BG3HUD_APP.persistenceManager;

// Load state for current token
const state = await persistence.loadState();
// Returns: { version: 2, views: {...}, hotbar: {...}, weaponSets: {...}, quickAccess: {...} }

// Update a single cell
await persistence.updateCell({
    container: 'hotbar',      // 'hotbar', 'weaponSet', 'quickAccess', 'containerPopover'
    containerIndex: 0,        // Grid index
    slotKey: '2-1',           // Column-row format
    data: {
        uuid: 'Actor.abc123.Item.def456',
        name: 'Longsword',
        img: 'icons/weapons/swords/sword.webp',
        type: 'weapon'
    }
});

// Update entire container
await persistence.updateContainer('hotbar', 0, {
    '0-0': { uuid: 'item1', name: 'Item 1', img: 'icon1.webp' },
    '1-0': { uuid: 'item2', name: 'Item 2', img: 'icon2.webp' }
});

// Update grid configuration (rows/cols)
await persistence.updateGridConfig(0, { rows: 4, cols: 6 });

// Update all grids rows at once (atomic operation)
await persistence.updateAllGridsRows(1);  // Add one row to all grids
await persistence.updateAllGridsRows(-1); // Remove one row from all grids

// Set active weapon set
await persistence.setActiveWeaponSet(1);

// Clear all items from all containers
await persistence.clearAll();

// Find if UUID exists in HUD (prevents duplicates)
const location = persistence.findUuidInHud('Actor.abc.Item.xyz');
// Returns: { container: 'hotbar', containerIndex: 0, slotKey: '1-2' } or null

// View management
const viewId = await persistence.createView('Combat View', 'fa-sword');
await persistence.switchView(viewId);
await persistence.renameView(viewId, 'Boss Fight', 'fa-dragon');
await persistence.duplicateView(viewId, 'Boss Fight Copy');
await persistence.deleteView(viewId);
const views = persistence.getViews();
const activeView = persistence.getActiveView();

```

--------------------------------

### Customize BG3 HUD Theme with CSS Variables (JavaScript)

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

Shows how to programmatically update and apply theme settings for the BG3 HUD using CSS custom properties. It demonstrates retrieving current settings, updating them via `game.settings.set`, and applying the theme to the DOM using `applyTheme`. The code relies on `game.settings` and an `applyTheme` function from `./utils/settings.js`.

```javascript
import { BASE_THEME, applyTheme } from './utils/settings.js';

// Get current theme settings
const themeGeneral = game.settings.get('bg3-hud-core', 'themeGeneral');
const themeSections = game.settings.get('bg3-hud-core', 'themeSections');

// Update theme programmatically
await game.settings.set('bg3-hud-core', 'themeGeneral', {
    '--bg3-border-color': '#666666',
    '--bg3-background-color': '#1a1a1a',
    '--bg3-text-color': '#ffffff',
    '--bg3-hotbar-cell-size': '55px',
    '--bg3-portrait-size': '200px'
});

// Apply theme to DOM
await applyTheme();

// Available CSS variables (partial list):
const themeVariables = {
    // Core colors
    '--bg3-border-color': '#444444',
    '--bg3-background-color': '#222222',
    '--bg3-text-color': '#dddddd',

    // Hotbar specific
    '--bg3-hotbar-cell-size': '50px',
    '--bg3-hotbar-border-color': 'var(--bg3-border-color)',
    '--bg3-hotbar-background-color': 'var(--bg3-background-color)',

    // Small containers (filters, passives, actives)
    '--bg3-small-container-cell-size': '31px',

    // Weapon sets
    '--bg3-weapon-cell-size': '75px',

    // Portrait
    '--bg3-portrait-size': '175px',

    // Borders and radii
    '--bg3-container-border-size': '2px',
    '--bg3-container-border-radius': '10px',
    '--bg3-cell-border-width': '2px',
    '--bg3-grid-gap': '2px'
};
```

--------------------------------

### Registering Menu Builders for Hotbar Cells (JavaScript)

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

This snippet demonstrates how to register a custom menu builder for specific game systems (e.g., 'dnd5e') to provide context-specific menus for hotbar cells. It requires the `bg3HudReady` hook and a `MenuBuilder` implementation.

```javascript
Hooks.on('bg3HudReady', (api) => {
    api.registerMenuBuilder('dnd5e', DnD5eMenuBuilder, { adapter: myAdapter });
});

// Menu builder implementation
class DnD5eMenuBuilder extends MenuBuilder {
    buildCellMenu(cell, item) {
        return [
            {
                label: 'Use Item',
                icon: 'fas fa-hand-pointer',
                callback: () => this.adapter.handleItemUse(item)
            },
            {
                label: 'Edit Item',
                icon: 'fas fa-edit',
                callback: () => item.sheet.render(true)
            },
            {
                label: 'Remove from Hotbar',
                icon: 'fas fa-trash',
                callback: () => cell.clearItem()
            }
        ];
    }
}
```

--------------------------------

### Register Custom Container Components - JavaScript

Source: https://context7.com/bragginrites/bg3-hud-core/llms.txt

This snippet shows how system adapters can register custom container components to extend or replace core UI elements like portraits, filters, and action buttons within the BG3 Inspired HUD.

```javascript
Hooks.on('bg3HudReady', (api) => {
    // Register custom portrait container
    api.registerPortraitContainer(MyCustomPortraitContainer);

    // Register custom filter container
    api.registerFilterContainer(MySystemFilterContainer);

    // Register custom action buttons container
    api.registerActionButtonsContainer(MyActionButtonsContainer);

    // Register custom weapon set container
    api.registerWeaponSetContainer(MyWeaponSetContainer);

    // Register custom info container
    api.registerInfoContainer(MyInfoContainer);

    // Register additional named containers
    api.registerContainer('situationalBonuses', MySituationalBonusesContainer);
    api.registerContainer('cprGenericActions', MyCPRActionsContainer);
});

// Example custom filter container
class MySystemFilterContainer extends FilterContainer {
    getFilters() {
        return [
            {
                id: 'spells',
                icon: 'fas fa-wand-magic',
                label: 'Spells',
                filter: (item) => item.type === 'spell',
                alwaysShow: true
            },
            {
                id: 'items',
                icon: 'fas fa-box',
                label: 'Items',
                filter: (item) => item.type === 'item'
            },
            {
                type: 'group',
                id: 'actions',
                icon: 'fas fa-hand-fist',
                label: 'Actions',
                children: [
                    { id: 'attack', label: 'Attacks', filter: (item) => item.system.actionType === 'attack' },
                    { id: 'utility', label: 'Utility', filter: (item) => item.system.actionType === 'utility' }
                ]
            }
        ];
    }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.