npm - @artooi/ag-ui-web-component - Versions diffs - 0.20.0 → 0.21.0 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/CHANGELOG.md +135 -1
package/README.md +286 -20
package/dist/ag-ui-web-component.bundle.js +407 -382
package/dist/ag-ui-web-component.bundle.js.map +4 -4
package/dist/core/ag_ui_chat.d.ts +82 -1
package/dist/core/ag_ui_chat.d.ts.map +1 -1
package/dist/core/create_http_agent.d.ts +9 -0
package/dist/core/create_http_agent.d.ts.map +1 -1
package/dist/core/remote_conversation_store.d.ts +8 -1
package/dist/core/remote_conversation_store.d.ts.map +1 -1
package/dist/core/run_index.d.ts +8 -1
package/dist/core/run_index.d.ts.map +1 -1
package/dist/core/transcribe_audio.d.ts +7 -0
package/dist/core/transcribe_audio.d.ts.map +1 -1
package/dist/core/upload_attachment.d.ts +9 -0
package/dist/core/upload_attachment.d.ts.map +1 -1
package/dist/core/utils.d.ts +12 -0
package/dist/core/utils.d.ts.map +1 -0
package/dist/dom/animations.d.ts +51 -11
package/dist/dom/animations.d.ts.map +1 -1
package/dist/dom/dom_driver.d.ts +12 -7
package/dist/dom/dom_driver.d.ts.map +1 -1
package/dist/index.d.ts +1 -1
package/dist/index.d.ts.map +1 -1
package/dist/index.js +766 -430
package/dist/index.js.map +3 -3
package/dist/ui/styles.d.ts +1 -1
package/dist/ui/styles.d.ts.map +1 -1
package/package.json +1 -1
package/src/core/ag_ui_chat.ts +292 -31
package/src/core/create_http_agent.ts +14 -3
package/src/core/remote_conversation_store.ts +25 -6
package/src/core/run_index.ts +27 -5
package/src/core/transcribe_audio.ts +20 -5
package/src/core/upload_attachment.ts +13 -0
package/src/core/utils.ts +18 -0
package/src/dom/animations.ts +175 -31
package/src/dom/dom_driver.ts +18 -12
package/src/index.ts +2 -0
package/src/ui/styles.ts +377 -352
package/src/version.ts +1 -1

package/dist/index.js CHANGED Viewed

