/** * 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 } | { 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(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 = { 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( commandId: string, params: JsonValue = {}, ): Promise> { try { const value = await invoke("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> { try { const value = await invoke("engine_list_commands"); return { ok: true, value }; } catch (reason: unknown) { return { ok: false, error: toEngineError(reason) }; } }