@mcp-b/react-components 0.47.0 → 0.49.0

package/dist/components/agents-sdk/WorkspaceExecution.js

@@ -1,34 +1,33 @@
 import { t as cx } from "../../class-names-BiMDVpUo.js";
-import { P as MonitorIcon, S as FileIcon, Z as TerminalIcon, d as CheckIcon, z as PlayIcon } from "../../icons-cuEtsgj9.js";
+import { K as SpinnerIcon, S as FileIcon, Z as TerminalIcon, d as CheckIcon, z as PlayIcon } from "../../icons-cuEtsgj9.js";
 import { Button } from "../foundations/Button.js";
 import { IconButton } from "../foundations/IconButton.js";
-import { a as formatErrorMessage } from "../../format-COCyV98Z.js";
-import { EmptyState } from "../foundations/EmptyState.js";
+import { a as formatErrorMessage, o as formatUnknownValue, r as firstLine } from "../../format-COCyV98Z.js";
 import { Field } from "../foundations/Field.js";
 import { Form } from "../foundations/Form.js";
+import { EmptyState } from "../foundations/EmptyState.js";
 import { Input } from "../foundations/Input.js";
 import { DescriptionList } from "../foundations/DescriptionList.js";
-import { Switch } from "../foundations/Switch.js";
+import { Checkbox } from "../foundations/Checkbox.js";
 import { Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle } from "../foundations/Card.js";
-import { i as WorkspaceDeleteControl, n as WorkspaceComposerLink, r as httpUrl, t as FaviconMark } from "../../workspace-assets-CxpEHsac.js";
+import { i as WorkspaceDeleteControl, n as WorkspaceComposerLink, r as httpUrl, t as FaviconMark } from "../../workspace-assets-Bg7XhPsk.js";
 import * as React from "react";
