@earendil-works/pi-voice 0.1.0

package/src/shortcut-core.ts

@@ -0,0 +1,85 @@
+export const DEFAULT_SHORTCUT = "ctrl+alt+z";
+
+/** Widget slot shared by the startup status and the recording meter. */
+export const STATUS_WIDGET_KEY = "pi-voice-meter";
+
+const MODIFIER_ORDER = ["ctrl", "shift", "alt", "super"] as const;
+const SPECIAL_KEYS = new Set([
+  "escape",
+  "enter",
+  "tab",
+  "space",
+  "backspace",
+  "delete",
+  "insert",
+  "home",
+  "end",
+  "pageup",
+  "pagedown",
+  "up",
+  "down",
+  "left",
+  "right",
+]);
+const SYMBOL_KEYS = new Set(["`", "-", "=", "[", "]", "\\", ";", "'", ",", ".", "/"]);
+
+export function normalizeShortcut(input: string): string | undefined {
+  const parts = input
+    .trim()
+    .toLowerCase()
+    .replaceAll("option", "alt")
+    .replaceAll("command", "super")
+    .replaceAll("cmd", "super")
+    .split("+")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (parts.length === 0) return undefined;
+
+  const key = parts.at(-1)!;
+  const modifiers = parts.slice(0, -1);
+  if (new Set(modifiers).size !== modifiers.length) return undefined;
+  if (
+    modifiers.some(
+      (modifier) =>
+        !MODIFIER_ORDER.includes(modifier as (typeof MODIFIER_ORDER)[number]),
+    )
+  ) {
+    return undefined;
+  }
+
+  const isLetter = /^[a-z]$/.test(key);
+  const isDigit = /^\d$/.test(key);
+  const isFunction = /^f(?:[1-9]|1[0-2])$/.test(key);
+  const isSpecial = SPECIAL_KEYS.has(key);
+  const isSymbol = SYMBOL_KEYS.has(key);
+  if (!isLetter && !isDigit && !isFunction && !isSpecial && !isSymbol) return undefined;
+
+  // Bare printable keys would make normal editor input impossible.
+  if (modifiers.length === 0 && !isFunction) return undefined;
+  // Shift-only printable keys are also normal text input.
+  if (
+    modifiers.length === 1 &&
+    modifiers[0] === "shift" &&
+    (isLetter || isDigit || isSymbol)
+  ) {
+    return undefined;
+  }
+
+  const ordered = MODIFIER_ORDER.filter((modifier) => modifiers.includes(modifier));
+  return [
+    ...ordered,
+    key === "pageup" ? "pageUp" : key === "pagedown" ? "pageDown" : key,
+  ].join("+");
+}
+
+export function displayShortcut(shortcut: string): string {
+  return shortcut
+    .split("+")
+    .map((part) => {
+      if (process.platform === "darwin" && part.toLowerCase() === "alt") return "Option";
+      return part.length === 1
+        ? part.toUpperCase()
+        : `${part[0]?.toUpperCase()}${part.slice(1)}`;
+    })
+    .join("+");
+}

package/src/shortcuts.ts

@@ -0,0 +1,167 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  parseKey,
+  Spacer,
+  Text,
+  truncateToWidth,
+  type Component,
+  type KeybindingsManager,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import {
+  DEFAULT_SHORTCUT,
+  displayShortcut,
+  normalizeShortcut,
+} from "./shortcut-core.js";
+import { VoiceKeys } from "./keybindings.js";
+import { panelBorder } from "./ui-components.js";
+
+type UiTheme = ExtensionContext["ui"]["theme"];
+type Conflict = { description: string };
+type Phase =
+  | { kind: "waiting" }
+  | { kind: "preview"; normalized: string; conflicts: Conflict[] }
+  | { kind: "error"; message: string };
+
+// Pi exposes its resolved built-in bindings here, but not shortcuts owned by
+// other extensions. Pi reports those collisions when it reloads.
+function findConflicts(kb: KeybindingsManager, shortcut: string): Conflict[] {
+  const resolved = kb.getResolvedBindings();
+  const result: Conflict[] = [];
+  for (const [id, keys] of Object.entries(resolved)) {
+    if (keys === undefined) continue;
+    const keyList: string[] = Array.isArray(keys) ? keys : [keys];
+    if (keyList.includes(shortcut)) {
+      const def = kb.getDefinition(id as never);
+      if (def?.description) result.push({ description: def.description });
+    }
+  }
+  return result;
+}
+
+export function createShortcutPicker(
+  tui: TUI,
+  theme: UiTheme,
+  keybindings: KeybindingsManager,
+  current: string,
+  done: (shortcut: string | undefined) => void,
+): Component {
+  const keys = new VoiceKeys(keybindings);
+  let phase: Phase = { kind: "waiting" };
+  const container = new Container();
+
+  function rebuild(): void {
+    container.clear();
+    container.addChild(panelBorder(theme));
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(theme.fg("accent", theme.bold("Record keyboard shortcut")), 1, 0),
+    );
+    container.addChild(
+      new Text(theme.fg("muted", `Current: ${displayShortcut(current)}`), 1, 0),
+    );
+    container.addChild(new Spacer(1));
+
+    if (phase.kind === "preview") {
+      container.addChild(
+        new Text(theme.fg("accent", displayShortcut(phase.normalized)), 1, 0),
+      );
+      if (phase.conflicts.length > 0) {
+        container.addChild(
+          new Text(
+            theme.fg(
+              "warning",
+              `Built-in conflict: ${phase.conflicts.map((conflict) => conflict.description).join(", ")}. Pi may override or reject this shortcut.`,
+            ),
+            1,
+            0,
+          ),
+        );
+      }
+      container.addChild(new Spacer(1));
+      container.addChild(
+        new Text(
+          `${keys.hint("tui.select.confirm", "keep")}  ${keys.hint("voice.shortcut.useDefault", "default")}  ${theme.fg("dim", "press another shortcut to replace")}  ${keys.hint("tui.select.cancel", "back")}`,
+          1,
+          0,
+        ),
+      );
+    } else {
+      if (phase.kind === "error") {
+        container.addChild(new Text(theme.fg("error", phase.message), 1, 0));
+        container.addChild(new Spacer(1));
+      }
+      container.addChild(
+        new Text(theme.fg("muted", "Press a key combination…"), 1, 0),
+      );
+      container.addChild(new Spacer(1));
+      container.addChild(
+        new Text(
+          `${keys.hint("voice.shortcut.useDefault", `default (${displayShortcut(DEFAULT_SHORTCUT)})`)}  ${keys.hint("tui.select.cancel", "back")}`,
+          1,
+          0,
+        ),
+      );
+    }
+
+    container.addChild(new Spacer(1));
+    container.addChild(panelBorder(theme));
+  }
+
+  rebuild();
+
+  return {
+    wantsKeyRelease: false,
+
+    render(width: number): string[] {
+      return container.render(width).map((line) => truncateToWidth(line, width, ""));
+    },
+
+    handleInput(data: string): void {
+      if (keys.matches(data, "tui.select.cancel")) {
+        done(undefined);
+        return;
+      }
+
+      if (keys.matches(data, "tui.select.confirm")) {
+        if (phase.kind === "preview") done(phase.normalized);
+        return;
+      }
+
+      if (keys.matches(data, "voice.shortcut.useDefault")) {
+        phase = {
+          kind: "preview",
+          normalized: DEFAULT_SHORTCUT,
+          conflicts: findConflicts(keybindings, DEFAULT_SHORTCUT),
+        };
+        rebuild();
+        tui.requestRender();
+        return;
+      }
+
+      const parsed = parseKey(data);
+      if (!parsed) return;
+
+      const normalized = normalizeShortcut(parsed);
+      if (!normalized) {
+        phase = {
+          kind: "error",
+          message: `${displayShortcut(parsed)} is not valid. Use a modifier such as Ctrl or Alt, or a function key.`,
+        };
+      } else {
+        phase = {
+          kind: "preview",
+          normalized,
+          conflicts: findConflicts(keybindings, normalized),
+        };
+      }
+      rebuild();
+      tui.requestRender();
+    },
+
+    invalidate(): void {
+      rebuild();
+    },
+  };
+}

