# Work App — Design Spec

**Date:** 2026-09-01
**Status:** Approved for implementation
**Type:** Prototype, iterated in place

## Purpose

A desktop app that is a browser for one thing only: the web tools used for work. A left
nav lists those tools; clicking one shows it. Links between configured tools navigate
inside the app; every other link leaves for the real browser.

It is not a general browser. There is no address bar, no tab strip, and no way to reach a
site that is not on the list.

## Constraints and decisions

Settled during brainstorming. Not open questions.

| Decision | Choice | Rationale |
|---|---|---|
| Shell | Tauri 2.11 · React 19 · Vite 7 · Tailwind 4 · TypeScript | Matches FlightTube, the reference app on this machine |
| App rendering | One child webview per app (`add_child`) | Iframes are impossible: Google, Microsoft and most SaaS send `X-Frame-Options: DENY` |
| Sessions | Persistent per-app cookie jar | You sign in once per tool and it sticks |
| Link routing | Injected JS click interceptor; permissive `on_navigation` | A strict navigation filter breaks every OAuth redirect chain |
| Tab memory | Every app is a live webview, hidden when inactive | Keeps scroll position, drafts and timers across switches |
| Collapsed nav | ~52px icon rail | Still clickable when collapsed |
| Storage | One `apps.json` in the app config dir | A list of a dozen apps does not need SQLite |
| Platform | macOS only | Single webview engine, single cookie store, no cross-platform branches |

### Known limitations, accepted

- **Multi-webview is `unstable` in Tauri.** The API can change between minor versions, so
  `tauri` is pinned to `=2.11.5`.
- **Browser cookie import was built, measured, and removed.** It worked mechanically —
  43 cookies decrypted from Arc and verifiably visible to the page — but Google, Microsoft
  and Odoo all refused the imported sessions, because each binds a session to the browser
  that created it. Signing in once inside the app is both simpler and more reliable, so
  the whole import path was deleted rather than kept as a feature that mostly fails.
- **Bounds sync trails layout by a frame.** A native webview is positioned from measurements
  the shell reports, so during a window resize it can lag. Every app in this class does.
- **The Chrome user agent is a lie.** Sites that sniff deeply may behave oddly. It is on by
  default because Google refuses logins from anything it identifies as an embedded webview,
  and it is overridable per app.
- **Reading Chrome's cookies raises a Keychain prompt.** Once, on pairing. That is macOS
  asking permission, and it is the correct behaviour.

## Verified environment

Confirmed present before writing this spec:

- `rustc` / `cargo` 1.98.0 (aarch64-apple-darwin)
- Node v22.22.2, npm 10.9.7
- Xcode Command Line Tools (sufficient; full Xcode not required)

Every API the design leans on was confirmed to exist in the vendored `tauri` 2.11.5 source:
`Window::add_child`, `Webview::{hide, show, set_bounds, bounds}`,
`WebviewBuilder::{on_navigation, on_new_window, user_agent, initialization_script,
data_store_identifier, on_page_load, on_download}`, and `NewWindowResponse::Deny`.

## Architecture

The window's own webview is the **shell**: React, drawing the nav, the top bar, settings
and dialogs. Each configured app is a **child webview** stacked in a "stage" rect to the
right of the nav.

```
┌ window ─────────────────────────────────────────────┐
│ ┌ nav ──────┐ ┌ stage ───────────────────────────┐  │
│ │  shell    │ │  child webview (active app)      │  │
│ │  webview  │ │  ...others hidden behind it      │  │
│ └───────────┘ └──────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
```

Child webviews are native views layered above the shell's content. They do not participate
in CSS layout and they paint over anything the shell draws beneath them. Two consequences:

- **The shell reports the stage rect.** A `ResizeObserver` on an empty `<div id="stage">`
  sends its bounding rect to Rust in logical pixels; Rust calls `set_bounds` on the active
  webview and `hide()` on the others.
- **Modals hide the stage.** Opening Settings hides the active app webview, or it would
  paint straight over the dialog.

