basalt-ui 1.9.0 → 1.10.0

package/src/agent/use-agent-thread-runs.wedge.test.tsx

@@ -0,0 +1,299 @@
+/**
+ * F3 — the mount-reconcile / unmount-cleanup wedge in useAgentThreadRuns.
+ *
+ * The bug: the unmount-cleanup effect (`controllersRef.current.forEach(c => c.abort())`) aborted
+ * every in-flight controller but never CLEARED the map. The mount-reconcile effect treats a thread
+ * as "orphaned" (worth a resume attempt) only when `!controllersRef.current.has(thread.id)`. If
+ * this fiber's effects re-run WITHOUT the fiber itself unmounting — React 19 StrictMode's
+ * dev-only double-invoke, or a `<Activity>` boundary being hidden then shown again — the stale,
+ * now-aborted entry survives into the second reconcile pass, `orphaned` reads `false`, no new
+ * resume is attempted, and the one live consumer that WAS attempted already returned silently on
+ * its AbortError (`consumeAndFinalize`'s guard at the top of its try block). The thread is left in
+ * `'streaming'` forever with nothing left to resolve it.
+ *
+ * Both halves matter equally here:
+ *
+ *   (a) REFUTED — a genuine unmount + remount (a fresh component instance, not a re-run of THIS
+ *       fiber's effects) gets a brand-new `useRef` Map. There is nothing for the fix to protect
+ *       against here; the test exists so nobody "fixes" this non-bug later.
+ *   (b) CONFIRMED — React 19 StrictMode's dev-only double-invoke reuses the SAME fiber (and thus
+ *       the same ref) across a simulated unmount+remount within one commit.
+ *   (c) CONFIRMED — React 19.2's `<Activity>` does the SAME thing in PRODUCTION: hiding an
+ *       Activity boundary destroys the subtree's effects and re-creates them on show, while state,
+ *       DOM, and ref identity survive. This is the reachable-in-prod half of the wedge, not a
+ *       StrictMode-only curiosity — hence testing it directly against `<Activity>` from `react`
+ *       rather than only through Mantine's `Collapse`. At the `@mantine/core` 9.3.0 pinned in THIS
+ *       repo, `Collapse` has no `keepMounted` DEFAULT — with the prop unset it keeps `children`
+ *       permanently mounted (the `else` branch below), so a bare `<Collapse>` cannot wedge and a
+ *       default-Collapse-based test would not reproduce the bug. But a consumer writing
+ *       `<Collapse keepMounted>` on this SAME 9.3.0 does hit the `<Activity>` path — read
+ *       the installed `@mantine/core` 9.3.0 `Collapse.mjs` source directly: it imports
+ *       `Activity` from `react` and, when `keepMounted === true`, renders
+ *       `jsx(Activity, { mode: isExited ? 'hidden' : 'visible', … })` on the ordinary non-zero-
+ *       duration path (only the `duration === 0` fast path carries a `&& env !== 'test'` guard). So
+ *       the Activity hazard is live on THIS pinned version, not only on the 9.4.1 argo resolves —
+ *       testing `<Activity>` directly is still the right call because it is what a `keepMounted`
+ *       consumer actually gets here today, not because 9.3.0 is exempt.
+ *
+ * Verified manually while writing this file (reported alongside the test suite, not re-asserted
+ * here as a runtime check): reverting the one-line `controllersRef.current.clear()` fix makes (b)
+ * and (c) fail — the thread's status stays `'streaming'` instead of settling — while (a) passes
+ * either way, exactly as the "refutation" framing above expects.
+ *
+ * Both (b) and (c) observe `resume()` invoked TWICE post-fix (once for the pass that gets aborted,
+ * once for the pass that survives), not once — React's whole justification for double-invoking a
+ * mount effect with a side effect (a network call here) is to surface exactly this
+ * non-idempotence; a spec that anticipated "resume() attempted exactly once" for this scenario
+ * does not match observed React 19.2.7 behavior. What's invariant, and what these tests assert, is
+ * that the thread SETTLES (leaves `'streaming'`) rather than wedging — the resume() call count is
+ * asserted too, but as an observed constant with the doubling explained, not as evidence of a
+ * single attempt.
+ */
+import { describe, expect, test } from 'bun:test'
+import { Activity, StrictMode, useState } from 'react'
+import { act, render, renderHook, waitFor } from '@testing-library/react'
+import { useAgentThreadRuns } from './use-agent-thread-runs'
+import type { AgentThread, ThreadsStore } from './thread'
+import type { AgentTransport } from './transport'
+import type { AgentPart } from './parts'
+import type { ChatMessage } from './history'
+import type { AgentOutcome } from './outcome'
+
+// ── test-only ThreadsStore double ────────────────────────────────────────────
+//
+// A plain mutable object satisfying the ThreadsStore contract — no React state, no
+// localStorage/useSyncExternalStore. useAgentThreadRuns only ever reads `store.threads` and calls
+// its action methods synchronously (via `storeRef.current`), so a hand-rolled mutable double gives
+// the test full, synchronous, non-persisted control over what a "reload mid-stream" looked like —
+// exactly what these mount-reconcile tests need to seed.
+function createTestThreadsStore(initial: AgentThread<AgentPart>[] = []): ThreadsStore<AgentPart> {
+  let threads = initial
+  let activeId: string | null = null
+  return {
+    get threads() {
+      return threads
+    },
+    get activeId() {
+      return activeId
+    },
+    select(id) {
+      activeId = id
+    },
+    create(opts) {
+      const id = crypto.randomUUID()
+      const now = Date.now()
+      const thread: AgentThread<AgentPart> = {
+        id,
+        messages: [],
+        outcome: null,
+        status: 'pending',
+        read: false,
+        createdAt: now,
+        updatedAt: now,
+        ...(opts?.meta !== undefined ? { meta: opts.meta } : {}),
+      }
+      threads = [thread, ...threads]
+      return id
+    },
+    appendMessage(id, message) {
+      threads = threads.map((thread) =>
+        thread.id === id
+          ? { ...thread, messages: [...thread.messages, message], updatedAt: Date.now() }
+          : thread,
+      )
+    },
+    setOutcome(id, outcome) {
+      threads = threads.map((thread) =>
+        thread.id === id ? { ...thread, outcome, updatedAt: Date.now() } : thread,
+      )
+    },
+    setStatus(id, status) {
+      threads = threads.map((thread) =>
+        thread.id === id ? { ...thread, status, updatedAt: Date.now() } : thread,
+      )
+    },
+    setResumeToken(id, token) {
+      threads = threads.map((thread) => {
+        if (thread.id !== id) return thread
+        const { resumeToken: _resumeToken, ...rest } = thread
+        return {
+          ...rest,
+          ...(token !== undefined ? { resumeToken: token } : {}),
+          updatedAt: Date.now(),
+        }
+      })
+    },
+    markRead(id) {
+      threads = threads.map((thread) => (thread.id === id ? { ...thread, read: true } : thread))
+    },
+    remove(id) {
+      threads = threads.filter((thread) => thread.id !== id)
+      if (activeId === id) activeId = null
+    },
+    clear() {
+      threads = []
+      activeId = null
+    },
+  }
+}
+
+function makeThread(overrides: Partial<AgentThread<AgentPart>> = {}): AgentThread<AgentPart> {
+  const now = Date.now()
+  return {
+    id: crypto.randomUUID(),
+    messages: [],
+    outcome: null,
+    status: 'pending',
+    read: false,
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  }
+}
+
+function deferred<T>(): { promise: Promise<T>; resolve: (value: T) => void } {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((r) => {
+    resolve = r
+  })
+  return { promise, resolve }
+}
+
+const resolveOutcome = (): AgentOutcome => ({ title: 'title', summary: 'summary', status: 'done' })
+
+describe('useAgentThreadRuns — F3 mount-reconcile / unmount-cleanup wedge', () => {
+  test('(a) REFUTED: a genuine unmount + remount gets a fresh controllers map — resolves to interrupted, never re-enters streaming', () => {
+    const store = createTestThreadsStore()
+    const threadId = store.create()
+
+    // No `resume` on this transport: on remount, the orphaned thread must fall straight to
+    // 'interrupted' with no async wait involved.
+    const transport: AgentTransport<AgentPart, string> = {
+      // oxlint-disable-next-line require-yield -- hangs until aborted; never has anything to yield
+      async *stream(_input, signal) {
+        await new Promise((resolve) => {
+          signal?.addEventListener('abort', () => resolve(undefined))
+        })
+      },
+    }
+
+    const { result, unmount } = renderHook(() =>
+      useAgentThreadRuns({ transport, store, resolveOutcome }),
+    )
+
+    act(() => {
+      result.current.start(threadId, 'hello')
+    })
+    expect(store.threads.find((thread) => thread.id === threadId)?.status).toBe('streaming')
+
+    unmount()
+
+    // A brand-new component instance against the SAME store object — a fresh fiber, fresh
+    // `useRef` Map. This must hold both before AND after the F3 fix.
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    expect(store.threads.find((thread) => thread.id === threadId)?.status).toBe('interrupted')
+  })
+
+  test('(b) CONFIRMED: React 19 StrictMode double-invoke resumes the orphaned thread instead of wedging it in streaming', async () => {
+    const userMessage: ChatMessage<AgentPart> = {
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text: 'hello' }],
+      createdAt: Date.now(),
+    }
+    const thread = makeThread({
+      status: 'streaming',
+      resumeToken: 'resume-token-1',
+      messages: [userMessage],
+    })
+    const store = createTestThreadsStore([thread])
+
+    let resumeCalls = 0
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+      async *resume() {
+        resumeCalls++
+        yield { type: 'text', text: 'resumed' }
+      },
+    }
+
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }), {
+      wrapper: StrictMode,
+    })
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === thread.id)?.status).toBe('done')
+    })
+    // Observed constant for this scenario (see file doc): the aborted first pass plus the
+    // surviving second pass, not "exactly once".
+    expect(resumeCalls).toBe(2)
+  })
+
+  test('(c) CONFIRMED: an <Activity> hide/show cycle resumes the orphaned thread instead of wedging it in streaming', async () => {
+    const userMessage: ChatMessage<AgentPart> = {
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text: 'hello' }],
+      createdAt: Date.now(),
+    }
+    const thread = makeThread({
+      status: 'streaming',
+      resumeToken: 'resume-token-2',
+      messages: [userMessage],
+    })
+    const store = createTestThreadsStore([thread])
+
+    // Gates the first resume() attempt so the hide happens strictly before it settles — an
+    // explicit happens-before, not a scheduler coincidence a `setTimeout(…, 0)` would only
+    // usually win.
+    const gate = deferred<void>()
+
+    let resumeCalls = 0
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+      async *resume() {
+        resumeCalls++
+        await gate.promise
+        yield { type: 'text', text: 'resumed' }
+      },
+    }
+
+    let externalSetMode: ((mode: 'visible' | 'hidden') => void) | undefined
+
+    function Probe(): null {
+      useAgentThreadRuns({ transport, store, resolveOutcome })
+      return null
+    }
+
+    function Harness(): JSX.Element {
+      const [mode, setMode] = useState<'visible' | 'hidden'>('visible')
+      externalSetMode = setMode
+      return (
+        <Activity mode={mode}>
+          <Probe />
+        </Activity>
+      )
+    }
+
+    await act(async () => {
+      render(<Harness />)
+    })
+
+    // First resume attempt is in flight (its gate hasn't been released yet) — hide now to abort
+    // it via the F3-fixed cleanup effect. `gate.resolve()` only runs after this completes, so the
+    // hide is guaranteed to land before the first attempt could ever settle.
+    await act(async () => {
+      externalSetMode?.('hidden')
+    })
+    gate.resolve()
+    await act(async () => {
+      externalSetMode?.('visible')
+    })
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === thread.id)?.status).toBe('done')
+    })
+    expect(resumeCalls).toBe(2)
+  })
+})

