### Initialize WezTerm Config

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/types.md

Example of a configuration object structure containing common WezTerm settings.

```lua
local config = {
  front_end = 'WebGpu',
  max_fps = 120,
  font = wezterm.font({family = 'JetBrainsMono Nerd Font'}),
  colors = {...},
  keys = {...},
  -- ... more options
}
```

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

### Config:init()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-config-builder.md

Initializes a new ConfigBuilder instance to start accumulating configuration options.

```APIDOC
## Config:init()

### Description
Creates a new ConfigBuilder instance in a clean state, ready to accumulate options from configuration modules.

### Returns
- **ConfigBuilder** - A new instance with an empty options table.

### Example
```lua
local Config = require('config')
local builder = Config:init()
```
```

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

### Initialize All Event Modules

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-events.md

Example of initializing multiple event modules and building the final configuration in the main wezterm.lua file.

```lua
local Config = require('config')

-- Setup all events
require('events.left-status').setup()
require('events.right-status').setup({ date_format = '%a %H:%M:%S' })
require('events.tab-title').setup({
   hide_active_tab_unseen = true,
   unseen_icon = 'numbered_box',
   show_progress = true,
})
require('events.new-tab-button').setup()
require('events.gui-startup').setup()

-- Build and return config
return Config:init()
  :append(require('config.appearance'))
  -- ... more config modules
  .options
```

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

### Initialize ConfigBuilder

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-config-builder.md

Creates a new instance of the ConfigBuilder to start accumulating configuration options.

```lua
local Config = require('config')
local builder = Config:init()
```

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

### Setup New Tab Button

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Registers the new tab button menu. No parameters are required.

```lua
require('events.new-tab-button').setup()
```

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

### Construct FormatItem list

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/types.md

Example of creating a sequence of formatting items for terminal output.

```lua
local format_items = {
  {Text = 'Hello '},
  {Attribute = {Intensity = 'Bold'}},
  {Foreground = {Color = '#89b4fa'}},
  {Text = 'World'},
  'ResetAttributes',
}
```

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

### Implement Event with Validated Options

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-utility-modules.md

Example of using OptsValidator to manage and validate configuration options within a module setup function.

```lua
local wezterm = require('wezterm')
local OptsValidator = require('utils.opts-validator')

local EVENT_OPTS = OptsValidator:new({
  {
    name = 'date_format',
    type = 'string',
    default = '%a %H:%M:%S',
  },
  {
    name = 'show_battery',
    type = 'boolean',
    default = true,
  },
})

local M = {}

---@param opts? {date_format?: string, show_battery?: boolean}
M.setup = function(opts)
  local valid_opts, err = EVENT_OPTS:validate(opts or {})
  
  if err then
    wezterm.log_error(err)
  end

  wezterm.on('update-status', function(window, _pane)
    -- valid_opts is guaranteed to have all required fields with proper types
    local date_str = wezterm.strftime(valid_opts.date_format)
    -- Use valid_opts...
  end)
end

return M
```

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

### Define Opt.boolean type and example

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/types.md

Schema definition for boolean configuration options.

```lua
type Opt.boolean = {
  name: string,
  type: 'boolean',
  default: boolean,
  required?: boolean,
}
```

```lua
{
  name = 'show_battery',
  type = 'boolean',
  default = true,
  required = false,
}
```

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

### Setup Tab Title Formatting

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Registers tab title formatting and custom events for tab management.

```lua
require('events.tab-title').setup(opts?)
```

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

### Install WezTerm Nightly on Windows

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/README.md

Commands for installing the nightly version of WezTerm on Windows.

```sh
scoop bucket add versions
scoop install wezterm-nightly
```

```sh
scoop bucket add k https://github.com/KevinSilvester/scoop-bucket
scoop install k/wezterm-nightly
```

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

### Define Opt.string type and example

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/types.md

Schema definition for string configuration options, supporting optional enum constraints.

```lua
type Opt.string = {
  name: string,
  type: 'string',
  default: string,
  required?: boolean,
  enum?: string[],
}
```

```lua
{
  name = 'theme',
  type = 'string',
  default = 'catppuccin',
  enum = {'catppuccin', 'dracula', 'nord'},
}
```

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

### Setup Tab Title Formatting

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-events.md

Configures advanced tab title rendering with options for unseen output indicators and progress tracking.

```lua
function M.setup(opts?: Event.TabTitleOptionsInput)
  -> void
```

```lua
require('events.tab-title').setup({
  unseen_icon = 'numbered_box',
  hide_active_tab_unseen = true,
  show_progress = true,
})
```

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

### Install WezTerm Stable on Windows

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/README.md

Commands for installing the stable version of WezTerm on Windows using various package managers.

```sh
scoop bucket add extras
scoop install wezterm
```

```sh
scoop bucket add k https://github.com/KevinSilvester/scoop-bucket
scoop install k/wezterm
```

```sh
winget install wez.wezterm
```

```sh
choco install wezterm -y
```

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

### str.starts_with(str, prefix)

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-utility-modules.md

Checks if a string starts with a specified prefix.

```APIDOC
## str.starts_with(str, prefix)

### Description
Checks if the provided string starts with the given prefix.

### Parameters
- **str** (string) - Required - String to check
- **prefix** (string) - Required - Prefix to match

### Returns
- **boolean** - true if str starts with prefix, false otherwise.
```

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

### Define Opt.table type and example

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/types.md

