@assistant-ui/vue 0.0.0-stage → 0.0.1

package/dist/useAuiState.d.ts

@@ -0,0 +1,23 @@
+import { type ComputedRef } from "vue";
+import { type AssistantState } from "@assistant-ui/store/client";
+/**
+ * Subscribes to a slice of `AssistantState` and returns it as a computed ref.
+ *
+ * The `selector` runs on every store update; dependents re-run only when the
+ * selected slice changes by `Object.is`. Returning the entire state object is
+ * not supported and throws — select a specific field instead, or compose
+ * multiple `useAuiState` calls. Returning a fresh object or array literal
+ * re-triggers dependents on every update; select primitives or a memoized
+ * reference.
+ *
+ * Scopes that may be unavailable can be read via `s.optional.<scope>`, which
+ * resolves to `undefined` instead of throwing.
+ *
+ * @example
+ * ```ts
+ * const isRunning = useAuiState((s) => s.thread.isRunning);
+ * // template: <button :disabled="isRunning">…</button>
+ * ```
+ */
+export declare const useAuiState: <T>(selector: (state: AssistantState) => T) => ComputedRef<T>;
+//# sourceMappingURL=useAuiState.d.ts.map

package/dist/useAuiState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAuiState.d.ts","sourceRoot":"","sources":["../src/useAuiState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAC7E,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AAGpC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAC3B,UAAU,CAAC,KAAK,EAAE,cAAc,KAAK,CAAC,KACrC,WAAW,CAAC,CAAC,CA0Bf,CAAC"}

package/dist/useAuiState.js

@@ -0,0 +1,42 @@
+import { useAuiContext } from "./context.js";
+import { computed, onScopeDispose, shallowRef } from "vue";
+import { getProxiedAssistantState } from "@assistant-ui/store/client";
+//#region src/useAuiState.ts
+/**
+* Subscribes to a slice of `AssistantState` and returns it as a computed ref.
+*
+* The `selector` runs on every store update; dependents re-run only when the
+* selected slice changes by `Object.is`. Returning the entire state object is
+* not supported and throws — select a specific field instead, or compose
+* multiple `useAuiState` calls. Returning a fresh object or array literal
+* re-triggers dependents on every update; select primitives or a memoized
+* reference.
+*
+* Scopes that may be unavailable can be read via `s.optional.<scope>`, which
+* resolves to `undefined` instead of throwing.
+*
+* @example
+* ```ts
+* const isRunning = useAuiState((s) => s.thread.isRunning);
+* // template: <button :disabled="isRunning">…</button>
+* ```
+*/
+const useAuiState = (selector) => {
+	const { source } = useAuiContext();
+	const version = shallowRef(0);
+	const unsubscribe = source.subscribe(() => {
+		version.value++;
+	});
+	onScopeDispose(unsubscribe);
+	return computed(() => {
+		version.value;
+		const state = getProxiedAssistantState(source.getClient());
+		const slice = selector(state);
+		if (typeof slice === "object" && slice !== null && (slice === state || slice === state.optional)) throw new Error("You tried to return the entire AssistantState. This is not supported due to technical limitations.");
+		return slice;
+	});
+};
+//#endregion
+export { useAuiState };
+
+//# sourceMappingURL=useAuiState.js.map

