ink-cartridge 3.6.1

package/dist/keyboard/hook.d.ts

@@ -0,0 +1,51 @@
+import { KeyboardContextValue } from "./context.js";
+import type { ModalMissCallback, ModalMissOptions } from "./types.js";
+/**
+ * Access the keyboard API from within a React component.
+ *
+ * Returns `{ boundKeyboard, blockedKey, stop, globalKeys, ... }`.
+ *
+ * When called inside an overlay component (wrapped in OverlayContext.Provider),
+ * keyboard bindings are automatically isolated to the overlay's own layer,
+ * keyed by overlay ID. This enables multiple instances of the same component
+ * to coexist as separate overlays with independent keyboard state.
+ *
+ * When called inside a modal component (wrapped in ModalContext.Provider),
+ * the same isolation mechanism applies: bindings are scoped to the modal's
+ * own layer, keyed by modal ID. This is architecturally symmetric to overlay
+ * isolation.
+ *
+ * Must be used inside a {@link KeyboardProvider}.
+ *
+ * @throws If no provider is found in the component tree.
+ */
+export declare function useKeyboard(): KeyboardContextValue;
+/**
+ * Subscribe to the focus state of a named focus target.
+ *
+ * Returns `true` when the target with the given `focusId` is the currently
+ * active focus target on the current screen layer, `false` otherwise.
+ *
+ * Re-renders the component when the focus target changes (via Tab,
+ * `focusSet`, `focusNext`, `focusPrev`, or `focusUnregister`).
+ *
+ * @param focusId The focus target id to watch.
+ * @returns Whether the named target is currently focused.
+ */
+export declare function useFocusState(focusId: string): boolean;
+/**
+ * Subscribe to unhandled key presses inside a modal.
+ *
+ * When the active modal receives a key that was not consumed by any
+ * binding, the callback is invoked. The definition of "consumed" is
+ * controlled by {@link ModalMissOptions}.
+ *
+ * Only functions when called inside a modal component (where
+ * {@link ModalContext} is set). Outside a modal the hook is a silent
+ * no-op — the callback is never invoked.
+ *
+ * @param cb      - Callback invoked on every key press in the modal.
+ * @param options - Controls which mechanics count as "handled".
+ * @returns An unsubscribe function.
+ */
+export declare function useModalMissListener(cb: ModalMissCallback, options?: ModalMissOptions): () => void;

package/dist/keyboard/hook.js

