@joewinke/jatui 0.22.0 → 0.24.0

package/dist/utils/audioRecorderCore.js

@@ -0,0 +1,447 @@
+/**
+ * createAudioRecorderCore — headless audio-capture primitive (jatui-is2ow.8).
+ *
+ * The capture pipeline of `AudioRecorder.svelte` (permission request, MIME
+ * negotiation, MediaRecorder state machine, pause-aware wall-clock timing,
+ * AnalyserNode level meter, blob out) factored into a dependency-injected,
+ * DOM-free core so any host can drive it from its own UI — mic buttons,
+ * push-to-talk keys, overlays — without importing the component.
+ *
+ * NO transcription here by design: hosts that transcribe (the jat IDE's
+ * VoiceMicButton/VoiceInput, wave 3.5 of the adoption audit jat-1alfp) keep
+ * their POST-local capture shape and consume `onStop`'s blob payload.
+ *
+ * Two layers:
+ *   • this plain module — every knob injectable via `deps` (tests drive a fake
+ *     MediaRecorder backend in node:test, no DOM);
+ *   • `audioRecorder.svelte.ts` — the `createAudioRecorder()` rune wrapper
+ *     that wires the core's snapshot into `$state` so Svelte 5 templates react
+ *     to it. Components and app code import the wrapper; tests import this.
+ *
+ * Modes:
+ *   • `'toggle'` (default) — click-style: `start()` begins, `stop()` ends.
+ *   • `'push'` — hold-to-talk: the host wires pointerdown → `start()`,
+ *     pointerup → `stop()`. A `stop()` that arrives while the mic stream is
+ *     still being acquired (a very quick tap) CANCELS — no blob, no error —
+ *     matching the jat IDE VoiceMicButton's pointerup-before-stream behavior.
+ *
+ * Phases: idle → starting → recording ⇄(pause/resume) → processing → done,
+ * with `cancel()` from recording returning straight to idle and `reset()`
+ * returning a finished/errored recorder to idle so the host can go again.
+ *
+ * Timer discipline (lesson from MediaCapture, mos-ow4q4.37): elapsed time is
+ * derived from the wall clock minus accumulated pause, never an incremented
+ * counter — a throttled background tab can't freeze it.
+ */
+const MIME_CANDIDATES = ['audio/webm;codecs=opus', 'audio/webm', 'audio/mp4', 'audio/ogg'];
+/** First supported recording MIME type, or '' when none are. */
+export function pickAudioMimeType(isSupported = (t) => typeof MediaRecorder !== 'undefined' && MediaRecorder.isTypeSupported(t)) {
+    for (const c of MIME_CANDIDATES) {
+        if (isSupported(c))
+            return c;
+    }
+    return '';
+}
+/** RMS of the time-domain data scaled to the recorder's 0–100 meter range. */
+export function computeAudioLevel(timeData) {
+    if (!timeData || timeData.length === 0)
+        return 0;
+    let sum = 0;
+    for (let i = 0; i < timeData.length; i++) {
+        const s = (timeData[i] - 128) / 128;
+        sum += s * s;
+    }
+    return Math.min(100, Math.sqrt(sum / timeData.length) * 300);
+}
+/** Elapsed from the wall clock, pause-adjusted — see module header note. */
+export function computeElapsedMs(startedAt, pausedTotalMs, pauseStartedAt, now) {
+    if (!startedAt)
+        return 0;
+    const pausedMs = pausedTotalMs + (pauseStartedAt ? now - pauseStartedAt : 0);
+    return Math.max(0, now - startedAt - pausedMs);
+}
+export function createAudioRecorderCore(options = {}, deps = {}) {
+    const { mode = 'toggle', maxDurationMs = 0, onStart, onPause, onResume, onStop, onCancel, onError, onFrame } = options;
+    // Lazy globalThis defaults — resolved per factory call, never at import time.
+    const g = (v) => v;
+    const getUserMedia = deps.getUserMedia ??
+        g(typeof navigator !== 'undefined'
+            ? navigator.mediaDevices?.getUserMedia?.bind(navigator.mediaDevices)
+            : undefined);
+    const MediaRecorderCtor = deps.MediaRecorder ?? g(typeof MediaRecorder !== 'undefined' ? MediaRecorder : undefined);
+    const AudioContextCtor = deps.AudioContext ?? g(typeof AudioContext !== 'undefined' ? AudioContext : undefined);
+    const rafFn = deps.requestAnimationFrame ?? g(typeof requestAnimationFrame !== 'undefined' ? requestAnimationFrame : undefined);
+    const rafCancel = deps.cancelAnimationFrame ?? g(typeof cancelAnimationFrame !== 'undefined' ? cancelAnimationFrame : undefined);
+    const setTimeoutFn = deps.setTimeout ?? setTimeout;
+    const clearTimeoutFn = deps.clearTimeout ?? clearTimeout;
+    const setIntervalFn = deps.setInterval ?? setInterval;
+    const clearIntervalFn = deps.clearInterval ?? clearInterval;
+    const now = deps.now ?? (() => Date.now());
+    const isTypeSupported = MediaRecorderCtor && MediaRecorderCtor.isTypeSupported
+        ? (t) => !!MediaRecorderCtor.isTypeSupported(t)
+        : () => false;
+    const supported = !!(getUserMedia && MediaRecorderCtor);
+    // State — plain locals; mutations funnel through notify().
+    let phase = 'idle';
+    let paused = false;
+    let level = 0;
+    let sizeBytes = 0;
+    let error = null;
+    // Recorder internals
+    let recorder = null;
+    let stream = null;
+    let audioCtx = null;
+    let analyser = null;
+    let chunks = [];
+    let mimeType = '';
+    let startedAt = 0;
+    let pausedTotalMs = 0;
+    let pauseStartedAt = 0;
+    let raf = null;
+    let tickTimer = null;
+    let autoStopTimer = null;
+    let wasCancelled = false;
+    /** A stop()/cancel() arrived while the stream was still being acquired. */
+    let pendingCancel = false;
+    const listeners = new Set();
+    function snapshot() {
+        return { phase, paused, level, sizeBytes, elapsedMs: computeElapsedMs(startedAt, pausedTotalMs, pauseStartedAt, now()), error };
+    }
+    function notify() {
+        const s = snapshot();
+        listeners.forEach((fn) => fn(s));
+    }
+    function subscribe(fn) {
+        listeners.add(fn);
+        return () => listeners.delete(fn);
+    }
+    function fail(next) {
+        error = next;
+        notify();
+        onError?.(next);
+    }
+    function elapsed() {
+        return computeElapsedMs(startedAt, pausedTotalMs, pauseStartedAt, now());
+    }
+    function tick() {
+        // elapsedMs is derived, not stored — notify pushes the new value out.
+        notify();
+    }
+    function teardownStream() {
+        stream?.getTracks().forEach((t) => t.stop());
+        stream = null;
+    }
+    function stopFrames() {
+        if (raf !== null && rafCancel) {
+            rafCancel(raf);
+            raf = null;
+        }
+    }
+    function clearTimers() {
+        if (tickTimer) {
+            clearIntervalFn(tickTimer);
+            tickTimer = null;
+        }
+        if (autoStopTimer) {
+            clearTimeoutFn(autoStopTimer);
+            autoStopTimer = null;
+        }
+    }
+    function frameCb() {
+        if (phase !== 'recording' || !analyser) {
+            raf = null;
+            return;
+        }
+        const frequency = new Uint8Array(analyser.frequencyBinCount);
+        const time = new Uint8Array(analyser.frequencyBinCount);
+        analyser.getByteFrequencyData(frequency);
+        analyser.getByteTimeDomainData(time);
+        level = computeAudioLevel(time);
+        notify();
+        onFrame?.({ level, frequency, time });
+        if (rafFn)
+            raf = rafFn(frameCb);
+        else
+            raf = null;
+    }
+    function pumpFrames() {
+        stopFrames();
+        if (rafFn)
+            raf = rafFn(frameCb);
+    }
+    /** Tear down every media resource. Idempotent — safe from cancel/stop/destroy. */
+    function teardown() {
+        wasCancelled = true;
+        if (recorder && recorder.state !== 'inactive') {
+            recorder.ondataavailable = null;
+            recorder.onstop = null;
+            try {
+                recorder.stop();
+            }
+            catch {
+                // already inactive
+            }
+        }
+        recorder = null;
+        teardownStream();
+        if (audioCtx && audioCtx.state !== 'closed') {
+            try {
+                const closing = audioCtx.close();
+                if (closing?.catch)
+                    closing.catch(() => { });
+            }
+            catch {
+                // already closed
+            }
+        }
+        audioCtx = null;
+        analyser = null;
+        stopFrames();
+        clearTimers();
+        chunks = [];
+        sizeBytes = 0;
+        level = 0;
+        startedAt = 0;
+        pausedTotalMs = 0;
+        pauseStartedAt = 0;
+        paused = false;
+    }
+    function mapStartError(err) {
+        const name = err?.name ?? '';
+        if (name === 'NotAllowedError' || name === 'SecurityError') {
+            return {
+                kind: 'denied',
+                message: 'Microphone access was denied. Allow mic permission in your browser settings and try again.'
+            };
+        }
+        if (name === 'NotFoundError' || name === 'OverconstrainedError') {
+            return { kind: 'no-mic', message: 'No microphone was found. Connect one and try again.' };
+        }
+        return { kind: 'start-failed', message: 'Failed to start recording. Check the microphone and try again.' };
+    }
+    async function start() {
+        if (!supported) {
+            fail({
+                kind: 'unsupported',
+                message: 'Audio recording is not supported in this browser.'
+            });
+            return;
+        }
+        if (phase === 'starting' || phase === 'recording' || phase === 'processing')
+            return;
+        error = null;
+        pendingCancel = false;
+        wasCancelled = false;
+        phase = 'starting';
+        notify();
+        try {
+            stream = await getUserMedia({
+                audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true }
+            });
+        }
+        catch (err) {
+            teardownStream();
+            phase = 'idle';
+            notify();
+            fail(mapStartError(err));
+            return;
+        }
+        if (pendingCancel) {
+            // Push-to-talk tap shorter than stream acquisition, or an explicit
+            // cancel mid-start: release the mic, produce nothing (no error).
+            teardownStream();
+            pendingCancel = false;
+            phase = 'idle';
+            notify();
+            onCancel?.();
+            return;
+        }
+        try {
+            mimeType = pickAudioMimeType(isTypeSupported);
+            recorder = mimeType ? new MediaRecorderCtor(stream, { mimeType }) : new MediaRecorderCtor(stream);
+            mimeType = recorder.mimeType || mimeType || 'audio/webm';
+        }
+        catch (err) {
+            teardownStream();
+            phase = 'idle';
+            notify();
+            fail({
+                kind: 'start-failed',
+                message: err instanceof Error ? err.message : 'Failed to start recording. Check the microphone and try again.'
+            });
+            return;
+        }
+        chunks = [];
+        sizeBytes = 0;
+        recorder.ondataavailable = (e) => {
+            if (e.data && e.data.size > 0) {
+                chunks.push(e.data);
+                sizeBytes += e.data.size;
+                notify();
+            }
+        };
+        recorder.onstop = () => {
+            void finalize();
+        };
+        // Waveform analyser — visualization + level only, never touches the
+        // recorded data. Optional: a platform without AudioContext still records.
+        if (AudioContextCtor) {
+            try {
+                audioCtx = new AudioContextCtor();
+                analyser = audioCtx.createAnalyser();
+                analyser.fftSize = 512;
+                analyser.smoothingTimeConstant = 0.3;
+                analyser.minDecibels = -100;
+                analyser.maxDecibels = -20;
+                audioCtx.createMediaStreamSource(stream).connect(analyser);
+            }
+            catch {
+                audioCtx = null;
+                analyser = null;
+            }
+        }
+        recorder.start(1000);
+        startedAt = now();
+        pausedTotalMs = 0;
+        pauseStartedAt = 0;
+        paused = false;
+        phase = 'recording';
+        notify();
+        tickTimer = setIntervalFn(tick, 250);
+        if (maxDurationMs > 0)
+            autoStopTimer = setTimeoutFn(stop, maxDurationMs);
+        pumpFrames();
+        onStart?.();
+    }
+    function pause() {
+        if (phase !== 'recording' || paused || !recorder)
+            return;
+        try {
+            recorder.pause();
+            paused = true;
+            pauseStartedAt = now();
+            stopFrames();
+            notify();
+            onPause?.();
+        }
+        catch {
+            // recorder already inactive — nothing to pause
+        }
+    }
+    function resume() {
+        if (phase !== 'recording' || !paused || !recorder)
+            return;
+        try {
+            recorder.resume();
+            pausedTotalMs += now() - pauseStartedAt;
+            pauseStartedAt = 0;
+            paused = false;
+            pumpFrames();
+            notify();
+            onResume?.();
+        }
+        catch {
+            // recorder already inactive — nothing to resume
+        }
+    }
+    function stop() {
+        if (phase === 'starting') {
+            // Stop arrived before the mic stream resolved (quick push-to-talk
+            // tap) — cancel at start completion rather than emit a stub clip.
+            pendingCancel = true;
+            return;
+        }
+        if (phase !== 'recording' || !recorder)
+            return;
+        if (pauseStartedAt) {
+            pausedTotalMs += now() - pauseStartedAt;
+            pauseStartedAt = 0;
+        }
+        clearTimers();
+        stopFrames();
+        if (recorder.state !== 'inactive') {
+            phase = 'processing';
+            notify();
+            recorder.stop();
+        }
+    }
+    function cancel() {
+        if (phase === 'starting') {
+            pendingCancel = true;
+            return;
+        }
+        if (phase !== 'recording')
+            return;
+        teardown();
+        phase = 'idle';
+        notify();
+        onCancel?.();
+    }
+    async function finalize() {
+        if (wasCancelled)
+            return;
+        if (chunks.length === 0) {
+            // Zero chunks (e.g. stopped before any data arrived) — fail loud, not a silent no-op.
+            phase = 'idle';
+            notify();
+            fail({ kind: 'too-short', message: 'Recording was too short — nothing was captured. Try again.' });
+            return;
+        }
+        phase = 'processing';
+        notify();
+        const blob = new Blob(chunks, { type: mimeType });
+        const result = {
+            blob,
+            mimeType,
+            durationSeconds: Math.max(1, Math.round(elapsed() / 1000)),
+            sizeBytes: blob.size
+        };
+        teardown();
+        // Stay in 'processing' while the host's handler settles (documented in
+        // AudioRecorderOptions.onStop) — the host may be uploading/transcribing
+        // and must not have the user re-trigger a recording mid-flight.
+        if (onStop) {
+            try {
+                await onStop(result);
+            }
+            catch (err) {
+                fail({
+                    kind: 'handler-failed',
+                    message: `Recording kept, but the handler failed: ${err instanceof Error ? err.message : String(err)}`
+                });
+            }
+        }
+        phase = 'done';
+        notify();
+    }
+    function reset() {
+        teardown();
+        pendingCancel = false;
+        phase = 'idle';
+        error = null;
+        notify();
+    }
+    function destroy() {
+        teardown();
+        pendingCancel = false;
+        phase = 'idle';
+        error = null;
+        listeners.clear();
+        notify();
+    }
+    return {
+        get supported() {
+            return supported;
+        },
+        mode,
+        snapshot,
+        subscribe,
+        start,
+        stop,
+        pause,
+        resume,
+        cancel,
+        reset,
+        destroy
+    };
+}

