@cueplusplus/ui 0.13.0

package/dist/elements/agent-card.js

@@ -0,0 +1,91 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { field, inkButton, mono, paper } from "./surfaces.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { BotIcon, CheckIcon } from "lucide-react";
+//#region src/elements/agent-card.tsx
+/**
+* Who you are about to talk to: its skills, its model, and the endpoint behind it.
+*
+* @example
+* import { AgentCard } from "@cueplusplus/ui/elements";
+*
+* <AgentCard
+*   name="Maintainer"
+*   description="Reproduces the report, writes the fix, opens the PR."
+*   provider="assistant-ui"
+*   version="1.4.0"
+*   model="opus"
+*   endpoint="https://agents.example.com/a2a"
+*   skills={skills}
+*   connected={false}
+*   onConnect={connect}
+* />
+*/
+function AgentCard({ name, description, provider, version, model, endpoint, skills, connected, onConnect, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "agent-card",
+		className: cn(paper, "flex w-full max-w-sm flex-col gap-3.5 rounded-(--radius-overlay) p-4", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-start gap-3",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "bg-surface-1 text-fg-muted flex size-9 shrink-0 items-center justify-center rounded-(--radius-surface)",
+					children: /* @__PURE__ */ jsx(BotIcon, { className: "size-4" })
+				}), /* @__PURE__ */ jsxs("div", {
+					className: "flex min-w-0 flex-1 flex-col",
+					children: [/* @__PURE__ */ jsxs("span", {
+						className: "flex items-baseline gap-2",
+						children: [/* @__PURE__ */ jsx("span", {
+							className: "truncate text-(length:--cue-text-body) font-medium",
+							children: name
+						}), /* @__PURE__ */ jsxs("span", {
+							className: cn(mono, "text-fg-subtle shrink-0"),
+							children: ["v", version]
+						})]
+					}), /* @__PURE__ */ jsx("span", {
+						className: "text-fg-muted truncate text-(length:--cue-text-ui)",
+						children: provider
+					})]
+				})]
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "text-fg-muted text-(length:--cue-text-ui) leading-(--cue-leading-ui)",
+				children: description
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "flex flex-col gap-1.5",
+				children: skills.map((skill) => /* @__PURE__ */ jsxs("div", {
+					className: "flex items-baseline gap-2",
+					children: [/* @__PURE__ */ jsx("span", {
+						className: cn(field, mono, "text-fg-muted shrink-0 rounded-(--radius-control) px-1.5 py-0.5"),
+						children: skill.name
+					}), /* @__PURE__ */ jsx("span", {
+						className: "text-fg-muted min-w-0 flex-1 truncate text-(length:--cue-text-ui)",
+						children: skill.description
+					})]
+				}, skill.name))
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "border-border flex items-center gap-2 border-t pt-3",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: cn(mono, "text-fg-subtle min-w-0 flex-1 truncate"),
+					children: endpoint
+				}), /* @__PURE__ */ jsx("span", {
+					className: cn(mono, "text-fg-subtle shrink-0"),
+					children: model
+				})]
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				onClick: onConnect,
+				disabled: connected,
+				className: cn(connected ? cn(field, "text-fg-muted") : cn(inkButton, "justify-center"), "flex h-8 items-center justify-center gap-1.5 rounded-full px-3.5 text-(length:--cue-text-ui) font-medium disabled:pointer-events-none"),
+				children: connected ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(CheckIcon, { className: "size-3.5 text-ok" }), "Connected"] }) : "Connect"
+			})
+		]
+	});
+}
+//#endregion
+export { AgentCard };

package/dist/elements/agent-handoff.d.ts

