@agi-fans/dsh-tui 0.3.0 → 0.5.0

package/lib/chrome/status-config.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Status-line customization shared by settings, persistence, and rendering.
+ * @module @agi-fans/dsh-tui/status-config
+ */
+/** Stable telemetry groups users can show, hide, and reorder. */
+export declare const STATUS_GROUP_IDS: readonly ["context", "cache", "tokens", "speed", "durations", "counts"];
+export type StatusGroupId = (typeof STATUS_GROUP_IDS)[number];
+/** First-line pieces: model, reasoning effort, workspace path, and Git branch. */
+export declare const STATUS_META_IDS: readonly ["model", "effort", "path", "git"];
+export type StatusMetaId = (typeof STATUS_META_IDS)[number];
+/** Every independently placed footer item. */
+export declare const STATUS_ITEM_IDS: readonly ["model", "effort", "path", "git", "context", "cache", "tokens", "speed", "durations", "counts"];
+export type StatusItemId = (typeof STATUS_ITEM_IDS)[number];
+export declare const STATUS_LABEL_STYLES: readonly ["compact", "full"];
+export type StatusLabelStyle = (typeof STATUS_LABEL_STYLES)[number];
+/**
+ * Color slots: one per preview item, plus legacy `metrics` as a fallback for
+ * telemetry groups that do not have their own color yet.
+ */
+export declare const STATUS_COLOR_SLOTS: readonly ["model", "effort", "path", "git", "context", "cache", "tokens", "speed", "durations", "counts", "metrics"];
+export type StatusColorSlot = (typeof STATUS_COLOR_SLOTS)[number];
+/** Theme tokens offered for a status item. `default` keeps the built-in hierarchy. */
+export declare const STATUS_COLOR_TOKENS: readonly ["default", "text", "muted", "accent", "success", "warning", "border", "label"];
+export type StatusColorToken = (typeof STATUS_COLOR_TOKENS)[number];
+/** Footer column an item can occupy. */
+export declare const STATUS_SIDES: readonly ["left", "right"];
+export type StatusSide = (typeof STATUS_SIDES)[number];
+export declare const DEFAULT_STATUS_SIDES: Record<StatusItemId, StatusSide>;
+/** Per-item color choices. Omitted items keep their built-in tone. */
+export type StatusBarColors = Partial<Record<StatusColorSlot, StatusColorToken>>;
+/** User-owned status-line layout. Missing `groups`/`meta` are hidden; `order` retains their slots. */
+export interface StatusBarConfig {
+    enabled: boolean;
+    labels: StatusLabelStyle;
+    groups: StatusGroupId[];
+    /** Complete visual order, including hidden groups. Absent in legacy settings. */
+    order?: StatusGroupId[];
+    /** Visible first-line items. Absent means every meta item is shown. */
+    meta?: StatusMetaId[];
+    /** Complete first-line order, including hidden meta items. */
+    metaOrder?: StatusMetaId[];
+    /** Optional per-item colors for the two-line footer. */
+    colors?: StatusBarColors;
+    /** Optional left/right column for each item. */
+    sides?: Partial<Record<StatusItemId, StatusSide>>;
+}
+/** Normalized layout always carries complete orders, colors, and columns. */
+export interface ResolvedStatusBarConfig extends StatusBarConfig {
+    order: StatusGroupId[];
+    meta: StatusMetaId[];
+    metaOrder: StatusMetaId[];
+    colors: Required<StatusBarColors>;
+    sides: Record<StatusItemId, StatusSide>;
+}
+/** Legacy value accepted while existing settings documents migrate. */
+export declare const STATUS_PRESETS: readonly ["minimal", "compact", "full"];
+export type StatusPreset = (typeof STATUS_PRESETS)[number];
+export declare const DEFAULT_STATUS_GROUPS: readonly StatusGroupId[];
+export declare const DEFAULT_STATUS_META: readonly StatusMetaId[];
+export declare const DEFAULT_STATUS_COLORS: Required<StatusBarColors>;
+/** Return a fresh default so callers can safely replace its group list. */
+export declare function defaultStatusBarConfig(): ResolvedStatusBarConfig;
+export declare function isStatusMetaId(value: unknown): value is StatusMetaId;
+export declare function isStatusItemId(value: unknown): value is StatusItemId;
+export declare function itemSide(config: StatusBarConfig, id: StatusItemId): StatusSide;
+/**
+ * Normalize persisted input at the single configuration seam. Invalid and
+ * duplicate groups disappear; legacy presets retain their previous meaning.
+ */
+export declare function resolveStatusBarConfig(config?: Partial<StatusBarConfig>, legacyPreset?: StatusPreset): ResolvedStatusBarConfig;