package/dist/utils/clipboard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Clipboard write that works outside secure contexts.
+ *
+ * `navigator.clipboard` only exists on HTTPS or localhost origins. Apps using
+ * this library are routinely viewed over plain HTTP from another machine
+ * (Tailscale/LAN), where the API is undefined and a bare
+ * `navigator.clipboard.writeText()` throws synchronously — the classic
+ * "copy button silently does nothing" bug.
+ *
+ * Falls back to the legacy hidden-textarea + `document.execCommand('copy')`
+ * path, which still works in every browser the library targets.
+ *
+ * @returns true if the text was (as far as detectable) copied
+ */
+export declare function copyText(text: string): Promise<boolean>;
+/**
+ * Clipboard read for menu-triggered paste actions (e.g. a context menu "Paste"
+ * item), where there's no native ClipboardEvent to pull text/plain from.
+ *
+ * Requires navigator.clipboard.readText, which needs a secure context and a
+ * user-gesture-driven call (satisfied by a click handler). Returns null on
+ * any failure — missing API, denied permission, non-secure origin — so
+ * callers can fall back to telling the user to press Ctrl+V instead.
+ */
+export declare function readClipboardText(): Promise<string | null>;

package/dist/utils/clipboard.js

@@ -0,0 +1,59 @@
+/**
+ * Clipboard write that works outside secure contexts.
+ *
+ * `navigator.clipboard` only exists on HTTPS or localhost origins. Apps using
+ * this library are routinely viewed over plain HTTP from another machine
+ * (Tailscale/LAN), where the API is undefined and a bare
+ * `navigator.clipboard.writeText()` throws synchronously — the classic
+ * "copy button silently does nothing" bug.
+ *
+ * Falls back to the legacy hidden-textarea + `document.execCommand('copy')`
+ * path, which still works in every browser the library targets.
+ *
+ * @returns true if the text was (as far as detectable) copied
+ */
+export async function copyText(text) {
+    if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+        try {
+            await navigator.clipboard.writeText(text);
+            return true;
+        }
+        catch {
+            // Permission denied or transient failure — try the legacy path
+        }
+    }
+    try {
+        const ta = document.createElement('textarea');
+        ta.value = text;
+        ta.setAttribute('readonly', '');
+        ta.style.position = 'fixed';
+        ta.style.left = '-9999px';
+        document.body.appendChild(ta);
+        ta.select();
+        const ok = document.execCommand('copy');
+        document.body.removeChild(ta);
+        return ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Clipboard read for menu-triggered paste actions (e.g. a context menu "Paste"
+ * item), where there's no native ClipboardEvent to pull text/plain from.
+ *
+ * Requires navigator.clipboard.readText, which needs a secure context and a
+ * user-gesture-driven call (satisfied by a click handler). Returns null on
+ * any failure — missing API, denied permission, non-secure origin — so
+ * callers can fall back to telling the user to press Ctrl+V instead.
+ */
+export async function readClipboardText() {
+    if (typeof navigator === 'undefined' || !navigator.clipboard?.readText)
+        return null;
+    try {
+        return await navigator.clipboard.readText();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/dateFormatters.d.ts

@@ -68,6 +68,10 @@ export declare function taskAge(dateStr: string): {
     color: string;
 };
 export type PacingLevel = 'fresh' | 'aging' | 'stale';
+export interface PacingOptions {
+    /** Return DaisyUI CSS-var tokens (`var(--color-success|warning|error)`) instead of fixed oklch literals, so colors follow the active theme. */
+    themeVars?: boolean;
+}
 export interface PacingResult {
     level: PacingLevel;
     color: string;
@@ -84,6 +88,11 @@ export interface PacingResult {
  *
  * Usage:
  *   const pacing = pacingColor(elapsedSeconds, 30, 120)
- *   // <span style="color: {pacing.color}">{elapsedSeconds}s</span>
+ *   // <span style="color: {pacing.color}">{formatPacingDuration(elapsedSeconds)}</span>
+ *
+ * Pass { themeVars: true } to get DaisyUI CSS-var tokens (var(--color-success|warning|error))
+ * instead of fixed oklch literals — colors then follow the active DaisyUI theme.
  */
-export declare function pacingColor(elapsedSeconds: number, warnAtSeconds: number, alertAtSeconds: number): PacingResult;
+export declare function pacingColor(elapsedSeconds: number, warnAtSeconds: number, alertAtSeconds: number, options?: PacingOptions): PacingResult;
+/** Compact duration format for pacing readouts: "45s", "3m 12s", "1h 05m". */
+export declare function formatPacingDuration(seconds: number): string;

package/dist/utils/dateFormatters.js

@@ -209,12 +209,32 @@ export function taskAge(dateStr) {
  *
  * Usage:
  *   const pacing = pacingColor(elapsedSeconds, 30, 120)
- *   // <span style="color: {pacing.color}">{elapsedSeconds}s</span>
+ *   // <span style="color: {pacing.color}">{formatPacingDuration(elapsedSeconds)}</span>
+ *
+ * Pass { themeVars: true } to get DaisyUI CSS-var tokens (var(--color-success|warning|error))
+ * instead of fixed oklch literals — colors then follow the active DaisyUI theme.
  */
-export function pacingColor(elapsedSeconds, warnAtSeconds, alertAtSeconds) {
+export function pacingColor(elapsedSeconds, warnAtSeconds, alertAtSeconds, options) {
+    if (options?.themeVars) {
+        if (elapsedSeconds >= alertAtSeconds)
+            return { level: 'stale', color: 'var(--color-error)' };
+        if (elapsedSeconds >= warnAtSeconds)
+            return { level: 'aging', color: 'var(--color-warning)' };
+        return { level: 'fresh', color: 'var(--color-success)' };
+    }
     if (elapsedSeconds >= alertAtSeconds)
         return { level: 'stale', color: 'oklch(0.65 0.20 25)' }; // red
     if (elapsedSeconds >= warnAtSeconds)
         return { level: 'aging', color: 'oklch(0.75 0.15 85)' }; // amber
     return { level: 'fresh', color: 'oklch(0.75 0.18 145)' }; // green
 }
+/** Compact duration format for pacing readouts: "45s", "3m 12s", "1h 05m". */
+export function formatPacingDuration(seconds) {
+    const s = Math.max(0, Math.floor(seconds));
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m ${s % 60}s`;
+    const mins = (s % 3600) / 60;
+    return `${Math.floor(s / 3600)}h ${mins < 10 ? '0' : ''}${Math.floor(mins)}m`;
+}