ego-lite Documentation

Technical Documentation: citrolabs/ego-lite

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

ego (lite) is a browser where you and your AI agents work in parallel. Your agents run their browser tasks in their own Spaces, isolated workspaces inside the same browser, while you keep browsing in yours, so no agent ever takes the browser away from you. And the automation itself finishes faster, on fewer tokens.

Existing tools like browser-use and agent-browser are a bridge to the browser, not a browser of their own: they need a separate one to drive, your browser data rarely carries over intact, the connection is unstable, and you and the agent end up fighting over control of the browser. ego lite is one browser designed from the start for the two of you to share. No extra setup, and the agent can always reach your real logins and tabs through ego-browser.

Demo Copy Chapter

https://github.com/user-attachments/assets/ffe7954b-58ee-411e-b35d-ec30c58a08bc

Quick Start Copy Chapter

ego lite runs on macOS today, a Windows closed beta is coming soon, and Linux is on the roadmap.

1. Install Copy Section

Pick whichever fits your flow.

1.1 Download the macOS app

Click to download, then open it to install. Either way, ego lite adds the ego-browser skill to every agent's skills directory on your machine.

1.2 Add the skill with npx

Install just the ego-browser skill:

npx skills add citrolabs/ego-lite

The first time your agent runs a browser task, it walks you through installing the ego lite app.

1.3 Let your agent set it up

Paste this into your agent:

Set up ego lite for me: https://github.com/citrolabs/ego-lite

Read `skills/ego-browser/references/install.md` and follow the steps to install ego lite.

On first launch, ego lite asks one question, whether to migrate your Chrome data. Say yes and your agent inherits your existing logins, cookies, extensions, and bookmarks.

2. Try your first task Copy Section

In your agent CLI, type /ego-browser followed by a space, then describe what you want in plain language:

ego-browser follow @ego_agent on x.com for me

The agent picks up the ego-browser skill, opens the page in its own Space, reads a Snapshot (the page turned into structured text), acts on the page, and reports back, all while your own tabs stay untouched.

Your browsing data, cookies, and everything else the browser holds stay on your device. ego lite keeps its data collection deliberately narrow: simple product signals, like whether you've set ego lite as your default browser.

Highlights of ego lite Copy Chapter

ego lite vs existing products Copy Chapter

Most tools can automate a browser. The real questions are what browser the agent gets, whether you can keep working at the same time, and whether the tool is built for the agent you already use or a built-in one.

Two other categories try to solve the same problem. Browser automation frameworks like Browser-Use and Vercel's agent-browser are libraries the agent calls; they ship no browser of their own, so they need a separate one to drive and your logins rarely carry cleanly. AI browsers like ChatGPT Atlas and Perplexity Comet ship a built-in agent, and only that agent can drive the browser. ego lite is one browser, designed from the start for you and any agent you bring to share.

Benchmarks Copy Chapter

We benchmarked ego lite against Vercel's agent-browser on four complex browser automation tasks. ego lite finished each task up to 2.5× faster, with substantially fewer tokens. The harder the task, the bigger the gap. See the comparison below.

Docs Copy Chapter

Tutorials, the full tool reference, and integration guides live at lite.ego.app/document/.

Community Copy Chapter

• Discord, questions, setup help, and skill sharing
• GitHub Discussions, ideas and longer threads
• X/Twitter, updates and releases

Star History Copy Chapter

License Copy Chapter

The contents of this repository are released under the MIT License. The ego lite browser is a separate, free download.

Overview (`package/ego-browser/README.md`) Copy Section

ego-browser (Node helper runtime)

The Node.js helper layer that runs inside the ego-browser Chromium browser. The browser exposes an ego runtime (tabs, CDP, snapshots, task spaces); this package bundles the agent-facing helpers that script that runtime.

ego-browser (Chromium) → globalThis.ego → helper functions → agent heredoc

Build and run Copy Chapter

npm ci
npm run build     # bundle to dist/out/index.js
npm test          # build + tsc --noEmit + node --test

The build emits a single ESM file dist/out/index.js. The ego-browser browser dispatches ego-browser nodejs <<'EOF' ... EOF heredocs to that bundle. The v2 TaskSpace and Page APIs are preloaded; the v1 global helpers remain available only for existing scripts.

ego-browser nodejs <<'EOF'
const task = await taskSpace('demo')
const page = task.page('p1')
await page.goto('https://example.com')
console.log(await page.snapshot())
EOF

Local invocation without the browser (for debugging the helper bundle itself) reads stdin:

node dist/out/index.js <<'JS'
help()
JS

Use -h or --help to print the local CLI usage.

Skill workspace Copy Chapter

The usage guide lives in skill-body/SKILL.md; the build renders it to dist/out/ego-browser/SKILL.md, where ego-browser skill prints it. Site learnings live in the entry Skill at ../../skills/ego-browser/learnings/; the build copies the entry Skill to dist/out/agent-skills/ego-browser. By default the runtime loads agent helpers and site learnings from that bundled entry Skill:

dist/out/agent-skills/ego-browser

Override with EGO_BROWSER_AGENT_WORKSPACE:

EGO_BROWSER_AGENT_WORKSPACE=/path/to/skill ego-browser nodejs <<'EOF'
cliLog(await siteSkills())
EOF

Site learnings under agentWorkspace()/learnings/<site>/ are always active and read on every helper call. Validate them with:

npm run validate:site-skills

Source layout Copy Chapter

src/
  run.ts                 CLI entry; reads stdin, injects helpers, executes
  helpers.ts             public helper surface (re-exports + glue)
  page-model.ts          TaskSpace/Page lifecycle and operations
  public-api-schema.ts   v2 validation, help, and reference source
  browser-runtime.ts     bridge to globalThis.ego (CDP, sessions, events)
  element-resolver.ts    resolves @N / CSS / XPath / ARIA targets
  driver/
    pointer.ts           click, hover, drag, scroll, scrollBy
    observe.ts           snapshot, captureScreenshot, elementCenter
    keyboard.ts          typeText, pressKey, fillInput, dispatchKey
    nav.ts               tabs, gotoUrl, openOrReuseTab, closeTab
    load.ts              waitForLoad and load orchestration
    waits.ts             waitForElement, waitForNetworkIdle, wait
    files.ts             uploadFile
  http.ts                serverFetch, browserFetch
  cdp-eval.ts            cdp() and js() raw eval
  learning/              site-learnings discovery and manifest validation
scripts/
  build.mjs              esbuild bundling

See skill-body/SKILL.md for the agent-facing workflow and help() for the v2
API reference.
The old global helpers remain available as a v1 compatibility surface for
existing scripts.

Design constraints Copy Chapter

