ink-cartridge 3.6.1

package/dist/components/text/types.js

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

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

@@ -0,0 +1,36 @@
+import React from "react";
+import { DevProps } from "./types.js";
+/**
+ * Developer debugging modal for the ink-cartridge screen system.
+ *
+ * Renders as an absolutely-positioned panel showing real-time navigation
+ * state: the current screen path as a breadcrumb, a list of open overlays
+ * (green = active, gray = inactive), open modals, screen count, and the
+ * panel's vertical offset.
+ *
+ * Keyboard controls (bound on mount):
+ * - **↑ / ↓** — move the panel vertically, clamped to the terminal bounds.
+ *   The position automatically re-clamps on terminal resize so the panel
+ *   never drifts off-screen.
+ * - **Escape** — close the DevScreen modal.
+ *
+ * Must be opened via {@link openDevTool} (which calls `openModal`).
+ * 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
+ * and screens while open.
+ *
+ * @param top   - Initial vertical position in rows (0 = top of terminal).
+ * @param left  - Horizontal position in columns.
+ *
+ * @example
+ * ```ts
+ * // Open from any screen or keyboard handler:
+ * import { openDevTool } from 'ink-cartridge/dev';
+ * openDevTool({ top: 0, left: 0 });
+ * ```
+ *
+ * @2026-06-23 3.6.1
+ */
+export declare function DevScreen({ top: initialTop, left }: DevProps): React.JSX.Element;

package/dist/dev/dev-screen.js

