barebrowse 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.13.0] - 2026-06-12
+
+### Added
+- **`readable()` — clean article extraction.** New read mode that returns the
+  main article of a page as clean text (title + body prose, nav/ads/sidebars
+  stripped) via Mozilla Readability injected in-page over CDP. Companion to
+  `snapshot()`, not a replacement: `snapshot()` is the *actionable* ARIA tree
+  for clicking/typing; `readable()` is for *reading/summarising* article-like
+  pages (news, blogs, docs, wiki), where `snapshot()` is noisy and silently
+  lossy on long prose. Article detection is unreliable, so `readable()` never
+  hard-gates — it always returns the text plus an advisory `confidence`
+  (`high`/`low`) and a hint to fall back to `snapshot()` on non-article pages.
+  Exposed everywhere: `page.readable()`, MCP `readable` tool, bareagent
+  `readable` tool, and `barebrowse readable` CLI (→ `.barebrowse/article-*.txt`).
+
+### Fixed
+- **Large pages no longer kill the CDP connection.** Node's built-in WebSocket
+  (undici) silently caps decompressed messages at ~3 MB and *permanently* tears
+  down the socket when a single `Accessibility.getFullAXTree` response exceeds
+  it — which broke `snapshot()` (and consent dismissal during `goto()`) on big
+  pages (e.g. long Wikipedia articles). `cdp.js` now uses the `ws` package with
+  a 256 MB `maxPayload`; the built-in exposes no way to raise the limit.
+  Regression test: `connect.test.js` snapshots a 12k-node page that tripped the
+  old cap.
+
+### Security
+- **MCP output files are now owner-only (`0600`).** `saveSnapshot()` and the
+  screenshot tool previously wrote snapshots / articles / screenshots with
+  default perms (`0644` in a `0755` dir under the standard umask) —
+  authenticated page content readable by other local users on a shared host.
+  They now write `0600` files in a `0700` dir, umask-independent, matching the
+  daemon's existing invariant. Regression-guarded by a test that fails on a
+  `0644` write.
+- **Daemon hardening:** `GET /status` (the only pre-auth endpoint) no longer
+  returns the pid; `/command` now caps the request body at 16 MB (→ `413`).
+
+### Changed
+- **Two runtime dependencies (previously zero):** `ws` (CDP transport, above)
+  and `@mozilla/readability` (`readable()`). Both are lightweight, widely
+  adopted, and actively maintained, per the project's dependency rule (external
+  only when the stdlib genuinely can't do the job).
+
+## [0.12.0] - 2026-05-29
+
+### Added
+- **Shipped TypeScript types, generated from JSDoc.** The package now ships
+  `.d.ts` declarations so adopters get autocomplete and type errors out of the
+  box — no `@types/barebrowse`. The `.js` we author is still the `.js` that
+  ships; there is **no build step for runtime code**. Types are generated by
+  `tsc` (`checkJs` + `strictNullChecks`), emitted to a git-ignored `types/`, and
+  built into the tarball at publish via `prepublishOnly`. Because they are
+  generated-and-never-committed, the JSDoc, the `.d.ts`, and CI cannot drift.
+  `exports` now carries a `types` condition on every subpath.
+- **`ci.yml` (push/PR gate):** `npm ci → typecheck → build:types → test`. A
+  JSDoc/code mismatch is now a type error that blocks merge. No lint step — `tsc`
+  covers the bug class that matters for a vanilla-ESM lib.
+- Dev-only tooling: `typescript` + `@types/node` (devDependencies; never
+  shipped), `tsconfig.json`, and `typecheck` / `build:types` / `prepublishOnly`
+  scripts.
+
+### Changed
+- **`publish.yml` is now manual-only (`workflow_dispatch`) — npm OIDC trusted publishing with provenance, idempotent, and verifies the registry end-state.**
+- **Packaging now uses a `files` allowlist** (`src/`, generated `types/`,
+  `cli.js`, `mcp-server.js`, and the doc set) instead of the old `.npmignore`
+  denylist, which was removed. Repo-only files (`test/`, `docs/`, `CLAUDE.md`)
+  are excluded from the tarball.
+
+### Fixed
+- **`auth.js`: cookie databases are now opened with `readOnly: true`.** The
+  previous `readonly` (lowercase) key is silently ignored by `node:sqlite`;
+  surfaced by the new `tsc` typecheck. Read-only was already enforced via the
+  `?immutable=1` connection URI, so observable behavior is unchanged — this
+  honors the intended option. Added minimal, behavior-preserving null/type
+  guards in a few spots (`server.address()`, SQLite row values) flagged by
+  `strictNullChecks`.
+
 ## 0.11.0
 
 ### Security hardening — audit findings fixed, safe-by-default