@@ -0,0 +1,24 @@
+import { ComponentProps } from "react";
+//#region src/elements/agent-handoff.d.ts
+/**
+ * Control passing between agents, with the reason and what came along.
+ *
+ * @example
+ * import { AgentHandoff } from "@cueplusplus/ui/elements";
+ *
+ * <AgentHandoff from="Triage" to="Maintainer" reason={reason} carried={carried} settled />
+ */
+declare function AgentHandoff({ from, to, reason, carried, settled, className, ...props }: Omit<ComponentProps<"div">, "children" | "from" | "to" | "reason" | "carried" | "settled"> & {
+  /** Agent giving up control. */
+  from: string;
+  /** Agent taking it. */
+  to: string;
+  /** Why the baton moved. Without it a handoff reads as an unexplained jump. */
+  reason: string;
+  /** Context that travelled across. Pass an empty array to hide the section. */
+  carried: readonly string[];
+  /** Cools the arrow and the receiving badge once the new agent is underway. */
+  settled: boolean;
+}): import("react").JSX.Element;
+//#endregion
+export { AgentHandoff };

package/dist/elements/agent-handoff.js

@@ -0,0 +1,53 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { field } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { ArrowRightIcon, BotIcon } from "lucide-react";
+//#region src/elements/agent-handoff.tsx
+/**
+* Control passing between agents, with the reason and what came along.
+*
+* @example
+* import { AgentHandoff } from "@cueplusplus/ui/elements";
+*
+* <AgentHandoff from="Triage" to="Maintainer" reason={reason} carried={carried} settled />
+*/
+function AgentHandoff({ from, to, reason, carried, settled, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "agent-handoff",
+		className: cn("flex w-full max-w-sm flex-col gap-2", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-2",
+				children: [
+					/* @__PURE__ */ jsxs("span", {
+						className: cn(field, "text-fg-muted flex items-center gap-1.5 rounded-full px-2.5 py-1 text-(length:--cue-text-ui) transition-opacity duration-500", settled && "opacity-45"),
+						children: [/* @__PURE__ */ jsx(BotIcon, { className: "size-3" }), from]
+					}),
+					/* @__PURE__ */ jsx(ArrowRightIcon, { className: cn("size-3.5 shrink-0 transition-colors duration-500", settled ? "text-fg-subtle" : "text-stream") }),
+					/* @__PURE__ */ jsxs("span", {
+						className: cn("flex items-center gap-1.5 rounded-full px-2.5 py-1 text-(length:--cue-text-ui) transition-colors duration-500", settled ? cn(field, "text-fg-muted") : "bg-stream/15 text-stream"),
+						children: [/* @__PURE__ */ jsx(BotIcon, { className: "size-3" }), to]
+					})
+				]
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "text-fg-muted text-(length:--cue-text-ui) leading-(--cue-leading-ui)",
+				children: reason
+			}),
+			carried.length > 0 && /* @__PURE__ */ jsxs("div", {
+				className: "flex flex-col gap-1",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: cn("font-mono text-(length:--cue-text-label) tracking-tight", "text-fg-subtle"),
+					children: "carried over"
+				}), carried.map((item) => /* @__PURE__ */ jsx("span", {
+					className: "text-fg-muted border-border border-s ps-2.5 text-(length:--cue-text-ui) leading-(--cue-leading-ui)",
+					children: item
+				}, item))]
+			})
+		]
+	});
+}
+//#endregion
+export { AgentHandoff };

package/dist/elements/agent-mode-badge.d.ts

