ink-cartridge 3.8.1 → 3.8.2

package/README.md

@@ -56,7 +56,7 @@ npx ink-cartridge init my-tui
 - [useKeyboard](docs/keyboard/useKeyboard-API.md)
 - [boundKeyboard](docs/keyboard/boundKeyboard-API.md)
 - [boundSequence](docs/keyboard/boundSequence-API.md)
-- [blockedKey](docs/keyboard/blockedKey-API.md)
+- [penetration](docs/keyboard/penetration-API.md)
 - [stop](docs/keyboard/stop-API.md)
 - [globalKeys](docs/keyboard/globalKeys-API.md)
 - [globalSequence](docs/keyboard/globalSequence-API.md)
@@ -166,7 +166,7 @@ npx ink-cartridge init my-tui
 
 ## Other
 
-The method `blockedKey` is poorly named — it means *pass-through*, not "block." The internal name is `penetration`. Too late to rename now.
+The method `penetration` (formerly `blockedKey`) marks keys as transparent (pass-through). Renamed in v3.8.1 to eliminate the historical naming confusion.
 
 ## License
 

package/dist/dev/dev-screen.d.ts

@@ -18,7 +18,7 @@ import { DevProps } from "./types.js";
  * The panel registers itself via `registerComponent` so it participates
  * in the modal keyboard layer automatically.
  *
- * As a modal, DevScreen blocks all keyboard events from reaching overlays
+ * As a modal, DevScreen consumes all keyboard events from reaching overlays
  * and screens while open.
  *
  * @param top   - Initial vertical position in rows (0 = top of terminal).

package/dist/dev/dev-screen.js

