basalt-ui 2.0.3 → 2.0.5

package/dist/table/data-table.d.ts.map

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

package/dist/table/data-table.js

@@ -588,7 +588,11 @@ function BasaltDataTable(props) {
   const tableNode = /* @__PURE__ */ jsxs(
     Table,
     {
-      className: cx(classNames?.table),
+      className: cx(
+        classes.table,
+        pageStickyHeader && !contained && classes.pageSticky,
+        classNames?.table
+      ),
       ...striped !== void 0 && { striped },
       ...highlightOnHover !== void 0 && { highlightOnHover },
       ...stickyHeader !== void 0 && { stickyHeader },
@@ -601,7 +605,7 @@ function BasaltDataTable(props) {
       withTableBorder,
       children: [
         /* @__PURE__ */ jsx(Table.Thead, { children: headerGroups.map((headerGroup) => /* @__PURE__ */ jsxs(Table.Tr, { children: [
-          hasFolded && /* @__PURE__ */ jsx(Table.Th, { className: classes.foldToggleCell, "aria-hidden": true }),
+          hasFolded && /* @__PURE__ */ jsx(Table.Th, { className: classes.foldToggleCell, children: /* @__PURE__ */ jsx("span", { className: classes.srOnly, children: "Details" }) }),
           headerGroup.headers.map((header) => {
             const canSort = sortingEnabled && header.column.getCanSort();
             const sorted = header.column.getIsSorted();

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

@@ -63,6 +63,49 @@
   overflow-x: auto;
 }
 
+/*
+ * A page-scrolled sticky header INSIDE the shell seals the strip above it.
+ *
+ * `AppShell.Main` is the scrollport and carries block padding (`app-main.module.css`: `stack-md`,
+ * 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
+ * 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));
+  }
+}
+
+/*
+ * A Badge cell keeps its label. Mantine's Badge label is `overflow: hidden; text-overflow:
+ * ellipsis`, which gives the badge a min-content of ~0, so an auto-layout column holding only
+ * badges was free to shrink under its neighbours (`WORKING` → `WOR…` at 1280px). `max-content`
+ * as the floor makes the status column the widest thing a short enum ever needs.
+ */
+.table :global(.mantine-Badge-root) {
+  min-width: max-content;
+}
+
+/* Visually hidden, still announced — the fold toggle column's header has no visible label. */
+.srOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
 /*
  * The selection column's hit area is the WHOLE cell (`docs/CONTROLS-SPEC.md` §2): the
  * cell is the positioning box and the wrapping <label>'s ::after stretches over it, so a tap

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

@@ -16,7 +16,10 @@ declare const classes: {
   readonly foldToggle: string
   readonly foldToggleCell: string
   readonly foldWrapper: string
+  readonly pageSticky: string
   readonly selectCell: string
   readonly selectHit: string
+  readonly srOnly: string
+  readonly table: string
 }
 export default classes

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v2.0.3
+# basalt-ui v2.0.5
 # 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.3
+Version: 2.0.5
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

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

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),

package/src/cli/index.ts

@@ -148,23 +148,11 @@ function sanitizeSeverity(cfg: BasaltConfig): BasaltConfig {
 /** Does `cwd`'s own `package.json` carry a `basalt` key? — "misconfigured roots" vs "wrong
  *  directory", the failure a root-invoked hook hits since 1.29.0's single resolver. Never a walk. */
 export function hasBasaltKey(cwd: string): boolean {
-  const raw = readIfExists(resolve(cwd, 'package.json'))
-  try {
-    return raw !== null && (JSON.parse(raw) as { basalt?: unknown }).basalt !== undefined
-  } catch {
-    return false
-  }
+  return readPackageJson<{ basalt?: unknown }>(cwd)?.basalt !== undefined
 }
 
 export function readBasaltConfig(cwd: string): BasaltConfig {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(cwd, 'package.json'), 'utf8')) as {
-      basalt?: BasaltConfig
-    }
-    return sanitizeSeverity(pkg.basalt ?? {})
-  } catch {
-    return {}
-  }
+  return sanitizeSeverity(readPackageJson<{ basalt?: BasaltConfig }>(cwd)?.basalt ?? {})
 }
 
 /**
@@ -237,13 +225,10 @@ const UNRESOLVED_INSTALL: BasaltInstall = { dir: null, version: null, how: null
 /** `<dir>/node_modules/basalt-ui` when it holds a readable package.json, else null. */
 function basaltInstallAt(dir: string): { dir: string; version: string | null } | null {
   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) as { version?: string }
-    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<{ version?: string }>(installDir)?.version ?? null,
   }
 }
 
@@ -500,31 +485,30 @@ export function readIfExists(abs: string): string | null {
   }
 }
 
+/** `<dir>/package.json` parsed as `T`; null when absent or not JSON. */
+export function readPackageJson<T>(dir: string): T | null {
+  const raw = readIfExists(resolve(dir, 'package.json'))
+  try {
+    return raw === null ? null : (JSON.parse(raw) as T)
+  } catch {
+    return null
+  }
+}
+
 /** Read a shipped source asset from the package root; null if the sibling hasn't authored it yet. */
 export function readSource(pkgRoot: string, source: string): string | null {
   return readIfExists(resolve(pkgRoot, source))
 }
 
 function readPackageName(cwd: string): string {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(cwd, 'package.json'), 'utf8')) as { name?: string }
-    if (pkg.name && pkg.name.length > 0) return pkg.name
-  } catch {
-    // fall through to dir name
-  }
+  const name = readPackageJson<{ name?: string }>(cwd)?.name
+  if (name && name.length > 0) return name
   return cwd.split('/').filter(Boolean).pop() ?? 'app'
 }
 
 /** The framework's own published version, read from the package root package.json. */
 export function readFrameworkVersion(pkgRoot: string): string {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(pkgRoot, 'package.json'), 'utf8')) as {
-      version?: string
-    }
-    return pkg.version ?? '0.0.0'
-  } catch {
-    return '0.0.0'
-  }
+  return readPackageJson<{ version?: string }>(pkgRoot)?.version ?? '0.0.0'
 }
 
 /**
@@ -733,20 +717,18 @@ export function resolveAppDir(root: string): AppResolution {
 
 /** True when `pkgName` appears in the consumer's dependencies, devDependencies, or peerDependencies. */
 function hasDependency(cwd: string, pkgName: string): boolean {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(cwd, 'package.json'), 'utf8')) as {
-      dependencies?: Record<string, string>
-      devDependencies?: Record<string, string>
-      peerDependencies?: Record<string, string>
-    }
-    return Boolean(
-      pkg.dependencies?.[pkgName] ??
-      pkg.devDependencies?.[pkgName] ??
-      pkg.peerDependencies?.[pkgName],
-    )
-  } catch {
-    return false
-  }
+  const pkg =
+    readPackageJson<
+      Record<
+        'dependencies' | 'devDependencies' | 'peerDependencies',
+        Record<string, string> | undefined
+      >
+    >(cwd)
+  return Boolean(
+    pkg?.dependencies?.[pkgName] ??
+    pkg?.devDependencies?.[pkgName] ??
+    pkg?.peerDependencies?.[pkgName],
+  )
 }
 
 /**
@@ -1275,14 +1257,8 @@ export function patchPackageJson(
 ): boolean {
   const abs = resolve(cwd, 'package.json')
   const raw = readIfExists(abs)
-  if (raw === null) return false
-  let pkg: Record<string, unknown>
-  try {
-    pkg = JSON.parse(raw) as Record<string, unknown>
-  } catch {
-    return false
-  }
-  if (!mutate(pkg)) return false
+  const pkg = readPackageJson<Record<string, unknown>>(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
@@ -1689,15 +1665,8 @@ function expandWorkspaceGlobs(cwd: string, patterns: readonly string[]): string[
  * an unrecognized `workspaces` shape.
  */
 function collectWorkspacePackages(cwd: string): WorkspaceWalk {
-  const raw = readIfExists(resolve(cwd, 'package.json'))
-  if (raw === null) return { packages: [], hasWorkspacesField: false }
-
-  let parsed: { workspaces?: unknown; name?: string }
-  try {
-    parsed = JSON.parse(raw) as { workspaces?: unknown; name?: string }
-  } catch {
-    return { packages: [], hasWorkspacesField: false }
-  }
+  const parsed = readPackageJson<{ workspaces?: unknown; name?: string }>(cwd)
+  if (parsed === null) return { packages: [], hasWorkspacesField: false }
 
   const patterns = isStringArray(parsed.workspaces)
     ? parsed.workspaces

package/src/content/highlighter.ts

@@ -64,6 +64,18 @@ const LANG_ALIASES: Record<string, string> = {
 }
 
 let highlighterPromise: Promise<HighlighterCore | null> | null = null
+let warnedMissingPeer = false
+
+/** Dev-only, once per process: the highlighter peers did not resolve, so code stays unhighlighted. */
+function warnMissingPeer(error: unknown): void {
+  if (warnedMissingPeer || process.env['NODE_ENV'] === 'production') return
+  warnedMissingPeer = true
+  console.warn(
+    '[basalt] CodeBlock: syntax highlighting is off — 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(): Promise<HighlighterCore | null> {
   const [{ createHighlighterCore }, { createJavaScriptRegexEngine }] = await Promise.all([
@@ -79,7 +91,10 @@ async function loadHighlighter(): Promise<HighlighterCore | null> {
 
 /** Module-level singleton — resolves once; every caller shares the same highlighter instance. */
 function getHighlighter(): Promise<HighlighterCore | null> {
-  highlighterPromise ??= loadHighlighter().catch(() => null)
+  highlighterPromise ??= loadHighlighter().catch((error: unknown) => {
+    warnMissingPeer(error)
+    return null
+  })
   return highlighterPromise
 }
 
@@ -91,7 +106,8 @@ async function ensureLanguage(highlighter: HighlighterCore, lang: string): Promi
   try {
     await highlighter.loadLanguage(loadLang() as LanguageInput)
     return true
-  } catch {
+  } catch (error) {
+    warnMissingPeer(error)
     return false
   }
 }