@xingular/harness 1.1.1 → 1.2.0

package/dist/sdk/terminal/tui/commands.d.ts

@@ -15,6 +15,7 @@ export interface TerminalCommandHost {
     control: <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>;
     ui: ExtensionUIContext;
     cwd(): string;
+    branch(): string | null;
     sessionDirectory(): string;
     refresh(): void;
     changed(): void;
@@ -43,4 +44,5 @@ export declare function createTerminalCommands(host: TerminalCommandHost): {
     completions: () => TerminalCommandCompletion[];
     skills: () => SkillEntry[];
     expandSkill: (text: string) => string;
+    legacyAliases: () => string[];
 };

package/dist/sdk/terminal/tui/commands.js

@@ -1,49 +1,34 @@
 import { isAbsolute, relative, resolve } from 'node:path';
 import { SessionManager } from '@earendil-works/pi-coding-agent';
+import { CORE_COMMANDS, coreCommand } from "../../commands/registry.js";
+import { commandRoutes, promptCommandAvailable } from "../../commands/routes.js";
 import { BUILTIN_PLUGIN_REGISTRY } from "../../plugins/builtin.js";
+import { pluginCommandPrefix } from "../../plugins/commandPrefix.js";
 import { PageOverlay } from "./pageOverlay.js";
 import { ModelPicker } from "./modelPicker.js";
 import { TreePicker } from "./treePicker.js";
 import { createCommandPage } from "./commandPages.js";
 import { pageOverlayOptions } from "./dialogGeometry.js";
+import { ResumeSessionsPage } from "./sessionPicker.js";
 import { expandSkillInvocation } from "./skillInvocation.js";
 import { groupTerminalCommands } from "../commandHelp.js";
 import { createBuiltinPluginCommandHandlers } from "./pluginCommands.js";
 export { parseAnnotate } from "./pluginCommands.js";
-const BUILTINS = [
-    { name: 'help', description: 'List the commands', group: 'Core' },
-    { name: 'plan', description: 'Plan one request, read-only: /plan <brief>', group: 'Run' },
-    { name: 'btw', aliases: ['side'], description: 'Ask a side question without interrupting: /btw <question>', group: 'Run' },
-    { name: 'new', description: 'Start a new session', group: 'Session' },
-    { name: 'stop', description: 'Stop the current reply', group: 'Run' },
-    { name: 'session', aliases: ['resume'], description: 'Choose a saved session in this account and folder', group: 'Session' },
-    { name: 'history', aliases: ['tree'], description: 'Navigate branches in the current session', group: 'Session' },
-    { name: 'fork', description: 'Fork from an earlier message', group: 'Session' },
-    { name: 'clone', description: 'Clone this branch into a new session', group: 'Session' },
-    { name: 'model', description: 'Choose the model', group: 'Model' },
-    { name: 'effort', description: 'Choose the thinking effort', group: 'Model' },
-    { name: 'thinking', description: 'Toggle transcript thinking visibility: /thinking [show|hide]', group: 'Model' },
-    { name: 'name', description: 'Name this session', group: 'Session' },
-    { name: 'compact', description: 'Compact the context', group: 'Session' },
-    { name: 'copy', description: 'Copy the last reply', group: 'Inspect' },
-    { name: 'export', description: 'Export this branch to HTML or JSONL', group: 'Inspect' },
-    { name: 'reload', description: 'Reload trusted resources and keybindings', group: 'Harness' },
-    { name: 'accounts', description: 'Sign in, switch, check and remove Pi accounts', group: 'Harness' },
-    { name: 'permissions', description: 'Full Permission and per-tool approvals', group: 'Harness' },
-    { name: 'harness', description: 'Browse foundation, variant and all resources', group: 'Harness' },
-    { name: 'skills', description: 'View, inspect and use skills; discover more', group: 'Harness' },
-    { name: 'connections', description: 'Manage local and remote MCP connections', group: 'Harness' },
-    { name: 'mcp', description: 'Open Connections in the Harness browser', group: 'Harness' },
-    { name: 'tools', description: 'Inspect available tools, owners and approvals', group: 'Harness' },
-    { name: 'plugins', description: 'Switch plugins on or off and trust their code', group: 'Harness' },
-    { name: 'hub', description: 'Browse and install reviewed skills, plugins and documents', group: 'Harness' },
-    { name: 'components', description: 'Browse skills, prompts and rules for this Harness scope', group: 'Harness' },
-    { name: 'settings', description: 'Session, terminal and browser settings', group: 'Harness' },
-    { name: 'log', description: "Harness diagnostics and this conversation's run events", group: 'Inspect' },
-    { name: 'hotkeys', description: 'Keyboard controls', group: 'Core' },
-    { name: 'quit', description: 'Restore the terminal and exit', group: 'Core' }
-];
+const BUILTINS = CORE_COMMANDS.map((command) => ({
+    name: command.name,
+    ...('aliases' in command ? { aliases: [...command.aliases] } : {}),
+    description: command.description,
+    group: command.group
+}));
 const COMMAND_ALIASES = new Map(BUILTINS.flatMap(command => (command.aliases ?? []).map(alias => [alias, command.name])));
+const CORE_PROMPT_NAMES = new Set([...BUILTINS.map(command => command.name), ...COMMAND_ALIASES.keys()]);
+const LEGACY_BUILTIN_COMMAND_ALIASES = new Map([
+    ['doctor:doctor', 'doctor'], ['plugin:doctor', 'doctor'],
+    ['worktrees:worktree', 'worktree'], ['plugin:worktree', 'worktree'],
+    ['history:trajectory', 'trajectory'], ['plugin:trajectory', 'trajectory'],
+    ['subagents:subagents', 'subagents'], ['plugin:subagents', 'subagents'],
+    ['subagents:agents', 'agents'], ['plugin:agents', 'agents']
+]);
 export function createTerminalCommands(host) {
     const notify = (text) => host.ui.notify(text, 'info');
     const choose = async (title, items, label) => {
@@ -70,37 +55,31 @@ export function createTerminalCommands(host) {
     }
     const pluginHandlers = createBuiltinPluginCommandHandlers(host, openPage);
     const pluginCommands = BUILTIN_PLUGIN_REGISTRY.commands();
-    const coreNames = new Set([...BUILTINS.map(command => command.name), ...COMMAND_ALIASES.keys()]);
-    for (const command of pluginCommands) {
-        if (command.namespace === 'unprefixed' && coreNames.has(command.name)) {
-            throw new Error(`Required plugin command collides with a core command: ${command.pluginId}:${command.name}`);
-        }
-    }
+    const builtinPrefixes = new Map(pluginCommands.map(command => [command.prefix, command.pluginId]));
+    const prefixCache = new WeakMap();
     const extensionCommands = () => {
-        const byName = new Map();
-        for (const command of host.session().extensionRunner.getRegisteredCommands()) {
-            byName.set(command.name, [...(byName.get(command.name) ?? []), command]);
-        }
-        const unique = new Map();
-        const duplicates = new Map();
-        for (const [name, commands] of byName) {
-            if (commands.length === 1)
-                unique.set(name, commands[0]);
-            else
-                duplicates.set(name, commands);
-        }
-        return { unique, duplicates };
+        return commandRoutes(host.session().extensionRunner.getRegisteredCommands().map(command => {
+            const source = command.sourceInfo;
+            let prefix = prefixCache.get(source);
+            if (!prefix) {
+                prefix = pluginCommandPrefix(source);
+                prefixCache.set(source, prefix);
+            }
+            const owner = source.origin === 'package'
+                ? `package:${source.baseDir ?? source.source}`
+                : `extension:${source.path}`;
+            return { ...command, prefix, owner, path: source.path };
+        }));
     };
-    const unprefixedCommandNames = (session) => new Set([
+    const coreCommandNames = (session) => new Set([
         ...BUILTINS.flatMap(command => [command.name, ...(command.aliases ?? [])]),
-        ...pluginCommands.filter(command => command.namespace === 'unprefixed').map(command => command.name),
         ...session.resourceLoader.getPrompts().prompts.map(prompt => prompt.name)
     ]);
-    const runBuiltinPluginCommand = async (name, argument) => {
+    const runBuiltinPluginCommand = async (command, argument) => {
         try {
-            const handler = pluginHandlers.get(name);
+            const handler = pluginHandlers.get(`${command.pluginId}:${command.name}`);
             if (!handler)
-                throw new Error(`No terminal handler for built-in plugin command ${name}.`);
+                throw new Error(`No terminal handler for built-in plugin command ${command.pluginId}:${command.name}.`);
             await handler(argument);
             host.refresh();
         }
@@ -108,33 +87,141 @@ export function createTerminalCommands(host) {
             host.ui.notify(error instanceof Error ? error.message : String(error), 'error');
         }
     };
+    const runExtensionCommand = async (registered, argument, route) => {
+        try {
+            const command = host.session().extensionRunner.getCommand(registered.invocationName);
+            if (!command)
+                throw new Error(`Plugin command /${route} is no longer registered. Reload trusted resources.`);
+            await command.handler(argument, host.session().extensionRunner.createCommandContext());
+            host.refresh();
+        }
+        catch (error) {
+            host.ui.notify(error instanceof Error ? error.message : String(error), 'error');
+        }
+    };
+    const runLegacyPluginCommand = async (name, argument) => {
+        const session = host.session();
+        if (coreCommandNames(session).has(name)) {
+            host.ui.notify(`Use /${name}; /plugin:${name} is unavailable because a core command or prompt already uses that name.`, 'error');
+            return;
+        }
+        const builtins = BUILTIN_PLUGIN_REGISTRY.commandsNamed(name);
+        const extensions = extensionCommands();
+        if (builtins.length > 1) {
+            host.ui.notify(`Legacy plugin command /plugin:${name} is ambiguous. Use its owner-qualified command.`, 'error');
+            return;
+        }
+        if (builtins.length === 1) {
+            const competitors = extensions.byName.get(name) ?? [];
+            if (competitors.length) {
+                host.ui.notify(`Extension command /plugin:${name} from ${competitors.map(command => command.sourceInfo.path).join(', ')} is unavailable because the name belongs to the built-in ${builtins[0].pluginId} plugin.`, 'error');
+            }
+            await runBuiltinPluginCommand(builtins[0], argument);
+            return;
+        }
+        const matches = extensions.byName.get(name) ?? [];
+        if (matches.length > 1) {
+            host.ui.notify(`Legacy plugin command /plugin:${name} is ambiguous. Registered by: ${matches.map(command => command.sourceInfo.path).join(', ')}. Use its owner-qualified command.`, 'error');
+            return;
+        }
+        if (matches.length === 1) {
+            if (extensions.conflictingPrefixes.has(matches[0].prefix)) {
+                host.ui.notify(`Plugin prefix /${matches[0].prefix}: is ambiguous or reserved. Owners: ${extensions.conflictingPrefixes.get(matches[0].prefix).join(', ')}.`, 'error');
+                return;
+            }
+            await runExtensionCommand(matches[0], argument, `plugin:${name}`);
+            return;
+        }
+        host.ui.notify(`Unknown plugin command: /plugin:${name}. Use /help to list the commands.`, 'error');
+    };
+    const runNamespacedCommand = async (typedName, argument) => {
+        const separator = typedName.indexOf(':');
+        if (separator < 1)
+            return false;
+        const prefix = typedName.slice(0, separator);
+        const name = typedName.slice(separator + 1);
+        if (prefix === 'plugin') {
+            await runLegacyPluginCommand(name, argument);
+            return true;
+        }
+        const builtin = name ? BUILTIN_PLUGIN_REGISTRY.command(prefix, name) : BUILTIN_PLUGIN_REGISTRY.defaultCommand(prefix);
+        const extensions = extensionCommands();
+        const isBuiltinPrefix = builtinPrefixes.has(prefix);
+        const isExtensionPrefix = extensions.ownersByPrefix.has(prefix);
+        if (!builtin && !isBuiltinPrefix && !isExtensionPrefix)
+            return false;
+        if (builtin) {
+            const competitors = extensions.routes.get(`${prefix}:${builtin.name}`) ?? [];
+            if (competitors.length) {
+                host.ui.notify(`Extension command /${prefix}:${builtin.name} from ${competitors.map(command => command.sourceInfo.path).join(', ')} is unavailable because the prefix belongs to built-in ${builtin.pluginId}.`, 'error');
+            }
+            await runBuiltinPluginCommand(builtin, argument);
+            return true;
+        }
+        if (extensions.conflictingPrefixes.has(prefix)) {
+            host.ui.notify(`Plugin prefix /${prefix}: is ambiguous or reserved. Owners: ${extensions.conflictingPrefixes.get(prefix).join(', ')}.`, 'error');
+            return true;
+        }
+        if (!name) {
+            host.ui.notify(`Plugin /${prefix}: has no default command. Use /help to list its commands.`, 'error');
+            return true;
+        }
+        const matches = extensions.routes.get(`${prefix}:${name}`) ?? [];
+        if (matches.length > 1) {
+            host.ui.notify(`Plugin command /${prefix}:${name} is ambiguous. Registered by: ${matches.map(command => command.sourceInfo.path).join(', ')}.`, 'error');
+            return true;
+        }
+        if (matches.length === 1) {
+            await runExtensionCommand(matches[0], argument, `${prefix}:${name}`);
+            return true;
+        }
+        host.ui.notify(`Unknown plugin command: /${typedName}. Use /help to list the commands.`, 'error');
+        return true;
+    };
+    const legacyAliases = () => {
+        const session = host.session();
+        const coreNames = coreCommandNames(session);
+        const aliases = new Set(LEGACY_BUILTIN_COMMAND_ALIASES.keys());
+        for (const command of pluginCommands) {
+            if (coreNames.has(command.name))
+                continue;
+            aliases.add(`plugin:${command.name}`);
+            if (command.legacyBare)
+                aliases.add(command.name);
+        }
+        for (const name of extensionCommands().byName.keys()) {
+            if (!coreNames.has(name))
+                aliases.add(`plugin:${name}`);
+        }
+        return [...aliases];
+    };
     const completions = () => {
         const session = host.session();
         const prompts = session.resourceLoader.getPrompts().prompts;
         const commands = new Map(BUILTINS.map(command => [command.name, command]));
-        const bareNames = unprefixedCommandNames(session);
-        const namespacedBuiltins = new Set();
         for (const command of pluginCommands) {
-            if (command.namespace === 'unprefixed') {
-                commands.set(command.name, { name: command.name, description: command.description, group: 'Harness' });
-            }
-            else {
-                namespacedBuiltins.add(command.name);
-                if (!bareNames.has(command.name)) {
-                    const invocation = `plugin:${command.name}`;
-                    commands.set(invocation, { name: invocation, description: command.description, group: 'Plugins' });
-                }
+            const invocation = `${command.prefix}:${command.name}`;
+            commands.set(invocation, { name: invocation, description: command.description, group: 'Plugins' });
+        }
+        for (const module of BUILTIN_PLUGIN_REGISTRY.modules) {
+            const defaultCommand = module.defaultCommand && BUILTIN_PLUGIN_REGISTRY.command(module.commandPrefix ?? module.descriptor.id, module.defaultCommand);
+            if (defaultCommand) {
+                const invocation = `${defaultCommand.prefix}:`;
+                commands.set(invocation, { name: invocation, description: defaultCommand.description, group: 'Plugins' });
             }
         }
         const extensions = extensionCommands();
-        for (const [name, command] of extensions.unique) {
-            if (!bareNames.has(name) && !namespacedBuiltins.has(name)) {
-                const invocation = `plugin:${name}`;
-                commands.set(invocation, { name: invocation, description: command.description, group: 'Plugins' });
-            }
+        for (const [route, matches] of extensions.routes) {
+            const prefix = route.slice(0, route.indexOf(':'));
+            if (matches.length !== 1 || extensions.conflictingPrefixes.has(prefix))
+                continue;
+            if (BUILTIN_PLUGIN_REGISTRY.command(prefix, matches[0].name))
+                continue;
+            commands.set(route, { name: route, description: matches[0].description, group: 'Plugins' });
         }
+        const extensionNames = new Set(extensions.byName.keys());
         for (const prompt of prompts) {
-            if (!commands.has(prompt.name) && !COMMAND_ALIASES.has(prompt.name))
+            if (promptCommandAvailable(prompt.name, new Set([...commands.keys(), ...COMMAND_ALIASES.keys()]), extensionNames))
                 commands.set(prompt.name, { name: prompt.name, description: prompt.description, group: 'Prompts' });
         }
         return [...commands.values()];
@@ -145,65 +232,34 @@ export function createTerminalCommands(host) {
             return false;
         const typedName = match[1];
         const argument = match[2]?.trim() ?? '';
-        if (typedName.startsWith('plugin:')) {
-            const pluginName = typedName.slice('plugin:'.length);
-            const session = host.session();
-            if (unprefixedCommandNames(session).has(pluginName)) {
-                host.ui.notify(`Use /${pluginName}; /plugin:${pluginName} is unavailable because an unprefixed command already uses that name.`, 'error');
-                return true;
-            }
-            const builtin = BUILTIN_PLUGIN_REGISTRY.command(pluginName);
-            const extensions = extensionCommands();
-            if (builtin?.namespace === 'plugin') {
-                const collisions = extensions.unique.get(pluginName) ? [extensions.unique.get(pluginName)] : extensions.duplicates.get(pluginName) ?? [];
-                if (collisions.length) {
-                    const owners = collisions.map(command => command.sourceInfo.path).join(', ');
-                    host.ui.notify(`Extension command /plugin:${pluginName} from ${owners} is unavailable because the name belongs to the built-in ${builtin.pluginId} plugin.`, 'error');
-                }
-                await runBuiltinPluginCommand(pluginName, argument);
-                return true;
-            }
-            const duplicate = extensions.duplicates.get(pluginName);
-            if (duplicate) {
-                const owners = duplicate.map(command => command.sourceInfo.path).join(', ');
-                host.ui.notify(`Plugin command /plugin:${pluginName} is ambiguous. Registered by: ${owners}. Rename or remove one command.`, 'error');
+        const legacyBuiltin = LEGACY_BUILTIN_COMMAND_ALIASES.get(typedName);
+        if (!legacyBuiltin && await runNamespacedCommand(typedName, argument))
+            return true;
+        const session = host.session();
+        const name = coreCommand(legacyBuiltin ?? typedName)?.name ?? legacyBuiltin ?? typedName;
+        const builtin = BUILTINS.find(item => item.name === name);
+        if (!builtin && !coreCommandNames(session).has(name)) {
+            const legacyBare = BUILTIN_PLUGIN_REGISTRY.commandsNamed(name).filter(command => command.legacyBare);
+            if (legacyBare.length > 1) {
+                host.ui.notify(`Legacy command /${name} is ambiguous. Use its owner-qualified command.`, 'error');
                 return true;
             }
-            const registered = extensions.unique.get(pluginName);
-            if (registered) {
-                try {
-                    const command = host.session().extensionRunner.getCommand(registered.invocationName);
-                    if (!command)
-                        throw new Error(`Plugin command /plugin:${pluginName} is no longer registered. Reload trusted resources.`);
-                    await command.handler(argument, host.session().extensionRunner.createCommandContext());
-                    host.refresh();
-                }
-                catch (error) {
-                    host.ui.notify(error instanceof Error ? error.message : String(error), 'error');
-                }
+            if (legacyBare.length === 1) {
+                await runBuiltinPluginCommand(legacyBare[0], argument);
                 return true;
             }
-            host.ui.notify(`Unknown plugin command: /${typedName}. Use /help to list the commands.`, 'error');
-            return true;
-        }
-        const name = COMMAND_ALIASES.get(typedName) ?? typedName;
-        const builtin = BUILTINS.find(item => item.name === name);
-        const requiredPluginCommand = BUILTIN_PLUGIN_REGISTRY.command(name);
-        if (!builtin && requiredPluginCommand?.namespace === 'unprefixed') {
-            await runBuiltinPluginCommand(name, argument);
-            return true;
         }
         if (!builtin) {
             // A skill is offered as $name; the typed /skill:name form still reaches the SDK, which expands it.
             if (skills().some(skill => `skill:${skill.name}` === name))
                 return false;
-            if (host.session().resourceLoader.getPrompts().prompts.some(prompt => prompt.name === name))
+            const prompt = session.resourceLoader.getPrompts().prompts.some(item => item.name === name);
+            if (prompt && promptCommandAvailable(name, CORE_PROMPT_NAMES, new Set(extensionCommands().byName.keys())))
                 return false;
             host.ui.notify(`Unknown command: /${name}. Use /help to list commands.`, 'error');
             return true;
         }
         try {
-            const session = host.session();
             switch (name) {
                 case 'help':
                     host.showHelp(groupTerminalCommands(completions()));
@@ -221,7 +277,7 @@ export function createTerminalCommands(host) {
                     await host.btw(argument);
                     break;
                 case 'stop': {
-                    if (!session.isStreaming)
+                    if (session.isIdle)
                         throw new Error('Nothing is running.');
                     await host.runtime().interrupt();
                     break;
@@ -232,11 +288,21 @@ export function createTerminalCommands(host) {
                 case 'session': {
                     let path = argument;
                     if (!path) {
-                        const sessions = await SessionManager.list(host.cwd(), host.sessionDirectory());
-                        const selected = await choose('Resume session', sessions, (item, index) => `${index + 1}. ${item.name ?? item.firstMessage ?? item.id}  ${item.modified.toLocaleString()}`);
+                        const selected = await host.ui.custom((tui, _theme, _keys, done) => {
+                            const page = new ResumeSessionsPage({
+                                theme: () => host.ui.theme,
+                                cwd: () => host.cwd(),
+                                branch: () => host.branch(),
+                                listSessions: signal => SessionManager.list(host.cwd(), host.sessionDirectory(), undefined, signal),
+                                select: done,
+                                cancel: () => done(undefined),
+                                changed: host.changed
+                            });
+                            return new PageOverlay({ page, tui, theme: () => host.ui.theme, close: () => done(undefined), changed: host.changed });
+                        }, { overlay: true, overlayOptions: pageOverlayOptions('fullscreen') });
                         if (!selected)
                             break;
-                        path = selected.path;
+                        path = selected;
                     }
                     const target = resolve(host.cwd(), path);
                     const within = relative(host.sessionDirectory(), target);
@@ -324,6 +390,21 @@ export function createTerminalCommands(host) {
                 case 'settings':
                     await openPage('settings');
                     break;
+                case 'doctor':
+                    await openPage('doctor');
+                    break;
+                case 'worktree':
+                    await openPage('worktree');
+                    break;
+                case 'trajectory':
+                    await openPage('trajectory', { runId: argument });
+                    break;
+                case 'subagents':
+                    await openPage('subagents');
+                    break;
+                case 'agents':
+                    await openPage('agents');
+                    break;
                 case 'permissions':
                     await openPage('permissions');
                     break;
@@ -395,5 +476,5 @@ export function createTerminalCommands(host) {
         }
         return true;
     }
-    return { execute, completions, skills, expandSkill };
+    return { execute, completions, skills, expandSkill, legacyAliases };
 }

package/dist/sdk/terminal/tui/list.d.ts

@@ -2,11 +2,20 @@ import type { Theme } from '@earendil-works/pi-coding-agent';
 import { type Component, type Focusable, type TuiMouseEventResult } from '@earendil-works/pi-tui';
 import { type TerminalMouseInput } from "./mouse.js";
 export type RowTone = 'success' | 'warning' | 'error' | 'muted' | 'dim' | 'accent';
+export interface ListLabelPart {
+    text: string;
+    color?: string;
+    tone?: RowTone;
+}
 export interface ListRow<T = unknown> {
     id: string;
     label: string;
+    /** Optional colored spans for the label; selected rows keep the shared high-contrast text. */
+    labelParts?: readonly ListLabelPart[];
     /** Shown at the right edge, in `tone`. */
     detail?: string;
+    /** An optional muted second line beneath the label. */
+    subtitle?: string;
     tone?: RowTone;
     /** Rows with the same consecutive group share a heading (not shown while searching). */
     group?: string;
@@ -22,6 +31,8 @@ export interface FilterListOptions<T> {
     search?: 'always' | 'never';
     /** Rows the list may use; the search field is part of it. Defaults to what `render` is given. */
     limit?: () => number;
+    /** Blank lines between visible rows. */
+    rowGap?: number;
     empty?: string;
     noun?: readonly [string, string];
     /** Short context included in the search row while a query is active. */
@@ -59,6 +70,7 @@ export declare class FilterList<T = unknown> implements Component, Focusable {
     handleMouse(event: TerminalMouseInput): TuiMouseEventResult | undefined;
     invalidate(): void;
     private limit;
+    private rowGap;
     private mode;
     private canSearch;
     private searchVisible;
@@ -67,7 +79,8 @@ export declare class FilterList<T = unknown> implements Component, Focusable {
     private move;
     handleInput(data: string): boolean;
     private entries;
-    private line;
+    private lines;
+    private labelParts;
     /** `rows` is the most the list may use, the search row included. */
     render(width: number, rows?: number): string[];
 }

package/dist/sdk/terminal/tui/list.js

@@ -1,4 +1,4 @@
-import { fuzzyFilter, matchesKey, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { fuzzyFilter, matchesKey, parseColor, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
 import { safeText, selectedRow, selectionMuted, selectionText } from "./chrome.js";
 import { SEARCH_FIELD_ROWS, SearchField, searchFieldRowsFor } from "./search.js";
 import { isPrimaryClick } from "./mouse.js";
@@ -25,7 +25,10 @@ export class FilterList {
     get total() { return this.rows.length; }
     get shown() { return this.visible.length; }
     /** Rows the list would use if nothing cut it: the search field, headings and rows. */
-    get height() { return (this.searchVisible() ? this.renderedSearchRows : 0) + this.entries().length; }
+    get height() {
+        return (this.searchVisible() ? this.renderedSearchRows : 0)
+            + this.entries().reduce((height, entry) => height + (entry.row?.subtitle === undefined ? 1 : 2), 0);
+    }
     /** Rows at the top of `render` that a frame must keep when it has to cut the list. */
     get pinnedRows() { return this.searchVisible() ? this.renderedSearchRows : 0; }
     setRows(rows) {
@@ -61,6 +64,10 @@ export class FilterList {
     }
     invalidate() { this.search.invalidate(); }
     limit() { return Math.max(1, Math.floor(this.options.limit?.() ?? Number.POSITIVE_INFINITY)); }
+    rowGap() {
+        const gap = this.options.rowGap ?? 0;
+        return Number.isFinite(gap) ? Math.max(0, Math.floor(gap)) : 0;
+    }
     mode() { return this.options.search ?? 'always'; }
     canSearch() { return this.mode() === 'always'; }
     searchVisible() { return this.canSearch() || this.query.length > 0; }
@@ -68,7 +75,7 @@ export class FilterList {
     refilter() {
         const query = this.query.trim();
         this.visible = query
-            ? fuzzyFilter(this.rows, query, row => row.searchText ?? `${row.label} ${row.detail ?? ''} ${row.group ?? ''}`)
+            ? fuzzyFilter(this.rows, query, row => row.searchText ?? `${row.label} ${row.subtitle ?? ''} ${row.detail ?? ''} ${row.group ?? ''}`)
             : this.rows;
         if (!this.visible.some(row => row.id === this.selectedId && !row.disabled))
             this.selectedId = this.firstSelectable()?.id;
@@ -136,15 +143,20 @@ export class FilterList {
     entries() {
         const entries = [];
         let last;
-        for (const row of this.visible) {
+        const gap = this.rowGap();
+        for (const [index, row] of this.visible.entries()) {
             if (!this.query && row.group && row.group !== last)
                 entries.push({ heading: row.group });
             last = row.group;
             entries.push({ row });
+            if (index < this.visible.length - 1) {
+                for (let line = 0; line < gap; line += 1)
+                    entries.push({ spacer: true });
+            }
         }
         return entries;
     }
-    line(row, width) {
+    lines(row, width) {
         const theme = this.options.theme();
         const selected = row.id === this.selectedId;
         const detail = row.detail ? safeText(row.detail) : '';
@@ -153,10 +165,40 @@ export class FilterList {
         const label = truncateToWidth(safeText(row.label), Math.max(0, room - (showDetail ? visibleWidth(detail) + 2 : 0)), '…');
         const gap = ' '.repeat(Math.max(0, room - visibleWidth(label) - (showDetail ? visibleWidth(detail) : 0)));
         const tone = (text) => theme.fg(row.tone ?? 'muted', text);
-        const main = (selected ? '❯ ' : '  ') + label;
-        if (selected)
-            return selectedRow(selectionText(theme, main) + gap + (showDetail ? selectionMuted(theme, detail) : ''), width, theme);
-        return (row.disabled ? theme.fg('dim', main) : main) + gap + (showDetail ? tone(detail) : '');
+        const prefix = selected ? '❯ ' : '  ';
+        const labelText = selected || row.disabled || !row.labelParts?.length ? label : this.labelParts(row.labelParts, label, theme);
+        const main = prefix + label;
+        const primary = selected
+            ? selectedRow(selectionText(theme, main) + gap + (showDetail ? selectionMuted(theme, detail) : ''), width, theme)
+            : (row.disabled ? theme.fg('dim', main) : prefix + labelText) + gap + (showDetail ? tone(detail) : '');
+        if (row.subtitle === undefined)
+            return [primary];
+        const subtitle = truncateToWidth(`  ${safeText(row.subtitle)}`, width, '…');
+        const secondary = selected
+            ? selectedRow(selectionMuted(theme, subtitle), width, theme)
+            : theme.fg(row.disabled ? 'dim' : 'muted', subtitle);
+        return [primary, secondary];
+    }
+    labelParts(parts, visibleLabel, theme) {
+        const source = parts.map(part => safeText(part.text)).join('');
+        const truncated = visibleWidth(source) > visibleWidth(visibleLabel);
+        let remaining = Math.max(0, visibleWidth(visibleLabel) - (truncated ? 1 : 0));
+        const output = [];
+        for (const part of parts) {
+            if (remaining <= 0)
+                break;
+            const text = safeText(part.text);
+            const fitted = truncateToWidth(text, remaining, '');
+            if (fitted) {
+                output.push(part.color ? theme.style(fitted, { fg: parseColor(part.color) }) : part.tone ? theme.fg(part.tone, fitted) : fitted);
+            }
+            remaining -= visibleWidth(fitted);
+            if (visibleWidth(fitted) < visibleWidth(text))
+                break;
+        }
+        if (truncated)
+            output.push('…');
+        return output.join('');
     }
     /** `rows` is the most the list may use, the search row included. */
     render(width, rows) {
@@ -186,11 +228,51 @@ export class FilterList {
             return lines.map(line => truncateToWidth(line, width, ''));
         }
         const at = Math.max(0, entries.findIndex(entry => entry.row?.id === this.selectedId));
-        const start = Math.max(0, Math.min(Math.max(0, entries.length - budget), at - Math.floor(budget / 2)));
-        for (const entry of entries.slice(start, start + budget)) {
-            lines.push(entry.row ? this.line(entry.row, width) : theme.fg('dim', safeText(entry.heading ?? '')));
-            this.renderedRows.push(entry.row);
+        let start = at;
+        let end = at + 1;
+        let used = entries[at]?.row?.subtitle === undefined ? 1 : 2;
+        let preferBefore = true;
+        while (start > 0 || end < entries.length) {
+            const before = entries[start - 1];
+            const after = entries[end];
+            const beforeHeight = before ? (before.row?.subtitle === undefined ? 1 : 2) : Number.POSITIVE_INFINITY;
+            const afterHeight = after ? (after.row?.subtitle === undefined ? 1 : 2) : Number.POSITIVE_INFINITY;
+            if (preferBefore && before && used + beforeHeight <= budget) {
+                start -= 1;
+                used += beforeHeight;
+            }
+            else if (after && used + afterHeight <= budget) {
+                end += 1;
+                used += afterHeight;
+            }
+            else if (before && used + beforeHeight <= budget) {
+                start -= 1;
+                used += beforeHeight;
+            }
+            else
+                break;
+            preferBefore = !preferBefore;
+        }
+        if (entries[start]?.spacer)
+            start += 1;
+        if (entries[end - 1]?.spacer)
+            end -= 1;
+        for (const entry of entries.slice(start, end)) {
+            if (entry.row) {
+                const rendered = this.lines(entry.row, width);
+                lines.push(...rendered);
+                this.renderedRows.push(...rendered.map(() => entry.row));
+            }
+            else if (entry.spacer) {
+                lines.push('');
+                this.renderedRows.push(undefined);
+            }
+            else {
+                lines.push(theme.fg('dim', safeText(entry.heading ?? '')));
+                this.renderedRows.push(undefined);
+            }
         }
-        return lines.map(line => truncateToWidth(line, width, ''));
+        this.renderedRows = this.renderedRows.slice(0, rowBudget);
+        return lines.slice(0, rowBudget).map(line => truncateToWidth(line, width, ''));
     }
 }