feat(tiles): Tiles header button with a session picker, and a tile's + menu

A Tiles button beside Split in the header, opt-in through the per-device
showTileGridButton setting (read in applyHeaderVisibilitySettings; the
settings checkbox, displayKeys membership and schema exclusion follow with
persistence) and hard-gated like Split: hidden by its --hidden marker, a JS
width check with a live media listener, a @media (max-width: 1179px) backstop
and never in a solo window. While the grid is open the button closes it and
reads as pressed.

Closed, it opens a picker: a checkbox per open session in tab order (never one
popped out to its own window; one with no PTY is offered, its tile shows the
Attach overlay), names as text, preselected with the grid this tab last left,
else the active session and an open split's two. Boxes past what the window
can fit are disabled with the count shown, and Open opens the grid on the
checked sessions, focusing the active one if checked. Escape and an outside
click close it; its close method is idempotent and the global Escape handler
calls it.

A tile's + lists the open sessions not yet tiled; picking one adds it and
focuses it (a human selection). A grid that already holds what the window fits
disables the entries. "New session in this case" waits for auto-join.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/web/public/app.js

@@ -1369,6 +1369,8 @@ class CodemanApp {
         if (this.attachmentHistoryDrawerOpen) this.closeAttachmentHistory();
         this.closeSessionManager();
         this.closeCommandPalette?.();
+        this.closeTilePicker?.();
+        this.closeTileAddMenu?.();
         this.closeShortcutOverlay?.();
         // Overlay layouts only: below 1024px the sidebar is a modal off-canvas
         // drawer over the terminal, so Escape must close it. The docked desktop

src/web/public/constants.js

@@ -1741,6 +1741,29 @@ function sanitizeTileGridState(raw, liveSessions, detachedIds) {
   };
 }
 