• The browser runtime owns tabs, task spaces, CDP transport, snapshots, and event delivery. This package keeps only agent-facing ergonomics.
• Snapshot helpers use the browser runtime contract: ego.snapshot({ scope, root, includeActionMarks, includeStableLocator }); the Page API resolves a subtree root from a Page-scoped snapshot ref before invoking it.
• V2 Page refs are SDK-assigned ids bound to a frame, document, and backend node. Input actions preserve refs to unchanged nodes, allowing consecutive ref actions. Partial snapshots retain omitted refs; full-page snapshots replace the active set. The Page ledger persists mappings and invalidation across Agent rounds. Missing, stale, or unresolvable refs require a fresh snapshot rather than native renumbering or role/name fallback.
• Page selectors search the top document first. Input actions search frames
  when the top document has no match usable for that action, then require one
  usable frame match.
• The selector parser supports the documented Ego forms plus a narrow
  Playwright-compatible subset: css=, terminal :has-text(), :text-is(),
  >> nth=N after CSS/text/href selectors (N >= 0 or -1), and role
  name*= matching.
• Clicks require an enabled element and a real hit target. Hover and drag keep
  the hit-target requirement but may address disabled elements. DOM-backed
  actions such as selectOption() require a rendered, enabled control but may
  operate on an opacity-zero native control used by a custom widget. Like
  Playwright, selectOption() can programmatically choose a disabled option.
• Network-idle waits use continuous per-Page and OOPIF request state; they do
  not consume the CDP events returned by page.events() or include other Pages.
• fill() verifies that editing took effect, not that application formatting
  preserved the requested string byte-for-byte. Business postconditions remain
  explicit Page reads or waits.
• New public APIs must be added to public-api-schema.ts; runtime validation,
  default help(), and the usage guide must remain aligned.
• Embedded hosts should await the exported disposeEgoSdk() hook before
  discarding a Node context; see ../../docs/native-sdk-lifecycle-requirement.md.
• Site-specific reusable experience belongs under ../../skills/ego-browser/learnings/, not in this package.

License Copy Chapter

MIT

Overview (`plugins/ego/README.md`) Copy Section

ego agent plugin

Package the same ego-browser Skill for nine agent hosts. Each distribution
contains only its host entry points, a complete copy of the canonical Skill,
and installation instructions for that host.

Requirements Copy Chapter

• macOS or Windows with ego lite installed and open
• ego-browser available on the agent's PATH
• An agent host that can read Skills and execute local shell commands

Packaging Copy Chapter

From the repository root, build all nine artifacts with one command:

npm --prefix plugins/ego run package

The output directory is dist/plugins/ego-v2.1.0/:

Every ZIP includes a host-specific README.md at its root; npm archives include
it under package/. The WorkBuddy ZIP contains a marketplace root with the
plugin under plugins/ego/. Other ZIPs start directly at the plugin root. The
Codex ZIP starts there too and carries its marketplace file alongside, because
the public plugin directory rejects an archive whose manifest is not at the
root.

The two npm packages have separate names and exports so their adapters cannot
be confused by package caches. All nine packages contain real Skill files;
none depends on the source checkout or its symlink.

Override the output parent directory, or package all plugin directories:

npm --prefix plugins/ego run package -- --output /absolute/path/to/artifacts
node plugins/scripts/package-plugins.mjs --all

Each plugin gets its own <name>-v<version>/ directory. Rebuilding replaces the
nine named artifacts only after all nine have been built. A build failure leaves
previous artifacts intact. Older universal ZIP/npm outputs outside the version
directory are left untouched and are no longer generated.

Packaging requires Node.js, npm, zip, and unzip. Run this command instead of
npm pack in the source directory: npm omits the linked Skill when packing the
source directly.

Installation Copy Chapter

Choose the artifact for the host. Extract ZIPs into a persistent local directory
unless the host accepts ZIP upload. The paths below are placeholders for that
directory or the downloaded npm archive. Each packaged README repeats only the
matching section and the requirements above.

Claude Code Copy Section

Extract the Claude Code ZIP, then load its plugin directory for a session:

claude --plugin-dir /absolute/path/to/ego-claude-code

Use /ego:ego-browser. This flag loads the plugin for that session. Persistent
installation uses a plugin marketplace; the repository marketplace exposes
ego@ego-agent-skills when that source version is available.

See the Claude Code plugin reference.

Codex Copy Section

The Codex ZIP serves both install routes. .codex-plugin/plugin.json and
skills/ sit at the archive root, and .agents/plugins/marketplace.json
points at that same root with "path": "./".

To install locally, extract the ZIP and add the extracted directory:

codex plugin marketplace add /absolute/path/to/ego-codex
codex plugin add ego@ego-codex-local

Restart Codex if the plugin does not appear, then ask it to use $ego-browser.
Remove the installed plugin with codex plugin remove ego@ego-codex-local.

To publish, upload the same ZIP as a skills-only plugin in the submission
portal and select the verified developer identity that matches author.name.
The listing copy comes from the manifest's interface object, whose category
must be one of the values the portal accepts. See
Submit plugins and
the submission error reference.

See the OpenAI plugin guide.

Cursor Copy Section

Extract the Cursor ZIP and load it with Cursor CLI:

cursor-agent --plugin-dir /absolute/path/to/ego-cursor

The package declares its Skill through .cursor-plugin/plugin.json. Use
/ego-browser in the session. This command does not install a Cursor Desktop
marketplace entry.

GitHub Copilot Copy Section

Extract the GitHub Copilot ZIP and load it with Copilot CLI:

copilot --plugin-dir /absolute/path/to/ego-github-copilot

Use /ego-browser. This local session uses the packaged Claude-compatible
manifest. VS Code marketplace installation is a separate host workflow.

Check the Skill's source when a personal ego-browser Skill is already
installed. In the tested Copilot CLI, the personal copy takes precedence over
the plugin copy, and a disabled personal copy prevents the plugin Skill from
being invoked. Resolve that duplicate and enable the plugin Skill before use.

See the GitHub Copilot plugin guide.

Grok Build Copy Section

Extract the Grok Build ZIP, then install the local directory:

grok plugin install /absolute/path/to/ego-grok-build

Use /ego-browser. The package contains the Agent Plugins plugin.json and
Skill directory. Remove it with grok plugin uninstall ego.

WorkBuddy Copy Section

Extract the WorkBuddy ZIP as a marketplace root. It contains
.claude-plugin/marketplace.json and plugins/ego/, including
.codebuddy-plugin/plugin.json, .workbuddy-plugin/plugin.json, and the
Claude-compatible manifest.

For WorkBuddy versions that expose 添加市场 with local sources, add the
absolute path of the extracted root, select ego-workbuddy-local, and install
ego. Start a new task and ask it to use the ego-browser Skill.

