@artooi/ag-ui-web-component 0.20.0 → 0.21.0

package/src/core/transcribe_audio.ts

@@ -1,3 +1,5 @@
+import { withCredentials } from "./utils.js";
+
 /**
  * The composer's voice-transcription contract: take a recorded audio `Blob` and
  * resolve to the transcript text. The built-in handler is {@link transcribeAudio}
@@ -13,6 +15,13 @@ export interface TranscribeOptions {
   readonly url: string;
   /** Extra HTTP headers (CSRF / auth), read fresh per request. */
   readonly headers?: Record<string, string>;
+  /**
+   * Cookie policy, as `fetch`'s own `credentials` mode. Unset leaves the
+   * browser default (`same-origin`), which sends no cookies to an endpoint on
+   * another origin; a cookie-authenticated cross-origin deployment needs
+   * `"include"`.
+   */
+  readonly credentials?: RequestCredentials;
 }
 
 /**
@@ -29,11 +38,17 @@ export async function transcribeAudio(audio: Blob, options: TranscribeOptions):
   // reads the blob's content type).
   form.append("audio", audio, "recording.webm");
 
-  const response = await fetch(options.url, {
-    method: "POST",
-    headers: { ...(options.headers ?? {}) },
-    body: form,
-  });
+  const response = await fetch(
+    options.url,
+    withCredentials(
+      {
+        method: "POST",
+        headers: { ...(options.headers ?? {}) },
+        body: form,
+      },
+      options.credentials,
+    ),
+  );
   if (!response.ok) {
     throw new Error(await errorMessage(response));
   }

package/src/core/upload_attachment.ts

@@ -26,6 +26,15 @@ export interface UploadOptions {
   readonly url: string;
   /** Extra HTTP headers (CSRF / auth), read fresh per upload. */
   readonly headers?: Record<string, string>;
+  /**
+   * Cookie policy, spelled as `fetch`'s `credentials` mode for consistency with
+   * the component's other endpoints — but carried by `XMLHttpRequest`, which
+   * only has the two-state `withCredentials`. `"include"` sets it; every other
+   * value leaves it off, which matches `"same-origin"`. `"omit"` therefore
+   * **cannot** be honoured for a same-origin upload (XHR always sends cookies
+   * there); use a custom {@link UploadHandler} if that matters.
+   */
+  readonly credentials?: RequestCredentials;
   /** Progress callback, `0..1`, fired as the body uploads. */
   readonly onProgress?: (fraction: number) => void;
   /** Abort signal to cancel the in-flight upload. */
@@ -48,6 +57,10 @@ export function uploadAttachment(file: File, options: UploadOptions): Promise<At
 
     const xhr = new XMLHttpRequest();
     xhr.open("POST", options.url);
+    // Cross-origin cookies ride only when asked for, exactly as with the fetch
+    // sites; without this an upload to another subdomain is anonymous and 401s
+    // while the run itself succeeds.
+    xhr.withCredentials = options.credentials === "include";
     for (const [key, value] of Object.entries(options.headers ?? {})) {
       xhr.setRequestHeader(key, value);
     }

package/src/core/utils.ts

@@ -0,0 +1,18 @@
+// Non-exported-from-index helpers shared by the core transport modules.
+
+/**
+ * Overlay a `credentials` mode onto a fetch `init`, or hand the `init` back
+ * untouched when the caller has none configured.
+ *
+ * Absent and `undefined` are not the same thing here. `exactOptionalPropertyTypes`
+ * rejects an explicit `credentials: undefined`, and writing one anyway would
+ * state a mode where the point is to leave the browser's own default in place.
+ * Every fetch this component makes has to make that choice, so it is made in one
+ * place rather than repeated (and eventually forgotten) at each call site.
+ */
+export function withCredentials(
+  init: RequestInit | undefined,
+  credentials: RequestCredentials | undefined,
+): RequestInit | undefined {
+  return credentials === undefined ? init : { ...init, credentials };
+}

package/src/dom/animations.ts

@@ -8,14 +8,61 @@
 
 import { setNativeChecked, setNativeValue } from "./native_setter.js";
 
+/** Ring colour when the host page has not themed `--ag-ui-accent`. */
 const ACCENT = "#4f46e5";
 
+/**
+ * Fallback for the box-shadow rings, which read as a soft halo rather than a
+ * line and so carry their own alpha.
+ */
+const ACCENT_HALO = "rgba(79, 70, 229, 0.4)";
+
+const ACCENT_PROPERTY = "--ag-ui-accent";
+
 function delay(ms: number): Promise<void> {
   return new Promise<void>((resolve) => {
     setTimeout(resolve, ms);
   });
 }
 
