glide #

• glide.ctx #

glide.ctx.mode: GlideMode #

The currently active mode.

glide.ctx.url: URL #

The URL of the currently focused tab.

glide.ctx.os #

The operating system Glide is running on.

glide.ctx.is_editing(): Promise<boolean> #

Whether or not the currently focused element is editable.

This includes but is not limited to <textarea>, <input>, contenteditable=true.

• glide.o: glide.Options #

Set browser-wide options.

glide.o.mapping_timeout: number #

How long to wait until cancelling a partial keymapping execution.

For example, glide.keymaps.set('insert', 'jj', 'mode_change normal'), after pressing j once, this option determines how long the delay should be until the j key is considered fully pressed and the mapping sequence is reset.

note: this only applies in insert mode.

@default 200

glide.o.yank_highlight: glide.RGBString #

Color used to briefly highlight text when it's yanked.

@example "#ff6b35" // Orange highlight

@default "#edc73b"

glide.o.yank_highlight_time: number #

How long, in milliseconds, to highlight the selection for when it's yanked.

@default 150

glide.o.which_key_delay: number #

The delay, in milliseconds, before showing the which key UI.

@default 300

glide.o.jumplist_max_entries: number #

The maximum number of entries to include in the jumplist, i.e. how far back in history will the jumplist store.

@default 100

glide.o.hint_size: string #

The font size of the hint label, directly corresponds to the font-size property.

@default "11px"

• glide.bo: Partial<glide.Options> #

Set buffer specific options.

This has the exact same API as glide.o.

• glide.options #

glide.options.get(name): glide.Options[Name] #

Returns either a buffer-specific option, or the global version. In that order

• glide.env #

glide.env.get(name): string | null #

Get the value of an environment variable.

If it does not exist null is returned.

glide.env.set(name, value): void #

Set the value of an environment variable.

glide.env.delete(name): string | null #

Remove an environment variable.

Does not error if the environment variable did not already exist.

Returns the value of the deleted environment variable, if it did not exist null is returned.

• glide.process #

glide.process.spawn(command, args?, opts?): Promise<glide.Process> #

Spawn a new process. The given command can either be the name of a binary in the PATH or an absolute path to a binary file.

If the process exits with a non-zero code, an error will be thrown, you can disable this check with { check_exit_code: false }.

const proc = await glide.process.spawn("kitty", [
  "nvim",
  "glide.ts",
], { cwd: "~/.dotfiles/glide" });
console.log("opened kitty with pid", proc.pid);

  
  

glide.process.execute(command, args?, opts?): Promise<glide.CompletedProcess> #

Spawn a new process and wait for it to exit.

See glide.process.spawn for more information.

• glide.prefs #

glide.prefs.set(name, value): void #

Set a preference. This is an alternative to prefs.js / about:config so that all customisation can be represented in a single glide.ts file.

warning: this function is expected to be called at the top-level of your config, there is no guarantee that calling glide.prefs.set in callbacks will result in the pref being properly applied everywhere.

warning: there is also no guarantee that these settings will be applied when first loaded, sometimes a restart is required.

glide.prefs.get(name): string | number | boolean | undefined #

Get the value of a pref.

If the pref is not defined, then undefined is returned.

glide.prefs.clear(name): void #

Reset the pref value back to its default.

• glide.g: GlideGlobals #

Equivalent to vim.g.

You can also store arbitrary data here in a typesafe fashion with:

declare global {
  interface GlideGlobals {
    my_prop?: boolean;
  }
}
glide.g.my_prop = true;

  
  

glide.g.mapleader: string #

The key notation that any <leader> mapping matches against.

For example, a mapping defined with <leader>r would be matched when Space + r is pressed.

@default "<Space>"

• glide.tabs #

glide.tabs.active(): Promise<glide.TabWithID> #

Returns the active tab for the currently focused window.

This is equivalent to:

const tab = await browser.tabs.query({
  active: true,
  currentWindow: true,
})[0];

  
  

But with additional error handling for invalid states.

glide.tabs.get_first(query): Promise<Browser.Tabs.Tab | undefined> #

Find the first tab matching the given query filter.

