basalt-ui 1.8.0 → 1.10.0

package/configs/oxlint-plugin.js

@@ -14,6 +14,19 @@
  * immediately above it. The three boundary rules deliberately do NOT — see their own comment for
  * why.
  *
+ * ── The two agent-chat guard rules (`agent-resume-guard` / `agent-no-raw-usechat`) + `ai-sdk-major` ──
+ * These are also correctness/architecture boundaries, not design guidance, so they do NOT honour
+ * `theme-allow`. All three instead honour their own line-comment escape, `basalt-agent-allow`
+ * (`hasAgentAllow`, a copy of `hasThemeAllow` with a different needle) — deliberately a separate
+ * token, so a color exemption can never double as a license to switch off a streaming guard or an
+ * intentional `ai` major skew. `ai-sdk-major`'s escape is line-level and per-import, distinct from
+ * `basalt.aiMajorSkewReason` — the repo-wide, mandatory-reason config exemption for the SAME skew
+ * read by `doctor`'s `ai-major-parity` check (`src/cli/index.ts`): a lint run only ever sees one
+ * file, so there's no reason string to echo here, just a marker on the import that intentionally
+ * crosses the declared skew. `ai-sdk-major` is the one rule in this file that touches the
+ * filesystem (reads ancestor `package.json`s, memoized per directory so a lint run does one walk
+ * per directory, not per file) — every other rule here is pure AST + filename-string matching.
+ *
  * ── The three boundary rules (`visx-boundary` / `visx-tooltip` / `token-layer-boundary`) ─────────
  * These used to be one bundled `import-boundary` rule sharing a single on/off toggle — that meant
  * a consumer disabling the one check they disagreed with silently dropped the other two as well.
@@ -58,6 +71,9 @@
  * oxlint's own parser accepts (see `ALLOWED_TOP_LEVEL_KEYS` in that script); do not add ad hoc keys
  * to that file.
  */
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, resolve as resolvePath } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 // ── Shared helpers ──────────────────────────────────────────────────────────────────────────────
 
@@ -73,6 +89,23 @@ function hasThemeAllow(context, node) {
   )
 }
 
+/**
+ * True when a `basalt-agent-allow` line comment sits on `node`'s own source line or the line above
+ * it. A copy of `hasThemeAllow` with a different needle — deliberately NOT the same token, so a
+ * color exemption can never double as a license to switch off a streaming guard (see the file-header
+ * comment for the two agent-chat rules).
+ */
+function hasAgentAllow(context, node) {
+  const sourceCode = context.sourceCode ?? context.getSourceCode?.()
+  const comments = sourceCode?.getAllComments?.() ?? []
+  const nodeLine = node.loc.start.line
+  return comments.some(
+    (comment) =>
+      comment.value.includes('basalt-agent-allow') &&
+      (comment.loc.end.line === nodeLine || comment.loc.end.line === nodeLine - 1),
+  )
+}
+
 function getFilename(context) {
   return context.filename ?? context.getFilename?.() ?? ''
 }
@@ -523,6 +556,249 @@ const tokenLayerBoundary = {
   },
 }
 
