open-design/design-browser-task-handoff.md

# Design Browser Task Handoff

Generated from this chat session on 2026-05-30.

## Repository

- Worktree: `/Users/pftom/.superset/worktrees/d3aab1a3-c696-403f-9692-7e5bc2dfa1f3/accidental-bolt`
- Product area: OpenDesign `Design Files` workspace, embedded browser module, desktop host bridge, browser-harness task entry.

## User Queries, In Order

1. Initial feature request:

   > `[Image #1]` 在 design files 那一排支持一个 plus icon, 增加一个类似 `[Image #2]` 的 browser 模块,然后可以打开浏览器, 支持 `[Image #3]` 如图的能力, 包括上一页/下一页/刷新/输入地址栏/支持展示/搜索和选择历史地址打开各种能在浏览器打开的文件如本地文件/各种服务文件/网站 `[Image #4]` 如图也支持一些 clear/open in browser /等截图的能力
   >
   > 参考 https://github.com/superset-sh/superset 代码, 里面已经实现了完整的能力了,直接搬过来,确保在 open-design 里面完美适配和使用, 就像内嵌了一个真实的浏览器, 然后那个地址栏 + 浏览器空白页可以给大量的推荐网址, 方便做设计的参考,做的好看/酷/世界级设计
   >
   > 比如 svg 的 https://thesvg.org/
   > https://unsplash.com/ 图片的
   > https://motionsites.ai/ 各种高级网站参考 https://motion.page/showcase/
   > https://styles.refero.design/ 借鉴设计风格

2. Add blank-page recommendation:

   > 浏览器空白页网址继续添加:
   >
   > - https://brandfetch.com/

3. Agent/browser-harness integration direction:

   > 然后理论上应该结合 agent 的能力 和 https://github.com/browser-use/browser-harness , 以及结合对 browser 的控制和能力, 增加一些快捷的入口或者操作, 能够让用户轻松通过 browser use（browser harness）能够把这些网站的内容搞下来然后应用在用户自己的设计 artifacts 里面, 这样能够极大的增长用户的设计水准

4. User supplied repo instructions:

   > `# AGENTS.md instructions for /Users/pftom/.superset/worktrees/d3aab1a3-c696-403f-9692-7e5bc2dfa1f3/accidental-bolt`
   >
   > The full root `AGENTS.md` content was pasted into the chat. Important for next agent: follow the real repo `AGENTS.md`, plus `apps/AGENTS.md` and `packages/AGENTS.md` before touching those directories.

5. Add motion site:

   > 网址增加 https://gsap.com/ 做动效的

6. Add transition and font references:

   > 网址添加 https://transitions.dev/ 过渡动画/ 以及字体:https://fonts.google.com/

7. Add text animation reference:

   > 文字动画:https://animography.net/

8. Add resource collection:

   > 各种集合站和资源:https://toolfolio.io/

9. Add hand-drawn image reference:

   > 手绘图像: https://www.whirrls.com/

10. Add startup inspiration reference:

    > 各种顶尖的创业公司: https://startups.gallery/

11. Add dot-map visualization reference:

    > 世界点状图:https://www.worldindots.com/

12. Add design resource URL:

    > 添加 网址: getdesign.md

13. Verification request:

    > check 一下整体能力真的实现和跑通了吗

14. Handoff request:

    > 吧我这个 task/会话所有的历史的 query 都帮我提取出来放到一个文件里, 我要 handoff 任务给下一个 agent

## Derived Acceptance Requirements

- Add a `+` icon in the Design Files tab row.
- `+` opens a module menu with a Browser module.
- Browser module opens as a workspace tab.
- Browser supports back, forward, refresh, hard reload, address/search input, history suggestions, and reference-site suggestions.
- Browser can open websites and local/service URLs where supported by the embedded runtime.
- Browser menu supports:
  - Take Screenshot
  - Hard Reload
  - Copy URL
  - Open in Browser
  - Clear Browsing History
  - Clear Cookies
  - Clear All Data
- Blank page includes curated design-reference recommendations:
  - https://thesvg.org/
  - https://unsplash.com/
  - https://motionsites.ai/
  - https://motion.page/showcase/
  - https://styles.refero.design/
  - https://brandfetch.com/
  - https://gsap.com/
  - https://transitions.dev/
  - https://fonts.google.com/
  - https://animography.net/
  - https://toolfolio.io/
  - https://www.whirrls.com/
  - https://startups.gallery/
  - https://www.worldindots.com/
  - https://getdesign.md/
- Add browser-use/browser-harness oriented shortcut/task entry so a user can extract page screenshots/design language/assets and apply them to OpenDesign artifacts.

## Current Implementation Status

Files changed so far:

- `apps/web/src/components/DesignBrowserPanel.tsx`
- `apps/web/src/components/FileWorkspace.tsx`
- `apps/web/src/components/Icon.tsx`
- `apps/web/src/styles/workspace/design-files.css`
- `apps/web/src/styles/workspace/drawer.css`
- `apps/desktop/src/main/index.ts`
- `apps/desktop/src/main/preload.cts`
- `apps/desktop/src/main/runtime.ts`
- `apps/desktop/tests/main/preload-host-boundary.test.ts`
- `apps/packaged/tests/desktop-url-allowlist.test.ts`
- `packages/host/src/index.ts`
- `packages/host/src/testing.ts`
- `packages/host/tests/index.test.ts`

