[loc]

Demo

import { createWindowPool, PooledWindow } from "@loc/electron-window";

const popoutPool = createWindowPool(
  { frame: true },
  { minIdle: 1 },
  {
    // injectStyles stays "auto" — onWindowSetup is additive, not a replacement.
    onWindowSetup: (childWindow, doc) => {
      // Each pooled window is its own browsing-context realm. Registrations on
      // the parent window's globals (e.g. a library calling
      // customElements.define at import time) are invisible here.
      if (!childWindow.customElements.get("my-widget")) {
        childWindow.customElements.define(
          "my-widget",
          class extends childWindow.HTMLElement { /* ... */ },
        );
      }
      doc.documentElement.dataset.theme = document.documentElement.dataset.theme;

      // Optional cleanup — runs when the window is destroyed.
      return () => { /* ... */ };
    },
  },
);

Runtime guard if you accidentally pass an async hook:

[electron-window] onWindowSetup must be synchronous. An async hook's errors
are not caught and its returned cleanup is dropped. Do dynamic imports at
module scope and call sync APIs in the hook.

Summary

Adds an additive per-window setup hook to createWindowPool for realm-specific initialization — custom element registration, prototype patches, documentElement attribute sync — without giving up the default injectStyles: "auto" style mirroring.

Why

Each pooled window is its own browsing-context realm: its own customElements registry, its own prototypes, its own document. A library that registers a custom element with shadow-DOM adoptedStyleSheets at import time registers it on the parent window's realm; the popout's realm never sees it, so the element renders unstyled.

Until now the only hook into pool window initialization was the function form of injectStyles, which replaces the auto <style>/<link> mirroring entirely (handleStyleInjection short-circuits when mode is a function). "Auto styles plus a bit more setup" had no clean home — apps either reimplemented the full MutationObserver-based style mirroring or did their setup in a per-component useLayoutEffect, which runs after React mounts content and risks a flash of unupgraded custom elements.

What

• New WindowSetupCallback type, exported.
• createWindowPool(shape, config?, options?) — options.onWindowSetup? is new. WindowPoolDefinition gains the corresponding field.
• The hook is threaded through initWindowDocument (whose body establishes the documented timing invariant: <base>, styles, #root in place) and runs at the bottom of that function, so the contract is enforced by construction rather than by call-site ordering. initWindowDocument now takes the child Window (the hook needs realm globals, which live on the window) and returns a single combined cleanup.
• Cleanup runs at most once, when the window is destroyed — not on release back to the pool. The hook fires once per window lifetime, not once per use.
• Errors in setup or cleanup are caught and logged (console.error) so a faulty hook can't poison pool warm-up or teardown.
• Runtime detection of async hooks — TypeScript's permissive void return rule lets async (win, doc) => ... through the type check, but at runtime its rejection escapes the error guard and its returned cleanup is silently dropped. The library fails loud instead.
• InjectStylesMode and its function-replaces-auto semantics are unchanged.

Behavior contract

• Runs: once per window the pool creates (including pre-warmed idle windows), after <base>/styles/#root, before React portals content in.
• Does not run: on re-acquire of a recycled window. Once per lifetime, not per use.
• Cleanup runs: on destroy (pool teardown, idle eviction, external close). At most once.
• Cleanup does not run: on release back to the pool.
• Survives reuse: realm globals (customElements, prototype patches), documentElement attributes, <head> contents.
• Reset on reuse: body.className, doc.title, #root contents, any other <body> children.
• Must be synchronous. Sync-only is enforced at runtime with a console.error.
• Errors contained. A throwing setup/cleanup is caught and logged.

Why not <Window> too

Non-pooled <Window> consumers have a React component already mounted when the document is ready — useWindowDocument() + useLayoutEffect does the same job at the same time. Pooled windows are pre-warmed before any consumer component exists, so there's no React lifecycle to hang an effect on. Documented as the recommended pattern in both the README and the pooling guide.

Implementation notes

• initWindowDocument(doc, options) → initWindowDocument(childWindow, options). Internal-only function (not in the package barrel); the three call sites all already hold the Window reference.
• PoolEntry.styleCleanup → PoolEntry.cleanup (it now does both teardowns). The four teardown sites change names, not logic.
• The combined cleanup is one-shot and drops its captured closure references after running, mirroring the defensive null-out in RendererWindowPool.destroyEntry so a lingering reference can't pin the consumer's setup closure (which plausibly captures the child Window).
• MockWindow in the test setup has no realm globals — documented as a known limitation in tests/setup.ts.

Tests

Added in tests/integration/PooledWindow.test.tsx:

• fires once per window with the child window+doc, after #root/<base> exist
• pre-warmed and on-the-fly windows both run setup
• returned cleanup runs on destroy / external close, not on release
• cleanup is idempotent across overlapping teardown paths (unload + notifyDestroyed)
• a throwing setup hook doesn't break pool warm-up
• a throwing cleanup doesn't break pool teardown
• runs independently of injectStyles mode (function form + setup hook coexist)
• async hook is detected, warned, and its eventual cleanup correctly not captured
• end-to-end prop-threading: createWindowPool → WindowPoolDefinition → <PooledWindow> → pool

Checklist

• yarn typecheck
• yarn test — 393 passed, 2 skipped
• yarn lint (oxlint)
• yarn format (oxfmt)
• Conventional commit (feat: → minor) per CONTRIBUTING.md
• Docs updated: README.md, docs/.../pooling.mdx, docs/.../props.mdx, JSDoc on WindowSetupCallback and createWindowPool

[github-actions]

🎉 This PR is included in version 1.2.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