### Complete Modal.wezterm Configuration Example

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

A comprehensive configuration example demonstrating loading the plugin, applying defaults, setting custom keybindings, adding a new 'debug' mode, and handling mode events.

```lua
local wezterm = require("wezterm")
local config = wezterm.config_builder()

-- Load the plugin
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

-- Apply all default modes
modal.apply_to_config(config)

-- Add default keybindings (ALT-n, ALT-u, ALT-c)
modal.set_default_keys(config)

-- Add custom exit-all keybinding
table.insert(config.keys, {
  key = "Escape",
  mods = "SUPER",
  action = modal.exit_all_modes("global_escape"),
})

-- Create custom mode
local debug_keys = {
  { key = "Escape", action = modal.exit_mode("debug") },
  { key = "c", mods = "CTRL", action = modal.exit_mode("debug") },
  { key = "d", action = wezterm.action.SendString("debug\n") },
}

modal.add_mode("debug", debug_keys, wezterm.format({
  { Background = { Color = "Red" } },
  { Foreground = { Color = "White" } },
  { Text = "DEBUG" },
}))

-- Add debug mode keybinding
table.insert(config.keys, {
  key = "d",
  mods = "ALT",
  action = modal.activate_mode("debug"),
})

-- Assign all key tables to config
config.key_tables = modal.key_tables

-- Handle mode events
wezterm.on("modal.enter", function(name, window, pane)
  modal.set_right_status(window, name)
  modal.set_window_title(pane, name)
end)

wezterm.on("modal.exit", function(name, window, pane)
  window:set_right_status("")
  modal.reset_window_title(pane)
end)

-- Fallback status update
wezterm.on("update-right-status", function(window, _)
  if not modal.get_mode(window) then
    window:set_right_status("")
  end
end)

return config
```

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

### Hint Icons Configuration Example

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/types.md

Provides an example of configuring hint icons and separators used in status text generation.

```lua
local icons = {
  left_seperator = wezterm.nerdfonts.ple_left_half_circle_thick,
  key_hint_seperator = " | ",
  mod_seperator = "-",
}
```

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

### KeyAssignment Examples

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/types.md

Demonstrates using built-in WezTerm actions, custom callbacks, and multiple actions for keybindings.

```lua
-- Built-in action
{ key = "j", action = wezterm.action.ActivatePaneDirection("Down") }
```

```lua
-- Custom callback
{ key = "j", action = wezterm.action_callback(function(win, pane)
  print("J pressed")
end) }
```

```lua
-- Multiple actions
{ key = "c", action = wezterm.action.Multiple({
  wezterm.action.CopyMode("ClearPattern"),
  wezterm.action_callback(function(window, pane)
    wezterm.emit("modal.exit", "copy_mode", window, pane)
  end),
}) }
```

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

### key_table Example: From Defaults

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/types.md

Shows how to reference key tables from imported modules like copy_mode and ui_mode.

```lua
local copy_mode = require("copy_mode")
-- copy_mode.key_table contains 50+ keybindings for text selection and manipulation

local ui_mode = require("ui_mode")
-- ui_mode.key_table contains 30+ keybindings for pane and tab management
```

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

### key_bind Examples

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/types.md

Illustrates creating keybindings with no modifiers, single modifiers, multiple modifiers, and for arrow keys.

```lua
-- Simple key
{ key = "j", action = wezterm.action.ActivatePaneDirection("Down") }
```

```lua
-- With single modifier
{ key = "c", mods = "CTRL", action = modal.exit_mode("copy_mode") }
```

```lua
-- With multiple modifiers
{ key = "v", mods = "CTRL|SHIFT", action = wezterm.action.CopyMode({ SetSelectionMode = "Block" }) }
```

```lua
-- Arrow keys
{ key = "LeftArrow", mods = "CTRL", action = wezterm.action.SendKey({ key = "LeftArrow", mods = "CTRL" }) }
```

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

### Basic Setup for Modal.wezterm

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/README.md

Applies default modes, keybindings, and sets up event handlers for modal entry and exit. This is the initial configuration required to use the plugin.

```lua
local wezterm = require("wezterm")
local config = wezterm.config_builder()
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

-- Apply all default modes
modal.apply_to_config(config)

-- Add default keybindings (ALT-c, ALT-u, ALT-n)
modal.set_default_keys(config)

-- Assign key tables to config
config.key_tables = modal.key_tables

-- Handle mode entry/exit
wezterm.on("modal.enter", function(name, window, pane)
  modal.set_right_status(window, name)
end)

wezterm.on("modal.exit", function(name, window, pane)
  window:set_right_status("")
end)

return config

```

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

### Modal Modes Table Example

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/types.md

Illustrates the structure of the 'modes' table, showing how different modes are registered with their properties.

```lua
modal.modes = {
  ["UI"] = { name = "UI", key_table_name = "UI", status_text = "..." },
  ["copy_mode"] = { name = "copy_mode", key_table_name = "copy_mode", status_text = "..." },
  ["Scroll"] = { name = "Scroll", key_table_name = "Scroll", status_text = "..." },
}
```

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

