basalt-ui 1.41.0 → 2.0.0

package/src/table/index.ts

@@ -0,0 +1,18 @@
+/**
+ * ./table — BasaltDataTable: a sortable data table over @tanstack/react-table v9, rendered with
+ * Mantine primitives. Opt-in chrome: a search/facet toolbar, a pagination bar (client-side or
+ * server-driven) and sticky column pinning. `createColumnHelper` is basalt's own, bound to the
+ * table's feature set — no TanStack hook, feature or row-model symbol leaves this subpath.
+ *
+ * Optional peer: @tanstack/react-table 9.2.8 (exact).
+ *
+ * @example
+ * import { BasaltDataTable, createColumnHelper } from 'basalt-ui/table'
+ * type Row = { name: string; score: number }
+ * const col = createColumnHelper<Row>()
+ * const columns = [col.accessor('name', { header: 'Name' }), col.accessor('score', { header: 'Score' })]
+ * <BasaltDataTable data={rows} columns={columns} enableGlobalFilter enablePagination />
+ */
+
+export { BasaltDataTable } from './data-table'
+export { createColumnHelper } from './table-features'

package/src/table/table-features.ts

@@ -0,0 +1,102 @@
+/**
+ * The ONE module-scope Table v9 feature set `BasaltDataTable` runs on, and the basalt-owned
+ * `createColumnHelper` bound to it. Nothing here but `createColumnHelper` leaves `./table`: the
+ * feature set, `useTable` and the row-model factories are implementation, and a consumer never
+ * spells `<TFeatures, TData>` (`docs/V2-SPEC.md` § 8).
+ */
+import {
+  columnFilteringFeature,
+  columnPinningFeature,
+  columnSizingFeature,
+  columnVisibilityFeature,
+  createColumnHelper as tanstackColumnHelper,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  filterFn_includesString,
+  globalFilteringFeature,
+  metaHelper,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  sortFn_alphanumeric,
+  sortFn_basic,
+  sortFn_datetime,
+  sortFn_text,
+  tableFeatures,
+} from '@tanstack/react-table'
+import type { ColumnDef, ColumnHelper, RowData } from '@tanstack/react-table'
+
+/** Horizontal alignment of a column's header AND its cells. */
+export type DataTableAlign = 'left' | 'center' | 'right'
+
+/**
+ * What a column def's `meta` may carry. Registered per table through `columnMeta: metaHelper<…>()`
+ * rather than a global `declare module '@tanstack/react-table'`, so `meta: { aling: 'right' }` is a
+ * compile error (excess-property check on the literal) and nothing leaks into a consumer's own
+ * TanStack types. A wrong align VALUE that reaches runtime still throws at render.
+ */
+export type BasaltColumnMeta = {
+  align?: DataTableAlign
+  /**
+   * Opt OUT of the automatic mono-numeral cell style. The table applies it whenever the cell's
+   * raw value is a number — which is right for a plain figure and wrong for a numeric accessor
+   * whose `cell` renders its own chrome (a coloured `Text`, a `Badge`, a sparkline), because the
+   * `<td>`'s mono font then overrides what the cell asked for.
+   */
+  numeral?: boolean
+  /**
+   * Fold priority for the measured column fold (`docs/CONTROLS-SPEC.md` §2): once the
+   * table no longer fits its wrapper, the HIGHEST-numbered priority column folds first, moving
+   * into a per-row disclosure instead of forcing the table into horizontal scroll. Unset columns
+   * fall back to their declared position, so a bare `<BasaltDataTable data columns />` folds its
+   * LAST column first — nothing regresses with no `meta.priority` set anywhere. See `foldOrder`.
+   */
+  priority?: number
+}
+
+/**
+ * Every row model is registered (v9 has no per-render `getXRowModel` switch); the table bypasses the
+ * ones a prop turns off through TanStack's `manual*` flags. `sortFns` is load-bearing: v9 falls back
+ * to `basic` for an unregistered sort function with only a dev warning, which sorts `Project 10`
+ * before `Project 2`. `columnSizingFeature` is too — `column.getStart`/`getAfter` live there, and
+ * sticky pinning reads them.
+ */
+export const basaltTableFeatures = tableFeatures({
+  rowSortingFeature,
+  columnFilteringFeature,
+  globalFilteringFeature,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  columnSizingFeature,
+  columnPinningFeature,
+  columnVisibilityFeature,
+  sortedRowModel: createSortedRowModel(),
+  filteredRowModel: createFilteredRowModel(),
+  paginatedRowModel: createPaginatedRowModel(),
+  sortFns: {
+    alphanumeric: sortFn_alphanumeric,
+    text: sortFn_text,
+    datetime: sortFn_datetime,
+    basic: sortFn_basic,
+  },
+  filterFns: { includesString: filterFn_includesString },
+  columnMeta: metaHelper<BasaltColumnMeta>(),
+})
+
+export type BasaltTableFeatures = typeof basaltTableFeatures
+
+/**
+ * A column def of `BasaltDataTable`'s feature set; the cell value varies per column, hence the `any`.
+ * Build columns with `createColumnHelper` below — hand-typing this is not the supported path.
+ */
+// oxlint-disable-next-line typescript/no-explicit-any -- TanStack-idiomatic heterogeneous column array
+export type BasaltColumnDef<T extends RowData> = ColumnDef<BasaltTableFeatures, T, any>
+
+/**
+ * Typed accessor builder for `BasaltDataTable` columns: `col.accessor('field', …)` columns sort by
+ * value. One generic, the row type — the feature set is basalt's.
+ */
+export function createColumnHelper<T extends RowData>(): ColumnHelper<BasaltTableFeatures, T> {
+  return tanstackColumnHelper<BasaltTableFeatures, T>()
+}

