v0.3.1 — Lossless compression

Fixed

• Remove sibling deduplication from the pipeline. The optimization was lossy — it collapsed repeated elements (product cards, search results) into summaries, preventing the agent from reading omitted items. All page content is now preserved losslessly.
• Update benchmark numbers to reflect the lossless pipeline.

Site	Raw HTML	TideSurf	Compression
GitHub	84,236	2,593	32x
Wikipedia	123,623	12,097	10x
MDN	24,925	1,793	14x
HN	8,706	1,038	8.4x

Full changelog: https://github.com/TideSurf/core/blob/main/CHANGELOG.md

v0.3.0 — Token Optimization

New output format

TideSurf's output has been rewritten from XML to a compact markdown-like format — 4-5x fewer tokens than the previous XML.

# Page Title
> example.com/search | 0/3000 800vh

NAV
  [L1](/) Home
  [L2](/about) About

FORM F1
  I1 ~Search... ="TideSurf"
  [B1] Search

Benchmark results

Site	Before (XML)	After	Compression
GitHub	10,968 tok	2,148 tok	39x
Wikipedia	25,189 tok	8,564 tok	14x
MDN	18,769 tok	1,535 tok	16x
Hacker News	7,364 tok	1,032 tok	8.5x

Token optimization pipeline

• URL compression — strips tracking params, relativizes same-origin, drops protocol, truncates long paths
• Text truncation — body text outside interactive/heading context truncated to 60 chars
• Sibling deduplication — 4+ identical siblings collapsed to 3 + summary
• Attribute reduction — elides defaults (type="text", method="get"), removes noise attrs
• Conditional structural collapse — section/article/aside only kept with aria-label/role; header/footer only kept with interactive children

Breaking changes

• getState() now uses viewport mode by default — set viewport: false for full page
• PageState.content is the new primary field (.xml still works as deprecated alias)

Full changelog: https://github.com/TideSurf/core/blob/main/CHANGELOG.md

v0.2.3

Fixed

• Filter getState() node maps down to the IDs actually present in the returned XML, so filtered/minimal snapshots no longer leave hidden elements actionable.
• Tighten runtime validation for URLs, search queries, numeric inputs, screenshot options, file paths, and local demo/server ports.
• Confine upload/download filesystem access to fileAccessRoots (default: working directory + temp directory), and block clipboard_read in read-only sessions.
• Bind the local demo and HTTP bridge to 127.0.0.1 and harden the demo static file serving path handling.
• Remove evaluate from read-only sessions so observation mode cannot mutate pages through arbitrary JavaScript.
• Keep the session usable after the initial tab is closed, and preserve visible shadow DOM / iframe content in viewport snapshots.
• Return the nearest interactive TideSurf ID from search() when one exists.
• Collapse long data: and other oversized page URLs in the XML wrapper so release benchmarks and token budgets reflect page content instead of transport noise.

Security and release hardening

• Add a repo-root llms.txt and publish it with the npm package.
• Sync runtime/package versions for the CLI and MCP adapter, and add a version-sync unit test.
• Strengthen release verification to cover MCP type-checking, browser integration tests, website builds, and npm pack --dry-run.
• Make browser integration/benchmark suites self-contained and automatically skip when Chrome cannot launch in the current environment.
• Keep the Chrome sandbox enabled in normal CI runs unless running as root or explicitly opting out.

v0.2.2 — Tests + search fix

What's new

Tests for v0.2.0 features

• Mode filters: 16 tests for filterInteractive and filterMinimal
• Viewport filter: 8 tests for filterViewportOnly
• Tool definitions: 7 tests — 18 tools default, 8 read-only, write tool exclusion
• Validation: 9 new tests for validatePort and validateFilePath
• XML serializer: 2 tests for wrapPage scroll position attributes

Unit test count: 80 → 138

Bug fix

• Removed always-undefined elementId from SearchResult — the field was never populated. Cleaner API instead of a misleading undefined.

Files changed

src/types.ts, src/cdp/page.ts, src/tools/definitions.ts, package.json, plus 6 test files (3 new, 3 extended)

