### Basic Setup for Periodic Saving and Startup Restore

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/INDEX.md

Enables periodic saving of WezTerm state at a specified interval and configures the plugin to restore state automatically when the GUI starts.

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

-- Enable periodic saving
resurrect.state_manager.periodic_save({
  interval_seconds = 600,
  save_workspaces = true,
})

-- Restore on startup
wezterm.on("gui-startup", resurrect.state_manager.resurrect_on_gui_startup)
```

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

### Configuration Example for Resurrect.wezterm

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

This is a complete configuration example for the resurrect.wezterm plugin, ready to be copied and adapted. It includes settings for encryption, periodic saving, startup restoration, and keybindings.

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

-- Configuration
resurrect.configure({
  -- Save and restore windows, tabs, and panes
  save_to_disk = true,
  -- Save and restore scrollback buffer
  save_scrollback = true,
  -- Maximum number of lines of scrollback to save
  max_scrollback_lines = 1000,
  -- Save interval in seconds (0 to disable periodic saving)
  save_interval = 60,
  -- Restore on startup
  restore_on_startup = true,
  -- Encryption backend (nil, "age", "rage", "gpg")
  encryption = nil,
  -- Encryption key file path (if encryption is enabled)
  encryption_key_path = nil,
  -- Directory to save session state
  session_dir = "~/.wezterm/session",
  -- Exclude specific panes from being saved
  exclude_panes = {},
  -- Custom keybindings
  keys = {
    save = { "<leader>ss" },
    load = { "<leader>sl" },
    delete = { "<leader>sd" },
  },
})

-- Example of using the API (not part of configuration)
-- resurrect.save_session()
-- resurrect.load_session()
-- resurrect.delete_session()

```

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

### Set State Save Directory (Windows Example)

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/configuration-guide.md

Example of setting the state save directory on Windows. Must use a valid path with write permissions.

```lua
-- Must use valid path with write permissions
resurrect.state_manager.change_state_save_dir("C:\\Users\\<user>\\AppData\\Local\\wezterm\\state\\")
```

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

### Set State Save Directory (Linux Example)

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/configuration-guide.md

Example of setting the state save directory on Linux, utilizing XDG_DATA_HOME if available.

```lua
local xdg_data = os.getenv("XDG_DATA_HOME") or (os.getenv("HOME") .. "/.local/share")
resurrect.state_manager.change_state_save_dir(xdg_data .. "/wezterm/resurrect/")
```

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

### Basic Encryption Setup with Resurrect.wezterm

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/encryption-api.md

Demonstrates the basic setup for enabling encryption during configuration initialization. This ensures all subsequent save and load operations utilize the configured encryption method.

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

-- During config initialization
resurrect.state_manager.set_encryption({
  enable = true,
  method = "age",
  private_key = "/home/user/.ssh/age_key.txt",
  public_key = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p",
})

-- Now all saves and loads use encryption
resurrect.state_manager.periodic_save({
  interval_seconds = 600,
  save_workspaces = true,
})
```

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

### Example Window State JSON

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

Provides an example of a window state object, detailing the window's title, its tabs, and its dimensions.

```json
{
  "title": "Editor",
  "tabs": [
    {
      "title": "main.py",
      "pane_tree": {...},
      "is_active": true,
      "is_zoomed": false
    }
  ],
  "size": {
    "cols": 200,
    "rows": 50,
    "pixel_width": 1920,
    "pixel_height": 1000,
    "dpi": 96
  }
}
```

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

### Local Process Info Example

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

Provides an example of the local_process_info object, detailing the name, arguments, current working directory, and executable path of a foreground process. This is crucial for restoring TUI applications.

```json
{
  "name": "vim",
  "executable": "/usr/bin/vim",
  "argv": ["vim", "+10", "file.txt"],
  "cwd": "/home/user/project"
}
```

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

### Example fmt_fun Implementation

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

Provides an example implementation of a formatting function for the fuzzy loader. This function prepends a checkmark and applies green foreground color to the state label.

```lua
local fmt = function(label) 
  return wezterm.format({
    { Foreground = { AnsiColor = "Green" } },
    { Text = "✓ " .. label },
  })
end
```

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

### Set State Save Directory (macOS Example)

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/configuration-guide.md

Example of setting the state save directory on macOS using the HOME environment variable.

```lua
resurrect.state_manager.change_state_save_dir(os.getenv("HOME") .. "/.local/share/wezterm/resurrect/")
```

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

### Configuration and Events

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

Guides on setting up the plugin, including encryption, periodic saving, startup restoration, keybindings, and detailed information on all lifecycle events.

```APIDOC
## Configuration & Events

This section covers how to configure and interact with the plugin's lifecycle events.

