@mochabug/adapt-electron

Adapt automations in native Electron views.

Electron 34.1.0 or later is required. This minimum comes from the View.getVisible() API added in Electron 34.1.0, which the client uses when applying content sizes. The peer dependency has no upper version limit; the development dependency selects the version used for building and testing.

Main area and forks

When no main content is present, the least nested non-minimized fork occupies the main area. A shallower arrival replaces it; equal-depth arrivals keep the current occupant. Real main content always wins, including retained completed content. When main arrives, the promoted fork returns to its previous group if it still exists, otherwise the default group for forkDisplay. The same WebContentsView is transferred, preserving its document and state without navigation.

Set reserveMain: true to reserve the main area for main content. Its default is false; client.setReserveMain(boolean) changes it at runtime without reloading views. Explicitly minimized forks stay minimized. Placement changes wait for active tab and separator drags to finish.

Completion and URL lifecycle

Session completion keeps the last main and fork views alive. URL policies control automatic closure: unspecified/retain keeps the view, recycle allows reuse, and close closes on URL completion, optionally after timeoutSeconds. Delayed closes continue after the session ends. Explicit stopping, panel dismissal, and client destruction still clean up views.

onContentActive(active) reports whether any main or fork URL remains open, including retained and minimized views. Keep Stop enabled while the session is running or content is active; disable it when the session has ended and the last URL closes.

Application theme

The Electron host owns one application-wide theme using Electron's native API:

import { nativeTheme } from "electron";

nativeTheme.themeSource = "dark"; // "light" or "system" also work

Set it before creating the client/views for the initial theme. Changes update native views and Adapt window chrome live. The client follows nativeTheme.shouldUseDarkColors; setTheme() supplies chrome color/font tokens. There is no per-client theme mode.

Plugins use the same HTML and CSS as web frames: an HTML-linked stylesheet with prefers-color-scheme media queries and a corresponding root color-scheme. This works for SSG before JavaScript runs. No Electron-specific plugin code or theme messages are needed. Existing IPC for trusted window chrome remains internal.

Content sizing

Plugins call init({ resize: true }) from @mochabug/adapt-sdk/browser. The SDK reports immediately and on content/viewport changes. The preload relays only adapt-resize reports; the main process validates the current main frame and expected origin. Native navigation clears cached sizes.

autoResizing controls docked reports to onContentResize(viewId, height); the host owns the surrounding window/layout bounds. floatingAutoResize fits a floating window once, preserving later manual sizing. Both policies can change without reloading plugins. Measurements remain cached while sizing is disabled and are applied only to visible active views at the reported viewport width.

init({ resize: false }) installs no SDK observers or messages. Use it for layouts whose height follows the viewport, such as height: 100vh. Themes work independently.

Run npm test for builds/unit tests and npm run test:e2e for real Electron window, splitter, theme, and resizing tests.