Local marketplace import still needs verification in WorkBuddy Desktop. The
official WorkBuddy plugin guide
documents marketplace installation but does not establish a direct ZIP import
workflow. If the installed version only accepts a published marketplace, this
local archive must be distributed through that supported marketplace first.

QwenWork Desktop Copy Section

Upload the QwenWork ZIP directly through 扩展 → 专家套件 → + 添加 → 上传套件,
then click 安装. Start a new task and ask it to use ego-browser.

This package uses .claude-plugin/plugin.json, an explicitly supported expert
kit format. The older .qoder-plugin/plugin.json source manifest is not used
for this artifact. See the QwenWork expert-kit guide.

OpenCode Copy Section

Extract the local npm archive into a persistent directory, then register its
JavaScript entry point:

mkdir -p /absolute/path/to/ego-opencode
tar -xzf /absolute/path/to/ego-opencode-v2.1.0.tgz -C /absolute/path/to/ego-opencode
opencode plugin "file:///absolute/path/to/ego-opencode/package/index.js" -g

Keep the extracted directory in place. OpenCode 1.14.30 accepts a local .tgz
in its installer but fails to resolve that archive's server entry at startup;
the extracted file URL loads successfully. Remove any earlier .tgz entry
from the config's plugin array when switching to the file URL.

The package is named @citrolabs/ego-opencode. Its . and ./server exports
load index.js, which adds the packaged Skill instructions and /ego-browser
command. To remove it, delete its entry from the applicable opencode.json
plugin array.

See the OpenCode plugin guide.

DeepSeek Harness Copy Section

Extract the npm archive into a persistent directory, then add its package/
directory to the desired profile:

mkdir -p /absolute/path/to/ego-deepseek-harness
tar -xzf /absolute/path/to/ego-deepseek-harness-v2.1.0.tgz -C /absolute/path/to/ego-deepseek-harness
dsh plugin --profile web add /absolute/path/to/ego-deepseek-harness/package
dsh --profile web --dump-config
dsh --profile web

The package is named @citrolabs/ego-deepseek-harness. Its bundle patch loads
@citrolabs/ego-deepseek-harness/dsh and registers the packaged Skill. Use
/ego-browser. Remove it with
dsh plugin --profile web remove @citrolabs/ego-deepseek-harness.

An existing personal ego-browser Skill takes precedence over this bundled
provider. Check the base directory returned by the Skill tool: it must point
inside this extracted package when validating the plugin. Resolve the duplicate
personal Skill if you want named invocation to use the plugin copy.

See the DeepSeek Harness local package guide.

Verification Copy Chapter

Packaging tests check all nine payloads, marketplace paths, canonical Skill
contents, source symlink preservation, repeat builds, and failed-batch handling.
They load both npm adapters after extraction outside the repository. These
checks do not establish end-to-end compatibility in all nine host applications.

After installation, confirm that the host discovers ego-browser and can run:

ego-browser nodejs <<'EOF'
console.log('ego-browser ready')
EOF

Development Copy Chapter

skills/ego-browser is a relative symlink to ../../../skills/ego-browser.
It is the thin entry Skill; the usage guide it points to lives in
package/ego-browser/skill-body/SKILL.md and ships with ego lite. Edit the
canonical entry Skill; the packager materializes it in temporary directories
and leaves the source link untouched. Unexpected or broken links fail packaging.

Plugin tests belong in plugins/ego/tests/ and run independently of browser
runtime tests:

npm --prefix plugins/ego test

CI and the commit hook run this suite for plugin changes.

Ego Browser Skill Command (`docs/ego-browser-skill-command.md`) Copy Section

`ego-browser skill` browser integration

The ego-browser Skill has two layers:

• Entry Skill — skills/ego-browser/ in this repository. It is what skill
  markets, plugins, and ~/.agents/skills/ego-browser contain. It only tells the
  agent to run ego-browser skill, plus the install guide and the
  cookie/cache/storage guide that must be readable before ego lite exists.
• Usage guide — package/ego-browser/skill-body/SKILL.md. It is versioned
  with the SDK and printed by ego-browser skill, so the agent always reads the
  guide that matches the installed browser.

This document lists what the ego lite app and its native ego-browser launcher
must implement. Everything else lives in this repository.

Release payload Copy Chapter

npm run build writes the payload to package/ego-browser/dist/out/
(CI archives the same directory as ego-browser-release-payload.tar.gz):

dist/out/
├── index.js                     SDK bundle
├── ego-browser/
│   └── SKILL.md                 usage guide printed by `ego-browser skill`
└── agent-skills/
    └── ego-browser/             entry Skill to install into ~/.agents/skills/ego-browser
        ├── SKILL.md
        ├── references/
        ├── scripts/
        ├── agents/
        ├── assets/
        └── learnings/           site learnings; the SDK reads this bundled copy

Ship dist/out/ as one unit inside the app, keeping ego-browser/ next to
index.js.

1. Add the `ego-browser skill` subcommand Copy Chapter

1. Resolve the SDK with exactly the same rules as ego-browser nodejs:
   --sdk-path, then the debug override
   (~/Library/Application Support/Citro Labs/debug/index.js), then the bundled
   SDK. Do not implement a separate lookup, or the guide and SDK can come from
   different builds.

2. Read ego-browser/SKILL.md from the directory that contains the resolved
   index.js.

3. Write it to stdout unchanged and exit 0. The build already adds the first
   line ([ego-browser:skill] ego-browser usage guide v<version>) and the last
   line ([ego-browser:skill] end of guide v<version>); do not add or parse
   anything else.

4. When the SDK is not the bundled one, print one extra line before the guide so
   developers notice the override:

   text Copy

   [ego-browser:skill] source=debug-sdk dir=/path/to/dist/out/ego-browser (override, not the bundled guide)

   source is sdk-path or debug-sdk.

Errors:

Also list skill in ego-browser help, e.g. "Print the usage guide for this
ego lite version".

Older launchers print Unknown command: skill and exit 2. The entry Skill
relies on that to send the agent to references/install.md, which asks the user
to run ego-browser upgrade.

2. Install the entry Skill on launch Copy Chapter

On every launch, check ~/.agents/skills/ego-browser:

Stop extracting the full Skill to ~/.local/share/ego/ego-skills. After the
entry Skill is in place, the browser never writes ~/.agents/skills again;
upgrades only replace the bundled payload.

Acceptance checks Copy Chapter

• ego-browser skill output is byte-identical to the bundled
  ego-browser/SKILL.md, starts with the version line, and ends with
  [ego-browser:skill] end of guide v<version>.
• With --sdk-path <checkout>/package/ego-browser/dist/out/index.js or the
  debug override, the output is the checkout's guide and starts with a
  source= line; removing the override restores the bundled guide.
• ego-browser skill foo and a missing guide both exit non-zero with a
  readable error.