@@ -0,0 +1,105 @@
+import { useContext, useEffect, useState } from "react";
+import { KeyboardContext } from "./context.js";
+import { OverlayContext } from "../screen/OverlayContext.js";
+import { ModalContext } from "../screen/ModalContext.js";
+/**
+ * Access the keyboard API from within a React component.
+ *
+ * Returns `{ boundKeyboard, blockedKey, stop, globalKeys, ... }`.
+ *
+ * When called inside an overlay component (wrapped in OverlayContext.Provider),
+ * keyboard bindings are automatically isolated to the overlay's own layer,
+ * keyed by overlay ID. This enables multiple instances of the same component
+ * to coexist as separate overlays with independent keyboard state.
+ *
+ * When called inside a modal component (wrapped in ModalContext.Provider),
+ * the same isolation mechanism applies: bindings are scoped to the modal's
+ * own layer, keyed by modal ID. This is architecturally symmetric to overlay
+ * isolation.
+ *
+ * Must be used inside a {@link KeyboardProvider}.
+ *
+ * @throws If no provider is found in the component tree.
+ */
+export function useKeyboard() {
+    const ctx = useContext(KeyboardContext);
+    const overlayId = useContext(OverlayContext);
+    const modalId = useContext(ModalContext);
+    if (!ctx) {
+        throw new Error("[Ink-Cartridge] useKeyboard() must be called inside a <KeyboardProvider>.");
+    }
+    // Manage the owner stack for overlay isolation.
+    // When inside an overlay, push the overlay ID as the current owner so
+    // that boundKeyboard, blockedKey, stop, and focus functions operate on
+    // the overlay's own keyboard layer instead of the screen's layer.
+    useEffect(() => {
+        if (overlayId) {
+            ctx._pushOwner(overlayId);
+            return () => {
+                ctx._popOwner(overlayId);
+            };
+        }
+        return;
+    }, [overlayId, ctx._pushOwner, ctx._popOwner]);
+    // Manage the owner stack for modal isolation (symmetric to overlay).
+    // When inside a modal, push the modal ID as the current owner so that
+    // keyboard functions operate on the modal's own layer.
+    useEffect(() => {
+        if (modalId) {
+            ctx._pushOwner(modalId);
+            return () => {
+                ctx._popOwner(modalId);
+            };
+        }
+        return;
+    }, [modalId, ctx._pushOwner, ctx._popOwner]);
+    return ctx;
+}
+/**
+ * Subscribe to the focus state of a named focus target.
+ *
+ * Returns `true` when the target with the given `focusId` is the currently
+ * active focus target on the current screen layer, `false` otherwise.
+ *
+ * Re-renders the component when the focus target changes (via Tab,
+ * `focusSet`, `focusNext`, `focusPrev`, or `focusUnregister`).
+ *
+ * @param focusId The focus target id to watch.
+ * @returns Whether the named target is currently focused.
+ */
+export function useFocusState(focusId) {
+    const { focusCurrent, subscribeFocus } = useKeyboard();
+    const [isFocused, setIsFocused] = useState(() => focusCurrent() === focusId);
+    useEffect(() => {
+        return subscribeFocus(() => {
+            setIsFocused(focusCurrent() === focusId);
+        });
+    }, [focusId, focusCurrent, subscribeFocus]);
+    return isFocused;
+}
+/**
+ * Subscribe to unhandled key presses inside a modal.
+ *
+ * When the active modal receives a key that was not consumed by any
+ * binding, the callback is invoked. The definition of "consumed" is
+ * controlled by {@link ModalMissOptions}.
+ *
+ * Only functions when called inside a modal component (where
+ * {@link ModalContext} is set). Outside a modal the hook is a silent
+ * no-op — the callback is never invoked.
+ *
+ * @param cb      - Callback invoked on every key press in the modal.
+ * @param options - Controls which mechanics count as "handled".
+ * @returns An unsubscribe function.
+ */
+export function useModalMissListener(cb, options) {
+    const ctx = useContext(KeyboardContext);
+    const modalId = useContext(ModalContext);
+    useEffect(() => {
+        if (!ctx || !modalId)
+            return;
+        const unsub = ctx.useModalMissListener(cb, options);
+        return unsub;
+    }, [ctx, modalId, cb, options]);
+    return () => { };
+}

package/dist/keyboard/index.d.ts

@@ -0,0 +1,5 @@
+export { KeyboardProvider } from "./provider.js";
+export type { KeyboardProviderProps } from "./provider.js";
+export { useKeyboard, useFocusState, useModalMissListener } from "./hook.js";
+export { normalizeKeyNames, isNormalCharacter } from "./keyNormalizer.js";
+export type { KeyHandler, BoundKeyboardOptions, BlockedKeyOptions, StopOptions, BoundKeyEntry, ScreenKeyboardLayer, FocusTarget, GlobalKeyEntry, GlobalSequenceEntry, ShortcutOperationEntry, SequenceOperationEntry, SequenceOptions, SequenceBinding, PendingSequence, ModalMissEvent, ModalMissCallback, ModalMissOptions, ResolvedGlobalKeyEntry, } from "./types.js";

package/dist/keyboard/index.js

@@ -0,0 +1,3 @@
+export { KeyboardProvider } from "./provider.js";
+export { useKeyboard, useFocusState, useModalMissListener } from "./hook.js";
+export { normalizeKeyNames, isNormalCharacter } from "./keyNormalizer.js";

package/dist/keyboard/keyNormalizer.d.ts

