45 files changed, 124 insertions, 12 deletions
diff --git a/docs/guide/getting-started/supported-languages.md b/docs/guide/getting-started/supported-languages.md
index eacd1da..0dc3f62 100644
--- a/docs/guide/getting-started/supported-languages.md
+++ b/docs/guide/getting-started/supported-languages.md
@@ -18,16 +18,16 @@ The runtime is [GJS](https://gitlab.gnome.org/GNOME/gjs) and **not** nodejs
 
 Examples:
 
-- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/js/simple-bar)
+- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/gtk3/js/simple-bar)
 ![simple-bar](https://github.com/user-attachments/assets/a306c864-56b7-44c4-8820-81f424f32b9b)
 
-- [Notification Popups](https://github.com/Aylur/astal/tree/main/examples/js/notifications)
+- [Notification Popups](https://github.com/Aylur/astal/tree/main/examples/gtk3/js/notifications)
 ![notification-popups](https://github.com/user-attachments/assets/0df0eddc-5c74-4af0-a694-48dc8ec6bb44)
 
-- [Applauncher](https://github.com/Aylur/astal/tree/main/examples/js/applauncher)
+- [Applauncher](https://github.com/Aylur/astal/tree/main/examples/gtk3/js/applauncher)
 ![launcher](https://github.com/user-attachments/assets/2695e3bb-dff4-478a-b392-279fe638bfd3)
 
-- [Media Player](https://github.com/Aylur/astal/tree/main/examples/js/media-player)
+- [Media Player](https://github.com/Aylur/astal/tree/main/examples/gtk3/js/media-player)
 ![media-player](https://github.com/user-attachments/assets/891e9706-74db-4505-bd83-c3628d7b4fd0)
 
 ## Lua
@@ -36,7 +36,7 @@ Lua is well-supported, but I would still recommend TypeScript, as Lua lacks a ty
 
 Examples:
 
-- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/lua/simple-bar)
+- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/gtk3/lua/simple-bar)
 ![simple-bar](https://github.com/user-attachments/assets/a306c864-56b7-44c4-8820-81f424f32b9b)
 
 ## Python
@@ -47,7 +47,7 @@ However, you can still use python the OOP way [pygobject](https://pygobject.gnom
 
 Examples:
 
-- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/py/simple-bar)
+- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/gtk3/py/simple-bar)
 ![simple-bar](https://github.com/user-attachments/assets/a306c864-56b7-44c4-8820-81f424f32b9b)
 
 ## Vala
@@ -58,7 +58,7 @@ using TypeScript or Lua over Vala as they are simpler to work with.
 
 Examples:
 
-- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/vala/simple-bar)
+- [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/gtk3/vala/simple-bar)
 ![simple-bar](https://github.com/user-attachments/assets/a306c864-56b7-44c4-8820-81f424f32b9b)
 
 ## C
diff --git a/docs/guide/lua/examples.md b/docs/guide/lua/examples.md
index be46b6e..c2dd30c 100644
--- a/docs/guide/lua/examples.md
+++ b/docs/guide/lua/examples.md
@@ -1,4 +1,4 @@
 # Lua examples
 
-## [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/lua/simple-bar)
+## [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/gtk3/lua/simple-bar)
 ![simple-bar](https://github.com/user-attachments/assets/a306c864-56b7-44c4-8820-81f424f32b9b)
diff --git a/docs/guide/typescript/examples.md b/docs/guide/typescript/examples.md
index ec51e89..ff1d9a1 100644
--- a/docs/guide/typescript/examples.md
+++ b/docs/guide/typescript/examples.md
@@ -2,13 +2,13 @@
 
 ## Gtk3
 
-### [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/js/simple-bar)
+### [Simple Bar](https://github.com/Aylur/astal/tree/main/examples/gtk3/js/simple-bar)
 ![simple-bar](https://github.com/user-attachments/assets/a306c864-56b7-44c4-8820-81f424f32b9b)
 
-### [Notification Popups](https://github.com/Aylur/astal/tree/main/examples/js/notifications)
+### [Notification Popups](https://github.com/Aylur/astal/tree/main/examples/gtk3/js/notifications)
 ![notification-popups](https://github.com/user-attachments/assets/0df0eddc-5c74-4af0-a694-48dc8ec6bb44)
-### [Applauncher](https://github.com/Aylur/astal/tree/main/examples/js/applauncher)
+### [Applauncher](https://github.com/Aylur/astal/tree/main/examples/gtk3/js/applauncher)
 ![launcher](https://github.com/user-attachments/assets/2695e3bb-dff4-478a-b392-279fe638bfd3)
 
-### [Media Player](https://github.com/Aylur/astal/tree/main/examples/js/media-player)
+### [Media Player](https://github.com/Aylur/astal/tree/main/examples/gtk3/js/media-player)
 ![media-player](https://github.com/user-attachments/assets/891e9706-74db-4505-bd83-c3628d7b4fd0)
diff --git a/docs/guide/typescript/faq.md b/docs/guide/typescript/faq.md
index 132900a..15a97e5 100644
--- a/docs/guide/typescript/faq.md
+++ b/docs/guide/typescript/faq.md
@@ -299,3 +299,11 @@ focusable set its keymode.
 />
 ```
 :::
+
+## How to create a Popup
+
+In Gtk4 simply use Gtk's builtin [Popover](https://docs.gtk.org/gtk4/class.Popover.html).
+
+In Gtk3 you can create an [Astal.Window](https://aylur.github.io/libastal/astal3/class.Window.html) and handle click events.
+
+Checkout [examples/gtk3/js/popover](https://github.com/Aylur/astal/tree/main/examples/gtk3/js/popover)
diff --git a/examples/js/.gitignore b/examples/gtk3/js/.gitignore
index d53b85b..d53b85b 100644
--- a/examples/js/.gitignore
+++ b/examples/gtk3/js/.gitignore
diff --git a/examples/js/applauncher/README.md b/examples/gtk3/js/applauncher/README.md
index 682adf1..682adf1 100644
--- a/examples/js/applauncher/README.md
+++ b/examples/gtk3/js/applauncher/README.md
diff --git a/examples/js/applauncher/app.ts b/examples/gtk3/js/applauncher/app.ts
index d6c9e1c..d6c9e1c 100644
--- a/examples/js/applauncher/app.ts
+++ b/examples/gtk3/js/applauncher/app.ts
diff --git a/examples/js/applauncher/style.scss b/examples/gtk3/js/applauncher/style.scss
index ba13eed..ba13eed 100644
--- a/examples/js/applauncher/style.scss
+++ b/examples/gtk3/js/applauncher/style.scss
diff --git a/examples/js/applauncher/widget/Applauncher.scss b/examples/gtk3/js/applauncher/widget/Applauncher.scss
index ae2453d..ae2453d 100644
--- a/examples/js/applauncher/widget/Applauncher.scss
+++ b/examples/gtk3/js/applauncher/widget/Applauncher.scss
diff --git a/examples/js/applauncher/widget/Applauncher.tsx b/examples/gtk3/js/applauncher/widget/Applauncher.tsx
index c7bac68..c7bac68 100644
--- a/examples/js/applauncher/widget/Applauncher.tsx
+++ b/examples/gtk3/js/applauncher/widget/Applauncher.tsx
diff --git a/examples/js/media-player/README.md b/examples/gtk3/js/media-player/README.md
index 4e3d237..4e3d237 100644
--- a/examples/js/media-player/README.md
+++ b/examples/gtk3/js/media-player/README.md
diff --git a/examples/js/media-player/app.ts b/examples/gtk3/js/media-player/app.ts
index 5b7558a..5b7558a 100644
--- a/examples/js/media-player/app.ts
+++ b/examples/gtk3/js/media-player/app.ts
diff --git a/examples/js/media-player/style.scss b/examples/gtk3/js/media-player/style.scss
index 2e2f625..2e2f625 100644
--- a/examples/js/media-player/style.scss
+++ b/examples/gtk3/js/media-player/style.scss
diff --git a/examples/js/media-player/widget/MediaPlayer.scss b/examples/gtk3/js/media-player/widget/MediaPlayer.scss
index e1597c2..e1597c2 100644
--- a/examples/js/media-player/widget/MediaPlayer.scss
+++ b/examples/gtk3/js/media-player/widget/MediaPlayer.scss
diff --git a/examples/js/media-player/widget/MediaPlayer.tsx b/examples/gtk3/js/media-player/widget/MediaPlayer.tsx
index 06c7e77..06c7e77 100644
--- a/examples/js/media-player/widget/MediaPlayer.tsx
+++ b/examples/gtk3/js/media-player/widget/MediaPlayer.tsx
diff --git a/examples/js/notifications/README.md b/examples/gtk3/js/notifications/README.md
index 60dad60..60dad60 100644
--- a/examples/js/notifications/README.md
+++ b/examples/gtk3/js/notifications/README.md
diff --git a/examples/js/notifications/app.ts b/examples/gtk3/js/notifications/app.ts
index ed53292..ed53292 100644
--- a/examples/js/notifications/app.ts
+++ b/examples/gtk3/js/notifications/app.ts
diff --git a/examples/js/notifications/notifications/Notification.scss b/examples/gtk3/js/notifications/notifications/Notification.scss
index a32f08b..a32f08b 100644
--- a/examples/js/notifications/notifications/Notification.scss
+++ b/examples/gtk3/js/notifications/notifications/Notification.scss
diff --git a/examples/js/notifications/notifications/Notification.tsx b/examples/gtk3/js/notifications/notifications/Notification.tsx
index 5149d5b..5149d5b 100644
--- a/examples/js/notifications/notifications/Notification.tsx
+++ b/examples/gtk3/js/notifications/notifications/Notification.tsx
diff --git a/examples/js/notifications/notifications/NotificationPopups.tsx b/examples/gtk3/js/notifications/notifications/NotificationPopups.tsx
index 13fdd88..13fdd88 100644
--- a/examples/js/notifications/notifications/NotificationPopups.tsx
+++ b/examples/gtk3/js/notifications/notifications/NotificationPopups.tsx
diff --git a/examples/js/notifications/style.scss b/examples/gtk3/js/notifications/style.scss
index 7ef0168..7ef0168 100644
--- a/examples/js/notifications/style.scss
+++ b/examples/gtk3/js/notifications/style.scss
diff --git a/examples/gtk3/js/popover/app.tsx b/examples/gtk3/js/popover/app.tsx
new file mode 100644
index 0000000..6358297
--- /dev/null
+++ b/examples/gtk3/js/popover/app.tsx
@@ -0,0 +1,104 @@
+import { App, Astal, Gdk, Gtk } from "astal/gtk3"
+
+const { TOP, RIGHT, BOTTOM, LEFT } = Astal.WindowAnchor
+
+type PopupProps = {
+    child?: unknown
+    marginBottom?: number
+    marginTop?: number
+    marginLeft?: number
+    marginRight?: number
+    halign?: Gtk.Align
+    valign?: Gtk.Align
+}
+
+function Popup({
+    child,
+    marginBottom,
+    marginTop,
+    marginLeft,
+    marginRight,
+    halign = Gtk.Align.CENTER,
+    valign = Gtk.Align.CENTER,
+}: PopupProps) {
+    return (
+        <window
+            visible={false}
+            css="background-color: transparent"
+            keymode={Astal.Keymode.EXCLUSIVE}
+            anchor={TOP | RIGHT | BOTTOM | LEFT}
+            exclusivity={Astal.Exclusivity.IGNORE}
+            // close when click occurs otside of child
+            onButtonPressEvent={(self, event) => {
+                const [, _x, _y] = event.get_coords()
+                const { x, y, width, height } = self
+                    .get_child()!
+                    .get_allocation()
+
+                const xOut = _x < x || _x > x + width
+                const yOut = _y < y || _y > y + height
+
+                // clicked outside
+                if (xOut || yOut) self.hide()
+            }}
+            // close when hitting Escape
+            onKeyPressEvent={(self, event: Gdk.Event) => {
+                if (event.get_keyval()[1] === Gdk.KEY_Escape) {
+                    self.hide()
+                }
+            }}
+        >
+            <box
+                className="Popup"
+                onButtonPressEvent={() => true} // make sure click event does not bubble up
+                // child can be positioned with `halign` `valign` and margins
+                expand
+                halign={halign}
+                valign={valign}
+                marginBottom={marginBottom}
+                marginTop={marginTop}
+                marginStart={marginLeft}
+                marginEnd={marginRight}
+            >
+                {child}
+            </box>
+        </window>
+    )
+}
+
+App.start({
+    instanceName: "popup-example",
+    css: `
+        .Popup {
+            background-color: @theme_bg_color;
+            box-shadow: 2px 3px 7px 0 rgba(0,0,0,0.4);
+            border-radius: 12px;
+            padding: 12px;
+        }
+    `,
+    main() {
+        const popup = (
+            <Popup
+                marginTop={36}
+                marginRight={60}
+                valign={Gtk.Align.START}
+                halign={Gtk.Align.END}
+            >
+                <button onClicked={() => popup.hide()}>
+                    Click me to close the popup
+                </button>
+            </Popup>
+        )
+
+        return (
+            <window
+                anchor={TOP | LEFT | RIGHT}
+                exclusivity={Astal.Exclusivity.EXCLUSIVE}
+            >
+                <button onClicked={() => popup.show()} halign={Gtk.Align.END}>
+                    Click to open popup
+                </button>
+            </window>
+        )
+    },
+})
diff --git a/examples/js/simple-bar/README.md b/examples/gtk3/js/simple-bar/README.md
index f92b20e..f92b20e 100644
--- a/examples/js/simple-bar/README.md
+++ b/examples/gtk3/js/simple-bar/README.md
diff --git a/examples/js/simple-bar/app.ts b/examples/gtk3/js/simple-bar/app.ts
index 4b7ea48..4b7ea48 100644
--- a/examples/js/simple-bar/app.ts
+++ b/examples/gtk3/js/simple-bar/app.ts
diff --git a/examples/js/simple-bar/style.scss b/examples/gtk3/js/simple-bar/style.scss
index f5f771a..f5f771a 100644
--- a/examples/js/simple-bar/style.scss
+++ b/examples/gtk3/js/simple-bar/style.scss
diff --git a/examples/js/simple-bar/widget/Bar.tsx b/examples/gtk3/js/simple-bar/widget/Bar.tsx
index 6592f6a..6592f6a 100644
--- a/examples/js/simple-bar/widget/Bar.tsx
+++ b/examples/gtk3/js/simple-bar/widget/Bar.tsx
diff --git a/examples/lua/simple-bar/README.md b/examples/gtk3/lua/simple-bar/README.md
index 48cc27c..48cc27c 100644
--- a/examples/lua/simple-bar/README.md
+++ b/examples/gtk3/lua/simple-bar/README.md
diff --git a/examples/lua/simple-bar/init.lua b/examples/gtk3/lua/simple-bar/init.lua
index 8c412fb..8c412fb 100644
--- a/examples/lua/simple-bar/init.lua
+++ b/examples/gtk3/lua/simple-bar/init.lua
diff --git a/examples/lua/simple-bar/lib.lua b/examples/gtk3/lua/simple-bar/lib.lua
index d94db5c..d94db5c 100644
--- a/examples/lua/simple-bar/lib.lua
+++ b/examples/gtk3/lua/simple-bar/lib.lua
diff --git a/examples/lua/simple-bar/style.scss b/examples/gtk3/lua/simple-bar/style.scss
index f5f771a..f5f771a 100644
--- a/examples/lua/simple-bar/style.scss
+++ b/examples/gtk3/lua/simple-bar/style.scss
diff --git a/examples/lua/simple-bar/widget/Bar.lua b/examples/gtk3/lua/simple-bar/widget/Bar.lua
index 155b9b8..155b9b8 100644
--- a/examples/lua/simple-bar/widget/Bar.lua
+++ b/examples/gtk3/lua/simple-bar/widget/Bar.lua
diff --git a/examples/py/.gitignore b/examples/gtk3/py/.gitignore
index c18dd8d..c18dd8d 100644
--- a/examples/py/.gitignore
+++ b/examples/gtk3/py/.gitignore
diff --git a/examples/py/simple-bar/README.md b/examples/gtk3/py/simple-bar/README.md
index 48cc27c..48cc27c 100644
--- a/examples/py/simple-bar/README.md
+++ b/examples/gtk3/py/simple-bar/README.md
diff --git a/examples/py/simple-bar/__init__.py b/examples/gtk3/py/simple-bar/__init__.py
index e69de29..e69de29 100644
--- a/examples/py/simple-bar/__init__.py
+++ b/examples/gtk3/py/simple-bar/__init__.py
diff --git a/examples/py/simple-bar/app.py b/examples/gtk3/py/simple-bar/app.py
index d95dc0e..d95dc0e 100755
--- a/examples/py/simple-bar/app.py
+++ b/examples/gtk3/py/simple-bar/app.py
diff --git a/examples/py/simple-bar/style.scss b/examples/gtk3/py/simple-bar/style.scss
index f5f771a..f5f771a 100644
--- a/examples/py/simple-bar/style.scss
+++ b/examples/gtk3/py/simple-bar/style.scss
diff --git a/examples/py/simple-bar/versions.py b/examples/gtk3/py/simple-bar/versions.py
index 0e57708..0e57708 100644
--- a/examples/py/simple-bar/versions.py
+++ b/examples/gtk3/py/simple-bar/versions.py
diff --git a/examples/py/simple-bar/widget/Bar.py b/examples/gtk3/py/simple-bar/widget/Bar.py
index 555ab85..555ab85 100644
--- a/examples/py/simple-bar/widget/Bar.py
+++ b/examples/gtk3/py/simple-bar/widget/Bar.py
diff --git a/examples/py/simple-bar/widget/__init__.py b/examples/gtk3/py/simple-bar/widget/__init__.py
index e69de29..e69de29 100644
--- a/examples/py/simple-bar/widget/__init__.py
+++ b/examples/gtk3/py/simple-bar/widget/__init__.py
diff --git a/examples/vala/simple-bar/README.md b/examples/gtk3/vala/simple-bar/README.md
index 48cc27c..48cc27c 100644
--- a/examples/vala/simple-bar/README.md
+++ b/examples/gtk3/vala/simple-bar/README.md
diff --git a/examples/vala/simple-bar/app.in.vala b/examples/gtk3/vala/simple-bar/app.in.vala
index b04a1fa..b04a1fa 100644
--- a/examples/vala/simple-bar/app.in.vala
+++ b/examples/gtk3/vala/simple-bar/app.in.vala
diff --git a/examples/vala/simple-bar/flake.nix b/examples/gtk3/vala/simple-bar/flake.nix
index d13c649..d13c649 100644
--- a/examples/vala/simple-bar/flake.nix
+++ b/examples/gtk3/vala/simple-bar/flake.nix
diff --git a/examples/vala/simple-bar/meson.build b/examples/gtk3/vala/simple-bar/meson.build
index 5a0ef4c..5a0ef4c 100644
--- a/examples/vala/simple-bar/meson.build
+++ b/examples/gtk3/vala/simple-bar/meson.build
diff --git a/examples/vala/simple-bar/style.scss b/examples/gtk3/vala/simple-bar/style.scss
index f5f771a..f5f771a 100644
--- a/examples/vala/simple-bar/style.scss
+++ b/examples/gtk3/vala/simple-bar/style.scss
diff --git a/examples/vala/simple-bar/widget/Bar.vala b/examples/gtk3/vala/simple-bar/widget/Bar.vala
index 28b32ef..28b32ef 100644
--- a/examples/vala/simple-bar/widget/Bar.vala
+++ b/examples/gtk3/vala/simple-bar/widget/Bar.vala