This is the same API as browser.tabs.get, but returns the first tab instead of an Array.

• glide.excmds #

glide.excmds.execute(cmd): Promise<void> #

Execute an excmd, this is the same as typing :cmd --args.

glide.excmds.create(info, fn): Excmd #

Create a new excmd.

e.g.

const cmd = glide.excmds.create({
  name: "my_excmd",
  description: "...",
}, () => {
  // ...
});
declare global {
  interface ExcmdRegistry {
    my_excmd: typeof cmd;
  }
}

  
  

• glide.content #

glide.content.execute(func, opts): Promise<ReturnType<F>> #

Execute a function in the content process for the given tab.

The given function will be stringified before being sent across processes, which means it cannot capture any outside variables.

If you need to pass some context into the function, use args, e.g.

function set_body_border_style(css: string) {
  document.body.style.setProperty("border", css);
}
await glide.content.execute(set_body_border_style, {
  tab_id,
  args: ["20px dotted pink"],
});

  
  

Note: all args must be JSON serialisable.

• glide.keymaps #

glide.keymaps.set(modes, lhs, rhs, opts?): void #

glide.keymaps.del(modes, lhs, opts?): void #

Remove the mapping of {lhs} for the {modes} where the map command applies.

The mapping may remain defined for other modes where it applies.

glide.keymaps.list(modes?): glide.Keymap[] #

List all global key mappings.

If a key mapping is defined for multiple modes, multiple entries will be returned for each mode.

• glide.hints #

glide.hints.show(opts?): void #

Find and show hints for "clickable" elements in the content frame.

An optional action() function can be passed that will be invoked when a hint is selected.

• glide.buf #

glide.buf.prefs #

glide.buf.prefs.set(name, value): void #

Set a preference for the current buffer. When navigating to a new buffer, the pref will be reset to the previous value.

See glide.prefs.set for more information.

glide.buf.keymaps #

glide.buf.keymaps.set(modes, lhs, rhs, opts?): void #

glide.buf.keymaps.del(modes, lhs, opts?): void #

Remove the mapping of {lhs} for the {modes} where the map command applies.

The mapping may remain defined for other modes where it applies.

• glide.keys #

glide.keys.send(keyseq, opts?): Promise<void> #

Send a key sequence to the browser, simulating physical key presses.

The key sequence can include multiple regular keys, special keys, and modifiers.

For example:

// Send a simple key sequence, each char is sent separately
await glide.keys.send("hello");

// Send with modifiers, results in two events
// - { ctrlKey: true, key: 'a' }
// - { ctrlKey: true, key: 'c' }
await glide.keys.send("<C-a><C-c>");

  
  

glide.keys.next(): Promise<glide.KeyEvent> #

Returns a Promise that resolves to a glide.KeyEvent when the next key is pressed.

This also prevents the key input from being processed further and does not invoke any associated mappings.

If you want to inspect keys without preventing any default behaviour, you can use glide.keys.next_passthrough.

Note: there can only be one Promise registered at any given time.

Note: this does not include modifier keys by themselves, e.g. just pressing ctrl will not resolve until another key is pressed, e.g. <C-a>.

glide.keys.next_passthrough(): Promise<glide.KeyEvent> #

Returns a Promise that resolves to a glide.KeyEvent when the next key is pressed.

Unlike glide.keys.next, this does not prevent key events from passing through into their original behaviour.

Note: this does not include modifier keys by themselves, e.g. just pressing ctrl will not resolve until another key is pressed, e.g. <C-a>.

glide.keys.next_str(): Promise<string> #

Returns a Promise that resolves to a string representation of the key, when the next key is pressed.

This also prevents the key input from being processed further and does not invoke any associated mappings.

If you want to inspect keys without preventing any default behaviour, you can use glide.keys.next_passthrough.

Note: there can only be one Promise registered at any given time.

Note: this does not include modifier keys by themselves, e.g. just pressing ctrl will not resolve until another key is pressed, e.g. <C-a>.

@example 'd'

@example '<C-l>'

glide.keys.parse(key_notation): glide.KeyNotation #

Parse a single key notation into a structured object.