package/dist/useAuiState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAuiState.js","names":[],"sources":["../src/useAuiState.ts"],"sourcesContent":["import { computed, onScopeDispose, shallowRef, type ComputedRef } from \"vue\";\nimport {\n  getProxiedAssistantState,\n  type AssistantState,\n} from \"@assistant-ui/store/client\";\nimport { useAuiContext } from \"./context\";\n\n/**\n * Subscribes to a slice of `AssistantState` and returns it as a computed ref.\n *\n * The `selector` runs on every store update; dependents re-run only when the\n * selected slice changes by `Object.is`. Returning the entire state object is\n * not supported and throws — select a specific field instead, or compose\n * multiple `useAuiState` calls. Returning a fresh object or array literal\n * re-triggers dependents on every update; select primitives or a memoized\n * reference.\n *\n * Scopes that may be unavailable can be read via `s.optional.<scope>`, which\n * resolves to `undefined` instead of throwing.\n *\n * @example\n * ```ts\n * const isRunning = useAuiState((s) => s.thread.isRunning);\n * // template: <button :disabled=\"isRunning\">…</button>\n * ```\n */\nexport const useAuiState = <T>(\n  selector: (state: AssistantState) => T,\n): ComputedRef<T> => {\n  const { source } = useAuiContext();\n\n  const version = shallowRef(0);\n  const unsubscribe = source.subscribe(() => {\n    version.value++;\n  });\n  onScopeDispose(unsubscribe);\n\n  return computed(() => {\n    void version.value;\n    const state = getProxiedAssistantState(source.getClient());\n    const slice = selector(state);\n\n    if (\n      typeof slice === \"object\" &&\n      slice !== null &&\n      ((slice as unknown) === state || (slice as unknown) === state.optional)\n    ) {\n      throw new Error(\n        \"You tried to return the entire AssistantState. This is not supported due to technical limitations.\",\n      );\n    }\n\n    return slice;\n  });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AA0BA,MAAa,eACX,aACmB;CACnB,MAAM,EAAE,WAAW,cAAc;CAEjC,MAAM,UAAU,WAAW,CAAC;CAC5B,MAAM,cAAc,OAAO,gBAAgB;EACzC,QAAQ;CACV,CAAC;CACD,eAAe,WAAW;CAE1B,OAAO,eAAe;EACpB,QAAa;EACb,MAAM,QAAQ,yBAAyB,OAAO,UAAU,CAAC;EACzD,MAAM,QAAQ,SAAS,KAAK;EAE5B,IACE,OAAO,UAAU,YACjB,UAAU,SACR,UAAsB,SAAU,UAAsB,MAAM,WAE9D,MAAM,IAAI,MACR,oGACF;EAGF,OAAO;CACT,CAAC;AACH"}

package/dist/useScrollLock.d.ts

@@ -0,0 +1,3 @@
+import { type Ref } from "vue";
+export declare const useScrollLock: (target: Ref<HTMLElement | null | undefined>, animationDuration: number) => () => void;
+//# sourceMappingURL=useScrollLock.d.ts.map

package/dist/useScrollLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollLock.d.ts","sourceRoot":"","sources":["../src/useScrollLock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AAY/C,eAAO,MAAM,aAAa,GACxB,QAAQ,GAAG,CAAC,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,EAC3C,mBAAmB,MAAM,eAgE1B,CAAC"}

package/dist/useScrollLock.js

@@ -0,0 +1,53 @@
+import { onScopeDispose } from "vue";
+//#region src/useScrollLock.ts
+const findScrollableAncestor = (element) => {
+	let current = element;
+	while (current) {
+		const { overflowY } = getComputedStyle(current);
+		if (overflowY === "scroll" || overflowY === "auto") return current;
+		current = current.parentElement;
+	}
+	return null;
+};
+const useScrollLock = (target, animationDuration) => {
+	let cleanup = null;
+	onScopeDispose(() => cleanup?.());
+	return () => {
+		cleanup?.();
+		const scrollContainer = findScrollableAncestor(target.value);
+		if (!scrollContainer) {
+			cleanup = null;
+			return;
+		}
+		const scrollPosition = scrollContainer.scrollTop;
+		const scrollbarWidth = scrollContainer.style.scrollbarWidth;
+		const computed = getComputedStyle(scrollContainer);
+		const paddingSide = computed.direction === "rtl" ? "paddingLeft" : "paddingRight";
+		const previousPadding = scrollContainer.style[paddingSide];
+		const elementScrollbarSize = scrollContainer.offsetWidth - scrollContainer.clientWidth - parseFloat(computed.borderLeftWidth) - parseFloat(computed.borderRightWidth);
+		const ownerDocument = scrollContainer.ownerDocument;
+		const scrollbarSize = (scrollContainer === ownerDocument.documentElement || scrollContainer === ownerDocument.body) && elementScrollbarSize <= 0 ? (ownerDocument.defaultView?.innerWidth ?? 0) - ownerDocument.documentElement.clientWidth : elementScrollbarSize;
+		scrollContainer.style.scrollbarWidth = "none";
+		if (scrollbarSize > 0) scrollContainer.style[paddingSide] = `${parseFloat(computed[paddingSide]) + scrollbarSize}px`;
+		const restoreStyles = () => {
+			scrollContainer.style.scrollbarWidth = scrollbarWidth;
+			scrollContainer.style[paddingSide] = previousPadding;
+		};
+		const resetPosition = () => scrollContainer.scrollTop = scrollPosition;
+		scrollContainer.addEventListener("scroll", resetPosition);
+		const timeoutId = setTimeout(() => {
+			scrollContainer.removeEventListener("scroll", resetPosition);
+			restoreStyles();
+			cleanup = null;
+		}, animationDuration);
+		cleanup = () => {
+			clearTimeout(timeoutId);
+			scrollContainer.removeEventListener("scroll", resetPosition);
+			restoreStyles();
+		};
+	};
+};
+//#endregion
+export { useScrollLock };
+
+//# sourceMappingURL=useScrollLock.js.map

