Browser preview

Pond can show your dev server beside the agent's terminal. The preview is for the agent's own work, not for general browsing.

Open a preview

• When the agent's terminal prints a dev-server URL such as http://localhost:5173/, a globe appears in the terminal header and the worktree card shows "Preview localhost:5173". Click either one.
• Cmd-click a localhost URL in a terminal. Cmd-Option-click opens it in Safari or Chrome instead.
• In a shell, run pond open-preview.

The tile opens next to the terminal. There is one page per worktree and no tabs.

To start the dev server yourself, use Run in the worktree row's menu. See Run a dev server. The preview then appears in the same way, even when no agent is working there.

The bar

The bar has back, forward and reload (Cmd-R, or Shift-Cmd-R for a hard reload), the address, the picker (Cmd-Shift-C), an error count and a menu. The menu has:

• Viewport: Desktop, Tablet 820 or Phone 390.
• Reload on file change, off by default, for static pages.
• Open in default browser, Web Inspector, Clear site data, and Pop out.

If the dev server stops, the tile says "localhost:5173 is not answering." and offers Reload. Pond does not retry by itself.

The page has its own storage. Your Safari logins are never in it. A link to an address outside the worktree's own addresses opens in your default browser, not in the tile.

Point at something

Click the picker in the bar, or press Shift-Cmd-C, and move over the page. A quiet outline follows the pointer with a small label: the tag, its test id, id or first class, and its size. Click an element. The page does not react to that click. A one-line prompt opens under it. Type what to change ("Change this…") and press Return. Esc cancels and sends nothing. With several agents in the worktree, a small menu in the prompt picks which one.

Return sends the agent one message: your words, the page address and route, the viewport size, the element's selector and text, and the path of a screenshot of just that element. The screenshot goes in the worktree's .pond-drop/ folder, which only you can read and git ignores. This is the one Return Pond presses in an agent's terminal from the browser, and only because you pressed it. If you have half-typed text in the agent's input, or the agent waits on a dialog, nothing is sent and the prompt says why. The picker works only on the worktree's own dev servers, and it is dimmed on any other page.

Errors

The bar counts console errors, uncaught exceptions and failed requests. Click the count to open a panel. Each line has Send to agent, which pastes a line starting [Pond error] into the terminal, again without pressing Return. Pond keeps no request bodies, headers or cookies.

What an agent may do in the page

An agent can drive the page through Pond's browser tools: navigate, take a snapshot, click, type, read the console and wait. While it does, the bar shows the agent's blob, "is using this page" and a Stop button, and the page gets an outline in the agent's colour. If you click or type in the page, the agent pauses for 3 seconds.

Pond limits what the agent can do:

• An agent can use only the worktree's own dev addresses. For any other address, including a LAN IP, a sheet names the origin with its scheme and port. Return denies. The buttons that grant, Allow once and Allow for this task, have no keyboard shortcut, so you have to click them. Allow for this task ends with the task, and Pond removes the cookies it set.
• Off localhost, a click or Enter on a button with a word such as pay, buy, send or delete asks you first. Return means Don't allow.
• Off localhost, an agent cannot type into password fields.
• Agents cannot download files or open file:// addresses outside the worktree.
• A grant comes only from your click on a Pond sheet, never from the agent.

To turn the browser off for one task, start it with pond task new --no-browser.