package/README.md

@@ -10,6 +10,7 @@
 ```
 
 <p align="center">
+  <a href="https://github.com/hamr0/barebrowse/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/hamr0/barebrowse/ci.yml?label=CI" alt="CI"></a>
   <img src="https://img.shields.io/github/package-json/v/hamr0/barebrowse?label=version&color=2a4f8c" alt="version (auto from package.json)">
   <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
 </p>
@@ -25,7 +26,7 @@ barebrowse gives your AI agent a real browser. Navigate, read, interact, move on
 
 It uses the browser you already have -- your sessions, your cookies. Pages come back stripped to what matters -- 40-90% fewer tokens than raw output.
 
-No Playwright. Zero dependencies. No bundled browser. No 200MB download.
+No Playwright. No bundled browser. No 200MB download. Two tiny dependencies (`ws` + Mozilla Readability).
 
 ## Install
 
@@ -35,6 +36,8 @@ npm install barebrowse
 
 Requires Node.js >= 22 and any installed Chromium-based browser.
 
+Ships with TypeScript types (generated from JSDoc) — autocomplete and type-checking work out of the box, no `@types/barebrowse` needed. The library is vanilla JS with no build step.
+
 ## Three ways to use it
 
 ### 1. CLI session -- for coding agents and quick testing
@@ -42,6 +45,7 @@ Requires Node.js >= 22 and any installed Chromium-based browser.
 ```bash
 barebrowse open https://example.com    # Start session + navigate
 barebrowse snapshot                    # ARIA snapshot → .barebrowse/page-*.yml
+barebrowse readable                    # Clean article text → .barebrowse/article-*.txt
 barebrowse click 8                     # Click element
 barebrowse close                       # End session
 ```
@@ -92,7 +96,7 @@ Or manually add to your config (`claude_desktop_config.json`, `.cursor/mcp.json`
 }
 ```
 
-18 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`. Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Plus opt-in `eval` (`BAREBROWSE_MCP_EVAL=1`) — runs JS in the authenticated session, off by default because it can read cookies/localStorage. Session runs in hybrid mode with automatic cookie injection. Per-tool timeouts (goto/reload/wait_for 60s, back/forward 30s, interactive ops 15s, pdf/screenshot/upload 45s) with auto-retry on transient failures (idempotent only — mutating tools fail loudly to avoid double-submits).
+19 tools: `browse`, `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`. Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Plus opt-in `eval` (`BAREBROWSE_MCP_EVAL=1`) — runs JS in the authenticated session, off by default because it can read cookies/localStorage. Session runs in hybrid mode with automatic cookie injection. Per-tool timeouts (goto/reload/wait_for 60s, back/forward 30s, interactive ops 15s, pdf/screenshot/upload 45s) with auto-retry on transient failures (idempotent only — mutating tools fail loudly to avoid double-submits).
 
 `browse` and `snapshot` accept `pruneMode: 'act'|'read'` (v0.9.1). `act` (default) keeps interactive elements — best for clicking/filling. `read` keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. If act-mode collapses a content-heavy page near-totally, the snapshot includes a `hint: …` line suggesting `pruneMode='read'` so the agent doesn't bail to a separate HTTP fetch.
 
@@ -100,7 +104,7 @@ Troubleshooting MCP setup: `npx barebrowse doctor` scans every known config loca
 
 ### 3. Library -- for agentic automation
 
-Import barebrowse in your agent code. One-shot reads, interactive sessions, full observe-think-act loops. Works with any LLM orchestration library. Ships with a ready-made adapter for [bareagent](https://www.npmjs.com/package/bare-agent) (17 tools, auto-snapshot after every action).
+Import barebrowse in your agent code. One-shot reads, interactive sessions, full observe-think-act loops. Works with any LLM orchestration library. Ships with a ready-made adapter for [bareagent](https://www.npmjs.com/package/bare-agent) (18 tools, auto-snapshot after every action).
 
 For code examples, API reference, and wiring instructions, see **[barebrowse.context.md](barebrowse.context.md)** -- the full integration guide.
 
@@ -167,6 +171,7 @@ Everything the agent can do through barebrowse:
 | **Navigate** | Load a URL, wait for page load, auto-dismiss consent |
 | **Back / Forward** | Browser history navigation |
 | **Snapshot** | Pruned ARIA tree with `[ref=N]` markers. Two modes: `act` (buttons, links, inputs) and `read` (full text). 40-90% token reduction. |
+| **Readable** | Clean article text (title + body, chrome stripped — Reader-View engine). For *reading* article-like pages, not interacting. Advisory `confidence`; falls back to snapshot on non-articles. |
 | **Click** | Scroll into view + mouse click at element center, JS fallback for hidden elements |
 | **Type** | Focus + insert text, with option to clear existing content first |
 | **Press** | Special keys: Enter, Tab, Escape, Backspace, Delete, arrows, Space |
@@ -213,7 +218,7 @@ URL -> find/launch browser (chromium.js)
     -> agent-ready snapshot with [ref=N] markers
 ```
 