package/src/agent-chat/index.ts

@@ -2,11 +2,12 @@
  * Mantine-styled thread-chat components over the headless `basalt-ui/agent` layer, capped by the
  * flagship `ThreadWorkspace` composite.
  *
- * This module is Mantine-coupled by design and lives under the root entry (unlike `basalt-ui/agent`,
- * which stays headless so it can be styled by any consumer).
+ * This module is Mantine-coupled by design and ships its own `basalt-ui/agent-chat` subpath
+ * (also re-exported from the root entry, unchanged for existing consumers) — unlike
+ * `basalt-ui/agent`, which stays headless so it can be styled by any consumer.
  *
  * @example
- * import { ThreadWorkspace } from 'basalt-ui'
+ * import { ThreadWorkspace } from 'basalt-ui/agent-chat'
  * import { createThreadsStore, edenTransport, heuristicOutcome } from 'basalt-ui/agent'
  */
 

package/src/charts/primitives/ChartFrame.test.tsx

@@ -4,11 +4,14 @@
  * shape back on screen exactly where `ChartPending` is supposed to reserve a static, contentless
  * placeholder (see `ChartPending`'s JSDoc for the three-state "nothing to draw" rationale).
  *
- * No jsdom is configured in this repo (see `theme/use-basalt-spacing.test.tsx`'s doc) —
- * `renderToStaticMarkup` is enough here: `ChartFrame`/`ChartPending` live in `src/charts/**`, which
- * is Mantine-free, so no `MantineProvider` wrapper is needed either. `useChartSize` never measures
- * under SSR (no `ResizeObserver`), so the plot rect falls back to `minWidth` × the resolved fixed
- * height — non-zero, which is what lets `children`/`ChartPending` render at all in this harness.
+ * A DOM harness now exists (`tests/setup/dom.ts`, preloaded via the root `bunfig.toml`; see
+ * `theme/use-basalt-spacing.test.tsx`'s doc) — `renderToStaticMarkup` is used deliberately here
+ * instead: `ChartFrame`/`ChartPending` live in `src/charts/**`, which is Mantine-free, so no
+ * `MantineProvider` wrapper is needed either. `useChartSize` never measures under SSR (no
+ * `ResizeObserver`), so the plot rect falls back to `minWidth` × the resolved fixed height —
+ * non-zero, which is what lets `children`/`ChartPending` render at all in this harness. Converting
+ * to the DOM harness would only be worth it if a future assertion here needed a real measured size
+ * (a live `ResizeObserver` reading) rather than this SSR fallback rect.
  */
 import { describe, expect, test } from 'bun:test'
 import { renderToStaticMarkup } from 'react-dom/server'

package/src/cli/index.ts

@@ -165,6 +165,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
 }
 
 const DEFAULT_ROOT = 'src'
@@ -1560,6 +1579,202 @@ type DoctorResult = {
   warnings: number
 }
 
+type WorkspacePackage = { readonly name: string; readonly dir: string }
+
+/** {@link collectWorkspacePackages}'s return: the walked packages plus whether a `workspaces`
+ * field was present at all (distinguishes "nothing to compare" from "not a workspace root"). */
+type WorkspaceWalk = {
+  readonly packages: readonly WorkspacePackage[]
+  readonly hasWorkspacesField: boolean
+}
+
+/**
+ * Every subdirectory of `base` (name only), or `[]` if `base` doesn't exist / isn't a directory.
+ * `node_modules` is always excluded — a wildcard workspaces pattern must never descend into a
+ * dependency tree. `skipDotDirs` additionally excludes dot-directories; it is only set by the
+ * `*`/`**` wildcard descent in {@link expandPatternSegments}, never for an explicitly named
+ * literal segment, so a pattern like `.internal/*` still resolves.
+ */
+function subdirNames(base: string, options: { skipDotDirs?: boolean } = {}): string[] {
+  let entries: string[]
+  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
+    }
+  })
+}
+
+/**
+ * Expands one glob PATTERN's segments against the filesystem, starting from `baseDir`. Supports
+ * three segment kinds: a literal name, a single `*` wildcard (any one directory), and a `**`
+ * wildcard (zero or more directory levels, i.e. arbitrary depth) — covering a trailing single
+ * wildcard, an interior wildcard between literal segments, and a trailing double-wildcard alike,
+ * not just one trailing single-wildcard segment.
+ */
+function expandPatternSegments(baseDir: string, segments: readonly string[]): string[] {
+  if (segments.length === 0) return [baseDir]
+  const [head, ...rest] = segments
+
+  if (head === '**') {
+    // Zero levels: `**` consumes nothing and the rest of the pattern matches right here.
+    const matches = expandPatternSegments(baseDir, rest)
+    // One-or-more levels: descend into every subdirectory, `**` still active.
+    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))
+}
+
+/**
+ * Expands a root `package.json`'s `workspaces` patterns into concrete package directories.
+ * Supports literal segments, a single-wildcard segment, and a double-wildcard segment, both
+ * interior and trailing (e.g. `packages` followed by a double wildcard, or an interior single
+ * wildcard between two literal segments) — not just one trailing single-wildcard segment. A
+ * candidate directory that has no `package.json` of its own is skipped, not reported — an empty
+ * scaffold directory is not a workspace package. Also honours npm/bun/yarn `!`-prefixed exclusion
+ * entries (e.g. `["packages/*", "!packages/legacy"]`) — both the included and excluded patterns
+ * are expanded through the same machinery, then the excluded set is subtracted.
+ */
+function expandWorkspaceGlobs(cwd: string, patterns: readonly string[]): string[] {
+  const expand = (pattern: string): string[] =>
+    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: string[] = []
+  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
+}
+
+/**
+ * Every workspace package declared by `cwd`'s root `package.json` (npm/bun/yarn `workspaces`
+ * field, array or `{ packages: [...] }` object form), named + directory-resolved — PLUS the root
+ * manifest itself, labelled `"{name} (root)"`. The root is walked because it commonly carries a
+ * hoisted `ai` dev dependency that can itself skew against a workspace package's own major — that
+ * is the producer/consumer shape the whole check exists to catch, and it is invisible if only the
+ * expanded workspace dirs are inspected. `hasWorkspacesField` is `false` (and `packages` empty)
+ * when `cwd` has no `package.json`, no `workspaces` field, or the field is a shape this doesn't
+ * recognize — a repo-wide walk is a bonus check, not something that should ever throw doctor over
+ * an unrecognized `workspaces` shape.
+ */
+function collectWorkspacePackages(cwd: string): WorkspaceWalk {
+  const raw = readIfExists(resolve(cwd, 'package.json'))
+  if (raw === null) return { packages: [], hasWorkspacesField: false }
+
+  let parsed: { workspaces?: unknown; name?: string }
+  try {
+    parsed = JSON.parse(raw) as { workspaces?: unknown; name?: string }
+  } catch {
+    return { packages: [], hasWorkspacesField: false }
+  }
+
+  const patterns = isStringArray(parsed.workspaces)
+    ? parsed.workspaces
+    : parsed.workspaces !== null &&
+        typeof parsed.workspaces === 'object' &&
+        isStringArray((parsed.workspaces as { packages?: unknown }).packages)
+      ? (parsed.workspaces as { packages: string[] }).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,
+  }
+}
+
+/** Narrows to a string array — shared by `collectWorkspacePackages`'s two `workspaces` shapes. */
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+}
+
+/**
+ * First run of digits in a semver range string (`^7.0.15` → `7`), or null if there is none.
+ *
+ * Duplicated verbatim in `configs/oxlint-plugin.js` — that file must stay import-free from this
+ * package (it loads via `jsPlugins` out of a consumer's node_modules, before this package's own
+ * code is necessarily resolvable), so the duplication is structural, not an oversight. Keep both
+ * copies in sync by hand; a future parsing fix (pre-release suffixes, say) must land in both.
+ */
+function majorOf(range: string | undefined): number | null {
+  if (typeof range !== 'string') return null
+  const match = range.match(/\d+/)
+  return match === null ? null : Number(match[0])
+}
+
+/** The `ai` package's declared major at `dir`'s own `package.json`, or null if undeclared/unreadable. */
+function aiMajorAt(dir: string): number | null {
+  const raw = readIfExists(resolve(dir, 'package.json'))
+  if (raw === null) return null
+  try {
+    const pkg = JSON.parse(raw) as {
+      dependencies?: Record<string, string>
+      devDependencies?: Record<string, string>
+      peerDependencies?: Record<string, string>
+    }
+    return majorOf(
+      pkg.dependencies?.['ai'] ?? pkg.devDependencies?.['ai'] ?? pkg.peerDependencies?.['ai'],
+    )
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Splits `basalt.aiMajorSkewReason` into a validated reason (or null) plus whether the key was
+ * present at all but failed validation. A present-but-invalid value (anything other than a
+ * non-empty string — including a bare `true`) is treated as absent for the pass/fail decision, same
+ * as a missing key, but doctor's failure message still calls out that the key exists and is
+ * malformed rather than silently falling back to the plain "no exemption" message — a forgotten key
+ * and a broken one are different mistakes and deserve different guidance.
+ */
+function resolveAiMajorSkewReason(cfg: BasaltConfig): {
+  reason: string | null
+  presentButInvalid: boolean
+} {
+  const raw = cfg.aiMajorSkewReason
+  if (raw === undefined) return { reason: null, presentButInvalid: false }
+  if (typeof raw === 'string' && raw.trim().length > 0) {
+    return { reason: raw, presentButInvalid: false }
+  }
+  return { reason: null, presentButInvalid: true }
+}
+
 /**
  * Check a consumer repo's basalt integration and print a pass/warn report.
  *
@@ -1570,6 +1785,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
@@ -1581,10 +1807,14 @@ 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.
  */
 export function doctor(cwd: string = process.cwd()): number {
+  const cfg = readBasaltConfig(cwd)
   const result: DoctorResult = { hardFailures: 0, warnings: 0 }
   const lines: string[] = [`\nbasalt-ui doctor — ${cwd}\n`]
 
@@ -1728,6 +1958,61 @@ export function doctor(cwd: string = process.cwd()): number {
     }
   }
 
+  // ── Hard check 6: ai package major version parity across workspace packages ─
+  // basalt/ai-sdk-major (the lint rule) is per-file against the 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 real defect is CROSS-package (argo defect 1: apps/api on ai@5 producing a
+  // stream apps/dashboard's ai@7 client can't parse) and only a repo-wide manifest walk sees it —
+  // this is that walk. Hard failure, not a warning: a skewed pair throws at runtime, it doesn't
+  // just look different. `basalt.aiMajorSkewReason` exempts an INTENTIONAL skew (e.g. a
+  // producer-side TransformStream neutralizing the divergent enum value) — see the BasaltConfig
+  // JSDoc for its exact semantics; a stale declaration (skew resolved, reason still present) warns
+  // instead of passing silently.
+  const workspaceWalk = collectWorkspacePackages(cwd)
+  const aiMajors = workspaceWalk.packages
+    .map((pkg) => ({ name: pkg.name, major: aiMajorAt(pkg.dir) }))
+    .filter((entry): entry is { name: string; major: number } => 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} — exempted via ` +
+            `basalt.aiMajorSkewReason: "${aiMajorSkewReason}"`,
+        )
+      } else if (aiMajorSkewReasonInvalid) {
+        fail(
+          `ai package major version mismatch across workspace packages: ${summary} — ` +
+            '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}) — 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) {
+    // A hard check that can silently not run is worse than one that is absent — say so.
+    pass('ai-major-parity: no workspace package declares the ai dependency — nothing to compare')
+  }
+
   // ── Report ──────────────────────────────────────────────────────────────────
   lines.push('')
   if (result.hardFailures === 0 && result.warnings === 0) {

package/src/dashboard/stat-card.test.tsx

@@ -13,9 +13,11 @@
  *     leaving the prop off, so the absence case asserts no rail and no verdict text at all — which a
  *     future `tone = tone ?? 'good'` style default would immediately fail.
  *
- * No jsdom is configured in this repo (see `theme/use-basalt-spacing.test.tsx`'s doc) —
- * `renderToStaticMarkup` inside a real `MantineProvider` is enough here, since the rail is an inline
- * style on server-rendered markup.
+ * A DOM harness now exists (`tests/setup/dom.ts`, preloaded via the root `bunfig.toml`; see
+ * `theme/use-basalt-spacing.test.tsx`'s doc) — `renderToStaticMarkup` inside a real `MantineProvider`
+ * is used deliberately here instead, since the rail is an inline style on server-rendered markup.
+ * Converting to the DOM harness would only be worth it if a future assertion here needed live DOM
+ * behavior (e.g. computed styles, focus/hover interaction) rather than the static markup string.
  */
 import { MantineProvider } from '@mantine/core'
 import { describe, expect, test } from 'bun:test'