zidane-ui 0.0.0-stage → 9.0.2

package/src/chat/sidebar/SessionSidebar.tsx

@@ -0,0 +1,805 @@
+/**
+ * The session sidebar, whole: its frame (`SidebarFrame`), the top band (the
+ * orchestration Main, New session, the search well with the filter menu),
+ * the list (grouped sections whose headers stick, the search results, one
+ * list per space that slides on a user switch) and the footer the app puts
+ * under it. The keyboard walks the list (`useSidebarKeyboardNav`).
+ *
+ * The data comes in as props, the session directory's view
+ * (`useSessionDirectoryView`) with the app's actions; the live parts of the
+ * rows from the app's {@link SidebarLive}; the platform rows of the menus
+ * from the `SidebarHost` in context.
+ */
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import {
+  AnimatePresence,
+  domAnimation,
+  LazyMotion,
+  m,
+  useIsPresent,
+  type HTMLMotionProps,
+  type Variants,
+} from 'motion/react';
+import type { SessionEnvironmentSummary } from 'zidane/chat';
+import type { Space } from 'zidane/chat/pure';
+
+import { KeyHint } from '../../keybindings/KeyHint';
+import { useWithFade } from '../../motion/springs';
+import { basename } from '../../path';
+import { SessionHostHeader } from '../SessionHostHeader';
+import { ShowMoreRow } from '../SessionGroupHeader';
+import type { HostView } from '../headless/hosts';
+import { MAIN_SESSION_ICON_KEY } from '../headless/sidebar/project-icons';
+import {
+  buildHostSidebarRows,
+  groupsByFolder,
+  nestSidebarRows,
+  partitionMainSession,
+  type SidebarNode,
+  type SidebarRow,
+} from '../headless/sidebar/rows';
+import type {
+  SessionArchiveFilter,
+  SidebarGroupBy,
+  SidebarListSession,
+  SidebarSortBy,
+} from '../headless/sidebar/types';
+import { MainSessionRow } from './MainSessionRow';
+import { useProjectIcons } from './ProjectIcon';
+import type { RowProject } from './RowChips';
+import { useEnvironmentCommands, type SidebarProject } from './session-menu';
+import { holdFocusIn } from './sidebar-focus-hold';
+import { SidebarFrame, useSidebarFrame, type SidebarChromeInset } from './SidebarFrame';
+import { SidebarGroupHeader } from './SidebarGroupHeader';
+import type { SidebarLive } from './sidebar-live';
+import { useSidebarNotice } from './SidebarHostProvider';
+import { SidebarSearchRow } from './SidebarSearchRow';
+import { SidebarSessionRow } from './SidebarSessionRow';
+import { usePinnedProjects } from './usePinnedProjects';
+import { useSessionSearch, type SessionContentSearch } from './useSessionSearch';
+import { useSidebarKeyboardNav } from './useSidebarKeyboardNav';
+import { useSidebarLabels } from './useSidebarLabels';
+
+/** A session as the sidebar's rows read it: the list's session plus where it runs when not here. */
+export interface SidebarRowSession extends SidebarListSession {
+  /** Its environment, when it runs somewhere else than this machine's folder. */
+  environment?: SessionEnvironmentSummary;
+}
+
+/** The space switch that showed the list's space: the list slides that way. */
+export interface SidebarSpaceSlide {
+  /** The space switched to. */
+  spaceId: string;
+  /** Toward a later space, or an earlier one. */
+  direction: 'next' | 'prev';
+}
+
+/** Props of {@link SessionSidebar}. */
+export interface SessionSidebarProps<S extends SidebarRowSession> {
+  /** The sessions the list shows (the shown space's filters applied). */
+  sessions: readonly S[];
+  /** This machine and the remote hosts (their sections and chips). */
+  hosts: readonly HostView[];
+  /** How the rows group. */
+  groupBy: SidebarGroupBy;
+  /** How the rows sort inside a group. */
+  sortBy: SidebarSortBy;
+  /** The archive axis, for the content search. */
+  archiveFilter: SessionArchiveFilter;
+  /** The open session. */
+  activeSessionId: S['id'] | null;
+  /** Opens a session (`null`: the new-session surface). */
+  onActivate: (sessionId: S['id'] | null) => void;
+  /** The orchestration Main is on: its session is pinned above the groups. Off: it is hidden. */
+  orchestration: boolean;
+  /** Spaces are on. */
+  spacesOn: boolean;
+  /** The spaces. */
+  spaces: readonly Space[];
+  /** The space the list shows (`listSpaceId`). */
+  listSpaceId: string;
+  /** The last user switch of space; the list slides when it showed `listSpaceId`. */
+  spaceSlide: SidebarSpaceSlide | null;
+  /** Content search. Absent: titles only. */
+  search?: SessionContentSearch;
+  /** The rows' live parts (`createSidebarLive`, built once). */
+  live: SidebarLive;
+  /** What runs are doing in the trailing slot. Default: true. */
+  runDetails?: boolean;
+  /** Artifacts on a second line. Default: true. */
+  artifactBadges?: boolean;
+  /** Starts a new session. */
+  onNewSession: () => void;
+  /** Starts a new session in a project's folder. */
+  onNewSessionIn: (path: string) => void;
+  /** Renames a session. */
+  onRename: (sessionId: S['id'], title: string) => Promise<void>;
+  /** Archives or restores a session. */
+  onSetArchived: (sessionId: S['id'], archived: boolean) => Promise<void>;
+  /** Stars or unstars a session. */
+  onSetFavorite: (sessionId: S['id'], favorite: boolean) => Promise<void>;
+  /** Deletes a session (ask first: `useConfirmDeleteSession`). */
+  onDelete: (session: { id: S['id']; title: string; environment?: SessionEnvironmentSummary }) => void;
+  /** Moves a session to a space. Absent: no move rows. */
+  onMoveToSpace?: (sessionId: S['id'], spaceId: string) => Promise<unknown>;
+  /** Moves a session to another environment of its host (`useMoveSession`, `zidane-ui/git`). Absent: no "Move to…". */
+  onMoveSession?: (sessionId: S['id']) => void;
+  /** Moves a project to a space. Absent: no move rows on the headers. */
+  onMoveProjectToSpace?: (project: SidebarProject, spaceId: string) => Promise<unknown>;
+  /** Archives a project's conversations (`useProjectSessionActions`). */
+  onArchiveProject: (project: SidebarProject, label: string) => void;
+  /** Deletes a project's conversations; `onRemoved` unpins it once they are gone. */
+  onDeleteProject: (project: SidebarProject, label: string, onRemoved: () => void) => void;
+  /** The keys belong elsewhere now (a modal is open). */
+  keyboardBlocked?: () => boolean;
+  /** Beside the search well: the filter menu. */
+  filter?: ReactNode;
+  /** Under the list: the footer strip. */
+  footer?: ReactNode;
+  /** The user collapsed the sidebar. */
+  collapsed: boolean;
+  /** The width the user wants (px). */
+  width: number;
+  /** A resize ended at this width. */
+  onWidthCommit: (width: number) => void;
+  /** A drag strip clearing the window's native controls. */
+  chromeInset?: SidebarChromeInset;
+  /** Names the aside's landmark (several sidebars on one page each need their own). */
+  ariaLabel?: string;
+  /** Extra classes on the aside. */
+  className?: string;
+  /** Inline styles on the aside. */
+  style?: CSSProperties;
+}
+
+/** The list's top and bottom fades (rows dissolve into the search row and the footer, never cut). */
+const LIST_MASK = 'linear-gradient(to bottom, transparent, black 8px, black calc(100% - 12px), transparent)';
+const LIST_STYLE: CSSProperties = { maskImage: LIST_MASK, WebkitMaskImage: LIST_MASK };
+
+/*
+ * The spaces list slide: `custom` is the direction (1 = to a later space, -1
+ * earlier, 0 = cut). The new list travels a quarter of its width; the leaving
+ * one goes the other way (`popLayout` pulls it out of flow so both share the slot).
+ */
+/** The space list slide's duration (s). */
+const SPACE_SLIDE_S = 0.22;
+
+const SPACE_LIST_VARIANTS: Variants = {
+  enter: (dir: number) => (dir === 0 ? { x: 0, opacity: 1 } : { x: `${dir * 24}%`, opacity: 0 }),
+  center: { x: 0, opacity: 1 },
+  leave: (dir: number) =>
+    dir === 0 ? { opacity: 0, transition: { duration: 0 } } : { x: `${dir * -24}%`, opacity: 0 },
+};
+
+/**
+ * One space's list. While it slides out it is inert, hidden from assistive tech and marked `data-leaving`:
+ * the incoming list (which may hold the same rows) is the only one to act on.
+ */
+const SpaceList = forwardRef<HTMLUListElement, HTMLMotionProps<'ul'>>(function SpaceList(props, ref) {
+  const leaving = !useIsPresent();
+  return (
+    <m.ul
+      ref={ref}
+      {...props}
+      {...(leaving ? { inert: true, 'aria-hidden': true, 'data-leaving': '' } : { 'data-live-list': '' })}
+    />
+  );
+});
+
+/** Props of {@link NewSessionButton}. */
+export interface NewSessionButtonProps {
+  /** Starts a new session. */
+  onNewSession: () => void;
+  /** No session is open: the button is the current selection (the raised chip). */
+  isActive: boolean;
+  /** Extra classes on the wrapper. */
+  className?: string;
+  /** Inline styles on the wrapper. */
+  style?: CSSProperties;
+}
+
+/**
+ * The New session row: the same grid as a session row (an 18px glyph column, `text-sm`), raised while no
+ * session is open, its ⌘N hint fading in on hover or focus.
+ *
+ * @param props - What it starts, whether it is the current selection, `className` and `style`.
+ */
+export function NewSessionButton({ onNewSession, isActive, className = '', style }: NewSessionButtonProps) {
+  const labels = useSidebarLabels();
+  return (
+    <div className={`shrink-0${className ? ` ${className}` : ''}`} style={style}>
+      <button
+        type="button"
+        onClick={onNewSession}
+        title={labels.newSessionTitle}
+        data-active={isActive ? 'true' : undefined}
+        // pl-1 + the band's px-2 puts the 18px glyph slot at x=12 and the label
+        // at x=36: the same columns as the session rows.
+        className="zg-press-subtle group w-full inline-flex items-center gap-1.5 pl-1 pr-2 py-1 rounded-zg-md bg-transparent hover:before:bg-[var(--zg-row-hover)] data-[active=true]:before:bg-[var(--zg-raised)] data-[active=true]:hover:before:bg-[var(--zg-raised)] data-[active=true]:before:[box-shadow:var(--zg-shadow-raised)] text-[var(--zg-text)] cursor-pointer border-0 transition-[background-color,box-shadow] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[var(--zg-ring)]"
+      >
+        <span aria-hidden className="inline-flex items-center justify-center w-[18px] shrink-0">
+          <span className="i-ph-plus text-sm text-[var(--zg-text-muted)] group-data-[active=true]:text-[var(--zg-text)]" />
+        </span>
+        <span className="text-sm text-[var(--zg-text-muted)] group-data-[active=true]:text-[var(--zg-text)]">
+          {labels.newSession}
+        </span>
+        <span className="flex-1" />
+        <KeyHint
+          spec="cmd+n"
+          className="opacity-0 group-hover:opacity-100 group-focus-visible:opacity-100 transition-opacity"
+        />
+      </button>
+    </div>
+  );
+}
+
+const messageOf = (err: unknown): string => (err as Error)?.message ?? String(err);
+
+/**
+ * Renders the session sidebar.
+ *
+ * @param props - The directory's view, the app's actions, the live row parts, the footer and the frame.
+ */
+export function SessionSidebar<S extends SidebarRowSession>(props: SessionSidebarProps<S>) {
+  const {
+    sessions: allSessions,
+    hosts,
+    groupBy,
+    sortBy,
+    archiveFilter,
+    activeSessionId,
+    onActivate,
+    orchestration,
+    spacesOn,
+    spaces,
+    listSpaceId,
+    spaceSlide: lastSpaceSwitch,
+    search,
+    live,
+    runDetails = true,
+    artifactBadges = true,
+    onNewSession,
+    onNewSessionIn: newSessionIn,
+    onRename,
+    onSetArchived,
+    onSetFavorite,
+    onDelete,
+    onMoveToSpace,
+    onMoveSession,
+    onMoveProjectToSpace,
+    onArchiveProject,
+    onDeleteProject: deleteProject,
+    keyboardBlocked,
+    filter,
+    footer,
+    collapsed,
+    width,
+    onWidthCommit,
+    chromeInset,
+    ariaLabel,
+    className,
+    style,
+  } = props;
+  type K = S['id'];
+  const labels = useSidebarLabels();
+  const notify = useSidebarNotice();
+  const environment = useEnvironmentCommands();
+
+  /*
+   * The slide of the user switch that showed this space (switcher, keys,
+   * palette); anything else cuts. Keyed on the list's space, so the list swaps
+   * and slides with the rows it was keyed for.
+   */
+  const slideDirection = lastSpaceSwitch?.spaceId === listSpaceId ? lastSpaceSwitch.direction : null;
+  const slideOffset = slideDirection === 'next' ? 1 : slideDirection === 'prev' ? -1 : 0;
+  /*
+   * The list's identity: it changes only when the user switched spaces, so only
+   * that slides (old list out, new in). Following the open chat, turning Spaces
+   * off, filters: the same list re-renders, nothing doubles.
+   */
+  const lastSlideKey = useRef('list');
+  // eslint-disable-next-line react-hooks/refs -- the key holds across renders until the next user switch
+  if (spacesOn && lastSpaceSwitch?.spaceId === listSpaceId) lastSlideKey.current = lastSpaceSwitch.spaceId;
+  // eslint-disable-next-line react-hooks/refs -- read with the switch above, in the same render
+  const listKey = lastSlideKey.current;
+  // The lists move on `slide`; their opacity fades (`withFade`), never on the spring.
+  // Shorter than `slide`: the new space's rows read as soon as the switcher answers.
+  const slideTransition = useWithFade('slide', SPACE_SLIDE_S);
+
+  /*
+   * The orchestration Main is HIDDEN while the feature is off: showing it as an
+   * ordinary chat while nothing can serve it would invite the user into a
+   * session whose whole purpose is switched off. Applied once, at the source,
+   * so the groups, the search results and the pin all see the same list.
+   */
+  const sessions = useMemo(
+    () => (orchestration ? allSessions : allSessions.filter((s) => s.isMain !== true)),
+    [allSessions, orchestration],
+  );
+
+  const { searchQuery, setSearchQuery, trimmedQuery, searchMode, searching, titleMatches, contentMatches } =
+    useSessionSearch(sessions, archiveFilter, search);
+
+  const [renamingId, setRenamingId] = useState<K | null>(null);
+  const [renameValue, setRenameValue] = useState('');
+  const [menuForId, setMenuForId] = useState<K | null>(null);
+
+  /**
+   * Collapsed group headers. Re-grouping produces fresh ids, so stale entries no longer match and the new
+   * buckets start expanded. Not persisted: collapse is a transient view tweak.
+   */
+  const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(() => new Set());
+  const toggleGroup = useCallback((id: string) => {
+    setCollapsedGroups((current) => {
+      const next = new Set(current);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  }, []);
+
+  /** Groups whose "Show more" row was clicked: they render past the per-project cap. */
+  const [showMoreExpanded, setShowMoreExpanded] = useState<Set<string>>(() => new Set());
+  const expandGroup = useCallback((id: string) => {
+    setShowMoreExpanded((current) => new Set(current).add(id));
+  }, []);
+
+  const { icons: projectIcons, setIcon: setProjectIcon } = useProjectIcons();
+  /** The listed space's projects pinned at the top of the project grouping, in pin order. */
+  const { pinned: pinnedProjects, setPinned: setProjectPinned } = usePinnedProjects(listSpaceId);
+
+  /** The pinned Main renders once, above every group, instead of also in its own bucket. */
+  const { main: mainSession, rest: groupableSessions } = useMemo(
+    () => partitionMainSession(sessions, orchestration),
+    [sessions, orchestration],
+  );
+
+  /**
+   * Sorted + grouped rows. Collapse and the per-project cap are applied inside the builder, so arrow-key nav
+   * (which walks the session rows) can never land on a hidden row.
+   */
+  const rows = useMemo<SidebarRow<S>[]>(
+    () =>
+      buildHostSidebarRows(groupableSessions, hosts, groupBy, sortBy, {
+        collapsedGroups,
+        showMoreExpanded,
+        pinnedProjects,
+      }),
+    [groupableSessions, hosts, groupBy, sortBy, collapsedGroups, showMoreExpanded, pinnedProjects],
+  );
+  /** The rows as the list draws them: each header with the rows under it, a section whose header sticks. */
+  const sections = useMemo(() => nestSidebarRows(rows), [rows]);
+  const hostById = useMemo(() => new Map(hosts.map((h) => [h.id, h])), [hosts]);
+
+  /** This machine's project folders with a listed conversation not archived yet. */
+  const archivableProjects = useMemo(() => {
+    const out = new Set<string>();
+    for (const s of groupableSessions) {
+      if (!s.hostId && !s.archived) out.add((s.projectRoot || s.cwd).replace(/\/+$/, '') || '/');
+    }
+    return out;
+  }, [groupableSessions]);
+
+  /* A favorite has left its project group: its row names the project, with the group's icon. One object per session, so the rows' memo holds. */
+  const favoriteProjects = useMemo(() => {
+    const out = new Map<K, RowProject>();
+    for (const row of rows) {
+      if (row.kind !== 'session' || !row.favorites) continue;
+      const path = (row.session.projectRoot || row.session.cwd).replace(/\/+$/, '');
+      if (!path) continue;
+      out.set(row.session.id, {
+        label: basename(path) || path,
+        path,
+        isGitRepo: row.session.isGitRepo === true,
+        ...(row.session.hostId ? {} : projectIcons[path] ? { icon: projectIcons[path] } : {}),
+      });
+    }
+    return out;
+  }, [rows, projectIcons]);
+
+  const listRef = useRef<HTMLUListElement | null>(null);
+  /* During a space slide two lists exist: the leaving one unmounts AFTER the new one mounted, and must not null the ref the new one just set. */
+  const setListRef = useCallback((node: HTMLUListElement | null) => {
+    if (node) listRef.current = node;
+    else if (listRef.current && !listRef.current.isConnected) listRef.current = null;
+  }, []);
+
+  /*
+   * Focus in the sidebar stays there across a space switch, so ⌥⌘←/→ and ↑/↓ keep working from it.
+   * The leaving list turns inert, so a row focused there drops focus to the page: it lands on the
+   * new list's open row, else its first, else the list itself, after the switch has painted
+   * (`focus()` lays the page out, which in the switch's frame would cost the whole new conversation's
+   * layout twice). Until the user acts, the reopened conversation's tools mounting can't take it
+   * (`holdFocusIn`).
+   */
+  const listBox = useRef<HTMLDivElement>(null);
+  const releaseFocus = useRef<(() => void) | null>(null);
+  useLayoutEffect(() => {
+    const box = listBox.current;
+    // Not `listRef`: the new list's ref lands after this effect (the presence wrapper attaches it).
+    const list = box?.querySelector<HTMLElement>('[data-live-list]');
+    const sidebar = box?.closest('aside');
+    const focused = document.activeElement;
+    if (!box || !list || !sidebar || !(focused instanceof HTMLElement) || !sidebar.contains(focused)) return undefined;
+    const moving = box.contains(focused) && !list.contains(focused);
+    const home = moving
+      ? (list.querySelector<HTMLElement>('[data-active="true"] [data-row-select]') ??
+        list.querySelector<HTMLElement>('[data-row-select]') ??
+        list)
+      : focused;
+    releaseFocus.current?.();
+    releaseFocus.current = holdFocusIn(sidebar, () => (home.isConnected ? home : list));
+    if (!moving) return undefined;
+    let timer = 0;
+    const frame = requestAnimationFrame(() => {
+      timer = window.setTimeout(() => {
+        // Still where the switch left it (the page, or the leaving list): the user hasn't moved it.
+        const now = document.activeElement;
+        if (!now || now === document.body || now === focused || now.closest('[inert]')) {
+          home.focus({ preventScroll: true });
+        }
+      }, 0);
+    });
+    return () => {
+      cancelAnimationFrame(frame);
+      clearTimeout(timer);
+    };
+  }, [listKey]);
+  useEffect(() => () => releaseFocus.current?.(), []);
+
+  /** Arrow-nav walks the order the user sees on screen. */
+  const displaySessions = useMemo<S[]>(() => {
+    if (searchMode) return [...titleMatches, ...contentMatches.map((m) => m.session)];
+    return rows
+      .filter((row): row is Extract<SidebarRow<S>, { kind: 'session' }> => row.kind === 'session')
+      .map((r) => r.session);
+  }, [rows, searchMode, titleMatches, contentMatches]);
+
+  const { commitImmediate } = useSidebarKeyboardNav<K>({
+    listRef,
+    sessions: displaySessions,
+    activeSessionId,
+    onActivate,
+    onNewSession,
+    ...(keyboardBlocked ? { blocked: keyboardBlocked } : {}),
+  });
+
+  /* Row callbacks keep a stable identity so the rows' memo short-circuits: the row passes its own id. */
+  const onRowSelect = useCallback(
+    (sessionId: string) => {
+      if (renamingId === sessionId) return;
+      commitImmediate(sessionId as K);
+    },
+    [renamingId, commitImmediate],
+  );
+
+  const onRowStartRename = useCallback((sessionId: string, currentTitle: string) => {
+    setMenuForId(null);
+    setRenamingId(sessionId as K);
+    setRenameValue(currentTitle);
+  }, []);
+
+  const onRowSetArchived = useCallback(
+    (sessionId: string, archived: boolean) => {
+      void onSetArchived(sessionId as K, archived);
+    },
+    [onSetArchived],
+  );
+
+  const onRowSetFavorite = useCallback(
+    (sessionId: string, favorite: boolean) => {
+      onSetFavorite(sessionId as K, favorite).catch((err) => console.error('[zidane-ui] favorite failed', err));
+    },
+    [onSetFavorite],
+  );
+
+  const onRowDelete = useCallback(
+    (sessionId: string, title: string, env?: SessionEnvironmentSummary) => {
+      onDelete({ id: sessionId as K, title, ...(env ? { environment: env } : {}) });
+    },
+    [onDelete],
+  );
+
+  const onRowMoveToSpace = useCallback(
+    (sessionId: string, spaceId: string) => {
+      onMoveToSpace?.(sessionId as K, spaceId).catch((err: unknown) =>
+        notify(labels.moveSessionFailed(messageOf(err))),
+      );
+    },
+    [onMoveToSpace, notify, labels],
+  );
+
+  const onRowMoveProjectToSpace = useCallback(
+    (project: SidebarProject, spaceId: string) => {
+      onMoveProjectToSpace?.(project, spaceId).catch((err: unknown) =>
+        notify(labels.moveProjectFailed(messageOf(err))),
+      );
+    },
+    [onMoveProjectToSpace, notify, labels],
+  );
+
+  const onDeleteProject = useCallback(
+    (project: SidebarProject, label: string) =>
+      deleteProject(project, label, () => setProjectPinned(project.path, false)),
+    [deleteProject, setProjectPinned],
+  );
+
+  const onRowOpenMenu = useCallback((sessionId: string) => setMenuForId(sessionId as K), []);
+  const onRowCloseMenu = useCallback((sessionId: string) => {
+    setMenuForId((current) => (current === sessionId ? null : current));
+  }, []);
+
+  const onRenameCommitRef = useRef<{ id: K | null; value: string }>({ id: null, value: '' });
+  // eslint-disable-next-line react-hooks/refs -- the commit keeps its identity (the rows' memo) and reads the field
+  onRenameCommitRef.current = { id: renamingId, value: renameValue };
+
+  const onRowRenameCommit = useCallback(async () => {
+    const { id, value } = onRenameCommitRef.current;
+    if (!id) return;
+    if (value.trim()) await onRename(id, value.trim());
+    setRenamingId(null);
+  }, [onRename]);
+
+  const onRowRenameCancel = useCallback(() => setRenamingId(null), []);
+
+  // What rows say beyond their title; primitives, so the rows' memo holds.
+  const rowDetails = {
+    runDetails,
+    artifactBadges: runDetails && artifactBadges,
+    spaces: spacesOn ? spaces : null,
+  };
+  const spaceList = onMoveToSpace ? rowDetails.spaces : null;
+
+  // One stable bag for every row: identities only change with their deps, so the rows' memo holds.
+  const rowHandlers = useMemo(
+    () => ({
+      onSelect: onRowSelect,
+      onRenameValueChange: setRenameValue,
+      onRenameCommit: onRowRenameCommit,
+      onRenameCancel: onRowRenameCancel,
+      onStartRename: onRowStartRename,
+      onDelete: onRowDelete,
+      onSetArchived: onRowSetArchived,
+      onSetFavorite: onRowSetFavorite,
+      onRetryEnvironment: environment.retry,
+      onRunEnvironmentAction: environment.run,
+      onMoveToSpace: onRowMoveToSpace,
+      ...(onMoveSession ? { onMoveSession: onMoveSession as (sessionId: string) => void } : {}),
+      onOpenMenu: onRowOpenMenu,
+      onCloseMenu: onRowCloseMenu,
+      live,
+    }),
+    [
+      onRowSelect,
+      onRowRenameCommit,
+      onRowRenameCancel,
+      onRowStartRename,
+      onRowDelete,
+      onRowSetArchived,
+      onRowSetFavorite,
+      environment,
+      onRowMoveToSpace,
+      onMoveSession,
+      onRowOpenMenu,
+      onRowCloseMenu,
+      live,
+    ],
+  );
+
+  // A row menu left open goes when the open session flips (keyboard navigation).
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- a switch from anywhere closes the stale menu
+    setMenuForId(null);
+  }, [activeSessionId]);
+
+  // A collapsed sidebar is unmounted: an open rename would be orphaned mid-edit.
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- collapsing drops the orphaned rename
+    if (collapsed) setRenamingId(null);
+  }, [collapsed]);
+
+  // Same draft as "New session", with this project's folder.
+  const onNewSessionIn = useCallback((fullPath: string) => newSessionIn(fullPath), [newSessionIn]);
+
+  const handleNewSession = useCallback(() => {
+    commitImmediate(null);
+    onNewSession();
+  }, [commitImmediate, onNewSession]);
+
+  const frame = useSidebarFrame({ collapsed, width, onWidthCommit });
+  // Rows always render their expanded form while mounted: the aside is a sliding sheet at full width.
+  if (!frame.mounted) return null;
+
+  // Collapse and the per-group caps are already applied in the builder: each row maps 1:1.
+  const renderNode = (node: SidebarNode<S>): ReactNode => {
+    if (node.kind === 'section') {
+      const { header } = node;
+      return (
+        <li key={node.id} className={header.kind === 'host' ? 'zg-host-section' : undefined}>
+          <ul className="list-none m-0 p-0">
+            {header.kind === 'host' ? (
+              <SessionHostHeader
+                id={header.id}
+                host={header.host}
+                collapsed={header.collapsed}
+                onToggle={toggleGroup}
+                className="zg-sticky-head"
+              />
+            ) : (
+              <SidebarGroupHeader
+                row={header}
+                groupBy={groupBy}
+                icon={header.fullPath ? projectIcons[header.fullPath] : undefined}
+                onAssignIcon={setProjectIcon}
+                onToggle={toggleGroup}
+                onNewSessionIn={onNewSessionIn}
+                spaces={onMoveProjectToSpace ? rowDetails.spaces : null}
+                spaceId={listSpaceId}
+                onMoveProject={onRowMoveProjectToSpace}
+                pinned={header.pinned === true}
+                onSetPinned={setProjectPinned}
+                canArchive={header.fullPath !== undefined && archivableProjects.has(header.fullPath)}
+                onArchiveProject={onArchiveProject}
+                onDeleteProject={onDeleteProject}
+                {...(header.hostId && hostById.get(header.hostId) ? { server: hostById.get(header.hostId)! } : {})}
+              />
+            )}
+            {node.children.map(renderNode)}
+          </ul>
+        </li>
+      );
+    }
+
+    if (node.kind === 'showMore') {
+      return <ShowMoreRow key={node.id} hiddenCount={node.hiddenCount} onExpand={() => expandGroup(node.groupId)} />;
+    }
+
+    const session = node.session;
+    const isRenaming = session.id === renamingId;
+    return (
+      <SidebarSessionRow
+        key={session.id}
+        sessionId={session.id}
+        title={session.title}
+        cwd={session.cwd}
+        hostId={session.hostId}
+        // A folder or host header above already names the server (not in Favorites).
+        hostBadge={node.favorites === true || !groupsByFolder(groupBy)}
+        spaceId={session.spaceId}
+        isMain={session.isMain}
+        updatedAt={session.updatedAt}
+        isActive={session.id === activeSessionId}
+        isRenaming={isRenaming}
+        archived={session.archived === true}
+        favorite={session.favorite}
+        renameValue={isRenaming ? renameValue : ''}
+        menuOpen={menuForId === session.id}
+        {...rowHandlers}
+        {...rowDetails}
+        spaces={spaceList}
+        environment={session.environment}
+        project={favoriteProjects.get(session.id)}
+      />
+    );
+  };
+
+  const searchRow = (session: S, excerpt?: string) => (
+    <SidebarSessionRow
+      key={session.id}
+      sessionId={session.id}
+      title={session.title}
+      cwd={session.cwd}
+      hostId={session.hostId}
+      spaceId={session.spaceId}
+      isMain={session.isMain}
+      isActive={session.id === activeSessionId}
+      isRenaming={session.id === renamingId}
+      archived={session.archived === true}
+      favorite={session.favorite}
+      renameValue={session.id === renamingId ? renameValue : ''}
+      menuOpen={menuForId === session.id}
+      {...rowHandlers}
+      {...rowDetails}
+      spaces={spaceList}
+      environment={session.environment}
+      {...(excerpt !== undefined ? { excerpt, excerptQuery: trimmedQuery } : {})}
+    />
+  );
+
+  return (
+    <SidebarFrame
+      frame={frame}
+      {...(chromeInset ? { chromeInset } : {})}
+      {...(ariaLabel ? { ariaLabel } : {})}
+      {...(className ? { className } : {})}
+      {...(style ? { style } : {})}
+    >
+      {/*
+       * Top band. ONE vertical rhythm for everything above the list: every item
+       * is a row on the same grid as the session rows, and the band spaces them
+       * with the same 4px the list uses between rows. Order is by reach: the
+       * Main session, New session, then the search right on top of the list.
+       */}
+      <div className="shrink-0 flex flex-col gap-1 px-2 pt-1">
+        {!searchMode && mainSession && (
+          <ul className="list-none m-0 p-0">
+            <MainSessionRow
+              sessionId={mainSession.id}
+              isActive={mainSession.id === activeSessionId}
+              icon={projectIcons[MAIN_SESSION_ICON_KEY]}
+              onAssignIcon={setProjectIcon}
+              onSelect={onRowSelect}
+            />
+          </ul>
+        )}
+        <NewSessionButton onNewSession={handleNewSession} isActive={activeSessionId == null} />
+        <SidebarSearchRow value={searchQuery} onChange={setSearchQuery} filter={filter} />
+      </div>
+
+      {/*
+       * The list is the ONLY flexible child (`flex-1 min-h-0`): it absorbs all
+       * height pressure by scrolling, so nothing pushes past the footer. Its
+       * edges fade (`LIST_MASK`): a stuck header pushed out dissolves below the
+       * search row, and a part-scrolled row into the footer; `pb-3` keeps a
+       * fully scrolled last row out of the 12px fade.
+       *
+       * One list per space: the leaving list slides out one way while the new
+       * one slides in from the other, on the `slide` spring. The key moves only
+       * on a user switch (`listKey`).
+       */}
+      <div ref={listBox} className="relative flex-1 min-h-0 overflow-hidden flex flex-col">
+        <LazyMotion features={domAnimation}>
+          <AnimatePresence initial={false} custom={slideOffset} mode="popLayout">
+            <SpaceList
+              key={listKey}
+              ref={setListRef}
+              custom={slideOffset}
+              variants={SPACE_LIST_VARIANTS}
+              initial="enter"
+              animate="center"
+              exit="leave"
+              transition={slideTransition}
+              data-space={spacesOn ? listSpaceId : undefined}
+              tabIndex={-1}
+              className="zg-sidebar-list outline-none flex-1 min-h-0 w-full overflow-y-auto px-2 pt-1 pb-3 list-none m-0"
+              style={LIST_STYLE}
+            >
+              {searchMode ? (
+                <>
+                  {titleMatches.map((session) => searchRow(session))}
+                  {contentMatches.map(({ session, hit }) => searchRow(session, hit.excerpt))}
+                  {searching && (
+                    <li aria-live="polite" className="text-xs text-[var(--zg-text-muted)] px-3 pt-1 select-none">
+                      {labels.searchingSessions}
+                    </li>
+                  )}
+                  {!searching && titleMatches.length === 0 && contentMatches.length === 0 && (
+                    <li className="text-xs text-[var(--zg-text-muted)] px-3 pt-1 select-none">
+                      {labels.sidebarNoMatches}
+                    </li>
+                  )}
+                </>
+              ) : (
+                sections.map(renderNode)
+              )}
+              {!searchMode && sessions.length === 0 && (
+                <li className="text-xs text-[var(--zg-text-muted)] px-3 pt-1">{labels.noChatsYet}</li>
+              )}
+            </SpaceList>
+          </AnimatePresence>
+        </LazyMotion>
+      </div>
+      {footer}
+    </SidebarFrame>
+  );
+}