Agent completed work jubii

src/worker/protocol.ts

@@ -0,0 +1,189 @@
+/**
+ * Typed postMessage protocol between the UI and the inference Web Worker
+ * (Decisions.md D-003). Shared by `src/worker/inference.worker.ts` and the UI.
+ *
+ * Everything in this file must stay free of browser/worker globals so it can
+ * be unit-tested with `bun test`.
+ */
+
+/** Devices supported by the worker. M1 is WASM-only; M2 adds "webgpu" (D-004). */
+export type InferenceDevice = "wasm";
+
+// ---------------------------------------------------------------------------
+// UI → worker
+// ---------------------------------------------------------------------------
+
+export interface LoadMessage {
+  type: "load";
+  /** Hugging Face Hub model id, e.g. "onnx-community/whisper-tiny.en". */
+  modelId: string;
+  device: InferenceDevice;
+}
+
+export interface TranscribeMessage {
+  type: "transcribe";
+  /**
+   * Mono PCM at 16 kHz (see src/lib/audio.ts). The underlying ArrayBuffer
+   * should be passed as a transferable for zero-copy handoff.
+   */
+  audio: Float32Array;
+}
+
+export type UiToWorkerMessage = LoadMessage | TranscribeMessage;
+
+// ---------------------------------------------------------------------------
+// Worker → UI
+// ---------------------------------------------------------------------------
+
+/**
+ * Model download / initialization progress. Mirrors the Transformers.js
+ * `progress_callback` events we care about; `status: "ready"` marks the end
+ * of a successful load.
+ */
+export type LoadProgressMessage =
+  | { type: "load-progress"; status: "initiate"; file: string }
+  | { type: "load-progress"; status: "download"; file: string }
+  | {
+      type: "load-progress";
+      status: "progress";
+      file: string;
+      /** Bytes downloaded so far. */
+      loaded: number;
+      /** Total bytes for this file. */
+      total: number;
+      /** Percentage in [0, 100]. */
+      progress: number;
+    }
+  | { type: "load-progress"; status: "done"; file: string }
+  | { type: "load-progress"; status: "ready" };
+
+/** Incremental transcript fragment — append to the text streamed so far. */
+export interface PartialMessage {
+  type: "partial";
+  text: string;
+}
+
+/** One timestamped segment of the final transcript. */
+export interface TranscriptChunk {
+  text: string;
+  /** [start, end] in seconds; end may be null if Whisper never closed the segment. */
+  timestamp: [number, number | null];
+}
+
+export interface ResultMessage {
+  type: "result";
+  text: string;
+  chunks: TranscriptChunk[];
+}
+
+export interface ErrorMessage {
+  type: "error";
+  stage: "load" | "transcribe";
+  message: string;
+}
+
+export type WorkerToUiMessage =
+  | LoadProgressMessage
+  | PartialMessage
+  | ResultMessage
+  | ErrorMessage;
+
+// ---------------------------------------------------------------------------
+// Runtime guards (postMessage data arrives untyped)
+// ---------------------------------------------------------------------------
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function isUiToWorkerMessage(value: unknown): value is UiToWorkerMessage {
+  if (!isRecord(value)) return false;
+  switch (value.type) {
+    case "load":
+      return typeof value.modelId === "string" && value.device === "wasm";
+    case "transcribe":
+      return value.audio instanceof Float32Array;
+    default:
+      return false;
+  }
+}
+
+export function isWorkerToUiMessage(value: unknown): value is WorkerToUiMessage {
+  if (!isRecord(value)) return false;
+  switch (value.type) {
+    case "load-progress":
+      switch (value.status) {
+        case "initiate":
+        case "download":
+        case "done":
+          return typeof value.file === "string";
+        case "progress":
+          return (
+            typeof value.file === "string" &&
+            typeof value.loaded === "number" &&
+            typeof value.total === "number" &&
+            typeof value.progress === "number"
+          );
+        case "ready":
+          return true;
+        default:
+          return false;
+      }
+    case "partial":
+      return typeof value.text === "string";
+    case "result":
+      return typeof value.text === "string" && Array.isArray(value.chunks);
+    case "error":
+      return (
+        typeof value.message === "string" &&
+        (value.stage === "load" || value.stage === "transcribe")
+      );
+    default:
+      return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Load-progress accumulation (pure; drives the download progress UI)
+// ---------------------------------------------------------------------------
+
+export interface FileProgress {
+  file: string;
+  loaded: number;
+  total: number;
+  done: boolean;
+}
+
+export interface LoadProgressState {
+  /** Per-file progress, keyed by file name, in first-seen order. */
+  files: Record<string, FileProgress>;
+  /** True once the pipeline reported ready. */
+  ready: boolean;
+}
+
+export const initialLoadProgress: LoadProgressState = { files: {}, ready: false };
+
+/** Fold one load-progress message into the accumulated state. Pure. */
+export function applyLoadProgress(
+  state: LoadProgressState,
+  message: LoadProgressMessage,
+): LoadProgressState {
+  if (message.status === "ready") {
+    return { ...state, ready: true };
+  }
+  const previous = state.files[message.file];
+  const next: FileProgress = {
+    file: message.file,
+    loaded: previous?.loaded ?? 0,
+    total: previous?.total ?? 0,
+    done: previous?.done ?? false,
+  };
+  if (message.status === "progress") {
+    next.loaded = message.loaded;
+    next.total = message.total;
+  } else if (message.status === "done") {
+    next.done = true;
+    if (next.total > 0) next.loaded = next.total;
+  }
+  return { ...state, files: { ...state.files, [message.file]: next } };
+}