@arcote.tech/arc-ai-voice 0.7.9

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@arcote.tech/arc-ai-voice",
+  "type": "module",
+  "version": "0.7.9",
+  "private": false,
+  "description": "Voice input + transcription standard for Arc — provider abstraction (Whisper, ...) + React VoiceTextInput/Textarea/ContentEditable components",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@arcote.tech/arc": "^0.7.9",
+    "@arcote.tech/arc-ds": "^0.7.9",
+    "@arcote.tech/platform": "^0.7.9",
+    "react": "^18.0.0 || ^19.0.0",
+    "lucide-react": ">=0.400.0",
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/src/adapters/whisper.ts

@@ -0,0 +1,74 @@
+import type { TranscriptionOptions, TranscriptionProvider } from "../types";
+
+export interface WhisperConfig {
+  /** OpenAI API key. */
+  apiKey: string;
+  /** Model — default `"whisper-1"`. Można też podać nowsze np. `gpt-4o-transcribe`. */
+  model?: string;
+  /** Custom base URL (proxy / Azure OpenAI / self-hosted). Default OpenAI. */
+  baseUrl?: string;
+}
+
+/**
+ * OpenAI Whisper adapter. `whisper-1` jest sprawdzony, ekonomiczny i wspiera
+ * polski + większość innych języków. Endpoint `/v1/audio/transcriptions`
+ * przyjmuje multipart z polem `file` (webm/opus/mp4/wav/mp3).
+ */
+export function whisper(config: WhisperConfig): TranscriptionProvider {
+  const baseUrl = config.baseUrl ?? "https://api.openai.com/v1";
+  const model = config.model ?? "whisper-1";
+
+  return {
+    name: "whisper",
+    async transcribe(audio: Blob, options: TranscriptionOptions = {}) {
+      const formData = new FormData();
+      // Whisper wymaga `file` z rozszerzeniem w nazwie żeby rozpoznać format —
+      // sam Content-Type Bloba nie wystarczy.
+      const ext = mimeToExt(audio.type);
+      formData.append("file", audio, `audio.${ext}`);
+      formData.append("model", model);
+      formData.append("response_format", "text");
+      if (options.language) formData.append("language", options.language);
+
+      const response = await fetch(`${baseUrl}/audio/transcriptions`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${config.apiKey}` },
+        body: formData,
+      });
+
+      if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new Error(
+          `Whisper API ${response.status}: ${detail || response.statusText}`,
+        );
+      }
+
+      // response_format=text → plain string body, nie JSON.
+      return (await response.text()).trim();
+    },
+  };
+}
+
+function mimeToExt(mime: string): string {
+  // Whisper waliduje po rozszerzeniu pliku. `audio/webm;codecs=opus` → "webm".
+  const m = mime.split(";")[0].trim();
+  switch (m) {
+    case "audio/webm":
+      return "webm";
+    case "audio/mp4":
+    case "audio/m4a":
+    case "audio/x-m4a":
+      return "m4a";
+    case "audio/mpeg":
+    case "audio/mp3":
+      return "mp3";
+    case "audio/wav":
+    case "audio/x-wav":
+      return "wav";
+    case "audio/ogg":
+      return "ogg";
+    default:
+      // Bezpieczny fallback — Whisper akceptuje webm szeroko.
+      return "webm";
+  }
+}

package/src/arc.d.ts

@@ -0,0 +1,6 @@
+declare const BROWSER: boolean;
+declare const NOT_ON_BROWSER: boolean;
+declare const ONLY_BROWSER: boolean;
+declare const SERVER: boolean;
+declare const NOT_ON_SERVER: boolean;
+declare const ONLY_SERVER: boolean;

package/src/index.ts

@@ -0,0 +1,31 @@
+// Provider abstrakcja + adaptery
+export type { TranscriptionOptions, TranscriptionProvider } from "./types";
+export { whisper, type WhisperConfig } from "./adapters/whisper";
+
+// Server-side: builder modułu + route
+export { voice, type VoiceConfig } from "./voice-builder";
+export {
+  createTranscribeRoute,
+  type TranscribeRouteConfig,
+} from "./routes/transcribe-route";
+
+// React: hook + komponenty UI
+export {
+  useVoiceRecorder,
+  type UseVoiceRecorderOptions,
+  type UseVoiceRecorderResult,
+  type VoiceRecorderState,
+} from "./react/use-voice-recorder";
+export { VoiceButton, type VoiceButtonProps } from "./react/voice-button";
+export {
+  VoiceTextInput,
+  type VoiceTextInputProps,
+} from "./react/voice-text-input";
+export {
+  VoiceTextarea,
+  type VoiceTextareaProps,
+} from "./react/voice-textarea";
+export {
+  VoiceContentEditable,
+  type VoiceContentEditableProps,
+} from "./react/voice-content-editable";

package/src/react/use-voice-recorder.ts

@@ -0,0 +1,255 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Niskopoziomowa klasa do nagrywania audio. Trzymana jako moduł
+ * (nie hook) bo MediaRecorder ma własny lifecycle ortogonalny do React.
+ * Inspirowana legacy/packages/platform/src/utils/voice-recorder.ts (NDT,
+ * sprawdzona produkcyjnie).
+ */
+class Recorder {
+  private mediaRecorder: MediaRecorder | null = null;
+  private stream: MediaStream | null = null;
+  private chunks: Blob[] = [];
+
+  async start(): Promise<void> {
+    this.stream = await navigator.mediaDevices.getUserMedia({
+      audio: { echoCancellation: true, noiseSuppression: true, sampleRate: 44100 },
+    });
+    // Fallback chain: webm/opus → mp4 → default. Whisper akceptuje wszystkie.
+    let mimeType: string | undefined = "audio/webm;codecs=opus";
+    if (!MediaRecorder.isTypeSupported(mimeType)) mimeType = "audio/mp4";
+    if (!MediaRecorder.isTypeSupported(mimeType)) mimeType = undefined;
+
+    this.mediaRecorder = new MediaRecorder(
+      this.stream,
+      mimeType ? { mimeType } : undefined,
+    );
+    this.chunks = [];
+    this.mediaRecorder.ondataavailable = (e) => {
+      if (e.data.size > 0) this.chunks.push(e.data);
+    };
+    // start(100) — zbieraj data co 100ms, lepszy responsiveness na cancel.
+    this.mediaRecorder.start(100);
+  }
+
+  stop(): Promise<Blob> {
+    return new Promise((resolve, reject) => {
+      const mr = this.mediaRecorder;
+      if (!mr) return reject(new Error("not recording"));
+      mr.onstop = () => {
+        const mime = mr.mimeType || "audio/webm";
+        const blob = new Blob(this.chunks, { type: mime });
+        this.cleanup();
+        resolve(blob);
+      };
+      mr.onerror = () => reject(new Error("recording error"));
+      mr.stop();
+    });
+  }
+
+  cancel(): void {
+    if (this.mediaRecorder?.state === "recording") {
+      try { this.mediaRecorder.stop(); } catch {}
+    }
+    this.cleanup();
+  }
+
+  private cleanup(): void {
+    if (this.stream) {
+      this.stream.getTracks().forEach((t) => t.stop());
+      this.stream = null;
+    }
+    this.mediaRecorder = null;
+    this.chunks = [];
+  }
+
+  static isSupported(): boolean {
+    return (
+      typeof navigator !== "undefined" &&
+      typeof navigator.mediaDevices?.getUserMedia === "function" &&
+      typeof MediaRecorder !== "undefined"
+    );
+  }
+}
+
+export type VoiceRecorderState =
+  | "idle"
+  | "recording"
+  | "processing"
+  | "error";
+
+export interface UseVoiceRecorderOptions {
+  /** Endpoint do POST audio. Default `/route/voice/transcribe` (zgodne z arc-host prefix `/route` + voice path). */
+  apiUrl?: string;
+  /** Język ISO 639-1 (np. "pl"). Przekazany jako form field. */
+  language?: string;
+  /** Max długość nagrania (ms) — auto-stop po przekroczeniu. Default 60_000. */
+  maxDurationMs?: number;
+  /** Wywoływany gdy transkrypcja gotowa. */
+  onTranscript: (text: string) => void;
+  /** Wywoływany przy każdym błędzie (permission, network, API). */
+  onError?: (err: Error) => void;
+}
+
+export interface UseVoiceRecorderResult {
+  state: VoiceRecorderState;
+  /** Czas nagrywania w ms — rośnie podczas `state === "recording"`. */
+  elapsedMs: number;
+  /** Ostatni błąd (kasowany przy następnym start()). */
+  error: Error | null;
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+  cancel: () => void;
+  /** Sprawdza dostępność MediaRecorder + getUserMedia. */
+  isSupported: boolean;
+}
+
+const DEFAULT_API_URL = "/route/voice/transcribe";
+const DEFAULT_MAX_MS = 60_000;
+// Refresh elapsed time — 100ms wystarczy do gładkiej animacji koła postępu
+// bez przeciążania React renderem.
+const TICK_INTERVAL_MS = 100;
+
+export function useVoiceRecorder(
+  options: UseVoiceRecorderOptions,
+): UseVoiceRecorderResult {
+  const {
+    apiUrl = DEFAULT_API_URL,
+    language,
+    maxDurationMs = DEFAULT_MAX_MS,
+    onTranscript,
+    onError,
+  } = options;
+
+  const [state, setState] = useState<VoiceRecorderState>("idle");
+  const [elapsedMs, setElapsedMs] = useState(0);
+  const [error, setError] = useState<Error | null>(null);
+
+  const recorderRef = useRef<Recorder | null>(null);
+  const startTimeRef = useRef<number>(0);
+  const tickRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const autoStopRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Callbacks w refach żeby start/stop nie potrzebowały ich w deps i nie
+  // re-tworzyły się przy każdym renderze konsumenta.
+  const onTranscriptRef = useRef(onTranscript);
+  const onErrorRef = useRef(onError);
+  onTranscriptRef.current = onTranscript;
+  onErrorRef.current = onError;
+
+  const clearTimers = useCallback(() => {
+    if (tickRef.current !== null) {
+      clearInterval(tickRef.current);
+      tickRef.current = null;
+    }
+    if (autoStopRef.current !== null) {
+      clearTimeout(autoStopRef.current);
+      autoStopRef.current = null;
+    }
+  }, []);
+
+  const handleError = useCallback(
+    (e: unknown) => {
+      const err = e instanceof Error ? e : new Error(String(e));
+      setError(err);
+      setState("error");
+      onErrorRef.current?.(err);
+    },
+    [],
+  );
+
+  const transcribe = useCallback(
+    async (audio: Blob) => {
+      setState("processing");
+      try {
+        const form = new FormData();
+        form.append("audio", audio);
+        if (language) form.append("language", language);
+        const res = await fetch(apiUrl, { method: "POST", body: form });
+        if (!res.ok) {
+          throw new Error(`transcribe failed: ${res.status} ${await res.text().catch(() => "")}`);
+        }
+        const text = await res.text();
+        setState("idle");
+        setElapsedMs(0);
+        onTranscriptRef.current(text.trim());
+      } catch (e) {
+        handleError(e);
+      }
+    },
+    [apiUrl, language, handleError],
+  );
+
+  const stop = useCallback(async () => {
+    clearTimers();
+    const rec = recorderRef.current;
+    if (!rec) return;
+    recorderRef.current = null;
+    try {
+      const blob = await rec.stop();
+      if (blob.size === 0) {
+        setState("idle");
+        setElapsedMs(0);
+        return;
+      }
+      await transcribe(blob);
+    } catch (e) {
+      handleError(e);
+    }
+  }, [clearTimers, transcribe, handleError]);
+
+  const start = useCallback(async () => {
+    if (state === "recording" || state === "processing") return;
+    setError(null);
+    setElapsedMs(0);
+    if (!Recorder.isSupported()) {
+      handleError(new Error("Voice recording not supported in this browser"));
+      return;
+    }
+    const rec = new Recorder();
+    try {
+      await rec.start();
+    } catch (e) {
+      handleError(e);
+      return;
+    }
+    recorderRef.current = rec;
+    startTimeRef.current = Date.now();
+    setState("recording");
+    tickRef.current = setInterval(() => {
+      setElapsedMs(Date.now() - startTimeRef.current);
+    }, TICK_INTERVAL_MS);
+    autoStopRef.current = setTimeout(() => {
+      // Po przekroczeniu max time — auto-stop + transkrypcja.
+      void stop();
+    }, maxDurationMs);
+  }, [state, maxDurationMs, stop, handleError]);
+
+  const cancel = useCallback(() => {
+    clearTimers();
+    const rec = recorderRef.current;
+    recorderRef.current = null;
+    rec?.cancel();
+    setState("idle");
+    setElapsedMs(0);
+    setError(null);
+  }, [clearTimers]);
+
+  // Cleanup gdy komponent zniknie podczas nagrywania (np. user nawiguje).
+  useEffect(() => {
+    return () => {
+      clearTimers();
+      recorderRef.current?.cancel();
+      recorderRef.current = null;
+    };
+  }, [clearTimers]);
+
+  return {
+    state,
+    elapsedMs,
+    error,
+    start,
+    stop,
+    cancel,
+    isSupported: Recorder.isSupported(),
+  };
+}

package/src/react/voice-button.tsx

@@ -0,0 +1,154 @@
+import { Mic, MicOff, Loader2, Square } from "lucide-react";
+import type { VoiceRecorderState } from "./use-voice-recorder";
+
+export interface VoiceButtonProps {
+  state: VoiceRecorderState;
+  /** Czas nagrywania w ms — driver progress koła i MM:SS. */
+  elapsedMs: number;
+  /** Maksimum (ms) — odniesienie dla wypełnienia koła (0% → 100%). */
+  maxDurationMs: number;
+  /** Klik podczas idle = start, podczas recording = stop. */
+  onClick: () => void;
+  /** Klik cancel — pokazywany jako osobny przycisk obok podczas recording. */
+  onCancel?: () => void;
+  /** Komunikat błędu — tooltip nad ikoną MicOff. */
+  error?: Error | null;
+  className?: string;
+}
+
+// Constanty rysowania koła. Promień taki żeby SVG mieścił się w 32×32 z
+// 2px stroke + 2px padding na pulsującą obwódkę.
+const SIZE = 32;
+const STROKE = 2.5;
+const RADIUS = (SIZE - STROKE) / 2;
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
+
+function formatMmSs(ms: number): string {
+  const total = Math.max(0, Math.floor(ms / 1000));
+  const m = Math.floor(total / 60);
+  const s = total % 60;
+  return `${m}:${String(s).padStart(2, "0")}`;
+}
+
+export function VoiceButton({
+  state,
+  elapsedMs,
+  maxDurationMs,
+  onClick,
+  onCancel,
+  error,
+  className,
+}: VoiceButtonProps) {
+  const recording = state === "recording";
+  const processing = state === "processing";
+  const errored = state === "error";
+
+  if (recording) {
+    const progress = Math.min(1, elapsedMs / maxDurationMs);
+    const dashOffset = CIRCUMFERENCE * (1 - progress);
+    return (
+      <div className={`flex items-center gap-1 ${className ?? ""}`}>
+        {onCancel && (
+          <button
+            type="button"
+            onClick={onCancel}
+            aria-label="Anuluj nagrywanie"
+            title="Anuluj"
+            className="flex h-7 w-7 items-center justify-center rounded-full text-muted-foreground/70 transition-colors hover:bg-muted hover:text-foreground"
+          >
+            <span className="text-xs">✕</span>
+          </button>
+        )}
+        <button
+          type="button"
+          onClick={onClick}
+          aria-label="Zakończ nagrywanie"
+          className="relative inline-flex items-center justify-center"
+          style={{ width: SIZE, height: SIZE }}
+        >
+          <svg
+            width={SIZE}
+            height={SIZE}
+            className="absolute inset-0 -rotate-90"
+            aria-hidden
+          >
+            {/* Tło — pełne koło, niska opacity */}
+            <circle
+              cx={SIZE / 2}
+              cy={SIZE / 2}
+              r={RADIUS}
+              fill="none"
+              stroke="currentColor"
+              strokeWidth={STROKE}
+              className="text-muted-foreground/20"
+            />
+            {/* Progress — wypełnia się w miarę elapsedMs */}
+            <circle
+              cx={SIZE / 2}
+              cy={SIZE / 2}
+              r={RADIUS}
+              fill="none"
+              stroke="currentColor"
+              strokeWidth={STROKE}
+              strokeLinecap="round"
+              strokeDasharray={CIRCUMFERENCE}
+              strokeDashoffset={dashOffset}
+              className="text-primary transition-[stroke-dashoffset] duration-100 ease-linear"
+            />
+          </svg>
+          {/* Pulsująca obwódka — sygnał że nagrywanie aktywne */}
+          <span
+            className="absolute inset-0 rounded-full bg-primary/20 animate-ping"
+            style={{ animationDuration: "1.5s" }}
+            aria-hidden
+          />
+          {/* Środek — kwadracik stop + timer pod spodem */}
+          <Square className="relative h-3 w-3 fill-primary text-primary" />
+        </button>
+        <span className="text-xs font-medium tabular-nums text-muted-foreground min-w-[2.5rem]">
+          {formatMmSs(elapsedMs)}
+        </span>
+      </div>
+    );
+  }
+
+  if (processing) {
+    return (
+      <button
+        type="button"
+        disabled
+        aria-label="Transkrybuję…"
+        className={`inline-flex h-7 w-7 items-center justify-center rounded-full text-primary ${className ?? ""}`}
+      >
+        <Loader2 className="h-4 w-4 animate-spin" />
+      </button>
+    );
+  }
+
+  if (errored) {
+    return (
+      <button
+        type="button"
+        onClick={onClick}
+        aria-label="Spróbuj ponownie nagrać"
+        title={error?.message ?? "Błąd nagrywania"}
+        className={`inline-flex h-7 w-7 items-center justify-center rounded-full text-destructive transition-colors hover:bg-destructive/10 ${className ?? ""}`}
+      >
+        <MicOff className="h-4 w-4" />
+      </button>
+    );
+  }
+
+  // idle
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label="Nagraj głosowo"
+      title="Nagraj głosowo"
+      className={`inline-flex h-7 w-7 items-center justify-center rounded-full text-muted-foreground/70 transition-colors hover:bg-muted hover:text-foreground ${className ?? ""}`}
+    >
+      <Mic className="h-4 w-4" />
+    </button>
+  );
+}

package/src/react/voice-content-editable.tsx

@@ -0,0 +1,130 @@
+import { useEffect, useRef } from "react";
+import { useI18n } from "@arcote.tech/platform";
+import { useVoiceRecorder } from "./use-voice-recorder";
+import { VoiceButton } from "./voice-button";
+
+export interface VoiceContentEditableProps {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string;
+  className?: string;
+  /** ISO 639-1 (np. "pl"). Default — z `useI18n().locale`. */
+  language?: string;
+  /** Max długość nagrania w ms. Default 60_000. */
+  maxDurationMs?: number;
+  /** Override endpointu transkrypcji. Default `/route/voice/transcribe`. */
+  transcribeUrl?: string;
+}
+
+const DEFAULT_MAX_MS = 60_000;
+
+/**
+ * Auto-grow contentEditable — bez wewnętrznego scrolla, height rośnie z
+ * treścią. Sensowny dla pól typu "opisz dłuższą myśl" gdzie chcemy widzieć
+ * całość bez maxHeight. Voice button w prawym górnym rogu (absolute), tekst
+ * z padding-right żeby nie wchodził pod ikonkę.
+ *
+ * Implementacja podobna do `TextareaField` (`/ds/form/fields/textarea-field.tsx`),
+ * ale bez `maxHeight` / scrolla — div sam rośnie.
+ */
+export function VoiceContentEditable({
+  value,
+  onChange,
+  placeholder,
+  className,
+  language,
+  maxDurationMs = DEFAULT_MAX_MS,
+  transcribeUrl,
+}: VoiceContentEditableProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const composingRef = useRef(false);
+  const locale = useLocaleLanguage();
+
+  const { state, elapsedMs, error, start, stop, cancel } = useVoiceRecorder({
+    apiUrl: transcribeUrl,
+    language: language ?? locale,
+    maxDurationMs,
+    onTranscript: (text) => {
+      const trimmed = text.trim();
+      if (!trimmed) return;
+      onChange(value ? `${value.trimEnd()} ${trimmed}` : trimmed);
+    },
+  });
+
+  // Sync zewnętrznego value → DOM. Zapisujemy w innerText (plaintext)
+  // żeby uniknąć HTML escapingu i niespójności caret.
+  useEffect(() => {
+    if (!ref.current) return;
+    if (ref.current.innerText !== (value ?? "")) {
+      ref.current.innerText = value ?? "";
+    }
+  }, [value]);
+
+  const handleInput = () => {
+    if (composingRef.current) return;
+    onChange(ref.current?.innerText ?? "");
+  };
+
+  // Paste jako plaintext — bez stylów z innej apki.
+  const handlePaste = (e: React.ClipboardEvent) => {
+    e.preventDefault();
+    const text = e.clipboardData.getData("text/plain");
+    document.execCommand("insertText", false, text);
+  };
+
+  const recording = state === "recording";
+  const isEmpty = !value;
+
+  return (
+    <div className={`relative ${className ?? ""}`}>
+      <div
+        ref={ref}
+        contentEditable
+        onInput={handleInput}
+        onPaste={handlePaste}
+        onCompositionStart={() => (composingRef.current = true)}
+        onCompositionEnd={() => {
+          composingRef.current = false;
+          handleInput();
+        }}
+        suppressContentEditableWarning
+        className={
+          // `whitespace-pre-wrap` + `break-words` (overflow-wrap: break-word)
+          // łamie długie słowa gdy nie mieszczą się w linii. Arbitrary
+          // `[overflow-wrap:anywhere]` jest bardziej agresywne i łapie
+          // edge case'y typu długie URL-e / sklejone wyrazy bez spacji.
+          "min-h-[6rem] w-full rounded-md border border-input bg-background px-3 py-2 text-sm whitespace-pre-wrap break-words [overflow-wrap:anywhere] focus:outline-none focus:ring-2 focus:ring-ring " +
+          (recording ? "pr-28" : "pr-10")
+        }
+        data-placeholder={placeholder}
+      />
+      {isEmpty && placeholder && (
+        <span
+          aria-hidden
+          className="pointer-events-none absolute left-3 top-2 text-sm text-muted-foreground"
+        >
+          {placeholder}
+        </span>
+      )}
+      <div className="absolute top-1.5 right-1.5">
+        <VoiceButton
+          state={state}
+          elapsedMs={elapsedMs}
+          maxDurationMs={maxDurationMs}
+          error={error}
+          onClick={recording ? stop : start}
+          onCancel={recording ? cancel : undefined}
+        />
+      </div>
+    </div>
+  );
+}
+
+function useLocaleLanguage(): string | undefined {
+  try {
+    const { locale } = useI18n();
+    return locale ? locale.split("-")[0] : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/react/voice-text-input.tsx

@@ -0,0 +1,87 @@
+import { Input } from "@arcote.tech/arc-ds";
+import { useI18n } from "@arcote.tech/platform";
+import type { ComponentType } from "react";
+import { useVoiceRecorder } from "./use-voice-recorder";
+import { VoiceButton } from "./voice-button";
+
+export interface VoiceTextInputProps {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string;
+  icon?: ComponentType<{ className?: string }>;
+  size?: "default" | "sm" | "xs" | "lg";
+  className?: string;
+  /** ISO 639-1 (np. "pl"). Default — z `useI18n().locale` (np. `pl-PL` → `pl`). */
+  language?: string;
+  /** Max długość nagrania w ms. Default 60_000. */
+  maxDurationMs?: number;
+  /** Override endpointu transkrypcji. Default `/route/voice/transcribe`. */
+  transcribeUrl?: string;
+}
+
+const DEFAULT_MAX_MS = 60_000;
+
+/**
+ * Jednoliniowy `Input` z przyciskiem nagrywania głosu w prawej części
+ * (vertically centered). Transkrypt jest **dopisywany** do bieżącego
+ * `value` (ze spacją gdy value nie pusty) — pozwala dyktować w kawałkach.
+ */
+export function VoiceTextInput({
+  value,
+  onChange,
+  placeholder,
+  icon,
+  size = "default",
+  className,
+  language,
+  maxDurationMs = DEFAULT_MAX_MS,
+  transcribeUrl,
+}: VoiceTextInputProps) {
+  const locale = useLocaleLanguage();
+  const { state, elapsedMs, error, start, stop, cancel } = useVoiceRecorder({
+    apiUrl: transcribeUrl,
+    language: language ?? locale,
+    maxDurationMs,
+    onTranscript: (text) => {
+      const trimmed = text.trim();
+      if (!trimmed) return;
+      onChange(value ? `${value.trimEnd()} ${trimmed}` : trimmed);
+    },
+  });
+
+  const recording = state === "recording";
+
+  return (
+    <div className={`relative ${className ?? ""}`}>
+      <Input
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder}
+        icon={icon}
+        size={size}
+        // Padding-right zostawiamy miejsce na przycisk + ewentualny timer.
+        className={recording ? "pr-24" : "pr-10"}
+      />
+      <div className="absolute right-2 top-1/2 -translate-y-1/2">
+        <VoiceButton
+          state={state}
+          elapsedMs={elapsedMs}
+          maxDurationMs={maxDurationMs}
+          error={error}
+          onClick={recording ? stop : start}
+          onCancel={recording ? cancel : undefined}
+        />
+      </div>
+    </div>
+  );
+}
+
+// `pl-PL` → `pl`. Whisper akceptuje BCP-47 ale ISO 639-1 jest bezpieczniejsze.
+function useLocaleLanguage(): string | undefined {
+  try {
+    const { locale } = useI18n();
+    return locale ? locale.split("-")[0] : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/react/voice-textarea.tsx

@@ -0,0 +1,98 @@
+import { TextareaField } from "@arcote.tech/arc-ds";
+import { useI18n } from "@arcote.tech/platform";
+import type { ReactNode } from "react";
+import { useVoiceRecorder } from "./use-voice-recorder";
+import { VoiceButton } from "./voice-button";
+
+export interface VoiceTextareaProps {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string;
+  label?: ReactNode;
+  rows?: number;
+  maxHeight?: number;
+  className?: string;
+  /** ISO 639-1 (np. "pl"). Default — z `useI18n().locale`. */
+  language?: string;
+  /** Max długość nagrania w ms. Default 60_000. */
+  maxDurationMs?: number;
+  /** Override endpointu transkrypcji. Default `/route/voice/transcribe`. */
+  transcribeUrl?: string;
+}
+
+const DEFAULT_MAX_MS = 60_000;
+
+/**
+ * Wieloliniowy edytor `TextareaField` z przyciskiem nagrywania w prawym
+ * GÓRNYM rogu. Transkrypt jest **dopisywany** do bieżącego `value`.
+ * Dla użycia w chacie zostaw `rows=1` — TextareaField auto-rośnie z treścią.
+ */
+export function VoiceTextarea({
+  value,
+  onChange,
+  placeholder,
+  label,
+  rows = 4,
+  maxHeight,
+  className,
+  language,
+  maxDurationMs = DEFAULT_MAX_MS,
+  transcribeUrl,
+}: VoiceTextareaProps) {
+  const locale = useLocaleLanguage();
+  const { state, elapsedMs, error, start, stop, cancel } = useVoiceRecorder({
+    apiUrl: transcribeUrl,
+    language: language ?? locale,
+    maxDurationMs,
+    onTranscript: (text) => {
+      const trimmed = text.trim();
+      if (!trimmed) return;
+      onChange(value ? `${value.trimEnd()} ${trimmed}` : trimmed);
+    },
+  });
+
+  const recording = state === "recording";
+
+  // Pojedyncza linia (np. chat-input rows=1) — button vertically centered.
+  // Wieloliniowo — button kotwiczony w prawym górnym, przy pierwszej linii.
+  const isSingleLine = (rows ?? 1) <= 1;
+  const buttonPosition = isSingleLine
+    ? "top-1/2 -translate-y-1/2 right-1.5"
+    : "top-1.5 right-1.5";
+
+  return (
+    <div className={`relative ${className ?? ""}`}>
+      <TextareaField
+        value={value}
+        onChange={(val) => onChange(val ?? "")}
+        placeholder={placeholder}
+        label={label}
+        rows={rows}
+        maxHeight={maxHeight}
+        // Padding-right na samym contentEditable żeby tekst nie wchodził
+        // pod absolute-positioned VoiceButton. Recording wyświetla mic +
+        // MM:SS timer (szerszy widget) — większy padding.
+        inputClassName={recording ? "pr-28" : "pr-10"}
+      />
+      <div className={`absolute ${buttonPosition}`}>
+        <VoiceButton
+          state={state}
+          elapsedMs={elapsedMs}
+          maxDurationMs={maxDurationMs}
+          error={error}
+          onClick={recording ? stop : start}
+          onCancel={recording ? cancel : undefined}
+        />
+      </div>
+    </div>
+  );
+}
+
+function useLocaleLanguage(): string | undefined {
+  try {
+    const { locale } = useI18n();
+    return locale ? locale.split("-")[0] : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/routes/transcribe-route.ts

@@ -0,0 +1,94 @@
+/// <reference path="../arc.d.ts" />
+import { route, type ArcTokenAny } from "@arcote.tech/arc";
+import type { TranscriptionProvider } from "../types";
+
+export interface TranscribeRouteConfig {
+  provider: TranscriptionProvider;
+  /** Domyślny język gdy klient nie przekaże `language` w form-data. */
+  defaultLanguage?: string;
+  /**
+   * Opcjonalny gating endpointu. Konsumer przekazuje swój token (np.
+   * `userToken` z arc-auth) i funkcję check (zwracającą `true` lub
+   * `{ ...whereClause }`). Bez tego endpoint jest `.public()` — koszty
+   * API są wtedy eksponowane na każdego, więc rekomendacja: zawsze
+   * przekazać token.
+   */
+  protectBy?: {
+    token: ArcTokenAny;
+    check?: (params: any) => boolean | object;
+  };
+}
+
+const MAX_AUDIO_BYTES = 25 * 1024 * 1024; // Whisper limit = 25MB
+
+/**
+ * POST /route/voice/transcribe
+ *
+ * Multipart body:
+ *  - `audio` (Blob, required) — webm/opus, mp4, wav, mp3, m4a, ogg
+ *  - `language` (string, optional) — ISO 639-1 (np. "pl"), nadpisuje default
+ *
+ * Response: plain text z transkrypcją (200) albo `{ error }` JSON (4xx/5xx).
+ */
+export function createTranscribeRoute(config: TranscribeRouteConfig) {
+  const base = route("voiceTranscribe").path("/voice/transcribe");
+  // `.public()` i `.protectBy()` zwracają niezgodne typy (isPublic: true vs
+  // protections w typie), więc rozdzielamy branche zamiast reassignować let.
+  const gated = config.protectBy
+    ? base.protectBy(
+        config.protectBy.token,
+        (config.protectBy.check ?? (() => true)) as any,
+      )
+    : base.public();
+
+  return gated.handle({
+    POST: async (_ctx, req: Request) => {
+      if (!ONLY_SERVER) {
+        return new Response("server only", { status: 500 });
+      }
+
+      let form: FormData;
+      try {
+        form = await req.formData();
+      } catch (e) {
+        return jsonError(400, "invalid multipart body");
+      }
+
+      const audio = form.get("audio");
+      if (!(audio instanceof Blob)) {
+        return jsonError(400, "missing 'audio' field");
+      }
+      if (audio.size === 0) {
+        return jsonError(400, "empty audio");
+      }
+      if (audio.size > MAX_AUDIO_BYTES) {
+        return jsonError(413, `audio exceeds ${MAX_AUDIO_BYTES} bytes`);
+      }
+
+      const language =
+        (form.get("language") as string | null) ?? config.defaultLanguage;
+
+      try {
+        const text = await config.provider.transcribe(
+          audio,
+          language ? { language } : undefined,
+        );
+        return new Response(text, {
+          status: 200,
+          headers: { "Content-Type": "text/plain; charset=utf-8" },
+        });
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : "transcription failed";
+        console.error("[voice:transcribe]", msg);
+        return jsonError(502, msg);
+      }
+    },
+  });
+}
+
+function jsonError(status: number, error: string): Response {
+  return new Response(JSON.stringify({ error }), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}

package/src/types.ts

@@ -0,0 +1,23 @@
+// Abstrakcja providera transkrypcji audio → tekst. Konkretne adaptery
+// (whisper, google-speech itp.) eksportują fabrykę zwracającą instancję
+// tej struktury. `voice({ provider })` wstrzykuje wybranego providera do
+// route handlera `/voice/transcribe`.
+
+export interface TranscriptionOptions {
+  /**
+   * Język nagrania w formacie ISO 639-1 (np. "pl", "en"). Większość
+   * providerów potrafi auto-detekować, ale podanie języka znacząco
+   * poprawia accuracy dla krótkich nagrań.
+   */
+  language?: string;
+}
+
+export interface TranscriptionProvider {
+  /** Identyfikator providera — używany w logach i diagnozie. */
+  name: string;
+  /**
+   * Transkrybuje audio (webm/opus, mp4, wav, mp3...) na tekst.
+   * Powinien rzucić błąd przy nieprawidłowym formacie / awarii API.
+   */
+  transcribe(audio: Blob, options?: TranscriptionOptions): Promise<string>;
+}

package/src/voice-builder.ts

@@ -0,0 +1,36 @@
+import { contextElement, module } from "@arcote.tech/platform";
+import {
+  createTranscribeRoute,
+  type TranscribeRouteConfig,
+} from "./routes/transcribe-route";
+
+export interface VoiceConfig extends TranscribeRouteConfig {}
+
+/**
+ * Rejestruje moduł `voice` z route `/voice/transcribe`. Konsumer wywołuje raz
+ * w init aplikacji:
+ *
+ * ```ts
+ * voice({
+ *   provider: whisper({ apiKey: process.env.OPENAI_API_KEY! }),
+ *   defaultLanguage: "pl",
+ *   protectBy: { token: userToken },
+ * }).build();
+ * ```
+ *
+ * Maksymalny czas nagrania (`maxDurationMs`) kontroluje hook
+ * `useVoiceRecorder` — `VoiceTextarea`/`VoiceTextInput`/`VoiceContentEditable`
+ * przyjmują go z propsa, więc konsumer ustawia go per-komponent.
+ */
+export function voice(config: VoiceConfig) {
+  const transcribeRoute = createTranscribeRoute(config);
+  return {
+    route: transcribeRoute,
+    /** Rejestruje moduł "voice" z transcribe route jako jednym fragmentem. */
+    build() {
+      return module("voice")
+        .public([contextElement(transcribeRoute)])
+        .build();
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "include": ["src/**/*"]
+}