feat: polish dock behavior and extension review readiness (#81)

* 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.

* 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.

* 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.

Author: leandromqrs

.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

.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

.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' }}
 

.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."

.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

.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

.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

.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 }}'."