This normalises special keys to be consistent but otherwise the parsed object only containers modifiers that were in the input string.

Shifted keys are not special cased, the returned key is whatever was given in in the input.

@example "<Space>" -> { key: "<Space>" }

@example "H" -> { key: "H" }

@example "<S-h>" -> { key: "h", shift: true }

@example "<S-H>" -> { key: "H", shift: true }

@example "<C-S-a>" -> { key: "A", shift: true, ctrl: true }

@example "<M-a>" -> { key: "a", meta: true }

• glide.unstable #

glide.unstable.include(path): Promise<void> #

Include another file as part of your config. The given file is evluated as if it was just another Glide config file.

note: this only supports files that are directly relative to your config file, for example, "shared.glide.ts" or "shared/glide.ts" would work but "../shared/glide.ts" will not.

note: this function cannot be called from inside a file that has been included itself, i.e. nested glide.unstable.include calls are not supported.

@example glide.unstable.include("shared.glide.ts")

• glide.path #

glide.path.cwd #

glide.path.home_dir #

glide.path.temp_dir #

glide.path.profile_dir #

glide.path.join(...parts): string #

Join all arguments together and normalize the resulting path.

Throws an error on non-relative paths.

• glide.fs #

glide.fs.read(path, encoding): Promise<string> #

Read the file at the given path.

Relative paths are resolved relative to the config directory, if no config directory is defined then relative paths are not allowed.

The encoding must currently be set to "utf8" as that is the only supported encoding.

@example await glide.fs.read("github.css", "utf8");

glide.fs.write(path, contents): Promise<void> #

Write to the file at the given path.

Relative paths are resolved relative to the config directory, if no config directory is defined then relative paths are not allowed.

If the path has parent directories that do not exist, they will be created.

The contents are written in utf8.

@example await glide.fs.write("github.css", ".copilot { display: none !important }");

glide.fs.exists(path): Promise<boolean> #

Determine if the given path exists.

Relative paths are resolved relative to the config directory, if no config directory is defined then relative paths are not allowed.

