@spec begin_synchronized_output() :: :ok

Enables synchronized output mode for flicker-free rendering.

When enabled, terminal output is buffered until explicitly flushed, preventing screen flickering during complex updates.

Examples

AdvancedFeatures.begin_synchronized_output()
# ... perform multiple terminal updates ...
AdvancedFeatures.end_synchronized_output()

@spec clear_progress() :: String.t()

Clears any taskbar/dock progress previously set via report_progress/2.

@spec create_hyperlink(String.t(), url(), hyperlink_params()) :: String.t()

Creates a clickable hyperlink using OSC 8 escape sequences.

Parameters

• text - The text to display as clickable
• url - The URL to open when clicked
• options - Additional hyperlink options

Examples

iex> AdvancedFeatures.create_hyperlink("Visit GitHub", "https://github.com")
"\e]8;;https://github.com\e\\Visit GitHub\e]8;;\e\\"

iex> AdvancedFeatures.create_hyperlink("Click me", "https://example.com", %{
...>   id: "link1",
...>   tooltip: "Opens example.com"
...> })

@spec create_hyperlinks([{String.t(), url()}], hyperlink_params()) :: [String.t()]

Creates multiple hyperlinks with shared parameters.

Examples

links = [
  {"GitHub", "https://github.com"},
  {"GitLab", "https://gitlab.com"}
]

AdvancedFeatures.create_hyperlinks(links, %{tooltip: "Git repository"})

@spec disable_bracketed_paste() :: :ok

Disables bracketed paste mode.

@spec disable_focus_events() :: :ok

Disables terminal focus events.

@spec enable_bracketed_paste() :: :ok

Enables enhanced bracketed paste mode.

This prevents pasted content from being interpreted as terminal commands and provides better handling of multiline pastes.

@spec enable_focus_events() :: :ok

Enables terminal focus events.

When enabled, the terminal will send escape sequences when it gains or loses focus, allowing applications to respond to focus changes.

@spec end_synchronized_output() :: :ok

Disables synchronized output mode and flushes buffered content.

@spec get_terminal_capabilities() :: %{
  hyperlinks: boolean(),
  synchronized_output: boolean(),
  focus_events: boolean(),
  bracketed_paste: boolean(),
  window_manipulation: boolean(),
  terminal_type: String.t(),
  term_variable: String.t()
}

Gets current terminal capabilities and features.

@spec get_window_size() ::
  {:ok, {non_neg_integer(), non_neg_integer()}} | {:error, term()}

Gets the current terminal window size.

Returns {:ok, {width, height}} or {:error, reason}.

@spec notify(String.t()) :: String.t()

Sends a desktop notification using OSC 9.

Examples

iex> AdvancedFeatures.notify("Build finished")
"\e]9;Build finished\e\\"

@spec parse_focus_event(binary()) :: {:focus_in} | {:focus_out} | {:unknown, binary()}

Parses focus event sequences.

Returns:

• {:focus_in} - Terminal gained focus
• {:focus_out} - Terminal lost focus
• {:unknown, data} - Unrecognized sequence

@spec parse_paste_event(binary()) ::
  {:paste_start} | {:paste_end} | {:paste_content, binary()}

Parses bracketed paste sequences.

Returns:

• {:paste_start} - Beginning of pasted content
• {:paste_end} - End of pasted content
• {:paste_content, data} - Pasted content

@spec report_progress(progress_state(), 0..100) :: String.t()

Reports progress on the host terminal's dock/taskbar icon using OSC 9;4.

state is one of :remove, :set, :error, :indeterminate, or :warning. value is the progress percentage (0-100), ignored by most terminals for :remove and :indeterminate.

Examples

iex> AdvancedFeatures.report_progress(:set, 42)
"\e]9;4;1;42\e\\"

iex> AdvancedFeatures.report_progress(:remove)
"\e]9;4;0;0\e\\"

@spec set_pointer_shape(String.t()) :: String.t()

Sets the mouse pointer shape using OSC 22.

shape is a CSS-style cursor keyword, e.g. "default", "text", "pointer", "wait", "crosshair".

Examples

iex> AdvancedFeatures.set_pointer_shape("pointer")
"\e]22;pointer\e\\"

@spec set_window_title(String.t()) :: :ok

Sets the terminal window title.

@spec supports_hyperlinks?() :: boolean()

Detects if the current terminal supports OSC 8 hyperlinks.

@spec supports_synchronized_output?() :: boolean()

Detects if the terminal supports synchronized output.

@spec with_synchronized_output((-> any())) :: any()

Executes a function with synchronized output enabled.

Examples

AdvancedFeatures.with_synchronized_output(fn ->
  Log.info("Line 1")
  Log.info("Line 2")
  # These will appear atomically
end)