Merge pull request #1066 from org2AI/dev/consolidate-layout-settings

refactor(layout-settings): consolidate station layout controls

Author: Chloe-JY

docs/architecture-audit-2026-08-29/ChatPanelPositionUnification.md

@@ -0,0 +1,38 @@
+# Chat panel position unification architecture audit
+
+## Acceptance criteria
+
+- One canonical persisted setting controls the chat-panel side in every station layout
+- One writable atom owns reads and writes for that setting
+- Settings and Spotlight expose one choice rather than station-specific choices
+- Existing split settings migrate deterministically without changing the default for new users
+- No production reference remains to the old atoms, action IDs, or station-specific labels
+- Obsolete station-specific and superseded menu translation keys are removed from every locale
+
+## Ten-layer audit
+
+| Layer                                     | Verdict       | Evidence                                                                                                                                                                                                                                                           |
+| ----------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1. Compilation correctness                | pass          | TypeScript typecheck and focused tests cover the schema, atom, Settings menu, Spotlight definition, and action registration.                                                                                                                                       |
+| 2. Dead code and structural deduplication | pass          | Two schema fields, two atoms, four actions, two Spotlight choices, and the station-selection branches were replaced by one source and one action pair. The repository sweep found no old runtime identifier; eight obsolete keys were removed from all 13 locales. |
+| 3. Naming consistency                     | pass          | `general.chatPanelPosition` and `chatPanelPositionAtom` describe the setting without tying it to either station. Legacy names occur only in the migration boundary and its tests.                                                                                  |
+| 4. Semantic overloading                   | pass          | “Station” now describes the active layout only; it no longer selects a separate meaning for chat-panel position.                                                                                                                                                   |
+| 5. Default branch analysis                | pass          | New users retain the left-side default. Migration precedence is explicit: canonical value, valid legacy My Station value, valid legacy Agent Station value, then the schema default.                                                                               |
+| 6. Cross-domain leakage                   | pass          | Shared layout consumers import a station-neutral atom; no My Station or Agent Station position concept leaks into shared state.                                                                                                                                    |
+| 7. New-developer clarity                  | pass          | One schema key, atom, UI row, and action pair form a direct ownership chain.                                                                                                                                                                                       |
+| 8. Wire and serialization                 | pass / scoped | No network or IPC payload changed. The settings JSONC persistence surface changes to one canonical key; old keys are accepted only during validation and removed from normalized runtime state.                                                                    |
+| 9. Init parity                            | pass          | Startup hydration and external settings-file changes both call `validateSettings`, so both entry paths apply the same migration and canonical projection.                                                                                                          |
+| 10. Resolver symmetry                     | pass          | Both station layouts resolve the same field through the same atom. There is no longer a station-dependent fallback branch.                                                                                                                                         |
+
+## Ownership path
+
+| Entry point             | Canonical write/read                             | My Station consumer                          | Agent Station consumer                         |
+| ----------------------- | ------------------------------------------------ | -------------------------------------------- | ---------------------------------------------- |
+| Layout settings submenu | `chatPanelPositionAtom`                          | App layout and workstation header affordance | App layout and agent-station header affordance |
+| Action system           | `chatPanelPositionAtom`                          | Same shared projection                       | Same shared projection                         |
+| Spotlight               | Shared left/right action IDs                     | Same shared projection                       | Same shared projection                         |
+| Settings hydration      | `validateSettings` → `general.chatPanelPosition` | Same shared projection                       | Same shared projection                         |
+
+## Migration invariant
+
+`src/config/settingsSchema/index.ts:55` is the only compatibility boundary. A valid canonical value always wins. If it is absent, the prior My Station value wins when valid because it was the primary workstation preference; a valid prior Agent Station value is the fallback. The normalized settings object drops both legacy keys, and startup backfills the canonical key to disk.

docs/frontend-ui-audit-2026-08-29/SidebarLayoutSettingsMenu.md

