basalt-ui 1.9.0 → 1.10.0

package/configs/oxlint-plugin.test.ts

@@ -8,7 +8,7 @@
  * binary and returns the parsed set of `basalt/<rule>` diagnostics it printed.
  */
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, resolve } from 'node:path'
 
@@ -31,6 +31,9 @@ beforeEach(() => {
         'basalt/visx-boundary': 'error',
         'basalt/visx-tooltip': 'error',
         'basalt/token-layer-boundary': 'error',
+        'basalt/agent-resume-guard': 'error',
+        'basalt/agent-no-raw-usechat': 'error',
+        'basalt/ai-sdk-major': 'error',
       },
     }),
   )
@@ -232,3 +235,215 @@ describe('rule independence', () => {
     expect(rules).toContain('visx-tooltip')
   })
 })
+
+// ── agent-resume-guard ───────────────────────────────────────────────────────
+// The two agent rules honour a SEPARATE escape token, `basalt-agent-allow`, not `theme-allow` — a
+// color exemption must never be able to switch off a streaming guard. The `theme-allow` fixture
+// below proves the wrong token does not suppress the finding.
+
+describe('basalt/agent-resume-guard', () => {
+  it('flags useChat({ resume: true })', () => {
+    const { code, rules } = run(`const c = useChat({ id, resume: true })\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-resume-guard')
+  })
+
+  it('does NOT flag useChat({ resume: false })', () => {
+    const { code, rules } = run(`const c = useChat({ id, resume: false })\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-resume-guard')
+  })
+
+  it('does NOT flag a bare useChat({ id }) with no resume key', () => {
+    const { code, rules } = run(`const c = useChat({ id })\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-resume-guard')
+  })
+
+  it('flags chat.resumeStream() called from an effect', () => {
+    const { code, rules } = run(`useEffect(() => { chat.resumeStream() }, [])\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-resume-guard')
+  })
+
+  it('does NOT flag chat.resumeStream() marked basalt-agent-allow', () => {
+    const { code, rules } = run(`// basalt-agent-allow\nchat.resumeStream()\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-resume-guard')
+  })
+
+  it('STILL flags chat.resumeStream() marked only theme-allow (wrong escape token)', () => {
+    const { code, rules } = run(`// theme-allow\nchat.resumeStream()\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-resume-guard')
+  })
+
+  it('does NOT flag an unrelated call like runs.start(id, text)', () => {
+    const { code, rules } = run(`runs.start(id, text)\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-resume-guard')
+  })
+})
+
+// ── agent-no-raw-usechat ─────────────────────────────────────────────────────
+
+describe('basalt/agent-no-raw-usechat', () => {
+  it('flags importing useChat from @ai-sdk/react', () => {
+    const { code, rules } = run(`import { useChat } from '@ai-sdk/react'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-no-raw-usechat')
+  })
+
+  it('flags importing useCompletion from @ai-sdk/react', () => {
+    const { code, rules } = run(`import { useCompletion } from '@ai-sdk/react'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-no-raw-usechat')
+  })
+
+  it('does NOT flag a type-only import of UIMessage from the same module', () => {
+    const { code, rules } = run(`import type { UIMessage } from '@ai-sdk/react'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-no-raw-usechat')
+  })
+
+  it('does NOT flag an unrelated import from ai', () => {
+    const { code, rules } = run(`import { DefaultChatTransport } from 'ai'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-no-raw-usechat')
+  })
+
+  it('does NOT flag useChat imported from a local module', () => {
+    const { code, rules } = run(`import { useChat } from './my-hooks'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-no-raw-usechat')
+  })
+
+  // The matcher covers TWO source specifiers (RAW_USE_CHAT_SOURCES: '@ai-sdk/react' AND
+  // 'ai/react') — every fixture above only exercises '@ai-sdk/react'; this pins the other half.
+  it("flags importing useChat from 'ai/react' (the other matched source)", () => {
+    const { code, rules } = run(`import { useChat } from 'ai/react'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-no-raw-usechat')
+  })
+
+  it('does NOT flag an import marked basalt-agent-allow', () => {
+    const { code, rules } = run(
+      `// basalt-agent-allow\nimport { useChat } from '@ai-sdk/react'\n`,
+      'lib.ts',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-no-raw-usechat')
+  })
+
+  it('STILL flags an import marked only theme-allow (wrong escape token)', () => {
+    const { code, rules } = run(
+      `// theme-allow\nimport { useChat } from '@ai-sdk/react'\n`,
+      'lib.ts',
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-no-raw-usechat')
+  })
+})
+
+// ── ai-sdk-major ─────────────────────────────────────────────────────────────
+// The lint rule compares the LINTED FILE's nearest package.json against basalt-ui's own declared
+// `ai` peer major (read from packages/basalt-ui/package.json — the real file, since the plugin
+// resolves it relative to its own module location regardless of where it's invoked from). basalt-ui
+// declares "ai": "^7.0.15" (major 7) in both devDependencies and peerDependencies.
+
+describe('basalt/ai-sdk-major', () => {
+  it("flags when the nearest package.json declares a different ai major (5 vs basalt's 7)", () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    const { code, rules } = run(`import { streamText } from 'ai'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('ai-sdk-major')
+  })
+
+  it('does NOT flag when the nearest package.json declares the same major (^7.0.18)', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '^7.0.18' } }))
+    const { code, rules } = run(`import { streamText } from 'ai'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  it('does NOT flag when there is no ai in the nearest package.json', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: {} }))
+    const { code, rules } = run(`import { streamText } from 'ai'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  it('does NOT flag an unrelated import even with a skewed nearest package.json', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    const { code, rules } = run(`import { useState } from 'react'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  // The matcher covers TWO forms (source === 'ai' OR source.startsWith('@ai-sdk/')) — every
+  // fixture above only exercises the bare 'ai' specifier; this pins the scoped-package half.
+  it("flags a scoped '@ai-sdk/*' import when the nearest package.json declares a different ai major", () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    const { code, rules } = run(`import { openai } from '@ai-sdk/openai'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('ai-sdk-major')
+  })
+
+  it("does NOT flag a scoped '@ai-sdk/*' import when the nearest package.json declares the same major", () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '^7.0.18' } }))
+    const { code, rules } = run(`import { openai } from '@ai-sdk/openai'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  // Unlike the other rules in this file, ai-sdk-major honours `basalt-agent-allow` — the SAME
+  // token as its two agent-chat siblings above — not `theme-allow`. A skewed producer/consumer
+  // import that is genuinely intentional (see doctor's `aiMajorSkewReason`) can mark the line.
+  it('does NOT flag an import marked basalt-agent-allow, even with a skewed nearest package.json', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    const { code, rules } = run(
+      `// basalt-agent-allow\nimport { streamText } from 'ai'\n`,
+      'lib.ts',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  it('STILL flags an import marked only theme-allow (wrong escape token)', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    const { code, rules } = run(`// theme-allow\nimport { streamText } from 'ai'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('ai-sdk-major')
+  })
+})
+
+// ── raw-scroll-container — promotion (off → warn shipped) ────────────────────
+
+describe('basalt/raw-scroll-container promotion', () => {
+  it('ships "warn" (not "off") in the consumer preset', () => {
+    const shipped = JSON.parse(
+      readFileSync(resolve(import.meta.dirname, 'oxlint.json'), 'utf8'),
+    ) as { rules: Record<string, unknown> }
+    expect(shipped.rules['basalt/raw-scroll-container']).toBe('warn')
+  })
+
+  it('stays "warn" repo-local', () => {
+    const repoLocal = JSON.parse(
+      readFileSync(resolve(import.meta.dirname, '..', '..', '..', '.oxlintrc.json'), 'utf8'),
+    ) as { rules: Record<string, unknown> }
+    expect(repoLocal.rules['basalt/raw-scroll-container']).toBe('warn')
+  })
+
+  it('still flags a raw overflow:auto style property at the shipped level', () => {
+    writeFileSync(
+      resolve(dir, '.oxlintrc.json'),
+      JSON.stringify({
+        plugins: [],
+        jsPlugins: [PLUGIN_PATH],
+        rules: { 'basalt/raw-scroll-container': 'warn' },
+      }),
+    )
+    const { rules } = run(`const s = { overflowY: 'auto' }\n`, 'lib.ts')
+    expect(rules).toContain('raw-scroll-container')
+  })
+})

package/configs/oxlint.json

@@ -20,9 +20,12 @@
     "basalt/raw-size-literal": "warn",
     "basalt/card-inset": "error",
     "basalt/chart-in-raw-surface": "error",
-    "basalt/raw-scroll-container": "off",
+    "basalt/raw-scroll-container": "warn",
     "basalt/visx-boundary": "error",
-    "basalt/visx-tooltip": "error"
+    "basalt/visx-tooltip": "error",
+    "basalt/agent-resume-guard": "warn",
+    "basalt/agent-no-raw-usechat": "warn",
+    "basalt/ai-sdk-major": "warn"
   },
   "overrides": [
     {

package/dist/agent/use-agent-thread-runs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-agent-thread-runs.d.ts","sourceRoot":"","sources":["../../src/agent/use-agent-thread-runs.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,WAAW,CAAA;AAE9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,KAAK,EAA6B,YAAY,EAAE,MAAM,UAAU,CAAA;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAIjD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,SAAS,IAAI;IAC9C,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,CAAA;CACxB,CAAA;AAID,MAAM,MAAM,sBAAsB,CAAC,KAAK,GAAG,SAAS,IAAI;IACtD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EACd,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,GAC7B,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAA;IACzD,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,CAAA;IACnC,uFAAuF;IACvF,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC,KAAK,CAAC,CAAA;IAC/C;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,EAAE,CAAA;CAClD,CAAA;AAID,MAAM,MAAM,wBAAwB,CAAC,KAAK,GAAG,SAAS,IAAI;IACxD,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAA;IACzD,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACzD;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAC7B,CAAA;AA0ID;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAG,SAAS,EAAE,EACpD,SAAS,EACT,KAAK,EACL,cAAc,EACd,WAAW,GACZ,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAAG,wBAAwB,CAAC,KAAK,CAAC,CA6KjE"}
+{"version":3,"file":"use-agent-thread-runs.d.ts","sourceRoot":"","sources":["../../src/agent/use-agent-thread-runs.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,WAAW,CAAA;AAE9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,KAAK,EAA6B,YAAY,EAAE,MAAM,UAAU,CAAA;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAIjD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,SAAS,IAAI;IAC9C,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,CAAA;CACxB,CAAA;AAID,MAAM,MAAM,sBAAsB,CAAC,KAAK,GAAG,SAAS,IAAI;IACtD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EACd,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,GAC7B,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAA;IACzD,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,CAAA;IACnC,uFAAuF;IACvF,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC,KAAK,CAAC,CAAA;IAC/C;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,EAAE,CAAA;CAClD,CAAA;AAID,MAAM,MAAM,wBAAwB,CAAC,KAAK,GAAG,SAAS,IAAI;IACxD,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAA;IACzD,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACzD;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAC7B,CAAA;AA0ID;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAG,SAAS,EAAE,EACpD,SAAS,EACT,KAAK,EACL,cAAc,EACd,WAAW,GACZ,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAmLjE"}

package/dist/agent/use-agent-thread-runs.js

@@ -117,6 +117,7 @@ function useAgentThreadRuns({
   useEffect(
     () => () => {
       controllersRef.current.forEach((controller) => controller.abort());
+      controllersRef.current.clear();
     },
     []
   );

package/dist/agent-chat/index.d.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'
  */
 export { ThreadWorkspace } from './thread-workspace.js';

package/dist/agent-chat/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent-chat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAG9D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAGpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAGnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAGnE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG/C,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxE,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent-chat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAG9D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAGpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAGnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAGnE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG/C,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxE,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA"}

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/surfaces.d.ts

@@ -291,6 +291,16 @@ export declare const SURFACES: {
         };
         readonly forbiddenImports: readonly [ForbiddenImport, ForbiddenImport, ForbiddenImport];
     };
+    readonly './agent-chat': {
+        readonly kind: "doctrine";
+        readonly layer: "mantine-coupled";
+        readonly rule: "agent";
+        readonly skill: readonly ["basalt-app"];
+        readonly guardKinds: readonly [];
+        readonly description: "Mantine-styled thread-chat components over basalt-ui/agent: ThreadWorkspace, ThreadFeed, ThreadOutcomeCard, ThreadDetailPanel, Composer, ThreadTranscript, threadPartRenderers (Mantine-coupled). remend and motion are required, not optional — ThreadTranscript imports content/markdown.tsx (remend eagerly), and ThreadFeed/ThreadDetailPanel import motion/react eagerly, so this subpath fails to resolve without both installed even though peerDependenciesMeta marks them optional (npm has no per-subpath optionality).";
+        readonly optionalPeers: readonly ["ai", "motion", "remend", "use-stick-to-bottom", "react-markdown", "remark-gfm", "shiki", "@shikijs/langs", "@shikijs/themes", "beautiful-mermaid"];
+        readonly forbiddenImports: readonly [];
+    };
     readonly './content': {
         readonly kind: "doctrine";
         readonly layer: "mantine-coupled";

package/dist/surfaces.d.ts.map

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

package/dist/surfaces.js

@@ -197,6 +197,27 @@ const SURFACES = {
     // @visx/* ban dropped — `basalt/visx-boundary` now bans it universally outside charts.
     forbiddenImports: [...MANTINE_BANS]
   },
+  "./agent-chat": {
+    kind: "doctrine",
+    layer: "mantine-coupled",
+    rule: "agent",
+    skill: ["basalt-app"],
+    guardKinds: [],
+    description: "Mantine-styled thread-chat components over basalt-ui/agent: ThreadWorkspace, ThreadFeed, ThreadOutcomeCard, ThreadDetailPanel, Composer, ThreadTranscript, threadPartRenderers (Mantine-coupled). remend and motion are required, not optional \u2014 ThreadTranscript imports content/markdown.tsx (remend eagerly), and ThreadFeed/ThreadDetailPanel import motion/react eagerly, so this subpath fails to resolve without both installed even though peerDependenciesMeta marks them optional (npm has no per-subpath optionality).",
+    optionalPeers: [
+      "ai",
+      "motion",
+      "remend",
+      "use-stick-to-bottom",
+      "react-markdown",
+      "remark-gfm",
+      "shiki",
+      "@shikijs/langs",
+      "@shikijs/themes",
+      "beautiful-mermaid"
+    ],
+    forbiddenImports: []
+  },
   "./content": {
     kind: "doctrine",
     layer: "mantine-coupled",

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.9.0
+# basalt-ui v1.10.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.9.0
+Version: 1.10.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'
@@ -119,6 +119,13 @@ Layer: headless
 Rule: basalt-agent
 OptionalPeers: ai@^7.0.15, use-stick-to-bottom@^1.1.6
 
+## basalt-ui/agent-chat
+Import: import { ... } from 'basalt-ui/agent-chat'
+Description: Mantine-styled thread-chat components over basalt-ui/agent: ThreadWorkspace, ThreadFeed, ThreadOutcomeCard, ThreadDetailPanel, Composer, ThreadTranscript, threadPartRenderers (Mantine-coupled). remend and motion are required, not optional — ThreadTranscript imports content/markdown.tsx (remend eagerly), and ThreadFeed/ThreadDetailPanel import motion/react eagerly, so this subpath fails to resolve without both installed even though peerDependenciesMeta marks them optional (npm has no per-subpath optionality).
+Layer: mantine-coupled
+Rule: basalt-agent
+OptionalPeers: ai@^7.0.15, motion@12.42.0, remend@1.3.0, use-stick-to-bottom@^1.1.6, react-markdown@^10.1.0, remark-gfm@^4.0.1, shiki@^4.3.0, @shikijs/langs@^4.3.1, @shikijs/themes@^4.3.1, beautiful-mermaid@^1.1.0
+
 ## basalt-ui/content
 Import: import { ... } from 'basalt-ui/content'
 Description: Prose (article/chat typography), CodeBlock (shiki, optional peer), Callout, TableOfContents, ReadingProgress, Markdown (react-markdown + remark-gfm, optional peers, streaming-aware), MermaidDiagram (beautiful-mermaid, optional peer), mdxComponents/createMdxComponents, ArticleLayout (docs-page frame), ArticleCard/ArticleGrid (overview cards), Article model (sortArticles/filterArticles/formatArticleDate), ArticleFilterBar (category/tags filter UI), toArticleActions (Spotlight projector, @mantine/spotlight type-only), GuideLink/GuideDrawer (contextual-help drawer) — the content/prose surface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",
@@ -104,6 +104,10 @@
       "types": "./dist/agent/index.d.ts",
       "import": "./dist/agent/index.js"
     },
+    "./agent-chat": {
+      "types": "./dist/agent-chat/index.d.ts",
+      "import": "./dist/agent-chat/index.js"
+    },
     "./content": {
       "types": "./dist/content/index.d.ts",
       "import": "./dist/content/index.js"
@@ -128,6 +132,7 @@
   "scripts": {
     "build": "tsup && tsc --emitDeclarationOnly --declarationMap && bun scripts/copy-assets.mjs && bun scripts/gen-tokens-css.mjs && bun scripts/fix-esm-extensions.mjs",
     "typecheck": "tsc --noEmit",
+    "test": "cd ../.. && bun test packages/basalt-ui",
     "pack-test": "bash scripts/pack-test.sh",
     "prepack": "bun run build",
     "clean": "rm -rf dist"