ink-cartridge 3.6.1

package/dist/screen/registry.d.ts

@@ -0,0 +1,27 @@
+import React from "react";
+import type { RegisterOptions } from "./types.js";
+/**
+ * Register a component as a screen in the navigation tree.
+ *
+ * @param component  The React component (used as the unique token).
+ * @param template   Default props for the component.
+ * @param options    Optional registration options (e.g. `parent` to attach
+ *                   the component under an existing node in the tree).
+ *
+ * @throws If the component has already been registered.
+ */
+export declare function registerComponent<C extends React.ComponentType<any>>(component: C, template: React.ComponentProps<C>, options?: RegisterOptions): void;
+/** 获取组件的模板参数 */
+export declare function getTemplate(component: React.ComponentType<any>): Record<string, unknown> | undefined;
+/** 获取组件的父节点 */
+export declare function getParent(component: React.ComponentType<any>): React.ComponentType<any> | null | undefined;
+/** 获取组件的子节点列表 */
+export declare function getChildren(component: React.ComponentType<any>): React.ComponentType<any>[];
+/** 检查组件是否已注册 */
+export declare function hasComponent(component: React.ComponentType<any>): boolean;
+/** 获取所有根节点（parent 为 null 的组件） */
+export declare function getRoots(): React.ComponentType<any>[];
+/** 判断 child 是否是 parent 的直接子节点 */
+export declare function isChildOf(child: React.ComponentType<any>, parent: React.ComponentType<any>): boolean;
+/** 清除所有注册（仅供测试使用） */
+export declare function clearRegistry(): void;

package/dist/screen/registry.js

@@ -0,0 +1,71 @@
+/** 模块级注册表：组件 → 注册信息 */
+const registry = new Map();
+/**
+ * Register a component as a screen in the navigation tree.
+ *
+ * @param component  The React component (used as the unique token).
+ * @param template   Default props for the component.
+ * @param options    Optional registration options (e.g. `parent` to attach
+ *                   the component under an existing node in the tree).
+ *
+ * @throws If the component has already been registered.
+ */
+export function registerComponent(component, template, options) {
+    if (registry.has(component)) {
+        throw new Error(`[Ink-Cartridge] Component "${component.displayName || component.name || "anonymous"}" is already registered. Duplicate registration is not allowed.`);
+    }
+    registry.set(component, {
+        template: template,
+        parent: options?.parent ?? null,
+        children: new Set(),
+    });
+    // 如果声明了父节点，将自己添加到父节点的 children 中
+    if (options?.parent) {
+        const parentEntry = registry.get(options.parent);
+        if (!parentEntry) {
+            const compName = component.displayName || component.name || "anonymous";
+            const parentName = options.parent.displayName ||
+                options.parent.name ||
+                "anonymous";
+            throw new Error(`[Ink-Cartridge] registerComponent("${compName}"): parent component "${parentName}" is not registered. ` +
+                `Register the parent first with registerComponent(${parentName}, template).`);
+        }
+        parentEntry.children.add(component);
+    }
+}
+/** 获取组件的模板参数 */
+export function getTemplate(component) {
+    return registry.get(component)?.template;
+}
+/** 获取组件的父节点 */
+export function getParent(component) {
+    return registry.get(component)?.parent;
+}
+/** 获取组件的子节点列表 */
+export function getChildren(component) {
+    const entry = registry.get(component);
+    return entry ? Array.from(entry.children) : [];
+}
+/** 检查组件是否已注册 */
+export function hasComponent(component) {
+    return registry.has(component);
+}
+/** 获取所有根节点（parent 为 null 的组件） */
+export function getRoots() {
+    const roots = [];
+    for (const [component, entry] of registry) {
+        if (entry.parent === null) {
+            roots.push(component);
+        }
+    }
+    return roots;
+}
+/** 判断 child 是否是 parent 的直接子节点 */
+export function isChildOf(child, parent) {
+    const entry = registry.get(child);
+    return entry?.parent === parent;
+}
+/** 清除所有注册（仅供测试使用） */
+export function clearRegistry() {
+    registry.clear();
+}

package/dist/screen/types.d.ts