@@ -134,11 +134,29 @@ function setNativeChecked(el, checked) {
 // src/dom/animations.ts
 var ACCENT = "#4f46e5";
+var ACCENT_HALO = "rgba(79, 70, 229, 0.4)";
+var ACCENT_PROPERTY = "--ag-ui-accent";
 function delay(ms) {
   return new Promise((resolve) => {
     setTimeout(resolve, ms);
   });
 }
+function prefersReducedMotion() {
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+function motionDelay(ms) {
+  if (ms <= 0 || prefersReducedMotion()) {
+    return Promise.resolve();
+  }
+  return delay(ms);
+}
+function accentColor(el, fallback) {
+  const themed = window.getComputedStyle(el).getPropertyValue(ACCENT_PROPERTY).trim();
+  return themed === "" ? fallback : themed;
+}
+function ringShadow(el) {
+  return `0 0 0 3px ${accentColor(el, ACCENT_HALO)}`;
+}
 async function typeInto(el, value, options = {}) {
   const charDelayMs = options.charDelayMs ?? 35;
   setNativeValue(el, "");
@@ -156,33 +174,75 @@ async function highlightThenClick(el, options = {}) {
   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;
   el.style.outlineOffset = previousOffset;
   el.click();
 }
-function scrollIntoCenterView(el) {
-  el.scrollIntoView({ block: "center", inline: "nearest", behavior: "smooth" });
+var SCROLL_SETTLE_MS = 600;
+var SCROLL_START_MS = 100;
+function scrollIntoCenterView(el, options = {}) {
+  const reduced = prefersReducedMotion();
+  el.scrollIntoView({
+    block: "center",
+    inline: "nearest",
+    behavior: reduced ? "auto" : "smooth"
+  });
+  if (reduced) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    let timer;
+    const settle = () => {
+      clearTimeout(timer);
+      document.removeEventListener("scroll", started, true);
+      document.removeEventListener("scrollend", settle, true);
+      resolve();
+    };
+    const started = () => {
+      document.removeEventListener("scroll", started, true);
+      clearTimeout(timer);
+      timer = setTimeout(settle, options.settleMs ?? SCROLL_SETTLE_MS);
+    };
+    timer = setTimeout(settle, SCROLL_START_MS);
+    document.addEventListener("scroll", started, true);
+    document.addEventListener("scrollend", settle, true);
+  });
 }
-async function focusWithFlash(el, options = {}) {
-  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;
+var FLASH_MS = 1200;
+var FLASH_FADE_RATIO = 1 / 3;
+async function flashRing(el, options, focusByDefault) {
+  if (options.focus ?? focusByDefault) {
+    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);
+  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) {
+    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;
 }
-var RING = "0 0 0 3px rgba(79, 70, 229, 0.4)";
-function prefersReducedMotion() {
-  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+function flash(el, options = {}) {
+  return flashRing(el, options, false);
 }
-function motionDelay(ms) {
-  if (ms <= 0 || prefersReducedMotion()) {
-    return Promise.resolve();
-  }
-  return delay(ms);
+function focusWithFlash(el, options = {}) {
+  return flashRing(el, options, true);
 }
 async function pressThenClick(el, options = {}) {
   const pressMs = options.pressMs ?? 140;
@@ -191,7 +251,7 @@ async function pressThenClick(el, options = {}) {
   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;
@@ -214,7 +274,7 @@ async function selectOption(el, value, options = {}) {
   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);
@@ -226,7 +286,7 @@ async function selectOption(el, value, options = {}) {
 async function toggleControl(el, checked, options = {}) {
   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 }));
@@ -4401,151 +4461,186 @@ var SkillsMenu = class {
 // src/ui/styles.ts
 var STYLES = `
+/* \u2500\u2500 Token defaults \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+   Every public --ag-ui-* token is read here into a private --_* alias, and
+   only the alias is used by the rules below.
+   The indirection is what makes ancestor theming work. Declaring the public
+   name on :host would set it *on the host element*, and a value on an element
+   always beats one inherited from an ancestor \u2014 so a page that put the tokens
+   on a wrapper would see no effect at all, which is the one thing the API is
+   documented to support. Reading the public name with the default as a var()
+   fallback leaves it undeclared on the element, so an ancestor's value is
+   inherited normally while a value aimed at the element still wins over it.
+   Two invariants hold this together:
+   1. No rule outside this file's :host blocks may reference a public name
+      directly. A public name read outside these blocks resolves to nothing and
+      silently drops its declaration rather than erroring, so the miss shows up
+      as a missing colour, not a failure.
+   2. Every --_* alias in use is declared here. Aliases inherit like any custom
+      property, so an undeclared one would pick up a same-named property from
+      the host page; declaring it on :host shields the shadow tree from that. */
 :host {
   /* Colors */
-  --ag-ui-bg: #ffffff;
-  --ag-ui-fg: #1a1a2e;
-  --ag-ui-accent: #4f46e5;
-  --ag-ui-user-bg: #4f46e5;
-  --ag-ui-user-fg: #ffffff;
-  --ag-ui-assistant-bg: #f1f1f6;
-  --ag-ui-hover: #e7e7ee;
-  --ag-ui-input-bg: var(--ag-ui-bg);
-  --ag-ui-tool-bg: var(--ag-ui-assistant-bg);
-  --ag-ui-tool-fg: var(--ag-ui-accent);
-  --ag-ui-header-bg: var(--ag-ui-accent);
-  --ag-ui-header-fg: #ffffff;
-  --ag-ui-border: #e2e2ec;
-  --ag-ui-radius: 12px;
+  --_bg: var(--ag-ui-bg, #ffffff);
+  --_fg: var(--ag-ui-fg, #1a1a2e);
+  --_accent: var(--ag-ui-accent, #4f46e5);
+  --_user-bg: var(--ag-ui-user-bg, #4f46e5);
+  --_user-fg: var(--ag-ui-user-fg, #ffffff);
+  --_assistant-bg: var(--ag-ui-assistant-bg, #f1f1f6);
+  --_hover: var(--ag-ui-hover, #e7e7ee);
+  --_input-bg: var(--ag-ui-input-bg, var(--_bg));
+  --_tool-bg: var(--ag-ui-tool-bg, var(--_assistant-bg));
+  --_tool-fg: var(--ag-ui-tool-fg, var(--_accent));
+  --_header-bg: var(--ag-ui-header-bg, var(--_accent));
+  --_header-fg: var(--ag-ui-header-fg, #ffffff);
+  --_border: var(--ag-ui-border, #e2e2ec);
+  --_radius: var(--ag-ui-radius, 12px);
+  /* Body text and raised chrome. Both are referenced by the code-block copy
+     button; neither had a default before, so the declarations reading them
+     were dropped and the button fell back to the inherited colour over a
+     transparent box. The defaults below restate exactly that, so this is a
+     rename with no repaint \u2014 see the note on .code-copy. */
+  --_text: var(--ag-ui-text, var(--_fg));
+  --_surface: var(--ag-ui-surface, transparent);
   /* Status accents for tool-call cards. */
-  --ag-ui-success: #15803d;
-  --ag-ui-danger: #b91c1c;
-  --ag-ui-muted: #6b7280;
+  --_success: var(--ag-ui-success, #15803d);
+  --_danger: var(--ag-ui-danger, #b91c1c);
+  --_muted: var(--ag-ui-muted, #6b7280);
   /* Tool-call status icon glyphs (override to re-theme) + spinner speed.
      The pending state is the animated ring; the settled states use these. */
-  --ag-ui-tool-icon-done: "\u2713";
-  --ag-ui-tool-icon-error: "\u2715";
-  --ag-ui-tool-icon-declined: "\u2298";
-  --ag-ui-tool-spin-duration: 0.7s;
+  --_tool-icon-done: var(--ag-ui-tool-icon-done, "\u2713");
+  --_tool-icon-error: var(--ag-ui-tool-icon-error, "\u2715");
+  --_tool-icon-declined: var(--ag-ui-tool-icon-declined, "\u2298");
+  --_tool-spin-duration: var(--ag-ui-tool-spin-duration, 0.7s);
   /* Answer well (opt-in via data-answer-well) \u2014 boxes a whole assistant turn. */
-  --ag-ui-well-bg: transparent;
-  --ag-ui-well-border: var(--ag-ui-border);
+  --_well-bg: var(--ag-ui-well-bg, transparent);
+  --_well-border: var(--ag-ui-well-border, var(--_border));
   /* Surface \u2014 set --ag-ui-shadow: none for a flush, embedded panel. */
-  --ag-ui-shadow: 0 12px 32px rgba(20, 20, 50, 0.18);
-  --ag-ui-font: inherit;
-  --ag-ui-font-size: 14px;
-  --ag-ui-code-font: ui-monospace, "SF Mono", Menlo, monospace;
+  --_shadow: var(--ag-ui-shadow, 0 12px 32px rgba(20, 20, 50, 0.18));
+  --_font: var(--ag-ui-font, inherit);
+  --_font-size: var(--ag-ui-font-size, 14px);
+  --_code-font: var(--ag-ui-code-font, ui-monospace, "SF Mono", Menlo, monospace);
+  /* Header / launcher icon box. */
+  --_icon-size: var(--ag-ui-icon-size, 22px);
+  --_icon-radius: var(--ag-ui-icon-radius, 4px);
   /* Spacing \u2014 the density preset overrides these. */
-  --ag-ui-space: 10px;
-  --ag-ui-pad: 16px;
-  --ag-ui-msg-pad: 8px 12px;
-  --ag-ui-msg-radius: 14px;
+  --_space: var(--ag-ui-space, 10px);
+  --_pad: var(--ag-ui-pad, 16px);
+  --_msg-pad: var(--ag-ui-msg-pad, 8px 12px);
+  --_msg-radius: var(--ag-ui-msg-radius, 14px);
   /* Layout \u2014 override from outside to dock the widget anywhere.
      Set --ag-ui-position: static (and place this element in your own
      grid/flex layout) to embed it in the page flow instead of floating. */
-  --ag-ui-position: fixed;
-  --ag-ui-z-index: 2147483000;
-  --ag-ui-width: 380px;
-  --ag-ui-height: 560px;
-  --ag-ui-inset: auto 24px 24px auto;
-  --ag-ui-max-width: calc(100vw - 48px);
-  --ag-ui-max-height: calc(100vh - 48px);
+  --_position: var(--ag-ui-position, fixed);
+  --_z-index: var(--ag-ui-z-index, 2147483000);
+  --_width: var(--ag-ui-width, 380px);
+  --_height: var(--ag-ui-height, 560px);
+  --_inset: var(--ag-ui-inset, auto 24px 24px auto);
+  --_max-width: var(--ag-ui-max-width, calc(100vw - 48px));
+  --_max-height: var(--ag-ui-max-height, calc(100vh - 48px));
   /* Reading-column width for placement="page" (full-bleed, centred content). */
-  --ag-ui-content-max-width: 820px;
-  position: var(--ag-ui-position);
-  inset: var(--ag-ui-inset);
-  z-index: var(--ag-ui-z-index);
-  width: var(--ag-ui-width);
-  max-width: var(--ag-ui-max-width);
-  height: var(--ag-ui-height);
-  max-height: var(--ag-ui-max-height);
+  --_content-max-width: var(--ag-ui-content-max-width, 820px);
+  /* Slim rail the sidebar placement collapses to. Only that placement reads
+     it, but it is declared here so invariant 2 holds for every alias. */
+  --_rail-width: var(--ag-ui-rail-width, 52px);
+  position: var(--_position);
+  inset: var(--_inset);
+  z-index: var(--_z-index);
+  width: var(--_width);
+  max-width: var(--_max-width);
+  height: var(--_height);
+  max-height: var(--_max-height);
   display: flex;
-  font-family: var(--ag-ui-font);
-  font-size: var(--ag-ui-font-size);
-  color: var(--ag-ui-fg);
+  font-family: var(--_font);
+  font-size: var(--_font-size);
+  color: var(--_fg);
 }
 /* \u2500\u2500 Themes \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
    Themes only re-set the colour variables; layout/spacing are unaffected.
    theme="auto" follows the OS via prefers-color-scheme. */
 :host([theme="dark"]) {
-  --ag-ui-bg: #15151f;
-  --ag-ui-fg: #e8e8f2;
-  --ag-ui-assistant-bg: #25253a;
-  --ag-ui-hover: #303049;
-  --ag-ui-header-bg: #1f1f30;
-  --ag-ui-header-fg: #e8e8f2;
-  --ag-ui-border: #33334a;
-  --ag-ui-muted: #9aa0b4;
-  --ag-ui-shadow: 0 12px 32px rgba(0, 0, 0, 0.5);
+  --_bg: var(--ag-ui-bg, #15151f);
+  --_fg: var(--ag-ui-fg, #e8e8f2);
+  --_assistant-bg: var(--ag-ui-assistant-bg, #25253a);
+  --_hover: var(--ag-ui-hover, #303049);
+  --_header-bg: var(--ag-ui-header-bg, #1f1f30);
+  --_header-fg: var(--ag-ui-header-fg, #e8e8f2);
+  --_border: var(--ag-ui-border, #33334a);
+  --_muted: var(--ag-ui-muted, #9aa0b4);
+  --_shadow: var(--ag-ui-shadow, 0 12px 32px rgba(0, 0, 0, 0.5));
 }
 @media (prefers-color-scheme: dark) {
   :host([theme="auto"]) {
-    --ag-ui-bg: #15151f;
-    --ag-ui-fg: #e8e8f2;
-    --ag-ui-assistant-bg: #25253a;
-    --ag-ui-hover: #303049;
-    --ag-ui-header-bg: #1f1f30;
-    --ag-ui-header-fg: #e8e8f2;
-    --ag-ui-border: #33334a;
-    --ag-ui-muted: #9aa0b4;
-    --ag-ui-shadow: 0 12px 32px rgba(0, 0, 0, 0.5);
+    --_bg: var(--ag-ui-bg, #15151f);
+    --_fg: var(--ag-ui-fg, #e8e8f2);
+    --_assistant-bg: var(--ag-ui-assistant-bg, #25253a);
+    --_hover: var(--ag-ui-hover, #303049);
+    --_header-bg: var(--ag-ui-header-bg, #1f1f30);
+    --_header-fg: var(--ag-ui-header-fg, #e8e8f2);
+    --_border: var(--ag-ui-border, #33334a);
+    --_muted: var(--ag-ui-muted, #9aa0b4);
+    --_shadow: var(--ag-ui-shadow, 0 12px 32px rgba(0, 0, 0, 0.5));
   }
 }
 /* A terminal-flavoured "code" theme: dark, monospace, green accent. */
 :host([theme="code"]) {
-  --ag-ui-bg: #0d1117;
-  --ag-ui-fg: #c9d1d9;
-  --ag-ui-accent: #3fb950;
-  --ag-ui-user-bg: #238636;
-  --ag-ui-assistant-bg: #161b22;
-  --ag-ui-hover: #21262d;
-  --ag-ui-header-bg: #010409;
-  --ag-ui-header-fg: #c9d1d9;
-  --ag-ui-border: #30363d;
-  --ag-ui-muted: #8b949e;
-  --ag-ui-font: var(--ag-ui-code-font);
-  --ag-ui-shadow: 0 12px 32px rgba(0, 0, 0, 0.6);
+  --_bg: var(--ag-ui-bg, #0d1117);
+  --_fg: var(--ag-ui-fg, #c9d1d9);
+  --_accent: var(--ag-ui-accent, #3fb950);
+  --_user-bg: var(--ag-ui-user-bg, #238636);
+  --_assistant-bg: var(--ag-ui-assistant-bg, #161b22);
+  --_hover: var(--ag-ui-hover, #21262d);
+  --_header-bg: var(--ag-ui-header-bg, #010409);
+  --_header-fg: var(--ag-ui-header-fg, #c9d1d9);
+  --_border: var(--ag-ui-border, #30363d);
+  --_muted: var(--ag-ui-muted, #8b949e);
+  --_font: var(--ag-ui-font, var(--_code-font));
+  --_shadow: var(--ag-ui-shadow, 0 12px 32px rgba(0, 0, 0, 0.6));
 }
 /* \u2500\u2500 Density \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
 :host([density="compact"]) {
-  --ag-ui-font-size: 13px;
-  --ag-ui-space: 6px;
-  --ag-ui-pad: 10px;
-  --ag-ui-msg-pad: 5px 9px;
-  --ag-ui-msg-radius: 10px;
+  --_font-size: var(--ag-ui-font-size, 13px);
+  --_space: var(--ag-ui-space, 6px);
+  --_pad: var(--ag-ui-pad, 10px);
+  --_msg-pad: var(--ag-ui-msg-pad, 5px 9px);
+  --_msg-radius: var(--ag-ui-msg-radius, 10px);
 }
 /* \u2500\u2500 Placement presets \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
 :host([placement="bottom-left"]) {
-  --ag-ui-inset: auto auto 24px 24px;
+  --_inset: var(--ag-ui-inset, auto auto 24px 24px);
 }
 :host([placement="side"]) {
-  --ag-ui-inset: 0 0 0 auto;
-  --ag-ui-width: 420px;
-  --ag-ui-height: 100vh;
-  --ag-ui-max-height: 100vh;
-  --ag-ui-radius: 0;
+  --_inset: var(--ag-ui-inset, 0 0 0 auto);
+  --_width: var(--ag-ui-width, 420px);
+  --_height: var(--ag-ui-height, 100vh);
+  --_max-height: var(--ag-ui-max-height, 100vh);
+  --_radius: var(--ag-ui-radius, 0);
 }
 :host([placement="full"]) {
-  --ag-ui-inset: 0;
-  --ag-ui-width: 100vw;
-  --ag-ui-height: 100vh;
-  --ag-ui-max-width: 100vw;
-  --ag-ui-max-height: 100vh;
-  --ag-ui-radius: 0;
+  --_inset: var(--ag-ui-inset, 0);
+  --_width: var(--ag-ui-width, 100vw);
+  --_height: var(--ag-ui-height, 100vh);
+  --_max-width: var(--ag-ui-max-width, 100vw);
+  --_max-height: var(--ag-ui-max-height, 100vh);
+  --_radius: var(--ag-ui-radius, 0);
 }
 /* Page: full-bleed background with a centred reading column. Unlike
@@ -4554,85 +4649,20 @@ var STYLES = `
    padding on the scroll area + composer (no per-row wrapper), so user pills
    still right-align and the assistant well spans the column. */
 :host([placement="page"]) {
-  --ag-ui-inset: 0;
-  --ag-ui-width: 100vw;
-  --ag-ui-height: 100vh;
-  --ag-ui-max-width: 100vw;
-  --ag-ui-max-height: 100vh;
-  --ag-ui-radius: 0;
+  --_inset: var(--ag-ui-inset, 0);
+  --_width: var(--ag-ui-width, 100vw);
+  --_height: var(--ag-ui-height, 100vh);
+  --_max-width: var(--ag-ui-max-width, 100vw);
+  --_max-height: var(--ag-ui-max-height, 100vh);
+  --_radius: var(--ag-ui-radius, 0);
 }
 :host([placement="page"]) .messages {
-  padding-inline: max(var(--ag-ui-pad), calc((100% - var(--ag-ui-content-max-width)) / 2));
+  padding-inline: max(var(--_pad), calc((100% - var(--_content-max-width)) / 2));
 }
-:host([placement="page"]) /* Resize handle: a corner grip on a floating panel, an edge grip on a docked
-   one. Absent entirely where the placement is full-bleed, since there is
-   nothing to drag. */
-.resize-handle {
-  position: absolute;
-  z-index: 2;
-  background: transparent;
-  touch-action: none;
-}
-.resize-handle:focus-visible {
-  outline: 2px solid var(--ag-ui-accent);
-  outline-offset: -2px;
-}
-/* The grip sits at the corner the panel grows toward. Which corner that is
-   depends on the host's layout, not on placement, so the element measures it
-   and stamps data-resize-anchor with the edges that stay put.
-   Default (bottom-right pinned, the floating case) puts the grip top-left. */
-.resize-handle {
-  top: 0;
-  left: 0;
-  width: 14px;
-  height: 14px;
-  cursor: nwse-resize;
-}
-:host([data-resize-anchor~="left"]) .resize-handle {
-  left: auto;
-  right: 0;
-}
-:host([data-resize-anchor~="top"]) .resize-handle {
-  top: auto;
-  bottom: 0;
-}
-/* One axis flipped means the drag runs along the other diagonal. */
-:host([data-resize-anchor="top-right"]) .resize-handle,
-:host([data-resize-anchor="bottom-left"]) .resize-handle {
-  cursor: nesw-resize;
-}
-/* Docked: the placement owns the height, so only the inner edge is the user's. */
-:host([placement="sidebar"]) .resize-handle,
-:host([placement="side"]) .resize-handle {
-  top: 0;
-  bottom: auto;
-  width: 8px;
-  height: 100%;
-  cursor: ew-resize;
-}
-/* Full-bleed: nothing to drag. */
-:host([placement="full"]) .resize-handle,
-:host([placement="page"]) .resize-handle {
-  display: none;
-}
-.resize-handle[data-dragging] {
-  background: var(--ag-ui-accent);
-  opacity: 0.35;
-}
-.input-row {
-  padding-inline: max(12px, calc((100% - var(--ag-ui-content-max-width)) / 2));
+:host([placement="page"]) .input-row {
+  padding-inline: max(12px, calc((100% - var(--_content-max-width)) / 2));
 }
 /* The rows between the message list and the composer (skill chips, the
@@ -4641,12 +4671,12 @@ var STYLES = `
    margin-based, so each gets its own inline axis nudged by the same gutter. */
 :host([placement="page"]) .skill-chips,
 :host([placement="page"]) .attachment-tray {
-  padding-inline: max(12px, calc((100% - var(--ag-ui-content-max-width)) / 2));
+  padding-inline: max(12px, calc((100% - var(--_content-max-width)) / 2));
 }
 :host([placement="page"]) .skill-palette,
 :host([placement="page"]) .skill-hint {
-  margin-inline: max(12px, calc((100% - var(--ag-ui-content-max-width)) / 2));
+  margin-inline: max(12px, calc((100% - var(--_content-max-width)) / 2));
 }
 /* In the reading column the assistant well uses the full width; the user
@@ -4661,17 +4691,16 @@ var STYLES = `
    --ag-ui-position: static (and place this element in your own layout) for a
    host-managed push instead. */
 :host([placement="sidebar"]) {
-  --ag-ui-inset: 0 0 0 auto;
-  --ag-ui-width: 420px;
-  --ag-ui-height: 100vh;
-  --ag-ui-max-height: 100vh;
-  --ag-ui-radius: 0;
-  --ag-ui-rail-width: 52px;
+  --_inset: var(--ag-ui-inset, 0 0 0 auto);
+  --_width: var(--ag-ui-width, 420px);
+  --_height: var(--ag-ui-height, 100vh);
+  --_max-height: var(--ag-ui-max-height, 100vh);
+  --_radius: var(--ag-ui-radius, 0);
   transition: width 0.28s ease;
 }
 :host([placement="sidebar"][data-side="left"]) {
-  --ag-ui-inset: 0 auto 0 0;
+  --_inset: var(--ag-ui-inset, 0 auto 0 0);
 }
 :host([placement="sidebar"]) .chat {
@@ -4682,7 +4711,7 @@ var STYLES = `
    reveal the rail. Higher specificity than the generic collapse rules, so it
    wins regardless of source order. */
 :host([placement="sidebar"][collapsed]) {
-  width: var(--ag-ui-rail-width);
+  width: var(--_rail-width);
   height: 100vh;
   max-height: 100vh;
   bottom: 0;
@@ -4707,9 +4736,9 @@ var STYLES = `
   align-items: flex-start;
   justify-content: center;
   padding-top: 16px;
-  border: 1px solid var(--ag-ui-border);
-  background: var(--ag-ui-header-bg);
-  color: var(--ag-ui-header-fg);
+  border: 1px solid var(--_border);
+  background: var(--_header-bg);
+  color: var(--_header-fg);
   cursor: pointer;
 }
@@ -4723,13 +4752,13 @@ var STYLES = `
 /* Embedded: drop the floating chrome and the high z-index stacking context so
    the widget lives in the host's own layout (fixes overlay/z-index clashes). */
 :host([placement="embedded"]) {
-  --ag-ui-position: static;
-  --ag-ui-width: 100%;
-  --ag-ui-height: 100%;
-  --ag-ui-max-width: 100%;
-  --ag-ui-max-height: 100%;
-  --ag-ui-shadow: none;
-  --ag-ui-z-index: auto;
+  --_position: var(--ag-ui-position, static);
+  --_width: var(--ag-ui-width, 100%);
+  --_height: var(--ag-ui-height, 100%);
+  --_max-width: var(--ag-ui-max-width, 100%);
+  --_max-height: var(--ag-ui-max-height, 100%);
+  --_shadow: var(--ag-ui-shadow, none);
+  --_z-index: var(--ag-ui-z-index, auto);
 }
 .chat {
@@ -4738,10 +4767,10 @@ var STYLES = `
   flex-direction: column;
   flex: 1;
   min-height: 0;
-  background: var(--ag-ui-bg);
-  border: 1px solid var(--ag-ui-border);
-  border-radius: var(--ag-ui-radius);
-  box-shadow: var(--ag-ui-shadow);
+  background: var(--_bg);
+  border: 1px solid var(--_border);
+  border-radius: var(--_radius);
+  box-shadow: var(--_shadow);
   overflow: hidden;
 }
@@ -4751,9 +4780,9 @@ var STYLES = `
   justify-content: space-between;
   gap: 8px;
   padding: 10px 14px;
-  border-bottom: 1px solid var(--ag-ui-border);
-  background: var(--ag-ui-header-bg);
-  color: var(--ag-ui-header-fg);
+  border-bottom: 1px solid var(--_border);
+  background: var(--_header-bg);
+  color: var(--_header-fg);
 }
 .header-title {
@@ -4772,8 +4801,8 @@ var STYLES = `
   align-items: center;
   justify-content: center;
   flex: none;
-  width: var(--ag-ui-icon-size, 22px);
-  height: var(--ag-ui-icon-size, 22px);
+  width: var(--_icon-size);
+  height: var(--_icon-size);
   line-height: 1;
 }
@@ -4781,7 +4810,7 @@ var STYLES = `
   width: 100%;
   height: 100%;
   object-fit: contain;
-  border-radius: var(--ag-ui-icon-radius, 4px);
+  border-radius: var(--_icon-radius);
 }
 .header-controls {
@@ -4833,10 +4862,10 @@ var STYLES = `
 .messages {
   flex: 1;
   overflow-y: auto;
-  padding: var(--ag-ui-pad);
+  padding: var(--_pad);
   display: flex;
   flex-direction: column;
-  gap: var(--ag-ui-space);
+  gap: var(--_space);
 }
 /* Empty-state region (slot): centred while it's the only thing in the
@@ -4844,7 +4873,7 @@ var STYLES = `
 .empty {
   margin: auto;
   text-align: center;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
 }
 .empty[hidden] {
@@ -4860,22 +4889,22 @@ var STYLES = `
 .answer {
   display: flex;
   flex-direction: column;
-  gap: var(--ag-ui-space);
+  gap: var(--_space);
   align-self: stretch;
   min-width: 0;
 }
 :host([data-answer-well]) .answer {
-  padding: var(--ag-ui-pad);
-  background: var(--ag-ui-well-bg);
-  border: 1px solid var(--ag-ui-well-border);
-  border-radius: var(--ag-ui-radius);
+  padding: var(--_pad);
+  background: var(--_well-bg);
+  border: 1px solid var(--_well-border);
+  border-radius: var(--_radius);
 }
 .message {
   max-width: 80%;
-  padding: var(--ag-ui-msg-pad);
-  border-radius: var(--ag-ui-msg-radius);
+  padding: var(--_msg-pad);
+  border-radius: var(--_msg-radius);
   line-height: 1.4;
   white-space: pre-wrap;
   word-break: break-word;
@@ -4913,14 +4942,14 @@ var STYLES = `
 .message--user {
   align-self: flex-end;
-  background: var(--ag-ui-user-bg);
-  color: var(--ag-ui-user-fg);
+  background: var(--_user-bg);
+  color: var(--_user-fg);
   border-bottom-right-radius: 4px;
 }
 .message--assistant {
   align-self: flex-start;
-  background: var(--ag-ui-assistant-bg);
+  background: var(--_assistant-bg);
   border-bottom-left-radius: 4px;
   /* Assistant bubbles hold rendered markdown/HTML, so collapse the source
      whitespace the renderer leaves between block tags. */
@@ -4950,7 +4979,7 @@ var STYLES = `
 }
 .message--assistant a {
-  color: var(--ag-ui-accent);
+  color: var(--_accent);
   text-decoration: underline;
 }
@@ -4965,8 +4994,8 @@ var STYLES = `
 .message--assistant pre {
   padding: 8px 10px;
   overflow: auto;
-  background: var(--ag-ui-bg);
-  border: 1px solid var(--ag-ui-border);
+  background: var(--_bg);
+  border: 1px solid var(--_border);
   border-radius: 6px;
 }
@@ -4982,6 +5011,13 @@ var STYLES = `
   position: relative;
 }
+/* This button is the only reader of --ag-ui-surface and --ag-ui-text, and
+   neither had a default until the alias layer gave them one. Both references
+   used to resolve to nothing, dropping the declaration: the background fell
+   back to the initial transparent, and the hover/copied colour to the
+   inherited body colour. The defaults chosen upstream (transparent, and the
+   body foreground) reproduce that, so the rename repaints nothing. A raised
+   surface behind the button is a separate design question. */
 .code-copy {
   position: absolute;
   top: 4px;
@@ -4990,9 +5026,9 @@ var STYLES = `
   font: inherit;
   font-size: 0.75em;
   line-height: 1.6;
-  color: var(--ag-ui-muted);
-  background: var(--ag-ui-surface);
-  border: 1px solid var(--ag-ui-border);
+  color: var(--_muted);
+  background: var(--_surface);
+  border: 1px solid var(--_border);
   border-radius: 4px;
   cursor: pointer;
   opacity: 0;
@@ -5007,24 +5043,24 @@ var STYLES = `
 }
 .code-copy:hover {
-  color: var(--ag-ui-text);
-  background: var(--ag-ui-hover);
+  color: var(--_text);
+  background: var(--_hover);
 }
 .code-copy[data-state="copied"] {
   opacity: 1;
-  color: var(--ag-ui-text);
+  color: var(--_text);
 }
 .code-copy[data-state="failed"] {
   opacity: 1;
-  color: var(--ag-ui-danger, var(--ag-ui-text));
+  color: var(--_danger, var(--_text));
 }
 .message--assistant blockquote {
   padding-left: 10px;
-  border-left: 3px solid var(--ag-ui-border);
-  color: var(--ag-ui-muted);
+  border-left: 3px solid var(--_border);
+  color: var(--_muted);
 }
 /* Markdown tables. table/thead/tbody/tr/th/td are all in
@@ -5045,13 +5081,13 @@ var STYLES = `
 .message--assistant th,
 .message--assistant td {
   padding: 6px 10px;
-  border: 1px solid var(--ag-ui-border);
+  border: 1px solid var(--_border);
   text-align: left;
   vertical-align: top;
 }
 .message--assistant th {
-  background: var(--ag-ui-hover);
+  background: var(--_hover);
   font-weight: 600;
 }
@@ -5061,7 +5097,7 @@ var STYLES = `
   gap: 4px;
   align-items: center;
   padding: 12px 14px;
-  background: var(--ag-ui-assistant-bg);
+  background: var(--_assistant-bg);
   border-radius: 14px;
   border-bottom-left-radius: 4px;
 }
@@ -5070,7 +5106,7 @@ var STYLES = `
   width: 6px;
   height: 6px;
   border-radius: 50%;
-  background: var(--ag-ui-muted);
+  background: var(--_muted);
   animation: ag-ui-pending 1.2s infinite ease-in-out both;
 }
@@ -5103,7 +5139,7 @@ var STYLES = `
   flex-direction: column;
   gap: 4px;
   font-size: 12px;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
 }
 .thoughts-toggle {
@@ -5114,7 +5150,7 @@ var STYLES = `
   font: inherit;
   font-size: 12px;
   font-weight: 600;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
   cursor: pointer;
 }
@@ -5139,7 +5175,7 @@ var STYLES = `
 .thoughts-body {
   margin: 0;
   padding: 4px 0 4px 10px;
-  border-left: 2px solid var(--ag-ui-border);
+  border-left: 2px solid var(--_border);
   max-height: 220px;
   overflow: auto;
   white-space: pre-wrap;
@@ -5168,9 +5204,9 @@ var STYLES = `
   font-family: ui-monospace, "SF Mono", Menlo, monospace;
   padding: 8px 10px;
   border-radius: 8px;
-  background: var(--ag-ui-tool-bg);
-  border: 1px solid var(--ag-ui-border);
-  color: var(--ag-ui-tool-fg);
+  background: var(--_tool-bg);
+  border: 1px solid var(--_border);
+  color: var(--_tool-fg);
 }
 .tool-call-head {
@@ -5203,10 +5239,10 @@ var STYLES = `
 /* Pending: a real spinning ring. Speed is tunable; reduced motion stops it. */
 .tool-call[data-status="pending"] .tool-call-icon {
-  border: 2px solid var(--ag-ui-muted);
+  border: 2px solid var(--_muted);
   border-top-color: transparent;
   border-radius: 50%;
-  animation: ag-ui-tool-spin var(--ag-ui-tool-spin-duration) linear infinite;
+  animation: ag-ui-tool-spin var(--_tool-spin-duration) linear infinite;
 }
 @keyframes ag-ui-tool-spin {
@@ -5215,18 +5251,18 @@ var STYLES = `
 /* Settled: a themeable glyph coloured by outcome. */
 .tool-call[data-status="done"] .tool-call-icon::before {
-  content: var(--ag-ui-tool-icon-done);
-  color: var(--ag-ui-success);
+  content: var(--_tool-icon-done);
+  color: var(--_success);
 }
 .tool-call[data-status="error"] .tool-call-icon::before {
-  content: var(--ag-ui-tool-icon-error);
-  color: var(--ag-ui-danger);
+  content: var(--_tool-icon-error);
+  color: var(--_danger);
 }
 .tool-call[data-status="declined"] .tool-call-icon::before {
-  content: var(--ag-ui-tool-icon-declined);
-  color: var(--ag-ui-muted);
+  content: var(--_tool-icon-declined);
+  color: var(--_muted);
 }
 @media (prefers-reduced-motion: reduce) {
@@ -5252,19 +5288,19 @@ var STYLES = `
   font-size: 11px;
   font-weight: 600;
   background: rgba(127, 127, 127, 0.16);
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
 }
 .tool-call[data-status="done"] .tool-call-status {
-  color: var(--ag-ui-success);
+  color: var(--_success);
 }
 .tool-call[data-status="error"] .tool-call-status {
-  color: var(--ag-ui-danger);
+  color: var(--_danger);
 }
 .tool-call[data-status="declined"] .tool-call-status {
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
 }
 .tool-call-body {
@@ -5286,7 +5322,7 @@ var STYLES = `
   font-weight: 700;
   letter-spacing: 0.06em;
   text-transform: uppercase;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
 }
 /* The record of a human decision on a gated call. An approved call used to
@@ -5294,7 +5330,7 @@ var STYLES = `
 .skill-item-token {
   font-family: ui-monospace, "SF Mono", Menlo, monospace;
   font-size: 0.92em;
-  color: var(--ag-ui-accent);
+  color: var(--_accent);
   margin-right: 6px;
 }
@@ -5302,7 +5338,7 @@ var STYLES = `
   flex: none;
   font-size: 11px;
   font-style: italic;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
 }
 .tool-call-args,
@@ -5311,12 +5347,12 @@ var STYLES = `
   padding: 6px 8px;
   max-height: 160px;
   overflow: auto;
-  background: var(--ag-ui-bg);
-  border: 1px solid var(--ag-ui-border);
+  background: var(--_bg);
+  border: 1px solid var(--_border);
   border-radius: 6px;
   white-space: pre-wrap;
   word-break: break-word;
-  color: var(--ag-ui-fg);
+  color: var(--_fg);
 }
 /* Display modes are pure visibility over one DOM shape, selected from the host
@@ -5363,7 +5399,7 @@ var STYLES = `
   background: none;
   font: inherit;
   font-weight: 600;
-  color: var(--ag-ui-accent);
+  color: var(--_accent);
   cursor: pointer;
 }
@@ -5386,13 +5422,12 @@ var STYLES = `
 }
 .resize-handle:focus-visible {
-  outline: 2px solid var(--ag-ui-accent);
+  outline: 2px solid var(--_accent);
   outline-offset: -2px;
 }
 /* The grip sits on the corner opposite the panel's anchor, because a resize
-   measures from whichever edge is not moving. Selected from the host attribute,
-   so switching placement moves the grip immediately.
+   measures from whichever edge is not moving.
    Default is floating: pinned bottom-right, so the grip is top-left. */
 .resize-handle {
@@ -5403,7 +5438,9 @@ var STYLES = `
   cursor: nwse-resize;
 }
-/* Embedded sits in normal flow, pinned top-left, so it grows bottom-right. */
+/* Placement is only the opening guess, and these two rules are all it is good
+   for. Embedded sits in normal flow, pinned top-left, so it grows bottom-right;
+   bottom-left is pinned there, so its free corner is top-right. */
 :host([placement="embedded"]) .resize-handle {
   top: auto;
   left: auto;
@@ -5412,16 +5449,64 @@ var STYLES = `
   cursor: nwse-resize;
 }
-/* Pinned bottom-left, so the free corner is top-right. */
 :host([placement="bottom-left"]) .resize-handle {
   left: auto;
   right: 0;
   cursor: nesw-resize;
 }
-/* Docked: the placement owns the height, so only the inner edge is the user's. */
+/* Then the measurement corrects it. Which edges are held still belongs to the
+   host's layout rather than to placement -- a floating panel a host right-aligns
+   is anchored bottom-left, not bottom-right -- so the element measures the edges
+   that stay put and stamps them here as "<y>-<x>". Equal specificity to the
+   rules above, so source order is what lets the measured value win.
+   These must not be written as [data-resize-anchor~="left"]: the stamped value
+   is one hyphenated token, and ~= matches whitespace-separated words, so such a
+   selector cannot ever match. It did not, which left the grip drawn at the
+   corner that moves while the cursor pointed along the right diagonal.
+   Each rule also sets both sides of its axis rather than only the side it
+   moves. One that flipped a single way could not undo a placement guess that
+   had flipped the other, which put the grip on the anchored corner for an
+   embedded panel its host right-aligns. */
+:host([data-resize-anchor$="-left"]) .resize-handle {
+  left: auto;
+  right: 0;
+}
+:host([data-resize-anchor$="-right"]) .resize-handle {
+  left: 0;
+  right: auto;
+}
+:host([data-resize-anchor^="top-"]) .resize-handle {
+  top: auto;
+  bottom: 0;
+}
+:host([data-resize-anchor^="bottom-"]) .resize-handle {
+  top: 0;
+  bottom: auto;
+}
+/* One axis flipped means the drag runs along the other diagonal. */
+:host([data-resize-anchor="top-left"]) .resize-handle,
+:host([data-resize-anchor="bottom-right"]) .resize-handle {
+  cursor: nwse-resize;
+}
+:host([data-resize-anchor="top-right"]) .resize-handle,
+:host([data-resize-anchor="bottom-left"]) .resize-handle {
+  cursor: nesw-resize;
+}
+/* Docked: the placement owns the height, so only the inner edge is the user's --
+   an edge, not a corner, so this outranks the measured anchor by coming after. */
 :host([placement="sidebar"]) .resize-handle,
 :host([placement="side"]) .resize-handle {
+  top: 0;
+  bottom: auto;
   width: 8px;
   height: 100%;
   cursor: ew-resize;
@@ -5440,7 +5525,7 @@ var STYLES = `
 }
 .resize-handle[data-dragging] {
-  background: var(--ag-ui-accent);
+  background: var(--_accent);
   opacity: 0.35;
 }
@@ -5448,14 +5533,14 @@ var STYLES = `
   display: flex;
   gap: 8px;
   padding: 12px;
-  border-top: 1px solid var(--ag-ui-border);
+  border-top: 1px solid var(--_border);
 }
 .input {
   flex: 1;
   resize: none;
-  background: var(--ag-ui-input-bg);
-  border: 1px solid var(--ag-ui-border);
+  background: var(--_input-bg);
+  border: 1px solid var(--_border);
   border-radius: 8px;
   padding: 8px 10px;
   font: inherit;
@@ -5464,14 +5549,14 @@ var STYLES = `
 }
 .input:focus {
-  border-color: var(--ag-ui-accent);
+  border-color: var(--_accent);
 }
 .send {
   border: none;
   border-radius: 8px;
   padding: 0 16px;
-  background: var(--ag-ui-accent);
+  background: var(--_accent);
   color: #ffffff;
   font: inherit;
   font-weight: 600;
@@ -5485,23 +5570,23 @@ var STYLES = `
 /* The composer button doubles as the Stop control while a run is in flight. */
 .send[data-state="running"] {
-  background: var(--ag-ui-muted);
+  background: var(--_muted);
 }
 /* \u2500\u2500 File attachments \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
 /* The \u{1F4CE} picker button sits left of the input; hidden until data-attachments-url. */
 .attach-btn {
-  border: 1px solid var(--ag-ui-border);
+  border: 1px solid var(--_border);
   border-radius: 8px;
   padding: 0 10px;
-  background: var(--ag-ui-input-bg);
+  background: var(--_input-bg);
   color: inherit;
   font: inherit;
   cursor: pointer;
 }
 .attach-btn:hover {
-  border-color: var(--ag-ui-accent);
+  border-color: var(--_accent);
 }
 .attach-input {
@@ -5514,17 +5599,17 @@ var STYLES = `
 }
 .voice-btn {
-  border: 1px solid var(--ag-ui-border);
+  border: 1px solid var(--_border);
   border-radius: 8px;
   padding: 0 10px;
-  background: var(--ag-ui-input-bg);
+  background: var(--_input-bg);
   color: inherit;
   font: inherit;
   cursor: pointer;
 }
 .voice-btn:hover {
-  border-color: var(--ag-ui-accent);
+  border-color: var(--_accent);
 }
 .voice-btn:disabled {
@@ -5534,8 +5619,8 @@ var STYLES = `
 /* Recording: a red tint + a gentle pulse so it's clearly "live". */
 .voice-btn[data-state="recording"] {
-  border-color: var(--ag-ui-danger);
-  background: var(--ag-ui-danger);
+  border-color: var(--_danger);
+  background: var(--_danger);
   color: #ffffff;
   animation: ag-ui-voice-pulse 1.2s ease-in-out infinite;
 }
@@ -5578,10 +5663,10 @@ var STYLES = `
   max-width: 100%;
   margin: 2px 0;
   padding: 3px 10px;
-  border: 1px dashed var(--ag-ui-border);
+  border: 1px dashed var(--_border);
   border-radius: 999px;
   background: transparent;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
   font-size: 0.8em;
   line-height: 1.4;
 }
@@ -5602,16 +5687,16 @@ var STYLES = `
   gap: 6px;
   max-width: 100%;
   padding: 4px 8px;
-  border: 1px solid var(--ag-ui-border);
+  border: 1px solid var(--_border);
   border-radius: 999px;
-  background: var(--ag-ui-assistant-bg);
+  background: var(--_assistant-bg);
   font-size: 0.85em;
   position: relative;
 }
 .attachment-chip--error {
-  border-color: var(--ag-ui-danger);
-  color: var(--ag-ui-danger);
+  border-color: var(--_danger);
+  color: var(--_danger);
 }
 .attachment-chip-name {
@@ -5622,12 +5707,12 @@ var STYLES = `
 }
 .attachment-chip-size {
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
   white-space: nowrap;
 }
 .attachment-chip--error .attachment-chip-size {
-  color: var(--ag-ui-danger);
+  color: var(--_danger);
 }
 /* The progress bar fills as the file uploads. */
@@ -5635,13 +5720,13 @@ var STYLES = `
   flex-basis: 100%;
   height: 3px;
   border-radius: 2px;
-  background: var(--ag-ui-border);
+  background: var(--_border);
   overflow: hidden;
 }
 .attachment-chip-bar-fill {
   height: 100%;
-  background: var(--ag-ui-accent);
+  background: var(--_accent);
   transition: width 0.15s ease;
 }
@@ -5663,14 +5748,14 @@ var STYLES = `
 /* A subtle outline while a file is dragged over the shell. */
 .chat--dragover {
-  outline: 2px dashed var(--ag-ui-accent);
+  outline: 2px dashed var(--_accent);
   outline-offset: -4px;
 }
 /* Muted "\u23F9 Stopped" line after a cancelled run \u2014 a note, not an error bubble. */
 .stopped-note {
   align-self: flex-start;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
   font-size: 12px;
   padding: 2px 4px;
 }
@@ -5683,14 +5768,14 @@ var STYLES = `
   flex-direction: column;
   gap: 8px;
   padding: 12px;
-  background: var(--ag-ui-bg);
-  border: 1px solid var(--ag-ui-accent);
+  background: var(--_bg);
+  border: 1px solid var(--_accent);
   border-radius: 10px;
 }
 .confirm[data-resolved] {
   opacity: 0.7;
-  border-color: var(--ag-ui-border);
+  border-color: var(--_border);
 }
 .confirm-body {
@@ -5704,7 +5789,7 @@ var STYLES = `
   overflow: auto;
   font-size: 12px;
   font-family: ui-monospace, "SF Mono", Menlo, monospace;
-  background: var(--ag-ui-assistant-bg);
+  background: var(--_assistant-bg);
   border-radius: 8px;
   white-space: pre-wrap;
   word-break: break-word;
@@ -5717,14 +5802,14 @@ var STYLES = `
 }
 .confirm-btn {
-  border: 1px solid var(--ag-ui-border);
+  border: 1px solid var(--_border);
   border-radius: 8px;
   padding: 8px 14px;
   font: inherit;
   font-weight: 600;
   cursor: pointer;
-  background: var(--ag-ui-bg);
-  color: var(--ag-ui-fg);
+  background: var(--_bg);
+  color: var(--_fg);
 }
 .confirm-btn:disabled {
@@ -5733,8 +5818,8 @@ var STYLES = `
 }
 .confirm-btn--confirm {
-  border-color: var(--ag-ui-accent);
-  background: var(--ag-ui-accent);
+  border-color: var(--_accent);
+  background: var(--_accent);
   color: #ffffff;
 }
@@ -5746,14 +5831,14 @@ var STYLES = `
   flex-direction: column;
   gap: 8px;
   padding: 12px;
-  background: var(--ag-ui-bg);
-  border: 1px solid var(--ag-ui-accent);
+  background: var(--_bg);
+  border: 1px solid var(--_accent);
   border-radius: 10px;
 }
 .approval[data-resolved] {
   opacity: 0.7;
-  border-color: var(--ag-ui-border);
+  border-color: var(--_border);
 }
 .approval-body {
@@ -5767,14 +5852,14 @@ var STYLES = `
 }
 .approval-btn {
-  border: 1px solid var(--ag-ui-border);
+  border: 1px solid var(--_border);
   border-radius: 8px;
   padding: 8px 14px;
   font: inherit;
   font-weight: 600;
   cursor: pointer;
-  background: var(--ag-ui-bg);
-  color: var(--ag-ui-fg);
+  background: var(--_bg);
+  color: var(--_fg);
 }
 .approval-btn:disabled {
@@ -5783,8 +5868,8 @@ var STYLES = `
 }
 .approval-btn--approve {
-  border-color: var(--ag-ui-accent);
-  background: var(--ag-ui-accent);
+  border-color: var(--_accent);
+  background: var(--_accent);
   color: #ffffff;
 }
@@ -5796,14 +5881,14 @@ var STYLES = `
   flex-direction: column;
   gap: 8px;
   padding: 12px;
-  background: var(--ag-ui-bg);
-  border: 1px solid var(--ag-ui-accent);
+  background: var(--_bg);
+  border: 1px solid var(--_accent);
   border-radius: 10px;
 }
 .question[data-resolved] {
   opacity: 0.7;
-  border-color: var(--ag-ui-border);
+  border-color: var(--_border);
 }
 .question-body {
@@ -5828,9 +5913,9 @@ var STYLES = `
   width: 100%;
   padding: 8px 10px;
   font: inherit;
-  color: var(--ag-ui-fg);
-  background: var(--ag-ui-bg);
-  border: 1px solid var(--ag-ui-border);
+  color: var(--_fg);
+  background: var(--_bg);
+  border: 1px solid var(--_border);
   border-radius: 8px;
 }
@@ -5844,13 +5929,13 @@ var STYLES = `
 }
 .question-btn {
-  border: 1px solid var(--ag-ui-accent);
+  border: 1px solid var(--_accent);
   border-radius: 8px;
   padding: 8px 14px;
   font: inherit;
   font-weight: 600;
   cursor: pointer;
-  background: var(--ag-ui-accent);
+  background: var(--_accent);
   color: #ffffff;
 }
@@ -5868,18 +5953,18 @@ var STYLES = `
 }
 .skill-chip {
-  border: 1px solid var(--ag-ui-border);
+  border: 1px solid var(--_border);
   border-radius: 999px;
   padding: 4px 12px;
   font: inherit;
   font-size: 0.9em;
   cursor: pointer;
-  background: var(--ag-ui-assistant-bg);
-  color: var(--ag-ui-fg);
+  background: var(--_assistant-bg);
+  color: var(--_fg);
 }
 .skill-chip:hover {
-  border-color: var(--ag-ui-accent);
+  border-color: var(--_accent);
 }
 .skill-palette {
@@ -5888,8 +5973,8 @@ var STYLES = `
   flex-direction: column;
   max-height: 220px;
   overflow: auto;
-  background: var(--ag-ui-bg);
-  border: 1px solid var(--ag-ui-border);
+  background: var(--_bg);
+  border: 1px solid var(--_border);
   border-radius: 8px;
   box-shadow: 0 8px 24px rgba(20, 20, 50, 0.16);
 }
@@ -5905,11 +5990,11 @@ var STYLES = `
   font: inherit;
   text-align: left;
   cursor: pointer;
-  color: var(--ag-ui-fg);
+  color: var(--_fg);
 }
 .skill-item[aria-selected="true"] {
-  background: var(--ag-ui-assistant-bg);
+  background: var(--_assistant-bg);
 }
 .skill-item-title {
@@ -5918,7 +6003,7 @@ var STYLES = `
 .skill-item-desc {
   font-size: 0.85em;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
 }
 /* The hint sits directly above the composer's top border, so a zero bottom
@@ -5927,7 +6012,7 @@ var STYLES = `
   margin: 8px 12px;
   font-size: 0.85em;
   line-height: 1.4;
-  color: var(--ag-ui-danger);
+  color: var(--_danger);
 }
 /* Chat-history drawer \u2014 a slide-over within the chat panel. */
@@ -5951,9 +6036,9 @@ var STYLES = `
   flex-direction: column;
   gap: 0.25rem;
   padding: 0.5rem;
-  border: 1px solid var(--ag-ui-border);
+  border: 1px solid var(--_border);
   border-radius: 0.5rem;
-  background: var(--ag-ui-assistant-bg);
+  background: var(--_assistant-bg);
   box-shadow: 0 6px 24px rgb(0 0 0 / 12%);
   max-height: 60%;
   overflow-y: auto;
@@ -5984,7 +6069,7 @@ var STYLES = `
 }
 .checkpoint-row:hover {
-  background: var(--ag-ui-hover);
+  background: var(--_hover);
 }
 .checkpoint-label {
@@ -5999,7 +6084,7 @@ var STYLES = `
   font-size: 0.6875rem;
   padding: 0 0.375rem;
   border-radius: 999px;
-  background: var(--ag-ui-hover);
+  background: var(--_hover);
   opacity: 0.8;
 }
@@ -6008,14 +6093,14 @@ var STYLES = `
   font-size: 0.75rem;
   cursor: pointer;
   padding: 0.125rem 0.5rem;
-  border: 1px solid var(--ag-ui-border);
+  border: 1px solid var(--_border);
   border-radius: 0.375rem;
   background: transparent;
   color: inherit;
 }
 .checkpoint-action:hover {
-  background: var(--ag-ui-hover);
+  background: var(--_hover);
 }
 .drawer-backdrop {
@@ -6030,9 +6115,9 @@ var STYLES = `
   flex-direction: column;
   width: min(300px, 85%);
   height: 100%;
-  background: var(--ag-ui-bg);
-  border-right: 1px solid var(--ag-ui-border);
-  box-shadow: var(--ag-ui-shadow);
+  background: var(--_bg);
+  border-right: 1px solid var(--_border);
+  box-shadow: var(--_shadow);
   overflow: hidden;
 }
@@ -6040,9 +6125,9 @@ var STYLES = `
   display: flex;
   align-items: center;
   justify-content: space-between;
-  gap: var(--ag-ui-space);
-  padding: var(--ag-ui-pad);
-  border-bottom: 1px solid var(--ag-ui-border);
+  gap: var(--_space);
+  padding: var(--_pad);
+  border-bottom: 1px solid var(--_border);
 }
 .drawer-title {
@@ -6050,10 +6135,10 @@ var STYLES = `
 }
 .drawer-new {
-  border: 1px solid var(--ag-ui-border);
-  border-radius: var(--ag-ui-radius);
-  background: var(--ag-ui-bg);
-  color: var(--ag-ui-accent);
+  border: 1px solid var(--_border);
+  border-radius: var(--_radius);
+  background: var(--_bg);
+  color: var(--_accent);
   padding: 4px 10px;
   font: inherit;
   font-size: 0.85em;
@@ -6067,19 +6152,19 @@ var STYLES = `
 }
 .drawer-empty {
-  padding: var(--ag-ui-pad);
+  padding: var(--_pad);
   font-size: 0.9em;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
 }
 .drawer-row {
   display: flex;
   align-items: stretch;
-  border-bottom: 1px solid var(--ag-ui-border);
+  border-bottom: 1px solid var(--_border);
 }
 .drawer-row--active {
-  background: var(--ag-ui-assistant-bg);
+  background: var(--_assistant-bg);
 }
 .drawer-row-select {
@@ -6106,12 +6191,12 @@ var STYLES = `
 .drawer-row-time {
   font-size: 0.72em;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
 }
 .drawer-row-preview {
   font-size: 0.8em;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
   overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
@@ -6128,7 +6213,7 @@ var STYLES = `
 .drawer-row-delete {
   border: none;
   background: none;
-  color: var(--ag-ui-muted);
+  color: var(--_muted);
   font-size: 0.9em;
   padding: 4px;
   cursor: pointer;
@@ -6139,10 +6224,10 @@ var STYLES = `
   min-width: 0;
   margin: 6px 10px;
   padding: 4px 8px;
-  border: 1px solid var(--ag-ui-accent);
+  border: 1px solid var(--_accent);
   border-radius: 6px;
-  background: var(--ag-ui-input-bg);
-  color: var(--ag-ui-fg);
+  background: var(--_input-bg);
+  color: var(--_fg);
   font: inherit;
 }
@@ -6155,13 +6240,13 @@ var STYLES = `
 }
 .drawer-confirm-label {
-  color: var(--ag-ui-danger);
+  color: var(--_danger);
 }
 .drawer-confirm-yes {
   border: none;
   border-radius: 6px;
-  background: var(--ag-ui-danger);
+  background: var(--_danger);
   color: #ffffff;
   padding: 3px 10px;
   font: inherit;
@@ -6169,7 +6254,7 @@ var STYLES = `
 }
 .drawer-confirm-no {
-  border: 1px solid var(--ag-ui-border);
+  border: 1px solid var(--_border);
   border-radius: 6px;
   background: none;
   color: inherit;
@@ -7232,6 +7317,13 @@ function truncate(text2, limit) {
 // src/core/create_http_agent.ts
 import { HttpAgent } from "@ag-ui/client";
+// src/core/utils.ts
+function withCredentials(init, credentials) {
+  return credentials === void 0 ? init : { ...init, credentials };
+}
+// src/core/create_http_agent.ts
 function createHttpAgent(options) {
   return new HttpAgent({
     url: options.endpoint,
@@ -7242,17 +7334,18 @@ function createHttpAgent(options) {
     // "Illegal invocation" in browsers. Wrap it so `fetch` is always called as
     // a free function with the correct receiver. The wrapper also overlays
     // `getHeaders()` per request, so header rotation (CSRF, short-lived JWT)
-    // reaches the stream even though the agent instance is cached.
+    // reaches the stream even though the agent instance is cached, and applies
+    // the configured cookie policy — the agent's own config has no seam for it.
     fetch: (url, init) => {
       const fresh = options.getHeaders?.();
       if (fresh === void 0) {
-        return fetch(url, init);
+        return fetch(url, withCredentials(init, options.credentials));
       }
       const headers = new Headers(init?.headers);
       for (const [name, value] of Object.entries(fresh)) {
         headers.set(name, value);
       }
-      return fetch(url, { ...init, headers });
+      return fetch(url, withCredentials({ ...init, headers }, options.credentials));
     },
     // Spread conditionally: under `exactOptionalPropertyTypes` an explicit
     // `undefined` is not assignable to these optional config fields.
@@ -7266,12 +7359,14 @@ var RemoteConversationStore = class {
   #url;
   #headers;
   #local;
+  #credentials;
   #dropped = /* @__PURE__ */ new Set();
   #renamed = /* @__PURE__ */ new Map();
-  constructor(url, headers = () => ({}), local = new SessionStorageStore()) {
+  constructor(url, headers = () => ({}), local = new SessionStorageStore(), credentials = () => void 0) {
     this.#url = url.endsWith("/") ? url : `${url}/`;
     this.#headers = headers;
     this.#local = local;
+    this.#credentials = credentials;
   }
   threadId() {
     return this.#local.threadId();
@@ -7349,7 +7444,7 @@ var RemoteConversationStore = class {
   /** GET that resolves to the `Response`, or `null` on a network error. */
   async #get(url) {
     try {
-      return await fetch(url, { headers: this.#headers() });
+      return await fetch(url, withCredentials({ headers: this.#headers() }, this.#credentials()));
     } catch {
       return null;
     }
@@ -7358,11 +7453,17 @@ var RemoteConversationStore = class {
   async #mutate(threadId, method, body) {
     const headers = this.#headers();
     try {
-      await fetch(`${this.#url}${encodeURIComponent(threadId)}/`, {
-        method,
-        headers: body === void 0 ? headers : { ...headers, "content-type": "application/json" },
-        body: body === void 0 ? null : JSON.stringify(body)
-      });
+      await fetch(
+        `${this.#url}${encodeURIComponent(threadId)}/`,
+        withCredentials(
+          {
+            method,
+            headers: body === void 0 ? headers : { ...headers, "content-type": "application/json" },
+            body: body === void 0 ? null : JSON.stringify(body)
+          },
+          this.#credentials()
+        )
+      );
     } catch {
     }
   }
