basalt-ui 1.9.0 → 1.11.0

package/dist/agent-chat/thread-message.d.ts

@@ -1,5 +1,5 @@
 import type { JSX } from 'react';
-import type { AgentPart, AgentPartRenderers, ChatMessage, StreamStatus } from '../agent/index.js';
+import type { AgentPartRenderers, ChatMessage, ForeignPart, PartRenderer, PartRenderers, StreamStatus, TranscriptPart } from '../agent/index.js';
 /**
  * Mantine overrides for `PartList`'s default headless renderers — the house style for rendering
  * an `AgentPart` inside a chat surface.
@@ -10,22 +10,39 @@ import type { AgentPart, AgentPartRenderers, ChatMessage, StreamStatus } from '.
  * <PartList parts={parts} components={threadPartRenderers} />
  */
 export declare const threadPartRenderers: Partial<AgentPartRenderers>;
-export type ThreadTranscriptProps = {
+/**
+ * Render-execution counter for `MessageBlockImpl` — increments only when React actually calls the
+ * function body (a `memo` bail-out never reaches it). NOT part of the public surface —
+ * `agent-chat/index.ts` does not re-export it. The memoization test imports this module directly
+ * (bypassing the barrel) to prove the memo boundary in a controlled render-count harness.
+ */
+export declare const messageBlockRenderCounter: {
+    count: number;
+};
+type ThreadTranscriptBase = {
     /** Settled messages for the thread, oldest first. */
-    readonly messages: ChatMessage[];
+    readonly messages: readonly ChatMessage<TranscriptPart>[];
     /** The live (in-flight) assistant turn's parts, when a run is streaming for this thread. */
-    readonly liveParts?: AgentPart[];
+    readonly liveParts?: readonly TranscriptPart[];
     /** The live run's status — drives the in-progress indicator on the live block. */
     readonly liveStatus?: StreamStatus;
+    /** Consumer renderers keyed by part.type. Consulted BEFORE the built-in union. */
+    readonly renderers?: PartRenderers;
+    /** Called for a part whose type is neither an AgentPart variant nor a registered key. Defaults
+     * to a visible `UnknownPartChip` outside production, `null` in production — never throws. */
+    readonly fallbackRenderer?: PartRenderer<ForeignPart>;
 };
+export type ThreadTranscriptProps = ThreadTranscriptBase;
 /**
- * Renders a thread's settled messages, each role-labelled ("You" / "Assistant") and rendered via
- * `PartList` + `threadPartRenderers`. When `liveParts` is non-empty, an extra in-progress
+ * Renders a thread's settled messages, each role-labelled ("You" / "Assistant"). Each part
+ * resolves in order: a registered `renderers[part.type]` first, then basalt's own `PartList` for
+ * the built-in six, then `fallbackRenderer`. When `liveParts` is non-empty, an extra in-progress
  * assistant block is appended at the tail.
  *
  * @example
  * import { ThreadTranscript } from 'basalt-ui'
  * <ThreadTranscript messages={thread.messages} liveParts={liveParts} liveStatus={runStatus} />
  */
-export declare function ThreadTranscript({ messages, liveParts, liveStatus, }: ThreadTranscriptProps): JSX.Element;
+export declare function ThreadTranscript({ messages, liveParts, liveStatus, renderers: renderersProp, fallbackRenderer, }: ThreadTranscriptProps): JSX.Element;
+export {};
 //# sourceMappingURL=thread-message.d.ts.map

package/dist/agent-chat/thread-message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"thread-message.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-message.tsx"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,KAAK,EACV,SAAS,EACT,kBAAkB,EAClB,WAAW,EAIX,YAAY,EAGb,MAAM,UAAU,CAAA;AAmGjB;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,kBAAkB,CAM3D,CAAA;AAyDD,MAAM,MAAM,qBAAqB,GAAG;IAClC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAA;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,CAAA;IAChC,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,CAAA;CACnC,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,SAAS,EACT,UAAU,GACX,EAAE,qBAAqB,GAAG,GAAG,CAAC,OAAO,CAiBrC"}
+{"version":3,"file":"thread-message.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-message.tsx"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,KAAK,EAEV,kBAAkB,EAClB,WAAW,EAEX,WAAW,EACX,YAAY,EACZ,aAAa,EAGb,YAAY,EAGZ,cAAc,EACf,MAAM,UAAU,CAAA;AAkFjB;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,kBAAkB,CAM3D,CAAA;AAqID;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;CAAe,CAAA;AA8ErD,KAAK,oBAAoB,GAAG;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,CAAC,cAAc,CAAC,EAAE,CAAA;IACzD,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IAC9C,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,CAAA;IAClC,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAA;IAClC;iGAC6F;IAC7F,QAAQ,CAAC,gBAAgB,CAAC,EAAE,YAAY,CAAC,WAAW,CAAC,CAAA;CACtD,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG,oBAAoB,CAAA;AAExD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,SAAS,EACT,UAAU,EACV,SAAS,EAAE,aAAa,EACxB,gBAA4C,GAC7C,EAAE,qBAAqB,GAAG,GAAG,CAAC,OAAO,CAgCrC"}

package/dist/agent-chat/thread-message.js

@@ -11,9 +11,11 @@ import {
   UnstyledButton
 } from "@mantine/core";
 import { useDisclosure } from "@mantine/hooks";
-import { PartList } from "../agent/index.js";
+import { Fragment, memo, useMemo } from "react";
+import { coalesceParts, narrowAgentPart, PartList } from "../agent/index.js";
 import { Markdown } from "../content/markdown.js";
-import { alpha, VX } from "../tokens/index.js";
+import { VX } from "../tokens/index.js";
+import { ToolChip } from "./tool-chip.js";
 const MICRO_LABEL_STYLE = {
   fontFamily: "var(--basalt-font-mono)",
   fontSize: VX.text.micro,
@@ -29,16 +31,6 @@ const RAIL_STYLE = {
   borderLeft: `2px solid ${VX.divider}`,
   paddingLeft: "var(--vx-space-agent-rail-inset-x)"
 };
-const CODE_BLOCK_STYLE = {
-  margin: 0,
-  marginTop: "var(--vx-space-agent-part-gap-top)",
-  fontFamily: "var(--basalt-font-mono)",
-  backgroundColor: alpha(VX.ink, 0.06),
-  borderRadius: "var(--vx-radius-card)",
-  padding: "var(--vx-space-agent-code-inset)",
-  whiteSpace: "pre-wrap",
-  overflowWrap: "anywhere"
-};
 function ReasoningRenderer({ part }) {
   const [open, { toggle }] = useDisclosure(false);
   return /* @__PURE__ */ jsx(Box, { style: RAIL_STYLE, children: /* @__PURE__ */ jsxs(Stack, { gap: 4, children: [
@@ -46,12 +38,8 @@ function ReasoningRenderer({ part }) {
     /* @__PURE__ */ jsx(Collapse, { expanded: open, children: /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", style: { whiteSpace: "pre-wrap" }, children: part.text }) })
   ] }) });
 }
-function ToolRenderer({ part }) {
-  return /* @__PURE__ */ jsx(Box, { style: RAIL_STYLE, children: /* @__PURE__ */ jsxs(Stack, { gap: 4, children: [
-    /* @__PURE__ */ jsx(Text, { style: MICRO_LABEL_STYLE, children: part.toolName }),
-    /* @__PURE__ */ jsx(Text, { component: "pre", size: "xs", style: CODE_BLOCK_STYLE, children: JSON.stringify(part.input, null, 2) }),
-    part.output !== void 0 && /* @__PURE__ */ jsx(Text, { component: "pre", size: "xs", style: CODE_BLOCK_STYLE, children: JSON.stringify(part.output, null, 2) })
-  ] }) });
+function ToolChipRenderer({ part }) {
+  return /* @__PURE__ */ jsx(ToolChip, { part });
 }
 function SourceRenderer({ part }) {
   return /* @__PURE__ */ jsx(Anchor, { href: part.url, target: "_blank", rel: "noopener noreferrer", size: "sm", children: part.title ?? part.url });
@@ -62,70 +50,141 @@ function ErrorRenderer({ part }) {
 const threadPartRenderers = {
   text: TextRenderer,
   reasoning: ReasoningRenderer,
-  tool: ToolRenderer,
+  tool: ToolChipRenderer,
   source: SourceRenderer,
   error: ErrorRenderer
 };
-function coalesceParts(parts) {
-  const out = [];
+function UnknownPartChip({ part }) {
+  return /* @__PURE__ */ jsx(Box, { style: RAIL_STYLE, children: /* @__PURE__ */ jsx(Text, { style: MICRO_LABEL_STYLE, children: `Unknown part: ${part.type}` }) });
+}
+const DEFAULT_FALLBACK_RENDERER = ({ part }) => process.env["NODE_ENV"] !== "production" ? /* @__PURE__ */ jsx(UnknownPartChip, { part }) : null;
+function resolveSegments(parts, renderers, fallbackRenderer) {
+  const segments = [];
+  let buffer = [];
+  const flushBuffer = () => {
+    const first = buffer[0];
+    if (first === void 0) return;
+    segments.push({ kind: "agent", key: first.id, parts: coalesceParts(buffer) });
+    buffer = [];
+  };
   for (const part of parts) {
-    const last = out[out.length - 1];
-    if (part.type === "text" && last?.type === "text") {
-      out[out.length - 1] = { type: "text", text: last.text + part.text };
-    } else if (part.type === "reasoning" && last?.type === "reasoning") {
-      out[out.length - 1] = { type: "reasoning", text: last.text + part.text };
-    } else {
-      out.push(part);
+    const consumerRenderer = renderers[part.type];
+    if (consumerRenderer !== void 0) {
+      flushBuffer();
+      segments.push({
+        kind: "foreign",
+        key: part.id,
+        part,
+        render: consumerRenderer
+      });
+      continue;
+    }
+    const agentPart = narrowAgentPart(part);
+    if (agentPart !== null) {
+      buffer.push(agentPart);
+      continue;
     }
+    flushBuffer();
+    segments.push({
+      kind: "foreign",
+      key: part.id,
+      part,
+      render: fallbackRenderer
+    });
   }
-  return out;
+  flushBuffer();
+  return segments;
 }
 const ROLE_LABEL = {
   user: "You",
   assistant: "Assistant"
 };
-function MessageBlock({
-  author,
-  parts,
-  streaming = false
+const FINISH_INDICATOR = {
+  stopped: { label: "Stopped", statusToken: VX.status.warn },
+  error: { label: "Error", statusToken: VX.status.bad }
+};
+const messageBlockRenderCounter = { count: 0 };
+function MessageBlockImpl({
+  message,
+  streaming = false,
+  renderers,
+  fallbackRenderer
 }) {
+  messageBlockRenderCounter.count += 1;
+  const settled = !streaming;
+  const segments = useMemo(
+    () => resolveSegments(message.parts, renderers, fallbackRenderer),
+    [message.parts, renderers, fallbackRenderer]
+  );
+  const finishIndicator = message.finish === void 0 ? void 0 : FINISH_INDICATOR[message.finish];
   return /* @__PURE__ */ jsx(
     Box,
     {
       style: {
         padding: "var(--vx-space-agent-message-inset-y) var(--vx-space-agent-message-inset-x)",
-        backgroundColor: author === "user" ? VX.surface.subtle : VX.surface.panel,
+        backgroundColor: message.role === "user" ? VX.surface.subtle : VX.surface.panel,
         borderRadius: VX.radiusCard,
         boxShadow: VX.shadowCard
       },
       children: /* @__PURE__ */ jsxs(Stack, { gap: 6, children: [
         /* @__PURE__ */ jsxs(Group, { gap: 6, align: "center", children: [
-          /* @__PURE__ */ jsx(Text, { style: MICRO_LABEL_STYLE, children: ROLE_LABEL[author] }),
-          streaming && /* @__PURE__ */ jsx(Loader, { size: "xs" })
+          /* @__PURE__ */ jsx(Text, { style: MICRO_LABEL_STYLE, children: ROLE_LABEL[message.role] }),
+          streaming && /* @__PURE__ */ jsx(Loader, { size: "xs" }),
+          finishIndicator !== void 0 && /* @__PURE__ */ jsx(Text, { style: { ...MICRO_LABEL_STYLE, color: finishIndicator.statusToken }, children: finishIndicator.label })
         ] }),
-        /* @__PURE__ */ jsx(PartList, { parts: coalesceParts(parts), components: threadPartRenderers })
+        segments.map(
+          (segment) => segment.kind === "agent" ? /* @__PURE__ */ jsx(PartList, { parts: segment.parts, components: threadPartRenderers }, segment.key) : /* @__PURE__ */ jsx(Fragment, { children: segment.render({
+            part: segment.part,
+            messageId: message.id,
+            partId: segment.part.id,
+            settled,
+            role: message.role
+          }) }, segment.key)
+        )
       ] })
     }
   );
 }
+function areMessageBlockPropsEqual(prev, next) {
+  return prev.message === next.message && prev.streaming === next.streaming && prev.renderers === next.renderers && prev.fallbackRenderer === next.fallbackRenderer;
+}
+const MessageBlock = memo(MessageBlockImpl, areMessageBlockPropsEqual);
+const EMPTY_RENDERERS = {};
 function ThreadTranscript({
   messages,
   liveParts,
-  liveStatus
+  liveStatus,
+  renderers: renderersProp,
+  fallbackRenderer = DEFAULT_FALLBACK_RENDERER
 }) {
+  const renderers = useMemo(() => renderersProp ?? EMPTY_RENDERERS, [renderersProp]);
+  const liveMessage = useMemo(() => {
+    if (liveParts === void 0 || liveParts.length === 0) return null;
+    return { id: "__live__", role: "assistant", parts: liveParts, createdAt: 0 };
+  }, [liveParts]);
   return /* @__PURE__ */ jsxs(Stack, { gap: "sm", children: [
-    messages.map((message) => /* @__PURE__ */ jsx(MessageBlock, { author: message.role, parts: message.parts }, message.id)),
-    liveParts !== void 0 && liveParts.length > 0 && /* @__PURE__ */ jsx("div", { "aria-live": "polite", "aria-atomic": "false", "aria-relevant": "additions", children: /* @__PURE__ */ jsx(
+    messages.map((message) => /* @__PURE__ */ jsx(
+      MessageBlock,
+      {
+        message,
+        renderers,
+        fallbackRenderer
+      },
+      message.id
+    )),
+    liveMessage !== null && /* @__PURE__ */ jsx("div", { "aria-live": "polite", "aria-atomic": "false", "aria-relevant": "additions", children: /* @__PURE__ */ jsx(
       MessageBlock,
       {
-        author: "assistant",
-        parts: liveParts,
-        streaming: liveStatus === "streaming"
+        message: liveMessage,
+        streaming: liveStatus === "streaming",
+        renderers,
+        fallbackRenderer
       }
     ) })
   ] });
 }
 export {
   ThreadTranscript,
+  messageBlockRenderCounter,
   threadPartRenderers
 };

package/dist/agent-chat/tool-chip.d.ts

@@ -0,0 +1,21 @@
+import type { JSX } from 'react';
+import type { ToolCallPart } from '../agent/index.js';
+export type ToolChipProps = {
+    readonly part: ToolCallPart;
+    readonly defaultExpanded?: boolean;
+    /** Rendered only in 'approval-requested'. Omit both to render a read-only chip. */
+    readonly onApprove?: (approvalId: string) => void;
+    readonly onDeny?: (approvalId: string, reason?: string) => void;
+};
+/**
+ * A collapsed-by-default row for a single tool-call part. All seven wire states render something
+ * sane; the switch above still gates an eighth (compile-time-unhandled) state as a tsc error via a
+ * `const _: never = part` assignment, but unlike a truly-closed switch, its `default` branch never
+ * throws at RUNTIME — a value from persisted/wire data that reaches here with a `state` this build
+ * doesn't recognize renders an inert 'unknown' chip instead of blanking the transcript.
+ *
+ * @example
+ * <ToolChip part={part} />
+ */
+export declare function ToolChip({ part, defaultExpanded, onApprove, onDeny, }: ToolChipProps): JSX.Element;
+//# sourceMappingURL=tool-chip.d.ts.map

package/dist/agent-chat/tool-chip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-chip.d.ts","sourceRoot":"","sources":["../../src/agent-chat/tool-chip.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAEhC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AA4E5C,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;IAClC,mFAAmF;IACnF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAA;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAChE,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,EACvB,IAAI,EACJ,eAAuB,EACvB,SAAS,EACT,MAAM,GACP,EAAE,aAAa,GAAG,GAAG,CAAC,OAAO,CAiG7B"}

package/dist/agent-chat/tool-chip.js

@@ -0,0 +1,120 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Box, Button, Collapse, Group, Stack, Text, UnstyledButton } from "@mantine/core";
+import { useDisclosure } from "@mantine/hooks";
+import { isToolCallSettled } from "../agent/index.js";
+import { alpha, VX } from "../tokens/index.js";
+const MICRO_LABEL_STYLE = {
+  fontFamily: "var(--basalt-font-mono)",
+  fontSize: VX.text.micro,
+  fontWeight: 500,
+  letterSpacing: "0.06em",
+  textTransform: "uppercase",
+  color: VX.faint
+};
+const RAIL_STYLE = {
+  borderLeft: `2px solid ${VX.divider}`,
+  paddingLeft: "var(--vx-space-agent-rail-inset-x)"
+};
+const CODE_BLOCK_STYLE = {
+  margin: 0,
+  marginTop: "var(--vx-space-agent-part-gap-top)",
+  fontFamily: "var(--basalt-font-mono)",
+  backgroundColor: alpha(VX.ink, 0.06),
+  borderRadius: "var(--vx-radius-card)",
+  padding: "var(--vx-space-agent-code-inset)",
+  whiteSpace: "pre-wrap",
+  overflowWrap: "anywhere"
+};
+function stateMeta(part) {
+  switch (part.state) {
+    case "input-streaming":
+      return { label: "streaming", dotToken: VX.status.neutral };
+    case "input-available":
+      return { label: "running", dotToken: VX.status.neutral };
+    case "approval-requested":
+      return { label: "needs approval", dotToken: VX.status.warn };
+    case "approval-responded":
+      return part.approval.approved ? { label: "approved", dotToken: VX.status.neutral } : { label: "declined", dotToken: VX.status.bad };
+    case "output-available":
+      return part.preliminary === true ? { label: "preliminary", dotToken: VX.status.warn } : { label: "done", dotToken: VX.status.good };
+    case "output-error":
+      return { label: "error", dotToken: VX.status.bad };
+    case "output-denied":
+      return { label: "denied", dotToken: VX.status.bad };
+    default: {
+      const exhaustive = part;
+      void exhaustive;
+      return { label: "unknown", dotToken: VX.status.neutral };
+    }
+  }
+}
+function formatDuration(ms) {
+  return ms >= 1e3 ? `${(ms / 1e3).toFixed(1)}s` : `${Math.round(ms)}ms`;
+}
+function ToolChip({
+  part,
+  defaultExpanded = false,
+  onApprove,
+  onDeny
+}) {
+  const [expanded, { toggle }] = useDisclosure(defaultExpanded);
+  const { label, dotToken } = stateMeta(part);
+  const settled = isToolCallSettled(part);
+  const input = "input" in part ? part.input : void 0;
+  const rawInput = part.state === "output-error" ? part.rawInput : void 0;
+  return /* @__PURE__ */ jsx(Box, { style: RAIL_STYLE, children: /* @__PURE__ */ jsxs(Stack, { gap: 4, children: [
+    /* @__PURE__ */ jsx(UnstyledButton, { onClick: toggle, children: /* @__PURE__ */ jsxs(Group, { gap: 6, align: "center", wrap: "nowrap", children: [
+      /* @__PURE__ */ jsx(
+        Box,
+        {
+          "aria-hidden": true,
+          style: {
+            width: 6,
+            height: 6,
+            flexShrink: 0,
+            borderRadius: "50%",
+            // theme-allow: a 6px state dot is a circle, not a surface corner — no radius token expresses it
+            backgroundColor: dotToken
+          }
+        }
+      ),
+      /* @__PURE__ */ jsx(Text, { style: MICRO_LABEL_STYLE, children: part.toolName }),
+      /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", children: label }),
+      part.durationMs !== void 0 && /* @__PURE__ */ jsx(
+        Text,
+        {
+          style: {
+            fontFamily: "var(--basalt-font-mono)",
+            fontSize: VX.text.micro,
+            color: VX.faint
+          },
+          children: formatDuration(part.durationMs)
+        }
+      ),
+      !settled && /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", children: "\u2026" })
+    ] }) }),
+    /* @__PURE__ */ jsx(Collapse, { expanded, children: /* @__PURE__ */ jsxs(Stack, { gap: 6, children: [
+      input !== void 0 && /* @__PURE__ */ jsx(Text, { component: "pre", size: "xs", style: CODE_BLOCK_STYLE, children: JSON.stringify(input, null, 2) }),
+      rawInput !== void 0 && /* @__PURE__ */ jsx(Text, { component: "pre", size: "xs", style: CODE_BLOCK_STYLE, children: JSON.stringify(rawInput, null, 2) }),
+      part.state === "output-available" && /* @__PURE__ */ jsx(Text, { component: "pre", size: "xs", style: CODE_BLOCK_STYLE, children: JSON.stringify(part.output, null, 2) }),
+      part.state === "output-error" && /* @__PURE__ */ jsx(Text, { size: "xs", style: { color: VX.status.bad }, children: part.errorText }),
+      part.state === "output-denied" && part.approval.reason !== void 0 && /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", children: part.approval.reason }),
+      part.state === "approval-requested" && (onApprove !== void 0 || onDeny !== void 0) && /* @__PURE__ */ jsxs(Group, { gap: 6, children: [
+        onApprove !== void 0 && /* @__PURE__ */ jsx(Button, { size: "compact-sm", onClick: () => onApprove(part.approval.id), children: "Approve" }),
+        onDeny !== void 0 && /* @__PURE__ */ jsx(
+          Button,
+          {
+            size: "compact-sm",
+            variant: "light",
+            color: "red",
+            onClick: () => onDeny(part.approval.id),
+            children: "Deny"
+          }
+        )
+      ] })
+    ] }) })
+  ] }) });
+}
+export {
+  ToolChip
+};

package/dist/cli/index.d.ts

@@ -126,6 +126,25 @@ export type BasaltConfig = {
      * { exemptRules: { 'inline-display': ['agent'] } } // inline-display never fires under src/agent/**
      */
     exemptRules?: Partial<Record<GuardKind, string[]>>;
+    /**
+     * Declares an intentional `ai` package major-version skew across workspace packages, exempting
+     * `doctor`'s `ai-major-parity` hard check. The value IS the reason — a bare `true` is rejected,
+     * because the whole point of this key is that the pairing is written down, not just switched off.
+     * A written declaration is the pin `basalt/ai-sdk-major`'s own comment notes is otherwise missing.
+     *
+     * Semantics: absent (or present but not a non-empty string) → the skew still hard-fails exactly as
+     * without this key. A non-empty string with a skew present → `doctor` passes, echoing both the
+     * skew and this reason. A non-empty string with NO skew present → `doctor` warns that the
+     * exemption is stale and can be deleted (an exemption nobody re-checks is how a real, later skew
+     * slips through unnoticed).
+     *
+     * @example
+     * // apps/api streams on ai@5; apps/dashboard parses on ai@7; a producer-side TransformStream
+     * // neutralizes the one enum value that differs between the two majors.
+     * { aiMajorSkewReason: 'apps/api pinned to ai@5, apps/dashboard on ai@7 — the skew is neutralized '
+     *   + 'by a producer-side TransformStream in apps/api/src/stream-transform.ts' }
+     */
+    aiMajorSkewReason?: string;
 };
 /**
  * Theme guard — thin FS walker over the headless `../guard` core. Reads BasaltConfig, builds a
@@ -324,6 +343,17 @@ type DoctorResult = {
  *
  * Hard failures (exit non-zero):
  *   1. .basalt/manifest.json exists (init was run).
+ *   6. `ai-major-parity`: every workspace package that declares the `ai` package agrees on its
+ *      major version. `basalt/ai-sdk-major` (the oxlint plugin rule) cannot catch this — it checks
+ *      a linted file's NEAREST package.json, so a lint run scoped to one workspace package only
+ *      ever sees that package's own `ai` major and is perfectly happy; the cross-package skew (one
+ *      package streaming on `ai@5`, another parsing it on `ai@7`) only a repo-wide manifest walk
+ *      can see. Skipped entirely when `cwd` has no `workspaces` field or none of its packages
+ *      declare `ai`. A detected skew is exempt-able via `basalt.aiMajorSkewReason` (a non-empty
+ *      reason string, not a bare `true`) in the consumer's package.json — an intentional
+ *      producer/consumer split neutralized by a transform is a locked decision, not a defect, and
+ *      the written reason IS the pin that a permanently-failing guard would otherwise lack. Missing
+ *      or invalid (empty/non-string) still hard-fails exactly as if the key were absent.
  *
  * Warnings (non-fatal):
  *   2. The installed node_modules/basalt-ui version matches the manifest's basaltVersion
@@ -335,6 +365,9 @@ type DoctorResult = {
  *      `bunx basalt-ui` npm fetch; best-effort, skipped if node_modules is absent).
  *   5. `basaltAppPlugin`'s (basalt-ui/vite) default icon filenames exist under public/ (only when
  *      a public/ dir exists at all — skipped otherwise).
+ *   7. A declared `basalt.aiMajorSkewReason` when the ai majors currently AGREE — the exemption is
+ *      stale and can be deleted; an exemption nobody revisits is how a real, later skew slips
+ *      through unnoticed.
  *
  * Returns the exit code: 0 = all good, 1 = one or more hard failures.
  */

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.js

@@ -783,7 +783,105 @@ function checkCoverage() {
   }
   return 1;
 }
+function subdirNames(base, options = {}) {
+  let entries;
+  try {
+    entries = readdirSync(base);
+  } catch {
+    return [];
+  }
+  return entries.filter((name) => {
+    if (name === "node_modules") return false;
+    if (options.skipDotDirs && name.startsWith(".")) return false;
+    try {
+      return statSync(resolve(base, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+function expandPatternSegments(baseDir, segments) {
+  if (segments.length === 0) return [baseDir];
+  const [head, ...rest] = segments;
+  if (head === "**") {
+    const matches = expandPatternSegments(baseDir, rest);
+    for (const name of subdirNames(baseDir, { skipDotDirs: true })) {
+      matches.push(...expandPatternSegments(resolve(baseDir, name), segments));
+    }
+    return matches;
+  }
+  const names = head === "*" ? subdirNames(baseDir, { skipDotDirs: true }) : subdirNames(baseDir).filter((n) => n === head);
+  return names.flatMap((name) => expandPatternSegments(resolve(baseDir, name), rest));
+}
+function expandWorkspaceGlobs(cwd, patterns) {
+  const expand = (pattern) => expandPatternSegments(
+    cwd,
+    pattern.split("/").filter((s) => s.length > 0)
+  );
+  const excluded = new Set(
+    patterns.filter((pattern) => pattern.startsWith("!")).flatMap((pattern) => expand(pattern.replace(/^!+/, "")))
+  );
+  const dirs = [];
+  for (const pattern of patterns) {
+    if (pattern.startsWith("!")) continue;
+    for (const abs of expand(pattern)) {
+      if (excluded.has(abs)) continue;
+      if (existsSync(resolve(abs, "package.json"))) dirs.push(abs);
+    }
+  }
+  return dirs;
+}
+function collectWorkspacePackages(cwd) {
+  const raw = readIfExists(resolve(cwd, "package.json"));
+  if (raw === null) return { packages: [], hasWorkspacesField: false };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { packages: [], hasWorkspacesField: false };
+  }
+  const patterns = isStringArray(parsed.workspaces) ? parsed.workspaces : parsed.workspaces !== null && typeof parsed.workspaces === "object" && isStringArray(parsed.workspaces.packages) ? parsed.workspaces.packages : null;
+  if (patterns === null) return { packages: [], hasWorkspacesField: false };
+  const rootName = parsed.name && parsed.name.length > 0 ? `${parsed.name} (root)` : "(root)";
+  const workspacePackages = expandWorkspaceGlobs(cwd, patterns).map((dir) => ({
+    name: readPackageName(dir),
+    dir
+  }));
+  return {
+    packages: [{ name: rootName, dir: cwd }, ...workspacePackages],
+    hasWorkspacesField: true
+  };
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function majorOf(range) {
+  if (typeof range !== "string") return null;
+  const match = range.match(/\d+/);
+  return match === null ? null : Number(match[0]);
+}
+function aiMajorAt(dir) {
+  const raw = readIfExists(resolve(dir, "package.json"));
+  if (raw === null) return null;
+  try {
+    const pkg = JSON.parse(raw);
+    return majorOf(
+      pkg.dependencies?.["ai"] ?? pkg.devDependencies?.["ai"] ?? pkg.peerDependencies?.["ai"]
+    );
+  } catch {
+    return null;
+  }
+}
+function resolveAiMajorSkewReason(cfg) {
+  const raw = cfg.aiMajorSkewReason;
+  if (raw === void 0) return { reason: null, presentButInvalid: false };
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return { reason: raw, presentButInvalid: false };
+  }
+  return { reason: null, presentButInvalid: true };
+}
 function doctor(cwd = process.cwd()) {
+  const cfg = readBasaltConfig(cwd);
   const result = { hardFailures: 0, warnings: 0 };
   const lines = [`
 basalt-ui doctor \u2014 ${cwd}
@@ -881,6 +979,39 @@ basalt-ui doctor \u2014 ${cwd}
       pass("public/ has all of basaltAppPlugin's default icon files");
     }
   }
+  const workspaceWalk = collectWorkspacePackages(cwd);
+  const aiMajors = workspaceWalk.packages.map((pkg) => ({ name: pkg.name, major: aiMajorAt(pkg.dir) })).filter((entry) => entry.major !== null);
+  const { reason: aiMajorSkewReason, presentButInvalid: aiMajorSkewReasonInvalid } = resolveAiMajorSkewReason(cfg);
+  if (aiMajors.length > 0) {
+    const distinctMajors = new Set(aiMajors.map((entry) => entry.major));
+    if (distinctMajors.size > 1) {
+      const summary = aiMajors.map((entry) => `${entry.name}@ai${entry.major}`).join(", ");
+      if (aiMajorSkewReason !== null) {
+        pass(
+          `ai package major version mismatch across workspace packages: ${summary} \u2014 exempted via basalt.aiMajorSkewReason: "${aiMajorSkewReason}"`
+        );
+      } else if (aiMajorSkewReasonInvalid) {
+        fail(
+          `ai package major version mismatch across workspace packages: ${summary} \u2014 basalt.aiMajorSkewReason is present but is not a non-empty string (a bare \`true\` is not accepted); the exemption must carry a written reason, e.g. \`aiMajorSkewReason: "apps/api on ai@5, apps/dashboard on ai@7, neutralized by a producer-side TransformStream"\`.`
+        );
+      } else {
+        fail(`ai package major version mismatch across workspace packages: ${summary}`);
+      }
+    } else {
+      const [major] = distinctMajors;
+      if (aiMajorSkewReason !== null) {
+        warn(
+          `basalt.aiMajorSkewReason ("${aiMajorSkewReason}") is declared but the ai package major already matches across all ${aiMajors.length} workspace package(s) declaring it (ai@${major}) \u2014 the exemption is no longer needed and can be deleted.`
+        );
+      } else {
+        pass(
+          `ai package major matches across ${aiMajors.length} workspace package(s) declaring it (ai@${major})`
+        );
+      }
+    }
+  } else if (workspaceWalk.hasWorkspacesField) {
+    pass("ai-major-parity: no workspace package declares the ai dependency \u2014 nothing to compare");
+  }
   lines.push("");
   if (result.hardFailures === 0 && result.warnings === 0) {
     lines.push("All checks passed.");

package/dist/guard/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE7E,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,CAAA;AAoP9D,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,WAoBlC,CAAA;AA0TD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;gCA0BL,WAAW;;;;;;;gCAcX,WAAW;;;;;gCAMX,WAAW;;;;;;;gCAaX,WAAW;;;;;;;gCAQX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCASX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCAaX,WAAW;;;;;;gCAMX,WAAW;;;;;;;gCAaX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCAUX,WAAW;;;;CAOmB,CAAA;AAUjD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,EAAE,CA2PtF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE7E,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,CAAA;AAoP9D,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,WAoBlC,CAAA;AAwTD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;gCA0BL,WAAW;;;;;;;gCAcX,WAAW;;;;;gCAMX,WAAW;;;;;;;gCAaX,WAAW;;;;;;;gCAQX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCASX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCAaX,WAAW;;;;;;gCAMX,WAAW;;;;;;;gCAaX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCAUX,WAAW;;;;CAOmB,CAAA;AAUjD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,EAAE,CA2PtF"}