@@ -0,0 +1,72 @@
+import { AgentMode } from "./vocabulary.js";
+import * as React from "react";
+import { useRender } from "@base-ui/react/use-render";
+//#region src/elements/agent-mode-badge.d.ts
+interface AgentModeBadgeProps extends Omit<React.ComponentPropsWithoutRef<"span">, "children"> {
+  /**
+   * How much authority the run is holding: `manual`, `auto-edit`, `plan` or
+   * `unsafe`. Stamped as `data-agent-mode`, which is what the quadruple in
+   * `@cueplusplus/ui/elements.css` is keyed on.
+   */
+  mode: AgentMode;
+  /**
+   * The product's own word for it — `Agent`, `Build`, `YOLO`, `Bypass
+   * permissions`. Defaults to `AGENT_MODE_LABELS[mode]`, and it is the reason
+   * a nine-mode product needs no more than these four rungs.
+   */
+  label?: string;
+  /**
+   * What the mode actually does, as the badge's `title`. Defaults to
+   * `AGENT_MODE_DESCRIPTIONS[mode]`. Pass `""` for no tooltip at all.
+   */
+  description?: string;
+  /**
+   * Replace the rendered element (Base UI render prop) — `render={<button
+   * type="button" onClick={cycle} />}` for a picker that cycles, which is what
+   * every product with more than two modes ships.
+   */
+  render?: useRender.RenderProp;
+}
+/**
+ * What the run is allowed to do, said in one chip and one attribute.
+ *
+ * Agent authority is the fact a person most needs from the corner of their eye
+ * and the one every catalogue leaves to prose. This is the readout: a glyph, a
+ * word, and `data-agent-mode` on the element. The attribute is the part that
+ * travels — `@cueplusplus/ui/elements.css` declares four custom properties
+ * under it, so putting the same attribute on a composer tints its focus ring,
+ * its send button and its rail from one place, and a console adds a
+ * mode-aware surface by reading a property rather than by threading a prop:
+ *
+ * ```css
+ * .composer:focus-within { border-color: var(--cue-elements-mode-icon); }
+ * .send-button { background: var(--cue-elements-mode-icon); color: var(--cue-elements-mode-background); }
+ * .turn-rail { background: var(--cue-elements-mode-border); }
+ * ```
+ *
+ * The ladder is four rungs and the mode set is open. Every product in the study
+ * paints six, seven or nine modes in exactly four accents — will it ask me, is
+ * it writing, is it only planning, are the guardrails off — so the rung is what
+ * `mode` carries and the product's own word is what `label` carries.
+ *
+ * The properties resolve against the *element that carries the attribute*, not
+ * against the page: a badge inside an `<AgentSurface skin="aui">` takes the
+ * island's palette, because the quadruple is declared on `[data-agent-mode]`
+ * rather than at `:root` where a `var()` would have been substituted before it
+ * ever reached the island.
+ *
+ * @example
+ * import { AgentModeBadge } from "@cueplusplus/ui/elements";
+ *
+ * <AgentModeBadge mode="plan" />
+ * @example
+ * // A product's own word on cue's rung, and a chip that cycles.
+ * <AgentModeBadge
+ *   mode="unsafe"
+ *   label="YOLO"
+ *   render={<button type="button" onClick={cycle} />}
+ * />
+ */
+declare const AgentModeBadge: React.ForwardRefExoticComponent<AgentModeBadgeProps & React.RefAttributes<HTMLSpanElement>>;
+//#endregion
+export { AgentModeBadge, AgentModeBadgeProps };

package/dist/elements/agent-mode-badge.js

