refactor(main): normalize runtime composer contracts

2026-02-27 18:22:41 -08:00 · 2026-02-21 02:21:04 -08:00
parent 5805d774ca
commit 69474c9642
18 changed files with 415 additions and 106 deletions
--- a/Normalize-runtime-composer-contracts.md
+++ b/Normalize-runtime-composer-contracts.md
@@ -0,0 +1,79 @@
+---
+id: TASK-97
+title: Normalize runtime composer contracts
+status: Done
+assignee:
+  - opencode
+created_date: '2026-02-21 07:15'
+updated_date: '2026-02-21 10:07'
+labels:
+  - architecture
+  - type-safety
+  - maintainability
+dependencies:
+  - TASK-94
+  - TASK-71
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Runtime composer interfaces currently allow optional/null drift. Standardize contracts via shared context types and stricter per-composer dependency interfaces.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Action Steps
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Inventory all composer entrypoints in `src/main/runtime/composers/` and classify current optional/nullable fields.
+2. Introduce shared `RuntimeContext` types in `src/main/runtime/` with explicit non-null guarantees where required.
+3. Narrow each composer input type to only required fields; remove permissive `any`/optional drift.
+4. Add compile-time contract tests (type assertions) and runtime seam tests for wiring regressions.
+5. Update composition root adapters in `src/main.ts` and domain registries to satisfy strict contracts.
+6. Run verification gate: `bun run build`, `bun run check:main-fanin`, `bun run test:core:dist`.
+7. Document contract rules in architecture/development docs.
+<!-- SECTION:PLAN:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Shared runtime context/types exist and are consumed by all composers.
+- [x] #2 Composer inputs reject missing required dependencies at compile time.
+- [x] #3 No behavior regression in runtime wiring tests.
+- [x] #4 Main fan-in guard remains within configured threshold.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add shared composer contract helpers (`ComposerInputs`, `ComposerOutputs`, `BuiltMainDeps`) in `src/main/runtime/composers/contracts.ts` and consume them across all runtime composers.
+2. Tighten high-risk composer boundaries (`mpv-runtime-composer.ts`, `jellyfin-remote-composer.ts`, `ipc-runtime-composer.ts`) and align `src/main.ts` callsites with normalized contract types.
+3. Add compile-time contract checks in `src/main/runtime/composers/composer-contracts.type-test.ts` for required composer deps.
+4. Update composer contract conventions in docs (`docs/architecture.md`, `docs/development.md`) and validate gates (`bun run build`, `bun run check:main-fanin`, `bun run test:core:dist`).
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+2026-02-21: started execution pass in current session; loaded task context and scanning composer contracts/tests before writing implementation plan.
+
+Implemented shared runtime composer contract module and rewired all composer option/result types to use shared contract helpers.
+
+Normalized MPV/Jellyfin/IPC composer boundaries, removed composer-level cast escape hatches where possible, and aligned `src/main.ts` runtime composer callsites to compile against stricter contracts.
+
+Added compile-only type contract coverage in `src/main/runtime/composers/composer-contracts.type-test.ts` to assert required dependency keys fail when omitted.
+
+Verification: `bun run build` PASS; focused composer tests PASS (`dist/main/runtime/composers/{mpv,jellyfin,ipc}-runtime-composer.test.js`); `bun run check:main-fanin` PASS (86 import lines, 10 runtime paths); `bun run test:core:dist` PASS (204 pass, 10 skipped).
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Normalized runtime composer contracts by introducing shared contract helpers (`ComposerInputs`, `ComposerOutputs`, `BuiltMainDeps`) and applying them across all composer modules. Tightened MPV/Jellyfin/IPC composer interfaces and main callsites to enforce required dependency surfaces at compile time, added compile-only contract assertions, updated architecture/development conventions, and revalidated build/fan-in/core-runtime test gates with no behavior regressions.
+<!-- SECTION:FINAL_SUMMARY:END -->
+
+## Definition of Done
+<!-- DOD:BEGIN -->
+- [x] #1 Type-level contract tests added for composer boundaries.
+- [x] #2 `bun run build`, `bun run check:main-fanin`, and `bun run test:core:dist` pass.
+- [x] #3 Docs updated with composer contract conventions.
+<!-- DOD:END -->
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -170,6 +170,12 @@ The composition root (`src/main.ts`) delegates to focused modules in `src/main/`
 - `runtime/composers/anilist-tracking-composer.ts` — AniList media tracking/probe/retry wiring
 - `runtime/composers/mpv-runtime-composer.ts` — MPV event/factory/tokenizer/warmup wiring

+Composer modules share contract conventions via `src/main/runtime/composers/contracts.ts`:
+
+- composer input surfaces are declared with `ComposerInputs<T>` so required dependencies cannot be omitted at compile time
+- composer outputs are declared with `ComposerOutputs<T>` to keep result contracts explicit and stable
+- builder return payload extraction should use shared type helpers instead of inline ad-hoc inference
+
 This keeps side effects explicit and makes behavior easy to unit-test with fakes.

 ## Program Lifecycle
