@iloveagents/foundry-web-ui 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @iloveagents/foundry-web-ui
 
+## 0.2.0
+
+### Minor Changes
+
+- UI: collapsible nav groups in `sidebar.tsx` with persisted state via
+  `useSyncExternalStore` + localStorage, plus stable group ordering via
+  new `priority` field in `nav-config.ts`.
+
+  `ag-ui-runtime-provider.tsx` accepts an external `threadId` and
+  `historyAdapterFactory` so the consuming app can wire its own
+  persistence (e.g. `ThreadHistoryAdapter` → REST `/api/conversations`).
+
+### Patch Changes
+
+- Move `@iloveagents/foundry-agent`, `-web-primitives` from
+  `peerDependencies` to `dependencies`. They always ship together as a
+  coordinated fixed group from this monorepo — they were never
+  independently-versioned peers. Declaring them as peerDeps caused
+  changesets' `shouldBumpMajor` cascade to promote the entire group to
+  a major version on every minor changeset. See the root `foundry-agent`
+  CHANGELOG entry for details.
+
+- Updated dependencies
+  - @iloveagents/foundry-agent@0.2.0
+  - @iloveagents/foundry-web-primitives@0.2.0
+
+### NOTE: 1.0.1 was accidental
+
+Version 1.0.1 was published briefly on 2026-05-27 due to the peerDep
+cascade bug described above (1.0.0 was reserved but not published —
+1.0.1 was the retry). It has been unpublished. Both 1.0.0 and 1.0.1
+are now permanently reserved on npm and CANNOT be re-published. Do
+not depend on 1.0.x.
+
+## 0.1.5
+
+### Patch Changes
+
+- f9144ca: Add `NavItem.statusIcon` slot for sidebar warning / status hints.
+
+  Renders a small tone-coloured icon next to the existing `statusDot`. Use for "this item needs attention" annotations (failed background jobs, permission drift, etc.) where a coloured dot isn't legible enough. Tones map to `warning` / `danger` / `info` / `neutral`. The `label` lands on both `aria-label` and the wrapping span's `title` attribute so screen-reader announcement + hover tooltip work without consumer wiring.
+  - @iloveagents/foundry-agent@0.1.5
+  - @iloveagents/foundry-web-primitives@0.1.5
+
 ## 0.1.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iloveagents/foundry-web-ui",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "types": "./src/index.ts",
@@ -22,9 +22,7 @@
     "zustand": "^5.0.0",
     "lucide-react": ">=0.400.0",
     "@azure/msal-browser": "^5.0.0",
