@askdkc/dsh-cli 0.11.3

package/lib/types/components/design-system/ListItem.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useState } from 'react';
+import { Box, Text } from '../../ui.js';
+import { useDeclaredCursor } from '../../ink/hooks/use-declared-cursor.js';
+import { POINTER, DOWN_ARROW, UP_ARROW, TICK } from '../../terminal-utils/figures.js';
+/**
+ * A list item for selection UIs: `❯` marks the focused row, `✓`
+ * checkmark for the selected row, description on an indented second line,
+ * and its color states (focused = suggestion blue, selected = success
+ * green).
+ */
+export function ListItem({ isFocused, isSelected = false, children, description, showScrollDown, showScrollUp, styled = true, disabled = false, declareCursor, onClick, }) {
+    // Park the native terminal cursor on the pointer indicator so screen
+    // readers / magnifiers track the focused item. (0,0) is the
+    // top-left of this Box, where the pointer renders.
+    const cursorRef = useDeclaredCursor({
+        line: 0,
+        column: 0,
+        active: isFocused && !disabled && declareCursor !== false,
+    });
+    // Hover highlight only when the row is actually clickable — the extra
+    // background is the mouse affordance (there is no cursor-shape feedback
+    // in a terminal).
+    const [hovered, setHovered] = useState(false);
+    const clickable = Boolean(onClick) && !disabled;
+    function renderIndicator() {
+        if (disabled) {
+            return _jsx(Text, { children: " " });
+        }
+        if (isFocused) {
+            return _jsx(Text, { color: "suggestion", children: POINTER });
+        }
+        if (showScrollDown) {
+            return _jsx(Text, { dimColor: true, children: DOWN_ARROW });
+        }
+        if (showScrollUp) {
+            return _jsx(Text, { dimColor: true, children: UP_ARROW });
+        }
+        return _jsx(Text, { children: " " });
+    }
+    function getTextColor() {
+        if (disabled)
+            return 'inactive';
+        if (!styled)
+            return undefined;
+        if (isSelected)
+            return 'success';
+        if (isFocused)
+            return 'suggestion';
+        return undefined;
+    }
+    // 窗口化列表（ModelPicker/History/Rewind/Select）按固定行高切片：字符串
+    // 内容必须恒占一行——压平内嵌换行（历史命令可能带 \n），超宽 truncate
+    // 而非换行，否则一项实际占多行会把焦点行裁出浮层（二次审查实证）。
+    // 压平必须递归穿透 Fragment/数组：ThemePicker 的 label 就是包着用户
+    // displayName 的 Fragment，而 customTheme 允许 displayName 保留内部
+    // 换行（三轮审查实证：不递归则 Fragment 里的 'Foo\nBar' 仍渲染两行）。
+    // 非 Fragment 的 element（如调用方自己的 <Text>）保留原样——其子树高度
+    // 由调用方负责。
+    const flatChildren = flattenDeep(children);
+    return (_jsxs(Box, { ref: cursorRef, flexDirection: "column", onClick: clickable ? onClick : undefined, onMouseEnter: clickable ? () => setHovered(true) : undefined, onMouseLeave: clickable ? () => setHovered(false) : undefined, backgroundColor: clickable && hovered ? 'userMessageBackgroundHover' : undefined, children: [_jsxs(Box, { flexDirection: "row", gap: 1, height: 1, flexShrink: 0, overflow: "hidden", width: "100%", children: [renderIndicator(), styled ? (_jsx(Text, { color: getTextColor(), dimColor: disabled, wrap: "truncate-end", children: flatChildren })) : (flatChildren), isSelected && !disabled && _jsx(Text, { color: "success", children: TICK })] }), description && (_jsx(Box, { paddingLeft: 2, children: _jsx(Text, { color: "inactive", wrap: "truncate", children: flattenLine(description) }) }))] }));
+}
+/** 单行化：内嵌换行折叠为空格（行尾/行首换行随之消除）。 */
+function flattenLine(s) {
+    return s.replace(/[\r\n]+/g, ' ');
+}
+/**
+ * 递归单行化：字符串直接压平；数组逐元素递归；Fragment 是透明结构包装，
+ * 递归进其 children（保留 key/props）。其他 element 原样保留。
+ * 数组必须走 React.Children.map 而非原生 map：后者把静态 JSX children
+ * 变成无 key 的动态数组，/theme（label 含 Fragment）会稳定触发 React
+ * key warning（四次审查实证）。
+ */
+function flattenDeep(node) {
+    if (typeof node === 'string')
+        return flattenLine(node);
+    if (Array.isArray(node))
+        return React.Children.map(node, flattenDeep);
+    if (React.isValidElement(node) && node.type === React.Fragment) {
+        const frag = node;
+        return React.cloneElement(frag, undefined, flattenDeep(frag.props.children));
+    }
+    return node;
+}