@@ -92,7 +92,7 @@ function AllFocusSummary({ currentPath, activeOverlayIds, activeModalId, readLay
 }
 /**
  * Renders a compact summary of the keyboard layer for the top screen
- * component: bindings, sequences, stopped keys, and blocked keys.
+ * component: bindings, sequences, stopped keys, and penetration keys.
  *
  * Focus targets are displayed separately by {@link AllFocusSummary}
  * so that all layers' targets are visible at once.
@@ -107,7 +107,7 @@ function LayerSummary({ topComponent, readLayer }) {
     const seqCount = [...layer.sequences.values()].reduce((s, a) => s + a.length, 0);
     const seqFirstKeys = [...layer.sequences.keys()].join(' ');
     const stopped = layer.stoppedKeys.map(r => Array.isArray(r.key) ? r.key.join(',') : r.key).join(' ');
-    const blocked = layer.blockedKeys.map(r => Array.isArray(r.key) ? r.key.join(',') : r.key).join(' ');
+    const penetrated = layer.penetrationKeys.map(r => Array.isArray(r.key) ? r.key.join(',') : r.key).join(' ');
     return (React.createElement(Box, { flexDirection: "column", paddingY: 1 },
         React.createElement(Box, { flexDirection: "row" },
             React.createElement(Text, { color: "cyan" },
@@ -128,9 +128,9 @@ function LayerSummary({ topComponent, readLayer }) {
         stopped && (React.createElement(Box, { flexDirection: "row" },
             React.createElement(Text, { color: "red" }, "Stopped: "),
             React.createElement(Text, { dimColor: true }, stopped))),
-        blocked && (React.createElement(Box, { flexDirection: "row" },
-            React.createElement(Text, { color: "gray" }, "Blocked: "),
-            React.createElement(Text, { dimColor: true }, blocked)))));
+        penetrated && (React.createElement(Box, { flexDirection: "row" },
+            React.createElement(Text, { color: "gray" }, "Penetr: "),
+            React.createElement(Text, { dimColor: true }, penetrated)))));
 }
 /**
  * Developer debugging modal for the ink-cartridge screen system.
@@ -150,7 +150,7 @@ function LayerSummary({ topComponent, readLayer }) {
  * The panel registers itself via `registerComponent` so it participates
  * in the modal keyboard layer automatically.
  *
- * As a modal, DevScreen blocks all keyboard events from reaching overlays
+ * As a modal, DevScreen consumes all keyboard events from reaching overlays
  * and screens while open.
  *
  * @param top   - Initial vertical position in rows (0 = top of terminal).

package/dist/dev/layerKey-display.js

@@ -116,8 +116,8 @@ function FocusTargetDetail({ focusId, target }) {
                 React.createElement(Text, { color: "white" }, focusId)),
             React.createElement(Row, { label: "Bindings" },
                 React.createElement(Text, { color: "white" }, target.bindings.length)),
-            React.createElement(Row, { label: "Blocked" },
-                React.createElement(Text, { color: "white" }, target.blockedKeys.length)),
+            React.createElement(Row, { label: "Penetr." },
+                React.createElement(Text, { color: "white" }, target.penetrationKeys.length)),
             React.createElement(Row, { label: "Stopped" },
                 React.createElement(Text, { color: "white" }, target.stoppedKeys.length))),
         target.bindings.length > 0 && (React.createElement(Box, { paddingTop: 1, flexDirection: "column" },
@@ -126,9 +126,9 @@ function FocusTargetDetail({ focusId, target }) {
                 "  [",
                 b.keys.join(', '),
                 "]"))))),
-        target.blockedKeys.length > 0 && (React.createElement(Box, { paddingTop: 1, flexDirection: "column" },
-            React.createElement(Text, { color: "gray", dimColor: true }, "Blocked:"),
-            target.blockedKeys.map((r, i) => (React.createElement(Text, { key: i, color: "gray" },
+        target.penetrationKeys.length > 0 && (React.createElement(Box, { paddingTop: 1, flexDirection: "column" },
+            React.createElement(Text, { color: "gray", dimColor: true }, "Penetration:"),
+            target.penetrationKeys.map((r, i) => (React.createElement(Text, { key: i, color: "gray" },
                 "  ",
                 fmtKeys(r.key)))))),
         target.stoppedKeys.length > 0 && (React.createElement(Box, { paddingTop: 1, flexDirection: "column" },
@@ -213,18 +213,18 @@ export default function LayerKeyDisplayBox({ top: initialTop, left, screenCompon
             Key: `stop-${i}`,
         });
     });
-    // Blocked keys
-    layer.blockedKeys.forEach((rule, i) => {
+    // Penetration keys
+    layer.penetrationKeys.forEach((rule, i) => {
         items.push({
-            label: `[Blk]  ${keyRuleLabel(rule)}`,
-            value: { kind: 'blocked', idx: i, rule },
+            label: `[Pen]  ${keyRuleLabel(rule)}`,
+            value: { kind: 'penetrated', idx: i, rule },
             Key: `blk-${i}`,
         });
     });
     // Focus targets
     for (const [focusId, target] of layer.focusTargets) {
         items.push({
-            label: `[Foc]  ${focusId}  (bind:${target.bindings.length} blk:${target.blockedKeys.length} stp:${target.stoppedKeys.length})`,
+            label: `[Foc]  ${focusId}  (bind:${target.bindings.length} pen:${target.penetrationKeys.length} stp:${target.stoppedKeys.length})`,
             value: { kind: 'focusTarget', focusId, target },
             Key: `focus-${focusId}`,
         });
@@ -249,8 +249,8 @@ export default function LayerKeyDisplayBox({ top: initialTop, left, screenCompon
                 return React.createElement(SequenceDetail, { firstKey: expandedEntry.firstKey, entry: expandedEntry.entry });
             case 'stopped':
                 return React.createElement(KeyRuleDetail, { label: "Stopped Key", rule: expandedEntry.rule });
-            case 'blocked':
-                return React.createElement(KeyRuleDetail, { label: "Blocked Key (pass-through)", rule: expandedEntry.rule });
+            case 'penetrated':
+                return React.createElement(KeyRuleDetail, { label: "Penetration Key (pass-through)", rule: expandedEntry.rule });
             case 'focusTarget':
                 return React.createElement(FocusTargetDetail, { focusId: expandedEntry.focusId, target: expandedEntry.target });
         }
@@ -266,7 +266,7 @@ export default function LayerKeyDisplayBox({ top: initialTop, left, screenCompon
                 layer.currentFocusId ?? 'none')),
         React.createElement(Sep, null),
         expandedEntry ? (renderDetail()) : items.length === 0 ? (React.createElement(Box, { flexGrow: 1, justifyContent: "center", alignItems: "center" },
-            React.createElement(Text, { color: "gray" }, "No bindings, sequences, stopped/blocked keys, or focus targets."))) : (React.createElement(SelectInput, { items: items, onSelect: handleSelect, focusId: "layerKey-list", limit: 9 })),
+            React.createElement(Text, { color: "gray" }, "No bindings, sequences, stopped/penetration keys, or focus targets."))) : (React.createElement(SelectInput, { items: items, onSelect: handleSelect, focusId: "layerKey-list", limit: 9 })),
         React.createElement(Sep, null),
         React.createElement(Box, { paddingTop: 1 },
             React.createElement(Text, { dimColor: true }, expandedEntry

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { SkipOptions, SkipFn, BackFn, GotoScreenFn, OpenOverlayFn, CloseOve
 export { KeyboardProvider, useKeyboard } from "./keyboard/index.js";
 export { normalizeKeyNames, isNormalCharacter } from "./keyboard/index.js";
 export type { KeyHandler, BoundKeyboardOptions, BoundKeyEntry, ScreenKeyboardLayer, KeyboardProviderProps, GlobalKeyEntry, GlobalSequenceEntry, } from "./keyboard/index.js";
-export type { BlockedKeyOptions, AllowModalOptions, StopOptions, LayerKind, FocusTarget, SequenceOptions, ShortcutOperationEntry, SequenceOperationEntry, ModalMissEvent, ModalMissCallback, ModalMissOptions, ResolvedGlobalKeyEntry, } from "./keyboard/index.js";
+export type { PenetrationOptions, AllowModalOptions, StopOptions, LayerKind, FocusTarget, SequenceOptions, ShortcutOperationEntry, SequenceOperationEntry, ModalMissEvent, ModalMissCallback, ModalMissOptions, ResolvedGlobalKeyEntry, } from "./keyboard/index.js";
 export { useFocusState } from "./keyboard/index.js";
 export { SelectInput } from "./components/select/SelectInput.js";
 export type { Item } from "./components/select/types.js";

package/dist/keyboard/context.d.ts

@@ -1,4 +1,4 @@
-import type { KeyHandler, BoundKeyboardOptions, BlockedKeyOptions, StopOptions, AllowModalOptions, GlobalKeyEntry, GlobalSequenceEntry, ShortcutOperationEntry, SequenceOperationEntry, SequenceOptions, ModalMissCallback, ModalMissOptions, ResolvedGlobalKeyEntry, ResolvedGlobalSequenceEntry, GlobalPendingSequence, ScreenKeyboardLayer } from "./types.js";
+import type { KeyHandler, BoundKeyboardOptions, PenetrationOptions, StopOptions, AllowModalOptions, GlobalKeyEntry, GlobalSequenceEntry, ShortcutOperationEntry, SequenceOperationEntry, SequenceOptions, ModalMissCallback, ModalMissOptions, ResolvedGlobalKeyEntry, ResolvedGlobalSequenceEntry, GlobalPendingSequence, ScreenKeyboardLayer } 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).
@@ -45,7 +45,7 @@ export interface KeyboardContextValue {
      * @param options  If `focusId` is provided, marks transparent only
      *                 within that focus target.
      */
-    blockedKey: (keys: string[], options?: BlockedKeyOptions) => () => void;
+    penetration: (keys: string[], options?: PenetrationOptions) => () => void;
     /**
      * Prevent one or more keys from propagating to layers below.
      *

package/dist/keyboard/hook.d.ts

@@ -3,7 +3,7 @@ import type { ModalMissCallback, ModalMissOptions } from "./types.js";
 /**
  * Access the keyboard API from within a React component.
  *
- * Returns `{ boundKeyboard, blockedKey, stop, globalKeys, ... }`.
+ * Returns `{ boundKeyboard, penetration, stop, globalKeys, ... }`.
  *
  * When called inside an overlay component (wrapped in OverlayContext.Provider),
  * keyboard bindings are automatically isolated to the overlay's own layer,

package/dist/keyboard/hook.js

@@ -6,7 +6,7 @@ import { useScreenSystem } from "../screen/hook.js";
 /**
  * Access the keyboard API from within a React component.
  *
- * Returns `{ boundKeyboard, blockedKey, stop, globalKeys, ... }`.
+ * Returns `{ boundKeyboard, penetration, stop, globalKeys, ... }`.
  *
  * When called inside an overlay component (wrapped in OverlayContext.Provider),
  * keyboard bindings are automatically isolated to the overlay's own layer,

package/dist/keyboard/index.d.ts

@@ -2,4 +2,4 @@ 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, AllowModalOptions, StopOptions, BoundKeyEntry, ScreenKeyboardLayer, LayerKind, FocusTarget, GlobalKeyEntry, GlobalSequenceEntry, ShortcutOperationEntry, SequenceOperationEntry, SequenceOptions, SequenceBinding, PendingSequence, ModalMissEvent, ModalMissCallback, ModalMissOptions, ResolvedGlobalKeyEntry, } from "./types.js";
+export type { KeyHandler, BoundKeyboardOptions, PenetrationOptions, AllowModalOptions, StopOptions, BoundKeyEntry, ScreenKeyboardLayer, LayerKind, FocusTarget, GlobalKeyEntry, GlobalSequenceEntry, ShortcutOperationEntry, SequenceOperationEntry, SequenceOptions, SequenceBinding, PendingSequence, ModalMissEvent, ModalMissCallback, ModalMissOptions, ResolvedGlobalKeyEntry, } from "./types.js";

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

@@ -25,14 +25,14 @@ export declare function keyMatchesRule(keyName: string, rules: KeyRule[]): boole
  * 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 availableKeys Normalized key names available for matching 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;
+export declare function tryMatchBindings(bindings: BoundKeyEntry[], availableKeys: string[], input: string, key: Key, skipBinding?: (binding: BoundKeyEntry) => boolean): boolean;
 /**
  * Built-in Tab / Shift+Tab focus rotation for a given layer.
  *
@@ -46,7 +46,7 @@ export declare function handleTabNavigation(layer: ScreenKeyboardLayer, eventNam
 /**
  * Handle a keyboard event against a single layer.
  *
- * Evaluates tab navigation, blocked keys, wildcard priority, sequence
+ * Evaluates tab navigation, penetration keys, wildcard priority, sequence
  * matching, focus-target bindings, layer-level bindings, and stopped
  * keys — in that order.
  *

package/dist/keyboard/layer-handler.js

@@ -33,22 +33,22 @@ export function keyMatchesRule(keyName, rules) {
  * 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 availableKeys Normalized key names available for matching 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)
+export function tryMatchBindings(bindings, availableKeys, input, key, skipBinding) {
+    if (availableKeys.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))) {
+        if (binding.keys.some((k) => availableKeys.includes(k))) {
             binding.handler(input, key);
             return true;
         }
@@ -91,7 +91,7 @@ export function handleTabNavigation(layer, eventNames, shift, notifyFocusChange)
 /**
  * Handle a keyboard event against a single layer.
  *
- * Evaluates tab navigation, blocked keys, wildcard priority, sequence
+ * Evaluates tab navigation, penetration keys, wildcard priority, sequence
  * matching, focus-target bindings, layer-level bindings, and stopped
  * keys — in that order.
  *
@@ -105,8 +105,8 @@ export function handleLayer(layer, eventNames, input, key, isTop, notifyFocusCha
     // 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));
+    const penetrated = layer.penetrationKeys;
+    const available = eventNames.filter((n) => !keyMatchesRule(n, penetrated));
     // 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)
@@ -120,14 +120,14 @@ export function handleLayer(layer, eventNames, input, key, isTop, notifyFocusCha
     // 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) {
+    if (isTop && wildcardFirst && available.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 fPenetrated = ft.penetrationKeys;
+                const fAvailable = available.filter(n => !keyMatchesRule(n, fPenetrated));
+                if (fAvailable.length > 0) {
                     const wb = ft.bindings.find(b => b.keys.includes('*'));
                     if (wb && isNormalCharacter(input, key)) {
                         if (wb.when?.() === false) { /* skip */ }
