feat(frontend): theme-aware particle dissolve + spinner spawn loader

Replace abrupt session removal with a canvas-based "Thanos snap" particle
dispersion: edge-biased, omnidirectional, theme-coloured fine dust drifting
outward. Two presets — `card` (long & dramatic, ~260 particles, 1500ms) for
SessionsHub, `tab` (short & snappy, ~90 particles, 700ms) for TabBar +
SidePanel. Particle palette is built live from session.color + the active
theme's --accent and --text CSS vars (exponential weight decay) so the dust
stays coherent with whatever theme is active. New particleDissolve preference
(default true) gates the canvas effect; the host CSS fade still plays so the
row always exits smoothly.

Replace the blank pre-paint state on freshly spawned terminal sessions with
a Braille dots spinner — the same loader idiom used by npm/cargo/yarn/gh —
gated by a 150ms show-delay so fast localhost spawns never flicker. Drives
off the first xterm onWriteParsed event (true first paint) rather than the
WebSocket attach ack, and fades gracefully on first byte.

Coordinated via a shared dissolvingIds Set on useSessionStore + a
useDissolveDelete hook that fires API DELETE in parallel with the visual,
removes the row from local/store state once the host fade completes, and
shields the polling loops in TerminalApp + SessionsHub so the row stays
mounted long enough for the animation to play out. Hero-source rule means
only the surface the user clicked emits canvas particles; mirror surfaces
play the CSS fade only. Concurrency cap at 3 active canvases. Honors
prefers-reduced-motion throughout.

Also fixes two flaky test categories surfaced while developing this:

* macOS dev-machine flake — file-tree.test.js, preview.test.js,
  config.test.js, tunnel-token-renewal.test.js all called
  createTermBeamServer without isolating configDir, so on developer machines
  they would read ~/.termbeam/prefs.json and auto-spawn workspace sessions
  whose cwd overrode the test fixture. Each test now creates a per-server
  mkdtempSync configDir cleaned up in after().

* Windows CI 180s timeout — node-pty ConPTY threads persist after pty.kill()
  and keep the per-file worker alive past the test-timeout. npm test +
  npm run test:coverage now pass --test-force-exit, Node's supported flag
  for forcing worker exit after all tests complete.

Documentation updates in copilot-instructions.md cover both invariants.

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

Author: dorlugasigal

.github/copilot-instructions.md

@@ -35,6 +35,8 @@ Pre-commit hooks (Husky + lint-staged) auto-format and syntax-check staged files
 - **`test/cli/resume.test.js`** — uses `TERMBEAM_CONFIG_DIR` env var pointing to a temp directory for isolation.
 - **WebSocket connections** — close in `finally` blocks or `after()` hooks to prevent connection leaks.
 - **Windows temp directory cleanup** — on Windows, node-pty ConPTY holds directory locks after `pty.kill()`. Use `await safeCleanup(dir)` (async `fs.promises.rm` with `maxRetries`) instead of `fs.rmSync` in `after()` hooks and `finally` blocks when the temp dir was used as a PTY CWD. See the `safeCleanup()` helper in `test/server/routes.test.js`.
+- **`configDir` isolation** — every test that calls `createTermBeamServer({ config })` MUST set `configDir` (or `TERMBEAM_CONFIG_DIR` env var) to a fresh `mkdtempSync` temp directory. Without this, the server reads the developer's real `~/.termbeam/prefs.json` and may auto-spawn workspace sessions with a different `cwd`, silently breaking assertions about the default session. `routes.test.js`'s `startServer()` is the canonical example.
+- **`--test-force-exit`** — `npm test` passes this flag so dangling Windows ConPTY threads can't keep the worker alive past the 180 s per-file timeout. Tests that legitimately need to leak resources for assertions should be flagged in the suite description.
 
 **Port isolation:** Integration tests use port `0` (OS-assigned random port) to avoid conflicts. Never hardcode ports in tests.
 

package.json

