# Windows

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

```ts
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

```ts
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

```ts
ctx.commands?.registerCommand("hello-plugin.open-dashboard", async () => {
  return ctx.services?.windows.open({
    layoutType: "hello-plugin.dashboard",
    state: { source: "menu" }
  });
});
```