Struct Config 

pub struct Config {

    pub cols: usize,
    pub rows: usize,
    pub font_size: f32,
    pub font_family: String,
    pub font_family_bold: Option<String>,
    pub font_family_italic: Option<String>,
    pub font_family_bold_italic: Option<String>,
    pub font_ranges: Vec<FontRange>,
    pub line_spacing: f32,
    pub char_spacing: f32,
    pub enable_text_shaping: bool,
    pub enable_ligatures: bool,
    pub enable_kerning: bool,
    pub font_rendering: FontRenderingConfig,
    pub window_title: String,
    pub allow_title_change: bool,
    pub rendering: RenderingConfig,
    pub window: WindowConfig,
    pub placement: WindowPlacementConfig,
    pub background: BackgroundConfig,
    pub image: ImageConfig,
    pub download_save_location: DownloadSaveLocation,
    pub last_download_directory: Option<String>,
    pub shader: GlobalShaderConfig,
    pub input: InputConfig,
    pub selection: SelectionConfig,
    pub mouse: MouseConfig,
    pub word_selection: WordSelectionConfig,
    pub copy_mode: CopyModeConfig,
    pub scrollback: ScrollbackConfig,
    pub unicode: UnicodeConfig,
    pub cursor: CursorConfig,
    pub scrollbar: ScrollbarConfig,
    pub theme_colors: ThemeColorsConfig,
    pub screenshot_format: String,
    pub shell: ShellConfig,
    pub semantic_history: SemanticHistoryConfig,
    pub command_separator: CommandSeparatorConfig,
    pub clipboard: ClipboardConfig,
    pub max_osc_data_length: usize,
    pub command_history_max_entries: usize,
    pub notifications: NotificationConfig,
    pub ssh: SshConfig,
    pub tabs: TabConfig,
    pub tab_colors: TabBarColorsConfig,
    pub panes: PaneConfig,
    pub tmux: TmuxConfig,
    pub power: PowerConfig,
    pub shader_watch: ShaderWatchConfig,
    pub shader_overrides: ShaderOverridesConfig,
    pub keybindings: Vec<KeyBinding>,
    pub custom_action_prefix_key: String,
    pub integrations: IntegrationConfig,
    pub updates: UpdateConfig,
    pub session_restore: SessionRestoreConfig,
    pub search: SearchConfig,
    pub session_log: SessionLogConfig,
    pub log_level: LogLevel,
    pub badge: BadgeConfig,
    pub status_bar: StatusBarConfig,
    pub progress_bar: ProgressBarConfig,
    pub automation: AutomationConfig,
    pub snippets: Vec<SnippetConfig>,
    pub actions: Vec<CustomActionConfig>,
    pub collapsed_settings_sections: Vec<String>,
    pub dynamic_profile_sources: Vec<DynamicProfileSource>,
    pub security: SecurityConfig,
    pub ai_inspector: AiInspectorConfig,
    pub insecure_trigger_names: Vec<String>,
    pub unaccepted_risk_trigger_names: Vec<String>,
}

Configuration for the terminal emulator Aligned with par-tui-term naming conventions for consistency

Fields

cols: usize

Number of columns in the terminal

rows: usize

Number of rows in the terminal

font_size: f32

Font size in points

font_family: String

Font family name (regular/normal weight)

font_family_bold: Option<String>

Bold font family name (optional, defaults to font_family)

font_family_italic: Option<String>

Italic font family name (optional, defaults to font_family)

font_family_bold_italic: Option<String>

Bold italic font family name (optional, defaults to font_family)

font_ranges: Vec<FontRange>

Custom font mappings for specific Unicode ranges Format: Vec of (start_codepoint, end_codepoint, font_family_name) Example: [(0x4E00, 0x9FFF, “Noto Sans CJK SC”)] for CJK Unified Ideographs

line_spacing: f32

Line height multiplier (1.0 = default/tight, 1.2 = comfortable, 1.5 = spacious)

char_spacing: f32

Character width multiplier (1.0 = default, values < 1.0 = narrow, values > 1.0 = wide)

enable_text_shaping: bool

Enable text shaping for ligatures and complex scripts When enabled, uses HarfBuzz for proper ligature, emoji, and complex script rendering

enable_ligatures: bool

Enable ligatures (requires enable_text_shaping)

enable_kerning: bool

Enable kerning adjustments (requires enable_text_shaping)

font_rendering: FontRenderingConfig

Font rendering quality settings: anti-aliasing, hinting, stroke weight, minimum contrast.

