basalt-ui 1.26.0 → 1.28.0

package/src/theme/density-relations.test.ts

@@ -1,506 +0,0 @@
-/**
- * Cross-level RELATION tests for the density knob — the audit that drove the Fix 1-7 pass in this
- * commit found the knob correct only at level 0 because every prior test was a level-0 snapshot, not
- * a relation that has to hold at every level. These loop over the full accepted range instead of
- * spot-checking one or two levels, so a future edit that reintroduces one of the audited defects
- * fails here regardless of which level it breaks first.
- *
- * `ALL_LEVELS` is derived from {@link DENSITY_LEVEL_RANGE} (`deriveSpacing`'s accepted `[-3, 3]`
- * range, narrowed from `[-5, 5]` by Fix 7 in this same commit — see `deriveSpacing`'s JSDoc in
- * `../tokens/palette` for why) rather than a hardcoded literal, so a future range change is picked
- * up here automatically instead of silently narrowing this file's own coverage. `ALL_RADIUS_LEVELS`
- * is the same derivation off {@link RADIUS_LEVEL_RANGE} — `deriveRadius` still accepts the wider
- * `[-5, 5]`, so the radius-only relation test below (Fix 3) samples MORE points than the density
- * tests, every one of them a real, valid radius level.
- */
-import { DEFAULT_THEME, mergeMantineTheme } from '@mantine/core'
-import type { MantineTheme } from '@mantine/core'
-import { describe, expect, test } from 'bun:test'
-import { VX } from '../tokens'
-import {
-  DENSITY_LEVEL_RANGE,
-  RADIUS_LEVEL_RANGE,
-  deriveRadius,
-  deriveSpacing,
-  scaleSpace,
-  SPACE,
-  SPACE_FIXED,
-  SPACE_SCALE,
-  SPACE_STEP,
-} from '../tokens/palette'
-import { baseTheme } from './index'
-
-const theme: MantineTheme = mergeMantineTheme(DEFAULT_THEME, baseTheme)
-const ALL_LEVELS = Array.from(
-  { length: DENSITY_LEVEL_RANGE.max - DENSITY_LEVEL_RANGE.min + 1 },
-  (_, i) => DENSITY_LEVEL_RANGE.min + i,
-)
-const ALL_RADIUS_LEVELS = Array.from(
-  { length: RADIUS_LEVEL_RANGE.max - RADIUS_LEVEL_RANGE.min + 1 },
-  (_, i) => RADIUS_LEVEL_RANGE.min + i,
-)
-
-/** Flatten `deriveSpacing(level)`'s anchors + scale + step into one numeric record — `rowLineHeight`
- * is excluded (it is additive, not routed through `scaleSpace`, and always moves, which would
- * inflate a change ratio and can never be "frozen"). Used by the "Fix 7" resolution-honesty block. */
-function flattenSpacing(level: number): Record<string, number> {
-  const { anchors, scale, step } = deriveSpacing(level)
-  return { ...anchors, ...scale, ...step }
-}
-
-describe('Fix 1 — input height, button height, and ActionIcon size never drift', () => {
-  test('every level: controlHeight AND inputHeight resolve to the exact scaled anchor, not merely to each other', () => {
-    // The old form of this test (`controlHeight === inputHeight`) is true BY CONSTRUCTION — both
-    // keys hold the literal same `CONTROL_HEIGHT_BASE` and are scaled by the SAME deterministic
-    // `scaleSpace(value, level, multiplier)` call, so they can never disagree regardless of what the
-    // multiplier law actually computes. Assert each against its own hardcoded expected value instead
-    // — this bites on a change to `CONTROL_HEIGHT_BASE`, the multiplier law, OR a divergence between
-    // the two keys, none of which the old form could catch.
-    const expected: Record<number, number> = {
-      [-3]: 29,
-      [-2]: 34,
-      [-1]: 38,
-      0: 42,
-      1: 46,
-      2: 50,
-      3: 55,
-    }
-    for (const level of ALL_LEVELS) {
-      const { anchors } = deriveSpacing(level)
-      const expectedHeight = expected[level]
-      if (expectedHeight === undefined) throw new Error(`no expected height for level ${level}`)
-      expect(anchors.inputHeight).toBe(expectedHeight)
-      expect(anchors.controlHeight).toBe(expectedHeight)
-    }
-  })
-
-  test('every level: Input/Button/ActionIcon vars() resolve to the SAME calc() shape at size=md', () => {
-    // The three overrides read different CSS custom properties (`--vx-space-input-height` vs.
-    // `--vx-space-control-height`) but the same anchor, so their `calc(...)` bodies differ only in
-    // var NAME, never in the numeric anchor they carry.
-    const inputVars = baseTheme.components?.['Input']?.vars
-    const buttonVars = baseTheme.components?.['Button']?.vars
-    const actionIconVars = baseTheme.components?.['ActionIcon']?.vars
-    const inputResult = inputVars?.(theme, { size: 'md' } as never, {} as never)
-    const buttonResult = buttonVars?.(theme, { size: 'md' } as never, {} as never)
-    const actionIconResult = actionIconVars?.(theme, { size: 'md' } as never, {} as never)
-    expect(inputResult?.wrapper?.['--input-height']).toBe(
-      'calc(var(--vx-space-input-height) * var(--mantine-scale))',
-    )
-    expect(buttonResult?.root?.['--button-height']).toBe(
-      'calc(var(--vx-space-control-height) * var(--mantine-scale))',
-    )
-    expect(actionIconResult?.root?.['--ai-size']).toBe(
-      'calc(var(--vx-space-control-height) * var(--mantine-scale))',
-    )
-  })
-})
-
-describe('Fix 2 — the 4px stack rhythm holds its 2:1 pairs at every level', () => {
-  test('stackXl = 2 * stackMd, stackLg = 2 * stackSm, and every step is its documented multiple of stackXs', () => {
-    for (const level of ALL_LEVELS) {
-      const { anchors } = deriveSpacing(level)
-      expect(anchors.stackXl).toBe(2 * anchors.stackMd)
-      expect(anchors.stackLg).toBe(2 * anchors.stackSm)
-      // The DOCUMENTED law (`deriveSpacing`'s JSDoc): stackSm/stackMd/stackLg/stackXl are exactly
-      // 2x/3x/4x/6x stackXs. A real equality against that documented multiple — not a `% === 0`
-      // divisibility check, which the two ratio assertions above already guarantee for free (any
-      // value that IS `stackXs * N` trivially divides `stackXs`) and so adds zero independent
-      // coverage on top of them.
-      expect(anchors.stackSm).toBe(2 * anchors.stackXs)
-      expect(anchors.stackMd).toBe(3 * anchors.stackXs)
-      expect(anchors.stackLg).toBe(4 * anchors.stackXs)
-      expect(anchors.stackXl).toBe(6 * anchors.stackXs)
-    }
-  })
-})
-
-describe('Fix 3 — SegmentedControl concentricity holds at every RADIUS level', () => {
-  test('RADIUS.card === RADIUS_STEP.tight + segmentedTrackInset, every RADIUS level (the full [-5, 5] range, not the narrower density range)', () => {
-    for (const level of ALL_RADIUS_LEVELS) {
-      const radius = deriveRadius(level)
-      expect(radius.card).toBe(radius.tight + SPACE_FIXED.segmentedTrackInset)
-    }
-  })
-
-  test('at the radius floor (-5), tight is clamped exactly to 0 while card is not — the closest the accepted range gets to breaking concentricity', () => {
-    const radius = deriveRadius(RADIUS_LEVEL_RANGE.min)
-    expect(radius.tight).toBe(0) // clampRadius(ctrl - 1) = clampRadius((6 - 5) - 1) = clampRadius(0)
-    expect(radius.card).toBe(2) // clampRadius(7 - 5) = 2, still positive — the clamp doesn't engage
-    // Concentricity holds here only because `ctrl - 1` landed EXACTLY on the clamp floor (0), not
-    // below it: one level further down (out of the accepted range) would clamp `tight` to 0 while
-    // `card` kept falling, breaking `card === tight + 2` — which is exactly why the range stops here.
-    expect(radius.card).toBe(radius.tight + SPACE_FIXED.segmentedTrackInset)
-  })
-
-  test("segmentedTrackInset never moves with density — it's a SPACE_FIXED constant, not part of deriveSpacing's step output at ANY level", () => {
-    // Claim 1 (the constant itself): the shipped value.
-    expect(SPACE_FIXED.segmentedTrackInset).toBe(2)
-    // Claim 2 (deriveSpacing has no such key any more): a bare `.toBe(2)` on the constant alone would
-    // still pass even if `segmentedTrackInset` were ALSO reintroduced into `SPACE_STEP_BASE` at a
-    // level-0 value of 2 — it would just happen to coincide there. Assert its actual absence from
-    // `step` at every level instead, which a reintroduction WOULD break immediately.
-    for (const level of ALL_LEVELS) {
-      expect(deriveSpacing(level).step).not.toHaveProperty('segmentedTrackInset')
-    }
-  })
-})
-
-describe('Fix 4 — every interactive target clears the WCAG 2.5.8 24px floor at every level', () => {
-  test('sidebar search trigger (and its collapsed rail ActionIcon, which reads the same value)', () => {
-    for (const level of ALL_LEVELS) {
-      expect(deriveSpacing(level).step.sidebarSearchTriggerHeight).toBeGreaterThanOrEqual(24)
-    }
-  })
-
-  test('a NavLink/Menu row (2 * rowInsetY padding + rowLineHeight * the fixed md text step)', () => {
-    for (const level of ALL_LEVELS) {
-      const { anchors, rowLineHeight } = deriveSpacing(level)
-      const rowHeight = 2 * anchors.rowInsetY + rowLineHeight * VX.text.md
-      expect(rowHeight).toBeGreaterThanOrEqual(24)
-    }
-  })
-
-  test('the page bar row (pageBarRowHeight — the mobile header actions row it replaced is gone)', () => {
-    for (const level of ALL_LEVELS) {
-      expect(deriveSpacing(level).step.pageBarRowHeight).toBeGreaterThanOrEqual(24)
-    }
-  })
-
-  // The mobile bar's own two targets clear a HIGHER bar than WCAG 2.5.8's 24px: a thumb on a phone
-  // is not a mouse pointer, so `deriveSpacing` floors them at Apple HIG 44pt / WCAG 2.5.5 AAA
-  // instead. Without those floors the 1 + 0.1*level multiplier takes 56 -> 39 and 44 -> 31 at level
-  // -3 — both under even the 24px floor the rest of this block asserts.
-  test('the mobile nav bar height never drops below its own 48px floor', () => {
-    for (const level of ALL_LEVELS) {
-      expect(deriveSpacing(level).step.mobileNavBarHeight).toBeGreaterThanOrEqual(48)
-    }
-  })
-
-  test('a mobile nav menu/sheet row never drops below its own 44px floor', () => {
-    for (const level of ALL_LEVELS) {
-      expect(deriveSpacing(level).step.mobileNavRowHeight).toBeGreaterThanOrEqual(44)
-    }
-  })
-
-  // `sheetRowHeight`'s own doc calls it "same floor family as `mobileNavRowHeight`" — same touch-only
-  // surface (the `Filters (n)` drawer, the mobile kebab sheet), same Apple HIG 44pt / WCAG 2.5.5 AAA
-  // floor, so it must clear it at every level too, not just coincidentally at level 0.
-  test('a Filters/kebab sheet row never drops below its own 44px floor', () => {
-    for (const level of ALL_LEVELS) {
-      expect(deriveSpacing(level).step.sheetRowHeight).toBeGreaterThanOrEqual(44)
-    }
-  })
-
-  test('the resolved control/input height (size="md" Button/ActionIcon/Input) clears the floor too', () => {
-    for (const level of ALL_LEVELS) {
-      const { anchors } = deriveSpacing(level)
-      expect(anchors.controlHeight).toBeGreaterThanOrEqual(24)
-      expect(anchors.inputHeight).toBeGreaterThanOrEqual(24)
-    }
-  })
-
-  // C15 (`docs/CONTROLS-SPEC.md` §5): "every touch target inside a home is ≥36px below `sm` (floor
-  // 30 at density −3)". Without the floor the 1 + 0.1*level multiplier takes 36 -> 25 at level -3,
-  // well under even the 24px WCAG floor above.
-  test('touchControlHeight never drops below its own 30px floor (C15)', () => {
-    for (const level of ALL_LEVELS) {
-      expect(deriveSpacing(level).anchors.touchControlHeight).toBeGreaterThanOrEqual(30)
-    }
-    expect(deriveSpacing(-3).anchors.touchControlHeight).toBe(30)
-  })
-
-  test('the remaining controls-tier anchors clear their own floors at every level', () => {
-    for (const level of ALL_LEVELS) {
-      const { anchors } = deriveSpacing(level)
-      expect(anchors.controlHeightTag).toBeGreaterThanOrEqual(18)
-      expect(anchors.controlHeightWidget).toBeGreaterThanOrEqual(22)
-      expect(anchors.controlHeightCtl).toBeGreaterThanOrEqual(28)
-    }
-  })
-})
-
-describe('Fix 5 — scaleSpace floors a sub-1 base at 1 (the inverted-clamp regression)', () => {
-  test('a base below 1 that would round to 0 floors at 1 instead', () => {
-    // round(0.5 * 0.35) = round(0.175) = 0 without the unconditional floor — the exact regression
-    // the old `value >= 1 ? ... : scaled` guard let through (see `scaleSpace`'s doc).
-    expect(scaleSpace(0.5, -5, 0.35)).toBe(1)
-  })
-
-  test('a base below 1 at level 0 still returns verbatim (bypasses scaling entirely)', () => {
-    expect(scaleSpace(0.5, 0, 1)).toBe(0.5)
-  })
-})
-
-/**
- * Faithful reconstruction of the pre-Fix-7 law: IDENTICAL structural shape to the current
- * `deriveSpacing` (shared stack-unit rebuild, the WCAG floor, the sticky-clearance derivation) —
- * ONLY the multiplier coefficient (0.1 -> 0.06) and the accepted range ([-3,3] -> [-5,5]) revert,
- * exactly the regression the "Fix 7" resolution-floor block below exists to catch.
- */
-function oldLawFlatten(level: number): Record<string, number> {
-  const multiplier = 1 + 0.06 * level
-  const anchors: Record<string, number> = {}
-  for (const [k, v] of Object.entries(SPACE)) anchors[k] = scaleSpace(v, level, multiplier)
-  const stackUnit = scaleSpace(4, level, multiplier)
-  anchors['stackXs'] = stackUnit
-  anchors['stackSm'] = stackUnit * 2
-  anchors['stackMd'] = stackUnit * 3
-  anchors['stackLg'] = stackUnit * 4
-  anchors['stackXl'] = stackUnit * 6
-  const scale: Record<string, number> = {}
-  for (const [k, v] of Object.entries(SPACE_SCALE)) scale[k] = scaleSpace(v, level, multiplier)
-  const step: Record<string, number> = {}
-  for (const [k, v] of Object.entries(SPACE_STEP)) {
-    if (k === 'stickyHeaderClearance') continue
-    step[k] = scaleSpace(v, level, multiplier)
-  }
-  step['sidebarSearchTriggerHeight'] = Math.max(24, step['sidebarSearchTriggerHeight']!)
-  step['mobileNavBarHeight'] = Math.max(48, step['mobileNavBarHeight']!)
-  step['mobileNavRowHeight'] = Math.max(44, step['mobileNavRowHeight']!)
-  step['sheetRowHeight'] = Math.max(44, step['sheetRowHeight']!)
-  step['stickyHeaderClearance'] = step['appShellHeaderHeight']! + anchors['stackMd']!
-  return { ...anchors, ...scale, ...step }
-}
-
-describe("Fix 7 — the knob's resolution is honest at every notch", () => {
-  test('adjacent-notch resolution floor: more than 70% of the flattened spacing set changes at every step', () => {
-    for (let i = 0; i < ALL_LEVELS.length - 1; i++) {
-      const a = flattenSpacing(ALL_LEVELS[i]!)
-      const b = flattenSpacing(ALL_LEVELS[i + 1]!)
-      const keys = Object.keys(a)
-      const changed = keys.filter((k) => a[k] !== b[k]).length
-      // Observed minimum under the current 0.1/±3 law is ~0.759 (level -3 -> -2) — the 0.7 floor
-      // leaves a small margin for legitimate retuning while still catching the regression the next
-      // test proves it catches.
-      expect(changed / keys.length).toBeGreaterThan(0.7)
-    }
-  })
-
-  test('regression proof: the OLD 0.06/±5 law fails the SAME 0.7 floor — confirms the floor above actually bites', () => {
-    // Run here, not merely claimed, so a future edit to the CURRENT law can't silently make this
-    // proof stale without failing too — see `oldLawFlatten`'s own doc above.
-    const oldLawLevels = [-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5]
-    let minRatio = 1
-    for (let i = 0; i < oldLawLevels.length - 1; i++) {
-      const a = oldLawFlatten(oldLawLevels[i]!)
-      const b = oldLawFlatten(oldLawLevels[i + 1]!)
-      const keys = Object.keys(a)
-      const changed = keys.filter((k) => a[k] !== b[k]).length
-      minRatio = Math.min(minRatio, changed / keys.length)
-    }
-    // Observed: ~0.491 (level -4 -> -3 and level 3 -> 4), well under the 0.7 floor above — the old
-    // law's dead zone this whole fix replaced.
-    expect(minRatio).toBeLessThan(0.7)
-  })
-
-  test('frozen-vs-baseline ceiling: fewer than 27 of the ~129 values equal their level-0 value at any non-zero level', () => {
-    // Measured under the 0.1/±3 law: worst case is 25 (at level −1) — down from 43 under the old
-    // 0.06/±5 law. It is 25 rather than 24 because `mobileNavTabInsetY` (base 2) joined the set:
-    // a base that small rounds back to itself at ±1 and ±2 under any multiplier this law can
-    // produce, exactly as `mobileNavTabGap` (base 3) already did. That is the rounding law, not a
-    // resolution regression — the ceiling of 27 keeps the same margin over the measured worst case
-    // while still catching a future step reduction that reintroduces the real dead zone.
-    const baseline = flattenSpacing(0)
-    const keys = Object.keys(baseline)
-    for (const level of ALL_LEVELS) {
-      if (level === 0) continue
-      const values = flattenSpacing(level)
-      const frozen = keys.filter((k) => values[k] === baseline[k]).length
-      expect(frozen).toBeLessThan(27)
-    }
-  })
-
-  test('monotonicity: every flattened value is non-decreasing across adjacent levels', () => {
-    for (let i = 0; i < ALL_LEVELS.length - 1; i++) {
-      const a = flattenSpacing(ALL_LEVELS[i]!)
-      const b = flattenSpacing(ALL_LEVELS[i + 1]!)
-      for (const key of Object.keys(a)) {
-        expect(b[key]!).toBeGreaterThanOrEqual(a[key]!)
-      }
-    }
-  })
-
-  test('endpoint preservation: deriveSpacing(±3) reproduces the exact value set the old deriveSpacing(±5) produced', () => {
-    expect(deriveSpacing(-3).anchors.inputHeight).toBe(29)
-    expect(deriveSpacing(3).anchors.inputHeight).toBe(55)
-    expect(deriveSpacing(-3).anchors.rowInsetX).toBe(7)
-    expect(deriveSpacing(3).anchors.rowInsetX).toBe(13)
-    // `stickyHeaderClearance` is EXCLUDED here on purpose — since it now DERIVES from the AppShell
-    // header instead of scaling off an independent base (see `deriveSpacing`'s doc, third bullet),
-    // it never reproduced the old ±5 envelope to
-    // begin with; its own law is asserted by the dedicated describe block in `tokens/density.test.ts`
-    // (specific low/zero/high values) AND by the "Fix 8" describe block below in this same file
-    // (the generic `clearance = header + anchors.stackMd` relation, looped over every level).
-    expect(deriveSpacing(-3).rowLineHeight).toBe(1.25)
-    expect(deriveSpacing(3).rowLineHeight).toBe(1.45)
-  })
-})
-
-describe('Fix 8 — the sticky-header clearance clears the AppShell header, exactly', () => {
-  test('clearance = appShellHeaderHeight + stackMd, exactly, at every level', () => {
-    for (const level of ALL_LEVELS) {
-      const { step, anchors } = deriveSpacing(level)
-      expect(step.stickyHeaderClearance).toBe(step.appShellHeaderHeight + anchors.stackMd)
-    }
-  })
-
-  // The "mobile clearance = appShellHeaderMobileHeight + stackMd" and "mobile exceeds desktop" tests
-  // that used to sit here are DELETED, not renamed: since 1.26.0 the AppShell header is ONE 48px row
-  // at every viewport (law C14, `docs/CONTROLS-SPEC.md` §2.1), so `stickyHeaderClearanceMobile` and
-  // the `appShellHeaderMobileHeight` it derived from no longer exist to assert anything about.
-
-  // The "both breathing-room margins (clearance minus own header) are monotonically non-decreasing"
-  // check used to live here as its own test — deleted, not merely renamed: the two tests above this
-  // one already assert `clearance = header + anchors.stackMd` EXACTLY at every level, so
-  // `clearance - header` is identically `anchors.stackMd` — its monotonicity adds no coverage beyond
-  // what "Fix 7"'s global "every flattened value is non-decreasing across adjacent levels" test
-  // already guarantees (`stackMd` is one of the flattened anchors that test loops over). A bug this
-  // block could catch independently of both of those would have to leave `clearance - header`
-  // non-monotonic while `clearance = header + stackMd` still holds exactly and `stackMd` itself still
-  // stays monotonic — impossible by substitution.
-})
-
-describe('Fix 6 — BasaltShell AppShell dimensions track density', () => {
-  test('desktop header always holds a size="md" control', () => {
-    for (const level of ALL_LEVELS) {
-      const { step, anchors } = deriveSpacing(level)
-      expect(step.appShellHeaderHeight).toBeGreaterThanOrEqual(anchors.controlHeight)
-    }
-  })
-
-  test('the collapsed rail content box (rail width minus its own row inset) stays positive', () => {
-    for (const level of ALL_LEVELS) {
-      const { step, anchors } = deriveSpacing(level)
-      expect(step.appShellNavbarRailWidth - 2 * anchors.rowInsetX).toBeGreaterThan(0)
-    }
-  })
-
-  test('the header is ONE row at every viewport, and it holds a touch target below sm', () => {
-    // The invariant this replaced was a BUDGET: `appShellHeaderMobileHeight` was a documented SUM
-    // (row 1 + `SPACE_SCALE.sm` + `appHeaderMobileActionsHeight`), so row 1 was whatever the total
-    // left over, and raising an addend without raising the total silently ate the target-size margin
-    // — which is exactly what the component-roominess retune did (`SPACE_SCALE.sm` 12 -> 13 drove
-    // level -3 to 22px, flush against Mantine's 22px `--ai-size-sm` floor).
-    //
-    // 1.26.0 deletes the sum instead of re-tuning it: `PageBar` folds the page's overflow into a
-    // kebab and moves filters/tabs into the page flow, so there is no second mobile row to reserve
-    // (law C14) and the header is `appShellHeaderHeight` at EVERY width. Row 1's budget is therefore
-    // the whole header, and the thing worth asserting is what law C15 actually promises — that a
-    // `touchControlHeight` target fits inside it below `sm`.
-    for (const level of ALL_LEVELS) {
-      const { step, anchors } = deriveSpacing(level)
-      expect(step.appShellHeaderHeight).toBeGreaterThanOrEqual(anchors.touchControlHeight)
-      expect(anchors.touchControlHeight).toBeGreaterThanOrEqual(anchors.controlHeightCtl)
-    }
-  })
-
-  test('the header row is monotonically non-decreasing across levels', () => {
-    const heights = ALL_LEVELS.map((level) => deriveSpacing(level).step.appShellHeaderHeight)
-    for (let i = 1; i < heights.length; i++) {
-      expect(heights[i]).toBeGreaterThanOrEqual(heights[i - 1]!)
-    }
-  })
-
-  test('the collapsed-rail content box is monotonically non-decreasing across levels', () => {
-    const boxes = ALL_LEVELS.map((level) => {
-      const { step, anchors } = deriveSpacing(level)
-      return step.appShellNavbarRailWidth - 2 * anchors.rowInsetX
-    })
-    for (let i = 1; i < boxes.length; i++) {
-      expect(boxes[i]).toBeGreaterThanOrEqual(boxes[i - 1]!)
-    }
-  })
-
-  test('the navbar label column never shrinks as density rises', () => {
-    const columns = ALL_LEVELS.map((level) => {
-      const { step, anchors } = deriveSpacing(level)
-      return step.appShellNavbarWidth - (4 * anchors.rowInsetX + step.navIconGap)
-    })
-    for (let i = 1; i < columns.length; i++) {
-      expect(columns[i]).toBeGreaterThanOrEqual(columns[i - 1]!)
-    }
-  })
-
-  // The "header/rail 48-coincidence at level 0" check that used to live here is deleted, not
-  // rewritten: it asserted `appShellHeaderHeight === appShellNavbarRailWidth` at level 0, which is
-  // true BY CONSTRUCTION (both `SPACE_STEP_BASE` entries hold the literal same base, 48, and are
-  // mapped through the same deterministic `scaleSpace` call) and stays true at every OTHER level for
-  // the identical reason — no value-based assertion can distinguish "these two happen to share a
-  // base" (a coincidence) from "one is derived from the other" (a law) without mutating the source,
-  // which is out of scope for a value-level test. The actual claim (they are two INDEPENDENT
-  // `SPACE_STEP_BASE` entries, not one derived from the other) is already documented at the source —
-  // see `appShellHeaderHeight`'s own JSDoc in `tokens/palette.ts`.
-
-  test('the footer stays a structural literal — no density-tracking entry for it, and the sm:0 landmine stays fenced', () => {
-    for (const level of ALL_LEVELS) {
-      expect(deriveSpacing(level).step).not.toHaveProperty('appShellFooterHeight')
-    }
-    // `scaleSpace(0, level, m)` floors at 1 for any non-zero level — this is why `shell/index.tsx`'s
-    // `footer.sm` stays a literal 0, never routed through the density law (it would paint a 1px
-    // desktop footer strip at every non-zero level).
-    expect(scaleSpace(0, -5, 0.7)).toBe(1)
-    expect(scaleSpace(0, 5, 1.3)).toBe(1)
-  })
-})
-
-describe('Fix 9 — the Mantine spacing scale keeps its strict xs < sm < md < lg < xl ordering at every level', () => {
-  test('every level: the five scale stops are strictly increasing, never tying or inverting', () => {
-    // Every consumer `p=`/`m=`/`gap=` prop app-wide resolves through this scale, and its five stops
-    // are independently rounded (unlike the anchor group's shared-unit stack rhythm) — a retune plus
-    // rounding could tie or invert two adjacent stops with nothing else in this file catching it.
-    for (const level of ALL_LEVELS) {
-      const { scale } = deriveSpacing(level)
-      expect(scale.xs).toBeLessThan(scale.sm)
-      expect(scale.sm).toBeLessThan(scale.md)
-      expect(scale.md).toBeLessThan(scale.lg)
-      expect(scale.lg).toBeLessThan(scale.xl)
-    }
-  })
-})
-
-describe('Fix 10 — ctl SegmentedControl matches the ctl Button/Input box at every level, not a fixed 30px', () => {
-  // `SegmentedControl.extend`'s function-form `styles` only sets a label `minHeight` when
-  // `props.size === 'ctl'` — everything else (`sm`/`md` in a form) must fall through untouched.
-  const stylesFn = baseTheme.components?.['SegmentedControl']?.styles as
-    | ((t: MantineTheme, props: { size?: string }, ctx: never) => Record<string, unknown>)
-    | undefined
-
-  test('a non-ctl size (e.g. the form default) gets no label override', () => {
-    const result = stylesFn?.(theme, { size: 'md' }, {} as never)
-    expect(
-      (result?.['label'] as Record<string, unknown> | undefined)?.['minHeight'],
-    ).toBeUndefined()
-  })
-
-  test("size='ctl' gets an inline-flex, vertically centred label — Mantine's label is `display: block`, so a bare minHeight alone would leave the text top-aligned", () => {
-    const result = stylesFn?.(theme, { size: 'ctl' }, {} as never)
-    const label = result?.['label'] as Record<string, unknown> | undefined
-    expect(label?.['display']).toBe('inline-flex')
-    expect(label?.['alignItems']).toBe('center')
-  })
-
-  test('the label minHeight formula, plus the root track padding on both sides, reconstructs EXACTLY the same scaled expression as `--button-height-ctl` — the algebraic identity that makes the two controls the same height at every density level, not just level 0', () => {
-    const result = stylesFn?.(theme, { size: 'ctl' }, {} as never)
-    const label = result?.['label'] as Record<string, unknown> | undefined
-    const minHeight = label?.['minHeight']
-    expect(typeof minHeight).toBe('string')
-    const rootPadding = 2 * SPACE_FIXED.segmentedTrackInset
-    expect(minHeight).toBe(
-      `calc(var(--vx-space-control-height-ctl) * var(--mantine-scale) - ${rootPadding}px)`,
-    )
-    // `--button-height-ctl` (`ctlSizeVars` in theme/index.ts) is the un-subtracted form — adding the
-    // root's own `2 * segmentedTrackInset` padding back to the label's minHeight must reproduce it,
-    // for every level, since neither term is level-dependent (the level only changes the CSS var's
-    // RESOLVED value at paint time, never this formula).
-    for (const level of ALL_LEVELS) {
-      // `anchors.controlHeightCtl` is the JS-side value `--vx-space-control-height-ctl` resolves to
-      // at this level (scale = 1, the JS-derivation default) — substituting it into both formulas
-      // must land on the same total.
-      const { anchors } = deriveSpacing(level)
-      const labelHeight = anchors.controlHeightCtl - rootPadding
-      const totalHeight = labelHeight + rootPadding
-      expect(totalHeight).toBe(anchors.controlHeightCtl)
-    }
-  })
-})

