@frockbot/plugin-shell 0.3.13 → 0.3.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "private": false,
   "type": "module",
   "exports": {
@@ -27,6 +27,7 @@
     "./client/FrockBotApp.vue": "./src/client/FrockBotApp.vue",
     "./client/notify": "./src/client/notify.ts",
     "./client/styles.css": "./src/client/styles.css",
+    "./client/voice-worklet": "./src/client/voice-worklet.ts",
     "./focus": "./src/focus.ts",
     "./frockbot.json": "./frockbot.json",
     "./host": "./src/host.ts",
@@ -50,42 +51,42 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/agent-runtime": "0.3.13",
-    "@frockbot/application-foundation": "0.3.13",
-    "@frockbot/catalog-core": "0.3.13",
-    "@frockbot/client-core": "0.3.13",
-    "@frockbot/client-ui": "0.3.13",
-    "@frockbot/computer-core": "0.3.13",
-    "@frockbot/computer-host-protocol": "0.3.13",
-    "@frockbot/configuration-core": "0.3.13",
-    "@frockbot/connection-core": "0.3.13",
-    "@frockbot/kernel-agent-loop": "0.3.13",
-    "@frockbot/kernel-composition": "0.3.13",
-    "@frockbot/kernel-contracts": "0.3.13",
-    "@frockbot/kernel-do": "0.3.13",
-    "@frockbot/machine-protocol": "0.3.13",
-    "@frockbot/plugin-applets": "0.3.13",
-    "@frockbot/plugin-authoring": "0.3.13",
-    "@frockbot/plugin-bot-template": "0.3.13",
-    "@frockbot/plugin-computer": "0.3.13",
-    "@frockbot/plugin-flock": "0.3.13",
-    "@frockbot/plugin-image": "0.3.13",
-    "@frockbot/plugin-machine-messages": "0.3.13",
-    "@frockbot/plugin-mcp": "0.3.13",
-    "@frockbot/plugin-memory": "0.3.13",
-    "@frockbot/plugin-package-catalog": "0.3.13",
-    "@frockbot/plugin-routines": "0.3.13",
-    "@frockbot/plugin-skills": "0.3.13",
-    "@frockbot/plugin-subagents": "0.3.13",
-    "@frockbot/plugin-user-machine": "0.3.13",
-    "@frockbot/protocol": "0.3.13",
+    "@frockbot/agent-runtime": "0.3.14",
+    "@frockbot/application-foundation": "0.3.14",
+    "@frockbot/catalog-core": "0.3.14",
+    "@frockbot/client-core": "0.3.14",
+    "@frockbot/client-ui": "0.3.14",
+    "@frockbot/computer-core": "0.3.14",
+    "@frockbot/computer-host-protocol": "0.3.14",
+    "@frockbot/configuration-core": "0.3.14",
+    "@frockbot/connection-core": "0.3.14",
+    "@frockbot/kernel-agent-loop": "0.3.14",
+    "@frockbot/kernel-composition": "0.3.14",
+    "@frockbot/kernel-contracts": "0.3.14",
+    "@frockbot/kernel-do": "0.3.14",
+    "@frockbot/machine-protocol": "0.3.14",
+    "@frockbot/plugin-applets": "0.3.14",
+    "@frockbot/plugin-authoring": "0.3.14",
+    "@frockbot/plugin-bot-template": "0.3.14",
+    "@frockbot/plugin-computer": "0.3.14",
+    "@frockbot/plugin-flock": "0.3.14",
+    "@frockbot/plugin-image": "0.3.14",
+    "@frockbot/plugin-machine-messages": "0.3.14",
+    "@frockbot/plugin-mcp": "0.3.14",
+    "@frockbot/plugin-memory": "0.3.14",
+    "@frockbot/plugin-package-catalog": "0.3.14",
+    "@frockbot/plugin-routines": "0.3.14",
+    "@frockbot/plugin-skills": "0.3.14",
+    "@frockbot/plugin-subagents": "0.3.14",
+    "@frockbot/plugin-user-machine": "0.3.14",
+    "@frockbot/protocol": "0.3.14",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "latest",
-    "@frockbot/plugin-prompt": "0.3.13",
-    "@frockbot/plugin-tools": "0.3.13",
+    "@frockbot/plugin-prompt": "0.3.14",
+    "@frockbot/plugin-tools": "0.3.14",
     "@types/bun": "1.3.6",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/client/FrockBotApp.vue

@@ -28,6 +28,19 @@ import {
   type WebToolActivity,
 } from "../shared.js";
 import { ComposerDraftStore } from "./composer-draft.js";
+import {
+  applyDictationTailV1,
+  voiceButtonLabelV1,
+  voiceWaveBarsV1,
+  VoiceDictationTranscriptV1,
+  type VoiceDictationStateV1,
+} from "./voice-dictation.js";
+import {
+  startVoiceMicrophoneV1,
+  voiceMicrophoneRefusalV1,
+  type VoiceMicrophoneV1,
+} from "./voice-microphone.js";
+import type { VoiceDictationSessionV1 } from "@frockbot/client-core";
 import {
   activityTrailBeginV1,
   activityTrailSampleV1,
@@ -372,6 +385,149 @@ const canSend = computed(
  */
 const showStop = computed(() => isRunning.value && !canSend.value);
 
+/*
+ * Dictation (voice plan D4).
+ *
+ * The send button's slot already switches between Send and Stop, and this is
+ * the third thing it holds: with nothing to send and nothing to stop, the
+ * button offers to listen instead. While it is listening the slot carries a
+ * bin and a send, because those are the only two things a person wants next.
+ *
+ * Nothing here is a second composer. Speech lands in the same draft the
+ * keyboard writes to, through the same `ComposerDraftStore`, and Send is the
+ * ordinary `sendMessage` — so a message that is half spoken and half typed
+ * behaves exactly like one that is entirely typed, including a refusal that
+ * gives the draft back.
+ */
+const voiceState = ref<VoiceDictationStateV1>("idle");
+const voiceError = ref<string | undefined>(undefined);
+const voiceBars = ref<number[]>(voiceWaveBarsV1(0, []));
+const voiceTranscript = new VoiceDictationTranscriptV1();
+let voiceSession: VoiceDictationSessionV1 | undefined;
+let voiceMicrophone: VoiceMicrophoneV1 | undefined;
+/** The exact text dictation last wrote, so a typed edit around it survives. */
+let voiceTail = "";
+/** Send was pressed; the last transcript is what we are waiting for. */
+let voiceSendOnFinal = false;
+
+const dictating = computed(() => voiceState.value !== "idle");
+const voiceButtonLabel = computed(() => voiceButtonLabelV1(voiceState.value));
+/**
+ * The wave button takes the slot only when the slot is otherwise idle: an
+ * empty draft, no Turn to stop, and a platform that can actually listen.
+ */
+const showVoiceButton = computed(
+  () =>
+    state.value.voiceAvailable &&
+    !dictating.value &&
+    !showStop.value &&
+    draftText.value.length === 0,
+);
+
+function writeDictationIntoDraft(): void {
+  const applied = applyDictationTailV1(
+    draft.value,
+    voiceTail,
+    voiceTranscript.text(),
+  );
+  voiceTail = applied.tail;
+  draft.value = applied.draft;
+  void nextTick(syncComposerHeight);
+}
+
+async function startDictation(): Promise<void> {
+  if (dictating.value || !state.value.voiceAvailable) return;
+  voiceError.value = undefined;
+  voiceTranscript.reset();
+  voiceTail = "";
+  voiceSendOnFinal = false;
+  voiceBars.value = voiceWaveBarsV1(0, []);
+  voiceState.value = "starting";
+  const session = web.value.openVoiceDictation({
+    ready: () => {
+      if (voiceState.value === "starting") voiceState.value = "listening";
+    },
+    delta: (text) => {
+      voiceTranscript.delta(text);
+      writeDictationIntoDraft();
+    },
+    transcript: (text) => {
+      voiceTranscript.settle(text);
+      writeDictationIntoDraft();
+    },
+    final: () => {
+      void completeDictation();
+    },
+    failed: (message) => {
+      voiceError.value = message;
+      void stopDictation();
+    },
+    closed: () => {
+      // A socket that goes away mid-capture leaves the draft exactly where it
+      // is; the person can still type the rest and send it.
+      if (dictating.value) void stopDictation();
+    },
+  });
+  if (!session) {
+    voiceState.value = "idle";
+    voiceError.value = "Dictation isn't available on this device.";
+    return;
+  }
+  voiceSession = session;
+  try {
+    voiceMicrophone = await startVoiceMicrophoneV1({
+      audio: (pcm16) => session.sendAudio(pcm16),
+      level: (value) => {
+        voiceBars.value = voiceWaveBarsV1(value, voiceBars.value);
+      },
+    });
+  } catch (error) {
+    voiceError.value = voiceMicrophoneRefusalV1(error);
+    await stopDictation();
+  }
+}
+
+/** Everything captured has been transcribed; send it if that is why we stopped. */
+async function completeDictation(): Promise<void> {
+  const send = voiceSendOnFinal;
+  await stopDictation();
+  if (send) await sendMessage();
+}
+
+async function stopDictation(): Promise<void> {
+  voiceState.value = "idle";
+  voiceSendOnFinal = false;
+  voiceBars.value = voiceWaveBarsV1(0, []);
+  const microphone = voiceMicrophone;
+  const session = voiceSession;
+  voiceMicrophone = undefined;
+  voiceSession = undefined;
+  await microphone?.stop();
+  session?.close();
+}
+
+/** The bin. Discards what was dictated, exactly as D4 says it does. */
+function discardDictation(): void {
+  voiceSession?.cancel();
+  voiceTranscript.reset();
+  voiceTail = "";
+  draft.value = "";
+  voiceError.value = undefined;
+  void stopDictation();
+  void nextTick(syncComposerHeight);
+}
+
+/**
+ * Send, mid-dictation. The audio is committed and the message waits for the
+ * last transcript rather than sending half a sentence.
+ */
+function sendDictation(): void {
+  if (voiceState.value !== "listening") return;
+  voiceSendOnFinal = true;
+  voiceState.value = "finishing";
+  voiceSession?.commit();
+}
+
 /*
  * Tool activity is internal to the Turn. A Turn that produced only tool calls
  * shows the Bot avatar while it runs and nothing once it finishes with no
@@ -818,6 +974,9 @@ onBeforeUnmount(() => {
   window.removeEventListener("hashchange", applySettingsDeepLink);
   phoneLayoutMedia?.removeEventListener("change", onPhoneLayoutChange);
   window.removeEventListener("keydown", onRootKeydown);
+  // A microphone outlives a component that stops drawing it unless it is told
+  // not to, and a browser shows the recording indicator for as long as it does.
+  void stopDictation();
 });
 
 watch(
@@ -1058,8 +1217,20 @@ function handleComposerKeydown(event: KeyboardEvent): void {
       }
     }
   }
+  if (event.key === "Escape" && dictating.value) {
+    // Escape is the keyboard's bin, the same as it is for the Skill popover.
+    event.preventDefault();
+    discardDictation();
+    return;
+  }
   if (event.key !== "Enter" || event.shiftKey) return;
   event.preventDefault();
+  // Enter means send either way; mid-dictation it commits the audio first so
+  // the last word spoken is in the message.
+  if (dictating.value) {
+    sendDictation();
+    return;
+  }
   void sendMessage();
 }
 </script>
@@ -1492,6 +1663,36 @@ function handleComposerKeydown(event: KeyboardEvent): void {
             >
               {{ draftCounterLabel }}
             </p>
+            <!--
+              The capture animation, and the only place the state is written
+              out. It is level-driven from the microphone: bars that move while
+              the room is silent would say the microphone works when it does
+              not.
+            -->
+            <p
+              v-if="dictating"
+              class="voice-capture"
+              role="status"
+              aria-live="polite"
+            >
+              <span class="voice-wave" aria-hidden="true">
+                <span
+                  v-for="(bar, index) in voiceBars"
+                  :key="index"
+                  class="voice-wave-bar"
+                  :style="{ transform: `scaleY(${bar})` }"
+                />
+              </span>
+              <span>{{ voiceButtonLabel }}</span>
+            </p>
+            <!--
+              Why dictation stopped, in the words the server or the browser
+              used. It sits under the draft it could not add to, and the draft
+              itself is untouched.
+            -->
+            <p v-if="voiceError" class="voice-error" role="alert">
+              {{ voiceError }}
+            </p>
           </div>
           <!--
             Start a new conversation. Sits beside the composer because that is
@@ -1506,14 +1707,44 @@ function handleComposerKeydown(event: KeyboardEvent): void {
             :disabled="isRunning"
             @click="web.startConversation()"
           />
+          <!--
+            The send slot, and its four states. Dictation replaces the one
+            button with two, because while it is listening the only two things
+            worth offering are "throw this away" and "that's the message".
+          -->
+          <template v-if="dictating">
+            <UiIconButton
+              class="voice-discard-button"
+              icon="trash"
+              label="Discard dictation"
+              variant="ghost"
+              @click="discardDictation"
+            />
+            <UiIconButton
+              class="voice-send-button"
+              icon="arrow-up"
+              label="Send dictated message"
+              variant="primary"
+              :disabled="voiceState !== 'listening'"
+              @click="sendDictation"
+            />
+          </template>
           <UiIconButton
-            v-if="showStop"
+            v-else-if="showStop"
             class="stop-button"
             icon="stop"
             label="Stop generating"
             variant="primary"
             @click="web.stopRun()"
           />
+          <UiIconButton
+            v-else-if="showVoiceButton"
+            class="voice-button"
+            icon="waveform"
+            :label="voiceButtonLabel"
+            variant="primary"
+            @click="startDictation"
+          />
           <UiIconButton
             v-else
             type="submit"

package/src/client/index.ts

@@ -15,6 +15,7 @@ import {
 } from "@frockbot/client-core";
 import { clientSurfaceRegistryKey } from "@frockbot/client-core";
 import { COMPACTED_ANNOUNCEMENT_TEXT_V1 } from "../compaction.js";
+import { voiceCaptureSupportedV1 } from "./voice-microphone.js";
 import { readViewerFocusV1, shouldNotifyForBotV1 } from "../focus.js";
 // Connection mutations use the provider-neutral hosted command contract.
 import type {
@@ -1417,6 +1418,9 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     modelSource: "none",
     settingsAvailable: true,
     connectionsAvailable: ctx.transport.connectionsAvailable !== false,
+    voiceAvailable:
+      typeof ctx.transport.openVoiceDictation === "function" &&
+      voiceCaptureSupportedV1(),
     activeBotId: undefined,
     composerContext: undefined,
     transcripts: {
@@ -2878,6 +2882,9 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         }
       }
     },
+    openVoiceDictation(observer) {
+      return ctx.transport.openVoiceDictation?.(observer);
+    },
     async resumeRun(runId: string): Promise<void> {
       if (!ctx.transport.reconcileRun) {
         web.value.settingsError = "Can't retry this right now.";

package/src/client/styles.css

@@ -758,6 +758,50 @@
   color: var(--frock-danger-text);
 }
 
+/*
+ * Dictation.
+ *
+ * The capture line sits under the draft it is writing, inside the composer,
+ * because the text arriving in the textarea is the thing it is describing. It
+ * is a status line rather than an overlay: nothing about the composer moves
+ * when it appears beyond the row it adds.
+ */
+.voice-capture {
+  display: flex;
+  margin: 0;
+  align-items: center;
+  gap: 8px;
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-xs);
+}
+
+.voice-wave {
+  display: flex;
+  height: 14px;
+  align-items: center;
+  gap: 2px;
+}
+
+/*
+ * Each bar is scaled from the microphone's own level, so the animation stops
+ * when the room does. `transform` rather than `height`: it is the one property
+ * that animates without a layout pass, and this runs at frame rate.
+ */
+.voice-wave-bar {
+  width: 2px;
+  height: 100%;
+  border-radius: 999px;
+  background: var(--frock-action-primary);
+  transform-origin: center;
+  transition: transform var(--frock-motion-fast);
+}
+
+.voice-error {
+  margin: 0;
+  color: var(--frock-danger-text);
+  font-size: var(--frock-text-xs);
+}
+
 .skill-chips {
   display: flex;
   margin: 0;

package/src/client/voice-dictation.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "bun:test";
+import {
+  applyDictationTailV1,
+  voiceButtonLabelV1,
+  voiceWaveBarsV1,
+  VoiceDictationTranscriptV1,
+} from "./voice-dictation.js";
+
+describe("writing dictation into a draft somebody may be editing", () => {
+  test("appends the first words to an empty draft", () => {
+    expect(applyDictationTailV1("", "", "hello")).toEqual({
+      draft: "hello",
+      tail: "hello",
+    });
+  });
+
+  test("grows in place rather than repeating itself", () => {
+    const first = applyDictationTailV1("", "", "hello");
+    const second = applyDictationTailV1(first.draft, first.tail, "hello there");
+    expect(second.draft).toBe("hello there");
+  });
+
+  test("keeps a typed prefix, and a typed suffix, around what is spoken", () => {
+    const first = applyDictationTailV1("Note: ", "", "buy milk");
+    expect(first.draft).toBe("Note: buy milk");
+    // The person types on the end while the next words arrive.
+    const edited = `${first.draft} today`;
+    const second = applyDictationTailV1(
+      edited,
+      first.tail,
+      "buy milk and bread",
+    );
+    expect(second.draft).toBe("Note: buy milk and bread today");
+  });
+
+  test("rewrites the last occurrence, so a repeated word moves the right one", () => {
+    // "go" was typed, then "go" was dictated. Growing the dictated one must
+    // not reach back and rewrite the typed one.
+    expect(applyDictationTailV1("go go", "go", "gone")).toEqual({
+      draft: "go gone",
+      tail: "gone",
+    });
+  });
+
+  test("appends rather than fighting when the person deleted what was dictated", () => {
+    const first = applyDictationTailV1("", "", "hello");
+    const cleared = applyDictationTailV1("", first.tail, "hello there");
+    expect(cleared).toEqual({ draft: "hello there", tail: "hello there" });
+  });
+
+  test("never glues two words together", () => {
+    expect(applyDictationTailV1("Note:", "", "one").draft).toBe("Note: one");
+    expect(applyDictationTailV1("Note: ", "", "one").draft).toBe("Note: one");
+  });
+});
+
+describe("what has been heard so far", () => {
+  test("streams deltas, then lets the finished segment replace them", () => {
+    const transcript = new VoiceDictationTranscriptV1();
+    expect(transcript.empty()).toBe(true);
+    transcript.delta("hello ");
+    transcript.delta("their");
+    expect(transcript.text()).toBe("hello their");
+    transcript.settle("Hello there.");
+    expect(transcript.text()).toBe("Hello there.");
+    expect(transcript.empty()).toBe(false);
+  });
+
+  test("joins segments with a single space and drops an empty one", () => {
+    const transcript = new VoiceDictationTranscriptV1();
+    transcript.settle("  One. ");
+    transcript.settle("");
+    transcript.settle("Two.");
+    transcript.delta("thr");
+    expect(transcript.text()).toBe("One. Two. thr");
+  });
+
+  test("resets to nothing, so a binned capture leaves no tail behind", () => {
+    const transcript = new VoiceDictationTranscriptV1();
+    transcript.settle("One.");
+    transcript.reset();
+    expect(transcript.empty()).toBe(true);
+    expect(transcript.text()).toBe("");
+  });
+});
+
+describe("the composer's dictation chrome", () => {
+  test("names each state for the aria label and the tooltip alike", () => {
+    expect(voiceButtonLabelV1("idle")).toBe("Dictate a message");
+    expect(voiceButtonLabelV1("listening")).toBe("Listening");
+    expect(voiceButtonLabelV1("finishing")).toBe("Finishing dictation");
+  });
+
+  test("the wave follows the microphone and never collapses to a line", () => {
+    const silent = voiceWaveBarsV1(0, []);
+    expect(silent).toHaveLength(4);
+    expect(silent.every((bar) => bar >= 0.2)).toBe(true);
+    const loud = voiceWaveBarsV1(1, silent);
+    expect(loud[0]).toBeCloseTo(1);
+    // The level travels along the bars rather than moving all of them at once.
+    expect(loud[1]).toBeCloseTo(silent[0]!);
+    expect(voiceWaveBarsV1(Number.NaN, silent)[0]).toBeCloseTo(0.2);
+    expect(voiceWaveBarsV1(9, silent)[0]).toBeCloseTo(1);
+  });
+});

package/src/client/voice-dictation.ts

@@ -0,0 +1,137 @@
+// Dictation, as text arriving in a draft somebody may be editing at the same
+// time (voice plan D4).
+//
+// The composer writes what it hears into the textarea rather than into a
+// separate box, so the message is editable while it is being spoken, a
+// rejected send restores it like any other draft, and Send is the ordinary
+// Send. That makes one thing hard and this module is that one thing: knowing
+// which part of the draft dictation put there, when the person is free to
+// type in the middle of it.
+//
+// The answer is a *tail*: the exact text last written on dictation's behalf.
+// Each update replaces the last occurrence of the previous tail with the next
+// one. Delete it, retype around it, paste over it — if the previous tail is
+// no longer in the draft, the new text is appended rather than forced back
+// into a position nobody asked for. Nothing here reads the caret, so it holds
+// on a phone keyboard and a desktop one alike.
+
+export type VoiceDictationStateV1 =
+  /** No microphone. The send button is the wave button when the draft is empty. */
+  | "idle"
+  /** Asked for the microphone, or waiting for the upstream to say `ready`. */
+  | "starting"
+  /** Capturing. Bin and Send have replaced the wave button. */
+  | "listening"
+  /** Send was pressed; the last of the audio is being transcribed. */
+  | "finishing";
+
+export interface DictationDraftV1 {
+  draft: string;
+  tail: string;
+}
+
+/** Joins dictation onto a draft without gluing two words together. */
+function joined(head: string, tail: string): string {
+  if (!head) return tail;
+  if (!tail) return head;
+  return /\s$/u.test(head) ? `${head}${tail}` : `${head} ${tail}`;
+}
+
+/**
+ * Puts `nextTail` where `previousTail` was, or on the end when it has gone.
+ *
+ * `lastIndexOf`, not `indexOf`: dictating the same short word twice must
+ * rewrite the second one.
+ */
+export function applyDictationTailV1(
+  draft: string,
+  previousTail: string,
+  nextTail: string,
+): DictationDraftV1 {
+  if (!previousTail) return { draft: joined(draft, nextTail), tail: nextTail };
+  const at = draft.lastIndexOf(previousTail);
+  if (at < 0) return { draft: joined(draft, nextTail), tail: nextTail };
+  const before = draft.slice(0, at);
+  const after = draft.slice(at + previousTail.length);
+  return { draft: `${before}${nextTail}${after}`, tail: nextTail };
+}
+
+/**
+ * What has been heard so far: the finished segments, and the deltas of the
+ * one still being spoken.
+ *
+ * A provider streams a segment as deltas and then re-sends it, punctuated and
+ * capitalised, as a `completed` transcript. Keeping the two apart is what lets
+ * the finished form replace the rough one in place instead of appearing twice.
+ */
+export class VoiceDictationTranscriptV1 {
+  #settled: string[] = [];
+  #pending = "";
+
+  delta(text: string): void {
+    this.#pending += text;
+  }
+
+  /** One finished segment; it replaces the deltas that built it. */
+  settle(text: string): void {
+    const trimmed = text.trim();
+    if (trimmed) this.#settled.push(trimmed);
+    this.#pending = "";
+  }
+
+  /** Everything dictated in this session, as one string. */
+  text(): string {
+    const settled = this.#settled.join(" ");
+    const pending = this.#pending.trim();
+    if (!settled) return pending;
+    if (!pending) return settled;
+    return `${settled} ${pending}`;
+  }
+
+  /** True until the first word arrives, so an empty capture sends nothing. */
+  empty(): boolean {
+    return this.text().length === 0;
+  }
+
+  reset(): void {
+    this.#settled = [];
+    this.#pending = "";
+  }
+}
+
+/** The composer's label for each state, so the aria text and the title agree. */
+export function voiceButtonLabelV1(state: VoiceDictationStateV1): string {
+  switch (state) {
+    case "idle":
+      return "Dictate a message";
+    case "starting":
+      return "Starting dictation";
+    case "listening":
+      return "Listening";
+    case "finishing":
+      return "Finishing dictation";
+  }
+}
+
+/**
+ * The scale factor of each bar of the capture animation, newest first.
+ *
+ * Level-driven rather than time-driven: a wave that moves while the room is
+ * silent says the microphone is working when it is not. Each call shifts the
+ * previous bars along, so a syllable travels across the control instead of
+ * every bar jumping at once.
+ *
+ * `previous` is the value this function last returned, so the whole animation
+ * is one `ref` and one assignment.
+ */
+export function voiceWaveBarsV1(
+  level: number,
+  previous: readonly number[],
+  bars = 4,
+): number[] {
+  const clamped = Number.isFinite(level) ? Math.min(1, Math.max(0, level)) : 0;
+  // A floor, so the control never collapses to a line and loses its shape.
+  const next = [0.2 + clamped * 0.8, ...previous].slice(0, bars);
+  while (next.length < bars) next.push(0.2);
+  return next;
+}

package/src/client/voice-microphone.ts

@@ -0,0 +1,125 @@
+// The browser's half of dictation: a microphone, resampled to the PCM16 the
+// upstream transcription session expects.
+//
+// The capture itself runs on the audio thread; its source and the reason it is
+// served as a first-party asset are in `voice-worklet.ts`. This module is the
+// graph around it: permission, the context, the silent sink that keeps the
+// node pulled, and the teardown that actually releases the microphone.
+import {
+  VOICE_CAPTURE_WORKLET_PATH_V1,
+  VOICE_CAPTURE_WORKLET_PROCESSOR_V1,
+} from "./voice-worklet.js";
+
+/** What the upstream is told to expect, and therefore what leaves here. */
+export const VOICE_CAPTURE_SAMPLE_RATE_V1 = 16_000;
+
+/** Samples per frame at 16 kHz: 32 ms, small enough to feel live. */
+const FRAME_SAMPLES = 512;
+
+export interface VoiceMicrophoneV1 {
+  stop(): Promise<void>;
+}
+
+export interface VoiceMicrophoneOptionsV1 {
+  /** One frame of PCM16, little-endian, mono, 16 kHz. */
+  audio(pcm16: ArrayBuffer): void;
+  /** Peak amplitude of the frame, 0…1, for the capture animation. */
+  level(value: number): void;
+}
+
+/** False on a platform with no microphone API at all; the button stays hidden. */
+export function voiceCaptureSupportedV1(): boolean {
+  return (
+    typeof navigator !== "undefined" &&
+    typeof navigator.mediaDevices?.getUserMedia === "function" &&
+    typeof (globalThis as { AudioContext?: unknown }).AudioContext ===
+      "function"
+  );
+}
+
+/**
+ * The refusal a person reads when the browser will not give up the
+ * microphone. Named cases only: anything else says what the browser said.
+ */
+export function voiceMicrophoneRefusalV1(error: unknown): string {
+  const name =
+    typeof error === "object" && error !== null && "name" in error
+      ? String((error as { name: unknown }).name)
+      : "";
+  if (name === "NotAllowedError" || name === "SecurityError") {
+    return "FrockBot needs permission to use your microphone. Allow it in your browser, then try again.";
+  }
+  if (name === "NotFoundError" || name === "OverconstrainedError") {
+    return "No microphone was found. Plug one in, then try again.";
+  }
+  return `The microphone couldn't start: ${
+    error instanceof Error && error.message ? error.message : "unknown error"
+  }`;
+}
+
+export async function startVoiceMicrophoneV1(
+  options: VoiceMicrophoneOptionsV1,
+): Promise<VoiceMicrophoneV1> {
+  const stream = await navigator.mediaDevices.getUserMedia({
+    audio: {
+      channelCount: 1,
+      echoCancellation: true,
+      noiseSuppression: true,
+      autoGainControl: true,
+    },
+  });
+  const context = new AudioContext();
+  let node: AudioWorkletNode | undefined;
+  let source: MediaStreamAudioSourceNode | undefined;
+  let silence: GainNode | undefined;
+  try {
+    // Same-origin, so `script-src 'self'` admits it. See `voice-worklet.ts`.
+    await context.audioWorklet.addModule(VOICE_CAPTURE_WORKLET_PATH_V1);
+    node = new AudioWorkletNode(context, VOICE_CAPTURE_WORKLET_PROCESSOR_V1, {
+      numberOfInputs: 1,
+      // One silent output, connected below. A graph is pulled from the
+      // destination, so a node with no path to it is never asked to process
+      // and the microphone produces nothing at all — silently.
+      numberOfOutputs: 1,
+      outputChannelCount: [1],
+      processorOptions: {
+        targetRate: VOICE_CAPTURE_SAMPLE_RATE_V1,
+        frameSamples: FRAME_SAMPLES,
+      },
+    });
+    node.port.onmessage = (event: MessageEvent) => {
+      const message = event.data as { pcm?: ArrayBuffer; level?: number };
+      if (message.pcm) options.audio(message.pcm);
+      if (typeof message.level === "number") options.level(message.level);
+    };
+    source = context.createMediaStreamSource(stream);
+    source.connect(node);
+    // Silenced at the sink rather than left unconnected: the person must not
+    // hear themselves, and the node must still be pulled.
+    silence = context.createGain();
+    silence.gain.value = 0;
+    node.connect(silence);
+    silence.connect(context.destination);
+    // A suspended context produces silence and no error at all; Safari hands
+    // one back whenever the gesture that opened it has already finished.
+    if (context.state === "suspended") await context.resume();
+  } catch (error) {
+    for (const track of stream.getTracks()) track.stop();
+    await context.close().catch(() => undefined);
+    throw error;
+  }
+
+  let stopped = false;
+  return {
+    async stop() {
+      if (stopped) return;
+      stopped = true;
+      if (node) node.port.onmessage = null;
+      source?.disconnect();
+      node?.disconnect();
+      silence?.disconnect();
+      for (const track of stream.getTracks()) track.stop();
+      await context.close().catch(() => undefined);
+    },
+  };
+}

package/src/client/voice-worklet.ts

@@ -0,0 +1,75 @@
+// The dictation capture worklet, and the path the app serves it from.
+//
+// It is a first-party asset on the app's own origin rather than a blob URL,
+// and that is a security decision, not a packaging one: the hosted client is
+// served under `script-src 'self'`, which a `blob:` module does not satisfy —
+// `context.audioWorklet.addModule(blobUrl)` fails with "Unable to load a
+// worklet's module". Widening the policy to admit blob scripts everywhere, to
+// load one 40-line file, is the wrong trade. So the source lives here as a
+// string, the application Worker answers `GET` on the path below with it
+// (`apps/cloudflare/src/user-application.ts`), and the policy is untouched.
+//
+// Its own module so the Worker can serve the source without pulling the
+// browser-only microphone plumbing in beside it.
+
+/** Where the application Worker serves {@link VOICE_CAPTURE_WORKLET_SOURCE_V1}. */
+export const VOICE_CAPTURE_WORKLET_PATH_V1 = "/voice-capture-worklet.js";
+
+/** The processor's registered name, shared by the source and the node. */
+export const VOICE_CAPTURE_WORKLET_PROCESSOR_V1 = "frock-voice-capture";
+
+/**
+ * Microphone audio, decimated to the target rate and framed as PCM16.
+ *
+ * On the audio thread rather than the main one, because the alternative
+ * (`ScriptProcessorNode`) shares the thread with Vue's renderer and drops
+ * audio exactly when the composer is busiest — while the draft it is writing
+ * is being re-laid out.
+ *
+ * The rate is reached by decimating whatever the context gives us rather than
+ * by asking for it: iOS Safari ignores `new AudioContext({ sampleRate })` and
+ * hands back 48 kHz regardless, and audio at the wrong rate transcribes as
+ * gibberish rather than failing.
+ */
+export const VOICE_CAPTURE_WORKLET_SOURCE_V1 = `
+class FrockVoiceCapture extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+    this.target = options.processorOptions.targetRate;
+    this.frame = options.processorOptions.frameSamples;
+    this.buffer = new Float32Array(this.frame);
+    this.filled = 0;
+    this.position = 0;
+  }
+  process(inputs) {
+    const channel = inputs[0] && inputs[0][0];
+    if (!channel) return true;
+    const step = sampleRate / this.target;
+    let peak = 0;
+    for (let index = 0; index < channel.length; index += 1) {
+      const value = channel[index];
+      const magnitude = value < 0 ? -value : value;
+      if (magnitude > peak) peak = magnitude;
+    }
+    // Decimation: walk the block at a fractional step, carrying the remainder
+    // across blocks so no drift accumulates. Enough for speech, and cheap.
+    while (this.position < channel.length) {
+      this.buffer[this.filled] = channel[Math.floor(this.position)];
+      this.position += step;
+      this.filled += 1;
+      if (this.filled === this.frame) {
+        const pcm = new Int16Array(this.frame);
+        for (let sample = 0; sample < this.frame; sample += 1) {
+          const clamped = Math.max(-1, Math.min(1, this.buffer[sample]));
+          pcm[sample] = clamped < 0 ? clamped * 0x8000 : clamped * 0x7fff;
+        }
+        this.port.postMessage({ pcm: pcm.buffer, level: peak }, [pcm.buffer]);
+        this.filled = 0;
+      }
+    }
+    this.position -= channel.length;
+    return true;
+  }
+}
+registerProcessor("${VOICE_CAPTURE_WORKLET_PROCESSOR_V1}", FrockVoiceCapture);
+`;

package/src/shared.ts

@@ -22,6 +22,10 @@ import type {
   SendToUserPayloadV1,
   SkillRefV1,
 } from "@frockbot/kernel-contracts";
+import type {
+  VoiceDictationObserverV1,
+  VoiceDictationSessionV1,
+} from "@frockbot/client-core";
 import type { McpServerStatusViewV1 } from "@frockbot/plugin-mcp/records";
 import type { PackageSettingDefinition } from "@frockbot/kernel-composition";
 import type { ClientSkillCatalogEntryV1 } from "./skill-protocol.js";
@@ -256,6 +260,12 @@ export interface FrockBotWebData {
   modelSource: "bot" | "default" | "none";
   settingsAvailable: boolean;
   connectionsAvailable: boolean;
+  /**
+   * False when this platform cannot dictate — no transport socket, or a
+   * browser with no microphone API. The composer's send button then never
+   * changes shape and nothing about it moves.
+   */
+  voiceAvailable: boolean;
   activeBotId?: string;
   composerContext?: unknown;
   messages: WebChatMessage[];
@@ -511,6 +521,13 @@ export interface FrockBotWebData {
     skills?: readonly SkillRefV1[],
   ): Promise<SendPromptResult>;
   resumeRun(runId: string): Promise<void>;
+  /**
+   * Opens one dictation session (voice plan D2). `undefined` on a platform
+   * whose transport cannot, which is what `voiceAvailable` reports up front.
+   */
+  openVoiceDictation(
+    observer: VoiceDictationObserverV1,
+  ): VoiceDictationSessionV1 | undefined;
   /** Sends the durable Stop command for the observed active run. */
   stopRun(): Promise<void>;
   /** Detaches the local observer only; admitted work stays durable. */