From f764ade37e86995ff395271722cea7322b6035fa Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Sat, 4 Jul 2026 12:32:10 +0000
Subject: [PATCH 1/2] feat(m3.4): @tronbrowser/sdk and `tron run`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Public developer SDK + a script runner (PRD M3.4), building on the M3.1–M3.3
Node automation runtime.

  import { tron } from '@tronbrowser/sdk';
  const browser = await tron.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto(url); const snap = await page.snapshot(); await browser.close();

  tron run ./agent.ts            # TS runs directly (Node >=24 strips types)
  tron run ./agent.js --headless --trace ./trace

- packages/sdk: Browser (session lifecycle: launch via the tron-session engine,
  hand out Pages, tear down the temp profile on close) and Page (goto/reload/
  back/forward, snapshot, click/fill/type by ref, extract, screenshot, pdf,
  eval, url/title). analyze/step/runTask are declared but throw until M3.5.
  Side-effects are injectable; launch reuses TRON_SESSION_BIN so binary
  resolution isn't duplicated.
- tron-run.mjs + tron-run-hooks.mjs: the runner registers an ESM resolver hook
  mapping @tronbrowser/sdk + /browser-core to the shipped runtime, then imports
  the user script (no node_modules, no build). --headless/--profile/--trace
  arrive via env and are honored by tron.launch().
- trace.ts: minimal --trace bundle (metadata.json + actions.jsonl) with values
  redacted (full trace/replay is M3.7).
- install.sh routes `tron run`; build-release ships browser-core + sdk dist and
  the runner files in the launcher payload.

Tests (+8): SDK lifecycle/cleanup/launch-failure with fakes, and an end-to-end
run over the real CDP WebSocket transport incl. multi-page Target.createTarget.
Verified `tron run` for JS and TS (no build) and --trace end-to-end against a
WS CDP stub. Full workspace suite green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/desktop/launcher/tron-run-hooks.mjs |  15 +++
 apps/desktop/launcher/tron-run.mjs       |  57 ++++++++++
 apps/desktop/scripts/build-release.sh    |  24 ++--
 apps/web/public/install.sh               |  10 ++
 docs/sdk-and-run.md                      |  63 +++++++++++
 packages/sdk/package.json                |   3 +
 packages/sdk/src/browser.ts              | 115 +++++++++++++++++++
 packages/sdk/src/deps.ts                 |  74 ++++++++++++
 packages/sdk/src/index.ts                |  36 +++++-
 packages/sdk/src/page.ts                 | 137 +++++++++++++++++++++++
 packages/sdk/src/sdk-e2e.test.ts         | 116 +++++++++++++++++++
 packages/sdk/src/sdk.test.ts             | 114 +++++++++++++++++++
 packages/sdk/src/trace.ts                |  47 ++++++++
 pnpm-lock.yaml                           |   5 +-
 14 files changed, 803 insertions(+), 13 deletions(-)
 create mode 100644 apps/desktop/launcher/tron-run-hooks.mjs
 create mode 100644 apps/desktop/launcher/tron-run.mjs
 create mode 100644 docs/sdk-and-run.md
 create mode 100644 packages/sdk/src/browser.ts
 create mode 100644 packages/sdk/src/deps.ts
 create mode 100644 packages/sdk/src/page.ts
 create mode 100644 packages/sdk/src/sdk-e2e.test.ts
 create mode 100644 packages/sdk/src/sdk.test.ts
 create mode 100644 packages/sdk/src/trace.ts

