@cairnvibe/sdk 0.3.0 → 0.4.0

package/dist/verb-executor.js

@@ -10,6 +10,7 @@ exports.executeToolStep = executeToolStep;
 exports.executeVerbResponse = executeVerbResponse;
 const core_1 = require("@cairnvibe/core");
 const element_ladder_1 = require("./element-ladder");
+const cursor_overlay_1 = require("./cursor-overlay");
 const webmcp_client_1 = require("./webmcp-client");
 // wait_for's own real, bounded retry budget — longer than
 // findElementWithRetry's own default (2 attempts, 300ms apart, ~300ms
@@ -78,12 +79,17 @@ function dispatchVerb(verb, route, options) {
                 return;
             }
             (0, element_ladder_1.highlightElement)(el);
-            // "open" means make the thing actually appear (a menu, a modal, a
-            // panel) — highlighting alone doesn't do that; a real click does.
-            if (verb.verb === "open")
-                el.click();
-            if (verb.text)
-                options.onExplain(verb.text);
+            // The cursor visibly arrives before "open"'s real click fires — the
+            // whole point is a user watching sees where it's about to click
+            // BEFORE the menu/modal/panel actually opens, not simultaneously.
+            void (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                // "open" means make the thing actually appear (a menu, a modal, a
+                // panel) — highlighting alone doesn't do that; a real click does.
+                if (verb.verb === "open")
+                    el.click();
+                if (verb.text)
+                    options.onExplain(verb.text);
+            });
             return;
         }
         case "navigate": {
@@ -142,9 +148,11 @@ function dispatchVerb(verb, route, options) {
                     // on a different page) — never fired in addition to a real
                     // click, so the action can't run twice.
                     (0, element_ladder_1.highlightElement)(el);
-                    el.click();
-                    if (verb.text)
-                        options.onExplain(verb.text);
+                    void (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                        el.click();
+                        if (verb.text)
+                            options.onExplain(verb.text);
+                    });
                     return;
                 }
                 if (verb.target)
@@ -189,14 +197,16 @@ function dispatchVerb(verb, route, options) {
                 return;
             }
             (0, element_ladder_1.highlightElement)(el);
-            el.click();
-            // Real, live-found race this closes — see waitForDomSettle's own doc
-            // comment: a click can trigger an async re-render (a cart count
-            // updating, a filtered list refreshing) that hasn't happened yet the
-            // instant .click() returns. A subsequent read step in the same turn
-            // needs the SETTLED result, not whatever was on screen a moment ago.
-            void (0, element_ladder_1.waitForDomSettle)().then(() => {
-                options.onToolStep?.({ verb: "click", target: verb.target, ok: true, observation: "Clicked it." });
+            void (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                el.click();
+                // Real, live-found race this closes — see waitForDomSettle's own
+                // doc comment: a click can trigger an async re-render (a cart count
+                // updating, a filtered list refreshing) that hasn't happened yet the
+                // instant .click() returns. A subsequent read step in the same turn
+                // needs the SETTLED result, not whatever was on screen a moment ago.
+                void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                    options.onToolStep?.({ verb: "click", target: verb.target, ok: true, observation: "Clicked it." });
+                });
             });
             return;
         }
