From d0707882ba2a730f392d68ac88868118f6187b6f Mon Sep 17 00:00:00 2001
From: Leandro Rodrigues <leandromqrs@hotmail.com>
Date: Tue, 28 Jul 2026 15:29:19 -0300
Subject: [PATCH 1/3] feat: polish dock behavior and extension review readiness

Introduce configurable dock motion profiles with isolated animation state, press feedback, and integration coverage for catalog and transform behavior.

Keep Picture-in-Picture windows above normal windows and visible across workspaces while excluding them from dock smart reveal, including the cross-monitor focus case where PiP previously caused the dock to reappear.

Expand Capture Tools with movable annotations, deterministic toolbar placement, and stronger unit and Shell integration coverage.

Separate production and development extension entry points, modularize Just recipes, verify package contents, and keep developer-only tooling out of the production archive.

Harden lifecycle cleanup across Shell modules, document accepted EGO analyzer findings, align metadata and documentation, and add policy checks for GNOME Extensions review readiness.

Validated with type checking, linting, formatting, Shexli, 184 unit tests, 22 GNOME Shell integration tests, and production/development package inspections.
---
 .github/workflows/ci.yml                      |  15 +-
 .just/package.just                            |  78 ++++
 .just/test.just                               |  37 ++
 .just/toolbox.just                            |  65 +++
 .just/translation.just                        |  56 +++
 .just/vagrant.just                            |  27 ++
 AGENTS.md                                     |  74 +++-
 ARCHITECTURE.md                               |   6 +-
 CONTRIBUTING.md                               |  25 +-
 CREDITS.md                                    |   7 +
 Containerfile                                 |   1 +
 EGO_REVIEW.md                                 |  60 +++
 README.md                                     |   4 +
 data/po/pt_BR.po                              |   4 +-
 ....shell.extensions.aurora-shell.gschema.xml |  17 +-
 justfile                                      | 235 +++-------
 metadata.json                                 |   2 +-
 package.json                                  |   2 +-
 sass.config.ts                                |  22 +-
 scripts/check-packages.ts                     |  63 +++
 scripts/run-shell-tests.sh                    |   9 +-
 scripts/run-vagrant-gnome-shell.sh            |   1 +
 src/capture/annotationModel.ts                | 148 ++++++-
 src/capture/captureTools.ts                   |  69 +--
 src/capture/toolbarPlacement.ts               | 110 +++++
 src/clipboard/clipboardItem.ts                |   8 +-
 src/core/extensionBase.ts                     |  52 +++
 src/core/lifecycleScope.ts                    |  10 +-
 src/desktop/trayIcons/trayContainer.ts        |  30 +-
 src/desktop/trayIcons/trayIcons.ts            |  76 ++--
 src/device/device.ts                          |  24 +-
 src/dock/dock.manifest.ts                     |  17 +
 src/dock/dock.ts                              |  67 ++-
 src/dock/externalStorageIcon.ts               | 113 +++--
 src/dock/hotArea.ts                           |  18 +-
 src/dock/intellihide.ts                       |  29 +-
 src/dock/intellihideState.ts                  |  31 +-
 src/dock/motion/catalog.ts                    | 140 ++++++
 src/dock/motion/dashMotionIntegration.ts      |  80 ++++
 src/dock/motion/easing.ts                     |  20 +
 src/dock/motion/iconMotionController.ts       | 419 ++++++++++++++++++
 src/dock/motion/motionSurface.ts              | 198 +++++++++
 src/dock/motion/pressInteraction.ts           |  50 +++
 src/dock/motion/transforms.ts                 | 194 ++++++++
 src/dock/trashIcon.ts                         |  40 +-
 src/extension.dev.ts                          |  40 ++
 src/extension.ts                              |  89 +---
 src/panel/auroraMenu.ts                       |   2 +-
 src/panel/bluetoothMenu/bluetoothMenu.ts      |   2 +-
 .../meetingClock/calendarServerBackend.ts     |  10 +-
 src/panel/clock/meetingClock/meetingClock.ts  |  25 +-
 src/panel/clock/weatherClock/weatherClock.ts  |  21 +-
 src/panel/volumeMixer/mixerList.ts            |  13 +-
 src/panel/volumeMixer/streamSlider.ts         |   2 +-
 src/patches/appSearchTooltip.ts               |  33 +-
 src/patches/iconWeave.ts                      |  75 ++--
 src/patches/pipOnTop.manifest.ts              |   2 +-
 src/patches/pipOnTop.ts                       | 165 ++++---
 src/patches/pipWindowPolicy.ts                |  42 ++
 src/patches/velaVpnQuickSettings.ts           |   4 +-
 src/patches/xwaylandIndicator.ts              |   2 +-
 src/privacy/dndOnShare.ts                     |   2 +-
 src/privacy/privacyPanel.ts                   |   4 +-
 src/shared/ui/dash.ts                         |  59 ++-
 src/styles/stylesheet-dark.scss               |  13 +-
 src/styles/stylesheet-light.scss              |  13 +-
 src/theme/themeChanger.ts                     |  22 +-
 tests/shell/auroraCaptureTools.js             |  54 ++-
 tests/shell/auroraDock.js                     | 144 +++++-
 tests/unit/annotationModel.test.ts            |  73 ++-
 tests/unit/dockMotionCatalog.test.ts          |  60 +++
 tests/unit/dockMotionPressInteraction.test.ts |  59 +++
 tests/unit/dockMotionTransforms.test.ts       | 109 +++++
 tests/unit/egoPolicy.test.ts                  |  76 ++++
 tests/unit/intellihideState.test.ts           |  87 +++-
 tests/unit/pipWindowPolicy.test.ts            |  89 ++++
 tests/unit/registry.test.ts                   |   4 +-
 tests/unit/toolbarPlacement.test.ts           |  99 +++++
 78 files changed, 3499 insertions(+), 748 deletions(-)
 create mode 100644 .just/package.just
 create mode 100644 .just/test.just
 create mode 100644 .just/toolbox.just
 create mode 100644 .just/translation.just
 create mode 100644 .just/vagrant.just
 create mode 100644 EGO_REVIEW.md
 create mode 100644 scripts/check-packages.ts
 create mode 100644 src/capture/toolbarPlacement.ts
 create mode 100644 src/core/extensionBase.ts
 create mode 100644 src/dock/motion/catalog.ts
 create mode 100644 src/dock/motion/dashMotionIntegration.ts
 create mode 100644 src/dock/motion/easing.ts
 create mode 100644 src/dock/motion/iconMotionController.ts
 create mode 100644 src/dock/motion/motionSurface.ts
 create mode 100644 src/dock/motion/pressInteraction.ts
 create mode 100644 src/dock/motion/transforms.ts
 create mode 100644 src/extension.dev.ts
 create mode 100644 src/patches/pipWindowPolicy.ts
 create mode 100644 tests/unit/dockMotionCatalog.test.ts
 create mode 100644 tests/unit/dockMotionPressInteraction.test.ts
 create mode 100644 tests/unit/dockMotionTransforms.test.ts
 create mode 100644 tests/unit/egoPolicy.test.ts
 create mode 100644 tests/unit/pipWindowPolicy.test.ts
 create mode 100644 tests/unit/toolbarPlacement.test.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b18c3aa..92b60f6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -108,7 +108,7 @@ jobs:
         run: just deps
 
       - name: Run unit tests
-        run: just unit-test
+        run: just test unit
 
   build:
     name: Build
@@ -127,14 +127,16 @@ jobs:
       - name: Install dependencies
         run: just deps
 
-      - name: Build extension package
-        run: just package
+      - name: Build and inspect extension packages
+        run: just package check
 
-      - name: Upload extension zip
+      - name: Upload extension zips
         uses: actions/upload-artifact@v7
         with:
           name: extension-zip
-          path: dist/target/aurora-shell@luminusos.github.io.shell-extension.zip
+          path: |
+            dist/target/aurora-shell@luminusos.github.io.shell-extension.zip
+            dist/target/aurora-shell@luminusos.github.io.development.shell-extension.zip
           retention-days: 1
 
   integration-tests:
@@ -190,3 +192,6 @@ jobs:
             "$XDG_SESSION_ID" seat0 "$(id -u)" "$(id -un)" true
           bash scripts/run-shell-tests.sh \
             dist/target/aurora-shell@luminusos.github.io.shell-extension.zip
+          AURORA_DEVTOOLS=1 bash scripts/run-shell-tests.sh \
+            dist/target/aurora-shell@luminusos.github.io.development.shell-extension.zip \
+            tests/shell/auroraDevTool.js
diff --git a/.just/package.just b/.just/package.just
new file mode 100644
index 0000000..fcaa32e
--- /dev/null
+++ b/.just/package.just
@@ -0,0 +1,78 @@
+uuid := "aurora-shell@luminusos.github.io"
+
+# Build the production ZIP.
+default: production
+
+# Build the production ZIP.
+production: _build _production
+
+# Build the DevTool-enabled ZIP.
+development: _build _development
+
+# Build and inspect both ZIPs.
+[no-cd]
+check: _build _production _development
+    yarn tsx scripts/check-packages.ts
+
+[no-cd]
+_build:
+    just build
+
+[no-cd]
+_production:
+    #!/usr/bin/env bash
+    set -e
+    mkdir -p dist/target
+    cd dist
+
+    extra_sources=()
+    while IFS= read -r source; do
+        case "$source" in
+            dev|extension.dev.js|extension.js|metadata.json|schemas|target) continue ;;
+        esac
+        extra_sources+=("--extra-source=$source")
+    done < <(find . -mindepth 1 -maxdepth 1 -printf '%P\n' | sort)
+
+    gnome-extensions pack . \
+        --force \
+        --out-dir=target \
+        "${extra_sources[@]}" \
+        --schema=schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml
+
+    echo "Production package ready."
+
+[no-cd]
+_development:
+    #!/usr/bin/env bash
+    set -e
+    work="$(mktemp -d)"
+    stage="$work/stage"
+    target="$work/target"
+    trap 'rm -rf "$work"' EXIT
+
+    mkdir -p "$stage" "$target" dist/target
+    cp -a dist/. "$stage/"
+    rm -rf "$stage/target"
+    cp "$stage/extension.dev.js" "$stage/extension.js"
+    cp "$stage/dev/stylesheet.css" "$stage/stylesheet.css"
+    cp "$stage/dev/stylesheet-light.css" "$stage/stylesheet-light.css"
+    cp "$stage/dev/stylesheet-dark.css" "$stage/stylesheet-dark.css"
+
+    extra_sources=()
+    while IFS= read -r source; do
+        case "$source" in
+            extension.dev.js|extension.js|metadata.json|schemas|target) continue ;;
+        esac
+        extra_sources+=("--extra-source=$source")
+    done < <(find "$stage" -mindepth 1 -maxdepth 1 -printf '%P\n' | sort)
+
+    gnome-extensions pack "$stage" \
+        --force \
+        --out-dir="$target" \
+        "${extra_sources[@]}" \
+        --schema="$stage/schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml"
+    mv \
+        "$target/{{ uuid }}.shell-extension.zip" \
+        "dist/target/{{ uuid }}.development.shell-extension.zip"
+
+    echo "Development package ready."
diff --git a/.just/test.just b/.just/test.just
new file mode 100644
index 0000000..19c7531
--- /dev/null
+++ b/.just/test.just
@@ -0,0 +1,37 @@
+uuid := "aurora-shell@luminusos.github.io"
+production_zip := "dist/target/" + uuid + ".shell-extension.zip"
+development_zip := "dist/target/" + uuid + ".development.shell-extension.zip"
+
+# List the available test commands.
+default:
+    @just --list test
+
+# Run unit tests.
+[no-cd]
+unit:
+    yarn test:unit
+
+# Run unit tests with coverage.
+[no-cd]
+coverage:
+    yarn test:unit:coverage
+
+# Run one GNOME Shell integration test.
+[no-cd]
+shell script:
+    just package production
+    bash scripts/run-shell-tests.sh {{ production_zip }} {{ script }}
+
+# Run every production GNOME Shell integration test.
+[no-cd]
+all:
+    just package production
+    bash scripts/run-shell-tests.sh {{ production_zip }}
+
+# Run the DevTool integration test.
+[no-cd]
+dev:
+    just package development
+    AURORA_DEVTOOLS=1 bash scripts/run-shell-tests.sh \
+        {{ development_zip }} \
+        tests/shell/auroraDevTool.js
diff --git a/.just/toolbox.just b/.just/toolbox.just
new file mode 100644
index 0000000..91541e7
--- /dev/null
+++ b/.just/toolbox.just
@@ -0,0 +1,65 @@
+toolbox_name := env_var_or_default("AURORA_TOOLBOX_NAME", "aurora-shell-devel")
+uuid := "aurora-shell@luminusos.github.io"
+production_zip := "dist/target/" + uuid + ".shell-extension.zip"
+development_zip := "dist/target/" + uuid + ".development.shell-extension.zip"
+
+# List the available toolbox commands.
+default:
+    @just --list toolbox
+
+# Create the Fedora development toolbox.
+[no-cd]
+create:
+    #!/usr/bin/env bash
+    set -e
+    if [ -n "${AURORA_TOOLBOX_IMAGE:-}" ]; then
+        image="$AURORA_TOOLBOX_IMAGE"
+    else
+        image="$(bash scripts/ci-image-name.sh)"
+        podman build -f Containerfile -t "$image" .
+    fi
+
+    echo "Creating toolbox '{{ toolbox_name }}' from '$image'..."
+    toolbox create --image "$image" {{ toolbox_name }}
+
+# Launch GNOME Shell inside the toolbox.
+[no-cd]
+run:
+    bash scripts/run-gnome-shell.sh {{ toolbox_name }}
+
+# Remove the development toolbox.
+[no-cd]
+remove:
+    toolbox rm --force {{ toolbox_name }}
+    @echo "Removed toolbox '{{ toolbox_name }}'."
+
+# Run a test inside the toolbox: `test <script>`, `test all`, or `test dev`.
+[no-cd]
+test target:
+    #!/usr/bin/env bash
+    set -e
+    project="$(pwd -P)"
+
+    case "{{ target }}" in
+        all)
+            just package production
+            toolbox --container {{ toolbox_name }} run \
+                bash "$project/scripts/run-shell-tests.sh" \
+                "$project/{{ production_zip }}"
+            ;;
+        dev)
+            just package development
+            toolbox --container {{ toolbox_name }} run \
+                env AURORA_DEVTOOLS=1 \
+                bash "$project/scripts/run-shell-tests.sh" \
+                "$project/{{ development_zip }}" \
+                "$project/tests/shell/auroraDevTool.js"
+            ;;
+        *)
+            just package production
+            toolbox --container {{ toolbox_name }} run \
+                bash "$project/scripts/run-shell-tests.sh" \
+                "$project/{{ production_zip }}" \
+                "$project/{{ target }}"
+            ;;
+    esac
diff --git a/.just/translation.just b/.just/translation.just
new file mode 100644
index 0000000..8dcfb91
--- /dev/null
+++ b/.just/translation.just
@@ -0,0 +1,56 @@
+# List the available translation commands.
+default:
+    @just --list translation
+
+# Regenerate the POT template.
+[no-cd]
+pot:
+    #!/usr/bin/env bash
+    set -e
+    just build
+    mapfile -t javascript_files < <(find dist -name '*.js' | sort)
+
+    xgettext \
+        --from-code=UTF-8 \
+        --language=JavaScript \
+        --keyword=_ \
+        --keyword=ngettext:1,2 \
+        --keyword=pgettext:1c,2 \
+        --package-name=aurora-shell \
+        --msgid-bugs-address=https://github.com/luminusOS/aurora-shell/issues \
+        --output=dist/aurora-shell@luminusos.github.io.pot \
+        "${javascript_files[@]}"
+
+    echo "POT template regenerated."
+
+# Merge the current POT template into every PO catalog.
+[no-cd]
+update: pot
+    #!/usr/bin/env bash
+    set -e
+    for catalog in data/po/*.po; do
+        echo "Merging $catalog..."
+        msgmerge \
+            --update \
+            --backup=none \
+            "$catalog" \
+            dist/aurora-shell@luminusos.github.io.pot
+    done
+
+    echo "Translation catalogs updated."
+
+# Compile every PO catalog into dist.
+[no-cd]
+compile:
+    #!/usr/bin/env bash
+    set -e
+    domain="aurora-shell@luminusos.github.io"
+
+    for catalog in data/po/*.po; do
+        [ -f "$catalog" ] || continue
+        language="$(basename "$catalog" .po)"
+        output="dist/locale/$language/LC_MESSAGES/$domain.mo"
+        mkdir -p "$(dirname "$output")"
+        msgfmt --output-file="$output" "$catalog"
+        echo "Compiled $catalog -> $output"
+    done
diff --git a/.just/vagrant.just b/.just/vagrant.just
new file mode 100644
index 0000000..8495b81
--- /dev/null
+++ b/.just/vagrant.just
@@ -0,0 +1,27 @@
+name := "aurora-shell-devel"
+
+# List the available Vagrant commands.
+default:
+    @just --list vagrant
+
+# Boot and provision the development VM.
+[no-cd]
+create:
+    @echo "Booting and provisioning Vagrant VM '{{ name }}'..."
+    vagrant up
+
+# Launch GNOME Shell inside the VM.
+[no-cd]
+run:
+    bash scripts/run-vagrant-gnome-shell.sh
+
+# Open an SSH session in the VM.
+[no-cd]
+ssh:
+    vagrant ssh
+
+# Destroy the development VM.
+[no-cd]
+remove:
+    vagrant destroy -f
+    @echo "Removed Vagrant VM '{{ name }}'."
diff --git a/AGENTS.md b/AGENTS.md
index 56179b0..e4123ce 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,16 +13,16 @@ or `just shexli` unless the task specifically requires that validation.
 1.  **Run `just validate`** — type-checks the source, lints, and checks formatting. Fix any reported errors.
 2.  **Run `just shexli`** — packages the extension and runs the extensions.gnome.org static analyzer on the generated ZIP. Review every finding. Some `warning` or `manual_review` findings can be false positives or accepted GNOME-review tradeoffs, but they must be called out explicitly; fix any real regression before finishing.
 3.  **Run targeted integration tests:**
-    - If you modified only **one module**, run only the integration test for that module (e.g., `just test tests/shell/auroraTrayIcons.js`).
+    - If you modified only **one module**, run only the integration test for that module (e.g., `just test shell tests/shell/auroraTrayIcons.js`).
     - If you made **formatting-only changes** (Prettier) and have already passed the tests in a previous turn, you only need to run `just validate` and `just shexli`.
-    - If you made **architectural or cross-cutting changes**, run `just toolbox test-all`.
+    - If you made **architectural or cross-cutting changes**, run `just toolbox test all`.
 
-**IMPORTANT:** Never execute the `test` command (or `test-all`) chained with another command using `&&`. Always run it as a separate standalone turn.
+**IMPORTANT:** Never execute `just test shell`, `just test all`, or `just toolbox test` chained with another command using `&&`. Always run tests as a separate standalone turn.
 
-To read only the relevant output from a `test-all` run (pass/fail summary):
+To read only the relevant output from a full test run (pass/fail summary):
 
 ```sh
-just toolbox test-all 2>&1 | grep -E "PASS:|FAIL:|Results:"
+just toolbox test all 2>&1 | grep -E "PASS:|FAIL:|Results:"
 ```
 
 Do not leave a task incomplete if either command reports errors or failures.
@@ -31,10 +31,12 @@ Do not leave a task incomplete if either command reports errors or failures.
 
 - **Install deps:** `just deps` — runs `yarn install --immutable`; use once or after changing branches
 - **Build:** `just build` — compiles TypeScript and SCSS, copies metadata/schemas, and compiles `.mo` files
-- **Package:** `just package` — packs the extension as a `.zip` in `dist/target/` (depends on `build`)
-- **Install:** `just install` — packages and installs the `.zip` to GNOME Shell
+- **Package:** `just package production` — packs the production extension as a `.zip` in `dist/target/`
+- **Development package:** `just package development` — packs the separate DevTool-enabled development ZIP
+- **Inspect packages:** `just package check` — builds both ZIPs and verifies their contents and generated line lengths
+- **Install:** `just install` — packages and installs the DevTool-enabled development ZIP
 - **Uninstall:** `just uninstall` — disables and removes the extension
-- **Run (host):** `just run` — packages, installs, then launches a devkit GNOME Shell session
+- **Run (host):** `just run` — installs development, then launches a DevTool-enabled devkit session
 - **Run (toolbox):** `just toolbox run` — packages/installs on the host, then runs GNOME Shell inside the Fedora toolbox
 - **Create toolbox:** `just toolbox create` — creates `aurora-shell-devel` from the same Fedora/GNOME image used by CI
 - **Remove toolbox:** `just toolbox remove` — delete the toolbox
@@ -44,25 +46,28 @@ Do not leave a task incomplete if either command reports errors or failures.
 - **Watch SCSS:** `just watch` — watches `src/styles/` and recompiles on change
 - **View logs:** `just logs` — shows recent `aurora` entries from the current boot journal
 - **Clean:** `just clean` — removes `dist/`
-- **Deep clean:** `just distclean` — removes `dist/` and `node_modules/`
-- **Unit tests:** `just unit-test` — runs unit tests with Node's test runner
-- **Coverage:** `just coverage` — runs unit tests with coverage report
-- **Single integration test:** `just test <script>` — packages and runs one shell test script headlessly (e.g., `just test tests/shell/auroraTrayIcons.js`)
-- **All integration tests:** `just test-all` — packages and runs all `tests/shell/aurora*.js` on the host, printing a pass/fail summary
-- **All integration tests (toolbox):** `just toolbox test-all` — same as above but inside the Fedora toolbox (preferred; use this instead of `just test-all`)
+- **Deep clean:** `just clean all` — removes `dist/` and `node_modules/`
+- **Unit tests:** `just test unit` — runs unit tests with Node's test runner
+- **Coverage:** `just test coverage` — runs unit tests with coverage report
+- **Single integration test:** `just test shell <script>` — packages and runs one shell test script headlessly (e.g., `just test shell tests/shell/auroraTrayIcons.js`)
+- **All integration tests:** `just test all` — packages and runs all `tests/shell/aurora*.js` on the host, printing a pass/fail summary
+- **DevTool integration test:** `just test dev` — tests `auroraDevTool.js` against the development ZIP
+- **All integration tests (toolbox):** `just toolbox test all` — same as above but inside the Fedora toolbox (preferred; use this instead of `just test all`)
 - **Single integration test (toolbox):** `just toolbox test <script>` — packages and runs one test inside the toolbox
 - **Vagrant VM:** `just vagrant create|run|ssh|remove` — full Arch VM kept for manual GNOME environment testing
 
 ### Translation commands
 
-- **Regenerate POT template:** `just pot` — builds, then scans compiled JS (`dist/`) and writes the `.pot` into `dist/` (a build artifact, **not** committed — avoids `POT-Creation-Date` churn). Run this whenever translatable strings are added or removed.
-- **Merge new strings into .po files:** `just update-po` — depends on `pot`; regenerates the template into `dist/` then runs `msgmerge` on every `data/po/*.po` against it. The hand-translated `data/po/*.po` files are the committed source of truth.
-- **Compile .mo binaries:** `just compile-mo` — compiles each `po/*.po` into `dist/locale/<lang>/LC_MESSAGES/*.mo`. Called automatically by `just build`.
+- **Regenerate POT template:** `just translation pot` — builds, then scans compiled JS (`dist/`) and writes the `.pot` into `dist/` (a build artifact, **not** committed — avoids `POT-Creation-Date` churn). Run this whenever translatable strings are added or removed.
+- **Merge new strings into .po files:** `just translation update` — depends on `translation pot`; regenerates the template into `dist/` then runs `msgmerge` on every `data/po/*.po` against it. The hand-translated `data/po/*.po` files are the committed source of truth.
+- **Compile .mo binaries:** `just translation compile` — compiles each `po/*.po` into `dist/locale/<lang>/LC_MESSAGES/*.mo`. Called automatically by `just build`.
 
 ## Repository Structure
 
 - `src/` — TypeScript source root
-  - `extension.ts` — entry point; creates the context and delegates lifecycle to `ModuleManager`
+  - `extension.ts` — minimal production entry point
+  - `extension.dev.ts` — development entry point used only by the development ZIP
+  - `core/extensionBase.ts` — shared extension lifecycle; creates the context and delegates to `ModuleManager`
   - `module.ts` — base `Module` plus manifest, option, factory, and runtime policy types
   - `moduleCatalog.ts` — ordered Shell-free manifest catalog shared by runtime and preferences
   - `moduleManager.ts` — settings/runtime reconciliation, failure isolation, and teardown
@@ -81,7 +86,7 @@ Do not leave a task incomplete if either command reports errors or failures.
     - `privacy/` — privacy and screen-sharing behavior
     - `clipboard/` — clipboard history module and UI
   - `device/` — runtime target and hardware capability detection for future mobile work
-  - `dev/` — developer-only tooling (e.g., `devTool.ts`), gated behind the `AURORA_DEVTOOLS=1` env var. **Not** a feature module: it is not in the registry, prefs, or gschema, and is instantiated directly by `extension.ts`
+  - `dev/` — developer-only tooling (e.g., `devTool.ts`), gated behind the `AURORA_DEVTOOLS=1` env var and excluded from the production ZIP. **Not** a feature module: it is not in the registry, prefs, or gschema
   - `shared/` — shared utilities used across modules (e.g., `quickSettings.ts`)
   - `styles/` — SCSS stylesheets (compiled to light + dark CSS)
   - `types/` — TypeScript type declarations (`@girs`, GJS, etc.)
@@ -171,6 +176,37 @@ Per the GNOME review guidelines, clipboard-related keyboard shortcuts must not s
 
 Avoid code that only looks plausible. A human reviewer should be able to read a change and see a real contract, not a guess.
 
+### EGO review policy
+
+Changes intended for the production extension must follow both:
+
+- [GNOME Extensions review guidelines](https://gjs.guide/extensions/review-guidelines/review-guidelines.html)
+- [EGO AI reference](https://blogs.gnome.org/jrahmatzadeh/2026/07/27/ego-ai-reference/)
+
+Apply these rules during implementation and review:
+
+- Target the Shell versions declared in `metadata.json`; do not add speculative compatibility checks
+  or optional calls for APIs guaranteed by those versions.
+- Keep `extension.ts` small and keep `enable()`/`disable()` close, symmetric, and limited to lifecycle
+  orchestration.
+- Every signal, GLib source, cancellable, child actor, menu, and other resource created by a component
+  must be cleaned up by that same component. Remove sources and signals before destroying owned actors,
+  and call `super.destroy()` last in widget overrides.
+- Override a widget's `destroy()` method for its cleanup. Do not connect the widget's own `destroy`
+  signal as a substitute.
+- Do not add `_enabled`, `_destroyed`, or similar lifecycle flags when owned references, cancellables,
+  or the underlying GObject lifecycle already express the state. Any unavoidable exception needs a
+  concise invariant comment and regression coverage.
+- Avoid defensive `try`/`catch` around deterministic cleanup and avoid trivial comments that merely
+  restate the next line.
+- Do not use emoji or ASCII art as UI icons, do not ship placeholders, keep generated JavaScript lines
+  at 200 characters or fewer, and keep production packages free of developer-only files.
+- Avoid subprocesses in the Shell process. If a subprocess is unavoidable, document why a D-Bus
+  service is not practical and keep invocation local, explicit, cancellable, and free of shell
+  interpretation.
+- Review every Shexli finding. Fix real ownership/lifecycle defects and record accepted manual-review
+  findings or analyzer false positives in `EGO_REVIEW.md`.
+
 - Do not add optional calls such as `object?.method?.(...)` unless that method is a real, documented API or the local type intentionally models it. Never use patterns like `this.disconnectObject?.(this)` on objects that do not own that signal connection contract.
 - Do not ship fake behavior. If a UI label, schema description, README entry, or module subtitle says a feature is wired to NetworkManager, ModemManager, UPower, sensors, widgets, or GNOME internals, the code must actually call the relevant API or clearly describe itself as a fallback.
 - Keep runtime capability checks honest. Hardware-specific modules must detect missing services/devices at runtime and stay inactive or degrade explicitly.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 0425fc6..d211e20 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -89,10 +89,10 @@ to match the schema exactly.
 ## Test Boundaries
 
 Pure TypeScript logic belongs in `tests/unit`. St/Clutter/Main integration belongs in
-`tests/shell`. Architectural changes are accepted only after `just validate`, `just unit-test`,
-`just shexli`, and `just toolbox test-all`.
+`tests/shell`. Architectural changes are accepted only after `just validate`, `just test unit`,
+`just shexli`, and `just toolbox test all`.
 
 ## Packaging
 
-`just package` builds TypeScript and SCSS into `dist/`, compiles schemas and translations, and packs
+`just package production` builds TypeScript and SCSS into `dist/`, compiles schemas and translations, and packs
 the extension. Manifests stay as source modules; no TypeScript or XML generation step is involved.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6f45fc9..d277861 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -122,24 +122,27 @@ The CI pipeline runs all tests and, if they pass, publishes the GitHub Release a
 
 - **Install deps:** `just deps` — runs an immutable Yarn install; use once or after changing branches
 - **Build:** `just build` — compiles TypeScript and SCSS, copies metadata/schemas, compiles `.mo` files
-- **Package:** `just package` — packs the extension as a `.zip` in `dist/target/` (depends on `build`)
-- **Install:** `just install` — packages and installs the `.zip` to GNOME Shell
+- **Package:** `just package production` — packs the production extension ZIP
+- **Development package:** `just package development` — packs the separate DevTool-enabled ZIP
+- **Package policy:** `just package check` — builds and inspects both artifacts
+- **Install:** `just install` — packages and installs the DevTool-enabled development ZIP
 - **Uninstall:** `just uninstall` — disables and removes the extension
-- **Run (host):** `just run` — launches a devkit GNOME Shell session (headless, Wayland)
+- **Run (host):** `just run` — installs development and launches a DevTool-enabled devkit session
 - **Validate:** `just validate` — runs tsc, ESLint, Prettier check, and Stylelint
 - **Lint:** `just lint` — runs ESLint only
-- **Unit tests:** `just unit-test` — runs unit tests with Node's test runner (no GNOME Shell required)
-- **Coverage:** `just coverage` — runs unit tests with coverage report
-- **Single integration test:** `just test <script>` — packages and runs one shell test headlessly
-- **All integration tests:** `just test-all` — packages and runs all shell tests on the host, printing a pass/fail summary
+- **Unit tests:** `just test unit` — runs unit tests with Node's test runner (no GNOME Shell required)
+- **Coverage:** `just test coverage` — runs unit tests with coverage report
+- **Single integration test:** `just test shell <script>` — packages and runs one shell test headlessly
+- **All integration tests:** `just test all` — packages and runs all shell tests on the host, printing a pass/fail summary
+- **DevTool integration test:** `just test dev` — runs the DevTool test against the development ZIP
 - **Shexli review scan:** `just shexli` — packages the extension and runs the extensions.gnome.org static analyzer on the generated ZIP
 - **Watch SCSS:** `just watch` — watches `src/styles/` and recompiles on change
 - **View logs:** `just logs` — shows recent `aurora` entries from the current boot journal
 - **Clean:** `just clean` — removes `dist/`
-- **Deep clean:** `just distclean` — removes `dist/` and `node_modules/`
+- **Deep clean:** `just clean all` — removes `dist/` and `node_modules/`
 
 For a full test environment, create the Fedora toolbox with `just toolbox create` and run
-`just toolbox test-all` (preferred over `just test-all`). The toolbox uses the public,
+`just toolbox test all` (preferred over `just test all`). The toolbox uses the public,
 versioned GNOME image from `ghcr.io/luminusos/aurora-shell-ci` shared with CI. Set
 `AURORA_TOOLBOX_IMAGE` to test a locally built replacement.
 
@@ -168,7 +171,7 @@ extensions.gnome.org:
 just shexli
 ```
 
-The recipe depends on `just package` and scans the generated
+The recipe depends on `just package production` and scans the generated
 `dist/target/aurora-shell@luminusos.github.io.shell-extension.zip`. Install Shexli with
 `python3 -m pip install --user shexli`, or install `uvx` and the recipe will run
 `uvx --from shexli shexli` automatically.
@@ -180,7 +183,7 @@ job ensures the CI image exists; the four validation jobs then run inside that s
 
 1. **Validate** — runs tsc, ESLint, Prettier check, and Stylelint via `just validate`
 2. **Unit & regression tests** — runs the Node test suite without GNOME Shell
-3. **Build** — runs `just package` and uploads the extension `.zip` as an artifact (depends on lint)
+3. **Build** — runs `just package check` and uploads both extension ZIPs as artifacts (depends on lint)
 4. **Integration tests** — runs the shared Shell-test runner against headless GNOME Shell (depends on build + unit tests)
 
 The private `XDG_RUNTIME_DIR`, system D-Bus, and logind mock in the integration job belong only to
diff --git a/CREDITS.md b/CREDITS.md
index c2008c7..8cbfe13 100644
--- a/CREDITS.md
+++ b/CREDITS.md
@@ -50,3 +50,10 @@ local screenshot OCR workflow is inspired by
 `data/icons/hicolor/scalable/actions/` are copied from Gradia Capture and redistributed under
 GPL-3.0. The toolbar integration, annotation canvas, export, and OCR implementation are otherwise
 independent.
+
+## Dock Motion
+
+The Dock motion recipes and controller behavior are adapted from
+[**Orsso/d2d-companion**](https://github.com/Orsso/d2d-companion), version `v0.1.0-beta.1`
+(commit `33eef1d2ddc4678c46d015a4a2c276d4177901df`). The adapted source is redistributed
+under GPL-2.0-or-later and is combined with Aurora Shell under GPL-3.0-only.
diff --git a/Containerfile b/Containerfile
index c443b62..a666d4f 100644
--- a/Containerfile
+++ b/Containerfile
@@ -19,6 +19,7 @@ RUN dnf install -y --quiet --setopt=install_weak_deps=False \
         gsettings-desktop-schemas \
         just \
         mesa-dri-drivers \
+        mutter-devkit \
         nodejs \
         npm \
         python3-dbusmock \
diff --git a/EGO_REVIEW.md b/EGO_REVIEW.md
new file mode 100644
index 0000000..e97900e
--- /dev/null
+++ b/EGO_REVIEW.md
@@ -0,0 +1,60 @@
+# EGO Review Notes
+
+This file records the Aurora Shell review baseline for
+[the GNOME Extensions review guidelines](https://gjs.guide/extensions/review-guidelines/review-guidelines.html)
+and the
+[EGO AI reference](https://blogs.gnome.org/jrahmatzadeh/2026/07/27/ego-ai-reference/).
+It is not a replacement for reviewing the generated production ZIP.
+
+## Accepted manual-review findings
+
+### Clipboard access
+
+Aurora Shell intentionally accesses the clipboard in Clipboard History and Capture Tools.
+`metadata.json` describes both uses. Clipboard History stores data locally, its shortcut is unset by
+default, and neither clipboard nor OCR data is shared with third parties.
+
+### Capture Tools OCR subprocess
+
+Capture Tools invokes the local `tesseract` executable only after an explicit OCR action. The command
+uses `Gio.SubprocessLauncher` arguments directly rather than a shell, supports cancellation and forced
+termination, and does not transmit captured content. A companion D-Bus service would add installation
+and lifecycle complexity disproportionate to this optional, user-triggered operation, so this remains
+a documented subprocess exception.
+
+## Analyzer interpretation
+
+Aurora Shell uses `LifecycleScope`, `connectObject()`, and actor ownership for cleanup. Static analyzers
+can miss those indirect ownership paths. Treat a warning as a false positive only after tracing the
+corresponding enable/disable or create/destroy path; do not suppress or ignore findings by category.
+
+`AuroraDash._isDestroyed` is a narrow compatibility exception. The GNOME Shell base Dash creates raw
+connections that may call overridden methods after the subclass begins teardown, so the guard protects
+those callbacks until the base actor finishes destruction. Keep the invariant comment and Shell
+integration coverage if this exception changes.
+
+### Shexli baseline (2026-07-28)
+
+The production ZIP reports five findings, zero errors, and four warnings:
+
+- `EGO-A-005` is the declared clipboard manual review described above.
+- `EGO-L-002` is a structural false positive. Capture Tools destroys session actors through its
+  session `LifecycleScope`; Trash and External Storage are custom actors whose menus, monitors,
+  cancellables, and signals are released by their `destroy()` overrides before `super.destroy()`
+  destroys the owned child tree.
+- `EGO-L-005` is a custom-actor false positive for the non-null `toggleButton` child expected by
+  `DashItemContainer`. It remains actor-owned and is released by `super.destroy()`.
+- `EGO-L-003` is an indirection false positive. The listed signals are owned by `LifecycleScope`,
+  `connectObject()`, widget destruction, or the corresponding backend/manager `destroy()` method.
+- `EGO-L-004` is an indirection false positive. Clipboard History removes its startup idle through
+  `LifecycleScope`; Aurora Dash removes all six stored source IDs in `destroy()`; Auto Theme Switcher
+  registers `_cancelScheduledTick()` in its `LifecycleScope`.
+
+Recheck this classification against every new Shexli run. A stable rule ID does not imply that new
+locations are automatically accepted.
+
+## Package policy
+
+The production ZIP contains `LICENSE` and `CREDITS.md`, excludes developer tooling, targets only the
+Shell versions declared in `metadata.json`, and is the only artifact submitted to EGO. The development
+ZIP is separate and exists solely for the local DevTool integration test and development sessions.
diff --git a/README.md b/README.md
index 732e855..da6a0ca 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,9 @@
 
 A modular GNOME Shell extension that adds quality-of-life features missing in vanilla GNOME.
 
+Aurora Shell is distributed under the GNU General Public License, version 3 only. See
+[LICENSE](LICENSE) and [CREDITS.md](CREDITS.md) for licensing and attribution details.
+
 > **Project goal:** Aurora Shell is a proving ground. Over time, the aim is for some of its
 > features to mature and make their way upstream into GNOME Shell itself. Modules here are
 > meant to be useful on their own today and good candidates for upstream tomorrow.
@@ -90,5 +93,6 @@ Aurora Shell builds on the work of the wider GNOME community. Special thanks to:
 - [**swsnr/gnome-shell-extension-xwayland-indicator**](https://codeberg.org/swsnr/gnome-shell-extension-xwayland-indicator/) the inspiration behind the XWayland Indicator module.
 - [**AlexanderVanhee/gradia-capture**](https://github.com/AlexanderVanhee/gradia-capture) inspired the Capture Tools annotation workflow.
 - [**SamkitJain660/Shotzy**](https://github.com/SamkitJain660/Shotzy) inspired the local screenshot OCR workflow.
+- [**Orsso/d2d-companion**](https://github.com/Orsso/d2d-companion) is the source of the adapted Dock motion behavior.
 
 See [CREDITS.md](CREDITS.md) for the full list of attributed work.
diff --git a/data/po/pt_BR.po b/data/po/pt_BR.po
index 4e60b59..0c81c0c 100644
--- a/data/po/pt_BR.po
+++ b/data/po/pt_BR.po
@@ -795,8 +795,8 @@ msgid "Pip On Top"
 msgstr "PiP Sempre no Topo"
 
 #: dist/patches/pipOnTop.manifest.js:9
-msgid "Keeps Picture-in-Picture windows always on top"
-msgstr "Mantém janelas Picture-in-Picture sempre no topo"
+msgid "Keeps Picture-in-Picture windows above others across workspaces"
+msgstr "Mantém janelas Picture-in-Picture acima das demais em todas as áreas de trabalho"
 
 #: dist/patches/velaVpnQuickSettings.manifest.js:8
 msgid "Vela VPN Quick Settings"
diff --git a/data/schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml b/data/schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml
index 205903a..0f3a8e2 100644
--- a/data/schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml
+++ b/data/schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml
@@ -9,7 +9,7 @@
     <key name="module-pip-on-top" type="b">
       <default>true</default>
       <summary>Enable Pip On Top module</summary>
-      <description>Keeps Picture-in-Picture windows always on top</description>
+      <description>Keeps Picture-in-Picture windows above others across workspaces</description>
     </key>
     <key name="module-focus-launched-windows" type="b">
       <default>true</default>
@@ -132,6 +132,21 @@
       <summary>Show external storage</summary>
       <description>Show removable drives in the dock when they are connected</description>
     </key>
+    <key name="dock-motion-enabled" type="b">
+      <default>true</default>
+      <summary>Enable dock icon hover &amp; press effects</summary>
+      <description>Animate dock icons on hover and click</description>
+    </key>
+    <key name="dock-motion-profile" type="s">
+      <choices>
+        <choice value="subtle"/>
+        <choice value="balanced"/>
+        <choice value="expressive"/>
+      </choices>
+      <default>'subtle'</default>
+      <summary>Dock icon effect intensity</summary>
+      <description>Subtle, Balanced, or Expressive dock icon hover and press motion</description>
+    </key>
     <key name="module-aurora-menu" type="b">
       <default>true</default>
       <summary>Enable Aurora Menu module</summary>
diff --git a/justfile b/justfile
index 64be540..9b22ab2 100644
--- a/justfile
+++ b/justfile
@@ -1,229 +1,104 @@
 uuid := "aurora-shell@luminusos.github.io"
-ext_dir := env("HOME") / ".local/share/gnome-shell/extensions" / uuid
-toolbox_name := env_var_or_default("AURORA_TOOLBOX_NAME", "aurora-shell-devel")
-vagrant_name := "aurora-shell-devel"
-
+extension_dir := env("HOME") / ".local/share/gnome-shell/extensions" / uuid
+
+# Build production and development extension archives.
+mod package '.just/package.just'
+# Run unit, coverage, and GNOME Shell tests.
+mod test '.just/test.just'
+# Manage and test inside the Fedora development container.
+mod toolbox '.just/toolbox.just'
+# Maintain translation templates and compiled catalogs.
+mod translation '.just/translation.just'
+# Manage the full development VM.
+mod vagrant '.just/vagrant.just'
+
+# List the available command groups.
 default:
     @just --list
 
+# Install immutable JavaScript dependencies.
 deps:
     yarn install --immutable
 
+# Compile sources and assemble the unpacked extension.
 build:
     yarn build
     cp metadata.json dist/
+    cp LICENSE CREDITS.md dist/
     cp -r data/schemas dist/
     glib-compile-schemas dist/schemas/
     cp -r data/icons dist/
     cp -r data/media dist/
-    just compile-mo
+    just translation compile
 
-package: build
-    #!/usr/bin/env bash
-    set -e
-    mkdir -p dist/target
-    cd dist
-    EXTRA_SOURCES=()
-    while IFS= read -r source; do
-        case "$source" in
-            extension.js|metadata.json|schemas|target) continue ;;
-        esac
-        EXTRA_SOURCES+=("--extra-source=$source")
-    done < <(find . -mindepth 1 -maxdepth 1 -printf '%P\n' | sort)
+# Run type, lint, formatting, and style checks.
+validate:
+    yarn validate
+
+# Run ESLint.
+lint:
+    yarn lint
 
-    gnome-extensions pack . \
-        --force \
-        --out-dir=target \
-        "${EXTRA_SOURCES[@]}" \
-        --schema=schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml
-    echo "Packing Done!"
+# Watch and recompile SCSS.
+watch:
+    yarn watch:css
 
-shexli *args: package
+# Scan the production package with the EGO static analyzer.
+shexli *args: package::production
     #!/usr/bin/env bash
     set -e
-    EXT="dist/target/{{ uuid }}.shell-extension.zip"
+    extension="dist/target/{{ uuid }}.shell-extension.zip"
 
     if command -v shexli >/dev/null 2>&1; then
-        shexli "$EXT" {{ args }}
+        shexli "$extension" {{ args }}
     elif command -v uvx >/dev/null 2>&1; then
-        uvx --from shexli shexli "$EXT" {{ args }}
+        uvx --from shexli shexli "$extension" {{ args }}
     else
         echo "shexli is not installed."
         echo "Install it with: python3 -m pip install --user shexli"
-        echo "Then run: just shexli"
         exit 1
     fi
 
-validate:
-    yarn validate
-
-lint:
-    yarn lint
-
-watch:
-    yarn watch:css
-
-install: package
-    gnome-extensions install --force dist/target/{{ uuid }}.shell-extension.zip
-    glib-compile-schemas {{ ext_dir }}/schemas/
-    @echo "Installed at: {{ ext_dir }}"
+# Install the development package locally.
+install: package::development
+    gnome-extensions install --force dist/target/{{ uuid }}.development.shell-extension.zip
+    glib-compile-schemas {{ extension_dir }}/schemas/
+    @echo "Installed development package at: {{ extension_dir }}"
 
+# Remove the locally installed extension.
 uninstall:
     gnome-extensions uninstall {{ uuid }}
     @echo "Uninstalled."
 
-logs:
-    journalctl -b 0 -r -o cat /usr/bin/gnome-shell | grep -i "aurora"
-
-clean:
-    rm -rf dist
-
-distclean:
-    rm -rf dist
-    rm -rf node_modules
-
-# Translation workflow
-# Run `just pot` after adding new translatable strings to regenerate the template.
-# Run `just update-po` to merge new strings from the template into existing .po files.
-# Edit po/*.po files (with Poedit or a text editor), then run `just build`.
-
-pot: build
-    #!/usr/bin/env bash
-    set -e
-    JS_FILES=$(find dist -name '*.js' | sort)
-    POT="dist/aurora-shell@luminusos.github.io.pot"
-    xgettext \
-        --from-code=UTF-8 \
-        --language=JavaScript \
-        --keyword=_ \
-        --keyword=ngettext:1,2 \
-        --keyword=pgettext:1c,2 \
-        --package-name=aurora-shell \
-        --msgid-bugs-address=https://github.com/luminusOS/aurora-shell/issues \
-        --output="$POT" \
-        $JS_FILES
-    echo "POT file regenerated: $POT"
-
-update-po: pot
-    #!/usr/bin/env bash
-    set -e
-    POT="dist/aurora-shell@luminusos.github.io.pot"
-    for po in data/po/*.po; do
-        echo "Merging $po..."
-        msgmerge --update --backup=none "$po" "$POT"
-    done
-    echo "All .po files updated."
-
-compile-mo:
-    #!/usr/bin/env bash
-    set -e
-    DOMAIN="aurora-shell@luminusos.github.io"
-    for po in data/po/*.po; do
-        [ -f "$po" ] || continue
-        lang=$(basename "$po" .po)
-        outdir="dist/locale/$lang/LC_MESSAGES"
-        mkdir -p "$outdir"
-        msgfmt --output-file="$outdir/$DOMAIN.mo" "$po"
-        echo "Compiled $po -> $outdir/$DOMAIN.mo"
-    done
-
-unit-test:
-    yarn test:unit
-
-coverage:
-    yarn test:unit:coverage
-
-# Run a single test script with gnome-shell-test-tool (headless).
-# Wrapped in dbus-run-session to avoid conflicting with any running GNOME session.
-
-# Usage: just test tests/shell/auroraBasic.js
-test script: package
-    bash scripts/run-shell-tests.sh dist/target/{{ uuid }}.shell-extension.zip {{ script }}
-
-test-all: package
-    bash scripts/run-shell-tests.sh dist/target/{{ uuid }}.shell-extension.zip
-
+# Install development and launch a host devkit GNOME Shell session.
 run: install
     #!/usr/bin/env bash
     set -e
-    SHELL_ENV=(
+    shell_environment=(
         GSETTINGS_SCHEMA_DIR=/usr/share/glib-2.0/schemas
+        AURORA_DEVTOOLS=1
         XDG_CURRENT_DESKTOP=GNOME
     )
-    env "${SHELL_ENV[@]}" dbus-run-session gnome-shell --wayland --devkit
+    env "${shell_environment[@]}" dbus-run-session gnome-shell --wayland --devkit
 
-toolbox action *args:
-    #!/usr/bin/env bash
-    set -e
-    case "{{ action }}" in
-        "create")
-            IMAGE="${AURORA_TOOLBOX_IMAGE:-$(bash scripts/ci-image-name.sh)}"
-            echo "Creating toolbox '{{ toolbox_name }}' from '$IMAGE'..."
-            toolbox create --image "$IMAGE" {{ toolbox_name }}
-            ;;
-        "run")
-            bash scripts/run-gnome-shell.sh {{ toolbox_name }}
-            ;;
-        "remove")
-            echo "Removing toolbox '{{ toolbox_name }}'..."
-            toolbox rm --force {{ toolbox_name }}
-            echo "Toolbox '{{ toolbox_name }}' removed."
-            ;;
-        "test")
-            just package
-            EXT="dist/target/{{ uuid }}.shell-extension.zip"
-            SCRIPT="{{ args }}"
-            if [ -z "$SCRIPT" ]; then
-                echo "Usage: just toolbox test <script>"
-                echo "Example: just toolbox test tests/shell/auroraBasic.js"
-                exit 1
-            fi
-            PROJECT_DIR="$(pwd -P)"
-            toolbox --container {{ toolbox_name }} run \
-                bash "$PROJECT_DIR/scripts/run-shell-tests.sh" \
-                "$PROJECT_DIR/$EXT" \
-                "$PROJECT_DIR/$SCRIPT"
-            ;;
-        "test-all")
-            just package
-            EXT="dist/target/{{ uuid }}.shell-extension.zip"
-            PROJECT_DIR="$(pwd -P)"
-            toolbox --container {{ toolbox_name }} run \
-                bash "$PROJECT_DIR/scripts/run-shell-tests.sh" \
-                "$PROJECT_DIR/$EXT"
-            ;;
-        *)
-            echo "Unknown toolbox action: {{ action }}"
-            echo "Available: create, run, remove, test <script>, test-all"
-            exit 1
-            ;;
-    esac
-
-# Vagrant-based devkit VM (mirrors 'toolbox' but uses a full VM via Vagrant).
+# Show Aurora messages from the current boot.
+logs:
+    journalctl -b 0 -r -o cat /usr/bin/gnome-shell | grep -i "aurora"
 
-# Actions: create | run | ssh | remove
-vagrant action *args:
+# Remove build output, or all generated dependencies with `just clean all`.
+clean scope="dist":
     #!/usr/bin/env bash
     set -e
-    case "{{ action }}" in
-        "create")
-            echo "Booting and provisioning Vagrant VM '{{ vagrant_name }}'..."
-            vagrant up
-            ;;
-        "run")
-            bash scripts/run-vagrant-gnome-shell.sh
-            ;;
-        "ssh")
-            vagrant ssh
+    case "{{ scope }}" in
+        dist)
+            rm -rf dist
             ;;
-        "remove")
-            echo "Destroying Vagrant VM '{{ vagrant_name }}'..."
-            vagrant destroy -f
-            echo "VM '{{ vagrant_name }}' destroyed."
+        all)
+            rm -rf dist node_modules
             ;;
         *)
-            echo "Unknown vagrant action: {{ action }}"
-            echo "Available: create, run, ssh, remove"
+            echo "Unknown clean scope: {{ scope }}"
+            echo "Available: dist, all"
             exit 1
             ;;
     esac
diff --git a/metadata.json b/metadata.json
index 6681be7..1ccf661 100644
--- a/metadata.json
+++ b/metadata.json
@@ -1,7 +1,7 @@
 {
     "name": "Aurora Shell",
     "description": "A customizable GNOME Shell extension that enhances the user experience with various modules and features. Clipboard History reads and stores clipboard content locally so it can be browsed and restored. Capture Tools writes captured images and locally recognized text to the clipboard when requested. No clipboard or OCR data is shared with third parties, and the Clipboard History shortcut is unset by default.",
-    "version-name": "50.10",
+    "version-name": "50.11",
     "uuid": "aurora-shell@luminusos.github.io",
     "url": "https://github.com/luminusOS/aurora-shell",
     "settings-schema": "org.gnome.shell.extensions.aurora-shell",
diff --git a/package.json b/package.json
index 84ac33f..92069e5 100644
--- a/package.json
+++ b/package.json
@@ -3,7 +3,7 @@
   "description": "A customizable GNOME Shell extension that enhances the user experience with various modules and features.",
   "type": "module",
   "main": "dist/extension.js",
-  "license": "LGPL-3.0-or-later",
+  "license": "GPL-3.0-only",
   "private": true,
   "workspaces": [
     "."
diff --git a/sass.config.ts b/sass.config.ts
index 88068b5..8c1a2b0 100644
--- a/sass.config.ts
+++ b/sass.config.ts
@@ -7,6 +7,7 @@ import * as sass from 'sass';
 interface SassEntry {
   input: string;
   outputs: string[];
+  packageVariant: 'production' | 'development';
 }
 
 interface SassConfig {
@@ -22,10 +23,22 @@ const config: SassConfig = {
     {
       input: 'src/styles/stylesheet-light.scss',
       outputs: ['dist/stylesheet.css', 'dist/stylesheet-light.css'],
+      packageVariant: 'production',
     },
     {
       input: 'src/styles/stylesheet-dark.scss',
       outputs: ['dist/stylesheet-dark.css'],
+      packageVariant: 'production',
+    },
+    {
+      input: 'src/styles/stylesheet-light.scss',
+      outputs: ['dist/dev/stylesheet.css', 'dist/dev/stylesheet-light.css'],
+      packageVariant: 'development',
+    },
+    {
+      input: 'src/styles/stylesheet-dark.scss',
+      outputs: ['dist/dev/stylesheet-dark.css'],
+      packageVariant: 'development',
     },
   ],
   watchGlobs: ['src/styles/**/*.scss'],
