M1.8: command palette, global keymap, UI commands

- Engine: ui.registerCommands (validated, replaces the previous set),
  UI commands in listCommands with ui: true and labelKey, running one
  through the engine emits uiCommand {id, params}.
- Frontend: ui/src/commands/ (keymap by key code, fuzzy ranking, Pinia
  commands store with handlers, recents and error toasts), the command
  palette (Mod+Shift+P), UI commands palette.open, settings.open (Mod+,,
  disabled until M1.9b) and view.toggleProjectTree (Mod+1). The editor's
  shortcuts.ts moved into the global keymap.
- Tests: engine and control-channel tests for registration and
  uiCommand, Vitest for keymap, ranking, store, palette and App wiring.
- Docs: architecture, ui-parity, target-app-parity, gaps, roadmap,
  ROADMAP, README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-16 16:59:43 +02:00
parent 2f8fef876b
commit 184b8a3468
33 changed files with 2282 additions and 233 deletions

205
ui/src/commands/keymap.ts Normal file
View file

@ -0,0 +1,205 @@
/**
* The global keymap: default shortcuts of every command, engine and UI,
* matched against key presses by key code.
*
* Shortcuts are written in Lutra notation (`Mod+Alt+S`, `Mod` = Cmd on
* macOS, Ctrl elsewhere) and come from the command list (`listCommands`
* plus the UI commands); nothing here hard-codes a key.
*/
import { t } from "../i18n";
/** A parsed shortcut. */
export interface Shortcut {
/** Ctrl must be held. */
ctrl: boolean;
/** Meta (Cmd) must be held. */
meta: boolean;
/** Alt (Option) must be held. */
alt: boolean;
/** Shift must be held. */
shift: boolean;
/** The key, lower case (`s`, `f4`, `enter`, `,`). */
key: string;
}
/** One binding of the keymap. */
export interface Binding {
/** The command id. */
command: string;
/** The shortcut that runs it. */
shortcut: Shortcut;
}
/** Whether the frontend runs on macOS, where `Mod` means Cmd. */
export function isMac(): boolean {
return typeof navigator !== "undefined" && /Mac OS X|Macintosh|iPhone|iPad/.test(navigator.userAgent);
}
/**
* Parses a shortcut in Lutra notation.
*
* @param text - for example `Mod+Alt+S`; a trailing `+` is the plus key
* (`Mod++`).
* @param mac - whether `Mod` means Cmd.
* @returns the shortcut, or null when the text has no key or an unknown modifier.
*/
export function parseShortcut(text: string, mac: boolean): Shortcut | null {
const plusKey = text.endsWith("++");
const parts = (plusKey ? text.slice(0, -2) : text).split("+").map((part) => part.trim().toLowerCase());
const key = plusKey ? "+" : parts.pop();
if (key === undefined || key === "") {
return null;
}
const shortcut: Shortcut = { ctrl: false, meta: false, alt: false, shift: false, key };
for (const part of parts) {
switch (part) {
case "":
if (!plusKey) {
return null;
}
break;
case "mod":
if (mac) {
shortcut.meta = true;
} else {
shortcut.ctrl = true;
}
break;
case "ctrl":
shortcut.ctrl = true;
break;
case "cmd":
case "meta":
shortcut.meta = true;
break;
case "alt":
shortcut.alt = true;
break;
case "shift":
shortcut.shift = true;
break;
default:
return null;
}
}
return shortcut;
}
/** Punctuation keys by `KeyboardEvent.code`, as the US layout labels them. */
const PUNCTUATION: Readonly<Record<string, string>> = {
Comma: ",",
Period: ".",
Slash: "/",
Semicolon: ";",
Quote: "'",
BracketLeft: "[",
BracketRight: "]",
Backslash: "\\",
Minus: "-",
Equal: "=",
Backquote: "`",
};
/**
* The key of an event, independent of the keyboard layout effects of Alt
* and Shift for letters, digits and punctuation (`Alt+S` on macOS types
* `ß`, `Shift+1` types `!`).
*
* @param event - the key event.
*/
export function eventKey(event: KeyboardEvent): string {
const code = event.code;
if (/^Key[A-Z]$/.test(code)) {
return code.slice(3).toLowerCase();
}
if (/^(Digit|Numpad)[0-9]$/.test(code)) {
return code.slice(-1);
}
const punctuation = PUNCTUATION[code];
if (punctuation !== undefined) {
return punctuation;
}
return event.key.toLowerCase();
}
/**
* Whether a key event matches a shortcut exactly.
*
* @param event - the key event.
* @param shortcut - the shortcut.
*/
export function matches(event: KeyboardEvent, shortcut: Shortcut): boolean {
return (
event.ctrlKey === shortcut.ctrl &&
event.metaKey === shortcut.meta &&
event.altKey === shortcut.alt &&
event.shiftKey === shortcut.shift &&
eventKey(event) === shortcut.key
);
}
/**
* Builds the keymap from command descriptions. Commands without a shortcut
* or with one that does not parse are left out; when two commands share a
* shortcut, the first one listed wins.
*
* @param commands - id and default shortcut of each command.
* @param mac - whether `Mod` means Cmd.
*/
export function buildKeymap(
commands: readonly { id: string; defaultShortcut?: string | null | undefined }[],
mac: boolean,
): Binding[] {
const keymap: Binding[] = [];
for (const command of commands) {
const raw: unknown = command.defaultShortcut;
const shortcut = typeof raw === "string" ? parseShortcut(raw, mac) : null;
if (shortcut) {
keymap.push({ command: command.id, shortcut });
}
}
return keymap;
}
/**
* The command a key event triggers.
*
* @param keymap - the keymap.
* @param event - the key event.
* @returns the command id, or null.
*/
export function commandFor(keymap: readonly Binding[], event: KeyboardEvent): string | null {
return keymap.find((binding) => matches(event, binding.shortcut))?.command ?? null;
}
/**
* Formats a shortcut for display: modifier names from the catalog, in the
* order Ctrl, Alt, Shift, Cmd, and the key in upper case
* (`Ctrl+Shift+P`, `Cmd+,`).
*
* @param text - the shortcut in Lutra notation.
* @param mac - whether `Mod` means Cmd.
* @returns the display text, or null when the shortcut does not parse.
*/
export function formatShortcut(text: string, mac: boolean): string | null {
const shortcut = parseShortcut(text, mac);
if (shortcut === null) {
return null;
}
const parts: string[] = [];
if (shortcut.ctrl) {
parts.push(t("command.key.ctrl"));
}
if (shortcut.alt) {
parts.push(mac ? t("command.key.option") : t("command.key.alt"));
}
if (shortcut.shift) {
parts.push(t("command.key.shift"));
}
if (shortcut.meta) {
parts.push(t("command.key.cmd"));
}
const key = shortcut.key;
parts.push(key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1));
return parts.join("+");
}

