@deepseek-ai/dsh-host-directory-picker-native 0.1.3-alpha.2 → 0.1.5-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/directory-picker-native/README.md
-README.md: a432bdc19175c690287745cc9c2df004d03b7478
-README.zh.md: 98ea9a033dbf6720fa08fbb068e243371998dab6
+README.md: 3f980831848965b976e32b0e5ef25abb77fe4e6e
+README.zh.md: 66f77a0b715aee8b4087dd03d4d4eea69d39bb09

package/README.md

@@ -53,7 +53,7 @@ The backend is a thin service over a platform chooser: `NativeDirectoryPicker` r
 
 ### Platform mechanics
 
-Platform tools run without a shell: `osascript` on macOS, and Zenity with a KDialog fallback on Linux; the caller's abort terminates the native process. Windows opens the modern `IFileOpenDialog` in a spawned child process — a koffi-driven COM conversation on the child's main thread with the best thread DPI awareness the host accepts (per-monitor-v2 first), aborted by posting `WM_CLOSE` to the dialog thread.
+Platform tools run without a shell: `osascript` on macOS, and Zenity with a KDialog fallback on Linux; the caller's abort terminates the native process. Windows opens the modern `IFileOpenDialog` in a spawned child process — a koffi-driven COM conversation on the child's main thread with the best thread DPI awareness the host accepts (per-monitor-v2 first), aborted by posting `WM_CLOSE` to the dialog thread. Immediately before `Show`, the child synthesizes one Alt press through `keybd_event`, which lets the dialog activate as the foreground window even when a background host process spawned the child.
 
 ### Source map
 
@@ -98,6 +98,7 @@ These limits define when the native interaction is unavailable or fragile. They
 
 - **Linux requires desktop tooling** — with neither Zenity nor KDialog installed, `pick` rejects with an actionable error; it does not fall back to a typed-path prompt (the browse backend is that fallback at the composition level).
 - **Windows has no mechanism fallback** — the child-process picker through packaged koffi is the only native tier, so a COM refusal or dialog crash surfaces the failure; the browse backend remains the fallback at the composition level.
+- **Windows foreground grant relies on injected input** — the child synthesizes an Alt press before `Show` so the dialog can take the foreground from a background host; where synthesized input is suppressed (secure desktops, restricted remote sessions, an elevated foreground window), the dialog may still open behind other windows. The technique is validated on Windows 11 only.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -53,7 +53,7 @@ kind: "package-reference"
 
 ### 平台机制
 
-平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在 spawn 的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。
+平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在 spawn 的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。在 `Show` 之前，子进程立即通过 `keybd_event` 合成一次 Alt 按键，让对话框即使由后台宿主进程 spawn 也能激活为前台窗口。
 
 ### 源码地图
 
@@ -98,6 +98,7 @@ kind: "package-reference"
 
 - **Linux 依赖桌面工具**——Zenity 与 KDialog 均未安装时，`pick` 以包含解决建议的错误拒绝；它不会回退为手输路径提示（组合层面的回退是浏览后端）。
 - **Windows 没有机制级回退**——通过打包依赖 koffi 运行的子进程选择器是唯一原生层级，因此 COM 拒绝或对话框崩溃会直接上报失败；组合层面的回退仍是浏览后端。