@@ -0,0 +1,37 @@
+import type { Key } from 'ink';
+/**
+ * Convert an Ink `(input, key)` event into a list of possible key-name
+ * strings for matching.
+ *
+ * For special keys (return, escape, arrows, etc.) it produces the base
+ * name plus any modifier-prefixed variants.  For character keys it
+ * produces the raw character and modifier combinations.
+ *
+ * Examples:
+ *   press('s', { ctrl: true })              →  ["s", "ctrl+s"]
+ *   press('',  { escape: true })            →  ["escape"]
+ *   press('',  { return: true, shift: true }) → ["return", "shift+return"]
+ *
+ * @param input - Raw character string from Ink's useInput (empty for special keys).
+ * @param key   - Full Key descriptor from Ink.
+ * @returns An ordered array of key-name strings; first match wins in the pipeline.
+ */
+export declare function normalizeKeyNames(input: string, key: Key): string[];
+/**
+ * Determine whether the Ink key event represents a "normal" character.
+ *
+ * Only input with actual character content is eligible, and all special
+ * keys (arrows, return, escape, tab, backspace, delete, pageup, pagedown,
+ * home, end), modifier keys (ctrl, meta, super, hyper), and release events
+ * are excluded.
+ *
+ * This function drives the wildcard `"*"` binding — only normal characters
+ * are ever matched by the wildcard.
+ *
+ * @param input - Raw character from Ink's useInput.
+ * @param key   - Full Key descriptor from Ink.
+ * @returns true when the event should be treated as a normal character.
+ *
+ * @2026-06-14 v3.4.0
+ */
+export declare function isNormalCharacter(input: string, key: Key): boolean;

package/dist/keyboard/keyNormalizer.js

@@ -0,0 +1,119 @@
+/**
+ * Convert an Ink `(input, key)` event into a list of possible key-name
+ * strings for matching.
+ *
+ * For special keys (return, escape, arrows, etc.) it produces the base
+ * name plus any modifier-prefixed variants.  For character keys it
+ * produces the raw character and modifier combinations.
+ *
+ * Examples:
+ *   press('s', { ctrl: true })              →  ["s", "ctrl+s"]
+ *   press('',  { escape: true })            →  ["escape"]
+ *   press('',  { return: true, shift: true }) → ["return", "shift+return"]
+ *
+ * @param input - Raw character string from Ink's useInput (empty for special keys).
+ * @param key   - Full Key descriptor from Ink.
+ * @returns An ordered array of key-name strings; first match wins in the pipeline.
+ */
+export function normalizeKeyNames(input, key) {
+    const names = [];
+    const specialMap = [
+        ['return', 'return'],
+        ['escape', 'escape'],
+        ['backspace', 'backspace'],
+        ['delete', 'delete'],
+        ['upArrow', 'up'],
+        ['downArrow', 'down'],
+        ['leftArrow', 'left'],
+        ['rightArrow', 'right'],
+        ['tab', 'tab'],
+        ['pageDown', 'pagedown'],
+        ['pageUp', 'pageup'],
+        ['home', 'home'],
+        ['end', 'end'],
+    ];
+    for (const [kProp, kName] of specialMap) {
+        if (key[kProp]) {
+            names.push(kName);
+            if (key.ctrl)
+                names.push(`ctrl+${kName}`);
+            if (key.shift)
+                names.push(`shift+${kName}`);
+            if (key.meta)
+                names.push(`meta+${kName}`);
+            if (key.ctrl && key.shift)
+                names.push(`ctrl+shift+${kName}`);
+            return names;
+        }
+    }
+    if (input) {
+        names.push(input);
+        if (key.ctrl)
+            names.push(`ctrl+${input}`);
+        if (key.shift)
+            names.push(`shift+${input}`);
+        if (key.meta)
+            names.push(`meta+${input}`);
+        if (key.ctrl && key.shift)
+            names.push(`ctrl+shift+${input}`);
+    }
+    return names;
+}
+/**
+ * Determine whether the Ink key event represents a "normal" character.
+ *
+ * Only input with actual character content is eligible, and all special
+ * keys (arrows, return, escape, tab, backspace, delete, pageup, pagedown,
+ * home, end), modifier keys (ctrl, meta, super, hyper), and release events
+ * are excluded.
+ *
+ * This function drives the wildcard `"*"` binding — only normal characters
+ * are ever matched by the wildcard.
+ *
+ * @param input - Raw character from Ink's useInput.
+ * @param key   - Full Key descriptor from Ink.
+ * @returns true when the event should be treated as a normal character.
+ *
+ * @2026-06-14 v3.4.0
+ */
+export function isNormalCharacter(input, key) {
+    if (!input)
+        return false;
+    if (key.upArrow)
+        return false;
+    if (key.downArrow)
+        return false;
+    if (key.leftArrow)
+        return false;
+    if (key.rightArrow)
+        return false;
+    if (key.pageDown)
+        return false;
+    if (key.pageUp)
+        return false;
+    if (key.home)
+        return false;
+    if (key.end)
+        return false;
+    if (key.return)
+        return false;
+    if (key.escape)
+        return false;
+    if (key.tab)
+        return false;
+    if (key.backspace)
+        return false;
+    if (key.delete)
+        return false;
+    if (key.ctrl)
+        return false;
+    if (key.meta)
+        return false;
+    if (key.super)
+        return false;
+    if (key.hyper)
+        return false;
+    if (key.eventType === 'release')
+        return false;
+    return true;
+}