@@ -204,23 +214,30 @@ function dispatchVerb(verb, route, options) {
             if (verb.text)
                 options.onExplain(verb.text);
             const el = (0, element_ladder_1.findElement)(verb.target, options.liveElements);
-            if (!el || !(0, element_ladder_1.fillElement)(el, verb.value)) {
+            if (!el) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
-                options.onToolStep?.({
-                    verb: "fill",
-                    target: verb.target,
-                    ok: false,
-                    observation: el ? "That element isn't a real form field — can't type into it." : "Could not find that element on the page.",
-                });
+                options.onToolStep?.({ verb: "fill", target: verb.target, ok: false, observation: "Could not find that element on the page." });
                 return;
             }
             (0, element_ladder_1.highlightElement)(el);
-            // See the click case's own comment — the exact real bug found live:
-            // typing into a search box, then reading the still-unfiltered
-            // results a moment later and reporting a match the real, since-
-            // filtered page never actually showed.
-            void (0, element_ladder_1.waitForDomSettle)().then(() => {
-                options.onToolStep?.({ verb: "fill", target: verb.target, ok: true, observation: `Typed "${verb.value}" into it.` });
+            // fillElement itself is both the "is this a real form field" check
+            // AND the commit (it sets the value the instant it returns true) —
+            // deliberately called from inside this .then(), not the synchronous
+            // miss-check above, so the cursor is genuinely seen arriving BEFORE
+            // any text appears, not simultaneously with it.
+            void (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                if (!(0, element_ladder_1.fillElement)(el, verb.value)) {
+                    (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
+                    options.onToolStep?.({ verb: "fill", target: verb.target, ok: false, observation: "That element isn't a real form field — can't type into it." });
+                    return;
+                }
+                // See the click case's own comment — the exact real bug found live:
+                // typing into a search box, then reading the still-unfiltered
+                // results a moment later and reporting a match the real, since-
+                // filtered page never actually showed.
+                void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                    options.onToolStep?.({ verb: "fill", target: verb.target, ok: true, observation: `Typed "${verb.value}" into it.` });
+                });
             });
             return;
         }
@@ -233,7 +250,12 @@ function dispatchVerb(verb, route, options) {
                 options.onToolStep?.({ verb: "read", target: verb.target, ok: false, observation: "Could not find that element on the page." });
                 return;
             }
-            options.onToolStep?.({ verb: "read", target: verb.target, ok: true, observation: (0, element_ladder_1.readElement)(el) });
+            // No mutation here, but the cursor still visits what's being read —
+            // real visual proof of what the agent is actually looking at, not
+            // just a claim in the eventual reported observation.
+            void (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                options.onToolStep?.({ verb: "read", target: verb.target, ok: true, observation: (0, element_ladder_1.readElement)(el) });
+            });
             return;
         }
         case "call_tool": {
@@ -255,12 +277,19 @@ function dispatchVerb(verb, route, options) {
                 return;
             }
             (0, element_ladder_1.highlightElement)(from);
-            (0, element_ladder_1.dragElement)(from, to);
-            // Same real re-render race as click/fill — a drop can trigger an
-            // async re-render (a canvas connection line, a reordered list) that
-            // hasn't settled the instant the pointer sequence finishes.
-            void (0, element_ladder_1.waitForDomSettle)().then(() => {
-                options.onToolStep?.({ verb: "drag", target: verb.target, ok: true, observation: `Dragged it to ${verb.to}.` });
+            void (0, cursor_overlay_1.moveCursorTo)(from).then(() => {
+                (0, element_ladder_1.dragElement)(from, to);
+                // The cursor also glides to the drop point — fire-and-forget, not
+                // awaited, since it's purely a visual echo of a drag that already
+                // happened via real pointer events; nothing downstream depends on
+                // it finishing.
+                void (0, cursor_overlay_1.moveCursorTo)(to);
+                // Same real re-render race as click/fill — a drop can trigger an
+                // async re-render (a canvas connection line, a reordered list) that
+                // hasn't settled the instant the pointer sequence finishes.
+                void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                    options.onToolStep?.({ verb: "drag", target: verb.target, ok: true, observation: `Dragged it to ${verb.to}.` });
+                });
             });
             return;
         }
