feat(ui): configurable splash + mobile tips on empty SessionsHub

Adds a 'Splash screen' toggle under Settings → Notifications & Feedback
(default ON). When OFF the brand-animation min-duration gate is bypassed
on cold load so the app shell paints immediately.

When SessionsHub has zero sessions, a curated random Tip card now
appears below the empty-state copy. Tips are aimed at mobile users:
TouchBar customization, voice mic, pinch-to-zoom, sharing the tunnel
URL, PWA install, workspaces, resume agents, kbd shortcuts, etc. A
single tip is pinned per hub mount and a fresh one is picked on next
visit.

Schema additions: showSplash boolean on both client (preferencesStore)
and server (preferences.js sanitize). Defaults to true.

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

Author: dorlugasigal

packages/site/src/content/docs/customization.md

@@ -27,13 +27,13 @@ The **Theme picker** is rendered inline inside the **VIEW** section — tap the
 
 Reach **Settings** from the Tools panel → **Settings…** (or via <kbd>Cmd+,</kbd> / <kbd>Ctrl+,</kbd>). The panel is non-blocking so theme, font and haptics changes are visible against the terminal as you make them.
 
-| Section                      | What it controls                                                                                                                   |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| **Appearance**               | Theme picker (live preview cards) and font-size slider.                                                                            |
-| **Notifications & Feedback** | Browser notifications when a backgrounded command completes, and haptic feedback on TouchBar key presses.                          |
-| **Touch Bar**                | Toggle "Start collapsed by default" and open the **Customize keys** editor.                                                        |
-| **New Session Defaults**     | Default folder and default initial command pre-fills used by **+ New session** and by workspace sessions when they don't override. |
-| **Workspaces**               | List of named workspaces. Mark one as the default startup workspace, edit per-workspace sessions, drag to reorder.                 |
+| Section                      | What it controls                                                                                                                                                            |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Appearance**               | Theme picker (live preview cards) and font-size slider.                                                                                                                     |
+| **Notifications & Feedback** | Browser notifications when a backgrounded command completes, haptic feedback on TouchBar key presses, and a **Splash screen** toggle to skip the cold-load brand animation. |
+| **Touch Bar**                | Toggle "Start collapsed by default" and open the **Customize keys** editor.                                                                                                 |
+| **New Session Defaults**     | Default folder and default initial command pre-fills used by **+ New session** and by workspace sessions when they don't override.                                          |
+| **Workspaces**               | List of named workspaces. Mark one as the default startup workspace, edit per-workspace sessions, drag to reorder.                                                          |
 
 All of the above is persisted to `~/.termbeam/prefs.json` (mode `0o600`) on the server. The browser keeps a `localStorage` cache (`termbeam-prefs`) for instant first paint and offline UX, but the server file is the source of truth.
 
@@ -115,6 +115,7 @@ The schema is roughly:
   "fontSize": 13,
   "notifications": false,
   "haptics": true,
+  "showSplash": true,
   "defaultFolder": "",
   "defaultInitialCommand": "",
   "touchBarCollapsed": true,

src/frontend/src/App.tsx

