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

package/dist/types/prompt/custom-editor.d.ts

@@ -0,0 +1,261 @@
+import type { ImageContent } from "@oh-my-pi/pi-ai";
+import { Editor, type EditorTextDecorationContext } from "../components/editor.js";
+import { type KeyId } from "../keys.js";
+import { TUI } from "../tui.js";
+import type { AppKeybinding } from "../app-keybindings.js";
+import { type SpellingFeatures } from "./macos-spelling.js";
+type ConfigurableEditorAction = Extract<AppKeybinding, "app.interrupt" | "app.clear" | "app.exit" | "app.suspend" | "app.display.reset" | "app.thinking.cycle" | "app.model.cycleForward" | "app.model.cycleBackward" | "app.model.select" | "app.model.selectTemporary" | "app.message.dequeue" | "app.retry" | "app.clipboard.pasteImage" | "app.clipboard.pasteTextRaw" | "app.clipboard.copyPrompt">;
+/** Max gap (ms) between two spaces for the later one to count as OS key auto-repeat rather than a
+ *  deliberate press. OS auto-repeat is fast; a deliberate tap (even a fast one) is slower. */
+export declare const SPACE_REPEAT_MAX_GAP_MS = 120;
+/** Two consecutive inter-space gaps are "mechanical" (machine-driven auto-repeat) when both are
+ *  within {@link SPACE_REPEAT_MAX_GAP_MS} and differ by no more than this — an absolute jitter floor
+ *  or, for slower repeat rates, {@link SPACE_REPEAT_JITTER_RATIO} of the smaller gap. OS key-repeat
+ *  is metronomic; a human smashing the bar is fast but irregular, so its deltas never stay this
+ *  steady. */
+export declare const SPACE_REPEAT_JITTER_MS = 18;
+export declare const SPACE_REPEAT_JITTER_RATIO = 0.35;
+/** Consecutive mechanical (fast + steady) deltas that confirm the space bar is held and start
+ *  recording. Needs a sustained metronomic cadence, so jittery smashing and deliberate taps never
+ *  reach it. */
+export declare const SPACE_HOLD_MECHANICAL_RUN = 2;
+/** Idle gap (ms) after the last repeated space that counts as the space bar being released, ending
+ *  the push-to-talk recording. Must comfortably exceed the OS key-repeat interval. */
+export declare const SPACE_HOLD_RELEASE_MS = 250;
+/**
+ * Extract image-or-other file paths from plain (un-bracketed) clipboard text.
+ * Mirrors {@link extractBracketedPastePaths} for terminals/handlers that
+ * already stripped the `\x1b[200~`…`\x1b[201~` markers (e.g. clipboard text
+ * read directly via `pbpaste`/PowerShell).
+ */
+export declare function extractPastePathsFromText(text: string): string[] | undefined;
+/**
+ * Same shape as {@link extractBracketedImagePastePaths} but operates on a
+ * payload that has already been stripped of the `\x1b[200~` / `\x1b[201~`
+ * markers — used by the assembled-paste router in {@link CustomEditor.handleInput}
+ * so split bracketed pastes get the same attachment-path detection as single-chunk ones.
+ *
+ * When the segment splitter fails (an unescaped space in a real path breaks
+ * its every-segment-is-a-path invariant), falls back to
+ * {@link extractWholeTextAttachmentPath}, so a dropped macOS screenshot
+ * (`Screenshot 2026-06-25 at 1.23.45 PM.png`) attaches as an image instead of
+ * degrading to literal text (#6578).
+ */
+export declare function extractImagePastePathsFromText(text: string): string[] | undefined;
+export declare function extractBracketedPastePaths(data: string): string[] | undefined;
+export declare function extractBracketedImagePastePaths(data: string): string[] | undefined;
+export declare function extractBracketedImagePastePath(data: string): string | undefined;
+/**
+ * Return a single previewable file path when `text` is exactly one explicit
+ * image (`.png`, `.jpg`/`.jpeg`, `.gif`, `.webp`) or video path. Used by the
+ * keybind-driven clipboard image paste path so a
+ * clipboard whose only payload is an image file (e.g. Finder `Cmd+C` on
+ * macOS) attaches the image instead of pasting the path as literal text.
+ *
+ * Two-stage detection:
+ *
+ * 1. Splitter pass (shared with the bracketed-paste handler) — handles
+ *    quoted paths, shell-escaped spaces, and unambiguous single tokens.
+ *    Returns the single previewable path when it parses cleanly; explicitly
+ *    returns `undefined` when the splitter found multiple segments (so
+ *    ambiguous multi-path clipboard text like `/tmp/a.png /tmp/b.png`
+ *    still falls through to the text fallback instead of being mis-loaded
+ *    as one giant path).
+ * 2. {@link extractWholeTextAttachmentPath} — only reached when the splitter
+ *    failed (every segment must look like an explicit path; an unescaped
+ *    space in a real path breaks that). This is what recovers macOS
+ *    screenshot filenames like
+ *    `/Users/me/Desktop/Screenshot 2026-06-25 at 1.23.45 PM.png`.
+ */
+export declare function extractImagePathFromText(text: string): string | undefined;
+/** A large text paste staged as a composer chip. `content` feeds the band card's snippet and
+ *  captions; the submit-time expansion (verbatim content or a wrapped block) lives in the
+ *  editor's atom table under `label`. */
+export interface TextAttachment {
+    n: number;
+    label: string;
+    content: string;
+    lineCount: number;
+    charCount: number;
+}
+/** One visible composer attachment, in band order (vision attachments first, then text pastes). */
+export type ComposerChipDescriptor = {
+    kind: "image" | "video";
+    n: number;
+    image: ImageContent;
+    link: string | undefined;
+} | {
+    kind: "paste";
+    n: number;
+    text: TextAttachment;
+};
+/**
+ * Custom editor that handles configurable app-level shortcuts for coding-agent.
+ */
+export declare class CustomEditor extends Editor {
+    #private;
+    imageLinks?: readonly (string | undefined)[];
+    /** Draft images pasted into the composer, consumed on submit. Co-located with
+     *  {@link imageLinks} so every piece of draft-image state lives on the editor. */
+    pendingImages: ImageContent[];
+    /** Per-image source links (file:// targets) parallel to {@link pendingImages};
+     *  `undefined` entries are images without a backing reference yet. */
+    pendingImageLinks: (string | undefined)[];
+    /** Large text pastes staged as compact chip tokens; expansion lives in the atom table.
+     *  Numbered by a per-draft monotonic counter so a deleted chip never recycles its number
+     *  (labels key the atom table). */
+    pendingTexts: TextAttachment[];
+    /** Host-wired producer of per-image `file://` links (session blob store); drives clickable
+     *  chip tokens for restored drafts (esc-esc, `/tree`, branch). */
+    draftImageLinkMaterializer?: (images: readonly ImageContent[]) => Promise<(string | undefined)[] | undefined>;
+    /**
+     * The host {@link TUI}, captured when a plugin constructs this editor through
+     * the upstream-pi `(tui, theme, keybindings)` convention. Undefined for omp's
+     * own `new CustomEditor(theme)` callers (they drive repaints through the
+     * interactive-mode wiring instead). Plugins that call `this.tui.requestRender()`
+     * in their overrides read it here (issue #4766).
+     */
+    tui?: TUI;
+    /**
+     * Accept both the omp constructor convention — `new CustomEditor(theme)` —
+     * and the upstream-pi `Editor` convention — `new Editor(tui, theme, keybindings)`
+     * — that {@link ExtensionUIContext.setEditorComponent}'s factory contract
+     * advertises `(tui, theme, keybindings)`. Plugins written against upstream pi
+     * subclass `CustomEditor`/`Editor` and forward `super(tui, theme, keybindings)`;
+     * without this shim the `TUI` lands in the `theme` slot and every render throws
+     * `undefined is not an object (evaluating 'this.#theme.symbols.boxRound')`
+     * (issue #4766). We locate the real {@link EditorTheme} among the args by shape
+     * (it carries `symbols`/`borderColor`) rather than by position, and capture a
+     * leading {@link TUI} so plugin overrides calling `this.tui.requestRender()`
+     * keep working.
+     */
+    constructor(...args: readonly unknown[]);
+    /** Independently configure typo detection, word autocomplete, and autocorrect. */
+    setSpellingFeatures(features: SpellingFeatures): void;
+    /** Clear the composer draft: optionally commit `historyText` to history, then
+     *  reset the editor text and all pending draft-image state. The shared tail of
+     *  every "message submitted" path; pass no argument for a plain discard. */
+    clearDraft(historyText?: string): void;
+    /** Preserve a canceled draft in local navigation, then clear the composer. */
+    clearDraftForRecall(): void;
+    restoreHistoryState(restore?: () => void): void;
+    /** Replace the composer draft with a restored historical prompt: re-attaches the message's
+     *  images, collapses stored `[Image #N, WxH]` markers back into compact chip tokens (so the
+     *  chips band and atomic deletion return), and re-materializes `file://` links so the tokens
+     *  are clickable again instead of degrading to dead text (esc-esc branch, `/tree`). */
+    setDraft(text: string, images?: readonly ImageContent[]): void;
+    /** Set restored text with image, skill, and model references collapsed into atomic chips.
+     *  Leaves pending image/text state untouched — callers own that. */
+    setCollapsedText(text: string): void;
+    /**
+     * Host-owned skill registry probe: the SKILL.md path for a registered skill, else
+     * `undefined`. Only registered skills collapse into chips — an unknown `/skill:<name>`
+     * stays literal text — and the path makes the chip a clickable link. Startup defaults
+     * to "none known".
+     */
+    skillFilePath: (name: string) => string | undefined;
+    /** Host-owned model probe: maps a mentionable selector to its display chip label. */
+    modelMentionLabel: (selector: string) => string | undefined;
+    /** Host-owned session probe: maps a persisted model pseudonym back to its selector. */
+    modelMentionSelector: (agent: string) => string | undefined;
+    /**
+     * Late-bound OSC 8 file link renderer. Startup stays plain until the full
+     * interactive graph supplies the settings-aware implementation.
+     */
+    fileHyperlink: (filePath: string, text: string) => string;
+    /** Stage `content` as a text-attachment chip: inserts the compact token at the cursor and
+     *  registers `expansion` (default: the content itself) in the atom table for submit. */
+    insertTextAttachment(content: string, expansion?: string): void;
+    /** Cached read-only attachments whose chip token remains in the buffer.
+     * Deleting a token hides its chip and drops the attachment from submission. */
+    composerChips(): readonly ComposerChipDescriptor[];
+    /** Treat image/paste references — compact chip tokens and bracketed markers alike — as
+     *  indivisible: a stray backspace deletes the whole token instead of corrupting it. */
+    atomicTokenPattern: RegExp;
+    /** Magic-keyword shimmer cadence — drives one editor repaint every 70 ms while
+     *  a keyword is on screen and the prompt is focused. ~14 frames/s is smooth
+     *  without flooding the renderer. */
+    static readonly SHIMMER_FRAME_MS = 70;
+    /** Time for the gradient to sweep one full cycle across each keyword. */
+    static readonly SHIMMER_PERIOD_MS = 1800;
+    /** Decorate magic keywords, attachments, and the queue-composer header/list markers.
+     *  Queue shorthand reserves its first logical line as a dim `Queueing` label; sequential
+     *  item markers use the accent color so separate follow-ups remain visible while composing. */
+    decorateText: (text: string, context: EditorTextDecorationContext) => string;
+    /** Optional test override for the magic-keyword shimmer gate. */
+    magicKeywordsEnabledOverride: boolean | undefined;
+    /**
+     * Host-owned setting reader. Startup defaults to enabled without loading the
+     * settings graph; InteractiveMode replaces this with the live session setting.
+     */
+    magicKeywordsEnabled: () => boolean;
+    /**
+     * Late-bound OSC hyperlink renderer. Startup stays plain until the full
+     * interactive graph supplies the settings-aware implementation.
+     */
+    imageReferenceHyperlink: (label: string, index: number, imageLinks: readonly (string | undefined)[] | undefined, renderLabel: (text: string) => string) => string;
+    /** Bind the host's render request callback. Idempotent — the host wires this
+     *  once after construction (and again after `setEditorComponent` swaps the
+     *  editor). Passing `undefined` clears any pending frame. */
+    setShimmerRepaintHandler(handler: (() => void) | undefined): void;
+    onEscape?: () => void;
+    onClear?: () => void;
+    onExit?: () => void;
+    onDisplayReset?: () => void;
+    onCycleThinkingLevel?: () => void;
+    onCycleModelForward?: () => void;
+    onCycleModelBackward?: () => void;
+    onSelectModel?: () => void;
+    onSuspend?: () => void;
+    onSelectModelTemporary?: () => void;
+    /** Called when the configured copy-prompt shortcut is pressed. */
+    onCopyPrompt?: () => void;
+    /** Called when the configured image-paste shortcut is pressed. */
+    onPasteImage?: () => Promise<boolean>;
+    /** Called when a bracketed paste contains one or more image or video file paths. */
+    onPasteImagePath?: (path: string) => void | Promise<void>;
+    /** Called when the configured raw text-paste shortcut is pressed. */
+    onPasteTextRaw?: () => void;
+    /** Called when the configured dequeue shortcut is pressed. */
+    onDequeue?: () => void;
+    /** Called when the configured retry shortcut is pressed. */
+    onRetry?: () => void;
+    /** Called when Caps Lock is pressed. */
+    onCapsLock?: () => void;
+    /** Called when left-arrow is pressed while the editor is empty (cursor necessarily at start). */
+    onLeftAtStart?: () => void;
+    /** Fired when a sustained space-bar hold is recognized — the push-to-talk STT start. The
+     *  optimistically-typed spaces have already been deleted by the time this runs. */
+    onSpaceHoldStart?: () => void;
+    /** Fired when the held space bar is released (detected as an idle gap with no further repeated
+     *  spaces) — the push-to-talk STT stop. */
+    onSpaceHoldEnd?: () => void;
+    /** Gate for the space-hold gesture. Returns false to keep the space bar inserting spaces
+     *  normally; wired to `stt.enabled` so disabling STT restores plain space behavior. */
+    sttHoldEnabled?: () => boolean;
+    setActionKeys(action: ConfigurableEditorAction, keys: KeyId[]): void;
+    /**
+     * Register a custom key handler. Extensions use this for shortcuts.
+     */
+    setCustomKeyHandler(key: KeyId, handler: () => void): void;
+    /**
+     * Remove a custom key handler.
+     */
+    removeCustomKeyHandler(key: KeyId): void;
+    /**
+     * Clear all custom key handlers.
+     */
+    clearCustomKeyHandlers(): void;
+    handleInput(data: string): void;
+    /**
+     * Route a keystroke through the base text-editor pipeline only, skipping the
+     * editor-scoped shortcut interception in {@link handleInput}. Used when the
+     * editor is mounted for draft editing beneath another focused surface — e.g.
+     * an Ask dialog opened over a non-empty prompt — so finishing or submitting
+     * the draft cannot fire an editor-slot shortcut that clears
+     * `editorContainer` and orphans the overlay. Only text editing, cursor
+     * movement, submission, and the clear action reach the buffer.
+     */
+    handleDraftEdit(data: string): void;
+}
+export {};

