basalt-ui 1.27.0 → 1.29.0

package/src/cli/tokens-css.ts

@@ -0,0 +1,252 @@
+/**
+ * `tokens:css` / `fonts:css` — split out of `src/cli/index.ts` (C2) so the dispatcher file holds
+ * routing only. Imports its shared plumbing (`readFrameworkVersion`, `packageRoot`, `readSource`,
+ * `readIfExists`) back from `./index`, this package's shared CLI helpers.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, relative, resolve } from 'node:path'
+
+import { GENERATED_HEADER_LINE } from '../guard'
+import { buildPaletteCss } from '../tokens'
+import { packageRoot, readFrameworkVersion, readIfExists, readSource } from './index'
+
+/** Read the value that follows a `--flag` in an argv slice; `undefined` when absent or terminal. */
+function flagValue(flags: string[], name: string): string | undefined {
+  const i = flags.indexOf(name)
+  if (i === -1) return undefined
+  const value = flags[i + 1]
+  return value === undefined || value.startsWith('--') ? undefined : value
+}
+
+/**
+ * The generated-file header: the canonical marker line (imported from the guard, which owns it),
+ * then the version + invocation that produced the file.
+ *
+ * Both lines are load-bearing, not decoration — `checkSource` only exempts a stylesheet whose line
+ * 1 is the marker verbatim AND whose line 2 parses as this provenance line. Reword either half and
+ * basalt starts reporting its own output again (116 findings in rollhook's token sheet).
+ */
+function generatedHeader(version: string, command: string, flags: string[]): string {
+  const shown = flags.filter((f) => f !== '--check')
+  const invocation = shown.length === 0 ? command : `${command} ${shown.join(' ')}`
+  return `${GENERATED_HEADER_LINE}\n/* basalt-ui ${version} — \`basalt-ui ${invocation}\` */\n`
+}
+
+/**
+ * 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.
+ */
+export function normalizeColorFunctions(css: string): string {
+  return css.replace(/\b(rgba?|hsla?)\(([^()]*)\)/g, (_match, fn: string, args: string) => {
+    const parts = args.split(',').map((part) => normalizeCssNumber(part.trim()))
+    return `${fn}(${parts.join(', ')})`
+  })
+}
+
+/** `0.10` → `0.1`, `1.0` → `1`; anything that is not a bare decimal literal is returned verbatim. */
+function normalizeCssNumber(arg: string): string {
+  if (!/^\d+\.\d+$/.test(arg)) return arg
+  return arg.replace(/\.?0+$/, '')
+}
+
+/** A scheme-class emission uses this sentinel attribute, then rewrites it to a class selector. */
+const SCHEME_CLASS_SENTINEL = 'data-basalt-scheme-class'
+
+/**
+ * Write (or drift-check) a generated stylesheet. `--check` makes no writes and exits 1 when the
+ * file on disk differs from what would be emitted — the CI gate for a committed `tokens:css`
+ * artifact, mirroring `sync --check`. Without `--out` the content goes to stdout unchanged.
+ */
+function emitGeneratedCss(content: string, flags: string[], cwd: string, command: string): number {
+  const out = flagValue(flags, '--out')
+  const check = flags.includes('--check')
+  if (out === undefined) {
+    if (check) {
+      console.error(
+        `${command}: --check needs --out <path> — there is nothing to compare stdout to.`,
+      )
+      return 1
+    }
+    process.stdout.write(content)
+    return 0
+  }
+  const target = isAbsolute(out) ? out : resolve(cwd, out)
+  const shown = relative(cwd, target) || target
+  if (check) {
+    const onDisk = readIfExists(target)
+    if (onDisk === null) {
+      console.error(
+        `✖ ${command} --check: ${shown} does not exist — run without --check to write it.`,
+      )
+      return 1
+    }
+    if (onDisk === content) {
+      console.log(`✓ ${command} --check: ${shown} is up to date.`)
+      return 0
+    }
+    const diskLines = onDisk.split('\n')
+    const wantLines = content.split('\n')
+    console.error(
+      `✖ ${command} --check: ${shown} differs from what \`basalt-ui ${command}\` emits today ` +
+        `(on disk ${diskLines.length} lines, emitted ${wantLines.length}) — re-run the same ` +
+        'command without --check and commit the result. A basalt-ui release moves the ' +
+        '`@generated` header line, so this is byte-exact — expect a no-op commit on every upgrade ' +
+        'that ships a committed generated sheet.',
+    )
+    return 1
+  }
+  mkdirSync(dirname(target), { recursive: true })
+  writeFileSync(target, content)
+  console.log(`wrote ${content.split('\n').length} lines → ${shown}`)
+  return 0
+}
+
+/**
+ * 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.
+ */
+export function tokensCss(flags: string[], cwd: string = process.cwd()): number {
+  const attribute = flagValue(flags, '--selector-attribute')
+  const schemeClass = flagValue(flags, '--selector-class')
+  const lightClass = flagValue(flags, '--light-class')
+  const darkValue = flagValue(flags, '--dark-value')
+  const lightValue = flagValue(flags, '--light-value')
+  const defaultScheme = flagValue(flags, '--default-scheme')
+
+  const only = flagValue(flags, '--only')
+
+  if (defaultScheme !== undefined && !['dark', 'light', 'none'].includes(defaultScheme)) {
+    console.error(
+      `tokens:css: --default-scheme must be dark, light or none (got '${defaultScheme}')`,
+    )
+    return 1
+  }
+  if (only !== undefined && !['core', 'all'].includes(only)) {
+    console.error(`tokens:css: --only must be core or all (got '${only}')`)
+    return 1
+  }
+  if (schemeClass !== undefined && attribute !== undefined) {
+    console.error(
+      'tokens:css: --selector-class and --selector-attribute are alternatives — pass one.',
+    )
+    return 1
+  }
+  if (schemeClass !== undefined && /[^\w-]/.test(schemeClass)) {
+    console.error(
+      `tokens:css: --selector-class must be a plain CSS class name (got '${schemeClass}')`,
+    )
+    return 1
+  }
+  if (lightClass !== undefined && /[^\w-]/.test(lightClass)) {
+    console.error(`tokens:css: --light-class must be a plain CSS class name (got '${lightClass}')`)
+    return 1
+  }
+
+  // A class selector is Tailwind's universal dark convention (`<html class="dark">`) and was
+  // reachable before only by parking dark on the bare `:root` via --default-scheme. `buildPaletteCss`
+  // emits attribute selectors, so the class form is produced by emitting against a sentinel
+  // attribute this CLI chose itself and rewriting exactly those selectors — a rewrite of strings
+  // the command generated deterministically, never of a token value.
+  const resolvedDarkValue = schemeClass !== undefined ? schemeClass : darkValue
+  const resolvedLightValue = schemeClass !== undefined ? (lightClass ?? 'light') : lightValue
+  const resolvedAttribute = schemeClass !== undefined ? SCHEME_CLASS_SENTINEL : attribute
+
+  const scheme = {
+    ...(resolvedAttribute === undefined ? {} : { attribute: resolvedAttribute }),
+    ...(resolvedDarkValue === undefined ? {} : { darkValue: resolvedDarkValue }),
+    ...(resolvedLightValue === undefined ? {} : { lightValue: resolvedLightValue }),
+  }
+
+  let css = buildPaletteCss({
+    ...(Object.keys(scheme).length === 0 ? {} : { scheme }),
+    ...(defaultScheme === undefined
+      ? {}
+      : { defaultScheme: defaultScheme as 'dark' | 'light' | 'none' }),
+    ...(flags.includes('--media-fallback') ? { mediaFallback: true } : {}),
+    ...(only === undefined ? {} : { only: only as 'core' | 'all' }),
+    // The tokens-only consumer is exactly the one who writes these names by hand, so they are also
+    // the one who wants the deprecated camelCase aliases gone — and this command is their only
+    // entry point. Without the flag the CLI and the API could disagree about what basalt's tokens
+    // are, which is the one thing this command is documented never to allow.
+    ...(flags.includes('--no-legacy-aliases') ? { legacyAliases: false } : {}),
+  })
+
+  if (schemeClass !== undefined) {
+    css = css.replace(
+      new RegExp(`\\[${SCHEME_CLASS_SENTINEL}='([\\w-]+)'\\]`, 'g'),
+      (_match, value: string) => `.${value}`,
+    )
+  }
+
+  const version = readFrameworkVersion(packageRoot())
+  const content = `${generatedHeader(version, 'tokens:css', flags)}${normalizeColorFunctions(css)}\n`
+  return emitGeneratedCss(content, flags, cwd, 'tokens:css')
+}
+
+/** Every `--basalt-font-*` declaration in the shipped stylesheet, in source order. */
+function readShippedFontDecls(pkgRoot: string): { name: string; value: string }[] {
+  const css = readSource(pkgRoot, 'dist/styles.css') ?? readSource(pkgRoot, 'src/styles.css')
+  if (css === null) return []
+  const decls: { name: string; value: string }[] = []
+  for (const match of css.matchAll(/(--basalt-font[\w-]*)\s*:\s*([^;]+);/g)) {
+    decls.push({
+      name: match[1] as string,
+      value: (match[2] as string).replace(/\s+/g, ' ').trim(),
+    })
+  }
+  return decls
+}
+
+/**
+ * fonts:css — emit the shipped `--basalt-font-*` stacks as plain CSS.
+ *
+ * The typeface half of the framework-free route, which had no supported path at all: `tokens.css`
+ * emits no font vars, `styles.css` is the one place the defaults live and a framework-free consumer
+ * is told not to import it, and `buildFontsCss` returns `''` unless the caller already knows the
+ * stacks. The one non-Mantine consumer lost its font identity entirely and hardcoded the stacks —
+ * which the theme guard then flagged as `raw-font-family`.
+ *
+ * The declarations are READ from the shipped stylesheet rather than restated here, so this command
+ * and `basalt-ui/styles.css` can never name different typefaces. Note the fonts themselves are
+ * `@fontsource-variable/*` packages: without them the stacks fall through to their own system
+ * fallbacks, which is the intended framework-free behaviour.
+ */
+export function fontsCss(flags: string[], cwd: string = process.cwd()): number {
+  const pkgRoot = packageRoot()
+  const decls = readShippedFontDecls(pkgRoot)
+  if (decls.length === 0) {
+    console.error(
+      'fonts:css: could not read the shipped font stacks from styles.css — this is a packaging ' +
+        'bug in basalt-ui, not a config error.',
+    )
+    return 1
+  }
+  const body = `:root {\n${decls.map((d) => `  ${d.name}: ${d.value};`).join('\n')}\n}\n`
+  const header = generatedHeader(readFrameworkVersion(pkgRoot), 'fonts:css', flags)
+  return emitGeneratedCss(`${header}${body}`, flags, cwd, 'fonts:css')
+}