package/dist/useScrollLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollLock.js","names":[],"sources":["../src/useScrollLock.ts"],"sourcesContent":["import { onScopeDispose, type Ref } from \"vue\";\n\nconst findScrollableAncestor = (element: HTMLElement | null | undefined) => {\n  let current = element;\n  while (current) {\n    const { overflowY } = getComputedStyle(current);\n    if (overflowY === \"scroll\" || overflowY === \"auto\") return current;\n    current = current.parentElement;\n  }\n  return null;\n};\n\nexport const useScrollLock = (\n  target: Ref<HTMLElement | null | undefined>,\n  animationDuration: number,\n) => {\n  let cleanup: (() => void) | null = null;\n\n  onScopeDispose(() => cleanup?.());\n\n  return () => {\n    cleanup?.();\n\n    const scrollContainer = findScrollableAncestor(target.value);\n    if (!scrollContainer) {\n      cleanup = null;\n      return;\n    }\n\n    const scrollPosition = scrollContainer.scrollTop;\n    const scrollbarWidth = scrollContainer.style.scrollbarWidth;\n    const computed = getComputedStyle(scrollContainer);\n    const paddingSide =\n      computed.direction === \"rtl\" ? \"paddingLeft\" : \"paddingRight\";\n    const previousPadding = scrollContainer.style[paddingSide];\n    const elementScrollbarSize =\n      scrollContainer.offsetWidth -\n      scrollContainer.clientWidth -\n      parseFloat(computed.borderLeftWidth) -\n      parseFloat(computed.borderRightWidth);\n    // Root offsetWidth excludes the viewport scrollbar, so use the viewport\n    // width only when the element's own gutter is absent.\n    const ownerDocument = scrollContainer.ownerDocument;\n    const isRootScroller =\n      scrollContainer === ownerDocument.documentElement ||\n      scrollContainer === ownerDocument.body;\n    const scrollbarSize =\n      isRootScroller && elementScrollbarSize <= 0\n        ? (ownerDocument.defaultView?.innerWidth ?? 0) -\n          ownerDocument.documentElement.clientWidth\n        : elementScrollbarSize;\n\n    scrollContainer.style.scrollbarWidth = \"none\";\n    if (scrollbarSize > 0) {\n      scrollContainer.style[paddingSide] = `${\n        parseFloat(computed[paddingSide]) + scrollbarSize\n      }px`;\n    }\n\n    const restoreStyles = () => {\n      scrollContainer.style.scrollbarWidth = scrollbarWidth;\n      scrollContainer.style[paddingSide] = previousPadding;\n    };\n    const resetPosition = () => (scrollContainer.scrollTop = scrollPosition);\n    scrollContainer.addEventListener(\"scroll\", resetPosition);\n\n    const timeoutId = setTimeout(() => {\n      scrollContainer.removeEventListener(\"scroll\", resetPosition);\n      restoreStyles();\n      cleanup = null;\n    }, animationDuration);\n\n    cleanup = () => {\n      clearTimeout(timeoutId);\n      scrollContainer.removeEventListener(\"scroll\", resetPosition);\n      restoreStyles();\n    };\n  };\n};\n"],"mappings":";;AAEA,MAAM,0BAA0B,YAA4C;CAC1E,IAAI,UAAU;CACd,OAAO,SAAS;EACd,MAAM,EAAE,cAAc,iBAAiB,OAAO;EAC9C,IAAI,cAAc,YAAY,cAAc,QAAQ,OAAO;EAC3D,UAAU,QAAQ;CACpB;CACA,OAAO;AACT;AAEA,MAAa,iBACX,QACA,sBACG;CACH,IAAI,UAA+B;CAEnC,qBAAqB,UAAU,CAAC;CAEhC,aAAa;EACX,UAAU;EAEV,MAAM,kBAAkB,uBAAuB,OAAO,KAAK;EAC3D,IAAI,CAAC,iBAAiB;GACpB,UAAU;GACV;EACF;EAEA,MAAM,iBAAiB,gBAAgB;EACvC,MAAM,iBAAiB,gBAAgB,MAAM;EAC7C,MAAM,WAAW,iBAAiB,eAAe;EACjD,MAAM,cACJ,SAAS,cAAc,QAAQ,gBAAgB;EACjD,MAAM,kBAAkB,gBAAgB,MAAM;EAC9C,MAAM,uBACJ,gBAAgB,cAChB,gBAAgB,cAChB,WAAW,SAAS,eAAe,IACnC,WAAW,SAAS,gBAAgB;EAGtC,MAAM,gBAAgB,gBAAgB;EAItC,MAAM,iBAFJ,oBAAoB,cAAc,mBAClC,oBAAoB,cAAc,SAEhB,wBAAwB,KACrC,cAAc,aAAa,cAAc,KAC1C,cAAc,gBAAgB,cAC9B;EAEN,gBAAgB,MAAM,iBAAiB;EACvC,IAAI,gBAAgB,GAClB,gBAAgB,MAAM,eAAe,GACnC,WAAW,SAAS,YAAY,IAAI,cACrC;EAGH,MAAM,sBAAsB;GAC1B,gBAAgB,MAAM,iBAAiB;GACvC,gBAAgB,MAAM,eAAe;EACvC;EACA,MAAM,sBAAuB,gBAAgB,YAAY;EACzD,gBAAgB,iBAAiB,UAAU,aAAa;EAExD,MAAM,YAAY,iBAAiB;GACjC,gBAAgB,oBAAoB,UAAU,aAAa;GAC3D,cAAc;GACd,UAAU;EACZ,GAAG,iBAAiB;EAEpB,gBAAgB;GACd,aAAa,SAAS;GACtB,gBAAgB,oBAAoB,UAAU,aAAa;GAC3D,cAAc;EAChB;CACF;AACF"}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@assistant-ui/vue",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Vue bindings for assistant-ui",
+  "keywords": [
+    "assistant",
+    "ai",
+    "chat",
+    "vue",
+    "nuxt"
+  ],
+  "author": "AgentbaseAI Inc.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@assistant-ui/core": "^0.3.24",
+    "@assistant-ui/store": "^0.3.17",
+    "@assistant-ui/tap": "^0.9.21"
+  },
+  "peerDependencies": {
+    "@types/react": "*",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "0.0.30",
+    "@types/node": "^26.6.3",
+    "@types/react": "^19.3.0",
+    "assistant-cloud": "0.2.5",
+    "jsdom": "^30.0.1",
+    "vitest": "^5.0.3",
+    "vue": "^3.5.43"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "https://www.assistant-ui.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/assistant-ui/assistant-ui.git",
+    "directory": "packages/vue"
+  },
+  "bugs": {
+    "url": "https://github.com/assistant-ui/assistant-ui/issues"
+  },
+  "scripts": {
+    "build": "aui-build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text --coverage.reporter=html --coverage.reporter=json-summary",
+    "typecheck": "tsc --noEmit",
+    "test:watch": "vitest"
+  }
 }