@@ -9,8 +9,8 @@
   "scripts": {
     "start": "node bin/termbeam.js",
     "dev": "node bin/termbeam.js --generate-password",
-    "test": "node -e \"const{execFileSync:r}=require('child_process'),{readdirSync:d,statSync:s}=require('fs'),{join:j}=require('path');function f(p){let a=[];for(const e of d(p)){const c=j(p,e);s(c).isDirectory()?a.push(...f(c)):e.endsWith('.test.js')&&!e.startsWith('e2e-')&&e!=='devtunnel-install.test.js'&&a.push(c)}return a}r(process.execPath,['--test','--test-timeout=180000',...f('test')],{stdio:'inherit'})\"",
-    "test:coverage": "c8 --reporter=text --reporter=lcov --reporter=json-summary --reporter=json node -e \"const{execFileSync:r}=require('child_process'),{readdirSync:d,statSync:s}=require('fs'),{join:j}=require('path');function f(p){let a=[];for(const e of d(p)){const c=j(p,e);s(c).isDirectory()?a.push(...f(c)):e.endsWith('.test.js')&&!e.startsWith('e2e-')&&e!=='devtunnel-install.test.js'&&a.push(c)}return a}r(process.execPath,['--test','--test-timeout=180000','--test-reporter=spec','--test-reporter-destination=stdout',...f('test')],{stdio:'inherit'})\"",
+    "test": "node -e \"const{execFileSync:r}=require('child_process'),{readdirSync:d,statSync:s}=require('fs'),{join:j}=require('path');function f(p){let a=[];for(const e of d(p)){const c=j(p,e);s(c).isDirectory()?a.push(...f(c)):e.endsWith('.test.js')&&!e.startsWith('e2e-')&&e!=='devtunnel-install.test.js'&&a.push(c)}return a}r(process.execPath,['--test','--test-timeout=180000','--test-force-exit',...f('test')],{stdio:'inherit'})\"",
+    "test:coverage": "c8 --reporter=text --reporter=lcov --reporter=json-summary --reporter=json node -e \"const{execFileSync:r}=require('child_process'),{readdirSync:d,statSync:s}=require('fs'),{join:j}=require('path');function f(p){let a=[];for(const e of d(p)){const c=j(p,e);s(c).isDirectory()?a.push(...f(c)):e.endsWith('.test.js')&&!e.startsWith('e2e-')&&e!=='devtunnel-install.test.js'&&a.push(c)}return a}r(process.execPath,['--test','--test-timeout=180000','--test-force-exit','--test-reporter=spec','--test-reporter-destination=stdout',...f('test')],{stdio:'inherit'})\"",
     "prepare": "husky",
     "format": "prettier --write .",
     "lint": "node --check src/server/*.js src/cli/*.js src/tunnel/*.js src/utils/*.js bin/*.js",

src/frontend/src/components/SessionsHub/SessionCard.tsx

@@ -3,6 +3,8 @@ import type { Session } from '@/types';
 import { CopilotLogo } from '@/components/common/CopilotLogo';
 import styles from './SessionCard.module.css';
 
+import dissolveStyles from '@/components/common/Disintegrate.module.css';
+
 interface SessionCardProps {
   session: Session;
   onSelect: (id: string) => void;
@@ -14,6 +16,12 @@ interface SessionCardProps {
    * entrance so cards cascade in instead of appearing all at once.
    */
   index?: number;
+  /**
+   * When true, the card is playing the disintegrate (Thanos-snap)
+   * animation prior to being removed. Disables interaction and applies
+   * the dust effect via a CSS modifier class.
+   */
+  dissolving?: boolean;
 }
 
 function formatActivity(lastActivity: string | number): string {
@@ -96,6 +104,7 @@ export default function SessionCard({
   revealedId,
   onRevealChange,
   index = 0,
+  dissolving = false,
 }: SessionCardProps) {
   const cardRef = useRef<HTMLDivElement>(null);
   const touchStartX = useRef(0);
@@ -213,14 +222,17 @@ export default function SessionCard({
 
   return (
     <div
-      className={styles.wrapper}
+      className={`${styles.wrapper} ${dissolving ? dissolveStyles.dissolving : ''}`}
       style={{ ['--stagger-i' as string]: Math.min(index, 8) }}
+      data-session-id={session.id}
+      aria-hidden={dissolving || undefined}
     >
       <button
         className={styles.deleteBackground}
         onClick={handleDeleteClick}
         aria-label={`Delete session ${session.name}`}
         type="button"
+        disabled={dissolving}
       >
         <TrashIcon />
         Delete
@@ -229,7 +241,10 @@ export default function SessionCard({
         ref={cardRef}
         className={styles.card}
         data-testid="session-card"
-        onClick={() => onSelect(session.id)}
+        onClick={() => {
+          if (dissolving) return;
+          onSelect(session.id);
+        }}
         onTouchStart={handleTouchStart}
         onTouchMove={handleTouchMove}
         onTouchEnd={handleTouchEnd}

src/frontend/src/components/SessionsHub/SessionsHub.tsx

@@ -2,6 +2,8 @@ import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
 import { toast } from 'sonner';
 import { fetchSessions, deleteSession, fetchVersion, getShareUrl } from '@/services/api';
 import { useUIStore } from '@/stores/uiStore';
+import { useSessionStore } from '@/stores/sessionStore';
+import { useDissolveDelete } from '@/hooks/useDissolveDelete';
 import ThemePicker from '@/components/common/ThemePicker';
 import type { Session } from '@/types';
 import UpdateBanner from '@/components/common/UpdateBanner';
@@ -87,6 +89,7 @@ export default function SessionsHub() {
   const [revealedId, setRevealedId] = useState<string | null>(null);
   const [filter, setFilter] = useState<SessionFilterState>(() => loadFilterFromStorage());
   const [workspaceLauncherOpen, setWorkspaceLauncherOpen] = useState(false);
+  const listRef = useRef<HTMLDivElement>(null);
   const {
     openNewSessionModal,
     openResumeBrowser,
@@ -95,10 +98,23 @@ export default function SessionsHub() {
     closeThemePicker,
   } = useUIStore();
 
+  const dissolvingIds = useSessionStore((s) => s.dissolvingIds);
+  const dissolveDelete = useDissolveDelete();
+
   const loadSessions = useCallback(async () => {
     try {
       const list = await fetchSessions();
-      setSessions(list.filter((s) => !s.hidden));
+      const visible = list.filter((s) => !s.hidden);
+      setSessions((prev) => {
+        // Re-include any sessions currently mid-dissolve so the row
+        // stays mounted long enough for the disintegrate animation to
+        // play. The server has already removed them by this point.
+        const visibleIds = new Set(visible.map((s) => s.id));
+        const dissolveExtras = prev.filter(
+          (s) => useSessionStore.getState().dissolvingIds.has(s.id) && !visibleIds.has(s.id),
+        );
+        return [...visible, ...dissolveExtras];
+      });
     } catch {
       // Silently retry on next poll
     } finally {
@@ -149,9 +165,16 @@ export default function SessionsHub() {
 
   async function handleDelete(id: string) {
     const session = sessions.find((s) => s.id === id);
+    const element = listRef.current?.querySelector<HTMLElement>(
+      `[data-session-id="${id}"]`,
+    );
     try {
-      await deleteSession(id);
-      setSessions((prev) => prev.filter((s) => s.id !== id));
+      await dissolveDelete(id, {
+        element: element ?? null,
+        color: session?.color ?? '#6ec1e4',
+        apiDelete: () => deleteSession(id),
+        finalize: () => setSessions((prev) => prev.filter((s) => s.id !== id)),
+      });
       toast.success(`Session "${session?.name ?? id}" deleted`);
     } catch (err) {
       toast.error(err instanceof Error ? err.message : 'Failed to delete session');
@@ -355,6 +378,7 @@ export default function SessionsHub() {
               </div>
             ) : (
               <div
+                ref={listRef}
                 className={styles.sessionsList}
                 data-testid="sessions-list"
                 data-filter-active={filterActive || undefined}
@@ -368,6 +392,7 @@ export default function SessionsHub() {
                     revealedId={revealedId}
                     onRevealChange={setRevealedId}
                     index={i}
+                    dissolving={dissolvingIds.has(session.id)}
                   />
                 ))}
               </div>

src/frontend/src/components/SettingsPanel/SettingsPanel.tsx

@@ -438,6 +438,21 @@ export default function SettingsPanel() {
                 onChange={(v) => setPreference('showSplash', v)}
               />
             </div>
+
+            <div className={styles.row}>
+              <span className={styles.rowLabel}>
+                Particle dissolve
+                <span className={styles.rowHint}>
+                  Play the canvas particle effect when deleting a session. Turn off for a plain
+                  fade only — useful on low-power devices.
+                </span>
+              </span>
+              <Toggle
+                on={prefs.particleDissolve}
+                ariaLabel="Toggle particle dissolve effect"
+                onChange={(v) => setPreference('particleDissolve', v)}
+              />
+            </div>
           </section>
 
           {/* ── Touch Bar ─────────────────────────────────────────── */}

src/frontend/src/components/SidePanel/SidePanel.tsx

@@ -2,8 +2,10 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import type { ManagedSession } from '@/stores/sessionStore';
 import { useSessionStore } from '@/stores/sessionStore';
 import { useUIStore } from '@/stores/uiStore';
+import { useDissolveDelete } from '@/hooks/useDissolveDelete';
 import { fetchVersion, deleteSession } from '@/services/api';
 import { FileBrowser } from '@/components/FileBrowser/FileBrowser';
+import dissolveStyles from '@/components/common/Disintegrate.module.css';
 import styles from './SidePanel.module.css';
 
 function getActivityLabel(ts: string | number | undefined): string {
@@ -59,13 +61,16 @@ export function SidePanel() {
   const sessions = useSessionStore((s) => s.sessions);
   const activeId = useSessionStore((s) => s.activeId);
   const tabOrder = useSessionStore((s) => s.tabOrder);
+  const dissolvingIds = useSessionStore((s) => s.dissolvingIds);
   const setActiveId = useSessionStore((s) => s.setActiveId);
   const removeSession = useSessionStore((s) => s.removeSession);
+  const dissolveDelete = useDissolveDelete();
 
   const [closing, setClosing] = useState(false);
   const [version, setVersion] = useState('');
   const [showFiles, setShowFiles] = useState(false);
   const panelRef = useRef<HTMLDivElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
 
   const animateClose = useCallback(() => {
     setClosing(true);
@@ -107,9 +112,21 @@ export function SidePanel() {
 
   const handleClose = (e: React.MouseEvent, id: string) => {
     e.stopPropagation();
+    if (dissolvingIds.has(id)) return;
     if (confirm('Close this session?')) {
-      deleteSession(id).catch(() => {});
-      removeSession(id);
+      if (id === activeId) {
+        const nextActive = tabOrder.find((tid) => tid !== id && sessions.has(tid));
+        if (nextActive) setActiveId(nextActive);
+      }
+      const session = sessions.get(id);
+      const rowEl = listRef.current?.querySelector<HTMLElement>(`[data-session-id="${id}"]`);
+      void dissolveDelete(id, {
+        element: rowEl ?? null,
+        color: session?.color || '#6ec1e4',
+        variant: 'tab',
+        apiDelete: () => deleteSession(id),
+        finalize: () => removeSession(id),
+      });
     }
   };
 
@@ -164,23 +181,49 @@ export function SidePanel() {
             <div className={styles.sectionTitle}>Sessions</div>
 
             {/* Session list */}
-            <div className={styles.list} data-testid="side-panel-list">
+            <div ref={listRef} className={styles.list} data-testid="side-panel-list">
               {orderedSessions.map((session) => {
                 const activity = getActivityLabel(session.lastActivity);
                 const git = session.git;
+                const isDissolvingRow = dissolvingIds.has(session.id);
 
                 return (
                   <div
                     key={session.id}
-                    className={`${styles.card} ${session.id === activeId ? styles.cardActive : ''}`}
+                    className={`${styles.card} ${session.id === activeId ? styles.cardActive : ''} ${isDissolvingRow ? dissolveStyles.dissolving : ''}`}
                     data-testid="side-panel-card"
-                    onClick={() => selectSession(session.id)}
+                    data-session-id={session.id}
+                    aria-hidden={isDissolvingRow || undefined}
+                    style={
+                      isDissolvingRow
+                        ? ({ ['--termbeam-fragment-ms' as string]: '280ms' } as React.CSSProperties)
+                        : undefined
+                    }
+                    onClick={() => {
+                      if (isDissolvingRow) return;
+                      selectSession(session.id);
+                    }}
                     onAuxClick={(e) => {
+                      if (isDissolvingRow) return;
                       if (e.button === 1) {
                         e.preventDefault();
                         if (confirm('Close this session?')) {
-                          deleteSession(session.id).catch(() => {});
-                          removeSession(session.id);
+                          if (session.id === activeId) {
+                            const nextActive = tabOrder.find(
+                              (tid) => tid !== session.id && sessions.has(tid),
+                            );
+                            if (nextActive) setActiveId(nextActive);
+                          }
+                          const rowEl = listRef.current?.querySelector<HTMLElement>(
+                            `[data-session-id="${session.id}"]`,
+                          );
+                          void dissolveDelete(session.id, {
+                            element: rowEl ?? null,
+                            color: session.color || '#6ec1e4',
+                            variant: 'tab',
+                            apiDelete: () => deleteSession(session.id),
+                            finalize: () => removeSession(session.id),
+                          });
                         }
                       }
                     }}

src/frontend/src/components/TabBar/SortableTab.tsx

@@ -3,12 +3,15 @@ import { useSortable } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
 import type { ManagedSession } from '@/stores/sessionStore';
 import { CopilotLogo } from '@/components/common/CopilotLogo';
+import dissolveStyles from '@/components/common/Disintegrate.module.css';
 import styles from './TabBar.module.css';
 
 interface SortableTabProps {
   session: ManagedSession;
   isActive: boolean;
   isSplit?: boolean;
+  /** When true, this tab is currently playing the disintegrate animation. */
+  dissolving?: boolean;
   onActivate: () => void;
   onClose: () => void;
   onMouseEnter?: (e: React.MouseEvent<HTMLDivElement>) => void;
@@ -32,6 +35,7 @@ export function SortableTab({
   session,
   isActive,
   isSplit = false,
+  dissolving = false,
   onActivate,
   onClose,
   onMouseEnter,
@@ -65,6 +69,9 @@ export function SortableTab({
     transform: CSS.Transform.toString(transform),
     transition,
     opacity: isDragging ? 0.5 : 1,
+    // Snappier host fade for tabs (280 ms) — matches the 'tab' variant
+    // in useDissolveDelete. Cards (Hub) keep the default 600 ms.
+    ...(dissolving ? { ['--termbeam-fragment-ms' as string]: '280ms' } : null),
   };
 
   const activity = formatTabActivity(session.lastActivity);
@@ -73,9 +80,10 @@ export function SortableTab({
     <div
       ref={setNodeRef}
       style={style}
-      className={`${styles.tab} ${isActive ? styles.tabActive : ''} ${isSplit ? styles.tabSplit : ''} ${flash ? styles.tabFlash : ''}`}
+      className={`${styles.tab} ${isActive ? styles.tabActive : ''} ${isSplit ? styles.tabSplit : ''} ${flash ? styles.tabFlash : ''} ${dissolving ? dissolveStyles.dissolving : ''}`}
       data-testid="session-tab"
       {...(isActive ? { 'data-active': 'true' } : {})}
+      aria-hidden={dissolving || undefined}
       {...attributes}
       {...listeners}
       onPointerDown={(e) => {