basalt-ui 1.30.2 → 1.32.0

package/src/charts/utils/ticks.ts

@@ -12,47 +12,123 @@ const X_TICK_LABEL_GAP = 8
  * `useBandPlot` and `DualPanel` — the three call sites that used to reimplement this formula.
  *
  * `fontPx` defaults to `VX.axisFont`; a phone-tier chart passes its own smaller tick font
- * (`chartTierMetrics().axisFont`) so the spacing is derived from the size actually painted.
+ * (`chartMetrics().axisFont`) so the spacing is derived from the size actually painted.
  */
 export function xLabelPxFor(labels: string[], fontPx: number = VX.axisFont): number {
   return maxTextWidth(labels, fontPx) + X_TICK_LABEL_GAP
 }
 
+/**
+ * The horizontal room one 45°-rotated x label takes: its projected box (`cos 45°` of the width plus
+ * one line box) plus the gap. A tilted label still competes with its neighbour for this much, so
+ * thinning by the bare `VX.minPxPerTick` floor let two of them touch as soon as the plot widened.
+ */
+export function rotatedXLabelPx(labels: string[], fontPx: number = VX.axisFont): number {
+  return (
+    Math.ceil(COS_45 * (maxTextWidth(labels, fontPx) + Math.ceil(fontPx * 1.35))) + X_TICK_LABEL_GAP
+  )
+}
+
 /**
  * Pick evenly-spaced tick values that fit the available width.
  *
  * `labelPx` is the width one formatted label actually needs (measured, plus the gap it wants from
- * its neighbour) and overrides the `VX.minPxPerTick` floor whenever it is wider. Without it the
- * spacing came from that constant alone regardless of what was painted, so a `formatX` returning
- * `Mar 08 14:00` overlapped at every width — the one side of the chart that did not follow §1's
- * "measure what you paint" law. Omit it and nothing moves.
+ * its neighbour) and REPLACES the `VX.minPxPerTick` constant whenever it is supplied, in either
+ * direction — a wide label needs more room than the constant assumed (a `formatX` returning
+ * `Mar 08 14:00` used to overlap at every width, the one side of the chart that did not follow
+ * §1's "measure what you paint" law), and a narrow one (single-digit band labels) can pack in
+ * MORE ticks than the constant would allow, which the floor used to suppress (R2C-11). Omit it and
+ * the constant is what governs, same as before.
  *
  * The final key is still appended when the step misses the last index — a thinned axis would
  * otherwise paint no label at the right edge at all — but it no longer prints ON TOP of its
  * neighbour. An appended tick lands a PARTIAL step from the last one on the grid, so at any tick
  * count wide enough labels overlap there; measured at `/charts-stress` block (f1), `Mar 13 14:00`
  * and `Mar 14 14:00` printed over each other at 1440px. When that gap is narrower than one label,
- * the grid tick before it is dropped instead. Index 0 is never dropped: the left edge is the one
- * label a reader orients from.
+ * the grid tick before it is dropped instead.
+ *
+ * `anchorTerminals` (default false) mirrors the SAME flag `autoMargin`/`Axes.tsx` take: when the
+ * axis anchors index 0 and the last index at their TEXT edge rather than their centre
+ * (`terminalAnchor`), each reaches a FULL label's width toward its neighbour instead of half, so
+ * the plain per-tick pitch above (sized for two centred labels) isn't enough at either boundary —
+ * `Bars` with 30 daily "Jan DD HH:MM" keys overlapped there at phone width even though the interior
+ * pitch was fine (R2C-6). The SAME rule then applies, symmetrically, to the tick right after
+ * index 0. 1.5× is a deliberately generous (cheap, simple) stand-in for "one label plus half a
+ * label" rather than measuring the split precisely; it's skipped when `labelPx` is only the bare
+ * `VX.minPxPerTick` floor, which has no relationship to how wide a label actually is. Index 0
+ * always survives (never the one dropped here) and `last` is always (re-)added below, so dropping
+ * any OTHER index never breaks the "at least 2 ticks" floor.
  */
