@cairnvibe/sdk 0.2.13 → 0.4.0

package/src/agent-loop.ts

@@ -0,0 +1,222 @@
+// The shared skeleton behind both agent-loop drivers — index.tsx's
+// runTypedAgentLoop (HTTP/typed transport) and realtime-server.ts's
+// finalizeTurn (WebSocket/voice relay) independently re-implemented the
+// exact same "ask, check terminal, execute a continuing step for real,
+// fold the result into working history, ask again, up to a hard
+// iteration cap" shape — a real, live duplication risk (any future fix
+// to one had to be remembered and re-applied to the other by hand).
+// This module is the first step of the Phase 3 multi-agent redesign
+// (see DEVELOPMENT.md/the plan file's "Phase 3" entry): extract exactly
+// that shared shape, with ZERO behavior change, so Planner/Critic
+// wiring in later steps has one real place to attach to instead of two.
+//
+// Deliberately does NOT own transport-specific side effects — sending a
+// message to a client, speaking, committing to a connection's real
+// cross-turn memory, barge-in cancellation timing. Those stay in each
+// transport's own getNextStep/onStep/onStepResult/executeStep closures,
+// and in what the caller does with this function's return value, exactly
+// as before this extraction. Plain TypeScript only (no JSX, no Node
+// built-ins) — imported as raw source by index.tsx's browser bundle AND
+// compiled to dist/ for realtime-server.ts's Node build.
+
+import { isTerminalVerb, type AgentEvent, type CriticVerdict, type HistoryTurn, type VerbResponse } from "@cairnvibe/core";
+
+/** 4 exchanges — matches the cap both original drivers independently used. */
+export const MAX_HISTORY_TURNS = 8;
+
+/**
+ * Architecture Pillar 4 — a cheap, LOCAL signal for "this goal probably
+ * needs more than one real step," checked BEFORE the first step even
+ * runs, so a caller can start the Planner call in PARALLEL with the
+ * first getNextStep instead of only after that first step already came
+ * back non-terminal (the "lazy gate" the plan singles out for
+ * replacement — realtime-server.ts's own onStep used to build planPromise
+ * only once `!terminal && iteration === 0` was already true, one full
+ * model round trip later than it needed to be). Deliberately
+ * conservative, on purpose: a false negative here just falls back to
+ * that same lazy-after-step-1 behavior — unchanged, zero regression —
+ * while a false positive costs one Planner call that would have started
+ * a moment later anyway, never a wrong answer. Genuine UI-pattern-aware
+ * classification (Pillar 2, not built yet) can replace this heuristic
+ * later without changing what calls it. Lives here (not server.ts) so
+ * BOTH transports can use the exact same check: this file is plain,
+ * dependency-free TypeScript imported as raw source by index.tsx's
+ * browser bundle AND compiled for realtime-server.ts's Node build — a
+ * server-only file (server.ts imports the Anthropic/Groq SDKs) can never
+ * be imported from the client widget.
+ */
+const MULTI_STEP_SIGNAL = /\b(then|after that|once (you|it|that|i)|and then|next,|first[,.]? .*\bthen\b)\b/;
+export function looksMultiStep(question: string): boolean {
+  return MULTI_STEP_SIGNAL.test(question.toLowerCase());
+}
+
+export function summarizeVerbForHistory(verb: VerbResponse): string {
+  if ("text" in verb && verb.text) return verb.text;
+  switch (verb.verb) {
+    case "highlight":
+    case "open":
+      return `(highlighted ${verb.target})`;
+    case "navigate":
+      return `(navigated to ${verb.route})`;
+    case "do":
+      return `(ran ${verb.action}${verb.target ? ` on ${verb.target}` : ""})`;
+    case "tour":
+      return verb.steps.map((s) => s.text).join(" ");
+    case "click":
+      return `(clicked ${verb.target})`;
+    case "fill":
+      return `(typed "${verb.value}" into ${verb.target})`;
+    case "read":
+      return `(read ${verb.target})`;
+    case "call_tool":
+      return `(called ${verb.name})`;
+    case "drag":
+      return `(dragged ${verb.target} to ${verb.to})`;
+    case "select":
+      return `(selected "${verb.value}" in ${verb.target})`;
+    case "key":
+      return `(pressed ${verb.key}${verb.target ? ` on ${verb.target}` : ""})`;
+    case "batch":
+      return `(${verb.actions.length} steps: ${verb.actions.map((a) => a.verb).join(", ")})`;
+    default:
+      return "(no response)";
+  }
+}
+
+export interface AgentLoopStepEvent {
+  verb: VerbResponse;
+  /** 0-based. */
+  iteration: number;
+  /** True if isTerminalVerb(verb) says this ends the loop right after
+   * this hook returns (TERMINAL_VERBS membership, except a navigate
+   * marked continueAfter — see isTerminalVerb's own doc comment). Lets a
+   * caller act differently for a continuing vs. final step without
+   * re-deriving that check itself. */
+  terminal: boolean;
+}
+
+export interface AgentLoopStepResultEvent {
+  verb: VerbResponse;
+  iteration: number;
+  observation: string | null | undefined;
+}
+
+export interface AgentLoopDeps {
+  /** Resolve the next step given the CURRENT working history. Return
+   * `null` for a response that failed to parse/validate — the HTTP
+   * path's own real case (a raw fetch response might not conform);
+   * realtime's in-process resolveVerb never produces this, since it
+   * always returns a valid VerbResponse itself. A null return ends the
+   * loop immediately with outcome "unparseable". */
+  getNextStep(loopHistory: HistoryTurn[], iteration: number): Promise<VerbResponse | null>;
+  /** Fires immediately after getNextStep resolves, before the terminal/
+   * continuing branch is decided — the real-time side-effect point (send
+   * the verb to a client, trigger an ack on the first continuing step,
+   * check for a superseding barge-in). Returning true aborts the loop
+   * immediately: no further side effects, outcome "aborted". */
+  onStep?(event: AgentLoopStepEvent): boolean | Promise<boolean>;
+  /** Execute a continuing verb (click/fill/read/call_tool/batch) for
+   * real; return its observation text (or null/undefined for "no
+   * result", folded into history as "no result" exactly like both
+   * original drivers already did). */
+  executeStep(verb: VerbResponse, iteration: number): Promise<string | null | undefined>;
+  /** Fires after executeStep resolves, before folding the observation
+   * into working history — a second real-time abort checkpoint (e.g. a
+   * barge-in generation check after awaiting a real tool result, which
+   * can itself take a while). Returning true aborts the loop with
+   * outcome "aborted", discarding this step's observation. */
+  onStepResult?(event: AgentLoopStepResultEvent): boolean | Promise<boolean>;
+  /**
+   * Phase 3 step 3 — a genuinely separate pass over the step's REAL
+   * observation, decoupled from the Executor/model's own self-report
+   * (the direct fix for the diagnosed bug: a batch succeeded and the
+   * model kept looping instead of recognizing it). Fires after
+   * onStepResult/the history fold. Returning a "task_complete" or
+   * "give_up" verdict ends the loop right here — even though the
+   * model's own verb was never a TERMINAL_VERBS member — instead of
+   * asking the model again and hoping it notices. Returning "continue"
+   * (including after the caller's own closure has silently handled a
+   * "replan" by fetching a fresh Plan — driveAgentLoop itself has no
+   * concept of a Plan, only of "keep going or stop") keeps the loop
+   * going exactly as if this hook were absent. Returning null/undefined
+   * behaves the same as "continue" — a caller can choose not to run the
+   * Critic on a particular step without a special no-op verdict shape.
+   */
+  runCritic?(event: AgentLoopStepResultEvent): Promise<CriticVerdict | null | undefined>;
+  /**
+   * Phase 3 step 5 — a pure, fire-and-forget event consumer for a
+   * Talker-style narration layer ("Revisable by Design"'s pattern):
+   * never awaited, never able to affect control flow. driveAgentLoop
+   * itself emits "act" (right after a step's onStep/abort check passes —
+   * only for a verb that's actually going to execute, never a discarded
+   * one) and "obs" (right after onStepResult's own abort check passes),
+   * since it already has that data at exactly those points. A caller's
+   * own onStep/runCritic closures can call this SAME callback directly —
+   * it's just a plain reference they already have via the deps object
+   * they constructed — to emit "thk" (Critic reasoning) or "inj"
+   * (injected filler narration, e.g. a Talker ack phrase) events too;
+   * driveAgentLoop has no opinion on those.
+   */
+  onEvent?(event: AgentEvent): void;
+  /** Defaults to 6 — a hard cap, not a target, matching both original drivers. */
+  maxIterations?: number;
+}
+
+export type AgentLoopOutcome =
+  | { outcome: "terminal"; finalVerb: VerbResponse; workingHistory: HistoryTurn[] }
+  /** The Critic independently confirmed the (last) task's doneContract
+   * is satisfied — the real fix for the diagnosed bug. The caller
+   * synthesizes its own terminal-shaped response (e.g. `{verb: "explain",
+   * text: verdict.reasoning}`) from `verdict`, same as it would for a
+   * model-produced terminal verb. */
+  | { outcome: "critic-complete"; verdict: CriticVerdict; workingHistory: HistoryTurn[] }
+  /** The Critic (or the harness's own stall-count fail-safe, inside the
+   * caller's runCritic closure) decided continuing wouldn't help. */
+  | { outcome: "critic-give-up"; verdict: CriticVerdict; workingHistory: HistoryTurn[] }
+  | { outcome: "unparseable"; workingHistory: HistoryTurn[] }
+  | { outcome: "gave-up"; workingHistory: HistoryTurn[] }
+  | { outcome: "aborted"; workingHistory: HistoryTurn[] };
+
+export async function driveAgentLoop(initialHistory: HistoryTurn[], deps: AgentLoopDeps): Promise<AgentLoopOutcome> {
+  const maxIterations = deps.maxIterations ?? 6;
+  let loopHistory = initialHistory;
+
+  for (let i = 0; i < maxIterations; i++) {
+    const verb = await deps.getNextStep(loopHistory, i);
+    if (verb === null) return { outcome: "unparseable", workingHistory: loopHistory };
+
+    const terminal = isTerminalVerb(verb);
+    if (deps.onStep) {
+      const abort = await deps.onStep({ verb, iteration: i, terminal });
+      if (abort) return { outcome: "aborted", workingHistory: loopHistory };
+    }
+    deps.onEvent?.({ type: "act", verb, at: Date.now() });
+
+    if (terminal) {
+      return { outcome: "terminal", finalVerb: verb, workingHistory: loopHistory };
+    }
+
+    const observation = await deps.executeStep(verb, i);
+    if (deps.onStepResult) {
+      const abort = await deps.onStepResult({ verb, iteration: i, observation });
+      if (abort) return { outcome: "aborted", workingHistory: loopHistory };
+    }
+    deps.onEvent?.({ type: "obs", observation: observation ?? "no result", ok: observation !== null && observation !== undefined, at: Date.now() });
+
+    loopHistory = [
+      ...loopHistory,
+      { role: "assistant" as const, text: `${summarizeVerbForHistory(verb)}. Result: ${observation ?? "no result"}` },
+    ].slice(-MAX_HISTORY_TURNS);
+
+    if (deps.runCritic) {
+      const verdict = await deps.runCritic({ verb, iteration: i, observation });
+      if (verdict?.verdict === "task_complete") return { outcome: "critic-complete", verdict, workingHistory: loopHistory };
+      if (verdict?.verdict === "give_up") return { outcome: "critic-give-up", verdict, workingHistory: loopHistory };
+      // "continue", "replan" (already handled inside the caller's own
+      // runCritic closure — see this field's own doc comment), or no
+      // verdict at all: fall through and keep looping, unchanged.
+    }
+  }
+
+  return { outcome: "gave-up", workingHistory: loopHistory };
+}

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/element-ladder.ts

