@cueplusplus/ui 0.1.0 → 0.3.0

package/dist/layout/sidebar.d.ts

@@ -7,7 +7,27 @@ interface SidebarContextValue {
 }
 /** Read the collapse state of the nearest {@link SidebarRoot}. */
 declare function useSidebar(): SidebarContextValue;
+/**
+ * Which landmark a navigation column announces as.
+ *
+ * `"navigation"` renders `<nav>`, `"complementary"` renders `<aside>`. Two
+ * values rather than a free `role`, because those are the only two a column of
+ * destinations can honestly be — and naming the landmark keeps the element and
+ * the role from ever disagreeing.
+ */
+type SidebarLandmark = "navigation" | "complementary";
 interface SidebarRootProps extends React.ComponentPropsWithoutRef<"aside"> {
+  /**
+   * Which landmark the column is. Defaults to `"navigation"`, rendering
+   * `<nav>`; `"complementary"` renders `<aside>` instead.
+   *
+   * A column of `Sidebar.Item`s is a list of destinations, one of which carries
+   * `aria-current="page"` — that is primary navigation, and announcing it as
+   * complementary tells a screen-reader user the site's main map is an aside.
+   * `"complementary"` is there for the column that genuinely is one: a filter
+   * rail, an inspector, a related-links strip.
+   */
+  landmark?: SidebarLandmark;
   /** Collapsed state when controlled. Pass with `onCollapsedChange`. */
   collapsed?: boolean;
   /** Initial collapsed state when uncontrolled. Defaults to `false`. */
@@ -46,8 +66,8 @@ interface SidebarRailProps extends Omit<React.ComponentPropsWithoutRef<"button">
   expandLabel?: string;
 }
 /**
- * The console's navigation column: sections of items, and a rail that collapses
- * the whole thing to icons.
+ * The console's navigation column: sections of items, a scroller of its own,
+ * and a rail that collapses the whole thing to icons.
  *
  * @example
  * <Sidebar.Root defaultCollapsed aria-label="Main">
@@ -64,4 +84,4 @@ declare const Sidebar: {
   Rail: React.ForwardRefExoticComponent<SidebarRailProps & React.RefAttributes<HTMLButtonElement>>;
 };
 //#endregion
-export { Sidebar, SidebarItemProps, SidebarRailProps, SidebarRootProps, SidebarSectionProps, useSidebar };
+export { Sidebar, SidebarItemProps, SidebarLandmark, SidebarRailProps, SidebarRootProps, SidebarSectionProps, useSidebar };

package/dist/layout/sidebar.js

@@ -19,9 +19,14 @@ const SidebarContext = React.createContext({
 function useSidebar() {
 	return React.useContext(SidebarContext);
 }
+/** The element each landmark is spelled with. */
+const LANDMARK_ELEMENTS = {
+	navigation: "nav",
+	complementary: "aside"
+};
 /**
-* The console's navigation column: sections of items, and a rail that collapses
-* the whole thing to icons.
+* The console's navigation column: sections of items, a scroller of its own,
+* and a rail that collapses the whole thing to icons.
 *
 * @example
 * <Sidebar.Root defaultCollapsed aria-label="Main">
@@ -32,7 +37,8 @@ function useSidebar() {
 * </Sidebar.Root>
 */
 const Sidebar = {
-	Root: React.forwardRef(function SidebarRoot({ className, collapsed: collapsedProp, defaultCollapsed = false, onCollapsedChange, width = "14rem", collapsedWidth = "3rem", style, ...elementProps }, ref) {
+	Root: React.forwardRef(function SidebarRoot({ className, landmark = "navigation", collapsed: collapsedProp, defaultCollapsed = false, onCollapsedChange, width = "14rem", collapsedWidth = "3rem", style, children, ...elementProps }, ref) {
+		const Element = LANDMARK_ELEMENTS[landmark];
 		const [uncontrolled, setUncontrolled] = React.useState(defaultCollapsed);
 		const collapsed = collapsedProp ?? uncontrolled;
 		const toggle = React.useCallback(() => {
@@ -50,16 +56,21 @@ const Sidebar = {
 		}), [collapsed, toggle]);
 		return /* @__PURE__ */ jsx(SidebarContext.Provider, {
 			value: context,
-			children: /* @__PURE__ */ jsx("aside", {
+			children: /* @__PURE__ */ jsx(Element, {
 				ref,
 				"data-slot": "sidebar",
 				"data-collapsed": collapsed ? "" : void 0,
-				className: cn("group/sidebar relative flex h-full shrink-0 flex-col gap-(--cue-space-4) border-r border-border bg-surface-1 py-(--cue-space-4) transition-[width] duration-150 ease-out motion-reduce:transition-none", className),
+				className: cn("group/sidebar relative flex h-full min-h-0 shrink-0 flex-col border-r border-border bg-surface-1 transition-[width] duration-150 ease-out motion-reduce:transition-none", className),
 				style: {
 					width: collapsed ? collapsedWidth : width,
 					...style
 				},
-				...elementProps
+				...elementProps,
+				children: /* @__PURE__ */ jsx("div", {
+					"data-slot": "sidebar-scroller",
+					className: "flex min-h-0 flex-1 flex-col gap-(--cue-space-4) overflow-y-auto py-(--cue-space-4)",
+					children
+				})
 			})
 		});
 	}),
@@ -88,7 +99,7 @@ const Sidebar = {
 				"data-slot": "sidebar-item",
 				"data-active": active ? "" : void 0,
 				"aria-current": active ? "page" : void 0,
-				className: cn("flex h-control-md w-full cursor-pointer items-center gap-(--cue-space-3) rounded-(--radius-control) border-0 bg-transparent px-(--cue-space-3) text-left font-mono text-(length:--cue-text-ui) text-fg-muted no-underline transition-colors duration-150 outline-none select-none hover:bg-surface-2 hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-1 focus-visible:outline-accent data-[active]:bg-accent-soft data-[active]:text-accent disabled:pointer-events-none disabled:opacity-40", className),
+				className: cn("relative flex h-control-md w-full cursor-pointer items-center gap-(--cue-space-3) rounded-(--radius-control) border-0 bg-transparent px-(--cue-space-3) text-left font-mono text-(length:--cue-text-ui) text-fg-muted no-underline transition-colors duration-150 outline-none select-none hover:bg-surface-2 hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-1 focus-visible:outline-accent data-[active]:bg-accent-soft data-[active]:text-accent disabled:pointer-events-none disabled:opacity-40", className),
 				children: /* @__PURE__ */ jsxs(Fragment, { children: [
 					Icon === void 0 ? null : /* @__PURE__ */ jsx(Icon, {
 						"aria-hidden": "true",

package/dist/midi/spectrum-visualizer.js

@@ -1,8 +1,8 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effect.js";
-import { toRem } from "../instruments/_rem.js";
 import { useComposedRefs } from "../lib/compose.js";
+import { toRem } from "../instruments/_rem.js";
 import { resolveToken } from "../charts/_token.js";
 import { RAMPS } from "../charts/ramps.js";
 import * as React from "react";

package/dist/midi/timeline-ruler.js

@@ -1,7 +1,7 @@
 "use client";
 import { cn } from "../lib/cn.js";
-import { toRem } from "../instruments/_rem.js";
 import { useComposedRefs } from "../lib/compose.js";
+import { toRem } from "../instruments/_rem.js";
 import { DEFAULT_TIME_SIGNATURE, barBeats, beatsToMusical, formatMusicalTime } from "./_time.js";
 import { rulerTicks } from "./_ruler.js";
 import * as React from "react";

package/dist/overlays/command-palette.js

@@ -1,9 +1,9 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { SearchGlyph } from "./_glyphs.js";
 import { useCuePortalProps } from "../system/portal.js";
 import { overlayModalTransitionClasses, overlaySurfaceClasses, scrimClasses } from "./_surface.js";
 import { useDebouncedValue } from "./_debounce.js";
-import { SearchGlyph } from "./_glyphs.js";
 import * as React from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { Combobox } from "@base-ui/react/combobox";

package/dist/overlays/dialog.js

@@ -1,10 +1,10 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { cva } from "../lib/cva.js";
+import { CrossGlyph } from "./_glyphs.js";
 import { useCuePortalProps } from "../system/portal.js";
 import { overlayDescriptionClasses, overlayFooterClasses, overlayModalTransitionClasses, overlaySurfaceClasses, overlayTitleClasses, scrimClasses } from "./_surface.js";
 import { IconButton } from "../primitives/icon-button.js";
-import { CrossGlyph } from "./_glyphs.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Dialog } from "@base-ui/react/dialog";

package/dist/overlays/dropdown-menu.js

@@ -1,9 +1,9 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { useComposedRefs } from "../lib/compose.js";
+import { TickGlyph } from "./_glyphs.js";
 import { useCuePortalProps } from "../system/portal.js";
 import { menuItemClasses, menuLabelClasses, menuPopupClasses, menuSeparatorClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses } from "./_surface.js";
-import { TickGlyph } from "./_glyphs.js";
-import { useComposedRefs } from "../lib/compose.js";
 import { useCloseOnWheel } from "./_wheel.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/overlays/hover-card.js

@@ -1,8 +1,8 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { useComposedRefs } from "../lib/compose.js";
 import { useCuePortalProps } from "../system/portal.js";
 import { overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses } from "./_surface.js";
-import { useComposedRefs } from "../lib/compose.js";
 import { useCloseOnWheel } from "./_wheel.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";

package/dist/overlays/index.js

@@ -1,10 +1,10 @@
 import { OVERLAY_SIDE_OFFSET, menuItemClasses, menuLabelClasses, menuPopupClasses, menuSeparatorClasses, overlayDescriptionClasses, overlayFooterClasses, overlayModalTransitionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTextClasses, overlayTitleClasses, scrimClasses } from "./_surface.js";
+import { Drawer } from "./drawer.js";
 import { AlertDialog } from "./alert-dialog.js";
 import { CommandPalette } from "./command-palette.js";
 import { DropdownMenu } from "./dropdown-menu.js";
 import { ContextMenu } from "./context-menu.js";
 import { Dialog } from "./dialog.js";
-import { Drawer } from "./drawer.js";
 import { HoverCard } from "./hover-card.js";
 import { Tooltip } from "./tooltip.js";
 import { InfoTip } from "./info-tip.js";

package/dist/overlays/popover.js

@@ -1,8 +1,8 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { useComposedRefs } from "../lib/compose.js";
 import { useCuePortalProps } from "../system/portal.js";
 import { overlayDescriptionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTitleClasses } from "./_surface.js";
-import { useComposedRefs } from "../lib/compose.js";
 import { useCloseOnWheel } from "./_wheel.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";

package/dist/overlays/sheet.js

@@ -1,10 +1,10 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { cva } from "../lib/cva.js";
+import { CrossGlyph } from "./_glyphs.js";
 import { useCuePortalProps } from "../system/portal.js";
 import { overlayDescriptionClasses, overlayFooterClasses, overlaySurfaceClasses, overlayTitleClasses, scrimClasses } from "./_surface.js";
 import { IconButton } from "../primitives/icon-button.js";
-import { CrossGlyph } from "./_glyphs.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Dialog } from "@base-ui/react/dialog";

package/dist/overlays/toast.js

@@ -1,8 +1,8 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { CrossGlyph } from "./_glyphs.js";
 import { useCuePortalProps } from "../system/portal.js";
 import { overlaySurfaceClasses } from "./_surface.js";
-import { CrossGlyph } from "./_glyphs.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Toast } from "@base-ui/react/toast";

package/dist/primitives/chip.d.ts

@@ -15,7 +15,7 @@ import * as React from "react";
  * <span className={chipVariants({ tone: "danger", variant: "outline" })}>fault</span>
  */
 declare const chipVariants: (props?: ({
-  tone?: "danger" | "info" | "warn" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
+  tone?: "info" | "warn" | "danger" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
   variant?: "outline" | "tinted" | null | undefined;
   interactive?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;

package/dist/primitives/index.d.ts

@@ -1,10 +1,10 @@
+import { Separator, SeparatorProps } from "./separator.js";
 import { Button, ButtonProps, buttonVariants } from "./button.js";
 import { StatusDot, StatusDotProps, StatusTone } from "./status-dot.js";
 import { Avatar, AvatarGroup, AvatarGroupProps, AvatarProps, AvatarSize } from "./avatar.js";
 import { Chip, ChipProps, chipVariants } from "./chip.js";
 import { IconButton, IconButtonProps } from "./icon-button.js";
 import { Kbd, KbdProps } from "./kbd.js";
-import { Separator, SeparatorProps } from "./separator.js";
 import { Skeleton, SkeletonProps } from "./skeleton.js";
 import { Spinner, SpinnerProps } from "./spinner.js";
 export { Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Button, type ButtonProps, Chip, type ChipProps, IconButton, type IconButtonProps, Kbd, type KbdProps, Separator, type SeparatorProps, Skeleton, type SkeletonProps, Spinner, type SpinnerProps, StatusDot, type StatusDotProps, type StatusTone, buttonVariants, chipVariants };

package/dist/primitives/index.js

@@ -1,10 +1,10 @@
 import { Button, buttonVariants } from "./button.js";
 import { Chip, chipVariants } from "./chip.js";
 import { Spinner } from "./spinner.js";
+import { Separator } from "./separator.js";
 import { IconButton } from "./icon-button.js";
 import { StatusDot } from "./status-dot.js";
 import { Avatar, AvatarGroup } from "./avatar.js";
 import { Kbd } from "./kbd.js";
-import { Separator } from "./separator.js";
 import { Skeleton } from "./skeleton.js";
 export { Avatar, AvatarGroup, Button, Chip, IconButton, Kbd, Separator, Skeleton, Spinner, StatusDot, buttonVariants, chipVariants };

package/dist/primitives/status-dot.d.ts

@@ -32,6 +32,13 @@ interface StatusDotProps extends Omit<React.ComponentPropsWithoutRef<"span">, "c
  * component always emits an `sr-only` label inside a `role="status"` wrapper,
  * so the state is announced as well as shown (WCAG 1.4.1).
  *
+ * The wrapper is `relative` for that label's sake and no other reason.
+ * `.sr-only` is `position: absolute`; without a positioned ancestor its
+ * containing block is the initial one, so its scrollable overflow lands on
+ * `<html>` rather than on whatever scroller it is nested in. One dot is
+ * harmless and a table of two thousand rows is a document several thousand
+ * pixels taller than anything visible on it.
+ *
  * Static markup — no `"use client"`.
  *
  * @example

package/dist/primitives/status-dot.js

@@ -20,6 +20,13 @@ const toRem = (px) => `${px / 16}rem`;
 * component always emits an `sr-only` label inside a `role="status"` wrapper,
 * so the state is announced as well as shown (WCAG 1.4.1).
 *
+* The wrapper is `relative` for that label's sake and no other reason.
+* `.sr-only` is `position: absolute`; without a positioned ancestor its
+* containing block is the initial one, so its scrollable overflow lands on
+* `<html>` rather than on whatever scroller it is nested in. One dot is
+* harmless and a table of two thousand rows is a document several thousand
+* pixels taller than anything visible on it.
+*
 * Static markup — no `"use client"`.
 *
 * @example
@@ -31,7 +38,7 @@ const StatusDot = React.forwardRef(function StatusDot({ className, tone, pulse =
 	return /* @__PURE__ */ jsxs("span", {
 		ref,
 		role: "status",
-		className: cn("inline-flex shrink-0 items-center justify-center", className),
+		className: cn("relative inline-flex shrink-0 items-center justify-center", className),
 		...elementProps,
 		children: [/* @__PURE__ */ jsx("span", {
 			"aria-hidden": "true",

package/dist/styles.css

@@ -14,6 +14,62 @@
 
 @source "./";
 
-@custom-variant density-ultra (&:where([data-density="ultra-compact"], [data-density="ultra-compact"] *));
+/* One variant per rung of the density ladder, each named after the rung it
+ * matches — so `density-large:` means the level a consumer writes as
+ * `density="large"`, and cannot drift from it.
+ *
+ * `density-ultra:` is gone with the five-rung rename of 2026-08-19: with an
+ * `ultra-large` rung in the ladder, "ultra" no longer names one level. Its
+ * replacement is `density-ultra-compact:`. `density-large:` survives the rename
+ * as a name and changes meaning with it — it matched the ladder's top rung
+ * before, and the ladder now has two rungs above that one. */
+@custom-variant density-ultra-compact (&:where([data-density="ultra-compact"], [data-density="ultra-compact"] *));
+@custom-variant density-compact (&:where([data-density="compact"], [data-density="compact"] *));
+@custom-variant density-normal (&:where([data-density="normal"], [data-density="normal"] *));
 @custom-variant density-large (&:where([data-density="large"], [data-density="large"] *));
-@custom-variant mode-light (&:where([data-mode="light"], [data-mode="light"] *));
+@custom-variant density-ultra-large (&:where([data-density="ultra-large"], [data-density="ultra-large"] *));
+@custom-variant mode-light {
+  &:where([data-mode="light"], [data-mode="light"] *) {
+    @slot;
+  }
+
+  @media (prefers-color-scheme: light) {
+    &:where([data-mode="system"], [data-mode="system"] *) {
+      @slot;
+    }
+  }
+}
+
+/* The one keyframe this library's core needs, and the reason it cannot be a
+ * utility: `<Plussie idle />` blinks, and Tailwind has no `animate-*` for a
+ * two-frame squash about an SVG group's own centre.
+ *
+ * Same shape as the pulse in `flow.css`: a bespoke class, the keyframes beside
+ * it, and a `prefers-reduced-motion` block that switches it off. `fill-box`
+ * puts the transform origin at the eye's own centre rather than the SVG's
+ * corner, which is what makes the eye shut across its middle instead of sliding
+ * up. The class does nothing unless the prop asks for it — every other Plussie
+ * on the page is still. */
+@keyframes cue-plussie-blink {
+  0%,
+  93%,
+  100% {
+    transform: scaleY(1);
+  }
+  95.5%,
+  96.5% {
+    transform: scaleY(0.05);
+  }
+}
+
+.cue-plussie-idle {
+  transform-box: fill-box;
+  transform-origin: center;
+  animation: cue-plussie-blink 5.2s ease-in-out infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .cue-plussie-idle {
+    animation: none;
+  }
+}

package/dist/system/density.d.ts

@@ -2,7 +2,10 @@ import * as React from "react";
 import { Density } from "@cueplusplus/tokens";
 //#region src/system/density.d.ts
 interface DensityProps {
-  /** Level to apply to this subtree: `ultra-compact`, `normal` or `large`. */
+  /**
+   * Level to apply to this subtree: `ultra-compact`, `compact`, `normal`,
+   * `large` or `ultra-large`.
+   */
   density: Density;
   /** Subtree that should render at `density`. */
   children: React.ReactNode;

package/dist/system/density.js

@@ -2,13 +2,21 @@
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/system/density.tsx
-/** Density level every unstamped subtree falls back to. */
-const DEFAULT_DENSITY = "normal";
-/** The three levels, as a runtime array for validating persisted input. */
+/**
+* Density level every unstamped subtree falls back to.
+*
+* `compact`, which is the second rung and not the middle one. This is console
+* software: the ladder is symmetric about `normal` for the sake of its names,
+* but the level a screen gets when nobody chose is the dense one.
+*/
+const DEFAULT_DENSITY = "compact";
+/** The five levels, as a runtime array for validating persisted input. */
 const DENSITY_LEVELS = [
 	"ultra-compact",
+	"compact",
 	"normal",
-	"large"
+	"large",
+	"ultra-large"
 ];
 /**
 * Nearest ambient density. `null` means "nothing has stamped a level yet", which

package/dist/system/index.d.ts

@@ -1,8 +1,8 @@
-import { ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps } from "./theme-provider.js";
+import { FontFamilies, ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps } from "./theme-provider.js";
 import { Density, DensityProps } from "./density.js";
 import { CuePortalFrame, CuePortalFrameProps, useCuePortalProps } from "./portal.js";
-import { DEFAULT_STORAGE_KEY, PersistedPreferences, prepaintScript } from "./prepaint.js";
+import { DEFAULT_STORAGE_KEY, PersistedPreferences, PrepaintDefaults, PrepaintOptions, prepaintScript } from "./prepaint.js";
 import { ControlSize, useControlHeight, useDensity } from "./use-density.js";
 import { useTheme } from "./use-theme.js";
-import { Density as DensityLevel, Mode, ThemeName } from "@cueplusplus/tokens";
-export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, Density, type DensityLevel, type DensityProps, type Mode, type PersistedPreferences, type ResolvedMode, type ThemeContextValue, type ThemeName, ThemeProvider, type ThemeProviderProps, prepaintScript, useControlHeight, useCuePortalProps, useDensity, useTheme };
+import { Density as DensityLevel, FontName, Mode, ThemeName } from "@cueplusplus/tokens";
+export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, Density, type DensityLevel, type DensityProps, type FontFamilies, type FontName, type Mode, type PersistedPreferences, type PrepaintDefaults, type PrepaintOptions, type ResolvedMode, type ThemeContextValue, type ThemeName, ThemeProvider, type ThemeProviderProps, prepaintScript, useControlHeight, useCuePortalProps, useDensity, useTheme };

package/dist/system/portal.d.ts

@@ -2,11 +2,11 @@ import * as React from "react";
 //#region src/system/portal.d.ts
 /**
  * Props to spread onto a Base UI `Portal` part so the portal root inherits the
- * caller's theme, density and mode.
+ * caller's theme, density, font pairing and mode.
  *
  * Returns a `container` element appended to `document.body` and stamped with
- * `data-theme` / `data-density` / `data-mode` (plus `--cue-font-scale`) copied
- * from the nearest provider and density island. The container is
+ * `data-theme` / `data-density` / `data-font` / `data-mode` (plus
+ * `--cue-font-scale`) copied from the nearest provider and density island. The container is
  * `display: contents`, so it changes no layout and creates no containing block —
  * fixed-position overlay content behaves exactly as if it were a direct child of
  * `<body>`.
@@ -38,8 +38,8 @@ interface CuePortalFrameProps {
  * chosen (a third-party overlay, or content already portaled by something else).
  *
  * Wraps `children` in a `display: contents` element carrying the same
- * `data-theme` / `data-density` / `data-mode` triple and `--cue-font-scale` as
- * {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
+ * `data-theme` / `data-density` / `data-font` / `data-mode` stamp and
+ * `--cue-font-scale` as {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
  * element per overlay instead of one per render tree — and reach for this only
  * when the container prop is not available.
  *

package/dist/system/portal.js

@@ -1,14 +1,17 @@
 "use client";
 import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
 import { DensityContext } from "./density.js";
-import { FontScaleContext, ThemeContext } from "./theme-provider.js";
+import { FontFamiliesContext, FontScaleContext, ThemeContext } from "./theme-provider.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
+import { DEFAULT_FONT } from "@cueplusplus/tokens";
 //#region src/system/portal.tsx
 const DEFAULT_THEME = "cue";
-const DEFAULT_RESOLVED_MODE = "dark";
+const DEFAULT_MODE = "dark";
 /** Custom property the density text ladder multiplies by; see `FontScaleContext`. */
 const FONT_SCALE_PROPERTY = "--cue-font-scale";
+const FONT_SANS_PROPERTY = "--cue-font-sans";
+const FONT_MONO_PROPERTY = "--cue-font-mono";
 /**
 * Read the stamp from React context — never from the DOM. A portal is mounted
 * outside its owner's DOM subtree, so `getComputedStyle`-style discovery would
@@ -21,20 +24,23 @@ function usePortalStamp() {
 	const theme = React.useContext(ThemeContext);
 	const island = React.useContext(DensityContext);
 	const fontScale = React.useContext(FontScaleContext);
+	const fontFamilies = React.useContext(FontFamiliesContext);
 	return {
 		theme: theme?.theme ?? DEFAULT_THEME,
-		density: island ?? theme?.density ?? "normal",
-		mode: theme?.resolvedMode ?? DEFAULT_RESOLVED_MODE,
-		fontScale
+		density: island ?? theme?.density ?? "compact",
+		mode: theme?.mode ?? DEFAULT_MODE,
+		font: theme?.font ?? DEFAULT_FONT,
+		fontScale,
+		fontFamilies
 	};
 }
 /**
 * Props to spread onto a Base UI `Portal` part so the portal root inherits the
-* caller's theme, density and mode.
+* caller's theme, density, font pairing and mode.
 *
 * Returns a `container` element appended to `document.body` and stamped with
-* `data-theme` / `data-density` / `data-mode` (plus `--cue-font-scale`) copied
-* from the nearest provider and density island. The container is
+* `data-theme` / `data-density` / `data-font` / `data-mode` (plus
+* `--cue-font-scale`) copied from the nearest provider and density island. The container is
 * `display: contents`, so it changes no layout and creates no containing block —
 * fixed-position overlay content behaves exactly as if it were a direct child of
 * `<body>`.
@@ -75,8 +81,11 @@ function useCuePortalProps() {
 		container,
 		stamp.theme,
 		stamp.density,
+		stamp.font,
 		stamp.mode,
-		stamp.fontScale
+		stamp.fontScale,
+		stamp.fontFamilies?.sans,
+		stamp.fontFamilies?.mono
 	]);
 	return React.useMemo(() => container === null ? {} : { container }, [container]);
 }
@@ -84,17 +93,24 @@ function useCuePortalProps() {
 function applyStamp(element, stamp) {
 	element.setAttribute("data-theme", stamp.theme);
 	element.setAttribute("data-density", stamp.density);
+	element.setAttribute("data-font", stamp.font);
 	element.setAttribute("data-mode", stamp.mode);
 	if (stamp.fontScale === null) element.style.removeProperty(FONT_SCALE_PROPERTY);
 	else element.style.setProperty(FONT_SCALE_PROPERTY, String(stamp.fontScale));
+	setOptionalProperty(element, FONT_SANS_PROPERTY, stamp.fontFamilies?.sans);
+	setOptionalProperty(element, FONT_MONO_PROPERTY, stamp.fontFamilies?.mono);
+}
+function setOptionalProperty(element, property, value) {
+	if (value === void 0) element.style.removeProperty(property);
+	else element.style.setProperty(property, value);
 }
 /**
 * Inline version of the portal contract, for portals whose container cannot be
 * chosen (a third-party overlay, or content already portaled by something else).
 *
 * Wraps `children` in a `display: contents` element carrying the same
-* `data-theme` / `data-density` / `data-mode` triple and `--cue-font-scale` as
-* {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
+* `data-theme` / `data-density` / `data-font` / `data-mode` stamp and
+* `--cue-font-scale` as {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
 * element per overlay instead of one per render tree — and reach for this only
 * when the container prop is not available.
 *
@@ -106,12 +122,15 @@ function CuePortalFrame({ children, className, style }) {
 	const frameStyle = {
 		display: "contents",
 		...stamp.fontScale === null ? null : { [FONT_SCALE_PROPERTY]: stamp.fontScale },
+		...stamp.fontFamilies?.sans === void 0 ? null : { [FONT_SANS_PROPERTY]: stamp.fontFamilies.sans },
+		...stamp.fontFamilies?.mono === void 0 ? null : { [FONT_MONO_PROPERTY]: stamp.fontFamilies.mono },
 		...style
 	};
 	return /* @__PURE__ */ jsx("div", {
 		"data-cue-portal": "",
 		"data-theme": stamp.theme,
 		"data-density": stamp.density,
+		"data-font": stamp.font,
 		"data-mode": stamp.mode,
 		className,
 		style: frameStyle,

package/dist/system/prepaint.d.ts

@@ -1,4 +1,4 @@
-import { ThemeName } from "@cueplusplus/tokens";
+import { Density, FontName, Mode, ThemeName } from "@cueplusplus/tokens";
 //#region src/system/prepaint.d.ts
 /** localStorage key the ThemeProvider and the pre-paint script share by default. */
 declare const DEFAULT_STORAGE_KEY = "cue-ui";
@@ -10,17 +10,36 @@ interface PersistedPreferences {
   density?: string;
   /** Last mode the user picked, including the literal `"system"`. */
   mode?: string;
+  /** Last font pairing the user picked. */
+  font?: string;
+}
+/** Complete server-authoritative fallback stamped when storage is absent or ignored. */
+interface PrepaintDefaults {
+  theme: ThemeName;
+  density: Density;
+  mode: Mode;
+  /** Initial document-wide font pairing. Defaults to the token package's system pairing. */
+  font?: FontName;
+}
+/** Options form for apps whose server projection, not localStorage, owns first paint. */
+interface PrepaintOptions {
+  /** localStorage key shared with ThemeProvider. */
+  storageKey?: string;
+  /** Complete validated fallback triple. */
+  defaults: PrepaintDefaults;
+  /** Whether valid stored axes may override `defaults`. Defaults to `true`. */
+  readStoredPreferences?: boolean;
 }
 /**
  * Build the blocking inline script that stamps `data-theme`, `data-density`,
- * `data-mode` and `color-scheme` on `<html>` from localStorage before the first
- * paint.
+ * `data-font`, `data-mode` and `color-scheme` on `<html>` from localStorage
+ * before the first paint.
  *
  * Render it as `<script dangerouslySetInnerHTML={{ __html: prepaintScript() }} />`
  * in `<head>`, above everything else. The output never contains `</script>` and
  * never throws: private-mode localStorage failures degrade to the dark-first
- * defaults (`cue` / `normal` / `dark`), which are also what bare `:root` in
- * `@cueplusplus/tokens/theme.css` already paints.
+ * defaults (`cue` / `compact` / `system` / `dark`), which are also what bare
+ * `:root` in `@cueplusplus/tokens/theme.css` already paints.
  *
  * @param storageKey - localStorage key to read. Must match the `storageKey`
  *   passed to `<ThemeProvider>`. Defaults to {@link DEFAULT_STORAGE_KEY}.
@@ -28,11 +47,17 @@ interface PersistedPreferences {
  *   Must match the `theme` passed to `<ThemeProvider>`, or the first paint
  *   dresses `<html>` in one preset while the app renders in another. Defaults to
  *   `"cue"`.
+ * @param defaultDensity - Density level to stamp for a visitor with nothing
+ *   persisted yet. Same rule as `defaultTheme`: it must match the `density`
+ *   passed to `<ThemeProvider>` or the first frame is drawn at one rung and
+ *   every frame after it at another. Defaults to `"compact"`, the library's own
+ *   fallback, which is what an app that passes no `density` renders at.
  * @returns One line of JavaScript, safe to inline verbatim.
  * @example
- * // An app whose provider is <ThemeProvider theme="terminal">:
- * prepaintScript(DEFAULT_STORAGE_KEY, "terminal");
+ * // An app whose provider is <ThemeProvider theme="terminal" density="normal">:
+ * prepaintScript(DEFAULT_STORAGE_KEY, "terminal", "normal");
  */
-declare function prepaintScript(storageKey?: string, defaultTheme?: ThemeName): string;
+declare function prepaintScript(storageKey?: string, defaultTheme?: ThemeName, defaultDensity?: Density, defaultFont?: FontName): string;
+declare function prepaintScript(options: PrepaintOptions): string;
 //#endregion
-export { DEFAULT_STORAGE_KEY, PersistedPreferences, prepaintScript };
+export { DEFAULT_STORAGE_KEY, PersistedPreferences, PrepaintDefaults, PrepaintOptions, prepaintScript };