Troy / Project
Architecture
Troy's process model, main-process components, key design decisions, security boundaries, performance rules and test strategy, from the design document.
This page summarises how Troy is built, file by file. How it works explains the same design from first principles: the problem, the constraints and what follows from them. The full reasoning, including the alternatives each decision beat, is in docs/DESIGN.md, which was last revised on 9 August 2026 and still describes the read pipeline as planned.
Process model
Electron main process
main.js tabs, navigation, menu, lifecycle
omnibox.js what you typed becomes an instruction
tracking.js cancel trackers, strip tracking parameters
settings.js what Troy remembers, and what it will not
shortcuts.js new tab tiles (v0.1.5; unused on main)
history.js visits, when you ask (main)
extensions.js unpacked extensions from the profile
resilience.js the net that keeps the browser open
endpoint.js where an agent can find this browser
readPort.js the live tab as a read port (main)
Window webContents (Troy's chrome, top 88px)
preload.cjs, renderer/chrome.*
One WebContentsView per tab (the web page, below 88px)
tab-preload.cjs, renderer/newtab.*, renderer/error.*
| CDP, when --cdp-port is given
v
an agent, in another process
The chrome is an ordinary web page in the window’s own webContents. Each tab is a WebContentsView laid out beneath it. Page content renders exactly as Chrome renders it and cannot repaint or script Troy’s user interface (UI), because it is a different frame tree in a different process. Every tab’s webContents.debugger speaks the Chrome DevTools Protocol (CDP), the same protocol the engine’s Cdp port drives.
Outside the Electron app, on main:
src/read/: the read pipeline (settle, extract, cover, transcribe, fuse, render), used by the agent panel throughreadPort.jsand byscripts/read.mjs. See How Troy reads a page.src/agent/: the agent tool layer, model loop and key store. Tested, not wired into the app. See Agent tool layer.src/cdp/: theCdpport over Playwright, used by the tests.
Decisions
- Refusals in the resolver, not at each call site. The address bar, the new tab search box and (in v0.1.5) shortcut tiles all go through
resolveOmnibox, so they refuse the same things. On main the agent tool layer’spage_navigateuses it too. Refused schemes are checked before the generic Uniform Resource Locator (URL) rule. - The main process is the authority on inter-process communication (IPC). The tab preload only decides what to expose; the main process checks the calling frame’s address on every new tab channel.
- A tab is touched only while its renderer exists. Every getter on a destroyed
webContentsthrows, and a throw in the main process would end the browser, so reads go through a liveness check and dead tabs are pruned first. - State updates are coalesced. One navigation fires five events; the chrome is updated once per turn of the event loop.
- The tab strip is edited in place, so favicons are not refetched on every update.
- Glass comes from the window, not Cascading Style Sheets (CSS). On macOS the window uses system vibrancy. There is no
backdrop-filter, which could not blur the separate page view anyway. - Settings are cached in memory, because the tracker blocker checks them on every request.
- Ad-hoc signing is not optional.
scripts/after-pack.cjsreseals the macOS bundle withcodesign --sign -and verifies it. Without it, Apple silicon reports the app as damaged. - One native build per architecture. The Intel macOS build is cross-built on Apple silicon with Rosetta installed.
- The read pipeline asks for two capabilities (main). It needs only
evaluateand, for optical character recognition (OCR),screenshot. Any host that offers those can run it, which is why the panel, the script and the tests share one pipeline. - OCR is the caller’s choice (main). The pipeline never looks for an engine on its own, because which engine is acceptable (cost, privacy, platform) is the caller’s decision. Without one, regions are reported as untranscribed rather than silently dropped.
- The endpoint file is written atomically (main). It goes to a temporary file that is renamed into place, so a reader never sees half of it.
Security boundaries
| Boundary | Enforcement |
|---|---|
| Page to chrome | Separate view, context isolation, sandbox |
| Page to main | Fixed IPC; new tab channels checked by frame URL |
| Address bar to origin | Scheme refusals in omnibox.js |
| Page to operating system | Popups denied; unknown schemes go to the operating system |
| Page to devices | Only fullscreen and sanitized clipboard write |
| Extension to disk | allowFileAccess: false |
| Agent to browser | Port closed by default, loopback, per launch |
Out of scope: a malicious extension the user installs on purpose, a compromised machine, and first-party tracking by a site you chose to visit.
Performance rules
- Animate only transforms and opacity. The progress bar scales and the tab spinner rotates.
- No synchronous disk reads on the main process during a page load.
- No per-frame work in the main process.
- Edit the Document Object Model (DOM), do not rebuild it.
- No graphics processing unit (GPU) work that buys nothing.
npm run stress enforces the frame budget. See Command line and environment.
Testing
At v0.1.5 there are 127 tests: 84 pure unit tests, 7 driving real Chromium through the Cdp port, and 36 driving a real Electron process over real sockets. Main has 226 tests in 16 files. The additions cover the read pipeline against fixtures in headless Chromium, the agent tool layer (some of it against a real page), the model loop with scripted responses, the key store, and history.
The Electron tests assert through two surfaces only: what a person can see in the chrome page, and a snapshot hook in the main process (enabled by TROY_TEST=1) for things a person cannot see directly, such as which view is visible and where it sits.
Test files run one at a time. In parallel, two files launching Electron raced to download the same binary and corrupted it.
Continuous integration (CI) runs lint, type checking and the suite on macOS, Windows and Linux. The Windows leg caught 'file://' + path.join() producing backslash URLs, which made a new tab leak its own file path into the address bar on that platform only.
Known gaps
From the design document, with their state on main:
rememberHistoryis stored and shown but nothing reads it. Fixed on main.- The agent panel’s read is a placeholder for the planned pipeline. Replaced on main by the real pipeline.
- No behavioural test coverage on Intel Macs. The Intel build is packaged and launched under Rosetta only.
- Extensions load but have no UI.
- No auto-update.
Found since, and still open on main (most are listed in docs/spec/2026-09-bugs-and-enhancements.md):
- No OCR engine is passed to the pipeline, so regions are never transcribed.
scripts/read.mjshas no tests, and its--urlmatches open tabs by exact string.- The endpoint file can outlive a crash, and there is no single-instance lock.
- Selectors that cross a shadow root (
>>>) cannot be used by the action layer. - The agent tool layer is not wired into the app.