package/lib/types/components/design-system/LoadingState.d.ts

@@ -0,0 +1,19 @@
+import React from 'react';
+/**
+ * A spinner with a loading message for async operations, using the small
+ * animated glyph.
+ *
+ * @example
+ * <LoadingState message="Loading models" bold subtitle="Querying the provider…" />
+ */
+export declare function LoadingState({ message, bold, dimColor, subtitle, }: {
+    /** The loading message to display next to the spinner. */
+    message: string;
+    /** Display the message in bold. @default false */
+    bold?: boolean;
+    /** Display the message in dimmed color. @default false */
+    dimColor?: boolean;
+    /** Optional subtitle displayed below the main message. */
+    subtitle?: string;
+}): React.ReactNode;
+//# sourceMappingURL=LoadingState.d.ts.map

package/lib/types/components/design-system/LoadingState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoadingState.d.ts","sourceRoot":"","sources":["../../../../src/components/design-system/LoadingState.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAYzB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAC3B,OAAO,EACP,IAAY,EACZ,QAAgB,EAChB,QAAQ,GACT,EAAE;IACD,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAA;IACf,kDAAkD;IAClD,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,KAAK,CAAC,SAAS,CAelB"}

package/lib/types/components/design-system/LoadingState.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import Box from '../../ink/components/Box.js';
+import Text from './ThemedText.js';
+import { useAnimationFrame } from '../../ink/hooks/use-animation-frame.js';
+import { SpinnerGlyph } from '../Spinner/SpinnerGlyph.js';
+import { getDefaultCharacters } from '../Spinner/spinnerUtils.js';
+const SPINNER_FRAMES = [
+    ...getDefaultCharacters(),
+    ...[...getDefaultCharacters()].reverse(),
+];
+/**
+ * A spinner with a loading message for async operations, using the small
+ * animated glyph.
+ *
+ * @example
+ * <LoadingState message="Loading models" bold subtitle="Querying the provider…" />
+ */
+export function LoadingState({ message, bold = false, dimColor = false, subtitle, }) {
+    const [ref, time] = useAnimationFrame(80);
+    const frame = Math.floor(time / 80) % SPINNER_FRAMES.length;
+    return (_jsxs(Box, { ref: ref, flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsx(SpinnerGlyph, { frame: frame, messageColor: "text", time: time }), _jsxs(Text, { bold: bold, dimColor: dimColor, children: [' ', message] })] }), subtitle && _jsx(Text, { dimColor: true, children: subtitle })] }));
+}

package/lib/types/components/design-system/Pane.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { Theme } from '../../theme.js';
+/**
+ * A pane — a region below the prompt bounded by a colored top line with a
+ * one-row gap above and horizontal padding. Used by the slash-command dialogs
+ * (/thinking,
+ * /model, /resume).
+ *
+ * @example
+ * <Pane color="permission">...</Pane>
+ */
+export declare function Pane({ children, color, }: {
+    children: React.ReactNode;
+    /** Theme color for the top border line. */
+    color?: keyof Theme;
+}): React.ReactNode;
+//# sourceMappingURL=Pane.d.ts.map

package/lib/types/components/design-system/Pane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pane.d.ts","sourceRoot":"","sources":["../../../../src/components/design-system/Pane.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE3C;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,EACnB,QAAQ,EACR,KAAK,GACN,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,KAAK,CAAA;CACpB,GAAG,KAAK,CAAC,SAAS,CASlB"}