189
ui/src/commands/rank.ts Normal file
View file

@ -0,0 +1,189 @@
/**
* Fuzzy ranking of commands for the palette.
*
* A query matches a command's label (the catalog text) or its id. Matches
* fall into tiers, best first: the text starts with the query; a word of
* the text starts with it; the query is spread over the starts of
* consecutive words (`togpro` → "Toggle Project"); the text contains it;
* its characters appear in order. Within a tier, recently run commands come
* first, then shorter texts, then the label alphabetically. Without a query
* every command is listed, recent ones first.
*/
/** Tier of a match; higher is better. */
export const Tier = {
/** Characters of the query appear in order. */
Fuzzy: 1,
/** The text contains the query. */
Substring: 2,
/** The query is spread over the starts of consecutive words. */
WordStarts: 3,
/** A word of the text starts with the query. */
WordPrefix: 4,
/** The text starts with the query. */
Prefix: 5,
} as const;
/** Longest query considered; longer ones are cut. */
export const MAX_QUERY = 100;
/** A match: its tier and how well it fits within the tier (higher is better). */
export interface Match {
/** The tier. */
tier: number;
/** Fit within the tier; shorter texts and tighter matches fit better. */
fit: number;
}
/** What the ranking needs of a command. */
export interface Rankable {
/** Command id. */
id: string;
/** Label as shown. */
label: string;
}
/**
* Splits a text into lower-case words at spaces, punctuation and camelCase
* boundaries (`view.toggleProjectTree` → view, toggle, project, tree).
*
* @param text - the text.
*/
export function words(text: string): string[] {
return text
.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
.toLowerCase()
.split(/[^\p{L}\p{N}]+/u)
.filter((word) => word !== "");
}
/**
* Whether the query can be split into pieces that start consecutive words,
* in order, each piece starting a later word than the one before.
*
* @param query - the query, lower case, without spaces.
* @param list - the words of the text.
*/
function spreadOverWordStarts(query: string, list: readonly string[]): boolean {
const memo = new Map<string, boolean>();
const from = (q: number, w: number): boolean => {
if (q === query.length) {
return true;
}
const memoKey = `${String(q)}:${String(w)}`;
const known = memo.get(memoKey);
if (known !== undefined) {
return known;
}
let found = false;
for (let i = w; i < list.length && !found; i += 1) {
const word = list[i] ?? "";
let k = 0;
while (k < word.length && q + k < query.length && word[k] === query[q + k]) {
k += 1;
}
for (let take = k; take >= 1 && !found; take -= 1) {
found = from(q + take, i + 1);
}
}
memo.set(memoKey, found);
return found;
};
return from(0, 0);
}
/**
* Matches a query against one text.
*
* @param query - the query; case and surrounding spaces are ignored.
* @param text - the label or id.
* @returns the match, or null if the query does not match.
*/
export function matchText(query: string, text: string): Match | null {
const q = query.trim().toLowerCase().slice(0, MAX_QUERY);
const lower = text.toLowerCase();
const length = -text.length;
if (q === "") {
return { tier: Tier.Prefix, fit: length };
}
if (lower.startsWith(q)) {
return { tier: Tier.Prefix, fit: length };
}
const list = words(text);
if (list.some((_, i) => list.slice(i).join(" ").startsWith(q))) {
return { tier: Tier.WordPrefix, fit: length };
}
const compact = q.replace(/\s+/g, "");
if (compact !== "" && spreadOverWordStarts(compact, list)) {
return { tier: Tier.WordStarts, fit: length };
}
const at = lower.indexOf(q);
if (at >= 0) {
return { tier: Tier.Substring, fit: length - at };
}
let gaps = 0;
let pos = -1;
for (const ch of compact) {
const next = lower.indexOf(ch, pos + 1);
if (next < 0) {
return null;
}
if (pos >= 0) {
gaps += next - pos - 1;
}
pos = next;
}
return compact === "" ? null : { tier: Tier.Fuzzy, fit: -gaps * 100 + length };
}
/**
* The better of two matches.
*
* @param a - a match or null.
* @param b - a match or null.
*/
function better(a: Match | null, b: Match | null): Match | null {
if (a === null) {
return b;
}
if (b === null) {
return a;
}
if (a.tier !== b.tier) {
return a.tier > b.tier ? a : b;
}
return a.fit >= b.fit ? a : b;
}
/**
* Ranks commands for a query.
*
* @param items - the commands.
* @param query - what the user typed.
* @param recent - ids of recently run commands, most recent first.
* @returns the matching commands, best first.
*/
export function rank<T extends Rankable>(items: readonly T[], query: string, recent: readonly string[]): T[] {
const recency = new Map(recent.map((id, i) => [id, i]));
const scored: { item: T; match: Match; recent: number }[] = [];
for (const item of items) {
const match = better(matchText(query, item.label), matchText(query, item.id));
if (match !== null) {
scored.push({ item, match, recent: recency.get(item.id) ?? Number.MAX_SAFE_INTEGER });
}
}
const empty = query.trim() === "";
scored.sort((a, b) => {
if (!empty && a.match.tier !== b.match.tier) {
return b.match.tier - a.match.tier;
}
if (a.recent !== b.recent) {
return a.recent - b.recent;
}
if (!empty && a.match.fit !== b.match.fit) {
return b.match.fit - a.match.fit;
}
return a.item.label.localeCompare(b.item.label);
});
return scored.map((entry) => entry.item);
}