@example await glide.fs.exists(\${glide.path.home_dir}/.config/foo`);`

glide.fs.stat(path): Promise<glide.FileInfo> #

Obtain information about a file, such as size, modification dates, etc.

Relative paths are resolved relative to the config directory, if no config directory is defined then relative paths are not allowed.

const stat = await glide.fs.stat("userChrome.css");
stat.last_modified; // 1758835015092
stat.type; // "file"

  
  

• glide.messengers #

glide.messengers.create(receiver): glide.ParentMessenger<Messages> #

Create a glide.ParentMessenger that can be used to communicate with the content process.

Communication is currently uni-directional, the content process can communicate with the main process, but not the other way around.

Sending and receiving messages is type safe & determined from the type variable passed to this function. e.g. in the example below, the only message that can be sent is my_message.

// create a messenger and pass in the callback that will be invoked
// when `messenger.send()` is called below
const messenger = glide.messengers.create<
  { my_message: null }
>((message) => {
  switch (message.name) {
    case "my_message": {
      // ...
      break;
    }
  }
});

glide.keymaps.set("normal", "gt", ({ tab_id }) => {
  // note the `messenger.content.execute()` function intead of
  // the typical `glide.content.execute()` function.
  messenger.content.execute((messenger) => {
    document.addEventListener("focusin", (event) => {
      if (event.target.id === "my-element") {
        messenger.send("my_message");
      }
    });
  }, { tab_id });
});

  
  

• glide.modes #

glide.modes.register(mode, opts): void #

Register a custom mode.

note: you must also register it as a type like so:

declare global {
  interface GlideModes {
    leap: "leap";
  }
}
glide.modes.register("leap", { caret: "block" });

  
  

Types #

• glide.SpawnOptions #

cwd?: string;
env?: Record<string, string | null>;
extend_env?: boolean;
success_codes?: number[];
/**
 * If `false`, do not throw an error for non-zero exit codes.
 *
 * @default true
 */
check_exit_code?: boolean;
/**
 * Control where the stderr output is sent.
 *
 * If `"pipe"` then sterr is accessible through `process.stderr`.
 * If `"stdout"` then sterr is mixed with stdout and accessible through `process.stdout`.
 *
 * @default "pipe"
 */
stderr?: "pipe" | "stdout";

  
  

• glide.Process #

pid: number;
/**
 * The process exit code.
 *
 * `null` if it has not exited yet.
 */
exit_code: number | null;
/**
 * A `ReadableStream` of `string`s from the stdout pipe.
 */
stdout: ReadableStream<string>;
/**
 * A `ReadableStream` of `string`s from the stderr pipe.
 *
 * This is `null` if the `stderr: 'stdout'` option was set as the pipe will be forwarded
 * to `stdout` instead.
 */
stderr: ReadableStream<string> | null;
/**
 * Wait for the process to exit.
 */
wait(): Promise<glide.CompletedProcess>;
/**
 * Kill the process.
 *
 * On platforms which support it, the process will be sent a `SIGTERM` signal immediately,
 * so that it has a chance to terminate gracefully, and a `SIGKILL` signal if it hasn't exited
 * within `timeout` milliseconds.
 *
 * @param {integer} [timeout=300]
 *        A timeout, in milliseconds, after which the process will be forcibly killed.
 */
kill(timeout?: number): Promise<glide.CompletedProcess>;

  
  

• glide.CompletedProcess #

Represents a process that has exited.

glide.Process & {
    exit_code: number;
}

  
  

• glide.RGBString: '#${string}' #

• glide.TabWithID #

A web extension tab that is guaranteed to have the id property present.

Omit<Browser.Tabs.Tab, "id"> & {
    id: number;
}

  
  

• glide.KeyEvent #

KeyboardEvent & {
    /**
     * The vim notation of the KeyEvent, e.g.
     *
     * `{ ctrlKey: true, key: 's' }` -> `'<C-s>'`
     */
    glide_key: string;
}

  
  

• glide.KeySendOptions #

/**
 * Send the key event(s) directly through to the builtin Firefox
 * input handler and skip all of the mappings defined in Glide.
 */
skip_mappings?: boolean;

  
  

• glide.KeymapCallback #

(props: glide.KeymapCallbackProps) => void

  
  

• glide.KeymapCallbackProps #

/**
 * The tab that the callback is being executed in.
 */
tab_id: number;

  
  

• glide.HintLocation: "content" | "browser-ui" #

• glide.KeyNotation #

/**
 * @example <leader>
 * @example h
 * @example j
 * @example K
 * @example L
 * @example <Tab>
 */
key: string;

// modifiers
alt: boolean;
ctrl: boolean;
meta: boolean;
shift: boolean;

  
  

• glide.Keymap #

sequence: string[];
lhs: string;
rhs: glide.ExcmdValue;
description: string | undefined;
mode: GlideMode;

  
  

• glide.KeymapOpts #

description?: string | undefined;
/**
 * If `true`, applies the mapping for the current buffer instead of globally.
 *
 * @default {false}
 */
buffer?: boolean;
/**
 * If true, the key sequence will be displayed even after the mapping is executed.
 *
 * This is useful for mappings that are conceptually chained but are not *actually*, e.g. `diw`.
 *
 * @default false
 */
retain_key_display?: boolean;

  
  

• glide.KeymapDeleteOpts #

Pick<glide.KeymapOpts, "buffer">;

  
  

• glide.FileInfo #

type: "file" | "directory" | null;
permissions: number | undefined;
last_accessed: number | undefined;
last_modified: number | undefined;
creation_time: number | undefined;
path: string | undefined;
size: number | undefined;

  
  

DOM #

Helper functions for interacting with the DOM.

note: this is currently only available in the main process, for updating the browser UI itself. it is not available in content processes.

DOM.create_element(tag_name, props?): TagName extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[TagName] : HTMLElement #

Wrapper over document.createElement() providing a more ergonomic API.

Element properties that can be assigned directly can be provided as props:

DOM.create_element("img", { src: "..." });

  
  

You can also pass a children property, which will use .replaceChildren():

DOM.create_element("div", {
  children: [
    "text content",
    DOM.create_element("img", { alt: "hint" }),
  ],
});