package/lib/types/components/design-system/Pane.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import Box from '../../ink/components/Box.js';
+import { Divider } from './Divider.js';
+/**
+ * A pane — a region below the prompt bounded by a colored top line with a
+ * one-row gap above and horizontal padding. Used by the slash-command dialogs
+ * (/thinking,
+ * /model, /resume).
+ *
+ * @example
+ * <Pane color="permission">...</Pane>
+ */
+export function Pane({ children, color, }) {
+    return (_jsxs(Box, { flexDirection: "column", paddingTop: 1, children: [_jsx(Divider, { color: color }), _jsx(Box, { flexDirection: "column", paddingX: 2, children: children })] }));
+}

package/lib/types/components/design-system/ProgressBar.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+import type { Theme } from '../../theme.js';
+/**
+ * A proportional progress bar drawn with block glyphs: `█` fills whole cells,
+ * the partial cell uses the `▏▎▍▌▋▊▉` ladder for sub-cell precision, and the empty
+ * remainder is spaces with the empty color as background.
+ *
+ * @example
+ * <ProgressBar ratio={0.42} width={20} fillColor='accent' emptyColor="inactive" />
+ */
+export declare function ProgressBar({ ratio: inputRatio, width, fillColor, emptyColor, }: {
+    /** How much progress to display, between 0 and 1 inclusive. */
+    ratio: number;
+    /** How many characters wide to draw the progress bar. */
+    width: number;
+    /** Optional color for the filled portion of the bar. */
+    fillColor?: keyof Theme;
+    /** Optional color for the empty portion of the bar. */
+    emptyColor?: keyof Theme;
+}): React.ReactNode;
+//# sourceMappingURL=ProgressBar.d.ts.map

package/lib/types/components/design-system/ProgressBar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProgressBar.d.ts","sourceRoot":"","sources":["../../../../src/components/design-system/ProgressBar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE3C;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EAAE,UAAU,EACjB,KAAK,EACL,SAAS,EACT,UAAU,GACX,EAAE;IACD,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,KAAK,CAAA;IACvB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,KAAK,CAAA;CACzB,GAAG,KAAK,CAAC,SAAS,CAkBlB"}

package/lib/types/components/design-system/ProgressBar.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Text from './ThemedText.js';
+/**
+ * A proportional progress bar drawn with block glyphs: `█` fills whole cells,
+ * the partial cell uses the `▏▎▍▌▋▊▉` ladder for sub-cell precision, and the empty
+ * remainder is spaces with the empty color as background.
+ *
+ * @example
+ * <ProgressBar ratio={0.42} width={20} fillColor='accent' emptyColor="inactive" />
+ */
+export function ProgressBar({ ratio: inputRatio, width, fillColor, emptyColor, }) {
+    const ratio = Math.min(1, Math.max(0, inputRatio));
+    const whole = Math.floor(ratio * width);
+    const segments = [BLOCKS[BLOCKS.length - 1].repeat(whole)];
+    if (whole < width) {
+        const remainder = ratio * width - whole;
+        const middle = Math.floor(remainder * BLOCKS.length);
+        segments.push(BLOCKS[middle]);
+        const empty = width - whole - 1;
+        if (empty > 0) {
+            segments.push(BLOCKS[0].repeat(empty));
+        }
+    }
+    return (_jsx(Text, { color: fillColor, backgroundColor: emptyColor, children: segments.join('') }));
+}
+const BLOCKS = [' ', '▏', '▎', '▍', '▌', '▋', '▊', '▉', '█'];

package/lib/types/components/design-system/StatusIcon.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+type Status = 'success' | 'error' | 'warning' | 'info' | 'pending' | 'loading';
+/**
+ * A status indicator icon with the dsh-TUI color mapping: ✓ green / ✗ red /
+ * ⚠ amber / ℹ blue /
+ * ○ dim / … dim.
+ */
+export declare function StatusIcon({ status, withSpace, }: {
+    /** The status to display; determines both the icon and color. */
+    status: Status;
+    /** Include a trailing space after the icon. Useful when followed by text. */
+    withSpace?: boolean;
+}): React.ReactNode;
+export {};
+//# sourceMappingURL=StatusIcon.d.ts.map