@@ -0,0 +1,227 @@
+import React from 'react';
+export interface RegisterOptions {
+    /**
+     * The parent component in the navigation tree.
+     * If not provided, the component is considered a root candidate.
+     */
+    parent?: React.ComponentType<any>;
+}
+export interface SkipOptions {
+    /**
+     * When true, only the component's props are updated without remounting the component.
+     * This is useful for performance or when preserving internal state.
+     */
+    onlyAttribute?: boolean;
+}
+/**
+ * Options for {@link openOverlay}.
+ */
+export interface OpenOverlayOptions {
+    /** Whether to activate the overlay immediately. Defaults to true. */
+    activate?: boolean;
+    /** Visual stacking order. Smaller values render behind larger values. */
+    zIndex?: number;
+}
+/**
+ * Options for {@link openModal}.
+ */
+export interface OpenModalOptions {
+    /** Visual stacking order. Smaller values render behind larger values. Defaults to the current modal count. */
+    zIndex?: number;
+    /** Whether to render the modal even when it is not the active modal (zIndex not highest). Defaults to false. */
+    renderNow?: boolean;
+}
+/**
+ * A single overlay entry in the multi-overlay system.
+ */
+export interface OverlayEntry {
+    /** Unique identifier for this overlay. */
+    id: string;
+    /** The overlay component to render. */
+    component: React.ComponentType<any>;
+    /** Props passed to the overlay component. */
+    props: Record<string, unknown>;
+    /** Visual stacking order (lower = behind, higher = front). */
+    zIndex: number;
+    /** Timestamp for tie-breaking when zIndex values are equal. */
+    createdAt: number;
+}
+/**
+ * A single modal entry in the modal system.
+ *
+ * Modals are architecturally symmetric to overlays but with absolute
+ * keyboard priority: the modal with the highest zIndex is the single
+ * active modal and consumes all keyboard events.
+ */
+export interface ModalEntry {
+    /** Unique identifier for this modal. */
+    id: string;
+    /** The modal component to render. */
+    component: React.ComponentType<any>;
+    /** Props passed to the modal component. */
+    props: Record<string, unknown>;
+    /** Visual stacking order (lower = behind, higher = front). Also determines activation order. */
+    zIndex: number;
+    /** Timestamp for tie-breaking when zIndex values are equal. */
+    createdAt: number;
+    /** Whether to render even when not the active modal. Defaults to false. */
+    renderNow: boolean;
+}
+/**
+ * Internal state of the screen management provider.
+ */
+export interface ScreenState {
+    /** The full navigation path from the root component to the current screen. */
+    path: React.ComponentType<any>[];
+    /** Parameters for each component along the path, in the same order. */
+    pathParams: Record<string, unknown>[];
+    /** All open overlays, sorted by zIndex (ascending). */
+    overlays: OverlayEntry[];
+    /** Set of overlay IDs that are currently active (receiving keyboard events). */
+    activeOverlayIds: Set<string>;
+    /** All open modals, sorted by zIndex (ascending). */
+    modals: ModalEntry[];
+    /** ID of the currently active modal (zIndex highest), or null if none. */
+    activeModalId: string | null;
+    /** Auto-incrementing counter used as a React key to force remounts when needed. */
+    counter: number;
+}
+/** Discriminated union type discriminator. */
+export type ScreenActionType = 'skip' | 'back' | 'gotoScreen' | 'openOverlay' | 'closeOverlay' | 'closeAllOverlays' | 'activateOverlay' | 'deactivateOverlay' | 'openModal' | 'closeModal' | 'closeAllModals';
+/** Action dispatched when navigating down to a child screen. */
+export interface SkipAction {
+    type: 'skip';
+    /** The target component to navigate to. */
+    component: React.ComponentType<any>;
+    /** Props to merge with the component's registered template. */
+    params: Record<string, unknown>;
+    /** Whether to only update props without remounting. */
+    onlyAttribute: boolean;
+}
+/** Action dispatched when navigating back to the parent screen. */
+export interface BackAction {
+    type: 'back';
+    /** Number of levels to go back. Defaults to 1. */
+    levels?: number;
+}
+/** Action dispatched when jumping to any registered screen across branches. */
+export interface GotoScreenAction {
+    type: 'gotoScreen';
+    /** The target component to navigate to. */
+    component: React.ComponentType<any>;
+    /** Props to merge with the component's registered template. */
+    params: Record<string, unknown>;
+}
+/** Action dispatched when opening a new overlay. */
+export interface OpenOverlayAction {
+    type: 'openOverlay';
+    /** Unique identifier for this overlay. */
+    id: string;
+    /** The overlay component to render. */
+    component: React.ComponentType<any>;
+    /** Props to pass to the overlay component. */
+    params: Record<string, unknown>;
+    /** Whether to activate the overlay immediately. */
+    activate: boolean;
+    /** Optional zIndex for visual stacking. */
+    zIndex?: number;
+}
+/** Action dispatched when closing a specific overlay by ID. */
+export interface CloseOverlayAction {
+    type: 'closeOverlay';
+    /** The ID of the overlay to close. */
+    id: string;
+}
+/** Action dispatched when closing all overlays. */
+export interface CloseAllOverlaysAction {
+    type: 'closeAllOverlays';
+}
+/** Action dispatched when activating an overlay by ID. */
+export interface ActivateOverlayAction {
+    type: 'activateOverlay';
+    /** The ID of the overlay to activate. */
+    id: string;
+}
+/** Action dispatched when deactivating an overlay by ID. */
+export interface DeactivateOverlayAction {
+    type: 'deactivateOverlay';
+    /** The ID of the overlay to deactivate. */
+    id: string;
+}
+/** Action dispatched when opening a new modal. */
+export interface OpenModalAction {
+    type: 'openModal';
+    /** Unique identifier for this modal. */
+    id: string;
+    /** The modal component to render. */
+    component: React.ComponentType<any>;
+    /** Props to pass to the modal component. */
+    params: Record<string, unknown>;
+    /** Optional zIndex for visual stacking and activation order. */
+    zIndex?: number;
+    /** Whether to render even when not active. Defaults to false. */
+    renderNow?: boolean;
+}
+/** Action dispatched when closing a specific modal by ID. */
+export interface CloseModalAction {
+    type: 'closeModal';
+    /** The ID of the modal to close. */
+    id: string;
+}
+/** Action dispatched when closing all modals. */
+export interface CloseAllModalsAction {
+    type: 'closeAllModals';
+}
+/** Union of all possible screen actions. */
+export type ScreenAction = SkipAction | BackAction | GotoScreenAction | OpenOverlayAction | CloseOverlayAction | CloseAllOverlaysAction | ActivateOverlayAction | DeactivateOverlayAction | OpenModalAction | CloseModalAction | CloseAllModalsAction;
+/**
+ * Function signature for navigating to a direct child of the current screen.
+ *
+ * @typeParam C - The component type (must be a React component).
+ * @param component - The child component (must be registered and a direct child).
+ * @param params - Props to pass to the component.
+ * @param options - Optional navigation flags.
+ */
+export type SkipFn = <C extends React.ComponentType<any>>(component: C, params: React.ComponentProps<C>, options?: SkipOptions) => void;
+/** Function signature for navigating back to the parent screen. */
+export type BackFn = (levels?: number) => void;
+/**
+ * Function signature for jumping to any registered screen across branches.
+ *
+ * @typeParam C - The target component type.
+ * @param component - The target component (must be registered).
+ * @param params - Props to pass to the component.
+ */
+export type GotoScreenFn = <C extends React.ComponentType<any>>(component: C, params: React.ComponentProps<C>) => void;
+/**
+ * Function signature for opening a new overlay.
+ *
+ * @typeParam C - The overlay component type.
+ * @param id - Unique identifier for this overlay.
+ * @param component - The overlay component (must be registered).
+ * @param params - Props to pass to the overlay.
+ * @param options - Optional activation and zIndex settings.
+ */
+export type OpenOverlayFn = <C extends React.ComponentType<any>>(id: string, component: C, params: React.ComponentProps<C>, options?: OpenOverlayOptions) => void;
+/** Function signature for closing a specific overlay by ID. */
+export type CloseOverlayFn = (id: string) => void;
+/** Function signature for closing all overlays. */
+export type CloseAllOverlaysFn = () => void;
+/** Function signature for activating an overlay by ID. */
+export type ActivateOverlayFn = (id: string) => void;
+/** Function signature for deactivating an overlay by ID. */
+export type DeactivateOverlayFn = (id: string) => void;
+/**
+ * Function signature for opening a new modal.
+ *
+ * @typeParam C - The modal component type.
+ * @param id - Unique identifier for this modal.
+ * @param component - The modal component (must be registered).
+ * @param params - Props to pass to the modal.
+ * @param options - Optional zIndex and renderNow settings.
+ */
+export type OpenModalFn = <C extends React.ComponentType<any>>(id: string, component: C, params: React.ComponentProps<C>, options?: OpenModalOptions) => void;
+/** Function signature for closing a specific modal by ID. */
+export type CloseModalFn = (id: string) => void;
+/** Function signature for closing all modals. */
+export type CloseAllModalsFn = () => void;