package/dist/types/prompt/editor-top-gap.d.ts

@@ -0,0 +1,18 @@
+import type { Component } from "../index.js";
+/** Set the process-wide editor gap layout. */
+export declare function setEditorGapComposerShape(shape: string): void;
+/**
+ * One-line top margin between the working/status HUD row and the editor.
+ * The band composer's status band is designed to sit flush under the working
+ * row, so the gap collapses there — but only while that row actually rendered
+ * content (the loader and idle title bring their own leading blank). An empty
+ * status row keeps the gap so the band never sits flush against the
+ * transcript. Shape and row state are read at render time, so runtime changes
+ * apply immediately.
+ */
+export declare class EditorTopGap implements Component {
+    readonly statusRowOccupied: () => boolean;
+    /** @param statusRowOccupied Whether the status/working row directly above rendered lines this frame. */
+    constructor(statusRowOccupied: () => boolean);
+    render(_width: number): readonly string[];
+}

package/dist/types/prompt/emoji-autocomplete.d.ts

@@ -0,0 +1,16 @@
+import type { AutocompleteItem } from "../index.js";
+export declare function getEmojiSuggestions(textBeforeCursor: string): {
+    items: AutocompleteItem[];
+    prefix: string;
+} | null;
+export declare function applyEmojiCompletion(lines: string[], cursorLine: number, cursorCol: number, item: AutocompleteItem, prefix: string): {
+    lines: string[];
+    cursorLine: number;
+    cursorCol: number;
+};
+export declare function tryEmojiInlineReplace(textBeforeCursor: string): {
+    replaceLen: number;
+    insert: string;
+} | null;
+export declare function isEmojiPrefix(prefix: string): boolean;
+export declare function expandEmoticons(text: string): string;