package/lib/types/components/design-system/StatusIcon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StatusIcon.d.ts","sourceRoot":"","sources":["../../../../src/components/design-system/StatusIcon.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,KAAK,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAA;AAc9E;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,SAAiB,GAClB,EAAE;IACD,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAA;IACd,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,GAAG,KAAK,CAAC,SAAS,CAQlB"}

package/lib/types/components/design-system/StatusIcon.js

@@ -0,0 +1,20 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import figures from 'figures';
+import Text from './ThemedText.js';
+const STATUS_CONFIG = {
+    success: { icon: figures.tick, color: 'success' },
+    error: { icon: figures.cross, color: 'error' },
+    warning: { icon: figures.warning, color: 'warning' },
+    info: { icon: figures.info, color: 'suggestion' },
+    pending: { icon: figures.circle, color: undefined },
+    loading: { icon: '…', color: undefined },
+};
+/**
+ * A status indicator icon with the dsh-TUI color mapping: ✓ green / ✗ red /
+ * ⚠ amber / ℹ blue /
+ * ○ dim / … dim.
+ */
+export function StatusIcon({ status, withSpace = false, }) {
+    const config = STATUS_CONFIG[status];
+    return (_jsxs(Text, { color: config.color, children: [config.icon, withSpace ? ' ' : ''] }));
+}

package/lib/types/components/design-system/ThemeProvider.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+import type { TuiThemeHost } from '../../dsh-adapter/themes.js';
+/**
+ * DSH_TUI_THEME skips terminal detection (tests, debugging). Accepts a
+ * built-in, static JSON, or runtime plugin theme name; invalid
+ * values are warned and ignored by the caller, falling back to detection.
+ * Exported for /reload, which must respect the env override's precedence.
+ */
+export declare function envThemeOverride(): string | undefined;
+export declare function ThemeProvider({ children, theme, themeHost, }: {
+    children: React.ReactNode;
+    theme?: string;
+    /** Optional runtime theme host; absent in headless/static embeds. */
+    themeHost?: TuiThemeHost;
+}): React.ReactNode;
+/**
+ * Resolves the active theme name and the runtime setter. Returns
+ * `[themeName, setTheme]`.
+ */
+export declare function useTheme(): [string, (name: string) => boolean];
+//# sourceMappingURL=ThemeProvider.d.ts.map

package/lib/types/components/design-system/ThemeProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThemeProvider.d.ts","sourceRoot":"","sources":["../../../../src/components/design-system/ThemeProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAyD,MAAM,OAAO,CAAA;AAY7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAiE/D;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAGrD;AAcD,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,KAAK,EACL,SAAS,GACV,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,SAAS,CAAC,EAAE,YAAY,CAAA;CACzB,GAAG,KAAK,CAAC,SAAS,CAmMlB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAG9D"}

package/lib/types/components/design-system/ThemeProvider.js