Flattened into the top-level YAML so existing config files remain compatible. Access via config.font_rendering.font_antialias, etc.

See FontRenderingConfig for field documentation.

window_title: String

Window title

allow_title_change: bool

Allow applications to change the window title via OSC escape sequences When false, the window title will always be the configured window_title

rendering: RenderingConfig

Frame rate target, VSync mode, GPU preference and output batching.

Flattened into the top-level YAML so existing config files remain compatible. See RenderingConfig.

window: WindowConfig

Window appearance settings (opacity, padding, decorations, blur, etc.) Serialised flat at the top level via #[serde(flatten)] so that existing YAML config files require no changes.

placement: WindowPlacementConfig

Window type, target monitor/Space, resize lock and window numbering.

Flattened into the top-level YAML so existing config files remain compatible. See WindowPlacementConfig.

background: BackgroundConfig

Background image source and how transparency applies to cells and text.

Flattened into the top-level YAML so existing config files remain compatible. See BackgroundConfig.

image: ImageConfig

Inline image scaling and the terminal background source.

Flattened into the top-level YAML so existing config files remain compatible. See ImageConfig.

download_save_location: DownloadSaveLocation

Default save location for downloaded files

last_download_directory: Option<String>

Last used download directory (persisted internally)

shader: GlobalShaderConfig

All custom_shader_* and cursor_shader_* settings.

Flattened into the top-level YAML so existing config files remain compatible.

input: InputConfig

Option/Alt key behaviour, modifier remapping and physical key positions.

Flattened into the top-level YAML so existing config files remain compatible. See InputConfig.

selection: SelectionConfig

Copy-on-select, paste behaviour and dropped-file quoting.

Flattened into the top-level YAML so existing config files remain compatible. See SelectionConfig.

mouse: MouseConfig

Mouse behavior settings (see MouseConfig).

Flattened into the top-level YAML so existing config files remain compatible.

word_selection: WordSelectionConfig

Word boundary characters and pattern-based smart selection rules.

Flattened into the top-level YAML so existing config files remain compatible. See WordSelectionConfig.

copy_mode: CopyModeConfig

Vi-style copy mode settings (see CopyModeConfig).

scrollback: ScrollbackConfig

Scrollback buffer size settings (see ScrollbackConfig).

Flattened into the top-level YAML so existing config files remain compatible.

unicode: UnicodeConfig

Unicode character width and normalization settings (see UnicodeConfig).

cursor: CursorConfig

Cursor appearance and behavior settings (see CursorConfig).

Flattened into the top-level YAML so existing config files remain compatible.

scrollbar: ScrollbarConfig

Scrollbar placement, size, colours, command marks and auto-hide.

Flattened into the top-level YAML so existing config files remain compatible. See ScrollbarConfig.

theme_colors: ThemeColorsConfig

Terminal colour theme and the light/dark pair used by auto dark mode.

Flattened into the top-level YAML so existing config files remain compatible. See ThemeColorsConfig.

screenshot_format: String

File format for screenshots (png, jpeg, svg, html)

shell: ShellConfig

Which shell runs, where it starts, what it is sent, and exit handling.

Flattened into the top-level YAML so existing config files remain compatible. See ShellConfig.

semantic_history: SemanticHistoryConfig

File path/URL detection, the editor that opens them, and link highlighting.

Flattened into the top-level YAML so existing config files remain compatible. See SemanticHistoryConfig.

command_separator: CommandSeparatorConfig

Horizontal separator lines drawn between shell commands.

Flattened into the top-level YAML so existing config files remain compatible. See CommandSeparatorConfig.

clipboard: ClipboardConfig

Clipboard sync event retention and OSC 52 clipboard-set policy.

Flattened into the top-level YAML so existing config files remain compatible. See ClipboardConfig.

max_osc_data_length: usize

Maximum total OSC data length in bytes before a sequence is rejected by the core terminal (QA-012 memory-exhaustion guard). Must be large enough for inline images (iTerm2/Kitty base64) if used.

command_history_max_entries: usize

Maximum number of commands to persist in fuzzy search history

notifications: NotificationConfig

Bell, activity/silence alerts, anti-idle keep-alive, and OSC 9/777 buffer settings (see NotificationConfig).

Flattened into the top-level YAML so existing config files remain compatible.

ssh: SshConfig

SSH discovery and profile-switching settings (see SshConfig).

tabs: TabConfig

Tab style presets, tab bar placement and new-tab behaviour.

