Luau scripting

Afterglow uses Luau API version 1. The typed declarations define helper signatures, events, snapshots and results. Installed declarations are in share/afterglow/api/afterglow.d.luau. The examples are in the source repository, in examples/scripts and examples/packages.

Install a script

Copy a .luau file into scripts/ beside the active configuration file. The usual directory is ~/.config/afterglow/scripts/. A script can handle terminal events and add commands. Run a command with aglow run <id> <command>, from the command palette, from the context menu, with a key or with afterglow ctl action. A command that a script marks remote can also run from a remote host, with aglow run in an afterglow ssh session. It can also run with aglow run in a pane of a mux session of another host. Set Scripts.enabled=false to disable scripting. See packages for modules, dependencies and saved state.

A script file can have at most 1 MiB. Afterglow does not load a larger file. Files that end in .d.luau are type declarations. Afterglow does not load them. Afterglow parses each script file alone before it loads it, so a syntax error names the line of the file. A symbolic link that points to nothing shows as failed in afterglow ctl scripts. When its target appears in a directory that exists, the script loads. When the directory of the target does not exist yet, the script loads at the next change in the scripts directory.

The script ID is metadata.id, or the file name without .luau. It has 1 to 64 letters, digits, _ and -, and must not start with -. A script with an ID that breaks this rule does not load. afterglow ctl scripts shows the error. metadata.name is the name that afterglow ctl scripts shows. The default is the script ID. Afterglow also reads afterglow/scripts in each system data directory, such as /usr/share/afterglow/scripts. The directories have this priority, from low to high:

  1. The system data directories, in the reverse of their XDG order.
  2. ~/.local/share/afterglow/scripts.
  3. scripts/ beside the active configuration file.

When two scripts have the same ID, the script in the higher-priority directory loads. In one directory, a package wins over a single file with the same ID. Of two files in one directory with the same ID, the file whose name sorts last loads. afterglow ctl scripts lists the other script with the status superseded.

The VM has no direct file or process API. Installed scripts are trusted local code. They can request file reads and process launches through host effects. The VM sandbox does not prevent those explicit operations.

Wait for results

afterglow.await(effect) applies an effect and waits for its result in the same handler. It returns the result data. On failure, it returns nil and the error. The third value is the complete result event.

function script.run_command(command, ev)
if not ev.pane then return nil end
local name = afterglow.await(afterglow.prompt(ev.pane, "Branch name"))
if not name then return nil end -- the dialog was canceled
local switched, err = afterglow.await(afterglow.exec("switch", {"git", "switch", "-c", name.text}, {cwd = ev.pane.cwd}))
if not switched then return afterglow.notify("Branch", err.message, ev.pane) end
return afterglow.set_title(ev.pane, name.text)
end

Local variables keep their values across each wait. The handler returns its effects when it finishes, as a handler without waits does. Other handlers run while a handler waits. ev.terminal keeps the snapshot from the handler’s start. The result event contains a new terminal snapshot.

afterglow.await_all(effects) applies up to 16 effects in order and waits for all of them. It returns their result events in the same order. Each event has ok, data and error. Use it to run processes or queries together. The list must have only the keys 1 to n, with no nil entries. A list with a gap or another key, such as the n of table.pack, causes an error.

local results = afterglow.await_all({
afterglow.exec("branch", {"git", "branch", "--show-current"}, {cwd = ev.pane.cwd}),
afterglow.exec("commit", {"git", "rev-parse", "--short", "HEAD"}, {cwd = ev.pane.cwd}),
})
local branch = if results[1].ok then results[1].data.stdout else nil

afterglow.sleep(ms) waits from 0 to 600,000 milliseconds. A sleep is not an effect for the effect budget, but its result counts toward the result limits. A loop that sleeps for less than about 8 ms reaches the limit of 128 results each second.

Every handler can wait, except migrate and on_unload. A handler runs as a coroutine that only afterglow.await resumes. coroutine.resume and coroutine.close refuse a handler’s coroutine, also when a script keeps it from coroutine.running. Module code that runs at load time cannot wait. A wait inside a coroutine that the script creates is an error.

Each part of a handler between waits has the time limit of the handler type. An event handler has 20 ms for each part. A command has 100 ms for each part. A script can have 16 waiting handlers, 48 effects that they wait for and 16 sleeps. Another wait returns the error code busy. The busy result event has ok, kind, request_id, data and error, but no terminal. An error after a wait counts as a handler failure. Awaited results count toward the result limits. Exception: the result of an afterglow.output or afterglow.output_error with text to a run with a client is not counted each second (see command limits). Replacement, removal or disable discards waiting handlers. They do not continue.

The shell-region picker waits for four results in one command. The project navigator runs its project searches together with await_all.

Effects and results

Helpers create effects. Return an effect or a list of effects from a handler to apply them. Use afterglow.await when the handler needs the result. afterglow.request(id, effect) requests an on_result callback instead. Request IDs must contain 1 to 64 UTF-16 units. Use different IDs for requests that require separate tracking. IDs that start with afterglow.await: are reserved for afterglow.await. Afterglow refuses an effect with such an ID that afterglow.await did not give. The effect gets no result. The exec and read_file helpers use the task name as the request ID. So their results also reach on_result when you do not wait for them.

A helper that takes a pane uses the event’s pane when the pane is nil. Some events have no pane: on_load, on_unload, on_config_changed, and a command that runs without a pane. on_timer, on_file_changed and results also have no pane when the handler that started them had none. The typed declarations mark the other events whose pane can be nil. In these events, such an effect fails with invalid_effect. Give a pane explicitly, for example ev.terminal.active_pane.

function script.run_command(command, ev)
if ev.pane then
return afterglow.request("workspace", afterglow.split(ev.pane, "right"))
end
end
function script.on_result(ev)
if ev.request_id ~= "workspace" then return nil end
if not ev.ok then return afterglow.log(ev.error.message) end
return afterglow.set_title(ev.data.pane, "Workspace")
end
Result fieldMeaning
request_idCaller-supplied request ID
kindOperation type
okSuccess flag
dataOperation-specific values
terminalNew terminal snapshot
paneInitiating event’s pane, when available
errorError code and message, on failure

Common errors are invalid_effect, no_pane, rate_limited, operation_failed, busy, cancelled and unavailable. The output effects of a command also give no_run (see the handler). Direct creation effects return data.pane, pane_id, tab_id and window_id. Other effects return an empty data table unless their reference specifies other fields.

Afterglow queues results for the originating script instance after it applies the operation. The result records the operation at application time. Its snapshot can already show that a new pane has closed. Later effects validate the ID again.

Success confirms operation acceptance or application. For a generic action, it does not confirm that a process or a dialog finished. action cannot run a script command (script:<id>.<command>). Such an action fails. action also cannot run end_script_key_mode and cancel_overlay. These are the ways out for the user, and they end the key mode or the overlay of any owner. A script ends its own key mode with end_key_mode. action fails while a prompt or a script dialog is open in the window. A generic action runs in the pane’s tab, and shows that tab first. close_tab, rename_tab, move_tab_left, move_tab_right and detach_tab act on the pane’s tab and do not show it, as the tab menu does. close_tab asks first when a program runs in the tab and Terminal.confirmClose is on. With Mux.onClose at detach, closing the last tab of a mux session asks nothing about the programs of the session (see MUX.md). The same is true in a window that a project opened into its session, and while Afterglow quits. In these windows, close of the last pane and close_tab of the last tab leave the programs of the session running. exec, select, prompt and overlay deliver their results when the process or the dialog finishes. open_project for a project that opens into a mux session delivers its result when the window of the session opens. In the window of a mux session, split, new_tab and detach_tab deliver their results when the pane shows (see launch options). This is also true for move_pane to new-window, and for move_pane into the window of another session. Use direct creation helpers when you need a returned pane ID.

copy fails when the text is longer than 4,194,304 UTF-16 units. Afterglow does not cut it. notify cuts its title to 256 UTF-16 units and its body to 2,048. set_title cuts the title to 256 UTF-16 units. send_text fails with operation_failed when the program has exited, or when 32 MiB of input waits for the program already. open_url opens only http, https and mailto URLs. Another scheme fails. open_url also fails when the desktop cannot take the request. Success does not confirm that a program opened the URL. These failures return operation_failed.

Values that go to Afterglow

Afterglow converts the values that a handler returns, and the fields of its effects, in these steps:

Luau valueAfterglow value
nil, a function, a coroutine, userdataNothing: the field is absent
A boolean, a stringThe same. Bytes that are not UTF-8 become U+FFFD
A whole number of at most 2^53An integer. Other numbers stay numbers with a fraction
A table whose # is more than 0A list of the values 1 to #t. Its other keys are dropped
Another tableAn object. Number keys become strings, such as "1.5". Boolean and table keys are dropped
A table that is in itself, or below 32 levels of tablesNothing, at that place

