From b25688bceb91d46246a070e838eed1ddba015a82 Mon Sep 17 00:00:00 2001
From: Patrick Kettner <patrickkettner@gmail.com>
Date: Wed, 14 Feb 2024 17:16:03 -0500
Subject: [PATCH] update window.browser spec per #532

---
 specification/window.browser.bs | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/specification/window.browser.bs b/specification/window.browser.bs
index 3dbbe9b8..f540c767 100644
--- a/specification/window.browser.bs
+++ b/specification/window.browser.bs
@@ -52,6 +52,39 @@ spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/
     it MUST be used only for WebExtension related functionality.
   </section>
 
+  <section>
+    For backwards compatibility with older versions of web extensions, a UA MAY
+    alias individual properties of {{browser}} to <code>chrome</code>. {{browser}}
+    and <code>chrome</code> SHOULD NOT be direct aliases. Instead, individual
+    subproperties SHOULD be what is alaised. Any modification of a property of
+    {{browser}} SHOULD be reflected on <code>chrome</code>, and vice versa.
+
+    <div class="example" id="example-1">
+      Here's an example of the expected alias behavior
+      <pre><code class="lang-js">
+        // As `chrome` and `browser` are not direct aliases,
+        // modifying one top level values will not change the other
+
+        globalThis.browser.FAKE = true
+
+        console.log(globalThis.chrome.FAKE);
+        // undefined
+
+        // Individual properies are aliased, so updating a known property
+        // directly changes the existing property on the other
+        globalThis.browser.runtime.FAKE = 123
+
+        console.log(globalThis.chrome.runtime.FAKE);
+        // 123
+      </code></pre>
+
+    </div>
+
+
+  </section>
+
+/e
+
 
 <pre class="idl">
   partial interface Window {