Category: Javascript

Adding Window Previews to Dash to Dock: A GNOME Shell Extension Deep Dive

April 5, 2026
JavascriptLinux
0 Comment

I ported, debugged, and shipped a window preview feature for Dash to Dock — one of the most popular GNOME Shell extensions. This post documents the journey: what worked, what broke repeatedly, and the hard-won lessons about GNOME Shell extension development on Wayland.

The Starting Point: A Stale PR

It began with PR #574 on the upstream repository — an old pull request that added window preview popups when hovering over dock icons. The code was outdated and no longer compatible with current GNOME Shell. I pulled it down, analysed it, and set about porting it to the modern GNOME Shell API.

The goal was straightforward: when a user hovers over an application icon in the dock, show live thumbnail previews of that application’s open windows — similar to the taskbar preview feature in Windows.

The Focus Nightmare

The single hardest problem was focus management. GNOME Shell’s popup menu system uses a modal grab model — when a popup opens, it captures input events. This is fine for right-click context menus, but for hover-triggered preview windows it creates a nightmare:

  • The preview popup would steal focus — once shown, moving the mouse to another dock icon did nothing. The user was trapped.
  • The only escape was clicking elsewhere — hover-out events were swallowed by the modal grab.
  • Fixing focus broke the context menu — every attempt to make the preview release focus would break the right-click context menu. This happened at least 5 times during development.

The solution required carefully managing the popup’s reactive state: the preview needed to be open for rendering purposes but not capture input in the way a traditional menu does. We had to iterate through all dock icons on enter/leave events, explicitly closing previews for other applications.

Debugging on Wayland

GNOME Shell extensions on Wayland present unique debugging challenges. You cannot simply restart the shell — you need a nested Wayland session:

dbus-run-session -- gnome-shell --nested --wayland

Copy-paste does not work between the nested session and the host, so I added file-based logging early on to /tmp/dash-to-dock-DATE.log. This turned out to be essential. The log output was invaluable for analysis, creating a tight feedback loop: run the extension, reproduce the bug, analyse the logs, apply a fix, rebuild, repeat.

The Open/Close/Open Flicker Bug

One persistent bug: on the first hover over any icon, the preview would appear, disappear, then appear again — a visible flicker. It only happened once per icon, then worked fine afterward.

The root cause was a race condition between the hover-open timeout (300ms delay before showing) and the menu system’s own open/close signals. When the popup first rendered, GNOME Shell’s menu manager would fire a menu-closed signal during initial layout, which triggered our close handler, which then got re-triggered by the still-active hover state.

The fix was a justOpened guard flag that suppressed close events for a brief window after the initial open.

Window Preview Sizing

Getting the preview thumbnails to size correctly went through several iterations:

  1. First attempt: Fixed-size preview boxes — resulted in disproportionate previews with large empty spaces for narrow windows.
  2. Second attempt: Scale app thumbnails to fit the preview box — made everything look like squashed squares.
  3. Final approach: Dynamic width based on the application window’s aspect ratio, with a fixed height and a maximum width cap at 90% of desktop horizontal space. Single windows get a tight fit; multiple windows of the same app expand horizontally.

Aero Peek: Fading Away the Clutter

With previews working, I added an Aero Peek feature inspired by Windows: when hovering over a specific window thumbnail in the preview popup, all other windows fade to near-transparency (1% opacity), letting the user see the target window beneath the stack.

I initially tried full transparency (0% opacity) with a glow outline around windows, but GNOME Shell’s compositor does not support per-window glow effects without custom shaders. The simple opacity fade at 1% proved effective enough — windows are essentially invisible but technically still rendered, avoiding compositor edge cases.

Animation Styles That Refused to Animate

I added a settings dropdown for preview animation styles: Instant, Fade, Slide, Scale, Expand, and Dissolve. The settings UI worked, the values were stored and read correctly, the animation config function returned the right style… but nothing visually changed.

Over a dozen debug sessions later, the issue was that the animation transitions were being applied after the popup was already visible. The Clutter animation framework needs the initial state set before the actor is shown, then the target state set to trigger the transition. We were setting both states after show(), so there was nothing to animate between.

The Translation Gap

The feature introduced new user-facing strings — Show window previews on mouse hover, animation style names, etc. These all needed translations across the extension’s supported languages. GNOME Shell extensions use gettext, and each string needed entries in every .po file.

Key Takeaways for GNOME Shell Extension Development

  1. File-based logging is non-negotiable on Wayland — console.log goes to the journal, but you cannot easily copy from a nested session. Write to /tmp/.
  2. The menu/popup system is a minefield — GNOME Shell’s PopupMenu assumes modal interaction. If you need non-modal popups (like hover previews), expect to fight the framework.
  3. Test the right-click menu after every change — focus and event handling changes have a remarkable ability to break context menus silently.
  4. Race conditions are the default — hover events, timeouts, animation completions, and menu signals all fire asynchronously. Guard everything.
  5. Aspect ratio math is harder than it sounds — single window vs. multi-window layout, mixed landscape/portrait windows, and screen size limits all interact.
  6. Use a nested Wayland session — dbus-run-session gnome-shell nested wayland saves you from logging out after every crash.

