basalt-ui 1.30.2 → 1.31.0

package/dist/tokens.css

@@ -5,7 +5,7 @@
   --vx-radius-fine: 4px;
   --vx-radius-floating: 8px;
   --vx-radius-pill: 9999px;
-  --vx-space-touch-target: 44px;
+  --vx-hit: 24px;
   --vx-space-row-inset-x: 10px;
   --vx-space-row-inset-y: 6px;
   --vx-space-row-line-height: 1.35;
@@ -14,7 +14,6 @@
   --vx-space-control-height-tag: 1.25rem;
   --vx-space-control-height-widget: 1.5rem;
   --vx-space-control-height-ctl: 2rem;
-  --vx-space-touch-control-height: 2.25rem;
   --vx-space-stack-xs: 4px;
   --vx-space-stack-sm: 8px;
   --vx-space-stack-md: 12px;
@@ -103,7 +102,7 @@
   --vx-space-mobile-nav-icon-size: 24px;
   --vx-space-mobile-nav-tab-inset-y: 2px;
   --vx-space-mobile-nav-tab-inset-x: 12px;
-  --vx-space-mobile-nav-row-height: 40px;
+  --vx-space-mobile-nav-row-height: 44px;
   --vx-space-agent-rail-inset-x: 10px;
   --vx-space-agent-part-gap-top: 6px;
   --vx-space-agent-code-inset: 8px;
@@ -190,12 +189,17 @@
   --vx-badRef: var(--vx-bad-ref);
   --vx-warnRef: var(--vx-warn-ref);
 }
-@media (max-width: 47.99375em) {
+@media (max-width: 52.49375em) {
   :root {
     --vx-space-card-inset-x: 11px;
     --vx-space-section-gap: 8px;
   }
 }
+@media (pointer: coarse) {
+  :root {
+    --vx-hit: 44px;
+  }
+}
 :root,
 html[data-mantine-color-scheme='dark'] {
   --vx-status-excellent: #43bf4d;

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.30.2
+# basalt-ui v1.31.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,11 +19,11 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.30.2
+Version: 1.31.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'
-Description: BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useBreakpoint, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)
+Description: BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useSizeClass (useBreakpoint on notice), NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)
 Layer: mantine-coupled
 Rule: basalt-mantine
 OptionalPeers: react-markdown@^10.1.0, remark-gfm@^4.0.1, rehype-sanitize@^6.0.0, remend@1.3.0, shiki@^4.3.0, beautiful-mermaid@^1.1.0, @tanstack/react-router-devtools@^1.166.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.30.2",
+  "version": "1.31.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",
@@ -162,19 +162,19 @@
     "clean": "rm -rf dist"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "0.18.3",
-    "@fontsource-variable/hubot-sans": "5.2.8",
-    "@fontsource-variable/jetbrains-mono": "5.2.8",
-    "@fontsource-variable/nunito-sans": "5.2.7",
+    "@arethetypeswrong/cli": "0.18.5",
+    "@fontsource-variable/hubot-sans": "5.3.0",
+    "@fontsource-variable/jetbrains-mono": "5.3.0",
+    "@fontsource-variable/nunito-sans": "5.3.0",
     "@mantine/dates": "9.3.0",
-    "@shikijs/langs": "^4.3.1",
-    "@shikijs/themes": "^4.3.1",
+    "@shikijs/langs": "^4.4.3",
+    "@shikijs/themes": "^4.4.3",
     "@tanstack/react-hotkeys": "0.10.0",
-    "@tanstack/react-router-devtools": "^1.166.13",
-    "@types/bun": "^1.3.14",
-    "@types/hast": "^3.0.4",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
+    "@tanstack/react-router-devtools": "^1.167.2",
+    "@types/bun": "^1.4.2",
+    "@types/hast": "^3.0.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@visx/axis": "4.0.0",
     "@visx/curve": "4.0.0",
     "@visx/event": "4.0.0",
@@ -184,19 +184,19 @@
     "@visx/scale": "4.0.0",
     "@visx/shape": "4.0.0",
     "@visx/threshold": "4.0.0",
-    "ai": "^7.0.15",
+    "ai": "^7.0.107",
     "beautiful-mermaid": "^1.1.3",
     "motion": "12.42.0",