All webviews are created at startup, but their loads are **staggered**: the active app
first, the rest over the following seconds, so launching does not fire a dozen simultaneous
page loads.

### Rust modules

| Module | Responsibility |
|---|---|
| `config.rs` | `apps.json` load, save, seed, migrate |
| `routing.rs` | Pure URL → decision. No I/O, fully unit-tested |
| `webviews.rs` | Child webview registry: create, show, hide, bounds, navigate |
| `cookies/mod.rs` | Installed-browser detection |
| `cookies/chrome.rs` | Chromium cookie DB read and `v10` decryption |
| `cookies/inject.rs` | `WKHTTPCookieStore` injection (macOS) |
| `commands.rs` | The Tauri command surface |
| `lib.rs` | Builder, menu bar, setup |

### Data model

`apps.json`, in the app config dir. Apps are flat with a `groupId` rather than nested, so
dragging one between groups is a field change and not a tree rewrite.

```
apps[]:   { id, name, url, scope[], groupId, favicon, userAgent?, order }
groups[]: { id, name, collapsed, order }
settings: { navCollapsed, theme, pairedBrowser, lastPairedAt }
```

`scope` defaults to the URL's **exact host** — `mail.google.com`, not `google.com` — or
Gmail and Drive would each swallow the other's links. Extra hosts are addable per app. A
URL matches an app if its host equals, or is a subdomain of, a scope entry. On ambiguity
the longest match wins.

### Link routing

An `initialization_script` in every app webview intercepts real user clicks and
`target=_blank`, and decides:

| Target | Action |
|---|---|
| In the current app's scope | Allow |
| A known identity provider | Allow — this is what keeps SSO working |
| In another app's scope | `preventDefault()`, switch to that app and navigate it |
| Anything else | `preventDefault()`, hand to the default browser |

The identity-provider list (`accounts.google.com`, `login.microsoftonline.com`,
`login.live.com`, Okta, Auth0, Duo, `appleid.apple.com`, `github.com/login`, …) exists
because a "Sign in with Google" button is a user click to a foreign host, and the naive
rule would send it to the external browser and strand the login there.

`on_navigation` returns `true` unconditionally and only reports the URL back to the shell
for the top bar. Redirects, meta-refreshes and OAuth bounces are never blocked.

`on_new_window` returns `NewWindowResponse::Deny` and re-runs the same decision in Rust, so
`window.open` cannot escape into a stray window. A `_blank` link within the same app
navigates that app's webview in place.

reaches into the Keychain is worse than one the user presses when something logs them out.

## UI

The design system is ported from FlightTube's `ui.tsx`: 30px control height, slate and sky,
outline-first controls, borders for separation and shadows only for elevation, a 9–15px type
ladder, and light and dark both designed rather than one derived from the other.

- **Nav, expanded (~240px)** — traffic-light drag inset, title with cog and collapse
  chevron, then groups as collapsible sections with uppercase tracked labels, apps as
  favicon-and-name rows. The active row inverts to `bg-slate-900 text-white`.
- **Nav, collapsed (~52px)** — favicons only, active marked with a left accent bar, name on
  hover, hairline dividers between groups. Still clickable, so switching does not require
  expanding.
- **Top bar (~38px)** — back, forward, reload, the current URL muted and truncated, and
  open-in-browser. WKWebView's swipe-back gesture is enabled alongside it.
- **Settings** — Apps, Groups, Browser pairing, Appearance.
- **First boot** — an empty state offering "Add your first app" and "Pair with a browser",
  seeded with test apps across three groups so cross-app routing is demonstrable at once.

## Testing

`routing.rs` and `config.rs` are pure and carry real unit tests: scope matching and its
precedence, identity-provider passthrough, the four routing decisions, serde round-trips,
and seeding. Cookie decryption is tested against a fixture database with a known key.

Webview orchestration and bounds sync have no seam that a unit test can reach. They are
verified by running the app and driving it.