package/dist/keyboard/layer-handler.d.ts

@@ -0,0 +1,57 @@
+import type { Key } from 'ink';
+import type { ScreenKeyboardLayer, BoundKeyEntry, KeyRule } from './types.js';
+/**
+ * Check whether a normalized key name is covered by a list of key rules.
+ *
+ * A key is covered when any rule's key matches, AND the rule either has no
+ * `when` condition or the condition evaluates to `true`. When all matching
+ * rules have `when` returning `false`, the key is NOT covered.
+ */
+export declare function keyMatchesRule(keyName: string, rules: KeyRule[]): boolean;
+/**
+ * Iterate through a list of bindings and fire the first matching handler.
+ *
+ * Matches exact key names first, then falls back to the wildcard `"*"` binding
+ * for normal character input (see {@link isNormalCharacter}).
+ *
+ * A binding fires only when ALL of the following are satisfied (AND relationship):
+ *   1. `skipBinding` returns `false` / absent (covers `onlyThis`)
+ *   2. `when` returns `true` / absent (covers conditional enablement)
+ *   3. Key name matches one in `binding.keys`
+ *
+ * The short-circuit evaluation order is skipBinding → when → keyMatch.
+ * This order does NOT create priority among the conditions — they are
+ * logical AND peers. Whether skipBinding is checked before or after when,
+ * all must pass for the binding to fire.
+ *
+ * @param bindings      Ordered list of key bindings to try.
+ * @param unblockedKeys Normalized key names not blocked at this layer.
+ * @param input         Raw character from Ink's useInput.
+ * @param key           Full Key descriptor from Ink.
+ * @param skipBinding   Optional predicate to skip individual bindings
+ *                      (used for `onlyThis` enforcement).
+ * @returns `true` if a binding matched and consumed the event.
+ */
+export declare function tryMatchBindings(bindings: BoundKeyEntry[], unblockedKeys: string[], input: string, key: Key, skipBinding?: (binding: BoundKeyEntry) => boolean): boolean;
+/**
+ * Built-in Tab / Shift+Tab focus rotation for a given layer.
+ *
+ * Cycles {@link ScreenKeyboardLayer.currentFocusId} through the layer's
+ * {@link ScreenKeyboardLayer.focusOrder} list (Tab forward, Shift+Tab backward).
+ * Wraps around at both ends.
+ *
+ * @returns `true` if a tab event was handled and focus was moved.
+ */
+export declare function handleTabNavigation(layer: ScreenKeyboardLayer, eventNames: string[], shift: boolean, notifyFocusChange: () => void): boolean;
+/**
+ * Handle a keyboard event against a single layer.
+ *
+ * Evaluates tab navigation, blocked keys, wildcard priority, sequence
+ * matching, focus-target bindings, layer-level bindings, and stopped
+ * keys — in that order.
+ *
+ * @returns true if the event was consumed by this layer.
+ *
+ * @2026-06-14 v3.4.0
+ */
+export declare function handleLayer(layer: ScreenKeyboardLayer, eventNames: string[], input: string, key: Key, isTop: boolean, notifyFocusChange: () => void, activeOverlayCount: number, isOverlay: boolean, wildcardFirst: boolean): boolean;