-export function smartTicks(dates: string[], xMax: number, labelPx?: number): string[] {
+export function smartTicks(
+  dates: string[],
+  xMax: number,
+  labelPx?: number,
+  anchorTerminals = false,
+): string[] {
   if (dates.length === 0) return []
-  const perTick = Math.max(VX.minPxPerTick, labelPx ?? 0)
+  // A non-positive `labelPx` (a caller's own arithmetic gone wrong, or an explicit 0) is not "no
+  // measurement" — `labelPx ?? VX.minPxPerTick` let it through as-is, and `xMax / 0` then floors
+  // `maxTicks` to `Infinity`, which used to make EVERY tick "fit" and skip thinning entirely.
+  const perTick = labelPx !== undefined && labelPx > 0 ? labelPx : VX.minPxPerTick
   const maxTicks = Math.max(2, Math.floor(xMax / perTick))
-  if (dates.length <= maxTicks) return dates
-  const step = Math.ceil(dates.length / maxTicks)
   const last = dates.length - 1
+  // `scalePoint({ padding: 0.5 })` spreads N points over `xMax`, so one index is `xMax / N` wide.
+  const pxPerIndex = dates.length > 0 ? xMax / dates.length : 0
+  // Only a REAL measured label (not the bare `VX.minPxPerTick` floor, which knows nothing about how
+  // wide a label actually is) earns the wider terminal clearance below.
+  const anchored = anchorTerminals && labelPx !== undefined && labelPx > 0
 
   const keep = new Set<number>()
-  for (let i = 0; i <= last; i += step) keep.add(i)
+  if (dates.length <= maxTicks) {
+    // Every date already fits with no thinning — round 3: this used to `return dates` here,
+    // skipping the terminal-clearance pass below entirely. A terminal-anchored label still reaches
+    // a FULL label's width toward its neighbour (not half, like a centred one), which the plain
+    // per-tick spacing above does not itself guarantee, so the same pass has to run here too.
+    for (let i = 0; i <= last; i += 1) keep.add(i)
+  } else {
+    const step = Math.ceil(dates.length / maxTicks)
+    for (let i = 0; i <= last; i += step) keep.add(i)
 
-  const lastOnGrid = Math.floor(last / step) * step
-  if (lastOnGrid !== last) {
-    // `scalePoint({ padding: 0.5 })` spreads N points over `xMax`, so one index is `xMax / N` wide.
-    const pxPerIndex = dates.length > 0 ? xMax / dates.length : 0
-    const gapPx = (last - lastOnGrid) * pxPerIndex
-    if (lastOnGrid > 0 && gapPx > 0 && gapPx < perTick) keep.delete(lastOnGrid)
-    keep.add(last)
+    const BOUNDARY_FACTOR = 1.5
+    const boundaryPx = anchored ? perTick * BOUNDARY_FACTOR : perTick
+    // The final key is appended unconditionally, even when the step misses it — but only dropping
+    // the grid tick right before it when the two would otherwise sit closer than one tick's width.
+    // This is the "would an APPEND overlap" concern; it does nothing when the step already lands on
+    // `last` (nothing is being appended), which is the gap the anchored pass below closes.
+    const lastOnGrid = Math.floor(last / step) * step
+    if (lastOnGrid !== last) {
+      const gapPx = (last - lastOnGrid) * pxPerIndex
+      if (lastOnGrid > 0 && gapPx > 0 && gapPx < boundaryPx) keep.delete(lastOnGrid)
+      keep.add(last)
+    }
+  }
+
+  if (anchored && keep.size > 1) {
+    const BOUNDARY_FACTOR = 1.5
+    const boundaryPx = perTick * BOUNDARY_FACTOR
+    // START: the kept index right after 0 needs a FULL label's clearance from it, not the plain
+    // per-tick pitch a centred label would settle for.
+    const sorted = [...keep].toSorted((a, b) => a - b)
+    const second = sorted[1]
+    if (second !== undefined && second !== last && second * pxPerIndex < boundaryPx) {
+      keep.delete(second)
+    }
+    // END: the same check, mirrored, against whatever is now the second-to-last kept index —
+    // computed AFTER the START drop above (not from the original grid), and unconditional of
+    // whether `last` was naturally on the grid or had to be appended (round 3's fix: previously this
+    // only ran inside the `lastOnGrid !== last` branch above, so a grid that already landed on
+    // `last` skipped it — the 13-dates/60px-label/260px-width counter-example this closes: step 4
+    // lands on index 12, leaving its neighbour at index 8 only 80px away, under the 90px a
+    // full-width terminal label needs).
+    const afterHead = [...keep].toSorted((a, b) => a - b)
+    const secondLast = afterHead[afterHead.length - 2]
+    if (
+      secondLast !== undefined &&
+      secondLast !== 0 &&
+      (last - secondLast) * pxPerIndex < boundaryPx
+    ) {
+      keep.delete(secondLast)
+    }
   }
 
   return dates.filter((_, i) => keep.has(i))

package/src/common/errors.ts

@@ -48,10 +48,11 @@ export function deprecatedProp(
   oldProp: string,
   newProp: string,
   removeIn: string,
+  note?: string,
 ): string {
   return message(
     component,
-    `prop "${oldProp}" is deprecated — use "${newProp}" instead. "${oldProp}" is removed in ${removeIn}.`,
+    `prop "${oldProp}" is deprecated — use "${newProp}" instead. "${oldProp}" is removed in ${removeIn}.${note === undefined ? '' : ` ${note}`}`,
   )
 }
 
@@ -69,6 +70,19 @@ export function ignoredProp(component: string, prop: string, because: string): s
   return message(component, `prop "${prop}" is ignored because ${because}`)
 }
 
+/**
+ * A numeric `height` the caller stated that, once the legend band is taken out, leaves the plot
+ * under the floor. The frame keeps the plot at the floor and grows past the number, so the chart
+ * is taller than the caller asked for and nothing else says why.
+ */
+export function plotBelowFloor(component: string, height: number, floor: number): string {
+  return message(
+    component,
+    `prop "height" (${height}) leaves less than the ${floor}px plot floor once the legend band is ` +
+      'subtracted, so the frame grows past it. Raise the height or drop the legend.',
+  )
+}
+
 /**
  * An imperative call needs a layer that is not there — the optional peer is not installed, or the
  * mount that subscribes to its event bus is disabled. Both halves are named because the remedy
@@ -86,6 +100,16 @@ export function duplicateMount(component: string): string {
   )
 }
 
+/** Two frames inside one `ChartCard` both want the header legend slot (`docs/waves/PLAN.md` wave
+ * 3, P2-9) — only the first to mount keeps it, every later one falls back to its own band legend
+ * rather than silently overwriting the portal. */
+export function legendSlotContention(component: string): string {
+  return message(
+    component,
+    'more than one chart in this ChartCard wants the header legend slot — only the first keeps it, the rest fall back to their own band legend.',
+  )
+}
+
 // ── Transport-agnostic error decoding ────────────────────────────────────────────────────────────
 //
 // Deliberately in this module, with NO `@tanstack/react-query` import — `dashboard/query-state.tsx`

package/src/common/hit-floor.ts

@@ -0,0 +1,9 @@
+/**
+ * The pointer-tier hit floors, in px — WCAG 2.5.8 Target Size Minimum (24) and 2.5.5 Target Size
+ * Enhanced (44). One home for the number `--vx-hit` resolves to under `(pointer: coarse)` and for
+ * the components that compare a MEASURED px against it (a virtual list's row height, a column-fold
+ * toggle's width, the chart legend's dot pitch). Deliberately not re-exported through
+ * `common/index.ts`: a CSS-var's numeric value is not a public symbol.
+ */
+export const HIT_FINE = 24
+export const HIT_COARSE = 44

package/src/{shell → common}/isomorphic-layout-effect.ts

@@ -5,9 +5,10 @@
  * nothing on the server" warning. The branch reads a global that cannot change between renders, so
  * the hook identity is stable across every render of every caller.
  *
- * One module rather than one `const` per file: `page-bar.tsx` and `page-aside.tsx` declared the
- * same line with the same doc, and the second copy's doc already said "see `page-bar.tsx`'s copy".
- * Not exported from any barrel — this is a shell-internal utility, not a published hook.
+ * Lives in `common/` rather than beside the shell because both halves use it — the shell chrome, the
+ * provider, and the Mantine-free measured-fold core — and `common/` is the one module both may
+ * import from. One module rather than one `const` per file. Not exported from any barrel; import it
+ * by path.
  */
 import { useEffect, useLayoutEffect } from 'react'
 

package/src/common/use-measured-widths.ts

@@ -0,0 +1,88 @@
+import { useRef } from 'react'
+import type { MutableRefObject } from 'react'
+import { useIsomorphicLayoutEffect } from './isomorphic-layout-effect'
+
+/** One measured element's box, cached while it was still visible (a folded child is gone from the DOM). */
+export type MeasuredBox = { width: number; height: number }
+
+export interface UseMeasuredWidthsOptions {
+  /** The box to observe, resolved on each effect run. */
+  resolveRoot: () => HTMLElement | null
+  /** Change this string to drop every cached box — a folded child cannot report its unfolded width. */
+  signature: string
+  /** Skip measuring entirely (the feature is off). Default true. */
+  enabled?: boolean
+  /** Bump to re-measure on demand beyond a resize (a post-reset commit). */
+  nonce?: number
+  /** Extra descendants to observe besides the root (an inner table whose min-content can move). */
+  extra?: (root: HTMLElement) => (Element | null)[]
+  /** Read the current boxes from `root`, fill the cache, and plan — runs on every measure. */
+  onMeasure: (root: HTMLElement, boxes: MutableRefObject<Map<string, MeasuredBox>>) => void
+}
+
+export interface UseMeasuredWidthsResult {
+  boxes: MutableRefObject<Map<string, MeasuredBox>>
+  /** Re-run the measurement by hand (a web font settling changes every width without a resize). */
+  remeasure: () => void
+}
+
+/**
+ * The measured-fold core every fold planner shares: caches each measured box while it is visible,
+ * re-reads on a `ResizeObserver` of the root (plus {@link UseMeasuredWidthsOptions.extra}), and
+ * clears the cache when the {@link UseMeasuredWidthsOptions.signature} changes. The caller keeps its
+ * own element reading and pure plan function in `onMeasure`.
+ *
+ * A folded child is gone from the DOM but its cached box survives, so a resize never needs it back
+ * on screen; the caller's `onMeasure` decides which boxes to cache (e.g. skip an item that is
+ * currently folded, whose painted width is the collapsed one).
+ */
+export function useMeasuredWidths(options: UseMeasuredWidthsOptions): UseMeasuredWidthsResult {
+  const { resolveRoot, signature, enabled = true, nonce = 0, extra, onMeasure } = options
+  const boxes = useRef<Map<string, MeasuredBox>>(new Map())
+  const signatureRef = useRef(signature)
+  const remeasureRef = useRef<() => void>(() => {})
+
+  // Read through refs so a fresh closure each render does not re-run the effect.
+  const resolveRef = useRef(resolveRoot)
+  resolveRef.current = resolveRoot
+  const extraRef = useRef(extra)
+  extraRef.current = extra
+  const onMeasureRef = useRef(onMeasure)
+  onMeasureRef.current = onMeasure
+
+  useIsomorphicLayoutEffect(() => {
+    if (signatureRef.current !== signature) {
+      signatureRef.current = signature
+      boxes.current.clear()
+    }
+    if (!enabled) {
+      // A disabled/detached root leaves no `measure` to re-run — without this a stale closure over
+      // the PREVIOUS root's `onMeasure` survives on `remeasureRef` and a later `remeasure()` call
+      // (the web-font effect in `controls/actions.tsx`) would measure a root that is no longer live.
+      remeasureRef.current = () => {}
+      return
+    }
+    const root = resolveRef.current()
+    if (root === null) {
+      remeasureRef.current = () => {}
+      return
+    }
+    const measure = (): void => {
+      onMeasureRef.current(root, boxes)
+    }
+    remeasureRef.current = measure
+    if (typeof ResizeObserver === 'undefined') {
+      measure()
+      return
+    }
+    const observer = new ResizeObserver(measure)
+    observer.observe(root)
+    for (const el of extraRef.current?.(root) ?? []) {
+      if (el !== null) observer.observe(el)
+    }
+    measure()
+    return () => observer.disconnect()
+  }, [enabled, signature, nonce])
+
+  return { boxes, remeasure: () => remeasureRef.current() }
+}

package/src/common/use-media-query.ts

@@ -0,0 +1,56 @@
+/**
+ * `useMediaQuery` — the one sanctioned raw `window.matchMedia` read
+ * (`basalt/raw-breakpoint`'s `RAW_BREAKPOINT_EXEMPT_FILE`). Every other breakpoint/pointer-tier
+ * hook (`useSizeClass`, `useCoarsePointer`, the shell's own min-width dock check) is built on this
+ * one primitive instead of allocating its own `MediaQueryList`.
+ *
+ * `useSyncExternalStore`, so SSR and the hydration pass read `serverFallback` and the real match
+ * lands one commit later — never a mismatch mid-hydration. One `MediaQueryList` PER QUERY STRING,
+ * shared module-wide: `useSizeClass`'s two boundaries and a chart's coarse-pointer read resolve
+ * through the same handful of live objects rather than each allocating their own.
+ */
+import { useCallback, useSyncExternalStore } from 'react'
+
+// Keyed by the LIVE `window.matchMedia` function, not just the query string: a test that swaps in
+// its own stub (a real pattern in this repo — `provider/host.test.tsx`) gets a fresh inner cache
+// for free, rather than reading a `MediaQueryList` a previous test's stub produced.
+const cache = new WeakMap<typeof window.matchMedia, Map<string, MediaQueryList>>()
+
+function mediaQueryList(query: string): MediaQueryList | null {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return null
+  let byQuery = cache.get(window.matchMedia)
+  if (byQuery === undefined) {
+    byQuery = new Map()
+    cache.set(window.matchMedia, byQuery)
+  }
+  const cached = byQuery.get(query)
+  if (cached !== undefined) return cached
+  const list = window.matchMedia(query)
+  byQuery.set(query, list)
+  return list
+}
+
+/** A one-off, non-reactive read — for a dev-only check that runs once inside an effect/callback
+ * rather than subscribing for the component's lifetime. Prefer `useMediaQuery` for anything that
+ * should re-render on a match change. */
+export function readMediaQuery(query: string, fallback: boolean): boolean {
+  return mediaQueryList(query)?.matches ?? fallback
+}
+
+export function useMediaQuery(query: string, serverFallback: boolean): boolean {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const list = mediaQueryList(query)
+      if (list === null) return () => {}
+      list.addEventListener('change', onStoreChange)
+      return () => list.removeEventListener('change', onStoreChange)
+    },
+    [query],
+  )
+  const getSnapshot = useCallback(
+    () => mediaQueryList(query)?.matches ?? serverFallback,
+    [query, serverFallback],
+  )
+  const getServerSnapshot = useCallback(() => serverFallback, [serverFallback])
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+}