## Notifications

WKWebView defines `window.Notification`, but it is inert: constructing one throws nothing
and shows nothing, so a page believes it has notified you and you never hear about it. It
is replaced by a shim that forwards over the same sentinel channel as everything else, and
Rust raises a real macOS notification carrying the app's name.

Verified on the machine: `permission: Granted · direct: raised · page: api=function shim=no`
was the reading that showed the native API existed and the shim had therefore never
installed. The shim now replaces it unconditionally.

A click on the banner switches to the app that raised it and then runs the page's own
click handler, which is the only thing that knows which message the notification was
about. This is why notifications are raised through `mac-notification-sys` rather than
Tauri's notification plugin: the plugin cannot report a click.

Three things had to be right for a banner to actually appear on screen, and each was
wrong at first:

1. **Identity.** `set_application` has to be called with the bundle identifier. Left alone,
   mac-notification-sys looks up an application named `"use_default"`, fails, and posts as
   `com.apple.Finder` — so notifications arrive wearing another app's alert style.
2. **Presentation while frontmost.** `NSUserNotificationCenter` suppresses the banner
   whenever the posting app is in front, delivering it silently to Notification Centre
   instead, unless the delegate implements `shouldPresentNotification:`. The crate's
   delegate implements only delivery and activation, so the missing method is added to its
   class at runtime. Without it, Gmail notifying while you sit in Odoo — the same window,
   still frontmost — would never be seen.
3. **Waiting for the click.** `send_notification` only blocks for a response when the
   options ask it to. Passing `None` returns immediately with `NotificationResponse::None`,
   so no click is ever observed. Waiting costs a parked thread, and a notification left in
   Notification Centre never resolves, so the number of waiters is capped at 32; past that
   the notification still appears but cannot be clicked through.

Service-worker push is **not** covered — only notifications a page raises while it is open.

## Keeping background apps alive

The app is only worth having if a tool you are not looking at still tells you something
arrived. Getting there took three wrong turns, and each one is why the code looks as it
does:

1. **Hiding the inactive views.** The obvious way to switch apps, and it kills them:
   WebKit reads a hidden `NSView` as a page that is not visible, throttles its timers and
   eventually suspends it. Now nothing is hidden — every view keeps its full size and stays
   in the window, and the active one is simply ordered on top. Sibling views covering each
   other is not something WebKit tracks.

2. **Telling the page it was hidden.** The idea was that a page believing itself hidden
   would notify rather than stay quiet. It backfired: told it was hidden, Gmail throttled
   its *own* syncing, and its unread count sat unchanged for two and a half minutes. The
   spoof is gone. Pages are told nothing about visibility.

3. **Assuming that was enough.** It was not. A backgrounded page keeps running its timers
   but loses the long-lived connection its updates arrive on, and WKWebView offers no
   equivalent of Electron's `backgroundThrottling: false`. So every background app is
   **poked every 45 seconds** with the events a page uses to catch up when you return to a
   tab. It fetches as if you had just looked at it, and keeps its state — unlike a reload,
   which would throw away a half-written reply.

**Measured end to end:** Gmail behind Odoo went from 155 to 157 unread without being
touched, and the app raised `Gmail / 1 new`.

### Unread counting

Notifications do not come from the site's own notification code, because Gmail declines to
raise one while it believes you are looking at it — and with the visibility spoof gone, it
always believes that. They come from the **unread count in the title**: `Inbox (12)`,
`(3) Chat`. Every one of these tools publishes it, it cannot be switched off, and it never
moves into a service worker this app cannot reach. A rise while the app is not the one on
screen raises a banner; a fall is you reading things, and is not news.

The site's own notifications still work when they fire — both paths feed the same channel.

### Counting what was missed

Each rise in an app's unread count while you are elsewhere adds to a per-app tally shown
against its name in the nav — and on the rail, as a dot on the icon. Looking at an app is
the only thing that clears it; nothing else does, because nothing else means you have seen
it. Counts live in memory rather than `apps.json`: a restart reloads every app anyway, and
a number that survived would be a claim the app can no longer support.

