basalt-ui 2.0.4 → 2.1.0

package/dist/cli/index.js

@@ -91,20 +91,10 @@ function sanitizeSeverity(cfg) {
   return { ...cfg, severity: kept };
 }
 function hasBasaltKey(cwd) {
-  const raw = readIfExists(resolve(cwd, "package.json"));
-  try {
-    return raw !== null && JSON.parse(raw).basalt !== void 0;
-  } catch {
-    return false;
-  }
+  return readPackageJson(cwd)?.basalt !== void 0;
 }
 function readBasaltConfig(cwd) {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf8"));
-    return sanitizeSeverity(pkg.basalt ?? {});
-  } catch {
-    return {};
-  }
+  return sanitizeSeverity(readPackageJson(cwd)?.basalt ?? {});
 }
 const SCANNABLE_EXT = /\.(?:tsx?|jsx|[cm][jt]s|astro|vue|css|html?|webmanifest)$/;
 function walkSourceFiles(dir, out = []) {
@@ -136,14 +126,11 @@ function relativePosix(fromDir, toPath) {
 const UNRESOLVED_INSTALL = { dir: null, version: null, how: null };
 function basaltInstallAt(dir) {
   const installDir = resolve(dir, "node_modules", "basalt-ui");
-  const raw = readIfExists(resolve(installDir, "package.json"));
-  if (raw === null) return null;
-  try {
-    const pkg = JSON.parse(raw);
-    return { dir: installDir, version: pkg.version ?? null };
-  } catch {
-    return { dir: installDir, version: null };
-  }
+  if (readIfExists(resolve(installDir, "package.json")) === null) return null;
+  return {
+    dir: installDir,
+    version: readPackageJson(installDir)?.version ?? null
+  };
 }
 function findBasaltInstall(cwd) {
   const own = basaltInstallAt(cwd);
@@ -244,24 +231,24 @@ function readIfExists(abs) {
     return null;
   }
 }
+function readPackageJson(dir) {
+  const raw = readIfExists(resolve(dir, "package.json"));
+  try {
+    return raw === null ? null : JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 function readSource(pkgRoot, source) {
   return readIfExists(resolve(pkgRoot, source));
 }
 function readPackageName(cwd) {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf8"));
-    if (pkg.name && pkg.name.length > 0) return pkg.name;
-  } catch {
-  }
+  const name = readPackageJson(cwd)?.name;
+  if (name && name.length > 0) return name;
   return cwd.split("/").filter(Boolean).pop() ?? "app";
 }
 function readFrameworkVersion(pkgRoot) {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(pkgRoot, "package.json"), "utf8"));
-    return pkg.version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
+  return readPackageJson(pkgRoot)?.version ?? "0.0.0";
 }
 function basaltBinCommand(install, cwd) {
   if (install.dir === null) return "bunx basalt-ui";
@@ -397,14 +384,10 @@ function resolveAppDir(root) {
   };
 }
 function hasDependency(cwd, pkgName) {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf8"));
-    return Boolean(
-      pkg.dependencies?.[pkgName] ?? pkg.devDependencies?.[pkgName] ?? pkg.peerDependencies?.[pkgName]
-    );
-  } catch {
-    return false;
-  }
+  const pkg = readPackageJson(cwd);
+  return Boolean(
+    pkg?.dependencies?.[pkgName] ?? pkg?.devDependencies?.[pkgName] ?? pkg?.peerDependencies?.[pkgName]
+  );
 }
 const ROOT_PLACEMENT = {
   isPackageRepoRoot: true,
@@ -694,14 +677,8 @@ function renderContext(cwd) {
 function patchPackageJson(cwd, mutate) {
   const abs = resolve(cwd, "package.json");
   const raw = readIfExists(abs);
-  if (raw === null) return false;
-  let pkg;
-  try {
-    pkg = JSON.parse(raw);
-  } catch {
-    return false;
-  }
-  if (!mutate(pkg)) return false;
+  const pkg = readPackageJson(cwd);
+  if (raw === null || pkg === null || !mutate(pkg)) return false;
   const indent = /\n([ \t]+)"/.exec(raw)?.[1] ?? "  ";
   writeFileSync(abs, JSON.stringify(pkg, null, indent) + (raw.endsWith("\n") ? "\n" : ""));
   return true;
@@ -926,14 +903,8 @@ function expandWorkspaceGlobs(cwd, patterns) {
   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 parsed = readPackageJson(cwd);
+  if (parsed === null) 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)";
@@ -1048,6 +1019,7 @@ export {
   readFrameworkVersion,
   readIfExists,
   readManifest,
+  readPackageJson,
   readSource,
   reconcileRoots,
   relativePosix,

package/dist/content/highlighter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"highlighter.d.ts","sourceRoot":"","sources":["../../src/content/highlighter.ts"],"names":[],"mappings":"AAkGA;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkBtF"}
+{"version":3,"file":"highlighter.d.ts","sourceRoot":"","sources":["../../src/content/highlighter.ts"],"names":[],"mappings":"AAkHA;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkBtF"}

package/dist/content/highlighter.js

@@ -37,6 +37,14 @@ const LANG_ALIASES = {
   docker: "dockerfile"
 };
 let highlighterPromise = null;
+let warnedMissingPeer = false;
+function warnMissingPeer(error) {
+  if (warnedMissingPeer || process.env["NODE_ENV"] === "production") return;
+  warnedMissingPeer = true;
+  console.warn(
+    `[basalt] CodeBlock: syntax highlighting is off \u2014 a peer of basalt-ui/content did not load (${error instanceof Error ? error.message : String(error)}). Code renders unhighlighted. Install them with: bun add shiki @shikijs/langs @shikijs/themes`
+  );
+}
 async function loadHighlighter() {
   const [{ createHighlighterCore }, { createJavaScriptRegexEngine }] = await Promise.all([
     import("shiki/core"),
@@ -49,7 +57,10 @@ async function loadHighlighter() {
   });
 }
 function getHighlighter() {
-  highlighterPromise ??= loadHighlighter().catch(() => null);
+  highlighterPromise ??= loadHighlighter().catch((error) => {
+    warnMissingPeer(error);
+    return null;
+  });
   return highlighterPromise;
 }
 async function ensureLanguage(highlighter, lang) {
@@ -59,7 +70,8 @@ async function ensureLanguage(highlighter, lang) {
   try {
     await highlighter.loadLanguage(loadLang());
     return true;
-  } catch {
+  } catch (error) {
+    warnMissingPeer(error);
     return false;
   }
 }

package/dist/shell/app-main.module.css

@@ -103,9 +103,11 @@
    * Block is breathing room under the band's single `--vx-divider` line — nothing aligns to it.
    * `stack-md` (12) on a phone, one rung down (`stack-sm`, 8) from `sm` up where the inline gutter
    * is 16: the page then sits 16 from the seam and 8 under the header, rather than the 20/12 it
-   * used to.
+   * used to. The value rides `--basalt-main-pad-block`, which descendants inherit: the data
+   * table's page-sticky offset reads it instead of repeating this module's `sm` switch.
    */
-  padding: var(--vx-space-stack-md) var(--app-shell-padding);
+  --basalt-main-pad-block: var(--vx-space-stack-md);
+  padding: var(--basalt-main-pad-block) var(--app-shell-padding);
   /* Without this a wide flex/grid child (a bare table, a nowrap control row) sizes Main to ITSELF. */
   min-width: 0;
   overflow-y: auto;
@@ -124,7 +126,7 @@
 
 @media (min-width: 52.5em) {
   .main {
-    padding-block: var(--vx-space-stack-sm);
+    --basalt-main-pad-block: var(--vx-space-stack-sm);
   }
 }
 

package/dist/shell/app-sidebar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-sidebar.d.ts","sourceRoot":"","sources":["../../src/shell/app-sidebar.tsx"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAe,cAAc,EAAE,MAAM,aAAa,CAAA;AAI5E,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAE1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAgBjF,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C;;;;OAIG;IACH,KAAK,EAAE,WAAW,GAAG;QAAE,IAAI,CAAC,EAAE,eAAe,EAAE,CAAA;KAAE,CAAA;IACjD,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,IAAI,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACtC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,mBAAmB,GAAG;QAAE,OAAO,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAA;IACjE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;CACxB,CAAA;AAiUD,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,+BA2KhD"}
+{"version":3,"file":"app-sidebar.d.ts","sourceRoot":"","sources":["../../src/shell/app-sidebar.tsx"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAe,cAAc,EAAE,MAAM,aAAa,CAAA;AAI5E,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAE1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAgBjF,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C;;;;OAIG;IACH,KAAK,EAAE,WAAW,GAAG;QAAE,IAAI,CAAC,EAAE,eAAe,EAAE,CAAA;KAAE,CAAA;IACjD,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,IAAI,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACtC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,mBAAmB,GAAG;QAAE,OAAO,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAA;IACjE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;CACxB,CAAA;AAmUD,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,+BA2KhD"}

package/dist/shell/app-sidebar.js

@@ -163,7 +163,7 @@ function NavSection({ section, collapsed }) {
         ]
       }
     ),
-    /* @__PURE__ */ jsx(Collapse, { expanded: !folded, children: /* @__PURE__ */ jsx(Stack, { gap: 1, children: items }) })
+    /* @__PURE__ */ jsx(Collapse, { expanded: !folded || collapsed, children: /* @__PURE__ */ jsx(Stack, { gap: 1, children: items }) })
   ] });
 }
 function NavItemRow({ item, collapsed }) {

package/dist/table/data-table.module.css

@@ -70,20 +70,14 @@
  * one rung down to `stack-sm` from `sm` up). A sticky `<thead>` resolves against the scrollport's
  * CONTENT edge, so at `top: 0` it parked that padding below the band and every body row scrolled
  * through the gap. A negative offset equal to the padding moves the stick line out to the band's
- * edge, flush. The two media/token pairs below mirror `.main` there — the layout suite
- * (`data-table.layout.test.ts`, invariant 8) fails on drift. A consumer `stickyHeaderOffset` is an
+ * edge, flush. The padding is read from `--basalt-main-pad-block`, which `.main` sets and owns
+ * (including its `sm` switch), so the two cannot drift; `data-table.layout.test.ts` invariant 8
+ * pins both steps. A consumer `stickyHeaderOffset` is an
  * inline `--table-sticky-header-offset` on the table and beats this class, so it still wins.
  * Outside a shell no `.mantine-AppShell-main` ancestor matches and the offset stays 0.
  */
 :global(.mantine-AppShell-main) .pageSticky {
-  --table-sticky-header-offset: calc(-1 * var(--vx-space-stack-md));
-}
-
-/* theme-allow raw-media-query — mirrors app-main.module.css's own `sm` switch for Main's block padding; invariant 8 in data-table.layout.test.ts fails on drift */
-@media (min-width: 52.5em) {
-  :global(.mantine-AppShell-main) .pageSticky {
-    --table-sticky-header-offset: calc(-1 * var(--vx-space-stack-sm));
-  }
+  --table-sticky-header-offset: calc(-1 * var(--basalt-main-pad-block, 0px));
 }
 
 /*

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v2.0.4
+# basalt-ui v2.1.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, TanStack Charts, toolchain presets
 #
 # Entry points: use the exact import specifier below; do not guess.
@@ -13,7 +13,7 @@
 # A subpath's `Install:` line is its required peers; `OptionalPeers:` are import()-only, install on use.
 
 Package: basalt-ui
-Version: 2.0.4
+Version: 2.1.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, TanStack Charts, toolchain presets",
   "keywords": [
     "charts",

package/src/agent/error.ts

@@ -26,7 +26,22 @@ function stringField(value: unknown, key: string): string | undefined {
   return typeof field === 'string' ? field : undefined
 }
 
-/** Maps whatever a transport threw onto the closed `AgentError` union. */
+/**
+ * Classifies whatever a chat transport threw or received into the closed `AgentError` union — the
+ * same mapping `useAgentThreadRuns` applies to `ThreadRunState.error`, so a custom transport can
+ * report failures identically.
+ *
+ * Input is any thrown value, matched by shape (never `instanceof`, so the optional `ai` peer is not
+ * loaded). First match wins:
+ * - `name === 'AbortError'` (an `Error` or a `DOMException`) → `{ kind: 'aborted' }`
+ * - numeric `statusCode` (AI SDK `APICallError`) → `{ kind: 'http', status }`
+ * - string `chunkType` and `chunkId` (AI SDK `UIMessageStreamError`) → `{ kind: 'stream', ... }`
+ * - anything else, including an `error` chunk's text, a plain object or a primitive →
+ *   `{ kind: 'server', message }` with the value's `message` string, else `String(value)`.
+ *
+ * A `Response` is not classified: read its `status` and pass `{ statusCode: response.status }`.
+ * Never throws.
+ */
 export function toAgentError(error: unknown): AgentError {
   // By name, not `instanceof Error`: a `fetch` abort is a DOMException, which is not an Error.
   if (stringField(error, 'name') === 'AbortError') return { kind: 'aborted' }

package/src/agent/index.ts

@@ -18,6 +18,7 @@ export { aiSdkTransport } from './ai-sdk-transport'
 export { useAgentThreadRuns } from './use-agent-thread-runs'
 export type { ThreadRunState } from './use-agent-thread-runs'
 export type { AgentError } from './error'
+export { toAgentError } from './error'
 
 // ── Thread contracts (the store is consumer-owned) ────────────────────────────
 export type { ChatMessage } from './history'

package/src/cli/doctor-upgrade.ts

@@ -2,13 +2,13 @@
  * `doctor`'s 2.0 strictness and upgrade checks. Each returns null (pass), `{ fail }` (the problem
  * plus its fix) or `{ skip }` (the check could not run: a check that cannot run is not a pass).
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { dirname, relative, resolve } from 'node:path'
 
 import { BASALT_CONFIG_KEYS, RETIRED_CONFIG_KEYS } from './config'
 import type { BasaltConfig } from './config'
