From fc68d2c3a245f62c400f461d4b174c2edf47ff62 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 03:30:45 -0700
Subject: [PATCH] refactor(preload): name bridge modules for what they expose

The split named these -part-N, which says nothing. Renames each for the group of
bridge methods it actually exposes and folds the single-method window-reveal
module into the window-controls module it belongs with.

Verified by walking the composed contextBridge surface before and after: 1060
keys, identical nesting and value types, zero delta. The bridge modules carry no
satisfies annotation, so a dropped key here is a runtime error in the renderer
rather than a typecheck failure.
---
 src/main/ipc/github-ipc-channel-parity.test.ts |  4 ++--
 ...bridge-guest-registration-and-downloads.ts} |  2 +-
 ...er-bridge-page-interaction-and-sessions.ts} |  2 +-
 src/preload/api/browser-bridge.ts              |  9 ++++++---
 ....ts => gh-bridge-mutations-and-projects.ts} |  2 +-
 ... gh-bridge-pull-requests-and-work-items.ts} |  2 +-
 src/preload/api/gh-bridge.ts                   |  6 +++---
 ...part-1.ts => pty-bridge-session-control.ts} |  2 +-
 ... => pty-bridge-stream-and-serialization.ts} |  2 +-
 src/preload/api/pty-bridge.ts                  |  6 +++---
 ...ui-bridge-clipboard-and-window-controls.ts} |  5 ++++-
 src/preload/api/ui-bridge-part-5.ts            |  7 -------
 ...ts => ui-bridge-state-and-menu-commands.ts} |  2 +-
 ...s => ui-bridge-tab-and-browser-commands.ts} |  2 +-
 ... => ui-bridge-terminal-and-session-tabs.ts} |  2 +-
 src/preload/api/ui-bridge.ts                   | 18 ++++++++----------
 16 files changed, 35 insertions(+), 38 deletions(-)
 rename src/preload/api/{browser-bridge-part-1.ts => browser-bridge-guest-registration-and-downloads.ts} (99%)
 rename src/preload/api/{browser-bridge-part-2.ts => browser-bridge-page-interaction-and-sessions.ts} (99%)
 rename src/preload/api/{gh-bridge-part-2.ts => gh-bridge-mutations-and-projects.ts} (99%)
 rename src/preload/api/{gh-bridge-part-1.ts => gh-bridge-pull-requests-and-work-items.ts} (99%)
 rename src/preload/api/{pty-bridge-part-1.ts => pty-bridge-session-control.ts} (99%)
 rename src/preload/api/{pty-bridge-part-2.ts => pty-bridge-stream-and-serialization.ts} (99%)
 rename src/preload/api/{ui-bridge-part-4.ts => ui-bridge-clipboard-and-window-controls.ts} (98%)
 delete mode 100644 src/preload/api/ui-bridge-part-5.ts
 rename src/preload/api/{ui-bridge-part-1.ts => ui-bridge-state-and-menu-commands.ts} (99%)
 rename src/preload/api/{ui-bridge-part-2.ts => ui-bridge-tab-and-browser-commands.ts} (99%)
 rename src/preload/api/{ui-bridge-part-3.ts => ui-bridge-terminal-and-session-tabs.ts} (99%)