package/dist/types/prompt/github-ref-autocomplete.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Autocomplete for GitHub issue/PR references typed as `#<number>` (e.g. `#3164`).
+ *
+ * Mirrors the `@` file-reference and `scheme://` internal-url conventions: the
+ * token is rewritten to an internal URL (`pr://3164` or `issue://3164`) plus a
+ * trailing space, and the existing tool-mediated pipeline (the `read` tool →
+ * InternalUrlRouter → `gh`) resolves it from the session cwd's git remote.
+ *
+ * No network at suggestion time — candidates are generated locally. GitHub
+ * shares the issue/PR number space and there is no cheap way to tell which a
+ * given number is while typing, so both a PR and an Issue candidate are offered
+ * by default. Naming the type first (`pr #3164` / `issue #3164`) constrains the
+ * candidates to that kind. Anything that is not a standalone `#<number>` token
+ * keeps falling through to the existing prompt-action menu.
+ */
+import type { AutocompleteItem } from "../index.js";
+export interface GithubRefContext {
+    /** Text to replace on accept: `#3164`, or `pr #3164` when a qualifier precedes it. */
+    prefix: string;
+    /** Type the user named (`pr`/`pull` → `pr`, `issue` → `issue`), or null to offer both. */
+    qualifier: "pr" | "issue" | null;
+    /** The numeric reference, e.g. `3164`. */
+    number: string;
+}
+export declare function getGithubRefContext(textBeforeCursor: string): GithubRefContext | null;
+/**
+ * Suggestions for a `#<number>` token. Both kinds are offered unless the user
+ * named a type (`pr #3164` / `issue #3164`), in which case only that kind is
+ * offered. Returns `null` when the text before the cursor is not a standalone
+ * `#<number>` token.
+ */
+export declare function getGithubRefSuggestions(textBeforeCursor: string): {
+    items: AutocompleteItem[];
+    prefix: string;
+} | null;