package/src/telemetry.ts

@@ -0,0 +1,110 @@
+/**
+ * The telemetry seam (V2-SPEC § 7). Basalt emits typed events through one sink,
+ * `BasaltProvider telemetry`, and has no OTel dependency; the consumer maps events to its own SDK.
+ *
+ * Events carry ids, hashes, counts and durations only — never an error object, message, stack,
+ * search param or query data. A `failed: true` event additionally carries `exception.type` and
+ * `basalt.error.kind`; a `failed: false` event carries neither, and the types enforce both ways.
+ */
+import { createContext } from 'react'
+import type { ThreadStatus } from './agent/thread'
+
+/** Epoch ms (`performance.timeOrigin + performance.now()`). */
+type At = { start: number }
+/** `start` plus a duration in ms. */
+type Span = At & { duration: number }
+
+/** The error family, or an `AgentError` kind (W8) — closed. */
+type ErrorKind =
+  | 'route'
+  | 'query'
+  | 'mutation'
+  | 'render'
+  | 'window'
+  | 'unhandledrejection'
+  | 'http'
+  | 'stream'
+  | 'server'
+  | 'aborted'
+
+type Failure = { 'exception.type': string; 'basalt.error.kind': ErrorKind }
+type Ok<T, A> = Span & { type: T; failed: false; attributes: A }
+type Err<T, A, S = At> = S & { type: T; failed: true; attributes: A & Failure }
+
+type RouteAttrs = {
+  'basalt.route.id': string
+  'basalt.route.from': string
+  /** Pathname, never search. */
+  'url.path': string
+}
+
+type ChatAttrs = {
+  'basalt.chat.thread_id': string
+  'basalt.chat.ttft_ms': number
+  'basalt.chat.parts': number
+  'basalt.chat.status': ThreadStatus
+}
+
+/**
+ * Closed union: switch on `type`/`failed` and end with `default: return event satisfies never`.
+ *
+ * @example
+ * export function telemetry(e: BasaltEvent): void {
+ *   const span = tracer.startSpan(e.type, { startTime: e.start, attributes: { ...e.attributes } })
+ *   if (e.failed) span.setStatus({ code: SpanStatusCode.ERROR })
+ *   span.end('duration' in e ? e.start + e.duration : e.start)
+ * }
+ */
+export type BasaltEvent =
+  | Ok<'route.navigate', RouteAttrs>
+  | Err<'route.error', { 'basalt.route.id': string }>
+  | Err<'query.error', { 'basalt.query.hash': string; 'basalt.query.failure_count': number }>
+  | Err<'mutation.error', { 'basalt.mutation.key': string }>
+  | Err<'render.error', { 'basalt.error.boundary': 'root' }>
+  | Err<'window.error', { 'basalt.error.source': 'error' | 'unhandledrejection' }>
+  | Ok<'chat.turn', ChatAttrs>
+  | Err<'chat.turn', ChatAttrs, Span>
+
+export type Telemetry = (event: BasaltEvent) => void
+
+export const now = (): number => performance.timeOrigin + performance.now()
+
+/** `error.name`, `'Error'` for a non-`Error` throw. */
+export const errorName = (error: unknown): string => (error instanceof Error ? error.name : 'Error')
+
+/**
+ * Wrap a sink so it is called synchronously and a throwing sink never breaks a render. No sink, no
+ * events.
+ */
+export function createEmitter(sink: Telemetry | undefined): Telemetry {
+  if (sink === undefined) return noop
+  return (event) => {
+    try {
+      sink(event)
+    } catch {
+      // a throwing sink must never break the app (§ 7 delivery rules)
+    }
+  }
+}
+
+function noop(): void {}
+
+/**
+ * The provider's wrapped emitter, for hooks that emit their own events (`useAgentThreadRuns`'
+ * `chat.turn`). `undefined` outside a `BasaltProvider`, where such a hook emits nothing.
+ */
+export const TelemetryContext = createContext<Telemetry | undefined>(undefined)
+
+/** The event sink of the provider mounted on a router, read by `createBasaltRouter`'s `onCatch`. */
+const routerSinks = new WeakMap<object, Telemetry>()
+
+export function bindRouterTelemetry(router: object, emit: Telemetry): () => void {
+  routerSinks.set(router, emit)
+  return () => {
+    if (routerSinks.get(router) === emit) routerSinks.delete(router)
+  }
+}
+
+export function routerTelemetry(router: object): Telemetry {
+  return routerSinks.get(router) ?? noop
+}

