From 32bfd55d52f7be19d5f8ece61251bd7428a10474 Mon Sep 17 00:00:00 2001
From: Loc <loc@anthropic.com>
Date: Fri, 8 May 2026 10:56:05 -0700
Subject: [PATCH 1/2] feat: add per-window onWindowSetup hook to
 createWindowPool
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an additive per-window setup hook for realm-specific initialization
(custom element registration, prototype patches, documentElement attribute
sync) that runs once for each window the pool creates.

Each pooled window is its own browsing-context realm, so anything that
registers globals on the parent window (e.g. a library calling
customElements.define at import time) is invisible inside the popout.
Until now the only hook was the function form of injectStyles, which
replaces the default auto <style>/<link> mirroring entirely — so "auto
styles plus a bit more setup" had no clean home.

The hook is threaded through initWindowDocument (whose body establishes
the documented timing invariant: <base>, styles, and #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 (not just its Document) — the hook needs realm
globals which live on the window — and returns a single combined cleanup
that tears down both the consumer's setup and the style observer.

The cleanup is one-shot: it can be reached from overlapping teardown
paths (unload listener, notifyDestroyed, destroyEntry) and a consumer's
cleanup may not be naturally idempotent the way the style subscriber's
Set.delete is. A throwing setup or cleanup is caught and logged so a
faulty hook can't poison pool creation or teardown.

Cleanup runs when the window is destroyed (pool teardown, idle eviction,
external close), not on release back to the pool — the hook fires once
per window lifetime, not once per use. Documents what survives across
reuse (realm globals, documentElement attrs, head contents) and what
release() resets (body.className, doc.title, #root contents).

InjectStylesMode and its function-replaces-auto semantics are unchanged.
Exported as WindowSetupCallback.
---
 README.md                                |  40 +++-
 docs/src/content/docs/guides/pooling.mdx |  58 ++++-
 docs/src/content/docs/guides/props.mdx   |   2 +-
 src/renderer/PooledWindow.tsx            |  23 +-
 src/renderer/RendererWindowPool.ts       |  54 +++--
 src/renderer/Window.tsx                  |   2 +-
 src/renderer/index.ts                    |   1 +
 src/renderer/windowUtils.ts              | 107 ++++++++-
 src/shared/types.ts                      |  54 ++++-
 tests/integration/PooledWindow.test.tsx  | 271 +++++++++++++++++++++++
 tests/setup.ts                           |   9 +
 11 files changed, 580 insertions(+), 41 deletions(-)

diff --git a/README.md b/README.md
index 9b02e6b..3a8730f 100644
--- a/README.md
+++ b/README.md
@@ -174,7 +174,7 @@ The `default*` / controlled split follows React's `defaultValue` / `value` patte
 | `persistBounds`         | `string`                           | —        | Unique key. Saves bounds to localStorage, restores on reopen.    |
 | `recreateOnShapeChange` | `boolean`                          | `false`  | Recreate window when creation-only props change.                 |
 | `name`                  | `string`                           | —        | Debug label for DevTools and warning messages.                   |
-| `injectStyles`          | `"auto" \| false \| (doc) => void` | `"auto"` | How to copy styles into the child window. `false` for CSS-in-JS. |
+| `injectStyles`          | `"auto" \| false \| (doc) => void` | `"auto"` | How to copy styles into the child window. `false` for CSS-in-JS. The function form replaces auto mirroring entirely. |
 
 ## Hooks
 
@@ -267,6 +267,44 @@ On `open={true}`: acquires a pre-warmed window from the pool (instant). On `open
 
 Shape props (`transparent`, `frame`, `titleBarStyle`, `vibrancy`) and `injectStyles` are fixed by the pool definition. Most other props work per-use: `defaultWidth`/`defaultHeight` size the window on each acquire, and behavior props (`alwaysOnTop`, `opacity`, etc.) update live while open. `targetDisplay`, `persistBounds`, and `recreateOnShapeChange` are not accepted on `<PooledWindow>` (TypeScript error) — pool windows are pre-created and reused, so these don't fit the model.
 
+### Per-window setup (`onWindowSetup`)
+
+Each pooled window is its own browsing-context realm — it has its own `customElements` registry, its own prototypes, its own `document`. Code that registers globals on the *parent* window (e.g. a library calling `customElements.define(...)` at import time) won't be visible inside a pooled window.
+
+`onWindowSetup` is a per-window hook that runs once for each window the pool creates — including pre-warmed idle windows — right after the document is initialized (`<base>`, styles, and the `#root` container are in place) and **before React portals any content in**. That ordering matters: custom elements registered here upgrade synchronously as React inserts them, so there's no flash of unupgraded content the way a `useLayoutEffect` (which runs after mount) would risk.
+
+```tsx
+const popoutPool = createWindowPool(
+  { frame: true },
+  { minIdle: 1 },
+  {
+    // injectStyles stays "auto" — onWindowSetup is additive, not a replacement
+    onWindowSetup: (childWindow, doc) => {
+      // Register custom elements on the child realm's registry
+      if (!childWindow.customElements.get("my-widget")) {
+        childWindow.customElements.define("my-widget", class extends childWindow.HTMLElement {});
+      }
+      // Sync a documentElement attribute from the parent
+      doc.documentElement.dataset.theme = document.documentElement.dataset.theme;
+
+      // Optional cleanup, runs when the window is destroyed (pool teardown,
+      // idle eviction, or external close — not on hide/release back to pool).
+      return () => {
+        /* tear down listeners, observers, etc. */
+      };
+    },
+  },
+);
+```
+
+This is the sanctioned home for "auto styles **plus** a bit more per-window setup." The function form of `injectStyles` *replaces* the auto `<style>`/`<link>` mirroring — use it only when you want full control over style injection. `onWindowSetup` runs regardless of `injectStyles` mode.
+
+The hook **must be synchronous**. An `async` hook's rejection escapes the error guard and its returned cleanup is silently dropped — TypeScript won't warn (its `void` return rule is permissive), but the library detects it at runtime and logs an error. Do dynamic imports at module scope; keep the hook itself sync.
+
+**What survives across pool reuse.** The hook runs once per window *lifetime*, not once per use. A pooled window is acquired and released many times before it's destroyed, and `release()` resets `body.className`, `doc.title`, clears `#root`'s contents, and removes any other `<body>` children (e.g. portal mount points appended directly to `body`) between uses to prevent state leaking between consumers. Mutations to those will be silently reverted after the first reuse cycle. Mutations that **do** persist: realm globals (`customElements` registrations, prototype patches), `documentElement` attributes, and `<head>` contents (the style observer manages those separately). Stick to those in `onWindowSetup`; anything per-acquire belongs in your component's effect.
+
+For non-pooled `<Window>`, you don't need `onWindowSetup` — the window's lifetime matches your component's, so a `useWindowDocument()` + `useLayoutEffect` does the same job at the same time.
+
 **[Full pooling guide →](https://loc.github.io/electron-window/guides/pooling/)** — pool lifetime, `destroyWindowPool`, HMR handling, and the close-button behavior difference vs `<Window>`.
 
 ## Common Patterns
diff --git a/docs/src/content/docs/guides/pooling.mdx b/docs/src/content/docs/guides/pooling.mdx
index 1ab2802..d48d2ad 100644
--- a/docs/src/content/docs/guides/pooling.mdx
+++ b/docs/src/content/docs/guides/pooling.mdx
@@ -53,13 +53,14 @@ Changing these after pool creation has no effect — recreate the pool instead.
 | `maxIdle`     | `number` | `3`     | Maximum idle windows to retain                       |
 | `idleTimeout` | `number` | `30000` | Milliseconds before excess idle windows are destroyed |
 
-### Style injection (`options.injectStyles`)
+### Pool options (third argument)
 
 The third argument to `createWindowPool` is an options object:
 
-| Option         | Type                                   | Default    | Description                                                             |
-| -------------- | -------------------------------------- | ---------- | ----------------------------------------------------------------------- |
-| `injectStyles` | `"auto" \| false \| (doc) => void` | `"auto"` | How to copy styles into pool windows. `false` for CSS-in-JS frameworks. |
+| Option          | Type                                   | Default    | Description                                                             |
+| --------------- | -------------------------------------- | ---------- | ----------------------------------------------------------------------- |
+| `injectStyles`  | `"auto" \| false \| (doc) => void` | `"auto"` | How to copy styles into pool windows. `false` for CSS-in-JS frameworks. The function form **replaces** auto mirroring. |
+| `onWindowSetup` | `WindowSetupCallback` | — | Per-window setup hook. Runs once for each window the pool creates, after styles and `#root` are in place and before React portals content in. Must be synchronous. **Additive** — runs regardless of `injectStyles`. Optionally return a cleanup. |
 
 ```ts
 const overlayPool = createWindowPool(
@@ -69,6 +70,55 @@ const overlayPool = createWindowPool(
 );
 ```
 
+### Per-window setup (`options.onWindowSetup`)
+
+Each pooled window is its own browsing-context realm — its own `customElements` registry, its own prototypes, its own `document`. Code that registers globals on the parent window at import time isn't visible inside the pooled window.
+
+`onWindowSetup` runs once per window the pool creates — including pre-warmed idle windows — right after `<base>`, styles, and the `#root` portal container are in place, and **before React portals any content in**. That ordering is the point: custom elements registered here upgrade synchronously as React inserts them, with no flash of unupgraded content the way a `useLayoutEffect` (which runs after mount) would risk. Use it for realm-specific initialization without giving up the default `injectStyles: "auto"` style mirroring:
+
+```ts
+const popoutPool = createWindowPool(
+  { frame: true },
+  { minIdle: 1 },
+  {
+    onWindowSetup: (childWindow, doc) => {
+      // Register a custom element on the child realm
+      if (!childWindow.customElements.get("my-widget")) {
+        childWindow.customElements.define(
+          "my-widget",
+          class extends childWindow.HTMLElement {},
+        );
+      }
+      // Patch a prototype, sync a documentElement attribute, etc.
+      doc.documentElement.dataset.theme = document.documentElement.dataset.theme;
+
+      // Optional: cleanup runs when the window is destroyed (pool teardown,
+      // idle eviction, or external close — not on hide/release back to pool).
+      return () => {
+        /* ... */
+      };
+    },
+  },
+);
+```
+
+Compared to the function form of `injectStyles`, which **replaces** the auto `<style>`/`<link>` mirroring entirely, `onWindowSetup` is additive and runs in any `injectStyles` mode.
+
+The hook **must be synchronous**. An `async` hook's rejection escapes the error guard and its returned cleanup is silently dropped — TypeScript won't warn (its `void` return rule is permissive), but the library detects it at runtime and logs an error. Do dynamic imports at module scope; keep the hook itself sync. The full contract — error containment, partial-failure rollback, the `Window & typeof globalThis` parameter type — is on the exported `WindowSetupCallback` type.
+
+:::caution[What survives across pool reuse]
+The hook runs once per window **lifetime**, not once per use. A pooled window is acquired and released many times before it's destroyed, and `release()` resets `body.className`, `doc.title`, clears `#root`'s contents, and removes any other `<body>` children (e.g. a portal mount point appended directly to `body`) between uses to prevent state leaking between consumers. Mutations to those will be silently reverted after the first reuse cycle.
+
+Mutations that **do** persist across reuse:
+- Realm globals — `customElements` registrations, prototype patches
+- `documentElement` attributes (e.g. `dataset.theme`)
+- `<head>` contents (the style observer manages those separately)
+
+Anything that should reset per-acquire belongs in your component's effect, not `onWindowSetup`.
+:::
+
+For non-pooled `<Window>`, you don't need `onWindowSetup` — the window's lifetime matches your component's, so `useWindowDocument()` + `useLayoutEffect` does the same job at the same time.
+
 ## `<PooledWindow>` Props
 
 `PooledWindow` accepts most `<Window>` props except creation-only shape props (those are fixed by the pool). Behavior props — `alwaysOnTop`, `title`, event handlers, etc. — can vary per use and update live while open.
diff --git a/docs/src/content/docs/guides/props.mdx b/docs/src/content/docs/guides/props.mdx
index 3eccdf2..5b292a6 100644
--- a/docs/src/content/docs/guides/props.mdx
+++ b/docs/src/content/docs/guides/props.mdx
@@ -95,6 +95,6 @@ Setting `open={false}` destroys the window via `BrowserWindow.destroy()`, which
 | `persistBounds`         | `string`                           | —        | Unique key. Saves bounds to localStorage, restores on reopen.    |
 | `recreateOnShapeChange` | `boolean`                          | `false`  | Recreate window when creation-only props change.                 |
 | `name`                  | `string`                           | —        | Debug label for DevTools and warning messages.                   |
-| `injectStyles`          | `"auto" \| false \| (doc) => void` | `"auto"` | How to copy styles into the child window. `false` for CSS-in-JS. |
+| `injectStyles`          | `"auto" \| false \| (doc) => void` | `"auto"` | How to copy styles into the child window. `false` for CSS-in-JS. The function form replaces auto mirroring entirely. |
 
 For `persistBounds` and the `usePersistedBounds` hook, see [Persistence](/electron-window/guides/persistence/).
diff --git a/src/renderer/PooledWindow.tsx b/src/renderer/PooledWindow.tsx
index 16fe83e..2461b2a 100644
--- a/src/renderer/PooledWindow.tsx
+++ b/src/renderer/PooledWindow.tsx
@@ -8,6 +8,7 @@ import type {
   WindowPoolConfig,
   BaseWindowProps,
   InjectStylesMode,
+  WindowSetupCallback,
 } from "../shared/types.js";
 import {
   CREATION_ONLY_PROPS,
@@ -62,6 +63,7 @@ export interface WindowPoolDefinition {
   config?: WindowPoolConfig;
   debug?: boolean;
   injectStyles?: InjectStylesMode;
+  onWindowSetup?: WindowSetupCallback;
 }
 
 // Singleton pool instances keyed by pool definition. Pools outlive individual
@@ -80,14 +82,28 @@ const poolInstances = new WeakMap<WindowPoolDefinition, RendererWindowPool>();
  * @param options.injectStyles - How to inject styles into pool windows.
  *   - "auto": Copy <style> and <link> tags from parent (default)
  *   - false: No injection (for CSS-in-JS frameworks)
- *   - function: Custom injection
+ *   - function: Custom injection (REPLACES auto mirroring)
+ * @param options.onWindowSetup - Per-window setup hook. Runs once for each
+ *   window the pool creates (including pre-warmed idle windows), after
+ *   `<base>`, styles, and the `#root` portal container are in place — and
+ *   before React portals any content in. Must be synchronous. Use it for
+ *   realm-specific initialization on the child window — custom element
+ *   registration, prototype patches, etc. Additive: runs regardless of
+ *   `injectStyles` mode. Optionally return a cleanup function; it runs
+ *   when the window is destroyed. See {@link WindowSetupCallback} for the
+ *   full contract.
  */
 export function createWindowPool(
   shape: PoolShape,
   config?: WindowPoolConfig,
-  options?: { injectStyles?: InjectStylesMode },
+  options?: { injectStyles?: InjectStylesMode; onWindowSetup?: WindowSetupCallback },
 ): WindowPoolDefinition {
-  return { shape, config: config ?? {}, injectStyles: options?.injectStyles };
+  return {
+    shape,
+    config: config ?? {},
+    injectStyles: options?.injectStyles,
+    onWindowSetup: options?.onWindowSetup,
+  };
 }
 
 /** @deprecated Use createWindowPool instead */
@@ -201,6 +217,7 @@ export const PooledWindow = forwardRef<PooledWindowRef, PooledWindowProps>(funct
         config: poolDef.config,
         debug: poolDef.debug,
         injectStyles: poolDef.injectStyles,
+        onWindowSetup: poolDef.onWindowSetup,
         registerWindow: provider.registerWindow,
         unregisterWindow: provider.unregisterWindow,
         updateWindow: provider.updateWindow,
diff --git a/src/renderer/RendererWindowPool.ts b/src/renderer/RendererWindowPool.ts
index 547fb99..621ed19 100644
--- a/src/renderer/RendererWindowPool.ts
+++ b/src/renderer/RendererWindowPool.ts
@@ -4,6 +4,7 @@ import type {
   InjectStylesMode,
   TitleBarStyle,
   VibrancyType,
+  WindowSetupCallback,
 } from "../shared/types.js";
 import { POOL_RELEASE_PROP_DEFAULTS } from "../shared/types.js";
 import { waitForWindowReady, initWindowDocument } from "./windowUtils.js";
@@ -24,7 +25,11 @@ interface PoolEntry {
   id: string;
   childWindow: globalThis.Window;
   portalTarget: HTMLElement;
-  styleCleanup: () => void;
+  /**
+   * Combined teardown returned by `initWindowDocument` — runs the consumer's
+   * `onWindowSetup` cleanup and disconnects the style observer. Idempotent.
+   */
+  cleanup: () => void;
 }
 
 export interface RendererWindowPoolOptions {
@@ -32,6 +37,13 @@ export interface RendererWindowPoolOptions {
   config?: WindowPoolConfig;
   debug?: boolean;
   injectStyles?: InjectStylesMode;
+  /**
+   * Per-window setup hook. Runs once for each window the pool creates —
+   * including pre-warmed idle windows — after `initWindowDocument` finishes
+   * (`<base>`, styles, and `#root` are in place). Forwarded to
+   * `initWindowDocument`; see {@link WindowSetupCallback} for the contract.
+   */
+  onWindowSetup?: WindowSetupCallback;
   // Injected by PooledWindow from WindowProviderContext
   registerWindow: (id: string, props: Record<string, unknown>) => Promise<boolean>;
   unregisterWindow: (id: string) => Promise<void>;
@@ -66,6 +78,7 @@ export class RendererWindowPool {
   private windowAction: RendererWindowPoolOptions["windowAction"];
   private readonly debug: boolean;
   private readonly injectStyles: InjectStylesMode;
+  private readonly onWindowSetup?: WindowSetupCallback;
 
   private isDestroyed = false;
   private inFlight = 0;
@@ -90,6 +103,7 @@ export class RendererWindowPool {
     this.windowAction = options.windowAction;
     this.debug = options.debug ?? false;
     this.injectStyles = options.injectStyles ?? "auto";
+    this.onWindowSetup = options.onWindowSetup;
   }
 
   /**
@@ -182,13 +196,11 @@ export class RendererWindowPool {
         return;
       }
 
-      const { container: portalTarget, cleanup: styleCleanup } = initWindowDocument(
-        childWindow.document,
-        {
-          injectStyles: this.injectStyles,
-        },
-      );
-      const entry: PoolEntry = { id, childWindow, portalTarget, styleCleanup };
+      const { container: portalTarget, cleanup } = initWindowDocument(childWindow, {
+        injectStyles: this.injectStyles,
+        onWindowSetup: this.onWindowSetup,
+      });
+      const entry: PoolEntry = { id, childWindow, portalTarget, cleanup };
       this.idle.push(entry);
       this.debugLog("idle window ready", id);
 
@@ -197,7 +209,7 @@ export class RendererWindowPool {
       // treat it as destruction if the window is actually closed.
       childWindow.addEventListener("unload", () => {
         if (childWindow.closed) {
-          styleCleanup();
+          cleanup();
           scheduleLeakCheck(childWindow, id);
           this.debugLog("window destroyed externally", id);
           this.handleWindowDestroyed(id);
@@ -289,24 +301,22 @@ export class RendererWindowPool {
         throw new Error("Pool destroyed during acquire");
       }
 
-      const { container: portalTarget, cleanup: styleCleanup } = initWindowDocument(
-        childWindow.document,
-        {
-          injectStyles: this.injectStyles,
-        },
-      );
+      const { container: portalTarget, cleanup } = initWindowDocument(childWindow, {
+        injectStyles: this.injectStyles,
+        onWindowSetup: this.onWindowSetup,
+      });
       const newEntry: PoolEntry = {
         id,
         childWindow,
         portalTarget,
-        styleCleanup,
+        cleanup,
       };
       this.active.set(id, newEntry);
 
       // Handle external destruction for on-the-fly windows too
       childWindow.addEventListener("unload", () => {
         if (childWindow.closed) {
-          styleCleanup();
+          cleanup();
           scheduleLeakCheck(childWindow, id);
           this.handleWindowDestroyed(id);
         }
@@ -356,7 +366,7 @@ export class RendererWindowPool {
     // The window may have been destroyed main-side during the IPC awaits
     // above (e.g., parent-crash cleanup). Accessing .document on a closed
     // Window proxy throws. release() is void-ed by callers, so that throw
-    // becomes an unhandled rejection AND skips styleCleanup → subscriber leak.
+    // becomes an unhandled rejection AND skips cleanup → subscriber leak.
     if (entry.childWindow.closed) {
       this.debugLog("window closed during release, discarding", id);
       this.destroyEntry(entry);
@@ -408,14 +418,14 @@ export class RendererWindowPool {
    * Destroy a pool entry. Pool windows have hideOnClose: true, so
    * childWindow.close() would be a no-op (preventDefaulted + hidden +
    * spurious userCloseRequested event). We rely solely on unregisterWindow →
-   * BrowserWindow.destroy() which bypasses the close handler. styleCleanup
+   * BrowserWindow.destroy() which bypasses the close handler. cleanup()
    * must run explicitly since destroy() doesn't fire unload.
    */
   private destroyEntry(entry: PoolEntry): void {
     // Idempotency guard — the null-out below means a second call on the
-    // same entry would pass null to styleCleanup.
+    // same entry would pass null to cleanup.
     if (!entry.childWindow) return;
-    entry.styleCleanup();
+    entry.cleanup();
     const timer = this.idleTimers.get(entry.id);
     if (timer) {
       clearTimeout(timer);
@@ -498,7 +508,7 @@ export class RendererWindowPool {
     // from main doesn't fire unload — this path must clean up explicitly.
     const entry = this.active.get(id) ?? this.idle.find((e) => e.id === id);
     if (entry) {
-      entry.styleCleanup();
+      entry.cleanup();
       scheduleLeakCheck(entry.childWindow, id);
     }
     this.handleWindowDestroyed(id);
diff --git a/src/renderer/Window.tsx b/src/renderer/Window.tsx
index 724a97f..de8e0c8 100644
--- a/src/renderer/Window.tsx
+++ b/src/renderer/Window.tsx
@@ -317,7 +317,7 @@ export const Window = forwardRef<WindowRef, WindowProps>(function Window(props,
         return;
       }
 
-      const { container, cleanup: styleCleanup } = initWindowDocument(win.document, {
+      const { container, cleanup: styleCleanup } = initWindowDocument(win, {
         injectStyles,
         title,
       });
diff --git a/src/renderer/index.ts b/src/renderer/index.ts
index a1a2633..7133ca6 100644
--- a/src/renderer/index.ts
+++ b/src/renderer/index.ts
@@ -63,6 +63,7 @@ export type {
   TitleBarStyle,
   VibrancyType,
   InjectStylesMode,
+  WindowSetupCallback,
   TargetDisplay,
   WindowPoolConfig,
 } from "../shared/types.js";
diff --git a/src/renderer/windowUtils.ts b/src/renderer/windowUtils.ts
index fffbca0..405ba8e 100644
--- a/src/renderer/windowUtils.ts
+++ b/src/renderer/windowUtils.ts
@@ -1,5 +1,5 @@
 import { sleep } from "../shared/utils.js";
-import type { InjectStylesMode } from "../shared/types.js";
+import type { InjectStylesMode, WindowSetupCallback } from "../shared/types.js";
 
 export const WINDOW_READY_TIMEOUT_MS = 4000;
 export const BOUNDS_CHANGE_DEBOUNCE_MS = 100;
@@ -25,22 +25,47 @@ export async function waitForWindowReady(
 export interface InitWindowDocumentResult {
   /** The portal container element */
   container: HTMLElement;
-  /** Call to disconnect the style observer and clean up */
+  /**
+   * Call when the child window is destroyed. Runs the consumer's
+   * `onWindowSetup` teardown (if any) and disconnects the style observer.
+   * Idempotent: callers can reach teardown from multiple paths (unload
+   * listener, pool eviction, external destroy) without double-running
+   * consumer cleanup.
+   */
   cleanup: () => void;
 }
 
+export interface InitWindowDocumentOptions {
+  injectStyles?: InjectStylesMode;
+  title?: string;
+  /**
+   * Per-window setup hook. Runs after `<base>`, styles, and the `#root`
+   * portal container are in place. Additive — runs regardless of
+   * `injectStyles` mode. Optionally returns a cleanup, which is folded
+   * into the returned `cleanup()`.
+   */
+  onWindowSetup?: WindowSetupCallback;
+}
+
 /**
  * Set up a child window's document for portal rendering.
- * Clears the document, adds a base href, injects styles, creates the portal container.
+ * Clears the document, adds a base href, injects styles, creates the portal
+ * container, and runs the consumer's `onWindowSetup` hook.
  *
  * When injectStyles is "auto", a MutationObserver keeps child styles in sync
- * with the parent as new styles are added/removed/modified (e.g., Tailwind JIT, HMR).
- * Call cleanup() when the child window closes to disconnect the observer.
+ * with the parent as new styles are added/removed/modified (e.g., Tailwind JIT,
+ * HMR). Call cleanup() when the child window closes to disconnect the observer
+ * and run any consumer-provided teardown.
+ *
+ * Takes the child `Window` (not just its `Document`) so the setup hook can
+ * reach realm globals — `customElements`, prototype constructors, etc. —
+ * which live on the window, not the document.
  */
 export function initWindowDocument(
-  doc: Document,
-  options: { injectStyles?: InjectStylesMode; title?: string } = {},
+  childWindow: globalThis.Window,
+  options: InitWindowDocumentOptions = {},
 ): InitWindowDocumentResult {
+  const doc = childWindow.document;
   doc.head.innerHTML = "";
   doc.body.innerHTML = "";
 
@@ -48,7 +73,12 @@ export function initWindowDocument(
   base.href = window.location.origin;
   doc.head.appendChild(base);
 
-  const cleanup = handleStyleInjection(doc, options.injectStyles ?? "auto");
+  // `let` (not `const`) so the cleanup closure can null these out after
+  // running — see the cleanup body below for why.
+  let styleCleanup: (() => void) | undefined = handleStyleInjection(
+    doc,
+    options.injectStyles ?? "auto",
+  );
 
   if (options.title) {
     doc.title = options.title;
@@ -58,6 +88,67 @@ export function initWindowDocument(
   container.id = "root";
   doc.body.appendChild(container);
 
+  // Run consumer setup AFTER <base>, styles, and #root are in place — this
+  // is the invariant the hook's contract documents, so it lives next to the
+  // code that establishes it. Errors are caught so a faulty hook can't
+  // poison window creation. Cast: `window.open()` is typed `Window | null`,
+  // but a same-origin child window is genuinely a global object at runtime,
+  // and the hook needs realm constructors (`childWindow.HTMLElement`) and
+  // realm globals (`childWindow.customElements`) that only exist on the
+  // global-object intersection type. This is the one place in the codebase
+  // that uses `Window & typeof globalThis` instead of `globalThis.Window` —
+  // the divergence is the point.
+  let setupCleanup: (() => void) | undefined;
+  if (options.onWindowSetup) {
+    try {
+      const result = options.onWindowSetup(childWindow as Window & typeof globalThis, doc);
+      if (result instanceof Promise) {
+        // TS's permissive `void` rule lets `async (win, doc) => ...` through
+        // the type check. An async hook would (a) have its rejection escape
+        // the try/catch as an unhandled rejection, and (b) silently drop any
+        // cleanup it eventually resolves to (`typeof Promise !== "function"`).
+        // Fail loud instead of silently mishandling both.
+        console.error(
+          "[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.",
+        );
+        result.catch((err) => {
+          console.error("[electron-window] async onWindowSetup rejected:", err);
+        });
+      } else if (typeof result === "function") {
+        setupCleanup = result;
+      }
+    } catch (err) {
+      console.error("[electron-window] onWindowSetup threw:", err);
+    }
+  }
+
+  // Combined, one-shot cleanup. The style subscriber's teardown is naturally
+  // idempotent (Set.delete), but a consumer's setup teardown may not be —
+  // and callers can reach this from overlapping paths (unload listener +
+  // notifyDestroyed + destroyEntry).
+  let cleaned = false;
+  const cleanup = (): void => {
+    if (cleaned) return;
+    cleaned = true;
+    if (setupCleanup) {
+      try {
+        setupCleanup();
+      } catch (err) {
+        console.error("[electron-window] onWindowSetup cleanup threw:", err);
+      }
+    }
+    styleCleanup?.();
+    // Drop captured refs so a lingering reference to `cleanup` (held by the
+    // unload listener, a PoolEntry, or a debounced callback) doesn't pin the
+    // consumer's setup closure — which plausibly captures the child Window
+    // and its detached realm. Mirrors the defensive null-out in
+    // RendererWindowPool.destroyEntry.
+    setupCleanup = undefined;
+    styleCleanup = undefined;
+  };
+
   return { container, cleanup };
 }
 
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 2b23e04..b2cbd39 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -37,6 +37,58 @@ export type AlwaysOnTopLevel =
  */
 export type InjectStylesMode = "auto" | false | ((targetDocument: Document) => void);
 
+/**
+ * Per-window setup hook for pooled windows.
+ *
+ * Runs once for each window the pool creates, after the document has been
+ * initialized (`<base>` href, style injection, and the `#root` portal
+ * container are all in place) and **before React portals any content in**.
+ * Custom elements registered here upgrade synchronously as React inserts
+ * them — no flash of unstyled/unupgraded content the way a `useLayoutEffect`
+ * (which runs after mount) would risk. Use it for realm-specific
+ * initialization that must happen on the child window's globals — registering
+ * custom elements on the child `customElements` registry, patching
+ * prototypes, syncing `document.documentElement` attributes, etc.
+ *
+ * Unlike the function form of {@link InjectStylesMode}, this is *additive*:
+ * it runs regardless of `injectStyles` mode and does not replace the default
+ * `"auto"` style mirroring.
+ *
+ * Optionally return a cleanup function. It runs **at most once**, when the
+ * window is destroyed (pool teardown, idle eviction, external close) —
+ * alongside the style observer cleanup. It does NOT run on release back to
+ * the pool: the hook fires once per window *lifetime*, not once per use.
+ * The hook must be synchronous — an `async` hook's rejection escapes the
+ * error guard and its returned cleanup is dropped (the library logs an
+ * error if it detects this).
+ *
+ * **Errors are contained.** A throwing setup hook (or cleanup) is caught and
+ * logged to `console.error`; it won't take down pool warm-up or teardown.
+ * Don't rely on a hook side-effect that you haven't verified actually ran.
+ *
+ * **What survives across pool reuse:** registrations on realm globals
+ * (`customElements`, prototype patches), `documentElement` attributes, and
+ * `<head>` contents persist. The pool's `release()` resets `body.className`,
+ * `doc.title`, clears `#root`'s contents, and removes any other `<body>`
+ * children between uses — don't rely on those from setup.
+ *
+ * **If your setup throws partway through, no cleanup is captured** — the
+ * return value is never reached. If partial mutations must be undone on
+ * failure (only), use `try/catch` and re-throw: catch, roll back, `throw err`.
+ * (Don't reach for `try/finally` — `finally` runs on success too and would
+ * unconditionally undo your setup.)
+ *
+ * The `childWindow` parameter is typed `Window & typeof globalThis` (not the
+ * codebase's usual `globalThis.Window`) so realm constructors like
+ * `childWindow.HTMLElement` and realm globals like `childWindow.customElements`
+ * are reachable without a cast — they live on the global-object intersection,
+ * not on `Window` alone.
+ */
+export type WindowSetupCallback = (
+  childWindow: Window & typeof globalThis,
+  doc: Document,
+) => void | (() => void);
+
 /**
  * Target display for window placement
  */
@@ -497,7 +549,7 @@ export interface BaseWindowProps {
    * How to inject styles into the new window.
    * - "auto": Copy <style> and <link> tags from parent (default)
    * - false: No injection (for CSS-in-JS)
-   * - function: Custom injection
+   * - function: Custom injection (replaces the auto mirroring entirely)
    */
   injectStyles?: InjectStylesMode;
 
diff --git a/tests/integration/PooledWindow.test.tsx b/tests/integration/PooledWindow.test.tsx
index f47ed7e..9829e4c 100644
--- a/tests/integration/PooledWindow.test.tsx
+++ b/tests/integration/PooledWindow.test.tsx
@@ -149,6 +149,277 @@ describe("createWindowPool", () => {
     expect(a.shape).toEqual(b.shape);
     expect(a.config).toEqual(b.config);
   });
+
+  it("threads onWindowSetup through to the pool definition", () => {
+    const onWindowSetup = vi.fn();
+    const pool = createWindowPool({}, undefined, { onWindowSetup });
+    expect(pool.onWindowSetup).toBe(onWindowSetup);
+  });
+});
+
+// ─── onWindowSetup ───────────────────────────────────────────────────────────
+
+describe("onWindowSetup", () => {
+  beforeEach(() => {
+    resetMockWindows();
+    resetMockWindowsGlobal();
+    vi.clearAllMocks();
+  });
+
+  async function makePool(
+    onWindowSetup: import("../../src/shared/types.js").WindowSetupCallback,
+    config: { minIdle?: number; maxIdle?: number } = { minIdle: 1, maxIdle: 3 },
+  ) {
+    const { RendererWindowPool } = await import("../../src/renderer/RendererWindowPool.js");
+    return new RendererWindowPool({
+      shape: {},
+      config,
+      onWindowSetup,
+      registerWindow: vi.fn(async () => true),
+      unregisterWindow: vi.fn(async () => {}),
+      updateWindow: vi.fn(async () => {}),
+      windowAction: vi.fn(async () => {}),
+    });
+  }
+
+  it("fires once per pooled window with the child window and document", async () => {
+    const calls: Array<{ win: unknown; doc: Document }> = [];
+    // maxIdle=1 keeps the pool from replenishing in the background after
+    // acquire() — that path is async and would make `calls.length` racy.
+    const pool = await makePool(
+      (win, doc) => {
+        calls.push({ win, doc });
+      },
+      { minIdle: 1, maxIdle: 1 },
+    );
+
+    // Pre-warmed idle window (created during warmUp, not on first acquire)
+    await pool.warmUp();
+    expect(calls).toHaveLength(1);
+
+    // The callback receives the *child* window/doc, not the parent's.
+    expect(calls[0]!.win).not.toBe(window);
+    expect(calls[0]!.doc).not.toBe(document);
+    expect((calls[0]!.win as { document: Document }).document).toBe(calls[0]!.doc);
+
+    // Document was already initialized by initWindowDocument when the hook ran:
+    // <base> and #root exist.
+    expect(calls[0]!.doc.querySelector("base")).not.toBeNull();
+    expect(calls[0]!.doc.getElementById("root")).not.toBeNull();
+
+    // Acquiring the pre-warmed window does NOT re-run setup (it ran at create time).
+    const e1 = await pool.acquire();
+    expect(calls).toHaveLength(1);
+
+    // On-the-fly creation when the pool is exhausted DOES run setup.
+    const e2 = await pool.acquire();
+    expect(calls).toHaveLength(2);
+    expect(calls[1]!.win).not.toBe(calls[0]!.win);
+
+    await pool.release(e1.id);
+    await pool.release(e2.id);
+    pool.destroy();
+  });
+
+  it("runs the returned cleanup when the window is destroyed, not on release", async () => {
+    const cleanup = vi.fn();
+    const pool = await makePool(() => cleanup, { minIdle: 1, maxIdle: 1 });
+
+    await pool.warmUp();
+    const entry = await pool.acquire();
+    expect(cleanup).not.toHaveBeenCalled();
+
+    // Release returns the window to the idle pool — it stays alive, no cleanup.
+    await pool.release(entry.id);
+    expect(cleanup).not.toHaveBeenCalled();
+    expect(pool.getIdleCount()).toBe(1);
+
+    // destroy() tears down all idle entries → cleanup fires once per window.
+    pool.destroy();
+    expect(cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it("runs the returned cleanup when the window is closed externally (unload)", async () => {
+    const cleanup = vi.fn();
+    const pool = await makePool(() => cleanup, { minIdle: 1, maxIdle: 1 });
+
+    await pool.warmUp();
+    const entry = await pool.acquire();
+    expect(cleanup).not.toHaveBeenCalled();
+
+    // External close → unload listener fires setupCleanup + styleCleanup.
+    (entry.childWindow as unknown as { simulateUnload: () => void }).simulateUnload();
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    pool.destroy();
+  });
+
+  it("returned cleanup is idempotent across overlapping teardown paths", async () => {
+    const cleanup = vi.fn();
+    const pool = await makePool(() => cleanup, { minIdle: 1, maxIdle: 1 });
+
+    await pool.warmUp();
+    const entry = await pool.acquire();
+
+    // Main-process `closed` event arrives → notifyDestroyed tears down the entry.
+    pool.notifyDestroyed(entry.id);
+    expect(cleanup).toHaveBeenCalledTimes(1);
+
+    // The unload listener captures the same setupCleanup wrapper. A late
+    // renderer-side unload must not double-run the consumer's cleanup —
+    // unlike the style subscriber's Set.delete(), consumer code may not
+    // be naturally idempotent.
+    (entry.childWindow as unknown as { simulateUnload: () => void }).simulateUnload();
+    expect(cleanup).toHaveBeenCalledTimes(1);
+
+    pool.destroy();
+    expect(cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it("a throwing onWindowSetup does not break window creation", async () => {
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const pool = await makePool(() => {
+      throw new Error("boom");
+    });
+
+    await pool.warmUp();
+    expect(pool.getIdleCount()).toBe(1);
+    expect(consoleError).toHaveBeenCalledWith(
+      expect.stringContaining("onWindowSetup threw"),
+      expect.any(Error),
+    );
+
+    // The window is still usable.
+    const entry = await pool.acquire();
+    expect(entry.childWindow.closed).toBe(false);
+    await pool.release(entry.id);
+    pool.destroy();
+    consoleError.mockRestore();
+  });
+
+  it("runs setup independently of injectStyles mode", async () => {
+    const { RendererWindowPool } = await import("../../src/renderer/RendererWindowPool.js");
+    const customInject = vi.fn();
+    const onWindowSetup = vi.fn();
+    const pool = new RendererWindowPool({
+      shape: {},
+      config: { minIdle: 1 },
+      // Function form REPLACES auto mirroring — onWindowSetup must still run.
+      injectStyles: customInject,
+      onWindowSetup,
+      registerWindow: vi.fn(async () => true),
+      unregisterWindow: vi.fn(async () => {}),
+      updateWindow: vi.fn(async () => {}),
+      windowAction: vi.fn(async () => {}),
+    });
+
+    await pool.warmUp();
+    expect(customInject).toHaveBeenCalledTimes(1);
+    expect(onWindowSetup).toHaveBeenCalledTimes(1);
+    pool.destroy();
+  });
+
+  it("warns and discards an async onWindowSetup instead of dropping its cleanup silently", async () => {
+    // TS's permissive `void` rule lets `async (win, doc) => ...` pass the
+    // type check. The runtime check should fail loud instead of silently
+    // mishandling the rejection and the dropped cleanup.
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const cleanup = vi.fn();
+    const pool = await makePool(
+      // No `@ts-expect-error` — TS's permissive `void` return-type rule means
+      // `async () => fn` IS assignable to `() => void | (() => void)`. That's
+      // exactly the footgun the runtime check is for: the type system can't
+      // catch it, so the library must.
+      async () => {
+        await Promise.resolve();
+        return cleanup;
+      },
+      { minIdle: 1, maxIdle: 1 },
+    );
+
+    await pool.warmUp();
+    expect(consoleError).toHaveBeenCalledWith(
+      expect.stringContaining("onWindowSetup must be synchronous"),
+    );
+
+    // The eventually-resolved cleanup was never captured — it does NOT run
+    // on destroy. (This is the failure mode the warning is for.)
+    pool.destroy();
+    // Flush the microtask queue so the async hook's promise settles.
+    await Promise.resolve();
+    expect(cleanup).not.toHaveBeenCalled();
+    consoleError.mockRestore();
+  });
+
+  it("a throwing cleanup does not break pool teardown", async () => {
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const cleanupCalls: number[] = [];
+    let n = 0;
+    const pool = await makePool(
+      () => {
+        const i = ++n;
+        return () => {
+          cleanupCalls.push(i);
+          throw new Error(`cleanup ${i} boom`);
+        };
+      },
+      { minIdle: 2, maxIdle: 2 },
+    );
+
+    await pool.warmUp();
+    expect(pool.getIdleCount()).toBe(2);
+
+    // destroy() iterates all idle entries — a throwing cleanup on the first
+    // must not skip the second.
+    pool.destroy();
+    expect(cleanupCalls).toHaveLength(2);
+    expect(pool.getIdleCount()).toBe(0);
+    expect(consoleError).toHaveBeenCalledWith(
+      expect.stringContaining("onWindowSetup cleanup threw"),
+      expect.any(Error),
+    );
+    consoleError.mockRestore();
+  });
+
+  it("threads through createWindowPool → <PooledWindow> → pool", async () => {
+    // The other tests in this block drive RendererWindowPool directly. This
+    // one exercises the full prop-threading path: createWindowPool stores the
+    // hook on WindowPoolDefinition, PooledWindow passes it to the pool
+    // constructor, the pool runs it during warmUp.
+    const onWindowSetup = vi.fn();
+    const pool = createWindowPool({}, { minIdle: 1, maxIdle: 1 }, { onWindowSetup });
+
+    function TestApp() {
+      const [open, setOpen] = useState(false);
+      return (
+        <MockWindowProvider>
+          <button onClick={() => setOpen(true)}>Open</button>
+          <PooledWindow pool={pool} open={open}>
+            <div data-testid="setup-content">Content</div>
+          </PooledWindow>
+        </MockWindowProvider>
+      );
+    }
+
+    render(<TestApp />);
+
+    // warmUp runs onWindowSetup once for the pre-warmed idle window — before
+    // any acquire.
+    await waitFor(() => {
+      expect(onWindowSetup).toHaveBeenCalledTimes(1);
+    });
+    const [calledWin, calledDoc] = onWindowSetup.mock.calls[0]!;
+    expect(calledWin).not.toBe(window);
+    expect(calledDoc).not.toBe(document);
+    expect((calledWin as { document: Document }).document).toBe(calledDoc);
+    expect((calledDoc as Document).getElementById("root")).not.toBeNull();
+
+    // Acquiring the pre-warmed window does NOT re-run setup.
+    fireEvent.click(document.querySelector("button")!);
+    await waitFor(() => {
+      expect(queryInPoolWindows('[data-testid="setup-content"]')).not.toBeNull();
+    });
+    expect(onWindowSetup).toHaveBeenCalledTimes(1);
+  });
 });
 
 // ─── <PooledWindow> ──────────────────────────────────────────────────────────
diff --git a/tests/setup.ts b/tests/setup.ts
index 8068d4e..6111a35 100644
--- a/tests/setup.ts
+++ b/tests/setup.ts
@@ -4,6 +4,15 @@ import "@testing-library/jest-dom/vitest";
 // Track mock windows for testing
 const mockWindows = new Map<string, MockWindow>();
 
+// LIMITATION: MockWindow is a plain object, not a real browsing context. It
+// has no realm globals — no `customElements`, no `HTMLElement` constructor, no
+// per-realm prototypes. The `Window & typeof globalThis` cast in
+// `initWindowDocument` (the type `onWindowSetup` callbacks receive) is sound
+// at runtime in Electron (a child window IS a global object) but not against
+// this mock. Tests can assert *that* `onWindowSetup` runs and what it
+// receives; they cannot exercise the realm-global use case (e.g.
+// `childWindow.customElements.define(...)`) without first adding those
+// globals to MockWindow.
 class MockWindow {
   innerWidth = 800;
   innerHeight = 600;

From 1b93f8a302e1d117c39c6265e95d714d9bc61ba1 Mon Sep 17 00:00:00 2001
From: Loc <loc@anthropic.com>
Date: Fri, 8 May 2026 12:00:37 -0700
Subject: [PATCH 2/2] ci: explicitly run electron's install script after
 version swap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

yarn 1 sometimes skips the electron postinstall when `yarn add` swaps
the version over an existing install — `node_modules/electron/dist/`
ends up empty and the chrome-sandbox fix step fails with "No such file
or directory". Run `node node_modules/electron/install.js` explicitly
after the swap; it downloads the prebuilt binary if missing and is a
no-op if it's already there.

The `electron-versions (beta)` job is informational (continue-on-error)
so this isn't blocking, but the red X is noise.
---
 .github/workflows/ci.yml | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 31bdd44..821666a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -113,7 +113,14 @@ jobs:
           cache: "yarn"
       - run: yarn install --immutable
       - name: Install Electron ${{ matrix.electron }}
-        run: yarn add -D electron@${{ matrix.electron }}
+        # yarn 1 sometimes skips electron's postinstall when `yarn add`
+        # swaps versions over an existing install — `dist/` ends up empty
+        # and every later step (chrome-sandbox fix, build, e2e) fails. The
+        # install script downloads the prebuilt binary if it's missing and
+        # is a no-op if it's already there.
+        run: |
+          yarn add -D electron@${{ matrix.electron }}
+          node node_modules/electron/install.js
       # Re-run after the electron install — `yarn add` reinstalls the binary
       # and resets permissions. Same Ubuntu 24.04 userns issue as the e2e job.
       - name: Fix chrome-sandbox