v0.2.1

Bugfixes for v0.2.0.

• Download directory creation — setupDownloads now creates the directory before telling Chrome to save there
• Download listener cleanup — event listeners are removed on timeout instead of leaking
• Read-only MCP gating — all write tools (navigate, click, type, select, scroll, new_tab, close_tab) are now hidden in read-only mode, not just the new tools
• fullPage screenshot — captures actual document dimensions instead of just the viewport
• Docs — api-reference, getting-started, architecture updated for 18 tools, output modes, read-only

Full changelog: v0.2.0...v0.2.1

v0.2.0

New tools (6)

Tool	Description
search	Find text on the page with element IDs and context
screenshot	Capture viewport, full page, or specific element as PNG
upload	Upload file to <input type="file">
download	Click download link and capture the file
clipboard_read	Read clipboard contents
clipboard_write	Write to clipboard

Total tools: 18 (up from 12).

Output modes

get_state now accepts mode and viewport parameters:

await browser.getState({ mode: "interactive" }); // only clickable elements
await browser.getState({ mode: "minimal" });     // landmarks + summaries  
await browser.getState({ viewport: true });       // visible viewport only

All modes compose with each other and maxTokens.

Read-only mode

const browser = await TideSurf.connect({ readOnly: true });

tidesurf mcp --auto-connect --read-only

Disables 10 write tools (navigate, click, type, select, scroll, new_tab, close_tab, upload, clipboard_write, download). Tool definitions are filtered so the LLM never sees disabled tools.

New files

• src/parser/mode-filter.ts — filterInteractive(), filterMinimal()
• src/parser/viewport-filter.ts — filterViewportOnly()
• src/cdp/download-manager.ts — download interception via CDP events

Full changelog: v0.1.2...v0.2.0

v0.1.2

Auto Connect

Connect to an already-running Chrome instance instead of launching a new one. Re-use logged-in sessions, debug live pages, and seamlessly hand off between manual browsing and agent control.

• TideSurf.connect(options?) — attach to existing Chrome via CDP
• TideSurfConnectOptions type (port, host, timeout)
• discoverBrowser() — Chrome instance discovery with timeout
• --auto-connect and --port CLI/MCP flags
• close() skips process cleanup when auto-connected
• Port validation (validatePort()) across all entry points
• Targets first page tab explicitly to avoid service worker / chrome:// attachment

Usage:

const browser = await TideSurf.connect({ port: 9222 });

{
  "mcpServers": {
    "tidesurf": {
      "command": "bunx",
      "args": ["tidesurf", "mcp", "--auto-connect"]
    }
  }
}

Demo

• TideTravel interactive demo site
• bun run demo server script (localhost:3456)

Full changelog: v0.1.1...v0.1.2

v0.1.1

What's new

• Live-site benchmarks — animated bar chart on landing page + full docs page with methodology, cost analysis, and context window impact
• Three-wave logo — new branding across README, landing page, docs, and favicon
• llms.txt — LLM-friendly project discovery at tidesurf.org/llms.txt
• Docs URL fix — docs.tidesurf.org → tidesurf.org/docs
• CI fixes — increased DevTools timeout, --no-sandbox for CI runners, race condition fix in waitForDevTools()
• Package rename — tidesurf-core → @tidesurf/core
• i18n READMEs — English, Japanese (ます/です), Korean (합니다체)
• npm publish workflow — automated via GitHub Actions on release

v0.1.0

Initial Release

The connector between Chromium and LLM agents — no screenshots, no vision models, just the DOM compressed for machines.

Highlights

• DOM compression: 100–800 tokens per page (vs 5,000–50,000+ raw HTML)
• 12 standard tools for LLM function calling (navigate, click, type, scroll, extract, etc.)
• Multi-tab support with independent state per tab
• Token budgeting with priority-based pruning
• MCP server adapter for Claude Code
• TypeScript-first with typed errors

Install

bun add @tidesurf/core

Links

• Documentation
• Getting Started