@deepseek-ai/dsh-client-ui-directory-picker-native 0.0.1-rc.3

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/client/ui-directory-picker-native/README.md
+README.md: feb944b38a17086e0fcc6e4da52e1f16a4055166
+README.zh.md: 0420fb4d5edc0c05ce72d68243c7377b144ee639

package/README.md

@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-ui-directory-picker-native
+
+English | [中文](README.zh.md)
+
+Native directory-picker surface: the browser half of the native picking interaction. It fills ui-workspace's two directory-flow holes (`conversation.hero.workspace.directoryFlow` and `sidebar.workspaces.directoryFlow`) with a renderless occupant that answers each `open` request by driving the local Host's OS chooser through `ctx.workspaces.pickDirectory()`, then reports exactly one outcome — a picked path, a cancellation, or a failure — back through the owner conversation. The OS dialog itself belongs to [`dsh-host-directory-picker-native`](../../host/directory-picker-native/README.md); mounting this package composes the surface with that backend from one cordis.yml row, so no client code branches on a capability kind.
+
+Both registrations install as one transactional effect through nested `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 — including an adoption that keeps `open` true while `busy` — never launch a second chooser, and the owner withdrawing `open` re-arms the next request. Settlements ride a ref so the answer reaches the owner's latest handlers rather than the ones captured when the chooser opened. An unmount (HMR replacing the occupant) discards the settlement wholesale: the wire carries no per-request abort, so the host-side chooser survives until answered, its answer lands nowhere, and the replacement instance re-arms under the owner's still-open request.
+
+The node half is an empty `apply`: it exists so the plugin appears in the host cordis.yml and Loader, while the browser half ships through `exports["./client"]` and is discovered through the `dsh.client` manifest declaration.
+
+## 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
+
+- **No cancellation of an open chooser** — the wire has no per-request abort, so a chooser already on the host display cannot be closed from the browser; a discarded settlement is simply ignored.
+- **Local Host carriers only** — an OS dialog opens on the machine running the Host, so in-process and remote-browser deployments need the `-browse` composition instead. Platform failures surface through the owner's retryable folder dialog.

package/README.zh.md

@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-ui-directory-picker-native
+
+[English](README.md) | 中文
+
+原生目录选择界面：原生选取交互的浏览器半边。它通过 ui-workspace 的两个 directory-flow 洞（`conversation.hero.workspace.directoryFlow` 与 `sidebar.workspaces.directoryFlow`）装入一个无渲染占位者，每次收到 `open` 请求就用 `ctx.workspaces.pickDirectory()` 驱动本地 Host 的操作系统选择框，然后通过 owner 会话回报恰好一个结果——选中的路径、取消、或失败。系统对话框本身属于 [`dsh-host-directory-picker-native`](../../host/directory-picker-native/README.md)；挂载本包即用一行 cordis.yml 把界面与该后端组合起来，因此没有任何客户端代码按能力种类分支。
+
+两处注册通过嵌套的 `slots.inject()` 作为一个事务性 effect 安装，因为任一声明方条目都可能稍后激活或替换其声明。占位者在每个 `open` 上升沿只武装一次，所以重渲染（包括采纳期间 `busy` 而 `open` 仍为真）都不会再开第二个选择框；owner 撤回 `open` 会为下一次请求重新武装。结果经由 ref 回报，因此答案落到 owner 最新的处理器上，而不是打开选择框时捕获的那一套。卸载（HMR 替换占位者）会整体丢弃该结果：wire 上没有按请求的中止通道，所以 Host 侧的选择框会一直存在到被回答，它的答案无处可落，替换后的实例则在 owner 仍然打开的请求下重新武装。
+
+node 半边是一个空 `apply`：它的存在只为让插件出现在 host 的 cordis.yml 与 Loader 中，浏览器半边经 `exports["./client"]` 出货，并通过 `dsh.client` 清单声明被发现。
+
+## 模型体验
+
+无，因为目录选择器属于浏览器界面；本包中的任何内容都不会进入模型请求。
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送 provider 请求。
+
+## 已知限制与暂缓事项
+
+- **无法取消已打开的选择框** —— wire 上没有按请求的中止通道，因此已经出现在 Host 显示器上的选择框无法从浏览器关闭；被丢弃的结果只是被忽略。
+- **仅限本地 Host 载体** —— 系统对话框开在运行 Host 的机器上，所以进程内与远程浏览器部署需要改用 `-browse` 组合。平台失败通过 owner 的可重试文件夹对话框呈现。

package/lib/client.js

@@ -0,0 +1,82 @@
+window.__ModuleLoader__.load({
+	id: "@deepseek-ai/dsh-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 the wire-facing workspace service. */
+		const inject = ["slots", "workspaces"];
+		/**
+		* 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 injected = () => ({ pick: () => ctx.workspaces.pickDirectory() });
+			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
+* dsh.client declaration. The OS chooser it drives lives in
+* `@deepseek-ai/dsh-host-directory-picker-native`.
+*/
+/** Host plugin body — no host-side behavior for this surface plugin. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-directory-picker-native`.
+* @module @deepseek-ai/dsh-client-ui-directory-picker-native/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-client-ui-directory-picker-native";
+/** Cordis companion plugin name. */
+const name = "client-ui-directory-picker-native-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the plugin registers a renderless flow occupant into
+* two workspace holes as one transactional effect, whose disposal the
+* HMR-safety spec proves, and it retains no state between picks.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

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

@@ -0,0 +1,17 @@
+import type { ReactElement } from 'react';
+import type { DirectoryFlowOwnerProps } from '@deepseek-ai/dsh-client-ui-workspace/client';
+/** Injected face: the wire call the flow drives (bound in apply's closure). */
+export interface NativeFlowInjected {
+    /** Ask the local Host to open its native 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,20 @@
+/**
+ * Browser half of the native directory-picker backend: fills ui-workspace's
+ * two directory-flow holes with a renderless occupant that answers each
+ * `open` by driving `host.pickDirectory` (the node half's OS chooser) and
+ * reporting the one outcome — picked path, cancellation, or failure — back
+ * through the owner conversation. Mounting this package therefore composes
+ * both sides of the native interaction with one cordis.yml row; no client
+ * code branches on a capability kind.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+/** Required services (cordis fiber inject): the slot registry and the wire-facing workspace 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
+ * dsh.client declaration. The OS chooser it drives lives in
+ * `@deepseek-ai/dsh-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/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-directory-picker-native`.
+ * @module @deepseek-ai/dsh-client-ui-directory-picker-native/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-ui-directory-picker-native-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-directory-picker-native",
+  "description": "Native directory-picker surface: the renderless workspace directory-flow occupant driving the host's OS chooser",
+  "version": "0.0.1-rc.3",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-directory-picker-native"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-workspace"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-workspace": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-workspace": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}