@cueplusplus/ui 0.2.0 → 0.5.0

package/dist/agent-runtime/use-agent-thread.js

@@ -0,0 +1,251 @@
+"use client";
+import * as React from "react";
+//#region src/agent-runtime/use-agent-thread.ts
+/**
+* The runtime says `assistant`; this library has said `agent` since its first
+* chat component, because a turn here can come from one of a dozen named
+* workers rather than the assistant.
+*/
+const ROLES = {
+	assistant: "agent",
+	system: "system",
+	user: "user"
+};
+/** Every text part of a turn, as one block of prose. */
+function joinText(content) {
+	return content.flatMap((part) => part.type === "text" ? [part.text] : []).join("\n\n");
+}
+/** Every reasoning part, or nothing at all when the model showed none. */
+function joinReasoning(content) {
+	const thoughts = content.flatMap((part) => part.type === "reasoning" ? [part.text] : []);
+	return thoughts.length === 0 ? void 0 : thoughts.join("\n\n");
+}
+/**
+* While a call is still streaming, `args` is a partial parse — often `{}` for
+* several frames — and `argsText` is what the model has actually said. Show the
+* parse once there is one, the raw text until then, and nothing invented in
+* either case.
+*/
+function formatArgs(part) {
+	const args = part.args;
+	if (typeof args === "object" && args !== null && Object.keys(args).length > 0) return JSON.stringify(args, null, 2);
+	return part.argsText ?? "";
+}
+/** A result as text, whatever the tool returned. Never parsed, never rendered as markup. */
+function formatResult(result) {
+	if (result === void 0) return void 0;
+	if (typeof result === "string") return result;
+	return JSON.stringify(result, null, 2) ?? String(result);
+}
+/**
+* A call has no status of its own until it has an outcome, so until then it
+* borrows the turn's: a call inside a running turn is working, one inside a
+* turn parked on a human is waiting.
+*/
+function toolStatus(part, message) {
+	if (part.isError === true) return "failed";
+	if (part.result !== void 0) return "done";
+	switch (message.status?.type) {
+		case "running": return "working";
+		case "requires-action": return "idle";
+		case "incomplete": return "failed";
+		default: return "done";
+	}
+}
+/** The turn's tool calls, in the order the model made them. */
+function toolCalls(message) {
+	return message.content.flatMap((part) => part.type === "tool-call" ? [{
+		id: part.toolCallId,
+		tool: part.toolName,
+		args: formatArgs(part),
+		result: formatResult(part.result),
+		status: toolStatus(part, message)
+	}] : []);
+}
+/** The runtime's status vocabulary, in this library's words. */
+function turnStatus(message) {
+	if (message.role !== "assistant") return "complete";
+	switch (message.status.type) {
+		case "running": return "streaming";
+		case "requires-action": return "requires-action";
+		case "incomplete": return message.status.reason === "cancelled" ? "cancelled" : "failed";
+		default: return "complete";
+	}
+}
+/** Where the turn sits among its regenerated siblings. */
+function branchOf(runtime, id) {
+	try {
+		const state = runtime.thread.getMessageById(id).getState();
+		return {
+			index: state.branchNumber,
+			count: state.branchCount
+		};
+	} catch {
+		return {
+			index: 1,
+			count: 1
+		};
+	}
+}
+/** One runtime message, in the props the Chat group takes. */
+function toTurn(runtime, message, agent) {
+	const role = ROLES[message.role];
+	const status = turnStatus(message);
+	return {
+		id: message.id,
+		role,
+		agent: role !== "agent" ? void 0 : typeof agent === "function" ? agent(message) : agent,
+		text: joinText(message.content),
+		reasoning: joinReasoning(message.content),
+		toolCalls: toolCalls(message),
+		status,
+		pending: status === "streaming",
+		createdAt: message.createdAt,
+		branch: branchOf(runtime, message.id),
+		message
+	};
+}
+/**
+* An assistant-ui runtime, read as the props the Chat group already takes.
+*
+* `Message`, `MessageList` and `Composer` render turns that have finished
+* arriving. The hard part of a turn that is *still* arriving — assembling
+* tokens, tracking a run, cancelling one, keeping a regenerated answer beside
+* its sibling — is a solved problem, so this library does not re-derive it. You
+* build a runtime with one line of assistant-ui, typically
+* `useExternalStoreRuntime(adapter)`, and hand the object over; every field
+* that comes back is named for the prop it feeds.
+*
+* It is provider-free by construction: a `useSyncExternalStore` over the
+* runtime's thread, and nothing else. No `AssistantRuntimeProvider`, no
+* primitive, no context and no borrowed DOM — this library renders 100% of what
+* the reader sees, and the peer is only a type in the shipped modules.
+*
+* `MessageList` follows a turn that is still growing on its own: the items
+* container is watched for growth, so a streaming bubble keeps the bottom in
+* view without the host adding anything, while a tool-call card the reader
+* folds away leaves the view where it was.
+*
+* Four things are worth knowing before wiring an `ExternalStoreAdapter` to it:
+*
+* - **Pass `convertMessage`, and keep its identity.** Without it your messages
+*   must already be complete runtime messages, and a missing `metadata`
+*   throws; `convertMessage: (m) => m` lets the runtime fill the defaults in.
+*   Declare it outside the component (or memoise it): the runtime caches the
+*   conversion against that function, so a fresh arrow every render re-converts
+*   the whole thread, which re-renders, which converts it again — an inline
+*   arrow turns the next message change into "Maximum update depth exceeded".
+* - **`onReload` takes two arguments** — `(parentId, config)`. Regenerating a
+*   turn re-runs its *parent*, which is what puts the new answer beside the old
+*   one rather than after it.
+* - **A branch switch is host-owned.** Under an ExternalStore runtime
+*   `switchBranch` does not move the thread: it arrives at the adapter's
+*   `setMessages` with the newly visible list, and the host writes it back. A
+*   host that ignores `setMessages` gets a picker that does nothing.
+* - **`onStop`, `regenerate` and `switchBranch` are `undefined`** until the
+*   matching callback exists on the adapter (`onCancel`, `onReload`,
+*   `setMessages`). That is deliberate: `Composer` keeps drawing Send while
+*   `onStop` is missing, so a control that cannot work is never drawn.
+*
+* @example
+* // Outside the component: the runtime caches the conversion against this
+* // function, and a new one every render is an update loop.
+* const convertMessage = (m: ThreadMessageLike) => m;
+*
+* const runtime = useExternalStoreRuntime({
+*   messages,
+*   isRunning,
+*   convertMessage,
+*   onNew,
+*   onCancel,
+*   onReload,
+*   setMessages,
+* });
+* const thread = useAgentThread(runtime, { agent: "planner" });
+*
+* <MessageList aria-label="Thread">
+*   {thread.turns.map((t) => (
+*     <Message
+*       key={t.id}
+*       role={t.role}
+*       agent={t.agent}
+*       pending={t.pending}
+*       footer={
+*         t.branch.count > 1 && thread.switchBranch ? (
+*           <BranchPicker
+*             index={t.branch.index}
+*             count={t.branch.count}
+*             onNavigate={(d) => thread.switchBranch?.(t.id, d)}
+*             disabled={thread.busy}
+*           />
+*         ) : undefined
+*       }
+*     >
+*       {t.text}
+*       {t.toolCalls.map((c) => (
+*         <ToolCallCard key={c.id} tool={c.tool} args={c.args} result={c.result} status={c.status} />
+*       ))}
+*     </Message>
+*   ))}
+* </MessageList>
+* <Composer
+*   onSend={thread.onSend}
+*   busy={thread.busy}
+*   disabled={thread.disabled || thread.busy}
+*   onStop={thread.onStop}
+* />
+*/
+function useAgentThread(runtime, options) {
+	const agent = options?.agent;
+	const agentRef = React.useRef(agent);
+	agentRef.current = agent;
+	const agentKey = typeof agent === "function" ? "fn" : agent;
+	const subscribe = React.useCallback((onStoreChange) => runtime.thread.subscribe(onStoreChange), [runtime]);
+	const getState = React.useCallback(() => runtime.thread.getState(), [runtime]);
+	const { capabilities, isDisabled, isRunning, messages } = React.useSyncExternalStore(subscribe, getState, getState);
+	const turns = React.useMemo(() => messages.map((message) => toTurn(runtime, message, agentRef.current)), [
+		messages,
+		runtime,
+		agentKey
+	]);
+	const onSend = React.useCallback((text) => {
+		runtime.thread.append({
+			role: "user",
+			content: [{
+				type: "text",
+				text
+			}]
+		});
+	}, [runtime]);
+	const cancel = React.useCallback(() => {
+		runtime.thread.cancelRun();
+	}, [runtime]);
+	const reload = React.useCallback((turnId) => {
+		runtime.thread.getMessageById(turnId).reload();
+	}, [runtime]);
+	const switchTo = React.useCallback((turnId, direction) => {
+		runtime.thread.getMessageById(turnId).switchToBranch({ position: direction });
+	}, [runtime]);
+	return React.useMemo(() => ({
+		turns,
+		busy: isRunning,
+		disabled: isDisabled,
+		onSend,
+		onStop: capabilities.cancel ? cancel : void 0,
+		regenerate: capabilities.reload ? reload : void 0,
+		switchBranch: capabilities.switchToBranch ? switchTo : void 0,
+		runtime
+	}), [
+		turns,
+		isRunning,
+		isDisabled,
+		capabilities,
+		onSend,
+		cancel,
+		reload,
+		switchTo,
+		runtime
+	]);
+}
+//#endregion
+export { useAgentThread };

