basalt-ui 1.41.0 → 2.0.0

package/src/content/markdown.tsx

@@ -29,7 +29,7 @@
  *    through (`./callout-alert`).
  *  - `a`/`img` — hardened via `allowedLinkPrefixes`/`allowedImagePrefixes`/`defaultOrigin`
  *    (`./url-hardening`); a disallowed URL (including remend's `streamdown:incomplete-link`
- *    sentinel) drops the `href`/`src`, and the component renders an unlinked span / nothing.
+ *    sentinel) drops the `href`/`src`, and the component renders an unlinked span / the image's alt text.
  *
  * Streaming mode (`streaming`): `blockSplit` splits `children` into top-level blocks. Every block
  * except the last renders through a memoized renderer (`React.memo`, referentially stable
@@ -183,8 +183,9 @@ function LinkRenderer({ href, children, node: _node, ...rest }: LinkProps) {
 
 function ImageRenderer({ src, alt }: ImgProps) {
   // A blocked src arrives as undefined OR '' depending on how urlTransform dropped it — an
-  // `<img src="">` renders the broken-image glyph, so both cases must skip the element entirely.
-  if (typeof src !== 'string' || src === '') return <span aria-label={alt} />
+  // `<img src="">` renders the broken-image glyph, so both cases skip the element and keep the alt
+  // as plain text — the same "text, never a destination" degrade an unfinished link gets.
+  if (typeof src !== 'string' || src === '') return alt ? <span>{alt}</span> : null
   return <img src={src} alt={alt ?? ''} loading="lazy" />
 }
 

package/src/content/mermaid.tsx

@@ -20,7 +20,7 @@
  * <MermaidDiagram code={'graph TD\n  A --> B'} />
  */
 import type { CSSProperties, ReactNode } from 'react'
-import { useEffect, useMemo, useRef, useState } from 'react'
+import { useEffect, useMemo, useState } from 'react'
 import { CodeBlock } from './code-block'
 import classes from './mermaid.module.css'
 
@@ -67,7 +67,7 @@ export type MermaidDiagramProps = {
 
 export function MermaidDiagram({ code, className, style, fallback }: MermaidDiagramProps) {
   const [mod, setMod] = useState<MermaidModule | null | undefined>(undefined)
-  const lastGoodRef = useRef<string | null>(null)
+  const [lastGood, setLastGood] = useState<string | null>(null)
 
   useEffect(() => {
     let cancelled = false
@@ -82,16 +82,18 @@ export function MermaidDiagram({ code, className, style, fallback }: MermaidDiag
 
   // Pure and synchronous once `mod` is resolved — parse errors keep the last successfully
   // rendered SVG (docs/CONTENT-SPEC.md §2 decision 4) instead of blanking a settled diagram.
-  const html = useMemo(() => {
+  // Three states: `null` = module not resolved yet, `undefined` = this `code` failed to parse (show
+  // the last good SVG), `string` = fresh SVG.
+  const rendered = useMemo(() => {
     if (!mod) return null
     try {
-      const svg = mod.renderMermaidSVG(code, MERMAID_THEME_OPTIONS)
-      lastGoodRef.current = svg
-      return svg
+      return mod.renderMermaidSVG(code, MERMAID_THEME_OPTIONS)
     } catch {
-      return lastGoodRef.current
+      return undefined
     }
   }, [mod, code])
+  if (typeof rendered === 'string' && rendered !== lastGood) setLastGood(rendered)
+  const html = rendered === undefined ? lastGood : rendered
 
   if (html === null) {
     return (

package/src/content/slug.ts

@@ -1,5 +1,5 @@
 /**
- * headingSlug + readingTime — small, pure, zero-dep utils for the content surface.
+ * headingSlug + SlugTracker — small, pure, zero-dep utils for the content surface.
  *
  * `headingSlug` follows the github-slugger algorithm (lowercase, strip punctuation, spaces → `-`)
  * so headings authored in `<Prose>`, markdown, or MDX land on the SAME anchor ids GitHub itself
@@ -44,18 +44,3 @@ export class SlugTracker {
     return seen === 0 ? base : `${base}-${seen}`
   }
 }
-
-/** The distilled reading-time estimate for a body of text. */
-export type ReadingTime = {
-  readonly minutes: number
-  readonly words: number
-}
-
-const WORDS_PER_MINUTE = 225
-
-/** Estimate reading time at 225 wpm, rounded up to the nearest whole minute. */
-export function readingTime(text: string): ReadingTime {
-  const words = text.trim().split(WHITESPACE_RE).filter(Boolean).length
-  const minutes = Math.ceil(words / WORDS_PER_MINUTE)
-  return { minutes, words }
-}

package/src/content/url-hardening.ts

@@ -11,6 +11,11 @@ import type { UrlTransform } from 'react-markdown'
 
 const SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i
 
+// remend's repair sentinels (`[text](streamdown:incomplete-link)`, `![alt](streamdown:incomplete-image)`)
+// are placeholders for a half-streamed URL, never a destination. Rejected before the allowlist so a
+// permissive consumer prefix (`''`, `'streamdown:'`) can't turn one into a real `href`/`img src`.
+const INCOMPLETE_SENTINEL_RE = /^streamdown:incomplete-(?:link|image)$/i
+
 function isAllowedUrl(url: string, prefixes: readonly string[]): boolean {
   return prefixes.some((prefix) => url.startsWith(prefix))
 }
@@ -33,12 +38,13 @@ export type CreateUrlTransformOptions = {
 
 /**
  * Builds the `urlTransform` passed to `<ReactMarkdown>`. Disallowed URLs (including remend's
- * `streamdown:incomplete-link` sentinel — never a member of the default allowlist) resolve to
+ * `streamdown:incomplete-link` / `streamdown:incomplete-image` sentinels, which no allowlist can admit) resolve to
  * `null`, which react-markdown renders as an `href`/`src`-less element; the `a`/`img` component
- * overrides in `./markdown` turn that into an unlinked span / dropped image.
+ * overrides in `./markdown` turn that into an unlinked span / the image's alt text in a plain span.
  */
 export function createUrlTransform(opts: CreateUrlTransformOptions): UrlTransform {
   return (url, key) => {
+    if (INCOMPLETE_SENTINEL_RE.test(url)) return null
     const prefixes = key === 'src' ? opts.allowedImagePrefixes : opts.allowedLinkPrefixes
     if (!isAllowedUrl(url, prefixes)) return null
     return resolveRelativeUrl(url, opts.defaultOrigin)

package/src/controls/actions.tsx

@@ -26,7 +26,7 @@ import classes from './actions.module.css'
 
 /**
  * A button-shaped action. `Anchor` is the router seam basalt HOSTS (the same seam `SidebarItem`
- * uses — pass the one `useNav` builds, or your router's `Link`); `link` is the no-router fallback
+ * uses — pass your router's `Link`); `link` is the no-router fallback
  * and only its `to` is honoured, since resolving `search`/`params` needs a router. Supply `Anchor`
  * whenever the destination carries either.
  */
@@ -74,6 +74,29 @@ export type BarActionCustom = {
 
 export type BarAction = BarActionItem | BarActionMenu | BarActionCustom
 
+/** The one primary action of a page bar (law C6): the first tuple entry, flagged `primary: true`. */
+type PrimaryBarAction = BarAction & { primary: true }
+/** Every other page-bar action; `primary` may only be absent or `false`. */
+type MoreBarAction = BarAction & { primary?: false }
+
+/**
+ * `PageBar.actions`: exactly one primary first, then up to four more. Law C6 as a type — a missing
+ * or second primary and a sixth entry are tsc errors (`docs/V2-SPEC.md` §3).
+ */
+export type PageBarActions =
+  | [PrimaryBarAction]
+  | [PrimaryBarAction, MoreBarAction]
+  | [PrimaryBarAction, MoreBarAction, MoreBarAction]
+  | [PrimaryBarAction, MoreBarAction, MoreBarAction, MoreBarAction]
+  | [PrimaryBarAction, MoreBarAction, MoreBarAction, MoreBarAction, MoreBarAction]
+
+/** `Section.actions`: at most three (law C6). */
+export type SectionActions =
+  | []
+  | [BarAction]
+  | [BarAction, BarAction]
+  | [BarAction, BarAction, BarAction]
+
 /**
  * A home's `actions` slot. `primary` is SINGULAR by type — that is the whole enforcement of law
  * C6's "exactly one primary"; there is no runtime check because a second one cannot be written.

package/src/controls/enum-filter.tsx

@@ -29,7 +29,7 @@
 import { Radio, Stack } from '@mantine/core'
 import type { ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
-import type { FieldOption } from '../state'
+import type { FieldOption } from '../state/fields'
 import classes from './controls.module.css'
 import { POPOVER_ROW_HIT_GAP, useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterClearButton, FilterPill } from './filter-pill'

package/src/controls/filter-context.tsx

@@ -114,7 +114,9 @@ export function useFilterRegistration(isActive: boolean, reset: () => void): voi
   // A ref, so a `reset` closure that is fresh every render does not re-run the effect (and so
   // `Reset all` always calls the LATEST setter, not the one captured at registration).
   const resetRef = useRef(reset)
-  resetRef.current = reset
+  useEffect(() => {
+    resetRef.current = reset
+  })
   const stableReset = useCallback(() => {
     resetRef.current()
   }, [])

package/src/controls/filter-set.tsx

@@ -6,7 +6,7 @@
  * **Desktop.** One row, `wrap: nowrap`, and it NEVER scrolls (C7). When the measured pill widths
  * exceed the container the tail folds into a `+N` menu pill — a `ResizeObserver` on the row plus
  * per-slot `offsetWidth`, because the fold point depends on the labels actually painted (the same
- * reasoning as the charts' `autoMargin`), not on a guessed pill width.
+ * reasoning as the charts' measured margins), not on a guessed pill width.
  *
  * **Mobile (`< sm`).** The first `inline` children stay pills; every child — inline ones included —
  * also renders its full-width sheet form inside the `Filters (n)` Drawer — which exists only when
@@ -173,14 +173,12 @@ export function FilterSet({
 function useOverflowFit(rowRef: RefObject<HTMLDivElement | null>, count: number): number {
   const [fit, setFit] = useState(count)
   const widths = useRef<number[]>([])
+  const canObserve = typeof ResizeObserver !== 'undefined'
 
   useEffect(() => {
     const row = rowRef.current
     if (row === null) return
-    if (typeof ResizeObserver === 'undefined') {
-      setFit(count)
-      return
-    }
+    if (!canObserve) return
 
     const measure = (): void => {
       const slots = [...row.querySelectorAll<HTMLElement>('[data-filter-slot]')]
@@ -213,9 +211,9 @@ function useOverflowFit(rowRef: RefObject<HTMLDivElement | null>, count: number)
     return () => {
       observer.disconnect()
     }
-  }, [rowRef, count])
+  }, [rowRef, count, canObserve])
 
-  return fit
+  return canObserve ? fit : count
 }
 
 function fitCount(

package/src/controls/form-layout.tsx

@@ -26,8 +26,8 @@ import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
 import { BarActionSlot } from './actions'
 import type { SlotActions } from './actions'
-import { WidgetHeader } from '../dashboard'
-import type { WidgetHeaderTitleProps } from '../dashboard'
+import { WidgetHeader } from '../dashboard/widget-header'
+import type { WidgetHeaderTitleProps } from '../dashboard/widget-header'
 import { useFormState } from '../forms/form-state'
 import classes from './form-layout.module.css'
 

package/src/controls/glyphs.tsx

@@ -47,16 +47,6 @@ export function CalendarGlyph(): ReactNode {
   )
 }
 
-/** `CompareFilter`'s default leading icon — the arrows-swap glyph. */
-export function SwapGlyph(): ReactNode {
-  return (
-    <Stroke>
-      <path d="M4 8h13l-3.5 -3.5" />
-      <path d="M20 16h-13l3.5 3.5" />
-    </Stroke>
-  )
-}
-
 /** The mobile `Filters (n)` pill's leading icon. */
 export function FunnelGlyph(): ReactNode {
   return (

package/src/controls/index.ts

@@ -2,70 +2,19 @@
  * `basalt-ui/controls` — the Mantine-coupled control tier (`docs/CONTROLS-SPEC.md` §3).
  *
  * Every control here renders at the `ctl` tier from the home that hosts it and owns its own
- * desktop/mobile swap in CSS (law C9). Actions and sync land in wave 3; the filter/tab family
- * follows in wave 4.
+ * desktop/mobile swap in CSS (law C9).
  */
-export {
-  ActionGroup,
-  OverflowMenu,
-  MOBILE_GLOBAL_BAR_MAX,
-  barActionMobile,
-  globalActionMobile,
-  type BarAction,
-  type BarActionItem,
-  type BarActionMenu,
-  type BarActionCustom,
-  type ActionGroupProps,
-  type GlobalAction,
-  type OverflowMenuProps,
-} from './actions'
-export { SyncButton, formatAge, AGE_REFRESH_MS, type SyncButtonProps } from './sync-button'
-export { ControlGroup, type ControlGroupProps } from './control-group'
+export { type BarAction, type GlobalAction } from './actions'
+export { SyncButton } from './sync-button'
 
-// ── Filters + tabs (wave 4) ───────────────────────────────────────────────────────────────────
 // `FilterPill`, `FilterSheet` and the `EnumFilter` body are deliberately NOT here: reaching for
-// them is hand-rolling a filter (`basalt/hand-rolled-filter`), and `useFilterSurface` is only
-// meaningful to a control living inside a `FilterSet` — i.e. to this folder.
-export { FilterSet, type FilterSetProps } from './filter-set'
-export { RangeFilter, type RangeCustomPickerProps, type RangeFilterProps } from './range-filter'
-export {
-  CompareFilter,
-  COMPARE_VALUES,
-  type CompareFilterProps,
-  type CompareValue,
-} from './compare-filter'
-export {
-  SelectFilter,
-  type FilterOption,
-  type SelectFilterEnumProps,
-  type SelectFilterProps,
-  type SelectFilterStringProps,
-} from './select-filter'
-export { MultiSelectFilter, type MultiSelectFilterProps } from './multi-select-filter'
-export { NumberFilter, type NumberFilterOption, type NumberFilterProps } from './number-filter'
-export { SearchFilter, type SearchFilterProps } from './search-filter'
-export { ToggleFilter, type ToggleFilterProps } from './toggle-filter'
-export { ViewTabs, type ViewTabsOption, type ViewTabsProps } from './view-tabs'
-
-// ── The `panel` surface (docs/ASIDE-SPEC.md wave 2) ───────────────────────────────────────────
-// The two row-level primitives an aside body needs. `PanelRow` is the home (it wraps its slots in
-// `CtlSlot`), and `SliderControl` is the one bound control that has no pill form at all — see their
-// docs. The filters above render their own panel forms; there is nothing extra to import for them.
-export { PanelRow, type PanelRowProps } from './panel-row'
-export { SliderControl, type SliderControlProps } from './slider-control'
-
-// ── The form layout (moved from ./forms in 1.36.0) ────────────────────────────────────────────
-// Layout needs no `@mantine/form`, and `./forms`' barrel value-imports it — so a consumer rendering
-// a `FormRow` had to install a peer it never used. `./forms` re-exports these until 1.39.0.
-export {
-  FormSection,
-  FormRow,
-  FormGroup,
-  FormActions,
-  type FormSectionProps,
-  type FormSectionSlot,
-  type FormRowProps,
-  type FormRowSlot,
-  type FormGroupProps,
-  type FormActionsProps,
-} from './form-layout'
+// them is hand-rolling a filter (`basalt/hand-rolled-filter`).
+export { FilterSet } from './filter-set'
+export { RangeFilter } from './range-filter'
+export { SelectFilter } from './select-filter'
+export { MultiSelectFilter } from './multi-select-filter'
+export { NumberFilter } from './number-filter'
+export { SearchFilter } from './search-filter'
+export { ToggleFilter } from './toggle-filter'
+export { ViewTabs } from './view-tabs'
+export { FormRow, FormGroup } from './form-layout'

package/src/controls/multi-select-filter.tsx

@@ -25,21 +25,22 @@
 import { Checkbox, Stack } from '@mantine/core'
 import { useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
-import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import type { FieldHandle, MultiField } from '../state'
+import type { FieldHandle } from '../state'
+import type { MultiField } from '../state/fields'
 import type { FilterOption } from './select-filter'
 import classes from './controls.module.css'
 import { POPOVER_ROW_HIT_GAP, useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterClearButton, FilterPill } from './filter-pill'
 import { CheckGlyph, useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
+import type { UncontrolledProps } from './uncontrolled'
 
 /** How many facet rows a panel shows before the rest fold behind `Show N more`. Six is the point at
  *  which a facet column stops being a list you scan and starts being one you scroll. */
 const PANEL_FACET_MAX = 6
 
-export type MultiSelectFilterProps<T extends string> = BasaltProps & {
+export type MultiSelectFilterProps<T extends string> = UncontrolledProps & {
   readonly field: FieldHandle<MultiField<T>>
   readonly label: string
   readonly icon?: ReactNode
@@ -75,7 +76,7 @@ export type MultiSelectFilterProps<T extends string> = BasaltProps & {
 
 export function MultiSelectFilter<T extends string>(props: MultiSelectFilterProps<T>): ReactNode {
   // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
-  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  // (evaluating 'field.use')`, caught by `RootBoundary`.
   assertRequiredProps('MultiSelectFilter', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })

package/src/controls/number-filter.tsx

@@ -63,7 +63,8 @@ import { useEffect, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import type { FieldHandle, NumberField } from '../state'
+import type { FieldHandle } from '../state'
+import type { NumberField } from '../state/fields'
 import classes from './controls.module.css'
 import { EnumFilter } from './enum-filter'
 import type { ChoiceHandle } from './enum-filter'
@@ -71,6 +72,7 @@ import { useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterClearButton, FilterPill } from './filter-pill'
 import { useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
+import type { UncontrolledProps } from './uncontrolled'
 
 /** One row of a numeric preset set. Narrower than `FilterOption` — a preset is never `disabled`:
  *  the set is declared at the call site, so a row that should not be offered is left out. */
@@ -79,7 +81,7 @@ export type NumberFilterOption = {
   readonly label: string
 }
 
-export type NumberFilterProps = BasaltProps & {
+export type NumberFilterProps = UncontrolledProps & {
   readonly field: FieldHandle<NumberField>
   /** The popover/sheet heading and the accessible name — never the pill text, which reads the
    *  VALUE (see `EnumFilter`'s doc for why a pill may only print what is selected). */
@@ -102,7 +104,7 @@ export type NumberFilterProps = BasaltProps & {
 
 export function NumberFilter(props: NumberFilterProps): ReactNode {
   // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
-  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  // (evaluating 'field.use')`, caught by `RootBoundary`.
   assertRequiredProps('NumberFilter', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })
@@ -316,7 +318,9 @@ function useCommittedNumber(
   const [draft, setDraft] = useState<number | string>(value)
   const seen = useRef(value)
   const commitRef = useRef(setValue)
-  commitRef.current = setValue
+  useEffect(() => {
+    commitRef.current = setValue
+  })
 
   useEffect(() => {
     if (seen.current === value) return

package/src/controls/range-filter.tsx

@@ -30,15 +30,16 @@
 import { SegmentedControl, Select, Stack } from '@mantine/core'
 import { useEffect, useRef, useState } from 'react'
 import type { ComponentType, ReactNode } from 'react'
-import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import type { FieldHandle, RangeField, RangeValue } from '../state'
+import type { FieldHandle } from '../state'
+import type { RangeField, RangeValue } from '../state/fields'
 import classes from './controls.module.css'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterPill } from './filter-pill'
 import { CalendarGlyph } from './glyphs'
 import { useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
+import type { UncontrolledProps } from './uncontrolled'
 
 /** Past four presets the track goes vertical. */
 const VERTICAL_FROM = 5
@@ -81,7 +82,7 @@ export type RangeCustomPickerProps = {
 }
 
 /** Everything about the props that does not depend on the field's `custom` flag. */
-type RangeFilterBase<P extends string, C extends boolean> = BasaltProps & {
+type RangeFilterBase<P extends string, C extends boolean> = UncontrolledProps & {
   /**
    * A range handle from either store factory. Generic over the field's `custom` flag so a
    * `field.range({ ... })` WITHOUT `custom` (whose handle is `RangeField<P, false>`, and whose
@@ -112,7 +113,7 @@ export function RangeFilter<P extends string, C extends boolean = boolean>(
   props: RangeFilterProps<P, C>,
 ): ReactNode {
   // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
-  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  // (evaluating 'field.use')`, caught by `RootBoundary`.
   assertRequiredProps('RangeFilter', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })

package/src/controls/search-filter.tsx

@@ -13,19 +13,21 @@
  * <SearchFilter field={table.field.q} placeholder="Search pages" />
  */
 import { TextInput } from '@mantine/core'
+import { useDebouncedCallback } from '@mantine/hooks'
 import { useEffect, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
-import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import type { FieldHandle, StringField } from '../state'
+import type { FieldHandle } from '../state'
+import type { StringField } from '../state/fields'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
 import { useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
+import type { UncontrolledProps } from './uncontrolled'
 
 /** One navigation per typed phrase, not per keystroke. */
 const DEBOUNCE_MS = 200
 
-export type SearchFilterProps = BasaltProps & {
+export type SearchFilterProps = UncontrolledProps & {
   readonly field: FieldHandle<StringField>
   readonly placeholder?: string
   /** Sheet-form heading. @default 'Search' */
@@ -34,7 +36,7 @@ export type SearchFilterProps = BasaltProps & {
 
 export function SearchFilter(props: SearchFilterProps): ReactNode {
   // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
-  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  // (evaluating 'field.use')`, caught by `RootBoundary`.
   assertRequiredProps('SearchFilter', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })
@@ -98,27 +100,31 @@ function useDebouncedField(
 ): { value: string; set: (next: string) => void } {
   const [draft, setDraft] = useState(value)
   const seen = useRef(value)
-  const commit = useRef(setValue)
-  commit.current = setValue
+  const held = useRef(value)
+  useEffect(() => {
+    held.current = value
+  })
+  const commit = useDebouncedCallback((next: string) => {
+    // A phrase typed and erased inside the window ends where it began: nothing to write.
+    if (next === held.current) return
+    seen.current = next
+    setValue(next)
+  }, DEBOUNCE_MS)
 
   useEffect(() => {
     if (seen.current === value) return
     seen.current = value
     setDraft(value)
-  }, [value])
+    commit.cancel()
+  }, [value, commit])
 
-  useEffect(() => {
-    if (draft === value) return
-    const timer = setTimeout(() => {
-      seen.current = draft
-      commit.current(draft)
-    }, DEBOUNCE_MS)
-    return () => {
-      clearTimeout(timer)
-    }
-  }, [draft, value])
-
-  return { value: draft, set: setDraft }
+  return {
+    value: draft,
+    set: (next) => {
+      setDraft(next)
+      commit(next)
+    },
+  }
 }
 
 function SearchIcon(): ReactNode {

package/src/controls/select-filter.tsx

@@ -30,10 +30,11 @@
  * />
  */
 import type { ReactNode } from 'react'
-import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import type { EnumField, FieldHandle, StringField } from '../state'
+import type { EnumField, FieldHandle } from '../state'
+import type { StringField } from '../state/fields'
 import { EnumFilter } from './enum-filter'
+import type { UncontrolledProps } from './uncontrolled'
 
 /**
  * One row of a runtime catalogue. Wider than the store's own `FieldOption` by exactly one member:
@@ -47,7 +48,7 @@ export type FilterOption = {
   readonly disabled?: boolean
 }
 
-type SelectFilterCommon = BasaltProps & {
+type SelectFilterCommon = UncontrolledProps & {
   readonly label: string
   readonly icon?: ReactNode
   /** Adds a `Clear` action that writes the field back to its fallback. */
@@ -82,7 +83,7 @@ export function SelectFilter(props: SelectFilterStringProps): ReactNode
 export function SelectFilter<T extends string>(props: SelectFilterProps<T>): ReactNode {
   // F-ERR-1: without this, a `field` that never arrived surfaces as
   // `undefined is not an object (evaluating 'field.use')` from inside `EnumFilter`, caught by
-  // `BasaltErrorBoundary` and rendered as a blank subtree. `field` is not optional in the type, so
+  // `RootBoundary` and rendered as a blank subtree. `field` is not optional in the type, so
   // this only ever fires on untyped JS, a `props` object built at runtime, or a store key that
   // resolved to nothing — all three of which the message now names.
   assertRequiredProps('SelectFilter', props, ['field'], {

package/src/controls/sync-button.tsx

@@ -21,7 +21,7 @@
  * button relying on its visible children would be an unnamed icon on a phone.
  */
 import { ActionIcon, Button, Tooltip } from '@mantine/core'
-import { useEffect, useState } from 'react'
+import { useSyncExternalStore } from 'react'
 import type { ReactNode } from 'react'
 import { cx } from '../common/props'
 import type { BasaltProps } from '../common/props'
@@ -73,30 +73,28 @@ function toMillis(at: number | Date | null | undefined): number | undefined {
  * The age string, refreshed on an interval that exists ONLY while the component is mounted and
  * only while there is an age to show — a sync control on a background route costs no timer.
  *
- * The clock is read in the EFFECT, never during render. A global `SyncButton` in `globalActions`
- * renders inline in the shell header (no portal), so under SSR the server would emit `just now` and
- * a client hydrating a minute later would emit `1m ago` — a React text mismatch that discards the
- * subtree. Server and first client paint both omit the age; the effect fills it in after mount.
- * That also makes the interval the only thing that re-renders, so the old `setTick` counter is gone.
+ * The clock is read through `useSyncExternalStore`, whose server snapshot omits the age. A global
+ * `SyncButton` in `globalActions` renders inline in the shell header (no portal), so under SSR the
+ * server would emit `just now` and a client hydrating a minute later would emit `1m ago` — a React
+ * text mismatch that discards the subtree. Server and hydrating paint both omit the age; React
+ * re-renders with the client snapshot right after. The snapshot is the formatted label, a bucketed
+ * string (`just now`, `1m ago`, …), so it is stable across calls within a bucket and a tick only
+ * re-renders when the label changes. With no timestamp there is no subscription and no timer.
  */
 function useRelativeAge(at: number | Date | null | undefined): string | undefined {
-  const [age, setAge] = useState<string | undefined>(undefined)
   const timestamp = toMillis(at)
+  return useSyncExternalStore(
+    timestamp === undefined ? subscribeNever : subscribeAgeTick,
+    () => (timestamp === undefined ? undefined : formatAge(Date.now() - timestamp)),
+    () => undefined,
+  )
+}
 
-  useEffect(() => {
-    if (timestamp === undefined) {
-      setAge(undefined)
-      return
-    }
-    const publish = (): void => {
-      setAge(formatAge(Date.now() - timestamp))
-    }
-    publish()
-    const id = setInterval(publish, AGE_REFRESH_MS)
-    return () => clearInterval(id)
-  }, [timestamp])
+const subscribeNever = (): (() => void) => () => {}
 
-  return age
+function subscribeAgeTick(onTick: () => void): () => void {
+  const id = setInterval(onTick, AGE_REFRESH_MS)
+  return () => clearInterval(id)
 }
 
 function RefreshGlyph({ spinning }: { spinning: boolean }) {