+- **Windows 前台授权依赖注入的输入**——子进程在 `Show` 之前合成一次 Alt 按键，对话框才能从后台宿主取得前台；在合成输入被抑制的环境（安全桌面、受限远程会话、提权前台窗口）中，对话框仍可能在其他窗口后面打开。该技术仅在 Windows 11 上验证过。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -64,9 +64,10 @@ async function closeThreadWindows(threadId) {
 /**
 * Spawn the dialog child process. Built consumers launch the bundled CJS
 * entry next to this module under plain node; unbuilt (source) consumers
-* bootstrap tsx first, mirroring the dsh CLI's source launch. The dialog is
-* the child's first window, so Windows activates it without a foreground
-* call.
+* bootstrap tsx first, mirroring the dsh CLI's source launch. The child
+* opens its dialog as foreground on its own: `runFolderDialog` synthesizes
+* an Alt press before `Show`, which matters when a background host spawned
+* the child.
 * @param data - the child payload (dialog title).
 * @returns the spawned child process.
 */
@@ -276,7 +277,9 @@ async function pickNativeDirectory(signal, internals = {}) {
 * with the `native` capability, opening one native OS chooser on the host
 * display per pick (macOS `osascript`, Linux Zenity with a KDialog fallback;
 * Windows opens the modern `IFileOpenDialog` in a spawned child process — a
-* koffi-driven COM conversation on the child's main thread). Only viable when
+* koffi-driven COM conversation on the child's main thread, preceded by a
+* synthesized Alt press so the dialog activates as foreground even when a
+* background host spawned the child). Only viable when
 * the operator sits at the host's screen; remote deployments compose the
 * browse backend instead.
 * @module @deepseek-ai/dsh-host-directory-picker-native

package/lib/types/index.d.ts

@@ -3,7 +3,9 @@
  * with the `native` capability, opening one native OS chooser on the host
  * display per pick (macOS `osascript`, Linux Zenity with a KDialog fallback;
  * Windows opens the modern `IFileOpenDialog` in a spawned child process — a
- * koffi-driven COM conversation on the child's main thread). Only viable when
+ * koffi-driven COM conversation on the child's main thread, preceded by a
+ * synthesized Alt press so the dialog activates as foreground even when a
+ * background host spawned the child). Only viable when
  * the operator sits at the host's screen; remote deployments compose the
  * browse backend instead.
  * @module @deepseek-ai/dsh-host-directory-picker-native

package/lib/types/win32-dialog-host.d.ts

@@ -11,9 +11,10 @@ import type { Win32DialogWorkerData } from './win32-dialog-worker.ts';
 /**
  * Spawn the dialog child process. Built consumers launch the bundled CJS
  * entry next to this module under plain node; unbuilt (source) consumers
- * bootstrap tsx first, mirroring the dsh CLI's source launch. The dialog is
- * the child's first window, so Windows activates it without a foreground
- * call.
+ * bootstrap tsx first, mirroring the dsh CLI's source launch. The child
+ * opens its dialog as foreground on its own: `runFolderDialog` synthesizes
+ * an Alt press before `Show`, which matters when a background host spawned
+ * the child.
  * @param data - the child payload (dialog title).
  * @returns the spawned child process.
  */

package/lib/types/win32-dialog-logic.d.ts

@@ -78,6 +78,20 @@ export interface Win32DialogBindings {
      * @returns the calling thread's native id.
      */
     currentThreadId(): number;
+    /**
+     * Make the dialog that `Show` is about to create able to take the
+     * foreground. Windows grants activation only to the foreground process,
+     * to a process it started, or to a process that received recent input; a
+     * worker spawned by a background host (the web GUI server) qualifies for
+     * none, so the dialog would open behind every other window. Synthesizing
+     * one Alt press (down, then up) through `keybd_event` counts this process
+     * as the most recent input owner — a community-documented technique with
+     * no documented contract. Call immediately before `Show`. When the
+     * process already holds foreground rights (a console-launched CLI), the
+     * press is inert, but the focused window still receives the lone Alt and
+     * may briefly highlight its menu bar before the dialog activates.
+     */
+    pressAltForForeground(): void;
 }
 /**
  * Run one modal folder-picker conversation on the calling thread: DPI opt-in,

package/lib/types/win32-dialog-worker.d.ts

@@ -1,9 +1,12 @@
 /**
  * Child-process entry for the Win32 folder dialog: blocks THIS process
  * inside the modal `Show` so the host event loop stays live, reporting over
- * the IPC channel. Spawned as a child process (not a worker thread) so the
- * dialog is the process's first window and Windows activates it without a
- * manual foreground call. Protocol: `{kind:'showing',threadId}` right
+ * the IPC channel. Spawned as a child process (not a worker thread) so a
+ * native fault stays contained and the modal call never wedges the host.
+ * A background host (the web GUI server) leaves this process without
+ * foreground rights, so `runFolderDialog` synthesizes an Alt press
+ * immediately before `Show` and the dialog then activates as foreground.
+ * Protocol: `{kind:'showing',threadId}` right
  * before the blocking call (the driver's abort lever needs the native
  * thread id), then exactly one of `{kind:'done',path}` or
  * `{kind:'error',message}`.

package/lib/worker.cjs

@@ -41,6 +41,10 @@ const DPI_AWARENESS_CONTEXTS = [
 	-3,
 	-2
 ];
+/** `VK_MENU`: the synthesized Alt press's virtual key. */
+const VK_MENU = 18;
+/** `KEYEVENTF_KEYUP`: the synthesized Alt press's release flag. */
+const KEYEVENTF_KEYUP = 2;
 /** IFileOpenDialog vtable slots (IUnknown 0-2, IModalWindow 3, IFileDialog 4+). */
 const SLOT_RELEASE = 2;
 const SLOT_SHOW = 3;
@@ -86,6 +90,12 @@ async function loadWin32DialogBindings() {
 	]);
 	const coTaskMemFree = ole32.func("__stdcall", "CoTaskMemFree", "void", ["void *"]);
 	const getCurrentThreadId = kernel32.func("__stdcall", "GetCurrentThreadId", "uint32", []);
+	const keybdEvent = user32.func("__stdcall", "keybd_event", "void", [
+		"uint8",
+		"uint8",
+		"uint32",
+		"uintptr"
+	]);
 	const protoShow = koffi.proto("int32 __stdcall DshDialogShow(void *self, void *owner)");
 	const protoSetOptions = koffi.proto("int32 __stdcall DshDialogSetOptions(void *self, uint32 options)");
 	const protoSetTitle = koffi.proto("int32 __stdcall DshDialogSetTitle(void *self, str16 title)");
@@ -113,6 +123,10 @@ async function loadWin32DialogBindings() {
 			coUninitialize();
 		},
 		currentThreadId: () => getCurrentThreadId(),
+		pressAltForForeground: () => {
+			keybdEvent(VK_MENU, 0, 0, 0);
+			keybdEvent(VK_MENU, 0, KEYEVENTF_KEYUP, 0);
+		},
 		createFolderDialog: () => {
 			const out = Buffer.alloc(pointerSize);
 			const created = coCreateInstance(CLSID_FILE_OPEN_DIALOG, null, CLSCTX_INPROC_SERVER, IID_IFILE_OPEN_DIALOG, out);
@@ -177,6 +191,7 @@ function runFolderDialog(bindings, title, onShowing) {
 			check(dialog.setOptions(104), "SetOptions");
 			check(dialog.setTitle(title), "SetTitle");
 			onShowing(bindings.currentThreadId());
+			bindings.pressAltForForeground();
 			const shown = dialog.show();
 			if (shown === -2147023673) return null;
 			check(shown, "Show");
@@ -195,9 +210,12 @@ function runFolderDialog(bindings, title, onShowing) {
 /**
 * Child-process entry for the Win32 folder dialog: blocks THIS process
 * inside the modal `Show` so the host event loop stays live, reporting over
-* the IPC channel. Spawned as a child process (not a worker thread) so the
-* dialog is the process's first window and Windows activates it without a
-* manual foreground call. Protocol: `{kind:'showing',threadId}` right
+* the IPC channel. Spawned as a child process (not a worker thread) so a
+* native fault stays contained and the modal call never wedges the host.
+* A background host (the web GUI server) leaves this process without
+* foreground rights, so `runFolderDialog` synthesizes an Alt press
+* immediately before `Show` and the dialog then activates as foreground.
+* Protocol: `{kind:'showing',threadId}` right
 * before the blocking call (the driver's abort lever needs the native
 * thread id), then exactly one of `{kind:'done',path}` or
 * `{kind:'error',message}`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-host-directory-picker-native",
   "description": "Native-OS-chooser backend of the directory-picker seam for the DeepSeek Harness web GUI host",
-  "version": "0.1.3-alpha.2",
+  "version": "0.1.5-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -33,8 +33,8 @@
   "license": "MIT",
   "dependencies": {
     "koffi": "^3.1.0",
-    "@deepseek-ai/dsh-host-directory-picker": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-native-command": "^0.1.3-alpha.2"
+    "@deepseek-ai/dsh-host-directory-picker": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-native-command": "^0.1.5-alpha.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2"