+// ── Rule 8 — agent-resume-guard ─────────────────────────────────────────────────────────────────
+
+const AGENT_RESUME_GUARD_MESSAGE =
+  'Unguarded stream resume — useAgentThreadRuns owns single-consumer discipline and ' +
+  'StrictMode-safe reconnection; a raw resume re-fires on every effect re-run (vercel/ai#7891, no ' +
+  "merged fix). Mark the line 'basalt-agent-allow' if you own the guard. (basalt/agent-resume-guard)"
+
+/** True for `resumeStream()` and `<anything>.resumeStream()` call expressions. */
+function isResumeStreamCall(callee) {
+  if (callee.type === 'Identifier') return callee.name === 'resumeStream'
+  return (
+    callee.type === 'MemberExpression' &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === 'resumeStream'
+  )
+}
+
+/** The `key` of an object Property as a string, covering both Identifier and Literal keys. */
+function propertyKeyName(node) {
+  const key = node.key
+  if (key.type === 'Identifier') return key.name
+  if (key.type === 'Literal') return key.value
+  return undefined
+}
+
+// Deliberately NO `hasThemeAllow` escape — see basalt/visx-boundary's comment for why these
+// guards use their own token (`basalt-agent-allow`, see the file-header comment) instead.
+const agentResumeGuard = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow unguarded useChat({ resume: true }) / resumeStream() calls outside useAgentThreadRuns.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+
+        if (callee.type === 'Identifier' && callee.name === 'useChat') {
+          const arg0 = node.arguments[0]
+          if (arg0 === undefined || arg0.type !== 'ObjectExpression') return
+          for (const prop of arg0.properties) {
+            if (prop.type !== 'Property') continue
+            if (propertyKeyName(prop) !== 'resume') continue
+            if (prop.value.type !== 'Literal' || prop.value.value !== true) continue
+            if (hasAgentAllow(context, prop)) continue
+            context.report({ node: prop, message: AGENT_RESUME_GUARD_MESSAGE })
+          }
+          return
+        }
+
+        if (!isResumeStreamCall(callee)) return
+        if (hasAgentAllow(context, node)) return
+        context.report({ node, message: AGENT_RESUME_GUARD_MESSAGE })
+      },
+    }
+  },
+}
+
+// ── Rule 9 — agent-no-raw-usechat ───────────────────────────────────────────────────────────────
+
+const AGENT_NO_RAW_USECHAT_MESSAGE =
+  'Raw @ai-sdk/react useChat — use useAgentStream / useAgentThreadRuns over aiSdkTransport ' +
+  "(unmount abort, supersede guards, single-consumer resume). Mark the line 'basalt-agent-allow' to " +
+  'opt out. (basalt/agent-no-raw-usechat)'
+
+const RAW_USE_CHAT_SOURCES = new Set(['@ai-sdk/react', 'ai/react'])
+const RAW_USE_CHAT_NAMES = new Set(['useChat', 'useCompletion'])
+
+// Deliberately NO `hasThemeAllow` escape — see the file-header comment.
+const agentNoRawUseChat = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow importing useChat/useCompletion directly from @ai-sdk/react or ai/react.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      ImportDeclaration(node) {
+        const source = node.source?.value
+        if (typeof source !== 'string' || !RAW_USE_CHAT_SOURCES.has(source)) return
+        // A whole `import type { … } from '…'` is erased at compile time — nothing to guard.
+        if (node.importKind === 'type') return
+
+        for (const specifier of node.specifiers) {
+          if (specifier.type !== 'ImportSpecifier') continue
+          // `import { type useChat } from '…'` — the individual specifier is type-only.
+          if (specifier.importKind === 'type') continue
+          const imported = specifier.imported
+          const importedName = imported.type === 'Identifier' ? imported.name : imported.value
+          if (typeof importedName !== 'string' || !RAW_USE_CHAT_NAMES.has(importedName)) continue
+          if (hasAgentAllow(context, specifier)) continue
+          context.report({ node: specifier, message: AGENT_NO_RAW_USECHAT_MESSAGE })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 10 — ai-sdk-major ──────────────────────────────────────────────────────────────────────
+
+/**
+ * First run of digits in a semver range string (`^7.0.15` → `7`), or null if there is none.
+ *
+ * Duplicated verbatim in `src/cli/index.ts` — kept separate deliberately: this file must stay
+ * import-free from the package (it loads via `jsPlugins` out of a consumer's node_modules), so it
+ * cannot import the CLI's copy. Keep both copies in sync by hand; a future parsing fix (pre-release
+ * suffixes, say) must land in both.
+ */
+function majorOf(range) {
+  if (typeof range !== 'string') return null
+  const match = range.match(/\d+/)
+  return match === null ? null : Number(match[0])
+}
+
+/**
+ * `ai`'s declared major off one parsed package.json, checked in ONE fixed order shared by every
+ * reader in this file (basalt's own major below, and the linted file's nearest package.json in
+ * `aiMajorAtPackageJson`) — `dependencies` → `devDependencies` → `peerDependencies`. Chosen
+ * deliberately: `dependencies` is what actually gets installed and resolved at runtime, so it wins
+ * over a `devDependencies` pin (test-only) or a `peerDependencies` range (a floor, not a pin). Two
+ * readers disagreeing on this order is exactly the kind of skew this rule exists to catch — see
+ * `cli/index.ts`'s `aiMajorAt`, which uses the same order for doctor's cross-package walk.
+ */
+function aiMajorFromPkg(pkg) {
+  return majorOf(pkg.dependencies?.ai ?? pkg.devDependencies?.ai ?? pkg.peerDependencies?.ai)
+}
+
+/**
+ * basalt-ui's OWN declared `ai` peer major, read once at module load from the package.json
+ * sitting next to this file's `configs/` directory — `../package.json` relative to this module,
+ * which resolves to `packages/basalt-ui/package.json` repo-locally AND to
+ * `node_modules/basalt-ui/package.json` when this file runs from a consumer's installed copy
+ * (`configs/oxlint-plugin.js` is one directory below the package root in both places). `null` when
+ * unreadable or undeclared — the rule then has nothing to compare against and stays silent.
+ */
+const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url))
+const BASALT_AI_MAJOR = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync(resolvePath(PLUGIN_DIR, '..', 'package.json'), 'utf8'))
+    // Peer-first, unlike aiMajorFromPkg's dependencies-first order: `ai` is an optional PEER of
+    // basalt-ui, never its runtime dependency, so the "dependencies wins because runtime" rationale
+    // above does not apply to this self-read — a devDependencies test pin must not masquerade as
+    // the declared peer major.
+    return majorOf(pkg.peerDependencies?.ai ?? pkg.devDependencies?.ai ?? pkg.dependencies?.ai)
+  } catch {
+    return null
+  }
+})()
+
+// One JSON.parse per package.json path, and one directory-walk result per starting directory — so
+// a lint run over N files in the same package does one filesystem walk total, not N.
+const packageJsonMajorCache = new Map()
+const nearestAiMajorCache = new Map()
+
+function aiMajorAtPackageJson(pkgPath) {
+  if (packageJsonMajorCache.has(pkgPath)) return packageJsonMajorCache.get(pkgPath)
+  let major = null
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    major = aiMajorFromPkg(pkg)
+  } catch {
+    major = null
+  }
+  packageJsonMajorCache.set(pkgPath, major)
+  return major
+}
+
+/** Walks up from `startDir` to the nearest ancestor `package.json`'s declared `ai` major. */
+function nearestAiMajor(startDir) {
+  if (nearestAiMajorCache.has(startDir)) return nearestAiMajorCache.get(startDir)
+
+  const visited = []
+  let dir = startDir
+  let result = null
+  for (;;) {
+    if (nearestAiMajorCache.has(dir)) {
+      result = nearestAiMajorCache.get(dir)
+      break
+    }
+    visited.push(dir)
+    const pkgPath = resolvePath(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      result = aiMajorAtPackageJson(pkgPath)
+      break
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break // filesystem root — no package.json found
+    dir = parent
+  }
+  for (const d of visited) nearestAiMajorCache.set(d, result)
+  return result
+}
+
+function aiSdkMajorMessage(consumerMajor) {
+  return (
+    `This file's nearest package.json declares ai@${consumerMajor}, but basalt-ui declares the ` +
+    `ai@${BASALT_AI_MAJOR} peer major — a producer/consumer pair on different ai majors can throw ` +
+    "'Unknown chunk type' at runtime (argo defect 1: apps/api on ai@5 vs apps/dashboard on ai@7). " +
+    '(basalt/ai-sdk-major)'
+  )
+}
+
+// Honours `basalt-agent-allow` (NOT `theme-allow`) like its two agent-chat siblings above — a
+// version skew is still a fact about two package.json files, but a written, intentional
+// producer/consumer pair (see `doctor`'s `aiMajorSkewReason`) needs a way to say so at the import
+// site too, not just be permanently blocked.
+const aiSdkMajor = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        "Disallow importing 'ai'/'@ai-sdk/*' from a package whose declared ai major differs from basalt-ui's.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      ImportDeclaration(node) {
+        if (BASALT_AI_MAJOR === null) return
+        const source = node.source?.value
+        if (typeof source !== 'string') return
+        if (source !== 'ai' && !source.startsWith('@ai-sdk/')) return
+
+        const filename = getFilename(context)
+        if (filename.length === 0) return
+        const consumerMajor = nearestAiMajor(dirname(filename))
+        if (consumerMajor === null) return // no `ai` in the nearest package.json — nothing to compare
+        if (consumerMajor === BASALT_AI_MAJOR) return
+        if (hasAgentAllow(context, node)) return
+
+        context.report({ node, message: aiSdkMajorMessage(consumerMajor) })
+      },
+    }
+  },
+}
+
 // ── Plugin export ───────────────────────────────────────────────────────────────────────────────
 
 export default {
@@ -536,5 +812,8 @@ export default {
     'visx-boundary': visxBoundary,
     'visx-tooltip': visxTooltip,
     'token-layer-boundary': tokenLayerBoundary,
+    'agent-resume-guard': agentResumeGuard,
+    'agent-no-raw-usechat': agentNoRawUseChat,
+    'ai-sdk-major': aiSdkMajor,
   },
 }

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/charts/hooks/useHoverSync.d.ts

