# Create Window

When you instantiate a new `Window`, Positron orchestrates a sequence of internal state changes, queuing mechanisms, and direct commands to the native rendering binary.

### Instantiation Flow

1. **Memory Allocation & ID Assignment**: The window receives a unique, auto-incrementing ID.
2. **Socket Handshake Checking**: The instance checks if the background native render process is connected.
   * If **connected** (`WebSocket.OPEN`), the window prepares to signal it is `ready`.
   * If **disconnected/connecting**, the instance adds itself to a `pendingWindows` tracking set and caches subsequent layout commands into an outbound array queue.
3. **Native Window Construction**: Unless explicitly told to bypass automatic creation via `skipCreate: true`, the class automatically invokes its internal `create()` method.

### Instantiation Parameters

```javascript
const win = new Window(options);
```

#### `options` Object Properties

| Property        | Type               | Default     | Description                                                                                                                                         |
| --------------- | ------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width`         | `Number \| String` | `800`       | The fallback target structural width of the window frame.                                                                                           |
| `height`        | `Number \| String` | `600`       | The fallback target structural height of the window frame.                                                                                          |
| `skipCreate`    | `Boolean`          | `false`     | If `true`, halts automatic execution of the native window creation command during class instantiation. You must call `win.create()` manually later. |
| `darwinOptions` | `Object`           | *See below* | Platform-specific UI tailoring rules applied directly to macOS instances.                                                                           |

### macOS Options

The `darwinOptions` object specifically dictates the behavioral traits and structural presentation of windows running on macOS environments.

#### Supported Properties & Defaults

If you omit `darwinOptions` or partial keys, Positron automatically hydrates the configuration object with these hardcoded defaults:

```javascript
darwinOptions: {
  closable: true,
  resizable: true,
  minimizable: true,
  titlebarTransparent: false,
  titlebarVisible: true
}
```

* `closable` *(Boolean)*: Enables or disables the native red close window button.
* `resizable` *(Boolean)*: Dictates whether the user can manually drag corners or maximize the window frame.
* `minimizable` *(Boolean)*: Enables or disables the native yellow minimize window button.
* `titlebarTransparent` *(Boolean)*: When set to `true`, blends the titlebar area seamlessly into your application view layer (often used for frameless/custom UI layouts).
* `titlebarVisible` *(Boolean)*: Dictates whether the macOS native title header strip is visibly rendered at the top of the window application viewport.

<details>

<summary>Underlying Execution Mechanics</summary>

When `create()` evaluates your configuration, it flattens your parameters and serializes them into a single positional array sent over IPC via the `createWindow` command.

Because the native binary expects consistent, stringified arguments, the framework transforms the settings. For example, your configuration:

```javascript
const win = new Window({
  width: 1024,
  height: 768,
  darwinOptions: {
    closable: true,
    resizable: true,
    minimizable: false,
    titlebarTransparent: true,
    titlebarVisible: false
  }
});
```

Will internally flatten out the `darwinOptions` properties via `Object.values(darwinOptions).map(String)` and execute:

```javascript
this.sendCommand("createWindow", ["1024", "768", "true", "true", "false", "true", "false"]);
```

</details>

### Multi-Creation Prevention

The `create()` method utilizes a private class field (`#created`) acting as a state guard. If you accidentally attempt to trigger `win.create()` on a window that is already visible or spawned, the engine drops a console warning (`Window X is already created.`) and exits out of the process cleanly to prevent duplicate native rendering frames.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://positronjs.gitbook.io/v1/commands/create-window.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.