docs: add Phase 1 MVP design
Captures the brainstormed design for the two-window overlay app: architecture, frontend structure, Rust backend split, persistence model, click-through escape hatch, and the manual verification checklist that defines "Phase 1 done." Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Michael Chihlas
261
docs/plans/2026-05-08-browserlay-mvp-design.md
Normal file
261
docs/plans/2026-05-08-browserlay-mvp-design.md
Normal file
@@ -0,0 +1,261 @@
|
|||||||
|
# Browserlay Phase 1 (MVP) — Design
|
||||||
|
|
||||||
|
Date: 2026-05-08
|
||||||
|
Status: Approved, ready for implementation planning
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Ship a Windows desktop app that creates a translucent, always-on-top browser overlay. The user types a URL, clicks Open, and gets a frameless transparent window pinned over their other apps. Real-time opacity, always-on-top, and click-through controls. A global hotkey (`Ctrl+Alt+Space`) is the recovery path out of click-through mode.
|
||||||
|
|
||||||
|
## Stack (already scaffolded)
|
||||||
|
|
||||||
|
- Tauri 2.x (Rust backend, single process)
|
||||||
|
- React 19 + TypeScript + Vite
|
||||||
|
- Tailwind CSS v4 (dark-mode only, charcoal palette via CSS variables)
|
||||||
|
- `lucide-react` for icons
|
||||||
|
- Bundle id `com.chihlas.browserlay`
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
Two top-level webview windows in a single Tauri process.
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────┐ ┌──────────────────────────────┐
|
||||||
|
│ Control Window (`main`) │ │ Overlay Window (`overlay`) │
|
||||||
|
│ React app, Tailwind v4 │ │ Tauri WebviewWindow │
|
||||||
|
│ │ spawns │ • frameless │
|
||||||
|
│ • URL input │ ───────►│ • transparent │
|
||||||
|
│ • Opacity slider │ │ • alwaysOnTop=true │
|
||||||
|
│ • AOT toggle │ │ • loads <user URL> directly │
|
||||||
|
│ • Click-through toggle │ drives │ • no React shell on top │
|
||||||
|
│ • Open / Close button │ ◀──────►│ │
|
||||||
|
└─────────────────────────────┘ └──────────────────────────────┘
|
||||||
|
│ ▲
|
||||||
|
│ direct calls via WebviewWindow.getByLabel │
|
||||||
|
│ .setOpacity / .setAlwaysOnTop / │
|
||||||
|
│ .setIgnoreCursorEvents │
|
||||||
|
└────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
┌──────────────────────────────────────┐
|
||||||
|
│ Global shortcut (Ctrl+Alt+Space) │
|
||||||
|
│ Rust handler → toggles click-through│
|
||||||
|
│ + opacity pulse on overlay window │
|
||||||
|
└──────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key decisions** (made during brainstorming):
|
||||||
|
|
||||||
|
1. Overlay creation lives in JS via `WebviewWindow`. No Rust command for window creation.
|
||||||
|
2. State management: Zustand from day one (anticipating Phase 2 presets/hotkeys).
|
||||||
|
3. Persistence: debounced (~300ms) writes to `tauri-plugin-store` on every change.
|
||||||
|
4. Overlay loads the external URL directly. No in-overlay React shell or toolbar in Phase 1 — controls live entirely on the control panel + the global hotkey. (In-overlay toolbar deferred to Phase 2.)
|
||||||
|
5. Click-through hotkey is **toggle** (press to flip), with **opacity-pulse** feedback (~180ms dip and restore).
|
||||||
|
6. URL validation: forgiving (prepends `https://` if scheme missing) but only `http`/`https` allowed. `tauri://`, `file://`, `javascript:`, `data:` rejected.
|
||||||
|
7. Click-through hotkey handler lives in Rust, not JS — global shortcut runs regardless of focus and Rust is the reliable handler path.
|
||||||
|
|
||||||
|
## Frontend structure
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── main.tsx # React entry, mounts <App />
|
||||||
|
├── App.tsx # Layout shell only
|
||||||
|
├── index.css # Tailwind v4 import + :root design tokens
|
||||||
|
├── components/
|
||||||
|
│ ├── ControlPanel.tsx # Top-level form layout
|
||||||
|
│ ├── UrlField.tsx # URL input + validation feedback
|
||||||
|
│ ├── OpacitySlider.tsx # Slider + numeric readout
|
||||||
|
│ ├── ToggleRow.tsx # Reusable toggle (label + switch + hint)
|
||||||
|
│ ├── OpenOverlayButton.tsx # Primary action (Open / Close)
|
||||||
|
│ └── StatusBar.tsx # Footer: hotkey hint, error states
|
||||||
|
├── hooks/
|
||||||
|
│ └── useClickThroughSync.ts# Subscribes to Rust 'click-through-toggled' event
|
||||||
|
├── lib/
|
||||||
|
│ ├── store.ts # Zustand store
|
||||||
|
│ ├── overlay.ts # Wrapper over WebviewWindow APIs
|
||||||
|
│ ├── url.ts # normalizeUrl + isAllowedUrl
|
||||||
|
│ └── persist.ts # tauri-plugin-store load/save with debounce
|
||||||
|
└── types/
|
||||||
|
└── overlay.ts # OverlayState, OverlayActions
|
||||||
|
```
|
||||||
|
|
||||||
|
### Zustand store
|
||||||
|
|
||||||
|
```ts
|
||||||
|
type OverlayState = {
|
||||||
|
url: string;
|
||||||
|
opacity: number; // 0.1 – 1.0
|
||||||
|
alwaysOnTop: boolean;
|
||||||
|
clickThrough: boolean;
|
||||||
|
isOpen: boolean; // overlay window currently exists
|
||||||
|
urlError: string | null;
|
||||||
|
};
|
||||||
|
|
||||||
|
type OverlayActions = {
|
||||||
|
setUrl: (raw: string) => void;
|
||||||
|
setOpacity: (v: number) => void;
|
||||||
|
setAlwaysOnTop: (v: boolean) => void;
|
||||||
|
setClickThrough: (v: boolean) => void;
|
||||||
|
_setClickThroughFromBackend: (v: boolean) => void; // silent setter, no apply
|
||||||
|
openOverlay: () => Promise<void>;
|
||||||
|
closeOverlay: () => Promise<void>;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### `lib/overlay.ts` (single Tauri-API boundary)
|
||||||
|
|
||||||
|
```
|
||||||
|
openOverlay(url, {opacity, alwaysOnTop, clickThrough}): Promise<void>
|
||||||
|
closeOverlay(): Promise<void>
|
||||||
|
applyOpacity(v): Promise<void>
|
||||||
|
applyAlwaysOnTop(v): Promise<void>
|
||||||
|
applyClickThrough(v): Promise<void>
|
||||||
|
pulseOpacity(target): Promise<void>
|
||||||
|
```
|
||||||
|
|
||||||
|
Each function looks up `WebviewWindow.getByLabel('overlay')`. If null, no-op — store still reflects state and reopening picks it up.
|
||||||
|
|
||||||
|
### Live wiring
|
||||||
|
|
||||||
|
Zustand subscribers (or `useEffect` per controllable property) watch the store and call the matching `applyX` function whenever values change. UI changes the store; store changes propagate.
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
|
||||||
|
`setUrl(raw)` runs `normalizeUrl` → `isAllowedUrl`, sets `url` and `urlError` together. Open button disabled when `urlError` set or field empty.
|
||||||
|
|
||||||
|
## Rust backend
|
||||||
|
|
||||||
|
```
|
||||||
|
src-tauri/src/
|
||||||
|
├── main.rs # Unchanged — calls browserlay_lib::run()
|
||||||
|
├── lib.rs # Plugin registration + builder
|
||||||
|
└── commands/
|
||||||
|
├── mod.rs
|
||||||
|
└── overlay.rs # toggle_click_through + helpers
|
||||||
|
```
|
||||||
|
|
||||||
|
### Plugin registration (in `lib.rs`)
|
||||||
|
|
||||||
|
- `tauri-plugin-store`
|
||||||
|
- `tauri-plugin-window-state`
|
||||||
|
- `tauri-plugin-global-shortcut` (with Rust handler)
|
||||||
|
- `tauri-plugin-opener` (already there from scaffold; keep)
|
||||||
|
|
||||||
|
### Click-through toggle (`commands/overlay.rs`)
|
||||||
|
|
||||||
|
A private `do_toggle(app: &AppHandle)` function is the single implementation. Both the global-shortcut handler and the `toggle_click_through` Tauri command delegate to it.
|
||||||
|
|
||||||
|
`do_toggle` flow:
|
||||||
|
|
||||||
|
1. Look up overlay window by label. If absent → emit `click-through-no-overlay` event, return.
|
||||||
|
2. Read current `ignore_cursor_events` state.
|
||||||
|
3. Flip via `set_ignore_cursor_events(!current)`.
|
||||||
|
4. Read current opacity. Pulse: `set_opacity(0.4)` → `tokio::time::sleep(180ms)` → `set_opacity(prev)`.
|
||||||
|
5. Emit `click-through-toggled` event with `{ clickThrough: bool }` payload.
|
||||||
|
|
||||||
|
The control panel's `useClickThroughSync` listens to that event and calls `_setClickThroughFromBackend`, which updates the store *without* re-triggering the apply effect (avoiding ping-pong).
|
||||||
|
|
||||||
|
### Capabilities
|
||||||
|
|
||||||
|
`capabilities/default.json` — control window:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"windows": ["main"],
|
||||||
|
"permissions": [
|
||||||
|
"core:default",
|
||||||
|
"core:webview:allow-create-webview-window",
|
||||||
|
"core:window:allow-set-opacity",
|
||||||
|
"core:window:allow-set-always-on-top",
|
||||||
|
"core:window:allow-set-ignore-cursor-events",
|
||||||
|
"core:window:allow-close",
|
||||||
|
"store:default",
|
||||||
|
"global-shortcut:allow-register",
|
||||||
|
"global-shortcut:allow-unregister",
|
||||||
|
"global-shortcut:allow-is-registered"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`capabilities/overlay.json` — overlay window only, minimal/empty allowlist. The loaded external page must not be able to call Tauri APIs.
|
||||||
|
|
||||||
|
> Exact permission identifiers will be reconciled against current Tauri 2 docs at implementation time.
|
||||||
|
|
||||||
|
## Persistence
|
||||||
|
|
||||||
|
### `tauri-plugin-store` (user prefs)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"url": "https://twitch.tv/somechannel",
|
||||||
|
"opacity": 0.65,
|
||||||
|
"alwaysOnTop": true,
|
||||||
|
"clickThrough": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- On control-window mount: `lib/persist.ts` reads store and hydrates Zustand. Empty store → defaults.
|
||||||
|
- On any store change: debounced 300ms write back. `isOpen` and `urlError` not persisted.
|
||||||
|
- **Not** using Zustand persist middleware — using `tauri-plugin-store` directly to avoid hydration race.
|
||||||
|
|
||||||
|
### `tauri-plugin-window-state` (geometry)
|
||||||
|
|
||||||
|
Tracks position/size for both `main` and `overlay` automatically. `alwaysOnTop` would be saved by this plugin too, but our store is authoritative — on overlay create we explicitly call `setAlwaysOnTop(store.alwaysOnTop)` after geometry restore.
|
||||||
|
|
||||||
|
### First-run defaults
|
||||||
|
|
||||||
|
- `url: ""` (Open disabled until typed)
|
||||||
|
- `opacity: 1.0`
|
||||||
|
- `alwaysOnTop: true`
|
||||||
|
- `clickThrough: false`
|
||||||
|
|
||||||
|
### First-open overlay placement
|
||||||
|
|
||||||
|
Top-right of primary monitor, 800×600, 24px margin. After that, `tauri-plugin-window-state` remembers wherever the user dragged it.
|
||||||
|
|
||||||
|
## Click-through escape hatch
|
||||||
|
|
||||||
|
The safety-critical piece.
|
||||||
|
|
||||||
|
- Hotkey: `Ctrl+Alt+Space`. Hardcoded in Phase 1.
|
||||||
|
- Registered at app startup via `tauri-plugin-global-shortcut` in Rust.
|
||||||
|
- Handler delegates to `do_toggle` (above).
|
||||||
|
- If overlay isn't open: no-op + brief toast on control panel.
|
||||||
|
- If hotkey registration fails (conflict with another app): surface in StatusBar — "⚠ Hotkey unavailable — click-through escape disabled". **Silent failure is the worst outcome; we explicitly surface this.**
|
||||||
|
- Phase 2 will add configurable hotkeys.
|
||||||
|
|
||||||
|
## Testing & definition of done
|
||||||
|
|
||||||
|
No automated tests in Phase 1 — most logic is OS integration where mocks would test mocks. Manual verification:
|
||||||
|
|
||||||
|
1. Cold start: only control window opens.
|
||||||
|
2. URL validation: `twitch.tv/foo` → normalized; `not a url` → error + Open disabled; `tauri://`, `javascript:` rejected.
|
||||||
|
3. Overlay opens frameless, transparent, top-right of primary monitor.
|
||||||
|
4. Opacity slider 1.0 → 0.3 fades overlay in real time.
|
||||||
|
5. AOT off → other windows can cover overlay; AOT on → raised.
|
||||||
|
6. Click-through off: clicks on overlay scroll/click the loaded page.
|
||||||
|
7. Click-through on: clicks pass through to apps underneath.
|
||||||
|
8. With click-through on and our windows unfocused, `Ctrl+Alt+Space` flips it off; overlay opacity blinks; control toggle reflects new state.
|
||||||
|
9. Persistence: change URL/opacity/toggles → close → reopen → restored.
|
||||||
|
10. Geometry: drag overlay → close → reopen → position/size restored.
|
||||||
|
|
||||||
|
Plus safety-net checks:
|
||||||
|
|
||||||
|
- Hotkey conflict surfaces a warning rather than failing silently.
|
||||||
|
- Closing the overlay via taskbar X recovers correctly on next apply.
|
||||||
|
|
||||||
|
**Ship criteria**:
|
||||||
|
|
||||||
|
- All 10 checks pass on Windows 11.
|
||||||
|
- `npm run tauri build` produces a working installer.
|
||||||
|
- README updated: what the app does, dev setup, build, hotkey documented.
|
||||||
|
- `main` branch on origin (Gitea) tagged `v0.1.0`.
|
||||||
|
|
||||||
|
## Out of scope for Phase 1
|
||||||
|
|
||||||
|
Tray icon, presets, configurable hotkeys, edge snap, multi-monitor placement UI, in-overlay toolbar, auto-update. All deferred to Phase 2.
|
||||||
|
|
||||||
|
## Workflow notes
|
||||||
|
|
||||||
|
- Conventional Commits (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`).
|
||||||
|
- Frequent commits per meaningful chunk.
|
||||||
|
- Push to `origin/main` after user approves each chunk (will check before pushing the first few times — pushes are externally visible).
|
||||||
Reference in New Issue
Block a user