diff --git a/src/main/ipc/github-ipc-channel-parity.test.ts b/src/main/ipc/github-ipc-channel-parity.test.ts
index 73fc291f4ca..22a8b4c4178 100644
--- a/src/main/ipc/github-ipc-channel-parity.test.ts
+++ b/src/main/ipc/github-ipc-channel-parity.test.ts
@@ -88,8 +88,8 @@ describe('GitHub IPC channel parity', () => {
     // The preload facade now composes the two GitHub bridge owners; inspect
     // both owners so the channel census remains tied to the actual invokes.
     const preloadSource = [
-      '../../preload/api/gh-bridge-part-1.ts',
-      '../../preload/api/gh-bridge-part-2.ts'
+      '../../preload/api/gh-bridge-pull-requests-and-work-items.ts',
+      '../../preload/api/gh-bridge-mutations-and-projects.ts'
     ]
       .map((relativePath) => readFileSync(new URL(relativePath, import.meta.url), 'utf8'))
       .join('\n')
diff --git a/src/preload/api/browser-bridge-part-1.ts b/src/preload/api/browser-bridge-guest-registration-and-downloads.ts
similarity index 99%
rename from src/preload/api/browser-bridge-part-1.ts
rename to src/preload/api/browser-bridge-guest-registration-and-downloads.ts
index 47883976338..3714a3bca7c 100644
--- a/src/preload/api/browser-bridge-part-1.ts
+++ b/src/preload/api/browser-bridge-guest-registration-and-downloads.ts
@@ -7,7 +7,7 @@ import type {
 import { readBrowserClientHostIdArgument } from '../../shared/browser-client-host-id-argument'
 import { browserClientPageRendererRequests } from '../preload-runtime-support'
 
-export const browserApiPart1 = {
+export const browserGuestRegistrationAndDownloadsApi = {
   onClientPageRendererRequest: browserClientPageRendererRequests.subscribe,
   readClientHostId: (): string | null => readBrowserClientHostIdArgument(process.argv),
   registerGuest: (args: {
diff --git a/src/preload/api/browser-bridge-part-2.ts b/src/preload/api/browser-bridge-page-interaction-and-sessions.ts
similarity index 99%
rename from src/preload/api/browser-bridge-part-2.ts
rename to src/preload/api/browser-bridge-page-interaction-and-sessions.ts
index 07788c59d2e..0e959e0af4f 100644
--- a/src/preload/api/browser-bridge-part-2.ts
+++ b/src/preload/api/browser-bridge-page-interaction-and-sessions.ts
@@ -1,6 +1,6 @@
 import { ipcRenderer } from 'electron'
 
-export const browserApiPart2 = {
+export const browserPageInteractionAndSessionsApi = {
   onContextMenuRequested: (
     callback: (event: {
       browserPageId: string
diff --git a/src/preload/api/browser-bridge.ts b/src/preload/api/browser-bridge.ts
index 9b72b1658d3..dca222c5843 100644
--- a/src/preload/api/browser-bridge.ts
+++ b/src/preload/api/browser-bridge.ts
@@ -1,4 +1,7 @@
-import { browserApiPart1 } from './browser-bridge-part-1'
-import { browserApiPart2 } from './browser-bridge-part-2'
+import { browserGuestRegistrationAndDownloadsApi } from './browser-bridge-guest-registration-and-downloads'
+import { browserPageInteractionAndSessionsApi } from './browser-bridge-page-interaction-and-sessions'
 
-export const browserApi = { ...browserApiPart1, ...browserApiPart2 }
+export const browserApi = {
+  ...browserGuestRegistrationAndDownloadsApi,
+  ...browserPageInteractionAndSessionsApi
+}
diff --git a/src/preload/api/gh-bridge-part-2.ts b/src/preload/api/gh-bridge-mutations-and-projects.ts
similarity index 99%
rename from src/preload/api/gh-bridge-part-2.ts
rename to src/preload/api/gh-bridge-mutations-and-projects.ts
index c7ebc51b57e..3103cb432ec 100644
--- a/src/preload/api/gh-bridge-part-2.ts
+++ b/src/preload/api/gh-bridge-mutations-and-projects.ts
@@ -36,7 +36,7 @@ import type {
 } from '../../shared/github/project-request-types'
 import type { AppStarSource } from '../../shared/gh-star-source'
 
-export const ghApiPart2 = {
+export const ghMutationsAndProjectsApi = {
   setPRAutoMerge: (args: {
     repoPath: string
     repoId?: string
diff --git a/src/preload/api/gh-bridge-part-1.ts b/src/preload/api/gh-bridge-pull-requests-and-work-items.ts
similarity index 99%
rename from src/preload/api/gh-bridge-part-1.ts
rename to src/preload/api/gh-bridge-pull-requests-and-work-items.ts
index 11ed8c32f79..a4f3e1d45ef 100644
--- a/src/preload/api/gh-bridge-part-1.ts
+++ b/src/preload/api/gh-bridge-pull-requests-and-work-items.ts
@@ -10,7 +10,7 @@ import type { GitHubWorkItem, ListWorkItemsResult } from '../../shared/github/wo
 import type { GitHubCreateIssueResult } from '../../shared/issue-mutation-types'
 import type { TaskSourceContext } from '../../shared/task-source-context'
 
-export const ghApiPart1 = {
+export const ghPullRequestsAndWorkItemsApi = {
   viewer: (): Promise<unknown> => ipcRenderer.invoke('gh:viewer'),
   repoSlug: (args: { repoPath: string; repoId?: string }): Promise<unknown> =>
     ipcRenderer.invoke('gh:repoSlug', args),
diff --git a/src/preload/api/gh-bridge.ts b/src/preload/api/gh-bridge.ts
index c4bef718721..52c21a966a7 100644
--- a/src/preload/api/gh-bridge.ts
+++ b/src/preload/api/gh-bridge.ts
@@ -1,4 +1,4 @@
-import { ghApiPart1 } from './gh-bridge-part-1'
-import { ghApiPart2 } from './gh-bridge-part-2'
+import { ghPullRequestsAndWorkItemsApi } from './gh-bridge-pull-requests-and-work-items'
+import { ghMutationsAndProjectsApi } from './gh-bridge-mutations-and-projects'
 
-export const ghApi = { ...ghApiPart1, ...ghApiPart2 }
+export const ghApi = { ...ghPullRequestsAndWorkItemsApi, ...ghMutationsAndProjectsApi }
diff --git a/src/preload/api/pty-bridge-part-1.ts b/src/preload/api/pty-bridge-session-control.ts
similarity index 99%
rename from src/preload/api/pty-bridge-part-1.ts
rename to src/preload/api/pty-bridge-session-control.ts
index 40da8dbfa52..7e761738256 100644
--- a/src/preload/api/pty-bridge-part-1.ts
+++ b/src/preload/api/pty-bridge-session-control.ts
@@ -16,7 +16,7 @@ import type { TerminalViewAttributes } from '../../shared/terminal-view-attribut
 import type { PtyMainDeliveryDiagnostics } from '../../shared/pty-delivery-diagnostics'
 import type { AgentKind, LaunchSource, RequestKind } from '../../shared/telemetry-events'
 
-export const ptyApiPart1 = {
+export const ptySessionControlApi = {
   spawn: (opts: {
     cols: number
     rows: number
diff --git a/src/preload/api/pty-bridge-part-2.ts b/src/preload/api/pty-bridge-stream-and-serialization.ts
similarity index 99%
rename from src/preload/api/pty-bridge-part-2.ts
rename to src/preload/api/pty-bridge-stream-and-serialization.ts
index 1686a621f97..8fc9c48bce1 100644
--- a/src/preload/api/pty-bridge-part-2.ts
+++ b/src/preload/api/pty-bridge-stream-and-serialization.ts
@@ -2,7 +2,7 @@ import { ipcRenderer } from 'electron'
 import type { PtyModelRestoreNeededEvent } from '../../shared/pty-model-restore-marker'
 import type { TerminalSideEffectBatch } from '../../shared/terminal-side-effect-facts'
 
-export const ptyApiPart2 = {
+export const ptyStreamAndSerializationApi = {
   inspectProcess: (
     id: string
   ): Promise<{
diff --git a/src/preload/api/pty-bridge.ts b/src/preload/api/pty-bridge.ts
index 314bd6f993f..df080692178 100644
--- a/src/preload/api/pty-bridge.ts
+++ b/src/preload/api/pty-bridge.ts
@@ -1,4 +1,4 @@
-import { ptyApiPart1 } from './pty-bridge-part-1'
-import { ptyApiPart2 } from './pty-bridge-part-2'
+import { ptySessionControlApi } from './pty-bridge-session-control'
+import { ptyStreamAndSerializationApi } from './pty-bridge-stream-and-serialization'
 
-export const ptyApi = { ...ptyApiPart1, ...ptyApiPart2 }
+export const ptyApi = { ...ptySessionControlApi, ...ptyStreamAndSerializationApi }
diff --git a/src/preload/api/ui-bridge-part-4.ts b/src/preload/api/ui-bridge-clipboard-and-window-controls.ts
similarity index 98%
rename from src/preload/api/ui-bridge-part-4.ts
rename to src/preload/api/ui-bridge-clipboard-and-window-controls.ts
index 2c5e2683931..867bd80026d 100644
--- a/src/preload/api/ui-bridge-part-4.ts
+++ b/src/preload/api/ui-bridge-clipboard-and-window-controls.ts
@@ -13,7 +13,7 @@ import type { NativeFileDropPayload } from '../../shared/native-file-drop'
 import type { ReadClipboardTextOptions } from '../../shared/clipboard-text'
 import { subscribeNativeFileDrop } from '../preload-runtime-support'
 
-export const uiApiPart4 = {
+export const uiClipboardAndWindowControlsApi = {
   onOpenDiffFromMobile: (
     callback: (data: {
       worktreeId: string
@@ -191,5 +191,8 @@ export const uiApiPart4 = {
   },
   confirmWindowClose: (): void => {
     ipcRenderer.send('window:confirm-close')
+  },
+  notifyWindowRevealed: (): void => {
+    ipcRenderer.send('ui:window-revealed')
   }
 }
diff --git a/src/preload/api/ui-bridge-part-5.ts b/src/preload/api/ui-bridge-part-5.ts
deleted file mode 100644
index 7c4c10eb1c6..00000000000
--- a/src/preload/api/ui-bridge-part-5.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-import { ipcRenderer } from 'electron'
-
-export const uiApiPart5 = {
-  notifyWindowRevealed: (): void => {
-    ipcRenderer.send('ui:window-revealed')
-  }
-}
diff --git a/src/preload/api/ui-bridge-part-1.ts b/src/preload/api/ui-bridge-state-and-menu-commands.ts
similarity index 99%
rename from src/preload/api/ui-bridge-part-1.ts
rename to src/preload/api/ui-bridge-state-and-menu-commands.ts
index b402b44b248..25476165cfb 100644
--- a/src/preload/api/ui-bridge-part-1.ts
+++ b/src/preload/api/ui-bridge-state-and-menu-commands.ts
@@ -2,7 +2,7 @@ import { ipcRenderer } from 'electron'
 import type { PersistedUIState } from '../../shared/persisted-ui-state-types'
 import type { KeybindingActionId } from '../../shared/keybindings'
 
-export const uiApiPart1 = {
+export const uiStateAndMenuCommandsApi = {
   get: () => ipcRenderer.invoke('ui:get'),
   set: (args) => ipcRenderer.invoke('ui:set', args),
   setWithAck: (args) => ipcRenderer.invoke('ui:set', args),
diff --git a/src/preload/api/ui-bridge-part-2.ts b/src/preload/api/ui-bridge-tab-and-browser-commands.ts
similarity index 99%
rename from src/preload/api/ui-bridge-part-2.ts
rename to src/preload/api/ui-bridge-tab-and-browser-commands.ts
index fdf8956622e..ccca9a24f5b 100644
--- a/src/preload/api/ui-bridge-part-2.ts
+++ b/src/preload/api/ui-bridge-tab-and-browser-commands.ts
@@ -7,7 +7,7 @@ import type {
 } from '../../shared/worktree/launch-types'
 import { browserFindSubscriptions } from '../preload-runtime-support'
 
-export const uiApiPart2 = {
+export const uiTabAndBrowserCommandsApi = {
   onRequestTabSetProfile: (
     callback: (data: {
       requestId: string
diff --git a/src/preload/api/ui-bridge-part-3.ts b/src/preload/api/ui-bridge-terminal-and-session-tabs.ts
similarity index 99%
rename from src/preload/api/ui-bridge-part-3.ts
rename to src/preload/api/ui-bridge-terminal-and-session-tabs.ts
index 44669b67838..9de47cceb0c 100644
--- a/src/preload/api/ui-bridge-part-3.ts
+++ b/src/preload/api/ui-bridge-terminal-and-session-tabs.ts
@@ -12,7 +12,7 @@ import type {
   RuntimeTerminalPresentation
 } from '../../shared/runtime-types'
 
-export const uiApiPart3 = {
+export const uiTerminalAndSessionTabsApi = {
   onCreateTerminal: (
     callback: (data: {
       requestId?: string
diff --git a/src/preload/api/ui-bridge.ts b/src/preload/api/ui-bridge.ts
index 97e199215c6..200d49ba1c1 100644
--- a/src/preload/api/ui-bridge.ts
+++ b/src/preload/api/ui-bridge.ts
@@ -1,14 +1,12 @@
 import type { PreloadApi } from '../api-types'
-import { uiApiPart1 } from './ui-bridge-part-1'
-import { uiApiPart2 } from './ui-bridge-part-2'
-import { uiApiPart3 } from './ui-bridge-part-3'
-import { uiApiPart4 } from './ui-bridge-part-4'
-import { uiApiPart5 } from './ui-bridge-part-5'
+import { uiStateAndMenuCommandsApi } from './ui-bridge-state-and-menu-commands'
+import { uiTabAndBrowserCommandsApi } from './ui-bridge-tab-and-browser-commands'
+import { uiTerminalAndSessionTabsApi } from './ui-bridge-terminal-and-session-tabs'
+import { uiClipboardAndWindowControlsApi } from './ui-bridge-clipboard-and-window-controls'
 
 export const uiApi = {
-  ...uiApiPart1,
-  ...uiApiPart2,
-  ...uiApiPart3,
-  ...uiApiPart4,
-  ...uiApiPart5
+  ...uiStateAndMenuCommandsApi,
+  ...uiTabAndBrowserCommandsApi,
+  ...uiTerminalAndSessionTabsApi,
+  ...uiClipboardAndWindowControlsApi
 } satisfies PreloadApi['ui']