@oh-my-pi/pi-tui 18.2.4 → 18.2.5

package/dist/types/theme/index.d.ts

@@ -0,0 +1,4 @@
+export * from "../lang-from-path.js";
+export * from "./session-color.js";
+export * from "./shimmer.js";
+export * from "./theme.js";

package/dist/types/theme/loader.d.ts

@@ -0,0 +1,23 @@
+import type { ColorMode, ThemeJson } from "./schema.js";
+import { type SymbolPreset } from "./symbols.js";
+import { Theme } from "./theme-class.js";
+export declare function getBuiltinThemes(): Record<string, ThemeJson>;
+export declare function getAvailableThemes(): Promise<string[]>;
+export interface ThemeInfo {
+    name: string;
+    path: string | undefined;
+}
+export declare function getAvailableThemesWithPaths(): Promise<ThemeInfo[]>;
+export declare function loadThemeJson(name: string): Promise<ThemeJson>;
+/** Load a theme definition synchronously for the first terminal frame. */
+export declare function loadThemeJsonSync(name: string): ThemeJson;
+export interface CreateThemeOptions {
+    mode?: ColorMode;
+    symbolPresetOverride?: SymbolPreset;
+    colorBlindMode?: boolean;
+}
+export declare function createTheme(themeJson: ThemeJson, options?: CreateThemeOptions): Theme;
+export declare function loadTheme(name: string, options?: CreateThemeOptions): Promise<Theme>;
+/** Load and construct a theme synchronously for latency-sensitive first paint. */
+export declare function loadThemeSync(name: string, options?: CreateThemeOptions): Theme;
+export declare function getThemeByName(name: string): Promise<Theme | undefined>;

package/dist/types/theme/mermaid-cache.d.ts

@@ -0,0 +1,26 @@
+import { type MermaidAsciiRenderOptions } from "@oh-my-pi/pi-utils/mermaid-ascii";
+/**
+ * Options controlling how fenced Mermaid source is resolved to terminal ASCII.
+ * Extends the raw render options (theme, color mode, spacing, `useAscii`) with a
+ * viewport-fitting hint.
+ */
+export interface MermaidResolveOptions extends MermaidAsciiRenderOptions {
+    /**
+     * Maximum display width (terminal columns) the diagram should occupy. A
+     * layout that overflows this width is re-rendered in the perpendicular
+     * orientation — a wide horizontal chain collapses to a tall vertical column
+     * (which the terminal can scroll), and a wide vertical fan-out collapses to a
+     * tall horizontal column. Omit to keep the source's own layout regardless of
+     * width.
+     */
+    maxWidth?: number;
+}
+/**
+ * Resolve mermaid ASCII from fenced block source text.
+ * Returns null when rendering fails, while memoizing failures to avoid repeated work.
+ */
+export declare function resolveMermaidAscii(source: string, options?: MermaidResolveOptions): string | null;
+/**
+ * Clear the mermaid cache.
+ */
+export declare function clearMermaidCache(): void;

package/dist/types/theme/schema-validation.d.ts

@@ -0,0 +1,3 @@
+import type { ThemeJson } from "./schema.js";
+/** Validate a custom theme with the full omptype contract. */
+export declare function validateThemeJson(value: unknown): ThemeJson;

package/dist/types/theme/schema.d.ts

@@ -0,0 +1,25 @@
+import type { SpinnerFramesOverride } from "./symbols.js";
+export type ColorValue = string | number;
+export interface ThemeJson {
+    $schema?: string;
+    name: string;
+    vars?: Record<string, ColorValue>;
+    colors: Omit<Record<ThemeColor | ThemeBg, ColorValue>, "thinkingMax"> & {
+        thinkingMax?: ColorValue;
+    };
+    export?: {
+        pageBg?: ColorValue;
+        cardBg?: ColorValue;
+        infoBg?: ColorValue;
+    };
+    symbols?: {
+        preset?: "unicode" | "nerd" | "ascii";
+        overrides?: Record<string, string>;
+        spinnerFrames?: SpinnerFramesOverride;
+    };
+}
+export type ThemeColor = "accent" | "border" | "borderAccent" | "borderMuted" | "success" | "error" | "warning" | "muted" | "dim" | "text" | "thinkingText" | "userMessageText" | "customMessageText" | "customMessageLabel" | "toolTitle" | "toolOutput" | "mdHeading" | "mdLink" | "mdLinkUrl" | "mdCode" | "mdCodeBlock" | "mdCodeBlockBorder" | "mdQuote" | "mdQuoteBorder" | "mdHr" | "mdListBullet" | "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext" | "syntaxComment" | "syntaxKeyword" | "syntaxFunction" | "syntaxVariable" | "syntaxString" | "syntaxNumber" | "syntaxType" | "syntaxOperator" | "syntaxPunctuation" | "thinkingOff" | "thinkingMinimal" | "thinkingLow" | "thinkingMedium" | "thinkingHigh" | "thinkingXhigh" | "thinkingMax" | "bashMode" | "pythonMode" | "statusLineSep" | "statusLineModel" | "statusLinePath" | "statusLineGitClean" | "statusLineGitDirty" | "statusLineContext" | "statusLineSpend" | "statusLineStaged" | "statusLineDirty" | "statusLineUntracked" | "statusLineOutput" | "statusLineCost" | "statusLineSubagents";
+/** Check if a string is a valid ThemeColor value */
+export declare function isValidThemeColor(color: string): color is ThemeColor;
+export type ThemeBg = "selectedBg" | "userMessageBg" | "customMessageBg" | "toolPendingBg" | "toolSuccessBg" | "toolErrorBg" | "statusLineBg";
+export type ColorMode = "truecolor" | "256color";