Schema definition for table/array configuration options requiring homogeneous element types.

```lua
type Opt.table = {
  name: string,
  type: 'table',
  table_of: 'string' | 'number' | 'boolean',
  default: table,
  required?: boolean,
}
```

```lua
{
  name = 'allowed_hosts',
  type = 'table',
  table_of = 'string',
  default = {},
}
```

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

### Define Opt.number type and example

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/types.md

Schema definition for numeric configuration options, supporting optional enum constraints.

```lua
type Opt.number = {
  name: string,
  type: 'number',
  default: number,
  required?: boolean,
  enum?: number[],
}
```

```lua
{
  name = 'max_attempts',
  type = 'number',
  default = 3,
  enum = {1, 2, 3, 5, 10},
}
```

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

### Install WezTerm Stable on MacOS

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/README.md

Commands for installing the stable version of WezTerm on MacOS.

```sh
brew install --cask wezterm
```

```sh
sudo port selfupdate
sudo port install wezterm
```

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

### Setup New Tab Button Event

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-events.md

Registers the new-tab-button-click event handler to enable right-click launch options.

```lua
function M.setup()
  -> void
```

```lua
require('events.new-tab-button').setup()
```

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

### Install WezTerm Nightly on MacOS

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/README.md

Commands for installing and upgrading the nightly version of WezTerm on MacOS.

```sh
brew install --cask wezterm@nightly
```

```sh
brew install --cask wezterm@nightly --no-quarantine --greedy-latest
```

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

### Cycle Background Forward

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-backdrops.md

Advance to the next image in the sequence, wrapping around to the start if necessary.

```lua
function BackDrops:cycle_forward(window: Window)
  -> void
```

```lua
local act = wezterm.action
local backdrops = require('utils.backdrops')

{
  key = ',',
  mods = 'ALT',
  action = wezterm.action_callback(function(window, _pane)
    backdrops:cycle_forward(window)
  end),
}
```

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

### Setup Left Status Bar

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-events.md

Registers the update-status event handler for the left status bar to display leader key and key table indicators.

```lua
require('events.left-status').setup()
```

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

### Setup Right Status Bar

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-events.md

Registers the update-status event handler for the right status bar, supporting custom date formatting.

```lua
require('events.right-status').setup({
  date_format = '%Y-%m-%d %H:%M:%S'
})
```

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

### events.gui-startup.setup()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Registers the GUI startup handler to maximize the window.

```APIDOC
## events.gui-startup.setup()

### Description
Registers GUI startup handler to maximize window. No parameters required.
```

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

### Install JetBrainsMono Nerd Font

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/README.md

Commands to install the required font on MacOS and Windows.

```sh
brew install --cask font-jetbrains-mono-nerd-font
```

```sh
scoop bucket add nerd-fonts
scoop install JetBrainsMono-NF
```

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

### tab-title.setup()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-events.md

Configures advanced tab title formatting including icons, progress indicators, and unseen output markers.

```APIDOC
## setup(opts)

### Description
Configures enhanced tab titles with prefix icons, unseen output indicators, and progress tracking.

### Parameters
- **opts** (table) - Optional - Options object
  - **unseen_icon** (string) - Optional - Icon style for unseen output: 'circle', 'numbered_circle', or 'numbered_box'. Default: 'circle'.
  - **hide_active_tab_unseen** (boolean) - Optional - Hide unseen indicator on active tab. Default: true.
  - **show_progress** (boolean) - Optional - Show progress indicators (requires WezTerm 20250209+). Default: true.

### Returns
- **void**
```

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

### Configure WezTerm with Manual GPU Selection

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Use the pick_manual method to specify a preferred backend and device type for WebGpu.

```lua
local gpu_adapters = require('utils.gpu-adapter')

-- Prefer integrated GPU with Vulkan on Linux
local config = {
  front_end = 'WebGpu',
  webgpu_preferred_adapter = gpu_adapters:pick_manual('Vulkan', 'IntegratedGpu'),
}
```

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

### events.new-tab-button.setup()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Registers the new tab button menu.

```APIDOC
## events.new-tab-button.setup()

### Description
Registers the new tab button menu. No parameters required.
```

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

### Initialize BackDrops Module

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-backdrops.md

Import the singleton instance of the BackDrops module.

```lua
local backdrops = require('utils.backdrops')
```

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

### new-tab-button.setup()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-events.md

Registers the new-tab-button-click event handler to provide a right-click menu with launch options on the new tab button.

```APIDOC
## setup()

### Description
Registers the `new-tab-button-click` event handler. Provides a right-click menu on the new tab button showing launch options including DefaultDomain shells, WSL, SSH, and Unix domains.

### Signature
`require('events.new-tab-button').setup()`

### Returns
- **void**
```

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

### Configure WezTerm with Automatic GPU Selection

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Use the pick_best method to set the preferred WebGpu adapter in the WezTerm configuration.

```lua
local gpu_adapters = require('utils.gpu-adapter')

local config = {
  front_end = 'WebGpu',
  webgpu_preferred_adapter = gpu_adapters:pick_best(),
}
```

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

### Import Math Utilities

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Load the math utility module to access clamp and round functions.

```lua
local umath = require('utils.math')
```

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

### Initialize GUI Startup Event

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-events.md

Registers the gui-startup event handler to initialize the window on startup.

```lua
require('events.gui-startup').setup()
```

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

