basalt-ui 1.30.2 → 1.31.0

package/configs/oxlint-plugin.js

@@ -143,6 +143,7 @@ export const KNOWN_RULE_IDS = new Set([
   'visx-tooltip',
   'token-layer-boundary',
   'no-import-meta-env',
+  'raw-breakpoint',
   // These three honour `basalt-agent-allow`, never `theme-allow` — but they are real ids, so an
   // annotation naming one must parse as a (useless) scoped annotation rather than as prose.
   'agent-resume-guard',
@@ -175,6 +176,7 @@ export const KNOWN_RULE_IDS = new Set([
   'hidden-inline-style',
   'in-body-page-title',
   'raw-selection-control',
+  'raw-media-query',
   // Retired guard kinds — no longer in GUARD_RULES, but a `theme-allow` naming one must still
   // parse as a real (dead) waiver rather than an unknown-id typo. See RETIRED_RULE_IDS above.
   ...RETIRED_RULE_IDS,
@@ -2706,7 +2708,7 @@ const CONTROL_OUTSIDE_HOME_MESSAGE =
  * `@mantine/form` (a form is the third home and its inputs are not filters), and the owner
  * exemption — a file DEFINING a basalt control cannot be told to use one.
  */
-// Ships: warn (grace → 1.31.0)
+// Ships: warn (grace → 1.32.0)
 const controlOutsideHome = {
   meta: {
     type: 'suggestion',
@@ -3645,8 +3647,19 @@ const queryFnUnwrap = {
  * @type {readonly DeprecatedExport[]}
  */
 export const DEPRECATED_EXPORTS = [
-  // Empty since 1.29.0: every 1.28.x deprecation was removed on schedule. The next
-  // deprecation adds a row here in the same commit as its @deprecated JSDoc and MIGRATING entry.
+  // The chart phone-tier API (`resolveChartTier`/`chartTierMetrics`/`useChartTier`/
+  // `useChartTierMetrics`/`ChartTierMetrics`/`phoneChartWidth`) is NOT here: MIGRATING.md's own
+  // Unreleased section states it a hard removal with no grace window (zero consumers), and these
+  // exports are no longer reachable from any public barrel in `src/charts`/`src/tokens` — a row
+  // here would nudge a rewrite to an import that no longer resolves, i.e. "it still resolves today"
+  // would be false.
+  {
+    subpath: 'basalt-ui',
+    name: 'useBreakpoint',
+    replacement: 'useSizeClass (compact/medium/expanded) or @container for a container concern',
+    removeIn: '1.31.0',
+    fix: false,
+  },
 ]
 
 function deprecatedExportMessage(row) {
@@ -3935,6 +3948,227 @@ const noImportMetaEnv = {
   },
 }
 
+// ── Rule 32 — raw-breakpoint ─────────────────────────────────────────────────────────────────────
+
+/** The Mantine responsive-style-prop shorthand keys — `{ base, xs, sm, md, lg, xl }`, never a mix. */
+const RESPONSIVE_OBJECT_KEYS = new Set(['base', 'xs', 'sm', 'md', 'lg', 'xl'])
+
+/**
+ * Is `node` a Mantine responsive-style-prop object literal — `{ base: 1, sm: 2 }`? Every property
+ * key has to be one of {@link RESPONSIVE_OBJECT_KEYS}, and there has to be at least one: a random
+ * object that merely happens to have a `sm` key among other, unrelated ones is not this shape, and
+ * an empty object is not a breakpoint decision at all.
+ */
+function isResponsiveObjectValue(node) {
+  if (node === null || node === undefined || node.type !== 'ObjectExpression') return false
+  if (node.properties.length === 0) return false
+  return node.properties.every((prop) => {
+    if (prop.type !== 'Property') return false
+    const name = propertyKeyName(prop)
+    return typeof name === 'string' && RESPONSIVE_OBJECT_KEYS.has(name)
+  })
+}
+
+/**
+ * Does this prop value CONTAIN a responsive object — itself, nested one level down in a property
+ * (`footer={{ height: { base: 60, sm: 0 } }}`, Mantine's own AppShell idiom), or behind a same-file
+ * `const` binding at either place (`const h = { base: 60, sm: 0 }`, then `footer={{ height: h }}`)?
+ * `consts` is the same-file name→object map, so an Identifier resolves identically wherever it
+ * appears — the top-level attribute value and a nested property value alike. Matching only a nested
+ * `ObjectExpression` left the Identifier-in-a-property shape trivially bypassable.
+ */
+function containsResponsiveObjectValue(node, consts, seen = new Set()) {
+  const resolved =
+    node !== null && node !== undefined && node.type === 'Identifier' ? consts.get(node.name) : node
+  if (resolved === null || resolved === undefined || resolved.type !== 'ObjectExpression')
+    return false
+  if (seen.has(resolved)) return false
+  seen.add(resolved)
+  if (isResponsiveObjectValue(resolved)) return true
+  return resolved.properties.some(
+    (prop) => prop.type === 'Property' && containsResponsiveObjectValue(prop.value, consts, seen),
+  )
+}
+
+/**
+ * The shell components that are `visibleFrom`/`hiddenFrom`'s legitimate home — the size-class
+ * axis's one JSX escape hatch, alongside overlays. Matched by DECLARATION name, the same
+ * owner-by-declaration test `hand-rolled-shell`'s
+ * `notesOwnerDefinition` already uses for "this file IS the framework piece, not a consumer of it"
+ * — a file defining one of these is exempt for the whole file, because deciding which JSX line
+ * inside a shell's own render tree is "the shell deciding its own chrome" vs. "a stray breakpoint"
+ * is not a distinction the shell's own implementation can make about itself. The OTHER legitimate
+ * home is a control implementing its own C9 swap (`ViewTabs`, `ActionGroup`, …) — that half reuses
+ * {@link createControlOwnerProbe} (`controlOwner` below) rather than a second name list.
+ */
+const SHELL_HOME_NAMES = new Set(['BasaltShell', 'AppSidebar', 'MobileNav', 'AppBrand'])
+
+/**
+ * The two files exempted by NAME rather than by declaration: `useMediaQuery`'s own implementation
+ * (`common/use-media-query.ts` — the one sanctioned `window.matchMedia` read every other file,
+ * including `useSizeClass`, now funnels through) and `ChartTooltip` (the Mantine-free chart layer's
+ * own pointer-tier read).
+ */
+const RAW_BREAKPOINT_EXEMPT_FILE = /(?:^|[\\/])(?:use-media-query\.ts|ChartTooltip\.tsx)$/
+
+const RAW_BREAKPOINT_RESPONSIVE_PROP_MESSAGE =
+  'Responsive-object style prop on a Mantine component — the framework owns the three responsive ' +
+  'axes (size class for shell chrome, container class for a component’s own width, pointer tier), ' +
+  'never a per-component `{ base, sm, … }`. Reach for a container query for this component’s own ' +
+  'width, or useSizeClass() for shell-only chrome. (basalt/raw-breakpoint)'
+
+const RAW_BREAKPOINT_VISIBLE_HIDDEN_MESSAGE =
+  "visibleFrom/hiddenFrom outside a shell home or a control's own C9 swap — this pair is the " +
+  "size-class axis's one JSX escape hatch. Anywhere else it is a hand-rolled viewport breakpoint " +
+  "the framework cannot see or move. Use a container query for a component's own width instead. " +
+  '(basalt/raw-breakpoint)'
+
+const RAW_BREAKPOINT_HOOK_MESSAGE =
+  "useMediaQuery/useMatches/useViewportSize — a raw viewport read outside the framework's one seam " +
+  '(useSizeClass(), shell-only). A component deciding its own layout from a viewport read instead of ' +
+  'a container query is exactly the law this rule exists to catch. (basalt/raw-breakpoint)'
+
+const RAW_BREAKPOINT_GLOBAL_MESSAGE =
+  'window.matchMedia/window.innerWidth read directly — the same viewport read useSizeClass() already ' +
+  "owns, shell-only. Route a component's own layout decision through a container query instead. " +
+  '(basalt/raw-breakpoint)'
+
+/** The three viewport hooks the law names, whatever module they are imported from. */
+const RAW_BREAKPOINT_HOOK_NAMES = new Set(['useMediaQuery', 'useMatches', 'useViewportSize'])
+
+/**
+ * Four independent shapes, one law: a consumer (or basalt itself, outside the shell homes)
+ * reaching past the framework's two sanctioned seams — `useSizeClass()` for shell-only viewport
+ * chrome, a container query for everything else — to read or react to a raw
+ * viewport breakpoint. `visibleFrom`/`hiddenFrom` and the responsive-object shape are reported once
+ * the whole file has been walked ({@link SHELL_HOME_NAMES} may be declared after its first JSX use,
+ * the same ordering hazard `hand-rolled-shell` defers a `Program:exit` report to avoid); the import
+ * and the two global reads carry no such ordering hazard and report immediately. A file that
+ * declares a shell home (or a control's own C9 swap) is exempt for all four shapes uniformly — the
+ * shell's own responsive chrome is the sanctioned use, whatever shape it takes.
+ */
+// Ships: warn (grace → 1.32.0)
+const rawBreakpoint = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Disallow a hand-rolled viewport breakpoint — a responsive-object Mantine prop, ' +
+        'visibleFrom/hiddenFrom outside a shell home, useMediaQuery/useMatches/useViewportSize, or ' +
+        'a raw window.matchMedia/innerWidth read. All four shapes are exempt inside a file that ' +
+        'declares a shell-home component (or a control implementing its own C9 swap).',
+    },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    if (RAW_BREAKPOINT_EXEMPT_FILE.test(getFilename(context))) return {}
+
+    const mantineImports = new Map()
+    // A control implementing its OWN C9 responsive swap (`ViewTabs`, `ActionGroup`'s file, …) is
+    // the other legitimate visibleFrom/hiddenFrom home, alongside the three named shell pieces —
+    // reuse `responsive-twin`'s existing owner probe rather than hand-listing every control file
+    // here too (`view-tabs.tsx`/`actions.tsx` were both false positives before this reuse).
+    const controlOwner = createControlOwnerProbe()
+    let definesShellHome = false
+    const visibleHiddenCandidates = []
+    const responsiveObjectCandidates = []
+    // Same-file `const NAME = { base, sm }` bindings, resolved when a JSX attribute or a nested
+    // property passes the Identifier — no scope manager here, so this is a flat name→object map.
+    // A name declared more than once in the file is ambiguous (its two bindings cannot be told
+    // apart), so it is dropped from the map entirely rather than guessed at last-wins.
+    const responsiveObjectConsts = new Map()
+    const seenDeclaratorNames = new Set()
+
+    const noteShellHomeOwner = (name) => {
+      if (typeof name === 'string' && SHELL_HOME_NAMES.has(name)) definesShellHome = true
+    }
+
+    return {
+      ImportDeclaration(node) {
+        controlOwner.noteImport(node)
+        collectMantineImports(node, mantineImports)
+        if (node.importKind === 'type') return
+        // `useMatches` collides with `@tanstack/react-router`'s own hook of the same name (basalt's
+        // own `src/router-tanstack/index.ts` imports it) — scope the whole set to a `@mantine/*`
+        // source rather than name alone, the same provenance gate every other Mantine-name rule in
+        // this file already uses (`collectMantineImports`).
+        const source = node.source?.value
+        if (typeof source !== 'string' || !source.startsWith('@mantine/')) return
+        for (const specifier of node.specifiers ?? []) {
+          if (specifier.type !== 'ImportSpecifier') continue
+          if (specifier.importKind === 'type') continue
+          const imported = specifier.imported
+          const importedName = imported.type === 'Identifier' ? imported.name : imported.value
+          if (typeof importedName !== 'string' || !RAW_BREAKPOINT_HOOK_NAMES.has(importedName))
+            continue
+          if (hasThemeAllow(context, specifier, 'raw-breakpoint')) continue
+          context.report({ node: specifier, message: RAW_BREAKPOINT_HOOK_MESSAGE })
+        }
+      },
+      FunctionDeclaration(node) {
+        noteShellHomeOwner(node.id?.name)
+        controlOwner.visitors.FunctionDeclaration(node)
+      },
+      VariableDeclarator(node) {
+        noteShellHomeOwner(node.id?.name)
+        controlOwner.visitors.VariableDeclarator(node)
+        if (node.id?.type !== 'Identifier') return
+        const name = node.id.name
+        if (seenDeclaratorNames.has(name)) {
+          // A redeclared name — drop whatever the first declaration put here, so the ambiguous
+          // binding is never used to flag (or clear) a JSX value it may not even be.
+          responsiveObjectConsts.delete(name)
+          return
+        }
+        seenDeclaratorNames.add(name)
+        if (node.init?.type === 'ObjectExpression') responsiveObjectConsts.set(name, node.init)
+      },
+      JSXAttribute(node) {
+        const name = node.name?.name
+        if (typeof name !== 'string') return
+        if (name === 'visibleFrom' || name === 'hiddenFrom') {
+          visibleHiddenCandidates.push(node)
+          return
+        }
+        // Resolved at `Program:exit` so a `const` declared after its first JSX use still resolves.
+        responsiveObjectCandidates.push(node)
+      },
+      CallExpression(node) {
+        if (node.callee?.type !== 'Identifier' || node.callee.name !== 'matchMedia') return
+        if (hasThemeAllow(context, node, 'raw-breakpoint')) return
+        context.report({ node, message: RAW_BREAKPOINT_GLOBAL_MESSAGE })
+      },
+      MemberExpression(node) {
+        if (node.object?.type !== 'Identifier' || node.object.name !== 'window') return
+        if (node.computed) return
+        const property = node.property?.name
+        if (property !== 'matchMedia' && property !== 'innerWidth') return
+        if (hasThemeAllow(context, node, 'raw-breakpoint')) return
+        context.report({ node, message: RAW_BREAKPOINT_GLOBAL_MESSAGE })
+      },
+      'Program:exit'() {
+        // A shell home (or a control implementing its own C9 swap) IS the framework piece — the
+        // shell's own responsive chrome is the sanctioned use, so nothing here reports there.
+        if (definesShellHome || controlOwner.isOwner()) return
+        for (const node of responsiveObjectCandidates) {
+          const value = unwrapExpressionContainer(node.value)
+          if (!containsResponsiveObjectValue(value, responsiveObjectConsts)) continue
+          const owner = node.parent
+          if (owner === null || owner === undefined || owner.type !== 'JSXOpeningElement') continue
+          if (resolveMantineTag(owner.name, mantineImports) === undefined) continue
+          if (hasThemeAllow(context, node, 'raw-breakpoint')) continue
+          context.report({ node, message: RAW_BREAKPOINT_RESPONSIVE_PROP_MESSAGE })
+        }
+        for (const node of visibleHiddenCandidates) {
+          if (hasThemeAllow(context, node, 'raw-breakpoint')) continue
+          context.report({ node, message: RAW_BREAKPOINT_VISIBLE_HIDDEN_MESSAGE })
+        }
+      },
+    }
+  },
+}
+
 // ── Grace ledger ────────────────────────────────────────────────────────────────────────────────
 
 /**
@@ -3968,8 +4202,9 @@ const noImportMetaEnv = {
 export const PLUGIN_RULE_GRACE = {
   'control-outside-home': {
     since: '1.26.0',
-    promote: '1.31.0',
+    promote: '1.32.0',
     why:
+      'Extended 1.31.0 -> 1.32.0 at the 1.31.0 release: the basalt tree still carries incumbents (data-table, notifications center, theme-lab) and the argo sweep has not run. ' +
       'the wave-6 control guards (docs/CONTROLS-SPEC.md §6). The one openly HEURISTIC rule of the ' +
       'set — "this control has no home" is a claim about layout intent, so its false-positive load ' +
       'is carried by four exemptions (overlay/settings-row ancestor, the overlay FILENAME ' +
@@ -3995,6 +4230,20 @@ export const PLUGIN_RULE_GRACE = {
       "still an overlay's own body declares it with " +
       '`theme-allow-file control-outside-home — overlay`.',
   },
+  'raw-breakpoint': {
+    since: '1.31.0',
+    promote: '1.32.0',
+    why:
+      'new in the wave-11 responsive/touch guards. Catches four ' +
+      'independent shapes at once — a responsive-object Mantine prop, visibleFrom/hiddenFrom outside ' +
+      'the three shell homes, the three raw viewport hooks, and window.matchMedia/innerWidth — none ' +
+      'of which basalt policed before this wave, so every consumer on an earlier minor has a green ' +
+      "build with all four shapes already in it. basalt-ui/content's own article-card.tsx (a " +
+      "`SimpleGrid cols={{ base: 1, sm: 2, lg }}`) is one incumbent measured in basalt's own tree at " +
+      'ship time — a real number, not zero, so this ships warn rather than error from the start. ' +
+      '1.32.0 is when that incumbent and any consumer-side ones are expected to have moved to a ' +
+      'container query or a theme-allow with a stated reason.',
+  },
 }
 
 /**
@@ -4064,5 +4313,6 @@ export default {
     'agent-no-raw-usechat': agentNoRawUseChat,
     'ai-sdk-major': aiSdkMajor,
     'no-import-meta-env': noImportMetaEnv,
+    'raw-breakpoint': rawBreakpoint,
   },
 }

package/configs/oxlint-plugin.test.ts

@@ -70,6 +70,7 @@ beforeEach(() => {
         'basalt/agent-resume-guard': 'error',
         'basalt/agent-no-raw-usechat': 'error',
         'basalt/ai-sdk-major': 'error',
+        'basalt/raw-breakpoint': 'error',
       },
     }),
   )
@@ -2735,10 +2736,11 @@ describe('basalt/responsive-twin', () => {
   })
 
   it('does NOT flag two halves on DIFFERENT breakpoints', () => {
-    const { code, rules } = run(
+    // `code` is not asserted here: raw visibleFrom/hiddenFrom outside a shell home is its own,
+    // unrelated finding (basalt/raw-breakpoint) — this test is only about responsive-twin's silence.
+    const { rules } = run(
       `export const C = () => (\n  <div>\n    <SegmentedControl visibleFrom="sm" data={[]} />\n    <SegmentedControl hiddenFrom="md" data={[]} />\n  </div>\n)\n`,
     )
-    expect(code).toBe(0)
     expect(rules).not.toContain('responsive-twin')
   })
 
@@ -3400,6 +3402,147 @@ describe('basalt/forms-field-key', () => {
   })
 })
 
+// ── raw-breakpoint ────────────────────────────────────────────────────────────
+
+describe('basalt/raw-breakpoint', () => {
+  it('flags a responsive-object prop on an imported Mantine component', () => {
+    const { rules } = run(
+      `import { SimpleGrid } from '@mantine/core'\n` +
+        `export const C = () => <SimpleGrid cols={{ base: 1, sm: 2 }} />\n`,
+    )
+    expect(rules).toContain('raw-breakpoint')
+  })
+
+  it('flags a responsive object nested one level down (Mantine AppShell idiom)', () => {
+    const { rules } = run(
+      `import { AppShell } from '@mantine/core'\n` +
+        `export const C = () => <AppShell footer={{ height: { base: 60, sm: 0 } }}>hi</AppShell>\n`,
+    )
+    expect(rules).toContain('raw-breakpoint')
+  })
+
+  it('flags a responsive object behind a same-file const binding', () => {
+    const { rules } = run(
+      `import { SimpleGrid } from '@mantine/core'\n` +
+        `const responsiveCols = { base: 1, sm: 2 }\n` +
+        `export const C = () => <SimpleGrid cols={responsiveCols} />\n`,
+    )
+    expect(rules).toContain('raw-breakpoint')
+  })
+
+  // The nested-property half: a property VALUE that is itself an Identifier must resolve through
+  // the same-file const map, exactly as the attribute's own top-level value already does.
+  it('flags a responsive object behind a const used as a nested property value', () => {
+    const { rules } = run(
+      `import { AppShell } from '@mantine/core'\n` +
+        `const h = { base: 60, sm: 0 }\n` +
+        `export const C = () => <AppShell footer={{ height: h }}>hi</AppShell>\n`,
+    )
+    expect(rules).toContain('raw-breakpoint')
+  })
+
+  // A name declared twice in the file has no single binding without a scope manager, so it is
+  // dropped rather than resolved last-declaration-wins — the outer (non-responsive) `cols` the JSX
+  // actually references must not be flagged via the inner function's responsive one.
+  it('does NOT flag a name redeclared in the file — an ambiguous binding is skipped, not guessed', () => {
+    const { rules } = run(
+      `import { SimpleGrid } from '@mantine/core'\n` +
+        `const cols = { fixed: 2 }\n` +
+        `function Other() {\n  const cols = { base: 1, sm: 2 }\n  return null\n}\n` +
+        `export const C = () => <SimpleGrid cols={cols} />\n`,
+    )
+    expect(rules).not.toContain('raw-breakpoint')
+  })
+
+  it('does NOT flag a fixed cols on the same component', () => {
+    const { rules } = run(
+      `import { SimpleGrid } from '@mantine/core'\n` +
+        `export const C = () => <SimpleGrid cols={2} />\n`,
+    )
+    expect(rules).not.toContain('raw-breakpoint')
+  })
+
+  it('does NOT flag an object prop on a component never imported from @mantine/*', () => {
+    const { rules } = run(`export const C = () => <WidgetGrid cols={{ base: 1, sm: 2 }} />\n`)
+    expect(rules).not.toContain('raw-breakpoint')
+  })
+
+  it('flags visibleFrom/hiddenFrom outside a shell home', () => {
+    const { rules } = run(
+      `import { Box } from '@mantine/core'\n` +
+        `export const C = () => <Box visibleFrom="sm">desktop only</Box>\n`,
+    )
+    expect(rules).toContain('raw-breakpoint')
+  })
+
+  it('does NOT flag visibleFrom/hiddenFrom inside a file that DEFINES BasaltShell', () => {
+    const { rules } = run(
+      `import { Box } from '@mantine/core'\n` +
+        `export function BasaltShell() {\n  return <Box visibleFrom="sm">desktop only</Box>\n}\n`,
+    )
+    expect(rules).not.toContain('raw-breakpoint')
+  })
+
+  // The exemption is uniform across all four shapes: a file that IS the shell may also carry a
+  // responsive-object prop, not only visibleFrom/hiddenFrom.
+  it('does NOT flag a responsive-object prop inside a file that DEFINES BasaltShell', () => {
+    const { rules } = run(
+      `import { SimpleGrid } from '@mantine/core'\n` +
+        `export function BasaltShell() {\n  return null\n}\n` +
+        `export const C = () => <SimpleGrid cols={{ base: 1, sm: 2 }} />\n`,
+    )
+    expect(rules).not.toContain('raw-breakpoint')
+  })
+
+  it('does NOT flag visibleFrom/hiddenFrom inside a file that DEFINES a C9 control (ViewTabs) and imports no basalt-ui', () => {
+    const { rules } = run(
+      `import { Box } from '@mantine/core'\n` +
+        `export function ViewTabs() {\n  return <Box visibleFrom="sm">desktop only</Box>\n}\n`,
+    )
+    expect(rules).not.toContain('raw-breakpoint')
+  })
+
+  it('flags an import of useMediaQuery/useMatches/useViewportSize from @mantine/*', () => {
+    expect(run(`import { useMediaQuery } from '@mantine/hooks'\n`).rules).toContain(
+      'raw-breakpoint',
+    )
+    expect(run(`import { useMatches } from '@mantine/core'\n`).rules).toContain('raw-breakpoint')
+    expect(run(`import { useViewportSize } from '@mantine/hooks'\n`).rules).toContain(
+      'raw-breakpoint',
+    )
+  })
+
+  it('does NOT flag useMatches imported from a non-Mantine router (name collision)', () => {
+    // @tanstack/react-router (and react-router) export their own unrelated `useMatches` —
+    // basalt's own `src/router-tanstack/index.ts` imports it; scoped to `@mantine/*` sources only.
+    expect(run(`import { useMatches } from '@tanstack/react-router'\n`).rules).not.toContain(
+      'raw-breakpoint',
+    )
+    expect(run(`import { useViewportSize } from 'some-lib'\n`).rules).not.toContain(
+      'raw-breakpoint',
+    )
+  })
+
+  it('flags window.matchMedia and window.innerWidth', () => {
+    expect(run(`const mq = window.matchMedia('(max-width: 600px)')\n`).rules).toContain(
+      'raw-breakpoint',
+    )
+    expect(run(`const w = window.innerWidth\n`).rules).toContain('raw-breakpoint')
+  })
+
+  it('flags a bare matchMedia() call', () => {
+    expect(run(`const mq = matchMedia('(max-width: 600px)')\n`).rules).toContain('raw-breakpoint')
+  })
+
+  it('honors a scoped theme-allow on the responsive-object prop', () => {
+    const { rules } = run(
+      `import { SimpleGrid } from '@mantine/core'\n` +
+        `export const C = () => (\n  // theme-allow raw-breakpoint — migrating in a follow-up\n  <SimpleGrid cols={{ base: 1, sm: 2 }} />\n)\n`,
+    )
+    expect(rules).not.toContain('raw-breakpoint')
+  })
+})
+
 // ── the deprecation ledger (B4) ──────────────────────────────────────────────
 
 describe('DEPRECATED_EXPORTS', () => {

package/configs/oxlint.json

@@ -49,7 +49,8 @@
     "basalt/visx-tooltip": "error",
     "basalt/agent-resume-guard": "error",
     "basalt/agent-no-raw-usechat": "error",
-    "basalt/ai-sdk-major": "error"
+    "basalt/ai-sdk-major": "error",
+    "basalt/raw-breakpoint": "warn"
   },
   "overrides": [
     {

package/dist/agent-chat/composer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composer.d.ts","sourceRoot":"","sources":["../../src/agent-chat/composer.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"composer.d.ts","sourceRoot":"","sources":["../../src/agent-chat/composer.tsx"],"names":[],"mappings":"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"}

package/dist/agent-chat/composer.js

@@ -1,9 +1,10 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import { ActionIcon, Group, Kbd, Stack, Text, Textarea } from "@mantine/core";
+import { ActionIcon, Box, Group, Kbd, Stack, Text, Textarea } from "@mantine/core";
 import { useImperativeHandle, useLayoutEffect, useRef, useSyncExternalStore } from "react";
 import { cx } from "../common/props.js";
 import { readPersistedValue } from "../state.js";
 import { VX } from "../tokens/index.js";
+import { useKeyboardInsetRef } from "./use-keyboard-inset.js";
 function SendGlyph() {
   return /* @__PURE__ */ jsx("svg", { width: 16, height: 16, viewBox: "0 0 24 24", fill: "none", "aria-hidden": true, children: /* @__PURE__ */ jsx(
     "path",
@@ -90,6 +91,7 @@ const noopSubscribe = (_cb) => () => {
 };
 const emptyDraft = () => "";
 const NO_ATTACHMENTS = [];
+const ROOT_GAP = 6;
 function liveSelection(el) {
   if (document.activeElement !== el) return null;
   const { selectionStart, selectionEnd } = el;
@@ -170,6 +172,7 @@ function Composer({
     textareaRef.current?.focus();
   };
   useImperativeHandle(ref, () => ({ insertText, setValue, focus: focusTextarea }));
+  const keyboardInsetRef = useKeyboardInsetRef();
   const submit = () => {
     if (inputDisabled || !hasPayload) return;
     const submittedText = trimmed;
@@ -221,48 +224,43 @@ function Composer({
   if (onPaste !== void 0) textareaProps.onPaste = onPaste;
   if (classNames?.input !== void 0) textareaProps.className = cx(classNames.input);
   const showActions = showStop || showSend;
-  return /* @__PURE__ */ jsxs(
-    Stack,
-    {
-      gap: 6,
-      className: cx(classNames?.root, className),
-      ...style !== void 0 && { style },
-      children: [
-        /* @__PURE__ */ jsxs(Group, { gap: "xs", align: "flex-end", wrap: "nowrap", children: [
-          leftSection,
-          /* @__PURE__ */ jsx(Textarea, { ...textareaProps, ref: textareaRef }),
-          rightSection,
-          showActions && /* @__PURE__ */ jsxs(Group, { gap: "xs", wrap: "nowrap", className: cx(classNames?.actions), children: [
-            showStop ? /* @__PURE__ */ jsx(
-              ActionIcon,
-              {
-                size: 42,
-                radius: "md",
-                variant: "filled",
-                color: "red",
-                onClick: onStop,
-                "aria-label": "Stop generating",
-                children: /* @__PURE__ */ jsx(StopGlyph, {})
-              }
-            ) : null,
-            showSend ? /* @__PURE__ */ jsx(
-              ActionIcon,
-              {
-                size: 42,
-                radius: "md",
-                variant: "filled",
-                onClick: submit,
-                disabled: inputDisabled || !hasPayload,
-                "aria-label": "Send message",
-                children: /* @__PURE__ */ jsx(SendGlyph, {})
-              }
-            ) : null
-          ] })
-        ] }),
-        hint === void 0 ? /* @__PURE__ */ jsx(DefaultHint, {}) : hint
-      ]
-    }
-  );
+  return /* @__PURE__ */ jsxs(Box, { ref: keyboardInsetRef, className: cx(classNames?.root, className), style, children: [
+    /* @__PURE__ */ jsxs(Stack, { gap: ROOT_GAP, children: [
+      /* @__PURE__ */ jsxs(Group, { gap: "xs", align: "flex-end", wrap: "nowrap", children: [
+        leftSection,
+        /* @__PURE__ */ jsx(Textarea, { ...textareaProps, ref: textareaRef }),
+        rightSection,
+        showActions && /* @__PURE__ */ jsxs(Group, { gap: "xs", wrap: "nowrap", className: cx(classNames?.actions), children: [
+          showStop ? /* @__PURE__ */ jsx(
+            ActionIcon,
+            {
+              size: 42,
+              radius: "md",
+              variant: "filled",
+              color: "red",
+              onClick: onStop,
+              "aria-label": "Stop generating",
+              children: /* @__PURE__ */ jsx(StopGlyph, {})
+            }
+          ) : null,
+          showSend ? /* @__PURE__ */ jsx(
+            ActionIcon,
+            {
+              size: 42,
+              radius: "md",
+              variant: "filled",
+              onClick: submit,
+              disabled: inputDisabled || !hasPayload,
+              "aria-label": "Send message",
+              children: /* @__PURE__ */ jsx(SendGlyph, {})
+            }
+          ) : null
+        ] })
+      ] }),
+      hint === void 0 ? /* @__PURE__ */ jsx(DefaultHint, {}) : hint
+    ] }),
+    /* @__PURE__ */ jsx(Box, { "aria-hidden": true, style: { height: "var(--vx-keyboard-inset, 0px)" } })
+  ] });
 }
 export {
   Composer

package/dist/agent-chat/thread-workspace.d.ts

@@ -3,7 +3,7 @@ import type { AgentPart, AgentTransport, OutcomeResolver, ThreadsStore } from '.
 import type { BasaltProps, SlotStylesProps } from '../common/props.js';
 /** 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 & SlotStylesProps<ThreadWorkspaceSlot> & {
     /**
@@ -35,7 +35,7 @@ export type ThreadWorkspaceProps = BasaltProps & SlotStylesProps<ThreadWorkspace
 /**
  * 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} />

package/dist/agent-chat/thread-workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"thread-workspace.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-workspace.tsx"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAGxF,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAanE;;iEAEiE;AACjE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAA;AAEzE,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAC5C,eAAe,CAAC,mBAAmB,CAAC,GAAG;IACrC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,YAAY,CAAA;IACvC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;IACrD,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC,SAAS,CAAC,CAAA;IACnD,qEAAqE;IACrE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAA;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAA;CAChC,CAAA;AA4DH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAC9B,UAAU,EACV,SAAS,EACT,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,UAAU,EACV,SAAS,EACT,KAAK,EACL,UAAU,GACX,EAAE,oBAAoB,GAAG,GAAG,CAAC,OAAO,CAsHpC"}
+{"version":3,"file":"thread-workspace.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-workspace.tsx"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAGxF,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAcnE;;iFAEiF;AACjF,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAA;AAEzE,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAC5C,eAAe,CAAC,mBAAmB,CAAC,GAAG;IACrC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,YAAY,CAAA;IACvC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;IACrD,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC,SAAS,CAAC,CAAA;IACnD,qEAAqE;IACrE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAA;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAA;CAChC,CAAA;AA4DH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAC9B,UAAU,EACV,SAAS,EACT,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,UAAU,EACV,SAAS,EACT,KAAK,EACL,UAAU,GACX,EAAE,oBAAoB,GAAG,GAAG,CAAC,OAAO,CAmHpC"}