### Iterating Through Modes

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/types.md

Provides an example of how to iterate over the 'modes' table to access information about each registered mode.

```lua
for mode_name, mode_obj in pairs(modal.modes) do
  print("Mode: " .. mode_name)
  print("  Display name: " .. mode_obj.name)
  print("  Key table: " .. mode_obj.key_table_name)
end
```

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

### key_table Example: Custom Mode

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/types.md

Defines a custom key table for a mode named 'custom' and adds it using modal.add_mode().

```lua
local custom_keys = {
  { key = "Escape", action = modal.exit_mode("custom") },
  { key = "c", mods = "CTRL", action = modal.exit_mode("custom") },
  { key = "j", action = wezterm.action.ActivatePaneDirection("Down") },
  { key = "k", action = wezterm.action.ActivatePaneDirection("Up") },
  { key = "h", action = wezterm.action.ActivatePaneDirection("Left") },
  { key = "l", action = wezterm.action.ActivatePaneDirection("Right") },
}

modal.add_mode("custom", custom_keys)
```

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

### WezTerm Key Binding Definition Example

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/main.md

Illustrates the standard WezTerm format for defining key bindings, including key, optional modifiers, and the WezTerm action to be performed.

```lua
{
  key = "a",                    -- Key name
  mods = "CTRL|SHIFT",          -- Optional modifiers
  action = wezterm.action.Foo   -- WezTerm action
}
```

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

### Add Keybinding to Activate Custom Mode

Source: https://github.com/mlflexer/modal.wezterm/blob/main/README.md

Assign a key combination to activate a custom mode. This example binds 'ALT-m' to activate the 'mode_name' mode.

```lua
config.keys = {
  -- ...
  -- your other keybindings
  {
    key = "m",
    mods = "ALT",
    action = activate_mode("mode_name"),
  }
}
```

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

### Creating a Simple Custom Mode

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Defines keybindings and status text for a custom mode named 'mymode', then registers it with the plugin. This example includes pane navigation keys and CTRL-Escape to exit.

```lua
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

-- Define keybindings
local my_keys = {
  { key = "Escape", action = modal.exit_mode("mymode") },
  { key = "c", mods = "CTRL", action = modal.exit_mode("mymode") },
  { key = "j", action = wezterm.action.ActivatePaneDirection("Down") },
  { key = "k", action = wezterm.action.ActivatePaneDirection("Up") },
  { key = "h", action = wezterm.action.ActivatePaneDirection("Left") },
  { key = "l", action = wezterm.action.ActivatePaneDirection("Right") },
}

-- Optional: Create status text
local my_status = wezterm.format({
  { Background = { Color = "Purple" } },
  { Foreground = { Color = "White" } },
  { Text = "MY MODE" },
})

-- Register the mode
modal.add_mode("mymode", my_keys, my_status)

-- Add to config
config.key_tables = modal.key_tables

-- Add keybinding to enter the mode
table.insert(config.keys, {
  key = "m",
  mods = "ALT",
  action = modal.activate_mode("mymode"),
})
```

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

### Handling Modal Enter Event

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/main.md

Example of how to use `wezterm.on()` to listen for the `modal.enter` event, which is emitted when a mode is activated. This snippet shows how to update the status and window title.

```lua
wezterm.on("modal.enter", function(name, window, pane)
  modal.set_right_status(window, name)
  modal.set_window_title(pane, name)
  print("Entered mode: " .. name)
end)
```

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

### Define Custom Mode Key Table and Status Text

Source: https://github.com/mlflexer/modal.wezterm/blob/main/README.md

Create a custom mode by defining its key table and optional status text. This example shows how to set up a 'mode_name' with a key to exit and a visual indicator.

```lua
-- example key table
local key_table = {
  { key = "Escape", action = modal.exit_mode("mode_name") },
  { key = "c", mods = "CTRL", action = modal.exit_mode("mode_name") },
  { key = "z", action = wezterm.action.TogglePaneZoomState },
}
-- example right status text
local status_text = wezterm.format({
  { Attribute = { Intensity = "Bold" } },
  { Foreground = { Color = "Red" } },
  { Text = wezterm.nerdfonts.ple_left_half_circle_thick },
  { Foreground = { Color = "Black" } },
  { Background = { Color = "Red" } },
  { Text = "MODE NAME  " },
})
modal.add_mode("mode_name", key_table, status_text)
```

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

### Handling Modal Exit Event

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/main.md

Example of how to use `wezterm.on()` to listen for the `modal.exit` event, which is emitted when a mode is exited. This snippet demonstrates resetting the status and window title.

```lua
wezterm.on("modal.exit", function(name, window, pane)
  window:set_right_status("")
  modal.reset_window_title(pane)
  print("Exited mode: " .. name)
end)
```

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

### Registering Modal Enter Event Handler

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/architecture.md

Example of how to register a handler for the `modal.enter` event, which is emitted when a mode is activated. This handler updates the window's right status and the pane's title.

```lua
wezterm.on("modal.enter", function(name, window, pane) 
  modal.set_right_status(window, name)
  modal.set_window_title(pane, name)
end)
```

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