### Configure Launch Settings by Platform

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/configuration.md

Defines the default shell and launch menu items for Windows, macOS, and Linux environments.

```lua
default_prog = { 'pwsh', '-NoLogo' }
launch_menu = {
   { label = 'PowerShell Core', args = { 'pwsh', '-NoLogo' } },
   { label = 'PowerShell Desktop', args = { 'powershell' } },
   { label = 'Command Prompt', args = { 'cmd' } },
   { label = 'Nushell', args = { 'nu' } },
   { label = 'Msys2', args = { 'ucrt64.cmd' } },
   { label = 'Git Bash', args = { 'C:\\Users\\kevin\\scoop\\apps\\git\\current\\bin\\bash.exe' } },
}
```

```lua
default_prog = { '/opt/homebrew/bin/fish', '-l' }
launch_menu = {
   { label = 'Bash', args = { 'bash', '-l' } },
   { label = 'Fish', args = { '/opt/homebrew/bin/fish', '-l' } },
   { label = 'Nushell', args = { '/opt/homebrew/bin/nu', '-l' } },
   { label = 'Zsh', args = { 'zsh', '-l' } },
}
```

```lua
default_prog = { 'fish', '-l' }
launch_menu = {
   { label = 'Bash', args = { 'bash', '-l' } },
   { label = 'Fish', args = { 'fish', '-l' } },
   { label = 'Zsh', args = { 'zsh', '-l' } },
}
```

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

### events.right-status.setup(opts?)

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Registers the right status bar handler with optional date formatting.

```APIDOC
## events.right-status.setup(opts?)

### Description
Registers the right status bar handler.

### Options
- **date_format** (string, optional) - strftime() format string for date display.
```

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

### initial_options(opts)

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-backdrops.md

Generates background layer configuration objects for WezTerm.

```APIDOC
## BackDrops:initial_options(opts)

### Description
Generates an array of BackgroundLayer objects for WezTerm configuration.

### Parameters
- **opts** (table) - Required - Options object.
- **opts.no_img** (boolean) - Optional - If true, returns focus mode options (no background image).
```

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

### Configure WezTerm Window Settings

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/configuration.md

Sets window padding, frame styling, pane brightness, and visual bell behavior.

```lua
window_padding = {
   left = 0,
   right = 0,
   top = 10,
   bottom = 7.5,
}
adjust_window_size_when_changing_font_size = false
window_close_confirmation = 'NeverPrompt'
window_frame = {
   active_titlebar_bg = '#090909',
}
inactive_pane_hsb = {
   saturation = 1,
   brightness = 1,
}
visual_bell = {
   fade_in_function = 'EaseIn',
   fade_in_duration_ms = 250,
   fade_out_function = 'EaseOut',
   fade_out_duration_ms = 250,
   target = 'CursorColor',
}
```

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

### Import ConfigBuilder Module

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Load the ConfigBuilder module to begin composing WezTerm configurations.

```lua
local Config = require('config')
```

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

### Initialize GpuAdapters Module

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Import the singleton instance of the GpuAdapters module.

```lua
local gpu_adapters = require('utils.gpu-adapter')
```

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

### events.left-status.setup()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Registers the left status bar handler.

```APIDOC
## events.left-status.setup()

### Description
Registers the left status bar handler. No parameters required.
```

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

### Import standard configuration and utility modules

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Use these imports to access the configuration builder, utility functions, and event handlers in the main configuration file.

```lua
-- Configuration builder
local Config = require('config')

-- Utilities
local backdrops = require('utils.backdrops')
local gpu_adapters = require('utils.gpu-adapter')
local Cells = require('utils.cells')
local OptsValidator = require('utils.opts-validator')
local platform = require('utils.platform')
local str = require('utils.str')
local umath = require('utils.math')

-- Events
require('events.left-status').setup()
require('events.right-status').setup(opts)

-- Colors
local colors = require('colors.custom')
```

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

### Integrate configuration modules

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-config-builder.md

Initializes the configuration builder and chains multiple modules to construct the final WezTerm configuration object.

```lua
-- wezterm.lua (entry point)

local wezterm = require('wezterm')
local Config = require('config')
local backdrops = require('utils.backdrops')
local platform = require('utils.platform')

-- Setup UI events
require('events.left-status').setup()
require('events.right-status').setup({ date_format = '%a %H:%M:%S' })
require('events.tab-title').setup({
   hide_active_tab_unseen = true,
   unseen_icon = 'numbered_box',
   show_progress = true,
})
require('events.new-tab-button').setup()
require('events.gui-startup').setup()

-- Setup background management
backdrops
   :scan_images_dir()
   :random()

-- Build final configuration
local config = Config:init()
   :append(require('config.appearance'))
   :append(require('config.bindings'))
   :append(require('config.domains'))
   :append(require('config.fonts'))
   :append(require('config.general'))
   :append(require('config.launch'))

return config.options
```

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

### Import Platform Detection Module

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Load the platform module to detect the operating system at module load time.

```lua
local platform = require('utils.platform')
```

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

### Configure Launch Settings in Lua

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Returns default shell and launch menu configuration, which is platform-specific.

```lua
return {
  default_prog = {...},
  launch_menu = {...},
}
```

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

### events.tab-title.setup(opts?)

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Registers tab title formatting and custom events.

