diff --git a/docs/development.md b/docs/development.md
index 95665c9..bc9306d 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -1,11 +1,11 @@
# Development
-> **Status:** draft · **Last updated:** 2026-10-13
+> **Status:** draft · **Last updated:** 2026-10-14
## Prerequisites
- Rust stable (via rustup), edition 2024
-- Node.js 20 or newer and pnpm
+- Node.js 22.12 or newer (Vite 8 needs it) and pnpm 10
- Tauri 2 system prerequisites for your platform (WebView2 on Windows, WebKitGTK on Linux)
- Optional: Phpactor on the PATH for language features, PHP 8.2+ and Composer for reference projects
@@ -29,4 +29,5 @@ No inline comments. Doc comment blocks above modules, functions, types and field
| Date | Change | Summary |
|---|---|---|
+| 2026-10-14 | minor | Node.js 22.12+ required by the frontend toolchain |
| 2026-10-13 | major | Initial draft |
diff --git a/ui/eslint.config.js b/ui/eslint.config.js
new file mode 100644
index 0000000..e2db329
--- /dev/null
+++ b/ui/eslint.config.js
@@ -0,0 +1,43 @@
+/**
+ * ESLint flat configuration of the Lutra frontend.
+ *
+ * Type-aware TypeScript rules apply to `.ts` and `.vue` files. Floating and
+ * misused promises are errors so that no rejection goes unhandled, `any`
+ * is an error, and inline comments are banned in favour of TSDoc blocks.
+ */
+import js from "@eslint/js";
+import { defineConfig } from "eslint/config";
+import pluginVue from "eslint-plugin-vue";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+import vueParser from "vue-eslint-parser";
+
+export default defineConfig(
+ { ignores: ["dist/**", "node_modules/**", "coverage/**"] },
+ js.configs.recommended,
+ tseslint.configs.strictTypeChecked,
+ pluginVue.configs["flat/recommended"],
+ {
+ languageOptions: {
+ parser: vueParser,
+ parserOptions: {
+ parser: tseslint.parser,
+ projectService: true,
+ tsconfigRootDir: import.meta.dirname,
+ extraFileExtensions: [".vue"],
+ },
+ globals: { ...globals.browser },
+ },
+ rules: {
+ "@typescript-eslint/no-floating-promises": "error",
+ "@typescript-eslint/no-misused-promises": "error",
+ "@typescript-eslint/no-explicit-any": "error",
+ "no-inline-comments": "error",
+ },
+ },
+ {
+ files: ["**/*.js"],
+ extends: [tseslint.configs.disableTypeChecked],
+ languageOptions: { globals: { ...globals.node } },
+ },
+);
diff --git a/ui/index.html b/ui/index.html
new file mode 100644
index 0000000..f28a346
--- /dev/null
+++ b/ui/index.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+ Lutra
+
+
+
+
+
+
diff --git a/ui/package.json b/ui/package.json
index 20a2372..2e4c50d 100644
--- a/ui/package.json
+++ b/ui/package.json
@@ -4,6 +4,10 @@
"version": "0.0.0",
"license": "MIT OR Apache-2.0",
"type": "module",
+ "engines": {
+ "node": ">=22.12"
+ },
+ "packageManager": "pnpm@10.34.7",
"scripts": {
"dev": "vite",
"build": "vue-tsc --noEmit && vite build",
diff --git a/ui/src/App.vue b/ui/src/App.vue
new file mode 100644
index 0000000..ffda0ad
--- /dev/null
+++ b/ui/src/App.vue
@@ -0,0 +1,49 @@
+
+
+
+
+
+
+ {{ app.about?.slogan ?? "" }}
+
+
+
+
+
+
+
diff --git a/ui/src/components/StatusBar.vue b/ui/src/components/StatusBar.vue
new file mode 100644
index 0000000..0c837bb
--- /dev/null
+++ b/ui/src/components/StatusBar.vue
@@ -0,0 +1,45 @@
+
+
+
+
+
+
+
diff --git a/ui/src/env.d.ts b/ui/src/env.d.ts
new file mode 100644
index 0000000..c980c07
--- /dev/null
+++ b/ui/src/env.d.ts
@@ -0,0 +1,10 @@
+/**
+ * Module declaration for single-file components, so that tools without Vue
+ * support (the ESLint type checker) see `.vue` imports as components.
+ * `vue-tsc` resolves the real component types.
+ */
+declare module "*.vue" {
+ import type { DefineComponent } from "vue";
+ const component: DefineComponent;
+ export default component;
+}
diff --git a/ui/src/ipc.ts b/ui/src/ipc.ts
new file mode 100644
index 0000000..cefb2a9
--- /dev/null
+++ b/ui/src/ipc.ts
@@ -0,0 +1,95 @@
+/**
+ * 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.
+ */
+import { invoke } from "@tauri-apps/api/core";
+
+/** 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. */
+ label: 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;
+}
+
+/**
+ * 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) };
+ }
+}
diff --git a/ui/src/main.ts b/ui/src/main.ts
new file mode 100644
index 0000000..1d592bc
--- /dev/null
+++ b/ui/src/main.ts
@@ -0,0 +1,10 @@
+/**
+ * Entry point of the Lutra frontend: creates the Vue app with Pinia and
+ * mounts it on `#app`.
+ */
+import { createPinia } from "pinia";
+import { createApp } from "vue";
+import App from "./App.vue";
+import "./styles/base.css";
+
+createApp(App).use(createPinia()).mount("#app");
diff --git a/ui/src/stores/app.ts b/ui/src/stores/app.ts
new file mode 100644
index 0000000..b957792
--- /dev/null
+++ b/ui/src/stores/app.ts
@@ -0,0 +1,38 @@
+/**
+ * Application-wide state: product information from `app.about` and the
+ * last error the shell reported.
+ */
+import { defineStore } from "pinia";
+import { ref } from "vue";
+import { run, type EngineError } from "../ipc";
+
+/** Result of the `app.about` command. */
+export interface AboutInfo {
+ /** Product name. */
+ name: string;
+ /** Version of the running build. */
+ version: string;
+ /** Slogan shown in the About window. */
+ slogan: string;
+}
+
+/** Store holding product information and the last engine error. */
+export const useAppStore = defineStore("app", () => {
+ /** Product information, null until loaded. */
+ const about = ref(null);
+ /** Last error from the engine, null if none. */
+ const lastError = ref(null);
+
+ /** Loads product information from the engine; on failure records the error. */
+ async function loadAbout(): Promise {
+ const result = await run("app.about");
+ if (result.ok) {
+ about.value = result.value;
+ lastError.value = null;
+ } else {
+ lastError.value = result.error;
+ }
+ }
+
+ return { about, lastError, loadAbout };
+});
diff --git a/ui/src/styles/base.css b/ui/src/styles/base.css
new file mode 100644
index 0000000..a390fe5
--- /dev/null
+++ b/ui/src/styles/base.css
@@ -0,0 +1,19 @@
+/**
+ * Base layout of the Lutra window. Colours and fonts come only from the
+ * theme tokens (`--lt-*`) that the desktop shell injects before first paint.
+ */
+html,
+body,
+#app {
+ height: 100%;
+ margin: 0;
+}
+
+body {
+ background: var(--lt-bg);
+ color: var(--lt-fg);
+ font-family: var(--lt-font-ui);
+ font-size: var(--lt-font-size-ui);
+ overflow: hidden;
+ user-select: none;
+}
diff --git a/ui/tests/App.test.ts b/ui/tests/App.test.ts
new file mode 100644
index 0000000..b391795
--- /dev/null
+++ b/ui/tests/App.test.ts
@@ -0,0 +1,36 @@
+/**
+ * Tests for the root component: it loads product information on mount and
+ * shows it, or the error, in the status bar.
+ */
+import { flushPromises, mount } from "@vue/test-utils";
+import { createPinia, setActivePinia } from "pinia";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const invoke = vi.hoisted(() => vi.fn());
+vi.mock("@tauri-apps/api/core", () => ({ invoke }));
+
+import App from "../src/App.vue";
+
+describe("App", () => {
+ beforeEach(() => {
+ invoke.mockReset();
+ setActivePinia(createPinia());
+ });
+
+ it("shows name and version in the status bar", async () => {
+ invoke.mockResolvedValue({ name: "Lutra", version: "0.0.0", slogan: "An otterly perfect IDE" });
+ const wrapper = mount(App);
+ await flushPromises();
+ expect(wrapper.get("[data-test=status-bar]").text()).toBe("Lutra 0.0.0");
+ expect(wrapper.get("[data-test=main]").text()).toBe("An otterly perfect IDE");
+ });
+
+ it("shows the engine error when the call fails", async () => {
+ invoke.mockRejectedValue({ code: "internal", message: "engine unavailable" });
+ const wrapper = mount(App);
+ await flushPromises();
+ const bar = wrapper.get("[data-test=status-bar]");
+ expect(bar.text()).toBe("engine unavailable");
+ expect(bar.classes()).toContain("status-bar--error");
+ });
+});
diff --git a/ui/tests/ipc.test.ts b/ui/tests/ipc.test.ts
new file mode 100644
index 0000000..c02054d
--- /dev/null
+++ b/ui/tests/ipc.test.ts
@@ -0,0 +1,55 @@
+/**
+ * Tests for the engine bridge: results and every kind of rejection map to
+ * a `RunResult` instead of a rejected promise.
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const invoke = vi.hoisted(() => vi.fn());
+vi.mock("@tauri-apps/api/core", () => ({ invoke }));
+
+import { listCommands, run, toEngineError } from "../src/ipc";
+
+describe("run", () => {
+ beforeEach(() => {
+ invoke.mockReset();
+ });
+
+ it("passes command and params to the shell", async () => {
+ invoke.mockResolvedValue({ name: "Lutra" });
+ const result = await run("app.about", { verbose: true });
+ expect(invoke).toHaveBeenCalledWith("engine_execute", {
+ command: "app.about",
+ params: { verbose: true },
+ });
+ expect(result).toEqual({ ok: true, value: { name: "Lutra" } });
+ });
+
+ it("returns engine errors instead of rejecting", async () => {
+ invoke.mockRejectedValue({ code: "unknown_command", message: "no such command: x" });
+ const result = await run("x");
+ expect(result).toEqual({
+ ok: false,
+ error: { code: "unknown_command", message: "no such command: x" },
+ });
+ });
+
+ it("wraps unexpected rejections", async () => {
+ invoke.mockRejectedValue(new Error("window.__TAURI_INTERNALS__ is undefined"));
+ const result = await run("app.about");
+ expect(result.ok).toBe(false);
+ expect(result.ok ? null : result.error.code).toBe("ipc");
+ });
+
+ it("lists commands", async () => {
+ invoke.mockResolvedValue([]);
+ expect(await listCommands()).toEqual({ ok: true, value: [] });
+ expect(invoke).toHaveBeenCalledWith("engine_list_commands");
+ });
+});
+
+describe("toEngineError", () => {
+ it("handles strings and malformed objects", () => {
+ expect(toEngineError("boom")).toEqual({ code: "ipc", message: "boom" });
+ expect(toEngineError({ code: 1, message: "x" }).code).toBe("ipc");
+ });
+});
diff --git a/ui/tsconfig.json b/ui/tsconfig.json
new file mode 100644
index 0000000..5a66e76
--- /dev/null
+++ b/ui/tsconfig.json
@@ -0,0 +1,22 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
+ "types": ["node", "vite/client"],
+ "strict": true,
+ "noUncheckedIndexedAccess": true,
+ "noImplicitOverride": true,
+ "exactOptionalPropertyTypes": true,
+ "noFallthroughCasesInSwitch": true,
+ "isolatedModules": true,
+ "verbatimModuleSyntax": true,
+ "useDefineForClassFields": true,
+ "resolveJsonModule": true,
+ "skipLibCheck": true,
+ "noEmit": true,
+ "jsx": "preserve"
+ },
+ "include": ["src/**/*.ts", "src/**/*.vue", "tests/**/*.ts", "vite.config.ts"]
+}
diff --git a/ui/vite.config.ts b/ui/vite.config.ts
new file mode 100644
index 0000000..d8a9a62
--- /dev/null
+++ b/ui/vite.config.ts
@@ -0,0 +1,15 @@
+/**
+ * Vite and Vitest configuration of the Lutra frontend.
+ *
+ * The dev server port is fixed because the Tauri shell loads it as `devUrl`.
+ */
+import { defineConfig } from "vitest/config";
+import vue from "@vitejs/plugin-vue";
+
+export default defineConfig({
+ plugins: [vue()],
+ clearScreen: false,
+ server: { port: 5173, strictPort: true },
+ build: { target: "es2022", outDir: "dist" },
+ test: { environment: "jsdom", include: ["tests/**/*.test.ts"] },
+});