basalt-ui 1.28.0 → 1.29.1

package/src/provider/index.tsx

@@ -15,20 +15,28 @@
  *
  * Mantine usage is allowed in this `./` root layer (unlike `src/charts/**` and `src/tokens/**`).
  */
-import { MantineProvider, useComputedColorScheme, useMantineTheme } from '@mantine/core'
+import {
+  MantineProvider,
+  useComputedColorScheme,
+  useMantineColorScheme,
+  useMantineTheme,
+} from '@mantine/core'
 import type { MantineProviderProps } from '@mantine/core'
 import { Component, useEffect, useMemo } from 'react'
 import type { ErrorInfo, ReactNode } from 'react'
 import { VxThemeProvider } from '../charts/theme'
-import { ConnectivityProvider } from '../connectivity'
-import type { ConnectivityProviderProps } from '../connectivity'
+import fallbackClasses from './error-fallback.module.css'
+import { ConnectivityProvider } from './connectivity-provider'
+import type { ConnectivityProviderProps } from './connectivity-types'
 import { cssVariablesResolver } from '../theme'
 import { useLabTheme } from './lab-theme'
 import { buildDensityCss, buildFontsCss, buildPaletteCss, buildRadiusCss } from '../tokens'
 import type { BuildPaletteOpts } from '../tokens'
 import { isDefaultDeriveConfig } from '../tokens/derive'
 import { buildPaletteData } from '../tokens/palette'
-import { isDev } from '../utils/is-dev'
+import { isDev } from '../common/is-dev'
+import { registerColorSchemeSetter } from '../commands/shell-bridge'
+import { PageTitle } from '../shell/page-title'
 
 /**
  * Where an error surfaced — drives consumer routing (a render error vs a global rejection differ).
@@ -97,25 +105,9 @@ export type BasaltProviderProps = {
    * Options threaded through to the auto-mounted `ConnectivityProvider` (everything except
    * `children`) — `sseUrl`, `healthUrl`, `healthIntervalMs`, and `override` (previously
    * unreachable through `BasaltProvider`: the only way to reach it was a second, shadowing
-   * `ConnectivityProvider`). Takes precedence over the deprecated flattened props below when both
-   * are set.
+   * `ConnectivityProvider`).
    */
   connectivity?: Omit<ConnectivityProviderProps, 'children'>
-  /**
-   * @deprecated Use `connectivity={{ sseUrl }}` instead. Still honoured when `connectivity` is
-   * unset or omits `sseUrl`; removed in 1.29.0.
-   */
-  sseUrl?: string
-  /**
-   * @deprecated Use `connectivity={{ healthUrl }}` instead. Still honoured when `connectivity` is
-   * unset or omits `healthUrl`; removed in 1.29.0.
-   */
-  healthUrl?: string
-  /**
-   * @deprecated Use `connectivity={{ healthIntervalMs }}` instead. Still honoured when
-   * `connectivity` is unset or omits `healthIntervalMs`; removed in 1.29.0.
-   */
-  healthIntervalMs?: number
 } & Omit<MantineProviderProps, 'children' | 'theme' | 'defaultColorScheme' | 'cssVariablesResolver'>
 
 // ── Default error handler ─────────────────────────────────────────────────────────────────────────