```APIDOC
## events.tab-title.setup(opts?)

### Description
Registers tab title formatting and custom events.

### Options
- **unseen_icon** (string, optional) - 'circle', 'numbered_circle', or 'numbered_box'.
- **hide_active_tab_unseen** (boolean, optional) - Hide unseen on active tab.
- **show_progress** (boolean, optional) - Show progress indicators.
```

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

### Visualize WezTerm Configuration Module Dependencies

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/INDEX.md

A tree representation of the project's module structure, showing the entry point and sub-directories.

```text
wezterm.lua (entry point)
  ├─→ config/init.lua (ConfigBuilder)
  ├─→ config/*.lua (configuration modules)
  ├─→ events/*.lua (event handlers)
  ├─→ utils/*.lua (shared utilities)
  └─→ colors/custom.lua (color scheme)
```

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

### right-status.setup()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-events.md

Registers the update-status event handler to display the date, time, and battery status in the right status bar.

```APIDOC
## right-status.setup()

### Description
Registers the `update-status` event handler to display a formatted date and battery status (percentage and icon) in the right status bar.

### Signature
`function setup(opts?: {date_format?: string}) -> void`

### Parameters
- **opts** (table) - Optional - Options object
- **opts.date_format** (string) - Optional - `strftime()` format string for date display (Default: '%a %H:%M:%S')

### Example
```lua
require('events.right-status').setup({
  date_format = '%Y-%m-%d %H:%M:%S'
})
```
```

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

### Import String Utilities Module

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Load the string utilities module for helper functions like prefix and suffix checking.

```lua
local str = require('utils.str')
```

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

### Manual GPU adapter selection

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Forces selection of a specific backend and device type.

```lua
local gpu_adapters = require('utils.gpu-adapter')

-- Force discrete GPU with Vulkan (Linux/Windows)
return {
  front_end = 'WebGpu',
  webgpu_preferred_adapter = gpu_adapters:pick_manual('Vulkan', 'DiscreteGpu'),
}
```

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

### Initialize FormatCells

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-cells.md

Create a new instance of the FormatCells builder.

```lua
local Cells = require('utils.cells')
local cells = Cells:new()
```

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

### Initialize WezTerm Configuration

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-config-builder.md

The main entry point in wezterm.lua that initializes events, configures backdrops, and aggregates configuration modules.

```lua
local Config = require('config')

-- Initialize all events (these modify window state, not config)
require('events.left-status').setup()
require('events.right-status').setup({ date_format = '%a %H:%M:%S' })
require('events.tab-title').setup({
   hide_active_tab_unseen = true,
   unseen_icon = 'numbered_box',
   show_progress = true,
})
require('events.new-tab-button').setup()
require('events.gui-startup').setup()

-- Initialize backdrops (provides computed config values)
require('utils.backdrops')
   :set_images_dir(require('wezterm').home_dir .. '/Pictures/Wallpapers/')
   :scan_images_dir()
   :random()

-- Build configuration
return Config:init()
   :append(require('config.appearance'))
   :append(require('config.bindings'))
   :append(require('config.domains'))
   :append(require('config.fonts'))
   :append(require('config.general'))
   :append(require('config.launch'))
   .options
```

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

### Configure Bindings in Lua

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Returns keyboard bindings and key tables.

```lua
return {
  keys = {...},
  key_tables = {...},
}
```

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

### Initialize and merge configuration modules

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/configuration.md

The main entry point in wezterm.lua that chains configuration modules. Modules are merged in the order provided, with earlier modules taking precedence.

```lua
return Config:init()
   :append(require('config.appearance'))
   :append(require('config.bindings'))
   :append(require('config.domains'))
   :append(require('config.fonts'))
   :append(require('config.general'))
   :append(require('config.launch'))
   .options
```

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

### Constructor Definition

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-backdrops.md

Internal initialization method for the BackDrops class.

```lua
function BackDrops:init()
  -> BackDrops
```

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

### Automatic GPU adapter selection

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Recommended approach for selecting the best available GPU adapter automatically.

```lua
local gpu_adapters = require('utils.gpu-adapter')

return {
  front_end = 'WebGpu',
  webgpu_power_preference = 'HighPerformance',
  webgpu_preferred_adapter = gpu_adapters:pick_best(),
}
```

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

### left-status.setup()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-events.md

Registers the update-status event handler to display the leader key state or active key table in the left status bar.

```APIDOC
## left-status.setup()

### Description
Registers the `update-status` event handler to display the leader key indicator or the active key table name in the left status bar.

### Signature
`function setup() -> void`

### Example
```lua
require('events.left-status').setup()
```
```

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

### Use PlatformType for conditional logic

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/types.md

Demonstrates checking the current operating system using the platform utility.

```lua
local platform = require('utils.platform')
if platform.os == 'windows' then
  -- Windows-specific logic
end
```

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

### Configure WezTerm Background

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/configuration.md

Initializes background image settings and enables the scrollbar.

```lua
background = backdrops:initial_options({ no_img = false })
enable_scroll_bar = true
```

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

### GpuAdapters:pick_manual()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Manually selects a specific GPU adapter by providing the desired graphics backend and device type.