package/dist/types/prompt/gradient-highlight.d.ts

@@ -0,0 +1,32 @@
+/** A gradient keyword highlighter.
+ *
+ * - `resetTo` is the SGR foreground sequence re-emitted after each painted
+ *   keyword so surrounding text keeps its color; it defaults to a plain
+ *   foreground reset (editor / default-colored text).
+ * - `phase` ∈ [0, 1) rotates the gradient stops cyclically; pass `Date.now()`-
+ *   derived values to animate a shimmer. Defaults to `0` (the static
+ *   sent-bubble palette). */
+export type KeywordHighlighter = (text: string, resetTo?: string, phase?: number) => string;
+/** Declarative spec for {@link createGradientHighlighter}. */
+export interface GradientHighlightSpec {
+    /** Cheap, stateless presence probe used to skip the boundary regex on most lines. Must be non-global. */
+    probe: RegExp;
+    /** Global, word-bounded match regex walked by `.replace`. */
+    highlight: RegExp;
+    /** Number of color stops swept across the gradient. */
+    stops: number;
+    /** Maps a normalized position `t` in [0, 1) to an HSL hue in degrees. */
+    hue: (t: number) => number;
+    /** HSL saturation percentage. Default 90. */
+    saturation?: number;
+    /** HSL lightness percentage. Default 62. */
+    lightness?: number;
+}
+/**
+ * Build a stateless highlighter that paints each standalone match of `highlight`
+ * with a smooth HSL gradient for editor display. The returned function adds only
+ * zero-width SGR escapes — the visible width is unchanged — and returns the input
+ * untouched when `probe` does not match. The palette is compiled lazily and
+ * memoized per active color mode.
+ */
+export declare function createGradientHighlighter(spec: GradientHighlightSpec): KeywordHighlighter;

