Feat/dock mode

[s3d-i]

Description

Linked Issues

#938

Additional Context

[gemini-code-assist]

Summary of Changes

Hello @s3d-i, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant new 'Dock Mode' feature, enabling the AIRI application to display an interactive character overlay that dynamically follows a chosen target window. The implementation involves a new modular Electron package for managing the docking behavior, complemented by native Rust bindings for precise Windows API integration. A comprehensive developer interface has been added to facilitate configuration and debugging of this complex window management system. Additionally, theme synchronization has been enhanced to maintain visual consistency across all application windows.

Highlights

• New Dock Mode Feature: Introduced a new 'Dock Mode' that allows the AIRI application to display a transparent overlay character visually attached to and following a user-selected target window. This feature is designed for cross-platform compatibility (Windows and macOS).
• Dedicated Window Docking Package: Developed a new workspace package, @proj-airi/electron-window-dock, which encapsulates the core logic for managing the overlay window's visibility, position, and interaction with the target window. It includes a DockController state machine and platform-specific window tracking.
• Native Windows API Bindings: Created a new Rust-based Node-API (N-API) package, @proj-airi/win32-window-bindings, to provide direct interaction with Win32 APIs on Windows. This enables more accurate and robust window information retrieval (e.g., z-order, cloaking, bounds) for the dock mode.
• Overlay Window Implementation: Implemented a new transparent, unfocusable dockOverlayWindow in the main Electron process. This window serves as the host for the AIRI character when in dock mode, ensuring it doesn't interfere with user interaction with the target application.
• Developer Tools and Debugging: Added a new developer settings page (/devtools/window-dock) within the application. This page provides controls for selecting target windows, configuring polling intervals, and inspecting the real-time debug state of the dock mode, aiding in development and troubleshooting.
• Centralized Theme Synchronization: Refactored theme synchronization logic using a new useStageThemeSync composable and dedicated Eventa events (dockOverlaySyncTheme, dockOverlayThemeUpdated). This ensures consistent application of chromatic hue and dynamic hue animations across the main application and the new dock overlay window.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-architected "Dock Mode" feature, allowing the AIRI overlay to attach to a target window. The implementation is robust, featuring a new native Windows binding package for accurate window tracking, a comprehensive state controller, and a dedicated devtools page for debugging. The code quality is high, with thoughtful error handling, performance considerations like adaptive polling, and a clean refactoring of theme-related styles into a reusable composable. My review includes a couple of suggestions to further improve the correctness and maintainability of the new dock controller logic.

[gemini-code-assist]

The adjustment to realAbove.length is a workaround for a Win32-specific behavior, as noted in the comment. However, it's being applied unconditionally. This will cause isFrontmost to be calculated incorrectly on non-Windows platforms where the fallback tracker is used. To ensure correctness across platforms, this adjustment should only be applied when running on Windows.

    const adjustedAboveCount = process.platform === 'win32'
      ? Math.max(0, realAbove.length - 1)
      : realAbove.length;

[nekomeowww]

cc @sumimakito do we have other naming options here? If more platform native API integrated in, should we keep them all inside of this package? I guess this is not correct? Perhaps... @proj-airi/native-window-win32?

[sumimakito]

Yeah. @proj-airi/native-window-win32 sounds better. Maybe we can have @proj-airi/native-window-macos in the future in the @proj-airi/native-window-<platform> pattern.

[nekomeowww]

Split this into another Pull Request.

[nekomeowww]

cc @sumimakito would you mind merge your WIP code first? It seems this PR is more focused on Windows but not macOS. And the handling of Three.js is not included.