```APIDOC
## GpuAdapters:pick_manual(backend, device_type)

### Description
Manually selects an adapter by specifying both the backend and device type. Logs an error and returns nil if the preferred combination is not available.

### Parameters
- **backend** (string) - Required - Graphics API backend: 'Dx12', 'Vulkan', 'Gl' (Windows/Linux); 'Metal' (Mac)
- **device_type** (string) - Required - GPU device type: 'DiscreteGpu', 'IntegratedGpu', 'Other', 'Cpu'

### Returns
- **GpuInfo|nil** - The matching GpuInfo object if found, nil if the combination is unavailable.

### Example
```lua
local gpu_adapters = require('utils.gpu-adapter')
local config = {
  front_end = 'WebGpu',
  webgpu_preferred_adapter = gpu_adapters:pick_manual('Vulkan', 'IntegratedGpu'),
}
```
```

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

### gpu_adapters:pick_manual(backend, device_type)

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Manually selects a specific GPU adapter based on the provided backend and device type.

```APIDOC
## gpu_adapters:pick_manual(backend, device_type)

### Description
Attempts to find a GPU adapter that matches the specified backend and device type.

### Parameters
- **backend** (string) - The graphics backend (e.g., 'Dx12', 'Vulkan', 'Gl', 'Metal').
- **device_type** (string) - The device type (e.g., 'DiscreteGpu', 'IntegratedGpu', 'Other', 'Cpu').

### Returns
- **GpuInfo** (table) - The matching GPU adapter information, or nil if no match is found.
```

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

### Configure Appearance in Lua

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Returns visual configuration options such as front_end and max_fps.

```lua
return {
  front_end = 'WebGpu',
  max_fps = 120,
  -- ... other options
}
```

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

### Compose Configuration with Builder Pattern

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/architecture.md

Uses a fluent API to compose configuration modules while ensuring first-come precedence and duplicate key detection.

```lua
return Config:init()
  :append(require('config.appearance'))
  :append(require('config.bindings'))
  .options
```

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

### Initialize and Validate Options

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-utility-modules.md

Constructor and validation method signatures for the OptsValidator class.

```lua
function OptsValidator:new(schema: OptsSchema)
  -> OptsValidator
```

```lua
function OptsValidator:validate(opts: table)
  -> (table, string|nil)
```

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

### Configure WezTerm Rendering Backend

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/configuration.md

Sets the graphics backend and performance parameters for the terminal window.

```lua
front_end = 'WebGpu'     -- 'WebGpu' | 'OpenGL' | 'Software'
max_fps = 120
webgpu_power_preference = 'HighPerformance'
webgpu_preferred_adapter = gpu_adapters:pick_best()  -- GpuInfo|nil
```

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

### Set Images Directory

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-backdrops.md

Define the directory path for background images. Must be called before scanning.

```lua
function BackDrops:set_images_dir(path: string)
  -> BackDrops
```

```lua
local backdrops = require('utils.backdrops')
backdrops:set_images_dir(wezterm.home_dir .. '/Pictures/Wallpapers/')
  :scan_images_dir()
```

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

### Import OptsValidator Module

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Load the OptsValidator module to validate configuration options against a defined schema.

```lua
local OptsValidator = require('utils.opts-validator')
```

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

### GpuAdapters:pick_best()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Automatically selects the best available GPU adapter based on predefined device type and graphics API priority scores.

```APIDOC
## GpuAdapters:pick_best()

### Description
Automatically selects the best GPU adapter using a scoring algorithm based on device type (Discrete > Integrated > Other > CPU) and platform-specific graphics API priority.

### Returns
- **GpuInfo|nil** - The best available GpuInfo object, or nil if no suitable adapter is found.

### Example
```lua
local gpu_adapters = require('utils.gpu-adapter')
local config = {
  front_end = 'WebGpu',
  webgpu_preferred_adapter = gpu_adapters:pick_best(),
}
```
```

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

### Clone Configuration Repository

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/README.md

Command to clone the configuration repository into the standard WezTerm config directory.

```sh
# On Windows and Unix systems
git clone https://github.com/KevinSilvester/wezterm-config.git ~/.config/wezterm
```

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

### Check string prefix with str.starts_with

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-utility-modules.md

Determines if a string begins with a specified prefix.

```lua
function str.starts_with(str: string, prefix: string)
  -> boolean
```

```lua
local str = require('utils.str')
if str.starts_with('Administrator: powershell', 'Administrator:') then
  print('Elevated shell detected')
end
```

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

### gpu_adapters:pick_best()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Automatically selects the best available GPU adapter based on pre-defined scoring for backends and device types.

```APIDOC
## gpu_adapters:pick_best()

### Description
Automatically selects the best available GPU adapter by evaluating available backends and device types against a scoring system.

### Returns
- **GpuInfo** (table) - The best available GPU adapter information, or nil if none are found.
```

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

### Reference Source File Location

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/README.md

Standard format for documenting the source file path and line range for major components.

```markdown
**File:** `config/appearance.lua`  
**Lines:** 1–75
```

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

### Manage Global State with Singleton Pattern

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/architecture.md

Modules export initialized singleton instances to maintain a single source of truth for shared state.

```lua
-- BackDrops returns initialized instance
return BackDrops:init()

-- GpuAdapters returns initialized instance
return GpuAdapters:init()
```

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

### Generate Background Options

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-backdrops.md

Create configuration objects for WezTerm's background settings, supporting focus mode toggling.

```lua
function BackDrops:initial_options(opts: {no_img?: boolean})
  -> BackgroundLayer[]
```

```lua
local backdrops = require('utils.backdrops')
backdrops:scan_images_dir()

-- Enable images
local bg = backdrops:initial_options({ no_img = false })

-- Or disable images (focus mode)
local bg_no_img = backdrops:initial_options({ no_img = true })
```

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