@@ -0,0 +1,142 @@
+import React, { useCallback, useContext, useEffect, useRef, useState } from "react";
+import { Box, Text, useWindowSize } from "ink";
+import { useScreenSystem } from "../screen/hook.js";
+import { useKeyboard, useModalMissListener } from "../keyboard/hook.js";
+import { ModalContext } from "../screen/ModalContext.js";
+import { registerComponent } from "../screen/registry.js";
+import { closeDevTool } from "./entrance.js";
+const PANEL_HEIGHT = 30;
+/**
+ * Developer debugging modal for the ink-cartridge screen system.
+ *
+ * Renders as an absolutely-positioned panel showing real-time navigation
+ * state: the current screen path as a breadcrumb, a list of open overlays
+ * (green = active, gray = inactive), open modals, screen count, and the
+ * panel's vertical offset.
+ *
+ * Keyboard controls (bound on mount):
+ * - **↑ / ↓** — move the panel vertically, clamped to the terminal bounds.
+ *   The position automatically re-clamps on terminal resize so the panel
+ *   never drifts off-screen.
+ * - **Escape** — close the DevScreen modal.
+ *
+ * Must be opened via {@link openDevTool} (which calls `openModal`).
+ * 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
+ * and screens while open.
+ *
+ * @param top   - Initial vertical position in rows (0 = top of terminal).
+ * @param left  - Horizontal position in columns.
+ *
+ * @example
+ * ```ts
+ * // Open from any screen or keyboard handler:
+ * import { openDevTool } from 'ink-cartridge/dev';
+ * openDevTool({ top: 0, left: 0 });
+ * ```
+ *
+ * @2026-06-23 3.6.1
+ */
+export function DevScreen({ top: initialTop, left }) {
+    const { currentPath, displayedOverlays, activeOverlayIds, modalQueue, activeModalId, } = useScreenSystem();
+    const { boundKeyboard } = useKeyboard();
+    const modalId = useContext(ModalContext);
+    const { rows } = useWindowSize();
+    const [offsetTop, setOffsetTop] = useState(initialTop);
+    const [flashBorder, setFlashBorder] = useState(false);
+    const flashTimerRef = useRef(null);
+    // Stable ref so the []-deps keyboard effect always reads the latest
+    // rows-based clamp, preventing a stale-closure on the initial size.
+    const clampTopRef = useRef((next) => next);
+    clampTopRef.current = (next) => Math.max(0, Math.min(next, rows - PANEL_HEIGHT));
+    useModalMissListener(useCallback((evt) => {
+        if (evt.miss) {
+            setFlashBorder(true);
+            if (flashTimerRef.current)
+                clearTimeout(flashTimerRef.current);
+            flashTimerRef.current = setTimeout(() => {
+                setFlashBorder(false);
+                flashTimerRef.current = null;
+            }, 200);
+        }
+    }, []));
+    // Cleanup flash timer on unmount
+    useEffect(() => {
+        return () => {
+            if (flashTimerRef.current)
+                clearTimeout(flashTimerRef.current);
+        };
+    }, []);
+    useEffect(() => {
+        const u1 = boundKeyboard(['up'], () => setOffsetTop(prev => clampTopRef.current(prev - 1)));
+        const u2 = boundKeyboard(['down'], () => setOffsetTop(prev => clampTopRef.current(prev + 1)));
+        const u3 = boundKeyboard(['escape'], () => {
+            if (modalId)
+                closeDevTool();
+        });
+        return () => {
+            u1();
+            u2();
+            u3();
+        };
+    }, [modalId]);
+    // When the terminal is resized the current position may land outside
+    // the new bounds — re-clamp so the panel stays visible immediately.
+    useEffect(() => {
+        setOffsetTop(prev => clampTopRef.current(prev));
+    }, [rows]);
+    return (React.createElement(Box, { borderColor: flashBorder ? 'yellow' : 'blue', borderStyle: 'round', position: "absolute", top: offsetTop, left: left, height: PANEL_HEIGHT, width: '100%', flexDirection: "column", paddingX: 1, paddingY: 1, backgroundColor: 'black' },
+        React.createElement(Box, { flexDirection: "row" },
+            React.createElement(Text, { color: "cyan", bold: true }, "Path "),
+            currentPath.map((component, index) => {
+                const name = component.displayName || component.name || 'Unknown';
+                const isLast = index === currentPath.length - 1;
+                return (React.createElement(Box, { key: index, flexDirection: "row" },
+                    React.createElement(Text, { color: "gray" },
+                        " ",
+                        '>',
+                        " "),
+                    React.createElement(Text, { color: isLast ? 'yellow' : 'gray', bold: isLast }, name)));
+            })),
+        React.createElement(Box, { flexDirection: "row", paddingTop: 1 },
+            React.createElement(Text, { color: "cyan" }, "Overlays "),
+            React.createElement(Text, { dimColor: true },
+                "(",
+                displayedOverlays.length,
+                ")"),
+            displayedOverlays.length === 0 ? (React.createElement(Text, { color: "gray" }, " \u2014 none")) : (displayedOverlays.map((entry, i) => {
+                const name = entry.component.displayName || entry.component.name || 'Unknown';
+                const active = activeOverlayIds.includes(entry.id);
+                return (React.createElement(Box, { key: entry.id, flexDirection: "row" },
+                    React.createElement(Text, { color: "gray" }, i > 0 ? ', ' : ' — '),
+                    React.createElement(Text, { color: active ? 'green' : 'gray' }, name)));
+            }))),
+        React.createElement(Box, { flexDirection: "row", paddingTop: 0 },
+            React.createElement(Text, { color: "cyan" }, "Modals "),
+            React.createElement(Text, { dimColor: true },
+                "(",
+                modalQueue.length,
+                ")"),
+            modalQueue.length === 0 ? (React.createElement(Text, { color: "gray" }, " \u2014 none")) : (modalQueue.map((entry, i) => {
+                const name = entry.component.displayName || entry.component.name || 'Unknown';
+                const active = entry.id === activeModalId;
+                return (React.createElement(Box, { key: entry.id, flexDirection: "row" },
+                    React.createElement(Text, { color: "gray" }, i > 0 ? ', ' : ' — '),
+                    React.createElement(Text, { color: active ? 'green' : 'gray' }, name)));
+            }))),
+        React.createElement(Box, { width: '100%', paddingY: 1 },
+            React.createElement(Text, { color: "blue", dimColor: true }, "─".repeat(60))),
+        React.createElement(Box, { flexDirection: "column" },
+            React.createElement(Text, { dimColor: true },
+                "Screens: ",
+                currentPath.length,
+                "  |  \u2191\u2193 Move  |  Esc Close"),
+            React.createElement(Text, { dimColor: true },
+                "Top: ",
+                offsetTop,
+                "/",
+                rows - PANEL_HEIGHT))));
+}
+registerComponent(DevScreen, { top: 0, left: 0 });

package/dist/dev/entrance.d.ts

