basalt-ui 1.27.0 → 1.28.0

package/src/guard/index.ts

@@ -160,8 +160,9 @@ const INLINE_FONT_SIZE =
 // Two deliberate non-matches:
 //   • `<Card.Section withBorder>` — a section DIVIDER, not card depth. Excluded by the `(?![\w.])`
 //     lookahead, which also rejects `<CardHeader>`-style names.
-//   • `withBorder={false}` — an explicit opt-out (what the shell's AppShell parts do). Excluded by
-//     the lookahead on WITH_BORDER_PROP.
+//   • `withBorder={false}` — a consumer opt-out; the shell no longer uses it (region edges are
+//     painted by the theme's `AppShell.extend`, not by a prop). Excluded by the lookahead on
+//     WITH_BORDER_PROP.
 const CARD_SURFACE_TAG = /<(?:Card|Paper)(?![\w.])(?:=>|[^>])*?>/g
 const WITH_BORDER_PROP = /\bwithBorder\b(?!\s*=\s*\{\s*false\s*\})/
 
@@ -506,9 +507,19 @@ const RAW_SELECTION_CONTROL_TAG =
  */
 const PROSE_CONTEXT_TAG = /<(?:Prose|ArticleLayout|Modal|Drawer)(?![\w])/
 
-/** An opening tag for one of the declared non-homes — a settings row, an overlay, a composer. */
+/**
+ * An opening tag for one of the declared non-homes — a settings row, an overlay, a composer — or
+ * for one of the basalt SUBTREE homes, where the children ARE the home (`FilterSet` / `PageAside` /
+ * `PanelRow`, `docs/ASIDE-SPEC.md` §3). The text lane cannot ask which of the two a tag is, and it
+ * does not need to: both mean "a raw control here is not homeless".
+ *
+ * The three subtree homes are the plugin's `BASALT_HOST_TAGS`, mirrored here so one law does not
+ * read differently in the two lanes. The plugin gates them on the tag's basalt IMPORT; a 12-line
+ * regex window has no import graph, so this lane matches by name and accepts the missed warn on a
+ * consumer's own `PanelRow` — the same direction every approximation in this scan already leans.
+ */
 const CONTROL_HOST_TAG =
-  /<(?:SettingsRow|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer)(?![\w])/
+  /<(?:SettingsRow|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer|FilterSet|PageAside|PanelRow)(?![\w])/
 
 /**
  * How far ABOVE a control the host-tag window reaches, in lines.
@@ -524,23 +535,50 @@ const CONTROL_HOST_WINDOW_LINES = 12
 
 /**
  * A file whose BASENAME declares it is an overlay's or a form's own body — the cross-file half of
- * {@link CONTROL_HOST_TAG}, and the same regex the plugin's `OVERLAY_CONVENTION_FILE` applies to
- * `basalt/control-outside-home` (one law, two lanes, one exemption).
+ * {@link CONTROL_HOST_TAG}, and the same two dialects the plugin's `isOverlayConventionFile`
+ * applies to `basalt/control-outside-home` and `basalt/bound-control-outside-home` (one law, two
+ * lanes, one exemption).
  *
  * Law C1's cross-file case is advisory by declaration (`docs/CONTROLS-SPEC.md` §6, "Honest
  * coverage"), and this kind was paying for it: a `<Select>` inside `edit-session-modal.tsx` whose
  * `<Modal>` is rendered by the parent route is outside BOTH the 12-line host window and any
  * ancestry walk, because the host tag is not in the file at all. argo carried 9 of them.
  *
+ * KEBAB and PascalCase both count, because a repo picks one file-naming law and the convention has
+ * to survive either: `edit-session-modal.tsx`, and `CbbiPanel.tsx` in a repo mandating
+ * `PascalCase.tsx` for component files (basalt's own root `CLAUDE.md` included). Each needs the
+ * leading SUBJECT — a bare `modal.tsx` / `Panel.tsx` is a page module, not the convention.
+ *
  * The trade is that a whole file goes unscanned on a naming convention — the same bargain
  * {@link MANTINE_FORM_IMPORT} already buys, and a smaller one than promoting the kind with 9 known
  * false positives. Basename only: a `modal/` DIRECTORY holds the page pieces around the modals too.
  */
