@qilin-agent/util-file-drag 0.0.0-stage → 3.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 kkutysllb
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,40 @@
1
+ # Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
2
+ # section, a hash of its English and Chinese blocks outside code blocks and generated regions.
3
+ # After editing either side, bring the other along and re-record with:
4
+ # pnpm run verify-translation-pairing --write packages/util/file-drag/README.md
5
+ /:
6
+ en: 698a0c2307c84f75
7
+ zh: 7c97281f0e2f3edd
8
+ /qilin-agent-util-file-drag:
9
+ en: c2ef6a8e50e805b6
10
+ zh: 84fa5cbe7a4770e8
11
+ /qilin-agent-util-file-drag/summary:
12
+ en: 5753bd56a486ab0f
13
+ zh: c9e10cf5ce140921
14
+ /qilin-agent-util-file-drag/table-of-contents:
15
+ en: 2e89ddb1e73218cb
16
+ zh: 8a6bc778724bb498
17
+ /qilin-agent-util-file-drag/use-this-package:
18
+ en: 3b99d71b8194d170
19
+ zh: ec0b79bdabaaa2ad
20
+ /qilin-agent-util-file-drag/model-experience:
21
+ en: 215e7ba838619b7b
22
+ zh: a311da3843709f90
23
+ /qilin-agent-util-file-drag/model-experience/no-model-visible-output:
24
+ en: 54bd40b5e1147e86
25
+ zh: 61a397812fc220f7
26
+ /qilin-agent-util-file-drag/model-experience/no-model-visible-output/what-the-model-sees:
27
+ en: c2a2eed83d37dd10
28
+ zh: ff829e1cdda5fa88
29
+ /qilin-agent-util-file-drag/model-experience/no-model-visible-output/token-effect:
30
+ en: bd16938457e46ac1
31
+ zh: 31c00670e5c199bf
32
+ /qilin-agent-util-file-drag/model-experience/no-model-visible-output/kv-cache-effect:
33
+ en: 153f9e543b14724a
34
+ zh: 75edd1e642ce73aa
35
+ /qilin-agent-util-file-drag/known-limitations-and-deferred-work:
36
+ en: f41a82f415a6f5aa
37
+ zh: 7304089c56838bfe
38
+ /qilin-agent-util-file-drag/known-limitations-and-deferred-work/dev-note:
39
+ en: b836f01bd0bceb4a
40
+ zh: 8122fa08b2aa95fa
package/README.md CHANGED
@@ -1,3 +1,62 @@
1
- # Temporary Holding Version
1
+ ---
2
+ description: "Shared export filenames and native file drag requests for Web and Desktop."
3
+ kind: "package-library"
4
+ ---
2
5
 
