@freighttech/ui 0.13.18

package/src/backend/dynamic-table/__tests__/contentRegistry.test.ts

@@ -0,0 +1,267 @@
+/**
+ * The unified content registry: tables AND widgets, one lookup, four states.
+ *
+ * The interesting assertions are the negative ones. `denied` and `unknown` are
+ * different messages to the user and different bugs to a developer, so the pair
+ * that separates them (catalogue absence vs. code absence) is pinned here — as
+ * is default-deny, which is the behaviour that stops a missing provider from
+ * silently offering everything.
+ *
+ * Unit companion to TC-APP-603 (picker lists both kinds, ACL-filtered) and
+ * TC-APP-609 (a layout naming a removed widget degrades that pane only).
+ * Spec: .ai/specs/2026-08-17-split-view-workspace-composition.md
+ */
+
+import * as React from 'react'
+import { renderHook } from '@testing-library/react'
+import {
+  ContentRegistryProvider,
+  useAccessibleContent,
+  useContentById,
+  type ContentStatus,
+  type PaneContentItem,
+} from '../registry/ContentRegistryContext'
+import { TableRegistryProvider } from '../registry/TableRegistryContext'
+import type { TableDefinition } from '../registry/types'
+import type { WidgetCatalogEntry } from '../registry/widgetCatalog'
+import type { PaneContentRef } from '../split-view/types'
+
+// ── fixtures ────────────────────────────────────────────────────────────────
+
+function makeTable(id: string, features: string[], group = 'Sales'): TableDefinition {
+  return {
+    metadata: {
+      id,
+      title: `Table ${id}`,
+      titleKey: `tables.${id}`,
+      features,
+      perspectiveTableId: id,
+      entityId: id.replace('.', ':'),
+      href: `/backend/${id}`,
+      group,
+    },
+    Table: () => null,
+  }
+}
+
+function makeWidget(id: string, loaderKey: string, moduleId = 'invoicing'): WidgetCatalogEntry {
+  return {
+    id,
+    title: `Widget ${id}`,
+    description: null,
+    loaderKey,
+    icon: null,
+    features: ['dashboards.view'],
+    moduleId,
+    defaultSettings: { window: 30 },
+    defaultSize: 'md',
+    supportsRefresh: true,
+  }
+}
+
+const OFFERS = makeTable('offers.offer', ['offers.offers.view'])
+const INVOICES = makeTable('invoicing.invoice', ['invoicing.invoices.view'], 'Finance')
+const INFLOWS = makeWidget('invoicing.dashboard.inflows', 'invoicing:inflows:widget')
+
+type Options = {
+  tables?: TableDefinition[]
+  granted?: string[]
+  tablesReady?: boolean
+  widgets?: WidgetCatalogEntry[]
+  widgetsReady?: boolean
+  /** Widget code present in the build but absent from the allowed catalogue. */
+  existingLoaderKeys?: string[]
+  /** Omit both providers, to exercise the default context. */
+  noProvider?: boolean
+}
+
+function wrapperFor(options: Options) {
+  const granted = new Set(options.granted ?? [])
+  const contentValue = {
+    widgets: options.widgets ?? [],
+    context: null,
+    ready: options.widgetsReady ?? true,
+    loaderKeyExists: (key: string) => (options.existingLoaderKeys ?? []).includes(key),
+  }
+  const tableValue = {
+    tables: options.tables ?? [],
+    hasFeature: (feature: string) => granted.has(feature),
+    ready: options.tablesReady ?? true,
+  }
+
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    if (options.noProvider) return React.createElement(React.Fragment, null, children)
+    return React.createElement(
+      TableRegistryProvider,
+      { value: tableValue },
+      React.createElement(ContentRegistryProvider, { value: contentValue }, children),
+    )
+  }
+}
+
+function accessible(options: Options): PaneContentItem[] {
+  return renderHook(() => useAccessibleContent(), { wrapper: wrapperFor(options) }).result.current
+}
+
+function resolve(ref: PaneContentRef | null, options: Options): {
+  item: PaneContentItem | null
+  status: ContentStatus
+} {
+  return renderHook(() => useContentById(ref), { wrapper: wrapperFor(options) }).result.current
+}
+
+// ── tests ───────────────────────────────────────────────────────────────────
+
+describe('useAccessibleContent', () => {
+  it('TC-APP-603 lists tables and widgets together, each carrying its kind, title and group', () => {
+    const items = accessible({
+      tables: [OFFERS, INVOICES],
+      granted: ['offers.offers.view', 'invoicing.invoices.view'],
+      widgets: [INFLOWS],
+    })
+
+    expect(items).toHaveLength(3)
+    expect(items.map((i) => [i.kind, i.id])).toEqual([
+      ['table', 'offers.offer'],
+      ['table', 'invoicing.invoice'],
+      ['widget', 'invoicing.dashboard.inflows'],
+    ])
+    expect(items.find((i) => i.id === 'invoicing.invoice')?.group).toBe('Finance')
+    // A widget's group is its owning module — the only grouping the DTO carries.
+    expect(items.find((i) => i.kind === 'widget')?.group).toBe('invoicing')
+  })
+
+  it('TC-APP-603 drops tables whose features are not granted, keeping the rest', () => {
+    const items = accessible({
+      tables: [OFFERS, INVOICES],
+      granted: ['offers.offers.view'],
+      widgets: [INFLOWS],
+    })
+
+    expect(items.map((i) => i.id)).toEqual(['offers.offer', 'invoicing.dashboard.inflows'])
+  })
+
+  it('TC-APP-603 lists only the widgets the catalogue returned — the server is the ACL for widgets', () => {
+    // The catalogue endpoint returns the ALLOWED set only, so "filtering" a
+    // widget means it never arrives. Nothing client-side may add one back.
+    const items = accessible({ tables: [], granted: [], widgets: [] })
+    expect(items).toEqual([])
+  })
+
+  it('carries loaderKey on widgets so a picked widget can be reopened without the catalogue', () => {
+    const items = accessible({ widgets: [INFLOWS] })
+    const widget = items[0]
+    expect(widget.kind).toBe('widget')
+    expect(widget.kind === 'widget' && widget.loaderKey).toBe('invoicing:inflows:widget')
+  })
+
+  it('offers nothing when no provider is mounted (default-deny)', () => {
+    const items = accessible({
+      noProvider: true,
+      tables: [OFFERS],
+      granted: ['offers.offers.view'],
+      widgets: [INFLOWS],
+    })
+    expect(items).toEqual([])
+  })
+})
+
+describe('useContentById — tables', () => {
+  it('resolves a granted table to ok', () => {
+    const { item, status } = resolve(
+      { kind: 'table', tableId: 'offers.offer' },
+      { tables: [OFFERS], granted: ['offers.offers.view'] },
+    )
+    expect(status).toBe('ok')
+    expect(item?.kind).toBe('table')
+    expect(item?.title).toBe('Table offers.offer')
+  })
+
+  it('reports an unregistered table id as unknown', () => {
+    const { item, status } = resolve(
+      { kind: 'table', tableId: 'gone.table' },
+      { tables: [OFFERS], granted: ['offers.offers.view'] },
+    )
+    expect(status).toBe('unknown')
+    expect(item).toBeNull()
+  })
+
+  it('reports a registered but ungranted table as denied', () => {
+    const { status } = resolve({ kind: 'table', tableId: 'offers.offer' }, { tables: [OFFERS], granted: [] })
+    expect(status).toBe('denied')
+  })
+
+  it('reports loading while grants are still in flight, never denied', () => {
+    // Denying during the fetch would flash "no access" at a user who has it.
+    const { status } = resolve(
+      { kind: 'table', tableId: 'offers.offer' },
+      { tables: [OFFERS], granted: [], tablesReady: false },
+    )
+    expect(status).toBe('loading')
+  })
+})
+
+describe('useContentById — widgets', () => {
+  it('TC-APP-604 resolves a catalogued widget to ok, with its loader key and defaults', () => {
+    const { item, status } = resolve(
+      { kind: 'widget', widgetId: 'invoicing.dashboard.inflows', loaderKey: 'invoicing:inflows:widget' },
+      { widgets: [INFLOWS] },
+    )
+    expect(status).toBe('ok')
+    expect(item?.kind).toBe('widget')
+    expect(item?.kind === 'widget' && item.loaderKey).toBe('invoicing:inflows:widget')
+    expect(item?.kind === 'widget' && item.defaultSettings).toEqual({ window: 30 })
+  })
+
+  it('TC-APP-609 reports a widget absent from the catalogue AND from the build as unknown', () => {
+    const { item, status } = resolve(
+      { kind: 'widget', widgetId: 'offers.dashboard.deleted', loaderKey: 'offers:deleted:widget' },
+      { widgets: [INFLOWS], existingLoaderKeys: [] },
+    )
+    expect(status).toBe('unknown')
+    expect(item).toBeNull()
+  })
+
+  it('TC-APP-609 reports a widget absent from the catalogue but still in the build as denied', () => {
+    // The distinction that stops "you may not have this" and "this no longer
+    // exists" collapsing into one wrong message.
+    const { status } = resolve(
+      { kind: 'widget', widgetId: 'offers.dashboard.unsent', loaderKey: 'offers:unsent:widget' },
+      { widgets: [INFLOWS], existingLoaderKeys: ['offers:unsent:widget'] },
+    )
+    expect(status).toBe('denied')
+  })
+
+  it('reports loading while the catalogue is in flight, never unknown', () => {
+    const { status } = resolve(
+      { kind: 'widget', widgetId: 'invoicing.dashboard.inflows', loaderKey: 'invoicing:inflows:widget' },
+      { widgets: [], widgetsReady: false, existingLoaderKeys: ['invoicing:inflows:widget'] },
+    )
+    expect(status).toBe('loading')
+  })
+
+  it('never resolves a widget to ok when no provider is mounted, and warns the developer', () => {
+    // Default-deny for the user; loud for whoever forgot the provider. Without
+    // the warning this reads as "the widget was deleted", which sends the next
+    // person looking in entirely the wrong place.
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      const { item, status } = resolve(
+        { kind: 'widget', widgetId: 'invoicing.dashboard.inflows', loaderKey: 'invoicing:inflows:widget' },
+        { noProvider: true },
+      )
+      expect(status).not.toBe('ok')
+      expect(status).toBe('unknown')
+      expect(item).toBeNull()
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('ContentRegistryBootstrap'))
+    } finally {
+      warn.mockRestore()
+    }
+  })
+
+  it('treats a null ref as unknown rather than throwing', () => {
+    const { item, status } = resolve(null, { widgets: [INFLOWS] })
+    expect(status).toBe('unknown')
+    expect(item).toBeNull()
+  })
+})