diff --git a/apps/desktop/launcher/tron-run-hooks.mjs b/apps/desktop/launcher/tron-run-hooks.mjs
new file mode 100644
index 0000000..66c904d
--- /dev/null
+++ b/apps/desktop/launcher/tron-run-hooks.mjs
@@ -0,0 +1,15 @@
+// ESM resolver hook for `tron run`: maps the bare `@tronbrowser/*` specifiers a
+// user script imports to the runtime shipped in the launcher payload, so scripts
+// need no node_modules of their own. Registered by tron-run.mjs.
+let map = {};
+
+export async function initialize(data) {
+  map = data ?? {};
+}
+
+export async function resolve(specifier, context, next) {
+  if (Object.prototype.hasOwnProperty.call(map, specifier)) {
+    return { url: map[specifier], shortCircuit: true };
+  }
+  return next(specifier, context);
+}
diff --git a/apps/desktop/launcher/tron-run.mjs b/apps/desktop/launcher/tron-run.mjs
new file mode 100644
index 0000000..4111e3e
--- /dev/null
+++ b/apps/desktop/launcher/tron-run.mjs
@@ -0,0 +1,57 @@
+// `tron run <script>` — execute a user JS/TS automation script that imports
+// `@tronbrowser/sdk` (PRD M3.4). Node >= 24 strips TS types natively, so .ts
+// runs with no build step. The @tronbrowser/* imports resolve to the runtime
+// shipped alongside this file via the registered resolver hook.
+import { existsSync } from 'node:fs';
+import { register } from 'node:module';
+import { dirname, resolve as resolvePath, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const sdkEntry = join(here, 'sdk', 'index.js');
+const coreEntry = join(here, 'automate', 'index.js');
+
+const argv = process.argv.slice(2);
+let script;
+const passthrough = [];
+for (let i = 0; i < argv.length; i += 1) {
+  const a = argv[i];
+  if (a === '--') { passthrough.push(...argv.slice(i + 1)); break; }
+  if (!script && !a.startsWith('-')) { script = a; continue; }
+  if (a === '--headless') { process.env.TRON_RUN_HEADLESS = '1'; continue; }
+  if (a === '--profile') { process.env.TRON_RUN_PROFILE = argv[++i]; continue; }
+  if (a === '--trace') { process.env.TRON_RUN_TRACE = resolvePath(argv[++i]); continue; }
+  passthrough.push(a);
+}
+
+if (!script) {
+  process.stderr.write('usage: tron run <script.js|.ts> [--headless] [--profile <name>] [--trace <dir>]\n');
+  process.exit(2);
+}
+
+const scriptPath = resolvePath(script);
+if (!existsSync(scriptPath)) {
+  process.stderr.write(`tron run: script not found: ${script}\n`);
+  process.exit(2);
+}
+if (!existsSync(sdkEntry)) {
+  process.stderr.write('This TronBrowser build lacks the SDK runtime. Run: tron upgrade\n');
+  process.exit(1);
+}
+
+register(pathToFileURL(join(here, 'tron-run-hooks.mjs')), import.meta.url, {
+  data: {
+    '@tronbrowser/sdk': pathToFileURL(sdkEntry).href,
+    '@tronbrowser/browser-core': pathToFileURL(coreEntry).href,
+  },
+});
+
+// Present argv to the script as if it were invoked directly.
+process.argv = [process.argv[0], scriptPath, ...passthrough];
+
+try {
+  await import(pathToFileURL(scriptPath).href);
+} catch (err) {
+  process.stderr.write(`tron run: ${err && err.stack ? err.stack : err}\n`);
+  process.exit(1);
+}
diff --git a/apps/desktop/scripts/build-release.sh b/apps/desktop/scripts/build-release.sh
index 546a922..b8a1304 100755
--- a/apps/desktop/scripts/build-release.sh
+++ b/apps/desktop/scripts/build-release.sh
@@ -51,22 +51,25 @@ fetch_marksyncr() {
   [ -n "$MKS_SRC" ] || echo "  ! MarkSyncr fetch skipped (non-fatal)"
 }
 
-# The Node automation runtime for `tron snapshot|click|fill` (PRD M3.2). The
-# @tronbrowser/browser-core source has no runtime deps, so its compiled dist tree
-# is self-contained; ship it with a {"type":"module"} marker and the shell
-# dispatcher runs it via node. Best-effort like the extension fetches — a build
-# host without node/pnpm simply omits it (the CLI then reports "run tron upgrade").
+# The Node automation runtime for `tron snapshot|click|fill|extract|...` (M3.2/3)
+# and the `@tronbrowser/sdk` used by `tron run` (M3.4). Both packages' source has
+# no runtime deps, so their compiled dist trees are self-contained; ship each with
+# a {"type":"module"} marker and the shell dispatcher / tron-run.mjs run them via
+# node. Best-effort like the extension fetches — a build host without node/pnpm
+# simply omits them (the CLI then reports "run tron upgrade").
 stage_automation() { # dest dir
   local s="$1"
   command -v node >/dev/null 2>&1 && command -v pnpm >/dev/null 2>&1 || {
     echo "  ! automation runtime skipped (needs node + pnpm)"; return; }
-  if ( cd "$REPO_ROOT" && pnpm --filter @tronbrowser/browser-core build >/dev/null 2>&1 ); then
-    rm -rf "$s/automate"
+  if ( cd "$REPO_ROOT" && pnpm --filter @tronbrowser/browser-core --filter @tronbrowser/sdk build >/dev/null 2>&1 ); then
+    rm -rf "$s/automate" "$s/sdk"
     cp -R "$REPO_ROOT/packages/browser-core/dist" "$s/automate"
     printf '{\n  "type": "module"\n}\n' > "$s/automate/package.json"
-    echo "  + bundled automation runtime (tron snapshot/click/fill)"
+    cp -R "$REPO_ROOT/packages/sdk/dist" "$s/sdk"
+    printf '{\n  "type": "module"\n}\n' > "$s/sdk/package.json"
+    echo "  + bundled automation runtime + SDK (tron snapshot/extract/run)"
   else
-    echo "  ! automation runtime skipped (browser-core build failed)"
+    echo "  ! automation runtime skipped (browser-core/sdk build failed)"
   fi
 }
 
@@ -81,6 +84,9 @@ stage() { # dest dir
   # Managed-session engine for `tron browser …` / `tron open` (PRD M3.1). Sits
   # next to the shim; the `tron` dispatcher resolves it relative to $CURRENT.
   install -m 0755 "$DESKTOP/launcher/tron-session" "$s/tron-session"
+  # `tron run` launcher + ESM resolver hook (PRD M3.4).
+  install -m 0644 "$DESKTOP/launcher/tron-run.mjs" "$s/tron-run.mjs"
+  install -m 0644 "$DESKTOP/launcher/tron-run-hooks.mjs" "$s/tron-run-hooks.mjs"
   stage_automation "$s"
   # -L dereferences the branding symlinks (icons/logo.svg -> repo-root logo.svg)
   # so the package contains real files, not dangling links.
diff --git a/apps/web/public/install.sh b/apps/web/public/install.sh
index 62dad87..94945fa 100755
--- a/apps/web/public/install.sh
+++ b/apps/web/public/install.sh
@@ -90,6 +90,7 @@ Usage:
   tron extract <mode>   Extract text|links|forms|tables|main (JSON)
   tron screenshot <p>   Save a PNG of the current page (--full-page)
   tron headless <url>   One-shot: --snapshot | --screenshot <p> | --extract <mode>
+  tron run <script>     Run a JS/TS script using @tronbrowser/sdk (--headless/--trace)
   tron upgrade          Update to the latest release
   tron remove           Uninstall TronBrowser (keeps your profile data)
   tron version          Print the installed version
@@ -178,6 +179,15 @@ case "${1:-}" in
   headless)
     # One-shot: launch a headless ephemeral session, navigate, act, tear down.
     run_automation "$@" ;;
+  run)
+    # Execute a JS/TS automation script that imports @tronbrowser/sdk (PRD M3.4).
+    shift
+    [ "$#" -gt 0 ] || { echo "usage: tron run <script.js|.ts> [--headless] [--profile <name>] [--trace <dir>]" >&2; exit 2; }
+    _ld="$(dirname "$(readlink -f "$CURRENT" 2>/dev/null || echo "$CURRENT")")"
+    RUNNER="$_ld/tron-run.mjs"
+    command -v node >/dev/null 2>&1 || { echo "tron run needs Node.js (>=24) on PATH." >&2; exit 1; }
+    [ -f "$RUNNER" ] || { echo "This TronBrowser build lacks the SDK runtime. Run: tron upgrade" >&2; exit 1; }
+    exec env TRON_SESSION_BIN="$(session_bin)" node "$RUNNER" "$@" ;;
   restart)
     # Force-quit any running TronBrowser, then launch fresh. Chromium forwards a
     # new launch to an already-running instance (which keeps the OLD extension