+import { createElement } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useQuery } from "@tanstack/react-query";
+import { useMutation, useQuery } from "@tanstack/react-query";
 //#region src/components/agents-sdk/WorkspaceExecution.tsx
 function draftFrom(parameters) {
-	return Object.fromEntries(parameters.map((parameter) => [parameter.name, parameter.type === "boolean" ? Boolean(parameter.value) : String(parameter.value ?? "")]));
+	return Object.fromEntries(parameters.flatMap((parameter) => parameter.value === void 0 ? [] : [[parameter.name, parameter.type === "boolean" ? Boolean(parameter.value) : String(parameter.value)]]));
 }
 /**
-* Typed values for one run. Empty optional fields are omitted — an absent
-* property is the schema's own "use the default" — while empty required
-* fields and non-numeric numbers refuse the run with a field-level message.
+* Values for one run. Empty and untouched fields stay absent so module
+* defaults work. Schema types improve the input but never gate execution.
 */
 function collectRunParameters(parameters, draft) {
 	const collected = [];
-	const problems = [];
 	for (const parameter of parameters) {
 		if (parameter.type === "boolean") {
-			collected.push({
+			if (Object.hasOwn(draft, parameter.name)) collected.push({
 				...parameter,
 				value: Boolean(draft[parameter.name])
 			});
@@ -36,19 +35,12 @@ function collectRunParameters(parameters, draft) {
 		}
 		const raw = draft[parameter.name];
 		const text = (typeof raw === "string" ? raw : String(raw ?? "")).trim();
-		if (text === "") {
-			if (parameter.required) problems.push(`${parameter.label} is required.`);
-			continue;
-		}
+		if (text === "") continue;
 		if (parameter.type === "number") {
 			const numeric = Number(text);
-			if (!Number.isFinite(numeric)) {
-				problems.push(`${parameter.label} must be a number.`);
-				continue;
-			}
 			collected.push({
 				...parameter,
-				value: numeric
+				value: Number.isFinite(numeric) ? numeric : text
 			});
 			continue;
 		}
@@ -57,66 +49,15 @@ function collectRunParameters(parameters, draft) {
 			value: text
 		});
 	}
-	return problems.length > 0 ? {
-		status: "invalid",
-		message: problems.join(" ")
-	} : {
-		status: "ok",
-		parameters: collected
-	};
+	return collected;
 }
 function snapshotValue(parameter) {
+	if (parameter.value === void 0) return "";
 	if (parameter.type === "boolean") return parameter.value ? "Yes" : "No";
-	return String(parameter.value ?? "");
-}
-function siteHref(value) {
-	return httpUrl(value.includes("://") ? value : `https://${value}`);
-}
-function siteMarks(values) {
-	const marks = [];
-	for (const value of values) {
-		const trimmed = value.trim();
-		if (!trimmed) continue;
-		const href = siteHref(trimmed);
-		let site = trimmed;
-		if (href) try {
-			site = new URL(href).hostname.replace(/^www\./, "");
-		} catch {
-			site = trimmed;
-		}
-		if (!site || marks.some((mark) => mark.site === site)) continue;
-		marks.push({
-			site,
-			href,
-			hint: trimmed
-		});
-	}
-	return marks;
+	return String(parameter.value);
 }
 function ExecutionIcon({ module }) {
-	if (module.icon) return module.icon;
-	const href = siteMarks(module.sites ?? []).find((mark) => mark.href)?.href;
-	return href ? /* @__PURE__ */ jsx(FaviconMark, {
-		href,
-		fallback: /* @__PURE__ */ jsx(TerminalIcon, {})
-	}) : /* @__PURE__ */ jsx(TerminalIcon, {});
-}
-function SiteDetails({ sites }) {
-	const marks = siteMarks(sites);
-	if (marks.length === 0) return null;
-	return /* @__PURE__ */ jsxs(DescriptionList.Item, { children: [/* @__PURE__ */ jsx(DescriptionList.Term, { children: "Sites" }), /* @__PURE__ */ jsx(DescriptionList.Details, { children: /* @__PURE__ */ jsx("div", {
-		className: "sigvelo-cluster",
-		children: marks.map(({ href, hint, site }) => /* @__PURE__ */ jsx(WorkspaceComposerLink, {
-			kind: "tab",
-			value: site,
-			label: site,
-			hint: hint === site ? void 0 : hint,
-			icon: /* @__PURE__ */ jsx(FaviconMark, {
-				href,
-				fallback: /* @__PURE__ */ jsx(MonitorIcon, {})
-			})
-		}, site))
-	}) })] });
+	return module.icon ?? /* @__PURE__ */ jsx(TerminalIcon, {});
 }
 function RunLinks({ runs }) {
 	return /* @__PURE__ */ jsx("div", {
@@ -129,61 +70,63 @@ function RunLinks({ runs }) {
 		}, run.path))
 	});
 }
-function RunDetails({ runState, runs }) {
-	const completed = runState.status === "completed";
-	return /* @__PURE__ */ jsxs(Fragment, { children: [completed ? /* @__PURE__ */ jsxs(DescriptionList.Item, { children: [/* @__PURE__ */ jsx(DescriptionList.Term, { children: "Last run" }), /* @__PURE__ */ jsx(DescriptionList.Details, { children: /* @__PURE__ */ jsxs("div", {
-		className: "sigvelo-cluster",
-		children: [/* @__PURE__ */ jsxs("span", {
-			className: "workspace-execution-outcome",
-			children: [/* @__PURE__ */ jsx(CheckIcon, { size: 14 }), "Completed"]
-		}), runState.runs.length > 0 ? /* @__PURE__ */ jsx(RunLinks, { runs: runState.runs }) : null]
-	}) })] }) : null, runs.length > 0 ? /* @__PURE__ */ jsxs(DescriptionList.Item, { children: [/* @__PURE__ */ jsx(DescriptionList.Term, { children: completed ? "Earlier" : runs.length === 1 ? "Last" : "Runs" }), /* @__PURE__ */ jsx(DescriptionList.Details, { children: /* @__PURE__ */ jsx(RunLinks, { runs }) })] }) : null] });
+function RunDetails({ outcome, runs }) {
+	const completed = outcome !== void 0;
+	const result = outcome?.result != null ? firstLine(formatUnknownValue(outcome.result)) : "";
+	const log = outcome ? firstLine(outcome.logs.join("\n")) : "";
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		completed ? /* @__PURE__ */ jsxs(DescriptionList.Item, { children: [/* @__PURE__ */ jsx(DescriptionList.Term, { children: "Last run" }), /* @__PURE__ */ jsx(DescriptionList.Details, { children: /* @__PURE__ */ jsxs("div", {
+			className: "sigvelo-cluster",
+			children: [/* @__PURE__ */ jsxs("span", {
+				className: "workspace-execution-outcome",
+				children: [/* @__PURE__ */ jsx(CheckIcon, { size: 14 }), "Completed"]
+			}), outcome.runs.length > 0 ? /* @__PURE__ */ jsx(RunLinks, { runs: outcome.runs }) : null]
+		}) })] }) : null,
+		result ? /* @__PURE__ */ jsxs(DescriptionList.Item, { children: [/* @__PURE__ */ jsx(DescriptionList.Term, { children: "Result" }), /* @__PURE__ */ jsx(DescriptionList.Details, { children: result })] }) : null,
+		log ? /* @__PURE__ */ jsxs(DescriptionList.Item, { children: [/* @__PURE__ */ jsx(DescriptionList.Term, { children: "Log" }), /* @__PURE__ */ jsx(DescriptionList.Details, { children: log })] }) : null,
+		runs.length > 0 ? /* @__PURE__ */ jsxs(DescriptionList.Item, { children: [/* @__PURE__ */ jsx(DescriptionList.Term, { children: completed ? "Earlier" : runs.length === 1 ? "Last" : "Runs" }), /* @__PURE__ */ jsx(DescriptionList.Details, { children: /* @__PURE__ */ jsx(RunLinks, { runs }) })] }) : null
+	] });
 }
