@peter.naydenov/shortcuts 4.0.1 → 4.1.0

package/README.md

@@ -22,37 +22,167 @@ Currently existing plugins:
 
 
 
-## Shortcut Description Rules
-The shortcuts definition includes a context name and a set of rules(object). The rules are a set of key-value pairs. The key contains a plugin name and a shortcut name and the value is a function or array of functions, to be executed when the shortcut is triggered (action function).
+## Table of Contents
+1. [Quick Start](#quick-start)
+2. [Concepts](#concepts)
+3. [Constructor Options](#constructor-options)
+4. [Per-Plugin Options](#per-plugin-options)
+5. [Shortcut Description Rules](#shortcut-description-rules)
+6. [Per-Context Setup vs `enablePlugin` Options](#per-context-setup-vs-enableplugin-options)
+7. [Plugin Reference](#plugin-reference)
+   - [Plugin 'key'](#plugin-key-shortcut-descriptions)
+   - [Plugin 'click'](#plugin-click-shortcut-descriptions)
+   - [Plugin 'hover'](#plugin-hover-shortcut-descriptions)
+   - [Plugin 'scroll'](#plugin-scroll-shortcut-descriptions)
+   - [Plugin 'form'](#plugin-form-shortcut-descriptions)
+8. [Action Function Signatures](#action-functions)
+9. [Methods](#methods)
+10. [Contexts, Notes, and Dependencies](#contexts-notes-and-dependencies)
+11. [Errors and the `errorEventName` Channel](#errors-and-the-erroreventname-channel)
+12. [Custom Events & Workflows](#custom-events--workflows)
+13. [TypeScript Support](#typescript-support)
+14. [Links](#links)
+
+
+
+## Quick Start
 
-### Per-Context Plugin Setup (Preferred Method)
-Every plugin supports a `setup` event (e.g., `key:setup`, `click:setup`, `hover:setup`, `scroll:setup`) that allows you to configure plugin settings specifically for that context. This is the **preferred method** for customizing plugins as it provides:
+```js
+// for es6 module projects:
+import { shortcuts, pluginKey, pluginClick, pluginForm, pluginHover, pluginScroll } from '@peter.naydenov/shortcuts'
+// for commonjs projects:
+const { shortcuts, pluginKey, pluginClick, pluginForm, pluginHover, pluginScroll } = require('@peter.naydenov/shortcuts')
 
-- **Context-specific configuration** - Different settings for different contexts
-- **Cleaner code** - No global plugin options needed
-- **Better maintainability** - Settings are defined alongside the shortcuts they affect
 
-The setup function receives:
-- `dependencies` - External dependencies set via `setDependencies()`
-- `defaults` - Default plugin options as a starting point
+const short = shortcuts ();
+// Load needed plugins.  Second argument is per-plugin options.
+short.enablePlugin ( pluginKey )
+short.enablePlugin ( pluginClick )
+// Load a shortcut definition
+short.load ( shortcutDefinition )
+// Activate a context to start listening.
+short.changeContext ( 'editor' )
+```
+
+To stop all shortcuts without activating another context:
 
-Example pattern:
 ```js
-const shortcutDefinition = {
-    context1: {
-        'plugin:setup': ({ dependencies, defaults }) => {
-            return {
-                // Override specific options for this context
-                option1: 'customValue1',
-                option2: 123
-            };
-        },
-        'plugin:event': () => { /* your action */ }
-    }
-};
+short.changeContext ()   // deactivates the current context
 ```
 
-See individual plugin sections for specific setup examples.
+See [Shortcut Description Rules](#shortcut-description-rules) for the shape of `shortcutDefinition`, and [Methods](#methods) for the full API.
+
+
+
+## Concepts
+
+- **Shortcut** — a single rule like `'key: ctrl+s'` or `'click: left-1'` that is triggered by a physical event.
+- **Action function** — the function (or array of functions) executed when a shortcut fires. Each plugin passes a different `data` object to it (see [Action Functions](#action-functions)).
+- **Context** — a named bucket of shortcuts. Only one context is active at a time; `changeContext(name)` switches between them.
+- **Note** — a sub-context tag that lives inside the current context. Lets a single context react differently to the same shortcut under different notes. Set with `setNote('foo')`, read inside the action as `data.note`.
+- **Plugin** — the layer that converts physical input into shortcut events (`key`, `click`, `hover`, `scroll`, `form`).
+- **Custom event** — any string (typically namespaced with `@` or `app:`) that you can `emit` and `listen` to. See [Custom Events & Workflows](#custom-events--workflows).
+
+
+
+## Constructor Options
+
+`shortcuts(options)` accepts:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `onShortcut` | `function` | `false` | Called for every triggered shortcut in the current context (including programmatically emitted events). |
+| `errorEventName` | `string` | `'@shortcuts-error'` | Name of the event on which the library publishes error messages. See [Errors and the `errorEventName` Channel](#errors-and-the-erroreventname-channel). |
+| `streamKeys` | `function` | `false` | Called on every key press while the `key` plugin is active. Equivalent to passing `streamKeys` to `enablePlugin(pluginKey, …)`. |
+
+```js
+const short = shortcuts ({
+        onShortcut   : ({ shortcut, context }) => console.log ( shortcut, 'in', context )
+      , errorEventName : '@my-app-shortcut-errors'
+});
+```
+
+### `onShortcut({ shortcut, context, note, dependencies })`
+```js
+function onShortcut ({ shortcut, context, note, dependencies }) {
+    // shortcut      - (string) Triggered shortcut name (e.g. 'KEY:CTRL+S')
+    // context       - (string) Name of the current context
+    // note          - (string) Name of the note or null if note isn't set
+    // dependencies  - (object) Object with dependencies that you have set by calling `setDependencies` method
+}
+```
+
+### `streamKeys({ key, context, note, dependencies })`
+```js
+function streamKeys ({ key, context, note, dependencies }) {
+    // key           - (string) Pressed key name
+    // context       - (string) Name of the current context
+    // note          - (string) Name of the note or null if note isn't set
+    // dependencies  - (object) Object with dependencies that you have set by calling `setDependencies` method
+}
+```
+
+
+
+## Per-Plugin Options
+
+These are passed as the second argument of `enablePlugin(plugin, options)`. To override per-context, use the `plugin:setup` event — see [Per-Context Setup vs `enablePlugin` Options](#per-context-setup-vs-enableplugin-options).
+
+### Plugin 'key' options
+```js
+  keyWait       : 'Timeout for entering shortcut sequence in ms. Default value - 480'
+, streamKeys    : 'False or a callback function that is called when a key is pressed. Default value - false'
+```
+
+### Plugin 'click' options
+```js
+  mouseWait     : 'Timeout for entering multiple mouse events. Default value - 320.'
+, clickTarget   : 'Array of attribute names to recognize click items in HTML. Default value - ["data-click", "href"]' // checks for data-click='someName' or href attributes
+```
+
+### Plugin 'hover' options
+```js
+  wait          : 'Time to wait for hover sequence in ms. Default value - 320.'
+, hoverTarget   : 'Array of attribute names to recognize hover items in HTML. Default value - ["data-hover"]' // checks for data-hover='someName' attribute
+```
+
+### Plugin 'scroll' options
+```js
+  scrollWait    : 'Delay between scroll events in ms. Default value - 50.'
+, endScrollWait : 'Delay when scroll was stopped in ms. Default value - 400.'
+, minSpace      : 'Minimum distance between scroll events in px. Default value - 40.'
+```
+
+Plugin options are provided as a second argument during the plugin enabling:
+
+```js
+  short.enablePlugin ( pluginKey, {
+                             keyWait: 500 // set the interval to 500ms
+                           , streamKeys: (key) => console.log(key)   // Log in console each pressed key
+                      })
+
+  short.enablePlugin ( pluginClick, {
+                             mouseWait: 200     // set the interval between multiple clicks to 200ms
+                           , clickTarget: ['data-puk', 'data-button'] // array of attribute names to check
+                      })
+
+  short.enablePlugin ( pluginHover, {
+                             wait: 500         // set the hover delay to 500ms
+                           , hoverTarget: ['data-hover-me', 'data-interactive'] // array of attribute names to check
+                      })
+
+  short.enablePlugin ( pluginScroll, {
+                             scrollWait: 100      // set the delay between scroll events to 100ms
+                           , endScrollWait: 600   // set the end scroll delay to 600ms
+                           , minSpace: 60         // set minimum distance to 60px
+                      })
+```
+
+
+
+## Shortcut Description Rules
+
+The shortcuts definition includes a context name and a set of rules (object). The rules are a set of key-value pairs. The key contains a plugin name and a shortcut name and the value is a function or array of functions, to be executed when the shortcut is triggered (action function).
 
 ```js
 // { context: { shortcutName: actionFunction } }
@@ -65,7 +195,7 @@ See individual plugin sections for specific setup examples.
                     shortcutName : function () {
                                                 // do something
                                         }
-                    , shortcutName : [ 
+                    , shortcutName : [
                                               function action1() {
                                                         // do something
                                                 }
@@ -75,302 +205,169 @@ See individual plugin sections for specific setup examples.
                                     ]
                 }
 }
-// shortcutName after v.3.0.0 have a plugin prefix. - 'pluginPrefix:shortcutName'. 
+// shortcutName after v.3.0.0 have a plugin prefix. - 'pluginPrefix:shortcutName'.
 // For example:  'key:s+alt'   - for 's+alt' shortcut that is handled by 'key' plugin.
 ```
 
 Load a shortcut definition by calling `load` method.
 
 ```js
-// for es6 module projects:
-import { shortcuts, pluginKey, pluginClick, pluginForm, pluginHover, pluginScroll } from '@peter.naydenov/shortcuts'
-// for commonjs projects:
-const { shortcuts, pluginKey, pluginClick, pluginForm, pluginHover, pluginScroll } = require('@peter.naydenov/shortcuts')
-
-
-
 const short = shortcuts ();
-// Load a needed plugins
-// short.enablePlugin ( pluginCode, ?pluginOptions )
-short.enablePlugin ( pluginKey ) 
+short.enablePlugin ( pluginKey )
 short.enablePlugin ( pluginClick )
-// Load a shortcut definition
 short.load ( shortcutDefinition )
-
+short.changeContext ( contextName )   // activate a context
 ```
 
-Shortcuts are working only if contex is active. To activate a context call `changeContext` method.
+Shortcuts only fire while a context is active. To deactivate a context without starting another, call `changeContext` with no argument.
 
 ```js
-short.changeContext ( contextName )
+short.changeContext () // deactivates the current context
 ```
 
-To deactivate a context without starting other context, call `changeContext` method without arguments.
 
-```js
-short.changeContext ()
-```
 
+## Per-Context Setup vs `enablePlugin` Options
 
-## Plugin 'hover' Shortcut Descriptions
-`Hover` plugin is used to detect when mouse enters or leaves specific HTML elements. The plugin supports two main events: hover on and hover off.
+There are two ways to configure a plugin:
 
-```js
-hover:on    // Triggered when mouse enters a target element
-hover:off   // Triggered when mouse leaves a target element
-```
+1. **Globally** — pass options to `enablePlugin(plugin, options)`. They apply to every context that uses that plugin.
+2. **Per-context** — define a `plugin:setup` event inside the context object. The function receives `{ dependencies, defaults }` and returns an options object that overrides the defaults **for that context only**. The supported events are `key:setup`, `click:setup`, `hover:setup`, and `scroll:setup`.
 
-### Define Hover Targets
-Target HTML elements for `hover` plugin are defined by `data-hover` attribute. The value of the attribute is the name of the target. Example:
+**Per-context setup is the preferred method** because:
+- Different contexts can use different settings (e.g. fast clicks in a game context, deliberate clicks in a form context).
+- The configuration lives next to the shortcuts that depend on it.
+- You don't have to re-enable the plugin when switching contexts.
 
-```html
-<div data-hover="menu">Menu content</div>
-<!-- target name is 'menu' -->
-```
-
-Attribute is customizable by setting `hoverTarget` hover plugin option. By default, it checks for `['data-hover']`. You can provide an array of attribute names. Read more in section `Options`.
-
-
-
-### Hover Action Functions
-Hover plugin action functions receive the following arguments:
-
-```js
-function myHoverHandler ({
-                  context     // (string) Name of the current context;
-                , note        // (string) Name of the note or null if note isn't set;
-                , dependencies // (object) Object with dependencies that you have set by calling `setDependencies` method;
-                , target      // (DOM element). Target element of the hover event;
-                , targetProps // (object). Coordinates of the target element (top, left, right, bottom, width, height) or null if target element is not available;
-                , x           // (number). X coordinate of the target element;
-                , y           // (number). Y coordinate of the target element;
-                , event       // (object). Original hover event object;
-          }) {
-    // Body of the handler. Do something...
-}
-```
-
-### Hover Detection Timing
-Hover events are detected with a delay to avoid triggering when mouse quickly moves over elements. The default delay is 320ms but you can change it by setting `wait` hover plugin option.
-
-```js
-short.enablePlugin ( pluginHover, { wait: 500 }) // set the delay to 500ms
-```
+The setup function receives:
+- `dependencies` - External dependencies set via `setDependencies()`
+- `defaults` - Default plugin options as a starting point or just for reference. Use them to read or partially override.
 
-### Per-Context Setup (Preferred Method)
-Instead of global plugin options, you can use `hover:setup` event to configure plugin settings per context. This is the preferred method for customization.
+Example pattern (applies to every plugin that supports `setup`):
 
 ```js
 const shortcutDefinition = {
-    navigation: {
-        'hover:setup': ({ dependencies, defaults }) => {
-            // Customize hover settings for this context only
-            return {
-                wait: 200,           // Faster hover detection for navigation
-                hoverTarget: ['data-nav-item', 'data-menu'] // Array of attribute names
-            };
-        },
-        'hover:on': ({ target }) => {
-            target.classList.add('active');
-        },
-        'hover:off': ({ target }) => {
-            target.classList.remove('active');
-        }
-    },
-    slowTooltips: {
-        'hover:setup': ({ dependencies, defaults }) => {
-            // Slower hover detection for tooltips
+    context1: {
+        'plugin:setup': ({ dependencies, defaults }) => {
             return {
-                wait: 800,           // Slower hover detection
-                hoverTarget: ['data-tooltip', 'data-help'] // Different attributes for tooltips
+                // Override specific options for this context
+                option1: 'customValue1',
+                option2: 123
             };
         },
-        'hover:on': ({ target }) => {
-            // Show tooltip with delay
-            setTimeout(() => target.classList.add('visible'), 100);
-        }
+        'plugin:event': () => { /* your action */ }
     }
 };
-
-short.enablePlugin(pluginHover);
-short.load(shortcutDefinition);
-short.changeContext('navigation'); // Uses navigation settings
-// short.changeContext('slowTooltips'); // Uses tooltip settings
 ```
 
-The `hover:setup` function receives:
-- `dependencies` - External dependencies set via `setDependencies()`
-- `defaults` - Default plugin options as a starting point or just for reference
+See individual plugin sections for specific setup examples (`key:setup`, `click:setup`, `hover:setup`, `scroll:setup`).
 
-Example usage:
+**Rule of thumb:** use `enablePlugin(plugin, options)` only for values you want to be global to the app. Use `plugin:setup` for anything that varies by context.
 
-```js
-const shortcutDefinition = {
-    navigation: {
-        'hover:on': ({ target }) => {
-            // Mouse entered the target
-            target.classList.add('active');
-        },
-        'hover:off': ({ target }) => {
-            // Mouse left the target
-            target.classList.remove('active');
-        }
-    }
-};
 
-short.enablePlugin(pluginHover);
-short.load(shortcutDefinition);
-short.changeContext('navigation');
-```
 
-## Plugin 'scroll' Shortcut Descriptions
-`Scroll` plugin is used to detect scroll events on the page. The plugin supports four main scroll directions:
+## Plugin Reference
 
-```js
-scroll:up     // Triggered when scrolling up
-scroll:down   // Triggered when scrolling down
-scroll:left   // Triggered when scrolling left
-scroll:right  // Triggered when scrolling right
-scroll:end    // Triggered when scrolling stops (after endScrollWait timeout)
-```
 
-### Scroll Detection Settings
-Scroll events are detected with specific timing and distance thresholds to avoid excessive triggering. The default settings are:
 
-- `scrollWait`: 50ms - Delay between scroll events
-- `endScrollWait`: 400ms - Delay when scroll was stopped
-- `minSpace`: 40px - Minimum distance between scroll events
+### Plugin 'key' Shortcut Descriptions
 
-These can be customized by setting scroll plugin options:
+Keyboard event description contains a key name and a modifier keys if they are used. The modifier keys `ctrl`, `alt`, and `shift` are supported. They are added to the keyboard event by sign `+`:
 
 ```js
-short.enablePlugin ( pluginScroll, { 
-    scrollWait: 100,      // set delay to 100ms
-    endScrollWait: 600,   // set end scroll delay to 600ms
-    minSpace: 60          // set minimum distance to 60px
-})
+ // example:
+ // key: ctrl+alt+shift+a -> for key 'a' with ctrl, alt and shift keys pressed
 ```
 
-### Per-Context Setup (Preferred Method)
-Instead of global plugin options, you can use `scroll:setup` event to configure plugin settings per context. This is preferred method for customization.
+Keyboard event description support a shortcut sequenses. These means that you can press a sequence of keys to trigger a shortcut. The sequence elements are separated by sign "," ( coma ):
 
 ```js
-const shortcutDefinition = {
-    sensitiveScrolling: {
-        'scroll:setup': ({ dependencies, defaults }) => {
-            // High sensitivity for gaming or precise interactions
-            return {
-                scrollWait: 20,       // Very responsive
-                endScrollWait: 200,   // Quick end detection
-                minSpace: 20          // Small movements trigger
-            };
-        },
-        'scroll:up': () => console.log('Sensitive scroll up'),
-        'scroll:down': () => console.log('Sensitive scroll down'),
-        'scroll:end': () => console.log('Sensitive scroll ended')
-    },
-    lazyScrolling: {
-        'scroll:setup': ({ dependencies, defaults }) => {
-            // Low sensitivity for reading or casual browsing
-            return {
-                scrollWait: 150,      // Less responsive
-                endScrollWait: 800,   // Slow end detection
-                minSpace: 80          // Larger movements needed
-            };
-        },
-        'scroll:up': () => console.log('Lazy scroll up'),
-        'scroll:down': () => console.log('Lazy scroll down'),
-        'scroll:end': () => console.log('Lazy scroll ended')
-    }
-};
-
-short.enablePlugin(pluginScroll);
-short.load(shortcutDefinition);
-short.changeContext('sensitiveScrolling'); // Uses sensitive settings
-// short.changeContext('lazyScrolling'); // Uses lazy settings
-```
-
-The `scroll:setup` function receives:
-- `dependencies` - External dependencies set via `setDependencies()`
-- `defaults` - Default plugin options as a starting point
-
-### Scroll Action Functions
-Scroll plugin action functions receive the following arguments:
+ // example:
+ // key: a,b,c -> for key 'a' then key 'b' then key 'c'
 
-```js
-function myScrollHandler ({
-                  context     // (string) Name of the current context;
-                , note        // (string) Name of the note or null if note isn't set;
-                , dependencies // (object) Object with dependencies that you have set by calling `setDependencies` method;
-                , event       // (object). Original scroll event object;
-          }) {
-    // Body of the handler. Do something...
-}
+ // key: g+shift,o,t,o -> for key 'g' with shift, then key 'o', then key 't' then key 'o'
 ```
 
-Example usage:
+Order of describing keyboard event and modifier keys is not important, but sequence elements are:
 
 ```js
-const shortcutDefinition = {
-    scrollView: {
-        'scroll:up': () => {
-            console.log('User scrolled up');
-        },
-        'scroll:down': () => {
-            console.log('User scrolled down');
-        },
-        'scroll:end': () => {
-            console.log('User stopped scrolling');
-        }
-    }
-};
-
-short.enablePlugin(pluginScroll);
-short.load(shortcutDefinition);
-short.changeContext('scrollView');
+ // example:
+ // key: a+ctrl,l,o,t -> a with ctrl, then l, then o, then t
+ // this is equal to:
+ // key: ctrl+a,l,o,t
+ // but not equal to:
+ // key: ctrl+a,o,t,l
 ```
 
-```
+Keyboard sequence is detected automatically by time interval between key presses. The default interval is 480ms but you can change it by setting `keyWait` key plugin option. Read more in section `Per-Plugin Options`.
 
-Shortcuts context has `note` that works like sub-contexts. Every shortcut function receives a context and note as arguments, so you can have fine control over the context.
+#### Per-Context Setup (Preferred Method)
+Instead of global plugin options, you can use `key:setup` event to configure plugin settings per context. This is preferred method for customization.
 
 ```js
-short.setNote ( 'special' ) // set note to 'special'
-short.setNote () // remove the note
-```
-
-The idea of `note` is to minimize the number of contexts if they are very simular. You can use same context but change the `note` and control the shortcut execution from inside of the action function by checking the `note`.
+const shortcutDefinition = {
+    fastTyping: {
+        'key:setup': ({ dependencies, defaults }) => {
+            // Fast key detection for gaming or rapid input
+            return {
+                keyWait: 200,       // Very fast sequence detection
+                streamKeys: (key) => console.log('Key pressed:', key) // Enable key streaming
+            };
+        },
+        'key:a,b,c': () => console.log('Fast sequence triggered'),
+        'key:ctrl+s': () => console.log('Fast save')
+    },
+    slowTyping: {
+        'key:setup': ({ dependencies, defaults }) => {
+            // Slower key detection for accessibility or careful input
+            return {
+                keyWait: 800,       // Slower sequence detection
+                streamKeys: false    // Disable key streaming
+            };
+        },
+        'key:a,b,c': () => console.log('Slow sequence triggered'),
+        'key:ctrl+s': () => console.log('Careful save')
+    }
+};
 
-```js
-{
-    contextName : {
-                    shortcutName : function ( {context, note} ) {
-                                        if ( note === 'special' ) {
-                                                        // do something
-                                            }
-                                    }
-                }
-}
+short.enablePlugin(pluginKey);
+short.load(shortcutDefinition);
+short.changeContext('fastTyping'); // Uses fast settings
+// short.changeContext('slowTyping'); // Uses slow settings
 ```
 
-Context and notes are available inside action functions but you can check them from outside too.
-Check current context by calling `getContext` method.
+The `key:setup` function receives:
+- `dependencies` - External dependencies set via `setDependencies()`
+- `defaults` - Default plugin options as a starting point
 
-```js
-short.getContext ()
-```
+There is a way to disable automatic sequence detection and mark the begining and the end of the sequense by using a keyboard action functions. Read more in section [Action Functions → Keyboard Action Functions](#keyboard-action-functions).
 
-Check notes by calling `getNote` method.
+Special characters that are available for your shortcut descriptions:
+- 'left' - left arrow key
+- 'right' - right arrow key
+- 'up' - up arrow key
+- 'down' - down arrow key
+- 'enter' - enter key
+- 'space' - space key
+- 'esc' - escape key
+- 'tab' - tab key
+- 'backspace' - backspace key
+- '=' - equal key
+- F1 - F12 - function keys
+- '/' - slash key
+- '\\' - backslash key
+- '[' - open square bracket key
+- ']' - close square bracket key
+- '`' - backtick key
 
-```js
-short.getNote ()
-```
+**Warning**: For keys with two symbols(look at the keyboard), in shortcut description use the lower one. Examples: Use '=' instead of '+', use '/' instead of '?', etc. Modifier keys are available for special characters too.
 
+**Warining**: Some of the shortcuts are used by OS and the browswer, so they are not available.
 
 
 
+### Plugin 'click' Shortcut Descriptions
 
-## Plugin 'click' Shortcut Descriptions
 Mouse event name is build from the following parts:
 ```js
  // click:<mouse button>-<number of clicks>-<modifier key>-<modifier key>-<modifier key>
@@ -405,7 +402,7 @@ Multiple clicks are detected automatically by time interval between clicks. The
  short.enablePlugin ( pluginClick, { mouseWait: 500 }) // set the interval to 500ms
 ```
 
-### Per-Context Setup (Preferred Method)
+#### Per-Context Setup (Preferred Method)
 Instead of global plugin options, you can use `click:setup` event to configure plugin settings per context. This is preferred method for customization.
 
 ```js
@@ -430,7 +427,7 @@ const shortcutDefinition = {
             // Slower clicking for form submissions or important actions
             return {
                 mouseWait: 600,      // Slower click detection
-                clickTarget: ['data-form-action', 'data-submit'] // Array of attributes for form actions
+                clickTarget: ['data-form-action', 'data-submit'] // Array of attributes for form submissions
             };
         },
         'click:left-1': ({ target }) => {
@@ -449,10 +446,12 @@ The `click:setup` function receives:
 - `dependencies` - External dependencies set via `setDependencies()`
 - `defaults` - Default plugin options as a starting point
 
-Read more in section `Options`.
+Read more in section `Per-Plugin Options`.
+
 
 
-## Define a Click Targets
+### Define a Click Targets
+
 Target HTML elements for `shortcuts` are defined by `data-click` attribute. The value of the attribute is the name of the target. Example:
 
 ```html
@@ -460,7 +459,7 @@ Target HTML elements for `shortcuts` are defined by `data-click` attribute. The
 <!-- target name is 'id' -->
 ```
 
-Attribute is customizable by setting `clickTarget` click plugin option. By default, it checks for `['data-click', 'href']`. You can provide an array of attribute names. Read more in section `Options`.
+Attribute is customizable by setting `clickTarget` click plugin option. By default, it checks for `['data-click', 'href']`. You can provide an array of attribute names. Read more in section `Per-Plugin Options`.
 
 If current shortcuts context contain definition for 2 or more clicks, this may slow down the execution of single shortcuts because `shortcuts` will wait for the time interval to detect multiple clicks. To avoid this for specific targets, you can set `data-quick-click` attribute to the target element. Example:
 
@@ -493,121 +492,229 @@ Clicking on <a> tag will execute default browser behaviour. In your `click:left-
 
 
 
-## Plugin 'key' Event Descriptions
-Keyboard event description contains a key name and a modifier keys if they are used. The modifier keys `ctrl`, `alt`, and `shift` are supported. They are added to the keyboard event by sign `+`:
+### Plugin 'hover' Shortcut Descriptions
+
+`Hover` plugin is used to detect when mouse enters or leaves specific HTML elements. The plugin supports two main events: hover on and hover off.
 
 ```js
- // example:
- // key: ctrl+alt+shift+a -> for key 'a' with ctrl, alt and shift keys pressed
+hover:on    // Triggered when mouse enters a target element
+hover:off   // Triggered when mouse leaves a target element
 ```
 
-Keyboard event description support a shortcut sequenses. These means that you can press a sequence of keys to trigger a shortcut. The sequence elements are separated by sign "," ( coma ):
+#### Define Hover Targets
+Target HTML elements for `hover` plugin are defined by `data-hover` attribute. The value of the attribute is the name of the target. Example:
+
+```html
+<div data-hover="menu">Menu content</div>
+<!-- target name is 'menu' -->
+```
+
+Attribute is customizable by setting `hoverTarget` hover plugin option. By default, it checks for `['data-hover']`. You can provide an array of attribute names. Read more in section `Per-Plugin Options`.
+
+
+
+### Hover Detection Timing
+Hover events are detected with a delay to avoid triggering when mouse quickly moves over elements. The default delay is 320ms but you can change it by setting `wait` hover plugin option.
 
 ```js
- // example:
- // key: a,b,c -> for key 'a' then key 'b' then key 'c'
+short.enablePlugin ( pluginHover, { wait: 500 }) // set the delay to 500ms
+```
 
- // key: g+shift,o,t,o -> for key 'g' with shift, then key 'o', then key 't' then key 'o'
+#### Per-Context Setup (Preferred Method)
+Instead of global plugin options, you can use `hover:setup` event to configure plugin settings per context. This is the preferred method for customization.
+
+```js
+const shortcutDefinition = {
+    navigation: {
+        'hover:setup': ({ dependencies, defaults }) => {
+            // Customize hover settings for this context only
+            return {
+                wait: 200,           // Faster hover detection for navigation
+                hoverTarget: ['data-nav-item', 'data-menu'] // Array of attribute names
+            };
+        },
+        'hover:on': ({ target }) => {
+            target.classList.add('active');
+        },
+        'hover:off': ({ target }) => {
+            target.classList.remove('active');
+        }
+    },
+    slowTooltips: {
+        'hover:setup': ({ dependencies, defaults }) => {
+            // Slower hover detection for tooltips
+            return {
+                wait: 800,           // Slower hover detection
+                hoverTarget: ['data-tooltip', 'data-help'] // Different attributes for tooltips
+            };
+        },
+        'hover:on': ({ target }) => {
+            // Show tooltip with delay
+            setTimeout(() => target.classList.add('visible'), 100);
+        }
+    }
+};
+
+short.enablePlugin(pluginHover);
+short.load(shortcutDefinition);
+short.changeContext('navigation'); // Uses navigation settings
+// short.changeContext('slowTooltips'); // Uses tooltip settings
 ```
 
-Order of describing keyboard event and modifier keys is not important, but sequence elements are:
+The `hover:setup` function receives:
+- `dependencies` - External dependencies set via `setDependencies()`
+- `defaults` - Default plugin options as a starting point or just for reference
+
+Example usage:
 
 ```js
- // example:
- // key: a+ctrl,l,o,t -> a with ctrl, then l, then o, then t
- // this is equal to:
- // key: ctrl+a,l,o,t
- // but not equal to:
- // key: ctrl+a,o,t,l
+const shortcutDefinition = {
+    navigation: {
+        'hover:on': ({ target }) => {
+            // Mouse entered the target
+            target.classList.add('active');
+        },
+        'hover:off': ({ target }) => {
+            // Mouse left the target
+            target.classList.remove('active');
+        }
+    }
+};
+
+short.enablePlugin(pluginHover);
+short.load(shortcutDefinition);
+short.changeContext('navigation');
 ```
 
-Keyboard sequence is detected automatically by time interval between key presses. The default interval is 480ms but you can change it by setting `keyWait` key plugin option. Read more in section `Options`. 
 
-### Per-Context Setup (Preferred Method)
-Instead of global plugin options, you can use `key:setup` event to configure plugin settings per context. This is preferred method for customization.
+
+### Plugin 'scroll' Shortcut Descriptions
+
+`Scroll` plugin is used to detect scroll events on the page. The plugin supports four main scroll directions:
+
+```js
+scroll:up     // Triggered when scrolling up
+scroll:down   // Triggered when scrolling down
+scroll:left   // Triggered when scrolling left
+scroll:right  // Triggered when scrolling right
+scroll:end    // Triggered when scrolling stops (after endScrollWait timeout)
+```
+
+#### Scroll Detection Settings
+Scroll events are detected with specific timing and distance thresholds to avoid excessive triggering. The default settings are:
+
+- `scrollWait`: 50ms - Delay between scroll events
+- `endScrollWait`: 400ms - Delay when scroll was stopped
+- `minSpace`: 40px - Minimum distance between scroll events
+
+These can be customized by setting scroll plugin options:
+
+```js
+short.enablePlugin ( pluginScroll, {
+    scrollWait: 100,      // set delay to 100ms
+    endScrollWait: 600,   // set end scroll delay to 600ms
+    minSpace: 60          // set minimum distance to 60px
+})
+```
+
+#### Per-Context Setup (Preferred Method)
+Instead of global plugin options, you can use `scroll:setup` event to configure plugin settings per context. This is preferred method for customization.
 
 ```js
 const shortcutDefinition = {
-    fastTyping: {
-        'key:setup': ({ dependencies, defaults }) => {
-            // Fast key detection for gaming or rapid input
+    sensitiveScrolling: {
+        'scroll:setup': ({ dependencies, defaults }) => {
+            // High sensitivity for gaming or precise interactions
             return {
-                keyWait: 200,       // Very fast sequence detection
-                streamKeys: (key) => console.log('Key pressed:', key) // Enable key streaming
+                scrollWait: 20,       // Very responsive
+                endScrollWait: 200,   // Quick end detection
+                minSpace: 20          // Small movements trigger
             };
         },
-        'key:a,b,c': () => console.log('Fast sequence triggered'),
-        'key:ctrl+s': () => console.log('Fast save')
+        'scroll:up': () => console.log('Sensitive scroll up'),
+        'scroll:down': () => console.log('Sensitive scroll down'),
+        'scroll:end': () => console.log('Sensitive scroll ended')
     },
-    slowTyping: {
-        'key:setup': ({ dependencies, defaults }) => {
-            // Slower key detection for accessibility or careful input
+    lazyScrolling: {
+        'scroll:setup': ({ dependencies, defaults }) => {
+            // Low sensitivity for reading or casual browsing
             return {
-                keyWait: 800,       // Slower sequence detection
-                streamKeys: false    // Disable key streaming
+                scrollWait: 150,      // Less responsive
+                endScrollWait: 800,   // Slow end detection
+                minSpace: 80          // Larger movements needed
             };
         },
-        'key:a,b,c': () => console.log('Slow sequence triggered'),
-        'key:ctrl+s': () => console.log('Careful save')
+        'scroll:up': () => console.log('Lazy scroll up'),
+        'scroll:down': () => console.log('Lazy scroll down'),
+        'scroll:end': () => console.log('Lazy scroll ended')
     }
 };
 
-short.enablePlugin(pluginKey);
+short.enablePlugin(pluginScroll);
 short.load(shortcutDefinition);
-short.changeContext('fastTyping'); // Uses fast settings
-// short.changeContext('slowTyping'); // Uses slow settings
+short.changeContext('sensitiveScrolling'); // Uses sensitive settings
+// short.changeContext('lazyScrolling'); // Uses lazy settings
 ```
 
-The `key:setup` function receives:
+The `scroll:setup` function receives:
 - `dependencies` - External dependencies set via `setDependencies()`
 - `defaults` - Default plugin options as a starting point
 
-There is a way to disable automatic sequence detection and mark the begining and the end of the sequense by using a keyboard action functions. Read more in section `Keyboard Action Functions`.
+Example usage:
 
-Special characters that are available for your shortcut descriptions:
-- 'left' - left arrow key
-- 'right' - right arrow key
-- 'up' - up arrow key
-- 'down' - down arrow key
-- 'enter' - enter key
-- 'space' - space key
-- 'esc' - escape key
-- 'tab' - tab key
-- 'backspace' - backspace key
-- '=' - equal key
-- F1 - F12 - function keys
-- '/' - slash key
-- '\\' - backslash key
-- '[' - open square bracket key
-- ']' - close square bracket key
-- '`' - backtick key
+```js
+const shortcutDefinition = {
+    scrollView: {
+        'scroll:up': () => {
+            console.log('User scrolled up');
+        },
+        'scroll:down': () => {
+            console.log('User scrolled down');
+        },
+        'scroll:end': () => {
+            console.log('User stopped scrolling');
+        }
+    }
+};
 
-**Warning**: For keys with two symbols(look at the keyboard), in shortcut description use the lower one. Examples: Use '=' instead of '+', use '/' instead of '?', etc. Modifier keys are available for special characters too.
+short.enablePlugin(pluginScroll);
+short.load(shortcutDefinition);
+short.changeContext('scrollView');
+```
 
-**Warining**: Some of the shortcuts are used by OS and the browswer, so they are not available.
+Shortcuts context has `note` that works like sub-contexts. Every shortcut function receives a context and note as arguments, so you can have fine control over the context. See [Contexts, Notes, and Dependencies](#contexts-notes-and-dependencies).
 
 
 
+### Plugin 'form' Shortcut Descriptions
 
+`Form` plugin is used to watch for changes in inputs, textareas, select and textarea elements. All 3 possible shortcuts are predefined: `form: watch`, `form: define` and `form: action`.
 
-## Plugin 'form' Shortcut Descriptions
-`Form` plugin is used to watch for changes in inputs, textareas, select and textarea elements. All 3 possible shortcuts are predefined: 'form: watch', 'form: define' and 'form: action'.
 ```js
-`form: watch`  // (function). Should return list of elements to watch
-`form: define` // (function). Define every element you are watching as a type(own definition).
-`form: action` // (function). Function should return a list of objects with action function definitions.
+form: watch    // (function). Should return list of elements to watch
+form: define   // (function). Define every element you are watching as a type (own definition)
+form: action   // (function). Must return a list of step objects. Each step has a fn, type, timing and optional wait
 ```
-Action definitions have 4 possible properties:
+
+#### Action definition step shape
+
+`form:action` returns an array of steps. Each step has four possible properties:
+
 ```js
 {
-   fn // (function) Action function
- , type // (string) Type of the element. Available types are according to `form: define` reponses
- , timing // (string) Possible values are: 'in', 'out', 'instant'
- , wait // (number) It's a event reducer timer in milliseconds. Worsk only for 'timing: instant'  
+   fn     // (function) Action function. Receives FormEventData.
+ , type   // (string) Type of the element. Must match a value returned by `form: define`
+ , timing // (string) 'in' (focus in), 'out' (focus out), or 'instant' (value change)
+ , wait   // (number) Event-reducer timer in ms. Only used when `timing: 'instant'`.
 }
 ```
 
-Definition Example:
+- `timing: 'in'` fires once when focus enters the element.
+- `timing: 'out'` fires once when focus leaves the element.
+- `timing: 'instant'` fires on each value change but is throttled by `wait` ms so the action doesn't run on every keystroke.
+
+#### Definition example
+
 ```js
 const shortcutScope = {
 ...
@@ -636,7 +743,7 @@ const shortcutScope = {
                         fn: () => { console.log ( 'Update content') }
                       , type : 'input'
                       , timing : 'instant' // on content change. on each change
-                      , wait : 500        // Wait 500ms between changes. 
+                      , wait : 500        // Wait 500ms between changes.
                     },
                     {
                         fn: () => { console.log('It was a button') }
@@ -646,9 +753,13 @@ const shortcutScope = {
 ] // form: action
 }
 ```
-`form:watch` can contains `.someClass` for selecting elements by class name or `#someId` for selecting elements by id. It's could be everything that works in querySelectorAll. The `form:define` gives you a way to separate different inputs and privide a custom callback for each of them or use single callback for all inputs.
 
-Plugin `form` has a default versions for `form:watch` and `form:define` functions. Only `form:action` is required but should use the default settings. Here are the defaults:
+`form:watch` can contain `.someClass` for selecting elements by class name or `#someId` for selecting elements by id. It's could be everything that works in `querySelectorAll`. The `form:define` gives you a way to separate different inputs and privide a custom callback for each of them or use single callback for all inputs.
+
+#### Default `form:watch` and `form:define`
+
+The `form` plugin ships with defaults for `form:watch` and `form:define`. Only `form:action` is required.
+
 ```js
 const _defaults = {
       watch : () => 'input, select, textarea, button, a'
@@ -664,9 +775,18 @@ const _defaults = {
 } // defaults
 ```
 
-If you want to pause of resume event from `form` plugin, call `short.pause(eventName)` and `short.resume(eventName)` where eventName is a `${type}/${timing}`. Take type and timing from action definitions.
+#### Pausing a specific form event
+
+To pause or resume a single form event, call `short.pause(eventName)` / `short.resume(eventName)` where `eventName` is `${type}/${timing}`. Take `type` and `timing` from the action definitions.
+
+```js
+// Disable 'instant' updates on inputs
+short.pause('input/instant');
+// Re-enable them
+short.resume('input/instant');
+```
 
-### Per-Context Setup (Coming Soon)
+#### Per-Context Setup (Coming Soon)
 The `form:setup` event is planned for future versions to allow per-context configuration of form plugin settings. Currently, form plugin uses default settings or global plugin options.
 
 **Note**: In version 4.0.0, the `form:action` event now has access to `dependencies` at the top level, allowing you to minimize dependency declarations. Other named arguments are not available at the top level of `form:action`.
@@ -674,42 +794,89 @@ The `form:setup` event is planned for future versions to allow per-context confi
 
 
 ## Action Functions
+
 Action functions are called when a shortcut is triggered. There is a difference among plugin action functions. Arguments are slightly different.
 
+> Every action function `data` object also contains `emit` — a reference to the library's internal event emitter. See [Custom Events & Workflows](#custom-events--workflows).
+
 
 
 ### Keyboard Action Functions
-Description of `key` plugin action functions is:
+
+The `key` plugin's `data` object includes helper functions to control sequences manually (useful when the timer-based detection is undesirable). Disable auto-detection by using a multi-key sequence, then call `wait`/`end` to control when it is allowed to match.
+
 ```js
 function myKeyHandler ({
-                  context   // (string) Name of the current context;
-                , note      // (string) Name of the note or null if note isn't set;
-                , dependencies // (object) Object with dependencies that you have set by calling `setDependencies` method;
-                , wait      // (function). Call it to stop a sequence timer and write shortcut sequence without a timer.
-                , end       // (function). Recover the sequence timer;
-                , ignore    // (function). Call it to ignore the current shortcut from the sequence;
-                , isWaiting // (boolean). True if the sequence timer is active;
-                        }) {
+              context       // (string) Name of the current context;
+            , note          // (string) Name of the note or null if note isn't set;
+            , dependencies  // (object) Object with dependencies that you have set by calling `setDependencies` method;
+            , wait          // (function). Stop the sequence timer and write the shortcut sequence without a timer. Use inside a key handler when you want manual control of the sequence.
+            , end           // (function). Recover the sequence timer (the opposite of `wait`).
+            , ignore        // (function). Ignore the current shortcut from the sequence. Useful for keys that should not advance the sequence (e.g. modifier keys).
+            , isWaiting     // (boolean). True if the sequence timer is currently active.
+            , emit          // (function). Call it to trigger a shortcut or custom event;
+                    }) {
     // Body of the handler. Do something...
 }
 ```
 
 
 
-
 ### Mouse Action Functions
+
 Click plugin action functions can be described like:
 
 ```js
 function myMouseHandler ({
-                  context     // (string) Name of the current context;
-                , note        // (string) Name of the note or null if note isn't set;
-                , dependencies // (object) Object with dependencies that you have set by calling `setDependencies` method;
-                , target      // (DOM element). Target element of the mouse event;
-                , targetProps // (object). Coordinates of the target element (top, left, right, bottom, width, height) or null if target element is not available;
-                , x           // (number). X coordinate of the target element;
-                , y           // (number). Y coordinate of the target element;
-                , event       // (object). Original mouse event object;
+              context       // (string) Name of the current context;
+            , note          // (string) Name of the note or null if note isn't set;
+            , dependencies  // (object) Object with dependencies that you have set by calling `setDependencies` method;
+            , target        // (DOM element). Target element of the mouse event;
+            , targetProps   // (object). Coordinates of the target element (top, left, right, bottom, width, height) or null if target element is not available;
+            , x             // (number). X coordinate of the target element;
+            , y             // (number). Y coordinate of the target element;
+            , event         // (object). Original mouse event object;
+            , emit          // (function). Call it to trigger a shortcut or custom event;
+          }) {
+    // Body of the handler. Do something...
+}
+```
+
+
+
+### Hover Action Functions
+
+Hover plugin action functions receive the following arguments:
+
+```js
+function myHoverHandler ({
+              context       // (string) Name of the current context;
+            , note          // (string) Name of the note or null if note isn't set;
+            , dependencies  // (object) Object with dependencies that you have set by calling `setDependencies` method;
+            , target        // (DOM element). Target element of the hover event;
+            , targetProps   // (object). Coordinates of the target element (top, left, right, bottom, width, height) or null if target element is not available;
+            , x             // (number). X coordinate of the target element;
+            , y             // (number). Y coordinate of the target element;
+            , event         // (object). Original hover event object;
+            , emit          // (function). Call it to trigger a shortcut or custom event;
+          }) {
+    // Body of the handler. Do something...
+}
+```
+
+
+
+### Scroll Action Functions
+
+Scroll plugin action functions receive the following arguments:
+
+```js
+function myScrollHandler ({
+              context       // (string) Name of the current context;
+            , note          // (string) Name of the note or null if note isn't set;
+            , dependencies  // (object) Object with dependencies that you have set by calling `setDependencies` method;
+            , event         // (object). Original scroll event object;
+            , emit          // (function). Emit event to trigger a shortcut or custom event;
           }) {
     // Body of the handler. Do something...
 }
@@ -717,137 +884,474 @@ function myMouseHandler ({
 
 
 
+### Form Action Functions
+
+The `fn` inside each `form:action` step receives the same shape as the other plugins, plus `target` and the type of change (`type`, `timing`):
+
+```js
+function myFormHandler ({
+              context       // (string) Name of the current context;
+            , note          // (string) Name of the note or null if note isn't set;
+            , dependencies  // (object) Object with dependencies that you have set by calling `setDependencies` method;
+            , target        // (DOM element). Element that triggered the form event;
+            , type          // (string). The type label returned by 'form: define';
+            , timing        // (string). 'in' | 'out' | 'instant';
+            , wait          // (number). The reducer interval in ms (only when timing: 'instant');
+            , emit          // (function). Call it to trigger a shortcut or custom event;
+          }) {
+    // Body of the handler. Do something...
+}
+```
+
+> The `form:action` outer function itself receives `{ dependencies }` (and nothing else).
+
 
 
 ## Methods
 
-Description of the methods of shortcut instance:
+Below is the full API of a `shortcuts()` instance. Every method is described with its signature, what it returns, and a usage example.
+
+
+
+### `load(shortcutsUpdate)`
+
+Load a context with shortcuts. Can be called multiple times to add or replace contexts.
+
+- **Returns:** `void`
+- **Emits errors:** none
 
 ```js
-  load            : 'Load and extend a shortcut definition.'
-, unload          : 'Remove a shortcut context with all its shortcuts.'
+short.load({
+    editor: {
+        'key:ctrl+s': () => save(),
+        'click:left-1': ({ target }) => handleClick(target)
+    },
+    viewer: {
+        // ...
+    }
+});
+```
+
+> If you `load` a context that is **currently active**, the library will re-apply it so the new shortcuts take effect immediately. No need to call `changeContext` again.
+
 
-, enablePlugin    : 'Enable a plugin.'
-, disablePlugin   : 'Disable a plugin.'
-, mutePlugin      : 'Mute a plugin. All events for the plugin will be ignored.'
-, unmutePlugin    : 'Unmute a plugin. All events for the plugin will be listened again.'
 
-, changeContext   : 'Switch to existing shortcut context or shitch off the context(if no argument).'
-, getContext      : 'Return a name of current context or null if there is no context selected'
-, emit            : 'Trigger a shortcut or custom event programmatically.'
-, pause           : 'Stop listening for shortcuts.'
-, resume          : 'Resume listening for shortcuts.'
-, listPlugins     : "Return list of enabled plugins. Plugins are represented by plugin's prefixes."
-, listContexts    : 'Return list of available contexts.'
-, listShortcuts   : 'Return list of shortcuts per context.'
-, getNote         : `Return a name of current note or null if note isn't set`
-, setNote         : 'Set a note to current context.'
-, setDependencies : 'Set dependencies that will be available in action functions.'
-, getDependencies : 'Return a dependencies object.'
-, reset           : 'Reset shortcut instance.'
+### `unload(contextName)`
+
+Remove a context and all its shortcuts. Cannot remove the currently active context.
+
+- **Returns:** `void`
+- **Emits errors:**
+  - `'@shortcuts-error'` — if `contextName` is the active context (call `changeContext` first).
+  - `'@shortcuts-error'` — if `contextName` doesn't exist.
+
+```js
+short.changeContext('editor');
+short.unload('login'); // removes 'login' and its shortcuts
 ```
 
-### How to 'pause' and 'resume'?
-When you want to stop execution of shortcuts, call `short.pause()`. It's equal to `short.pause('*')`. Will stop all shortcuts in the active context. Stop for single shortcut is by calling `short.pause('shortcutName')`. To resume shortcuts execution call `short.resume()`. It's equal to `short.resume('*')`. Will resume all shortcuts in the active context. Resume for single shortcut is by calling `short.resume('shortcutName')`.
+
+
+### `enablePlugin(plugin, options?)` and `disablePlugin(pluginName)`
+
+Enable a plugin. Calling with a plugin that is already enabled will replace it (useful for hot-reloading options). `disablePlugin` permanently removes the plugin — you'll need to call `enablePlugin` again to use it.
+
+- **Returns:** `void`
+- **Emits errors:** none
 
 ```js
-// pause all shortcuts in the active context
-short.pause () // will stop all shortcuts in the active context
-short.resume ( 'shift+a' ) // will resume only 'shift+a' shortcut
+short.enablePlugin(pluginKey);                 // enable with defaults
+short.enablePlugin(pluginKey, { keyWait: 300 }); // enable with custom options
+short.disablePlugin('key');                    // permanently disable
+```
+
+> Pass the **plugin function** to `enablePlugin`, but the plugin's **prefix string** to `disablePlugin` (the value returned by `listPlugins()`).
+
+
 
-short.resume ('*') // will resume all shortcuts
+### `mutePlugin(pluginName)` and `unmutePlugin(pluginName)`
+
+Temporarily suspend / resume a plugin. Muted plugins keep their state but stop processing events. Use these for "soft" disable (e.g. when a modal opens) — they are reversible.
+
+- **Returns:** `number` — index of the plugin in the internal array, or `-1` if not found.
+- **Emits errors:** none
+
+```js
+short.mutePlugin('key');     // ignore all keyboard shortcuts
+short.unmutePlugin('key');   // resume keyboard shortcuts
 ```
 
+> **`mutePlugin` vs `disablePlugin`** — `disablePlugin` destroys the plugin (you'll lose any per-context setup state). `mutePlugin` keeps the plugin registered and just stops it from processing events. Prefer `mutePlugin` for transient pauses.
 
 
-## Options
 
-Shortcut receives `options` during the start. Here is the list of available options:
+### `changeContext(contextName?)`
+
+Switch to a different context. Pass `null`, `undefined`, or no argument to **deactivate** the current context (no shortcuts fire).
+
+- **Returns:** `void`
+- **Emits errors:**
+  - `'@shortcuts-error'` — if `contextName` doesn't exist.
 
 ```js
- onShortcut    : 'Callback function that is called when a shortcut is triggered. Default value - false'
+short.changeContext('editor'); // switch to 'editor'
+short.changeContext();         // deactivate all shortcuts
 ```
+
+
+
+### `getContext()`
+
+Return the name of the currently active context, or `null` if none.
+
+- **Returns:** `string | null`
+
 ```js
-const short = shortcut ({onShortcut: (shortcut) => console.log(shortcut) }) // Log in console each triggered shortcut
+if (short.getContext() === 'editor') {
+    // editor-specific UI logic
+}
 ```
 
 
 
-### Plugin 'key' options
+### `getNote()` and `setNote(note?)`
+
+`setNote` tags the current context with a sub-context string. `getNote` reads it back. Pass `null` / no argument to `setNote` to clear it. Non-string arguments are silently ignored.
+
+- **Returns:** `getNote` returns `string | null`; `setNote` returns `void`.
+- **Emits errors:** none
+
 ```js
-  keyWait       : 'Timeout for entering shortcut sequence in ms. Default value - 480'
-, streamKeys    : 'False or a callback function that is called when a key is pressed. Default value - false'
+short.setNote('special');  // tag the current context
+short.getNote();           // 'special'
+short.setNote();           // clear the note (passing nothing)
+short.setNote(null);       // same — explicit null
+
+// Inside an action function:
+'key:ctrl+s': ({ note }) => {
+    if (note === 'special') {
+        // do the "special" variant of save
+    }
+}
 ```
 
+The idea of `note` is to minimize the number of contexts if they are very similar — keep one context, switch its `note`, and branch inside the action by reading it.
 
 
-### Plugin 'click' options
+
+### `setDependencies(deps)` and `getDependencies()`
+
+`setDependencies` registers a bag of external values that will be merged into the `dependencies` object passed to every action function. `getDependencies` returns the live bag (mutating it affects future shortcut calls — `setDependencies` is `Object.assign`-based, not a snapshot).
+
+- **Returns:** `getDependencies` returns `object`; `setDependencies` returns `void`.
+- **Emits errors:** none
+
 ```js
-  mouseWait     : 'Timeout for entering multiple mouse events. Default value - 320.'
-, clickTarget   : 'Array of attribute names to recognize click items in HTML. Default value - ["data-click", "href"]' // checks for data-click='someName' or href attributes
+// Once at startup:
+short.setDependencies({
+    api: myApi,
+    router: myRouter,
+    analytics: track
+});
+
+// Inside any action function:
+'key:ctrl+s': ({ dependencies }) => {
+    dependencies.api.save();
+    dependencies.analytics.track('save');
+}
 ```
 
-### Plugin 'hover' options
+> `dependencies` is also available inside `form:action`, `key:setup`, `click:setup`, `hover:setup`, `scroll:setup`, `onShortcut`, and `streamKeys` — anywhere the library hands you a `data` object.
+
+
+
+### `listPlugins()`
+
+Return an array of enabled plugin prefixes.
+
+- **Returns:** `string[]` (e.g. `['key', 'click']`)
+
 ```js
-  wait          : 'Time to wait for hover sequence in ms. Default value - 320.'
-, hoverTarget   : 'Array of attribute names to recognize hover items in HTML. Default value - ["data-hover"]' // checks for data-hover='someName' attribute
+short.listPlugins(); // ['key', 'click', 'hover']
 ```
 
-### Plugin 'scroll' options
+
+
+### `listContexts()`
+
+Return an array of all loaded context names (including the inactive ones).
+
+- **Returns:** `string[]`
+
 ```js
-  scrollWait    : 'Delay between scroll events in ms. Default value - 50.'
-, endScrollWait : 'Delay when scroll was stopped in ms. Default value - 400.'
-, minSpace      : 'Minimum distance between scroll events in px. Default value - 40.'
+short.listContexts(); // ['login', 'editor', 'settings']
 ```
 
-Plugin options are provided as a second argument during the plugin enabling. It's look like this:
-  
+
+
+### `listShortcuts(contextName?)`
+
+Return a list of shortcuts. Two return shapes:
+
+- With no argument — an array of `{ context, shortcuts }` for every context.
+- With a context name — an array of shortcut names for that context, or `null` if the context doesn't exist.
+
+- **Returns:** `string[] | { context: string, shortcuts: string[] }[] | null`
+
 ```js
-  short.enablePlugin ( pluginKey, {
-                             keyWait: 500 // set the interval to 500ms
-                           , streamKeys: (key) => console.log(key)   // Log in console each pressed key
-                      })
+short.listShortcuts();
+// [
+//   { context: 'editor',  shortcuts: ['KEY:CTRL+S', 'CLICK:LEFT-1', ...] },
+//   { context: 'viewer',  shortcuts: ['KEY:ESC'] }
+// ]
 
-  short.enablePlugin ( pluginClick, {
-                             mouseWait: 200     // set the interval between multiple clicks to 200ms
-                           , clickTarget: ['data-puk', 'data-button'] // array of attribute names to check
-                      })
+short.listShortcuts('editor');
+// ['KEY:CTRL+S', 'CLICK:LEFT-1']
 
-  short.enablePlugin ( pluginHover, {
-                             wait: 500         // set the hover delay to 500ms
-                           , hoverTarget: ['data-hover-me', 'data-interactive'] // array of attribute names to check
-                      })
+short.listShortcuts('does-not-exist'); // null
+```
 
-  short.enablePlugin ( pluginScroll, {
-                             scrollWait: 100      // set the delay between scroll events to 100ms
-                           , endScrollWait: 600   // set the end scroll delay to 600ms
-                           , minSpace: 60         // set minimum distance to 60px
-                      })
 
+
+### `pause(name?)` and `resume(name?)`
+
+Stop / resume listening for shortcuts. Both default to `'*'` (all shortcuts in the active context). The `name` must be a **fully-prefixed** shortcut name (e.g. `'KEY:CTRL+S'`, not `'ctrl+s'`).
+
+- **Returns:** `void`
+- **Emits errors:** none
+- **Side effect:** an in-flight key sequence is dropped on `pause`, not queued for resume.
+
+```js
+short.pause();              // pause all shortcuts in the active context
+short.pause('KEY:CTRL+S');  // pause just one shortcut (use the full prefix!)
+short.resume('KEY:CTRL+S'); // resume just that one
+short.resume('*');          // resume everything
+```
+
+
+
+### `emit(name, ...args)`
+
+Programmatically trigger a shortcut or a custom event. The first argument is the **fully-prefixed** shortcut name (or any custom event string you define — see [Custom Events & Workflows](#custom-events--workflows)). Extra arguments are forwarded to the action function.
+
+- **Returns:** `void`
+- **Emits errors:** none
+
+```js
+short.emit('KEY:CTRL+S');              // fire the save shortcut
+short.emit('CLICK:LEFT-1', myTarget);  // forward a synthetic click
+short.emit('@extend', { source: 'api' }); // fire a custom event
+```
+
+See the [Custom Events & Workflows](#custom-events--workflows) section for full examples of `emit` from inside a handler (`data.dependencies.emit(...)`) and from outside (`short.emit(...)`).
+
+
+
+### `reset()`
+
+Reset the library instance to its initial state. Destroys every enabled plugin, unloads every context, deactivates the current context, and clears the `dependencies` bag. After `reset()`, you can re-`enablePlugin` and re-`load` from scratch.
+
+- **Returns:** `void`
+- **Emits errors:** none
+- **Side effects:** `onShortcut` callback is cleared. `errorEventName` is preserved.
+
+```js
+short.reset();
+// short is now equivalent to a freshly created `shortcuts()` instance
+```
+
+
+
+## Contexts, Notes, and Dependencies
+
+The three orthogonal axes you control from outside the action functions:
+
+- **Context** — which set of shortcuts is active. Use `changeContext` to switch.
+- **Note** — a sub-tag for the current context. Use `setNote` to set, `getNote` to read.
+- **Dependencies** — external services passed into actions. Use `setDependencies` to register, available as `dependencies` in every action.
+
+```js
+short.setDependencies({ api, router });
+short.changeContext('editor');
+short.setNote('draft');
+
+'key:ctrl+s': ({ context, note, dependencies }) => {
+    // context === 'editor'
+    // note === 'draft'
+    // dependencies === { api, router }
+    dependencies.api.save({ context, note });
+}
+```
+
+Read each value from outside the actions with `getContext()`, `getNote()`, `getDependencies()`. Set them with `changeContext()`, `setNote()`, `setDependencies()`.
+
+
+
+## Errors and the `errorEventName` Channel
+
+The library publishes error messages on a single named event instead of throwing. By default that event is named `'@shortcuts-error'`. You can rename it with the `errorEventName` constructor option (see [Constructor Options](#constructor-options)).
+
+Errors currently emitted:
+- `changeContext(name)` — `name` does not exist.
+- `unload(name)` — `name` is the currently active context.
+- `unload(name)` — `name` does not exist.
+
+The message is delivered as the **first argument** to the listener. Because the library uses the [`@peter.naydenov/notice`](https://github.com/PeterNaydenov/notice) event emitter internally, the simplest way to subscribe is to install a listener via the public `emit` channel — but the cleanest way is to handle errors inside your own action handlers (e.g. wrap risky work in `try/catch`).
+
+```js
+const short = shortcuts({ errorEventName: '@my-app-errors' });
+
+// Optional: forward errors anywhere you like.  The library exposes
+// the event emitter indirectly through the action context:
+//   If you need a programmatic hook, expose it via setDependencies:
+// short.setDependencies({
+//     onError: (msg) => myLogger.error(msg)
+// });
+//
+// Then in any handler that can fail:
+// 'key:ctrl+s': ({ dependencies }) => {
+//     try { save() }
+//     catch (e) { dependencies.onError(`Save failed: ${e.message}`) }
+// }
+```
+
+> If you don't need to react to errors at runtime, you can simply ignore this channel — errors are advisory, not fatal.
+
+
+
+## Custom Events & Workflows
+
+Every plugin callback receives a `data` object that includes a `dependencies` bag with an `emit` function — the same event emitter used internally by the library. This lets a handler trigger any other event in the system, so you can build pipelines where one signal chains into another.
+
+### The `data.dependencies.emit` property
+
+The `data` argument passed to your callback contains:
+
+```js
+{
+    // ... event-specific fields (target, key, context, type, etc.)
+    dependencies: {
+        // `emit` is always present — it's the library's event emitter.
+        emit: ev.emit,    // function(eventName, ...args)
+        // ... any other keys you set via short.setDependencies({...})
+    }
+}
+```
+
+`data.dependencies.emit` is a direct reference to the underlying event emitter. Calling it triggers the named event just like `shortcuts.emit(...)` does, but from inside a handler. Any extra values you pass to `short.setDependencies({...})` are merged into this same bag, so a single `data.dependencies` field carries both your application data and the `emit` function.
+
+### Example: chaining a key shortcut into a click
+
+```js
+import { shortcuts, pluginKey, pluginClick } from '@peter.naydenov/shortcuts';
+
+const short = shortcuts();
+short.enablePlugin(pluginKey);
+short.enablePlugin(pluginClick);
+
+short.load({
+    editor: {
+        'key: ctrl+s': (data) => {
+            console.log('Save requested');
+
+            // Trigger a click event on something — for example, a "Save" button
+            data.dependencies.emit('CLICK:LEFT-1', { target: document.getElementById('save-btn') });
+        },
+        'click: left-1': ({ target }) => {
+            if (target?.id === 'save-btn') {
+                console.log('Save button clicked by Ctrl+S');
+                doSave();
+            }
+        }
+    }
+});
+
+short.changeContext('editor');
 ```
 
+### Example: workflow with multiple plugins
 
+You can mix signals from different plugins in a single workflow:
 
-### onShortcut option
 ```js
- function onShortcut ({ shortcut, context, note, dependencies }) {
-        // shortcut - (string) Triggered shortcut name
-        // context - (string) Name of the current context
-        // note - (string) Name of the note or null if note isn't set
-        // dependencies - (object) Object with dependencies that you have set by calling `setDependencies` method
+short.load({
+    main: {
+        'hover : on': (data) => {
+            // show tooltip
+            showTooltip(data.target);
+        },
+        'key: escape': (data) => {
+            // hide any open tooltip by emitting the hover-off signal
+            data.dependencies.emit('HOVER:OFF');
+        }
     }
+});
 ```
 
+### Notes
+
+- The `emit` function lives on `data.dependencies` for every plugin (`key`, `click`, `hover`, `scroll`, `form`);
+- The event name passed to `emit` can be either a fully normalized plugin shortcut (e.g. `KEY:CTRL+S`, `CLICK:LEFT-1`, `SCROLL:DOWN`, `HOVER:ON`, `HOVER:OFF`) or a custom name you define. For form actions, use the `type/timing` key (e.g. `input/in`). See the [Custom Event Names](#custom-event-names-application-level-hooks) section below.
+- This is a *signal source*: any handler in the active context listening for the emitted event will run, including handlers attached to a different plugin. This makes it the foundation for pipelines and multi-step workflows.
+
 
 
-### streamKeys option
+### Custom Event Names (Application-Level Hooks)
+
+The event name you pass to `data.dependencies.emit` does not have to be a plugin shortcut. It can be **any string you invent** — this lets you turn a physical gesture (click, hover, scroll, key) into a custom application signal. Other code, plugins, or modules can listen for that name and react.
+
+Use a prefix that won't collide with plugin shortcuts (e.g. `@`, `app:`, `domain:`):
+
 ```js
- function streamKeys ({ key, context, note, dependencies }) {
-        // key - (string) Pressed key name
-        // context - (string) Name of the current context
-        // note - (string) Name of the note or null if note isn't set
-        // dependencies - (object) Object with dependencies that you have set by calling `setDependencies` method
+import { shortcuts, pluginClick, pluginHover } from '@peter.naydenov/shortcuts';
+
+const short = shortcuts();
+short.enablePlugin(pluginClick);
+short.enablePlugin(pluginHover);
+
+short.load({
+    editor: {
+        // A click anywhere in the editor area triggers the custom "@extend" event.
+        // No keyboard shortcut is involved — only the click.
+        'click: left-1': (data) => {
+            // Forward the click as a custom application event.
+            data.dependencies.emit('@extend', {
+                target : data.target,
+                at     : { x: data.x, y: data.y },
+                when   : Date.now()
+            });
+        },
+
+        // A custom handler listens for "@extend" — this is NOT a plugin shortcut.
+        // It is a hook that other parts of your app can subscribe to.
+        '@extend': ({ target, at, when }) => {
+            console.log('extend requested at', at, 'on', target);
+            doExtend({ target, at, when });
+        },
+
+        // Hover signals also work — you can wire the same hook to multiple gestures:
+        'hover : on': (data) => {
+            data.dependencies.emit('@extend', { target: data.target, source: 'hover' });
+        }
     }
+});
+
+short.changeContext('editor');
+```
+
+**Why this is useful:**
+
+- **Decoupling** — the gesture layer (click/hover/key) is separate from the application logic (`@extend`). You can change which gesture triggers it without touching the handler.
+- **Multiple gestures, one hook** — bind `@extend` to clicks, hovers, key combos, or even `shortcuts.emit('@extend')` from anywhere in your code.
+- **No collision with plugin events** — using a non-plugin prefix (`@`, `app:`, etc.) keeps your custom names from ever being emitted by the library itself.
+
+You can also trigger a custom event from **outside** any handler using the public API:
+
+```js
+// Trigger a custom event programmatically — no plugin involved
+shortcuts.emit('@extend', { source: 'api' });
+// or, if you have a short instance:
+short.emit('@extend', { source: 'api' });
 ```
 
 
@@ -882,19 +1386,24 @@ short.changeContext('myContext');
 
 The `ShortcutsAPI` interface provides full type safety for all methods and their parameters.
 
+
+
 ## Links
 
 - [API reference](https://github.com/PeterNaydenov/shortcuts/blob/main/API.md)
-- [How to make a plugin](https://github.com/PeterNaydenov/shortcuts/blob/main/How.to.make.plugins.md)
-- [ Build a SPA apps with shortcuts (@peter.naydenov/cuts)](https://github.com/PeterNaydenov/cuts )
+- [How to make a plugin](https://github.com/PeterNaydenov/shortcuts/blob/main/How-to-create-a-plugin.md)
+- [Build a SPA apps with shortcuts (@peter.naydenov/cuts)](https://github.com/PeterNaydenov/cuts )
 - [History of changes - changelog](https://github.com/PeterNaydenov/shortcuts/blob/main/Changelog.md)
 - [Migration guide](https://github.com/PeterNaydenov/shortcuts/blob/main/Migration.guide.md)
 
 
+
 ## Credits
+
 '@peter.naydenov/shortcuts' was created and supported by Peter Naydenov.
 
 
 
 ## License
-'@peter.naydenov/shortcuts' is released under the MIT License.
+
+'@peter.naydenov/shortcuts' is released under the MIT License.