### platform

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-utility-modules.md

The platform module provides properties to detect the current operating system, allowing for conditional configuration logic.

```APIDOC
## platform

### Description
Provides cross-platform detection for conditional configuration. Exports a table containing the current OS and boolean flags for specific platforms.

### Properties
- **os** (PlatformType) - The current OS ('windows', 'linux', or 'mac')
- **is_win** (boolean) - True if running on Windows
- **is_linux** (boolean) - True if running on Linux
- **is_mac** (boolean) - True if running on macOS
```

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

### Chain Configuration Modules

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-config-builder.md

Uses method chaining to merge multiple configuration modules into the builder and extract the final options table.

```lua
local Config = require('config')

return Config:init()
  :append(require('config.appearance'))    -- Add appearance settings
  :append(require('config.bindings'))      -- Add key bindings
  :append(require('config.fonts'))         -- Add font configuration
  :append(require('config.general'))       -- Add general settings
  :append(require('config.launch'))        -- Add launch menu
  .options                                 -- Extract final config
```

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

### BackDrops:choices()

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-backdrops.md

Converts the internal images array into a format suitable for WezTerm's InputSelector.

```APIDOC
## BackDrops:choices()

### Description
Converts the internal images array into a format suitable for fuzzy selection UI.

### Returns
- **Array** ({id: string, label: string}[]) - An array of choice objects where id is the index and label is the filename.
```

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

### Define Individual Config Module

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-config-builder.md

Structure for individual configuration files that return a table of WezTerm options.

```lua
-- config/appearance.lua
local gpu_adapters = require('utils.gpu-adapter')
local backdrops = require('utils.backdrops')
local colors = require('colors.custom')

---@type Config
return {
   max_fps = 120,
   front_end = 'WebGpu',
   cursor_blink_rate = 650,
   colors = colors,
   background = backdrops:initial_options({ no_img = false }),
   enable_tab_bar = true,
   tab_max_width = 23,
   -- ... more options
}
```

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

### Configure Custom Colors in Lua

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Returns color scheme configuration, specifically for Catppuccin Mocha.

```lua
return {
  foreground = '#cdd6f4',
  background = '#1f1f28',
  -- ... other colors
}
```

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

### Configure WezTerm UI Colors

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/configuration.md

Maps palette variables to specific UI elements like the tab bar and background.

```lua
colorscheme = {
   foreground = mocha.text,
   background = mocha.base,
   selection_bg = mocha.surface2,
   tab_bar = {
      background = 'rgba(0, 0, 0, 0.4)',
      active_tab = { bg_color = mocha.surface2, fg_color = mocha.text },
      inactive_tab = { bg_color = mocha.surface0, fg_color = mocha.subtext1 },
      inactive_tab_hover = { bg_color = mocha.surface0, fg_color = mocha.text },
      new_tab = { bg_color = mocha.base, fg_color = mocha.text },
      new_tab_hover = { bg_color = mocha.mantle, fg_color = mocha.text, italic = true },
   },
   -- ... indexed colors, scrollbar, split colors
}
```

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

### BackDrops

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Manages background image selection, cycling, and focus mode for WezTerm.

```APIDOC
## BackDrops

### Instance Methods
- **set_images_dir(path)**: Sets the directory to scan for background images.
- **scan_images_dir()**: Loads images from the configured directory.
- **initial_options({no_img?})**: Generates the background configuration.
- **random(window?)**: Selects a random background image.
- **cycle_forward(window)**: Cycles to the next background image.
- **cycle_back(window)**: Cycles to the previous background image.
- **set_img(window, idx)**: Sets the background image by index.
- **toggle_focus(window)**: Toggles focus mode to hide/show images.
- **choices()**: Generates a list of choices for an InputSelector.

### Properties
- **current_idx** (number): The current image index.
- **images** (string[]): Array of image file paths.
- **images_dir** (string): The directory currently being scanned.
- **no_bg** (boolean): Flag indicating if focus mode is enabled.
```

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

### Define AVAILABLE_BACKENDS constant

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Defines platform-specific graphics API scoring for Windows, Linux, and macOS.

```lua
local AVAILABLE_BACKENDS = {
   windows = { Dx12   = 3, Vulkan = 2, Gl = 1 },
   linux   = { Vulkan = 2, Gl     = 1 },
   mac     = { Metal  = 1 },
}
```

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

### Project Directory Structure

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/architecture.md

The file system layout of the wezterm-config project.

```text
wezterm-config/
├── wezterm.lua              # Entry point: initializes events and builds config
├── config/
│   ├── init.lua             # ConfigBuilder class for composing config
│   ├── appearance.lua       # Visual settings: rendering, cursor, colors, UI
│   ├── bindings.lua         # Keyboard shortcuts
│   ├── domains.lua          # Multiplexing domains (WSL, SSH, Unix)
│   ├── fonts.lua            # Font selection and rendering
│   ├── general.lua          # Behavior: reload, exit, URL rules, scrollback
│   └── launch.lua           # Default shell and launch menu (platform-specific)
├── events/
│   ├── left-status.lua      # Left status bar (key table/leader indicator)
│   ├── right-status.lua     # Right status bar (date and battery)
│   ├── tab-title.lua        # Advanced tab title with icons and progress
│   ├── new-tab-button.lua   # Right-click menu on new tab button
│   └── gui-startup.lua      # GUI initialization (maximize on startup)
├── utils/
│   ├── backdrops.lua        # Background image selection and cycling
│   ├── cells.lua            # Format items builder for status bars
│   ├── gpu-adapter.lua      # GPU adapter selection for WebGpu
│   ├── opts-validator.lua   # Options validation against schemas
│   ├── platform.lua         # Platform detection (Windows/Linux/macOS)
│   ├── str.lua              # String utilities
│   └── math.lua             # Numeric utilities
├── colors/
│   └── custom.lua           # Color scheme (Catppuccin Mocha)
└── backdrops/               # Directory for background images
```

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