package/dist/brand/_chassis.d.ts

@@ -22,7 +22,7 @@ type BrandSize = "sm" | "md" | "lg";
  *
  * Not a light/dark pair. The source artwork ships two files that hard-code
  * `white`, `black` and `#1E1E1E`; this library ships one component that reads
- * the token layer, so a single element is correct in all eight presets and both
+ * the token layer, so a single element is correct in all ten presets and both
  * modes without anybody choosing a file.
  */
 type BrandTone = "inherit" | "fg" | "accent";

package/dist/brand/cue-mark.d.ts

@@ -8,7 +8,7 @@ interface CueMarkProps extends BrandAssetProps {}
  * Square at every size, drawn from the artwork's own path data, and painted
  * entirely from tokens — the disc takes the tone's ink and the two "+" glyphs
  * take the ground, which is exactly the relationship the two shipped SVGs
- * encode by hand. One element is therefore correct in all eight presets and
+ * encode by hand. One element is therefore correct in all ten presets and
  * both modes, and there is no light/dark variant to pick.
  *
  * The two glyphs are {@link Plussie}'s eyes; both components read one geometry

package/dist/brand/cue-mark.js

@@ -10,7 +10,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 * Square at every size, drawn from the artwork's own path data, and painted
 * entirely from tokens — the disc takes the tone's ink and the two "+" glyphs
 * take the ground, which is exactly the relationship the two shipped SVGs