package/dist/types/theme/session-color.d.ts

@@ -0,0 +1,43 @@
+/** Theme-derived inputs for {@link getSessionAccentHex}; see `Theme.sessionAccentInputs`. */
+export interface SessionAccentTheme {
+    /** Theme accent hex; the session accent adopts its OKLCH lightness and chroma. */
+    accentHex: string;
+    /** Major theme color hexes checked for hue collision. */
+    colorHexes: string[];
+    /** WCAG luminance of the status-line surface on light themes; undefined on dark themes. */
+    surfaceLuminance?: number;
+}
+/**
+ * Derive a stable CSS hex accent color from a session name and the active theme.
+ *
+ * The session name hash picks only the **hue**, from a dark/light-specific
+ * hue arc so the accent feels natural for the theme type: the full wheel on
+ * dark minus hues whose vividness peak is unreachable under the dark
+ * lightness cap (see {@link DARK_HUE_INTERVALS}); cool on light. **Lightness and chroma are carried over from the theme's own accent
+ * color**, normalized to the sRGB gamut cusp of each hue: the lightness at
+ * which a hue peaks in chroma varies wildly (yellow ≈ 0.97, blue ≈ 0.45), so
+ * absolute OKLCH lightness cannot transfer between hues — a pink accent's
+ * l≈0.67 re-hued to yellow is mustard, not vivid yellow. Instead the
+ * accent's position relative to its own hue's cusp (lightness side and
+ * chroma fraction) is re-applied at the target hue's cusp, so the session
+ * accent inherits the theme's vividness at every hue. The hue is checked against all
+ * theme color hues and shifted if it lands within {@link MIN_HUE_DISTANCE}
+ * of one, but the shift walks along the admissible arc so it never drifts
+ * into an unrelated or excluded part of the spectrum.
+ *
+ * On dark themes (`surfaceLuminance` undefined) the carried lightness is
+ * clamped to stay visible on dark surfaces. On light themes it is reduced
+ * until the accent's luminance clears {@link ACCENT_MIN_CONTRAST} against
+ * the actual surface it renders on — legible on near-white *and* mid-light
+ * backgrounds.
+ *
+ * @param name — session name for per-session uniqueness.
+ * @param theme — accent hex, collision colors, and surface luminance of the active theme.
+ */
+export declare function getSessionAccentHex(name: string, theme: SessionAccentTheme): string;
+/**
+ * Convert a hex accent color to an ANSI foreground escape sequence matching
+ * the detected terminal color depth.
+ * Returns `undefined` if `hex` is nullish or Bun.color conversion fails.
+ */
+export declare function getSessionAccentAnsi(hex: string | undefined): string | undefined;

package/dist/types/theme/shimmer.d.ts