package/lib/chrome/status-config.js

@@ -0,0 +1,147 @@
+/**
+ * Status-line customization shared by settings, persistence, and rendering.
+ * @module @agi-fans/dsh-tui/status-config
+ */
+/** Stable telemetry groups users can show, hide, and reorder. */
+export const STATUS_GROUP_IDS = ['context', 'cache', 'tokens', 'speed', 'durations', 'counts'];
+/** First-line pieces: model, reasoning effort, workspace path, and Git branch. */
+export const STATUS_META_IDS = ['model', 'effort', 'path', 'git'];
+/** Every independently placed footer item. */
+export const STATUS_ITEM_IDS = [...STATUS_META_IDS, ...STATUS_GROUP_IDS];
+export const STATUS_LABEL_STYLES = ['compact', 'full'];
+/**
+ * Color slots: one per preview item, plus legacy `metrics` as a fallback for
+ * telemetry groups that do not have their own color yet.
+ */
+export const STATUS_COLOR_SLOTS = [...STATUS_ITEM_IDS, 'metrics'];
+/** Theme tokens offered for a status item. `default` keeps the built-in hierarchy. */
+export const STATUS_COLOR_TOKENS = ['default', 'text', 'muted', 'accent', 'success', 'warning', 'border', 'label'];
+/** Footer column an item can occupy. */
+export const STATUS_SIDES = ['left', 'right'];
+export const DEFAULT_STATUS_SIDES = {
+    model: 'left',
+    effort: 'left',
+    path: 'right',
+    git: 'right',
+    context: 'left',
+    cache: 'left',
+    tokens: 'left',
+    speed: 'left',
+    durations: 'right',
+    counts: 'right',
+};
+/** Legacy value accepted while existing settings documents migrate. */
+export const STATUS_PRESETS = ['minimal', 'compact', 'full'];
+export const DEFAULT_STATUS_GROUPS = STATUS_GROUP_IDS;
+export const DEFAULT_STATUS_META = STATUS_META_IDS;
+export const DEFAULT_STATUS_COLORS = {
+    model: 'default',
+    effort: 'default',
+    path: 'default',
+    git: 'default',
+    metrics: 'default',
+    context: 'default',
+    cache: 'default',
+    tokens: 'default',
+    speed: 'default',
+    durations: 'default',
+    counts: 'default',
+};
+/** Return a fresh default so callers can safely replace its group list. */
+export function defaultStatusBarConfig() {
+    return {
+        enabled: true,
+        labels: 'compact',
+        groups: [...DEFAULT_STATUS_GROUPS],
+        order: [...DEFAULT_STATUS_GROUPS],
+        meta: [...DEFAULT_STATUS_META],
+        metaOrder: [...DEFAULT_STATUS_META],
+        colors: { ...DEFAULT_STATUS_COLORS },
+        sides: { ...DEFAULT_STATUS_SIDES },
+    };
+}
+function isStatusGroupId(value) {
+    return typeof value === 'string' && STATUS_GROUP_IDS.includes(value);
+}
+export function isStatusMetaId(value) {
+    return typeof value === 'string' && STATUS_META_IDS.includes(value);
+}
+export function isStatusItemId(value) {
+    return typeof value === 'string' && STATUS_ITEM_IDS.includes(value);
+}
+function isStatusLabelStyle(value) {
+    return typeof value === 'string' && STATUS_LABEL_STYLES.includes(value);
+}
+function isStatusColorToken(value) {
+    return typeof value === 'string' && STATUS_COLOR_TOKENS.includes(value);
+}
+function isStatusSide(value) {
+    return value === 'left' || value === 'right';
+}
+export function itemSide(config, id) {
+    return config.sides?.[id] ?? DEFAULT_STATUS_SIDES[id];
+}
+function resolveStatusSides(sides) {
+    const resolved = { ...DEFAULT_STATUS_SIDES };
+    if (sides === undefined)
+        return resolved;
+    for (const id of STATUS_ITEM_IDS) {
+        const side = sides[id];
+        if (isStatusSide(side))
+            resolved[id] = side;
+    }
+    return resolved;
+}
+function completeOrder(ids, preferred) {
+    const ordered = [...new Set(preferred.filter((id) => ids.includes(id)))];
+    return [...ordered, ...ids.filter(id => !ordered.includes(id))];
+}
+function resolveStatusColors(colors) {
+    const resolved = { ...DEFAULT_STATUS_COLORS };
+    if (colors === undefined)
+        return resolved;
+    for (const slot of STATUS_COLOR_SLOTS) {
+        const token = colors[slot];
+        if (isStatusColorToken(token))
+            resolved[slot] = token;
+    }
+    const legacyMetrics = resolved.metrics;
+    if (legacyMetrics !== 'default') {
+        for (const group of STATUS_GROUP_IDS) {
+            if (colors[group] === undefined)
+                resolved[group] = legacyMetrics;
+        }
+    }
+    return resolved;
+}
+/**
+ * Normalize persisted input at the single configuration seam. Invalid and
+ * duplicate groups disappear; legacy presets retain their previous meaning.
+ */
+export function resolveStatusBarConfig(config, legacyPreset) {
+    if (config === undefined) {
+        const fallback = defaultStatusBarConfig();
+        if (legacyPreset === 'minimal')
+            fallback.enabled = false;
+        if (legacyPreset === 'full')
+            fallback.labels = 'full';
+        return fallback;
+    }
+    const groups = config.groups === undefined
+        ? [...DEFAULT_STATUS_GROUPS]
+        : [...new Set(config.groups.filter(isStatusGroupId))];
+    const meta = config.meta === undefined
+        ? [...DEFAULT_STATUS_META]
+        : [...new Set(config.meta.filter(isStatusMetaId))];
+    return {
+        enabled: config.enabled ?? true,
+        labels: isStatusLabelStyle(config.labels) ? config.labels : 'compact',
+        groups,
+        order: completeOrder(STATUS_GROUP_IDS, config.order === undefined ? groups : config.order),
+        meta,
+        metaOrder: completeOrder(STATUS_META_IDS, config.metaOrder === undefined ? meta : config.metaOrder),
+        colors: resolveStatusColors(config.colors),
+        sides: resolveStatusSides(config.sides),
+    };
+}
+//# sourceMappingURL=status-config.js.map

