tranquil
Docs

Browser Start-Page Tweaks — Delivery Notes

Delivery summary for three refinements to the tranquil-browser://blank start page. No ADR — these are polish on existing decisions; they extend Browser Start Page — Delivery Notes and Browser Color-Scheme Isolation — Delivery Notes.

Status

Implemented and verified in the running app (light + dark). Not yet committed.

TweakState
Theme-aware start page (light/dark, matches the active Tranquil theme, live)✅ verified
Tab title reads “Tranquil Browser”✅ verified
Empty address bar + placeholder on the start page✅ verified

1 · Theme-aware start page (light/dark, live)

resources/home.html is an isolated file:// webview — it can’t read theme LESS, and the OS color scheme it could fall back to may not match the active Tranquil theme (business-dark on a light-mode Mac, etc.). So the host tells it explicitly.

  • lib/tranquil-browser.js — activeThemeMode() returns 'light'/'dark' from core.themes (matches *light* UI themes, ignores *-syntax). blankPageUrl() builds the home.html file:// URL and appends ?theme=<mode>. Both the fresh-open path and the restore path (getTranquilBrowserUrl) use it, so a restored blank tab picks up the theme current at restore.
  • resources/home.html — an early head script reads ?theme= and sets data-theme on <html> before the stylesheet parses (no flash). CSS keys palettes off :root[data-theme="dark|light"], with @media (prefers-color-scheme) scoped to :root:not([data-theme]) as a fallback when no param is passed.
  • lib/tranquil-browser-view.js — each view subscribes to atom.themes.onDidChangeActiveThemes and calls applyStartPageTheme(), which pushes data-theme into the live webview via executeJavaScript — so an open start page recolors instantly on a theme switch (no reload). It no-ops for real sites (only the blank page reads data-theme) and when there’s no webview yet; the subscription lives on this.subscriptions and is disposed with the tab.

2 · Tab title “Tranquil Browser”

updatePageUrl() sets the tab title to "Tranquil Browser" whenever its already-computed isBlankPage is true (every other page keeps its real <title>). Chosen over editing home.html’s <title> because it applies on load, on Back-to-blank, and on restore, and dodges the model’s 20-char title truncation (“Tranquil Browser” is 16).

3 · Empty address bar + placeholder on the blank page

The bar used to display tranquil-browser://blank. That string was doing two jobs — the address-bar display and the model’s internal identity (getURI() dedup, serialize, restore). Decoupled:

  • Identity stays. model.url is still "tranquil-browser://blank" on the blank page.
  • Display is empty. updatePageUrl() calls this.url.val("") for the blank page; content() computes a displayUrl (empty for the blank/home.html case) for the initial render so there’s no flash of the file:// path. A placeholder: "Search or enter address" was added to the URL input — it only shows when empty, i.e. on the start page (which also has its own in-page search box).
  • Any transient repopulation (e.g. a refresh that sets the bar) self-corrects: reloading the page fires a navigation that re-runs updatePageUrl and re-clears the bar.

Gotchas worth remembering

  • The start page is an isolated file:// webview — theme can only reach it by URL param (initial) or executeJavaScript (live). CSS alone won’t follow the app theme.
  • Set data-theme before the stylesheet parses, or the page flashes the default palette.
  • Don’t overload model.url for display. It’s the tab’s identity for dedup/serialize/restore; the address-bar text is a separate concern.
  • Theme sync: home.html is self-contained (not in the theme repos), so its palette lives with the browser — but any browser toolbar changes still need mirroring in both theme tranquil-browser.less files, per the standing rule.

Related