@@ -130,15 +122,54 @@ function defaultOnError(error: unknown, ctx: BasaltErrorContext): void {
 
 // ── Error boundary ────────────────────────────────────────────────────────────────────────────────
 
-type BoundaryProps = {
+/**
+ * `BasaltErrorBoundary`'s props — exported (C5 consolidation) so a consumer mounting a nested
+ * boundary can name the type, e.g. for a wrapper component's own prop forwarding.
+ */
+export type BasaltErrorBoundaryProps = {
   children: ReactNode
-  onError: (error: unknown, ctx: BasaltErrorContext) => void
-  /** Optional UI to render when a render error is caught. If a function, called with the error. Defaults to null. */
+  /**
+   * Report the caught render error. Unset → `defaultOnError` (console.error in dev, no-op in
+   * prod — the same fallback `BasaltProvider`'s own top-level `onError` uses), so a NESTED
+   * boundary mounted with no `onError` still surfaces something in dev instead of silently
+   * swallowing it.
+   */
+  onError?: (error: unknown, ctx: BasaltErrorContext) => void
+  /**
+   * UI to render when a render error is caught. If a function, called with the error. Unset →
+   * {@link DefaultErrorFallback} — a minimal `PageTitle` + reload button, never a silent `null`;
+   * pass `fallback={null}` explicitly for the old swallow-it behaviour.
+   */
   fallback?: ReactNode | ((error: unknown) => ReactNode)
 }
 
 type BoundaryState = { hasError: boolean; error: unknown }
 
+/**
+ * The boundary's own default fallback — a `PageTitle` (C5's shell-less page-title primitive, so
+ * this needs no `in-body-page-title` waiver) plus a plain reload affordance. Deliberately minimal:
+ * a consumer wanting session ids, a stack trace or a "try to recover" reset (argo's own
+ * `lib/error-boundary.tsx`) still passes its own `fallback` render function — this default exists
+ * so an app that mounts `BasaltErrorBoundary` and does nothing else shows a page, not a blank one.
+ */
+function DefaultErrorFallback(): ReactNode {
+  return (
+    <div className={fallbackClasses.root}>
+      <PageTitle
+        title="Something went wrong"
+        subtitle="The page hit an unexpected error and was unloaded to keep the app stable."
+      />
+      <button
+        type="button"
+        className={fallbackClasses.reload}
+        onClick={() => window.location.reload()}
+      >
+        Reload page
+      </button>
+    </div>
+  )
+}
+
 /**
  * Error boundary that catches render-phase errors inside `BasaltProvider`. Wraps `BasaltBridge` +
  * children INSIDE `MantineProvider` so a thrown render error still has theme context for a fallback.
@@ -149,8 +180,8 @@ type BoundaryState = { hasError: boolean; error: unknown }
  *   <MyFeature />
  * </BasaltErrorBoundary>
  */
-export class BasaltErrorBoundary extends Component<BoundaryProps, BoundaryState> {
-  constructor(props: BoundaryProps) {
+export class BasaltErrorBoundary extends Component<BasaltErrorBoundaryProps, BoundaryState> {
+  constructor(props: BasaltErrorBoundaryProps) {
     super(props)
     this.state = { hasError: false, error: undefined }
   }
@@ -160,13 +191,15 @@ export class BasaltErrorBoundary extends Component<BoundaryProps, BoundaryState>
   }
 
   override componentDidCatch(error: unknown, info: ErrorInfo): void {
-    this.props.onError(error, { kind: 'render', info })
+    const onError = this.props.onError ?? defaultOnError
+    onError(error, { kind: 'render', info })
   }
 
   override render(): ReactNode {
     if (this.state.hasError) {
       const { fallback } = this.props
-      if (fallback === undefined) return null
+      if (fallback === undefined) return <DefaultErrorFallback />
+      if (fallback === null) return null
       return typeof fallback === 'function' ? fallback(this.state.error) : fallback
     }
     return this.props.children
@@ -219,6 +252,15 @@ function BasaltBridge({
   // (fallback 'dark' before hydration, matching the provider's defaultColorScheme).
   const resolved = useComputedColorScheme('dark')
 
+  // `commands/shell-bridge.ts`'s `setColorScheme` handle — registered here (already inside
+  // `MantineProvider`) so a consumer's `commands.tsx` calls it with ZERO `__root.tsx` wiring,
+  // unlike argo's hand-rolled `color-scheme-bridge.ts` this seeds from (see that file's own doc).
+  const { setColorScheme: setMantineColorScheme } = useMantineColorScheme()
+  useEffect(() => {
+    registerColorSchemeSetter(setMantineColorScheme)
+    return () => registerColorSchemeSetter(null)
+  }, [setMantineColorScheme])
+
   // `createBasaltTheme`'s non-default `{ derive }` / `{ fonts }` / `{ radius }` / `{ density }`
   // paths stash the resolved values on `theme.other.basaltDerive` / `theme.other.basaltFonts` /
   // `theme.other.basaltRadius` / `theme.other.basaltDensity` — read them here (INSIDE
@@ -302,40 +344,6 @@ function useDuplicateProviderGuard(): void {
   }, [])
 }
 
-/**
- * Resolves the `connectivity` object against the three deprecated flattened props: `connectivity`
- * wins WHOLESALE when provided, not per-key — a partial `connectivity={{ sseUrl }}` no longer picks
- * up a stray `healthUrl` left on the old prop, which was surprising for a mid-migration consumer who
- * expected the new prop to fully replace the old ones once set. Warns once, dev builds only, when
- * both are actually supplied. Exported as a pure function (same rationale as `composeInjectedCss`
- * above) so `provider/index.test.ts` can assert the precedence without rendering a tree.
- */
-export function resolveConnectivityProps(props: {
-  connectivity: Omit<ConnectivityProviderProps, 'children'> | undefined
-  sseUrl: string | undefined
-  healthUrl: string | undefined
-  healthIntervalMs: number | undefined
-}): Omit<ConnectivityProviderProps, 'children'> {
-  if (props.connectivity !== undefined) {
-    const hasDeprecated =
-      props.sseUrl !== undefined ||
-      props.healthUrl !== undefined ||
-      props.healthIntervalMs !== undefined
-    if (hasDeprecated && isDev()) {
-      console.warn(
-        '[basalt] BasaltProvider: `connectivity` and one of `sseUrl`/`healthUrl`/`healthIntervalMs` ' +
-          'were both supplied — `connectivity` wins wholesale and the deprecated props are ignored.',
-      )
-    }
-    return props.connectivity
-  }
-  return {
-    ...(props.sseUrl !== undefined ? { sseUrl: props.sseUrl } : {}),
-    ...(props.healthUrl !== undefined ? { healthUrl: props.healthUrl } : {}),
-    ...(props.healthIntervalMs !== undefined ? { healthIntervalMs: props.healthIntervalMs } : {}),
-  }
-}
-
 // ── Public provider ───────────────────────────────────────────────────────────────────────────────
 
 export function BasaltProvider({
@@ -347,9 +355,6 @@ export function BasaltProvider({
   onError,
   nonce,
   connectivity,
-  sseUrl,
-  healthUrl,
-  healthIntervalMs,
   ...rest
 }: BasaltProviderProps) {
   useDuplicateProviderGuard()
@@ -361,12 +366,7 @@ export function BasaltProvider({
   // Basalt base and nothing else. See `./lab-theme.ts`.
   const resolvedTheme = useLabTheme(theme)
 
-  const resolvedConnectivity = resolveConnectivityProps({
-    connectivity,
-    sseUrl,
-    healthUrl,
-    healthIntervalMs,
-  })
+  const resolvedConnectivity = connectivity ?? {}
 
   return (
     // `...rest` spreads FIRST so a consumer's `MantineProviderProps` can never shadow the three

package/src/provider/lab-theme.ts

@@ -44,7 +44,7 @@ import { useMemo } from 'react'
 import { useDeriveControlsState, toDeriveOverride } from '../theme-lab/derive-state'
 import type { DeriveOverride } from '../theme-lab/derive-state'
 import { baseTheme, createBasaltTheme } from '../theme'
-import { isDev } from '../utils/is-dev'
+import { isDev } from '../common/is-dev'
 
 type Plain = Record<string, unknown>
 

package/src/{connectivity → provider}/use-connectivity.ts

@@ -2,8 +2,8 @@
  * useConnectivity — reads the aggregated connectivity status from ConnectivityContext.
  *
  * Throws if used outside a ConnectivityProvider. `BasaltProvider` auto-mounts
- * `ConnectivityProvider`, so this hook works with zero setup in the common case; the removed
- * `useOnlineStatus` (formerly `basalt-ui/state`) is replaced by this hook (see MIGRATING.md).
+ * `ConnectivityProvider`, so this hook works with zero setup in the common case. It replaced the
+ * former online-status hook that lived on `basalt-ui/state` (see MIGRATING.md).
  *
  * @example
  * const { status, details } = useConnectivity()
@@ -11,7 +11,7 @@
  */
 import { useContext } from 'react'
 import { ConnectivityContext } from './connectivity-provider'
-import type { ConnectivitySnapshot } from './types'
+import type { ConnectivitySnapshot } from './connectivity-types'
 
 export function useConnectivity(): ConnectivitySnapshot {
   const snapshot = useContext(ConnectivityContext)

package/src/query-client.ts

@@ -0,0 +1,105 @@
+/**
+ * `createBasaltQueryClient` + `unwrap` — the two TanStack Query primitives basalt ships. Folded
+ * onto the root barrel (C1 consolidation, dropping the `./query` subpath): the root already
+ * requires `@tanstack/react-query` as a peer, so a dedicated Mantine-free subpath bought nothing —
+ * and it re-exported 10 raw TanStack symbols no consumer imported through it.
+ * Optional peer: @tanstack/react-query.
+ */
+import { QueryClient } from '@tanstack/react-query'
+import type { QueryClientConfig } from '@tanstack/react-query'
+
+// ── createBasaltQueryClient ───────────────────────────────────────────────────────────────────────
+
+const BASALT_QUERY_DEFAULTS = {
+  staleTime: 30_000,
+  gcTime: 5 * 60 * 1000,
+  retry: 2,
+  refetchOnWindowFocus: false,
+} as const
+
+/**
+ * Wraps QueryClient with basalt dashboard defaults. All options are mergeable — consumer
+ * overrides win per-query, framework defaults are the fallback.
+ *
+ * @example
+ * import { createBasaltQueryClient } from 'basalt-ui'
+ * import { QueryClientProvider } from '@tanstack/react-query'
+ * import { useState } from 'react'
+ *
+ * function Root({ children }: { children: React.ReactNode }) {
+ *   const [client] = useState(() => createBasaltQueryClient())
+ *   return <QueryClientProvider client={client}>{children}</QueryClientProvider>
+ * }
+ */
+export function createBasaltQueryClient(config?: QueryClientConfig): QueryClient {
+  return new QueryClient({
+    ...config,
+    defaultOptions: {
+      ...config?.defaultOptions,
+      queries: { ...BASALT_QUERY_DEFAULTS, ...config?.defaultOptions?.queries },
+    },
+  })
+}
+
+// ── unwrap ────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Transport-agnostic unwrap for any `{ data, error }` envelope (Eden Treaty, raw fetch wrappers,
+ * etc.). TData is inferred from the data field. Throws on the error branch so failures surface
+ * to the nearest error boundary or TanStack Query's error state.
+ *
+ * Absence guard: if `error` is falsy but `data` is `null` OR `undefined`, unwrap throws with a
+ * descriptive message. This catches 204 No Content responses and silent transport failures that
+ * return `{ data: null, error: null }` — both signal an unexpected absence of data and should not
+ * silently resolve. `undefined` joined `null` here (C5 consolidation) so a hand-rolled fetch
+ * wrapper that leaves `data` unset on a miss — rather than explicitly `null` — is caught the same
+ * way; the two envelope shapes argo's own pre-basalt `unwrap` and basalt's ONLY differed on.
+ *
+ * **One generic signature, a conditional return** — a Promise of the envelope (basalt's original
+ * shape, `queryFn: () => unwrap(api.x.get())`) or the ALREADY-RESOLVED envelope itself
+ * (`unwrap(await api.x.get())`), both resolve `TData` off the same conditional. The two-overload
+ * form this replaced (1.29.0) resolved `unwrap` to `unknown` whenever it was passed as a bare
+ * callback — `.then(unwrap)` never applies an overload, it just reads the declared type of the
+ * `unwrap` reference — so `api.threads.get().then(unwrap)` silently widened. A single generic
+ * signature has exactly one type to read regardless of how the reference is used.
+ *
+ * @example
+ * import { unwrap } from 'basalt-ui'
+ *
+ * // Promise-of-envelope — queryFn:
+ * queryFn: () => unwrap(api.users.get({ query: params }))
+ * // mutation:
+ * mutationFn: (body) => unwrap(api.resource.post({ body }))
+ *
+ * // resolved-envelope — either shape, including a bare `.then(unwrap)` callback:
+ * const rows = unwrap(await api.users.get())
+ * const rows2 = await api.users.get().then(unwrap)
+ */
+export function unwrap<R extends Envelope | Promise<Envelope>>(response: R): UnwrapResult<R> {
+  if (response instanceof Promise) {
+    return response.then((envelope) => unwrapEnvelope(envelope)) as unknown as UnwrapResult<R>
+  }
+  return unwrapEnvelope(response as Envelope) as unknown as UnwrapResult<R>
+}
+
+/** Transport-agnostic `{ data, error }` result shape — Eden Treaty, a raw fetch wrapper, etc. */
+type Envelope<TData = unknown> = { data: TData | null | undefined; error: unknown }
+
+/** `unwrap`'s conditional return: a `Promise<TData>` when `R` is a promised envelope, `TData` when
+ * it is an already-resolved one — inferred off the SAME `R` the overload used to split on. */
+type UnwrapResult<R> =
+  R extends Promise<Envelope<infer TData>>
+    ? Promise<TData>
+    : R extends Envelope<infer TData>
+      ? TData
+      : never
+
+function unwrapEnvelope<TData>(envelope: Envelope<TData>): TData {
+  const { data, error } = envelope
+  if (error) throw error
+  if (data === null || data === undefined)
+    throw new Error(
+      'unwrap: null/undefined data with no error — check for a 204 response or a transport failure',
+    )
+  return data
+}

package/src/{query/devtools.tsx → query-devtools.tsx}

@@ -1,7 +1,8 @@
 /**
- * ./query/devtools — prod-safe lazy wrapper for @tanstack/react-query-devtools.
- * The devtools package is an OPTIONAL peer — never imported at module evaluation time.
- * The dynamic import() resolves only when rendered in non-production.
+ * `BasaltQueryDevtools` — prod-safe lazy wrapper for @tanstack/react-query-devtools. Folded onto
+ * the root barrel alongside `query-client.ts` (C1 consolidation, dropping the `./query` subpath).
+ * The devtools package is an OPTIONAL peer — never imported at module evaluation time. The dynamic
+ * import() resolves only when rendered in non-production.
  */
 import { lazy, Suspense } from 'react'
 import type { ComponentProps } from 'react'
@@ -18,7 +19,7 @@ Object.assign(LazyDevtools, { displayName: 'LazyDevtools' })
  * import fires. In production this returns null immediately.
  *
  * @example
- * import { BasaltQueryDevtools } from 'basalt-ui/query'
+ * import { BasaltQueryDevtools } from 'basalt-ui'
  *
  * function Root() {
  *   return (

package/src/register.ts

@@ -37,11 +37,27 @@ export interface BasaltRegister {}
  * slot instantiates against. At 1.0 the `series`, `commands`, `overlays`, and `notifications`
  * slots ship and have concrete instantiations (define-commands.ts, define-overlays.ts,
  * define-notifications.ts); `router`, `query`, and `state` remain advisory.
+ *
+ * **Indexed-access form, not a mapped-type structural match (C5 consolidation)** — this used to
+ * read `BasaltRegister extends { [P in K]: infer S extends Constraint } ? S : {}`, which forces
+ * TS to structurally match the WHOLE `BasaltRegister` interface (every augmented slot's VALUE
+ * type, not just `K`'s) before it can answer "does slot `K` exist". That is the commands↔overlays
+ * cycle argo's `lib/overlays.tsx` documents: `defineCommands`'s inferred type has to type-check a
+ * command `run` body calling `overlays.open(…)`, which resolves `Slot<'overlays', …>` — and the
+ * OLD form's whole-interface match ALSO had to resolve `BasaltRegister['commands']`
+ * (`typeof COMMANDS`, the very type still being computed) to complete the match, because a
+ * mapped-type pattern binds every property simultaneously. `K extends keyof BasaltRegister` only
+ * needs the augmented KEY NAMES (available from declaration merging with no value-type checking
+ * at all), and `BasaltRegister[K]` then touches ONLY that one slot's value — so resolving
+ * `overlays` never has to resolve `commands` first, and a consumer can define both registries,
+ * with one calling the other's imperative controller, in a SINGLE file. Behaviourally identical to
+ * the old form for every existing augmentation (fixture J.1/J.2 pin both the `{}` fallback and the
+ * `Extract<keyof, string>` guard below); ONLY the internal resolution path changed.
  */
-export type Slot<K extends string, Constraint> = BasaltRegister extends {
-  [P in K]: infer S extends Constraint
-}
-  ? S
+export type Slot<K extends string, Constraint> = K extends keyof BasaltRegister
+  ? BasaltRegister[K] extends Constraint
+    ? BasaltRegister[K]
+    : {}
   : {}
 
 /** The consumer's registered series map, or `{}` when un-augmented. */

package/src/router-tanstack/index.ts

@@ -4,12 +4,11 @@
  * Carries the typed navigation definition (`defineNav`/`navGroup`/`navTarget`/`flattenNav`) and
  * `useNav`, which resolves it into `BasaltShell`'s `sections` + `mobileNav` props; plus the
  * StaticDataRouteOption augmentation (title/icon/navSection) for router-derived breadcrumbs, plus
- * `createSearchStore` + the `field.*` vocabulary (and the two deprecated enum-only wrappers it
- * replaced) — no Mantine, no JSX.
+ * `createSearchStore` + the `field.*` vocabulary — no Mantine, no JSX.
  */
 
 export { createSearchStore, type CreateSearchStoreOptions, type SearchStore } from './search-store'
-export { field } from './field'
+export { field } from '../state'
 export type {
   AnyField,
   BooleanField,
@@ -32,17 +31,7 @@ export type {
   SearchValues,
   StoredValues,
   StringField,
-} from './field'
-export {
-  createSearchParamStore,
-  type SearchParamStore,
-  type SearchParamStoreOptions,
-} from './search-param-store'
-export {
-  createMultiSearchParamStore,
-  type MultiSearchParamStore,
-  type MultiSearchParamStoreOptions,
-} from './multi-search-param-store'
+} from '../state'
 export { defineNav, navGroup, navTarget, flattenNav } from './nav'
 export type {
   NavItemMeta,
@@ -59,7 +48,7 @@ export type {
 } from './nav'
 export { useNav } from './use-nav'
 export type { UseNavOptions, NavBinding } from './use-nav'
-export type { NavAnchor, NavAnchorProps, NavMobilePlacement } from '../nav/types'
+export type { NavAnchor, NavAnchorProps, NavMobilePlacement } from '../shell/nav-types'
 import type { ReactNode } from 'react'
 import { useLocation, useMatches } from '@tanstack/react-router'
 

package/src/router-tanstack/nav.ts

@@ -12,7 +12,7 @@
  * No JSX and no Mantine in this module — `./router-tanstack` is a headless barrel by contract.
  */
 import type { ReactNode } from 'react'
-import type { NavMobilePlacement, NavSectionMobile } from '../nav/types'
+import type { NavMobilePlacement, NavSectionMobile } from '../shell/nav-types'
 
 // ── authoring shapes ─────────────────────────────────────────────────────────────────────────────
 

package/src/router-tanstack/search-store.ts

@@ -212,12 +212,11 @@ function isMemoryLane(entry: StoreEntry): boolean {
 }
 
 /**
- * The store, plus the one knob the deprecated wrappers need: `legacyValueField` keeps the
- * enum-only stores' single-value storage layout so an already-persisted selection still resolves.
- * Not exported from the barrel — `createSearchStore` is the public door.
+ * The store's implementation. Not exported from the barrel — `createSearchStore` is the public
+ * door.
  */
 export function buildSearchStore<const S extends Record<string, AnyField>>(
-  o: CreateSearchStoreOptions<S> & { legacyValueField?: string },
+  o: CreateSearchStoreOptions<S>,
 ): InternalSearchStore<S> {
   assertNoLazyUrlFallback(o.key, o.fields)
   const core = createStoreCore(o)

package/src/router-tanstack/use-nav.ts

@@ -12,7 +12,7 @@
 import { createElement, useMemo } from 'react'
 import type { ElementType, ReactNode } from 'react'
 import { Link, useMatchRoute, useRouterState } from '@tanstack/react-router'
-import type { MobileNavConfig, NavAnchor, SidebarItem, SidebarSection } from '../nav/types'
+import type { MobileNavConfig, NavAnchor, SidebarItem, SidebarSection } from '../shell/nav-types'
 import { flattenNav } from './nav'
 import type { AnyNavGroup, AnyNavItem, NavConfig, NavItemId, NavTabId } from './nav'
 

package/src/shell/app-breadcrumbs.tsx

@@ -12,7 +12,7 @@
  */
 import { Anchor, Group, Text } from '@mantine/core'
 import type { CSSProperties } from 'react'
-import type { NavAnchor } from '../nav/types'
+import type { NavAnchor } from './nav-types'
 import { VX } from '../tokens'
 import type { BasaltProps } from '../common/props'
 import classes from './app-header.module.css'

package/src/shell/app-main.module.css

@@ -105,3 +105,14 @@
    * tracks those instead. The HEIGHT is flex's job and needs no transition of its own. */
   transition-property: margin;
 }
+
+/* Installed PWA (C5 consolidation, seeded from argo's `styles/native.css`): clear the landscape
+ * notch on the side Main touches. `max()` is a FLOOR over `.main`'s own `padding` shorthand above
+ * — same mechanism as `app-sidebar.module.css`'s left counterpart. The bottom inset already rides
+ * `margin-bottom` above (`env(safe-area-inset-bottom)`); the PWA's top inset needs no rule here
+ * (the status bar uses the opaque `default` style, per argo's own seed comment). */
+@media (display-mode: standalone) {
+  .main {
+    padding-right: max(var(--app-shell-padding), env(safe-area-inset-right));
+  }
+}

package/src/shell/app-mobile-nav.tsx

@@ -34,7 +34,7 @@ import type {
   SidebarItem,
   SidebarListBlock,
   SidebarProgressBlock,
-} from '../nav/types'
+} from './nav-types'
 import type { BasaltAccountProps } from './account-types'
 import type { SettingsMenuItem } from './index'
 import { NavCountBadge } from './nav-count-badge'
@@ -95,6 +95,26 @@ function IconMore() {
   )
 }
 
+/** The `ActionRow.active` glyph — same shape as `app-sidebar.tsx`'s own copy (no icon dependency
+ * to import between the two render trees). */
+function IconCheck() {
+  return (
+    <svg
+      width={14}
+      height={14}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <path d="M5 12l5 5l10 -10" />
+    </svg>
+  )
+}
+
 /** A row the More surface derives from `account`/`settingsMenuItems` — never a destination. */
 type ActionRow = {
   key: string
@@ -102,6 +122,8 @@ type ActionRow = {
   icon?: ReactNode
   danger?: boolean
   onClick?: ((e: MouseEvent<HTMLElement>) => void) | undefined
+  /** Mirrors `SettingsMenuItem.active` — a trailing check + `aria-current` in every row form. */
+  active?: boolean
 }
 
 /**
@@ -172,6 +194,7 @@ function settingsRows(items: SettingsMenuItem[] | undefined): ActionRow[] {
     label: item.label,
     icon: item.icon,
     onClick: item.onClick,
+    ...(item.active !== undefined && { active: item.active }),
   }))
 }
 
@@ -234,8 +257,10 @@ const menuActionRow = (row: ActionRow) => (
     key={row.key}
     className={classes.menuItem}
     leftSection={row.icon}
+    rightSection={row.active ? <IconCheck /> : undefined}
     {...(row.danger ? { color: 'red' } : {})}
     onClick={(event: MouseEvent<HTMLElement>) => row.onClick?.(event)}
+    aria-current={row.active ? 'true' : undefined}
   >
     {row.label}
   </Menu.Item>
@@ -480,11 +505,13 @@ export function MobileNav({
       classNames={{ root: classes.row }}
       label={row.label}
       leftSection={row.icon}
+      rightSection={row.active ? <IconCheck /> : undefined}
       {...(row.danger ? { color: 'red' } : {})}
       onClick={(event: MouseEvent<HTMLElement>) => {
         row.onClick?.(event)
         close()
       }}
+      aria-current={row.active ? 'true' : undefined}
     />
   )
 

package/src/shell/app-sidebar.module.css

@@ -26,6 +26,16 @@
   padding: 0 var(--vx-space-row-inset-x);
 }
 
+/* Installed PWA (C5 consolidation, seeded from argo's `styles/native.css`): clear the landscape
+ * notch on the side the sidebar touches. `max()` is a FLOOR — the inset only grows the padding
+ * past its normal value, never shrinks it. Right inset is `app-main.module.css`'s to draw; the
+ * PWA's top inset needs no rule here (the status bar uses the opaque `default` style). */
+@media (display-mode: standalone) {
+  .root {
+    padding-left: max(var(--vx-space-row-inset-x), env(safe-area-inset-left));
+  }
+}
+
 .link {
   font-size: var(--vx-text-md);
   border-radius: var(--vx-radius-ctrl) !important;