basalt-ui 1.28.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/define-commands.ts

@@ -24,7 +24,7 @@
  */
 import type { ReactNode } from 'react'
 import type { Slot } from '../register'
-import { isDev } from '../utils/is-dev'
+import { isDev } from '../common/is-dev'
 
 // ── Context ───────────────────────────────────────────────────────────────────
 

package/src/commands/define-overlays.ts

@@ -29,7 +29,7 @@ import type { ReactNode } from 'react'
 import { useEffect } from 'react'
 import { missingLayer } from '../common/errors'
 import type { Slot } from '../register'
-import { isDev } from '../utils/is-dev'
+import { isDev } from '../common/is-dev'
 
 // ── Lazy @mantine/modals resolution ───────────────────────────────────────────
 // @mantine/modals is an OPTIONAL peer — never imported at module evaluation time, so importing

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>
@@ -79,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'
 

package/src/commands/overlays-mount.tsx

@@ -2,10 +2,10 @@
  * overlays-mount — composable overlay mount for basalt-ui apps.
  *
  * `BasaltOverlays` bundles ModalsProvider, Spotlight, and Notifications into a single mount point.
- * Put it inside BasaltProvider, before the router. It replaces the standalone
- * `<BasaltNotifications />` from `basalt-ui/notifications` — do NOT mount both
- * `<BasaltOverlays notifications />` and `<BasaltNotifications />` in the same tree (double-mount
- * of `<Notifications />`).
+ * Put it inside BasaltProvider, before the router. It is the ONLY notifications mount — the
+ * standalone `basalt-ui/notifications` overlay it superseded is gone (C1 consolidation); mounting
+ * a second, hand-rolled `<Notifications />` alongside `<BasaltOverlays notifications />` still
+ * double-mounts the overlay and is still wrong for the same reason.
  *
  * Every layer — ModalsProvider included — mounts as a SIBLING of `children`, never as a wrapper:
  * see the comment in the component body (R1). `@mantine/modals`' imperative API (`modals.open*`,
@@ -33,8 +33,8 @@
  * code. The re-exported `openSpotlight` / `closeSpotlight` helpers delegate to this store.
  *
  * @example
- * // main.tsx — replace <BasaltNotifications /> with <BasaltOverlays>. Use the layered bundle —
- * // the unlayered one outranks basalt's `@layer basalt` styles regardless of specificity:
+ * // main.tsx — mount <BasaltOverlays>. Use the layered bundle — the unlayered one outranks
+ * // basalt's `@layer basalt` styles regardless of specificity:
  * import { BasaltOverlays } from 'basalt-ui/commands'
  * import '@mantine/spotlight/styles.layer.css'
  *