package/src/backend/dynamic-table/__tests__/dateWindows.test.ts

@@ -0,0 +1,149 @@
+import { isDateWindowOperator, resolveDateWindow } from '../server/dateWindows'
+
+/**
+ * The shared date-window resolver (workshop A14).
+ *
+ * The point of the module is that the now-relative presets and the explicit
+ * `is_between` range are ONE mechanism: whatever route applies the filter — SQL
+ * push-down or in-memory comparator — it resolves the operator here and gets
+ * the same `[from, to]`. These tests pin the windows themselves; the two
+ * consumers are pinned separately (`filterParser.presets`, the folders route).
+ *
+ * Anchor: 2026-06-12 is a Friday (ISO weekday 5), so
+ *   this ISO week = Mon 2026-06-08 … Sun 2026-06-14
+ *   next ISO week = Mon 2026-06-15 … Sun 2026-06-21
+ * All arithmetic is local-time, so expectations build local Dates the same way.
+ */
+
+const now = new Date(2026, 5, 12, 10, 30) // Fri 2026-06-12 10:30 local
+const startOfDay = (y: number, m: number, d: number) => new Date(y, m, d, 0, 0, 0, 0)
+const endOfDay = (y: number, m: number, d: number) => new Date(y, m, d, 23, 59, 59, 999)
+
+describe('resolveDateWindow — now-relative presets', () => {
+  it('is_today → the whole of today', () => {
+    const w = resolveDateWindow('is_today', [], now)!
+    expect(w.from!.getTime()).toBe(startOfDay(2026, 5, 12).getTime())
+    expect(w.to!.getTime()).toBe(endOfDay(2026, 5, 12).getTime())
+    expect(w.toExclusive).toBeFalsy()
+  })
+
+  it('is_tomorrow → the whole of tomorrow', () => {
+    const w = resolveDateWindow('is_tomorrow', [], now)!
+    expect(w.from!.getTime()).toBe(startOfDay(2026, 5, 13).getTime())
+    expect(w.to!.getTime()).toBe(endOfDay(2026, 5, 13).getTime())
+  })
+
+  it('is_this_week → today through Sunday (upcoming, not past days)', () => {
+    const w = resolveDateWindow('is_this_week', [], now)!
+    expect(w.from!.getTime()).toBe(startOfDay(2026, 5, 12).getTime())
+    expect(w.to!.getTime()).toBe(endOfDay(2026, 5, 14).getTime())
+  })
+
+  it('is_next_week → Monday through Sunday of next ISO week', () => {
+    const w = resolveDateWindow('is_next_week', [], now)!
+    expect(w.from!.getTime()).toBe(startOfDay(2026, 5, 15).getTime())
+    expect(w.to!.getTime()).toBe(endOfDay(2026, 5, 21).getTime())
+  })
+
+  it('is_overdue → unbounded below, EXCLUSIVE at the start of today', () => {
+    // Exclusivity is the reason `DateWindow` carries a flag at all: "overdue"
+    // must not match anything happening today, and an inclusive end-of-yesterday
+    // bound only reproduces that by a millisecond fudge.
+    const w = resolveDateWindow('is_overdue', [], now)!
+    expect(w.from).toBeNull()
+    expect(w.to!.getTime()).toBe(startOfDay(2026, 5, 12).getTime())
+    expect(w.toExclusive).toBe(true)
+  })
+
+  it('presets ignore stray values', () => {
+    const w = resolveDateWindow('is_today', ['garbage', 'more'], now)!
+    expect(w.from!.getTime()).toBe(startOfDay(2026, 5, 12).getTime())
+  })
+
+  it('re-resolves against the clock it is given — a saved preset never goes stale', () => {
+    const later = new Date(2027, 0, 4, 8, 0)
+    const w = resolveDateWindow('is_today', [], later)!
+    expect(w.from!.getTime()).toBe(startOfDay(2027, 0, 4).getTime())
+  })
+})
+
+describe('resolveDateWindow — moving windows', () => {
+  it('is_in_next N days → [start of today, end of today + N]', () => {
+    const w = resolveDateWindow('is_in_next', ['7', 'days'], now)!
+    expect(w.from!.getTime()).toBe(startOfDay(2026, 5, 12).getTime())
+    expect(w.to!.getTime()).toBe(endOfDay(2026, 5, 19).getTime())
+  })
+
+  it('is_in_last N days → [start of today - N, end of today]', () => {
+    const w = resolveDateWindow('is_in_last', ['7', 'days'], now)!
+    expect(w.from!.getTime()).toBe(startOfDay(2026, 5, 5).getTime())
+    expect(w.to!.getTime()).toBe(endOfDay(2026, 5, 12).getTime())
+  })
+
+  it('months clamp to the end of the target month', () => {
+    const may31 = new Date(2026, 4, 31, 12, 0)
+    const w = resolveDateWindow('is_in_last', ['1', 'months'], may31)!
+    expect(w.from!.getTime()).toBe(startOfDay(2026, 3, 30).getTime()) // Apr 30, not May 1
+  })
+
+  it('a missing or non-integer count drops the rule rather than matching nothing', () => {
+    expect(resolveDateWindow('is_in_next', [], now)).toBeNull()
+    expect(resolveDateWindow('is_in_next', ['1.5', 'days'], now)).toBeNull()
+    expect(resolveDateWindow('is_in_next', ['5abc', 'days'], now)).toBeNull()
+    expect(resolveDateWindow('is_in_next', ['0', 'days'], now)).toBeNull()
+  })
+
+  it('an unknown unit falls back to days', () => {
+    const bogus = resolveDateWindow('is_in_next', ['5', 'fortnights'], now)!
+    const days = resolveDateWindow('is_in_next', ['5', 'days'], now)!
+    expect(bogus.to!.getTime()).toBe(days.to!.getTime())
+  })
+})
+
+describe('resolveDateWindow — explicit is_between range', () => {
+  it('both ends → day-bounded inclusive range', () => {
+    const w = resolveDateWindow('is_between', ['2026-07-01', '2026-07-31'], now)!
+    expect(w.from!.getTime()).toBe(startOfDay(2026, 6, 1).getTime())
+    expect(w.to!.getTime()).toBe(endOfDay(2026, 6, 31).getTime())
+  })
+
+  it('half-open ranges stay useful — the missing side is unbounded', () => {
+    const openTop = resolveDateWindow('is_between', ['2026-07-01', ''], now)!
+    expect(openTop.from!.getTime()).toBe(startOfDay(2026, 6, 1).getTime())
+    expect(openTop.to).toBeNull()
+
+    const openBottom = resolveDateWindow('is_between', ['', '2026-07-31'], now)!
+    expect(openBottom.from).toBeNull()
+    expect(openBottom.to!.getTime()).toBe(endOfDay(2026, 6, 31).getTime())
+  })
+
+  it('neither end filled → drop the rule (never "match nothing")', () => {
+    expect(resolveDateWindow('is_between', ['', ''], now)).toBeNull()
+    expect(resolveDateWindow('is_between', [], now)).toBeNull()
+  })
+
+  it('rejects non-ISO input instead of guessing', () => {
+    expect(resolveDateWindow('is_between', ['01/07/2026', '31/07/2026'], now)).toBeNull()
+  })
+})
+
+describe('isDateWindowOperator', () => {
+  it('covers presets, moving windows AND the explicit range', () => {
+    for (const op of [
+      'is_today', 'is_tomorrow', 'is_this_week', 'is_next_week', 'is_overdue',
+      'is_in_next', 'is_in_last', 'is_between',
+    ]) {
+      expect(isDateWindowOperator(op)).toBe(true)
+    }
+  })
+
+  it('excludes the single-sided date operators, which take a picked date', () => {
+    for (const op of ['is_before', 'is_after', 'is_on_or_before', 'is_on_or_after', 'equals', 'contains']) {
+      expect(isDateWindowOperator(op)).toBe(false)
+    }
+  })
+
+  it('an unknown operator resolves to no window', () => {
+    expect(resolveDateWindow('is_next_millennium', [], now)).toBeNull()
+  })
+})

