@athenaintel/react 0.60.0 → 0.61.0

package/dist/agent-ui/secret-fields.js

@@ -0,0 +1,50 @@
+const SECRET_AUTOCOMPLETE_TOKENS = [
+  "current-password",
+  "new-password",
+  "one-time-code",
+  "cc-number",
+  "cc-csc"
+];
+const SECRET_LABEL_PATTERN_SOURCE = [
+  "\\b(?:password|passwd|passcode|passphrase|pwd|pin|otp|totp|cvv|cvc|csc|secret|token)\\d*\\b",
+  "\\bone time (?:code|password|passcode|pin)\\b",
+  "\\b(?:verification|security|authentication|authenticator|auth|2fa|mfa|sms) code\\b",
+  "\\b(?:api|access|secret|private) key\\b"
+].join("|");
+const SECRET_LABEL_PATTERN = new RegExp(SECRET_LABEL_PATTERN_SOURCE, "i");
+function normalizedFieldText(text) {
+  return text.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/[^A-Za-z0-9]+/g, " ").toLowerCase();
+}
+function isSecretFieldLabel(text) {
+  return SECRET_LABEL_PATTERN.test(normalizedFieldText(text));
+}
+function labelText(element) {
+  const own = element.labels;
+  const labels = own ? Array.from(own, (node) => node.textContent ?? "").join(" ") : "";
+  return [
+    element.getAttribute("aria-label"),
+    element.getAttribute("placeholder"),
+    element.getAttribute("name"),
+    element.id,
+    labels
+  ].join(" ");
+}
+function isSecretField(element) {
+  if (element.tagName.toUpperCase() === "INPUT" && (element.getAttribute("type") ?? "").toLowerCase() === "password") {
+    return true;
+  }
+  const hint = (element.getAttribute("autocomplete") ?? "").toLowerCase().split(/\s+/);
+  if (hint.some((token) => SECRET_AUTOCOMPLETE_TOKENS.includes(token))) return true;
+  const view = element.ownerDocument.defaultView;
+  const masking = view == null ? void 0 : view.getComputedStyle(element).getPropertyValue("-webkit-text-security");
+  if (masking && masking !== "none") return true;
+  return isSecretFieldLabel(labelText(element));
+}
+export {
+  SECRET_AUTOCOMPLETE_TOKENS,
+  SECRET_LABEL_PATTERN_SOURCE,
+  isSecretField,
+  isSecretFieldLabel,
+  normalizedFieldText
+};
+//# sourceMappingURL=secret-fields.js.map

