[Design Exploration] Browser-style preview toolbar

[shaunandrews]

Related issues

• STU-2370
• Compare the permanent site-header exploration in Design Exploration: Replace the site dropdown with a permanent site header #4400 and the full browser-tab exploration in [Design Exploration] Full browser preview tabs #4753, which extends this toolbar with independent tab/history state and platform-standard modifier-click navigation.

How AI was used in this PR

AI assisted with iterative implementation, refactoring, and test updates. Shaun directed the interaction and visual design through hands-on review of the running Studio preview, including toolbar spacing, responsive behavior, control states, icon treatment, and dark-mode corrections.

Proposed Changes

• Explore a conventional browser-style preview toolbar that replaces the realm tab selector with a filled URL field and familiar navigation controls.
• Give the URL field a deliberate browser-address treatment: 32px tall, comfortably padded, strongly rounded, filled rather than bordered, and theme-aware in light and dark mode.
• Keep Front-end, WordPress admin, and Database available from the address menu, then add deduplicated per-site recent addresses as the user navigates.
• Make navigation more useful with browser-like back, forward, and refresh controls, including right-click history menus for jumping between visited pages.
• Keep preview tools understandable at a glance: Annotate uses a bordered secondary treatment, while Responsive always keeps its current mode visible and uses a checkmark to identify the selected menu item.
• Move the Open in action to the chat header, where its split button stays visually quiet at rest and preserves external destinations without crowding the browser toolbar.
• Preserve compact behavior, truncation, theme-aware colors, and legible controls across narrow layouts and light/dark appearances.
• Hide empty browser chrome while a site is stopped, remove obsolete realm-number shortcuts, and disable preview-only controls on Database with explanatory tooltips.

This is intentionally a design exploration. The interaction model and visual treatment are presented for feedback rather than as a final approved direction.

Current screenshots

The set below covers the address menu and recents, compact toolbar behavior, dark mode, and the disabled Database state.

Wide · light · address menu	Narrow · light · toolbar

Wide · dark · address menu	Narrow · light · Database state

Testing Instructions

1. Launch the Agentic UI in Studio and open a running local site with the preview visible.
2. Confirm the toolbar presents back, forward, refresh, the 32px filled URL field, Responsive, and Annotate.
3. Confirm the URL field has no resting border, retains a clear focus treatment, and remains legible in light and dark mode.
4. Focus the URL field and use Front-end, WordPress, and Database; verify the menu closes after selection.
5. Submit new paths, reopen the address menu, and confirm deduplicated recent addresses appear only for that site.
6. Navigate through several pages, then right-click Back and Forward; verify each history menu opens below its button and can jump to an entry.
7. Open the Responsive dropdown and try Responsive, Mobile, Tablet, Desktop, and Desktop + Mobile. Confirm the trigger label updates and only the selected row has a checkmark.
8. Open a Database destination and confirm Responsive and Annotate are disabled with explanatory tooltips.
9. Stop the site and confirm the empty browser toolbar is hidden.
10. Confirm Open in appears at the top-right of the chat panel, repeats the current default destination, has no border or fill at rest, and remains legible as chat content scrolls behind it.
11. Narrow the preview and confirm Responsive keeps its visible label while Annotate can collapse to its icon.
12. Repeat the visual checks in both light and dark color schemes.

Automated verification completed for the latest update:

• npm test -- apps/ui/src/components/site-preview/address-bar.test.tsx apps/ui/src/components/site-preview/index.test.tsx apps/ui/src/components/site-preview/inspector-script.test.ts (65 tests)
• npm run typecheck -w @studio/ui
• npm run cli:build:ui on the combined exploration branch

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[wojtekn]

@shaunandrews I merged trunk, resolved the conflict, tested, and fixed minor issues. I think it solves STU-2370. I see potential improvements:

• "Annotate" hides everything when clicked, but "Responsive" stays. It would make sense to make it consistent and hide this one, too.
• The new "Open in" button mixes two concepts and is inconsistent with the Overview tab:
  • Finder, PhpStorm, and Terminal are scoped to the site in general, and they open the site in external apps, but the "Browser" opens the currently active page in the external browser. What if we moved this one item to the browser bar, maybe as the last icon?
  • Then we could add phpMyAdmin to Finder, PhpStorm, and Terminal, so that "Open" in the dropdown menu would be consistent with the "Open in" section from the site's Overview

[wojtekn]

Two more small things:

• The "Browser" button has a grey hover and gets a grey outline when the dropdown is clicked, but the "Responsive" button has a grey hover without a grey outline.
• Also, the "Responsive" button loses the hover after the dropdown is opened and then closed
• The "Browser" label is not entirely clear - would "Open in" be better and more consistent with the Overview tab?

[wpmobilebot]

📊 Performance Test Results

Comparing 7349286 vs trunk

app-size

Metric	trunk	7349286	Diff	Change
App Size (Mac)	1456.81 MB	1456.77 MB	0.05 MB	⚪ 0.0%

site-editor

Metric	trunk	7349286	Diff	Change
load	1200 ms	1245 ms	+45 ms	⚪ 0.0%

site-startup

Metric	trunk	7349286	Diff	Change
siteCreation	7520 ms	7538 ms	+18 ms	⚪ 0.0%
siteStartup	3367 ms	3369 ms	+2 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[Poliuk]

I've been testing it, and it's very clear and very easy to use. Great job, @shaunandrews.

In addition to @wojtekn's comments above, I just have three small suggestions:

• When entering the "annotate" mode, you hide the URL box, which makes sense, as we need the user to stay on the current page, but I think we can leverage that change and make it clearer to the user that he's in "annotate" mode by adding some sort of message in the center of the top bar.
• The favicon in the URL bar is not clickable; I think it should be clickable in the same way the URL is.
• Clicking in the URL opens a pop-up with the 3 shortcuts (:chef_kiss:) and the browser history, and the only way I've found to close it is by choosing one of the options in the list or pressing ESC on my keyboard. I expected clicking anywhere outside the pop-up to close it; let's make that happen.

[shaunandrews]

Thanks for the review y'all. Here's whats been updated:

1. Removed the split buttons and fixed the button focus/hover states. Open in now matches the behavior of the responsive mode picker.
2. The responsive button shrinks to an icon when there's no room.
3. Annotate now makes the toolbar purple, and we use this purple elsewhere while in annotation mode.
4. Fixed the bugs around clicking the site icon and closing the URL dropdown menu.

[wojtekn]

Thanks @shaunandrews , it's much smoother now.

I think those still stand:

• "Annotate" hides everything when clicked, but "Responsive" stays. It would make sense to make it consistent and hide this one, too. Another thing is that annotate dialogs don't behave well when user is switching responsive modes.
• The new "Open in" button still mixes two concepts: Finder, PhpStorm, and Terminal are scoped to the site in general, and they open the site in external apps, but the "Browser" opens the currently active page in the external browser. What if we moved this one item to the browser bar, maybe as the last icon? It would work well with the "Full preview" button- the first would open it full-size in the Studio window, and the new one would open the currently visible page in an external browser.

Thanks for adding phpMyAdmin to "Open in". What if we changed this one to open phpMyAdmin in an external browser, so it's consistent with other actions in this menu? If the user wants to use phpMyAdmin in the internal browser, they can still click in the address bar and pick the database there.

[shaunandrews]

My bad @wojtekn I definitely read your feedback, but just got lost in the shuffle!

"Annotate" hides everything when clicked, but "Responsive" stays. It would make sense to make it consistent and hide this one, too. Another thing is that annotate dialogs don't behave well when user is switching responsive modes.

I remove the navigation controls, because those break the annotation feature. But I like being able to switch views while annotating to give the agent notes about mobile or other viewport-specific options.

But you're right that the experience has some rough edges; I've tried to smooth over some of the more common ones:

1. Selection indicators, notes, and the composer now reorient themselves as the viewport size changes.
2. Notes now record/report the viewport size, but in the UI and to the agent.
3. Notes made in other viewports display, but with a dashed outline appearance.

The new "Open in" button still mixes two concepts: Finder, PhpStorm, and Terminal are scoped to the site in general, and they open the site in external apps, but the "Browser" opens the currently active page in the external browser.

It took me a while to see your point here, but now I agree. The "Open in..." browser option now opens your homepage in your browser. I've added a new control to the preview toolbar to let you quickly open the current page in your browser.

What if we changed this one to open phpMyAdmin in an external browser, so it's consistent with other actions in this menu?

Done!

[wojtekn]

I remove the navigation controls, because those break the annotation feature. But I like being able to switch views while annotating to give the agent notes about mobile or other viewport-specific options.

Makes sense, thanks for sharing more on this use case. I tested it now, and it works better.

It took me a while to see your point here, but now I agree. The "Open in..." browser option now opens your homepage in your browser. I've added a new control to the preview toolbar to let you quickly open the current page in your browser.

Thanks for considering it - it is much more consistent now. The location you chose for the new control is even better than the one I proposed.