package/dist/types/prompt/image-format.d.ts

@@ -0,0 +1,4 @@
+/** Normalize a safe sidecar extension for image display files. */
+export declare function normalizeBlobExtension(extension: string | undefined): string | undefined;
+/** Resolve a safe display-file extension from an image MIME type. */
+export declare function blobExtensionForImageMimeType(mimeType: string | undefined): string | undefined;

package/dist/types/prompt/image-references.d.ts

@@ -0,0 +1,26 @@
+import type { ImageContent } from "@oh-my-pi/pi-ai";
+/** Materialized image destination returned by the host blob writer. */
+interface ImageBlobResult {
+    displayPath: string;
+}
+/** Cached probe result for a draft image: dimensions, `null` (probe failed), or `undefined`
+ *  (never probed). */
+export declare function cachedImageDimensions(image: ImageContent): {
+    width: number;
+    height: number;
+} | null | undefined;
+/** Record a probe result for a draft image (see {@link cachedImageDimensions}). */
+export declare function setCachedImageDimensions(image: ImageContent, dims: {
+    width: number;
+    height: number;
+} | null): void;
+type ImageBlobWriter = (data: Buffer, options?: {
+    extension?: string;
+}) => Promise<ImageBlobResult>;
+type ImageBlobWriterSync = (data: Buffer, options?: {
+    extension?: string;
+}) => ImageBlobResult;
+export declare function imageReferenceHyperlink(label: string, index: number, imageLinks: readonly (string | undefined)[] | undefined, renderLabel: (text: string) => string): string;
+export declare function materializeImageReferenceLinks(images: readonly ImageContent[] | undefined, putBlob: ImageBlobWriter): Promise<(string | undefined)[] | undefined>;
+export declare function materializeImageReferenceLinksSync(images: readonly ImageContent[] | undefined, putBlob: ImageBlobWriterSync): (string | undefined)[] | undefined;
+export {};