@@ -12,16 +12,32 @@ type XScale = (x: string) => number | undefined;
  * closest-point loop inline — drift across 15+ charts is the exact problem
  * this hook prevents.
  */
-export declare function useHoverSync<T>({ data, chartId, getKey, xScale, marginLeft, }: {
+export declare function useHoverSync<T>({ data, chartId, getKey, xScale, marginLeft, resolveKey, }: {
     data: T[];
     chartId: string;
     getKey: (d: T) => string;
     xScale: XScale;
     marginLeft: number;
+    /**
+     * Overrides how a SIBLING's broadcast key resolves to one of THIS chart's own points. Only
+     * affects reading another chart's hover — this chart's own hover (via `getKey`/`xScale`) is
+     * untouched.
+     *
+     * Cross-chart sync is exact string match by default (`pointByKey.get(ctx.key)`), so two charts
+     * share a cursor only if they emit identical key strings. A chart that downsamples/folds its
+     * domain to fit a narrow viewport (e.g. ~288 buckets folded into ~97 columns at 390px) no longer
+     * owns most of the keys its unfolded siblings broadcast — the shared crosshair then appears on
+     * roughly one hover in three, with no rule a reader can infer, which is worse than no shared
+     * cursor at all. Pass `resolveKey` to map a foreign key onto whichever of this chart's own points
+     * swallowed it (e.g. the folded bucket the key falls into).
+     *
+     * Omit it and behaviour is byte-identical to today.
+     */
+    resolveKey?: (key: string) => T | null;
 }): {
     tip: import("./useChartTooltip.js").TooltipState<T>;
     tooltipRef: import("react").RefObject<HTMLDivElement | null>;
-    syncedPoint: NonNullable<T> | null;
+    syncedPoint: T | null;
     isDirectHover: boolean;
     handleMouse: (event: React.MouseEvent<SVGRectElement>) => void;
     handleLeave: () => void;

package/dist/charts/hooks/useHoverSync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useHoverSync.d.ts","sourceRoot":"","sources":["../../../src/charts/hooks/useHoverSync.ts"],"names":[],"mappings":"AAKA,KAAK,MAAM,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;AAE/C;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAC9B,IAAI,EACJ,OAAO,EACP,MAAM,EACN,MAAM,EACN,UAAU,GACX,EAAE;IACD,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAA;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;CACnB;;;;;yBAgCW,KAAK,CAAC,UAAU,CAAC,cAAc,CAAC;;EAmD3C"}
+{"version":3,"file":"useHoverSync.d.ts","sourceRoot":"","sources":["../../../src/charts/hooks/useHoverSync.ts"],"names":[],"mappings":"AAKA,KAAK,MAAM,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;AAE/C;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAC9B,IAAI,EACJ,OAAO,EACP,MAAM,EACN,MAAM,EACN,UAAU,EACV,UAAU,GACX,EAAE;IACD,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAA;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,IAAI,CAAA;CACvC;;;;;yBA6CW,KAAK,CAAC,UAAU,CAAC,cAAc,CAAC;;EAyD3C"}