@@ -0,0 +1,51 @@
+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).
+ *
+ * When open, DevScreen blocks all keyboard events from reaching
+ * overlays and screens. The modal provides its own close mechanism
+ * via the Escape key.
+ *
+ * @param top  - Initial vertical position in rows (0 = top of terminal).
+ * @param left - Horizontal position in columns.
+ *
+ * @throws If `ScenarioManagementProvider` is not mounted, or the modal
+ *         ID `_Dev-Tool_` is already open.
+ *
+ * @example
+ * ```ts
+ * // Toggle with a ref to avoid duplicate-open errors:
+ * const devOpenRef = useRef(false);
+ * boundKeyboard(['ctrl+d'], () => {
+ *   if (devOpenRef.current) {
+ *     closeDevTool();
+ *     devOpenRef.current = false;
+ *   } else {
+ *     openDevTool({ top: 0, left: 0 });
+ *     devOpenRef.current = true;
+ *   }
+ * });
+ * ```
+ */
+export declare function openDevTool({ top, left, zindex }: DevProps & {
+    zindex?: number;
+}): 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.
+ *
+ * @example
+ * ```ts
+ * boundKeyboard(['escape'], () => closeDevTool());
+ * ```
+ */
+export declare function closeDevTool(): void;

package/dist/dev/entrance.js

