tutti/packages/browser/workbench-node/README.md

@tutti-os/browser-node

Reusable Workbench Browser Node capability for Electron desktop hosts.

The package owns browser-node mechanics such as URL normalization, session partitioning, renderer state, React surfaces, webview security, and Electron guest lifecycle coordination. Product hosts own business bridge methods, diagnostics policy, loopback preview routing policy, and daemon or server clients.

The Browser Node overflow actions support page find, printing, zoom, fixed device emulation, visible-area and full-page screenshots, download progress and actions, Cookie import, and clearing the active session partition's browsing data. Its browser settings dialog groups current-session device, zoom, screenshot mode, download location, Cookie, and browsing-data controls. Screenshot save dialogs, Cookie-file and download-folder selection, and operating-system file open/reveal behavior are supplied by the host. Cookie file contents stay in the main process and are written only to the registered guest session.

Chrome and Dia login-state import

The optional Chrome and Dia import capability is host-injected. The Browser package owns renderer-safe profile contracts, Profile selection and prompt UI, normalized non-partitioned Cookie writes, aggregate results, and refreshing every registered ordinary Browser Node that shares the target Electron Session. It also publishes a macOS Chrome source adapter through @tutti-os/browser-node/chrome-cookie-import/macos; hosts supply only their feature-toggle and logging policy, then inject the returned discovery and preparation callbacks into the Electron main registration. The package does not own a product preference key.

The macOS adapter supports Google Chrome Stable at the standard ~/Library/Application Support/Google/Chrome location and Dia at ~/Library/Application Support/Dia/User Data. It discovers Default and Profile N entries from each browser's Local State, prepares a consistent SQLite snapshot, obtains the selected browser's Safe Storage secret from Keychain only after an explicit import, decrypts v10 values, and validates the version 24+ host hash before returning normalized Cookies to the Browser package. Paths, database contents, secrets, keys, decrypted values, and Cookie identifiers never cross into renderer code. A validated local Profile picture may cross as a size-limited PNG/JPEG data URL; local paths and Chrome-internal avatar URIs never do.

Import merges into the active ordinary persistent Browser session. It keeps session Cookies as session Cookies and skips expired, damaged, rejected, or partitioned (CHIPS) entries. Incognito nodes, custom Workspace App sessions, other Chromium browsers, custom user-data directories, and non-Cookie Chrome data are not supported. JSON and Netscape Cookie-file import remains available as a fallback. A user cancellation aborts preparation before any write; once the best-effort write phase starts, it runs to completion even if its window closes. Foreground imports report aggregate success, partial, zero-write, or failure feedback through the shared toast surface; a main-process notification remains the fallback after the originating window closes.

import { createMacosChromeCookieImportAdapter } from "@tutti-os/browser-node/chrome-cookie-import/macos";
import { registerBrowserNodeElectronMain } from "@tutti-os/browser-node/electron-main";

const chromeCookieImport = createMacosChromeCookieImportAdapter({
  isEnabled: () => true,
  logger
});

registerBrowserNodeElectronMain({
  ...chromeCookieImport,
  channels,
  getOwnerWindow,
  openExternal,
  registerHandler,
  resolveWebContents
});

For manual verification on macOS:

1. Open a normal persistent Browser Node and choose a discovered Chrome or Dia Profile from the prompt or Browser settings.
2. Allow the selected browser's Safe Storage Keychain request and verify signed-in sites reload in every open Browser Node sharing that Electron session.
3. Verify independent Profiles, incognito nodes, and Workspace App browsers do not reload or inherit the imported Cookies.
4. With Chrome or Dia writing Cookies, repeat the import; if snapshot validation fails, quit that browser and retry as prompted.

The package supports ordinary HTTP and HTTPS browser navigation by default. For hosts that need local runtime previews, the Electron main integration can also configure a package-owned loopback preview proxy through loopbackPreviewRouting.

For Workbench hosts, the package also exposes a dock helper through @tutti-os/browser-node/workbench. createBrowserDockEntry(...) wires the dock label, matches Browser nodes back to the dock entry, and restores popup title, URL subtitle, and preview capture from the Browser runtime state. Hosts that want the package-owned default dock visual can import it explicitly from @tutti-os/browser-node/assets/workspace-dock-website.png.

Browser Home and Agent automation

BrowserNode accepts an optional renderHome function for empty tabs. The function receives the tab node id and a navigate(url) callback, allowing a host to render live sandbox ports or other product-owned shortcuts without forking the Browser surface.

BrowserNode also accepts an optional renderError function for load failures, including HTTP status errors such as 502. The function receives the runtime error, formatted default copy, the tab node id, and navigate / reload callbacks. Hosts that omit it, or return null, keep the package default overlay.

Hosts that coordinate multiple Browser surfaces can use findBrowserNodePageByUrl(...) and activateBrowserNodePageByUrl(...). These helpers prefer a live runtime URL match, then retain the tab's requested URL as an alias for redirects and newly created pages without runtime state. Surface eligibility, top-level window focus, and whether a missing page opens in an existing or new Browser remain host policy.

Electron hosts may attach automationTarget metadata to User Browser and Agent Browser surfaces. The package registry then exposes the current workspace's User tabs and only the calling Agent session's Agent tabs, with stable page selection and per-tab leases. Website Apps remain excluded unless a host explicitly opts them in. new_page is created as about:blank; the package attaches request interception before navigating to the requested URL, so the initial document, redirects, and subresources all cross the same guard. Agent release is a lifecycle barrier: queued target work drains before guards are disabled and retained Agent pages are closed, and later calls fail closed.

createBrowserNodeAutomationServer publishes the registry on authenticated loopback and writes a private listener-info file for an explicitly configured daemon. createBrowserNodeAutomationNetworkAuthorizer accepts public, private, local-network, metadata, and loopback HTTP/HTTPS targets alike, matching manual Browser navigation reachability. Hosts should also install the authorizer as the registry's authorizeRequest callback so the initial navigation, redirects, subresources, and script-initiated requests retain the HTTP/HTTPS protocol boundary for the lifetime of an automation lease.