### Implement a custom callback

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/keybindings.md

Use wezterm.action_callback to execute complex logic, such as window dimension retrieval or configuration overrides, when a key is pressed.

```lua
{
  key = 'a',
  mods = mod.SUPER,
  action = wezterm.action_callback(function(window, pane)
    -- Custom logic here
    local dims = window:get_dimensions()
    window:set_config_overrides({...})
  end)
}
```

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

### Define pick_best Method Signature

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Signature for the method that automatically selects the best available GPU adapter.

```lua
function GpuAdapters:pick_best()
  -> GpuInfo|nil
```

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

### Detect Platform for Configuration

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-utility-modules.md

Uses the platform module to conditionally set configuration options based on the operating system.

```lua
local platform = require('utils.platform')

if platform.is_win then
  print('Running on Windows')
  options.default_prog = { 'pwsh', '-NoLogo' }
elseif platform.is_mac then
  print('Running on macOS')
  options.default_prog = { '/opt/homebrew/bin/fish', '-l' }
elseif platform.is_linux then
  print('Running on Linux')
  options.default_prog = { 'fish', '-l' }
end

-- Or use the os field
if platform.os == 'windows' then
  -- Windows-specific configuration
end
```

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

### Configure General Behavior in Lua

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Returns general behavior configuration such as auto-reload and hyperlink rules.

```lua
return {
  automatically_reload_config = true,
  hyperlink_rules = {...},
  -- ... other options
}
```

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

### ConfigBuilder

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

A builder class for composing WezTerm configuration from multiple modules.

```APIDOC
## ConfigBuilder

### Static Methods
- **init()**: Creates a new builder instance.

### Instance Methods
- **append(table)**: Merges a configuration table into the builder, returning the builder instance for chaining.

### Properties
- **options** (table): The accumulated configuration options.
```

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

### Standard Event Module Pattern

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-events.md

Template for creating new event modules, including optional validation and event registration.

```lua
local wezterm = require('wezterm')

local M = {}

M.setup = function(opts)
  -- Optional: validate options
  local valid_opts, err = VALIDATOR:validate(opts or {})
  if err then
    wezterm.log_error(err)
  end

  -- Register event handler
  wezterm.on('event-name', function(window, pane, ...)
    -- Handler logic
  end)
end

return M
```

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

### Define Right Status Bar Options

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/types.md

Schemas for configuring the right status bar, including user-provided input and the final validated configuration.

```lua
type Event.RightStatusOptionsInput = {
  date_format?: string,
}
```

```lua
type Event.RightStatusOptions = {
  date_format: string,
}
```

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

### Conditional GPU adapter selection

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Attempts a manual selection and falls back to the best available adapter if the manual selection fails.

```lua
local gpu_adapters = require('utils.gpu-adapter')

local adapter = gpu_adapters:pick_manual('Vulkan', 'DiscreteGpu')
if not adapter then
  adapter = gpu_adapters:pick_best()
end

return {
  front_end = 'WebGpu',
  webgpu_preferred_adapter = adapter,
}
```

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

### Generate background selection choices

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-backdrops.md

Returns an array of choices for use with WezTerm's InputSelector, mapping image indices to filenames.

```lua
local backdrops = require('utils.backdrops')
backdrops:scan_images_dir()

wezterm.on('update-status', function(window, pane)
  window:perform_action(
    wezterm.action.InputSelector({
      title = 'Select Background',
      choices = backdrops:choices(),
      action = wezterm.action_callback(function(_window, _pane, id)
        if id then
          backdrops:set_img(window, tonumber(id))
        end
      end),
    }),
    pane
  )
end)
```

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

### Define Tab Title Options

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/types.md

Schemas for configuring tab title appearance, including unseen indicators and progress display settings.

```lua
type Event.TabTitleOptionsInput = {
  unseen_icon?: 'circle' | 'numbered_circle' | 'numbered_box',
  hide_active_tab_unseen?: boolean,
  show_progress?: boolean,
}
```

```lua
type Event.TabTitleOptions = {
  unseen_icon: 'circle' | 'numbered_circle' | 'numbered_box',
  hide_active_tab_unseen: boolean,
  show_progress: boolean,
}
```

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

### Define GPU Adapter Information

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/types.md

Schemas for representing GPU hardware information and supported graphics backends.

```lua
type GpuInfo = {
  backend: GpuInfo.Backend,
  device_type: GpuInfo.DeviceType,
  name: string,
}
```

```lua
type GpuInfo.Backend = 'Dx12' | 'Vulkan' | 'Gl' | 'Metal' | string
```

```lua
type GpuInfo.DeviceType = 'DiscreteGpu' | 'IntegratedGpu' | 'Other' | 'Cpu'
```

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

### Format Status Bar with Segment-Based Logic

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/architecture.md

