Split Translate and Speech into separate stages with TTS word timestamps (#268)

* Split Translate and Speech into separate pipeline stages with TTS timestamps and word highlighting

Separate the monolithic Translate stage into distinct Translate and Speech stages
with independent settings, DAG dependencies, and UI views. Add Whisper-based word
timestamp generation with inline playback highlighting, editable multi-column
timecode tables, and background task queue for batch transcription. Improve language
picker to show only linguistically relevant countries, add visual separation to
stage run cards, and pass source text as Whisper prompt for better accuracy.

* Add confirmation dialogs for delete speech and generate timestamps actions

* Fix timestamp race condition and show language name in generate dialog

Write timestamps incrementally during batch transcription instead of
accumulating in a stale snapshot, preventing concurrent user edits from
being silently overwritten. Show human-readable language name (e.g.
"English") instead of locale code in the generate timestamps confirmation.

* Add Class-suffix pattern to ESLint ignoreNames for CSS class variables

Fixes CI lint failure where `inputClass` (a Tailwind class string variable)
was flagged as an unlocalized string.

* Fix tts-timestamps data not cleared when deleting TTS or editing pages

tts-timestamps node data was not included in clearNodesByType calls
alongside tts, leaving stale word-timestamp data after speech deletion
or upstream page/caption edits.

---------

Co-authored-by: Nic Pottier <nicpottier@gmail.com>

Author: elasticsounds

apps/api/src/app.ts

@@ -93,7 +93,7 @@ app.route("/api", createQuizRoutes(booksDir))
 app.route("/api", createPackageRoutes(booksDir, webAssetsDir, configPath, taskService))
 app.route("/api", createPromptRoutes(promptsDir, booksDir))
 app.route("/api", createTextCatalogRoutes(booksDir))
-app.route("/api", createTTSRoutes(booksDir, configPath))
+app.route("/api", createTTSRoutes(booksDir, configPath, taskService))
 app.route(
   "/api",
   createStageRoutes(stageService, eventBus, booksDir, promptsDir, webAssetsDir, configPath)

apps/api/src/routes/books.test.ts

@@ -529,8 +529,8 @@ describe("POST /books/:label/stages/run", () => {
         "X-Gemini-API-Key": "gm-test",
       },
       body: JSON.stringify({
-        fromStage: "text-and-speech",
-        toStage: "text-and-speech",
+        fromStage: "translate",
+        toStage: "speech",
       }),
     })
 

apps/api/src/routes/pages.test.ts

@@ -669,7 +669,7 @@ describe("Page routes", () => {
     }
   }
 
-  /** Assert that all caption + text-and-speech node data and step_runs were cleared. */
+  /** Assert that all caption + translate/speech node data and step_runs were cleared. */
   function expectAllDownstreamCleared(dir: string, bookLabel: string) {
     const s = createBookStorage(bookLabel, dir)
     try {
@@ -689,7 +689,7 @@ describe("Page routes", () => {
     }
   }
 
-  /** Assert that text-and-speech (but NOT image-captioning) node data and step_runs were cleared. */
+  /** Assert that translate/speech (but NOT image-captioning) node data and step_runs were cleared. */
   function expectTextAndSpeechCleared(dir: string, bookLabel: string) {
     const s = createBookStorage(bookLabel, dir)
     try {
@@ -711,7 +711,7 @@ describe("Page routes", () => {
   }
 
   describe("PUT /api/books/:label/pages/:pageId/sectioning clears downstream", () => {
-    it("clears caption + text-and-speech data on sectioning save", async () => {
+    it("clears caption + translate/speech data on sectioning save", async () => {
       seedDownstreamData(tmpDir, label)
 
       const data = {
@@ -748,7 +748,7 @@ describe("Page routes", () => {
   })
 
   describe("PUT /api/books/:label/pages/:pageId/rendering clears downstream", () => {
-    it("clears caption + text-and-speech data on rendering save", async () => {
+    it("clears caption + translate/speech data on rendering save", async () => {
       seedDownstreamData(tmpDir, label)
 
       const data = {
@@ -775,7 +775,7 @@ describe("Page routes", () => {
   })
 
   describe("POST clone clears downstream", () => {
-    it("clears caption + text-and-speech data on section clone", async () => {
+    it("clears caption + translate/speech data on section clone", async () => {
       seedDownstreamData(tmpDir, label)
 
       const res = await app.request(
@@ -789,7 +789,7 @@ describe("Page routes", () => {
   })
 
   describe("POST delete clears downstream", () => {
-    it("clears caption + text-and-speech data on section delete", async () => {
+    it("clears caption + translate/speech data on section delete", async () => {
       // Need at least 2 sections so delete is valid
       const s = createBookStorage(label, tmpDir)
       try {
@@ -839,7 +839,7 @@ describe("Page routes", () => {
   })
 
   describe("POST crop (images) clears downstream", () => {
-    it("clears caption + text-and-speech data on image crop", async () => {
+    it("clears caption + translate/speech data on image crop", async () => {
       seedDownstreamData(tmpDir, label)
 
       // Minimal valid PNG (1x1 pixel)
@@ -867,7 +867,7 @@ describe("Page routes", () => {
     })
   })
 
-  describe("PUT image-captioning clears text-and-speech downstream", () => {
+  describe("PUT image-captioning clears translate/speech downstream", () => {
     it("clears text-catalog/translations/TTS but keeps image-captioning", async () => {
       seedDownstreamData(tmpDir, label)
 

apps/api/src/routes/pages.ts

@@ -327,9 +327,9 @@ async function executeAiImageGeneration(params: AiImageGenParams): Promise<{
   }
 }
 
-/** Clear caption + downstream text-and-speech data when images change. */
+/** Clear caption + downstream translate/speech data when images change. */
 function clearCaptionData(storage: Storage): void {
-  storage.clearNodesByType(["image-captioning", "text-catalog", "text-catalog-translation", "tts"])
+  storage.clearNodesByType(["image-captioning", "text-catalog", "text-catalog-translation", "tts", "tts-timestamps"])
   storage.clearStepRuns(["image-captioning", "text-catalog", "catalog-translation", "tts"])
 }
 
@@ -736,7 +736,7 @@ export function createPageRoutes(
 
       const version = storage.putNodeData("image-captioning", pageId, parsed.data)
       // Caption change cascades to text-catalog/translations/TTS
-      storage.clearNodesByType(["text-catalog", "text-catalog-translation", "tts"])
+      storage.clearNodesByType(["text-catalog", "text-catalog-translation", "tts", "tts-timestamps"])
       storage.clearStepRuns(["text-catalog", "catalog-translation", "tts"])
       return c.json({ version })
     } finally {

apps/api/src/routes/tts.test.ts

@@ -344,3 +344,57 @@ describe("POST /books/:label/tts/generate-one", () => {
     )
   })
 })
+
+describe("DELETE /books/:label/tts", () => {
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "adt-tts-route-"))
+    configPath = path.join(tmpDir, "config.yaml")
+    writeConfig()
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+    tmpDir = ""
+    configPath = ""
+  })
+
+  it("clears both tts and tts-timestamps data", async () => {
+    const label = "delete-tts"
+    seedBook(label)
+
+    // Seed TTS and tts-timestamps data
+    const storage = createBookStorage(label, tmpDir)
+    try {
+      storage.putNodeData("tts", "en", {
+        entries: [{ textId: "pg001_t001", fileName: "pg001_t001.wav" }],
+        generatedAt: new Date().toISOString(),
+      })
+      storage.putNodeData("tts-timestamps", "en", {
+        entries: {
+          pg001_t001: {
+            textId: "pg001_t001",
+            language: "en",
+            words: [{ word: "Hello", start: 0, end: 0.5 }],
+            duration: 0.5,
+          },
+        },
+        generatedAt: new Date().toISOString(),
+      })
+    } finally {
+      storage.close()
+    }
+
+    const app = createTTSRoutes(tmpDir, configPath)
+    const res = await app.request(`/books/${label}/tts`, { method: "DELETE" })
+
+    expect(res.status).toBe(200)
+
+    const after = createBookStorage(label, tmpDir)
+    try {
+      expect(after.getLatestNodeData("tts", "en")).toBeNull()
+      expect(after.getLatestNodeData("tts-timestamps", "en")).toBeNull()
+    } finally {
+      after.close()
+    }
+  })
+})