fix(desktop): plan titlebar chrome from the front surface

apps/desktop/src/main/__tests__/app-shell-titlebar-chrome.test.ts

@@ -0,0 +1,90 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { planTitlebarChrome } from '../../renderer/app-shell-titlebar-chrome.js';
+
+test('settings owns the front surface: no shell session or workbar chrome', () => {
+  assert.deepEqual(
+    planTitlebarChrome({
+      settingsOpen: true,
+      agentsView: 'chat',
+      onSessionsSurface: true,
+      hasSessionIdentity: true,
+      hasWorkbarSession: true,
+    }),
+    {
+      showShellRail: false,
+      showSessionIdentity: false,
+      showWorkbarActions: false,
+    },
+  );
+});
+
+test('active session on the sessions surface shows shell + workbar chrome', () => {
+  assert.deepEqual(
+    planTitlebarChrome({
+      settingsOpen: false,
+      agentsView: 'chat',
+      onSessionsSurface: true,
+      hasSessionIdentity: true,
+      hasWorkbarSession: true,
+    }),
+    {
+      showShellRail: true,
+      showSessionIdentity: true,
+      showWorkbarActions: true,
+    },
+  );
+});
+
+test('sessions surface without an active session keeps search/sidebar only', () => {
+  assert.deepEqual(
+    planTitlebarChrome({
+      settingsOpen: false,
+      agentsView: 'chat',
+      onSessionsSurface: true,
+      hasSessionIdentity: false,
+      hasWorkbarSession: false,
+    }),
+    {
+      showShellRail: true,
+      showSessionIdentity: false,
+      showWorkbarActions: false,
+    },
+  );
+});
+
+test('session identity can appear before workbar while a placeholder view loads', () => {
+  assert.deepEqual(
+    planTitlebarChrome({
+      settingsOpen: false,
+      agentsView: 'chat',
+      onSessionsSurface: true,
+      hasSessionIdentity: true,
+      hasWorkbarSession: false,
+    }),
+    {
+      showShellRail: true,
+      showSessionIdentity: true,
+      showWorkbarActions: false,
+    },
+  );
+});
+
+test('module hubs that own the column drop workbar actions', () => {
+  for (const agentsView of ['skills', 'cron', 'daily-review'] as const) {
+    assert.deepEqual(
+      planTitlebarChrome({
+        settingsOpen: false,
+        agentsView,
+        onSessionsSurface: false,
+        hasSessionIdentity: false,
+        hasWorkbarSession: false,
+      }),
+      {
+        showShellRail: true,
+        showSessionIdentity: false,
+        showWorkbarActions: false,
+      },
+    );
+  }
+});

apps/desktop/src/renderer/app-shell-chrome-actions.tsx

@@ -62,6 +62,13 @@ function ChromeColumnToggle(props: {
   );
 }
 