package/src/common/validate.ts

@@ -51,16 +51,29 @@ export function useValidateProps(
     const messages = Array.isArray(result) ? result : [result]
     for (const raw of messages) {
       if (raw === null || raw === undefined) continue
-      const key = `${component} ${raw}`
-      if (reported.has(key)) continue
-      reported.add(key)
-      console.error(raw)
+      reportOnce(component, raw)
     }
     // The deps ARE the caller's contract: this hook cannot know what `check` closes over.
     // oxlint-disable-next-line react-hooks/exhaustive-deps -- the caller owns the dep list
   }, deps)
 }
 
+/**
+ * The same once-per-`(component, message)` dev diagnostic {@link useValidateProps} logs, for a
+ * caller that already owns the effect a check would otherwise race — a decision made synchronously
+ * inside a `useLayoutEffect` (e.g. `ChartFrame`'s header-slot claim, P2-9) has no business waiting a
+ * further render for a REACTIVE check on state that effect itself just set: that state update lags
+ * one commit behind the decision, and a passive-effect check racing it warns about instances that
+ * are about to win in the very next render.
+ */
+export function reportOnce(component: string, message: string): void {
+  if (!isDev()) return
+  const key = `${component} ${message}`
+  if (reported.has(key)) return
+  reported.add(key)
+  console.error(message)
+}
+
 /** Test seam. The once-per-message Set is module state, so a suite has to be able to clear it. */
 export function resetValidatedProps(): void {
   reported.clear()

package/src/content/article-layout.module.css

@@ -17,12 +17,19 @@
   grid-template-columns: minmax(0, var(--vx-prose-measure));
 }
 