package/dist/screen/types.js

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

package/dist/storage/index.d.ts

@@ -0,0 +1,45 @@
+import type { StorageOptions, StorageAPI } from './types.js';
+/**
+ * Create a key-value storage station backed by a JSON file.
+ *
+ * The returned {@link StorageAPI} provides typed `read.*` and `write.*`
+ * methods that validate types at runtime and automatically repair
+ * mismatches by writing the default value back to disk. All operations
+ * are serialised internally — concurrent callers never interleave.
+ *
+ * @param options  Optional configuration for the storage directory,
+ *                 file name, and flush behaviour.
+ * @returns A typed storage API. Each instance is independent;
+ *          you can create as many stations as you need.
+ *
+ * @example
+ * ```ts
+ * // Default storage station (./data/config.json)
+ * const config = createStorage();
+ *
+ * // Custom station for game saves
+ * const saves = createStorage({ dir: './saves', file: 'slot1.json' });
+ *
+ * // Write typed values
+ * await config.write.str('username', 'Alice');
+ * await config.write.num('volume', 80);
+ * await config.write.obj('window', { width: 120, height: 40 });
+ *
+ * // Read with defaults (auto-repairs on mismatch)
+ * const name = await config.read.str('username', 'Guest');
+ * const vol  = await config.read.num('volume', 50);
+ * const win  = await config.read.obj('window', { width: 80, height: 24 });
+ *
+ * // Key management
+ * if (await config.has('username')) { ... }
+ * await config.delete('temp-key');
+ * await config.clear();
+ * const all = await config.getAll();
+ * ```
+ *
+ * @throws Never throws during construction. Read/write errors from
+ *         the filesystem (permissions, disk full) propagate to the
+ *         caller as standard Node.js `ErrnoException` objects.
+ */
+export declare function createStorage(options?: StorageOptions): StorageAPI;
+export type { StorageOptions, StorageAPI };

