bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.8

package/dist/ai/source/BbTable.md

@@ -17,45 +17,51 @@
 		:style="containerStyle"
 	>
 		<legend v-if="selectable" class="sr-only">{{ legendText }}</legend>
-		<table
+		<!-- The caption lives OUTSIDE the table role (a `caption` role is invalid
+		there for a div table) and names the table through `aria-labelledby`. -->
+		<div
+			v-if="caption"
+			:id="captionId"
+			class="bb-table-caption"
+			:class="{
+				'sr-only': !displayCaption,
+			}"
+		>
+			{{ caption }}
+		</div>
+		<!-- The grid root. It owns `grid-template-columns` (the tracks ARE the
+		column API); rowgroups and rows are subgrids that inherit them. The role
+		chain table → rowgroup → row → columnheader/cell must stay unbroken: a
+		single unroled wrapper between two levels collapses the whole tree to
+		generic for assistive tech. -->
+		<div
 			ref="tableRef"
+			:aria-labelledby="caption ? captionId : undefined"
 			:aria-rowcount="
-				hasProvidedAccessibilityData ? contextState.totalItems : undefined
+				hasProvidedAccessibilityData && contextState.totalItems != null
+					? contextState.totalItems + 1
+					: undefined
 			"
+			class="bb-table__table"
+			role="table"
+			:style="{ gridTemplateColumns: gridTemplate }"
 		>
-			<caption
-				v-if="caption"
-				class="bb-table-caption"
-				:class="{
-					'sr-only': !displayCaption,
-				}"
-			>
-				{{
-					caption
-				}}
-			</caption>
-			<colgroup>
-				<col
-					v-for="track in columnTracks"
-					:key="track.key"
-					:style="{ width: track.width }"
-				/>
-			</colgroup>
 			<!-- Inert while loading too: sorting or select-all would fire against
 			rows that are about to be replaced. -->
-			<thead :inert="contentInert">
+			<div class="bb-table__head" :inert="contentInert" role="rowgroup">
 				<!-- @vue-ignore -->
 				<slot name="thead">
-					<tr
+					<div
 						:aria-rowindex="hasProvidedAccessibilityData ? 1 : undefined"
 						class="bb-table-header-row"
 						:class="headerRowClass"
+						role="row"
 					>
-						<th
+						<div
 							v-if="selectable"
 							class="bb-table-header bb-table-header--select"
 							:class="thClass"
-							scope="col"
+							role="columnheader"
 						>
 							<!-- @vue-ignore -->
 							<slot
@@ -93,8 +99,8 @@
 									>
 								</span>
 							</slot>
-						</th>
-						<th
+						</div>
+						<div
 							v-for="(header, index) in mappedHeaders"
 							:key="header.key"
 							:aria-sort="
@@ -109,8 +115,13 @@
 										index === mappedHeaders.length - 1,
 								},
 							]"
-							scope="col"
+							role="columnheader"
 						>
+							<component
+								:is="headerAffixFor(header.key, 'prepend')"
+								v-if="headerAffixFor(header.key, 'prepend')"
+								v-bind="headerAffixScope(header)"
+							/>
 							<!-- @vue-ignore -->
 							<slot
 								:classes="header.classes"
@@ -134,22 +145,39 @@
 									<span class="bb-table-header__content">{{
 										header.label
 									}}</span>
-									<BbIcon
+									<!-- One up arrow (ascending, AG Grid convention); the desc state
+									rotates it 180° (the glyph is its own mirror), so the flip
+									between directions animates. -->
+									<svg
+										aria-hidden="true"
 										class="bb-table-sort__icon"
-										:icon="sortIcon"
-										size="sm"
-									/>
+										fill="none"
+										height="1em"
+										stroke="currentColor"
+										stroke-linecap="round"
+										stroke-linejoin="round"
+										stroke-width="2"
+										viewBox="0 0 24 24"
+										width="1em"
+									>
+										<path d="M12 20V4m-7 7l7-7l7 7" />
+									</svg>
 								</BbBaseButton>
 								<span v-else class="bb-table-header__content">{{
 									header.label
 								}}</span>
 							</slot>
-						</th>
-						<th
+							<component
+								:is="headerAffixFor(header.key, 'append')"
+								v-if="headerAffixFor(header.key, 'append')"
+								v-bind="headerAffixScope(header)"
+							/>
+						</div>
+						<div
 							v-if="actions"
 							class="bb-table-header bb-table-header--actions"
 							:class="thClass"
-							scope="col"
+							role="columnheader"
 						>
 							<!-- @vue-ignore -->
 							<slot
@@ -160,11 +188,11 @@
 									{{ actionsText || t('table.actionsText').value }}
 								</span>
 							</slot>
-						</th>
-					</tr>
+						</div>
+					</div>
 				</slot>
-			</thead>
-			<tbody>
+			</div>
+			<div class="bb-table__body" role="rowgroup">
 				<!-- Skeletons only when there is nothing to show. A refetch over
 				existing rows keeps them on screen (dimmed, with the busy bar above)
 				instead of blanking the table — see `.bb-table--loading` in the CSS. -->
@@ -174,23 +202,26 @@
 					name="loading"
 				>
 					<template v-for="(_, rowIndex) in skeletonLength" :key="rowIndex">
-						<tr
+						<div
 							:aria-rowindex="
 								hasProvidedAccessibilityData ? rowIndex + 2 : undefined
 							"
 							class="bb-table-skeleton__row"
+							role="row"
 						>
-							<td
+							<div
 								v-if="selectable"
 								class="bb-table-skeleton__cell bb-table-skeleton__cell--select"
+								role="cell"
 							>
 								<div class="bb-table-skeleton__placeholder" />
-							</td>
-							<td
+							</div>
+							<div
 								v-for="(col, colIndex) in props.columns"
 								:key="col.key"
 								class="bb-table-skeleton__cell"
 								:class="[`bb-table-skeleton__cell--${col.skeleton ?? 'text'}`]"
+								role="cell"
 							>
 								<!-- text: 2 lines with dynamic widths -->
 								<template v-if="!col.skeleton || col.skeleton === 'text'">
@@ -245,37 +276,42 @@
 									v-else-if="col.skeleton === 'badge'"
 									class="bb-table-skeleton__badge"
 								/>
-							</td>
-							<td
+							</div>
+							<div
 								v-if="actions"
 								class="bb-table-skeleton__cell bb-table-skeleton__cell--actions"
+								role="cell"
 							>
 								<div class="bb-table-skeleton__placeholder" />
-							</td>
-						</tr>
+							</div>
+						</div>
 					</template>
 				</slot>
 				<!-- The empty state's row/cell shell is the table's, not the
-				consumer's: the slot fills a full-width cell (the colspan already
-				accounts for the selection/actions columns) so custom content is
-				centred across the table instead of landing as stray markup inside
-				`<tbody>`. -->
-				<tr
+				consumer's: the slot fills a full-width cell (spanning the selection/
+				actions columns too) so custom content is centred across the table
+				instead of landing as stray markup inside the body. -->
+				<div
 					v-else-if="!options.length"
 					:aria-rowindex="hasProvidedAccessibilityData ? 2 : undefined"
 					class="bb-table-no-data__row"
+					role="row"
 				>
-					<td class="bb-table-no-data__cell" :colspan="replacementContentSpan">
+					<div
+						:aria-colspan="replacementContentSpan"
+						class="bb-table-no-data__cell"
+						role="cell"
+					>
 						<slot name="no-data">
 							<span class="bb-table-no-data__text">{{
 								noDataText || t('common.noDataText').value
 							}}</span>
 						</slot>
-					</td>
-				</tr>
+					</div>
+				</div>
 				<slot v-else name="tbody">
 					<template v-for="(item, index) in mappedItems" :key="item.valueHash">
-						<tr
+						<div
 							:aria-current="item.highlighted ? 'true' : undefined"
 							:aria-rowindex="
 								hasProvidedAccessibilityData && item.rowIndex
@@ -288,6 +324,7 @@
 								{ 'bb-table-data__row--highlighted': item.highlighted },
 							]"
 							:inert="contentInert"
+							role="row"
 							:tabindex="
 								keyboardNavigation
 									? index === activeRowIndex
@@ -301,10 +338,11 @@
 							@focus="() => onRowFocus(index)"
 							@keydown="(event) => onRowKeydown(event, index)"
 						>
-							<td
+							<div
 								v-if="selectable"
 								class="bb-table-data__cell bb-table-data__cell--select"
 								:class="tdClass"
+								role="cell"
 							>
 								<!-- @vue-ignore -->
 								<slot
@@ -358,8 +396,8 @@
 										}}</span>
 									</label>
 								</slot>
-							</td>
-							<td
+							</div>
+							<div
 								v-for="(col, colIndex) in item.cols"
 								:key="col.key"
 								class="bb-table-data__cell"
@@ -371,6 +409,7 @@
 											colIndex === item.cols.length - 1,
 									},
 								]"
+								role="cell"
 							>
 								<!-- @vue-ignore -->
 								<slot
@@ -389,11 +428,12 @@
 									:value="item.value"
 									>{{ col.content }}</slot
 								>
-							</td>
-							<td
+							</div>
+							<div
 								v-if="actions"
 								class="bb-table__cell bb-table__cell--actions"
 								:class="tdClass"
+								role="cell"
 							>
 								<!-- @vue-ignore -->
 								<slot
@@ -408,9 +448,9 @@
 									:toggle-selected="() => toggleSelectedFor(item)"
 									:value="item.value"
 								></slot>
-							</td>
-						</tr>
-						<tr
+							</div>
+						</div>
+						<div
 							v-if="item.expanded"
 							:id="`expanded_${item.valueHash}`"
 							:aria-rowindex="
@@ -420,10 +460,12 @@
 							"
 							class="bb-table-expand__row"
 							:class="{ 'bb-table-expand__row--highlighted': item.highlighted }"
+							role="row"
 						>
-							<td
+							<div
+								:aria-colspan="replacementContentSpan"
 								class="bb-table-expand__cell"
-								:colspan="replacementContentSpan"
+								role="cell"
 							>
 								<!-- @vue-ignore -->
 								<slot
@@ -438,8 +480,8 @@
 									:toggle-selected="() => toggleSelectedFor(item)"
 									:value="item.value"
 								></slot>
-							</td>
-						</tr>
+							</div>
+						</div>
 					</template>
 				</slot>
 
@@ -448,8 +490,11 @@
 				rows alike — and now also when a custom `#loading` slot replaces the
 				skeleton, which used to swallow it. Deliberately NOT inert (unlike
 				the data rows above): `inert` would remove it from the a11y tree and
-				the table would go busy in silence. -->
-				<tr
+				the table would go busy in silence. The live region sits on the
+				inner text, not on the cell: a `status` role ON the cell leaves the
+				row with zero cells in the accessibility tree (a native table
+				repaired that; a div table does not). -->
+				<div
 					v-if="loading"
 					:aria-rowindex="
 						hasProvidedAccessibilityData && !options.length
@@ -457,24 +502,30 @@
 							: undefined
 					"
 					class="bb-table-loading__row bb-table-loading__row--sr-only"
+					role="row"
 				>
-					<td
-						aria-live="polite"
+					<div
+						:aria-colspan="replacementContentSpan"
 						class="bb-table-loading__cell"
-						:colspan="replacementContentSpan"
-						role="status"
+						role="cell"
 					>
-						<span class="bb-table-loading__text sr-only">{{
-							loadingText || t('common.loadingText').value
-						}}</span>
-					</td>
-				</tr>
-			</tbody>
-			<tfoot>
+						<span
+							aria-live="polite"
+							class="bb-table-loading__text sr-only"
+							role="status"
+							>{{ loadingText || t('common.loadingText').value }}</span
+						>
+					</div>
+				</div>
+			</div>
+			<!-- Rendered unconditionally (class parity); the rowgroup role only
+			when there is content, since an empty `rowgroup` fails the required
+			owned-elements check. -->
+			<div class="bb-table__foot" :role="slots.tfoot ? 'rowgroup' : undefined">
 				<!-- @vue-ignore -->
 				<slot :column-count="replacementContentSpan" name="tfoot"></slot>