@@ -244,7 +244,7 @@ Object.assign(LazyNotifications, { displayName: 'LazyNotifications' })
 // ── NotificationsLayer (runs the shared duplicate-mount guard, F15) ───────────
 
 /** Wraps `LazyNotifications` so `useNotificationsMountGuard` only fires while this layer is
- * actually enabled — a sibling of `BasaltNotifications` importing the SAME shared counter. */
+ * actually enabled — the shared counter guards against any second `<Notifications />` mount. */
 function NotificationsLayer({
   notificationsProps,
 }: {
@@ -278,9 +278,7 @@ function HotkeysMount() {
  * `children`. All three layers are enabled by default; pass `false` to disable. A disabled layer's
  * optional peer is never imported.
  *
- * Mount exactly ONE BasaltOverlays per app. Do NOT combine with a standalone
- * `<BasaltNotifications />` from `basalt-ui/notifications` — that would double-mount
- * `<Notifications />`.
+ * Mount exactly ONE BasaltOverlays per app — a second instance double-mounts `<Notifications />`.
  *
  * @example
  * <BasaltProvider>

package/src/commands/shell-bridge.ts

@@ -0,0 +1,86 @@
+/**
+ * `setColorScheme`/`toggleSidebar` — imperative shell handles, wired automatically.
+ *
+ * Command bodies run OUTSIDE the React tree (a Spotlight action, a hotkey), so a `run: () =>
+ * ...`  has no hook access to `useMantineColorScheme()` or `BasaltShell`'s collapse state. Every
+ * consumer of `defineCommands` therefore hand-rolled the SAME "register a live setter ref, read
+ * it later" bridge per action — argo's own `lib/color-scheme-bridge.ts` / `lib/sidebar-bridge.ts`
+ * are the seed for this file, right down to the reason each is its OWN leaf module: `commands.tsx`
+ * imports the router, which imports the generated route tree, which imports every route file
+ * including the one that owns the shell — so a command file importing anything back out of the
+ * shell closes a real circular module dependency (surfaces as TS's "implicitly has type any…
+ * referenced in its own initializer"). A leaf with ZERO local imports is what both sides can
+ * depend on without re-closing that cycle (`register.ts`'s `Slot` doc has the type-level half of
+ * the same story for `commands`↔`overlays`).
+ *
+ * basalt registers BOTH setters itself — `BasaltProvider` calls {@link registerColorSchemeSetter}
+ * from inside `MantineProvider` (`provider/index.tsx`'s `BasaltBridge`), `BasaltShell` calls
+ * {@link registerSidebarToggle} (`shell/index.tsx`'s `ShellFrame`) — so a consumer's own
+ * `commands.tsx` needs no `__root.tsx` wiring at all, unlike argo's hand-rolled version: mount
+ * `BasaltProvider`/`BasaltShell` once, and `setColorScheme`/`toggleSidebar` just work.
+ *
+ * Last-registered wins, same "last call wins" rule `defineCommands`/`defineOverlays`'s own runtime
+ * stash documents — two overlapping mounts (a route swap) are normal, not a race to guard against.
+ *
+ * @example
+ * // commands.ts
+ * import { defineCommands, setColorScheme, toggleSidebar } from 'basalt-ui/commands'
+ * export const COMMANDS = defineCommands({
+ *   'theme:dark': { label: 'Dark theme', run: () => setColorScheme('dark') },
+ *   'ui:toggle-sidebar': { label: 'Toggle sidebar', shortcut: 'Mod+B', run: () => toggleSidebar() },
+ * })
+ */
+
+export type ColorScheme = 'light' | 'dark' | 'auto'
+export type ColorSchemeSetter = (scheme: ColorScheme) => void
+export type SidebarToggle = () => void
+
+let colorSchemeSetterRef: ColorSchemeSetter | null = null
+let sidebarToggleRef: SidebarToggle | null = null
+
+/** @internal called by `BasaltProvider`. Not part of the public API surface. */
+export function registerColorSchemeSetter(setter: ColorSchemeSetter | null): void {
+  colorSchemeSetterRef = setter
+}
+
+/** @internal called by `BasaltShell`. Not part of the public API surface. */
+export function registerSidebarToggle(toggle: SidebarToggle | null): void {
+  sidebarToggleRef = toggle
+}
+
+/**
+ * Set the color scheme from outside the React tree. A no-op (with a dev-only console warning)
+ * when no `BasaltProvider` is mounted yet — the same "not wired" shape `runCommand`/
+ * `overlays.open` already use for an unregistered id.
+ *
+ * @example
+ * setColorScheme('dark')
+ */
+export function setColorScheme(scheme: ColorScheme): void {
+  if (colorSchemeSetterRef === null) {
+    if (process.env['NODE_ENV'] !== 'production') {
+      // eslint-disable-next-line no-console -- dev-only diagnostic, mirrors runCommand's own
+      console.warn('[basalt] setColorScheme: no BasaltProvider is mounted yet')
+    }
+    return
+  }
+  colorSchemeSetterRef(scheme)
+}
+
+/**
+ * Toggle `BasaltShell`'s desktop sidebar collapse from outside the React tree. A no-op (with a
+ * dev-only console warning) when no `BasaltShell` is mounted yet.
+ *
+ * @example
+ * toggleSidebar()
+ */
+export function toggleSidebar(): void {
+  if (sidebarToggleRef === null) {
+    if (process.env['NODE_ENV'] !== 'production') {
+      // eslint-disable-next-line no-console -- dev-only diagnostic, mirrors runCommand's own
+      console.warn('[basalt] toggleSidebar: no BasaltShell is mounted yet')
+    }
+    return
+  }
+  sidebarToggleRef()
+}

package/src/common/errors.ts

@@ -71,3 +71,73 @@ export function duplicateMount(component: string): string {
     'more than one instance is mounted at once — mount exactly one, at the app root.',
   )
 }
+
+// ── Transport-agnostic error decoding ────────────────────────────────────────────────────────────
+//
+// Deliberately in this module, with NO `@tanstack/react-query` import — `dashboard/query-state.tsx`
+// renders server messages and must not drag the query peer into the root barrel's graph to do it.
+
+/**
+ * The HTTP status behind a thrown envelope (Eden Treaty's `{ status, value }`, a `Response`-shaped
+ * throw), when there is one. Use it to BRANCH — 404 → "not found" copy — rather than to build a
+ * message; `toErrorMessage` already folds the status into its text when the body says nothing.
+ *
+ * @example
+ * if (errorStatus(err) === 404) return <EmptyState title="Gone" />
+ */
+export function errorStatus(err: unknown): number | undefined {
+  if (err === null || typeof err !== 'object') return undefined
+  const status = (err as { status?: unknown }).status
+  return typeof status === 'number' ? status : undefined
+}
+
+/** Strings that technically decoded but tell a reader nothing. `JSON.stringify` produces most. */
+const UNUSABLE_MESSAGES = new Set(['', '{}', '[]', 'null', 'undefined', '[object Object]'])
+
+function decodeError(err: unknown): string {
+  if (err instanceof Error) return err.message
+  if (typeof err === 'string') return err
+  if (typeof err === 'object' && err !== null) {
+    const obj = err as Record<string, unknown>
+    if (typeof obj['message'] === 'string') return obj['message']
+    // Eden-style { value: ... } or { status, value } envelopes — unwrap one level.
+    if ('value' in obj) return decodeError(obj['value'])
+  }
+  try {
+    return JSON.stringify(err) ?? ''
+  } catch {
+    return String(err)
+  }
+}
+
+/**
+ * Extract a human-readable message from an unknown thrown value (e.g. the raw Eden envelope
+ * thrown by `unwrap`). Removes the 8-line three-branch boilerplate consumers duplicate.
+ *
+ * Resolution order:
+ *   1. `Error` instance       → err.message
+ *   2. `{ message: string }`  → message (Eden / Elysia error shape)
+ *   3. `{ value: ... }`       → recursively (Eden nested value envelope)
+ *   4. plain string           → itself
+ *   5. anything else          → `JSON.stringify`
+ *
+ * **If that yields nothing a human can read** (`''`, `'{}'`, `'[]'`, `'null'`, `'undefined'`,
+ * `'[object Object]'` — the shapes `JSON.stringify` produces for an opaque envelope) the `fallback`
+ * is returned instead, with `(HTTP <status>)` appended when the envelope carries one. Without that
+ * guard the caller renders a literal `{}` at the user, or — for `toErrorMessage(undefined)` —
+ * the actual value `undefined`, since `JSON.stringify(undefined)` is not a string at all.
+ *
+ * @example
+ * try {
+ *   await unwrap(api.resource.post({ body }))
+ * } catch (e) {
+ *   toast(toErrorMessage(e, 'Could not create share'))   // → "slug already in use"
+ *                                                        // → "Could not create share (HTTP 502)"
+ * }
+ */
+export function toErrorMessage(err: unknown, fallback = 'The request failed.'): string {
+  const decoded = decodeError(err).trim()
+  if (!UNUSABLE_MESSAGES.has(decoded)) return decoded
+  const status = errorStatus(err)
+  return status === undefined ? fallback : `${fallback} (HTTP ${status})`
+}

package/src/common/index.ts

@@ -19,3 +19,5 @@ export {
 } from './errors'
 export { useValidateProps, assertRequiredProps, resetValidatedProps } from './validate'
 export { scrollParentOf, SCROLLPORT_ATTRIBUTE } from './scroll-parent'
+export { isDev } from './is-dev'
+export { MOTION_DURATION, MOTION_EASE_STANDARD, MOTION_SPRING } from './motion'

package/src/common/props.ts

@@ -60,7 +60,7 @@ export type ToneWithNeutral = Tone | 'neutral'
  * twice — `WidgetHeaderTier` stays the name on the public barrel; `Tier` is what `common`-aware
  * code spells. Type-only, so this file emits no runtime edge into the Mantine-coupled half.
  */
-export type { WidgetHeaderTier as Tier } from '../widget-header/widget-header'
+export type { WidgetHeaderTier as Tier } from '../dashboard/widget-header'
 
 /**
  * The class joiner. Replaces the `[a, b].filter(Boolean).join(' ')` spelled out in seven files

package/src/common/validate.ts

@@ -7,7 +7,7 @@
  * mean warns once in dev and renders on (`useValidateProps`).
  */
 import { useEffect } from 'react'
-import { isDev } from '../utils/is-dev'
+import { isDev } from './is-dev'
 import { requiredProp } from './errors'
 
 /** A check returns the message(s) it has, or nothing. `null`/`undefined` entries are ignored. */

package/src/content/markdown.tsx

@@ -101,10 +101,9 @@ export type MarkdownProps = {
    * default to same-origin `['/']`; `'trusted'` (your own authored content) keeps
    * `['https://', '/']`. An explicit `allowedImagePrefixes` always wins over both.
    *
-   * Default: `'untrusted'` when `streaming` is set, `'trusted'` otherwise. That default only
-   * preserves the pre-1.12 fail-safe — it is NOT the policy. Settledness has nothing to do with
-   * trust: a FINISHED agent message is still model-generated, so any surface rendering agent text
-   * must pin `contentTrust="untrusted"` explicitly rather than lean on `streaming`.
+   * Default: `'trusted'`. Settledness has nothing to do with trust: a FINISHED agent message is
+   * still model-generated, so any surface rendering agent text must pin `contentTrust="untrusted"`
+   * explicitly rather than lean on `streaming`.
    */
   readonly contentTrust?: MarkdownContentTrust
   /**
@@ -618,10 +617,7 @@ export function Markdown({
   density = 'article',
   measure,
   streaming = false,
-  // `streaming` as the trust DEFAULT is backward compatibility only (pre-1.12 the image policy was
-  // read straight off `streaming`, so dropping it would silently widen every existing streaming
-  // call site). It is a floor, never the policy — see the prop's JSDoc.
-  contentTrust = streaming ? 'untrusted' : 'trusted',
+  contentTrust = 'trusted',
   components,
   fenceRenderers,
   sanitizeSchema,

package/src/controls/actions.tsx

@@ -16,7 +16,7 @@ import { ActionIcon, Button, Group, Menu } from '@mantine/core'
 import { createContext, isValidElement, useContext, useEffect } from 'react'
 import type { ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
-import type { NavAnchor } from '../nav/types'
+import type { NavAnchor } from '../shell/nav-types'
 import type { AnyNavLink } from '../router-tanstack/nav'
 import { IconSlot } from '../theme/icon-slot'
 import { ControlGroup } from './control-group'

package/src/controls/panel-row.tsx

@@ -28,7 +28,7 @@ import type { ReactNode, RefObject } from 'react'
 import { cx } from '../common/props'
 import type { BasaltProps } from '../common/props'
 import { CtlSlot } from '../theme'
-import { InfoGlyph } from '../widget-header/widget-header'
+import { InfoGlyph } from '../dashboard/widget-header'
 import classes from './panel-row.module.css'
 
 /**

package/src/controls/range-filter.tsx

@@ -32,7 +32,7 @@ import { useEffect, useRef, useState } from 'react'
 import type { ComponentType, ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import { isDev } from '../utils/is-dev'
+import { isDev } from '../common/is-dev'
 import type { FieldHandle, RangeField, RangeValue } from '../state'
 import classes from './controls.module.css'
 import { useFilterRegistration, useFilterSurface } from './filter-context'