@bakapiano/ccsm 0.16.0 → 0.17.2

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

@@ -10,11 +10,15 @@
 // never bind those combos.
 
 import { signal } from '@preact/signals';
-import { activeSessionId, sessions, folders, sessionsByFolder, selectSession } from './state.js';
+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-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';
@@ -76,11 +80,12 @@ export function comboFromEvent(ev) {
 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);
   }
-  for (const s of grouped.get(null) || []) out.push(s.id);
   return out;
 }
 
@@ -98,9 +103,34 @@ function moveSelection(delta) {
   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-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

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,7 +17,8 @@ import {
 } from '../api.js';
 import { setToast } from '../toast.js';
 import { ccsmConfirm } from '../dialog.js';
-import { keybindings, setBinding, resetBinding, ACTIONS, formatCombo, comboFromEvent } from '../keybindings.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';
@@ -41,30 +42,51 @@ function cliFieldsFor({ creating } = {}) {
       { value: 'copilot', label: 'GitHub Copilot', icon: html`<${IconCopilotColor} />` },
       { value: 'other',   label: 'Other',          icon: html`<${IconTerminal} />` },
     ],
-      // When user picks a type while creating, prefill command + resumeArgs.
-      // For edit mode we don't override what the user already has.
-      onChange: creating ? (v, next) => {
+      // Type-change side effects. For known types we force the
+      // integration args (newSessionIdArgs / resumeIdArgs) to the
+      // canonical template — those fields are locked anyway so
+      // there's no value in leaving stale strings around. For
+      // type='other' we leave existing args alone so the user can
+      // keep editing them. Name + command are only prefilled when
+      // creating (don't clobber a saved CLI's name on edit).
+      onChange: (v, next) => {
         const d = CLI_TYPE_DEFAULTS[v];
         if (!d) return null;
-        const patch = { resumeIdArgs: d.resumeIdArgs, newSessionIdArgs: d.newSessionIdArgs };
-        if (!next.command || !next.command.trim()) patch.command = d.command || '';
-        if (!next.name || !next.name.trim()) {
-          patch.name = v === 'claude' ? 'Claude Code'
-                     : v === 'codex' ? 'OpenAI Codex'
-                     : v === 'copilot' ? 'GitHub Copilot'
-                     : '';
+        const patch = {};
+        if (v !== 'other') {
+          patch.resumeIdArgs = d.resumeIdArgs;
+          patch.newSessionIdArgs = d.newSessionIdArgs;
+        }
+        if (creating) {
+          if (!next.command || !next.command.trim()) patch.command = d.command || '';
+          if (!next.name || !next.name.trim()) {
+            patch.name = v === 'claude' ? 'Claude Code'
+                       : v === 'codex' ? 'OpenAI Codex'
+                       : v === 'copilot' ? 'GitHub Copilot'
+                       : '';
+          }
         }
         return patch;
-      } : undefined,
+      },
     },
     { key: 'name', label: 'Name', placeholder: 'My CLI', required: true },
     { key: 'command', label: 'Command', mono: true, placeholder: 'ccp / claude / ...', required: true },
     { key: 'args', label: 'Args (space-separated)', mono: true, placeholder: '',
       hint: 'Used on every launch.' },
     { key: 'newSessionIdArgs', label: 'New session id args', mono: true, placeholder: '--session-id <id>',
-      hint: 'ccsm pre-generates a UUID and substitutes it for <id> on first launch — the upstream CLI session id is known immediately.' },
+      // Lock for known types — those args are an integration contract
+      // with the upstream CLI, not a user knob. Only Type=Other allows
+      // a custom value (for hand-rolled CLIs ccsm doesn't ship a
+      // template for).
+      readOnly: (d) => d.type && d.type !== 'other',
+      hint: (d) => d.type && d.type !== 'other'
+        ? `Locked to the canonical flags for ${d.type}. Change Type to "Other" to override.`
+        : 'ccsm pre-generates a UUID and substitutes it for <id> on first launch — the upstream CLI session id is known immediately.' },
     { key: 'resumeIdArgs', label: 'Resume by id args', mono: true, placeholder: '--resume <id>',
-      hint: 'Used on every resume. Substitutes <id> with the captured session UUID.' },
+      readOnly: (d) => d.type && d.type !== 'other',
+      hint: (d) => d.type && d.type !== 'other'
+        ? `Locked to the canonical flags for ${d.type}. Change Type to "Other" to override.`
+        : 'Used on every resume. Substitutes <id> with the captured session UUID.' },
     { key: 'shell', label: 'Shell', type: 'select', default: 'direct', options: [
       { value: 'direct', label: 'direct (real .exe / .cmd)' },
       { value: 'pwsh',   label: 'pwsh (PowerShell aliases & functions)' },
@@ -521,69 +543,47 @@ function AccentPicker() {
 
 // ── Keyboard shortcuts ───────────────────────────────────────────────
 const ACTION_ICONS = {
-  'session-next': IconChevronDown,
-  'session-prev': IconChevronUp,
+  '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
 
-  // While recording, swallow every keydown globally and feed it into
-  // comboFromEvent. We use the capture phase so the global shortcut
-  // listener never sees the keys and never fires actions mid-record.
-  useEffect(() => {
-    if (!recording) return;
-    const onKey = (ev) => {
-      if (ev.key === 'Escape') {
-        ev.preventDefault();
-        ev.stopPropagation();
-        setRecording(null);
-        return;
-      }
-      const combo = comboFromEvent(ev);
-      if (!combo) return; // pure-modifier keydown, keep listening
-      ev.preventDefault();
-      ev.stopPropagation();
-      setBinding(recording, combo);
-      setRecording(null);
-    };
-    window.addEventListener('keydown', onKey, true);
-    return () => window.removeEventListener('keydown', onKey, true);
-  }, [recording]);
-
   return html`
     <div class="entity-list">
       ${Object.entries(ACTIONS).map(([id, def]) => {
         const combo = map[id];
-        const isRec = recording === id;
         const isCustom = combo !== def.defaultCombo;
         const Icon = ACTION_ICONS[id] || IconTerminal;
-        const badges = [{
-          label: isRec ? 'press keys…' : formatCombo(combo),
-          tone: isRec ? 'warn' : 'accent',
-        }];
         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}
-                ${badges.map((b) => html`
-                  <span class=${`entity-row-badge tone-${b.tone}`}>${b.label}</span>`)}
+                <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=${isRec ? 'Cancel (Esc)' : 'Rebind'}
-                      onClick=${() => setRecording(isRec ? null : id)}><${IconPencil} /></button>
+              <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>`;
+    </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;
 });

package/scripts/dev.js

@@ -38,6 +38,52 @@ if (!fs.existsSync(configPath)) {
   }, null, 2));
 }
 