diff --git a/docs/sdk-and-run.md b/docs/sdk-and-run.md
new file mode 100644
index 0000000..a0ec394
--- /dev/null
+++ b/docs/sdk-and-run.md
@@ -0,0 +1,63 @@
+# SDK and `tron run` (M3.4)
+
+Write browser automation as scripts with the public SDK, and run them with
+`tron run` — no build step, no `node_modules` of your own.
+
+```ts
+import { tron } from '@tronbrowser/sdk';
+
+const browser = await tron.launch({ headless: true });
+const page = await browser.newPage();
+
+await page.goto('https://example.com/contact');
+const snap = await page.snapshot();
+const emailRef = snap.elements.find((e) => e.name === 'Email')?.ref;
+if (emailRef) await page.fill(emailRef, 'jane@example.com');
+
+console.log(await page.extract('links'));
+await page.screenshot({ fullPage: true }).then(/* … */);
+await browser.close();
+```
+
+```sh
+tron run ./agent.ts                 # TypeScript runs directly (Node ≥24 strips types)
+tron run ./agent.js
+tron run ./agent.ts --headless      # force headless regardless of launch({})
+tron run ./agent.ts --profile work  # use a named profile
+tron run ./agent.ts --trace ./trace # write an action trace bundle
+```
+
+## API (`@tronbrowser/sdk`)
+
+- **`tron.launch(options?)` → `Browser`** — `{ headless?, profile? }`. Starts a
+  managed session in its own isolated temp profile.
+- **`Browser`**: `newPage()`, `pages()`, `close()` (stops the session, removes
+  the temp profile).
+- **`Page`**: `goto`, `reload`, `back`, `forward`, `snapshot`/`snapshotText`,
+  `click(@ref)`, `fill(@ref, value)`, `type`, `extract(target, fields?)`,
+  `screenshot`, `pdf`, `eval`, `url`, `title`, `close`.
+- `analyze` / `step` / `runTask` are declared but land in **M3.5** (AI analyze).
+
+## How `tron run` works
+
+- The shell `tron` dispatcher runs `tron-run.mjs` via `node`, passing
+  `TRON_SESSION_BIN` so the SDK can launch/close a managed session.
+- `tron-run.mjs` registers an ESM resolver hook that maps `@tronbrowser/sdk`
+  and `@tronbrowser/browser-core` to the runtime shipped in the launcher payload,
+  then imports your script. TypeScript needs no build — Node ≥24 strips types.
+- `--headless` / `--profile` / `--trace` arrive via env and are honored by
+  `tron.launch()` when the script doesn't specify otherwise.
+
+## Trace bundles (`--trace <dir>`)
+
+A minimal trace (full trace/replay is M3.7): `metadata.json` plus
+`actions.jsonl` — the sequence of page actions. **Values are redacted** (a
+`fill` records its ref, never the text), matching the PRD's default privacy.
+
+## Scope / limitations
+
+- Requires Node ≥24 (bundled with the desktop app or on PATH).
+- `click`/`fill` take `@refs` from a `snapshot`; richer targets (CSS/text/role)
+  and character-level `type`/`press` come later.
+- SDK contracts are unit-tested and exercised end-to-end over the real CDP
+  transport in `packages/sdk/src/*.test.ts`.
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index d17925a..ae73f92 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -18,6 +18,9 @@
     "test": "vitest run --passWithNoTests",
     "lint": "eslint src"
   },