+/**
+ * Left titlebar rail: conversation search + session sidebar toggle.
+ *
+ * Mount only when `planTitlebarChrome(...).showShellRail` is true. Settings
+ * (and any future full-window surface) owns its own nav — do not half-hide a
+ * single button while leaving other shell tools visible.
+ */
 export function AppShellTopbarActions(props: {
   sidebarCollapsed: boolean;
   onToggleSidebar(): void;
@@ -98,25 +105,13 @@ export function AppShellTopbarActions(props: {
 }
 
 /**
- * The titlebar's right edge.
- *
- * It used to also carry a `…` menu holding 问题反馈 / 打开命令面板 / 打开帮助 /
- * 打开健康中心 — a drawer of four things that each belong somewhere else.
- * 健康中心 was a duplicate of the Settings nav entry, 问题反馈 only opened
- * Settings → 关于, and the other two now have real homes: the keyboard sheet is
- * a row on 关于, and the palette keeps ⌘K, which that sheet documents.
- *
- * What is left is the workbar toggle — the right-hand mirror of the sidebar
- * toggle above, down to the component: one control that stays put across its
- * own state change. It used to hand itself off to a second button inside the
- * workbar's tab row while the workbar was open, so the single control a user
- * clicks twice moved ~30px down and left between those two clicks.
+ * The titlebar's right edge: workbar launcher + workbar column toggle.
  *
- * The titlebar is also the only row in the app that already knows where the
- * platform's native window controls are: `.maka-window-titlebar` reserves
- * `env(titlebar-area-*)` on both sides, so this button clears the macOS traffic
- * lights and the Windows caption strip without either platform being named
- * here. A toggle parked anywhere else would have to restate that.
+ * Mount only when `planTitlebarChrome(...).showWorkbarActions` is true. The
+ * titlebar is the only row that already clears `env(titlebar-area-*)` for OS
+ * caption buttons; a toggle parked elsewhere would restate that. Outside an
+ * active session workspace (or under Settings), there is nothing to toggle —
+ * leave the drag surface alone rather than paint an empty no-drag rect.
  */
 export function AppShellWorkspaceTopActions(props: {
   workbarAvailable: boolean;
@@ -126,8 +121,6 @@ export function AppShellWorkspaceTopActions(props: {
 }) {
   const locale = useUiLocale();
   const copy = getShellCopy(locale).chrome;
-  // Nothing to toggle outside a session; an empty no-drag rectangle in the
-  // titlebar would only subtract from the window's drag surface.
   if (!props.workbarAvailable) return null;
 
   return (

apps/desktop/src/renderer/app-shell-titlebar-chrome.ts

@@ -0,0 +1,62 @@
+/**
+ * Frame-level titlebar chrome planning.
+ *
+ * The titlebar strip is always painted: content columns bleed under it, and
+ * the OS drag region has to stay alive. Interactive controls, however, belong
+ * only to the surface currently in front of the user.
+ *
+ * Settings is a full-window surface (stacked under the titlebar on purpose so
+ * window drag still works). It owns its own navigation column. Shell
+ * session/workspace controls that still reflect the session *under* Settings
+ * are wrong affordances — hide them rather than special-casing each button.
+ */
+
+/** Module surfaces that own the whole column and have no session workbar. */
+export const TITLEBAR_MODULES_WITHOUT_WORKBAR = new Set([
+  'skills',
+  'cron',
+  'daily-review',
+]);
+
+export type TitlebarChromePlan = {
+  /** Conversation search + session sidebar toggle (left rail). */
+  readonly showShellRail: boolean;
+  /** Active session name / project breadcrumb (center). */
+  readonly showSessionIdentity: boolean;
+  /** Workbar launcher + workbar column toggle (right). */
+  readonly showWorkbarActions: boolean;
+};
+
+export type TitlebarChromeInput = {
+  readonly settingsOpen: boolean;
+  /** Current module key used for hub surfaces (skills, cron, daily-review, …). */
+  readonly agentsView: string;
+  readonly onSessionsSurface: boolean;
+  /**
+   * Session identity can appear on a short-lived placeholder record while the
+   * real summary loads (`activeSessionForView`).
+   */
+  readonly hasSessionIdentity: boolean;
+  /** Workbar needs a real active session id, not only a view placeholder. */
+  readonly hasWorkbarSession: boolean;
+};
+
+export function planTitlebarChrome(input: TitlebarChromeInput): TitlebarChromePlan {
+  // Settings is the primary surface: keep drag chrome, drop shell tools.
+  if (input.settingsOpen) {
+    return {
+      showShellRail: false,
+      showSessionIdentity: false,
+      showWorkbarActions: false,
+    };
+  }
+
+  return {
+    showShellRail: true,
+    showSessionIdentity: input.onSessionsSurface && input.hasSessionIdentity,
+    showWorkbarActions:
+      input.onSessionsSurface &&
+      input.hasWorkbarSession &&
+      !TITLEBAR_MODULES_WITHOUT_WORKBAR.has(input.agentsView),
+  };
+}

apps/desktop/src/renderer/app-shell.tsx

@@ -135,6 +135,7 @@ import {
 import { modelSetupToastCopy } from './model-connection-errors';
 import type { AppShellCommandListOptions } from './app-shell-command-actions';
 import { AppShellTopbarActions, AppShellWorkspaceTopActions } from './app-shell-chrome-actions';
+import { planTitlebarChrome } from './app-shell-titlebar-chrome';
 import { updateReminderFromStatus } from './app-shell-app-update';
 import { AppShellDetailPanel } from './app-shell-detail-panel';
 import { AppShellOverlays } from './app-shell-overlays';
@@ -222,14 +223,6 @@ type ComposerImportOwner = {
  * assistant stream slot when the primary post-commit signal is missed.
  */
 const SETTLE_FALLBACK_GRACE_MS = 1000;
-/**
- * Module surfaces that own their whole column and render no workspace toolbar.
- * This used to be a `display: none` rule keyed on the detail panel's
- * `data-agents-view`; the toolbar now lives in the window titlebar, which is not
- * a descendant of the detail panel, so the condition belongs here.
- */
-const VIEWS_WITHOUT_WORKSPACE_ACTIONS = new Set(['skills', 'cron', 'daily-review']);
-
 type AppShellProps = {
   /** Pre-mount snapshot prefetched by main.tsx — see prefetchOnboardingSnapshot. */
   initialOnboardingSnapshot?: OnboardingSnapshot | null;
@@ -2479,6 +2472,16 @@ function AppShellContent({
         ? navSelection.module
         : 'im_hub';
 
+  // Titlebar paint is frame-level; interactive chrome follows the front surface.
+  // See planTitlebarChrome — Settings must not leak session workbar tools.
+  const titlebarChrome = planTitlebarChrome({
+    settingsOpen,
+    agentsView,
+    onSessionsSurface: navSelection.section === 'sessions',
+    hasSessionIdentity: Boolean(activeSessionForView),
+    hasWorkbarSession: Boolean(activeId),
+  });
+
   return (
     <div
       className="appFrame agents-layout-root"
@@ -2523,55 +2526,51 @@ function AppShellContent({
         aria-hidden={shellObscured ? 'true' : undefined}
         inert={hasModalOpen ? true : undefined}
       >
-        {/* Settings owns the full window chrome. Keep this empty header mounted
-            as the frameless window's drag authority, but remove every control
-            and identity belonging to the obscured session shell. */}
-        {!settingsOpen && (
-          <>
-            <AppShellTopbarActions
-              sidebarCollapsed={sessionListCollapsed}
-              onToggleSidebar={() => sessionSideNavHandleRef.current?.getCollapseState()?.toggle()}
-              onOpenSearchModal={() => setSearchModalOpen(true)}
-            />
-            {/* Only a session has an identity to state. The other views name
-                themselves in the nav column they are selected from, and the
-                new-task surface still shows its project in the composer's
-                WorkspacePicker — which stops rendering at the exact moment this
-                takes over, when the first message creates the session. */}
-            {/* `activeSessionForView`, not `activeSession`: opening or creating a
-                session runs a few hundred ms on a placeholder record while the real
-                summary loads, and the name this replaced (the context layer's) was
-                showing through that window. Hung on the real record alone, 新任务
-                was named nowhere for the length of it. */}
-            {navSelection.section === 'sessions' && activeSessionForView && (
-              <TitlebarSessionIdentity
-                /* Keyed by session: the open rename is local state and the field is
-                   uncontrolled, so a switch that left the instance mounted would
-                   carry one session's half-typed name — and its commit — onto the
-                   next one. A remount ties the edit to the session it belongs to. */
-                key={activeSessionForView.id}
-                sessionName={activeSessionForView.name}
-                onRenameSession={(name) => {
-                  void sessionRowActionHandlers.renameSession(activeSessionForView.id, name);
-                }}
-                project={
-                  titlebarProjectName
-                    ? { name: titlebarProjectName, onOpenFolder: () => void openProjectFolder() }
-                    : undefined
-                }
-                parentSession={titlebarParentSession}
-              />
-            )}
-            {!VIEWS_WITHOUT_WORKSPACE_ACTIONS.has(agentsView) && (
-              <AppShellWorkspaceTopActions
-                workbarAvailable={navSelection.section === 'sessions' && Boolean(activeId)}
-                workbarCollapsed={workbarCollapsed}
-                onOpenWorkbarLauncher={revealWorkbarLauncher}
-                onToggleWorkbar={toggleWorkbar}
-              />
-            )}
-          </>
+        {/* Titlebar strip stays mounted as the frameless window's drag authority
+            (Settings stacks under it). Interactive chrome follows
+            planTitlebarChrome — only the front surface's tools. */}
+        {titlebarChrome.showShellRail && (
+          <AppShellTopbarActions
+            sidebarCollapsed={sessionListCollapsed}
+            onToggleSidebar={() => sessionSideNavHandleRef.current?.getCollapseState()?.toggle()}
+            onOpenSearchModal={() => setSearchModalOpen(true)}
+          />
         )}
+        {/* Only a session has an identity to state. The other views name
+            themselves in the nav column they are selected from, and the
+            new-task surface still shows its project in the composer's
+            WorkspacePicker — which stops rendering at the exact moment this
+            takes over, when the first message creates the session. */}
+        {/* `activeSessionForView`, not `activeSession`: opening or creating a
+            session runs a few hundred ms on a placeholder record while the real
+            summary loads, and the name this replaced (the context layer's) was
+            showing through that window. Hung on the real record alone, 新任务
+            was named nowhere for the length of it. */}
+        {titlebarChrome.showSessionIdentity && activeSessionForView && (
+          <TitlebarSessionIdentity
+            /* Keyed by session: the open rename is local state and the field is
+               uncontrolled, so a switch that left the instance mounted would
+               carry one session's half-typed name — and its commit — onto the
+               next one. A remount ties the edit to the session it belongs to. */
+            key={activeSessionForView.id}
+            sessionName={activeSessionForView.name}
+            onRenameSession={(name) => {
+              void sessionRowActionHandlers.renameSession(activeSessionForView.id, name);
+            }}
+            project={
+              titlebarProjectName
+                ? { name: titlebarProjectName, onOpenFolder: () => void openProjectFolder() }
+                : undefined
+            }
+            parentSession={titlebarParentSession}
+          />
+        )}
+        <AppShellWorkspaceTopActions
+          workbarAvailable={titlebarChrome.showWorkbarActions}
+          workbarCollapsed={workbarCollapsed}
+          onOpenWorkbarLauncher={revealWorkbarLauncher}
+          onToggleWorkbar={toggleWorkbar}
+        />
       </header>
       <AstryxAppShell
         className="app maka-shell-astryx agents-layout-body"