@@ -0,0 +1,44 @@
+import type { Theme, ThemeColor } from "./theme.js";
+type ShimmerTheme = Pick<Theme, "bold" | "fg" | "getFgAnsi">;
+/** Sweep style for animated shimmer text; `disabled` renders every tier as the low color. */
+export type ShimmerMode = "classic" | "kitt" | "disabled";
+/** Select the shimmer sweep style. The host pushes its `display.shimmer` preference here. */
+export declare function setShimmerMode(mode: ShimmerMode): void;
+type ShimmerPaletteTier = ThemeColor | {
+    ansi: string;
+};
+/** Three-tier color stack a shimmer character cycles through as the band sweeps. */
+export interface ShimmerPalette {
+    /** Color for chars outside / at the edge of the band (intensity < ~0.22). */
+    low: ShimmerPaletteTier;
+    /** Color for chars approaching the crest (~0.22 ≤ intensity < ~0.65). */
+    mid: ShimmerPaletteTier;
+    /** Color at the band's crest (intensity ≥ ~0.65). */
+    high: ShimmerPaletteTier;
+    /** Whether to bold the crest tier. Default `false`. */
+    bold?: boolean;
+}
+/** One run of text that shares a palette inside a larger shimmer sweep. */
+export interface ShimmerSegment {
+    text: string;
+    palette?: ShimmerPalette;
+}
+export declare const DEFAULT_SHIMMER_PALETTE: ShimmerPalette;
+/** Whether shimmer animations are active (any mode other than `disabled`). */
+export declare function shimmerEnabled(): boolean;
+/**
+ * Apply a shimmer sweep across one or more segments, treating them as a
+ * single continuous string for band positioning. Each segment can supply
+ * its own palette so the gradient stays in lockstep while the colors
+ * differ.
+ *
+ * Performance shape (per call, dominant cost):
+ *   - One `Date.now()` read.
+ *   - One `compile()` lookup per segment (Symbol-keyed cache slot, hot path
+ *     skipped after first frame).
+ *   - One ANSI open/close pair per **run of same-tier chars**, not per char.
+ *   - No per-char allocations beyond the run buffer.
+ */
+export declare function shimmerSegments(segments: readonly ShimmerSegment[], theme: ShimmerTheme): string;
+export declare function shimmerText(text: string, theme: ShimmerTheme, palette?: ShimmerPalette): string;
+export {};

package/dist/types/theme/symbols.d.ts