• ego-browser help lists skill.
• Fresh install: ~/.agents/skills/ego-browser contains the entry Skill.
• Upgrade from a version that used the ego-skills symlink: the symlink is
  replaced by the entry Skill. A user-installed Skill stays unchanged.

Local Runtime Development (`docs/local-runtime-development.md`) Copy Section

Use a Local Runtime with Ego Lite

Ego Lite installs the ego-browser CLI and provides the native browser bridge.
This repository builds the JavaScript runtime that the CLI can load for a
single command:

Installed Ego Lite CLI
  -> --sdk-path
  -> local dist/out/index.js
  -> Ego Lite and Chromium

The override is temporary. It does not modify the installed application.

Build Copy Chapter

Ego Lite must be installed and onboarding must be complete. The examples below
assume that ego-browser on PATH belongs to Ego Lite.

From the repository root:

cd package/ego-browser
npm ci
npm run build

The runtime is written to package/ego-browser/dist/out/index.js. Run
npm run build again after changing runtime source code.

Run with the local runtime Copy Chapter

Use the CLI installed by Ego Lite and pass the absolute bundle path:

cd package/ego-browser

ego-browser nodejs --sdk-path "$PWD/dist/out/index.js" <<'EOF'
if (!globalThis.ego) throw new Error('Ego Lite native bindings are unavailable')
process.stdout.write('Local runtime loaded successfully\n')
EOF

For browser automation, keep the same command and write the heredoc using the
API documented by the current checkout in package/ego-browser/skill-body/SKILL.md.

Every manual invocation needs --sdk-path; it is not a persistent setting.
Do not use npm link or replace files inside the Ego Lite application bundle.
The installed CLI is still required to provide the native browser environment.

Verify against the real browser Copy Chapter

Run the real-browser E2E suite:

cd package/ego-browser
npm run e2e

The suite builds the current worktree and automatically runs it through the
Ego Lite CLI with --sdk-path. On macOS it prefers the app's stable
Versions/Current helper path, so another installed Ego product cannot silently
take over the test. Set EGO_BROWSER_REAL_E2E_CLI to use another installation.
This is the preferred end-to-end compatibility check. npm test remains useful
for repository tests but does not replace the real-browser check.

The command is self-contained: it starts its own local fixture server, creates a
uniquely named temporary task space, and cleans both up. No manual SDK linking,
task-space selection, takeover, or browser interaction is part of a successful
run. A fresh agent can use this command without any context from an earlier
debugging session.

Keep the Skill aligned Copy Chapter

The usage guide describes the APIs implemented by the runtime. ego-browser skill
prints the guide next to the SDK it loads, so an agent that runs it with the same
--sdk-path (or the debug override) reads the guide from the same checkout as
the bundle. A guide from another release may generate helper calls that the
local runtime does not support.

Troubleshooting Copy Chapter

• ego-browser not found: finish Ego Lite onboarding and add its CLI
  directory, commonly ~/.local/bin, to PATH.
• Multiple Ego products are installed: set EGO_BROWSER_REAL_E2E_CLI to
  the intended Ego Lite helper. The E2E output prints the selected CLI path.
• --sdk-path unsupported: update Ego Lite to a build that supports loading
  an external runtime.
• Changes are not visible: rebuild and confirm that the absolute SDK path
  points to the intended checkout.
• Browser APIs are missing: align the Skill with the checkout, then run
  npm run e2e to check app/runtime compatibility.

Native Bindings Api (`docs/native-bindings-api.md`) Copy Section

Ego Lite Native Bindings API Reference

This document describes the low-level globalThis.ego API injected into the
ego-browser nodejs environment by the installed Ego Lite application.

These bindings are provided by Ego Lite, not implemented by this repository.
Their availability is determined by the installed Ego Lite build and is
independent of the Git tag or branch used to build the local ego-browser
runtime.

The runtime in this repository consumes these bindings and may expose only a
subset of them through its higher-level helpers. Agent automation should
normally follow the usage guide printed by ego-browser skill; runtime maintainers may access
globalThis.ego directly when working with the native bridge.

Runtime Model Copy Chapter

Most methods return a Promise and route work to the browser-side
NodeClient. Promise results are converted from browser-side base::Value
objects, so result shapes can follow the command implementation that handled the
request.

Task-scoped APIs operate on the current task context. Select that context with
ego.useTaskSpace(id) inside the script. id is the numeric task-space id
reported by ego.createTaskSpace(), ego.claimTaskSpace(), or
ego.listTaskSpaces(). Selecting a task only updates the current Node
invocation; it does not create, claim, or validate the browser-side task space.

Profiles are selected when a task space is created, not through
ego.useTaskSpace(). Call ego.listProfiles() to discover the available
profiles, then pass the selected profile's id to
ego.createTaskSpace(name, profileId). Existing task-scoped APIs continue to
operate on the profile that owns the selected task space.

Task-space result objects currently expose both a numeric locator and a
user-visible name:

{
  id: 7,                    // numeric unique task-space locator
  taskId: 'checkout-flow',  // same value as name
  name: 'checkout-flow',    // user-visible display name
}

Use id when calling APIs that operate on an existing task space. taskId is a
display-name compatibility field and should not be used as a locator.

If no task context is available, task-scoped APIs resolve to an error object or
reject depending on the underlying operation. Regular task commands usually
resolve an object like
{ error: "Task space not selected", error_code: "EGO_TASK_SPACE_NOT_SELECTED" };
ego.snapshot() rejects with an Error whose error_code property is set.

When a task has been handed off to the user, browser-mutating automation calls
are blocked until the agent takes the task back. The affected APIs are
ego.createTab(), ego.listTabs(), ego.snapshot(), ego.closeTaskSpace(),
ego.completeTaskSpace(), ego.animationHighlightMouseToPosition(),
ego.setAgentTaskState(), and raw CDP sends through ego.sendCDPMessage().
Most of these APIs resolve an error object with error and error_code fields;
ego.snapshot() rejects with an Error containing error_code; raw CDP sends
report the failure through ego.onSendCDPMessageError.

Error Codes Copy Chapter

Browser-side failures expose a stable error_code in addition to a human-readable
message. Promise-returning APIs use one of these shapes:

{ error: 'Task space not selected', error_code: 'EGO_TASK_SPACE_NOT_SELECTED' }

or, for rejected operations:

try {
  await ego.snapshot();
} catch (error) {
  console.log(error.message);
  console.log(error.error_code);
}

Argument validation failures throw TypeError with
error_code: 'EGO_INVALID_ARGUMENT'.

Known error codes:

EGO_BROWSER_UNAVAILABLE
EGO_CDP_CHANNEL_UNAVAILABLE
EGO_CDP_SEND_FAILED
EGO_INVALID_ARGUMENT
EGO_INVALID_RESULT_PAYLOAD
EGO_OPERATION_FAILED
EGO_PROFILE_NOT_FOUND
EGO_RESULT_CONVERSION_FAILED
EGO_SNAPSHOT_FAILED
EGO_TASK_HOST_DISCONNECTED
EGO_TASK_SPACE_INACTIVE
EGO_TASK_SPACE_NOT_FOUND
EGO_TASK_SPACE_NOT_SELECTED
EGO_TASK_SPACE_UNAVAILABLE
EGO_TASK_SPACE_USER_IN_CONTROL
EGO_WEB_CONTENTS_UNAVAILABLE

All async callbacks are bounced through the Node event loop before JS is
invoked. Scripts can safely await these APIs and allow the process to exit
after pending requests settle.

Browser Version Copy Chapter

`await ego.getBrowserVersion()` Copy Section

Returns the installed Ego Lite version and whether its updater has an available
release. This method is not task-scoped and does not start an update.

{
  currentVersion: '0.5.0.5',
  updateAvailable: false,
}

Older Ego Lite builds may not expose this method. Callers should treat a missing
method, a failed request, or an invalid result as unavailable update status.

Task Context Copy Chapter

`ego.useTaskSpace(id)` Copy Section

Selects the task context for subsequent task-scoped helper calls in the current
Node invocation. This is a synchronous local selection only.

const id = ego.useTaskSpace(task.id);

Arguments:

id: number

Returns the selected id synchronously.

Throws TypeError when id is missing, not a number, or extra arguments are
provided. The thrown error has error_code: 'EGO_INVALID_ARGUMENT'.

Use ego.createTaskSpace(name) to create a new agent-owned task space. Regular
Spaces created by the user are returned by ego.listTaskSpaces() with
ownership: 'user'. Pass their numeric id to
ego.claimTaskSpace(id, name?) before selecting them.

Profiles Copy Chapter

Profiles determine which browser identity, cookies, storage, and login state a
new task space inherits. Profile selection only applies when creating the task
space. After creation, select the returned task-space id with
ego.useTaskSpace(task.id) as usual.

Profile APIs are available when the installed Ego Lite build exposes them,
even if the checked-out repository runtime does not yet provide equivalent
higher-level helper methods.

`await ego.listProfiles()` Copy Section

Lists the profiles that may be used by ego.createTaskSpace().

const result = await ego.listProfiles();
for (const profile of result.profiles) {
  console.log(profile.id, profile.name, profile.isDefault);
}

Arguments: none.

Returns:

{
  profiles: [
    {
      id: 'Profile 2',
      name: 'Work',
      isDefault: false,
    },
    {
      id: 'Default',
      name: 'Personal',
      isDefault: true,
    },
  ],
}

Field meanings:

id:
  Locator accepted by ego.createTaskSpace(name, profileId), for example
  "Default" or "Profile 2".

name:
  User-visible profile name. It may be duplicated and is not a locator.

isDefault:
  True for the profile selected when profileId is omitted. This does not
  necessarily mean that id is "Default".

The result contains available regular profiles. The internal Ego authentication
profile is not exposed.

Throws TypeError when any argument is passed. The thrown error has
error_code: 'EGO_INVALID_ARGUMENT'.

To create a task space with a profile, pass profile.id to
ego.createTaskSpace(name, profileId). See the Task Spaces section for the
complete call and error handling.

Tabs Copy Chapter

`await ego.createTab(url)` Copy Section

Creates a tab in the current task space.

const tab = await ego.createTab('https://example.com/');
console.log(tab.targetId);

Arguments:

url: string

Returns a browser-side result object. Current task implementations return a
tab descriptor containing at least targetId when creation succeeds.

Throws TypeError when url is missing or not a string.
The thrown error has error_code: 'EGO_INVALID_ARGUMENT'.

`await ego.listTabs()` Copy Section

Lists tabs in the current task space.

const result = await ego.listTabs();
for (const tab of result.tabs) {
  console.log(tab.index, tab.title, tab.url, tab.active);
}

Arguments: none.

Typical result:

{
  tabs: [
    {
      index: 0,
      targetId: '...',
      url: 'https://example.com/',
      title: 'Example',
      active: true,
    },
  ],
}

If the current task has been handed off to the user, the promise resolves to an
error object:

{
  error: 'The task is under user control...',
  error_code: 'EGO_TASK_SPACE_USER_IN_CONTROL',
}

error_code is 'EGO_TASK_SPACE_USER_IN_CONTROL'. For this code, error is a
stable reason key rather than display text. Current keys are:

notifications
location
camera
microphone
pan_tilt_zoom_microphone
midi
bluetooth
usb
serial
hid
protocol_handler
manual_takeover

For example, a location prompt returns:

{
  error: 'location',
  error_code: 'EGO_TASK_SPACE_USER_IN_CONTROL',
}

Callers should use error_code to identify the control boundary, then use the
reason key to choose guidance. Unknown reason keys must fall back to generic
user-control guidance.

Page-authored JavaScript dialogs must not use this user-control path; see
Native JavaScript dialog requirement.

Snapshot Copy Chapter

`await ego.snapshot(options?)` Copy Section

Captures a structured snapshot for the current task space.

const snapshot = await ego.snapshot({
  scope: 'only_within_viewport',
  includeActionMarks: true,
  interactiveOnly: true,
  includeStableLocator: true,
  maxResultLength: 4000,
});

console.log(snapshot.content);
console.log(snapshot.refs);

const subtree = await ego.snapshot({
  scope: 'subtree',
  root: snapshot.refs[0].backendNodeId,
});

Arguments:

options?: object

Supported options:

scope:
  'full_page'            Capture the full page. This is the default.
  'only_within_viewport' Capture only the viewport.
  'subtree'              Capture the node identified by root and its descendants.

root: number
  backendNodeId from a previous snapshot ref. Required only for subtree scope.

includeActionMarks: boolean
  Include action markers in the textual snapshot.

interactiveOnly: boolean
  Limit output to interactive elements.

includeStableLocator: boolean
  Include reusable locator hints on refs when available.

maxResultLength: number
  Maximum result content length. Zero or omitted means unlimited.

In Ego Lite 0.5.0.19, subtree scope requires launching the browser with
--enable-features=SnapshotSubtree. Do not use PageSnapshotSubtree.
This version matches root by backendNodeId across all frames, although that
identifier is only frame-local. If the same value occurs in multiple frames,
the call fails with an ambiguity error instead of selecting an arbitrary node.

Result:

{
  content: '...',
  refs: [
    {
      backendNodeId: 17,
      role: 'button',
      name: 'Continue',
      loc: 'role:button[name=Continue]', // only when available
    },
  ],
}

When no stable, unique locator is available, omit loc from both refs and
the textual snapshot. Do not return unstable or ambiguous as locator values.