@@ -268,19 +297,24 @@ function dispatchVerb(verb, route, options) {
             if (verb.text)
                 options.onExplain(verb.text);
             const el = (0, element_ladder_1.findElement)(verb.target, options.liveElements);
-            if (!el || !(0, element_ladder_1.selectOption)(el, verb.value)) {
+            if (!el) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
-                options.onToolStep?.({
-                    verb: "select",
-                    target: verb.target,
-                    ok: false,
-                    observation: el ? `Could not find an option matching "${verb.value}".` : "Could not find that element on the page.",
-                });
+                options.onToolStep?.({ verb: "select", target: verb.target, ok: false, observation: "Could not find that element on the page." });
                 return;
             }
             (0, element_ladder_1.highlightElement)(el);
-            void (0, element_ladder_1.waitForDomSettle)().then(() => {
-                options.onToolStep?.({ verb: "select", target: verb.target, ok: true, observation: `Selected "${verb.value}".` });
+            // Same reasoning as fill's own comment — selectOption is both the
+            // "does a matching option exist" check and the commit, so it's called
+            // from inside this .then(), after the cursor genuinely arrives.
+            void (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                if (!(0, element_ladder_1.selectOption)(el, verb.value)) {
+                    (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
+                    options.onToolStep?.({ verb: "select", target: verb.target, ok: false, observation: `Could not find an option matching "${verb.value}".` });
+                    return;
+                }
+                void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                    options.onToolStep?.({ verb: "select", target: verb.target, ok: true, observation: `Selected "${verb.value}".` });
+                });
             });
             return;
         }
@@ -294,10 +328,22 @@ function dispatchVerb(verb, route, options) {
                 options.onToolStep?.({ verb: "key", target: verb.target, ok: false, observation: "Could not find that element on the page." });
                 return;
             }
-            (0, element_ladder_1.pressKey)(el, verb.key);
-            void (0, element_ladder_1.waitForDomSettle)().then(() => {
-                options.onToolStep?.({ verb: "key", target: verb.target, ok: true, observation: `Pressed ${verb.key}.` });
-            });
+            const afterMove = () => {
+                (0, element_ladder_1.pressKey)(el, verb.key);
+                void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                    options.onToolStep?.({ verb: "key", target: verb.target, ok: true, observation: `Pressed ${verb.key}.` });
+                });
+            };
+            // With no explicit target ("whatever's currently focused"), there's
+            // nothing sensible for the cursor to glide to — call straight through
+            // instead of routing through a promise callback for no reason, so
+            // this path stays exactly as synchronous as it always was.
+            if (verb.target) {
+                void (0, cursor_overlay_1.moveCursorTo)(el).then(afterMove);
+            }
+            else {
+                afterMove();
+            }
             return;
         }
         case "scroll": {
@@ -314,8 +360,10 @@ function dispatchVerb(verb, route, options) {
             // exactly the real repositioning this verb exists for; the glow
             // also gives the user a visible cue of where the agent just moved.
             (0, element_ladder_1.highlightElement)(el);
-            void (0, element_ladder_1.waitForDomSettle)().then(() => {
-                options.onToolStep?.({ verb: "scroll", target: verb.target, ok: true, observation: "Scrolled it into view." });
+            void (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                    options.onToolStep?.({ verb: "scroll", target: verb.target, ok: true, observation: "Scrolled it into view." });
+                });
             });
             return;
         }
@@ -328,7 +376,9 @@ function dispatchVerb(verb, route, options) {
                     options.onToolStep?.({ verb: "wait_for", target: verb.target, ok: false, observation: "It never appeared." });
                     return;
                 }
-                options.onToolStep?.({ verb: "wait_for", target: verb.target, ok: true, observation: "It appeared." });
+                void (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                    options.onToolStep?.({ verb: "wait_for", target: verb.target, ok: true, observation: "It appeared." });
+                });
             });
             return;
         }
@@ -379,6 +429,7 @@ async function executeOneBatchAction(action, route, options) {
                 return { ok: false, observation: "Could not find that element on the page." };
             }
             (0, element_ladder_1.highlightElement)(el);
+            await (0, cursor_overlay_1.moveCursorTo)(el);
             el.click();
             // Same real race as the single-step case (see waitForDomSettle's own
             // doc comment) — arguably MORE likely here, since a batch's next
@@ -388,14 +439,19 @@ async function executeOneBatchAction(action, route, options) {
         }
         case "fill": {
             const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
-            if (!el || !(0, element_ladder_1.fillElement)(el, action.value)) {
+            if (!el) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
-                return {
-                    ok: false,
-                    observation: el ? "That element isn't a real form field — can't type into it." : "Could not find that element on the page.",
-                };
+                return { ok: false, observation: "Could not find that element on the page." };
             }
             (0, element_ladder_1.highlightElement)(el);
+            // See the single-step fill case's own comment — fillElement is both
+            // the field-type check and the commit, called after the cursor
+            // genuinely arrives rather than in the synchronous miss-check.
+            await (0, cursor_overlay_1.moveCursorTo)(el);
+            if (!(0, element_ladder_1.fillElement)(el, action.value)) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: "That element isn't a real form field — can't type into it." };
+            }
             await (0, element_ladder_1.waitForDomSettle)();
             return { ok: true, observation: `Typed "${action.value}" into it.` };
         }
@@ -405,6 +461,7 @@ async function executeOneBatchAction(action, route, options) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
                 return { ok: false, observation: "Could not find that element on the page." };
             }
+            await (0, cursor_overlay_1.moveCursorTo)(el);
             return { ok: true, observation: (0, element_ladder_1.readElement)(el) };
         }
         case "call_tool": {
@@ -419,17 +476,24 @@ async function executeOneBatchAction(action, route, options) {
                 return { ok: false, observation: from ? "Could not find the drop destination on the page." : "Could not find that element on the page." };
             }
             (0, element_ladder_1.highlightElement)(from);
+            await (0, cursor_overlay_1.moveCursorTo)(from);
             (0, element_ladder_1.dragElement)(from, to);
+            void (0, cursor_overlay_1.moveCursorTo)(to); // visual echo of the drop point — not awaited, purely decorative
             await (0, element_ladder_1.waitForDomSettle)();
             return { ok: true, observation: `Dragged it to ${action.to}.` };
         }
         case "select": {
             const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
-            if (!el || !(0, element_ladder_1.selectOption)(el, action.value)) {
+            if (!el) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
-                return { ok: false, observation: el ? `Could not find an option matching "${action.value}".` : "Could not find that element on the page." };
+                return { ok: false, observation: "Could not find that element on the page." };
             }
             (0, element_ladder_1.highlightElement)(el);
+            await (0, cursor_overlay_1.moveCursorTo)(el);
+            if (!(0, element_ladder_1.selectOption)(el, action.value)) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: `Could not find an option matching "${action.value}".` };
+            }
             await (0, element_ladder_1.waitForDomSettle)();
             return { ok: true, observation: `Selected "${action.value}".` };
         }
@@ -440,6 +504,8 @@ async function executeOneBatchAction(action, route, options) {
                     (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
                 return { ok: false, observation: "Could not find that element on the page." };
             }
+            if (action.target)
+                await (0, cursor_overlay_1.moveCursorTo)(el);
             (0, element_ladder_1.pressKey)(el, action.key);
             await (0, element_ladder_1.waitForDomSettle)();
             return { ok: true, observation: `Pressed ${action.key}.` };
@@ -451,6 +517,7 @@ async function executeOneBatchAction(action, route, options) {
                 return { ok: false, observation: "Could not find that element on the page." };
             }
             (0, element_ladder_1.highlightElement)(el);
+            await (0, cursor_overlay_1.moveCursorTo)(el);
             await (0, element_ladder_1.waitForDomSettle)();
             return { ok: true, observation: "Scrolled it into view." };
         }
@@ -460,6 +527,7 @@ async function executeOneBatchAction(action, route, options) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
                 return { ok: false, observation: "It never appeared." };
             }
+            await (0, cursor_overlay_1.moveCursorTo)(el);
             return { ok: true, observation: "It appeared." };
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnvibe/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "In-app AI copilot — <Copilot/> for React/Next.js, <cairn-widget> for any framework — plus the server handlers and realtime voice relay behind them.",
   "license": "MIT",
   "publishConfig": { "access": "public" },

package/src/cursor-overlay.ts

