Developing the browser extension¶
Beta
The browser extension is in early development, and its build and test setup changes often. Please report bugs and they will be fixed promptly.
This page covers building the extension, adding a site and running its tests. Architecture explains how the parts fit together. The package is web/ in the repository, and web/README.md is a shorter, denser version of both pages.
Building¶
The extension is built with esbuild from web/, with TypeScript sources in web/src/.
just build-web # from the repository root
cd web && pnpm install && pnpm run build # the same, by hand
pnpm run build builds the client’s webview apps (pnpm --dir ../extension run build:webview) and then runs node esbuild.mjs. The output is web/dist/, which holds the manifest, one content script and one page script per site, the background, the palette, the options page, the config page and the panel pages. The build targets Firefox 128 and Chrome 128.
The package’s prepare step generates the client’s protobuf bindings, so the client’s dependencies have to be installed first. just build-web depends on install-ts for that reason.
The command palette is @appulsauce/ninja-keys from npm, a fork of ninja-keys (source).
web/manifest.json holds what is fixed. The build adds the content_scripts, the web_accessible_resources matches and the description from the site catalog, so the manifest never lists a site by hand. The manifest has both background.service_worker and background.scripts, for Chrome and Firefox. Its permissions are nativeMessaging and storage.
Three build modes share one script.
node esbuild.mjsbuildsweb/dist/.node esbuild.mjs --testbuildsweb/dist-test/, which also matches each site’s stand-in origin, a loopback address of its own. The end-to-end tests load it.node esbuild.mjs --devbuildsweb/dist-dev/and keeps watching. After each build it announces a build id over a loopback WebSocket on127.0.0.1:35817, and the dev extension reloads itself from disk withruntime.reload()when the id differs from its own. The release build refuses to contain any of the reload code.
For the dev build, run just dev-web from the repository root. It builds the release core and registers the host with Firefox. When CHROME_EXTENSION_ID is set it registers Chrome too. Then it runs pnpm run dev. Load web/dist-dev/manifest.json once. After a reload Firefox injects the new scripts into open tabs itself, and in Chrome the new background reloads the site tabs once.
just install-local-web builds the release core and web/dist and registers the host, as described in installing. just install-local does that and installs the VS Code extension as well.
Adding a site¶
A site is a few facts about where its editor is, what the open document is called and what language it is in. Everything else is shared. Three places hold a site, and a compile error or a unit test fails when they disagree.
Add a row to
SITESinweb/src/sites/catalog.ts: theidand anamefor the manifest’s description. Then the realorigins, and thepathson them as match-pattern paths such as/project/*. Last istest, the loopback origin and paths of the end-to-end stand-in. Real origins arehttps, a stand-in origin ishttp://localhostorhttp://127.0.0.<n>, and every id and origin is unique. The catalog file has no imports, because the build script loads it on its own.Write
web/src/sites/<id>.ts, exportingsiteof typeSiteModule. Itsworkspaceis aSiteWorkspace: the site’sidandprojectFromPath(pathname), which returns the project the URL names orundefined. The workspace key is<id>-<project>, and the native host accepts only 1 to 128 characters ofA-Z a-z 0-9 . _ -that do not start with a dot, so a project id has to be a URL-safe token. ItscreatePage()returns aSitePage, made in the page and never on import, because the background imports the module too.Register the module in
web/src/sites/workspaces.ts.SITE_MODULESis typed over the catalog’s ids, so a catalog row with no module does not compile, and a module cannot name a site the catalog lacks.
A SitePage has findEditor(), which returns an EditorHandle for the editor on the page now. For a CodeMirror 6 editor, build it with cm6Editor(view, name, languageId, foreignSpecs, path). For a block editor of contenteditable leaves, build it with domEditor(root, identity, name, languageId, rules, path), where rules is the DomEditorRules of web/src/editor/domAdapter.ts. A SitePage may also have dictionary (a SiteDictionarySource) and files (a SiteFiles, giving the site’s documents as workspace files). A site with neither has no dictionary and no files, as Gmail has neither.
The build derives the rest from the catalog (web/src/build/sites.ts). Each site’s content script and page script come from a generated entry. The manifest’s matches and description, the test build’s stand-in origins and the background’s table of origins (web/src/sites/registry.ts) come from it too. web/test/unit/siteCatalog.test.ts holds the catalog, the site modules and the derived manifest to each other.
Then add what a site needs to be tested. The stand-ins are in web/test/e2e/: fakeHost.ts plays Overleaf and Typst on two origins, fakeNotion.ts and fakeGmail.ts play the other two, and server.mjs serves them. Give a new site a stand-in on its catalog row’s origin and a realPath<Site>.spec.ts. Draw the stand-in from the live site’s markup, as the existing ones do. Gmail’s stand-in is served with Gmail’s Trusted Types policy, so an HTML-string sink in page code fails a test.
Testing¶
All commands run from web/.
pnpm run typecheck && pnpm run lint
pnpm test # unit tests: vitest, test/unit
pnpm run test:e2e # builds the test extension, then Playwright
pnpm run check # all of the above
just check covers the Rust core, the VS Code client and Lua, and does not run these.
The unit tests (web/test/unit/) run under vitest with the same vscode alias the build uses and no real browser.
The end-to-end tests (web/test/e2e/) have two kinds. The global setup builds the debug language-check-server and language-check-native-host with cargo, then the test extension with node esbuild.mjs --test.
realPath*.spec.tsdrive the whole path in Chromium with the real native host and the real core. Each test gets its own browser profile, its own data directory and its own host and server. The host is registered in the profile, and the stand-in sites are served byserver.mjson loopback addresses. Playwright runs Chromium through itschromiumchannel, because the headless shell cannot load extensions. Playwright cannot load an extension into Firefox, so this kind runs on Chromium only. The Overleaf and Typst stand-ins run CodeMirror 6.43 and 6.38, either side of the 6.39 rewrite. Tests run with no retries.pageLayer.spec.tsruns the built page bundle in Chromium and Firefox against a stub content script (stubContent.ts) whose answers can be held, so the window between an edit and its recheck can be seen. It needs no native host.
realPathSplit.spec.ts needs a Chromium newer than the one Playwright pins, because split views arrived in Chrome 155. Point LC_CHROMIUM at one:
LC_CHROMIUM=/path/to/chrome pnpm exec playwright test realPathSplit
What must behave the same in VS Code and in the browser is written once, in the client’s UI test directory, and both hosts run it. Each host’s spec supplies a driver for its own window and keeps only what is its host’s own.
Scenarios |
VS Code |
Browser |
|---|---|---|
|
|
|
|
|
|
|
|
|
Rust tests cover the host and the core’s web features: rust-core/src/native_host.rs has unit tests for admission and the config confinement, and rust-core/tests/server_protocol.rs runs against the server binary.
Scale, memory and benchmarks¶
realPathScale.spec.ts and realPathMemory.spec.ts are permanent fixtures for long documents and memory: a 4000-line document checked whole, the size cap, and heap snapshots. The snapshots must show no kind of object growing per re-check, panel cycle or file switch. The benchmarks and the soak run with pnpm run bench, under playwright.bench.config.ts, against the release core, one test at a time. They are not run in CI. Their method and results are in the benchmarks reference. web/.jscpd.json scans web/src together with the client’s sources for duplicated code.
Contributing¶
The conventions in CONTRIBUTING.md apply. A change that adds a field a page may send also changes parsePageRequest (see messages and validation).