### Basic Initialization with Presets

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Quickly set up the modal plugin with default modes and keybindings. This applies all 5 default modes, default entry keybindings, and color-matched status text.

```lua
local wezterm = require("wezterm")
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

modal.apply_to_config(config)
modal.set_default_keys(config)
```

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

### Applying Modal to WezTerm Configuration

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/types.md

Shows how to load the modal plugin and apply its configuration, including automatically assigning key tables to WezTerm's config.

```lua
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

modal.apply_to_config(config)

-- All key tables are automatically assigned
config.key_tables = modal.key_tables
```

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

### Applying and Accessing Key Tables

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/main.md

Shows how to apply the modal.wezterm plugin's key tables to your WezTerm configuration and access them after application.

```lua
local wezterm = require("wezterm")
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

modal.apply_to_config(config)

-- Copy the key tables to config
config.key_tables = modal.key_tables

-- key_tables now contains entries like:
-- { "UI", { ... key bindings ... } }
-- { "copy_mode", { ... key bindings ... } }
-- { "Scroll", { ... key bindings ... } }
```

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

### Get Current WezTerm Mode

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/main.md

Retrieves the active mode for a given window. Use this to display mode-specific information in the status bar or for conditional logic.

```lua
local wezterm = require("wezterm")
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

wezterm.on("update-right-status", function(window, _)
  local mode = modal.get_mode(window)
  if mode then
    window:set_right_status("Mode: " .. mode.name)
  else
    window:set_right_status("Normal")
  end
end)
```

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

### Full WezTerm Configuration with Modal Plugin

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/main.md

This snippet shows a complete WezTerm configuration file that integrates the MLFlexer modal plugin. It demonstrates applying default modes, setting default keys, defining a custom mode with specific keybindings and status, adding a custom activation key, and handling modal enter/exit events.

```lua
local wezterm = require("wezterm")
local config = wezterm.config_builder()
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

-- Apply and configure default modes
modal.apply_to_config(config)
modal.set_default_keys(config)

-- Define custom mode
local custom_keys = {
  { key = "Escape", action = modal.exit_mode("custom") },
  { key = "j", action = wezterm.action.SendString("down\n") },
}

local custom_status = wezterm.format({
  { Background = { Color = "Purple" } },
  { Foreground = { Color = "White" } },
  { Text = "CUSTOM" },
})

modal.add_mode("custom", custom_keys, custom_status)

-- Add custom activation key
table.insert(config.keys, {
  key = "x",
  mods = "ALT",
  action = modal.activate_mode("custom"),
})

-- Handle mode events
wezterm.on("modal.enter", function(name, window, pane)
  modal.set_right_status(window, name)
  modal.set_window_title(pane, name)
end)

wezterm.on("modal.exit", function(name, window, pane)
  window:set_right_status("")
  modal.reset_window_title(pane)
end)

return config

```

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

### Handling Modal Exit All Event

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/main.md

Example of how to use `wezterm.on()` to listen for the `modal.exit_all` event, which is emitted when all modes are exited. This snippet resets the status and window title.

```lua
wezterm.on("modal.exit_all", function(name, window, pane)
  window:set_right_status("")
  modal.reset_window_title(pane)
  print("Exited all modes via: " .. name)
end)
```

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

### Applying Configuration in Modal WezTerm

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/architecture.md

Outlines the steps performed by the `apply_to_config` function, including enabling defaults, loading modes, extracting colors, adding modes, and setting up the global key tables.

```lua
apply_to_config(config)
  ├─ enable_defaults()
  │   └─ Append defaults/ to package.path
  ├─ Load ui_mode
  ├─ Load scroll_mode
  ├─ Load copy_mode
  ├─ Load search_mode
  ├─ Load visual_mode
  ├─ Extract colors from config
  ├─ For each mode:
  │   ├─ Get status text from module
  │   └─ add_mode(...)
  └─ config.key_tables = key_tables
```

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

### Define Git Workflow Mode Keys

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/extending.md

Sets up a 'git' mode with shortcuts for common Git commands like status, diff, log, add, commit, push, and fetch. Includes a visual indicator for the mode.

```lua
local git_mode_keys = {
  { key = "Escape", action = modal.exit_mode("git") },
  { key = "s", action = wezterm.action.SendString("git status\n") },
  { key = "d", action = wezterm.action.SendString("git diff\n") },
  { key = "l", action = wezterm.action.SendString("git log --oneline -10\n") },
  { key = "a", action = wezterm.action.SendString("git add .\n") },
  { key = "c", action = wezterm.action_callback(function(window, pane)
    pane:send_text("git commit -m '\"")
    window:perform_action(modal.exit_mode("git"), pane)
  end) },
  { key = "p", action = wezterm.action.SendString("git push\n") },
  { key = "f", action = wezterm.action.SendString("git fetch\n") },
}

local git_status = wezterm.format({
  { Background = { Color = "Magenta" } },
  { Foreground = { Color = "White" } },
  { Text = " GIT " },
})

modal.add_mode("git", git_mode_keys, git_status)

table.insert(config.keys, {
  key = "g",
  mods = "ALT",
  action = modal.activate_mode("git"),
})
```

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