@@ -0,0 +1,130 @@
+// A visible, animated synthetic cursor that glides to whatever element the
+// agent is about to act on, and genuinely arrives — before anything actually
+// happens on screen — rather than a click just occurring with no visible
+// lead-up. Real, watchable proof of what the agent resolved, the same way
+// watching a person's own mouse move tells you where they're about to click
+// before it happens; matches this SDK's own "verified, not trusted"
+// discipline in a form a user can literally see, not just read.
+//
+// Purely additive and deliberately decoupled from highlightElement
+// (element-ladder.ts) — that function's own scroll+glow behavior is
+// unchanged and still called by every site that used it before. This module
+// only adds the moving cursor itself; a caller awaits moveCursorTo(el)
+// before firing the real action so the cursor is seen arriving first, never
+// after the fact — see verb-executor.ts's own call sites for the exact
+// sequencing.
+
+const CURSOR_ID = "cairn-cursor";
+const MOVE_MS = 550;
+const ARRIVE_PAUSE_MS = 160;
+// The CSS side already disables the cursor's transition/animation under
+// prefers-reduced-motion (see #cairn-cursor in the injected <style> block),
+// which makes it jump instead of glide — but without this, the real delay
+// before the action fires would stay the full ~710ms even though there's
+// nothing left to watch. Mirrors the visual change with a real timing one.
+const REDUCED_MOVE_MS = 60;
+const REDUCED_ARRIVE_PAUSE_MS = 40;
+
+function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  );
+}
+
+// Module-scope, not per-call — the whole point is a SINGLE cursor that
+// glides from wherever it last was, the way a real mouse never teleports
+// between two unrelated screen positions.
+let lastX: number | null = null;
+let lastY: number | null = null;
+
+function ensureCursorEl(): HTMLElement | null {
+  if (typeof document === "undefined" || !document.body) return null;
+  let el = document.getElementById(CURSOR_ID);
+  if (el) return el;
+  el = document.createElement("div");
+  el.id = CURSOR_ID;
+  el.setAttribute("aria-hidden", "true");
+  // A simple filled pointer shape — matches the widget's own ember accent,
+  // with a thin dark stroke so it reads clearly on light AND dark pages
+  // (the host app's own background is never something this SDK controls).
+  el.innerHTML =
+    '<svg width="22" height="22" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg">' +
+    '<path d="M2 1.5 L2 18.2 L6.3 14.4 L9.1 20.6 L11.7 19.4 L8.9 13.3 L14.6 13.1 Z" fill="#E07A3F" stroke="#1B1815" stroke-width="1.1" stroke-linejoin="round"/>' +
+    "</svg>";
+  el.style.cssText =
+    "position:fixed;left:0;top:0;z-index:2147483001;pointer-events:none;opacity:0;transition:opacity 180ms ease;will-change:transform;filter:drop-shadow(0 3px 6px rgba(0,0,0,0.35));";
+  document.body.appendChild(el);
+  return el;
+}
+
+/**
+ * Animates the synthetic cursor to `el`'s center and resolves once it has
+ * genuinely arrived (plus a brief real hover pause) — callers await this
+ * BEFORE performing the real action, so the cursor is seen gliding there
+ * first. Deliberately timer-driven (`window.setTimeout`), not
+ * `transitionend`/`Element.animate().finished`-driven — this repo's test
+ * environment is plain Node, not a real browser (see waitForDomSettle's own
+ * doc comment for the same discipline), and a fixed, known duration is what
+ * makes this testable with fake timers instead of needing real animation-
+ * completion events that a headless/no-DOM environment may never fire.
+ *
+ * SSR/no-DOM safe — same defensive guard `waitForDomSettle` already uses —
+ * so a caller never needs its own environment check before calling this.
+ */
+export function moveCursorTo(el: HTMLElement): Promise<void> {
+  if (typeof document === "undefined" || typeof window === "undefined" || typeof el.getBoundingClientRect !== "function") {
+    return Promise.resolve();
+  }
+  const cursor = ensureCursorEl();
+  if (!cursor) return Promise.resolve();
+
+  const rect = el.getBoundingClientRect();
+  const x = rect.left + rect.width / 2;
+  const y = rect.top + rect.height / 2;
+
+  if (lastX === null || lastY === null) {
+    // The very first move of the session starts from the widget's own
+    // corner (bottom-right, where the FAB lives) instead of materializing
+    // at (0,0) — reads as "coming from Cairn," not appearing from nowhere.
+    lastX = window.innerWidth - 40;
+    lastY = window.innerHeight - 40;
+    cursor.style.transform = `translate(${lastX}px, ${lastY}px)`;
+  }
+
+  const reduced = prefersReducedMotion();
+  const moveMs = reduced ? REDUCED_MOVE_MS : MOVE_MS;
+  const arrivePauseMs = reduced ? REDUCED_ARRIVE_PAUSE_MS : ARRIVE_PAUSE_MS;
+
+  cursor.style.transition = `transform ${moveMs}ms cubic-bezier(.4,0,.2,1), opacity 180ms ease`;
+  cursor.style.opacity = "1";
+  // Forces a style flush so the browser animates FROM the current position
+  // TO the new one instead of jumping straight there — reading a layout
+  // property is the standard, harmless way to force this without a real
+  // animation API (which, per this function's own doc comment, this
+  // deliberately avoids depending on for its completion signal anyway).
+  void cursor.offsetHeight;
+  cursor.style.transform = `translate(${x}px, ${y}px)`;
+  lastX = x;
+  lastY = y;
+
+  return new Promise((resolve) => {
+    window.setTimeout(() => {
+      cursor.classList.add("cairn-cursor-hover");
+      window.setTimeout(() => {
+        cursor.classList.remove("cairn-cursor-hover");
+        resolve();
+      }, arrivePauseMs);
+    }, moveMs);
+  });
+}
+
+/** Fades the synthetic cursor out — called once the widget itself closes or
+ * unmounts, so it doesn't sit visible on screen after the conversation
+ * ends. Safe to call even if the cursor was never created. */
+export function hideCursor(): void {
+  if (typeof document === "undefined") return;
+  const el = document.getElementById(CURSOR_ID);
+  if (el) el.style.opacity = "0";
+}

