IdeaSDK/docs/windows.md

Windows

Plugin windows are detached OS windows that host an existing contributes.layouts layout. There is no separate window contribution type.

await ctx.services?.windows.open({
  layoutType: "hello-plugin.dashboard",
  state: { openedFrom: "menu" }
});

windows.open is the public API for commands that need to make feedback visible to a human. A command handler may still return structured data, but menu clicks do not currently guarantee that return value is displayed.

Contract

• layoutType must match a layout type declared by the calling plugin.
• The plugin must declare capabilities: ["ui"] when it relies on plugin layouts/windows as a human-facing surface. Add "tooling" only when the plugin also uses tooling/workspace/task services.
• There is no contributes.windows manifest key. Windows always host an existing contributes.layouts layout.
• The host validates the plugin is runtime-active and the layout exists before opening or focusing the window.
• The calling plugin package must still be installed, enabled globally and enabled for the focused project. A stale command from a replaced runtime is rejected instead of opening a window under another plugin's identity.
• windows.open(...) rejects its promise when any validation or native-window operation fails. Let that rejection reach the command handler (or catch it, log it and return explicit failed feedback); the IdeA menu host logs the rejection and shows a retryable error to the user.
• Reopening the same plugin/layout pair focuses the existing window.
• state is JSON-serializable initial window state. The mounted component can later call setState(next) to update its local host state.
• The window follows IdeA's focused project, matching detached native panel behavior. If no project is focused, the host shows a neutral shell until one is focused.

Return Value

const win = await ctx.services.windows.open({ layoutType: "hello-plugin.dashboard" });

win.label;
win.alreadyOpen;
win.surface.layoutType;

The returned label is a host-owned window identity. Treat it as opaque.

Typical Menu Flow

ctx.commands?.registerCommand("hello-plugin.open-dashboard", async () => {
  if (!ctx.services) {
    return { status: "skipped", reason: "ui-service-unavailable", message: "UI service unavailable." };
  }
  const win = await ctx.services.windows.open({
    layoutType: "hello-plugin.dashboard",
    state: { source: "menu" }
  });

  return { status: "opened", message: "Opened dashboard.", alreadyOpen: win.alreadyOpen };
});