ink-cartridge 3.8.1 → 3.8.3

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)
@@ -109,6 +109,7 @@ npx ink-cartridge init my-tui
 - [TextInput](docs/components/TextInput/TextInput-API.md)
 - [UncontrolledTextInput](docs/components/TextInput/UncontrolledTextInput-API.md)
 - [NumberInput](docs/components/NumberInput/NumberInput-API.md)
+- [SearchBar](docs/components/SearchBar/SearchBar-API.md)
 - [SearchInput](docs/components/SearchInput/SearchInput-API.md)
 - [ConfirmDialog](docs/components/ConfirmDialog/ConfirmDialog-API.md)
 - [Spinner](docs/components/Spinner/Spinner-API.md)
@@ -164,9 +165,9 @@ npx ink-cartridge init my-tui
 - [closeDevTool](docs/dev-tool/closeDevTool-API.md)
 </details>
 
-## Other
+## Examples
 
-The method `blockedKey` is poorly named — it means *pass-through*, not "block." The internal name is `penetration`. Too late to rename now.
+Runnable demos for every component. See [examples/README.md](examples/README.md) for the full list and run commands.
 
 ## License
 

package/dist/components/search-bar/SearchBar.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import type { SearchBarItem, SearchBarProps } from "./search-bar-types.js";
+export default function SearchBar<T, I extends SearchBarItem<T> = SearchBarItem<T>>({ focusId, width, items, onSubmit, selectBar: SelectBar, }: SearchBarProps<T, I>): React.JSX.Element;

package/dist/components/search-bar/SearchBar.js

@@ -0,0 +1,62 @@
+import { Box, Text, useWindowSize } from "ink";
+import React, { useState, useMemo, useEffect, useCallback } from "react";
+import { TextInput } from "../text/TextInput.js";
+import { useKeyboard } from "../../keyboard/hook.js";
+/**
+ * Filter and sort items by query against their labels.
+ * Priority: exact match → prefix match → earlier substring position.
+ */
+function filterAndSort(items, query) {
+    if (!query.trim())
+        return items;
+    const lower = query.toLowerCase();
+    return items
+        .filter((item) => item.label.toLowerCase().includes(lower))
+        .sort((a, b) => {
+        const aLower = a.label.toLowerCase();
+        const bLower = b.label.toLowerCase();
+        if (aLower === lower && bLower !== lower)
+            return -1;
+        if (aLower !== lower && bLower === lower)
+            return 1;
+        const aStarts = aLower.startsWith(lower);
+        const bStarts = bLower.startsWith(lower);
+        if (aStarts && !bStarts)
+            return -1;
+        if (!aStarts && bStarts)
+            return 1;
+        return aLower.indexOf(lower) - bLower.indexOf(lower);
+    });
+}
+export default function SearchBar({ focusId, width, items = [], onSubmit, selectBar: SelectBar, }) {
+    const [value, setValue] = useState("");
+    const { columns } = useWindowSize();
+    const { focusSet, boundKeyboard } = useKeyboard();
+    const inputWidth = width ?? Math.max(1, columns - 4);
+    const resultsFocusId = `${focusId}-results`;
+    // Filter and sort results whenever the query or items change.
+    const results = useMemo(() => filterAndSort(items, value), [items, value]);
+    /**
+     * When selectBar confirms a selection, fire onSubmit and return
+     * focus to the TextInput.
+     */
+    const handleSelect = useCallback((item) => {
+        onSubmit?.(item);
+        focusSet(focusId);
+    }, [onSubmit, focusSet, focusId]);
+    // Enter in TextInput switches focus to the selectBar.
+    // Registered at screen level so it fires after TextInput's focus-level
+    // bindings (TextInput does not bind 'return' when onSubmit is not passed).
+    useEffect(() => {
+        const unReturn = boundKeyboard(['return'], () => {
+            focusSet(resultsFocusId);
+        });
+        return unReturn;
+    }, [boundKeyboard, focusSet, resultsFocusId]);
+    return (React.createElement(Box, { flexDirection: "column", width: "100%", height: "100%", borderColor: "white", borderStyle: "bold" },
+        React.createElement(Box, { flexDirection: "row" },
+            React.createElement(Text, { bold: true }, "> "),
+            React.createElement(TextInput, { focusId: focusId, value: value, onChange: setValue, width: inputWidth })),
+        React.createElement(Text, { bold: true }, "-".repeat(inputWidth)),
+        React.createElement(SelectBar, { items: results, onSelect: handleSelect, focusId: resultsFocusId, query: value })));
+}

