@qilin-agent/client-ui-directory-picker-native 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,40 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-directory-picker-native/README.md
+/:
+  en: 6f45a471a5e9305f
+  zh: d771883685e91a45
+/qilin-agent-client-ui-directory-picker-native:
+  en: 6251d6baf414cbd5
+  zh: 30c71437be56b37b
+/qilin-agent-client-ui-directory-picker-native/summary:
+  en: cc747c58ca147259
+  zh: 4c824ab9ca48fb50
+/qilin-agent-client-ui-directory-picker-native/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-agent-client-ui-directory-picker-native/use-this-package:
+  en: db8eb73d3deb11cf
+  zh: 117b1601bec2d17e
+/qilin-agent-client-ui-directory-picker-native/use-this-package/when-to-choose-it:
+  en: 21e63f891429e3e4
+  zh: 59f2db2767873b37
+/qilin-agent-client-ui-directory-picker-native/understand-the-implementation:
+  en: f7a287740b4b08f9
+  zh: 3347375c4e486b22
+/qilin-agent-client-ui-directory-picker-native/further-exploration:
+  en: 41bda049cc870571
+  zh: 549115c78ea39360
+/qilin-agent-client-ui-directory-picker-native/model-experience:
+  en: 35d8546cfb4b540b
+  zh: 25e4ce35c66c92e2
+/qilin-agent-client-ui-directory-picker-native/model-experience/kv-cache-effect:
+  en: ca75c51c89c2c9b0
+  zh: f57cc48a1b5cbfa9
+/qilin-agent-client-ui-directory-picker-native/known-limitations-and-deferred-work:
+  en: 52484b1e7a8c91de
+  zh: 701059acbb1b78ed
+/qilin-agent-client-ui-directory-picker-native/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+---
+description: "Native directory-picker surface: the browser half that drives the local Desktop or Host OS chooser for workspace-directory flows; for users and maintainers choosing a picking interaction."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/client-ui-directory-picker-native
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This package provides the native directory-picking surface for the Web GUI: when a workspace flow asks for a directory, a renderless browser occupant opens the operating system's own chooser on the local machine and reports the single outcome — a picked path, a cancellation, or a failure. It fills the two directory-flow slots declared by `ui-workspace`, composing the client side of the native picking interaction in one `cordis.yml` row. Choose it when the browser runs on the same machine as the Host; in-process and remote-browser deployments need the [`-browse`](../ui-directory-picker-browse/README.md) surface instead.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount this plugin alongside `ui-workspace` and the host backend [`qilin-host-directory-picker-native`](../../host/directory-picker-native/README.md); one `cordis.yml` row then composes the whole native picking interaction. When a workspace add or picker flow opens a directory request, the user sees the operating system's folder dialog; the picked path is adopted by the workspace flow, and cancelling closes the dialog.
+
+A desktop carrier may inject the narrow `__QILIN_DIRECTORY_PICKER__` preload bridge; this flow uses it when present. Cancellation and failure never retry through the Host chooser. Ordinary Web uses the Host call; the separate browse composition always lists Host directories.
+
+### When to choose it
+
+Choose this surface when the browser runs on the same machine as the Host, so an OS dialog can open there. Choose the [`-browse`](../ui-directory-picker-browse/README.md) surface when the browser is remote or in-process and no local chooser exists. The two surfaces fill the same slots, so switching is a composition change, not a code change.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+Both slot registrations install as one transactional effect through nested `ctx.slots.inject()` calls, because either declaring entry may activate later or replace its declaration. The occupant arms once per rising `open` edge, so re-renders never launch a second chooser; settlements ride a ref so the answer reaches the owner's latest handlers. An unmount (HMR replacing the occupant) discards the settlement wholesale: the wire carries no per-request abort, so the native chooser survives until answered and its answer lands nowhere. The node half is an empty `apply` that keeps the plugin on the host roster.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the picking surface is not enough. They move from the browser half to the host backend and the slots it fills.
+
+- [qilin-host-directory-picker-native](../../host/directory-picker-native/README.md) — the OS chooser backend this surface drives.
+- [ui-workspace](../ui-workspace/README.md) — declares the directory-flow slots and owns the picking conversation.
+- [ui-directory-picker-browse](../ui-directory-picker-browse/README.md) — the in-app browsing alternative for remote and in-process deployments.
+- [Web client architecture](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) — how browser plugin rows load and register slots.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the directory chooser is browser chrome; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the native chooser fits. They are current package constraints, not a general picker comparison or a task backlog.
+
+- **No cancellation of an open chooser** — the wire has no per-request abort, so a chooser already on the local display cannot be closed from the browser; a discarded settlement is ignored.
+- **Local carriers only** — a local carrier dialog selects local paths; ordinary Web opens the Host chooser. Remote-browser and in-process deployments use the `-browse` composition. Platform failures surface through the owner's retryable folder dialog.
+- **Linux automatic selection** — without zenity or kdialog, the Host selects browse even when a carrier bridge is present; the carrier dialog is not used.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,90 @@
+---
+description: "原生目录选择表面：驱动本地 Desktop 或 Host 操作系统选择器的浏览器半部，用于工作区目录流程；供选择拾取交互的用户与维护者阅读。"
+kind: "package-reference"
+---
+
+# @qilin-agent/client-ui-directory-picker-native
+
+[English](README.md) | 中文
+
+## 概述
+
+本包提供 Web GUI 的原生目录拾取表面：当工作区流程请求一个目录时，一个无渲染的浏览器填充会在本地机器上打开操作系统自带的选择器，并回报唯一结果——拾取的路径、取消或失败。它填充 `ui-workspace` 声明的两个目录流程 slot，用一行 `cordis.yml` 组合出原生拾取交互的客户端一侧。当浏览器与 Host 运行在同一台机器上时选择它；进程内与远程浏览器部署则需要 [`-browse`](../ui-directory-picker-browse/README.zh.md) 表面。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+与 `ui-workspace` 及 Host 后端 [`qilin-host-directory-picker-native`](../../host/directory-picker-native/README.zh.md) 一起挂载本插件；一行 `cordis.yml` 随即组合出完整的原生拾取交互。当工作区添加或选择器流程发起目录请求时，用户看到操作系统的文件夹对话框；拾取的路径被工作区流程采纳，取消则关闭对话框。
+
+桌面载体可以注入 preload 提供的窄 `__QILIN_DIRECTORY_PICKER__` 接口；此流程在接口存在时使用它。取消和失败都不会改用 Host 选择器重试。普通 Web 使用 Host 调用；独立的浏览组合始终列出 Host 目录。
+
+### 何时选择
+
+当浏览器与 Host 运行在同一台机器上、操作系统对话框可以在那里打开时，选择此表面。当浏览器为远程或进程内、没有本地选择器时，选择 [`-browse`](../ui-directory-picker-browse/README.zh.md) 表面。两个表面填充相同的 slot，因此切换只是组合改动，而非代码改动。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+两个 slot 注册经嵌套的 `ctx.slots.inject()` 调用作为一个事务性 effect 安装，因为任一声明条目都可能晚些激活或替换其声明。填充在每个上升沿 `open` 时只武装一次，因此重渲染永远不会再拉起一个选择器；结算结果挂在 ref 上，让答复到达持有方最新的处理器。HMR（热模块替换）导致填充被替换时，卸载会整体丢弃结算：wire 没有按请求中止的机制，因此 Host 侧选择器会一直存活到被答复，而它的答复无处落地。node 半部是一个空 `apply`，让插件留在 Host 名单上。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当拾取面不够用时阅读以下页面。它们从浏览器半部进入 Host 后端与它所填充的 slot。
+
+- [qilin-host-directory-picker-native](../../host/directory-picker-native/README.zh.md)——本表面驱动的操作系统选择器后端。
+- [ui-workspace](../ui-workspace/README.zh.md)——声明目录流程 slot 并拥有拾取对话。
+- [ui-directory-picker-browse](../ui-directory-picker-browse/README.zh.md)——面向远程与进程内部署的应用内浏览替代方案。
+- [Web 客户端架构](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md)——浏览器插件行如何加载并注册 slot。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为目录选择器属于浏览器界面；本包中的任何内容都不会进入模型请求。
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制界定了原生选择器的适用时机。它们是当前包约束，不是通用选择器对比或任务积压。
+
+- **无法取消已打开的选择器**——wire 没有按请求中止的机制，因此已显示在本地的选择器无法从浏览器关闭；被丢弃的结算会被忽略。
+- **仅限本地承载**——本地承载对话框选择本地路径；普通 Web 打开 Host 选择器。远程浏览器与进程内部署使用 `-browse` 组合。平台失败经由持有方的可重试文件夹对话框呈现。
+- **Linux 自动选择**——缺少 zenity 或 kdialog 时，Host 即使在承载接口存在时也选择浏览模式，不使用承载对话框。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/client.js