--- a/docs/subagents/agents/opencode-task97-runtime-composer-20260221T094150Z-r8k3.md
+++ b/docs/subagents/agents/opencode-task97-runtime-composer-20260221T094150Z-r8k3.md
@@ -0,0 +1,65 @@
+# Agent Session: opencode-task97-runtime-composer-20260221T094150Z-r8k3
+
+- alias: `opencode-task97-runtime-composer`
+- mission: `Execute TASK-97 normalize runtime composer contracts end-to-end without commit`
+- status: `done`
+- started_utc: `2026-02-21T09:42:20Z`
+- backlog_task: `TASK-97`
+
+## Intent
+
+- Load TASK-97 context from Backlog MCP.
+- Build execution plan via `writing-plans` skill.
+- Execute with `executing-plans` skill.
+- Use parallel subagents for independent slices.
+
+## Planned Files
+
+- `src/main/runtime/composers/*`
+- `src/main/runtime/*`
+- `src/main.ts`
+- `src/**/*.test.ts`
+- `docs/**/*.md`
+
+## Assumptions
+
+- Existing TASK-94/TASK-71 composer extraction is baseline.
+- No commit requested.
+
+## Heartbeat Log
+
+- `2026-02-21T09:42:20Z` session start; context load + planning pending.
+- `2026-02-21T10:06:59Z` implementation complete; TASK-97 marked Done in Backlog MCP.
+
+## Files Touched
+
+- `src/main/runtime/composers/contracts.ts`
+- `src/main/runtime/composers/index.ts`
+- `src/main/runtime/composers/anilist-setup-composer.ts`
+- `src/main/runtime/composers/anilist-tracking-composer.ts`
+- `src/main/runtime/composers/app-ready-composer.ts`
+- `src/main/runtime/composers/ipc-runtime-composer.ts`
+- `src/main/runtime/composers/jellyfin-remote-composer.ts`
+- `src/main/runtime/composers/mpv-runtime-composer.ts`
+- `src/main/runtime/composers/shortcuts-runtime-composer.ts`
+- `src/main/runtime/composers/startup-lifecycle-composer.ts`
+- `src/main/runtime/composers/ipc-runtime-composer.test.ts`
+- `src/main/runtime/composers/mpv-runtime-composer.test.ts`
+- `src/main/runtime/composers/composer-contracts.type-test.ts`
+- `src/main/runtime/mpv-client-runtime-service.ts`
+- `src/main.ts`
+- `docs/architecture.md`
+- `docs/development.md`
+- `docs/plans/2026-02-21-task-97-normalize-runtime-composer-contracts.md`
+
+## Verification
+
+- `bun run build` pass
+- `bun run build && node --test dist/main/runtime/composers/mpv-runtime-composer.test.js dist/main/runtime/composers/jellyfin-remote-composer.test.js dist/main/runtime/composers/ipc-runtime-composer.test.js` pass
+- `bun run check:main-fanin` pass (`86 import lines`, `10 unique runtime paths`)
+- `bun run test:core:dist` pass (`204 pass`, `10 skipped`)
+
+## Handoff
+
+- no commit performed (per task request)
+- TASK-97 acceptance criteria + DoD checked and status set to Done in Backlog MCP
--- a/src/main.ts
+++ b/src/main.ts
@@ -225,6 +225,7 @@ import { createBindMpvMainEventHandlersHandler } from './main/runtime/domains/mp
 import { createBuildBindMpvMainEventHandlersMainDepsHandler } from './main/runtime/domains/mpv';
 import { createBuildMpvClientRuntimeServiceFactoryDepsHandler } from './main/runtime/domains/mpv';
 import { createMpvClientRuntimeServiceFactory } from './main/runtime/domains/mpv';
