Contexts are groups of commands that can be combined to determine which commands are relevant or valid for the page's current state. By default, if a command does not have a context, it is in the PluginBase.constants.contexts.Normal context where most default commands live. LipSurf is always in one or more contexts.

Example use cases:

  • Allowing certain commands only in certain situations.

    • e.g. When we're watching a Netflix show, we want play, pause etc. available. When we're browsing the Netflix catalogue, we don't want player commands, but we do want things like next page. To handle this, we could watch for URL changes, and if we're on a page to watch a show, we could use prependContext('Player Controls') to add the context that the player controls are under.


    Because we used prependContext the default commands will still work, because the Normal context remains in the context list.

  • Limiting which commands are valid.

    • e.g. In the "Dictation" context, we don't want youtube to take us to, we want it to literally write "youtube" where we're composing our text. In this case we don't want the "Normal" context, so we would enterContext(["Dictation"]) to replace the current context with only "Dictation".

Contexts are per-tab. So the user may be in a dictation mode in one tab, and normal mode in another.


  • Make sure to remove a context if it's specific to the plugin in the plugin's destroy function.

Context Order

Context order matters. If there are two search * commands, the one from the context earlier in the context list gets chosen.

Designating a Context

A context is "created" by designating:

Context can be manipulated programmatically using:

Commands Outside of Normal Mode

By default, a command is in the PluginBase.constants.contexts.Normal (default) context unless normal: false is specified or a context is specified that doesn't include PluginBase.constants.contexts.Normal.