+// Mirror pages-root assets into public/ so the dev server can serve
+// them at the URL paths the deployed site uses (manifest at
+// /manifest.webmanifest, setup page at /setup/). Both mirror files
+// are .gitignored — they exist only for local preview.
+//
+// The manifest is rewritten with a "ccsm-dev" identity so the PWA
+// installed from dev shows up separately in Chrome's installed-apps
+// list and Start Menu, instead of conflicting with the prod CCSM
+// install.
+const REPO_ROOT = path.join(__dirname, '..');
+const PAGES_ROOT = path.join(REPO_ROOT, 'pages-root');
+const PUBLIC_DIR = path.join(REPO_ROOT, 'public');
+
+function mirrorSetup() {
+  try {
+    const src = path.join(PAGES_ROOT, 'setup');
+    const dst = path.join(PUBLIC_DIR, 'setup');
+    fs.mkdirSync(dst, { recursive: true });
+    for (const f of fs.readdirSync(src)) {
+      fs.copyFileSync(path.join(src, f), path.join(dst, f));
+    }
+  } catch (e) { console.warn('[dev] setup mirror failed:', e.message); }
+}
+function writeDevManifest() {
+  try {
+    const src = path.join(PAGES_ROOT, 'manifest.webmanifest');
+    const m = JSON.parse(fs.readFileSync(src, 'utf8'));
+    m.id = '/?ccsm-dev';
+    m.name = 'CCSM dev';
+    m.short_name = 'CCSM dev';
+    // Dev runs at host root (localhost:7788/), so scope + start_url
+    // anchor at `/` not `./` (which would resolve relative to the
+    // manifest URL — same result here, but explicit is clearer).
+    m.scope = '/';
+    m.start_url = '/';
+    // Drop related_applications self-reference — its URL points at
+    // the prod GH Pages manifest, not this dev one. Leaving it in
+    // would let prod's getInstalledRelatedApps() detect dev installs
+    // as if they were prod, which is the opposite of what we want.
+    delete m.related_applications;
+    fs.writeFileSync(path.join(PUBLIC_DIR, 'manifest.webmanifest'), JSON.stringify(m, null, 2));
+  } catch (e) { console.warn('[dev] manifest mirror failed:', e.message); }
+}
+mirrorSetup();
+writeDevManifest();
+
 const env = {
   ...process.env,
   CCSM_HOME: DEV_HOME,

package/scripts/install.js

@@ -130,29 +130,24 @@ try {
   warn('the hosted frontend\'s "Start ccsm" button will not be able to launch the backend. You can still run `ccsm` manually in a terminal.');
 }
 
-// Auto-launch ccsm after install so the user lands directly in the app
-// without needing a second command. Detached + windowsHide so the npm
-// install command returns immediately. Skip if CCSM_NO_AUTOLAUNCH=1 is
-// set (CI, headless setups).
+// Open the hosted setup guide. The page walks the user through the
+// remaining one-time setup (allow ccsm:// protocol, firewall, install
+// as PWA) and Step 1's "Try ccsm://start" button doubles as ccsm
+// auto-launch — so we don't need a separate spawn here. Set
+// CCSM_NO_AUTOLAUNCH=1 to skip (CI, headless setups).
 if (process.env.CCSM_NO_AUTOLAUNCH !== '1') {
   try {
-    const { spawn } = require('node:child_process');
-    // Spawn `node bin/ccsm.js` directly — NOT ccsm.cmd. On Windows,
-    // child_process.spawn() with shell:false refuses .cmd files (throws
-    // EINVAL); using shell:true would flash a console window. Going
-    // through node + the JS entrypoint sidesteps both problems and
-    // matches exactly what the .cmd shim would have invoked.
-    const launcherJs = path.join(__dirname, '..', 'bin', 'ccsm.js');
-    const child = spawn(process.execPath, [launcherJs], {
-      detached: true,
-      stdio: 'ignore',
-      windowsHide: true,
-    });
-    child.unref();
-    log('launching ccsm now · check for the chromeless window');
+    // `start` on Windows opens the default browser without attaching a
+    // console. Run via cmd.exe /c since `start` is a cmd builtin.
+    require('node:child_process').spawn(
+      'cmd.exe',
+      ['/d', '/s', '/c', 'start', '', 'https://bakapiano.github.io/ccsm/setup/'],
+      { detached: true, stdio: 'ignore', windowsHide: true }
+    ).unref();
+    log('opened setup guide · https://bakapiano.github.io/ccsm/setup/');
     log('(set CCSM_NO_AUTOLAUNCH=1 to skip this on future installs)');
   } catch (e) {
-    warn(`auto-launch failed · ${e.message}`);
+    warn(`setup guide open failed · ${e.message}`);
     warn('run `ccsm` manually to start.');
   }
 }