package/src/backend/dynamic-table/__tests__/density.test.ts

@@ -0,0 +1,204 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import {
+  DENSITY_LEVELS,
+  DEFAULT_DENSITY,
+  DENSITY_ATTRIBUTE,
+  DENSITY_METRICS,
+  isDensityLevel,
+  resolveDensityAttribute,
+  resolveDensityRowHeight,
+  type DensityLevel,
+} from '../types/density'
+
+const CSS_PATH = resolve(__dirname, '../styles/density.css')
+const css = readFileSync(CSS_PATH, 'utf8')
+
+/**
+ * Pull the value of a custom property out of a level's variable block.
+ * Deliberately a dumb text scan, not a CSS parser: the point is to fail loudly
+ * when the two sources of truth drift, and a parser dependency would be a
+ * bigger liability than the regex.
+ */
+function readVar(level: DensityLevel, prop: string): string | null {
+  const blockMatch = css.match(
+    new RegExp(String.raw`\[data-density-level="${level}"\]\s*\{([\s\S]*?)\}`),
+  )
+  if (!blockMatch) return null
+  const declMatch = blockMatch[1].match(new RegExp(String.raw`${prop}\s*:\s*([^;]+);`))
+  return declMatch ? declMatch[1].trim() : null
+}
+
+describe('density scale — the setting', () => {
+  it('defaults to comfortable, so shipping the feature is a visual no-op', () => {
+    expect(DEFAULT_DENSITY).toBe('comfortable')
+  })
+
+  it('exposes exactly three levels, coarsest first', () => {
+    expect(DENSITY_LEVELS).toEqual(['comfortable', 'compact', 'dense'])
+  })
+
+  it('does NOT reuse the legacy `data-density` attribute', () => {
+    // `data-density` already carries the developer-facing 'sm' | 'md' prop, and
+    // DynamicTable.v2.css has `:not([data-density])` rules that define part of
+    // today's DEFAULT rendering. Reusing it would switch those off the moment a
+    // user picked `comfortable`.
+    expect(DENSITY_ATTRIBUTE).toBe('data-density-level')
+    expect(DENSITY_ATTRIBUTE).not.toBe('data-density')
+  })
+})
+
+describe('resolveDensityAttribute', () => {
+  it('maps each level to its own attribute value', () => {
+    for (const level of DENSITY_LEVELS) {
+      expect(resolveDensityAttribute(level)).toBe(level)
+    }
+  })
+
+  it('falls back to the default for a corrupt stored preference', () => {
+    // A bad value in localStorage must not break the grid.
+    expect(resolveDensityAttribute(undefined)).toBe('comfortable')
+    expect(resolveDensityAttribute(null)).toBe('comfortable')
+    expect(resolveDensityAttribute('cosy' as unknown as DensityLevel)).toBe('comfortable')
+  })
+
+  it('is pure — same input, same interned output, no allocation', () => {
+    expect(resolveDensityAttribute('dense')).toBe(resolveDensityAttribute('dense'))
+  })
+})
+
+describe('isDensityLevel', () => {
+  it('accepts only the three levels', () => {
+    expect(isDensityLevel('comfortable')).toBe(true)
+    expect(isDensityLevel('compact')).toBe(true)
+    expect(isDensityLevel('dense')).toBe(true)
+    for (const bad of ['', 'DENSE', 'sm', 'md', 0, null, undefined, {}]) {
+      expect(isDensityLevel(bad)).toBe(false)
+    }
+  })
+})
+
+describe('density metrics ↔ density.css', () => {
+  it('comfortable is TODAY\'S sizing, pinned', () => {
+    // 32px is DynamicTable.tsx `dataRowHeight` default. If this changes, the
+    // "opting out is a no-op" guarantee is gone.
+    expect(DENSITY_METRICS.comfortable.rowHeight).toBe(32)
+    expect(DENSITY_METRICS.comfortable.headerHeight).toBeNull()
+    expect(readVar('comfortable', '--dt-header-height')).toBe('auto')
+  })
+
+  it('row heights strictly decrease across the scale', () => {
+    const heights = DENSITY_LEVELS.map((l) => DENSITY_METRICS[l].rowHeight)
+    expect(heights).toEqual([...heights].sort((a, b) => b - a))
+    expect(new Set(heights).size).toBe(heights.length)
+  })
+
+  it.each(DENSITY_LEVELS)(
+    '%s: --dt-row-height in CSS equals DENSITY_METRICS (the virtualizer reads the TS one)',
+    (level) => {
+      // The virtualizer positions rows with translateY from the TS number while
+      // the box model comes from the CSS one. Drift = overlapping rows.
+      expect(readVar(level, '--dt-row-height')).toBe(`${DENSITY_METRICS[level].rowHeight}px`)
+    },
+  )
+
+  it('every level declares the full variable set — a missing var silently inherits', () => {
+    const required = [
+      '--dt-row-height',
+      '--dt-row-gap-top',
+      '--dt-row-gap-bottom',
+      '--dt-row-rule-color',
+      '--dt-cell-pad-y',
+      '--dt-cell-pad-x',
+      '--dt-header-height',
+      '--dt-header-pad-y',
+      '--dt-header-pad-x',
+      '--dt-header-gap',
+      '--dt-cell-font-size',
+      '--dt-cell-line-height',
+      '--dt-cell-letter-spacing',
+      '--dt-mono-font-size',
+      '--dt-mono-line-height',
+      '--dt-mono-letter-spacing',
+      '--dt-header-font-size',
+      '--dt-header-line-height',
+      '--dt-header-letter-spacing',
+      '--dt-header-font-weight',
+      '--dt-badge-pad-y',
+      '--dt-badge-pad-x',
+      '--dt-badge-font-size',
+      '--dt-badge-line-height',
+      '--dt-editor-inset-y',
+      '--dt-editor-inset-x',
+      '--dt-editor-pad-x',
+      '--dt-editor-line-height',
+    ]
+    // Collect first, assert once — a missing var then names itself in the diff
+    // instead of failing as an anonymous `null`.
+    const missing: string[] = []
+    for (const level of DENSITY_LEVELS) {
+      for (const prop of required) {
+        if (readVar(level, prop) === null) missing.push(`${level} ${prop}`)
+      }
+    }
+    expect(missing).toEqual([])
+  })
+
+  it('the box model closes: padding + borders + line-height fit inside the row', () => {
+    const px = (v: string | null) => Number.parseFloat(v ?? 'NaN')
+    // Resolved line-heights, in px, of the token each level points its data
+    // cells at (comfortable/compact → body/regular/xs 16px, dense → 2xs 14px).
+    const lineHeightPx: Record<DensityLevel, number> = {
+      comfortable: 16,
+      compact: 16,
+      dense: 14,
+    }
+    const overflowing = DENSITY_LEVELS.filter((level) => {
+      const chrome =
+        px(readVar(level, '--dt-row-gap-top')) +
+        px(readVar(level, '--dt-row-gap-bottom')) +
+        2 * px(readVar(level, '--dt-cell-pad-y'))
+      return DENSITY_METRICS[level].rowHeight - chrome < lineHeightPx[level]
+    })
+    expect(overflowing).toEqual([])
+  })
+
+  it('dense trades whitespace separation for a hairline rule', () => {
+    // At 20px there is no whitespace left to separate rows with; the hairline
+    // is what lets the eye track one record across 20+ columns.
+    expect(readVar('dense', '--dt-row-gap-top')).toBe('0px')
+    expect(readVar('dense', '--dt-row-rule-color')).not.toBe('transparent')
+    // The looser levels keep the rounded-pill look.
+    expect(readVar('comfortable', '--dt-row-rule-color')).toBe('transparent')
+    expect(readVar('compact', '--dt-row-rule-color')).toBe('transparent')
+  })
+
+  it('compact keeps today\'s 12px type — only geometry tightens', () => {
+    // The safe recommendation: nothing that was legible stops being legible.
+    expect(readVar('compact', '--dt-cell-font-size')).toBe(readVar('comfortable', '--dt-cell-font-size'))
+    expect(readVar('compact', '--dt-cell-line-height')).toBe(readVar('comfortable', '--dt-cell-line-height'))
+  })
+})
+
+describe('comfortable is a no-op by construction', () => {
+  it('no consuming rule targets the comfortable level', () => {
+    // Every consuming rule is guarded by :not([data-density-level="comfortable"]).
+    // Count selectors that mention the attribute but are NOT a variable block
+    // and NOT guarded — there must be none.
+    const consuming = css
+      .split('\n')
+      .filter((line) => line.includes('[data-density-level]'))
+      .filter((line) => !line.includes(':not([data-density-level="comfortable"])'))
+    expect(consuming).toEqual([])
+  })
+})
+
+describe('resolveDensityRowHeight', () => {
+  it('returns the level height, or the default height for junk', () => {
+    expect(resolveDensityRowHeight('dense')).toBe(DENSITY_METRICS.dense.rowHeight)
+    expect(resolveDensityRowHeight('nope' as unknown as DensityLevel)).toBe(
+      DENSITY_METRICS.comfortable.rowHeight,
+    )
+  })
+})