@@ -53,15 +53,21 @@ function useChromeColor(screen: 'terminal' | 'main') {
 export default function App() {
   const { authenticated, passwordRequired, login, loading } = useAuth();
   const [path, setPath] = useState(getPath);
+  const showSplash = usePreferencesStore((s) => s.prefs.showSplash);
 
   /*
    * Hold the splash screen for at least 1500ms on cold load so the
    * per-letter Keynote-bloom animation (last letter starts at 0.55s,
    * 0.85s duration = 1.40s end) plays through with a 100ms beat to read
    * the settled wordmark. Without this gate, auth on localhost resolves
    * in ~50ms and the user never sees the animation.
+   *
+   * When the user has opted out via Settings → Startup → "Show splash
+   * screen", `splashHoldMs` collapses to 0 so we skip straight through
+   * to the app shell.
    */
-  const splashElapsed = useMinDuration(1500);
+  const splashHoldMs = showSplash ? 1500 : 0;
+  const splashElapsed = useMinDuration(splashHoldMs);
 
   // Hydrate user preferences from the server once we're authenticated. The
   // store seeds itself synchronously from localStorage on import so the first

src/frontend/src/components/SessionsHub/SessionsHub.module.css

@@ -138,6 +138,69 @@
   color: var(--text-primary);
 }
 
+/* ──────────────────────────────────────────────────────────────────
+   Empty-state Tip Card
+   Shown only when there are zero sessions. Designed to feel like a
+   helpful aside, not a banner — reads well on a phone in portrait.
+   ────────────────────────────────────────────────────────────────── */
+
+.tipCard {
+  position: relative;
+  display: grid;
+  grid-template-columns: auto 1fr;
+  align-items: start;
+  gap: 12px;
+  margin-top: 1.5rem;
+  padding: 14px 16px;
+  max-width: 340px;
+  width: 100%;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  text-align: left;
+  box-shadow: 0 1px 0 0 rgba(255, 255, 255, 0.02) inset;
+}
+
+.tipBadge {
+  position: absolute;
+  top: -9px;
+  left: 14px;
+  padding: 1px 8px;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  background: var(--bg);
+  color: var(--accent, var(--text-dim));
+  border: 1px solid var(--border);
+  border-radius: 999px;
+}
+
+.tipIcon {
+  font-size: 22px;
+  line-height: 1;
+  margin-top: 2px;
+}
+
+.tipBody {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+}
+
+.tipTitle {
+  font-size: 0.9rem;
+  font-weight: 600;
+  color: var(--text);
+}
+
+.tipText {
+  font-size: 0.82rem;
+  line-height: 1.4;
+  color: var(--text-dim);
+}
+
 .hubFooter {
   position: fixed;
   bottom: var(--safe-bottom);

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

@@ -12,6 +12,7 @@ import NewSessionModal from './NewSessionModal';
 import ResumeBrowser from '@/components/ResumeBrowser/ResumeBrowser';
 import WorkspaceLauncher from '@/components/WorkspaceLauncher/WorkspaceLauncher';
 import FilterBar from './FilterBar';
+import { pickRandomTip } from './tips';
 import {
   EMPTY_FILTER,
   deriveFacets,
@@ -125,6 +126,11 @@ export default function SessionsHub() {
   );
   const filterActive = !isEmptyFilter(filter);
 
+  // Pin one tip for the lifetime of this hub mount so it doesn't shuffle
+  // while the user is looking at the empty state. A fresh tip is picked
+  // on the next visit / refresh.
+  const tip = useMemo(() => pickRandomTip(), []);
+
   function navigateToSession(id: string) {
     window.history.pushState(null, '', `/terminal?session=${id}`);
     window.dispatchEvent(new PopStateEvent('popstate'));
@@ -235,6 +241,17 @@ export default function SessionsHub() {
             <span className={styles.emptyHint}>
               Tap &quot;+ New Session&quot; to create a new terminal session
             </span>
+
+            <div className={styles.tipCard} data-testid="hub-tip">
+              <span className={styles.tipBadge}>Tip</span>
+              <span className={styles.tipIcon} aria-hidden="true">
+                {tip.icon}
+              </span>
+              <div className={styles.tipBody}>
+                <strong className={styles.tipTitle}>{tip.title}</strong>
+                <span className={styles.tipText}>{tip.body}</span>
+              </div>
+            </div>
           </div>
         ) : (
           <>

src/frontend/src/components/SessionsHub/__tests__/tips.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from 'vitest';
+import { HUB_TIPS, pickRandomTip } from '../tips';
+
+describe('HUB_TIPS', () => {
+  it('has at least 8 curated tips', () => {
+    expect(HUB_TIPS.length).toBeGreaterThanOrEqual(8);
+  });
+
+  it('every tip has icon, title, and body', () => {
+    for (const tip of HUB_TIPS) {
+      expect(tip.icon).toBeTruthy();
+      expect(tip.title).toBeTruthy();
+      expect(tip.body).toBeTruthy();
+      expect(tip.body.length).toBeLessThanOrEqual(200);
+    }
+  });
+
+  it('tips have unique titles (no duplicates)', () => {
+    const titles = HUB_TIPS.map((t) => t.title);
+    expect(new Set(titles).size).toBe(titles.length);
+  });
+});
+
+describe('pickRandomTip', () => {
+  it('returns a deterministic tip when given a seed', () => {
+    expect(pickRandomTip(0)).toBe(HUB_TIPS[0]);
+    // 0.9999 * length floors to length-1
+    expect(pickRandomTip(0.9999)).toBe(HUB_TIPS[HUB_TIPS.length - 1]);
+  });
+
+  it('always returns a valid tip object', () => {
+    for (let seed = 0; seed < 1; seed += 0.05) {
+      const tip = pickRandomTip(seed);
+      expect(HUB_TIPS).toContain(tip);
+    }
+  });
+
+  it('without a seed returns one of the curated tips', () => {
+    expect(HUB_TIPS).toContain(pickRandomTip());
+  });
+});

src/frontend/src/components/SessionsHub/tips.ts

@@ -0,0 +1,91 @@
+/**
+ * Mobile-first tips shown in the SessionsHub when the user has zero
+ * sessions. Curated list — every tip points at a feature that actually
+ * exists today and is meaningful for someone driving TermBeam from a
+ * phone or tablet on the go.
+ *
+ * Add new tips to the end of the array. Tips with leading icons are
+ * fine; keep the body short enough to read in one breath.
+ */
+export interface Tip {
+  /** 1-3 character emoji or symbol shown to the left. */
+  icon: string;
+  /** Short headline (≤ 40 chars works best on a phone). */
+  title: string;
+  /** Body. One sentence. No trailing period required. */
+  body: string;
+}
+
+export const HUB_TIPS: Tip[] = [
+  {
+    icon: '⌨️',
+    title: 'TouchBar is your secret weapon',
+    body: 'Esc, Tab, Ctrl, arrows — all live one tap away on the bar above the keyboard',
+  },
+  {
+    icon: '🎤',
+    title: 'Talk to your terminal',
+    body: 'Drop a Mic key into the TouchBar to dictate commands hands-free',
+  },
+  {
+    icon: '🤏',
+    title: 'Pinch to resize',
+    body: 'Two-finger pinch on the terminal scales the font — and we remember the size',
+  },
+  {
+    icon: '↕️',
+    title: 'Stack more keys',
+    body: 'Drag the TouchBar handle upward to add up to 3 rows for vim, tmux, or your own combos',
+  },
+  {
+    icon: '⚙️',
+    title: 'Customize every key',
+    body: 'Open Tools (▦) → Settings → Touch Bar → Customize to set what each key types',
+  },
+  {
+    icon: '🔗',
+    title: 'Beam this terminal anywhere',
+    body: 'Hit the share button to copy a URL — open it on any device with the password',
+  },
+  {
+    icon: '📱',
+    title: 'Add to Home Screen',
+    body: 'Install TermBeam as a PWA from your browser for full-screen, app-like access',
+  },
+  {
+    icon: '🗂️',
+    title: 'Save a workspace',
+    body: 'Group your favorite sessions into a workspace from Tools → Save Workspace, then re-launch with one tap',
+  },
+  {
+    icon: '↺',
+    title: 'Pick up where you left off',
+    body: 'Resume Agent reattaches to running Claude Code, Codex, or other agent sessions with full history',
+  },
+  {
+    icon: '⌘K',
+    title: 'Keyboard-shortcut everything',
+    body: 'Cmd/Ctrl+K opens the Tools panel, Cmd/Ctrl+, opens Settings — handy with a Bluetooth keyboard',
+  },
+  {
+    icon: '⏯',
+    title: 'Hold an arrow to repeat',
+    body: 'Long-press the arrow keys on the TouchBar for fast cursor movement, just like a real keyboard',
+  },
+  {
+    icon: '🛰️',
+    title: 'Cellular access on the go',
+    body: 'A persistent dev tunnel lets you reach this terminal from your phone over LTE, no VPN needed',
+  },
+];
+
+/**
+ * Returns a tip chosen at random from {@link HUB_TIPS}. The optional
+ * `seed` lets tests pin a deterministic pick. In production we generate
+ * a fresh seed once per render so the tip stays stable while the user
+ * looks at it but rotates on the next visit.
+ */
+export function pickRandomTip(seed: number = Math.random()): Tip {
+  const idx = Math.floor(seed * HUB_TIPS.length) % HUB_TIPS.length;
+  return HUB_TIPS[idx]!;
+}

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

@@ -424,6 +424,20 @@ export default function SettingsPanel() {
                 onChange={(v) => setPreference('haptics', v)}
               />
             </div>
+
+            <div className={styles.row}>
+              <span className={styles.rowLabel}>
+                Splash screen
+                <span className={styles.rowHint}>
+                  Show the brand animation on cold load. Turn off to jump straight to the app.
+                </span>
+              </span>
+              <Toggle
+                on={prefs.showSplash}
+                ariaLabel="Toggle splash screen"
+                onChange={(v) => setPreference('showSplash', v)}
+              />
+            </div>
           </section>
 
           {/* ── Touch Bar ─────────────────────────────────────────── */}

src/frontend/src/stores/__tests__/preferencesStore.test.ts

@@ -72,4 +72,18 @@ describe('usePreferencesStore', () => {
     expect(raw).toBeTruthy();
     expect(JSON.parse(raw!).fontSize).toBe(18);
   });
+
+  it('seeds showSplash to true by default', () => {
+    const { prefs } = usePreferencesStore.getState();
+    expect(prefs.showSplash).toBe(true);
+    expect(PREF_DEFAULTS.showSplash).toBe(true);
+  });
+
+  it('round-trips showSplash through setPreference', () => {
+    const { setPreference } = usePreferencesStore.getState();
+    setPreference('showSplash', false);
+    expect(usePreferencesStore.getState().prefs.showSplash).toBe(false);
+    setPreference('showSplash', true);
+    expect(usePreferencesStore.getState().prefs.showSplash).toBe(true);
+  });
 });

src/frontend/src/stores/preferencesStore.ts

@@ -138,6 +138,9 @@ export interface Preferences {
   fontSize: number;
   notifications: boolean;
   haptics: boolean;
+  /** When false, the brand splash animation is skipped on cold load and the
+   *  user goes straight to the app shell. Default: true. */
+  showSplash: boolean;
   defaultFolder: string;
   defaultInitialCommand: string;
   touchBarCollapsed: boolean;
@@ -159,6 +162,7 @@ export const PREF_DEFAULTS: Preferences = Object.freeze({
   // the Notifications toggle doesn't flip on first hydrate.
   notifications: false,
   haptics: true,
+  showSplash: true,
   defaultFolder: '',
   defaultInitialCommand: '',
   touchBarCollapsed: false,
@@ -197,6 +201,7 @@ function normalize(input: unknown): Preferences {
     fontSize: clampFont(typeof p.fontSize === 'number' ? p.fontSize : PREF_DEFAULTS.fontSize),
     notifications: typeof p.notifications === 'boolean' ? p.notifications : PREF_DEFAULTS.notifications,
     haptics: typeof p.haptics === 'boolean' ? p.haptics : PREF_DEFAULTS.haptics,
+    showSplash: typeof p.showSplash === 'boolean' ? p.showSplash : PREF_DEFAULTS.showSplash,
     defaultFolder: typeof p.defaultFolder === 'string' ? p.defaultFolder : '',
     defaultInitialCommand:
       typeof p.defaultInitialCommand === 'string' ? p.defaultInitialCommand : '',

src/server/preferences.js

@@ -16,6 +16,7 @@ const DEFAULTS = Object.freeze({
   fontSize: 14,
   notifications: false,
   haptics: true,
+  showSplash: true,
   defaultFolder: '',
   defaultInitialCommand: '',
   touchBarCollapsed: false,
@@ -188,6 +189,7 @@ function sanitize(prefs) {
     fontSize: clampNumber(src.fontSize, FONT_MIN, FONT_MAX, DEFAULTS.fontSize),
     notifications: asBool(src.notifications, DEFAULTS.notifications),
     haptics: asBool(src.haptics, DEFAULTS.haptics),
+    showSplash: asBool(src.showSplash, DEFAULTS.showSplash),
     defaultFolder: asString(src.defaultFolder, DEFAULTS.defaultFolder, 1024),
     defaultInitialCommand: asString(
       src.defaultInitialCommand,