The Result

The final feature, submitted as PR #2470, adds:

  • Hover-triggered window preview popups with live thumbnails
  • Dynamic sizing based on window aspect ratios
  • Clickable previews that bring windows to focus
  • Close buttons on individual previews
  • Aero Peek transparency effect
  • Multiple animation styles (fade, slide, scale, expand, dissolve)
  • Late-arriving window detection (preview appears when an app finishes launching)
  • Full translation support

Dozens of iterations, countless regressions, and one very stubborn focus-stealing bug later — it works.

Introducing AA Dev Prod Watcher: A Tool for Enhanced Development Monitoring

April 28, 2025
Javascript
0 Comment

In the fast-paced world of software development, keeping track of various environments can be a daunting task. The AA Dev Prod Watcher project emerged as a solution to this challenge, providing developers with a streamlined way to monitor development and production environments effectively. This project was initiated in 2021, marking a significant step in enhancing the development workflow.

The AA Dev Prod Watcher was created in response to the common issue of developers losing track of changes between development and production environments. As applications evolve, it becomes increasingly important to ensure that the right versions are deployed and that any discrepancies are promptly addressed. This tool aims to bridge that gap, offering a solution that is both practical and user-friendly.

Project Overview

The AA Dev Prod Watcher is designed to monitor and compare the state of development and production environments. It serves as a watchdog, alerting developers to any changes or inconsistencies that may arise during the development process. This project is particularly beneficial for teams working in agile environments where rapid iterations are common.

Targeted at developers and DevOps teams, the AA Dev Prod Watcher utilizes technologies such as Node.js and various monitoring libraries to provide real-time insights into environment statuses. By integrating this tool into their workflow, teams can ensure that they are always aware of the current state of their applications, reducing the risk of deploying outdated or incorrect versions.

Key Features

  • Real-Time Monitoring: The tool continuously checks the status of both development and production environments, providing instant feedback.
  • Alert System: Users receive notifications about any discrepancies, allowing for quick resolution of potential issues.
  • Easy Integration: The AA Dev Prod Watcher can be easily integrated into existing workflows, making it a versatile addition to any development toolkit.
  • Open Source: As an open-source project, it encourages collaboration and contributions from the community, fostering continuous improvement.

Current State and Future Plans

As of now, the AA Dev Prod Watcher is actively maintained, with ongoing updates and improvements being made. The project’s repository reflects a commitment to enhancing its functionality and user experience. Future plans include expanding its capabilities to support additional environments and integrating more advanced monitoring features.

In conclusion, the AA Dev Prod Watcher stands as a testament to the importance of maintaining clarity and control in software development environments. With its practical features and focus on user needs, it is poised to make a lasting impact on how developers manage their projects. We invite you to explore the repository, contribute to its development, and join us in making the development process smoother and more efficient.

For more information, visit the project’s GitHub page: AA Dev Prod Watcher.

Exploring MattersHighLight: A Tool for Enhanced Content Engagement

February 3, 2023
Javascript
0 Comment

In the ever-evolving landscape of digital content, the need for tools that enhance user engagement and streamline information processing has never been more critical. The MattersHighLight project was initiated in response to this need, aiming to provide users with a unique way to highlight and manage important content effectively. This project was started in 2021, marking a significant milestone in the journey of digital content interaction.

Historical Context

MattersHighLight was developed during a time when content overload was becoming increasingly prevalent. Users were struggling to sift through vast amounts of information, leading to the creation of tools that could help prioritize and highlight key points. This project is part of a larger trend towards enhancing user experience through innovative digital solutions.

Project Overview

MattersHighLight is a web-based application designed to allow users to highlight important sections of text within articles, documents, or any online content. This tool addresses the problem of information overload by enabling users to focus on what truly matters to them. The target audience includes students, researchers, and anyone who regularly engages with large volumes of text and wishes to retain critical information efficiently.

Technologies and Tools

The project leverages modern web technologies, including HTML, CSS, and JavaScript, to create an intuitive user interface that is both responsive and user-friendly. The application is built with a focus on accessibility, ensuring that all users can benefit from its features.

Key Features

  • Highlighting Functionality: Users can easily select and highlight text, making it simple to mark important information.
  • Save and Retrieve Highlights: The application allows users to save their highlights for future reference, enhancing their ability to revisit important content.
  • User-Friendly Interface: Designed with the user in mind, the interface is clean and straightforward, allowing for seamless navigation.