@@ -0,0 +1,110 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { AGENT_MODE_DESCRIPTIONS, AGENT_MODE_LABELS } from "./vocabulary.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useRender } from "@base-ui/react/use-render";
+import { HandIcon, MapIcon, PencilIcon, ShieldOffIcon } from "lucide-react";
+//#region src/elements/agent-mode-badge.tsx
+/**
+* The glyph per rung, so the ladder survives a colour-blind reader and a
+* monochrome screenshot.
+*
+* A hand for the mode that stops and asks, a pencil for the one that writes, a
+* map for the one that only reads and plans, and a shield with a line through
+* it for the one that does not stop. Colour alone cannot carry authority — this
+* is the same argument that puts a label beside it.
+*/
+const MODE_GLYPH = {
+	manual: HandIcon,
+	"auto-edit": PencilIcon,
+	plan: MapIcon,
+	unsafe: ShieldOffIcon
+};
+/**
+* The four properties the quadruple publishes, with a token behind each.
+*
+* The fallbacks are not decoration: `elements.css` is a consumer import, and
+* without it these four are undeclared. A badge that resolved to nothing would
+* be an invisible chip, so the fallback is the family's neutral — the mode is
+* then carried by the glyph and the label, which is where it has to be carried
+* anyway.
+*/
+const MODE_PAINT = {
+	backgroundColor: "var(--cue-elements-mode-background, var(--cue-surface-2))",
+	color: "var(--cue-elements-mode-text, var(--cue-fg-muted))",
+	borderColor: "var(--cue-elements-mode-border, var(--cue-border))"
+};
+/** The icon's own property, which is the one a rail and a spinner also read. */
+const MODE_ICON = { color: "var(--cue-elements-mode-icon, var(--cue-fg-subtle))" };
+/**
+* What the run is allowed to do, said in one chip and one attribute.
+*
+* Agent authority is the fact a person most needs from the corner of their eye
+* and the one every catalogue leaves to prose. This is the readout: a glyph, a
+* word, and `data-agent-mode` on the element. The attribute is the part that
+* travels — `@cueplusplus/ui/elements.css` declares four custom properties
+* under it, so putting the same attribute on a composer tints its focus ring,
+* its send button and its rail from one place, and a console adds a
+* mode-aware surface by reading a property rather than by threading a prop:
+*
+* ```css
+* .composer:focus-within { border-color: var(--cue-elements-mode-icon); }
+* .send-button { background: var(--cue-elements-mode-icon); color: var(--cue-elements-mode-background); }
+* .turn-rail { background: var(--cue-elements-mode-border); }
+* ```
+*
+* The ladder is four rungs and the mode set is open. Every product in the study
+* paints six, seven or nine modes in exactly four accents — will it ask me, is
+* it writing, is it only planning, are the guardrails off — so the rung is what
+* `mode` carries and the product's own word is what `label` carries.
+*
+* The properties resolve against the *element that carries the attribute*, not
+* against the page: a badge inside an `<AgentSurface skin="aui">` takes the
+* island's palette, because the quadruple is declared on `[data-agent-mode]`
+* rather than at `:root` where a `var()` would have been substituted before it
+* ever reached the island.
+*
+* @example
+* import { AgentModeBadge } from "@cueplusplus/ui/elements";
+*
+* <AgentModeBadge mode="plan" />
+* @example
+* // A product's own word on cue's rung, and a chip that cycles.
+* <AgentModeBadge
+*   mode="unsafe"
+*   label="YOLO"
+*   render={<button type="button" onClick={cycle} />}
+* />
+*/
+const AgentModeBadge = React.forwardRef(function AgentModeBadge({ mode, label, description, render, className, style, ...elementProps }, ref) {
+	const Glyph = MODE_GLYPH[mode];
+	const said = label ?? AGENT_MODE_LABELS[mode];
+	const explained = description ?? AGENT_MODE_DESCRIPTIONS[mode];
+	return useRender({
+		render,
+		ref,
+		defaultTagName: "span",
+		props: {
+			...elementProps,
+			"data-slot": "agent-mode-badge",
+			"data-agent-mode": mode,
+			title: explained === "" ? void 0 : explained,
+			style: {
+				...MODE_PAINT,
+				...style
+			},
+			className: cn("inline-flex shrink-0 items-center gap-1.5 rounded-full border px-2 py-0.5 text-(length:--cue-text-ui) font-medium", className),
+			children: /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Glyph, {
+				"aria-hidden": true,
+				className: "size-3.5 shrink-0",
+				style: MODE_ICON
+			}), /* @__PURE__ */ jsx("span", {
+				className: "min-w-0 truncate",
+				children: said
+			})] })
+		}
+	});
+});
+//#endregion
+export { AgentModeBadge };

package/dist/elements/agent-plan.d.ts

@@ -0,0 +1,24 @@
+import { ComponentProps } from "react";
+//#region src/elements/agent-plan.d.ts
+/**
+ * A checklist the agent works through, with progress you can glance.
+ *
+ * @example
+ * import { AgentPlan } from "@cueplusplus/ui/elements";
+ *
+ * <AgentPlan
+ *   steps={["Read the file", "Draft the fix", "Run tests"]}
+ *   activeIndex={1}
+ * />
+ */
+declare function AgentPlan({ steps, activeIndex, className, ...props }: Omit<ComponentProps<"div">, "children" | "steps" | "activeIndex"> & {
+  /** Checklist items the agent works through in order. */
+  steps: readonly string[];
+  /**
+   * Index of the step currently running. Values past the end mark every step done, and
+   * values before the start mark none.
+   */
+  activeIndex: number;
+}): import("react").JSX.Element;
+//#endregion
+export { AgentPlan };

package/dist/elements/agent-plan.js