package/src/theme/index.ts

@@ -81,9 +81,9 @@ import {
 import type { PaletteData, RadiusValues, SpaceValues } from '../tokens/palette'
 import { DEFAULT_DERIVE_CONFIG, isDefaultDeriveConfig, resolveDeriveConfig } from '../tokens/derive'
 import type { DeriveConfig } from '../tokens/derive'
-import { pxRem, VX } from '../tokens'
+import { pxRem, VX } from '../tokens/core'
 import { SIZE_CLASS_BREAKPOINTS } from '../tokens/size-classes'
-import type { BasaltFontsConfig } from '../tokens'
+import type { BasaltFontsConfig } from '../tokens/core'
 import controlsClasses from './controls.module.css'
 import floatingClasses from './floating.module.css'
 import navLinkClasses from './nav-link.module.css'
@@ -92,12 +92,12 @@ import timelineClasses from './timeline.module.css'
 import { HIT_ATTR } from './ctl-theme'
 
 /**
- * The `fonts` option's resolved shape — defined in `basalt-ui/tokens` (`BasaltFontsConfig`,
- * paired with its pure builder `buildFontsCss` there); re-exported here since
+ * The `fonts` option's resolved shape — defined in `../tokens/core` (`BasaltFontsConfig`, paired
+ * with its pure builder `buildFontsCss` there, internal to the package); re-exported here since
  * `CreateBasaltThemeOptions.fonts` below is its primary production entry point. See
  * {@link CreateBasaltThemeOptions.fonts}.
  */
-export type { BasaltFontsConfig } from '../tokens'
+export type { BasaltFontsConfig } from '../tokens/core'
 
 // The active resolved SpaceValues off the running theme (as opposed to the static level-0
 // snapshot) — see its own doc comment for why it lives here rather than in `tokens/`.
@@ -110,11 +110,10 @@ export { useBasaltSpacing } from './use-basalt-spacing'
 export { CTL_THEME, CtlSlot, type CtlSlotProps } from './ctl-theme'
 
 // `ThemeToggle` moved into this directory (C1 consolidation, merging the former `theme-toggle/`
-// dir) but is deliberately NOT re-exported from this barrel: it imports `motion/react` eagerly,
-// and this file resolves from `./controls` (via `CtlSlot`) among others — re-exporting it here
-// would make `motion` a hard transitive peer of every consumer of this barrel, not just of
-// `ThemeToggle` itself. The root barrel (`src/index.ts`) imports it straight from
-// `./theme/theme-toggle`, unchanged from before the merge.
+// dir) and is deliberately NOT re-exported from this barrel: the root barrel (`src/index.ts`) imports
+// it straight from `./theme/theme-toggle`, which keeps it out of the `./controls` graph (this file
+// resolves from `./controls` via `CtlSlot`). It no longer imports `motion/react` (V2-SPEC § 5), so
+// that is no longer a peer concern, only a graph-size one.
 
 // Typed `theme.other.basaltDerive` / `theme.other.basaltFonts` / `theme.other.basaltRadius` /
 // `theme.other.basaltDensity` reads (Mantine's `MantineThemeOther` ships an index signature, so
@@ -447,6 +446,8 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
     // Mantine's dark `--mantine-color-{c}-text`, which is hardcoded to shade 4 = `ACCENT.accent.dark`.
     primaryShade: 6,
     autoContrast: true,
+    // V2-SPEC § 5: Mantine's own transitions (modal, drawer, popover, menu) follow the OS setting.
+    respectReducedMotion: true,
     luminanceThreshold: 0.45,
     // Force the `light` variant to a faint, AA-legible tint in both schemes (see resolver above).
     variantColorResolver: basaltVariantColorResolver,
@@ -1433,6 +1434,12 @@ function ctlSizeVars(): Record<string, string> {
   }
 }
 
