basalt-ui 1.30.2 → 1.32.0

package/dist/tokens/palette.js

@@ -177,12 +177,7 @@ const SPACE_ANCHORS_BASE = {
    * rowLineHeight * text.md`) — so a `size="ctl"` button sitting beside any of them read 2px short
    * and the whole band looked unresolved. 32 lands the entire chrome tier on ONE number, which is
    * also the smallest square that still holds a 16px icon with a 8px surround. */
-  controlHeightCtl: 32,
-  /** The touch hit-area size (`::before`) every home control expands to below `sm` (C15,
-   * `docs/CONTROLS-SPEC.md` §5) — independent of the visible `controlHeightCtl` box, same shape as
-   * `mobileNavBarHeight`/`mobileNavRowHeight`'s Apple HIG 44pt / WCAG 2.5.5 floors elsewhere in this
-   * table. Floored at 30px in {@link deriveSpacing} (C15's "floor 30 at density −3"). */
-  touchControlHeight: 36
+  controlHeightCtl: 32
 };
 const SPACE_SCALE_BASE = {
   xs: 11,
@@ -421,9 +416,8 @@ const SPACE_STEP_BASE = {
    *
    *  44, down from 48. The band holds ONE `ctl`-tier row (32 since this pass), so 48 left 8px of
    *  dead air above and below it — the "too much spacing at the top bar" the header reads as. 44
-   *  keeps 6px of breathing room a side, still clears `touchControlHeight` (36) below `sm` and
-   *  `controlHeight` (42) for a `size="md"` control, and is the Apple HIG 44pt figure the rest of
-   *  this table already floors its touch targets at. */
+   *  keeps 6px of breathing room a side, still clears `controlHeight` (42) for a `size="md"`
+   *  control, and is the 44px touch floor (WCAG 2.5.5). */
   appShellHeaderHeight: 44,
   /** AppShell navbar width, expanded — ONE entry for both the `base` (mobile, where the navbar is
    *  permanently collapsed and unused — see `MobileNav`) and the expanded `sm` value: the same
@@ -498,12 +492,9 @@ const SPACE_STEP_BASE = {
   mobileNavTabInsetY: 2,
   /** Active-pill inset around the slot icon, horizontal. */
   mobileNavTabInsetX: 12,
-  /** Menu/sheet row height. Floored at 40px in `deriveSpacing` — a deliberate design choice, not
-   *  a WCAG floor: it's the row height shared with the desktop sidebar rows, above the WCAG 2.5.8
-   *  AA minimum (24px) and below the 2.5.5 AAA figure (44px, the size `mobileNavBarHeight`/
-   *  `sheetRowHeight` still hold to) — the shortest box that still reads as ONE row vocabulary with
-   *  the sidebar instead of a bespoke touch size. */
-  mobileNavRowHeight: 40,
+  /** Menu/sheet row height — the WCAG 2.5.5 44px target, floored at 44 in `deriveSpacing` (the
+   *  pointer tier's `--vx-hit` is the same number under `(pointer: coarse)`). */
+  mobileNavRowHeight: 44,
   /** More/group `<Menu width={…}>`. JS-consumed, no var — same rationale as
    *  `sidebarSettingsMenuWidth` directly above. */
   mobileNavMenuWidth: 232,
@@ -643,19 +634,7 @@ const SPACE_FIXED = {
    * to 1 at density's floor level -3 and 3 at its ceiling level +3 — the widest swing `deriveSpacing`'s
    * `[-3, 3]` range can produce) for no compensating benefit, since the two radii it sits between
    * never move independently of each other. */
-  segmentedTrackInset: 2,
-  /**
-   * The WCAG 2.5.5/2.5.8 touch-target floor (44px) for a hit area that has no `ctl`-tier home to
-   * size it — a raw CSS-module rule bumping a control's hit area under `@media (pointer: coarse)`
-   * (C5 consolidation: argo carried three such rules with a hand-picked 44/46px literal apiece).
-   * Density-exempt for the same reason `touchControlHeight`'s FLOOR is: a target this small must
-   * never shrink further, whatever the density knob says elsewhere. Unlike the rest of this
-   * object, this ONE key IS emitted as a `--vx-*` var (`tokens/index.ts`'s `space-touch-target`) —
-   * the others stay JS-only because nothing outside the framework's own components reads them, but
-   * this floor's whole purpose is being read by a CONSUMER's own `.module.css`, which cannot
-   * import a JS ref at all.
-   */
-  spaceTouchTarget: 44
+  segmentedTrackInset: 2
 };
 function scaleSpace(value, level, multiplier) {
   if (level === 0) return value;
@@ -687,11 +666,10 @@ function deriveSpacing(level) {
   anchors.controlHeightTag = Math.max(18, anchors.controlHeightTag);
   anchors.controlHeightWidget = Math.max(22, anchors.controlHeightWidget);
   anchors.controlHeightCtl = Math.max(28, anchors.controlHeightCtl);
-  anchors.touchControlHeight = Math.max(30, anchors.touchControlHeight);
   const mappedStep = mapSpaceGroup(SPACE_STEP_BASE, level, multiplier);
   mappedStep.sidebarSearchTriggerHeight = Math.max(24, mappedStep.sidebarSearchTriggerHeight);
   mappedStep.mobileNavBarHeight = Math.max(49, mappedStep.mobileNavBarHeight);
-  mappedStep.mobileNavRowHeight = Math.max(40, mappedStep.mobileNavRowHeight);
+  mappedStep.mobileNavRowHeight = Math.max(44, mappedStep.mobileNavRowHeight);
   mappedStep.sheetRowHeight = Math.max(44, mappedStep.sheetRowHeight);
   const step = {
     ...mappedStep,

package/dist/tokens/size-classes.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The two responsive tables (`docs/DESIGN-CORE.md` § Layout, elevation, shapes) — pure data, Mantine-free. Each
+ * value is the class's minimum width in px.
+ *
+ * A `@media`/`@container` condition cannot read a custom property, so CSS writes the literal and
+ * `breakpoint-literals.test.ts` pins every literal to these tables.
+ */
+/** Viewport classes — shell chrome only (bottom bar / rail / sidebar, aside docking). */
+export declare const SIZE_CLASSES: {
+    readonly compact: 0;
+    readonly medium: 840;
+    readonly expanded: 1200;
+};
+/** A component's own inline size — card chrome, chart tier, forms. No CSS reads it yet. */
+export declare const CONTAINER_CLASSES: {
+    readonly micro: 0;
+    readonly compact: 240;
+    readonly regular: 480;
+    readonly wide: 800;
+};
+export type ContainerClass = keyof typeof CONTAINER_CLASSES;
+/** The class a MEASURED inline size falls in (`px` is a min-width boundary, so 240 is `compact`). */
+export declare function resolveContainerClass(px: number): ContainerClass;
+/**
+ * `theme.breakpoints`, derived — a consumer cannot retune it. Mantine needs all five keys:
+ * `base` (no key) is compact, `xs`/`sm` open the medium class, `md`/`lg`/`xl` the expanded one, so
+ * every `visibleFrom`/`hiddenFrom` in the package stays "desktop chrome" from `sm` up.
+ */
+export declare const SIZE_CLASS_BREAKPOINTS: {
+    readonly xs: `${number}em`;
+    readonly sm: `${number}em`;
+    readonly md: `${number}em`;
+    readonly lg: `${number}em`;
+    readonly xl: `${number}em`;
+};
+/** A px width as the `em` length media queries use (16px root). */
+export declare function toEm(px: number): string;
+/** The `max-width` complement of a class boundary — 0.1px under it, Mantine's own convention. */
+export declare function sizeClassMaxEm(minPx: number): string;
+//# sourceMappingURL=size-classes.d.ts.map

package/dist/tokens/size-classes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"size-classes.d.ts","sourceRoot":"","sources":["../../src/tokens/size-classes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,yFAAyF;AACzF,eAAO,MAAM,YAAY;;;;CAAuD,CAAA;AAEhF,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB;;;;;CAA+D,CAAA;AAE7F,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,iBAAiB,CAAA;AAE3D,qGAAqG;AACrG,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAKhE;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;CAMzB,CAAA;AAEV,mEAAmE;AACnE,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEvC;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/tokens/size-classes.js

@@ -0,0 +1,29 @@
+const SIZE_CLASSES = { compact: 0, medium: 840, expanded: 1200 };
+const CONTAINER_CLASSES = { micro: 0, compact: 240, regular: 480, wide: 800 };
+function resolveContainerClass(px) {
+  if (px >= CONTAINER_CLASSES.wide) return "wide";
+  if (px >= CONTAINER_CLASSES.regular) return "regular";
+  if (px >= CONTAINER_CLASSES.compact) return "compact";
+  return "micro";
+}
+const SIZE_CLASS_BREAKPOINTS = {
+  xs: `${SIZE_CLASSES.medium / 16}em`,
+  sm: `${SIZE_CLASSES.medium / 16}em`,
+  md: `${SIZE_CLASSES.expanded / 16}em`,
+  lg: `${SIZE_CLASSES.expanded / 16}em`,
+  xl: `${SIZE_CLASSES.expanded / 16}em`
+};
+function toEm(px) {
+  return `${Number((px / 16).toFixed(5))}em`;
+}
+function sizeClassMaxEm(minPx) {
+  return toEm(minPx - 0.1);
+}
+export {
+  CONTAINER_CLASSES,
+  SIZE_CLASSES,
+  SIZE_CLASS_BREAKPOINTS,
+  resolveContainerClass,
+  sizeClassMaxEm,
+  toEm
+};

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.32.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.32.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.32.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",
@@ -162,19 +162,20 @@
     "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",
+    "@testing-library/react": "16.3.3",
+    "@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 +185,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
+}