bridge-client

client/ is the application/client repo in the split Bridge workspace.

It owns the user-facing shell/app layer and is responsible for browser chrome, lifecycle, diagnostics, and backend orchestration.

Naming note

This repo is in the middle of a broader split/rename transition:

• Bridge = the current workspace/repository architecture (bridge/, client/, engine-custom/, engine-chromium/)
• BROWZ = the browser product name still used in much of the historical documentation, example content, window titles, test fixtures, and some internal symbols

For now, assume those names refer to the same overall browser project unless a document says otherwise.

What this repo owns

• application/window/chrome lifecycle
• browser navigation/controller logic
• session/debug/HUD/tooling surfaces
• current engine API headers and client-facing engine contract
• backend factory / backend selection
• client-facing end-to-end tests
• client-facing benchmarks, examples, and helper scripts

What this repo does not own

• custom engine internals (../engine-custom)
• Chromium engine internals (../engine-chromium)
• heavyweight engine dependency trees like V8 or Chromium checkouts

Current transition status

This repo is already split conceptually, but the implementation is still transitional.

True today

• client builds against sibling repos at ../engine-custom and ../engine-chromium
• the backend API and backend factory live here
• the shell can select a renderer/backend by name
• focused shell/backend seam tests already exist
• custom is the primary working backend path
• chromium is an active bring-up path, not a finished backend

Still transitional today

• client/CMakeLists.txt still compiles a temporary set of custom-engine sources into the shell build
• the shell/backend contract exists, but full page-load/render ownership has not been fully migrated behind it yet
• some docs still describe the intended final split more cleanly than the current build graph actually is

If you are contributing during this phase, trust the code/build graph over the idealized architecture diagrams.

Sibling repo expectations

By default local development expects these sibling paths:

• ../engine-custom
• ../engine-chromium

The client CMake config links those repos by sibling path during local workspace development.

Quickstart

Build

Preferred workspace-root entrypoint:

Custom engine, V8 off

cd ..
./compile.sh --engine custom --js off

Custom engine, V8 on

cd ..
./compile.sh --engine custom --js v8

Chromium seam targets

cd ..
./compile.sh --engine chromium --js off

Legacy repo-local entrypoint still exists:

./build.sh off
./build.sh on --v8-include /path/to/v8/include --v8-lib /path/to/v8/out.gn/x64.release/obj

Notes:

• root compile.sh is now the preferred build entrypoint for the split workspace
• build.sh prefers V8 paths from ../engine-custom/third_party/v8/... when present
• legacy BROWZ_* V8 env vars are still accepted as transitional aliases

Run

Launch the browser shell:

./startbrowser.sh

Examples:

./startbrowser.sh --off
./startbrowser.sh --renderer custom https://example.com
./startbrowser.sh --renderer chromium --off

Test

Run the default test pass through the build script:

./build.sh off

Or run focused tests directly:

ctest --test-dir build/v8-off --output-on-failure \
  -R 'application_interaction_test|custom_backend_bridge_test|blink_backend_stub_test'

Benchmark / debug

Run the Core Web 80 benchmark:

./build/v8-off/core_web_80_benchmark

Run the Google debug helper:

./scripts/google-debug-session.sh help

Backend selection

Backend selection currently happens through the application/backend factory and can be controlled via CLI/env paths already wired into the client.

Typical backend values:

• custom
• chromium

At the moment:

• custom is the primary working backend path
• chromium is under active bring-up in the sibling engine-chromium repo

Important directories

• src/app/ — application lifecycle and shell/backend integration
• src/backend_factory/ — backend construction/selection
• src/browser/ — navigation/controller logic
• src/debug/ — session/HUD/debug tooling
• src/engine_api/ — current engine/backend contract surface
• tests/ — client/end-to-end tests
• benchmarks/ — client-facing benchmarks
• scripts/ — browser-owned scripts
• docs/ — architecture, roadmap, benchmark, and planning docs

Repo hygiene / artifact policy

This repo intentionally tracks authored source, docs, scripts, tests, and selected benchmark material.

Use these rules while the rewrite is active:

• keep runtime/debug scratch output under ignored paths like artifacts/ or other local-only locations
• keep build system output out of git
• treat benchmark result history as something to commit selectively, not automatically
• if a generated artifact matters for a change, prefer a small curated summary over a pile of raw local output

Currently ignored examples include:

• build/
• artifacts/
• benchmarks/results/latest
• local editor/cache noise

Recommended doc map

Use these files as the main guide rails:

• README.md — quick orientation, build/run/test entry point, and current transition status
• TODO.md — active execution priorities
• docs/architecture.md — current practical architecture truth
• docs/architecture-roadmap.md — longer-horizon target architecture
• refactor.md — renderer split / migration execution plan
• PRD.md — product framing and original-to-current direction

Notes for contributors

• Keep client responsibilities client-sized: shell UX, lifecycle, tooling, diagnostics, and backend orchestration.
• Do not let engine-specific internals leak back into client unless they are explicitly transitional and documented as such.
• Do not add Chromium- or V8-specific dependency ownership here.
• If a dependency belongs primarily to one engine, it should live with that engine repo.
• When docs and code disagree during the transition, update the docs so the repo stays honest.