package/dist/agent-ui/secret-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-fields.js","sources":["../../src/agent-ui/secret-fields.ts"],"sourcesContent":["/*\n * Fields whose value the agent never reads and never types: a password, a\n * one-time code, a card number or its security code.\n *\n * The rules are the ones Athena's browser tools apply to any web page\n * (`packages/browser-cdp/src/secret-fields.ts`, which this published package\n * cannot import); `secret-fields.test.ts` holds the two together.\n */\n\n/** `autocomplete` tokens that mark a field as holding a secret. */\nexport const SECRET_AUTOCOMPLETE_TOKENS: readonly string[] = [\n  'current-password',\n  'new-password',\n  'one-time-code',\n  'cc-number',\n  'cc-csc',\n];\n\n/** What a secret field's label, name, id or placeholder says. */\nexport const SECRET_LABEL_PATTERN_SOURCE = [\n  '\\\\b(?:password|passwd|passcode|passphrase|pwd|pin|otp|totp|cvv|cvc|csc|secret|token)\\\\d*\\\\b',\n  '\\\\bone time (?:code|password|passcode|pin)\\\\b',\n  '\\\\b(?:verification|security|authentication|authenticator|auth|2fa|mfa|sms) code\\\\b',\n  '\\\\b(?:api|access|secret|private) key\\\\b',\n].join('|');\n\nconst SECRET_LABEL_PATTERN = new RegExp(SECRET_LABEL_PATTERN_SOURCE, 'i');\n\n/** `text` as lower-case words: camelCase, runs of capitals and punctuation split. */\nexport function normalizedFieldText(text: string): string {\n  return text\n    .replace(/([a-z])([A-Z])/g, '$1 $2')\n    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')\n    .replace(/[^A-Za-z0-9]+/g, ' ')\n    .toLowerCase();\n}\n\n/** Whether a field's label, name, id or placeholder says it holds a secret. */\nexport function isSecretFieldLabel(text: string): boolean {\n  return SECRET_LABEL_PATTERN.test(normalizedFieldText(text));\n}\n\nfunction labelText(element: Element): string {\n  // Read structurally, never with `instanceof`: an element of another\n  // document (a popout, an iframe) is not an instance of this one's classes.\n  const own = (element as { labels?: ArrayLike<Element> | null }).labels;\n  const labels = own ? Array.from(own, (node) => node.textContent ?? '').join(' ') : '';\n  return [\n    element.getAttribute('aria-label'),\n    element.getAttribute('placeholder'),\n    element.getAttribute('name'),\n    element.id,\n    labels,\n  ].join(' ');\n}\n\n/**\n * Whether a form control holds a secret: a password input, an `autocomplete`\n * that names a password, a one-time code or a card number or code, a field\n * the page masks, or one whose label, name, id or placeholder says so (which\n * keeps a revealed password hidden, since a reveal toggle keeps the label).\n */\nexport function isSecretField(element: Element): boolean {\n  if (\n    element.tagName.toUpperCase() === 'INPUT' &&\n    (element.getAttribute('type') ?? '').toLowerCase() === 'password'\n  ) {\n    return true;\n  }\n  const hint = (element.getAttribute('autocomplete') ?? '').toLowerCase().split(/\\s+/);\n  if (hint.some((token) => SECRET_AUTOCOMPLETE_TOKENS.includes(token))) return true;\n  const view = element.ownerDocument.defaultView;\n  const masking = view?.getComputedStyle(element).getPropertyValue('-webkit-text-security');\n  if (masking && masking !== 'none') return true;\n  return isSecretFieldLabel(labelText(element));\n}\n"],"names":[],"mappings":"AAUO,MAAM,6BAAgD;AAAA,EAC3D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,MAAM,8BAA8B;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,EAAE,KAAK,GAAG;AAEV,MAAM,uBAAuB,IAAI,OAAO,6BAA6B,GAAG;AAGjE,SAAS,oBAAoB,MAAsB;AACxD,SAAO,KACJ,QAAQ,mBAAmB,OAAO,EAClC,QAAQ,yBAAyB,OAAO,EACxC,QAAQ,kBAAkB,GAAG,EAC7B,YAAA;AACL;AAGO,SAAS,mBAAmB,MAAuB;AACxD,SAAO,qBAAqB,KAAK,oBAAoB,IAAI,CAAC;AAC5D;AAEA,SAAS,UAAU,SAA0B;AAG3C,QAAM,MAAO,QAAmD;AAChE,QAAM,SAAS,MAAM,MAAM,KAAK,KAAK,CAAC,SAAS,KAAK,eAAe,EAAE,EAAE,KAAK,GAAG,IAAI;AACnF,SAAO;AAAA,IACL,QAAQ,aAAa,YAAY;AAAA,IACjC,QAAQ,aAAa,aAAa;AAAA,IAClC,QAAQ,aAAa,MAAM;AAAA,IAC3B,QAAQ;AAAA,IACR;AAAA,EAAA,EACA,KAAK,GAAG;AACZ;AAQO,SAAS,cAAc,SAA2B;AACvD,MACE,QAAQ,QAAQ,YAAA,MAAkB,YACjC,QAAQ,aAAa,MAAM,KAAK,IAAI,YAAA,MAAkB,YACvD;AACA,WAAO;AAAA,EACT;AACA,QAAM,QAAQ,QAAQ,aAAa,cAAc,KAAK,IAAI,YAAA,EAAc,MAAM,KAAK;AACnF,MAAI,KAAK,KAAK,CAAC,UAAU,2BAA2B,SAAS,KAAK,CAAC,EAAG,QAAO;AAC7E,QAAM,OAAO,QAAQ,cAAc;AACnC,QAAM,UAAU,6BAAM,iBAAiB,SAAS,iBAAiB;AACjE,MAAI,WAAW,YAAY,OAAQ,QAAO;AAC1C,SAAO,mBAAmB,UAAU,OAAO,CAAC;AAC9C;"}

package/dist/agent-ui/stage.cjs

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const pace = require("./pace.cjs");
+const screen = require("./screen.cjs");
+const EMPTY = { mark: null, cursor: null, tour: null, question: null };
+function tourStep({
+  target,
+  text,
+  seconds
+}) {
+  const trimmed = text.trim();
+  return { target: target.trim(), text: trimmed, durationMs: pace.stepDurationMs({ text: trimmed, seconds }) };
+}
+function createAgentUiStage({
+  pace: pace$1,
+  findStepElementNow,
+  findStepElement,
+  reveal
+}) {
+  let state = EMPTY;
+  const listeners = /* @__PURE__ */ new Set();
+  let markTimer;
+  let fadeTimer;
+  let tourTimer;
+  let tourSearch = null;
+  let resolveQuestion = null;
+  const set = (next) => {
+    state = { ...state, ...next };
+    for (const listener of Array.from(listeners)) listener();
+  };
+  const stopMarkTimers = () => {
+    if (markTimer !== void 0) clearTimeout(markTimer);
+    if (fadeTimer !== void 0) clearTimeout(fadeTimer);
+    markTimer = void 0;
+    fadeTimer = void 0;
+  };
+  const clearMark = () => {
+    stopMarkTimers();
+    const mark = state.mark;
+    if (!mark) return;
+    const fadeMs = pace$1().fadeMs;
+    if (fadeMs <= 0) {
+      set({ mark: null });
+      return;
+    }
+    set({ mark: { ...mark, leaving: true } });
+    fadeTimer = setTimeout(() => {
+      var _a;
+      fadeTimer = void 0;
+      if ((_a = state.mark) == null ? void 0 : _a.leaving) set({ mark: null });
+    }, fadeMs);
+  };
+  const stopTourTimers = () => {
+    if (tourTimer !== void 0) clearTimeout(tourTimer);
+    tourTimer = void 0;
+    tourSearch == null ? void 0 : tourSearch.abort();
+    tourSearch = null;
+  };
+  const endTour = () => {
+    stopTourTimers();
+    if (state.tour) set({ tour: null });
+  };
+  const scheduleAdvance = () => {
+    if (tourTimer !== void 0) clearTimeout(tourTimer);
+    tourTimer = void 0;
+    const tour = state.tour;
+    if (!(tour == null ? void 0 : tour.playing) || tour.searching) return;
+    const step = tour.steps[tour.index];
+    if (!step) return;
+    tourTimer = setTimeout(() => {
+      tourTimer = void 0;
+      const current = state.tour;
+      if (!(current == null ? void 0 : current.playing)) return;
+      if (current.index >= current.steps.length - 1) endTour();
+      else void showStep(current.index + 1);
+    }, step.durationMs);
+  };
+  const showStep = async (index) => {
+    const tour = state.tour;
+    const step = tour == null ? void 0 : tour.steps[index];
+    if (!tour || !step) return;
+    stopTourTimers();
+    const present = findStepElementNow(step.target);
+    if (present && screen.isInViewport(present)) {
+      set({ tour: { ...tour, index, element: present, searching: false } });
+      scheduleAdvance();
+      return;
+    }
+    const search = new AbortController();
+    tourSearch = search;
+    set({ tour: { ...tour, index, element: present, searching: true } });
+    let element = present;
+    try {
+      element ?? (element = await findStepElement({ target: step.target, signal: search.signal }));
+      if (element && !search.signal.aborted && !screen.isInViewport(element)) {
+        await reveal({ element, signal: search.signal });
+      }
+    } catch {
+      element = null;
+    }
+    if (search.signal.aborted || tourSearch !== search) return;
+    tourSearch = null;
+    const current = state.tour;
+    if (!current) return;
+    set({ tour: { ...current, index, element, searching: false } });
+    scheduleAdvance();
+  };
+  const answer = (allow) => {
+    const resolve = resolveQuestion;
+    resolveQuestion = null;
+    if (state.question) set({ question: null });
+    resolve == null ? void 0 : resolve(allow);
+  };
+  return {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    mark({ element, tone, caption = null, spotlight = false, durationMs }) {
+      stopMarkTimers();
+      set({ mark: { element, tone, caption, spotlight, leaving: false } });
+      if (durationMs !== void 0) {
+        markTimer = setTimeout(() => {
+          markTimer = void 0;
+          clearMark();
+        }, durationMs);
+      }
+    },
+    clearMark,
+    async cursorTo({ element, signal }) {
+      var _a;
+      set({ cursor: { element, presses: ((_a = state.cursor) == null ? void 0 : _a.presses) ?? 0 } });
+      await pace.pause(pace$1().cursorGlideMs, signal);
+    },
+    press() {
+      if (state.cursor) set({ cursor: { ...state.cursor, presses: state.cursor.presses + 1 } });
+    },
+    hideCursor() {
+      if (state.cursor) set({ cursor: null });
+    },
+    ask(question) {
+      answer(false);
+      return new Promise((resolve) => {
+        resolveQuestion = resolve;
+        set({ question });
+      });
+    },
+    answer,
+    startTour({ title, steps }) {
+      stopMarkTimers();
+      stopTourTimers();
+      state = {
+        ...state,
+        mark: null,
+        cursor: null,
+        tour: { title, steps, index: 0, playing: true, element: null, searching: true }
+      };
+      void showStep(0);
+    },
+    tourNext() {
+      const tour = state.tour;
+      if (!tour) return;
+      if (tour.index >= tour.steps.length - 1) endTour();
+      else void showStep(tour.index + 1);
+    },
+    tourBack() {
+      const tour = state.tour;
+      if (tour && tour.index > 0) void showStep(tour.index - 1);
+    },
+    tourTogglePlaying() {
+      const tour = state.tour;
+      if (!tour) return;
+      set({ tour: { ...tour, playing: !tour.playing } });
+      if (tour.playing) {
+        if (tourTimer !== void 0) clearTimeout(tourTimer);
+        tourTimer = void 0;
+      } else {
+        scheduleAdvance();
+      }
+    },
+    endTour,
+    clear() {
+      stopMarkTimers();
+      stopTourTimers();
+      answer(false);
+      state = EMPTY;
+      for (const listener of Array.from(listeners)) listener();
+    }
+  };
+}
+exports.createAgentUiStage = createAgentUiStage;
+exports.tourStep = tourStep;
+//# sourceMappingURL=stage.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stage.cjs","sources":["../../src/agent-ui/stage.ts"],"sourcesContent":["/*\n * The stage: what the overlay is showing right now. A mark around an element\n * with its caption, the agent's cursor, a walkthrough, a question to the\n * person. The tools write it, `AgentUiLayer` draws it, and nothing here\n * touches the page: the stage only holds which element is marked and for how\n * long.\n *\n * Framework-free, so a host without React can draw it too.\n */\n\nimport { type AgentUiPace, pause, stepDurationMs } from './pace';\nimport { isInViewport } from './screen';\n\n/** Why the mark is on an element: the agent is showing it, operating it, or asking about it. */\nexport type AgentUiMarkTone = 'point' | 'act' | 'ask';\n\nexport interface AgentUiMark {\n  element: Element;\n  tone: AgentUiMarkTone;\n  /** Dim the rest of the page. */\n  spotlight: boolean;\n  /** The words shown beside the element. */\n  caption: string | null;\n  /** Fading out. */\n  leaving: boolean;\n}\n\nexport interface AgentUiCursor {\n  /** The element the cursor rests on. */\n  element: Element;\n  /** Counts presses, so the layer plays one ripple per click. */\n  presses: number;\n}\n\nexport interface AgentUiTourStep {\n  /** The target the step is about, as the agent named it. */\n  target: string;\n  text: string;\n  /** How long the step stays before the next one plays. */\n  durationMs: number;\n}\n\nexport interface AgentUiTour {\n  title: string | null;\n  steps: readonly AgentUiTourStep[];\n  index: number;\n  /** Advancing by itself; false while the person paused it. */\n  playing: boolean;\n  /** The current step's element, or `null` when its target is not on this page. */\n  element: Element | null;\n  /** The current step is still looking for its target. */\n  searching: boolean;\n}\n\nexport interface AgentUiQuestion {\n  /** The element the question is about, if it is on screen. */\n  element: Element | null;\n  title: string;\n  body: string | null;\n  allowLabel: string;\n  declineLabel: string;\n}\n\nexport interface AgentUiStageState {\n  mark: AgentUiMark | null;\n  cursor: AgentUiCursor | null;\n  tour: AgentUiTour | null;\n  question: AgentUiQuestion | null;\n}\n\nconst EMPTY: AgentUiStageState = { mark: null, cursor: null, tour: null, question: null };\n\nexport interface AgentUiStage {\n  getState(): AgentUiStageState;\n  subscribe(listener: () => void): () => void;\n\n  /** Mark an element. `durationMs` clears it after that long; without one it stays until replaced. */\n  mark(args: {\n    element: Element;\n    tone: AgentUiMarkTone;\n    caption?: string | null;\n    spotlight?: boolean;\n    durationMs?: number;\n  }): void;\n  /** Fade the mark out. */\n  clearMark(): void;\n\n  /** Move the agent's cursor onto an element; resolves when it has arrived. */\n  cursorTo(args: { element: Element; signal?: AbortSignal }): Promise<void>;\n  /** Show a click where the cursor is. */\n  press(): void;\n  hideCursor(): void;\n\n  /** Ask the person; resolves `true` on allow. A new question declines the one before it. */\n  ask(question: AgentUiQuestion): Promise<boolean>;\n  answer(allow: boolean): void;\n\n  /** Play a walkthrough; replaces whatever the stage showed. */\n  startTour(args: { title: string | null; steps: readonly AgentUiTourStep[] }): void;\n  tourNext(): void;\n  tourBack(): void;\n  tourTogglePlaying(): void;\n  endTour(): void;\n\n  /** Take everything off the page at once. */\n  clear(): void;\n}\n\nexport interface CreateAgentUiStageOptions {\n  /** The pace in force now (read per use, so a host can change speed live). */\n  pace: () => AgentUiPace;\n  /** A step's element if it is on the page right now. */\n  findStepElementNow: (target: string) => Element | null;\n  /** Find a step's element, waiting for a page that is still loading; `null` when it is not there. */\n  findStepElement: (args: { target: string; signal: AbortSignal }) => Promise<Element | null>;\n  /** Bring an element into view. */\n  reveal: (args: { element: Element; signal?: AbortSignal }) => Promise<void>;\n}\n\n/** Normalise a walkthrough's steps: its text trimmed, its duration set. */\nexport function tourStep({\n  target,\n  text,\n  seconds,\n}: {\n  target: string;\n  text: string;\n  seconds?: number;\n}): AgentUiTourStep {\n  const trimmed = text.trim();\n  return { target: target.trim(), text: trimmed, durationMs: stepDurationMs({ text: trimmed, seconds }) };\n}\n\nexport function createAgentUiStage({\n  pace,\n  findStepElementNow,\n  findStepElement,\n  reveal,\n}: CreateAgentUiStageOptions): AgentUiStage {\n  let state: AgentUiStageState = EMPTY;\n  const listeners = new Set<() => void>();\n  let markTimer: ReturnType<typeof setTimeout> | undefined;\n  let fadeTimer: ReturnType<typeof setTimeout> | undefined;\n  let tourTimer: ReturnType<typeof setTimeout> | undefined;\n  let tourSearch: AbortController | null = null;\n  let resolveQuestion: ((allow: boolean) => void) | null = null;\n\n  const set = (next: Partial<AgentUiStageState>) => {\n    state = { ...state, ...next };\n    for (const listener of Array.from(listeners)) listener();\n  };\n\n  const stopMarkTimers = () => {\n    if (markTimer !== undefined) clearTimeout(markTimer);\n    if (fadeTimer !== undefined) clearTimeout(fadeTimer);\n    markTimer = undefined;\n    fadeTimer = undefined;\n  };\n\n  const clearMark = () => {\n    stopMarkTimers();\n    const mark = state.mark;\n    if (!mark) return;\n    const fadeMs = pace().fadeMs;\n    if (fadeMs <= 0) {\n      set({ mark: null });\n      return;\n    }\n    set({ mark: { ...mark, leaving: true } });\n    fadeTimer = setTimeout(() => {\n      fadeTimer = undefined;\n      if (state.mark?.leaving) set({ mark: null });\n    }, fadeMs);\n  };\n\n  const stopTourTimers = () => {\n    if (tourTimer !== undefined) clearTimeout(tourTimer);\n    tourTimer = undefined;\n    tourSearch?.abort();\n    tourSearch = null;\n  };\n\n  const endTour = () => {\n    stopTourTimers();\n    if (state.tour) set({ tour: null });\n  };\n\n  const scheduleAdvance = () => {\n    if (tourTimer !== undefined) clearTimeout(tourTimer);\n    tourTimer = undefined;\n    const tour = state.tour;\n    if (!tour?.playing || tour.searching) return;\n    const step = tour.steps[tour.index];\n    if (!step) return;\n    tourTimer = setTimeout(() => {\n      tourTimer = undefined;\n      const current = state.tour;\n      if (!current?.playing) return;\n      if (current.index >= current.steps.length - 1) endTour();\n      else void showStep(current.index + 1);\n    }, step.durationMs);\n  };\n\n  const showStep = async (index: number): Promise<void> => {\n    const tour = state.tour;\n    const step = tour?.steps[index];\n    if (!tour || !step) return;\n    stopTourTimers();\n    // The usual step is on the page and in view: move to it in one update, so\n    // the card goes straight from one element to the next.\n    const present = findStepElementNow(step.target);\n    if (present && isInViewport(present)) {\n      set({ tour: { ...tour, index, element: present, searching: false } });\n      scheduleAdvance();\n      return;\n    }\n    const search = new AbortController();\n    tourSearch = search;\n    set({ tour: { ...tour, index, element: present, searching: true } });\n    let element: Element | null = present;\n    try {\n      element ??= await findStepElement({ target: step.target, signal: search.signal });\n      if (element && !search.signal.aborted && !isInViewport(element)) {\n        await reveal({ element, signal: search.signal });\n      }\n    } catch {\n      element = null;\n    }\n    // Another step, or the end of the walkthrough, took over while this one looked.\n    if (search.signal.aborted || tourSearch !== search) return;\n    tourSearch = null;\n    const current = state.tour;\n    if (!current) return;\n    set({ tour: { ...current, index, element, searching: false } });\n    scheduleAdvance();\n  };\n\n  const answer = (allow: boolean) => {\n    const resolve = resolveQuestion;\n    resolveQuestion = null;\n    if (state.question) set({ question: null });\n    resolve?.(allow);\n  };\n\n  return {\n    getState: () => state,\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n\n    mark({ element, tone, caption = null, spotlight = false, durationMs }) {\n      stopMarkTimers();\n      set({ mark: { element, tone, caption, spotlight, leaving: false } });\n      if (durationMs !== undefined) {\n        markTimer = setTimeout(() => {\n          markTimer = undefined;\n          clearMark();\n        }, durationMs);\n      }\n    },\n    clearMark,\n\n    async cursorTo({ element, signal }) {\n      set({ cursor: { element, presses: state.cursor?.presses ?? 0 } });\n      await pause(pace().cursorGlideMs, signal);\n    },\n    press() {\n      if (state.cursor) set({ cursor: { ...state.cursor, presses: state.cursor.presses + 1 } });\n    },\n    hideCursor() {\n      if (state.cursor) set({ cursor: null });\n    },\n\n    ask(question) {\n      answer(false);\n      return new Promise<boolean>((resolve) => {\n        resolveQuestion = resolve;\n        set({ question });\n      });\n    },\n    answer,\n\n    startTour({ title, steps }) {\n      stopMarkTimers();\n      stopTourTimers();\n      // Published by `showStep` with the first step's element, in one update.\n      state = {\n        ...state,\n        mark: null,\n        cursor: null,\n        tour: { title, steps, index: 0, playing: true, element: null, searching: true },\n      };\n      void showStep(0);\n    },\n    tourNext() {\n      const tour = state.tour;\n      if (!tour) return;\n      if (tour.index >= tour.steps.length - 1) endTour();\n      else void showStep(tour.index + 1);\n    },\n    tourBack() {\n      const tour = state.tour;\n      if (tour && tour.index > 0) void showStep(tour.index - 1);\n    },\n    tourTogglePlaying() {\n      const tour = state.tour;\n      if (!tour) return;\n      set({ tour: { ...tour, playing: !tour.playing } });\n      if (tour.playing) {\n        if (tourTimer !== undefined) clearTimeout(tourTimer);\n        tourTimer = undefined;\n      } else {\n        scheduleAdvance();\n      }\n    },\n    endTour,\n\n    clear() {\n      stopMarkTimers();\n      stopTourTimers();\n      answer(false);\n      state = EMPTY;\n      for (const listener of Array.from(listeners)) listener();\n    },\n  };\n}\n"],"names":["stepDurationMs","pace","isInViewport","pause"],"mappings":";;;;AAsEA,MAAM,QAA2B,EAAE,MAAM,MAAM,QAAQ,MAAM,MAAM,MAAM,UAAU,KAAA;AAkD5E,SAAS,SAAS;AAAA,EACvB;AAAA,EACA;AAAA,EACA;AACF,GAIoB;AAClB,QAAM,UAAU,KAAK,KAAA;AACrB,SAAO,EAAE,QAAQ,OAAO,KAAA,GAAQ,MAAM,SAAS,YAAYA,KAAAA,eAAe,EAAE,MAAM,SAAS,QAAA,CAAS,EAAA;AACtG;AAEO,SAAS,mBAAmB;AAAA,EAAA,MACjCC;AAAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAA4C;AAC1C,MAAI,QAA2B;AAC/B,QAAM,gCAAgB,IAAA;AACtB,MAAI;AACJ,MAAI;AACJ,MAAI;AACJ,MAAI,aAAqC;AACzC,MAAI,kBAAqD;AAEzD,QAAM,MAAM,CAAC,SAAqC;AAChD,YAAQ,EAAE,GAAG,OAAO,GAAG,KAAA;AACvB,eAAW,YAAY,MAAM,KAAK,SAAS,EAAG,UAAA;AAAA,EAChD;AAEA,QAAM,iBAAiB,MAAM;AAC3B,QAAI,cAAc,OAAW,cAAa,SAAS;AACnD,QAAI,cAAc,OAAW,cAAa,SAAS;AACnD,gBAAY;AACZ,gBAAY;AAAA,EACd;AAEA,QAAM,YAAY,MAAM;AACtB,mBAAA;AACA,UAAM,OAAO,MAAM;AACnB,QAAI,CAAC,KAAM;AACX,UAAM,SAASA,SAAO;AACtB,QAAI,UAAU,GAAG;AACf,UAAI,EAAE,MAAM,MAAM;AAClB;AAAA,IACF;AACA,QAAI,EAAE,MAAM,EAAE,GAAG,MAAM,SAAS,KAAA,GAAQ;AACxC,gBAAY,WAAW,MAAM;;AAC3B,kBAAY;AACZ,WAAI,WAAM,SAAN,mBAAY,aAAa,EAAE,MAAM,MAAM;AAAA,IAC7C,GAAG,MAAM;AAAA,EACX;AAEA,QAAM,iBAAiB,MAAM;AAC3B,QAAI,cAAc,OAAW,cAAa,SAAS;AACnD,gBAAY;AACZ,6CAAY;AACZ,iBAAa;AAAA,EACf;AAEA,QAAM,UAAU,MAAM;AACpB,mBAAA;AACA,QAAI,MAAM,KAAM,KAAI,EAAE,MAAM,MAAM;AAAA,EACpC;AAEA,QAAM,kBAAkB,MAAM;AAC5B,QAAI,cAAc,OAAW,cAAa,SAAS;AACnD,gBAAY;AACZ,UAAM,OAAO,MAAM;AACnB,QAAI,EAAC,6BAAM,YAAW,KAAK,UAAW;AACtC,UAAM,OAAO,KAAK,MAAM,KAAK,KAAK;AAClC,QAAI,CAAC,KAAM;AACX,gBAAY,WAAW,MAAM;AAC3B,kBAAY;AACZ,YAAM,UAAU,MAAM;AACtB,UAAI,EAAC,mCAAS,SAAS;AACvB,UAAI,QAAQ,SAAS,QAAQ,MAAM,SAAS,EAAG,SAAA;AAAA,UAC1C,MAAK,SAAS,QAAQ,QAAQ,CAAC;AAAA,IACtC,GAAG,KAAK,UAAU;AAAA,EACpB;AAEA,QAAM,WAAW,OAAO,UAAiC;AACvD,UAAM,OAAO,MAAM;AACnB,UAAM,OAAO,6BAAM,MAAM;AACzB,QAAI,CAAC,QAAQ,CAAC,KAAM;AACpB,mBAAA;AAGA,UAAM,UAAU,mBAAmB,KAAK,MAAM;AAC9C,QAAI,WAAWC,oBAAa,OAAO,GAAG;AACpC,UAAI,EAAE,MAAM,EAAE,GAAG,MAAM,OAAO,SAAS,SAAS,WAAW,MAAA,GAAS;AACpE,sBAAA;AACA;AAAA,IACF;AACA,UAAM,SAAS,IAAI,gBAAA;AACnB,iBAAa;AACb,QAAI,EAAE,MAAM,EAAE,GAAG,MAAM,OAAO,SAAS,SAAS,WAAW,KAAA,GAAQ;AACnE,QAAI,UAA0B;AAC9B,QAAI;AACF,4BAAY,MAAM,gBAAgB,EAAE,QAAQ,KAAK,QAAQ,QAAQ,OAAO,QAAQ;AAChF,UAAI,WAAW,CAAC,OAAO,OAAO,WAAW,CAACA,OAAAA,aAAa,OAAO,GAAG;AAC/D,cAAM,OAAO,EAAE,SAAS,QAAQ,OAAO,QAAQ;AAAA,MACjD;AAAA,IACF,QAAQ;AACN,gBAAU;AAAA,IACZ;AAEA,QAAI,OAAO,OAAO,WAAW,eAAe,OAAQ;AACpD,iBAAa;AACb,UAAM,UAAU,MAAM;AACtB,QAAI,CAAC,QAAS;AACd,QAAI,EAAE,MAAM,EAAE,GAAG,SAAS,OAAO,SAAS,WAAW,MAAA,GAAS;AAC9D,oBAAA;AAAA,EACF;AAEA,QAAM,SAAS,CAAC,UAAmB;AACjC,UAAM,UAAU;AAChB,sBAAkB;AAClB,QAAI,MAAM,SAAU,KAAI,EAAE,UAAU,MAAM;AAC1C,uCAAU;AAAA,EACZ;AAEA,SAAO;AAAA,IACL,UAAU,MAAM;AAAA,IAChB,UAAU,UAAU;AAClB,gBAAU,IAAI,QAAQ;AACtB,aAAO,MAAM;AACX,kBAAU,OAAO,QAAQ;AAAA,MAC3B;AAAA,IACF;AAAA,IAEA,KAAK,EAAE,SAAS,MAAM,UAAU,MAAM,YAAY,OAAO,cAAc;AACrE,qBAAA;AACA,UAAI,EAAE,MAAM,EAAE,SAAS,MAAM,SAAS,WAAW,SAAS,MAAA,GAAS;AACnE,UAAI,eAAe,QAAW;AAC5B,oBAAY,WAAW,MAAM;AAC3B,sBAAY;AACZ,oBAAA;AAAA,QACF,GAAG,UAAU;AAAA,MACf;AAAA,IACF;AAAA,IACA;AAAA,IAEA,MAAM,SAAS,EAAE,SAAS,UAAU;;AAClC,UAAI,EAAE,QAAQ,EAAE,SAAS,WAAS,WAAM,WAAN,mBAAc,YAAW,EAAA,GAAK;AAChE,YAAMC,WAAMF,SAAO,eAAe,MAAM;AAAA,IAC1C;AAAA,IACA,QAAQ;AACN,UAAI,MAAM,OAAQ,KAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,QAAQ,SAAS,MAAM,OAAO,UAAU,EAAA,GAAK;AAAA,IAC1F;AAAA,IACA,aAAa;AACX,UAAI,MAAM,OAAQ,KAAI,EAAE,QAAQ,MAAM;AAAA,IACxC;AAAA,IAEA,IAAI,UAAU;AACZ,aAAO,KAAK;AACZ,aAAO,IAAI,QAAiB,CAAC,YAAY;AACvC,0BAAkB;AAClB,YAAI,EAAE,UAAU;AAAA,MAClB,CAAC;AAAA,IACH;AAAA,IACA;AAAA,IAEA,UAAU,EAAE,OAAO,SAAS;AAC1B,qBAAA;AACA,qBAAA;AAEA,cAAQ;AAAA,QACN,GAAG;AAAA,QACH,MAAM;AAAA,QACN,QAAQ;AAAA,QACR,MAAM,EAAE,OAAO,OAAO,OAAO,GAAG,SAAS,MAAM,SAAS,MAAM,WAAW,KAAA;AAAA,MAAK;AAEhF,WAAK,SAAS,CAAC;AAAA,IACjB;AAAA,IACA,WAAW;AACT,YAAM,OAAO,MAAM;AACnB,UAAI,CAAC,KAAM;AACX,UAAI,KAAK,SAAS,KAAK,MAAM,SAAS,EAAG,SAAA;AAAA,UACpC,MAAK,SAAS,KAAK,QAAQ,CAAC;AAAA,IACnC;AAAA,IACA,WAAW;AACT,YAAM,OAAO,MAAM;AACnB,UAAI,QAAQ,KAAK,QAAQ,QAAQ,SAAS,KAAK,QAAQ,CAAC;AAAA,IAC1D;AAAA,IACA,oBAAoB;AAClB,YAAM,OAAO,MAAM;AACnB,UAAI,CAAC,KAAM;AACX,UAAI,EAAE,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,QAAA,GAAW;AACjD,UAAI,KAAK,SAAS;AAChB,YAAI,cAAc,OAAW,cAAa,SAAS;AACnD,oBAAY;AAAA,MACd,OAAO;AACL,wBAAA;AAAA,MACF;AAAA,IACF;AAAA,IACA;AAAA,IAEA,QAAQ;AACN,qBAAA;AACA,qBAAA;AACA,aAAO,KAAK;AACZ,cAAQ;AACR,iBAAW,YAAY,MAAM,KAAK,SAAS,EAAG,UAAA;AAAA,IAChD;AAAA,EAAA;AAEJ;;;"}

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

@@ -0,0 +1,110 @@
+import { type AgentUiPace } from './pace';
+/** Why the mark is on an element: the agent is showing it, operating it, or asking about it. */
+export type AgentUiMarkTone = 'point' | 'act' | 'ask';
+export interface AgentUiMark {
+    element: Element;
+    tone: AgentUiMarkTone;
+    /** Dim the rest of the page. */
+    spotlight: boolean;
+    /** The words shown beside the element. */
+    caption: string | null;
+    /** Fading out. */
+    leaving: boolean;
+}
+export interface AgentUiCursor {
+    /** The element the cursor rests on. */
+    element: Element;
+    /** Counts presses, so the layer plays one ripple per click. */
+    presses: number;
+}
+export interface AgentUiTourStep {
+    /** The target the step is about, as the agent named it. */
+    target: string;
+    text: string;
+    /** How long the step stays before the next one plays. */
+    durationMs: number;
+}
+export interface AgentUiTour {
+    title: string | null;
+    steps: readonly AgentUiTourStep[];
+    index: number;
+    /** Advancing by itself; false while the person paused it. */
+    playing: boolean;
+    /** The current step's element, or `null` when its target is not on this page. */
+    element: Element | null;
+    /** The current step is still looking for its target. */
+    searching: boolean;
+}
+export interface AgentUiQuestion {
+    /** The element the question is about, if it is on screen. */
+    element: Element | null;
+    title: string;
+    body: string | null;
+    allowLabel: string;
+    declineLabel: string;
+}
+export interface AgentUiStageState {
+    mark: AgentUiMark | null;
+    cursor: AgentUiCursor | null;
+    tour: AgentUiTour | null;
+    question: AgentUiQuestion | null;
+}
+export interface AgentUiStage {
+    getState(): AgentUiStageState;
+    subscribe(listener: () => void): () => void;
+    /** Mark an element. `durationMs` clears it after that long; without one it stays until replaced. */
+    mark(args: {
+        element: Element;
+        tone: AgentUiMarkTone;
+        caption?: string | null;
+        spotlight?: boolean;
+        durationMs?: number;
+    }): void;
+    /** Fade the mark out. */
+    clearMark(): void;
+    /** Move the agent's cursor onto an element; resolves when it has arrived. */
+    cursorTo(args: {
+        element: Element;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Show a click where the cursor is. */
+    press(): void;
+    hideCursor(): void;
+    /** Ask the person; resolves `true` on allow. A new question declines the one before it. */
+    ask(question: AgentUiQuestion): Promise<boolean>;
+    answer(allow: boolean): void;
+    /** Play a walkthrough; replaces whatever the stage showed. */
+    startTour(args: {
+        title: string | null;
+        steps: readonly AgentUiTourStep[];
+    }): void;
+    tourNext(): void;
+    tourBack(): void;
+    tourTogglePlaying(): void;
+    endTour(): void;
+    /** Take everything off the page at once. */
+    clear(): void;
+}
+export interface CreateAgentUiStageOptions {
+    /** The pace in force now (read per use, so a host can change speed live). */
+    pace: () => AgentUiPace;
+    /** A step's element if it is on the page right now. */
+    findStepElementNow: (target: string) => Element | null;
+    /** Find a step's element, waiting for a page that is still loading; `null` when it is not there. */
+    findStepElement: (args: {
+        target: string;
+        signal: AbortSignal;
+    }) => Promise<Element | null>;
+    /** Bring an element into view. */
+    reveal: (args: {
+        element: Element;
+        signal?: AbortSignal;
+    }) => Promise<void>;
+}
+/** Normalise a walkthrough's steps: its text trimmed, its duration set. */
+export declare function tourStep({ target, text, seconds, }: {
+    target: string;
+    text: string;
+    seconds?: number;
+}): AgentUiTourStep;
+export declare function createAgentUiStage({ pace, findStepElementNow, findStepElement, reveal, }: CreateAgentUiStageOptions): AgentUiStage;

package/dist/agent-ui/stage.js

@@ -0,0 +1,196 @@
+import { pause, stepDurationMs } from "./pace.js";
+import { isInViewport } from "./screen.js";
+const EMPTY = { mark: null, cursor: null, tour: null, question: null };
+function tourStep({
+  target,
+  text,
+  seconds
+}) {
+  const trimmed = text.trim();
+  return { target: target.trim(), text: trimmed, durationMs: stepDurationMs({ text: trimmed, seconds }) };
+}
+function createAgentUiStage({
+  pace,
+  findStepElementNow,
+  findStepElement,
+  reveal
+}) {
+  let state = EMPTY;
+  const listeners = /* @__PURE__ */ new Set();
+  let markTimer;
+  let fadeTimer;
+  let tourTimer;
+  let tourSearch = null;
+  let resolveQuestion = null;
+  const set = (next) => {
+    state = { ...state, ...next };
+    for (const listener of Array.from(listeners)) listener();
+  };
+  const stopMarkTimers = () => {
+    if (markTimer !== void 0) clearTimeout(markTimer);
+    if (fadeTimer !== void 0) clearTimeout(fadeTimer);
+    markTimer = void 0;
+    fadeTimer = void 0;
+  };
+  const clearMark = () => {
+    stopMarkTimers();
+    const mark = state.mark;
+    if (!mark) return;
+    const fadeMs = pace().fadeMs;
+    if (fadeMs <= 0) {
+      set({ mark: null });
+      return;
+    }
+    set({ mark: { ...mark, leaving: true } });
+    fadeTimer = setTimeout(() => {
+      var _a;
+      fadeTimer = void 0;
+      if ((_a = state.mark) == null ? void 0 : _a.leaving) set({ mark: null });
+    }, fadeMs);
+  };
+  const stopTourTimers = () => {
+    if (tourTimer !== void 0) clearTimeout(tourTimer);
+    tourTimer = void 0;
+    tourSearch == null ? void 0 : tourSearch.abort();
+    tourSearch = null;
+  };
+  const endTour = () => {
+    stopTourTimers();
+    if (state.tour) set({ tour: null });
+  };
+  const scheduleAdvance = () => {
+    if (tourTimer !== void 0) clearTimeout(tourTimer);
+    tourTimer = void 0;
+    const tour = state.tour;
+    if (!(tour == null ? void 0 : tour.playing) || tour.searching) return;
+    const step = tour.steps[tour.index];
+    if (!step) return;
+    tourTimer = setTimeout(() => {
+      tourTimer = void 0;
+      const current = state.tour;
+      if (!(current == null ? void 0 : current.playing)) return;
+      if (current.index >= current.steps.length - 1) endTour();
+      else void showStep(current.index + 1);
+    }, step.durationMs);
+  };
+  const showStep = async (index) => {
+    const tour = state.tour;
+    const step = tour == null ? void 0 : tour.steps[index];
+    if (!tour || !step) return;
+    stopTourTimers();
+    const present = findStepElementNow(step.target);
+    if (present && isInViewport(present)) {
+      set({ tour: { ...tour, index, element: present, searching: false } });
+      scheduleAdvance();
+      return;
+    }
+    const search = new AbortController();
+    tourSearch = search;
+    set({ tour: { ...tour, index, element: present, searching: true } });
+    let element = present;
+    try {
+      element ?? (element = await findStepElement({ target: step.target, signal: search.signal }));
+      if (element && !search.signal.aborted && !isInViewport(element)) {
+        await reveal({ element, signal: search.signal });
+      }
+    } catch {
+      element = null;
+    }
+    if (search.signal.aborted || tourSearch !== search) return;
+    tourSearch = null;
+    const current = state.tour;
+    if (!current) return;
+    set({ tour: { ...current, index, element, searching: false } });
+    scheduleAdvance();
+  };
+  const answer = (allow) => {
+    const resolve = resolveQuestion;
+    resolveQuestion = null;
+    if (state.question) set({ question: null });
+    resolve == null ? void 0 : resolve(allow);
+  };
+  return {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    mark({ element, tone, caption = null, spotlight = false, durationMs }) {
+      stopMarkTimers();
+      set({ mark: { element, tone, caption, spotlight, leaving: false } });
+      if (durationMs !== void 0) {
+        markTimer = setTimeout(() => {
+          markTimer = void 0;
+          clearMark();
+        }, durationMs);
+      }
+    },
+    clearMark,
+    async cursorTo({ element, signal }) {
+      var _a;
+      set({ cursor: { element, presses: ((_a = state.cursor) == null ? void 0 : _a.presses) ?? 0 } });
+      await pause(pace().cursorGlideMs, signal);
+    },
+    press() {
+      if (state.cursor) set({ cursor: { ...state.cursor, presses: state.cursor.presses + 1 } });
+    },
+    hideCursor() {
+      if (state.cursor) set({ cursor: null });
+    },
+    ask(question) {
+      answer(false);
+      return new Promise((resolve) => {
+        resolveQuestion = resolve;
+        set({ question });
+      });
+    },
+    answer,
+    startTour({ title, steps }) {
+      stopMarkTimers();
+      stopTourTimers();
+      state = {
+        ...state,
+        mark: null,
+        cursor: null,
+        tour: { title, steps, index: 0, playing: true, element: null, searching: true }
+      };
+      void showStep(0);
+    },
+    tourNext() {
+      const tour = state.tour;
+      if (!tour) return;
+      if (tour.index >= tour.steps.length - 1) endTour();
+      else void showStep(tour.index + 1);
+    },
+    tourBack() {
+      const tour = state.tour;
+      if (tour && tour.index > 0) void showStep(tour.index - 1);
+    },
+    tourTogglePlaying() {
+      const tour = state.tour;
+      if (!tour) return;
+      set({ tour: { ...tour, playing: !tour.playing } });
+      if (tour.playing) {
+        if (tourTimer !== void 0) clearTimeout(tourTimer);
+        tourTimer = void 0;
+      } else {
+        scheduleAdvance();
+      }
+    },
+    endTour,
+    clear() {
+      stopMarkTimers();
+      stopTourTimers();
+      answer(false);
+      state = EMPTY;
+      for (const listener of Array.from(listeners)) listener();
+    }
+  };
+}
+export {
+  createAgentUiStage,
+  tourStep
+};
+//# sourceMappingURL=stage.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stage.js","sources":["../../src/agent-ui/stage.ts"],"sourcesContent":["/*\n * The stage: what the overlay is showing right now. A mark around an element\n * with its caption, the agent's cursor, a walkthrough, a question to the\n * person. The tools write it, `AgentUiLayer` draws it, and nothing here\n * touches the page: the stage only holds which element is marked and for how\n * long.\n *\n * Framework-free, so a host without React can draw it too.\n */\n\nimport { type AgentUiPace, pause, stepDurationMs } from './pace';\nimport { isInViewport } from './screen';\n\n/** Why the mark is on an element: the agent is showing it, operating it, or asking about it. */\nexport type AgentUiMarkTone = 'point' | 'act' | 'ask';\n\nexport interface AgentUiMark {\n  element: Element;\n  tone: AgentUiMarkTone;\n  /** Dim the rest of the page. */\n  spotlight: boolean;\n  /** The words shown beside the element. */\n  caption: string | null;\n  /** Fading out. */\n  leaving: boolean;\n}\n\nexport interface AgentUiCursor {\n  /** The element the cursor rests on. */\n  element: Element;\n  /** Counts presses, so the layer plays one ripple per click. */\n  presses: number;\n}\n\nexport interface AgentUiTourStep {\n  /** The target the step is about, as the agent named it. */\n  target: string;\n  text: string;\n  /** How long the step stays before the next one plays. */\n  durationMs: number;\n}\n\nexport interface AgentUiTour {\n  title: string | null;\n  steps: readonly AgentUiTourStep[];\n  index: number;\n  /** Advancing by itself; false while the person paused it. */\n  playing: boolean;\n  /** The current step's element, or `null` when its target is not on this page. */\n  element: Element | null;\n  /** The current step is still looking for its target. */\n  searching: boolean;\n}\n\nexport interface AgentUiQuestion {\n  /** The element the question is about, if it is on screen. */\n  element: Element | null;\n  title: string;\n  body: string | null;\n  allowLabel: string;\n  declineLabel: string;\n}\n\nexport interface AgentUiStageState {\n  mark: AgentUiMark | null;\n  cursor: AgentUiCursor | null;\n  tour: AgentUiTour | null;\n  question: AgentUiQuestion | null;\n}\n\nconst EMPTY: AgentUiStageState = { mark: null, cursor: null, tour: null, question: null };\n\nexport interface AgentUiStage {\n  getState(): AgentUiStageState;\n  subscribe(listener: () => void): () => void;\n\n  /** Mark an element. `durationMs` clears it after that long; without one it stays until replaced. */\n  mark(args: {\n    element: Element;\n    tone: AgentUiMarkTone;\n    caption?: string | null;\n    spotlight?: boolean;\n    durationMs?: number;\n  }): void;\n  /** Fade the mark out. */\n  clearMark(): void;\n\n  /** Move the agent's cursor onto an element; resolves when it has arrived. */\n  cursorTo(args: { element: Element; signal?: AbortSignal }): Promise<void>;\n  /** Show a click where the cursor is. */\n  press(): void;\n  hideCursor(): void;\n\n  /** Ask the person; resolves `true` on allow. A new question declines the one before it. */\n  ask(question: AgentUiQuestion): Promise<boolean>;\n  answer(allow: boolean): void;\n\n  /** Play a walkthrough; replaces whatever the stage showed. */\n  startTour(args: { title: string | null; steps: readonly AgentUiTourStep[] }): void;\n  tourNext(): void;\n  tourBack(): void;\n  tourTogglePlaying(): void;\n  endTour(): void;\n\n  /** Take everything off the page at once. */\n  clear(): void;\n}\n\nexport interface CreateAgentUiStageOptions {\n  /** The pace in force now (read per use, so a host can change speed live). */\n  pace: () => AgentUiPace;\n  /** A step's element if it is on the page right now. */\n  findStepElementNow: (target: string) => Element | null;\n  /** Find a step's element, waiting for a page that is still loading; `null` when it is not there. */\n  findStepElement: (args: { target: string; signal: AbortSignal }) => Promise<Element | null>;\n  /** Bring an element into view. */\n  reveal: (args: { element: Element; signal?: AbortSignal }) => Promise<void>;\n}\n\n/** Normalise a walkthrough's steps: its text trimmed, its duration set. */\nexport function tourStep({\n  target,\n  text,\n  seconds,\n}: {\n  target: string;\n  text: string;\n  seconds?: number;\n}): AgentUiTourStep {\n  const trimmed = text.trim();\n  return { target: target.trim(), text: trimmed, durationMs: stepDurationMs({ text: trimmed, seconds }) };\n}\n\nexport function createAgentUiStage({\n  pace,\n  findStepElementNow,\n  findStepElement,\n  reveal,\n}: CreateAgentUiStageOptions): AgentUiStage {\n  let state: AgentUiStageState = EMPTY;\n  const listeners = new Set<() => void>();\n  let markTimer: ReturnType<typeof setTimeout> | undefined;\n  let fadeTimer: ReturnType<typeof setTimeout> | undefined;\n  let tourTimer: ReturnType<typeof setTimeout> | undefined;\n  let tourSearch: AbortController | null = null;\n  let resolveQuestion: ((allow: boolean) => void) | null = null;\n\n  const set = (next: Partial<AgentUiStageState>) => {\n    state = { ...state, ...next };\n    for (const listener of Array.from(listeners)) listener();\n  };\n\n  const stopMarkTimers = () => {\n    if (markTimer !== undefined) clearTimeout(markTimer);\n    if (fadeTimer !== undefined) clearTimeout(fadeTimer);\n    markTimer = undefined;\n    fadeTimer = undefined;\n  };\n\n  const clearMark = () => {\n    stopMarkTimers();\n    const mark = state.mark;\n    if (!mark) return;\n    const fadeMs = pace().fadeMs;\n    if (fadeMs <= 0) {\n      set({ mark: null });\n      return;\n    }\n    set({ mark: { ...mark, leaving: true } });\n    fadeTimer = setTimeout(() => {\n      fadeTimer = undefined;\n      if (state.mark?.leaving) set({ mark: null });\n    }, fadeMs);\n  };\n\n  const stopTourTimers = () => {\n    if (tourTimer !== undefined) clearTimeout(tourTimer);\n    tourTimer = undefined;\n    tourSearch?.abort();\n    tourSearch = null;\n  };\n\n  const endTour = () => {\n    stopTourTimers();\n    if (state.tour) set({ tour: null });\n  };\n\n  const scheduleAdvance = () => {\n    if (tourTimer !== undefined) clearTimeout(tourTimer);\n    tourTimer = undefined;\n    const tour = state.tour;\n    if (!tour?.playing || tour.searching) return;\n    const step = tour.steps[tour.index];\n    if (!step) return;\n    tourTimer = setTimeout(() => {\n      tourTimer = undefined;\n      const current = state.tour;\n      if (!current?.playing) return;\n      if (current.index >= current.steps.length - 1) endTour();\n      else void showStep(current.index + 1);\n    }, step.durationMs);\n  };\n\n  const showStep = async (index: number): Promise<void> => {\n    const tour = state.tour;\n    const step = tour?.steps[index];\n    if (!tour || !step) return;\n    stopTourTimers();\n    // The usual step is on the page and in view: move to it in one update, so\n    // the card goes straight from one element to the next.\n    const present = findStepElementNow(step.target);\n    if (present && isInViewport(present)) {\n      set({ tour: { ...tour, index, element: present, searching: false } });\n      scheduleAdvance();\n      return;\n    }\n    const search = new AbortController();\n    tourSearch = search;\n    set({ tour: { ...tour, index, element: present, searching: true } });\n    let element: Element | null = present;\n    try {\n      element ??= await findStepElement({ target: step.target, signal: search.signal });\n      if (element && !search.signal.aborted && !isInViewport(element)) {\n        await reveal({ element, signal: search.signal });\n      }\n    } catch {\n      element = null;\n    }\n    // Another step, or the end of the walkthrough, took over while this one looked.\n    if (search.signal.aborted || tourSearch !== search) return;\n    tourSearch = null;\n    const current = state.tour;\n    if (!current) return;\n    set({ tour: { ...current, index, element, searching: false } });\n    scheduleAdvance();\n  };\n\n  const answer = (allow: boolean) => {\n    const resolve = resolveQuestion;\n    resolveQuestion = null;\n    if (state.question) set({ question: null });\n    resolve?.(allow);\n  };\n\n  return {\n    getState: () => state,\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n\n    mark({ element, tone, caption = null, spotlight = false, durationMs }) {\n      stopMarkTimers();\n      set({ mark: { element, tone, caption, spotlight, leaving: false } });\n      if (durationMs !== undefined) {\n        markTimer = setTimeout(() => {\n          markTimer = undefined;\n          clearMark();\n        }, durationMs);\n      }\n    },\n    clearMark,\n\n    async cursorTo({ element, signal }) {\n      set({ cursor: { element, presses: state.cursor?.presses ?? 0 } });\n      await pause(pace().cursorGlideMs, signal);\n    },\n    press() {\n      if (state.cursor) set({ cursor: { ...state.cursor, presses: state.cursor.presses + 1 } });\n    },\n    hideCursor() {\n      if (state.cursor) set({ cursor: null });\n    },\n\n    ask(question) {\n      answer(false);\n      return new Promise<boolean>((resolve) => {\n        resolveQuestion = resolve;\n        set({ question });\n      });\n    },\n    answer,\n\n    startTour({ title, steps }) {\n      stopMarkTimers();\n      stopTourTimers();\n      // Published by `showStep` with the first step's element, in one update.\n      state = {\n        ...state,\n        mark: null,\n        cursor: null,\n        tour: { title, steps, index: 0, playing: true, element: null, searching: true },\n      };\n      void showStep(0);\n    },\n    tourNext() {\n      const tour = state.tour;\n      if (!tour) return;\n      if (tour.index >= tour.steps.length - 1) endTour();\n      else void showStep(tour.index + 1);\n    },\n    tourBack() {\n      const tour = state.tour;\n      if (tour && tour.index > 0) void showStep(tour.index - 1);\n    },\n    tourTogglePlaying() {\n      const tour = state.tour;\n      if (!tour) return;\n      set({ tour: { ...tour, playing: !tour.playing } });\n      if (tour.playing) {\n        if (tourTimer !== undefined) clearTimeout(tourTimer);\n        tourTimer = undefined;\n      } else {\n        scheduleAdvance();\n      }\n    },\n    endTour,\n\n    clear() {\n      stopMarkTimers();\n      stopTourTimers();\n      answer(false);\n      state = EMPTY;\n      for (const listener of Array.from(listeners)) listener();\n    },\n  };\n}\n"],"names":[],"mappings":"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"}