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(update-card): quiet background downloads, restart feedback, Later, release highlights

review238354a16c88
diff --git a/src/renderer/components/UpdateCard.flow.test.tsx b/src/renderer/components/UpdateCard.flow.test.tsx
new file mode 100644
index 000000000..2a25f415f
--- /dev/null
+++ b/src/renderer/components/UpdateCard.flow.test.tsx
@@ -0,0 +1,229 @@
+// @vitest-environment jsdom
+// The update card's wiring: quiet automatic downloads, user-initiated progress, the ready card's
+// install-on-quit copy + Later, the restart feedback, and the periodic policy re-read. The state
+// rules themselves are pinned in lib/updateCardState.test.ts.
+import { act } from 'react'
+import { createRoot } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { UpdateCard, POLICY_REFRESH_MS, POLICY_RETRY_MS } from './UpdateCard'
+import { usePendingUpdate } from '../state/pendingUpdate'
+import { LAST_SEEN_VERSION_KEY } from '../lib/releaseNotes'
+import type { UpdatePolicy } from '@shared/types'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+type Fire = (...a: unknown[]) => void
+const fire: Record<string, Fire> = {}
+const sub = (name: string) => (listener: Fire) => {
+ fire[name] = listener
+ return () => delete fire[name]
+}
+
+let container: HTMLDivElement
+let root: ReturnType<typeof createRoot>
+let policies: Array<UpdatePolicy | Error>
+let version: string
+const restart = vi.fn()
+const check = vi.fn()
+
+function mount(): void {
+ container = document.createElement('div')
+ document.body.appendChild(container)
+ act(() => {
+ root = createRoot(container)
+ root.render(<UpdateCard />)
+ })
+}
+
+beforeEach(() => {
+ vi.useFakeTimers()
+ for (const k of Object.keys(fire)) delete fire[k]
+ restart.mockClear()
+ check.mockClear()
+ policies = []
+ version = '0.5.0'
+ usePendingUpdate.setState({ pending: null })
+ try {
+ window.localStorage.clear()
+ } catch {
+ /* no storage */
+ }
+ ;(window as unknown as { nodeTerminal: unknown }).nodeTerminal = {
+ updates: {
+ onAvailable: sub('available'),
+ onDownloaded: sub('downloaded'),
+ onProgress: sub('progress'),
+ onError: sub('error'),
+ onNotAvailable: sub('notAvailable'),
+ onNoChannel: sub('noChannel'),
+ onInstalling: sub('installing'),
+ getVersion: () => Promise.resolve(version),
+ getPolicy: vi.fn(() => {
+ const next = policies.shift() ?? { minSupported: null, mandatory: false }
+ return next instanceof Error ? Promise.reject(next) : Promise.resolve(next)
+ }),
+ check,
+ restart,
+ prepareInspect: () => Promise.resolve({ kind: 'unsupported' }),
+ prepareShutdownHost: () => Promise.resolve({ kind: 'unsupported' }),
+ prepareQuit: () => {}
+ }
+ }
+})
+
+afterEach(() => {
+ act(() => root.unmount())
+ container.remove()
+ vi.useRealTimers()
+})
+
+const text = (): string => container.textContent ?? ''
+const button = (label: string): HTMLButtonElement | undefined =>
+ [...container.querySelectorAll('button')].find((b) => b.textContent?.trim() === label)
+const flush = async (): Promise<void> => {
+ await act(async () => {
+ for (let i = 0; i < 5; i++) await Promise.resolve()
+ })
+}
+
+describe('automatic downloads are quiet', () => {
+ beforeEach(mount)
+
+ it('an automatic available renders nothing — no card, no pill', () => {
+ act(() => fire.available({ version: '0.6.0', notes: '', manual: false }))
+ act(() => fire.progress({ percent: 40 }))
+ expect(text()).toBe('')
+ })
+
+ it('the finished download opens the ready card and fills the title-bar button', () => {
+ act(() => fire.available({ version: '0.6.0', notes: '', manual: false }))
+ act(() => fire.downloaded({ version: '0.6.0' }))
+ expect(text()).toContain('Update ready')
+ expect(usePendingUpdate.getState().pending).toEqual({ kind: 'downloaded', version: '0.6.0' })
+ })
+
+ it('a user check shows progress, and that card can be closed', () => {
+ act(() => window.dispatchEvent(new CustomEvent('nodeterm:update-checking')))
+ act(() => fire.available({ version: '0.6.0', notes: '', manual: false }))
+ act(() => fire.progress({ percent: 25 }))
+ expect(text()).toContain('Downloading… 25%')
+ act(() => container.querySelector<HTMLButtonElement>('button[aria-label="Dismiss"]')!.click())
+ expect(text()).toBe('')
+ act(() => fire.downloaded({ version: '0.6.0' }))
+ expect(text()).toContain('Update ready')
+ })
+
+ it('a manual-delivery payload (check-only build) still opens its card', () => {
+ act(() => fire.available({ version: '0.6.0', notes: '', manual: true }))
+ expect(text()).toContain('nodeterm v0.6.0 is available. Download it to update.')
+ })
+
+ it('an automatic "up to date" says nothing', () => {
+ act(() => fire.notAvailable())
+ expect(text()).toBe('')
+ })
+})
+
+describe('the ready card', () => {
+ beforeEach(() => {
+ mount()
+ act(() => fire.downloaded({ version: '0.6.0', notes: '- Faster canvas\n- Fewer prompts' }))
+ })
+
+ it('says it installs on quit, shows highlights, and offers Later', () => {
+ expect(text()).toContain('It installs automatically the next time you quit.')
+ expect(text()).toContain('Faster canvas')
+ expect(text()).toContain('Fewer prompts')
+ act(() => button('Later')!.click())
+ expect(text()).toContain('Ready')
+ expect(text()).not.toContain('Update ready')
+ expect(restart).not.toHaveBeenCalled()
+ })
+
+ it('Restart → a disabled Preparing… button, then Restarting… from main', () => {
+ act(() => button('Restart to update')!.click())
+ expect(restart).toHaveBeenCalledTimes(1)
+ expect(text()).toContain('Preparing update…')
+ const busy = container.querySelector<HTMLButtonElement>('button[disabled]')
+ expect(busy?.textContent).toContain('Preparing…')
+ act(() => fire.installing({ phase: 'restarting', version: '0.6.0' }))
+ expect(text()).toContain('Restarting nodeterm…')
+ expect(container.querySelector<HTMLButtonElement>('button[disabled]')?.textContent).toContain('Restarting…')
+ })
+
+ it('an install failure returns to the ready card with the reason', () => {
+ act(() => button('Restart to update')!.click())
+ act(() => fire.installing({ phase: 'preparing', version: '0.6.0' }))
+ act(() => fire.error('Code signature did not pass validation'))
+ expect(text()).toContain('Update ready')
+ expect(text()).toContain('Code signature did not pass validation')
+ expect(button('Restart to update')).toBeTruthy()
+ })
+
+ it('a repeat downloaded for the same version does not re-open a minimized card', () => {
+ act(() => button('Later')!.click())
+ act(() => fire.downloaded({ version: '0.6.0' }))
+ expect(text()).not.toContain('Update ready')
+ })
+})
+
+describe('the mandatory policy is re-read', () => {
+ it('retries once after an empty first read, then every six hours', async () => {
+ policies = [
+ { minSupported: null, mandatory: false },
+ { minSupported: '0.1.0', mandatory: false },
+ { minSupported: '0.9.0', mandatory: true }
+ ]
+ mount()
+ await flush()
+ const getPolicy = (window as unknown as { nodeTerminal: { updates: { getPolicy: ReturnType<typeof vi.fn> } } })
+ .nodeTerminal.updates.getPolicy
+ expect(getPolicy).toHaveBeenCalledTimes(1)
+ await act(async () => {
+ vi.advanceTimersByTime(POLICY_RETRY_MS)
+ })
+ await flush()
+ expect(getPolicy).toHaveBeenCalledTimes(2)
+ expect(text()).toBe('')
+ await act(async () => {
+ vi.advanceTimersByTime(POLICY_REFRESH_MS)
+ })
+ await flush()
+ expect(getPolicy).toHaveBeenCalledTimes(3)
+ expect(text()).toContain('Update required')
+ expect(text()).toContain('minimum 0.9.0')
+ })
+
+ it('a failed first read is retried too', async () => {
+ policies = [new Error('offline'), { minSupported: '0.9.0', mandatory: true }]
+ mount()
+ await flush()
+ expect(text()).toBe('')
+ await act(async () => {
+ vi.advanceTimersByTime(POLICY_RETRY_MS)
+ })
+ await flush()
+ expect(text()).toContain('Update required')
+ })
+})
+
+describe('updated to vX', () => {
+ it('announces the first launch of a newer version once', async () => {
+ window.localStorage.setItem(LAST_SEEN_VERSION_KEY, '0.4.3')
+ mount()
+ await flush()
+ expect(text()).toContain('Updated to v0.5.0')
+ act(() => root.unmount())
+ container.remove()
+ mount()
+ await flush()
+ expect(text()).not.toContain('Updated to')
+ })
+
+ it('stays silent on a fresh install', async () => {
+ mount()
+ await flush()
+ expect(text()).toBe('')
+ expect(window.localStorage.getItem(LAST_SEEN_VERSION_KEY)).toBe('0.5.0')
+ })
+})
diff --git a/src/renderer/components/UpdateCard.no-channel.test.tsx b/src/renderer/components/UpdateCard.no-channel.test.tsx
index 910f926f9..9ae3a3ffc 100644
--- a/src/renderer/components/UpdateCard.no-channel.test.tsx
+++ b/src/renderer/components/UpdateCard.no-channel.test.tsx
@@ -32,6 +32,8 @@ beforeEach(() => {
onError: sub('error'),
onNotAvailable: sub('notAvailable'),
onNoChannel: sub('noChannel'),
+ onInstalling: sub('installing'),
+ getVersion: () => Promise.reject(new Error('unsupported')),
getPolicy: () => Promise.resolve({ minSupported: null, mandatory: false }),
check: () => {},
restart: () => {},
@@ -100,7 +102,9 @@ describe('the no-channel card', () => {
})
describe('the states either side of it are unchanged', () => {
- it('"not available" still renders the up-to-date card', () => {
+ it('"not available" still renders the up-to-date card for a user check', () => {
+ // (An AUTOMATIC check's "not available" is silent — see UpdateCard.flow.test.tsx.)
+ act(() => window.dispatchEvent(new CustomEvent('nodeterm:update-checking')))
act(() => fire.notAvailable())
expect(text()).toContain("You're up to date")
expect(text()).toContain('nodeterm is on the latest version.')
diff --git a/src/renderer/components/UpdateCard.tsx b/src/renderer/components/UpdateCard.tsx
index 609cd9eff..d17e11223 100644
--- a/src/renderer/components/UpdateCard.tsx
+++ b/src/renderer/components/UpdateCard.tsx
@@ -1,31 +1,40 @@
-import { useEffect, useRef, useState } from 'react'
+import { useEffect, useReducer, useState } from 'react'
import { IconClose } from './icons'
import { noSelfInstallCopy } from '@shared/update-platform'
import type { UpdateProgress } from '@shared/types'
-import { RELEASES_URL, usePendingUpdate } from '../state/pendingUpdate'
+import { RELEASES_URL, checkForUpdatesNow, usePendingUpdate } from '../state/pendingUpdate'
+import {
+ INITIAL_CARD_STATE,
+ cardVisible,
+ nextCardState,
+ statusVersion,
+ type CardStatus
+} from '../lib/updateCardState'
+import { noteVersionSeen, releaseHighlights, releaseNotesUrl } from '../lib/releaseNotes'
-// The full updater lifecycle as one status union, driving a fixed bottom-right card.
-// `checking` is only ever shown for a user-initiated manual check; automatic checks stay
-// silent until they produce an `available` (or, for a manual check, `upToDate`/`error`).
-type Status =
- | { kind: 'idle' }
- | { kind: 'checking' }
- | { kind: 'available'; version: string; percent: number }
- // A .deb/.rpm Linux install can't self-install — show a manual download link, no progress/restart.
- | { kind: 'manual'; version: string }
- // This build has no update channel at all, so no version is known and none ever will be
- // (issue #814). Same mechanism as `manual` — one card, one download link — different sentence,
- // because "we cannot look" is not "we looked and you are current".
- | { kind: 'noChannel' }
- | { kind: 'downloaded'; version: string }
- | { kind: 'upToDate' }
- | { kind: 'required'; minSupported: string | null }
- | { kind: 'error'; message: string }
+// The updater lifecycle as one state machine (lib/updateCardState.ts — every transition rule and
+// why lives there), driving a fixed bottom-right card. The contract, in short: automatic checks are
+// SILENT until an update is downloaded (the card's single prompt — the title-bar button keeps the
+// install path once the card is closed); a user-initiated check shows progress and its answer; a
+// staged update is never downgraded or re-opened by a repeat; a restart click shows
+// Preparing…/Restarting… until the app goes away.
+
+/** Re-read the mandatory-update policy this often (main's /v1/check cache refreshes on the same
+ * cadence), and once sooner after an empty/failed first read (an offline launch). */
+export const POLICY_REFRESH_MS = 6 * 60 * 60 * 1000
+export const POLICY_RETRY_MS = 60 * 1000
+/** A restart click main never acknowledged gives the button back after this long. */
+const RESTART_ACK_MS = 10_000
+const UP_TO_DATE_MS = 4000
+const UPDATED_NOTE_MS = 15_000
export function UpdateCard(): JSX.Element | null {
- const [status, setStatus] = useState<Status>({ kind: 'idle' })
- const [minimized, setMinimized] = useState(false)
- const upToDateTimer = useRef<number | null>(null)
+ const [state, dispatch] = useReducer(nextCardState, INITIAL_CARD_STATE)
+ const status = state.status
+ // Highlights the /v1/check feed carries for one version (the update feed itself carries none
+ // today). Shown only on a card for that exact version.
+ const [feedNotes, setFeedNotes] = useState<{ version: string; notes: string } | null>(null)
+
// Windows session host (issue #829): the installer refuses to run while the host is up, so the
// card offers the in-app "Prepare for update" flow. Main answers `unsupported` everywhere else.
const [canPrepare, setCanPrepare] = useState(false)
@@ -43,87 +52,101 @@ export function UpdateCard(): JSX.Element | null {
}, [])
useEffect(() => {
- const offAvailable = window.nodeTerminal.updates.onAvailable((info) => {
- setStatus(
- info.manual
- ? { kind: 'manual', version: info.version }
- : { kind: 'available', version: info.version, percent: 0 }
- )
- setMinimized(false)
- })
- const offProgress = window.nodeTerminal.updates.onProgress((p: UpdateProgress) => {
- setStatus((s) => (s.kind === 'available' ? { ...s, percent: p.percent } : s))
- })
- const offDownloaded = window.nodeTerminal.updates.onDownloaded((info) => {
- setStatus({ kind: 'downloaded', version: info.version })
- setMinimized(false)
- })
- const offNotAvailable = window.nodeTerminal.updates.onNotAvailable(() => {
- setStatus((s) => (s.kind === 'required' ? s : { kind: 'upToDate' }))
- setMinimized(false)
- if (upToDateTimer.current) window.clearTimeout(upToDateTimer.current)
- upToDateTimer.current = window.setTimeout(
- () => setStatus((s) => (s.kind === 'required' ? s : { kind: 'idle' })),
- 4000
- )
- })
- const offNoChannel = window.nodeTerminal.updates.onNoChannel(() => {
- // Never auto-hides, unlike `upToDate`: this card carries the only action the user has.
- setStatus((s) => (s.kind === 'required' ? s : { kind: 'noChannel' }))
- setMinimized(false)
- })
- const offError = window.nodeTerminal.updates.onError((message) => {
- setStatus({ kind: 'error', message })
- setMinimized(false)
- })
- return () => {
- offAvailable()
- offProgress()
- offDownloaded()
- offNotAvailable()
- offNoChannel()
- offError()
- if (upToDateTimer.current) window.clearTimeout(upToDateTimer.current)
- }
+ const u = window.nodeTerminal.updates
+ const offs = [
+ u.onAvailable((info) =>
+ dispatch({ type: 'available', version: info.version, notes: info.notes, manual: !!info.manual })
+ ),
+ u.onProgress((p: UpdateProgress) => dispatch({ type: 'progress', percent: p.percent })),
+ u.onDownloaded((info) => dispatch({ type: 'downloaded', version: info.version, notes: info.notes })),
+ u.onNotAvailable(() => dispatch({ type: 'notAvailable' })),
+ u.onNoChannel(() => dispatch({ type: 'noChannel' })),
+ u.onError((message) => dispatch({ type: 'error', message })),
+ u.onInstalling((s) => dispatch({ type: 'installing', phase: s.phase, version: s.version }))
+ ]
+ return () => offs.forEach((off) => off())
}, [])
- // A manual check was triggered from Settings → show the checking state (unless an update
- // is already downloading or staged, which must not be overwritten).
+ // "You're up to date" is a toast, not a card that stays.
useEffect(() => {
- const onChecking = () => {
- setStatus((s) =>
- s.kind === 'available' ||
- s.kind === 'manual' ||
- s.kind === 'downloaded' ||
- s.kind === 'required'
- ? s
- : { kind: 'checking' }
- )
- setMinimized(false)
- }
+ if (status.kind !== 'upToDate') return
+ const t = window.setTimeout(() => dispatch({ type: 'upToDateExpired' }), UP_TO_DATE_MS)
+ return () => window.clearTimeout(t)
+ }, [status.kind])
+
+ useEffect(() => {
+ if (status.kind !== 'updated') return
+ const t = window.setTimeout(() => dispatch({ type: 'updatedExpired' }), UPDATED_NOTE_MS)
+ return () => window.clearTimeout(t)
+ }, [status.kind])
+
+ // A restart click main never acknowledged (it refused, or a stale card) must not leave a
+ // permanently disabled button.
+ useEffect(() => {
+ if (status.kind !== 'preparing' || state.installAck) return
+ const t = window.setTimeout(() => dispatch({ type: 'restartStalled' }), RESTART_ACK_MS)
+ return () => window.clearTimeout(t)
+ }, [status.kind, state.installAck])
+
+ // A user-initiated check (Settings, the required card, the title-bar button).
+ useEffect(() => {
+ const onChecking = (): void => dispatch({ type: 'checking' })
window.addEventListener('nodeterm:update-checking', onChecking)
return () => window.removeEventListener('nodeterm:update-checking', onChecking)
}, [])
- // Mandatory-update policy (from /v1/check via main). If the running version is below the
- // channel minimum, show a non-dismissible "required" card. Don't override an in-progress
- // download/ready state.
+ // Mandatory-update policy (from /v1/check via main). Re-read on a 6h cadence — a dock app runs
+ // for weeks, and a minimum raised meanwhile used to wait for a relaunch — with one quick retry
+ // when the first read failed or came back empty (an offline launch).
useEffect(() => {
- void window.nodeTerminal.updates.getPolicy().then((p) => {
- if (!p.mandatory) return
- setStatus((s) =>
- s.kind === 'available' || s.kind === 'manual' || s.kind === 'downloaded'
- ? s
- : { kind: 'required', minSupported: p.minSupported }
+ let live = true
+ let first = true
+ let timer: number | undefined
+ const schedule = (empty: boolean): void => {
+ timer = window.setTimeout(read, first && empty ? POLICY_RETRY_MS : POLICY_REFRESH_MS)
+ first = false
+ }
+ function read(): void {
+ window.nodeTerminal.updates.getPolicy().then(
+ (p) => {
+ if (!live) return
+ dispatch({ type: 'policy', policy: p })
+ if (p.notes && p.latestVersion) setFeedNotes({ version: p.latestVersion, notes: p.notes })
+ schedule(p.minSupported === null && !p.mandatory)
+ },
+ () => {
+ if (live) schedule(true)
+ }
)
- })
+ }
+ read()
+ return () => {
+ live = false
+ if (timer !== undefined) window.clearTimeout(timer)
+ }
+ }, [])
+
+ // First launch of a newer version: a one-time "Updated to vX". Silent on a fresh install; the
+ // Server Edition has no version to report (getVersion rejects) and so never shows it.
+ useEffect(() => {
+ let live = true
+ Promise.resolve()
+ .then(() => window.nodeTerminal.updates.getVersion())
+ .then((v) => {
+ if (live && typeof v === 'string' && noteVersionSeen(v, () => window.localStorage))
+ dispatch({ type: 'updated', version: v })
+ })
+ .catch(() => {})
+ return () => {
+ live = false
+ }
}, [])
// Dev-only: drive the card through its states from the console without packaging, e.g.
// __simulateUpdate({ kind: 'available', version: '0.3.0', percent: 42 })
useEffect(() => {
- ;(window as unknown as { __simulateUpdate?: (s: Status) => void }).__simulateUpdate = (s) =>
- setStatus(s)
+ ;(window as unknown as { __simulateUpdate?: (s: CardStatus) => void }).__simulateUpdate = (s) =>
+ dispatch({ type: 'simulate', status: s })
return () => {
delete (window as unknown as { __simulateUpdate?: unknown }).__simulateUpdate
}
@@ -133,16 +156,33 @@ export function UpdateCard(): JSX.Element | null {
// card's ✕ sets `idle`, and dismissing the card must not take the install path away with it.
const setPending = usePendingUpdate((s) => s.setPending)
useEffect(() => {
- if (status.kind === 'downloaded' || status.kind === 'manual') {
- setPending({ kind: status.kind, version: status.version })
+ if (status.kind === 'downloaded' || status.kind === 'preparing' || status.kind === 'restarting') {
+ setPending({ kind: 'downloaded', version: status.version })
+ } else if (status.kind === 'manual') {
+ setPending({ kind: 'manual', version: status.version })
} else if (status.kind === 'required') {
setPending({ kind: 'required', minSupported: status.minSupported })
}
}, [status, setPending])
- if (status.kind === 'idle') return null
+ if (!cardVisible(state)) return null
+ const version = statusVersion(status)
+ const notesUrl = releaseNotesUrl(version)
const openReleases = () => window.open(RELEASES_URL, '_blank', 'noopener')
+ const openNotes = () => window.open(notesUrl, '_blank', 'noopener')
+ const notes =
+ ('notes' in status && status.notes) ||
+ (feedNotes && version && feedNotes.version === version ? feedNotes.notes : undefined)
+ const highlights = releaseHighlights(notes)
+ const highlightList =
+ highlights.length > 0 ? (
+ <ul className="update-card__notes">
+ {highlights.map((h, i) => (
+ <li key={i}>{h}</li>
+ ))}
+ </ul>
+ ) : null
const prepareButton = canPrepare ? (
<button
className="update-card__link"
@@ -151,9 +191,14 @@ export function UpdateCard(): JSX.Element | null {
Prepare for update…
</button>
) : null
- const dismiss = () => setStatus({ kind: 'idle' })
+ const dismiss = () => dispatch({ type: 'dismiss' })
+ const minimize = () => dispatch({ type: 'minimize' })
+ const restartNow = () => {
+ dispatch({ type: 'restartClicked' })
+ window.nodeTerminal.updates.restart()
+ }
- if (minimized) {
+ if (state.minimized) {
const label =
status.kind === 'available'
? `${Math.round(status.percent)}%`
@@ -166,7 +211,7 @@ export function UpdateCard(): JSX.Element | null {
<button
className="update-card update-card--pill"
title="Show update"
- onClick={() => setMinimized(false)}
+ onClick={() => dispatch({ type: 'restore' })}
>
<span className="update-card__dot" />
{label}
@@ -183,28 +228,36 @@ export function UpdateCard(): JSX.Element | null {
? noSelfInstallCopy('manual-install', status.version).title
: status.kind === 'noChannel'
? noSelfInstallCopy('no-channel').title
- : status.kind === 'downloaded'
- ? 'Update ready'
- : status.kind === 'upToDate'
- ? "You're up to date"
- : status.kind === 'required'
- ? 'Update required'
- : 'Update failed'
+ : status.kind === 'downloaded'
+ ? 'Update ready'
+ : status.kind === 'preparing'
+ ? 'Preparing update…'
+ : status.kind === 'restarting'
+ ? 'Restarting nodeterm…'
+ : status.kind === 'upToDate'
+ ? "You're up to date"
+ : status.kind === 'required'
+ ? 'Update required'
+ : status.kind === 'updated'
+ ? `Updated to v${status.version}`
+ : 'Update failed'
const canMinimize = status.kind === 'available' || status.kind === 'downloaded'
const canDismiss =
+ status.kind === 'available' ||
status.kind === 'manual' ||
status.kind === 'noChannel' ||
status.kind === 'downloaded' ||
status.kind === 'upToDate' ||
- status.kind === 'error'
+ status.kind === 'error' ||
+ status.kind === 'updated'
return (
<div className="update-card">
<div className="update-card__head">
<span className="update-card__title">{title}</span>
{canMinimize && (
- <button className="update-card__icon" title="Minimize" onClick={() => setMinimized(true)}>
+ <button className="update-card__icon" title="Minimize" onClick={minimize}>
—
</button>
)}
@@ -222,7 +275,8 @@ export function UpdateCard(): JSX.Element | null {
{status.kind === 'available' && (
<>
<p className="update-card__body">nodeterm v{status.version} is downloading.</p>
- <button className="update-card__link" onClick={openReleases}>
+ {highlightList}
+ <button className="update-card__link" onClick={openNotes}>
Release notes
</button>
<div className="update-card__bar">
@@ -237,6 +291,7 @@ export function UpdateCard(): JSX.Element | null {
<p className="update-card__body">
{noSelfInstallCopy('manual-install', status.version).body}
</p>
+ {highlightList}
<button className="update-card__btn" onClick={openReleases}>
{noSelfInstallCopy('manual-install', status.version).action}
</button>
@@ -256,15 +311,36 @@ export function UpdateCard(): JSX.Element | null {
{status.kind === 'downloaded' && (
<>
- <p className="update-card__body">nodeterm v{status.version} is ready to install.</p>
- <button className="update-card__link" onClick={openReleases}>
+ {/* `downloaded` is only reached on self-install delivery, where install-on-quit is on. */}
+ <p className="update-card__body">
+ nodeterm v{status.version} is ready. It installs automatically the next time you quit.
+ </p>
+ {highlightList}
+ {status.installError && <p className="update-card__hint">{status.installError}</p>}
+ <button className="update-card__link" onClick={openNotes}>
Release notes
</button>
- <button
- className="update-card__btn"
- onClick={() => window.nodeTerminal.updates.restart()}
- >
- Restart to update
+ <div className="update-card__actions">
+ <button className="update-card__btn" onClick={restartNow}>
+ Restart to update
+ </button>
+ <button className="update-card__link" onClick={minimize}>
+ Later
+ </button>
+ </div>
+ </>
+ )}
+
+ {(status.kind === 'preparing' || status.kind === 'restarting') && (
+ <>
+ <p className="update-card__body">
+ {status.kind === 'preparing'
+ ? `Getting nodeterm v${status.version} ready to install. This can take a moment.`
+ : 'nodeterm will close and reopen on the new version. Your terminals keep running.'}
+ </p>
+ <button className="update-card__btn" disabled>
+ <span className="update-card__spinner" aria-hidden="true" />
+ {status.kind === 'preparing' ? 'Preparing…' : 'Restarting…'}
</button>
</>
)}
@@ -273,6 +349,15 @@ export function UpdateCard(): JSX.Element | null {
<p className="update-card__body">nodeterm is on the latest version.</p>
)}
+ {status.kind === 'updated' && (
+ <>
+ {highlightList ?? <p className="update-card__body">See what changed in this release.</p>}
+ <button className="update-card__link" onClick={openNotes}>
+ What&apos;s new
+ </button>
+ </>
+ )}
+
{status.kind === 'required' && (
<>
<p className="update-card__body">
@@ -280,9 +365,18 @@ export function UpdateCard(): JSX.Element | null {
{status.minSupported ? ` (minimum ${status.minSupported})` : ''}. Please update to
continue.
</p>
- <button className="update-card__btn" onClick={() => window.nodeTerminal.updates.check()}>
- Update now
- </button>
+ {status.percent !== null ? (
+ <>
+ <div className="update-card__bar">
+ <div className="update-card__bar-fill" style={{ width: `${status.percent}%` }} />
+ </div>
+ <p className="update-card__pct">Downloading… {Math.round(status.percent)}%</p>
+ </>
+ ) : (
+ <button className="update-card__btn" onClick={checkForUpdatesNow}>
+ Update now
+ </button>
+ )}
</>
)}
diff --git a/src/renderer/components/settings/sections/UpdatesSection.tsx b/src/renderer/components/settings/sections/UpdatesSection.tsx
index 6eb1e96e4..b82693658 100644
--- a/src/renderer/components/settings/sections/UpdatesSection.tsx
+++ b/src/renderer/components/settings/sections/UpdatesSection.tsx
@@ -3,6 +3,7 @@ import { SettingsSection } from '../SettingsSection'
import { SearchableRow } from '../SearchableRow'
import { FieldRow } from '../FieldRow'
import { Button } from '@renderer/ui/Button'
+import { checkForUpdatesNow } from '@renderer/state/pendingUpdate'
const ROWS = {
updates: { title: 'Updates', keywords: ['update', 'version', 'check', 'upgrade'] }
@@ -22,12 +23,7 @@ export function UpdatesSection({ isActive }: { isActive: boolean }): React.JSX.E
label="Current version"
control={<span className="text-[13px] text-muted">{version || '…'}</span>}
/>
- <Button
- onClick={() => {
- window.dispatchEvent(new CustomEvent('nodeterm:update-checking'))
- window.nodeTerminal.updates.check()
- }}
- >
+ <Button onClick={checkForUpdatesNow}>
Check for updates
</Button>
<p className="text-sm text-muted">Results appear in the update card at the bottom-right.</p>
diff --git a/src/renderer/lib/releaseNotes.test.ts b/src/renderer/lib/releaseNotes.test.ts
new file mode 100644
index 000000000..b252079be
--- /dev/null
+++ b/src/renderer/lib/releaseNotes.test.ts
@@ -0,0 +1,94 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import {
+ LAST_SEEN_VERSION_KEY,
+ lastSeenDecision,
+ noteVersionSeen,
+ releaseHighlights,
+ releaseNotesUrl,
+ type VersionStorage
+} from './releaseNotes'
+
+describe('releaseHighlights', () => {
+ it('takes the first three markdown bullets as plain text', () => {
+ const notes = '## Highlights\n\n- **Faster** canvas\n* Fix [SSH](https://x) reconnect\n• `tmux` 3.4 support\n- fourth'
+ expect(releaseHighlights(notes)).toEqual(['Faster canvas', 'Fix SSH reconnect', 'tmux 3.4 support'])
+ })
+
+ it('reads numbered lists too, and honours max', () => {
+ expect(releaseHighlights('1. one\n2) two', 1)).toEqual(['one'])
+ })
+
+ it('reads <li> items of HTML notes as text, never as markup', () => {
+ const html = '<h2>New</h2><ul><li><b>Bold</b> thing</li><li>Second &amp; more<img src=x onerror=alert(1)></li></ul>'
+ expect(releaseHighlights(html)).toEqual(['Bold thing', 'Second & more'])
+ })
+
+ it('no list, empty or non-string notes → nothing', () => {
+ expect(releaseHighlights('Just a paragraph.')).toEqual([])
+ expect(releaseHighlights('')).toEqual([])
+ expect(releaseHighlights(undefined)).toEqual([])
+ expect(releaseHighlights(42)).toEqual([])
+ })
+
+ it('truncates a long bullet', () => {
+ const [h] = releaseHighlights(`- ${'a'.repeat(400)}`)
+ expect(h.length).toBe(140)
+ expect(h.endsWith('…')).toBe(true)
+ })
+})
+
+describe('releaseNotesUrl', () => {
+ it('anchors at the version when known', () => {
+ expect(releaseNotesUrl('0.5.0')).toBe('https://nodeterm.dev/releases#v0.5.0')
+ expect(releaseNotesUrl(null)).toBe('https://nodeterm.dev/releases')
+ })
+})
+
+describe('lastSeenDecision', () => {
+ it('fresh install: record silently', () => {
+ expect(lastSeenDecision(null, '0.5.0')).toEqual({ show: false, write: true })
+ })
+ it('same version: nothing', () => {
+ expect(lastSeenDecision('0.5.0', '0.5.0')).toEqual({ show: false, write: false })
+ })
+ it('upgrade: announce once and record', () => {
+ expect(lastSeenDecision('0.4.3', '0.5.0')).toEqual({ show: true, write: true })
+ })
+ it('downgrade: record, never announce', () => {
+ expect(lastSeenDecision('0.5.0', '0.4.3')).toEqual({ show: false, write: true })
+ })
+})
+
+describe('noteVersionSeen', () => {
+ const mem = (init: Record<string, string> = {}): VersionStorage & { data: Record<string, string> } => {
+ const data = { ...init }
+ return { data, getItem: (k) => data[k] ?? null, setItem: (k, v) => void (data[k] = v) }
+ }
+
+ it('announces an upgrade exactly once', () => {
+ const s = mem({ [LAST_SEEN_VERSION_KEY]: '0.4.3' })
+ expect(noteVersionSeen('0.5.0', () => s)).toBe(true)
+ expect(noteVersionSeen('0.5.0', () => s)).toBe(false)
+ expect(s.data[LAST_SEEN_VERSION_KEY]).toBe('0.5.0')
+ })
+
+ it('a throwing storage accessor is silence, not a crash', () => {
+ expect(
+ noteVersionSeen('0.5.0', () => {
+ throw new Error('SecurityError')
+ })
+ ).toBe(false)
+ expect(noteVersionSeen('0.5.0', () => null)).toBe(false)
+ })
+
+ it('a storage that cannot record stays quiet rather than repeating every launch', () => {
+ const s: VersionStorage = {
+ getItem: () => '0.4.3',
+ setItem: () => {
+ throw new Error('QuotaExceeded')
+ }
+ }
+ expect(noteVersionSeen('0.5.0', () => s)).toBe(false)
+ })
+})
diff --git a/src/renderer/lib/releaseNotes.ts b/src/renderer/lib/releaseNotes.ts
new file mode 100644
index 000000000..c317dfe28
--- /dev/null
+++ b/src/renderer/lib/releaseNotes.ts
@@ -0,0 +1,90 @@
+// Release-notes highlights for the update card, and the one-time "Updated to vX" decision. Pure,
+// apart from the storage accessor, which is injected and wrapped (it can throw in a private window
+// or with blocked site data).
+import { isNewerVersion } from '@shared/update-gate'
+import { RELEASES_URL } from '../state/pendingUpdate'
+
+const HIGHLIGHT_MAX = 140
+
+/** Strip inline markdown down to readable text. Rendered as plain text — never as HTML. */
+function plain(line: string): string {
+ return line
+ .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+ .replace(/(\*\*|__|`)/g, '')
+ .replace(/\s+/g, ' ')
+ .trim()
+}
+
+/**
+ * The first `max` bullet points of a release's notes (markdown `-`/`*`/`•`/`1.` lists, or the
+ * `<li>` items of HTML notes — GitHub-style feeds carry HTML), as plain text. HTML goes through
+ * DOMParser's `textContent` (inert: a parsed document runs no scripts and loads nothing), never
+ * through a tag-stripping regex. Empty when the notes carry no list — the card then shows only its
+ * link.
+ */
+export function releaseHighlights(notes: unknown, max = 3): string[] {
+ if (typeof notes !== 'string' || !notes.trim()) return []
+ const out: string[] = []
+ const push = (raw: string): boolean => {
+ const t = plain(raw)
+ if (t) out.push(t.length > HIGHLIGHT_MAX ? `${t.slice(0, HIGHLIGHT_MAX - 1)}…` : t)
+ return out.length >= max
+ }
+ if (/<li[\s>]/i.test(notes)) {
+ if (typeof DOMParser === 'undefined') return []
+ const doc = new DOMParser().parseFromString(notes, 'text/html')
+ for (const li of Array.from(doc.querySelectorAll('li'))) if (push(li.textContent ?? '')) break
+ return out
+ }
+ for (const line of notes.split(/\r?\n/)) {
+ const m = /^\s*(?:[-*•]|\d+[.)])\s+(.*)$/.exec(line)
+ if (m && push(m[1])) break
+ }
+ return out
+}
+
+/** The releases page, anchored at one version when it is known. */
+export function releaseNotesUrl(version?: string | null): string {
+ return version ? `${RELEASES_URL}#v${encodeURIComponent(version)}` : RELEASES_URL
+}
+
+export const LAST_SEEN_VERSION_KEY = 'nodeterm.lastSeenVersion'
+
+/**
+ * Whether this launch is the first of a newer version than the last one seen — and whether to
+ * record the current version. A fresh install (nothing recorded) is silent: there is nothing it
+ * was "updated" from. A downgrade is recorded but never announced.
+ */
+export function lastSeenDecision(prev: string | null, current: string): { show: boolean; write: boolean } {
+ if (!current) return { show: false, write: false }
+ if (prev === current) return { show: false, write: false }
+ if (prev === null) return { show: false, write: true }
+ return { show: isNewerVersion(current, prev), write: true }
+}
+
+export interface VersionStorage {
+ getItem(key: string): string | null
+ setItem(key: string, value: string): void
+}
+
+/** Apply `lastSeenDecision` against storage; every access is guarded and a failure is silence. */
+export function noteVersionSeen(current: string, storage: () => VersionStorage | null): boolean {
+ let prev: string | null = null
+ let store: VersionStorage | null = null
+ try {
+ store = storage()
+ prev = store?.getItem(LAST_SEEN_VERSION_KEY) ?? null
+ } catch {
+ return false // unreadable: announcing on every launch would be worse than never
+ }
+ if (!store) return false
+ const d = lastSeenDecision(prev, current)
+ if (d.write) {
+ try {
+ store.setItem(LAST_SEEN_VERSION_KEY, current)
+ } catch {
+ return false // could not record it: stay quiet rather than repeat it every launch
+ }
+ }
+ return d.show
+}
diff --git a/src/renderer/lib/updateCardState.test.ts b/src/renderer/lib/updateCardState.test.ts
new file mode 100644
index 000000000..6f04a3784
--- /dev/null
+++ b/src/renderer/lib/updateCardState.test.ts
@@ -0,0 +1,179 @@
+import { describe, expect, it } from 'vitest'
+import { INITIAL_CARD_STATE, cardVisible, nextCardState, type CardEvent, type CardState } from './updateCardState'
+
+const run = (...events: CardEvent[]): CardState => events.reduce(nextCardState, INITIAL_CARD_STATE)
+
+describe('automatic checks are quiet until downloaded', () => {
+ it('an automatic available renders nothing, but is tracked', () => {
+ const s = run({ type: 'available', version: '1.1.0' }, { type: 'progress', percent: 40 })
+ expect(s.status).toEqual({ kind: 'available', version: '1.1.0', percent: 40, notes: undefined })
+ expect(cardVisible(s)).toBe(false)
+ })
+
+ it('the download finishing opens the ready card', () => {
+ const s = run({ type: 'available', version: '1.1.0' }, { type: 'downloaded', version: '1.1.0' })
+ expect(s.status.kind).toBe('downloaded')
+ expect(cardVisible(s)).toBe(true)
+ expect(s.minimized).toBe(false)
+ })
+
+ it('a user check shows progress; closing it drops back to quiet tracking', () => {
+ let s = run({ type: 'checking' }, { type: 'available', version: '1.1.0' })
+ expect(cardVisible(s)).toBe(true)
+ s = nextCardState(s, { type: 'dismiss' })
+ expect(cardVisible(s)).toBe(false)
+ expect(s.status.kind).toBe('available')
+ s = nextCardState(s, { type: 'downloaded', version: '1.1.0' })
+ expect(cardVisible(s)).toBe(true)
+ })
+
+ it('a user check during a quiet download reveals the progress card at its current percent', () => {
+ const s = run({ type: 'available', version: '1.1.0' }, { type: 'progress', percent: 63 }, { type: 'checking' })
+ expect(cardVisible(s)).toBe(true)
+ expect(s.status).toMatchObject({ kind: 'available', percent: 63 })
+ })
+
+ it('an automatic "not available" says nothing; a user check gets its answer', () => {
+ expect(run({ type: 'notAvailable' }).status.kind).toBe('idle')
+ expect(run({ type: 'checking' }, { type: 'notAvailable' }).status.kind).toBe('upToDate')
+ })
+})
+
+describe('never downgrade a staged update', () => {
+ const staged = (): CardState => run({ type: 'available', version: '1.1.0' }, { type: 'downloaded', version: '1.1.0' })
+
+ it('a repeat available for the same version keeps "ready"', () => {
+ expect(nextCardState(staged(), { type: 'available', version: '1.1.0' }).status.kind).toBe('downloaded')
+ })
+
+ it('a newer release downloading behind it keeps "ready" until that one is ready', () => {
+ let s = nextCardState(staged(), { type: 'available', version: '1.2.0' })
+ expect(s.status).toMatchObject({ kind: 'downloaded', version: '1.1.0' })
+ s = nextCardState(s, { type: 'downloaded', version: '1.2.0' })
+ expect(s.status).toMatchObject({ kind: 'downloaded', version: '1.2.0' })
+ })
+
+ it('a minimized ready card stays minimized on a repeat', () => {
+ const s = nextCardState(nextCardState(staged(), { type: 'minimize' }), { type: 'downloaded', version: '1.1.0' })
+ expect(s.minimized).toBe(true)
+ })
+
+ it('a dismissed version is not resurrected by a background repeat, but is by a user check', () => {
+ let s = nextCardState(staged(), { type: 'dismiss' })
+ expect(s.status.kind).toBe('idle')
+ s = nextCardState(s, { type: 'downloaded', version: '1.1.0' })
+ expect(s.status.kind).toBe('idle')
+ s = nextCardState(s, { type: 'available', version: '1.1.0' })
+ expect(s.status.kind).toBe('idle')
+ s = nextCardState(nextCardState(s, { type: 'checking' }), { type: 'downloaded', version: '1.1.0' })
+ expect(s.status.kind).toBe('downloaded')
+ })
+
+ it('a newer version than the dismissed one still surfaces', () => {
+ const s = run({ type: 'downloaded', version: '1.1.0' }, { type: 'dismiss' }, { type: 'downloaded', version: '1.2.0' })
+ expect(s.status).toMatchObject({ kind: 'downloaded', version: '1.2.0' })
+ })
+
+ it('errors never overwrite ready or required', () => {
+ expect(nextCardState(staged(), { type: 'error', message: 'x' }).status.kind).toBe('downloaded')
+ const req = run({ type: 'policy', policy: { mandatory: true, minSupported: '0.9.0' } })
+ expect(nextCardState(req, { type: 'error', message: 'x' }).status.kind).toBe('required')
+ })
+})
+
+describe('restart feedback', () => {
+ const staged = (): CardState => run({ type: 'downloaded', version: '1.1.0' })
+
+ it('a click is preparing at once; main moves it to restarting', () => {
+ let s = nextCardState(staged(), { type: 'restartClicked' })
+ expect(s.status).toEqual({ kind: 'preparing', version: '1.1.0' })
+ s = nextCardState(s, { type: 'installing', phase: 'preparing', version: '1.1.0' })
+ s = nextCardState(s, { type: 'restartStalled' })
+ expect(s.status.kind).toBe('preparing') // acknowledged: not stalled
+ s = nextCardState(s, { type: 'installing', phase: 'restarting', version: '1.1.0' })
+ expect(s.status).toEqual({ kind: 'restarting', version: '1.1.0' })
+ })
+
+ it('an unacknowledged click gives the button back', () => {
+ const s = nextCardState(nextCardState(staged(), { type: 'restartClicked' }), { type: 'restartStalled' })
+ expect(s.status.kind).toBe('downloaded')
+ })
+
+ it('an install failure returns to the ready card with the reason', () => {
+ let s = nextCardState(staged(), { type: 'installing', phase: 'preparing', version: '1.1.0' })
+ s = nextCardState(s, { type: 'error', message: 'signature' })
+ expect(s.status).toEqual({ kind: 'downloaded', version: '1.1.0', installError: 'signature' })
+ })
+
+ it('a tray restart while the card is closed shows the phase', () => {
+ const s = nextCardState(run({ type: 'downloaded', version: '1.1.0' }, { type: 'dismiss' }), {
+ type: 'installing',
+ phase: 'restarting',
+ version: '1.1.0'
+ })
+ expect(cardVisible(s)).toBe(true)
+ })
+})
+
+describe('the mandatory policy', () => {
+ it('requires from idle / checking / error, and carries a quiet download\'s progress', () => {
+ expect(run({ type: 'policy', policy: { mandatory: true, minSupported: '1.0.0' } }).status).toEqual({
+ kind: 'required',
+ minSupported: '1.0.0',
+ percent: null
+ })
+ const s = run({ type: 'available', version: '1.1.0' }, { type: 'progress', percent: 20 }, {
+ type: 'policy',
+ policy: { mandatory: true, minSupported: '1.0.0' }
+ })
+ expect(s.status).toEqual({ kind: 'required', minSupported: '1.0.0', percent: 20 })
+ expect(nextCardState(s, { type: 'progress', percent: 70 }).status).toMatchObject({ percent: 70 })
+ })
+
+ it('never overrides ready or the manual download card', () => {
+ const p = { type: 'policy', policy: { mandatory: true, minSupported: '1.0.0' } } as const
+ expect(run({ type: 'downloaded', version: '1.1.0' }, p).status.kind).toBe('downloaded')
+ expect(run({ type: 'available', version: '1.1.0', manual: true }, p).status.kind).toBe('manual')
+ })
+
+ it('a real non-mandatory answer clears it; an empty read does not', () => {
+ const req = run({ type: 'policy', policy: { mandatory: true, minSupported: '1.0.0' } })
+ expect(nextCardState(req, { type: 'policy', policy: { mandatory: false, minSupported: null } }).status.kind).toBe(
+ 'required'
+ )
+ expect(nextCardState(req, { type: 'policy', policy: { mandatory: false, minSupported: '0.1.0' } }).status.kind).toBe(
+ 'idle'
+ )
+ })
+
+ it('cannot be dismissed', () => {
+ const req = run({ type: 'policy', policy: { mandatory: true, minSupported: '1.0.0' } })
+ expect(nextCardState(req, { type: 'dismiss' }).status.kind).toBe('required')
+ })
+})
+
+describe('manual (check-only) delivery', () => {
+ it('opens its card on an automatic check — it is the only signal there is', () => {
+ const s = run({ type: 'available', version: '1.1.0', manual: true })
+ expect(cardVisible(s)).toBe(true)
+ })
+
+ it('a repeat does not un-minimize it', () => {
+ const s = run({ type: 'available', version: '1.1.0', manual: true }, { type: 'minimize' }, {
+ type: 'available',
+ version: '1.1.0',
+ manual: true
+ })
+ expect(s.minimized).toBe(true)
+ })
+})
+
+describe('updated note', () => {
+ it('shows only over an idle card and expires', () => {
+ let s = run({ type: 'updated', version: '1.1.0' })
+ expect(s.status).toEqual({ kind: 'updated', version: '1.1.0' })
+ s = nextCardState(s, { type: 'updatedExpired' })
+ expect(s.status.kind).toBe('idle')
+ expect(run({ type: 'checking' }, { type: 'updated', version: '1.1.0' }).status.kind).toBe('checking')
+ })
+})
diff --git a/src/renderer/lib/updateCardState.ts b/src/renderer/lib/updateCardState.ts
new file mode 100644
index 000000000..4f646a37f
--- /dev/null
+++ b/src/renderer/lib/updateCardState.ts
@@ -0,0 +1,264 @@
+// The update card's state machine — pure, so every transition unit-tests without React or Electron.
+//
+// Rules the card used to break, each one a user-visible annoyance:
+// - A staged update must never be downgraded: a 6h re-check's repeat `available` turned "Update
+// ready" back into "Downloading 0%" and un-minimized it. `downloaded` (and the install phases
+// after it) and the mandatory `required` card are only ever replaced by something further along.
+// - A repeat of what the card already shows must not un-minimize it, and a version the user
+// dismissed stays dismissed until they ask (a user check) or a newer version arrives.
+// - Automatic checks download QUIETLY: the card appears at `downloaded`, not as a progress bar the
+// user never asked for. A user-initiated check shows its progress; closing that progress card
+// drops back to quiet mode, it does not stop tracking the download.
+// - Errors never overwrite `downloaded` or `required` (main already keeps background failures off
+// the card; this is the second line).
+import { isNewerVersion } from '@shared/update-gate'
+import type { UpdatePolicy } from '@shared/types'
+
+export type CardStatus =
+ | { kind: 'idle' }
+ | { kind: 'checking' }
+ | { kind: 'available'; version: string; percent: number; notes?: string }
+ // A .deb/.rpm Linux install (or the check-only Windows beta) can't self-install — a manual
+ // download link, no progress/restart.
+ | { kind: 'manual'; version: string; notes?: string }
+ // This build has no update channel at all (issue #814): "we cannot look", not "you are current".
+ | { kind: 'noChannel' }
+ // `installError`: a restart that was attempted and failed — the update is still staged.
+ | { kind: 'downloaded'; version: string; notes?: string; installError?: string }
+ | { kind: 'preparing'; version: string }
+ | { kind: 'restarting'; version: string }
+ | { kind: 'upToDate' }
+ | { kind: 'required'; minSupported: string | null; percent: number | null }
+ | { kind: 'error'; message: string }
+ // First launch of a new version: a one-time "Updated to vX" note.
+ | { kind: 'updated'; version: string }
+
+export interface CardState {
+ status: CardStatus
+ minimized: boolean
+ /** Self-install download running without a card (automatic check, or progress card closed). */
+ quiet: boolean
+ /** The current flow was started by the user (Settings → Check, "Update now"). */
+ userInitiated: boolean
+ /** The version whose card the user closed; not resurrected by a background repeat. */
+ dismissedVersion: string | null
+ /** Main acknowledged the restart click (sent `installing`). */
+ installAck: boolean
+}
+
+export type CardEvent =
+ | { type: 'checking' }
+ | { type: 'available'; version: string; notes?: string; manual?: boolean }
+ | { type: 'progress'; percent: number }
+ | { type: 'downloaded'; version: string; notes?: string }
+ | { type: 'notAvailable' }
+ | { type: 'upToDateExpired' }
+ | { type: 'noChannel' }
+ | { type: 'error'; message: string }
+ | { type: 'installing'; phase: 'preparing' | 'restarting'; version: string | null }
+ | { type: 'restartClicked' }
+ | { type: 'restartStalled' }
+ | { type: 'policy'; policy: UpdatePolicy }
+ | { type: 'dismiss' }
+ | { type: 'minimize' }
+ | { type: 'restore' }
+ | { type: 'updated'; version: string }
+ | { type: 'updatedExpired' }
+ | { type: 'simulate'; status: CardStatus }
+
+export const INITIAL_CARD_STATE: CardState = {
+ status: { kind: 'idle' },
+ minimized: false,
+ quiet: false,
+ userInitiated: false,
+ dismissedVersion: null,
+ installAck: false
+}
+
+/** The version a status is about, if any. */
+export function statusVersion(s: CardStatus): string | null {
+ return 'version' in s ? s.version : null
+}
+
+/** Staged or further along: only a newer staged version may replace these. */
+function isStaged(s: CardStatus): s is Extract<CardStatus, { kind: 'downloaded' | 'preparing' | 'restarting' }> {
+ return s.kind === 'downloaded' || s.kind === 'preparing' || s.kind === 'restarting'
+}
+
+/** Whether the card renders at all. */
+export function cardVisible(state: CardState): boolean {
+ if (state.status.kind === 'idle') return false
+ return !(state.quiet && state.status.kind === 'available')
+}
+
+export function nextCardState(state: CardState, ev: CardEvent): CardState {
+ const s = state.status
+ switch (ev.type) {
+ case 'checking': {
+ const keep =
+ s.kind === 'available' || s.kind === 'manual' || s.kind === 'required' || isStaged(s)
+ return {
+ ...state,
+ status: keep ? s : { kind: 'checking' },
+ minimized: false,
+ quiet: false,
+ userInitiated: true,
+ dismissedVersion: null
+ }
+ }
+
+ case 'available': {
+ if (isStaged(s) && !isNewerVersion(ev.version, s.version)) return state
+ // A newer release behind a staged one downloads in the background; the ready card stays
+ // until that one is ready too.
+ if (isStaged(s)) return state
+ if (s.kind === 'required') {
+ // The remedy is on its way: a check-only build hands over to its download card (the one
+ // action it has), a self-installing one keeps the mandatory card and shows progress in it.
+ if (ev.manual) return { ...state, status: { kind: 'manual', version: ev.version, notes: ev.notes }, minimized: false }
+ return { ...state, status: { ...s, percent: 0 } }
+ }
+ if (!state.userInitiated && state.dismissedVersion === ev.version) return state
+ if (ev.manual) {
+ const repeat = s.kind === 'manual' && s.version === ev.version
+ return {
+ ...state,
+ status: { kind: 'manual', version: ev.version, notes: ev.notes || (repeat ? s.notes : undefined) },
+ minimized: repeat ? state.minimized : false,
+ quiet: false
+ }
+ }
+ if (s.kind === 'available' && s.version === ev.version) {
+ return state.userInitiated ? { ...state, quiet: false, minimized: false } : state
+ }
+ return {
+ ...state,
+ status: { kind: 'available', version: ev.version, percent: 0, notes: ev.notes },
+ quiet: !state.userInitiated,
+ minimized: false
+ }
+ }
+
+ case 'progress':
+ if (s.kind === 'available') return { ...state, status: { ...s, percent: ev.percent } }
+ if (s.kind === 'required' && s.percent !== null) return { ...state, status: { ...s, percent: ev.percent } }
+ return state
+
+ case 'downloaded': {
+ if (isStaged(s)) {
+ if (!isNewerVersion(ev.version, s.version)) {
+ // A repeat (or the manual-check echo): no un-minimize unless the user asked.
+ return state.userInitiated ? { ...state, minimized: false, userInitiated: false } : state
+ }
+ } else if (!state.userInitiated && state.dismissedVersion === ev.version) {
+ return state
+ }
+ const notes = ev.notes || ((s.kind === 'available' || s.kind === 'manual') && s.version === ev.version ? s.notes : undefined)
+ return {
+ ...state,
+ status: { kind: 'downloaded', version: ev.version, notes: notes || undefined },
+ minimized: false,
+ quiet: false,
+ userInitiated: false,
+ installAck: false
+ }
+ }
+
+ case 'notAvailable': {
+ // Automatic checks are silent: "You're up to date" answers a question only the user asks.
+ if (!state.userInitiated) return state
+ const keep = s.kind === 'required' || s.kind === 'available' || s.kind === 'manual' || isStaged(s)
+ return { ...state, status: keep ? s : { kind: 'upToDate' }, minimized: false, userInitiated: false }
+ }
+
+ case 'upToDateExpired':
+ return s.kind === 'upToDate' ? { ...state, status: { kind: 'idle' } } : state
+
+ case 'noChannel':
+ // Never auto-hides, unlike `upToDate`: this card carries the only action the user has.
+ return s.kind === 'required'
+ ? { ...state, userInitiated: false }
+ : { ...state, status: { kind: 'noChannel' }, minimized: false, userInitiated: false }
+
+ case 'error': {
+ if (s.kind === 'preparing' || s.kind === 'restarting')
+ return {
+ ...state,
+ status: { kind: 'downloaded', version: s.version, installError: ev.message },
+ minimized: false,
+ userInitiated: false,
+ installAck: false
+ }
+ if (s.kind === 'downloaded' || s.kind === 'required') return { ...state, userInitiated: false }
+ return {
+ ...state,
+ status: { kind: 'error', message: ev.message },
+ minimized: false,
+ quiet: false,
+ userInitiated: false
+ }
+ }
+
+ case 'installing': {
+ const version = ev.version ?? statusVersion(s) ?? ''
+ return { ...state, status: { kind: ev.phase, version }, minimized: false, quiet: false, installAck: true }
+ }
+
+ case 'restartClicked':
+ return s.kind === 'downloaded'
+ ? { ...state, status: { kind: 'preparing', version: s.version }, installAck: false }
+ : state
+
+ case 'restartStalled':
+ // The click was never acknowledged (main refused it): give the button back.
+ return s.kind === 'preparing' && !state.installAck
+ ? { ...state, status: { kind: 'downloaded', version: s.version } }
+ : state
+
+ case 'policy': {
+ const p = ev.policy
+ if (p.mandatory) {
+ if (isStaged(s) || s.kind === 'manual') return state
+ if (s.kind === 'required') return { ...state, status: { ...s, minSupported: p.minSupported } }
+ return {
+ ...state,
+ status: { kind: 'required', minSupported: p.minSupported, percent: s.kind === 'available' ? s.percent : null },
+ minimized: false,
+ quiet: false
+ }
+ }
+ // A real answer (a minimum is known) that no longer requires the update clears the card —
+ // a rolled-back minSupported. An empty/failed read (no minimum) is no evidence of anything.
+ if (s.kind === 'required' && p.minSupported !== null) return { ...state, status: { kind: 'idle' } }
+ return state
+ }
+
+ case 'dismiss': {
+ if (s.kind === 'required') return state
+ // Closing a progress card drops back to quiet tracking; the ready card still comes.
+ if (s.kind === 'available') return { ...state, quiet: true, minimized: false, userInitiated: false }
+ return {
+ ...state,
+ status: { kind: 'idle' },
+ minimized: false,
+ userInitiated: false,
+ dismissedVersion: statusVersion(s) ?? state.dismissedVersion
+ }
+ }
+
+ case 'minimize':
+ return { ...state, minimized: true }
+
+ case 'restore':
+ return { ...state, minimized: false }
+
+ case 'updated':
+ return s.kind === 'idle' ? { ...state, status: { kind: 'updated', version: ev.version } } : state
+
+ case 'updatedExpired':
+ return s.kind === 'updated' ? { ...state, status: { kind: 'idle' } } : state
+
+ case 'simulate':
+ return { ...state, status: ev.status, quiet: false, minimized: false }
+ }
+}
diff --git a/src/renderer/state/pendingUpdate.ts b/src/renderer/state/pendingUpdate.ts
index 913ef0e6e..2e468c2cd 100644
--- a/src/renderer/state/pendingUpdate.ts
+++ b/src/renderer/state/pendingUpdate.ts
@@ -25,9 +25,19 @@ export const usePendingUpdate = create<PendingUpdateState>((set) => ({
export const RELEASES_URL = 'https://nodeterm.dev/releases'
+/**
+ * A USER-initiated update check. The card listens for `nodeterm:update-checking` to know the user
+ * asked — that is what makes it show progress and "You're up to date", which automatic checks
+ * never do. Every button that checks goes through here.
+ */
+export function checkForUpdatesNow(): void {
+ window.dispatchEvent(new CustomEvent('nodeterm:update-checking'))
+ window.nodeTerminal.updates.check()
+}
+
/** What clicking the title-bar button does for each pending kind. */
export function runPendingUpdate(p: PendingUpdate): void {
if (p.kind === 'downloaded') window.nodeTerminal.updates.restart()
else if (p.kind === 'manual') window.open(RELEASES_URL, '_blank', 'noopener')
- else window.nodeTerminal.updates.check()
+ else checkForUpdatesNow()
}
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 4caaf30b8..7f1ed3943 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -5231,6 +5231,55 @@ body,
background: var(--accent-hover);
}
+/* Preparing / restarting: the click was taken, the button says so and cannot be pressed twice. */
+.update-card__btn:disabled {
+ display: inline-flex;
+ align-items: center;
+ gap: 8px;
+ opacity: 0.7;
+ cursor: default;
+}
+
+.update-card__btn:disabled:hover {
+ background: var(--accent);
+}
+
+.update-card__spinner {
+ width: 11px;
+ height: 11px;
+ border: 2px solid rgba(255, 255, 255, 0.35);
+ border-top-color: #fff;
+ border-radius: 50%;
+ animation: nt-spin 0.8s linear infinite;
+}
+
+.update-card__actions {
+ display: flex;
+ align-items: center;
+ gap: 14px;
+}
+
+.update-card__actions .update-card__link {
+ align-self: center;
+}
+
+.update-card__notes {
+ margin: 0;
+ padding-left: 18px;
+ font-size: 12.5px;
+ color: rgba(var(--tint-rgb), 0.7);
+}
+
+.update-card__notes li + li {
+ margin-top: 2px;
+}
+
+.update-card__hint {
+ margin: 0;
+ font-size: 12.5px;
+ color: rgba(var(--tint-rgb), 0.6);
+}
+
.update-card--pill {
flex-direction: row;
align-items: center;