package/dist/components/search-bar/search-bar-types.d.ts

@@ -0,0 +1,39 @@
+import type React from "react";
+export interface SearchBarItem<T> {
+    /** Display text shown in the results list */
+    label: string;
+    /** Value returned to onSubmit when this item is selected */
+    value: T;
+    /** Optional stable key for React reconciliation */
+    Key?: string;
+}
+export interface SearchBarProps<T, I extends SearchBarItem<T> = SearchBarItem<T>> {
+    /** Focus identifier for the TextInput in the keyboard system */
+    focusId: string;
+    /**
+     * Input area width in characters. When omitted, auto-detected from
+     * terminal dimensions (columns - 4 for border + prompt).
+     */
+    width?: number;
+    /** Items to search through. Filtered and sorted by label as the user types. */
+    items?: I[];
+    /**
+     * Called when the user confirms a selection via the selectBar.
+     * Receives the selected item.
+     */
+    onSubmit?: (item: I) => void;
+    /**
+     * Component that renders the filtered results and handles selection.
+     * Receives filtered items, an onSelect callback, a focusId for keyboard
+     * integration, and the current query string.
+     *
+     * Must be a component that registers its own keyboard bindings under the
+     * given focusId (e.g. SelectInput).
+     */
+    selectBar: React.ComponentType<{
+        items: I[];
+        onSelect: (item: I) => void;
+        focusId: string;
+        query: string;
+    }>;
+}

package/dist/components/search-bar/search-bar-types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/search-input/SearchInput.js