@@ -0,0 +1,74 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { mono } from "./surfaces.js";
+import { pct, progressOf } from "./range.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CheckIcon, Loader2Icon } from "lucide-react";
+//#region src/elements/agent-plan.tsx
+/**
+* A checklist the agent works through, with progress you can glance.
+*
+* @example
+* import { AgentPlan } from "@cueplusplus/ui/elements";
+*
+* <AgentPlan
+*   steps={["Read the file", "Draft the fix", "Run tests"]}
+*   activeIndex={1}
+* />
+*/
+function AgentPlan({ steps, activeIndex, className, ...props }) {
+	const total = steps.length;
+	const completed = progressOf(activeIndex, total);
+	const allDone = completed >= total;
+	const progress = pct(completed, total);
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "agent-plan",
+		className: cn("flex w-full max-w-sm flex-col gap-3", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center justify-between",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "text-(length:--cue-text-body) font-medium",
+					children: "Plan"
+				}), /* @__PURE__ */ jsxs("span", {
+					className: cn(mono, "text-fg-subtle tabular-nums"),
+					children: [
+						completed,
+						" of ",
+						total
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "bg-surface-2 h-[3px] w-full overflow-hidden rounded-full",
+				children: /* @__PURE__ */ jsx("span", {
+					className: "bg-accent block h-full rounded-full transition-[width] duration-500",
+					style: { width: `${progress}%` }
+				})
+			}),
+			/* @__PURE__ */ jsx("ul", {
+				className: "flex flex-col gap-2.5",
+				children: steps.map((step, i) => {
+					const done = allDone || i < completed;
+					const active = !allDone && i === completed;
+					return /* @__PURE__ */ jsxs("li", {
+						className: "flex items-center gap-2.5 text-(length:--cue-text-body)",
+						children: [/* @__PURE__ */ jsx("span", {
+							className: "flex size-4 shrink-0 items-center justify-center",
+							children: done ? /* @__PURE__ */ jsx(CheckIcon, { className: "text-fg-subtle size-3.5" }) : active ? /* @__PURE__ */ jsx(Loader2Icon, { className: "text-fg size-3.5 animate-spin motion-reduce:animate-none" }) : /* @__PURE__ */ jsx("span", {
+								"aria-hidden": true,
+								className: "bg-surface-3 size-1.5 rounded-full"
+							})
+						}), /* @__PURE__ */ jsx("span", {
+							className: cn(done && "text-fg-subtle", active && "text-fg", !done && !active && "text-fg-subtle"),
+							children: step
+						})]
+					}, step);
+				})
+			})
+		]
+	});
+}
+//#endregion
+export { AgentPlan };

package/dist/elements/agent-status.d.ts

@@ -0,0 +1,29 @@
+import { ComponentProps } from "react";
+//#region src/elements/agent-status.d.ts
+/** What the agent is doing: `working`, `waiting` on the user, or `done`. */
+type AgentState = "working" | "waiting" | "done";
+/** One step of an agent's run, for a surface that lists them rather than showing the last. */
+interface StatusStep {
+  /** The step's own state, drawn as its glyph. */
+  state: AgentState;
+  /** What the step says. */
+  label: string;
+}
+/**
+ * One pill that always answers: what is it doing, and for how long.
+ *
+ * @example
+ * import { AgentStatus } from "@cueplusplus/ui/elements";
+ *
+ * <AgentStatus state="working" label="Editing composer.tsx" elapsed="8s" />
+ */
+declare function AgentStatus({ state, label, elapsed, className, ...props }: Omit<ComponentProps<"div">, "children" | "state" | "label" | "elapsed"> & {
+  /** Visual mode of the pill: working, waiting, or done with a check. */
+  state: AgentState;
+  /** Short status line describing what the agent is doing. */
+  label: string;
+  /** Elapsed time shown in mono when provided. */
+  elapsed?: string;
+}): import("react").JSX.Element;
+//#endregion
+export { AgentState, AgentStatus, StatusStep };

package/dist/elements/agent-status.js

