@cueplusplus/ui 0.2.0 → 0.3.0

package/dist/system/theme-provider.js

@@ -5,9 +5,9 @@ import { DEFAULT_DENSITY as DEFAULT_DENSITY$1, DENSITY_LEVELS, DensityContext }
 import { DEFAULT_STORAGE_KEY } from "./prepaint.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
-import { DEFAULT_FONT, FONTS } from "@cueplusplus/tokens";
+import { DEFAULT_FONT, FONTS, THEMES } from "@cueplusplus/tokens";
 //#region src/system/theme-provider.tsx
-const MODES = [
+const MODES$1 = [
 	"dark",
 	"light",
 	"system"
@@ -34,6 +34,8 @@ const ThemeContext = React.createContext(null);
 * Internal: not part of the public API.
 */
 const FontScaleContext = React.createContext(null);
+/** Effective font-family overrides from the nearest provider chain. */
+const FontFamiliesContext = React.createContext(null);
 function isOneOf(allowed, value) {
 	return typeof value === "string" && allowed.includes(value);
 }
@@ -84,14 +86,14 @@ function writePreferences(storageKey, preferences) {
 *   <App />
 * </ThemeProvider>
 */
-function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp = DEFAULT_DENSITY$1, mode: modeProp = DEFAULT_MODE, font: fontProp = DEFAULT_FONT, fontScale = 1, storageKey = DEFAULT_STORAGE_KEY, asChild = false, className, style: styleProp, children }) {
+function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp = DEFAULT_DENSITY$1, mode: modeProp = DEFAULT_MODE, font: fontProp = DEFAULT_FONT, fontScale = 1, fontFamilies, storageKey = DEFAULT_STORAGE_KEY, persistPreferences = true, asChild = false, className, style: styleProp, children }) {
 	const ambient = React.useContext(ThemeContext);
 	const isRoot = ambient === null;
 	const [theme, setThemeState] = React.useState(themeProp);
 	const [density, setDensityState] = React.useState(densityProp);
 	const [mode, setModeState] = React.useState(modeProp);
 	const [rootFont, setRootFontState] = React.useState(() => {
-		if (!isRoot) return fontProp;
+		if (!isRoot || !persistPreferences) return fontProp;
 		const stored = readPreferences(storageKey).font;
 		return isOneOf(FONT_NAMES, stored) ? stored : fontProp;
 	});
@@ -101,15 +103,24 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 	const restoredKey = React.useRef(null);
 	const [restored, setRestored] = React.useState(false);
 	useIsomorphicLayoutEffect(() => {
-		if (!isRoot || restoredKey.current === storageKey) return;
+		if (!isRoot) return;
+		if (!persistPreferences) {
+			setRestored(true);
+			return;
+		}
+		if (restoredKey.current === storageKey) return;
 		restoredKey.current = storageKey;
 		setRestored(true);
 		const stored = readPreferences(storageKey);
-		if (typeof stored.theme === "string" && stored.theme.length > 0) setThemeState(stored.theme);
+		if (isOneOf(THEMES, stored.theme)) setThemeState(stored.theme);
 		if (isOneOf(DENSITY_LEVELS, stored.density)) setDensityState(stored.density);
 		if (isOneOf(FONT_NAMES, stored.font)) setRootFontState(stored.font);
-		if (isOneOf(MODES, stored.mode)) setModeState(stored.mode);
-	}, [isRoot, storageKey]);
+		if (isOneOf(MODES$1, stored.mode)) setModeState(stored.mode);
+	}, [
+		isRoot,
+		persistPreferences,
+		storageKey
+	]);
 	const lastProps = React.useRef({
 		theme: themeProp,
 		density: densityProp,
@@ -162,9 +173,13 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 			...patch
 		};
 		stateRef.current = next;
-		if (!isRoot) return;
+		if (!isRoot || !persistPreferences) return;
 		writePreferences(storageKey, next);
-	}, [isRoot, storageKey]);
+	}, [
+		isRoot,
+		persistPreferences,
+		storageKey
+	]);
 	const setTheme = React.useCallback((next) => {
 		setThemeState(next);
 		persist({ theme: next });
@@ -197,15 +212,15 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		root.setAttribute("data-theme", theme);
 		root.setAttribute("data-density", density);
 		root.setAttribute("data-font", font);
-		root.setAttribute("data-mode", resolvedMode);
-		root.style.colorScheme = resolvedMode;
+		root.setAttribute("data-mode", mode);
+		root.style.colorScheme = mode === "system" ? "light dark" : mode;
 	}, [
 		isRoot,
 		restored,
 		theme,
 		density,
 		font,
-		resolvedMode
+		mode
 	]);
 	React.useEffect(() => () => {
 		const original = originalStamp.current;
@@ -243,20 +258,38 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		setMode,
 		setFont
 	]);