@@ -0,0 +1,34 @@
+export type SymbolPreset = "unicode" | "nerd" | "ascii";
+/**
+ * All available symbol keys organized by category.
+ */
+export type SymbolKey = "status.success" | "status.error" | "status.warning" | "status.info" | "status.pending" | "status.disabled" | "status.enabled" | "status.running" | "status.shadowed" | "status.aborted" | "status.done" | "nav.cursor" | "nav.selected" | "nav.expand" | "nav.collapse" | "nav.back" | "tree.branch" | "tree.last" | "tree.vertical" | "tree.horizontal" | "tree.hook" | "progress.filled" | "progress.empty" | "context.speculation" | "context.compaction" | "boxRound.topLeft" | "boxRound.topRight" | "boxRound.bottomLeft" | "boxRound.bottomRight" | "boxRound.horizontal" | "boxRound.vertical" | "boxDotted.horizontal" | "boxDotted.vertical" | "boxSharp.topLeft" | "boxSharp.topRight" | "boxSharp.bottomLeft" | "boxSharp.bottomRight" | "boxSharp.horizontal" | "boxSharp.vertical" | "boxSharp.cross" | "boxSharp.teeDown" | "boxSharp.teeUp" | "boxSharp.teeRight" | "boxSharp.teeLeft" | "sep.powerline" | "sep.powerlineThin" | "sep.powerlineLeft" | "sep.powerlineRight" | "sep.powerlineThinLeft" | "sep.powerlineThinRight" | "sep.powerlineCapLeft" | "sep.block" | "sep.space" | "sep.asciiLeft" | "sep.asciiRight" | "sep.dot" | "sep.slash" | "sep.pipe" | "icon.model" | "icon.plan" | "icon.prewalk" | "icon.goal" | "icon.pause" | "icon.loop" | "icon.folder" | "icon.worktree" | "icon.search" | "icon.scratchFolder" | "icon.file" | "icon.git" | "icon.branch" | "icon.pr" | "icon.pin" | "icon.tokens" | "icon.context" | "icon.cost" | "icon.subscription" | "icon.advisor" | "icon.advisorClosed" | "icon.time" | "icon.omp" | "icon.esc" | "icon.ghost" | "icon.agents" | "icon.job" | "icon.cache" | "icon.cacheMiss" | "icon.input" | "icon.output" | "icon.throughput" | "icon.intelligence" | "icon.host" | "icon.session" | "icon.package" | "icon.warning" | "icon.rewind" | "icon.auto" | "icon.fast" | "icon.extensionSkill" | "icon.extensionTool" | "icon.extensionSlashCommand" | "icon.extensionMcp" | "icon.extensionRule" | "icon.extensionHook" | "icon.extensionPrompt" | "icon.extensionContextFile" | "icon.extensionInstruction" | "icon.vimNormal" | "icon.vimInsert" | "icon.vimVisual" | "icon.vimVisualLine" | "cmd.action" | "cmd.prompt" | "cmd.extension" | "cmd.settings" | "cmd.gear" | "cmd.shield" | "cmd.wave" | "cmd.compass" | "cmd.inbox" | "cmd.swap" | "cmd.expand" | "cmd.computer" | "cmd.eye" | "cmd.todo" | "cmd.stats" | "cmd.news" | "cmd.keyboard" | "cmd.export" | "cmd.clipboard" | "cmd.share" | "cmd.broadcast" | "cmd.globe" | "cmd.copy" | "cmd.plus" | "cmd.restart" | "cmd.eraser" | "cmd.trash" | "cmd.compress" | "cmd.vibrate" | "cmd.handoff" | "cmd.history" | "cmd.question" | "cmd.rocket" | "cmd.stethoscope" | "cmd.redo" | "cmd.bug" | "cmd.memory" | "cmd.pencil" | "cmd.folderMove" | "cmd.folderPlus" | "cmd.folderMinus" | "cmd.hammer" | "cmd.power" | "cmd.cart" | "icon.mic" | "icon.camera" | "thinking.minimal" | "thinking.low" | "thinking.medium" | "thinking.high" | "thinking.xhigh" | "thinking.max" | "thinking.autoPending" | "checkbox.checked" | "checkbox.unchecked" | "radio.selected" | "radio.unselected" | "format.bullet" | "format.dash" | "format.bracketLeft" | "format.bracketRight" | "md.quoteBorder" | "md.hrChar" | "md.bullet" | "md.colorSwatch" | "advisor.rail" | "skill.rail" | "lang.default" | "lang.typescript" | "lang.javascript" | "lang.python" | "lang.rust" | "lang.go" | "lang.java" | "lang.c" | "lang.cpp" | "lang.csharp" | "lang.ruby" | "lang.julia" | "lang.php" | "lang.swift" | "lang.kotlin" | "lang.shell" | "lang.html" | "lang.css" | "lang.json" | "lang.yaml" | "lang.markdown" | "lang.sql" | "lang.docker" | "lang.lua" | "lang.text" | "lang.env" | "lang.toml" | "lang.xml" | "lang.ini" | "lang.conf" | "lang.log" | "lang.csv" | "lang.tsv" | "lang.image" | "lang.pdf" | "lang.archive" | "lang.binary" | "chip.image" | "chip.video" | "chip.paste" | "tab.appearance" | "tab.model" | "tab.interaction" | "tab.context" | "tab.files" | "tab.shell" | "tab.tools" | "tab.memory" | "tab.tasks" | "tab.providers" | "tool.write" | "tool.edit" | "tool.bash" | "tool.ssh" | "tool.lsp" | "tool.gh" | "tool.webSearch" | "tool.exa" | "tool.browser" | "tool.eval" | "tool.debug" | "tool.mcp" | "tool.job" | "tool.launch" | "tool.task" | "tool.todo" | "tool.memory" | "tool.ask" | "tool.resolve" | "tool.review" | "tool.goal" | "tool.irc" | "tool.delete" | "tool.move";
+export type SymbolMap = Record<SymbolKey, string>;
+/**
+ * Icon vocabulary for slash-command autocomplete type indicators. Each name
+ * resolves through `Theme.cmd` to either a dedicated `cmd.*` symbol or an
+ * existing `icon.*` symbol shared with the rest of the UI.
+ */
+export type SlashCommandIconName = "action" | "prompt" | "extension" | "settings" | "gear" | "shield" | "wave" | "compass" | "inbox" | "swap" | "expand" | "computer" | "eye" | "todo" | "stats" | "news" | "keyboard" | "export" | "clipboard" | "share" | "broadcast" | "globe" | "copy" | "plus" | "restart" | "eraser" | "trash" | "compress" | "vibrate" | "handoff" | "history" | "question" | "rocket" | "stethoscope" | "redo" | "bug" | "memory" | "pencil" | "folderMove" | "folderPlus" | "folderMinus" | "hammer" | "power" | "cart" | "model" | "plan" | "prewalk" | "goal" | "pause" | "loop" | "session" | "jobs" | "gauge" | "context" | "agents" | "branch" | "tree" | "signIn" | "signOut" | "advisor" | "host" | "package" | "fast" | "voice" | "tools" | "rule" | "skill" | "mcp" | "pin";
+export declare const SYMBOL_PRESETS: Record<SymbolPreset, SymbolMap>;
+export type SpinnerType = "status" | "activity";
+export declare const SPINNER_FRAMES: Record<SymbolPreset, Record<SpinnerType, string[]>>;
+/**
+ * Shape accepted by `themeJson.symbols.spinnerFrames`. A flat array applies to
+ * both spinner types; an object lets a theme override `status` and/or
+ * `activity` independently. Anything not specified falls back to the symbol
+ * preset's default frames.
+ */
+export type SpinnerFramesOverride = string[] | {
+    status?: string[];
+    activity?: string[];
+};
+export declare function normalizeSpinnerFramesOverride(value: SpinnerFramesOverride | undefined): Partial<Record<SpinnerType, string[]>>;
+/**
+ * Get available symbol presets.
+ */
+export declare function getAvailableSymbolPresets(): SymbolPreset[];
+/**
+ * Check if a string is a valid symbol preset.
+ */
+export declare function isValidSymbolPreset(preset: string): preset is SymbolPreset;

