@athenaintel/react 0.60.0 → 0.61.0

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"contract.cjs","sources":["../../src/agent-ui/contract.ts"],"sourcesContent":["/*\n * Agent targets: the elements of an app the agent may see, point at and\n * operate on the screen the person has open.\n *\n * The contract is a handful of `data-agent-*` attributes on the element\n * itself. The DOM is the registry: what is in the document is what is on\n * screen, list rows and third-party components need nothing special, and a\n * plain web component can take part without React. `agentTarget()` writes the\n * attributes with types; `useAgentTarget()` also registers handlers for a\n * control that ordinary clicks and typing cannot drive.\n *\n * The app decides what the agent can touch: an element without\n * `data-agent-target` does not exist for the agent, a target lists the actions\n * it allows, and one marked dangerous or sensitive is treated as such by every\n * tool. Nothing here is a permission boundary. The tools drive the same\n * handlers a click would, as the signed-in person.\n */\n\n/** What the agent may do to a target, beyond pointing at it. */\nexport const AGENT_TARGET_ACTIONS = ['click', 'type', 'select', 'toggle', 'clear'] as const;\nexport type AgentTargetAction = (typeof AGENT_TARGET_ACTIONS)[number];\n\nexport function isAgentTargetAction(value: unknown): value is AgentTargetAction {\n  return AGENT_TARGET_ACTIONS.some((action) => action === value);\n}\n\n/** The attribute names of the contract. */\nexport const AGENT_ATTR = {\n  /** The target's id, stable across renders (`investors.search`). */\n  target: 'data-agent-target',\n  /** Which one of several targets sharing an id (a row's key). */\n  key: 'data-agent-key',\n  /** The name the person would call it. Falls back to the element's own accessible name. */\n  label: 'data-agent-label',\n  /** One line for the agent on what it is for. */\n  description: 'data-agent-description',\n  /** Space-separated actions the agent may take, or `none`. Derived from the element when absent. */\n  actions: 'data-agent-actions',\n  /** Present: acting on it changes or destroys something, so the person confirms every time. */\n  danger: 'data-agent-danger',\n  /** Present: its value is never read and never typed. */\n  sensitive: 'data-agent-sensitive',\n  /** On a container: a named part of the screen its targets belong to. */\n  region: 'data-agent-region',\n  /** Present on the overlay's own root: never a target, and input inside it is the overlay's. */\n  layer: 'data-agent-ui-layer',\n} as const;\n\n/** What an app says about one target. */\nexport interface AgentTargetOptions {\n  /**\n   * The target's id: lowercase words joined by `.`, `-` or `_`\n   * (`investors.search`, `filters.stage`). Stable across renders and visits,\n   * since the agent names targets by it.\n   */\n  id: string;\n  /** Which one, when several targets share the id (a table row's key). */\n  key?: string;\n  /** The name a person would call it (\"Search investors\"). */\n  label?: string;\n  /** One line for the agent: what it is for, or what using it does. */\n  description?: string;\n  /**\n   * What the agent may do to it. Absent: what the element allows by its\n   * nature (a button is clicked, a text field typed into). An empty list: the\n   * agent may only point at it.\n   */\n  actions?: readonly AgentTargetAction[];\n  /** Acting on it changes or destroys something: the person confirms every time. */\n  danger?: boolean;\n  /** Its value is never read back to the agent and never typed by it. */\n  sensitive?: boolean;\n}\n\n/** The props an element takes to become a target. */\nexport type AgentTargetProps = Readonly<Record<string, string>>;\n\nconst TARGET_ID_PATTERN = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;\nconst NO_PROPS: AgentTargetProps = {};\n\n/** Whether `id` is a well-formed target id. */\nexport function isAgentTargetId(id: string): boolean {\n  return id.length <= 80 && TARGET_ID_PATTERN.test(id);\n}\n\n/**\n * The props that make an element an agent target. Spread them on the element\n * (any component that passes `data-*` props to its root works):\n *\n * ```tsx\n * <input {...agentTarget({ id: 'investors.search', label: 'Search investors' })} />\n * {rows.map((row) => (\n *   <tr key={row.id} {...agentTarget({ id: 'investors.row', key: row.id, label: row.name })} />\n * ))}\n * ```\n */\nexport function agentTarget(options: AgentTargetOptions): AgentTargetProps {\n  if (!isAgentTargetId(options.id)) {\n    // An id built from data must never take the page down with it: the\n    // element is simply not a target, and the console says why.\n    console.error(\n      `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\").`,\n    );\n    return NO_PROPS;\n  }\n  const props: Record<string, string> = { [AGENT_ATTR.target]: options.id };\n  if (options.key !== undefined && options.key !== '') props[AGENT_ATTR.key] = options.key;\n  if (options.label) props[AGENT_ATTR.label] = options.label;\n  if (options.description) props[AGENT_ATTR.description] = options.description;\n  if (options.actions) {\n    props[AGENT_ATTR.actions] = options.actions.length > 0 ? options.actions.join(' ') : 'none';\n  }\n  if (options.danger) props[AGENT_ATTR.danger] = '';\n  if (options.sensitive) props[AGENT_ATTR.sensitive] = '';\n  return props;\n}\n\n/** The props that name a part of the screen; targets inside it are grouped under it. */\nexport function agentRegion({ id, label }: { id: string; label?: string }): AgentTargetProps {\n  if (!isAgentTargetId(id)) {\n    console.error(`agentRegion: \"${id}\" is not a region id (e.g. \"filters\"), so the element names no region.`);\n    return NO_PROPS;\n  }\n  return label ? { [AGENT_ATTR.region]: id, [AGENT_ATTR.label]: label } : { [AGENT_ATTR.region]: id };\n}\n\n/** How the agent names one target: its id, with its key in brackets when it has one. */\nexport function agentTargetRef({ id, key }: { id: string; key?: string | null }): string {\n  return key ? `${id}[${key}]` : id;\n}\n\n/** A reference split into id and key; `null` when it is not one. */\nexport function parseAgentTargetRef(ref: string): { id: string; key: string | null } | null {\n  const text = ref.trim();\n  const match = /^([^[\\]]+)(?:\\[(.+)\\])?$/.exec(text);\n  if (!match?.[1]) return null;\n  return { id: match[1].trim(), key: match[2] ?? null };\n}\n\n/**\n * What a target does when ordinary input cannot drive it (a custom select, a\n * date picker, a canvas). A handler here replaces the tool's own click or\n * keystrokes for that action; it runs the app's own code, so validation and\n * undo apply as for a person.\n */\nexport interface AgentTargetHandlers {\n  click?: () => void | Promise<void>;\n  /** Called with the text so far as it is typed, then once more with `done: true`. */\n  type?: (args: { text: string; done: boolean }) => void | Promise<void>;\n  select?: (args: { option: string }) => void | Promise<void>;\n  toggle?: (args: { checked: boolean | null }) => void | Promise<void>;\n  clear?: () => void | Promise<void>;\n  /** The options a `select` may be given, when the element is not a native `<select>`. */\n  options?: () => readonly string[];\n  /** The target's current value, as the agent should read it. */\n  value?: () => string | null;\n}\n\nconst HANDLER_REGISTRY_KEY = Symbol.for('athena.agentUi.targetHandlers');\n\ntype HandlerRegistry = Map<string, AgentTargetHandlers>;\n\n/**\n * One registry per page, on `globalThis`: a host can carry more than one copy\n * of this module (the SDK bundles its own), and a handler registered through\n * one must be found by the tools of another.\n */\nfunction handlerRegistry(): HandlerRegistry {\n  const holder = globalThis as typeof globalThis & { [HANDLER_REGISTRY_KEY]?: HandlerRegistry };\n  let registry = holder[HANDLER_REGISTRY_KEY];\n  if (!registry) {\n    registry = new Map();\n    holder[HANDLER_REGISTRY_KEY] = registry;\n  }\n  return registry;\n}\n\n/** Register a target's handlers; returns the unregister function. */\nexport function registerAgentTargetHandlers({\n  ref,\n  handlers,\n}: {\n  ref: string;\n  handlers: AgentTargetHandlers;\n}): () => void {\n  const registry = handlerRegistry();\n  if (registry.has(ref)) {\n    // Handlers are found by reference: with two mounted targets sharing one,\n    // the agent would be shown one and run the other's.\n    console.error(\n      `useAgentTarget: two mounted targets share \"${ref}\" and both register handlers. Give each its own key.`,\n    );\n  }\n  registry.set(ref, handlers);\n  return () => {\n    if (registry.get(ref) === handlers) registry.delete(ref);\n  };\n}\n\n/** The handlers registered for a target reference, if any. */\nexport function agentTargetHandlers(ref: string): AgentTargetHandlers | undefined {\n  return handlerRegistry().get(ref);\n}\n"],"names":[],"mappings":";;AAmBO,MAAM,uBAAuB,CAAC,SAAS,QAAQ,UAAU,UAAU,OAAO;AAG1E,SAAS,oBAAoB,OAA4C;AAC9E,SAAO,qBAAqB,KAAK,CAAC,WAAW,WAAW,KAAK;AAC/D;AAGO,MAAM,aAAa;AAAA;AAAA,EAExB,QAAQ;AAAA;AAAA,EAER,KAAK;AAAA;AAAA,EAEL,OAAO;AAAA;AAAA,EAEP,aAAa;AAAA;AAAA,EAEb,SAAS;AAAA;AAAA,EAET,QAAQ;AAAA;AAAA,EAER,WAAW;AAAA;AAAA,EAEX,QAAQ;AAAA;AAAA,EAER,OAAO;AACT;AA+BA,MAAM,oBAAoB;AAC1B,MAAM,WAA6B,CAAA;AAG5B,SAAS,gBAAgB,IAAqB;AACnD,SAAO,GAAG,UAAU,MAAM,kBAAkB,KAAK,EAAE;AACrD;AAaO,SAAS,YAAY,SAA+C;AACzE,MAAI,CAAC,gBAAgB,QAAQ,EAAE,GAAG;AAGhC,YAAQ;AAAA,MACN,iBAAiB,QAAQ,EAAE;AAAA,IAAA;AAE7B,WAAO;AAAA,EACT;AACA,QAAM,QAAgC,EAAE,CAAC,WAAW,MAAM,GAAG,QAAQ,GAAA;AACrE,MAAI,QAAQ,QAAQ,UAAa,QAAQ,QAAQ,GAAI,OAAM,WAAW,GAAG,IAAI,QAAQ;AACrF,MAAI,QAAQ,MAAO,OAAM,WAAW,KAAK,IAAI,QAAQ;AACrD,MAAI,QAAQ,YAAa,OAAM,WAAW,WAAW,IAAI,QAAQ;AACjE,MAAI,QAAQ,SAAS;AACnB,UAAM,WAAW,OAAO,IAAI,QAAQ,QAAQ,SAAS,IAAI,QAAQ,QAAQ,KAAK,GAAG,IAAI;AAAA,EACvF;AACA,MAAI,QAAQ,OAAQ,OAAM,WAAW,MAAM,IAAI;AAC/C,MAAI,QAAQ,UAAW,OAAM,WAAW,SAAS,IAAI;AACrD,SAAO;AACT;AAGO,SAAS,YAAY,EAAE,IAAI,SAA2D;AAC3F,MAAI,CAAC,gBAAgB,EAAE,GAAG;AACxB,YAAQ,MAAM,iBAAiB,EAAE,wEAAwE;AACzG,WAAO;AAAA,EACT;AACA,SAAO,QAAQ,EAAE,CAAC,WAAW,MAAM,GAAG,IAAI,CAAC,WAAW,KAAK,GAAG,UAAU,EAAE,CAAC,WAAW,MAAM,GAAG,GAAA;AACjG;AAGO,SAAS,eAAe,EAAE,IAAI,OAAoD;AACvF,SAAO,MAAM,GAAG,EAAE,IAAI,GAAG,MAAM;AACjC;AAGO,SAAS,oBAAoB,KAAwD;AAC1F,QAAM,OAAO,IAAI,KAAA;AACjB,QAAM,QAAQ,2BAA2B,KAAK,IAAI;AAClD,MAAI,EAAC,+BAAQ,IAAI,QAAO;AACxB,SAAO,EAAE,IAAI,MAAM,CAAC,EAAE,QAAQ,KAAK,MAAM,CAAC,KAAK,KAAA;AACjD;AAqBA,MAAM,uBAAuB,OAAO,IAAI,+BAA+B;AASvE,SAAS,kBAAmC;AAC1C,QAAM,SAAS;AACf,MAAI,WAAW,OAAO,oBAAoB;AAC1C,MAAI,CAAC,UAAU;AACb,mCAAe,IAAA;AACf,WAAO,oBAAoB,IAAI;AAAA,EACjC;AACA,SAAO;AACT;AAGO,SAAS,4BAA4B;AAAA,EAC1C;AAAA,EACA;AACF,GAGe;AACb,QAAM,WAAW,gBAAA;AACjB,MAAI,SAAS,IAAI,GAAG,GAAG;AAGrB,YAAQ;AAAA,MACN,8CAA8C,GAAG;AAAA,IAAA;AAAA,EAErD;AACA,WAAS,IAAI,KAAK,QAAQ;AAC1B,SAAO,MAAM;AACX,QAAI,SAAS,IAAI,GAAG,MAAM,SAAU,UAAS,OAAO,GAAG;AAAA,EACzD;AACF;AAGO,SAAS,oBAAoB,KAA8C;AAChF,SAAO,gBAAA,EAAkB,IAAI,GAAG;AAClC;;;;;;;;;;;"}