feat: implement dual-phase contextual transcription for dictation (GH-256)

src/UniversalDictationModule.ts

@@ -1,6 +1,6 @@
 import { Observation } from "./dom/Observation";
 import { addChild } from "./dom/DOMModule";
-import { createDictationMachine } from "./state-machines/DictationMachine";
+import { createDictationMachine, DictationTranscribedEvent } from "./state-machines/DictationMachine";
 import { interpret } from "xstate";
 import EventBus from "./events/EventBus.js";
 import { IconModule } from "./icons/IconModule";
@@ -328,6 +328,19 @@ export class UniversalDictationModule {
     };
 
     const hideButton = () => {
+      // Trigger refinement if dictation is active for this element
+      if (target.machine) {
+        const state = target.machine.getSnapshot();
+        // Check if machine is in a state where refinement makes sense
+        if (state.matches("listening")) {
+          console.debug("[UniversalDictation] Field blur - triggering refinement for element:", element);
+          target.machine.send({
+            type: "saypi:refineTranscription",
+            targetElement: element,
+          });
+        }
+      }
+
       // Use setTimeout to delay hiding so click event can fire first
       setTimeout(() => {
         if (button && !this.currentActiveTarget) {
@@ -387,14 +400,14 @@ export class UniversalDictationModule {
     element.addEventListener("input", handleContentChange);
 
     // Listen for dictation updates to track dictated content
-    EventBus.on("dictation:contentUpdated", (data) => {
+    EventBus.on("dictation:contentUpdated", (data: { targetElement: HTMLElement }) => {
       if (data.targetElement === element) {
         markDictationUpdate();
       }
     });
-    
+
     // Listen for dictation termination due to manual edit
-    EventBus.on("dictation:terminatedByManualEdit", (data) => {
+    EventBus.on("dictation:terminatedByManualEdit", (data: { targetElement: HTMLElement; reason: string }) => {
       if (data.targetElement === element && this.currentActiveTarget?.element === element) {
         console.debug("Dictation terminated due to manual edit on element:", element);
         // Clean up the active dictation state
@@ -1026,7 +1039,7 @@ export class UniversalDictationModule {
 
     // Events with additional data
     [USER_STOPPED_SPEAKING, AUDIO_DEVICE_CONNECTED, SESSION_ASSIGNED].forEach((eventName) => {
-      EventBus.on(eventName, (detail) => {
+      EventBus.on(eventName, (detail: any) => {
         if (detail) {
           // sanitise the detail object to replace any `frames` property with `[REDACTED]`
           const sanitisedDetail = { ...detail };
@@ -1042,7 +1055,7 @@ export class UniversalDictationModule {
     });
 
     // Listen for transcription events
-    EventBus.on("saypi:transcription:completed", (detail) => {
+    EventBus.on("saypi:transcription:completed", (detail: Omit<DictationTranscribedEvent, 'type'>) => {
       logger.debug(`[UniversalDictationModule] Forwarding transcription to dictation machine`, detail);
       dictationService.send({ type: "saypi:transcribed", ...detail });
     });