basalt-ui 1.41.0 → 2.0.0

package/src/cli/init.ts

@@ -6,15 +6,16 @@
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 
-import { deriveSpacing } from '../tokens'
+import { deriveSpacing } from '../tokens/core'
 import type { MergeLintResult, ScaffoldFlags } from './index'
 import {
   MANIFEST_PATH,
-  blockMigrationProblem,
+  declaredProfile,
+  readBasaltConfig,
+  ROUTER_SEED_DESTS,
   findBasaltInstall,
   managedFiles,
   mergeOxlintExtends,
-  migrateBlockToAgentsMd,
   normalizeForLedger,
   patchPackageJson,
   placementNotices,
@@ -22,9 +23,7 @@ import {
   readManifest,
   reconcileRoots,
   renderContext,
-  reportBlockMigration,
   reportPrune,
-  resolvePeerFlags,
   resolvePlacement,
   rootsNotices,
   sha256,
@@ -32,6 +31,7 @@ import {
   writeFileEnsuringDir,
   writeUnit,
 } from './index'
+import { seedTsconfigExtends } from './doctor-upgrade'
 import { readOxlintPresetPlugins } from './sync'
 
 /**
@@ -40,28 +40,35 @@ import { readOxlintPresetPlugins } from './sync'
  * whole lint half stays off, and every gate downstream reports green over it.
  */
 const KEPT_FILE_COST: Record<string, string> = {
-  '.oxlintrc.json':
-    'the shipped oxlint preset (the basalt/* design rules AND the jsx-a11y / import / promise / ' +
-    'unicorn plugins) is NOT active — nothing else turns it on, and every gate stays green ' +
-    'without it. Re-run with `--merge-lint` to splice the extends in, or add it by hand.',
   'lefthook.yml':
     'the pre-commit oxlint / oxfmt / check-theme jobs are not wired — add `extends: ' +
     '[<preset>]` to your own file.',
   '.github/workflows/check.yml':
     'CI does not run check-theme or the sync drift gate — copy those steps into your own workflow.',
+  'src/main.tsx':
+    'change it to match node_modules/basalt-ui/agent/templates/main.tpl: import ' +
+    "'basalt-ui/styles.css'; `const router = createBasaltRouter({ routeTree })`; declare " +
+    "`interface Register { router: typeof router }` in module '@tanstack/react-router'; render " +
+    '`<BasaltProvider router={router} />`. Without them the seeded src/lib/nav.tsx fails tsc.',
   '.oxfmtrc.json': 'your existing formatter config stands; basalt formats nothing on its own.',
   'DESIGN.md': 'the design brief Claude reads is yours, not the seeded one.',
 }
 
-/** Scaffold all managed files into the consumer repo, then write the manifest. Idempotent. Returns 0. */
-export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags = {}): number {
-  // First, before anything is written: a block that cannot be moved safely refuses the whole run.
-  const blockProblem = blockMigrationProblem(cwd)
-  if (blockProblem !== null) {
-    console.error(`✖ basalt-ui init: ${blockProblem}`)
-    return 1
+/** What happened to a kept `.oxlintrc.json`, by the merge result (null: `--no-merge-lint`). */
+function oxlintrcCost(merge: MergeLintResult | null): string {
+  if (merge === 'added' || merge === 'already') {
+    return 'now extends the shipped preset: the basalt/* design rules and the jsx-a11y / import / promise / unicorn plugins are on.'
   }
+  const why =
+    merge === null ? 'init ran with --no-merge-lint' : 'init could not splice the extends in'
+  return (
+    `the shipped oxlint preset (the basalt/* rules, jsx-a11y, import, promise, unicorn) is NOT active: ${why}, ` +
+    'nothing else turns it on, and every gate stays green without it. Add the `extends` by hand.'
+  )
+}
 
+/** Scaffold all managed files into the consumer repo, then write the manifest. Idempotent. Returns 0. */
+export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags = {}): number {
   // ── Describe the repo BEFORE rendering anything ───────────────────────────
   // Every roots-derived seed (the CI oxfmt globs, DESIGN.md's series path, the default scan
   // exemption) renders from `basalt.roots`, so the key has to exist first. Writing it is what
@@ -91,13 +98,30 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
     return true
   })
 
+  // create-vite's `tsc -b && vite build` fails on a fresh app: vite generates routeTree.gen.ts.
+  // The stock script is reordered; any other script that runs tsc gets one line of advice.
+  let buildNote: string | null = null
+  patchPackageJson(cwd, (pkg) => {
+    const scripts = (pkg['scripts'] ?? {}) as Record<string, unknown>
+    const build = scripts['build']
+    if (typeof build !== 'string' || !/\btsc\b/.test(build) || build.startsWith('vite build')) {
+      return false
+    }
+    if (build !== 'tsc -b && vite build') {
+      buildNote = `"build" (${build}) left as is: run \`vite build\` before \`tsc\` (vite generates routeTree.gen.ts).`
+      return false
+    }
+    pkg['scripts'] = { ...scripts, build: 'vite build && tsc -b' }
+    buildNote = 'rewrote "build" to `vite build && tsc -b` (vite generates routeTree.gen.ts).'
+    return true
+  })
+
   const manifest = readManifest(cwd)
-  const peers = resolvePeerFlags(cwd, scaffoldFlags)
   const placement = resolvePlacement(cwd)
-  const files = managedFiles(peers, placement)
-
-  // Before the loop: an install from before the move carries the block in CLAUDE.md.
-  const migration = migrateBlockToAgentsMd(cwd, manifest)
+  // A tokens-only consumer has no use for the Mantine/React scaffolds (doctor skips them there too).
+  const tokensOnly = declaredProfile(readBasaltConfig(cwd), []) === 'tokens-only'
+  const routerSeeds: string[] = Object.values(ROUTER_SEED_DESTS)
+  const files = managedFiles(placement).filter((f) => !(tokensOnly && routerSeeds.includes(f.dest)))
 
   const writtenFiles: string[] = []
   const keptFiles: string[] = []
@@ -134,7 +158,7 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
   const pruned = pruneRetiredManagedFiles(cwd, manifest, files)
 
   const mergeLint: MergeLintResult | null =
-    scaffoldFlags.mergeLint === true ? mergeOxlintExtends(cwd, ctx.vars.OXLINT_PRESET_PATH) : null
+    scaffoldFlags.noMergeLint === true ? null : mergeOxlintExtends(cwd, ctx.vars.OXLINT_PRESET_PATH)
 
   manifest.basaltVersion = ctx.vars.BASALT_VERSION
   manifest.spacingScale = { ...deriveSpacing(0).scale }
@@ -144,7 +168,6 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
     `basalt-ui init: ${writtenFiles.length} written, ${keptFiles.length} kept, manifest at ${MANIFEST_PATH}`,
   )
   reportPrune(pruned)
