@mcp-b/react-components 0.17.0 → 0.19.0

package/dist/components/ThinkThreadPicker.js

@@ -1,8 +1,11 @@
-import { t as cx } from "../class-names-Bk-QLWWI.js";
-import { I as PlusIcon, J as WarningIcon, V as SpinnerIcon, m as DotIcon } from "../icons--FqCZEc3.js";
-import { Button } from "./Button.js";
+import { t as cx } from "../class-names-BiMDVpUo.js";
+import { K as SpinnerIcon, Q as WarningIcon, V as PlusIcon, _ as DotIcon, t as ArchiveIcon } from "../icons-DKXiSepE.js";
+import { t as NavigationLink } from "../navigation-link-Cob7KBlM.js";
+import { Button, buttonVariants } from "./Button.js";
+import { SearchField } from "./SearchField.js";
+import { AlertDialog } from "./AlertDialog.js";
 import { ScrollArea } from "./ScrollArea.js";
-import "react";
+import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/ThinkThreadPicker.tsx
 function toThreadDate(value) {
@@ -49,6 +52,9 @@ function formatThreadStatus(thread) {
 function isThreadBusy(status) {
 	return status === "pending" || status === "running" || status === "starting" || status === "streaming" || status === "submitted" || status === "recovering";
 }
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 function summarizeThinkThreads(threads) {
 	return threads.reduce((summary, thread) => {
 		if (isThreadBusy(thread.status)) summary.running += 1;
@@ -98,12 +104,55 @@ function ThinkThreadStatusIndicators({ summary, className }) {
 * Thread roster UI for sub-agent chat apps.
 *
 * This component does not call Think or Cloudflare RPC methods directly. Feed
-* it from the parent agent's roster method, then route `onSelect` into the
-* child `useAgent({ sub: [...] })` name. Keep backend contract notes beside the
-* parent Think agent because `listThreads()`/`createThread()` are app-owned.
+* it from the parent agent's roster method, then render app-owned route links
+* that select the child `useAgent({ sub: [...] })` name. Keep backend contract
+* notes beside the parent Think agent because
+* `listThreads()`/`createThread()`/`deleteThread()` are app-owned.
 */
-function ThinkThreadPicker({ threads, selectedId, onSelect, onCreate, className, title = "Recents", "aria-label": ariaLabel = "Threads", ref, ...props }) {
+function ThinkThreadPicker({ threads, renderThreadLink, onCreate, onDelete, className, title = "Recents", "aria-label": ariaLabel = "Threads", ref, ...props }) {
 	const statusSummary = summarizeThinkThreads(threads);
+	const [query, setQuery] = React.useState("");
+	const [deleteOpen, setDeleteOpen] = React.useState(false);
+	const [deleteCandidate, setDeleteCandidate] = React.useState();
+	const [deleteBusy, setDeleteBusy] = React.useState(false);
+	const [deleteError, setDeleteError] = React.useState();
+	const deleteSucceededRef = React.useRef(false);
+	const deleteFallbackIdRef = React.useRef(void 0);
+	const threadLinkRefs = React.useRef(/* @__PURE__ */ new Map());
+	const deleteButtonRefs = React.useRef(/* @__PURE__ */ new Map());
+	const createButtonRef = React.useRef(null);
+	const navRef = React.useRef(null);
+	const normalizedQuery = query.trim().toLocaleLowerCase();
+	const visibleThreads = normalizedQuery ? threads.filter((thread) => thread.title.toLocaleLowerCase().includes(normalizedQuery)) : threads;
+	const requestDelete = (thread) => {
+		const index = threads.findIndex((candidate) => candidate.id === thread.id);
+		deleteFallbackIdRef.current = threads[index + 1]?.id ?? threads[index - 1]?.id ?? void 0;
+		deleteSucceededRef.current = false;
+		setDeleteCandidate(thread);
+		setDeleteError(void 0);
+		setDeleteOpen(true);
+	};
+	const performDelete = async () => {
+		if (!deleteCandidate || !onDelete) return;
+		setDeleteBusy(true);
+		setDeleteError(void 0);
+		try {
+			await onDelete(deleteCandidate);
+			deleteSucceededRef.current = true;
+			setDeleteOpen(false);
+		} catch (error) {
+			setDeleteError(errorMessage(error));
+		} finally {
+			setDeleteBusy(false);
+		}
+	};
+	const resolveDeleteFinalFocus = () => {
+		if (deleteSucceededRef.current) {
+			const fallbackId = deleteFallbackIdRef.current;
+			return (fallbackId ? threadLinkRefs.current.get(fallbackId) : void 0) ?? createButtonRef.current ?? navRef.current;
+		}
+		return (deleteCandidate ? deleteButtonRefs.current.get(deleteCandidate.id) : void 0) ?? createButtonRef.current ?? navRef.current;
+	};
 	return /* @__PURE__ */ jsxs("aside", {
 		ref,
 		className: cx("think-thread-picker", className),
@@ -116,53 +165,90 @@ function ThinkThreadPicker({ threads, selectedId, onSelect, onCreate, className,
 					children: title
 				}), /* @__PURE__ */ jsx(ThinkThreadStatusIndicators, { summary: statusSummary })]
 			}),
+			/* @__PURE__ */ jsxs(SearchField.Root, {
+				className: "think-thread-picker__search",
+				name: "thread-search",
+				children: [/* @__PURE__ */ jsx(SearchField.Label, {
+					className: "sigvelo-visually-hidden",
+					children: "Search threads"
+				}), /* @__PURE__ */ jsx(SearchField.Control, {
+					value: query,
+					placeholder: "Search recent threads",
+					autoComplete: "off",
+					onChange: (event) => setQuery(event.currentTarget.value)
+				})]
+			}),
 			/* @__PURE__ */ jsx("nav", {
+				ref: navRef,
 				className: "think-thread-picker__nav",
 				"aria-label": ariaLabel,
+				tabIndex: -1,
 				children: /* @__PURE__ */ jsxs(ScrollArea.Root, {
 					className: "think-thread-picker__scroll",
 					children: [/* @__PURE__ */ jsx(ScrollArea.Viewport, {
 						className: "think-thread-picker__viewport",
 						"aria-label": "Thread list",
-						children: threads.length ? /* @__PURE__ */ jsx("ul", {
+						children: visibleThreads.length ? /* @__PURE__ */ jsx("ul", {
 							className: "think-thread-picker__list",
-							children: threads.map((thread) => {
+							children: visibleThreads.map((thread) => {
 								const timestamp = formatThreadTimestamp(thread);
 								const statusLabel = formatThreadStatus(thread);
 								const busy = isThreadBusy(thread.status);
-								return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs(Button, {
-									type: "button",
-									variant: "ghost",
-									color: "neutral",
-									size: "sm",
-									className: "think-thread-picker__thread",
-									"data-selected": thread.id === selectedId ? "true" : "false",
-									"data-status": thread.status,
-									"aria-current": thread.id === selectedId ? "page" : void 0,
-									onClick: () => onSelect(thread.id),
-									children: [/* @__PURE__ */ jsx("span", {
-										className: "think-thread-picker__thread-title",
-										children: thread.title
-									}), statusLabel ? /* @__PURE__ */ jsx("span", {
-										className: "think-thread-picker__thread-status",
-										role: "img",
-										"aria-label": statusLabel,
-										title: statusLabel,
-										children: busy ? /* @__PURE__ */ jsx(SpinnerIcon, {}) : /* @__PURE__ */ jsx(DotIcon, {})
-									}) : timestamp?.date ? /* @__PURE__ */ jsx("time", {
-										className: "think-thread-picker__thread-time",
-										dateTime: timestamp.date.toISOString(),
-										title: timestamp.date.toLocaleString(),
-										children: timestamp.label
-									}) : timestamp ? /* @__PURE__ */ jsx("span", {
-										className: "think-thread-picker__thread-time",
-										children: timestamp.label
+								return /* @__PURE__ */ jsxs("li", {
+									className: "think-thread-picker__item",
+									children: [/* @__PURE__ */ jsxs(NavigationLink, {
+										render: renderThreadLink(thread),
+										ref: (node) => {
+											if (node) threadLinkRefs.current.set(thread.id, node);
+											else threadLinkRefs.current.delete(thread.id);
+										},
+										className: buttonVariants({
+											variant: "ghost",
+											color: "neutral",
+											size: "sm",
+											className: "think-thread-picker__thread"
+										}),
+										"data-thread-status": thread.status,
+										children: [/* @__PURE__ */ jsx("span", {
+											className: "think-thread-picker__thread-title",
+											children: thread.title
+										}), statusLabel ? /* @__PURE__ */ jsx("span", {
+											className: "think-thread-picker__thread-status",
+											role: "img",
+											"aria-label": statusLabel,
+											title: statusLabel,
+											children: busy ? /* @__PURE__ */ jsx(SpinnerIcon, {}) : /* @__PURE__ */ jsx(DotIcon, {})
+										}) : timestamp?.date ? /* @__PURE__ */ jsx("time", {
+											className: "think-thread-picker__thread-time",
+											dateTime: timestamp.date.toISOString(),
+											title: timestamp.date.toLocaleString(),
+											children: timestamp.label
+										}) : timestamp ? /* @__PURE__ */ jsx("span", {
+											className: "think-thread-picker__thread-time",
+											children: timestamp.label
+										}) : null]
+									}), onDelete ? /* @__PURE__ */ jsx(Button, {
+										ref: (node) => {
+											if (node) deleteButtonRefs.current.set(thread.id, node);
+											else deleteButtonRefs.current.delete(thread.id);
+										},
+										type: "button",
+										variant: "ghost",
+										color: "neutral",
+										size: "sm",
+										iconOnly: true,
+										className: "think-thread-picker__delete",
+										"aria-label": `Delete thread ${thread.title}`,
+										"aria-haspopup": "dialog",
+										disabled: deleteBusy,
+										onClick: () => requestDelete(thread),
+										children: /* @__PURE__ */ jsx(ArchiveIcon, {})
 									}) : null]
-								}) }, thread.id);
+								}, thread.id);
 							})
 						}) : /* @__PURE__ */ jsx("p", {
 							className: "think-thread-picker__empty",
-							children: "No threads yet."
+							children: threads.length ? "No matching threads." : "No threads yet."
 						})
 					}), /* @__PURE__ */ jsx(ScrollArea.Scrollbar, {
 						orientation: "vertical",
@@ -173,6 +259,7 @@ function ThinkThreadPicker({ threads, selectedId, onSelect, onCreate, className,
 			onCreate ? /* @__PURE__ */ jsx("div", {
 				className: "think-thread-picker__footer",
 				children: /* @__PURE__ */ jsxs(Button, {
+					ref: createButtonRef,
 					type: "button",
 					variant: "normal",
 					color: "neutral",
@@ -181,6 +268,43 @@ function ThinkThreadPicker({ threads, selectedId, onSelect, onCreate, className,
 					onClick: () => void onCreate(),
 					children: [/* @__PURE__ */ jsx(PlusIcon, {}), /* @__PURE__ */ jsx("span", { children: "New thread" })]
 				})
+			}) : null,
+			onDelete && deleteCandidate ? /* @__PURE__ */ jsx(AlertDialog.Root, {
+				open: deleteOpen,
+				onOpenChange: (open, eventDetails) => {
+					if (deleteBusy) {
+						eventDetails.cancel();
+						return;
+					}
+					setDeleteOpen(open);
+					if (!open) setDeleteError(void 0);
+				},
+				children: /* @__PURE__ */ jsxs(AlertDialog.Portal, { children: [/* @__PURE__ */ jsx(AlertDialog.Backdrop, {}), /* @__PURE__ */ jsx(AlertDialog.Viewport, { children: /* @__PURE__ */ jsxs(AlertDialog.Popup, {
+					finalFocus: resolveDeleteFinalFocus,
+					children: [
+						/* @__PURE__ */ jsxs(AlertDialog.Title, { children: [
+							"Delete ",
+							deleteCandidate.title,
+							"?"
+						] }),
+						/* @__PURE__ */ jsx(AlertDialog.Description, { children: "This permanently deletes the conversation, its schedules, and its execution history. Any active work stops. This action cannot be undone." }),
+						deleteError ? /* @__PURE__ */ jsxs("p", {
+							className: "think-thread-picker__delete-error",
+							role: "alert",
+							children: [/* @__PURE__ */ jsx(WarningIcon, {}), /* @__PURE__ */ jsx("span", { children: deleteError })]
+						}) : null,
+						/* @__PURE__ */ jsxs(AlertDialog.Footer, { children: [/* @__PURE__ */ jsx(AlertDialog.Close, {
+							disabled: deleteBusy,
+							children: "Cancel"
+						}), /* @__PURE__ */ jsxs(Button, {
+							type: "button",
+							color: "destructive",
+							disabled: deleteBusy,
+							onClick: () => void performDelete(),
+							children: [deleteBusy ? /* @__PURE__ */ jsx(SpinnerIcon, {}) : null, deleteBusy ? "Deleting…" : "Delete thread"]
+						})] })
+					]
+				}) })] })
 			}) : null
 		]
 	});

package/dist/components/Toast.js

@@ -1,4 +1,4 @@
-import { n as mergeBaseClassName } from "../class-names-Bk-QLWWI.js";
+import { n as mergeBaseClassName } from "../class-names-BiMDVpUo.js";
 import "react";
 import { jsx } from "react/jsx-runtime";
 import { Toast as Toast$1 } from "@base-ui/react/toast";

package/dist/components/Toggle.d.ts

@@ -1,2 +1,2 @@
-import { i as toggleVariants, n as ToggleProps, r as ToggleVariantsOptions, t as Toggle } from "../Toggle-DaXpe1Lc.js";
+import { i as toggleVariants, n as ToggleProps, r as ToggleVariantsOptions, t as Toggle } from "../Toggle-JKZ43D5S.js";
 export { Toggle, ToggleProps, ToggleVariantsOptions, toggleVariants };

package/dist/components/Toggle.js

@@ -1,13 +1,13 @@
-import { n as mergeBaseClassName } from "../class-names-Bk-QLWWI.js";
+import { n as mergeBaseClassName } from "../class-names-BiMDVpUo.js";
 import "react";
 import { jsx } from "react/jsx-runtime";
 import { Toggle as Toggle$1 } from "@base-ui/react/toggle";
 //#region src/components/Toggle.tsx
-function toggleVariants({ variant = "default", size = "default", className } = {}) {
+function toggleVariants({ variant = "default", size = "md", className } = {}) {
 	return [
 		"toggle",
 		variant === "outline" && "toggle--outline",
-		size !== "default" && `toggle--${size}`,
+		size !== "md" && `toggle--${size}`,
 		className
 	].filter(Boolean).join(" ");
 }
@@ -52,13 +52,15 @@ function toggleVariants({ variant = "default", size = "default", className } = {
 * @see {@link https://base-ui.com/react/components/toggle | Base UI Toggle}
 */
 function Toggle({ className, variant, size, ref, ...props }) {
+	const classes = mergeBaseClassName(toggleVariants({
+		variant,
+		size
+	}), className);
 	return /* @__PURE__ */ jsx(Toggle$1, {
 		ref,
 		"data-slot": "toggle",
-		className: mergeBaseClassName(toggleVariants({
-			variant,
-			size
-		}), className),
+		"data-size": size ?? "md",
+		className: classes,
 		...props
 	});
 }

package/dist/components/ToggleGroup.d.ts

@@ -1,2 +1,2 @@
-import { n as ToggleGroupItemProps, r as ToggleGroupProps, t as ToggleGroup } from "../ToggleGroup-yseEWkOC.js";
+import { n as ToggleGroupItemProps, r as ToggleGroupProps, t as ToggleGroup } from "../ToggleGroup-DNd6cDJZ.js";
 export { ToggleGroup, ToggleGroupItemProps, ToggleGroupProps };

package/dist/components/ToggleGroup.js

@@ -1,4 +1,4 @@
-import { n as mergeBaseClassName } from "../class-names-Bk-QLWWI.js";
+import { n as mergeBaseClassName } from "../class-names-BiMDVpUo.js";
 import { toggleVariants } from "./Toggle.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
@@ -7,12 +7,9 @@ import { Toggle } from "@base-ui/react/toggle";
 //#region src/components/ToggleGroup.tsx
 const ToggleGroupContext = React.createContext({
 	variant: "default",
-	size: "default",
+	size: "md",
 	spacing: 0
 });
-function normalizeSize(size) {
-	return size === "md" ? "default" : size;
-}
 /**
 * A toggle group component for selecting one or multiple options.
 *
@@ -39,7 +36,6 @@ function normalizeSize(size) {
 * @see {@link https://base-ui.com/react/components/toggle-group | Base UI Toggle Group}
 */
 function ToggleGroupRoot({ size = "md", spacing = 0, variant = "default", className, children, style, ref, ...props }) {
-	const normalizedSize = normalizeSize(size);
 	const gap = `${spacing * .25}rem`;
 	const groupStyle = typeof style === "function" ? (state) => ({
 		...style(state),
@@ -48,21 +44,27 @@ function ToggleGroupRoot({ size = "md", spacing = 0, variant = "default", classN
 		...style,
 		gap
 	};
+	const classes = mergeBaseClassName(["toggle-group", size !== "md" && `toggle-group--${size}`].filter(Boolean).join(" "), className);
+	const contextValue = React.useMemo(() => ({
+		variant,
+		size,
+		spacing
+	}), [
+		size,
+		spacing,
+		variant
+	]);
 	return /* @__PURE__ */ jsx(ToggleGroup$1, {
 		ref,
-		"data-size": normalizedSize,
+		"data-size": size,
 		"data-slot": "toggle-group",
 		"data-spacing": spacing,
 		"data-variant": variant,
-		className: mergeBaseClassName(["toggle-group", size !== "md" && `toggle-group--${size}`].filter(Boolean).join(" "), className),
+		className: classes,
 		style: groupStyle,
 		...props,
 		children: /* @__PURE__ */ jsx(ToggleGroupContext.Provider, {
-			value: {
-				variant,
-				size: normalizedSize,
-				spacing
-			},
+			value: contextValue,
 			children
 		})
 	});

package/dist/components/ToolInvocation.js

@@ -1,6 +1,6 @@
 import { Activity, ActivityContent, ActivityPanel, ActivityTrigger } from "./Activity.js";
 import { getToolDisplayName, isToolPartFailed, isToolPartWorking } from "./ThinkChatToolParts.js";
-import { t as summarizeToolInput } from "../summarize-tool-input-BUJsENSn.js";
+import { t as summarizeToolInput } from "../summarize-tool-input-CqTcGRYy.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { getToolName } from "ai";
 import { getToolInput, getToolOutput, getToolPartState } from "@cloudflare/think/react";

package/dist/components/Toolbar.js

@@ -1,4 +1,4 @@
-import { n as mergeBaseClassName } from "../class-names-Bk-QLWWI.js";
+import { n as mergeBaseClassName } from "../class-names-BiMDVpUo.js";
 import "react";
 import { jsx } from "react/jsx-runtime";
 import { Toolbar as Toolbar$1 } from "@base-ui/react/toolbar";

package/dist/components/Tooltip.d.ts

@@ -40,6 +40,13 @@ declare function TooltipProvider({
   ...props
 }: TooltipProviderProps): React.JSX.Element;
 declare function TooltipTrigger(props: TooltipTriggerProps): React.JSX.Element;
+declare function TooltipPositioner({
+  className,
+  ref,
+  ...props
+}: TooltipPositionerProps & {
+  ref?: React.Ref<HTMLDivElement>;
+}): React.JSX.Element;
 declare function TooltipPopup({
   className,
   ref,
@@ -77,7 +84,7 @@ declare const Tooltip: {
   Provider: typeof TooltipProvider;
   Trigger: typeof TooltipTrigger;
   Portal: React.ForwardRefExoticComponent<Omit<import("@base-ui/react").TooltipPortalProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-  Positioner: React.ForwardRefExoticComponent<Omit<import("@base-ui/react").TooltipPositionerProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+  Positioner: typeof TooltipPositioner;
   Popup: typeof TooltipPopup;
   Viewport: typeof TooltipViewport;
   Arrow: typeof TooltipArrow;

package/dist/components/Tooltip.js

@@ -1,4 +1,4 @@
-import { n as mergeBaseClassName } from "../class-names-Bk-QLWWI.js";
+import { n as mergeBaseClassName } from "../class-names-BiMDVpUo.js";
 import "react";
 import { jsx } from "react/jsx-runtime";
 import { Tooltip as Tooltip$1 } from "@base-ui/react/tooltip";
@@ -37,6 +37,15 @@ function TooltipTrigger(props) {
 		...props
 	});
 }
+function TooltipPositioner({ className, ref, ...props }) {
+	const classes = mergeBaseClassName(["tooltip__positioner", "base-ui-positioner"].filter(Boolean).join(" "), className);
+	return /* @__PURE__ */ jsx(Tooltip$1.Positioner, {
+		ref,
+		"data-slot": "tooltip-positioner",
+		className: classes,
+		...props
+	});
+}
 function TooltipPopup({ className, ref, role = "tooltip", ...props }) {
 	const classes = mergeBaseClassName(["tooltip__popup", "base-ui-popup"].filter(Boolean).join(" "), className);
 	return /* @__PURE__ */ jsx(Tooltip$1.Popup, {
@@ -80,7 +89,7 @@ const Tooltip = {
 	Provider: TooltipProvider,
 	Trigger: TooltipTrigger,
 	Portal: Tooltip$1.Portal,
-	Positioner: Tooltip$1.Positioner,
+	Positioner: TooltipPositioner,
 	Popup: TooltipPopup,
 	Viewport: TooltipViewport,
 	Arrow: TooltipArrow

package/dist/components/TransitionSurface.d.ts

@@ -0,0 +1,27 @@
+import * as React from "react";
+
+//#region src/components/TransitionSurface.d.ts
+type TransitionSurfaceVariant = "fade" | "scale" | "slide-block" | "slide-inline";
+interface TransitionSurfaceProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * The restrained entrance and hidden-state treatment applied to the surface.
+   * Pair separate surfaces around Suspense fallback and resolved content.
+   * @default "fade"
+   */
+  variant?: TransitionSurfaceVariant;
+}
+/**
+ * A lightweight presence surface for content inserted by React or revealed
+ * from `hidden`. CSS owns its motion through `@starting-style` and discrete
+ * transitions; this component does not own data loading or Suspense state.
+ */
+declare function TransitionSurface({
+  className,
+  variant,
+  ref,
+  ...props
+}: TransitionSurfaceProps & {
+  ref?: React.Ref<HTMLDivElement>;
+}): React.JSX.Element;
+//#endregion
+export { TransitionSurface, TransitionSurfaceProps, TransitionSurfaceVariant };

package/dist/components/TransitionSurface.js

@@ -0,0 +1,20 @@
+import { t as cx } from "../class-names-BiMDVpUo.js";
+import "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/TransitionSurface.tsx
+/**
+* A lightweight presence surface for content inserted by React or revealed
+* from `hidden`. CSS owns its motion through `@starting-style` and discrete
+* transitions; this component does not own data loading or Suspense state.
+*/
+function TransitionSurface({ className, variant = "fade", ref, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		"data-slot": "transition-surface",
+		"data-variant": variant,
+		className: cx("transition-surface", className),
+		...props
+	});
+}
+//#endregion
+export { TransitionSurface };

package/dist/components/WebPreview.d.ts

@@ -1,4 +1,4 @@
-import { r as ButtonProps } from "../Button-FX_hpqxm.js";
+import { r as ButtonProps } from "../Button-DLGzHsjc.js";
 import * as React from "react";
 
 //#region src/components/WebPreview.d.ts
@@ -17,9 +17,9 @@ interface WebPreviewContextValue {
 interface WebPreviewProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Initial URL for uncontrolled preview history. */
   defaultUrl?: string;
-  /** Controlled URL pushed into preview history when it changes. */
+  /** Controlled URL. Controlled previews leave history ownership to the caller. */
   url?: string;
-  /** Called when the displayed URL changes. */
+  /** Called when navigation requests a URL change. Controlled callers update `url`. */
   onUrlChange?: (url: string) => void;
   /** Additional class names for layout only; do not override iframe sandboxing from apps. */
   className?: string;
@@ -28,8 +28,8 @@ interface WebPreviewProps extends React.HTMLAttributes<HTMLDivElement> {
 }
 /**
  * An iframe preview with a navigation bar, URL input, and optional console
- * panel. Tracks browsing history internally so back/forward buttons work
- * without depending on the iframe's own history.
+ * panel. Uncontrolled previews track browsing history internally; controlled
+ * previews leave history and back/forward behavior to their caller.
  *
  * Built internally for agent/browser preview surfaces. Use it to display a
  * known URL with local navigation controls. Do not use it for trusted app