fix(touchbar): sort keys by col so reordered layouts render all keys

After a drag-swap in the customizer (e.g. Tab at col 3 swapped with the
down arrow at col 6), the persisted touchBarKeys array order no longer
matched the visual column order. CSS Grid auto-flow doesn't reliably
backtrack when DOM order has a key at a later column ahead of one at an
earlier column — later keys got pushed onto a phantom row 2 where the
JS-computed bar height clips them, so they vanished from the rendered
TouchBar even though the customizer Live Preview still showed them.

The customizer Live Preview shipped this fix in commit ab68d5e but the
runtime bar regressed and never got the same treatment.

- Extract sortKeysByCol helper in defaultKeys.ts with a docstring
  explaining the auto-flow trap so this stops regressing.
- Sort each row by col before rendering in TouchBar.tsx, and render the
  mic in its sorted position rather than always last so DOM order is
  strictly L→R.
- Add grid-template-rows: 32px and overflow: hidden to .row in
  TouchBar.module.css as defensive belt-and-suspenders clipping that
  matches the customizer fix.
- Add unit tests including a regression test that reproduces the exact
  Tab ↔ down swap from the user's screenshot.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dorlugasigal

src/frontend/src/components/TouchBar/TouchBar.module.css

@@ -222,8 +222,16 @@
 .row {
   display: grid;
   grid-template-columns: repeat(8, 1fr);
+  /* Pin to a single row of fixed height. Defensive belt-and-suspenders:
+   * sortKeysByCol() in TouchBar.tsx already guarantees DOM order matches
+   * column order so CSS Grid lays everything out on row 1, but if a future
+   * change ever emitted an out-of-order key the implicit row would still
+   * be clipped by overflow:hidden instead of vanishing into a phantom row
+   * that the JS-computed bar height can't reach. */
+  grid-template-rows: 32px;
   gap: 4px;
   padding: 0 2px;
+  overflow: hidden;
 }
 
 /* Both rows use the same 8-column grid so keys are the same width across

src/frontend/src/components/TouchBar/TouchBar.tsx

@@ -5,7 +5,7 @@ import { useUIStore } from '@/stores/uiStore';
 import { usePreferencesStore, type TouchBarKey } from '@/stores/preferencesStore';
 import { useMobileKeyboard } from '@/hooks/useMobileKeyboard';
 import { uploadImage } from '@/services/api';
-import { DEFAULT_TOUCHBAR_KEYS } from './defaultKeys';
+import { DEFAULT_TOUCHBAR_KEYS, sortKeysByCol } from './defaultKeys';
 import styles from './TouchBar.module.css';
 
 let hapticsUnsupportedWarned = false;
@@ -715,18 +715,24 @@ export default function TouchBar() {
         <div className={styles.rows} aria-hidden={collapsed}>
           {([1, 2, 3] as const).map((rowNum) => {
             if (rowGroups[rowNum].length === 0) return null;
-            const rowKeys = rowGroups[rowNum];
-            // Mic is rendered separately for its hold-to-record behaviour;
-            // exclude it from the regular renderKey loop.
-            const nonMicKeys = rowKeys.filter((k) => k.action !== 'mic');
-            const rowMic = rowKeys.find((k) => k.action === 'mic');
+            // Sort by `col` so DOM order matches visual column order.
+            // Required because CSS Grid auto-flow can spawn a phantom row
+            // when DOM order is out of column order — see sortKeysByCol's
+            // docstring and the matching customizer fix in commit ab68d5eb.
+            const sortedKeys = sortKeysByCol(rowGroups[rowNum]);
             const startIndex = (rowNum - 1) * 8;
             return (
               <div key={`row-${rowNum}`} className={styles.row}>
-                {nonMicKeys.map((k, i) =>
-                  renderKey(touchBarKeyToDef(k), startIndex + i),
-                )}
-                {rowMic === micKey && micKey && micButton}
+                {sortedKeys.map((k, i) => {
+                  // Render the mic in its sorted-by-col position rather
+                  // than always last, so DOM order is strictly L→R.
+                  if (k.action === 'mic' && k.id === micKey?.id) {
+                    return (
+                      <React.Fragment key={k.id ?? 'mic'}>{micButton}</React.Fragment>
+                    );
+                  }
+                  return renderKey(touchBarKeyToDef(k), startIndex + i);
+                })}
               </div>
             );
           })}

src/frontend/src/components/TouchBar/__tests__/defaultKeys.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest';
+import type { TouchBarKey } from '@/stores/preferencesStore';
+import { DEFAULT_TOUCHBAR_KEYS, sortKeysByCol } from '../defaultKeys';
+
+describe('sortKeysByCol', () => {
+  it('returns a new array (does not mutate input)', () => {
+    const input: TouchBarKey[] = [
+      { id: 'a', label: 'A', send: 'a', col: 3 },
+      { id: 'b', label: 'B', send: 'b', col: 1 },
+    ];
+    const out = sortKeysByCol(input);
+    expect(out).not.toBe(input);
+    expect(input.map((k) => k.id)).toEqual(['a', 'b']);
+  });
+
+  it('sorts by ascending col', () => {
+    const input: TouchBarKey[] = [
+      { id: 'tab', label: 'Tab', send: '\t', col: 6 },
+      { id: 'ctrl', label: 'Ctrl', send: '', col: 1 },
+      { id: 'shift', label: 'Shift', send: '', col: 2 },
+      { id: 'down', label: '↓', send: '\x1b[B', col: 3 },
+    ];
+    expect(sortKeysByCol(input).map((k) => k.id)).toEqual([
+      'ctrl',
+      'shift',
+      'down',
+      'tab',
+    ]);
+  });
+
+  it('treats missing col as col 1', () => {
+    const input: TouchBarKey[] = [
+      { id: 'b', label: 'B', send: 'b', col: 5 },
+      { id: 'a', label: 'A', send: 'a' },
+      { id: 'c', label: 'C', send: 'c', col: 8 },
+    ];
+    expect(sortKeysByCol(input).map((k) => k.id)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('keeps stable order for equal cols (assumes typed sort is stable)', () => {
+    const input: TouchBarKey[] = [
+      { id: 'x', label: 'X', send: '', col: 4 },
+      { id: 'y', label: 'Y', send: '', col: 4 },
+      { id: 'z', label: 'Z', send: '', col: 1 },
+    ];
+    expect(sortKeysByCol(input).map((k) => k.id)).toEqual(['z', 'x', 'y']);
+  });
+
+  it('regression: a swapped row layout still renders all keys L→R by col', () => {
+    // Reproduces the bug from the user's screenshot: Tab (col 3) and
+    // ↓ (col 6) were swapped via drag-and-drop. The persisted array
+    // order doesn't change, only their row+col fields. Without sorting,
+    // CSS Grid pushes col-3 ↓ onto a phantom row 2 where the bar's
+    // JS-computed height clips it. With sorting, DOM order is L→R.
+    const row2BeforeSwap = DEFAULT_TOUCHBAR_KEYS.filter((k) => k.row === 2);
+    const swapped = row2BeforeSwap.map((k) => {
+      if (k.id === 'tab') return { ...k, col: 6 };
+      if (k.id === 'down') return { ...k, col: 3 };
+      return k;
+    });
+    // Pre-sort: array order is Ctrl(1), Shift(2), Tab(6), ^C(4), ←(5),
+    // ↓(3), →(7), Mic(8) — out of column order.
+    const preSortCols = swapped.map((k) => k.col);
+    expect(preSortCols).toEqual([1, 2, 6, 4, 5, 3, 7, 8]);
+    // Post-sort: DOM order matches grid columns.
+    const sorted = sortKeysByCol(swapped);
+    expect(sorted.map((k) => k.col)).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+    expect(sorted.map((k) => k.id)).toEqual([
+      'ctrl',
+      'shift',
+      'down',
+      'ctrl-c',
+      'left',
+      'tab',
+      'right',
+      'mic',
+    ]);
+  });
+});

src/frontend/src/components/TouchBar/defaultKeys.ts

@@ -32,6 +32,23 @@ export const DEFAULT_TOUCHBAR_KEYS: TouchBarKey[] = [
   { id: 'mic', label: 'Mic', send: '', style: 'plain', action: 'mic', row: 2, col: 8 },
 ];
 
+/** Sort touchbar keys within a row by their starting column.
+ *
+ *  CSS Grid `auto-flow: row` (the default) doesn't reliably backtrack when
+ *  DOM order has a key at a later column ahead of one at an earlier column.
+ *  After a drag-swap (e.g. `Tab` at col 3 ↔ `↓` at col 6), the persisted
+ *  `touchBarKeys` array still has the keys in their original array order,
+ *  so DOM order no longer matches visual column order. Without sorting,
+ *  later keys get pushed onto a phantom CSS row 2, where the JS-computed
+ *  bar height clips them — they vanish from the rendered TouchBar even
+ *  though the customizer's Live Preview still shows them (the Live Preview
+ *  shipped this fix in commit ab68d5eb; the runtime bar regressed).
+ *
+ *  Returns a new array, never mutates input. */
+export function sortKeysByCol<T extends { col?: number }>(keys: T[]): T[] {
+  return [...keys].sort((a, b) => (a.col ?? 1) - (b.col ?? 1));
+}
+
 /** Map from a TouchBarKey "look" preset to the display name shown in the
  *  customizer. */
 export const KEY_LOOK_OPTIONS: { value: NonNullable<TouchBarKey['style']>; label: string; description: string }[] = [