package/src/AuiIf.ts

@@ -0,0 +1,34 @@
+import {
+  defineComponent,
+  type PropType,
+  type SlotsType,
+  type VNodeChild,
+} from "vue";
+import type { AssistantState } from "@assistant-ui/store/client";
+import { useAuiState } from "./useAuiState";
+
+/**
+ * Renders the default slot while `condition` selects `true` from the
+ * assistant state.
+ *
+ * @example
+ * ```html
+ * <AuiIf :condition="(s) => s.thread.isRunning">
+ *   <StopButton />
+ * </AuiIf>
+ * ```
+ */
+export const AuiIf = defineComponent({
+  name: "AuiIf",
+  props: {
+    condition: {
+      type: Function as PropType<(state: AssistantState) => boolean>,
+      required: true,
+    },
+  },
+  slots: Object as SlotsType<{ default?: () => VNodeChild[] }>,
+  setup(props, { slots }) {
+    const active = useAuiState((state) => props.condition(state));
+    return () => (active.value ? slots.default?.() : null);
+  },
+});

package/src/AuiProvider.ts

@@ -0,0 +1,90 @@
+import {
+  defineComponent,
+  inject,
+  onScopeDispose,
+  provide,
+  watch,
+  type PropType,
+  type SlotsType,
+  type VNodeChild,
+} from "vue";
+import {
+  createAssistantClient,
+  type AssistantClient,
+  type AuiConfig,
+} from "@assistant-ui/store/client";
+import { auiInjectionKey, createClientFacade } from "./context";
+import { isDevelopment } from "@assistant-ui/core/store/internal";
+
+/**
+ * Creates an `AssistantClient` from the given config and provides it to the
+ * subtree.
+ *
+ * At the top level, `config` alone creates this subtree's own client. Under a
+ * parent provider, `extends` is mandatory: pass `:extends="aui"` to extend the
+ * parent client or `:extends="null"` to isolate from it (enforced with a dev
+ * error).
+ *
+ * The `config` prop is live: passing a new config object updates element args
+ * in place (scopes keep their state) and mounts or unmounts added and removed
+ * scopes. Pass a computed config to derive it from reactive inputs. `extends`
+ * is captured when the provider mounts; remount (for example with a `key`) to
+ * change the parent.
+ */
+export const AuiProvider = defineComponent({
+  name: "AuiProvider",
+  props: {
+    config: {
+      type: Object as PropType<AuiConfig>,
+      required: true,
+    },
+    extends: {
+      type: Object as PropType<AssistantClient | null>,
+      default: undefined,
+    },
+  },
+  slots: Object as SlotsType<{ default?: () => VNodeChild[] }>,
+  setup(props, { slots }) {
+    const injected = inject(auiInjectionKey, null);
+    const hasExtends = props.extends !== undefined;
+
+    if (isDevelopment) {
+      if (injected && !hasExtends) {
+        throw new Error(
+          'A parent AuiProvider exists. Pass :extends="aui" to inherit it or :extends="null" to isolate.',
+        );
+      }
+    }
+
+    const parent = !hasExtends
+      ? injected?.source
+      : props.extends === null
+        ? undefined
+        : injected && props.extends === injected.aui
+          ? injected.source
+          : props.extends;
+
+    const handle = createAssistantClient(
+      {
+        getConfig: () => props.config,
+        subscribe: (listener) => watch(() => props.config, listener),
+      },
+      parent ? { parent } : undefined,
+    );
+    // The provider holds the lifetime subscription that keeps the client
+    // mounted while descendants come and go
+    const release = handle.subscribe(() => {});
+    onScopeDispose(release);
+
+    const source = {
+      getClient: handle.getClient,
+      subscribe: handle.subscribe,
+    };
+    provide(auiInjectionKey, {
+      source,
+      aui: createClientFacade(source),
+    });
+
+    return () => slots.default?.();
+  },
+});