301
ui/src/commands/store.ts Normal file
View file

@ -0,0 +1,301 @@
/**
* The command store: every command the user can reach, engine and UI, the
* global keymap built from their default shortcuts, and running commands
* from the keyboard, the palette and `uiCommand` events.
*
* - **List:** `listCommands` from the engine, refreshed when a project opens
* or closes and whenever the palette opens, plus the UI commands of
* {@link UI_COMMANDS} (also before the engine lists them).
* - **Keymap:** one listener on the window in the capture phase, so
* shortcuts also work while CodeMirror or an input has the focus. A
* disabled command's shortcut is swallowed and does nothing.
* - **Handlers:** components supply the behaviour of UI commands and the
* context of engine commands (the editor runs `file.save` with the active
* buffer) with {@link useCommandsStore}'s `provide`. Other engine
* commands run with empty params.
* - **Errors:** a failed command raises an error toast (M1.12).
*/
import { defineStore } from "pinia";
import { computed, ref, shallowReactive } from "vue";
import { hasMessage, t } from "../i18n";
import { listCommands, onEngineEvent, run, type CommandInfo, type EngineEventPayload, type JsonValue } from "../ipc";
import { useNotificationsStore } from "../stores/notifications";
import { buildKeymap, commandFor, formatShortcut, isMac } from "./keymap";
import { UI_COMMANDS } from "./uiCommands";
/** Behaviour a component supplies for a command. */
export interface CommandHandler {
/**
* Runs the command.
*
* @param params - the params it was run with (`{}` from the keyboard and
* the palette, as given in a `uiCommand` event).
*/
run: (params: JsonValue) => void | Promise<void>;
/** Whether it can run now; always when absent. Reactive reads update the palette. */
enabled?: () => boolean;
}
/** A command as the palette shows it. */
export interface PaletteEntry {
/** Command id. */
id: string;
/** Label: the catalog text for UI commands, the engine's label otherwise. */
label: string;
/** Default shortcut formatted for display, or null. */
shortcut: string | null;
/** Whether it can run now. */
enabled: boolean;
}
/** Most recently run commands remembered. */
export const MAX_RECENT = 20;
/**
* Reads the command list from the engine, keeping well-formed entries.
*
* @param raw - the `listCommands` result.
*/
function toCommandInfos(raw: unknown): CommandInfo[] | null {
if (!Array.isArray(raw)) {
return null;
}
return (raw as unknown[]).filter(
(c): c is CommandInfo =>
typeof c === "object" &&
c !== null &&
"id" in c &&
typeof c.id === "string" &&
"label" in c &&
typeof c.label === "string",
);
}
/**
* The label of a command: the catalog text of its `labelKey` when the
* catalog has it, else the engine's label.
*
* @param info - the command.
*/
function labelOf(info: CommandInfo): string {
return typeof info.labelKey === "string" && hasMessage(info.labelKey) ? t(info.labelKey) : info.label;
}
/** Store of the commands, the keymap and the recently run commands. */
export const useCommandsStore = defineStore("commands", () => {
const notifications = useNotificationsStore();
/** Commands as the engine lists them; empty until loaded. */
const infos = ref<CommandInfo[]>([]);
/** Handlers supplied by components, by command id. */
const handlers = shallowReactive(new Map<string, CommandHandler>());
/** Ids of recently run commands, most recent first. */
const recent = ref<string[]>([]);
/** Whether `Mod` means Cmd. */
const mac = isMac();
/** Ends the engine event subscription; set while started. */
let unsubscribe: (() => void) | null = null;
/** Every command: the engine's list plus UI commands it does not list yet. */
const all = computed<CommandInfo[]>(() => {
const listed = new Set(infos.value.map((info) => info.id));
const local = UI_COMMANDS.filter((spec) => !listed.has(spec.id)).map(
(spec): CommandInfo => ({
id: spec.id,
label: spec.labelKey,
labelKey: spec.labelKey,
menuPath: spec.menuPath ?? null,
defaultShortcut: spec.defaultShortcut ?? null,
params: "",
enabled: true,
ui: true,
}),
);
return [...infos.value, ...local];
});
/** The keymap of every command with a default shortcut. */
const keymap = computed(() => buildKeymap(all.value, mac));
/**
* Whether a command can run now: its handler decides if it has one; a UI
* command without a handler cannot run; otherwise the engine's state.
*
* @param id - the command id.
*/
function isEnabled(id: string): boolean {
const handler = handlers.get(id);
if (handler) {
return handler.enabled?.() ?? true;
}
const info = all.value.find((c) => c.id === id);
return info !== undefined && info.ui !== true && info.enabled;
}
/**
* The commands the palette offers: UI commands and engine commands that
* are user actions (they have a menu path or a default shortcut), not
* the protocol commands clients call with data (`buffer.edit`).
*/
const entries = computed<PaletteEntry[]>(() =>
all.value
.filter((info) => info.ui === true || info.menuPath !== null || info.defaultShortcut !== null)
.map((info) => ({
id: info.id,
label: labelOf(info),
shortcut: typeof info.defaultShortcut === "string" ? formatShortcut(info.defaultShortcut, mac) : null,
enabled: isEnabled(info.id),
})),
);
/**
* Supplies the behaviour of a command.
*
* @param id - the command id.
* @param handler - what running it does.
* @returns a function that withdraws the handler (only if it is still this one).
*/
function provide(id: string, handler: CommandHandler): () => void {
handlers.set(id, handler);
return () => {
if (handlers.get(id) === handler) {
handlers.delete(id);
}
};
}
/**
* Remembers a command as run most recently. Opening the palette itself
* is not remembered: it would always head the list it opens.
*
* @param id - the command id.
*/
function remember(id: string): void {
if (id === "palette.open") {
return;
}
recent.value = [id, ...recent.value.filter((other) => other !== id)].slice(0, MAX_RECENT);
}
/**
* Runs a command the user chose (keyboard or palette): through its
* handler if a component supplied one, else through the engine. A
* disabled command does nothing. A failure raises an error toast.
*
* @param id - the command id.
* @param params - the params.
*/
async function execute(id: string, params: JsonValue = {}): Promise<void> {
if (!isEnabled(id)) {
return;
}
remember(id);
const handler = handlers.get(id);
if (handler) {
try {
await handler.run(params);
} catch (reason: unknown) {
notifications.notifyError(id, {
code: "internal",
message: reason instanceof Error ? reason.message : String(reason),
});
}
return;
}
const result = await run(id, params);
if (!result.ok) {
notifications.notifyError(id, result.error);
}
}
/**
* Runs a UI command the engine dispatched (`uiCommand`). One without a
* handler, or disabled now, raises a warning toast instead, so an agent
* learns that nothing happened.
*
* @param id - the command id; unchecked, it comes from the engine.
* @param params - its params.
*/
async function dispatch(id: unknown, params: unknown): Promise<void> {
const name = typeof id === "string" ? id : String(id);
const handler = handlers.get(name);
if (!handler || !(handler.enabled?.() ?? true)) {
notifications.notify({ level: "warning", message: t("command.unavailable", { command: name }) });
return;
}
await execute(name, (params ?? {}) as JsonValue);
}
/** Loads the command list from the engine; a failure raises an error toast. */
async function refresh(): Promise<void> {
const result = await listCommands();
const list = result.ok ? toCommandInfos(result.value) : null;
if (list) {
infos.value = list;
} else {
notifications.notifyError(
"listCommands",
result.ok
? { code: "ipc", message: t("common.error.unexpectedResult", { command: "listCommands" }) }
: result.error,
);
}
}
/**
* Handles an engine event: runs `uiCommand`s and refreshes the enabled
* states when a project opens or closes.
*
* @param event - the engine event.
*/
function onEvent(event: EngineEventPayload): void {
if (event.kind === "uiCommand") {
void dispatch(event.id, event.params);
} else if (event.kind === "projectOpened" || event.kind === "projectClosed") {
void refresh();
}
}
/**
* Runs the command bound to a key press.
*
* @param event - a key press anywhere in the window.
*/
function onKeydown(event: KeyboardEvent): void {
const id = commandFor(keymap.value, event);
if (id === null) {
return;
}
event.preventDefault();
event.stopPropagation();
void execute(id);
}
/**
* Starts the keymap and the `uiCommand` subscription, registers the UI
* commands with the engine and loads the command list. Starting twice is
* a no-op.
*/
async function start(): Promise<void> {
if (unsubscribe) {
return;
}
unsubscribe = onEngineEvent(onEvent);
window.addEventListener("keydown", onKeydown, true);
const registered = await run("ui.registerCommands", {
commands: UI_COMMANDS.map((spec) => ({ ...spec })),
});
if (!registered.ok) {
notifications.notifyError("ui.registerCommands", registered.error);
}
await refresh();
}
/** Stops the keymap and the subscription. */
function stop(): void {
window.removeEventListener("keydown", onKeydown, true);
unsubscribe?.();
unsubscribe = null;
}
return { infos, recent, keymap, entries, isEnabled, provide, execute, dispatch, refresh, start, stop };
});

View file

@ -0,0 +1,27 @@
/**
* UI commands: commands the frontend runs itself. They are registered with
* the engine (`ui.registerCommands`) so `listCommands`, the palette, the
* keymap and agents see them; running one through the engine comes back as
* a `uiCommand` event. Components supply the behaviour with
* `useCommandsStore().provide(id, handler)`; a UI command nobody provides
* is disabled.
*/
/** A UI command as registered with the engine. */
export interface UiCommandSpec {
/** Command id, `area.action` in camelCase. */
id: string;
/** Catalog key of the label. */
labelKey: string;
/** Menu path with `/` separators. */
menuPath?: string;
/** Default shortcut in Lutra notation. */
defaultShortcut?: string;
}
/** The frontend's UI commands. */
export const UI_COMMANDS: readonly UiCommandSpec[] = [
{ id: "palette.open", labelKey: "command.palette.open", defaultShortcut: "Mod+Shift+P" },
{ id: "settings.open", labelKey: "command.settings.open", defaultShortcut: "Mod+," },
{ id: "view.toggleProjectTree", labelKey: "command.view.toggleProjectTree", defaultShortcut: "Mod+1" },
];