@1presence/speech 1.0.0

package/README.md

@@ -0,0 +1,129 @@
+# @1presence/speech
+
+**Free, private speech-to-text for Mac. No cloud. No subscription. No monthly fee.**
+
+Dictate into any app on your Mac — terminal, editor, notes, chat, anything — using the speech recognition that is already built into Chrome or Edge. Your voice is processed entirely on your device; nothing leaves your machine.
+
+One command to start:
+
+```bash
+npx @1presence/speech
+```
+
+Your browser opens automatically. Start speaking.
+
+---
+
+## Why this exists
+
+macOS has excellent voice input, but routing speech into a terminal or a specific app is harder than it should be. This tool fills that gap: a clean browser UI where you dictate, review your words, and send them — live, as you speak — into wherever your cursor is sitting.
+
+It works with your browser's built-in Web Speech API (Chrome and Edge on Mac have the best recognition quality). No API keys. No account. No sending audio to a third party. Just open it and talk.
+
+---
+
+## Requirements
+
+- Node.js 18 or later
+- Chrome or Edge (Web Speech API has the widest support there)
+- macOS (keystroke injection uses AppleScript; the browser UI works on any OS, but the send-to-app feature is Mac-only)
+
+---
+
+## Usage
+
+### One-off, no install needed
+
+```bash
+npx @1presence/speech
+```
+
+The browser opens at `http://127.0.0.1:8787` automatically. Allow microphone access when Chrome asks. Start speaking — words appear in the transcript as you go.
+
+### Installed globally
+
+```bash
+npm install -g @1presence/speech
+1presence-speech
+```
+
+### In a project
+
+```bash
+npm install @1presence/speech
+npx 1presence-speech
+```
+
+---
+
+## Sending text to apps
+
+Three delivery modes — pick from the dropdown:
+
+| Mode | How it works | Best for |
+|------|-------------|----------|
+| **Focused app typed keystrokes** | AppleScript `keystroke` — types character by character into the focused window | Most apps, most of the time |
+| **Frontmost app via paste** | Copies to clipboard and sends Cmd+V | Apps that handle paste better than keystroke |
+| **iTerm active session** | iTerm's native `write text` API | iTerm users |
+
+**Click "Send to app"** to send the full transcript at any time. Or leave **Live word mode** enabled (the default) to stream words into the focused app as you speak — no need to click between sentences.
+
+---
+
+## macOS permissions
+
+The first time you send text, macOS will block it. Here is how to fix that in under a minute:
+
+1. Open **System Settings > Privacy & Security > Accessibility**
+2. Find the app you used to run the command — Terminal, iTerm, Warp, VS Code, Cursor — and enable it
+3. If it is not listed, click **+** and add it from `/Applications`
+4. Fully quit and reopen that app, then run `npx @1presence/speech` again
+
+If macOS still blocks input after enabling the app, reset the Accessibility permissions database:
+
+```bash
+tccutil reset Accessibility
+```
+
+Then repeat the steps above.
+
+For **iTerm mode**, also open **System Settings > Privacy & Security > Automation** and allow your terminal to control iTerm.
+
+---
+
+## Options
+
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` | `8787` | Port the local server listens on |
+| `HOST` | `127.0.0.1` | Host to bind — loopback only by default |
+
+---
+
+## How it works
+
+A small Node.js HTTP server (zero dependencies) serves the browser UI and exposes a `POST /paste` endpoint. The browser page uses the Web Speech API for recognition — Chrome's built-in engine, running entirely on device. When words are ready, the page posts them to the local server, which uses AppleScript (`osascript`) to deliver them to the focused app. Nothing hits the internet.
+
+Live word mode sends words as they are recognised, before Chrome finalises the transcript, so they appear in your app immediately. A phrase-ordering gate in the browser ensures words always arrive in the correct sequence even when Chrome is processing multiple speech segments in parallel.
+
+---
+
+## Part of 1Presence
+
+This tool is part of [1Presence](https://1presence.com) — an AI agent that lives in your pocket. It reads your notes and email, remembers your conversations across sessions, connects to the tools you already use, and works from your phone, tablet, or any browser without needing an app install.
+
+Speech Terminal is one piece of the productivity toolkit we built for ourselves and decided to share. If you want an AI that truly knows your context — not just the last few messages — [1Presence](https://1presence.com) is worth a look.
+
+---
+
+## Troubleshooting
+
+**"Unsupported" error** — Open the page in Chrome or Edge. Safari and Firefox do not support the Web Speech API.
+
+**Error 1002** — macOS blocked keystroke injection. Grant Accessibility permission to the terminal app running the server, fully quit and reopen it, then try again.
+
+**Speech stops after a few seconds** — Chrome may have revoked microphone access. Click the lock icon in the address bar and set Microphone to Allow.
+
+**iTerm does not appear in Automation settings** — Click **Test in 3s** to trigger the macOS permission prompt, then check **System Settings > Privacy & Security > Automation**.
+
+**Words arrive out of order or duplicated** — Make sure you are on the latest version: `npx @1presence/speech@latest`. Version 1.0.0 fixed a phrase-ordering bug that could scramble live-word output during fast continuous speech.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@1presence/speech",
+  "version": "1.0.0",
+  "description": "Free speech-to-text for Mac — dictate into any app using your browser's built-in voice recognition, no subscription required",
+  "type": "module",
+  "bin": {
+    "1presence-speech": "server.mjs"
+  },
+  "files": [
+    "server.mjs",
+    "public",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node server.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "speech-to-text",
+    "dictation",
+    "voice",
+    "macos",
+    "accessibility",
+    "web-speech-api",
+    "free",
+    "terminal",
+    "productivity"
+  ],
+  "license": "MIT",
+  "homepage": "https://1presence.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jonathankata/presence"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/public/index.html

@@ -0,0 +1,483 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Speech Terminal</title>
+    <link rel="stylesheet" href="/styles.css" />
+  </head>
+  <body>
+    <main class="shell">
+      <section class="panel">
+        <div class="topbar">
+          <div>
+            <h1>Speech Terminal</h1>
+            <p>Dictate in Chrome, review the text, then send it into the focused app.</p>
+          </div>
+          <div class="status" id="status">Idle</div>
+        </div>
+
+        <div class="controls">
+          <button id="start" type="button">Start</button>
+          <button id="stop" type="button" disabled>Stop</button>
+          <button id="send" type="button">Send to app</button>
+          <button id="test" type="button" class="secondary">Test in 3s</button>
+          <button id="diagnosticsButton" type="button" class="secondary">Diagnostics</button>
+          <button id="clear" type="button" class="secondary">Clear</button>
+        </div>
+
+        <label class="field">
+          <span>Destination</span>
+          <select id="destination">
+            <option value="type">Focused app typed keystrokes</option>
+            <option value="iterm">iTerm active session</option>
+            <option value="frontmost">Frontmost app via paste</option>
+          </select>
+        </label>
+
+        <label class="toggle">
+          <input id="liveWords" type="checkbox" checked />
+          <span>Live word mode: send words as they are recognized</span>
+        </label>
+
+        <textarea id="transcript" spellcheck="true" placeholder="Your dictated text will appear here."></textarea>
+
+        <div class="hint" id="hint">
+          Web Speech API works best in Chrome or Edge. The default destination types into whichever app has focus after macOS Accessibility permission is granted.
+        </div>
+
+        <section class="setup" aria-labelledby="setup-title">
+          <h2 id="setup-title">macOS Setup</h2>
+          <ol>
+            <li>Start this bridge from Terminal, iTerm, Warp, or the terminal app you normally use: <code>cd speech &amp;&amp; npm start</code>.</li>
+            <li>Open this page in Chrome or Edge at <code>http://127.0.0.1:8787</code>.</li>
+            <li>When the browser asks for microphone access, allow it. The page tries to start listening automatically; if Chrome blocks auto-start, click <strong>Start</strong>.</li>
+            <li>Leave <strong>Destination</strong> set to <strong>Focused app typed keystrokes</strong> for the broadest app support.</li>
+            <li>Click <strong>Test in 3s</strong>, focus any app text input within three seconds, and wait for the test text. If macOS asks for Accessibility access, allow it.</li>
+            <li>Open <strong>System Settings -&gt; Privacy &amp; Security -&gt; Accessibility</strong>.</li>
+            <li>Enable the app that is running <code>npm start</code>: Terminal, iTerm, Warp, Visual Studio Code, Cursor, or whichever app launched the server. If it is missing, click <strong>+</strong> and add it from <code>/Applications</code>.</li>
+            <li>If that app is already enabled but keystrokes are still blocked, toggle it off and on, or remove it and add it again.</li>
+            <li>For iTerm, also check <strong>System Settings -&gt; Privacy &amp; Security -&gt; Automation</strong> and allow the app running <code>npm start</code> to control iTerm.</li>
+            <li>Fully quit and reopen the app running <code>npm start</code>, then restart <code>npm start</code> after granting permission.</li>
+            <li>For manual mode, dictate here, edit the transcript, focus the target app, then click <strong>Send to app</strong>.</li>
+            <li>For terminal mode, focus the target app, then speak. Speech is sent automatically without returning to this page.</li>
+            <li>Short pauses create a new line in the transcript. Longer pauses add a full stop, start the next phrase with a capital letter, and show a blank line.</li>
+            <li><strong>Live word mode</strong> is enabled by default. It sends words earlier and optimistically while you speak. Turn it off to send only after the browser marks speech as settled.</li>
+          </ol>
+
+          <div class="callout">
+            <strong>If you see error 1002:</strong>
+            macOS has not allowed the server app to control keystrokes yet. Grant Accessibility permission to the app running this server, not to Chrome. Then fully quit and reopen that app, restart <code>npm start</code>, refresh this page, and try <strong>Test in 3s</strong> again.
+          </div>
+
+          <div class="callout">
+            <strong>If Accessibility still blocks input:</strong>
+            run <code>tccutil reset Accessibility</code>, then repeat the Accessibility setup. This resets the macOS approval database for synthetic keystrokes.
+          </div>
+
+          <div class="callout">
+            <strong>If iTerm does not appear in Automation:</strong>
+            switch Destination to <strong>iTerm active session</strong>, click <strong>Test in 3s</strong> first to trigger the macOS prompt, and allow the request if macOS asks. If it still does not appear, run <code>tccutil reset AppleEvents</code>, restart this server, then click <strong>Test in 3s</strong> again. macOS may list the controller as Terminal, iTerm, Warp, Visual Studio Code, Cursor, or osascript depending on how the server was started.
+          </div>
+
+          <pre id="diagnostics" class="diagnostics" hidden></pre>
+        </section>
+      </section>
+    </main>
+
+    <script>
+      const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition;
+      const statusEl = document.getElementById("status");
+      const transcriptEl = document.getElementById("transcript");
+      const startButton = document.getElementById("start");
+      const stopButton = document.getElementById("stop");
+      const sendButton = document.getElementById("send");
+      const testButton = document.getElementById("test");
+      const diagnosticsButton = document.getElementById("diagnosticsButton");
+      const diagnosticsEl = document.getElementById("diagnostics");
+      const clearButton = document.getElementById("clear");
+      const destinationEl = document.getElementById("destination");
+      const liveWordsEl = document.getElementById("liveWords");
+
+      let recognition = null;
+      let finalText = "";
+      let listening = false;
+      let sendQueue = Promise.resolve();
+      const resultState = new Map();
+      let hasFinalSpeech = false;
+      let lastFinalAt = 0;
+      const SHORT_PAUSE_MS = 1000;
+      const LONG_PAUSE_MS = 2400;
+
+      function setStatus(text, tone = "") {
+        statusEl.textContent = text;
+        statusEl.dataset.tone = tone;
+      }
+
+      function setListening(nextListening) {
+        listening = nextListening;
+        startButton.hidden = listening;
+        startButton.disabled = listening;
+        stopButton.disabled = !listening;
+      }
+
+      function appendFinal(text, state) {
+        const normalized = normalizeSpeechText(text);
+        if (!normalized) return;
+
+        applyDisplaySeparator(state);
+        finalText = `${finalText}${formatChunkText(normalized, state)}`;
+        hasFinalSpeech = true;
+        lastFinalAt = Date.now();
+      }
+
+      async function sendToTerminal(text, pressEnter) {
+        const response = await fetch("/paste", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            text,
+            pressEnter,
+            destination: destinationEl.value,
+          }),
+        });
+        const payload = await response.json();
+
+        if (!payload.ok) {
+          throw new Error(payload.error || "Paste failed.");
+        }
+      }
+
+      function queueAutoSend(text) {
+        if (!text) return;
+
+        sendQueue = sendQueue
+          .then(async () => {
+            setStatus("Sending", "active");
+            await sendToTerminal(text, false);
+            setStatus("Listening", "active");
+          })
+          .catch((error) => {
+            setStatus(error.message, "error");
+            if (recognition && listening) recognition.stop();
+          });
+      }
+
+      function normalizeSpeechText(text) {
+        return text.replace(/\s+/g, " ").trim();
+      }
+
+      function capitalizeFirstWord(text) {
+        return text.replace(/[A-Za-z]/, (letter) => letter.toUpperCase());
+      }
+
+      function endsWithSentencePunctuation(text) {
+        return /[.!?]["')\]]?$/.test(text.trim());
+      }
+
+      function getPauseType() {
+        if (!hasFinalSpeech || !lastFinalAt) return "none";
+
+        const pauseMs = Date.now() - lastFinalAt;
+        if (pauseMs >= LONG_PAUSE_MS) return "long";
+        if (pauseMs >= SHORT_PAUSE_MS) return "short";
+        return "none";
+      }
+
+      function createResultState() {
+        return {
+          sentText: "",
+          finalizedText: "",
+          pauseType: getPauseType(),
+          appPrefixSent: false,
+          displaySeparatorApplied: false,
+        };
+      }
+
+      function splitSpeechWords(text) {
+        const normalized = normalizeSpeechText(text);
+        return normalized ? normalized.split(" ") : [];
+      }
+
+      function commonPrefixLength(leftWords, rightWords) {
+        let index = 0;
+        while (index < leftWords.length && index < rightWords.length && leftWords[index] === rightWords[index]) {
+          index += 1;
+        }
+        return index;
+      }
+
+      function getResultState(resultIndex) {
+        if (!resultState.has(resultIndex)) {
+          resultState.set(resultIndex, createResultState());
+        }
+        return resultState.get(resultIndex);
+      }
+
+      function resetResultState(resultIndex) {
+        const nextState = createResultState();
+        resultState.set(resultIndex, nextState);
+        return nextState;
+      }
+
+      function formatChunkText(text, state) {
+        const normalized = normalizeSpeechText(text);
+        if (!normalized) return "";
+        return !hasFinalSpeech || state.pauseType === "long" ? capitalizeFirstWord(normalized) : normalized;
+      }
+
+      function getDisplaySeparator(state, sourceText = finalText) {
+        if (!hasFinalSpeech) return "";
+        if (state.pauseType === "long") {
+          return `${endsWithSentencePunctuation(sourceText) ? "" : "."}\n\n`;
+        }
+        if (state.pauseType === "short") return "\n";
+        return " ";
+      }
+
+      function applyDisplaySeparator(state) {
+        if (state.displaySeparatorApplied) return;
+        const separator = getDisplaySeparator(state);
+
+        if (separator) {
+          finalText = `${finalText.trimEnd()}${separator}`;
+        }
+
+        state.displaySeparatorApplied = true;
+      }
+
+      function getAppPrefix(state) {
+        if (!hasFinalSpeech || state.appPrefixSent) return "";
+        if (state.pauseType !== "long") return "";
+        return endsWithSentencePunctuation(finalText) ? " " : ". ";
+      }
+
+      // Normalise a word for comparison: lowercase + strip leading/trailing
+      // punctuation. Keeps apostrophes so contractions ("it's") match correctly.
+      // This lets "sure" match "sure," and "Testing" match "testing".
+      function wordKey(w) {
+        return w.toLowerCase().replace(/^[^a-z0-9']+|[^a-z0-9']+$/gi, "");
+      }
+
+      function getSpeechDelta(previous, next, allowCorrection) {
+        const previousWords = splitSpeechWords(previous);
+        const nextWords = splitSpeechWords(next);
+
+        if (!nextWords.length) return "";
+
+        const prevKeys = previousWords.map(wordKey);
+        const nextKeys = nextWords.map(wordKey);
+
+        const fullPrefixMatches =
+          prevKeys.length <= nextKeys.length &&
+          prevKeys.every((key, index) => key === nextKeys[index]);
+
+        if (fullPrefixMatches) {
+          return nextWords.slice(previousWords.length).join(" ");
+        }
+
+        if (!allowCorrection) return "";
+
+        return nextWords.slice(commonPrefixLength(prevKeys, nextKeys)).join(" ");
+      }
+
+      function getReadyInterimText(text) {
+        const normalized = normalizeSpeechText(text);
+        const boundary = normalized.lastIndexOf(" ");
+
+        if (boundary === -1) return;
+        return normalized.slice(0, boundary);
+      }
+
+      function queueResultDelta(resultIndex, text, onlyCompleteWords, isFinal) {
+        let state = getResultState(resultIndex);
+
+        if (!isFinal && state.finalizedText) {
+          state = resetResultState(resultIndex);
+        }
+
+        const candidate = onlyCompleteWords ? getReadyInterimText(text) : normalizeSpeechText(text);
+        const normalizedCandidate = formatChunkText(candidate || "", state);
+
+        if (!normalizedCandidate) return;
+        if (isFinal && state.finalizedText === normalizedCandidate) return;
+
+        const delta = getSpeechDelta(state.sentText, normalizedCandidate, isFinal);
+
+        if (delta) {
+          const prefix = getAppPrefix(state);
+          state.appPrefixSent = true;
+          queueAutoSend(`${prefix}${delta} `);
+        }
+
+        state.sentText = normalizedCandidate;
+        if (isFinal) {
+          state.finalizedText = normalizedCandidate;
+        }
+      }
+
+      function createRecognition() {
+        if (!SpeechRecognition) {
+          setStatus("Unsupported", "error");
+          startButton.disabled = true;
+          return null;
+        }
+
+        const rec = new SpeechRecognition();
+        rec.continuous = true;
+        rec.interimResults = true;
+        rec.lang = navigator.language || "en-US";
+
+        rec.onstart = () => {
+          setListening(true);
+          resultState.clear();
+          setStatus("Listening", "active");
+        };
+
+        rec.onend = () => {
+          setListening(false);
+          setStatus("Idle");
+        };
+
+        rec.onerror = (event) => {
+          setStatus(event.error || "Speech error", "error");
+          setListening(false);
+        };
+
+        rec.onresult = (event) => {
+          let displayText = finalText;
+
+          for (let i = event.resultIndex; i < event.results.length; i += 1) {
+            const result = event.results[i];
+            const text = result[0].transcript;
+            let state = getResultState(i);
+            if (!result.isFinal && state.finalizedText) {
+              state = resetResultState(i);
+            }
+
+            if (result.isFinal) {
+              queueResultDelta(i, text, false, true);
+              appendFinal(text, state);
+              displayText = finalText;
+            } else {
+              const formattedInterimText = formatChunkText(text, state);
+              if (formattedInterimText) {
+                displayText = `${displayText.trimEnd()}${getDisplaySeparator(state, displayText)}${formattedInterimText}`;
+              }
+              if (liveWordsEl.checked) {
+                // Gate: only live-word result i if all earlier results have
+                // finalised. Chrome can fire interim events for result N+1
+                // before result N finalises; without this guard their words
+                // land in the send queue out of order.
+                const prevState = i > 0 ? resultState.get(i - 1) : null;
+                if (!prevState || prevState.finalizedText) {
+                  queueResultDelta(i, text, true, false);
+                }
+              }
+            }
+          }
+
+          transcriptEl.value = displayText;
+        };
+
+        return rec;
+      }
+
+      function startRecognition() {
+        recognition = recognition || createRecognition();
+        if (!recognition || listening) return;
+
+        finalText = transcriptEl.value ? transcriptEl.value.trim() : "";
+        hasFinalSpeech = Boolean(finalText);
+        lastFinalAt = hasFinalSpeech ? Date.now() : 0;
+        try {
+          recognition.start();
+        } catch (error) {
+          setListening(false);
+          setStatus(error.message || "Click Start", "error");
+        }
+      }
+
+      startButton.addEventListener("click", () => {
+        startRecognition();
+      });
+
+      stopButton.addEventListener("click", () => {
+        if (recognition && listening) recognition.stop();
+      });
+
+      clearButton.addEventListener("click", () => {
+        finalText = "";
+        resultState.clear();
+        hasFinalSpeech = false;
+        lastFinalAt = 0;
+        transcriptEl.value = "";
+        transcriptEl.focus();
+      });
+
+      sendButton.addEventListener("click", async () => {
+        const text = transcriptEl.value.trim();
+        if (!text) {
+          setStatus("No text", "error");
+          return;
+        }
+
+        sendButton.disabled = true;
+        setStatus("Sending", "active");
+
+        try {
+          await sendToTerminal(text, false);
+          setStatus("Sent", "success");
+        } catch (error) {
+          setStatus(error.message, "error");
+        } finally {
+          sendButton.disabled = false;
+        }
+      });
+
+      testButton.addEventListener("click", async () => {
+        testButton.disabled = true;
+        setStatus("Focus target", "active");
+
+        try {
+          await new Promise((resolve) => setTimeout(resolve, 3000));
+          setStatus("Testing", "active");
+          await sendToTerminal("speech terminal test ", false);
+          setStatus("Test sent", "success");
+        } catch (error) {
+          setStatus(error.message, "error");
+        } finally {
+          testButton.disabled = false;
+        }
+      });
+
+      diagnosticsButton.addEventListener("click", async () => {
+        diagnosticsButton.disabled = true;
+        setStatus("Checking", "active");
+
+        try {
+          const response = await fetch("/diagnostics", { method: "POST" });
+          const payload = await response.json();
+          if (!payload.ok) throw new Error(payload.error || "Diagnostics failed.");
+          diagnosticsEl.hidden = false;
+          diagnosticsEl.textContent = JSON.stringify(payload.diagnostics, null, 2);
+          setStatus("Checked", "success");
+        } catch (error) {
+          setStatus(error.message, "error");
+        } finally {
+          diagnosticsButton.disabled = false;
+        }
+      });
+
+      if (!SpeechRecognition) {
+        setStatus("Unsupported", "error");
+        startButton.disabled = true;
+      }
+
+      setListening(false);
+      window.addEventListener("load", () => {
+        startRecognition();
+      });
+    </script>
+  </body>
+</html>

package/public/styles.css

@@ -0,0 +1,452 @@
+@import url("https://fonts.googleapis.com/css2?family=Gilda+Display&family=Alegreya:ital,wght@0,400;0,500;0,700;1,400;1,500&family=Jost:wght@300;400;500&display=swap");
+
+:root {
+  color-scheme: light;
+
+  --font-display: "Gilda Display", Georgia, serif;
+  --font-body: "Alegreya", Georgia, serif;
+  --font-ui: "Jost", system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
+
+  --surface: oklch(0.955 0.018 82);
+  --surface-raised: oklch(0.910 0.026 76);
+  --surface-overlay: oklch(0.930 0.020 80);
+  --surface-hover: oklch(0.895 0.030 74);
+  --surface-code: oklch(0.900 0.022 78);
+
+  --text-primary: oklch(0.220 0.030 50);
+  --text-secondary: oklch(0.450 0.038 55);
+  --text-tertiary: oklch(0.620 0.022 62);
+  --text-faint: oklch(0.680 0.014 65);
+
+  --accent: oklch(0.420 0.082 52);
+  --accent-hover: oklch(0.360 0.088 50);
+  --text-on-accent: oklch(0.960 0.010 82);
+  --accent-soft: oklch(0.920 0.030 56);
+  --accent-soft-2: oklch(0.880 0.038 54);
+
+  --green: oklch(0.45 0.075 145);
+  --green-soft: oklch(0.92 0.035 145);
+  --amber: oklch(0.55 0.090 75);
+  --amber-soft: oklch(0.93 0.045 80);
+  --red: oklch(0.50 0.110 28);
+  --red-soft: oklch(0.93 0.040 30);
+
+  --border-subtle: oklch(0.880 0.016 78);
+  --border: oklch(0.820 0.020 72);
+  --border-strong: oklch(0.720 0.028 65);
+
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-12: 48px;
+
+  --radius-sm: 6px;
+  --radius-md: 8px;
+  --radius-full: 9999px;
+
+  --ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);
+  --shadow-sm: 0 1px 4px oklch(0.22 0.030 50 / 0.07);
+  --shadow-md: 0 4px 20px oklch(0.22 0.030 50 / 0.09);
+  --shadow-lg: 0 8px 40px oklch(0.22 0.030 50 / 0.12);
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html {
+  min-height: 100%;
+  background: var(--surface);
+  font-size: 16px;
+  -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background:
+    radial-gradient(circle at 18% 0%, oklch(0.990 0.020 88 / 0.78), transparent 34rem),
+    linear-gradient(180deg, var(--surface), oklch(0.938 0.022 78));
+  color: var(--text-primary);
+  font-family: var(--font-ui);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+button,
+select,
+textarea {
+  font: inherit;
+}
+
+button,
+select,
+input,
+textarea {
+  color: inherit;
+}
+
+:focus {
+  outline: none;
+}
+
+:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+.shell {
+  min-height: 100vh;
+  display: grid;
+  place-items: start center;
+  padding: clamp(var(--space-4), 5vw, var(--space-12));
+}
+
+.panel {
+  width: min(920px, 100%);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  background: color-mix(in oklch, var(--surface) 82%, var(--surface-overlay));
+  padding: clamp(var(--space-5), 4vw, var(--space-8));
+  box-shadow: var(--shadow-lg);
+}
+
+.topbar {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--space-6);
+}
+
+h1,
+h2,
+p {
+  margin: 0;
+}
+
+h1 {
+  font-family: var(--font-display);
+  font-size: clamp(2.15rem, 8vw, 4.75rem);
+  font-weight: 400;
+  line-height: 0.96;
+  letter-spacing: 0;
+  color: var(--text-primary);
+}
+
+p {
+  max-width: 58ch;
+  margin-top: var(--space-3);
+  color: var(--text-secondary);
+  font-family: var(--font-body);
+  font-size: 1.16rem;
+  line-height: 1.55;
+}
+
+.status {
+  flex: 0 0 auto;
+  min-width: 112px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-full);
+  padding: 7px 12px;
+  text-align: center;
+  color: var(--text-secondary);
+  background: var(--surface-overlay);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  box-shadow: var(--shadow-sm);
+}
+
+.status[data-tone="active"] {
+  border-color: var(--accent-soft-2);
+  background: var(--accent-soft);
+  color: var(--accent);
+}
+
+.status[data-tone="success"] {
+  border-color: color-mix(in oklch, var(--green), var(--border) 58%);
+  background: var(--green-soft);
+  color: var(--green);
+}
+
+.status[data-tone="error"] {
+  border-color: color-mix(in oklch, var(--red), var(--border) 58%);
+  background: var(--red-soft);
+  color: var(--red);
+}
+
+.controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  margin-top: var(--space-8);
+}
+
+button {
+  min-height: 44px;
+  border: 1px solid transparent;
+  border-radius: var(--radius-md);
+  padding: 0 var(--space-4);
+  background: var(--accent);
+  color: var(--text-on-accent);
+  cursor: pointer;
+  font-weight: 500;
+  transition:
+    background 160ms var(--ease-out-quart),
+    border-color 160ms var(--ease-out-quart),
+    transform 160ms var(--ease-out-quart),
+    opacity 160ms var(--ease-out-quart);
+}
+
+button:hover:not(:disabled) {
+  background: var(--accent-hover);
+  transform: translateY(-1px);
+}
+
+button:active:not(:disabled) {
+  transform: translateY(0);
+}
+
+button:disabled {
+  cursor: not-allowed;
+  opacity: 0.48;
+}
+
+button[hidden] {
+  display: none;
+}
+
+button.secondary {
+  border-color: var(--border);
+  background: var(--surface-overlay);
+  color: var(--text-secondary);
+}
+
+button.secondary:hover:not(:disabled) {
+  border-color: var(--border-strong);
+  background: var(--surface-hover);
+  color: var(--text-primary);
+}
+
+.field {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  margin-top: var(--space-5);
+  color: var(--text-secondary);
+  font-size: 0.9375rem;
+}
+
+.field span {
+  font-weight: 500;
+}
+
+.field select {
+  min-height: 40px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: 0 var(--space-3);
+  background: var(--surface-overlay);
+  color: var(--text-primary);
+  box-shadow: var(--shadow-sm);
+}
+
+.toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  margin-top: var(--space-4);
+  margin-right: var(--space-5);
+  color: var(--text-secondary);
+  font-size: 0.9375rem;
+  line-height: 1.4;
+}
+
+.toggle input {
+  width: 18px;
+  height: 18px;
+  accent-color: var(--accent);
+}
+
+textarea {
+  display: block;
+  width: 100%;
+  min-height: 280px;
+  margin-top: var(--space-5);
+  resize: vertical;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: var(--space-5);
+  background: color-mix(in oklch, var(--surface) 78%, var(--surface-overlay));
+  color: var(--text-primary);
+  font-family: var(--font-body);
+  font-size: 1.125rem;
+  line-height: 1.62;
+  box-shadow: inset 0 1px 0 oklch(0.985 0.010 82 / 0.42);
+  transition:
+    border-color 160ms var(--ease-out-quart),
+    background 160ms var(--ease-out-quart),
+    box-shadow 160ms var(--ease-out-quart);
+}
+
+textarea::placeholder {
+  color: var(--text-faint);
+}
+
+textarea:focus {
+  border-color: var(--border-strong);
+  background: var(--surface);
+  box-shadow:
+    inset 0 1px 0 oklch(0.985 0.010 82 / 0.48),
+    0 0 0 3px color-mix(in oklch, var(--accent-soft), transparent 32%);
+}
+
+.hint {
+  max-width: 66ch;
+  margin-top: var(--space-4);
+  color: var(--text-tertiary);
+  font-family: var(--font-body);
+  font-size: 1rem;
+  line-height: 1.5;
+}
+
+.setup {
+  margin-top: var(--space-8);
+  border-top: 1px solid var(--border-subtle);
+  padding-top: var(--space-6);
+}
+
+.setup h2 {
+  margin: 0;
+  font-family: var(--font-display);
+  font-size: 1.75rem;
+  font-weight: 400;
+  line-height: 1.1;
+}
+
+.setup ol {
+  max-width: 76ch;
+  margin: var(--space-4) 0 0;
+  padding-left: 1.35rem;
+  color: var(--text-secondary);
+  font-family: var(--font-body);
+  font-size: 1.06rem;
+  line-height: 1.58;
+}
+
+.setup li + li {
+  margin-top: var(--space-2);
+}
+
+strong {
+  color: var(--text-primary);
+  font-weight: 500;
+}
+
+code {
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+  padding: 1px 6px;
+  background: var(--surface-code);
+  color: var(--text-primary);
+  font-family: var(--font-mono);
+  font-size: 0.86em;
+}
+
+.callout {
+  max-width: 76ch;
+  margin-top: var(--space-4);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  padding: var(--space-4);
+  background: var(--surface-overlay);
+  color: var(--text-secondary);
+  font-family: var(--font-body);
+  font-size: 1.02rem;
+  line-height: 1.52;
+}
+
+.callout strong {
+  color: var(--accent);
+}
+
+.diagnostics {
+  max-width: 76ch;
+  margin: var(--space-4) 0 0;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  padding: var(--space-4);
+  overflow-x: auto;
+  background: var(--surface-code);
+  color: var(--text-secondary);
+  font-family: var(--font-mono);
+  font-size: 0.8125rem;
+  line-height: 1.5;
+}
+
+@media (max-width: 640px) {
+  .shell {
+    padding: var(--space-3);
+    place-items: stretch;
+  }
+
+  .panel {
+    padding: var(--space-5);
+  }
+
+  .topbar {
+    display: block;
+  }
+
+  .status {
+    width: fit-content;
+    margin-top: var(--space-4);
+  }
+
+  .controls {
+    margin-top: var(--space-6);
+  }
+
+  .controls button {
+    flex: 1 1 148px;
+  }
+
+  .field {
+    align-items: stretch;
+    flex-direction: column;
+    gap: var(--space-2);
+  }
+
+  .field select {
+    width: 100%;
+  }
+
+  .toggle {
+    width: 100%;
+    align-items: flex-start;
+    margin-right: 0;
+  }
+
+  textarea {
+    min-height: 220px;
+    padding: var(--space-4);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    scroll-behavior: auto !important;
+    transition-duration: 0.01ms !important;
+  }
+}

package/server.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+import { exec, execFile } from "child_process";
+import { createServer } from "http";
+import { promises as fs } from "fs";
+import { extname, join, normalize } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const publicDir = join(__dirname, "public");
+const host = process.env.HOST || "127.0.0.1";
+const port = Number(process.env.PORT || 8787);
+
+const contentTypes = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+};
+
+function sendJson(res, status, payload) {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  res.end(JSON.stringify(payload));
+}
+
+async function readRequestBody(req) {
+  const chunks = [];
+  let size = 0;
+
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > 256_000) {
+      throw new Error("Request body is too large.");
+    }
+    chunks.push(chunk);
+  }
+
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function pasteIntoFocusedApp(text, pressEnter) {
+  const script = `
+on run argv
+  set the clipboard to item 1 of argv
+  tell application "System Events"
+    keystroke "v" using command down
+    if item 2 of argv is "true" then
+      key code 36
+    end if
+  end tell
+end run
+`;
+
+  return new Promise((resolve, reject) => {
+    execFile("osascript", ["-e", script, text, String(Boolean(pressEnter))], (error, stdout, stderr) => {
+      if (error) {
+        const message = stderr.trim() || error.message;
+        if (message.includes("not allowed to send keystrokes") || message.includes("(1002)")) {
+          reject(
+            new Error(
+              "macOS blocked keystrokes. Open System Settings -> Privacy & Security -> Accessibility, then enable the terminal app running this server. Restart the server after granting permission."
+            )
+          );
+          return;
+        }
+        reject(new Error(message));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+function typeIntoFocusedApp(text, pressEnter) {
+  const script = `
+on run argv
+  tell application "System Events"
+    keystroke item 1 of argv
+    if item 2 of argv is "true" then
+      key code 36
+    end if
+  end tell
+end run
+`;
+
+  return new Promise((resolve, reject) => {
+    execFile("osascript", ["-e", script, text, String(Boolean(pressEnter))], (error, stdout, stderr) => {
+      if (error) {
+        const message = stderr.trim() || error.message;
+        if (message.includes("not allowed to send keystrokes") || message.includes("(1002)")) {
+          reject(
+            new Error(
+              "macOS blocked typed keystrokes. Open System Settings -> Privacy & Security -> Accessibility, then enable the terminal app running this server and restart npm start."
+            )
+          );
+          return;
+        }
+        reject(new Error(message));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+function writeToITerm(text, pressEnter) {
+  const script = `
+on run argv
+  tell application id "com.googlecode.iterm2"
+    if (count of windows) is 0 then
+      create window with default profile
+    end if
+    tell current session of current window
+      write text item 1 of argv newline false
+      if item 2 of argv is "true" then
+        write text ""
+      end if
+    end tell
+  end tell
+end run
+`;
+
+  return new Promise((resolve, reject) => {
+    execFile("osascript", ["-e", script, text, String(Boolean(pressEnter))], (error, stdout, stderr) => {
+      if (error) {
+        const message = stderr.trim() || error.message;
+        if (message.includes("not allowed to send Apple events") || message.includes("Not authorized")) {
+          reject(
+            new Error(
+              "macOS blocked Apple Events to iTerm. Open System Settings -> Privacy & Security -> Automation and allow your terminal app to control iTerm. You may need to restart the server."
+            )
+          );
+          return;
+        }
+        reject(new Error(message));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+function runAppleScript(script, args = []) {
+  return new Promise((resolve, reject) => {
+    execFile("osascript", ["-e", script, ...args], (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error(stderr.trim() || error.message));
+        return;
+      }
+      resolve(stdout.trim());
+    });
+  });
+}
+
+async function getDiagnostics() {
+  const diagnostics = {
+    platform: process.platform,
+    node: process.version,
+    iTermBundleId: "unknown",
+    frontmostApp: "unknown",
+    controllingProcess: "osascript via node",
+  };
+
+  try {
+    diagnostics.iTermBundleId = await runAppleScript('id of application "iTerm"');
+  } catch (error) {
+    diagnostics.iTermBundleId = `unavailable: ${error.message}`;
+  }
+
+  try {
+    diagnostics.frontmostApp = await runAppleScript(
+      'tell application "System Events" to get name of first application process whose frontmost is true'
+    );
+  } catch (error) {
+    diagnostics.frontmostApp = `unavailable: ${error.message}`;
+  }
+
+  return diagnostics;
+}
+
+async function sendToDestination(payload) {
+  const destination = payload.destination || "frontmost";
+  const text = String(payload.text || "");
+
+  if (!text) {
+    throw new Error("No text to paste.");
+  }
+
+  if (destination === "iterm") {
+    await writeToITerm(text, Boolean(payload.pressEnter));
+    return;
+  }
+
+  if (destination === "type") {
+    await typeIntoFocusedApp(text, Boolean(payload.pressEnter));
+    return;
+  }
+
+  await pasteIntoFocusedApp(text, Boolean(payload.pressEnter));
+}
+
+async function serveStatic(req, res) {
+  const url = new URL(req.url, `http://${req.headers.host}`);
+  const pathname = url.pathname === "/" ? "/index.html" : url.pathname;
+  const normalized = normalize(decodeURIComponent(pathname)).replace(/^(\.\.[/\\])+/, "");
+  const filePath = join(publicDir, normalized);
+
+  if (!filePath.startsWith(publicDir)) {
+    res.writeHead(403);
+    res.end("Forbidden");
+    return;
+  }
+
+  try {
+    const content = await fs.readFile(filePath);
+    res.writeHead(200, {
+      "content-type": contentTypes[extname(filePath)] || "application/octet-stream",
+      "cache-control": "no-store",
+    });
+    res.end(req.method === "HEAD" ? undefined : content);
+  } catch {
+    res.writeHead(404);
+    res.end("Not found");
+  }
+}
+
+const server = createServer(async (req, res) => {
+  try {
+    if (req.method === "GET" || req.method === "HEAD") {
+      await serveStatic(req, res);
+      return;
+    }
+
+    if (req.method === "POST" && req.url === "/paste") {
+      const body = await readRequestBody(req);
+      const payload = JSON.parse(body || "{}");
+      await sendToDestination(payload);
+      sendJson(res, 200, { ok: true });
+      return;
+    }
+
+    if (req.method === "POST" && req.url === "/diagnostics") {
+      sendJson(res, 200, { ok: true, diagnostics: await getDiagnostics() });
+      return;
+    }
+
+    sendJson(res, 404, { ok: false, error: "Not found." });
+  } catch (error) {
+    sendJson(res, 500, { ok: false, error: error.message });
+  }
+});
+
+server.listen(port, host, () => {
+  const url = `http://${host}:${port}`;
+  console.log(`Speech Terminal  →  ${url}`);
+  console.log("Web Speech API requires Chrome or Edge. Focus your target app before speaking.");
+
+  const openCmd =
+    process.platform === "win32" ? `start "" "${url}"` :
+    process.platform === "darwin" ? `open "${url}"` :
+    `xdg-open "${url}"`;
+
+  exec(openCmd, (err) => {
+    if (err) console.log(`Could not open browser automatically. Open ${url} in Chrome or Edge.`);
+  });
+});