basalt-ui 1.30.2 → 1.31.0

package/src/shell/page-aside.tsx

@@ -13,7 +13,10 @@
  * WHERE it renders is decided by context and viewport, never by a prop:
  *
  * - **Inside `BasaltShell`, from `sm` up** the panel portals into `AppShell.Aside`, folding to a
- *   `appShellAsideRailWidth` rail with one expand button.
+ *   `appShellAsideRailWidth` rail with one expand button. It DOCKS (pushes main) only while main
+ *   keeps its floor width; otherwise it opens as an overlay over main and starts folded. The overlay
+ *   is a persistent panel closed by its own fold button, or by Escape (the shell's keyboard escape
+ *   hatch — `shell/index.tsx`'s `asideOverlay` effect) — it is not click-away dismissable.
  * - **Below `sm`, with a `PageBar` that renders a row 2**, the panel PROJECTS into that row: it
  *   registers its title and glyph with the page-bar slot, renders no node of its own, and row 2
  *   draws one `Panel` pill opening a `FilterSheet` its children portal into. One node at a time —
@@ -43,18 +46,17 @@
  * read stays in JS — through `useSyncExternalStore`, so SSR, hydration and the first paint agree.
  * Recorded in `docs/CONTROLS-SPEC.md` §1 (C9) and `docs/ASIDE-SPEC.md` §0.
  */
-import { createContext, useCallback, useContext, useMemo, useState } from 'react'
+import { createContext, useCallback, useContext, useMemo, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import { createPortal } from 'react-dom'
-import { useMantineTheme } from '@mantine/core'
 import { cx } from '../common/props'
 import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
 import { usePersistedOrLocal } from '../state/persisted-or-local'
 import { FilterSetScope } from '../controls/filter-context'
 import { useAsidePanelSlot } from './page-bar'
-import { useIsomorphicLayoutEffect } from './isomorphic-layout-effect'
-import { useMediaQueryMatches } from './use-breakpoint'
+import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
+import { useSizeClass } from './use-size-class'
 import classes from './page-aside.module.css'
 
 type AsideRegion = {
@@ -70,6 +72,14 @@ type AsideRegion = {
   folded: boolean
   claim: () => () => void
   publishFolded: (folded: boolean) => void
+  /**
+   * Bumped by `requestClose` — never 0 again once a close has been requested, so `PageAside` can
+   * treat "changed since mount" as "fold now" without a ref of its own. `ShellFrame` is the one
+   * caller, on Escape while the aside renders as an overlay.
+   */
+  closeSignal: number
+  /** Asks the claiming `PageAside` to fold — the keyboard escape hatch for the overlay form. */
+  requestClose: () => void
 }
 
 const NO_REGION: AsideRegion = {
@@ -80,6 +90,8 @@ const NO_REGION: AsideRegion = {
   folded: false,
   claim: () => () => {},
   publishFolded: () => {},
+  closeSignal: 0,
+  requestClose: () => {},
 }
 
 const AsideContext = createContext<AsideRegion>(NO_REGION)
@@ -92,6 +104,7 @@ export function AsideProvider({ children }: { children: ReactNode }): ReactNode
   const [target, setTarget] = useState<HTMLElement | null>(null)
   const [claims, setClaims] = useState(0)
   const [folded, setFolded] = useState(false)
+  const [closeSignal, setCloseSignal] = useState(0)
 
   const claim = useCallback(() => {
     setClaims((n) => n + 1)
@@ -102,6 +115,8 @@ export function AsideProvider({ children }: { children: ReactNode }): ReactNode
     }
   }, [])
 
+  const requestClose = useCallback(() => setCloseSignal((n) => n + 1), [])
+
   const value: AsideRegion = {
     target,
     setTarget,
@@ -110,17 +125,28 @@ export function AsideProvider({ children }: { children: ReactNode }): ReactNode
     folded,
     claim,
     publishFolded: setFolded,
+    closeSignal,
+    requestClose,
   }
 
   return <AsideContext.Provider value={value}>{children}</AsideContext.Provider>
 }
 
-/** Internal — the region's state, read by `BasaltShell` to size `AppShell.Aside`. */
-export function useAsideRegion(): Pick<AsideRegion, 'claimed' | 'folded'> {
-  const { claimed, folded } = useContext(AsideContext)
-  return { claimed, folded }
+/** Internal — the region's state, read by `BasaltShell` to size `AppShell.Aside` and to request a
+ * close (the Escape hatch on the overlay form). */
+export function useAsideRegion(): Pick<AsideRegion, 'claimed' | 'folded' | 'requestClose'> {
+  const { claimed, folded, requestClose } = useContext(AsideContext)
+  return { claimed, folded, requestClose }
 }
 
+/**
+ * Internal — whether an OPEN aside would push the main column (expanded, main keeps its floor)
+ * rather than overlay it. Provided by `ShellFrame`, which alone knows the navbar width, from the
+ * same render that computes it: a state published after mount would make the first pass read
+ * "cannot dock" and fold a default-open aside for one commit.
+ */
+export const AsideDocksContext = createContext(false)
+
 /** Internal — the node inside `AppShell.Aside` the active page's panel portals into. */
 export function AsideOutlet({ className }: { className?: string }) {
   const { setTarget } = useContext(AsideContext)
@@ -136,7 +162,10 @@ export type PageAsideProps = BasaltProps &
     title: string
     /** Persists the fold at `basalt:aside:<persistKey>`. Omit for an unpersisted fold. */
     persistKey?: string
-    /** Fold state on first render, respected only while nothing is persisted. @default false */
+    /**
+     * The fold while the user has not chosen one — an explicit (persisted or toggled) choice always
+     * wins. @default open where the aside docks beside main, folded where it would overlay it
+     */
     defaultFolded?: boolean
     children: ReactNode
   }
@@ -214,26 +243,25 @@ export function PageAside(props: PageAsideProps): ReactNode {
   assertRequiredProps('PageAside', props, ['title'], {
     title: 'it names the region — it is the header text AND the `aria-label` on the landmark.',
   })
-  const { title, persistKey, defaultFolded = false, children, className, style, classNames } = props
-  const { target, inShell, claim, publishFolded } = useContext(AsideContext)
+  const { title, persistKey, defaultFolded, children, className, style, classNames } = props
+  const { target, inShell, claim, publishFolded, closeSignal } = useContext(AsideContext)
+  const docks = useContext(AsideDocksContext)
   // Destructured, not held as one object: the hook returns a fresh literal every render, and the
   // claim effect below would then re-run (claim → release → claim) forever. `claimPanel` is a
   // `useCallback` on the provider, so it is the stable half.
   const { host: panelHost, claim: claimPanel, target: panelTarget } = useAsidePanelSlot()
-  const theme = useMantineTheme()
-  // `sm` is the only breakpoint (`docs/CONTROLS-SPEC.md` §2), read off the theme so a consumer that
-  // retunes it moves the aside with it. THE declared C9 exception (see this file's header): the
-  // read is JS because the two projections are two portal targets under two filter surfaces, and a
-  // CSS twin would double-mount stateful children. `useSyncExternalStore` is what keeps SSR, the
-  // hydration pass and the first client paint agreeing on which single node exists.
-  const desktop = useMediaQueryMatches(`(min-width: ${theme.breakpoints.sm})`, true)
+  // THE declared C9 exception (see this file's header): the read is JS because the two projections
+  // are two portal targets under two filter surfaces, and a CSS twin would double-mount stateful
+  // children. `useSizeClass` (`useSyncExternalStore`) keeps SSR, the hydration pass and the first
+  // client paint agreeing on which single node exists.
+  const isCompact = useSizeClass() === 'compact'
   const [folded, setFolded] = usePersistedOrLocal({
     scope: 'aside',
     persistKey,
-    initial: defaultFolded,
+    initial: defaultFolded ?? !docks,
   })
 
-  const portalled = inShell && desktop
+  const portalled = inShell && !isCompact
   // Below `sm` the panel goes into the page bar's row 2 IF there is one. Without a row 2 there is
   // nowhere to put a trigger, so the honest in-flow form (wave 1) stays.
   const projected = !portalled && panelHost
@@ -268,6 +296,27 @@ export function PageAside(props: PageAsideProps): ReactNode {
     publishFolded(folded)
   }, [portalled, folded, publishFolded])
 
+  // The Escape hatch (`shell/index.tsx`'s `asideOverlay` effect): `closeSignal` is monotonic and
+  // shared across every `PageAside` the shell ever mounts, so "past the initial 0" is the wrong
+  // question for any instance mounted AFTER the first Escape elsewhere in the app's lifetime — it
+  // would read the ALREADY-bumped signal as "a close was requested" on its very first commit and
+  // fold before the user ever asked. `closeSignalBaseline` captures the value THIS instance mounted
+  // with, so only a change AFTER that point — a close requested while this instance is live — folds
+  // it; a later-mounted instance still respects its own `defaultFolded`/persisted state. Guarded on
+  // `portalled`, matching where `ShellFrame` can even observe an overlay to escape out of.
+  //
+  // The baseline ADVANCES to every `closeSignal` it acts on — not just at mount. Without that, a
+  // portalled false→true transition (the aside leaving and rejoining the shell, e.g. a viewport
+  // resize crossing `sm`) re-runs this effect with `closeSignal` still sitting on the value the
+  // FIRST Escape already bumped it to, which the baseline — frozen at its pre-Escape value — reads
+  // as "a close was just requested" all over again and folds an aside the user had since reopened.
+  const closeSignalBaseline = useRef(closeSignal)
+  useIsomorphicLayoutEffect(() => {
+    if (!portalled || closeSignal === closeSignalBaseline.current) return
+    closeSignalBaseline.current = closeSignal
+    setFolded(true)
+  }, [portalled, closeSignal])
+
   useIsomorphicLayoutEffect(() => {
     if (!projected) return
     return claimPanel(panelClaim)

package/src/shell/page-bar.module.css

@@ -46,6 +46,8 @@
 }
 
 .row1 {
+  /* Fills the header's elastic outlet, so `.row1End` below is the ROOM the action fold measures. */
+  width: 100%;
   display: flex;
   flex-wrap: nowrap;
   align-items: center;
@@ -188,42 +190,16 @@
 }
 
 /*
- * Law C15 — every touch target inside a home is at least `touchControlHeight` (36px at level 0)
- * below `sm`, while the VISIBLE box stays the 30px `ctl` tier. `::after` and not `::before`:
- * Mantine's Button owns `::before` for its loading overlay (`@mantine/core/styles/Button.css`),
- * so a hit area drawn there would fight it. `pointer-events` stays default so the overlay is the
- * one receiving the tap.
- *
- * `overflow: visible` is LOAD-BEARING, not tidying. Mantine's Button and ActionIcon roots both set
- * `overflow: hidden` (`Button.css`, `ActionIcon.css`), which clips an overlay that by definition
- * extends past the 30px box — so without this the 36px target simply does not exist and a tap 3px
- * above the control misses. What `overflow: hidden` buys those roots is clipping the loading
- * overlay's blur, and that overlay is only painted under `[data-loading]`, which is excluded below.
+ * Law C15 — controls in a home adopt the shared `[data-basalt-hit]` overlay (`styles.css`) through
+ * `data-basalt-hit-scope` on `.row1`/`.row2`; `--vx-hit-gap` caps the expansion at the real gap so
+ * neighbours' hit boxes never overlap. The VISIBLE box stays the 30px `ctl` tier.
  */
-@media (max-width: 47.99375em) {
-  .row1 :is(button, a),
-  .row2 :is(button, a) {
-    position: relative;
-  }
-
-  .row1 :is(button, a):not([data-loading]),
-  .row2 :is(button, a):not([data-loading]) {
-    overflow: visible;
-  }
-
-  .row1 :is(button, a)::after,
-  .row2 :is(button, a)::after {
-    content: '';
-    position: absolute;
-    top: 50%;
-    left: 50%;
-    translate: -50% -50%;
-    width: 100%;
-    height: 100%;
-    min-width: var(--vx-space-touch-control-height);
-    min-height: var(--vx-space-touch-control-height);
-  }
+.row1,
+.row2 {
+  --vx-hit-gap: var(--vx-space-control-gap);
+}
 
+@media (max-width: 52.49375em) {
   /*
    * Row 2's phone form: two declared lines, tabs then pills — not a wrap (law C7). `.pills` folds
    * every overflow into `Filters (n)` at any width, EXCEPT when it holds nothing visible: below `sm`

package/src/shell/page-bar.tsx

@@ -28,13 +28,18 @@ import { createPortal } from 'react-dom'
 import { cx } from '../common/props'
 import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { CtlSlot } from '../theme'
-import { BarActionRow, BarExtrasProvider, globalActionAsBarAction } from '../controls/actions'
+import {
+  BarActionRow,
+  BarExtrasProvider,
+  PAGE_BAR_END_ATTR,
+  globalActionAsBarAction,
+} from '../controls/actions'
 import { FilterPill } from '../controls/filter-pill'
 import { FilterSheet } from '../controls/filter-sheet'
 import { SyncButton } from '../controls/sync-button'
 import type { ActionGroupProps, BarAction, GlobalAction } from '../controls/actions'
 import type { SyncButtonProps } from '../controls/sync-button'
-import { useIsomorphicLayoutEffect } from './isomorphic-layout-effect'
+import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
 import classes from './page-bar.module.css'
 import asideClasses from './page-aside.module.css'
 
@@ -388,7 +393,7 @@ export function PageBar({
   }, [inShell, hasRow2, claimPanelHost])
 
   const row1 = hasRow1 ? (
-    <div className={cx(classes.row1, classNames?.row1)}>
+    <div className={cx(classes.row1, classNames?.row1)} data-basalt-hit-scope>
       {hasLead && (
         <div className={classes.lead}>
           {icon !== undefined && (
@@ -399,7 +404,7 @@ export function PageBar({
           {title !== undefined && <h1 className={classes.title}>{title}</h1>}
         </div>
       )}
-      <div className={classes.row1End}>
+      <div className={classes.row1End} {...{ [PAGE_BAR_END_ATTR]: '' }}>
         {(actions !== undefined || filtersEndActions.length > 0 || sync !== undefined) && (
           <CtlSlot>
             {/* THE row-1 group: the only `host: 'page'` instance, so the shell's `mobile: 'more'`
@@ -430,7 +435,7 @@ export function PageBar({
   const hasPills = filters !== undefined || panel !== null || filtersEndActions.length > 0
 
   const row2 = hasRow2 ? (
-    <div className={cx(classes.row2, classNames?.row2)}>
+    <div className={cx(classes.row2, classNames?.row2)} data-basalt-hit-scope>
       {tabs !== undefined && (
         <div className={classes.tabs} data-basalt-page-bar-line="tabs">
           <CtlSlot>{tabs}</CtlSlot>

package/src/shell/use-breakpoint.ts

@@ -1,21 +1,12 @@
 /**
- * `useBreakpoint` — one media-query hook over the theme's own breakpoints, SSR/hydration-safe.
- *
- * Built on `useSyncExternalStore`, NOT `@mantine/hooks`' `useMediaQuery` — that hook reads
- * `matchMedia` inside a `useState` initializer, so on the server it returns its `fallback` and on
- * the client's very first render it returns the REAL match; when that render is a hydration pass
- * the two disagree silently (a server-rendered desktop layout hydrating on a phone against a
- * client tree that already moved). `useSyncExternalStore`'s `getServerSnapshot` makes React render
- * the server's answer during hydration and correct itself immediately after — the documented,
- * warning-free version of the same fix. `page-aside.tsx`'s own former private
- * `useMediaQueryMatches` carried this exact rationale; it now lives here and page-aside composes
- * this hook instead (C5 consolidation — one media-query hook, not two).
+ * `useBreakpoint` — DEPRECATED (on notice in `MIGRATING.md`, removed next minor): use
+ * `useSizeClass` from `./use-size-class`. One media-query hook over the theme's own breakpoints,
+ * built on the shared `useMediaQuery` (`common/use-media-query`) — SSR/hydration-safe.
  *
  * `edge` defaults to `'min'` (`"at least this wide"`); pass `'max'` for `"narrower than"`. The
  * `fallback` (what the server, and a shim with no `matchMedia`, sees) defaults to the answer that
  * assumes the NARROW side of the query — `false` for `min`, `true` for `max` — since a component
- * library cannot know a consumer's real device mix; a call site with its own rationale (e.g.
- * `page-aside.tsx`'s desktop-first portal fallback) overrides it via `options.fallback`.
+ * library cannot know a consumer's real device mix; `options.fallback` overrides it.
  *
  * @example
  * import { useBreakpoint } from 'basalt-ui'
@@ -24,43 +15,16 @@
  * const isNarrow = !useBreakpoint('sm')             // < theme.breakpoints.sm
  * const isWide = useBreakpoint('lg')                // >= theme.breakpoints.lg
  */
-import { useCallback, useMemo, useSyncExternalStore } from 'react'
 import { useMantineTheme } from '@mantine/core'
+import { useMediaQuery } from '../common/use-media-query'
 
 export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
 
-/** `window.matchMedia`, or `null` where there is no window and on a shim that does not ship it. */
-function mediaQueryList(query: string): MediaQueryList | null {
-  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return null
-  return window.matchMedia(query)
-}
-
 /**
- * Internal — the raw media-query read. Exported (not `default`) so `page-aside.tsx` can compose
- * it directly for its `(min-width: theme.breakpoints.sm)` desktop check without re-deriving the
- * query string `useBreakpoint` builds for the fixed `BreakpointName` union.
+ * @deprecated Use `useSizeClass` — removed next minor (see `MIGRATING.md`). `theme.breakpoints` is
+ * now derived: `sm` moved 48em → 52.5em and `md`/`lg`/`xl` all sit at 75em (`xs`/`sm` collapse,
+ * `md`/`lg`/`xl` collapse).
  */
-export function useMediaQueryMatches(query: string, fallback: boolean): boolean {
-  // ONE `MediaQueryList` per query, held across renders — `matchMedia()` allocates a fresh live
-  // object on every call, and `getSnapshot` runs on every render AND after every store
-  // notification, so calling it there would churn an object per read while `subscribe` listened
-  // on a different instance than `getSnapshot` measured.
-  const list = useMemo(() => mediaQueryList(query), [query])
-  const subscribe = useCallback(
-    (onStoreChange: () => void) => {
-      if (list === null) return () => {}
-      list.addEventListener('change', onStoreChange)
-      return () => {
-        list.removeEventListener('change', onStoreChange)
-      }
-    },
-    [list],
-  )
-  const getSnapshot = useCallback(() => list?.matches ?? fallback, [list, fallback])
-  const getServerSnapshot = useCallback(() => fallback, [fallback])
-  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
-}
-
 export function useBreakpoint(
   name: BreakpointName,
   edge: 'min' | 'max' = 'min',
@@ -69,5 +33,5 @@ export function useBreakpoint(
   const theme = useMantineTheme()
   const bp = theme.breakpoints[name]
   const fallback = options?.fallback ?? edge === 'max'
-  return useMediaQueryMatches(`(${edge}-width: ${bp})`, fallback)
+  return useMediaQuery(`(${edge}-width: ${bp})`, fallback)
 }

package/src/shell/use-size-class.ts

@@ -0,0 +1,31 @@
+/**
+ * `useSizeClass` — the viewport axis of the responsive law (`docs/DESIGN-CORE.md` § Layout,
+ * elevation, shapes):
+ * `'compact' | 'medium' | 'expanded'`, for the JS reads CSS cannot express (portal targets,
+ * mount-one-of-two branches). Shell-only — components size by container, not by this.
+ *
+ * Built on `useMediaQuery` (`common/use-media-query`), one call per class boundary. The server
+ * snapshot is `<BasaltProvider sizeClassHint>` (default `'compact'`), so SSR, the hydration pass
+ * and the first client paint agree, and the real class lands one commit later — no first-frame
+ * flash from a `matchMedia` read inside a `useState` initializer.
+ */
+import { createContext, useContext } from 'react'
+import { useMediaQuery } from '../common/use-media-query'
+import { SIZE_CLASSES, toEm } from '../tokens/size-classes'
+
+export type SizeClass = keyof typeof SIZE_CLASSES
+
+/** Provided by `BasaltProvider`'s `sizeClassHint`; the server snapshot. `undefined` = no provider. */
+export const SizeClassHintContext = createContext<SizeClass | undefined>(undefined)
+
+export function useSizeClass(): SizeClass {
+  const hint = useContext(SizeClassHintContext) ?? 'compact'
+  const isMedium = useMediaQuery(`(min-width: ${toEm(SIZE_CLASSES.medium)})`, hint !== 'compact')
+  const isExpanded = useMediaQuery(
+    `(min-width: ${toEm(SIZE_CLASSES.expanded)})`,
+    hint === 'expanded',
+  )
+  if (isExpanded) return 'expanded'
+  if (isMedium) return 'medium'
+  return 'compact'
+}

package/src/state/persisted-or-local.ts

@@ -13,7 +13,7 @@
  *
  * Not exported from `../state` — this is an internal hook, not part of the `./state` surface.
  */
-import { useMemo, useState } from 'react'
+import { useCallback, useMemo, useState } from 'react'
 import { createPersistedState } from './persisted'
 
 /** The key an unpersisted caller parks on — never read, because that branch returns local state. */
@@ -28,10 +28,14 @@ export function usePersistedOrLocal<T>({
   scope: string
   /** Persist under `basalt:<scope>:<persistKey>`. Omitted → local state, nothing written. */
   persistKey: string | undefined
-  /** First-render value, respected only while nothing is persisted. */
+  /**
+   * The value while the user has not chosen one — unset, NOT "written as this". It may change
+   * between renders (a size-class default) and the flag follows until a set call pins it.
+   */
   initial: T
 }): readonly [T, (next: T) => void] {
-  const [local, setLocal] = useState(initial)
+  // Boxed so "never set" (`null`) stays distinct from a set value of any `T`, falsy ones included.
+  const [local, setLocal] = useState<{ value: T } | null>(null)
   // `createPersistedState` is a per-key module FACTORY, so it is memoized rather than called during
   // render — the same reason `shell/index.tsx` memoizes its collapse store.
   const usePersisted = useMemo(
@@ -44,7 +48,9 @@ export function usePersistedOrLocal<T>({
     [scope, persistKey, initial],
   )
   const [persisted, setPersisted] = usePersisted()
+  // Stable across renders like the persisted setter — a value-only setter, so no updater form.
+  const setLocalValue = useCallback((next: T) => setLocal({ value: next }), [])
 
   if (persistKey !== undefined) return [persisted, setPersisted] as const
-  return [local, setLocal] as const
+  return [local === null ? initial : local.value, setLocalValue] as const
 }

package/src/state/persisted.ts

@@ -16,6 +16,9 @@ const noopSubscribe =
   (_cb: () => void): (() => void) =>
   () => {}
 
+// Nothing has been written as far as the server can tell.
+const serverIsSet = (): boolean => false
+
 export type PersistedStateOptions<T> = {
   /** localStorage key (will be namespaced as `basalt:<key>`). */
   readonly key: string
@@ -81,40 +84,59 @@ function isEnvelope(raw: unknown): raw is Envelope {
   )
 }
 
-/** Parse a raw localStorage string (or null) into a value, falling back to `initial` on any miss. */
-function parseStorage<T>(raw: string | null, opts: PersistedStateOptions<T>): T {
-  if (raw === null) return opts.initial
+/**
+ * One parse pass over a raw localStorage string: the value AND whether the store ACCEPTED what it
+ * found. `accepted` is false for a miss, garbage, a wrong version with no `migrate`, or a value the
+ * schema rejects — every case that falls back to `initial`, so `isSet` never claims a choice that
+ * was not honoured.
+ */
+function parseStorage<T>(
+  raw: string | null,
+  opts: PersistedStateOptions<T>,
+): { value: T; accepted: boolean } {
+  const miss = { value: opts.initial, accepted: false }
+  if (raw === null) return miss
   try {
     const parsed: unknown = JSON.parse(raw)
-    if (!isEnvelope(parsed)) return opts.initial
+    if (!isEnvelope(parsed)) return miss
 
     let value: unknown = parsed.value
 
     if (parsed.v !== opts.version) {
-      value = opts.migrate ? opts.migrate(parsed.value, parsed.v) : opts.initial
+      if (!opts.migrate) return miss
+      value = opts.migrate(parsed.value, parsed.v)
     }
 
     if (opts.schema) {
       const result = opts.schema['~standard'].validate(value)
       // Async schema — can't await in sync storage path; fall back to initial
-      if (result instanceof Promise) return opts.initial
-      if (result.issues !== undefined) return opts.initial
+      if (result instanceof Promise) return miss
+      if (result.issues !== undefined) return miss
       // Narrowed to SuccessResult<T> — value is T
-      return result.value
+      return { value: result.value, accepted: true }
     }
 
-    return value as T
+    return { value: value as T, accepted: true }
   } catch {
-    return opts.initial
+    return miss
   }
 }
 
+/**
+ * Values a write could not persist (storage blocked, full, private mode), by namespaced key. An
+ * explicit user choice then still wins for the rest of the session instead of snapping back to the
+ * default; a successful write or a `storage` event for the key drops the entry.
+ */
+const unpersisted = new Map<string, { value: unknown }>()
+
 function writeEnvelope(storageKey: string, version: number, value: unknown): void {
   try {
     const envelope: Envelope = { v: version, value }
     window.localStorage.setItem(storageKey, JSON.stringify(envelope))
+    unpersisted.delete(storageKey)
   } catch {
-    // Silently fail (storage full, private browsing, etc.)
+    // Storage full or blocked: keep the value in memory rather than lose the choice.
+    unpersisted.set(storageKey, { value })
   }
 }
 
@@ -137,6 +159,25 @@ function writeStorage<T>(opts: PersistedStateOptions<T>, next: T): void {
 export function createPersistedState<T>(
   opts: PersistedStateOptions<T>,
 ): () => readonly [T, (next: T) => void] {
+  const useStore = createPersistedStore(opts)
+  return function usePersistedState() {
+    const [value, setValue] = useStore()
+    return [value, setValue] as const
+  }
+}
+
+/**
+ * `createPersistedState` plus a third tuple element: `isSet`, false until a value is written or a
+ * stored one is accepted (a stale-version or schema-invalid envelope is NOT set).
+ * `value` alone cannot say — an unset key and an explicit write of `initial` both read as `initial`,
+ * and a default that depends on context (the shell's size-class collapse default) may apply to the
+ * first only.
+ *
+ * @internal Not exported from the `basalt-ui/state` barrel.
+ */
+export function createPersistedStore<T>(
+  opts: PersistedStateOptions<T>,
+): () => readonly [T, (next: T) => void, boolean] {
   const storageKey = `basalt:${opts.key}`
 
   const subscribe = (cb: () => void): (() => void) => {
@@ -148,7 +189,10 @@ export function createPersistedState<T>(
     // when the last one leaves (cleanup semantics preserved).
     if (channel.handler === null) {
       channel.handler = (e: StorageEvent): void => {
-        if (e.key === storageKey) notify(storageKey)
+        if (e.key !== storageKey) return
+        // Another tab's write (or removal) is newer than anything this tab failed to persist.
+        unpersisted.delete(storageKey)
+        notify(storageKey)
       }
       window.addEventListener('storage', channel.handler)
     }
@@ -171,9 +215,12 @@ export function createPersistedState<T>(
   // the object/array case (chat history, form drafts).
   let cachedRaw: string | null = null
   let cachedValue: T = opts.initial
+  let cachedIsSet = false
   let primed = false
 
   const getSnapshot = (): T => {
+    const override = unpersisted.get(storageKey)
+    if (override !== undefined) return override.value as T
     let raw: string | null
     try {
       raw = window.localStorage.getItem(storageKey)
@@ -181,11 +228,17 @@ export function createPersistedState<T>(
       raw = null
     }
     if (primed && raw === cachedRaw) return cachedValue
+    const parsed = parseStorage(raw, opts)
     cachedRaw = raw
-    cachedValue = parseStorage(raw, opts)
+    cachedValue = parsed.value
+    cachedIsSet = parsed.accepted
     primed = true
     return cachedValue
   }
+  const getIsSet = (): boolean => {
+    getSnapshot()
+    return unpersisted.has(storageKey) || cachedIsSet
+  }
   const getServerSnapshot = (): T => opts.initial
 
   const setState = (next: T): void => {
@@ -198,15 +251,21 @@ export function createPersistedState<T>(
   // Detect SSR once at creation time — the environment doesn't change between renders.
   const isServer = typeof window === 'undefined'
 
-  return function usePersistedState(): readonly [T, (next: T) => void] {
+  return function usePersistedStore(): readonly [T, (next: T) => void, boolean] {
+    // SSR guard — subscribe must not reference `window` on the server.
+    const listen = isServer ? noopSubscribe : subscribe
     const value = useSyncExternalStore<T>(
-      // SSR guard — subscribe must not reference `window` on the server.
-      isServer ? noopSubscribe : subscribe,
+      listen,
       isServer ? getServerSnapshot : getSnapshot,
       getServerSnapshot,
     )
+    const isSet = useSyncExternalStore<boolean>(
+      listen,
+      isServer ? serverIsSet : getIsSet,
+      serverIsSet,
+    )
 
-    return [value, setState] as const
+    return [value, setState, isSet] as const
   }
 }