### Troubleshoot Keybindings Not Working

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Verify that `config.key_tables` is correctly assigned to `modal.key_tables` to enable modal keybindings.

```lua
config.key_tables = modal.key_tables
```

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

### Create a Simple Custom Mode

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/extending.md

Defines a new custom mode with specific keybindings, an optional status text, and registers it for activation.

```lua
local wezterm = require("wezterm")
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

-- Step 1: Define keybindings
local my_mode_keys = {
  -- Exit the mode
  { key = "Escape", action = modal.exit_mode("my_mode") },
  { key = "c", mods = "CTRL", action = modal.exit_mode("my_mode") },
  
  -- Custom actions
  { key = "a", action = wezterm.action.SendString("action_a\n") },
  { key = "b", action = wezterm.action.SendString("action_b\n") },
}

-- Step 2: Create status text (optional)
local my_mode_status = wezterm.format({
  { Background = { Color = "Magenta" } },
  { Foreground = { Color = "White" } },
  { Text = "MY_MODE" },
})

-- Step 3: Register the mode
modal.add_mode("my_mode", my_mode_keys, my_mode_status)

-- Step 4: Add keybinding to activate mode
table.insert(config.keys, {
  key = "m",
  mods = "ALT",
  action = modal.activate_mode("my_mode"),
})

-- Step 5: Add to config
config.key_tables = modal.key_tables
```

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

### Get Search Mode Hint Status Text

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/default-modes.md

Generates formatted status text for search mode, including keybinding hints. This function requires configuration for icons and colors.

```lua
local search_mode = require("search_mode")

local icons = {
  left_seperator = wezterm.nerdfonts.ple_left_half_circle_thick,
  key_hint_seperator = " | ",
  mod_seperator = "-",
}

local colors = {
  key_hint_seperator = "Yellow",
  key = "Green",
  hint = "Red",
  bg = "Black",
  left_bg = "Gray",
}

local mode_colors = { bg = "Cyan", fg = "Black" }

local status = search_mode.get_hint_status_text(icons, colors, mode_colors)
```

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

### Default Keybindings Implementation

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Shows the equivalent code for `modal.set_default_keys(config)`, illustrating how standard mode activation keybindings are added to `config.keys`.

```lua
modal.set_default_keys(config)

-- Equivalent to:
table.insert(config.keys, { key = "n", mods = "ALT", action = modal.activate_mode("Scroll") })
table.insert(config.keys, { key = "u", mods = "ALT", action = modal.activate_mode("UI") })
table.insert(config.keys, { key = "c", mods = "ALT", action = modal.activate_mode("copy_mode") })
```

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

### Activate Key Table Parameters

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/types.md

Optional parameters for WezTerm's ActivateKeyTable action. Customize one-shot behavior for key tables.

```lua
{
  one_shot?: boolean,
  name?: string
}
```

```lua
-- Activate mode with one-shot behavior
modal.activate_mode("custom", { one_shot = true })

-- Default non-one-shot behavior
modal.activate_mode("custom")
-- Same as
modal.activate_mode("custom", { one_shot = false })
```

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

### Search Mode Temporary State

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/architecture.md

Example of using wezterm.GLOBAL to store temporary state within the search mode. This uses a boolean flag to indicate the current state of the search mode.

```lua
wezterm.GLOBAL.search_mode - Boolean flag for search mode state
```

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

### Get Visual Mode Hint Status Text

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/default-modes.md

Generates formatted status text for visual selection mode, including keybinding hints. This function requires configuration for icons and colors.

```lua
local visual_mode = require("visual_mode")

local icons = {
  left_seperator = wezterm.nerdfonts.ple_left_half_circle_thick,
  key_hint_seperator = " | ",
  mod_seperator = "-",
}

local colors = {
  key_hint_seperator = "Yellow",
  key = "Green",
  hint = "Red",
  bg = "Black",
  left_bg = "Gray",
}

local mode_colors = { bg = "Yellow", fg = "Black" }

local status = visual_mode.get_hint_status_text(icons, colors, mode_colors)
```

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

### List Available Default Modes

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/extending.md

Applies the modal plugin to the configuration and lists all available default modes.

```lua
modal.apply_to_config(config)

-- Get all modes
local modes_list = modal.modes

-- Create a list of available modes
local available_modes = {}
for name, mode_obj in pairs(modes_list) do
  table.insert(available_modes, name)
end

print("Available modes:", table.concat(available_modes, ", "))
```

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

### Manually Adding a Custom Mode

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/types.md

Demonstrates how to define custom keybindings for a new mode and register it using `add_mode()`.

```lua
local custom_keys = {
  { key = "Escape", action = modal.exit_mode("custom") },
  { key = "j", action = wezterm.action.ActivatePaneDirection("Down") },
}

modal.add_mode("custom", custom_keys)

-- key_tables["custom"] is now populated with custom_keys
config.key_tables = modal.key_tables
```

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

### Registering Modal Exit Event Handler

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/architecture.md

Example of how to register a handler for the `modal.exit` event, which is emitted when a mode is exited. This handler clears the window's right status and resets the pane's title.

```lua
wezterm.on("modal.exit", function(name, window, pane) 
  window:set_right_status("")
  modal.reset_window_title(pane)
end)
```

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

### Activating a UI Mode with Key Table

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/architecture.md

Demonstrates the sequence of calls to activate a UI mode in modal.wezterm, which involves calling `activate_mode` followed by WezTerm's `ActivateKeyTable` action.

```lua
activate_mode("ui") 
  ↓
wezterm.action.ActivateKeyTable({ name = "ui", one_shot = false })
  ↓
WezTerm looks up key_tables["ui"]
  ↓
Keys from that table take precedence
```

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

### Copy Mode Temporary State

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/architecture.md

Example of using wezterm.GLOBAL to store temporary state within the copy mode. This specifically tracks the active visual mode type, allowing submode state to persist across callbacks.

```lua
wezterm.GLOBAL.visual_mode - Tracks active visual mode type ("Cell", "Line", "Block", "SemanticZone")
```

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

### enable_defaults

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/main.md

Configures Lua's package path to enable loading default mode files from the plugin directory.

```APIDOC
## enable_defaults

### Description
Configures Lua's package path to enable loading default mode files from the plugin directory.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **url** (string) - Required - Plugin URL; typically `"https://github.com/MLFlexer/modal.wezterm"`

### Behavior
- Called internally by `apply_to_config()` to load default modes
- Adds the `defaults/` directory to the Lua package path, allowing `require("copy_mode")`, `require("ui_mode")`, etc.

### Request Example
```lua
local wezterm = require("wezterm")
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

-- Optional: call manually if not using apply_to_config()
modal.enable_defaults("https://github.com/MLFlexer/modal.wezterm")

-- Now you can require default modes
local ui_mode = require("ui_mode")
```

### Response
#### Success Response (200)
- **return value** (nil)
```

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

### Accessing Color Scheme Information

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/architecture.md

Demonstrates how `apply_to_config` accesses color information from the WezTerm configuration, either directly from `config.colors` or by fetching built-in schemes.

```lua
config.colors
  ↓ or
config.color_scheme → wezterm.color.get_builtin_schemes()
  ↓
Extract foreground, background, ansi colors
  ↓
Use in status text generation
```

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

### Vim Integration with Smart-Splits

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Apply modal configuration to WezTerm's config. UI mode automatically handles integration with Neovim and smart-splits.nvim by passing navigation keys through.

```lua
modal.apply_to_config(config)

-- UI mode already handles this automatically
-- It checks for IS_NVIM variable set by smart-splits.nvim
-- and passes navigation keys through to Vim when appropriate

wezterm.on("modal.enter", function(name, window, pane)
  if name == "UI" then
    print("Smart-splits integration active if in Neovim")
  end
  modal.set_right_status(window, name)
end)
```

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

### Enable Defaults and Customize UI Mode

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Enables default modes and customizes the UI mode with custom keybindings and status bar colors.

```lua
modal.enable_defaults("https://github.com/MLFlexer/modal.wezterm")

local ui_mode = require("ui_mode")

-- Get base keybindings
local my_keys = ui_mode.key_table

-- Add custom keybindings
table.insert(my_keys, {
  key = "R",
  mods = "CTRL",
  action = wezterm.action_callback(function(win, pane)
    -- Custom action
    print("Custom action!")
  end)
})

-- Create status with custom colors
local colors = {
  key_hint_seperator = config.colors.foreground,
  key = config.colors.foreground,
  hint = config.colors.foreground,
  bg = config.colors.background,
  left_bg = config.colors.background,
}

local status = ui_mode.get_hint_status_text({
  left_seperator = wezterm.nerdfonts.ple_left_half_circle_thick,
  key_hint_seperator = "  ",
  mod_seperator = "-",
}, colors, { bg = config.colors.ansi[2], fg = config.colors.background })

modal.add_mode("UI", my_keys, status)
```

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

### Enable Defaults and Customize Copy Mode

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Enables default modes and customizes the copy mode with additional keybindings and a custom status bar appearance.

```lua
modal.enable_defaults("https://github.com/MLFlexer/modal.wezterm")

local copy_mode = require("copy_mode")

-- Use default keybindings
local my_keys = copy_mode.key_table

-- Add custom keybindings
table.insert(my_keys, {
  key = "q",
  action = modal.exit_mode("copy_mode")
})

-- Create custom status
local icons = {
  left_seperator = "█",
  key_hint_seperator = "•",
  mod_seperator = "+",
}

local colors = {
  key_hint_seperator = "Cyan",
  key = "Yellow",
  hint = "Magenta",
  bg = "Black",
  left_bg = "Black",
}

local status = copy_mode.get_hint_status_text(icons, colors, {
  bg = "Blue",
  fg = "White"
})

-- Register with custom configuration
modal.add_mode("copy_mode", my_keys, status, "copy_mode")
```

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

### apply_to_config() Behavior

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Demonstrates the state of `config.key_tables` after calling `modal.apply_to_config()`. This function populates keybindings for UI, Scroll, copy_mode, and search_mode.

```lua
modal.apply_to_config(config)

-- After this call:
-- config.key_tables is populated with:
-- - UI mode keybindings
-- - Scroll mode keybindings
-- - copy_mode keybindings
-- - search_mode keybindings
-- - Visual mode status (no keybindings, submodes of copy_mode)
```

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

### Troubleshoot Modes Not Appearing

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Ensure you have event listeners set up for modal mode entry to update the status bar.

```lua
wezterm.on("modal.enter", function(name, window, pane)
  modal.set_right_status(window, name)
end)
```

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

### Modal.wezterm API: Utility Functions

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/README.md

Utility functions for creating status text, enabling defaults, applying configurations, and setting default keys.

```lua
-- Utilities
modal.create_status_text(left_sep, key_hints, mode_colors) → string
modal.enable_defaults(url: string)
modal.apply_to_config(config)
modal.set_default_keys(config)

```

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

### Activating a Mode in Modal WezTerm

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/architecture.md

Details the logic within `activate_mode`, distinguishing between activating 'copy_mode', 'search_mode', or other custom modes, and showing the corresponding WezTerm actions and event emissions.

```lua
activate_mode(name, params?)
  ├─ If name == "copy_mode"
  │   ├─ wezterm.action.ActivateCopyMode
  │   └─ action_callback → wezterm.emit("modal.enter", ...)
  ├─ If name == "search_mode"
  │   ├─ wezterm.action.Search()
  │   └─ action_callback → wezterm.emit("modal.enter", ...)
  └─ Else
      ├─ wezterm.action.ActivateKeyTable({ name = name, ... })
      └─ action_callback → wezterm.emit("modal.enter", ...)
```

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

### Create a Custom Mode in Modal.wezterm

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/README.md

Defines a new custom mode with specific keybindings for pane navigation and activates it with the 'ALT-m' key. This demonstrates how to extend the plugin's functionality.

```lua
local my_keys = {
  { key = "Escape", action = modal.exit_mode("custom") },
  { key = "j", action = wezterm.action.ActivatePaneDirection("Down") },
  { key = "k", action = wezterm.action.ActivatePaneDirection("Up") },
}

modal.add_mode("custom", my_keys, wezterm.format({
  { Background = { Color = "Blue" } },
  { Text = "CUSTOM" },
}))

table.insert(config.keys, {
  key = "m",
  mods = "ALT",
  action = modal.activate_mode("custom"),
})

config.key_tables = modal.key_tables

```

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

### Handling Mode Entry and Exit Events

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Sets up event listeners for `modal.enter`, `modal.exit`, and `modal.exit_all` to update the right status and window title when modes change. This ensures the UI reflects the current mode.

```lua
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

modal.apply_to_config(config)

-- Listen for mode entry
wezterm.on("modal.enter", function(name, window, pane)
  modal.set_right_status(window, name)
  modal.set_window_title(pane, name)
end)

-- Listen for mode exit
wezterm.on("modal.exit", function(name, window, pane)
  window:set_right_status("")
  modal.reset_window_title(pane)
end)

-- Listen for exit-all
wezterm.on("modal.exit_all", function(name, window, pane)
  window:set_right_status("")
  modal.reset_window_title(pane)
end)
```

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

### Modal.wezterm API: Event Handlers

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/README.md

Event handlers for mode entry, exit, and exit_all events.

```lua
wezterm.on("modal.enter", function(name, window, pane) end)
wezterm.on("modal.exit", function(name, window, pane) end)
wezterm.on("modal.exit_all", function(name, window, pane) end)

```

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

### Enable Default Modes and Add Custom UI Mode

Source: https://github.com/mlflexer/modal.wezterm/blob/main/README.md

This configuration enables default modes and adds a custom 'UI' mode with specific keybindings and status text formatting, including Nerd Font icons and color customization.

```lua
modal.enable_defaults("https://github.com/MLFlexer/modal.wezterm")
-- "ui_mode" can be replaced by any filename from the /defaults directory
local key_table = require("ui_mode").key_table

local icons = {
  left_seperator = wezterm.nerdfonts.ple_left_half_circle_thick,
  key_hint_seperator = " | ",
  mod_seperator = "-",
}
local hint_colors = {
  key_hint_seperator = "Yellow",
  key = "Green",
  hint = "Red",
  bg = "Black",
  left_bg = "Gray",
}
local mode_colors = { bg = "Red", fg = "Black" }
local status_text = require("ui_mode").get_hint_status_text(icons, hint_colors, mode_colors)

modal.add_mode("UI", key_table, status_text)

config.keys = {
  -- ...
  -- your other keybindings
  {
    key = "u",
    mods = "ALT",
    action = activate_mode("UI"),
  }
}
config.key_tables = modal.key_tables
```

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

### Troubleshoot Colors Not Matching

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Call `apply_to_config()` early in your WezTerm configuration, before making custom color changes, to ensure colors match the color scheme.