If the browser side reports a snapshot error, the promise rejects with an
Error. The message contains the human-readable error, and error_code
contains a stable code such as EGO_SNAPSHOT_FAILED,
EGO_TASK_SPACE_NOT_SELECTED, EGO_TASK_SPACE_NOT_FOUND,
EGO_TASK_SPACE_USER_IN_CONTROL, or EGO_WEB_CONTENTS_UNAVAILABLE.

Task Spaces Copy Chapter

`await ego.listTaskSpaces()` Copy Section

Lists Agent task spaces and regular user-created Spaces that are available to
the native task-space bridge. Listing is read-only: it does not select or claim
a Space.

const spaces = await ego.listTaskSpaces();
for (const space of spaces.taskSpaces) {
  console.log(space.id, space.name, space.ownership);
}

Arguments: none.

Returns:

{
  taskSpaces: [
    {
      taskId: 'research',
      id: 3,
      name: 'research',
      createdBy: 'user',
      ownership: 'user',
      profileId: 'Default',
      profileName: 'Work',
      recentTabTitles: ['Project notes', 'Reference'],
    },
    {
      taskId: 'checkout-flow',
      id: 7,
      name: 'checkout-flow',
      createdBy: 'agent',
      ownership: 'agent',
      recentTabTitles: ['Checkout', 'Cart'],
    },
  ],
}

id is the locator for ego.claimTaskSpace() and other task-space APIs.
name and taskId are display values and may be duplicated. A regular Space
created in the Ego Lite UI has createdBy: 'user' and ownership: 'user'.
recentTabTitles may help the caller identify the intended Space without
claiming it.

Throws TypeError when any argument is passed.
The thrown error has error_code: 'EGO_INVALID_ARGUMENT'.

`await ego.createTaskSpace(name, profileId?)` Copy Section

Creates an agent-owned task space by name, optionally using a specific profile.

const { profiles } = await ego.listProfiles();
const profile = profiles.find(item => !item.isDefault) ?? profiles[0];
if (!profile) {
  throw new Error('No available profile');
}

const taskName = `profile-demo-${Date.now()}`;
const task = await ego.createTaskSpace(taskName, profile.id);
if (task.error) {
  throw new Error(`${task.error} (${task.error_code})`);
}
ego.useTaskSpace(task.id);
console.log(JSON.stringify({ profile, task }, null, 2));

Arguments:

name: string, non-empty
profileId?: string
  Unique profile id returned by ego.listProfiles(). If omitted, empty, or
  "default", the currently active/last-used regular profile is selected.

Returns:

{
  taskId: 'checkout-flow',
  id: 7,
  name: 'checkout-flow',
}

Throws TypeError when name is missing, not a string, or empty; when
profileId is present but not a string; or when extra arguments are provided.
The thrown error has error_code: 'EGO_INVALID_ARGUMENT'.

If profileId does not identify an available profile, the promise resolves to:

{
  error: 'Profile not found',
  error_code: 'EGO_PROFILE_NOT_FOUND',
}

If the browser cannot create a task space, the promise resolves to an error
object:

{
  error: 'No active browser',
  error_code: 'EGO_BROWSER_UNAVAILABLE',
}

`await ego.claimTaskSpace(id, name?)` Copy Section

Claims a Space returned by ego.listTaskSpaces() and turns it into an
agent-owned task space. This includes regular Spaces created by the user. Pass
name to rename the Space while claiming it.

const spaces = await ego.listTaskSpaces();
const checkout = spaces.taskSpaces.find(space => space.name === 'checkout-flow');
const task = await ego.claimTaskSpace(checkout.id, 'checkout-flow');
ego.useTaskSpace(task.id);

Arguments:

id: number
name?: string

Returns:

{
  taskId: 'checkout-flow',
  id: 7,
  name: 'checkout-flow',
}

Claiming a regular user Space keeps its browser profile, tabs, active tab, and
numeric id; it does not create a replacement Space. The caller must have the
user's approval before taking ownership.

Throws TypeError when id is missing or not a number, when name is present
but not a string, or when extra arguments are provided. The thrown error has
error_code: 'EGO_INVALID_ARGUMENT'.

If the space does not exist or cannot be claimed, the promise resolves to an
error object. Error messages identify the numeric id that was used for lookup:

{
  error: 'Task space not found: 7',
  error_code: 'EGO_TASK_SPACE_NOT_FOUND',
}

claimTaskSpace() does not select the task context by itself. Call
ego.useTaskSpace(task.id) after a successful claim before using task-scoped
helpers.

`await ego.closeTaskSpace()` Copy Section

Closes the current task space and removes the task-owned browser state.

await ego.closeTaskSpace();

Arguments: none.

Returns a browser-side status value, currently a string such as
" task space closed." on success, or an error object if the task does
not exist. Error objects include error and error_code.

Throws TypeError when any argument is passed. The thrown error has
error_code: 'EGO_INVALID_ARGUMENT'.

`await ego.completeTaskSpace()` Copy Section

Completes the current task space by removing agent task state while leaving the
Space open for the user. It remains discoverable through
ego.listTaskSpaces() under the same numeric id with user ownership.

await ego.completeTaskSpace();

Arguments: none.

Returns a browser-side status value, currently a string such as
" task space completed." on success, or an error object if the task
does not exist. Error objects include error and error_code.

Throws TypeError when any argument is passed. The thrown error has
error_code: 'EGO_INVALID_ARGUMENT'.

Task Control Copy Chapter

`await ego.handOffTaskSpace()` Copy Section

Transfers the current task space to user control.

await ego.handOffTaskSpace();

Arguments: none.

Returns the browser-side status value from the handoff operation.
Current implementations return a string such as
" has been handed off to the user.".

Throws TypeError when any argument is passed. The thrown error has
error_code: 'EGO_INVALID_ARGUMENT'.

`await ego.takeOverTaskSpace()` Copy Section

Returns the current task space to agent control.

await ego.takeOverTaskSpace();

Arguments: none.

Returns the browser-side status value from the takeover operation.
Current implementations return a string such as
" has been taken over by the agent.".

Throws TypeError when any argument is passed. The thrown error has
error_code: 'EGO_INVALID_ARGUMENT'.

`await ego.setAgentTaskState(state)` Copy Section

Updates the user-visible agent progress text for the current task space.

await ego.setAgentTaskState('Waiting for checkout page');

Arguments:

state: string

Returns the browser-side status value from the task state update. Current
implementations return a string such as " state updated.".

Throws TypeError when state is missing, not a string, or extra arguments are
provided. The thrown error has error_code: 'EGO_INVALID_ARGUMENT'.

UI Helpers Copy Chapter

`await ego.animationHighlightMouseToPosition(x, y)` Copy Section

Shows an animated highlight at the given screen position for the current task
space.

