ink-cartridge 3.6.1

package/dist/keyboard/modal-processor/index.js

@@ -0,0 +1,97 @@
+import { handleLayer } from '../layer-handler.js';
+/**
+ * Check whether a list of bindings contains one whose `keys` match
+ * the event but whose `when` returns `false`.
+ */
+function hasWhenFalseBinding(bindings, eventNames) {
+    return bindings.some((b) => b.when?.() === false &&
+        b.keys.some((k) => eventNames.includes(k)));
+}
+/**
+ * Check whether any non-active focus target has a binding matching
+ * the event.
+ */
+function matchesOtherFocusTarget(layer, eventNames) {
+    for (const [fid, ft] of layer.focusTargets) {
+        if (fid === layer.currentFocusId)
+            continue;
+        if (ft.bindings.some((b) => b.keys.some((k) => eventNames.includes(k)))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Determine whether a key event is a "miss" and invoke the callback.
+ *
+ * @returns true if the callback was invoked with miss=true.
+ */
+function invokeMissIfNeeded(layer, handled, key, input, eventNames) {
+    if (!layer.onMiss)
+        return false;
+    const opts = layer.onMissOptions ?? {};
+    // fix: The stop API and blockedKey API cases are no longer handled.
+    // Instead, it is left to handlerLayer to handle natural
+    // So the expectation is that, So the Stop API returns miss: false, but the BlockedKeys API returns miss: true
+    // TODO: You need to modify the corresponding test and do it later.
+    // @2026-06-23 3.6.1
+    if (handled) {
+        layer.onMiss({ miss: false });
+        return false;
+    }
+    // handled === false — key was not consumed by handleLayer.
+    if (opts.monitorWhen && hasWhenFalseBinding(layer.bindings, eventNames)) {
+        layer.onMiss({ miss: true, key, input, eventNames });
+        return true;
+    }
+    if (opts.monitorWhen &&
+        layer.currentFocusId) {
+        const ft = layer.focusTargets.get(layer.currentFocusId);
+        if (ft && hasWhenFalseBinding(ft.bindings, eventNames)) {
+            layer.onMiss({ miss: true, key, input, eventNames });
+            return true;
+        }
+    }
+    if (opts.monitorFocusMismatch &&
+        matchesOtherFocusTarget(layer, eventNames)) {
+        layer.onMiss({ miss: true, key, input, eventNames });
+        return true;
+    }
+    // Definitely a miss — no mechanism handled this key.
+    layer.onMiss({ miss: true, key, input, eventNames });
+    return true;
+}
+/**
+ * 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 function createModalProcessor() {
+    return {
+        process(ctx) {
+            if (!ctx.activeModalId)
+                return false;
+            const layer = ctx.layersRef.current.get(ctx.activeModalId);
+            let handled = false;
+            if (layer) {
+                handled = handleLayer(layer, ctx.eventNames, ctx.input, ctx.key, true, // isTop — modal is always the top layer
+                ctx.notifyFocusChange, 1, // activeCount — modal is singleton
+                true, // isOverlay — modal is treated as a floating layer for onlyThis semantics
+                ctx.wildcardFirst);
+            }
+            if (layer) {
+                invokeMissIfNeeded(layer, handled, ctx.key, ctx.input, ctx.eventNames);
+            }
+            return true;
+        },
+    };
+}

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

@@ -0,0 +1,16 @@
+import type { PipelineProcessor } from '../types.js';
+/**
+ * Create a processor for the overlay broadcast stage.
+ *
+ * Iterates all active overlays (sorted by zIndex ascending) and offers
+ * the event to each one via {@link handleLayer}. Unlike other processors,
+ * this stage does NOT stop on the first consumer — every active overlay
+ * receives the event. The `anyOverlayConsumed` flag on the context is
+ * set if at least one overlay handled the event, which later determines
+ * whether the screen stack (stage ⑥) runs.
+ *
+ * @returns A PipelineProcessor for the overlay broadcast stage.
+ *
+ * @2026-06-14 v3.4.0
+ */
+export declare function createOverlayProcessor(): PipelineProcessor;

package/dist/keyboard/overlay-processor/index.js

@@ -0,0 +1,30 @@
+import { handleLayer } from '../layer-handler.js';
+/**
+ * Create a processor for the overlay broadcast stage.
+ *
+ * Iterates all active overlays (sorted by zIndex ascending) and offers
+ * the event to each one via {@link handleLayer}. Unlike other processors,
+ * this stage does NOT stop on the first consumer — every active overlay
+ * receives the event. The `anyOverlayConsumed` flag on the context is
+ * set if at least one overlay handled the event, which later determines
+ * whether the screen stack (stage ⑥) runs.
+ *
+ * @returns A PipelineProcessor for the overlay broadcast stage.
+ *
+ * @2026-06-14 v3.4.0
+ */
+export function createOverlayProcessor() {
+    return {
+        process(ctx) {
+            for (const overlay of ctx.activeOverlays) {
+                const layer = ctx.layersRef.current.get(overlay.id);
+                if (layer && handleLayer(layer, ctx.eventNames, ctx.input, ctx.key, true, ctx.notifyFocusChange, ctx.activeCount, true, ctx.wildcardFirst)) {
+                    ctx.anyOverlayConsumed = true;
+                    // Do not break — continue to next overlay (broadcast semantics).
+                }
+            }
+            // Always return false so the chain continues to subsequent stages.
+            return false;
+        },
+    };
+}

package/dist/keyboard/pipeline/chain.d.ts

@@ -0,0 +1,10 @@
+import type { PipelineContext } from '../types.js';
+/**
+ * Run a keyboard event through the full processor chain.
+ *
+ * Each processor's {@link PipelineProcessor.process} is called in order.
+ * The first processor to return `true` (event consumed) stops the chain.
+ *
+ * @param ctx - Snapshot context built by {@link buildPipelineContext}.
+ */
+export declare function runPipeline(ctx: PipelineContext): void;

package/dist/keyboard/pipeline/chain.js

@@ -0,0 +1,45 @@
+import { createModalProcessor } from '../modal-processor/index.js';
+import { createGlobalSequenceProcessor } from '../global-sequence-processor/index.js';
+import { createGlobalKeyProcessor } from '../global-key-processor/index.js';
+import { createOverlayProcessor } from '../overlay-processor/index.js';
+import { createScreenStackProcessor } from '../screen-stack-processor/index.js';
+/**
+ * Build the canonical 7-stage processor chain.
+ *
+ * Priority order (highest first):
+ *   ⓪ Modal                                    — active modal, always blocks
+ *   ① GlobalSequence (affectOverlay: true)  — pending + start
+ *   ② GlobalKey      (affectOverlay: true)  — fire before overlays
+ *   ③ Overlay broadcast                      — all active overlays, zIndex asc
+ *   ④ GlobalSequence (affectOverlay: false) — pending + start
+ *   ⑤ GlobalKey      (affectOverlay: false) — fire before screen stack
+ *   ⑥ Screen stack                           — top → bottom, only if no overlay consumed
+ *
+ * @2026-06-22 v3.6.1
+ */
+function buildProcessors() {
+    return [
+        createModalProcessor(),
+        createGlobalSequenceProcessor({ affectOverlay: true }),
+        createGlobalKeyProcessor({ affectOverlay: true }),
+        createOverlayProcessor(),
+        createGlobalSequenceProcessor({ affectOverlay: false }),
+        createGlobalKeyProcessor({ affectOverlay: false }),
+        createScreenStackProcessor(),
+    ];
+}
+/**
+ * Run a keyboard event through the full processor chain.
+ *
+ * Each processor's {@link PipelineProcessor.process} is called in order.
+ * The first processor to return `true` (event consumed) stops the chain.
+ *
+ * @param ctx - Snapshot context built by {@link buildPipelineContext}.
+ */
+export function runPipeline(ctx) {
+    const processors = buildProcessors();
+    for (const processor of processors) {
+        if (processor.process(ctx))
+            return;
+    }
+}

package/dist/keyboard/pipeline/context.d.ts

@@ -0,0 +1,34 @@
+import type { Key } from 'ink';
+import type React from 'react';
+import type { OverlayEntry } from '../../screen/types.js';
+import type { LayerOwner } from '../context.js';
+import type { PipelineContext, ScreenKeyboardLayer, ResolvedGlobalKeyEntry, ResolvedGlobalSequenceEntry } from '../types.js';
+/**
+ * Collection of all provider refs needed by {@link buildPipelineContext}
+ * to snapshot the current keyboard state for a single event.
+ */
+export interface PipelineRefs {
+    pathRef: React.MutableRefObject<React.ComponentType<any>[]>;
+    globalKeysRef: React.MutableRefObject<ResolvedGlobalKeyEntry[]>;
+    globalSequencesRef: React.MutableRefObject<ResolvedGlobalSequenceEntry[]>;
+    activeOverlayIdsRef: React.MutableRefObject<Set<string>>;
+    displayedOverlaysRef: React.MutableRefObject<OverlayEntry[]>;
+    activeModalIdRef: React.MutableRefObject<string | null>;
+    layersRef: React.MutableRefObject<Map<LayerOwner, ScreenKeyboardLayer>>;
+    globalPendingSeqRef: React.MutableRefObject<import('../types.js').GlobalPendingSequence | null>;
+    wildcardPriorityCountRef: React.MutableRefObject<number>;
+    notifyFocusChange: () => void;
+}
+/**
+ * Build a {@link PipelineContext} snapshot from the provider's refs.
+ *
+ * Called once per key event at the top of the `useInput` callback.
+ * All `ref.current` values are read synchronously to produce a
+ * consistent snapshot for the current event.
+ *
+ * @param input - Raw character string from Ink's useInput.
+ * @param key   - Full Key descriptor from Ink.
+ * @param refs  - All mutable refs owned by the keyboard provider.
+ * @returns A frozen-in-time context for the pipeline chain.
+ */
+export declare function buildPipelineContext(input: string, key: Key, refs: PipelineRefs): PipelineContext;

package/dist/keyboard/pipeline/context.js

@@ -0,0 +1,42 @@
+import { normalizeKeyNames } from '../keyNormalizer.js';
+/**
+ * Build a {@link PipelineContext} snapshot from the provider's refs.
+ *
+ * Called once per key event at the top of the `useInput` callback.
+ * All `ref.current` values are read synchronously to produce a
+ * consistent snapshot for the current event.
+ *
+ * @param input - Raw character string from Ink's useInput.
+ * @param key   - Full Key descriptor from Ink.
+ * @param refs  - All mutable refs owned by the keyboard provider.
+ * @returns A frozen-in-time context for the pipeline chain.
+ */
+export function buildPipelineContext(input, key, refs) {
+    const eventNames = normalizeKeyNames(input, key);
+    const path = refs.pathRef.current;
+    const topComponent = path.length > 0 ? path[path.length - 1] : null;
+    const globalKeys = refs.globalKeysRef.current;
+    const globalSequences = refs.globalSequencesRef.current;
+    const activeIds = refs.activeOverlayIdsRef.current;
+    const overlays = refs.displayedOverlaysRef.current;
+    const activeOverlays = overlays.filter(n => activeIds.has(n.id));
+    const activeCount = activeIds.size;
+    const wildcardFirst = refs.wildcardPriorityCountRef.current > 0;
+    return {
+        input,
+        key,
+        eventNames,
+        topComponent,
+        globalKeys,
+        globalSequences,
+        activeOverlays,
+        activeCount,
+        wildcardFirst,
+        screenPath: path,
+        activeModalId: refs.activeModalIdRef.current,
+        layersRef: refs.layersRef,
+        pendingSeqRef: refs.globalPendingSeqRef,
+        notifyFocusChange: refs.notifyFocusChange,
+        anyOverlayConsumed: false,
+    };
+}

package/dist/keyboard/pipeline/index.d.ts

@@ -0,0 +1,3 @@
+export { buildPipelineContext } from './context.js';
+export type { PipelineRefs } from './context.js';
+export { runPipeline } from './chain.js';

package/dist/keyboard/pipeline/index.js

@@ -0,0 +1,2 @@
+export { buildPipelineContext } from './context.js';
+export { runPipeline } from './chain.js';

package/dist/keyboard/provider.d.ts

@@ -0,0 +1,32 @@
+import React, { ReactNode } from 'react';
+/**
+ * Clear all registered shortcut operations.
+ *
+ * NOTE: Since the refactoring to per-instance useRef state, this function
+ * is a no-op at module level. Shortcut operations are now scoped to each
+ * {@link KeyboardProvider} instance and are automatically cleaned up when
+ * the provider unmounts.
+ *
+ * Kept for backward compatibility with tests and external consumers that
+ * call this function in cleanup routines.
+ */
+export declare function clearShortcutOperations(): void;
+export interface KeyboardProviderProps {
+    children: ReactNode;
+}
+/**
+ * Keyboard context provider for layered key handling.
+ *
+ * Manages per-screen-layer key bindings, transparent keys (`blockedKey`),
+ * key-stop propagation barriers (`stop`), and global keys (`globalKeys`).
+ * Handles the full event priority chain:
+ *   1. Global keys with `affectOverlay: true`
+ *   2. Broadcast to all active overlays (sorted by zIndex ascending)
+ *   3. Global keys with `affectOverlay: false` (default)
+ *   4. Screen stack (top → bottom), only if no overlay consumed the event
+ *   5. Drop unhandled keys
+ *
+ * Must be nested inside a {@link ScenarioManagementProvider} so that the
+ * current screen path and overlay state are available.
+ */
+export declare function KeyboardProvider({ children }: KeyboardProviderProps): React.JSX.Element;