@@ -40,13 +53,18 @@ export default config;
 
 async function compileEntry(entry: SassEntry): Promise<void> {
   const inputPath = resolve(projectRoot, entry.input);
-  const result = await sass.compileAsync(inputPath, config.sassOptions);
+  const source = `
+@use ${JSON.stringify(pathToFileURL(inputPath).href)} with (
+  $package-variant: ${JSON.stringify(entry.packageVariant)}
+);
+`;
+  const result = await sass.compileStringAsync(source, config.sassOptions);
 
   await Promise.all(entry.outputs.map(async (output) => {
     const outputPath = resolve(projectRoot, output);
     await mkdir(dirname(outputPath), { recursive: true });
     await writeFile(outputPath, result.css, 'utf8');
-    console.log(`✓ ${entry.input} → ${output}`);
+    console.log(`✓ ${entry.input} (${entry.packageVariant}) → ${output}`);
   }));
 }
 
diff --git a/scripts/check-packages.ts b/scripts/check-packages.ts
new file mode 100644
index 0000000..187a280
--- /dev/null
+++ b/scripts/check-packages.ts
@@ -0,0 +1,63 @@
+import AdmZip from 'adm-zip';
+import { readFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+
+const UUID = 'aurora-shell@luminusos.github.io';
+const productionPath = resolve('dist/target', `${UUID}.shell-extension.zip`);
+const developmentPath = resolve('dist/target', `${UUID}.development.shell-extension.zip`);
+
+function inspectPackage(path: string, development: boolean): void {
+  const zip = new AdmZip(path);
+  const entries = zip.getEntries();
+  const names = new Set(entries.map((entry) => entry.entryName));
+  const label = development ? 'development' : 'production';
+
+  for (const required of ['extension.js', 'metadata.json', 'LICENSE', 'CREDITS.md']) {
+    if (!names.has(required)) throw new Error(`${label} package is missing ${required}`);
+  }
+
+  const extension = zip.readAsText('extension.js');
+  const stylesheet = zip.readAsText('stylesheet.css');
+  if (development) {
+    if (!names.has('dev/devTool.js'))
+      throw new Error('development package is missing dev/devTool.js');
+    if (!extension.includes('DevTool'))
+      throw new Error('development entry point does not enable DevTool');
+    if (!stylesheet.includes('.aurora-devtool'))
+      throw new Error('development package is missing DevTool styles');
+  } else {
+    const forbidden = [...names].filter(
+      (name) => name === 'extension.dev.js' || name.startsWith('dev/'),
+    );
+    if (forbidden.length > 0)
+      throw new Error(`production package contains developer files: ${forbidden.join(', ')}`);
+    if (extension.includes('DevTool') || extension.includes('AURORA_DEVTOOLS'))
+      throw new Error('production entry point references developer tooling');
+    if (stylesheet.includes('.aurora-devtool'))
+      throw new Error('production stylesheet contains developer-only styles');
+  }
+
+  for (const entry of entries) {
+    if (entry.isDirectory || !entry.entryName.endsWith('.js')) continue;
+    const lines = entry.getData().toString('utf8').split(/\r?\n/u);
+    for (const [index, line] of lines.entries()) {
+      if (line.length > 200)
+        throw new Error(
+          `${label} package ${entry.entryName}:${index + 1} has ${line.length} characters`,
+        );
+    }
+  }
+
+  console.log(`${label} package policy: PASS (${entries.length} entries)`);
+}
+
+for (const path of [productionPath, developmentPath]) {
+  try {
+    readFileSync(path);
+  } catch {
+    throw new Error(`package not found: ${basename(path)}`);
+  }
+}
+
+inspectPackage(productionPath, false);
+inspectPackage(developmentPath, true);
diff --git a/scripts/run-shell-tests.sh b/scripts/run-shell-tests.sh
index c7b8c98..9251e2b 100755
--- a/scripts/run-shell-tests.sh
+++ b/scripts/run-shell-tests.sh
@@ -51,6 +51,13 @@ else
   shopt -s nullglob
   TEST_SCRIPTS=("$PROJECT_DIR"/tests/shell/aurora*.js)
   shopt -u nullglob
+  PROD_TEST_SCRIPTS=()
+  for script in "${TEST_SCRIPTS[@]}"; do
+    if [[ "$(basename "$script")" != "auroraDevTool.js" ]]; then
+      PROD_TEST_SCRIPTS+=("$script")
+    fi
+  done
+  TEST_SCRIPTS=("${PROD_TEST_SCRIPTS[@]}")
 fi
 
 if (( ${#TEST_SCRIPTS[@]} == 0 )); then
@@ -79,7 +86,7 @@ run_test() {
       test_args=(--headless --extension "$1")
       extra_monitors=0
       case "$(basename "$2")" in
-        auroraClipboardHistory.js)
+        auroraCaptureTools.js | auroraClipboardHistory.js)
           extra_monitors=1
           ;;
         auroraDock.js)
diff --git a/scripts/run-vagrant-gnome-shell.sh b/scripts/run-vagrant-gnome-shell.sh
index 7b137d4..2a72277 100755
--- a/scripts/run-vagrant-gnome-shell.sh
+++ b/scripts/run-vagrant-gnome-shell.sh
@@ -20,6 +20,7 @@ vagrant ssh -- -t '
 
   echo "==> Starting GNOME Shell devkit session..."
   exec env \
+    AURORA_DEVTOOLS=1 \
     XDG_CURRENT_DESKTOP=GNOME \
     XDG_SESSION_TYPE=wayland \
     dbus-run-session gnome-shell --wayland --devkit
diff --git a/src/capture/annotationModel.ts b/src/capture/annotationModel.ts
index cd7d20c..8c82791 100644
--- a/src/capture/annotationModel.ts
+++ b/src/capture/annotationModel.ts
@@ -27,10 +27,19 @@ export type CaptureTransform = {
 };
 
 const MIN_DRAG_DISTANCE = 2;
+const POINTER_HIT_PADDING = 6;
+
+type MoveState = {
+  annotation: Annotation;
+  origin: Point;
+  originalPoints: Point[];
+  changed: boolean;
+};
 
 export class AnnotationModel {
   private _annotations: Annotation[] = [];
   private _draft: Annotation | null = null;
+  private _move: MoveState | null = null;
   private _tool: AnnotationTool = 'select';
   private _color = '#e01b24';
   private _width = 4;
@@ -74,7 +83,8 @@ export class AnnotationModel {
   }
 
   begin(point: Point): boolean {
-    if (this._tool === 'select' || this._tool === 'pointer' || this._tool === 'text') return false;
+    if (this._tool === 'pointer') return this._beginMove(point);
+    if (this._tool === 'select' || this._tool === 'text') return false;
 
     if (this._tool === 'stamp') {
       this._annotations.push({
@@ -97,6 +107,17 @@ export class AnnotationModel {
   }
 
   update(point: Point): boolean {
+    if (this._move) {
+      const offsetX = point.x - this._move.origin.x;
+      const offsetY = point.y - this._move.origin.y;
+      this._move.annotation.points = this._move.originalPoints.map((original) => ({
+        x: original.x + offsetX,
+        y: original.y + offsetY,
+      }));
+      this._move.changed = offsetX !== 0 || offsetY !== 0;
+      return true;
+    }
+
     if (!this._draft) return false;
 
     if (this._draft.tool === 'freehand') {
@@ -110,6 +131,12 @@ export class AnnotationModel {
   }
 
   finish(): boolean {
+    if (this._move) {
+      const changed = this._move.changed;
+      this._move = null;
+      return changed;
+    }
+
     const draft = this._draft;
     this._draft = null;
     if (!draft || !isUsefulAnnotation(draft)) return false;
@@ -132,6 +159,8 @@ export class AnnotationModel {
 
   cancelDraft(): void {
     this._draft = null;
+    if (this._move) this._move.annotation.points = clonePoints(this._move.originalPoints);
+    this._move = null;
   }
 
   undo(): boolean {
@@ -143,13 +172,26 @@ export class AnnotationModel {
   }
 
   clear(): boolean {
-    const changed = this._annotations.length > 0 || this._draft !== null;
+    const changed = this._annotations.length > 0 || this._draft !== null || this._move !== null;
     this._annotations = [];
     this._draft = null;
+    this._move = null;
     this._nextCounter = 1;
     return changed;
   }
 
+  private _beginMove(point: Point): boolean {
+    const annotation = findTopAnnotationAt(this._annotations, point);
+    if (!annotation) return false;
+    this._move = {
+      annotation,
+      origin: { ...point },
+      originalPoints: clonePoints(annotation.points),
+      changed: false,
+    };
+    return true;
+  }
+
   private _recalculateCounter(): void {
     this._nextCounter =
       this._annotations.reduce(
@@ -179,3 +221,105 @@ function isUsefulAnnotation(annotation: Annotation): boolean {
   const last = annotation.points[annotation.points.length - 1]!;
   return Math.hypot(last.x - first.x, last.y - first.y) >= MIN_DRAG_DISTANCE;
 }
+
+function findTopAnnotationAt(annotations: readonly Annotation[], point: Point): Annotation | null {
+  for (let index = annotations.length - 1; index >= 0; index--) {
+    const annotation = annotations[index]!;
+    if (annotationContainsPoint(annotation, point)) return annotation;
+  }
+  return null;
+}
+
+function annotationContainsPoint(annotation: Annotation, point: Point): boolean {
+  const points = annotation.points;
+  if (points.length === 0) return false;
+  const padding = POINTER_HIT_PADDING + annotation.width / 2;
+
+  if (annotation.tool === 'rectangle' || annotation.tool === 'solid-rectangle')
+    return points.length >= 2 && pointInBounds(point, points[0]!, points.at(-1)!, padding);
+
+  if (annotation.tool === 'stamp') {
+    const radius = Math.max(12, annotation.width * 2.5) + POINTER_HIT_PADDING;
+    return distance(point, points[0]!) <= radius;
+  }
+
+  if (annotation.tool === 'text') return pointInText(annotation, point, padding);
+
+  if (annotation.tool === 'arrow') {
+    if (points.length < 2) return false;
+    const start = points[0]!;
+    const end = points.at(-1)!;
+    const angle = Math.atan2(end.y - start.y, end.x - start.x);
+    const head = Math.max(10, annotation.width * 3);
+    const headLeft = {
+      x: end.x - head * Math.cos(angle - Math.PI / 6),
+      y: end.y - head * Math.sin(angle - Math.PI / 6),
+    };
+    const headRight = {
+      x: end.x - head * Math.cos(angle + Math.PI / 6),
+      y: end.y - head * Math.sin(angle + Math.PI / 6),
+    };
+    return (
+      distanceToSegment(point, start, end) <= padding ||
+      distanceToSegment(point, end, headLeft) <= padding ||
+      distanceToSegment(point, end, headRight) <= padding
+    );
+  }
+
+  const visualWidth = annotation.tool === 'highlighter' ? annotation.width * 4 : annotation.width;
+  return distanceToPolyline(point, points) <= POINTER_HIT_PADDING + visualWidth / 2;
+}
+
+function pointInText(annotation: Annotation, point: Point, padding: number): boolean {
+  const origin = annotation.points[0]!;
+  const lines = (annotation.text ?? '').split('\n');
+  const fontSize = Math.max(16, annotation.width * 4);
+  const width = Math.max(...lines.map((line) => line.length), 1) * fontSize * 0.65;
+  const height = Math.max(lines.length, 1) * fontSize;
+  return (
+    point.x >= origin.x - padding &&
+    point.x <= origin.x + width + padding &&
+    point.y >= origin.y - padding &&
+    point.y <= origin.y + height + padding
+  );
+}
+
+function pointInBounds(point: Point, first: Point, last: Point, padding: number): boolean {
+  return (
+    point.x >= Math.min(first.x, last.x) - padding &&
+    point.x <= Math.max(first.x, last.x) + padding &&
+    point.y >= Math.min(first.y, last.y) - padding &&
+    point.y <= Math.max(first.y, last.y) + padding
+  );
+}
+
+function distanceToPolyline(point: Point, points: readonly Point[]): number {
+  if (points.length === 1) return distance(point, points[0]!);
+  let closest = Number.POSITIVE_INFINITY;
+  for (let index = 1; index < points.length; index++)
+    closest = Math.min(closest, distanceToSegment(point, points[index - 1]!, points[index]!));
+  return closest;
+}
+
+function distanceToSegment(point: Point, start: Point, end: Point): number {
+  const deltaX = end.x - start.x;
+  const deltaY = end.y - start.y;
+  const lengthSquared = deltaX * deltaX + deltaY * deltaY;
+  if (lengthSquared === 0) return distance(point, start);
+  const projection = Math.max(
+    0,
+    Math.min(1, ((point.x - start.x) * deltaX + (point.y - start.y) * deltaY) / lengthSquared),
+  );
+  return distance(point, {
+    x: start.x + projection * deltaX,
+    y: start.y + projection * deltaY,
+  });
+}
+
+function distance(first: Point, second: Point): number {
+  return Math.hypot(first.x - second.x, first.y - second.y);
+}
+
+function clonePoints(points: readonly Point[]): Point[] {
+  return points.map((point) => ({ ...point }));
+}
diff --git a/src/capture/captureTools.ts b/src/capture/captureTools.ts
index 300a3ac..3d93d9f 100644
--- a/src/capture/captureTools.ts
+++ b/src/capture/captureTools.ts
@@ -24,6 +24,10 @@ import {
   type Geometry,
   type ScreenshotUi,
 } from '~/capture/screenshotUiAdapter.ts';
+import {
+  calculateToolbarTranslation,
+  findMonitorForSelection,
+} from '~/capture/toolbarPlacement.ts';
 import type { ExtensionContext } from '~/core/context.ts';
 import { LifecycleScope } from '~/core/lifecycleScope.ts';
 import { logger } from '~/core/logger.ts';
@@ -259,8 +263,10 @@ export class CaptureTools extends Module {
       this._setInteractionState('idle');
       this._syncToolbarPlacement();
     });
-    if (this._toolbar)
-      scope.connect(this._toolbar, 'notify::allocation', () => this._syncToolbarPlacement());
+    if (this._toolbar) {
+      for (const signal of ['notify::allocation', 'notify::mapped'])
+        scope.connect(this._toolbar, signal, () => this._syncToolbarPlacement());
+    }
 
     const monitorsChangedId = Main.layoutManager.connect('monitors-changed', () => {
       this._endToolbarDrag();
@@ -289,6 +295,7 @@ export class CaptureTools extends Module {
     this._originalOpen = original;
     const wrapper: ScreenshotOpen = async (mode = 0, ...args: unknown[]) => {
       this._portalMode = mode === 2;
+      const result = await original.call(ui, mode, ...args);
       this._syncVisibility();
       logger.debug(
         `Native screenshot UI opened; toolbar visible=${!this._portalMode} (mode=${mode})`,
@@ -296,7 +303,7 @@ export class CaptureTools extends Module {
           prefix: LOG_PREFIX,
         },
       );
-      return original.call(ui, mode, ...args);
+      return result;
     };
     this._openWrapper = wrapper;
     ui.open = wrapper;
@@ -482,11 +489,11 @@ export class CaptureTools extends Module {
     this._commitText(true);
     this._model?.setTool(tool);
     for (const [candidate, button] of this._toolButtons) button.checked = candidate === tool;
-    this._canvas?.setDrawingEnabled(this._isDrawingTool(tool) && this._toolbar?.visible === true);
+    this._canvas?.setDrawingEnabled(this._usesCanvas(tool) && this._toolbar?.visible === true);
   }
 
-  private _isDrawingTool(tool: AnnotationTool): boolean {
-    return tool !== 'select' && tool !== 'pointer';
+  private _usesCanvas(tool: AnnotationTool): boolean {
+    return tool !== 'select';
   }
 
   private _beginToolbarDrag(handle: St.Button, event: Clutter.Event): boolean {
@@ -732,7 +739,7 @@ export class CaptureTools extends Module {
       this._hideOcrPanel();
       this._ocrTooltip?.close();
     } else {
-      this._canvas?.setDrawingEnabled(this._model ? this._isDrawingTool(this._model.tool) : false);
+      this._canvas?.setDrawingEnabled(this._model ? this._usesCanvas(this._model.tool) : false);
     }
     this._syncOcrButton();
     if (visible) this._syncToolbarPlacement();
@@ -741,13 +748,10 @@ export class CaptureTools extends Module {
   private _syncToolbarPlacement(): void {
     const toolbar = this._toolbar;
     const ui = this._ui;
-    if (!toolbar || !ui || !toolbar.visible || toolbar.width === 0) return;
+    if (!toolbar || !ui || !toolbar.visible || !toolbar.mapped) return;
     // A position picked manually through the drag handle wins for the session.
     if (this._toolbarDraggedByUser) return;
 
-    const monitor = Main.layoutManager.primaryMonitor;
-    if (!monitor) return;
-
     let selection: Geometry | null = null;
     if (!this._portalMode && ui._shotButton.checked && ui._selectionButton.checked) {
       try {
@@ -764,22 +768,37 @@ export class CaptureTools extends Module {
       return;
     }
 
-    // Anchor to the aligned top-center slot the toolbar is allocated in, then
-    // translate so it floats just above the selection rectangle.
-    const [stageX, stageY] = toolbar.get_transformed_position();
-    const anchorX = stageX - toolbar.translation_x;
-    const anchorY = stageY - toolbar.translation_y;
     const [x, y, width, height] = selection;
-    const margin = 12;
-    const desiredX = Math.max(
-      monitor.x,
-      Math.min(x + width / 2 - toolbar.width / 2, monitor.x + monitor.width - toolbar.width),
+    const selectionRectangle = { x, y, width, height };
+    const monitor = findMonitorForSelection(
+      selectionRectangle,
+      Main.layoutManager.monitors ?? [],
+      Main.layoutManager.primaryIndex,
     );
-    let desiredY = y - toolbar.height - margin;
-    if (desiredY < monitor.y) desiredY = y + height + margin;
-    desiredY = Math.max(monitor.y, Math.min(desiredY, monitor.y + monitor.height - toolbar.height));
-    toolbar.translation_x = Math.round(desiredX - anchorX);
-    toolbar.translation_y = Math.round(desiredY - anchorY);
+    if (!monitor) {
+      toolbar.translation_x = 0;
+      toolbar.translation_y = 0;
+      return;
+    }
+
+    const [stageX, stageY] = toolbar.get_transformed_position();
+    const translation = calculateToolbarTranslation({
+      monitor,
+      selection: selectionRectangle,
+      toolbar: {
+        width: toolbar.width,
+        height: toolbar.height,
+        stageX,
+        stageY,
+        translationX: toolbar.translation_x,
+        translationY: toolbar.translation_y,
+      },
+      margin: 12,
+    });
+    if (!translation) return;
+
+    toolbar.translation_x = translation.x;
+    toolbar.translation_y = translation.y;
   }
 
   private _setControlsOpacity(opacity: number): void {
diff --git a/src/capture/toolbarPlacement.ts b/src/capture/toolbarPlacement.ts
new file mode 100644
index 0000000..1b30517
--- /dev/null
+++ b/src/capture/toolbarPlacement.ts
@@ -0,0 +1,110 @@
+export type Rectangle = { x: number; y: number; width: number; height: number };
+
+export type ToolbarPlacement = {
+  monitor: Rectangle;
+  selection: Rectangle;
+  toolbar: {
+    width: number;
+    height: number;
+    stageX: number;
+    stageY: number;
+    translationX: number;
+    translationY: number;
+  };
+  margin: number;
+};
+
+export type ToolbarTranslation = { x: number; y: number };
+
+export function findMonitorForSelection(
+  selection: Rectangle,
+  monitors: readonly Rectangle[],
+  primaryIndex: number,
+): Rectangle | null {
+  let selectedMonitor: Rectangle | null = null;
+  let selectedArea = 0;
+
+  for (const monitor of monitors) {
+    if (!isValidRectangle(monitor)) continue;
+    const intersectionWidth = Math.max(
+      0,
+      Math.min(selection.x + selection.width, monitor.x + monitor.width) -
+        Math.max(selection.x, monitor.x),
+    );
+    const intersectionHeight = Math.max(
+      0,
+      Math.min(selection.y + selection.height, monitor.y + monitor.height) -
+        Math.max(selection.y, monitor.y),
+    );
+    const intersectionArea = intersectionWidth * intersectionHeight;
+    if (!Number.isFinite(intersectionArea) || intersectionArea <= selectedArea) continue;
+
+    selectedMonitor = monitor;
+    selectedArea = intersectionArea;
+  }
+
+  if (selectedMonitor) return selectedMonitor;
+  const primaryMonitor = monitors[primaryIndex];
+  if (primaryMonitor && isValidRectangle(primaryMonitor)) return primaryMonitor;
+  return monitors.find(isValidRectangle) ?? null;
+}
+
+export function calculateToolbarTranslation(
+  placement: ToolbarPlacement,
+): ToolbarTranslation | null {
+  const { monitor, selection, toolbar, margin } = placement;
+  const coordinates = [
+    monitor.x,
+    monitor.y,
+    monitor.width,
+    monitor.height,
+    selection.x,
+    selection.y,
+    selection.width,
+    selection.height,
+    toolbar.width,
+    toolbar.height,
+    toolbar.stageX,
+    toolbar.stageY,
+    toolbar.translationX,
+    toolbar.translationY,
+    margin,
+  ];
+  if (!coordinates.every(Number.isFinite)) return null;
+  if (
+    monitor.width <= 0 ||
+    monitor.height <= 0 ||
+    selection.width <= 0 ||
+    selection.height <= 0 ||
+    toolbar.width <= 0 ||
+    toolbar.height <= 0
+  )
+    return null;
+
+  const anchorX = toolbar.stageX - toolbar.translationX;
+  const anchorY = toolbar.stageY - toolbar.translationY;
+  const desiredX = Math.max(
+    monitor.x,
+    Math.min(
+      selection.x + selection.width / 2 - toolbar.width / 2,
+      monitor.x + monitor.width - toolbar.width,
+    ),
+  );
+  let desiredY = selection.y - toolbar.height - margin;
+  if (desiredY < monitor.y) desiredY = selection.y + selection.height + margin;
+  desiredY = Math.max(monitor.y, Math.min(desiredY, monitor.y + monitor.height - toolbar.height));
+
+  const translation = {
+    x: Math.round(desiredX - anchorX),
+    y: Math.round(desiredY - anchorY),
+  };
+  return Number.isFinite(translation.x) && Number.isFinite(translation.y) ? translation : null;
+}
+
+function isValidRectangle(rectangle: Rectangle): boolean {
+  return (
+    [rectangle.x, rectangle.y, rectangle.width, rectangle.height].every(Number.isFinite) &&
+    rectangle.width > 0 &&
+    rectangle.height > 0
+  );
+}
diff --git a/src/clipboard/clipboardItem.ts b/src/clipboard/clipboardItem.ts
index 40caf72..7e47b7b 100644
--- a/src/clipboard/clipboardItem.ts
+++ b/src/clipboard/clipboardItem.ts
@@ -116,7 +116,6 @@ export class ClipboardItem extends St.Button {
   declare private _removeButton: St.Button;
   declare private _menuButton: St.Button;
   declare private _menu: PopupMenu.PopupMenu | null;
-  declare private _disposed: boolean;
   declare private _linkTitle: St.Label | null;
   declare private _linkDescription: St.Label | null;
   declare private _linkThumb: St.Widget | null;
@@ -140,7 +139,6 @@ export class ClipboardItem extends St.Button {
     this._entry = entry;
     this._callbacks = callbacks;
     this._menu = null;
-    this._disposed = false;
     this._linkTitle = null;
     this._linkDescription = null;
     this._linkThumb = null;
@@ -192,8 +190,10 @@ export class ClipboardItem extends St.Button {
   }
 
   override destroy(): void {
-    this._disposed = true;
     this._destroyMenu();
+    this._linkTitle = null;
+    this._linkDescription = null;
+    this._linkThumb = null;
     super.destroy();
   }
 
@@ -317,7 +317,7 @@ export class ClipboardItem extends St.Button {
 
   private async _loadLinkPreview(url: string): Promise<void> {
     const meta = await fetchLinkMetadata(url);
-    if (this._disposed) return;
+    if (!this._linkTitle) return;
 
     if (meta.title && this._linkTitle) {
       this._linkTitle.text = meta.title;
diff --git a/src/core/extensionBase.ts b/src/core/extensionBase.ts
new file mode 100644
index 0000000..c0f4289
--- /dev/null
+++ b/src/core/extensionBase.ts
@@ -0,0 +1,52 @@
+import { Extension } from '@girs/gnome-shell/extensions/extension';
+
+import type { ExtensionContext } from '~/core/context.ts';
+import { DefaultExtensionContext } from '~/core/context.ts';
+import { ConsoleLogger, logger, setGlobalLogger } from '~/core/logger.ts';
+import { GSettingsManager } from '~/core/settings.ts';
+import { DefaultDeviceService } from '~/device/device.ts';
+import { ModuleManager } from '~/moduleManager.ts';
+import type { Module } from '~/module.ts';
+import { getModuleRegistry } from '~/registry.ts';
+import { cleanupIcons, initIcons } from '~/shared/icons.ts';
+
+const LOG_PREFIX = 'AuroraShell';
+
+export class AuroraShellExtensionBase extends Extension {
+  protected _manager: ModuleManager | null = null;
+  protected _context: ExtensionContext | null = null;
+
+  get _modules(): ReadonlyMap<string, Module> {
+    return this._manager?.modules ?? new Map();
+  }
+
+  override enable(): void {
+    const consoleLogger = new ConsoleLogger('Aurora Shell', this.uuid);
+    setGlobalLogger(consoleLogger);
+    consoleLogger.debug('Enabling extension', { prefix: LOG_PREFIX });
+
+    const device = new DefaultDeviceService();
+    this._context = new DefaultExtensionContext(
+      this.uuid,
+      this.path,
+      new GSettingsManager(this.getSettings()),
+      device,
+    );
+
+    initIcons(this.path);
+    this._manager = new ModuleManager(getModuleRegistry(), this._context, {
+      debug: (message) => logger.debug(message, { prefix: LOG_PREFIX }),
+      error: (message) => logger.error(message, { prefix: LOG_PREFIX }),
+    });
+    this._manager.start();
+  }
+
+  override disable(): void {
+    logger.debug('Disabling extension', { prefix: LOG_PREFIX });
+    this._manager?.stop();
+    this._manager = null;
+    this._context?.device.destroy();
+    this._context = null;
+    cleanupIcons();
+  }
+}
diff --git a/src/core/lifecycleScope.ts b/src/core/lifecycleScope.ts
index d3db7c7..76d60ed 100644
--- a/src/core/lifecycleScope.ts
+++ b/src/core/lifecycleScope.ts
@@ -6,11 +6,10 @@ type SignalTarget<Args extends unknown[]> = {
 };
 
 export class LifecycleScope {
-  private _teardowns: Teardown[] = [];
-  private _disposed = false;
+  private _teardowns: Teardown[] | null = [];
 
   onDispose(teardown: Teardown): void {
-    if (this._disposed) {
+    if (!this._teardowns) {
       teardown();
       return;
     }
@@ -27,10 +26,9 @@ export class LifecycleScope {
   }
 
   dispose(): void {
-    if (this._disposed) return;
-    this._disposed = true;
+    if (!this._teardowns) return;
     const teardowns = this._teardowns;
-    this._teardowns = [];
+    this._teardowns = null;
     for (let index = teardowns.length - 1; index >= 0; index--) {
       try {
         teardowns[index]?.();
diff --git a/src/desktop/trayIcons/trayContainer.ts b/src/desktop/trayIcons/trayContainer.ts
index 349497d..0150343 100644
--- a/src/desktop/trayIcons/trayContainer.ts
+++ b/src/desktop/trayIcons/trayContainer.ts
@@ -132,7 +132,17 @@ class TrayClipArea extends Clutter.Actor {
 
   layoutSnapshot(): string {
     const child = this.get_first_child();
-    return `reservedWidth=${Math.round(this.reservedWidth)} actorWidth=${Math.round(this.width)} viewportWidth=${Math.round(this._viewportWidth)} clipStart=${Math.round(this._clipStart)} allocated=${Math.round(this.allocation.x2 - this.allocation.x1)} fullWidth=${Math.round(this.fullWidth)} childOffsetX=${Math.round(this._childOffsetX)} childX=${child ? Math.round(child.x) : 'none'} childWidth=${child ? Math.round(child.width) : 'none'}`;
+    return [
+      `reservedWidth=${Math.round(this.reservedWidth)}`,
+      `actorWidth=${Math.round(this.width)}`,
+      `viewportWidth=${Math.round(this._viewportWidth)}`,
+      `clipStart=${Math.round(this._clipStart)}`,
+      `allocated=${Math.round(this.allocation.x2 - this.allocation.x1)}`,
+      `fullWidth=${Math.round(this.fullWidth)}`,
+      `childOffsetX=${Math.round(this._childOffsetX)}`,
+      `childX=${child ? Math.round(child.x) : 'none'}`,
+      `childWidth=${child ? Math.round(child.width) : 'none'}`,
+    ].join(' ');
   }
 }
 
@@ -525,7 +535,23 @@ export class TrayContainer extends PanelMenu.Button {
 
     if (animated) {
       logger.debug(
-        `Viewport animation collapsed=${this._state.collapsed} count=${count} limit=${this._limit} effectiveLimit=${effectiveLimit} visible=${visibleCount} fullWidth=${fullWidth} reservedWidth=${reservedWidth} availableClipWidth=${availableClipWidth ?? 'none'} fromViewport=${startViewportWidth} toViewport=${targetViewportWidth} fromClipStart=${startClipStart} toClipStart=${targetClipStart} scrollOffset=${this._state.scrollOffset} chevronX=${Math.round(this._chevron.translationX)} ${this._clipArea.layoutSnapshot()}`,
+        [
+          `Viewport animation collapsed=${this._state.collapsed}`,
+          `count=${count}`,
+          `limit=${this._limit}`,
+          `effectiveLimit=${effectiveLimit}`,
+          `visible=${visibleCount}`,
+          `fullWidth=${fullWidth}`,
+          `reservedWidth=${reservedWidth}`,
+          `availableClipWidth=${availableClipWidth ?? 'none'}`,
+          `fromViewport=${startViewportWidth}`,
+          `toViewport=${targetViewportWidth}`,
+          `fromClipStart=${startClipStart}`,
+          `toClipStart=${targetClipStart}`,
+          `scrollOffset=${this._state.scrollOffset}`,
+          `chevronX=${Math.round(this._chevron.translationX)}`,
+          this._clipArea.layoutSnapshot(),
+        ].join(' '),
         { prefix: LOG_PREFIX },
       );
     }
diff --git a/src/desktop/trayIcons/trayIcons.ts b/src/desktop/trayIcons/trayIcons.ts
index b13875c..633a913 100644
--- a/src/desktop/trayIcons/trayIcons.ts
+++ b/src/desktop/trayIcons/trayIcons.ts
@@ -44,7 +44,6 @@ export class TrayIcons extends Module {
   private _dedupBgApps = true;
   private _bgAppsToggle: any = null;
   private _bgAppsGrid: any = null;
-  private _bgAppsGridChildAddedId = 0;
   private _desktopSettings: SettingsManager | null = null;
 
   constructor(context: ExtensionContext) {
@@ -155,6 +154,27 @@ export class TrayIcons extends Module {
     });
   }
 
+  override disable(): void {
+    this._lifecycle?.dispose();
+    this._lifecycle = null;
+    this._desktopSettings = null;
+
+    this._restoreBgAppsQuickSettings();
+
+    this._bgSource?.destroy();
+    this._bgSource = null;
+    this._bgItemAppIds.clear();
+
+    this._sniHost?.destroy();
+    this._sniHost = null;
+
+    this._sniWatcher?.destroy();
+    this._sniWatcher = null;
+
+    this._container?.destroy();
+    this._container = null;
+  }
+
   private _onSniItemAdded(item: TrayItem): void {
     logger.debug(`SNI item added: ${item.id} (menuBus=${item.menuBusName ?? 'none'})`, {
       prefix: LOG_PREFIX,
@@ -390,7 +410,7 @@ export class TrayIcons extends Module {
 
   private _findBgAppsQuickSettingsToggle(): any {
     const quickSettings = Main.panel.statusArea.quickSettings as any;
-    const backgroundAppsItem = quickSettings?._backgroundApps?.quickSettingsItems?.find?.(
+    const backgroundAppsItem = quickSettings?._backgroundApps?.quickSettingsItems?.find(
       (item: any) => this._isBgAppsQuickSettingsToggle(item),
     );
     if (backgroundAppsItem) return backgroundAppsItem;
@@ -417,24 +437,25 @@ export class TrayIcons extends Module {
   private _watchBgAppsQuickSettingsGrid(): void {
     const grid = getQuickSettingsGrid();
     if (!grid) return;
-    if (this._bgAppsGrid === grid && this._bgAppsGridChildAddedId) return;
+    if (this._bgAppsGrid === grid) return;
 
     this._unwatchBgAppsQuickSettingsGrid();
     this._bgAppsGrid = grid;
-    this._bgAppsGridChildAddedId = grid.connect('child-added', () => {
-      this._hideBgAppsQuickSettings();
-    });
+    grid.connectObject(
+      'child-added',
+      () => this._hideBgAppsQuickSettings(),
+      'destroy',
+      () => {
+        if (this._bgAppsGrid === grid) this._bgAppsGrid = null;
+      },
+      this,
+    );
   }
 
   private _unwatchBgAppsQuickSettingsGrid(): void {
-    if (!this._bgAppsGrid || !this._bgAppsGridChildAddedId) return;
-    try {
-      this._bgAppsGrid.disconnect(this._bgAppsGridChildAddedId);
-    } catch {
-      // Quick Settings may be destroyed during Shell shutdown.
-    }
+    if (!this._bgAppsGrid) return;
+    this._bgAppsGrid.disconnectObject(this);
     this._bgAppsGrid = null;
-    this._bgAppsGridChildAddedId = 0;
   }
 
   private _forceHideBgAppsToggle(): void {
@@ -445,33 +466,8 @@ export class TrayIcons extends Module {
   private _restoreBgAppsQuickSettings(): void {
     this._unwatchBgAppsQuickSettingsGrid();
     if (!this._bgAppsToggle) return;
-    try {
-      this._bgAppsToggle.disconnectObject(this);
-    } catch {
-      // Quick Settings may be destroyed during Shell shutdown.
-    }
-    this._bgAppsToggle._syncVisibility?.();
+    this._bgAppsToggle.disconnectObject(this);
+    this._bgAppsToggle._syncVisibility();
     this._bgAppsToggle = null;
   }
-
-  override disable(): void {
-    this._lifecycle?.dispose();
-    this._lifecycle = null;
-    this._desktopSettings = null;
-
-    this._restoreBgAppsQuickSettings();
-
-    this._bgSource?.destroy();
-    this._bgSource = null;
-    this._bgItemAppIds.clear();
-
-    this._sniHost?.destroy();
-    this._sniHost = null;
-
-    this._sniWatcher?.destroy();
-    this._sniWatcher = null;
-
-    this._container?.destroy();
-    this._container = null;
-  }
 }
diff --git a/src/device/device.ts b/src/device/device.ts
index 1baedd5..aafccd0 100644
--- a/src/device/device.ts
+++ b/src/device/device.ts
@@ -32,12 +32,11 @@ const DISPLAY_CONFIG_PATH = '/org/gnome/Mutter/DisplayConfig';
 export class DefaultDeviceService implements DeviceService {
   private readonly _listeners = new Set<DeviceChangeListener>();
   private readonly _seat = Clutter.get_default_backend().get_default_seat();
-  private readonly _monitorChangedId: number;
-  private readonly _deviceAddedId: number;
-  private readonly _deviceRemovedId: number;
-  private readonly _nameWatchIds: number[];
+  private _monitorChangedId: number | null;
+  private _deviceAddedId: number | null;
+  private _deviceRemovedId: number | null;
+  private _nameWatchIds: number[] | null;
   private _snapshot: DeviceSnapshot;
-  private _destroyed = false;
 
   constructor() {
     this._snapshot = this._detect();
@@ -64,7 +63,7 @@ export class DefaultDeviceService implements DeviceService {
   }
 
   refresh(): DeviceSnapshot {
-    if (this._destroyed) return this._snapshot;
+    if (!this._nameWatchIds) return this._snapshot;
     const next = this._detect();
     if (!sameDeviceSnapshot(this._snapshot, next)) {
       this._snapshot = next;
@@ -79,12 +78,15 @@ export class DefaultDeviceService implements DeviceService {
   }
 
   destroy(): void {
-    if (this._destroyed) return;
-    this._destroyed = true;
-    Main.layoutManager.disconnect(this._monitorChangedId);
-    this._seat.disconnect(this._deviceAddedId);
-    this._seat.disconnect(this._deviceRemovedId);
+    if (!this._nameWatchIds) return;
+    if (this._monitorChangedId !== null) Main.layoutManager.disconnect(this._monitorChangedId);
+    if (this._deviceAddedId !== null) this._seat.disconnect(this._deviceAddedId);
+    if (this._deviceRemovedId !== null) this._seat.disconnect(this._deviceRemovedId);
     for (const id of this._nameWatchIds) Gio.bus_unwatch_name(id);
+    this._monitorChangedId = null;
+    this._deviceAddedId = null;
+    this._deviceRemovedId = null;
+    this._nameWatchIds = null;
     this._listeners.clear();
   }
 
diff --git a/src/dock/dock.manifest.ts b/src/dock/dock.manifest.ts
index 570f75a..340c6f9 100644
--- a/src/dock/dock.manifest.ts
+++ b/src/dock/dock.manifest.ts
@@ -40,5 +40,22 @@ export const manifest: ModuleManifest = {
       subtitle: _('Show removable drives in the dock when they are connected'),
       type: 'switch',
     },
+    {
+      key: 'dock-motion-enabled',
+      title: _('Icon Hover &amp; Press Effects'),
+      subtitle: _('Animate dock icons on hover and click'),
+      type: 'switch',
+    },
+    {
+      key: 'dock-motion-profile',
+      title: _('Effect Intensity'),
+      subtitle: _('How strong the hover and press effects are'),
+      type: 'select',
+      choices: [
+        { value: 'subtle', title: _('Subtle') },
+        { value: 'balanced', title: _('Balanced') },
+        { value: 'expressive', title: _('Expressive') },
+      ],
+    },
   ],
 };
diff --git a/src/dock/dock.ts b/src/dock/dock.ts
index 7e87138..8e7ef22 100644
--- a/src/dock/dock.ts
+++ b/src/dock/dock.ts
@@ -14,6 +14,8 @@ import { AuroraDash, type DashBounds } from '~/shared/ui/dash.ts';
 import { DockHotArea } from '~/dock/hotArea.ts';
 import { DockIntellihide, OverlapStatus } from '~/dock/intellihide.ts';
 import { getDockMonitorIndexes } from '~/dock/monitorTopology.ts';
+import { DEFAULT_PROFILE, getBuiltInRecipe } from '~/dock/motion/catalog.ts';
+import { DashMotionIntegration } from '~/dock/motion/dashMotionIntegration.ts';
 
 const HOT_AREA_REVEAL_DURATION = 1500;
 const HOT_AREA_STRIP_HEIGHT = 1;
@@ -30,6 +32,7 @@ export type ManagedDockBinding = {
   autoHideReleaseId: number;
   hotAreaEnableId: number;
   hotAreaActive: boolean;
+  motion: DashMotionIntegration;
 };
 
 export class Dock extends Module {
@@ -42,6 +45,8 @@ export class Dock extends Module {
   private _showOnAllMonitors = false;
   private _showTrash = true;
   private _showExternalStorage = true;
+  private _motionEnabled = true;
+  private _motionProfile: string = DEFAULT_PROFILE;
 
   constructor(context: ExtensionContext) {
     super(context);
@@ -60,8 +65,17 @@ export class Dock extends Module {
     this._showTrash = this._dockSettings?.get_boolean('dock-show-trash') ?? true;
     this._showExternalStorage =
       this._dockSettings?.get_boolean('dock-show-external-storage') ?? true;
+    this._motionEnabled = this._dockSettings?.get_boolean('dock-motion-enabled') ?? true;
+    this._motionProfile = this._dockSettings?.get_string('dock-motion-profile') ?? DEFAULT_PROFILE;
     logger.debug(
-      `enable alwaysShow=${this._alwaysShow} intellihide=${this._intellihideEnabled} showOnAllMonitors=${this._showOnAllMonitors} showTrash=${this._showTrash} showExternalStorage=${this._showExternalStorage} monitors=${Main.layoutManager.monitors?.length ?? 0}`,
+      [
+        `enable alwaysShow=${this._alwaysShow}`,
+        `intellihide=${this._intellihideEnabled}`,
+        `showOnAllMonitors=${this._showOnAllMonitors}`,
+        `showTrash=${this._showTrash}`,
+        `showExternalStorage=${this._showExternalStorage}`,
+        `monitors=${Main.layoutManager.monitors?.length ?? 0}`,
+      ].join(' '),
       { prefix: LOG_PREFIX },
     );
 
@@ -94,7 +108,7 @@ export class Dock extends Module {
     );
     this._lifecycle.onDispose(() => Main.overview.disconnectObject(this));
 
-    this._dockSettings?.connectObject?.(
+    this._dockSettings?.connectObject(
       'changed::dock-always-show',
       () => {
         this._alwaysShow = this._dockSettings?.get_boolean('dock-always-show') ?? false;
@@ -130,12 +144,31 @@ export class Dock extends Module {
           this._dockSettings?.get_boolean('dock-show-external-storage') ?? true;
         this._rebuildBindings();
       },
+      'changed::dock-motion-enabled',
+      () => {
+        this._motionEnabled = this._dockSettings?.get_boolean('dock-motion-enabled') ?? true;
+        this._bindings.forEach((b) => b.motion.setEnabled(this._motionEnabled));
+      },
+      'changed::dock-motion-profile',
+      () => {
+        this._motionProfile =
+          this._dockSettings?.get_string('dock-motion-profile') ?? DEFAULT_PROFILE;
+        const recipe = getBuiltInRecipe(this._motionProfile);
+        this._bindings.forEach((b) => b.motion.setRecipe(recipe));
+      },
+      'changed::module-pip-on-top',
+      () => {
+        const enabled = this._dockSettings?.get_boolean('module-pip-on-top') ?? false;
+        this._bindings.forEach((binding) =>
+          binding.intellihide?.setExcludePipFromSmartReveal(enabled),
+        );
+      },
       this,
     );
 
     this.context.signals.connectObject('icons-woven', () => this._refreshBindingsLayout(), this);
     this._lifecycle.onDispose(() => this.context.signals.disconnectObject(this));
-    this._lifecycle.onDispose(() => this._dockSettings?.disconnectObject?.(this));
+    this._lifecycle.onDispose(() => this._dockSettings?.disconnectObject(this));
   }
 
   override disable(): void {
@@ -235,8 +268,18 @@ export class Dock extends Module {
     const monitors: DashBounds[] = Main.layoutManager.monitors ?? [];
     const primaryIndex = Main.layoutManager.primaryIndex;
     const monitorIndexes = getDockMonitorIndexes(monitors, primaryIndex, this._showOnAllMonitors);
+    const monitorSummary = monitors
+      .map(
+        (monitor, index) => `${index}:${monitor.x},${monitor.y} ${monitor.width}x${monitor.height}`,
+      )
+      .join(';');
     logger.debug(
-      `rebuild primary=${primaryIndex} showOnAllMonitors=${this._showOnAllMonitors} selected=[${monitorIndexes.join(',')}] monitors=[${monitors.map((monitor, index) => `${index}:${monitor.x},${monitor.y} ${monitor.width}x${monitor.height}`).join(';')}]`,
+      [
+        `rebuild primary=${primaryIndex}`,
+        `showOnAllMonitors=${this._showOnAllMonitors}`,
+        `selected=[${monitorIndexes.join(',')}]`,
+        `monitors=[${monitorSummary}]`,
+      ].join(' '),
       { prefix: LOG_PREFIX },
     );
     monitorIndexes.forEach((monitorIndex) => {
@@ -287,6 +330,9 @@ export class Dock extends Module {
     container.set_child(dash);
     dash.attachToContainer(container);
 
+    const motion = new DashMotionIntegration(getBuiltInRecipe(this._motionProfile));
+    motion.attach(dash, this._motionEnabled);
+
     const binding: ManagedDockBinding = {
       monitorIndex,
       mode,
@@ -298,6 +344,7 @@ export class Dock extends Module {
       autoHideReleaseId: 0,
       hotAreaEnableId: 0,
       hotAreaActive: false,
+      motion,
     };
     logger.debug(
       `monitor=${monitorIndex} binding created geometry=${monitor.x},${monitor.y} ${monitor.width}x${monitor.height} mode=${mode}`,
@@ -322,7 +369,10 @@ export class Dock extends Module {
         return binding;
       }
 
-      const intellihide = new DockIntellihide(monitorIndex);
+      const intellihide = new DockIntellihide(
+        monitorIndex,
+        this._dockSettings?.get_boolean('module-pip-on-top') ?? false,
+      );
       binding.intellihide = intellihide;
       dash.setTargetBoxListener((box) => intellihide.updateTargetBox(box));
 
@@ -475,9 +525,9 @@ export class Dock extends Module {
     }
     this._clearHotAreaEnable(binding);
 
-    binding.intellihide?.disconnectObject?.(this);
-    binding.hotArea?.disconnectObject?.(this);
-    binding.container.disconnectObject?.(this);
+    binding.intellihide?.disconnectObject(this);
+    binding.hotArea?.disconnectObject(this);
+    binding.container.disconnectObject(this);
 
     if (binding.hotArea) {
       Main.layoutManager.removeChrome?.(binding.hotArea);
@@ -492,6 +542,7 @@ export class Dock extends Module {
     }
 
     binding.intellihide?.destroy();
+    binding.motion.dispose();
     binding.dash.detachFromContainer();
     binding.dash.destroy();
 
diff --git a/src/dock/externalStorageIcon.ts b/src/dock/externalStorageIcon.ts
index 564b0fd..7ae6821 100644
--- a/src/dock/externalStorageIcon.ts
+++ b/src/dock/externalStorageIcon.ts
@@ -208,8 +208,8 @@ export const ExternalStorageIcon = GObject.registerClass(
     declare private _menuManager: PopupMenu.PopupMenuManager | null;
     declare private _openItem: PopupMenu.PopupMenuItem | null;
     declare private _ejectItem: PopupMenu.PopupMenuItem | null;
+    declare private _operationCancellable: Gio.Cancellable | null;
     declare private _busy: boolean;
-    declare private _destroyed: boolean;
 
     override _init(item?: ExternalStorageItem): void {
       super._init();
@@ -222,8 +222,8 @@ export const ExternalStorageIcon = GObject.registerClass(
       this._menuManager = null;
       this._openItem = null;
       this._ejectItem = null;
+      this._operationCancellable = new Gio.Cancellable();
       this._busy = false;
-      this._destroyed = false;
 
       this.toggleButton = new St.Button({
         style_class: 'show-apps',
@@ -261,14 +261,25 @@ export const ExternalStorageIcon = GObject.registerClass(
         },
         this,
       );
-
-      this.connect('destroy', () => this._onDestroy());
     }
 
     setIconSize(size: number): void {
       this.icon.setIconSize(size);
     }
 
+    override destroy(): void {
+      this._operationCancellable?.cancel();
+      this._operationCancellable = null;
+      this.toggleButton.disconnectObject(this);
+      this._menu?.destroy();
+      this._menu = null;
+      this._menuManager = null;
+      this._openItem = null;
+      this._ejectItem = null;
+      this._iconActor = null;
+      super.destroy();
+    }
+
     get menuIsOpen(): boolean {
       return this._menu?.isOpen ?? false;
     }
@@ -316,31 +327,32 @@ export const ExternalStorageIcon = GObject.registerClass(
     }
 
     private async _openAsync(): Promise<void> {
-      if (this._busy || this._destroyed) return;
+      const cancellable = this._operationCancellable;
+      if (this._busy || !cancellable) return;
       this._setBusy(true);
 
       try {
-        const mount = await this._ensureMounted();
+        const mount = await this._ensureMounted(cancellable);
         if (!mount) throw new Error('Volume is not mounted');
 
         const uri = mount.get_root().get_uri();
         const launchContext = global.create_app_launch_context(global.get_current_time(), -1);
-        await this._launchUri(uri, launchContext);
+        await this._launchUri(uri, launchContext, cancellable);
       } catch (error) {
         this._reportFailure(_('Failed to open “%s”').format(this._item.name), error);
       } finally {
-        this._setBusy(false);
+        if (this._operationCancellable === cancellable) this._setBusy(false);
       }
     }
 
-    private async _ensureMounted(): Promise<Gio.Mount | null> {
+    private async _ensureMounted(cancellable: Gio.Cancellable): Promise<Gio.Mount | null> {
       const currentMount = this._item.volume?.get_mount() ?? this._item.mount;
       if (currentMount) return currentMount;
       if (!this._item.volume?.can_mount()) return null;
 
       const operation = new ShellMountOperation.ShellMountOperation(this._item.volume);
       try {
-        await this._mountVolume(this._item.volume, operation.mountOp);
+        await this._mountVolume(this._item.volume, operation.mountOp, cancellable);
         return this._item.volume.get_mount();
       } finally {
         operation.close();
@@ -352,7 +364,8 @@ export const ExternalStorageIcon = GObject.registerClass(
     }
 
     private async _ejectAsync(): Promise<void> {
-      if (this._busy || this._destroyed || !this._canUnmountOrEject()) return;
+      const cancellable = this._operationCancellable;
+      if (this._busy || !cancellable || !this._canUnmountOrEject()) return;
       this._setBusy(true);
 
       try {
@@ -361,21 +374,21 @@ export const ExternalStorageIcon = GObject.registerClass(
         if (mount?.can_eject()) {
           const operation = new ShellMountOperation.ShellMountOperation(mount);
           try {
-            await this._ejectMount(mount, operation.mountOp);
+            await this._ejectMount(mount, operation.mountOp, cancellable);
           } finally {
             operation.close();
           }
         } else if (mount?.can_unmount()) {
           const operation = new ShellMountOperation.ShellMountOperation(mount);
           try {
-            await this._unmountMount(mount, operation.mountOp);
+            await this._unmountMount(mount, operation.mountOp, cancellable);
           } finally {
             operation.close();
           }
         } else if (this._item.volume?.can_eject()) {
           const operation = new ShellMountOperation.ShellMountOperation(this._item.volume);
           try {
-            await this._ejectVolume(this._item.volume, operation.mountOp);
+            await this._ejectVolume(this._item.volume, operation.mountOp, cancellable);
           } finally {
             operation.close();
           }
@@ -383,7 +396,7 @@ export const ExternalStorageIcon = GObject.registerClass(
       } catch (error) {
         this._reportFailure(_('Failed to eject “%s”').format(this._item.name), error);
       } finally {
-        this._setBusy(false);
+        if (this._operationCancellable === cancellable) this._setBusy(false);
       }
     }
 
@@ -401,22 +414,35 @@ export const ExternalStorageIcon = GObject.registerClass(
       return mount?.can_eject() === true || this._item.volume?.can_eject() === true;
     }
 
-    private _launchUri(uri: string, launchContext: Gio.AppLaunchContext): Promise<void> {
+    private _launchUri(
+      uri: string,
+      launchContext: Gio.AppLaunchContext,
+      cancellable: Gio.Cancellable,
+    ): Promise<void> {
       return new Promise((resolve, reject) => {
-        Gio.app_info_launch_default_for_uri_async(uri, launchContext, null, (_source, result) => {
-          try {
-            Gio.app_info_launch_default_for_uri_finish(result);
-            resolve();
-          } catch (error) {
-            reject(error);
-          }
-        });
+        Gio.app_info_launch_default_for_uri_async(
+          uri,
+          launchContext,
+          cancellable,
+          (_source, result) => {
+            try {
+              Gio.app_info_launch_default_for_uri_finish(result);
+              resolve();
+            } catch (error) {
+              reject(error);
+            }
+          },
+        );
       });
     }
 
-    private _mountVolume(volume: Gio.Volume, mountOperation: Gio.MountOperation): Promise<void> {
+    private _mountVolume(
+      volume: Gio.Volume,
+      mountOperation: Gio.MountOperation,
+      cancellable: Gio.Cancellable,
+    ): Promise<void> {
       return new Promise((resolve, reject) => {
-        volume.mount(Gio.MountMountFlags.NONE, mountOperation, null, (_source, result) => {
+        volume.mount(Gio.MountMountFlags.NONE, mountOperation, cancellable, (_source, result) => {
           try {
             volume.mount_finish(result);
             resolve();
@@ -427,12 +453,16 @@ export const ExternalStorageIcon = GObject.registerClass(
       });
     }
 
-    private _ejectMount(mount: Gio.Mount, mountOperation: Gio.MountOperation): Promise<void> {
+    private _ejectMount(
+      mount: Gio.Mount,
+      mountOperation: Gio.MountOperation,
+      cancellable: Gio.Cancellable,
+    ): Promise<void> {
       return new Promise((resolve, reject) => {
         mount.eject_with_operation(
           Gio.MountUnmountFlags.NONE,
           mountOperation,
-          null,
+          cancellable,
           (_source, result) => {
             try {
               mount.eject_with_operation_finish(result);
@@ -445,12 +475,16 @@ export const ExternalStorageIcon = GObject.registerClass(
       });
     }
 
-    private _unmountMount(mount: Gio.Mount, mountOperation: Gio.MountOperation): Promise<void> {
+    private _unmountMount(
+      mount: Gio.Mount,
+      mountOperation: Gio.MountOperation,
+      cancellable: Gio.Cancellable,
+    ): Promise<void> {
       return new Promise((resolve, reject) => {
         mount.unmount_with_operation(
           Gio.MountUnmountFlags.NONE,
           mountOperation,
-          null,
+          cancellable,
           (_source, result) => {
             try {
               mount.unmount_with_operation_finish(result);
@@ -463,12 +497,16 @@ export const ExternalStorageIcon = GObject.registerClass(
       });
     }
 
-    private _ejectVolume(volume: Gio.Volume, mountOperation: Gio.MountOperation): Promise<void> {
+    private _ejectVolume(
+      volume: Gio.Volume,
+      mountOperation: Gio.MountOperation,
+      cancellable: Gio.Cancellable,
+    ): Promise<void> {
       return new Promise((resolve, reject) => {
         volume.eject_with_operation(
           Gio.MountUnmountFlags.NONE,
           mountOperation,
-          null,
+          cancellable,
           (_source, result) => {
             try {
               volume.eject_with_operation_finish(result);
@@ -503,17 +541,6 @@ export const ExternalStorageIcon = GObject.registerClass(
         maybeGioError?.matches?.(Gio.IOErrorEnum, Gio.IOErrorEnum.CANCELLED) === true
       );
     }
-
-    private _onDestroy(): void {
-      this._destroyed = true;
-      this.toggleButton.disconnectObject(this);
-      this._menu?.destroy();
-      this._menu = null;
-      this._menuManager = null;
-      this._openItem = null;
-      this._ejectItem = null;
-      this._iconActor = null;
-    }
   },
 );
 
diff --git a/src/dock/hotArea.ts b/src/dock/hotArea.ts
index 6bde686..398ca85 100644
--- a/src/dock/hotArea.ts
+++ b/src/dock/hotArea.ts
@@ -24,7 +24,7 @@ export class DockHotArea extends St.Widget {
   private _pressureBarrier: Layout.PressureBarrier | null = null;
   private _horizontalBarrier: Meta.Barrier | null = null;
   private _monitor!: DashBounds;
-  private _enabled = true;
+  private _active = true;
   private _edgeArmed = true;
   private _grabSuppressed = false;
   private _pointerDwellTimeoutId = 0;
@@ -80,7 +80,7 @@ export class DockHotArea extends St.Widget {
       'leave-event',
       () => {
         this._clearDebounceTimer();
-        if (this._enabled && !this._grabSuppressed && !this._edgeArmed) {
+        if (this._active && !this._grabSuppressed && !this._edgeArmed) {
           this._edgeArmed = true;
           logger.debug(`rearmed after pointer leave geometry=${this._formatGeometry()}`, {
             prefix: LOG_PREFIX,
@@ -104,7 +104,7 @@ export class DockHotArea extends St.Widget {
       (_d: any, _w: any, op: Meta.GrabOp) => {
         if (op === Meta.GrabOp.MOVING) {
           this._grabSuppressed = false;
-          if (this._enabled) this._edgeArmed = !this._isPointerInsideHotArea();
+          if (this._active) this._edgeArmed = !this._isPointerInsideHotArea();
         }
       },
       this,
@@ -113,12 +113,12 @@ export class DockHotArea extends St.Widget {
 
   setGeometry(monitor: DashBounds): void {
     this._monitor = monitor;
-    if (this._enabled) this._rebuildBarrier(monitor.width);
+    if (this._active) this._rebuildBarrier(monitor.width);
   }
 
   setEnabled(enabled: boolean): void {
-    if (enabled === this._enabled && enabled === this.reactive) return;
-    this._enabled = enabled;
+    if (enabled === this._active && enabled === this.reactive) return;
+    this._active = enabled;
     this.set_reactive(enabled);
     if (enabled) {
       this._edgeArmed = !this._isPointerInsideHotArea() && !this._grabSuppressed;
@@ -141,8 +141,8 @@ export class DockHotArea extends St.Widget {
     this._destroyBarrier();
     this._clearDebounceTimer();
 
-    this._pressureBarrier?.disconnectObject?.(this);
-    this._pressureBarrier?.destroy?.();
+    this._pressureBarrier?.disconnectObject(this);
+    this._pressureBarrier?.destroy();
     this._pressureBarrier = null;
 
     super.destroy();
@@ -186,7 +186,7 @@ export class DockHotArea extends St.Widget {
   }
 
   private _canTrigger(): boolean {
-    return this._enabled && this._edgeArmed && !this._grabSuppressed;
+    return this._active && this._edgeArmed && !this._grabSuppressed;
   }
 
   private _isPointerInsideHotArea(): boolean {
diff --git a/src/dock/intellihide.ts b/src/dock/intellihide.ts
index cc2114d..4754af9 100644
--- a/src/dock/intellihide.ts
+++ b/src/dock/intellihide.ts
@@ -12,6 +12,7 @@ import {
   isOnActiveWorkspace,
   rectanglesOverlap,
 } from '~/dock/intellihideState.ts';
+import { isPipTitle } from '~/patches/pipWindowPolicy.ts';
 import type { DashBounds } from '~/shared/ui/dash.ts';
 
 const LOG_PREFIX = 'DockIntellihide';
@@ -48,6 +49,7 @@ const TRACKED_WINDOW_SIGNALS = [
   'notify::maximized-vertically',
   'notify::minimized',
   'notify::on-all-workspaces',
+  'notify::title',
 ] as const;
 
 export enum OverlapStatus {
@@ -66,13 +68,15 @@ export class DockIntellihide extends GObject.Object {
   private _pendingStatus: OverlapStatus = OverlapStatus.CLEAR;
   private _pendingReason = '';
   private _pendingRectangles: Array<{ x: number; y: number; width: number; height: number }> = [];
+  private _excludePipFromSmartReveal = false;
   declare private _trackedWindowActors: Set<any>;
   declare private _trackedWindows: Set<Meta.Window>;
   declare private _queuedRefreshIds: Set<number>;
 
-  override _init(monitorIndex: number) {
+  override _init(monitorIndex: number, excludePipFromSmartReveal = false) {
     super._init();
     this._monitorIndex = monitorIndex;
+    this._excludePipFromSmartReveal = excludePipFromSmartReveal;
     this._trackedWindowActors = new Set<any>();
     this._trackedWindows = new Set<Meta.Window>();
     this._queuedRefreshIds = new Set<number>();
@@ -136,6 +140,13 @@ export class DockIntellihide extends GObject.Object {
     this._checkOverlap(reason, force);
   }
 
+  setExcludePipFromSmartReveal(enabled: boolean): void {
+    if (this._excludePipFromSmartReveal === enabled) return;
+
+    this._excludePipFromSmartReveal = enabled;
+    this._queueRefresh('pip-smart-reveal-policy-changed', [0, 100]);
+  }
+
   destroy(): void {
     this._cancelPendingStatus();
     for (const id of this._queuedRefreshIds) {
@@ -176,6 +187,7 @@ export class DockIntellihide extends GObject.Object {
         focused: focusedWindow === window,
         topmost: index === candidates.length - 1,
         fullscreen: window.is_fullscreen(),
+        excludedFromSmartReveal: this._excludePipFromSmartReveal && isPipTitle(window.get_title()),
       })),
       this._targetBox,
       global.display.get_monitor_in_fullscreen(this._monitorIndex),
@@ -321,8 +333,19 @@ export class DockIntellihide extends GObject.Object {
     const oldStatus = this._status === null ? 'UNKNOWN' : OverlapStatus[this._status];
     this._status = newStatus;
     const workspace = global.workspace_manager.get_active_workspace_index();
+    const rectangleSummary = rectangles
+      .map((rectangle) => this._formatRectangle(rectangle))
+      .join(';');
     logger.debug(
-      `monitor=${this._monitorIndex} workspace=${workspace} ${oldStatus}->${OverlapStatus[newStatus]} reason=${reason}${force ? ' force=true' : ''} target=${this._formatRectangle(this._targetBox)} candidates=${rectangles.length} rects=[${rectangles.map((rectangle) => this._formatRectangle(rectangle)).join(';')}]`,
+      [
+        `monitor=${this._monitorIndex}`,
+        `workspace=${workspace}`,
+        `${oldStatus}->${OverlapStatus[newStatus]}`,
+        `reason=${reason}${force ? ' force=true' : ''}`,
+        `target=${this._formatRectangle(this._targetBox)}`,
+        `candidates=${rectangles.length}`,
+        `rects=[${rectangleSummary}]`,
+      ].join(' '),
       { prefix: LOG_PREFIX },
     );
     this.emit('status-changed');
@@ -391,7 +414,7 @@ export class DockIntellihide extends GObject.Object {
 
   private _safeDisconnect(target: unknown): void {
     try {
-      (target as { disconnectObject?: (object: unknown) => void }).disconnectObject?.(this);
+      (target as { disconnectObject: (object: unknown) => void }).disconnectObject(this);
     } catch {
       // The object may already be disposed or unmanaged by Shell.
     }
diff --git a/src/dock/intellihideState.ts b/src/dock/intellihideState.ts
index a3d6b41..16d5dd7 100644
--- a/src/dock/intellihideState.ts
+++ b/src/dock/intellihideState.ts
@@ -10,6 +10,7 @@ export interface OverlapCandidate {
   focused?: boolean;
   topmost?: boolean;
   fullscreen?: boolean;
+  excludedFromSmartReveal?: boolean;
 }
 
 export interface BlockingOverlapState {
@@ -44,28 +45,42 @@ export function hasOverlap(rectangles: Rectangle[], target: Rectangle): boolean
 /**
  * Computes the windows that are allowed to block intellihide.
  *
- * If a candidate window is focused, only that focused window is considered.
- * If focus is on another monitor, only the topmost window on this monitor is
- * considered. This prevents a fullscreen/maximized background window from
- * keeping the dock hidden while a small window is visibly above it.
+ * If an eligible candidate window is focused, only that focused window is
+ * considered. If focus is on another monitor, only the topmost eligible window
+ * on this monitor is considered. This prevents a fullscreen/maximized
+ * background window from keeping the dock hidden while a small window is
+ * visibly above it.
+ *
+ * Windows excluded from the smart-reveal exception (such as PiP) are skipped
+ * while selecting that foreground window. The next eligible window underneath
+ * remains authoritative, so a fullscreen background still keeps the dock
+ * hidden. If every candidate is excluded, the dock remains hidden: an excluded
+ * foreground window must never become the reason for revealing it.
  */
 export function getBlockingOverlapState(
   candidates: OverlapCandidate[],
   target: Rectangle | null,
   monitorFullscreen: boolean,
 ): BlockingOverlapState {
-  const focusedCandidates = candidates.filter((candidate) => candidate.focused === true);
-  const topmostCandidate = candidates.find((candidate) => candidate.topmost === true);
+  const smartRevealCandidates = candidates.filter(
+    (candidate) => candidate.excludedFromSmartReveal !== true,
+  );
+  const focusedCandidates = smartRevealCandidates.filter((candidate) => candidate.focused === true);
+  const hasExplicitTopmostCandidate = candidates.some((candidate) => candidate.topmost === true);
+  const topmostCandidate = hasExplicitTopmostCandidate ? smartRevealCandidates.at(-1) : undefined;
   const blockingCandidates =
     focusedCandidates.length > 0
       ? focusedCandidates
       : topmostCandidate
         ? [topmostCandidate]
-        : candidates;
+        : smartRevealCandidates.length > 0
+          ? smartRevealCandidates
+          : candidates;
   const rectangles = blockingCandidates.map((candidate) => candidate.rectangle);
   const hasExclusiveWindow =
     blockingCandidates.some((candidate) => candidate.fullscreen === true) ||
-    (blockingCandidates.length === 0 && monitorFullscreen);
+    (blockingCandidates.length === 0 && monitorFullscreen) ||
+    (candidates.length > 0 && smartRevealCandidates.length === 0);
 
   return {
     blocked: hasExclusiveWindow || (target !== null && hasOverlap(rectangles, target)),
diff --git a/src/dock/motion/catalog.ts b/src/dock/motion/catalog.ts
new file mode 100644
index 0000000..fcc8193
--- /dev/null
+++ b/src/dock/motion/catalog.ts
@@ -0,0 +1,140 @@
+// Dock icon hover/press motion recipes, ported from d2d-companion's
+// lib/motion/catalog.js (Subtle/Balanced/Expressive; "Balanced" is the
+// profile that shipped as "Lively" in d2d-companion 0.1.0-beta.1). The
+// launch effect from the source project is intentionally not ported here.
+
+export const Profile = Object.freeze({
+  SUBTLE: 'subtle',
+  BALANCED: 'balanced',
+  EXPRESSIVE: 'expressive',
+});
+export type ProfileId = (typeof Profile)[keyof typeof Profile];
+
+export const PressMode = Object.freeze({
+  LAUNCHES_ONLY: 'launches-only',
+  ALL_PRIMARY_CLICKS: 'all-primary-clicks',
+});
+export type PressModeId = (typeof PressMode)[keyof typeof PressMode];
+
+export const PressEffect = Object.freeze({
+  SQUASH: 'squash',
+  DIM: 'dim',
+});
+export type PressEffectId = (typeof PressEffect)[keyof typeof PressEffect];
+
+export const Easing = Object.freeze({
+  LINEAR: 'linear',
+  EASE_OUT_QUAD: 'ease-out-quad',
+  EASE_OUT_CUBIC: 'ease-out-cubic',
+  EASE_OUT_BACK: 'ease-out-back',
+});
+export type EasingId = (typeof Easing)[keyof typeof Easing];
+
+// The gschema range mirrors these bounds; keep them in sync.
+export const NeighborRadius = Object.freeze({ MIN: 1, MAX: 3 });
+
+export const DEFAULT_PROFILE: ProfileId = Profile.SUBTLE;
+
+export interface HoverRecipe {
+  enabled: boolean;
+  scale: number;
+  lift: number;
+  duration: number;
+  easing: EasingId;
+  neighborScale: number;
+  neighborRadius: number;
+}
+
+export interface PressRecipe {
+  enabled: boolean;
+  mode: PressModeId;
+  effect: PressEffectId;
+  intensity: number;
+  duration: number;
+}
+
+export interface MotionRecipe {
+  id: ProfileId;
+  hover: HoverRecipe;
+  press: PressRecipe;
+}
+
+const BUILTIN_RECIPES: Readonly<Record<ProfileId, MotionRecipe>> = deepFreeze({
+  [Profile.SUBTLE]: {
+    id: Profile.SUBTLE,
+    hover: {
+      enabled: true,
+      scale: 1.05,
+      lift: 0,
+      duration: 150,
+      easing: Easing.EASE_OUT_QUAD,
+      neighborScale: 1,
+      neighborRadius: 1,
+    },
+    press: {
+      enabled: true,
+      mode: PressMode.ALL_PRIMARY_CLICKS,
+      effect: PressEffect.DIM,
+      intensity: 0.2,
+      duration: 90,
+    },
+  },
+  [Profile.BALANCED]: {
+    id: Profile.BALANCED,
+    hover: {
+      enabled: true,
+      scale: 1.1,
+      lift: 0,
+      duration: 180,
+      easing: Easing.EASE_OUT_CUBIC,
+      neighborScale: 1,
+      neighborRadius: 1,
+    },
+    press: {
+      enabled: true,
+      mode: PressMode.LAUNCHES_ONLY,
+      effect: PressEffect.SQUASH,
+      intensity: 0.35,
+      duration: 90,
+    },
+  },
+  [Profile.EXPRESSIVE]: {
+    id: Profile.EXPRESSIVE,
+    hover: {
+      enabled: true,
+      scale: 1.15,
+      lift: 0,
+      duration: 210,
+      easing: Easing.EASE_OUT_CUBIC,
+      neighborScale: 1,
+      neighborRadius: 1,
+    },
+    press: {
+      enabled: true,
+      mode: PressMode.ALL_PRIMARY_CLICKS,
+      effect: PressEffect.SQUASH,
+      intensity: 0.55,
+      duration: 120,
+    },
+  },
+} satisfies Record<ProfileId, MotionRecipe>);
+
+export function isBuiltInProfile(profile: string): profile is ProfileId {
+  return Object.hasOwn(BUILTIN_RECIPES, profile);
+}
+
+export function getBuiltInRecipe(profile: string): MotionRecipe {
+  const selected = isBuiltInProfile(profile) ? profile : DEFAULT_PROFILE;
+  return clone(BUILTIN_RECIPES[selected]);
+}
+
+function clone(value: MotionRecipe): MotionRecipe {
+  return JSON.parse(JSON.stringify(value)) as MotionRecipe;
+}
+
+function deepFreeze<T>(value: T): T {
+  for (const child of Object.values(value as Record<string, unknown>)) {
+    if (child && typeof child === 'object') deepFreeze(child);
+  }
+  return Object.freeze(value);
+}
diff --git a/src/dock/motion/dashMotionIntegration.ts b/src/dock/motion/dashMotionIntegration.ts
new file mode 100644
index 0000000..0fa7c8f
--- /dev/null
+++ b/src/dock/motion/dashMotionIntegration.ts
@@ -0,0 +1,80 @@
+// Attaches dock icon hover/press motion to an AuroraDash, replacing
+// d2d-companion's lib/runtime/dashIntegration.js. aurora-shell always has
+// exactly one AuroraDash target per binding (no "is this a dock or the
+// stock overview dash" guard needed, unlike the source project).
+
+import type St from '@girs/st-18';
+
+import type { MotionRecipe } from '~/dock/motion/catalog.ts';
+import { MotionSurface } from '~/dock/motion/motionSurface.ts';
+import type { AuroraDash } from '~/shared/ui/dash.ts';
+
+interface DashBoxInternals {
+  _box?: St.Widget;
+  _dashContainer?: St.Widget;
+}
+
+export class DashMotionIntegration {
+  private _dash: AuroraDash | null = null;
+  private _box: St.Widget | null = null;
+  private _savedClip = false;
+  private _surface: MotionSurface | null = null;
+  private _recipe: MotionRecipe;
+
+  constructor(recipe: MotionRecipe) {
+    this._recipe = recipe;
+  }
+
+  attach(dash: AuroraDash, enabled: boolean): void {
+    this._dash = dash;
+    if (enabled) this._start();
+  }
+
+  setEnabled(enabled: boolean): void {
+    if (enabled) this._start();
+    else this._stop();
+  }
+
+  setRecipe(recipe: MotionRecipe): void {
+    this._recipe = recipe;
+    this._surface?.setRecipe(recipe);
+  }
+
+  dispose(): void {
+    this._stop();
+    this._dash = null;
+  }
+
+  private _start(): void {
+    if (this._surface || !this._dash) return;
+    const internals = this._dash as unknown as DashBoxInternals;
+    const box = internals._box;
+    const dashContainer = internals._dashContainer;
+    if (!box) return;
+
+    this._box = box;
+    // The dash clips icons to their row; hover motion needs to overflow it.
+    this._savedClip = box.clip_to_allocation;
+    box.clip_to_allocation = false;
+
+    this._surface = new MotionSurface({
+      recipe: this._recipe,
+      getOrderedContainers: () => {
+        if (!dashContainer) return box.get_children();
+        return dashContainer
+          .get_children()
+          .flatMap((container) => (container === box ? box.get_children() : [container]));
+      },
+    });
+    this._surface.addContainerSource(box);
+    if (dashContainer && dashContainer !== box) this._surface.addContainerSource(dashContainer);
+  }
+
+  private _stop(): void {
+    if (!this._surface) return;
+    this._surface.dispose();
+    this._surface = null;
+    if (this._box) this._box.clip_to_allocation = this._savedClip;
+    this._box = null;
+  }
+}
diff --git a/src/dock/motion/easing.ts b/src/dock/motion/easing.ts
new file mode 100644
index 0000000..e0f6d6b
--- /dev/null
+++ b/src/dock/motion/easing.ts
@@ -0,0 +1,20 @@
+import type Clutter from '@girs/clutter-18';
+
+import { Easing, type EasingId } from '~/dock/motion/catalog.ts';
+
+export function resolveAnimationMode(
+  easing: EasingId,
+  animationMode: typeof Clutter.AnimationMode,
+): Clutter.AnimationMode {
+  switch (easing) {
+    case Easing.LINEAR:
+      return animationMode.LINEAR;
+    case Easing.EASE_OUT_QUAD:
+      return animationMode.EASE_OUT_QUAD;
+    case Easing.EASE_OUT_BACK:
+      return animationMode.EASE_OUT_BACK;
+    case Easing.EASE_OUT_CUBIC:
+    default:
+      return animationMode.EASE_OUT_CUBIC;
+  }
+}
diff --git a/src/dock/motion/iconMotionController.ts b/src/dock/motion/iconMotionController.ts
new file mode 100644
index 0000000..0b1e6e2
--- /dev/null
+++ b/src/dock/motion/iconMotionController.ts
@@ -0,0 +1,419 @@
+// Per-icon hover/press motion controller, ported from d2d-companion's
+// lib/runtime/iconMotionController.js. The launch-related state
+// (#launching, beginLaunch/endLaunch) is not ported — see the dock motion
+// plan for why. PressMode.LAUNCHES_ONLY is honored via a direct check of
+// the app's running state at click time instead of a launch engine.
+
+import Clutter from '@girs/clutter-18';
+import St from '@girs/st-18';
+import Shell from '@girs/shell-18';
+
+import type { MotionRecipe } from '~/dock/motion/catalog.ts';
+import { resolveAnimationMode } from '~/dock/motion/easing.ts';
+import { PressInteraction } from '~/dock/motion/pressInteraction.ts';
+import {
+  dimOpacity,
+  hoverNeedsBudget,
+  neighborScaleAt,
+  resolveIconTransform,
+  textureRenderSize,
+} from '~/dock/motion/transforms.ts';
+
+const OWNED_TRANSITIONS = Object.freeze(['scale-x', 'scale-y', 'translation-x', 'translation-y']);
+
+function finiteActorValue(value: number, fallback: number): number {
+  return Number.isFinite(value) ? value : fallback;
+}
+
+interface OriginalState {
+  scaleX: number;
+  scaleY: number;
+  translationX: number;
+  translationY: number;
+  pivotX: number;
+  pivotY: number;
+  opacity: number;
+  redirect: number;
+}
+
+interface SizeConstraints {
+  minWidth: number;
+  minWidthSet: boolean;
+  naturalWidth: number;
+  naturalWidthSet: boolean;
+  minHeight: number;
+  minHeightSet: boolean;
+  naturalHeight: number;
+  naturalHeightSet: boolean;
+}
+
+interface TextureState {
+  actor: St.Icon;
+  constraints: SizeConstraints;
+}
+
+interface AppliedProperties {
+  scale_x: number;
+  scale_y: number;
+  translation_x: number;
+  translation_y: number;
+}
+
+export interface IconBudget {
+  budgetPx: number;
+  iconNormalSize: number;
+}
+
+export interface BaseIconLike {
+  iconSize: number;
+  _iconBin?: St.Bin;
+}
+
+export type MotionTarget = St.Button & {
+  app?: Shell.App | null;
+  icon?: BaseIconLike;
+  _delegate?: { icon?: BaseIconLike };
+};
+
+export interface IconMotionControllerParams {
+  icon: MotionTarget;
+  baseIcon: BaseIconLike;
+  bin: St.Bin;
+  recipe: MotionRecipe;
+  onHoverChanged?: (controller: IconMotionController, hovered: boolean) => void;
+  onDestroyed?: (controller: IconMotionController) => void;
+  onMeasured?: (measurement: IconBudget) => void;
+}
+
+export class IconMotionController {
+  private _icon: MotionTarget | null;
+  private _baseIcon: BaseIconLike | null;
+  private _bin: St.Bin | null;
+  private _recipe: MotionRecipe;
+  private _onHoverChanged: (controller: IconMotionController, hovered: boolean) => void;
+  private _onDestroyed: (controller: IconMotionController) => void;
+  private _onMeasured: (measurement: IconBudget) => void;
+
+  private _dimmed = false;
+  private _hovered = false;
+  private _neighborDistance = Infinity;
+  private _pendingBudgetReport = false;
+  private _press = new PressInteraction();
+  private _signalIds: number[] = [];
+  private _binChildId = 0;
+  private readonly _original: OriginalState;
+  private _textureState: TextureState | null = null;
+  private _lastApplied: AppliedProperties;
+
+  constructor({
+    icon,
+    baseIcon,
+    bin,
+    recipe,
+    onHoverChanged = () => {},
+    onDestroyed = () => {},
+    onMeasured = () => {},
+  }: IconMotionControllerParams) {
+    this._icon = icon;
+    this._baseIcon = baseIcon;
+    this._bin = bin;
+    this._recipe = recipe;
+    this._onHoverChanged = onHoverChanged;
+    this._onDestroyed = onDestroyed;
+    this._onMeasured = onMeasured;
+
+    const [pivotX, pivotY] = bin.get_pivot_point();
+    this._original = {
+      scaleX: finiteActorValue(bin.scale_x, 1),
+      scaleY: finiteActorValue(bin.scale_y, 1),
+      translationX: finiteActorValue(bin.translation_x, 0),
+      translationY: finiteActorValue(bin.translation_y, 0),
+      pivotX: finiteActorValue(pivotX, 0.5),
+      pivotY: finiteActorValue(pivotY, 0.5),
+      opacity: bin.opacity,
+      redirect: bin.offscreen_redirect,
+    };
+    // The bin starts at rest, so the first apply toward rest skips.
+    this._lastApplied = {
+      scale_x: this._original.scaleX,
+      scale_y: this._original.scaleY,
+      translation_x: this._original.translationX,
+      translation_y: this._original.translationY,
+    };
+
+    this._signalIds.push(icon.connect('notify::hover', () => this._syncHover()));
+    this._signalIds.push(
+      icon.connect('button-press-event', (_actor: unknown, event: Clutter.Event) => {
+        if (event.get_button() === Clutter.BUTTON_PRIMARY) {
+          // Fixed dock actions (Trash/removable storage) have no Shell.App,
+          // but their primary click still launches or opens something and
+          // should receive the same tactile feedback as a cold app launch.
+          const isLaunchClick = !icon.app || icon.app.state === Shell.AppState.STOPPED;
+          if (this._press.beginPrimary(this._recipe.press, isLaunchClick))
+            this._apply(this._recipe.press.duration);
+        }
+        return Clutter.EVENT_PROPAGATE;
+      }),
+    );
+    this._signalIds.push(
+      icon.connect('notify::pressed', () => {
+        if (this._press.syncButtonPressed(icon.pressed)) this._apply(this._recipe.press.duration);
+      }),
+    );
+    this._signalIds.push(
+      icon.connect_after('clicked', () => {
+        if (this._press.finishClick()) this._apply(this._recipe.press.duration);
+      }),
+    );
+    this._signalIds.push(icon.connect('destroy', () => this.onTargetDestroyed()));
+    this._binChildId = bin.connect('notify::child', () => this._syncTextureResolution());
+    this._syncTextureResolution();
+    this._syncHover();
+  }
+
+  get recipe(): MotionRecipe {
+    return this._recipe;
+  }
+
+  setRecipe(recipe: MotionRecipe): void {
+    this._recipe = recipe;
+    this._press.reset();
+    this._syncTextureResolution();
+    this._apply();
+  }
+
+  // State only; returns true when the flush must apply this icon.
+  setNeighborDistance(distance: number): boolean {
+    if (this._neighborDistance === distance) return false;
+    const { hover } = this._recipe;
+    const visibleChange =
+      hover.enabled &&
+      neighborScaleAt(hover, this._neighborDistance) !== neighborScaleAt(hover, distance);
+    this._neighborDistance = distance;
+    return visibleChange && !this._hovered;
+  }
+
+  // The neighbor group schedules the apply.
+  applyHoverState(): void {
+    this._apply();
+  }
+
+  onTargetDestroyed(): void {
+    if (!this._icon) return;
+    this._signalIds = [];
+    this._binChildId = 0;
+    this._dimmed = false;
+    this._textureState = null;
+    this._bin = null;
+    this._baseIcon = null;
+    this._icon = null;
+    this._onDestroyed(this);
+  }
+
+  dispose({ restore = true }: { restore?: boolean } = {}): void {
+    if (!this._icon) return;
+    if (this._icon) {
+      for (const id of this._signalIds) this._icon.disconnect(id);
+    }
+    this._signalIds = [];
+    if (this._bin && this._binChildId) this._bin.disconnect(this._binChildId);
+    this._binChildId = 0;
+    this._syncDim(0);
+    if (restore) this._restore();
+    this._onDestroyed(this);
+    this._bin = null;
+    this._baseIcon = null;
+    this._icon = null;
+  }
+
+  measure(): IconBudget | null {
+    return this._icon ? this._measureBudget() : null;
+  }
+
+  private _syncHover(): void {
+    if (!this._icon) return;
+    const hovered = Boolean(this._icon.hover);
+    if (this._hovered === hovered) return;
+    this._hovered = hovered;
+    this._pendingBudgetReport = hovered;
+    if (!hovered) this._press.reset();
+    this._onHoverChanged(this, hovered);
+  }
+
+  private _apply(durationOverride: number | null = null): void {
+    if (!this._icon || !this._bin) return;
+    const animationsEnabled = St.Settings.get().enable_animations;
+    const budget =
+      this._pendingBudgetReport ||
+      (animationsEnabled &&
+        hoverNeedsBudget({
+          recipe: this._recipe,
+          hovered: this._hovered,
+          neighborDistance: this._neighborDistance,
+        }))
+        ? this._measureBudget()
+        : null;
+    if (this._pendingBudgetReport) {
+      this._pendingBudgetReport = false;
+      if (budget) this._onMeasured(budget);
+    }
+
+    const transform = resolveIconTransform({
+      recipe: this._recipe,
+      hovered: this._hovered,
+      neighborDistance: this._neighborDistance,
+      pressed: this._press.pressed,
+      animationsEnabled,
+      budgetPx: budget ? budget.budgetPx : Infinity,
+      iconNormalSize: budget ? budget.iconNormalSize : 0,
+    });
+    // Leaving settles a little more slowly than entering. This avoids a
+    // twitchy snap-back during quick pointer sweeps without delaying hover.
+    const hoverDuration = this._hovered
+      ? this._recipe.hover.duration
+      : Math.round(this._recipe.hover.duration * 1.15);
+    const baseDuration = durationOverride ?? hoverDuration;
+    const duration = animationsEnabled ? baseDuration : 0;
+    const properties: AppliedProperties = {
+      scale_x: this._original.scaleX * transform.scaleX,
+      scale_y: this._original.scaleY * transform.scaleY,
+      translation_x: this._original.translationX + transform.translationX,
+      translation_y: this._original.translationY + transform.translationY,
+    };
+
+    this._syncDim(transform.dim);
+    this._bin.set_pivot_point(transform.pivot[0], transform.pivot[1]);
+
+    const last = this._lastApplied;
+    if (
+      duration > 0 &&
+      last.scale_x === properties.scale_x &&
+      last.scale_y === properties.scale_y &&
+      last.translation_x === properties.translation_x &&
+      last.translation_y === properties.translation_y
+    )
+      return;
+    this._lastApplied = properties;
+
+    this._removeOwnedTransitions();
+    if (duration === 0) {
+      Object.assign(this._bin, properties);
+      return;
+    }
+
+    this._bin.ease({
+      ...properties,
+      duration,
+      mode: resolveAnimationMode(this._recipe.hover.easing, Clutter.AnimationMode),
+    });
+  }
+
+  // Measure the room between the icon and the dash's clip.
+  private _measureBudget(): IconBudget | null {
+    const bin = this._bin;
+    if (!bin) return null;
+    const parent = bin.get_parent();
+    if (!parent) return null;
+    let clipActor: Clutter.Actor | null = null;
+    for (let node: Clutter.Actor | null = bin; node; node = node.get_parent()) {
+      if (node.has_clip) {
+        clipActor = node;
+        break;
+      }
+    }
+    if (!clipActor) return null;
+
+    const box = bin.get_allocation_box();
+    const clip = clipActor.get_clip();
+    if (!clip) return null;
+    const [, clipY] = clipActor.get_transformed_position();
+    const [, parentY] = parent.get_transformed_position();
+    const top = parentY + box.y1;
+    const clipTop = clipY + clip[1];
+
+    return { budgetPx: top - clipTop, iconNormalSize: box.y2 - box.y1 };
+  }
+
+  // A brightness effect would render offscreen and blur the scaled icon.
+  // Dim from the original opacity, never the current one: a snapshot of an
+  // already dimmed bin would compound and darken the icon for good.
+  private _syncDim(dim: number): void {
+    if (!this._bin) return;
+    if (dim > 0) {
+      if (!this._dimmed) {
+        this._dimmed = true;
+        this._bin.offscreen_redirect = 0;
+      }
+      this._bin.opacity = dimOpacity(this._original.opacity, dim);
+    } else if (this._dimmed) {
+      this._bin.opacity = this._original.opacity;
+      this._bin.offscreen_redirect = this._original.redirect;
+      this._dimmed = false;
+    }
+  }
+
+  private _syncTextureResolution(): void {
+    const bin = this._bin;
+    const normalSize = this._baseIcon?.iconSize ?? 0;
+    if (!bin || !(normalSize > 0)) return;
+
+    const child = bin.child;
+    if (!(child instanceof St.Icon)) return;
+    if (this._textureState?.actor !== child) {
+      this._textureState = {
+        actor: child,
+        constraints: {
+          minWidth: child.min_width,
+          minWidthSet: child.min_width_set,
+          naturalWidth: child.natural_width,
+          naturalWidthSet: child.natural_width_set,
+          minHeight: child.min_height,
+          minHeightSet: child.min_height_set,
+          naturalHeight: child.natural_height,
+          naturalHeightSet: child.natural_height_set,
+        },
+      };
+    }
+
+    const renderSize = textureRenderSize(normalSize, this._recipe);
+    if (renderSize > 0 && child.icon_size !== renderSize) child.icon_size = renderSize;
+    // Keep only the texture supersampled. Explicitly constraining the St.Icon
+    // actor itself preserves the exact preferred size that Dash uses for its
+    // icon-size budget; constraining the parent bin subtly changes that math.
+    child.set_size(normalSize, normalSize);
+  }
+
+  private _restoreTextureResolution(): void {
+    const normalSize = this._baseIcon?.iconSize ?? 0;
+    const state = this._textureState;
+    if (!state) return;
+
+    if (normalSize > 0 && state.actor.icon_size !== normalSize) state.actor.icon_size = normalSize;
+
+    const { actor, constraints } = state;
+    actor.min_width = constraints.minWidth;
+    actor.natural_width = constraints.naturalWidth;
+    actor.min_height = constraints.minHeight;
+    actor.natural_height = constraints.naturalHeight;
+    actor.min_width_set = constraints.minWidthSet;
+    actor.natural_width_set = constraints.naturalWidthSet;
+    actor.min_height_set = constraints.minHeightSet;
+    actor.natural_height_set = constraints.naturalHeightSet;
+    this._textureState = null;
+  }
+
+  private _restore(): void {
+    if (!this._bin) return;
+    this._removeOwnedTransitions();
+    this._bin.set_pivot_point(this._original.pivotX, this._original.pivotY);
+    this._bin.set_scale(this._original.scaleX, this._original.scaleY);
+    this._bin.translation_x = this._original.translationX;
+    this._bin.translation_y = this._original.translationY;
+    this._restoreTextureResolution();
+  }
+
+  private _removeOwnedTransitions(): void {
+    if (!this._bin) return;
+    for (const transition of OWNED_TRANSITIONS) this._bin.remove_transition(transition);
+  }
+}
diff --git a/src/dock/motion/motionSurface.ts b/src/dock/motion/motionSurface.ts
new file mode 100644
index 0000000..9349bb2
--- /dev/null
+++ b/src/dock/motion/motionSurface.ts
@@ -0,0 +1,198 @@
+// Owns one IconMotionController per dock icon and groups them to compute
+// neighbor-hover distances, ported from d2d-companion's
+// lib/runtime/motionSurface.js. Each AuroraDash has two container sources:
+// _box for app icons and _dashContainer for fixed items such as Trash and
+// removable storage. Both feed one visually ordered neighbor group.
+
+import GLib from '@girs/glib-2.0';
+import Meta from '@girs/meta-18';
+import type Clutter from '@girs/clutter-18';
+import type St from '@girs/st-18';
+
+import type { MotionRecipe } from '~/dock/motion/catalog.ts';
+import { NeighborRadius } from '~/dock/motion/catalog.ts';
+import {
+  IconMotionController,
+  type IconBudget,
+  type MotionTarget,
+} from '~/dock/motion/iconMotionController.ts';
+
+interface DashItemContainerLike extends St.Widget {
+  child?: MotionTarget;
+}
+
+interface SourceConnections {
+  childAddedId: number;
+  destroyId: number;
+}
+
+export class MotionSurface {
+  private _recipe: MotionRecipe;
+  private _onMeasured: (measurement: IconBudget) => void;
+  private _icons = new Map<MotionTarget, IconMotionController>();
+  private _group: NeighborGroup | null;
+  private _sources: Map<St.Widget, SourceConnections> | null = new Map();
+
+  constructor({
+    recipe,
+    getOrderedContainers,
+    onMeasured = () => {},
+  }: {
+    recipe: MotionRecipe;
+    getOrderedContainers: () => Clutter.Actor[];
+    onMeasured?: (measurement: IconBudget) => void;
+  }) {
+    this._recipe = recipe;
+    this._onMeasured = onMeasured;
+    this._group = new NeighborGroup(getOrderedContainers);
+  }
+
+  get controllers(): IconMotionController[] {
+    return [...this._icons.values()];
+  }
+
+  setRecipe(recipe: MotionRecipe): void {
+    this._recipe = recipe;
+    for (const controller of this.controllers) controller.setRecipe(recipe);
+  }
+
+  addContainerSource(source: St.Widget): void {
+    if (!this._sources || this._sources.has(source)) return;
+    for (const container of source.get_children())
+      this._registerContainer(container as DashItemContainerLike);
+    const childAddedId = source.connect(
+      'child-added',
+      (_source: St.Widget, container: St.Widget) => {
+        this._registerContainer(container as DashItemContainerLike);
+      },
+    );
+    const destroyId = source.connect('destroy', () => {
+      this._sources?.delete(source);
+    });
+    this._sources.set(source, { childAddedId, destroyId });
+  }
+
+  dispose(): void {
+    if (!this._sources) return;
+    for (const [icon, controller] of [...this._icons]) {
+      this._icons.delete(icon);
+      controller.dispose();
+    }
+    this._group?.dispose();
+    this._group = null;
+    for (const [source, connections] of this._sources) {
+      if (connections.childAddedId) source.disconnect(connections.childAddedId);
+      if (connections.destroyId) source.disconnect(connections.destroyId);
+    }
+    this._sources.clear();
+    this._sources = null;
+  }
+
+  private _registerContainer(container: DashItemContainerLike): void {
+    const icon = container.child ?? (container as unknown as MotionTarget);
+    const baseIcon = icon?.icon ?? icon?._delegate?.icon;
+    const bin = baseIcon?._iconBin;
+    if (!icon || !bin || this._icons.has(icon)) return;
+
+    const controller = new IconMotionController({
+      icon,
+      baseIcon,
+      bin,
+      recipe: this._recipe,
+      onHoverChanged: (changed, hovered) => this._group?.setHovered(changed, hovered),
+      onDestroyed: (destroyed) => {
+        this._icons.delete(icon);
+        this._group?.remove(destroyed);
+      },
+      onMeasured: (measurement) => this._onMeasured(measurement),
+    });
+    this._group?.add(controller, container);
+    this._icons.set(icon, controller);
+  }
+}
+
+class NeighborGroup {
+  private _entries: Array<{ controller: IconMotionController; container: St.Widget }> = [];
+  private _dirty = new Set<IconMotionController>();
+  private _hovered: IconMotionController | null = null;
+  private _flushId = 0;
+  private _getOrderedContainers: () => Clutter.Actor[];
+
+  constructor(getOrderedContainers: () => Clutter.Actor[]) {
+    this._getOrderedContainers = getOrderedContainers;
+  }
+
+  add(controller: IconMotionController, container: St.Widget): void {
+    this._entries.push({ controller, container });
+    this._scheduleFlush();
+  }
+
+  remove(controller: IconMotionController): void {
+    const index = this._entries.findIndex((entry) => entry.controller === controller);
+    if (index === -1) return;
+    this._entries.splice(index, 1);
+    if (this._hovered === controller) this._hovered = null;
+    // Survivors shift by one index, so their distances change too.
+    this._scheduleFlush();
+  }
+
+  setHovered(controller: IconMotionController, hovered: boolean): void {
+    this._hovered = hovered ? controller : this._hovered === controller ? null : this._hovered;
+    // The flip must apply even when the distances are inert.
+    this._dirty.add(controller);
+    this._scheduleFlush();
+  }
+
+  dispose(): void {
+    this._cancelFlush();
+    this._hovered = null;
+    this._entries = [];
+  }
+
+  private _scheduleFlush(): void {
+    if (this._flushId) return;
+    this._flushId = global.compositor.get_laters().add(Meta.LaterType.BEFORE_REDRAW, () => {
+      this._flushId = 0;
+      this._flush();
+      return GLib.SOURCE_REMOVE;
+    });
+  }
+
+  private _cancelFlush(): void {
+    if (!this._flushId) return;
+    global.compositor.get_laters().remove(this._flushId);
+    this._flushId = 0;
+  }
+
+  // Swap first so changes made while applying get a fresh flush.
+  private _flush(): void {
+    this._syncNeighbors();
+    const dirty = this._dirty;
+    this._dirty = new Set();
+    for (const { controller } of this._entries) {
+      if (dirty.has(controller)) controller.applyHoverState();
+    }
+  }
+
+  private _syncNeighbors(): void {
+    const orderedContainers = this._getOrderedContainers();
+    this._entries.sort((first, second) => {
+      const firstIndex = orderedContainers.indexOf(first.container);
+      const secondIndex = orderedContainers.indexOf(second.container);
+      return (
+        (firstIndex === -1 ? Number.MAX_SAFE_INTEGER : firstIndex) -
+        (secondIndex === -1 ? Number.MAX_SAFE_INTEGER : secondIndex)
+      );
+    });
+    const hoveredIndex = this._entries.findIndex((entry) => entry.controller === this._hovered);
+    for (let index = 0; index < this._entries.length; index++) {
+      const distance = hoveredIndex === -1 ? Infinity : Math.abs(index - hoveredIndex);
+      // Beyond any possible radius the transform is identity; collapse to
+      // Infinity so far icons never see a change to apply.
+      const entry = this._entries[index];
+      if (!entry) continue;
+      if (entry.controller.setNeighborDistance(distance > NeighborRadius.MAX ? Infinity : distance))
+        this._dirty.add(entry.controller);
+    }
+  }
+}
diff --git a/src/dock/motion/pressInteraction.ts b/src/dock/motion/pressInteraction.ts
new file mode 100644
index 0000000..48b7fbb
--- /dev/null
+++ b/src/dock/motion/pressInteraction.ts
@@ -0,0 +1,50 @@
+// Small press-state machine for dock icon click feedback, ported from
+// d2d-companion's lib/motion/pressInteraction.js. The source project's
+// PressMode.LAUNCHES_ONLY is driven by its launch engine (not ported here);
+// this version decides "is this a launch click" itself via a caller-supplied
+// flag instead (see IconMotionController).
+
+import { PressMode, type PressRecipe } from '~/dock/motion/catalog.ts';
+
+export class PressInteraction {
+  private _pressed = false;
+  private _active = false;
+
+  get pressed(): boolean {
+    return this._pressed;
+  }
+
+  // Call on the primary button-press-event. `isLaunchClick` should reflect
+  // whether this click is expected to start a new app instance.
+  beginPrimary(config: PressRecipe, isLaunchClick: boolean): boolean {
+    this._active = Boolean(
+      config.enabled &&
+      (config.mode === PressMode.ALL_PRIMARY_CLICKS ||
+        (config.mode === PressMode.LAUNCHES_ONLY && isLaunchClick)),
+    );
+    return this._applyStep(this._active);
+  }
+
+  // Call on notify::pressed; clears an early visual press if the pointer
+  // was dragged off the icon before release.
+  syncButtonPressed(buttonPressed: boolean): boolean {
+    if (buttonPressed || !this._active) return false;
+    return this._applyStep(false);
+  }
+
+  finishClick(): boolean {
+    this._active = false;
+    return this._applyStep(false);
+  }
+
+  reset(): boolean {
+    this._active = false;
+    return this._applyStep(false);
+  }
+
+  private _applyStep(pressed: boolean): boolean {
+    if (this._pressed === pressed) return false;
+    this._pressed = pressed;
+    return true;
+  }
+}
diff --git a/src/dock/motion/transforms.ts b/src/dock/motion/transforms.ts
new file mode 100644
index 0000000..3a522c3
--- /dev/null
+++ b/src/dock/motion/transforms.ts
@@ -0,0 +1,194 @@
+// Pure transform math for dock icon hover/press motion, ported from
+// d2d-companion's lib/motion/transforms.js. aurora-shell's dock only ever
+// renders at the bottom of the screen (no DockPosition concept exists
+// elsewhere in the dock code), so the orientation is hardcoded here instead
+// of being parameterized like the source project.
+
+import {
+  Easing,
+  PressEffect,
+  type HoverRecipe,
+  type MotionRecipe,
+  type PressEffectId,
+} from '~/dock/motion/catalog.ts';
+
+// Bottom-dock orientation: icons grow upward, away from the screen edge.
+const PIVOT: readonly [number, number] = [0.5, 1];
+const OUTWARD: readonly [number, number] = [0, -1];
+
+export interface IconTransform {
+  scaleX: number;
+  scaleY: number;
+  translationX: number;
+  translationY: number;
+  dim: number;
+  pivot: readonly [number, number];
+}
+
+interface PressTransform {
+  scaleX: number;
+  scaleY: number;
+  translationX: number;
+  translationY: number;
+  dim: number;
+}
+
+// Press effects: (intensity) → geometry + dim, identity at 0.
+const PRESS_SQUASH_FACTOR = 0.22;
+const PRESS_DIM_FACTOR = 0.3;
+
+export function resolvePressTransform(effect: PressEffectId, intensity: number): PressTransform {
+  const clamped = clamp(intensity, 0, 1);
+  if (effect === PressEffect.DIM) return pressTransform({ dim: PRESS_DIM_FACTOR * clamped });
+  // Squash on the dock-facing (vertical) axis; the bottom dock is horizontal.
+  const normalScale = 1 - PRESS_SQUASH_FACTOR * clamped;
+  return pressTransform({ scaleY: normalScale });
+}
+
+export function dimOpacity(opacity: number, dim: number): number {
+  return Math.round(opacity * (1 - clamp(dim, 0, 1)));
+}
+
+function pressTransform({
+  scaleX = 1,
+  scaleY = 1,
+  translationX = 0,
+  translationY = 0,
+  dim = 0,
+}: Partial<PressTransform> = {}): PressTransform {
+  return { scaleX, scaleY, translationX, translationY, dim };
+}
+
+export function composeIconTransform({
+  hoverScale = 1,
+  lift = 0,
+  pressIntensity = 0,
+  pressEffect = PressEffect.SQUASH,
+}: {
+  hoverScale?: number;
+  lift?: number;
+  pressIntensity?: number;
+  pressEffect?: PressEffectId;
+}): IconTransform {
+  const press = resolvePressTransform(pressEffect, pressIntensity);
+  return {
+    scaleX: hoverScale * press.scaleX,
+    scaleY: hoverScale * press.scaleY,
+    translationX: press.translationX,
+    translationY: OUTWARD[1] * lift + press.translationY,
+    dim: press.dim,
+    pivot: PIVOT,
+  };
+}
+
+// EASE_OUT_BACK overshoots by about 10%.
+export const OVERSHOOT_RESERVE = 0.1;
+export const TEXTURE_SUPERSAMPLE = 2;
+
+// Load magnified icons at twice their normal resolution. Merely matching the
+// final hover scale still leaves too few source pixels at the fractional sizes
+// used by intermediate animation frames. The actor remains allocated at its
+// normal size, so this improves Clutter's sampling without changing layout.
+export function textureRenderSize(iconNormalSize: number, recipe: MotionRecipe): number {
+  if (!(iconNormalSize > 0) || !Number.isFinite(iconNormalSize)) return 0;
+  if (!recipe.hover.enabled) return Math.ceil(iconNormalSize);
+
+  const largestScale = Math.max(1, recipe.hover.scale, recipe.hover.neighborScale);
+  const overshoot = recipe.hover.easing === Easing.EASE_OUT_BACK ? OVERSHOOT_RESERVE : 0;
+  const hoverRenderScale = 1 + (largestScale - 1) * (1 + overshoot);
+  const renderScale = Math.max(TEXTURE_SUPERSAMPLE, hoverRenderScale);
+  return Math.ceil(iconNormalSize * renderScale);
+}
+
+// Fit hover scale and lift into the available room above the dock.
+export function fitHoverToBudget(
+  hoverScale: number,
+  lift: number,
+  iconNormalSize: number,
+  budgetPx: number,
+  overshoot = 0,
+): { hoverScale: number; lift: number } {
+  if (!(iconNormalSize > 0) || !Number.isFinite(budgetPx)) return { hoverScale, lift };
+  const budget = Math.max(0, budgetPx) / (1 + Math.max(0, overshoot));
+  const scaleGrowth = iconNormalSize * Math.max(0, hoverScale - 1);
+  const safeLift = Math.max(0, lift);
+  const reach = scaleGrowth + safeLift;
+  if (reach <= budget || reach === 0) return { hoverScale, lift };
+  const factor = budget / reach;
+  return {
+    hoverScale: 1 + (scaleGrowth * factor) / iconNormalSize,
+    lift: safeLift * factor,
+  };
+}
+
+// Linear falloff: full neighbor scale next to the hover, fading to identity
+// past the radius.
+export function neighborScaleAt(hover: HoverRecipe, distance: number): number {
+  if (!(distance >= 1) || distance > hover.neighborRadius) return 1;
+  const weight = (hover.neighborRadius - distance + 1) / hover.neighborRadius;
+  return 1 + (hover.neighborScale - 1) * weight;
+}
+
+// Only a hover reach (scale growth or lift) is fitted to the budget.
+export function hoverNeedsBudget({
+  recipe,
+  hovered = false,
+  neighborDistance = Infinity,
+}: {
+  recipe: MotionRecipe;
+  hovered?: boolean;
+  neighborDistance?: number;
+}): boolean {
+  const { hover } = recipe;
+  if (!hover.enabled) return false;
+  if (hovered) return hover.scale !== 1 || hover.lift !== 0;
+  return neighborScaleAt(hover, neighborDistance) !== 1;
+}
+
+export function resolveIconTransform({
+  recipe,
+  hovered = false,
+  neighborDistance = Infinity,
+  pressed = false,
+  animationsEnabled = true,
+  budgetPx = Infinity,
+  iconNormalSize = 0,
+}: {
+  recipe: MotionRecipe;
+  hovered?: boolean;
+  neighborDistance?: number;
+  pressed?: boolean;
+  animationsEnabled?: boolean;
+  budgetPx?: number;
+  iconNormalSize?: number;
+}): IconTransform {
+  if (!animationsEnabled) {
+    return { scaleX: 1, scaleY: 1, translationX: 0, translationY: 0, dim: 0, pivot: PIVOT };
+  }
+
+  const hoverEnabled = recipe.hover.enabled;
+  const hoverScale =
+    hoverEnabled && hovered
+      ? recipe.hover.scale
+      : hoverEnabled
+        ? neighborScaleAt(recipe.hover, neighborDistance)
+        : 1;
+  const lift = hoverEnabled && hovered ? recipe.hover.lift : 0;
+  const pressIntensity = recipe.press.enabled && pressed ? recipe.press.intensity : 0;
+
+  const overshoot = recipe.hover.easing === Easing.EASE_OUT_BACK ? OVERSHOOT_RESERVE : 0;
+  const fitted = fitHoverToBudget(hoverScale, lift, iconNormalSize, budgetPx, overshoot);
+
+  return composeIconTransform({
+    hoverScale: fitted.hoverScale,
+    lift: fitted.lift,
+    pressIntensity,
+    pressEffect: recipe.press.effect,
+  });
+}
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return minimum;
+  return Math.min(maximum, Math.max(minimum, number));
+}
diff --git a/src/dock/trashIcon.ts b/src/dock/trashIcon.ts
index 77b1450..fe9ed6b 100644
--- a/src/dock/trashIcon.ts
+++ b/src/dock/trashIcon.ts
@@ -37,7 +37,6 @@ export const TrashIcon = GObject.registerClass(
     declare private _menu: PopupMenu.PopupMenu | null;
     declare private _menuManager: PopupMenu.PopupMenuManager | null;
     declare private _emptyItem: PopupMenu.PopupMenuItem | null;
-    declare private _destroyed: boolean;
 
     override _init(): void {
       super._init();
@@ -53,7 +52,6 @@ export const TrashIcon = GObject.registerClass(
       this._menu = null;
       this._menuManager = null;
       this._emptyItem = null;
-      this._destroyed = false;
 
       this.toggleButton = new St.Button({
         style_class: 'show-apps',
@@ -94,14 +92,27 @@ export const TrashIcon = GObject.registerClass(
 
       this._startMonitor();
       this._refresh();
-
-      this.connect('destroy', () => this._onDestroy());
     }
 
     setIconSize(size: number): void {
       this.icon.setIconSize(size);
     }
 
+    override destroy(): void {
+      this.toggleButton.disconnectObject(this);
+      this._refreshCancellable?.cancel();
+      this._refreshCancellable = null;
+      this._monitor?.disconnectObject(this);
+      this._monitor?.cancel();
+      this._monitor = null;
+      this._menu?.destroy();
+      this._menu = null;
+      this._menuManager = null;
+      this._emptyItem = null;
+      this._iconActor = null;
+      super.destroy();
+    }
+
     get menuIsOpen(): boolean {
       return this._menu?.isOpen ?? false;
     }
@@ -146,8 +157,6 @@ export const TrashIcon = GObject.registerClass(
     }
 
     private _refresh(): void {
-      if (this._destroyed) return;
-
       this._refreshCancellable?.cancel();
       const cancellable = new Gio.Cancellable();
       this._refreshCancellable = cancellable;
@@ -158,7 +167,7 @@ export const TrashIcon = GObject.registerClass(
         0,
         cancellable,
         (file, res) => {
-          if (this._destroyed || cancellable.is_cancelled()) return;
+          if (this._refreshCancellable !== cancellable || cancellable.is_cancelled()) return;
 
           let count = 0;
           try {
@@ -211,7 +220,7 @@ export const TrashIcon = GObject.registerClass(
           },
         });
       } catch (error) {
-        if (!this._destroyed) this._warn('Failed to open trash', error);
+        this._warn('Failed to open trash', error);
       }
     }
 
@@ -305,21 +314,6 @@ export const TrashIcon = GObject.registerClass(
     private _warn(message: string, error: unknown): void {
       logger.warn(`${message}: ${error}`, { prefix: LOG_PREFIX });
     }
-
-    private _onDestroy(): void {
-      this._destroyed = true;
-      this.toggleButton.disconnectObject(this);
-      this._refreshCancellable?.cancel();
-      this._refreshCancellable = null;
-      this._monitor?.disconnectObject(this);
-      this._monitor?.cancel();
-      this._monitor = null;
-      this._menu?.destroy();
-      this._menu = null;
-      this._menuManager = null;
-      this._emptyItem = null;
-      this._iconActor = null;
-    }
   },
 );
 
diff --git a/src/extension.dev.ts b/src/extension.dev.ts
new file mode 100644
index 0000000..4c410ea
--- /dev/null
+++ b/src/extension.dev.ts
@@ -0,0 +1,40 @@
+import '@girs/gjs';
+
+import GLib from '@girs/glib-2.0';
+
+import { AuroraShellExtensionBase } from '~/core/extensionBase.ts';
+import { logger } from '~/core/logger.ts';
+import { DevTool } from '~/dev/devTool.ts';
+
+const LOG_PREFIX = 'AuroraShell';
+
+export default class AuroraShellDevelopmentExtension extends AuroraShellExtensionBase {
+  private _devTool: DevTool | null = null;
+
+  override enable(): void {
+    super.enable();
+    if (GLib.getenv('AURORA_DEVTOOLS') !== '1' || !this._context || !this._manager) return;
+
+    try {
+      this._devTool = new DevTool(this._context, {
+        getModule: (key) => this._manager?.getModule(key) ?? null,
+        openPreferences: () => this.openPreferences(),
+      });
+      this._devTool.enable();
+    } catch (error) {
+      this._devTool?.disable();
+      this._devTool = null;
+      logger.error(`Failed to enable DevTool: ${String(error)}`, { prefix: LOG_PREFIX });
+    }
+  }
+
+  override disable(): void {
+    try {
+      this._devTool?.disable();
+    } catch (error) {
+      logger.error(`Failed to disable DevTool: ${String(error)}`, { prefix: LOG_PREFIX });
+    }
+    this._devTool = null;
+    super.disable();
+  }
+}
diff --git a/src/extension.ts b/src/extension.ts
index 9040dfe..db8eb6c 100644
--- a/src/extension.ts
+++ b/src/extension.ts
@@ -1,90 +1,5 @@
 import '@girs/gjs';
 
-import GLib from '@girs/glib-2.0';
-import { Extension } from '@girs/gnome-shell/extensions/extension';
+import { AuroraShellExtensionBase } from '~/core/extensionBase.ts';
 
-import type { ExtensionContext } from '~/core/context.ts';
-import { DefaultExtensionContext } from '~/core/context.ts';
-import { ConsoleLogger, logger, setGlobalLogger } from '~/core/logger.ts';
-import { GSettingsManager } from '~/core/settings.ts';
-import { DefaultDeviceService } from '~/device/device.ts';
-import { DevTool } from '~/dev/devTool.ts';
-import { ModuleManager } from '~/moduleManager.ts';
-import type { Module } from '~/module.ts';
-import { getModuleRegistry } from '~/registry.ts';
-import { cleanupIcons, initIcons } from '~/shared/icons.ts';
-
-const LOG_PREFIX = 'AuroraShell';
-
-export default class AuroraShellExtension extends Extension {
-  private _manager: ModuleManager | null = null;
-  private _devTool: DevTool | null = null;
-  private _context: ExtensionContext | null = null;
-
-  get _modules(): ReadonlyMap<string, Module> {
-    return this._manager?.modules ?? new Map();
-  }
-
-  override enable(): void {
-    const consoleLogger = new ConsoleLogger('Aurora Shell', this.uuid);
-    setGlobalLogger(consoleLogger);
-    consoleLogger.debug('Enabling extension', { prefix: LOG_PREFIX });
-
-    const device = new DefaultDeviceService();
-    this._context = new DefaultExtensionContext(
-      this.uuid,
-      this.path,
-      new GSettingsManager(this.getSettings()),
-      device,
-    );
-
-    initIcons(this.path);
-    this._manager = new ModuleManager(getModuleRegistry(), this._context, {
-      debug: (message) => logger.debug(message, { prefix: LOG_PREFIX }),
-      error: (message) => logger.error(message, { prefix: LOG_PREFIX }),
-    });
-    this._manager.start();
-    this._enableDevTool();
-  }
-
-  private _enableDevTool(): void {
-    if (GLib.getenv('AURORA_DEVTOOLS') !== '1' || !this._context || !this._manager) return;
-
-    try {
-      this._devTool = new DevTool(this._context, {
-        getModule: (key) => this._manager?.getModule(key) ?? null,
-        openPreferences: () => this.openPreferences(),
-      });
-      this._devTool.enable();
-    } catch (error) {
-      try {
-        this._devTool?.disable();
-      } catch {
-        // Preserve the original enable error.
-      }
-      logger.error(`Failed to enable DevTool: ${String(error)}`, { prefix: LOG_PREFIX });
-      this._devTool = null;
-    }
-  }
-
-  private _disableDevTool(): void {
-    if (!this._devTool) return;
-    try {
-      this._devTool.disable();
-    } catch (error) {
-      logger.error(`Failed to disable DevTool: ${String(error)}`, { prefix: LOG_PREFIX });
-    } finally {
-      this._devTool = null;
-    }
-  }
-
-  override disable(): void {
-    logger.debug('Disabling extension', { prefix: LOG_PREFIX });
-    this._disableDevTool();
-    this._manager?.stop();
-    this._manager = null;
-    this._context?.device.destroy();
-    this._context = null;
-    cleanupIcons();
-  }
-}
+export default class AuroraShellExtension extends AuroraShellExtensionBase {}
diff --git a/src/panel/auroraMenu.ts b/src/panel/auroraMenu.ts
index 3f7c32d..ec46565 100644
--- a/src/panel/auroraMenu.ts
+++ b/src/panel/auroraMenu.ts
@@ -99,7 +99,7 @@ export class AuroraMenu extends Module {
 
     const menu = this._getMenu();
     menu?.actor?.add_style_class_name('aurora-menu');
-    menu?.setSourceAlignment?.(0.0);
+    menu?.setSourceAlignment(0.0);
     if (menu) this._lockMenuWidth(menu);
 
     if (menu) {
diff --git a/src/panel/bluetoothMenu/bluetoothMenu.ts b/src/panel/bluetoothMenu/bluetoothMenu.ts
index bef9697..a7527d3 100644
--- a/src/panel/bluetoothMenu/bluetoothMenu.ts
+++ b/src/panel/bluetoothMenu/bluetoothMenu.ts
@@ -42,7 +42,7 @@ export class BluetoothMenu extends Module {
     this._lifecycle = null;
 
     for (const [item, { patcher, destroyId }] of this._patchedItems) {
-      item?.disconnect?.(destroyId);
+      item?.disconnect(destroyId);
       patcher.disable();
     }
     this._patchedItems.clear();
diff --git a/src/panel/clock/meetingClock/calendarServerBackend.ts b/src/panel/clock/meetingClock/calendarServerBackend.ts
index 90878ac..c0128bf 100644
--- a/src/panel/clock/meetingClock/calendarServerBackend.ts
+++ b/src/panel/clock/meetingClock/calendarServerBackend.ts
@@ -19,7 +19,6 @@ export class CalendarServerBackend {
   private _signalId = 0;
   private _eventsById = new Map<string, MeetingEvent>();
   private _onEventsChanged: EventsChangedCallback;
-  private _running = false;
 
   constructor(onEventsChanged: EventsChangedCallback) {
     this._onEventsChanged = onEventsChanged;
@@ -27,8 +26,6 @@ export class CalendarServerBackend {
 
   start(): void {
     if (this._proxy) return;
-    this._running = true;
-
     try {
       this._proxy = Gio.DBusProxy.new_for_bus_sync(
         Gio.BusType.SESSION,
@@ -47,11 +44,11 @@ export class CalendarServerBackend {
 
     this._signalId = this._proxy.connect('g-signal', (_proxy, _senderName, signalName, params) => {
       if (signalName === 'EventsAddedOrUpdated') {
-        if (!this._running) return;
+        if (!this._proxy) return;
         const [rawEvents = []] = params.deepUnpack() as [unknown[]?];
         this._onEventsAddedOrUpdated(rawEvents);
       } else if (signalName === 'EventsRemoved') {
-        if (!this._running) return;
+        if (!this._proxy) return;
         const [rawIds = []] = params.deepUnpack() as [string[]?];
         this._onEventsRemoved(rawIds);
       }
@@ -59,7 +56,6 @@ export class CalendarServerBackend {
   }
 
   stop(): void {
-    this._running = false;
     if (this._signalId && this._proxy) {
       this._proxy.disconnect(this._signalId);
       this._signalId = 0;
@@ -105,7 +101,7 @@ export class CalendarServerBackend {
   }
 
   private _emitEventsChanged(): void {
-    if (!this._running) return;
+    if (!this._proxy) return;
 
     this._onEventsChanged(
       [...this._eventsById.values()].sort((a, b) => a.startEpochSeconds - b.startEpochSeconds),
diff --git a/src/panel/clock/meetingClock/meetingClock.ts b/src/panel/clock/meetingClock/meetingClock.ts
index 545c214..05245fd 100644
--- a/src/panel/clock/meetingClock/meetingClock.ts
+++ b/src/panel/clock/meetingClock/meetingClock.ts
@@ -52,8 +52,6 @@ export class MeetingClock extends Module {
   private _notificationSourceDestroyId = 0;
   private _activeNotification: MessageTray.Notification | null = null;
   private _activeNotificationDestroyId = 0;
-  private _uiAlive = false;
-  private _enabled = false;
   private _lifecycle: LifecycleScope | null = null;
   private _refreshTimerId = 0;
   private _labelTimerId = 0;
@@ -73,12 +71,10 @@ export class MeetingClock extends Module {
   override enable(): void {
     this.disable();
     this._lifecycle = new LifecycleScope();
-    this._enabled = true;
-
     this._installClockWidget();
 
     this._backend = new CalendarServerBackend((events) => {
-      if (!this._enabled) return;
+      if (!this._lifecycle) return;
       this.setSourceEvents(CALENDAR_SERVER_SOURCE_KEY, events);
     });
     this._backend.start();
@@ -128,9 +124,6 @@ export class MeetingClock extends Module {
   }
 
   override disable(): void {
-    this._enabled = false;
-    this._uiAlive = false;
-
     this._lifecycle?.dispose();
     this._lifecycle = null;
 
@@ -188,7 +181,6 @@ export class MeetingClock extends Module {
       'right',
       100,
     );
-    this._uiAlive = Boolean(this._clockPillRegistration);
   }
 
   private _refreshEvents(): void {
@@ -196,7 +188,7 @@ export class MeetingClock extends Module {
   }
 
   setSourceEvents(sourceKey: string, events: readonly MeetingEvent[]): void {
-    if (!this._enabled) return;
+    if (!this._lifecycle) return;
 
     const previousIds = new Set(this._eventsBySource.get(sourceKey)?.map((event) => event.id));
     const nextEvents = [...events];
@@ -230,7 +222,7 @@ export class MeetingClock extends Module {
   }
 
   openMenu(): boolean {
-    if (!this._enabled || !this._uiAlive) return false;
+    if (!this._lifecycle || !this._clockPillRegistration) return false;
 
     this._render();
     return openClockMenu();
@@ -245,7 +237,7 @@ export class MeetingClock extends Module {
   }
 
   private _render(): void {
-    if (!this._enabled || !this._uiAlive) return;
+    if (!this._lifecycle || !this._clockPillRegistration) return;
 
     const now = this._now();
     const excludeAllDayEvents = this.context.settings.getBoolean(EXCLUDE_ALL_DAY_KEY);
@@ -269,7 +261,7 @@ export class MeetingClock extends Module {
   }
 
   private _scheduleAlerts(): void {
-    if (!this._enabled || !this._uiAlive) return;
+    if (!this._lifecycle || !this._clockPillRegistration) return;
 
     this._clearAlertTimer();
     if (this._activeAlertEventId) return;
@@ -296,7 +288,7 @@ export class MeetingClock extends Module {
   }
 
   private _schedulePanelRevealTimer(): void {
-    if (!this._enabled || !this._uiAlive) return;
+    if (!this._lifecycle || !this._clockPillRegistration) return;
 
     this._clearPanelRevealTimer();
     const intervalSeconds =
@@ -350,7 +342,7 @@ export class MeetingClock extends Module {
   }
 
   private _showAlert(event: MeetingEvent): void {
-    if (!this._enabled || !this._uiAlive) return;
+    if (!this._lifecycle || !this._clockPillRegistration) return;
 
     if (this._activeAlertEventId === event.id) return;
 
@@ -427,7 +419,8 @@ export class MeetingClock extends Module {
 
   private _revealPanelWidget(): void {
     const widget = this._panelWidget;
-    if (!this._enabled || !this._uiAlive || !widget || !this._lastPanelEventId) return;
+    if (!this._lifecycle || !this._clockPillRegistration || !widget || !this._lastPanelEventId)
+      return;
 
     this._clearPanelHideTimer();
     widget.remove_transition('opacity');
diff --git a/src/panel/clock/weatherClock/weatherClock.ts b/src/panel/clock/weatherClock/weatherClock.ts
index 460c3c0..eb0869d 100644
--- a/src/panel/clock/weatherClock/weatherClock.ts
+++ b/src/panel/clock/weatherClock/weatherClock.ts
@@ -67,8 +67,6 @@ export class WeatherClock extends Module {
   private _refreshTimerId = 0;
   private _retryTimerId = 0;
   private _retryCount = 0;
-  private _enabled = false;
-  private _uiAlive = false;
 
   constructor(context: ExtensionContext) {
     super(context);
@@ -77,7 +75,6 @@ export class WeatherClock extends Module {
   override enable(): void {
     this.disable();
     this._lifecycle = new LifecycleScope();
-    this._enabled = true;
     this._monitor = Gio.NetworkMonitor.get_default();
     this._gweatherSettings = this._createGWeatherSettings();
     if (this._gweatherSettings)
@@ -94,9 +91,6 @@ export class WeatherClock extends Module {
   }
 
   override disable(): void {
-    this._enabled = false;
-    this._uiAlive = false;
-
     this._lifecycle?.dispose();
     this._lifecycle = null;
 
@@ -120,7 +114,7 @@ export class WeatherClock extends Module {
   }
 
   setWeatherSnapshot(sourceKey: string, snapshot: Partial<WeatherSnapshot>): void {
-    if (!this._enabled) return;
+    if (!this._lifecycle) return;
 
     this._snapshotsBySource.set(sourceKey, normalizeWeatherSnapshot(snapshot, this._now()));
     this._syncSnapshot();
@@ -189,7 +183,6 @@ export class WeatherClock extends Module {
       afterClock ? 'right' : 'left',
       afterClock ? 10 : 100,
     );
-    this._uiAlive = Boolean(this._clockPillRegistration);
     this._render();
   }
 
@@ -236,7 +229,7 @@ export class WeatherClock extends Module {
   }
 
   private _onConnectivityChanged(): void {
-    if (!this._enabled) return;
+    if (!this._lifecycle) return;
 
     if (!this._hasConnectivity()) {
       this.setWeatherSnapshot(GNOME_WEATHER_SOURCE_KEY, {
@@ -252,7 +245,7 @@ export class WeatherClock extends Module {
 
   private _onWeatherChanged(): void {
     const weather = this._weatherClient;
-    if (!this._enabled || !weather) return;
+    if (!this._lifecycle || !weather) return;
 
     if (!weather.available) {
       this.setWeatherSnapshot(GNOME_WEATHER_SOURCE_KEY, {
@@ -370,7 +363,13 @@ export class WeatherClock extends Module {
   }
 
   private _render(): void {
-    if (!this._enabled || !this._uiAlive || !this._panelWidget || !this._icon || !this._label) {
+    if (
+      !this._lifecycle ||
+      !this._clockPillRegistration ||
+      !this._panelWidget ||
+      !this._icon ||
+      !this._label
+    ) {
       return;
     }
 
diff --git a/src/panel/volumeMixer/mixerList.ts b/src/panel/volumeMixer/mixerList.ts
index 752978b..897e254 100644
--- a/src/panel/volumeMixer/mixerList.ts
+++ b/src/panel/volumeMixer/mixerList.ts
@@ -59,14 +59,13 @@ export class VolumeMixerList extends St.BoxLayout {
     for (const stream of this._control.get_streams()) {
       this._streamAdded(stream.get_id());
     }
+  }
 
-    this.connect('destroy', () => {
-      this._control.disconnectObject(this);
-      for (const slider of this._sliders.values()) {
-        slider.destroy();
-      }
-      this._sliders.clear();
-    });
+  override destroy(): void {
+    this._control.disconnectObject(this);
+    for (const slider of this._sliders.values()) slider.destroy();
+    this._sliders.clear();
+    super.destroy();
   }
 
   private _streamAdded(id: number): void {
diff --git a/src/panel/volumeMixer/streamSlider.ts b/src/panel/volumeMixer/streamSlider.ts
index 6b0747f..6041123 100644
--- a/src/panel/volumeMixer/streamSlider.ts
+++ b/src/panel/volumeMixer/streamSlider.ts
@@ -211,7 +211,7 @@ export class ApplicationStreamSlider extends QuickSlider {
       this.slider.disconnect(this._dragEndId);
       this._dragEndId = 0;
     }
-    this._soundSettings?.disconnectObject?.(this);
+    this._soundSettings?.disconnectObject(this);
     this._stream?.disconnectObject(this);
     super.destroy();
   }
diff --git a/src/patches/appSearchTooltip.ts b/src/patches/appSearchTooltip.ts
index 2443857..e32e2ee 100644
--- a/src/patches/appSearchTooltip.ts
+++ b/src/patches/appSearchTooltip.ts
@@ -20,7 +20,7 @@ export class AppSearchTooltip extends Module {
   private _pendingActor: any = null;
   private _overviewHidingId = 0;
   private _patchedSearchAddItem: any = null;
-  private _trackedActors = new Map<any, number[]>();
+  private _trackedActors = new Set<any>();
 
   constructor(context: ExtensionContext) {
     super(context);
@@ -59,15 +59,7 @@ export class AppSearchTooltip extends Module {
     }
     this._pendingActor = null;
 
-    for (const [actor, ids] of this._trackedActors) {
-      try {
-        for (const id of ids) {
-          actor.disconnect(id);
-        }
-      } catch (_e) {
-        // actor may already be destroyed
-      }
-    }
+    for (const actor of this._trackedActors) actor.disconnectObject(this);
     this._trackedActors.clear();
 
     this._hideTooltip();
@@ -81,21 +73,26 @@ export class AppSearchTooltip extends Module {
 
     if (this._trackedActors.has(actor)) return;
 
-    const ids = [
-      actor.connect('notify::hover', () => this._onHover(actor)),
-      actor.connect('key-focus-in', () => this._onHover(actor)),
-      actor.connect('key-focus-out', () => this._onHover(actor)),
-      actor.connect('destroy', () => {
+    actor.connectObject(
+      'notify::hover',
+      () => this._onHover(actor),
+      'key-focus-in',
+      () => this._onHover(actor),
+      'key-focus-out',
+      () => this._onHover(actor),
+      'destroy',
+      () => {
         if (this._pendingActor === actor && this._showTimeoutId > 0) {
           GLib.source_remove(this._showTimeoutId);
           this._showTimeoutId = 0;
           this._pendingActor = null;
         }
         this._trackedActors.delete(actor);
-      }),
-    ];
+      },
+      this,
+    );
 
-    this._trackedActors.set(actor, ids);
+    this._trackedActors.add(actor);
   }
 
   private _onHover(actor: any): void {
diff --git a/src/patches/iconWeave.ts b/src/patches/iconWeave.ts
index 9531250..48090d7 100644
--- a/src/patches/iconWeave.ts
+++ b/src/patches/iconWeave.ts
@@ -41,7 +41,7 @@ type ActorSignalIds = {
 export class IconWeave extends Module {
   private _displayConnectionId = 0;
   private _processed = new Set<string>();
-  private _pendingConnections = new Map<any, number>();
+  private _pendingConnections = new Set<any>();
   private _actorConnections = new Map<any, ActorSignalIds>();
   private _timeoutSources = new Set<TimeoutId>();
 
@@ -186,26 +186,12 @@ export class IconWeave extends Module {
     for (const id of this._timeoutSources) GLib.source_remove(id);
     this._timeoutSources.clear();
 
-    for (const [win, id] of this._pendingConnections) {
-      try {
-        win.disconnect(id);
-      } catch (_e) {
-        // window may already be gone
-      }
-    }
+    for (const win of this._pendingConnections) win.disconnectObject(this);
     this._pendingConnections.clear();
 
     for (const [actor, { frameId, destroyId }] of this._actorConnections) {
-      try {
-        actor.disconnect(frameId);
-      } catch (_e) {
-        // actor may already be gone
-      }
-      try {
-        actor.disconnect(destroyId);
-      } catch (_e) {
-        // actor may already be gone
-      }
+      actor.disconnect(frameId);
+      actor.disconnect(destroyId);
     }
     this._actorConnections.clear();
 
@@ -273,11 +259,7 @@ export class IconWeave extends Module {
       if (done) return;
       done = true;
       this._actorConnections.delete(actor);
-      try {
-        actor.disconnect(destroyId);
-      } catch (_e) {
-        /* actor may already be gone */
-      }
+      actor.disconnect(destroyId);
       if (currentTimeoutId) {
         this._timeoutSources.delete(currentTimeoutId);
         GLib.source_remove(currentTimeoutId);
@@ -309,16 +291,8 @@ export class IconWeave extends Module {
         this._timeoutSources.delete(timeoutId);
         if (!done) {
           done = true;
-          try {
-            actor.disconnect(frameId);
-          } catch (_e) {
-            /* actor may already be gone */
-          }
-          try {
-            actor.disconnect(destroyId);
-          } catch (_e) {
-            /* actor may already be gone */
-          }
+          actor.disconnect(frameId);
+          actor.disconnect(destroyId);
           this._actorConnections.delete(actor);
           this._inspectWindow(win);
         }
@@ -348,15 +322,7 @@ export class IconWeave extends Module {
       const appId: string = win.get_gtk_application_id() ?? '';
 
       if (!wmClass && !appId) {
-        // No class info yet — wait for title which may arrive with more context
-        if (!this._pendingConnections.has(win)) {
-          const id = win.connect('notify::title', () => {
-            win.disconnect(id);
-            this._pendingConnections.delete(win);
-            this._inspectWindow(win);
-          });
-          this._pendingConnections.set(win, id);
-        }
+        this._waitForTitle(win);
         return;
       }
 
@@ -411,14 +377,7 @@ export class IconWeave extends Module {
 
       // Heuristic needs title for reliable scoring — defer until it's available.
       if (!title) {
-        if (!this._pendingConnections.has(win)) {
-          const id = win.connect('notify::title', () => {
-            win.disconnect(id);
-            this._pendingConnections.delete(win);
-            this._inspectWindow(win);
-          });
-          this._pendingConnections.set(win, id);
-        }
+        this._waitForTitle(win);
         return;
       }
 
@@ -441,6 +400,22 @@ export class IconWeave extends Module {
     }
   }
 
+  private _waitForTitle(win: any): void {
+    if (this._pendingConnections.has(win)) return;
+    this._pendingConnections.add(win);
+    win.connectObject(
+      'notify::title',
+      () => {
+        win.disconnectObject(this);
+        this._pendingConnections.delete(win);
+        this._inspectWindow(win);
+      },
+      'unmanaged',
+      () => this._pendingConnections.delete(win),
+      this,
+    );
+  }
+
   private _isValidApp(app: any): boolean {
     if (!app) return false;
     const id: string = app.get_id() ?? '';
diff --git a/src/patches/pipOnTop.manifest.ts b/src/patches/pipOnTop.manifest.ts
index 85b3388..70d5bbb 100644
--- a/src/patches/pipOnTop.manifest.ts
+++ b/src/patches/pipOnTop.manifest.ts
@@ -6,5 +6,5 @@ export const manifest: ModuleManifest = {
   settingsKey: 'module-pip-on-top',
   section: 'behavior',
   title: _('Pip On Top'),
-  subtitle: _('Keeps Picture-in-Picture windows always on top'),
+  subtitle: _('Keeps Picture-in-Picture windows above others across workspaces'),
 };
diff --git a/src/patches/pipOnTop.ts b/src/patches/pipOnTop.ts
index c161dd8..c219bda 100644
--- a/src/patches/pipOnTop.ts
+++ b/src/patches/pipOnTop.ts
@@ -1,112 +1,133 @@
 import { gettext as _ } from '~/shared/i18n.ts';
-import Meta from '@girs/meta-18';
+import type Meta from '@girs/meta-18';
 
 import type { ExtensionContext } from '~/core/context.ts';
 import { Module } from '~/module.ts';
+import {
+  enforcePipWindow,
+  isPipTitle,
+  restorePipWindow,
+  type PipWindowOwnership,
+  type PipWindowState,
+} from '~/patches/pipWindowPolicy.ts';
+
+interface TrackedWindow {
+  ownership: PipWindowOwnership | null;
+  syncing: boolean;
+}
 
-const PIP_TITLES = ['Picture-in-Picture', 'Picture in picture', 'Picture-in-picture'];
+function toWindowState(window: Meta.Window): PipWindowState {
+  return {
+    isAbove: () => window.is_above(),
+    isOnAllWorkspaces: () => window.is_on_all_workspaces(),
+    makeAbove: () => window.make_above(),
+    makeSticky: () => window.stick(),
+    unmakeAbove: () => window.unmake_above(),
+    unmakeSticky: () => window.unstick(),
+  };
+}
 
 /**
  * PipOnTop Module
  *
- * Automatically keeps Picture-in-Picture (PiP) windows above other windows.
- * It detects PiP windows based on their title and ensures they are always on top.
- * This enhances the user experience by preventing PiP windows from being accidentally hidden behind other windows.
+ * Keeps Picture-in-Picture (PiP) windows above normal windows and visible on
+ * every workspace. Mutter preserves their monitor and frame geometry.
  */
 export class PipOnTop extends Module {
-  private _lastWorkspace: any = null;
-  private _windowAddedId = 0;
-  private _windowRemovedId = 0;
+  private readonly _trackedWindows = new Map<Meta.Window, TrackedWindow>();
 
   constructor(context: ExtensionContext) {
     super(context);
   }
 
   override enable(): void {
-    global.window_manager.connectObject('switch-workspace', () => this._onSwitchWorkspace(), this);
-    this._onSwitchWorkspace();
-  }
-
-  override disable(): void {
-    global.window_manager.disconnectObject(this);
-    this._disconnectWorkspace();
+    global.display.connectObject(
+      'window-created',
+      (_display: Meta.Display, window: Meta.Window) => this._trackWindow(window),
+      this,
+    );
 
     for (const actor of global.get_window_actors()) {
-      const window = actor.meta_window as any;
-      if (!window) continue;
-      this._cleanupWindow(window);
+      const window = actor.meta_window;
+      if (window) this._trackWindow(window);
     }
   }
 
-  private _onSwitchWorkspace(): void {
-    this._disconnectWorkspace();
-
-    const workspace = global.workspace_manager.get_active_workspace();
-    this._lastWorkspace = workspace;
-
-    this._windowAddedId = workspace.connect('window-added', (_ws: any, window: any) =>
-      this._onWindowAdded(window),
-    );
-    this._windowRemovedId = workspace.connect('window-removed', (_ws: any, window: any) =>
-      this._onWindowRemoved(window),
-    );
+  override disable(): void {
+    global.display.disconnectObject(this);
 
-    const windows = global.display.get_tab_list(Meta.TabList.NORMAL, workspace);
-    if (windows) {
-      for (const window of windows) {
-        this._onWindowAdded(window);
-      }
+    for (const [window, tracked] of this._trackedWindows) {
+      this._restoreWindow(window, tracked);
+      this._safeDisconnect(window);
     }
+    this._trackedWindows.clear();
   }
 
-  private _disconnectWorkspace(): void {
-    if (this._windowAddedId) {
-      this._lastWorkspace.disconnect(this._windowAddedId);
-      this._windowAddedId = 0;
-    }
-    if (this._windowRemovedId) {
-      this._lastWorkspace.disconnect(this._windowRemovedId);
-      this._windowRemovedId = 0;
-    }
-    this._lastWorkspace = null;
+  private _trackWindow(window: Meta.Window): void {
+    if (this._trackedWindows.has(window)) return;
+
+    const tracked: TrackedWindow = {
+      ownership: null,
+      syncing: false,
+    };
+    this._trackedWindows.set(window, tracked);
+
+    window.connectObject(
+      'notify::title',
+      () => this._syncWindow(window),
+      'notify::above',
+      () => this._syncWindow(window),
+      'notify::on-all-workspaces',
+      () => this._syncWindow(window),
+      'unmanaged',
+      () => this._trackedWindows.delete(window),
+      this,
+    );
+    this._syncWindow(window);
   }
 
-  private _onWindowAdded(window: any): void {
-    if (!window._notifyPipTitleId) {
-      window._notifyPipTitleId = window.connect('notify::title', () => this._checkTitle(window));
+  private _syncWindow(window: Meta.Window): void {
+    const tracked = this._trackedWindows.get(window);
+    if (!tracked || tracked.syncing) return;
+
+    tracked.syncing = true;
+    try {
+      const state = toWindowState(window);
+      if (isPipTitle(window.get_title())) {
+        tracked.ownership = enforcePipWindow(state, tracked.ownership);
+      } else {
+        this._restoreWindowState(state, tracked);
+      }
+    } finally {
+      tracked.syncing = false;
     }
-    this._checkTitle(window);
   }
 
-  private _onWindowRemoved(window: any): void {
-    if (window._notifyPipTitleId) {
-      window.disconnect(window._notifyPipTitleId);
-      window._notifyPipTitleId = null;
+  private _restoreWindow(window: Meta.Window, tracked: TrackedWindow): void {
+    if (tracked.syncing) return;
+
+    tracked.syncing = true;
+    try {
+      this._restoreWindowState(toWindowState(window), tracked);
+    } catch {
+      // The window may have been unmanaged while the module was shutting down.
+    } finally {
+      tracked.syncing = false;
     }
   }
 
-  private _checkTitle(window: any): void {
-    if (!window.title) return;
-
-    const isPip = PIP_TITLES.some((t) => window.title === t) || window.title.endsWith(' - PiP');
+  private _restoreWindowState(state: PipWindowState, tracked: TrackedWindow): void {
+    if (!tracked.ownership) return;
 
-    if (isPip) {
-      window._isPipManaged = true;
-      if (!window.above) window.make_above();
-    } else if (window._isPipManaged) {
-      window._isPipManaged = null;
-      if (window.above) window.unmake_above();
-    }
+    restorePipWindow(state, tracked.ownership);
+    tracked.ownership = null;
   }
 
-  private _cleanupWindow(window: any): void {
-    if (window._notifyPipTitleId) {
-      window.disconnect(window._notifyPipTitleId);
-      window._notifyPipTitleId = null;
-    }
-    if (window._isPipManaged) {
-      if (window.above) window.unmake_above();
-      window._isPipManaged = null;
+  private _safeDisconnect(window: Meta.Window): void {
+    try {
+      window.disconnectObject(this);
+    } catch {
+      // The window may already have been disposed by Mutter.
     }
   }
 }
diff --git a/src/patches/pipWindowPolicy.ts b/src/patches/pipWindowPolicy.ts
new file mode 100644
index 0000000..f627a67
--- /dev/null
+++ b/src/patches/pipWindowPolicy.ts
@@ -0,0 +1,42 @@
+const PIP_TITLES = new Set(['picture-in-picture', 'picture in picture']);
+
+export interface PipWindowState {
+  isAbove(): boolean;
+  isOnAllWorkspaces(): boolean;
+  makeAbove(): void;
+  makeSticky(): void;
+  unmakeAbove(): void;
+  unmakeSticky(): void;
+}
+
+export interface PipWindowOwnership {
+  madeAbove: boolean;
+  madeSticky: boolean;
+}
+
+export function isPipTitle(title: string | null): boolean {
+  if (!title) return false;
+
+  const normalizedTitle = title.trim().toLowerCase();
+  return PIP_TITLES.has(normalizedTitle) || normalizedTitle.endsWith(' - pip');
+}
+
+export function enforcePipWindow(
+  window: PipWindowState,
+  ownership: PipWindowOwnership | null,
+): PipWindowOwnership {
+  const nextOwnership = ownership ?? {
+    madeAbove: !window.isAbove(),
+    madeSticky: !window.isOnAllWorkspaces(),
+  };
+
+  if (!window.isAbove()) window.makeAbove();
+  if (!window.isOnAllWorkspaces()) window.makeSticky();
+
+  return nextOwnership;
+}
+
+export function restorePipWindow(window: PipWindowState, ownership: PipWindowOwnership): void {
+  if (ownership.madeSticky && window.isOnAllWorkspaces()) window.unmakeSticky();
+  if (ownership.madeAbove && window.isAbove()) window.unmakeAbove();
+}
diff --git a/src/patches/velaVpnQuickSettings.ts b/src/patches/velaVpnQuickSettings.ts
index 4624bbc..926044f 100644
--- a/src/patches/velaVpnQuickSettings.ts
+++ b/src/patches/velaVpnQuickSettings.ts
@@ -74,7 +74,7 @@ export class VelaVpnQuickSettings extends Module {
       });
     };
     toggle.deactivateConnection = (activeConnection: any) => {
-      const connection = activeConnection?.connection ?? activeConnection?.get_connection?.();
+      const connection = activeConnection?.connection ?? activeConnection?.get_connection();
       this._setConnectionActive(connection, false, () => {
         this._originalDeactivateConnection?.call(this._vpnToggle, activeConnection);
       });
@@ -84,7 +84,7 @@ export class VelaVpnQuickSettings extends Module {
   }
 
   private _setConnectionActive(connection: any, active: boolean, fallback?: () => void): void {
-    const path = connection?.get_path?.();
+    const path = connection?.get_path();
     if (!path) {
       logger.warn('Cannot route VPN activation without a NetworkManager connection path', {
         prefix: LOG_PREFIX,
diff --git a/src/patches/xwaylandIndicator.ts b/src/patches/xwaylandIndicator.ts
index 0f98331..c9bc2bf 100644
--- a/src/patches/xwaylandIndicator.ts
+++ b/src/patches/xwaylandIndicator.ts
@@ -88,7 +88,7 @@ export class XwaylandIndicator extends Module {
   }
 
   private _addBadge(item: Clutter.Actor): void {
-    const iconActor = item?.get_first_child?.();
+    const iconActor = item?.get_first_child();
     if (!iconActor) return;
 
     const wrapper = new St.Widget({
diff --git a/src/privacy/dndOnShare.ts b/src/privacy/dndOnShare.ts
index f93faad..b388cbf 100644
--- a/src/privacy/dndOnShare.ts
+++ b/src/privacy/dndOnShare.ts
@@ -41,7 +41,7 @@ export class DndOnShare extends Module {
   override disable(): void {
     const indicator = getSharingIndicator();
     if (indicator) {
-      (indicator as any).disconnectObject?.(this);
+      (indicator as any).disconnectObject(this);
     }
 
     this._restoreState();
diff --git a/src/privacy/privacyPanel.ts b/src/privacy/privacyPanel.ts
index f3f7f07..ec8c06b 100644
--- a/src/privacy/privacyPanel.ts
+++ b/src/privacy/privacyPanel.ts
@@ -63,10 +63,10 @@ export class PrivacyPanel extends Module {
       this._startupCompleteId = null;
     }
 
-    this._indicator?.disconnectObject?.(this);
+    this._indicator?.disconnectObject(this);
     this._indicator = null;
 
-    Main.panel.disconnectObject?.(this);
+    Main.panel.disconnectObject(this);
 
     this._restoreAll();
     this._isSharing = false;
diff --git a/src/shared/ui/dash.ts b/src/shared/ui/dash.ts
index 9c75a86..2e88560 100644
--- a/src/shared/ui/dash.ts
+++ b/src/shared/ui/dash.ts
@@ -68,6 +68,7 @@ export class AuroraDash extends Dash {
   private _iconResizeTimeoutId = 0;
   private _targetBox: DashBounds | null = null;
   private _blockAutoHide = false;
+  private _itemDragVisibilityHold = false;
   private _dashContainerHover = false;
   private _isDestroyed = false;
   private _flushMode = false;
@@ -96,13 +97,13 @@ export class AuroraDash extends Dash {
     this.connect('notify::mapped', () => this._unredirectInhibitor.setInhibited(this.mapped));
 
     const button = (this as any).showAppsButton;
-    button?.set_toggle_mode?.(false);
-    button?.connectObject?.('clicked', () => Main.overview.showApps(), this);
+    button?.set_toggle_mode(false);
+    button?.connectObject('clicked', () => Main.overview.showApps(), this);
 
     const dashContainer = this._dashInternals._dashContainer;
-    dashContainer?.set_track_hover?.(true);
-    dashContainer?.set_reactive?.(true);
-    dashContainer?.connectObject?.(
+    dashContainer?.set_track_hover(true);
+    dashContainer?.set_reactive(true);
+    dashContainer?.connectObject(
       'notify::hover',
       () => {
         this._dashContainerHover = dashContainer.get_hover();
@@ -124,7 +125,7 @@ export class AuroraDash extends Dash {
     // preferred width every frame. Critical during drag: the placeholder
     // animates scale 0→1, so a one-shot resize would lock the container
     // at the half-scaled width.
-    (this as any)._box?.connectObject?.(
+    (this as any)._box?.connectObject(
       'notify::allocation',
       () => this._queueWorkAreaUpdate(),
       this,
@@ -164,6 +165,7 @@ export class AuroraDash extends Dash {
     this._autohideTimeoutId = this._removeSource(this._autohideTimeoutId);
     this._delayEnsureAutoHideId = this._removeSource(this._delayEnsureAutoHideId);
     this._blockAutoHideDelayId = this._removeSource(this._blockAutoHideDelayId);
+    this._itemDragVisibilityHold = false;
     this._dashContainerHover = false;
     delete this._dashInternals._dashContainer;
   }
@@ -327,14 +329,14 @@ export class AuroraDash extends Dash {
     }
     this._externalStorageIcons = [];
 
-    (this as any).showAppsButton?.disconnectObject?.(this);
-    (this as any)._box?.disconnectObject?.(this);
+    (this as any).showAppsButton?.disconnectObject(this);
+    (this as any)._box?.disconnectObject(this);
     Main.overview.disconnectObject(this);
     global.display.disconnectObject(this);
     global.workspace_manager.disconnectObject(this);
-    (this as any)._dashContainer?.disconnectObject?.(this);
-    this._container?.disconnectObject?.(this);
-    (global.backend as any).get_dnd?.()?.disconnectObject?.(this);
+    (this as any)._dashContainer?.disconnectObject(this);
+    this._container?.disconnectObject(this);
+    (global.backend as any).get_dnd().disconnectObject(this);
 
     this._container = null;
     this._targetBox = null;
@@ -389,7 +391,7 @@ export class AuroraDash extends Dash {
   attachToContainer(container: St.Bin): void {
     if (this._container === container) return;
 
-    this._container?.disconnectObject?.(this);
+    this._container?.disconnectObject(this);
     this._container = container;
 
     (container as any).connectObject?.(
@@ -406,7 +408,7 @@ export class AuroraDash extends Dash {
   }
 
   detachFromContainer(): void {
-    this._container?.disconnectObject?.(this);
+    this._container?.disconnectObject(this);
     this._container = null;
     this._targetBox = null;
     this._targetBoxListener?.(null);
@@ -498,6 +500,11 @@ export class AuroraDash extends Dash {
   }
 
   override hide(animate = true): void {
+    if (this._itemDragVisibilityHold) {
+      this.show(false);
+      return;
+    }
+
     // The chrome container remains allocated while the dash is hidden. If it
     // stays reactive, its transparent bounds win Clutter picking and create a
     // dead area over controls in windows underneath the dock.
@@ -682,21 +689,29 @@ export class AuroraDash extends Dash {
 
   // Stock Dash._init() connects item-drag-* / window-drag-* via bare
   // connect() (no disconnect on destroy), so signals keep firing after the
-  // GObject is disposed. Each override is just a disposed-guard; resize is
-  // driven by the _box notify::allocation listener in _init.
+  // GObject is disposed. The shared super call guards disposal; item dragging
+  // additionally holds visibility while the placeholder changes hover state.
   private _guardedSuper(method: string, args: any[] = []): void {
     if (this._isDestroyed) return;
     (Dash.prototype as any)[method].call(this, ...args);
   }
 
   override _onItemDragBegin(): void {
+    this._itemDragVisibilityHold =
+      !Main.overview.visible && (this.visible || this._visibilityTarget === 'shown');
+    if (this._itemDragVisibilityHold) {
+      this._autohideTimeoutId = this._removeSource(this._autohideTimeoutId);
+      this.show(false);
+    }
     this._guardedSuper('_onItemDragBegin');
   }
   override _onItemDragEnd(): void {
     this._guardedSuper('_onItemDragEnd');
+    this._releaseItemDragVisibilityHold();
   }
   override _onItemDragCancelled(): void {
     this._guardedSuper('_onItemDragCancelled');
+    this._releaseItemDragVisibilityHold();
   }
   override _onWindowDragBegin(...a: any[]): void {
     this._guardedSuper('_onWindowDragBegin', a);
@@ -1088,12 +1103,12 @@ export class AuroraDash extends Dash {
 
     (global.backend as any)
       .get_dnd?.()
-      ?.connectObject?.('dnd-leave', () => this._clearSpringLoad(), this);
+      ?.connectObject('dnd-leave', () => this._clearSpringLoad(), this);
   }
 
   private _clearSpringLoad(): void {
     try {
-      this._springLoadTarget?.remove_style_class_name?.('aurora-drag-hover');
+      this._springLoadTarget?.remove_style_class_name('aurora-drag-hover');
     } catch {
       // The target may already be disposed during shell shutdown.
     }
@@ -1108,6 +1123,10 @@ export class AuroraDash extends Dash {
     if (this._autohideTimeoutId !== 0) {
       this._autohideTimeoutId = this._removeSource(this._autohideTimeoutId);
     }
+    if (this._itemDragVisibilityHold) {
+      this.show(false);
+      return;
+    }
     this._autohideTimeoutId = GLib.timeout_add(GLib.PRIORITY_DEFAULT, AUTOHIDE_TIMEOUT, () => {
       if (this._isDestroyed) {
         this._autohideTimeoutId = 0;
@@ -1129,6 +1148,12 @@ export class AuroraDash extends Dash {
     });
   }
 
+  private _releaseItemDragVisibilityHold(): void {
+    if (!this._itemDragVisibilityHold) return;
+    this._itemDragVisibilityHold = false;
+    this._onHover();
+  }
+
   private _ensureHoverState(): void {
     if (this._isDestroyed) return;
     if (this._blockAutoHideDelayId !== 0) {
diff --git a/src/styles/stylesheet-dark.scss b/src/styles/stylesheet-dark.scss
index 424705d..2c04ac8 100644
--- a/src/styles/stylesheet-dark.scss
+++ b/src/styles/stylesheet-dark.scss
@@ -1,3 +1,5 @@
+@use 'sass:meta';
+
 @use './variables' with (
   $variant: 'dark'
 );
@@ -13,6 +15,15 @@
 @use './meeting-clock';
 @use './weather-clock';
 @use './tray-icons';
-@use './devtool';
 @use './clipboard-history';
 @use './capture-tools';
+
+$package-variant: 'production' !default;
+
+@if $package-variant != 'production' and $package-variant != 'development' {
+  @error 'Unknown package variant: #{$package-variant}';
+}
+
+@if $package-variant == 'development' {
+  @include meta.load-css('./devtool');
+}
diff --git a/src/styles/stylesheet-light.scss b/src/styles/stylesheet-light.scss
index b37bd8c..470ba28 100644
--- a/src/styles/stylesheet-light.scss
+++ b/src/styles/stylesheet-light.scss
@@ -1,3 +1,5 @@
+@use 'sass:meta';
+
 @use './variables' with (
   $variant: 'light'
 );
@@ -14,6 +16,15 @@
 @use './meeting-clock';
 @use './weather-clock';
 @use './tray-icons';
-@use './devtool';
 @use './clipboard-history';
 @use './capture-tools';
+
+$package-variant: 'production' !default;
+
+@if $package-variant != 'production' and $package-variant != 'development' {
+  @error 'Unknown package variant: #{$package-variant}';
+}
+
+@if $package-variant == 'development' {
+  @include meta.load-css('./devtool');
+}
diff --git a/src/theme/themeChanger.ts b/src/theme/themeChanger.ts
index 07a3918..1388831 100644
--- a/src/theme/themeChanger.ts
+++ b/src/theme/themeChanger.ts
@@ -44,6 +44,17 @@ export class ThemeChanger extends Module {
     }
   }
 
+  override disable(): void {
+    logger.debug('Disabling theme monitor', { prefix: LOG_PREFIX });
+
+    if (this._signalId && this._settings) {
+      this._settings.disconnect(this._signalId);
+      this._signalId = null;
+    }
+
+    this._settings = null;
+  }
+
   private _onColorSchemeChanged(): void {
     if (!this._settings) return;
 
@@ -56,15 +67,4 @@ export class ThemeChanger extends Module {
       return;
     }
   }
-
-  override disable(): void {
-    logger.debug('Disabling theme monitor', { prefix: LOG_PREFIX });
-
-    if (this._signalId && this._settings) {
-      this._settings.disconnect(this._signalId);
-      this._signalId = null;
-    }
-
-    this._settings = null;
-  }
 }
diff --git a/tests/shell/auroraCaptureTools.js b/tests/shell/auroraCaptureTools.js
index 2407ead..2492d6a 100644
--- a/tests/shell/auroraCaptureTools.js
+++ b/tests/shell/auroraCaptureTools.js
@@ -40,6 +40,10 @@ export var METRICS = {};
 export function init() {
   Scripting.defineScriptEvent('attachedOnce', 'Capture toolbar and canvas attached exactly once');
   Scripting.defineScriptEvent('visibleOnOpen', 'Floating toolbar visible immediately on open');
+  Scripting.defineScriptEvent(
+    'externalMonitorPlacement',
+    'Floating toolbar follows a selection onto an external monitor',
+  );
   Scripting.defineScriptEvent('drawingMode', 'Drawing tool activates the capture canvas');
   Scripting.defineScriptEvent(
     'lifecycleRestored',
@@ -138,8 +142,49 @@ export async function run() {
   await ui.open();
   await Scripting.sleep(350);
   if (!toolbar.visible) throw new Error('Capture toolbar is hidden after opening ScreenshotUI');
+  if (!toolbar.mapped) throw new Error('Capture toolbar is not mapped after opening ScreenshotUI');
+  if (![toolbar.translation_x, toolbar.translation_y].every(Number.isFinite))
+    throw new Error('Capture toolbar produced a non-finite translation');
   if (!toolbar.has_style_class_name('screenshot-ui-panel'))
     throw new Error('Capture toolbar does not use the native screenshot panel styling');
+
+  const externalMonitor = Main.layoutManager.monitors.find(
+    (_monitor, index) => index !== Main.layoutManager.primaryIndex,
+  );
+  if (externalMonitor) {
+    const originalSelection = [
+      ui._areaSelector._startX,
+      ui._areaSelector._startY,
+      ui._areaSelector._lastX,
+      ui._areaSelector._lastY,
+    ];
+    ui._areaSelector._startX = externalMonitor.x + Math.floor(externalMonitor.width / 4);
+    ui._areaSelector._startY = externalMonitor.y + Math.floor(externalMonitor.height / 4);
+    ui._areaSelector._lastX = externalMonitor.x + Math.floor((externalMonitor.width * 3) / 4);
+    ui._areaSelector._lastY = externalMonitor.y + Math.floor((externalMonitor.height * 3) / 4);
+    ui._areaSelector._updateSelectionRect();
+    ui._areaSelector.emit('drag-ended');
+    await Scripting.sleep(250);
+    const [externalToolbarX, externalToolbarY] = toolbar.get_transformed_position();
+    if (
+      externalToolbarX < externalMonitor.x ||
+      externalToolbarX + toolbar.width > externalMonitor.x + externalMonitor.width ||
+      externalToolbarY < externalMonitor.y ||
+      externalToolbarY + toolbar.height > externalMonitor.y + externalMonitor.height
+    )
+      throw new Error('Capture toolbar did not follow the selection onto the external monitor');
+    [
+      ui._areaSelector._startX,
+      ui._areaSelector._startY,
+      ui._areaSelector._lastX,
+      ui._areaSelector._lastY,
+    ] = originalSelection;
+    ui._areaSelector._updateSelectionRect();
+    ui._areaSelector.emit('drag-ended');
+    await Scripting.sleep(250);
+  }
+  Scripting.scriptEvent('externalMonitorPlacement');
+
   const colorButtons = findActors(toolbar, COLOR_BUTTON_CLASS);
   const selectedColorButtons = colorButtons.filter((button) => button.checked);
   const activeColor = settings.get_string('capture-tools-color');
@@ -198,7 +243,7 @@ export async function run() {
   if (toolbar.opacity !== 255 || ui._panel.opacity !== 255 || ui._closeButton.opacity !== 255)
     throw new Error('Capture and native control opacity was not restored after drawing');
   pointerButton.emit('clicked', pointerButton);
-  if (canvas.reactive) throw new Error('Pointer tool did not release the capture canvas');
+  if (!canvas.reactive) throw new Error('Pointer tool did not activate annotation movement');
   const textButton = findActors(toolbar, TEXT_TOOL_CLASS)[0];
   textButton.emit('clicked', textButton);
   canvas._requestText({ x: 320, y: 240 });
@@ -253,6 +298,7 @@ export async function run() {
 
 let _attachedOnce = false;
 let _visibleOnOpen = false;
+let _externalMonitorPlacement = false;
 let _drawingMode = false;
 let _lifecycleRestored = false;
 
@@ -264,6 +310,10 @@ export function script_visibleOnOpen() {
   _visibleOnOpen = true;
 }
 
+export function script_externalMonitorPlacement() {
+  _externalMonitorPlacement = true;
+}
+
 export function script_drawingMode() {
   _drawingMode = true;
 }
@@ -275,6 +325,8 @@ export function script_lifecycleRestored() {
 export function finish() {
   if (!_attachedOnce) throw new Error('Capture Tools attachment was not verified');
   if (!_visibleOnOpen) throw new Error('Immediate toolbar visibility was not verified');
+  if (!_externalMonitorPlacement)
+    throw new Error('External-monitor toolbar placement was not verified');
   if (!_drawingMode) throw new Error('Capture Tools drawing mode was not verified');
   if (!_lifecycleRestored) throw new Error('Capture Tools lifecycle restoration was not verified');
 }
diff --git a/tests/shell/auroraDock.js b/tests/shell/auroraDock.js
index aacd183..449cd62 100644
--- a/tests/shell/auroraDock.js
+++ b/tests/shell/auroraDock.js
@@ -78,6 +78,10 @@ export function init() {
     'repeatedShowStable',
     'Repeated show requests do not restart the dock animation',
   );
+  Scripting.defineScriptEvent(
+    'itemDragKeepsDockStable',
+    'Favorite reordering holds the Dock visible and restores auto-hide after drop',
+  );
   Scripting.defineScriptEvent(
     'blockedOverlapDefersHide',
     'Intellihide BLOCKED keeps the dock while hovered and hides after leave',
@@ -102,6 +106,10 @@ export function init() {
     'intellihideFlapDebounced',
     'Transient geometry flaps coalesce into a single settled status',
   );
+  Scripting.defineScriptEvent(
+    'pipSmartRevealPolicySynced',
+    'Intellihide follows the PiP module setting without rebuilding the Dock',
+  );
   Scripting.defineScriptEvent(
     'externalWorkspaceActorStable',
     'Intellihide keeps the dock actor stable on external monitors in workspace two',
@@ -126,6 +134,14 @@ export function init() {
     'iconResizeCountsFixedIcons',
     'Automatic icon resize accounts for trash/storage icons outside _box',
   );
+  Scripting.defineScriptEvent(
+    'motionTextureSupersampled',
+    'Dock motion keeps high-resolution icon textures in a normal-sized layout box',
+  );
+  Scripting.defineScriptEvent(
+    'fixedIconMotionRegistered',
+    'Trash and removable-storage icons are registered with dock motion',
+  );
   Scripting.defineScriptEvent('dockRemoved', 'Dock actor removed from stage after disable');
 }
 
@@ -140,11 +156,16 @@ export async function run() {
   const originalAlwaysShow = settings.get_boolean('dock-always-show');
   const originalIntellihide = settings.get_boolean('dock-intellihide');
   const originalShowOnAllMonitors = settings.get_boolean('dock-show-on-all-monitors');
+  const originalMotionEnabled = settings.get_boolean('dock-motion-enabled');
+  const originalMotionProfile = settings.get_string('dock-motion-profile');
+  const originalPipOnTop = settings.get_boolean('module-pip-on-top');
   settings.set_boolean('dock-show-trash', true);
   settings.set_boolean('dock-show-external-storage', false);
   settings.set_boolean('dock-always-show', false);
   settings.set_boolean('dock-intellihide', true);
   settings.set_boolean('dock-show-on-all-monitors', false);
+  settings.set_boolean('dock-motion-enabled', true);
+  settings.set_string('dock-motion-profile', 'balanced');
 
   await Scripting.waitLeisure();
   await Scripting.sleep(500);
@@ -260,7 +281,9 @@ export async function run() {
   }
 
   if (dash._externalStorageIcons?.length)
-    throw new Error('External storage icons were created while dock-show-external-storage is disabled');
+    throw new Error(
+      'External storage icons were created while dock-show-external-storage is disabled',
+    );
 
   Scripting.scriptEvent('externalStorageDisabled');
 
@@ -296,6 +319,28 @@ export async function run() {
       );
     }
 
+    const customFixedIcons = [dash._trashIcon, ...(dash._externalStorageIcons ?? [])].filter(
+      Boolean,
+    );
+    if (customFixedIcons.length === 0)
+      throw new Error('Dock motion test could not create a fixed Trash or storage icon');
+    for (const fixedIcon of customFixedIcons) {
+      const baseIcon = fixedIcon.icon;
+      const texture = baseIcon?._iconBin?.child;
+      if (
+        !texture ||
+        texture.icon_size < baseIcon.iconSize * 2 ||
+        texture.min_width !== baseIcon.iconSize ||
+        texture.natural_height !== baseIcon.iconSize
+      ) {
+        throw new Error(
+          `Fixed dock icon was not supersampled without changing layout: normal=${baseIcon?.iconSize} texture=${texture?.icon_size} actor=${texture?.min_width}x${texture?.natural_height}`,
+        );
+      }
+    }
+    Scripting.scriptEvent('motionTextureSupersampled');
+    Scripting.scriptEvent('fixedIconMotionRegistered');
+
     const boxIconChildren = dash._box
       .get_children()
       .filter((actor) => actor.child?._delegate?.icon && !actor.animatingOut);
@@ -326,9 +371,7 @@ export async function run() {
     const scaleFactor = St.ThemeContext.get_for_stage(global.stage).scale_factor;
     const targetIconSize = 31 * scaleFactor;
     const maxWidth = Math.ceil(
-      totalIcons * (iconPadding + targetIconSize) +
-        (totalIcons - 1) * spacing +
-        horizontalChrome,
+      totalIcons * (iconPadding + targetIconSize) + (totalIcons - 1) * spacing + horizontalChrome,
     );
 
     dash.setMaxSize(maxWidth, priorMaxHeight > 0 ? priorMaxHeight : 400);
@@ -405,9 +448,7 @@ export async function run() {
     }
 
     for (const externalBinding of externalBindings) {
-      const windowsBefore = new Set(
-        global.get_window_actors().map((actor) => actor.meta_window),
-      );
+      const windowsBefore = new Set(global.get_window_actors().map((actor) => actor.meta_window));
       await Scripting.createTestWindow({ width: 900, height: 650, maximized: false });
       await Scripting.waitTestWindows();
       await Scripting.sleep(200);
@@ -435,9 +476,7 @@ export async function run() {
 
         const stableBounds = externalBinding.dash.targetBox;
         if (!stableBounds) {
-          throw new Error(
-            `Dock on monitor ${externalBinding.monitorIndex} lost its target bounds`,
-          );
+          throw new Error(`Dock on monitor ${externalBinding.monitorIndex} lost its target bounds`);
         }
 
         for (let sample = 0; sample < 8; sample++) {
@@ -501,8 +540,48 @@ export async function run() {
 
   Scripting.scriptEvent('repeatedShowStable');
 
+  const originalItemDragHover = dash._dashContainerHasHover;
+  try {
+    dash._dashContainerHasHover = () => false;
+    dash.blockAutoHide(false);
+    dash.show(false);
+    dash._onItemDragBegin();
+    dash.hide(false);
+    await Scripting.sleep(300);
+    if (!dash.visible || dash.opacity !== 255 || dash.translation_y !== 0)
+      throw new Error('Dock hid while a favorite icon drag was active');
+
+    dash._onItemDragEnd();
+    await Scripting.sleep(400);
+    if (dash.visible) throw new Error('Dock did not restore auto-hide after the icon drop');
+
+    dash.show(false);
+    dash._onItemDragBegin();
+    dash._onItemDragCancelled();
+    await Scripting.sleep(400);
+    if (dash.visible) throw new Error('Dock did not restore auto-hide after cancelling icon drag');
+  } finally {
+    if (dash._itemDragVisibilityHold) dash._onItemDragCancelled();
+    dash._dashContainerHasHover = originalItemDragHover;
+    dash.blockAutoHide(true);
+    dash.show(false);
+  }
+  Scripting.scriptEvent('itemDragKeepsDockStable');
+
   const binding = dock.bindings[0];
 
+  settings.set_boolean('module-pip-on-top', false);
+  await Scripting.waitLeisure();
+  if (binding.intellihide?._excludePipFromSmartReveal)
+    throw new Error('Intellihide kept excluding PiP after the PiP module was disabled');
+
+  settings.set_boolean('module-pip-on-top', true);
+  await Scripting.waitLeisure();
+  if (!binding.intellihide?._excludePipFromSmartReveal)
+    throw new Error('Intellihide did not exclude PiP after the PiP module was enabled');
+
+  Scripting.scriptEvent('pipSmartRevealPolicySynced');
+
   // I7 — a direct intellihide BLOCKED transition from a visible dock must hand
   // off to hover autohide. This covers switching from a small window to a
   // fullscreen window via the dock: the dock must stay up while the pointer is
@@ -555,8 +634,7 @@ export async function run() {
   } finally {
     dash._dashContainerHasHover = originalHoldZoneDashContainerHasHover;
   }
-  if (!dash.visible)
-    throw new Error('Native autohide hid the dock while the pointer was over it');
+  if (!dash.visible) throw new Error('Native autohide hid the dock while the pointer was over it');
   if (!binding.hotAreaActive)
     throw new Error('Hot-area reveal ended while the pointer was over the dock');
   if (binding.autoHideReleaseId !== 0)
@@ -577,8 +655,7 @@ export async function run() {
   binding.intellihide.emit('status-changed');
   await Scripting.sleep(350);
   if (!dash.visible) throw new Error('Hot-area active CLEAR did not show the dock');
-  if (binding.hotAreaActive)
-    throw new Error('Hot-area active CLEAR did not end the reveal state');
+  if (binding.hotAreaActive) throw new Error('Hot-area active CLEAR did not end the reveal state');
   if (binding.hotArea?.reactive)
     throw new Error('Hot-area active CLEAR left the hot area reactive over the dock');
 
@@ -693,8 +770,7 @@ export async function run() {
   } finally {
     dash._dashContainerHasHover = originalReassertHasHover;
   }
-  if (dash.visible)
-    throw new Error('Focus reassert did not hide the dock after the pointer left');
+  if (dash.visible) throw new Error('Focus reassert did not hide the dock after the pointer left');
   if (binding.hotAreaActive)
     throw new Error('Focus reassert left the hot-area reveal active after the pointer left');
 
@@ -806,6 +882,9 @@ export async function run() {
   settings.set_boolean('dock-always-show', originalAlwaysShow);
   settings.set_boolean('dock-intellihide', originalIntellihide);
   settings.set_boolean('dock-show-on-all-monitors', originalShowOnAllMonitors);
+  settings.set_boolean('dock-motion-enabled', originalMotionEnabled);
+  settings.set_string('dock-motion-profile', originalMotionProfile);
+  settings.set_boolean('module-pip-on-top', originalPipOnTop);
   settings.set_boolean('module-dock', originalValue);
   await Scripting.waitLeisure();
   await Scripting.sleep(300);
@@ -820,12 +899,15 @@ let _hotAreaYieldedInput = false;
 let _hotAreaReleaseDeferred = false;
 let _hotAreaRearmedAfterHide = false;
 let _repeatedShowStable = false;
+let _itemDragKeepsDockStable = false;
 let _blockedOverlapDefersHide = false;
 let _hotAreaActiveBlockedHidesDock = false;
 let _hotAreaActiveClearShowsDock = false;
 let _dockRemoved = false;
 let _externalStorageDisabled = false;
 let _iconResizeCountsFixedIcons = false;
+let _motionTextureSupersampled = false;
+let _fixedIconMotionRegistered = false;
 let _externalWorkspaceActorStable = false;
 let _primaryMonitorOnly = false;
 let _allMonitorsEnabled = false;
@@ -876,6 +958,11 @@ export function script_repeatedShowStable() {
   _repeatedShowStable = true;
 }
 
+/** @returns {void} */
+export function script_itemDragKeepsDockStable() {
+  _itemDragKeepsDockStable = true;
+}
+
 /** @returns {void} */
 export function script_blockedOverlapDefersHide() {
   _blockedOverlapDefersHide = true;
@@ -906,6 +993,16 @@ export function script_iconResizeCountsFixedIcons() {
   _iconResizeCountsFixedIcons = true;
 }
 
+/** @returns {void} */
+export function script_motionTextureSupersampled() {
+  _motionTextureSupersampled = true;
+}
+
+/** @returns {void} */
+export function script_fixedIconMotionRegistered() {
+  _fixedIconMotionRegistered = true;
+}
+
 /** @returns {void} */
 export function script_externalWorkspaceActorStable() {
   _externalWorkspaceActorStable = true;
@@ -939,8 +1036,9 @@ export function finish() {
     throw new Error('Hot-area release did not stay visible while pointer was inside the dock');
   if (!_hotAreaRearmedAfterHide)
     throw new Error('Hot area was not rearmed after the dock hide transition');
-  if (!_repeatedShowStable)
-    throw new Error('Repeated show requests restarted the dock animation');
+  if (!_repeatedShowStable) throw new Error('Repeated show requests restarted the dock animation');
+  if (!_itemDragKeepsDockStable)
+    throw new Error('Favorite icon dragging did not preserve and restore Dock visibility');
   if (!_blockedOverlapDefersHide)
     throw new Error('Intellihide BLOCKED did not defer hiding while hovered');
   if (!_hotAreaActiveBlockedHidesDock)
@@ -951,12 +1049,14 @@ export function finish() {
     throw new Error('External storage icons were not verified disabled');
   if (!_iconResizeCountsFixedIcons)
     throw new Error('Automatic icon resize did not account for fixed dock icons');
+  if (!_motionTextureSupersampled)
+    throw new Error('Dock motion icon textures were not verified at high resolution');
+  if (!_fixedIconMotionRegistered)
+    throw new Error('Trash and removable-storage icons were not registered with dock motion');
   if (!_externalWorkspaceActorStable)
     throw new Error('External-monitor Dock actor did not remain stable in workspace two');
-  if (!_primaryMonitorOnly)
-    throw new Error('Dock primary-monitor-only behavior was not verified');
-  if (!_allMonitorsEnabled)
-    throw new Error('Dock all-monitors opt-in behavior was not verified');
+  if (!_primaryMonitorOnly) throw new Error('Dock primary-monitor-only behavior was not verified');
+  if (!_allMonitorsEnabled) throw new Error('Dock all-monitors opt-in behavior was not verified');
   if (!_alwaysAutoHideIndependent)
     throw new Error('Dock always auto-hide behavior was not verified');
   if (!_dockRemoved) throw new Error('Dock actor was not removed after module was disabled');
diff --git a/tests/unit/annotationModel.test.ts b/tests/unit/annotationModel.test.ts
index 28baff4..ba86aa4 100644
--- a/tests/unit/annotationModel.test.ts
+++ b/tests/unit/annotationModel.test.ts
@@ -64,9 +64,80 @@ test('annotation settings and capture transforms are bounded and deterministic',
   });
 });
 
-test('pointer tool does not start an annotation stroke', () => {
+test('pointer tool ignores empty space', () => {
   const model = new AnnotationModel();
   model.setTool('pointer');
   assert.equal(model.begin({ x: 10, y: 10 }), false);
   assert.equal(model.hasAnnotations, false);
 });
+
+test('pointer tool moves every supported annotation geometry', () => {
+  const cases = [
+    { tool: 'freehand', hit: { x: 15, y: 15 } },
+    { tool: 'highlighter', hit: { x: 15, y: 15 } },
+    { tool: 'arrow', hit: { x: 15, y: 15 } },
+    { tool: 'rectangle', hit: { x: 15, y: 15 } },
+    { tool: 'solid-rectangle', hit: { x: 15, y: 15 } },
+  ] as const;
+
+  for (const { tool, hit } of cases) {
+    const model = new AnnotationModel();
+    model.setTool(tool);
+    model.begin({ x: 10, y: 10 });
+    model.update({ x: 20, y: 20 });
+    model.finish();
+    assertMovedBy(model, hit, { x: 7, y: -3 });
+  }
+
+  const text = new AnnotationModel();
+  text.addText({ x: 10, y: 10 }, 'Aurora');
+  assertMovedBy(text, { x: 20, y: 20 }, { x: 7, y: -3 });
+
+  const stamp = new AnnotationModel();
+  stamp.setTool('stamp');
+  stamp.begin({ x: 10, y: 10 });
+  assertMovedBy(stamp, { x: 10, y: 10 }, { x: 7, y: -3 });
+});
+
+test('pointer tool moves the topmost annotation and restores a cancelled drag', () => {
+  const model = new AnnotationModel();
+  model.setTool('solid-rectangle');
+  model.begin({ x: 0, y: 0 });
+  model.update({ x: 30, y: 30 });
+  model.finish();
+  model.begin({ x: 10, y: 10 });
+  model.update({ x: 40, y: 40 });
+  model.finish();
+
+  const firstBefore = structuredClone(model.annotations[0]!.points);
+  const secondBefore = structuredClone(model.annotations[1]!.points);
+  model.setTool('pointer');
+  assert.equal(model.begin({ x: 20, y: 20 }), true);
+  model.update({ x: 25, y: 27 });
+  assert.deepEqual(model.annotations[0]!.points, firstBefore);
+  assert.deepEqual(model.annotations[1]!.points, offsetPoints(secondBefore, 5, 7));
+
+  model.setTool('rectangle');
+  assert.deepEqual(model.annotations[1]!.points, secondBefore);
+});
+
+function assertMovedBy(
+  model: AnnotationModel,
+  hit: { x: number; y: number },
+  offset: { x: number; y: number },
+): void {
+  const before = structuredClone(model.annotations[0]!.points);
+  model.setTool('pointer');
+  assert.equal(model.begin(hit), true);
+  assert.equal(model.update({ x: hit.x + offset.x, y: hit.y + offset.y }), true);
+  assert.equal(model.finish(), true);
+  assert.deepEqual(model.annotations[0]!.points, offsetPoints(before, offset.x, offset.y));
+}
+
+function offsetPoints(
+  points: readonly { x: number; y: number }[],
+  offsetX: number,
+  offsetY: number,
+): { x: number; y: number }[] {
+  return points.map((point) => ({ x: point.x + offsetX, y: point.y + offsetY }));
+}
diff --git a/tests/unit/dockMotionCatalog.test.ts b/tests/unit/dockMotionCatalog.test.ts
new file mode 100644
index 0000000..ceccaa0
--- /dev/null
+++ b/tests/unit/dockMotionCatalog.test.ts
@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import {
+  DEFAULT_PROFILE,
+  Profile,
+  getBuiltInRecipe,
+  isBuiltInProfile,
+} from '../../src/dock/motion/catalog.ts';
+
+test('dock motion catalog — Subtle is the default profile', () => {
+  assert.equal(DEFAULT_PROFILE, Profile.SUBTLE);
+});
+
+test('dock motion catalog — recognizes only the three built-in profiles', () => {
+  assert.equal(isBuiltInProfile('subtle'), true);
+  assert.equal(isBuiltInProfile('balanced'), true);
+  assert.equal(isBuiltInProfile('expressive'), true);
+  assert.equal(isBuiltInProfile('custom'), false);
+  assert.equal(isBuiltInProfile('nonsense'), false);
+});
+
+test('dock motion catalog — falls back to the default profile for unknown ids', () => {
+  assert.deepEqual(getBuiltInRecipe('nonsense'), getBuiltInRecipe(DEFAULT_PROFILE));
+});
+
+test('dock motion catalog — Subtle gives only the selected icon a gentle hover', () => {
+  const recipe = getBuiltInRecipe(Profile.SUBTLE);
+  assert.equal(recipe.hover.enabled, true);
+  assert.equal(recipe.hover.scale, 1.05);
+  assert.equal(recipe.hover.lift, 0);
+  assert.equal(recipe.hover.neighborScale, 1);
+  assert.equal(recipe.press.enabled, true);
+  assert.equal(recipe.press.mode, 'all-primary-clicks');
+});
+
+test('dock motion catalog — Balanced only grows the selected icon', () => {
+  const recipe = getBuiltInRecipe(Profile.BALANCED);
+  assert.equal(recipe.hover.enabled, true);
+  assert.equal(recipe.hover.scale, 1.1);
+  assert.ok(recipe.hover.duration >= 180);
+  assert.equal(recipe.hover.neighborScale, 1);
+  assert.equal(recipe.press.mode, 'launches-only');
+});
+
+test('dock motion catalog — Expressive is stronger without overlapping neighboring icons', () => {
+  const recipe = getBuiltInRecipe(Profile.EXPRESSIVE);
+  assert.ok(recipe.hover.scale > getBuiltInRecipe(Profile.BALANCED).hover.scale);
+  assert.equal(recipe.hover.scale, 1.15);
+  assert.equal(recipe.hover.lift, 0);
+  assert.equal(recipe.hover.neighborScale, 1);
+  assert.equal(recipe.hover.easing, 'ease-out-cubic');
+});
+
+test('dock motion catalog — recipes are independent copies, not shared references', () => {
+  const first = getBuiltInRecipe(Profile.BALANCED);
+  const second = getBuiltInRecipe(Profile.BALANCED);
+  first.hover.scale = 999;
+  assert.notEqual(second.hover.scale, 999);
+});
diff --git a/tests/unit/dockMotionPressInteraction.test.ts b/tests/unit/dockMotionPressInteraction.test.ts
new file mode 100644
index 0000000..a9e4da8
--- /dev/null
+++ b/tests/unit/dockMotionPressInteraction.test.ts
@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { getBuiltInRecipe, Profile } from '../../src/dock/motion/catalog.ts';
+import { PressInteraction } from '../../src/dock/motion/pressInteraction.ts';
+
+test('press interaction — ALL_PRIMARY_CLICKS presses immediately regardless of launch state', () => {
+  const { press } = getBuiltInRecipe(Profile.EXPRESSIVE); // all-primary-clicks
+  const interaction = new PressInteraction();
+  assert.equal(interaction.beginPrimary(press, false), true);
+  assert.equal(interaction.pressed, true);
+});
+
+test('press interaction — LAUNCHES_ONLY stays idle for clicks on a running app', () => {
+  const { press } = getBuiltInRecipe(Profile.BALANCED); // launches-only
+  const interaction = new PressInteraction();
+  assert.equal(interaction.beginPrimary(press, false), false);
+  assert.equal(interaction.pressed, false);
+});
+
+test('press interaction — LAUNCHES_ONLY presses for a click that starts a stopped app', () => {
+  const { press } = getBuiltInRecipe(Profile.BALANCED);
+  const interaction = new PressInteraction();
+  assert.equal(interaction.beginPrimary(press, true), true);
+  assert.equal(interaction.pressed, true);
+});
+
+test('press interaction — finishClick releases an active press exactly once', () => {
+  const { press } = getBuiltInRecipe(Profile.EXPRESSIVE);
+  const interaction = new PressInteraction();
+  interaction.beginPrimary(press, false);
+  assert.equal(interaction.finishClick(), true);
+  assert.equal(interaction.pressed, false);
+  assert.equal(interaction.finishClick(), false); // already released, no change
+});
+
+test('press interaction — syncButtonPressed releases an early drag-out before click fires', () => {
+  const { press } = getBuiltInRecipe(Profile.EXPRESSIVE);
+  const interaction = new PressInteraction();
+  interaction.beginPrimary(press, false);
+  assert.equal(interaction.syncButtonPressed(true), false); // still held, no change
+  assert.equal(interaction.syncButtonPressed(false), true); // released outside the icon
+  assert.equal(interaction.pressed, false);
+});
+
+test('press interaction — reset clears an in-progress press (e.g. pointer leaves)', () => {
+  const { press } = getBuiltInRecipe(Profile.EXPRESSIVE);
+  const interaction = new PressInteraction();
+  interaction.beginPrimary(press, false);
+  assert.equal(interaction.reset(), true);
+  assert.equal(interaction.pressed, false);
+});
+
+test('press interaction — disabled press config never presses', () => {
+  const { press } = getBuiltInRecipe(Profile.EXPRESSIVE);
+  const interaction = new PressInteraction();
+  assert.equal(interaction.beginPrimary({ ...press, enabled: false }, true), false);
+  assert.equal(interaction.pressed, false);
+});
diff --git a/tests/unit/dockMotionTransforms.test.ts b/tests/unit/dockMotionTransforms.test.ts
new file mode 100644
index 0000000..d184a23
--- /dev/null
+++ b/tests/unit/dockMotionTransforms.test.ts
@@ -0,0 +1,109 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { getBuiltInRecipe, Profile, PressEffect } from '../../src/dock/motion/catalog.ts';
+import {
+  dimOpacity,
+  fitHoverToBudget,
+  hoverNeedsBudget,
+  neighborScaleAt,
+  resolveIconTransform,
+  resolvePressTransform,
+  textureRenderSize,
+} from '../../src/dock/motion/transforms.ts';
+
+test('transforms — squash press shrinks the vertical axis toward the dock', () => {
+  const identity = resolvePressTransform(PressEffect.SQUASH, 0);
+  assert.equal(identity.scaleY, 1);
+  const pressed = resolvePressTransform(PressEffect.SQUASH, 1);
+  assert.ok(pressed.scaleY < 1);
+  assert.equal(pressed.scaleX, 1);
+});
+
+test('transforms — dim press only changes opacity, not geometry', () => {
+  const pressed = resolvePressTransform(PressEffect.DIM, 1);
+  assert.equal(pressed.scaleX, 1);
+  assert.equal(pressed.scaleY, 1);
+  assert.ok(pressed.dim > 0);
+});
+
+test('transforms — dimOpacity scales down from the original, clamped to [0, 1]', () => {
+  assert.equal(dimOpacity(255, 0), 255);
+  assert.equal(dimOpacity(255, 1), 0);
+  assert.equal(dimOpacity(200, 0.5), 100);
+});
+
+test('transforms — neighborScaleAt fades linearly to identity past the radius', () => {
+  const hover = {
+    ...getBuiltInRecipe(Profile.EXPRESSIVE).hover,
+    neighborScale: 1.08,
+    neighborRadius: 2,
+  };
+  assert.equal(neighborScaleAt(hover, 0), 1); // the hovered icon itself is not a "neighbor"
+  assert.ok(neighborScaleAt(hover, 1) > neighborScaleAt(hover, 2));
+  assert.equal(neighborScaleAt(hover, 3), 1); // beyond the radius
+});
+
+test('transforms — fitHoverToBudget leaves room untouched when it already fits', () => {
+  const fitted = fitHoverToBudget(1.1, 5, 48, 1000);
+  assert.equal(fitted.hoverScale, 1.1);
+  assert.equal(fitted.lift, 5);
+});
+
+test('transforms — fitHoverToBudget shrinks scale and lift proportionally when clipped', () => {
+  const fitted = fitHoverToBudget(1.5, 10, 48, 12);
+  const reachBefore = 48 * 0.5 + 10;
+  const reachAfter = 48 * (fitted.hoverScale - 1) + fitted.lift;
+  assert.ok(Math.abs(reachAfter - 12) < 1e-6);
+  assert.ok(reachAfter < reachBefore);
+});
+
+test('transforms — Subtle has a visible but gentler hover than Balanced', () => {
+  const recipe = getBuiltInRecipe(Profile.SUBTLE);
+  const transform = resolveIconTransform({ recipe, hovered: true });
+  assert.equal(hoverNeedsBudget({ recipe, hovered: true }), true);
+  assert.equal(transform.scaleX, 1.05);
+  assert.ok(transform.scaleX < getBuiltInRecipe(Profile.BALANCED).hover.scale);
+});
+
+test('transforms — resolveIconTransform is identity when animations are globally off', () => {
+  const recipe = getBuiltInRecipe(Profile.EXPRESSIVE);
+  const transform = resolveIconTransform({ recipe, hovered: true, animationsEnabled: false });
+  assert.equal(transform.scaleX, 1);
+  assert.equal(transform.scaleY, 1);
+  assert.equal(transform.translationY, 0);
+});
+
+test('transforms — resolveIconTransform scales and lifts on hover for Balanced', () => {
+  const recipe = getBuiltInRecipe(Profile.BALANCED);
+  const transform = resolveIconTransform({ recipe, hovered: true });
+  assert.equal(transform.scaleX, 1.1);
+  assert.equal(transform.scaleY, 1.1);
+});
+
+test('transforms — Balanced leaves neighboring icons at their normal size', () => {
+  const recipe = getBuiltInRecipe(Profile.BALANCED);
+  const transform = resolveIconTransform({ recipe, neighborDistance: 1 });
+  assert.equal(transform.scaleX, 1);
+  assert.equal(transform.scaleY, 1);
+});
+
+test('transforms — Expressive leaves neighboring icons at their normal size', () => {
+  const recipe = getBuiltInRecipe(Profile.EXPRESSIVE);
+  const transform = resolveIconTransform({ recipe, neighborDistance: 1 });
+  assert.equal(transform.scaleX, 1);
+  assert.equal(transform.scaleY, 1);
+  assert.equal(transform.translationY, 0);
+});
+
+test('transforms — textureRenderSize uses 2x pixels for smooth hover magnification', () => {
+  const recipe = getBuiltInRecipe(Profile.BALANCED);
+  assert.equal(textureRenderSize(48, recipe), 96);
+  assert.ok(textureRenderSize(48, recipe) >= 48 * recipe.hover.scale);
+});
+
+test('transforms — textureRenderSize stays at the normal size when hover is disabled', () => {
+  const recipe = getBuiltInRecipe(Profile.SUBTLE);
+  recipe.hover.enabled = false;
+  assert.equal(textureRenderSize(48, recipe), 48);
+});
diff --git a/tests/unit/egoPolicy.test.ts b/tests/unit/egoPolicy.test.ts
new file mode 100644
index 0000000..70b4162
--- /dev/null
+++ b/tests/unit/egoPolicy.test.ts
@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import test from 'node:test';
+import ts from 'typescript';
+
+const sourceRoot = resolve('src');
+
+function sourceFiles(directory: string): string[] {
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) return sourceFiles(path);
+    return entry.name.endsWith('.ts') || entry.name.endsWith('.scss') ? [path] : [];
+  });
+}
+
+test('source lines stay within the EGO 200-character limit', () => {
+  const violations: string[] = [];
+  for (const file of sourceFiles(sourceRoot)) {
+    const lines = readFileSync(file, 'utf8').split(/\r?\n/u);
+    for (const [index, line] of lines.entries()) {
+      if (line.length > 200)
+        violations.push(`${file.slice(sourceRoot.length + 1)}:${index + 1} (${line.length})`);
+    }
+  }
+  assert.deepEqual(violations, []);
+});
+
+test('widgets override destroy instead of observing their own destroy signal', () => {
+  const violations: string[] = [];
+  for (const file of sourceFiles(sourceRoot).filter((path) => path.endsWith('.ts'))) {
+    const source = readFileSync(file, 'utf8');
+    if (/\bthis\.connect\(\s*['"]destroy['"]/u.test(source))
+      violations.push(file.slice(sourceRoot.length + 1));
+  }
+  assert.deepEqual(violations, []);
+});
+
+test('module enable and disable methods remain adjacent', () => {
+  const violations: string[] = [];
+  for (const file of sourceFiles(sourceRoot).filter((path) => path.endsWith('.ts'))) {
+    const source = readFileSync(file, 'utf8');
+    const tree = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+    const visit = (node: ts.Node): void => {
+      if (
+        ts.isClassDeclaration(node) &&
+        node.heritageClauses?.some((clause) =>
+          clause.types.some((type) => type.expression.getText(tree) === 'Module'),
+        )
+      ) {
+        const methods = node.members
+          .filter(ts.isMethodDeclaration)
+          .map((method) => method.name.getText(tree));
+        const enableIndex = methods.indexOf('enable');
+        const disableIndex = methods.indexOf('disable');
+        if (enableIndex >= 0 && disableIndex !== enableIndex + 1)
+          violations.push(file.slice(sourceRoot.length + 1));
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(tree);
+  }
+  assert.deepEqual(violations, []);
+});
+
+test('new lifecycle flags are not used as resource ownership', () => {
+  const violations: string[] = [];
+  const forbiddenDeclaration =
+    /\b(?:private|protected|public|declare\s+private)\s+_(?:enabled|destroyed|disposed|running|uiAlive)\b/u;
+  for (const file of sourceFiles(sourceRoot).filter((path) => path.endsWith('.ts'))) {
+    if (file.endsWith(join('shared', 'ui', 'dash.ts'))) continue;
+    if (forbiddenDeclaration.test(readFileSync(file, 'utf8')))
+      violations.push(file.slice(sourceRoot.length + 1));
+  }
+  assert.deepEqual(violations, []);
+});
diff --git a/tests/unit/intellihideState.test.ts b/tests/unit/intellihideState.test.ts
index 48f5276..66dd4ef 100644
--- a/tests/unit/intellihideState.test.ts
+++ b/tests/unit/intellihideState.test.ts
@@ -36,10 +36,7 @@ test('rectanglesOverlap does not block when a small window only touches the dock
 
 test('hasOverlap checks every relevant window rather than only the focused or last window', () => {
   const dock = rect(700, 1030, 600, 50);
-  const windows = [
-    rect(800, 1000, 500, 100),
-    rect(0, 0, 500, 500),
-  ];
+  const windows = [rect(800, 1000, 500, 100), rect(0, 0, 500, 500)];
 
   assert.equal(hasOverlap(windows, dock), true);
 });
@@ -80,6 +77,88 @@ test('getBlockingOverlapState lets a topmost small window reveal when focus is o
   assert.deepEqual(state.rectangles, [topmostSmallWindow]);
 });
 
+test('getBlockingOverlapState does not let a focused PiP reveal over fullscreen', () => {
+  const dock = rect(700, 1030, 600, 50);
+  const backgroundFullscreenWindow = rect(0, 0, 1920, 1080);
+  const focusedPipWindow = rect(100, 100, 500, 300);
+
+  const state = getBlockingOverlapState(
+    [
+      { rectangle: backgroundFullscreenWindow, fullscreen: true },
+      {
+        rectangle: focusedPipWindow,
+        focused: true,
+        topmost: true,
+        excludedFromSmartReveal: true,
+      },
+    ],
+    dock,
+    true,
+  );
+
+  assert.equal(state.blocked, true);
+  assert.deepEqual(state.rectangles, [backgroundFullscreenWindow]);
+});
+
+test('getBlockingOverlapState keeps ordinary small-window reveal when PiP exclusion is off', () => {
+  const dock = rect(700, 1030, 600, 50);
+  const backgroundFullscreenWindow = rect(0, 0, 1920, 1080);
+  const focusedSmallWindow = rect(100, 100, 500, 300);
+
+  const state = getBlockingOverlapState(
+    [
+      { rectangle: backgroundFullscreenWindow, fullscreen: true },
+      { rectangle: focusedSmallWindow, focused: true, topmost: true },
+    ],
+    dock,
+    true,
+  );
+
+  assert.equal(state.blocked, false);
+  assert.deepEqual(state.rectangles, [focusedSmallWindow]);
+});
+
+test('getBlockingOverlapState still lets an excluded PiP block by overlapping the dock', () => {
+  const dock = rect(700, 1030, 600, 50);
+  const overlappingPipWindow = rect(800, 1000, 500, 100);
+
+  const state = getBlockingOverlapState(
+    [
+      {
+        rectangle: overlappingPipWindow,
+        focused: true,
+        topmost: true,
+        excludedFromSmartReveal: true,
+      },
+    ],
+    dock,
+    false,
+  );
+
+  assert.equal(state.blocked, true);
+  assert.deepEqual(state.rectangles, [overlappingPipWindow]);
+});
+
+test('getBlockingOverlapState does not reveal for an excluded PiP when focus is on another monitor', () => {
+  const dock = rect(700, 1030, 600, 50);
+  const topmostPipWindow = rect(100, 100, 500, 300);
+
+  const state = getBlockingOverlapState(
+    [
+      {
+        rectangle: topmostPipWindow,
+        topmost: true,
+        excludedFromSmartReveal: true,
+      },
+    ],
+    dock,
+    false,
+  );
+
+  assert.equal(state.blocked, true);
+  assert.deepEqual(state.rectangles, [topmostPipWindow]);
+});
+
 test('getBlockingOverlapState blocks when the focused window overlaps the dock', () => {
   const dock = rect(700, 1030, 600, 50);
   const focusedOverlappingWindow = rect(800, 1000, 500, 100);
diff --git a/tests/unit/pipWindowPolicy.test.ts b/tests/unit/pipWindowPolicy.test.ts
new file mode 100644
index 0000000..7c7cabd
--- /dev/null
+++ b/tests/unit/pipWindowPolicy.test.ts
@@ -0,0 +1,89 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  enforcePipWindow,
+  isPipTitle,
+  restorePipWindow,
+  type PipWindowState,
+} from '../../src/patches/pipWindowPolicy.ts';
+
+class FakeWindow implements PipWindowState {
+  constructor(
+    private above = false,
+    private sticky = false,
+  ) {}
+
+  isAbove(): boolean {
+    return this.above;
+  }
+
+  isOnAllWorkspaces(): boolean {
+    return this.sticky;
+  }
+
+  makeAbove(): void {
+    this.above = true;
+  }
+
+  makeSticky(): void {
+    this.sticky = true;
+  }
+
+  unmakeAbove(): void {
+    this.above = false;
+  }
+
+  unmakeSticky(): void {
+    this.sticky = false;
+  }
+}
+
+test('recognizes supported PiP titles without matching unrelated windows', () => {
+  assert.equal(isPipTitle('Picture-in-Picture'), true);
+  assert.equal(isPipTitle('Picture in picture'), true);
+  assert.equal(isPipTitle('Video title - PiP'), true);
+  assert.equal(isPipTitle('  PICTURE-IN-PICTURE  '), true);
+
+  assert.equal(isPipTitle(null), false);
+  assert.equal(isPipTitle('Picture editor'), false);
+  assert.equal(isPipTitle('PiP settings'), false);
+  assert.equal(isPipTitle('Video title - PiP controls'), false);
+});
+
+test('enforces above and sticky state and restores Aurora-owned changes', () => {
+  const window = new FakeWindow();
+  const ownership = enforcePipWindow(window, null);
+
+  assert.equal(window.isAbove(), true);
+  assert.equal(window.isOnAllWorkspaces(), true);
+  assert.deepEqual(ownership, { madeAbove: true, madeSticky: true });
+
+  restorePipWindow(window, ownership);
+  assert.equal(window.isAbove(), false);
+  assert.equal(window.isOnAllWorkspaces(), false);
+});
+
+test('preserves states that existed before Aurora managed the window', () => {
+  const window = new FakeWindow(true, true);
+  const ownership = enforcePipWindow(window, null);
+
+  assert.deepEqual(ownership, { madeAbove: false, madeSticky: false });
+
+  restorePipWindow(window, ownership);
+  assert.equal(window.isAbove(), true);
+  assert.equal(window.isOnAllWorkspaces(), true);
+});
+
+test('reapplies a managed state without changing its original ownership', () => {
+  const window = new FakeWindow();
+  const ownership = enforcePipWindow(window, null);
+  window.unmakeAbove();
+  window.unmakeSticky();
+
+  const nextOwnership = enforcePipWindow(window, ownership);
+
+  assert.equal(nextOwnership, ownership);
+  assert.equal(window.isAbove(), true);
+  assert.equal(window.isOnAllWorkspaces(), true);
+});
diff --git a/tests/unit/registry.test.ts b/tests/unit/registry.test.ts
index e5b1948..9381ff8 100644
--- a/tests/unit/registry.test.ts
+++ b/tests/unit/registry.test.ts
@@ -166,7 +166,7 @@ test('catalog — every section is declared by moduleCatalog', () => {
   for (const entry of entries) assert.ok(sections.has(entry.section), entry.key);
 });
 
-test('prefs uses the manifest-only catalog and extension uses the runtime registry', () => {
+test('prefs uses the manifest-only catalog and extension core uses the runtime registry', () => {
   const prefs = sourceFile('src/prefs.ts');
   const importsCatalog = prefs.statements.some(
     (statement) =>
@@ -175,7 +175,7 @@ test('prefs uses the manifest-only catalog and extension uses the runtime regist
       statement.moduleSpecifier.text === '~/moduleCatalog.ts',
   );
   assert.equal(importsCatalog, true);
-  const extension = sourceFile('src/extension.ts');
+  const extension = sourceFile('src/core/extensionBase.ts');
   const importsRegistry = extension.statements.some(
     (statement) =>
       ts.isImportDeclaration(statement) &&
diff --git a/tests/unit/toolbarPlacement.test.ts b/tests/unit/toolbarPlacement.test.ts
new file mode 100644
index 0000000..ff8e274
--- /dev/null
+++ b/tests/unit/toolbarPlacement.test.ts
@@ -0,0 +1,99 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import {
+  calculateToolbarTranslation,
+  findMonitorForSelection,
+  type ToolbarPlacement,
+} from '../../src/capture/toolbarPlacement.ts';
+
+const placement: ToolbarPlacement = {
+  monitor: { x: 0, y: 0, width: 1920, height: 1080 },
+  selection: { x: 500, y: 300, width: 800, height: 500 },
+  toolbar: {
+    width: 600,
+    height: 48,
+    stageX: 660,
+    stageY: 0,
+    translationX: 0,
+    translationY: 0,
+  },
+  margin: 12,
+};
+
+test('toolbar placement produces finite translations inside the monitor', () => {
+  assert.deepEqual(calculateToolbarTranslation(placement), { x: -60, y: 240 });
+});
+
+test('toolbar placement moves below selections that have no room above', () => {
+  assert.deepEqual(
+    calculateToolbarTranslation({
+      ...placement,
+      selection: { x: 20, y: 10, width: 300, height: 200 },
+    }),
+    { x: -660, y: 222 },
+  );
+});
+
+test('toolbar placement selects the monitor containing most of the selection', () => {
+  const monitors = [
+    { x: 0, y: 0, width: 1920, height: 1080 },
+    { x: 1920, y: 180, width: 2560, height: 1440 },
+  ];
+
+  assert.equal(
+    findMonitorForSelection({ x: 2200, y: 400, width: 800, height: 500 }, monitors, 0),
+    monitors[1],
+  );
+  assert.deepEqual(
+    calculateToolbarTranslation({
+      ...placement,
+      monitor: monitors[1]!,
+      selection: { x: 2200, y: 400, width: 800, height: 500 },
+    }),
+    { x: 1640, y: 340 },
+  );
+});
+
+test('toolbar placement uses the primary monitor as a safe fallback', () => {
+  const monitors = [
+    { x: 0, y: 0, width: 1920, height: 1080 },
+    { x: 1920, y: 0, width: 1920, height: 1080 },
+  ];
+
+  assert.equal(
+    findMonitorForSelection({ x: 5000, y: 5000, width: 100, height: 100 }, monitors, 0),
+    monitors[0],
+  );
+});
+
+test('toolbar placement supports a monitor with a negative stage offset', () => {
+  const monitors = [
+    { x: 0, y: 0, width: 1920, height: 1080 },
+    { x: -1600, y: -200, width: 1600, height: 900 },
+  ];
+
+  assert.equal(
+    findMonitorForSelection({ x: -1400, y: 100, width: 600, height: 300 }, monitors, 0),
+    monitors[1],
+  );
+});
+
+test('toolbar placement rejects non-finite actor coordinates', () => {
+  for (const value of [Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY]) {
+    assert.equal(
+      calculateToolbarTranslation({
+        ...placement,
+        toolbar: { ...placement.toolbar, stageX: value },
+      }),
+      null,
+    );
+    assert.equal(
+      calculateToolbarTranslation({
+        ...placement,
+        toolbar: { ...placement.toolbar, stageY: value },
+      }),
+      null,
+    );
+  }
+});

From 05f0e93159d4ed221c70380db05365d689c64d4c Mon Sep 17 00:00:00 2001
From: Leandro Rodrigues <leandromqrs@hotmail.com>
Date: Tue, 28 Jul 2026 15:50:19 -0300
Subject: [PATCH 2/3] ci: publish development archives in releases

Attach both the production extension archive and the separate DevTool-enabled development archive to stable releases and manually dispatched release candidates.

Apply the same two-asset policy to nightly pre-releases so QA and contributors can download the development build directly from every published release type.

Document the purpose of each asset and keep the production archive as the recommended package for regular installations.

Validated workflow YAML syntax, Prettier formatting, and staged diff integrity. The local QA acceptance document is intentionally excluded from this commit.
---
 .github/workflows/pre-release.yml |  4 +++-
 .github/workflows/release.yml     |  4 +++-
 CONTRIBUTING.md                   | 13 +++++++++++--
 README.md                         |  9 +++++++++
 4 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/pre-release.yml b/.github/workflows/pre-release.yml
index 3426433..e63618c 100644
--- a/.github/workflows/pre-release.yml
+++ b/.github/workflows/pre-release.yml
@@ -116,7 +116,9 @@ jobs:
           tag_name: ${{ needs.nightly-state.outputs.tag_name }}
           target_commitish: ${{ needs.nightly-state.outputs.head_sha }}
           name: ${{ needs.nightly-state.outputs.release_name }}
-          files: dist/target/aurora-shell@luminusos.github.io.shell-extension.zip
+          files: |
+            dist/target/aurora-shell@luminusos.github.io.shell-extension.zip
+            dist/target/aurora-shell@luminusos.github.io.development.shell-extension.zip
           generate_release_notes: true
           previous_tag: ${{ steps.stable_release.outputs.tag }}
           prerelease: true
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c636a88..f818d68 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -89,7 +89,9 @@ jobs:
           tag_name: ${{ needs.state.outputs.tag_name }}
           target_commitish: ${{ needs.state.outputs.head_sha }}
           name: ${{ needs.state.outputs.tag_name }}
-          files: dist/target/aurora-shell@luminusos.github.io.shell-extension.zip
+          files: |
+            dist/target/aurora-shell@luminusos.github.io.shell-extension.zip
+            dist/target/aurora-shell@luminusos.github.io.development.shell-extension.zip
           generate_release_notes: true
           prerelease: ${{ github.event_name == 'workflow_dispatch' }}
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d277861..c208dd3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -105,6 +105,10 @@ Release candidates are published alongside GNOME Shell RCs. Tags follow the patt
 
 To publish an RC, trigger the `Release` workflow manually (`workflow_dispatch`) — no input is needed. Like the nightly flow, the workflow numbers the next candidate automatically (`v50-rc1`, then `v50-rc2`, ...), tags current `main`, runs CI against it, and publishes the pre-release. An RC supersedes the nightly line, so publishing one deletes all nightly pre-releases.
 
+Every RC and nightly pre-release publishes both the production ZIP and the separate DevTool-enabled
+development ZIP. The production package is the installable artifact for regular users; the
+development package is intended only for contributors, QA, and development sessions.
+
 ### Stable releases
 
 Stable releases use tags like `v50.1`, `v50.2`, matching the GNOME Shell major version they target.
@@ -116,7 +120,8 @@ git tag -a v50.1 -m "Release v50.1"
 git push origin v50.1
 ```
 
-The CI pipeline runs all tests and, if they pass, publishes the GitHub Release automatically.
+The CI pipeline runs all tests and, if they pass, publishes the GitHub Release automatically with
+both the production ZIP and the separate DevTool-enabled development ZIP.
 
 ## Build System & Commands
 
@@ -192,7 +197,11 @@ D-Bus services.
 
 All jobs must pass before a PR can be merged.
 
-When a stable version tag (`v50.1`, `v50.2`, etc.) is pushed, `.github/workflows/release.yml` calls the CI pipeline and, if all jobs pass, publishes the GitHub Release automatically. Release candidate tags (`v50-rc1`, etc.) are excluded from this trigger and are published manually via `workflow_dispatch`, as described above.
+When a stable version tag (`v50.1`, `v50.2`, etc.) is pushed, `.github/workflows/release.yml` calls
+the CI pipeline and, if all jobs pass, publishes the GitHub Release automatically with both extension
+ZIPs. Release candidate tags (`v50-rc1`, etc.) are excluded from this trigger and are published
+manually via `workflow_dispatch`, as described above. The nightly workflow follows the same
+two-package release-asset policy.
 
 ## Coding Standards
 
diff --git a/README.md b/README.md
index da6a0ca..8085bfe 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,15 @@ gnome-extensions install --force aurora-shell@luminusos.github.io.shell-extensio
 gnome-extensions enable aurora-shell@luminusos.github.io
 ```
 
+Stable releases, release candidates, and nightly pre-releases publish two assets:
+
+- `aurora-shell@luminusos.github.io.shell-extension.zip` — production package recommended for
+  regular installations;
+- `aurora-shell@luminusos.github.io.development.shell-extension.zip` — DevTool-enabled package for
+  contributors, QA, and development sessions.
+
+Do not use the development package as a regular desktop installation.
+
 ## Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for information on project architecture, code style, and step-by-step instructions on how to add a new module.

From ca08eb0e831adf7219bcc67889ec3e2e35e7e7ee Mon Sep 17 00:00:00 2001
From: Leandro Rodrigues <leandromqrs@hotmail.com>
Date: Tue, 28 Jul 2026 15:55:44 -0300
Subject: [PATCH 3/3] test: wait for dock hot area rearm

Replace fixed DevTool dock animation delays with condition-based polling so the integration test follows the actual Shell state under forced animations.

Wait until the selected dock is hidden, its reveal state is cleared, and its hot area is reactive before triggering the simulated edge action. Also wait for show and reveal transitions instead of assuming fixed completion times.

This removes the CI race where the pending rearm timer treated the DevTool trigger as a duplicate and then cleared hotAreaActive after the assertion started.

Validated with just validate, the host DevTool integration test, and the Toolbox DevTool integration test; both integration runs passed.
---
 tests/shell/auroraDevTool.js | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/tests/shell/auroraDevTool.js b/tests/shell/auroraDevTool.js
index 7f1388a..5b89d66 100644
--- a/tests/shell/auroraDevTool.js
+++ b/tests/shell/auroraDevTool.js
@@ -20,6 +20,15 @@ function collectText(actor) {
   return text;
 }
 
+async function waitForCondition(condition, timeoutMs = 3000) {
+  const deadline = GLib.get_monotonic_time() + timeoutMs * 1000;
+  while (GLib.get_monotonic_time() < deadline) {
+    if (condition()) return true;
+    await Scripting.sleep(50);
+  }
+  return condition();
+}
+
 export var METRICS = {};
 
 /** @returns {void} */
@@ -261,23 +270,25 @@ export async function run() {
     throw new Error('Dock DevTool hideAll left a hidden container reactive');
 
   const monitorIndex = dock.bindings[0].monitorIndex;
+  const binding = dock.bindings[0];
   if (!dockTool.showMonitor(monitorIndex))
     throw new Error('Dock DevTool showMonitor returned false');
-  await Scripting.sleep(300);
-  if (!dock.bindings[0].dash.visible)
+  if (!(await waitForCondition(() => binding.dash.visible)))
     throw new Error('Dock DevTool showMonitor did not show the selected monitor');
 
   if (!dockTool.hideMonitor(monitorIndex))
     throw new Error('Dock DevTool hideMonitor returned false');
-  await Scripting.sleep(300);
-  if (dock.bindings[0].dash.visible)
-    throw new Error('Dock DevTool hideMonitor did not hide the selected monitor');
-
-  if (dock.bindings[0].hotArea) {
+  if (
+    !(await waitForCondition(
+      () => !binding.dash.visible && !binding.hotAreaActive && binding.hotArea?.reactive === true,
+    ))
+  )
+    throw new Error('Dock DevTool did not hide the selected monitor and rearm its hot area');
+
+  if (binding.hotArea) {
     if (!dockTool.triggerMonitorHotArea(monitorIndex))
       throw new Error('Dock DevTool triggerMonitorHotArea returned false');
-    await Scripting.sleep(100);
-    if (!dock.bindings[0].hotAreaActive)
+    if (!(await waitForCondition(() => binding.hotAreaActive, 1000)))
       throw new Error('Dock DevTool did not trigger the selected monitor hot area');
   }