An empty table is an object with no keys. A helper that expects a list also takes it. The # of a table with a nil gap is not certain. Do not put nil in a list, except in a list of effects that a handler returns. The limits on values and text in a returned table are in execution limits.

Replacement, removal or disable cancels outstanding results. An unchanged script keeps its VM and pending results during reload. Effect lists execute in order. They are not transactions. A nil entry in a returned list is skipped. An effect with a malformed request ID is refused and not applied. It receives no result.

Execution limits

LimitValueAt the limit
VM memory16 MiBThe call fails
Module code at load time1,000 msThe script does not load
Event handler, on_result, on_unload20 msThe call fails
Command, package on_load and migrate100 msThe call fails
Handler failures in a row5The script is disabled
on_timer and on_file_changed calls64 each secondAfterglow drops the call
Other event handler calls (see the notes)64 each secondAfterglow drops the call
Effects in one returned list64No effect applies
Values in a returned table, nested tables included262,144The call fails. A handler that waits for these effects stops
Text in a returned table, each use of a string counted again64 MiBThe call fails. A handler that waits for these effects stops
Applied effects20 each secondrate_limited
Applied dock effects60 each secondrate_limited
Structural effects3 each 10 secondsrate_limited
Queued results128The script is disabled
Result delivery, except output that went out (see the notes)128 each secondThe script is disabled
Waiting handlers16busy
Effects that waiting handlers wait for48busy
Effects in one await_all16An error in the handler
Sleeps at once16busy
Delay of one sleep0 to 600,000 msinvalid_effect
Handler time of one script, Scripts.cpuBudget250 ms in each second. 10 to 1,000 msAfterglow drops or delays the calls (see CPU time)
Log message2,048 charactersAfterglow cuts the message

A list with more than 64 effects applies nothing and causes an error. A disabled script stays disabled until its source or package configuration changes. Turning scripting off and on again also loads it again. Refused operations also count toward result limits. Only effects with a request ID, or that a handler waits for, get results. The result limits are more than the effect limit and the dock limit together. So the results of the effects that those two limits let through cannot disable a script. Requested sleep, cancel, end_key_mode, undock, output, output_error and exit effects are outside both limits, and their results add to the count. The result of an output or output_error with text, to a run with a client, is not counted each second. Scripts.commandOutputLimit and Scripts.commandTimeout bound it. An output with empty text writes nothing, so its result counts. A run with no client drops its stdout at once, so the result of its output counts too. A run from the palette, a key, the menu or afterglow ctl action has no client. Thus such a run that waits for each of more than 128 lines in a second disables its script. Wait for each line only when ev.source is shell or remote. Do not wait for each line when ev.source is control, because afterglow ctl action also starts runs with that source. on_load, on_key, on_dock_click, on_dock_hover and on_dock_layout calls do not count toward a handler call limit. run_command calls do not count either. The command limits bound them. The start, end and cancel calls of on_dock_drag do not count either. An on_dock_click from an accessibility client’s press counts, because a client can press without a limit. on_dock_wheel calls count, because a touchpad can send many in a second. The move calls of on_dock_drag count, because a fast drag crosses many cells in a second. The next move or the end tells the item and the cell that a dropped move would have told. Timers and watchers have their own limit, so events cannot use it up. A dropped one-shot timer does not fire again. A repeating timer fires at its next interval. A dropped on_file_changed call is not sent again. The next change to the file sends a new one. A dropped on_dock_wheel call is not sent again. Its steps are lost. dock effects have their own limit and do not count toward the effect limit. Structural effects create, close or move panes, tabs or windows. They are split, new_tab, new_window, close, move_pane, detach_tab, open_directory and open_project. move_tab and the move_tab_left and move_tab_right actions change the order of the tabs. They are not structural. Generic actions that do the same use the same structural budget.

Afterglow keeps a broken source file from running again. It loads the file again only after the file changes.

CPU time

Scripts.cpuBudget is the handler time that one script can use in each second. The default is 250 ms. Afterglow adds the time of each part of each call in the last second. This includes events, results, the parts after each wait, on_unload, and the cleanup of a run that ended. When a script has used its budget, these steps occur:

  1. Afterglow drops the events that count toward a handler call limit, such as on_title, on_focus, on_dock_wheel and the move calls of on_dock_drag. dropped_callbacks counts them.
  2. The other calls wait until the script has time again, in the order that they came. delayed_callbacks counts them.
  3. When 256 calls wait, Afterglow disables the script.

These calls wait:

  • Results, also the results that resume a handler after afterglow.await or afterglow.sleep.
  • on_timer and on_file_changed. A one-shot timer and a file change do not come again, so the CPU budget does not drop their calls. A repeating timer or a watcher has one call that waits for CPU time, at most. A tick or a change that comes while that call waits gives its event to the call, and adds no call. dropped_callbacks counts the tick or the change. So the call that waits gets the newest event, and a watcher’s exists is that of the last change. When the script cancels the timer or the watcher while its call waits, the call does not run.
  • on_key, and the clicks, hovers, layouts and the start, end and cancel calls of dock events.
  • The start of a command run, and the cleanup of a run that ended.
  • An event that comes after the script has time again, but before the calls that wait have run. It runs after them, with a new snapshot.

A command run that waits to start is live. Scripts.commandTimeout counts the wait. Each second in which a call had to wait counts. After 5 such seconds, each less than 3 seconds after the one before, Afterglow disables the script. A dropped event does not count. So a program that changes its title very fast does not disable a script whose on_title uses the budget: Afterglow drops the extra on_title calls. But when such a script also has a call that waits, for example a key in a key mode, that second counts. cpu_ms in the diagnostics is the handler time of the last second.

An effect can cause an event: set_title causes on_title, focus causes on_focus, and a split causes on_pane_created. A handler that replies to its own event, or two scripts that reply to the events of each other, run without end. The limits above slow such a loop. They do not stop it. Compare the new value with the last one before you reply.

Terminal state

Each handler receives ev.terminal, a version 1 metadata snapshot. It contains windows, tabs, panes, active_window, active_tab and active_pane. It does not contain terminal text. Changing the snapshot does not change the terminal. Afterglow captures the snapshot before dispatch. A queued event can describe an earlier command than the snapshot. ev.state in on_status remains the program status string. When a program clears its last status, or the terminal resets, ev.state is idle and ev.text is empty.

RecordFields
Windowid, focused, active_tab, active_pane, project, project_directory, overview, session, session_host, cols, rows
Tabid, window, index, title, active, active_pane
Paneid, window, tab_id, tab, title, cwd, command, cols, rows, focused, context

session is the mux session that the window shows, else empty. session_host is the ssh destination of its daemon, empty for this computer.

cwd is the local directory that the shell reported last, or the working directory of the pane’s foreground process. It is "" when it is not known. For a session pane of a mux session, cwd is only the directory that the shell reported. Afterglow does not ask the mux daemon for it, because scripts read every pane often (see MUX.md). Afterglow ignores a reported directory that names another host, such as the directory of an ssh session. A reported path without a host is used when that path exists on this machine.

A window’s cols and rows are the cells of the terminal font that fit in the complete window. A top or bottom window area that shows is cols cells wide. A pane’s cols and rows are the cells of its text, without the areas of the pane.

A tab is active when its window selects it. Each unfocused window keeps its selected tab and pane. Top-level active IDs are zero when no Afterglow window has keyboard focus. Pane, tab and window IDs exist only during the process lifetime. tab_id remains stable during tab reordering. pane.tab and the tab field of the pane object are zero-based positions.

Closed-pane events retain id, tab_id and window. The closed pane is absent from the live snapshot. Use these IDs to update surviving panes in the affected tab.

afterglow.panes(state, scope, anchor) filters an existing snapshot. Scope is all, pane, tab or window. The default is all. Another scope causes an error in the handler. The anchor can be a pane record or ID. Without an anchor, the helper uses the globally active objects. A missing anchor ID gives no matches, in every scope.