package/dist/storage/index.js

@@ -0,0 +1,46 @@
+import { Storage } from './storage.js';
+/**
+ * Create a key-value storage station backed by a JSON file.
+ *
+ * The returned {@link StorageAPI} provides typed `read.*` and `write.*`
+ * methods that validate types at runtime and automatically repair
+ * mismatches by writing the default value back to disk. All operations
+ * are serialised internally — concurrent callers never interleave.
+ *
+ * @param options  Optional configuration for the storage directory,
+ *                 file name, and flush behaviour.
+ * @returns A typed storage API. Each instance is independent;
+ *          you can create as many stations as you need.
+ *
+ * @example
+ * ```ts
+ * // Default storage station (./data/config.json)
+ * const config = createStorage();
+ *
+ * // Custom station for game saves
+ * const saves = createStorage({ dir: './saves', file: 'slot1.json' });
+ *
+ * // Write typed values
+ * await config.write.str('username', 'Alice');
+ * await config.write.num('volume', 80);
+ * await config.write.obj('window', { width: 120, height: 40 });
+ *
+ * // Read with defaults (auto-repairs on mismatch)
+ * const name = await config.read.str('username', 'Guest');
+ * const vol  = await config.read.num('volume', 50);
+ * const win  = await config.read.obj('window', { width: 80, height: 24 });
+ *
+ * // Key management
+ * if (await config.has('username')) { ... }
+ * await config.delete('temp-key');
+ * await config.clear();
+ * const all = await config.getAll();
+ * ```
+ *
+ * @throws Never throws during construction. Read/write errors from
+ *         the filesystem (permissions, disk full) propagate to the
+ *         caller as standard Node.js `ErrnoException` objects.
+ */
+export function createStorage(options) {
+    return new Storage(options);
+}

package/dist/storage/storage.d.ts

