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" }
});

Contract

• layoutType must match a layout type declared by the calling plugin.
• The host validates the plugin is runtime-active and the layout exists before opening or focusing the window.
• 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 () => {
  return ctx.services?.windows.open({
    layoutType: "hello-plugin.dashboard",
    state: { source: "menu" }
  });
});