+import type { MpvClientRuntimeServiceOptions } from './main/runtime/domains/mpv';
 import { createUpdateMpvSubtitleRenderMetricsHandler } from './main/runtime/domains/mpv';
 import { createBuildUpdateMpvSubtitleRenderMetricsMainDepsHandler } from './main/runtime/domains/mpv';
 import {
@@ -2006,7 +2007,11 @@ const {
  createMecabTokenizerAndCheck,
  prewarmSubtitleDictionaries,
  startBackgroundWarmups,
-} = composeMpvRuntimeHandlers<ReturnType<typeof createTokenizerDepsRuntime>, SubtitleData>({
+} = composeMpvRuntimeHandlers<
+  MpvIpcClient,
+  ReturnType<typeof createTokenizerDepsRuntime>,
+  SubtitleData
+>({
  bindMpvMainEventHandlersMainDeps: {
    appState,
    getQuitOnDisconnectArmed: () => jellyfinPlayQuitOnDisconnectArmed,
@@ -2055,7 +2060,10 @@ const {
    },
  },
  mpvClientRuntimeServiceFactoryMainDeps: {
-    createClient: MpvIpcClient as unknown as new (socketPath: string, options: unknown) => unknown,
+    createClient: MpvIpcClient as unknown as new (
+      socketPath: string,
+      options: MpvClientRuntimeServiceOptions,
+    ) => MpvIpcClient,
    getSocketPath: () => appState.mpvSocketPath,
    getResolvedConfig: () => getResolvedConfig(),
    isAutoStartOverlayEnabled: () => appState.autoStartOverlay,
@@ -2500,10 +2508,7 @@ const {
  handleMpvCommandFromIpc: handleMpvCommandFromIpcHandler,
  runSubsyncManualFromIpc: runSubsyncManualFromIpcHandler,
  registerIpcRuntimeHandlers,
-} = composeIpcRuntimeHandlers<
-  SubsyncManualRunRequest,
-  Awaited<ReturnType<typeof subsyncRuntime.runManualFromIpc>>
->({
+} = composeIpcRuntimeHandlers({
  mpvCommandMainDeps: {
    triggerSubsyncFromConfig: () => triggerSubsyncFromConfig(),
    openRuntimeOptionsPalette: () => openRuntimeOptionsPalette(),
@@ -2525,7 +2530,8 @@ const {
    hasRuntimeOptionsManager: () => appState.runtimeOptionsManager !== null,
  },
  handleMpvCommandFromIpcRuntime,
-  runSubsyncManualFromIpc: (request) => subsyncRuntime.runManualFromIpc(request),
+  runSubsyncManualFromIpc: (request) =>
+    subsyncRuntime.runManualFromIpc(request as SubsyncManualRunRequest),
  registration: {
    runtimeOptions: {
      getRuntimeOptionsManager: () => appState.runtimeOptionsManager,
@@ -2867,7 +2873,7 @@ function handleMpvCommandFromIpc(command: (string | number)[]): void {
 }

 async function runSubsyncManualFromIpc(request: SubsyncManualRunRequest): Promise<SubsyncResult> {
-  return runSubsyncManualFromIpcHandler(request);
+  return runSubsyncManualFromIpcHandler(request) as Promise<SubsyncResult>;
 }

 function appendClipboardVideoToQueue(): { ok: boolean; message: string } {
--- a/src/main/runtime/composers/anilist-setup-composer.ts
+++ b/src/main/runtime/composers/anilist-setup-composer.ts
@@ -8,27 +8,28 @@ import {
  createNotifyAnilistSetupHandler,
  createRegisterSubminerProtocolClientHandler,
 } from '../domains/anilist';
+import type { ComposerInputs, ComposerOutputs } from './contracts';

 type NotifyHandler = ReturnType<typeof createNotifyAnilistSetupHandler>;
 type ConsumeHandler = ReturnType<typeof createConsumeAnilistSetupTokenFromUrlHandler>;
 type HandleProtocolHandler = ReturnType<typeof createHandleAnilistSetupProtocolUrlHandler>;
 type RegisterClientHandler = ReturnType<typeof createRegisterSubminerProtocolClientHandler>;

-export type AnilistSetupComposerOptions = {
+export type AnilistSetupComposerOptions = ComposerInputs<{
  notifyDeps: Parameters<typeof createBuildNotifyAnilistSetupMainDepsHandler>[0];
  consumeTokenDeps: Parameters<typeof createBuildConsumeAnilistSetupTokenFromUrlMainDepsHandler>[0];
  handleProtocolDeps: Parameters<typeof createBuildHandleAnilistSetupProtocolUrlMainDepsHandler>[0];
  registerProtocolClientDeps: Parameters<
    typeof createBuildRegisterSubminerProtocolClientMainDepsHandler
  >[0];
-};
+}>;

-export type AnilistSetupComposerResult = {
+export type AnilistSetupComposerResult = ComposerOutputs<{
  notifyAnilistSetup: NotifyHandler;
  consumeAnilistSetupTokenFromUrl: ConsumeHandler;
  handleAnilistSetupProtocolUrl: HandleProtocolHandler;
  registerSubminerProtocolClient: RegisterClientHandler;
-};
+}>;

 export function composeAnilistSetupHandlers(
  options: AnilistSetupComposerOptions,
--- a/src/main/runtime/composers/anilist-tracking-composer.ts
+++ b/src/main/runtime/composers/anilist-tracking-composer.ts
@@ -20,8 +20,9 @@ import {
  createResetAnilistMediaTrackingHandler,
  createSetAnilistMediaGuessRuntimeStateHandler,
 } from '../domains/anilist';
+import type { ComposerInputs, ComposerOutputs } from './contracts';

-export type AnilistTrackingComposerOptions = {
+export type AnilistTrackingComposerOptions = ComposerInputs<{
  refreshClientSecretMainDeps: Parameters<
    typeof createBuildRefreshAnilistClientSecretStateMainDepsHandler
  >[0];
@@ -50,9 +51,9 @@ export type AnilistTrackingComposerOptions = {
  maybeRunPostWatchUpdateMainDeps: Parameters<
    typeof createBuildMaybeRunAnilistPostWatchUpdateMainDepsHandler
  >[0];
-};
+}>;

-export type AnilistTrackingComposerResult = {
+export type AnilistTrackingComposerResult = ComposerOutputs<{
  refreshAnilistClientSecretState: ReturnType<typeof createRefreshAnilistClientSecretStateHandler>;
  getCurrentAnilistMediaKey: ReturnType<typeof createGetCurrentAnilistMediaKeyHandler>;
  resetAnilistMediaTracking: ReturnType<typeof createResetAnilistMediaTrackingHandler>;
@@ -67,7 +68,7 @@ export type AnilistTrackingComposerResult = {
  ensureAnilistMediaGuess: ReturnType<typeof createEnsureAnilistMediaGuessHandler>;
  processNextAnilistRetryUpdate: ReturnType<typeof createProcessNextAnilistRetryUpdateHandler>;
  maybeRunAnilistPostWatchUpdate: ReturnType<typeof createMaybeRunAnilistPostWatchUpdateHandler>;
-};
+}>;

 export function composeAnilistTrackingHandlers(
  options: AnilistTrackingComposerOptions,
--- a/src/main/runtime/composers/app-ready-composer.ts
+++ b/src/main/runtime/composers/app-ready-composer.ts
@@ -7,6 +7,7 @@ import {
 import { createCriticalConfigErrorHandler, createReloadConfigHandler } from '../startup-config';
 import { createBuildImmersionTrackerStartupMainDepsHandler } from '../immersion-startup-main-deps';
 import { createImmersionTrackerStartupHandler } from '../immersion-startup';
+import type { ComposerInputs, ComposerOutputs } from './contracts';

 type ReloadConfigMainDeps = Parameters<typeof createBuildReloadConfigMainDepsHandler>[0];
 type CriticalConfigErrorMainDeps = Parameters<
@@ -14,20 +15,20 @@ type CriticalConfigErrorMainDeps = Parameters<
 >[0];
 type AppReadyRuntimeMainDeps = Parameters<typeof createBuildAppReadyRuntimeMainDepsHandler>[0];

-export type AppReadyComposerOptions = {
+export type AppReadyComposerOptions = ComposerInputs<{
  reloadConfigMainDeps: ReloadConfigMainDeps;
  criticalConfigErrorMainDeps: CriticalConfigErrorMainDeps;
  appReadyRuntimeMainDeps: Omit<AppReadyRuntimeMainDeps, 'reloadConfig' | 'onCriticalConfigErrors'>;
  immersionTrackerStartupMainDeps: Parameters<
    typeof createBuildImmersionTrackerStartupMainDepsHandler
  >[0];
-};
+}>;

-export type AppReadyComposerResult = {
+export type AppReadyComposerResult = ComposerOutputs<{
  reloadConfig: ReturnType<typeof createReloadConfigHandler>;
  criticalConfigError: ReturnType<typeof createCriticalConfigErrorHandler>;
  appReadyRuntimeRunner: ReturnType<typeof createAppReadyRuntimeRunner>;
-};
+}>;

 export function composeAppReadyRuntime(options: AppReadyComposerOptions): AppReadyComposerResult {
  const reloadConfig = createReloadConfigHandler(
--- a/src/main/runtime/composers/composer-contracts.type-test.ts
+++ b/src/main/runtime/composers/composer-contracts.type-test.ts
@@ -0,0 +1,95 @@
+import type { ComposerInputs } from './contracts';
+import type { IpcRuntimeComposerOptions } from './ipc-runtime-composer';
+import type { JellyfinRemoteComposerOptions } from './jellyfin-remote-composer';
+import type { MpvRuntimeComposerOptions } from './mpv-runtime-composer';
+import type { AnilistSetupComposerOptions } from './anilist-setup-composer';
+
+type Assert<T extends true> = T;
+type IsAssignable<From, To> = [From] extends [To] ? true : false;
+
+type FakeMpvClient = {
+  on: (...args: unknown[]) => unknown;
+  connect: () => void;
+};
+
+type FakeTokenizerDeps = { isKnownWord: (text: string) => boolean };
+type FakeTokenizedSubtitle = { text: string };
+
+type RequiredAnilistSetupInputKeys = keyof ComposerInputs<AnilistSetupComposerOptions>;
+type RequiredJellyfinInputKeys = keyof ComposerInputs<JellyfinRemoteComposerOptions>;
+type RequiredIpcInputKeys = keyof ComposerInputs<IpcRuntimeComposerOptions>;
+type RequiredMpvInputKeys = keyof ComposerInputs<
+  MpvRuntimeComposerOptions<FakeMpvClient, FakeTokenizerDeps, FakeTokenizedSubtitle>
+>;
+
+type _anilistHasNotifyDeps = Assert<IsAssignable<'notifyDeps', RequiredAnilistSetupInputKeys>>;
+type _jellyfinHasGetMpvClient = Assert<IsAssignable<'getMpvClient', RequiredJellyfinInputKeys>>;
+type _ipcHasRegistration = Assert<IsAssignable<'registration', RequiredIpcInputKeys>>;
+type _mpvHasTokenizer = Assert<IsAssignable<'tokenizer', RequiredMpvInputKeys>>;
+
+// @ts-expect-error missing required notifyDeps should fail compile-time contract
+const anilistMissingRequired: AnilistSetupComposerOptions = {
+  consumeTokenDeps: {} as AnilistSetupComposerOptions['consumeTokenDeps'],
+  handleProtocolDeps: {} as AnilistSetupComposerOptions['handleProtocolDeps'],
+  registerProtocolClientDeps: {} as AnilistSetupComposerOptions['registerProtocolClientDeps'],
+};
+
+// @ts-expect-error missing required getMpvClient should fail compile-time contract
+const jellyfinMissingRequired: JellyfinRemoteComposerOptions = {
+  getConfiguredSession: {} as JellyfinRemoteComposerOptions['getConfiguredSession'],
+  getClientInfo: {} as JellyfinRemoteComposerOptions['getClientInfo'],
+  getJellyfinConfig: {} as JellyfinRemoteComposerOptions['getJellyfinConfig'],
+  playJellyfinItem: {} as JellyfinRemoteComposerOptions['playJellyfinItem'],
+  logWarn: {} as JellyfinRemoteComposerOptions['logWarn'],
+  sendMpvCommand: {} as JellyfinRemoteComposerOptions['sendMpvCommand'],
+  jellyfinTicksToSeconds: {} as JellyfinRemoteComposerOptions['jellyfinTicksToSeconds'],
+  getActivePlayback: {} as JellyfinRemoteComposerOptions['getActivePlayback'],
+  clearActivePlayback: {} as JellyfinRemoteComposerOptions['clearActivePlayback'],
+  getSession: {} as JellyfinRemoteComposerOptions['getSession'],
+  getNow: {} as JellyfinRemoteComposerOptions['getNow'],
+  getLastProgressAtMs: {} as JellyfinRemoteComposerOptions['getLastProgressAtMs'],
+  setLastProgressAtMs: {} as JellyfinRemoteComposerOptions['setLastProgressAtMs'],
+  progressIntervalMs: 3000,
+  ticksPerSecond: 10_000_000,
+  logDebug: {} as JellyfinRemoteComposerOptions['logDebug'],
+};
+
+// @ts-expect-error missing required registration should fail compile-time contract
+const ipcMissingRequired: IpcRuntimeComposerOptions = {
+  mpvCommandMainDeps: {} as IpcRuntimeComposerOptions['mpvCommandMainDeps'],
+  handleMpvCommandFromIpcRuntime: {} as IpcRuntimeComposerOptions['handleMpvCommandFromIpcRuntime'],
+  runSubsyncManualFromIpc: {} as IpcRuntimeComposerOptions['runSubsyncManualFromIpc'],
+};
+
+// @ts-expect-error missing required tokenizer should fail compile-time contract
+const mpvMissingRequired: MpvRuntimeComposerOptions<
+  FakeMpvClient,
+  FakeTokenizerDeps,
+  FakeTokenizedSubtitle
+> = {
+  bindMpvMainEventHandlersMainDeps: {} as MpvRuntimeComposerOptions<
+    FakeMpvClient,
+    FakeTokenizerDeps,
+    FakeTokenizedSubtitle
+  >['bindMpvMainEventHandlersMainDeps'],
+  mpvClientRuntimeServiceFactoryMainDeps: {} as MpvRuntimeComposerOptions<
+    FakeMpvClient,
+    FakeTokenizerDeps,
+    FakeTokenizedSubtitle
+  >['mpvClientRuntimeServiceFactoryMainDeps'],
+  updateMpvSubtitleRenderMetricsMainDeps: {} as MpvRuntimeComposerOptions<
+    FakeMpvClient,
+    FakeTokenizerDeps,
+    FakeTokenizedSubtitle
+  >['updateMpvSubtitleRenderMetricsMainDeps'],
+  warmups: {} as MpvRuntimeComposerOptions<
+    FakeMpvClient,
+    FakeTokenizerDeps,
+    FakeTokenizedSubtitle
+  >['warmups'],
+};
+
+void anilistMissingRequired;
+void jellyfinMissingRequired;
+void ipcMissingRequired;
+void mpvMissingRequired;
--- a/src/main/runtime/composers/contracts.ts
+++ b/src/main/runtime/composers/contracts.ts
@@ -0,0 +1,13 @@
+type ComposerShape = Record<string, unknown>;
+
+export type ComposerInputs<T extends ComposerShape> = Readonly<Required<T>>;
+
+export type ComposerOutputs<T extends ComposerShape> = Readonly<T>;
+
+export type BuiltMainDeps<TFactory> = TFactory extends (
+  ...args: infer _TFactoryArgs
+) => infer TBuilder
+  ? TBuilder extends (...args: infer _TBuilderArgs) => infer TDeps
+    ? TDeps
+    : never
+  : never;
--- a/src/main/runtime/composers/index.ts
+++ b/src/main/runtime/composers/index.ts
@@ -1,6 +1,7 @@
 export * from './anilist-setup-composer';
 export * from './anilist-tracking-composer';
 export * from './app-ready-composer';
+export * from './contracts';
 export * from './ipc-runtime-composer';
 export * from './jellyfin-remote-composer';
 export * from './mpv-runtime-composer';
--- a/src/main/runtime/composers/ipc-runtime-composer.test.ts
+++ b/src/main/runtime/composers/ipc-runtime-composer.test.ts
@@ -5,7 +5,7 @@ import { composeIpcRuntimeHandlers } from './ipc-runtime-composer';
 test('composeIpcRuntimeHandlers returns callable IPC handlers and registration bridge', async () => {
  let registered = false;

-  const composed = composeIpcRuntimeHandlers<{ value: number }, { ok: boolean; received: number }>({
+  const composed = composeIpcRuntimeHandlers({
    mpvCommandMainDeps: {
      triggerSubsyncFromConfig: async () => {},
      openRuntimeOptionsPalette: () => {},
@@ -18,7 +18,10 @@ test('composeIpcRuntimeHandlers returns callable IPC handlers and registration b
      hasRuntimeOptionsManager: () => true,
    },
    handleMpvCommandFromIpcRuntime: () => {},
-    runSubsyncManualFromIpc: async (request) => ({ ok: true, received: request.value }),
+    runSubsyncManualFromIpc: async (request) => ({
+      ok: true,
+      received: (request as { value: number }).value,
+    }),
    registration: {
      runtimeOptions: {
        getRuntimeOptionsManager: () => null,
@@ -89,7 +92,10 @@ test('composeIpcRuntimeHandlers returns callable IPC handlers and registration b
  assert.equal(typeof composed.runSubsyncManualFromIpc, 'function');
  assert.equal(typeof composed.registerIpcRuntimeHandlers, 'function');

-  const result = await composed.runSubsyncManualFromIpc({ value: 7 });
+  const result = (await composed.runSubsyncManualFromIpc({ value: 7 })) as {
+    ok: boolean;
+    received: number;
+  };
  assert.deepEqual(result, { ok: true, received: 7 });

  composed.registerIpcRuntimeHandlers();
--- a/src/main/runtime/composers/ipc-runtime-composer.ts
+++ b/src/main/runtime/composers/ipc-runtime-composer.ts
@@ -3,48 +3,43 @@ import {
  createBuildMpvCommandFromIpcRuntimeMainDepsHandler,
  createIpcRuntimeHandlers,
 } from '../domains/ipc';
+import type { ComposerInputs, ComposerOutputs } from './contracts';

 type MpvCommand = (string | number)[];

-type IpcMainDepsWithoutHandlers = Omit<
-  RegisterIpcRuntimeServicesParams['mainDeps'],
-  'handleMpvCommand' | 'runSubsyncManual'
->;
+type IpcMainDeps = RegisterIpcRuntimeServicesParams['mainDeps'];
+type IpcMainDepsWithoutHandlers = Omit<IpcMainDeps, 'handleMpvCommand' | 'runSubsyncManual'>;
+type RunSubsyncManual = IpcMainDeps['runSubsyncManual'];

-type IpcRuntimeDeps<TRequest, TResult> = Parameters<
-  typeof createIpcRuntimeHandlers<TRequest, TResult>
->[0];
+type IpcRuntimeDeps = Parameters<typeof createIpcRuntimeHandlers<unknown, unknown>>[0];

-export type IpcRuntimeComposerOptions<TRequest, TResult> = {
+export type IpcRuntimeComposerOptions = ComposerInputs<{
  mpvCommandMainDeps: Parameters<typeof createBuildMpvCommandFromIpcRuntimeMainDepsHandler>[0];
-  handleMpvCommandFromIpcRuntime: IpcRuntimeDeps<
-    TRequest,
-    TResult
-  >['handleMpvCommandFromIpcDeps']['handleMpvCommandFromIpcRuntime'];
-  runSubsyncManualFromIpc: (request: TRequest) => Promise<TResult>;
+  handleMpvCommandFromIpcRuntime: IpcRuntimeDeps['handleMpvCommandFromIpcDeps']['handleMpvCommandFromIpcRuntime'];
+  runSubsyncManualFromIpc: RunSubsyncManual;
  registration: {
    runtimeOptions: RegisterIpcRuntimeServicesParams['runtimeOptions'];
    mainDeps: IpcMainDepsWithoutHandlers;
    ankiJimakuDeps: RegisterIpcRuntimeServicesParams['ankiJimakuDeps'];
    registerIpcRuntimeServices: (params: RegisterIpcRuntimeServicesParams) => void;
  };
-};
+}>;

-export type IpcRuntimeComposerResult<TRequest, TResult> = {
+export type IpcRuntimeComposerResult = ComposerOutputs<{
  handleMpvCommandFromIpc: (command: MpvCommand) => void;
-  runSubsyncManualFromIpc: (request: TRequest) => Promise<TResult>;
+  runSubsyncManualFromIpc: RunSubsyncManual;
  registerIpcRuntimeHandlers: () => void;
-};
+}>;

-export function composeIpcRuntimeHandlers<TRequest, TResult>(
-  options: IpcRuntimeComposerOptions<TRequest, TResult>,
-): IpcRuntimeComposerResult<TRequest, TResult> {
+export function composeIpcRuntimeHandlers(
+  options: IpcRuntimeComposerOptions,
+): IpcRuntimeComposerResult {
  const mpvCommandFromIpcRuntimeMainDeps = createBuildMpvCommandFromIpcRuntimeMainDepsHandler(
    options.mpvCommandMainDeps,
  )();
  const { handleMpvCommandFromIpc, runSubsyncManualFromIpc } = createIpcRuntimeHandlers<
-    TRequest,
-    TResult
+    unknown,
+    unknown
  >({
    handleMpvCommandFromIpcDeps: {
      handleMpvCommandFromIpcRuntime: options.handleMpvCommandFromIpcRuntime,
@@ -61,7 +56,7 @@ export function composeIpcRuntimeHandlers<TRequest, TResult>(
      mainDeps: {
        ...options.registration.mainDeps,
        handleMpvCommand: (command) => handleMpvCommandFromIpc(command),
-        runSubsyncManual: (request) => runSubsyncManualFromIpc(request as TRequest),
+        runSubsyncManual: (request: unknown) => runSubsyncManualFromIpc(request),
      },
      ankiJimakuDeps: options.registration.ankiJimakuDeps,
    });
--- a/src/main/runtime/composers/jellyfin-remote-composer.ts
+++ b/src/main/runtime/composers/jellyfin-remote-composer.ts
@@ -10,26 +10,41 @@ import {
  createReportJellyfinRemoteProgressHandler,
  createReportJellyfinRemoteStoppedHandler,
 } from '../domains/jellyfin';
+import type { ComposerInputs, ComposerOutputs } from './contracts';

 type RemotePlayPayload = Parameters<ReturnType<typeof createHandleJellyfinRemotePlay>>[0];
 type RemotePlaystatePayload = Parameters<ReturnType<typeof createHandleJellyfinRemotePlaystate>>[0];
-type RemoteGeneralPayload = Parameters<ReturnType<typeof createHandleJellyfinRemoteGeneralCommand>>[0];
+type RemoteGeneralPayload = Parameters<
+  ReturnType<typeof createHandleJellyfinRemoteGeneralCommand>
+>[0];
+type JellyfinRemotePlayMainDeps = Parameters<
+  typeof createBuildHandleJellyfinRemotePlayMainDepsHandler
+>[0];
+type JellyfinRemotePlaystateMainDeps = Parameters<
+  typeof createBuildHandleJellyfinRemotePlaystateMainDepsHandler
+>[0];
+type JellyfinRemoteGeneralMainDeps = Parameters<
+  typeof createBuildHandleJellyfinRemoteGeneralCommandMainDepsHandler
+>[0];
+type JellyfinRemoteProgressMainDeps = Parameters<
+  typeof createBuildReportJellyfinRemoteProgressMainDepsHandler
+>[0];

-export type JellyfinRemoteComposerOptions = {
-  getConfiguredSession: Parameters<typeof createBuildHandleJellyfinRemotePlayMainDepsHandler>[0]['getConfiguredSession'];
-  getClientInfo: Parameters<typeof createBuildHandleJellyfinRemotePlayMainDepsHandler>[0]['getClientInfo'];
-  getJellyfinConfig: Parameters<typeof createBuildHandleJellyfinRemotePlayMainDepsHandler>[0]['getJellyfinConfig'];
-  playJellyfinItem: Parameters<typeof createBuildHandleJellyfinRemotePlayMainDepsHandler>[0]['playJellyfinItem'];
-  logWarn: Parameters<typeof createBuildHandleJellyfinRemotePlayMainDepsHandler>[0]['logWarn'];
-  getMpvClient: Parameters<typeof createBuildReportJellyfinRemoteProgressMainDepsHandler>[0]['getMpvClient'];
-  sendMpvCommand: Parameters<typeof createBuildHandleJellyfinRemotePlaystateMainDepsHandler>[0]['sendMpvCommand'];
+export type JellyfinRemoteComposerOptions = ComposerInputs<{
+  getConfiguredSession: JellyfinRemotePlayMainDeps['getConfiguredSession'];
+  getClientInfo: JellyfinRemotePlayMainDeps['getClientInfo'];
+  getJellyfinConfig: JellyfinRemotePlayMainDeps['getJellyfinConfig'];
+  playJellyfinItem: JellyfinRemotePlayMainDeps['playJellyfinItem'];
+  logWarn: JellyfinRemotePlayMainDeps['logWarn'];
+  getMpvClient: JellyfinRemoteProgressMainDeps['getMpvClient'];
+  sendMpvCommand: JellyfinRemotePlaystateMainDeps['sendMpvCommand'];
  jellyfinTicksToSeconds: Parameters<
    typeof createBuildHandleJellyfinRemotePlaystateMainDepsHandler
  >[0]['jellyfinTicksToSeconds'];
-  getActivePlayback: Parameters<typeof createBuildHandleJellyfinRemoteGeneralCommandMainDepsHandler>[0]['getActivePlayback'];
-  clearActivePlayback: Parameters<typeof createBuildReportJellyfinRemoteProgressMainDepsHandler>[0]['clearActivePlayback'];
-  getSession: Parameters<typeof createBuildReportJellyfinRemoteProgressMainDepsHandler>[0]['getSession'];
-  getNow: Parameters<typeof createBuildReportJellyfinRemoteProgressMainDepsHandler>[0]['getNow'];
+  getActivePlayback: JellyfinRemoteGeneralMainDeps['getActivePlayback'];
+  clearActivePlayback: JellyfinRemoteProgressMainDeps['clearActivePlayback'];
+  getSession: JellyfinRemoteProgressMainDeps['getSession'];
+  getNow: JellyfinRemoteProgressMainDeps['getNow'];
  getLastProgressAtMs: Parameters<
    typeof createBuildReportJellyfinRemoteProgressMainDepsHandler
  >[0]['getLastProgressAtMs'];
@@ -38,16 +53,18 @@ export type JellyfinRemoteComposerOptions = {
  >[0]['setLastProgressAtMs'];
  progressIntervalMs: number;
  ticksPerSecond: number;
-  logDebug: Parameters<typeof createBuildReportJellyfinRemoteProgressMainDepsHandler>[0]['logDebug'];
-};
+  logDebug: Parameters<
+    typeof createBuildReportJellyfinRemoteProgressMainDepsHandler
+  >[0]['logDebug'];
+}>;

-export type JellyfinRemoteComposerResult = {
+export type JellyfinRemoteComposerResult = ComposerOutputs<{
  reportJellyfinRemoteProgress: ReturnType<typeof createReportJellyfinRemoteProgressHandler>;
  reportJellyfinRemoteStopped: ReturnType<typeof createReportJellyfinRemoteStoppedHandler>;
  handleJellyfinRemotePlay: (payload: RemotePlayPayload) => Promise<void>;
  handleJellyfinRemotePlaystate: (payload: RemotePlaystatePayload) => Promise<void>;
  handleJellyfinRemoteGeneralCommand: (payload: RemoteGeneralPayload) => Promise<void>;
-};
+}>;

 export function composeJellyfinRemoteHandlers(
  options: JellyfinRemoteComposerOptions,
@@ -89,9 +106,7 @@ export function composeJellyfinRemoteHandlers(
    });
  const buildHandleJellyfinRemotePlaystateMainDepsHandler =
    createBuildHandleJellyfinRemotePlaystateMainDepsHandler({
-      getMpvClient: options.getMpvClient as Parameters<
-        typeof createBuildHandleJellyfinRemotePlaystateMainDepsHandler
-      >[0]['getMpvClient'],
+      getMpvClient: options.getMpvClient,
      sendMpvCommand: options.sendMpvCommand,
      reportJellyfinRemoteProgress: (force) => reportJellyfinRemoteProgress(force),
      reportJellyfinRemoteStopped: () => reportJellyfinRemoteStopped(),
@@ -99,9 +114,7 @@ export function composeJellyfinRemoteHandlers(
    });
  const buildHandleJellyfinRemoteGeneralCommandMainDepsHandler =
    createBuildHandleJellyfinRemoteGeneralCommandMainDepsHandler({
-      getMpvClient: options.getMpvClient as Parameters<
-        typeof createBuildHandleJellyfinRemoteGeneralCommandMainDepsHandler
-      >[0]['getMpvClient'],
+      getMpvClient: options.getMpvClient,
      sendMpvCommand: options.sendMpvCommand,
      getActivePlayback: options.getActivePlayback,
      reportJellyfinRemoteProgress: (force) => reportJellyfinRemoteProgress(force),
--- a/src/main/runtime/composers/mpv-runtime-composer.test.ts
+++ b/src/main/runtime/composers/mpv-runtime-composer.test.ts
@@ -48,6 +48,7 @@ test('composeMpvRuntimeHandlers returns callable handlers and forwards to inject
  }

  const composed = composeMpvRuntimeHandlers<
+    FakeMpvClient,
    { isKnownWord: (text: string) => boolean },
    { text: string }
  >({
@@ -189,7 +190,7 @@ test('composeMpvRuntimeHandlers returns callable handlers and forwards to inject
  assert.equal(typeof composed.launchBackgroundWarmupTask, 'function');
  assert.equal(typeof composed.startBackgroundWarmups, 'function');

-  const client = composed.createMpvClientRuntimeService() as FakeMpvClient;
+  const client = composed.createMpvClientRuntimeService();
  assert.equal(client.connected, true);

  composed.updateMpvSubtitleRenderMetrics({ subPos: 90 });
--- a/src/main/runtime/composers/mpv-runtime-composer.ts
+++ b/src/main/runtime/composers/mpv-runtime-composer.ts
@@ -2,6 +2,7 @@ import { createBindMpvMainEventHandlersHandler } from '../mpv-main-event-binding
 import { createBuildBindMpvMainEventHandlersMainDepsHandler } from '../mpv-main-event-main-deps';
 import { createBuildMpvClientRuntimeServiceFactoryDepsHandler } from '../mpv-client-runtime-service-main-deps';
 import { createMpvClientRuntimeServiceFactory } from '../mpv-client-runtime-service';
+import type { MpvClientRuntimeServiceOptions } from '../mpv-client-runtime-service';
 import { createBuildUpdateMpvSubtitleRenderMetricsMainDepsHandler } from '../mpv-subtitle-render-metrics-main-deps';
 import { createUpdateMpvSubtitleRenderMetricsHandler } from '../mpv-subtitle-render-metrics';
 import {
@@ -17,19 +18,29 @@ import {
  createLaunchBackgroundWarmupTaskHandler as createLaunchBackgroundWarmupTaskFromStartup,
  createStartBackgroundWarmupsHandler as createStartBackgroundWarmupsFromStartup,
 } from '../startup-warmups';
+import type { BuiltMainDeps, ComposerInputs, ComposerOutputs } from './contracts';

 type BindMpvMainEventHandlersMainDeps = Parameters<
  typeof createBuildBindMpvMainEventHandlersMainDepsHandler
 >[0];
-type MpvClientRuntimeServiceFactoryMainDeps = Omit<
-  Parameters<typeof createBuildMpvClientRuntimeServiceFactoryDepsHandler>[0],
+type BindMpvMainEventHandlers = ReturnType<typeof createBindMpvMainEventHandlersHandler>;
+type BoundMpvClient = Parameters<BindMpvMainEventHandlers>[0];
+type RuntimeMpvClient = BoundMpvClient & { connect: () => void };
+type MpvClientRuntimeServiceFactoryMainDeps<TMpvClient extends RuntimeMpvClient> = Omit<
+  Parameters<
+    typeof createBuildMpvClientRuntimeServiceFactoryDepsHandler<
+      TMpvClient,
+      unknown,
+      MpvClientRuntimeServiceOptions
+    >
+  >[0],
  'bindEventHandlers'
 >;
 type UpdateMpvSubtitleRenderMetricsMainDeps = Parameters<
  typeof createBuildUpdateMpvSubtitleRenderMetricsMainDepsHandler
 >[0];
 type BuildTokenizerDepsMainDeps = Parameters<typeof createBuildTokenizerDepsMainHandler>[0];
-type TokenizerMainDeps = ReturnType<ReturnType<typeof createBuildTokenizerDepsMainHandler>>;
+type TokenizerMainDeps = BuiltMainDeps<typeof createBuildTokenizerDepsMainHandler>;
 type CreateMecabTokenizerAndCheckMainDeps = Parameters<
  typeof createCreateMecabTokenizerAndCheckMainHandler
 >[0];
@@ -44,9 +55,13 @@ type StartBackgroundWarmupsMainDeps = Omit<
  'launchTask' | 'createMecabTokenizerAndCheck' | 'prewarmSubtitleDictionaries'
 >;

-export type MpvRuntimeComposerOptions<TTokenizerRuntimeDeps, TTokenizedSubtitle> = {
+export type MpvRuntimeComposerOptions<
+  TMpvClient extends RuntimeMpvClient,
+  TTokenizerRuntimeDeps,
+  TTokenizedSubtitle,
+> = ComposerInputs<{
  bindMpvMainEventHandlersMainDeps: BindMpvMainEventHandlersMainDeps;
-  mpvClientRuntimeServiceFactoryMainDeps: MpvClientRuntimeServiceFactoryMainDeps;
+  mpvClientRuntimeServiceFactoryMainDeps: MpvClientRuntimeServiceFactoryMainDeps<TMpvClient>;
  updateMpvSubtitleRenderMetricsMainDeps: UpdateMpvSubtitleRenderMetricsMainDeps;
  tokenizer: {
    buildTokenizerDepsMainDeps: BuildTokenizerDepsMainDeps;
@@ -59,22 +74,29 @@ export type MpvRuntimeComposerOptions<TTokenizerRuntimeDeps, TTokenizedSubtitle>
    launchBackgroundWarmupTaskMainDeps: LaunchBackgroundWarmupTaskMainDeps;
    startBackgroundWarmupsMainDeps: StartBackgroundWarmupsMainDeps;
  };
-};
+}>;

-export type MpvRuntimeComposerResult<TTokenizedSubtitle> = {
-  bindMpvClientEventHandlers: ReturnType<typeof createBindMpvMainEventHandlersHandler>;
-  createMpvClientRuntimeService: () => unknown;
+export type MpvRuntimeComposerResult<
+  TMpvClient extends RuntimeMpvClient,
+  TTokenizedSubtitle,
+> = ComposerOutputs<{
+  bindMpvClientEventHandlers: BindMpvMainEventHandlers;
+  createMpvClientRuntimeService: () => TMpvClient;
  updateMpvSubtitleRenderMetrics: ReturnType<typeof createUpdateMpvSubtitleRenderMetricsHandler>;
  tokenizeSubtitle: (text: string) => Promise<TTokenizedSubtitle>;
  createMecabTokenizerAndCheck: () => Promise<void>;
  prewarmSubtitleDictionaries: () => Promise<void>;
  launchBackgroundWarmupTask: ReturnType<typeof createLaunchBackgroundWarmupTaskFromStartup>;
  startBackgroundWarmups: ReturnType<typeof createStartBackgroundWarmupsFromStartup>;
-};
+}>;

-export function composeMpvRuntimeHandlers<TTokenizerRuntimeDeps, TTokenizedSubtitle>(
-  options: MpvRuntimeComposerOptions<TTokenizerRuntimeDeps, TTokenizedSubtitle>,
-): MpvRuntimeComposerResult<TTokenizedSubtitle> {
+export function composeMpvRuntimeHandlers<
+  TMpvClient extends RuntimeMpvClient,
+  TTokenizerRuntimeDeps,
+  TTokenizedSubtitle,
+>(
+  options: MpvRuntimeComposerOptions<TMpvClient, TTokenizerRuntimeDeps, TTokenizedSubtitle>,
+): MpvRuntimeComposerResult<TMpvClient, TTokenizedSubtitle> {
  const bindMpvMainEventHandlersMainDeps = createBuildBindMpvMainEventHandlersMainDepsHandler(
    options.bindMpvMainEventHandlersMainDeps,
  )();
@@ -83,14 +105,16 @@ export function composeMpvRuntimeHandlers<TTokenizerRuntimeDeps, TTokenizedSubti
  );

  const buildMpvClientRuntimeServiceFactoryMainDepsHandler =
-    createBuildMpvClientRuntimeServiceFactoryDepsHandler({
+    createBuildMpvClientRuntimeServiceFactoryDepsHandler<
+      TMpvClient,
+      unknown,
+      MpvClientRuntimeServiceOptions
+    >({
      ...options.mpvClientRuntimeServiceFactoryMainDeps,
-      bindEventHandlers: (client) => bindMpvClientEventHandlers(client as never),
+      bindEventHandlers: (client) => bindMpvClientEventHandlers(client),
    });
-  const createMpvClientRuntimeService = (): unknown =>
-    createMpvClientRuntimeServiceFactory(
-      buildMpvClientRuntimeServiceFactoryMainDepsHandler() as never,
-    )();
+  const createMpvClientRuntimeService = (): TMpvClient =>
+    createMpvClientRuntimeServiceFactory(buildMpvClientRuntimeServiceFactoryMainDepsHandler())();

  const updateMpvSubtitleRenderMetrics = createUpdateMpvSubtitleRenderMetricsHandler(
    createBuildUpdateMpvSubtitleRenderMetricsMainDepsHandler(
--- a/src/main/runtime/composers/shortcuts-runtime-composer.ts
+++ b/src/main/runtime/composers/shortcuts-runtime-composer.ts
@@ -5,6 +5,7 @@ import {
  createNumericShortcutSessionRuntimeHandlers,
  createOverlayShortcutsRuntimeHandlers,
 } from '../domains/shortcuts';
+import type { ComposerInputs, ComposerOutputs } from './contracts';

 type GlobalShortcutsOptions = Parameters<typeof createGlobalShortcutsRuntimeHandlers>[0];
 type NumericShortcutRuntimeMainDeps = Parameters<
@@ -18,18 +19,18 @@ type OverlayShortcutsMainDeps = Parameters<
  typeof createOverlayShortcutsRuntimeHandlers
 >[0]['overlayShortcutsRuntimeMainDeps'];

-export type ShortcutsRuntimeComposerOptions = {
+export type ShortcutsRuntimeComposerOptions = ComposerInputs<{
  globalShortcuts: GlobalShortcutsOptions;
  numericShortcutRuntimeMainDeps: NumericShortcutRuntimeMainDeps;
  numericSessions: NumericSessionOptions;
  overlayShortcutsRuntimeMainDeps: OverlayShortcutsMainDeps;
-};
+}>;

-export type ShortcutsRuntimeComposerResult = ReturnType<
-  typeof createGlobalShortcutsRuntimeHandlers
-> &
+export type ShortcutsRuntimeComposerResult = ComposerOutputs<
+  ReturnType<typeof createGlobalShortcutsRuntimeHandlers> &
    ReturnType<typeof createNumericShortcutSessionRuntimeHandlers> &
-  ReturnType<typeof createOverlayShortcutsRuntimeHandlers>;
+    ReturnType<typeof createOverlayShortcutsRuntimeHandlers>
+>;

 export function composeShortcutRuntimes(
  options: ShortcutsRuntimeComposerOptions,
--- a/src/main/runtime/composers/startup-lifecycle-composer.ts
+++ b/src/main/runtime/composers/startup-lifecycle-composer.ts
@@ -10,6 +10,7 @@ import {
 } from '../app-lifecycle-main-activate';
 import { createBuildRegisterProtocolUrlHandlersMainDepsHandler } from '../protocol-url-handlers-main-deps';
 import { registerProtocolUrlHandlers } from '../protocol-url-handlers';
+import type { ComposerInputs, ComposerOutputs } from './contracts';

 type RegisterProtocolUrlHandlersMainDeps = Parameters<
  typeof createBuildRegisterProtocolUrlHandlersMainDepsHandler
@@ -22,19 +23,19 @@ type RestoreWindowsOnActivateMainDeps = Parameters<
  typeof createBuildRestoreWindowsOnActivateMainDepsHandler
 >[0];

-export type StartupLifecycleComposerOptions = {
+export type StartupLifecycleComposerOptions = ComposerInputs<{
  registerProtocolUrlHandlersMainDeps: RegisterProtocolUrlHandlersMainDeps;
  onWillQuitCleanupMainDeps: OnWillQuitCleanupDeps;
  shouldRestoreWindowsOnActivateMainDeps: ShouldRestoreWindowsOnActivateMainDeps;
  restoreWindowsOnActivateMainDeps: RestoreWindowsOnActivateMainDeps;
-};
+}>;

-export type StartupLifecycleComposerResult = {
+export type StartupLifecycleComposerResult = ComposerOutputs<{
  registerProtocolUrlHandlers: () => void;
  onWillQuitCleanup: () => void;
  shouldRestoreWindowsOnActivate: () => boolean;
  restoreWindowsOnActivate: () => void;
-};
+}>;

 export function composeStartupLifecycleHandlers(
  options: StartupLifecycleComposerOptions,
--- a/src/main/runtime/mpv-client-runtime-service.ts
+++ b/src/main/runtime/mpv-client-runtime-service.ts
@@ -1,4 +1,4 @@
-type MpvClientCtorBaseOptions = {
+export type MpvClientRuntimeServiceOptions = {
  getResolvedConfig: () => unknown;
  autoStartOverlay: boolean;
  setOverlayVisible: (visible: boolean) => void;
@@ -12,14 +12,14 @@ type MpvClientLike = {
  connect: () => void;
 };

-type MpvClientCtor<TClient extends MpvClientLike, TOptions extends MpvClientCtorBaseOptions> = new (
-  socketPath: string,
-  options: TOptions,
-) => TClient;
+type MpvClientCtor<
+  TClient extends MpvClientLike,
+  TOptions extends MpvClientRuntimeServiceOptions,
+> = new (socketPath: string, options: TOptions) => TClient;

 export function createMpvClientRuntimeServiceFactory<
  TClient extends MpvClientLike,
-  TOptions extends MpvClientCtorBaseOptions,
+  TOptions extends MpvClientRuntimeServiceOptions,
 >(deps: {
  createClient: MpvClientCtor<TClient, TOptions>;
  socketPath: string;