-11 modules, 2,400 lines, zero required dependencies.
+14 modules, ~3,000 lines, two small dependencies (`ws`, `@mozilla/readability`).
 
 ## Requirements
 

package/barebrowse.context.md

@@ -1,7 +1,7 @@
 # barebrowse -- Integration Guide
 
 > For AI assistants and developers wiring barebrowse into a project.
-> v0.11.0 | Node.js >= 22 | 0 required deps | Apache-2.0
+> v0.12.0 | Node.js >= 22 | 0 required deps | Apache-2.0
 
 ## What this is
 
@@ -13,6 +13,11 @@ No Playwright. No bundled browser. No build step. Vanilla JS, ES modules.
 npm install barebrowse
 ```
 
+**TypeScript:** ships with `.d.ts` types generated from the source JSDoc, so
+autocomplete and type-checking work out of the box — no `@types/barebrowse`
+needed. The library itself is vanilla JS with no build step; the types are a
+publish-time artifact.
+
 Three integration paths:
 1. **Library:** `import { browse, connect } from 'barebrowse'` -- one-shot or interactive session
 2. **MCP server:** `barebrowse mcp` -- JSON-RPC over stdio for Claude Desktop, Cursor, etc.
@@ -62,6 +67,7 @@ const snapshot = await browse('https://example.com', {
 | `goForward()` | -- | void | Navigate forward in browser history |
 | `reload(opts?)` | { ignoreCache?: boolean, timeout?: number } | void | Reload the current page. Clears refMap (refs from pre-reload reject). |
 | `snapshot(pruneOpts?)` | false or { mode: 'act'\|'read' } | string | ARIA tree with `[ref=N]` markers. Pass `false` for raw. |
+| `readable()` | -- | object | Clean article text (Reader-View engine). `{ ok, title, byline, text, length, confidence: 'high'\|'low', readerable, hint? }` or `{ ok: false, hint }`. For *reading*, not interacting — see note below. |
 | `click(ref)` | ref: string | void | Scroll into view + mouse press+release at center |
 | `type(ref, text, opts?)` | ref: string, text: string, opts: { clear?, keyEvents? } | void | Focus + insert text. `clear: true` replaces existing. |
 | `press(key)` | key: string | void | Special key: Enter, Tab, Escape, Backspace, Delete, arrows, Home, End, PageUp, PageDown, Space |
@@ -117,6 +123,28 @@ Key rules:
 - `click(ref)` / `type(ref, text)` / `hover(ref)` / `select(ref, value)` use these ref strings
 - Pruning removes noise (~47-95% token reduction) while keeping all interactive elements
 
+## readable() vs snapshot() — which to use
+
+Two different jobs:
+
+- **`snapshot()`** → the *actionable* ARIA tree (`[ref=N]` markers). Use it to **interact** (click/type/fill) or on **any** page type (home pages, search results, app UIs).
+- **`readable()`** → the *article* as clean reading text (title + body prose; nav/ads/sidebars stripped). Use it **only** to **read or summarise** article-like pages (news, blogs, docs, wiki), where `snapshot()` is both noisy and *silently lossy on long prose* (`read` pruning can drop body text).
+
+`readable()` is **not** a token-savings feature — vs a read-mode snapshot it can be smaller *or* larger depending on the page; its value is **complete, clean prose**. It returns no refs, so you cannot interact with its output.
+
+**Article detection is unreliable**, so `readable()` never hard-gates. It always returns whatever it extracted plus an advisory `confidence`:
+- `confidence: 'high'` → safe to treat as an article.
+- `confidence: 'low'` (or `ok: false`) → probably not an article; the `hint` tells the agent to fall back to `snapshot()`.
+
+```js
+const r = await page.readable();
+if (r.ok && r.confidence === 'high') {
+  use(r.text);              // clean article prose
+} else {
+  const snap = await page.snapshot({ mode: 'read' });  // fall back
+}
+```
+
 ## Interaction loop: observe, think, act
 
 ```javascript
@@ -202,10 +230,10 @@ try {
 ```
 
 `createBrowseTools(opts)` returns:
-- `tools` -- array of bareagent-compatible tool objects: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `select`, `hover`, `back`, `forward`, `reload` (v0.9.0), `drag`, `upload`, `tabs`, `switchTab`, `pdf`, `screenshot`, `wait_for` (v0.9.0), `downloads` (v0.9.0), plus `assess` if wearehere installed
+- `tools` -- array of bareagent-compatible tool objects: `browse`, `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `select`, `hover`, `back`, `forward`, `reload` (v0.9.0), `drag`, `upload`, `tabs`, `switchTab`, `pdf`, `screenshot`, `wait_for` (v0.9.0), `downloads` (v0.9.0), plus `assess` if wearehere installed
 - `close()` -- cleanup function, call when done
 
-Action tools (click, type, press, scroll, hover, goto, back, forward, reload, drag, upload, select, switchTab, wait_for) auto-return a fresh snapshot so the LLM always sees the result. 300ms settle delay after actions for DOM updates.
+Action tools (click, type, press, scroll, hover, goto, back, forward, reload, drag, upload, select, switchTab, wait_for) auto-return a fresh snapshot so the LLM always sees the result. 300ms settle delay after actions for DOM updates. `readable` is a read tool (like `snapshot`): it returns the article text directly, not a follow-up snapshot.
 
 `onDialog` is intentionally not exposed as a tool — it's a callback shape that doesn't fit a request/response tool loop. If your bareagent flow needs to override a confirm/prompt, drop to `import { connect }` directly and pass the page through.
 
@@ -216,6 +244,7 @@ For coding agents (Claude Code, Copilot, Cursor) and quick interactive testing.
 ```bash
 barebrowse open https://example.com    # Start daemon + navigate
 barebrowse snapshot                    # → .barebrowse/page-<timestamp>.yml
+barebrowse readable                    # → .barebrowse/article-<timestamp>.txt (clean article text)
 barebrowse click 8                     # Click element ref=8
 barebrowse type 12 hello world         # Type into element ref=12
 barebrowse back                        # Go back in history
@@ -257,11 +286,11 @@ barebrowse ships an MCP server for direct use with Claude Desktop, Cursor, or an
 }
 ```
 
-18 core tools as of v0.9.0: `browse` (one-shot), `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`. Plus `assess` (privacy scan) if `wearehere` is installed (`npm install wearehere`). Plus the **opt-in `eval` tool** gated by `BAREBROWSE_MCP_EVAL=1` (default OFF) — `Runtime.evaluate` in the user's authenticated session can read cookies/localStorage and hit any same-origin endpoint, so opt-in only.
+19 core tools: `browse` (one-shot), `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`. Plus `assess` (privacy scan) if `wearehere` is installed (`npm install wearehere`). Plus the **opt-in `eval` tool** gated by `BAREBROWSE_MCP_EVAL=1` (default OFF) — `Runtime.evaluate` in the user's authenticated session can read cookies/localStorage and hit any same-origin endpoint, so opt-in only.
 
 Action tools return `'ok'` -- the agent calls `snapshot` explicitly to observe. This avoids double-token output since MCP tool calls are cheap to chain.
 
-`browse` and `snapshot` accept a `maxChars` param (default 30000). If the snapshot exceeds the limit, it's saved to `.barebrowse/page-<timestamp>.yml` and a short message with the file path is returned instead. `screenshot` always saves to `.barebrowse/screenshot-<timestamp>.{png,jpeg,webp}` and returns the file path (raw base64 in a JSON-RPC response would blow `maxChars`). `tabs` returns the JSON array, or with `switchTo: N` it switches and returns `'ok'`.
+`browse`, `snapshot`, and `readable` accept a `maxChars` param (default 30000). If the output exceeds the limit it's saved to `.barebrowse/` and a short message with the file path is returned instead (`page-<timestamp>.yml` for snapshots, `article-<timestamp>.txt` for `readable`). `screenshot` always saves to `.barebrowse/screenshot-<timestamp>.{png,jpeg,webp}` and returns the file path (raw base64 in a JSON-RPC response would blow `maxChars`). `tabs` returns the JSON array, or with `switchTo: N` it switches and returns `'ok'`. All files MCP writes are owner-only (`0600` in a `0700` dir) — they can hold authenticated page content, so they're not world-readable on a shared host.
 
 `browse` and `snapshot` also accept `pruneMode: 'act'|'read'`. `act` (the default) keeps interactive elements and short labels — best for clicking/filling. `read` keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. Same surface on the bareagent adapter. If act mode collapses a content-heavy page (raw > 5 KB → pruned < 500 chars AND < 5% of raw), the result includes a `hint: act mode dropped most of the page — retry with pruneMode='read' …` line between the stats and the tree so the caller knows to re-snapshot in read mode instead of bailing to a separate HTTP fetch.
 

package/cli.js

@@ -38,6 +38,8 @@ if (args.includes('--daemon-internal')) {
   await cmdProxy('goto', { url: args[1], timeout: parseFlag('--timeout') });
 } else if (cmd === 'snapshot') {
   await cmdProxy('snapshot', { mode: parseFlag('--mode') });
+} else if (cmd === 'readable') {
+  await cmdProxy('readable');
 } else if (cmd === 'screenshot') {
   await cmdProxy('screenshot', { format: parseFlag('--format') });
 } else if (cmd === 'click' && args[1]) {
@@ -504,6 +506,7 @@ Navigation:
   barebrowse forward                Go forward in history
   barebrowse reload [--no-cache]    Reload current page
   barebrowse snapshot [--mode=M]    ARIA snapshot -> .barebrowse/page-*.yml
+  barebrowse readable               Clean article text -> .barebrowse/article-*.txt
   barebrowse screenshot [--format]  Screenshot -> .barebrowse/screenshot-*.png
   barebrowse pdf [--landscape]      PDF export -> .barebrowse/page-*.pdf
 

package/mcp-server.js

@@ -3,13 +3,15 @@
  * mcp-server.js — MCP server for barebrowse.
  *
  * Raw JSON-RPC 2.0 over stdio. No SDK dependency.
- * 12 tools: browse, goto, snapshot, click, type, press, scroll, back, forward, drag, upload, pdf.
+ * Tools: browse, goto, snapshot, readable, click, type, press, scroll, back,
+ * forward, drag, upload, pdf, reload, screenshot, wait_for, tabs, select, hover.
  *
  * Session tools share a singleton page, lazy-created on first use.
  * Action tools return 'ok' — agent calls snapshot explicitly to observe.
  */
 
 import { browse, connect } from './src/index.js';
+import { formatReadable } from './src/readable.js';
 import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
@@ -102,11 +104,14 @@ async function withRetry(fn, timeoutMs, { retry = true } = {}) {
 const MAX_CHARS_DEFAULT = 30000;
 const OUTPUT_DIR = join(process.cwd(), '.barebrowse');
 
-function saveSnapshot(text) {
-  mkdirSync(OUTPUT_DIR, { recursive: true });
+export function saveSnapshot(text, { prefix = 'page', ext = 'yml' } = {}) {
+  // Owner-only: snapshots/articles can hold authenticated page content
+  // (logged-in text, reflected session data). Matches the daemon's 0600/0700
+  // invariant — and is umask-independent because the modes are explicit.
+  mkdirSync(OUTPUT_DIR, { recursive: true, mode: 0o700 });
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
-  const file = join(OUTPUT_DIR, `page-${ts}.yml`);
-  writeFileSync(file, text);
+  const file = join(OUTPUT_DIR, `${prefix}-${ts}.${ext}`);
+  writeFileSync(file, text, { mode: 0o600 });
   return file;
 }
 
@@ -178,6 +183,16 @@ export const TOOLS = [
       },
     },
   },
+  {
+    name: 'readable',
+    description: 'Extract the main article of the current page as clean reading text (title + body prose, nav/ads/sidebars stripped — the Firefox Reader View engine). Use ONLY when your goal is to READ or SUMMARISE article-like content (news, blog posts, docs, wiki). For clicking/typing/forms, or for non-article pages (home pages, search results, app UIs), use snapshot instead. On a non-article page this returns a low-confidence result with a hint to use snapshot.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        maxChars: { type: 'number', description: 'Max chars to return inline. Longer articles are saved to .barebrowse/ and a file path is returned instead. Default: 30000.' },
+      },
+    },
+  },
   {
     name: 'click',
     description: 'Click an element by its ref from the snapshot. Returns ok — call snapshot to observe.',
@@ -403,6 +418,18 @@ async function handleToolCall(name, args) {
       }
       return text;
     }, TIMEOUTS.snapshot);