-/* The literal below MUST equal `BREAKPOINTS.article` (src/tokens/index.ts) — a `@media`
+/* The literal below MUST equal `BREAKPOINTS.article - 0.1` (src/tokens/index.ts) — a `@media`
  * condition is resolved before custom properties exist, so `max-width: var(--x)` is invalid CSS
- * and a stylesheet with a responsive rule has no choice but to write the number. The token is the
- * readable half; `article-layout.breakpoint.test.ts` asserts the two agree, the same
+ * and a stylesheet with a responsive rule has no choice but to write the number. The 0.1px offset
+ * is `tokens/size-classes.ts`' own `sizeClassMaxEm` convention (Mantine's own): the JS side
+ * (`article-layout.tsx`'s `useSizeClass() === 'expanded'`) reads a plain `min-width: 1200px`,
+ * inclusive AT 1200 — writing this query as a bare `max-width: 1200px` would ALSO be inclusive at
+ * exactly 1200px, so at that one width both conditions would fire at once: JS renders the rail,
+ * and this rule then hides it with `display: none`, leaving neither the rail nor the trigger
+ * visible. `1199.9px` makes the two conditions strict complements with no such gap. The token is
+ * the readable half; `article-layout.breakpoint.test.ts` asserts the two agree, the same
  * "literal must match the token" idiom as `styles.floor.test.ts`. Change both or neither. */