@@ -0,0 +1,256 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { createContext, useContext, useEffect, useState } from 'react';
+import { isThemeAvailable, isLightThemeActive, registerCustomThemeResolver, setActiveThemeName, setAutoThemeBase, getAutoThemeBase, AUTO_THEME_NAME, } from '../../theme.js';
+import instances from '../../ink/instances.js';
+import { resolveCustomTheme } from '../../customTheme.js';
+import { useRuntimeThemeSnapshot } from '../../hooks/useRuntimeThemeSnapshot.js';
+import { readThemePref, writeThemePref } from '../../themePrefs.js';
+import useStdin from '../../ink/hooks/use-stdin.js';
+import useApp from '../../ink/hooks/use-app.js';
+import { oscColor } from '../../ink/terminal-querier.js';
+import { parseOscColor } from '../../ink/termio/osc.js';
+import { logForDebugging } from '../../utils/debug.js';
+/**
+ * Theme provider with terminal-background auto-detection. With no explicit
+ * `theme` prop, no DSH_TUI_THEME override and no persisted choice
+ * (~/.dsh-tui/theme.json), it queries the terminal's background color
+ * (OSC 11) before first paint and picks the Gentle Mist Blue `light` palette
+ * on light backgrounds, `dark` otherwise. Priority: explicit `theme` prop >
+ * DSH_TUI_THEME (built-in, static, or runtime plugin name) > persisted `/theme`
+ * choice > OSC 11 detection. An invalid forced name is warned and skipped, so
+ * detection still runs. Children render only after the theme settles, so
+ * the first frame already carries the final palette — no dark→light flash.
+ * Detection never blocks boot: a terminal that ignores OSC 11 (or a 400ms
+ * stall) falls back to `dark`. The resolved name is mirrored via
+ * setActiveThemeName() for non-React rendering (markdown inline code).
+ *
+ * The `auto` pseudo-theme turns that one-shot startup detection into a
+ * standing choice: `auto` is valid everywhere a theme name is (DSH_TUI_THEME,
+ * theme.json, /theme), defers first paint until detection settles like the
+ * unforced path, and re-queries OSC 11 on every runtime switch to `auto` —
+ * the detected base (light/dark) is mirrored via setAutoThemeBase() so
+ * getTheme('auto') resolves it for every consumer. OSC 11 tracks the system
+ * theme in terminals that follow it, so `auto` effectively follows the
+ * system light/dark mode.
+ *
+ * The context also exposes setTheme() for the runtime `/theme` picker: it
+ * validates static or plugin names, persists the choice to ~/.dsh-tui/theme.json
+ * and hot swaps the palette (and the module-level mirror) immediately. A
+ * disappearing plugin theme falls back safely without erasing the request.
+ */
+// Static user themes (~/.dsh-tui/themes/<name>.json) resolve through this
+// registry; the optional runtime host resolver is installed by the Cordis
+// service. Together they serve every themed component and non-React rendering.
+registerCustomThemeResolver(resolveCustomTheme);
+const ThemeContext = createContext({
+    theme: 'dark',
+    autoBase: 'dark',
+    setTheme: () => false,
+});
+/**
+ * DSH_TUI_THEME skips terminal detection (tests, debugging). Accepts a
+ * built-in, static JSON, or runtime plugin theme name; invalid
+ * values are warned and ignored by the caller, falling back to detection.
+ * Exported for /reload, which must respect the env override's precedence.
+ */
+export function envThemeOverride() {
+    const v = process.env.DSH_TUI_THEME;
+    return v === undefined || v === '' ? undefined : v;
+}
+/** Detection round-trip is normally ~10ms locally; this only bounds pathological stalls. */
+const DETECT_TIMEOUT_MS = 400;
+/**
+ * sRGB luma (Rec. 601). The threshold biases dark: a light palette on a
+ * dark terminal is far less readable than the reverse, and the dark
+ * palette is the pre-detection status quo.
+ */
+function isLightBackground(r, g, b) {
+    return 0.299 * r + 0.587 * g + 0.114 * b > 140;
+}
+export function ThemeProvider({ children, theme, themeHost, }) {
+    const runtimeThemeSnapshot = useRuntimeThemeSnapshot(themeHost);
+    // Resolution happens once on mount: the forced chain (prop > env >
+    // persisted) or null, which arms OSC 11 detection.
+    const [forced] = useState(() => theme ?? envThemeOverride() ?? readThemePref());
+    const [forcedValid] = useState(() => {
+        if (forced === undefined)
+            return false;
+        if (isThemeAvailable(forced))
+            return true;
+        console.warn(`[dsh-tui] theme "${forced}" not found (built-ins: auto, light, dark, dark-ansi; static ~/.dsh-tui/themes/*.json; runtime plugin themes); falling back to auto-detection`);
+        return false;
+    });
+    // `auto` (like the unforced path) stays null until detection settles, so
+    // the first frame already carries the detected palette.
+    const [active, setActive] = useState(forcedValid && forced !== AUTO_THEME_NAME ? forced ?? null : null);
+    // Keep the user's requested name independent from the rendered fallback. If
+    // a plugin theme disappears, this lets a later registration restore it while
+    // the persisted preference remains untouched.
+    const requestedThemeRef = React.useRef(forced);
+    const { internal_querier, isRawModeSupported } = useStdin();
+    const { stdout } = useApp();
+    /**
+     * The terminal background OSC 11 reported, if any. It is the colour a
+     * backdrop shade fades explicit colours toward (see StylePool.withDim);
+     * without it the shade falls back to black/white by theme lightness.
+     */
+    const [detectedBackground, setDetectedBackground] = useState(null);
+    /**
+     * The palette `auto` resolves to, as React state so a flip re-renders
+     * consumers through the context value. Kept in sync with the module-level
+     * mirror in theme.ts (non-React rendering reads that one).
+     */
+    const [autoBase, setAutoBase] = useState(() => getAutoThemeBase());
+    const applyAutoBase = React.useCallback((base) => {
+        setAutoThemeBase(base);
+        setAutoBase(base);
+    }, []);
+    useEffect(() => {
+        if (forcedValid && forced !== AUTO_THEME_NAME)
+            return;
+        const querier = internal_querier;
+        // Settle on the detected base: a concrete forced/unforced name activates
+        // directly; `auto` records the base and activates as `auto`.
+        const settle = (name, why) => {
+            logForDebugging(`theme: ${name} (${why})`);
+            const requested = requestedThemeRef.current;
+            if (forced !== AUTO_THEME_NAME && requested !== undefined && isThemeAvailable(requested)) {
+                setActive(requested);
+            }
+            else if (forced === AUTO_THEME_NAME) {
+                applyAutoBase(name);
+                setActive(AUTO_THEME_NAME);
+            }
+            else {
+                setActive(name);
+            }
+        };
+        // Stdin responses only flow while raw mode holds the readable listener;
+        // without a querier (or raw-mode support) detection is impossible.
+        if (querier === null || !isRawModeSupported) {
+            settle('dark', 'detection unavailable (no querier/raw mode)');
+            return;
+        }
+        let settled = false;
+        const finish = (name, why) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            settle(name, why);
+        };
+        const timer = setTimeout(() => {
+            finish('dark', 'detection timeout');
+        }, DETECT_TIMEOUT_MS);
+        void Promise.all([querier.send(oscColor(11)), querier.flush()]).then(([r]) => {
+            const color = r ? parseOscColor(r.data) : null;
+            if (color === null || color.type !== 'rgb') {
+                finish('dark', 'no OSC 11 reply');
+            }
+            else {
+                setDetectedBackground({ r: color.r, g: color.g, b: color.b });
+                finish(isLightBackground(color.r, color.g, color.b) ? 'light' : 'dark', `OSC 11 bg rgb(${color.r},${color.g},${color.b})`);
+            }
+        });
+        return () => {
+            settled = true;
+            clearTimeout(timer);
+        };
+    }, []);
+    /**
+     * Re-query the terminal background while the app is running (runtime
+     * switch to `auto`). Stdin is already in raw mode here — unlike the
+     * startup path above — so no raw-mode toggling. Best effort: a terminal
+     * that doesn't answer just keeps the current base.
+     */
+    const redetectAutoBase = React.useCallback(() => {
+        const querier = internal_querier;
+        if (querier === null || !isRawModeSupported) {
+            logForDebugging('theme: auto re-detection unavailable, keeping current base');
+            return;
+        }
+        void Promise.all([querier.send(oscColor(11)), querier.flush()]).then(([r]) => {
+            const color = r ? parseOscColor(r.data) : null;
+            if (color === null || color.type !== 'rgb')
+                return;
+            setDetectedBackground({ r: color.r, g: color.g, b: color.b });
+            const base = isLightBackground(color.r, color.g, color.b) ? 'light' : 'dark';
+            logForDebugging(`theme: auto base ${base} (OSC 11 bg rgb(${color.r},${color.g},${color.b}))`);
+            applyAutoBase(base);
+        });
+    }, [internal_querier, isRawModeSupported, applyAutoBase]);
+    /**
+     * Runtime theme switch (/theme picker or direct command). Validates the
+     * name, persists first (a choice that cannot be saved never silently
+     * disappears), then hot swaps the palette. Switching to `auto` applies
+     * the last detected base immediately and re-queries OSC 11 in the
+     * background, so a theme change since launch is picked up.
+     */
+    const setTheme = React.useCallback((name) => {
+        if (!isThemeAvailable(name)) {
+            console.warn(`[dsh-tui] theme "${name}" not found`);
+            return false;
+        }
+        if (!writeThemePref(name)) {
+            console.warn('[dsh-tui] failed to write ~/.dsh-tui/theme.json');
+            return false;
+        }
+        requestedThemeRef.current = name;
+        setActive(name);
+        if (name === AUTO_THEME_NAME)
+            redetectAutoBase();
+        return true;
+    }, [redetectAutoBase]);
+    useEffect(() => {
+        if (active !== null && !isThemeAvailable(active)) {
+            // A runtime plugin can disappear while its name remains persisted. Do
+            // not render getTheme(name)'s dark fallback under the stale name; keep
+            // the requested name in the ref and use a safe auto palette instead.
+            setActive(AUTO_THEME_NAME);
+            redetectAutoBase();
+            return;
+        }
+        const requested = requestedThemeRef.current;
+        if (requested !== undefined &&
+            requested !== AUTO_THEME_NAME &&
+            requested !== active &&
+            isThemeAvailable(requested)) {
+            // The plugin theme was unavailable during boot (or briefly unloaded),
+            // but has registered again. Restore the persisted/requested choice.
+            setActive(requested);
+        }
+    }, [active, redetectAutoBase, runtimeThemeSnapshot]);
+    const renderedTheme = active === null
+        ? 'dark'
+        : isThemeAvailable(active)
+            ? active
+            : AUTO_THEME_NAME;
+    const value = React.useMemo(() => ({ theme: renderedTheme, autoBase, setTheme }), [renderedTheme, autoBase, setTheme]);
+    useEffect(() => {
+        if (active !== null)
+            setActiveThemeName(renderedTheme);
+    }, [active, renderedTheme]);
+    // Backdrop shade target: the detected terminal background when OSC 11
+    // answered, else black/white by the rendered theme's lightness. `autoBase`
+    // is a dependency because `auto` resolves through it.
+    useEffect(() => {
+        if (active === null)
+            return;
+        const ink = instances.get(stdout);
+        if (ink === undefined)
+            return;
+        ink.setShadeTarget(detectedBackground
+            ?? (isLightThemeActive(renderedTheme) ? { r: 255, g: 255, b: 255 } : { r: 0, g: 0, b: 0 }));
+    }, [active, renderedTheme, autoBase, detectedBackground, stdout]);
+    if (active === null)
+        return null;
+    return _jsx(ThemeContext.Provider, { value: value, children: children });
+}
+/**
+ * Resolves the active theme name and the runtime setter. Returns
+ * `[themeName, setTheme]`.
+ */
+export function useTheme() {
+    const { theme, setTheme } = useContext(ThemeContext);
+    return [theme, setTheme];
+}

