Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(onboarding): add a shortcuts step to the setup tour

reviewaf2b2f5f4a75
diff --git a/src/renderer/components/onboarding/OnboardingFlow.tsx b/src/renderer/components/onboarding/OnboardingFlow.tsx
index 2934b2a46..704ab31da 100644
--- a/src/renderer/components/onboarding/OnboardingFlow.tsx
+++ b/src/renderer/components/onboarding/OnboardingFlow.tsx
@@ -26,8 +26,10 @@ import {
SceneKeepAwake,
SceneNotch,
SceneNotify,
- ScenePhone
+ ScenePhone,
+ SceneShortcuts
} from './scenes'
+import type { CommandId } from '@shared/keybindings'
const isMac = /Mac/i.test(navigator.platform || navigator.userAgent)
@@ -54,17 +56,20 @@ const STEPS = [
'notify',
'keepawake',
...(isMac ? (['notch'] as const) : []),
+ 'shortcuts',
'phone'
] as const
type StepId = (typeof STEPS)[number]
const STEP_COUNT = STEPS.length
/**
- * First-run setup tour: welcome → agents → dictation → kanban → notifications. Each step
- * pairs an animated scene with ONE decision, and every choice writes settings immediately
- * (there is no final "save" — closing mid-way keeps what was chosen so far). Replaces both
- * the auto-opened ShortcutsPanel and the standalone notification-consent dialog on first
- * launch; rerunnable via the ⌘K "Setup tour" command.
+ * First-run setup tour: welcome → agents → dictation → kanban → notifications → keep-awake →
+ * (notch) → shortcuts → phone. Each step pairs an animated scene with ONE decision, and every
+ * choice writes settings immediately (there is no final "save" — closing mid-way keeps what was
+ * chosen so far). Replaces both the auto-opened ShortcutsPanel and the standalone
+ * notification-consent dialog on first launch — which is why it owes the user its own
+ * shortcuts step: before it, a fresh install never heard of ⌘K or ⌘/ at all. Rerunnable via the
+ * ⌘K "Setup tour" command.
*/
export function OnboardingFlow({ onClose }: { onClose: () => void }) {
const settings = useSettings((s) => s.settings)
@@ -143,6 +148,25 @@ export function OnboardingFlow({ onClose }: { onClose: () => void }) {
return () => window.removeEventListener('keydown', onKey, true)
}, [step])
+ // ---- shortcuts try-it: the command palette chord, caught the same way as the kanban one
+ // (capture phase, registry-matched, so a remap is what counts and the real palette never
+ // opens under the tour). ----
+ const [paletteTried, setPaletteTried] = useState(false)
+ const [palettePulse, setPalettePulse] = useState(0)
+ useEffect(() => {
+ if (STEPS[step] !== 'shortcuts') return
+ const onKey = (e: KeyboardEvent) => {
+ if (effectiveBindings('app.commandPalette').some((s) => matchesShortcut(e, s, isMac))) {
+ e.preventDefault()
+ e.stopPropagation()
+ setPaletteTried(true)
+ setPalettePulse((n) => n + 1)
+ }
+ }
+ window.addEventListener('keydown', onKey, true)
+ return () => window.removeEventListener('keydown', onKey, true)
+ }, [step])
+
// Esc skips the tour (settings chosen so far are already saved).
useEffect(() => {
const onKey = (e: KeyboardEvent) => {
@@ -184,6 +208,22 @@ export function OnboardingFlow({ onClose }: { onClose: () => void }) {
// are live. `''` / `[]` mean the command is unbound — each site below says what it does then.
const newAgentChip = chipFor('node.newAgent')
const kanbanKeys = commandKeys('view.kanbanToggle')
+ const paletteKeys = commandKeys('app.commandPalette')
+ const panelKeys = commandKeys('app.shortcutsPanel')
+ // The handful worth learning on day one, each with its EFFECTIVE chord. A command the user
+ // unbound has no key to teach, so its row is dropped rather than shown chordless.
+ const essentials = (
+ [
+ ['app.commandPalette', 'Find any command, node or file'],
+ ['node.newAgent', `New ${agent.label}`],
+ ['node.newTerminal', 'New terminal'],
+ ['canvas.fitAll', 'See the whole canvas'],
+ ['node.maximize', 'Maximize / restore a node'],
+ ['view.kanbanToggle', 'Canvas ⇄ kanban']
+ ] as const satisfies ReadonlyArray<readonly [CommandId, string]>
+ )
+ .map(([id, label]) => ({ id, label, keys: commandKeys(id) }))
+ .filter((r) => r.keys.length > 0)
const stepId: StepId = STEPS[step] ?? 'cover'
const next = () => setStep((s) => Math.min(s + 1, STEP_COUNT - 1))
@@ -245,6 +285,7 @@ export function OnboardingFlow({ onClose }: { onClose: () => void }) {
<SceneKeepAwake agentId={agentId} label={agent.label} color={agent.color} />
)}
{stepId === 'notch' && <SceneNotch />}
+ {stepId === 'shortcuts' && <SceneShortcuts keys={paletteKeys} query={`new ${agent.label.toLowerCase()}`} pulseKey={palettePulse} />}
{stepId === 'phone' && <ScenePhone />}
</div>
<div className="onb-pane">
@@ -460,6 +501,63 @@ export function OnboardingFlow({ onClose }: { onClose: () => void }) {
</>
)}
+ {stepId === 'shortcuts' && (
+ <>
+ <h2>A few keys worth knowing</h2>
+ <p>
+ Everything in nodeterm has a keyboard shortcut — and every one of them can be
+ remapped.
+ </p>
+ <div className="onb-keys">
+ {essentials.map((r) => (
+ <div key={r.id} className="onb-keys__row">
+ <span>{r.label}</span>
+ <span className="onb-keys__chord">
+ {r.keys.map((k, i) => (
+ <kbd key={i} className="kbd">
+ {k}
+ </kbd>
+ ))}
+ </span>
+ </div>
+ ))}
+ </div>
+ {/* Same contract as the kanban try-it: no prompt when the palette is unbound. */}
+ {(paletteKeys.length > 0 || paletteTried) && (
+ <div className={`onb-tryit ${paletteTried ? 'is-done' : ''}`}>
+ {paletteTried ? (
+ <>
+ <OnbCheck /> That's the command palette — the one key to remember.
+ </>
+ ) : (
+ <>
+ Try it now — press{' '}
+ {paletteKeys.map((k, i) => (
+ <kbd key={i} className="kbd">
+ {k}
+ </kbd>
+ ))}
+ </>
+ )}
+ </div>
+ )}
+ <div className="onb-fineprint">
+ {panelKeys.length > 0 ? (
+ <>
+ The full list is one{' '}
+ {panelKeys.map((k, i) => (
+ <kbd key={i} className="kbd">
+ {k}
+ </kbd>
+ ))}{' '}
+ away.{' '}
+ </>
+ ) : null}
+ Remap anything in Settings → Keyboard Shortcuts.
+ </div>
+ </>
+ )}
+
{stepId === 'phone' && (
<>
<h2>Your sessions, in your pocket</h2>
diff --git a/src/renderer/components/onboarding/scenes.tsx b/src/renderer/components/onboarding/scenes.tsx
index d40a5d511..a329b0308 100644
--- a/src/renderer/components/onboarding/scenes.tsx
+++ b/src/renderer/components/onboarding/scenes.tsx
@@ -346,6 +346,44 @@ export function SceneKeepAwake({ agentId, label, color }: { agentId: AgentId; la
)
}
+/** Shortcuts: the palette chord goes down and a command palette drops open under it, a query
+ * typing into it. The palette is the step's one key to remember, so it is the one acted out;
+ * the user's own press of that chord (`pulseKey`) replays the drop. */
+export function SceneShortcuts({ keys, query, pulseKey }: { keys: string[]; query: string; pulseKey?: number }) {
+ return (
+ <div className="onb-scene-canvas onb-scene--dictation" aria-hidden="true">
+ {keys.length > 0 && (
+ <div className="onb-kbd-row">
+ {keys.map((k, i) => (
+ <kbd key={i} className="onb-kbd" style={{ animationDelay: `${i * 0.1}s` }}>
+ {k}
+ </kbd>
+ ))}
+ </div>
+ )}
+ {/* keyed on the pulse so a real press restarts the drop animation */}
+ <div key={pulseKey ?? 0} className="onb-palette">
+ <div className="onb-palette__input">
+ <span className="onb-term-typed">{query}</span>
+ <span className="onb-caret" />
+ </div>
+ <div className="onb-palette__row is-hl">
+ <span className="onb-mini__dot" style={{ background: '#d97757' }} />
+ <span className="onb-mini__bar" />
+ </div>
+ <div className="onb-palette__row">
+ <span className="onb-mini__dot" />
+ <span className="onb-mini__bar onb-mini__bar--short" />
+ </div>
+ <div className="onb-palette__row">
+ <span className="onb-mini__dot" />
+ <span className="onb-mini__bar" />
+ </div>
+ </div>
+ </div>
+ )
+}
+
/** The mobile companion as a floating phone mockup: live session rows with real status
* badges + a terminal line — live on the App Store (the step links to it). */
export function ScenePhone() {
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index babcf9444..8cf0b315d 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -12317,6 +12317,72 @@ button.group-node__setup:disabled {
50% { transform: rotate(8deg) scale(1.07); }
}
+/* -- shortcuts scene: the palette chord goes down (~5%), the palette drops open under it and the
+ query types in on the shared 8s timeline (onb-type) -- */
+.onb-palette {
+ width: 250px;
+ padding: 8px;
+ border-radius: 12px;
+ background: var(--surface-deep);
+ border: 1px solid var(--border);
+ box-shadow: 0 18px 40px rgba(0, 0, 0, 0.45);
+ display: flex;
+ flex-direction: column;
+ gap: 4px;
+ animation: onb-palette-drop 8s ease infinite;
+ animation-play-state: var(--nt-anim-state);
+}
+.onb-palette__input {
+ display: flex;
+ align-items: center;
+ height: 28px;
+ padding: 0 8px;
+ margin-bottom: 4px;
+ border-radius: 7px;
+ background: rgba(var(--tint-rgb), 0.06);
+ font-size: 12.5px;
+}
+.onb-palette__row {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ height: 24px;
+ padding: 0 8px;
+ border-radius: 6px;
+}
+.onb-palette__row .onb-mini__bar {
+ flex: 1;
+}
+.onb-palette__row.is-hl {
+ background: color-mix(in srgb, var(--accent) 28%, transparent);
+}
+@keyframes onb-palette-drop {
+ 0%, 6% { opacity: 0; transform: translateY(-8px) scale(0.97); }
+ 12%, 94% { opacity: 1; transform: none; }
+ 100% { opacity: 0; transform: none; }
+}
+
+/* ---- shortcuts step: the essentials list ---- */
+.onb-keys {
+ display: flex;
+ flex-direction: column;
+ gap: 6px;
+ margin-bottom: 14px;
+}
+.onb-keys__row {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 12px;
+ font-size: 13px;
+ color: rgba(235, 235, 245, 0.8);
+}
+.onb-keys__chord {
+ display: inline-flex;
+ gap: 3px;
+ flex-shrink: 0;
+}
+
/* ---- reduced motion: freeze every scene to a readable final frame ---- */
@media (prefers-reduced-motion: reduce) {
.onb-ghost,
@@ -12328,7 +12394,8 @@ button.group-node__setup:disabled {
.onb-wave span,
.onb-caret,
.onb-bell,
- .onb-notif {
+ .onb-notif,
+ .onb-palette {
animation: none;
}
.onb-menu {