package/src/startup-shortcut.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { DEFAULT_SHORTCUT, normalizeShortcut } from "./shortcut-core.js";
+import { legacySettingsPath, settingsPath } from "./settings-path.js";
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Read only the setting Pi needs while synchronously registering the extension. */
+export function readShortcutForRegistration(): string {
+  for (const path of [settingsPath(), legacySettingsPath()]) {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+      if (!isObject(parsed) || parsed.version !== 1 || typeof parsed.shortcut !== "string") {
+        return DEFAULT_SHORTCUT;
+      }
+      return normalizeShortcut(parsed.shortcut) ?? DEFAULT_SHORTCUT;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      return DEFAULT_SHORTCUT;
+    }
+  }
+  return DEFAULT_SHORTCUT;
+}

package/src/transcript-preview.ts

@@ -0,0 +1,52 @@
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import type { VoiceKeys } from "./keybindings.js";
+
+/** A bounded read-only view. Clipping never changes the underlying transcript. */
+export class TranscriptPreview {
+  private content = "";
+  private text = new Text("", 1, 0);
+  private offset = 0;
+  private lineCount = 1;
+  private pageSize = 1;
+
+  constructor(private readonly keys: VoiceKeys) {}
+
+  setText(content: string): void {
+    if (this.content === content) return;
+    this.content = content;
+    this.text.setText(content);
+    this.offset = 0;
+  }
+
+  invalidate(): void { this.text.invalidate(); }
+
+  render(width: number, height: number, muted: (text: string) => string): string[] {
+    const rows = Math.max(1, height);
+    const lines = this.content ? this.text.render(width) : [" ".repeat(width)];
+    this.lineCount = lines.length;
+    const clipped = lines.length > rows;
+    this.pageSize = Math.max(1, rows - (clipped && rows > 1 ? 1 : 0));
+    this.offset = Math.max(0, Math.min(this.offset, lines.length - this.pageSize));
+    const visible = lines.slice(this.offset, this.offset + this.pageSize);
+    if (clipped && rows > 1) {
+      visible.push(truncateToWidth(
+        muted(` ${this.offset + 1}–${this.offset + visible.length} / ${lines.length} lines · ${this.keys.navLabel()} / ${this.keys.keyText(["tui.select.pageUp", "tui.select.pageDown"])} scroll`), width,
+      ));
+    }
+    return visible;
+  }
+
+  handleInput(data: string): boolean {
+    if (this.lineCount <= this.pageSize) return false;
+    let offset = this.offset;
+    if (this.keys.matches(data, "tui.select.up")) offset--;
+    else if (this.keys.matches(data, "tui.select.down")) offset++;
+    else if (this.keys.matches(data, "tui.select.pageUp")) offset -= this.pageSize;
+    else if (this.keys.matches(data, "tui.select.pageDown")) offset += this.pageSize;
+    else if (this.keys.matches(data, "voice.scroll.top")) offset = 0;
+    else if (this.keys.matches(data, "voice.scroll.bottom")) offset = this.lineCount - this.pageSize;
+    else return false;
+    this.offset = Math.max(0, Math.min(offset, this.lineCount - this.pageSize));
+    return true;
+  }
+}