-* encode by hand. One element is therefore correct in all eight presets and
+* encode by hand. One element is therefore correct in all ten presets and
 * both modes, and there is no light/dark variant to pick.
 *
 * The two glyphs are {@link Plussie}'s eyes; both components read one geometry

package/dist/chat/index.d.ts

@@ -1,8 +1,8 @@
+import { AskAnswer, AskBox, AskBoxProps, AskDanger, AskKind, AskOption } from "./ask-box.js";
+import { Message, MessageProps, MessageRole } from "./message.js";
 import { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, AgentColorOptions, agentColor, agentColorStyle } from "./agent-color.js";
 import { AgentPile, AgentPileEntry, AgentPileProps, AgentPileSize } from "./agent-pile.js";
-import { AskAnswer, AskBox, AskBoxProps, AskDanger, AskKind, AskOption } from "./ask-box.js";
 import { Composer, ComposerProps, ComposerSubmitKey } from "./composer.js";
 import { DelegationCard, DelegationCardProps, DelegationDirection, DelegationStatus } from "./delegation-card.js";
-import { Message, MessageProps, MessageRole } from "./message.js";
 import { MessageList, MessageListProps } from "./message-list.js";
 export { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, type AgentColorOptions, AgentPile, type AgentPileEntry, type AgentPileProps, type AgentPileSize, type AskAnswer, AskBox, type AskBoxProps, type AskDanger, type AskKind, type AskOption, Composer, type ComposerProps, type ComposerSubmitKey, DelegationCard, type DelegationCardProps, type DelegationDirection, type DelegationStatus, Message, MessageList, type MessageListProps, type MessageProps, type MessageRole, agentColor, agentColorStyle };

package/dist/chat/message-list.d.ts

@@ -24,6 +24,12 @@ interface MessageListProps extends Omit<React.ComponentPropsWithoutRef<"div">, "
  * mid-sentence is the single most common reason people stop reading a chat
  * pane. Coming back to the bottom re-arms it.
  *
+ * It follows a turn that is still growing, too — the items container is watched
+ * for growth, so a streaming bubble keeps the bottom in view without the host
+ * adding anything, while something merely collapsing leaves the view alone. And
+ * when you have scrolled up, a turn that grows offers the pill instead of
+ * pulling you down.
+ *
  * Deliberately **not** virtualised. A virtualiser needs a measurable row height
  * and chat turns are variable-height by nature; the cost of getting that wrong
  * (jumping scrollbars) is worse than the cost of a few hundred DOM nodes. When

package/dist/chat/message-list.js

@@ -19,6 +19,12 @@ const ROOT_PX = 16;
 * mid-sentence is the single most common reason people stop reading a chat
 * pane. Coming back to the bottom re-arms it.
 *