Flattened into the top-level YAML so existing config files remain compatible. See TabConfig.

tab_colors: TabBarColorsConfig

Tab bar palette, dimming, sizing and border appearance.

Flattened into the top-level YAML so existing config files remain compatible. See TabBarColorsConfig.

panes: PaneConfig

Split-pane divider, padding, title bar and focus indicator settings.

Flattened into the top-level YAML so existing config files remain compatible. See PaneConfig.

tmux: TmuxConfig

tmux control-mode integration settings.

Flattened into the top-level YAML so existing config files remain compatible. See TmuxConfig.

power: PowerConfig

Shader pausing and reduced frame rates when unfocused or inactive.

Flattened into the top-level YAML so existing config files remain compatible. See PowerConfig.

shader_watch: ShaderWatchConfig

Automatic reloading of shader files when they change on disk.

Flattened into the top-level YAML so existing config files remain compatible. See ShaderWatchConfig.

shader_overrides: ShaderOverridesConfig

Per-file overrides for background and cursor shader settings.

Flattened into the top-level YAML so existing config files remain compatible. See ShaderOverridesConfig.

keybindings: Vec<KeyBinding>

Custom keybindings (checked before built-in shortcuts) Format: key = “CmdOrCtrl+Shift+B”, action = “toggle_background_shader”

custom_action_prefix_key: String

Optional global prefix key for custom actions using per-action prefix chars. Uses the same combo format as normal keybindings (for example “Ctrl+B”). Leave empty to disable prefix-mode custom actions.

integrations: IntegrationConfig

Install prompts and version tracking for bundled integrations.

Flattened into the top-level YAML so existing config files remain compatible. See IntegrationConfig.

updates: UpdateConfig

Configuration for automatic update checking

session_restore: SessionRestoreConfig

Startup arrangement restore, session restore and closed-tab undo.

Flattened into the top-level YAML so existing config files remain compatible. See SessionRestoreConfig.

search: SearchConfig

Terminal search settings (see SearchConfig).

session_log: SessionLogConfig

Automatic session recording: format, destination and redaction.

Flattened into the top-level YAML so existing config files remain compatible. See SessionLogConfig.

log_level: LogLevel

Log level for debug log file output. Controls verbosity of par_term_debug.log in the system temp directory ($TMPDIR on macOS, /tmp on Linux, %TEMP% on Windows). Environment variable RUST_LOG and –log-level CLI flag take precedence.

badge: BadgeConfig

Badge overlay text, colour, font and placement.

Flattened into the top-level YAML so existing config files remain compatible. See BadgeConfig.

status_bar: StatusBarConfig

Status bar settings (see StatusBarConfig).

All status_bar_* fields are flattened here for YAML backward-compatibility.

progress_bar: ProgressBarConfig

Progress bar overlay style, placement and state colours.

Flattened into the top-level YAML so existing config files remain compatible. See ProgressBarConfig.

automation: AutomationConfig

Regex triggers, coprocess definitions and external observer scripts.

Flattened into the top-level YAML so existing config files remain compatible. See AutomationConfig.

snippets: Vec<SnippetConfig>

Text snippets for quick insertion

actions: Vec<CustomActionConfig>

Custom actions (shell commands, text insertion, key sequences)

collapsed_settings_sections: Vec<String>

Settings window section IDs that have been toggled from their default collapse state. Sections default to open unless specified otherwise; IDs in this set invert the default.

dynamic_profile_sources: Vec<DynamicProfileSource>

Remote URLs to fetch profile definitions from

security: SecurityConfig

Environment variable substitution allowlist and plain-HTTP profile fetching.

Flattened into the top-level YAML so existing config files remain compatible. See SecurityConfig.

ai_inspector: AiInspectorConfig

AI Inspector side panel settings (see AiInspectorConfig).

All ai_inspector_* fields are flattened here for YAML backward-compatibility.

insecure_trigger_names: Vec<String>

Names of triggers that have prompt_before_run: false with dangerous actions (RunCommand or SendText).

Populated by Config::warn_insecure_triggers during config load. The UI reads this list to display a persistent visual warning banner so users are aware of the reduced security posture.

This field is intentionally skipped by serde — it is computed at runtime and never written to or read from the config file.

unaccepted_risk_trigger_names: Vec<String>

Names of triggers with prompt_before_run: false that are missing the explicit i_accept_the_risk: true opt-in.

Dangerous actions for these triggers are blocked at execution time. Users must add i_accept_the_risk: true to each such trigger to permit automatic execution without the confirmation dialog.

