Class KeyboardEngine<TComponent>

Create a new engine instance.

Builds the internal state tree: EngineState (path, layer/modal-layer ids, modes, conditions, global keys/sequences, operation registries, owner stack), LayerManager, PipelineManager (the built-in 9-stage chain plus any custom processors), BindingService, OperationRegistry and the CompositionEngine (initialized with defaultTimeout and valueSchema).

The instance is meant to persist for the lifetime of the host component — store it in a stable reference (e.g. useRef in React, a class field in Vue/Svelte).

The composition engine for composing multi-key compound actions.

Cancel the current composition chain immediately.

Activate a focus target in a group that currently has no active focus.

Unlike focusSet — which replaces a group's active target — this method only succeeds when the group has no active entry yet. It is designed for lazy activation: register focus targets early, then call activateFocusGroup to give a group its initial focus on demand without overwriting focus that was already established.

Returns false (no-op) when the group already has an active target, or when the owner, layer, group, or focus target is absent. Use focusSet when you need to switch a group's active target regardless of its current state.

Re-activate a previously kicked built-in processor by removing it from the disabled list. The processor resumes normal operation on the next processKey call.

When a processor is actively processing events (i.e. not in the disabled list), calling activeProcessor is a no-op that returns false.

Add a single shortcut action.

Register a named condition for when: "conditionId" references.

Register a mapping key entry. See CompositionEngine#addMapping.

Register a mode name. Modes must be registered before use in setMode, nextMode, or prevMode.

Insert a processor into this instance's pipeline at a specified position.

Options (checked in order):

• { index: n } — insert at 0-based index
• { before: "id" } / { after: "id" } — insert relative to a named processor
• omitted — append to the end

Add a single sequence action.

Allow specific keys to pass through the modal barrier. By default the active modal consumes every key event — even unbound keys. Adding a key to the allow list releases it to lower pipeline stages.

This is the only mechanism by which keys can escape the modal barrier. In the modal pipeline stage (stage 0), allowedKeys is checked before any other processing: a matching key (whose when evaluates to true) makes the modal processor return false, so the event continues to the global/layer/page stages below. Keys released this way count as unhandled ("miss") for useModalMissListener when nothing else consumes them.

Bind one or more keys to a handler on the current owner's layer.

Supports three calling conventions:

1. boundKeyboard(keys, handler, options?) — explicit keys and callback
2. boundKeyboard(keys, actionId, options?) — explicit keys, shortcut action by id
3. boundKeyboard(actionId, options?) — uses the shortcut action's preset keys