-const OVERLAY_CONVENTION_FILE = /(?:^|\/)[^/]*-(?:modal|drawer|popover|panel|form)\.[jt]sx$/
+const OVERLAY_CONVENTION_KEBAB = /^[^/]*-(?:modal|drawer|popover|panel|form)\.[jt]sx$/
+const OVERLAY_CONVENTION_PASCAL = /^[A-Z]\w*(?:Modal|Drawer|Popover|Panel|Form)\.[jt]sx$/
 
-/** A name whose DECLARATION means this file DEFINES a basalt control rather than consuming one. */
+/** Does `relPath`'s BASENAME declare the overlay convention, in either dialect? */
+function isOverlayConventionFile(relPath: string): boolean {
+  const basename = relPath.slice(relPath.lastIndexOf('/') + 1)
+  return OVERLAY_CONVENTION_KEBAB.test(basename) || OVERLAY_CONVENTION_PASCAL.test(basename)
+}
+
+/**
+ * A name whose DECLARATION means this file DEFINES a basalt control rather than consuming one.
+ *
+ * Paired with {@link BASALT_ANY_IMPORT}, and the pair is the exemption — see the plugin's
+ * `CONTROL_OWNER_NAMES` for the whole reasoning: `PanelRow`, `EnumFilter` and `SliderControl` are
+ * names a consumer writes for their own helpers, so a bare-name match let one local
+ * `function PanelRow(…)` switch this kind off for the whole file.
+ */
 const CONTROL_OWNER_DEF =
-  /\b(?:function|const|class)\s+(?:RangeFilter|CompareFilter|SelectFilter|MultiSelectFilter|NumberFilter|SearchFilter|ToggleFilter|ViewTabs|FilterSet|FilterPill|SyncButton|ActionGroup|OverflowMenu|CtlSlot)(?![\w])/
+  /\b(?:function|const|class)\s+(?:RangeFilter|CompareFilter|SelectFilter|MultiSelectFilter|NumberFilter|SearchFilter|ToggleFilter|ViewTabs|FilterSet|FilterPill|EnumFilter|PanelRow|SliderControl|SyncButton|ActionGroup|OverflowMenu|CtlSlot)(?![\w])/
+
+/**
+ * ANY import from `basalt-ui` or one of its subpaths — named, default, namespace or side-effect.
+ * A file that CONSUMES basalt is not the module that DEFINES its controls, whatever it names its
+ * own helpers; basalt's own control sources import each other relatively and never by package name.
+ */
+const BASALT_ANY_IMPORT = /\b(?:from|import)\s+['"]basalt-ui(?:\/[^'"]*)?['"]/
 
 /** `@mantine/form` — a form is C1's third home, and its inputs are not filters. */
 const MANTINE_FORM_IMPORT = /from\s+['"]@mantine\/form['"]/
@@ -653,17 +691,19 @@ export type GraceEntry = { since: string; promote: string; why: string }
 export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
   'raw-selection-control': {
     since: '1.26.0',
-    promote: '1.28.0',
+    promote: '1.30.0',
     why:
       'new in the wave-6 control guards (docs/CONTROLS-SPEC.md §6, law C1). The text lane cannot ' +
       'see ancestry, so "no home" is approximated by a 12-line host-tag window — the loosest ' +
       'reading in the guard, and the reason this one lands warn rather than error even though its ' +
-      'law is settled. It moved from 1.27.0 to 1.28.0 with its AST twin, `basalt/control-outside-' +
+      'law is settled. It moved from 1.27.0 to 1.30.0 with its AST twin, `basalt/control-outside-' +
       'home`, whose PLUGIN_RULE_GRACE entry carries the measurement: the wave-7 run left 9 warns ' +
       'in argo, all of them a control in a modal/form module whose `<Modal>` is rendered by the ' +
-      'PARENT — law C1 cross-file, which neither lane can see. `OVERLAY_CONVENTION_FILE` (this ' +
+      'PARENT — law C1 cross-file, which neither lane can see. `isOverlayConventionFile` (this ' +
       'file, and the same regex in the plugin) exempts that declared naming convention in both ' +
-      'lanes; 1.28.0 is when the remainder is re-measured. One law, two lanes, one promotion.',
+      'lanes. Re-dated 2026-08-28 — the argo wave-7 migration has not run; the PascalCase overlay ' +
+      'convention (this change) is expected to clear most of the 9. 1.30.0 is when the remainder ' +
+      'is re-measured. One law, two lanes, one promotion.',
   },
 }
 