+/** `radius` knob: an integer level, so an out-of-range value is a tsc error (V2-SPEC §3). */
+export type BasaltRadiusLevel = -5 | -4 | -3 | -2 | -1 | 0 | 1 | 2 | 3 | 4 | 5
+
+/** `density` knob: an integer level, so an out-of-range value is a tsc error (V2-SPEC §3). */
+export type BasaltDensityLevel = -3 | -2 | -1 | 0 | 1 | 2 | 3
+
 /**
  * Build the `cssVariablesResolver` bound to a given palette `data` — the derive-config-dependent
  * half of the fallback hexes below (see `buildTheme` above for the same split on `theme.colors`).
@@ -1444,9 +1451,9 @@ function ctlSizeVars(): Record<string, string> {
  * `BasaltBridge`'s injected `<style>` (the palette CSS built from the SAME resolved config, keyed
  * by `theme.other.basaltDerive`), which wins the cascade over the resolver's inline fallback hexes.
  * Limitation: `injectPalette={false}` combined with a custom `derive` therefore leaves the
- * resolver's fallback hexes at the shipped defaults — a consumer taking over palette injection
- * (SSR/head) with a non-default derive config must also emit `buildPaletteCss(opts, buildPaletteData(config))`
- * themselves, or those fallbacks silently mismatch the intended identity.
+ * resolver's fallback hexes at the shipped defaults, silently mismatching the intended identity.
+ * `buildPaletteData` is not public, so a consumer with a non-default derive config keeps
+ * `injectPalette` on.
  */
 function buildCssVariablesResolver(data: PaletteData): CSSVariablesResolver {
   const { INK, NEUTRAL, SURFACE } = data
@@ -1575,7 +1582,7 @@ export type CreateBasaltThemeOptions = {
    * @example
    * createBasaltTheme(undefined, { radius: 2 })
    */
-  radius?: number
+  radius?: BasaltRadiusLevel
 
   /**
    * Retune spacing DENSITY from a single integer level in `[-3, 3]` (default `0` = the shipped
@@ -1598,23 +1605,7 @@ export type CreateBasaltThemeOptions = {
    * @example
    * createBasaltTheme(undefined, { density: -2 })
    */
-  density?: number
-
-  /**
-   * Input sizing for the platform the app runs on. `'touch'` (default) keeps the shipped identity:
-   * `md` inputs (42px) with the 16px font floor that stops iOS Safari's focus-zoom. `'desktop'` is
-   * for an app that never runs in a mobile browser (a Tauri/Electron shell): the Input family
-   * (`TextInput`, `NumberInput`, `PasswordInput`, `Select`, `Textarea`, `Input`) defaults to
-   * Mantine's `sm` (36px, `--vx-text-sm` font) and the provider drops the 16px floor, so every
-   * input Mantine ships — `MultiSelect`/`TagsInput`/pills included, they already default to `sm` —
-   * renders at its own size. An explicit `size` prop still wins. Stashed on
-   * `theme.other.basaltInputs` (only when non-default); `BasaltProvider` emits the floor override,
-   * so `injectPalette={false}` also opts it out.
-   *
-   * @example
-   * createBasaltTheme(undefined, { inputs: 'desktop' })
-   */
-  inputs?: 'touch' | 'desktop'
+  density?: BasaltDensityLevel
 }
 
 /**
@@ -1627,20 +1618,6 @@ function hasFontsConfig(fonts: BasaltFontsConfig | undefined): fonts is BasaltFo
   return fonts !== undefined && Object.values(fonts).some((value) => value !== undefined)
 }
 
-/** `{ inputs: 'desktop' }` — see {@link CreateBasaltThemeOptions.inputs}. Merged AFTER the base
- * theme, so `defaultProps.size: 'sm'` replaces the base's `'md'` and `other` deep-merges. */
-const DESKTOP_INPUTS_THEME: MantineThemeOverride = {
-  components: {
-    Input: Input.extend({ defaultProps: { size: 'sm' } }),
-    TextInput: TextInput.extend({ defaultProps: { size: 'sm' } }),
-    NumberInput: NumberInput.extend({ defaultProps: { size: 'sm' } }),
-    PasswordInput: PasswordInput.extend({ defaultProps: { size: 'sm' } }),
-    Select: Select.extend({ defaultProps: { size: 'sm' } }),
-    Textarea: Textarea.extend({ defaultProps: { size: 'sm' } }),
-  },
-  other: { basaltInputs: 'desktop' },
-}
-
 /**
  * Build the Basalt theme, optionally merged with consumer overrides. Overrides win on conflict
  * (Mantine `mergeThemeOverrides` is last-wins), so a consumer can retune any field without
@@ -1677,7 +1654,6 @@ export function createBasaltTheme(
   const spaceValues = deriveSpacing(densityLevel)
   const isDefaultDensity = densityLevel === 0
   const isDefaultDerive = isDefaultDeriveConfig(resolvedConfig)
-  const desktopInputs = options?.inputs === 'desktop'
 
   let theme: MantineThemeOverride
   if (isDefaultDerive && isDefaultRadius && isDefaultDensity) {
@@ -1699,7 +1675,6 @@ export function createBasaltTheme(
   if (hasFontsConfig(fontsConfig)) {
     theme = mergeThemeOverrides(theme, { other: { basaltFonts: fontsConfig } })
   }
-  if (desktopInputs) theme = mergeThemeOverrides(theme, DESKTOP_INPUTS_THEME)
   if (!overrides) return theme
   // `theme.breakpoints` is derived from `SIZE_CLASSES` — a JS caller's override is dropped.
   return { ...mergeThemeOverrides(theme, overrides), breakpoints: SIZE_CLASS_BREAKPOINTS }

package/src/theme/theme-toggle.module.css

@@ -0,0 +1,30 @@
+/*
+ * The sun/moon glyph: both icons stacked in one grid cell, the inactive one faded, shrunk and
+ * rotated away. A CSS transition, not `motion` (V2-SPEC § 5); reduced motion swaps instantly.
+ */
+.glyph {
+  display: inline-grid;
+  place-items: center;
+}
+
+.sun,
+.moon {
+  grid-area: 1 / 1;
+  display: inline-flex;
+  transition:
+    opacity 150ms ease,
+    transform 250ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.glyph[data-dark='true'] .sun,
+.glyph[data-dark='false'] .moon {
+  opacity: 0;
+  transform: scale(0.6) rotate(30deg);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .sun,
+  .moon {
+    transition: none;
+  }
+}

package/src/theme/theme-toggle.module.css.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly glyph: string
+  readonly sun: string
+  readonly moon: string
+}
+export default classes

package/src/theme/theme-toggle.tsx

@@ -8,23 +8,20 @@
  *
  * The glyph is a single animated sun/moon (never a third "computer" icon) reflecting the
  * *resolved* appearance (`useComputedColorScheme`) — no extra chrome for system mode; the tooltip
- * ("System (dark)") and the popover's selected option carry that state instead. Animated via
- * `motion` (see `../motion` for the shared duration/spring tokens); collapses to an instant,
- * unanimated swap when `useReducedMotion` reports a preference for reduced motion.
+ * ("System (dark)") and the popover's selected option carry that state instead. Animated by a CSS
+ * transition (`theme-toggle.module.css`), which drops to an instant swap under
+ * `prefers-reduced-motion: reduce`.
  */
 import {
   ActionIcon,
-  Center,
   Popover,
   SegmentedControl,
   useComputedColorScheme,
   useMantineColorScheme,
 } from '@mantine/core'
-import { useReducedMotion } from '@mantine/hooks'
-import { AnimatePresence, motion } from 'motion/react'
 import { useRef, useState } from 'react'
-import { MOTION_SPRING } from '../common/motion'
 import type { BasaltProps } from '../common/props'
+import classes from './theme-toggle.module.css'
 
 type Scheme = 'light' | 'dark' | 'auto'
 
@@ -71,41 +68,17 @@ function MoonGlyph() {
   )
 }
 
