@bakapiano/ccsm 0.15.4 → 0.17.0

package/public/js/components/Sidebar.js

@@ -5,7 +5,7 @@ import {
   sessions, folders, sessionsByFolder, foldersCollapsed, activeSessionId,
   selectTab, selectSession, toggleSidebar, toggleFolder, setSidebarWidth,
 } from '../state.js';
-import { createFolder, renameFolder, deleteFolder, reorderFolders, setSessionFolder, deleteSession, resumeSession, setSessionTitle } from '../api.js';
+import { createFolder, renameFolder, deleteFolder, reorderFolders, setSessionFolder, reorderSessions, deleteSession, resumeSession, setSessionTitle } from '../api.js';
 import { ccsmPrompt, ccsmConfirm } from '../dialog.js';
 import { setToast } from '../toast.js';
 import { fmtAgo } from '../util.js';
@@ -36,9 +36,15 @@ function NavItem({ tab, icon, label, dirty }) {
     </button>`;
 }
 
-// One row in the session tree. Click → open in main pane. Right-click /
-// long-press not implemented; "..." menu via the inline kebab.
-function SessionRow({ s }) {
+// Module-level: the SessionRow currently being hovered as a reorder
+// drop target. Set on dragOver, cleared on dragLeave/end. Drives the
+// "above this row" insert-line indicator.
+const reorderOverSessionId = signal(null);
+
+// One row in the session tree. Click → open in main pane. Drag-to-folder
+// is handled by FolderGroup's drop zone; same-folder reorder is handled
+// here: the row is a drop target when an in-folder sibling is dragged.
+function SessionRow({ s, folderId, siblingIds }) {
   clockTick.value; // subscribe for fmtAgo refresh
   const isActive = activeSessionId.value === s.id;
   const running = s.status === 'running';
@@ -80,19 +86,67 @@ function SessionRow({ s }) {
   const onDragStart = (ev) => {
     draggingSessionId.value = s.id;
     ev.dataTransfer.effectAllowed = 'move';
-    // Firefox refuses to start a drag without some data set.
     try { ev.dataTransfer.setData('text/plain', s.id); } catch {}
   };
   const onDragEnd = () => {
     draggingSessionId.value = null;
     dragOverFolderKey.value = null;
+    reorderOverSessionId.value = null;
+  };
+
+  // Drop on a session row → place the dragged session at THIS row's
+  // position. Same folder = pure reorder. Different folder = move +
+  // position in one shot (reorderSessions sets both folderId and
+  // order in one backend call). stopPropagation so .tree-folder
+  // doesn't also fire its "drop into folder" handler — landing on a
+  // row is the more specific intent.
+  const draggedId = draggingSessionId.value;
+  const acceptDrop = !!draggedId && draggedId !== s.id;
+  const showInsertLine = acceptDrop && reorderOverSessionId.value === s.id;
+
+  const onRowDragOver = (ev) => {
+    if (!acceptDrop) return;
+    ev.preventDefault();
+    ev.stopPropagation();
+    ev.dataTransfer.dropEffect = 'move';
+    if (reorderOverSessionId.value !== s.id) reorderOverSessionId.value = s.id;
+    // Also clear the parent folder's drop-target highlight — we're
+    // overriding to "drop on this row" semantics.
+    if (dragOverFolderKey.value) dragOverFolderKey.value = null;
+  };
+  const onRowDragLeave = (ev) => {
+    if (!acceptDrop) return;
+    const rt = ev.relatedTarget;
+    if (rt && ev.currentTarget.contains(rt)) return;
+    if (reorderOverSessionId.value === s.id) reorderOverSessionId.value = null;
+  };
+  const onRowDrop = (ev) => {
+    if (!acceptDrop) return;
+    ev.preventDefault();
+    ev.stopPropagation();
+    const draggedSid = draggingSessionId.value;
+    draggingSessionId.value = null;
+    reorderOverSessionId.value = null;
+    dragOverFolderKey.value = null;
+    if (!draggedSid || !siblingIds) return;
+    // Build the new sibling sequence: remove dragged (in case it was
+    // already in this folder) then insert at this row's slot.
+    const next = siblingIds.filter((id) => id !== draggedSid);
+    const targetIdx = next.indexOf(s.id);
+    if (targetIdx < 0) return;
+    next.splice(targetIdx, 0, draggedSid);
+    reorderSessions(folderId || null, next)
+      .catch((e) => setToast(e.message, 'error'));
   };
 
   return html`
-    <div class=${`tree-session${isActive ? ' is-active' : ''}${running ? ' is-running' : ' is-stopped'}${running && s.activity === 'working' ? ' is-working' : ''}`}
+    <div class=${`tree-session${isActive ? ' is-active' : ''}${running ? ' is-running' : ' is-stopped'}${running && s.activity === 'working' ? ' is-working' : ''}${showInsertLine ? ' is-reorder-target' : ''}`}
          draggable=${true}
          onDragStart=${onDragStart}
          onDragEnd=${onDragEnd}
+         onDragOver=${onRowDragOver}
+         onDragLeave=${onRowDragLeave}
+         onDrop=${onRowDrop}
          onClick=${onClick}
          title=${`${title}\n${s.cwd}\n${running ? (s.activity === 'working' ? 'working' : 'idle') : 'stopped'} · ${s.cliId}`}>
       <span class=${`tree-dot ${running ? 'is-running' : 'is-stopped'}${running && s.activity === 'working' ? ' is-working' : ''}`}></span>
@@ -106,14 +160,20 @@ function SessionRow({ s }) {
 }
 
 function FolderGroup({ folder, sessionList, dndHandle, dndRow }) {
-  const key = folderKey(folder);
+  // folder is now always set — backend materializes a synthetic
+  // {id:'unsorted', name:'Unsorted', builtin:true} entry alongside the
+  // user folders. The bucket can be drag-reordered like any other but
+  // Rename / Delete are hidden, and drops set folderId=null so existing
+  // sessions don't need a data migration.
+  const isUnsorted = folder?.id === 'unsorted' || folder?.builtin;
+  const key = folder ? folder.id : 'unsorted';
   const collapsed = !!foldersCollapsed.value[key];
   const name = folder ? folder.name : 'Unsorted';
   const onToggle = () => toggleFolder(folder ? folder.id : null);
 
   const onRename = async (ev) => {
     ev.stopPropagation();
-    if (!folder) return;
+    if (!folder || isUnsorted) return;
     const next = await ccsmPrompt('Rename folder', folder.name, { title: folder.name, okLabel: 'Save' });
     if (next === null || !next.trim()) return;
     try { await renameFolder(folder.id, next.trim()); }
@@ -122,7 +182,7 @@ function FolderGroup({ folder, sessionList, dndHandle, dndRow }) {
 
   const onDelete = async (ev) => {
     ev.stopPropagation();
-    if (!folder) return;
+    if (!folder || isUnsorted) return;
     const ok = await ccsmConfirm(`Delete folder "${folder.name}"? Sessions inside move to Unsorted.`, {
       title: 'Delete folder', okLabel: 'Delete', danger: true });
     if (!ok) return;
@@ -135,11 +195,16 @@ function FolderGroup({ folder, sessionList, dndHandle, dndRow }) {
   // handlers (in dndRow) short-circuit when no folder is being dragged,
   // and our handlers below short-circuit when no session is being
   // dragged — so composing both is safe.
+  // When the dragged session lands on the Unsorted bucket, we persist
+  // it with folderId=null (matches the existing data model — sessions
+  // with no folder are null, not 'unsorted'). Same for the sameFolder
+  // guard below.
+  const dropFolderId = isUnsorted ? null : (folder ? folder.id : null);
   const draggedSession = draggingSessionId.value
     ? sessions.value.find((s) => s.id === draggingSessionId.value)
     : null;
   const sameFolder = draggedSession
-    && (draggedSession.folderId || null) === (folder ? folder.id : null);
+    && (draggedSession.folderId || null) === dropFolderId;
   const isOver = !sameFolder && dragOverFolderKey.value === key;
 
   const onSessionDragOver = (ev) => {
@@ -161,8 +226,8 @@ function FolderGroup({ folder, sessionList, dndHandle, dndRow }) {
     if (!sid || sameFolder) return;
     ev.preventDefault();
     ev.stopPropagation();
-    setSessionFolder(sid, folder ? folder.id : null)
-      .then(() => setToast(folder ? `moved to ${folder.name}` : 'moved to Unsorted'))
+    setSessionFolder(sid, dropFolderId)
+      .then(() => setToast(`moved to ${name}`))
       .catch((e) => setToast(e.message, 'error'));
   };
 
@@ -185,7 +250,7 @@ function FolderGroup({ folder, sessionList, dndHandle, dndRow }) {
           ${collapsed ? html`<${IconFolder} />` : html`<${IconFolderOpen} />`}
         </span>
         <span class="tree-folder-name">${name}</span>
-        ${folder ? html`
+        ${folder && !isUnsorted ? html`
           <span class="tree-folder-actions">
             <button class="tree-folder-action" title="rename" onClick=${onRename}><${IconPencil} /></button>
             <button class="tree-folder-action" title="delete" onClick=${onDelete}><${IconClose} /></button>
@@ -195,7 +260,15 @@ function FolderGroup({ folder, sessionList, dndHandle, dndRow }) {
         <div class="tree-folder-body">
           ${sessionList.length === 0
             ? html`<div class="tree-empty">no sessions</div>`
-            : sessionList.map((s) => html`<${SessionRow} key=${s.id} s=${s} />`)}
+            : (() => {
+                // siblingIds captured once per render so each row sees a
+                // consistent snapshot for splice math.
+                const siblingIds = sessionList.map((x) => x.id);
+                return sessionList.map((s) => html`
+                  <${SessionRow} key=${s.id} s=${s}
+                                 folderId=${dropFolderId}
+                                 siblingIds=${siblingIds} />`);
+              })()}
         </div>
       ` : null}
     </div>`;
@@ -232,7 +305,6 @@ function SessionTree() {
                         sessionList=${grouped.get(f.id) || []}
                         dndHandle=${dnd.handleProps(f.id)}
                         dndRow=${dnd.rowProps(f.id)} />`)}
-      <${FolderGroup} folder=${null} sessionList=${grouped.get(null) || []} />
     </div>`;
 }
 

package/public/js/keybindings.js

@@ -0,0 +1,182 @@
+// Global keyboard shortcuts.
+//
+// Stored in localStorage under `ccsm.keybindings` as `{ action: combo }`.
+// Combos are strings like "Ctrl+Alt+ArrowDown" — order doesn't matter
+// at parse time but we normalize when emitting so the UI shows a stable
+// representation.
+//
+// The terminal grabs most keys for itself; we use Ctrl+Alt as the
+// default modifier set because xterm.js / claude / pwsh basically
+// never bind those combos.
+
+import { signal } from '@preact/signals';
+import { activeSessionId, sessions, folders, sessionsByFolder, selectSession, UNSORTED_KEY } from './state.js';
+import { reorderSessions } from './api.js';
+import { setToast } from './toast.js';
+
+export const ACTIONS = {
+  'session-next':      { label: 'Next session',          defaultCombo: 'Ctrl+Alt+ArrowDown' },
+  'session-prev':      { label: 'Previous session',      defaultCombo: 'Ctrl+Alt+ArrowUp' },
+  'session-move-down': { label: 'Move session down',     defaultCombo: 'Ctrl+Alt+Shift+ArrowDown' },
+  'session-move-up':   { label: 'Move session up',       defaultCombo: 'Ctrl+Alt+Shift+ArrowUp' },
+};
+
+const LS_KEY = 'ccsm.keybindings';
+
+function defaults() {
+  const out = {};
+  for (const [id, def] of Object.entries(ACTIONS)) out[id] = def.defaultCombo;
+  return out;
+}
+
+function load() {
+  try {
+    const raw = localStorage.getItem(LS_KEY);
+    if (!raw) return defaults();
+    const saved = JSON.parse(raw);
+    return { ...defaults(), ...saved };
+  } catch { return defaults(); }
+}
+
+export const keybindings = signal(load());
+
+export function setBinding(actionId, combo) {
+  if (!ACTIONS[actionId]) return;
+  const next = { ...keybindings.value, [actionId]: combo };
+  keybindings.value = next;
+  try { localStorage.setItem(LS_KEY, JSON.stringify(next)); } catch {}
+}
+
+export function resetBinding(actionId) {
+  const def = ACTIONS[actionId]?.defaultCombo;
+  if (!def) return;
+  setBinding(actionId, def);
+}
+
+// Normalize a keydown event into a canonical combo string. Order:
+// Ctrl, Alt, Shift, Meta — then the key. Letter keys are uppercased.
+// Arrow keys retain "ArrowUp" / "ArrowDown" form.
+export function comboFromEvent(ev) {
+  if (!ev) return '';
+  const parts = [];
+  if (ev.ctrlKey) parts.push('Ctrl');
+  if (ev.altKey) parts.push('Alt');
+  if (ev.shiftKey) parts.push('Shift');
+  if (ev.metaKey) parts.push('Meta');
+  // Skip pure-modifier keydowns — those happen when the user presses
+  // just Ctrl/Alt/Shift/Meta on its own and we'd record a useless
+  // "Ctrl" combo. The recorder UI uses this; the matcher doesn't.
+  if (['Control', 'Alt', 'Shift', 'Meta'].includes(ev.key)) return '';
+  let key = ev.key;
+  if (/^[a-z]$/.test(key)) key = key.toUpperCase();
+  parts.push(key);
+  return parts.join('+');
+}
+
+// Build a flat list of sessions in the order they appear in the
+// sidebar — folder order first, then sessions within each folder,
+// then the unsorted bucket. Mirrors Sidebar's render order so
+// Next/Prev moves "down then up" visually.
+function flatSidebarOrder() {
+  const grouped = sessionsByFolder.value;
+  const out = [];
+  // folders.value now includes the synthetic Unsorted entry inline at
+  // its own user-set order — no need to special-case the bucket here.
+  for (const f of folders.value) {
+    const list = grouped.get(f.id) || [];
+    for (const s of list) out.push(s.id);
+  }
+  return out;
+}
+
+function moveSelection(delta) {
+  const ids = flatSidebarOrder();
+  if (ids.length === 0) return;
+  const cur = activeSessionId.value;
+  const idx = cur ? ids.indexOf(cur) : -1;
+  let next;
+  if (idx < 0) {
+    next = delta > 0 ? ids[0] : ids[ids.length - 1];
+  } else {
+    next = ids[(idx + delta + ids.length) % ids.length];
+  }
+  if (next) selectSession(next);
+}
+
+// Move the active session one slot up/down within its current folder.
+// Clamps at folder boundaries (doesn't cross folders — that's what
+// drag-and-drop is for). No-op when there's no active session, or
+// when the session is already at the folder edge.
+function moveActiveSessionInFolder(delta) {
+  const cur = activeSessionId.value;
+  if (!cur) return;
+  const s = sessions.value.find((x) => x.id === cur);
+  if (!s) return;
+  const folderId = s.folderId || null;
+  const folderKey = folderId || UNSORTED_KEY;
+  const siblings = sessionsByFolder.value.get(folderKey) || [];
+  const ids = siblings.map((x) => x.id);
+  const idx = ids.indexOf(cur);
+  if (idx < 0) return;
+  const target = idx + delta;
+  if (target < 0 || target >= ids.length) return;
+  const next = ids.slice();
+  next.splice(idx, 1);
+  next.splice(target, 0, cur);
+  reorderSessions(folderId, next).catch((e) => setToast(e.message, 'error'));
+}
+
+const HANDLERS = {
+  'session-next':      () => moveSelection(+1),
+  'session-prev':      () => moveSelection(-1),
+  'session-move-down': () => moveActiveSessionInFolder(+1),
+  'session-move-up':   () => moveActiveSessionInFolder(-1),
+};
+
+// Should we suppress shortcut handling because the user is typing into
+// an input / textarea? Terminal's xterm hidden textarea counts too,
+// but we deliberately let our Ctrl+Alt combos through there because
+// the terminal child process never uses them.
+function shouldSuppress(target) {
+  if (!target) return false;
+  const tag = (target.tagName || '').toLowerCase();
+  if (tag === 'input' || tag === 'textarea') {
+    // Exception: xterm's helper textarea is a hidden input — we want
+    // shortcuts to fire there.
+    if (target.classList?.contains('xterm-helper-textarea')) return false;
+    return true;
+  }
+  if (target.isContentEditable) return true;
+  return false;
+}
+
+let installed = false;
+export function installGlobalKeybindings() {
+  if (installed) return;
+  installed = true;
+  window.addEventListener('keydown', (ev) => {
+    if (shouldSuppress(ev.target)) return;
+    const combo = comboFromEvent(ev);
+    if (!combo) return;
+    const map = keybindings.value;
+    for (const [action, expected] of Object.entries(map)) {
+      if (expected === combo && HANDLERS[action]) {
+        ev.preventDefault();
+        ev.stopPropagation();
+        HANDLERS[action]();
+        return;
+      }
+    }
+  }, true);
+}
+
+// Pretty-print a combo for display in Settings. Replace verbose key
+// names with shorter symbols where it helps.
+export function formatCombo(combo) {
+  if (!combo) return '(unset)';
+  return combo
+    .replace(/ArrowUp/g, '↑')
+    .replace(/ArrowDown/g, '↓')
+    .replace(/ArrowLeft/g, '←')
+    .replace(/ArrowRight/g, '→');
+}

package/public/js/main.js

@@ -9,8 +9,10 @@ import { httpBase } from './backend.js';
 import { loadConfig, refreshAll, loadSessions, loadFolders, loadWorkspaces, pollHealth } from './api.js';
 import { setToast } from './toast.js';
 import { App } from './components/App.js';
+import { installGlobalKeybindings } from './keybindings.js';
 
 loadPersisted();
+installGlobalKeybindings();
 // Window/tab title pinned to "CCSM". A MutationObserver guards against
 // Chromium standalone builds that occasionally try to inject the URL
 // into the title bar.

package/public/js/pages/AboutPage.js

@@ -67,21 +67,39 @@ function UpgradeCard() {
     try {
       const r = await api('POST', '/api/upgrade', { target: 'latest' });
       setToast(`upgrading to v${info.latest} · backend will restart`);
-      if (r?.closeFrontend) {
-        // Backend will respawn with a fresh browser window — close this
-        // one so the user isn't stuck on the OfflineBanner during the
-        // upgrade window. window.close() only works when the window was
-        // script-opened (Edge --app=, our spawned browser); regular tabs
-        // ignore it silently, which is fine (OfflineBanner takes over).
+      if (r?.helperUrl) {
+        setTimeout(() => { location.href = r.helperUrl; }, 300);
+      } else if (r?.closeFrontend) {
         setTimeout(() => { try { window.close(); } catch {} }, 400);
       }
     } catch (e) {
       setUpgrading(false);
       setToast(e.message, 'error');
     }
-    // No "finally" reset — the server is about to shut down, and the
-    // OfflineBanner takes over UI. When the router reroutes us to the new
-    // version's frontend, this component re-mounts fresh.
+  };
+
+  // Dev-only sandbox test path: reinstall the SAME version into a
+  // throwaway prefix under ~/.ccsm-dev/test-install. Exercises the
+  // whole helper UI + SSE + lockfile flow without touching the user's
+  // global install. respawn=false keeps the helper showing "done"
+  // until it self-exits.
+  const onTestUpgrade = async () => {
+    if (!info?.current) return;
+    setUpgrading(true);
+    try {
+      const r = await api('POST', '/api/upgrade', {
+        target: info.current,
+        installPrefix: 'C:\\Users\\jiannanli\\.ccsm-dev\\test-install',
+        respawn: false,
+      });
+      setToast(`test upgrade · reinstalling v${info.current} to sandbox`);
+      if (r?.helperUrl) {
+        setTimeout(() => { location.href = r.helperUrl; }, 300);
+      }
+    } catch (e) {
+      setUpgrading(false);
+      setToast(e.message, 'error');
+    }
   };
 
   const current = info?.current || serverHealth.value.version || '';
@@ -116,6 +134,12 @@ function UpgradeCard() {
               ${upgrading ? 'Upgrading…' : `Upgrade to v${latest}`}
             </button>
           ` : null}
+          ${info?.devMode && !updateAvailable ? html`
+            <button class="action subtle" onClick=${onTestUpgrade} disabled=${upgrading}
+                    title="Reinstall to a sandbox prefix to exercise the updater UI without touching prod">
+              ${upgrading ? 'Testing…' : 'Test upgrade flow'}
+            </button>
+          ` : null}
         </div>
       </div>
       ${upgrading ? html`

package/public/js/pages/ConfigurePage.js

@@ -17,11 +17,13 @@ import {
 } from '../api.js';
 import { setToast } from '../toast.js';
 import { ccsmConfirm } from '../dialog.js';
+import { keybindings, setBinding, resetBinding, ACTIONS, formatCombo } from '../keybindings.js';
+import { KeybindingRecorder } from '../components/KeybindingRecorder.js';
 import { Card } from '../components/Card.js';
 import { PageTitleBar } from '../components/PageTitleBar.js';
 import { EntityFormModal } from '../components/EntityFormModal.js';
 import { useDragSort } from '../components/useDragSort.js';
-import { IconPlus, IconPencil, IconClose, IconTerminal, IconFolder, IconBranch, IconForCliType, IconClaudeColor, IconCodexColor, IconCopilotColor } from '../icons.js';
+import { IconPlus, IconPencil, IconClose, IconTerminal, IconFolder, IconBranch, IconRefresh, IconChevronUp, IconChevronDown, IconForCliType, IconClaudeColor, IconCodexColor, IconCopilotColor } from '../icons.js';
 
 // Type → smart defaults. Choosing a type in the form auto-fills resumeArgs
 // (and command if blank) so users don't need to remember the per-CLI flag.
@@ -251,6 +253,11 @@ export function ConfigurePage() {
       <${WorkspaceList} />
     </${Section}>
 
+    <${Section} title="Keyboard shortcuts"
+                meta="Click a binding to record a new combo. Press Esc to cancel.">
+      <${KeybindingsList} />
+    </${Section}>
+
     </div>
 
     ${edit?.kind === 'cli-new' ? html`
@@ -511,3 +518,51 @@ function AccentPicker() {
         </div>` : null}
     </div>`;
 }
+
+
+// ── Keyboard shortcuts ───────────────────────────────────────────────
+const ACTION_ICONS = {
+  'session-next':      IconChevronDown,
+  'session-prev':      IconChevronUp,
+  'session-move-down': IconChevronDown,
+  'session-move-up':   IconChevronUp,
+};
+
+function KeybindingsList() {
+  const map = keybindings.value;
+  const [recording, setRecording] = useState(null); // actionId or null
+
+  return html`
+    <div class="entity-list">
+      ${Object.entries(ACTIONS).map(([id, def]) => {
+        const combo = map[id];
+        const isCustom = combo !== def.defaultCombo;
+        const Icon = ACTION_ICONS[id] || IconTerminal;
+        return html`
+          <div class="entity-row" key=${id}>
+            <span class="entity-row-icon"><${Icon} /></span>
+            <span class="entity-row-main">
+              <span class="entity-row-primary">
+                ${def.label}
+                <span class="entity-row-badge tone-accent">${formatCombo(combo)}</span>
+              </span>
+              <span class="entity-row-secondary">
+                <span class="mono">${id}</span> · default <span class="mono">${formatCombo(def.defaultCombo)}</span>
+              </span>
+            </span>
+            <span class="entity-row-actions">
+              <button class="entity-row-action" title="Rebind"
+                      onClick=${() => setRecording(id)}><${IconPencil} /></button>
+              ${isCustom ? html`
+                <button class="entity-row-action" title="Reset to default"
+                        onClick=${() => resetBinding(id)}><${IconRefresh} /></button>` : null}
+            </span>
+          </div>`;
+      })}
+    </div>
+    ${recording ? html`
+      <${KeybindingRecorder}
+        actionLabel=${ACTIONS[recording]?.label || recording}
+        onCommit=${(combo) => { setBinding(recording, combo); setRecording(null); }}
+        onCancel=${() => setRecording(null)} />` : null}`;
+}

package/public/js/state.js

@@ -13,6 +13,10 @@ export const sessions     = signal([]);
 export const folders      = signal([]);   // [{id,name,order,createdAt}]
 export const workspaces   = signal([]);
 export const serverHealth = signal({ state: 'connecting' });
+// Flips true the first time we successfully reach the backend in this
+// frontend session. Gates UI (HealthOverlay) so it doesn't pop on the
+// very first boot probe while the page is still wiring up.
+export const hasBootedOnline = signal(false);
 
 // ── ui state (persisted in localStorage where noted) ───────────
 export const activeTab        = signal('sessions');
@@ -48,17 +52,32 @@ export const isInstalledPwa   = signal(false);           // running inside an in
 // matching folder hasn't loaded yet — that way on first paint sessions
 // don't all collapse into Unsorted and then snap back into their real
 // folder a few ms later when /api/folders resolves.
+// "Unsorted" is keyed as 'unsorted' (not null) so it can be looked up
+// alongside real folders by Sidebar/keybindings iterating folders.value
+// — backend exposes a synthetic folder with id='unsorted' that's always
+// present, drag-reorderable like real folders.
+export const UNSORTED_KEY = 'unsorted';
 export const sessionsByFolder = computed(() => {
   const groups = new Map();
-  groups.set(null, []);
+  groups.set(UNSORTED_KEY, []);
   for (const f of folders.value) groups.set(f.id, []);
   for (const s of sessions.value) {
-    const key = s.folderId || null;
+    const key = s.folderId || UNSORTED_KEY;
     if (!groups.has(key)) groups.set(key, []);
     groups.get(key).push(s);
   }
   for (const list of groups.values()) {
-    list.sort((a, b) => (b.createdAt || 0) - (a.createdAt || 0));
+    // Stable sort: explicit `order` field first (set by user drag), then
+    // createdAt desc as fallback. Sessions without `order` fall to the
+    // top (newer-first) which is the legacy behavior.
+    list.sort((a, b) => {
+      const oa = typeof a.order === 'number' ? a.order : null;
+      const ob = typeof b.order === 'number' ? b.order : null;
+      if (oa !== null && ob !== null) return oa - ob;
+      if (oa !== null) return -1;
+      if (ob !== null) return 1;
+      return (b.createdAt || 0) - (a.createdAt || 0);
+    });
   }
   return groups;
 });