+    case 'readable': return withRetry(async () => {
+      const page = await getPage();
+      const r = await page.readable();
+      if (!r.ok) return r.hint;
+      const body = formatReadable(r);
+      const limit = args.maxChars ?? MAX_CHARS_DEFAULT;
+      if (body.length > limit) {
+        const file = saveSnapshot(body, { prefix: 'article', ext: 'txt' });
+        return `Article "${r.title}" (${r.text.length} chars, confidence: ${r.confidence}) saved to ${file}`;
+      }
+      return body;
+    }, TIMEOUTS.snapshot);
     case 'click': return withRetry(async () => {
       const page = await getPage();
       await page.click(args.ref);
@@ -463,10 +490,11 @@ async function handleToolCall(name, args) {
       const page = await getPage();
       const format = args.format || 'png';
       const b64 = await page.screenshot({ format, quality: args.quality });
-      mkdirSync(OUTPUT_DIR, { recursive: true });
+      mkdirSync(OUTPUT_DIR, { recursive: true, mode: 0o700 });
       const ts = new Date().toISOString().replace(/[:.]/g, '-');
       const file = join(OUTPUT_DIR, `screenshot-${ts}.${format}`);
-      writeFileSync(file, Buffer.from(b64, 'base64'));
+      // Owner-only: a screenshot of an authenticated page is sensitive too.
+      writeFileSync(file, Buffer.from(b64, 'base64'), { mode: 0o600 });
       return file;
     }, TIMEOUTS.screenshot);
     case 'wait_for': return withRetry(async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "repository": {
     "type": "git",
@@ -10,18 +10,40 @@
   "bugs": "https://github.com/hamr0/barebrowse/issues",
   "type": "module",
   "main": "src/index.js",
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./bareagent": "./src/bareagent.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./bareagent": {
+      "types": "./types/bareagent.d.ts",
+      "default": "./src/bareagent.js"
+    }
   },
   "bin": {
     "barebrowse": "./cli.js"
   },
+  "files": [
+    "src/",
+    "types/",
+    "cli.js",
+    "mcp-server.js",
+    "barebrowse.context.md",
+    "README.md",
+    "CHANGELOG.md",
+    "NOTICE"
+  ],
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --test test/unit/*.test.js test/integration/*.test.js"
+    "test": "node --test test/unit/*.test.js test/integration/*.test.js",
+    "test:unit": "node --test test/unit/*.test.js",
+    "test:integration": "node --test test/integration/*.test.js",
+    "typecheck": "tsc --noEmit",
+    "build:types": "tsc",
+    "prepublishOnly": "npm run build:types"
   },
   "keywords": [
     "browser",
@@ -37,5 +59,13 @@
   "optionalDependencies": {
     "wearehere": "1.0.0"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "ws": "^8.21.0"
+  }
 }

package/src/auth.js

@@ -126,7 +126,7 @@ function extractChromiumCookies(dbPath, domain) {
   const aesKey = deriveKey(password);
 
   // immutable=1 bypasses WAL lock on live databases
-  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readonly: true });
+  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readOnly: true });
 
   let sql = `SELECT host_key, name, value, encrypted_value, path,
     CAST(expires_utc AS TEXT) AS expires_utc, is_secure, is_httponly, samesite
@@ -144,7 +144,8 @@ function extractChromiumCookies(dbPath, domain) {
   const SAMESITE = { 0: 'None', 1: 'Lax', 2: 'Strict' };
 
   return rows.map((row) => {
-    const enc = Buffer.from(row.encrypted_value);
+    const rawEnc = row.encrypted_value;
+    const enc = rawEnc instanceof Uint8Array ? Buffer.from(rawEnc) : Buffer.alloc(0);
     let value;
     try {
       value = enc.length > 0 ? decryptCookie(enc, aesKey) : row.value;
@@ -154,7 +155,9 @@ function extractChromiumCookies(dbPath, domain) {
 
     // Chrome timestamp: microseconds since 1601-01-01
     const CHROME_EPOCH = 11644473600000000n;
-    const expiresUtc = row.expires_utc ? BigInt(row.expires_utc) : 0n;
+    const expiresUtc = typeof row.expires_utc === 'string' || typeof row.expires_utc === 'number'
+      ? BigInt(row.expires_utc)
+      : 0n;
     const expires = expiresUtc > 0n
       ? Number((expiresUtc - CHROME_EPOCH) / 1000000n)
       : -1;
@@ -179,7 +182,7 @@ function extractChromiumCookies(dbPath, domain) {
  * @returns {Array<object>} Cookies in CDP Network.setCookie format
  */
 function extractFirefoxCookies(dbPath, domain) {
-  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readonly: true });
+  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readOnly: true });
 
   let sql = `SELECT host, name, value, path, expiry, isSecure, isHttpOnly, sameSite
     FROM moz_cookies`;