Current State and Future Plans

As of now, MattersHighLight is an active project, continuously evolving to meet user needs. The development team is currently working on adding new features based on user feedback, including improved sharing options and integration with popular note-taking applications. The goal is to create a comprehensive tool that not only highlights text but also enhances overall content interaction.

Conclusion

MattersHighLight stands out as a testament to the power of user-centered design in addressing the challenges of modern content consumption. By providing a means to highlight and manage important information, it empowers users to take control of their digital reading experience. As the project continues to grow and adapt, it remains an exciting resource for anyone looking to enhance their engagement with online content.

For more information and to contribute to the project, visit the MattersHighLight GitHub repository.

Exploring Document Architectures: A Comprehensive Guide

February 3, 2023
Javascript
0 Comment

In the ever-evolving landscape of technology, the need for efficient document management and architecture is more crucial than ever. The Document Architectures project, initiated by dmzoneill, stands as a testament to this need, providing innovative solutions that cater to various document handling challenges.

Historical Context

This project was started in response to the increasing complexity of managing digital documents in various formats and the need for a structured approach to document architecture. Launched in 2016, the project aimed to address the growing demand for efficient document workflows, particularly in academic and professional settings. The earliest commit dates back to 2016, marking the beginning of a journey towards simplifying document management.

Project Overview

The Document Architectures project serves as a framework for understanding and implementing effective document management systems. It is designed for developers, researchers, and organizations seeking to improve their document handling capabilities. The project employs a variety of technologies, including HTML, CSS, and JavaScript, to create a user-friendly interface that enhances the user experience.

Key Features

  • Modular Design: The project adopts a modular approach, allowing users to customize and extend the functionality according to their specific needs.
  • Responsive Interface: Built with a focus on user experience, the interface is responsive and accessible across different devices.
  • Comprehensive Documentation: The project includes detailed documentation to guide users through the setup and implementation processes.

Current State and Future Plans

As of now, the Document Architectures project is still active and continues to receive updates and enhancements. The community around the project is vibrant, with contributors actively working on new features and improvements. Future plans include expanding the functionality to support additional document formats and integrating advanced search capabilities to streamline document retrieval.

Conclusion

The Document Architectures project is not just a repository; it is a comprehensive solution that addresses the complexities of document management in the digital age. Whether you are a developer looking to implement a robust document architecture or an organization seeking to improve your document workflows, this project offers valuable insights and tools to help you succeed. Join us in exploring the future of document management!

For more information, visit the project on GitHub.

Exploring the iLab Template Scripts: A Comprehensive Development Tool

February 3, 2023
Javascript
0 Comment

In the ever-evolving landscape of software development, the need for efficient and reusable scripts has become paramount. The iLab Template Scripts project, initiated by dmzoneill, serves as a testament to this need. This project was started in 2016, marking a significant milestone in the development of tools aimed at enhancing productivity in laboratory settings.

Historical Context

The iLab Template Scripts project emerged in response to the growing complexity of managing laboratory workflows and data. As research environments became more intricate, the demand for streamlined processes and automation tools became evident. This project was part of a larger initiative to improve efficiency and accuracy in scientific research, aligning with the broader trend of digital transformation in laboratories.

Project Overview

The iLab Template Scripts project is designed to provide a set of customizable scripts that facilitate various laboratory tasks. These scripts aim to solve common problems faced by researchers, such as data management, experiment tracking, and workflow automation. The target audience includes laboratory managers, researchers, and anyone involved in scientific data handling.

Technologies and Tools

This project leverages a variety of programming languages and tools, primarily focusing on Python for its scripting capabilities. The use of Python allows for flexibility and ease of integration with other systems, making it an ideal choice for laboratory environments. The repository contains well-structured scripts that can be adapted to meet specific laboratory needs.

Key Features

One of the standout aspects of the iLab Template Scripts is its emphasis on customization. Users can easily modify the scripts to fit their unique workflows, ensuring that they can adapt to changing research requirements. Additionally, the repository includes comprehensive documentation, which is crucial for onboarding new users and facilitating effective usage of the scripts.

Current State and Future Developments

As of now, the iLab Template Scripts project is actively maintained, with ongoing developments aimed at enhancing functionality and user experience. The project continues to evolve, incorporating feedback from users and adapting to new technological advancements. Future plans include expanding the script library and improving integration with other laboratory management systems.

Conclusion

The iLab Template Scripts project exemplifies the importance of developing tools that address the specific needs of researchers. By providing a robust framework for automation and data management, this project not only improves efficiency but also contributes to the overall advancement of scientific research. As we look to the future, the potential for further innovation within this project remains exciting.

For those interested in exploring the iLab Template Scripts, visit the repository at GitHub and join the journey of enhancing laboratory workflows.