+	const parentFontFamilies = React.useContext(FontFamiliesContext);
+	const effectiveFontFamilies = React.useMemo(() => {
+		const sans = fontFamilies?.sans ?? parentFontFamilies?.sans;
+		const mono = fontFamilies?.mono ?? parentFontFamilies?.mono;
+		return sans === void 0 && mono === void 0 ? null : {
+			sans,
+			mono
+		};
+	}, [
+		fontFamilies?.sans,
+		fontFamilies?.mono,
+		parentFontFamilies?.sans,
+		parentFontFamilies?.mono
+	]);
 	const style = React.useMemo(() => ({
-		colorScheme: resolvedMode,
+		colorScheme: mode === "system" ? "light dark" : mode,
 		"--cue-font-scale": fontScale,
+		...fontFamilies?.sans === void 0 ? null : { "--cue-font-sans": fontFamilies.sans },
+		...fontFamilies?.mono === void 0 ? null : { "--cue-font-mono": fontFamilies.mono },
 		...styleProp
 	}), [
-		resolvedMode,
+		mode,
 		fontScale,
+		fontFamilies?.sans,
+		fontFamilies?.mono,
 		styleProp
 	]);
 	const stamp = {
 		"data-cue-root": "",
 		"data-theme": theme,
 		"data-density": density,
-		"data-mode": resolvedMode
+		"data-mode": mode
 	};
 	let root;
 	if (asChild) {
@@ -279,12 +312,15 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		value: contextValue,
 		children: /* @__PURE__ */ jsx(FontScaleContext.Provider, {
 			value: fontScale,
-			children: /* @__PURE__ */ jsx(DensityContext.Provider, {
-				value: density,
-				children: root
+			children: /* @__PURE__ */ jsx(FontFamiliesContext.Provider, {
+				value: effectiveFontFamilies,
+				children: /* @__PURE__ */ jsx(DensityContext.Provider, {
+					value: density,
+					children: root
+				})
 			})
 		})
 	});
 }
 //#endregion
-export { FontScaleContext, ThemeContext, ThemeProvider };
+export { FontFamiliesContext, FontScaleContext, ThemeContext, ThemeProvider };

package/dist/theming/_presets.js

@@ -454,6 +454,59 @@ const THEME_PRESETS = {
 		},
 		fonts: { "font-mono": "\"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" }
 	},