package/dist/types/prompt/interactive-context-helpers.d.ts

@@ -0,0 +1,43 @@
+/** Shared assistant transcript construction and model-authored link caching. */
+import type { AssistantMessage, Model } from "@oh-my-pi/pi-ai";
+import type { ImageBudget } from "../components/image.js";
+import type { AssistantThinkingRenderer } from "../chat/extension-types.js";
+import { AssistantMessageComponent } from "../chat/assistant-message.js";
+/** Session display capabilities supplied unchanged by the interactive host. */
+export interface AssistantMessageSession {
+    readonly model?: Model;
+    readonly extensionRunner?: {
+        getAssistantThinkingRenderers(): readonly AssistantThinkingRenderer[];
+    };
+}
+/** Host state required to construct and refresh assistant transcript segments. */
+export interface AssistantMessageHost {
+    readonly viewSession: AssistantMessageSession;
+    readonly effectiveHideThinkingBlock: boolean;
+    readonly proseOnlyThinking: boolean;
+    readonly assistantImagesVisible: boolean;
+    readonly hideToolActivity: boolean;
+    readonly toolOutputExpanded: boolean;
+    readonly ui: {
+        requestRender(): void;
+        readonly imageBudget: ImageBudget;
+    };
+    resolveAssistantMessageLinks(texts: readonly string[]): Promise<ReadonlyMap<string, string>>;
+}
+/**
+ * Resolve and cache the current session's model-authored prose links. Existing
+ * entries remain available to synchronous transcript rebuilds; links present in
+ * this batch are replaced atomically so missing resources cannot retain a stale
+ * destination.
+ */
+export declare function refreshAssistantMessageLinkTargets(ctx: AssistantMessageHost, messages: readonly AssistantMessage[]): Promise<ReadonlyMap<string, string>>;
+/** Current resolved destinations for synchronous component construction. */
+export declare function getAssistantMessageLinkTargets(ctx: AssistantMessageHost): ReadonlyMap<string, string>;
+/** Limit a session snapshot to destinations authored by one rendered segment. */
+export declare function assistantMessageLinkTargets(message: AssistantMessage, targets: ReadonlyMap<string, string>): ReadonlyMap<string, string>;
+/**
+ * Construct an {@link AssistantMessageComponent} wired to the live context's
+ * thinking/image settings. `message` is omitted for the streaming placeholder
+ * component and supplied when rendering a persisted turn.
+ */
+export declare function createAssistantMessageComponent(ctx: AssistantMessageHost, message?: AssistantMessage, linkTargets?: ReadonlyMap<string, string>): AssistantMessageComponent;

package/dist/types/prompt/internal-url-autocomplete.d.ts

@@ -0,0 +1,56 @@
+import type { AutocompleteItem } from "../index.js";
+/** Lazy runtime capabilities supplied by the internal URL host. */
+export interface InternalUrlCompletionHost {
+    completionSchemes(): string[];
+    resolveCompletions(scheme: string, query: string, context: InternalUrlCallerContext & {
+        signal?: AbortSignal;
+    }): Promise<readonly {
+        value: string;
+        label?: string;
+        description?: string;
+    }[] | null | undefined>;
+}
+/** Install the runtime URL completion capabilities. */
+export declare function setInternalUrlCompletionHost(host: InternalUrlCompletionHost): void;
+export interface InternalUrlContext {
+    /** Lowercased scheme (e.g. `local`). */
+    scheme: string;
+    /** Text typed after the slashes so far (host + path); may be empty. */
+    query: string;
+    /** Exact buffer token from its boundary to the cursor (the completion prefix). */
+    token: string;
+}
+/**
+ * Detect a completable internal-url token immediately before the cursor.
+ * Returns `null` when the text is not a `scheme://` token whose scheme is
+ * registered with a completion-capable handler.
+ */
+export declare function extractInternalUrlContext(textBeforeCursor: string): InternalUrlContext | null;
+/** Caller binding shared by tool execution and prompt completion. */
+export interface InternalUrlCallerContext {
+    cwd?: string;
+    sessionFile?: string;
+    sessionId?: string;
+}
+/**
+ * Suggestions for the internal-url token ending at the cursor, or `null` when
+ * the text is not such a token or no candidate matches the typed query.
+ * The optional lazy caller binding overrides cwd and is read only after
+ * recognizing an internal-URL token.
+ */
+export declare function getInternalUrlSuggestions(textBeforeCursor: string, cwd?: string, signal?: AbortSignal, getCaller?: () => InternalUrlCallerContext): Promise<{
+    items: AutocompleteItem[];
+    prefix: string;
+} | null>;
+/** Whether `prefix` (the token a completion was offered for) is an internal-url token. */
+export declare function isInternalUrlPrefix(prefix: string): boolean;
+/**
+ * Replace the internal-url token with the selected candidate, appending a
+ * trailing space (matching `@` file-reference behavior) so the user can keep
+ * typing.
+ */
+export declare function applyInternalUrlCompletion(lines: string[], cursorLine: number, cursorCol: number, item: AutocompleteItem, prefix: string): {
+    lines: string[];
+    cursorLine: number;
+    cursorCol: number;
+};