@@ -0,0 +1,84 @@
+window.__ModuleLoader__.load({
+	id: "@qilin-agent/client-ui-directory-picker-native",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react = require("react");
+		//#region lib/types/client/flow.js
+		/**
+		* The native picking occupant (package-internal; the `./client` surface
+		* exposes only the Loader exports). Same-package tests exercise it directly
+		* through this module.
+		*/
+		/**
+		* Renderless flow occupant: each rising `open` edge runs exactly one pick and
+		* reports exactly one outcome; the ref arms once per open so re-renders (and
+		* an adoption keeping `open` true while `busy`) never launch a second
+		* chooser. The owner withdrawing `open` re-arms the next request.
+		* @param props - owner conversation plus the injected pick call.
+		* @returns nothing — the native chooser renders on the host display.
+		*/
+		function NativeDirectoryFlow(props) {
+			const { open, pick } = props;
+			const armed = (0, react.useRef)(false);
+			const outcome = (0, react.useRef)(props);
+			outcome.current = props;
+			const alive = (0, react.useRef)(true);
+			(0, react.useEffect)(() => {
+				alive.current = true;
+				return () => {
+					alive.current = false;
+				};
+			}, []);
+			(0, react.useEffect)(() => {
+				if (!open) {
+					armed.current = false;
+					return;
+				}
+				if (armed.current) return;
+				armed.current = true;
+				pick().then((path) => {
+					if (!alive.current) return;
+					if (path === null) outcome.current.onCancel();
+					else outcome.current.onPicked(path);
+				}, (reason) => {
+					if (!alive.current) return;
+					outcome.current.onError(reason instanceof Error ? reason.message : String(reason));
+				});
+			}, [open, pick]);
+			return null;
+		}
+		//#endregion
+		//#region lib/types/client/index.js
+		/** Required services (cordis fiber inject): the slot registry and workspace UI service. */
+		const inject = ["slots", "uiWorkspace"];
+		/**
+		* Client plugin body: register the renderless native flow into both
+		* directory-flow holes through `slots.inject()` because the ui-workspace
+		* entries may activate later or replace their declarations.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			const desktop = globalThis.__QILIN_DIRECTORY_PICKER__;
+			const pick = desktop === void 0 ? () => ctx.uiWorkspace.pickDirectory() : () => desktop.pick();
+			const injected = () => ({ pick });
+			ctx.slots.inject("conversation.hero.workspace.directoryFlow", () => ctx.slots.inject("sidebar.workspaces.directoryFlow", function* () {
+				yield ctx.slots.register({
+					name: "conversation.hero.workspace.directoryFlow",
+					inject: injected
+				}, NativeDirectoryFlow);
+				yield ctx.slots.register({
+					name: "sidebar.workspaces.directoryFlow",
+					inject: injected
+				}, NativeDirectoryFlow);
+			}));
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,12 @@
+//#region lib/types/index.js
+/**
+* Native directory-picker surface, node half. Pure UI plugin: the empty apply
+* exists so the plugin appears in the host cordis.yml / Loader; the browser
+* half ships via exports["./client"], discovered through the package.json
+* qilin.client declaration. The OS chooser it drives lives in
+* `@qilin-agent/host-directory-picker-native`.
+*/
+/** Host plugin body — no host-side behavior for this surface plugin. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/types/client/flow.d.ts

@@ -0,0 +1,17 @@
+import type { ReactElement } from 'react';
+import type { DirectoryFlowOwnerProps } from '@qilin-agent/client-ui-workspace/client';
+/** Injected face: the native chooser call the flow drives (bound in apply's closure). */
+export interface NativeFlowInjected {
+    /** Open the local desktop or Host single-directory chooser. */
+    pick: () => Promise<string | null>;
+}
+/**
+ * Renderless flow occupant: each rising `open` edge runs exactly one pick and
+ * reports exactly one outcome; the ref arms once per open so re-renders (and
+ * an adoption keeping `open` true while `busy`) never launch a second
+ * chooser. The owner withdrawing `open` re-arms the next request.
+ * @param props - owner conversation plus the injected pick call.
+ * @returns nothing — the native chooser renders on the host display.
+ */
+export declare function NativeDirectoryFlow(props: DirectoryFlowOwnerProps & NativeFlowInjected): ReactElement | null;
+//# sourceMappingURL=flow.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,12 @@
+/** Native directory flow using the local desktop bridge or the Host's OS chooser. */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+/** Required services (cordis fiber inject): the slot registry and workspace UI service. */
+export declare const inject: string[];
+/**
+ * Client plugin body: register the renderless native flow into both
+ * directory-flow holes through `slots.inject()` because the ui-workspace
+ * entries may activate later or replace their declarations.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Native directory-picker surface, node half. Pure UI plugin: the empty apply
+ * exists so the plugin appears in the host cordis.yml / Loader; the browser
+ * half ships via exports["./client"], discovered through the package.json
+ * qilin.client declaration. The OS chooser it drives lives in
+ * `@qilin-agent/host-directory-picker-native`.
+ */
+/** Host plugin body — no host-side behavior for this surface plugin. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@qilin-agent/client-ui-directory-picker-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Native directory-picker surface: the renderless workspace directory-flow occupant driving the local Desktop or Host OS chooser",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-directory-picker-native"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/client-ui-renderer",
+        "@qilin-agent/client-ui-workspace"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@qilin-agent/client-ui-workspace": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/client-ui-renderer": "3.1.4",
+    "@qilin-agent/client-test-runtime": "3.1.4"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }