@athenaintel/react 0.60.1 → 0.61.0

package/dist/agent-ui/AgentUiLayer.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentUiLayer.cjs","sources":["../../src/agent-ui/AgentUiLayer.tsx"],"sourcesContent":["'use client';\n\nimport {\n  ChevronLeftIcon,\n  ChevronRightIcon,\n  MousePointer2Icon,\n  PauseIcon,\n  PlayIcon,\n  XIcon,\n} from 'lucide-react';\nimport {\n  type CSSProperties,\n  type ReactNode,\n  useEffect,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from 'react';\nimport { createPortal } from 'react-dom';\nimport { useOwnerDocument, usePortalContainer } from '../lib/owner-document';\nimport { cn } from '../lib/utils';\nimport { useAthenaThemeStyle } from '../provider/theme-style-context';\nimport { AGENT_ATTR } from './contract';\nimport type { AgentUiMarkTone, AgentUiQuestion, AgentUiStage, AgentUiTour } from './stage';\nimport type { AgentUi } from './tools';\n\n/*\n * The overlay: what the person sees of the agent on their page. A box around\n * the element it means, a note beside it, a cursor where it clicks, the\n * walkthrough's card and the question it asks before acting.\n *\n * It draws the stage and nothing else. Every piece is restyled through\n * `classNames`; a host that wants something else entirely reads\n * `agentUi.stage` and draws its own.\n */\n\nexport interface AgentUiLayerClassNames {\n  /** The box around the element. */\n  mark?: string;\n  /** The note beside a marked element. */\n  caption?: string;\n  /** The agent's cursor. */\n  cursor?: string;\n  /** The walkthrough's card. */\n  tour?: string;\n  /** The question asked before acting. */\n  question?: string;\n}\n\nexport interface AgentUiLayerProps {\n  agentUi: AgentUi;\n  classNames?: AgentUiLayerClassNames;\n}\n\ninterface Box {\n  top: number;\n  left: number;\n  width: number;\n  height: number;\n}\n\n/** Space between an element and the box drawn around it. */\nconst MARK_INSET_PX = 4;\n/** Space between the box and a card anchored to it. */\nconst CARD_GAP_PX = 10;\n/** A card's width, and the room a card needs below an element to sit there. */\nconst CARD_WIDTH_PX = 320;\nconst CARD_ROOM_PX = 150;\nconst EDGE_PX = 8;\n\n/** Follow an element's box frame by frame while it is shown: it rides scrolling and layout changes. */\nfunction useElementBox(element: Element | null): Box | null {\n  const [box, setBox] = useState<Box | null>(null);\n  useEffect(() => {\n    const view = element?.ownerDocument.defaultView;\n    if (!element || !view) {\n      setBox(null);\n      return;\n    }\n    let frame = 0;\n    let last = '';\n    const read = () => {\n      const rect = element.isConnected ? element.getBoundingClientRect() : null;\n      const next = rect ? { top: rect.top, left: rect.left, width: rect.width, height: rect.height } : null;\n      const signature = next\n        ? [next.top, next.left, next.width, next.height].map(Math.round).join(':')\n        : 'gone';\n      if (signature !== last) {\n        last = signature;\n        setBox(next);\n      }\n      frame = view.requestAnimationFrame(read);\n    };\n    read();\n    return () => view.cancelAnimationFrame(frame);\n  }, [element]);\n  return box;\n}\n\ninterface Viewport {\n  width: number;\n  height: number;\n}\n\nfunction viewportOf(doc: Document | null): Viewport {\n  const view = doc?.defaultView;\n  return { width: view?.innerWidth ?? 1024, height: view?.innerHeight ?? 768 };\n}\n\n/** Where a card anchored to an element sits: under it when there is room, else over it; at the bottom of the page without one. */\nexport function cardPosition({ box, viewport }: { box: Box | null; viewport: Viewport }): CSSProperties {\n  const width = Math.min(CARD_WIDTH_PX, viewport.width - EDGE_PX * 2);\n  if (!box) {\n    return { left: Math.max(EDGE_PX, (viewport.width - width) / 2), bottom: 24, width };\n  }\n  const left = Math.min(Math.max(box.left, EDGE_PX), Math.max(EDGE_PX, viewport.width - width - EDGE_PX));\n  const below = box.top + box.height + MARK_INSET_PX + CARD_GAP_PX;\n  if (below + CARD_ROOM_PX <= viewport.height || box.top < CARD_ROOM_PX) {\n    return { left, top: Math.min(below, Math.max(EDGE_PX, viewport.height - CARD_ROOM_PX)), width };\n  }\n  return { left, bottom: viewport.height - box.top + MARK_INSET_PX + CARD_GAP_PX, width };\n}\n\nconst TONE_CLASS: Record<AgentUiMarkTone, string> = {\n  point: 'border-primary ring-primary/25',\n  act: 'border-primary ring-primary/25 border-dashed',\n  ask: 'border-amber-500 ring-amber-500/25',\n};\n\nfunction Mark({\n  box,\n  tone,\n  spotlight,\n  leaving,\n  className,\n}: {\n  box: Box;\n  tone: AgentUiMarkTone;\n  spotlight: boolean;\n  leaving: boolean;\n  className?: string;\n}) {\n  return (\n    <div\n      data-testid=\"agent-ui-mark\"\n      data-tone={tone}\n      className={cn(\n        'pointer-events-none fixed rounded-lg border-2 ring-4 transition-opacity duration-500 motion-reduce:transition-none',\n        TONE_CLASS[tone],\n        spotlight && 'shadow-[0_0_0_100vmax_rgb(0_0_0/0.45)]',\n        leaving ? 'opacity-0' : 'opacity-100',\n        className,\n      )}\n      style={{\n        top: box.top - MARK_INSET_PX,\n        left: box.left - MARK_INSET_PX,\n        width: box.width + MARK_INSET_PX * 2,\n        height: box.height + MARK_INSET_PX * 2,\n      }}\n    />\n  );\n}\n\nfunction Card({\n  box,\n  viewport,\n  fit = false,\n  className,\n  children,\n  ...props\n}: {\n  box: Box | null;\n  viewport: Viewport;\n  /** As wide as its words need, up to a card's width (a note); otherwise a card's full width. */\n  fit?: boolean;\n  className?: string;\n  children: ReactNode;\n  role?: string;\n  'aria-label'?: string;\n  'data-testid'?: string;\n}) {\n  const { width, ...position } = cardPosition({ box, viewport });\n  return (\n    <div\n      {...props}\n      className={cn(\n        'pointer-events-auto fixed rounded-xl border border-border bg-popover px-3.5 py-3 text-popover-foreground text-sm shadow-lg',\n        className,\n      )}\n      style={fit ? { ...position, maxWidth: width } : { ...position, width }}\n    >\n      {children}\n    </div>\n  );\n}\n\nfunction Cursor({\n  box,\n  presses,\n  glideMs,\n  className,\n}: {\n  box: Box;\n  presses: number;\n  glideMs: number;\n  className?: string;\n}) {\n  const x = box.left + box.width / 2;\n  const y = box.top + box.height / 2;\n  // The cursor starts a little off the element and glides onto it.\n  const [arrived, setArrived] = useState(false);\n  useEffect(() => {\n    const frame = requestAnimationFrame(() => setArrived(true));\n    return () => cancelAnimationFrame(frame);\n  }, []);\n  return (\n    <div\n      data-testid=\"agent-ui-cursor\"\n      className={cn('pointer-events-none fixed top-0 left-0 motion-reduce:transition-none', className)}\n      style={{\n        transform: `translate(${arrived ? x : x + 48}px, ${arrived ? y : y + 48}px)`,\n        transitionProperty: 'transform',\n        transitionTimingFunction: 'ease-out',\n        transitionDuration: `${glideMs}ms`,\n      }}\n    >\n      <MousePointer2Icon className=\"size-5 fill-primary text-primary-foreground drop-shadow\" />\n      {presses > 0 ? (\n        <span\n          key={presses}\n          data-testid=\"agent-ui-press\"\n          className=\"-top-2 -left-2 absolute size-6 animate-ping rounded-full bg-primary/50 [animation-iteration-count:1]\"\n        />\n      ) : null}\n    </div>\n  );\n}\n\nfunction TourCard({\n  tour,\n  stage,\n  box,\n  viewport,\n  className,\n}: {\n  tour: AgentUiTour;\n  stage: AgentUiStage;\n  box: Box | null;\n  viewport: Viewport;\n  className?: string;\n}) {\n  const step = tour.steps[tour.index];\n  const last = tour.index >= tour.steps.length - 1;\n  const progressRef = useRef<HTMLDivElement>(null);\n  const advancing = tour.playing && !tour.searching;\n  const durationMs = step?.durationMs ?? 0;\n  // The bar fills over the step's time, so the person sees it will move on by itself.\n  // `tour.index` restarts it for a step of the same length.\n  // biome-ignore lint/correctness/useExhaustiveDependencies: a new step restarts the bar\n  useEffect(() => {\n    const bar = progressRef.current;\n    if (!bar || typeof bar.animate !== 'function') return;\n    if (!advancing) return;\n    const animation = bar.animate([{ width: '0%' }, { width: '100%' }], {\n      duration: durationMs,\n      fill: 'forwards',\n      easing: 'linear',\n    });\n    return () => animation.cancel();\n  }, [advancing, durationMs, tour.index]);\n  if (!step) return null;\n  return (\n    <Card\n      box={box}\n      viewport={viewport}\n      className={className}\n      role=\"dialog\"\n      aria-label={tour.title ?? 'Walkthrough'}\n      data-testid=\"agent-ui-tour\"\n    >\n      <div className=\"flex items-center justify-between gap-3\">\n        <p className=\"min-w-0 truncate text-muted-foreground text-xs\">\n          {tour.title ? `${tour.title} · ` : ''}\n          Step {tour.index + 1} of {tour.steps.length}\n        </p>\n        <button\n          type=\"button\"\n          aria-label=\"Close the walkthrough\"\n          onClick={() => stage.endTour()}\n          className=\"shrink-0 rounded-md p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground\"\n        >\n          <XIcon className=\"size-3.5\" />\n        </button>\n      </div>\n      <p className=\"break-words pt-1.5 leading-snug\" data-testid=\"agent-ui-tour-text\">\n        {step.text}\n      </p>\n      {!tour.searching && !tour.element ? (\n        <p className=\"pt-1 text-muted-foreground text-xs\">This one is not on the page you have open.</p>\n      ) : null}\n      <div className=\"mt-2.5 h-0.5 overflow-hidden rounded-full bg-muted\">\n        <div ref={progressRef} className=\"h-full w-0 bg-primary\" />\n      </div>\n      <div className=\"flex items-center gap-1 pt-2\">\n        <button\n          type=\"button\"\n          aria-label=\"Previous step\"\n          disabled={tour.index === 0}\n          onClick={() => stage.tourBack()}\n          className=\"rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40\"\n        >\n          <ChevronLeftIcon className=\"size-4\" />\n        </button>\n        <button\n          type=\"button\"\n          aria-label={tour.playing ? 'Pause the walkthrough' : 'Play the walkthrough'}\n          onClick={() => stage.tourTogglePlaying()}\n          className=\"rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground\"\n        >\n          {tour.playing ? <PauseIcon className=\"size-4\" /> : <PlayIcon className=\"size-4\" />}\n        </button>\n        <button\n          type=\"button\"\n          onClick={() => stage.tourNext()}\n          className=\"ml-auto flex items-center gap-1 rounded-md bg-primary px-2.5 py-1 font-medium text-primary-foreground text-xs transition-colors hover:bg-primary/90\"\n        >\n          {last ? 'Done' : 'Next'}\n          {last ? null : <ChevronRightIcon className=\"size-3.5\" />}\n        </button>\n      </div>\n    </Card>\n  );\n}\n\nfunction QuestionCard({\n  question,\n  stage,\n  box,\n  viewport,\n  className,\n}: {\n  question: AgentUiQuestion;\n  stage: AgentUiStage;\n  box: Box | null;\n  viewport: Viewport;\n  className?: string;\n}) {\n  return (\n    <Card\n      box={box}\n      viewport={viewport}\n      className={className}\n      role=\"alertdialog\"\n      aria-label={question.title}\n      data-testid=\"agent-ui-question\"\n    >\n      <p className=\"break-words font-semibold leading-snug\">{question.title}</p>\n      {question.body ? (\n        <p className=\"break-words pt-1 text-muted-foreground leading-snug\">{question.body}</p>\n      ) : null}\n      <div className=\"flex flex-wrap items-center gap-2 pt-2.5\">\n        <button\n          type=\"button\"\n          onClick={() => stage.answer(true)}\n          className=\"rounded-md bg-primary px-2.5 py-1 font-medium text-primary-foreground text-xs transition-colors hover:bg-primary/90\"\n        >\n          {question.allowLabel}\n        </button>\n        <button\n          type=\"button\"\n          onClick={() => stage.answer(false)}\n          className=\"rounded-md border border-border px-2.5 py-1 font-medium text-xs transition-colors hover:bg-muted\"\n        >\n          {question.declineLabel}\n        </button>\n      </div>\n    </Card>\n  );\n}\n\n/**\n * Draws the agent's stage over the page. Mount one per `AgentUi`, anywhere\n * under the provider; it portals to the document's body and takes no clicks\n * except on its own cards.\n */\nexport function AgentUiLayer({ agentUi, classNames }: AgentUiLayerProps) {\n  const { stage } = agentUi;\n  const state = useSyncExternalStore(stage.subscribe, stage.getState, stage.getState);\n  const ownerDocument = useOwnerDocument();\n  const portalContainer = usePortalContainer();\n  const themeStyle = useAthenaThemeStyle();\n\n  const tourElement = state.tour?.element ?? null;\n  const markedElement = state.tour ? tourElement : (state.mark?.element ?? null);\n  const markBox = useElementBox(markedElement);\n  const cursorBox = useElementBox(state.cursor?.element ?? null);\n  const questionBox = useElementBox(state.question?.element ?? null);\n\n  // Escape closes what the agent is showing: the person's page is theirs.\n  const showing = state.tour !== null || state.mark !== null;\n  useEffect(() => {\n    if (!showing || !ownerDocument) return;\n    const onKeyDown = (event: KeyboardEvent) => {\n      if (event.key !== 'Escape') return;\n      stage.endTour();\n      stage.clearMark();\n    };\n    ownerDocument.addEventListener('keydown', onKeyDown);\n    return () => ownerDocument.removeEventListener('keydown', onKeyDown);\n  }, [ownerDocument, showing, stage]);\n\n  const container = portalContainer ?? ownerDocument?.body;\n  if (!container) return null;\n  const idle = !state.mark && !state.cursor && !state.tour && !state.question;\n  if (idle) return null;\n  const viewport = viewportOf(ownerDocument);\n  const caption = state.tour ? null : (state.mark?.caption ?? null);\n\n  return createPortal(\n    <div\n      {...{ [AGENT_ATTR.layer]: '' }}\n      className=\"athena-sdk athena-sdk-chrome pointer-events-none fixed inset-0 z-[2147483000]\"\n      style={themeStyle as CSSProperties | undefined}\n    >\n      {markBox && (state.tour || state.mark) ? (\n        <Mark\n          box={markBox}\n          tone={state.tour ? 'point' : (state.mark?.tone ?? 'point')}\n          spotlight={state.tour ? false : (state.mark?.spotlight ?? false)}\n          leaving={state.tour ? false : (state.mark?.leaving ?? false)}\n          className={classNames?.mark}\n        />\n      ) : null}\n      {/* What the agent is doing, said aloud for a screen reader too. */}\n      <div aria-live=\"polite\">\n        {caption && markBox && !state.question ? (\n          <Card\n            box={markBox}\n            viewport={viewport}\n            fit\n            className={cn(\n              'pointer-events-none transition-opacity duration-500 motion-reduce:transition-none',\n              state.mark?.leaving ? 'opacity-0' : 'opacity-100',\n              classNames?.caption,\n            )}\n            data-testid=\"agent-ui-caption\"\n          >\n            <p className=\"break-words leading-snug\">{caption}</p>\n          </Card>\n        ) : null}\n      </div>\n      {state.tour ? (\n        <TourCard\n          tour={state.tour}\n          stage={stage}\n          box={markBox}\n          viewport={viewport}\n          className={classNames?.tour}\n        />\n      ) : null}\n      {state.question ? (\n        <QuestionCard\n          question={state.question}\n          stage={stage}\n          box={questionBox}\n          viewport={viewport}\n          className={classNames?.question}\n        />\n      ) : null}\n      {state.cursor && cursorBox ? (\n        <Cursor\n          box={cursorBox}\n          presses={state.cursor.presses}\n          glideMs={agentUi.pace().cursorGlideMs}\n          className={classNames?.cursor}\n        />\n      ) : null}\n    </div>,\n    container,\n  );\n}\n"],"names":["useState","useEffect","jsx","cn","jsxs","MousePointer2Icon","useRef","XIcon","ChevronLeftIcon","PauseIcon","PlayIcon","ChevronRightIcon","useSyncExternalStore","useOwnerDocument","usePortalContainer","useAthenaThemeStyle","createPortal","AGENT_ATTR"],"mappings":"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"}

package/dist/agent-ui/AgentUiLayer.d.ts

@@ -0,0 +1,40 @@
+import { type CSSProperties } from 'react';
+import type { AgentUi } from './tools';
+export interface AgentUiLayerClassNames {
+    /** The box around the element. */
+    mark?: string;
+    /** The note beside a marked element. */
+    caption?: string;
+    /** The agent's cursor. */
+    cursor?: string;
+    /** The walkthrough's card. */
+    tour?: string;
+    /** The question asked before acting. */
+    question?: string;
+}
+export interface AgentUiLayerProps {
+    agentUi: AgentUi;
+    classNames?: AgentUiLayerClassNames;
+}
+interface Box {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+interface Viewport {
+    width: number;
+    height: number;
+}
+/** Where a card anchored to an element sits: under it when there is room, else over it; at the bottom of the page without one. */
+export declare function cardPosition({ box, viewport }: {
+    box: Box | null;
+    viewport: Viewport;
+}): CSSProperties;
+/**
+ * Draws the agent's stage over the page. Mount one per `AgentUi`, anywhere
+ * under the provider; it portals to the document's body and takes no clicks
+ * except on its own cards.
+ */
+export declare function AgentUiLayer({ agentUi, classNames }: AgentUiLayerProps): import("react").ReactPortal | null;
+export {};

package/dist/agent-ui/AgentUiLayer.js

@@ -0,0 +1,387 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import { XIcon, ChevronLeftIcon, PauseIcon, PlayIcon, ChevronRightIcon, MousePointer2Icon } from "lucide-react";
+import { useSyncExternalStore, useEffect, useState, useRef } from "react";
+import { createPortal } from "react-dom";
+import { useOwnerDocument, usePortalContainer } from "../lib/owner-document.js";
+import { useAthenaThemeStyle } from "../provider/theme-style-context.js";
+import { AGENT_ATTR } from "./contract.js";
+import { cn } from "cnfast";
+const MARK_INSET_PX = 4;
+const CARD_GAP_PX = 10;
+const CARD_WIDTH_PX = 320;
+const CARD_ROOM_PX = 150;
+const EDGE_PX = 8;
+function useElementBox(element) {
+  const [box, setBox] = useState(null);
+  useEffect(() => {
+    const view = element == null ? void 0 : element.ownerDocument.defaultView;
+    if (!element || !view) {
+      setBox(null);
+      return;
+    }
+    let frame = 0;
+    let last = "";
+    const read = () => {
+      const rect = element.isConnected ? element.getBoundingClientRect() : null;
+      const next = rect ? { top: rect.top, left: rect.left, width: rect.width, height: rect.height } : null;
+      const signature = next ? [next.top, next.left, next.width, next.height].map(Math.round).join(":") : "gone";
+      if (signature !== last) {
+        last = signature;
+        setBox(next);
+      }
+      frame = view.requestAnimationFrame(read);
+    };
+    read();
+    return () => view.cancelAnimationFrame(frame);
+  }, [element]);
+  return box;
+}
+function viewportOf(doc) {
+  const view = doc == null ? void 0 : doc.defaultView;
+  return { width: (view == null ? void 0 : view.innerWidth) ?? 1024, height: (view == null ? void 0 : view.innerHeight) ?? 768 };
+}
+function cardPosition({ box, viewport }) {
+  const width = Math.min(CARD_WIDTH_PX, viewport.width - EDGE_PX * 2);
+  if (!box) {
+    return { left: Math.max(EDGE_PX, (viewport.width - width) / 2), bottom: 24, width };
+  }
+  const left = Math.min(Math.max(box.left, EDGE_PX), Math.max(EDGE_PX, viewport.width - width - EDGE_PX));
+  const below = box.top + box.height + MARK_INSET_PX + CARD_GAP_PX;
+  if (below + CARD_ROOM_PX <= viewport.height || box.top < CARD_ROOM_PX) {
+    return { left, top: Math.min(below, Math.max(EDGE_PX, viewport.height - CARD_ROOM_PX)), width };
+  }
+  return { left, bottom: viewport.height - box.top + MARK_INSET_PX + CARD_GAP_PX, width };
+}
+const TONE_CLASS = {
+  point: "border-primary ring-primary/25",
+  act: "border-primary ring-primary/25 border-dashed",
+  ask: "border-amber-500 ring-amber-500/25"
+};
+function Mark({
+  box,
+  tone,
+  spotlight,
+  leaving,
+  className
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      "data-testid": "agent-ui-mark",
+      "data-tone": tone,
+      className: cn(
+        "pointer-events-none fixed rounded-lg border-2 ring-4 transition-opacity duration-500 motion-reduce:transition-none",
+        TONE_CLASS[tone],
+        spotlight && "shadow-[0_0_0_100vmax_rgb(0_0_0/0.45)]",
+        leaving ? "opacity-0" : "opacity-100",
+        className
+      ),
+      style: {
+        top: box.top - MARK_INSET_PX,
+        left: box.left - MARK_INSET_PX,
+        width: box.width + MARK_INSET_PX * 2,
+        height: box.height + MARK_INSET_PX * 2
+      }
+    }
+  );
+}
+function Card({
+  box,
+  viewport,
+  fit = false,
+  className,
+  children,
+  ...props
+}) {
+  const { width, ...position } = cardPosition({ box, viewport });
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ...props,
+      className: cn(
+        "pointer-events-auto fixed rounded-xl border border-border bg-popover px-3.5 py-3 text-popover-foreground text-sm shadow-lg",
+        className
+      ),
+      style: fit ? { ...position, maxWidth: width } : { ...position, width },
+      children
+    }
+  );
+}
+function Cursor({
+  box,
+  presses,
+  glideMs,
+  className
+}) {
+  const x = box.left + box.width / 2;
+  const y = box.top + box.height / 2;
+  const [arrived, setArrived] = useState(false);
+  useEffect(() => {
+    const frame = requestAnimationFrame(() => setArrived(true));
+    return () => cancelAnimationFrame(frame);
+  }, []);
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-testid": "agent-ui-cursor",
+      className: cn("pointer-events-none fixed top-0 left-0 motion-reduce:transition-none", className),
+      style: {
+        transform: `translate(${arrived ? x : x + 48}px, ${arrived ? y : y + 48}px)`,
+        transitionProperty: "transform",
+        transitionTimingFunction: "ease-out",
+        transitionDuration: `${glideMs}ms`
+      },
+      children: [
+        /* @__PURE__ */ jsx(MousePointer2Icon, { className: "size-5 fill-primary text-primary-foreground drop-shadow" }),
+        presses > 0 ? /* @__PURE__ */ jsx(
+          "span",
+          {
+            "data-testid": "agent-ui-press",
+            className: "-top-2 -left-2 absolute size-6 animate-ping rounded-full bg-primary/50 [animation-iteration-count:1]"
+          },
+          presses
+        ) : null
+      ]
+    }
+  );
+}
+function TourCard({
+  tour,
+  stage,
+  box,
+  viewport,
+  className
+}) {
+  const step = tour.steps[tour.index];
+  const last = tour.index >= tour.steps.length - 1;
+  const progressRef = useRef(null);
+  const advancing = tour.playing && !tour.searching;
+  const durationMs = (step == null ? void 0 : step.durationMs) ?? 0;
+  useEffect(() => {
+    const bar = progressRef.current;
+    if (!bar || typeof bar.animate !== "function") return;
+    if (!advancing) return;
+    const animation = bar.animate([{ width: "0%" }, { width: "100%" }], {
+      duration: durationMs,
+      fill: "forwards",
+      easing: "linear"
+    });
+    return () => animation.cancel();
+  }, [advancing, durationMs, tour.index]);
+  if (!step) return null;
+  return /* @__PURE__ */ jsxs(
+    Card,
+    {
+      box,
+      viewport,
+      className,
+      role: "dialog",
+      "aria-label": tour.title ?? "Walkthrough",
+      "data-testid": "agent-ui-tour",
+      children: [
+        /* @__PURE__ */ jsxs("div", { className: "flex items-center justify-between gap-3", children: [
+          /* @__PURE__ */ jsxs("p", { className: "min-w-0 truncate text-muted-foreground text-xs", children: [
+            tour.title ? `${tour.title} · ` : "",
+            "Step ",
+            tour.index + 1,
+            " of ",
+            tour.steps.length
+          ] }),
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              "aria-label": "Close the walkthrough",
+              onClick: () => stage.endTour(),
+              className: "shrink-0 rounded-md p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground",
+              children: /* @__PURE__ */ jsx(XIcon, { className: "size-3.5" })
+            }
+          )
+        ] }),
+        /* @__PURE__ */ jsx("p", { className: "break-words pt-1.5 leading-snug", "data-testid": "agent-ui-tour-text", children: step.text }),
+        !tour.searching && !tour.element ? /* @__PURE__ */ jsx("p", { className: "pt-1 text-muted-foreground text-xs", children: "This one is not on the page you have open." }) : null,
+        /* @__PURE__ */ jsx("div", { className: "mt-2.5 h-0.5 overflow-hidden rounded-full bg-muted", children: /* @__PURE__ */ jsx("div", { ref: progressRef, className: "h-full w-0 bg-primary" }) }),
+        /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1 pt-2", children: [
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              "aria-label": "Previous step",
+              disabled: tour.index === 0,
+              onClick: () => stage.tourBack(),
+              className: "rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40",
+              children: /* @__PURE__ */ jsx(ChevronLeftIcon, { className: "size-4" })
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              "aria-label": tour.playing ? "Pause the walkthrough" : "Play the walkthrough",
+              onClick: () => stage.tourTogglePlaying(),
+              className: "rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground",
+              children: tour.playing ? /* @__PURE__ */ jsx(PauseIcon, { className: "size-4" }) : /* @__PURE__ */ jsx(PlayIcon, { className: "size-4" })
+            }
+          ),
+          /* @__PURE__ */ jsxs(
+            "button",
+            {
+              type: "button",
+              onClick: () => stage.tourNext(),
+              className: "ml-auto flex items-center gap-1 rounded-md bg-primary px-2.5 py-1 font-medium text-primary-foreground text-xs transition-colors hover:bg-primary/90",
+              children: [
+                last ? "Done" : "Next",
+                last ? null : /* @__PURE__ */ jsx(ChevronRightIcon, { className: "size-3.5" })
+              ]
+            }
+          )
+        ] })
+      ]
+    }
+  );
+}
+function QuestionCard({
+  question,
+  stage,
+  box,
+  viewport,
+  className
+}) {
+  return /* @__PURE__ */ jsxs(
+    Card,
+    {
+      box,
+      viewport,
+      className,
+      role: "alertdialog",
+      "aria-label": question.title,
+      "data-testid": "agent-ui-question",
+      children: [
+        /* @__PURE__ */ jsx("p", { className: "break-words font-semibold leading-snug", children: question.title }),
+        question.body ? /* @__PURE__ */ jsx("p", { className: "break-words pt-1 text-muted-foreground leading-snug", children: question.body }) : null,
+        /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-center gap-2 pt-2.5", children: [
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              onClick: () => stage.answer(true),
+              className: "rounded-md bg-primary px-2.5 py-1 font-medium text-primary-foreground text-xs transition-colors hover:bg-primary/90",
+              children: question.allowLabel
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              onClick: () => stage.answer(false),
+              className: "rounded-md border border-border px-2.5 py-1 font-medium text-xs transition-colors hover:bg-muted",
+              children: question.declineLabel
+            }
+          )
+        ] })
+      ]
+    }
+  );
+}
+function AgentUiLayer({ agentUi, classNames }) {
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i;
+  const { stage } = agentUi;
+  const state = useSyncExternalStore(stage.subscribe, stage.getState, stage.getState);
+  const ownerDocument = useOwnerDocument();
+  const portalContainer = usePortalContainer();
+  const themeStyle = useAthenaThemeStyle();
+  const tourElement = ((_a = state.tour) == null ? void 0 : _a.element) ?? null;
+  const markedElement = state.tour ? tourElement : ((_b = state.mark) == null ? void 0 : _b.element) ?? null;
+  const markBox = useElementBox(markedElement);
+  const cursorBox = useElementBox(((_c = state.cursor) == null ? void 0 : _c.element) ?? null);
+  const questionBox = useElementBox(((_d = state.question) == null ? void 0 : _d.element) ?? null);
+  const showing = state.tour !== null || state.mark !== null;
+  useEffect(() => {
+    if (!showing || !ownerDocument) return;
+    const onKeyDown = (event) => {
+      if (event.key !== "Escape") return;
+      stage.endTour();
+      stage.clearMark();
+    };
+    ownerDocument.addEventListener("keydown", onKeyDown);
+    return () => ownerDocument.removeEventListener("keydown", onKeyDown);
+  }, [ownerDocument, showing, stage]);
+  const container = portalContainer ?? (ownerDocument == null ? void 0 : ownerDocument.body);
+  if (!container) return null;
+  const idle = !state.mark && !state.cursor && !state.tour && !state.question;
+  if (idle) return null;
+  const viewport = viewportOf(ownerDocument);
+  const caption = state.tour ? null : ((_e = state.mark) == null ? void 0 : _e.caption) ?? null;
+  return createPortal(
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ...{ [AGENT_ATTR.layer]: "" },
+        className: "athena-sdk athena-sdk-chrome pointer-events-none fixed inset-0 z-[2147483000]",
+        style: themeStyle,
+        children: [
+          markBox && (state.tour || state.mark) ? /* @__PURE__ */ jsx(
+            Mark,
+            {
+              box: markBox,
+              tone: state.tour ? "point" : ((_f = state.mark) == null ? void 0 : _f.tone) ?? "point",
+              spotlight: state.tour ? false : ((_g = state.mark) == null ? void 0 : _g.spotlight) ?? false,
+              leaving: state.tour ? false : ((_h = state.mark) == null ? void 0 : _h.leaving) ?? false,
+              className: classNames == null ? void 0 : classNames.mark
+            }
+          ) : null,
+          /* @__PURE__ */ jsx("div", { "aria-live": "polite", children: caption && markBox && !state.question ? /* @__PURE__ */ jsx(
+            Card,
+            {
+              box: markBox,
+              viewport,
+              fit: true,
+              className: cn(
+                "pointer-events-none transition-opacity duration-500 motion-reduce:transition-none",
+                ((_i = state.mark) == null ? void 0 : _i.leaving) ? "opacity-0" : "opacity-100",
+                classNames == null ? void 0 : classNames.caption
+              ),
+              "data-testid": "agent-ui-caption",
+              children: /* @__PURE__ */ jsx("p", { className: "break-words leading-snug", children: caption })
+            }
+          ) : null }),
+          state.tour ? /* @__PURE__ */ jsx(
+            TourCard,
+            {
+              tour: state.tour,
+              stage,
+              box: markBox,
+              viewport,
+              className: classNames == null ? void 0 : classNames.tour
+            }
+          ) : null,
+          state.question ? /* @__PURE__ */ jsx(
+            QuestionCard,
+            {
+              question: state.question,
+              stage,
+              box: questionBox,
+              viewport,
+              className: classNames == null ? void 0 : classNames.question
+            }
+          ) : null,
+          state.cursor && cursorBox ? /* @__PURE__ */ jsx(
+            Cursor,
+            {
+              box: cursorBox,
+              presses: state.cursor.presses,
+              glideMs: agentUi.pace().cursorGlideMs,
+              className: classNames == null ? void 0 : classNames.cursor
+            }
+          ) : null
+        ]
+      }
+    ),
+    container
+  );
+}
+export {
+  AgentUiLayer,
+  cardPosition
+};
+//# sourceMappingURL=AgentUiLayer.js.map