@@ -0,0 +1,16 @@
+# Sidebar Layout settings menu UI audit
+
+| Line                                                                         | Element                         | Verdict          | Reason                                                                                                                                                                                              | Suggested change                                                |
+| ---------------------------------------------------------------------------- | ------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `src/scaffold/NavigationSidebar/blocks/SidebarSettingsMenuButton.tsx:511`    | Layout submenu trigger          | fix              | The separate Chat Panel and Workstation triggers duplicated one layout-settings surface. One localized Layout row now owns the complete submenu.                                                    | None.                                                           |
+| `src/scaffold/NavigationSidebar/blocks/SidebarSettingsMenuSubmenus.tsx:84`   | Layout submenu routing          | fix              | A single `layout` state replaces the two presentation-only modes, so menu state matches the consolidated information architecture.                                                                  | None.                                                           |
+| `src/components/SegmentedTextPill/index.tsx:9`                               | Segmented-control size API      | fix              | A typed `small` / `default` prop lets compact menus reduce the control without changing established creator controls. The default preserves the prior dimensions.                                   | None.                                                           |
+| `src/components/SegmentedTextPill/index.tsx:21`                              | Segmented-control size geometry | keep with reason | The 24px small control fits the shared 32px menu row, while the original 28px control remains the established Agent/Manual geometry. Both variants stay centralized in the design-system component. | None.                                                           |
+| `src/scaffold/NavigationSidebar/blocks/SidebarLayoutSettingsSubmenu.tsx:37`  | Compact segmented setting row   | abstract         | Three choice-based settings share one local row seam instead of rebuilding title/control alignment.                                                                                                 | Keep new choice-based Layout settings on `SegmentedControlRow`. |
+| `src/scaffold/NavigationSidebar/blocks/SidebarLayoutSettingsSubmenu.tsx:49`  | Dropdown setting-row chrome     | keep with reason | `DROPDOWN_CLASSES.menuControlItem` supplies the established menu height, spacing, typography, hover treatment, and label/control alignment.                                                         | None.                                                           |
+| `src/scaffold/NavigationSidebar/blocks/SidebarLayoutSettingsSubmenu.tsx:51`  | Left/right and style selectors  | keep with reason | Reuses the shared `SegmentedTextPill` that owns the Agent/Manual visual pattern requested for this menu; each group exposes an accessible name and pressed state.                                   | None.                                                           |
+| `src/scaffold/NavigationSidebar/blocks/SidebarLayoutSettingsSubmenu.tsx:74`  | Pagination control              | fix              | The shared Switch remains the correct boolean control and receives the visible row label as its accessible name.                                                                                    | None.                                                           |
+| `src/scaffold/NavigationSidebar/blocks/SidebarLayoutSettingsSubmenu.tsx:127` | Shared chat-panel side row      | fix              | One station-independent Left/Right control replaces separate My Station and Agent Station rows, preventing contradictory choices in the UI.                                                         | None.                                                           |
+| `src/scaffold/NavigationSidebar/blocks/SidebarLayoutSettingsSubmenu.tsx:121` | Floating submenu surface        | keep with reason | Reuses the dropdown panel and width tokens shared by the sibling Presence and Appearance submenus.                                                                                                  | None.                                                           |
+
+Verdict totals: **5 fix**, **4 keep with reason**, **1 abstract**.

src/ActionSystem/actionIds.ts

@@ -39,10 +39,8 @@ export const ACTION_ID = {
   WORKSTATION_TOGGLE_CHAT_FOCUS: "workstation.toggleChatFocus",
   WORKSTATION_TOGGLE_CHAT_PANEL_VISIBILITY:
     "workstation.toggleChatPanelVisibility",
-  CHAT_PANEL_SET_MY_STATION_LEFT: "chatPanel.setMyStationLeft",
-  CHAT_PANEL_SET_MY_STATION_RIGHT: "chatPanel.setMyStationRight",
-  CHAT_PANEL_SET_AGENT_STATION_LEFT: "chatPanel.setAgentStationLeft",
-  CHAT_PANEL_SET_AGENT_STATION_RIGHT: "chatPanel.setAgentStationRight",
+  CHAT_PANEL_SET_LEFT: "chatPanel.setLeft",
+  CHAT_PANEL_SET_RIGHT: "chatPanel.setRight",
   CHAT_PANEL_ENABLE_PAGINATION: "chatPanel.enablePagination",
   CHAT_PANEL_DISABLE_PAGINATION: "chatPanel.disablePagination",
   CHAT_PANEL_USE_MODEL_PICKER_SPOTLIGHT: "chatPanel.useModelPickerSpotlight",

src/ActionSystem/actions/chatPanelActions.zod.ts

@@ -10,8 +10,7 @@ import {
 } from "@src/store/ui/chatPanelAtom";
 import { stationModeAtom } from "@src/store/ui/simulatorAtom";
 import {
-  sessionChatPositionAtom,
-  workStationChatPositionAtom,
+  chatPanelPositionAtom,
   workStationLayoutModePersistAtom,
 } from "@src/store/ui/workStationAtom";
 import { getInstrumentedStore } from "@src/util/core/state/instrumentedStore";
@@ -53,56 +52,33 @@ function defineEmptyAction(
   );
 }
 