package/lib/types/components/design-system/ThemedBox.d.ts

@@ -0,0 +1,60 @@
+import React, { type PropsWithChildren, type Ref } from 'react';
+import type { DOMElement } from '../../ink/dom.js';
+import type { ClickEvent } from '../../ink/events/click-event.js';
+import type { ContextMenuEvent } from '../../ink/events/context-menu-event.js';
+import type { DragEvent } from '../../ink/events/drag-event.js';
+import type { FocusEvent } from '../../ink/events/focus-event.js';
+import type { KeyboardEvent } from '../../ink/events/keyboard-event.js';
+import type { PointerEvent } from '../../ink/events/pointer-event.js';
+import type { WheelEvent } from '../../ink/events/wheel-event.js';
+import type { Color, Styles } from '../../ink/styles.js';
+import { type Theme } from '../../theme.js';
+type ThemedColorProps = {
+    readonly borderColor?: keyof Theme | Color;
+    readonly borderTopColor?: keyof Theme | Color;
+    readonly borderBottomColor?: keyof Theme | Color;
+    readonly borderLeftColor?: keyof Theme | Color;
+    readonly borderRightColor?: keyof Theme | Color;
+    readonly backgroundColor?: keyof Theme | Color;
+    /** 条件表面色：仅当终端图像落在本 Box 后方时才涂底（见 ink Styles）。 */
+    readonly occlusionColor?: keyof Theme | Color;
+};
+type BaseStylesWithoutColors = Omit<Styles, 'textWrap' | 'borderColor' | 'borderTopColor' | 'borderBottomColor' | 'borderLeftColor' | 'borderRightColor' | 'backgroundColor' | 'occlusionColor'>;
+export type Props = BaseStylesWithoutColors & ThemedColorProps & {
+    ref?: Ref<DOMElement>;
+    tabIndex?: number;
+    autoFocus?: boolean;
+    onClick?: (event: ClickEvent) => void;
+    onContextMenu?: (event: ContextMenuEvent) => void;
+    /**
+     * Drag protocol handlers, transparently forwarded to the inner Box.
+     * Only inside `<AlternateScreen>`, left button, no modifier at press;
+     * `dragstart` fires on FIRST movement (not press); a press+release
+     * without movement still triggers `onClick`. See Box's JSDoc.
+     */
+    onDragStart?: (event: DragEvent) => void;
+    /** Fired on each pointer motion after dragstart. See onDragStart. */
+    onDragMove?: (event: DragEvent) => void;
+    /** Fired on release after dragstart. See onDragStart. */
+    onDragEnd?: (event: DragEvent) => void;
+    onFocus?: (event: FocusEvent) => void;
+    onFocusCapture?: (event: FocusEvent) => void;
+    onBlur?: (event: FocusEvent) => void;
+    onBlurCapture?: (event: FocusEvent) => void;
+    onKeyDown?: (event: KeyboardEvent) => void;
+    onKeyDownCapture?: (event: KeyboardEvent) => void;
+    onMouseEnter?: (event: PointerEvent) => void;
+    onMouseLeave?: (event: PointerEvent) => void;
+    /**
+     * Wheel events over this Box's rendered rect (position-routed; see the
+     * ink Box's onWheel JSDoc). Transparently forwarded.
+     */
+    onWheel?: (event: WheelEvent) => void;
+};
+/**
+ * Theme-aware Box component that resolves theme color keys to raw colors
+ * in the dsh-TUI visual language.
+ */
+declare function ThemedBox({ borderColor, borderTopColor, borderBottomColor, borderLeftColor, borderRightColor, backgroundColor, occlusionColor, ...rest }: PropsWithChildren<Props>): React.ReactNode;
+export default ThemedBox;
+//# sourceMappingURL=ThemedBox.d.ts.map

