ink-cartridge 3.6.1

package/dist/keyboard/context.d.ts

@@ -0,0 +1,398 @@
+import type { KeyHandler, BoundKeyboardOptions, BlockedKeyOptions, StopOptions, GlobalKeyEntry, GlobalSequenceEntry, ShortcutOperationEntry, SequenceOperationEntry, SequenceOptions, ModalMissCallback, ModalMissOptions, ResolvedGlobalKeyEntry } from "./types.js";
+/**
+ * Type for the owner stack used to track overlay context.
+ * Can be a component type (for screens) or a string (for overlay IDs).
+ */
+export type LayerOwner = React.ComponentType<any> | string;
+/**
+ * Value provided by {@link KeyboardProvider} via React context.
+ */
+export interface KeyboardContextValue {
+    /**
+     * Bind one or more keys to a handler on the current screen layer.
+     *
+     * When a `focusId` is provided, the binding is stored on a named focus
+     * target instead of the screen-level bucket. Only the currently active
+     * focus target receives events.
+     *
+     * Overloads:
+     * 1. `(keys: string | string[], handler: KeyHandler, options?: BoundKeyboardOptions)` —
+     *    explicit keys and handler. A single string is normalized to `[string]`.
+     * 2. `(actionId: string, options: BoundKeyboardOptions)` —
+     *    uses a registered shortcut action's predefined keys and callback.
+     *
+     * @param keys     Key name(s) to bind (e.g. `"s"`, `["s", "ctrl+q", "return"]`).
+     * @param handler  Callback receiving the raw `input` and `key` from Ink.
+     * @param options  Optional binding behavior (`onlyThis`, `focusId`, `once`, `times`, `when`).
+     * @returns        An unbind function that removes this binding when called.
+     */
+    boundKeyboard: {
+        (keys: string | string[], handler: KeyHandler, options?: BoundKeyboardOptions): () => void;
+        (actionId: string, options: BoundKeyboardOptions): () => void;
+    };
+    /**
+     * Mark one or more keys as "transparent" on the current layer.
+     *
+     * When a transparent key reaches this layer (or the named focus target),
+     * the layer's own bindings are skipped and the key continues to propagate
+     * to layers below.
+     *
+     * @param keys     Key names to make transparent.
+     * @param options  If `focusId` is provided, marks transparent only
+     *                 within that focus target.
+     */
+    blockedKey: (keys: string[], options?: BlockedKeyOptions) => () => void;
+    /**
+     * Prevent one or more keys from propagating to layers below.
+     *
+     * Stopped keys are consumed at this layer: local bindings are evaluated
+     * first, and if no binding matches, the key is blocked from reaching
+     * lower layers.
+     *
+     * @param keys     Key names to stop from propagating.
+     * @param options  If `focusId` is provided, stops only within that
+     *                 focus target.
+     * @returns        An unstop function that removes the keys from the
+     *                 stop list.
+     */
+    stop: (keys: string[], options?: StopOptions) => () => void;
+    /**
+     * Register global key bindings.
+     *
+     * Global keys fire independently of the screen stack (subject to
+     * `category` whitelist and `affectOverlay` placement).
+     *
+     * By default (or with `{ mode: 'replace' }`), replaces all previously
+     * registered global keys. Pass `{ mode: 'add' }` to append without
+     * removing existing entries.
+     *
+     * @param entries  Array of global key definitions.
+     * @param options  Optional: `{ mode: 'replace' | 'add' }`. Default `'replace'`.
+     */
+    globalKeys: (entries: GlobalKeyEntry[], options?: {
+        mode?: "replace" | "add";
+    }) => void;
+    /**
+     * Return a snapshot of all currently registered global key entries.
+     *
+     * Each entry includes the resolved `operate` callback (actions resolved
+     * from action IDs), plus metadata: `key`, `cover`, `affectOverlay`,
+     * `category`, `times`, `pressCount`, `observer`, `executeWhenNoOverlay`,
+     * and `when`.
+     *
+     * @returns A shallow copy of the current global keys array.
+     */
+    getGlobalKeys: () => ResolvedGlobalKeyEntry[];
+    /**
+     * Register global sequence key bindings.
+     *
+     * Global sequences fire independently of the screen stack with higher
+     * priority than {@link globalKeys}. They match multi-key sequences
+     * instead of single key presses.
+     *
+     * By default (or with `{ mode: 'replace' }`), replaces all previously
+     * registered global sequences. Pass `{ mode: 'add' }` to append without
+     * removing existing entries.
+     *
+     * **Priority chain**: global sequences are evaluated before global keys
+     * in both the `affectOverlay: true` and `affectOverlay: false` stages:
+     *   1. globalSequence(affectOverlay:true)
+     *   2. globalKeys(affectOverlay:true)
+     *   3. overlay layer
+     *   4. globalSequence(affectOverlay:false)
+     *   5. globalKeys(affectOverlay:false)
+     *   6. screen stack
+     *
+     * **Cover**: Only `boundSequence` can override a global sequence (not
+     * `boundKeyboard`). When `cover: false`, `boundSequence` with the same
+     * first key throws.
+     *
+     * **No `times` support**: Unlike `globalKeys`, global sequences do not
+     * support the `times` option.
+     *
+     * @param entries  Array of global sequence definitions.
+     * @param options  Optional: `{ mode: 'replace' | 'add' }`. Default `'replace'`.
+     * @throws If any `keys` array has length < 2.
+     */
+    globalSequence: (entries: GlobalSequenceEntry[], options?: {
+        mode?: "replace" | "add";
+    }) => void;
+    /**
+     * Remove a focus target from the current screen layer.
+     *
+     * If the removed target was the currently active one, the next target
+     * (in registration order) is activated automatically. If no targets
+     * remain, `currentFocusId` becomes `null`.
+     *
+     * Components should call this in their `useEffect` cleanup alongside
+     * unbinding their focus-level key bindings.
+     *
+     * @param focusId  The focus target id to remove.
+     */
+    focusUnregister: (focusId: string) => void;
+    /**
+     * Activate a specific focus target by its id.
+     *
+     * Throws a runtime error if the current screen has no keyboard layer
+     * or no focus target with the given id is registered.
+     *
+     * @param focusId  The focus target id to activate.
+     * @throws If the current screen has no keyboard layer or the focus
+     *         target does not exist.
+     */
+    focusSet: (focusId: string) => void;
+    /**
+     * Activate the next focus target in registration order.
+     *
+     * Equivalent to pressing Tab. Wraps around to the first target if
+     * the last target is currently active.
+     */
+    focusNext: () => void;
+    /**
+     * Activate the previous focus target in registration order.
+     *
+     * Equivalent to pressing Shift+Tab. Wraps around to the last target
+     * if the first target is currently active.
+     */
+    focusPrev: () => void;
+    /**
+     * Return the currently active focus target id on the current screen.
+     *
+     * @returns The active focus id, or `null` if no focus targets exist.
+     */
+    focusCurrent: () => string | null;
+    /**
+     * Subscribe to focus changes on the current screen layer.
+     *
+     * The listener is called whenever the active focus id changes (via
+     * Tab, `focusSet`, `focusNext`, `focusPrev`, or `focusUnregister`).
+     *
+     * @param listener  Callback invoked on focus change.
+     * @returns         An unsubscribe function.
+     */
+    subscribeFocus: (listener: () => void) => () => void;
+    /**
+     * Register named shortcut actions that can be referenced by key bindings
+     * using a string identifier instead of an inline callback.
+     *
+     * Decouples operation definition from key binding.
+     *
+     * @param entries - Array of shortcut operation definitions.
+     *                  Each entry must have a unique `actionId`.
+     *
+     * @throws {Error} If an `actionId` is duplicated.
+     */
+    defineShortcutAction: (entries: ShortcutOperationEntry[]) => void;
+    /**
+     * Dynamically register a single shortcut action.
+     *
+     * @param entry - The shortcut operation definition to add.
+     * @throws {Error} If an action with the same `actionId` already exists.
+     */
+    addAction: (entry: ShortcutOperationEntry) => void;
+    /**
+     * Check whether a shortcut action with the given id exists.
+     *
+     * @param actionId - The action id to look up.
+     * @returns `true` if the action is registered, `false` otherwise.
+     */
+    hasAction: (actionId: string) => boolean;
+    /**
+     * Remove a registered shortcut action.
+     *
+     * @param actionId - The action id to remove.
+     * @throws {Error} If no action with the given id exists.
+     */
+    removeAction: (actionId: string) => void;
+    /**
+     * Modify the default keys of an existing shortcut action.
+     *
+     * @param actionId - The unique identifier of the action.
+     * @param keys     - New key names to replace the previous default keys.
+     * @throws If the action does not exist or was not registered with a `keys` field.
+     */
+    modifyAction: (actionId: string, keys: string[]) => void;
+    /**
+     * Clear all registered shortcut operations.
+     * Primarily used for testing or full keyboard reset scenarios.
+     */
+    clearShortcutOperations: () => void;
+    /**
+     * Register named sequence actions that can be referenced by sequence
+     * bindings using a string identifier instead of an inline callback.
+     *
+     * @param entries - Array of sequence operation definitions.
+     *                  Each entry must have a unique `sequenceActionId`.
+     * @throws {Error} If a `sequenceActionId` is duplicated.
+     */
+    defineSequenceAction: (entries: SequenceOperationEntry[]) => void;
+    /**
+     * Dynamically register a single sequence action.
+     *
+     * @param entry - The sequence operation definition to add.
+     * @throws {Error} If an action with the same `sequenceActionId` already exists.
+     */
+    addSequenceAction: (entry: SequenceOperationEntry) => void;
+    /**
+     * Check whether a sequence action with the given id exists.
+     *
+     * @param sequenceActionId - The action id to look up.
+     * @returns `true` if the action is registered, `false` otherwise.
+     */
+    hasSequenceAction: (sequenceActionId: string) => boolean;
+    /**
+     * Remove a registered sequence action.
+     *
+     * @param sequenceActionId - The action id to remove.
+     * @throws {Error} If no action with the given id exists.
+     */
+    removeSequenceAction: (sequenceActionId: string) => void;
+    /**
+     * Modify the default keys (and optionally timeout) of an existing sequence action.
+     *
+     * @param sequenceActionId - The unique identifier of the action.
+     * @param keys             - New key names to replace the previous default keys.
+     * @param timeout          - Optional new timeout value.
+     * @throws If the action does not exist or was not registered with a `keys` (or `timeout`) field.
+     */
+    modifySequenceAction: (sequenceActionId: string, keys: string[], timeout?: number) => void;
+    /**
+     * Clear all registered sequence operations.
+     * Primarily used for testing or full keyboard reset scenarios.
+     */
+    clearSequenceOperations: () => void;
+    /**
+     * Internal: Push an owner onto the owner stack.
+     * Used by useKeyboard() when rendering inside an overlay.
+     */
+    _pushOwner: (owner: LayerOwner) => void;
+    /**
+     * Internal: Pop an owner from the owner stack.
+     * Used by useKeyboard() cleanup when leaving an overlay context.
+     */
+    _popOwner: (owner: LayerOwner) => void;
+    /**
+     * Register a multi-key sequence binding on the current screen layer.
+     *
+     * When the first key of a sequence is pressed, the layer enters a pending
+     * state waiting for subsequent keys within `timeout` milliseconds (default
+     * 500). If the full sequence is entered in order before the timeout, the
+     * handler fires. Otherwise the pending state is cancelled.
+     *
+     * **Sequence priority**: Sequences are evaluated before ordinary
+     * `boundKeyboard` bindings. When a sequence's first key is pressed, it
+     * is consumed by the sequence system and will not trigger any normal
+     * binding for that key.
+     *
+     * **Exclusive vs non-exclusive (default)**: In non-exclusive mode, a
+     * key that does NOT match the next expected key in the sequence
+     * immediately cancels the pending sequence and falls through to normal
+     * bindings. In exclusive mode (`exclusive: true`), mismatched keys are
+     * silently consumed — the sequence keeps waiting within its timeout.
+     *
+     * **Layer isolation**: Each screen / overlay maintains its own pending
+     * sequence state. Navigating away, switching focus, or closing an
+     * overlay automatically clears any pending sequence on that layer.
+     *
+     * @param keys      Ordered key names that make up the sequence
+     *                  (e.g. `['g', 'g']`, `['c', 'w']`). Length must be ≥ 2.
+     * @param handler   Callback invoked when the full sequence is matched.
+     *                  Receives the Ink `input` and `key` of the final key
+     *                  press that completed the sequence.
+     * @param options   Optional configuration:
+     *                  - `timeout` (ms, default 500): how long to wait between
+     *                    key presses before cancelling the sequence.
+     *                  - `exclusive` (default false): if true, mismatched keys
+     *                    are consumed silently; if false, they cancel the
+     *                    sequence and fall through.
+     *                  - `onlyThis` / `focusId`: same behaviour as
+     *                    `boundKeyboard`.
+     * @returns         An unbind function that removes the sequence binding
+     *                   when called.
+     *
+     * @example
+     * ```tsx
+     * // Vim-like 'gg' to jump to the top
+     * useEffect(() => {
+     *   boundSequence(['g', 'g'], () => scrollToTop());
+     * }, []);
+     *
+     * // Exclusive mode: only 'ctrl+w' 'q' triggers, no other key interrupts
+     * useEffect(() => {
+     *   boundSequence(['ctrl+w', 'q'], closeTab, { exclusive: true });
+     * }, []);
+     *
+     * // Sequence restricted to a specific focus target
+     * useEffect(() => {
+     *   boundSequence(['d', 'd'], deleteLine, { focusId: 'editor' });
+     * }, []);
+     * ```
+     */
+    /**
+     * Register a multi-key sequence binding on the current screen layer.
+     *
+     * Overloads:
+     * 1. `(keys: string | string[], handler: KeyHandler, options?: SequenceOptions)` —
+     *    explicit keys and handler. A single string is normalized to `[string]`
+     *    (but the sequence still requires at least 2 keys).
+     * 2. `(actionId: string, options?: SequenceOptions)` —
+     *    uses a registered sequence action's predefined keys and callback.
+     */
+    boundSequence: {
+        (keys: string | string[], handler: KeyHandler, options?: SequenceOptions): () => void;
+        (actionId: string, options?: SequenceOptions): () => void;
+    };
+    /**
+     * Enable wildcard priority mode.
+     *
+     * When enabled, wildcard `*` bindings take absolute priority over ALL
+     * other key handling — sequences, exact key matches, everything. Only
+     * normal character input (as determined by `isNormalCharacter`) is
+     * affected — special keys (Tab, Return, Escape, arrow keys, modifiers,
+     * etc.) are never matched by wildcard and always fall through to normal
+     * processing.
+     *
+     * Uses reference counting: multiple callers can enable independently.
+     * Each returned disable function decrements the count; the mode is
+     * disabled when the count reaches zero.
+     *
+     * @returns A function that, when called, disables wildcard priority
+     *          for this caller. When all callers have disabled, original
+     *          priority is restored.
+     *
+     * @example
+     * ```tsx
+     * useEffect(() => {
+     *   const disable = enableWildcardPriority();
+     *   const unbind = boundKeyboard(['*'], handleInput, { focusId: 'input' });
+     *   return () => { unbind(); disable(); };
+     * }, []);
+     * ```
+     */
+    enableWildcardPriority: () => (() => void);
+    /**
+     * Subscribe to unhandled key presses inside a modal.
+     *
+     * When the active modal receives a key that was not consumed by any
+     * binding (according to the specified {@link ModalMissOptions}), the
+     * callback is invoked with either `{ miss: true, key, input, eventNames }`
+     * or `{ miss: false }`.
+     *
+     * Only functions inside a modal component (where {@link ModalContext} is
+     * set). Returns an unsubscribe function. Calling outside a modal is a
+     * silent no-op.
+     *
+     * @param cb      - Callback invoked on every key press in the modal.
+     * @param options - Controls which mechanics count as "handled".
+     * @returns An unsubscribe function.
+     */
+    useModalMissListener: (cb: ModalMissCallback, options?: ModalMissOptions) => () => void;
+}
+/**
+ * React context for the keyboard system.
+ *
+ * Accessed via {@link useKeyboard}. Must be provided by a
+ * {@link KeyboardProvider} nested inside a
+ * {@link ScenarioManagementProvider}.
+ */
+export declare const KeyboardContext: import("react").Context<KeyboardContextValue | null>;