-function ExecutionFields({ draft, parameters, runState, runs, sites, onDraftChange }) {
+function ExecutionFields({ draft, outcome, parameters, runs, onDraftChange }) {
 	const fieldId = React.useId();
 	const editing = draft != null && onDraftChange != null;
-	const siteItems = siteMarks(sites ?? []);
 	const runItems = runs ?? [];
 	const visibleParameters = editing ? parameters : parameters.filter((parameter) => snapshotValue(parameter) !== "");
-	if (visibleParameters.length === 0 && siteItems.length === 0 && runItems.length === 0 && runState.status !== "completed") return null;
+	if (visibleParameters.length === 0 && runItems.length === 0 && outcome === void 0) return null;
 	return /* @__PURE__ */ jsxs(DescriptionList.Root, {
 		align: "start",
 		variant: "divided",
-		children: [
-			siteItems.length > 0 ? /* @__PURE__ */ jsx(SiteDetails, { sites: sites ?? [] }) : null,
-			visibleParameters.map((parameter) => {
-				const id = `${fieldId}-${parameter.name}`;
-				const href = parameter.type === "string" ? httpUrl(String(editing ? draft?.[parameter.name] ?? parameter.value : parameter.value)) : void 0;
-				return /* @__PURE__ */ jsxs(DescriptionList.Item, { children: [/* @__PURE__ */ jsxs(DescriptionList.Term, {
-					id: parameter.type === "boolean" ? id : void 0,
-					children: [href ? /* @__PURE__ */ jsx(FaviconMark, { href }) : null, editing && parameter.type !== "boolean" ? /* @__PURE__ */ jsx("label", {
-						htmlFor: id,
-						children: parameter.label
-					}) : parameter.label]
-				}), /* @__PURE__ */ jsx(DescriptionList.Details, { children: editing && parameter.type === "boolean" ? /* @__PURE__ */ jsx(Switch.Root, {
-					size: "sm",
-					checked: Boolean(draft?.[parameter.name]),
-					"aria-labelledby": id,
-					onCheckedChange: (checked) => {
-						if (typeof checked === "boolean") onDraftChange?.(parameter.name, checked);
-					},
-					children: /* @__PURE__ */ jsx(Switch.Thumb, {})
-				}) : editing ? /* @__PURE__ */ jsx(Input, {
-					id,
-					name: parameter.name,
-					type: href ? "url" : void 0,
-					required: parameter.required || void 0,
-					value: String(draft?.[parameter.name] ?? ""),
-					autoComplete: "off",
-					inputMode: parameter.type === "number" ? "decimal" : void 0,
-					onChange: (event) => onDraftChange?.(parameter.name, event.currentTarget.value)
-				}) : snapshotValue(parameter) })] }, parameter.name);
-			}),
-			/* @__PURE__ */ jsx(RunDetails, {
-				runState,
-				runs: runItems
-			})
-		]
+		children: [visibleParameters.map((parameter) => {
+			const id = `${fieldId}-${parameter.name}`;
+			const parameterLabel = editing && parameter.required ? `${parameter.label} (required)` : parameter.label;
+			const href = parameter.type === "string" ? httpUrl(String(editing ? draft?.[parameter.name] ?? parameter.value : parameter.value)) : void 0;
+			return /* @__PURE__ */ jsxs(DescriptionList.Item, { children: [/* @__PURE__ */ jsxs(DescriptionList.Term, {
+				id: parameter.type === "boolean" ? id : void 0,
+				children: [href ? /* @__PURE__ */ jsx(FaviconMark, { href }) : null, editing && parameter.type !== "boolean" ? /* @__PURE__ */ jsx("label", {
+					htmlFor: id,
+					children: parameterLabel
+				}) : parameterLabel]
+			}), /* @__PURE__ */ jsx(DescriptionList.Details, { children: editing && parameter.type === "boolean" ? /* @__PURE__ */ jsx(Checkbox.Root, {
+				checked: draft?.[parameter.name] === true,
+				indeterminate: draft?.[parameter.name] === void 0,
+				"aria-labelledby": id,
+				onCheckedChange: (checked) => {
+					if (typeof checked === "boolean") onDraftChange?.(parameter.name, checked);
+				},
+				children: /* @__PURE__ */ jsx(Checkbox.Indicator, {})
+			}) : editing ? /* @__PURE__ */ jsx(Input, {
+				id,
+				name: parameter.name,
+				type: href ? "url" : void 0,
+				value: String(draft?.[parameter.name] ?? ""),
+				autoComplete: "off",
+				inputMode: parameter.type === "number" ? "decimal" : void 0,
+				onChange: (event) => onDraftChange?.(parameter.name, event.currentTarget.value)
+			}) : snapshotValue(parameter) })] }, parameter.name);
+		}), /* @__PURE__ */ jsx(RunDetails, {
+			outcome,
+			runs: runItems
+		})]
 	});
 }
 function ExecutionActions({ busy, module }) {
@@ -218,50 +161,40 @@ function ExecutionActions({ busy, module }) {
 function executionFormKey(module) {
 	return `${module.path}:${JSON.stringify(module.parameters)}`;
 }
-function WorkspaceExecutionCard({ className, module, ref, ...props }) {
+function WorkspaceExecutionCard({ module, ...props }) {
+	return /* @__PURE__ */ createElement(WorkspaceExecutionCardSession, {
+		...props,
+		key: module.path,
+		module
+	});
+}
+function WorkspaceExecutionCardSession({ className, module, ref, ...props }) {
 	const titleId = React.useId();
 	const ariaLabel = props["aria-label"];
 	const ariaLabelledBy = props["aria-labelledby"] ?? (ariaLabel ? void 0 : titleId);
 	const editing = module.onRun != null;
 	const [draft, setDraft] = React.useState(() => draftFrom(module.parameters));
-	const [runState, setRunState] = React.useState({ status: "idle" });
-	const [validationMessage, setValidationMessage] = React.useState("");
 	const formKey = executionFormKey(module);
 	const [seenFormKey, setSeenFormKey] = React.useState(formKey);
 	if (formKey !== seenFormKey) {
 		setSeenFormKey(formKey);
 		setDraft(draftFrom(module.parameters));
-		setValidationMessage("");
 	}
-	const busy = runState.status === "running";
-	const run = async () => {
-		if (!module.onRun || busy) return;
-		const submission = collectRunParameters(module.parameters, draft);
-		if (submission.status === "invalid") {
-			setValidationMessage(submission.message);
-			return;
-		}
-		setValidationMessage("");
-		setRunState({ status: "running" });
-		try {
-			setRunState({
-				status: "completed",
-				runs: await module.onRun(submission.parameters)
-			});
-		} catch (error) {
-			setRunState({
-				status: "failed",
-				message: formatErrorMessage(error)
-			});
-		}
-	};
-	const errorMessage = validationMessage || (runState.status === "failed" ? runState.message : "");
-	const hasBody = module.parameters.length > 0 || (module.sites?.length ?? 0) > 0 || (module.runs?.length ?? 0) > 0 || runState.status === "completed" || editing || Boolean(errorMessage);
+	const runMutation = useMutation({ mutationFn: async () => {
+		if (!module.onRun) throw new Error("Execution is no longer available.");
+		return module.onRun(collectRunParameters(module.parameters, draft));
+	} });
+	const busy = runMutation.isPending;
+	const errorMessage = runMutation.isError ? formatErrorMessage(runMutation.error) : "";
+	const hasBody = module.parameters.length > 0 || (module.runs?.length ?? 0) > 0 || runMutation.isSuccess || editing || Boolean(errorMessage);
 	const header = /* @__PURE__ */ jsxs(CardHeader, { children: [
 		/* @__PURE__ */ jsxs(CardTitle, {
 			id: titleId,
 			className: "connected-app-card__title",
-			render: /* @__PURE__ */ jsx("h3", {}),
+			render: (props) => /* @__PURE__ */ jsx("h3", {
+				...props,
+				children: props.children
+			}),
 			children: [/* @__PURE__ */ jsx("span", {
 				className: "connected-app-card__icon",
 				"aria-hidden": "true",
@@ -277,30 +210,27 @@ function WorkspaceExecutionCard({ className, module, ref, ...props }) {
 	const body = hasBody ? /* @__PURE__ */ jsxs(CardContent, { children: [
 		/* @__PURE__ */ jsx(ExecutionFields, {
 			draft: editing ? draft : void 0,
+			outcome: runMutation.isSuccess ? runMutation.data : void 0,
 			parameters: module.parameters,
-			runState,
 			runs: module.runs,
-			sites: module.sites,
-			onDraftChange: editing ? (name, value) => {
-				setValidationMessage("");
-				setDraft((current) => ({
-					...current,
-					[name]: value
-				}));
-			} : void 0
+			onDraftChange: editing ? (name, value) => setDraft((current) => ({
+				...current,
+				[name]: value
+			})) : void 0
 		}),
 		errorMessage ? /* @__PURE__ */ jsx(Field.Errors, { errors: [errorMessage] }) : null,
 		/* @__PURE__ */ jsx("span", {
 			className: "sigvelo-visually-hidden",
 			role: "status",
 			"aria-atomic": "true",
-			children: errorMessage || (busy ? "Running" : runState.status === "completed" ? "Completed" : "")
+			children: errorMessage || (busy ? "Running" : runMutation.isSuccess ? "Completed" : "")
 		})
 	] }) : null;
 	const inner = editing ? /* @__PURE__ */ jsxs(Form, {
+		noValidate: true,
 		onSubmit: (event) => {
 			event.preventDefault();
-			run();
+			if (!busy) runMutation.mutate();
 		},
 		children: [header, body]
 	}) : /* @__PURE__ */ jsxs(Fragment, { children: [header, body] });
@@ -324,13 +254,15 @@ function WorkspaceExecutionFile({ fallback = null, path, source, ...props }) {
 	return /* @__PURE__ */ jsx(WorkspaceExecutionCard, {
 		...props,
 		module: executionWithSource(module, source)
-	});
+	}, JSON.stringify(source.queryOptions.queryKey));
 }
 /**
 * Workbench library. Same card as the inline placement. A query failure with
 * nothing loaded renders as a quiet inline error, never as an empty library.
 */
-function WorkspaceExecutionsPanel({ className, error, modules, onRetry, ref, ...props }) {
+function WorkspaceExecutionsPanel({ className, source, ref, ...props }) {
+	const query = useQuery(source.queryOptions);
+	const modules = query.data ?? [];
 	return /* @__PURE__ */ jsx("section", {
 		ref,
 		"data-slot": "workspace-executions-panel",
@@ -339,23 +271,26 @@ function WorkspaceExecutionsPanel({ className, error, modules, onRetry, ref, ...
 		"aria-label": props["aria-label"] ?? "Executions",
 		children: modules.length > 0 ? /* @__PURE__ */ jsx("ul", {
 			className: "sigvelo-stack-list sigvelo-stack",
-			children: modules.map((module) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx(WorkspaceExecutionCard, { module }) }, module.path))
-		}) : error !== void 0 ? /* @__PURE__ */ jsx(EmptyState, {
+			children: modules.map((module) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx(WorkspaceExecutionCard, { module: executionWithSource(module, source) }) }, module.path))
+		}) : query.error ? /* @__PURE__ */ jsx(EmptyState, {
 			icon: /* @__PURE__ */ jsx(TerminalIcon, {}),
 			title: "Executions unavailable",
-			description: error,
-			children: onRetry ? /* @__PURE__ */ jsx(Button, {
+			description: formatErrorMessage(query.error),
+			children: /* @__PURE__ */ jsx(Button, {
 				size: "sm",
 				variant: "outline",
 				color: "neutral",
-				onClick: onRetry,
+				onClick: () => void query.refetch(),
 				children: "Retry"
-			}) : null
+			})
+		}) : query.isPending ? /* @__PURE__ */ jsx(EmptyState, {
+			icon: /* @__PURE__ */ jsx(SpinnerIcon, {}),
+			title: "Loading modules"
 		}) : /* @__PURE__ */ jsx(EmptyState, {
 			icon: /* @__PURE__ */ jsx(TerminalIcon, {}),
 			title: "No modules"
 		})
-	});
+	}, JSON.stringify(source.queryOptions.queryKey));
 }
 function executionWithSource(module, source) {
 	const { onDelete, onOpen, onRun } = source;
@@ -366,28 +301,16 @@ function executionWithSource(module, source) {
 	return {
 		...module,
 		runs: module.runs?.map(withOpen),
-		onRun: onRun ? async (parameters) => (await onRun(module.path, parameters)).map(withOpen) : void 0,
+		onRun: onRun ? async (parameters) => {
+			const outcome = await onRun(module.path, parameters);
+			return {
+				...outcome,
+				runs: outcome.runs.map(withOpen)
+			};
+		} : void 0,
 		onOpen: onOpen ? () => onOpen(module.path) : void 0,
 		onDelete: onDelete ? () => onDelete(module.path) : void 0
 	};
 }
-function WorkspaceExecutionSourcePanel({ source }) {
-	const query = useQuery(source.queryOptions);
-	return /* @__PURE__ */ jsx(WorkspaceExecutionsPanel, {
-		modules: (query.data ?? []).map((module) => executionWithSource(module, source)),
-		error: query.isError ? formatErrorMessage(query.error) : void 0,
-		onRetry: query.isError ? () => void query.refetch() : void 0,
-		"aria-busy": query.isFetching || void 0
-	});
-}
-/** Canonical workbench descriptor; hosts supply only the source adapter. */
-function workspaceExecutionsPanel(source) {
-	return {
-		id: "executions",
-		label: "Executions",
-		icon: /* @__PURE__ */ jsx(TerminalIcon, {}),
-		render: () => /* @__PURE__ */ jsx(WorkspaceExecutionSourcePanel, { source })
-	};
-}
 //#endregion
-export { WorkspaceExecutionCard, WorkspaceExecutionFile, WorkspaceExecutionsPanel, workspaceExecutionsPanel };
+export { WorkspaceExecutionCard, WorkspaceExecutionFile, WorkspaceExecutionsPanel };

package/dist/components/agents-sdk/WorkspaceExplorer.d.ts

@@ -1,9 +1,10 @@
 import { l as WorkspaceNavigationAdapter } from "../../WorkspaceLink-Bh9-Jo1r.js";
-import { b as WorkspaceState } from "../../Workspace-C_zHq9KZ.js";
+import { b as WorkspaceState } from "../../Workspace-HzGrWDX3.js";
 import * as React from "react";
 
 //#region src/components/agents-sdk/WorkspaceExplorer.d.ts
 interface WorkspaceExplorerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  /** Workspace state that owns the file tree, selection, loading, and refresh behavior. */
   workspace: WorkspaceState;
   /** Host-owned URL/history adapter shared by chat links and the file explorer. */
   navigation: WorkspaceNavigationAdapter;
@@ -15,7 +16,9 @@ interface WorkspaceExplorerProps extends Omit<React.HTMLAttributes<HTMLDivElemen
   actions?: React.ReactNode;
   /** Show the file filter input. Hidden by default to keep the browser compact. */
   showFilter?: boolean;
+  /** Placeholder for the optional file filter. */
   filterPlaceholder?: string;
+  /** Content shown when the workspace contains no visible files. */
   emptyState?: React.ReactNode;
 }
 /**
@@ -26,7 +29,7 @@ interface WorkspaceExplorerProps extends Omit<React.HTMLAttributes<HTMLDivElemen
 declare function WorkspaceExplorer({
   ...props
 }: WorkspaceExplorerProps & {
-  ref?: React.Ref<HTMLDivElement>;
+  /** Ref forwarded to the component's rendered root element. */ref?: React.Ref<HTMLDivElement>;
 }): React.JSX.Element;
 //#endregion
 export { WorkspaceExplorer, WorkspaceExplorerProps };

package/dist/components/agents-sdk/WorkspaceExplorer.js

@@ -1,8 +1,9 @@
 import { t as cx } from "../../class-names-BiMDVpUo.js";
 import { n as mergeRefs } from "../../merge-refs-DF_7w2x_.js";
-import { a as WorkspaceNavigationRestorationBoundary, n as WorkspaceNavigationProvider, o as useRequiredWorkspaceNavigationRestoration, r as resolveWorkspaceLink } from "../../WorkspaceLink-B1d2GIGl.js";
+import { n as WorkspaceNavigationProvider, r as resolveWorkspaceLink } from "../../WorkspaceLink-BYZG-V_I.js";
+import { WorkspaceNavigationRestorationBoundary, useRequiredWorkspaceNavigationRestoration } from "./WorkspaceNavigationRestoration.js";
 import { WorkspaceBrowser } from "./WorkspaceBrowser.js";
-import { t as WorkspaceFileView } from "../../WorkspaceFileView-ChIJz-fl.js";
+import { t as WorkspaceFileView } from "../../WorkspaceFileView-DYPtRVpM.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/agents-sdk/WorkspaceExplorer.tsx

package/dist/components/agents-sdk/WorkspaceFile.d.ts

@@ -1,2 +1,2 @@
-import { _ as isWorkspaceTextPath, a as WorkspaceMediaInfo, c as WorkspaceMediaTrackKind, d as inferWorkspaceLanguage, f as inferWorkspaceMedia, g as isWorkspaceSkillPath, h as isWorkspaceMediaPath, i as WorkspaceFileState, l as WorkspaceSkillDocument, m as isWorkspaceMarkdownPath, n as WorkspaceFileAssetRequest, o as WorkspaceMediaKind, p as inferWorkspaceMimeType, r as WorkspaceFileAssetResolver, s as WorkspaceMediaTrack, t as WorkspaceFileAsset, u as getWorkspaceBasename, v as parseWorkspaceSkill } from "../../WorkspaceFile-Dq-GC0_T.js";
+import { _ as isWorkspaceTextPath, a as WorkspaceMediaInfo, c as WorkspaceMediaTrackKind, d as inferWorkspaceLanguage, f as inferWorkspaceMedia, g as isWorkspaceSkillPath, h as isWorkspaceMediaPath, i as WorkspaceFileState, l as WorkspaceSkillDocument, m as isWorkspaceMarkdownPath, n as WorkspaceFileAssetRequest, o as WorkspaceMediaKind, p as inferWorkspaceMimeType, r as WorkspaceFileAssetResolver, s as WorkspaceMediaTrack, t as WorkspaceFileAsset, u as getWorkspaceBasename, v as parseWorkspaceSkill } from "../../WorkspaceFile-Bouauobc.js";
 export { WorkspaceFileAsset, WorkspaceFileAssetRequest, WorkspaceFileAssetResolver, WorkspaceFileState, WorkspaceMediaInfo, WorkspaceMediaKind, WorkspaceMediaTrack, WorkspaceMediaTrackKind, WorkspaceSkillDocument, getWorkspaceBasename, inferWorkspaceLanguage, inferWorkspaceMedia, inferWorkspaceMimeType, isWorkspaceMarkdownPath, isWorkspaceMediaPath, isWorkspaceSkillPath, isWorkspaceTextPath, parseWorkspaceSkill };

package/dist/components/agents-sdk/WorkspaceFileView.d.ts

@@ -1,4 +1,4 @@
-import { i as WorkspaceFileState } from "../../WorkspaceFile-Dq-GC0_T.js";
+import { i as WorkspaceFileState } from "../../WorkspaceFile-Bouauobc.js";
 import * as React from "react";
 
 //#region src/components/agents-sdk/WorkspaceFileView.d.ts

package/dist/components/agents-sdk/WorkspaceFileView.js

@@ -1,2 +1,2 @@
-import { t as WorkspaceFileView } from "../../WorkspaceFileView-ChIJz-fl.js";
+import { t as WorkspaceFileView } from "../../WorkspaceFileView-DYPtRVpM.js";
 export { WorkspaceFileView };

package/dist/components/agents-sdk/WorkspaceLink.js

@@ -1,2 +1,2 @@
-import { n as WorkspaceNavigationProvider, r as resolveWorkspaceLink, t as WorkspaceFileLink } from "../../WorkspaceLink-B1d2GIGl.js";
+import { n as WorkspaceNavigationProvider, r as resolveWorkspaceLink, t as WorkspaceFileLink } from "../../WorkspaceLink-BYZG-V_I.js";
 export { WorkspaceFileLink, WorkspaceNavigationProvider, resolveWorkspaceLink };

package/dist/components/agents-sdk/WorkspaceLive.d.ts

@@ -1,2 +1,61 @@
-import { a as useWorkspaceLiveQueries, i as invalidateWorkspaceDirectories, n as WorkspaceChange, r as WorkspaceChangeSource, t as UseWorkspaceLiveQueriesOptions } from "../../WorkspaceLive-DLGhtIly.js";
+import { r as WorkspaceFileAssetResolver } from "../../WorkspaceFile-Bouauobc.js";
+import { y as WorkspaceSource } from "../../Workspace-HzGrWDX3.js";
+import { QueryClient } from "@tanstack/react-query";
+
+//#region src/components/agents-sdk/WorkspaceLive.d.ts
+type WorkspaceChange = {
+  type: "changed";
+  path: string;
+  movedFrom?: string;
+} | {
+  type: "unknown";
+};
+/** Host adapter for a native workspace observer. */
+interface WorkspaceChangeSource {
+  start?(): void | Promise<void>;
+  subscribe(listener: (change: WorkspaceChange) => void): () => void;
+}
+declare function invalidateWorkspaceDirectories(queryClient: QueryClient, sourceKey: string, directories: Iterable<string>, root: string): void;
+interface UseWorkspaceLiveQueriesOptions {
+  /** Native observer adapter. Omit for hosts without workspace observation. */
+  changes?: WorkspaceChangeSource;
+  sourceKey: string | undefined;
+  /**
+   * The host's workspace boundary. Required, and the same value the concept
+   * options were built with: invalidation is prefix-matched on it, so a root
+   * that disagrees with the queries silently invalidates nothing.
+   */
+  root: string;
+  /** Workspace read adapter used to refresh an observed open file in order. */
+  source?: WorkspaceSource;
+  /** Route-owned open file. Omit or pass null when Files has no selection. */
+  selectedPath?: string | null;
+  resolveFileAsset?: WorkspaceFileAssetResolver;
+  maxInlineAssetBytes?: number;
+  /**
+   * Disposable freshness tick for hosts without native observation — for
+   * example a serialization of settled-turn state. Every change of a defined
+   * value invalidates the source's concept queries. It never enters query
+   * identity, so data, mutation state, and form drafts survive the refresh.
+   */
+  revision?: string;
+}
+/**
+ * Synchronize external workspace freshness with the design system's Query
+ * resources. This is the one external-system effect: native observer events
+ * and host revision ticks both land here as targeted invalidation against
+ * stable query keys. Hosts only supply events; neither layer adds another
+ * watcher.
+ */
+declare function useWorkspaceLiveQueries({
+  changes,
+  maxInlineAssetBytes,
+  resolveFileAsset,
+  selectedPath,
+  source,
+  sourceKey,
+  root,
+  revision
+}: UseWorkspaceLiveQueriesOptions): void;
+//#endregion
 export { UseWorkspaceLiveQueriesOptions, WorkspaceChange, WorkspaceChangeSource, invalidateWorkspaceDirectories, useWorkspaceLiveQueries };