-    "publint": "0.3.21",
+    "publint": "0.3.24",
     "react-markdown": "^10.1.0",
     "rehype-sanitize": "6.0.0",
     "remark-gfm": "^4.0.1",
-    "remend": "1.3.0",
-    "shiki": "^4.3.1",
+    "remend": "1.3.1",
+    "shiki": "^4.4.3",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "use-stick-to-bottom": "^1.1.6",
-    "vite": "^8.0.16",
+    "vite": "^8.3.0",
     "vite-plugin-pwa": "^1.3.0"
   },
   "peerDependencies": {

package/src/agent-chat/composer.tsx

@@ -36,13 +36,14 @@
  *   onSubmit={({ text, attachments }) => send(text, attachments)}
  * />
  */
-import { ActionIcon, Group, Kbd, Stack, Text, Textarea } from '@mantine/core'
+import { ActionIcon, Box, Group, Kbd, Stack, Text, Textarea } from '@mantine/core'
 import type { ClipboardEvent, ComponentProps, JSX, KeyboardEvent, ReactNode, Ref } from 'react'
 import { useImperativeHandle, useLayoutEffect, useRef, useSyncExternalStore } from 'react'
 import { cx } from '../common/props'
 import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { readPersistedValue } from '../state'
 import { VX } from '../tokens'
+import { useKeyboardInsetRef } from './use-keyboard-inset'
 
 /** A minimal, dependency-free send-arrow glyph (icons are passed in as ReactNode elsewhere; this
  * one is inline since Composer has no icon prop in its contract). */
@@ -202,6 +203,14 @@ export type ComposerSubmit = {
 /** Stable empty list — keeps the submit payload's `attachments` referentially constant. */
 const NO_ATTACHMENTS: readonly ComposerAttachment[] = []
 
+/**
+ * The gap between the textarea/actions row and the hint row, inside the inner `Stack` the render
+ * below owns exclusively — the keyboard-inset spacer is deliberately NOT one of that Stack's flex
+ * children (see the render's own comment), so this value never has to be cancelled back out of
+ * anything the spacer contributes.
+ */
+const ROOT_GAP = 6
+
 /**
  * Imperative escape hatch for slot content that must write into the composer from OUTSIDE the
  * render tree — a voice recorder streaming transcript chunks, a suggestion chip inserting at the
@@ -471,6 +480,13 @@ export function Composer({
 
   useImperativeHandle(ref, () => ({ insertText, setValue, focus: focusTextarea }))
 
+  // Pins the composer above a coarse-pointer on-screen keyboard — see use-keyboard-inset.ts. The
+  // published custom property defaults to 0px via CSS, so a Composer with no `visualViewport`
+  // support (SSR, an unsupporting engine) pays for exactly one no-op custom property on a trailing
+  // spacer (see the render below) rather than an inline `paddingBottom` that could ever beat a
+  // consumer's own `className`/`classNames.root` padding.
+  const keyboardInsetRef = useKeyboardInsetRef()
+
   const submit = (): void => {
     if (inputDisabled || !hasPayload) return
     const submittedText = trimmed
@@ -572,51 +588,62 @@ export function Composer({
   const showActions = showStop || showSend
 
   return (
-    <Stack
-      gap={6}
-      className={cx(classNames?.root, className)}
-      {...(style !== undefined && { style })}
-    >
-      <Group gap="xs" align="flex-end" wrap="nowrap">
-        {leftSection}
-        <Textarea {...textareaProps} ref={textareaRef} />
-        {rightSection}
-        {showActions && (
-          <Group gap="xs" wrap="nowrap" className={cx(classNames?.actions)}>
-            {showStop ? (
-              <ActionIcon
-                size={42}
-                radius="md"
-                variant="filled"
-                color="red"
-                onClick={onStop}
-                aria-label="Stop generating"
-              >
-                <StopGlyph />
-              </ActionIcon>
-            ) : null}
-            {showSend ? (
-              <ActionIcon
-                size={42}
-                radius="md"
-                variant="filled"
-                onClick={submit}
-                disabled={inputDisabled || !hasPayload}
-                aria-label="Send message"
-                // Send action (docs/DESIGN-SPEC.md §5): the one accent-filled control. It needs no
-                // color override — `filled` resolves through the theme to `--vx-accent-fill` /
-                // `--vx-on-accent`. (It used to hand-wire those two vars inline, which is why this
-                // was the ONLY filled control that stayed legible while the rest of the chrome went
-                // through Mantine's scheme-blind autoContrast. The theme owns it now, and hover
-                // works again — an inline style can't express a `:hover` state.)
-              >
-                <SendGlyph />
-              </ActionIcon>
-            ) : null}
-          </Group>
-        )}
-      </Group>
-      {hint === undefined ? <DefaultHint /> : hint}
-    </Stack>
+    <Box ref={keyboardInsetRef} className={cx(classNames?.root, className)} style={style}>
+      <Stack gap={ROOT_GAP}>
+        <Group gap="xs" align="flex-end" wrap="nowrap">
+          {leftSection}
+          <Textarea {...textareaProps} ref={textareaRef} />
+          {rightSection}
+          {showActions && (
+            <Group gap="xs" wrap="nowrap" className={cx(classNames?.actions)}>
+              {showStop ? (
+                <ActionIcon
+                  size={42}
+                  radius="md"
+                  variant="filled"
+                  color="red"
+                  onClick={onStop}
+                  aria-label="Stop generating"
+                >
+                  <StopGlyph />
+                </ActionIcon>
+              ) : null}
+              {showSend ? (
+                <ActionIcon
+                  size={42}
+                  radius="md"
+                  variant="filled"
+                  onClick={submit}
+                  disabled={inputDisabled || !hasPayload}
+                  aria-label="Send message"
+                  // Send action (docs/DESIGN-SPEC.md §5): the one accent-filled control. It needs
+                  // no color override — `filled` resolves through the theme to `--vx-accent-fill`
+                  // / `--vx-on-accent`. (It used to hand-wire those two vars inline, which is why
+                  // this was the ONLY filled control that stayed legible while the rest of the
+                  // chrome went through Mantine's scheme-blind autoContrast. The theme owns it
+                  // now, and hover works again — an inline style can't express a `:hover` state.)
+                >
+                  <SendGlyph />
+                </ActionIcon>
+              ) : null}
+            </Group>
+          )}
+        </Group>
+        {hint === undefined ? <DefaultHint /> : hint}
+      </Stack>
+      {/* Pins the composer above a coarse-pointer on-screen keyboard by growing THIS spacer, not
+          by padding the root — so a consumer's own `className`/`classNames.root` padding-bottom is
+          never overridden (see use-keyboard-inset.ts). It is a SIBLING of the gapped Stack above,
+          not one of its flex children, precisely so it never has to cancel that Stack's `gap`
+          back out: a consumer's own `style` (which lands on this outer, non-flex root, not on the
+          inner Stack) can carry an unrelated `gap` without ever touching what this spacer
+          contributes. A closed keyboard (the var's `0px` fallback) then really is 0 extra height,
+          regardless of anything the caller's `style`/`className` does to the root. (This used to
+          be the Stack's own trailing child, cancelled via a negative `margin-top` reading
+          `--stack-gap` back — exact against Stack's OWN `gap` prop, but blind to a `gap` a
+          consumer added on top through `style`, which changes the rendered gap without moving that
+          var.) */}
+      <Box aria-hidden style={{ height: 'var(--vx-keyboard-inset, 0px)' }} />
+    </Box>
   )
 }