## App marks

Each app is drawn as its brand glyph in white on a round tile of its own colour, from
**Simple Icons** (CC0, ~3,400 marks). A host with no glyph gets its initial in the same
tile, so a private tool sits in the row looking like it belongs.

This replaced Google's favicon service, which was wrong as often as it was right: it
returned a sign-in page's icon for anything behind a login, nothing at all for a private
host, and cached both answers past any way of asking again. A "refresh icons" button could
not fix that, because the staleness was not local.

Each tile carries the **brand's own colour**, which Simple Icons publishes alongside the
glyph — Gmail red, Drive blue, Chat green, Gemini violet. The glyph is drawn black or
white depending on the tile's perceived brightness, because brand colours are chosen to
look right rather than to carry a white mark: GitHub and Notion are near-black, Snapchat
is pure yellow, and a fixed white glyph loses one end of that range.

A host with no mark falls back to a Tailwind 500 chosen by hashing the host, so it is
still stable — you find things by their colour, and one that moved every launch would be
worse than none.

The build turns Simple Icons' 15MB of SVG files into one 4.5MB map of slug to path and
hex,
written to `public/` so it is fetched once at runtime rather than parsed into the JS
bundle at every start. The bundle stays at 233KB. The map is generated by `npm run icons`,
which `npm run build` runs, so it is never committed and never stale.

Matching a host to a glyph tries the registrable name first — `example.odoo.com` is Odoo,
not Aputure — because a self-hosted tool is nearly always on a subdomain of its vendor. A
short table handles the ones a domain cannot answer, which is most of Google: `google.com`
says only that it is Google, not which of a dozen products.

## The window

There is no title bar and no toolbar, so in a normal window the shell keeps a 6px margin
around itself, and the traffic lights are pushed in to sit within it rather than crowding
the corner — which also sets the depth of the nav's drag strip.

An app's corners are rounded on its own layer, not by the container around it: an app is a
native view sitting on top rather than something the shell lays out, so a `rounded-xl` on
its parent does nothing and it overhangs the curve. Only the right pair is rounded; the
left edge butts against the nav, and rounding it would cut a notch out of the middle of
the window.

The margin That margin is the only part of the window that is not a web page, and
therefore the only place left to grab it by. Full screen has no use for it and gets the
room back.

## Dialogs

An app's webview is a native view that paints above the shell, so a dialog cannot simply
sit on a higher z-index — the app has to be moved out of the way first. Once it is moved
there is nothing left behind the dialog to look at, so a still is taken on the way out with
`takeSnapshotWithConfiguration` and shown blurred behind it.

The snapshot is deliberately 640px wide: it is going behind a 16px blur. It is also taken
on a blocking worker rather than the calling thread — its completion handler runs on the
main thread, and waiting for it *there* deadlocks until the timeout and returns nothing
every time.

## Zoom

Per app, on a fixed ladder so ⌘0 returns to exactly 100% rather than to whatever a
repeated multiplier happened to leave behind. The shortcuts are menu-bar accelerators, not
a key listener: the keystroke has to work while an app's own webview has focus, and that
webview is a remote page this app deliberately cannot script for input.

## Hiding elements

Anything on a page can be right-clicked and hidden. The injected script owns a stylesheet
of `display: none` rules, re-added when a single-page app rewrites `<head>`. Selectors are
per app and stored in `apps.json`, editable and reversible in Settings.

The selector generator prefers an id, then up to two stable-looking classes per level,
then position — skipping classes that look hashed or numbered, because those change on
every deploy. A selector that stops matching hides nothing; it never hides the wrong thing.

## Out of scope

- Windows and Linux.
- Tabs, history, bookmarks, an address bar — it is not a general browser.
- Per-app session isolation for multiple accounts on one service. One shared jar for now.
- Automatic background cookie re-sync.
- Notifications, badges and unread counts.