```lua
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")
modal.apply_to_config(config)  -- Call before custom color changes

-- Then you can override individual colors if needed
```

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

### Accessing and Iterating Modes

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/main.md

Demonstrates how to access specific mode definitions by name and iterate through all available modes provided by the modal.wezterm plugin.

```lua
local wezterm = require("wezterm")
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

-- Access mode definitions
print(modal.modes["UI"].status_text)

-- Iterate all modes
for name, mode_obj in pairs(modal.modes) do
  print(name .. ": " .. mode_obj.name)
end
```

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

### Create Pane Resizing Keybinding

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/default-modes.md

Creates a keybinding that either passes keys to Vim for resizing if in Neovim, or adjusts the pane size in the specified direction for regular shells.

```lua
function adjust_pane_size(
  key: string,
  direction: string,
  mods: string,
  vim_key: string,
  vim_mods: string,
  cells: number
): key_bind
end
```

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

### Manually Configure Colors with a Scheme

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/configuration.md

Applies a specific color scheme and then manually configures hint colors for modal modes using the scheme's color definitions.

```lua
local config = wezterm.config_builder()
config.color_scheme = "Dracula"

modal.apply_to_config(config)

-- Or manually set colors
local colors = config.colors or wezterm.color.get_builtin_schemes()[config.color_scheme]

local hint_colors = {
  key_hint_seperator = colors.ansi[3],  -- Yellow
  key = colors.ansi[2],                 -- Green
  hint = colors.ansi[1],                -- Red
  bg = colors.background,
  left_bg = colors.background,
}
```

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

### Require Modal Plugin

Source: https://github.com/mlflexer/modal.wezterm/blob/main/README.md

This snippet shows how to require the modal plugin in your WezTerm configuration. It's the first step for using any of its features.

```lua
local wezterm = require("wezterm")
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")
```

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

### Register a New Modal Mode with Custom Keybindings

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/main.md

Use `add_mode` to register a new modal mode. Provide a unique name, an array of keybinding definitions, and optionally custom status text and an internal key table name. Ensure the `key_tables` property is added to your WezTerm configuration.

```lua
local wezterm = require("wezterm")
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

-- Define custom keybindings
local custom_keys = {
  { key = "Escape", action = modal.exit_mode("custom") },
  { key = "j", action = wezterm.action.ActivatePaneDirection("Down") },
  { key = "k", action = wezterm.action.ActivatePaneDirection("Up") },
}

-- Create status text
local status = wezterm.format({
  { Background = { Color = "Blue" } },
  { Foreground = { Color = "White" } },
  { Text = "CUSTOM" },
})

-- Register the mode
modal.add_mode("custom", custom_keys, status)

-- Add to config
config.key_tables = modal.key_tables

-- Bind a key to activate the mode
config.keys = {
  {
    key = "m",
    mods = "ALT",
    action = modal.activate_mode("custom"),
  },
}
```

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

### apply_to_config

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/main.md

Applies all default modes (UI, Scroll, Copy, Search, Visual) to the WezTerm configuration.

```APIDOC
## apply_to_config

### Description
Applies all default modes (UI, Scroll, Copy, Search, Visual) to the WezTerm configuration.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **config** (any) - Required - WezTerm config table

### Behavior
- Enables default modes automatically
- Detects color scheme from config or uses defaults
- Creates all default modes with hint-based status text
- Sets `config.key_tables` to include all registered key tables
- Does NOT add keybindings to activate modes; use `set_default_keys()` for that

### Default modes registered:
- UI mode (green status)
- Scroll mode (white status)
- Copy mode (blue status)
- Search mode (cyan status)
- Visual mode (yellow status)

### Request Example
```lua
local wezterm = require("wezterm")
local config = wezterm.config_builder()
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")

modal.apply_to_config(config)
modal.set_default_keys(config)

config.keys = config.keys or {}
table.insert(config.keys, {
  key = "Escape",
  mods = "SUPER",
  action = modal.exit_all_modes("global"),
})

return config
```

### Response
#### Success Response (200)
- **return value** (nil)
```

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

### Activate Copy Mode in WezTerm

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/architecture.md

This snippet illustrates the sequence of events when a user activates copy mode. It shows how WezTerm processes key presses, executes actions, and triggers user listeners for mode entry.

```text
User presses ALT-c
  │
  ├─ WezTerm looks up ALT-c in config.keys
  │
  ├─ Executes action: modal.activate_mode("copy_mode")
  │
  ├─ Function execute:
  │   ├─ Detects "copy_mode" → special case
  │   ├─ Execute: wezterm.action.ActivateCopyMode
  │   └─ Execute: action_callback → emit("modal.enter", ...)
  │
  ├─ WezTerm activates copy mode
  │   ├─ Looks up key_tables["copy_mode"]
  │   └─ Now uses those keybindings
  │
  └─ User's listener fires:
      wezterm.on("modal.enter", function(name, window, pane)
        modal.set_right_status(window, name)
      end)
      │
      └─ Sets right status bar to "Copy" or formatted status text
```

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