+* It follows a turn that is still growing, too — the items container is watched
+* for growth, so a streaming bubble keeps the bottom in view without the host
+* adding anything, while something merely collapsing leaves the view alone. And
+* when you have scrolled up, a turn that grows offers the pill instead of
+* pulling you down.
+*
 * Deliberately **not** virtualised. A virtualiser needs a measurable row height
 * and chat turns are variable-height by nature; the cost of getting that wrong
 * (jumping scrollbars) is worse than the cost of a few hundred DOM nodes. When
@@ -31,8 +37,10 @@ const ROOT_PX = 16;
 */
 const MessageList = React.forwardRef(function MessageList({ className, children, follow = true, height, jumpLabel = "Jump to latest", emptyLabel = "No messages yet", "aria-label": ariaLabel, style, ...elementProps }, ref) {
 	const scrollerRef = React.useRef(null);
+	const itemsRef = React.useRef(null);
 	const [pinned, setPinned] = React.useState(true);
 	const [behind, setBehind] = React.useState(false);
+	const lastHeightRef = React.useRef(0);
 	const count = React.Children.count(children);
 	const previousCountRef = React.useRef(count);
 	const jumpToLatest = React.useCallback(() => {
@@ -58,6 +66,32 @@ const MessageList = React.forwardRef(function MessageList({ className, children,
 		follow,
 		pinned
 	]);
+	React.useEffect(() => {
+		const element = scrollerRef.current;
+		const items = itemsRef.current;
+		if (items === null) lastHeightRef.current = 0;
+		if (element === null || items === null || typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver((entries) => {
+			const entry = entries[0];
+			if (entry === void 0) return;
+			const height = entry.contentRect?.height ?? entry.target.getBoundingClientRect().height;
+			const grew = height > lastHeightRef.current;
+			lastHeightRef.current = height;
+			if (!grew) return;
+			if (follow && pinned) {
+				element.scrollTop = element.scrollHeight;
+				setBehind(false);
+				return;
+			}
+			setBehind(true);
+		});
+		observer.observe(items);
+		return () => observer.disconnect();
+	}, [
+		follow,
+		pinned,
+		count === 0
+	]);
 	const onScroll = React.useCallback(() => {
 		const element = scrollerRef.current;
 		if (element === null) return;
@@ -88,6 +122,7 @@ const MessageList = React.forwardRef(function MessageList({ className, children,
 				className: "flex h-full items-center justify-center p-(--cue-space-6) font-mono text-(length:--cue-text-ui) text-fg-subtle",
 				children: emptyLabel
 			}) : /* @__PURE__ */ jsx("div", {
+				ref: itemsRef,
 				"data-slot": "message-list-items",
 				className: "flex min-w-0 flex-col items-stretch gap-(--cue-space-4) p-(--cue-space-4)",
 				children

package/dist/chrome/_edge-scroller.js

@@ -52,9 +52,20 @@ function useEdgeScroll(enabled = true) {
 		el.addEventListener("scroll", sync, { passive: true });
 		const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => sync());
 		observer?.observe(el);
-		if (el.firstElementChild !== null) observer?.observe(el.firstElementChild);
+		let observedChildren = /* @__PURE__ */ new Set();
+		const syncObservedChildren = () => {
+			const nextChildren = new Set(el.children);
+			for (const child of observedChildren) if (!nextChildren.has(child)) observer?.unobserve(child);
+			for (const child of nextChildren) if (!observedChildren.has(child)) observer?.observe(child);
+			observedChildren = nextChildren;
+			sync();
+		};
+		syncObservedChildren();
+		const mutations = typeof MutationObserver === "undefined" ? null : new MutationObserver(() => syncObservedChildren());
+		mutations?.observe(el, { childList: true });
 		return () => {
 			el.removeEventListener("scroll", sync);
+			mutations?.disconnect();
 			observer?.disconnect();
 		};
 	}, [enabled, sync]);

package/dist/chrome/_tabs-scroll.d.ts

@@ -50,7 +50,7 @@ declare function computeScrollEdges(scrollLeft: number, scrollWidth: number, cli
  * an overlay would have to re-create that background as an opaque colour and
  * would drift the moment the theme changed. Masking fades the content itself
  * and lets whatever is behind show through, so it matches by construction in
- * all eight themes and both modes.
+ * every theme and both modes.
  *
  * This softens the cut; it is NOT the whole affordance. What sits at an
  * overflowing edge is often the gap between two tabs, and fading empty space is

package/dist/chrome/_tabs-scroll.js

@@ -53,7 +53,7 @@ function computeScrollEdges(scrollLeft, scrollWidth, clientWidth) {
 * an overlay would have to re-create that background as an opaque colour and
 * would drift the moment the theme changed. Masking fades the content itself
 * and lets whatever is behind show through, so it matches by construction in
-* all eight themes and both modes.
+* every theme and both modes.
 *
 * This softens the cut; it is NOT the whole affordance. What sits at an
 * overflowing edge is often the gap between two tabs, and fading empty space is

package/dist/chrome/app-shell.d.ts

@@ -8,6 +8,47 @@ interface AppShellRootProps extends React.ComponentPropsWithoutRef<"div"> {
   defaultNavOpen?: boolean;
   /** Called with the next open state whenever the drawer is opened or dismissed. */
   onNavOpenChange?: (open: boolean) => void;
+  /**
+   * Whether the navigation column is collapsed to an icon rail, when
+   * controlled. Pass with `onRailChange`. Defaults to expanded.
+   *
+   * It is the column's own collapse, owned one level up. Collapsing is a
+   * property of the column, but the header cell over it is a child of the bar
+   * — a different branch of the tree — and a length only one of them knows is
+   * a length they will eventually disagree about. So the frame holds the
+   * state, stamps `data-rail` on itself for anything that has to answer to it,
+   * and hands it down to `Sidebar.Root` as its controlled `collapsed`.
+   *
+   * **Persistence is the caller's.** A rail is set once and expected to be
+   * remembered, and where it is remembered — `localStorage`, a cookie the
+   * server can read before first paint, a user record — is a decision about
+   * hydration and privacy that a layout component has no business making.
+   */
+  rail?: boolean;
+  /** Initial rail state when uncontrolled. Defaults to `false`. */
+  defaultRail?: boolean;
+  /** Called with the next rail state whenever the column is collapsed or expanded. */
+  onRailChange?: (rail: boolean) => void;
+  /** Width of the navigation column while expanded. Any CSS length. Defaults to `"14rem"`. */
+  navWidth?: string;
+  /**
+   * Width of the navigation column while railed. Any CSS length. Defaults to
+   * `"3.5rem"` — a `--cue-icon-md` glyph centred in a `--cue-control-md` row,
+   * with a gutter either side that still reads as a column rather than a strip.
+   */
+  railWidth?: string;
+}
+interface AppShellBarProps extends React.ComponentPropsWithoutRef<"div"> {
+  /**
+   * The header cell over the navigation column: the app mark, and whatever
+   * control rails it.
+   *
+   * Omit it and the bar is one undivided strip — no empty bordered cell, which
+   * is worse than no cell.
+   */
+  brand?: React.ReactNode;
+  /** Extra classes for the header cell. */
+  brandClassName?: string;
 }
 type AppShellBodyProps = React.ComponentPropsWithoutRef<"div">;
 interface AppShellSidebarProps extends SidebarRootProps {
@@ -85,7 +126,15 @@ interface AppShellAsideProps extends React.ComponentPropsWithoutRef<"aside"> {
  * side; the shell exists so no page has to get them right again.
  *
  * The bars are ordinary children — `TitleBar` and `StatusBar` are already
- * `shrink-0` and need no wrapper — so a shell reads as the page's outline.
+ * `shrink-0` and need no wrapper — so a shell reads as the page's outline. The
+ * one bar the shell does own is {@link AppShellBar}, and it owns it for one
+ * reason: it is divided by the navigation column, which means it has to be
+ * measured from the same length the column is.
+ *
+ * That length is `--cue-nav-width`, written on the frame. `rail` rewrites it,
+ * `data-rail` announces it, and the column and the header cell over it move
+ * together because neither holds a width of its own. Persistence and the
+ * toggle are the caller's — see {@link AppShellRootProps.rail}.
  *
  * This is also the only component in the library with a viewport breakpoint:
  * below `md` the navigation column becomes a drawer and a trigger appears in
@@ -114,6 +163,7 @@ interface AppShellAsideProps extends React.ComponentPropsWithoutRef<"aside"> {
  */
 declare const AppShell: {
   Root: React.ForwardRefExoticComponent<AppShellRootProps & React.RefAttributes<HTMLDivElement>>;
+  Bar: React.ForwardRefExoticComponent<AppShellBarProps & React.RefAttributes<HTMLDivElement>>;
   Body: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
   Sidebar: React.ForwardRefExoticComponent<AppShellSidebarProps & React.RefAttributes<HTMLElement>>;
   NavTrigger: React.ForwardRefExoticComponent<AppShellNavTriggerProps & React.RefAttributes<HTMLButtonElement>>;
@@ -122,4 +172,4 @@ declare const AppShell: {
   Aside: React.ForwardRefExoticComponent<AppShellAsideProps & React.RefAttributes<HTMLElement>>;
 };
 //#endregion
-export { AppShell, AppShellAsideProps, AppShellBodyProps, AppShellContentProps, AppShellNavTriggerProps, AppShellRootProps, AppShellScrollerProps, AppShellSidebarProps };
+export { AppShell, AppShellAsideProps, AppShellBarProps, AppShellBodyProps, AppShellContentProps, AppShellNavTriggerProps, AppShellRootProps, AppShellScrollerProps, AppShellSidebarProps };

package/dist/chrome/app-shell.js

@@ -10,9 +10,29 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/chrome/app-shell.tsx
 const AppShellContext = React.createContext({
 	navOpen: false,
-	setNavOpen: () => {}
+	setNavOpen: () => {},
+	rail: false,
+	setRail: () => {}
 });
 /**
+* The navigation column's current width, written once on the frame and read by
+* everything that has to line up with it.
+*
+* The prototype this came from put it best: collapsing the rail rewrites one
+* length, and the bar's header cell and the column move together because
+* neither of them holds a length of its own. A custom property rather than two
+* inline widths because the two boxes are on opposite sides of the tree — the
+* cell is a child of the bar, above `AppShell.Body`, and the column is inside
+* it — and because it is then also the handle a consumer's own CSS aligns to.
+*
+* {@link AppShellBar} spells the name a second time, in a Tailwind utility,
+* because the scanner reads class strings and not constants. The two spellings
+* move together, and the shell's own suite fails if they stop matching.
+*/
+const NAV_WIDTH_PROPERTY = "--cue-nav-width";
+/** What a box that spans the navigation column sets its width to. */
+const NAV_WIDTH_VALUE = `var(${NAV_WIDTH_PROPERTY})`;
+/**
 * The console frame: title bar, navigation, work area, status bar — one
 * viewport tall, with exactly one thing scrolling.
 *
@@ -26,7 +46,15 @@ const AppShellContext = React.createContext({
 * side; the shell exists so no page has to get them right again.
 *
 * The bars are ordinary children — `TitleBar` and `StatusBar` are already
-* `shrink-0` and need no wrapper — so a shell reads as the page's outline.
+* `shrink-0` and need no wrapper — so a shell reads as the page's outline. The
+* one bar the shell does own is {@link AppShellBar}, and it owns it for one
+* reason: it is divided by the navigation column, which means it has to be
+* measured from the same length the column is.
+*
+* That length is `--cue-nav-width`, written on the frame. `rail` rewrites it,
+* `data-rail` announces it, and the column and the header cell over it move
+* together because neither holds a width of its own. Persistence and the
+* toggle are the caller's — see {@link AppShellRootProps.rail}.
 *
 * This is also the only component in the library with a viewport breakpoint:
 * below `md` the navigation column becomes a drawer and a trigger appears in
@@ -54,27 +82,62 @@ const AppShellContext = React.createContext({
 * </AppShell.Root>
 */
 const AppShell = {
-	Root: React.forwardRef(function AppShellRoot({ className, navOpen: navOpenProp, defaultNavOpen = false, onNavOpenChange, ...elementProps }, ref) {
+	Root: React.forwardRef(function AppShellRoot({ className, navOpen: navOpenProp, defaultNavOpen = false, onNavOpenChange, rail: railProp, defaultRail = false, onRailChange, navWidth = "14rem", railWidth = "3.5rem", style, ...elementProps }, ref) {
 		const [uncontrolled, setUncontrolled] = React.useState(defaultNavOpen);
 		const navOpen = navOpenProp ?? uncontrolled;
 		const setNavOpen = React.useCallback((open) => {
 			if (navOpenProp === void 0) setUncontrolled(open);
 			onNavOpenChange?.(open);
 		}, [navOpenProp, onNavOpenChange]);
+		const [uncontrolledRail, setUncontrolledRail] = React.useState(defaultRail);
+		const rail = railProp ?? uncontrolledRail;
+		const setRail = React.useCallback((next) => {
+			if (railProp === void 0) setUncontrolledRail(next);
+			onRailChange?.(next);
+		}, [railProp, onRailChange]);
 		const context = React.useMemo(() => ({
 			navOpen,
-			setNavOpen
-		}), [navOpen, setNavOpen]);
+			setNavOpen,
+			rail,
+			setRail
+		}), [
+			navOpen,
+			setNavOpen,
+			rail,
+			setRail
+		]);
 		return /* @__PURE__ */ jsx(AppShellContext.Provider, {
 			value: context,
 			children: /* @__PURE__ */ jsx("div", {
 				ref,
 				"data-slot": "app-shell",
-				className: cn("relative flex h-dvh flex-col overflow-clip bg-bg text-fg", className),
+				"data-rail": rail ? "" : void 0,
+				className: cn("group/app-shell relative flex h-dvh flex-col overflow-clip bg-bg text-fg", className),
+				style: {
+					[NAV_WIDTH_PROPERTY]: rail ? railWidth : navWidth,
+					...style
+				},
 				...elementProps
 			})
 		});
 	}),
+	Bar: React.forwardRef(function AppShellBar({ className, brand, brandClassName, children, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsxs("div", {
+			ref,
+			"data-slot": "app-shell-bar",
+			className: cn("flex h-(--cue-chrome-titlebar) w-full shrink-0 items-stretch border-b border-border bg-surface-1", className),
+			...elementProps,
+			children: [brand === void 0 ? null : /* @__PURE__ */ jsx("div", {
+				"data-slot": "app-shell-brand",
+				className: cn("flex w-auto min-w-0 shrink-0 items-center gap-(--cue-space-3) border-r border-border px-(--cue-pad-row-x) transition-[width] duration-150 ease-out md:w-(--cue-nav-width) motion-reduce:transition-none", brandClassName),
+				children: brand
+			}), /* @__PURE__ */ jsx("div", {
+				"data-slot": "app-shell-bar-rest",
+				className: "flex min-w-0 flex-1 items-center gap-(--cue-space-3) px-(--cue-pad-row-x)",
+				children
+			})]
+		});
+	}),
 	Body: React.forwardRef(function AppShellBody({ className, ...elementProps }, ref) {
 		return /* @__PURE__ */ jsx("div", {
 			ref,
@@ -83,15 +146,24 @@ const AppShell = {
 			...elementProps
 		});
 	}),
-	Sidebar: React.forwardRef(function AppShellSidebar({ className, drawerClassName, drawerTitle = "Navigation", closeLabel = "Close navigation", collapsible = true, landmark = "navigation", "aria-label": ariaLabel = "Navigation", children, ...sidebarProps }, ref) {
-		const { navOpen, setNavOpen } = React.useContext(AppShellContext);
+	Sidebar: React.forwardRef(function AppShellSidebar({ className, drawerClassName, drawerTitle = "Navigation", closeLabel = "Close navigation", collapsible = true, landmark = "navigation", "aria-label": ariaLabel = "Navigation", collapsed, defaultCollapsed, onCollapsedChange, width, collapsedWidth, children, ...sidebarProps }, ref) {
+		const { navOpen, setNavOpen, rail, setRail } = React.useContext(AppShellContext);
 		const DrawerLandmark = landmark === "complementary" ? "aside" : "nav";
+		const railed = collapsed === void 0 && defaultCollapsed === void 0;
 		return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs(Sidebar.Root, {
 			ref,
 			"data-slot": "app-shell-sidebar",
 			"aria-label": ariaLabel,
 			landmark,
 			className: cn("hidden md:flex", className),
+			collapsed: railed ? rail : collapsed,
+			defaultCollapsed,
+			onCollapsedChange: railed ? (next) => {
+				onCollapsedChange?.(next);
+				setRail(next);
+			} : onCollapsedChange,
+			width: width ?? (railed ? NAV_WIDTH_VALUE : void 0),
+			collapsedWidth: collapsedWidth ?? (railed ? NAV_WIDTH_VALUE : void 0),
 			...sidebarProps,
 			children: [children, collapsible ? /* @__PURE__ */ jsx(Sidebar.Rail, {}) : null]
 		}), /* @__PURE__ */ jsx(Drawer.Root, {

package/dist/chrome/index.d.ts

@@ -2,7 +2,7 @@ import { ScrollEdges, TAB_FADE_PX, computeScrollEdges, edgeFadeMask } from "./_t
 import { BarOverflow } from "./_edge-scroller.js";
 import { TREE_GUIDE_GLYPHS, TreeGuide, TreeItem, TreeRow, flattenTree } from "./_tree.js";
 import { AppBar, AppBarActionsProps, AppBarBrandProps, AppBarLinkProps, AppBarNavProps, AppBarRegister, AppBarRootProps, AppBarSeparatorProps } from "./app-bar.js";
-import { AppShell, AppShellAsideProps, AppShellBodyProps, AppShellContentProps, AppShellNavTriggerProps, AppShellRootProps, AppShellScrollerProps, AppShellSidebarProps } from "./app-shell.js";
+import { AppShell, AppShellAsideProps, AppShellBarProps, AppShellBodyProps, AppShellContentProps, AppShellNavTriggerProps, AppShellRootProps, AppShellScrollerProps, AppShellSidebarProps } from "./app-shell.js";
 import { EmptyState, EmptyStateProps } from "./empty-state.js";
 import { Eyebrow, EyebrowProps } from "./eyebrow.js";
 import { Footer, FooterProps } from "./footer.js";
@@ -18,4 +18,4 @@ import { ScrollableTabsList, ScrollableTabsListProps, Tabs, TabsListProps, TabsP
 import { TitleBar, TitleBarProps } from "./title-bar.js";
 import { Tree, TreeProps, TreeVisibility, TreeVisibilityToggle, TreeVisibilityToggleProps } from "./tree.js";
 import { Toolbar, ToolbarButtonProps, ToolbarGroupProps, ToolbarRootProps, ToolbarSeparatorProps } from "./toolbar.js";
-export { AppBar, type AppBarActionsProps, type AppBarBrandProps, type AppBarLinkProps, type AppBarNavProps, type AppBarRegister, type AppBarRootProps, type AppBarSeparatorProps, AppShell, type AppShellAsideProps, type AppShellBodyProps, type AppShellContentProps, type AppShellNavTriggerProps, type AppShellRootProps, type AppShellScrollerProps, type AppShellSidebarProps, type BarOverflow, EmptyState, type EmptyStateProps, Eyebrow, type EyebrowProps, Footer, type FooterProps, NavigationMenu, type NavigationMenuContentProps, type NavigationMenuItemProps, type NavigationMenuLinkProps, type NavigationMenuListProps, type NavigationMenuRootProps, type NavigationMenuTriggerProps, type NavigationMenuViewportProps, PageShell, type PageShellProps, type PageWidth, Panel, PanelHeader, type PanelHeaderProps, type PanelProps, Row, type RowProps, ScrollArea, type ScrollAreaOrientation, type ScrollAreaProps, type ScrollEdges, ScrollableTabsList, type ScrollableTabsListProps, SeamList, type SeamListProps, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlItem, type SegmentedControlProps, type SegmentedControlSize, StatusBar, type StatusBarItemProps, type StatusBarProps, type StatusBarTone, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Tabs, type TabsListProps, type TabsPanelProps, type TabsRootProps, type TabsTabProps, TitleBar, type TitleBarProps, Toolbar, type ToolbarButtonProps, type ToolbarGroupProps, type ToolbarRootProps, type ToolbarSeparatorProps, Tree, type TreeGuide, type TreeItem, type TreeProps, type TreeRow, type TreeVisibility, TreeVisibilityToggle, type TreeVisibilityToggleProps, computeScrollEdges, edgeFadeMask, flattenTree, rowVariants };
+export { AppBar, type AppBarActionsProps, type AppBarBrandProps, type AppBarLinkProps, type AppBarNavProps, type AppBarRegister, type AppBarRootProps, type AppBarSeparatorProps, AppShell, type AppShellAsideProps, type AppShellBarProps, type AppShellBodyProps, type AppShellContentProps, type AppShellNavTriggerProps, type AppShellRootProps, type AppShellScrollerProps, type AppShellSidebarProps, type BarOverflow, EmptyState, type EmptyStateProps, Eyebrow, type EyebrowProps, Footer, type FooterProps, NavigationMenu, type NavigationMenuContentProps, type NavigationMenuItemProps, type NavigationMenuLinkProps, type NavigationMenuListProps, type NavigationMenuRootProps, type NavigationMenuTriggerProps, type NavigationMenuViewportProps, PageShell, type PageShellProps, type PageWidth, Panel, PanelHeader, type PanelHeaderProps, type PanelProps, Row, type RowProps, ScrollArea, type ScrollAreaOrientation, type ScrollAreaProps, type ScrollEdges, ScrollableTabsList, type ScrollableTabsListProps, SeamList, type SeamListProps, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlItem, type SegmentedControlProps, type SegmentedControlSize, StatusBar, type StatusBarItemProps, type StatusBarProps, type StatusBarTone, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Tabs, type TabsListProps, type TabsPanelProps, type TabsRootProps, type TabsTabProps, TitleBar, type TitleBarProps, Toolbar, type ToolbarButtonProps, type ToolbarGroupProps, type ToolbarRootProps, type ToolbarSeparatorProps, Tree, type TreeGuide, type TreeItem, type TreeProps, type TreeRow, type TreeVisibility, TreeVisibilityToggle, type TreeVisibilityToggleProps, computeScrollEdges, edgeFadeMask, flattenTree, rowVariants };