@@ -0,0 +1,46 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { ghostButton, paper } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CheckIcon, PauseIcon, RotateCcwIcon } from "lucide-react";
+//#region src/elements/agent-status.tsx
+/**
+* One pill that always answers: what is it doing, and for how long.
+*
+* @example
+* import { AgentStatus } from "@cueplusplus/ui/elements";
+*
+* <AgentStatus state="working" label="Editing composer.tsx" elapsed="8s" />
+*/
+function AgentStatus({ state, label, elapsed, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "agent-status",
+		className: cn(paper, "flex items-center gap-2.5 rounded-full py-1.5 ps-3.5 pe-1.5", className),
+		...props,
+		children: [
+			state === "done" ? /* @__PURE__ */ jsx(CheckIcon, {
+				"aria-hidden": true,
+				className: "size-3 shrink-0 text-ok"
+			}) : /* @__PURE__ */ jsx("span", {
+				"aria-hidden": true,
+				className: cn("size-1.5 shrink-0 rounded-full motion-reduce:animate-none", state === "working" ? "animate-pulse bg-stream" : "bg-surface-3 animate-pulse")
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "cue-elements-fade-in cue-elements-blur-in-2 cue-elements-animate-in max-w-44 truncate text-(length:--cue-text-ui) duration-300 motion-reduce:animate-none",
+				children: label
+			}, label),
+			elapsed !== void 0 && state !== "done" && /* @__PURE__ */ jsx("span", {
+				className: cn("font-mono text-(length:--cue-text-label) tracking-tight", "text-fg-subtle tabular-nums"),
+				children: elapsed
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				"aria-label": state === "done" ? "Run again" : "Pause agent",
+				className: cn(ghostButton, "size-6"),
+				children: state === "done" ? /* @__PURE__ */ jsx(RotateCcwIcon, { className: "size-3" }) : /* @__PURE__ */ jsx(PauseIcon, { className: "size-3" })
+			})
+		]
+	});
+}
+//#endregion
+export { AgentStatus };

package/dist/elements/agent-surface.d.ts

@@ -0,0 +1,65 @@
+import { AgentFidelity, AgentSkin } from "../system/agent-skin.js";
+import * as React from "react";
+import { useRender } from "@base-ui/react/use-render";
+//#region src/elements/agent-surface.d.ts
+interface AgentSurfaceProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /**
+   * Which value-set paints the subtree: `cue` (the default) or `aui`, which
+   * installs assistant-ui's own inks, grounds and hues.
+   */
+  skin?: AgentSkin;
+  /**
+   * How much a supersede island re-points: `cue-metrics` (the default, colour
+   * only) or `upstream`, which also pins assistant-ui's radii, literal type
+   * sizes and spacing so the density ladder stops at the island edge.
+   */
+  fidelity?: AgentFidelity;
+  /**
+   * Replace the rendered element (Base UI render prop). Accepts an element —
+   * `render={<section />}` — or a function returning one.
+   */
+  render?: useRender.RenderProp;
+  /** The subtree that paints with this island's values. */
+  children?: React.ReactNode;
+}
+/**
+ * The supersede island: one subtree, painted by a different set of values.
+ *
+ * Renders a plain `<div data-slot="agent-surface" data-cue-skin="…"
+ * data-cue-fidelity="…">` and publishes the same pair on React context. The attributes do the work —
+ * `@cueplusplus/ui/elements.css` re-declares, under them, the `--cue-*` tokens
+ * the whole elements family reads, and custom properties inherit, so every
+ * element inside repaints with no prop threading and no branch in any
+ * component. The context exists for the one place that cannot see the DOM: an
+ * overlay portaled to `<body>` from inside the island, which
+ * {@link useCuePortalProps} stamps from the same values.
+ *
+ * Two things this is not. It is not a theme — `data-theme`, `data-mode` and
+ * `data-density` are untouched, and a light app keeps a light island. And it is
+ * not needed for cue mode: the elements were rewritten onto cue's tokens by the
+ * vendoring codemod, so `skin="cue"` is what they already do. Reach for this to
+ * show an element the way assistant-ui drew it, or to hand a chat panel back to
+ * upstream's design language inside a console that is otherwise cue's.
+ *
+ * What an `aui` island re-points is this family's own vocabulary rather than the
+ * whole token contract: `--cue-busy`, `--cue-info`, `--cue-selection`,
+ * `--cue-focus`, `--cue-scrim` and every derived `*-soft` / `*-border` stay on
+ * the console's theme. Nothing in the elements group reads them, so the island
+ * is complete for what it is for — but a *cue* component placed inside one (a
+ * `Chip tone="busy"`, a `Toast`) paints half in each palette, and the
+ * derivations cannot be made to follow at all: they are `color-mix()` values
+ * resolved on the theme block and inherited as answers. `elements.css` carries
+ * the full accounting beside the values themselves.
+ *
+ * `elements.css` is a consumer import: `@import "@cueplusplus/ui/elements.css";`
+ * after the main stylesheet. Without it a `skin="aui"` island simply stays in
+ * cue's palette.
+ *
+ * @example
+ * <AgentSurface skin="aui" fidelity="upstream">
+ *   <ToolCall label="Searched" activeLabel="Searching" query="composer" … />
+ * </AgentSurface>
+ */
+declare const AgentSurface: React.ForwardRefExoticComponent<AgentSurfaceProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { AgentSurface, AgentSurfaceProps };