package/src/__tests__/AuiIf.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, type Component } from "vue";
+import { flushTapSync } from "@assistant-ui/tap";
+import { AuiConfig } from "@assistant-ui/store/client";
+import { AuiProvider } from "../AuiProvider";
+import { AuiIf } from "../AuiIf";
+import { useAui } from "../useAui";
+import { ThreadClient, type AnyClient } from "./fixtures";
+
+const mountApp = (root: Component) => {
+  const app = createApp(root);
+  const el = document.createElement("div");
+  app.mount(el);
+  return { el, unmount: () => app.unmount() };
+};
+
+describe("AuiIf", () => {
+  it("renders the slot only while the condition selects true", async () => {
+    let aui!: AnyClient;
+    const Probe = defineComponent({
+      setup() {
+        aui = useAui() as AnyClient;
+        return () =>
+          h(
+            AuiIf,
+            { condition: (s) => (s as AnyClient).thread.selected === 1 },
+            { default: () => h("span", { id: "flag" }, "visible") },
+          );
+      },
+    });
+    const { el, unmount } = mountApp(
+      defineComponent({
+        setup: () => () =>
+          h(
+            AuiProvider,
+            { config: AuiConfig({ thread: ThreadClient() } as never) },
+            { default: () => h(Probe) },
+          ),
+      }),
+    );
+
+    expect(el.querySelector("#flag")).toBeNull();
+
+    flushTapSync(() => aui.thread.setSelected(1));
+    await nextTick();
+    expect(el.querySelector("#flag")?.textContent).toBe("visible");
+
+    flushTapSync(() => aui.thread.setSelected(0));
+    await nextTick();
+    expect(el.querySelector("#flag")).toBeNull();
+
+    unmount();
+  });
+});

