ink-cartridge 3.8.0 → 3.8.1

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)
@@ -161,4 +170,4 @@ The method `blockedKey` is poorly named — it means *pass-through*, not "block.
 
 ## 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

@@ -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

@@ -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

@@ -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);

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/keyboard/context.d.ts

@@ -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.

package/dist/keyboard/hook.js

@@ -1,7 +1,8 @@
-import { useContext, useEffect, useState } from "react";
+import { useContext, useEffect, useRef, useState } from "react";
 import { KeyboardContext } from "./context.js";
 import { OverlayContext } from "../screen/OverlayContext.js";
 import { ModalContext } from "../screen/ModalContext.js";
+import { useScreenSystem } from "../screen/hook.js";
 /**
  * Access the keyboard API from within a React component.
  *
@@ -23,41 +24,78 @@ import { ModalContext } from "../screen/ModalContext.js";
  */
 export function useKeyboard() {
     const ctx = useContext(KeyboardContext);
-    const overlayId = useContext(OverlayContext);
-    const modalId = useContext(ModalContext);
+    const overlayCtx = useContext(OverlayContext);
+    const modalCtx = useContext(ModalContext);
+    const overlayId = overlayCtx?.id ?? null;
+    const modalId = modalCtx?.id ?? null;
+    const { currentPath } = useScreenSystem();
     if (!ctx) {
         throw new Error("[Ink-Cartridge] useKeyboard() must be called inside a <KeyboardProvider>.");
     }
-    // Manage the owner stack for overlay isolation.
-    // When inside an overlay, push the overlay ID as the current owner so
-    // that boundKeyboard, blockedKey, stop, and focus functions operate on
-    // the overlay's own keyboard layer instead of the screen's layer.
-    //
-    // Destructuring _pushOwner / _popOwner to local variables gives ESLint a
-    // simple identifier to include in the dependency array (avoiding the need
-    // to list `ctx` as a whole, which would broaden the effect trigger).
     const { _pushOwner, _popOwner } = ctx;
+    const ownerPushedRef = useRef(false);
+    // Lifecycle: overlay mount → push, unmount → pop.
     useEffect(() => {
         if (overlayId) {
-            _pushOwner(overlayId);
+            if (!ownerPushedRef.current) {
+                _pushOwner(overlayId);
+                ownerPushedRef.current = true;
+            }
             return () => {
                 _popOwner(overlayId);
+                ownerPushedRef.current = false;
             };
         }
         return;
     }, [overlayId, _pushOwner, _popOwner]);
-    // Manage the owner stack for modal isolation (symmetric to overlay).
-    // When inside a modal, push the modal ID as the current owner so that
-    // keyboard functions operate on the modal's own layer.
+    // Lifecycle: modal mount → push, unmount → pop.
     useEffect(() => {
         if (modalId) {
-            _pushOwner(modalId);
+            if (!ownerPushedRef.current) {
+                _pushOwner(modalId);
+                ownerPushedRef.current = true;
+            }
             return () => {
                 _popOwner(modalId);
+                ownerPushedRef.current = false;
             };
         }
         return;
     }, [modalId, _pushOwner, _popOwner]);
+    /**
+     * Render-time owner stack sync for persistent layers.
+     *
+     * When a persistent overlay/modal survives navigation but the user has
+     * navigated to a different screen, the owner must be popped from the
+     * stack IMMEDIATELY (during render) so that sibling screen components'
+     * mount effects see the correct owner when they call boundKeyboard.
+     * Re-push happens when the user navigates back to the origin screen.
+     *
+     * This replaces the previous useEffect-based management which was
+     * subject to sibling ordering: screen components' effects fire before
+     * the persisting layer's effect, causing bindings to leak into the
+     * wrong keyboard layer.
+     *
+     * @2026-07-04 v3.8.0
+     */
+    const ownerCtx = modalCtx ?? overlayCtx;
+    const ownerId = ownerCtx?.id ?? null;
+    const originComponent = ownerCtx?.originComponent;
+    if (originComponent && ownerId) {
+        const currentTop = currentPath[currentPath.length - 1];
+        if (currentTop === originComponent) {
+            if (!ownerPushedRef.current) {
+                _pushOwner(ownerId);
+                ownerPushedRef.current = true;
+            }
+        }
+        else {
+            if (ownerPushedRef.current) {
+                _popOwner(ownerId);
+                ownerPushedRef.current = false;
+            }
+        }
+    }
     return ctx;
 }
 /**
@@ -99,7 +137,8 @@ export function useFocusState(focusId) {
  */
 export function useModalMissListener(cb, options) {
     const ctx = useContext(KeyboardContext);
-    const modalId = useContext(ModalContext);
+    const modalCtx = useContext(ModalContext);
+    const modalId = modalCtx?.id ?? null;
     useEffect(() => {
         if (!ctx || !modalId)
             return;

package/dist/screen/ModalContext.d.ts

@@ -1,6 +1,10 @@
 /**
- * Context that provides the modal ID when rendering inside
- * a modal component. Null when rendering a regular screen.
+ * Context that provides the modal ID and origin component when rendering
+ * inside a modal component. Null when rendering a regular screen.
+ *
+ * The {@link originComponent} field is set only for persistent modals —
+ * it tracks which screen opened the modal and enables automatic keyboard
+ * layer push/pop as the user navigates between screens.
  *
  * Used by the keyboard system to isolate per-modal keyboard layers
  * by modal ID instead of component type (enabling multiple instances
@@ -8,4 +12,9 @@
  *
  * Architecturally symmetric to {@link OverlayContext}.
  */
-export declare const ModalContext: import("react").Context<string | null>;
+export declare const ModalContext: import("react").Context<{
+    /** Unique modal identifier. */
+    id: string;
+    /** Screen that opened this modal (set only when persistent). */
+    originComponent?: React.ComponentType<any>;
+} | null>;

package/dist/screen/ModalContext.js

@@ -1,7 +1,11 @@
 import { createContext } from 'react';
 /**
- * Context that provides the modal ID when rendering inside
- * a modal component. Null when rendering a regular screen.
+ * Context that provides the modal ID and origin component when rendering
+ * inside a modal component. Null when rendering a regular screen.
+ *
+ * The {@link originComponent} field is set only for persistent modals —
+ * it tracks which screen opened the modal and enables automatic keyboard
+ * layer push/pop as the user navigates between screens.
  *
  * Used by the keyboard system to isolate per-modal keyboard layers
  * by modal ID instead of component type (enabling multiple instances

package/dist/screen/OverlayContext.d.ts

@@ -1,9 +1,20 @@
 /**
- * Context that provides the overlay ID when rendering inside
- * an overlay component. Null when rendering a regular screen.
+ * Context that provides the overlay ID and origin component when rendering
+ * inside an overlay component. Null when rendering a regular screen.
+ *
+ * The {@link originComponent} field is set only for persistent overlays —
+ * it tracks which screen opened the overlay and enables automatic keyboard
+ * layer push/pop as the user navigates between screens.
  *
  * Used by the keyboard system to isolate per-overlay keyboard layers
  * by overlay ID instead of component type (enabling multiple instances
  * of the same component as different overlays).
+ *
+ * Architecturally symmetric to {@link ModalContext}.
  */
-export declare const OverlayContext: import("react").Context<string | null>;
+export declare const OverlayContext: import("react").Context<{
+    /** Unique overlay identifier. */
+    id: string;
+    /** Screen that opened this overlay (set only when persistent). */
+    originComponent?: React.ComponentType<any>;
+} | null>;

package/dist/screen/OverlayContext.js

@@ -1,10 +1,16 @@
 import { createContext } from 'react';
 /**
- * Context that provides the overlay ID when rendering inside
- * an overlay component. Null when rendering a regular screen.
+ * Context that provides the overlay ID and origin component when rendering
+ * inside an overlay component. Null when rendering a regular screen.
+ *
+ * The {@link originComponent} field is set only for persistent overlays —
+ * it tracks which screen opened the overlay and enables automatic keyboard
+ * layer push/pop as the user navigates between screens.
  *
  * Used by the keyboard system to isolate per-overlay keyboard layers
  * by overlay ID instead of component type (enabling multiple instances
  * of the same component as different overlays).
+ *
+ * Architecturally symmetric to {@link ModalContext}.
  */
 export const OverlayContext = createContext(null);

package/dist/screen/current-screen.js

@@ -24,7 +24,7 @@ export function CurrentScreen() {
         const entry = displayedOverlays[i];
         if (!entry)
             return overlayNode;
-        return React.createElement(OverlayContext.Provider, { value: entry.id, key: `ovl-ctx-${entry.id}` }, overlayNode);
+        return React.createElement(OverlayContext.Provider, { value: { id: entry.id, originComponent: entry.originComponent }, key: `ovl-ctx-${entry.id}` }, overlayNode);
     });
     // Build modal elements with ModalContext wrappers (symmetric to overlays).
     // Uses renderedModalEntries (parallel to currentModals) for correct ID matching.
@@ -32,7 +32,10 @@ export function CurrentScreen() {
         const entry = renderedModalEntries[i];
         if (!entry)
             return modalNode;
-        return React.createElement(ModalContext.Provider, { value: entry.id, key: `mdl-ctx-${entry.id}` }, 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%' }, currentScreen, ...wrappedOverlays.map((w) => w), ...wrappedModals.map((w) => w));
+    return (React.createElement(Box, { flexDirection: 'column', width: '100%', height: '100%' },
+        currentScreen,
+        wrappedOverlays.map((w) => w),
+        wrappedModals.map((w) => w)));
 }

package/dist/screen/provider.d.ts

@@ -23,19 +23,23 @@ export declare function gotoScreen<C extends React.ComponentType<any>>(component
  * Open a floating overlay on top of the current screen stack.
  *
  * Multiple overlays can be open simultaneously, distinguished by unique IDs.
+ * Calling with an ID that already exists is a no-op — the existing overlay is
+ * left unchanged.
  *
  * @param id         Unique identifier for this overlay.
  * @param component  The overlay component (must be registered).
  * @param params     Props to pass to the overlay component.
  * @param options    Optional activation and zIndex settings.
  *
- * @throws If the provider is not mounted, the component is not registered,
- *         or the ID is already in use.
+ * @throws If the provider is not mounted or the component is not registered.
  */
 export declare function openOverlay<C extends React.ComponentType<any>>(id: string, component: C, params: React.ComponentProps<C>, options?: OpenOverlayOptions): void;
 /**
  * Close a specific overlay by its ID.
  *
+ * If no overlay with the given ID exists, this is a no-op — safe to call
+ * even when the overlay may have already been closed.
+ *
  * @param id  The ID of the overlay to close.
  *
  * @throws If the provider is not mounted.
@@ -70,13 +74,15 @@ export declare function deactivateOverlay(id: string): void;
  * The active modal receives absolute keyboard priority, consuming all
  * keyboard events before they reach overlays or screens.
  *
+ * Calling with an ID that already exists is a no-op — the existing modal
+ * is left unchanged. This supports simple toggle bindings without guard refs.
+ *
  * @param id         Unique identifier for this modal.
  * @param component  The modal component (must be registered).
  * @param params     Props to pass to the modal component.
  * @param options    Optional zIndex and renderNow settings.
  *
- * @throws If the provider is not mounted, the component is not registered,
- *         or the ID is already in use.
+ * @throws If the provider is not mounted or the component is not registered.
  */
 export declare function openModal<C extends React.ComponentType<any>>(id: string, component: C, params: React.ComponentProps<C>, options?: OpenModalOptions): void;
 /**
@@ -85,6 +91,9 @@ export declare function openModal<C extends React.ComponentType<any>>(id: string
  * When the active modal is closed, the modal with the next highest zIndex
  * automatically becomes active.
  *
+ * If no modal with the given ID exists, this is a no-op — safe to call
+ * even when the modal may have already been closed.
+ *
  * @param id  The ID of the modal to close.
  *
  * @throws If the provider is not mounted.

package/dist/screen/provider.js

@@ -80,14 +80,15 @@ export function gotoScreen(component, params) {
  * Open a floating overlay on top of the current screen stack.
  *
  * Multiple overlays can be open simultaneously, distinguished by unique IDs.
+ * Calling with an ID that already exists is a no-op — the existing overlay is
+ * left unchanged.
  *
  * @param id         Unique identifier for this overlay.
  * @param component  The overlay component (must be registered).
  * @param params     Props to pass to the overlay component.
  * @param options    Optional activation and zIndex settings.
  *
- * @throws If the provider is not mounted, the component is not registered,
- *         or the ID is already in use.
+ * @throws If the provider is not mounted or the component is not registered.
  */
 export function openOverlay(id, component, params, options) {
     if (!hasComponent(component)) {
@@ -100,11 +101,15 @@ export function openOverlay(id, component, params, options) {
         params: params,
         activate: options?.activate ?? true,
         zIndex: options?.zIndex,
+        persistent: options?.persistent,
     });
 }
 /**
  * Close a specific overlay by its ID.
  *
+ * If no overlay with the given ID exists, this is a no-op — safe to call
+ * even when the overlay may have already been closed.
+ *
  * @param id  The ID of the overlay to close.
  *
  * @throws If the provider is not mounted.
@@ -147,13 +152,15 @@ export function deactivateOverlay(id) {
  * The active modal receives absolute keyboard priority, consuming all
  * keyboard events before they reach overlays or screens.
  *
+ * Calling with an ID that already exists is a no-op — the existing modal
+ * is left unchanged. This supports simple toggle bindings without guard refs.
+ *
  * @param id         Unique identifier for this modal.
  * @param component  The modal component (must be registered).
  * @param params     Props to pass to the modal component.
  * @param options    Optional zIndex and renderNow settings.
  *
- * @throws If the provider is not mounted, the component is not registered,
- *         or the ID is already in use.
+ * @throws If the provider is not mounted or the component is not registered.
  */
 export function openModal(id, component, params, options) {
     if (!hasComponent(component)) {
@@ -165,7 +172,8 @@ export function openModal(id, component, params, options) {
         component,
         params: params,
         zIndex: options?.zIndex,
-        renderNow: options?.renderNow,
+        renderNow: options?.renderNow ?? false,
+        persistent: options?.persistent,
     });
 }
 /**
@@ -174,6 +182,9 @@ export function openModal(id, component, params, options) {
  * When the active modal is closed, the modal with the next highest zIndex
  * automatically becomes active.
  *
+ * If no modal with the given ID exists, this is a no-op — safe to call
+ * even when the modal may have already been closed.
+ *
  * @param id  The ID of the modal to close.
  *
  * @throws If the provider is not mounted.
@@ -223,6 +234,30 @@ function buildPathFrom(ancestor, target) {
     path.reverse();
     return path;
 }
+/**
+ * Rebuild active IDs for overlays and modals after navigation.
+ *
+ * Only persistent entries survive navigation. Among them, only those
+ * whose originComponent matches the current top-of-path screen are
+ * re-activated.
+ *
+ * @2026-07-04 v3.8.0
+ */
+function recalcActiveAfterNavigation(persistentOverlays, persistentModals, newTopScreen) {
+    const activeOverlayIds = new Set();
+    for (const o of persistentOverlays) {
+        if (o.originComponent === newTopScreen) {
+            activeOverlayIds.add(o.id);
+        }
+    }
+    let activeModalId = null;
+    for (const m of persistentModals) {
+        if (m.originComponent === newTopScreen) {
+            activeModalId = m.id;
+        }
+    }
+    return { activeOverlayIds, activeModalId };
+}
 /**
  * Pure reducer for {@link ScreenState}.
  *
@@ -230,7 +265,9 @@ function buildPathFrom(ancestor, target) {
  * (cross-branch), openOverlay, closeOverlay, closeAllOverlays,
  * activateOverlay, and deactivateOverlay.
  *
- * Navigation actions (skip / back / gotoScreen) clear all open overlays.
+ * Navigation actions filter out non-persistent overlays/modals and
+ * recalculate active IDs based on whether the origin screen of each
+ * persistent entry is at the top of the new path.
  */
 function screenReducer(state, action) {
     switch (action.type) {
@@ -245,13 +282,18 @@ function screenReducer(state, action) {
                 : state.counter + 1;
             const template = getTemplate(action.component) ?? {};
             const mergedParams = { ...template, ...action.params };
+            const newPath = [...state.path, action.component];
+            const persistentOverlays = state.overlays.filter(o => o.persistent);
+            const persistentModals = state.modals.filter(m => m.persistent);
+            const newTop = newPath[newPath.length - 1];
+            const { activeOverlayIds, activeModalId } = recalcActiveAfterNavigation(persistentOverlays, persistentModals, newTop);
             return {
-                path: [...state.path, action.component],
+                path: newPath,
                 pathParams: [...state.pathParams, mergedParams],
-                overlays: [],
-                activeOverlayIds: new Set(),
-                modals: [],
-                activeModalId: null,
+                overlays: persistentOverlays,
+                activeOverlayIds,
+                modals: persistentModals,
+                activeModalId,
                 counter,
             };
         }
@@ -262,13 +304,18 @@ function screenReducer(state, action) {
                     ? '[Ink-Cartridge] back() failed: already at the root node, cannot go back.'
                     : `[Ink-Cartridge] back(${levels}) failed: current depth is ${state.path.length}, cannot go back ${levels} levels.`);
             }
+            const newPath = state.path.slice(0, -levels);
+            const persistentOverlays = state.overlays.filter(o => o.persistent);
+            const persistentModals = state.modals.filter(m => m.persistent);
+            const newTop = newPath[newPath.length - 1];
+            const { activeOverlayIds, activeModalId } = recalcActiveAfterNavigation(persistentOverlays, persistentModals, newTop);
             return {
-                path: state.path.slice(0, -levels),
+                path: newPath,
                 pathParams: state.pathParams.slice(0, -levels),
-                overlays: [],
-                activeOverlayIds: new Set(),
-                modals: [],
-                activeModalId: null,
+                overlays: persistentOverlays,
+                activeOverlayIds,
+                modals: persistentModals,
+                activeModalId,
                 counter: state.counter + 1,
             };
         }
@@ -292,22 +339,26 @@ function screenReducer(state, action) {
                     return comp === action.component ? mergedParams : tpl;
                 }),
             ];
+            const persistentOverlays = state.overlays.filter(o => o.persistent);
+            const persistentModals = state.modals.filter(m => m.persistent);
+            const newTop = newPath[newPath.length - 1];
+            const { activeOverlayIds, activeModalId } = recalcActiveAfterNavigation(persistentOverlays, persistentModals, newTop);
             return {
                 path: newPath,
                 pathParams: newPathParams,
-                overlays: [],
-                activeOverlayIds: new Set(),
-                modals: [],
-                activeModalId: null,
+                overlays: persistentOverlays,
+                activeOverlayIds,
+                modals: persistentModals,
+                activeModalId,
                 counter: state.counter + 1,
             };
         }
         case 'openOverlay': {
             if (state.overlays.some(o => o.id === action.id)) {
-                throw new Error(`[Ink-Cartridge] Overlay with id "${action.id}" already exists. Use a unique id for each overlay.`);
+                return state;
             }
             if (state.modals.some(m => m.id === action.id)) {
-                throw new Error(`[Ink-Cartridge] Cannot open overlay "${action.id}": this ID is already in use by a modal. Use a unique id.`);
+                return state;
             }
             const newEntry = {
                 id: action.id,
@@ -315,6 +366,10 @@ function screenReducer(state, action) {
                 props: action.params,
                 zIndex: action.zIndex ?? state.overlays.length,
                 createdAt: Date.now(),
+                persistent: action.persistent,
+                originComponent: action.persistent
+                    ? state.path[state.path.length - 1]
+                    : undefined,
             };
             const newOverlays = sortOverlays([...state.overlays, newEntry]);
             const newActiveIds = new Set(state.activeOverlayIds);
@@ -329,7 +384,7 @@ function screenReducer(state, action) {
         }
         case 'closeOverlay': {
             if (!state.overlays.some(o => o.id === action.id)) {
-                throw new Error(`[Ink-Cartridge] Cannot close overlay "${action.id}": no overlay with that ID exists.`);
+                return state;
             }
             const newOverlays = state.overlays.filter(o => o.id !== action.id);
             const newActiveIds = new Set(state.activeOverlayIds);
@@ -371,10 +426,10 @@ function screenReducer(state, action) {
         }
         case 'openModal': {
             if (state.modals.some(m => m.id === action.id)) {
-                throw new Error(`[Ink-Cartridge] Modal with id "${action.id}" already exists. Use a unique id for each modal.`);
+                return state;
             }
             if (state.overlays.some(o => o.id === action.id)) {
-                throw new Error(`[Ink-Cartridge] Cannot open modal "${action.id}": this ID is already in use by an overlay. Use a unique id.`);
+                return state;
             }
             const newEntry = {
                 id: action.id,
@@ -383,6 +438,10 @@ function screenReducer(state, action) {
                 zIndex: action.zIndex ?? state.modals.length,
                 createdAt: Date.now(),
                 renderNow: action.renderNow ?? false,
+                persistent: action.persistent,
+                originComponent: action.persistent
+                    ? state.path[state.path.length - 1]
+                    : undefined,
             };
             const newModals = sortModals([...state.modals, newEntry]);
             // The last element (highest zIndex) is the active modal
@@ -395,7 +454,7 @@ function screenReducer(state, action) {
         }
         case 'closeModal': {
             if (!state.modals.some(m => m.id === action.id)) {
-                throw new Error(`[Ink-Cartridge] Cannot close modal "${action.id}": no modal with that ID exists.`);
+                return state;
             }
             const newModals = state.modals.filter(m => m.id !== action.id);
             const activeId = newModals.length > 0 ? newModals[newModals.length - 1].id : null;
@@ -502,6 +561,7 @@ export function ScenarioManagementProvider({ children, defaultScreen, defaultPar
             params: params,
             activate: options?.activate ?? true,
             zIndex: options?.zIndex,
+            persistent: options?.persistent,
         });
     }, []);
     const closeOverlayInContext = useMemo(() => (id) => dispatch({ type: 'closeOverlay', id }), []);
@@ -519,6 +579,7 @@ export function ScenarioManagementProvider({ children, defaultScreen, defaultPar
             params: params,
             zIndex: options?.zIndex,
             renderNow: options?.renderNow,
+            persistent: options?.persistent,
         });
     }, []);
     const closeModalInContext = useMemo(() => (id) => dispatch({ type: 'closeModal', id }), []);

package/dist/screen/types.d.ts

@@ -21,6 +21,8 @@ export interface OpenOverlayOptions {
     activate?: boolean;
     /** Visual stacking order. Smaller values render behind larger values. */
     zIndex?: number;
+    /** Whether this overlay survives screen navigation (skip/back/gotoScreen). */
+    persistent?: boolean;
 }
 /**
  * Options for {@link openModal}.
@@ -30,6 +32,8 @@ export interface OpenModalOptions {
     zIndex?: number;
     /** Whether to render the modal even when it is not the active modal (zIndex not highest). Defaults to false. */
     renderNow?: boolean;
+    /** Whether this modal survives screen navigation (skip/back/gotoScreen). */
+    persistent?: boolean;
 }
 /**
  * A single overlay entry in the multi-overlay system.
@@ -45,6 +49,15 @@ export interface OverlayEntry {
     zIndex: number;
     /** Timestamp for tie-breaking when zIndex values are equal. */
     createdAt: number;
+    /**
+     * When true, this overlay survives screen navigation (skip/back/gotoScreen).
+     * Non-persistent overlays are cleared on navigation. A persistent overlay
+     * is automatically re-activated when navigation returns to its originating
+     * screen and deactivated when navigating away.
+     */
+    persistent?: boolean;
+    /** When persistent, the screen component that opened this overlay — used to restore keyboard activation when returning to that screen. */
+    originComponent?: React.ComponentType<any>;
 }
 /**
  * A single modal entry in the modal system.
@@ -66,6 +79,15 @@ export interface ModalEntry {
     createdAt: number;
     /** Whether to render even when not the active modal. Defaults to false. */
     renderNow: boolean;
+    /**
+     * When true, this modal survives screen navigation (skip/back/gotoScreen).
+     * Non-persistent modals are cleared on navigation. A persistent modal is
+     * automatically re-activated when navigation returns to its originating
+     * screen and deactivated when navigating away.
+     */
+    persistent?: boolean;
+    /** When persistent, the screen component that opened this modal — used to restore activation when returning to that screen. */
+    originComponent?: React.ComponentType<any>;
 }
 /**
  * Internal state of the screen management provider.
@@ -125,6 +147,8 @@ export interface OpenOverlayAction {
     activate: boolean;
     /** Optional zIndex for visual stacking. */
     zIndex?: number;
+    /** Whether this overlay survives screen navigation. */
+    persistent?: boolean;
 }
 /** Action dispatched when closing a specific overlay by ID. */
 export interface CloseOverlayAction {
@@ -161,6 +185,8 @@ export interface OpenModalAction {
     zIndex?: number;
     /** Whether to render even when not active. Defaults to false. */
     renderNow?: boolean;
+    /** Whether this modal survives screen navigation. */
+    persistent?: boolean;
 }
 /** Action dispatched when closing a specific modal by ID. */
 export interface CloseModalAction {

package/package.json

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