package/dist/types/theme/theme-class.d.ts

@@ -0,0 +1,299 @@
+import { type ColorMode, type ThemeBg, type ThemeColor } from "./schema.js";
+import type { SessionAccentTheme } from "./session-color.js";
+import { type SlashCommandIconName, type SpinnerType, type SymbolKey, type SymbolPreset } from "./symbols.js";
+export declare class Theme {
+    #private;
+    private readonly mode;
+    private readonly symbolPreset;
+    /**
+     * Perceptual luma (0..1) of the status-line background — used to classify the
+     * theme light/dark. Undefined when it can't be resolved. Classified against the
+     * status line (the surface session accents render on) rather than the chat bubble
+     * (`userMessageBg`), which some themes (e.g. `porcelain`) style dark on an
+     * otherwise-light theme.
+     */
+    readonly statusLineLuminance: number | undefined;
+    constructor(fgColors: Record<ThemeColor, string | number>, bgColors: Record<ThemeBg, string | number>, mode: ColorMode, symbolPreset: SymbolPreset, symbolOverrides: Partial<Record<SymbolKey, string>>, spinnerFramesOverrides?: Partial<Record<SpinnerType, string[]>>);
+    /** True when the active theme has a light status-line background. */
+    get isLight(): boolean;
+    /**
+     * Surface luminance to size session accents against on light themes; undefined on
+     * dark themes so accents stay vivid. Pass straight to `getSessionAccentHex`.
+     */
+    get accentSurfaceLuminance(): number | undefined;
+    /**
+     * Get the resolved CSS hex string for a foreground theme color.
+     */
+    getColorHex(color: ThemeColor): string;
+    /**
+     * Get the resolved CSS hex string for a background theme color.
+     */
+    getBgHex(color: ThemeBg): string;
+    /**
+     * Get all foreground and background theme colors as CSS hex strings.
+     * Skips colors resolved to the default terminal color (unstyled).
+     */
+    getAllThemeColorHexes(): string[];
+    /**
+     * Get the most visually dominant theme colors as CSS hex strings — accent,
+     * border, success, error, warning, heading, link, diff markers, etc.
+     * These are the colors the session accent could visually clash with.
+     * Skips colors resolved to the default terminal color (unstyled).
+     */
+    getMajorThemeColorHexes(): string[];
+    /**
+     * Get the resolved CSS hex string for the theme's accent color.
+     */
+    getAccentColorHex(): string;
+    /**
+     * Theme-derived inputs for `getSessionAccentHex`: the accent hex whose
+     * OKLCH weight session accents adopt, the major colors they must not
+     * hue-collide with, and the light-theme surface luminance to contrast
+     * against.
+     */
+    get sessionAccentInputs(): SessionAccentTheme;
+    fg(color: ThemeColor, text: string): string;
+    /** Apply a foreground, replacing terminal-default tokens with the theme's contrast-safe fallback. */
+    fgResolved(color: ThemeColor, text: string): string;
+    bg(color: ThemeBg, text: string): string;
+    /**
+     * Apply a background fill that resumes after nested full/background resets.
+     *
+     * Composer rows contain styled text and cursor escapes; a normal background
+     * wrapper would otherwise stop at the first nested reset.
+     */
+    bgFill(color: ThemeBg, text: string): string;
+    /**
+     * Apply a foreground over a controlled background, choosing a contrast-safe
+     * fallback only when the theme token requests the terminal default and
+     * reapplying it after nested full/foreground resets.
+     */
+    fgOnBg(color: ThemeColor, background: ThemeBg, text: string): string;
+    bold(text: string): string;
+    italic(text: string): string;
+    underline(text: string): string;
+    strikethrough(text: string): string;
+    inverse(text: string): string;
+    getFgAnsi(color: ThemeColor): string;
+    getBgAnsi(color: ThemeBg): string;
+    /**
+     * Foreground ANSI for text rendered over a controlled theme background.
+     * Explicit theme colors win; terminal-default tokens become black or near-white.
+     */
+    getFgOnBgAnsi(color: ThemeColor, background: ThemeBg): string;
+    /**
+     * Foreground ANSI for text drawn **on top of** `fillColor` used as a solid
+     * background (e.g. a powerline chip). Picks near-black or near-white by the
+     * fill's perceived luminance (Rec. 601 luma) so the label stays legible on
+     * both bright and dark fills, across light and dark themes.
+     *
+     * Reads the RGB out of the already-resolved truecolor escape; when the fill
+     * is encoded as a 256-palette index (limited terminals) the RGB is
+     * unavailable, so it falls back to the theme `text` color.
+     */
+    getContrastFgAnsi(fillColor: ThemeColor): string;
+    getColorMode(): ColorMode;
+    /** Border color for a thinking/effort level name (`off`…`max`); unknown levels fall back to `thinkingOff`. */
+    getThinkingBorderColor(level: string): (str: string) => string;
+    getBashModeBorderColor(): (str: string) => string;
+    getPythonModeBorderColor(): (str: string) => string;
+    /**
+     * Get a symbol by key.
+     */
+    symbol(key: SymbolKey): string;
+    /**
+     * Get a symbol styled with a color.
+     */
+    styledSymbol(key: SymbolKey, color: ThemeColor): string;
+    /**
+     * Get the current symbol preset.
+     */
+    getSymbolPreset(): SymbolPreset;
+    get status(): {
+        success: string;
+        error: string;
+        warning: string;
+        info: string;
+        pending: string;
+        disabled: string;
+        enabled: string;
+        running: string;
+        shadowed: string;
+        aborted: string;
+        done: string;
+    };
+    get nav(): {
+        cursor: string;
+        selected: string;
+        expand: string;
+        collapse: string;
+        back: string;
+    };
+    get tree(): {
+        branch: string;
+        last: string;
+        vertical: string;
+        horizontal: string;
+        hook: string;
+    };
+    get progress(): {
+        filled: string;
+        empty: string;
+    };
+    get boxRound(): {
+        topLeft: string;
+        topRight: string;
+        bottomLeft: string;
+        bottomRight: string;
+        horizontal: string;
+        vertical: string;
+        cross: string;
+        teeDown: string;
+        teeUp: string;
+        teeRight: string;
+        teeLeft: string;
+    };
+    /**
+     * Dotted rules/verticals for transient selection outlines. Corners come from
+     * {@link boxRound} — Unicode has no rounded dotted corner glyphs.
+     */
+    get boxDotted(): {
+        horizontal: string;
+        vertical: string;
+    };
+    get boxSharp(): {
+        topLeft: string;
+        topRight: string;
+        bottomLeft: string;
+        bottomRight: string;
+        horizontal: string;
+        vertical: string;
+        cross: string;
+        teeDown: string;
+        teeUp: string;
+        teeRight: string;
+        teeLeft: string;
+    };
+    get sep(): {
+        powerline: string;
+        powerlineThin: string;
+        powerlineLeft: string;
+        powerlineRight: string;
+        powerlineThinLeft: string;
+        powerlineThinRight: string;
+        powerlineCapLeft: string;
+        block: string;
+        space: string;
+        asciiLeft: string;
+        asciiRight: string;
+        dot: string;
+        slash: string;
+        pipe: string;
+    };
+    get icon(): {
+        model: string;
+        plan: string;
+        prewalk: string;
+        goal: string;
+        pause: string;
+        loop: string;
+        folder: string;
+        worktree: string;
+        scratchFolder: string;
+        file: string;
+        git: string;
+        branch: string;
+        pr: string;
+        pin: string;
+        tokens: string;
+        context: string;
+        cost: string;
+        subscription: string;
+        advisor: string;
+        advisorClosed: string;
+        time: string;
+        omp: string;
+        esc: string;
+        ghost: string;
+        agents: string;
+        job: string;
+        cache: string;
+        cacheMiss: string;
+        input: string;
+        output: string;
+        throughput: string;
+        host: string;
+        session: string;
+        package: string;
+        warning: string;
+        rewind: string;
+        auto: string;
+        fast: string;
+        extensionSkill: string;
+        extensionTool: string;
+        extensionSlashCommand: string;
+        extensionMcp: string;
+        extensionRule: string;
+        extensionHook: string;
+        extensionPrompt: string;
+        extensionContextFile: string;
+        extensionInstruction: string;
+        vimNormal: string;
+        vimInsert: string;
+        vimVisual: string;
+        vimVisualLine: string;
+        mic: string;
+        camera: string;
+    };
+    /** Slash-command type-indicator glyphs for the autocomplete icon column. */
+    get cmd(): Record<SlashCommandIconName, string>;
+    get thinking(): {
+        minimal: string;
+        low: string;
+        medium: string;
+        high: string;
+        xhigh: string;
+        max: string;
+        autoPending: string;
+    };
+    get checkbox(): {
+        checked: string;
+        unchecked: string;
+    };
+    get radio(): {
+        selected: string;
+        unselected: string;
+    };
+    get format(): {
+        bullet: string;
+        dash: string;
+        bracketLeft: string;
+        bracketRight: string;
+    };
+    get md(): {
+        quoteBorder: string;
+        hrChar: string;
+        bullet: string;
+        colorSwatch: string;
+    };
+    /**
+     * Default spinner frames (status spinner).
+     */
+    get spinnerFrames(): string[];
+    /**
+     * Get spinner frames by type.
+     */
+    getSpinnerFrames(type?: SpinnerType): string[];
+    /**
+     * Get language icon for a language name.
+     * Maps common language names to their corresponding symbol keys.
+     */
+    getLangIcon(lang: string | undefined): string;
+    /**
+     * Language icon tinted with the language's brand color (see
+     * {@link LANG_BRAND_COLORS}). Falls back to the muted theme color for
+     * languages without a brand entry, and returns the bare (possibly empty)
+     * icon when the active symbol preset has none.
+     */
+    getLangIconStyled(lang: string | undefined): string;
+}