3
- 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.
6
+ # @qilin-agent/util-file-drag
7
+
8
+ English | [中文](README.zh.md)
9
+
10
+ ## Summary
11
+
12
+ Callers can export files with the same safe filename in Web and Desktop. MIME data fills missing suffixes without limiting accepted file types. The library also declares native byte and authorized-resource requests; it holds no files or application state.
13
+
14
+ ## Table of Contents
15
+
16
+ - [Use this package](#use-this-package)
17
+ - [Model Experience](#model-experience)
18
+ - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
19
+ - [Dev Note](#dev-note)
20
+
21
+ <a id="use-this-package"></a>
22
+ ## Use this package
23
+
24
+ `resolveDragFileName({ name, mediaType, outputExtension })` sanitizes path separators, reserved characters, and Windows device names. An explicit output suffix wins. Otherwise a compatible existing suffix is preserved, a known conflict is replaced using the declared MIME, and a missing suffix is completed from the maintained `mime` database. Unknown types retain a supplied name or suffix; unnamed content starts with `file`. Names fit 255 UTF-8 bytes, preserving the suffix and whole Unicode characters. Desktop validates wire input before using this typed resolver.
25
+
26
+ `FILE_DRAG_TOKEN_TYPE` names the browser transfer's `application/x-qilin-file` entry. Senders and drop targets import it directly from this package; the owning plugin retains the file bytes. The package root is safe to inline into client bundles because its exports share no runtime identity or application state.
27
+
28
+ `DesktopFileDrag.prepare(source, requestId)` accepts complete bytes or a Session resource reference, returning an opaque handle. `cancel(requestId)` stops unfinished preparation before a handle is available. Resource borrowing requires Host authorization and main-process content/name checks; callers fall back to byte preparation when borrowing is unavailable. Browser preparation belongs to the drag-and-drop client plugin, which is not yet in this tree; [Desktop](../../../apps/desktop/README.md) owns native delivery.
29
+
30
+ <a id="model-experience"></a>
31
+ ## Model Experience
32
+
33
+ ### No model-visible output
34
+
35
+ #### What the model sees
36
+
37
+ Nothing. `resolveDragFileName` resolves export filenames, and `FILE_DRAG_TOKEN_TYPE` with the `DesktopFileDrag` request types describe browser and Desktop transfer contracts; no code path assembles prompts, tool schemas, or model requests.
38
+
39
+ #### Token effect
40
+
41
+ None; no token, schema, or message is added to any request.
42
+
43
+ #### KV Cache effect
44
+
45
+ None; the package contributes no prompt text or tool definition.
46
+
47
+ ## Known Limitations and Deferred Work
48
+
49
+ <a id="known-limitations-and-deferred-work"></a>
50
+
51
+ - Names describe the caller-declared MIME; this library does not inspect content or infer an unknown format. Explicit suffixes intentionally override MIME naming.
52
+ - No in-tree consumer yet: the drag-and-drop client plugin and its Desktop bridge consume this contract, and arrive with a later port.
53
+
54
+ <a id="dev-note"></a>
55
+ ### Dev Note
56
+
57
+ <details>
58
+ <summary>Working context for maintainers</summary>
59
+
60
+ None.
61
+
62
+ </details>
package/README.zh.md ADDED
@@ -0,0 +1,62 @@
1
+ ---
2
+ description: "Web 与 Desktop 共用的导出文件名及原生文件拖放请求。"
3
+ kind: "package-library"
4
+ ---
5
+
6
+ # @qilin-agent/util-file-drag
7
+
8
+ [English](README.md) | 中文
9
+
10
+ ## 概述
11
+
12
+ 调用方可在 Web 与 Desktop 使用相同的安全文件名导出文件。MIME 数据补全缺失后缀,不限制可接受的文件类型。该库还声明原生字节及授权资源请求,不持有文件或应用状态。
13
+
14
+ ## 目录
15
+
16
+ - [使用此包](#use-this-package)
17
+ - [模型体验](#model-experience)
18
+ - [已知限制与后续工作](#known-limitations-and-deferred-work)
19
+ - [开发备注](#dev-note)
20
+
21
+ <a id="use-this-package"></a>
22
+ ## 使用此包
23
+
24
+ `resolveDragFileName({ name, mediaType, outputExtension })` 清理路径分隔符、保留字符与 Windows 设备名。显式输出后缀优先;否则保留兼容的已有后缀,已知冲突按声明 MIME 替换,缺失后缀从持续维护的 `mime` 数据库补全。未知类型保留调用方名称或后缀,无名内容以 `file` 命名。名称不超过 255 个 UTF-8 字节,保留后缀和完整 Unicode 字符。Desktop 在调用此类型化解析器前验证跨进程输入。
25
+
26
+ `FILE_DRAG_TOKEN_TYPE` 命名浏览器传输中的 `application/x-qilin-file` 数据项。发送端和投放目标直接从本包导入,文件字节由所属插件保留。包根入口的导出不共享运行时身份或应用状态,因此可安全内联到客户端 bundle。
27
+
28
+ `DesktopFileDrag.prepare(source, requestId)` 接受完整字节或 Session 资源地址,返回不透明句柄。`cancel(requestId)` 可在句柄返回前停止未完成的准备。资源借用必须经过 Host 授权与主进程的内容、名称检查;无法借用时,调用方回退到字节准备。浏览器准备归属于尚未落入本仓库的拖放客户端插件;[Desktop](../../../apps/desktop/README.zh.md) 负责原生交付。
29
+
30
+ <a id="model-experience"></a>
31
+ ## 模型体验
32
+
33
+ ### 无模型可见输出
34
+
35
+ #### 模型看到什么
36
+
37
+ 无。`resolveDragFileName` 解析导出文件名,`FILE_DRAG_TOKEN_TYPE` 与 `DesktopFileDrag` 请求类型描述浏览器与 Desktop 的传输契约;没有任何代码路径组装提示词、工具 schema 或模型请求。
38
+
39
+ #### Token effect
40
+
41
+ 无;任何请求都不增加 token、schema 或消息。
42
+
43
+ #### KV Cache 影响
44
+
45
+ 无;该包不贡献提示词文本或工具定义。
46
+
47
+ ## 已知限制与后续工作
48
+
49
+ <a id="known-limitations-and-deferred-work"></a>
50
+
51
+ - 名称遵循调用方声明的 MIME;该库不检查内容,也不推断未知格式。显式后缀会有意覆盖 MIME 命名。
52
+ - 本仓库暂无消费方:拖放客户端插件及其 Desktop 桥接消费此契约,随后续移植落地。
53
+
54
+ <a id="dev-note"></a>
55
+ ### 开发备注
56
+
57
+ <details>
58
+ <summary>维护者工作背景</summary>
59
+
60
+ 无。
61
+
62
+ </details>
package/lib/index.js ADDED
@@ -0,0 +1,41 @@
1
+ import mime from "mime";
2
+ //#region lib/types/index.js
3
+ /** File export naming, browser transfer token type, and native byte-or-resource requests. */
4
+ /** Browser transfer token type; original bytes stay with the application owner. */
5
+ const FILE_DRAG_TOKEN_TYPE = "application/x-qilin-file";
6
+ /**
7
+ * Resolve one platform-safe export filename. Explicit suffix wins; compatible suffixes survive.
8
+ * A known conflicting suffix is replaced from MIME; unknown MIME never rejects a supplied name.
9
+ * @param request - caller name, declared content type, and optional explicit suffix.
10
+ * @returns cleaned filename, with MIME-derived suffix only when needed.
11
+ */
12
+ function resolveDragFileName(request) {
13
+ const { name = "file", mediaType, outputExtension } = request;
14
+ let clean = name.replace(/[<>:"/\\|?*\x00-\x1f]/gu, "_").replace(/^[. ]+|[. ]+$/gu, "") || "file";
15
+ const dot = clean.lastIndexOf(".");
16
+ const suffix = dot < 0 ? "" : clean.slice(dot + 1);
17
+ const declared = mediaType.replace(/;.*$/su, "").trim().toLowerCase();
18
+ const preferred = mime.getExtension(declared);
19
+ const explicit = outputExtension?.replace(/^\./u, "").replace(/[^a-z\d_-]/giu, "");
20
+ const compatible = mime.getAllExtensions(declared)?.has(suffix.toLowerCase()) === true;
21
+ const extension = explicit || (suffix === "" || preferred !== null && !compatible ? preferred : suffix);
22
+ if (extension) clean = `${dot < 0 ? clean : clean.slice(0, dot)}.${extension}`;
23
+ if (/^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/iu.test(clean)) clean = `_${clean}`;
24
+ const finalDot = clean.lastIndexOf(".");
25
+ const tail = finalDot < 0 ? "" : clean.slice(finalDot);
26
+ const encoder = new TextEncoder();
27
+ const truncate = (value, bytes) => {
28
+ let result = "";
29
+ for (const character of value) {
30
+ const length = encoder.encode(character).length;
31
+ if (length > bytes) break;
32
+ result += character;
33
+ bytes -= length;
34
+ }
35
+ return result;
36
+ };
37
+ const extensionTail = truncate(tail, 32);
38
+ return `${truncate(finalDot < 0 ? clean : clean.slice(0, finalDot), 255 - encoder.encode(extensionTail).length)}${extensionTail}`;
39
+ }
40
+ //#endregion
41
+ export { FILE_DRAG_TOKEN_TYPE, resolveDragFileName };
@@ -0,0 +1,46 @@
1
+ import type { Branded } from '@qilin-agent/brand';
2
+ /** Browser transfer token type; original bytes stay with the application owner. */
3
+ export declare const FILE_DRAG_TOKEN_TYPE = "application/x-qilin-file";
4
+ /** Opaque preparation identity, minted and resolved only by the desktop main process. */
5
+ export type FileDragHandle = Branded<'FileDragHandle'>;
6
+ /** Caller-minted identity for cancelling a native preparation before it returns a handle. */
7
+ export type FileDragRequestId = Branded<'FileDragRequestId'>;
8
+ /** Caller-supplied export naming, shared by Web and Desktop. */
9
+ export interface DragFileName {
10
+ readonly name?: string | undefined;
11
+ readonly mediaType: string;
12
+ readonly outputExtension?: string | undefined;
13
+ }
14
+ /** Native preparation copies bytes or asks the Host to authorize borrowing a resource. */
15
+ export type DesktopFileSource = DragFileName & ({
16
+ readonly kind: 'bytes';
17
+ readonly bytes: Uint8Array;
18
+ } | {
19
+ readonly kind: 'resource';
20
+ readonly address: string;
21
+ readonly sha256?: string;
22
+ readonly size?: number;
23
+ });
24
+ /** Native file operations; no request accepts a raw renderer filesystem path. */
25
+ export interface DesktopFileDrag {
26
+ /**
27
+ * @param source - bytes or a verifiable resource.
28
+ * @param requestId - cancellation identity.
29
+ * @returns a handle, or undefined if the resource needs a byte copy.
30
+ */
31
+ prepare(this: void, source: DesktopFileSource, requestId: FileDragRequestId): Promise<FileDragHandle | undefined>;
32
+ /** Cancel unfinished preparation and release its unused resources. @param requestId - preparation identity. */
33
+ cancel(this: void, requestId: FileDragRequestId): void;
34
+ /** @param handle - prepared file. @returns whether the OS accepted the drag. */
35
+ start(this: void, handle: FileDragHandle): Promise<boolean>;
36
+ /** Release unused preparation; OS-delivered temporary files receive a bounded read grace period. @param handle - prepared file. */
37
+ release(this: void, handle: FileDragHandle): void;
38
+ }
39
+ /**
40
+ * Resolve one platform-safe export filename. Explicit suffix wins; compatible suffixes survive.
41
+ * A known conflicting suffix is replaced from MIME; unknown MIME never rejects a supplied name.
42
+ * @param request - caller name, declared content type, and optional explicit suffix.
43
+ * @returns cleaned filename, with MIME-derived suffix only when needed.
44
+ */
45
+ export declare function resolveDragFileName(request: DragFileName): string;
46
+ //# sourceMappingURL=index.d.ts.map
package/package.json CHANGED
@@ -1,6 +1,42 @@
1
1
  {
2
2
  "name": "@qilin-agent/util-file-drag",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "description": "Shared file drag names and native transfer requests",
4
+ "version": "3.1.8",
5
+ "publishConfig": {
6
+ "access": "public"
7
+ },
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/kkutysllb/QiLin.git",
11
+ "directory": "packages/util/file-drag"
12
+ },
13
+ "engines": {
14
+ "node": "^22.19.0 || >=24.0.0"
15
+ },
16
+ "type": "module",
17
+ "main": "lib/index.js",
18
+ "types": "lib/types/index.d.ts",
19
+ "exports": {
20
+ ".": {
21
+ "types": "./lib/types/index.d.ts",
22
+ "default": "./lib/index.js"
23
+ },
24
+ "./src/*": "./src/*",
25
+ "./package.json": "./package.json"
26
+ },
27
+ "files": [
28
+ "lib/index.js",
29
+ "lib/types/**/*.d.ts"
30
+ ],
31
+ "license": "MIT",
32
+ "peerDependencies": {
33
+ "@qilin-agent/kylin": "~4.0.6-alpha.2"
34
+ },
35
+ "devDependencies": {
36
+ "@qilin-agent/kylin": "~4.0.6-alpha.2",
37
+ "@qilin-agent/brand": "3.1.8"
38
+ },
39
+ "dependencies": {
40
+ "mime": "^4.1.1"
41
+ }
6
42
  }