From a287b6cd1f9fc73aba8dac4e5678a89850dd9c27 Mon Sep 17 00:00:00 2001
From: Sasivarnan R <sasivarnan.ramu@gmail.com>
Date: Mon, 7 Sep 2026 21:46:14 +0530
Subject: [PATCH] docs(runtime): document initial window configuration

---
 runtime/desktop/configuration.md | 33 ++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/runtime/desktop/configuration.md b/runtime/desktop/configuration.md
index 8fa2c85bd..90476b8c9 100644
--- a/runtime/desktop/configuration.md
+++ b/runtime/desktop/configuration.md
@@ -1,7 +1,7 @@
 ---
-last_modified: 2026-06-30
+last_modified: 2026-09-07
 title: "Configuration"
-description: "Configure deno desktop in deno.json: app metadata, icons, deep-link URL schemes, backend selection, output paths, error reporting, and the auto-update server."
+description: "Configure deno desktop in deno.json: app metadata, initial window options, icons, deep-link URL schemes, backend selection, output paths, error reporting, and the auto-update server."
 ---
 
 :::info Available in Deno 2.9
@@ -209,6 +209,35 @@ result is not distributable without further signing. Set a real Developer ID
 identity to produce a notarizable bundle. See
 [Distribution](/runtime/desktop/distribution/#code-signing).
 
+## `initialWindow`
+
+Configure the implicit first window created before your application code runs.
+This is useful when its creation-time properties must differ from the defaults;
+the first `new Deno.BrowserWindow()` adopts this window rather than creating a
+new one.
+
+```jsonc title="deno.json"
+{
+  "desktop": {
+    "initialWindow": {
+      "width": 320,
+      "height": 220,
+      "frameless": true,
+      "noActivate": true,
+      "transparent": true,
+      "showOnFirstLoad": false
+    }
+  }
+}
+```
+
+All fields are optional. The defaults preserve the standard 800×600, decorated,
+activating, opaque window that appears after its first page load. `frameless`,
+`noActivate`, `transparentTitlebar`, and `transparent` are applied when macOS,
+Windows, or Linux creates the native window, so they cannot be set later by
+adopting it in JavaScript. Set `showOnFirstLoad` to `false` when your app will
+reveal the adopted window itself.
+
 ## `release`
 
 Configuration for the auto-update system.