+  "dependencies": {
+    "@tronbrowser/browser-core": "workspace:*"
+  },
   "devDependencies": {
     "typescript": "^5.6.3",
     "vitest": "^2.1.4"
diff --git a/packages/sdk/src/browser.ts b/packages/sdk/src/browser.ts
new file mode 100644
index 0000000..cc4dc21
--- /dev/null
+++ b/packages/sdk/src/browser.ts
@@ -0,0 +1,115 @@
+/**
+ * A managed browser session (PRD M3.4 / §15.1). `tron.launch()` starts a
+ * `tron-session`, and each Browser owns that session's lifecycle: it hands out
+ * Page objects (one CDP connection per tab) and tears the session down on close.
+ */
+import type { CdpConnection, CdpTarget, SessionDescriptor } from '@tronbrowser/browser-core';
+import { defaultDeps, type SdkDeps } from './deps.js';
+import { Page } from './page.js';
+import { Tracer, tracerFromEnv } from './trace.js';
+
+export interface LaunchOptions {
+  headless?: boolean;
+  profile?: string;
+}
+
+export class Browser {
+  readonly #deps: SdkDeps;
+  readonly #dataDir: string;
+  readonly #descriptor: SessionDescriptor;
+  readonly #pages: Page[] = [];
+  readonly #usedTargets = new Set<string>();
+  readonly #tracer: Tracer | undefined;
+  readonly #traceDir: string | undefined;
+  #browserConn: CdpConnection | undefined;
+  #closed = false;
+
+  private constructor(
+    deps: SdkDeps,
+    dataDir: string,
+    descriptor: SessionDescriptor,
+    trace?: { tracer: Tracer; dir: string },
+  ) {
+    this.#deps = deps;
+    this.#dataDir = dataDir;
+    this.#descriptor = descriptor;
+    this.#tracer = trace?.tracer;
+    this.#traceDir = trace?.dir;
+  }
+
+  /** Launch a managed session and return a Browser. */
+  static async launch(options: LaunchOptions = {}, deps: SdkDeps = defaultDeps): Promise<Browser> {
+    // CLI flags from `tron run` arrive via env and win when the script is neutral.
+    const headless = options.headless ?? process.env.TRON_RUN_HEADLESS === '1';
+    const profile = options.profile ?? process.env.TRON_RUN_PROFILE;
+    const dataDir = await deps.makeDataDir();
+    try {
+      await deps.launchSession(dataDir, {
+        headless,
+        ...(profile !== undefined ? { profile } : {}),
+      });
+      const descriptor = await deps.loadDescriptor(dataDir);
+      return new Browser(deps, dataDir, descriptor, tracerFromEnv(process.env));
+    } catch (err) {
+      await deps.closeSession(dataDir).catch(() => {});
+      await deps.removeDataDir(dataDir).catch(() => {});
+      throw err;
+    }
+  }
+
+  #targets(): Promise<CdpTarget[]> {
+    return this.#deps.fetchTargets(this.#descriptor.host, this.#descriptor.port);
+  }
+
+  /** Open (or adopt the first free) page target and return a Page for it. */
+  async newPage(): Promise<Page> {
+    if (this.#closed) throw new Error('Browser is closed');
+
+    let target = (await this.#targets()).find(
+      (t) => t.type === 'page' && !this.#usedTargets.has(t.id),
+    );
+    if (!target) target = await this.#createTarget();
+    if (!target.webSocketDebuggerUrl) {
+      throw new Error(`Page target ${target.id} has no webSocketDebuggerUrl`);
+    }
+
+    const conn = await this.#deps.connect(target.webSocketDebuggerUrl);
+    const page = await Page.attach(conn, target.id, this.#tracer);
+    this.#usedTargets.add(target.id);
+    this.#pages.push(page);
+    return page;
+  }
+
+  async #createTarget(): Promise<CdpTarget> {
+    if (!this.#descriptor.webSocketDebuggerUrl) {
+      throw new Error('Cannot open another page: session has no browser WebSocket endpoint');
+    }
+    this.#browserConn ??= await this.#deps.connect(this.#descriptor.webSocketDebuggerUrl);
+    const { targetId } = await this.#browserConn.send<{ targetId: string }>('Target.createTarget', {
+      url: 'about:blank',
+    });
+    const created = (await this.#targets()).find((t) => t.id === targetId);
+    if (!created) throw new Error('Newly created page target did not appear');
+    return created;
+  }
+
+  /** Pages opened so far. */
+  pages(): Page[] {
+    return [...this.#pages];
+  }
+
+  /** Close every page, stop the managed session, and remove its temp profile. */
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+    for (const page of this.#pages) page.close();
+    this.#browserConn?.close();
+    if (this.#tracer && this.#traceDir) {
+      await this.#tracer
+        .flush(this.#traceDir, { headless: this.#descriptor.headless, profile: this.#descriptor.profileName })
+        .catch(() => {});
+    }
+    await this.#deps.closeSession(this.#dataDir).catch(() => {});
+    await this.#deps.removeDataDir(this.#dataDir).catch(() => {});
+  }
+}
diff --git a/packages/sdk/src/deps.ts b/packages/sdk/src/deps.ts
new file mode 100644
index 0000000..f1c071b
--- /dev/null
+++ b/packages/sdk/src/deps.ts
@@ -0,0 +1,74 @@
+/**
+ * Injectable side-effects for the SDK (PRD M3.4). The public `tron.launch` uses
+ * the real defaults below; tests inject fakes to exercise Browser/Page without a
+ * real browser. Launch reuses the M3.1 `tron-session` engine (resolved via
+ * TRON_SESSION_BIN, which `tron run` sets) so binary resolution isn't duplicated.
+ */
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import {
+  CdpClient,
+  cdpListUrl,
+  descriptorPath,
+  parseDescriptor,
+  type CdpConnection,
+  type CdpTarget,
+  type SessionDescriptor,
+} from '@tronbrowser/browser-core';
+
+const execFileP = promisify(execFile);
+
+export interface LaunchArgs {
+  headless: boolean;
+  profile?: string;
+}
+
+export interface SdkDeps {
+  makeDataDir(): Promise<string>;
+  removeDataDir(dir: string): Promise<void>;
+  launchSession(dataDir: string, args: LaunchArgs): Promise<void>;
+  closeSession(dataDir: string): Promise<void>;
+  loadDescriptor(dataDir: string): Promise<SessionDescriptor>;
+  fetchTargets(host: string, port: number): Promise<CdpTarget[]>;
+  connect(wsUrl: string): Promise<CdpConnection>;
+  writeBytes(path: string, bytes: Uint8Array): Promise<void>;
+}
+
+function sessionBin(): string {
+  const bin = process.env.TRON_SESSION_BIN ?? process.env.TRONBROWSER_SESSION_BIN;
+  if (!bin) {
+    throw new Error(
+      'The SDK needs the managed-session engine. Run scripts with `tron run`, or set TRON_SESSION_BIN.',
+    );
+  }
+  return bin;
+}
+
+export const defaultDeps: SdkDeps = {
+  makeDataDir: () => mkdtemp(join(tmpdir(), 'tron-sdk-')),
+  removeDataDir: (dir) => rm(dir, { recursive: true, force: true }),
+  async launchSession(dataDir, args) {
+    const argv = ['browser', 'launch'];
+    if (args.headless) argv.push('--headless');
+    if (args.profile) argv.push('--profile', args.profile);
+    await execFileP(sessionBin(), argv, { env: { ...process.env, TRONBROWSER_DATA: dataDir } });
+  },
+  async closeSession(dataDir) {
+    await execFileP(sessionBin(), ['browser', 'close'], {
+      env: { ...process.env, TRONBROWSER_DATA: dataDir },
+    });
+  },
+  async loadDescriptor(dataDir) {
+    return parseDescriptor(await readFile(descriptorPath(dataDir), 'utf8'));
+  },
+  async fetchTargets(host, port) {
+    const res = await fetch(cdpListUrl({ host, port }));
+    if (!res.ok) throw new Error(`DevTools /json/list returned ${res.status}`);
+    return (await res.json()) as CdpTarget[];
+  },
+  connect: (wsUrl) => CdpClient.connect(wsUrl),
+  writeBytes: (path, bytes) => writeFile(path, bytes),
+};
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index 71ab25f..2428fc4 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -1,7 +1,37 @@
 /**
- * @tronbrowser/sdk
- * Public SDK for TronBrowser apps and plugins
+ * @tronbrowser/sdk — public TypeScript/JavaScript SDK for TronBrowser
+ * automation (PRD M3.4).
  *
- * Stub — see ../../docs/tronbrowser-prd.md
+ *   import { tron } from '@tronbrowser/sdk';
+ *   const browser = await tron.launch({ headless: true });
+ *   const page = await browser.newPage();
+ *   await page.goto('https://example.com/contact');
+ *   const snap = await page.snapshot();
+ *   await browser.close();
+ *
+ * Run scripts with `tron run ./script.ts` (or .js), which provides the managed
+ * browser engine the SDK drives.
  */
 export const PACKAGE_NAME = '@tronbrowser/sdk' as const;
+
+export { Browser, type LaunchOptions } from './browser.js';
+export { Page } from './page.js';
+export type { SdkDeps, LaunchArgs } from './deps.js';
+
+// Re-export the shared automation types so scripts can annotate results.
+export type {
+  AgentSnapshot,
+  SnapshotElement,
+  AutomationTab,
+  FieldSpec,
+} from '@tronbrowser/browser-core';
+
+import { Browser, type LaunchOptions } from './browser.js';
+import type { SdkDeps } from './deps.js';
+
+/** The public entrypoint: `tron.launch(...)`. */
+export const tron = {
+  launch(options: LaunchOptions = {}, deps?: SdkDeps): Promise<Browser> {
+    return deps ? Browser.launch(options, deps) : Browser.launch(options);
+  },
+};
diff --git a/packages/sdk/src/page.ts b/packages/sdk/src/page.ts
new file mode 100644
index 0000000..1d80f16
--- /dev/null
+++ b/packages/sdk/src/page.ts
@@ -0,0 +1,137 @@
+/**
+ * A page in a managed session (PRD M3.4 / §15.2). Wraps a persistent CDP
+ * connection to one page target and exposes the automation primitives from
+ * @tronbrowser/browser-core with a clean, CDP-free API.
+ */
+import {
+  captureSnapshot,
+  clickRef,
+  enableRuntime,
+  extract as evalExpression,
+  extractExpression,
+  fillRef,
+  formatSnapshotText,
+  goto,
+  printPdf,
+  screenshotPng,
+  type AgentSnapshot,
+  type CdpConnection,
+  type FieldSpec,
+  type ScreenshotOptions,
+  type SnapshotOptions,
+} from '@tronbrowser/browser-core';
+import type { Tracer } from './trace.js';
+
+/** Analyze/step/runTask land in M3.5; the surface exists so scripts type-check. */
+function notYet(name: string): never {
+  throw new Error(`page.${name}() arrives in M3.5 (AI analyze). Not available yet.`);
+}
+
+export class Page {
+  readonly #conn: CdpConnection;
+  readonly #tracer: Tracer | undefined;
+  readonly id: string;
+  #closed = false;
+
+  /** @internal — use Browser.newPage(). */
+  constructor(conn: CdpConnection, targetId: string, tracer?: Tracer) {
+    this.#conn = conn;
+    this.id = targetId;
+    this.#tracer = tracer;
+  }
+
+  /** @internal */
+  static async attach(conn: CdpConnection, targetId: string, tracer?: Tracer): Promise<Page> {
+    await enableRuntime(conn);
+    await conn.send('Page.enable');
+    return new Page(conn, targetId, tracer);
+  }
+
+  async goto(url: string, options: { timeoutMs?: number } = {}): Promise<void> {
+    this.#tracer?.record('goto', url);
+    await goto(this.#conn, url, options);
+  }
+
+  reload(): Promise<void> {
+    this.#tracer?.record('reload');
+    return this.#conn.send('Page.reload').then(() => undefined);
+  }
+
+  back(): Promise<void> {
+    this.#tracer?.record('back');
+    return this.eval('history.back()').then(() => undefined);
+  }
+
+  forward(): Promise<void> {
+    this.#tracer?.record('forward');
+    return this.eval('history.forward()').then(() => undefined);
+  }
+
+  snapshot(options: SnapshotOptions = {}): Promise<AgentSnapshot> {
+    this.#tracer?.record('snapshot');
+    return captureSnapshot(this.#conn, options);
+  }
+
+  async snapshotText(options: SnapshotOptions = {}): Promise<string> {
+    return formatSnapshotText(await this.snapshot(options));
+  }
+
+  async click(ref: string): Promise<void> {
+    this.#tracer?.record('click', ref);
+    await clickRef(this.#conn, ref);
+  }
+
+  async fill(ref: string, value: string): Promise<void> {
+    this.#tracer?.record('fill', ref); // value redacted from the trace
+    await fillRef(this.#conn, ref, value);
+  }
+
+  /** Alias of fill for MVP (character-level typing lands with richer input in M3.5+). */
+  type(ref: string, value: string): Promise<void> {
+    return this.fill(ref, value);
+  }
+
+  extract<T = unknown>(target: string, fields: FieldSpec[] = []): Promise<T> {
+    this.#tracer?.record('extract', target);
+    return evalExpression<T>(this.#conn, extractExpression(target, fields));
+  }
+
+  eval<T = unknown>(code: string): Promise<T> {
+    return evalExpression<T>(this.#conn, code);
+  }
+
+  screenshot(options: ScreenshotOptions = {}): Promise<Uint8Array> {
+    this.#tracer?.record('screenshot');
+    return screenshotPng(this.#conn, options);
+  }
+
+  pdf(): Promise<Uint8Array> {
+    this.#tracer?.record('pdf');
+    return printPdf(this.#conn);
+  }
+
+  url(): Promise<string> {
+    return this.eval<string>('location.href');
+  }
+
+  title(): Promise<string> {
+    return this.eval<string>('document.title');
+  }
+
+  analyze(): never {
+    return notYet('analyze');
+  }
+  step(): never {
+    return notYet('step');
+  }
+  runTask(): never {
+    return notYet('runTask');
+  }
+
+  /** @internal */
+  close(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#conn.close();
+  }
+}
diff --git a/packages/sdk/src/sdk-e2e.test.ts b/packages/sdk/src/sdk-e2e.test.ts
new file mode 100644
index 0000000..a279ecd
--- /dev/null
+++ b/packages/sdk/src/sdk-e2e.test.ts
@@ -0,0 +1,116 @@
+// End-to-end: the SDK drives a page over a REAL CdpClient/WebSocket against a
+// mock DevTools server. Only the session launch is faked (no real browser); the
+// fetch + CDP transport are real, covering newPage() connect and Page ops.
+import { createHash } from 'node:crypto';
+import { createServer, type Server } from 'node:http';
+import type { Socket } from 'node:net';
+import { afterEach, describe, expect, it } from 'vitest';
+import type { SessionDescriptor } from '@tronbrowser/browser-core';
+import { tron } from './index.js';
+import { defaultDeps, type SdkDeps } from './deps.js';
+
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+const SNAP = { url: 'https://example.com/', title: 'Example', timestamp: 't', elements: [] };
+
+function decode(b: Buffer): string | null {
+  if ((b[0] & 0x0f) === 0x8) return null;
+  const masked = (b[1] & 0x80) !== 0;
+  let len = b[1] & 0x7f; let o = 2;
+  if (len === 126) { len = b.readUInt16BE(2); o = 4; }
+  let mask: Buffer | null = null;
+  if (masked) { mask = b.subarray(o, o + 4); o += 4; }
+  const p = b.subarray(o, o + len); const out = Buffer.alloc(len);
+  for (let i = 0; i < len; i += 1) out[i] = mask ? p[i] ^ mask[i % 4] : p[i];
+  return out.toString('utf8');
+}
+function encode(s: string): Buffer {
+  const p = Buffer.from(s);
+  if (p.length < 126) return Buffer.concat([Buffer.from([0x81, p.length]), p]);
+  const h = Buffer.alloc(4); h[0] = 0x81; h[1] = 126; h.writeUInt16BE(p.length, 2);
+  return Buffer.concat([h, p]);
+}
+
+interface Mock { port: number; close: () => Promise<void> }
+
+async function startMock(): Promise<Mock> {
+  const sockets = new Set<Socket>();
+  const pages = ['p1'];
+  const server: Server = createServer((req, res) => {
+    const port = (server.address() as { port: number }).port;
+    if (req.url === '/json/version') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ webSocketDebuggerUrl: `ws://127.0.0.1:${port}/devtools/browser/b` }));
+      return;
+    }
+    if (req.url === '/json' || req.url === '/json/list') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(pages.map((id) => ({ id, type: 'page', url: 'https://example.com/', webSocketDebuggerUrl: `ws://127.0.0.1:${port}/devtools/page/${id}` }))));
+      return;
+    }
+    res.writeHead(404).end();
+  });
+  server.on('upgrade', (req, socket) => {
+    sockets.add(socket as Socket);
+    socket.on('close', () => sockets.delete(socket as Socket));
+    const accept = createHash('sha1').update((req.headers['sec-websocket-key'] ?? '') + GUID).digest('base64');
+    socket.write('HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ' + accept + '\r\n\r\n');
+    socket.on('data', (buf: Buffer) => {
+      const t = decode(buf);
+      if (t === null) { socket.destroy(); return; }
+      const m = JSON.parse(t) as { id: number; method: string };
+      let result: Record<string, unknown> = {};
+      if (m.method === 'Runtime.evaluate') result = { result: { result: { value: SNAP } } };
+      else if (m.method === 'Target.createTarget') { pages.push('p2'); result = { result: { targetId: 'p2' } }; }
+      socket.write(encode(JSON.stringify({ id: m.id, ...result })));
+      if (m.method === 'Page.navigate') socket.write(encode(JSON.stringify({ method: 'Page.loadEventFired', params: {} })));
+    });
+    socket.on('error', () => {});
+  });
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', r));
+  return {
+    port: (server.address() as { port: number }).port,
+    close: () => new Promise<void>((r) => { for (const s of sockets) s.destroy(); server.close(() => r()); }),
+  };
+}
+
+/** Deps with a real transport but a faked (browser-less) session. */
+function mockDeps(port: number): SdkDeps {
+  const descriptor: SessionDescriptor = {
+    version: 1, pid: 1, host: '127.0.0.1', port, profileDir: '/x', profileName: 'ephemeral',
+    headless: true, ephemeral: true, createdAt: 't',
+    webSocketDebuggerUrl: `ws://127.0.0.1:${port}/devtools/browser/b`,
+  };
+  return {
+    ...defaultDeps,
+    makeDataDir: async () => '/tmp/sdk-e2e',
+    removeDataDir: async () => {},
+    launchSession: async () => {},
+    closeSession: async () => {},
+    loadDescriptor: async () => descriptor,
+  };
+}
+
+let mock: Mock;
+afterEach(async () => { await mock.close(); });
+
+describe('SDK over the real CDP transport', () => {
+  it('launches, opens a page, navigates, and snapshots', async () => {
+    mock = await startMock();
+    const browser = await tron.launch({ headless: true }, mockDeps(mock.port));
+    const page = await browser.newPage();
+    await page.goto('https://example.com');
+    expect((await page.snapshot()).title).toBe('Example');
+    await browser.close();
+  });
+
+  it('opens a second page via Target.createTarget', async () => {
+    mock = await startMock();
+    const browser = await tron.launch({}, mockDeps(mock.port));
+    const p1 = await browser.newPage();
+    const p2 = await browser.newPage();
+    expect(p1.id).toBe('p1');
+    expect(p2.id).toBe('p2');
+    expect(browser.pages()).toHaveLength(2);
+    await browser.close();
+  });
+});
diff --git a/packages/sdk/src/sdk.test.ts b/packages/sdk/src/sdk.test.ts
new file mode 100644
index 0000000..86fa25a
--- /dev/null
+++ b/packages/sdk/src/sdk.test.ts
@@ -0,0 +1,114 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { CdpConnection, CdpTarget, SessionDescriptor } from '@tronbrowser/browser-core';
+import { tron } from './index.js';
+import type { SdkDeps } from './deps.js';
+
+const descriptor: SessionDescriptor = {
+  version: 1, pid: 1, host: '127.0.0.1', port: 9222, profileDir: '/x',
+  profileName: 'ephemeral', headless: true, ephemeral: true,
+  createdAt: '2026-07-04T00:00:00.000Z', activeTabId: 'p1',
+  webSocketDebuggerUrl: 'ws://127.0.0.1:9222/devtools/browser/b',
+};
+
+/** Fake CDP connection: canned Runtime.evaluate value; simulates navigate load. */
+function fakeConn(evalValue: unknown, methods: Record<string, unknown> = {}): CdpConnection {
+  const evs: Record<string, (p: unknown) => void> = {};
+  return {
+    send: (async (method: string) => {
+      if (method === 'Page.navigate') {
+        queueMicrotask(() => evs['Page.loadEventFired']?.({}));
+        return {};
+      }
+      if (method === 'Runtime.evaluate') return { result: { value: evalValue } };
+      return methods[method] ?? {};
+    }) as CdpConnection['send'],
+    on: (m: string, h: (p: unknown) => void) => {
+      evs[m] = h;
+    },
+    close: vi.fn(),
+  };
+}
+
+function fakeDeps(conn: CdpConnection, overrides: Partial<SdkDeps> = {}) {
+  const calls: string[] = [];
+  const targets: CdpTarget[] = [
+    { id: 'p1', type: 'page', url: 'about:blank', webSocketDebuggerUrl: 'ws://x/p1' },
+  ];
+  const deps: SdkDeps = {
+    makeDataDir: async () => '/tmp/sdk-test',
+    removeDataDir: async () => {
+      calls.push('rm');
+    },
+    launchSession: async (_d, a) => {
+      calls.push(`launch:${a.headless ? 'headless' : 'headed'}:${a.profile ?? '-'}`);
+    },
+    closeSession: async () => {
+      calls.push('close');
+    },
+    loadDescriptor: async () => descriptor,
+    fetchTargets: async () => targets,
+    connect: async () => conn,
+    writeBytes: async () => {},
+    ...overrides,
+  };
+  return { deps, calls };
+}
+
+describe('tron.launch lifecycle', () => {
+  it('launches headless, opens a page, and snapshots', async () => {
+    const snap = { url: 'u', title: 'T', timestamp: 't', elements: [] };
+    const { deps, calls } = fakeDeps(fakeConn(snap));
+    const browser = await tron.launch({ headless: true }, deps);
+    expect(calls[0]).toBe('launch:headless:-');
+    const page = await browser.newPage();
+    await page.goto('https://example.com');
+    expect((await page.snapshot()).title).toBe('T');
+    await browser.close();
+    expect(calls).toContain('close');
+    expect(calls).toContain('rm');
+  });
+
+  it('passes a named profile through to the session engine', async () => {
+    const { deps, calls } = fakeDeps(fakeConn(null));
+    const browser = await tron.launch({ profile: 'work' }, deps);
+    expect(calls[0]).toBe('launch:headed:work');
+    await browser.close();
+  });
+
+  it('tears down the session if launch fails', async () => {
+    const { deps, calls } = fakeDeps(fakeConn(null), {
+      loadDescriptor: async () => {
+        throw new Error('never came up');
+      },
+    });
+    await expect(tron.launch({}, deps)).rejects.toThrow(/never came up/);
+    expect(calls).toContain('close');
+    expect(calls).toContain('rm');
+  });
+
+  it('extracts and reads url/title via the page', async () => {
+    const { deps } = fakeDeps(fakeConn([{ text: 'A', href: 'https://x/a' }]));
+    const browser = await tron.launch({}, deps);
+    const page = await browser.newPage();
+    expect(await page.extract('links')).toEqual([{ text: 'A', href: 'https://x/a' }]);
+    await browser.close();
+  });
+
+  it('captures a screenshot through the page', async () => {
+    const png = { 'Page.captureScreenshot': { data: Buffer.from('PNG').toString('base64') } };
+    const { deps } = fakeDeps(fakeConn(null, png));
+    const browser = await tron.launch({ headless: true }, deps);
+    const page = await browser.newPage();
+    const bytes = await page.screenshot();
+    expect(Buffer.from(bytes).toString()).toBe('PNG');
+    await browser.close();
+  });
+
+  it('surfaces analyze() as an M3.5 feature', async () => {
+    const { deps } = fakeDeps(fakeConn(null));
+    const browser = await tron.launch({}, deps);
+    const page = await browser.newPage();
+    expect(() => page.analyze()).toThrow(/M3\.5/);
+    await browser.close();
+  });
+});
diff --git a/packages/sdk/src/trace.ts b/packages/sdk/src/trace.ts
new file mode 100644
index 0000000..e5ae57e
--- /dev/null
+++ b/packages/sdk/src/trace.ts
@@ -0,0 +1,47 @@
+/**
+ * Minimal action trace for `tron run --trace <dir>` (PRD M3.4; full trace/replay
+ * is M3.7). Records the sequence of page actions — never their values (form
+ * input, secrets are redacted by default) — and flushes a small bundle on close.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface TraceEntry {
+  t: string;
+  action: string;
+  detail?: string;
+}
+
+export class Tracer {
+  readonly #entries: TraceEntry[] = [];
+
+  /** Record an action. `detail` should be a ref/url/mode — never a value. */
+  record(action: string, detail?: string): void {
+    this.#entries.push({
+      t: new Date().toISOString(),
+      action,
+      ...(detail !== undefined ? { detail } : {}),
+    });
+  }
+
+  get entries(): readonly TraceEntry[] {
+    return this.#entries;
+  }
+
+  /** Write metadata.json + actions.jsonl to the trace directory. */
+  async flush(dir: string, meta: Record<string, unknown>): Promise<void> {
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      join(dir, 'metadata.json'),
+      JSON.stringify({ ...meta, actions: this.#entries.length, finishedAt: new Date().toISOString() }, null, 2) + '\n',
+    );
+    await writeFile(dir + '/actions.jsonl', this.#entries.map((e) => JSON.stringify(e)).join('\n') + '\n');
+  }
+}
+
+/** A Tracer when `TRON_RUN_TRACE` names a directory, else undefined. */
+export function tracerFromEnv(env: NodeJS.ProcessEnv): { tracer: Tracer; dir: string } | undefined {
+  const dir = env.TRON_RUN_TRACE;
+  if (!dir) return undefined;
+  return { tracer: new Tracer(), dir };
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 160a2b6..76c09cc 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -170,6 +170,10 @@ importers:
         version: 2.1.9(@types/node@24.13.2)(happy-dom@20.10.6)(lightningcss@1.32.0)(terser@5.48.0)
 
   packages/sdk:
+    dependencies:
+      '@tronbrowser/browser-core':
+        specifier: workspace:*
+        version: link:../browser-core
     devDependencies:
       typescript:
         specifier: ^5.6.3
@@ -2398,7 +2402,6 @@ packages:
 
   libsql@0.4.7:
     resolution: {integrity: sha512-T9eIRCs6b0J1SHKYIvD8+KCJMcWZ900iZyxdnSCdqxN12Z1ijzT+jY5nrk72Jw4B0HGzms2NgpryArlJqvc3Lw==}
-    cpu: [x64, arm64, wasm32]
     os: [darwin, linux, win32]
 
   lighthouse-logger@1.4.2:

From e0893d45a485ee34dcb8cfc7753efd8c494a7711 Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Sat, 4 Jul 2026 12:42:09 +0000
Subject: [PATCH 2/2] ci: build before typecheck/test so cross-package deps
 resolve

@tronbrowser/sdk imports @tronbrowser/browser-core and resolves it via its
built dist, so typecheck/test need the dist present. pnpm builds in topological
order (browser-core before sdk), so building first fixes the resolution.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b995dd4..28afc99 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -25,15 +25,19 @@ jobs:
       - name: Lint
         run: pnpm lint
 
+      # Build first: packages that import another workspace package (e.g.
+      # @tronbrowser/sdk -> @tronbrowser/browser-core) resolve it via its built
+      # dist, so typecheck/test need the dist present. pnpm builds in topological
+      # order, so dependencies compile before their dependents.
+      - name: Build
+        run: pnpm build
+
       - name: Typecheck
         run: pnpm typecheck
 
       - name: Test
         run: pnpm test
 
-      - name: Build
-        run: pnpm build
-
   # package + release jobs are stubbed until the Chromium build lands in CI.
   package:
     runs-on: ubuntu-latest