package/lib/types/components/design-system/ThemedBox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThemedBox.d.ts","sourceRoot":"","sources":["../../../../src/components/design-system/ThemedBox.tsx"],"names":[],"mappings":"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"}

package/lib/types/components/design-system/ThemedBox.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Box from '../../ink/components/Box.js';
+import { getTheme } from '../../theme.js';
+import { useTheme } from './ThemeProvider.js';
+/** Resolves a color value that may be a theme key to a raw Color. */
+function resolveColor(color, theme) {
+    if (!color)
+        return undefined;
+    if (color.startsWith('rgb(') ||
+        color.startsWith('#') ||
+        color.startsWith('ansi256(') ||
+        color.startsWith('ansi:')) {
+        return color;
+    }
+    // Theme keys may be '' ("no color" in that theme) - collapse to undefined
+    // so empty tokens render as no background/foreground instead of feeding
+    // an empty color string to Ink.
+    return theme[color] || undefined;
+}
+/**
+ * Theme-aware Box component that resolves theme color keys to raw colors
+ * in the dsh-TUI visual language.
+ */
+function ThemedBox({ borderColor, borderTopColor, borderBottomColor, borderLeftColor, borderRightColor, backgroundColor, occlusionColor, ...rest }) {
+    const [themeName] = useTheme();
+    const theme = getTheme(themeName);
+    return (_jsx(Box, { ...rest, borderColor: resolveColor(borderColor, theme), borderTopColor: resolveColor(borderTopColor, theme), borderBottomColor: resolveColor(borderBottomColor, theme), borderLeftColor: resolveColor(borderLeftColor, theme), borderRightColor: resolveColor(borderRightColor, theme), backgroundColor: resolveColor(backgroundColor, theme), occlusionColor: resolveColor(occlusionColor, theme) }));
+}
+export default ThemedBox;