package/src/bareagent.js

@@ -11,7 +11,10 @@
  * 300ms settle delay after actions for DOM updates.
  */
 
+/// <reference path="./wearehere.d.ts" />
+
 import { browse, connect } from './index.js';
+import { formatReadable } from './readable.js';
 
 // Optional: privacy assessment via wearehere
 let assessFn = null;
@@ -22,6 +25,14 @@ try {
 const SETTLE_MS = 300;
 const settle = () => new Promise((r) => setTimeout(r, SETTLE_MS));
 
+/**
+ * @typedef {object} BrowseTool
+ * @property {string} name
+ * @property {string} description
+ * @property {object} parameters - JSON-schema-shaped parameter spec
+ * @property {(args?: any) => Promise<any>} execute
+ */
+
 /**
  * Create bareagent-compatible browse tools.
  * @param {object} [opts] - Options passed to connect() for session tools
@@ -42,6 +53,7 @@ export function createBrowseTools(opts = {}) {
     return await page.snapshot();
   }
 
+  /** @type {BrowseTool[]} */
   const tools = [
     {
       name: 'browse',
@@ -77,11 +89,20 @@ export function createBrowseTools(opts = {}) {
           pruneMode: { type: 'string', enum: ['act', 'read'], description: '"act" (default) for interactive elements only; "read" for paragraphs and long text (articles/docs).' },
         },
       },
-      execute: async ({ pruneMode } = {}) => {
+      execute: async (/** @type {{ pruneMode?: string }} */ { pruneMode } = {}) => {
         const page = await getPage();
         return await page.snapshot(pruneMode ? { mode: pruneMode } : undefined);
       },
     },
+    {
+      name: 'readable',
+      description: 'Extract the main article as clean reading text (title + body prose, chrome stripped — Firefox Reader View engine). Use ONLY to READ/SUMMARISE article-like pages (news, blogs, docs, wiki). For interacting, or for non-article pages, use snapshot. Returns a low-confidence hint to use snapshot when the page is not an article.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => {
+        const page = await getPage();
+        return formatReadable(await page.readable());
+      },
+    },
     {
       name: 'click',
       description: 'Click an element by its ref from the snapshot. Returns the updated snapshot.',
@@ -231,7 +252,7 @@ export function createBrowseTools(opts = {}) {
           landscape: { type: 'boolean', description: 'Landscape orientation (default: false)' },
         },
       },
-      execute: async ({ landscape } = {}) => {
+      execute: async (/** @type {{ landscape?: boolean }} */ { landscape } = {}) => {
         const page = await getPage();
         return await page.pdf({ landscape });
       },
@@ -245,7 +266,7 @@ export function createBrowseTools(opts = {}) {
           format: { type: 'string', enum: ['png', 'jpeg', 'webp'], description: 'Image format (default: png)' },
         },
       },
-      execute: async ({ format } = {}) => {
+      execute: async (/** @type {{ format?: string }} */ { format } = {}) => {
         const page = await getPage();
         return await page.screenshot({ format });
       },
@@ -259,7 +280,7 @@ export function createBrowseTools(opts = {}) {
           ignoreCache: { type: 'boolean', description: 'Bypass HTTP cache (hard reload). Default: false.' },
         },
       },
-      execute: async ({ ignoreCache } = {}) => actionAndSnapshot((page) => page.reload({ ignoreCache })),
+      execute: async (/** @type {{ ignoreCache?: boolean }} */ { ignoreCache } = {}) => actionAndSnapshot((page) => page.reload({ ignoreCache })),
     },
     {
       name: 'wait_for',
@@ -272,7 +293,7 @@ export function createBrowseTools(opts = {}) {
           timeout: { type: 'number', description: 'Timeout in ms (default: 30000)' },
         },
       },
