@iloveagents/foundry-web-voice 0.1.0

package/dist/react/voice-visualizer.js

@@ -0,0 +1,222 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The listening/speaking indicator: concentric rings breathing with the
+ * audio level.
+ *
+ * Three things it does that a canvas visualiser usually gets wrong:
+ *
+ * - **It wears the theme, and notices when the theme changes.** Colours are
+ *   read from the app's CSS custom properties (`--primary`,
+ *   `--muted-foreground`) rather than baked in. A canvas cannot inherit a CSS
+ *   variable the way a DOM node does, so it re-reads them: periodically while
+ *   animating (a theme-layer swap lands as inline style on an ancestor, which
+ *   no root-element observer can see), and on a root class / `data-theme` /
+ *   OS-scheme change for the static case, where no loop is running to notice.
+ *   Opacity comes from `globalAlpha`, not from building `rgba()` strings, so
+ *   any colour format the design system uses — `oklch`, `hsl`, hex — works
+ *   untouched.
+ * - **It matches the device.** The backing store is sized in device pixels
+ *   and scaled, so the rings are not soft on a retina display; a
+ *   `ResizeObserver` keeps that true when the pane is resized.
+ * - **It stops.** No analyser, a hidden tab, or `prefers-reduced-motion` and
+ *   the animation loop is not running at all — a decorative
+ *   `requestAnimationFrame` that never yields is a battery drain on a page
+ *   people leave open.
+ */
+import { useEffect, useRef } from "react";
+/**
+ * How often, in frames, to re-read the theme while animating.
+ *
+ * `getComputedStyle` forces a style recalc, so this cannot run per frame —
+ * but it must run at all: foundry applies its tokens as inline style on a
+ * `ThemeScope` div, so a theme-layer change is invisible to an observer
+ * watching the root element. Twice a second is imperceptible to the user
+ * and negligible to the browser.
+ */
+const COLOR_REFRESH_FRAMES = 30;
+/** Rings drawn outward from the core. */
+const RING_COUNT = 5;
+const RING_GAP = 22;
+const CORE_RADIUS = 20;
+/**
+ * Level smoothing, asymmetric on purpose.
+ *
+ * A single factor tracks speech syllable-for-syllable and the rings punch in
+ * and out on every one — a thud rather than a presence. Rising quickly and
+ * falling slowly turns the same signal into a swell that follows the shape
+ * of a phrase instead of its consonants.
+ */
+const ATTACK = 0.09;
+const RELEASE = 0.035;
+/**
+ * How far the rings travel at full level, in px.
+ *
+ * Deliberately small. The eye reads a gentle change as "alive"; a large one
+ * as an alarm, and at speech rates it is simply hectic.
+ */
+const SWELL = 14;
+function readColors(el) {
+    const style = getComputedStyle(el);
+    const primary = style.getPropertyValue("--primary").trim();
+    const muted = style.getPropertyValue("--muted-foreground").trim();
+    return {
+        // A theme that defines neither still gets something visible.
+        active: primary || "currentColor",
+        idle: muted || "currentColor",
+    };
+}
+export function VoiceVisualizer({ analyser, themeKey, className, label = "Voice activity", }) {
+    const canvasRef = useRef(null);
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        const ctx = canvas?.getContext("2d");
+        if (!canvas || !ctx)
+            return;
+        // Live, not a mount-time snapshot. Someone who turns reduced motion on
+        // mid-call is asking for the animation to stop now, and a voice session can
+        // run for many minutes — leaving the loop going for the rest of it is the
+        // whole of what they were trying to avoid.
+        const motionQuery = window.matchMedia?.("(prefers-reduced-motion: reduce)") ?? null;
+        let reducedMotion = motionQuery?.matches ?? false;
+        let colors = readColors(canvas);
+        let level = 0;
+        let frame = null;
+        let sinceColorRead = 0;
+        // The CSS-pixel size draw() works in. Cached here rather than measured per
+        // frame: getBoundingClientRect() forces layout, and at 60fps for the length
+        // of a call that is a self-inflicted reflow on every single frame. The only
+        // thing that can change it is a resize, and that has its own observer.
+        let cssWidth = 0;
+        let cssHeight = 0;
+        // Device pixels, so the strokes are crisp rather than upscaled.
+        const resize = () => {
+            const dpr = window.devicePixelRatio || 1;
+            const { width, height } = canvas.getBoundingClientRect();
+            if (!width || !height)
+                return;
+            cssWidth = width;
+            cssHeight = height;
+            canvas.width = Math.round(width * dpr);
+            canvas.height = Math.round(height * dpr);
+            ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        };
+        resize();
+        // Assigning canvas.width/height clears the backing store. With a loop
+        // running the next frame repaints it, but the static path (no analyser,
+        // or reduced motion) has no next frame — so resizing the window or the
+        // surrounding pane simply erased the idle indicator until something else
+        // happened to redraw.
+        const observer = new ResizeObserver(() => {
+            resize();
+            if (frame === null)
+                draw();
+        });
+        observer.observe(canvas);
+        const buffer = analyser ? new Uint8Array(new ArrayBuffer(analyser.frequencyBinCount)) : null;
+        const draw = () => {
+            if (++sinceColorRead >= COLOR_REFRESH_FRAMES) {
+                sinceColorRead = 0;
+                colors = readColors(canvas);
+            }
+            const width = cssWidth;
+            const height = cssHeight;
+            const cx = width / 2;
+            const cy = height / 2;
+            if (analyser && buffer) {
+                analyser.getByteFrequencyData(buffer);
+                let sum = 0;
+                for (let i = 0; i < buffer.length; i++)
+                    sum += buffer[i];
+                const next = sum / buffer.length / 255;
+                level += (next - level) * (next > level ? ATTACK : RELEASE);
+            }
+            else {
+                level += (0 - level) * RELEASE;
+            }
+            // Transparent: the surface behind decides the background, which is what
+            // makes this usable on a card, a panel, or a full-bleed stage.
+            ctx.clearRect(0, 0, width, height);
+            ctx.strokeStyle = analyser ? colors.active : colors.idle;
+            ctx.fillStyle = analyser ? colors.active : colors.idle;
+            for (let i = 0; i < RING_COUNT; i++) {
+                const radius = CORE_RADIUS + i * RING_GAP + level * SWELL;
+                const alpha = Math.max(0, 0.45 - i * 0.09);
+                if (alpha <= 0)
+                    continue;
+                ctx.globalAlpha = alpha;
+                ctx.lineWidth = 1.5 + level * 1.2;
+                ctx.beginPath();
+                ctx.arc(cx, cy, radius, 0, Math.PI * 2);
+                ctx.stroke();
+            }
+            ctx.globalAlpha = 0.32 + level * 0.3;
+            ctx.beginPath();
+            ctx.arc(cx, cy, CORE_RADIUS * (0.9 + level * 0.2), 0, Math.PI * 2);
+            ctx.fill();
+            ctx.globalAlpha = 1;
+        };
+        const loop = () => {
+            draw();
+            frame = requestAnimationFrame(loop);
+        };
+        /** Run only when there is something to animate and nobody objecting. */
+        const sync = () => {
+            const shouldAnimate = !reducedMotion && !!analyser && !document.hidden;
+            if (shouldAnimate && frame === null) {
+                loop();
+            }
+            else if (!shouldAnimate && frame !== null) {
+                cancelAnimationFrame(frame);
+                frame = null;
+                // One static frame: the shape is still meaningful as a state icon.
+                draw();
+            }
+            else if (!shouldAnimate) {
+                draw();
+            }
+        };
+        sync();
+        // A background tab throttles rAF to a crawl; stop rather than limp.
+        const onVisibility = sync;
+        const onMotionChange = (e) => {
+            reducedMotion = e.matches;
+            sync();
+        };
+        motionQuery?.addEventListener?.("change", onMotionChange);
+        document.addEventListener("visibilitychange", onVisibility);
+        // The theme can change without this component re-rendering: a class or
+        // data-theme flip, the OS scheme changing while the app is on "system",
+        // or a runtime theme layer being applied. Painted pixels do not follow a
+        // CSS variable, so watch for all three and repaint the static frame.
+        const refreshColors = () => {
+            colors = readColors(canvas);
+            if (frame === null)
+                draw();
+        };
+        const scheme = window.matchMedia?.("(prefers-color-scheme: dark)");
+        scheme?.addEventListener?.("change", refreshColors);
+        // Every ancestor, not just <html>: foundry's ThemeScope sets its runtime
+        // variables as an inline style on a wrapper div somewhere between the
+        // canvas and the root, and a change there is invisible to an observer
+        // watching only the document element. The animating path re-reads on a
+        // timer anyway; this is what keeps the STATIC path honest.
+        const themeObserver = new MutationObserver(refreshColors);
+        for (let node = canvas; node; node = node.parentElement) {
+            themeObserver.observe(node, {
+                attributes: true,
+                attributeFilter: ["class", "data-theme", "style"],
+            });
+        }
+        refreshColors();
+        return () => {
+            if (frame !== null)
+                cancelAnimationFrame(frame);
+            observer.disconnect();
+            themeObserver.disconnect();
+            scheme?.removeEventListener?.("change", refreshColors);
+            motionQuery?.removeEventListener?.("change", onMotionChange);
+            document.removeEventListener("visibilitychange", onVisibility);
+        };
+    }, [analyser, themeKey]);
+    return (_jsx("canvas", { ref: canvasRef, role: "img", "aria-label": label, className: className ?? "h-48 w-full max-w-md" }));
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@iloveagents/foundry-web-voice",
+  "version": "0.1.0",
+  "description": "Optional spoken-conversation tier for Foundry UI — Azure Voice Live wired into assistant-ui's realtime voice contract",
+  "keywords": [
+    "foundry",
+    "voice-live",
+    "assistant-ui",
+    "ag-ui",
+    "azure",
+    "voice",
+    "realtime",
+    "avatar"
+  ],
+  "license": "MIT",
+  "author": "iLoveAgents",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iLoveAgents/foundry-ui.git",
+    "directory": "packages/web-voice"
+  },
+  "homepage": "https://github.com/iLoveAgents/foundry-ui/tree/main/packages/web-voice#readme",
+  "bugs": {
+    "url": "https://github.com/iLoveAgents/foundry-ui/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/fix-dts-extensions.mjs dist",
+    "test:unit": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@iloveagents/foundry-agent": "workspace:^",
+    "@iloveagents/foundry-web-ui": "workspace:^",
+    "@iloveagents/foundry-voice-live-react": "^0.5.0"
+  },
+  "peerDependencies": {
+    "@assistant-ui/react": "^0.15.1",
+    "lucide-react": ">=0.400.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zustand": "^5.0.0"
+  },
+  "devDependencies": {
+    "@assistant-ui/react": "^0.15.1",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "jsdom": "^28.1.0",
+    "lucide-react": ">=0.400.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.4",
+    "zustand": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}