package/src/commands/ShortcutsHelp.tsx

@@ -19,13 +19,15 @@
  */
 import { useEffect, useState } from 'react'
 import { Box, Group, Kbd, Stack, Text, Title } from '@mantine/core'
+import type { BasaltProps } from '../common/props'
+import { cx } from '../common/props'
 import { toShortcutList } from './projectors'
 import { detectMac, parseShortcut } from './shortcut-format'
 import { VX } from '../tokens'
 
 // ── ShortcutsHelpProps ────────────────────────────────────────────────────────
 
-export type ShortcutsHelpProps = {
+export type ShortcutsHelpProps = BasaltProps & {
   /** Section title. Default: 'Keyboard shortcuts'. */
   title?: string
   /** Max-width passthrough (Mantine style prop). */
@@ -69,7 +71,12 @@ function ShortcutRow({
  * @example
  * <ShortcutsHelp title="Keyboard shortcuts" />
  */
-export function ShortcutsHelp({ title = 'Keyboard shortcuts', maw }: ShortcutsHelpProps) {
+export function ShortcutsHelp({
+  title = 'Keyboard shortcuts',
+  maw,
+  className,
+  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)
@@ -94,7 +101,7 @@ export function ShortcutsHelp({ title = 'Keyboard shortcuts', maw }: ShortcutsHe
   }
 
   return (
-    <Box maw={maw}>
+    <Box maw={maw} className={cx(className)} {...(style !== undefined && { style })}>
       <Title order={5} mb="sm">
         {title}
       </Title>

package/src/commands/define-commands.ts

@@ -24,6 +24,7 @@
  */
 import type { ReactNode } from 'react'
 import type { Slot } from '../register'
+import { isDev } from '../common/is-dev'
 
 // ── Context ───────────────────────────────────────────────────────────────────
 
@@ -171,8 +172,7 @@ export function defineCommand(cmd: Command): Command {
 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}"`)
+    if (isDev()) console.warn(`[basalt] runCommand: no command registered for "${id}"`)
     return
   }
   return cmd.run(ctx)

package/src/commands/define-overlays.ts

@@ -26,7 +26,10 @@
  * overlays.open('nonexistent', {})                         // ✗ tsc error
  */
 import type { ReactNode } from 'react'
+import { useEffect } from 'react'
+import { missingLayer } from '../common/errors'
 import type { Slot } from '../register'
+import { isDev } from '../common/is-dev'
 
 // ── Lazy @mantine/modals resolution ───────────────────────────────────────────
 // @mantine/modals is an OPTIONAL peer — never imported at module evaluation time, so importing
@@ -43,6 +46,60 @@ function loadModals(): Promise<ModalsSingleton | undefined> {
   return modalsPromise
 }
 
+// ── Modals-layer availability ─────────────────────────────────────────────────
+
+/**
+ * How many `ModalsProvider`s are live right now — a COUNTER, not a flag, for the same reason
+ * `notifications/mount-guard.ts` counts: two overlapping mounts are normal (a route swap mounts the
+ * next `BasaltOverlays` before unmounting the previous one), and a last-write-wins boolean reports
+ * the teardown of the OLD one as "no layer" while the new one is serving.
+ *
+ * It is the availability test `overlays.confirm` runs, because `@mantine/modals`' imperative API is
+ * a window event bus: with nothing subscribed the dialog never appears and the promise never
+ * settles. The previous version read `BasaltOverlays`' own `modals` flag instead, which refused the
+ * call whenever a mounted shell passed `modals={false}` — even though the consumer had mounted their
+ * own `<ModalsProvider>`, which is the very remedy the error message names.
+ */
+let mountedModalsProviders = 0
+
+/**
+ * Declare that a `@mantine/modals` `<ModalsProvider>` is mounted and serving, and get back the
+ * function that retracts it. `BasaltOverlays` calls this for its own provider; a consumer mounting
+ * the provider THEMSELVES (with `<BasaltOverlays modals={false} />`, or with no `BasaltOverlays` at
+ * all) calls it too, or `overlays.confirm` cannot tell their provider from no provider and rejects.
+ *
+ * There is no way to detect the provider from outside React — its context is only readable through
+ * `useModals()`, and `confirm` is an imperative call with no component to read it from. So the
+ * registration is explicit.
+ *
+ * @example
+ * useEffect(() => registerModalsProvider(), [])
+ * // …beside your own <ModalsProvider> mount.
+ */
+export function registerModalsProvider(): () => void {
+  mountedModalsProviders++
+  let released = false
+  return () => {
+    // Idempotent: an effect cleanup React runs twice (StrictMode remount) must not drive the count
+    // below the number of providers actually on screen.
+    if (released) return
+    released = true
+    mountedModalsProviders--
+  }
+}
+
+/**
+ * Internal — `BasaltOverlays` registers its OWN lazy `ModalsProvider` here, and only when it
+ * actually renders one. Deliberately NOT on the `./commands` barrel (internal wiring only, same as
+ * `notifications/mount-guard`); the consumer-facing half is {@link registerModalsProvider}.
+ */
+export function useModalsLayer(enabled: boolean): void {
+  useEffect(() => {
+    if (!enabled) return
+    return registerModalsProvider()
+  }, [enabled])
+}
+
 // ── Overlay + OverlayMap ──────────────────────────────────────────────────────
 
 /**
@@ -138,6 +195,143 @@ export function defineOverlay<P = Record<string, unknown>>(overlay: Overlay<P>):
   return overlay
 }
 
+// ── confirm ───────────────────────────────────────────────────────────────────
+
+/** Options for {@link overlays.confirm} — a two-button dialog that resolves to the answer. */
+export type ConfirmOptions = {
+  /** Dialog title — the question itself ("Delete photo.jpg?"), not a category. */
+  title: ReactNode
+  /** Optional body under the title. A plain string is fine; a ReactNode renders as-is. */
+  body?: ReactNode
+  /** Confirm button label. Default: 'Confirm'. */
+  confirmLabel?: string
+  /** Cancel button label. Default: 'Cancel'. */
+  cancelLabel?: string
+  /** Paint the confirm button in the destructive tone (the theme's derived `red` family). */
+  danger?: boolean
+  /** Runs once, before the promise resolves `true`. */
+  onConfirm: () => void
+  /** Runs once on cancel, escape, click-outside or the close button — every non-confirm exit. */
+  onCancel?: () => void
+}
+
+/** Options for {@link overlays.confirmDelete} — the delete idiom over {@link ConfirmOptions}. */
+export type ConfirmDeleteOptions = {
+  /**
+   * The singular noun for what is being deleted — `'item'`, `'photo'`, `'API key'`. Pluralised by
+   * appending `s` when `count` is not 1; a noun that does not pluralise that way calls
+   * {@link overlays.confirm} directly with its own title.
+   */
+  subject: string
+  /** How many. Default: 1. */
+  count?: number
+  /** Runs once, before the promise resolves `true`. */
+  onConfirm: () => void
+}
+
+/**
+ * Open a confirm dialog and resolve to the user's answer — `true` on confirm, `false` on every
+ * other exit (cancel, escape, click-outside, the close button). `onConfirm`/`onCancel` fire exactly
+ * once each at most, before the promise settles.
+ *
+ * Rejects with a named `[basalt]` error when the modals layer cannot serve the dialog — the
+ * `@mantine/modals` peer is absent, or no `ModalsProvider` is registered as live (see
+ * {@link registerModalsProvider}). Both would otherwise leave the promise pending forever: the
+ * imperative API is a window event bus with nothing subscribed.
+ *
+ * @example
+ * if (await overlays.confirm({ title: 'Discard draft?', onConfirm: () => reset() })) navigate('/')
+ *
+ * @example
+ * await overlays.confirm({
+ *   title: 'Revoke access?',
+ *   body: 'The key stops working immediately.',
+ *   confirmLabel: 'Revoke',
+ *   danger: true,
+ *   onConfirm: () => revoke(),
+ * })
+ */
+async function confirm(options: ConfirmOptions): Promise<boolean> {
+  const {
+    title,
+    body,
+    confirmLabel = 'Confirm',
+    cancelLabel = 'Cancel',
+    danger = false,
+    onConfirm,
+    onCancel,
+  } = options
+
+  const modals = await loadModals()
+  if (modals === undefined) {
+    throw new Error(
+      missingLayer(
+        'overlays.confirm',
+        '@mantine/modals',
+        'install the @mantine/modals peer and mount <BasaltOverlays>',
+      ),
+    )
+  }
+  if (mountedModalsProviders === 0) {
+    throw new Error(
+      missingLayer(
+        'overlays.confirm',
+        'a mounted <ModalsProvider>',
+        'drop `modals={false}` from <BasaltOverlays>, or mount <ModalsProvider> yourself and call ' +
+          'registerModalsProvider() from an effect for as long as it is up',
+      ),
+    )
+  }
+
+  return new Promise<boolean>((resolve) => {
+    // Mantine fires onCancel AND onClose on the cancel button, and onClose alone on escape /
+    // click-outside / the X — so the answer is settled once here and every later edge is a no-op.
+    let settled = false
+    const settle = (confirmed: boolean): void => {
+      if (settled) return
+      settled = true
+      try {
+        if (confirmed) onConfirm()
+        else onCancel?.()
+      } finally {
+        resolve(confirmed)
+      }
+    }
+
+    modals.openConfirmModal({
+      title,
+      ...(body !== undefined && { children: body }),
+      labels: { confirm: confirmLabel, cancel: cancelLabel },
+      // The destructive tone is the theme's `red` family (derived from the palette, bound to the
+      // --vx-* status tokens by cssVariablesResolver) — never a raw color.
+      ...(danger && { confirmProps: { color: 'red' } }),
+      onConfirm: () => settle(true),
+      onCancel: () => settle(false),
+      onClose: () => settle(false),
+    })
+  })
+}
+
+/**
+ * The delete confirmation every app writes — `confirm` with the destructive tone, the `Delete`
+ * label and a counted title already filled in.
+ *
+ * @example
+ * overlays.confirmDelete({ subject: 'item', count: 3, onConfirm: () => removeSelected() })
+ * // → "Delete 3 items?"
+ */
+function confirmDelete(options: ConfirmDeleteOptions): Promise<boolean> {
+  const { subject, count = 1, onConfirm } = options
+  const what = count === 1 ? subject : `${count} ${subject}s`
+  return confirm({
+    title: `Delete ${what}?`,
+    body: 'This cannot be undone.',
+    confirmLabel: 'Delete',
+    danger: true,
+    onConfirm,
+  })
+}
+
 // ── overlays controller ───────────────────────────────────────────────────────
 
 /**
@@ -155,8 +349,13 @@ type OverlayProps<K extends OverlayKey> = Overlays extends { [_K in K]: Overlay<
  * quick-edit panels). For shareable/back-button/refreshable overlays use route masks via
  * ./router-tanstack.
  *
+ * `open` needs a REGISTERED overlay; `confirm`/`confirmDelete` need none — they are the two-button
+ * dialog every app was hand-writing as a registry entry.
+ *
  * @example
  * overlays.open('confirm:delete', { name: 'photo.jpg' })
+ * await overlays.confirm({ title: 'Discard draft?', danger: true, onConfirm: () => reset() })
+ * overlays.confirmDelete({ subject: 'item', count: 3, onConfirm: () => removeSelected() })
  * overlays.close()
  */
 export const overlays = {
@@ -173,7 +372,7 @@ export const overlays = {
   open<K extends OverlayKey>(key: K, props: OverlayProps<K>): void {
     const spec = activeOverlays[key as string]
     if (spec === undefined) {
-      if (process.env['NODE_ENV'] !== 'production')
+      if (isDev())
         console.warn(`[basalt] overlays.open: no overlay registered for "${String(key)}"`)
       return
     }
@@ -185,6 +384,22 @@ export const overlays = {
     )
   },
 
+  /**
+   * Open a confirm dialog and resolve to the answer — see {@link confirm}.
+   *
+   * @example
+   * const ok = await overlays.confirm({ title: 'Discard draft?', onConfirm: () => reset() })
+   */
+  confirm,
+
+  /**
+   * The one-line delete idiom over {@link confirm} — see {@link confirmDelete}.
+   *
+   * @example
+   * overlays.confirmDelete({ subject: 'item', count: 3, onConfirm: () => removeSelected() })
+   */
+  confirmDelete,
+
   /**
    * Close all open overlays (delegates to modals.closeAll()).
    *

package/src/commands/index.ts

@@ -19,7 +19,7 @@
  *   interface BasaltRegister { commands: typeof COMMANDS }
  * }
  *
- * // main.tsx — mount composable overlays (replaces <BasaltNotifications />):
+ * // main.tsx — mount composable overlays:
  * import { BasaltOverlays } from 'basalt-ui/commands'
  * import '@mantine/spotlight/styles.layer.css'
  * <BasaltProvider><BasaltOverlays><App /></BasaltOverlays></BasaltProvider>
@@ -28,6 +28,15 @@
  * import { runCommand } from 'basalt-ui/commands'
  * runCommand('file:save')
  *
+ * // usage.ts — the registry-free confirm dialog:
+ * import { overlays } from 'basalt-ui/commands'
+ * const ok = await overlays.confirm({ title: 'Discard draft?', onConfirm: () => reset() })
+ * overlays.confirmDelete({ subject: 'item', count: 3, onConfirm: () => removeSelected() })
+ *
+ * // Mounting ModalsProvider yourself instead of letting <BasaltOverlays> do it:
+ * import { registerModalsProvider } from 'basalt-ui/commands'
+ * useEffect(() => registerModalsProvider(), [])
+ *
  * // Open/close Spotlight programmatically:
  * import { openSpotlight, closeSpotlight } from 'basalt-ui/commands'
  * openSpotlight()
@@ -49,9 +58,12 @@ export {
   defineOverlays,
   defineOverlay,
   overlays,
+  registerModalsProvider,
   type Overlay,
   type OverlayMap,
   type OverlayKey,
+  type ConfirmOptions,
+  type ConfirmDeleteOptions,
 } from './define-overlays'
 
 // ── Projectors ────────────────────────────────────────────────────────────────
@@ -67,6 +79,15 @@ export {
   type HotkeyBinding,
 } from './projectors'
 
+// ── Imperative shell handles (setColorScheme/toggleSidebar) ──────────────────
+export {
+  setColorScheme,
+  toggleSidebar,
+  type ColorScheme,
+  type ColorSchemeSetter,
+  type SidebarToggle,
+} from './shell-bridge'
+
 // ── Shortcut format utils ─────────────────────────────────────────────────────
 export { parseShortcut, detectMac, formatShortcutDisplay } from './shortcut-format'