package/dist/types/prompt/macos-spelling.d.ts

@@ -0,0 +1,44 @@
+import * as native from "@oh-my-pi/pi-natives";
+import type { EditorInlineReplacement, EditorTextAssistProvider, EditorWordReplacements } from "../components/editor.js";
+/** Independently switchable macOS prose-assistance features. */
+export interface SpellingFeatures {
+    typoDetection: boolean;
+    autocomplete: boolean;
+    autocorrect: boolean;
+}
+/** Logical source location for one rendered editor segment. */
+export interface SpellingDecorationContext {
+    editorText: string;
+    lines: readonly string[];
+    line: number;
+    startCol: number;
+}
+/** Native spelling operations used by {@link MacOSSpellingProvider}. */
+export interface SpellingBackend {
+    isAvailable(): boolean;
+    checkSpelling(text: string): Promise<readonly native.SpellingRange[]>;
+    completeWord(text: string, start: number, length: number): Promise<readonly string[]>;
+    autocorrectWord(text: string, start: number, length: number): Promise<string | null>;
+    spellingGuesses(text: string, start: number, length: number): Promise<readonly string[]>;
+}
+/**
+ * Bridges Apple's spelling service into the editor's separate typo,
+ * word-completion, and autocorrection paths.
+ */
+export declare class MacOSSpellingProvider implements EditorTextAssistProvider {
+    #private;
+    private readonly backend;
+    /** Invoked when an asynchronous spelling result can change rendered output. */
+    onUpdate: (() => void) | undefined;
+    constructor(backend?: SpellingBackend, styledUnderlines?: boolean);
+    /** Apply all three independent feature gates and invalidate rendered typo ranges. */
+    setFeatures(features: SpellingFeatures): void;
+    /** Add red undercurls to misspellings while preserving visible text width. */
+    decorateTypos(text: string, context: SpellingDecorationContext, decorate?: (span: string) => string): string;
+    /** Return the cached macOS completion suffix for the word ending at the cursor. */
+    getWordCompletion(lines: string[], cursorLine: number, cursorCol: number): string | null;
+    /** Return the confident macOS correction after a completed prose word. */
+    tryAutocorrect(lines: string[], cursorLine: number, cursorCol: number): Promise<EditorInlineReplacement | null>;
+    /** Return macOS replacement guesses for the misspelled word at the cursor. */
+    getWordReplacements(lines: string[], cursorLine: number, cursorCol: number): Promise<EditorWordReplacements | null>;
+}

package/dist/types/prompt/magic-keyword-boundary.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Build a case-sensitive magic-keyword matcher for prose punctuation boundaries.
+ *
+ * Sentence punctuation and quotes may touch the keyword, but letters, digits,
+ * underscores, slashes, backslashes, hyphens, file-extension dots, symbol
+ * references (`foo::keyword`), and immediate call parentheses (`keyword()`)
+ * keep the occurrence embedded in code rather than prose.
+ */
+export declare function magicKeywordRegex(keyword: string, flags?: string): RegExp;