This field is intentionally skipped by serde — it is computed at runtime and never written to or read from the config file.

Implementations

impl Config

pub fn generate_snippet_action_keybindings(&mut self)

Generate keybindings for snippets and actions that have keybindings configured.

This method adds or updates keybindings for snippets and actions in the keybindings list, using the format snippet:<id> for snippets and action:<id> for actions. If a keybinding for a snippet/action already exists, it will be updated with the new key.

impl Config

pub fn validate_config_path( path: &Path, expected_base: &Path, ) -> Result<PathBuf, ConfigError>

Validate that path (which must already exist on disk) resolves — via canonicalize — to a location inside expected_base.

Uses std::fs::canonicalize so symlinks are fully resolved before the containment check. Returns the canonical path on success, or a ConfigError::PathTraversal error if the resolved path escapes the expected directory.

Errors

Returns ConfigError::PathTraversal when the canonical path does not start with the canonical expected_base. Returns ConfigError::Io if either path cannot be canonicalized.

pub fn shaders_dir() -> PathBuf

Get the shaders directory path (using XDG convention)

pub fn shader_path(shader_name: &str) -> PathBuf

Get the full path to a shader file.

If shader_name is an absolute path it is returned as-is (the user explicitly chose a location outside the shaders directory).

For relative names the path is resolved under Self::shaders_dir. Any relative name that contains .. components is rejected: the function logs a warning and falls back to returning the shaders directory itself so that callers always receive a valid PathBuf without breaking existing call sites. Use Self::checked_shader_path when you need a hard error instead of a fallback.

pub fn checked_shader_path(shader_name: &str) -> Result<PathBuf, ConfigError>

Get the full path to a shader file, returning an error if the name would escape the shaders directory.

This is a strict variant of Self::shader_path for callers that prefer a hard error over a silent fallback.

Errors

Returns ConfigError::PathTraversal when a relative shader_name contains a .. component. Absolute paths are returned unchanged and are never rejected — the caller is trusted to have vetted them.

pub fn resolve_texture_path(path: &str) -> PathBuf

Resolve a texture path, expanding ~ to home directory and resolving relative paths relative to the shaders directory. Built-in texture IDs are preserved for renderer-side resolution. Returns the expanded path or the original if expansion fails

pub fn shader_channel_paths(&self) -> [Option<PathBuf>; 4]

Get the channel texture paths as an array of Options Returns [channel0, channel1, channel2, channel3] for iChannel0-3

pub fn shader_cubemap_path(&self) -> Option<PathBuf>

Get the cubemap path prefix (resolved) Returns None if not configured, otherwise the resolved path prefix

pub fn get_shader_override(&self, shader_name: &str) -> Option<&ShaderConfig>

Get the user override config for a specific shader (if any)

pub fn get_cursor_shader_override( &self, shader_name: &str, ) -> Option<&CursorShaderConfig>

Get the user override config for a specific cursor shader (if any)

pub fn get_or_create_shader_override( &mut self, shader_name: &str, ) -> &mut ShaderConfig

Get or create a mutable reference to a shader’s config override

pub fn get_or_create_cursor_shader_override( &mut self, shader_name: &str, ) -> &mut CursorShaderConfig

Get or create a mutable reference to a cursor shader’s config override

pub fn remove_shader_override(&mut self, shader_name: &str)

Remove a shader config override (revert to defaults)

pub fn remove_cursor_shader_override(&mut self, shader_name: &str)

Remove a cursor shader config override (revert to defaults)

pub fn should_prompt_shader_install(&self) -> bool

Check if the shaders folder is missing or empty Returns true if user should be prompted to install shaders

pub fn should_prompt_shader_install_versioned( &self, current_version: &str, ) -> bool

Check if shaders should be prompted (version-aware logic)

Arguments

• current_version - The application version (from root crate’s VERSION constant)

impl Config

pub fn load() -> Result<Config, Error>

Load configuration from file or create default

When no config file exists, a default one is written to disk and returned.

Errors

Returns an error if the config file resolves outside the config directory (a redirected symlink), if it cannot be read, if it is not valid YAML for the Config schema, or — on the first-run path — if writing the default config fails.

pub fn save(&self) -> Result<(), Error>

Save configuration to file

SEC-008/SEC-021: written through crate::atomic_save, which stages the write in a sibling 0600 temp file, fsyncs it, renames it over the real config and then fsyncs the directory. This used to be an inline temp-and-rename with no fsync, which still lost the file on a power cut: the rename can reach disk before the data it points at.