Allows independent updates and flexible ordering of status bar segments without requiring a full rebuild.

```lua
cells:add_segment('icon', icon, colors)
cells:add_segment('text', text, colors)

-- Later, update individual segments
cells:update_segment_text('text', new_text)
cells:update_segment_colors('text', new_colors)

-- Render selected segments in order
wezterm.format(cells:render({1, 2, 3}))
```

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

### Platform Detection

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Provides information about the current operating system.

```APIDOC
## Platform Detection

### Description
Detects the operating system at module load time.

### Fields
- **os**: ('windows'|'linux'|'mac') The current platform identifier.
- **is_win**: (boolean) True if running on Windows.
- **is_linux**: (boolean) True if running on Linux.
- **is_mac**: (boolean) True if running on macOS.
```

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

### Define pick_manual Method Signature

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-gpu-adapters.md

Signature for the method that allows manual selection of a specific GPU backend and device type.

```lua
function GpuAdapters:pick_manual(backend: string, device_type: string)
  -> GpuInfo|nil
```

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

### Log duplicate configuration keys

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-config-builder.md

Logs a warning when a duplicate key is encountered during the append process, retaining the original value.

```lua
wezterm.log_warn(
   'Duplicate config option detected: ',
   { old = self.options[k], new = new_options[k] }
)
```

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

### BackDrops:cycle_back(window)

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-backdrops.md

Moves to the previous image in the loaded images array, wrapping around to the last image if at the beginning.

```APIDOC
## BackDrops:cycle_back(window)

### Description
Moves to the previous image in the loaded images array. Wraps around to the last image if at the beginning. Updates the window background immediately.

### Parameters
- **window** (Window) - Required - WezTerm Window object to update
```

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

### Import modules within configuration files

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/MODULES.md

Use these imports when accessing shared utilities from within specific configuration sub-modules.

```lua
-- In config modules
local gpu_adapters = require('utils.gpu-adapter')
local backdrops = require('utils.backdrops')
local colors = require('colors.custom')
local platform = require('utils.platform')
```

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

### Configure WezTerm Tab Bar

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/configuration.md

Sets tab bar visibility, style, and behavior for tab management.

```lua
enable_tab_bar = true
hide_tab_bar_if_only_one_tab = false
use_fancy_tab_bar = false
tab_max_width = 23                              -- Characters
show_tab_index_in_tab_bar = false
switch_to_last_active_tab_when_closing_tab = true
```

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

### Define a new keybinding

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/keybindings.md

Standard structure for adding a new keybinding using a key, modifiers, and a predefined WezTerm action.

```lua
{
  key = 'a',
  mods = mod.SUPER,
  action = wezterm.action.SomeAction(...)
}
```

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

### Configure WezTerm Command Palette

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/configuration.md

Defines visual properties and dimensions for the command palette.

```lua
command_palette_fg_color = '#b4befe'
command_palette_bg_color = '#11111b'
command_palette_font_size = 12
command_palette_rows = 25
```

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

### Apply and update segment colors

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/types.md

Demonstrates applying colors to a segment and resetting the background color.

```lua
local colors = {
  bg = '#45475a',
  fg = '#cdd6f4',
}

cells:add_segment('text', 'Hello', colors)

-- Remove background
cells:update_segment_colors('text', {bg = 'UNSET'})
```

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

### cycle_forward(window)

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-backdrops.md

Advances to the next image in the list and updates the window background.

```APIDOC
## BackDrops:cycle_forward(window)

### Description
Advances to the next image in the loaded images array, wrapping around to the start if necessary, and updates the window background.

### Parameters
- **window** (Window) - Required - WezTerm Window object to update.
```

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

### Scan Images Directory

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-backdrops.md

Populate the internal images array by globbing the configured directory. Must be run before other methods.

```lua
function BackDrops:scan_images_dir()
  -> BackDrops
```

```lua
require('utils.backdrops')
  :scan_images_dir()
  :random()
```

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

### Configure Status Bar Segments with Cells

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/api-cells.md

Initializes a Cells instance and adds segments with custom styling and attributes for the status bar.

```lua
local wezterm = require('wezterm')
local Cells = require('utils.cells')
local attr = Cells.attr

-- Create cells instance
local cells = Cells:new()

-- Add segments
cells
  :add_segment(1, '▎', { bg = 'rgba(0,0,0,0.4)', fg = '#fab387' }, attr(attr.intensity('Bold')))
  :add_segment(2, ' File: ', { bg = '#45475a', fg = '#cdd6f4' }, attr(attr.intensity('Bold')))
  :add_segment(3, 'main.lua', { bg = '#45475a', fg = '#a6e3a1' })
  :add_segment(4, ' ▎', { bg = 'rgba(0,0,0,0.4)', fg = '#fab387' })

-- Render and display
local formatted = wezterm.format(cells:render({ 1, 2, 3, 4 }))
window:set_left_status(formatted)
```

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

### Configure WezTerm Cursor Appearance

Source: https://github.com/kevinsilvester/wezterm-config/blob/master/_autodocs/configuration.md

Defines cursor animation, style, blink rate, and underline thickness.

```lua
animation_fps = 120
cursor_blink_ease_in = 'EaseOut'       -- Easing function
cursor_blink_ease_out = 'EaseOut'
default_cursor_style = 'BlinkingBlock' -- Cursor shape
cursor_blink_rate = 650                -- ms
underline_thickness = '1.5pt'
```