basalt-ui 1.30.2 → 1.32.0

package/dist/common/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/common/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,yDAAyD;AACzD,eAAO,MAAM,aAAa,aAAa,CAAA;AAMvC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED,oEAAoE;AACpE,wBAAgB,KAAK,CACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,GAAG,EAAE,OAAO,GACX,MAAM,CAMR;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,MAAM,CAKR;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAErF;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxD;AAOD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI5D;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,SAAwB,GAAG,MAAM,CAKrF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/common/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,yDAAyD;AACzD,eAAO,MAAM,aAAa,aAAa,CAAA;AAMvC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED,oEAAoE;AACpE,wBAAgB,KAAK,CACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,GAAG,EAAE,OAAO,GACX,MAAM,CAMR;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAKR;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMvF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAErF;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED;;kDAEkD;AAClD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAK9D;AAOD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI5D;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,SAAwB,GAAG,MAAM,CAKrF"}

package/dist/common/errors.js

@@ -11,15 +11,21 @@ function oneOf(component, prop, allowed, got) {
     `prop "${prop}" must be one of ${allowed.map((value) => `'${value}'`).join(" | ")} \u2014 got ${JSON.stringify(got)}.`
   );
 }
-function deprecatedProp(component, oldProp, newProp, removeIn) {
+function deprecatedProp(component, oldProp, newProp, removeIn, note) {
   return message(
     component,
-    `prop "${oldProp}" is deprecated \u2014 use "${newProp}" instead. "${oldProp}" is removed in ${removeIn}.`
+    `prop "${oldProp}" is deprecated \u2014 use "${newProp}" instead. "${oldProp}" is removed in ${removeIn}.${note === void 0 ? "" : ` ${note}`}`
   );
 }
 function ignoredProp(component, prop, because) {
   return message(component, `prop "${prop}" is ignored because ${because}`);
 }
+function plotBelowFloor(component, height, floor) {
+  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.`
+  );
+}
 function missingLayer(component, layer, remedy) {
   return message(component, `needs ${layer}, which is not available \u2014 ${remedy}.`);
 }
@@ -29,6 +35,12 @@ function duplicateMount(component) {
     "more than one instance is mounted at once \u2014 mount exactly one, at the app root."
   );
 }
+function legendSlotContention(component) {
+  return message(
+    component,
+    "more than one chart in this ChartCard wants the header legend slot \u2014 only the first keeps it, the rest fall back to their own band legend."
+  );
+}
 function errorStatus(err) {
   if (err === null || typeof err !== "object") return void 0;
   const status = err.status;
@@ -61,8 +73,10 @@ export {
   duplicateMount,
   errorStatus,
   ignoredProp,
+  legendSlotContention,
   missingLayer,
   oneOf,
+  plotBelowFloor,
   requiredProp,
   toErrorMessage
 };

package/dist/common/hit-floor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare const HIT_FINE = 24;
+export declare const HIT_COARSE = 44;
+//# sourceMappingURL=hit-floor.d.ts.map

package/dist/common/hit-floor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hit-floor.d.ts","sourceRoot":"","sources":["../../src/common/hit-floor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,KAAK,CAAA;AAC1B,eAAO,MAAM,UAAU,KAAK,CAAA"}

package/dist/common/hit-floor.js

@@ -0,0 +1,6 @@
+const HIT_FINE = 24;
+const HIT_COARSE = 44;
+export {
+  HIT_COARSE,
+  HIT_FINE
+};

package/dist/{shell → common}/isomorphic-layout-effect.d.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 } from 'react';
 export declare const useIsomorphicLayoutEffect: typeof useEffect;

package/dist/common/isomorphic-layout-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isomorphic-layout-effect.d.ts","sourceRoot":"","sources":["../../src/common/isomorphic-layout-effect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,SAAS,EAAmB,MAAM,OAAO,CAAA;AAElD,eAAO,MAAM,yBAAyB,kBAA8D,CAAA"}

package/dist/common/use-measured-widths.d.ts

@@ -0,0 +1,37 @@
+import type { MutableRefObject } from 'react';
+/** 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 declare function useMeasuredWidths(options: UseMeasuredWidthsOptions): UseMeasuredWidthsResult;
+//# sourceMappingURL=use-measured-widths.d.ts.map

package/dist/common/use-measured-widths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-measured-widths.d.ts","sourceRoot":"","sources":["../../src/common/use-measured-widths.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAA;AAG7C,2GAA2G;AAC3G,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3D,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,WAAW,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;IACrC,qGAAqG;IACrG,SAAS,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iGAAiG;IACjG,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAA;IACjD,4FAA4F;IAC5F,SAAS,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,KAAK,IAAI,CAAA;CAC1F;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAA;IACjD,iGAAiG;IACjG,SAAS,EAAE,MAAM,IAAI,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,uBAAuB,CAiD5F"}

package/dist/common/use-measured-widths.js

@@ -0,0 +1,51 @@
+import { useRef } from "react";
+import { useIsomorphicLayoutEffect } from "./isomorphic-layout-effect.js";
+function useMeasuredWidths(options) {
+  const { resolveRoot, signature, enabled = true, nonce = 0, extra, onMeasure } = options;
+  const boxes = useRef(/* @__PURE__ */ new Map());
+  const signatureRef = useRef(signature);
+  const remeasureRef = useRef(() => {
+  });
+  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) {
+      remeasureRef.current = () => {
+      };
+      return;
+    }
+    const root = resolveRef.current();
+    if (root === null) {
+      remeasureRef.current = () => {
+      };
+      return;
+    }
+    const measure = () => {
+      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() };
+}
+export {
+  useMeasuredWidths
+};

package/dist/common/use-media-query.d.ts

@@ -0,0 +1,6 @@
+/** 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 declare function readMediaQuery(query: string, fallback: boolean): boolean;
+export declare function useMediaQuery(query: string, serverFallback: boolean): boolean;
+//# sourceMappingURL=use-media-query.d.ts.map

package/dist/common/use-media-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-media-query.d.ts","sourceRoot":"","sources":["../../src/common/use-media-query.ts"],"names":[],"mappings":"AAgCA;;yCAEyC;AACzC,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAExE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAgB7E"}

package/dist/common/use-media-query.js

@@ -0,0 +1,40 @@
+import { useCallback, useSyncExternalStore } from "react";
+const cache = /* @__PURE__ */ new WeakMap();
+function mediaQueryList(query) {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return null;
+  let byQuery = cache.get(window.matchMedia);
+  if (byQuery === void 0) {
+    byQuery = /* @__PURE__ */ new Map();
+    cache.set(window.matchMedia, byQuery);
+  }
+  const cached = byQuery.get(query);
+  if (cached !== void 0) return cached;
+  const list = window.matchMedia(query);
+  byQuery.set(query, list);
+  return list;
+}
+function readMediaQuery(query, fallback) {
+  return mediaQueryList(query)?.matches ?? fallback;
+}
+function useMediaQuery(query, serverFallback) {
+  const subscribe = useCallback(
+    (onStoreChange) => {
+      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);
+}
+export {
+  readMediaQuery,
+  useMediaQuery
+};

package/dist/common/validate.d.ts

@@ -20,6 +20,15 @@ type CheckResult = string | null | undefined | Array<string | null | undefined>;
  * )
  */
 export declare function useValidateProps(component: string, check: () => CheckResult, deps: unknown[]): void;
+/**
+ * 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 declare function reportOnce(component: string, message: string): void;
 /** Test seam. The once-per-message Set is module state, so a suite has to be able to clear it. */
 export declare function resetValidatedProps(): void;
 /**

package/dist/common/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/common/validate.ts"],"names":[],"mappings":"AAYA,iGAAiG;AACjG,KAAK,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;AAU/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,WAAW,EACxB,IAAI,EAAE,OAAO,EAAE,GACd,IAAI,CAeN;AAED,kGAAkG;AAClG,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,CAAC,EACR,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,EAC7C,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GACxD,IAAI,CASN"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/common/validate.ts"],"names":[],"mappings":"AAYA,iGAAiG;AACjG,KAAK,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;AAU/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,WAAW,EACxB,IAAI,EAAE,OAAO,EAAE,GACd,IAAI,CAYN;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAMnE;AAED,kGAAkG;AAClG,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,CAAC,EACR,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,EAC7C,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GACxD,IAAI,CASN"}

package/dist/common/validate.js

@@ -9,13 +9,17 @@ function useValidateProps(component, check, deps) {
     const messages = Array.isArray(result) ? result : [result];
     for (const raw of messages) {
       if (raw === null || raw === void 0) continue;
-      const key = `${component} ${raw}`;
-      if (reported.has(key)) continue;
-      reported.add(key);
-      console.error(raw);
+      reportOnce(component, raw);
     }
   }, deps);
 }
+function reportOnce(component, message) {
+  if (!isDev()) return;
+  const key = `${component} ${message}`;
+  if (reported.has(key)) return;
+  reported.add(key);
+  console.error(message);
+}
 function resetValidatedProps() {
   reported.clear();
 }
@@ -31,6 +35,7 @@ function assertRequiredProps(component, props, keys, hints) {
 }
 export {
   assertRequiredProps,
+  reportOnce,
   resetValidatedProps,
   useValidateProps
 };

package/dist/content/article-layout.d.ts

@@ -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'

package/dist/content/article-layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"article-layout.d.ts","sourceRoot":"","sources":["../../src/content/article-layout.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAK3C,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAA;IACjC,wFAAwF;IACxF,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;IACtB,0FAA0F;IAC1F,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAA;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAA;IAChC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,SAAS,KAAK,SAAS,CAAA;IAC9E,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;IAC/B;0EACsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAC/B,CAAA;AAiCD,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,IAAI,EACJ,GAAU,EACV,eAAuB,EACvB,IAAI,EACJ,IAAI,EACJ,UAA8B,EAC9B,OAAmB,EACnB,MAAgB,EAChB,SAAS,EACT,KAAK,GACN,EAAE,kBAAkB,+BAqDpB"}
+{"version":3,"file":"article-layout.d.ts","sourceRoot":"","sources":["../../src/content/article-layout.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAMrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAK3C,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAA;IACjC,wFAAwF;IACxF,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;IACtB,0FAA0F;IAC1F,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAA;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAA;IAChC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,SAAS,KAAK,SAAS,CAAA;IAC9E,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;IAC/B;0EACsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAC/B,CAAA;AAiCD,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,IAAI,EACJ,GAAU,EACV,eAAuB,EACvB,IAAI,EACJ,IAAI,EACJ,UAA8B,EAC9B,OAAmB,EACnB,MAAgB,EAChB,SAAS,EACT,KAAK,GACN,EAAE,kBAAkB,+BAyGpB"}

package/dist/content/article-layout.js

@@ -1,6 +1,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-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.js";
 import classes from "./article-layout.module.css";
 import { formatArticleDate } from "./article-model.js";
 import { Prose } from "./prose.js";
@@ -44,6 +45,13 @@ function ArticleLayout({
   const articleRef = useRef(null);
   const rootClass = [classes.root, !toc && classes.noToc, className].filter(Boolean).join(" ");
   const hasMetaRow = meta?.date !== void 0 || meta?.readingTime !== void 0;
+  const showTocRail = useSizeClass() === "expanded";
+  const [tocOpen, setTocOpen] = useState(false);
+  const prevShowTocRailRef = useRef(showTocRail);
+  if (prevShowTocRailRef.current !== showTocRail) {
+    prevShowTocRailRef.current = showTocRail;
+    if (tocOpen) setTocOpen(false);
+  }
   return /* @__PURE__ */ jsxs("div", { className: rootClass, ...style !== void 0 && { style }, children: [
     readingProgress && /* @__PURE__ */ jsx(ReadingProgress, { target: articleRef }),
     meta !== void 0 && /* @__PURE__ */ jsxs("header", { className: classes.header, children: [
@@ -59,7 +67,39 @@ function ArticleLayout({
       ] })
     ] }),
     /* @__PURE__ */ jsx("div", { className: classes.content, ref: articleRef, children: /* @__PURE__ */ jsx(Prose, { density, children }) }),
-    toc && /* @__PURE__ */ jsx("div", { className: classes.tocRail, children: /* @__PURE__ */ jsx(ScrollArea.Autosize, { mah: "calc(100vh - 108px)", type: "hover", children: /* @__PURE__ */ jsx(TableOfContents, { containerRef: articleRef }) }) }),
+    toc && showTocRail && /* @__PURE__ */ jsx("div", { className: classes.tocRail, children: /* @__PURE__ */ jsx(ScrollArea.Autosize, { mah: "calc(100vh - 108px)", type: "hover", children: /* @__PURE__ */ jsx(TableOfContents, { containerRef: articleRef }) }) }),
+    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).
+    /* @__PURE__ */ jsxs(
+      Popover,
+      {
+        opened: tocOpen,
+        onChange: setTocOpen,
+        onDismiss: () => setTocOpen(false),
+        position: "bottom-end",
+        withinPortal: true,
+        shadow: "md",
+        radius: "sm",
+        trapFocus: true,
+        children: [
+          /* @__PURE__ */ jsx(Popover.Target, { children: /* @__PURE__ */ jsx(
+            Button,
+            {
+              variant: "subtle",
+              color: "gray",
+              size: "compact-xs",
+              className: classes.tocTrigger,
+              classNames: { label: classes.tocTriggerLabel },
+              onClick: () => setTocOpen((current) => !current),
+              children: "On this page"
+            }
+          ) }),
+          /* @__PURE__ */ jsx(Popover.Dropdown, { className: classes.tocDropdown, children: /* @__PURE__ */ jsx(ScrollArea.Autosize, { mah: "calc(100vh - 108px)", type: "hover", children: /* @__PURE__ */ jsx(TableOfContents, { containerRef: articleRef, onNavigate: () => setTocOpen(false) }) }) })
+        ]
+      }
+    ),
     (prev !== void 0 || next !== void 0) && /* @__PURE__ */ jsxs("footer", { className: classes.footer, children: [
       prev !== void 0 ? /* @__PURE__ */ jsx(NavCell, { target: prev, side: "prev", renderLink }) : /* @__PURE__ */ jsx("span", {}),
       next !== void 0 ? /* @__PURE__ */ jsx(NavCell, { target: next, side: "next", renderLink }) : /* @__PURE__ */ jsx("span", {})

package/dist/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/dist/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/dist/content/code-block.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-block.d.ts","sourceRoot":"","sources":["../../src/content/code-block.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAM1C,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAC/B,CAAA;AAED,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,QAAe,EACf,SAAS,EACT,KAAK,GACN,EAAE,cAAc,+BA4ChB"}
+{"version":3,"file":"code-block.d.ts","sourceRoot":"","sources":["../../src/content/code-block.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAO1C,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAC/B,CAAA;AAED,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,QAAe,EACf,SAAS,EACT,KAAK,GACN,EAAE,cAAc,+BAuFhB"}

package/dist/content/code-block.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
+import { useIsomorphicLayoutEffect } from "../common/isomorphic-layout-effect.js";
 import classes from "./code-block.module.css";
 import { CopyAction } from "./copy-action.js";
 import { highlightCode } from "./highlighter.js";
@@ -12,6 +13,10 @@ function CodeBlock({
   style
 }) {
   const [html, setHtml] = useState(null);
+  const bodyRef = useRef(null);
+  const setBodyRef = (node) => {
+    bodyRef.current = node;
+  };
   useEffect(() => {
     if (language === void 0) return;
     let cancelled = false;
@@ -23,6 +28,23 @@ function CodeBlock({
       cancelled = true;
     };
   }, [code, language]);
+  const [showOverflowFade, setShowOverflowFade] = useState(false);
+  useIsomorphicLayoutEffect(() => {
+    const body = bodyRef.current;
+    if (!body) return;
+    const update = () => {
+      const atEnd = body.scrollLeft + body.clientWidth >= body.scrollWidth - 1;
+      setShowOverflowFade(body.scrollWidth > body.clientWidth && !atEnd);
+    };
+    update();
+    body.addEventListener("scroll", update, { passive: true });
+    const observer = new ResizeObserver(update);
+    observer.observe(body);
+    return () => {
+      body.removeEventListener("scroll", update);
+      observer.disconnect();
+    };
+  }, [html, code]);
   const containerClass = [classes.container, className].filter(Boolean).join(" ");
   return /* @__PURE__ */ jsxs("div", { className: containerClass, ...style !== void 0 && { style }, children: [
     title !== void 0 && /* @__PURE__ */ jsxs("div", { className: classes.header, children: [
@@ -32,7 +54,23 @@ function CodeBlock({
         showCopy && /* @__PURE__ */ jsx(CopyAction, { value: code, ariaLabel: "Copy code" })
       ] })
     ] }),
-    html !== null ? /* @__PURE__ */ jsx("div", { className: classes.body, dangerouslySetInnerHTML: { __html: html } }) : /* @__PURE__ */ jsx("pre", { className: classes.body, children: /* @__PURE__ */ jsx("code", { children: code }) }),
+    html !== null ? /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref: setBodyRef,
+        className: classes.body,
+        ...showOverflowFade && { "data-code-overflow": true },
+        dangerouslySetInnerHTML: { __html: html }
+      }
+    ) : /* @__PURE__ */ jsx(
+      "pre",
+      {
+        ref: setBodyRef,
+        className: classes.body,
+        ...showOverflowFade && { "data-code-overflow": true },
+        children: /* @__PURE__ */ jsx("code", { children: code })
+      }
+    ),
     title === void 0 && showCopy && /* @__PURE__ */ jsx("div", { className: classes.floatingCopy, children: /* @__PURE__ */ jsx(CopyAction, { value: code, ariaLabel: "Copy code" }) })
   ] });
 }

package/dist/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;
 }

package/dist/content/prose.module.css

@@ -149,17 +149,22 @@
   display: inline-flex;
   vertical-align: middle;
   margin-left: var(--vx-space-prose-heading-anchor-gap);
-  opacity: 0;
   transition: opacity 120ms ease;
 }
 
-.root h1:hover .headingAnchor,
-.root h2:hover .headingAnchor,
-.root h3:hover .headingAnchor,
-.root h4:hover .headingAnchor,
-.root h5:hover .headingAnchor,
-.root h6:hover .headingAnchor,
-.headingAnchor:focus-within {
+/* Hidden-until-hover only where hover exists (pointer tier, docs/DESIGN-CORE.md § Layout,
+   elevation, shapes); touch shows it. Focus always reveals (the rule below outranks the hidden one). */
+@media (hover: hover) and (pointer: fine) {
+  .root :is(h1, h2, h3, h4, h5, h6) .headingAnchor {
+    opacity: 0;
+  }
+
+  .root :is(h1, h2, h3, h4, h5, h6):hover .headingAnchor {
+    opacity: 1;
+  }
+}
+
+.root :is(h1, h2, h3, h4, h5, h6) .headingAnchor:focus-within {
   opacity: 1;
 }