package/dist/agent-ui/AgentUiLayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentUiLayer.js","sources":["../../src/agent-ui/AgentUiLayer.tsx"],"sourcesContent":["'use client';\n\nimport {\n  ChevronLeftIcon,\n  ChevronRightIcon,\n  MousePointer2Icon,\n  PauseIcon,\n  PlayIcon,\n  XIcon,\n} from 'lucide-react';\nimport {\n  type CSSProperties,\n  type ReactNode,\n  useEffect,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from 'react';\nimport { createPortal } from 'react-dom';\nimport { useOwnerDocument, usePortalContainer } from '../lib/owner-document';\nimport { cn } from '../lib/utils';\nimport { useAthenaThemeStyle } from '../provider/theme-style-context';\nimport { AGENT_ATTR } from './contract';\nimport type { AgentUiMarkTone, AgentUiQuestion, AgentUiStage, AgentUiTour } from './stage';\nimport type { AgentUi } from './tools';\n\n/*\n * The overlay: what the person sees of the agent on their page. A box around\n * the element it means, a note beside it, a cursor where it clicks, the\n * walkthrough's card and the question it asks before acting.\n *\n * It draws the stage and nothing else. Every piece is restyled through\n * `classNames`; a host that wants something else entirely reads\n * `agentUi.stage` and draws its own.\n */\n\nexport interface AgentUiLayerClassNames {\n  /** The box around the element. */\n  mark?: string;\n  /** The note beside a marked element. */\n  caption?: string;\n  /** The agent's cursor. */\n  cursor?: string;\n  /** The walkthrough's card. */\n  tour?: string;\n  /** The question asked before acting. */\n  question?: string;\n}\n\nexport interface AgentUiLayerProps {\n  agentUi: AgentUi;\n  classNames?: AgentUiLayerClassNames;\n}\n\ninterface Box {\n  top: number;\n  left: number;\n  width: number;\n  height: number;\n}\n\n/** Space between an element and the box drawn around it. */\nconst MARK_INSET_PX = 4;\n/** Space between the box and a card anchored to it. */\nconst CARD_GAP_PX = 10;\n/** A card's width, and the room a card needs below an element to sit there. */\nconst CARD_WIDTH_PX = 320;\nconst CARD_ROOM_PX = 150;\nconst EDGE_PX = 8;\n\n/** Follow an element's box frame by frame while it is shown: it rides scrolling and layout changes. */\nfunction useElementBox(element: Element | null): Box | null {\n  const [box, setBox] = useState<Box | null>(null);\n  useEffect(() => {\n    const view = element?.ownerDocument.defaultView;\n    if (!element || !view) {\n      setBox(null);\n      return;\n    }\n    let frame = 0;\n    let last = '';\n    const read = () => {\n      const rect = element.isConnected ? element.getBoundingClientRect() : null;\n      const next = rect ? { top: rect.top, left: rect.left, width: rect.width, height: rect.height } : null;\n      const signature = next\n        ? [next.top, next.left, next.width, next.height].map(Math.round).join(':')\n        : 'gone';\n      if (signature !== last) {\n        last = signature;\n        setBox(next);\n      }\n      frame = view.requestAnimationFrame(read);\n    };\n    read();\n    return () => view.cancelAnimationFrame(frame);\n  }, [element]);\n  return box;\n}\n\ninterface Viewport {\n  width: number;\n  height: number;\n}\n\nfunction viewportOf(doc: Document | null): Viewport {\n  const view = doc?.defaultView;\n  return { width: view?.innerWidth ?? 1024, height: view?.innerHeight ?? 768 };\n}\n\n/** Where a card anchored to an element sits: under it when there is room, else over it; at the bottom of the page without one. */\nexport function cardPosition({ box, viewport }: { box: Box | null; viewport: Viewport }): CSSProperties {\n  const width = Math.min(CARD_WIDTH_PX, viewport.width - EDGE_PX * 2);\n  if (!box) {\n    return { left: Math.max(EDGE_PX, (viewport.width - width) / 2), bottom: 24, width };\n  }\n  const left = Math.min(Math.max(box.left, EDGE_PX), Math.max(EDGE_PX, viewport.width - width - EDGE_PX));\n  const below = box.top + box.height + MARK_INSET_PX + CARD_GAP_PX;\n  if (below + CARD_ROOM_PX <= viewport.height || box.top < CARD_ROOM_PX) {\n    return { left, top: Math.min(below, Math.max(EDGE_PX, viewport.height - CARD_ROOM_PX)), width };\n  }\n  return { left, bottom: viewport.height - box.top + MARK_INSET_PX + CARD_GAP_PX, width };\n}\n\nconst TONE_CLASS: Record<AgentUiMarkTone, string> = {\n  point: 'border-primary ring-primary/25',\n  act: 'border-primary ring-primary/25 border-dashed',\n  ask: 'border-amber-500 ring-amber-500/25',\n};\n\nfunction Mark({\n  box,\n  tone,\n  spotlight,\n  leaving,\n  className,\n}: {\n  box: Box;\n  tone: AgentUiMarkTone;\n  spotlight: boolean;\n  leaving: boolean;\n  className?: string;\n}) {\n  return (\n    <div\n      data-testid=\"agent-ui-mark\"\n      data-tone={tone}\n      className={cn(\n        'pointer-events-none fixed rounded-lg border-2 ring-4 transition-opacity duration-500 motion-reduce:transition-none',\n        TONE_CLASS[tone],\n        spotlight && 'shadow-[0_0_0_100vmax_rgb(0_0_0/0.45)]',\n        leaving ? 'opacity-0' : 'opacity-100',\n        className,\n      )}\n      style={{\n        top: box.top - MARK_INSET_PX,\n        left: box.left - MARK_INSET_PX,\n        width: box.width + MARK_INSET_PX * 2,\n        height: box.height + MARK_INSET_PX * 2,\n      }}\n    />\n  );\n}\n\nfunction Card({\n  box,\n  viewport,\n  fit = false,\n  className,\n  children,\n  ...props\n}: {\n  box: Box | null;\n  viewport: Viewport;\n  /** As wide as its words need, up to a card's width (a note); otherwise a card's full width. */\n  fit?: boolean;\n  className?: string;\n  children: ReactNode;\n  role?: string;\n  'aria-label'?: string;\n  'data-testid'?: string;\n}) {\n  const { width, ...position } = cardPosition({ box, viewport });\n  return (\n    <div\n      {...props}\n      className={cn(\n        'pointer-events-auto fixed rounded-xl border border-border bg-popover px-3.5 py-3 text-popover-foreground text-sm shadow-lg',\n        className,\n      )}\n      style={fit ? { ...position, maxWidth: width } : { ...position, width }}\n    >\n      {children}\n    </div>\n  );\n}\n\nfunction Cursor({\n  box,\n  presses,\n  glideMs,\n  className,\n}: {\n  box: Box;\n  presses: number;\n  glideMs: number;\n  className?: string;\n}) {\n  const x = box.left + box.width / 2;\n  const y = box.top + box.height / 2;\n  // The cursor starts a little off the element and glides onto it.\n  const [arrived, setArrived] = useState(false);\n  useEffect(() => {\n    const frame = requestAnimationFrame(() => setArrived(true));\n    return () => cancelAnimationFrame(frame);\n  }, []);\n  return (\n    <div\n      data-testid=\"agent-ui-cursor\"\n      className={cn('pointer-events-none fixed top-0 left-0 motion-reduce:transition-none', className)}\n      style={{\n        transform: `translate(${arrived ? x : x + 48}px, ${arrived ? y : y + 48}px)`,\n        transitionProperty: 'transform',\n        transitionTimingFunction: 'ease-out',\n        transitionDuration: `${glideMs}ms`,\n      }}\n    >\n      <MousePointer2Icon className=\"size-5 fill-primary text-primary-foreground drop-shadow\" />\n      {presses > 0 ? (\n        <span\n          key={presses}\n          data-testid=\"agent-ui-press\"\n          className=\"-top-2 -left-2 absolute size-6 animate-ping rounded-full bg-primary/50 [animation-iteration-count:1]\"\n        />\n      ) : null}\n    </div>\n  );\n}\n\nfunction TourCard({\n  tour,\n  stage,\n  box,\n  viewport,\n  className,\n}: {\n  tour: AgentUiTour;\n  stage: AgentUiStage;\n  box: Box | null;\n  viewport: Viewport;\n  className?: string;\n}) {\n  const step = tour.steps[tour.index];\n  const last = tour.index >= tour.steps.length - 1;\n  const progressRef = useRef<HTMLDivElement>(null);\n  const advancing = tour.playing && !tour.searching;\n  const durationMs = step?.durationMs ?? 0;\n  // The bar fills over the step's time, so the person sees it will move on by itself.\n  // `tour.index` restarts it for a step of the same length.\n  // biome-ignore lint/correctness/useExhaustiveDependencies: a new step restarts the bar\n  useEffect(() => {\n    const bar = progressRef.current;\n    if (!bar || typeof bar.animate !== 'function') return;\n    if (!advancing) return;\n    const animation = bar.animate([{ width: '0%' }, { width: '100%' }], {\n      duration: durationMs,\n      fill: 'forwards',\n      easing: 'linear',\n    });\n    return () => animation.cancel();\n  }, [advancing, durationMs, tour.index]);\n  if (!step) return null;\n  return (\n    <Card\n      box={box}\n      viewport={viewport}\n      className={className}\n      role=\"dialog\"\n      aria-label={tour.title ?? 'Walkthrough'}\n      data-testid=\"agent-ui-tour\"\n    >\n      <div className=\"flex items-center justify-between gap-3\">\n        <p className=\"min-w-0 truncate text-muted-foreground text-xs\">\n          {tour.title ? `${tour.title} · ` : ''}\n          Step {tour.index + 1} of {tour.steps.length}\n        </p>\n        <button\n          type=\"button\"\n          aria-label=\"Close the walkthrough\"\n          onClick={() => stage.endTour()}\n          className=\"shrink-0 rounded-md p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground\"\n        >\n          <XIcon className=\"size-3.5\" />\n        </button>\n      </div>\n      <p className=\"break-words pt-1.5 leading-snug\" data-testid=\"agent-ui-tour-text\">\n        {step.text}\n      </p>\n      {!tour.searching && !tour.element ? (\n        <p className=\"pt-1 text-muted-foreground text-xs\">This one is not on the page you have open.</p>\n      ) : null}\n      <div className=\"mt-2.5 h-0.5 overflow-hidden rounded-full bg-muted\">\n        <div ref={progressRef} className=\"h-full w-0 bg-primary\" />\n      </div>\n      <div className=\"flex items-center gap-1 pt-2\">\n        <button\n          type=\"button\"\n          aria-label=\"Previous step\"\n          disabled={tour.index === 0}\n          onClick={() => stage.tourBack()}\n          className=\"rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40\"\n        >\n          <ChevronLeftIcon className=\"size-4\" />\n        </button>\n        <button\n          type=\"button\"\n          aria-label={tour.playing ? 'Pause the walkthrough' : 'Play the walkthrough'}\n          onClick={() => stage.tourTogglePlaying()}\n          className=\"rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground\"\n        >\n          {tour.playing ? <PauseIcon className=\"size-4\" /> : <PlayIcon className=\"size-4\" />}\n        </button>\n        <button\n          type=\"button\"\n          onClick={() => stage.tourNext()}\n          className=\"ml-auto flex items-center gap-1 rounded-md bg-primary px-2.5 py-1 font-medium text-primary-foreground text-xs transition-colors hover:bg-primary/90\"\n        >\n          {last ? 'Done' : 'Next'}\n          {last ? null : <ChevronRightIcon className=\"size-3.5\" />}\n        </button>\n      </div>\n    </Card>\n  );\n}\n\nfunction QuestionCard({\n  question,\n  stage,\n  box,\n  viewport,\n  className,\n}: {\n  question: AgentUiQuestion;\n  stage: AgentUiStage;\n  box: Box | null;\n  viewport: Viewport;\n  className?: string;\n}) {\n  return (\n    <Card\n      box={box}\n      viewport={viewport}\n      className={className}\n      role=\"alertdialog\"\n      aria-label={question.title}\n      data-testid=\"agent-ui-question\"\n    >\n      <p className=\"break-words font-semibold leading-snug\">{question.title}</p>\n      {question.body ? (\n        <p className=\"break-words pt-1 text-muted-foreground leading-snug\">{question.body}</p>\n      ) : null}\n      <div className=\"flex flex-wrap items-center gap-2 pt-2.5\">\n        <button\n          type=\"button\"\n          onClick={() => stage.answer(true)}\n          className=\"rounded-md bg-primary px-2.5 py-1 font-medium text-primary-foreground text-xs transition-colors hover:bg-primary/90\"\n        >\n          {question.allowLabel}\n        </button>\n        <button\n          type=\"button\"\n          onClick={() => stage.answer(false)}\n          className=\"rounded-md border border-border px-2.5 py-1 font-medium text-xs transition-colors hover:bg-muted\"\n        >\n          {question.declineLabel}\n        </button>\n      </div>\n    </Card>\n  );\n}\n\n/**\n * Draws the agent's stage over the page. Mount one per `AgentUi`, anywhere\n * under the provider; it portals to the document's body and takes no clicks\n * except on its own cards.\n */\nexport function AgentUiLayer({ agentUi, classNames }: AgentUiLayerProps) {\n  const { stage } = agentUi;\n  const state = useSyncExternalStore(stage.subscribe, stage.getState, stage.getState);\n  const ownerDocument = useOwnerDocument();\n  const portalContainer = usePortalContainer();\n  const themeStyle = useAthenaThemeStyle();\n\n  const tourElement = state.tour?.element ?? null;\n  const markedElement = state.tour ? tourElement : (state.mark?.element ?? null);\n  const markBox = useElementBox(markedElement);\n  const cursorBox = useElementBox(state.cursor?.element ?? null);\n  const questionBox = useElementBox(state.question?.element ?? null);\n\n  // Escape closes what the agent is showing: the person's page is theirs.\n  const showing = state.tour !== null || state.mark !== null;\n  useEffect(() => {\n    if (!showing || !ownerDocument) return;\n    const onKeyDown = (event: KeyboardEvent) => {\n      if (event.key !== 'Escape') return;\n      stage.endTour();\n      stage.clearMark();\n    };\n    ownerDocument.addEventListener('keydown', onKeyDown);\n    return () => ownerDocument.removeEventListener('keydown', onKeyDown);\n  }, [ownerDocument, showing, stage]);\n\n  const container = portalContainer ?? ownerDocument?.body;\n  if (!container) return null;\n  const idle = !state.mark && !state.cursor && !state.tour && !state.question;\n  if (idle) return null;\n  const viewport = viewportOf(ownerDocument);\n  const caption = state.tour ? null : (state.mark?.caption ?? null);\n\n  return createPortal(\n    <div\n      {...{ [AGENT_ATTR.layer]: '' }}\n      className=\"athena-sdk athena-sdk-chrome pointer-events-none fixed inset-0 z-[2147483000]\"\n      style={themeStyle as CSSProperties | undefined}\n    >\n      {markBox && (state.tour || state.mark) ? (\n        <Mark\n          box={markBox}\n          tone={state.tour ? 'point' : (state.mark?.tone ?? 'point')}\n          spotlight={state.tour ? false : (state.mark?.spotlight ?? false)}\n          leaving={state.tour ? false : (state.mark?.leaving ?? false)}\n          className={classNames?.mark}\n        />\n      ) : null}\n      {/* What the agent is doing, said aloud for a screen reader too. */}\n      <div aria-live=\"polite\">\n        {caption && markBox && !state.question ? (\n          <Card\n            box={markBox}\n            viewport={viewport}\n            fit\n            className={cn(\n              'pointer-events-none transition-opacity duration-500 motion-reduce:transition-none',\n              state.mark?.leaving ? 'opacity-0' : 'opacity-100',\n              classNames?.caption,\n            )}\n            data-testid=\"agent-ui-caption\"\n          >\n            <p className=\"break-words leading-snug\">{caption}</p>\n          </Card>\n        ) : null}\n      </div>\n      {state.tour ? (\n        <TourCard\n          tour={state.tour}\n          stage={stage}\n          box={markBox}\n          viewport={viewport}\n          className={classNames?.tour}\n        />\n      ) : null}\n      {state.question ? (\n        <QuestionCard\n          question={state.question}\n          stage={stage}\n          box={questionBox}\n          viewport={viewport}\n          className={classNames?.question}\n        />\n      ) : null}\n      {state.cursor && cursorBox ? (\n        <Cursor\n          box={cursorBox}\n          presses={state.cursor.presses}\n          glideMs={agentUi.pace().cursorGlideMs}\n          className={classNames?.cursor}\n        />\n      ) : null}\n    </div>,\n    container,\n  );\n}\n"],"names":[],"mappings":"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"}

package/dist/agent-ui/contract.cjs

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const AGENT_TARGET_ACTIONS = ["click", "type", "select", "toggle", "clear"];
+function isAgentTargetAction(value) {
+  return AGENT_TARGET_ACTIONS.some((action) => action === value);
+}
+const AGENT_ATTR = {
+  /** The target's id, stable across renders (`investors.search`). */
+  target: "data-agent-target",
+  /** Which one of several targets sharing an id (a row's key). */
+  key: "data-agent-key",
+  /** The name the person would call it. Falls back to the element's own accessible name. */
+  label: "data-agent-label",
+  /** One line for the agent on what it is for. */
+  description: "data-agent-description",
+  /** Space-separated actions the agent may take, or `none`. Derived from the element when absent. */
+  actions: "data-agent-actions",
+  /** Present: acting on it changes or destroys something, so the person confirms every time. */
+  danger: "data-agent-danger",
+  /** Present: its value is never read and never typed. */
+  sensitive: "data-agent-sensitive",
+  /** On a container: a named part of the screen its targets belong to. */
+  region: "data-agent-region",
+  /** Present on the overlay's own root: never a target, and input inside it is the overlay's. */
+  layer: "data-agent-ui-layer"
+};
+const TARGET_ID_PATTERN = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+const NO_PROPS = {};
+function isAgentTargetId(id) {
+  return id.length <= 80 && TARGET_ID_PATTERN.test(id);
+}
+function agentTarget(options) {
+  if (!isAgentTargetId(options.id)) {
+    console.error(
+      `agentTarget: "${options.id}" is not a target id, so the element is not a target. Use lowercase words joined by ".", "-" or "_" (e.g. "investors.search").`
+    );
+    return NO_PROPS;
+  }
+  const props = { [AGENT_ATTR.target]: options.id };
+  if (options.key !== void 0 && options.key !== "") props[AGENT_ATTR.key] = options.key;
+  if (options.label) props[AGENT_ATTR.label] = options.label;
+  if (options.description) props[AGENT_ATTR.description] = options.description;
+  if (options.actions) {
+    props[AGENT_ATTR.actions] = options.actions.length > 0 ? options.actions.join(" ") : "none";
+  }
+  if (options.danger) props[AGENT_ATTR.danger] = "";
+  if (options.sensitive) props[AGENT_ATTR.sensitive] = "";
+  return props;
+}
+function agentRegion({ id, label }) {
+  if (!isAgentTargetId(id)) {
+    console.error(`agentRegion: "${id}" is not a region id (e.g. "filters"), so the element names no region.`);
+    return NO_PROPS;
+  }
+  return label ? { [AGENT_ATTR.region]: id, [AGENT_ATTR.label]: label } : { [AGENT_ATTR.region]: id };
+}
+function agentTargetRef({ id, key }) {
+  return key ? `${id}[${key}]` : id;
+}
+function parseAgentTargetRef(ref) {
+  const text = ref.trim();
+  const match = /^([^[\]]+)(?:\[(.+)\])?$/.exec(text);
+  if (!(match == null ? void 0 : match[1])) return null;
+  return { id: match[1].trim(), key: match[2] ?? null };
+}
+const HANDLER_REGISTRY_KEY = Symbol.for("athena.agentUi.targetHandlers");
+function handlerRegistry() {
+  const holder = globalThis;
+  let registry = holder[HANDLER_REGISTRY_KEY];
+  if (!registry) {
+    registry = /* @__PURE__ */ new Map();
+    holder[HANDLER_REGISTRY_KEY] = registry;
+  }
+  return registry;
+}
+function registerAgentTargetHandlers({
+  ref,
+  handlers
+}) {
+  const registry = handlerRegistry();
+  if (registry.has(ref)) {
+    console.error(
+      `useAgentTarget: two mounted targets share "${ref}" and both register handlers. Give each its own key.`
+    );
+  }
+  registry.set(ref, handlers);
+  return () => {
+    if (registry.get(ref) === handlers) registry.delete(ref);
+  };
+}
+function agentTargetHandlers(ref) {
+  return handlerRegistry().get(ref);
+}
+exports.AGENT_ATTR = AGENT_ATTR;
+exports.AGENT_TARGET_ACTIONS = AGENT_TARGET_ACTIONS;
+exports.agentRegion = agentRegion;
+exports.agentTarget = agentTarget;
+exports.agentTargetHandlers = agentTargetHandlers;
+exports.agentTargetRef = agentTargetRef;
+exports.isAgentTargetAction = isAgentTargetAction;
+exports.isAgentTargetId = isAgentTargetId;
+exports.parseAgentTargetRef = parseAgentTargetRef;
+exports.registerAgentTargetHandlers = registerAgentTargetHandlers;
+//# sourceMappingURL=contract.cjs.map