-function setMyStationChatPosition(position: ChatPanelPosition): void {
+function setChatPanelPosition(position: ChatPanelPosition): void {
   const store = getInstrumentedStore();
   showActiveStationChatIfNeeded();
-  store.set(workStationChatPositionAtom, position);
-}
-
-function setAgentStationChatPosition(position: ChatPanelPosition): void {
-  const store = getInstrumentedStore();
-  store.set(sessionChatPositionAtom, position);
+  store.set(chatPanelPositionAtom, position);
 }
 
 function setModelPickerStyle(style: ModelPickerStyle): void {
   const store = getInstrumentedStore();
   store.set(modelPickerStyleAtom, style);
 }
 
-const chatPanelSetMyStationLeft = defineEmptyAction(
-  ACTION_ID.CHAT_PANEL_SET_MY_STATION_LEFT,
-  "settings",
-  "Move the My Station chat panel to the left",
-  "My Station chat panel moved left",
-  ["move my station chat left", "put chat panel on the left"],
-  () => setMyStationChatPosition("left")
-);
-
-const chatPanelSetMyStationRight = defineEmptyAction(
-  ACTION_ID.CHAT_PANEL_SET_MY_STATION_RIGHT,
-  "settings",
-  "Move the My Station chat panel to the right",
-  "My Station chat panel moved right",
-  ["move my station chat right", "put chat panel on the right"],
-  () => setMyStationChatPosition("right")
-);
-
-const chatPanelSetAgentStationLeft = defineEmptyAction(
-  ACTION_ID.CHAT_PANEL_SET_AGENT_STATION_LEFT,
+const chatPanelSetLeft = defineEmptyAction(
+  ACTION_ID.CHAT_PANEL_SET_LEFT,
   "settings",
-  "Move the Agent Station chat panel to the left",
-  "Agent Station chat panel moved left",
-  ["move agent station chat left", "put agent chat on the left"],
-  () => setAgentStationChatPosition("left")
+  "Move the chat panel to the left in every station layout",
+  "Chat panel moved left",
+  ["move chat panel left", "put chat panel on the left"],
+  () => setChatPanelPosition("left")
 );
 
-const chatPanelSetAgentStationRight = defineEmptyAction(
-  ACTION_ID.CHAT_PANEL_SET_AGENT_STATION_RIGHT,
+const chatPanelSetRight = defineEmptyAction(
+  ACTION_ID.CHAT_PANEL_SET_RIGHT,
   "settings",
-  "Move the Agent Station chat panel to the right",
-  "Agent Station chat panel moved right",
-  ["move agent station chat right", "put agent chat on the right"],
-  () => setAgentStationChatPosition("right")
+  "Move the chat panel to the right in every station layout",
+  "Chat panel moved right",
+  ["move chat panel right", "put chat panel on the right"],
+  () => setChatPanelPosition("right")
 );
 
 const chatPanelEnablePagination = defineEmptyAction(
@@ -172,10 +148,8 @@ const workstationSetSidebarRight = defineEmptyAction(
 );
 
 export const chatPanelZodActions = [
-  chatPanelSetMyStationLeft,
-  chatPanelSetMyStationRight,
-  chatPanelSetAgentStationLeft,
-  chatPanelSetAgentStationRight,
+  chatPanelSetLeft,
+  chatPanelSetRight,
   chatPanelEnablePagination,
   chatPanelDisablePagination,
   chatPanelUseModelPickerSpotlight,

src/components/SegmentedTextPill/SegmentedTextPill.test.ts

@@ -0,0 +1,39 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import SegmentedTextPill from ".";
+
+const options = [
+  { value: "left", label: "Left" },
+  { value: "right", label: "Right" },
+];
+
+function renderPill(size?: "small" | "default"): string {
+  return renderToStaticMarkup(
+    createElement(SegmentedTextPill, {
+      ariaLabel: "Position",
+      onChange: () => undefined,
+      options,
+      size,
+      value: "left",
+    })
+  );
+}
+
+describe("SegmentedTextPill", () => {
+  it("preserves the established dimensions by default", () => {
+    const markup = renderPill();
+
+    expect(markup).toContain("h-[28px]");
+    expect(markup).toContain("h-6 px-2.5");
+  });
+
+  it("offers a smaller variant for compact setting rows", () => {
+    const markup = renderPill("small");
+
+    expect(markup).toContain("h-6 text-[11px]");
+    expect(markup).toContain("h-5 px-2");
+    expect(markup).toContain('aria-label="Position"');
+  });
+});

src/components/SegmentedTextPill/index.tsx

@@ -6,28 +6,42 @@ export interface SegmentedTextPillOption<T extends string> {
   value: T;
 }
 
+export type SegmentedTextPillSize = "small" | "default";
+
 export interface SegmentedTextPillProps<T extends string> {
   ariaLabel: string;
   className?: string;
   dataTestId?: string;
   onChange: (value: T) => void;
   options: SegmentedTextPillOption<T>[];
+  size?: SegmentedTextPillSize;
   value: T;
 }
 
+const CONTAINER_SIZE_CLASSES: Record<SegmentedTextPillSize, string> = {
+  small: "h-6 text-[11px]",
+  default: "h-[28px] text-[12px]",
+};
+
+const BUTTON_SIZE_CLASSES: Record<SegmentedTextPillSize, string> = {
+  small: "h-5 px-2",
+  default: "h-6 px-2.5",
+};
+
 /** Compact text-only segmented control shared by creator setup rows. */
 export default function SegmentedTextPill<T extends string>({
   ariaLabel,
   className = "",
   dataTestId,
   onChange,
   options,
+  size = "default",
   value,
 }: SegmentedTextPillProps<T>) {
   return (
     <div
       aria-label={ariaLabel}
-      className={`inline-flex h-[28px] shrink-0 items-center rounded-full bg-fill-2 p-0.5 text-[12px] font-medium ${className}`}
+      className={`inline-flex shrink-0 items-center rounded-full bg-fill-2 p-0.5 font-medium ${CONTAINER_SIZE_CLASSES[size]} ${className}`}
       data-testid={dataTestId}
       role="group"
     >
@@ -38,7 +52,7 @@ export default function SegmentedTextPill<T extends string>({
           <button
             key={option.value}
             type="button"
-            className={`h-6 rounded-full px-2.5 py-0 transition-colors ${
+            className={`rounded-full py-0 transition-colors ${BUTTON_SIZE_CLASSES[size]} ${
               selected
                 ? "bg-bg-2 text-text-1 shadow-sm"
                 : "text-text-3 hover:text-text-1"

src/config/settingsSchema/__tests__/chatPanelPosition.test.ts

@@ -0,0 +1,42 @@
+import {
+  getSettingsDefaults,
+  validateSettings,
+} from "@src/config/settingsSchema";
+
+describe("chat panel position setting", () => {
+  it("has one canonical setting shared by both station layouts", () => {
+    const defaults = getSettingsDefaults();
+
+    expect(defaults["general.chatPanelPosition"]).toBe("left");
+    expect(defaults).not.toHaveProperty("general.workStationChatPosition");
+    expect(defaults).not.toHaveProperty("general.sessionChatPosition");
+  });
+
+  it("preserves an explicit canonical position", () => {
+    expect(
+      validateSettings({
+        "general.chatPanelPosition": "right",
+        "general.workStationChatPosition": "left",
+        "general.sessionChatPosition": "left",
+      })["general.chatPanelPosition"]
+    ).toBe("right");
+  });
+
+  it("migrates My Station first when legacy positions disagree", () => {
+    expect(
+      validateSettings({
+        "general.workStationChatPosition": "right",
+        "general.sessionChatPosition": "left",
+      })["general.chatPanelPosition"]
+    ).toBe("right");
+  });
+
+  it("falls back to the legacy Agent Station position when needed", () => {
+    expect(
+      validateSettings({
+        "general.workStationChatPosition": "invalid",
+        "general.sessionChatPosition": "right",
+      })["general.chatPanelPosition"]
+    ).toBe("right");
+  });
+});