await ego.animationHighlightMouseToPosition(120, 240);

Arguments:

x: number
y: number

Returns the browser-side status value from the highlight operation. Current
implementations return a string such as " mouse highlight shown.".

Throws TypeError when either coordinate is missing, not a number, or extra
arguments are provided. The thrown error has
error_code: 'EGO_INVALID_ARGUMENT'.

Chrome DevTools Protocol Copy Chapter

`ego.sendCDPMessage(message)` Copy Section

Sends a raw CDP message through the Node CDP channel. The message must already
be JSON-encoded. The current task must be selected with ego.useTaskSpace(id),
and its ownership must be agent. If the task is missing, inactive, delegated
to the user, or unavailable, the message is not sent and
ego.onSendCDPMessageError receives the reconstructed error message and code.

const task = await ego.createTaskSpace('cdp-demo');
ego.useTaskSpace(task.id);
ego.sendCDPMessage(JSON.stringify({
  id: 1,
  method: 'Runtime.enable',
}));

Arguments:

message: string

Returns undefined.

Throws TypeError when message is missing or not a string, or when the CDP
channel is not connected. The thrown error has error_code set to
EGO_INVALID_ARGUMENT for invalid arguments or EGO_CDP_CHANNEL_UNAVAILABLE
when the channel is missing.

Notes:

Raw CDP user-control checks use the task selected by ego.useTaskSpace(id).
If no task has been selected, the send fails with EGO_TASK_SPACE_NOT_SELECTED.

`ego.onCDPMessage` Copy Section

Property used to receive raw CDP messages from the browser side.

ego.onCDPMessage = message => {
  const event = JSON.parse(message);
  console.log(event.method);
};

Assign a function to receive messages. Assigning any non-function value clears
the callback. Incoming messages are delivered asynchronously through the Node
event loop.

`ego.onSendCDPMessageError` Copy Section

Property used to receive local send failures for ego.sendCDPMessage().

ego.onSendCDPMessageError = (message, error_code) => {
  console.error(message, error_code);
};

const task = await ego.createTaskSpace('cdp-version');
ego.useTaskSpace(task.id);
ego.sendCDPMessage(JSON.stringify({
  id: 2,
  method: 'Browser.getVersion',
}));

Arguments delivered to the callback:

message: string
error_code: string

The callback does not include the reason key. A user-control send failure
therefore identifies the control boundary, not the permission that caused it.

Assign a function to receive errors. Assigning any non-function value clears the
callback. Errors are delivered asynchronously through the Node event loop.

This callback is used for failures that happen before the message reaches CDP,
including:

- the task is currently under user control
- no task space has been selected
- the selected task space does not exist
- the selected task space has not been claimed by the agent
- the browser-side CDP agent host is no longer available

User-control example:

const task = await ego.createTaskSpace('user-control-demo');
ego.useTaskSpace(task.id);
await ego.handOffTaskSpace();

const result = await ego.createTab('https://example.com/');
console.log(result.error);
console.log(result.error_code); // "EGO_TASK_SPACE_USER_IN_CONTROL"

try {
  await ego.snapshot();
} catch (error) {
  console.log(error.message);
  console.log(error.error_code); // "EGO_TASK_SPACE_USER_IN_CONTROL"
}

ego.onSendCDPMessageError = (message, error_code) => {
  console.log(message);
  console.log(error_code); // "EGO_TASK_SPACE_USER_IN_CONTROL"
};
ego.sendCDPMessage(JSON.stringify({
  id: 1,
  method: 'Browser.getVersion',
}));

await ego.takeOverTaskSpace();

Complete Example Copy Chapter

const { profiles } = await ego.listProfiles();
const profile = profiles.find(item => !item.isDefault) ?? profiles[0];
if (!profile) {
  throw new Error('No available profile');
}

const task = await ego.createTaskSpace('checkout-flow', profile.id);
if (task.error) {
  throw new Error(`${task.error} (${task.error_code})`);
}
ego.useTaskSpace(task.id);

await ego.createTab('https://example.com/');
await ego.setAgentTaskState('Reading page');

const snapshot = await ego.snapshot({
  scope: 'only_within_viewport',
  includeActionMarks: true,
  interactiveOnly: true,
});

console.log(snapshot.content);

await ego.completeTaskSpace();

Native API Compatibility Notes Copy Chapter

Profile-aware task-space creation Copy Section

• Added ego.listProfiles(), which returns available profiles as
  {id, name, isDefault}.
• ego.createTaskSpace(name) now accepts an optional profile locator:
  ego.createTaskSpace(name, profileId?).
• Profile display names are not accepted as locators because they are not
  unique. Callers must pass the id returned by ego.listProfiles().
• Omitting profileId, passing an empty string, or passing "default" selects
  the current default regular profile.
• Unknown profile ids resolve an error object with
  error_code: 'EGO_PROFILE_NOT_FOUND'.

Task-space ids are numeric locators Copy Section

• ego.useTaskSpace(taskId) changed to ego.useTaskSpace(id).
  id is a numeric task-space locator returned by task-space APIs.

• ego.claimTaskSpace(name) changed to ego.claimTaskSpace(id, name?).
  The first argument identifies an existing task space by numeric id. name is
  optional and renames the task space when provided.

• Task-space result objects now distinguish locator and display fields:

  js Copy

  {
    id: 7,
    taskId: 'checkout-flow',
    name: 'checkout-flow',
  }

  Use id for API calls. taskId is currently the same value as name and is
  retained as a display-name compatibility field.

• Task-scoped examples now select task spaces with task.id, including
  createTab, listTabs, snapshot, closeTaskSpace,
  completeTaskSpace, handOffTaskSpace, takeOverTaskSpace,
  setAgentTaskState, animationHighlightMouseToPosition, and raw CDP sends.

• Browser-side operation messages now identify task spaces by numeric id, for
  example " task space completed.", " state updated.", and
  "Task space not found: ".

Error codes Copy Section

• Browser-side error results now include a stable error_code string.
• ego.snapshot() rejects with an Error whose error_code property is set.
• ego.onSendCDPMessageError receives (message, error_code).

Native Javascript Dialog Requirement (`docs/native-javascript-dialog-requirement.md`) Copy Section

Native JavaScript dialog requirement

Ego Lite 0.5.0.12 keeps page-authored alert, confirm, and prompt dialogs
under Agent control, including a confirm opened by a file input change handler.
The real-browser regression covers these paths without a takeover or recovery
step.

beforeunload remains outstanding. In 0.5.0.12, navigation proceeds without a
dialog event even after a trusted click and sticky user activation. The desired
behavior is to keep the dialog under Agent control and report it through the
same Page API.

No page-authored dialog may change TaskSpace ownership or report
EGO_TASK_SPACE_USER_IN_CONTROL with
fallback_site_dialog_required_notice.