package/dist/elements/agent-surface.js

@@ -0,0 +1,68 @@
+"use client";
+import { AgentSkinContext } from "../system/agent-skin.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+import { useRender } from "@base-ui/react/use-render";
+//#region src/elements/agent-surface.tsx
+/**
+* The supersede island: one subtree, painted by a different set of values.
+*
+* Renders a plain `<div data-slot="agent-surface" data-cue-skin="…"
+* data-cue-fidelity="…">` and publishes the same pair on React context. The attributes do the work —
+* `@cueplusplus/ui/elements.css` re-declares, under them, the `--cue-*` tokens
+* the whole elements family reads, and custom properties inherit, so every
+* element inside repaints with no prop threading and no branch in any
+* component. The context exists for the one place that cannot see the DOM: an
+* overlay portaled to `<body>` from inside the island, which
+* {@link useCuePortalProps} stamps from the same values.
+*
+* Two things this is not. It is not a theme — `data-theme`, `data-mode` and
+* `data-density` are untouched, and a light app keeps a light island. And it is
+* not needed for cue mode: the elements were rewritten onto cue's tokens by the
+* vendoring codemod, so `skin="cue"` is what they already do. Reach for this to
+* show an element the way assistant-ui drew it, or to hand a chat panel back to
+* upstream's design language inside a console that is otherwise cue's.
+*
+* What an `aui` island re-points is this family's own vocabulary rather than the
+* whole token contract: `--cue-busy`, `--cue-info`, `--cue-selection`,
+* `--cue-focus`, `--cue-scrim` and every derived `*-soft` / `*-border` stay on
+* the console's theme. Nothing in the elements group reads them, so the island
+* is complete for what it is for — but a *cue* component placed inside one (a
+* `Chip tone="busy"`, a `Toast`) paints half in each palette, and the
+* derivations cannot be made to follow at all: they are `color-mix()` values
+* resolved on the theme block and inherited as answers. `elements.css` carries
+* the full accounting beside the values themselves.
+*
+* `elements.css` is a consumer import: `@import "@cueplusplus/ui/elements.css";`
+* after the main stylesheet. Without it a `skin="aui"` island simply stays in
+* cue's palette.
+*
+* @example
+* <AgentSurface skin="aui" fidelity="upstream">
+*   <ToolCall label="Searched" activeLabel="Searching" query="composer" … />
+* </AgentSurface>
+*/
+const AgentSurface = React.forwardRef(function AgentSurface({ skin = "cue", fidelity = "cue-metrics", render, children, ...elementProps }, ref) {
+	const island = React.useMemo(() => ({
+		skin,
+		fidelity
+	}), [skin, fidelity]);
+	const element = useRender({
+		render,
+		ref,
+		defaultTagName: "div",
+		props: {
+			...elementProps,
+			"data-slot": "agent-surface",
+			"data-cue-skin": skin,
+			"data-cue-fidelity": fidelity,
+			children
+		}
+	});
+	return /* @__PURE__ */ jsx(AgentSkinContext.Provider, {
+		value: island,
+		children: element
+	});
+});
+//#endregion
+export { AgentSurface };