package/dist/types/prompt/magic-keywords.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Gradient-highlight every magic keyword ("ultrathink", "orchestrate",
+ * "workflowz") that appears as standalone prose, skipping any occurrence inside a
+ * code block, inline code span, or XML/HTML section. Each highlighter paints its
+ * own keyword with its own gradient, so chaining is order-independent — the
+ * earlier passes only inject zero-width SGR escapes (no backticks or angle
+ * brackets), which never confuse the later passes' markdown masking.
+ *
+ * `resetTo` is the SGR foreground sequence restored after each painted keyword;
+ * pass the surrounding text color when decorating already-colored content (e.g.
+ * a themed message bubble) so the gradient does not bleed into the rest of the
+ * line. Defaults to a plain foreground reset for default-colored editor text.
+ *
+ * `phase` ∈ [0, 1) cyclically rotates each gradient — the editor passes a
+ * `Date.now()`-derived value to animate a Claude-Code-style shimmer while a
+ * keyword is on screen and the prompt is focused; sent message bubbles omit it
+ * to keep the static gradient.
+ */
+export declare function highlightMagicKeywords(text: string, resetTo?: string, phase?: number): string;
+/**
+ * Cheap test for "does this text contain any magic keyword as standalone prose?".
+ * Short-circuits on a substring probe before paying for the markdown-aware
+ * prose check, so the common "no keyword in buffer" path is just three
+ * `String#indexOf`s. Used by the live editor to gate the shimmer timer.
+ */
+export declare function hasMagicKeyword(text: string): boolean;

package/dist/types/prompt/markdown-prose.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Return a copy of `text` with identical length (indices map 1:1) where every
+ * character inside a non-prose region is replaced by a space. Non-prose regions
+ * are markdown fenced code blocks, inline code spans, and HTML/XML tags together
+ * with the content they enclose. Newlines are preserved. Text with no construct
+ * that could open such a region is returned unchanged.
+ */
+export declare function maskNonProse(text: string): string;
+/**
+ * Whether `text` contains a standalone keyword match (per the non-global,
+ * word-bounded `word` regex) that lives in prose rather than inside a code
+ * block, inline code span, or HTML/XML section. `word` MUST be non-global so
+ * `.test` stays stateless.
+ */
+export declare function keywordInProse(text: string, word: RegExp): boolean;

package/dist/types/prompt/model-mention-autocomplete.d.ts

@@ -0,0 +1,25 @@
+import type { Model } from "@oh-my-pi/pi-ai";
+import type { AutocompleteItem } from "../index.js";
+import type { ModelBrowserRegistry, ModelBrowserSource } from "../overlays/model-browser.js";
+import type { ModelBrowserItem } from "../overlays/model-browser.js";
+/** Supplies picker-ranked model candidates for the query after `^`. */
+export type ModelMentionCandidateSource = (query: string) => ReadonlyArray<ModelBrowserItem>;
+/** Whether an autocomplete prefix belongs to a model mention. */
+export declare function isModelMentionPrefix(prefix: string): boolean;
+/** Build model mention choices for the whitespace-delimited token at the cursor. */
+export declare function getModelMentionSuggestions(textBeforeCursor: string, candidates: ModelMentionCandidateSource | undefined): {
+    items: AutocompleteItem[];
+    prefix: string;
+} | null;
+/** Replace the live mention token with the selected canonical selector and a trailing space. */
+export declare function applyModelMentionCompletion(lines: string[], cursorLine: number, cursorCol: number, item: AutocompleteItem, prefix: string): {
+    lines: string[];
+    cursorLine: number;
+    cursorCol: number;
+};
+/** Create a fresh session-scoped model candidate lookup using picker ordering. */
+export declare function createModelMentionSource(host: {
+    source: ModelBrowserSource;
+    registry: ModelBrowserRegistry;
+    scopedModels: () => ReadonlyArray<Model>;
+}): ModelMentionCandidateSource;

package/dist/types/prompt/model-mention-syntax.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Dependency-free `^model` mention syntax shared by the composer, message
+ * rendering, and the session registry. Kept apart from `model-mentions.ts` so
+ * the startup composer prepaint graph never loads the catalog or task agents.
+ */
+import type { Model } from "@oh-my-pi/pi-ai";
+/** Whitespace-delimited token; groups are leading delimiter and selector. Reset lastIndex before reuse. */
+export declare const MODEL_MENTION_RE: RegExp;
+/** Submitted mention; groups are agent pseudonym and display name. */
+export declare const MODEL_MENTION_TAG_RE: RegExp;
+/** A user-tagged model usable as a subagent pseudonym on the current session branch. */
+export interface ModelMention {
+    agent: string;
+    selector: string;
+    name: string;
+}
+/** Expand a composer atom back into its canonical model selector. */
+export declare function modelMentionToken(selector: string): string;
+/** Encode a registered mention for the user message sent to the model. */
+export declare function modelMentionTag(mention: ModelMention): string;
+/** Use the catalog display name, without quotes, or the id when the name is empty. */
+export declare function modelMentionDisplayName(model: Model): string;
+/** Restore known submitted tags to editable selectors; leave unknown agents literal. */
+export declare function expandModelMentionTags(text: string, selectorFor: (agent: string) => string | undefined): string;