-  reportBlockMigration(migration, 'init')
   if (missingSources.length > 0) {
     console.log(
       `basalt-ui init: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(', ')}`,
@@ -156,48 +179,34 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
   if (keptFiles.length > 0) {
     console.log(`\nKept (already present — basalt did not touch them):`)
     for (const dest of keptFiles) {
-      const cost = KEPT_FILE_COST[dest]
+      const cost = dest === '.oxlintrc.json' ? oxlintrcCost(mergeLint) : KEPT_FILE_COST[dest]
       console.log(cost === undefined ? `  · ${dest}` : `  · ${dest} — ${cost}`)
     }
   }
-  if (mergeLint !== null) {
-    const mergeMessage: Record<MergeLintResult, string> = {
-      added: `spliced "${ctx.vars.OXLINT_PRESET_PATH}" into the existing .oxlintrc.json extends`,
-      already: '.oxlintrc.json already extends the shipped preset — nothing to do',
-      absent:
-        'no existing .oxlintrc.json to merge into (the seeded one already extends the preset)',
-      unreadable: '.oxlintrc.json is not valid JSON — merge the extends entry by hand',
-      'has-comments':
-        '.oxlintrc.json carries comments; rewriting it would delete them (usually the reason each ' +
-        `rule is off). Add "extends": ["${ctx.vars.OXLINT_PRESET_PATH}"] as the first entry by hand.`,
-    }
-    console.log(`basalt-ui init: --merge-lint — ${mergeMessage[mergeLint]}`)
+  // `already` / `absent` need no words: the preset is on, or the seeded config just made it so.
+  const mergeMessage: Partial<Record<MergeLintResult, string>> = {
+    added: `spliced "${ctx.vars.OXLINT_PRESET_PATH}" into the existing .oxlintrc.json extends`,
+    unreadable: '.oxlintrc.json is not valid JSON — merge the extends entry by hand',
+    'has-comments':
+      '.oxlintrc.json carries comments; rewriting it would delete them (usually the reason each ' +
+      `rule is off). Add "extends": ["${ctx.vars.OXLINT_PRESET_PATH}"] as the first entry by hand.`,
   }
+  const mergeLine = mergeLint === null ? undefined : mergeMessage[mergeLint]
+  if (mergeLine !== undefined) console.log(`basalt-ui init: oxlint — ${mergeLine}`)
+  const tsconfigLine = tokensOnly ? null : seedTsconfigExtends(cwd)
+  if (tsconfigLine !== null) console.log(`basalt-ui init: ${tsconfigLine}`)
+  if (buildNote !== null) console.log(`basalt-ui init: ${buildNote}`)
   const rootsMessages = rootsNotices(rootsState)
   for (const line of rootsMessages.log) console.log(`basalt-ui init: ${line}`)
   for (const line of rootsMessages.error) console.error(`⚠ basalt-ui init: ${line}`)
   if (seededLintScript) {
     console.log(`basalt-ui init: added the "lint:basalt" script (${lintScript}) to package.json.`)
   }
-  // The permanent placement skips (repo-root-shaped tooling, a relocated scaffold) — one text,
+  // The permanent placement skips (repo-root-shaped tooling) — one text,
   // shared with `sync`. See {@link placementNotices}.
   for (const line of placementNotices(cwd, placement)) {
     console.log(`basalt-ui init: ${line}`)
   }
-  // query-client.ts / __root.tsx reference the optional TanStack peers directly — seeding them
-  // without the peer installed would ship an unresolved import. Hint how to opt in instead.
-  if (!peers.hasQuery) {
-    console.log(
-      'basalt-ui init: skipped src/query-client.ts (no @tanstack/react-query dependency detected) — ' +
-        'install it, or re-run with --with-query, to scaffold it.',
-    )
-  }
-  if (!peers.hasRouter || !peers.hasQuery) {
-    console.log(
-      'basalt-ui init: skipped src/routes/__root.tsx (needs both @tanstack/react-router and ' +
-        '@tanstack/react-query) — install both, or re-run with --with-router --with-query, to scaffold it.',
-    )
-  }
   // The guard-hook PreToolUse registration is NOT written automatically — add it manually to
   // .claude/settings.json so every Write/Edit/MultiEdit goes through the theme guard.
   console.log(

package/src/cli/sync.ts

@@ -1,13 +1,8 @@
-/**
- * `sync` — split out of `src/cli/index.ts` (C2) so the dispatcher file holds routing only. Imports
- * the managed-file manifest engine (`managedFiles`, `readManifest`, `writeUnit`, `reconcileRoots`,
- * …), the toolchain-seam inspectors (`inspectLefthookGate`, `basaltPresetEntry`), and project
- * resolution back from `./index`, this package's shared CLI helpers.
- */
+/** `sync` — split out of `src/cli/index.ts` (C2); shared plumbing is imported back from `./index`. */
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 
-import { deriveSpacing } from '../tokens'
+import { deriveSpacing } from '../tokens/core'
 import {
   MANIFEST_PATH,
   basaltPresetEntry,
@@ -17,12 +12,8 @@ import {
   diffSummary,
   findBasaltInstall,
   inspectLefthookGate,
-  AGENTS_MD,
-  blockMigrationProblem,
   isStringArray,
-  LEGACY_BLOCK_HOST,
   managedFiles,
-  migrateBlockToAgentsMd,
   normalizeForLedger,
   noteRelocation,
   OXLINT_FILES,
@@ -36,9 +27,7 @@ import {
   reconcileRoots,
   relativePosix,
   renderContext,
-  reportBlockMigration,
   reportPrune,
-  resolvePeerFlags,
   resolvePlacement,
   resolveProjectDir,
   rootsNotices,
@@ -63,22 +52,8 @@ export type SyncOptions = {
 }
 
 /**
- * The nearest ANCESTOR of `dir` (exclusive) carrying a basalt manifest, or null.
- *
- * `resolveProjectDir` resolves to exactly one directory — `BASALT_CWD` when set, else the
- * invocation cwd — and never walks. The shape that produced this function is the one that resolver
- * doesn't cover: a consumer standing in `apps/dashboard`, the package that actually depends on
- * basalt-ui, whose install lives at the repo root above it. With nothing walking up, `sync` read
- * "no manifest here" as "nothing scaffolded yet" and wrote a complete second consumer beside the
- * real one.
- */
-/**
- * The sentence `sync` prints when the cwd carries no install but an ancestor does.
- *
- * Shared with `doctor` deliberately. The two commands already share `resolveProjectDir`, but not
- * the ADVICE: `sync` named the parent install (1.22.0's "stop scaffolding a second consumer" fix)
- * while `doctor`, in the same directory, kept prescribing `basalt-ui init` — so following doctor
- * literally performed the exact mistake that fix exists to prevent. One function, one sentence.
+ * The sentence `sync` and `doctor` both print when the cwd carries no install but an ancestor does
+ * (a package under a configured repo); one text, so neither prescribes a second `init`.
  */
 export function parentInstallAdvice(cwd: string, parent: string, verb: string): string {
   return (
@@ -87,6 +62,7 @@ export function parentInstallAdvice(cwd: string, parent: string, verb: string):
   )
 }
 
+/** The nearest ANCESTOR of `dir` (exclusive) carrying a basalt manifest, or null. */
 export function findManifestAbove(dir: string): string | null {
   let current = resolve(dir, '..')
   for (;;) {
@@ -104,11 +80,8 @@ export function findManifestAbove(dir: string): string | null {
  *   (a CI freshness gate), exit 0 when all current.
  * - `--force` overwrites locally-drifted files instead of skipping them.
  *
- * Runs against `resolveProjectDir(cwd)`, exactly as `check-theme` and `doctor` do — and then
- * REFUSES rather than scaffolding when the resolved project has no manifest. See
- * {@link findManifestAbove} for the failure that bought this: `sync` is the drift refresh and
- * `init` is the scaffold, so placing twenty files on a cwd that was never a consumer is a decision
- * `sync` does not get to make silently.
+ * Runs against `resolveProjectDir(cwd)` and REFUSES rather than scaffolding when that project has no
+ * manifest: `sync` refreshes, `init` scaffolds.
  */
 export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd()): number {
   const syncFlags = opts.flags ?? []
@@ -117,15 +90,8 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
   const cwd = project.dir
   noteRelocation('sync', project)
 
-  // Profile before the refusal, because in a tokens-only consumer the refusal's own advice is
-  // wrong: it names `basalt-ui init`, and `doctor` in the same directory at the same version says
-  // in so many words that init is NOT the fix there — it places a Mantine doctrine the consumer
-  // has no use for. Mirrors doctor's manifest row verbatim, and exits 0 so `sync --check` is
-  // wirable into a tokens-only repo's CI (the one drift gate every other consumer runs).
-  //
-  // DECLARED, never inferred — the same asymmetry check-theme applies, for the same reason: the
-  // answer SILENCES the whole reconciliation, and inferring it from a missing @mantine/core would
-  // turn a framework consumer that keeps Mantine in a sibling package into a silent no-op.
+  // Profile before the refusal: init is NOT the fix for a tokens-only consumer. Declared, never
+  // inferred (the answer silences the whole reconciliation); exits 0 so `sync --check` is wirable.
   if (declaredProfile(readBasaltConfig(cwd), syncFlags) === 'tokens-only') {
     console.log(
       `basalt-ui sync: ${MANIFEST_PATH}: n/a — a tokens-only consumer has no scaffold to ` +
@@ -135,12 +101,10 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
     return 0
   }
 
-  // The refusal runs BEFORE reconcileRoots, which WRITES `basalt.roots` into package.json — that
-  // key is half the damage: a second `basalt` block means check-theme scans a different tree
-  // depending on which directory it was invoked from.
+  // Refuse BEFORE reconcileRoots, which writes `basalt.roots` into package.json.
   if (!existsSync(resolve(cwd, MANIFEST_PATH))) {
     const elsewhere = findManifestAbove(cwd)
-    const wouldWrite = managedFiles(resolvePeerFlags(cwd, {}), resolvePlacement(cwd)).length
+    const wouldWrite = managedFiles(resolvePlacement(cwd)).length
     console.error(
       `✖ basalt-ui sync: no ${MANIFEST_PATH} at ${cwd} — refusing to scaffold. ` +
         `\`sync\` refreshes an EXISTING basalt install; creating one is \`basalt-ui init\`'s ` +
@@ -154,24 +118,12 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
     return 1
   }
 
-  // A block that cannot be moved safely refuses the whole run BEFORE reconcileRoots writes anything.
-  const blockProblem = blockMigrationProblem(cwd)
-  if (blockProblem !== null) {
-    console.error(`✖ basalt-ui sync: ${blockProblem}`)
-    return 1
-  }
-
   // Before renderContext, which reads `basalt.roots` for the roots-derived template variables.
   const rootsState = reconcileRoots(cwd, { write: opts.check !== true })
   const ctx = renderContext(cwd)
   const manifest = readManifest(cwd)
-  const peers = resolvePeerFlags(cwd, {})
   const placement = resolvePlacement(cwd)
-  const files = managedFiles(peers, placement)
-
-  // Before the loop: the block moved from CLAUDE.md to AGENTS.md, and the loop reads AGENTS.md.
-  // `--check` only reports it (and stays red until a real sync moves it).
-  const migration = migrateBlockToAgentsMd(cwd, manifest, { dryRun: opts.check === true })
+  const files = managedFiles(placement)
 
   let updated = 0
   // `created` and `recreated` were one counter, and `0 updated, 20 recreated` is what a full
@@ -288,16 +240,10 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
           `${retired.join(', ')} — run \`basalt-ui sync\`.`,
       )
     }
-    if (migration.pending) {
-      console.error(
-        `basalt-ui sync --check: the basalt block is still in ${LEGACY_BLOCK_HOST} — it now ` +
-          `lives in ${AGENTS_MD}. Run \`basalt-ui sync\` to move it.`,
-      )
-    }
     if (staleForCheck > 0) {
       console.error(`basalt-ui sync --check: ${staleForCheck} managed file(s) out of date.`)
     }
-    if (staleForCheck > 0 || migration.pending) return 1
+    if (staleForCheck > 0) return 1
     const n = placementSkips.length
     const skips = n === 0 ? '' : ` (${n} permanent placement skip(s) — --verbose for detail)`
     console.log(`✓ basalt-ui sync --check: all managed files current.${skips}`)
@@ -313,7 +259,6 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
       `${skippedDrift} skipped (drift), ${pruned.removed.length} retired.`,
   )
   reportPrune(pruned)
-  reportBlockMigration(migration, 'sync')
   if (driftLines.length > 0) {
     console.log('Locally-edited files were skipped (run with --force to overwrite):')
     for (const l of driftLines) console.log(l)

package/src/cli/tokens-css.ts

@@ -34,21 +34,9 @@ function generatedHeader(version: string, command: string, flags: string[]): str
 
 /**
  * Space- and number-normalize the argument list of a legacy color function so the emitted file
- * survives a normal repo's formatter.
- *
- * This is FORMATTING ONLY and deliberately the CLI's single deviation from "print exactly what
- * `buildPaletteCss` returned": `rgba(255,255,255,0.6)` and `rgba(255, 255, 255, 0.6)` are the same
- * colour, the shipped palette emits the first form on the dark side and the second on the light
- * side, and a consumer committing the output ate a lint-ignore entry for the difference. The token
- * VALUES are untouched — nothing here can change what basalt's tokens are.
- *
- * Trailing zeros go the same way and for the same reason: prettier rewrites `0.10` → `0.1`, so the
- * two `rgba(28, 25, 23, 0.10)` alphas in the light shadow tokens were the whole reason the one
- * framework-free consumer still could not lint its committed sheet — `--fix` and `tokens:css
- * --check` disagreed forever, and the lint-ignore entry survived two releases. Only a bare decimal
- * literal is touched (never a `%`, a `var()` or a unit), and `0.10`/`0.1` are the same number.
- *
- * Exported for tests, so the expectation can be computed rather than restated.
+ * survives a repo's formatter (`rgba(255,255,255,0.6)` and `rgba(255, 255, 255, 0.6)` are the same
+ * colour; `0.10` becomes `0.1`). FORMATTING ONLY: token values are untouched, and only a bare decimal
+ * literal is touched (never a `%`, a `var()` or a unit). Exported for tests.
  */
 export function normalizeColorFunctions(css: string): string {
   return css.replace(/\b(rgba?|hsla?)\(([^()]*)\)/g, (_match, fn: string, args: string) => {
@@ -116,19 +104,10 @@ function emitGeneratedCss(content: string, flags: string[], cwd: string, command
 }
 
 /**
- * tokens:css — emit the `--vx-*` stylesheet, optionally retargeted.
- *
- * The escape hatch from installing anything: a static site runs this once (`bunx basalt-ui
- * tokens:css --selector-attribute data-theme --out src/tokens.css`) and consumes basalt's token
- * system as plain CSS, with no package in its dependency tree at all. `basalt-ui/tokens.css` is the
- * same artifact for a consumer that does install; this command exists for the ones that shouldn't
- * have to just to change a selector.
- *
- * It parses flags and calls `buildPaletteCss` for the token VALUES — the CLI and the API must not
- * be able to disagree about what basalt's tokens are. What it adds is strictly file framing for an
- * artifact a consumer COMMITS: the `@generated` header (the guard's skip marker), a trailing
- * newline, and `rgba()` argument spacing. All three were reported by the one framework-free
- * consumer as the reasons the output could not simply be committed.
+ * tokens:css — emit the `--vx-*` stylesheet, optionally retargeted, for a static site that installs
+ * nothing (`bunx basalt-ui tokens:css --selector-attribute data-theme --out src/tokens.css`). Token
+ * VALUES come from `buildPaletteCss`, so the CLI and the API cannot disagree; the CLI adds only file
+ * framing for a committed artifact: the `@generated` header, a trailing newline, `rgba()` spacing.
  */
 export function tokensCss(flags: string[], cwd: string = process.cwd()): number {
   const attribute = flagValue(flags, '--selector-attribute')

package/src/commands/ShortcutsHelp.tsx

@@ -2,11 +2,11 @@
  * ShortcutsHelp — renders a keyboard shortcut reference list grouped by command group.
  *
  * Reads from the active command registry at render time via `toShortcutList()`. The same
- * Command.shortcut field also drives live key binding via useCommandHotkeys().
+ * Command.shortcut field also drives live key binding in `BasaltProvider`.
  *
  * Platform-aware label: 'Mod' → '⌘' on mac, 'Ctrl' elsewhere.
- * Platform detection defers to post-mount (useEffect) to avoid SSR/client hydration mismatch.
- * Server and first client render both use non-mac glyphs; the client updates after mount.
+ * Platform detection reads through `useSyncExternalStore` with a non-mac server snapshot, so SSR and
+ * the hydrating render agree and the client updates right after.
  *
  * @example
  * import { ShortcutsHelp } from 'basalt-ui/commands'
@@ -17,7 +17,7 @@
  * // With a custom title and max width:
  * <ShortcutsHelp title="Keyboard shortcuts" maw={480} />
  */
-import { useEffect, useState } from 'react'
+import { useSyncExternalStore } from 'react'
 import { Box, Group, Kbd, Stack, Text, Title } from '@mantine/core'
 import type { BasaltProps } from '../common/props'
 import { cx } from '../common/props'
@@ -25,6 +25,8 @@ import { toShortcutList } from './projectors'
 import { detectMac, parseShortcut } from './shortcut-format'
 import { VX } from '../tokens'
 
+const subscribeNever = (): (() => void) => () => {}
+
 // ── ShortcutsHelpProps ────────────────────────────────────────────────────────
 
 export type ShortcutsHelpProps = BasaltProps & {
@@ -78,11 +80,8 @@ export function ShortcutsHelp({
   style,
 }: ShortcutsHelpProps) {
   // Default false — SSR and first client render produce non-mac glyphs (no hydration mismatch).
-  // Post-mount effect flips to true on macOS, triggering a single client-only re-render.
-  const [isMac, setIsMac] = useState(false)
-  useEffect(() => {
-    setIsMac(detectMac())
-  }, [])
+  // The client snapshot (`detectMac`) takes over right after hydration, in a single re-render.
+  const isMac = useSyncExternalStore(subscribeNever, detectMac, () => false)
 
   const shortcuts = toShortcutList()
 

package/src/commands/define-commands.ts

@@ -1,9 +1,9 @@
 /**
  * define-commands — const-generic factory for typed command registries.
  *
- * Consumer defines their commands with defineCommands, augments BasaltRegister.commands, then uses
- * runCommand — unknown ids are tsc errors. The type slot gives the compile-time id union; the
- * module-level stash gives the runtime values (type augmentation is erased at runtime).
+ * Consumer defines their commands with defineCommands and augments BasaltRegister.commands.
+ * `BasaltProvider` reads the module-level stash for its Spotlight actions and hotkeys (type
+ * augmentation is erased at runtime; the stash is the live source).
  *
  * @example
  * // commands.ts (app-side)
@@ -16,12 +16,8 @@
  * declare module 'basalt-ui' {
  *   interface BasaltRegister { commands: typeof COMMANDS }
  * }
- *
- * // usage.ts
- * import { runCommand } from 'basalt-ui/commands'
- * runCommand('file:save')    // ✓ typed
- * runCommand('nonexistent')  // ✗ tsc error
  */
+import type { Hotkey } from '@tanstack/react-hotkeys'
 import type { ReactNode } from 'react'
 import type { Slot } from '../register'
 
@@ -36,7 +32,7 @@ import type { Slot } from '../register'
  * })
  */
 export type CommandRunContext = {
-  /** Close the command palette (if open) before executing. Injected by BasaltOverlays. */
+  /** Close the command palette (if open) before executing. Injected by the palette. */
   close?: () => void
 }
 
@@ -62,11 +58,12 @@ export type Command = {
   /** Optional icon (ReactNode — no @tabler/icons dependency per house rules). */
   icon?: ReactNode
   /**
-   * Optional keyboard shortcut string. Drives BOTH the ShortcutsHelp display AND live key
-   * binding via useCommandHotkeys() (which registers with @tanstack/react-hotkeys optional peer).
-   * Convention: 'Mod+S' (Mod = Cmd on mac, Ctrl elsewhere), 'Shift+Mod+P', etc.
+   * Optional keyboard shortcut, typed as the peer's `Hotkey` so a typo (`'Cmd+B'`) is a compile
+   * error. Drives BOTH the ShortcutsHelp display AND live key
+   * binding by `BasaltProvider` (through the @tanstack/react-hotkeys optional peer).
+   * Convention: 'Mod+S' (Mod = Cmd on mac, Ctrl elsewhere), 'Mod+Shift+P', etc.
    */
-  shortcut?: string
+  shortcut?: Hotkey
   /**
    * Optional predicate — when() returning false hides the command from the palette.
    * Useful for context-sensitive commands (e.g. "save" only when a form is dirty).
@@ -109,7 +106,7 @@ export type CommandId = Extract<keyof Commands, string>
 /**
  * Module-level runtime registry. The BasaltRegister type-slot gives the compile-time id union,
  * but the augmentation is erased at runtime — so defineCommands also stashes the runtime map here
- * for runCommand and the projectors to resolve Command objects. Call defineCommands once (the
+ * for the provider and the projectors to resolve Command objects. Call defineCommands once (the
  * app's single command registry); the last call wins.
  */
 let activeCommands: CommandMap = {}
@@ -118,10 +115,10 @@ let activeCommands: CommandMap = {}
 
 /**
  * Define a typed command map. Const-generic identity passthrough — preserves the exact literal
- * keys so `runCommand('nonexistent')` is a tsc error after augmenting BasaltRegister.
+ * keys so the id union is exact after augmenting BasaltRegister.
  *
- * Stashes the runtime map so `runCommand` and `toSpotlightActions` resolve correctly at runtime
- * (type augmentation is erased; the stash is the live source).
+ * Stashes the runtime map so the provider resolves commands at runtime (type augmentation is
+ * erased; the stash is the live source).
  *
  * @example
  * export const COMMANDS = defineCommands({
@@ -144,7 +141,7 @@ export function defineCommands<const T extends CommandMap>(spec: T): T {
  *
  * WARNING: defineCommand only TYPES a command — it does NOT register it into the runtime stash.
  * Only defineCommands(map) registers commands. Calling defineCommand alone means the command will
- * never appear in the palette or be reachable via runCommand.
+ * never appear in the palette or bind its shortcut.
  *
  * @example
  * const saveCmd = defineCommand({ label: 'Save', shortcut: 'Mod+S', run: () => save() })
@@ -154,31 +151,7 @@ export function defineCommand(cmd: Command): Command {
   return cmd
 }
 
-// ── runCommand ────────────────────────────────────────────────────────────────
-
-/**
- * Run a registered command by id. The id must be a key of the consumer's registered
- * `BasaltRegister.commands` map — any other string is a tsc error.
- *
- * Resolves the command's run function from the runtime stash (NOT from the type slot — that is
- * erased). Un-augmented (Commands = {}): CommandId = never → `runCommand` is effectively
- * uncallable. Augmented: only the registered keys are accepted.
- *
- * @example
- * runCommand('file:save')
- * await runCommand('data:sync', { close: () => closeModal() })
- */
-export function runCommand(id: CommandId, ctx?: CommandRunContext): void | Promise<void> {
-  const cmd = activeCommands[id as string]
-  if (cmd === undefined) {
-    if (process.env.NODE_ENV !== 'production')
-      console.warn(`[basalt] runCommand: no command registered for "${id}"`)
-    return
-  }
-  return cmd.run(ctx)
-}
-
-/** @internal — exposed for projectors.ts to iterate the runtime stash. Returns a readonly view. */
+/** @internal — exposed to the provider and projectors.ts to iterate the runtime stash. Returns a readonly view. */
 export function getActiveCommands(): Readonly<CommandMap> {
   return activeCommands
 }