+/**
+ * Whether the user has asked the OS/browser to minimise motion.
+ *
+ * Honoured by every primitive that *moves* something: the action animations
+ * skip their hold delays, `scrollIntoCenterView` jumps instead of gliding, and
+ * the focus flash drops its fade while still holding the ring long enough to be
+ * seen — reduced motion asks for no animation, not for no feedback. The
+ * character-typing and highlight primitives predate this and keep their
+ * explicit-duration contract.
+ */
+export function prefersReducedMotion(): boolean {
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/** Like {@link delay}, but resolves immediately under reduced motion. */
+function motionDelay(ms: number): Promise<void> {
+  if (ms <= 0 || prefersReducedMotion()) {
+    return Promise.resolve();
+  }
+  return delay(ms);
+}
+
+/**
+ * Resolve the accent colour from the **target's** computed style.
+ *
+ * `--ag-ui-accent` inherits, so reading it off the element the agent is about
+ * to touch picks up whatever the host's cascade produced there — a themed page
+ * gets flashed in its own colour instead of this package's indigo.
+ */
+function accentColor(el: HTMLElement, fallback: string): string {
+  const themed = window.getComputedStyle(el).getPropertyValue(ACCENT_PROPERTY).trim();
+  return themed === "" ? fallback : themed;
+}
+
+function ringShadow(el: HTMLElement): string {
+  return `0 0 0 3px ${accentColor(el, ACCENT_HALO)}`;
+}
+
 /** An element whose `value` can be typed into. */
 export type TextLikeElement = HTMLInputElement | HTMLTextAreaElement;
 
@@ -59,7 +106,7 @@ export async function highlightThenClick(
   const highlightMs = options.highlightMs ?? 280;
   const previousOutline = el.style.outline;
   const previousOffset = el.style.outlineOffset;
-  el.style.outline = `2px solid ${ACCENT}`;
+  el.style.outline = `2px solid ${accentColor(el, ACCENT)}`;
   el.style.outlineOffset = "2px";
   await delay(highlightMs);
   el.style.outline = previousOutline;
@@ -67,46 +114,143 @@ export async function highlightThenClick(
   el.click();
 }
 
-/** Scroll ``el`` to the vertical centre of the viewport. */
-export function scrollIntoCenterView(el: HTMLElement): void {
-  el.scrollIntoView({ block: "center", inline: "nearest", behavior: "smooth" });
+export interface ScrollOptions {
+  /**
+   * How long to wait for a moving scroll to settle before giving up.
+   * Default 600.
+   */
+  settleMs?: number;
 }
 
+const SCROLL_SETTLE_MS = 600;
+
+/** How long to give a smooth scroll to start moving before assuming it will not. */
+const SCROLL_START_MS = 100;
+
+/**
+ * Scroll ``el`` to the vertical centre of the viewport.
+ *
+ * The returned promise resolves once the scroll has settled, so a caller can
+ * hold its animation until the element has stopped moving — a ring drawn
+ * mid-glide lands somewhere the user is not looking yet. Awaiting is optional;
+ * the scroll itself is requested synchronously.
+ */
+export function scrollIntoCenterView(el: HTMLElement, options: ScrollOptions = {}): Promise<void> {
+  const reduced = prefersReducedMotion();
+  el.scrollIntoView({
+    block: "center",
+    inline: "nearest",
+    behavior: reduced ? "auto" : "smooth",
+  });
+  if (reduced) {
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve) => {
+    let timer: ReturnType<typeof setTimeout>;
+    const settle = (): void => {
+      clearTimeout(timer);
+      document.removeEventListener("scroll", started, true);
+      document.removeEventListener("scrollend", settle, true);
+      resolve();
+    };
+    const started = (): void => {
+      document.removeEventListener("scroll", started, true);
+      clearTimeout(timer);
+      timer = setTimeout(settle, options.settleMs ?? SCROLL_SETTLE_MS);
+    };
+    // Neither event bubbles, and both fire on whichever ancestor actually
+    // scrolled, so listen on the document in the capture phase.
+    //
+    // Two timeouts, because two things can go wrong. An element already in
+    // view never scrolls and so never fires scrollend — waiting the full
+    // budget for it would add dead time to every action, hence the short
+    // did-anything-move probe. Once something is moving, the longer budget
+    // covers browsers that do not implement scrollend at all (Safari gained it
+    // only recently).
+    timer = setTimeout(settle, SCROLL_START_MS);
+    document.addEventListener("scroll", started, true);
+    document.addEventListener("scrollend", settle, true);
+  });
+}
+
+/** Total on-screen life of the flash ring, hold plus fade. */
+const FLASH_MS = 1200;
+
+/** Share of {@link FLASH_MS} spent fading out rather than holding. */
+const FLASH_FADE_RATIO = 1 / 3;
+
 export interface FlashOptions {
-  /** Milliseconds to hold the focus flash. Default 200. */
+  /**
+   * Total milliseconds the ring is on screen, hold plus fade. Default 1200 —
+   * long enough for someone who does not yet know where to look to find it.
+   */
   flashMs?: number;
+  /** Ring colour. Defaults to the target's `--ag-ui-accent`, else the package accent. */
+  color?: string;
+  /**
+   * Move keyboard focus to the element as well. Defaults to false for
+   * {@link flash} and true for {@link focusWithFlash}.
+   */
+  focus?: boolean;
 }
 
-/** Focus ``el`` and briefly flash a ring around it. */
-export async function focusWithFlash(el: HTMLElement, options: FlashOptions = {}): Promise<void> {
-  const flashMs = options.flashMs ?? 200;
-  el.focus();
-  const previousShadow = el.style.boxShadow;
-  el.style.boxShadow = `0 0 0 3px rgba(79, 70, 229, 0.4)`;
-  await delay(flashMs);
-  el.style.boxShadow = previousShadow;
+async function flashRing(
+  el: HTMLElement,
+  options: FlashOptions,
+  focusByDefault: boolean,
+): Promise<void> {
+  if (options.focus ?? focusByDefault) {
+    // preventScroll: a caller's smooth scroll is typically still in flight, and
+    // the instant scroll focus() would otherwise do fights it.
+    el.focus({ preventScroll: true });
+  }
+  const flashMs = options.flashMs ?? FLASH_MS;
+  if (flashMs <= 0) {
+    return;
+  }
+  const previousOutline = el.style.outline;
+  const previousOffset = el.style.outlineOffset;
+  const previousTransition = el.style.transition;
+  const color = options.color ?? accentColor(el, ACCENT);
+  // outline, not box-shadow: a shadow paints outside the border box, so any
+  // overflow:hidden ancestor sharing the target's box (a card, a table cell)
+  // clips the whole ring away while the helper still reports success.
+  el.style.outline = `3px solid ${color}`;
+  el.style.outlineOffset = "2px";
+  const fadeMs = prefersReducedMotion() ? 0 : Math.round(flashMs * FLASH_FADE_RATIO);
+  await delay(flashMs - fadeMs);
+  if (fadeMs > 0) {
+    // Setting the transition and the new colour in the same task is fine: the
+    // browser starts transitions from the after-change style.
+    el.style.transition = `outline-color ${fadeMs}ms ease-out`;
+    el.style.outline = "3px solid transparent";
+    await delay(fadeMs);
+  }
+  el.style.outline = previousOutline;
+  el.style.outlineOffset = previousOffset;
+  el.style.transition = previousTransition;
 }
 
-const RING = "0 0 0 3px rgba(79, 70, 229, 0.4)";
-
 /**
- * Whether the user has asked the OS/browser to minimise motion.
+ * Flash a ring around ``el`` without touching focus.
  *
- * The richer action animations below check this and skip their hold delays so
- * the agent's edits still happen (events fire, values set) but without the
- * visible pause. The character-typing / highlight primitives above predate this
- * and keep their explicit-duration contract.
+ * Prefer this over {@link focusWithFlash} when the point is to *show* the user
+ * something: moving focus steals it from the composer, can fire blur validation
+ * on whatever they were mid-edit in, and can close an open menu.
  */
-export function prefersReducedMotion(): boolean {
-  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+export function flash(el: HTMLElement, options: FlashOptions = {}): Promise<void> {
+  return flashRing(el, options, false);
 }
 
-/** Like {@link delay}, but resolves immediately under reduced motion. */
-function motionDelay(ms: number): Promise<void> {
-  if (ms <= 0 || prefersReducedMotion()) {
-    return Promise.resolve();
-  }
-  return delay(ms);
+/**
+ * Focus ``el`` and flash a ring around it.
+ *
+ * Focus moves unless ``options.focus`` says otherwise — that is the documented
+ * behaviour of this name. Use {@link flash} for a highlight that leaves focus
+ * where the user put it.
+ */
+export function focusWithFlash(el: HTMLElement, options: FlashOptions = {}): Promise<void> {
+  return flashRing(el, options, true);
 }
 
 export interface PressOptions {
@@ -126,7 +270,7 @@ export async function pressThenClick(el: HTMLElement, options: PressOptions = {}
   const previousShadow = el.style.boxShadow;
   el.style.transition = "transform 80ms ease";
   el.style.transform = "scale(0.96)";
-  el.style.boxShadow = RING;
+  el.style.boxShadow = ringShadow(el);
   await motionDelay(pressMs);
   el.style.transform = previousTransform;
   el.style.transition = previousTransition;
@@ -166,7 +310,7 @@ export async function selectOption(
   const highlightMs = options.highlightMs ?? 220;
   const previousOutline = el.style.outline;
   const previousOffset = el.style.outlineOffset;
-  el.style.outline = `2px solid ${ACCENT}`;
+  el.style.outline = `2px solid ${accentColor(el, ACCENT)}`;
   el.style.outlineOffset = "2px";
   await motionDelay(highlightMs);
   setNativeValue(el, option.value);
@@ -192,7 +336,7 @@ export async function toggleControl(
 ): Promise<void> {
   const flashMs = options.flashMs ?? 200;
   const previousShadow = el.style.boxShadow;
-  el.style.boxShadow = RING;
+  el.style.boxShadow = ringShadow(el);
   await motionDelay(flashMs);
   setNativeChecked(el, checked);
   el.dispatchEvent(new Event("input", { bubbles: true }));

package/src/dom/dom_driver.ts

@@ -1,4 +1,5 @@
 import {
+  type FlashOptions,
   focusWithFlash,
   type HighlightClickOptions,
   highlightThenClick,
@@ -23,20 +24,25 @@ import { setNativeChecked, setNativeValue } from "./native_setter.js";
  * `fill_field(name, value)` finds `#id_<name>` then calls {@link fillField}.
  */
 
-export interface FillFieldOptions extends TypeOptions, FlashOptionsLike {}
-
-interface FlashOptionsLike {
-  flashMs?: number;
-}
+/**
+ * A field has to hold focus to be typed into, so ``focus`` is not on offer
+ * here — everything else the flash takes is.
+ */
+export interface FillFieldOptions extends TypeOptions, Omit<FlashOptions, "focus"> {}
 
-/** Scroll to, focus (with a flash), and type ``value`` into a text field. */
+/**
+ * Scroll to, focus (with a flash), and type ``value`` into a text field.
+ *
+ * The scroll is awaited: typing into an element that is still gliding past
+ * shows the user nothing.
+ */
 export async function fillField(
   el: TextLikeElement,
   value: string,
   options: FillFieldOptions = {},
 ): Promise<void> {
-  scrollIntoCenterView(el);
-  await focusWithFlash(el, { flashMs: options.flashMs ?? 0 });
+  await scrollIntoCenterView(el);
+  await focusWithFlash(el, { ...options, flashMs: options.flashMs ?? 0 });
   await typeInto(el, value, options);
 }
 
@@ -45,13 +51,13 @@ export async function clickElement(
   el: HTMLElement,
   options: HighlightClickOptions = {},
 ): Promise<void> {
-  scrollIntoCenterView(el);
+  await scrollIntoCenterView(el);
   await highlightThenClick(el, options);
 }
 
 /** Scroll to a button/control and click it with a visible "press" animation. */
 export async function pressButton(el: HTMLElement, options: PressOptions = {}): Promise<void> {
-  scrollIntoCenterView(el);
+  await scrollIntoCenterView(el);
   await pressThenClick(el, options);
 }
 
@@ -61,7 +67,7 @@ export async function selectControl(
   value: string,
   options: SelectOptions = {},
 ): Promise<void> {
-  scrollIntoCenterView(el);
+  await scrollIntoCenterView(el);
   await selectOption(el, value, options);
 }
 
@@ -71,7 +77,7 @@ export async function toggleCheckbox(
   checked: boolean,
   options: ToggleOptions = {},
 ): Promise<void> {
-  scrollIntoCenterView(el);
+  await scrollIntoCenterView(el);
   await toggleControl(el, checked, options);
 }
 

package/src/index.ts

@@ -64,12 +64,14 @@ export {
 } from "./core/upload_attachment.js";
 export {
   type FlashOptions,
+  flash,
   focusWithFlash,
   type HighlightClickOptions,
   highlightThenClick,
   type PressOptions,
   prefersReducedMotion,
   pressThenClick,
+  type ScrollOptions,
   type SelectOptions,
   scrollIntoCenterView,
   selectOption,