-import { parseJsonc, readIfExists, scannableFiles } from './index'
+import { parseJsonc, readIfExists, readPackageJson, scannableFiles } from './index'
 import type { BasaltInstall } from './index'
 
 export type Check = { fail: string } | { skip: string } | null
@@ -22,6 +22,19 @@ const guarded = (id: string, run: () => Check): Check => {
   }
 }
 
+/** A check that reads the resolved install: skips when basalt-ui does not resolve. */
+const withInstall = (
+  id: string,
+  install: BasaltInstall,
+  reads: string,
+  run: (dir: string) => Check,
+): Check => {
+  const { dir } = install
+  return dir === null
+    ? { skip: `${id}: basalt-ui does not resolve, so its ${reads} cannot be read.` }
+    : guarded(id, () => run(dir))
+}
+
 const TSCONFIG_PRESET = /(?:^|\/)basalt-ui\/configs\/tsconfig\.(?:base|react-app)\.json$/
 const TSCONFIG_PRESET_ID = 'basalt-ui/configs/tsconfig.react-app.json'
 const TSCONFIG_FIX = `"extends": "${TSCONFIG_PRESET_ID}" (tsconfig.base.json for a package without a DOM)`
@@ -148,10 +161,7 @@ function basaltRuleIds(file: string, seen = new Set<string>()): string[] {
 /** `retired-lint-rules`: `basalt/<id>` entries the installed plugin no longer registers. */
 export function retiredLintRulesCheck(cwd: string, install: BasaltInstall): Check {
   const id = 'retired-lint-rules'
-  const dir = install.dir
-  if (dir === null)
-    return { skip: `${id}: basalt-ui does not resolve, so its plugin cannot be read.` }
-  return guarded(id, () => {
+  return withInstall(id, install, 'plugin', (dir) => {
     const ids = [...new Set(basaltRuleIds(resolve(cwd, '.oxlintrc.json')))]
     if (ids.length === 0) return null
     const pluginPath = resolve(dir, 'configs/oxlint-plugin.js')
@@ -215,6 +225,16 @@ function basaltImports(src: string): [string, number][] {
     .map((m) => [m[2] as string, code.slice(0, m.index + m[0].length).split('\n').length])
 }
 
+/** `[subpath, file, line]` per `basalt-ui/<subpath>` import in the app's source files. */
+const appImports = (cwd: string, cfg: BasaltConfig): [string, string, number][] =>
+  scannableFiles(cwd, cfg)
+    .filter((f) => /\.(?:[cm]?[jt]sx?|vue|astro)$/.test(f))
+    .flatMap((rel) =>
+      basaltImports(readIfExists(resolve(cwd, rel)) ?? '').map(
+        ([sub, line]): [string, string, number] => [sub, rel, line],
+      ),
+    )
+
 /** `dropped-subpaths`: `basalt-ui/<subpath>` imports the installed `exports` map does not have. */
 export function droppedSubpathsCheck(
   cwd: string,
@@ -222,28 +242,20 @@ export function droppedSubpathsCheck(
   install: BasaltInstall,
 ): Check {
   const id = 'dropped-subpaths'
-  const dir = install.dir
-  if (dir === null)
-    return { skip: `${id}: basalt-ui does not resolve, so its exports cannot be read.` }
-  return guarded(id, () => {
-    const pkg = JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf8')) as {
-      exports?: Record<string, unknown>
-    }
+  return withInstall(id, install, 'exports', (dir) => {
+    const pkg = readPackageJson<{ exports?: Record<string, unknown> }>(dir)
+    if (pkg === null) throw new Error(`${dir}/package.json is unreadable`)
+    const exportsMap = pkg.exports
     // No `exports` field means nothing restricts the deep imports.
-    if (pkg.exports === undefined) return null
-    const keys = Object.keys(pkg.exports)
+    if (exportsMap === undefined) return null
+    const keys = Object.keys(exportsMap)
     const has = (sub: string): boolean =>
       keys.some(
         (k) => k === `./${sub}` || (k.endsWith('*') && `./${sub}`.startsWith(k.slice(0, -1))),
       )
-    const hits: string[] = []
-    for (const rel of scannableFiles(cwd, cfg).filter((f) =>
-      /\.(?:[cm]?[jt]sx?|vue|astro)$/.test(f),
-    )) {
-      for (const [sub, line] of basaltImports(readIfExists(resolve(cwd, rel)) ?? '')) {
-        if (!has(sub)) hits.push(`${rel}:${line} imports basalt-ui/${sub}`)
-      }
-    }
+    const hits = appImports(cwd, cfg)
+      .filter(([sub]) => !has(sub))
+      .map(([sub, rel, line]) => `${rel}:${line} imports basalt-ui/${sub}`)
     if (hits.length === 0) return null
     const more = hits.length > 10 ? ` (+${hits.length - 10} more)` : ''
     return {
@@ -446,8 +458,7 @@ export function appWiringCheck(cwd: string): Check {
  */
 export function unknownConfigKeysCheck(cwd: string): Check {
   return guarded('config-keys', () => {
-    const raw = readIfExists(resolve(cwd, 'package.json'))
-    const block = raw === null ? null : (JSON.parse(raw) as { basalt?: unknown }).basalt
+    const block = readPackageJson<{ basalt?: unknown }>(cwd)?.basalt
     if (typeof block !== 'object' || block === null || Array.isArray(block)) return null
     const known = new Set<string>(BASALT_CONFIG_KEYS)
     const unknown = Object.keys(block).filter((k) => !known.has(k))
@@ -461,13 +472,18 @@ export function unknownConfigKeysCheck(cwd: string): Check {
   })
 }
 
+/** The `peerDependencies` ranges declared by the package installed at `dir`. */
+function peerRanges(dir: string): Record<string, string> {
+  return readPackageJson<{ peerDependencies?: Record<string, string> }>(dir)?.peerDependencies ?? {}
+}
+
 const EXACT_VERSION = /^\d+\.\d+\.\d+$/
 
 /** `node_modules/<pkg>/package.json`'s version, searching `cwd` then every ancestor. */
 function installedVersion(cwd: string, pkg: string): string | null {
   for (let dir = cwd; ; dir = dirname(dir)) {
-    const raw = readIfExists(resolve(dir, 'node_modules', pkg, 'package.json'))
-    if (raw !== null) return (JSON.parse(raw) as { version?: string }).version ?? null
+    const manifest = readPackageJson<{ version?: string }>(resolve(dir, 'node_modules', pkg))
+    if (manifest !== null) return manifest.version ?? null
     if (dirname(dir) === dir) return null
   }
 }
@@ -479,16 +495,8 @@ function installedVersion(cwd: string, pkg: string): string | null {
  */
 export function exactPeersCheck(cwd: string, install: BasaltInstall): Check {
   const id = 'exact-peers'
-  if (install.dir === null)
-    return { skip: `${id}: basalt-ui does not resolve, so its peers cannot be read.` }
-  const dir = install.dir
-  return guarded(id, () => {
-    const raw = readIfExists(resolve(dir, 'package.json'))
-    const peers =
-      (raw === null
-        ? {}
-        : (JSON.parse(raw) as { peerDependencies?: Record<string, string> }).peerDependencies) ?? {}
-    const off = Object.entries(peers)
+  return withInstall(id, install, 'peers', (dir) => {
+    const off = Object.entries(peerRanges(dir))
       .filter(([, range]) => EXACT_VERSION.test(range))
       .flatMap(([pkg, pin]) => {
         const have = installedVersion(cwd, pkg)
@@ -502,3 +510,46 @@ export function exactPeersCheck(cwd: string, install: BasaltInstall): Check {
     }
   })
 }
+
+/**
+ * The peers a subpath needs installed: V2-SPEC § 1's subpath-required class plus `./content`'s
+ * shiki trio, which a bundler cannot resolve without them (argo friction row 15). The test pins it
+ * to `package.json` and `surfaces.ts`.
+ */
+export const SUBPATH_REQUIRED_PEERS: Readonly<Record<string, readonly string[]>> = {
+  agent: ['ai', '@ai-sdk/provider', 'motion'],
+  charts: ['@tanstack/charts', 'd3-scale'],
+  commands: ['@tanstack/react-hotkeys'],
+  content: ['react-markdown', 'shiki', '@shikijs/langs', '@shikijs/themes'],
+  'controls-dates': ['@mantine/dates', 'dayjs'],
+  forms: ['@mantine/form'],
+  table: ['@tanstack/react-table'],
+}
+
+/**
+ * `subpath-peers`: every `basalt-ui/<subpath>` the app imports has its required peers installed. A
+ * missing one still builds, then throws "Could not resolve" when the chunk loads.
+ */
+export function subpathPeersCheck(cwd: string, cfg: BasaltConfig, install: BasaltInstall): Check {
+  const id = 'subpath-peers'
+  return withInstall(id, install, 'peers', (dir) => {
+    const missing = new Map<string, string[]>()
+    for (const [sub, file] of new Map(
+      appImports(cwd, cfg)
+        .toReversed()
+        .map(([s, f]) => [s, f]),
+    )) {
+      for (const peer of SUBPATH_REQUIRED_PEERS[sub] ?? []) {
+        if (installedVersion(cwd, peer) !== null) continue
+        missing.set(peer, [...(missing.get(peer) ?? []), `basalt-ui/${sub} (${file})`])
+      }
+    }
+    if (missing.size === 0) return null
+    const ranges = peerRanges(dir)
+    const named = [...missing].map(([peer, by]) => `${peer} for ${by.join(', ')}`)
+    const add = [...missing.keys()].map((peer) => (ranges[peer] ? `${peer}@${ranges[peer]}` : peer))
+    return {
+      fail: `${id}: peers a used basalt-ui subpath requires are not installed: ${named.join('; ')}. Fix: \`bun add ${add.join(' ')}\`.`,
+    }
+  })
+}

package/src/cli/doctor.ts

@@ -6,7 +6,6 @@
 import { existsSync } from 'node:fs'
 import { relative, resolve } from 'node:path'
 
-import type { BasaltConfig } from './config'
 import {
   AGENTS_MD,
   LEGACY_BLOCK_HOST,
@@ -26,6 +25,7 @@ import {
   readBasaltConfig,
   readIfExists,
   readManifest,
+  readPackageJson,
   resolveAppDir,
   resolveProjectDir,
   ROUTER_SEED_DESTS,
@@ -40,6 +40,7 @@ import {
   droppedSubpathsCheck,
   exactPeersCheck,
   retiredLintRulesCheck,
+  subpathPeersCheck,
   tsconfigBaseCheck,
   unknownConfigKeysCheck,
 } from './doctor-upgrade'
@@ -85,32 +86,13 @@ type AiMajorField = (typeof AI_MAJOR_FIELDS)[number]
 
 /** The `ai` major per dependency field of THIS package.json (not walked across workspaces). */
 function aiMajorsAt(dir: string): Partial<Record<AiMajorField, number>> {
-  const raw = readIfExists(resolve(dir, 'package.json'))
-  if (raw === null) return {}
-  try {
-    const pkg = JSON.parse(raw) as Partial<Record<AiMajorField, Record<string, string>>>
-    const out: Partial<Record<AiMajorField, number>> = {}
-    for (const field of AI_MAJOR_FIELDS) {
-      const major = majorOf(pkg[field]?.['ai'])
-      if (major !== null) out[field] = major
-    }
-    return out
-  } catch {
-    return {}
-  }
-}
-
-/** `basalt.aiMajorSkewReason` as a validated reason, plus whether the key was present but invalid. */
-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 }
+  const pkg = readPackageJson<Partial<Record<AiMajorField, Record<string, string>>>>(dir) ?? {}
+  const out: Partial<Record<AiMajorField, number>> = {}
+  for (const field of AI_MAJOR_FIELDS) {
+    const major = majorOf(pkg[field]?.['ai'])
+    if (major !== null) out[field] = major
   }
-  return { reason: null, presentButInvalid: true }
+  return out
 }
 
 /**
@@ -124,8 +106,8 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
  *   4. `oxlint-preset`: `.oxlintrc.json` extends the shipped preset AND that path resolves.
  *   7. `ai-major-parity`: the `ai` major agrees across this package.json's dependency fields
  *      (exempt via `basalt.aiMajorSkewReason`; a stale reason warns).
- *   8-13. `tsconfig-base`, `retired-lint-rules`, `dropped-subpaths`, `app-wiring`, `exact-peers`,
- *      `config-keys` (./doctor-upgrade);
+ *   8-14. `tsconfig-base`, `retired-lint-rules`, `dropped-subpaths`, `app-wiring`, `exact-peers`,
+ *      `subpath-peers`, `config-keys` (./doctor-upgrade);
  *      a check that cannot run is SKIPPED and exits non-zero.
  *
  * Warning (non-fatal):
@@ -153,21 +135,10 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
   const result: DoctorResult = { hardFailures: 0, warnings: 0, skipped: 0 }
   const lines: string[] = [`\nbasalt-ui doctor — ${cwd}\n`]
 
-  function pass(msg: string): void {
-    lines.push(`  ✓ ${msg}`)
-  }
-  function warn(msg: string): void {
-    lines.push(`  ⚠ ${msg}`)
-    result.warnings++
-  }
-  function fail(msg: string): void {
-    lines.push(`  ✖ ${msg}`)
-    result.hardFailures++
-  }
-  function skip(msg: string): void {
-    lines.push(`  ? SKIPPED ${msg}`)
-    result.skipped++
-  }
+  const pass = (msg: string): number => lines.push(`  ✓ ${msg}`)
+  const warn = (msg: string): number => lines.push(`  ⚠ ${msg}`) && result.warnings++
+  const fail = (msg: string): number => lines.push(`  ✖ ${msg}`) && result.hardFailures++
+  const skip = (msg: string): number => lines.push(`  ? SKIPPED ${msg}`) && result.skipped++
 
   if (project.relocatedFrom !== null) {
     lines.push(`  → BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.\n`)
@@ -368,8 +339,11 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
   const aiEntries = AI_MAJOR_FIELDS.filter((field) => aiMajors[field] !== undefined).map(
     (field) => ({ field, major: aiMajors[field] as number }),
   )
-  const { reason: aiMajorSkewReason, presentButInvalid: aiMajorSkewReasonInvalid } =
-    resolveAiMajorSkewReason(cfg)
+  // `basalt.aiMajorSkewReason`: a non-blank string exempts a skew; any other present value is invalid.
+  const rawSkewReason = cfg.aiMajorSkewReason
+  const aiMajorSkewReason =
+    typeof rawSkewReason === 'string' && rawSkewReason.trim().length > 0 ? rawSkewReason : null
+  const aiMajorSkewReasonInvalid = aiMajorSkewReason === null && rawSkewReason !== undefined
   if (aiEntries.length > 0) {
     const distinctMajors = new Set(aiEntries.map((entry) => entry.major))
     if (distinctMajors.size > 1) {
@@ -428,6 +402,10 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
         appWiringCheck(appDir),
       ],
       ['exact-peers: installed exact-pinned peers match basalt-ui', exactPeersCheck(cwd, install)],
+      [
+        'subpath-peers: every imported basalt-ui subpath has its required peers installed',
+        subpathPeersCheck(cwd, cfg, install),
+      ],
       [
         'config-keys: the basalt config block sets only keys basalt-ui reads',
         unknownConfigKeysCheck(cwd),