package/src/agent-chat/thread-workspace.tsx

@@ -4,7 +4,7 @@
  * Composes `ThreadFeed` + a new-thread `Composer` (left/main pane) with `ThreadDetailPanel`
  * (right pane) over `useAgentThreadRuns`, so a consumer wires one component instead of hand-
  * assembling the pieces. Responsive: wide viewports show both panes side by side; narrow
- * viewports (`<= 768px`) show exactly one — the feed when no thread is open, a full-screen
+ * viewports (the `compact` size class, < 840px) show exactly one — the feed when no thread is open, a full-screen
  * detail panel once one is.
  *
  * `useThreads` is a prop, not called internally, because `createThreadsStore` must be invoked
@@ -32,14 +32,14 @@
  *   )
  * }
  */
-import { Box, Divider, Flex, Skeleton, Stack, Text, useMantineTheme } from '@mantine/core'
-import { useMediaQuery } from '@mantine/hooks'
+import { Box, Divider, Flex, Skeleton, Stack, Text } from '@mantine/core'
 import type { JSX, ReactNode } from 'react'
 import type { AgentPart, AgentTransport, OutcomeResolver, ThreadsStore } from '../agent'
 import { useAgentThreadRuns } from '../agent'
 import { cx } from '../common/props'
 import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
+import { useSizeClass } from '../shell/use-size-class'
 import { VX } from '../tokens'
 import { Composer } from './composer'
 import { ThreadDetailPanel } from './thread-detail-panel'
