@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/dist/integrations/pi/components/upstream/history/kill-ring.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Provenance: @earendil-works/pi-tui 0.85.1 (MIT), commit d981de1229ef899957bbe968bc8dcda02a21f477,
+ * packages/tui/src/kill-ring.ts.
+ * Modifications: Owned editor core or minimal editor-local helper subset; public imports, strict
+ * types, typed persistent-history hooks, and semantic border state. Public terminal runtime/exports
+ * remain shared and unchanged. See docs/architecture/history-editor-provenance.md.
+ * Deviations: persistent-history-owned-editor-boundary.
+ */
+/**
+ * Ring buffer for Emacs-style kill/yank operations.
+ *
+ * Tracks killed (deleted) text entries. Consecutive kills can accumulate
+ * into a single entry. Supports yank (paste most recent) and yank-pop
+ * (cycle through older entries).
+ */
+export declare class KillRing {
+    private ring;
+    /**
+     * Add text to the kill ring.
+     *
+     * @param text - The killed text to add
+     * @param opts - Push options
+     * @param opts.prepend - If accumulating, prepend (backward deletion) or append (forward deletion)
+     * @param opts.accumulate - Merge with the most recent entry instead of creating a new one
+     */
+    push(text: string, opts: {
+        prepend: boolean;
+        accumulate?: boolean;
+    }): void;
+    /** Get most recent entry without modifying the ring. */
+    peek(): string | undefined;
+    /** Move last entry to front (for yank-pop cycling). */
+    rotate(): void;
+    get length(): number;
+}

package/dist/integrations/pi/components/upstream/history/kill-ring.js

@@ -0,0 +1,51 @@
+/**
+ * Provenance: @earendil-works/pi-tui 0.85.1 (MIT), commit d981de1229ef899957bbe968bc8dcda02a21f477,
+ * packages/tui/src/kill-ring.ts.
+ * Modifications: Owned editor core or minimal editor-local helper subset; public imports, strict
+ * types, typed persistent-history hooks, and semantic border state. Public terminal runtime/exports
+ * remain shared and unchanged. See docs/architecture/history-editor-provenance.md.
+ * Deviations: persistent-history-owned-editor-boundary.
+ */
+/**
+ * Ring buffer for Emacs-style kill/yank operations.
+ *
+ * Tracks killed (deleted) text entries. Consecutive kills can accumulate
+ * into a single entry. Supports yank (paste most recent) and yank-pop
+ * (cycle through older entries).
+ */
+export class KillRing {
+    ring = [];
+    /**
+     * Add text to the kill ring.
+     *
+     * @param text - The killed text to add
+     * @param opts - Push options
+     * @param opts.prepend - If accumulating, prepend (backward deletion) or append (forward deletion)
+     * @param opts.accumulate - Merge with the most recent entry instead of creating a new one
+     */
+    push(text, opts) {
+        if (!text)
+            return;
+        if (opts.accumulate && this.ring.length > 0) {
+            const last = this.ring.pop();
+            this.ring.push(opts.prepend ? text + last : last + text);
+        }
+        else {
+            this.ring.push(text);
+        }
+    }
+    /** Get most recent entry without modifying the ring. */
+    peek() {
+        return this.ring.length > 0 ? this.ring[this.ring.length - 1] : undefined;
+    }
+    /** Move last entry to front (for yank-pop cycling). */
+    rotate() {
+        if (this.ring.length > 1) {
+            const last = this.ring.pop();
+            this.ring.unshift(last);
+        }
+    }
+    get length() {
+        return this.ring.length;
+    }
+}

package/dist/integrations/pi/components/upstream/history/printable-key.d.ts

@@ -0,0 +1 @@
+export declare function decodePrintableKey(data: string): string | undefined;

package/dist/integrations/pi/components/upstream/history/printable-key.js