@@ -834,11 +874,25 @@ export const PLUGIN_RULE_IDS: ReadonlySet<string> = new Set([
   'raw-scroll-container',
   'hand-rolled-filter',
   'control-outside-home',
+  // No text-lane twin, by design: a bound control's NAME says nothing without the import graph
+  // and the ancestry, which a 12-line regex window has neither of. See the rule's own JSDoc.
+  'bound-control-outside-home',
   'control-size-literal',
   'page-bar-budget',
   'responsive-twin',
   'search-literal-link',
   'use-search-from-literal',
+  // The four F5 rules and the B4 deprecation rule — all AST-only, all outside `checkSource`'s
+  // reach: provenance here is an import graph and a JSX ancestry, neither of which a 12-line
+  // regex window has. Same reason `bound-control-outside-home` has no text-lane twin.
+  'provider-above-router',
+  'duplicate-notifications-mount',
+  'query-dual-import',
+  'query-fn-unwrap',
+  'deprecated-export',
+  // Same lane: `{...inputProps(…)}` without a sibling `key` is a JSX-ancestry claim (does this
+  // ELEMENT carry a `key` attribute?) over an import-resolved callee — neither is text.
+  'forms-field-key',
   // `in-body-page-title` is deliberately ABSENT: it is a plugin rule AND a guard kind under one id
   // (one law, two lanes, one annotation), and this set is the ids OUTSIDE `checkSource`'s reach.
   // `check-source.test.ts` asserts the two registries stay disjoint.
@@ -2381,13 +2435,14 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
 
   // raw-selection-control — full-text tag scan plus the host WINDOW (see CONTROL_HOST_WINDOW_LINES).
   // Three file-level exemptions mirror the plugin rule's, so the two lanes agree on the same file:
-  // a file that DEFINES a basalt control cannot be told to use one, a file importing
-  // `@mantine/form` is a form — C1's third home, whose inputs are not filters — and a file NAMED as
-  // an overlay body carries its `<Modal>` in the parent, where no scan of this file can reach it.
+  // a file that DEFINES a basalt control (and imports none — see CONTROL_OWNER_DEF) cannot be told
+  // to use one, a file importing `@mantine/form` is a form — C1's third home, whose inputs are not
+  // filters — and a file NAMED as an overlay body carries its `<Modal>` in the parent, where no
+  // scan of this file can reach it.
   if (
     ruleApplies('raw-selection-control', relPath) &&
-    !OVERLAY_CONVENTION_FILE.test(relPath) &&
-    !CONTROL_OWNER_DEF.test(codeText) &&
+    !isOverlayConventionFile(relPath) &&
+    !(CONTROL_OWNER_DEF.test(codeText) && !BASALT_ANY_IMPORT.test(codeText)) &&
     !MANTINE_FORM_IMPORT.test(codeText)
   ) {
     for (const m of codeText.matchAll(RAW_SELECTION_CONTROL_TAG)) {

package/src/index.ts

@@ -12,23 +12,57 @@ export {
   BasaltErrorBoundary,
   type BasaltErrorContext,
 } from './provider'
+// -- Common primitives (src/common) ------------------------------------------------------------
+// Not a subpath of its own: `BasaltProps` is the base every component's props extend, so it belongs
+// on the entry a consumer already imports. The module is Mantine-free (`common/boundary.test.ts`),
+// which is what lets `./charts` reach `cx`/`mergeRefs` without breaching the layer boundary.
+export {
+  type BasaltProps,
+  type SlotClassNames,
+  type SlotStylesProps,
+  type Tone,
+  type ToneWithNeutral,
+  type Tier,
+  cx,
+  assignRef,
+  mergeRefs,
+  BASALT_PREFIX,
+  requiredProp,
+  oneOf,
+  deprecatedProp,
+  duplicateMount,
+  missingLayer,
+  useValidateProps,
+  assertRequiredProps,
+  scrollParentOf,
+  SCROLLPORT_ATTRIBUTE,
+} from './common'
+
 export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme'
 export type { BasaltFontsConfig, CreateBasaltThemeOptions } from './theme'
 export { CTL_THEME, CtlSlot } from './theme'
 export type { CtlSlotProps } from './theme'
 /**
  * The action vocabulary every home's `actions` slot takes (`docs/CONTROLS-SPEC.md` §2.1). The
- * COMPONENTS that project it (`ActionGroup`, `OverflowMenu`, `SyncButton`, and the filter family)
- * live on `basalt-ui/controls` — only the types a `PageBar`/`BasaltShell` prop mentions are here.
+ * OTHER components that project it (`OverflowMenu`, `SyncButton`, and the filter family) live on
+ * `basalt-ui/controls`; `ActionGroup` is re-exported here alongside its own types so a typed
+ * `PageBar`/`BasaltShell` `actions` wrapper needs only this one subpath.
  */
-export type { BarAction, ActionGroupProps, GlobalAction } from './controls/actions'
+export {
+  ActionGroup,
+  type BarAction,
+  type ActionGroupProps,
+  type GlobalAction,
+} from './controls/actions'
 export { ThemeToggle, type ThemeToggleProps } from './theme-toggle'
 export { MOTION_DURATION, MOTION_SPRING, MOTION_EASE_STANDARD } from './motion'
 export {
   BasaltShell,
   NavCountBadge,
+  type NavCountBadgeProps,
   AppSidebar,
   SidebarSearch,
+  type SidebarSearchProps,
   type SidebarSearchConfig,
   type SidebarSearchActions,
   SidebarAccount,
@@ -40,8 +74,13 @@ export {
   MOBILE_MENU_MAX_DEFAULT,
   MOBILE_MORE_KEY,
   AppBreadcrumbs,
+  type AppBreadcrumbsProps,
   PageBar,
   type PageBarProps,
+  type PageBarSlot,
+  PageAside,
+  type PageAsideProps,
+  type PageAsideSlot,
   type SidebarSection,
   type SidebarItem,
   type SidebarBlock,
@@ -87,9 +126,11 @@ export {
 } from './register'
 
 // ── Persisted state + the headless store kernel (state.ts) ───────────────────────────────────────
-// The `field.*` VALUE is deliberately not re-exported here — `basalt-ui/forms` already owns the
-// name `field` on its own barrel. Import it from `basalt-ui/router-tanstack` (beside
-// `createSearchStore`) or from `basalt-ui/state` (beside `createLocalStore`).
+// The `field.*` VALUE is deliberately not re-exported here. `basalt-ui/forms` used to own the
+// name `field` too and collide with this one; that forms helper is now `inputProps` (`field`
+// stays there only as a @deprecated alias — see MIGRATING.md). Import `field.*` from
+// `basalt-ui/router-tanstack` (beside `createSearchStore`) or from `basalt-ui/state` (beside
+// `createLocalStore`).
 export {
   createPersistedState,
   type PersistedStateOptions,
@@ -114,36 +155,59 @@ export {
   type RangeWindow,
   type RangeWindows,
   type ResolvedLane,
+  type ResolveLane,
   type SearchValues,
   type StoredValues,
   type StringField,
 } from './state'
 
 // ── WidgetHeader (unified section/widget/card heading primitive, docs/CONTROLS-SPEC.md §2.2) ─────
-export { WidgetHeader, type WidgetHeaderProps } from './widget-header'
+export {
+  WidgetHeader,
+  type WidgetHeaderDeltaProps,
+  type WidgetHeaderMetricProps,
+  type WidgetHeaderProps,
+  type WidgetHeaderSlot,
+  type WidgetHeaderTier,
+  type WidgetHeaderTitleProps,
+  DeltaBadge,
+  type DeltaBadgeProps,
+  type DeltaPolarity,
+} from './widget-header'
 
 // ── Section (tier-2 heading composer over WidgetHeader, docs/CONTROLS-SPEC.md §2.2) ───────────────
-export { Section, type SectionProps } from './section'
+export { Section, type SectionProps, type SectionSlot } from './section'
 
 // ── Dashboard composites (KPI atoms + settings building blocks) ──────────────────────────────────
 export {
-  DeltaBadge,
-  type DeltaBadgeProps,
   StatCard,
   type StatCardBreakdownRow,
   type StatCardProps,
+  type StatCardSlot,
   type StatCardTone,
+  WidgetGrid,
+  type WidgetGridCols,
+  type WidgetGridItemProps,
+  type WidgetGridProps,
+  StatGroup,
+  type StatGroupCols,
+  type StatGroupProps,
   EmptyState,
   type EmptyStateProps,
+  type EmptyStateSlot,
   SettingsSection,
   type SettingsSectionProps,
+  type SettingsSectionSlot,
   SettingsRow,
   type SettingsRowProps,
+  type SettingsRowSlot,
   DangerZone,
   type DangerZoneProps,
   QueryState,
   type QueryStateProps,
   type QueryStateLike,
+  type QueryStateSlot,
+  type QueryStateTier,
   type QueryStateVariant,
   type QueryEmptyCopy,
   LoadingState,

package/src/nav/types.ts

@@ -73,11 +73,14 @@ export type SidebarSection = {
 }
 
 /**
- * Status tone on a sidebar-block item — the same three-member vocabulary as `StatCardTone`, whose
- * members are `VX.status` keys by construction. Declared here rather than imported from
- * `../dashboard/stat-card`: this module is the one `./router-tanstack` reads, and even a
- * type-only edge into the Mantine layer would make `nav/types.d.ts` unresolvable without
- * `@mantine/core` installed.
+ * Status tone on a sidebar-block item — byte-identical to the common `Tone` vocabulary
+ * (`common/props.ts`, audit A13) and to `StatCardTone`, whose members are `VX.status` keys by
+ * construction. Declared here rather than aliased to `common`'s `Tone`: this module is the one
+ * `./router-tanstack` reads, and `common/props.ts` re-exports `Tier` (type-only) from
+ * `../widget-header/widget-header`, a Mantine-coupled file — importing anything from `common/props`
+ * here would pull that whole module's declaration graph into `nav/types.d.ts`, making it
+ * unresolvable without `@mantine/core` installed. Kept in step with `Tone` by convention, not by
+ * import.
  */
 export type SidebarBlockTone = 'good' | 'warn' | 'bad'
 
@@ -192,6 +195,12 @@ export type MobileNavConfig = {
   menuMax?: number
   /** @default 'More' */
   moreLabel?: string
-  /** Scroll container for active-slot re-tap. @default document.scrollingElement */
+  /**
+   * Scroll container for active-slot re-tap. Only needed when the page scrolls somewhere basalt
+   * cannot see — inside a shell the default already resolves `AppShell.Main`
+   * (`[data-basalt-scrollport]`), and outside one it falls back to the document.
+   *
+   * @default the `[data-basalt-scrollport]` element, else `document.scrollingElement`
+   */
   getScrollElement?: () => HTMLElement | null
 }

package/src/notifications/bell.tsx

@@ -18,13 +18,14 @@
 import { ActionIcon, Indicator, Popover } from '@mantine/core'
 import { useDisclosure } from '@mantine/hooks'
 import { useRef } from 'react'
+import type { BasaltProps } from '../common/props'
 import { useNotificationHistory } from './store'
-import { NotificationCenter } from './center'
+import { NOTIFICATION_POPOVER_WIDTH, NotificationCenter } from './center'
 
 const HOVER_OPEN_DELAY = 150
 const HOVER_CLOSE_DELAY = 200
 
-export type NotificationBellProps = {
+export type NotificationBellProps = BasaltProps & {
   /** Tooltip label. Default: 'Notifications'. */
   label?: string
 }
@@ -38,7 +39,11 @@ export type NotificationBellProps = {
  *   {...rest}
  * />
  */
-export function NotificationBell({ label = 'Notifications' }: NotificationBellProps) {
+export function NotificationBell({
+  label = 'Notifications',
+  className,
+  style,
+}: NotificationBellProps) {
   const [opened, { open, toggle, close }] = useDisclosure(false)
   const { unreadCount } = useNotificationHistory()
   const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
@@ -53,7 +58,14 @@ export function NotificationBell({ label = 'Notifications' }: NotificationBellPr
   }
 
   return (
-    <Popover opened={opened} onClose={close} position="bottom-end" withArrow withinPortal>
+    <Popover
+      opened={opened}
+      onClose={close}
+      position="bottom-end"
+      width={NOTIFICATION_POPOVER_WIDTH}
+      withArrow
+      withinPortal
+    >
       <Popover.Target>
         <Indicator
           color="color-mix(in srgb, var(--vx-ink) 8%, transparent)"
@@ -78,6 +90,8 @@ export function NotificationBell({ label = 'Notifications' }: NotificationBellPr
             aria-label={label}
             aria-expanded={opened}
             aria-haspopup="dialog"
+            {...(className !== undefined && { className })}
+            {...(style !== undefined && { style })}
           >
             {/* Bell icon (simple SVG — no @tabler/icons dep per house rules) */}
             <svg

package/src/notifications/center.tsx

@@ -25,6 +25,8 @@ import {
   Stack,
   Text,
 } from '@mantine/core'
+import type { BasaltProps } from '../common/props'
+import { cx } from '../common/props'
 import { VX } from '../tokens'
 import { resolveAction } from './define-notifications'
 import { useNotificationHistory } from './store'
@@ -64,6 +66,11 @@ const INTENT_STATUS: Record<NotificationIntent, string> = {
 
 type CenterView = 'inbox' | 'all'
 
+/** The popover width `NotificationBell` fixes at the `Popover` level (see `NotificationCenter`'s
+ *  own doc for why WIDTH lives there and not on this component). Shared so the two call sites and
+ *  this doc's example never drift apart. */
+export const NOTIFICATION_POPOVER_WIDTH = 320
+
 // ── NotificationItem ──────────────────────────────────────────────────────────
 
 function NotificationItem({
@@ -150,7 +157,7 @@ function NotificationItem({
 
 // ── NotificationCenter ────────────────────────────────────────────────────────
 
-export type NotificationCenterProps = {
+export type NotificationCenterProps = BasaltProps & {
   /** Maximum height of the scrollable list. Default: 320px. */
   maxHeight?: number | string
 }
@@ -160,16 +167,22 @@ export type NotificationCenterProps = {
  * registry-resolved action buttons. Designed to be mounted inside a Popover or Drawer (e.g.
  * NotificationBell).
  *
+ * Sizes to its host's full width (`width: 100%`) rather than a fixed px — a popover default that
+ * overflowed any inline mount. `NotificationBell` fixes the WIDTH at the Popover level instead
+ * (`<Popover width={NOTIFICATION_POPOVER_WIDTH}>`), which is the correct home for a
+ * popover-specific dimension; a consumer mounting this directly controls the same thing through
+ * its own container.
+ *
  * @example
- * import { NotificationCenter } from 'basalt-ui/notifications'
+ * import { NOTIFICATION_POPOVER_WIDTH, NotificationCenter } from 'basalt-ui/notifications'
  *
- * <Popover>
+ * <Popover width={NOTIFICATION_POPOVER_WIDTH}>
  *   <Popover.Dropdown>
  *     <NotificationCenter />
  *   </Popover.Dropdown>
  * </Popover>
  */
-export function NotificationCenter({ maxHeight = 320 }: NotificationCenterProps) {
+export function NotificationCenter({ maxHeight = 320, className, style }: NotificationCenterProps) {
   const { items, inbox, unreadCount, markRead, markAllRead, dismiss, dismissAll, remove, clear } =
     useNotificationHistory()
   const [view, setView] = useState<CenterView>('inbox')
@@ -178,7 +191,7 @@ export function NotificationCenter({ maxHeight = 320 }: NotificationCenterProps)
   const emptyLabel = view === 'inbox' ? "You're all caught up" : 'No notifications yet'
 
   return (
-    <Stack gap="xs" style={{ width: 320 }}>
+    <Stack className={cx(className)} gap="xs" style={{ width: '100%', ...style }}>
       {/* Header: title + a single mark-all-read affordance (only when there's something unread) */}
       <Group justify="space-between" align="center" wrap="nowrap">
         <Text size="sm" fw={600}>

package/src/notifications/define-notifications.ts

@@ -5,6 +5,11 @@
  * Consumer augments BasaltRegister.notifications with the spec map type, then uses the typed
  * `emit` helper which resolves the registered kind at compile-time. An unknown kind is a tsc error.
  *
+ * A kind's payload type is INFERRED, the same way `defineOverlays` infers an overlay's props from
+ * `render` — annotate `toMessage` (or `action.run`) with the payload shape and `emit` picks it up:
+ * `emit('saved', { id })` then requires that shape and a wrong one is a tsc error. A kind that never
+ * annotates either function keeps today's `payload?: unknown` — additive, no existing call breaks.
+ *
  * @example
  * // notifications.ts (app-side)
  * import { defineNotifications } from 'basalt-ui/notifications'
@@ -18,8 +23,9 @@
  *
  * // usage.ts
  * import { emit } from 'basalt-ui/notifications'
- * emit('upload:success', { name: 'photo.jpg' })  // ✓ typed
- * emit('nonexistent', {})                         // ✗ tsc error
+ * emit('upload:success', { name: 'photo.jpg' })  // ✓ typed, and the payload shape is checked
+ * emit('upload:success', 'nope')                  // ✗ tsc error — wrong payload shape
+ * emit('nonexistent', {})                         // ✗ tsc error — unregistered kind
  */
 import type { ReactNode } from 'react'
 import type { Slot } from '../register'
@@ -36,23 +42,33 @@ export type { NotificationIntent }
  * registry (code, app-scoped) — only a serializable `{ kind, payload }` ref is persisted — so an
  * actionable notification keeps working after a reload. The handler can do anything (navigate, open
  * a modal, retry a request); it receives the same payload that was passed to `emit`.
+ *
+ * The payload type P is the consumer's own payload — same generic shape as `Overlay<P>` in
+ * ./define-overlays, inferred from `run`'s parameter, not a separate declared field.
  */
-export type NotificationAction = {
+export type NotificationAction<P = unknown> = {
   label: string
-  run: (payload: unknown) => void
+  run: (payload: P) => void
 }
 
 // ── NotificationSpecMap ───────────────────────────────────────────────────────
 
-/** A single notification kind spec — intent + optional payload→message renderer + optional action. */
-export type NotificationSpec = {
+/**
+ * A single notification kind spec — intent + optional payload→message renderer + optional action.
+ *
+ * The payload type P is INFERRED from `toMessage`/`action.run`'s parameter, the same mechanism
+ * `defineOverlays`' `Overlay<P>` uses for `render`. Default `unknown` — a kind that annotates
+ * neither function keeps taking any payload, unchanged.
+ */
+export type NotificationSpec<P = unknown> = {
   intent?: NotificationIntent
-  toMessage?: (payload: unknown) => ReactNode
-  action?: NotificationAction
+  toMessage?: (payload: P) => ReactNode
+  action?: NotificationAction<P>
 }
 
 /** The map of kind → spec that a consumer registers. */
-export type NotificationSpecMap = Record<string, NotificationSpec>
+// oxlint-disable-next-line typescript/no-explicit-any -- load-bearing contravariant spec map, mirrors OverlayMap
+export type NotificationSpecMap = Record<string, NotificationSpec<any>>
 
 // ── Slot extraction (mirror of SeriesKey pattern in register.ts) ──────────────
 
@@ -66,11 +82,33 @@ type Notifications = Slot<'notifications', NotificationSpecMap>
  */
 export type NotificationKind = Extract<keyof Notifications, string>
 
+/**
+ * Extract the inferred payload type for a registered notification kind — mirrors `OverlayProps` in
+ * ./define-overlays (same `infer` over the generic spec type, not a separate declared field).
+ *
+ * Resolves to `unknown` for a kind whose spec never annotates `toMessage`/`action.run` with a
+ * payload shape — that is the additive fallback, not a failure to infer.
+ */
+type NotificationPayload<K extends NotificationKind> = Notifications extends {
+  [_K in K]: NotificationSpec<infer V>
+}
+  ? V
+  : unknown
+
 // ── defineNotification (singular) ────────────────────────────────────────────
 
 /**
- * Type a single notification spec without registering it.
- * Identity passthrough — preserves the exact literal shape for local type-checking.
+ * Type a single notification spec without registering it. Identity passthrough — the payload type
+ * `P` is INFERRED from `toMessage`/`action.run`'s parameter, exactly as it is inside
+ * `defineNotifications`, so a spec typed here and a spec written inline behave identically.
+ *
+ * **It is `NotificationSpec<P>`, NOT `<const T extends NotificationSpec>(spec: T): T`** — the
+ * const-generic shape every other `defineX` factory takes. Under `strictFunctionTypes` that
+ * constraint rejects the example below outright: `T` must extend `NotificationSpec<unknown>`, and a
+ * `toMessage: (p: { name: string }) => …` is not assignable to `(payload: unknown) => …`
+ * (parameters are contravariant). The factory's own documented usage did not compile. Inferring `P`
+ * instead is what makes an annotated payload the point of this file rather than a type error.
+ * `.type-guard.test.ts` pins both halves.
  *
  * **WARNING:** this does NOT register the spec in the runtime registry and does NOT
  * augment BasaltRegister. Use `defineNotifications` (plural) to register a full spec
@@ -85,7 +123,7 @@ export type NotificationKind = Extract<keyof Notifications, string>
  * // Merge into the full registry before passing to defineNotifications:
  * const NOTIFICATIONS = defineNotifications({ 'upload:success': uploadSuccess })
  */
-export function defineNotification<const T extends NotificationSpec>(spec: T): T {
+export function defineNotification<P = unknown>(spec: NotificationSpec<P>): NotificationSpec<P> {
   return spec
 }
 
@@ -116,6 +154,16 @@ export function defineNotifications<const T extends NotificationSpecMap>(spec: T
 
 // ── emit ──────────────────────────────────────────────────────────────────────
 
+/**
+ * The rest-args tuple for `emit`'s payload + opts. A kind whose spec declared a payload shape
+ * (`NotificationPayload<K>` is narrower than `unknown`) requires that shape as a real argument; a
+ * kind that never declared one keeps `payload?: unknown` — the pre-existing, backward-compatible
+ * shape.
+ */
+type EmitArgs<K extends NotificationKind> = [unknown] extends [NotificationPayload<K>]
+  ? [payload?: unknown, opts?: Omit<NotifyOptions, 'intent' | 'message'>]
+  : [payload: NotificationPayload<K>, opts?: Omit<NotifyOptions, 'intent' | 'message'>]
+
 /**
  * Emit a registered notification kind. The kind must be a key of the consumer's registered
  * `BasaltRegister.notifications` map — any other string is a tsc error.
@@ -123,17 +171,15 @@ export function defineNotifications<const T extends NotificationSpecMap>(spec: T
  * Resolves the spec's intent + toMessage, then calls notify(). Extra opts override spec defaults.
  *
  * Un-augmented (Notifications = {}): NotificationKind = never → `emit` is effectively uncallable.
- * Augmented: only the registered keys are accepted.
+ * Augmented: only the registered keys are accepted, and a kind whose spec annotated
+ * `toMessage`/`action.run` with a payload shape requires that shape — see {@link NotificationPayload}.
  *
  * @example
  * emit('upload:success', { name: 'photo.jpg' })
  * emit('upload:error', null, { title: 'Storage full' })
  */
-export function emit(
-  kind: NotificationKind,
-  payload?: unknown,
-  opts?: Omit<NotifyOptions, 'intent' | 'message'>,
-): string {
+export function emit<K extends NotificationKind>(kind: K, ...args: EmitArgs<K>): string {
+  const [payload, opts] = args
   // The kind's compile-time validity comes from the BasaltRegister slot; the runtime spec
   // (intent/toMessage/action) comes from the registry stashed by defineNotifications.
   const spec: NotificationSpec | undefined = activeRegistry[kind]

package/src/notifications/index.ts

@@ -19,6 +19,10 @@
  * notifyError('Failed', { title: 'Upload error' })
  * notifyPromise(save(), { loading: 'Saving…', success: 'Saved', error: 'Failed' })
  *
+ * // Optimistic mutation with an undo window (the toast's autoClose IS the window):
+ * import { notifyUndo } from 'basalt-ui/notifications'
+ * notifyUndo({ message: 'Item deleted', onUndo: () => restore(), onExpire: () => api.delete(id) })
+ *
  * // Shell bell (globalActions slot):
  * <BasaltShell globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]} ... />
  */
@@ -31,8 +35,15 @@ export {
   notifyWarning,
   notifyInfo,
   notifyPromise,
+  notifyUndo,
+  notifyUndoable,
+} from './notify'
+export type {
+  NotifyOptions,
+  NotifyPromiseMessages,
+  NotifyUndoOptions,
+  NotifyUndoHandle,
 } from './notify'
-export type { NotifyOptions, NotifyPromiseMessages } from './notify'
 
 // ── defineNotification + defineNotifications + typed emit ─────────────────────
 export {