[ashx-j]

Phase 4a of the plugin system roadmap (#3, phase issue #8). It builds on #17, so until #14 to #17 merge this diff also shows their commits.

Until now plugins could only run on the server. This lets a plugin ship React code into the web app, and so into the desktop app, starting with two places it can show up: its own right panel in a thread, and its own settings panel on the Plugins page.

• Serving. The server serves each active plugin's web bundle at /api/plugins/<id>/web.js, with the same sign-in as the rest of /api. It reads the bundle from the plugin's real folder and refuses a path that resolves outside it.
• Loading. A small starter in the root route waits until the app is idle. On a server that advertises plugins, it follows plugins.subscribeStates and downloads the loader, its own chunk, only once an active plugin has a web part.
  • The loader fetches each bundle with the connection's bearer token or cookie and imports it from a blob: URL. A bare import(url) can't send credentials. The desktop CSP gains blob: in script-src for this.
  • A failed fetch, import or activate is shown on that plugin's row in Settings → Plugins, and other plugins keep loading.
  • Disabling, reloading or upgrading a plugin unloads its web part and everything it registered.
• Shared modules. Bundles take React, react-dom, the JSX runtime, a fixed set of atom hooks, a small set of UI primitives and the SDK from globalThis.__t3PluginHost, so they don't ship their own React. The loader chunk installs that object. The atom hooks are only ones the app already bundles, because exposing all of @effect/atom-react grew the shared startup chunk by 1.5 KB.
• Right panels. There's a new plugin right panel kind. Panels a plugin registers appear in the panel's add menu and in the empty panel's "Open a surface" list. While the plugin is unloaded, a plugin panel shows "Plugin not active" with a Close button, and a panel that throws shows an error notice instead of breaking the app. Reopening a closed plugin panel works like other panels.
• Settings panel. A plugin's own settings panel replaces the generated form on the Plugins page.
• Registries. Each registry is a module-level Map behind one version atom. Components read it through atoms derived from that version, because React Compiler would otherwise cache a plain lookup and never re-render.

Changes from the roadmap (issue #8 is updated):

• T3 Connect (DPoP) connections can't load web bundles yet. The fetch needs the relay signer, which only the client runtime holds. The Plugins page says so.
• Only the primary environment's plugins are loaded for now. Contributions carry their environment id, so adding other environments won't change the registries.
• Mobile doesn't load web plugins. Release builds can't load code, as the roadmap already says.
• Moved to 4b, where commands need them:
  • The SDK's Vite preset. hello-web is hand-written ESM against the shared modules.
  • Serving assets/ and api.assetUrl.
  • The settings, state, commands.run and navigate parts of the web API.
• Plugin panels have no keyboard shortcut letter in the "Open a surface" list. Built-in letters are fixed, and plugin titles could collide with them.

Measurements:

Bundle, from production web builds of #17's head and this branch, compared chunk by chunk:

• New chunks that only download on demand:

  • pluginLoader 3.8 KB, once an active plugin has a web part.
  • PluginPanelSurface 2.2 KB, when a plugin panel opens.
  • pluginWatch 0.4 KB and the plugin state atoms 0.8 KB, after idle on a plugin-capable server.
  • pluginRegistry 0.9 KB, with the right panel code.

• main grew 1.7 KB: the starter, plus an error boundary that moved in from another shared chunk (threadOverlayRetention shrank 0.4 KB).

• _chat grew 1.4 KB for the plugin panel kind in panel content and reopening.

• PanelLayoutControls grew 2.1 KB for the plugin entries in both panel menus.

• toast shrank 2.1 KB and a new localApi chunk of the same size appeared, so the loader can share that code. No net change.

• The shared utils chunk is unchanged.

• Renders: not measured. This PR changes no component on the timeline or sidebar paths, and none of them reads a plugin atom. The only new always-mounted component is the starter in the root route, which renders nothing.

• Loader start: in the dev server, the loader installed its shared modules 0.75 to 0.8 s after the thread view first rendered, over 3 runs. It waits for requestIdleCallback, so it never runs before first paint.

• With no plugins installed, or none with a web part, the loader chunk never downloads. The starter keeps one plugins.subscribeStates stream open, which sends one empty list and nothing after. Servers without the capability get no stream.

Screenshots:

Before this change, plugins had no web part. GitHub's CLI can't upload images, so the 5 screenshots are in the T3 thread for this work instead: the add menu and the empty panel listing "Hello panel", the open panel showing the server's greeting and the thread id, hello-web's own settings panel, and "Plugin not active" after disabling hello-web. They still need to be dragged into this description during review.

Test plugin: hello-web. Its web half registers a right panel that calls the plugin's server half (greeting), plus a settings panel.

Verification:

• pluginLoader.browser.test.ts loads the real hello-web bundle through a blob: import in Chromium, records a failing plugin's error, and unloads everything on stop.
• PluginPanelSurface.browser.test.tsx checks that a registered panel renders, then shows "Plugin not active" with a working Close once the plugin unloads.
• The PluginHost.test.ts web bundle route case checks the bundle is served while the plugin is active and gone after disabling.
• ElectronProtocol.test.ts covers the CSP change.
• In a browser against a dev server on seeded data, I opened the panel from both menus, saw the server's greeting, opened the custom settings panel, and saw "Plugin not active" after disabling. With hello-web off, the loader never ran. Enabling it started the loader without a reload.
• reactCompilerCoverage.test.ts passes, and vp run check:changed passed.
• Not verified: the desktop app. The CSP change is covered by its unit test only.

Review: an adversarial review of #18 to #22 found issues in this PR; the fixes are in #23.

---

PR filed by Claude Opus 5.5 in Claude Code through T3 Code.