@@ -151,7 +151,7 @@ export function handleLayer(layer, eventNames, input, key, isTop, notifyFocusCha
     }
     // Sequence matching: only for the top layer (isTop).
     // Sequences have priority over ordinary boundKeyboard bindings.
-    if (isTop && unblocked.length > 0) {
+    if (isTop && available.length > 0) {
         const pending = layer.pendingSequence;
         // We already have a pending sequence in progress.
         if (pending !== null) {
@@ -164,14 +164,14 @@ export function handleLayer(layer, eventNames, input, key, isTop, notifyFocusCha
             }
             else {
                 const expectedKey = pending.sequences[pending.nextIndex];
-                if (unblocked.includes(expectedKey)) {
+                if (available.includes(expectedKey)) {
                     // Matched the next key in the sequence.
                     clearTimeout(pending.timer);
                     pending.nextIndex++;
                     // Narrow candidates to only those whose next key also matches.
                     if (pending.candidates && pending.candidates.length > 1) {
                         const nextIdx = pending.nextIndex - 1;
-                        const narrowed = pending.candidates.filter(c => c.keys.length > nextIdx && unblocked.includes(c.keys[nextIdx]));
+                        const narrowed = pending.candidates.filter(c => c.keys.length > nextIdx && available.includes(c.keys[nextIdx]));
                         pending.candidates = narrowed.length <= 1 ? undefined : narrowed;
                     }
                     if (pending.nextIndex === pending.sequences.length) {
@@ -198,7 +198,7 @@ export function handleLayer(layer, eventNames, input, key, isTop, notifyFocusCha
                         // Non-exclusive with multiple candidates: try the current key
                         // against every candidate's next expected key to disambiguate.
                         const nextIdx = pending.nextIndex;
-                        const stillPossible = pending.candidates.filter(c => c.keys.length > nextIdx && unblocked.includes(c.keys[nextIdx]));
+                        const stillPossible = pending.candidates.filter(c => c.keys.length > nextIdx && available.includes(c.keys[nextIdx]));
                         if (stillPossible.length === 0) {
                             // No candidate matches — cancel all and fall through.
                             clearTimeout(pending.timer);
@@ -240,11 +240,11 @@ export function handleLayer(layer, eventNames, input, key, isTop, notifyFocusCha
                 }
             }
         }
-        // No pending sequence — try to start a new one from the first unblocked key.
+        // No pending sequence — try to start a new one from the first available key.
         if (layer.pendingSequence === null) {
-            // Check each unblocked key name (not just the first) to handle
+            // Check each available key name (not just the first) to handle
             // modifier combinations like 'ctrl+w' which appear after 'w'.
-            for (const keyName of unblocked) {
+            for (const keyName of available) {
                 // 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'
@@ -311,16 +311,16 @@ export function handleLayer(layer, eventNames, input, key, isTop, notifyFocusCha
     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))
+            const fPenetrated = ft.penetrationKeys;
+            const fAvailable = available.filter((n) => !keyMatchesRule(n, fPenetrated));
+            if (tryMatchBindings(ft.bindings, fAvailable, input, key, shouldSkipOnlyThis))
                 return true;
             if (eventNames.some((n) => keyMatchesRule(n, ft.stoppedKeys))) {
                 return true;
             }
         }
     }
-    if (tryMatchBindings(layer.bindings, unblocked, input, key, shouldSkipOnlyThis))
+    if (tryMatchBindings(layer.bindings, available, input, key, shouldSkipOnlyThis))
         return true;
     if (isTop && eventNames.some((n) => keyMatchesRule(n, layer.stoppedKeys))) {
         return true;

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

@@ -46,9 +46,9 @@ 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.
+    // fix: The stop API and penetration 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
+    // So the expectation is that, So the Stop API returns miss: false, but the penetration API returns miss: true
     // TODO: You need to modify the corresponding test and do it later.
     // @2026-06-23 3.6.1
     if (handled) {

package/dist/keyboard/provider.d.ts

@@ -17,7 +17,7 @@ export interface KeyboardProviderProps {
 /**
  * Keyboard context provider for layered key handling.
  *
- * Manages per-screen-layer key bindings, transparent keys (`blockedKey`),
+ * Manages per-screen-layer key bindings, transparent keys (`penetration`),
  * key-stop propagation barriers (`stop`), and global keys (`globalKeys`).
  * Handles the full event priority chain:
  *   1. Global keys with `affectOverlay: true`

package/dist/keyboard/provider.js

@@ -196,7 +196,7 @@ function finalizeBoundKeyboard(bindingsArray, actionKeysMap, layer, entry, handl
 /**
  * Keyboard context provider for layered key handling.
  *
- * Manages per-screen-layer key bindings, transparent keys (`blockedKey`),
+ * Manages per-screen-layer key bindings, transparent keys (`penetration`),
  * key-stop propagation barriers (`stop`), and global keys (`globalKeys`).
  * Handles the full event priority chain:
  *   1. Global keys with `affectOverlay: true`
@@ -346,7 +346,7 @@ export function KeyboardProvider({ children }) {
             layer = {
                 kind,
                 bindings: [],
-                blockedKeys: [],
+                penetrationKeys: [],
                 stoppedKeys: [],
                 allowedKeys: [],
                 globalKeyOverrides: new Set(),
@@ -408,7 +408,7 @@ export function KeyboardProvider({ children }) {
         if (!target) {
             target = {
                 bindings: [],
-                blockedKeys: [],
+                penetrationKeys: [],
                 stoppedKeys: [],
                 allowedKeys: [],
                 actionKeysMap: new Map(),
@@ -567,14 +567,14 @@ export function KeyboardProvider({ children }) {
     const penetration = useCallback((keys, options) => {
         const owner = getCurrentOwner();
         if (!owner) {
-            throw new Error('[Ink-Cartridge] blockedKey() must be called inside a screen component or overlay.');
+            throw new Error('[Ink-Cartridge] penetration() must be called inside a screen component or overlay.');
         }
         const layer = getLayer(owner);
         const compiledWhen = options?.when;
         const container = options?.focusId
             ? getOrCreateFocusTarget(layer, options.focusId)
             : layer;
-        return pushKeyEntries(container, 'blockedKeys', keys, (key) => ({
+        return pushKeyEntries(container, 'penetrationKeys', keys, (key) => ({
             key,
             when: compiledWhen,
         }));
@@ -970,7 +970,7 @@ export function KeyboardProvider({ children }) {
     const readLayer = useCallback((owner) => layersRef.current.get(owner), []);
     const value = useMemo(() => ({
         boundKeyboard,
-        blockedKey: penetration,
+        penetration,
         stop,
         globalKeys,
         getGlobalKeys,

package/dist/keyboard/types.d.ts

@@ -3,7 +3,7 @@ import type { OverlayEntry } from "../screen/types.js";
 /**
  * A single key rule with an optional when condition.
  *
- * Used internally for blockedKeys and stoppedKeys to support
+ * Used internally for penetrationKeys and stoppedKeys to support
  * conditional transparency and conditional propagation barriers.
  */
 export interface KeyRule {
@@ -132,7 +132,7 @@ export interface FocusTarget {
     /** Registered key bindings (evaluation order). */
     bindings: BoundKeyEntry[];
     /** Key rules marked as transparent on this target (pass-through). */
-    blockedKeys: KeyRule[];
+    penetrationKeys: KeyRule[];
     /** Key rules stopped on this target (propagation barrier). */
     stoppedKeys: KeyRule[];
     /**
@@ -256,7 +256,7 @@ export interface ScreenKeyboardLayer {
     /** Registered screen-level key bindings (evaluation order). */
     bindings: BoundKeyEntry[];
     /** Key rules marked as transparent at the screen level (pass-through). */
-    blockedKeys: KeyRule[];
+    penetrationKeys: KeyRule[];
     /** Key rules stopped at the screen level (propagation barrier). */
     stoppedKeys: KeyRule[];
     /**
@@ -303,7 +303,7 @@ export interface ScreenKeyboardLayer {
  * Event object passed to the {@link ModalMissCallback}.
  *
  * When `miss` is `false`, the key was handled (by a binding, Tab
- * navigation, sequence, or — depending on options — stop/blockedKey).
+ * navigation, sequence, or — depending on options — stop/penetration).
  * When `miss` is `true`, the remaining fields describe the key that
  * was not handled by any mechanism visible to the miss detector.
  */
@@ -365,16 +365,16 @@ export interface StopOptions {
     when?: () => boolean;
 }
 /**
- * Options for {@link KeyboardContextValue.blockedKey} when marking keys
+ * Options for {@link KeyboardContextValue.penetration} when marking keys
  * as transparent within a specific focus target.
  */
-export interface BlockedKeyOptions {
-    /** If provided, blocks only within the named focus target. */
+export interface PenetrationOptions {
+    /** If provided, penetrates only within the named focus target. */
     focusId?: string;
     /**
      * Optional condition callback. When provided, the key is only transparent
-     * (blocked) when this returns `true`. When `false`, the blocked-key rule
-     * is ignored and the key is not blocked.
+     * when this returns `true`. When `false`, the penetration rule
+     * is ignored and the key is not passed through.
      */
     when?: () => boolean;
 }

package/dist/screen/provider.js

@@ -251,9 +251,11 @@ function recalcActiveAfterNavigation(persistentOverlays, persistentModals, newTo
         }
     }
     let activeModalId = null;
+    let maxZ = -1;
     for (const m of persistentModals) {
-        if (m.originComponent === newTopScreen) {
+        if (m.originComponent === newTopScreen && m.zIndex > maxZ) {
             activeModalId = m.id;
+            maxZ = m.zIndex;
         }
     }
     return { activeOverlayIds, activeModalId };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ink-cartridge",
-    "version": "3.8.1",
+    "version": "3.8.2",
     "description": "Ready-to-use Ink components and screen management system for building terminal UIs.",
     "type": "module",
     "main": "./dist/index.js",