package/dist/types/theme/theme.d.ts

@@ -0,0 +1,111 @@
+import type { Terminal } from "../terminal.js";
+import type { ThemeColor } from "./schema.js";
+import type { SymbolPreset } from "./symbols.js";
+import type { Theme } from "./theme-class.js";
+export { getAvailableThemes, getAvailableThemesWithPaths, getThemeByName, type ThemeInfo } from "./loader.js";
+export { isValidThemeColor, type ThemeBg, type ThemeColor } from "./schema.js";
+export { getAvailableSymbolPresets, isValidSymbolPreset, type SpinnerType, type SymbolKey, type SymbolPreset, } from "./symbols.js";
+export { Theme } from "./theme-class.js";
+export { createHighlightStream, getEditorTheme, getMarkdownTheme, getSelectListTheme, getSettingsListTheme, getSymbolTheme, highlightCode, setMarkdownMermaidRendering, warmHighlighter, } from "./tui-adapters.js";
+/** Active theme; imports remain live across initialization, previews, and theme switches. */
+export declare var theme: Theme;
+type ThemeBinding = (value: Theme) => void;
+/** @internal Mirror assignments into bundled module bindings without replacing the UI change listener. */
+export declare function bindTheme(binding: ThemeBinding): () => void;
+/** Get the name of the currently active theme. */
+export declare function getCurrentThemeName(): string | undefined;
+/** Returns unstyled `text` before `initTheme()` assigns the global theme; use only for early-render paths. */
+export declare function fgOrPlain(color: ThemeColor, text: string, styledText?: string): string;
+export interface ThemeChangeEvent {
+    /** Preview/presentation-only changes should repaint live UI without replacing native scrollback. */
+    ephemeral?: boolean;
+}
+/** Initialize the active theme synchronously before the first terminal paint. */
+export declare function initThemeSync(symbolPreset?: SymbolPreset, colorBlindMode?: boolean, darkTheme?: string, lightTheme?: string): void;
+/** Ensure the module-local theme is initialized before synchronous component work. */
+export declare function ensureThemeSync(): void;
+/** Initialize the default theme only when no earlier prepaint initialized one. */
+export declare function ensureTheme(): Promise<void>;
+export declare function initTheme(enableWatcher?: boolean, symbolPreset?: SymbolPreset, colorBlindMode?: boolean, darkTheme?: string, lightTheme?: string): Promise<void>;
+export declare function setTheme(name: string, enableWatcher?: boolean): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+export declare function previewTheme(name: string, event?: ThemeChangeEvent): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Enable auto-detection mode, switching to the appropriate dark/light theme.
+ */
+export declare function enableAutoTheme(event?: ThemeChangeEvent): void;
+/**
+ * Update the theme mappings for auto-detection mode.
+ * When a dark/light mapping changes and auto-detection is active, re-evaluate the theme.
+ */
+export declare function setAutoThemeMapping(mode: "dark" | "light", themeName: string): void;
+/**
+ * Called when the terminal detects a dark/light appearance change.
+ * The terminal layer queries OSC 11 (background color) and computes luminance;
+ * Mode 2031 notifications trigger re-queries rather than providing the value directly.
+ */
+export declare function onTerminalAppearanceChange(mode: "dark" | "light", event?: ThemeChangeEvent): void;
+export declare function setThemeInstance(themeInstance: Theme): void;
+/**
+ * Set the symbol preset override, recreating the theme with the new preset.
+ */
+export declare function setSymbolPreset(preset: SymbolPreset): Promise<void>;
+/**
+ * Get the current symbol preset override.
+ */
+export declare function getSymbolPresetOverride(): SymbolPreset | undefined;
+/**
+ * Set color blind mode, recreating the theme with the new setting.
+ * When enabled, uses blue instead of green for diff additions.
+ */
+export declare function setColorBlindMode(enabled: boolean): Promise<void>;
+/**
+ * Get the current color blind mode setting.
+ */
+export declare function getColorBlindMode(): boolean;
+export declare function onThemeChange(callback: (event: ThemeChangeEvent) => void): () => void;
+/**
+ * Monotonic counter bumped on any theme-affecting change that should invalidate
+ * cached renders: theme swaps and reloads (including the invalid-theme dark
+ * fallback), theme previews, symbol-preset changes, and color-blind-mode
+ * changes — everything that routes through {@link notifyThemeChange}. Consumers
+ * key cached renders on it so the next render re-shapes their output.
+ */
+export declare function getThemeEpoch(): number;
+type MacOSAppearanceReprobeTerminal = Pick<Terminal, "appearance" | "onAppearanceChange" | "onAppearanceReport" | "onPrivateModeReport" | "refreshAppearance">;
+/**
+ * Fall back to native macOS appearance notifications when the terminal
+ * explicitly confirms that Mode 2031 notifications are unsupported.
+ *
+ * Native notifications provisionally repaint from the host appearance and
+ * synchronously trigger an OSC 11 probe, followed by a bounded burst of six
+ * retries. A changed terminal classification cancels the sequence; otherwise
+ * a confirmed terminal classification is restored at the validation deadline.
+ */
+export declare function startMacOSAppearanceReprobeFallback(terminal: MacOSAppearanceReprobeTerminal): () => void;
+export declare function stopThemeWatcher(): void;
+/**
+ * Get resolved theme colors as CSS-compatible hex strings.
+ * Used by HTML export to generate CSS custom properties.
+ */
+export declare function getResolvedThemeColors(themeName?: string): Promise<Record<string, string>>;
+/**
+ * Check if a theme is a "light" theme by analyzing its status-line background
+ * luminance. Loads theme JSON synchronously (built-in or custom file on disk)
+ * for callers in synchronous flows (settings migration, setup wizard).
+ */
+export declare function isLightTheme(themeName?: string): boolean;
+/**
+ * Get explicit export colors from theme JSON, if specified.
+ * Returns undefined for each color that isn't explicitly set.
+ */
+export declare function getThemeExportColors(themeName?: string): Promise<{
+    pageBg?: string;
+    cardBg?: string;
+    infoBg?: string;
+}>;