package/dist/keyboard/context.js

@@ -0,0 +1,9 @@
+import { createContext } from "react";
+/**
+ * React context for the keyboard system.
+ *
+ * Accessed via {@link useKeyboard}. Must be provided by a
+ * {@link KeyboardProvider} nested inside a
+ * {@link ScenarioManagementProvider}.
+ */
+export const KeyboardContext = createContext(null);

package/dist/keyboard/global-key-processor/index.d.ts

@@ -0,0 +1,16 @@
+import type { PipelineProcessor } from '../types.js';
+/**
+ * Create a processor for global single-key bindings.
+ *
+ * Iterates registered global keys, filters by the given affectOverlay flag,
+ * applies executeWhenNoOverlay / override / category / times constraints,
+ * and fires the first matching entry.
+ *
+ * @param config.affectOverlay - Which priority group this processor serves.
+ * @returns A PipelineProcessor for the global key stage.
+ *
+ * @2026-06-14 v3.4.0
+ */
+export declare function createGlobalKeyProcessor(config: {
+    affectOverlay: boolean;
+}): PipelineProcessor;

package/dist/keyboard/global-key-processor/index.js

@@ -0,0 +1,75 @@
+import { checkGlobalKey } from '../check-global-key.js';
+/**
+ * Create a processor for global single-key bindings.
+ *
+ * Iterates registered global keys, filters by the given affectOverlay flag,
+ * applies executeWhenNoOverlay / override / category / times constraints,
+ * and fires the first matching entry.
+ *
+ * @param config.affectOverlay - Which priority group this processor serves.
+ * @returns A PipelineProcessor for the global key stage.
+ *
+ * @2026-06-14 v3.4.0
+ */
+export function createGlobalKeyProcessor(config) {
+    const { affectOverlay } = config;
+    return {
+        process(ctx) {
+            for (const entry of ctx.globalKeys) {
+                if ((entry.affectOverlay ?? false) !== affectOverlay)
+                    continue;
+                // when=false → entry treated as if not registered
+                if (entry.when?.() === false)
+                    continue;
+                if (affectOverlay) {
+                    if (ctx.activeCount === 0 && !entry.executeWhenNoOverlay)
+                        continue;
+                    let anyOverlayHasOverride = false;
+                    if (entry.cover !== false) {
+                        const keyNames = Array.isArray(entry.key) ? entry.key : [entry.key];
+                        for (const overlay of ctx.activeOverlays) {
+                            const overlayLayer = ctx.layersRef.current.get(overlay.id);
+                            if (overlayLayer && keyNames.some(k => overlayLayer.globalKeyOverrides.has(k))) {
+                                anyOverlayHasOverride = true;
+                                break;
+                            }
+                        }
+                    }
+                    if (anyOverlayHasOverride)
+                        continue;
+                }
+                else {
+                    let screenHasOverride = false;
+                    if (entry.cover !== false && ctx.topComponent) {
+                        const keyNames = Array.isArray(entry.key) ? entry.key : [entry.key];
+                        const topLayer = ctx.layersRef.current.get(ctx.topComponent);
+                        if (topLayer && keyNames.some(k => topLayer.globalKeyOverrides.has(k))) {
+                            screenHasOverride = true;
+                        }
+                    }
+                    if (screenHasOverride)
+                        continue;
+                }
+                if (checkGlobalKey(entry, ctx.eventNames, ctx.topComponent, ctx.layersRef)) {
+                    if (entry.times !== undefined && entry.times >= 1) {
+                        entry.pressCount += 1;
+                        // For times=3:
+                        // 1st press: pressCount=1, observer(2), returns true (swallowed)
+                        // 2nd press: pressCount=2, observer(1), returns true (swallowed)
+                        // 3rd press: pressCount=3, observer(0), pressCount→0, handler fires
+                        // Next press starts a new cycle: pressCount=1, observer(2)…
+                        // @2026-06-19 v3.5.2
+                        entry.observer?.(entry.times - entry.pressCount);
+                        if (entry.pressCount < entry.times) {
+                            return true;
+                        }
+                        entry.pressCount = 0;
+                    }
+                    entry.operate();
+                    return true;
+                }
+            }
+            return false;
+        },
+    };
+}