package/src/__tests__/AuiProvider.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  createApp,
+  defineComponent,
+  h,
+  nextTick,
+  shallowRef,
+  type Component,
+} from "vue";
+import { flushTapSync } from "@assistant-ui/tap";
+import { AuiConfig, type AssistantClient } from "@assistant-ui/store/client";
+import { AuiProvider } from "../AuiProvider";
+import { useAui } from "../useAui";
+import {
+  MessageClient,
+  ThreadClient,
+  messageDerived,
+  trackers,
+  type AnyClient,
+} from "./fixtures";
+
+const mountApp = (root: Component) => {
+  const app = createApp(root);
+  const el = document.createElement("div");
+  app.mount(el);
+  return { app, unmount: () => app.unmount() };
+};
+
+const captureAui = () => {
+  let aui!: AnyClient;
+  const Probe = defineComponent({
+    setup() {
+      aui = useAui() as AnyClient;
+      return () => null;
+    },
+  });
+  return { Probe, getAui: () => aui };
+};
+
+describe("AuiProvider", () => {
+  it("provides a client built from the config", () => {
+    const { Probe, getAui } = captureAui();
+    const { unmount } = mountApp(
+      defineComponent({
+        setup: () => () =>
+          h(
+            AuiProvider,
+            { config: AuiConfig({ thread: ThreadClient() } as never) },
+            { default: () => h(Probe) },
+          ),
+      }),
+    );
+
+    expect(getAui().thread.getState()).toEqual({ selected: 0 });
+
+    flushTapSync(() => getAui().thread.setSelected(1));
+    expect(getAui().thread.getState()).toEqual({ selected: 1 });
+
+    unmount();
+  });
+
+  it("keeps the facade stable across structural changes", () => {
+    const { Probe, getAui } = captureAui();
+    const { unmount } = mountApp(
+      defineComponent({
+        setup: () => () =>
+          h(
+            AuiProvider,
+            {
+              config: AuiConfig({
+                thread: ThreadClient(),
+                message: messageDerived(),
+              } as never),
+            },
+            { default: () => h(Probe) },
+          ),
+      }),
+    );
+
+    const aui = getAui();
+    expect(aui.message.getState().id).toBe("m0");
+
+    flushTapSync(() => aui.thread.setSelected(1));
+
+    expect(getAui()).toBe(aui);
+    expect(aui.message.getState().id).toBe("m1");
+
+    unmount();
+  });
+
+  it("extends the parent provider's client with an explicit extends", () => {
+    const { Probe, getAui } = captureAui();
+    const Nested = defineComponent({
+      setup(_, { slots }) {
+        const aui = useAui();
+        return () =>
+          h(
+            AuiProvider,
+            {
+              config: AuiConfig({ message: messageDerived() } as never),
+              extends: aui,
+            },
+            { default: () => slots.default?.() },
+          );
+      },
+    });
+    const { unmount } = mountApp(
+      defineComponent({
+        setup: () => () =>
+          h(
+            AuiProvider,
+            { config: AuiConfig({ thread: ThreadClient() } as never) },
+            { default: () => h(Nested, null, { default: () => h(Probe) }) },
+          ),
+      }),
+    );
+
+    const aui = getAui();
+    expect(aui.message.getState().id).toBe("m0");
+    expect(aui.thread.getState()).toEqual({ selected: 0 });
+
+    flushTapSync(() => aui.thread.setSelected(1));
+    expect(aui.message.getState().id).toBe("m1");
+
+    unmount();
+  });
+
+  it("throws in dev when nested without an explicit extends", () => {
+    const Nested = defineComponent({
+      setup: () => () =>
+        h(
+          AuiProvider,
+          { config: AuiConfig({ message: messageDerived() } as never) },
+          { default: () => null },
+        ),
+    });
+    expect(() =>
+      mountApp(
+        defineComponent({
+          setup: () => () =>
+            h(
+              AuiProvider,
+              { config: AuiConfig({ thread: ThreadClient() } as never) },
+              { default: () => h(Nested) },
+            ),
+        }),
+      ),
+    ).toThrow("A parent AuiProvider exists.");
+  });
+
+  it("isolates from the parent with extends null", () => {
+    const { Probe, getAui } = captureAui();
+    const Isolated = defineComponent({
+      setup: () => () =>
+        h(
+          AuiProvider,
+          {
+            config: AuiConfig({
+              message: MessageClient({ id: "iso" }),
+            } as never),
+            extends: null,
+          },
+          { default: () => h(Probe) },
+        ),
+    });
+    const { unmount } = mountApp(
+      defineComponent({
+        setup: () => () =>
+          h(
+            AuiProvider,
+            { config: AuiConfig({ thread: ThreadClient() } as never) },
+            { default: () => h(Isolated) },
+          ),
+      }),
+    );
+
+    expect(getAui().message.getState()).toEqual({ id: "iso", text: "" });
+    expect(() => getAui().thread.getState()).toThrow(
+      'The current scope does not have a "thread" property.',
+    );
+
+    unmount();
+  });
+
+  it("applies config changes in place, keeping scope state", async () => {
+    const { Probe, getAui } = captureAui();
+    const config = shallowRef(
+      AuiConfig({ message: MessageClient({ id: "m0" }) } as never),
+    );
+    const { unmount } = mountApp(
+      defineComponent({
+        setup: () => () =>
+          h(AuiProvider, { config: config.value }, { default: () => h(Probe) }),
+      }),
+    );
+
+    flushTapSync(() => getAui().message.setText("draft"));
+    expect(getAui().message.getState()).toEqual({ id: "m0", text: "draft" });
+
+    config.value = AuiConfig({ message: MessageClient({ id: "m1" }) } as never);
+    await nextTick();
+    await vi.waitFor(() => {
+      expect(getAui().message.getState()).toEqual({ id: "m1", text: "draft" });
+    });
+
+    config.value = AuiConfig({
+      message: MessageClient({ id: "m1" }),
+      thread: ThreadClient(),
+    } as never);
+    await nextTick();
+    await vi.waitFor(() => {
+      expect(getAui().thread.getState()).toEqual({ selected: 0 });
+    });
+    expect(getAui().message.getState()).toEqual({ id: "m1", text: "draft" });
+
+    config.value = AuiConfig({ message: MessageClient({ id: "m1" }) } as never);
+    await nextTick();
+    await vi.waitFor(() => {
+      expect(() => getAui().thread.getState()).toThrow(
+        'The current scope does not have a "thread" property.',
+      );
+    });
+
+    unmount();
+  });
+
+  it("releases the client on unmount, soft unmounting its scopes", async () => {
+    const before = trackers.threadCleanups;
+    const { Probe } = captureAui();
+    const { unmount } = mountApp(
+      defineComponent({
+        setup: () => () =>
+          h(
+            AuiProvider,
+            { config: AuiConfig({ thread: ThreadClient() } as never) },
+            { default: () => h(Probe) },
+          ),
+      }),
+    );
+
+    const afterMount = trackers.threadCleanups;
+    unmount();
+    await vi.waitFor(() =>
+      expect(trackers.threadCleanups).toBe(afterMount + 1),
+    );
+    expect(afterMount).toBeGreaterThanOrEqual(before);
+  });
+
+  it("returns the throwing default client outside a provider", () => {
+    let aui!: AssistantClient;
+    const { unmount } = mountApp(
+      defineComponent({
+        setup() {
+          aui = useAui();
+          return () => null;
+        },
+      }),
+    );
+
+    expect(() => (aui as AnyClient).thread.getState()).toThrow(
+      "Wrap your component in an <AuiProvider> component.",
+    );
+
+    unmount();
+  });
+});