@@ -0,0 +1,67 @@
+import { closeModal, openModal } from "../screen/provider.js";
+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).
+ *
+ * When open, DevScreen blocks all keyboard events from reaching
+ * overlays and screens. The modal provides its own close mechanism
+ * via the Escape key.
+ *
+ * @param top  - Initial vertical position in rows (0 = top of terminal).
+ * @param left - Horizontal position in columns.
+ *
+ * @throws If `ScenarioManagementProvider` is not mounted, or the modal
+ *         ID `_Dev-Tool_` is already open.
+ *
+ * @example
+ * ```ts
+ * // Toggle with a ref to avoid duplicate-open errors:
+ * const devOpenRef = useRef(false);
+ * boundKeyboard(['ctrl+d'], () => {
+ *   if (devOpenRef.current) {
+ *     closeDevTool();
+ *     devOpenRef.current = false;
+ *   } else {
+ *     openDevTool({ top: 0, left: 0 });
+ *     devOpenRef.current = true;
+ *   }
+ * });
+ * ```
+ */
+export function openDevTool({ top, left, zindex }) {
+    openModal('_Dev-Tool_', DevScreen, {
+        top: top,
+        left: left
+    }, {
+        zIndex: zindex,
+        renderNow: true
+    });
+}
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * boundKeyboard(['escape'], () => closeDevTool());
+ * ```
+ */
+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.
+    }
+}

package/dist/dev/globalKey-display.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export default function GlobalKeyDisplayBox(): React.JSX.Element;

package/dist/dev/globalKey-display.js

@@ -0,0 +1,8 @@
+import { Box } from "ink";
+import React from "react";
+// This modal box is used to display information about all registered global keys.
+// Because it is a modal box, its keyboard is independent and will not be affected by DevTool.
+// Also make sure that the zindex is greater than the zindex of the DevTool so that the visual effects and keyboard reception are applied correctly when the modal box is opened
+export default function GlobalKeyDisplayBox() {
+    return (React.createElement(Box, { position: "absolute" }));
+}

package/dist/dev/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Props accepted by the {@link DevScreen} debugging overlay.
+ */
+export interface DevProps {
+    /** Vertical position in rows — 0 is the top of the terminal. */
+    top: number;
+    /** Horizontal position in columns — 0 is the left edge. */
+    left: number;
+}

package/dist/dev/types.js

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

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+export { registerComponent, ScenarioManagementProvider, CurrentScreen, skip, back, gotoScreen, openOverlay, closeOverlay, closeAllOverlays, activateOverlay, deactivateOverlay, openModal, closeModal, closeAllModals, useScreenSystem, ModalContext, } from "./screen/index.js";
+export type { SkipOptions, SkipFn, BackFn, GotoScreenFn, OpenOverlayFn, CloseOverlayFn, CloseAllOverlaysFn, ActivateOverlayFn, DeactivateOverlayFn, OpenModalFn, CloseModalFn, CloseAllModalsFn, OpenOverlayOptions, OpenModalOptions, OverlayEntry, ModalEntry, RegisterOptions, ScenarioManagementProviderProps, } from "./screen/index.js";
+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, StopOptions, FocusTarget, SequenceOptions, ShortcutOperationEntry, SequenceOperationEntry, ModalMissEvent, ModalMissCallback, ModalMissOptions, ResolvedGlobalKeyEntry, } from "./keyboard/index.js";
+export { useFocusState } from "./keyboard/index.js";
+export { SelectInput } from "./components/select/SelectInput.js";
+export type { Item } from "./components/select/types.js";
+export type { SelectInputProps } from "./components/select/types.js";
+export { MultiSelectInput } from "./components/multi-select/MultiSelectInput.js";
+export type { MultiSelectInputProps } from "./components/multi-select/types.js";
+export { TextInput, UncontrolledTextInput } from "./components/text/TextInput.js";
+export type { TextInputProps, UncontrolledTextInputProps } from "./components/text/types.js";
+export { ConfirmDialog } from "./components/dialog/ConfirmDialog.js";
+export type { ConfirmDialogProps } from "./components/dialog/types.js";
+export { Spinner } from "./components/spinner/Spinner.js";
+export type { SpinnerType } from "./components/spinner/Spinner.js";
+export { ProgressBar } from "./components/progress-bar/ProgressBar.js";
+export { Divider } from "./components/divider/Divider.js";
+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 { Tabs } from "./components/tabs/Tabs.js";
+export type { Tab, TabsProps } from "./components/tabs/types.js";
+export { Fold } from "./components/fold/Fold.js";
+export type { FoldProps } from "./components/fold/types.js";
+export { Form } from "./components/form/Form.js";
+export { Field } from "./components/form/Field.js";
+export { useFormContext } from "./components/form/context.js";
+export type { FormProps, FieldProps, FieldRenderProps, FormContextValue, Validator, } from "./components/form/types.js";
+export { LanguageProvider } from "./language/index.js";
+export { useI18n } from "./language/index.js";
+export type { LanguageProviderProps, I18nContextValue } from "./language/index.js";
+export { ThemeProvider } from "./theme/index.js";
+export { useTheme } from "./theme/index.js";
+export type { ThemeProviderProps, ThemeContextValue, ThemeDefinition } from "./theme/index.js";
+export { createStorage } from "./storage/index.js";
+export type { StorageOptions, StorageAPI } from "./storage/index.js";
+export { createBinaryStorage, TypeTag, TAG_NAMES } from "./binary-storage/index.js";
+export type { BinaryStorageOptions, BinaryStorageAPI } from "./binary-storage/index.js";
+export { createStreamingReader, StreamCorruptError } from "./binary-storage/StreamingReader.js";
+export type { StreamingReaderOptions, StreamingReaderAPI } from "./binary-storage/StreamingReader.js";
+export { openDevTool, closeDevTool } from "./dev/entrance.js";
+export type { DevProps } from "./dev/types.js";

package/dist/index.js

@@ -0,0 +1,50 @@
+// ── Screen System ──────────────────────────────────────────
+export { registerComponent, ScenarioManagementProvider, CurrentScreen, skip, back, gotoScreen, openOverlay, closeOverlay, closeAllOverlays, activateOverlay, deactivateOverlay, openModal, closeModal, closeAllModals, useScreenSystem, ModalContext, } from "./screen/index.js";
+// ── Keyboard System ────────────────────────────────────────
+export { KeyboardProvider, useKeyboard } from "./keyboard/index.js";
+export { normalizeKeyNames, isNormalCharacter } from "./keyboard/index.js";
+export { useFocusState } from "./keyboard/index.js";
+// Components — SelectInput
+export { SelectInput } from "./components/select/SelectInput.js";
+// Components — MultiSelectInput
+export { MultiSelectInput } from "./components/multi-select/MultiSelectInput.js";
+// Components — TextInput
+export { TextInput, UncontrolledTextInput } from "./components/text/TextInput.js";
+// Components — Dialog
+export { ConfirmDialog } from "./components/dialog/ConfirmDialog.js";
+// Components — Spinner
+export { Spinner } from "./components/spinner/Spinner.js";
+// Components — ProgressBar
+export { ProgressBar } from "./components/progress-bar/ProgressBar.js";
+// Components — Divider
+export { Divider } from "./components/divider/Divider.js";
+// Components — Badge
+export { Badge } from "./components/badge/Badge.js";
+// Components — KeyHint
+export { KeyHint } from "./components/key-hint/KeyHint.js";
+// Components — NumberInput
+export { NumberInput } from "./components/number-input/NumberInput.js";
+// Components — SearchInput
+export { SearchInput } from "./components/search-input/SearchInput.js";
+// Components — Tabs
+export { Tabs } from "./components/tabs/Tabs.js";
+// Components — Fold
+export { Fold } from "./components/fold/Fold.js";
+// Components — Form
+export { Form } from "./components/form/Form.js";
+export { Field } from "./components/form/Field.js";
+export { useFormContext } from "./components/form/context.js";
+// I18n — Language
+export { LanguageProvider } from "./language/index.js";
+export { useI18n } from "./language/index.js";
+// Theme System
+export { ThemeProvider } from "./theme/index.js";
+export { useTheme } from "./theme/index.js";
+// Persistence System
+export { createStorage } from "./storage/index.js";
+// Binary Persistence System
+export { createBinaryStorage, TAG_NAMES } from "./binary-storage/index.js";
+// Binary Streaming Reader
+export { createStreamingReader, StreamCorruptError } from "./binary-storage/StreamingReader.js";
+// Dev Tool
+export { openDevTool, closeDevTool } from "./dev/entrance.js";

package/dist/keyboard/check-global-key.d.ts

@@ -0,0 +1,18 @@
+import type React from 'react';
+import type { LayerOwner } from './context.js';
+import type { GlobalKeyEntry, ScreenKeyboardLayer } from './types.js';
+/**
+ * Check whether a global key entry should fire for the current event.
+ *
+ * Evaluates key-name matching, category whitelist, and screen-level
+ * global-key override (cover mechanism).
+ *
+ * @param entry        The global key entry to evaluate.
+ * @param eventNames   Normalized key names from the current event.
+ * @param topComponent The topmost screen component, or null if no screen is active.
+ * @param layersRef    Mutable ref to all keyboard layers.
+ * @returns true if the global key matches and is not overridden.
+ *
+ * @2026-06-14 v3.4.0
+ */
+export declare function checkGlobalKey(entry: GlobalKeyEntry, eventNames: string[], topComponent: React.ComponentType<any> | null, layersRef: React.MutableRefObject<Map<LayerOwner, ScreenKeyboardLayer>>): boolean;

package/dist/keyboard/check-global-key.js

@@ -0,0 +1,52 @@
+/**
+ * Check whether a global key entry should fire for the current event.
+ *
+ * Evaluates key-name matching, category whitelist, and screen-level
+ * global-key override (cover mechanism).
+ *
+ * @param entry        The global key entry to evaluate.
+ * @param eventNames   Normalized key names from the current event.
+ * @param topComponent The topmost screen component, or null if no screen is active.
+ * @param layersRef    Mutable ref to all keyboard layers.
+ * @returns true if the global key matches and is not overridden.
+ *
+ * @2026-06-14 v3.4.0
+ */
+export function checkGlobalKey(entry, eventNames, topComponent, layersRef) {
+    const keyNames = Array.isArray(entry.key) ? entry.key : [entry.key];
+    if (!keyNames.some((k) => eventNames.includes(k)))
+        return false;
+    if (!topComponent)
+        return false;
+    const cat = entry.category;
+    if (cat === undefined || cat === '*') {
+    }
+    else if (Array.isArray(cat) && cat.length === 0) {
+        return false;
+    }
+    else if (Array.isArray(cat)) {
+        if (!cat.includes(topComponent))
+            return false;
+    }
+    const topLayer = layersRef.current.get(topComponent);
+    // Global Key rules (affectOverlay + cover)
+    //
+    // When an Overlay is active:
+    // - [true,  true] : Affects Overlay, can be overridden only by Overlay
+    // - [true,  false]: Affects Overlay, cannot be overridden by anyone
+    // - [false, true] : Does NOT affect Overlay; works on Screen Stack, can be overridden by Screen Stack
+    // - [false, false]: Does NOT affect Overlay; works on Screen Stack, cannot be overridden by Screen Stack
+    //
+    // When NO Overlay is active (default):
+    // - affectOverlay = true  → Key becomes inactive
+    // - affectOverlay = false → Key remains active on Screen Stack (override rules as above)
+    //
+    // Option executeWhenNoOverlay (only if affectOverlay = true):
+    // Keeps the key active on Screen Stack even without an Overlay, while preserving the original cover rule.
+    // @2026-06-11 v3.3.0
+    if (topLayer && !entry.affectOverlay && (entry.cover ?? true)) {
+        if (keyNames.some((k) => topLayer.globalKeyOverrides.has(k)))
+            return false;
+    }
+    return true;
+}