-      execute: async ({ text, selector, timeout } = {}) => actionAndSnapshot((page) => page.waitFor({ text, selector, timeout })),
+      execute: async (/** @type {{ text?: string, selector?: string, timeout?: number }} */ { text, selector, timeout } = {}) => actionAndSnapshot((page) => page.waitFor({ text, selector, timeout })),
     },
     {
       name: 'downloads',

package/src/cdp.js

@@ -2,25 +2,35 @@
  * cdp.js — Minimal Chrome DevTools Protocol client over WebSocket.
  *
  * Sends JSON-RPC commands, receives responses and events.
- * Uses Node 22's built-in WebSocket (no external deps).
+ * Uses the `ws` package (not Node's built-in WebSocket): the built-in
+ * silently caps decompressed messages at ~3 MB and permanently kills the
+ * socket when a single CDP response (e.g. Accessibility.getFullAXTree on a
+ * large page) exceeds it — with no way to raise the limit. `ws` exposes
+ * maxPayload, so we lift the ceiling and disable compression.
  *
  * Supports flattened sessions: when a sessionId is provided,
  * it's sent at the top level of the message (not inside params).
  * Events from sessions are also dispatched by sessionId.
  */
 
+import WebSocket from 'ws';
+
+/** Lift the message ceiling well past any realistic AX/DOM payload. */
+const MAX_PAYLOAD = 256 * 1024 * 1024; // 256 MB
+
 /**
  * Create a CDP client connected to the given WebSocket URL.
  * @param {string} wsUrl - WebSocket URL (ws://127.0.0.1:PORT/devtools/...)
- * @returns {Promise<CDPClient>}
+ * @returns {Promise<object>} CDP client ({ send, on, once, session, close })
  */
 export async function createCDP(wsUrl) {
-  const ws = new WebSocket(wsUrl);
+  const ws = new WebSocket(wsUrl, { maxPayload: MAX_PAYLOAD, perMessageDeflate: false });
   let nextId = 1;
   const pending = new Map();   // id → { resolve, reject }
   const listeners = new Map(); // "method" or "sessionId:method" → Set<callback>
 
-  await new Promise((resolve, reject) => {
+  /** @type {Promise<void>} */
+  const connected = new Promise((resolve, reject) => {
     const timeout = setTimeout(() => reject(new Error('CDP connection timeout (5s)')), 5000);
     ws.onopen = () => { clearTimeout(timeout); resolve(); };
     ws.onerror = (e) => {
@@ -28,6 +38,7 @@ export async function createCDP(wsUrl) {
       reject(new Error(`CDP WebSocket connection failed: ${e.message || 'unknown error'}`));
     };
   });
+  await connected;
 
   ws.onmessage = (event) => {
     const msg = JSON.parse(typeof event.data === 'string' ? event.data : event.data.toString());

package/src/chromium.js

@@ -112,7 +112,8 @@ export function findBrowser() {
  * @param {number} [opts.port=0] - CDP port (0 = random available port)
  * @param {string} [opts.userDataDir] - Browser profile directory
  * @param {boolean} [opts.headed=false] - Launch in headed mode (with visible window)
- * @returns {Promise<{wsUrl: string, process: ChildProcess, port: number}>}
+ * @param {string} [opts.proxy] - Proxy server (e.g. 'http://host:port')
+ * @returns {Promise<{wsUrl: string, process: import('node:child_process').ChildProcess, port: number}>}
  */
 export async function launch(opts = {}) {
   const binary = opts.binary || findBrowser();
@@ -235,6 +236,7 @@ export async function cleanupBrowser(browser) {
   if (!browser) return;
   activeBrowsers.delete(browser);
   if (browser.process && !browser.process.killed && browser.process.exitCode === null) {
+    /** @type {Promise<void>} */
     const exited = new Promise((resolve) => {
       const timer = setTimeout(resolve, 2000);
       browser.process.once('exit', () => { clearTimeout(timer); resolve(); });
@@ -282,7 +284,10 @@ export async function cleanupBrowser(browser) {
 export async function getDebugUrl(port) {
   const res = await fetch(`http://127.0.0.1:${port}/json/version`);
   if (!res.ok) throw new Error(`Cannot reach browser debug port at ${port}: ${res.status}`);
-  const data = await res.json();
+  const data = /** @type {{ webSocketDebuggerUrl?: string }} */ (await res.json());
+  if (!data.webSocketDebuggerUrl) {
+    throw new Error(`Browser debug port at ${port} returned no webSocketDebuggerUrl`);
+  }
   return data.webSocketDebuggerUrl;
 }