package/dist/types/theme/tui-adapters.d.ts

@@ -0,0 +1,30 @@
+import { HighlightStream as NativeHighlightStream } from "@oh-my-pi/pi-natives";
+import type { EditorTheme } from "../components/editor.js";
+import type { MarkdownTheme } from "../components/markdown.js";
+import type { SelectListTheme } from "../components/select-list.js";
+import type { SettingsListTheme } from "../components/settings-list.js";
+import type { SymbolTheme } from "../symbols.js";
+import type { SlashCommandIconName } from "./symbols.js";
+import type { Theme } from "./theme-class.js";
+/**
+ * Highlight code with syntax coloring based on file extension or language.
+ * Returns array of highlighted lines.
+ */
+export declare function highlightCode(code: string, lang?: string, highlightTheme?: Theme): string[];
+/** Create a stateful highlighter for progressive terminal rendering. */
+export declare function createHighlightStream(lang?: string, highlightTheme?: Theme): NativeHighlightStream | null;
+/** Warm native syntax grammars off-thread once per process. */
+export declare function warmHighlighter(): Promise<void>;
+export declare function getSymbolTheme(): SymbolTheme;
+export declare function setMarkdownMermaidRendering(enabled: boolean): void;
+export declare function getMarkdownTheme(): MarkdownTheme;
+export declare function getSelectListTheme(): SelectListTheme;
+/**
+ * Resolve the autocomplete type-indicator glyph for a slash command.
+ * Returns `undefined` when no theme is initialized or the active preset is
+ * ASCII (shared `icon.*` glyphs have ASCII forms, but a partially lettered
+ * icon column reads as noise), which collapses the column entirely.
+ */
+export declare function getSlashCommandTypeIcon(name: SlashCommandIconName): string | undefined;
+export declare function getEditorTheme(): EditorTheme;
+export declare function getSettingsListTheme(): SettingsListTheme;