Storage follows the options: with elementId the binding is stored on that element's keyboard data; with focusId on the named FocusTarget.bindings array; with neither, on the page layer's bindings array (or the element keyboard's bindings inside a layer/modal layer). Element bindings are evaluated in the layer broadcast stage and the modal stage; page-level bindings in the screen-stack stage, after global keys and layer broadcast. Within a keyboard layer, focus-target bindings are checked before layer-level bindings.

Options behavior:

• once — auto-remove after the first invocation; the unbind happens before the handler runs
• times / observer — the handler fires after times presses; the counter resets after the handler runs, and observer is called on each press while counting (requires times)
• when — a condition function or a registered condition id (see addCondition); the binding is skipped when it evaluates to false
• mode — restricts the binding to a specific mode; skipped when the active mode doesn't match
• stopsWorkingAfterLayerAppearing — page-level bindings only: when any layer is present the page binding stops responding; has no effect inside a layer

Register a multi-key sequence binding on the current owner's layer.

When the first key of a registered sequence is pressed, the layer enters a pending state. Subsequent key presses are matched against the remaining keys; when all match within the timeout the handler fires. A mismatched key cancels the sequence (default) or is silently consumed (exclusive: true). The when condition (callback or registered condition id) is checked at each key press — if it returns false, the pending sequence is cancelled.

Supports three calling conventions:

1. boundSequence(keys, handler, options?) — explicit keys and callback
2. boundSequence(keys, actionId, options?) — explicit keys, sequence action by id (the action's callback is resolved at registration time)
3. boundSequence(actionId, options?) — uses the action's preset keys

The sequence timeout defaults to 500 ms — the timer starts on the first key and resets on each match. Unbinding while a sequence is pending does not cancel it.

Throws if fewer than 2 keys are provided, if the first key conflicts with a global sequence that has cover: false, or if observer is set without times.

Number of completed sequences available for undo.

Build a snapshot of all mutable state needed to process a single key event through the pipeline.

Called by processKey once per key event. All values are read synchronously to produce a consistent frozen-in-time view.

The returned object is cast to PipelineContext because the engine's generic TComponent may not match the legacy React.ComponentType in the typed interface — this is a bridge point that will be resolved when the pipeline types are fully generic.

Remove keyboard layers for screens that are no longer in the current path.

This is the cleanup side of the sync lifecycle: sync pushes new state, these methods remove stale state from the previous render cycle. Designed to be called in a post-render effect (e.g. useEffect in React) so they compare against the state pushed by the most recent sync.

Also clears any pending sequence timers on removed layers to prevent stale timeouts from firing after the layer is gone.

Remove element keyboards for modal layers that have been closed. Only cleans keyboards whose modal-layer owner is no longer present in the synced modalLayers state.

Remove element keyboards for layers that have been closed. Only cleans keyboards whose layer owner is no longer present in the synced layers state — pages and modal layers are left untouched.

Clear all registered composition keys.

Clear all buffered undo history.

Clear all registered sequence operations.

Clear all registered shortcut operations.

Check whether the current owner's layer has an active pending multi-key sequence (registered via boundSequence). Unlike thereGlobalQueueWaiting, this only checks the layer belonging to the current owner — the page, layer, or modal layer that owns the active keyboard data. Use this to show sequence-progress hints (like Vim's pending key display).

When a sync callback is provided it is added to the same pending-sync set used by thereGlobalQueueWaiting and fires after each processKey invocation.

Register named sequence actions.

Register named shortcut actions that can be referenced by key bindings via string identifier instead of inline callbacks.

Enable wildcard-priority mode. In this mode, "*" (wildcard) bindings take absolute priority over exact-key matches.

By default exact-key bindings ("return", "ctrl+s") are checked before wildcard bindings; with this mode the order is reversed so "*" bindings fire first. Essential for screens that must intercept every key press (e.g. a text input capturing all printable characters).

Uses reference counting: multiple callers can enable independently. Mode disables when all callers have called the returned disable function.

Query the currently active focus target for a group.

Returns a discriminated union rather than a bare id so callers can distinguish the "no owner / no layer / no focus / result" cases without guessing. Check .result?.id for the active focus id, or one of .noOwner / .noLayer / .noFound for the empty cases.

Cycle to the next focus target within a group (Tab semantics).

Wraps around. When group is omitted, cycles the default group's defaultFocusOrder; otherwise cycles the named group's registration order. Only switches the active target — does not activate a group that has no current focus.

Cycle to the previous focus target within a group (Shift+Tab semantics).

Wraps around. See focusNext for the group parameter behavior.

Activate a named focus target on the current owner's layer.

When group is omitted, the target is looked up in the layer's default focus group (defaultTargetsSymbol). When group is provided, the target is looked up in the named group — each group tracks its own active focus independently, so multiple groups can hold focus simultaneously.

Remove a focus target from the current owner's layer.

If the removed target was the active one for its group, the first remaining target (in registration order) is auto-activated. When no targets remain in the group, that group's focus slot is cleared.

Silently no-ops when the target or group is absent on the current layer — during unmount, sync() has already advanced the path to the new screen, so the focusId lives on the unmounting screen's layer (which cleanLayers() removes shortly after).

Return a copy of the current composition context.

Return the most recent composition event. See CompositionEngine#getLastEvent.

Return the most recent mapping-key event. See CompositionEngine#getLastMappingEvent.

Register global key bindings. Global keys fire independently of the screen stack, subject to category whitelist and affectLayer placement.

Evaluated at pipeline stages 3 and 7 — above the layer stage when affectLayer: true, below it otherwise. Entries are matched in registration order — the first match wins. Use this for application-wide shortcuts (quit, toggle dev tools, switch language) that should work on every screen. When cover is false, screens and layer elements cannot override the key via boundKeyboard.

When operate is a string, it is resolved to a registered shortcut action. Press-count tracking (times/pressCount) is initialized for entries with times.

Register global sequence key bindings. Global sequences fire independently of the screen stack with higher priority than global keys.

Evaluated at pipeline stages 2 and 6 — just above the global-key stages. When the first key of any registered sequence matches, the engine creates a pending global sequence and waits for subsequent keys within the sequence timeout (default 500 ms). On a full match the handler fires and the pending state clears; a mismatched key cancels the sequence (default) or is silently consumed (exclusive: true). Use these for application-wide key chords (like Vim-style g g to scroll to top).

When operate is a string, it resolves to a registered sequence action. In 'replace' mode (default), any active pending global sequence is cancelled before replacement.

Whether a composition chain is currently pending.

Remove a group's active focus entry from the current owner's layer.

Kicks the entire group out of the active focus slots — the specific focusId doesn't matter. After removal the group has no active focus until activateFocusGroup, focusSet, or an auto-select re-establishes one.

Returns false when the owner has no layer, the group is not registered, or the group is not currently active. Does not unregister the group's focus targets — bindings remain intact.

De-activate a built-in processor by adding it to a disabled list. The processor is skipped on the next processKey call — its process() method returns false immediately without running any logic. Later pipeline stages receive key events as if the kicked stage did not exist.

This does NOT remove the processor from the pipeline — it only disables its runtime behavior. The processor still appears in getProcessors. A kicked processor can be re-enabled at any time via activeProcessor.

Use this for temporarily suppressing a pipeline stage (e.g. disable the modal barrier, mute global keys) without permanently altering the pipeline structure.

Modify the default keys of an existing shortcut action.

Modify the keys (and optionally timeout) of an existing sequence action.

Cycle to the next mode in registration order. Wraps around.

Mark keys as transparent on the current layer. When a transparent key reaches the layer (or the named focus target), the layer's own bindings are skipped and the key continues to layers below.

Penetration means pass-through, not blocking — the key is only released, never consumed. Penetration rules are checked first during key matching (layer broadcast and screen-stack stages), so a key that is both stopped and penetrated on the same layer passes through. A wildcard "*" entry marks all keys transparent, and a when condition (callback or registered condition id) gates the rule — when it evaluates to false the penetration rule is ignored.

Remove the most recent matching owner from the stack. Uses lastIndexOf so nested owners of the same layer unwind correctly.

Cycle to the previous mode in registration order. Wraps around.

Process a keyboard event through the full processor pipeline.

Builds a snapshot context from the engine's current state, then runs each processor in order. The first processor that returns true (event consumed) stops the chain. The pipeline order is:

modal → composition (affectOverlay: true) → global sequence (affectLayer: true) → global keys (affectLayer: true) → layer broadcast → composition (affectOverlay: false) → global sequence (affectLayer: false) → global keys (affectLayer: false) → screen stack.

processKey itself only orchestrates the chain — side effects are produced by the individual processors, which may mutate layers (e.g. unbind once bindings), pending sequence state, focus targets, composition context, or press-count counters. After the chain finishes, pending sync callbacks registered via thereGlobalQueueWaiting and currentScreenHasSequenceWaiting are notified so the host framework can re-render.

Process a mouse event through the mouse region hit-testing.

move events drive hover transitions (onEnter/onLeave); click events fire onClick; wheel events fire onWheel. press/drag/ release events drive the drag lifecycle: a press inside a region arms a drag capture that the first drag event promotes (onDragStart/ onDragMove), and release fires onDragEnd — only when a real drag happened; plain clicks stay silent.

Push a new owner onto the owner stack so that keyboard bindings in a layer or modal element are attributed to that layer rather than the current top layer.

The "current owner" is the top of the stack — every call to boundKeyboard, boundSequence, penetration, stop, etc. registers on the layer belonging to the current owner. Layer and modal-layer rendering code pushes the layer/modal-layer id while rendering its children and pops it afterwards.

Read a layer without creating it. Returns undefined when no layer exists for the given owner.

Unlike the other binding functions (which lazily create a layer when the owner is missing), readLayer is strictly read-only.

Read a layer without creating it. Returns undefined when no layer exists for the given owner.

Unlike the other binding functions (which lazily create a layer when the owner is missing), readLayer is strictly read-only.

Read a layer without creating it. Returns undefined when no layer exists for the given owner.

Unlike the other binding functions (which lazily create a layer when the owner is missing), readLayer is strictly read-only.

Register a mouse region for hit-testing.

The region's layerId must match a synced layer id so hit priority follows the same modal > layer > root order as keyboard events: while any modal is open, only the topmost modal layer is hit-tested, and a miss on it is dead (no fall-through). regionId is a caller-chosen unique identifier for the region within that layer — it is independent of keyboard element ids. rect must be in 1-based terminal coordinates.

Within a layer, later registrations win; a priority in the region entry overrides registration order (used for child controls like buttons).

Register a composition key entry. See CompositionEngine#registryCompositionKey.

Remove a registered shortcut action.

Remove all composition entries registered under key. See CompositionEngine#removeCompositionKey.

Remove all mapping key entries whose head key matches firstKey. See CompositionEngine#removeMapping.

Remove a mapping key entry by its exact key sequence. See CompositionEngine#removeMappingKey.

Remove a processor from this instance's pipeline by its id.

Remove a registered sequence action.

Restore the processor pipeline to the default 9-stage chain.

Update a condition's value. Bindings referencing this condition via when: "id" use the new value on the next key event.

Switch to a specific mode. Pass null to exit all modes.

Set or replace the runtime value schema for composition chain validation. See CompositionEngine#setValueSchema.

Prevent keys from propagating beyond the current layer. A "stop barrier" means: once a key reaches this layer, even if no binding handles it, it does not fall through to layers below. Stop rules are checked after bindings and penetrations, and a when condition (callback or registered condition id) gates the rule — when it evaluates to false the key propagates normally. A wildcard "*" entry stops all keys.

stopAction: true treats keys as shortcut action IDs: the stop rule is stored against the action id and resolved to the action's current bound keys at match time, so re-binding the action moves the barrier automatically.

Subscribe to composition state changes. See CompositionEngine#subscribe.

Subscribe to focus changes. Returns an unsubscribe function. Use this in UI frameworks to track when the active focus target moves (e.g. Tab navigation, programmatic focusSet).

Subscribe to mapping-key state changes. See CompositionEngine#subscribeMapping. Independent from subscribeComposition — mapping events do not fire composition subscribers and vice versa.

Push page-path, layer, and modal-layer state into the engine.

The engine does not observe the host framework's component tree — it relies on sync being called on every render to build an accurate snapshot. Call this synchronously on every render (before any keyboard events) so that processKey reads a fresh snapshot. Cleanup methods (cleanLayers, etc.) should be called in a post-render effect so they compare the pre- and post-sync state.

The write is a direct field assignment — no merging, no diffing, no incremental update. layers and modalLayers are expected sorted by zIndex ascending.

Check whether a global multi-key sequence is currently pending (i.e. the first key was pressed and the engine is waiting for subsequent keys or a timeout).

This is a "pull" API — it reads the pending state on demand, equivalent to getGlobalPendingSequence() !== null. Pass a sync callback to make it "push": the engine invokes the callback after every processKey invocation, letting the host framework re-render when the pending state changes.

Undo one or more completed composition sequences. See CompositionEngine#undo.

Remove a mouse region by layerId + regionId (idempotent). Needed for unmount cleanup when a region may have been re-registered multiple times via registerMouseRegion.

Update a composition entry identified by key + flag. See CompositionEngine#updateCompositionKey.

Subscribe to unhandled key presses inside a modal. The callback receives { miss: false } when the key was handled, or { miss: true, key, input, eventNames } when nothing consumed it.