package/dist/keyboard/global-sequence-processor/index.d.ts

@@ -0,0 +1,14 @@
+import type { PipelineProcessor } from '../types.js';
+/**
+ * Create a processor for global multi-key sequences.
+ *
+ * Handles two sub-steps in order:
+ * 1. Drain any active global pending sequence.
+ * 2. Try to start a new sequence from registered entries.
+ *
+ * @param config.affectOverlay - Which priority group this processor serves.
+ * @returns A PipelineProcessor for the global sequence stage.
+ */
+export declare function createGlobalSequenceProcessor(config: {
+    affectOverlay: boolean;
+}): PipelineProcessor;

package/dist/keyboard/global-sequence-processor/index.js

@@ -0,0 +1,165 @@
+const DEFAULT_SEQUENCE_TIMEOUT = 500;
+/**
+ * Try to start a global pending sequence from a specific affectOverlay group.
+ *
+ * Iterates the candidate entries, filters by affectOverlay, category,
+ * and cover/override constraints, and creates a pending sequence when
+ * the first key matches.
+ *
+ * @param entries        Candidate global sequence entries.
+ * @param affectOverlay  Which group to filter (true = overlay-phase, false = screen-phase).
+ * @param ctx            Full pipeline context.
+ * @returns true when a new pending sequence was started (event consumed).
+ *
+ * @2026-06-14 v3.4.0
+ */
+function tryStartGlobalSequence(entries, affectOverlay, ctx) {
+    for (const entry of entries) {
+        if ((entry.affectOverlay ?? false) !== affectOverlay)
+            continue;
+        if (entry.when?.() === false)
+            continue;
+        if (affectOverlay && ctx.activeCount === 0 && !entry.executeWhenNoOverlay)
+            continue;
+        if (!ctx.topComponent)
+            continue;
+        const cat = entry.category;
+        if (cat !== undefined && cat !== '*') {
+            if (Array.isArray(cat) && cat.length === 0)
+                continue;
+            if (Array.isArray(cat) && !cat.includes(ctx.topComponent))
+                continue;
+        }
+        // Cover check: only boundSequence can override a global sequence.
+        // boundKeyboard is never checked — its keys are single-key bindings
+        // that the sequence system always consumes first.
+        if (entry.cover !== false) {
+            const firstKey = entry.keys[0];
+            if (affectOverlay) {
+                let anyOverlayHasOverride = false;
+                for (const overlay of ctx.activeOverlays) {
+                    const overlayLayer = ctx.layersRef.current.get(overlay.id);
+                    if (overlayLayer?.sequences.has(firstKey)) {
+                        anyOverlayHasOverride = true;
+                        break;
+                    }
+                }
+                if (anyOverlayHasOverride)
+                    continue;
+            }
+            else {
+                if (ctx.topComponent) {
+                    const topLayer = ctx.layersRef.current.get(ctx.topComponent);
+                    if (topLayer?.sequences.has(firstKey))
+                        continue;
+                }
+            }
+        }
+        if (ctx.eventNames.includes(entry.keys[0])) {
+            const timeout = entry.timeout ?? DEFAULT_SEQUENCE_TIMEOUT;
+            const pending = {
+                sequences: entry.keys,
+                nextIndex: 1,
+                handler: entry.operate,
+                timer: undefined,
+                timeout,
+                exclusive: entry.exclusive ?? false,
+                affectOverlay,
+                cover: entry.cover ?? true,
+                category: entry.category,
+                executeWhenNoOverlay: entry.executeWhenNoOverlay,
+                when: entry.when,
+            };
+            const timer = setTimeout(() => {
+                if (ctx.pendingSeqRef.current === pending) {
+                    ctx.pendingSeqRef.current = null;
+                }
+            }, timeout);
+            pending.timer = timer;
+            ctx.pendingSeqRef.current = pending;
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Process the currently active global pending sequence.
+ *
+ * Matches the next expected key, handles exclusive vs non-exclusive
+ * mismatch behaviour, and fires the handler when the full sequence
+ * is completed.
+ *
+ * @param ctx  Full pipeline context.
+ * @returns true when the event was consumed by the pending sequence.
+ *
+ * @2026-06-14 v3.4.0
+ */
+function processGlobalPending(ctx, affectOverlay) {
+    const pending = ctx.pendingSeqRef.current;
+    if (pending === null)
+        return false;
+    // Only process the pending sequence in the stage that matches its
+    // affectOverlay group — otherwise a pending sequence started in
+    // stage ④ (affectOverlay: false) would have its continuation
+    // consumed by stage ① (affectOverlay: true), bypassing the
+    // overlay layer.
+    if (pending.affectOverlay !== affectOverlay)
+        return false;
+    if (pending.affectOverlay && ctx.activeCount === 0 && !pending.executeWhenNoOverlay) {
+        clearTimeout(pending.timer);
+        ctx.pendingSeqRef.current = null;
+        return false;
+    }
+    if (pending.when?.() === false) {
+        clearTimeout(pending.timer);
+        ctx.pendingSeqRef.current = null;
+        return false;
+    }
+    const expectedKey = pending.sequences[pending.nextIndex];
+    if (ctx.eventNames.includes(expectedKey)) {
+        clearTimeout(pending.timer);
+        pending.nextIndex++;
+        if (pending.nextIndex === pending.sequences.length) {
+            pending.handler();
+            ctx.pendingSeqRef.current = null;
+        }
+        else {
+            pending.timer = setTimeout(() => {
+                if (ctx.pendingSeqRef.current === pending) {
+                    ctx.pendingSeqRef.current = null;
+                }
+            }, pending.timeout);
+        }
+        return true;
+    }
+    if (pending.exclusive) {
+        // Exclusive mode: silently consume the mismatched key, keep waiting.
+        return true;
+    }
+    // Non-exclusive (default): cancel the sequence, key falls through.
+    clearTimeout(pending.timer);
+    ctx.pendingSeqRef.current = null;
+    return false;
+}
+/**
+ * Create a processor for global multi-key sequences.
+ *
+ * Handles two sub-steps in order:
+ * 1. Drain any active global pending sequence.
+ * 2. Try to start a new sequence from registered entries.
+ *
+ * @param config.affectOverlay - Which priority group this processor serves.
+ * @returns A PipelineProcessor for the global sequence stage.
+ */
+export function createGlobalSequenceProcessor(config) {
+    const { affectOverlay } = config;
+    return {
+        process(ctx) {
+            if (processGlobalPending(ctx, affectOverlay))
+                return true;
+            if (tryStartGlobalSequence(ctx.globalSequences, affectOverlay, ctx))
+                return true;
+            return false;
+        },
+    };
+}