feat(browser): replace the preview proxy with a real browser panel and an agent web tool (#2883)

The preview panel worked by proxying a dev server through OpenChamber's own origin and rewriting the HTML that came back. Anything the rewriter did not anticipate broke, and pages that refuse to be embedded never loaded at all. This deletes the proxy (-1604 lines and its tests) and merges the preview and browser panels into one surface backed by a real Chromium view. What the panel is now - A `<webview>` in its own session partition: logins and cookies persist, hot reload works because nothing is rewritten, DevTools are one click away. - Annotation: pick one element, drag a region, or draw freehand, write a note, and it reaches chat with a screenshot of the visible page with the marks on it. - Toolbar: hard reload, page zoom, device sizes, a light/dark switch that applies to the page rather than the app, and cookie/cache clearing scoped to the panel alone. - Several pages at once, each tab showing the page's own favicon, and an address bar that suggests pages already visited in this project. - Dev servers are listed from what is actually listening on the machine, checked against what a project announced, so a server is offered no matter how it was started. One that is still starting is waited for instead of failing. Remote dev servers The desktop app binds a local port and pipes raw bytes to the OpenChamber host over the existing authenticated connection, so the page keeps its own origin at the root of its own host. The reachable set is exactly what discovery reports and is re-checked per connection, so an authenticated client cannot dial arbitrary local services on the host. Links and redirects to another loopback port stay on the machine that served the page. A tunnel that cannot be opened is reported; it is never replaced by the plain loopback URL, which would answer from the user's own machine under a remote address. Agent control Browser actions are a separate `openchamber_web` tool: open, snapshot, click, type, scroll, inspect computed styles, resize between mobile/tablet/desktop, and capture a screenshot into `.openchamber/screenshots/` in the project. The existing `openchamber` tool keeps sessions, worktrees and scheduled tasks. Each has its own setting in the new Settings -> General -> OpenChamber Tools section, and the plugin is not injected at all when both are off. Capability belongs to the connected client, not to configuration: a client declares on its event stream that it can drive a page, which only a Chromium host does. Exactly one client performs each request — it claims the request before acting, and the first claim wins — because deciding by whose result arrives first would be too late for a click that already happened. No client listening is answered immediately with an explanation rather than a timeout. Runtime boundaries Web tabs get a plain iframe that can display a page but not inspect one. The VS Code extension no longer offers the surface at all, since nothing that makes the panel worth having works there. Mobile is unaffected. Native boundary Camera, microphone, location and device-picker requests from panel pages are denied — Electron grants them by default when no handler is set, and the panel loads whatever address the user types. Page capture, appearance emulation and storage clearing verify that their target belongs to the panel's own session instead of trusting a web-contents id from the renderer. Persisted state Stored `preview` tabs migrate to `browser` (v13 -> v14). Context panel tab limits are now per surface, so filling one surface no longer evicts another's tabs. Address history is stored per project and per runtime. Documentation `preview.mdx` and `desktop-browser.mdx` rewritten across all locales, the agent tool settings path corrected, new `DOCUMENTATION.md` for the browser-control broker and the dev tunnel, and the `ui-api-decoupling` skill updated where it still described the deleted proxy.
2026-08-13 22:44:13 +03:00
parent 50613bb170
commit a5aa32446d
151 changed files with 10431 additions and 5587 deletions
@@ -28,7 +28,7 @@ description: 에이전트가 채팅에서 OpenChamber 세션, worktree, 예약

 ## 도구 켜기 또는 끄기

-**설정 → 일반 → OpenCode CLI**를 열고 **에이전트 제어 도구**를 변경한 다음 **Save + Reload**를 선택하세요. 관리형 OpenCode 서버가 다시 시작된 후 설정이 적용됩니다.
+**설정 → 일반 → OpenChamber 도구**를 열고 **에이전트 제어 도구**를 변경하세요. 설정은 관리형 OpenCode 서버가 다시 시작되면 적용되며, OpenChamber가 **Apply & Restart** 로 안내합니다.

 OpenChamber가 `OPENCODE_HOST` 또는 skip-start를 통해 외부 OpenCode 서버에 연결된 경우와 VS Code 확장에서는 이 도구를 사용할 수 없습니다. OpenChamber의 관리형 OpenCode 서버를 사용하는 데스크톱 및 웹 설치에서는 자동으로 지원됩니다.

@@ -37,3 +37,4 @@ OpenChamber가 `OPENCODE_HOST` 또는 skip-start를 통해 외부 OpenCode 서
 - [예약 작업](/ko/scheduled-tasks/)
 - [Worktree 세션](/ko/worktrees/)
 - [세션 목표](/ko/session-goals/)
+- [브라우저 패널](/ko/desktop-browser/) — 페이지를 보고 조작하는 OpenChamber Web 도구
@@ -1,22 +1,53 @@
 ---
-title: 데스크톱 브라우저
-description: 검사 및 콘솔 캡처 기능과 함께 데스크톱 앱 안에서 임의의 페이지를 탐색하세요.
+title: 브라우저 패널
+description: 앱 안에서 아무 페이지나 열고 주석을 달며 에이전트가 조작하게 합니다.
 ---

-# 데스크톱 브라우저
+# 브라우저 패널

-데스크톱 앱에는 내장 브라우저가 있어 채팅 바로 옆에서 임의의 페이지를 열고, 요소를 가리켜 질문하고, 페이지의 콘솔을 캡처할 수 있습니다. 앱 헤더의 지구본 버튼에서 엽니다.
+브라우저 패널은 채팅 바로 옆에 아무 페이지나 엽니다. 앱 헤더의 지구본 버튼으로 여세요.

-> 데스크톱 브라우저는 **데스크톱 전용** 기능입니다. 웹에서는 [미리보기](/ko/preview/) 패널이 로컬 개발 서버에 대해 동일한 검사 및 콘솔 도구를 제공합니다.
+데스크톱 앱에서는 진짜 브라우저입니다. 로그인 상태가 유지되고 핫 리로드가 동작하며 개발자 도구도 클릭 한 번이면 열립니다. 브라우저 탭에서도 페이지를 보여줄 수는 있지만 내부를 들여다볼 수는 없습니다. 아래 주석 도구는 데스크톱 전용입니다.

-## 검사 및 주석
+여기서 연 페이지는 카메라, 마이크, 위치를 사용할 수 없습니다. 그런 요청은 거부됩니다.

-**inspect**를 켜고 페이지의 임의 요소를 클릭합니다. OpenChamber가 그것이 무엇인지, 스타일, 위치, 스크린샷을 담은 메모를 캡처해 채팅 메시지에 첨부합니다. 에이전트에게 "바로 여기 이 요소"라고 알리는 가장 빠른 방법입니다.
+## 도구 모음

-## 콘솔 캡처
+주소창은 이 프로젝트에서 열었던 페이지를 기억해 두었다가 입력하는 동안 제안합니다. 주소의 일부나 페이지 제목의 일부와 맞춰 봅니다. 화살표 키로 목록을 이동하고, Enter로 선택한 항목을 열고, 행의 버튼으로 목록에서 지웁니다.

-브라우저는 페이지의 콘솔 출력(오류, 경고, 로그)을 수집하므로 개발자 도구를 열지 않고도 필터링하여 읽을 수 있습니다.
+그 옆에는 **새로 고침**이 있고, 변경이 도무지 반영되지 않을 때 캐시를 무시하는 **강력 새로 고침**, 그리고 페이지만 확대·축소하는 확대 조절이 있습니다.

-## 관련 항목
+**쿠키 지우기**와 **캐시 데이터 지우기**는 이 패널에만 적용됩니다. OpenChamber 세션이나 다른 창은 그대로입니다.

- [Preview & Dev Servers](/ko/preview/) — 로컬 개발 서버에 대한 동일한 도구
+## 페이지에 주석 달기
+
+**주석** 을 누르면 페이지 위에 세 가지 도구가 있는 막대가 나타납니다.
+
+- **요소** — 요소를 클릭합니다. 다른 요소를 클릭하면 선택이 옮겨가고, 같은 요소를 다시 클릭하면 해제됩니다.
+- **영역** — 여러 요소에 걸친 이야기를 할 때는 해당 부분을 드래그해 감쌉니다.
+- **그리기** — 페이지 위에 자유롭게 스케치합니다.
+
+표시 옆에 나타나는 입력란에 원하는 내용을 적고 **첨부** 를 누르세요. Enter 로도 됩니다. 채팅 메시지에 표시한 모든 것, 남긴 메모, 표시 중인 페이지에 표시를 그려 넣은 스크린샷이 담긴 카드가 붙습니다. 위치를 설명하는 대신 "이 버튼, 조금 더 둥글게"라고 말하면 됩니다.
+
+페이지 자체는 변경되지 않습니다. 주석은 있는 것을 표시할 뿐입니다. `Esc` 로 취소하고 도구 막대를 닫습니다.
+
+## 에이전트에게 조작 맡기기
+
+에이전트는 브라우저 패널을 직접 쓸 수 있습니다. 페이지를 열고, 내용을 읽고, 클릭하고, 입력하고, 스크롤하고, 모바일·태블릿·데스크톱 레이아웃을 바꿔 가며 자기 작업을 여러분에게 부탁하지 않고 스스로 확인합니다. 그 과정은 패널에서 보입니다.
+
+에이전트가 페이지에서 임의의 코드를 실행할 수는 없습니다. 브라우저가 실제 로그인 상태를 유지하므로 위에 적힌 동작으로만 제한됩니다.
+
+보고 있는 화면을 프로젝트의 `.openchamber/screenshots/` 에 이미지로 저장하고 답변에서 보여 줄 수도 있습니다. 전후 비교가 가능한 이유가 이것이며, 파일은 그대로 남아 풀 리퀘스트에 첨부할 수 있습니다.
+
+브라우저 동작은 **OpenChamber Web 도구**이며, **설정 → 일반 → OpenChamber 도구** 에서 따로 켜고 끌 수 있습니다.
+
+이 기능에는 데스크톱 앱이 필요합니다. 브라우저 탭에 표시된 페이지는 조작할 수 없습니다.
+
+## 개발자 도구
+
+막대의 터미널 버튼을 누르면 해당 페이지에 대한 Chromium 자체 개발자 도구가 열립니다. 콘솔, 네트워크, 요소 등 기대하는 모든 기능을 쓸 수 있습니다.
+
+## 관련 문서
+
+- [미리보기와 개발 서버](/preview/) — 원격 컴퓨터의 것을 포함해 실행 중인 앱 열기
+- [에이전트 제어 도구](/ko/agent-control-tool/) — 채팅에서 세션, worktree, 예약 작업 다루기
@@ -1,32 +1,35 @@
 ---
-title: 미리보기 및 개발 서버
-description: 실행 중인 개발 서버를 OpenChamber 안에서 여세요.
+title: 미리보기와 개발 서버
+description: 실행 중인 개발 서버를 OpenChamber 안에서 엽니다.
 ---

-# 미리보기 및 개발 서버
+# 미리보기와 개발 서버

-개발 서버를 시작하면 OpenChamber는 별도의 브라우저 탭이 아니라 앱 안에서 바로 열 수 있습니다. 그래서 채팅 옆에서 사이트를 보고, 콘솔을 캡처하고, 요소를 가리켜 질문할 수 있습니다.
+개발 서버를 띄우면 OpenChamber가 별도의 브라우저 탭 대신 앱 안에서 바로 열어 줍니다. 채팅 옆에 사이트를 두고 요소를 가리키며 물어볼 수 있습니다.

-## 미리보기 열기
+## 개발 서버 열기

-OpenChamber는 터미널 출력에서 로컬 주소(Vite, Next.js, Astro 같은 도구가 출력하는 `Local:` 줄)를 감시합니다. 발견하면 다음과 같이 동작합니다.
+앱 헤더의 지구본 버튼으로 브라우저 패널을 엽니다. 개발 서버가 이미 실행 중이면 목록에 나타나고 클릭 한 번으로 열립니다. OpenChamber는 컴퓨터에서 실제로 수신 대기 중인 것을 보고 찾아내므로, 어떻게 실행했든 상관없이 동작합니다.

- 터미널에 **Open preview** 버튼이 나타납니다
- auto-open이 켜진 [프로젝트 액션](/ko/project-actions/)이 대신 열어줍니다
- 채팅 메시지의 로컬 링크로도 열 수 있습니다
+다음 경우에도 개발 서버가 자동으로 열립니다.

-사이트는 사이드 패널에 로드됩니다. 로컬 주소(사용자 자신의 컴퓨터)만 미리볼 수 있습니다.
+- 터미널의 로컬 주소에서 **미리보기 열기** 를 누를 때
+- 자동 열기를 켠 [프로젝트 작업](/project-actions/)이 서버를 시작할 때
+- 채팅 메시지의 로컬 링크를 따라갈 때

-## 콘솔과 검사
+주소는 언제든 직접 입력할 수 있습니다. `localhost:5173` 처럼 스킴을 생략하면 `http://` 로 처리됩니다.

-미리보기 패널에서 다음을 할 수 있습니다.
+## 원격 OpenChamber와 함께 쓰기

- 페이지의 **console**(오류, 경고, 로그)을 원하는 대로 필터링하여 확인
- **inspect**를 켜고 임의의 요소를 클릭한 뒤 그에 대한 메모(선택자, 스타일, 위치, 스크린샷)를 바로 채팅으로 전송
+OpenChamber가 다른 컴퓨터에서 실행 중이면 개발 서버도 *그* 컴퓨터에 있습니다. 노트북의 `localhost`는 전혀 다른 곳을 가리키죠. 데스크톱 앱이 이를 대신 처리합니다. 로컬 포트를 열어 원격 개발 서버까지 연결을 이어 주므로 페이지가 평소처럼 로드되고 핫 리로드와 개발자 도구도 동작합니다. 여러분은 기대한 주소를 그대로 입력하면 되고, 내부 배관은 눈에 띄지 않습니다.

-이것은 설명 없이 에이전트에게 "여기 이 버튼"이라고 알리는 가장 빠른 방법입니다.
+이 기능에는 데스크톱 앱이 필요합니다. 브라우저 탭에서는 자신의 컴퓨터에 있는 개발 서버만 열 수 있습니다.

-## 관련 항목
+## 페이지에 주석 달기

- [Project Actions](/ko/project-actions/) — 서버를 시작할 때 자동으로 열기
- [Desktop Browser](/ko/desktop-browser/) — 데스크톱에서 임의의 페이지에 동일한 도구 사용
+요소를 가리키고, 페이지에 그리고, 스타일 변경을 시험해 보고, 이 모두를 채팅으로 보내는 방법은 [브라우저 패널](/desktop-browser/)을 참고하세요.
+
+## 관련 문서
+
+- [프로젝트 작업](/project-actions/) — 서버 시작 시 자동으로 열기
+- [브라우저 패널](/desktop-browser/) — 페이지 주석과 에이전트 조작