package/dist/keyboard/layer-handler.js

@@ -0,0 +1,274 @@
+import { isNormalCharacter } from './keyNormalizer.js';
+const DEFAULT_SEQUENCE_TIMEOUT = 500;
+/**
+ * Check whether a normalized key name is covered by a list of key rules.
+ *
+ * A key is covered when any rule's key matches, AND the rule either has no
+ * `when` condition or the condition evaluates to `true`. When all matching
+ * rules have `when` returning `false`, the key is NOT covered.
+ */
+export function keyMatchesRule(keyName, rules) {
+    for (const rule of rules) {
+        if (rule.key === keyName) {
+            if (!rule.when || rule.when())
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Iterate through a list of bindings and fire the first matching handler.
+ *
+ * Matches exact key names first, then falls back to the wildcard `"*"` binding
+ * for normal character input (see {@link isNormalCharacter}).
+ *
+ * A binding fires only when ALL of the following are satisfied (AND relationship):
+ *   1. `skipBinding` returns `false` / absent (covers `onlyThis`)
+ *   2. `when` returns `true` / absent (covers conditional enablement)
+ *   3. Key name matches one in `binding.keys`
+ *
+ * The short-circuit evaluation order is skipBinding → when → keyMatch.
+ * This order does NOT create priority among the conditions — they are
+ * logical AND peers. Whether skipBinding is checked before or after when,
+ * all must pass for the binding to fire.
+ *
+ * @param bindings      Ordered list of key bindings to try.
+ * @param unblockedKeys Normalized key names not blocked at this layer.
+ * @param input         Raw character from Ink's useInput.
+ * @param key           Full Key descriptor from Ink.
+ * @param skipBinding   Optional predicate to skip individual bindings
+ *                      (used for `onlyThis` enforcement).
+ * @returns `true` if a binding matched and consumed the event.
+ */
+export function tryMatchBindings(bindings, unblockedKeys, input, key, skipBinding) {
+    if (unblockedKeys.length === 0)
+        return false;
+    for (const binding of bindings) {
+        if (skipBinding && skipBinding(binding))
+            continue;
+        if (binding.when?.() === false)
+            continue;
+        if (binding.keys.some((k) => unblockedKeys.includes(k))) {
+            binding.handler(input, key);
+            return true;
+        }
+    }
+    const wildcardBinding = bindings.find(b => b.keys.includes('*'));
+    if (wildcardBinding && isNormalCharacter(input, key)) {
+        if (!skipBinding || !skipBinding(wildcardBinding)) {
+            if (wildcardBinding.when?.() === false)
+                return false;
+            wildcardBinding.handler(input, key);
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Built-in Tab / Shift+Tab focus rotation for a given layer.
+ *
+ * Cycles {@link ScreenKeyboardLayer.currentFocusId} through the layer's
+ * {@link ScreenKeyboardLayer.focusOrder} list (Tab forward, Shift+Tab backward).
+ * Wraps around at both ends.
+ *
+ * @returns `true` if a tab event was handled and focus was moved.
+ */
+export function handleTabNavigation(layer, eventNames, shift, notifyFocusChange) {
+    if (!eventNames.includes('tab') || layer.focusOrder.length === 0)
+        return false;
+    const current = layer.currentFocusId;
+    let idx = current ? layer.focusOrder.indexOf(current) : -1;
+    if (shift) {
+        idx = idx <= 0 ? layer.focusOrder.length - 1 : idx - 1;
+    }
+    else {
+        idx = (idx + 1) % layer.focusOrder.length;
+    }
+    layer.currentFocusId = layer.focusOrder[idx];
+    notifyFocusChange();
+    return true;
+}
+/**
+ * Handle a keyboard event against a single layer.
+ *
+ * Evaluates tab navigation, blocked keys, wildcard priority, sequence
+ * matching, focus-target bindings, layer-level bindings, and stopped
+ * keys — in that order.
+ *
+ * @returns true if the event was consumed by this layer.
+ *
+ * @2026-06-14 v3.4.0
+ */
+export function handleLayer(layer, eventNames, input, key, isTop, notifyFocusChange, activeOverlayCount, isOverlay, wildcardFirst) {
+    // The reason it has the highest priority is to ensure that tab/shift+tab have the highest priority, avoiding conflicts with business-bound actions.
+    // However, when there is no Focus Target in the Current Screen, handleTabNavigation will return false, which allows users to retain flexibility. When tab/shift+tab do not need to be enforced,
+    // they can also be bound to business-specific keys.
+    if (isTop && handleTabNavigation(layer, eventNames, key.shift, notifyFocusChange))
+        return true;
+    const blocked = layer.blockedKeys;
+    const unblocked = eventNames.filter((n) => !keyMatchesRule(n, blocked));
+    // onlyThis semantics differ between screens and overlays:
+    // - Screen: skip when any overlay is active (activeOverlayCount > 0)
+    // - Overlay: skip only when multiple overlays compete (activeOverlayCount > 1)
+    const shouldSkipOnlyThis = (b) => {
+        if (!b.onlyThis)
+            return false;
+        if (isOverlay)
+            return activeOverlayCount > 1;
+        return activeOverlayCount > 0;
+    };
+    // Wildcard priority pre-check: when enabled, wildcard `*` bindings
+    // are evaluated before sequences, exact matches, and everything else.
+    // Only normal characters are affected — special keys fall through.
+    if (isTop && wildcardFirst && unblocked.length > 0) {
+        // Check focus-target wildcard first
+        if (layer.currentFocusId) {
+            const ft = layer.focusTargets.get(layer.currentFocusId);
+            if (ft) {
+                const fBlocked = ft.blockedKeys;
+                const fUnblocked = unblocked.filter(n => !keyMatchesRule(n, fBlocked));
+                if (fUnblocked.length > 0) {
+                    const wb = ft.bindings.find(b => b.keys.includes('*'));
+                    if (wb && isNormalCharacter(input, key)) {
+                        if (wb.when?.() === false) { /* skip */ }
+                        else if (!shouldSkipOnlyThis(wb)) {
+                            wb.handler(input, key);
+                            return true;
+                        }
+                    }
+                }
+            }
+        }
+        // Check screen-level wildcard
+        const wb = layer.bindings.find(b => b.keys.includes('*'));
+        if (wb && isNormalCharacter(input, key)) {
+            if (wb.when?.() === false) { /* skip */ }
+            else if (!shouldSkipOnlyThis(wb)) {
+                wb.handler(input, key);
+                return true;
+            }
+        }
+    }
+    // Sequence matching: only for the top layer (isTop).
+    // Sequences have priority over ordinary boundKeyboard bindings.
+    if (isTop && unblocked.length > 0) {
+        const pending = layer.pendingSequence;
+        // We already have a pending sequence in progress.
+        if (pending !== null) {
+            // If the when condition changed to false mid-sequence, cancel
+            // the pending sequence and let the key fall through to normal processing.
+            if (pending.when?.() === false) {
+                clearTimeout(pending.timer);
+                layer.pendingSequence = null;
+                // Fall through to normal bindings — do NOT return true.
+            }
+            else {
+                const expectedKey = pending.sequences[pending.nextIndex];
+                if (unblocked.includes(expectedKey)) {
+                    // Matched the next key in the sequence.
+                    clearTimeout(pending.timer);
+                    pending.nextIndex++;
+                    if (pending.nextIndex === pending.sequences.length) {
+                        // Full sequence matched — fire handler.
+                        pending.handler(input, key);
+                        layer.pendingSequence = null;
+                    }
+                    else {
+                        // Still waiting for more keys — restart the timeout.
+                        pending.timer = setTimeout(() => {
+                            if (layer.pendingSequence === pending)
+                                layer.pendingSequence = null;
+                        }, pending.timeout);
+                    }
+                    return true;
+                }
+                else {
+                    // Mismatch.
+                    if (pending.options?.exclusive === true) {
+                        // Exclusive mode: ignore the key, keep waiting.
+                        return true;
+                    }
+                    else {
+                        // Non-exclusive (default): cancel the sequence and let the key
+                        // fall through to normal bindings.
+                        clearTimeout(pending.timer);
+                        layer.pendingSequence = null;
+                    }
+                }
+            }
+        }
+        // No pending sequence — try to start a new one from the first unblocked key.
+        if (layer.pendingSequence === null) {
+            // Check each unblocked key name (not just the first) to handle
+            // modifier combinations like 'ctrl+w' which appear after 'w'.
+            for (const keyName of unblocked) {
+                // When ctrl/meta modifier is held (but not shift), a bare key name
+                // (without '+') does not represent the keystroke the user intended.
+                // normalizeKeyNames expands ctrl+d into ['d', 'ctrl+d']; matching 'd'
+                // here would incorrectly start a ['d', 'v'] sequence instead of
+                // letting boundKeyboard(['ctrl+d'], ...) consume the event.
+                // Shift is exempt because it changes the character (d → D), so the
+                // bare key name 'D' faithfully represents shift+d.
+                // @2026-06-23 v3.6.1
+                if ((key.ctrl || key.meta) && !keyName.includes('+')) {
+                    continue;
+                }
+                const candidates = layer.sequences.get(keyName);
+                if (!candidates || candidates.length === 0)
+                    continue;
+                // Filter by onlyThis, focusId, and when constraints.
+                const selected = candidates.find(binding => {
+                    if (binding.options?.onlyThis) {
+                        if (isOverlay)
+                            return activeOverlayCount <= 1;
+                        else
+                            return activeOverlayCount === 0;
+                    }
+                    if (binding.options?.focusId) {
+                        return layer.currentFocusId === binding.options.focusId;
+                    }
+                    if (binding.when?.() === false)
+                        return false;
+                    return true;
+                });
+                if (selected) {
+                    const timeout = selected.timeout ?? DEFAULT_SEQUENCE_TIMEOUT;
+                    const newSeq = {
+                        sequences: selected.keys,
+                        nextIndex: 1,
+                        handler: selected.handler,
+                        timer: undefined,
+                        timeout,
+                        options: selected.options,
+                        when: selected.when,
+                    };
+                    const timer = setTimeout(() => {
+                        if (layer.pendingSequence === newSeq)
+                            layer.pendingSequence = null;
+                    }, timeout);
+                    newSeq.timer = timer;
+                    layer.pendingSequence = newSeq;
+                    return true;
+                }
+            }
+        }
+    }
+    if (isTop && layer.currentFocusId) {
+        const ft = layer.focusTargets.get(layer.currentFocusId);
+        if (ft) {
+            const fBlocked = ft.blockedKeys;
+            const fUnblocked = unblocked.filter((n) => !keyMatchesRule(n, fBlocked));
+            if (tryMatchBindings(ft.bindings, fUnblocked, input, key, shouldSkipOnlyThis))
+                return true;
+            if (eventNames.some((n) => keyMatchesRule(n, ft.stoppedKeys))) {
+                return true;
+            }
+        }
+    }
+    if (tryMatchBindings(layer.bindings, unblocked, input, key, shouldSkipOnlyThis))
+        return true;
+    if (isTop && eventNames.some((n) => keyMatchesRule(n, layer.stoppedKeys))) {
+        return true;
+    }
+    return false;
+}

package/dist/keyboard/modal-processor/index.d.ts

@@ -0,0 +1,16 @@
+import type { PipelineProcessor } from '../types.js';
+/**
+ * Create a processor for the modal stage (stage 0 — highest priority).
+ *
+ * When a modal is active (activeModalId is set), the modal's keyboard layer
+ * receives the event. The processor always returns `true`, consuming every
+ * event — even keys not bound in the modal — so that no event reaches
+ * lower-priority stages (global keys, overlays, or screens).
+ *
+ * Before blocking, if the layer has an {@link ScreenKeyboardLayer.onMiss}
+ * callback registered (via {@link useModalMissListener}), the processor
+ * determines whether the key was handled or missed and invokes the callback.
+ *
+ * @returns A PipelineProcessor for the modal stage.
+ */
+export declare function createModalProcessor(): PipelineProcessor;