### Configuration Guide
- **Module:** `configuration-guide.md`
- **Description:** Details setup patterns, encryption configuration (age, rage, gpg), periodic saving intervals, startup restoration, keybinding examples, and provides a complete configuration example.

### Events Reference
- **Module:** `events.md`
- **Description:** Documents all lifecycle events, including their emission conditions and practical usage examples.
```

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

### Install GnuPG (gpg)

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/encryption-api.md

Provides installation commands for GnuPG (gpg) on macOS, Debian/Ubuntu Linux, and Windows.

```bash
# macOS
brew install gnupg

# Linux (Debian/Ubuntu)
apt install gnupg

# Windows
chocolatey install gnupg
```

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

### Install Rage Encryption

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/encryption-api.md

Provides installation commands for the 'rage' encryption tool on macOS, Debian/Ubuntu Linux, and via Cargo.

```bash
# macOS
brew install rage

# Linux (Debian/Ubuntu)
apt install rage

# Cargo
cargo install rage
```

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

### Example JSON State File

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

This is an example of a JSON file used to store Wezterm window and tab states. It includes details about window size, pane tree structure, current working directory, and process information.

```json
{
   "window_states":[
      {
         "size":{
            "cols":191,
            "dpi":96,
            "pixel_height":1000,
            "pixel_width":1910,
            "rows":50
         },
         "tabs":[
            {
               "is_active":true,
               "pane_tree":{
                  "cwd":"/home/user/",
                  "domain": "SSHMUX:domain",
                  "height":50,
                  "index":0,
                  "is_active":true,
                  "is_zoomed":false,
                  "left":0,
                  "pixel_height":1000,
                  "pixel_width":1910,
                  "process":"/bin/bash", -- value is empty if attached to a remote domain
                  "text":"Some text", -- not saved if attached to a remote domain, see https://github.com/MLFlexer/resurrect.wezterm/issues/41
                  "top":0,
                  "width":191
               },
               "title":"tab_title"
            }
         ],
         "title":"window_title"
      }
   ],
   "workspace":"workspace_name"
}
```

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

### Example encryption_opts Configuration

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

Shows a typical configuration for enabling encryption using the 'age' method and specifying paths for the private and public keys.

```lua
{
  enable = true,
  method = "age",
  private_key = "/home/user/.ssh/age_key.txt",
  public_key = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p",
}
```

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

### Pane Tree Example with Alt-Screen Active

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

Shows a pane_tree where the 'alt_screen_active' field is true, indicating an alternate screen buffer is in use. This example includes 'process' information for a foreground application like vim.

```json
{
  "left": 0,
  "top": 0,
  "width": 100,
  "height": 50,
  "cwd": "/home/user",
  "alt_screen_active": true,
  "process": {
    "name": "vim",
    "executable": "/usr/bin/vim",
    "argv": ["vim", "file.txt"],
    "cwd": "/home/user"
  },
  "is_active": true
}
```

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

### Install Age Encryption

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/encryption-api.md

Provides installation commands for the 'age' encryption tool on macOS, Debian/Ubuntu Linux, and from source.

```bash
# macOS
brew install age

# Linux (Debian/Ubuntu)
apt install age