@@ -3,11 +3,14 @@ import { Box, Text } from 'ink';
 import { TextInput } from '../text/TextInput.js';
 import { useKeyboard } from '../../keyboard/index.js';
 export function SearchInput({ focusId, value, onChange, placeholder, onSubmit, }) {
-    const { boundKeyboard } = useKeyboard();
+    const { boundKeyboard, focusUnregister } = useKeyboard();
     useEffect(() => {
         const unEsc = boundKeyboard(['escape'], () => onChange(''), { focusId });
-        return () => { unEsc(); };
-    }, [focusId, onChange, boundKeyboard]);
+        return () => {
+            unEsc();
+            focusUnregister(focusId);
+        };
+    }, [focusId, onChange, boundKeyboard, focusUnregister]);
     return (React.createElement(Box, null,
         React.createElement(Text, { color: "blue" }, "Search "),
         React.createElement(TextInput, { focusId: focusId, value: value, onChange: onChange, placeholder: placeholder, onSubmit: onSubmit }),

package/dist/components/text/TextInput.d.ts

@@ -1,39 +1,7 @@
 import React from 'react';
 import type { TextInputProps, UncontrolledTextInputProps } from './types.js';
-/**
- * Controlled text input component integrated with the keyboard focus system.
- *
- * Supports:
- * - Arrow keys to move cursor
- * - Backspace/Delete to remove characters
- * - Regular character input (via wildcard '*')
- * - Optional mask (password mode)
- * - Paste highlighting (highlight the whole pasted block)
- * - Placeholder
- *
- * @example
- * ```tsx
- * const [name, setName] = useState('');
- * <TextInput
- *   focusId="name-field"
- *   value={name}
- *   onChange={setName}
- *   placeholder="Enter your name"
- *   showCursor
- * />
- * ```
- */
-export declare function TextInput({ placeholder, mask, showCursor, highlightPastedText, value: originalValue, onChange, onSubmit, focusId, }: TextInputProps): React.FunctionComponentElement<import("ink").TextProps>;
+export declare function TextInput({ placeholder, mask, showCursor, highlightPastedText, value: originalValue, onChange, onSubmit, focusId, wrap, width, }: TextInputProps): React.JSX.Element;
 /**
  * Uncontrolled text input component that manages its own internal state.
- *
- * @example
- * ```tsx
- * <UncontrolledTextInput
- *   focusId="search"
- *   initialValue="default"
- *   onSubmit={(val) => console.log(val)}
- * />
- * ```
  */
-export declare function UncontrolledTextInput({ initialValue, storage, storageKey, ...props }: UncontrolledTextInputProps): React.FunctionComponentElement<TextInputProps>;
+export declare function UncontrolledTextInput({ initialValue, storage, storageKey, ...props }: UncontrolledTextInputProps): React.JSX.Element;

package/dist/components/text/TextInput.js

@@ -1,34 +1,53 @@
 import React, { useState, useEffect, useCallback, useRef } from 'react';
-import { Text } from 'ink';
+import { Text, Box, useWindowSize } from 'ink';
 import chalk from 'chalk';
 import { useKeyboard, useFocusState } from '../../keyboard/index.js';
-/**
- * 将给定字符重复多次
- */
 function repeatChar(char, count) {
     return Array(count + 1).join(char);
 }
 /**
- * 计算光标在可见字符串中的偏移量，并生成带高亮（反色）的渲染结果
+ * Split text into wrapped lines at maxWidth boundaries.
  */
+function wrapLines(text, maxWidth) {
+    if (maxWidth <= 0 || text.length === 0)
+        return [''];
+    const lines = [];
+    for (let i = 0; i < text.length; i += maxWidth) {
+        lines.push(text.slice(i, i + maxWidth));
+    }
+    return lines;
+}
+/**
+ * Convert a flat cursor offset to {line, col} in wrap mode.
+ */
+function offsetToLineCol(offset, maxWidth) {
+    if (maxWidth <= 0)
+        return { line: 0, col: 0 };
+    return {
+        line: Math.floor(offset / maxWidth),
+        col: offset % maxWidth,
+    };
+}
+/**
+ * Convert {line, col} back to a flat cursor offset, clamped to [0, textLength].
+ */
+function lineColToOffset(line, col, maxWidth, textLength) {
+    const offset = line * maxWidth + col;
+    return Math.max(0, Math.min(offset, textLength));
+}
 function renderWithCursor(value, placeholder, mask, showCursor, isFocused, cursorOffset, cursorWidth, highlightPastedText) {
-    // 显示用的值：如果设置了掩码则每个字符替换为掩码字符
     const displayValue = mask ? repeatChar(mask, value.length) : value;
-    // 未聚焦或不需要显示光标 → 直接返回纯文本（空时显示占位符）
     if (!showCursor || !isFocused) {
         if (displayValue.length === 0 && placeholder) {
             return chalk.grey(placeholder);
         }
         return displayValue;
     }
-    // 聚焦且显示光标时的处理
-    // 空值 + 有占位符 → 占位符第一个字符反色，其余灰色
     if (displayValue.length === 0 && placeholder) {
         if (placeholder.length === 0)
             return chalk.inverse(' ');
         return chalk.inverse(placeholder[0]) + chalk.grey(placeholder.slice(1));
     }
-    // 实际高亮宽度（粘贴高亮时可能大于1）
     const actualHighlightWidth = highlightPastedText ? cursorWidth : 0;
     let result = '';
     for (let i = 0; i < displayValue.length; i++) {
@@ -37,84 +56,87 @@ function renderWithCursor(value, placeholder, mask, showCursor, isFocused, curso
             : i >= cursorOffset - actualHighlightWidth && i <= cursorOffset;
         result += isInHighlight ? chalk.inverse(displayValue[i]) : displayValue[i];
     }
-    // 光标在末尾时追加一个反色空格
     if (cursorOffset === displayValue.length) {
         result += chalk.inverse(' ');
     }
     return result;
 }
-/**
- * Controlled text input component integrated with the keyboard focus system.
- *
- * Supports:
- * - Arrow keys to move cursor
- * - Backspace/Delete to remove characters
- * - Regular character input (via wildcard '*')
- * - Optional mask (password mode)
- * - Paste highlighting (highlight the whole pasted block)
- * - Placeholder
- *
- * @example
- * ```tsx
- * const [name, setName] = useState('');
- * <TextInput
- *   focusId="name-field"
- *   value={name}
- *   onChange={setName}
- *   placeholder="Enter your name"
- *   showCursor
- * />
- * ```
- */
-export function TextInput({ placeholder = '', mask, showCursor = true, highlightPastedText = false, value: originalValue, onChange, onSubmit, focusId, }) {
+export function TextInput({ placeholder = '', mask, showCursor = true, highlightPastedText = false, value: originalValue, onChange, onSubmit, focusId, wrap = false, width, }) {
     const isFocused = useFocusState(focusId);
     const { boundKeyboard, focusUnregister, enableWildcardPriority } = useKeyboard();
-    // 光标位置（字符索引）
+    const { columns: terminalColumns } = useWindowSize();
+    // Available width: prop override or terminal width.
+    const availableWidth = Math.max(1, (width ?? terminalColumns) || 80);
+    // Virtual-scroll offset (only used when wrap=false).
+    const [scrollOffset, setScrollOffset] = useState(0);
+    // Cursor position (flat character index).
     const [cursorOffset, setCursorOffset] = useState(originalValue.length);
-    // 粘贴高亮宽度（一次插入的字符数）
+    // Paste highlight width.
     const [cursorWidth, setCursorWidth] = useState(0);
-    // 通配符优先模式的 disable 函数
+    // Wildcard priority disable function.
     const disablePriorityRef = useRef(null);
-    // 当外部 value 缩短时，修正光标位置避免越界
+    // Clamp cursor when external value shortens.
     useEffect(() => {
         setCursorOffset((prev) => Math.min(prev, originalValue.length));
     }, [originalValue]);
+    // When wrap mode changes or text is cleared externally, reset scroll.
+    const isTextEmpty = originalValue.length === 0;
+    useEffect(() => {
+        setScrollOffset(0);
+    }, [wrap, isTextEmpty]);
     /**
-     * 移动光标（左右箭头调用）
+     * Ensure the cursor is visible within the virtual-scroll window.
+     * No-op when wrap is enabled.
      */
+    const ensureVisible = useCallback((newOffset) => {
+        if (wrap)
+            return;
+        // Reserve 1 char per side for scroll indicators.
+        const visibleW = Math.max(1, availableWidth - 2);
+        const maxScroll = Math.max(0, originalValue.length - visibleW);
+        setScrollOffset((prev) => {
+            let next = prev;
+            if (newOffset < next)
+                next = newOffset;
+            if (newOffset >= next + visibleW)
+                next = newOffset - visibleW + 1;
+            return Math.max(0, Math.min(next, maxScroll));
+        });
+    }, [wrap, availableWidth, originalValue.length]);
     const moveCursor = useCallback((delta) => {
         if (!showCursor)
             return;
         setCursorOffset((prev) => {
             const next = prev + delta;
-            if (next < 0)
-                return 0;
-            if (next > originalValue.length)
-                return originalValue.length;
-            return next;
+            const clamped = Math.max(0, Math.min(next, originalValue.length));
+            ensureVisible(clamped);
+            return clamped;
         });
-        // 光标移动后清除粘贴高亮
         setCursorWidth(0);
-    }, [showCursor, originalValue.length]);
+    }, [showCursor, originalValue.length, ensureVisible]);
     /**
-     * 插入文本或删除字符
-     * @param insertion 要插入的字符串，undefined 表示执行删除操作
-     * @param isForwardDelete true 表示 Delete（删光标右侧），false/undefined 表示 Backspace（删光标左侧）
+     * Vertical cursor movement for wrap mode.
      */
+    const moveCursorVertical = useCallback((delta) => {
+        if (!showCursor || !wrap)
+            return;
+        const { line, col } = offsetToLineCol(cursorOffset, availableWidth);
+        const targetLine = Math.max(0, line + delta);
+        const newOffset = lineColToOffset(targetLine, col, availableWidth, originalValue.length);
+        setCursorOffset(newOffset);
+        setCursorWidth(0);
+    }, [showCursor, wrap, cursorOffset, availableWidth, originalValue.length]);
     const modifyText = useCallback((insertion, isForwardDelete = false) => {
         let newValue = originalValue;
         let newOffset = cursorOffset;
         if (insertion === undefined) {
-            // 删除操作
+            // Delete.
             if (isForwardDelete && cursorOffset < originalValue.length) {
-                // Delete：删除光标右侧一个字符
                 newValue =
                     originalValue.slice(0, cursorOffset) +
                         originalValue.slice(cursorOffset + 1);
-                // 光标位置不变
             }
             else if (!isForwardDelete && cursorOffset > 0) {
-                // Backspace：删除光标左侧一个字符
                 newValue =
                     originalValue.slice(0, cursorOffset - 1) +
                         originalValue.slice(cursorOffset);
@@ -125,17 +147,16 @@ export function TextInput({ placeholder = '', mask, showCursor = true, highlight
             }
         }
         else {
-            // 插入
+            // Insert.
             newValue =
                 originalValue.slice(0, cursorOffset) +
                     insertion +
                     originalValue.slice(cursorOffset);
             newOffset = cursorOffset + insertion.length;
         }
-        // 边界保护
         newOffset = Math.max(0, Math.min(newOffset, newValue.length));
         setCursorOffset(newOffset);
-        // 如果一次插入了多个字符且开启高亮，记录高亮宽度
+        ensureVisible(newOffset);
         if (insertion && insertion.length > 1 && highlightPastedText) {
             setCursorWidth(insertion.length);
         }
@@ -145,37 +166,39 @@ export function TextInput({ placeholder = '', mask, showCursor = true, highlight
         if (newValue !== originalValue) {
             onChange(newValue);
         }
-    }, [originalValue, cursorOffset, onChange, highlightPastedText]);
-    // 焦点目标生命周期 — focusId 变化时注销旧的，新的由绑定 effect 创建
+    }, [originalValue, cursorOffset, onChange, highlightPastedText, ensureVisible]);
+    // Focus lifecycle.
     useEffect(() => {
         return () => focusUnregister(focusId);
     }, [focusId, focusUnregister]);
-    // 注册键盘绑定（仅在获得焦点时生效）
+    // Keyboard bindings.
     useEffect(() => {
         const fid = focusId;
         const unbindList = [];
-        // 开启通配符最高优先级，确保所有普通字符输入优先被 TextInput 捕获
         disablePriorityRef.current?.();
         const disablePriority = enableWildcardPriority();
         disablePriorityRef.current = disablePriority;
-        // 左右移动光标
+        // Left/right.
         unbindList.push(boundKeyboard(['left'], () => moveCursor(-1), { focusId: fid }));
         unbindList.push(boundKeyboard(['right'], () => moveCursor(1), { focusId: fid }));
-        // 退格 / 删除
+        // Up/down (wrap mode only).
+        if (wrap) {
+            unbindList.push(boundKeyboard(['up'], () => moveCursorVertical(-1), { focusId: fid }));
+            unbindList.push(boundKeyboard(['down'], () => moveCursorVertical(1), { focusId: fid }));
+        }
+        // Backspace / Delete.
         unbindList.push(boundKeyboard(['backspace'], () => modifyText(), { focusId: fid }));
         unbindList.push(boundKeyboard(['delete'], () => modifyText(undefined, true), { focusId: fid }));
-        // 回车提交 — 提交时解除通配符最高优先级
+        // Enter — submit.
         if (onSubmit) {
             unbindList.push(boundKeyboard(['return'], () => {
-                // 用户提交后解除通配符优先级，恢复正常按键分发
                 disablePriority();
                 disablePriorityRef.current = null;
                 onSubmit(originalValue);
             }, { focusId: fid }));
         }
-        // 通配符 '*'：捕获所有普通字符输入
+        // Wildcard: capture all character input.
         unbindList.push(boundKeyboard(['*'], (input) => modifyText(input), { focusId: fid }));
-        // 清理：解绑所有键盘回调并恢复通配符优先级
         return () => {
             unbindList.forEach((fn) => fn());
             if (disablePriorityRef.current) {
@@ -187,26 +210,55 @@ export function TextInput({ placeholder = '', mask, showCursor = true, highlight
         focusId,
         boundKeyboard,
         moveCursor,
+        moveCursorVertical,
         modifyText,
         onSubmit,
         originalValue,
         enableWildcardPriority,
+        wrap,
     ]);
-    // 渲染最终显示的文本
-    const rendered = renderWithCursor(originalValue, placeholder, mask, showCursor, isFocused, cursorOffset, cursorWidth, highlightPastedText);
-    return React.createElement(Text, null, rendered);
+    // ── Render: wrap mode ──────────────────────────────────────────
+    if (wrap) {
+        const baseLines = wrapLines(originalValue, availableWidth);
+        const displayLines = baseLines.length === 0 ? [''] : [...baseLines];
+        const { line: cursorLine, col: cursorCol } = offsetToLineCol(cursorOffset, availableWidth);
+        // When empty and placeholder is set, show placeholder on first line.
+        if (originalValue.length === 0 && placeholder) {
+            return (React.createElement(Box, { flexDirection: "column" },
+                React.createElement(Text, null, renderWithCursor('', placeholder, mask, showCursor, isFocused, 0, 0, false))));
+        }
+        // Ensure the cursor always has a line to render on,
+        // even when it sits at the exact end of the last wrapped line.
+        while (displayLines.length <= cursorLine) {
+            displayLines.push('');
+        }
+        return (React.createElement(Box, { flexDirection: "column" }, displayLines.map((line, i) => {
+            if (i === cursorLine) {
+                return (React.createElement(Text, { key: i }, renderWithCursor(line, '', mask, showCursor, isFocused, cursorCol, cursorWidth, highlightPastedText)));
+            }
+            return React.createElement(Text, { key: i }, line);
+        })));
+    }
+    // ── Render: virtual-scroll mode ────────────────────────────────
+    if (originalValue.length === 0 && placeholder) {
+        return (React.createElement(Text, null, renderWithCursor('', placeholder, mask, showCursor, isFocused, 0, 0, false)));
+    }
+    if (originalValue.length <= availableWidth) {
+        return (React.createElement(Text, null, renderWithCursor(originalValue, '', mask, showCursor, isFocused, cursorOffset, cursorWidth, highlightPastedText)));
+    }
+    // Text is wider than available width — virtual scroll.
+    const visibleW = Math.max(1, availableWidth - 2);
+    const maxScroll = Math.max(0, originalValue.length - visibleW);
+    const windowStart = Math.max(0, Math.min(scrollOffset, maxScroll));
+    const windowText = originalValue.slice(windowStart, windowStart + visibleW);
+    const localCursor = cursorOffset - windowStart;
+    const textRendered = renderWithCursor(windowText, '', mask, showCursor, isFocused, localCursor, cursorWidth, highlightPastedText);
+    const leftIndicator = windowStart > 0 ? chalk.grey('←') : '';
+    const rightIndicator = windowStart + visibleW < originalValue.length ? chalk.grey('→') : '';
+    return React.createElement(Text, null, leftIndicator + textRendered + rightIndicator);
 }
 /**
  * Uncontrolled text input component that manages its own internal state.
- *
- * @example
- * ```tsx
- * <UncontrolledTextInput
- *   focusId="search"
- *   initialValue="default"
- *   onSubmit={(val) => console.log(val)}
- * />
- * ```
  */
 export function UncontrolledTextInput({ initialValue = '', storage, storageKey, ...props }) {
     const [value, setValue] = useState(initialValue);
@@ -225,9 +277,5 @@ export function UncontrolledTextInput({ initialValue = '', storage, storageKey,
         setValue(newVal);
         storage?.write.str(persistKey, newVal);
     };
-    return React.createElement(TextInput, {
-        ...props,
-        value,
-        onChange: handleChange,
-    });
+    return (React.createElement(TextInput, { ...props, value: value, onChange: handleChange }));
 }

package/dist/components/text/types.d.ts

@@ -39,6 +39,17 @@ export type TextInputProps = {
      * Must be unique on the current screen.
      */
     readonly focusId: string;
+    /**
+     * When true, text wraps to the next line instead of virtual-scrolling.
+     * Up/down arrow keys navigate between wrapped lines.
+     * @default false
+     */
+    readonly wrap?: boolean;
+    /**
+     * Available width in characters. When omitted, auto-detected from
+     * terminal dimensions via useWindowSize.
+     */
+    readonly width?: number;
 };
 /**
  * Props for the uncontrolled TextInput component.

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,8 +3,8 @@ 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 { useFocusState } from "./keyboard/index.js";
+export type { PenetrationOptions, AllowModalOptions, StopOptions, LayerKind, FocusTarget, SequenceOptions, ShortcutOperationEntry, SequenceOperationEntry, ModalMissEvent, ModalMissCallback, ModalMissOptions, ResolvedGlobalKeyEntry, } from "./keyboard/index.js";
+export { useFocusState, useModalMissListener } from "./keyboard/index.js";
 export { SelectInput } from "./components/select/SelectInput.js";
 export type { Item } from "./components/select/types.js";
 export type { SelectInputProps } from "./components/select/types.js";
@@ -24,6 +24,8 @@ export { Badge } from "./components/badge/Badge.js";
 export { KeyHint } from "./components/key-hint/KeyHint.js";
 export { NumberInput } from "./components/number-input/NumberInput.js";
 export { SearchInput } from "./components/search-input/SearchInput.js";
+export { default as SearchBar } from "./components/search-bar/SearchBar.js";
+export type { SearchBarItem, SearchBarProps } from "./components/search-bar/search-bar-types.js";
 export { Tabs } from "./components/tabs/Tabs.js";
 export type { Tab, TabsProps } from "./components/tabs/types.js";
 export { Fold } from "./components/fold/Fold.js";

package/dist/index.js

@@ -3,7 +3,7 @@ export { registerComponent, ScenarioManagementProvider, CurrentScreen, skip, bac
 // ── Keyboard System ────────────────────────────────────────
 export { KeyboardProvider, useKeyboard } from "./keyboard/index.js";
 export { normalizeKeyNames, isNormalCharacter } from "./keyboard/index.js";
-export { useFocusState } from "./keyboard/index.js";
+export { useFocusState, useModalMissListener } from "./keyboard/index.js";
 // Components — SelectInput
 export { SelectInput } from "./components/select/SelectInput.js";
 // Components — SelectRow
@@ -28,6 +28,8 @@ export { KeyHint } from "./components/key-hint/KeyHint.js";
 export { NumberInput } from "./components/number-input/NumberInput.js";
 // Components — SearchInput
 export { SearchInput } from "./components/search-input/SearchInput.js";
+// Components — SearchBar
+export { default as SearchBar } from "./components/search-bar/SearchBar.js";
 // Components — Tabs
 export { Tabs } from "./components/tabs/Tabs.js";
 // Components — Fold

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

@@ -1,18 +1,24 @@
 import { handleLayer } from '../layer-handler.js';
+function passAllowedKeys(allowedKeys, blockedKeys, eventNames) {
+    return allowedKeys.some((k) => !blockedKeys.includes(k.key) && eventNames.includes(k.key));
+}
 /**
  * Check whether a key event matches any entry in the allow-list of
  * the active focus target or the layer itself.
  */
 function isAllowed(layer, eventNames) {
-    if (layer.allowedKeys.some((r) => eventNames.includes(r.key))) {
-        return true;
-    }
+    const blockedKeys = layer.allowedKeys
+        .filter((r) => r.when?.() === false)
+        .map((r) => r.key);
     if (layer.currentFocusId) {
         const ft = layer.focusTargets.get(layer.currentFocusId);
-        if (ft?.allowedKeys.some((r) => eventNames.includes(r.key))) {
+        if (ft && passAllowedKeys(ft.allowedKeys, blockedKeys, eventNames)) {
             return true;
         }
     }
+    if (passAllowedKeys(layer.allowedKeys, blockedKeys, eventNames)) {
+        return true;
+    }
     return false;
 }
 /**
@@ -46,9 +52,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(),
@@ -434,7 +434,7 @@ export function KeyboardProvider({ children }) {
         const container = options?.focusId
             ? getOrCreateFocusTarget(layer, options.focusId)
             : layer;
-        return pushKeyEntries(container, 'allowedKeys', keys, (key) => ({ key }));
+        return pushKeyEntries(container, 'allowedKeys', keys, (key) => ({ key, when: options?.when }));
     }, [getCurrentOwner, getLayer, getOrCreateFocusTarget]);
     /**
      * Bind keys on the current layer (screen or overlay).
@@ -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;
 }
@@ -385,6 +385,8 @@ export interface BlockedKeyOptions {
 export interface AllowModalOptions {
     /** If provided, allows only within the named focus target. */
     focusId?: string;
+    /** Optional condition callback. When provided, the key is only allowed through when this returns `true`. When `false`, the allow rule is ignored and the key is blocked. */
+    when?: () => boolean;
 }
 /**
  * A single global key definition.

package/dist/screen/context.d.ts

@@ -51,6 +51,8 @@ export interface ScreenSystemContextValue {
     closeModal: CloseModalFn;
     /** Close all open modals at once. */
     closeAllModals: CloseAllModalsFn;
+    /** Whether to turn on full screen effect */
+    fullScreen?: boolean;
 }
 /**
  * React context for the screen navigation system.

package/dist/screen/current-screen.js

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Box } from 'ink';
+import { Box, useWindowSize } from 'ink';
 import { useScreenSystem } from './hook.js';
 import { OverlayContext } from './OverlayContext.js';
 import { ModalContext } from './ModalContext.js';
@@ -18,7 +18,8 @@ import { ModalContext } from './ModalContext.js';
  * Architecturally symmetric between overlays and modals.
  */
 export function CurrentScreen() {
-    const { currentScreen, currentOverlays, displayedOverlays, currentModals, renderedModalEntries } = useScreenSystem();
+    const { currentScreen, currentOverlays, displayedOverlays, currentModals, renderedModalEntries, fullScreen } = useScreenSystem();
+    const { rows } = useWindowSize();
     // Build overlay elements with OverlayContext wrappers
     const wrappedOverlays = currentOverlays.map((overlayNode, i) => {
         const entry = displayedOverlays[i];
@@ -34,7 +35,7 @@ export function CurrentScreen() {
             return modalNode;
         return React.createElement(ModalContext.Provider, { value: { id: entry.id, originComponent: entry.originComponent }, key: `mdl-ctx-${entry.id}` }, modalNode);
     });
-    return (React.createElement(Box, { flexDirection: 'column', width: '100%', height: '100%' },
+    return (React.createElement(Box, { flexDirection: 'column', width: '100%', height: fullScreen ? rows : '100%' },
         currentScreen,
         wrappedOverlays.map((w) => w),
         wrappedModals.map((w) => w)));

package/dist/screen/provider.d.ts

@@ -111,6 +111,7 @@ export interface ScenarioManagementProviderProps {
     defaultScreen: React.ComponentType<any>;
     /** 默认参数（可选，未传则使用注册时的模板参数） */
     defaultParams?: Record<string, unknown>;
+    fullScreen?: boolean;
 }
 /**
  * Screen-management context provider.
@@ -118,4 +119,4 @@ export interface ScenarioManagementProviderProps {
  * Wraps the application and enables tree-based screen navigation, overlays,
  * and module-level navigation functions.
  */
-export declare function ScenarioManagementProvider({ children, defaultScreen, defaultParams, }: ScenarioManagementProviderProps): React.JSX.Element;
+export declare function ScenarioManagementProvider({ children, defaultScreen, defaultParams, fullScreen }: ScenarioManagementProviderProps): React.JSX.Element;

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 };
@@ -481,7 +483,7 @@ function screenReducer(state, action) {
  * Wraps the application and enables tree-based screen navigation, overlays,
  * and module-level navigation functions.
  */
-export function ScenarioManagementProvider({ children, defaultScreen, defaultParams, }) {
+export function ScenarioManagementProvider({ children, defaultScreen, defaultParams, fullScreen }) {
     if (!hasComponent(defaultScreen)) {
         throw new Error(`[Ink-Cartridge] defaultScreen "${defaultScreen.displayName || defaultScreen.name || 'anonymous'}" is not registered. Please call registerComponent() first.`);
     }
@@ -612,6 +614,7 @@ export function ScenarioManagementProvider({ children, defaultScreen, defaultPar
         openModal: openModalInContext,
         closeModal: closeModalInContext,
         closeAllModals: closeAllModalsInContext,
+        fullScreen
     }), [
         currentScreen,
         currentOverlays,
@@ -634,6 +637,7 @@ export function ScenarioManagementProvider({ children, defaultScreen, defaultPar
         closeModalInContext,
         closeAllModalsInContext,
         state.activeModalId,
+        fullScreen
     ]);
     return (React.createElement(ScreenSystemContext.Provider, { value: value }, children));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ink-cartridge",
-    "version": "3.8.1",
+    "version": "3.8.3",
     "description": "Ready-to-use Ink components and screen management system for building terminal UIs.",
     "type": "module",
     "main": "./dist/index.js",
@@ -62,7 +62,7 @@
         "eslint": "^9.39.4",
         "eslint-plugin-react": "^7.37.5",
         "eslint-plugin-react-hooks": "^7.1.1",
-        "ink": "^7.0.1",
+        "ink": "^7.1.0",
         "ink-testing-library": "^4.0.0",
         "jsdom": "^26.0.0",
         "react": "^19.2.4",