@@ -53,7 +53,7 @@ const FULL_HEIGHT_STYLE = { height: '100%' } as const
 
 /** The four boxes `ThreadWorkspace` paints: `root` is the outermost pane split, `feed` is the
  * thread-list pane, `composer` is the new-thread composer pinned under the feed, `detail` is the
- * right-hand (or, below 768px, full-screen) open-thread pane. */
+ * right-hand (or, in the `compact` size class, full-screen) open-thread pane. */
 export type ThreadWorkspaceSlot = 'root' | 'feed' | 'composer' | 'detail'
 
 export type ThreadWorkspaceProps = BasaltProps &
@@ -146,7 +146,7 @@ function FeedErrorState(): JSX.Element {
 /**
  * A two-pane master-detail thread workspace: a scrollable feed of threads with an anchored
  * new-thread composer, and a detail panel for the open thread's live transcript. Collapses to a
- * single pane below 768px.
+ * single pane in the `compact` size class (< 840px).
  *
  * @example
  * <ThreadWorkspace useThreads={useThreads} transport={transport} resolveOutcome={heuristicOutcome} />
@@ -165,12 +165,9 @@ export function ThreadWorkspace({
   assertRequiredProps('ThreadWorkspace', { useThreads }, ['useThreads'])
   const store = useThreads()
   const runs = useAgentThreadRuns({ transport, store, resolveOutcome })
-  // Matches `shell/page-aside.tsx`'s own `theme.breakpoints.sm` desktop check — read off the theme,
-  // not hardcoded, so a consumer that retunes `breakpoints.sm` moves the aside and this workspace
-  // together. `max-width` is the min-width complement: `sm − 0.00625em` (the same 0.1px offset
-  // Mantine's own CSS breakpoints use), so the two checks never straddle the same pixel.
-  const theme = useMantineTheme()
-  const narrow = useMediaQuery(`(max-width: calc(${theme.breakpoints.sm} - 0.00625em))`)
+  // Narrow = the compact size class — the same viewport axis as the shell, and SSR/first-frame
+  // correct (the provider's `sizeClassHint` is the server snapshot, no post-mount flip).
+  const narrow = useSizeClass() === 'compact'
 
   const threads = store.threads
   const activeThread = threads.find((thread) => thread.id === store.activeId) ?? null

package/src/agent-chat/use-keyboard-inset.ts

@@ -0,0 +1,68 @@
+/**
+ * `useKeyboardInsetRef` — publishes the live on-screen-keyboard inset as `--vx-keyboard-inset` on
+ * a ref'd root element, so `Composer` can stay pinned above a coarse-pointer on-screen keyboard
+ * without the consumer hand-rolling a `dvh` clamp (`docs/MATURATION-LEDGER.md`, the wave 10
+ * agent-chat finding). Internal — not exported from the package.
+ *
+ * Reads `window.visualViewport`, guarded exactly like `useSizeClass`'s `matchMedia` guard
+ * (`shell/use-size-class.ts`): absent in SSR and in an engine with no `visualViewport` support
+ * (older Safari, and happy-dom/jsdom in tests), where the property is simply never published and
+ * CSS's `var(--vx-keyboard-inset, 0px)` fallback carries the zero.
+ *
+ * The inset is `document.documentElement.clientHeight - visualViewport.height -
+ * visualViewport.offsetTop`, floored at 0 — the slice of the LAYOUT viewport's bottom edge the
+ * visual viewport no longer covers. `clientHeight` (not `window.innerHeight`) is the layout
+ * viewport's height on every engine that also implements `visualViewport`. Both `resize` (fires
+ * when the on-screen keyboard opens/closes and shrinks `visualViewport.height`) and `scroll`
+ * (fires when the visual viewport's origin moves with no size change — iOS Safari scrolling the
+ * page to keep a focused field in view) are subscribed, because either can move the inset on its
+ * own.
+ *
+ * The state-node + layout-effect shape mirrors `shell/page-bar.tsx`'s `useMeasuredHeightVar`: a
+ * callback ref stored in state (so the effect re-runs once the node actually mounts) rather than a
+ * plain `RefObject` (which is not itself a dependency).
+ *
+ * Returns the callback ref only. It intentionally does NOT track the live inset (open/closed) —
+ * that stays an imperative, no-re-render style write, which is the entire point of publishing it
+ * outside React state.
+ */
+import { useCallback, useState } from 'react'
+import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
+
+const KEYBOARD_INSET_VAR = '--vx-keyboard-inset'
+
+export function useKeyboardInsetRef(): (el: HTMLElement | null) => void {
+  const [node, setNode] = useState<HTMLElement | null>(null)
+
+  const attach = useCallback((el: HTMLElement | null) => {
+    setNode(el)
+  }, [])
+
+  useIsomorphicLayoutEffect(() => {
+    if (node === null) return
+    if (typeof window === 'undefined') return
+    const viewport = window.visualViewport
+    // `undefined`, not the typed `null`, is what an engine with no support actually returns
+    // (confirmed: happy-dom — this package's test DOM — has no `visualViewport` property at all).
+    if (viewport === null || viewport === undefined) return
+
+    const publish = (): void => {
+      const inset = Math.max(
+        0,
+        document.documentElement.clientHeight - viewport.height - viewport.offsetTop,
+      )
+      node.style.setProperty(KEYBOARD_INSET_VAR, `${inset}px`)
+    }
+
+    publish()
+    viewport.addEventListener('resize', publish)
+    viewport.addEventListener('scroll', publish)
+    return () => {
+      viewport.removeEventListener('resize', publish)
+      viewport.removeEventListener('scroll', publish)
+      node.style.removeProperty(KEYBOARD_INSET_VAR)
+    }
+  }, [node])
+
+  return attach
+}

package/src/charts/cursor/touch-pin.ts

@@ -0,0 +1,138 @@
+/**
+ * Two small pieces shared by every touch-pinned surface in the chart layer — extracted so
+ * `useChartCursor`/`useDiscreteCursor`/`ChartLegend`'s disclosure cannot drift apart on the same
+ * contract (round 2's carried-forward gap: each had its own hand-rolled copy).
+ */
+import { useCallback, useEffect, useMemo, useRef } from 'react'
+
+/**
+ * Outside-tap / Escape / scroll (optionally resize) dismissal for a pinned/open floating element.
+ * Capture-phase `pointerdown` so a descendant that stops propagation on its own handler can't leave
+ * the dismissal stuck.
+ */
+export function useDismissOnOutside({
+  enabled,
+  isInside,
+  onDismiss,
+  dismissOnResize = false,
+  scrollExemptInside = false,
+}: {
+  enabled: boolean
+  /** A tap (or, with `scrollExemptInside`, a scroll) landing where this returns true doesn't
+   * dismiss. Omit to treat every tap as outside. */
+  isInside?: (target: Node) => boolean
+  onDismiss: () => void
+  /** Also dismiss on a window `resize` — `ChartLegend`'s disclosure needs this, the touch-pinned
+   * cursors don't (their host doesn't reflow independently of the chart it's pinned to). */
+  dismissOnResize?: boolean
+  /** Exempts a scroll whose target is `isInside` — `ChartLegend`'s own scrollable panel needs this
+   * (`overflowY: auto`), the cursor hooks don't (a chart has no internal scroller to protect). */
+  scrollExemptInside?: boolean
+}): void {
+  useEffect(() => {
+    if (!enabled) return
+    const onPointerDown = (event: PointerEvent) => {
+      if (event.target instanceof Node && isInside?.(event.target) === true) return
+      onDismiss()
+    }
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') onDismiss()
+    }
+    const onScroll = (event: Event) => {
+      if (scrollExemptInside && event.target instanceof Node && isInside?.(event.target) === true) {
+        return
+      }
+      onDismiss()
+    }
+    document.addEventListener('pointerdown', onPointerDown, true)
+    document.addEventListener('keydown', onKeyDown)
+    document.addEventListener('scroll', onScroll, true)
+    if (dismissOnResize) window.addEventListener('resize', onDismiss)
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown, true)
+      document.removeEventListener('keydown', onKeyDown)
+      document.removeEventListener('scroll', onScroll, true)
+      if (dismissOnResize) window.removeEventListener('resize', onDismiss)
+    }
+  }, [enabled, isInside, onDismiss, dismissOnResize, scrollExemptInside])
+}
+
+export type TouchPin = {
+  /** `onPointerDown` for a coarse press: snapshots whatever is currently committed (via
+   * `getCommitted`) so a later `cancel` can restore exactly that, then tracks `pointerId`. */
+  begin: (pointerId: number) => void
+  /** `onPointerUp` for the tracked pointer: the press is now committed — nothing left to revert. */
+  commit: (pointerId: number) => boolean
+  /** `onPointerCancel`/`onPointerLeave` for the tracked pointer: the browser took the gesture (a
+   * scroll) before the press committed — restores the pre-press value via `setCommitted`, or
+   * leaves it clear when nothing was committed before. Returns whether this pointer was tracked. */
+  cancel: (pointerId: number) => boolean
+  /** Hard reset — no restore, just drop any in-flight press bookkeeping (an explicit `clear()`, e.g.
+   * Escape or an outside tap, is about to overwrite the value directly anyway). */
+  reset: () => void
+}
+
+/**
+ * Provisional-press state machine shared by `useChartCursor`/`useDiscreteCursor`: a coarse press
+ * shows a value immediately (PROVISIONAL, not yet committed) — `commit` on `pointerup` leaves it in
+ * place, `cancel` on `pointercancel`/`pointerleave` (a scroll winning the gesture) restores whatever
+ * was committed before this press started, rather than dropping it. This is what keeps a previously
+ * COMMITTED pin alive through a second tap that gets cancelled instead of completed.
+ */
+export function useTouchPin<V>({
+  getCommitted,
+  setCommitted,
+}: {
+  /** Reads the value currently committed — snapshotted on `begin`, restored on `cancel`. */
+  getCommitted: () => V
+  setCommitted: (value: V) => void
+}): TouchPin {
+  const pressRef = useRef<number | null>(null)
+  const backupRef = useRef<V | undefined>(undefined)
+  // Whether `backupRef` holds a real snapshot — `backupRef.current !== undefined` used to stand in
+  // for this, which silently dropped a genuinely committed `undefined` (a caller's `V` can legally
+  // include it): `cancel` would restore nothing at all instead of restoring "nothing was pinned".
+  const hasBackupRef = useRef(false)
+  const getCommittedRef = useRef(getCommitted)
+  getCommittedRef.current = getCommitted
+  const setCommittedRef = useRef(setCommitted)
+  setCommittedRef.current = setCommitted
+
+  const begin = useCallback((pointerId: number) => {
+    backupRef.current = getCommittedRef.current()
+    hasBackupRef.current = true
+    pressRef.current = pointerId
+  }, [])
+
+  const commit = useCallback((pointerId: number): boolean => {
+    if (pressRef.current !== pointerId) return false
+    pressRef.current = null
+    backupRef.current = undefined
+    hasBackupRef.current = false
+    return true
+  }, [])
+
+  const cancel = useCallback((pointerId: number): boolean => {
+    if (pressRef.current !== pointerId) return false
+    pressRef.current = null
+    const backup = backupRef.current
+    const hasBackup = hasBackupRef.current
+    backupRef.current = undefined
+    hasBackupRef.current = false
+    if (hasBackup) setCommittedRef.current(backup as V)
+    return true
+  }, [])
+
+  const reset = useCallback(() => {
+    pressRef.current = null
+    backupRef.current = undefined
+    hasBackupRef.current = false
+  }, [])
+
+  // Stable identity: `begin`/`commit`/`cancel`/`reset` are themselves already stable (empty-dep
+  // `useCallback`s), but the returned OBJECT wrapping them was a fresh literal every render — a
+  // consumer's own effect depending on the whole `TouchPin` (or a `useDismissOnOutside` closing
+  // over one of these) would re-subscribe on every render for no reason. Memoizing on the four
+  // (stable) functions costs nothing and makes the wrapper's identity match theirs.
+  return useMemo(() => ({ begin, commit, cancel, reset }), [begin, commit, cancel, reset])
+}