-			</tfoot>
-		</table>
+			</div>
+		</div>
 		<input v-for="input in hiddenInputs" :key="input.value" v-bind="input" />
 	</component>
 </template>
@@ -515,8 +566,6 @@ import {
 } from '@/utilities/functions/parsePaginationNumber';
 import BaseCheckbox from '../BbBaseCheckbox/BbBaseCheckbox.vue';
 import BaseRadio from '../BbBaseRadio/BbBaseRadio.vue';
-import BbIcon from '../BbIcon/BbIcon.vue';
-import sortIcon from '@/assets/svgs/sort.svg?raw';
 import type { Option as BaseOption } from '@/types/Option';
 import type { Classes } from '@/types/Classes';
 import type { ColumnName } from '@/types/ColumnName';
@@ -524,10 +573,12 @@ import type { PrefixWith } from '@/types/PrefixWith';
 import type {
 	BbTableColumn,
 	BbTableEvents,
+	BbTableHeaderAffixSlotProps,
 	BbTableProps,
 	BbTableSlots,
 	BbTableSortEntry,
 	ExpandControllerProps,
+	HeaderAffixSuffix,
 	ItemKey,
 	ReservedColumnKey,
 	MappedCell,
@@ -540,6 +591,7 @@ import {
 	mergeCellClasses,
 	mergeHeaderClasses,
 	mergeRowClasses,
+	readResolvedTracks,
 } from './utils';
 import { useBbTableContextHost } from '../../composables/useBbTableContext';
 import { useLogger } from '@/composables/useLogger';
@@ -586,7 +638,7 @@ const props = withDefaults(defineProps<InternalProps<T>>(), {
 
 const emit = defineEmits<BbTableEvents>();
 
-defineSlots<
+const slots = defineSlots<
 	BbTableSlots<Item> &
 		Partial<
 			Record<
@@ -620,6 +672,12 @@ defineSlots<
 					toggleSort?: () => void;
 				}) => any
 			>
+		> &
+		Partial<
+			Record<
+				InferredHeaderAffixSlots,
+				(props: BbTableHeaderAffixSlotProps<Item>) => any
+			>
 		>
 >();
 
@@ -646,6 +704,7 @@ type InternalProps<K extends string> = Omit<BbTableProps<Item>, 'columns'> & {
 
 type InferredBodySlots = ColumnName<T>;
 type InferredHeaderSlots = PrefixWith<ColumnName<T>, 'header:'>;
+type InferredHeaderAffixSlots = `${InferredHeaderSlots}:${HeaderAffixSuffix}`;
 
 if (props.multiple && !Array.isArray(props.modelValue)) {
 	const logger = useLogger();
@@ -667,6 +726,15 @@ const RESERVED_COLUMN_KEYS: readonly ReservedColumnKey[] = [
 	'select',
 ];
 
+// Annotated with the exported union for the same reason as above.
+const HEADER_AFFIX_SUFFIXES: readonly HeaderAffixSuffix[] = [
+	'prepend',
+	'append',
+];
+
+const isHeaderAffixSuffix = (base: string): base is HeaderAffixSuffix =>
+	HEADER_AFFIX_SUFFIXES.includes(base as HeaderAffixSuffix);
+
 if (process.env.NODE_ENV !== 'production') {
 	const reserved = props.columns.filter((column) =>
 		RESERVED_COLUMN_KEYS.includes(column.key as ReservedColumnKey)
@@ -679,17 +747,31 @@ if (process.env.NODE_ENV !== 'production') {
 					: 'Selection is controlled by the `selectable` prop.')
 		);
 	}
+
+	// Such a key would make the column's full-replacement slot name
+	// (`header:prepend`) collide with the table-wide affix slot of the same
+	// name, so the table-wide interpretation wins for it.
+	for (const column of props.columns) {
+		const base = columnKeyToSlotName(column.key);
+		if (isHeaderAffixSuffix(base)) {
+			useLogger().warn(
+				`BbTable: column key '${String(column.key)}' normalizes to the slot name '${base}', which collides with the table-wide \`#header:${base}\` slot. That name keeps its table-wide meaning and per-column header slots are unavailable for this column.`
+			);
+		}
+	}
 }
 
 const { t } = useLocale();
 
-const tableRef = ref<HTMLTableElement>();
+/** The grid root (`.bb-table__table`, `role="table"`). */
+const tableRef = ref<HTMLElement>();
 const containerRef = ref<HTMLElement>();
 
 const {
 	id: tableId,
 	parentId,
 	parentNode,
+	node,
 	cssVars,
 	parentVar,
 	setTracks,
@@ -702,6 +784,9 @@ const {
 			: undefined,
 });
 
+/** Id of the caption element the grid root is labelled by. */
+const captionId = computed(() => `${tableId.value}__caption`);
+
 /** The highlight as a 0-or-1 array, which is what the hash index wants. */
 const highlightedValues = computed(() =>
 	isNil(highlighted.value) ? [] : [highlighted.value]
@@ -850,11 +935,11 @@ const inheritColumnWidths = computed(
 );
 
 /**
- * Assigned column widths (frozen, snapped, or inherited) are only authoritative
- * under `table-layout: fixed`; in auto layout they behave like a minimum. So a
- * table that drives widths — explicitly `fixed`, inheriting from a parent, or
- * with a column carrying a `width` or `snap` — uses fixed layout even when
- * `fixed` was not set. (`snap` is a width definition: the parent track range.)
+ * A table that drives its widths — explicitly `fixed`, inheriting from a
+ * parent, or with a column carrying a `width` or `snap` (`snap` is a width
+ * definition: the parent track range). Under grid the tracks are authoritative
+ * in every layout, so this only feeds the `bb-table--fixed` class, kept as a
+ * styling hook for consumers.
  */
 const fixedLayout = computed(
 	() =>
@@ -864,18 +949,16 @@ const fixedLayout = computed(
 		(inheritColumnWidths.value && !!parentId.value)
 );
 
-/**
- * A nested table inheriting its parent's widths must size itself to the sum of
- * those columns rather than stretching to fill its container — otherwise fixed
- * layout would distribute the slack and the columns would no longer match the
- * parent. Tables with the same column count already sum to the full width, so
- * this is a no-op for them and only narrows tables with fewer columns.
- */
 /** True for a nested table that inherits its column widths from a parent. */
 const isInheriting = computed(
 	() => inheritColumnWidths.value && !!parentId.value
 );
 
+/**
+ * A nested table inheriting its parent's widths sizes itself to those tracks
+ * and shares the ancestor scrollport instead of opening its own — see
+ * `.bb-table--inherit-widths` in the CSS.
+ */
 const sizeToColumns = isInheriting;
 
 /** Numbers and bare numeric strings (e.g. `400`, `'400'`) default to px; values
@@ -1021,117 +1104,219 @@ const fillColumnIndex = computed(() => {
 // render, or columns skipped by the first snap) and those right of the last are
 // folded into the edge columns as the structural offset, keeping the table
 // aligned to the parent. `offsetStartValue` becomes the first column's padding.
-const offsetStartValue = computed(() => {
+/*
+ * Nested geometry — the decision tree (plans/BBTABLE-GRID.md § v2.2).
+ *
+ * Every table publishes three kinds of rail: `select` = the START REGION
+ * (everything left of the first content column), `0…N-1` = the pure content
+ * columns, `actions` = the END REGION (unmapped trailing parent columns plus
+ * the parent's actions). An inheriting table reserves both regions and snaps
+ * its content columns 1:1, so alignment holds at any depth by induction.
+ *
+ * Per side, with R = the parent's region on that side:
+ *  1. own structural column on that side → its track is `minmax(R, max-content)`:
+ *     equal to the parent's when the content fits, wider only when it must.
+ *     No padding fold; the region is consumed by the structural track.
+ *  2. no own structural column, R > 0 → R is folded into the edge content
+ *     cell (padding + width, routable to the container via `--offset-*`) and
+ *     published UNFOLDED, with R itself published under the structural key,
+ *     so the next level reserves it too.
+ *  3. no own structural column, R = 0 → nothing to reserve.
+ * Surplus — an own structural cell wider than R (a select the parent lacks,
+ * three buttons against the parent's two) — is reclaimed from the ADJACENT
+ * content column only: its track shrinks by the surplus (a negative fold)
+ * and its content edge moves by that much; every other rail holds. Interior
+ * rails never absorb structure.
+ */
+
+/** The parent's start region: its select cell plus any columns skipped by the first snap. */
+const startRegion = computed(() => {
 	const first = columnIntervals.value[0];
-	// No parent to align to (a root table) means no offset at all — without this
-	// the structural reclaim below would still fold a negative `-ownSelect` in.
 	if (!inheritColumnWidths.value || !parentId.value || !first) return null;
-	// The fill runs from the parent's left edge to this table's first data
-	// column — the parent's select cell, if any, plus any skipped data columns.
-	const head = gridRangeWidth(0, first.start);
-	// This table's own select column sits flush at the left edge and takes its
-	// measured width, so reclaim it from the fill (mirror of the actions side):
-	// the first data column then lines the *next* column up flush with the
-	// parent. When the parent has a select cell it is part of `head`, so only the
-	// surplus over it is reclaimed; when the parent has none the whole select
-	// width comes out of the first column, which shrinks to make room for it.
-	const ownSelect = props.selectable ? structuralFit.select : null;
-	if (!ownSelect) return head;
-	return `calc(${head ?? '0px'} - ${ownSelect})`;
+	return gridRangeWidth(0, first.start);
 });
-const offsetEndValue = computed(() => {
+/**
+ * The parent's end region: unmapped trailing data columns plus its actions
+ * cell. With more columns than the parent there is no trailing region — the
+ * table runs past the parent's edge with content-sized overflow columns.
+ */
+const endRegion = computed(() => {
 	const intervals = columnIntervals.value;
 	const last = intervals[intervals.length - 1];
-	// No parent to align to (a root table) means no offset at all — without this
-	// the structural reclaim below would still fold a negative `-ownActions` in.
 	if (!inheritColumnWidths.value || !parentId.value || !last) return null;
-	// With more columns than the parent, the table runs past the parent's right
-	// edge: there is no trailing parent region to fold, and the last column is a
-	// content-sized overflow column, so there is no end fill.
 	if (overflowsParent.value) return null;
-	// When the last column is the (auto) fill column it already absorbs the whole
-	// trailing region via fixed layout, so folding the offset in too would double
-	// it — and skew its right-aligned content inward.
-	if (fillColumnIndex.value === props.columns.length - 1) return null;
-	// The fill runs from the last data column's end all the way to the parent's
-	// right edge — any unmapped data columns plus the parent's actions cell, if
-	// it has one.
-	const tail = gridRangeWidth(last.end, tableEndCell.value);
-	// This table's own actions column sits flush against that right edge and
-	// takes its measured content width, so reclaim it from the fill: the table
-	// then ends exactly at the parent's edge instead of overflowing by the
-	// actions width. When the parent has an actions cell it is part of `tail`, so
-	// only the surplus over it is effectively reclaimed; when the parent has none
-	// the whole actions width comes out of the data fill. The result may be
-	// negative — the last data column then shrinks to make room for the actions.
-	const ownActions = props.actions ? structuralFit.actions : null;
-	if (!ownActions) return tail;
-	return `calc(${tail ?? '0px'} - ${ownActions})`;
+	return gridRangeWidth(last.end, tableEndCell.value);
 });
+
+/**
+ * This table's OWN last-measured structural track (`select` / `actions`) as
+ * the px the grid resolved it to — `null` before the first measure. Feeds the
+ * surplus reclaim: it is `minmax(R, max-content)`, independent of the data
+ * columns, so folding it converges instead of oscillating.
+ */
+const ownStructuralTrack = (key: 'select' | 'actions') =>
+	node.tracks[key] ?? null;
+
+/**
+ * The edge fold. Without an own structural column it is the whole parent
+ * region (case 2: padding + width on the edge content cell). With one, the
+ * region lives in the structural track and only the SURPLUS over it — the
+ * own cell's resolved width minus R, never positive-padded, ≤ 0 by
+ * construction — is folded, shrinking the adjacent content column.
+ */
+const edgeFold = (
+	region: string | null,
+	own: string | null,
+	hasOwn: boolean
+): string | null => {
+	if (!inheritColumnWidths.value || !parentId.value) return null;
+	if (!hasOwn) return region;
+	if (!own) return null; // not measured yet — nothing to reclaim
+	return `calc(${region ?? '0px'} - ${own})`;
+};
+const offsetStartValue = computed(() =>
+	edgeFold(
+		startRegion.value,
+		props.selectable ? ownStructuralTrack('select') : null,
+		!!props.selectable
+	)
+);
+const offsetEndValue = computed(() =>
+	overflowsParent.value
+		? null
+		: edgeFold(
+				endRegion.value,
+				props.actions ? ownStructuralTrack('actions') : null,
+				!!props.actions
+			)
+);
 const offsetStartActive = computed(() => offsetStartValue.value !== null);
 const offsetEndActive = computed(() => offsetEndValue.value !== null);
 
 /**
- * Measured intrinsic content widths of the structural columns. In a fixed table
- * these pin `select`/`actions` to their content so the remaining space is shared
- * among the data columns; `null` falls back to the regular auto behavior.
+ * A structural track: `max-content` for a root table; for an inheriting table
+ * with a parent region on that side, `minmax(R, max-content)` (case 1). The
+ * chain is only emitted once the parent has published (see
+ * `parentTracksPublished`).
  */
-const structuralFit = reactive<{
-	select: string | null;
-	actions: string | null;
-}>({ select: null, actions: null });
+const structuralTrack = (region: string | null) =>
+	region && parentTracksPublished.value
+		? `minmax(${region}, max-content)`
+		: 'max-content';
+
+/**
+ * Whether the parent has published its tracks yet. Until it has (SSR, the
+ * first client frame — a nested table mounts before its parent measures),
+ * the inherited `var()` chains must NOT be emitted: their `0px` fallbacks
+ * would crush the tracks to literally zero under grid (fixed table layout
+ * used to redistribute; grid honours 0), and a fallbackless `var()` would
+ * invalidate the whole template. Content-sized tracks stand in until the
+ * parent's first measure lands, then the chains take over and this table's
+ * own header-cell observer re-measures.
+ */
+const parentTracksPublished = computed(
+	() => Object.keys(parentNode.value?.tracks ?? {}).length > 0
+);
 
 /**
  * Rendered columns in DOM order, each with the track key it publishes/inherits
- * and the width to apply via `<colgroup>`. A frozen column width wins; otherwise
- * an unfrozen column syncs to the parent's matching track (or `auto` at root).
- * The first/last column additionally absorbs the structural edge offset.
+ * and its `grid-template-columns` entry. The tracks ARE the column API: the
+ * grid root owns the template and every rowgroup/row is a subgrid of it.
+ *
+ * - structural `select` / `actions`: `max-content` — min == max for both
+ *   cells (the actions cell is `white-space: nowrap`, which is what makes that
+ *   track sizing-critical).
+ * - frozen (`width`): the declared length verbatim. A `%` resolves against the
+ *   root box, which under `width: fit-content; min-width: 100%` matches the
+ *   old `<table>` box. When EVERY data column of a root table is frozen there
+ *   is no flexible column to absorb the container's surplus, so each becomes
+ *   `minmax(<width>, <n>fr)` with `n` = its numeric width: the declared width
+ *   is the floor, and any surplus is shared in proportion to the declared
+ *   widths — the table keeps filling its container instead of leaving a
+ *   trailing gap (fixed table layout used to inflate those columns too).
+ * - root unfrozen column: `auto` (min-content floor, max-content ceiling, an
+ *   equal share of the surplus) — the same wrap floor and overflow threshold as
+ *   table auto layout. With `fixed` every unfrozen column is `minmax(0, 1fr)`
+ *   instead: an equal split of the root, exactly as fixed table layout did.
+ * - inheriting fill column: `minmax(0, 1fr)` — absorbs exactly the parent's
+ *   leftover and yields width authority when squeezed, like the old fixed
+ *   layout `auto` fill.
+ * - inheriting overflow column (past the parent's last column): `min-content`,
+ *   what the deleted probe measured.
+ * - inheriting in-range column: the parent's track `var()` chain (see
+ *   `gridRangeWidth`), gated on the parent having published.
+ *
+ * The first/last column additionally absorbs the structural edge offset. Never
+ * emit `repeat()` or line names: the track reader splits a flat px list.
  */
+/**
+ * A column `width` that is a grid sizing keyword rather than a length —
+ * `toLength()` passes these through verbatim. They size the track directly
+ * and must never be wrapped in `calc()`/`minmax()`.
+ */
+const isTrackKeyword = (value: string): boolean =>
+	/^(auto|min-content|max-content|fit-content\(.*\)|-?[\d.]+fr)$/.test(
+		value.trim()
+	);
+
 const columnTracks = computed(() => {
-	const sync = (key: string) =>
-		inheritColumnWidths.value ? parentVar(key) : 'auto';
-	// In fixed layout `auto` columns share width equally, so pin the structural
-	// columns to their measured content width and let the data columns share.
-	const structural = (key: 'select' | 'actions') =>
-		fixedLayout.value && structuralFit[key]
-			? (structuralFit[key] as string)
-			: sync(key);
 	const tracks: Array<{ key: string; width: string }> = [];
 
 	if (props.selectable) {
-		tracks.push({ key: 'select', width: structural('select') });
+		tracks.push({ key: 'select', width: structuralTrack(startRegion.value) });
 	}
 
 	const lastIndex = props.columns.length - 1;
+	// A root table whose data columns are ALL frozen (see the doc comment):
+	// the frozen lengths become proportional floors instead of hard sizes.
+	const allFrozen =
+		!isInheriting.value &&
+		props.columns.length > 0 &&
+		props.columns.every((column) => column.width != null);
 	props.columns.forEach((column, index) => {
 		const key = String(index);
 		const frozen = column.width != null ? toLength(column.width) : null;
 		const interval = columnIntervals.value[index];
 
-		// The fill column is left `auto` so fixed layout (the inheriting table has
-		// a definite `width: 100%`) hands it the leftover space — its own inherited
-		// track plus the folded edge region plus any deficit. Skipped when the
-		// table overflows: there is no leftover then, and it must content-size.
-		if (index === fillColumnIndex.value && !overflowsParent.value) {
-			tracks.push({ key, width: 'auto' });
-			return;
-		}
-
-		let span: string | null;
-		if (frozen != null) {
+		// `span` is a CSS *length* expression (frozen width or inherited chain)
+		// when the offset must be folded into it arithmetically; a `keyword`
+		// track sizes to the cell's content, which already includes the padding
+		// the offset adds, so it needs no folding.
+		let span: string | null = null;
+		let keyword: string | null = null;
+		if (frozen != null && isTrackKeyword(frozen)) {
+			// A keyword `width` (`auto`, `min-content`, `1fr`, …) is a track, not a
+			// length: it can neither be folded into the offset `calc()` (invalid
+			// at computed-value time — and an invalid template drops EVERY track)
+			// nor serve as a `minmax()` floor with an `fr` share.
+			keyword = frozen;
+		} else if (frozen != null && allFrozen) {
+			// `parseFloat` reads the leading number of any unit (`120px` → 120,
+			// `25%` → 25); a non-numeric length still gets an equal share.
+			const share = parseFloat(frozen) || 1;
+			keyword = `minmax(${frozen}, ${share}fr)`;
+		} else if (frozen != null) {
 			span = frozen;
 		} else if (isFlexColumn(index)) {
-			// Root table auto column: a precise share of the leftover space from the
-			// proportional probe rather than fixed layout's equal split. `auto` is
-			// the fallback before the probe runs.
-			span = (fixedLayout.value && probeColWidths.value[index]) || null;
+			keyword = props.fixed ? 'minmax(0, 1fr)' : 'auto';
+		} else if (!parentTracksPublished.value) {
+			// Inheriting, but the parent has not published yet (SSR, first client
+			// frame): content-size on `max-content`. Checked BEFORE the overflow
+			// test, which is vacuously true while the parent's geometry is unknown.
+			keyword = 'max-content';
 		} else if (isOverflowColumn(interval)) {
 			// Inheriting table, past the parent's last column: no track to snap to,
 			// so size to its own content and let the table overflow (and scroll).
-			span = columnMinWidths.value[index] ?? null;
+			keyword = 'min-content';
 		} else {
 			// In range: snap to the parent's matching column.
 			span = gridRangeWidth(interval.start, interval.end);
+			if (span === null) keyword = 'auto';
+		}
+
+		if (keyword !== null) {
+			tracks.push({ key, width: keyword });
+			return;
 		}
 
 		const offsets: string[] = [];
@@ -1142,22 +1327,35 @@ const columnTracks = computed(() => {
 			offsets.push('var(--offset-internal-end, 0px)');
 		}
 
-		// When folding an offset, use a calc-safe length base (no `auto`) so the
-		// column width = offset(s) + the column's own span.
-		const width = offsets.length
-			? `calc(${[...offsets, span ?? '0px'].join(' + ')})`
-			: (span ?? 'auto');
+		// Fold the offset(s) in so the track = offset(s) + the column's own span.
+		const folded = offsets.length
+			? `calc(${[...offsets, span].join(' + ')})`
+			: (span as string);
+
+		// The fill column: the last unfrozen/unsnapped column of an inheriting
+		// table grows to re-align everything after a narrower frozen sibling. Its
+		// rail is the floor — it never shrinks below it (structural surplus is
+		// not its job any more; see the decision tree above).
+		const width =
+			index === fillColumnIndex.value && !overflowsParent.value
+				? `minmax(${folded}, 1fr)`
+				: folded;
 
 		tracks.push({ key, width });
 	});
 
 	if (props.actions) {
-		tracks.push({ key: 'actions', width: structural('actions') });
+		tracks.push({ key: 'actions', width: structuralTrack(endRegion.value) });
 	}
 
 	return tracks;
 });
 
+/** The grid root's `grid-template-columns` value. */
+const gridTemplate = computed(() =>
+	columnTracks.value.map((track) => track.width).join(' ')
+);
+
 /**
  * Standalone edge-offset custom properties consumed by the first/last cell
  * padding and the first/last column width. Set only when an offset is active;
@@ -1174,460 +1372,124 @@ const structuralOffset = computed<Record<string, string>>(() => {
 	return style;
 });
 
-const containerStyle = computed(() => {
-	const vars: Record<string, string> = {
-		...cssVars.value,
-		...structuralOffset.value,
-	};
-
-	if (naturalTotalWidth.value) {
-		vars['--natural-width'] = naturalTotalWidth.value;
-	}
-
-	if (fillValue.value > 0) {
-		vars['--fill'] = `${fillValue.value}px`;
-	}
-
-	return vars;
-});
-
-/** Reads the header cells in render order: [select?, ...data, actions?]. */
-const headerCells = () =>
-	Array.from(
-		tableRef.value?.querySelectorAll<HTMLElement>(
-			':scope > thead > tr.bb-table-header-row > th'
-		) ?? []
-	);
-
-/** Measures the rendered columns and publishes them as this table's tracks. */
-const measureTracks = () => {
-	const keys = columnTracks.value.map((track) => track.key);
-	const tracks: Record<string, string> = {};
-	headerCells().forEach((cell, index) => {
-		const key = keys[index];
-		if (key != null) tracks[key] = `${cell.getBoundingClientRect().width}px`;
-	});
-	setTracks(tracks);
-};
+const containerStyle = computed(() => ({
+	...cssVars.value,
+	...structuralOffset.value,
+}));
 
 /**
- * Measures the intrinsic content width of the structural columns across header
- * and body. Fixed layout sizes columns from the header row only, so the body is
- * required here: the actions header is `sr-only`, while the real control lives
- * in the body. The measured child width is independent of the column width, so
- * pinning the column to it converges instead of oscillating.
+ * The cells whose border boxes ARE this table's tracks: the header row's
+ * cells, which are stretched subgrid items. When a `#thead` slot replaces the
+ * header with fewer cells than tracks, the first row (head or body) with at
+ * least one child per track stands in — so a short custom header on an empty
+ * table publishes nothing until it has rows (see `observeColumns`), and the
+ * `mappedItems` watch re-arms the observer when rows arrive or are re-keyed.
+ * Scoped with `:scope >` so a nested table's rows are never picked up.
  */
-const measureStructuralFit = () => {
-	const table = tableRef.value;
-	if (!table) return;
-
-	// Non-replaced block-level boxes stretch to their container's width in block
-	// formatting; everything else (inline-*, floats, tables) shrink-wraps.
-	const STRETCHING = ['block', 'flex', 'grid', 'flow-root', 'list-item'];
-	// Widgets and replaced elements size to their content regardless of display,
-	// so their rendered width is always intrinsic.
-	const SHRINK_WRAPPING_TAGS = [
-		'BUTTON',
-		'INPUT',
-		'SELECT',
-		'TEXTAREA',
-		'IMG',
-		'svg',
-		'VIDEO',
-		'CANVAS',
-	];
-
-	/**
-	 * Intrinsic occupied width of an element's in-flow contents: the sum of each
-	 * child's own intrinsic width plus horizontal margins and any flex/grid
-	 * column gaps — an actions cell holds several side-by-side controls and the
-	 * column must fit them all. Crucially this is *not* their shared extent: the
-	 * extent depends on how the container spreads them across its width, which
-	 * feeds the column width back into its own measurement and runs away into
-	 * the thousands.
-	 *
-	 * A shrink-wrapping child's rendered width does not depend on the cell, so
-	 * it is used as-is. A *stretching* child's rendered width IS its container's
-	 * width — a consumer slotting `<div class="flex">…</div>` would otherwise
-	 * ratchet the column wider on every container resize — so recurse into its
-	 * contents instead. A child stretches only in block formatting: flex/grid
-	 * items size to their content on the main axis, so inside a flex/grid
-	 * container every child's rendered width is trusted. Out-of-flow children
-	 * (e.g. an `sr-only` label parked far off-screen, a popover) are skipped so
-	 * they cannot inflate the result.
-	 */
-	const contentsWidth = (el: HTMLElement): number => {
-		const style = getComputedStyle(el);
-		const itemsShrinkWrap =
-			style.display.includes('flex') || style.display.includes('grid');
-		let total = 0;
-		let count = 0;
-		el.querySelectorAll<HTMLElement>(':scope > *').forEach((child) => {
-			const childStyle = getComputedStyle(child);
-			if (childStyle.position === 'absolute' || childStyle.position === 'fixed')
-				return;
-			const margin =
-				parseFloat(childStyle.marginLeft) + parseFloat(childStyle.marginRight);
-			const stretches =
-				!itemsShrinkWrap &&
-				!SHRINK_WRAPPING_TAGS.includes(child.tagName) &&
-				childStyle.cssFloat === 'none' &&
-				STRETCHING.includes(childStyle.display);
-			const own = stretches
-				? contentsWidth(child) +
-					parseFloat(childStyle.paddingLeft) +
-					parseFloat(childStyle.paddingRight) +
-					parseFloat(childStyle.borderLeftWidth) +
-					parseFloat(childStyle.borderRightWidth)
-				: child.getBoundingClientRect().width;
-			total += own + (margin || 0);
-			count += 1;
-		});
-		if (count === 0) {
-			// Text-only content: measure the laid-out text run itself.
-			const range = document.createRange();
-			range.selectNodeContents(el);
-			return range.getBoundingClientRect().width;
-		}
-		if (count > 1) {
-			const gap = parseFloat(style.columnGap);
-			if (gap) total += gap * (count - 1);
-		}
-		return total;
-	};
-
-	const fit = (selector: string) => {
-		let max = 0;
-		table.querySelectorAll<HTMLElement>(selector).forEach((cell) => {
-			const style = getComputedStyle(cell);
-			const padding =
-				parseFloat(style.paddingLeft) + parseFloat(style.paddingRight);
-			max = Math.max(max, contentsWidth(cell) + padding);
-		});
-		return max > 0 ? `${Math.ceil(max)}px` : null;
-	};
-
-	// Scoped to this table's own header/body rows: an unscoped descendant query
-	// would also match the structural cells of a nested table living in an expand
-	// row, letting a child's actions/select width hijack this table's column.
-	structuralFit.select = props.selectable
-		? fit(
-				':scope > thead > tr > th.bb-table-header--select, :scope > tbody > tr > td.bb-table-data__cell--select'
-			)
-		: null;
-	structuralFit.actions = props.actions
-		? fit(
-				':scope > thead > tr > th.bb-table-header--actions, :scope > tbody > tr > td.bb-table__cell--actions'
+const trackCells = (): HTMLElement[] => {
+	const root = tableRef.value;
+	const trackCount = columnTracks.value.length;
+	if (!root || !trackCount) return [];
+	const headerRow = root.querySelector<HTMLElement>(
+		':scope > .bb-table__head > .bb-table-header-row'
+	);
+	// The default header row is the first candidate, never the only one: a
+	// custom `#thead` may reuse its class with fewer cells than tracks.
+	const candidates = [
+		...(headerRow ? [headerRow] : []),
+		...Array.from(
+			root.querySelectorAll<HTMLElement>(
+				':scope > .bb-table__head > [role="row"], :scope > .bb-table__body > [role="row"]'
 			)
-		: null;
+		),
+	];
+	const row = candidates.find((r) => r.children.length >= trackCount);
+	return row ? (Array.from(row.children) as HTMLElement[]) : [];
 };
 
-const measure = () => {
-	measureStructuralFit();
-	measureTracks();
-};
+/** The joined px list last published, for the equality guard. */
+let publishedTracks = '';
 
 /**
- * Proportional `<col>` widths derived from an auto-layout probe, one entry per
- * data column (`null` for frozen columns — they keep their declared width).
+ * Measures the resolved columns and publishes them as this table's tracks.
+ * ONE read — `getComputedStyle(root).gridTemplateColumns` — yields the used px
+ * of every track type through both subgrid levels, synchronously and to the
+ * subpixel. The px substrings are published verbatim (no float round-trip:
+ * nested alignment is asserted at 1.5px and depends on it), zipped
+ * positionally with `columnTracks`.
  *
- * For each auto column the formula is:
- *   width = max(minimum, available × (minimum / minimumTotal))
- *
- * where `minimum` is the column's `min-content` width (what it shrinks to in a
- * very narrow container, i.e. the floor below which content would be clipped),
- * `available` = containerWidth − frozenColumnWidths − structuralColumnWidths
- * and `minimumTotal` = sum of the auto columns' minimums.
- *
- * So when the container has room (`available ≥ minimumTotal`) the slack is shared
- * out proportionally to each column's minimum, scaling them up together; when it
- * does not, every column drops to its minimum and the table-level `min-width`
- * lets it overflow (the container scrolls) rather than squashing content further.
- *
- * Re-measured after any DOM mutation (debounced 200 ms) and after any container
- * resize (via a dedicated ResizeObserver on the container element).
+ * Guarded twice: a non-px token means the table is hidden (the specified
+ * template comes back, and the observer fires on hide) — keep the last good
+ * vars, the observer fires again on re-show; and `setTracks` is skipped on an
+ * unchanged list — loop safety, since publishing re-renders the container
+ * style, which is observed by the very header cells that trigger this.
  */
-const probeColWidths = ref<Array<string | null>>([]);
-
-/**
- * Each unfrozen column's measured `min-content` width (`null` for frozen). Used
- * to content-size the overflow columns of an inheriting table — those past the
- * parent's last column, with no track to snap to.
- */
-const columnMinWidths = ref<Array<string | null>>([]);
-
-/**
- * Leftover px the inheriting fill column adds so the table reaches its parent's
- * width. Published as `--fill`; `0` when the table already fills or
- * overflows. Derived self-correctingly from the live total (see the probe).
- */
-const fillValue = ref(0);
-
-/**
- * Total minimum width of the table (all columns at their `min-content`, plus the
- * structural columns). Published as `--natural-width` and used as
- * `min-width` on the `<table>` so the table scrolls horizontally only once the
- * container is narrower than this true minimum.
- */
-const naturalTotalWidth = ref<string | null>(null);
-
-const runNaturalWidthProbe = () => {
-	const container = containerRef.value;
-	if (!container || !fixedLayout.value) return;
-	// Runs for a frozen-column table (to share space), or any inheriting table
-	// (to content-size overflow columns and drive the fill column's slack).
-	if (
-		!props.columns.some((col) => col.width != null) &&
-		!overflowsParent.value &&
-		fillColumnIndex.value < 0
-	)
-		return;
-
-	const containerWidth = container.offsetWidth;
-	const dataOffset = props.selectable ? 1 : 0;
-
-	// ── Real-table measurements ────────────────────────────────────────────
-	// Structural column widths come from measureStructuralFit (already run).
-	const selectWidth = structuralFit.select
-		? parseFloat(structuralFit.select)
-		: 0;
-	const actionsWidth = structuralFit.actions
-		? parseFloat(structuralFit.actions)
-		: 0;
-
-	// Live rendered widths from the fixed-layout table. `frozenTotal` (declared
-	// widths) feeds the stable min-width floor; `nonFlexTotal` (frozen + inherited)
-	// is what the flex columns share the remainder of. The inherited part is only
-	// used for that `available` figure — never fed back into min-width, since those
-	// widths stretch with the table and would otherwise lock min-width above
-	// max-content and force a spurious uniform stretch on every column.
-	const realThs = headerCells();
-	let frozenTotal = 0;
-	let nonFlexTotal = 0;
-	props.columns.forEach((col, i) => {
-		const width = realThs[dataOffset + i]?.getBoundingClientRect().width ?? 0;
-		if (col.width != null) frozenTotal += width;
-		if (!isFlexColumn(i)) nonFlexTotal += width;
-	});
-
-	// ── Offscreen probe for the auto columns' minimum (min-content) widths ──
-	// The clone's inner table is forced to `width: min-content` and the auto <col>
-	// hints are stripped so each <th> reports the narrowest width it can take
-	// before content would be clipped, independent of the container size or
-	// previous probe cycles.
-	const probe = document.createElement('div');
-	probe.style.cssText = [
-		'position:absolute',
-		'top:-9999px',
-		'left:-9999px',
-		'visibility:hidden',
-		'pointer-events:none',
-		`width:${containerWidth}px`,
-		`height:${container.offsetHeight}px`,
-		'overflow:visible',
-	].join(';');
-
-	const clone = container.cloneNode(true) as HTMLElement;
-	clone.classList.remove('bb-table--fixed');
-
-	// Expand rows are full-width (colspan) and hold nested tables; under the
-	// auto-layout probe their content would back-pressure this table's own
-	// columns, so drop them and measure this table's columns in isolation.
-	clone
-		.querySelectorAll('.bb-table-expand__row')
-		.forEach((row) => row.remove());
-
-	// Auto <col> hints are cleared so a previous cycle's computed width cannot
-	// act as a minimum and inflate the measurement; frozen hints are left intact
-	// since their declared width is a genuine floor for that column.
-	const probeColEls = Array.from(clone.querySelectorAll<HTMLElement>('col'));
-	props.columns.forEach((col, i) => {
-		if (col.width == null) {
-			const probeCol = probeColEls[dataOffset + i];
-			if (probeCol) probeCol.style.width = '';
-		}
+const measureTracks = () => {
+	const root = tableRef.value;
+	if (!root) return;
+	const resolved = readResolvedTracks(root);
+	if (!resolved) return;
+	const keys = columnTracks.value.map((track) => track.key);
+	if (resolved.length !== keys.length) return;
+	const joined = resolved.join(' ');
+	if (joined === publishedTracks) return;
+	publishedTracks = joined;
+	const tracks: Record<string, string> = {};
+	keys.forEach((key, index) => {
+		tracks[key] = resolved[index];
 	});
-
-	const innerTable = clone.querySelector<HTMLElement>('table');
-	if (innerTable) {
-		innerTable.style.width = 'min-content';
-		innerTable.style.minWidth = '0';
+	// Publish the CONTRACT, not the raw template (decision tree, case 2): an
+	// edge content column that folded a parent region into its width is
+	// published unfolded — the pure content rail — and the region goes out
+	// under the structural key even though no cell renders it, so the next
+	// level reserves it exactly as this one did.
+	const lastKey = String(props.columns.length - 1);
+	const startFold = offsetStartValue.value;
+	const endFold = offsetEndValue.value;
+	if (startFold && tracks['0']) {
+		tracks['0'] = `calc(${tracks['0']} - (${startFold}))`;
+		if (!props.selectable && startRegion.value)
+			tracks.select = startRegion.value;
 	}
-
-	probe.appendChild(clone);
-	document.body.appendChild(probe);
-
-	const headerRow = probe.querySelector<HTMLElement>(
-		'table thead tr.bb-table-header-row'
-	);
-	const ths = headerRow
-		? Array.from(headerRow.querySelectorAll<HTMLElement>(':scope > th'))
-		: [];
-
-	// Min-content of every unfrozen column (0 for frozen). Independent of the live
-	// table's width, so it is a stable basis for both the flex share and the
-	// min-width floor — unlike the rendered inherited widths.
-	const minContents = props.columns.map((col, i) => {
-		if (col.width != null) return 0;
-		const th = ths[dataOffset + i];
-		return th ? th.getBoundingClientRect().width : 0;
-	});
-
-	document.body.removeChild(probe);
-
-	// ── Proportional <col> widths ──────────────────────────────────────────
-	// Only the flex columns share `available`; the inherited columns are already
-	// laid out and excluded via `nonFlexTotal`.
-	const flexMinTotal = props.columns.reduce(
-		(s, _, i) => s + (isFlexColumn(i) ? minContents[i] : 0),
-		0
-	);
-	const available = containerWidth - nonFlexTotal - selectWidth - actionsWidth;
-
-	// Share the available space proportionally to each flex column's minimum, but
-	// never drop below that minimum — when space runs out the table overflows
-	// (and the container scrolls) instead of clipping content.
-	//
-	// Widths are kept sub-pixel (not rounded up): the raw shares sum to exactly
-	// `available`, whereas ceiling each column would over-allocate by up to a
-	// pixel apiece and, under `table-layout: fixed`, push the table a few px past
-	// the container and trip the horizontal scrollbar. `toFixed` only trims the
-	// float tail, well below the 1px a scrollbar needs.
-	const px = (n: number) => `${Number(n.toFixed(3))}px`;
-	probeColWidths.value = props.columns.map((_, i) => {
-		if (!isFlexColumn(i)) return null;
-		const minimum = minContents[i];
-		if (flexMinTotal <= 0) return px(minimum);
-		const share = available > 0 ? available * (minimum / flexMinTotal) : 0;
-		return px(Math.max(minimum, share));
-	});
-
-	// Min-content per unfrozen column, for content-sizing an inheriting table's
-	// overflow columns (no parent track to snap to).
-	columnMinWidths.value = minContents.map((w) => (w > 0 ? px(w) : null));
-
-	// Leftover the inheriting fill column must absorb to reach the parent's width.
-	// `parentTotal` is the parent table's full width (the expand cell this table
-	// sits in); the container itself shrink-wraps to the table, so it can't be the
-	// reference. Self-correcting: the live total already includes last cycle's
-	// fill, so adding it back recovers the intrinsic total and the result is the
-	// same once the table fills (0 when it already fills or overflows).
-	if (fillColumnIndex.value >= 0) {
-		const parentTotal = Object.values(parentNode.value?.tracks ?? {}).reduce(
-			(s, w) => s + (parseFloat(w) || 0),
-			0
-		);
-		const liveTotal = realThs.reduce(
-			(s, th) => s + th.getBoundingClientRect().width,
-			0
-		);
-		fillValue.value = Math.max(0, parentTotal - liveTotal + fillValue.value);
-	} else {
-		fillValue.value = 0;
+	if (endFold && tracks[lastKey]) {
+		tracks[lastKey] = `calc(${tracks[lastKey]} - (${endFold}))`;
+		if (!props.actions && endRegion.value) tracks.actions = endRegion.value;
+	}
+	setTracks(tracks);
+	// Sticky column offsets are prefix sums of these tracks: keep them current.
+	if (props.fixedColumns?.length) {
+		applyFixedTableColumns(root, props.fixedColumns);
 	}
-
-	// Table min-width = frozen (declared) widths + every unfrozen column's
-	// min-content + structural. Built only from values that do not depend on the
-	// table's own width, so it can never exceed max-content and force a stretch.
-	const minContentTotal = minContents.reduce((s, w) => s + w, 0);
-	const naturalTotal =
-		frozenTotal + minContentTotal + selectWidth + actionsWidth;
-	naturalTotalWidth.value =
-		naturalTotal > 0 ? `${Math.ceil(naturalTotal)}px` : null;
 };
 
-let naturalWidthDebounceTimer: ReturnType<typeof setTimeout> | null = null;
-let mutationObserver: MutationObserver | undefined;
-
 /**
- * True while a container resize is waiting on the debounced probe to reflow
- * the columns. A shrink leaves the old (wider) column widths in place until
- * the probe lands, so `overflow-x: auto` would flash a horizontal scrollbar
- * for that window. While measuring, overflow is clipped instead — but only
- * when the table wasn't already overflowing when the resize hit (an existing
- * scrollbar stays; hiding it would jolt a table the user may be scrolling).
+ * The single observer: the per-header-cell ResizeObserver. A header cell is a
+ * stretched subgrid item whose border box is the track, so it is the complete
+ * signal for every cause of a track change — including content-driven
+ * redistribution at a constant root width, which a root observer cannot see.
+ * Measuring inside the callback is post-layout, pre-paint: the republished
+ * vars restyle nested children in the same frame.
  */
-const measuring = ref(false);
-
-/** Whether the table genuinely overflowed its container at the last settle. */
-let hadOverflow = false;
-
-const updateOverflowState = () => {
-	const container = containerRef.value;
-	const table = tableRef.value;
-	hadOverflow =
-		!!container &&
-		!!table &&
-		table.getBoundingClientRect().width > container.clientWidth + 1;
-};
-
-/** Invalidates the cached natural width and schedules a fresh probe. */
-const scheduleNaturalWidthProbe = () => {
-	if (naturalWidthDebounceTimer !== null)
-		clearTimeout(naturalWidthDebounceTimer);
-	naturalWidthDebounceTimer = setTimeout(() => {
-		naturalWidthDebounceTimer = null;
-		runNaturalWidthProbe();
-		// Lift the overflow clip only after the new column widths have rendered,
-		// then re-read the settled overflow state (a scrollbar reappears here
-		// only if the table truly cannot fit the new container width).
-		nextTick(() => {
-			measuring.value = false;
-			updateOverflowState();
-		});
-	}, 200);
-};
-
 let resizeObserver: ResizeObserver | undefined;
-/** Observes the container element specifically for size changes so the
- *  proportional <col> widths are recomputed whenever the container grows or
- *  shrinks — separately from the header-cell observer that drives measureTracks. */
-let containerResizeObserver: ResizeObserver | undefined;
 
 const observeColumns = () => {
 	if (!resizeObserver) return;
 	resizeObserver.disconnect();
-	headerCells().forEach((cell) => resizeObserver?.observe(cell));
-	measure();
+	const cells = trackCells();
+	cells.forEach((cell) => resizeObserver?.observe(cell));
+	// No observable cells (a short custom `#thead` over an empty table): publish
+	// nothing rather than a snapshot nothing would ever refresh — an inheriting
+	// child then stays on its content-sized gate until rows arrive.
+	if (cells.length) measureTracks();
 };
 
 onMounted(() => {
-	resizeObserver = new ResizeObserver(() => measure());
+	resizeObserver = new ResizeObserver(measureTracks);
 	observeColumns();
-
-	// Initial probe runs after the first render so all cells have content.
-	nextTick(runNaturalWidthProbe);
-
-	// Invalidate the cache whenever rows or cell content change.
-	if (tableRef.value) {
-		mutationObserver = new MutationObserver(scheduleNaturalWidthProbe);
-		mutationObserver.observe(tableRef.value, {
-			childList: true,
-			subtree: true,
-			characterData: true,
-		});
-	}
-
-	// Re-probe whenever the container itself is resized so that proportional
-	// <col> widths stay accurate as the available space changes. Runs before
-	// paint, so clipping overflow here means the stale-width scrollbar never
-	// shows. The hadOverflow guard also breaks the feedback loop of the clip
-	// itself resizing the content box.
-	if (containerRef.value) {
-		containerResizeObserver = new ResizeObserver(() => {
-			if (!hadOverflow) measuring.value = true;
-			scheduleNaturalWidthProbe();
-		});
-		containerResizeObserver.observe(containerRef.value);
-	}
 });
 
 onBeforeUnmount(() => {
 	resizeObserver?.disconnect();
-	containerResizeObserver?.disconnect();
-	mutationObserver?.disconnect();
-	if (naturalWidthDebounceTimer !== null)
-		clearTimeout(naturalWidthDebounceTimer);
 });
 
 watch(columnTracks, () => nextTick(observeColumns), { flush: 'post' });
@@ -1658,8 +1520,8 @@ const loading = computed(() => props.loading || innerLoading.value);
  * out: a refetch is about to replace the rows, so editing, selecting or sorting
  * them races the incoming data.
  *
- * Applied to `<thead>` and to each row rather than to `<table>` or `<tbody>` on
- * purpose — `inert` removes descendants from the a11y tree, and the loading
+ * Applied to the header rowgroup and to each row rather than to the table or
+ * the body rowgroup on purpose — `inert` removes descendants from the a11y tree, and the loading
  * announcement lives in the same body as the rows, so a broader target would
  * silence it and the table would go busy in complete silence.
  */
@@ -1688,7 +1550,6 @@ const containerClass = computed(() => ({
 	'bb-table--loading': loading.value,
 	'bb-table--empty': !options.value.length,
 	'bb-table--selectable': !!props.selectable,
-	'bb-table--measuring': measuring.value,
 	'scrollbar-border': true,
 }));
 
@@ -1856,7 +1717,14 @@ const mapColumnToCell = (
 const mappedHeaders = computed(() =>
 	props.columns.map((column: BbTableColumn<Item>): MappedHeader => {
 		const align = column.align ?? 'left';
-		const slotName = `header:${slotNamesByKey.value[column.key]}`;
+		const base = slotNamesByKey.value[column.key];
+		// A key normalizing to an affix suffix collides with the table-wide
+		// `header:prepend/append` slots, and the table-wide reading wins (dev
+		// builds warn) — so route this column's own slot to a name no template
+		// can declare (the space guarantees it) and let the fallback render.
+		const slotName = isHeaderAffixSuffix(base)
+			? `header:${base} (shadowed)`
+			: `header:${base}`;
 		// The live sort model wins over the static `sorted` column flag.
 		const sortOrder = sortOrderFor(column.key);
 		const sorted = sortOrder ?? column.sorted;
@@ -1883,6 +1751,39 @@ const mappedHeaders = computed(() =>
 	})
 );
 
+/**
+ * Resolves a header cell's prepend/append content: the column's own
+ * `header:<key>:prepend/append` slot wins over the table-wide
+ * `header:prepend/append` one — they never stack (BbDropdown's item rule).
+ * A column whose key shadows an affix suffix only gets the table-wide slots.
+ */
+const headerAffixFor = (key: string, suffix: HeaderAffixSuffix) => {
+	const base = slotNamesByKey.value[key];
+	return (
+		(isHeaderAffixSuffix(base)
+			? undefined
+			: slots[`header:${base}:${suffix}`]) ?? slots[`header:${suffix}`]
+	);
+};
+
+/**
+ * Affix slots receive the `header:<key>` payload plus the column key so a
+ * table-wide template can branch per column. Named `columnKey`, not `key`:
+ * the payload is v-bound onto a rendered slot function, where `key` would be
+ * consumed as the vnode key instead of reaching the slot.
+ */
+const headerAffixScope = (
+	header: MappedHeader
+): BbTableHeaderAffixSlotProps<Item> => ({
+	classes: header.classes,
+	columnKey: header.key,
+	items: internalItems.value,
+	label: header.label,
+	sortable: header.sortable,
+	sortOrder: header.sortOrder,
+	toggleSort: () => toggleSortFor(header.key),
+});
+
 /**
  * Resolves the CURRENT option for a row at event time. Row handlers are built
  * in the selection-free formatter projection below, so they cannot capture a
@@ -1924,17 +1825,17 @@ const projectedItems = computed(() =>
 				const item = liveOptionFor(index, base.valueHash);
 				if (!item) return;
 				onRowClickHighlight(event, item);
-				emit('click:row', event, item, !!item.selected);
+				emit('click:row', event, item.item);
 			},
 			onRowContextMenu: (event: MouseEvent) => {
 				const item = liveOptionFor(index, base.valueHash);
 				if (!item) return;
-				emit('contextmenu:row', event, item, !!item.selected);
+				emit('contextmenu:row', event, item.item);
 			},
 			onRowDblClick: (event: MouseEvent) => {
 				const item = liveOptionFor(index, base.valueHash);
 				if (!item) return;
-				emit('dblclick:row', event, item, !!item.selected);
+				emit('dblclick:row', event, item.item);
 			},
 			item: base.item,
 			text: base.text,
@@ -2005,7 +1906,7 @@ watch(
 /** This table's own data rows (excludes expand rows and nested tables). */
 const dataRows = () =>
 	tableRef.value?.querySelectorAll<HTMLElement>(
-		':scope > tbody > tr.bb-table-data__row'
+		':scope > .bb-table__body > .bb-table-data__row'
 	);
 
 const focusRow = (index: number) => {
@@ -2228,6 +2129,10 @@ watch(
 		if (tableRef.value && props.fixedColumns?.length) {
 			applyFixedTableColumns(tableRef.value, props.fixedColumns);
 		}
+		// With a custom `#thead` the observed cells may live on a data row that
+		// just arrived, or was re-keyed and replaced: re-arm the observer. The
+		// default header row is stable, so this is skipped for it.
+		if (slots.thead) nextTick(observeColumns);
 	},
 	{ flush: 'post' }
 );
@@ -2283,6 +2188,14 @@ export type ItemKey<Item = any> = NestedPaths<Item> | (string & {});
  */
 export type ReservedColumnKey = 'actions' | 'select';
 
+/**
+ * Suffixes of the header affix slots (`header:prepend` / `header:append` and
+ * their per-column `header:<key>:prepend/append` variants). A column key that
+ * normalizes to one of these shadows the table-wide slot name; the table-wide
+ * interpretation wins and dev builds warn.
+ */
+export type HeaderAffixSuffix = 'prepend' | 'append';
+
 /**
  * Skeleton placeholder style for the loading state.
  * Matches the expected content type for a better loading experience.
@@ -2353,19 +2266,19 @@ export type BbTableColumn<Item = any> = BaseColumn<Item> & {
 	sorted?: 'asc' | 'desc';
 
 	/**
-	 * Classes this column contributes to the whole row's `<tr>`. Every column's
+	 * Classes this column contributes to the whole row element. Every column's
 	 * `rowClass` is accumulated with the table-level `rowClass` prop and applied
 	 * together. Can also be a function of the cell's content for dynamic values.
 	 */
 	rowClass?: ColumnClasses<Item>;
 
 	/**
-	 * Defines the classes to be passed to the `<td>` elements. Can also be a function for dynamic values.
+	 * Defines the classes to be passed to this column's data cells. Can also be a function for dynamic values.
 	 */
 	tdClass?: ColumnClasses<Item>;
 
 	/**
-	 * Defines the classes to be passed to the `<th>`.
+	 * Defines the classes to be passed to this column's header cell.
 	 */
 	thClass?: Classes;
 
@@ -2427,7 +2340,7 @@ export type BbTableProps<Item = any> = {
 	/**
 	 * Opt a nested table into inheriting its column widths from an ancestor
 	 * table's matching tracks (accounting for `select`/`actions` columns). This
-	 * also forces `table-layout: fixed`, so it is **off by default** — a nested
+	 * also makes the parent's tracks authoritative, so it is **off by default** — a nested
 	 * table renders independently unless you ask for alignment.
 	 * - `false` (the default): do not inherit; size independently.
 	 * - `true`: inherit from the nearest ancestor table.
@@ -2508,7 +2421,8 @@ export type BbTableProps<Item = any> = {
 	displayCaption?: boolean;
 
 	/**
-	 * Defines the table layout as fixed
+	 * Splits the width equally among the columns that declare no `width`
+	 * (each undeclared column becomes a `minmax(0, 1fr)` track)
 	 * making each column take up the same amount of space.
 	 */
 	fixed?: boolean;
@@ -2654,13 +2568,13 @@ export type BbTableProps<Item = any> = {
 	readonly?: boolean;
 
 	/**
-	 * Defines the classes to be passed to each data `<tr>`. Can also be a
+	 * Defines the classes to be passed to each data row. Can also be a
 	 * function of the row's item for dynamic values.
 	 */
 	rowClass?: RowClasses<Item>;
 
 	/**
-	 * Defines the classes to be passed to the header `<tr>`.
+	 * Defines the classes to be passed to the header row.
 	 */
 	headerRowClass?: Classes;
 
@@ -2710,12 +2624,12 @@ export type BbTableProps<Item = any> = {
 	selectText?: string;
 
 	/**
-	 * Defines the classes to be passed to the `<td>` elements. Can also be a function for dynamic values.
+	 * Defines the classes to be passed to every data cell. Can also be a function for dynamic values.
 	 */
 	tdClass?: ColumnClasses<Item>;
 
 	/**
-	 * Defines the classes to be passed to the `<th>`.
+	 * Defines the classes to be passed to every header cell.
 	 */
 	thClass?: Classes;
 
@@ -2791,7 +2705,7 @@ export type MappedItem = Option & {
  * Projection that represents a header
  */
 export type MappedHeader = {
-	align: HTMLTableCellElement['align'];
+	align: string;
 	classes?: Classes;
 	key: string;
 	label: string;
@@ -2821,9 +2735,12 @@ export type ExpandControllerProps = {
 };
 
 export type BbTableEvents = {
-	(e: 'click:row', event: MouseEvent, item: any, selected: boolean): void;
-	(e: 'contextmenu:row', event: MouseEvent, item: any, selected: boolean): void;
-	(e: 'dblclick:row', event: MouseEvent, item: any, selected: boolean): void;
+	// Row events carry `(event, item)` only, where `item` is the RAW record
+	// from `items` — not the table's internal row wrapper. Selection state is
+	// derivable from the selection v-model, so it is not repeated here.
+	(e: 'click:row', event: MouseEvent, item: any): void;
+	(e: 'contextmenu:row', event: MouseEvent, item: any): void;
+	(e: 'dblclick:row', event: MouseEvent, item: any): void;
 	(e: 'update:highlighted', value: any): void;
 	(e: 'update:modelValue', value: any): void;
 	(e: 'update:selectAll', value: boolean): void;
@@ -2834,22 +2751,58 @@ export type BbTableEvents = {
 	(e: 'item:unselected', value: any): void;
 };
 
+/**
+ * Props exposed by the table-wide `header:prepend` / `header:append` slots and
+ * their per-column `header:<key>:prepend` / `header:<key>:append` variants —
+ * the `header:<key>` payload plus the column key.
+ */
+export type BbTableHeaderAffixSlotProps<Item = any> = {
+	/** Merged header classes for this column. */
+	classes?: Classes;
+	/**
+	 * The raw key of the column being rendered — branch on it in the
+	 * table-wide slots.
+	 */
+	columnKey: string;
+	/** The current table items. */
+	items?: Item[];
+	/** The column's label. */
+	label?: string;
+	/** Whether this column is sortable. */
+	sortable?: boolean;
+	/** This column's current sort direction, or `null` when unsorted. */
+	sortOrder?: 'asc' | 'desc' | null;
+	/** Cycles this column's sort: unsorted → asc → desc → unsorted. */
+	toggleSort?: () => void;
+};
+
 export type BbTableSlots<Item = any> = {
 	/**
-	 * Replaces the entire `<thead>` element. Use when you need full control over the header markup.
+	 * Replaces the content of the header row group (`.bb-table__head`). Use when
+	 * you need full control over the header markup. The table is a CSS grid,
+	 * not a `<table>`: provide role-complete rows — `<div role="row">` holding
+	 * one `<div role="columnheader">` per column — and never a `<tr>`/`<th>`.
+	 * Rows are subgrid rows, so each cell lands on the matching column track.
 	 */
 	thead?: (props: object) => any;
 	/**
-	 * Replaces the entire `<tbody>` element. Use when you need full control over the body markup.
+	 * Replaces the content of the body row group (`.bb-table__body`). Use when
+	 * you need full control over the body markup. Provide role-complete rows —
+	 * `<div role="row">` holding one `<div role="cell">` per column — never a
+	 * `<tr>`/`<td>`. A full-width cell spans with `grid-column: 1 / -1`.
 	 */
 	tbody?: (props: object) => any;
 	/**
-	 * Replaces the entire `<tfoot>` element. Use when you need full control over the footer markup.
+	 * Fills the footer row group (`.bb-table__foot`). Use when you need a
+	 * footer. Provide role-complete rows — `<div role="row">` holding
+	 * `<div role="cell">` elements — never a `<tr>`/`<td>`.
 	 */
 	tfoot?: (props: {
 		/**
-		 * Total rendered column count — the value to give a full-width footer row's
-		 * `colspan` (accounts for the selection/expand columns), so you never hand-count it.
+		 * Total rendered column count (accounts for the selection/actions
+		 * columns), so you never hand-count it. A footer cell spanning the
+		 * whole table uses `grid-column: 1 / -1`; one spanning a subset uses
+		 * `grid-column: span N` with `N` up to this value.
 		 */
 		columnCount: number;
 	}) => any;
@@ -2869,6 +2822,20 @@ export type BbTableSlots<Item = any> = {
 	 * @param text - The accessible label text for the actions column header.
 	 */
 	'header:actions'?: (props: { text: string }) => any;
+	/**
+	 * Content rendered before every data column's header cell content — the
+	 * label + sort control, or the column's own `header:<key>` replacement.
+	 * A column's `header:<key>:prepend` slot wins over this one for that
+	 * column; they never stack. Branch on `columnKey` for per-column output.
+	 */
+	'header:prepend'?: (props: BbTableHeaderAffixSlotProps<Item>) => any;
+	/**
+	 * Content rendered after every data column's header cell content — the
+	 * label + sort control, or the column's own `header:<key>` replacement.
+	 * A column's `header:<key>:append` slot wins over this one for that
+	 * column; they never stack. Branch on `columnKey` for per-column output.
+	 */
+	'header:append'?: (props: BbTableHeaderAffixSlotProps<Item>) => any;
 	/**
 	 * Content shown while table rows are loading (replaces the skeleton rows).
 	 * @param items - The current (possibly stale) list of items, useful to match the previous row count.
@@ -2876,9 +2843,9 @@ export type BbTableSlots<Item = any> = {
 	loading?: (props: { items: Item[] }) => any;
 	/**
 	 * Content shown when the items list is empty and not loading. It fills the
-	 * table's own full-width empty-state cell (the colspan already accounts for
-	 * the selection/actions columns), so provide the *content* — a message, an
-	 * illustration, a "clear filters" button — never a `<tr>`/`<td>` of your own.
+	 * table's own full-width empty-state cell (it already spans the
+	 * selection/actions columns), so provide the *content* — a message, an
+	 * illustration, a "clear filters" button — never a row/cell of your own.
 	 */
 	'no-data'?: (props: object) => any;
 	/**
@@ -2950,6 +2917,11 @@ export type BbTableSlots<Item = any> = {
 	string,
 	(props: {
 		classes?: Classes[];
+		/**
+		 * Present only in the `header:<key>:prepend/append` affix slots — the
+		 * raw key of the column being rendered.
+		 */
+		columnKey?: string;
 		content?: any;
 		expanded?: boolean;
 		expandProps?: ExpandControllerProps;
@@ -2977,6 +2949,12 @@ export type BbTableSlots<Item = any> = {
 
 ```css
 .bb-table {
+	/* The table's surface colour. Cells are transparent at rest so the row can
+	   tint them, but anything that sticks over scrolled content — the stuck
+	   head band and `fixed-columns` cells — must be opaque, and paints this.
+	   Set it on the table (`.my-table { --bg: … }`) when the table sits on a
+	   surface that is not `--bb-panel`; a nested table re-declares its own. */
+	--bg: var(--bb-panel);
 	--padding-x: 12px;
 	--cell-h: 36px;
 	--padding-y: 6px;
@@ -2993,9 +2971,6 @@ export type BbTableSlots<Item = any> = {
 	--offset-internal-end: var(--offset-end);
 	--offset-external-start: 0px;
 	--offset-external-end: 0px;
-	/* Slack the fill column adds to reach the parent's width. Reset per table so a
-	   nested table never inherits an ancestor's value through the cascade. */
-	--fill: 0px;
 	display: grid;
 	/* Override the UA `min-inline-size: min-content` that a <fieldset> container
 	   (rendered for selectable tables) carries — without this the container can't
@@ -3004,14 +2979,6 @@ export type BbTableSlots<Item = any> = {
 	min-width: 0;
 	overflow-x: auto;
 
-	/* While a container resize waits on the debounced column re-probe, the stale
-	   (wider) column widths would flash a horizontal scrollbar; clip instead of
-	   scroll for that window. Applied only when the table wasn't already
-	   overflowing, so no live scroll position is ever clipped away. */
-	&--measuring {
-		overflow-x: clip;
-	}
-
 	padding-inline-end: var(--offset-external-end);
 	padding-inline-start: var(--offset-external-start);
 
@@ -3035,89 +3002,133 @@ export type BbTableSlots<Item = any> = {
 		--padding-y: 4px;
 	}
 
+	/* The visible caption keeps the UA `<caption>` centring it used to get. */
+	&-caption {
+		text-align: center;
+	}
+
+	/* --- The grid -------------------------------------------------------------
+	   The root owns the column tracks (`grid-template-columns` is set inline
+	   from the column definitions) and every rowgroup and row is a subgrid of
+	   it, so a cell lands on its track through two levels without any width
+	   of its own. Real boxes at every level, never `display: contents`: the
+	   rowgroups host the busy bar and the loading opacity, and only a real box
+	   can be sticky.
+
+	   `gap: 0` on the root is the authority — the heir of the old
+	   `border-spacing: 0` preflight reset. A subgrid-level `gap: 0` CANNOT
+	   neutralise a gap set on the root: the subgrid closes its gutters by
+	   growing its edge cells into the half-gutters (200px tracks came out
+	   215/230/215), so the root value is the only real protection; the two
+	   subgrid-level declarations below are defence in depth only. */
+	&__table {
+		display: grid;
+		gap: 0;
+		/* Reproduces the old `<table>` box: fills the container when the tracks
+		   sum below it, grows to the tracks' sum (and scrolls the container) when
+		   they don't. Bare `min-width: 100%` would leave this box at container
+		   width with the tracks overflowing it — row backgrounds and the busy bar
+		   would paint short and `%` widths would resolve against the wrong box.
+		   Nothing paints on the root itself: rowgroups and rows are the paint
+		   surfaces. */
+		min-width: 100%;
+		width: fit-content;
+	}
+
+	&__head,
+	&__body,
+	&__foot {
+		display: grid;
+		gap: 0;
+		grid-column: 1 / -1;
+		grid-template-columns: subgrid;
+	}
+
+	/* Anchors the busy bar (`::after` below). Positioned unconditionally so the
+	   fixed-header rule (a plain `sticky`, higher specificity) never has to fight
+	   a loading-only `relative`. */
+	&__head {
+		position: relative;
+	}
+
+	&__head > [role='row'],
+	&__body > [role='row'],
+	&__foot > [role='row'] {
+		display: grid;
+		gap: 0;
+		grid-column: 1 / -1;
+		grid-template-columns: subgrid;
+	}
+
+	/* Sticky headers live on the head ROWGROUP: a sticky cell or row inside the
+	   double subgrid cannot stick in any engine (an item's vertical sticky slack
+	   is bounded by its own grid container — the one-row-tall row). Descendant
+	   form on purpose, so a nested table's head sticks along, as it always did.
+	   The stuck band paints `--bg` so scrolled rows never show through it.
+	   Sticky-column header cells (inline sticky from `fixed-columns`) sit above
+	   their scrolled siblings within the band. */
 	&--fixed-header {
-		table {
-			thead {
-				th {
-					position: sticky;
-					top: 0;
-					z-index: 1;
-				}
-				th[style*='sticky'] {
-					position: sticky;
-					top: 0;
-					z-index: 2;
-				}
-			}
+		.bb-table__head {
+			background-color: var(--bg);
+			position: sticky;
+			top: 0;
+			z-index: 1;
+		}
+		.bb-table__head [style*='sticky'] {
+			z-index: 2;
 		}
 	}
 
-	&--selectable {
-		tr {
-			> .bb-table-data__cell--select {
-				text-align: center;
-				width: 0px;
-			}
-		}
+	/* A `fixed-columns` cell (inline `position: sticky` from the component)
+	   slides over its scrolled siblings, so it cannot stay transparent. It
+	   paints the row's current tint when the row has one (`--row-bg`, set by
+	   the hover / highlighted states below), else the table surface — so a
+	   pinned cell never reads as a hole in a hovered or current row. */
+	[style*='sticky'] {
+		background-color: var(--row-bg, var(--bg));
+		/* Same curve and duration as the row's own tint transition, so a pinned
+		   cell fades in step with its row instead of snapping ahead of it. */
+		transition: background-color var(--bb-transition-fast) var(--bb-ease);
 	}
 
-	table {
-		/* On the <table> element itself, not the container: `border-spacing` is
-		   inherited, so a container-level `0` loses to the UA's element rule
-		   (`table { border-spacing: 2px }`) — without a preflight reset every
-		   cell would drift by 2px per gridline and break nested-table
-		   alignment. */
-		border-collapse: separate;
-		border-spacing: 0;
-		min-width: 100%;
+	&--selectable {
+		[role='row'] > .bb-table-data__cell--select {
+			text-align: center;
+		}
 	}
 
-	/* A nested table inheriting its parent's widths sizes to the sum of its
-	   columns instead of filling its container, so fixed layout cannot stretch
-	   them out of alignment. Declared after `--fixed` and the base table rule so
-	   it overrides their width/min-width at equal specificity. */
+	/* A nested table inheriting its parent's widths sizes to its tracks (the
+	   parent's, republished as custom properties) instead of filling its
+	   container, so its columns stay aligned with the parent's. */
 	&--inherit-widths {
 		/* Never grow past the parent's expand cell: a child with more columns
-		   than the parent overflows the cell, so cap the container here and let its
-		   own `overflow-x: auto` scroll the surplus columns inside the expand row
-		   rather than stretching the ancestor. */
+		   than the parent overflows the cell, so cap the container here rather
+		   than stretching the ancestor. */
 		max-width: 100%;
 		min-width: 0;
 
-		table {
-			min-width: 0;
-			/* A *definite* width (not `max-content`) so `table-layout: fixed` stays
-			   content-independent: inherited columns keep their colgroup widths and
-			   align with the parent instead of growing to fit content. The fill
-			   column is `auto`, so fixed layout hands it the leftover; when columns
-			   overflow, the table grows past 100% and scrolls. */
-			width: 100%;
-		}
-	}
-
-	/* Declared after the base `table { min-width: 100% }` rule so it wins the
-	   cascade at equal specificity. The probe publishes the natural content width
-	   of all columns; the table fills its container freely but never compresses
-	   below that floor — the container's `overflow-x: auto` then shows a
-	   scrollbar instead of squishing content. */
-	&--fixed {
-		> table {
-			table-layout: fixed;
-			width: 100%;
-
-			thead {
-				.bb-table-header--actions {
-					width: auto;
-				}
-			}
-		}
-
-		table {
-			min-width: var(--natural-width, 0px);
-		}
+		/* No scrollport of its own — the ancestor's is the one that matters.
+		   A child that inherits its parent's tracks is sized to the parent's
+		   CONTENT width, so a scrollport here would have its right edge off in
+		   the overflow where nobody can see it, and `position: sticky` from
+		   `fixed-columns` would affix to that instead of to the visible edge:
+		   the parent's actions pin correctly while the child's sit hundreds of
+		   pixels off-screen until you scroll all the way right.
+
+		   Scrolling it separately was never coherent anyway. The whole point of
+		   `inherit-column-widths` is that the child's columns line up with the
+		   parent's, and an independent scrollport breaks that alignment the
+		   moment either one moves. One scrollport, one scroll position, columns
+		   that stay aligned — and sticky that affixes where the reader is
+		   looking. Both axes: with only `overflow-x` set, `overflow-y` computes
+		   to `auto` and the scrollport comes back. */
+		overflow: visible;
 	}
 
 	&-header {
+		/* Centres the content vertically like the UA did for table cells; the
+		   cell stays a block container so header affixes keep their inline flow. */
+		align-content: center;
 		border-bottom: var(--bb-border-w) solid var(--bb-border);
 		color: var(--bb-text-muted);
 		font-size: var(--bb-fs);
@@ -3131,16 +3142,13 @@ export type BbTableSlots<Item = any> = {
 		&--right {
 			text-align: right;
 		}
-
-		&--actions {
-			width: 0;
-		}
 	}
 
-	/* Sortable header control: label + the two-arrow sort icon. The icon is
-	   invisible at rest and fades in muted on hover/focus; an active sort keeps
-	   it visible with the active direction's arrow at full strength while the
-	   other arrow stays muted. */
+	/* Sortable header control: label + one arrow. Invisible at rest; hovering
+	   or focusing the header previews a faint arrow (the direction the next
+	   click sorts by); an active sort shows it solid — up for ascending,
+	   rotated down for descending (AG Grid convention) — and the third click
+	   clears it. The opacity ladder and the rotation both transition. */
 	&-sort {
 		align-items: center;
 		background: none;
@@ -3165,60 +3173,87 @@ export type BbTableSlots<Item = any> = {
 		}
 
 		.bb-table-sort__icon {
-			color: var(--bb-muted);
+			--arrow-preview: 0.45;
+			color: var(--bb-text);
 			flex-shrink: 0;
 			opacity: 0;
-			transition: opacity var(--bb-transition-fast) var(--bb-ease);
+			transition:
+				opacity var(--bb-transition-fast) var(--bb-ease),
+				transform var(--bb-transition-fast) var(--bb-ease);
 		}
 
-		/* The arrows are `fill: currentColor`, so transitioning `color` fades
-		   them between the muted rest tone and the active `--bb-text`. */
-		.sort-icon__asc,
-		.sort-icon__desc {
-			transition: color var(--bb-transition-fast) var(--bb-ease);
+		/* Preview: faint arrow while the header is hovered or focused. */
+		&:hover .bb-table-sort__icon,
+		&:focus-visible .bb-table-sort__icon {
+			opacity: var(--arrow-preview);
 		}
 
-		&:hover .bb-table-sort__icon,
-		&:focus-visible .bb-table-sort__icon,
+		/* Active sort: solid, and the second direction flips the arrow. */
 		&--asc .bb-table-sort__icon,
-		&--desc .bb-table-sort__icon {
+		&--desc .bb-table-sort__icon,
+		&--asc:hover .bb-table-sort__icon,
+		&--desc:hover .bb-table-sort__icon {
 			opacity: 1;
 		}
 
-		&--asc .sort-icon__asc,
-		&--desc .sort-icon__desc {
-			color: var(--bb-text);
+		&--desc .bb-table-sort__icon {
+			transform: rotate(180deg);
 		}
 	}
 
-	tbody {
-		tr {
-			/* On the cells, not the row: the table renders with the separate border
-			   model, where a `tr` border never paints. */
-			&:not(:last-child) > td {
-				border-bottom: var(--bb-border-w) solid var(--bb-border);
-			}
-			td {
-				color: var(--bb-text);
-				font-size: var(--bb-fs);
-				font-weight: 400;
-				height: var(--cell-h);
-				padding: var(--padding-y) var(--padding-x);
-			}
+	/* Every cell of this table's own body rows (data, structural, skeleton,
+	   empty-state, expand, loading) — the `:scope >`-style child chain keeps a
+	   nested table's cells out. The row step is wrapped in `:where()` so these
+	   rules stay at (0,2,0): the `<table>` era's `.bb-table tbody tr td` was
+	   (0,1,3), and consumer overrides scoped to one class + a cell class that
+	   won then must keep winning now. */
+	&__body > :where([role='row']) {
+		/* Row separators on the cells, not the row, so a full-width cell and a
+		   data cell draw the same line. */
+		&:where(:not(:last-child)) > [role='cell'] {
+			border-bottom: var(--bb-border-w) solid var(--bb-border);
+		}
 
-			td.bb-table-expand__cell {
-				/* Collapse to the content's height instead of inheriting the data-row
-				   cell height, so an expand row with no slot content takes no space. */
-				height: auto;
-				padding: 0;
+		> [role='cell'] {
+			/* Centres like the UA `vertical-align: middle` of table cells. */
+			align-content: center;
+			color: var(--bb-text);
+			font-size: var(--bb-fs);
+			font-weight: 400;
+			/* A minimum, as a `<td>` height always was: a grid box's `height` is a
+			   hard cap and would clip wrapped content. */
+			min-height: var(--cell-h);
+			padding: var(--padding-y) var(--padding-x);
+		}
 
-				&:empty {
-					display: none;
-				}
+		> .bb-table-expand__cell {
+			/* Collapse to the content's height instead of inheriting the data-row
+			   cell height, so an expand row with no slot content takes no space. */
+			min-height: 0;
+			padding: 0;
+
+			&:empty {
+				display: none;
 			}
 		}
 	}
 
+	/* Full-width cells span every track of their subgrid row. `contain:
+	   inline-size` is what keeps them from sizing the tracks: without it a
+	   spanning item's max-content contribution back-pressures the columns
+	   (300px tracks became 500px), and with a nested inheriting table inside
+	   that is a runaway loop. Containment holds the parent's tracks exactly;
+	   the content still overflows visibly, the ancestor scrollport still
+	   scrolls it, and sticky descendants keep working. Scoped to these three
+	   cells only — on every cell it would zero every intrinsic contribution. */
+	&-expand__cell,
+	&-no-data__cell,
+	&-loading__cell {
+		contain: inline-size;
+		grid-column: 1 / -1;
+		min-width: 0;
+	}
+
 	/* Apply the structural edge offsets to the first/last *data* column. They
 	   must land on the data cells, not the absolute first/last child: a select
 	   or actions column would otherwise absorb the fill and leave the data
@@ -3228,15 +3263,15 @@ export type BbTableSlots<Item = any> = {
 	   reserved as extra edge padding, but a *negative* offset (a select/actions
 	   column reclaimed from this column's width) must not eat into the normal
 	   `--padding-x` — that only shrinks the column width, not its inner padding. */
-	thead tr > th.bb-table-header--edge-start,
-	tbody tr > td.bb-table-data__cell--edge-start {
+	&__head > [role='row'] > .bb-table-header--edge-start,
+	&__body > [role='row'] > .bb-table-data__cell--edge-start {
 		padding-inline-start: calc(
 			var(--padding-x) + max(0px, var(--offset-internal-start))
 		);
 	}
 
-	thead tr > th.bb-table-header--edge-end,
-	tbody tr > td.bb-table-data__cell--edge-end {
+	&__head > [role='row'] > .bb-table-header--edge-end,
+	&__body > [role='row'] > .bb-table-data__cell--edge-end {
 		padding-inline-end: calc(
 			var(--padding-x) + max(0px, var(--offset-internal-end))
 		);
@@ -3245,8 +3280,8 @@ export type BbTableSlots<Item = any> = {
 	&.bb-table--loading {
 		.bb-table-loading__row {
 			.bb-table-loading__cell {
+				align-content: start;
 				padding: 0 var(--padding-x) !important;
-				vertical-align: top;
 			}
 		}
 
@@ -3254,6 +3289,7 @@ export type BbTableSlots<Item = any> = {
 			.bb-table-loading__cell {
 				border: none;
 				height: 0;
+				min-height: 0;
 				overflow: hidden;
 				padding: 0 !important;
 			}
@@ -3262,15 +3298,17 @@ export type BbTableSlots<Item = any> = {
 
 	&-skeleton {
 		&__cell {
-			height: var(--cell-h);
-			overflow: hidden;
+			align-content: center;
+			min-height: var(--cell-h);
+			/* `clip`, not `hidden`: a scroll container zeroes a grid item's
+			   automatic minimum, which let skeleton tracks compress below the
+			   shimmer's width and cut it flush at the column border. */
+			overflow: clip;
 			padding: var(--padding-y) var(--padding-x);
-			vertical-align: middle;
 
 			&--select,
 			&--actions {
 				text-align: center;
-				width: 0;
 			}
 		}
 
@@ -3375,9 +3413,9 @@ export type BbTableSlots<Item = any> = {
 	   centres itself regardless of the table's column alignment. */
 	&-no-data {
 		&__cell {
+			align-content: center;
 			padding: var(--padding-y) var(--padding-x);
 			text-align: center;
-			vertical-align: middle;
 		}
 
 		&__text {
@@ -3387,15 +3425,20 @@ export type BbTableSlots<Item = any> = {
 
 	&-data {
 		&__row {
+			/* Keep a row on one printed page. */
+			break-inside: avoid;
 			transition: background-color var(--bb-transition-fast) var(--bb-ease);
 
+			/* Row states publish their fill as `--row-bg` too, so pinned
+			   (sticky) cells — which must be opaque — paint the same colour. */
 			&:hover {
-				background-color: var(--bb-surface-hover);
+				--row-bg: var(--bb-surface-hover);
+				background-color: var(--row-bg);
 			}
 
 			/* Focusable only with `keyboardNavigation`; the ring is mandatory
-			   focus indication, not decoration. Inset outline (not box-shadow) —
-			   it paints reliably on table rows. */
+			   focus indication, not decoration. Inset outline so it never
+			   escapes the scrollport. */
 			&:focus-visible {
 				outline: var(--bb-ring-size) solid var(--bb-ring);
 				outline-offset: calc(var(--bb-ring-size) * -1);
@@ -3413,19 +3456,18 @@ export type BbTableSlots<Item = any> = {
 			   while the pointer is over it. Consumers can still override the whole
 			   look via `row-class`. */
 			&--highlighted {
-				background-color: color-mix(
-					in oklab,
-					var(--bb-primary) 8%,
-					var(--bb-panel)
-				);
-				box-shadow: inset 3px 0 0 0 var(--bb-primary);
+				--row-bg: color-mix(in oklab, var(--bb-primary) 8%, var(--bg));
+				background-color: var(--row-bg);
+
+				/* The accent bar sits on the first CELL, not the row: a pinned
+				   (opaque) first column would otherwise cover it. Same position
+				   either way — the first cell is the row's left edge. */
+				> :first-child {
+					box-shadow: inset 3px 0 0 0 var(--bb-primary);
+				}
 
 				&:hover {
-					background-color: color-mix(
-						in oklab,
-						var(--bb-primary) 15%,
-						var(--bb-panel)
-					);
+					--row-bg: color-mix(in oklab, var(--bb-primary) 15%, var(--bg));
 				}
 			}
 		}
@@ -3443,6 +3485,14 @@ export type BbTableSlots<Item = any> = {
 
 	&__cell {
 		&--actions {
+			/* Controls sit at the row's end. Invisible on a root table (the
+			   track IS the content width) — it matters in a nested table, whose
+			   actions track is widened to the parent's region so the two cells
+			   are equal and the controls line up under the parent's. */
+			text-align: end;
+			/* Track-sizing-critical: the actions track is `max-content`, and
+			   `nowrap` is what makes that the width of the controls laid side by
+			   side rather than a wrapped stack. */
 			white-space: nowrap;
 			> *:not(:first-child) {
 				margin-left: var(--actions-spacing);
@@ -3481,23 +3531,23 @@ export type BbTableSlots<Item = any> = {
    dependency change (a filter, a poll, an autosave round-trip). Keep the rows
    on screen, mark them stale, and run an indeterminate bar along the header/body
    boundary. `aria-busy` on the root already carries the semantics and the
-   sr-only row in `<tbody>` still announces, so the bar is decorative — hence a
+   sr-only row in the body still announces, so the bar is decorative — hence a
    pseudo-element rather than a node. `.bb-table--empty` is "nothing to keep". */
 .bb-table--loading:not(.bb-table--empty) {
-	& tbody {
+	& .bb-table__body {
 		opacity: 0.55;
 		transition: opacity var(--bb-transition-fast) ease;
 	}
 
-	/* Anchors the bar. When `fixed-header` is on, thead is already sticky and
-	   the bar rides along with it. */
-	& thead {
-		position: relative;
-	}
+	/* Anchored to the head rowgroup (positioned above). With `fixed-header`
+	   the head is sticky, so the bar rides along with the stuck band.
 
-	/* Animating background-position repaints a 2px strip instead of laying out
-	   a moving node every frame, and needs no wrapper to clip it. */
-	& thead::after {
+	   MUST stay absolutely positioned: on a subgrid box a non-positioned
+	   pseudo-element becomes a grid item and inserts a phantom row (the header
+	   row doubled in height). Animating background-position repaints a 2px
+	   strip instead of laying out a moving node every frame, and needs no
+	   wrapper to clip it. */
+	& .bb-table__head::after {
 		animation: bb-table-busy-slide 1.1s linear infinite;
 		background: linear-gradient(
 			90deg,
@@ -3528,7 +3578,7 @@ export type BbTableSlots<Item = any> = {
 }
 
 @media (prefers-reduced-motion: reduce) {
-	.bb-table--loading:not(.bb-table--empty) thead::after {
+	.bb-table--loading:not(.bb-table--empty) .bb-table__head::after {
 		animation: none;
 		background: var(--bb-primary);
 		opacity: 0.5;