package/src/theme/derive-theme.test.ts

@@ -1,101 +0,0 @@
-/**
- * `createBasaltTheme`'s `{ derive }` option — the graduation of the six-knob derive config into a
- * first-class consumer API. Two invariants:
- *
- *  1. The DEFAULT path (no `options`, or a `derive` that resolves back to
- *     `DEFAULT_DERIVE_CONFIG`) stays byte-identical to the pre-baked static palette — zero extra
- *     derivation work, and `theme.other.basaltDerive` stays unset (the provider's "or is absent"
- *     tolerance).
- *  2. A NON-default config lands the fully-resolved `DeriveConfig` on `theme.other.basaltDerive`
- *     (so `BasaltProvider` can inject the matching stylesheet) and produces `--vx-*` CSS that
- *     differs from the shipped default.
- */
-import { describe, expect, test } from 'bun:test'
-import { buildPaletteCss } from '../tokens'
-import { DEFAULT_DERIVE_CONFIG, resolveDeriveConfig } from '../tokens/derive'
-import { buildPaletteData } from '../tokens/palette'
-import { createBasaltTheme } from './index'
-
-describe('the default derive config stays on the static path', () => {
-  test('createBasaltTheme() carries no theme.other.basaltDerive', () => {
-    expect(createBasaltTheme().other?.['basaltDerive']).toBeUndefined()
-  })
-
-  test('createBasaltTheme(undefined, {}) resolves to the same default', () => {
-    expect(createBasaltTheme(undefined, {}).other?.['basaltDerive']).toBeUndefined()
-  })
-
-  test('a derive option that resolves back to the default also carries no basaltDerive', () => {
-    const theme = createBasaltTheme(undefined, { derive: { ...DEFAULT_DERIVE_CONFIG } })
-    expect(theme.other?.['basaltDerive']).toBeUndefined()
-  })
-
-  test('the default palette CSS is byte-identical to the static path', () => {
-    expect(buildPaletteCss(undefined, buildPaletteData(DEFAULT_DERIVE_CONFIG))).toBe(
-      buildPaletteCss(),
-    )
-  })
-})
-
-describe('a non-default derive config graduates onto the theme', () => {
-  const partial = { accent: '#16a34a' }
-  const theme = createBasaltTheme(undefined, { derive: partial })
-
-  test('the resolved config lands on theme.other.basaltDerive', () => {
-    expect(theme.other?.['basaltDerive']).toEqual(resolveDeriveConfig(partial))
-  })
-
-  test('its palette CSS differs from the shipped default', () => {
-    const resolved = resolveDeriveConfig(partial)
-    const customCss = buildPaletteCss(undefined, buildPaletteData(resolved))
-    expect(customCss).not.toBe(buildPaletteCss())
-  })
-
-  test('the accent fill in theme.colors.blue follows the custom seed', () => {
-    const resolved = resolveDeriveConfig(partial)
-    const data = buildPaletteData(resolved)
-    const blue = theme.colors?.['blue']
-    expect(blue?.[6]).toBe(data.ACCENT.accentFill.light)
-  })
-})
-
-describe('consumer overrides still win on top of a derive config', () => {
-  test('an explicit override merges onto the derived theme', () => {
-    const theme = createBasaltTheme({ primaryColor: 'green' }, { derive: { accent: '#16a34a' } })
-    expect(theme.primaryColor).toBe('green')
-    expect(theme.other?.['basaltDerive']).toEqual(resolveDeriveConfig({ accent: '#16a34a' }))
-  })
-})
-
-describe('a non-default derive config yields a dark tuple that tracks its own derived data', () => {
-  // `accent` alone doesn't move the dark tuple (it's built from INK/SURFACE, which key off
-  // `neutral` + `darkLevel`, not the accent seed) — vary `darkLevel` so the tuple's surface-based
-  // stops (border/hover/panel/body) actually diverge from the shipped default's.
-  const partial = { darkLevel: 3 }
-  const resolved = resolveDeriveConfig(partial)
-  const data = buildPaletteData(resolved)
-  const theme = createBasaltTheme(undefined, { derive: partial })
-
-  test('theme.colors.dark follows the derived data', () => {
-    expect(theme.colors?.['dark']?.[0]).toBe(data.INK.ink.dark)
-    expect(theme.colors?.['dark']?.[7]).toBe(data.SURFACE.bg.dark)
-  })
-
-  test("a non-default config yields a dark tuple that differs from the DEFAULT theme's", () => {
-    expect(theme.colors?.['dark']).not.toEqual(createBasaltTheme().colors?.['dark'])
-  })
-})
-
-describe('a malformed accent seed throws through createBasaltTheme', () => {
-  test('rejects a non-hex color name', () => {
-    expect(() => createBasaltTheme(undefined, { derive: { accent: 'red' } })).toThrow()
-  })
-
-  test('rejects a truncated hex', () => {
-    expect(() => createBasaltTheme(undefined, { derive: { accent: '#12' } })).toThrow()
-  })
-
-  test('rejects a non-hex-digit hex', () => {
-    expect(() => createBasaltTheme(undefined, { derive: { accent: '#zzzzzz' } })).toThrow()
-  })
-})