package/src/index.tsx

@@ -19,6 +19,7 @@ import {
 import { classifyUiPattern, deriveStructureSignals, isTerminalVerb, safeParseVerbResponse, type CriticVerdict, type HistoryTurn as HistoryEntry, type Plan, type ProgressLedger, type Task, type TourStep, type VerbResponse } from "@cairnvibe/core";
 import { driveAgentLoop, looksMultiStep } from "./agent-loop";
 import { collectVisible } from "./context-collector";
+import { hideCursor } from "./cursor-overlay";
 import { findElement, highlightElement, logMiss, type MissContext } from "./element-ladder";
 import { createLiveElementRegistry } from "./runtime-scan";
 import { discoverWebMcpTools } from "./webmcp-client";
@@ -132,6 +133,12 @@ export function Copilot({
   // loadPersistedConversation's own doc comment) had showing a moment ago,
   // so a real reload never again looks like the conversation simply ended.
   const [open, setOpen] = useState(false);
+  // Fades the synthetic cursor out once the panel closes (or the widget
+  // itself unmounts) instead of leaving it sitting visible on the page.
+  useEffect(() => {
+    if (!open) hideCursor();
+    return () => hideCursor();
+  }, [open]);
   // Collapsed by default so the panel only ever shows the current exchange
   // — the full archived transcript (built up over a long conversation)
   // stays out of the way behind an explicit toggle instead of always being
@@ -2160,9 +2167,13 @@ const COPILOT_STYLES = `
   0%, 100% { box-shadow: 0 0 0 0 rgba(16, 185, 129, 0.4); }
   70% { box-shadow: 0 0 0 10px rgba(16, 185, 129, 0); }
 }
-@keyframes cairn-pulse-indigo {
-  0%, 100% { box-shadow: 0 0 0 0 rgba(99, 102, 241, 0.4); }
-  70% { box-shadow: 0 0 0 10px rgba(99, 102, 241, 0); }
+@keyframes cairn-pulse-ember {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(224, 122, 63, 0.4); }
+  70% { box-shadow: 0 0 0 10px rgba(224, 122, 63, 0); }
+}
+@keyframes cairn-cursor-arrive {
+  0% { box-shadow: 0 0 0 0 rgba(224, 122, 63, 0.55); }
+  100% { box-shadow: 0 0 0 9px rgba(224, 122, 63, 0); }
 }
 @keyframes cairn-spin {
   from { transform: rotate(0deg); }
@@ -2178,7 +2189,7 @@ const COPILOT_STYLES = `
 }
 @keyframes cairn-word-sweep {
   0% { opacity: 0.35; text-shadow: none; }
-  35% { opacity: 1; color: #4f46e5; text-shadow: 0 0 10px rgba(99, 102, 241, 0.45); }
+  35% { opacity: 1; color: #E07A3F; text-shadow: 0 0 10px rgba(224, 122, 63, 0.45); }
   100% { opacity: 1; color: inherit; text-shadow: none; }
 }
 @keyframes cairn-thinking-bounce {
@@ -2186,16 +2197,19 @@ const COPILOT_STYLES = `
   40% { opacity: 0.9; transform: translateY(-3px); }
 }
 .cairn-glow {
-  animation: cairn-pulse-indigo 1.1s ease-out 2;
-  outline: 2px solid #6366f1;
+  animation: cairn-pulse-ember 1.1s ease-out 2;
+  outline: 2px solid #E07A3F;
   outline-offset: 3px;
   border-radius: 8px;
 }
+.cairn-cursor-hover {
+  animation: cairn-cursor-arrive 0.3s ease-out;
+}
 .cairn-spin {
   animation: cairn-spin 0.8s linear infinite;
 }
 @media (prefers-reduced-motion: reduce) {
-  .cairn-fab, .cairn-panel, .cairn-bubble, .cairn-word, .cairn-thinking-dot {
+  .cairn-fab, .cairn-panel, .cairn-bubble, .cairn-word, .cairn-thinking-dot, #cairn-cursor {
     animation: none !important;
     transition: none !important;
   }

package/src/realtime-server.ts

@@ -42,6 +42,7 @@ import {
   resolveCritic,
   resolvePlan,
   resolveVerb,
+  KeyRotator,
   type CapabilityTier,
   type CreateCopilotHandlerOptions,
 } from "./server";
@@ -175,11 +176,23 @@ export { seedHistoryFromMemory, formatRememberedFacts };
 export function createRealtimeServer(options: CreateRealtimeServerOptions): http.Server {
   const registeredActions = options.registeredActions ?? [];
   const capability = options.capability ?? "act";
-  const llm = createVerbLLM(options);
+  // One shared rotator across all three LLM roles — see
+  // CreateCopilotHandlerOptions.keyRotator's own doc comment for the real
+  // gap this closes (a key one role confirmed dead used to stay invisible
+  // to the other two, which kept rediscovering it fresh on every call).
+  // Only built for groq — anthropic's createXLLM calls ignore keyRotator
+  // entirely, so building one for it would be dead work. Respects a
+  // caller-supplied options.keyRotator (e.g. shared with the typed/HTTP
+  // transport in the same process) instead of always building a fresh one.
+  const sharedOptions: CreateRealtimeServerOptions =
+    options.provider === "groq" && !options.keyRotator
+      ? { ...options, keyRotator: options.apiKeys ? new KeyRotator(options.apiKeys) : options.apiKey ? new KeyRotator([options.apiKey]) : KeyRotator.fromEnvList(process.env.GROQ_API_KEYS) ?? undefined }
+      : options;
+  const llm = createVerbLLM(sharedOptions);
   // Phase 3 steps 2-3 — real, separately-configured Planner/Critic LLMs.
   // See finalizeTurn's own doc comment for how they're actually used.
-  const planLLM = createPlanLLM(options);
-  const criticLLM = createCriticLLM(options);
+  const planLLM = createPlanLLM(sharedOptions);
+  const criticLLM = createCriticLLM(sharedOptions);
   // "text" is optional on highlight/open/navigate/do in the base prompt —
   // fine for the typed/HTTP path, which always has a visible answer area,
   // but silence reads as broken in a live voice conversation (the client