Lutra/ui/src/ipc.ts
danny 1a38e68480 M1.15: one modal at a time, restore dialog follows outside restores
- Modal rule (ui/src/commands/modals.ts): palette, settings dialog and the
  close question are exclusive; opening one closes the other. Running any
  command but palette.open (keyboard, palette, uiCommand) closes the
  palette. The restore dialog is queued: hidden while another modal is
  open, back with its list intact afterwards.
- recovery.restore / recovery.discard emit recoveryResolved {paths}; the
  restore dialog drops the settled paths and closes when none are left.
  Rust was needed: discard gave the UI no signal, and a restored entry
  stays in the journal as the buffer's own entry.
- Dimmed restored text (C2 screenshot 09) was the dialog overlay, not an
  editor style; no editor change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 21:49:38 +02:00

225 lines
7.2 KiB
TypeScript

/**
* Bridge from the frontend to the engine.
*
* Every user-visible action runs as an engine command through {@link run}.
* Calls never reject: failures come back as `{ ok: false, error }` so that
* every caller has to handle them. State changes arrive as engine events
* through {@link onEngineEvent}.
*/
import { invoke } from "@tauri-apps/api/core";
import { listen, type UnlistenFn } from "@tauri-apps/api/event";
/** Name of the Tauri event that carries engine events. */
export const ENGINE_EVENT = "engine://event";
/**
* An engine event as the desktop shell emits it: the engine's `Event`,
* tagged by `kind`. Paths are project-relative with `/`; the root is `""`.
*/
export type EngineEventPayload =
| { kind: "projectOpened"; root: string; name: string }
| { kind: "projectClosed" }
| { kind: "treeChanged"; dir: string }
| { kind: "bufferOpened"; id: number; path: string }
| { kind: "bufferFocused"; id: number }
| { kind: "bufferChanged"; id: number; version: number }
| { kind: "dirtyChanged"; id: number; dirty: boolean }
| { kind: "bufferClosed"; id: number }
| { kind: "fileChangedOnDisk"; path: string; id: number; removed: boolean }
| { kind: "watchFailed"; message: string }
| { kind: "themeChanged"; id: string; dark: boolean; tokens: Record<string, string> }
| {
kind: "settingsChanged";
/** Keys whose effective value changed; unchecked, it comes from the engine. */
keys: unknown;
}
| {
kind: "recoveryAvailable";
entries: { path: string; savedAt: number; diskChanged: boolean }[];
}
| {
kind: "notification";
/** Unique id (`n1`, `n2`…); unchecked, it comes from the engine. */
id: unknown;
/** `info`, `warning` or `error`; unchecked. */
level: unknown;
/** Catalog key of the text; unchecked. */
messageKey?: unknown;
/** English fallback text; unchecked. */
message?: unknown;
/** Placeholder values; unchecked. */
params?: unknown;
}
| {
kind: "uiCommand";
/** Id of the UI command to run; unchecked, it comes from the engine. */
id: unknown;
/** The params it was run with, as given; unchecked. */
params?: unknown;
}
| {
kind: "recoveryResolved";
/** Paths restored or discarded; unchecked, it comes from the engine. */
paths: unknown;
};
/** Callback receiving engine events. */
export type EngineEventHandler = (event: EngineEventPayload) => void;
/** Whether the shell was told that the frontend listens (`engine_ready`). */
let announced = false;
/** Subscriptions started but not yet registered with the shell. */
let pending = 0;
/** Subscriptions registered with the shell and not ended. */
let live = 0;
/**
* Tells the shell that the frontend listens, once, as soon as a
* subscription is live and no started one is still being registered.
* Subscriptions made while the page mounts all start in the same tick, so
* every one of them receives the replay. A failed announcement is retried
* by the next subscription.
*/
function announce(): void {
if (announced || pending > 0 || live === 0) {
return;
}
announced = true;
invoke("engine_ready").catch(() => {
announced = false;
});
}
/**
* Subscribes to engine events. Once the subscriptions started together are
* registered, the shell is told that the frontend listens, so it replays
* the current project state and the notifications the page may have missed
* while loading. Outside the Tauri shell (tests, a plain browser)
* subscribing fails quietly and no events arrive.
*
* @param handler - called for every event, in order of arrival.
* @returns a function that ends the subscription.
*/
export function onEngineEvent(handler: EngineEventHandler): () => void {
let unlisten: UnlistenFn | null = null;
let cancelled = false;
pending += 1;
listen<EngineEventPayload>(ENGINE_EVENT, (event) => {
handler(event.payload);
})
.then((fn) => {
pending -= 1;
if (cancelled) {
fn();
} else {
unlisten = fn;
live += 1;
}
announce();
})
.catch(() => {
pending -= 1;
announce();
});
return () => {
cancelled = true;
if (unlisten) {
unlisten();
unlisten = null;
live -= 1;
}
};
}
/** A JSON value as exchanged with the engine. */
export type JsonValue =
| null
| boolean
| number
| string
| JsonValue[]
| { [key: string]: JsonValue };
/** An error reported by the engine, with a stable machine-readable code. */
export interface EngineError {
/** Stable code such as `unknown_command`, `invalid_params` or `internal`. */
code: string;
/** Message for the user. */
message: string;
}
/** Outcome of an engine call. */
export type RunResult<T> = { ok: true; value: T } | { ok: false; error: EngineError };
/** Static description of a command, as listed by the engine. */
export interface CommandInfo {
/** Command id, e.g. `app.about`. */
id: string;
/** Label shown in menus and the command palette; for UI commands the catalog key. */
label: string;
/** Catalog key of the label; set for UI commands. */
labelKey?: string;
/** Menu path such as `Help/About Lutra`, or null if not in a menu. */
menuPath: string | null;
/** Default shortcut in Lutra notation (`Mod+Q`), or null. */
defaultShortcut: string | null;
/** Documentation of the params object. */
params: string;
/** Whether the command can run in the current state. */
enabled: boolean;
/** Whether the frontend registered the command (`ui.registerCommands`) and runs it. */
ui?: boolean;
}
/**
* Turns whatever a failed `invoke` rejected with into an {@link EngineError}.
*
* @param reason - the rejection value; the shell sends `{ code, message }`.
* @returns the engine error, or an `ipc` error for anything else (for example
* when the page runs outside the Tauri shell).
*/
export function toEngineError(reason: unknown): EngineError {
if (typeof reason === "object" && reason !== null && "code" in reason && "message" in reason) {
const { code, message } = reason;
if (typeof code === "string" && typeof message === "string") {
return { code, message };
}
}
const message = reason instanceof Error ? reason.message : String(reason);
return { code: "ipc", message };
}
/**
* Runs an engine command.
*
* @param commandId - the command id, e.g. `app.about`.
* @param params - the command's params object.
* @returns the command's result, or the error it failed with.
*/
export async function run<T = JsonValue>(
commandId: string,
params: JsonValue = {},
): Promise<RunResult<T>> {
try {
const value = await invoke<T>("engine_execute", { command: commandId, params });
return { ok: true, value };
} catch (reason: unknown) {
return { ok: false, error: toEngineError(reason) };
}
}
/**
* Lists every command the engine knows, with its current enabled state.
*
* @returns the commands, or the error the call failed with.
*/
export async function listCommands(): Promise<RunResult<CommandInfo[]>> {
try {
const value = await invoke<CommandInfo[]>("engine_list_commands");
return { ok: true, value };
} catch (reason: unknown) {
return { ok: false, error: toEngineError(reason) };
}
}