ink-cartridge 3.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BAIGAO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# ink-cartridge
+
+> Ready-to-use Ink components and tools for building terminal UI applications.
+
+[![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+---
+
+## Getting Started
+
+### Quick Start (scaffold a new project)
+
+```bash
+npx ink-cartridge init my-tui
+cd my-tui
+npm start
+```
+
+### Install in existing project
+
+```bash
+npm install ink-cartridge
+```
+
+### Requirements
+
+| Dependency | Minimum Version |
+| ---------- | --------------- |
+| Node.js    | 22              |
+| ink        | 5               |
+| react      | 18              |
+
+---
+
+## Design Philosophy
+
+ink-cartridge aims to make **screen management** and **keyboard event handling** in Ink applications composable, maintainable, and type-safe.
+
+### Screen as Component
+
+In ink-cartridge, **every React component is a "screen"**. Register them into a **screen tree** via `registerComponent`, then navigate the tree with `skip` / `back` / `gotoScreen`. This design makes screen navigation predictable and eliminates the chaos of hand-written conditional rendering (`if-else` / `switch`).
+
+### Layered Keyboard Events
+
+No more global `useInput` cluttered with `if-else` chains. ink-cartridge's keyboard system maintains **per-screen-layer** key bindings. Events bubble from **top to bottom** through the stack, with four key mechanisms:
+
+- **Sequence (`boundSequence`)** — Multi-key chords (e.g. `gg`, `dd`, `cw`) with timeout and exclusive/non-exclusive modes. Sequences take priority over ordinary bindings.
+- **Blocked Key (`blockedKey`)** — Let a key pass through the current layer to be handled below
+- **Stop (`stop`)** — Prevent a key from propagating to lower layers. Supports `stopAction` mode to block by shortcut action ID instead of literal key name
+- **Global Key (`globalKeys`)** — Shortcuts independent of the screen stack
+
+#### Finer-grained partitioning
+
+Within the same level, identical keys are also in competition. To address this, we have a complete **focus system**.  
+Each level maintains a set of focus targets, and only one focus is active at any given time within a level. Each focus target has its own bound keyboard operations. Only the activated focus target is eligible to execute them during event dispatching in **useInput**.  
+
+**For more details, please refer to the API documentation.**
+
+### Shortcut Actions
+
+Decouple operation definition from key binding with `defineShortcutAction`. Register named operations once, then reference them by string ID in `boundKeyboard`, `globalKeys`, and `stop`:
+
+```tsx
+defineShortcutAction([
+  { actionId: 'quit', action: () => process.exit() },
+]);
+boundKeyboard(['q'], 'quit');
+globalKeys([{ key: 'escape', operate: 'quit' }]);
+stop(['quit'], { stopAction: true });
+```
+
+### Sequence Actions
+
+Decouple sequence operation definition from key binding with `defineSequenceAction`. Register named sequence operations once, then reference them by string ID in `globalSequence` and `boundSequence`:
+
+```tsx
+defineSequenceAction([
+  { sequenceActionId: 'save', action: () => saveFile(), keys: ['ctrl+s'] },
+]);
+
+// Global sequence referencing the action
+globalSequence([{ keys: ['ctrl+s'], operate: 'save' }]);
+
+// Screen-level sequence using the action's predefined keys
+boundSequence('save');
+
+// Modify an existing action's keys dynamically
+modifySequenceAction('save', ['ctrl+shift+s']);
+```
+
+### Overlay System
+
+`openOverlay()` and `closeOverlay()` provide floating dialogs on top of the screen stack. Combined with the keyboard system, overlays intercept keys before they reach the underlying screen — ideal for confirmation dialogs, modals, and pop-up menus.
+
+### Module-Level Functions
+
+Navigation functions (`skip`, `back`, `gotoScreen`, `openOverlay`, `closeOverlay`) work both inside React components (via hooks) and as **module-level imports** in any `.ts` / `.tsx` file. This allows non-UI layers — game engines, state managers, etc. — to trigger screen transitions.
+
+### Type Safety
+
+Every API provides full TypeScript type inference. Functions like `skip`, `gotoScreen`, and `openOverlay` automatically infer parameter types from your component's props, catching errors at compile time.
+
+---
+
+## ⚠️ Important: Component Nesting Order
+
+`KeyboardProvider` **must** be nested inside `ScenarioManagementProvider`, because it depends on the screen context to obtain the current screen stack.
+
+```tsx
+{/* ❌ Wrong: KeyboardProvider outside screen context */}
+<KeyboardProvider>
+  <ScenarioManagementProvider defaultScreen={Menu}>
+    ...
+  </ScenarioManagementProvider>
+</KeyboardProvider>
+
+{/* ✅ Correct: KeyboardProvider inside screen context */}
+<ScenarioManagementProvider defaultScreen={Menu}>
+  <KeyboardProvider>
+    ...
+  </KeyboardProvider>
+</ScenarioManagementProvider>
+```
+
+> The screen system can be used independently without `KeyboardProvider`; but the keyboard system requires the screen context.
+
+---
+
+## Documentation
+
+- **[Screen Management System](docs/screen.md)** — `registerComponent`, `ScenarioManagementProvider`, `CurrentScreen`, `useScreenSystem`, `skip` / `back` / `gotoScreen` / `openOverlay` / `closeOverlay`
+- **[Keyboard System](docs/keyboard.md)** — `KeyboardProvider`, `useKeyboard`, `boundKeyboard`, `boundSequence`, `blockedKey`, `stop`, `globalKeys`, `defineShortcutAction`, focus management
+- **[Internationalization](docs/language.md)** — `LanguageProvider`, `useI18n`, `t()` translation with interpolation, language switching, **`ink-cartridge makeLanguageType`** CLI for compile-time type-safe translation keys
+- **[Theme System](docs/theme.md)** — `ThemeProvider`, `useTheme`, There is also a companion type generator and theme profile generator
+- **[Persistence System](docs/storage.md)** — `createStorage`, typed key-value JSON storage with automatic type validation, atomic writes, and zero config
+- **[Binary Storage System](docs/binary-storage.md)** — `createBinaryStorage` for sequential typed binary streams with positional cursors, and `createStreamingReader` for memory-efficient streaming of large files (500 MB+) with backpressure support
+
+---
+
+## Components
+
+### Selection & Input
+- **[SelectInput](src/components/select/README.md)** — Single-select list with focus-aware keyboard navigation
+- **[MultiSelectInput](src/components/multi-select/README.md)** — Multi-select list with checkbox toggling (Space to toggle, Enter to submit)
+- **[TextInput](src/components/text/README.md)** — Text input with cursor, mask, and focus system integration
+- **[SearchInput](src/components/search-input/README.md)** — Search field with 🔍 icon and Esc-to-clear
+- **[NumberInput](src/components/number-input/README.md)** — Numeric stepper with min/max/step and keyboard controls
+
+### Display & Feedback
+- **[Spinner](src/components/spinner/README.md)** — Animated spinner with multiple preset styles
+- **[ProgressBar](src/components/progress-bar/README.md)** — Customizable progress bar with percentage display
+- **[Badge](src/components/badge/README.md)** — Colored label/tag component
+- **[KeyHint](src/components/key-hint/README.md)** — Keyboard shortcut hint bar (`[S] Save`)
+
+### Navigation
+- **[Tabs](src/components/tabs/README.md)** — Tabbed panel with keyboard navigation and focus system integration
+- **[Fold](src/components/fold/README.md)** — Collapsible panel with preview and Space-toggle, integrated with focus system
+
+### Layout
+- **[Divider](src/components/divider/README.md)** — Horizontal separator with optional centered label
+
+### Form
+- **[Form & Field](src/components/form/README.md)** — Context‑based form system with validation, error focus, and Ctrl+Enter submit
+
+### Dialog
+- **[ConfirmDialog](src/components/dialog/README.md)** — Modal confirmation dialog with two buttons, designed for the overlay system
+
+---
+
+## Quick Overview
+
+```tsx
+import React, { useEffect } from 'react';
+import { Box, Text, render } from 'ink';
+import {
+  registerComponent,
+  ScenarioManagementProvider,
+  CurrentScreen,
+  useScreenSystem,
+  KeyboardProvider,
+  useKeyboard,
+  ConfirmDialog,
+} from 'ink-cartridge';
+
+// ── Register screens ──
+function Menu() {
+  const { skip } = useScreenSystem();
+  const { boundKeyboard } = useKeyboard();
+  useEffect(() => {
+    boundKeyboard(['s'], () => skip(Game, { level: 1 }));
+  }, []);
+  return (
+    <Box>
+      <Text>Main Menu — Press S to start</Text>
+    </Box>
+  );
+}
+registerComponent(Menu, {});
+
+function Game({ level }: { level: number }) {
+  const { back } = useScreenSystem();
+  const { boundKeyboard } = useKeyboard();
+  useEffect(() => {
+    boundKeyboard(['b'], () => back());
+  }, []);
+  return (
+    <Box>
+      <Text>Level {level} — Press B to go back</Text>
+    </Box>
+  );
+}
+registerComponent(Game, { level: 1 }, { parent: Menu });
+
+// Register the dialog so it can be used with openOverlay()
+registerComponent(ConfirmDialog, {
+  title: '', message: '', onConfirm: () => {}, onCancel: () => {},
+});
+
+// ── Wire up ──
+function App() {
+  return (
+    <KeyboardProvider>
+      <CurrentScreen />
+    </KeyboardProvider>
+  );
+}
+
+render(
+  <ScenarioManagementProvider defaultScreen={Menu}>
+    <App />
+  </ScenarioManagementProvider>,
+);
+```
+
+---
+
+
+## Other
+
+I admit I thought about some things too quickly at the beginning of the project.
+For example, the method of **blockedKeys**. Why is it called that? I don't know. Maybe I didn't think about it at that time.
+Actually, it should be called **penetration**, but I don't want to change it.
+
+## License
+
+[MIT](LICENSE)

package/dist/binary-storage/BinaryStorage.d.ts

@@ -0,0 +1,308 @@
+import type { BinaryStorageOptions, BinaryStorageAPI } from './types.js';
+/**
+ * Sequential binary key-value store backed by a single file.
+ *
+ * ## Architecture
+ *
+ * The entire file is loaded into a single in-memory `Buffer` on
+ * construction (lazy — only if the file already exists). Two
+ * cursors track the current position:
+ *
+ * - `readPos`  — where the next `read.*()` will start reading.
+ *   Starts at 0. Advanced each time a value is consumed.
+ *
+ * - `writePos` — where the next `write.*()` will append data.
+ *   Starts at the file size (or 0 for a new file). Advanced
+ *   each time a value is written.
+ *
+ * Because both cursors point into the same Buffer, you can write
+ * values, then immediately read them back by resetting the read
+ * cursor — no disk round-trip needed.
+ *
+ * ## Write path
+ *
+ * 1. `write.num(v)` calls `enqueue(() => appendNum(v))`.
+ * 2. `enqueue` chains the task onto the internal `pending` promise
+ *    so writes are strictly ordered.
+ * 3. `appendNum` calls `growBuf()` to ensure capacity, writes
+ *    `[TypeTag.Number][8-byte float64 LE]` at `writePos`, then
+ *    advances `writePos`.
+ * 4. If `flush: true` (default), `forceFlush()` writes the buffer
+ *    to disk atomically (temp file → rename).
+ *
+ * ## Read path
+ *
+ * 1. `read.num()` calls `readTyped(TypeTag.Number, ...)`.
+ * 2. `readTyped` calls `readTag()` which checks `readPos < writePos`
+ *    (end-of-stream guard) and returns the byte at `readPos`.
+ * 3. If the tag matches `TypeTag.Number`, `readPos` advances past
+ *    the tag and the payload reader (`readNumPayload`) is invoked.
+ * 4. `readNumPayload` reads 8 bytes at `readPos` as float64 LE,
+ *    advances `readPos`, and returns the number.
+ *
+ * ## Concurrency model
+ *
+ * Writes are serialised through a promise chain (`this.pending`).
+ * The chain uses `.then(task, task)` — the second argument means
+ * that even if one write task rejects, subsequent writes still run.
+ * Reads do NOT go through the queue because they are synchronous
+ * operations on the in-memory buffer (the `async` wrapper is for
+ * API consistency only).
+ *
+ * ## Atomicity guarantee
+ *
+ * Flush uses the same temp-file-then-rename pattern as the JSON
+ * {@link Storage}: write to `file.bin.tmp`, then `fs.renameSync`.
+ * On POSIX systems, `rename` is atomic — the on-disk file is
+ * always either the complete old version or the complete new
+ * version. A crash mid-write leaves the original file intact.
+ *
+ * ## Buffer growth strategy
+ *
+ * {@link growBuf} doubles the buffer capacity when it runs out
+ * of space, with a minimum increment of {@link GROW_STEP} (4 KiB).
+ * This means writing 10,000 small values allocates ~20 times
+ * instead of 10,000 times — a classic amortised-O(1) approach.
+ */
+export declare class BinaryStorage implements BinaryStorageAPI {
+    /** Resolved configuration with defaults applied. */
+    private options;
+    /** Absolute path to the backing file. */
+    private filePath;
+    /**
+     * In-memory copy of the file. Growable — always
+     * `buffer.length >= writePos`. Only the first `writePos`
+     * bytes are meaningful; the rest is pre-allocated capacity.
+     */
+    private buffer;
+    /** Next byte to read from. Always `0 <= readPos <= writePos`. */
+    private readPos;
+    /** Next byte to write to. Equal to total valid data size. */
+    private writePos;
+    /**
+     * Promise chain for serialising writes. Each write task
+     * is attached via `.then(task, task)` so the chain never
+     * breaks even if a task rejects.
+     */
+    private pending;
+    /**
+     * @param options  Optional configuration. Instances should be
+     *                 created via {@link createBinaryStorage}.
+     */
+    constructor(options?: BinaryStorageOptions);
+    /**
+     * Typed write methods.
+     *
+     * Each method enqueues the write task so that concurrent
+     * callers never interleave. The task:
+     * 1. Ensures buffer capacity via `growBuf`.
+     * 2. Writes the type tag + payload at `writePos`.
+     * 3. Advances `writePos`.
+     * 4. Flushes if `options.flush` is true.
+     */
+    write: {
+        num: (value: number) => Promise<void>;
+        str: (value: string) => Promise<void>;
+        b: (value: boolean) => Promise<void>;
+        obj: <T extends object>(v: T) => Promise<void>;
+        arr: <T>(v: T[]) => Promise<void>;
+        any: (value: unknown) => Promise<void>;
+        null: () => Promise<void>;
+        /** Force-persist regardless of the `flush` option. */
+        flush: () => Promise<void>;
+    };
+    /**
+     * Typed read methods.
+     *
+     * Each method delegates to `readTyped()` which validates the
+     * type tag, then calls the type-specific payload reader.
+     * Wrapped in `async` so that errors thrown synchronously
+     * (e.g. type mismatch) become Promise rejections.
+     */
+    read: {
+        num: () => Promise<number>;
+        str: () => Promise<string>;
+        b: () => Promise<boolean>;
+        obj: <T extends object>() => Promise<T>;
+        arr: <T>() => Promise<T[]>;
+        any: () => Promise<unknown>;
+    };
+    tellRead(): number;
+    tellWrite(): number;
+    seekRead(pos: number): void;
+    /**
+     * Truncate the stream at `pos` and persist.
+     *
+     * Because this mutates the buffer, it goes through the write
+     * queue to avoid racing with in-flight writes. If the read
+     * cursor would end up past the new write position, it is
+     * clamped back.
+     */
+    seekWrite(pos: number): Promise<void>;
+    resetRead(): void;
+    /** Convenience: discard everything after the read cursor. */
+    truncate(): Promise<void>;
+    private ensureDir;
+    /**
+     * Read the file into a Buffer. Returns an empty buffer if the
+     * file does not exist (first use) or can't be read.
+     */
+    private loadFile;
+    /**
+     * Serialise access so concurrent callers never interleave.
+     *
+     * Each task is chained onto `this.pending` using
+     * `.then(task, task)`. The second `task` argument is critical:
+     * it means that if a previous task rejects, the next task
+     * still executes. Without it, a single failed write would
+     * permanently break the chain and all subsequent writes
+     * would hang.
+     */
+    private enqueue;
+    /**
+     * Conditional flush — only persists if `options.flush` is true.
+     *
+     * Called automatically after every write when `flush: true`.
+     * When `flush: false`, writes are buffered in memory until
+     * {@link forceFlush} is called (via `write.flush()`).
+     */
+    private flush;
+    /**
+     * Unconditional flush — always writes to disk.
+     *
+     * Only the first `writePos` bytes are written; the rest of the
+     * buffer is pre-allocated capacity. Uses atomic rename to
+     * prevent corruption from partial writes or crashes.
+     */
+    private forceFlush;
+    /**
+     * Ensure the internal Buffer has at least `needed` free bytes
+     * after `writePos`.
+     *
+     * Growth strategy: allocate `max(needed, GROW_STEP)` extra bytes,
+     * copy the old buffer into the new one. This is amortised O(1)
+     * per byte written — the classic dynamic-array approach.
+     */
+    private growBuf;
+    /**
+     * Encode a number: `[0x01][8 bytes float64 LE]`.
+     *
+     * Uses `writeDoubleLE` which writes IEEE 754 binary64 format.
+     * This preserves all JS numbers faithfully, including special
+     * values like `Infinity`, `-Infinity`, and `NaN`.
+     */
+    private appendNum;
+    /**
+     * Encode a string: `[0x02][4 bytes uint32 LE length][UTF-8 bytes]`.
+     *
+     * The length is the byte count of the UTF-8 encoding, not the
+     * character count. This ensures multi-byte characters (emoji,
+     * CJK) are handled correctly.
+     */
+    private appendStr;
+    /**
+     * Encode a boolean: `[0x03][1 byte: 0x00 or 0x01]`.
+     */
+    private appendBool;
+    /**
+     * Encode an object as JSON: `[0x04][4 bytes length][JSON UTF-8]`.
+     *
+     * Objects and arrays use the same wire format (length-prefixed
+     * UTF-8 string) but different type tags so that `read.obj()`
+     * and `read.arr()` can validate the expected shape.
+     */
+    private appendObj;
+    /**
+     * Encode an array as JSON: `[0x05][4 bytes length][JSON UTF-8]`.
+     */
+    private appendArr;
+    /**
+     * Auto-detect the type of `value` and delegate to the
+     * appropriate typed append method.
+     *
+     * Detection order:
+     * 1. `typeof` for number/string/boolean → typed tags
+     * 2. `null` / `undefined` → TypeTag.Null
+     * 3. `Array.isArray` → TypeTag.Array
+     * 4. `typeof === 'object'` → TypeTag.Object
+     * 5. Fallback → TypeTag.Null (shouldn't happen, but safe)
+     */
+    private appendAny;
+    /**
+     * Encode null: `[0x06]` — just the tag, no payload.
+     */
+    private appendNull;
+    /**
+     * Peek at the type tag byte at `readPos`.
+     *
+     * This is the end-of-stream guard for all typed read methods.
+     * It checks against `writePos` (not `buffer.length`) because
+     * the buffer may have pre-allocated capacity beyond the valid
+     * data region.
+     *
+     * @returns The tag byte (0x01–0x06).
+     * @throws If `readPos >= writePos` (no more values to read).
+     */
+    private readTag;
+    /**
+     * Read a uint32 LE length prefix from `readPos` and advance.
+     *
+     * @returns The length value.
+     * @throws If there aren't enough bytes for the length prefix.
+     */
+    private readUInt32LE;
+    /**
+     * Core typed-read routine.
+     *
+     * 1. Peek at the tag byte.
+     * 2. If it doesn't match `expected`, throw a descriptive error
+     *    with the byte position and human-readable type names.
+     * 3. Otherwise advance past the tag and invoke the payload
+     *    reader callback.
+     *
+     * @typeParam T — The return type of the payload reader.
+     * @param expected    — The TypeTag we expect to find.
+     * @param readPayload — Callback that reads the payload bytes
+     *                      and returns the decoded value.
+     */
+    private readTyped;
+    /**
+     * Read 8 bytes as a float64 LE number.
+     *
+     * Uses `readDoubleLE` which decodes IEEE 754 binary64.
+     * `Infinity`, `-Infinity`, and `NaN` round-trip correctly.
+     */
+    private readNumPayload;
+    /**
+     * Read a length-prefixed UTF-8 string.
+     *
+     * 1. Read 4-byte uint32 LE → byte length.
+     * 2. Read that many bytes as UTF-8.
+     */
+    private readStrPayload;
+    /**
+     * Read a single byte as a boolean.
+     *
+     * Any non-zero byte is treated as `true`.
+     */
+    private readBoolPayload;
+    /**
+     * Read a string payload and parse it as JSON.
+     *
+     * Shared by `read.obj()` and `read.arr()` — the type tag
+     * distinguishes the two, but the on-wire format is identical
+     * (JSON string).
+     */
+    private readJSONPayload;
+    /**
+     * Read the next value regardless of type.
+     *
+     * Reads the tag byte, then dispatches to the appropriate
+     * payload reader. This is the universal read method — it
+     * accepts any type and returns the decoded value directly.
+     *
+     * @throws If the tag byte is unknown (file corruption or
+     *         newer format version).
+     */
+    private readAnyPayload;
+}