Errors

Returns an error if the config directory cannot be created, if the config cannot be serialized to YAML, or if writing, syncing or renaming the temp file fails.

pub fn config_path() -> PathBuf

Get the configuration file path.

Always Config::config_dir plus config.yaml. These two used to resolve the directory independently, which meant any change to one silently desynchronised the other.

pub fn config_dir() -> PathBuf

Get the configuration directory path.

On Unix this honours XDG_CONFIG_HOME, falling back to ~/.config/par-term. On Windows it is %APPDATA%\par-term; the XDG variables are a freedesktop convention and are deliberately not consulted there.

Only XDG_CONFIG_HOME is read. XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME and XDG_RUNTIME_DIR are not honoured — par-term keeps all of its state under the config directory. See ENH-008.

pub fn shell_integration_dir() -> PathBuf

Get the shell integration directory (same as config dir)

pub fn logs_dir(&self) -> PathBuf

Resolve the session logs directory path, expanding a leading ~/.

QA-029: this is a pure path resolver and does not create the directory. It used to create_dir_all as a side effect, which meant the settings window created a directory just by rendering — including a directory per keystroke while the user typed a new path into the “Log directory” field, and at the process umask rather than the 0o700 that SEC-010 requires of a directory holding session logs.

The two callers that actually write logs (Tab::toggle_session_logging and the auto-log path in Tab::new) already create the directory themselves and then chmod it to 0o700, so nothing is lost by removing the side effect here.

pub fn resolve_tmux_path(&self) -> String

Resolve the tmux executable path at runtime. If the configured path is absolute and exists, use it. If it’s “tmux” (the default), search PATH and common installation locations. This handles cases where PATH may be incomplete (e.g., app launched from Finder).

pub fn with_title(self, title: impl Into<String>) -> Config

Set the window title

pub fn should_prompt_shell_integration(&self, current_version: &str) -> bool

Check if shell integration should be prompted

Arguments

• current_version - The application version (from root crate’s VERSION constant)

pub fn should_prompt_integrations(&self, current_version: &str) -> bool

Check if either integration should be prompted

Arguments

• current_version - The application version (from root crate’s VERSION constant)

pub fn get_effective_startup_directory(&self) -> Option<String>

Get the effective startup directory based on configuration mode.

Priority:

1. Legacy working_directory if set (backward compatibility)
2. Based on startup_directory_mode:
   • Home: Returns user’s home directory
   • Previous: Returns last_working_directory if valid, else home
   • Custom: Returns startup_directory if set and valid, else home

Returns None if the effective directory doesn’t exist (caller should fall back to default).

pub fn state_file_path() -> PathBuf

Get the state file path for storing session state (like last working directory)

pub fn save_last_working_directory( &mut self, directory: &str, ) -> Result<(), Error>

Save the last working directory to state file

Updates self.last_working_directory and persists it to state.yaml, so the value survives across sessions.

SEC-021: written through crate::atomic_save at mode 0o600. The previous inline temp-and-rename had neither an fsync nor a mode, so the path the user was last working in was world-readable.

Errors

Returns an error if the state directory cannot be created, if the state cannot be serialized to YAML, or if writing, syncing or renaming the temp file fails. The in-memory field is updated before any of these can fail.

pub fn load_last_working_directory(&mut self)

Load the last working directory from state file

pub fn get_pane_background( &self, index: usize, ) -> Option<(String, BackgroundImageMode, f32, f32)>

Get per-pane background config for a given pane index, if configured Returns (image_path, mode, opacity, darken) tuple for easy conversion to runtime type

impl Config

pub fn apply_tab_style(&mut self)

Apply tab style preset, overwriting the tab bar color/size fields.

This is called when the user changes tab_style in settings. The Dark style corresponds to the existing defaults and does nothing.

pub fn load_theme(&self) -> Theme

Load theme configuration

An unrecognized theme name falls back to the default theme; the fallback is logged so a typo in the config does not silently produce the wrong colors.

pub fn apply_system_theme(&mut self, is_dark: bool) -> bool

Apply system theme if auto_dark_mode is enabled. Returns true if the theme was changed.

pub fn apply_system_tab_style(&mut self, is_dark: bool) -> bool

Apply tab style based on system theme when tab_style is Automatic. Returns true if the style was applied.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Config

fn default() -> Config

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Config

fn deserialize<__D>( __deserializer: __D, ) -> Result<Config, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Config

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.