package/lib/chrome/status-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-config.js","sourceRoot":"","sources":["../../src/chrome/status-config.ts"],"names":[],"mappings":"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"}

package/lib/{status-line.d.ts → chrome/status-line.d.ts}

@@ -7,19 +7,22 @@
  * second locale — then this is the single seam where a dictionary is chosen.
  * @module @agi-fans/dsh-tui/status-line
  */
-import type { TuiSessionControls, TuiSessionStats } from './definition.ts';
-import { type StatusBarConfig } from './status-config.ts';
+import type { TuiLoopStatus, TuiSessionControls, TuiSessionStats } from '../definition.ts';
+import { type StatusBarConfig, type StatusItemId } from './status-config.ts';
 import type { Theme } from './theme.ts';
 /** Context needed to render the fixed session footer. */
 export interface StatusFooterOptions {
     model: string;
     reasoningEffort?: string;
     controls?: TuiSessionControls;
+    loop?: TuiLoopStatus;
     pwd?: string;
     branch?: string;
     stats?: TuiSessionStats;
     config: StatusBarConfig;
     width: number;
+    /** Settings preview: underline the focused item. */
+    focus?: StatusItemId;
 }
 /** Compact token count: 517 / 12.2K / 517K / 1.2M. */
 export declare function formatTokens(value: number): string;
@@ -29,11 +32,29 @@ export declare function formatDuration(ms: number): string;
 export declare function formatTokensPerSecond(value: number): string;
 /** Build the unpainted English groups for diagnostics and tests. */
 export declare function sessionStatusGroups(stats: TuiSessionStats, config?: StatusBarConfig): string[];
+/** Human-facing permission preset used consistently across terminal surfaces. */
+export declare function formatPermission(permission: string): string;
+/** Painted permission mode for the composer top-right cap. */
+export declare function renderPermissionBadge(permission: string | undefined, theme: Theme): string;
 /**
  * Render the fixed footer: model/workspace metadata first, customizable
  * session telemetry second. Both rows use left/right columns and exact width.
  */
 export declare function renderStatusFooter(options: StatusFooterOptions, theme: Theme): string[];
+/**
+ * Status sample for `/settings`. Uses the same left/right footer layout as
+ * the live two-line status bar.
+ */
+export declare function renderStatusPreviewLines(options: {
+    model: string;
+    reasoningEffort?: string;
+    pwd?: string;
+    branch?: string;
+    stats?: TuiSessionStats;
+    config: StatusBarConfig;
+    width: number;
+    focus?: StatusItemId;
+}, theme: Theme): string[];
 /**
  * Render the telemetry row without footer metadata. Used by the settings
  * preview and retained as a compatibility seam for direct render callers.