ink-cartridge 3.8.0 → 3.8.2

package/README.md

@@ -1,6 +1,15 @@
-# ink-cartridge
+<div align="center">
+        <br>
+        <br>
+        <img width="440" alt="cartridge" src="static/cartridge.png">
+        <br>
+        <br>
+        <br>					 
+</div>
 
-> A component kit for rapidly building complex, multi-page, interaction-heavy terminal applications — filling the critical gaps Ink leaves open.
+<h1 align="center">Cartridge</h1>
+
+>A component kit for rapidly building complex, multi-page, interaction-heavy terminal applications — filling the critical gaps Ink leaves open.
 
 [![CI](https://github.com/BAIGAOa/ink-cartridge/actions/workflows/ci.yml/badge.svg)](https://github.com/BAIGAOa/ink-trc/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/ink-cartridge.svg)](https://www.npmjs.com/package/ink-cartridge)
@@ -47,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)
@@ -157,8 +166,8 @@ 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
 
-[MIT](LICENSE)
+[MIT](LICENSE)

package/dist/components/multi-select/MultiSelectInput.d.ts

@@ -41,85 +41,4 @@ import type { MultiSelectInputProps, Item } from './types.js';
  * />
  * ```
  */
-export declare function MultiSelectInput<T, I extends Item<T> = Item<T>>({ items, selected: controlledSelected, defaultSelected, onChange, onSubmit, onSelect, onUnselect, onHighlight, indicatorComponent, checkboxComponent, itemComponent, focusId, limit: limitProp, initialIndex, storage, storageKey, }: MultiSelectInputProps<T, I>): React.FunctionComponentElement<{
-    readonly position?: "absolute" | "relative" | "static" | undefined;
-    readonly top?: number | string | undefined;
-    readonly right?: number | string | undefined;
-    readonly bottom?: number | string | undefined;
-    readonly left?: number | string | undefined;
-    readonly columnGap?: number | undefined;
-    readonly rowGap?: number | undefined;
-    readonly gap?: number | undefined;
-    readonly margin?: number | undefined;
-    readonly marginX?: number | undefined;
-    readonly marginY?: number | undefined;
-    readonly marginTop?: number | undefined;
-    readonly marginBottom?: number | undefined;
-    readonly marginLeft?: number | undefined;
-    readonly marginRight?: number | undefined;
-    readonly padding?: number | undefined;
-    readonly paddingX?: number | undefined;
-    readonly paddingY?: number | undefined;
-    readonly paddingTop?: number | undefined;
-    readonly paddingBottom?: number | undefined;
-    readonly paddingLeft?: number | undefined;
-    readonly paddingRight?: number | undefined;
-    readonly flexGrow?: number | undefined;
-    readonly flexShrink?: number | undefined;
-    readonly flexDirection?: "row" | "column" | "row-reverse" | "column-reverse" | undefined;
-    readonly flexBasis?: number | string | undefined;
-    readonly flexWrap?: "nowrap" | "wrap" | "wrap-reverse" | undefined;
-    readonly alignItems?: "flex-start" | "center" | "flex-end" | "stretch" | "baseline" | undefined;
-    readonly alignSelf?: "flex-start" | "center" | "flex-end" | "auto" | "stretch" | "baseline" | undefined;
-    readonly alignContent?: "flex-start" | "flex-end" | "center" | "stretch" | "space-between" | "space-around" | "space-evenly" | undefined;
-    readonly justifyContent?: "flex-start" | "flex-end" | "space-between" | "space-around" | "space-evenly" | "center" | undefined;
-    readonly width?: number | string | undefined;
-    readonly height?: number | string | undefined;
-    readonly minWidth?: number | string | undefined;
-    readonly minHeight?: number | string | undefined;
-    readonly maxWidth?: number | string | undefined;
-    readonly maxHeight?: number | string | undefined;
-    readonly aspectRatio?: number | undefined;
-    readonly display?: "flex" | "none" | undefined;
-    readonly borderStyle?: (keyof import("cli-boxes").Boxes | import("cli-boxes").BoxStyle) | undefined;
-    readonly borderTop?: boolean | undefined;
-    readonly borderBottom?: boolean | undefined;
-    readonly borderLeft?: boolean | undefined;
-    readonly borderRight?: boolean | undefined;
-    readonly borderColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
-    readonly borderTopColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
-    readonly borderBottomColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
-    readonly borderLeftColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
-    readonly borderRightColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
-    readonly borderDimColor?: boolean | undefined;
-    readonly borderTopDimColor?: boolean | undefined;
-    readonly borderBottomDimColor?: boolean | undefined;
-    readonly borderLeftDimColor?: boolean | undefined;
-    readonly borderRightDimColor?: boolean | undefined;
-    readonly borderBackgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
-    readonly borderTopBackgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
-    readonly borderBottomBackgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
-    readonly borderLeftBackgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
-    readonly borderRightBackgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
-    readonly overflow?: "visible" | "hidden" | undefined;
-    readonly overflowX?: "visible" | "hidden" | undefined;
-    readonly overflowY?: "visible" | "hidden" | undefined;
-    readonly backgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
-} & {
-    readonly 'aria-label'?: string;
-    readonly 'aria-hidden'?: boolean;
-    readonly 'aria-role'?: "button" | "checkbox" | "combobox" | "list" | "listbox" | "listitem" | "menu" | "menuitem" | "option" | "progressbar" | "radio" | "radiogroup" | "tab" | "tablist" | "table" | "textbox" | "timer" | "toolbar";
-    readonly 'aria-state'?: {
-        readonly busy?: boolean;
-        readonly checked?: boolean;
-        readonly disabled?: boolean;
-        readonly expanded?: boolean;
-        readonly multiline?: boolean;
-        readonly multiselectable?: boolean;
-        readonly readonly?: boolean;
-        readonly required?: boolean;
-        readonly selected?: boolean;
-    };
-} & {
-    children?: React.ReactNode | undefined;
-} & React.RefAttributes<import("ink").DOMElement>>;
+export declare function MultiSelectInput<T, I extends Item<T> = Item<T>>({ items, selected: controlledSelected, defaultSelected, onChange, onSubmit, onSelect, onUnselect, onHighlight, indicatorComponent, checkboxComponent, itemComponent, focusId, limit: limitProp, initialIndex, storage, storageKey, }: MultiSelectInputProps<T, I>): React.JSX.Element;

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).
@@ -33,4 +33,4 @@ import { DevProps } from "./types.js";
  *
  * @2026-06-23 3.6.1
  */
-export declare function DevScreen({ top: initialTop, left }: DevProps): React.JSX.Element;
+export declare function DevScreen({ top: initialTop, left, allowKeys }: DevProps): React.JSX.Element;

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).
@@ -165,10 +165,11 @@ function LayerSummary({ topComponent, readLayer }) {
  *
  * @2026-06-23 3.6.1
  */
-export function DevScreen({ top: initialTop, left }) {
+export function DevScreen({ top: initialTop, left, allowKeys }) {
     const { currentPath, displayedOverlays, activeOverlayIds, modalQueue, activeModalId, } = useScreenSystem();
-    const { boundKeyboard, readLayer } = useKeyboard();
-    const modalId = useContext(ModalContext);
+    const { boundKeyboard, readLayer, allowModal } = useKeyboard();
+    const modalCtx = useContext(ModalContext);
+    const modalId = modalCtx?.id ?? null;
     const { rows } = useWindowSize();
     const { openModal } = useScreenSystem();
     const [offsetTop, setOffsetTop] = useState(initialTop);
@@ -200,6 +201,9 @@ export function DevScreen({ top: initialTop, left }) {
                 clearTimeout(flashTimerRef.current);
         };
     }, []);
+    useEffect(() => {
+        return allowModal(allowKeys ?? []);
+    }, [allowModal]);
     useEffect(() => {
         const u1 = boundKeyboard(['up'], () => setOffsetTop(prev => clampTopRef.current(prev - 1)));
         const u2 = boundKeyboard(['down'], () => setOffsetTop(prev => clampTopRef.current(prev + 1)));

package/dist/dev/entrance.d.ts

@@ -3,43 +3,48 @@ import { DevProps } from "./types.js";
  * Open the developer debugging modal.
  *
  * Calls {@link openModal} with the fixed modal ID `_Dev-Tool_` and
- * the {@link DevScreen} component. Repeated calls while the modal is
- * already open will throw — guard with a ref or state flag to implement
- * a toggle (see example).
+ * the {@link DevScreen} component, using `persistent: true` by default
+ * so the panel survives screen navigation. Keyboard focus is
+ * automatically suspended when navigating away and restored when
+ * returning to the originating screen.
+ *
+ * Safe to call when the modal is already open — the underlying
+ * {@link openModal} treats duplicate IDs as a no-op, so a simple key
+ * binding without a toggle ref suffices:
+ *
+ * {@link closeDevTool} is the inverse.
  *
  * When open, DevScreen blocks all keyboard events from reaching
- * overlays and screens. The modal provides its own close mechanism
- * via the Escape key.
+ * overlays and screens. Pass `allowKeys` to let specific keys through
+ * (e.g. `allowKeys: ['ctrl+d']` to toggle the tool itself).
  *
- * @param top  - Initial vertical position in rows (0 = top of terminal).
- * @param left - Horizontal position in columns.
+ * @param top       - Initial vertical position in rows (0 = top of terminal).
+ * @param left      - Horizontal position in columns.
+ * @param zindex    - Optional modal z-index for stacking order.
+ * @param allowKeys - Keys allowed to pass through the modal to layers below.
+ * @param persistent - Whether the dev tool survives screen navigation. Defaults to `true`.
  *
- * @throws If `ScenarioManagementProvider` is not mounted, or the modal
- *         ID `_Dev-Tool_` is already open.
+ * @throws If `ScenarioManagementProvider` is not mounted.
  *
  * @example
  * ```ts
- * // Toggle with a ref to avoid duplicate-open errors:
- * const devOpenRef = useRef(false);
+ * // Press Ctrl+D to open the dev tool (no-op if already open):
+ * boundKeyboard(['ctrl+d'], () => openDevTool({ top: 0, left: 0 }));
+ *
+ * // Toggle requires allowKeys so the second press can pass through:
  * boundKeyboard(['ctrl+d'], () => {
- *   if (devOpenRef.current) {
- *     closeDevTool();
- *     devOpenRef.current = false;
- *   } else {
- *     openDevTool({ top: 0, left: 0 });
- *     devOpenRef.current = true;
- *   }
+ *   try { openDevTool({ top: 0, left: 0, allowKeys: ['ctrl+d'] }); } catch {}
  * });
  * ```
+ * @2026-07-04 v3.8.0
  */
-export declare function openDevTool({ top, left, zindex }: DevProps): void;
+export declare function openDevTool({ top, left, zindex, allowKeys, persistent }: DevProps): void;
 /**
  * Close the developer debugging modal.
  *
  * Calls {@link closeModal} for the fixed modal ID `_Dev-Tool_`.
- * Safe to call even if the modal is not currently open — acts as
- * a no-op in that case to support toggle patterns where the modal
- * may have been closed by its own Escape binding.
+ * Safe to call even if the modal is not currently open — the underlying
+ * {@link closeModal} treats non-existent IDs as a no-op.
  *
  * @example
  * ```ts

package/dist/dev/entrance.js

@@ -4,51 +4,58 @@ import { DevScreen } from "./dev-screen.js";
  * Open the developer debugging modal.
  *
  * Calls {@link openModal} with the fixed modal ID `_Dev-Tool_` and
- * the {@link DevScreen} component. Repeated calls while the modal is
- * already open will throw — guard with a ref or state flag to implement
- * a toggle (see example).
+ * the {@link DevScreen} component, using `persistent: true` by default
+ * so the panel survives screen navigation. Keyboard focus is
+ * automatically suspended when navigating away and restored when
+ * returning to the originating screen.
+ *
+ * Safe to call when the modal is already open — the underlying
+ * {@link openModal} treats duplicate IDs as a no-op, so a simple key
+ * binding without a toggle ref suffices:
+ *
+ * {@link closeDevTool} is the inverse.
  *
  * When open, DevScreen blocks all keyboard events from reaching
- * overlays and screens. The modal provides its own close mechanism
- * via the Escape key.
+ * overlays and screens. Pass `allowKeys` to let specific keys through
+ * (e.g. `allowKeys: ['ctrl+d']` to toggle the tool itself).
  *
- * @param top  - Initial vertical position in rows (0 = top of terminal).
- * @param left - Horizontal position in columns.
+ * @param top       - Initial vertical position in rows (0 = top of terminal).
+ * @param left      - Horizontal position in columns.
+ * @param zindex    - Optional modal z-index for stacking order.
+ * @param allowKeys - Keys allowed to pass through the modal to layers below.
+ * @param persistent - Whether the dev tool survives screen navigation. Defaults to `true`.
  *
- * @throws If `ScenarioManagementProvider` is not mounted, or the modal
- *         ID `_Dev-Tool_` is already open.
+ * @throws If `ScenarioManagementProvider` is not mounted.
  *
  * @example
  * ```ts
- * // Toggle with a ref to avoid duplicate-open errors:
- * const devOpenRef = useRef(false);
+ * // Press Ctrl+D to open the dev tool (no-op if already open):
+ * boundKeyboard(['ctrl+d'], () => openDevTool({ top: 0, left: 0 }));
+ *
+ * // Toggle requires allowKeys so the second press can pass through:
  * boundKeyboard(['ctrl+d'], () => {
- *   if (devOpenRef.current) {
- *     closeDevTool();
- *     devOpenRef.current = false;
- *   } else {
- *     openDevTool({ top: 0, left: 0 });
- *     devOpenRef.current = true;
- *   }
+ *   try { openDevTool({ top: 0, left: 0, allowKeys: ['ctrl+d'] }); } catch {}
  * });
  * ```
+ * @2026-07-04 v3.8.0
  */
-export function openDevTool({ top, left, zindex }) {
+export function openDevTool({ top, left, zindex, allowKeys, persistent = true }) {
     openModal('_Dev-Tool_', DevScreen, {
         top: top,
-        left: left
+        left: left,
+        allowKeys: allowKeys,
     }, {
         zIndex: zindex,
-        renderNow: true
+        renderNow: true,
+        persistent,
     });
 }
 /**
  * Close the developer debugging modal.
  *
  * Calls {@link closeModal} for the fixed modal ID `_Dev-Tool_`.
- * Safe to call even if the modal is not currently open — acts as
- * a no-op in that case to support toggle patterns where the modal
- * may have been closed by its own Escape binding.
+ * Safe to call even if the modal is not currently open — the underlying
+ * {@link closeModal} treats non-existent IDs as a no-op.
  *
  * @example
  * ```ts
@@ -56,12 +63,5 @@ export function openDevTool({ top, left, zindex }) {
  * ```
  */
 export function closeDevTool() {
-    try {
-        closeModal('_Dev-Tool_');
-    }
-    catch {
-        // Modal already closed — no-op. This handles the case where
-        // the Escape key inside DevScreen closed the modal, leaving
-        // an external toggle ref stale.
-    }
+    closeModal('_Dev-Tool_');
 }

package/dist/dev/globalKey-display.js

@@ -51,7 +51,8 @@ const Sep = () => (React.createElement(Box, null,
 export default function GlobalKeyDisplayBox({ top: initialTop, left }) {
     const { getGlobalKeys, boundKeyboard } = useKeyboard();
     const { closeModal } = useScreenSystem();
-    const modalId = useContext(ModalContext);
+    const modalCtx = useContext(ModalContext);
+    const modalId = modalCtx?.id ?? null;
     const { rows } = useWindowSize();
     const [offsetTop, setOffsetTop] = useState(initialTop);
     const [expandedEntry, setExpandedEntry] = useState(null);

package/dist/dev/globalSeq-display.js

@@ -56,7 +56,8 @@ const Sep = () => (React.createElement(Box, null,
 export default function GlobalSequenceDisplayBox({ top: initialTop, left }) {
     const { getGlobalSequences, getGlobalPendingSequence, boundKeyboard } = useKeyboard();
     const { closeModal } = useScreenSystem();
-    const modalId = useContext(ModalContext);
+    const modalCtx = useContext(ModalContext);
+    const modalId = modalCtx?.id ?? null;
     const { rows } = useWindowSize();
     const [offsetTop, setOffsetTop] = useState(initialTop);
     const [expandedEntry, setExpandedEntry] = useState(null);

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" },
@@ -140,7 +140,8 @@ function FocusTargetDetail({ focusId, target }) {
 export default function LayerKeyDisplayBox({ top: initialTop, left, screenComponent }) {
     const { readLayer, boundKeyboard } = useKeyboard();
     const { closeModal } = useScreenSystem();
-    const modalId = useContext(ModalContext);
+    const modalCtx = useContext(ModalContext);
+    const modalId = modalCtx?.id ?? null;
     const { rows } = useWindowSize();
     const [offsetTop, setOffsetTop] = useState(initialTop);
     const [expandedEntry, setExpandedEntry] = useState(null);
@@ -212,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}`,
         });
@@ -248,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 });
         }
@@ -265,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/dev/types.d.ts

@@ -7,6 +7,10 @@ export interface DevProps {
     /** Horizontal position in columns — 0 is the left edge. */
     left: number;
     zindex?: number;
+    /** Keys allowed to pass through the dev tool modal to layers below. */
+    allowKeys?: string[];
+    /** Whether the dev tool survives screen navigation. Defaults to `true`. */
+    persistent?: boolean;
 }
 /**
  * Props accepted by the {@link GlobalKeyDisplayBox} global-keys inspector modal.

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).
@@ -18,17 +18,21 @@ export interface KeyboardContextValue {
      * 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)` —
+     * 2. `(keys: string | string[], actionId: string, options?: BoundKeyboardOptions)` —
+     *    explicit keys referencing a registered shortcut action by id.
+     * 3. `(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 handler  Callback receiving the raw `input` and `key` from Ink,
+     *                 or a registered shortcut action id string.
      * @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;
+        (keys: string | string[], actionId: string, options?: BoundKeyboardOptions): () => void;
+        (actionId: string, options?: BoundKeyboardOptions): () => void;
     };
     /**
      * Mark one or more keys as "transparent" on the current layer.
@@ -41,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,