@@ -7372,9 +7473,11 @@ var RemoteConversationStore = class {
 var RunIndex = class {
   #url;
   #headers;
-  constructor(url, headers = () => ({})) {
+  #credentials;
+  constructor(url, headers = () => ({}), credentials = () => void 0) {
     this.#url = url.endsWith("/") ? url : `${url}/`;
     this.#headers = headers;
+    this.#credentials = credentials;
   }
   /**
    * The user's runs, or `[]` when the endpoint is unreachable or answers with
@@ -7384,10 +7487,16 @@ var RunIndex = class {
    */
   async list() {
     try {
-      const response = await fetch(this.#url, {
-        method: "GET",
-        headers: { Accept: "application/json", ...this.#headers() }
-      });
+      const response = await fetch(
+        this.#url,
+        withCredentials(
+          {
+            method: "GET",
+            headers: { Accept: "application/json", ...this.#headers() }
+          },
+          this.#credentials()
+        )
+      );
       if (!response.ok) {
         return [];
       }
@@ -7426,11 +7535,17 @@ var RunIndex = class {
 async function transcribeAudio(audio, options) {
   const form = new FormData();
   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));
   }
@@ -7458,6 +7573,7 @@ function uploadAttachment(file, options) {
     form.append("file", file);
     const xhr = new XMLHttpRequest();
     xhr.open("POST", options.url);
+    xhr.withCredentials = options.credentials === "include";
     for (const [key, value] of Object.entries(options.headers ?? {})) {
       xhr.setRequestHeader(key, value);
     }
@@ -7531,14 +7647,42 @@ var CONNECT_TIME_ATTRIBUTES = [
   "data-strings",
   "data-icon-url"
 ];
+var CREDENTIALS_MODES = ["omit", "same-origin", "include"];
+function isCredentialsMode(value) {
+  return CREDENTIALS_MODES.includes(value);
+}
 var COLLAPSED_KEY = "ag-ui-chat:collapsed";
 var SIZE_KEY = "ag-ui-chat:size";
 var THEME_KEY = "ag-ui-chat:theme";
 var AgUiChat = class extends HTMLElement {
   /** Agent factory; override to inject a custom or fake agent (tests). */
   agentFactory = createHttpAgent;
-  /** Extra HTTP headers for the AG-UI endpoint (e.g. CSRF). */
+  /**
+   * Static extra HTTP headers, sent with **every** request this element makes —
+   * the agent run, the thread index and its messages, the tool and skill
+   * catalogs, the run index, uploads and transcription.
+   *
+   * Right for values fixed for the element's lifetime. A credential that
+   * rotates (a short-lived JWT, a re-issued CSRF token) belongs in
+   * {@link getHeaders} instead: this is read at request time, but only a
+   * re-assignment updates it, so a token captured here is pinned until the host
+   * remembers to assign again.
+   */
   headers = {};
+  /**
+   * Live header source, consulted immediately before every request — the way to
+   * supply rotating credentials.
+   *
+   * Set it to a function and each request calls it afresh: a token refreshed by
+   * the host between two requests reaches the second one, with nothing to
+   * re-assign and nothing to keep in sync.
+   *
+   * Composes with {@link headers} rather than replacing it: the two are merged
+   * per key with `getHeaders()` winning, so a static `X-Client` and a rotating
+   * `Authorization` can be configured independently and neither silently drops
+   * the other.
+   */
+  getHeaders = null;
   /**
    * Permit `<img>` in rendered assistant markdown. **Off by default**: a
    * model-controlled image URL is fetched with no user interaction, which
@@ -7825,7 +7969,11 @@ var AgUiChat = class extends HTMLElement {
       return null;
     }
     if (this.#runIndex === null) {
-      this.#runIndex = new RunIndex(url, () => this.headers);
+      this.#runIndex = new RunIndex(
+        url,
+        () => this.#requestHeaders(),
+        () => this.#requestCredentials()
+      );
     }
     return this.#runIndex;
   }
@@ -7857,8 +8005,9 @@ var AgUiChat = class extends HTMLElement {
     const endpoint = verb === "resume" ? index.resumeUrl(runId) : index.forkUrl(runId);
     const agent = this.agentFactory({
       endpoint,
-      headers: this.headers,
-      getHeaders: () => this.headers,
+      headers: this.#requestHeaders(),
+      getHeaders: () => this.#requestHeaders(),
+      ...this.#credentialsOption(),
       threadId: this.#threadId,
       // The seed the endpoints assume: nothing. The snapshot is the history.
       initialMessages: []
@@ -7881,10 +8030,19 @@ var AgUiChat = class extends HTMLElement {
   }
   /** Attributes the element reacts to after it has been connected. */
   static get observedAttributes() {
-    return ["title-text", "placement", ...CONNECT_TIME_ATTRIBUTES];
+    return ["title-text", "placement", "credentials", ...CONNECT_TIME_ATTRIBUTES];
   }
   attributeChangedCallback(name, previous, value) {
+    if (name === "credentials") {
+      if (value !== null && !isCredentialsMode(value)) {
+        console.error(
+          `<ag-ui-chat>: credentials="${value}" is not a fetch credentials mode (${CREDENTIALS_MODES.join(" / ")}) \u2014 it is being ignored, so requests use the browser default and cross-origin cookies will not be sent.`
+        );
+      }
+      return;
+    }
     if (name === "placement") {
+      this.#releaseOwnedAxes();
       requestAnimationFrame(() => this.#syncResizeAnchor());
       return;
     }
@@ -8073,6 +8231,72 @@ var AgUiChat = class extends HTMLElement {
   set endpoint(value) {
     this.setAttribute("endpoint", value);
   }
+  /**
+   * Cookie policy for **every** request this element makes, as `fetch`'s own
+   * `credentials` mode (`"omit"` / `"same-origin"` / `"include"`). Mirrored to
+   * the `credentials` attribute, so markup embeds can set it without script.
+   *
+   * `null` (the default) leaves the browser's default of `same-origin` in
+   * place. That default sends **no cookies at all** when the endpoints live on
+   * a different origin from the page — app.example.com calling
+   * api.example.com is cross-origin — and the request goes out anonymously
+   * rather than failing, so the symptom is a 401 from a server that looks
+   * correctly configured. A cookie-authenticated cross-origin deployment wants
+   * `"include"`, plus `Access-Control-Allow-Credentials: true` and a concrete
+   * (non-wildcard) `Access-Control-Allow-Origin` on the server.
+   *
+   * Read per request, so a late assignment applies to everything after it.
+   * `"omit"` cannot be honoured by the built-in **upload** transport, which is
+   * an `XMLHttpRequest` and only has a two-state cookie switch; every other
+   * endpoint honours all three modes.
+   */
+  get credentials() {
+    const attr = this.getAttribute("credentials");
+    return attr !== null && isCredentialsMode(attr) ? attr : null;
+  }
+  set credentials(value) {
+    if (value === null) {
+      this.removeAttribute("credentials");
+      return;
+    }
+    if (!isCredentialsMode(value)) {
+      throw new TypeError(
+        `<ag-ui-chat>: credentials must be one of ${CREDENTIALS_MODES.map((mode) => `"${mode}"`).join(", ")} (got ${JSON.stringify(value)}).`
+      );
+    }
+    this.setAttribute("credentials", value);
+  }
+  /**
+   * The headers for the request about to go out: the static {@link headers}
+   * with {@link getHeaders}'s live values overlaid, per key.
+   *
+   * Every request site goes through here, so "how this element authenticates"
+   * is one answer rather than one per endpoint.
+   */
+  #requestHeaders() {
+    return { ...this.headers, ...this.getHeaders?.() };
+  }
+  /** The configured cookie policy as `fetch` spells it; `undefined` when unset. */
+  #requestCredentials() {
+    return this.credentials ?? void 0;
+  }
+  /**
+   * The `credentials` entry for an {@link AgentFactory} call, or nothing at all.
+   *
+   * Spread rather than assigned: `exactOptionalPropertyTypes` rejects an
+   * explicit `credentials: undefined`, and a factory should see the field
+   * absent — not present-and-empty — when no policy is configured. The agent
+   * reads it when it is built (first send, thread switch, continuation), by
+   * which time any host configuration has landed.
+   */
+  #credentialsOption() {
+    const credentials = this.#requestCredentials();
+    return credentials === void 0 ? {} : { credentials };
+  }
+  /** The `fetch` init for the element's own plain GETs (catalogs). */
+  #fetchInit() {
+    return withCredentials({ headers: this.#requestHeaders() }, this.#requestCredentials());
+  }
   /**
    * How much detail tool-call cards show, from the `data-tool-display`
    * attribute (`minimal` / `inline` / `compact` / `full`). Defaults to `full`.
@@ -8110,7 +8334,6 @@ var AgUiChat = class extends HTMLElement {
     }
     this.#syncRail();
     this.#initSkills();
-    void this.#fetchToolCatalog();
     if (this.#storageNs !== "" && this.conversationStore instanceof SessionStorageStore) {
       this.conversationStore = new SessionStorageStore(this.#storageNs);
     }
@@ -8118,9 +8341,62 @@ var AgUiChat = class extends HTMLElement {
     this.#wireAttachments();
     this.#wireVoice();
     this.#threadId = this.conversationStore.threadId();
+    queueMicrotask(() => this.#startup());
     void this.#rehydrate();
     this.#connected = true;
   }
+  /**
+   * The catalog requests the element issues on startup: the tool labels
+   * (`data-tools-url`) and the backend skills (`data-skills-url`).
+   *
+   * Deliberately one microtask behind `connectedCallback`. A host that
+   * configures the element through a framework ref necessarily does so *after*
+   * inserting the node — React attaches refs and runs layout effects in the
+   * same commit as the insertion, but strictly afterwards — so a request issued
+   * from `connectedCallback` itself goes out before `headers`,
+   * {@link getHeaders} or {@link credentials} exist, and comes back 401 in a
+   * way that reads as a server fault rather than a mis-timed assignment. A
+   * microtask lands after that commit and still before paint.
+   *
+   * Two things it is **not**. It is not a fix for configuration that arrives
+   * later than the commit (a passive `useEffect`, an awaited token fetch):
+   * configure before insertion (`createElement` → configure → `append`) or call
+   * {@link reload} once configured, because a longer timer would hide that race
+   * rather than close it. And it deliberately excludes the *history* replay,
+   * which stays in `connectedCallback`: the replay renders into the transcript,
+   * so deferring it lets a `sendMessage()` issued in the same task land first
+   * and the replay then duplicate it. The thread history is therefore the one
+   * request that can still go out before a ref is attached — {@link reload}
+   * covers it.
+   */
+  #startup() {
+    if (!this.#connected) {
+      return;
+    }
+    void this.#fetchToolCatalog();
+    void this.#fetchSkills();
+  }
+  /**
+   * Re-run everything the element loads on startup — the tool-label catalog,
+   * the backend skill catalog and the thread's history — with the transport
+   * configuration as it stands now.
+   *
+   * This is the answer for a host that can only configure the element after the
+   * fact (a token fetched in a passive effect, an async auth handshake): the
+   * startup requests already went out with whatever was set then, and this says
+   * "try again, properly authenticated" without removing and re-inserting the
+   * node.
+   *
+   * A reload, not a merge — the in-flight run is cancelled and the transcript
+   * is rebuilt from the persisted history, so anything streamed since is
+   * dropped. Call it once, when configuration lands; not between turns.
+   */
+  async reload() {
+    this.#cancelRun();
+    this.#resetState();
+    this.#setRunning(false);
+    await Promise.all([this.#fetchToolCatalog(), this.#fetchSkills(), this.#rehydrate()]);
+  }
   /**
    * Tear down live resources when the element leaves the DOM (a removed node, a
    * client-side route swap): cancel the in-flight run so its SSE stream closes,
@@ -8202,7 +8478,13 @@ var AgUiChat = class extends HTMLElement {
     if (url === null) {
       return null;
     }
-    return (file, onProgress, signal) => uploadAttachment(file, { url, headers: this.headers, onProgress, signal });
+    return (file, onProgress, signal) => uploadAttachment(file, {
+      url,
+      headers: this.#requestHeaders(),
+      ...this.#credentialsOption(),
+      onProgress,
+      signal
+    });
   }
   /**
    * Reveal the composer's 🎤 mic button when transcription is possible — either
@@ -8229,7 +8511,11 @@ var AgUiChat = class extends HTMLElement {
     if (url === null) {
       return null;
     }
-    return (audio) => transcribeAudio(audio, { url, headers: this.headers });
+    return (audio) => transcribeAudio(audio, {
+      url,
+      headers: this.#requestHeaders(),
+      ...this.#credentialsOption()
+    });
   }
   /** Drop a voice transcript into the composer (appended to any typed text). */
   #insertVoiceText(text2) {
@@ -8304,8 +8590,9 @@ Use the read_attachment tool with an id to read a file's contents.`
     if (url !== null) {
       this.conversationStore = new RemoteConversationStore(
         url,
-        () => this.headers,
-        this.conversationStore
+        () => this.#requestHeaders(),
+        this.conversationStore,
+        () => this.#requestCredentials()
       );
     }
   }
@@ -8316,7 +8603,7 @@ Use the read_attachment tool with an id to read a file's contents.`
       return;
     }
     try {
-      const response = await fetch(url, { headers: this.headers });
+      const response = await fetch(url, this.#fetchInit());
       this.#toolCatalog = parseToolCatalog(await response.json());
     } catch {
     }
@@ -8329,13 +8616,16 @@ Use the read_attachment tool with an id to read a file's contents.`
     this.#clientSkills = skills;
     this.#recomputeSkills();
   }
-  /** Wire the skill surfaces: opt-in flags, embedded catalog, optional fetch. */
+  /**
+   * Wire the skill surfaces: opt-in flags and the embedded catalog. The backend
+   * catalog is fetched from `#startup`, a microtask later, so it carries the
+   * host's transport configuration.
+   */
   #initSkills() {
     this.#skillsMenu.enableChips(this.#flag("data-prompt-chips"));
     this.#skillsMenu.enableSlash(this.#flag("data-slash-commands"));
     this.#embedSkills = this.#readEmbeddedSkills();
     this.#recomputeSkills();
-    void this.#fetchSkills();
   }
   /** Parse the inline `data-skills` JSON catalog (empty when absent/malformed). */
   #readEmbeddedSkills() {
@@ -8356,7 +8646,7 @@ Use the read_attachment tool with an id to read a file's contents.`
       return;
     }
     try {
-      const response = await fetch(url, { headers: this.headers });
+      const response = await fetch(url, this.#fetchInit());
       this.#backendSkills = parseSkills(await response.json());
       this.#recomputeSkills();
     } catch {
@@ -8531,21 +8821,45 @@ Use the read_attachment tool with an id to read a file's contents.`
     this.style.setProperty(name, value);
   }
   /**
-   * Write a dragged size onto the host as custom properties.
+   * Write a dragged size onto the host, on the axes this placement leaves free.
    *
-   * Properties rather than inline `width` / `height`: the placement rules set
-   * those same properties, so an inline dimension would outrank them and a
-   * panel dragged while floating would keep that width after switching to
-   * fullscreen.
+   * ⚠ Writing the custom property rather than inline `width` / `height` does
+   * **not** by itself leave placement in charge — an inline custom property
+   * still outranks a `:host([placement=…])` rule setting the same property, so
+   * a height dragged while floating capped a docked sidebar that had asked for
+   * `100vh`. The cascade cannot arbitrate this; the axis check has to.
+   *
+   * So the rule is explicit: a placement owns the axes it fixes, and a
+   * persisted size is only ever applied to the ones it does not.
    */
   #applySize(size) {
+    const axis = this.#resizeAxis();
+    if (axis === "none") {
+      return;
+    }
     if (size.width !== void 0) {
       this.style.setProperty("--ag-ui-width", `${size.width}px`);
     }
-    if (size.height !== void 0) {
+    if (size.height !== void 0 && axis === "both") {
       this.style.setProperty("--ag-ui-height", `${size.height}px`);
     }
   }
+  /**
+   * Drop any dragged size the new placement has taken ownership of.
+   *
+   * Without this a size survives the switch as an inline property and silently
+   * overrides the placement it moved to — the panel keeps a floating height
+   * while docked, and reads as a component that cannot do full height.
+   */
+  #releaseOwnedAxes() {
+    const axis = this.#resizeAxis();
+    if (axis !== "both") {
+      this.style.removeProperty("--ag-ui-height");
+    }
+    if (axis === "none") {
+      this.style.removeProperty("--ag-ui-width");
+    }
+  }
   /** Persist a dragged size per tab, alongside the collapsed/theme preferences. */
   #persistSize(size) {
     const stored = { ...this.#readSize(), ...size };
@@ -8585,6 +8899,32 @@ Use the read_attachment tool with an id to read a file's contents.`
     const dark = this.getAttribute("theme") === "dark";
     this.#themeToggle.textContent = dark ? "\u2600\uFE0F" : "\u{1F319}";
   }
+  /**
+   * Open the thread-history drawer: the imperative route to the control that
+   * renders as `::part(history-button)`.
+   *
+   * A host that hides `::part(header)` to render its own title bar hides the
+   * history, new-chat and collapse buttons with it — and thread switching then
+   * has no route at all, because those controls live inside the header. Each of
+   * them has a method, so a host chrome can rebuild the set: this one,
+   * {@link openCheckpoints}, {@link newChat}, {@link toggleCollapsed} and
+   * {@link toggleTheme}.
+   */
+  openThreads() {
+    void this.#refreshDrawer();
+    this.#drawer.open();
+  }
+  /**
+   * Open the checkpoints panel (the `::part(checkpoints-button)` route).
+   *
+   * It lists the runs the `data-runs-url` server reports as continuable;
+   * without that attribute the built-in button is never rendered and this opens
+   * an empty panel.
+   */
+  openCheckpoints() {
+    void this.#refreshCheckpoints();
+    this.#checkpoints.open();
+  }
   /**
    * Start a fresh conversation: forget the persisted history, drop the
    * in-memory run state, clear the transcript, and mint a new thread id.
@@ -8855,15 +9195,9 @@ Use the read_attachment tool with an id to read a file's contents.`
     controls.className = "header-controls";
     controls.setAttribute("part", "header-controls");
     const history = this.#headerButton("history", this.#strings.chatHistory, "\u2630");
-    history.addEventListener("click", () => {
-      void this.#refreshDrawer();
-      this.#drawer.open();
-    });
+    history.addEventListener("click", () => this.openThreads());
     const checkpoints = this.#headerButton("checkpoints", this.#strings.checkpoints, "\u2B6F");
-    checkpoints.addEventListener("click", () => {
-      void this.#refreshCheckpoints();
-      this.#checkpoints.open();
-    });
+    checkpoints.addEventListener("click", () => this.openCheckpoints());
     const newChat = this.#headerButton("new", this.#strings.newChat, "\u271A");
     newChat.addEventListener("click", () => this.newChat());
     const collapse = this.#headerButton("collapse", this.#strings.collapse, "\u2014");
@@ -9164,11 +9498,12 @@ Use the read_attachment tool with an id to read a file's contents.`
     if (this.#client === null) {
       const agent = this.agentFactory({
         endpoint: this.endpoint,
-        headers: this.headers,
+        headers: this.#requestHeaders(),
         // Live getter: the client is built once and cached, but a rotated
         // token must still reach every request — the factory's fetch wrapper
         // re-reads this on each call.
-        getHeaders: () => this.headers,
+        getHeaders: () => this.#requestHeaders(),
+        ...this.#credentialsOption(),
         threadId: this.#threadId,
         initialMessages: this.#initialMessages,
         initialState: this.#sharedState
@@ -9538,24 +9873,24 @@ function defineAgUiChat() {
 // src/dom/dom_driver.ts
 async function fillField(el, value, options = {}) {
-  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);
 }
 async function clickElement(el, options = {}) {
-  scrollIntoCenterView(el);
+  await scrollIntoCenterView(el);
   await highlightThenClick(el, options);
 }
 async function pressButton(el, options = {}) {
-  scrollIntoCenterView(el);
+  await scrollIntoCenterView(el);
   await pressThenClick(el, options);
 }
 async function selectControl(el, value, options = {}) {
-  scrollIntoCenterView(el);
+  await scrollIntoCenterView(el);
   await selectOption(el, value, options);
 }
 async function toggleCheckbox(el, checked, options = {}) {
-  scrollIntoCenterView(el);
+  await scrollIntoCenterView(el);
   await toggleControl(el, checked, options);
 }
 function setControlValue(el, value) {
@@ -9569,7 +9904,7 @@ function setControlValue(el, value) {
 }
 // src/version.ts
-var VERSION = "0.20.0";
+var VERSION = "0.21.0";
 export {
   ATTACHMENT_EVENT,
   AgUiChat,
@@ -9607,6 +9942,7 @@ export {
   createStateHookTools,
   defineAgUiChat,
   fillField,
+  flash,
   focusWithFlash,
   highlightThenClick,
   isDestructive,