@@ -0,0 +1,43 @@
+/**
+ * Provenance: @earendil-works/pi-tui 0.85.1 (MIT), commit d981de1229ef899957bbe968bc8dcda02a21f477,
+ * packages/tui/src/keys.ts.
+ * Modifications: Owned editor core or minimal editor-local helper subset; public imports, strict
+ * types, typed persistent-history hooks, and semantic border state. Public terminal runtime/exports
+ * remain shared and unchanged. See docs/architecture/history-editor-provenance.md.
+ * Deviations: persistent-history-owned-editor-boundary.
+ */
+import { decodeKittyPrintable } from "@earendil-works/pi-tui";
+const MODIFIERS = {
+    shift: 1,
+    alt: 2,
+    ctrl: 4,
+    super: 8,
+};
+const LOCK_MASK = 64 + 128;
+function parseModifyOtherKeysSequence(data) {
+    const match = data.match(/^\x1b\[27;(\d+);(\d+)~$/);
+    if (!match)
+        return null;
+    const modValue = parseInt(match[1], 10);
+    const codepoint = parseInt(match[2], 10);
+    return { codepoint, modifier: modValue - 1 };
+}
+function decodeModifyOtherKeysPrintable(data) {
+    const parsed = parseModifyOtherKeysSequence(data);
+    if (!parsed)
+        return undefined;
+    const modifier = parsed.modifier & ~LOCK_MASK;
+    if ((modifier & ~MODIFIERS.shift) !== 0)
+        return undefined;
+    if (!Number.isFinite(parsed.codepoint) || parsed.codepoint < 32)
+        return undefined;
+    try {
+        return String.fromCodePoint(parsed.codepoint);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function decodePrintableKey(data) {
+    return decodeKittyPrintable(data) ?? decodeModifyOtherKeysPrintable(data);
+}

package/dist/integrations/pi/components/upstream/history/text-helpers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Get the shared grapheme segmenter instance.
+ */
+export declare function getGraphemeSegmenter(): Intl.Segmenter;
+/**
+ * Get the shared word segmenter instance.
+ */
+export declare function getWordSegmenter(): Intl.Segmenter;
+export declare const cjkBreakRegex: RegExp;
+export declare const PUNCTUATION_REGEX: RegExp;
+/**
+ * Check if a character is whitespace.
+ */
+export declare function isWhitespaceChar(char: string): boolean;

package/dist/integrations/pi/components/upstream/history/text-helpers.js

@@ -0,0 +1,31 @@
+/**
+ * Provenance: @earendil-works/pi-tui 0.85.1 (MIT), commit d981de1229ef899957bbe968bc8dcda02a21f477,
+ * packages/tui/src/utils.ts.
+ * Modifications: Owned editor core or minimal editor-local helper subset; public imports, strict
+ * types, typed persistent-history hooks, and semantic border state. Public terminal runtime/exports
+ * remain shared and unchanged. See docs/architecture/history-editor-provenance.md.
+ * Deviations: persistent-history-owned-editor-boundary.
+ */
+// segmenters (shared instance)
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+const wordSegmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+/**
+ * Get the shared grapheme segmenter instance.
+ */
+export function getGraphemeSegmenter() {
+    return graphemeSegmenter;
+}
+/**
+ * Get the shared word segmenter instance.
+ */
+export function getWordSegmenter() {
+    return wordSegmenter;
+}
+export const cjkBreakRegex = /[\p{Script_Extensions=Han}\p{Script_Extensions=Hiragana}\p{Script_Extensions=Katakana}\p{Script_Extensions=Hangul}\p{Script_Extensions=Bopomofo}]/u;
+export const PUNCTUATION_REGEX = /[(){}[\]<>.,;:'"!?+\-=*/\\|&%^$#@~`]/;
+/**
+ * Check if a character is whitespace.
+ */
+export function isWhitespaceChar(char) {
+    return /\s/.test(char);
+}

package/dist/integrations/pi/components/upstream/history/undo-stack.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Provenance: @earendil-works/pi-tui 0.85.1 (MIT), commit d981de1229ef899957bbe968bc8dcda02a21f477,
+ * packages/tui/src/undo-stack.ts.
+ * Modifications: Owned editor core or minimal editor-local helper subset; public imports, strict
+ * types, typed persistent-history hooks, and semantic border state. Public terminal runtime/exports
+ * remain shared and unchanged. See docs/architecture/history-editor-provenance.md.
+ * Deviations: persistent-history-owned-editor-boundary.
+ */
+/**
+ * Generic undo stack with clone-on-push semantics.
+ *
+ * Stores deep clones of state snapshots. Popped snapshots are returned
+ * directly (no re-cloning) since they are already detached.
+ */
+export declare class UndoStack<S> {
+    private stack;
+    /** Push a deep clone of the given state onto the stack. */
+    push(state: S): void;
+    /** Pop and return the most recent snapshot, or undefined if empty. */
+    pop(): S | undefined;
+    /** Remove all snapshots. */
+    clear(): void;
+    updateSnapshots(update: (snapshot: S) => void): void;
+    get length(): number;
+}

package/dist/integrations/pi/components/upstream/history/undo-stack.js

@@ -0,0 +1,39 @@
+/**
+ * Provenance: @earendil-works/pi-tui 0.85.1 (MIT), commit d981de1229ef899957bbe968bc8dcda02a21f477,
+ * packages/tui/src/undo-stack.ts.
+ * Modifications: Owned editor core or minimal editor-local helper subset; public imports, strict
+ * types, typed persistent-history hooks, and semantic border state. Public terminal runtime/exports
+ * remain shared and unchanged. See docs/architecture/history-editor-provenance.md.
+ * Deviations: persistent-history-owned-editor-boundary.
+ */
+/**
+ * Generic undo stack with clone-on-push semantics.
+ *
+ * Stores deep clones of state snapshots. Popped snapshots are returned
+ * directly (no re-cloning) since they are already detached.
+ */
+export class UndoStack {
+    stack = [];
+    /** Push a deep clone of the given state onto the stack. */
+    push(state) {
+        this.stack.push(structuredClone(state));
+    }
+    /** Pop and return the most recent snapshot, or undefined if empty. */
+    pop() {
+        return this.stack.pop();
+    }
+    /** Remove all snapshots. */
+    clear() {
+        this.stack.length = 0;
+    }
+    updateSnapshots(update) {
+        this.stack = this.stack.map(snapshot => {
+            const copy = structuredClone(snapshot);
+            update(copy);
+            return copy;
+        });
+    }
+    get length() {
+        return this.stack.length;
+    }
+}

package/dist/integrations/pi/components/upstream/history/word-navigation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Options for word navigation functions.
+ * When omitted, uses the default Intl.Segmenter word segmentation.
+ */
+export interface WordNavigationOptions {
+    /** Custom segmenter returning word segments for the given text. */
+    segment?: (text: string) => Iterable<Intl.SegmentData>;
+    /** Predicate identifying atomic segments that should be treated as single units (e.g. paste markers). */
+    isAtomicSegment?: (segment: string) => boolean;
+}
+/**
+ * Find the cursor position after moving one word backward from `cursor` in `text`.
+ * Skips trailing whitespace, then stops at the next word/punctuation boundary.
+ *
+ * Pure function - does not mutate any state.
+ */
+export declare function findWordBackward(text: string, cursor: number, options?: WordNavigationOptions): number;
+/**
+ * Find the cursor position after moving one word forward from `cursor` in `text`.
+ * Skips leading whitespace, then stops at the next word/punctuation boundary.
+ *
+ * Pure function - does not mutate any state.
+ */
+export declare function findWordForward(text: string, cursor: number, options?: WordNavigationOptions): number;

package/dist/integrations/pi/components/upstream/history/word-navigation.js

@@ -0,0 +1,103 @@
+/**
+ * Provenance: @earendil-works/pi-tui 0.85.1 (MIT), commit d981de1229ef899957bbe968bc8dcda02a21f477,
+ * packages/tui/src/word-navigation.ts.
+ * Modifications: Owned editor core or minimal editor-local helper subset; public imports, strict
+ * types, typed persistent-history hooks, and semantic border state. Public terminal runtime/exports
+ * remain shared and unchanged. See docs/architecture/history-editor-provenance.md.
+ * Deviations: persistent-history-owned-editor-boundary.
+ */
+import { getWordSegmenter, isWhitespaceChar, PUNCTUATION_REGEX } from "./text-helpers.js";
+const wordSegmenter = getWordSegmenter();
+/**
+ * Find the cursor position after moving one word backward from `cursor` in `text`.
+ * Skips trailing whitespace, then stops at the next word/punctuation boundary.
+ *
+ * Pure function - does not mutate any state.
+ */
+export function findWordBackward(text, cursor, options) {
+    if (cursor <= 0)
+        return 0;
+    const textBeforeCursor = text.slice(0, cursor);
+    const segmentFn = options?.segment;
+    const isAtomic = options?.isAtomicSegment;
+    const segments = segmentFn ? [...segmentFn(textBeforeCursor)] : [...wordSegmenter.segment(textBeforeCursor)];
+    let newCursor = cursor;
+    // Skip trailing whitespace
+    while (segments.length > 0 &&
+        !isAtomic?.(segments[segments.length - 1]?.segment || "") &&
+        isWhitespaceChar(segments[segments.length - 1]?.segment || "")) {
+        newCursor -= segments.pop()?.segment.length || 0;
+    }
+    if (segments.length === 0)
+        return newCursor;
+    const last = segments[segments.length - 1];
+    if (isAtomic?.(last.segment)) {
+        // Skip one atomic segment.
+        newCursor -= last.segment.length;
+    }
+    else if (last.isWordLike) {
+        // Skip inside one word-like segment, preserving ASCII punctuation boundaries.
+        const segment = last.segment;
+        const matches = [...segment.matchAll(new RegExp(PUNCTUATION_REGEX, "g"))];
+        if (matches.length <= 0) {
+            newCursor -= segment.length;
+        }
+        else {
+            const lastMatch = matches[matches.length - 1];
+            newCursor -= segment.length - (lastMatch.index + lastMatch[0].length);
+        }
+    }
+    else {
+        // Skip non-word non-whitespace run (punctuation)
+        while (segments.length > 0 &&
+            !isAtomic?.(segments[segments.length - 1]?.segment || "") &&
+            !segments[segments.length - 1]?.isWordLike &&
+            !isWhitespaceChar(segments[segments.length - 1]?.segment || "")) {
+            newCursor -= segments.pop()?.segment.length || 0;
+        }
+    }
+    return newCursor;
+}
+/**
+ * Find the cursor position after moving one word forward from `cursor` in `text`.
+ * Skips leading whitespace, then stops at the next word/punctuation boundary.
+ *
+ * Pure function - does not mutate any state.
+ */
+export function findWordForward(text, cursor, options) {
+    if (cursor >= text.length)
+        return text.length;
+    const textAfterCursor = text.slice(cursor);
+    const segmentFn = options?.segment;
+    const isAtomic = options?.isAtomicSegment;
+    const segments = segmentFn ? segmentFn(textAfterCursor) : wordSegmenter.segment(textAfterCursor);
+    const iterator = segments[Symbol.iterator]();
+    let next = iterator.next();
+    let newCursor = cursor;
+    // Skip leading whitespace
+    while (!next.done && !isAtomic?.(next.value.segment) && isWhitespaceChar(next.value.segment)) {
+        newCursor += next.value.segment.length;
+        next = iterator.next();
+    }
+    if (next.done)
+        return newCursor;
+    if (isAtomic?.(next.value.segment)) {
+        // Skip one atomic segment.
+        newCursor += next.value.segment.length;
+    }
+    else if (next.value.isWordLike) {
+        // Skip inside one word-like segment, preserving ASCII punctuation boundaries.
+        newCursor += PUNCTUATION_REGEX.exec(next.value.segment)?.index ?? next.value.segment.length;
+    }
+    else {
+        // Skip non-word non-whitespace run (punctuation)
+        while (!next.done &&
+            !isAtomic?.(next.value.segment) &&
+            !next.value.isWordLike &&
+            !isWhitespaceChar(next.value.segment)) {
+            newCursor += next.value.segment.length;
+            next = iterator.next();
+        }
+    }
+    return newCursor;
+}

package/dist/integrations/pi/components/upstream/model-search.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Provenance: @earendil-works/pi-coding-agent 0.85.1 (MIT), commit d981de1229ef899957bbe968bc8dcda02a21f477,
+ * packages/coding-agent/src/modes/interactive/model-search.ts.
+ * Modifications: Mechanical source-synchronized port preserving pinned model search terms for stateful
+ * scoped-model filtering.
+ * Deviations: none.
+ */
+export interface ModelSearchItem {
+    id: string;
+    provider: string;
+    name?: string;
+}
+export declare function getModelSearchText(item: ModelSearchItem): string;
+/**
+ * The /model selector search should rank exact provider-prefixed queries before proxy-provider IDs
+ * like openrouter/openai/gpt-5, so keep the bare model ID out of the leading position.
+ */
+export declare function getModelSelectorSearchText(item: ModelSearchItem): string;

package/dist/integrations/pi/components/upstream/theme/theme-controller.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Provenance: @earendil-works/pi-coding-agent 0.85.1 (MIT), commit d981de1229ef899957bbe968bc8dcda02a21f477,
+ * packages/coding-agent/src/modes/interactive/theme/theme-controller.ts.
+ * Modifications: Source-synchronized controller port: renamed owner class, injected dependency-free
+ * settings/runtime ports, remapped private theme helpers to the public-backed A1 theme adapter, and
+ * added explicit disposal.
+ * Deviations: theme-controller-owned-boundaries, theme-controller-explicit-disposal.
+ */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type PiTerminalTheme, type PiTerminalThemeDetector, type PiThemeResult } from "./theme.js";
+export interface PiThemeRuntimePort extends PiTerminalThemeDetector {
+    invalidate(): void;
+    requestRender(force?: boolean): void;
+    setTerminalColorSchemeNotifications(enabled: boolean): void;
+    onTerminalColorSchemeChange(listener: (theme: PiTerminalTheme) => void): () => void;
+}
+export interface PiThemeSettingsPort {
+    getThemeSetting(): string | undefined;
+    setTheme(theme: string): void;
+    flush(): Promise<void>;
+}
+export declare class OwnedPiThemeController {
+    #private;
+    constructor(ui: PiThemeRuntimePort, settings: PiThemeSettingsPort, showError: (message: string) => void, onChanged: () => void);
+    rebindTui(): void;
+    applyFromSettings(): Promise<void>;
+    setThemeName(themeName: string, showError?: boolean): PiThemeResult;
+    setThemeInstance(theme: Theme): PiThemeResult;
+    preview(themeSettingOrName: string): void;
+    disableAutoSync(): void;
+    getTerminalTheme(): PiTerminalTheme;
+    dispose(): void;
+}

package/dist/integrations/pi/components/upstream/theme/theme-controller.js

@@ -0,0 +1,114 @@
+import { applyPiTheme, applyPiThemeInstance, detectPiTerminalBackgroundFromEnv, detectPiTerminalBackgroundTheme, detectPiTerminalThemeForAuto, parsePiAutoThemeSetting, resolvePiThemeSetting, } from "./theme.js";
+export class OwnedPiThemeController {
+    #ui;
+    #settings;
+    #showError;
+    #onChanged;
+    #terminalTheme = detectPiTerminalBackgroundFromEnv().theme;
+    #activeThemeName;
+    #autoSyncEnabled = false;
+    #terminalColorSchemeUnsubscribe;
+    constructor(ui, settings, showError, onChanged) {
+        this.#ui = ui;
+        this.#settings = settings;
+        this.#showError = showError;
+        this.#onChanged = onChanged;
+        this.#activeThemeName = resolvePiThemeSetting(this.#settings.getThemeSetting(), this.#terminalTheme);
+        applyPiTheme(this.#activeThemeName ?? this.#terminalTheme, true);
+        this.#bindTerminalColorSchemeListener();
+    }
+    rebindTui() {
+        this.#terminalColorSchemeUnsubscribe?.();
+        this.#bindTerminalColorSchemeListener();
+        this.#ui.setTerminalColorSchemeNotifications(this.#autoSyncEnabled);
+    }
+    async applyFromSettings() {
+        const themeSetting = this.#settings.getThemeSetting();
+        const autoTheme = parsePiAutoThemeSetting(themeSetting);
+        if (autoTheme) {
+            this.#terminalTheme = await detectPiTerminalThemeForAuto(this.#ui, 100);
+            this.#setAutoSync(true);
+            this.#applyThemeName(this.#terminalTheme === "light" ? autoTheme.lightTheme : autoTheme.darkTheme, true);
+            return;
+        }
+        this.#setAutoSync(false);
+        if (themeSetting !== undefined) {
+            this.#applyThemeName(themeSetting, true);
+            return;
+        }
+        const detection = await detectPiTerminalBackgroundTheme(this.#ui, 100);
+        this.#terminalTheme = detection.theme;
+        if (!this.#applyThemeName(detection.theme).success)
+            return;
+        if (detection.confidence === "high") {
+            this.#settings.setTheme(detection.theme);
+            await this.#settings.flush();
+        }
+    }
+    setThemeName(themeName, showError = false) {
+        this.#setAutoSync(false);
+        return this.#applyThemeName(themeName, showError);
+    }
+    setThemeInstance(theme) {
+        this.#setAutoSync(false);
+        const result = applyPiThemeInstance(theme);
+        this.#activeThemeName = result.name;
+        this.#notifyChanged();
+        return result;
+    }
+    preview(themeSettingOrName) {
+        const themeName = resolvePiThemeSetting(themeSettingOrName, this.#terminalTheme) ?? this.#activeThemeName;
+        if (!themeName)
+            return;
+        if (applyPiTheme(themeName, true).success) {
+            this.#ui.invalidate();
+            this.#ui.requestRender();
+        }
+    }
+    disableAutoSync() {
+        this.#setAutoSync(false);
+    }
+    getTerminalTheme() {
+        return this.#terminalTheme;
+    }
+    dispose() {
+        this.#terminalColorSchemeUnsubscribe?.();
+        this.#terminalColorSchemeUnsubscribe = undefined;
+        this.#setAutoSync(false);
+    }
+    #applyThemeName(themeName, showError = false) {
+        const result = applyPiTheme(themeName, true);
+        this.#activeThemeName = result.name;
+        this.#notifyChanged();
+        if (!result.success && showError) {
+            this.#showError(`Failed to load theme "${themeName}": ${result.error}\nFell back to dark theme.`);
+        }
+        return result;
+    }
+    #notifyChanged() {
+        this.#ui.invalidate();
+        this.#onChanged();
+    }
+    #setAutoSync(enabled) {
+        if (this.#autoSyncEnabled === enabled)
+            return;
+        this.#autoSyncEnabled = enabled;
+        this.#ui.setTerminalColorSchemeNotifications(enabled);
+    }
+    #bindTerminalColorSchemeListener() {
+        this.#terminalColorSchemeUnsubscribe = this.#ui.onTerminalColorSchemeChange(theme => this.#applyTerminalTheme(theme));
+    }
+    #applyTerminalTheme(terminalTheme) {
+        if (!this.#autoSyncEnabled)
+            return;
+        this.#terminalTheme = terminalTheme;
+        const autoTheme = parsePiAutoThemeSetting(this.#settings.getThemeSetting());
+        if (!autoTheme) {
+            this.#setAutoSync(false);
+            return;
+        }
+        const themeName = terminalTheme === "light" ? autoTheme.lightTheme : autoTheme.darkTheme;
+        if (themeName !== this.#activeThemeName)
+            this.#applyThemeName(themeName);
+    }
+}

package/dist/integrations/pi/components/upstream/theme/theme.d.ts

@@ -0,0 +1,61 @@
+import { Theme } from "@earendil-works/pi-coding-agent";
+import { type RgbColor } from "@earendil-works/pi-tui";
+export declare const PINNED_PI_LAYOUT: Readonly<{
+    readonly editorPaddingX: 0;
+    readonly outputPad: 1;
+    readonly autocompleteMaxVisible: 5;
+    readonly contentPaddingX: 1;
+    readonly messagePaddingY: 1;
+    readonly sectionSpacing: 1;
+    readonly selectorMaxVisible: 10;
+}>;
+export type PiTerminalTheme = "dark" | "light";
+export type PiThemeBackground = "selectedBg" | "userMessageBg" | "customMessageBg" | "toolPendingBg" | "toolSuccessBg" | "toolErrorBg";
+export type PiColorMode = "truecolor" | "256color";
+export interface PiThemeResult {
+    readonly success: boolean;
+    readonly name: string;
+    readonly error?: string;
+}
+export interface PiTerminalThemeDetection {
+    readonly theme: PiTerminalTheme;
+    readonly source: "terminal background" | "COLORFGBG" | "fallback";
+    readonly detail: string;
+    readonly confidence: "high" | "low";
+}
+export interface PiTerminalThemeDetector {
+    queryTerminalBackgroundColor(options: {
+        readonly timeoutMs: number;
+    }): Promise<RgbColor | undefined>;
+    queryTerminalColorScheme?(options: {
+        readonly timeoutMs: number;
+    }): Promise<PiTerminalTheme | undefined>;
+}
+export declare function ensurePiTheme(): Theme;
+export declare function piTheme(): Theme;
+export declare function currentPiThemeName(): string;
+export declare function applyPiTheme(name: string, enableWatcher?: boolean, mode?: PiColorMode): PiThemeResult;
+export declare function applyPiThemeInstance(theme: Theme): PiThemeResult;
+export declare function onPiThemeChange(listener: () => void): () => void;
+export declare function stopPiThemeWatcher(): void;
+export declare function loadPiTheme(name: string, mode?: PiColorMode): Theme;
+export declare function getAvailablePiThemes(): readonly {
+    readonly name: string;
+    readonly path: string;
+}[];
+export declare function parsePiAutoThemeSetting(setting: string | undefined): {
+    readonly lightTheme: string;
+    readonly darkTheme: string;
+} | undefined;
+export declare function resolvePiThemeSetting(setting: string | undefined, terminalTheme: PiTerminalTheme): string | undefined;
+export declare function detectPiTerminalBackgroundFromEnv(environment?: NodeJS.ProcessEnv): PiTerminalThemeDetection;
+export declare function detectPiTerminalBackgroundTheme(ui: PiTerminalThemeDetector, timeoutMs: number, environment?: NodeJS.ProcessEnv): Promise<PiTerminalThemeDetection>;
+export declare function detectPiTerminalThemeForAuto(ui: PiTerminalThemeDetector, timeoutMs: number, environment?: NodeJS.ProcessEnv): Promise<PiTerminalTheme>;
+/**
+ * Applies the theme the reader configured, as the engine does at startup. The
+ * setting is either a theme's name or the `light/dark` pair meaning "follow the
+ * terminal", and only the pair consults the terminal's own background. An
+ * unreadable or absent setting falls back to that detection, which is what the
+ * engine does with an unset theme.
+ */
+export declare function applyConfiguredPiTheme(setting: string | undefined): PiThemeResult;