No new binding is required. The existing CDP bridge must:

• forward Page.javascriptDialogOpening and
  Page.javascriptDialogClosed on the Page session;
• accept Page.handleJavaScriptDialog on that session while the dialog is
  open, even when the triggering command is still pending;
• preserve the dialog type, message, URL, prompt default, and supplied
  promptText.

Permission prompts and device choosers must continue to transfer control to
the user.

A dialog can outlive the ego-browser nodejs invocation that opened it. The
SDK keeps dialog state per process, and while a dialog is open Chromium does
not answer renderer commands, including Page.enable. The next invocation
therefore cannot discover the dialog and every command it sends times out.
Ego Lite 0.5.2.2 does not meet this requirement yet: in local runs the dialog
was dismissed when the invocation exited, and sometimes the TaskSpace also
moved to user control. In the field, the dialog stayed open and the next
invocation timed out. When an invocation exits with a dialog open, the bridge
must:

• keep the dialog open and the TaskSpace Agent-owned;
• report the open dialog to the next session that attaches to the Page, for
  example by emitting Page.javascriptDialogOpening after Page.enable.

Acceptance: trigger each JavaScript dialog from a real Page click, verify that
the TaskSpace remains Agent-owned, accept a prompt with promptText: "agent",
dismiss a confirm, accept an alert, and verify the returned values and opening
and closing events. Also set files on an intercepted file input whose change
handler opens a confirm, then accept it while DOM.setFileInputFiles is still
pending. For beforeunload, verify that the opening event and action receipt
arrive before choosing whether navigation may continue. Separately verify that
location, camera, and device prompts still transfer control to the user.

Native Sdk Lifecycle Requirement (`docs/native-sdk-lifecycle-requirement.md`) Copy Section

Embedded SDK host requirements

Disposal Copy Chapter

When Ego Lite unloads or replaces an embedded ego-browser Node context, it
should call and await the module's exported disposeEgoSdk() function before
destroying that context.

The function rejects unfinished CDP requests, clears Page/session state, and
removes onCDPMessage and onSendCDPMessageError only when they are still
owned by that SDK instance. This prevents native code from retaining callbacks
into a discarded JavaScript context.

No new binding method is required. The host only needs to honor the module
lifecycle hook. Older SDK builds without disposeEgoSdk may be unloaded as
before.

Acceptance: load the SDK, complete one CDP command, leave another command
pending, call disposeEgoSdk(), then verify that the pending command rejects
and both native callback slots are empty before the Node context is destroyed.

Syntax diagnostics Copy Chapter

The ego-browser nodejs host compiles the heredoc before the embedded SDK can
inspect it. When compilation fails, report the message, one-based line and
column, and the corresponding source line. The direct JavaScript entry point
already provides this diagnostic, but it cannot recover source location after
the host has reduced the failure to a generic node:internal/vm stack.

No new Agent API is needed. The host may either pass the uncompiled source to
the SDK executor or format the V8 compile error itself.

Acceptance: run a heredoc containing an invalid token on line 4 and verify that
stderr identifies line 4, points to the token, and prints the source line.

Native Snapshot Ref Requirement (`docs/native-snapshot-ref-requirement.md`) Copy Section

Native snapshot requirements

Compact snapshot text Copy Chapter

Please simplify the snapshot tree before serializing content:

• Omit text nodes that are empty, whitespace-only (including NBSP), or contain
  only zero-width formatting characters.
• Omit an unnamed container with no remaining children.
• Replace an unnamed container with its only remaining child.
• Keep unnamed containers with multiple children because they preserve
  grouping.
• Keep named or ref-bearing containers and semantic nodes such as image,
  svg_root, canvas, iframe, root, list items, and table cells.

The transformation must preserve the order of remaining nodes, refs, stable
locators, URLs, and iframe boundaries. It applies to both viewport and full-page
snapshots. Never remove or rewrite non-empty page text because it is
non-interactive, because its parent container is simplified, or while cleaning
locator metadata.

Acceptance: a fixture containing nested containers, blank text, two sibling
groups, an iframe, an image, an SVG, a canvas, and an empty table cell is
captured twice. The compact output is identical on the second pass, the sibling
groups remain distinct, and every ref still resolves to its original node.

Deferred: targeted snapshot scope Copy Chapter

A future snapshot API should be able to limit capture to one subtree selected
by a current ref or selector, including content inside an iframe or OOPIF. The
browser should apply the scope before serializing the snapshot; filtering a
full snapshot in JS does not reduce native work or transferred content.

The selected root must resolve uniquely, retain Page and frame provenance, and
produce refs that remain valid for normal Page actions. A missing or ambiguous
root should fail clearly. The exact public API is intentionally undecided, and
this requirement is not scheduled for the current implementation.

Snapshot refs for iframe content Copy Chapter

ego.snapshot() already includes text from ordinary iframes and OOPIFs, but
actionable nodes inside those frames are currently omitted from refs. The
result is visible content that has no @N target.

Please return a ref for every actionable frame node printed by the snapshot:

{
  refId: 901,
  backendNodeId: 21,
  frameId: "FRAME_OR_OOPIF_TARGET_ID",
  role: "button",
  name: "Run iframe action",
}

• The content must print [ref=901] for this node.
• refId must be unique within one snapshot, including across renderer
  processes. It is the value shown to the Agent.
• backendNodeId remains the node id local to its renderer.
• frameId identifies the frame that owns the node. It may be omitted for the
  top-level document.
• Capturing the snapshot must not activate, focus, or reload a frame.

Acceptance: one page contains a same-origin iframe and a cross-origin OOPIF,
with repeated backend node ids in different renderers. Every printed button and
textbox has a distinct ref, and each ref resolves to the node in its own frame.

ego-browser now backfills a missing frameId from the frame AX tree when one
backend node id has only one possible owner. Native metadata is still required
when renderer-local backend ids repeat, and for actionable frame nodes omitted
from refs entirely.

Stable locator correctness Copy Chapter

A stable locator must resolve uniquely to the same node that produced the
snapshot ref. It is invalid when it matches no node, matches more than one node,
or uniquely matches a different backendNodeId.

Please cover at least these cases in native tests:

• repeated controls in one document, such as buttons with the same name;
• a hidden copy and a visible editor sharing the same accessible name;
• the same role and name in the top-level document and an iframe;
• a locator whose element type does not match the source node.

Omit the locator when uniqueness and node identity cannot both be established.
Do not serialize loc=unstable or loc=ambiguous in content, and do not use
those status strings in refs. The JS runtime validates advertised locators
and omits invalid ones as a compatibility safeguard.

--- METRICS ---

• Files Extracted: 9
• Estimated Token Budget: ~16997 tokens
• Canonical Reference: https://codewiki.google/github.com/citrolabs/ego-lite