@@ -40,6 +40,94 @@ export function findElement(target: string, liveElements?: Map<string, HTMLEleme
   return null;
 }
 
+/**
+ * Phase 3 step 4 (see DEVELOPMENT.md/the plan file) — CODA's own point:
+ * the Executor gets real local retry latitude for a genuinely MECHANICAL
+ * miss (a re-render replaced the DOM node the frozen liveElements snapshot
+ * pointed at; an animation/async render hadn't settled yet) before a
+ * failure escalates all the way to the Critic/a replan. Deliberately NOT
+ * a second LLM call — the Executor stays opinion-free, exactly re-running
+ * the SAME real lookup (which, past the liveElements-map check, already
+ * queries the LIVE DOM directly — a stale snapshot doesn't matter to that
+ * part) after a short real wait. A target that's genuinely not on the
+ * page still fails after `attempts`, surfacing as a real miss — this
+ * never silently invents success.
+ */
+export async function findElementWithRetry(
+  target: string,
+  liveElements?: Map<string, HTMLElement>,
+  attempts = 2,
+  delayMs = 300,
+): Promise<HTMLElement | null> {
+  for (let i = 0; i < attempts; i++) {
+    const el = findElement(target, liveElements);
+    if (el) return el;
+    if (i < attempts - 1) await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  return null;
+}
+
+/**
+ * Real, live-found bug this closes: a `fill`/`click` step reported itself
+ * "done" the instant its DOM event was dispatched — but the app's own
+ * reaction to that event (a filtered search-results grid re-rendering, a
+ * cart count updating) can be an unbounded-latency async round trip (a
+ * Next.js App Router `router.push` re-fetching a server component, for
+ * example — not a fixed debounce with a known delay to just sleep past).
+ * A `read` step immediately after saw STALE content and the agent
+ * confidently reported findings that didn't match what the page actually,
+ * eventually, showed — confirmed live: typing "book" into a search box,
+ * then reading the still-unfiltered product grid a moment later, and
+ * reporting a match ("Novel: The Long Way") the REAL, since-filtered page
+ * went on to show zero results for.
+ *
+ * Waits for real DOM mutations instead of guessing a sleep duration: if
+ * nothing starts mutating within `initialWaitMs`, resolves immediately
+ * (the action had no async effect at all — no reason to add latency to
+ * the common case); once mutations start, waits for `quietMs` of no
+ * further mutations before considering the page settled; a hard
+ * `timeoutMs` ceiling means a page that never stops mutating (an
+ * animation, a polling widget) can't stall the agent loop forever.
+ */
+export function waitForDomSettle(initialWaitMs = 100, quietMs = 200, timeoutMs = 1500): Promise<void> {
+  return new Promise((resolve) => {
+    // Real gap this closes: some callers stub a partial `document` (real
+    // tests in this repo do exactly that for other reasons — a fake
+    // WebMCP-tool document, for instance) without the rest of the DOM API
+    // surface — checking `document` alone isn't enough to guarantee
+    // MutationObserver (or document.body) actually exist too.
+    if (typeof document === "undefined" || typeof MutationObserver === "undefined" || !document.body) {
+      resolve();
+      return;
+    }
+    let settled = false;
+    let sawMutation = false;
+    let quietTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      observer.disconnect();
+      if (quietTimer) clearTimeout(quietTimer);
+      clearTimeout(hardCap);
+      resolve();
+    };
+
+    const observer = new MutationObserver(() => {
+      sawMutation = true;
+      if (quietTimer) clearTimeout(quietTimer);
+      quietTimer = setTimeout(finish, quietMs);
+    });
+    observer.observe(document.body, { childList: true, subtree: true, characterData: true, attributes: true });
+
+    const hardCap = setTimeout(finish, timeoutMs);
+
+    setTimeout(() => {
+      if (!sawMutation) finish(); // the action had no async effect — nothing to wait for
+    }, initialWaitMs);
+  });
+}
+
 export function highlightElement(el: HTMLElement, glowMs = 4000): void {
   el.scrollIntoView({ behavior: "smooth", block: "center" });
   el.classList.add("cairn-glow");
@@ -87,6 +175,88 @@ export function readElement(el: HTMLElement): string {
   return trimmed.length > 500 ? `${trimmed.slice(0, 499)}…` : trimmed || "(empty)";
 }
 
+/**
+ * Chooses a real `<option>` by its visible text — never a raw internal
+ * `value` the model could never actually see. Native `<select>` gets the
+ * direct path (set `.value` to the matching option's own value, then fire
+ * the same input/change pair fillElement uses so React notices). A custom
+ * listbox/combobox (role="listbox"/"option" — Radix, Headless UI, etc.)
+ * has no real `<option>` to set, so the fallback clicks the matching
+ * option-shaped descendant instead, the same "do the real user gesture"
+ * principle the do/click cases already follow.
+ */
+export function selectOption(el: HTMLElement, visibleText: string): boolean {
+  if (el.tagName === "SELECT") {
+    const select = el as HTMLSelectElement;
+    const match = Array.from(select.options).find((o) => normalize(o.textContent ?? "") === normalize(visibleText)) ?? Array.from(select.options).find((o) => normalize(o.textContent ?? "").includes(normalize(visibleText)));
+    if (!match) return false;
+    select.value = match.value;
+    select.dispatchEvent(new Event("input", { bubbles: true }));
+    select.dispatchEvent(new Event("change", { bubbles: true }));
+    return true;
+  }
+
+  const candidates = el.querySelectorAll<HTMLElement>('[role="option"], option, li, [role="menuitem"]');
+  const match = Array.from(candidates).find((c) => normalize(c.textContent ?? "") === normalize(visibleText)) ?? Array.from(candidates).find((c) => normalize(c.textContent ?? "").includes(normalize(visibleText)));
+  if (!match) return false;
+  match.click();
+  return true;
+}
+
+/**
+ * A real multi-point pointer-event sequence — pointerdown on `from`'s
+ * center, several pointermove steps toward `to`'s center, pointerup on
+ * `to` — the same technique a real mouse drag produces, for canvas/kanban/
+ * sortable-list libraries (react-dnd, dnd-kit, n8n's own node canvas) that
+ * listen for pointer events rather than a single synthetic "drop". Mouse
+ * events are fired alongside (same coordinates) for the older libraries
+ * that still only listen for those. jsdom's getBoundingClientRect returns
+ * all-zero rects with no real layout engine — fine here, since what matters
+ * for a test is that the sequence fires with consistent coordinates, not
+ * that they reflect real pixels.
+ */
+export function dragElement(from: HTMLElement, to: HTMLElement, steps = 5): void {
+  const fromRect = from.getBoundingClientRect();
+  const toRect = to.getBoundingClientRect();
+  const fromX = fromRect.left + fromRect.width / 2;
+  const fromY = fromRect.top + fromRect.height / 2;
+  const toX = toRect.left + toRect.width / 2;
+  const toY = toRect.top + toRect.height / 2;
+
+  const fire = (target: HTMLElement, type: string, x: number, y: number) => {
+    const opts = { bubbles: true, cancelable: true, clientX: x, clientY: y, view: typeof window !== "undefined" ? window : undefined };
+    if (typeof PointerEvent !== "undefined") target.dispatchEvent(new PointerEvent(type.replace("mouse", "pointer"), opts));
+    target.dispatchEvent(new MouseEvent(type, opts));
+  };
+
+  fire(from, "mousedown", fromX, fromY);
+  for (let i = 1; i <= steps; i++) {
+    const x = fromX + ((toX - fromX) * i) / steps;
+    const y = fromY + ((toY - fromY) * i) / steps;
+    fire(i === steps ? to : from, "mousemove", x, y);
+  }
+  fire(to, "mouseup", toX, toY);
+}
+
+const KEYS_WITH_PRINTABLE_CHAR = new Set(["Enter", "Tab"]);
+
+/**
+ * Presses one real key on a target element — focuses it first (a real
+ * keypress always lands on whatever's focused; a component that reacts to
+ * Escape/Enter/arrows almost always keys off document-level or its own
+ * focus-scoped listener, so focus has to be real before the event fires).
+ * Fires keydown/keyup (and keypress only for the handful of keys that
+ * still expect one — Enter/Tab — matching a real browser's own behavior,
+ * which no longer fires keypress for pure navigation keys like arrows).
+ */
+export function pressKey(el: HTMLElement, key: string): void {
+  if (typeof el.focus === "function") el.focus();
+  const opts = { bubbles: true, cancelable: true, key };
+  el.dispatchEvent(new KeyboardEvent("keydown", opts));
+  if (KEYS_WITH_PRINTABLE_CHAR.has(key)) el.dispatchEvent(new KeyboardEvent("keypress", opts));
+  el.dispatchEvent(new KeyboardEvent("keyup", opts));
+}
+
 export interface MissContext {
   attempted: string;
   route: string;