function script.run_command(command, ev)
local panes = afterglow.panes(ev.terminal, "tab", ev.pane)
return afterglow.log("This tab has " .. #panes .. " panes")
end

Events and lifecycle

Pane events include on_pane_created, on_pane_closed, on_pane_moved, on_focus, on_bell and on_title. Other events are on_status, on_command_started, on_command_finished, on_user_var, on_context and on_tab_switch. These events contain the applicable pane and terminal snapshot. on_command_started and on_command_finished report the commands that a pane’s shell runs, through shell integration. They are not the script commands. The events of docked areas are on_dock_click, on_dock_hover, on_dock_wheel, on_dock_drag and on_dock_layout (see docked areas).

A split’s on_pane_created also contains split_from, the pane it split from, and edge. edge is the side the two panes share: 1 left, 2 top, 3 right or 4 bottom. on_tab_switch contains from_tab, to_tab and direction, 1 toward a tab on the right and -1 toward one on the left. Its pane is the new tab’s focused pane. on_pane_moved runs when a pane moves to another split, tab or window. A swap or a rotation of the panes in a tab does not send it. A tab that moves to another place in its window sends on_pane_moved for each of its panes. The tabs that the move puts at another index send it for each of their panes too. A pane of a mux session that moves to a new window goes to a new session, and gets a new pane ID. The script then gets on_pane_closed and on_pane_created, not on_pane_moved (see MUX.md).

A pane of a mux session has two IDs. ev.pane, the snapshot and the effects use the pane ID of the window, as for other panes. aglow run --pane N, afterglow ctl --session and AFTERGLOW_PANE_ID use the pane ID of the daemon. When the window of a session closes, the script gets on_pane_closed for its panes, also when the session keeps running. The next window that shows the session gives them new pane IDs, and the script gets on_pane_created. Thus state that a script keeps by pane ID does not follow the pane to the next window. A window that shows a session while a command runs in a pane gets the start of the command from the daemon. The script then gets on_command_started when the window shows the pane, and on_command_finished when the command ends.

on_user_var runs when a variable of a pane changes. A program sets a variable with iTerm2’s SetUserVar (OSC 1337). afterglow ctl set-user-var, and the variables of a launch, set one too. Setting the same value again sends no event. A pane keeps its variables until it closes, at most 256 of them. A new variable after that is ignored. A program can set a title or a variable faster than Afterglow delivers the events. on_title and on_user_var then get the newest value, and the values in between are skipped. Do not use user variables to send a sequence of messages.

run_command(command, ev) handles the script’s commands. on_load, on_unload and on_config_changed handle lifecycle changes. Handlers and metadata must be fields of the table that the script returns. Afterglow does not read them through a metatable. on_config_changed runs after the Afterglow configuration changes. It has no pane. A change to a package’s own config.json replaces the package instance instead. A single-file script’s on_load has the 20 ms event limit. A package’s on_load has 100 ms.

on_timer and on_file_changed contain the task name. They receive the pane of the handler that started the task, when that handler had one. Effects without a pane then go to that pane.

A broken replacement keeps the last working instance. Successful replacement, removal, disable or five handler failures in a row cancel tasks and remove UI contributions. on_result and on_unload have the 20 ms event limit. on_unload can return state_write and log effects. They apply before the instance goes. Other effects from on_unload fail with invalid_effect, and no effect of on_unload gets a result. When a package changes, the new instance loads before the old instance’s on_unload runs. A state_write from that on_unload then gives the new instance a revision conflict at its next write. Read the state again after a conflict. When the new instance migrates the state, Afterglow writes the migrated state before the old instance’s on_unload runs. The state_write of that on_unload then fails with a revision conflict, and its value is lost. Write the state when it changes, not only in on_unload. A handler that continues after afterglow.await keeps the limit of its handler type.

Tasks

Task names are strings of 1 to 64 UTF-16 units, and belong to one script instance. Limits are 16 active tasks for each script and 128 in total. Reusing an active name returns busy. afterglow.cancel(name) cancels the owned timer, watcher or job. A one-shot timer stays active until its on_timer call starts. A cancel before that stops the call, also when the call waits for CPU time.

EffectBehavior
timer(name, delay_ms, repeat_ms?)Calls on_timer with ev.name
exec(name, argv, options?)Starts an asynchronous process and returns a result with the task name
read_file(name, path, options?)Reads a regular file asynchronously and returns text and truncated
watch_file(name, path)Monitors an existing regular file and calls on_file_changed

A script that has 16 active tasks, or a total of 128 active tasks, gets rate_limited.

Timer fieldRange
delay_ms1 to 3,600,000 ms. afterglow.timer requires it
repeat_ms0 for one callback, or 250 to 3,600,000 ms

The next interval starts when the handler returns or first waits for a result. So an on_timer that waits for a result can still wait when the next tick comes. Waiting handlers then collect until waits return busy. For slow work, use a single timer and start it again at the end of the handler. When the call of on_timer waits for CPU time, the next interval starts at once. A tick that comes while that call waits for CPU time adds no call (see CPU time). Watcher events contain name, path and exists. Watchers handle atomic file replacement and combine changes within 250 ms.

read_file and watch_file need an absolute path of at most 4,096 characters. Process options include cwd, env, timeout_ms and max_bytes. cwd must be an absolute path. Without cwd, the process runs in the working directory of Afterglow. A command name without / is found in the PATH of the child environment, which env can change. Relative PATH entries start from the process working directory. A command that is not found gives spawn_failed. argv has 1 to 64 arguments of at most 4,096 characters each. argv can also be a string. The string is then the program alone, with no arguments. Afterglow does not split it at spaces and does not use a shell. Each entry of the argv list must be a string. Another value, such as a number, refuses the effect with invalid_effect. A task name that is not a string of 1 to 64 UTF-16 units also refuses the effect with invalid_effect. File reads accept the timeout and byte-limit options. Timeout defaults to 30,000 ms and cannot exceed 600,000 ms. The output limit defaults to 65,536 bytes and cannot exceed 1 MiB. At most eight file reads run together, for all scripts. One script can have four of them. Another read gets busy at once. A read from a file system that does not answer keeps its place until the read returns, also after its timeout_ms. Special files are not permitted.

Normal process results contain stdout, stderr, exit_code and truncated. Errors include spawn_failed, process_failed, timeout, output_limit, cancelled and io_error. Exceeding the combined stdout/stderr limit stops the job. On output_limit, the third value of afterglow.await has data with stdout, stderr and truncated. On process_failed, that data also has exit_code. timeout and cancelled return no output. When the process ends, Afterglow stops the other processes of its process group. Timeout, cancellation and unload also stop the process group. Afterglow discards callbacks for retired instances.

Native UI

Wait for the result of select(pane, title, items) or prompt(pane, title, initial_text?) with afterglow.await. You can also wrap the effect with afterglow.request. Selectors accept 1 to 500 unique {id, title} items and provide fuzzy filtering. An item without a title shows its id. Selection results contain id and title. Prompt results contain text. Escape, pane closure or window closure cancels a dialog. A second dialog in the same window returns busy. A dialog also returns busy while an overlay has the focus, or when its pane has an overlay. A pane that closed before the dialog opened returns no_pane. Dialogs use the desktop Qt Quick Controls theme.

status(pane, text?, tab_title?) replaces the status label and tab suffix. Empty strings clear these contributions.

TextLimit
Selector item id1 to 64 UTF-16 units
Selector item title512 UTF-16 units
Dialog title512 UTF-16 units
Prompt text4,096 UTF-16 units
status text512 UTF-16 units
status tab suffix128 UTF-16 units
Key mode label160 UTF-16 units

A text over its limit, or a repeated id, refuses the complete effect with invalid_effect.

override(pane, values) replaces the owner’s pane appearance settings. Supported fields are cursorBlink, backgroundOpacity and unfocusedDim. The last two fields accept values from zero to one. The latest script value for each field takes priority over configuration. Removal exposes the next owner’s value or the configured value. An empty table clears the owner’s values. values must be a table. Another value fails with invalid_effect. Unload and pane closure remove all contributions.

Overlays

An overlay runs a program over a pane and returns the result to the script. The program gets a terminal of its own, with the input focus. It takes the place of the pane, or a part of the pane as a popup. The pane under it keeps running, and its program keeps its output. Use an overlay for an interactive picker, such as fzf.

local items = {"alpha", "beta", "gamma"}
local r, _, event = afterglow.await(afterglow.overlay(ev.pane, {"fzf", "--multi"}, {
stdin = table.concat(items, "\n"), cwd = ev.pane.cwd, title = "Pick",
}))
if r and r.exit_code == 0 then
-- The pane as it is now: a program that started during the wait would get the keys.
local pane = afterglow.panes(event.terminal, "pane", ev.pane)[1]
if not pane or pane.command ~= "" then return nil end
-- One quoted word for each choice, with no line break: the user presses Enter.
local words = {}
for line in string.gmatch(r.stdout, "[^\n]+") do
table.insert(words, "'" .. string.gsub(line, "'", "'\\''") .. "'")
end
return afterglow.send_text(pane, table.concat(words, " "))
end

ev.pane is the pane at the start of the handler. Read the pane again from the terminal of the result event before you type. Do not type the output of the program as it is. A line break runs the command line. fzf --multi writes one line for each choice, so each choice would run as a command. A control character in a name, such as Ctrl+D, acts as a key. The fzf picker package does not list such names.

overlay(pane, command, options?) takes the program and its arguments as exec does: a list of 1 to 64 strings of at most 4,096 characters each, or a string that names the program alone.

OptionBehavior
stdinText for the program’s standard input, at most 4 MiB of UTF-8. Without it, the program reads the terminal.
captureWhere stdout of the result comes from. "stdout" (the default) reads the program’s standard output. "file" sets AFTERGLOW_RESULT to the path of a new file that only you can read, and reads that file. "none" returns an empty stdout.
cwdThe program’s directory: an absolute path, ~, or a path that starts with ~/. Another value refuses the effect. An empty value, or no cwd, starts the program in $HOME. When the directory does not exist on this machine, for example a path that a remote shell reported, the program starts in $HOME.
envVariables for the program, as for exec. false removes a variable. At most 256 variables and 64 KiB of names and values.
titleShows as the pane’s title while the overlay runs, at most 512 UTF-16 units. It follows the character rules of command text (see Commands): no control character, line break or bidirectional control. A border shows it in its top edge.
width, heightMake the overlay a popup. Give a whole number of cells, such as 60, or a percentage of the pane’s grid as a string, such as "80%". The border is part of the size. A side that you do not give takes the whole grid. Without width and height, the overlay takes the whole pane.
positionWhere a popup is in the pane: "center" (the default), "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left" or "bottom-right". It has no effect without width or height.
bordertrue puts a line one cell wide around the program’s grid, in the popup border color, with the title in its top edge. true without width and height makes a popup that fills the pane. The default is true for a popup and false for a full-pane overlay.

An option that is not in this table, or a value of the wrong type, refuses the effect with invalid_effect.

The terminal stays the program’s controlling terminal and its standard error, so the program can draw on /dev/tty. With stdin and capture = "stdout", a program like fzf reads its list from stdin, draws on /dev/tty and writes its choice to stdout. Standard output that is not captured goes to the terminal. The program gets the pane’s AFTERGLOW_PANE_ID, so afterglow ctl in it acts on the pane. It also gets AFTERGLOW_OVERLAY=1. An afterglow ssh in the overlay then gives aglow run on its host the socket of its own session, and the pane keeps that of its own.

Result fieldContent
exit_codeThe program’s exit status. A program that a signal ended gives 128 plus the signal number. It is -1 when Afterglow cannot read the status.
stdoutThe captured output: at most 1 MiB (1,048,576 bytes) of the program’s output, as text. Bytes that are not UTF-8 change to U+FFFD, so the text can be longer than 1 MiB.
truncatedtrue when the output was over 1 MiB and was cut

A non-zero exit status is a result, not an error: fzf exits with 130 at Escape and with 1 when nothing matches.

Error codeCause
invalid_effectThe command or an option breaks a rule above.
rate_limitedThe script has used its effect budget (see execution limits).
no_paneThe pane closed before the overlay opened.
busyAnother item holds the pane or the window: an overlay of the pane, a script dialog, the key mode of another script, a prompt, a confirmation, the command palette or a context menu.
spawn_failedThe program cannot start.
cancelledThe overlay closed before the program exited. The result has no output.

The overlay closes when its program exits. It also closes with cancelled, and its program gets SIGHUP, in these conditions:

  • The pane under it closes.
  • The script stops: a change, a removal, Scripts.enabled=false or a disable.
  • The command run that waits for it ends (see Cancel).
  • The user runs the cancel_overlay action while the pane has the focus. The default key is Ctrl+Shift+Alt+Escape.

The overlay fades in and out over the pane, through the Shaders.overlayTransition pack. The default pack, Overlay Fade, blends the pane and the overlay. Animation.overlayCurve and Animation.overlayDuration set the fade. For a popup, the pack blends the pane and the pane as it shows with the popup. That is the pane around the popup, darkened by Colors.popupDim, then the popup’s border if it has one, then the popup. With an empty Shaders.overlayTransition, the overlay shows and goes at once. The overlay takes the focus. When its pane is in another tab, that tab shows. When several overlays open at the same time, the last one has the focus. When the overlay closes, the focus goes back to the pane. The pane’s cursor and view stay where they were.

SituationBehavior
The pane overview, other tabsThe overlay shows where its pane is.
A moved pane, a detached tabThe overlay goes with its pane. A pane of a mux session that moves to a new window goes to a new session, and its overlay ends (see MUX.md).
Zoom, a resizeThey apply to both. The program of a full-pane overlay gets the pane’s new size. Afterglow places a popup again, and its program gets the popup’s new size.
Saved projectsOverlays are not saved.
Copy mode, search, hints, paste, the mouseThey act on the overlay while its pane has the focus.
Assistive technologyIt reads the overlay’s text in place of the pane’s. For a popup, the text is at the place of the popup’s grid.
The pane’s shadersThe pane’s layer and pane shaders draw the overlay, and the pane around a popup. During a fade, they draw the pane and the overlay both.

An overlay is not a pane of its own. afterglow ctl ls and the terminal snapshot do not show it. Effects that take a pane ID, such as send_text and read_text, act on the pane under the overlay, not on its program. afterglow ctl overlay opens an overlay from a shell (see CONTROL.md). The fzf picker package uses fzf when it is installed, and the select dialog when it is not.

Popups

A popup is an overlay that takes a part of the pane. The pane stays visible around it and keeps running. The pane’s docks stay where they are.

local r = afterglow.await(afterglow.overlay(ev.pane, "fzf", {
stdin = table.concat(items, "\n"), title = "Pick", width = "80%", height = "60%",
}))
RuleValue
WidthA whole number from 1 to 10,000 cells, or "1%" to "100%" of the pane’s columns
HeightA whole number from 1 to 10,000 cells, or "1%" to "100%" of the pane’s rows
LargestThe pane’s grid. A larger size is cut to the grid.
Smallest2 columns by 1 row inside the border, or the whole pane when the pane is smaller. A smaller size grows to this.
BorderOne cell on each side. When the pane has fewer than 4 columns or fewer than 3 rows, the popup has no border.
TitleIn the top edge of the border. A title that does not fit is cut with an ellipsis. A popup 6 cells wide or less shows no title.

Each layout places the popup again: a resize, a zoom, a font change or a dock that comes or goes. The program gets SIGWINCH when its size changes.

Colors.popupDim darkens the pane around the popup. The popup and its border keep their colors. The border has the popup border color: the popupBorder of the theme, or Colors.popupBorder without a theme (see Themes). The pane’s cursor shows as unfocused, because the popup has the keyboard. The mouse acts in the popup, in the popup’s own cells. The history scrollbar is at the right edge of the popup. A click outside the popup gives its pane the focus. It does not reach a program, and it does not close the popup. A scroll or a drop outside the popup does nothing.

Commands

A command is an operation that a script adds. You can run it from a shell, from the command palette, from the context menu, with a key, with afterglow ctl action or from a remote host. A single-file script declares its commands in metadata.commands. A package declares them in package.json (see packages).

local script = {}
script.metadata = {
commands = {
open = { summary = "Open a project directory", usage = "DIR [LAYOUT]", palette = "Open project…" },
list = { summary = "Print the saved projects" },
import = { summary = "Add projects from a list on stdin", stdin = true },
},
}
FieldRule
Command name1 to 64 characters: letters, digits, _ and -. It must not start with -, because aglow run reads that as an option
summaryRequired, not blank. At most 512 UTF-16 units
usageOptional. The arguments, for help. At most 512 UTF-16 units
paletteOptional palette title, not blank, at most 512 UTF-16 units. Commands that have it appear in the palette and the context menu
stdinOptional boolean, default false. Only a command with stdin = true gets the client’s stdin
remoteOptional boolean, default false. Only a command with remote = true can run from a remote host (see remote commands)
Commands of a scriptAt most 64, with those of set_commands

summary, usage and palette must not contain control characters, such as a line break or a tab. They also must not contain the line separator (U+2028), the paragraph separator (U+2029) or a bidirectional control. The bidirectional controls are U+061C, U+200E, U+200F, U+202A to U+202E and U+2066 to U+2069. The command palette shows <id>: <palette>, for example marker: Mark this pane. The Scripts submenu of the context menu shows the palette title alone.

A manifest that breaks a rule stops the script from loading. afterglow ctl scripts shows the error. A script with commands must have a run_command function.

Run a command

SourceHow
shellaglow run <id> <command> [ARGS…] (see control)
paletteThe command palette, for a command with palette
menuThe Scripts submenu of the context menu, for a command with palette
keyscript:<id>.<command> in Keybinds.bindings, in a key table or in a key sequence (see input)
controlafterglow ctl action script:<id>.<command>, or a SCRIPT.COMMAND call of the commands target. Also afterglow ctl --session NAME action script:<id>.<command>, only while a window shows the session. A client in a mux session of another host cannot run a command this way (see MUX.md).
remoteaglow run <id> <command> [ARGS…] on a remote host, for a command with remote. The client runs in an afterglow ssh session, or in a pane of a mux session of another host.

The palette, a key, the menu and afterglow ctl action pass no arguments. The handler of a command with palette must work with args empty. afterglow ctl action starts the command and returns at once. aglow run waits for the end of the run.

Treat the input of a remote run as untrusted. Any process of the remote user, and the remote root user, can start the run. That process gives args, cwd and stdin, and gets the output. The handler gets all the panes in ev.terminal. Its effects can act on any pane, not only the pane of the ssh session or of the mux session. An error in the handler counts toward the 5 failures that disable the script, as from any other source. So a remote process that sends bad input again and again can disable the script. Check the input before you use it. Remote runs and local runs share Scripts.commandRunLimit. A remote process can use all the runs of the script.

The handler

run_command(command, ev) handles every command of the script.

ev fieldContent
argsList of strings, at most 256, each at most 4,096 UTF-16 units
cwdThe client’s directory. Else the pane’s directory. Else an empty string, for a run with neither. At most 4,096 UTF-16 units: a run with a longer directory does not start. For a remote run, a directory on the remote host, as text, or an empty string when the client gives none. Do not use it as a local path. An overlay with this cwd starts in $HOME when the directory does not exist on this computer
paneFor a shell run: --pane N, else the pane that runs the shell, else the focused pane. For control, the pane that afterglow ctl names, else the focused pane. For remote, the pane that runs the ssh session, or the pane of the client in a mux session of another host. For other sources, the pane of the palette, key or menu. Only { id } when the pane closed before the run started. nil when there is no pane
stdinAll of the client’s stdin as one string, for a command with stdin = true that runs from the shell or from a remote host. nil for another source. nil also when aglow run reads no stdin: with -n, or when stdin is a terminal. A run with more stdin than Scripts.commandStdinLimit does not start. aglow run refuses stdin that is not UTF-8 text and exits with status 2
source"shell", "palette", "key", "menu", "control" or "remote"
remoteFor remote: { host }, the host of the ssh session as afterglow ssh names it, or the host of the mux session as --ssh names it. 1 to 255 characters with no control characters. nil for another source
runThe run ID, for the output effects
terminalThe terminal snapshot
EffectBehavior
afterglow.output(run, text)Writes text to the client’s stdout. When you wait for it, it returns after the text has gone to the client
afterglow.output_error(run, text)Writes text to the client’s stderr
afterglow.exit(run, code)Sets the exit status, 0 to 255. A run that sets no status exits with 0

run is ev.run, or the event itself. A script can write only to its own runs. Output to a run that has ended, or that is not the script’s, fails with no_run. Exception: the handler of the run itself can still write after the run ends. That output goes nowhere (see cancel). When you wait for output to a run that ends before the client gets the text, the result is cancelled.

The project navigator’s import command reads its stdin.

function script.run_command(command, ev)
if command == "list" then
local projects, err = afterglow.await(afterglow.list_projects())
if not projects then
return { afterglow.output_error(ev, err.message .. "\n"), afterglow.exit(ev, 1) }
end
return afterglow.output(ev, table.concat(projects.names, "\n") .. "\n")
end
end

The end of a run

  • The run ends when the handler returns, also after it waited with afterglow.await.
  • The client then gets the exit status.
  • When the handler fails, the run ends with exit status 1. The error goes to stderr.
  • A failure counts as a handler failure (see execution limits).
  • A run can end inside a returned list, at its output limit or when its client left. The effects after that point do not apply. dropped_effects in the diagnostics counts them.

A run with no client (from the palette, a key, the menu or afterglow ctl action) drops its stdout. When it writes to stderr or ends with a status other than 0, a notification shows on its pane. A run with no pane shows a desktop notification that belongs to no pane. The notification has the palette title of the command, else <id> <command>. It shows the last 2,048 characters of stderr, with their line breaks. These notifications count against Notifications.rateLimit of the pane, or against one limit for all notices without a pane.

Command limits

LimitValuePast the limit
Each part of the handler between waits100 ms. You cannot change itThe run ends with exit status 1
The total time of a run, Scripts.commandTimeout1,000 to 3,600,000 ms. Default 600,000 msThe run ends with exit status 124
Runs of one script at once, Scripts.commandRunLimit1 to 16. Default 16A new run fails with exit status 1 and a message
Stdin, Scripts.commandStdinLimit0 to 4,096 KiB. Default 1,024 KiB. 0 refuses any input that is not emptyThe run does not start. aglow run exits with status 2
UTF-8 bytes of stdout and stderr together, Scripts.commandOutputLimit64 to 262,144 KiB. Default 16,384 KiBThe run ends with exit status 1 and a message

One command can have several runs at once. The runs of one script share its 16 waiting handlers, 48 awaited effects, 16 sleeps and 16 tasks (see execution limits). The output effects and exit are outside the effect budget. Scripts.commandOutputLimit bounds them. A run with no client drops its stdout, so its stdout does not count toward Scripts.commandOutputLimit. Its stderr counts. A change to a limit applies to the runs that start after it.

Scripts.commandTimeout counts all the time of a run. This includes a wait for a task, for a dialog, for an overlay, and for a client that reads its output slowly. It does not include the time that aglow run sends stdin before the run starts. A client that reads its output slowly holds the run back. A wait for afterglow.output then takes longer. The output that waits counts toward Scripts.commandOutputLimit.

Cancel

A run also ends when its client leaves, at a cancel, at the time limit and at the output limit. When its handler waits at that moment, these steps occur:

  1. The dialogs, selectors and overlays that the handler waits for close. The program of an overlay gets SIGHUP. An open_project that the handler waits for does not stop. Its session and its window still open. In the window of a mux session, a split, new_tab or detach_tab does not stop either. The pane still opens or moves. The same is true for a move_pane to new-window or to another session.
  2. The processes (exec) and file reads (read_file) that it waits for stop. Its sleeps stop. Their task names and sleep slots are free again.
  3. The handler resumes once, as from afterglow.await, with nil and the error code cancelled. The error message tells why the run ended.
  4. afterglow.await_all gives the results that came before the end, and cancelled for the others. An effect that applied, but that had no result yet, also gives cancelled.

The handler resumes after the current handler call returns, not during it. The cancelled result events have terminal, and pane when the run has a pane. A result that was not delivered before the run ended does not resume the handler. The handler resumes once, with cancelled.

The handler can then clean up, for example clear a busy flag after a pcall. This part has the 100 ms limit of each part of a command. The cleanup can wait again. Each later part also has the 100 ms limit. Scripts.commandTimeout does not stop the cleanup, because the run has ended. Its waits count toward the 16 waiting handlers of the script until the handler returns. Its afterglow.output, afterglow.output_error and afterglow.exit go nowhere, because the client has its exit status already. They are not errors. Its other effects apply as usual. An error in this part is not a handler failure. It ends the script’s key mode, as every handler error does.

A run also ends when its script stops: a change, a removal, Scripts.enabled=false or a disable. The run then ends with exit status 1, and stderr tells why. A script is disabled after 5 handler failures in a row, after too many results (see execution limits), or when it keeps its CPU budget used (see CPU time). The handlers of a stopped script do not resume.

Commands at runtime

afterglow.set_commands(commands) sets the commands that the script adds while it runs. commands has the shape of metadata.commands: each command name maps to the fields of the table above. The table replaces the commands of the last set_commands. The manifest’s commands stay. An empty table removes the commands of the last set_commands. A name that the manifest has, or a field that breaks a rule, refuses the complete effect.

return afterglow.set_commands({ deploy = { summary = "Deploy the branch", palette = "Deploy" } })

The projects example adds a command for each saved project.

Docked areas

dock(pane, spec) puts a docked area (a dock) of styled text at an edge of the pane’s window, or of the pane. The panes get the space that is left, in whole cells. The shell in each pane gets the new size. The renderer draws the area like a pane, with the terminal font, the palette and the box-drawing and Powerline characters. No shader changes a window area. Each window has its own areas. The same id in another window is a different area. dock acts on the window that holds pane when Afterglow applies the effect. With scope = "pane", the area goes at an edge of the pane itself. See pane areas.

return {
on_focus = function(ev)
return afterglow.dock(ev.pane, {id="bar", edge="top", tab_bar=true, fill=8, lines={{
{text=" main ", fg=0, bg=4, bold=true},
{text="\u{e0b0}", fg=4},
{spacer=true},
{text=" 12:30 ", fg=0, bg=2, item="clock"},
}}})
end,
on_dock_click = function(ev)
return afterglow.log(ev.item .. " " .. ev.button)
end,
}
FieldValue
idRequired. 1 to 32 ASCII letters, digits, - or _. A second dock with the same id replaces the area.
edgeRequired. top, bottom, left or right.
sizeRows for top and bottom, 1 to 8. Columns for left and right, 1 to 80. The default is 1.
tab_bartrue draws a top area in place of the tab bar. The default is false. Only a top area with the window scope can have true.
scopewindow puts the area at an edge of the pane’s window. pane puts it at an edge of the pane. The default is window.
fillA palette index from 0 to 255, or "#rrggbb". It is the background of the complete area. Without it, the area uses the theme’s background. When the background is translucent, the fill has the same opacity as the pane background. A window area follows Window.backgroundOpacity, or the opacity that afterglow ctl set-opacity sets. A pane area follows its pane, also a backgroundOpacity override of a script.
linesA list of lines from the top. A line is a list of runs from the left. Without lines, the area is empty.

A top or bottom area has at most size lines. Lines past the bottom of a left or right area do not show.

Run fieldValue
textThe text. A control character shows as a space. Text past the edge is cut. A wide character that does not fit shows as an empty cell in the colors of its run.
fg, bgA palette index from 0 to 255, or "#rrggbb". Indices 0 to 15 follow the theme.
bold, italic, underlinetrue or false
item1 to 64 characters, with no control characters. A click on the cells of the run sends on_dock_click. on_dock_hover, on_dock_wheel and on_dock_drag name the item under the pointer.
spacertrue makes an empty run that takes the cells the other runs of its line leave. Several spacers share them.

Without fg, a run uses the theme’s foreground color. Without bg, it uses the area’s fill. A spacer cannot have text. A run that takes no cells, such as a run with empty text, cannot be clicked. A field that is not in these tables refuses the effect with invalid_effect. A value of the wrong type or outside its range also refuses the effect with invalid_effect.

on_dock_click goes only to the script that owns the area. Afterglow sends it when a mouse button goes down on a run with an item, or when an accessibility client presses the item.

Event fieldValue
dockThe id of the area
itemThe item of the run
buttonleft, middle or right
windowThe window ID
scopewindow or pane, as in the dock effect
paneFor a window area, the focused pane of the window, if the window has one. For a pane area, the pane of the area.

Other mouse buttons send no event. A click on a run without an item, or on empty cells, does nothing. Accessibility clients see each item as a button. Its press sends the event of a left click. See desktop integration. Clicks and the mouse wheel on an area never reach the panes. A click on a pane area does not focus its pane. The script can return focus(ev.pane) to do that. While the pane overview is open, a window area takes clicks too. A click on an item then sends on_dock_click, and the overview stays open. A pane area gets no clicks while the overview is open (see pane areas). A prompt that is open over the overview takes the click first. An area always reads from left to right. Terminal.bidi does not apply to areas.

on_dock_hover goes to the owner when the item under the pointer changes. It contains dock, scope, window and pane as above, and item when the pointer is on an item. Without item, the pointer has left the items of that area. New text that puts another item under a pointer that does not move also sends the event. When the script removes the area under the pointer with undock, the script gets the event without item first. The pointer is on no item while a prompt, a menu or the command palette is open, and while it is over the search bar. The pointer is also on no item during a drag that started in a pane or on a divider. The same is true for a drag that started on the tab bar, on the scrollbar or in the overview. Keep the cells of an item the same when it shows its hover state. Otherwise the item under the pointer can change again.

on_dock_wheel goes to the owner when the mouse wheel turns over an area. It contains dock, scope, window and pane as above.

Event fieldValue
directionup, down, left or right
stepsThe whole wheel notches, 1 or more. Part of a notch waits for the next event over the same item.
itemThe item under the pointer, when there is one

on_dock_drag goes to the owner when the left mouse button drags an item of an area. The press sends on_dock_click first. The drag starts when the pointer moves the system drag distance from the press. It contains dock, scope, window and pane as above.

Event fieldValue
phasestart when the drag starts, move when a pointer move changes over, col or row, end when the button goes up, cancel when the drag stops in another way
itemThe item that the press was on
overThe item of this area under the pointer, when there is one
col, rowThe cell under the pointer, from 0 at the top left of the area. Outside the area, they are less than 0, or equal to its size or more.

A press and release with no drag sends no on_dock_drag. The drag continues outside the area and outside the window, until the button goes up. The drag gets cancel when the script removes the area with undock. It also gets cancel when the area goes with its pane or window. A drag on a pane area that stops showing gets cancel at the next pointer move or release. A release that Afterglow does not get, such as a release in another window, sends cancel at the next pointer move. New text that puts another item under a pointer that does not move sends no move. The next pointer move or the end has the new over. on_dock_hover continues during the drag.

move_tab(pane, index) moves the pane’s tab to index in its window, and does not show it. index is the index of a tab in the snapshot, from 0. An index that is not a tab of the window fails with operation_failed. An index that is not a whole number of 0 or more is refused with invalid_effect. The index of the tab’s own place succeeds and does nothing. The tab line package uses on_dock_drag and move_tab to drag tabs.

on_dock_layout goes to the owner after Afterglow first places an area, also when the area does not fit. It also goes when the area starts or stops showing, and when its size changes. An undock sends no on_dock_layout. Use the event to lay out the text for the cells that the area has. It contains dock, scope, window and pane as above.

Event fieldValue
showntrue when the area shows
cols, rowsThe cells of the area. Both are 0 when it does not show.

New text in the same place sends no on_dock_layout. A change of the window size, the font or another area can send it. While the window changes size or a divider moves, it can come once in each frame. A script that draws again for each one can get rate_limited at the dock limit. Send the last text again later, as the tab line package does.

tab_menu(pane) opens the tab menu of the pane’s tab, as a right click on the tab bar does. The menu opens at the last click on an item of an area of that window, or at an accessibility client’s press. Each menu uses that position once. A click on another part of the window also clears it. Without a position, the menu opens at the pointer. When the pointer is outside the window, the menu opens at the top left corner. While a prompt, a script dialog or the command palette is open in the window, the result is busy. A menu that is open closes, and the tab menu opens in its place.

Areas on one edge stack inward from the window’s edge, in the order that they were placed. tab_bar areas are the outermost areas on the top edge, where the tab bar is. A top area without tab_bar shows below the tab bar. top and bottom areas take the full width. left and right areas fit between them. A tab_bar area shows for every Window.tabBar value, also in a window with one tab. An area that would leave the panes smaller than 4 columns or 2 rows does not show. Its dock effect still succeeds. New text for an area keeps its place. A change of edge, size or tab_bar puts it last on its edge.

undock(pane, id) removes the area from the pane’s window. When that window has no area with this id, or the pane has closed, undock looks elsewhere. It removes an area whose most recent dock named that pane. When several did, the newest goes. An id that the script has no area for is not an error. If the pane has closed and no such area names it, the result is no_pane. The tab bar shows again when the last tab_bar area is removed. A tab_bar area that does not show leaves the tab bar in place. Successful replacement, removal and disable of the script remove all of its areas. Five handler failures in a row disable the script, so they also remove its areas. When a window closes, its areas close with it.

LimitValueAt the limit
dock effects of one script60 each secondrate_limited
Areas of one script in a window8rate_limited
Areas in a window32rate_limited
Lines of a left or right area256invalid_effect
Runs in a line128invalid_effect
Runs in an area1,024invalid_effect
UTF-8 text and items of an area16,384 bytesinvalid_effect

A new area past a count limit gets rate_limited. Remove an area to make room. New text for an existing area is not refused at the count limits.

The tab line package draws the tab bar of each window as a docked area. A click switches tabs, a middle click closes a tab and a right click opens its tab menu. The package also has a + button, moves through the tabs with the wheel and shows the tab under the pointer. Drag a tab to move it.

Pane areas

A dock with scope = "pane" puts the area at an edge of the pane. The pane’s text gets the space that is left, in whole cells, and its shell gets the new size. The other panes keep their size. Each pane has its own areas. The same id at another pane, or in the window scope, is a different area.

local function title(pane, text)
return afterglow.dock(pane, {id="title", edge="top", scope="pane", fill=8, lines={{
{text=" " .. text .. " ", fg=0, bg=4, item="title"},
}}})
end
return {
on_pane_created = function(ev) return title(ev.pane, "ready") end,
on_command_started = function(ev) return title(ev.pane, ev.command) end,
on_command_finished = function(ev) return title(ev.pane, "ready") end,
}

New text keeps the area in its place, so the pane and its program keep their size. Do not add and remove an area for each command: each change gives the program a new size.

A pane area is part of the pane:

  • It moves and changes size with the pane in split animations.
  • It shows on the pane’s card in the pane overview, in a tab transition and in the frame of a pane that closes.
  • The pane shaders, the text and background layer shaders and the window shaders draw over it, as they draw over the pane’s text.
  • It goes with the pane to another tab or window, and it closes with the pane.
  • A pane of a mux session that moves to a new window goes to a new session, and its areas close. The script gets on_pane_created for the pane in the new window, and can dock them again.

The events of a pane area have scope = "pane", and their pane is the pane of the area. While the pane overview is open, the cards take the pointer: a pane area gets no click, hover, wheel or drag. A pane that a zoom hides shows none of its areas. The layout rules of window areas apply inside the pane. An area that would leave the pane smaller than 4 columns or 2 rows does not show. A pane in a tab that does not show lays out its areas in the last layout of its tab. Its shell gets the new size at once, unless a zoom hides the pane. Window areas are the outermost: they take their space from the window first, and the panes share the rest.

undock(pane, id, "pane") removes the area from the pane. When the pane has closed, its areas are gone, and the result is no_pane.

LimitValueAt the limit
Areas of one script at a pane4rate_limited
Areas at a pane8rate_limited

The other limits of areas apply to pane areas too. Pane areas do not count toward the window limits.

Key modes

key_mode(pane, label?) sends the keys of the pane’s window to the script’s on_key handler. The keys do not reach the shell. The window shows the label. A script needs an on_key handler to start a key mode. One script at a time holds a window’s keyboard. Another script’s request returns busy. A request also returns busy while an overlay of another owner, such as another script or a control client, has the keyboard of the focused pane. In a script’s own key mode, the cancel_overlay key still cancels the overlay of the focused pane. on_key does not get that key.

on_key receives key, text, ctrl, shift, alt, meta and repeat. key is the typed character, such as a or A. Other keys have a name:

Keyskey
EditingEnter, Escape, Tab, Backspace, Delete, Insert, Space
MovementHome, End, PageUp, PageDown, Left, Right, Up, Down
Function keysF1 to F35
Other keysThe lowercase Qt key name, such as menu

A modifier key alone does not reach on_key. It comes with the key that it changes, in ctrl, shift, alt and meta. meta is the Super key. With Keybinds.remapModifiers, these fields are the modifiers that the keys become. With Ctrl, key is the letter, and text is empty. Ignore the keys that the script does not use. end_key_mode() gives the keyboard back. It works also when the effect budget is spent. A handler error, disable, replacement or removal of the script also ends its key mode. The end_script_key_mode keybinding always ends a key mode. The default is Ctrl+Shift+Escape. With Keybinds.remapModifiers, it and cancel_overlay also match the modifiers on the keys. The script does not receive that key. Key releases are not reported.

Pane overview

overview(pane, operation) drives the pane overview of the pane’s window. open opens it from the pane. close closes it and keeps the focus. choose focuses the highlighted pane. open fails with busy while another script holds a key mode. The default operation is open. When the chosen pane is in another tab, that tab shows as the overview closes. overview_move(pane, step) moves the highlight by step cards. step is a whole number from -32 to 32. The default step is 0. overview_move(pane, 0, target) highlights the pane target. target is a pane record or ID. Results contain the overview: open, highlighted and cards. The snapshot’s window records contain the same overview table. cards lists the pane IDs of every tab in tab order while the overview is open, otherwise the panes of the current tab.

Combine these effects with a key mode to replace the overview’s keys. The scripted overview package moves with a, d, w and s, and ships its own overview shader. A key mode that starts while the overview is open ends when the overview closes. This also applies when a click or the keyboard closes the overview, so the next key goes to the shell. A key mode that starts before the overview opens continues.

Pane pulses

pulse(pane, effect, options?) plays an effect over the pane in Shaders.paneEffects. The bundled Phosphor Panes pack draws these effects:

EffectNumberLook
portal1A ring of light that sweeps out
flash2A light at the rim of the pane that fades
shake3The pane shakes

Numbers from 4 to 255 select effects that other packs define. Give an effect as its name, or as a number or a numeric string. A pulse without an effect causes an error in the handler. options.duration_ms sets the time, a whole number of ms from 50 to 10,000. The default is 600 ms. options.color is a palette index from 0 to 255. The default is 4. A new pulse on the same pane replaces the old one. The pulse example flashes failed commands and shakes on the bell.

Launch options

split, new_tab and new_window accept a final LaunchOptions table. cwd sets the working directory. cwd in the options takes priority over the cwd argument of new_tab and new_window. A cwd of ~ or one that starts with ~/ starts in your home directory. Another cwd must be an existing absolute directory. Without cwd, split(pane) and new_tab(pane) start in the directory of pane, as the Window.workingDirectory setting permits. The command is a program name, or a list of the program and its arguments. Each entry must be a string. Another value refuses the effect with invalid_effect. Without a command, or with an empty string, the pane starts the default shell. The tab of new_tab(pane) opens after the tab of pane. env changes inherited environment variables. size sets the new split fraction, greater than zero and less than one. Split directions are left, right, up and down. The default direction is right. Failed launches return errors and remove the incomplete ordinary pane.

In the window of a mux session of another host, split and new_tab start the command on that host. They take no cwd and no env there, and an effect that gives them fails. The new pane starts in the directory of the program of the pane that it opens from, on the host. new_window always opens a window of this computer. See sessions on another host.

In the window of a mux session, the daemon starts the program of split and new_tab while the windows go on responding. The result comes when the pane shows. The pane that it opens from can close in that time, or the split can lose its room. Then the new pane opens in a tab.

move_pane(pane, target?, placement?) moves a pane. The default placement is right. left, right, up and down place the pane beside target, which is required. new-tab puts the pane in a new tab after the tab of target, in the window of target. Without a target, the tab is in the pane’s own window. new-window takes no target. A beside placement without a target, or new-window with one, is refused with invalid_effect. new-tab into the pane’s own window is refused with operation_failed for a pane that is alone in its tab. This is true with a target in that window too. In the window of a mux session, new-window and detach_tab move the pane or the tab to a new session. A pane of a mux session that moves into the window of another session of the same daemon joins that session. The pane then gets a new pane ID (see MUX.md). The result comes when the window of the other session shows the pane. Until then, the pane stays in its window and takes input, and another move of it fails. A target pane that has closed fails with no_pane. Some moves of panes of mux sessions fail with operation_failed. A pane of a session cannot move into a window that shows no session. It cannot move into the window of a session of another host or of another mux daemon either. A pane of another window cannot move into the window of a session. The only pane of a session, and a tab that holds all the panes of a session, cannot go to a new window. See move panes and tabs and move a pane to another session.

Set an environment value to false to remove it. Other environment values must be strings. exec accepts the same env map. Each map permits 256 variables and 64 KiB of combined names and values.

return afterglow.split(ev.pane, "left", {"fish"}, {
cwd = "/tmp", size = 0.3,
env = {PROJECT_MODE = "development", INHERITED_SECRET = false},
})

Text and semantic regions

read_text accepts these scopes:

ScopeText
screenThe rows that show
scrollbackThe history and the rows of the main screen, also while the alternate screen shows
last-outputThe output of the last command (the default)
first-output-on-screenThe output of the first command whose output shows
last-visited-outputThe output of the last command that a prompt jump or a command output click went to
selectionThe selection

Another scope fails with invalid_effect. The output scopes need shell integration (OSC 133). While the alternate screen shows, first-output-on-screen is not available. Results contain text, available and truncated. max_bytes limits UTF-8 output to 1 to 1,048,576 bytes (1 MiB). The default is 65,536 bytes. Another value is refused with invalid_effect. A missing selection or unavailable region returns available=false. In a pane of a mux session, scrollback, last-output and the regions of semantic_regions are not available while their rows still come from the daemon. They return available=false, and a script can read again later. So does the last output of a session pane while its rows still come from the mux daemon, right after a window shows the session. For a session pane that you cannot see, read_text, read_region and semantic_regions first get the screen and the history from the mux daemon. They do this also for a pane that shows again before its screen came. They wait at most 5 seconds for them (see MUX.md).

semantic_regions returns up to 1,024 retained shell regions in chronological order. Afterglow removes a region when a line deletion, a scroll in a scroll region or a resize destroys its start row. It also removes a completed region when its end row is destroyed. A start row that leaves the history does not remove the region (see start_trimmed). Each region has these fields:

FieldMeaning
idStable string ID
kindprompt, input or output
start, finishStart position and exclusive end position
openRegion is still receiving content
availableRegion still has retained text
start_trimmedHistory removal deleted the region start
exit_codeOptional completed-output exit status

Positions use stable row IDs encoded as strings and zero-based columns. Strings avoid Luau number precision loss. read_region(pane, region, max_bytes) returns logical text for the region with the ID region. Unknown or fully discarded IDs are unavailable. Reset does not reuse IDs. Retained positions follow text reflow.

Set Scripts.allowReadText=false to deny these queries. While it is false, afterglow.action also fails for copy, paste, select_all, show_last_output, show_first_output_on_screen and show_last_visited_output. It controls terminal queries, not operating-system file or process access. A command run can have a client: aglow run, or a SCRIPT.COMMAND call of the commands target. In the handler of such a run, these queries also need Control.allowReadText. The output of the command can take the text to a process outside the window (see control). Other handlers do not need Control.allowReadText.

The client of a remote run is any process of the remote user, or the remote root user. In the handler of a remote run, these queries also need Control.allowRemoteReadText. It is off by default. While it is off, these queries fail with operation_failed. While it is off, only the handler of a remote run can write to the run with afterglow.output and afterglow.output_error. The output of another handler fails with operation_failed. These gates cover the queries and the direct output of other handlers. They do not cover other paths. A script can still give text to a run in other ways, for example in a module variable that another handler sets, or with exec and copy. The same is true for Control.allowReadText and a run with a local client. Install only scripts that you trust with the text of your panes.

The shell-region picker copies a selected region, with a 256 KiB limit. The build inspector finds compiler locations in command output. The creation example uses launch options and a returned pane ID.

Diagnostics

afterglow ctl scripts reports id, name, path, version, status, error, disabled_reason, calls, handler_errors, effect_errors and last_error. error is the load error of a failed or last-good script, why a script is superseded, or why a script is disabled. Else it is empty. For a disabled script whose file changed and does not load, error is the load error. disabled_reason always tells why a script was disabled. version is the package version. A single-file script has none. status is active, disabled, last-good, failed or superseded. An error in a package module names the module file and its line. Timing fields are last_call_ms, max_call_ms and total_call_ms. cpu_ms is the handler time of the last second, which Scripts.cpuBudget limits. Diagnostics also count what Afterglow dropped. dropped_callbacks counts calls dropped at either handler call limit, or at the CPU budget. It also counts the ticks and the changes that a waiting call of a timer or a watcher takes in. delayed_callbacks counts calls that waited for the CPU budget. dropped_effects and dropped_results count dropped effects and results. waiting is the number of handlers that wait for a result. Timing measures VM handler execution, not asynchronous process duration. Deferred failures count when the operation completes. A dialog that the user closes, and an effect that ends with its run, give cancelled. They do not count as effect errors. Unchanged instances retain counters. Replacements start new counters.

Helpers

The typed declarations give the same signatures with comments.

HelperSignature
afterglow.panes(state: State, scope: ("all" | "pane" | "tab" | "window")?, anchor: PaneRef?) -> { Pane }
afterglow.await(effect: Effect) -> (any?, OperationError?, ResultEvent)
afterglow.await_all(effects: { Effect }) -> { ResultEvent }
afterglow.sleep(ms: number) -> (any?, OperationError?, ResultEvent)
afterglow.request(id: string, effect: Effect) -> Effect
afterglow.key_mode(pane: PaneRef, label: string?) -> Effect
afterglow.end_key_mode() -> Effect
afterglow.overview(pane: PaneRef, operation: ("open" | "close" | "choose")?) -> Effect
afterglow.overview_move(pane: PaneRef, step: number?, target: PaneRef?) -> Effect
afterglow.pulse(pane: PaneRef, effect: ("portal" | "flash" | "shake" | string | number), options: { duration_ms: number?, color: number? }?) -> Effect
afterglow.semantic_regions(pane: PaneRef) -> Effect
afterglow.read_region(pane: PaneRef, region: string, max_bytes: number?) -> Effect
afterglow.read_text(pane: PaneRef, scope: ("screen" | "scrollback" | "last-output" | "first-output-on-screen" | "last-visited-output" | "selection")?, max_bytes: number?) -> Effect
afterglow.state_read() -> Effect
afterglow.state_write(value: {[string]: any}, revision: number) -> Effect
afterglow.open_directory(cwd: string, layout: string?) -> Effect
afterglow.save_project(pane: PaneRef, name: string, overwrite: boolean?) -> Effect
afterglow.open_project(name: string, newInstance: boolean?) -> Effect
afterglow.list_projects() -> Effect
afterglow.move_pane(pane: PaneRef, target: PaneRef?, placement: ("left" | "right" | "up" | "down" | "new-tab" | "new-window")?) -> Effect
afterglow.detach_tab(pane: PaneRef) -> Effect
afterglow.timer(name: string, delay_ms: number, repeat_ms: number?) -> Effect
afterglow.cancel(name: string) -> Effect
afterglow.exec(name: string, command: string | { string }, options: { env: {[string]: string | false}?, cwd: string?, timeout_ms: number?, max_bytes: number? }?) -> Effect
afterglow.read_file(name: string, path: string, options: { timeout_ms: number?, max_bytes: number? }?) -> Effect
afterglow.watch_file(name: string, path: string) -> Effect
afterglow.set_commands(commands: {[string]: CommandSpec}) -> Effect
afterglow.output(run: string | CommandEvent, text: string) -> Effect
afterglow.output_error(run: string | CommandEvent, text: string) -> Effect
afterglow.exit(run: string | CommandEvent, code: number) -> Effect
afterglow.select(pane: PaneRef, title: string, items: { { id: string, title: string? } }) -> Effect
afterglow.prompt(pane: PaneRef, title: string, text: string?) -> Effect
afterglow.overlay(pane: PaneRef, command: string | { string }, options: OverlayOptions?) -> Effect
afterglow.status(pane: PaneRef, text: string?, tab_title: string?) -> Effect
afterglow.override(pane: PaneRef, values: { cursorBlink: boolean?, backgroundOpacity: number?, unfocusedDim: number? }) -> Effect
afterglow.dock(pane: PaneRef, spec: DockSpec) -> Effect
afterglow.undock(pane: PaneRef, id: string, scope: ("window" | "pane")?) -> Effect
afterglow.send_text(pane: PaneRef, text: string) -> Effect
afterglow.notify(title: string, body: string?, pane: PaneRef?) -> Effect
afterglow.split(pane: PaneRef, direction: ("right" | "down" | "left" | "up")?, command: (string | { string })?, options: LaunchOptions?) -> Effect
afterglow.new_tab(pane: PaneRef, cwd: string?, command: (string | { string })?, options: LaunchOptions?) -> Effect
afterglow.new_window(cwd: string?, command: (string | { string })?, options: LaunchOptions?) -> Effect
afterglow.focus(pane: PaneRef) -> Effect
afterglow.close(pane: PaneRef) -> Effect
afterglow.set_title(pane: PaneRef, title: string) -> Effect
afterglow.copy(text: string) -> Effect
afterglow.open_url(url: string) -> Effect
afterglow.action(pane: PaneRef, name: string) -> Effect
afterglow.tab_menu(pane: PaneRef) -> Effect
afterglow.move_tab(pane: PaneRef, index: number) -> Effect
afterglow.shaders(pane: PaneRef) -> Effect
afterglow.scene_state(pane: PaneRef) -> Effect
afterglow.shader_presets(pane: PaneRef, instance: string) -> Effect
afterglow.shader_preset(pane: PaneRef, instance: string, preset: string, scope: ("pane" | "tab" | "window")?, transition: ShaderTransition?) -> Effect
afterglow.save_shader_preset(pane: PaneRef, instance: string, name: string) -> Effect
afterglow.shader_parameters(pane: PaneRef, instance: string, values: {[string]: number | boolean | string}, scope: ("pane" | "tab" | "window")?, transition: ShaderTransition?) -> Effect
afterglow.signal(pane: PaneRef, channel: number, value: number?) -> Effect
afterglow.signals(pane: PaneRef, values: { SignalValue }, scope: ("pane" | "tab" | "window")?) -> Effect
afterglow.log(message: string) -> Effect

Mirrored from docs/SCRIPTING.md in the Afterglow repository.