@code-yeongyu/senpi-tui 2026.9.29 → 2026.10.1-2

package/README.md

@@ -760,6 +760,44 @@ const lines = wrapTextWithAnsi("This is a long line that needs wrapping", 20);
 // ["This is a long line", "that needs wrapping"]
 ```
 
+### Colors and terminal styles
+
+Colors are values that can be converted or mixed before terminal rendering:
+
+```typescript
+import {
+  colorToRgb,
+  foregroundAnsi,
+  getTerminalColorMode,
+  mixColors,
+  parseColor,
+  rgbColor,
+  styleText,
+} from "@earendil-works/pi-tui";
+
+const accent = parseColor("oklch(70% 0.12 220)");
+const background = parseColor("#20242a");
+const foreground = mixColors(accent, background, 0.2);
+
+const text = styleText(
+  "Ready",
+  { fg: foreground, bg: background, bold: true },
+  getTerminalColorMode(),
+);
+```
+
+`Color` is an indexed ANSI color, an sRGB color, or an OKLCH color. Every color converts to sRGB, so color math such as `mixColors()` always works. Indices 0-15 follow the user's terminal palette, so their sRGB values are approximations. `styleText()` converts colors to truecolor or 256-color output based on the requested terminal mode.
+
+`parseColor()` also accepts OKHSL, as in `okhsl(250 60% 55%)`; `okhslColor()` builds it in code and `colorToOkhsl()` reads any color's OKHSL channels. OKHSL saturation is relative to the most the sRGB gamut allows at that hue and lightness, so every value is in gamut. OKHSL colors are converted to sRGB when created.
+
+Conversions are not cached, and OKLCH colors outside the sRGB gamut are the most expensive to convert. For colors used on every render, convert once and reuse the result:
+
+```typescript
+const { r, g, b } = colorToRgb(mixColors(accent, background, 0.2));
+const foreground = rgbColor(r, g, b); // cheap to render repeatedly
+const foregroundCode = foregroundAnsi(foreground, getTerminalColorMode());
+```
+
 ## Creating Custom Components
 
 When creating custom components, **each line returned by `render()` must not exceed the `width` parameter**. The TUI will error if any line is wider than the terminal.

package/dist/autocomplete.d.ts

@@ -2,6 +2,11 @@ export interface AutocompleteItem {
     value: string;
     label: string;
     description?: string;
+    /**
+     * The command declares an argument hint: confirming the row completes `/name ` and waits for
+     * arguments instead of submitting.
+     */
+    awaitsArguments?: boolean;
 }
 type Awaitable<T> = T | Promise<T>;
 export interface SlashCommand {

package/dist/autocomplete.js

@@ -4,7 +4,11 @@ import { homedir } from "os";
 import { basename, dirname, join } from "path";
 import { findDollarSkillMentions, getDollarInvocationContext, getDollarInvocationSuggestions, knownSkillNames, } from "./dollar-invocation-autocomplete.js";
 import { getSlashCommandSuggestions, isSlashNamespaceItem } from "./slash-command-autocomplete.js";
+import { autocompleteBoundaryRegex, autocompleteSeparatorRegex } from "./utils.js";
 const PATH_DELIMITERS = new Set([" ", "\t", '"', "'", "="]);
+const tokenStartRegex = new RegExp(`${autocompleteBoundaryRegex.source}$`, "u");
+// Opening wrappers that may precede a path in prose, mapped to their closing counterpart.
+const PATH_WRAPPERS = { "(": ")", "[": "]", "{": "}", "<": ">", "`": "`" };
 function toDisplayPath(value) {
     return value.replace(/\\/g, "/");
 }
@@ -36,12 +40,28 @@ function buildFdPathQuery(query) {
     return pattern;
 }
 function findLastDelimiter(text) {
-    for (let i = text.length - 1; i >= 0; i -= 1) {
-        if (PATH_DELIMITERS.has(text[i] ?? "")) {
-            return i;
+    let lastDelimiter = -1;
+    let index = 0;
+    for (const character of text) {
+        index += character.length;
+        if (PATH_DELIMITERS.has(character) || autocompleteSeparatorRegex.test(character)) {
+            lastDelimiter = index - 1;
         }
     }
-    return -1;
+    return lastDelimiter;
+}
+// Strip opening wrappers before a path, e.g. "(~/Dev" -> "~/Dev" or "`src/ma" -> "src/ma".
+// Keep a wrapper if the token also contains its closer, e.g. "app/[slug]/pa" or "(group)/pa".
+function stripLeadingWrappers(token) {
+    let result = token;
+    while (result.length > 0) {
+        const closer = PATH_WRAPPERS[result[0]];
+        if (!closer || result.includes(closer, 1)) {
+            break;
+        }
+        result = result.slice(1);
+    }
+    return result;
 }
 function findUnclosedQuoteStart(text) {
     let inQuotes = false;
@@ -57,7 +77,11 @@ function findUnclosedQuoteStart(text) {
     return inQuotes ? quoteStart : null;
 }
 function isTokenStart(text, index) {
-    return index === 0 || PATH_DELIMITERS.has(text[index - 1] ?? "");
+    let start = index;
+    while (start > 0 && PATH_WRAPPERS[text[start - 1]]) {
+        start -= 1;
+    }
+    return PATH_DELIMITERS.has(text[start - 1] ?? "") || tokenStartRegex.test(text.slice(0, start));
 }
 function extractQuotedPrefix(text) {
     const quoteStart = findUnclosedQuoteStart(text);
@@ -88,7 +112,7 @@ function parsePathPrefix(prefix) {
     return { rawPrefix: prefix, isAtPrefix: false, isQuotedPrefix: false };
 }
 function buildCompletionValue(path, options) {
-    const needsQuotes = options.isQuotedPrefix || path.includes(" ");
+    const needsQuotes = options.isQuotedPrefix || autocompleteSeparatorRegex.test(path);
     const prefix = options.isAtPrefix ? "@" : "";
     if (!needsQuotes) {
         return `${prefix}${path}`;
@@ -377,9 +401,9 @@ export class CombinedAutocompleteProvider {
             return quotedPrefix;
         }
         const lastDelimiterIndex = findLastDelimiter(text);
-        const tokenStart = lastDelimiterIndex === -1 ? 0 : lastDelimiterIndex + 1;
-        if (text[tokenStart] === "@") {
-            return text.slice(tokenStart);
+        const token = stripLeadingWrappers(lastDelimiterIndex === -1 ? text : text.slice(lastDelimiterIndex + 1));
+        if (token.startsWith("@")) {
+            return token;
         }
         return null;
     }
@@ -390,7 +414,7 @@ export class CombinedAutocompleteProvider {
             return quotedPrefix;
         }
         const lastDelimiterIndex = findLastDelimiter(text);
-        const pathPrefix = lastDelimiterIndex === -1 ? text : text.slice(lastDelimiterIndex + 1);
+        const pathPrefix = stripLeadingWrappers(lastDelimiterIndex === -1 ? text : text.slice(lastDelimiterIndex + 1));
         // For forced extraction (Tab key), always return something
         if (forceExtract) {
             return pathPrefix;
@@ -400,9 +424,9 @@ export class CombinedAutocompleteProvider {
         if (pathPrefix.includes("/") || pathPrefix.startsWith(".") || pathPrefix.startsWith("~/")) {
             return pathPrefix;
         }
-        // Return empty string only after a space (not for completely empty text)
+        // Return an empty prefix after whitespace or CJK punctuation, but not for empty text.
         // Empty text should not trigger file suggestions - that's for forced Tab completion
-        if (pathPrefix === "" && text.endsWith(" ")) {
+        if (pathPrefix === "" && text !== "" && tokenStartRegex.test(text)) {
             return pathPrefix;
         }
         return null;
@@ -576,8 +600,8 @@ export class CombinedAutocompleteProvider {
             }
             // Sort directories first, then alphabetically
             suggestions.sort((a, b) => {
-                const aIsDir = a.value.endsWith("/");
-                const bIsDir = b.value.endsWith("/");
+                const aIsDir = a.label.endsWith("/");
+                const bIsDir = b.label.endsWith("/");
                 if (aIsDir && !bIsDir)
                     return -1;
                 if (!aIsDir && bIsDir)

package/dist/colors.d.ts

@@ -0,0 +1,73 @@
+import type { RgbColor } from "./terminal-colors.ts";
+export interface IndexedColor {
+    readonly kind: "indexed";
+    readonly index: number;
+}
+export interface RgbColorValue {
+    readonly kind: "rgb";
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+}
+export interface OklchColorValue {
+    readonly kind: "oklch";
+    readonly l: number;
+    readonly c: number;
+    readonly h: number;
+}
+/** A concrete color. Every color can be converted to sRGB, so color math never fails. */
+export type Color = IndexedColor | RgbColorValue | OklchColorValue;
+export type TerminalColorMode = "256color" | "truecolor";
+export type ColorMixSpace = "oklch" | "srgb";
+export interface OklchChannels {
+    l: number;
+    c: number;
+    h: number;
+}
+/**
+ * OKHSL channels: hue in degrees, saturation and lightness 0-1. Saturation is relative to the most the
+ * sRGB gamut allows at that hue and lightness, so every value is in gamut.
+ */
+export interface OkhslChannels {
+    h: number;
+    s: number;
+    l: number;
+}
+export interface TextAttributes {
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    inverse?: boolean;
+    strikethrough?: boolean;
+}
+export interface TextStyle extends TextAttributes {
+    fg?: Color;
+    bg?: Color;
+}
+export declare function indexedColor(index: number): IndexedColor;
+export declare function rgbColor(r: number, g: number, b: number): RgbColorValue;
+export declare function oklchColor(l: number, c: number, h: number): OklchColorValue;
+/**
+ * An OKHSL color, converted to sRGB. Saturation is relative to the sRGB gamut at the hue and lightness,
+ * so equal saturation looks equally colorful across hues and lightness.
+ * @param h Hue in degrees.
+ * @param s Saturation, 0-1.
+ * @param l Lightness, 0-1.
+ */
+export declare function okhslColor(h: number, s: number, l: number): RgbColorValue;
+export declare function colorToOkhsl(color: Color): OkhslChannels;
+export declare function parseColor(value: string | number): Color;
+export declare function colorToRgb(color: Color): RgbColor;
+export declare function colorToOklch(color: Color): OklchChannels;
+export declare function colorToHex(color: Color): string;
+export declare function mixColors(first: Color, second: Color, amount: number, space?: ColorMixSpace): Color;
+export declare function foregroundAnsi(color: Color, mode: TerminalColorMode): string;
+export declare function backgroundAnsi(color: Color, mode: TerminalColorMode): string;
+export declare function styleText(text: string, options: TextStyle, mode: TerminalColorMode): string;
+/**
+ * Like `styleText()`, but with precomputed color escape sequences, e.g. cached theme colors.
+ * Colors in `options` are ignored.
+ */
+export declare function styleTextWithAnsi(text: string, fgAnsi: string | undefined, bgAnsi: string | undefined, options: TextAttributes): string;
+//# sourceMappingURL=colors.d.ts.map

package/dist/colors.js

@@ -0,0 +1,273 @@
+import { linearSrgbToRgb, okhslToRgb, oklabToLinearSrgb, rgbToOkhsl, rgbToOklab } from "./oklab.js";
+function requireFinite(value, name) {
+    if (!Number.isFinite(value))
+        throw new Error(`${name} must be finite`);
+}
+export function indexedColor(index) {
+    if (!Number.isInteger(index) || index < 0 || index > 255) {
+        throw new Error(`ANSI color index must be an integer from 0 to 255: ${index}`);
+    }
+    return Object.freeze({ kind: "indexed", index });
+}
+export function rgbColor(r, g, b) {
+    for (const [name, value] of [
+        ["r", r],
+        ["g", g],
+        ["b", b],
+    ]) {
+        requireFinite(value, name);
+        if (value < 0 || value > 255)
+            throw new Error(`${name} must be between 0 and 255: ${value}`);
+    }
+    return Object.freeze({ kind: "rgb", r, g, b });
+}
+export function oklchColor(l, c, h) {
+    requireFinite(l, "l");
+    requireFinite(c, "c");
+    requireFinite(h, "h");
+    if (l < 0 || l > 1)
+        throw new Error(`l must be between 0 and 1: ${l}`);
+    if (c < 0)
+        throw new Error(`c must not be negative: ${c}`);
+    return Object.freeze({ kind: "oklch", l, c, h: ((h % 360) + 360) % 360 });
+}
+const NUMBER_PATTERN = String.raw `[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?`;
+const OKLCH_PATTERN = new RegExp(`^oklch\\(\\s*(${NUMBER_PATTERN})(%)?\\s+(${NUMBER_PATTERN})\\s+(${NUMBER_PATTERN})(?:deg)?\\s*\\)$`, "i");
+const OKHSL_PATTERN = new RegExp(`^okhsl\\(\\s*(${NUMBER_PATTERN})(?:deg)?\\s+(${NUMBER_PATTERN})(%)?\\s+(${NUMBER_PATTERN})(%)?\\s*\\)$`, "i");
+/**
+ * An OKHSL color, converted to sRGB. Saturation is relative to the sRGB gamut at the hue and lightness,
+ * so equal saturation looks equally colorful across hues and lightness.
+ * @param h Hue in degrees.
+ * @param s Saturation, 0-1.
+ * @param l Lightness, 0-1.
+ */
+export function okhslColor(h, s, l) {
+    requireFinite(h, "h");
+    requireFinite(s, "s");
+    requireFinite(l, "l");
+    if (s < 0 || s > 1)
+        throw new Error(`s must be between 0 and 1: ${s}`);
+    if (l < 0 || l > 1)
+        throw new Error(`l must be between 0 and 1: ${l}`);
+    const { r, g, b } = okhslToRgb(h, s, l);
+    return rgbColor(r, g, b);
+}
+export function colorToOkhsl(color) {
+    return rgbToOkhsl(colorToRgb(color));
+}
+export function parseColor(value) {
+    if (typeof value === "number")
+        return indexedColor(value);
+    const hex = /^#([\da-f]{3}|[\da-f]{6})$/i.exec(value);
+    if (hex) {
+        const digits = hex[1].length === 3 ? [...hex[1]].map((digit) => digit + digit).join("") : hex[1];
+        return rgbColor(Number.parseInt(digits.slice(0, 2), 16), Number.parseInt(digits.slice(2, 4), 16), Number.parseInt(digits.slice(4, 6), 16));
+    }
+    const oklch = OKLCH_PATTERN.exec(value);
+    if (oklch) {
+        const lightness = Number.parseFloat(oklch[1]) / (oklch[2] ? 100 : 1);
+        return oklchColor(lightness, Number.parseFloat(oklch[3]), Number.parseFloat(oklch[4]));
+    }
+    const okhsl = OKHSL_PATTERN.exec(value);
+    if (okhsl) {
+        const saturation = Number.parseFloat(okhsl[2]) / (okhsl[3] ? 100 : 1);
+        const lightness = Number.parseFloat(okhsl[4]) / (okhsl[5] ? 100 : 1);
+        return okhslColor(Number.parseFloat(okhsl[1]), saturation, lightness);
+    }
+    throw new Error(`Invalid color value: ${value}`);
+}
+const BASIC_COLORS = [
+    { r: 0, g: 0, b: 0 },
+    { r: 128, g: 0, b: 0 },
+    { r: 0, g: 128, b: 0 },
+    { r: 128, g: 128, b: 0 },
+    { r: 0, g: 0, b: 128 },
+    { r: 128, g: 0, b: 128 },
+    { r: 0, g: 128, b: 128 },
+    { r: 192, g: 192, b: 192 },
+    { r: 128, g: 128, b: 128 },
+    { r: 255, g: 0, b: 0 },
+    { r: 0, g: 255, b: 0 },
+    { r: 255, g: 255, b: 0 },
+    { r: 0, g: 0, b: 255 },
+    { r: 255, g: 0, b: 255 },
+    { r: 0, g: 255, b: 255 },
+    { r: 255, g: 255, b: 255 },
+];
+const CUBE_VALUES = [0, 95, 135, 175, 215, 255];
+const GRAY_VALUES = Array.from({ length: 24 }, (_, index) => 8 + index * 10);
+function indexedToRgb(index) {
+    if (index < 16)
+        return { ...BASIC_COLORS[index] };
+    if (index < 232) {
+        const cubeIndex = index - 16;
+        return {
+            r: CUBE_VALUES[Math.floor(cubeIndex / 36)],
+            g: CUBE_VALUES[Math.floor((cubeIndex % 36) / 6)],
+            b: CUBE_VALUES[cubeIndex % 6],
+        };
+    }
+    const gray = 8 + (index - 232) * 10;
+    return { r: gray, g: gray, b: gray };
+}
+function isInSrgbGamut(linear) {
+    const epsilon = 1e-7;
+    return linear.every((channel) => channel >= -epsilon && channel <= 1 + epsilon);
+}
+function oklchToRgb({ l, c, h }) {
+    // Gamut mapping keeps the hue fixed, so its direction is computed once and scaled by chroma.
+    const radians = (h * Math.PI) / 180;
+    const cos = Math.cos(radians);
+    const sin = Math.sin(radians);
+    const atChroma = (chroma) => oklabToLinearSrgb([l, chroma * cos, chroma * sin]);
+    const direct = atChroma(c);
+    if (isInSrgbGamut(direct))
+        return linearSrgbToRgb(direct);
+    // Reduce chroma until the color fits. The achromatic color is always in gamut, so it is the
+    // fallback when no bisection step fits, e.g. `oklch(100% 0.3 150)` must map to white.
+    let linear = atChroma(0);
+    let low = 0;
+    let high = c;
+    for (let index = 0; index < 20; index++) {
+        const chroma = (low + high) / 2;
+        const candidate = atChroma(chroma);
+        if (isInSrgbGamut(candidate)) {
+            low = chroma;
+            linear = candidate;
+        }
+        else {
+            high = chroma;
+        }
+    }
+    return linearSrgbToRgb(linear);
+}
+export function colorToRgb(color) {
+    switch (color.kind) {
+        case "indexed":
+            return indexedToRgb(color.index);
+        case "rgb":
+            return { r: color.r, g: color.g, b: color.b };
+        case "oklch":
+            return oklchToRgb(color);
+    }
+}
+export function colorToOklch(color) {
+    if (color.kind === "oklch")
+        return { l: color.l, c: color.c, h: color.h };
+    const [l, a, b] = rgbToOklab(colorToRgb(color));
+    return { l, c: Math.hypot(a, b), h: ((Math.atan2(b, a) * 180) / Math.PI + 360) % 360 };
+}
+export function colorToHex(color) {
+    const { r, g, b } = colorToRgb(color);
+    const channel = (value) => Math.round(value).toString(16).padStart(2, "0");
+    return `#${channel(r)}${channel(g)}${channel(b)}`;
+}
+export function mixColors(first, second, amount, space = "oklch") {
+    requireFinite(amount, "amount");
+    if (amount < 0 || amount > 1)
+        throw new Error(`amount must be between 0 and 1: ${amount}`);
+    if (space === "srgb") {
+        const a = colorToRgb(first);
+        const b = colorToRgb(second);
+        return rgbColor(a.r + (b.r - a.r) * amount, a.g + (b.g - a.g) * amount, a.b + (b.b - a.b) * amount);
+    }
+    const a = colorToOklch(first);
+    const b = colorToOklch(second);
+    const firstHue = a.c < 1e-7 ? b.h : a.h;
+    const secondHue = b.c < 1e-7 ? firstHue : b.h;
+    const hueDelta = ((secondHue - firstHue + 540) % 360) - 180;
+    return oklchColor(a.l + (b.l - a.l) * amount, a.c + (b.c - a.c) * amount, firstHue + hueDelta * amount);
+}
+function findClosest(values, target) {
+    let closestIndex = 0;
+    let closestDistance = Infinity;
+    for (let index = 0; index < values.length; index++) {
+        const distance = Math.abs(target - values[index]);
+        if (distance < closestDistance) {
+            closestIndex = index;
+            closestDistance = distance;
+        }
+    }
+    return closestIndex;
+}
+function colorDistance(first, second) {
+    const dr = first.r - second.r;
+    const dg = first.g - second.g;
+    const db = first.b - second.b;
+    return dr * dr * 0.299 + dg * dg * 0.587 + db * db * 0.114;
+}
+function rgbToAnsi256(color) {
+    const rIndex = findClosest(CUBE_VALUES, color.r);
+    const gIndex = findClosest(CUBE_VALUES, color.g);
+    const bIndex = findClosest(CUBE_VALUES, color.b);
+    const cubeColor = { r: CUBE_VALUES[rIndex], g: CUBE_VALUES[gIndex], b: CUBE_VALUES[bIndex] };
+    const cubeIndex = 16 + 36 * rIndex + 6 * gIndex + bIndex;
+    const gray = Math.round(0.299 * color.r + 0.587 * color.g + 0.114 * color.b);
+    const grayOffset = findClosest(GRAY_VALUES, gray);
+    const grayValue = GRAY_VALUES[grayOffset];
+    const spread = Math.max(color.r, color.g, color.b) - Math.min(color.r, color.g, color.b);
+    if (spread < 10 &&
+        colorDistance(color, { r: grayValue, g: grayValue, b: grayValue }) < colorDistance(color, cubeColor)) {
+        return 232 + grayOffset;
+    }
+    return cubeIndex;
+}
+function colorAnsi(color, mode, background) {
+    if (color.kind === "indexed")
+        return `\x1b[${background ? 48 : 38};5;${color.index}m`;
+    const rgb = colorToRgb(color);
+    if (mode === "truecolor") {
+        return `\x1b[${background ? 48 : 38};2;${Math.round(rgb.r)};${Math.round(rgb.g)};${Math.round(rgb.b)}m`;
+    }
+    return `\x1b[${background ? 48 : 38};5;${rgbToAnsi256(rgb)}m`;
+}
+export function foregroundAnsi(color, mode) {
+    return colorAnsi(color, mode, false);
+}
+export function backgroundAnsi(color, mode) {
+    return colorAnsi(color, mode, true);
+}
+export function styleText(text, options, mode) {
+    return styleTextWithAnsi(text, options.fg && foregroundAnsi(options.fg, mode), options.bg && backgroundAnsi(options.bg, mode), options);
+}
+/**
+ * Like `styleText()`, but with precomputed color escape sequences, e.g. cached theme colors.
+ * Colors in `options` are ignored.
+ */
+export function styleTextWithAnsi(text, fgAnsi, bgAnsi, options) {
+    // Resets are prepended so they close in reverse order of the opening sequences.
+    let prefix = "";
+    let suffix = "";
+    if (fgAnsi) {
+        prefix += fgAnsi;
+        suffix = "\x1b[39m";
+    }
+    if (bgAnsi) {
+        prefix += bgAnsi;
+        suffix = `\x1b[49m${suffix}`;
+    }
+    if (options.bold)
+        prefix += "\x1b[1m";
+    if (options.dim)
+        prefix += "\x1b[2m";
+    if (options.bold || options.dim)
+        suffix = `\x1b[22m${suffix}`;
+    if (options.italic) {
+        prefix += "\x1b[3m";
+        suffix = `\x1b[23m${suffix}`;
+    }
+    if (options.underline) {
+        prefix += "\x1b[4m";
+        suffix = `\x1b[24m${suffix}`;
+    }
+    if (options.inverse) {
+        prefix += "\x1b[7m";
+        suffix = `\x1b[27m${suffix}`;
+    }
+    if (options.strikethrough) {
+        prefix += "\x1b[9m";
+        suffix = `\x1b[29m${suffix}`;
+    }
+    return `${prefix}${text}${suffix}`;
+}
+//# sourceMappingURL=colors.js.map

package/dist/components/box.js

@@ -94,14 +94,16 @@ export class Box {
         }
         const contentWidth = Math.max(1, width - this.paddingX * 2);
         const leftPad = " ".repeat(this.paddingX);
-        // Render all children
+        // Render all children. Keep the child lines unpadded: children usually return the same string
+        // objects every frame, so the cache check below is a cheap identity comparison per line.
+        // Padding here would create new strings that must be compared character by character.
         const childLines = [];
         const mouseChildren = [];
         for (const child of this.children) {
             const lines = child.render(contentWidth);
             mouseChildren.push({ component: child, height: lines.length });
             for (const line of lines) {
-                childLines.push(leftPad + line);
+                childLines.push(line);
             }
         }
         this.mouseLayout = { width: contentWidth, children: mouseChildren };
@@ -122,7 +124,7 @@ export class Box {
         }
         // Content
         for (const line of childLines) {
-            result.push(this.applyBg(line, width));
+            result.push(this.applyBg(leftPad + line, width));
         }
         // Bottom padding
         for (let i = 0; i < this.paddingY; i++) {

package/dist/components/editor.d.ts

@@ -1,4 +1,5 @@
 import type { AutocompleteProvider } from "../autocomplete.ts";
+import type { EditorSubmitDetails } from "../editor-component.ts";
 import { type EditorImageState } from "../image-markers.ts";
 import { type EditorPasteState } from "../paste-markers.ts";
 import { type Component, type Focusable, type TUI, type TuiMouseEvent, type TuiMouseEventResult } from "../tui.ts";
@@ -68,6 +69,8 @@ export declare class Editor implements Component, Focusable {
     private autocompleteList?;
     private autocompleteState;
     private autocompletePrefix;
+    /** The provider items behind `autocompleteList`, which only carries the display fields. */
+    private autocompleteItems;
     private autocompleteMaxVisible;
     private autocompleteAbort?;
     private autocompleteDebounceTimer?;
@@ -88,7 +91,7 @@ export declare class Editor implements Component, Focusable {
     private snappedFromCursorCol;
     private undoStack;
     private wrappedLineCache;
-    onSubmit?: (text: string) => void;
+    onSubmit?: (text: string, details?: EditorSubmitDetails) => void;
     onChange?: (text: string) => void;
     /**
      * Fired whenever image markers are added, removed, pruned or renumbered.

package/dist/components/editor.js

@@ -7,7 +7,7 @@ import { isSlashNamespaceItem } from "../slash-command-autocomplete.js";
 import { normalizeWarpWslShiftEnterInput } from "../terminal.js";
 import { CURSOR_MARKER, } from "../tui.js";
 import { UndoStack } from "../undo-stack.js";
-import { cjkBreakRegex, getGraphemeSegmenter, getWordSegmenter, isWhitespaceChar, sliceByColumn, visibleWidth, } from "../utils.js";
+import { autocompleteBoundaryRegex, autocompleteSeparatorRegex, cjkBreakRegex, getGraphemeSegmenter, getWordSegmenter, isWhitespaceChar, sliceByColumn, visibleWidth, } from "../utils.js";
 import { findWordBackward, findWordForward } from "../word-navigation.js";
 import { renderEditorLine } from "./editor-line-render.js";
 import { SelectList } from "./select-list.js";
@@ -173,15 +173,19 @@ const SLASH_COMMAND_SELECT_LIST_LAYOUT = {
 };
 const ATTACHMENT_AUTOCOMPLETE_DEBOUNCE_MS = 20;
 const DEFAULT_AUTOCOMPLETE_TRIGGER_CHARACTERS = ["@", "#", "$"];
+// Unquoted completions end at whitespace or CJK punctuation; quoted paths may contain either.
+const unquotedAutocompleteSuffixRegex = new RegExp(`(?:(?!${autocompleteSeparatorRegex.source}).)*`, "u");
+// Trigger tokens may be wrapped in prose, e.g. "(@src/foo" or "`@src/foo".
+const autocompleteTokenStartSource = `${autocompleteBoundaryRegex.source}[([{<\`]*`;
 function escapeCharacterClass(value) {
     return value.replace(/[\\^$.*+?()[\]{}|-]/g, "\\$&");
 }
 function buildTriggerPattern(triggerCharacters) {
-    return new RegExp(`(?:^|[\\s])[${triggerCharacters.map(escapeCharacterClass).join("")}][^\\s]*$`);
+    return new RegExp(`${autocompleteTokenStartSource}(?:@"[^"]*|[${triggerCharacters.map(escapeCharacterClass).join("")}]${unquotedAutocompleteSuffixRegex.source})$`, "u");
 }
 function buildDebouncePattern(triggerCharacters) {
     const escapedWithoutAt = triggerCharacters.filter((character) => character !== "@").map(escapeCharacterClass);
-    return new RegExp(`(?:^|[ \\t])(?:@(?:"[^"]*|[^\\s]*)|[${escapedWithoutAt.join("")}][^\\s]*)$`);
+    return new RegExp(`${autocompleteTokenStartSource}(?:@(?:"[^"]*|${unquotedAutocompleteSuffixRegex.source})|[${escapedWithoutAt.join("")}]${unquotedAutocompleteSuffixRegex.source})$`, "u");
 }
 function createScrollBorder(direction, hiddenLineCount, width) {
     const availableWidth = Math.max(0, width);
@@ -220,6 +224,8 @@ export class Editor {
         this.autocompleteDebouncePattern = buildDebouncePattern(this.autocompleteTriggerCharacters);
         this.autocompleteState = null;
         this.autocompletePrefix = "";
+        /** The provider items behind `autocompleteList`, which only carries the display fields. */
+        this.autocompleteItems = [];
         this.autocompleteMaxVisible = 5;
         this.autocompleteRequestTask = Promise.resolve();
         this.autocompleteStartToken = 0;
@@ -718,7 +724,14 @@ export class Editor {
                         return;
                     }
                     if (this.autocompletePrefix.startsWith("/")) {
+                        const awaitsArguments = this.autocompleteItems.some((item) => item === selected && item.awaitsArguments === true);
                         this.cancelAutocomplete();
+                        if (awaitsArguments) {
+                            // The command takes arguments: leave `/name ` in the editor for them.
+                            if (this.onChange)
+                                this.onChange(this.getText());
+                            return;
+                        }
                         // Fall through to submit
                     }
                     else {
@@ -1219,13 +1232,12 @@ export class Editor {
             else if (this.autocompleteTriggerCharacters.includes(char)) {
                 const currentLine = this.state.lines[this.state.cursorLine] || "";
                 const textBeforeCursor = currentLine.slice(0, this.state.cursorCol);
-                const charBeforeSymbol = textBeforeCursor[textBeforeCursor.length - 2];
-                if (textBeforeCursor.length === 1 || charBeforeSymbol === " " || charBeforeSymbol === "\t") {
+                if (this.autocompleteTriggerPattern.test(textBeforeCursor)) {
                     this.tryTriggerAutocomplete();
                 }
             }
             // Also auto-trigger when typing letters in a slash command or symbol completion context
-            else if (/[a-zA-Z0-9.\-_]/.test(char)) {
+            else if (/[a-zA-Z0-9.\-_]/.test(char) || cjkBreakRegex.test(char)) {
                 const currentLine = this.state.lines[this.state.cursorLine] || "";
                 const textBeforeCursor = currentLine.slice(0, this.state.cursorCol);
                 // Check if we're in a slash command (with or without space for arguments)
@@ -1325,7 +1337,8 @@ export class Editor {
     }
     submitValue() {
         this.cancelAutocomplete();
-        const result = this.pasteMarkers.expand(this.state.lines.join("\n")).trim();
+        const rawText = this.pasteMarkers.expand(this.state.lines.join("\n"));
+        const result = rawText.trim();
         this.state = { lines: [""], cursorLine: 0, cursorCol: 0 };
         this.pasteMarkers.clear();
         // Marker numbering is turn-local: ids restart at 1 for the next submission.
@@ -1337,7 +1350,7 @@ export class Editor {
         if (this.onChange)
             this.onChange("");
         if (this.onSubmit)
-            this.onSubmit(result);
+            this.onSubmit(result, { rawText });
     }
     handleBackspace() {
         this.exitHistoryBrowsing();
@@ -2203,6 +2216,7 @@ export class Editor {
     }
     applyAutocompleteSuggestions(suggestions, state) {
         this.autocompletePrefix = suggestions.prefix;
+        this.autocompleteItems = suggestions.items;
         this.autocompleteList = this.createAutocompleteList(suggestions.prefix, suggestions.items);
         const bestMatchIndex = this.getBestAutocompleteMatchIndex(suggestions.items, suggestions.prefix);
         if (bestMatchIndex >= 0) {
@@ -2222,6 +2236,7 @@ export class Editor {
     clearAutocompleteUi() {
         this.autocompleteState = null;
         this.autocompleteList = undefined;
+        this.autocompleteItems = [];
         this.autocompletePrefix = "";
     }
     cancelAutocomplete() {