Skip to content

Commit 044e763

Browse files
authored
fix(webui): first-run call to action, onboarding path for a fresh setup, and "what needs me" on the landing page (#1049)
* fix(webui): give first run a way forward (F3, F19) and keep "what needs me" on the landing page (F4) Web UI UX audit (docs/qa/ux-audit-webui-2026-08.md), first-run and onboarding. F3 — Servers page, zero servers. The page a new user lands on after closing the wizard said "No servers found / No servers available" and offered nothing to click, above four zero-valued stat tiles, four zero-count filter pills and a search box with nothing to search. It now renders the AgentTokens-style empty state: a headline, one line of why upstream servers matter, Add Server (primary), Browse Registry, and a quiet "Import from your AI client configs" link into the wizard's Servers step. The stat/filter/search chrome is hidden until a server exists, and "you have nothing yet" is now a separate state from "nothing matched your filter" — the two need different answers. F4 residual (after #1044) — #1044 routed /usage, made the analytics panel the default landing page and demoted the hub diagram, which is most of the fix. What it did not carry across is the other half the finding asked for: the landing page still answered "what happened" and not "what needs me". The servers-needing-attention and tools-pending-approval banners were inside the Overview panel, so a fresh landing could render charts while a server was down and an unreviewed tool was waiting, and say neither. They move above the panel switcher: visible on whichever panel is active, silent when there is nothing to act on. F19 — onboarding wizard, Servers step. It was entirely "pick which servers from your existing AI clients to import", so a user with no prior MCP config hit a dead end. Adds a nothing-to-import branch (browse the registry / add a server manually). Import & quarantine becomes the single primary and the unreviewed path becomes a link that says what it skips, "Import without review" — previously two similar primaries with the safer one rendered weaker. The Docker-isolation/quarantine panel is expanded by default and moved out of the sticky footer into the step body, where it can be open without squeezing the list; the import list is capped and scrolls in place instead of clipping its last row; and every step gets a Back. * fix(webui): initialise the wizard when it is mounted already-open, and keep every step exitable Cross-model review (opencode/gpt-sol) on the first-run changes. P1 — the Servers page's import link sets the store flag and then routes to the Dashboard, which is the component that mounts the wizard. The wizard therefore came into existence with `show` already true and never saw a transition to watch: it rendered, but the open sequence never ran. The onMounted fallback that existed for this case kicked off the fetches but never chose a tab and never consumed the request — so the wizard opened on Clients regardless of what the opener asked for, and left the request behind to hijack the next plain open. One `immediate` watcher now owns opening; the fallback is gone. The requested tab is read before the first await, so it cannot outlive its own open or be consumed twice, and it applies immediately so the wizard never paints the wrong step while the fetches are in flight. P2 — `goToRegistry` did not await `dismiss()`. `dismiss()` awaits its mark-skipped calls before emitting `close`, so routing first tore down the Dashboard that owns the open flag and the emit could land with nothing left to clear it, springing the wizard back open on return. P2 — the Servers page fetches on neither mount nor route: App.vue and the Dashboard do. That leaves a window where `loading` is false and the list is still unknown, in which the filter/search empty state claimed "no servers match your search criteria" about a list nobody had fetched. Adds an explicit pending state, gated so servers already in hand are never held behind it. Also restores Close to the import action footer, which the review asked about and the live run then proved: a step whose only exits are "import" strands the user, and the committed e2e sweep dismisses an auto-opened wizard through exactly that control — on a fresh instance the wizard can land on this step. The security disclosure gains `group` so its arrow reflects the now-open state. * fix(webui): abandon superseded wizard opens, and stop a failed refresh from hiding the server list Round 2 of the cross-model review (opencode/gpt-sol). P1 — nothing cancels the wizard's open sequence. A close, or a close followed by a reopen, while its five fetches were still in flight let the abandoned run finish and stamp its tab over the newer state — and call startPolling() on a wizard that was no longer open, leaving a 5s poll running until unmount. Each run now takes a generation token and checks it still owns the wizard before it writes; closing and unmounting both retire whatever is in flight. P2 — `loading.error` was write-only. Silent background refreshes set it and no success ever cleared it, so a single transient blip replaced the Servers page with a full-page "Failed to load servers" for the rest of the session, hiding a list we were still holding. A list that arrives now clears the error, and the blocking error state is reserved for the case with no fallback: when servers are already in hand, a failed refresh degrades to a non-blocking notice above the grid that says the data may be stale and offers Retry. * fix(webui): sequence the wizard's config read and the server-list failure path Round 3 of the cross-model review (opencode/gpt-sol). The open sequence's config read is the one fetch whose result the user can also edit: it drives the quarantine and Docker-isolation checkboxes, and this branch expands that panel by default, so toggling one the moment the step appears is now the expected path rather than a corner. A read left over from a superseded open landing afterwards would silently flip the checkbox back to the old server value. It now carries the open's generation token and does not commit if it has been superseded. The other fetches in the sequence write read-only display state that either run populates identically, so they are left alone. Server-list failures now take the same ticket as successes. Only the list itself was sequenced, so an older request failing after a newer one had already delivered a list would raise a stale error over fresh data — the mirror image of the stale-list problem the sequencing exists to prevent. * fix(webui): let a failed server fetch advance the sequencing mark Round 4 of the cross-model review (opencode/gpt-sol). Only a delivered list advanced the mark, so a newer request that failed left it behind — and an older list arriving afterwards still passed the check, applying stale servers over the newer outcome and clearing its error on the way. Both outcomes are news about the same list, so both now claim the ticket.
1 parent 7e33f68 commit 044e763

9 files changed

Lines changed: 1469 additions & 240 deletions

‎frontend/src/components/OnboardingWizard.vue‎

Lines changed: 276 additions & 143 deletions
Large diffs are not rendered by default.

‎frontend/src/stores/onboarding.ts‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ import api from '@/services/api'
1717
* onboarding.openWizard()
1818
* }
1919
*/
20+
/** Tabs the wizard renders, in order. */
21+
export type WizardTab = 'clients' | 'servers' | 'verify'
22+
2023
export const useOnboardingStore = defineStore('onboarding', () => {
2124
// State fetched from backend
2225
const state = ref<OnboardingStateResponse | null>(null)
@@ -29,6 +32,14 @@ export const useOnboardingStore = defineStore('onboarding', () => {
2932
// are satisfied.
3033
const wizardOpen = ref(false)
3134

35+
// Which tab the wizard should land on when it next opens. Callers that mean
36+
// a *specific* step ("Import from your AI client configs" on the Servers
37+
// page) set it; everything else leaves it null and gets the default first
38+
// tab. It is a one-shot request: the wizard consumes it on open and clears
39+
// it, so a later plain `openWizard()` is never silently redirected to a tab
40+
// some earlier caller asked for.
41+
const wizardInitialTab = ref<WizardTab | null>(null)
42+
3243
// Computed
3344
const shouldShowWizard = computed(() => state.value?.should_show_wizard ?? false)
3445
const hasConnectedClient = computed(() => state.value?.has_connected_client ?? false)
@@ -146,12 +157,20 @@ export const useOnboardingStore = defineStore('onboarding', () => {
146157
await mark({ engaged: true })
147158
}
148159

149-
function openWizard(): void {
160+
function openWizard(tab: WizardTab | null = null): void {
161+
wizardInitialTab.value = tab
150162
wizardOpen.value = true
151163
// Best-effort first-shown stamp.
152164
void markShown()
153165
}
154166

167+
/** Read and clear the one-shot initial-tab request. */
168+
function consumeWizardInitialTab(): WizardTab | null {
169+
const tab = wizardInitialTab.value
170+
wizardInitialTab.value = null
171+
return tab
172+
}
173+
155174
function closeWizard(): void {
156175
wizardOpen.value = false
157176
}
@@ -161,6 +180,7 @@ export const useOnboardingStore = defineStore('onboarding', () => {
161180
loading,
162181
error,
163182
wizardOpen,
183+
wizardInitialTab,
164184
shouldShowWizard,
165185
hasConnectedClient,
166186
hasConfiguredServer,
@@ -179,6 +199,7 @@ export const useOnboardingStore = defineStore('onboarding', () => {
179199
markServerSkipped,
180200
markEngaged,
181201
openWizard,
202+
consumeWizardInitialTab,
182203
closeWizard,
183204
}
184205
})

‎frontend/src/stores/servers.ts‎

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -105,12 +105,27 @@ export const useServersStore = defineStore('servers', () => {
105105
let issueSeq = 0
106106
let appliedSeq = 0
107107

108-
function applyServerList(list: Server[], ticket: number) {
109-
if (ticket < appliedSeq) return
108+
// A request settles when it produces an outcome — a list OR a failure. Both
109+
// advance the mark, because both are news about the same list: if only
110+
// successes advanced it, a newer request failing would leave the mark behind
111+
// and an older list arriving afterwards would still be accepted, overwriting
112+
// the newer outcome with stale data.
113+
function claimTicket(ticket: number): boolean {
114+
if (ticket < appliedSeq) return false
110115
appliedSeq = ticket
116+
return true
117+
}
118+
119+
function applyServerList(list: Server[], ticket: number) {
120+
if (!claimTicket(ticket)) return
111121
// Smart merge preserves object references and avoids unnecessary re-renders
112122
servers.value = mergeServers(servers.value, list)
113123
loaded.value = true
124+
// A list that arrived is proof the previous failure is over. Without this
125+
// an error is write-only: silent background refreshes set it and nothing
126+
// ever clears it, so one transient blip pins an error banner on the
127+
// Servers page for the rest of the session.
128+
loading.value.error = null
114129
}
115130

116131
// Actions
@@ -120,15 +135,24 @@ export const useServersStore = defineStore('servers', () => {
120135
}
121136
const ticket = ++issueSeq
122137

138+
// Failures are sequenced exactly like successes: an older request failing
139+
// after a newer one already delivered a list must not raise a stale error
140+
// over fresh data — the mirror image of the stale-list problem the
141+
// sequencing exists to prevent.
142+
const recordError = (message: string) => {
143+
if (!claimTicket(ticket)) return
144+
loading.value.error = message
145+
}
146+
123147
try {
124148
const response = await api.getServers()
125149
if (response.success && response.data) {
126150
applyServerList(response.data.servers, ticket)
127151
} else {
128-
loading.value.error = response.error || 'Failed to fetch servers'
152+
recordError(response.error || 'Failed to fetch servers')
129153
}
130154
} catch (error) {
131-
loading.value.error = error instanceof Error ? error.message : 'Unknown error'
155+
recordError(error instanceof Error ? error.message : 'Unknown error')
132156
} finally {
133157
if (!silent) {
134158
loading.value.loading = false

‎frontend/src/views/Dashboard.vue‎

Lines changed: 92 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -6,92 +6,12 @@
66
<!-- Upgrade nudge (Spec 079): dismissible per-version update banner -->
77
<UpdateBanner />
88

9-
<!-- Usage ↔ Overview switcher (Spec 069 T016). Usage is the default panel
10-
(analytics-as-landing-page); each tab maps to a deep-linkable route
11-
(/usage, /overview) so the panel survives a reload or a shared link. -->
12-
<div role="tablist" class="tabs tabs-boxed w-fit" data-test="dashboard-view-switcher">
13-
<a
14-
role="tab"
15-
class="tab"
16-
:class="activeView === 'usage' ? 'tab-active' : ''"
17-
data-test="dashboard-tab-usage"
18-
@click="selectUsage"
19-
>Usage</a>
20-
<a
21-
role="tab"
22-
class="tab"
23-
:class="activeView === 'overview' ? 'tab-active' : ''"
24-
data-test="dashboard-tab-overview"
25-
@click="selectOverview"
26-
>Overview</a>
27-
</div>
28-
29-
<!-- Usage view: the panel wrapper is always in the DOM (kept hidden with
30-
v-show so switching back is instant and the Overview subtree is never
31-
torn down, SC-006). The heavy chart bundle + the usage fetch inside
32-
UsageView are mounted only once the panel has been active
33-
(usageEverActive) AND the server list has arrived, and stay code-split
34-
behind Suspense, so the Dashboard shell still paints immediately
35-
(SC-004). -->
36-
<div v-show="activeView === 'usage'" data-test="dashboard-usage-panel">
37-
<!-- First run: no upstream servers configured, so the analytics panel
38-
would only ever show "no data". Point the new user at the one action
39-
that makes the dashboard useful instead. -->
40-
<div
41-
v-if="showFirstRunCta"
42-
class="card bg-base-200 border border-base-300"
43-
data-test="dashboard-usage-first-run"
44-
>
45-
<div class="card-body items-center text-center py-12">
46-
<svg class="w-12 h-12 opacity-40" fill="none" stroke="currentColor" viewBox="0 0 24 24">
47-
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z" />
48-
</svg>
49-
<h3 class="font-semibold text-lg mt-2">Add your first server to see usage</h3>
50-
<p class="text-sm opacity-60 max-w-md">
51-
No upstream MCP servers are configured yet, so there is nothing to chart.
52-
Add one and this page will show call volume, token sinks, error rates and a timeline.
53-
</p>
54-
<div class="flex flex-wrap gap-2 justify-center mt-2">
55-
<button
56-
class="btn btn-primary btn-sm"
57-
data-test="dashboard-first-run-add-server"
58-
@click="showAddServer = true"
59-
>
60-
Add your first server
61-
</button>
62-
<router-link to="/repositories" class="btn btn-sm btn-ghost">Browse Registry</router-link>
63-
<button
64-
class="btn btn-sm btn-ghost"
65-
data-test="dashboard-first-run-overview"
66-
@click="selectOverview"
67-
>
68-
Go to Overview
69-
</button>
70-
</div>
71-
</div>
72-
</div>
73-
<!-- Hold the charts back until the server list has arrived: mounting
74-
UsageView first would fire a usage aggregate request and flash the
75-
"no usage data yet" card on a fresh install, only to be replaced by
76-
the CTA above a moment later. Both requests are issued together in
77-
onMounted, so this costs no extra round-trip. -->
78-
<div
79-
v-else-if="!serversFetchSettled && !serversStore.loaded"
80-
class="flex justify-center py-16"
81-
data-test="dashboard-usage-pending"
82-
>
83-
<span class="loading loading-spinner loading-lg"></span>
84-
</div>
85-
<Suspense v-else-if="usageEverActive">
86-
<UsageView />
87-
<template #fallback>
88-
<div class="flex justify-center py-16"><span class="loading loading-spinner loading-lg"></span></div>
89-
</template>
90-
</Suspense>
91-
</div>
92-
93-
<!-- Overview: v-show (not v-if) so its state survives a switch to Usage and back (SC-006). -->
94-
<div v-show="activeView === 'overview'" class="space-y-6" data-test="dashboard-overview-panel">
9+
<!-- "What needs me": servers in a bad state and tools awaiting approval.
10+
These live above the panel switcher rather than inside a panel — they
11+
are the one thing on this page the user is expected to act on, and
12+
burying them under a tab means the landing page can look calm while a
13+
server is down or an unreviewed tool is waiting. Each renders only
14+
when it has something to say, so a healthy install sees neither. -->
9515
<!-- Servers Needing Attention Banner (using unified health status) -->
9616
<div
9717
v-if="serversNeedingAttention.length > 0"
@@ -179,6 +99,92 @@
17999
</router-link>
180100
</div>
181101

102+
<!-- Usage ↔ Overview switcher (Spec 069 T016). Usage is the default panel
103+
(analytics-as-landing-page); each tab maps to a deep-linkable route
104+
(/usage, /overview) so the panel survives a reload or a shared link. -->
105+
<div role="tablist" class="tabs tabs-boxed w-fit" data-test="dashboard-view-switcher">
106+
<a
107+
role="tab"
108+
class="tab"
109+
:class="activeView === 'usage' ? 'tab-active' : ''"
110+
data-test="dashboard-tab-usage"
111+
@click="selectUsage"
112+
>Usage</a>
113+
<a
114+
role="tab"
115+
class="tab"
116+
:class="activeView === 'overview' ? 'tab-active' : ''"
117+
data-test="dashboard-tab-overview"
118+
@click="selectOverview"
119+
>Overview</a>
120+
</div>
121+
122+
<!-- Usage view: the panel wrapper is always in the DOM (kept hidden with
123+
v-show so switching back is instant and the Overview subtree is never
124+
torn down, SC-006). The heavy chart bundle + the usage fetch inside
125+
UsageView are mounted only once the panel has been active
126+
(usageEverActive) AND the server list has arrived, and stay code-split
127+
behind Suspense, so the Dashboard shell still paints immediately
128+
(SC-004). -->
129+
<div v-show="activeView === 'usage'" data-test="dashboard-usage-panel">
130+
<!-- First run: no upstream servers configured, so the analytics panel
131+
would only ever show "no data". Point the new user at the one action
132+
that makes the dashboard useful instead. -->
133+
<div
134+
v-if="showFirstRunCta"
135+
class="card bg-base-200 border border-base-300"
136+
data-test="dashboard-usage-first-run"
137+
>
138+
<div class="card-body items-center text-center py-12">
139+
<svg class="w-12 h-12 opacity-40" fill="none" stroke="currentColor" viewBox="0 0 24 24">
140+
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z" />
141+
</svg>
142+
<h3 class="font-semibold text-lg mt-2">Add your first server to see usage</h3>
143+
<p class="text-sm opacity-60 max-w-md">
144+
No upstream MCP servers are configured yet, so there is nothing to chart.
145+
Add one and this page will show call volume, token sinks, error rates and a timeline.
146+
</p>
147+
<div class="flex flex-wrap gap-2 justify-center mt-2">
148+
<button
149+
class="btn btn-primary btn-sm"
150+
data-test="dashboard-first-run-add-server"
151+
@click="showAddServer = true"
152+
>
153+
Add your first server
154+
</button>
155+
<router-link to="/repositories" class="btn btn-sm btn-ghost">Browse Registry</router-link>
156+
<button
157+
class="btn btn-sm btn-ghost"
158+
data-test="dashboard-first-run-overview"
159+
@click="selectOverview"
160+
>
161+
Go to Overview
162+
</button>
163+
</div>
164+
</div>
165+
</div>
166+
<!-- Hold the charts back until the server list has arrived: mounting
167+
UsageView first would fire a usage aggregate request and flash the
168+
"no usage data yet" card on a fresh install, only to be replaced by
169+
the CTA above a moment later. Both requests are issued together in
170+
onMounted, so this costs no extra round-trip. -->
171+
<div
172+
v-else-if="!serversFetchSettled && !serversStore.loaded"
173+
class="flex justify-center py-16"
174+
data-test="dashboard-usage-pending"
175+
>
176+
<span class="loading loading-spinner loading-lg"></span>
177+
</div>
178+
<Suspense v-else-if="usageEverActive">
179+
<UsageView />
180+
<template #fallback>
181+
<div class="flex justify-center py-16"><span class="loading loading-spinner loading-lg"></span></div>
182+
</template>
183+
</Suspense>
184+
</div>
185+
186+
<!-- Overview: v-show (not v-if) so its state survives a switch to Usage and back (SC-006). -->
187+
<div v-show="activeView === 'overview'" class="space-y-6" data-test="dashboard-overview-panel">
182188
<!-- Hub Visualization -->
183189
<div class="grid grid-cols-1 lg:grid-cols-[280px_1fr_280px] gap-0 min-h-[520px] relative">
184190

0 commit comments

Comments
 (0)