-    "@azure/msal-react": "^5.0.0",
-    "@iloveagents/foundry-agent": "0.1.4",
-    "@iloveagents/foundry-web-primitives": "0.1.4"
+    "@azure/msal-react": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "@azure/msal-browser": {
@@ -47,7 +45,9 @@
     "tailwind-merge": "^3.5.0",
     "react-markdown": "^10.0.0",
     "remark-gfm": "^4.0.0",
-    "shiki": "^4.0.0"
+    "shiki": "^4.0.0",
+    "@iloveagents/foundry-agent": "0.2.0",
+    "@iloveagents/foundry-web-primitives": "0.2.0"
   },
   "devDependencies": {
     "typescript": "~5.9.3",

package/src/components/ag-ui-runtime-provider.tsx

@@ -1,15 +1,70 @@
 import { createContext, useContext, useState, useCallback, useMemo } from "react";
 import { AssistantRuntimeProvider, useLocalRuntime } from "@assistant-ui/react";
+import type { ThreadHistoryAdapter } from "@assistant-ui/react";
 import { TooltipProvider } from "../ui/tooltip.tsx";
 import { AGUIAdapterSDK } from "../lib/ag-ui-adapter.ts";
 import { FileAttachmentAdapter } from "../lib/attachment-adapter.ts";
 import { ShowDocumentToolUI } from "./show-document-tool-ui.tsx";
 import { ClientToolExecutor } from "./client-tool-executor.tsx";
 
+/**
+ * Per-mount inputs the host shell passes when it wants a chat
+ * conversation history wired to the runtime. Mirrors
+ * :type:`ChatConversationFactoryArgs` in ``foundry-web-shell`` —
+ * duplicated here (rather than imported) so the web-ui package stays
+ * independent of the shell package's dependency graph.
+ */
+export interface AGUIChatConversationFactoryArgs {
+  /** Conversation id captured from the URL (resumed chat) or undefined (fresh). */
+  urlMatch?: string;
+  /** Stable AG-UI adapter thread id — present in both cases. */
+  aguiThreadId: string;
+}
+
+/**
+ * Factory the consumer passes to build a :type:`ThreadHistoryAdapter`
+ * once the AG-UI adapter has minted its thread id. Called inside the
+ * keyed runtime mount; assistant-ui invokes ``load()``/``append()``
+ * via the returned adapter.
+ */
+export type AGUIHistoryAdapterFactory = (
+  args: AGUIChatConversationFactoryArgs,
+) => ThreadHistoryAdapter;
+
 interface AGUIRuntimeProviderProps {
   children: React.ReactNode;
   /** Custom fetch for agent requests. Handles URL rewriting + auth in production. */
   fetchFn?: typeof fetch;
+  /**
+   * Optional stable thread id for the AG-UI adapter. When set, the
+   * agent's POST body carries this id so server-side persistence
+   * (Foundry thread, conversation row) targets the same conversation
+   * across reloads / resumes. Changing the id remounts the inner
+   * runtime — past messages from a different thread don't bleed
+   * into the new one.
+   */
+  threadId?: string;
+  /**
+   * Conversation id captured from the current URL when the user
+   * resumed an existing chat (e.g. ``/chat/<id>``), or ``undefined``
+   * for a brand-new chat. Distinct from ``threadId``: the host shell
+   * MAY set ``threadId`` from a non-URL source (a sticky active
+   * conversation, a freshly-minted UUID) so ``threadId`` alone can't
+   * tell a history adapter "we're resuming". ``urlMatch`` carries
+   * that signal verbatim into ``historyAdapterFactory`` so the
+   * adapter can decide whether to load history (resume) or
+   * initialise empty (fresh) without inferring from ``threadId``.
+   */
+  urlMatch?: string;
+  /**
+   * Factory that builds the assistant-ui ``ThreadHistoryAdapter`` for
+   * this mount. Called once after the AG-UI adapter exists so it can
+   * receive both the URL match (when resuming) and the adapter's own
+   * thread id (always set — covers fresh chats). Pass alongside
+   * ``threadId`` for resumed chats; pass without ``threadId`` to get
+   * a fresh-chat runtime that still persists.
+   */
+  historyAdapterFactory?: AGUIHistoryAdapterFactory;
 }
 
 interface AGUIContextValue {
@@ -27,22 +82,78 @@ export function useAGUIAdapter() {
   return context;
 }
 
-export function AGUIRuntimeProvider({ children, fetchFn }: AGUIRuntimeProviderProps) {
+export function AGUIRuntimeProvider(props: AGUIRuntimeProviderProps) {
+  // Splitting render across an outer wrapper + a keyed inner is the
+  // canonical React idiom for "rebuild this stateful subtree when X
+  // changes". assistant-ui's runtime is created inside useLocalRuntime
+  // and tracks its messages internally; swapping threadId or history
+  // mid-life would leave stale state. Keying the inner subtree on
+  // threadId (+ the manual reset counter) guarantees a clean runtime
+  // per conversation, matching the ChatGPT-style "click → fresh chat
+  // backed by past messages" UX.
   const [resetKey, setResetKey] = useState(0);
-  // eslint-disable-next-line react-hooks/exhaustive-deps -- resetKey triggers new adapter with fresh threadId
-  const adapter = useMemo(
-    () => new AGUIAdapterSDK("/api/agent", fetchFn ? { fetchFn } : undefined),
-    [resetKey, fetchFn],
+  const resetThread = useCallback(() => setResetKey((p) => p + 1), []);
+
+  const innerKey = `${props.threadId ?? "fresh"}:${resetKey}`;
+
+  return (
+    <AGUIRuntimeInner key={innerKey} {...props} resetThread={resetThread} />
   );
+}
 
-  const resetThread = useCallback(() => {
-    setResetKey((prev) => prev + 1);
-  }, []);
+function AGUIRuntimeInner({
+  children,
+  fetchFn,
+  threadId,
+  urlMatch,
+  historyAdapterFactory,
+  resetThread,
+}: AGUIRuntimeProviderProps & { resetThread: () => void }) {
+  const adapter = useMemo(
+    () =>
+      new AGUIAdapterSDK(
+        "/api/agent",
+        // Only pass options if at least one is set, mirroring the prior
+        // single-arg semantics for the "fresh chat, no overrides" case.
+        fetchFn || threadId ? { fetchFn, threadId } : undefined,
+      ),
+    [fetchFn, threadId],
+  );
 
   const attachmentAdapter = useMemo(() => new FileAttachmentAdapter(), []);
 
+  // Build the history adapter ONCE per inner mount, after the AG-UI
+  // adapter exists so we know its thread id. The keyed-remount in the
+  // outer wrapper ensures threadId changes trigger a fresh adapter +
+  // fresh history adapter together, so resumed chats hydrate from the
+  // right conversation and fresh chats persist under their assistant-
+  // ui-minted UUID.
+  const historyAdapter = useMemo<ThreadHistoryAdapter | undefined>(() => {
+    if (!historyAdapterFactory) return undefined;
+    return historyAdapterFactory({
+      // ``urlMatch`` is the URL-derived resume signal (undefined for
+      // fresh chats). ``aguiThreadId`` is always defined — the AG-UI
+      // adapter mints it on construction. The factory uses ``urlMatch``
+      // to decide "load history" vs "initialise empty", and
+      // ``aguiThreadId`` to identify the row to write into.
+      urlMatch,
+      aguiThreadId: adapter.threadId,
+    });
+    // adapter is stable for the life of this inner mount (keyed remount
+    // covers the threadId change case), so it's OK to depend on the
+    // factory + urlMatch here.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [historyAdapterFactory, urlMatch]);
+
   const runtime = useLocalRuntime(adapter, {
-    adapters: { attachments: attachmentAdapter },
+    adapters: {
+      attachments: attachmentAdapter,
+      // history is optional — when undefined, the runtime acts as a
+      // pure in-memory thread (the original behaviour). When provided,
+      // assistant-ui calls .load() on mount to seed past messages and
+      // .append() after every turn.
+      ...(historyAdapter ? { history: historyAdapter } : {}),
+    },
   });
 
   return (

package/src/components/sidebar.test.tsx

@@ -2,7 +2,7 @@ import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { MemoryRouter } from "react-router";
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import { FolderOpen, MessageSquare } from "lucide-react";
+import { AlertTriangle, FolderOpen, MessageSquare } from "lucide-react";
 import { useNavStore } from "../lib/nav-store.ts";
 import { useAppStore } from "../lib/app-store.ts";
 import { SIDEBAR_WIDTH, useSidebarStore } from "../lib/sidebar-store.ts";
@@ -323,4 +323,289 @@ describe("Sidebar active state", () => {
       expect(wrappers[1].className).toContain("border-t");
     }
   });
+
+  it("renders NavItem.statusIcon with tone class + tooltip label", async () => {
+    // The statusIcon slot is consumer-driven (e.g. ``spaces-web-ui``
+    // stamps a warning triangle on workspaces with failed indexing).
+    // This test pins three things the consumer relies on:
+    //   1. The supplied LucideIcon component is rendered.
+    //   2. The tone maps to the right Tailwind class (``warning`` →
+    //      ``text-warning``).
+    //   3. The ``label`` lands on both ``aria-label`` and the
+    //      ``title`` attribute so the icon gets a hover tooltip and
+    //      a screen-reader announcement without the consumer having
+    //      to wire anything else.
+    const { Sidebar } = await import("./sidebar.tsx");
+
+    const navConfig: NavGroup[] = [
+      {
+        label: "Workspaces",
+        items: [
+          {
+            to: "/spaces/wsA",
+            label: "Workspace With Failures",
+            icon: FolderOpen,
+            statusIcon: {
+              icon: AlertTriangle,
+              tone: "warning",
+              label: "3 documents failed to index",
+            },
+          },
+          {
+            to: "/spaces/wsB",
+            label: "Healthy Workspace",
+            icon: FolderOpen,
+          },
+        ],
+      },
+    ];
+    useNavStore.getState().setConfig(navConfig);
+    useAppStore.setState({
+      currentPage: "/spaces/wsA",
+      threadActive: false,
+      contextItems: [],
+      sentContext: {},
+      highlights: [],
+      selectedItemId: null,
+      content: {},
+    });
+
+    await act(async () => {
+      root.render(
+        <MemoryRouter initialEntries={["/spaces/wsA"]}>
+          <TooltipProvider>
+            <Sidebar />
+          </TooltipProvider>
+        </MemoryRouter>,
+      );
+    });
+
+    // The warning row carries the icon wrapped in a span. The label
+    // lands on both ``aria-label`` (screen reader) and ``title``
+    // (hover tooltip) on the wrapping span; the inner svg carries
+    // the tone class.
+    const warningWrappers = container.querySelectorAll<HTMLElement>(
+      'span[aria-label="3 documents failed to index"]',
+    );
+    expect(warningWrappers.length).toBeGreaterThan(0);
+    const wrapper = warningWrappers[0];
+    expect(wrapper.getAttribute("title")).toBe("3 documents failed to index");
+    expect(wrapper.querySelector("svg.text-warning")).not.toBeNull();
+
+    // No statusIcon on the healthy workspace ⇒ its leaf row
+    // contains no warning svg. Workspaces are rendered as NavLink
+    // anchors (button is for folders), so scope to ``a, button``
+    // and reject ancestor containers that happen to enclose BOTH
+    // workspaces.
+    const healthyRowLeaves = Array.from(
+      container.querySelectorAll<HTMLElement>("a, button"),
+    ).filter((el) => el.textContent?.includes("Healthy Workspace"));
+    expect(healthyRowLeaves.length).toBeGreaterThan(0);
+    for (const leaf of healthyRowLeaves) {
+      expect(leaf.querySelectorAll("svg.text-warning").length).toBe(0);
+    }
+  });
+});
+
+describe("Sidebar group priority + collapse + status bubble-up", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let originalActEnvironment: boolean | undefined;
+  let originalInnerWidth: number;
+  let originalMatchMedia: typeof window.matchMedia | undefined;
+
+  beforeEach(() => {
+    originalActEnvironment = globalThis.IS_REACT_ACT_ENVIRONMENT;
+    originalInnerWidth = window.innerWidth;
+    originalMatchMedia = window.matchMedia;
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+    localStorage.clear();
+    window.innerWidth = 1280;
+    Object.defineProperty(window, "matchMedia", {
+      configurable: true,
+      writable: true,
+      value:
+        originalMatchMedia ||
+        ((query: string) =>
+          ({
+            matches: false,
+            media: query,
+            onchange: null,
+            addListener: () => {},
+            removeListener: () => {},
+            addEventListener: () => {},
+            removeEventListener: () => {},
+            dispatchEvent: () => false,
+          })),
+    });
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    act(() => {
+      root = createRoot(container);
+    });
+    useSidebarStore.setState({ collapsed: false, width: SIDEBAR_WIDTH });
+    useNavStore.setState({ groups: [], config: [] } as Parameters<
+      typeof useNavStore.setState
+    >[0]);
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+    globalThis.IS_REACT_ACT_ENVIRONMENT = originalActEnvironment;
+    window.innerWidth = originalInnerWidth;
+    if (originalMatchMedia) {
+      Object.defineProperty(window, "matchMedia", {
+        configurable: true,
+        writable: true,
+        value: originalMatchMedia,
+      });
+    } else {
+      // @ts-expect-error deleting configurable test override
+      delete window.matchMedia;
+    }
+  });
+
+  function indexOfLabel(label: string): number {
+    const headers = Array.from(
+      container.querySelectorAll<HTMLElement>("[data-nav-group-label]"),
+    );
+    return headers.findIndex(
+      (el) => el.getAttribute("data-nav-group-label") === label,
+    );
+  }
+
+  it("sorts groups by NavGroup.priority desc (higher priority first)", async () => {
+    const { Sidebar } = await import("./sidebar.tsx");
+    const navConfig: NavGroup[] = [
+      {
+        label: "Low",
+        priority: 10,
+        items: [{ to: "/low", label: "Low item", icon: FolderOpen }],
+      },
+      {
+        label: "High",
+        priority: 100,
+        items: [{ to: "/high", label: "High item", icon: FolderOpen }],
+      },
+      {
+        label: "Mid",
+        priority: 50,
+        items: [{ to: "/mid", label: "Mid item", icon: FolderOpen }],
+      },
+    ];
+    useNavStore.getState().setConfig(navConfig);
+
+    await act(async () => {
+      root.render(
+        <MemoryRouter initialEntries={["/"]}>
+          <TooltipProvider>
+            <Sidebar />
+          </TooltipProvider>
+        </MemoryRouter>,
+      );
+    });
+
+    const idxHigh = indexOfLabel("High");
+    const idxMid = indexOfLabel("Mid");
+    const idxLow = indexOfLabel("Low");
+    expect(idxHigh).toBeGreaterThanOrEqual(0);
+    expect(idxMid).toBeGreaterThan(idxHigh);
+    expect(idxLow).toBeGreaterThan(idxMid);
+  });
+
+  it("collapsing a group hides its children and persists to localStorage", async () => {
+    const { Sidebar } = await import("./sidebar.tsx");
+    const navConfig: NavGroup[] = [
+      {
+        label: "Recents",
+        collapsible: true,
+        items: [
+          { to: "/chat/1", label: "First chat", icon: MessageSquare },
+          { to: "/chat/2", label: "Second chat", icon: MessageSquare },
+        ],
+      },
+    ];
+    useNavStore.getState().setConfig(navConfig);
+
+    await act(async () => {
+      root.render(
+        <MemoryRouter initialEntries={["/"]}>
+          <TooltipProvider>
+            <Sidebar />
+          </TooltipProvider>
+        </MemoryRouter>,
+      );
+    });
+
+    // Children visible initially (count varies — the sidebar may
+    // also render an icon-only tooltip mirror in jsdom; we only care
+    // that "First chat" appears at least once now and disappears
+    // after collapse).
+    const childTextBefore = container.textContent ?? "";
+    expect(childTextBefore).toContain("First chat");
+    expect(childTextBefore).toContain("Second chat");
+
+    // Click the group header toggle button.
+    const headerToggle = container.querySelector<HTMLElement>(
+      '[data-nav-group-label="Recents"] [data-nav-group-toggle]',
+    );
+    expect(headerToggle).toBeTruthy();
+    await act(async () => {
+      headerToggle!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    // Children gone after collapse.
+    const childTextAfter = container.textContent ?? "";
+    expect(childTextAfter).not.toContain("First chat");
+    expect(childTextAfter).not.toContain("Second chat");
+
+    // Persisted to localStorage under the generic package-scoped key.
+    const persisted = JSON.parse(
+      localStorage.getItem("sidebar-nav-collapsed") ?? "{}",
+    );
+    expect(persisted.Recents).toBe(true);
+  });
+
+  it("child statusDot bubbles up to the collapsed group header", async () => {
+    const { Sidebar } = await import("./sidebar.tsx");
+    const navConfig: NavGroup[] = [
+      {
+        label: "Recents",
+        collapsible: true,
+        defaultCollapsed: true,
+        items: [
+          {
+            to: "/chat/active",
+            label: "Active chat",
+            icon: MessageSquare,
+            statusDot: { tone: "primary", srLabel: "active" },
+          },
+          { to: "/chat/idle", label: "Idle chat", icon: MessageSquare },
+        ],
+      },
+    ];
+    useNavStore.getState().setConfig(navConfig);
+
+    await act(async () => {
+      root.render(
+        <MemoryRouter initialEntries={["/"]}>
+          <TooltipProvider>
+            <Sidebar />
+          </TooltipProvider>
+        </MemoryRouter>,
+      );
+    });
+
+    const header = container.querySelector<HTMLElement>(
+      '[data-nav-group-label="Recents"]',
+    );
+    expect(header).toBeTruthy();
+    // The bubbled-up dot is rendered with the same status-dot marker
+    // as a child status dot; scope the lookup to the header.
+    const bubble = header!.querySelector<HTMLElement>("[data-nav-status-dot]");
+    expect(bubble).toBeTruthy();
+  });
 });

package/src/components/sidebar.tsx

@@ -1,6 +1,6 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { NavLink, useNavigate } from "react-router";
-import { Ellipsis, Layers, PanelLeft, PanelLeftOpen, SquarePen, ChevronRight, GripVertical, Plus, Upload } from "lucide-react";
+import { Ellipsis, Layers, PanelLeft, PanelLeftOpen, SquarePen, ChevronDown, ChevronRight, GripVertical, Plus, Upload } from "lucide-react";
 import { cn } from "@iloveagents/foundry-web-primitives";
 import {
   useSidebarStore,
@@ -12,7 +12,7 @@ import { useToolPanelStore } from "../lib/tool-panel-store.ts";
 import { useNewConversation } from "../lib/use-new-conversation.ts";
 import { useNavStore } from "../lib/nav-store.ts";
 import { useAppStore } from "../lib/app-store.ts";
-import type { NavItem, NavItemDnd } from "../lib/nav-config.ts";
+import type { NavGroup, NavItem, NavItemDnd } from "../lib/nav-config.ts";
 import { getContainerDropZoneLabel, hasAnyDropTarget, hasExternalFilesData } from "../lib/nav-dnd.ts";
 import { TooltipIconButton } from "./tooltip-icon-button.tsx";
 import { Button } from "@iloveagents/foundry-web-primitives";
@@ -28,6 +28,7 @@ const ACTIVE_NAV_BADGE_CLASS =
 const NESTED_NAV_INDENTS = ["pl-5", "pl-7", "pl-9", "pl-11", "pl-13"] as const;
 
 type NavStatusDot = NonNullable<NavItem["statusDot"]>;
+type NavStatusIcon = NonNullable<NavItem["statusIcon"]>;
 
 function getNestedNavIndent(depth: number) {
   return NESTED_NAV_INDENTS[depth] ?? NESTED_NAV_INDENTS[NESTED_NAV_INDENTS.length - 1];
@@ -53,19 +54,63 @@ function statusDotColor(tone: NavStatusDot["tone"]) {
 
 function NavStatusDot({ statusDot }: { statusDot?: NavStatusDot }) {
   if (!statusDot) return null;
+  // Both "pending" (impact in progress) and "info" (live / active —
+  // e.g. the currently-resumed chat conversation) pulse so the eye is
+  // drawn to "something is happening / you are here right now".
+  // Other tones render static.
+  const pulse = statusDot.tone === "pending" || statusDot.tone === "info";
   return (
     <span
+      data-nav-status-dot
+      data-nav-status-tone={statusDot.tone}
       aria-label={statusDot.label}
       title={statusDot.label}
       className={cn(
         "size-1.5 shrink-0 rounded-full opacity-90",
-        statusDot.tone === "pending" && "animate-pulse",
+        pulse && "animate-pulse",
       )}
       style={{ backgroundColor: statusDotColor(statusDot.tone) }}
     />
   );
 }
 
+function statusIconClass(tone: NavStatusIcon["tone"]) {
+  switch (tone) {
+    case "warning":
+      return "text-warning";
+    case "danger":
+      return "text-destructive";
+    case "info":
+      return "text-primary";
+    case "neutral":
+    default:
+      return "text-sidebar-foreground/60";
+  }
+}
+
+function NavStatusIcon({ statusIcon }: { statusIcon?: NavStatusIcon }) {
+  if (!statusIcon) return null;
+  const Icon = statusIcon.icon;
+  // Wrap in a ``<span>`` so the browser tooltip (``title``) and the
+  // screen-reader announcement (``aria-label``) attach to a real DOM
+  // node — lucide-react's icon types don't accept ``title`` as a
+  // prop. Kept small (size-3) so the icon doesn't compete with the
+  // entity icon on the left of the row.
+  return (
+    <span
+      role="img"
+      aria-label={statusIcon.label}
+      title={statusIcon.label}
+      className="inline-flex shrink-0"
+    >
+      <Icon
+        aria-hidden="true"
+        className={cn("size-3 shrink-0", statusIconClass(statusIcon.tone))}
+      />
+    </span>
+  );
+}
+
 // --- Generic drag-and-drop via NavItem.dnd ---
 
 /** Shared drag-and-drop props derived from NavItem.dnd (feature-provided). */
@@ -447,6 +492,7 @@ function NavLeafItem({
               {item.badge}
             </span>
           )}
+          <NavStatusIcon statusIcon={item.statusIcon} />
           <NavStatusDot statusDot={item.statusDot} />
         </button>
         {/* File-drop hint icon — rendered as an inline flex sibling so it
@@ -505,6 +551,7 @@ function NavLeafItem({
           {item.badge}
         </span>
       )}
+      <NavStatusIcon statusIcon={item.statusIcon} />
       <NavStatusDot statusDot={item.statusDot} />
       {isFileDragOver && !isDisabled && (
         <Upload
@@ -676,6 +723,7 @@ function NestedFolderItem({ item, depth }: { item: NavItem; depth: number }) {
               {item.badge}
             </span>
           )}
+          <NavStatusIcon statusIcon={item.statusIcon} />
           <NavStatusDot statusDot={item.statusDot} />
         </button>
         {/* File-drop hint icon — inline flex sibling so it sits to the
@@ -818,6 +866,7 @@ function CollapsibleNavItem({ item }: { item: NavItem }) {
               {item.badge}
             </span>
           )}
+          <NavStatusIcon statusIcon={item.statusIcon} />
           <NavStatusDot statusDot={item.statusDot} />
         </button>
         {/* File-drop hint icon — inline flex sibling so it sits to the
@@ -904,6 +953,7 @@ function CollapsibleNavItem({ item }: { item: NavItem }) {
               {item.badge}
             </span>
           )}
+          <NavStatusIcon statusIcon={item.statusIcon} />
           <NavStatusDot statusDot={item.statusDot} />
           {isFileDragOver && (
             <Upload
@@ -994,17 +1044,10 @@ function SidebarResizeHandle() {
   );
 }
 
-function ThreadIndicator() {
-  const threadActive = useAppStore((s) => s.threadActive);
-  if (!threadActive) return null;
-
-  return (
-    <div className="px-4 pb-2 flex items-center gap-2">
-      <span className="text-xs text-muted-foreground">Active thread</span>
-      <div className="size-1.5 rounded-full bg-primary animate-pulse" />
-    </div>
-  );
-}
+// ThreadIndicator (the "Active thread •" badge under New Thread) was
+// removed — the active conversation's selected row in the Recents
+// group is now the source of truth for "you're in a chat right now".
+// Kept as a comment so future spelunkers know it was intentional.
 
 function CollapsedNavShortcut({
   to,
@@ -1030,10 +1073,264 @@ function CollapsedNavShortcut({
   );
 }
 
+// ---------------------------------------------------------------------------
+// Collapsible nav-group state — persisted per-label in localStorage so the
+// user's "minimised Admin section" choice survives reloads. A single JSON
+// blob keyed on label means we only touch one storage key per render and
+// we can subscribe via useSyncExternalStore for cheap cross-component
+// updates (toggle one group, all SidebarContent instances re-render).
+// ---------------------------------------------------------------------------
+
+// Generic package-scoped key — ``foundry-web-ui`` is consumed beyond
+// the Spaces app, so we avoid consumer-specific names like
+// ``spaces.nav.collapsed``. Matches the keying style used by the
+// adjacent sidebar-store helpers (``sidebar``, ``sidebar-width``,
+// ``theme``).
+const COLLAPSE_STORAGE_KEY = "sidebar-nav-collapsed";
+type CollapseMap = Record<string, boolean>;
+
+let _collapseCache: CollapseMap | null = null;
+const _collapseListeners = new Set<() => void>();
+
+function readCollapseMap(): CollapseMap {
+  if (_collapseCache) return _collapseCache;
+  if (typeof window === "undefined") {
+    _collapseCache = {};
+    return _collapseCache;
+  }
+  try {
+    const raw = window.localStorage.getItem(COLLAPSE_STORAGE_KEY);
+    _collapseCache = raw ? (JSON.parse(raw) as CollapseMap) : {};
+  } catch {
+    _collapseCache = {};
+  }
+  return _collapseCache;
+}
+
+function writeCollapseMap(next: CollapseMap): void {
+  _collapseCache = next;
+  if (typeof window !== "undefined") {
+    try {
+      window.localStorage.setItem(COLLAPSE_STORAGE_KEY, JSON.stringify(next));
+    } catch {
+      // localStorage full / disabled — toggle still works in-memory for
+      // this page session.
+    }
+  }
+  for (const fn of _collapseListeners) fn();
+}
+
+function subscribeCollapse(fn: () => void): () => void {
+  _collapseListeners.add(fn);
+  return () => {
+    _collapseListeners.delete(fn);
+  };
+}
+
+/**
+ * Read the persisted collapse state for a single group. ``defaultCollapsed``
+ * is the fallback when the user has never toggled this group.
+ */
+function useGroupCollapsed(label: string, defaultCollapsed: boolean | undefined): boolean {
+  const map = useSyncExternalStore(subscribeCollapse, readCollapseMap, readCollapseMap);
+  // Use ``hasOwnProperty`` instead of the ``in`` operator so a label
+  // that happens to collide with a prototype key (e.g. ``toString``,
+  // ``__proto__``, ``constructor``) is not treated as a persisted
+  // entry. ``map`` is parsed JSON so its prototype is ``Object``'s.
+  return Object.prototype.hasOwnProperty.call(map, label)
+    ? map[label]
+    : Boolean(defaultCollapsed);
+}
+
+function toggleGroupCollapsed(label: string, current: boolean): void {
+  writeCollapseMap({ ...readCollapseMap(), [label]: !current });
+}
+
+/**
+ * Walk a group's items (and their children) to find the first statusDot.
+ * Used to "bubble up" the active-chat indicator onto a collapsed group
+ * header — so the user never loses sight of "your active conversation is
+ * inside this minimised section".
+ */
+function findFirstStatusDot(items: readonly NavItem[]): NavStatusDot | undefined {
+  for (const item of items) {
+    if (item.statusDot) return item.statusDot;
+    if (item.children && item.children.length > 0) {
+      const nested = findFirstStatusDot(item.children);
+      if (nested) return nested;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Render a single nav group: label header (with optional collapse
+ * chevron + bubbled-up status dot) + child items. Pulled out into its
+ * own component so each group's collapse state is its own hook scope
+ * — toggling one doesn't re-render siblings.
+ */
+function NavGroupSection({ group }: { group: NavGroup }) {
+  // hideLabel + collapsible are mutually exclusive — a hidden label
+  // can't host a chevron. The collapsible flag is the opt-in; legacy
+  // groups stay uncollapsable so behaviour is unchanged.
+  const isCollapsible = !group.hideLabel && Boolean(group.collapsible);
+  const persistedCollapsed = useGroupCollapsed(group.label, group.defaultCollapsed);
+  const collapsed = isCollapsible && persistedCollapsed;
+  // Bubble: show the first child statusDot on the collapsed header so
+  // the user never loses sight of "the active chat is inside this
+  // minimised group". Only render when actually collapsed.
+  const bubbledStatusDot = collapsed ? findFirstStatusDot(group.items) : undefined;
+
+  return (
+    <div data-nav-group-label={group.label}>
+      {!group.hideLabel && (
+        <div className="px-3 py-2">
+          {isCollapsible ? (
+            // Collapsible header is a flex of three siblings: chevron
+            // toggle (own button), label (NavLink when ``group.to``
+            // is set so the user can still navigate to the group
+            // landing page — Workspaces does this), createActions
+            // menu. Three SIBLINGS, not nested, so HTML stays valid
+            // (no <button> inside <button> / inside Radix's button).
+            <div className="group/header flex items-center justify-between rounded-lg transition-colors hover:bg-sidebar-accent/70">
+              <button
+                type="button"
+                data-nav-group-toggle
+                onClick={() => toggleGroupCollapsed(group.label, persistedCollapsed)}
+                aria-expanded={!collapsed}
+                aria-label={collapsed ? `Expand ${group.label}` : `Collapse ${group.label}`}
+                className="inline-flex size-6 shrink-0 items-center justify-center rounded text-sidebar-foreground/50 hover:text-sidebar-foreground"
+              >
+                {collapsed ? (
+                  <ChevronRight className="size-3 transition-transform" />
+                ) : (
+                  <ChevronDown className="size-3 transition-transform" />
+                )}
+              </button>
+              {group.to ? (
+                <NavLink to={group.to} end className="flex min-w-0 flex-1 items-center gap-1.5 py-1.5">
+                  {({ isActive }) => (
+                    <>
+                      <span
+                        className={cn(
+                          "truncate text-xs font-medium uppercase tracking-wider",
+                          isActive
+                            ? "text-sidebar-selected-foreground"
+                            : "text-sidebar-foreground/65 group-hover/header:text-sidebar-foreground",
+                        )}
+                      >
+                        {group.label}
+                      </span>
+                      <NavStatusDot statusDot={bubbledStatusDot} />
+                    </>
+                  )}
+                </NavLink>
+              ) : (
+                <button
+                  type="button"
+                  onClick={() => toggleGroupCollapsed(group.label, persistedCollapsed)}
+                  className="flex min-w-0 flex-1 items-center gap-1.5 py-1.5 text-left"
+                >
+                  <span className="truncate text-xs font-medium uppercase tracking-wider text-sidebar-foreground/65 group-hover/header:text-sidebar-foreground">
+                    {group.label}
+                  </span>
+                  <NavStatusDot statusDot={bubbledStatusDot} />
+                </button>
+              )}
+              {group.createActions && group.createActions.length > 0 && (
+                <CreateActionsMenu group={group} />
+              )}
+            </div>
+          ) : group.to ? (
+            <div className="flex items-center justify-between rounded-lg py-1.5 transition-colors hover:bg-sidebar-accent/70">
+              <NavLink to={group.to} end className="min-w-0 flex-1">
+                {({ isActive }) => (
+                  <span
+                    className={cn(
+                      "block text-xs font-medium uppercase tracking-wider",
+                      isActive
+                        ? "text-sidebar-selected-foreground"
+                        : "text-sidebar-foreground/65 hover:text-sidebar-foreground",
+                    )}
+                  >
+                    {group.label}
+                  </span>
+                )}
+              </NavLink>
+              {group.createActions && group.createActions.length > 0 && (
+                <CreateActionsMenu group={group} />
+              )}
+            </div>
+          ) : (
+            <span className="text-xs font-medium uppercase tracking-wider text-sidebar-foreground/65">
+              {group.label}
+            </span>
+          )}
+        </div>
+      )}
+      {!collapsed &&
+        group.items.map((item) => (
+          <CollapsibleNavItem key={item.to + item.label} item={item} />
+        ))}
+    </div>
+  );
+}
+
+/**
+ * The "+" dropdown shown next to a group label when the group declares
+ * ``createActions``. Pulled out so both the collapsible-button branch
+ * and the legacy plain-label branch can render it identically.
+ *
+ * The trigger button stops click propagation so opening the menu
+ * doesn't also toggle the surrounding collapsible-header button.
+ */
+function CreateActionsMenu({ group }: { group: NavGroup }) {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          onClick={(e) => e.stopPropagation()}
+          className="inline-flex size-6 items-center justify-center text-sidebar-foreground/65 transition-colors hover:text-sidebar-foreground"
+          aria-label={`Create in ${group.label}`}
+        >
+          <Plus className="size-4" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-48">
+        {(group.createActions ?? []).map((action) => (
+          <DropdownMenuItem
+            key={action.id}
+            onSelect={(e) => {
+              e.preventDefault();
+              action.handler();
+            }}
+          >
+            {action.label}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
 function SidebarContent({ collapsed }: { collapsed: boolean }) {
   const toggle = useSidebarStore((s) => s.toggle);
   const handleNewConversation = useNewConversation();
-  const navConfig = useNavStore((s) => s.config);
+  const rawNavConfig = useNavStore((s) => s.config);
+  // Sort by `priority` descending so feature hooks can declare slot
+  // intent (e.g. "Recents above Tasks") instead of relying on the
+  // order in which addGroup() happened to be called. Stable sort: ties
+  // preserve insertion order, so groups that don't set a priority keep
+  // the legacy append-where-you-arrive behaviour.
+  const navConfig = useMemo(
+    () =>
+      [...rawNavConfig]
+        .map((g, i) => ({ g, i, p: g.priority ?? 0 }))
+        .sort((a, b) => b.p - a.p || a.i - b.i)
+        .map(({ g }) => g),
+    [rawNavConfig],
+  );
   const currentPage = useAppStore((s) => s.currentPage);
   const navContext = useAppStore((s) => s.navContext);
 
@@ -1147,7 +1444,9 @@ function SidebarContent({ collapsed }: { collapsed: boolean }) {
         </button>
       </div>
 
-      <ThreadIndicator />
+      {/* ThreadIndicator removed — the active conversation's row in
+          the Recents group is now the source of truth for "you're in a
+          chat right now". A separate pulsing dot was redundant noise. */}
 
       {/* Navigation groups */}
       <nav
@@ -1156,63 +1455,7 @@ function SidebarContent({ collapsed }: { collapsed: boolean }) {
         onDropCapture={preventNativeFileDrop}
       >
         {navConfig.map((group) => (
-          <div key={group.label}>
-            {!group.hideLabel && (
-              <div className="px-3 py-2">
-                {group.to ? (
-                  <div className="flex items-center justify-between rounded-lg py-1.5 transition-colors hover:bg-sidebar-accent/70">
-                    <NavLink to={group.to} end className="min-w-0 flex-1">
-                      {({ isActive }) => (
-                        <span
-                          className={cn(
-                            "block text-xs font-medium uppercase tracking-wider",
-                            isActive
-                              ? "text-sidebar-selected-foreground"
-                              : "text-sidebar-foreground/65 hover:text-sidebar-foreground",
-                          )}
-                        >
-                          {group.label}
-                        </span>
-                      )}
-                    </NavLink>
-                    {group.createActions && group.createActions.length > 0 && (
-                      <DropdownMenu>
-                        <DropdownMenuTrigger asChild>
-                          <button
-                            type="button"
-                            className="inline-flex size-6 items-center justify-center text-sidebar-foreground/65 transition-colors hover:text-sidebar-foreground"
-                            aria-label={`Create in ${group.label}`}
-                          >
-                            <Plus className="size-4" />
-                          </button>
-                        </DropdownMenuTrigger>
-                        <DropdownMenuContent align="end" className="w-48">
-                          {group.createActions.map((action) => (
-                            <DropdownMenuItem
-                              key={action.id}
-                              onSelect={(e) => {
-                                e.preventDefault();
-                                action.handler();
-                              }}
-                            >
-                              {action.label}
-                            </DropdownMenuItem>
-                          ))}
-                        </DropdownMenuContent>
-                      </DropdownMenu>
-                    )}
-                  </div>
-                ) : (
-                  <span className="text-xs font-medium uppercase tracking-wider text-sidebar-foreground/65">
-                    {group.label}
-                  </span>
-                )}
-              </div>
-            )}
-            {group.items.map((item) => (
-              <CollapsibleNavItem key={item.to + item.label} item={item} />
-            ))}
-          </div>
+          <NavGroupSection key={group.label} group={group} />
         ))}
       </nav>
 

package/src/index.ts

@@ -5,6 +5,10 @@ export { ToolPanelLayout } from "./components/tool-panel-layout.tsx";
 export { MarkdownText, markdownComponents } from "./components/markdown-text.tsx";
 export { ClientToolExecutor } from "./components/client-tool-executor.tsx";
 export { AGUIRuntimeProvider, useAGUIAdapter } from "./components/ag-ui-runtime-provider.tsx";
+export type {
+  AGUIChatConversationFactoryArgs,
+  AGUIHistoryAdapterFactory,
+} from "./components/ag-ui-runtime-provider.tsx";
 export { ChatContent, DEFAULT_STARTER_SUGGESTIONS } from "./components/assistant-chat.tsx";
 export type { ChatContentProps } from "./components/assistant-chat.tsx";
 export { ChatBubble } from "./components/chat-bubble.tsx";

package/src/lib/nav-config.ts

@@ -60,6 +60,17 @@ export interface NavItem {
     tone?: "neutral" | "info" | "low-impact" | "medium-impact" | "high-impact" | "pending";
     label?: string;
   };
+  /**
+   * Optional warning / status icon shown after the label. Use for
+   * "something needs attention" annotations (e.g. failed indexing,
+   * permission drift) where a coloured dot isn't legible enough.
+   * Pass any LucideIcon; the tone drives the colour.
+   */
+  statusIcon?: {
+    icon: LucideIcon;
+    tone?: "neutral" | "info" | "warning" | "danger";
+    label?: string;
+  };
   /** Page description sent to the agent for context */
   description?: string;
   /** Arbitrary metadata sent to the agent (e.g., workspace IDs, entity types) */
@@ -102,6 +113,27 @@ export interface CollapsedRailContext {
 export interface NavGroup {
   label: string;
   items: NavItem[];
+  /**
+   * Render order weight. Higher = higher in the sidebar. Default 0.
+   * Ties keep insertion order (stable sort), so existing call sites
+   * that don't set a priority preserve the legacy "addGroup appends"
+   * behaviour. Use this to pin a group to a specific slot regardless
+   * of which feature hook finishes first.
+   */
+  priority?: number;
+  /**
+   * When true, the group header gets a click-to-toggle chevron and
+   * the children hide when collapsed. State persists per group label
+   * in localStorage so the user's preference survives reloads. Mutually
+   * exclusive with ``hideLabel`` — a hidden label can't host a chevron.
+   *
+   * If any child carries a :attr:`NavItem.statusDot`, it bubbles up to
+   * the collapsed header so the user can still see "the active chat is
+   * inside this collapsed group" without auto-expanding.
+   */
+  collapsible?: boolean;
+  /** Initial collapse state when no user preference is stored. */
+  defaultCollapsed?: boolean;
   /** Optional link for the group header label */
   to?: string;
   /** Hide the group header while preserving group semantics. */

package/src/lib/use-new-conversation.test.tsx

@@ -131,7 +131,13 @@ describe("useNewConversation", () => {
     expect(useToolPanelStore.getState().isOpen).toBe(false);
     expect(useSidebarStore.getState().isMobileOpen).toBe(false);
     expect(citationStore.getState().results).toEqual([]);
-    expect(citationStore.getState().handler).toBeNull();
+    // Handler is module-level state registered once at app boot by
+    // feature modules (e.g. SPACES' ``registerSpacesCitationHandler``)
+    // and MUST survive per-conversation resets — wiping it here would
+    // make every ``[n]`` marker inert for the rest of the session,
+    // since the registration guard suppresses re-binding. See
+    // ``packages/agent/src/store/citation-store.ts``.
+    expect(citationStore.getState().handler).not.toBeNull();
   });
 
   it("can reset the thread without leaving the current page", async () => {