# Build from source
go install filippo.io/age/cmd/age@latest
```

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

### Example Tab Size Object

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

Demonstrates the structure for tab size, including character rows, columns, pixel dimensions, and DPI.

```json
{
  "rows": 50,
  "cols": 200,
  "pixel_width": 1920,
  "pixel_height": 1000,
  "dpi": 96
}
```

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

### Example restore_opts Usage

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

Demonstrates how to configure restore options, including setting relative sizing, closing open tabs, specifying a target window, and providing a custom pane restore callback.

```lua
local opts = {
  relative = true,
  restore_text = true,
  close_open_tabs = true,
  window = current_window,
  on_pane_restore = resurrect.tab_state.default_on_pane_restore,
}
```

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

### Emit restore_window.start event

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before starting window restoration. This event has no parameters.

```lua
wezterm.emit("resurrect.window_state.restore_window.start")
```

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

### Example Workspace State JSON

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

Illustrates the structure of a workspace state object, showing a workspace name and its associated window states.

```json
{
  "workspace": "dev",
  "window_states": [
    {
      "title": "main",
      "tabs": [...],
      "size": {...}
    }
  ]
}
```

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

### Example Custom Formatting Functions

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/fuzzy-loader-api.md

Provides examples of how to define custom formatting functions for workspace and tab labels. The workspace formatter uses Wezterm's format function for colored output, while the tab formatter returns plain text.

```lua
local opts = {
  fmt_workspace = function(label) {
    return wezterm.format({
      { Foreground = { AnsiColor = "Green" } },
      { Text = "🚀 " .. label },
    })
  end,
  fmt_tab = function(label) {
    -- Just return plain text
    return "Tab: " .. label
  end,
}
```

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

### Emit restore_tab.start event

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before starting tab restoration. This event has no parameters.

```lua
wezterm.emit("resurrect.tab_state.restore_tab.start")
```

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

### Emit restore_workspace.start event

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before starting workspace restoration. This event has no parameters.

```lua
wezterm.emit("resurrect.workspace_state.restore_workspace.start")
```

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

### Table Merging with Defaults Example

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/utils-api.md

Demonstrates merging user options with default options using `tbl_deep_extend` with the 'force' strategy to prioritize user settings.

```lua
local utils = require("resurrect.utils")

-- Define defaults
local default_opts = {
  relative = true,
  restore_text = true,
  interval_seconds = 900,
  on_pane_restore = nil,
}

-- User provides partial config
local user_opts = {
  interval_seconds = 600,
}

-- Merge with "force" to override defaults
local final_opts = utils.tbl_deep_extend("force", default_opts, user_opts)
-- Result has user's interval_seconds (600) and defaults for others
```

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

### Example of macOS GUI App PATH Issue

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/encryption-api.md

Illustrates the difference between a potentially failing method string and a working one when specifying the encryption tool's path on macOS.

```lua
-- This may fail:
method = "age"

-- This will work:
method = "/opt/homebrew/bin/age"
```

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

### Simple Pane Tree Example

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

Illustrates a basic pane_tree object representing a single pane without any splits. This is useful for understanding the core properties of a pane's layout and state.

```json
{
  "left": 0,
  "top": 0,
  "width": 100,
  "height": 50,
  "cwd": "/home/user",
  "domain": "local",
  "text": "bash-5.1$ ",
  "is_active": true,
  "is_zoomed": false,
  "alt_screen_active": false
}
```

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

### Enable Automatic Session Restoration on GUI Startup

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/configuration-guide.md

Automatically restores the previous session when Wezterm starts. Also enables periodic saving of the current state.

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

wezterm.on("gui-startup", resurrect.state_manager.resurrect_on_gui_startup)

-- Also enable periodic saving to record state
resurrect.state_manager.periodic_save({
  interval_seconds = 600,
  save_workspaces = true,
})
```

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

### Example Tab State JSON

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

Illustrates the structure of a tab state object, showing the tab title, pane tree details, and its active/zoomed status.

```json
{
  "title": "dev",
  "pane_tree": {
    "left": 0,
    "top": 0,
    "width": 200,
    "height": 50,
    "cwd": "/home/user/project",
    "domain": "local",
    "text": "...",
    "is_active": true,
    "is_zoomed": false,
    "alt_screen_active": false
  },
  "is_active": true,
  "is_zoomed": false
}
```

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

### Custom Pane Restore Callback

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/tab-state-api.md

An example of a custom callback function for restoring panes, demonstrating how to selectively restore text without re-executing processes.

```lua
-- Custom restoration callback
resurrect.tab_state.restore_tab(tab, tab_state, {
  relative = true,
  on_pane_restore = function(pane_tree)
    -- Only restore text, never re-execute processes
    if pane_tree.text then
      pane_tree.pane:inject_output(pane_tree.text)
    end
  end,
})
```

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

### Resurrect State on GUI Startup

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

Restores the workspace state when the Wezterm GUI starts. Requires a mechanism to write the current workspace state beforehand.

```lua
wezterm.on("gui-startup", resurrect.state_manager.resurrect_on_gui_startup)
```

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

### Pane Tree Example with Horizontal Split

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

Demonstrates a pane_tree structure with a horizontal split, showing how the 'right' field is used to represent a child pane. This is key for visualizing and restoring complex layouts.

```json
{
  "left": 0,
  "top": 0,
  "width": 100,
  "height": 50,
  "cwd": "/home/user/left",
  "right": {
    "left": 50,
    "top": 0,
    "width": 50,
    "height": 50,
    "cwd": "/home/user/right",
    "is_active": false,
    "text": "..."
  },
  "is_active": true
}
```

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

### Wezterm Resurrect Event Listener Example

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

Sets up listeners for specific Wezterm Resurrect events to display toast notifications. It includes logic to suppress notifications for periodic save events.

```lua
local resurrect_event_listeners = {
  "resurrect.error",
  "resurrect.state_manager.save_state.finished",
}
local is_periodic_save = false
wezterm.on("resurrect.periodic_save", function()
  is_periodic_save = true
end)
for _, event in ipairs(resurrect_event_listeners) do
  wezterm.on(event, function(...)
    if event == "resurrect.state_manager.save_state.finished" and is_periodic_save then
      is_periodic_save = false
      return
    end
    local args = { ... }
    local msg = event
    for _, v in ipairs(args) do
      msg = msg .. " " .. tostring(v)
    end
    wezterm.gui.gui_windows()[1]:toast_notification("Wezterm - resurrect", msg, nil, 4000)
  end)
end

```

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

### resurrect_on_gui_startup

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/state-manager-api.md

Handles GUI startup events to restore the previous session. It reads the current state, expects a 'workspace' type, and uses internal functions to load and restore the workspace, finally setting it as the active workspace.

```APIDOC
## resurrect_on_gui_startup

### Description
GUI startup event handler to restore previous session. Reads `save_state_dir/current_state` file, expects two lines: workspace name and type. Only handles "workspace" type. Loads state via `load_state` and restores workspace with `spawn_in_workspace`, `relative`, `restore_text` options. Sets active workspace via `wezterm.mux.set_active_workspace`.

### Method
Function Call

### Parameters
None

### Return
- Success flag (boolean)
- Error message (string or nil) if failed

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

wezterm.on("gui-startup", resurrect.state_manager.resurrect_on_gui_startup)
```
```

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

### Get Tab State

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/tab-state-api.md

Captures the complete state of a tab, including all panes and their layout. Use this to save the current state of a tab.

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

-- Get and save current tab state
local tab = wezterm.mux.get_active_window():active_tab()
local state = resurrect.tab_state.get_tab_state(tab)
resurrect.state_manager.save_state(state)
```

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

### Automatically Update Wezterm Plugins

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

Add this line to your Wezterm configuration to automatically update all installed Wezterm plugins. This simplifies plugin maintenance.

```lua
wezterm.plugin.update_all()
```

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

### Keybinding for Fuzzy Loading States

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/INDEX.md

Sets up an ALT+r keybinding to trigger a fuzzy finder for loading saved states. It allows users to select and restore workspaces, windows, or tabs interactively.

```lua
config.keys = {
  {
    key = "r",
    mods = "ALT",
    action = wezterm.action_callback(function(win, pane)
      resurrect.fuzzy_loader.fuzzy_load(win, pane, function(id, label)
        local state_type = id:match("^([^/]+)")
        local file = id:match("([^/]+)$"):gsub("%.json$", "")
        local state = resurrect.state_manager.load_state(file, state_type)
        
        if state_type == "workspace" then
          resurrect.workspace_state.restore_workspace(state, {
            relative = true,
            restore_text = true,
            on_pane_restore = resurrect.tab_state.default_on_pane_restore,
          })
        end
      end)
    end),
  },
}
```

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

### resurrect.file_io.write_state.start

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before serializing and writing state to disk. Includes the destination file path and event type.

```APIDOC
## resurrect.file_io.write_state.start

### Description
Emitted before serializing and writing state to disk.

### Parameters
- file_path (string): Full destination file path
- event_type (string): "workspace", "window", or "tab"
```

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

### Log Encryption Operations in WezTerm

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Logs the start and finish of encryption and decryption operations. It extracts the filename from the provided file path for clearer logging.

```lua
local function log_encryption(operation)
  return function(file_path)
    local filename = file_path:match("([^/\\]+)$")
    wezterm.log_info(string.format("Encryption %s: %s", operation, filename))
  end
end

wezterm.on("resurrect.file_io.encrypt.start", log_encryption("starting"))
wezterm.on("resurrect.file_io.encrypt.finished", log_encryption("finished"))
wezterm.on("resurrect.file_io.decrypt.start", log_encryption("decryption starting"))
wezterm.on("resurrect.file_io.decrypt.finished", log_encryption("decryption finished"))
```

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

### Define Keybinding to Load State with Fuzzy Finder

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/configuration-guide.md

Sets up an ALT+r keybinding that opens a fuzzy finder to select and restore saved workspace, window, or tab states. It handles different state types and restoration options.

```lua
config.keys = {
  {
    key = "r",
    mods = "ALT",
    action = wezterm.action_callback(function(win, pane)
      resurrect.fuzzy_loader.fuzzy_load(win, pane, function(id, label)
        local state_type = id:match("^([^/]+)")
        local file = id:match("([^/]+)$"):gsub("%.json$", "")
        
        local state = resurrect.state_manager.load_state(file, state_type)
        
        if state_type == "workspace" then
          resurrect.workspace_state.restore_workspace(state, {
            relative = true,
            restore_text = true,
            on_pane_restore = resurrect.tab_state.default_on_pane_restore,
          })
        elseif state_type == "window" then
          resurrect.window_state.restore_window(win:mux_window(), state, {
            relative = true,
            restore_text = true,
            on_pane_restore = resurrect.tab_state.default_on_pane_restore,
          })
        elseif state_type == "tab" then
          resurrect.tab_state.restore_tab(pane:tab(), state, {
            relative = true,
            restore_text = true,
            on_pane_restore = resurrect.tab_state.default_on_pane_restore,
          })
        end
      end)
    end),
  },
}
```

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

### Listen to Encryption Events

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/file-io-api.md

Attaches event listeners to track the start and finish of the encryption process for file I/O operations. Logs messages to the console.

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

wezterm.on("resurrect.file_io.encrypt.start", function(file_path)
  wezterm.log_info("Starting encryption: " .. file_path)
end)

wezterm.on("resurrect.file_io.encrypt.finished", function(file_path)
  wezterm.log_info("Encryption finished: " .. file_path)
end)
```

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

### resurrect.state_manager.load_state.start

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before loading state from disk. Includes the state identifier and type.

```APIDOC
## resurrect.state_manager.load_state.start

### Description
Emitted before loading state from disk.

### Parameters
- name (string): State identifier
- type (string): "workspace", "window", or "tab"
```

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

### Sanitize JSON String

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/file-io-api.md

Replaces control characters in a JSON string with escaped Unicode sequences to ensure validity. Emits start and finish events.

```lua
local function sanitize_json(data)
  -> string
end
```

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

### Emit resurrect.file_io.write_state.start Event

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before state is serialized and written to disk, this event includes the full file path and the type of state being written.

```lua
wezterm.emit("resurrect.file_io.write_state.start", file_path: string, event_type: string)
```

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

### Get Current Wezterm Window Width

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/utils-api.md

Retrieves the width of the currently focused Wezterm window in terminal columns. Defaults to 80 if no window is focused.

```lua
function get_current_window_width()
  -> number
end
```

```lua
local utils = require("resurrect.utils")

local width = utils.get_current_window_width()
print("Current window width: " .. width)
```

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

### resurrect.file_io.encrypt.start

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before encrypting state data. Includes the target file path for the encrypted output.

```APIDOC
## resurrect.file_io.encrypt.start

### Description
Emitted before encrypting state data.

### Parameters
- file_path (string): Target file path for encrypted output
```

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

### Get Window State

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/window-state-api.md

Captures the complete state of a WezTerm window, including all its tabs and their pane layouts. This function is useful for saving the current window configuration.

```lua
function get_window_state(window)
  -> window_state
end
```

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

-- Get and save current window state
local mux_window = wezterm.mux.get_active_window()
local state = resurrect.window_state.get_window_state(mux_window)
resurrect.state_manager.save_state(state)
```

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

### Define Keybinding to Save All State (Workspace + Windows)

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/configuration-guide.md

Configures an ALT+s keybinding to save the state of the entire workspace and all open windows. It logs a confirmation message upon completion.

```lua
config.keys = {
  {
    key = "s",
    mods = "ALT",
    action = wezterm.action_callback(function(win, pane)
      local ws = resurrect.workspace_state.get_workspace_state()
      resurrect.state_manager.save_state(ws)
      
      for _, mux_win in ipairs(wezterm.mux.all_windows()) do
        local win_state = resurrect.window_state.get_window_state(mux_win)
        resurrect.state_manager.save_state(win_state)
      end
      
      wezterm.log_info("All state saved")
    end),
  },
}
```

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

### Emit resurrect.file_io.encrypt.start Event

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before state data is encrypted, this event specifies the target file path for the encrypted output.

```lua
wezterm.emit("resurrect.file_io.encrypt.start", file_path: string)
```

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

### Get Current Workspace State

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/workspace-state-api.md

Captures the current state of an active workspace. This function iterates through all multiplexer windows in the current workspace and captures their individual states.

```lua
function get_workspace_state()
  -> workspace_state
end
```

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

-- Get and save current workspace state
local state = resurrect.workspace_state.get_workspace_state()
resurrect.state_manager.save_state(state)
```

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

### delete_state

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/state-manager-api.md

Deletes a specified saved state file. It emits start and finish events and uses `os.remove()` to delete the file. If an error occurs during deletion, it emits a `resurrect.error` event.

```APIDOC
## delete_state

### Description
Deletes a saved state file. Emits `resurrect.state_manager.delete_state.start` event, calls `os.remove()` on the full path, emits `resurrect.error` event if deletion fails, and emits `resurrect.state_manager.delete_state.finished` event.

### Method
Function Call

### Parameters
#### Path Parameters
- **file_path** (string) - Required - Relative path from save_state_dir (e.g., "workspace/my_state.json")

### Return
None

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

-- Delete a workspace state
resurrect.state_manager.delete_state("workspace/old_session.json")
```
```

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

### Track restoration progress

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Tracks the progress of workspace, window, and tab restorations using boolean flags. Prints messages to the console indicating the start and completion of workspace restoration.

```lua
local resurrection_in_progress = {
  workspace = false,
  window = false,
  tab = false,
}

wezterm.on("resurrect.workspace_state.restore_workspace.start", function()
  resurrection_in_progress.workspace = true
  print("Restoring workspace...")
end)

wezterm.on("resurrect.workspace_state.restore_workspace.finished", function()
  resurrection_in_progress.workspace = false
  print("Workspace restored")
end)

-- Similar for window and tab events...
```

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

### Restore Session on GUI Startup

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/state-manager-api.md

This function is intended to be used as a GUI startup event handler to automatically restore the previous session. It reads the current state, handles workspace type, and loads the state using specified options.

```lua
function resurrect_on_gui_startup()
  -> boolean, string|nil
end
```

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

wezterm.on("gui-startup", resurrect.state_manager.resurrect_on_gui_startup)
```

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

### Create Directory with Parents

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/utils-api.md

Ensures a directory and its parent directories exist. Handles platform-specific path separators.

```lua
function ensure_folder_exists(path)
```

```lua
local utils = require("resurrect.utils")

-- Create directory structure
utils.ensure_folder_exists("/home/user/.local/share/wezterm/resurrect")
```

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

### Suppress periodic save notifications

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Listens for periodic save start and end events to conditionally display error notifications. Logs all errors but only shows toasts for non-periodic saves.

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

local is_periodic_save = false

wezterm.on("resurrect.state_manager.periodic_save.start", function()
  is_periodic_save = true
end)

wezterm.on("resurrect.error", function(err)
  -- Skip toast for periodic saves, but log all errors
  wezterm.log_error("Resurrect: " .. err)
  
  if not is_periodic_save then
    wezterm.gui.gui_windows()[1]:toast_notification(
      "Resurrect Error",
      err,
      nil,
      4000
    )
  end
end)

wezterm.on("resurrect.state_manager.periodic_save.finished", function()
  is_periodic_save = false
end)
```

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

### Emit resurrect.state_manager.load_state.start Event

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before loading state from disk, this event provides the state identifier and type.

```lua
wezterm.emit("resurrect.state_manager.load_state.start", name: string, type: string)
```

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

### Write State with Optional Encryption

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/file-io-api.md

Serializes a state object to a JSON file, with optional encryption. It handles JSON encoding, sanitization, and emits events for start, encryption, and finish stages.

```lua
function write_state(file_path, state, event_type)
end
```

```lua
local file_io = require("resurrect.file_io")

local state = {
  workspace = "my_workspace",
  window_states = { -- ... },
}

file_io.write_state("/path/to/state.json", state, "workspace")
```

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

### Configure Rage Encryption

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/encryption-api.md

Sets up the encryption configuration for the 'rage' method, including enabling encryption, specifying the method, and providing private and public keys.

```lua
resurrect.state_manager.set_encryption({
  enable = true,
  method = "rage",
  private_key = "/home/user/.ssh/age_key.txt",
  public_key = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p",
})
```

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

### Define Keybinding to Save Workspace State

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/configuration-guide.md

Sets up an ALT+w keybinding to save the current workspace state. This action logs a confirmation message upon successful save.

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

local config = {}

config.keys = {
  {
    key = "w",
    mods = "ALT",
    action = wezterm.action_callback(function(win, pane)
      local ws = resurrect.workspace_state.get_workspace_state()
      resurrect.state_manager.save_state(ws)
      wezterm.log_info("Workspace saved")
    end),
  },
}

return config
```

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

### Delete Saved State File

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/state-manager-api.md

Use this function to delete a specific saved state file. Provide the relative path of the file from the save state directory. It emits start and finish events, and an error event if deletion fails.

```lua
function delete_state(file_path)
```
```

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

-- Delete a workspace state
resurrect.state_manager.delete_state("workspace/old_session.json")
```

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

### Save Workspace, Window, and Tab States

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

Configure keybindings to save the current workspace, window, or tab state. Use ALT+w for workspace, ALT+W for window, and ALT+T for tab.

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

config.keys = {
  -- ...
  {
    key = "w",
    mods = "ALT",
    action = wezterm.action_callback(function(win, pane)
        resurrect.state_manager.save_state(resurrect.workspace_state.get_workspace_state())
      end),
  },
  {
    key = "W",
    mods = "ALT",
    action = resurrect.window_state.save_window_action(),
  },
  {
    key = "T",
    mods = "ALT",
    action = resurrect.tab_state.save_tab_action(),
  },
  {
    key = "s",
    mods = "ALT",
    action = wezterm.action_callback(function(win, pane)
        resurrect.state_manager.save_state(resurrect.workspace_state.get_workspace_state())
        resurrect.window_state.save_window_action()
      end),
  },
}
```

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

### Emit decrypt.start event

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before decrypting the state file. Includes the file path.

```lua
wezterm.emit("resurrect.file_io.decrypt.start", file_path: string)
```

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

### Configure Encryption with Age

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/configuration-guide.md

Configures optional encryption for state files using the Age method. Ensure the private key file exists and is accessible.

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

-- Generate key if needed:
-- age-keygen -o ~/.ssh/age_key.txt

resurrect.state_manager.set_encryption({
  enable = true,
  method = "age",
  private_key = "/home/user/.ssh/age_key.txt",
  public_key = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p",
})
```

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

### Create Pane Tree from Wezterm Panes

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/pane-tree-api.md

Constructs a binary tree representing pane layouts from Wezterm's pane information. It sorts panes, identifies the root, extracts pane details (domain, cwd, scrollback/process info), and recursively inserts remaining panes as children. Clears pane references, retaining only coordinates.

```lua
local pane_tree = require("resurrect.pane_tree")

-- Get panes from a tab
local tab = wezterm.mux.get_active_window():active_tab()
local panes = tab:panes_with_info()

-- Build tree
local tree = pane_tree.create_pane_tree(panes)

-- Tree can now be serialized to JSON and later restored
print(wezterm.json_encode(tree))
```

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

### Register Event Callback

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/overview.md

Subscribe to plugin events using `wezterm.on`. This allows you to react to various plugin lifecycle and I/O operations.

```lua
wezterm.on(event_name, callback)
```

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

### Custom Encryption and Decryption Functions

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/encryption-api.md

Shows how to implement custom encrypt and decrypt functions to use alternative tools for file encryption and decryption within the Resurrect.wezterm plugin.

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

resurrect.state_manager.set_encryption({
  enable = true,
  private_key = "/path/to/key",
  public_key = "public_key",
  
  -- Custom encrypt that uses a different tool
  encrypt = function(file_path, lines)
    local cmd = string.format("my_tool encrypt -k %s -o %s", 
      "public_key", file_path:gsub(" ", "\\ "))
    
    local success, output = wezterm.run_child_process({
      "bash", "-c",
      cmd .. " | " .. "echo " .. lines,
    })
    
    if not success then
      error("Encryption failed: " .. output)
    end
  end,
  
  -- Custom decrypt
  decrypt = function(file_path)
    local success, output, stderr = wezterm.run_child_process({
      "my_tool", "decrypt", "-k", "/path/to/key", file_path
    })
    
    if not success then
      error("Decryption failed: " .. stderr)
    end
    
    return output
  end,
})
```

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

### Emit fuzzy_load.start event

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted when the fuzzy load dialog opens. Includes the target window and pane.

```lua
wezterm.emit("resurrect.fuzzy_loader.fuzzy_load.start", window: MuxWindow, pane: Pane)
```

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

### Listen for Events with wezterm.on()

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Use `wezterm.on()` to subscribe to events emitted by resurrect.wezterm. Replace `resurrect.event_name` with the specific event you want to handle.

```lua
wezterm.on("resurrect.event_name", function(...)
  -- handle event
end)
```

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

### Configure Encryption with Rage

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/configuration-guide.md

Configures optional encryption for state files using the Rage method, which is compatible with Age keys. Ensure the private key file exists.

```lua
resurrect.state_manager.set_encryption({
  enable = true,
  method = "rage",
  private_key = "/home/user/.ssh/age_key.txt",  -- Compatible with age keys
  public_key = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p",
})
```

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

### Configure Encryption with Custom Functions

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/configuration-guide.md

Enables encryption using custom encrypt and decrypt functions. These functions should handle the logic for encrypting and decrypting file content.

```lua
resurrect.state_manager.set_encryption({
  enable = true,
  private_key = "/path/to/key",
  public_key = "public_key",
  
  encrypt = function(file_path, plaintext)
    -- Custom encryption implementation
    local cmd = string.format("custom_tool encrypt -k %s -o %s", 
      "public_key", file_path:gsub(" ", "\\ "))
    
    local process_args = { "bash", "-c", cmd }
    local success, output, stderr = wezterm.run_child_process(process_args)
    
    if not success then
      error("Encryption failed: " .. stderr)
    end
  end,
  
  decrypt = function(file_path)
    -- Custom decryption implementation
    local success, output, stderr = wezterm.run_child_process({
      "custom_tool", "decrypt", "-k", "/path/to/key", file_path
    })
    
    if not success then
      error("Decryption failed: " .. stderr)
    end
    
    return output
  end,
})
```

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

### Platform Path Separator

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/utils-api.md

String property representing the path separator for the current platform ('\' on Windows, '/' on Unix-like systems).

```lua
separator: string
```

```lua
local utils = require("resurrect.utils")

-- Construct platform-appropriate paths
local state_dir = "/home/user" .. utils.separator .. "state"
-- Windows: "C:\Users\user\state"
-- Unix: "/home/user/state"
```

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

### Platform-Specific File Path Construction

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/utils-api.md

The `utils.is_windows` flag helps determine the correct root directory for storing session states based on the operating system. It constructs paths using `os.getenv` and `utils.separator`.

```lua
local utils = require("resurrect.utils")

local state_root
if utils.is_windows then
  -- Use user's local app data on Windows
  state_root = os.getenv("LOCALAPPDATA") .. utils.separator .. "wezterm"
else
  -- Use XDG base dir on Linux, ~/Library on macOS
  state_root = os.getenv("HOME") .. utils.separator .. ".local" .. utils.separator .. "share" .. utils.separator .. "wezterm"
end

utils.ensure_folder_exists(state_root .. utils.separator .. "resurrect")
```

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

### Enable Encryption in WezTerm Config

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

Configure the Resurrect plugin to use encryption. Specify the encryption method (age, rage, or gpg) and provide the path to the private key and the public key.

```lua
local resurrect = wezterm.plugin.require("https://github.com/MLFlexer/resurrect.wezterm")
resurrect.state_manager.set_encryption({
  enable = true,
  method = "age" -- "age" is the default encryption method, but you can also specify "rage" or "gpg"
  private_key = "/path/to/private/key.txt", -- if using "gpg", you can omit this
  public_key = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p",
})
```

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

### Keybindings for Saving Workspace, Window, and Tab States

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/INDEX.md

Defines custom keybindings using ALT modifier to manually save the current workspace, window, or tab state. Requires the 'wezterm' module.

```lua
local config = {}

config.keys = {
  {
    key = "w",
    mods = "ALT",
    action = wezterm.action_callback(function(win, pane)
      local state = resurrect.workspace_state.get_workspace_state()
      resurrect.state_manager.save_state(state)
    end),
  },
  {
    key = "W",
    mods = "ALT",
    action = resurrect.window_state.save_window_action(),
  },
  {
    key = "T",
    mods = "ALT",
    action = resurrect.tab_state.save_tab_action(),
  },
}

return config
```

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

### Configure Periodic Saving with Custom Interval

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/configuration-guide.md

Configures periodic saving with a custom interval of 10 minutes and enables saving of workspaces.

```lua
-- Save every 10 minutes
resurrect.state_manager.periodic_save({
  interval_seconds = 600,
  save_workspaces = true,
})
```

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

### resurrect.state_manager.delete_state.start

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before deleting a state file. Includes the file path to be deleted.

```APIDOC
## resurrect.state_manager.delete_state.start

### Description
Emitted before deleting a state file.

### Parameters
- file_path (string): Relative path from save_state_dir
```

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

### Workspace State API

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/INDEX.md

Enables capturing and restoring the entire workspace, including all windows and their configurations.

```APIDOC
## Module: resurrect.workspace_state

### Description
Workspace-level capture and restoration of all open windows and their states.

### Functions
- `get_workspace_state()`: Capture the current workspace state.
- `restore_workspace(state, opts?)`: Restore a workspace from a saved state.
```

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

### Configure GPG Encryption

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/encryption-api.md

Sets up the encryption configuration for the 'gpg' method, enabling encryption and specifying the public key (recipient). The private key is managed by GPG itself.

```lua
-- Note: private_key is omitted for GPG (uses default key)
resurrect.state_manager.set_encryption({
  enable = true,
  method = "gpg",
  public_key = "your_email@example.com",  -- or key ID
})
```

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

### Emit resurrect.state_manager.delete_state.start Event

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/events.md

Emitted before a state file is deleted, this event provides the relative path of the file to be removed.

```lua
wezterm.emit("resurrect.state_manager.delete_state.start", file_path: string)
```

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

### Decrypt Resurrect State Files

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/INDEX.md

Demonstrates how to decrypt state files using 'age' or 'gpg' for verification. Ensure you have the correct decryption keys.

```bash
# age decryption
age -d -i ~/.ssh/age_key.txt ~/.local/share/wezterm/resurrect/workspace/my_state.json

# gpg decryption
gpg --decrypt ~/.local/share/wezterm/resurrect/workspace/my_state.json.gpg
```

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

### Configure Age Encryption

Source: https://github.com/mlflexer/resurrect.wezterm/blob/main/_autodocs/encryption-api.md

Sets up the encryption configuration for the 'age' method, including enabling encryption, specifying the method, and providing private and public keys.

```lua
resurrect.state_manager.set_encryption({
  enable = true,
  method = "age",
  private_key = "/home/user/.ssh/age_key.txt",
  public_key = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p",
})
```