TermKit 0.2.1: curation integrity and Studio hierarchy

.github/workflows/ci.yml

@@ -43,6 +43,10 @@ jobs:
         working-directory: apps/studio
       - run: bun run build
         working-directory: apps/studio
+      - run: bun x playwright install --with-deps chromium
+        working-directory: apps/studio
+      - run: bun run test:e2e
+        working-directory: apps/studio
       - run: uv run python scripts/embed_studio_assets.py --check
       - run: uv build
       - name: Rehearse example pack

.gitignore

@@ -23,4 +23,6 @@ site/
 apps/studio/node_modules/
 apps/studio/dist/
 apps/studio/*.tsbuildinfo
+apps/studio/test-results/
+apps/studio/playwright-report/
 *.termdb

README.md

@@ -22,7 +22,7 @@ or translation provider.
 > TermKit is pre-alpha. TermSpec 0.2 and the local Studio are implemented as the
 > long-term architecture, but public compatibility is not guaranteed until 1.0.
 
-![TermKit Studio concept workspace](.github/screenshots/studio-concepts.jpg)
+![TermKit Studio concept workspace](.github/screenshots/studio-concepts-v2.png)
 
 TermKit Studio keeps concept identity, multilingual lexical entries, evidence,
 relations and revision state visible in one dense workspace. Canonical files do
@@ -116,15 +116,21 @@ reconciliation capabilities, not at the center of the product.
 
 ### Review semantic changes
 
-![TermKit Studio review workspace](.github/screenshots/studio-review.jpg)
+![TermKit Studio draft inbox](.github/screenshots/studio-drafts-v2.png)
+
+Every edit is autosaved as one atomic ChangeSet. Draft Inbox is the shared
+continuation point for inspecting, submitting, rebasing, applying or discarding
+work without implying that canonical files have already changed.
+
+![TermKit Studio review workspace](.github/screenshots/studio-review-v2.png)
 
 A draft is an ordered semantic diff rather than an opaque form submission.
 Language and domain reviewers decide separately, provide rationale, and approve
 the same ChangeSet before canonical source is updated.
 
 ### Explain runtime decisions
 
-![TermKit Studio runtime lab](.github/screenshots/studio-runtime.jpg)
+![TermKit Studio runtime lab](.github/screenshots/studio-runtime-v2.png)
 
 Runtime Lab shows source offsets, concept identity, selected pack, target term,
 policy and evidence. The same bounded result can be consumed through the Python

apps/studio/e2e/studio.spec.ts

@@ -0,0 +1,35 @@
+import { expect, test } from "@playwright/test";
+
+test("navigates the curation workflow and command palette", async ({ page }) => {
+  await page.goto("/studio/#/concepts");
+
+  await expect(page.getByText("Canonical source valid")).toBeVisible();
+  await expect(page.getByRole("tab", { name: "Overview" })).toBeVisible();
+  await expect(page.getByText("pilot valve", { exact: true }).first()).toBeVisible();
+
+  await page.getByRole("button", { name: /Drafts/ }).click();
+  await expect(page.getByRole("heading", { name: "Draft Inbox" })).toBeVisible();
+
+  await page.keyboard.press("g");
+  await page.keyboard.press("t");
+  await expect(page.getByRole("heading", { name: "Runtime Lab" })).toBeVisible();
+
+  await page.keyboard.press("ControlOrMeta+k");
+  const palette = page.getByRole("dialog");
+  await palette.getByPlaceholder("Search commands…").fill("pilot");
+  await expect(palette.getByText("Concepts", { exact: true })).toBeVisible();
+  await expect(palette.getByRole("button", { name: /pilot valve/ })).toBeVisible();
+});
+
+test("Concepts 2.0 keeps its visual hierarchy", async ({ page }) => {
+  await page.goto("/studio/#/concepts");
+  await expect(page.getByRole("tab", { name: "Overview" })).toBeVisible();
+
+  await expect(page).toHaveScreenshot("concepts-v2.png", {
+    fullPage: true,
+    mask: [
+      page.locator(".draft-shortcut"),
+      page.getByRole("button", { name: /Drafts/ }),
+    ],
+  });
+});

apps/studio/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@termkit/studio",
-  "version": "0.2.0-alpha.0",
+  "version": "0.2.1-alpha.0",
   "private": true,
   "type": "module",
   "packageManager": "bun@1.3.14",
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",
     "check": "tsc -b --pretty false",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:e2e": "playwright test"
   },
   "dependencies": {
     "@radix-ui/react-dialog": "^1.1.15",
@@ -20,6 +21,7 @@
     "react-dom": "^19.2.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.55.0",
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
     "@vitejs/plugin-react": "^5.0.4",

apps/studio/playwright.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: false,
+  forbidOnly: Boolean(process.env.CI),
+  retries: process.env.CI ? 1 : 0,
+  reporter: process.env.CI ? "github" : "list",
+  snapshotPathTemplate: "{testDir}/__screenshots__/{arg}{ext}",
+  expect: {
+    toHaveScreenshot: {
+      animations: "disabled",
+      maxDiffPixelRatio: 0.04,
+    },
+  },
+  use: {
+    ...devices["Desktop Chrome"],
+    baseURL: "http://127.0.0.1:8771",
+    trace: "retain-on-failure",
+  },
+  webServer: {
+    command:
+      "../../.venv/bin/termkit studio ../../examples/packs/demo-hydraulics --no-open --port 8771",
+    url: "http://127.0.0.1:8771/health",
+    reuseExistingServer: false,
+    timeout: 30_000,
+  },
+});

apps/studio/src/App.tsx

@@ -9,13 +9,15 @@ import { pageFromHash, type PageId } from "./navigation";
 import { CandidatesPage } from "./pages/CandidatesPage";
 import { ConceptsPage } from "./pages/ConceptsPage";
 import { ExchangePage } from "./pages/ExchangePage";
+import { DraftsPage } from "./pages/DraftsPage";
 import { RelationsPage } from "./pages/RelationsPage";
 import { ReleasesPage } from "./pages/ReleasesPage";
 import { ReviewPage } from "./pages/ReviewPage";
 import { RuntimePage } from "./pages/RuntimePage";
 import { SourcesPage } from "./pages/SourcesPage";
 
 const pages: Record<PageId, () => React.JSX.Element> = {
+  drafts: DraftsPage,
   concepts: ConceptsPage,
   candidates: CandidatesPage,
   review: ReviewPage,
@@ -44,8 +46,34 @@ export function App() {
         setCommandOpen(true);
       }
     };
+    let chord = "";
+    let chordTimer = 0;
+    const shortcuts = (event: KeyboardEvent) => {
+      const element = event.target as HTMLElement | null;
+      if (element?.matches("input, textarea, select, [contenteditable=true]")) return;
+      const key = event.key.toLowerCase();
+      const map: Record<string, PageId> = {
+        d: "drafts", c: "concepts", a: "candidates", r: "review",
+        s: "sources", l: "relations", e: "exchange", t: "runtime", p: "releases"
+      };
+      if (chord === "g" && map[key]) {
+        event.preventDefault();
+        window.location.hash = `#/${map[key]}`;
+        chord = "";
+        window.clearTimeout(chordTimer);
+      } else if (key === "g" && !event.metaKey && !event.ctrlKey && !event.altKey) {
+        chord = "g";
+        chordTimer = window.setTimeout(() => { chord = ""; }, 900);
+      } else {
+        chord = "";
+      }
+    };
     window.addEventListener("keydown", keyboard);
-    return () => window.removeEventListener("keydown", keyboard);
+    window.addEventListener("keydown", shortcuts);
+    return () => {
+      window.removeEventListener("keydown", keyboard);
+      window.removeEventListener("keydown", shortcuts);
+    };
   }, []);
 
   const Page = pages[page];

apps/studio/src/api/client.test.ts

@@ -0,0 +1,36 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { api } from "./client";
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("Studio API workflow contracts", () => {
+  it("saves the complete operation set in one request", async () => {
+    const requests: Array<[RequestInfo | URL, RequestInit | undefined]> = [];
+    const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      requests.push([input, init]);
+      return new Response(JSON.stringify({ changeset_id: "changeset.test", operations: [], status: "DRAFT" }), { status: 200, headers: { "Content-Type": "application/json" } });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    await api.saveDraft({ author: "curator", reason: "Edit", operations: [
+      { kind: "UPDATE_CONCEPT", subject_kind: "CONCEPT", subject_id: "concept.test", after: { notes: ["one"] } },
+      { kind: "UPDATE_LEXICAL_ENTRY", subject_kind: "LEXICAL_ENTRY", subject_id: "term.test", after: { text: "term" } }
+    ] });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, request] = requests[0]!;
+    expect(url).toBe("/studio/api/v1/drafts");
+    expect(request?.method).toBe("PUT");
+    expect(JSON.parse(String(request?.body)).operations).toHaveLength(2);
+  });
+
+  it("selects the compiled backend explicitly", async () => {
+    const requests: Array<[RequestInfo | URL, RequestInit | undefined]> = [];
+    const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      requests.push([input, init]);
+      return new Response(JSON.stringify({ source_language: "en", target_language: "zh-Hans", matches: [], warnings: [], pack_coordinates: [] }), { status: 200, headers: { "Content-Type": "application/json" } });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    await api.resolve({ text: "pilot valve", source_language: "en", target_language: "zh-Hans" }, "compiled");
+    expect(requests[0]?.[0]).toBe("/studio/api/v1/runtime/resolve?backend=compiled");
+  });
+});

apps/studio/src/api/client.ts

@@ -7,6 +7,7 @@ import type {
   Relation,
   ResolutionResult,
   RuntimeCheckResult,
+  RuntimeStatus,
   ReviewDecision,
   ReviewTask,
   SourceSummary,
@@ -55,6 +56,22 @@ export const api = {
     request<ConceptListResult>(`/concepts${queryString(filters)}`),
   concept: (id: string) => request<ConceptDetail>(`/concepts/${encodeURIComponent(id)}`),
   changesets: (status = "") => request<ChangeSet[]>(`/changesets${queryString({ status })}`),
+  drafts: () => request<ChangeSet[]>("/drafts"),
+  saveDraft: (body: {
+    changeset_id?: string;
+    author: string;
+    reason: string;
+    operations: Array<{
+      kind: string;
+      subject_kind: string;
+      subject_id: string;
+      after: Record<string, unknown> | null;
+    }>;
+  }) => request<ChangeSet>("/drafts", { method: "PUT", body: JSON.stringify(body) }),
+  discardChangeset: (id: string) =>
+    request<ChangeSet>(`/changesets/${encodeURIComponent(id)}/discard`, { method: "POST" }),
+  rebaseChangeset: (id: string) =>
+    request<ChangeSet>(`/changesets/${encodeURIComponent(id)}/rebase`, { method: "POST" }),
   createChangeset: (body: { author: string; reason: string; source_run_id?: string }) =>
     request<ChangeSet>("/changesets", { method: "POST", body: JSON.stringify(body) }),
   addOperation: (
@@ -108,25 +125,30 @@ export const api = {
     request<ExchangePreview>("/exchange/preview", { method: "POST", body: JSON.stringify(body) }),
   createExchangeChangeset: (body: ExchangeRequest) =>
     request<ChangeSet>("/exchange/changeset", { method: "POST", body: JSON.stringify(body) }),
+  runtimeStatus: () => request<RuntimeStatus>("/runtime/status"),
   resolve: (body: {
     text: string;
     source_language: string;
     target_language: string;
     domain_hints?: string[];
-  }) => request<ResolutionResult>("/runtime/resolve", { method: "POST", body: JSON.stringify(body) }),
+  }, backend: "source" | "compiled" = "source") =>
+    request<ResolutionResult>(`/runtime/resolve${queryString({ backend })}`, {
+      method: "POST",
+      body: JSON.stringify(body)
+    }),
   check: (body: {
     source: string;
     translation: string;
     source_language: string;
     target_language: string;
     domain_hints?: string[];
-  }) =>
+  }, backend: "source" | "compiled" = "source") =>
     request<RuntimeCheckResult>(
-      "/runtime/check",
+      `/runtime/check${queryString({ backend })}`,
       { method: "POST", body: JSON.stringify(body) }
     ),
   compileRuntime: () =>
-    request<{ database_path: string; lexical_count: number; matcher_nodes: number }>(
+    request<{ database_path: string; lexical_count: number; matcher_nodes: number; lock_digest: string; built_at: string }>(
       "/runtime/compile",
       { method: "POST" }
     ),

apps/studio/src/api/types.ts

@@ -150,7 +150,15 @@ export interface ChangeSet {
   source_run_id: string;
   operations: ChangeOperation[];
   review_ids: string[];
-  status: "DRAFT" | "IN_REVIEW" | "APPROVED" | "APPLIED" | "REJECTED" | "REVERTED";
+  status:
+    | "DRAFT"
+    | "CONFLICTED"
+    | "IN_REVIEW"
+    | "APPROVED"
+    | "APPLIED"
+    | "REJECTED"
+    | "REVERTED"
+    | "DISCARDED";
 }
 
 export interface ConceptDetail {
@@ -175,6 +183,8 @@ export interface WorkspaceSummary {
   dirty_changesets: number;
   validation_ok: boolean;
   validation_errors: number;
+  recovery_mode: boolean;
+  validation_issues: Array<{ code: string; message: string; severity: string; record_id: string }>;
 }
 
 export interface CandidateConcept {
@@ -290,6 +300,20 @@ export interface RuntimeCheckResult {
   };
 }
 
+export interface RuntimeDescriptor {
+  backend: "source" | "compiled";
+  available: boolean;
+  pack_coordinates: string[];
+  lock_digest: string;
+  built_at: string;
+  database_path: string;
+}
+
+export interface RuntimeStatus {
+  source: RuntimeDescriptor;
+  compiled: RuntimeDescriptor;
+}
+
 export interface ExchangeMapping {
   column: string;
   target: