@cueplusplus/ui 0.1.0 → 0.3.0

package/dist/theming/_presets.js

@@ -453,6 +453,112 @@ const THEME_PRESETS = {
 			"scrim": "rgba(0,0,0,0.35)"
 		},
 		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",
+			"sunken": "#09090c",
+			"surface-1": "#15151a",
+			"surface-2": "#212127",
+			"surface-3": "#2b2b31",
+			"fg": "#f4f4f6",
+			"fg-muted": "#8b8b95",
+			"fg-subtle": "#62626b",
+			"border": "#2b2b31",
+			"border-strong": "#3d3d45",
+			"border-overlay": "#3d3d45",
+			"accent": "#00e5e5",
+			"accent-hover": "#33ffff",
+			"accent-fg": "#0e0e12",
+			"ok": "#22d967",
+			"busy": "#00e5e5",
+			"warn": "#ffab1a",
+			"danger": "#e13d3d",
+			"info": "#4a9eff",
+			"selection": "rgba(0,229,229,0.18)",
+			"focus": "#00e5e5",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.55)"
+		},
+		light: {
+			"bg": "#fcfcfd",
+			"sunken": "#f1f1f4",
+			"surface-1": "#ffffff",
+			"surface-2": "#f4f4f6",
+			"surface-3": "#e7e7ec",
+			"fg": "#18181b",
+			"fg-muted": "#6e6e78",
+			"fg-subtle": "#9a9aa4",
+			"border": "#e2e2e8",
+			"border-strong": "#c9c9d2",
+			"border-overlay": "#c9c9d2",
+			"accent": "#0d7d7d",
+			"accent-hover": "#0a6767",
+			"accent-fg": "#ffffff",
+			"ok": "#17914a",
+			"busy": "#0d7d7d",
+			"warn": "#b46a00",
+			"danger": "#c22d2d",
+			"info": "#1f6fd4",
+			"selection": "rgba(13,125,125,0.16)",
+			"focus": "#0d7d7d",
+			"data-ground": "#ffffff",
+			"scrim": "rgba(0,0,0,0.55)"
+		},
+		fonts: { "font-mono": "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", \"Courier New\", monospace" }
 	}
 };
 /**
@@ -461,11 +567,16 @@ const THEME_PRESETS = {
 * has to beat, and `:root` carries the *default* theme's font override. A silent
 * theme would inherit cue's JetBrains Mono instead of the base stack, so every
 * block says what it owns. Mirrors `build.mjs`'s `THEME_FONTS` handling.
+*
+* Every entry is a generic or a face the platform ships. The sans stack named
+* `Geist` until 2026-08-19 and no webfont was ever loaded to make it resolve, so
+* it was a name most visitors silently fell straight past; Geist is now the head
+* of the `geist` font pairing, which an app can actually deliver.
 */
 const BASE_FONT_STACKS = {
-	"font-sans": "Geist, ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", \"Helvetica Neue\", sans-serif",
+	"font-sans": "ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", \"Helvetica Neue\", sans-serif",
 	"font-mono": "ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace",
-	"font-display": "Geist, ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif"
+	"font-display": "ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif"
 };
 /**
 * The radius multiplier each density level contributes.
@@ -478,10 +589,27 @@ const BASE_FONT_STACKS = {
 */
 const DENSITY_RADIUS_SCALE = {
 	"ultra-compact": .75,
+	"compact": 1,
 	"normal": 1,
-	"large": 1
+	"large": 1,
+	"ultra-large": 1
 };
 /** The default density, whose radius scale the uncrossed theme block carries. */
-const DEFAULT_DENSITY_LEVEL = "normal";
+const DEFAULT_DENSITY_LEVEL = "compact";
+/**
+* What every theme block sets `--cue-font-mono` to.
+*
+* Neither the theme axis nor the font axis writes the shared token: each
+* publishes its own half (`--cue-font-theme-mono` and `--cue-font-pairing-mono`)
+* and this is the resolution, pairing first. It has to be a `var()` chain rather
+* than a value because the two attributes land on different elements — a
+* provider stamps `data-theme` on a `<div>` inside the `<html>` the pre-paint
+* script stamped `data-font` on, and for an inherited property the nearer
+* declaration would otherwise win whatever the stylesheet's order is.
+*
+* Mirrors `packages/tokens/build.mjs`'s `RESOLVED_MONO`, and
+* `test/theming/presets.test.ts` fails when the two drift.
+*/
+const RESOLVED_MONO = "var(--cue-font-pairing-mono, var(--cue-font-theme-mono))";
 //#endregion
-export { BASE_FONT_STACKS, DEFAULT_DENSITY_LEVEL, DENSITY_RADIUS_SCALE, THEME_COLOR_TOKENS, THEME_PRESETS };
+export { BASE_FONT_STACKS, DEFAULT_DENSITY_LEVEL, DENSITY_RADIUS_SCALE, RESOLVED_MONO, THEME_COLOR_TOKENS, THEME_PRESETS };

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, THEME_COLOR_TOKENS, THEME_PRESETS } from "./_presets.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. */
@@ -321,14 +321,23 @@ function resolveLight(dark, preset) {
 		provisional
 	};
 }
-/** The font declarations a theme block carries. */
+/**
+* The font declarations a theme block carries.
+*
+* The monospace lands on `--cue-font-theme-mono`, not on `--cue-font-mono`, and
+* the shared token is restated as the resolution of the two axes' halves —
+* exactly what a shipped preset's block does. A generated theme that wrote the
+* shared token directly would beat a `[data-font]` pairing stamped on any
+* ancestor, purely by sitting nearer to the text, and a consumer's own preset
+* would be the one preset in the system the typeface picker could not move.
+*/
 function resolveFonts(anchors, preset) {
 	const fonts = anchors.fonts ?? {};
 	const declared = [];
 	if (fonts.sans !== void 0) declared.push(["font-sans", fonts.sans]);
-	declared.push(["font-mono", fonts.mono ?? lookup(preset, "font-mono") ?? BASE_FONT_STACKS["font-mono"]]);
+	declared.push(["font-theme-mono", fonts.mono ?? lookup(preset, "font-mono") ?? BASE_FONT_STACKS["font-mono"]]);
 	if (fonts.display !== void 0) declared.push(["font-display", fonts.display]);
-	return declared.map(([name, value]) => [tokenProperty(name), assertCssValue(name, value)]);
+	return [...declared.map(([name, value]) => [tokenProperty(name), assertCssValue(name, value)]), [tokenProperty("font-mono"), RESOLVED_MONO]];
 }
 /** Round a product of two scales to something a stylesheet can print. */
 const scaled = (a, b) => String(Number((a * b).toFixed(4)));
@@ -391,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,
@@ -400,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 ?? []
 	];
@@ -432,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
+}