-/** The animated sun/moon glyph — crossfades + rotates between the two on scheme change. */
-function SchemeGlyph({ dark, reduceMotion }: { dark: boolean; reduceMotion: boolean }) {
-  if (reduceMotion) {
-    return (
-      <Center component="span" inline>
-        {dark ? <MoonGlyph /> : <SunGlyph />}
-      </Center>
-    )
-  }
+/** The sun/moon glyph — both mounted, crossfaded and rotated by CSS on scheme change. */
+function SchemeGlyph({ dark }: { dark: boolean }) {
   return (
-    <AnimatePresence mode="wait" initial={false}>
-      {dark ? (
-        <motion.span
-          key="moon"
-          style={{ display: 'inline-flex' }} // theme-allow inline-display — a framer-motion glyph wrapper, not a Mantine layout node
-          initial={{ opacity: 0, scale: 0.6, rotate: 30 }}
-          animate={{ opacity: 1, scale: 1, rotate: 0 }}
-          exit={{ opacity: 0, scale: 0.6, rotate: -30 }}
-          transition={MOTION_SPRING}
-        >
-          <MoonGlyph />
-        </motion.span>
-      ) : (
-        <motion.span
-          key="sun"
-          style={{ display: 'inline-flex' }} // theme-allow inline-display — a framer-motion glyph wrapper, not a Mantine layout node
-          initial={{ opacity: 0, scale: 0.6, rotate: -30 }}
-          animate={{ opacity: 1, scale: 1, rotate: 0 }}
-          exit={{ opacity: 0, scale: 0.6, rotate: 30 }}
-          transition={MOTION_SPRING}
-        >
-          <SunGlyph />
-        </motion.span>
-      )}
-    </AnimatePresence>
+    <span className={classes.glyph} data-dark={dark}>
+      <span className={classes.sun}>
+        <SunGlyph />
+      </span>
+      <span className={classes.moon}>
+        <MoonGlyph />
+      </span>
+    </span>
   )
 }
 
@@ -129,7 +102,6 @@ export function ThemeToggle({
 }: ThemeToggleProps = {}) {
   const { colorScheme, setColorScheme } = useMantineColorScheme()
   const resolved = useComputedColorScheme('dark')
-  const reduceMotion = useReducedMotion()
   const [opened, setOpened] = useState(false)
   const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
 
@@ -166,7 +138,7 @@ export function ThemeToggle({
           onFocus={scheduleOpen}
           onBlur={scheduleClose}
         >
-          <SchemeGlyph dark={dark} reduceMotion={reduceMotion} />
+          <SchemeGlyph dark={dark} />
         </ActionIcon>
       </Popover.Target>
       <Popover.Dropdown

package/src/theme-lab/derive-controls.tsx

@@ -61,7 +61,7 @@ import {
 } from '@mantine/core'
 import { useEffect, useState } from 'react'
 import type { ReactNode } from 'react'
-import { buildDensityCss, buildPaletteCss, buildRadiusCss } from '../tokens'
+import { buildDensityCss, buildPaletteCss, buildRadiusCss } from '../tokens/core'
 import type { DeriveConfig } from '../tokens/derive'
 import { buildPaletteData, deriveRadius, deriveSpacing } from '../tokens/palette'
 import {
@@ -145,9 +145,11 @@ export function DeriveControls({ resetIcon }: DeriveControlsProps) {
   // persisted/derived config once it matches a full hex; an invalid in-progress value keeps the
   // last valid accent applied.
   const [accentDraft, setAccentDraft] = useState(state.accent)
-  useEffect(() => {
+  const [draftSource, setDraftSource] = useState(state.accent)
+  if (draftSource !== state.accent) {
+    setDraftSource(state.accent)
     setAccentDraft(state.accent)
-  }, [state.accent])
+  }
 
   const handleAccentChange = (value: string) => {
     setAccentDraft(value)

package/src/theme-lab/derive-state.ts

@@ -14,7 +14,8 @@
  * whole dev-tool UI (Slider/ColorInput/SegmentedControl) along with the six lines of state it
  * actually needs. This module has zero `@mantine/*` and zero JSX for exactly that reason.
  */
-import { createPersistedState, readPersistedValue } from '../state'
+import { createPersistedState } from '../state'
+import { readPersistedValue } from '../state/persisted'
 import { DEFAULT_DERIVE_CONFIG, resolveDeriveConfig } from '../tokens/derive'
 import type { DeriveConfig } from '../tokens/derive'