+	requestport: {
+		dark: {
+			"bg": "#0a0d0e",
+			"sunken": "#07090a",
+			"surface-1": "#101416",
+			"surface-2": "#151a1d",
+			"surface-3": "#1a2024",
+			"fg": "#f0eee9",
+			"fg-muted": "#a3a6a8",
+			"fg-subtle": "#81868a",
+			"border": "#293034",
+			"border-strong": "#61686d",
+			"border-overlay": "#3f484e",
+			"accent": "#e66a45",
+			"accent-hover": "#f07a53",
+			"accent-fg": "#160d09",
+			"ok": "#63b482",
+			"busy": "#9a8cdb",
+			"warn": "#d6a65a",
+			"danger": "#dc6d69",
+			"info": "#6eb7d9",
+			"selection": "rgba(230,106,69,0.18)",
+			"focus": "#e66a45",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.72)"
+		},
+		light: {
+			"bg": "#f4f3ef",
+			"sunken": "#e7e6e1",
+			"surface-1": "#faf9f6",
+			"surface-2": "#ffffff",
+			"surface-3": "#deddd8",
+			"fg": "#1a1d1e",
+			"fg-muted": "#53595c",
+			"fg-subtle": "#62696d",
+			"border": "#d0d2cf",
+			"border-strong": "#7f8689",
+			"border-overlay": "#aeb4b5",
+			"accent": "#b8492b",
+			"accent-hover": "#963b23",
+			"accent-fg": "#ffffff",
+			"ok": "#247746",
+			"busy": "#604aaa",
+			"warn": "#8a5b00",
+			"danger": "#aa2f2b",
+			"info": "#1d6587",
+			"selection": "rgba(184,73,43,0.18)",
+			"focus": "#b8492b",
+			"data-ground": "#000000",
+			"scrim": "rgba(20,18,15,0.45)"
+		},
+		fonts: { "font-mono": "\"Geist Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" }
+	},
 	quotamate: {
 		dark: {
 			"bg": "#0e0e12",

package/dist/theming/create-theme.d.ts

@@ -30,7 +30,7 @@ declare const DEFAULT_THEME_BASE: ThemeName;
 /**
  * How far the sunken ground sits below the page, in oklch lightness.
  *
- * Small on purpose: sunken is a well, not a second theme. Across the eight
+ * Small on purpose: sunken is a well, not a second theme. Across the ten
  * shipped presets the authored gap runs −0.011 to −0.031.
  */
 declare const SUNKEN_LIGHTNESS_STEP = -0.02;
@@ -75,7 +75,7 @@ declare const ACCENT_FG_MINIMUM = 4.5;
  * extreme rather than to the arithmetic mirror: `1 − L` of a 0.16 near-black is a
  * 0.84 mid-grey, which is not a page. Compressing instead maps the ladder of
  * dark grounds onto a narrow paper band — a deeper dark theme gets a cleaner
- * white page — and lands within 0.01 of all eight authored light presets.
+ * white page — and lands within 0.01 of all ten authored light presets.
  */
 declare const LIGHT_GROUND_COMPRESSION = 0.1;
 interface ThemeAnchors {

package/dist/theming/create-theme.js

@@ -1,7 +1,7 @@
 import { formatColorString } from "../color/_convert.js";
 import { BASE_FONT_STACKS, DEFAULT_DENSITY_LEVEL, DENSITY_RADIUS_SCALE, RESOLVED_MONO, THEME_COLOR_TOKENS, THEME_PRESETS } from "./_presets.js";
 import { WCAG_AA_TEXT, contrastRatio, contrastReport } from "./contrast.js";
-import { assertCssValue, assertThemeName, derivedTokens, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
+import { assertCssValue, assertThemeName, derivedTokens, serializeSystemModeAliases, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
 import { clampChroma, converter, formatHex, inGamut, parse } from "culori";
 //#region src/theming/create-theme.ts
 /**
@@ -32,7 +32,7 @@ const DEFAULT_THEME_BASE = "cue";
 /**
 * How far the sunken ground sits below the page, in oklch lightness.
 *
-* Small on purpose: sunken is a well, not a second theme. Across the eight
+* Small on purpose: sunken is a well, not a second theme. Across the ten
 * shipped presets the authored gap runs −0.011 to −0.031.
 */
 const SUNKEN_LIGHTNESS_STEP = -.02;
@@ -81,7 +81,7 @@ const ACCENT_FG_MINIMUM = WCAG_AA_TEXT;
 * extreme rather than to the arithmetic mirror: `1 − L` of a 0.16 near-black is a
 * 0.84 mid-grey, which is not a page. Compressing instead maps the ladder of
 * dark grounds onto a narrow paper band — a deeper dark theme gets a cleaner
-* white page — and lands within 0.01 of all eight authored light presets.
+* white page — and lands within 0.01 of all ten authored light presets.
 */
 const LIGHT_GROUND_COMPRESSION = .1;
 /** Lightness a derived light colour steps down by while hunting for contrast. */
@@ -400,7 +400,7 @@ function createTheme(anchors) {
 	const derived = Object.entries(derivedTokens());
 	const fonts = resolveFonts(anchors, preset.fonts);
 	const radius = anchors.radiusScale === void 0 ? null : radiusBlocks(name, anchors.radiusScale);
-	const darkSections = [
+	const darkPaletteSections = [
 		{ declarations: colorDeclarations(dark.colors) },
 		{
 			comment: DERIVED_COMMENT,
@@ -409,25 +409,26 @@ function createTheme(anchors) {
 		{
 			comment: FONT_COMMENT,
 			declarations: fonts
-		},
-		...radius === null ? [] : [{
-			comment: SHAPE_COMMENT,
-			declarations: radius.base
-		}]
+		}
 	];
+	const darkSections = [...darkPaletteSections, ...radius === null ? [] : [{
+		comment: SHAPE_COMMENT,
+		declarations: radius.base
+	}]];
+	const lightSections = light === null ? null : [{ declarations: colorDeclarations(light.colors) }, {
+		comment: DERIVED_COMMENT,
+		declarations: derived
+	}];
 	const blocks = [
 		{
 			selector: themeSelector(name),
 			colorScheme: "dark",
 			sections: darkSections
 		},
-		...light === null ? [] : [{
+		...lightSections === null ? [] : [{
 			selector: themeSelector(name, { mode: "light" }),
 			colorScheme: "light",
-			sections: [{ declarations: colorDeclarations(light.colors) }, {
-				comment: DERIVED_COMMENT,
-				declarations: derived
-			}]
+			sections: lightSections
 		}],
 		...radius?.blocks ?? []
 	];
@@ -441,7 +442,15 @@ function createTheme(anchors) {
 	}]];
 	return {
 		name,
-		css: serializeThemeCss(blocks, { banner: `@cueplusplus/ui — theme "${name}"` }),
+		css: `${serializeThemeCss(blocks, { banner: `@cueplusplus/ui — theme "${name}"` }).trimEnd()}\n\n${serializeSystemModeAliases(name, [{
+			mode: "dark",
+			colorScheme: "light dark",
+			sections: darkPaletteSections
+		}, {
+			mode: "light",
+			colorScheme: "light dark",
+			sections: lightSections ?? darkPaletteSections
+		}])}\n`,
 		tokens: Object.fromEntries(darkSections.flatMap((section) => section.declarations)),
 		light: light === null ? null : Object.fromEntries([...colorDeclarations(light.colors), ...derived]),
 		report: contrastReport(inputs)

package/dist/theming/serialize.d.ts

@@ -110,7 +110,7 @@ interface ThemeBlock {
   /** The selector the rule declares under. */
   selector: string;
   /** Emitted as `color-scheme`, ahead of the custom properties. Omit to skip it. */
-  colorScheme?: "dark" | "light";
+  colorScheme?: "dark" | "light" | "light dark";
   /** The declarations, grouped into commented sections. */
   sections: readonly ThemeBlockSection[];
 }

package/dist/theming/serialize.js

@@ -148,6 +148,30 @@ function serializeThemeBlock(block) {
 	}
 	return `${block.selector} {\n${lines.join("\n")}\n}`;
 }
+/** Indent a complete rule once so it can live inside an at-rule. */
+function indentRule(rule) {
+	return rule.split("\n").map((line) => `  ${line}`).join("\n");
+}
+/**
+* Alias resolved dark/light palettes onto the preserved logical `system` mode.
+*
+* Both `createTheme()` and the configurator call this function. Keeping the
+* selector and media-query spelling here prevents exported overrides from
+* drifting away from generated custom themes.
+*
+* @internal Used by package-owned theme serializers; not part of the public
+* `@cueplusplus/ui/theming` barrel.
+*/
+function serializeSystemModeAliases(theme, aliases) {
+	const name = assertThemeName(theme);
+	return aliases.map(({ mode, colorScheme, sections }) => {
+		return `@media (prefers-color-scheme: ${mode}) {\n${indentRule(serializeThemeBlock({
+			selector: `[data-theme="${name}"][data-mode="system"]`,
+			colorScheme,
+			sections
+		}))}\n}`;
+	}).join("\n\n");
+}
 /**
 * A whole generated stylesheet: banner, then one rule per block.
 *
@@ -162,4 +186,4 @@ function serializeThemeCss(blocks, options = {}) {
 	return `${[...options.banner === void 0 ? [] : [`/*! ${options.banner}\n * Generated by createTheme(). Do not edit by hand.\n */`], ...rules].join("\n\n")}\n`;
 }
 //#endregion
-export { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, THEME_NAME_PATTERN, assertCssValue, assertThemeName, derivedTokens, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };
+export { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, THEME_NAME_PATTERN, assertCssValue, assertThemeName, derivedTokens, serializeSystemModeAliases, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };

package/manifest/components/accordion.json

@@ -0,0 +1,154 @@
+{
+  "name": "Accordion",
+  "slug": "accordion",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A stack of sections, one (or several) open at a time.\n\nWraps Base UI's `Accordion`, so the disclosure ARIA, keyboard handling and\nopen-state bookkeeping are the primitive's. This layer adds the console skin:\nhairline separation, mono summary rows on the control ladder, and a height\ntransition that respects `prefers-reduced-motion`.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Item",
+    "Header",
+    "Trigger",
+    "Panel"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Accordion.Root",
+      "description": "Groups the sections and owns which of them are open.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the accordion frame."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAccordion.Root.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Item",
+      "usage": "Accordion.Item",
+      "description": "One section.\n\nSeparation is a hairline the section draws above itself, dropped on the first\none — so a stack shows rules *between* sections and none against the rim of\nwhatever contains them. Same rule as `Row`, for the same reason.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the section."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAccordion.Item.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Header",
+      "usage": "Accordion.Header",
+      "description": "The heading that labels a section's panel. An `<h3>` with no type of its own.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the heading."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAccordion.Header.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "Accordion.Trigger",
+      "description": "The summary row that opens a section.\n\nA mono row on the control ladder, padded to the same gutters as a `Row`, with\na caret that rotates off the trigger's own `data-panel-open` — nothing in\nReact has to know the section is open for the arrow to turn.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the summary row."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAccordion.Trigger.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Panel",
+      "usage": "Accordion.Panel",
+      "description": "A section's body.\n\nHeight is animated from `--accordion-panel-height`, which Base UI measures.\nThe animating element carries no padding — padding is part of the box height,\nso it would be counted into the `0 → measured` transition and make the panel\njump at both ends — hence the inner body element.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the animating box. Padding belongs on `bodyClassName`."
+        },
+        {
+          "name": "bodyClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the padded body inside it."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAccordion.Panel.Props, \"className\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-md",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-pad-row-x",
+    "--cue-space-1",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-text-ui"
+  ],
+  "summary": "A stack of sections, one (or several) open at a time.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Accordion.Root>\n  <Accordion.Item value=\"routing\">\n    <Accordion.Header><Accordion.Trigger>routing</Accordion.Trigger></Accordion.Header>\n    <Accordion.Panel>…</Accordion.Panel>\n  </Accordion.Item>\n</Accordion.Root>\n<Accordion.Root multiple defaultValue={[\"routing\"]}>…</Accordion.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/accordion",
+  "mdUrl": "/docs/components/accordion.md",
+  "jsonUrl": "/r/components/accordion.json",
+  "specimens": [
+    {
+      "title": "Accordion",
+      "group": "layout",
+      "components": [
+        "Accordion"
+      ],
+      "code": "<Accordion.Root className=\"w-full max-w-[36rem]\" defaultValue={[\"patch\"]}>\n  <Accordion.Item value=\"patch\">\n    <Accordion.Header>\n      <Accordion.Trigger>Patch</Accordion.Trigger>\n    </Accordion.Header>\n    <Accordion.Panel>48 fixtures across 4 universes.</Accordion.Panel>\n  </Accordion.Item>\n  <Accordion.Item value=\"cues\">\n    <Accordion.Header>\n      <Accordion.Trigger>Cues</Accordion.Trigger>\n    </Accordion.Header>\n    <Accordion.Panel>12 cues, last edited 4 minutes ago.</Accordion.Panel>\n  </Accordion.Item>\n  <Accordion.Item value=\"network\" disabled>\n    <Accordion.Header>\n      <Accordion.Trigger>Network</Accordion.Trigger>\n    </Accordion.Header>\n    <Accordion.Panel>Art-Net on 10.0.0.42.</Accordion.Panel>\n  </Accordion.Item>\n</Accordion.Root>",
+      "note": "Hairline-separated items with mono summary rows. Several can be open at once.",
+      "interaction": "the whole header row is the trigger; the panel animates its height and stills under prefers-reduced-motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-pile.json

@@ -0,0 +1,116 @@
+{
+  "name": "AgentPile",
+  "slug": "agent-pile",
+  "group": "chat",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The roster of agents working on a thread, stacked into one object.\n\nThree states ride on each avatar, and none of them is colour-only: the\norchestrator wears a crown, a working agent gets a spinning arc, and an agent\nwaiting on the user gets a `?` badge — each of them also spelled into the\navatar's accessible name, so a screen reader hears \"Researcher · working\"\nrather than nothing at all.\n\nAvatars are outlined in the agent's colour rather than filled with it. A fill\nwould put arbitrary-hue ink on an arbitrary-hue ground at 20px; the outline\ntreatment is the same tinted-chip recipe the rest of the system uses and\nstays legible on every theme.",
+  "props": [
+    {
+      "name": "agents",
+      "type": "readonly AgentPileEntry[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The roster, in the order it should read. Renders nothing when empty."
+    },
+    {
+      "name": "root",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the orchestrator: takes the theme accent and wears the crown."
+    },
+    {
+      "name": "selected",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the lane currently open — that avatar gets a ring."
+    },
+    {
+      "name": "onSelect",
+      "type": "((slug: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with a slug when an avatar is pressed. Omit for a read-only pile."
+    },
+    {
+      "name": "max",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Show at most this many; the rest collapse into a `+N` chip."
+    },
+    {
+      "name": "fanned",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Force the fan open or shut. Omit to let hover and focus decide."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the group. Required in practice — name the roster."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onSelect\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The roster of agents working on a thread, stacked into one object.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<AgentPile aria-label=\"Agents\" agents={roster} root=\"chief\" onSelect={openLane} />\n<AgentPile aria-label=\"Agents\" agents={roster} max={5} fanned />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-pile",
+  "mdUrl": "/docs/components/agent-pile.md",
+  "jsonUrl": "/r/components/agent-pile.json",
+  "specimens": [
+    {
+      "title": "AgentPile",
+      "group": "chat",
+      "components": [
+        "AgentPile"
+      ],
+      "code": "<Specimens>\n  {([\"sm\", \"md\", \"lg\"] as const).map((size) => (\n    <Specimen key={size} label={size}>\n      <AgentPile agents={AGENTS} root=\"orchestrator\" size={size} />\n    </Specimen>\n  ))}\n  <Specimen label=\"max 4\">\n    <AgentPile agents={AGENTS} root=\"orchestrator\" max={4} />\n  </Specimen>\n  <Specimen label=\"not fanned\">\n    <AgentPile agents={AGENTS} root=\"orchestrator\" fanned={false} />\n  </Specimen>\n  <Specimen label=\"selected\">\n    <AgentPile agents={AGENTS} root=\"orchestrator\" selected=\"patcher\" />\n  </Specimen>\n</Specimens>",
+      "note": "Faces at −12px overlap, fanning to +4px on hover. The crown marks the orchestrator, an arc marks work in flight and a `?` marks an agent waiting on an answer.",
+      "interaction": "every face is a button with the agent's name; the pile is one tab stop and arrow keys move inside it."
+    }
+  ],
+  "todo": true
+}