-@media (max-width: 1200px) {
+/* theme-allow raw-media-query — deliberate literal pinned to BREAKPOINTS.article, outside shell/** */
+@media (max-width: 1199.9px) {
   .root {
     grid-template-columns: minmax(0, var(--vx-prose-measure));
   }
@@ -34,6 +41,7 @@
 
 .header {
   grid-column: 1;
+  grid-row: 1;
   display: flex;
   flex-direction: column;
   gap: var(--vx-space-article-header-gap);
@@ -71,11 +79,13 @@
 
 .content {
   grid-column: 1;
+  grid-row: 2;
   min-width: 0;
 }
 
 .tocRail {
   grid-column: 2;
+  grid-row: 2;
   position: sticky;
   /* The rail sticks inside whatever scrolls it — `AppShell.Main` in a shell, the document without
    * one — and NOTHING overhangs that box: the app header and `PageBar` row 2's band are both shell
@@ -87,8 +97,39 @@
   align-self: start;
 }
 
+/* The rail's below-breakpoint replacement (docs/CONTENT-SPEC.md §7): a small sticky trigger that
+ * opens the SAME `TableOfContents` in a `Popover` instead of the rail vanishing. Rendered by JS
+ * (`useSizeClass() !== 'expanded'`), never both at once with `.tocRail` — no media query needed
+ * here, only the sticky/alignment behaviour for whenever it IS mounted. `grid-row: 2` is EXPLICIT,
+ * not left to auto-placement: `.content` also being `grid-column: 1` moves the auto-placement
+ * cursor's row on past row 2 by the time this item (also column 1) is placed, landing it in its
+ * own row BELOW the content instead of at its top — the whole point of this trigger. */
+.tocTrigger {
+  grid-column: 1;
+  grid-row: 2;
+  justify-self: end;
+  align-self: start;
+  position: sticky;
+  top: var(--vx-space-sticky-header-clearance);
+  z-index: 1;
+}
+
+.tocTriggerLabel {
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-micro);
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--vx-faint);
+}
+
+.tocDropdown {
+  min-width: 220px;
+  max-width: min(320px, calc(100vw - 32px));
+}
+
 .footer {
   grid-column: 1;
+  grid-row: 3;
   display: grid;
   grid-template-columns: 1fr 1fr;
   gap: var(--vx-space-article-footer-gap);

package/src/content/article-layout.module.css.d.ts

@@ -11,6 +11,9 @@ declare const classes: {
   readonly metaRow: string
   readonly content: string
   readonly tocRail: string
+  readonly tocTrigger: string
+  readonly tocTriggerLabel: string
+  readonly tocDropdown: string
   readonly footer: string
   readonly navCell: string
   readonly navCellNext: string

package/src/content/article-layout.tsx

@@ -5,8 +5,10 @@
  * `ReadingProgress`) — it does not reimplement them.
  *
  * The header/content/footer all align to the SAME grid column, so the article body reads as one
- * consistent width whether or not the TOC rail is visible (hidden below the 1200px breakpoint,
- * where the content column takes the full centered width instead).
+ * consistent width whether or not the TOC rail is visible. Below the 1200px breakpoint the rail
+ * is replaced, not dropped: a sticky "On this page" trigger opens the same `TableOfContents` in a
+ * `Popover` (docs/CONTENT-SPEC.md §7's originally-documented behavior, `useSizeClass() !==
+ * 'expanded'` — the same numeric threshold, resolved in JS instead of `@media`).
  *
  * @example
  * import { ArticleLayout } from 'basalt-ui/content'
@@ -23,8 +25,9 @@
  * </ArticleLayout>
  */
 import type { CSSProperties, ReactNode } from 'react'
-import { useRef } from 'react'
-import { ScrollArea } from '@mantine/core'
+import { useRef, useState } from 'react'
+import { Button, Popover, ScrollArea } from '@mantine/core'
+import { useSizeClass } from '../shell/use-size-class'
 import classes from './article-layout.module.css'
 import { formatArticleDate } from './article-model'
 import type { ProseDensity } from './prose'
@@ -115,6 +118,22 @@ export function ArticleLayout({
   const articleRef = useRef<HTMLDivElement>(null)
   const rootClass = [classes.root, !toc && classes.noToc, className].filter(Boolean).join(' ')
   const hasMetaRow = meta?.date !== undefined || meta?.readingTime !== undefined
+  // `useSizeClass()` is the JS-side twin of the `@media (max-width: 1200px)` rule below — both read
+  // `BREAKPOINTS.article`/`SIZE_CLASSES.expanded`, the same 1200 number (`article-layout.module.css`'s
+  // own comment). Below it the rail is replaced by a trigger, never both at once — a CSS-only swap
+  // has no hook to open a `Popover` from, so this is one of the JS reads that breakpoint doctrine
+  // reserves `useSizeClass()` for, not a second raw media query.
+  const showTocRail = useSizeClass() === 'expanded'
+  const [tocOpen, setTocOpen] = useState(false)
+  // Resizing across the breakpoint unmounts the `Popover` without closing it — `tocOpen` lives on
+  // THIS component, not the Popover, so crossing back below the breakpoint would otherwise remount
+  // it already open with no user action. Adjusted during render (React's own pattern for resetting
+  // state when a derived value changes), not an effect, so there is no open-then-close flash.
+  const prevShowTocRailRef = useRef(showTocRail)
+  if (prevShowTocRailRef.current !== showTocRail) {
+    prevShowTocRailRef.current = showTocRail
+    if (tocOpen) setTocOpen(false)
+  }
 
   return (
     <div className={rootClass} {...(style !== undefined && { style })}>
@@ -140,7 +159,7 @@ export function ArticleLayout({
         <Prose density={density}>{children}</Prose>
       </div>
 
-      {toc && (
+      {toc && showTocRail && (
         <div className={classes.tocRail}>
           <ScrollArea.Autosize mah="calc(100vh - 108px)" type="hover">
             <TableOfContents containerRef={articleRef} />
@@ -148,6 +167,42 @@ export function ArticleLayout({
         </div>
       )}
 
+      {toc &&
+        !showTocRail && (
+          // `.tocTrigger`'s `grid-row: 2` (article-layout.module.css) is EXPLICIT, matching
+          // `.content`'s own row — not left to CSS Grid's auto-placement, which used to land this
+          // in its own row below the content instead of at its top (both are `grid-column: 1`, and
+          // the auto-placement cursor moves past row 2 once `.content` claims it).
+          <Popover
+            opened={tocOpen}
+            onChange={setTocOpen}
+            onDismiss={() => setTocOpen(false)}
+            position="bottom-end"
+            withinPortal
+            shadow="md"
+            radius="sm"
+            trapFocus
+          >
+            <Popover.Target>
+              <Button
+                variant="subtle"
+                color="gray"
+                size="compact-xs"
+                className={classes.tocTrigger}
+                classNames={{ label: classes.tocTriggerLabel }}
+                onClick={() => setTocOpen((current) => !current)}
+              >
+                On this page
+              </Button>
+            </Popover.Target>
+            <Popover.Dropdown className={classes.tocDropdown}>
+              <ScrollArea.Autosize mah="calc(100vh - 108px)" type="hover">
+                <TableOfContents containerRef={articleRef} onNavigate={() => setTocOpen(false)} />
+              </ScrollArea.Autosize>
+            </Popover.Dropdown>
+          </Popover>
+        )}
+
       {(prev !== undefined || next !== undefined) && (
         <footer className={classes.footer}>
           {prev !== undefined ? (

package/src/content/code-block.module.css

@@ -56,6 +56,27 @@
   overflow-x: auto;
 }
 
+/* Trailing-edge overflow fade (docs/MATURATION-LEDGER.md) — `code-block.tsx` toggles this
+ * attribute from a scroll/resize measurement (`scrollWidth > clientWidth`, not yet at the end), so
+ * it never decorates a block that already fits and never lingers once scrolled to the end. The mask
+ * fades to TRANSPARENT, not to a solid color — what shows through is `.container`'s own translucent
+ * background, already identical to what borders the block everywhere else, so the fade reads as a
+ * soft edge rather than a hard cut. Reuses the content inset token rather than a new literal; LTR
+ * only, matching the rest of this file (no `dir` handling exists here to fade the other edge from).
+ */
+.body[data-code-overflow] {
+  mask-image: linear-gradient(
+    to right,
+    black calc(100% - var(--vx-space-code-block-content-inset-x) * 2),
+    transparent 100%
+  );
+  -webkit-mask-image: linear-gradient(
+    to right,
+    black calc(100% - var(--vx-space-code-block-content-inset-x) * 2),
+    transparent 100%
+  );
+}
+
 .body :global(pre.shiki) {
   margin: 0;
   padding: 0;
@@ -77,11 +98,20 @@ html[data-mantine-color-scheme='light'] .body :global(.shiki span) {
   position: absolute;
   top: var(--vx-space-code-block-floating-copy-offset);
   right: var(--vx-space-code-block-floating-copy-offset);
-  opacity: 0;
   transition: opacity 120ms ease;
 }
 
-.container:hover .floatingCopy,
+/* Hidden-until-hover only where hover exists (pointer tier, docs/DESIGN-CORE.md § Layout). */
+@media (hover: hover) and (pointer: fine) {
+  .floatingCopy {
+    opacity: 0;
+  }
+
+  .container:hover .floatingCopy {
+    opacity: 1;
+  }
+}
+
 .container:focus-within .floatingCopy {
   opacity: 1;
 }