Implemented behavior:

- Design Files tab strip now has a `+` button.
- `+` menu can open a local `Browser` tab.
- Browser panel has address input, suggestions, history persistence, back/forward/reload controls, menu actions, reference cards, screenshot saving, page brief saving, and browser-harness task saving.
- Desktop runtime enables Electron `webviewTag` only for the main window and validates embedded browser startup URLs.
- Desktop host bridge exposes browser data clearing for the dedicated browser partition.
- Host package has helper `clearHostBrowserData`.

## Verification Status

Passed:

- `pnpm --filter @open-design/web typecheck`
- `pnpm --filter @open-design/desktop typecheck`
- `pnpm --filter @open-design/host typecheck`
- `pnpm --filter @open-design/host test`
- `pnpm --filter @open-design/packaged test -- desktop-url-allowlist`
- Direct targeted web tests from `apps/web`:
  - `pnpm exec vitest run -c vitest.config.ts tests/components/FileWorkspace.test.tsx tests/components/FileWorkspace.design-system.test.tsx`
  - Result: 2 files passed, 38 tests passed.
- Root `pnpm typecheck` completed successfully. It emitted existing landing-page warnings/hints but no errors.

Not fully verified:

- `pnpm guard` did not run in this sandbox because `tsx` failed to create its IPC pipe with `EPERM`.
- `pnpm tools-dev run web --daemon-port 17456 --web-port 17573` did not start in this sandbox for the same `tsx` IPC pipe `EPERM`.
- No final visual/browser verification was completed because local runtime startup was blocked by the sandbox.

Observed unrelated test friction:

- Running `pnpm --filter @open-design/web test -- FileWorkspace` or passing paths through the package script unexpectedly exercised the full web test set. It hit unrelated failures/timeouts in `SettingsDialog.execution.test.tsx` or `ExamplesTab.test.tsx`.
- Direct `pnpm exec vitest ...` from `apps/web` correctly scoped to FileWorkspace and passed.

## Next Agent Suggested Checks

- Run `pnpm guard` outside this sandbox or in an environment where `tsx` can create its local IPC pipe.
- Start `pnpm tools-dev run web --daemon-port <free> --web-port <free>` and visually check:
  - Design Files row shows the `+` icon.
  - `+` opens Browser.
  - Blank browser page shows all requested URLs.
  - Address input navigates to at least one external site and one local/service URL.
  - History suggestions appear after navigation.
  - Browser menu actions render and enabled/disabled states make sense.
  - In desktop runtime, webview loads and screenshot/page brief/task save into Design Files.

## Completion Pass — Workflow + Runtime Verification (2026-05-30, follow-up agent)

### Static audit (multi-agent workflow)

Ran a 5-phase audit/verify/implement workflow over all acceptance requirements. Result: **42/45 requirements met, 0 defects** in static analysis; remaining 3 are partial/judgment (i18n debt, CLI dual-track N/A for an interactive render surface, CSS global-vs-module precedent). The workflow added `apps/web/tests/components/DesignBrowserPanel.test.tsx` (34 cases over the pure helpers — `normalizeBrowserAddress` every branch, history round-trip, harness/brief markdown, etc.) and made those helpers named exports.

### Real runtime verification (computer-use against the live Electron desktop app)

Drove the running desktop runtime via `pnpm tools-dev inspect desktop eval/screenshot`. Confirmed in the real app: `+` → add-menu → **Browser** tab → `DesignBrowserPanel` renders; all **15** reference URLs across MOTION/ASSETS/SYSTEMS; `webviewTag` enabled (`WebViewElement`); host bridge `__od__` exposes `browser.clearData`; navigation commits; the embedded `<webview>` loads and **paints** a real page (`example.com` → `<h1>Example Domain</h1>`, 487×117 layout); and `webview.capturePage()` returns a real 51 KB PNG (the "Take Screenshot" action works).

### Three runtime-only bugs found and fixed (invisible to static/JSDOM checks)

All in `apps/web/src/components/DesignBrowserPanel.tsx`:

1. **`allowpopups` React warning** — bare boolean JSX attr tripped "Received `true` for a non-boolean attribute" when the webview branch mounts. Fixed by setting `allowpopups` imperatively in the ref callback.
2. **`dom-ready` crash** — `updateNavigationState` (and the reload button) called `canGoBack()`/`canGoForward()`/`isLoading()`/`reload()` before the webview attached, throwing "The WebView must be attached…". Guarded with try/catch (matching the existing `safeGetWebviewUrl/Title` pattern).
3. **`ERR_ABORTED (-3)` blank page (critical / made the feature unusable)** — `src={currentUrl}` + a `did-navigate` handler that wrote the committed (trailing-slash) URL back into `currentUrl` caused Electron to re-navigate mid-load and abort it, leaving a blank pane. Fixed by splitting state into `loadUrl` (drives `src`, changes only on user navigation) and `currentUrl` (address bar / history, synced from webview events). Covered by a red→green regression test: `apps/web/tests/components/DesignBrowserPanel.webview.test.tsx`.

### Final verification (all green after fixes)

`pnpm guard` 33 · web `typecheck` clean · desktop `typecheck` clean · web tests **74** (34 pure + 2 webview regression + FileWorkspace + design-system) · desktop **73** · host **14** · packaged **111**. Runtime re-drive on the fixed code: page paints, no error overlays.