+/**
+ * The sessions the Tiles picker (and a tile's + menu) offers, in tab order:
+ * live ones only, never a session popped out to its own window (that window
+ * owns its PTY size). A session with no PTY attached IS offered: its tile shows
+ * the Attach overlay.
+ *
+ * @param {Map<string, {name?: string}>} sessions
+ * @param {string[]} sessionOrder
+ * @param {{has(id: string): boolean}} [detachedIds]
+ * @param {{has(id: string): boolean}} [exclude] - ids not to offer (already tiled)
+ * @returns {Array<{id: string, label: string}>}
+ */
+function buildTilePickerSessions(sessions, sessionOrder, detachedIds, exclude) {
+  const result = [];
+  for (const id of sessionOrder) {
+    if (detachedIds?.has?.(id) || exclude?.has?.(id)) continue;
+    const session = sessions.get(id);
+    if (!session) continue;
+    result.push({ id, label: session.name || 'Session' });
+  }
+  return result;
+}
+
 /**
  * Which tile takes focus when `id` leaves the grid: the next one in grid
  * order, else the previous one, else null.
@@ -2050,6 +2073,7 @@ if (typeof window !== 'undefined') {
     computeTileLayout,
     tileGridCapacity,
     sanitizeTileGridState,
+    buildTilePickerSessions,
     tileNeighbor,
     tileInDirection,
     cycleTile,

src/web/public/index.html

@@ -192,6 +192,7 @@
         <button class="btn-icon-header btn-file-viewer" onclick="app.toggleFileBrowserButton()" title="File Viewer" aria-label="Open file viewer" aria-expanded="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg></button>
         <button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
         <button class="btn-icon-header btn-split btn-split--hidden" onclick="app.openSplitPicker(event)" title="Split: open a second session beside this one" aria-label="Split: open a second session beside this one" aria-pressed="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="3" width="20" height="18" rx="2"/><line x1="12" y1="3" x2="12" y2="21"/></svg></button>
+        <button class="btn-icon-header btn-tile-grid btn-tile-grid--hidden" onclick="app.openTilePicker(event)" title="Tiles: show several sessions side by side" aria-label="Tiles: show several sessions side by side" aria-pressed="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="8" height="8" rx="1"/><rect x="13" y="3" width="8" height="8" rx="1"/><rect x="3" y="13" width="8" height="8" rx="1"/><rect x="13" y="13" width="8" height="8" rx="1"/></svg></button>
         <button class="btn-icon-header btn-ultracode-agents btn-ultracode-agents--hidden" onclick="app.toggleUltracodeAgentsPanel()" title="Ultracode / Workflow agents" aria-label="Open ultracode workflow agents"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="6" cy="6" r="2.5"/><circle cx="6" cy="18" r="2.5"/><circle cx="18" cy="12" r="2.5"/><path d="M8.2 7.2 15.6 11M8.2 16.8 15.6 13"/></svg></button>
         <div class="header-plan-usage header-plan-usage--hidden" id="planUsageChip" title="Claude and Codex plan usage limits">—</div>
         <button class="btn-icon-header btn-notifications" onclick="app.toggleNotifications()" title="Notifications" aria-label="Toggle notifications" style="display:none;">

src/web/public/settings-ui.js

@@ -3632,6 +3632,10 @@ Object.assign(CodemanApp.prototype, {
     const showSplitButton = settings.showSplitButton ?? defaults.showSplitButton ?? false;
     this._applySplitButtonVisibility?.(showSplitButton);
 
+    // Tiles button: same gate and backstop as Split (tile-grid.js).
+    const showTileGridButton = settings.showTileGridButton ?? defaults.showTileGridButton ?? false;
+    this._applyTileGridButtonVisibility?.(showTileGridButton);
+
     // Ultracode/Workflow agents launcher — hidden by default; reveal when enabled.
     // Marker class only (base is display:inline-flex !important) so it's auto-excluded
     // from the mobile-header-buttons-policy guard.

src/web/public/styles.css

@@ -2510,6 +2510,19 @@ html[data-tab-orientation='vertical'].tab-rail-compact
   display: none !important;
 }
 
+/* Tile grid header button: hidden by default (opt-in, `showTileGridButton`),
+   and hard-gated to desktop widths like Split (the backstop below). */
+.btn-tile-grid--hidden {
+  display: none !important;
+}
+
+/* While the grid is open the button's click closes it (aria-pressed too). */
+.btn-icon-header.btn-tile-grid.tiles-open,
+.btn-icon-header.btn-tile-grid.tiles-open:hover {
+  background: var(--accent);
+  color: var(--accent-ink);
+}
+
 /* The tile grid is open (tile-grid.js): the split cannot open beside it. */
 .btn-split.btn-split--blocked {
   opacity: 0.4;
@@ -2537,7 +2550,8 @@ html[data-tab-orientation='vertical'].tab-rail-compact
    HOME_SESSIONS_MIN_WIDTH (home-sessions.js) / SPLIT_PANE_MIN_WIDTH
    (constants.js) — keep the three in sync. */
 @media (max-width: 1179px) {
-  .btn-icon-header.btn-split {
+  .btn-icon-header.btn-split,
+  .btn-icon-header.btn-tile-grid {
     display: none !important;
   }
 }
@@ -2853,6 +2867,7 @@ body.solo-mode .header-tokens,
 body.solo-mode .btn-notifications,
 body.solo-mode .btn-multimonitor,
 body.solo-mode .btn-split,
+body.solo-mode .btn-tile-grid,
 body.solo-mode .header-plan-usage,
 /* A solo window shows ONE session and has no tab strip to put restored ones in,
    so offering to rebuild a list of them there is an offer it cannot show the
@@ -19575,6 +19590,85 @@ html[data-session-list="sidebar"][data-sidebar="collapsed"] .btn-sidebar-toggle
   pointer-events: none;
 }
 
+/* Tiles picker (tile-grid.js openTilePicker): a checkbox per open session,
+   positioned `fixed` under the Tiles button; same layer as the split picker. */
+.tile-picker-menu {
+  position: fixed;
+  z-index: 1000;
+  min-width: 240px;
+  max-width: 340px;
+  max-height: 60vh;
+  display: flex;
+  flex-direction: column;
+  padding: 6px;
+  background: var(--bg-secondary, #1a1a1a);
+  border: 1px solid var(--border-color, #333);
+  border-radius: 6px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.35);
+  font-size: 13px;
+}
+
+.tile-picker-list {
+  overflow-y: auto;
+  min-height: 0;
+}
+
+.tile-picker-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 6px;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.tile-picker-item:hover {
+  background: color-mix(in srgb, var(--text-muted, #888) 14%, transparent);
+}
+
+.tile-picker-item span {
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.tile-picker-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 6px 4px 2px;
+  border-top: 1px solid var(--border-color, #333);
+  margin-top: 4px;
+}
+
+.tile-picker-hint,
+.tile-picker-empty,
+.tile-add-empty {
+  color: var(--text-muted);
+  font-size: 12px;
+}
+
+.tile-picker-empty,
+.tile-add-empty {
+  padding: 6px 8px;
+}
+
+.tile-picker-open {
+  padding: 4px 12px;
+  font: inherit;
+  color: var(--accent-ink, #fff);
+  background: var(--accent, #4a9eff);
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.tile-picker-open:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
 /* Split-picker menu: a small popover listing sessions to split with, appended
    to document.body and positioned `fixed` by openSplitPicker() (JS sets
    top/right against the Split header button's own rect). z-index above the

src/web/public/tile-grid.js

@@ -202,6 +202,7 @@ Object.assign(CodemanApp.prototype, {
     this._selectTiledSession(focus, { auto });
     this._updateConnectionIndicator?.();
     this._updateSplitButtonForTiles();
+    this._updateTileGridButtonState();
     return true;
   },
 
@@ -261,11 +262,249 @@ Object.assign(CodemanApp.prototype, {
     }
     this._updateConnectionIndicator?.();
     this._updateSplitButtonForTiles();
+    this._updateTileGridButtonState();
+    this.closeTileAddMenu();
     // The tabs drop their .in-tiles marker.
     this.renderSessionTabs?.();
     if (reselect) this._selectAfterTileGrid(focusedId);
   },
 
+  /**
+   * The header Tiles button: shown when its per-device setting is on AND the
+   * window is desktop-wide (a JS check plus a live media listener, the same
+   * pair as the Split button; the CSS `@media (max-width: 1179px)` rule is the
+   * backstop that hides it even if this never runs).
+   */
+  _applyTileGridButtonVisibility(enabled) {
+    this._tileGridButtonSettingEnabled = !!enabled;
+    const btn = document.querySelector('.btn-tile-grid');
+    const wide = window.innerWidth >= SPLIT_PANE_MIN_WIDTH;
+    btn?.classList.toggle('btn-tile-grid--hidden', !enabled || !wide || !!this.isSoloWindow);
+    if (!this._tileGridButtonWidthListener && window.matchMedia) {
+      this._tileGridButtonWidthListener = true;
+      const mq = window.matchMedia(`(min-width: ${SPLIT_PANE_MIN_WIDTH}px)`);
+      mq.addEventListener('change', () => this._applyTileGridButtonVisibility(this._tileGridButtonSettingEnabled));
+    }
+  },
+
+  // Open grid: the button's click closes it, and says so.
+  _updateTileGridButtonState() {
+    const btn = document.querySelector('.btn-tile-grid');
+    if (!btn) return;
+    const open = this._tilesOwnTerminal();
+    btn.classList.toggle('tiles-open', open);
+    btn.setAttribute('aria-pressed', open ? 'true' : 'false');
+    const title = open ? 'Tiles: back to a single session' : 'Tiles: show several sessions side by side';
+    btn.title = title;
+    btn.setAttribute('aria-label', title);
+  },
+
+  /** How many tiles the terminal area can hold right now (the grid section, or the single view it would replace). */
+  _tileGridCapacityNow() {
+    const el = this._tilesOwnTerminal() ? this._tileGridSection() : document.querySelector('.terminal-wrap');
+    const rect = el?.getBoundingClientRect?.() || { width: 0, height: 0 };
+    return window.CodemanTileGrid.tileGridCapacity({
+      width: rect.width || window.innerWidth,
+      height: rect.height || window.innerHeight,
+    });
+  },
+
+  /**
+   * The Tiles button: with the grid open it closes it (back to the single view
+   * of the focused session); otherwise it opens a picker with a checkbox per
+   * open session, in tab order, preselected with the grid this tab last left
+   * (else the active session and an open split's two), and an Open button.
+   * Boxes past what the window can fit are disabled.
+   */
+  openTilePicker(event) {
+    // As the split picker: the opening click must not reach the outside-click
+    // listener this call installs.
+    event?.stopPropagation?.();
+    if (this._tilesOwnTerminal()) {
+      this.closeTileGrid({ keepStored: true, reselect: true });
+      return;
+    }
+    if (this._tilePicker) {
+      this.closeTilePicker();
+      return;
+    }
+    if (!this.canOpenTileGrid()) return;
+    const T = window.CodemanTileGrid;
+    const capacity = Math.max(1, Math.min(this._tileGridCapacityNow(), T.TILE_GRID_MAX));
+    const candidates = T.buildTilePickerSessions(this.sessions, this.sessionOrder, this.detachedSessions);
+    const remembered = (this._tileGridRemembered?.ids || []).filter((id) => candidates.some((c) => c.id === id));
+    const seed = remembered.length
+      ? remembered
+      : [this.activeSessionId, this._splitPane ? this._splitSessionId : null].filter(Boolean);
+    const checked = new Set(seed.slice(0, capacity));
+
+    const menu = document.createElement('div');
+    menu.id = 'tilePickerMenu';
+    menu.className = 'tile-picker-menu';
+    menu.setAttribute('role', 'dialog');
+    menu.setAttribute('aria-label', 'Show sessions as tiles');
+    const list = document.createElement('div');
+    list.className = 'tile-picker-list';
+    const boxes = [];
+    for (const c of candidates) {
+      const row = document.createElement('label');
+      row.className = 'tile-picker-item';
+      const box = document.createElement('input');
+      box.type = 'checkbox';
+      box.value = c.id;
+      box.checked = checked.has(c.id);
+      const name = document.createElement('span');
+      // A session literally named like a UI string must not be translated.
+      name.setAttribute('data-i18n-skip', '');
+      name.textContent = c.label;
+      row.append(box, name);
+      list.appendChild(row);
+      boxes.push(box);
+    }
+    const footer = document.createElement('div');
+    footer.className = 'tile-picker-footer';
+    const hint = document.createElement('span');
+    hint.className = 'tile-picker-hint';
+    hint.textContent = `This window fits ${capacity} tile${capacity === 1 ? '' : 's'}`;
+    const open = document.createElement('button');
+    open.type = 'button';
+    open.className = 'tile-picker-open';
+    open.textContent = 'Open tiles';
+    footer.append(hint, open);
+    if (candidates.length === 0) {
+      const empty = document.createElement('div');
+      empty.className = 'tile-picker-empty';
+      empty.textContent = 'No sessions to show as tiles';
+      menu.appendChild(empty);
+    } else {
+      menu.append(list, footer);
+    }
+
+    const sync = () => {
+      const count = boxes.filter((b) => b.checked).length;
+      for (const b of boxes) {
+        b.disabled = !b.checked && count >= capacity;
+        b.title = b.disabled ? `This window fits ${capacity} tiles` : '';
+      }
+      open.disabled = count === 0;
+    };
+    for (const b of boxes) b.addEventListener('change', sync);
+    sync();
+    open.addEventListener('click', () => {
+      const ids = boxes.filter((b) => b.checked).map((b) => b.value);
+      this.closeTilePicker();
+      if (ids.length === 0) return;
+      this.openTileGrid(ids, { focusedId: ids.includes(this.activeSessionId) ? this.activeSessionId : ids[0] });
+    });
+
+    document.body.appendChild(menu);
+    const btn = document.querySelector('.btn-tile-grid');
+    if (btn?.getBoundingClientRect) {
+      const rect = btn.getBoundingClientRect();
+      menu.style.position = 'fixed';
+      menu.style.top = `${rect.bottom + 4}px`;
+      menu.style.right = `${window.innerWidth - rect.right}px`;
+    }
+    const onOutside = (e) => {
+      if (menu.contains?.(e.target) || e.target?.closest?.('.btn-tile-grid')) return;
+      this.closeTilePicker();
+    };
+    const onKey = (e) => {
+      if (e.key === 'Escape') this.closeTilePicker();
+    };
+    this._tilePicker = { menu, onOutside, onKey };
+    // Deferred a tick so the opening click (still bubbling) does not close it.
+    setTimeout(() => {
+      if (this._tilePicker?.menu === menu) document.addEventListener('click', onOutside);
+    }, 0);
+    document.addEventListener('keydown', onKey);
+    (boxes.find((b) => !b.disabled) || open).focus?.();
+  },
+
+  /** Idempotent: the global Escape handler calls it whether or not the picker is open. */
+  closeTilePicker() {
+    const picker = this._tilePicker;
+    if (!picker) return;
+    this._tilePicker = null;
+    document.removeEventListener('click', picker.onOutside);
+    document.removeEventListener('keydown', picker.onKey);
+    picker.menu.remove();
+  },
+
+  /**
+   * A tile's +: the open sessions not yet tiled, in tab order; picking one
+   * adds it to the grid and focuses it (a human selection). Disabled once the
+   * grid holds what the window can fit.
+   */
+  openTileAddMenu(event) {
+    event?.preventDefault?.();
+    event?.stopPropagation?.();
+    const grid = this._tileGrid;
+    if (!grid?.open) return;
+    const trigger = event?.currentTarget || null;
+    if (this._tileAddMenu && this._tileAddMenu.trigger === trigger) {
+      this.closeTileAddMenu();
+      return;
+    }
+    this.closeTileAddMenu();
+    const T = window.CodemanTileGrid;
+    const capacity = Math.min(this._tileGridCapacityNow(), T.TILE_GRID_MAX);
+    const full = grid.ids.length >= Math.max(capacity, 1);
+    const candidates = T.buildTilePickerSessions(this.sessions, this.sessionOrder, this.detachedSessions, grid.tiles);
+    const menu = document.createElement('div');
+    menu.className = 'tab-rail-action-menu tile-add-menu';
+    menu.setAttribute('role', 'menu');
+    menu.setAttribute('aria-label', 'Add a session to the grid');
+    if (candidates.length === 0) {
+      const empty = document.createElement('div');
+      empty.className = 'tile-add-empty';
+      empty.textContent = 'Every open session is already tiled';
+      menu.appendChild(empty);
+    }
+    for (const c of candidates) {
+      const item = document.createElement('button');
+      item.type = 'button';
+      item.setAttribute('role', 'menuitem');
+      item.setAttribute('data-i18n-skip', '');
+      item.textContent = c.label;
+      item.disabled = full;
+      if (full) item.title = `The grid already holds what this window fits (${capacity})`;
+      item.addEventListener('click', () => {
+        this.closeTileAddMenu();
+        if (this.addTile(c.id)) this.selectSession(c.id);
+      });
+      menu.appendChild(item);
+    }
+    document.body.appendChild(menu);
+    if (trigger?.getBoundingClientRect) {
+      const rect = trigger.getBoundingClientRect();
+      menu.style.position = 'fixed';
+      menu.style.top = `${rect.bottom + 4}px`;
+      menu.style.right = `${Math.max(8, window.innerWidth - rect.right)}px`;
+    }
+    const onOutside = (e) => {
+      if (menu.contains?.(e.target) || (trigger && trigger.contains?.(e.target))) return;
+      this.closeTileAddMenu();
+    };
+    const onKey = (e) => {
+      if (e.key === 'Escape') this.closeTileAddMenu();
+    };
+    this._tileAddMenu = { menu, trigger, onOutside, onKey };
+    document.addEventListener('pointerdown', onOutside, true);
+    document.addEventListener('keydown', onKey);
+    menu.querySelector?.('button:not([disabled])')?.focus?.();
+  },
+
+  /** Idempotent, like closeTilePicker. */
+  closeTileAddMenu() {
+    const m = this._tileAddMenu;
+    if (!m) return;
+    this._tileAddMenu = null;
+    document.removeEventListener('pointerdown', m.onOutside, true);
+    document.removeEventListener('keydown', m.onKey);
+    m.menu.remove();
+  },
+
   // The Split button cannot act while the grid is open (openSplitPicker and
   // openSplitPane refuse), so it says so: aria-disabled plus a title, the same
   // refusal the split already gives for web tabs and the welcome screen.
@@ -645,6 +884,7 @@ Object.assign(CodemanApp.prototype, {
     actions.append(
       button('tile-menu', 'Session actions', '\u22EF', (e) => this.openTabRailActionMenu?.(e, sessionId)),
       zoomBtn,
+      button('tile-add', 'Add a session to the grid', '+', (e) => this.openTileAddMenu(e)),
       // Removes the tile ONLY: the session keeps running. Killing it stays
       // behind the menu's Close session and its confirm.
       button('tile-remove', 'Remove tile (the session keeps running)', '\u00D7', () =>