@@ -0,0 +1,139 @@
+import type { ZodType } from 'zod';
+import type { StorageOptions, StorageAPI } from './types.js';
+/**
+ * A key-value storage station backed by a single JSON file.
+ *
+ * Each instance manages one JSON file on disk. All read/write operations
+ * are asynchronous and serialised internally — concurrent callers never
+ * interleave. The file is loaded lazily on the first access, and writes
+ * use atomic rename (write to `.tmp` then rename) to prevent data
+ * corruption from partial writes or crashes.
+ *
+ * Instances are created via {@link createStorage}, not directly.
+ */
+export declare class Storage implements StorageAPI {
+    private options;
+    private data;
+    private pending;
+    private filePath;
+    constructor(options?: StorageOptions);
+    /**
+     * Typed write methods.
+     *
+     * Each method writes a value of the corresponding type to the given key.
+     * The write is serialised: it waits for any pending writes to complete,
+     * then atomically persists the updated JSON to disk.
+     *
+     * `any` is the untyped escape hatch — it accepts any value and performs
+     * no type-checking on subsequent reads unless you use a typed read method.
+     */
+    write: {
+        /** Persist a numeric value under `key`. */
+        num: (key: string, value: number) => Promise<void>;
+        /** Persist a string value under `key`. */
+        str: (key: string, value: string) => Promise<void>;
+        /** Persist a boolean value under `key`. */
+        b: (key: string, value: boolean) => Promise<void>;
+        /** Persist a plain object under `key`. */
+        obj: <T extends object>(key: string, value: T) => Promise<void>;
+        /** Persist an array under `key`. */
+        arr: <T>(key: string, value: T[]) => Promise<void>;
+        /** Persist any value under `key`. No type constraint. */
+        any: (key: string, value: unknown) => Promise<void>;
+        /** Persist any value under `key`. Symmetric alias for `any`. */
+        schema: <T>(key: string, value: T) => Promise<void>;
+    };
+    /**
+     * Typed read methods.
+     *
+     * Each method reads the value at `key` and validates that it matches the
+     * expected type. If the key is missing or the stored value has a different
+     * type, `defaultValue` is returned **and the file is repaired** so that
+     * subsequent reads hit the correct value.
+     */
+    read: {
+        /** Read a number. Returns `defaultValue` if missing or wrong type. */
+        num: (key: string, defaultValue: number) => Promise<number>;
+        /** Read a string. Returns `defaultValue` if missing or wrong type. */
+        str: (key: string, defaultValue: string) => Promise<string>;
+        /** Read a boolean. Returns `defaultValue` if missing or wrong type. */
+        b: (key: string, defaultValue: boolean) => Promise<boolean>;
+        /** Read a plain object (generic). Returns `defaultValue` if missing or wrong type. */
+        obj: <T extends object>(key: string, defaultValue: T) => Promise<T>;
+        /** Read an array (generic). Returns `defaultValue` if missing or wrong type. */
+        arr: <T>(key: string, defaultValue: T[]) => Promise<T[]>;
+        /** Read any value. Returns `defaultValue` if missing. No type validation. */
+        any: <T>(key: string, defaultValue: T) => Promise<T>;
+        /** Read a value validated against a zod schema. Auto-repairs on parse failure. */
+        schema: <T>(key: string, schema: ZodType<T>, defaultValue: T) => Promise<T>;
+    };
+    /**
+     * Check whether a key exists in the store.
+     *
+     * @returns `true` if the key has an entry (even if its value is `null`
+     *          or `undefined` — it checks own-property presence).
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Remove a key and its value from the store.
+     *
+     * If the key does not exist this is a no-op (no error thrown).
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Remove all keys from the store, resetting it to an empty object.
+     */
+    clear(): Promise<void>;
+    /**
+     * Return a shallow copy of the entire raw data object.
+     *
+     * Modifications to the returned object do **not** affect the store
+     * (use the write methods to persist changes).
+     */
+    getAll(): Promise<Record<string, unknown>>;
+    private ensureDir;
+    /**
+     * Serialise access so concurrent callers never interleave.
+     *
+     * Each task is chained onto `this.pending` using `.then(task, task)`.
+     * The second argument ensures that even if a previous task rejects,
+     * the next task still runs (the chain is never broken).
+     */
+    private enqueue;
+    private setValue;
+    /**
+     * Read a value with type validation and automatic repair.
+     *
+     * If the key is missing the default is written to disk so that
+     * subsequent reads return it directly. If the stored value has a
+     * different type than expected, the default replaces it on disk.
+     */
+    private getValue;
+    /**
+     * Read a value and validate it against a zod schema.
+     *
+     * On success the parsed value is returned (including any transforms
+     * or coercions the schema applies). On failure — missing key or
+     * schema parse error — `defaultValue` is written to disk and returned.
+     */
+    private getValueWithSchema;
+    /**
+     * Load data from disk on first access (lazy initialisation).
+     *
+     * Once loaded the data stays in memory for the lifetime of the
+     * instance. File-not-found and corrupt-JSON errors are silently
+     * swallowed — in both cases we start with an empty store.
+     */
+    private ensureLoaded;
+    /**
+     * Atomically persist the in-memory data to disk.
+     *
+     * Writes to a `.tmp` file first, then renames it over the target
+     * file. This guarantees that the on-disk file is always either the
+     * complete previous version or the complete new version — never a
+     * partially-written mess.
+     *
+     * No-op when `options.flush` is `false`.
+     */
+    private flush;
+}