### Vim Integration Helper Functions

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/api-reference/default-modes.md

Helper functions for integrating UI mode with Neovim when using the smart-splits.nvim plugin.

```APIDOC
## Vim Integration

UI mode includes smart integration with Neovim when using smart-splits.nvim plugin:

### Helper Functions:

#### is_vim

```lua
function is_vim(pane: any): boolean
```

Checks if the pane is running Neovim by reading the `IS_NVIM` user variable set by smart-splits.nvim.

#### activate_pane_direction

```lua
function activate_pane_direction(
  key: string,
  direction: string,
  mods: string,
  vim_mods: string
): key_bind
```

Creates a keybinding that:
- Passes keys to Vim if in Neovim
- Activates pane direction if in regular shell

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| key | string | The key to bind |
| direction | string | Pane direction: "Left", "Down", "Up", "Right" |
| mods | string | WezTerm modifiers |
| vim_mods | string | Vim modifiers |

#### adjust_pane_size

```lua
function adjust_pane_size(
  key: string,
  direction: string,
  mods: string,
  vim_key: string,
  vim_mods: string,
  cells: number
): key_bind
```

Creates a keybinding that:
- Passes keys to Vim if in Neovim
- Adjusts pane size if in regular shell

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| key | string | The key to bind |
| direction | string | Pane direction: "Left", "Down", "Up", "Right" |
| mods | string | WezTerm modifiers |
| vim_key | string | The Vim key to use when in Neovim |
| vim_mods | string | Vim modifiers |
| cells | number | The number of cells to adjust the pane size by |
```

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

### Activating Search Mode

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/architecture.md

Illustrates how to activate the search mode within WezTerm's copy mode using modal.wezterm, which triggers `wezterm.action.Search`.

```lua
activate_mode("search_mode")
  ↓
wezterm.action.Search({ CaseSensitiveString = "" })
  ↓
WezTerm enters search overlay
  ↓
key_tables["search_mode"] is used
```

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

### Troubleshoot Keybindings Not Working

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/README.md

Ensure that custom key tables are assigned to the `config.key_tables` variable. This is a common requirement for custom mode activation.

```lua
config.key_tables = modal.key_tables  -- Must assign to config
```

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

### Core Functions

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/README.md

Functions for registering, activating, and exiting modes, managing status displays, and utility functions. Also includes access to global tables for modes and keybindings.

```APIDOC
## Core Functions

### `modal.add_mode(name: string, key_table, status_text?, key_table_name?)

Registers a new mode with the plugin.

### `modal.activate_mode(name: string, params?)

Activates a specified mode. Returns a `KeyAssignment`.

### `modal.exit_mode(name: string)

Exits a specified mode. Returns a `KeyAssignment`.

### `modal.exit_all_modes(name: string)

Exits all active modes. Returns a `KeyAssignment`.

### `modal.get_mode(window)

Queries the current mode for a given window. Returns the mode name or `nil`.

### `modal.set_right_status(window, name?)

Sets the right-hand status for a window, optionally displaying a mode name.

### `modal.set_window_title(pane, name: string)

Sets the window title for a pane, often used to display the current mode.

### `modal.reset_window_title(pane)

Resets the window title for a pane.

### `modal.create_status_text(left_sep, key_hints, mode_colors)

Utility function to create status text strings.

### `modal.enable_defaults(url: string)

Enables default configurations, likely from a plugin URL.

### `modal.apply_to_config(config)

Applies default modal configurations to a WezTerm config object.

### `modal.set_default_keys(config)

Sets default keybindings for modes within a WezTerm config object.

### Global Tables

- **`modal.modes`**: A table mapping mode names to mode configurations.
- **`modal.key_tables`**: A table mapping key table names to their respective key bindings.
```

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

### Integrate with Vim

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/README.md

Automatically apply modal configuration to WezTerm. This integration ensures that UI mode keys are passed to Vim when running, or to panes otherwise.

```lua
-- Just use apply_to_config() - integration is automatic
modal.apply_to_config(config)

-- UI mode's h/j/k/l will go to Vim if running, panes otherwise
```

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

### Custom Logic with Action Callbacks

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/architecture.md

Demonstrates the use of WezTerm's `action_callback` for implementing custom logic within modes. This pattern is used for actions like toggling visual modes, entering/exiting search modes, and other mode-specific behaviors.

```lua
wezterm.action_callback(function(window, pane)
  -- Custom logic here
  -- Can emit events, modify state, etc.
end)
```

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

### Log Mode Activation Details

Source: https://github.com/mlflexer/modal.wezterm/blob/main/_autodocs/extending.md

A utility function to log information about a mode's key bindings, including modifiers and keys. Useful for debugging custom modes.

```lua
local function log_keys(mode_name, key_table)
  wezterm.log_info("Mode: " .. mode_name)
  for i, binding in ipairs(key_table) do
    local mods = binding.mods or "—"
    wezterm.log_info("  " .. i .. ". [" .. mods .. "] " .. binding.key)
  end
end

log_keys("my_mode", my_mode_keys)
```