@prettier-ai/dsh-client-ui-reference 0.1.2-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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,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-reference/README.md
+README.md: 1f82f4bb30f2ad5d194a70279f9e80885d6a048e
+README.zh.md: 03a79ec4ff34431a63d8a7b0de115e3ec63b9392

package/README.md

@@ -0,0 +1,102 @@
+---
+description: "Web @file and @session reference source for the composer: candidates, ordering, and atomic inline references (unified file/session picking)."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-ui-reference
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-client-ui-reference` is the unified Web `@file` and `@session` reference source: it registers the `reference` entry in the composer's inline-suggestion machinery so a user typing `@` sees file and session candidates in one list. Files order before sessions, sections are labelled with locale-registered terms, and either candidate domain can fail independently without blocking the other. Each row carries only what distinguishes it: a file names its parent directory and nothing at the workspace root, a session names its workspace only when that workspace is not the current one, and a drilled directory listing names none because its breadcrumb already does. A pick inserts an atomic inline reference — file, folder, and session alike — whose hidden serialized and clipboard form is the natural text the shared `@path` grammar defines; a directory row additionally carries a drill verb (Tab or the row's chevron) that keeps plain editable path text and the menu active at its trailing slash so the user can descend another level. Selecting a session routes through the session-reference service, which validates the mention and captures model context at the pre-step boundary; this package itself registers no prompt or tool.
+
+## 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
+
+The source is active whenever the composition mounts this package and a Host `ctx.fileReferences` provider is available. Type `@` followed by an unquoted token to see files first, then sessions; open `@"…` to search files only. The candidate list is a completion menu, not a search result page: pick once and keep typing.
+
+### What a pick inserts
+
+A file closes completion as an atomic inline reference displayed with a file glyph and business-color filename. A directory row carries two verbs: the settling pick (row click or Enter) resolves the folder itself as the same kind of atomic reference — folder glyph, trailing-slash label, canonical `@dir/` mention as its serialized form — while the drill action (Tab or the row's chevron) keeps plain editable path text with a folder glyph and the menu active at its trailing slash, so you can descend another level. Paths containing whitespace use `@"path with spaces"`, and a quote the user opened explicitly remains quoted.
+
+A session pick inserts an atomic inline reference whose hidden `ref` and clipboard representation is the canonical `@[label](dsh-session:…)` mention returned by the Host; its visible form is a chat-bubble glyph plus the session title. Sending carries the mention through `session.prompt`, and the session-reference service validates it and captures model context at `agent/pre-step`.
+
+### Failure behavior
+
+One unavailable or failed candidate domain yields no rows for that domain while the other still lists. A session-reference preparation failure occurs after prompt acceptance and terminates that agent turn.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The source keeps candidate encoding internal to the registration effect: the `/client` export is the plugin body (`apply`/`inject`) only.
+
+### Candidate flow
+
+For an unquoted token, the browser starts the `fileReferences/list` and `sessionReferenceResolver/candidates` Remote calls together, then deterministically orders files before sessions with locale-registered folder/file/session labels. Rows render under non-selectable file and session section headings without a redundant raw `reference` source title. A session row is dated from the Host session list's `updatedAt` through the same relative-time bucket that list uses, so one session reads the same age on both surfaces; a session the list does not carry falls back to the candidate's creation time. A drilled query publishes a breadcrumb from the workspace root to the directory being listed; each crumb carries the drill payload a folder row would, so returning to a step and descending into one are one outcome.
+
+### Serialization
+
+File picks preserve the natural text defined by the shared `@path` grammar as the hidden serialized and clipboard form. Session picks use the canonical `@[label](dsh-session:…)` mention; serialization never reconstructs identity from the visible title.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+These pages cover the suggestion machinery, the reference seams, and the input pipeline.
+
+- [ui-input-trigger](../ui-input-trigger/README.md) — the inline suggestion machinery the source registers into.
+- [file-reference](../../context/file-reference/README.md) — the `@file` seam and its provider contract.
+- [session-reference](../../context/session-reference/README.md) — the `@session` seam and prepared snapshot semantics.
+- [Web input machine and slash pipeline](../../../.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) — how references and commands share the input machine.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through Host-owned providers, which own the file guidance and session snapshot preparation this package's reference selection delegates to them.
+
+#### KV Cache effect
+
+Candidate browsing has no model effect. A selected file or session changes only the new user-message suffix and any Host-prepared session-reference context that follows that message; earlier target history remains unchanged.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the reference source cannot help; they are current package constraints.
+
+- **Candidate failure is intentionally quiet** — one unavailable or failed Remote discovery call yields no rows for that domain. A session-reference preparation failure occurs after prompt acceptance and terminates that agent turn.
+- **No browser-side file scan** — Web completion requires a mounted Host `ctx.fileReferences` provider; the browser cannot fall back to its own filesystem.
+- **Session search remains metadata-only** — discovery filters session id, cwd, and the latest log-backed title through `ctx.sessionReferenceResolver`; message bodies and full transcripts are not searched.
+
+<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,102 @@
+---
+description: "Web @file 与 @session 引用 source：候选项、排序，以及原子行内引用（统一的文件/会话选取）。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-ui-reference
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-client-ui-reference` 是统一的 Web `@file` 与 `@session` 引用 source：它把 `reference` 条目注册进编辑器的行内建议机制，让用户在输入 `@` 时于同一个列表中看到文件与会话候选。文件排在会话之前，分组标题使用注册在 locale 字典中的标签，任一候选领域失败都会独立降级、不阻塞另一领域。每一行只承载能区分它的信息：文件显示其父目录、位于工作区根目录时不显示；会话仅在其工作区不是当前工作区时显示该工作区；下钻后的目录列表不显示位置，因为面包屑已经承载了它。选择一项会插入原子行内引用——文件、文件夹与会话皆然——其隐藏的序列化与剪贴板形式就是共享 `@path` 语法所定义的自然文本；目录行额外携带一个钻取动词（Tab 或行尾 chevron），保持可编辑的路径纯文本并让菜单在尾部斜杠处保持活跃，用户可以继续进入下一层。选择会话会经 session-reference 服务路由，该服务校验 mention 并在 pre-step 边界捕获模型上下文；本包自身不注册任何提示词或工具。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+只要组合挂载了本包且存在宿主 `ctx.fileReferences` 提供方，该 source 即处于活动状态。输入 `@` 后跟一个未加引号的 token，会先看到文件、再看到会话；打开 `@"…` 则只搜索文件。候选列表是补全菜单，不是搜索结果页：选一次、继续输入即可。
+
+### 选择后会插入什么
+
+选择文件会关闭补全，并显示为带文件图标与业务色文件名的原子行内引用。目录行携带两个动词：选定 pick（点击行主体或 Enter）把文件夹本身解析为同类原子引用——文件夹图标、带尾斜杠的标签、以规范 `@dir/` mention 为序列化形式；钻取动作（Tab 或行尾 chevron）则保持带文件夹图标的可编辑路径纯文本，并让菜单在尾部斜杠处保持活跃，用户可以继续进入下一层。包含空白的路径使用 `@"path with spaces"`，用户显式打开的引号会继续保留。
+
+选择会话会插入一个原子的行内引用，其隐藏 `ref` 与剪贴板表示均为宿主返回的规范 `@[label](dsh-session:…)` mention；可见形式为聊天气泡图标加会话标题。发送会经 `session.prompt` 携带该 mention，session-reference 服务会在 `agent/pre-step` 校验它并捕获模型上下文。
+
+### 失败行为
+
+某个候选领域不可用或失败时，该领域不产生任何行，另一领域仍正常列出。会话引用准备失败发生在提示词接受后，并会终止该 agent 轮次。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+该 source 把候选编码保留在注册 effect 内部：`/client` 导出接口只包含插件主体（`apply`/`inject`）。
+
+### 候选流程
+
+对于未加引号的 token，浏览器会同时启动 `fileReferences/list` 与 `sessionReferenceResolver/candidates` Remote 调用，再以确定性顺序把文件排在会话之前，并使用注册在 locale 字典中的文件夹、文件与会话标签。各行分别渲染在不可选择的文件与会话分组标题下，不显示重复的原始 `reference` source 标题。会话行用宿主会话列表的 `updatedAt` 经该列表相同的相对时间分档标注时间，因此同一个会话在两处读到的时长一致；列表中没有的会话回落到候选自带的创建时间。下钻后的查询会发布一条从工作区根目录到当前所列目录的面包屑；每一节携带的下钻载荷与文件夹行相同，因此「回到某一步」与「进入某一层」是同一个结果。
+
+### 序列化
+
+文件选择把共享 `@path` 语法所定义的自然文本保留为隐藏的序列化与剪贴板形式。会话选择使用规范的 `@[label](dsh-session:…)` mention；序列化永远不会根据可见标题重建身份。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+以下页面覆盖建议机制、引用 seam 与输入流水线。
+
+- [ui-input-trigger](../ui-input-trigger/README.zh.md)——该 source 注册进的行内建议机制。
+- [file-reference](../../context/file-reference/README.zh.md)——`@file` seam 及其提供方约定。
+- [session-reference](../../context/session-reference/README.zh.md)——`@session` seam 与准备后快照的语义。
+- [Web 输入机器与 slash 流水线](../../../.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md)——引用与命令如何共享输入机器。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+间接影响模型体验：通过宿主拥有的提供方实现，本包的引用选择把文件指引与会话快照准备委托给它们。
+
+#### KV Cache 影响
+
+浏览候选项不会影响模型。选择文件或会话只会改变新用户消息的后缀，以及紧随该消息、由宿主准备的会话引用上下文；目标会话更早的历史保持不变。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明引用 source 何时帮不上忙；它们是当前包约束。
+
+- **候选失败有意保持静默**：Remote 发现调用不可用或失败时，该领域不产生候选行。会话引用准备失败发生在提示词接受后，并会终止该 agent 轮次。
+- **浏览器侧不扫描文件**：Web 补全需要挂载宿主 `ctx.fileReferences` 提供方；浏览器无法回退到自身文件系统。
+- **会话搜索仍仅使用元数据**：发现流程通过 `ctx.sessionReferenceResolver` 筛选 session id、cwd 与以日志为依据的最新标题；不搜索消息主体或完整 transcript。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/client.js

@@ -0,0 +1,254 @@
+window.__ModuleLoader__.load({
+	id: "@prettier-ai/dsh-client-ui-reference",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let _prettier_ai_dsh_client_ui_primitives = require("@prettier-ai/dsh-client-ui-primitives");
+		//#region ../../context/file-reference/src/grammar.ts
+		/**
+		* Format a selected path as prompt text. Whitespace uses the quoted
+		* `@"path"` grammar; a quoted directory keeps that quote open after its
+		* trailing slash so completion can descend another level.
+		* @param candidate - selected file or directory.
+		* @param preserveQuote - retain an explicitly opened quote even when unnecessary.
+		* @returns the insertion value, or `undefined` for a path the editor grammar cannot represent safely.
+		*/
+		function formatFileMention(candidate, preserveQuote) {
+			const path = candidate.kind === "directory" ? `${candidate.path}/` : candidate.path;
+			if (/[\u0000-\u001f\u007f-\u009f"]/u.test(path)) return void 0;
+			if (!(preserveQuote || /\s/u.test(path))) return `@${path}`;
+			if (candidate.kind === "directory") return `@"${path}`;
+			return `@"${path}"`;
+		}
+		//#endregion
+		//#region ../../util/workspace-path/src/index.ts
+		/**
+		* Browser-safe Workspace path and display helpers.
+		* @module @prettier-ai/dsh-util-workspace-path
+		*/
+		/** Whether a path uses a Windows drive or UNC prefix. */
+		function isWindowsStylePath(value) {
+			return /^[A-Za-z]:[/\\]/.test(value) || value.startsWith("\\\\");
+		}
+		/**
+		* Abbreviate a POSIX home directory for display.
+		* @param path - Absolute or already-short display path.
+		* @param home - Host account home; absent skips abbreviation.
+		* @returns `~` or `~/…` for the POSIX home and its descendants, otherwise `path`.
+		*/
+		function abbreviateHomePath(path, home) {
+			if (home === void 0 || home === "") return path;
+			if (isWindowsStylePath(path) || isWindowsStylePath(home)) return path;
+			const root = home.replace(/\/+$/, "");
+			if (root === "" || root === "/") return path;
+			if (path.replace(/\/+$/, "") === root) return "~";
+			if (path.startsWith(`${root}/`)) return `~${path.slice(root.length)}`;
+			return path;
+		}
+		//#endregion
+		//#region lib/types/client/locales.js
+		/** `reference` namespace dictionaries for the unified `@` source. */
+		/** Dictionary namespace owned by this plugin. */
+		const NS = "reference";
+		/**
+		* Simplified Chinese dictionary (the key-set source of truth).
+		*
+		* The `time.*` bucket words are this namespace's own copy of the session-row
+		* vocabulary: locale-owned copy keeps the words per plugin, while the
+		* bucketing they name is the one shared {@link relativeTime} in ui-primitives.
+		*/
+		const zh = {
+			"section.files": "文件与文件夹",
+			"section.sessions": "对话",
+			"candidate.noCwd": "（无工作目录）",
+			"crumb.root": "工作区",
+			"time.now": "刚刚",
+			"time.minutes": "{n}分钟",
+			"time.hours": "{n}小时",
+			"time.days": "{n}天",
+			"time.months": "{n}个月",
+			"time.years": "{n}年"
+		};
+		/** English dictionary, checked complete against the zh key set. */
+		const en = {
+			"section.files": "Files & folders",
+			"section.sessions": "Sessions",
+			"candidate.noCwd": "(no cwd)",
+			"crumb.root": "Workspace",
+			"time.now": "now",
+			"time.minutes": "{n}min",
+			"time.hours": "{n}h",
+			"time.days": "{n}d",
+			"time.months": "{n}mo",
+			"time.years": "{n}y"
+		};
+		//#endregion
+		//#region lib/types/client/index.js
+		/** Required services: the trigger registry, the Remote namespaces, and the copy. */
+		const inject = [
+			"inputTriggers",
+			"locale",
+			"connection",
+			"sessions",
+			"remote",
+			"remote.fileReferences",
+			"remote.sessionReferenceResolver"
+		];
+		/**
+		* Register the combined `@file` / `@session` source.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			ctx.effect(() => ctx.locale.register(NS, {
+				zh,
+				en
+			}), "ui-reference: dictionaries");
+			const t = ctx.locale.bind(NS);
+			const connection = ctx.get("connection");
+			const sessions = ctx.get("sessions");
+			const source = {
+				trigger: "@",
+				name: "reference",
+				showGroupTitle: false,
+				async candidates(session, { query, quoted, drilled, signal }) {
+					const fileLookup = ctx.remote.fileReferences.list(session.sessionId, query, signal).then((result) => result.ok ? result.value : [], () => []);
+					const sessionLookup = quoted === true ? Promise.resolve([]) : ctx.remote.sessionReferenceResolver.candidates(session.sessionId, query, signal).then((result) => result.ok ? result.value : [], () => []);
+					const [fileItems, sessionItems] = await Promise.all([fileLookup, sessionLookup]);
+					if (signal.aborted) return [];
+					const withLocation = crumbsFor(query, quoted === true, drilled, t) === void 0;
+					const now = Date.now();
+					const home = connection.generation.getSnapshot()?.host.home;
+					const listed = sessions.list.getSnapshot().byId;
+					return [...fileItems.flatMap((candidate) => fileCandidate(candidate, quoted === true, withLocation, t)), ...sessionItems.map((candidate) => sessionCandidate(candidate, listed[candidate.sessionId]?.updatedAt ?? candidate.createdAt, now, home, t))];
+				},
+				header(_session, req) {
+					return crumbsFor(req.query, req.quoted === true, req.drilled, t);
+				},
+				onPick({ candidate, action }) {
+					const value = parseCandidate(candidate.value);
+					if (value?.kind === "file") {
+						if (value.fileKind === "directory" && action === "drill") return {
+							text: value.mention,
+							continue: true
+						};
+						return { insert: {
+							source: "reference",
+							ref: value.mention,
+							label: value.fileKind === "directory" ? `${value.label}/` : value.label,
+							appearance: value.fileKind === "directory" ? "folder" : "file",
+							clipboardText: value.mention
+						} };
+					}
+					if (value?.kind === "session") return { insert: {
+						source: "reference",
+						ref: value.mention,
+						label: value.label,
+						appearance: "session",
+						clipboardText: value.mention
+					} };
+				},
+				codec: {
+					clipboardText: (ref) => ref,
+					serialize: (ref) => Promise.resolve(ref)
+				}
+			};
+			const inputTriggers = ctx.get("inputTriggers");
+			ctx.effect(() => inputTriggers.registerSource(source), "ui-reference: @ source");
+		}
+		/**
+		* The breadcrumb of a drilled directory listing, from the workspace root down
+		* to the directory being listed.
+		*
+		* Only a drill produces one: a path the user typed carries its own context in
+		* the draft, while a drill replaced the text they were reading with a deeper
+		* one and owes them the way back.
+		* @param query - the live query, path text following `@` or `@"`.
+		* @param quoted - whether the active token is an open quoted path.
+		* @param drilled - whether a drill pick, rather than typing, produced the query.
+		* @param t - the reference dictionary.
+		* @returns the crumbs, or undefined when this listing needs no header.
+		*/
+		function crumbsFor(query, quoted, drilled, t) {
+			if (!drilled) return void 0;
+			const slash = query.lastIndexOf("/");
+			if (slash < 0) return void 0;
+			const segments = query.slice(0, slash).split("/").filter((segment) => segment !== "");
+			const crumbs = [{
+				label: t("crumb.root"),
+				value: directoryValue(t("crumb.root"), quoted ? "@\"" : "@")
+			}];
+			for (const [index, segment] of segments.entries()) {
+				const mention = formatFileMention({
+					path: segments.slice(0, index + 1).join("/"),
+					kind: "directory"
+				}, quoted);
+				if (mention === void 0) return void 0;
+				crumbs.push({
+					label: segment,
+					value: directoryValue(segment, mention),
+					...index === segments.length - 1 ? { current: true } : {}
+				});
+			}
+			return crumbs;
+		}
+		/** Project one directory destination as the drill payload `onPick` already understands. */
+		function directoryValue(label, mention) {
+			return JSON.stringify({
+				kind: "file",
+				fileKind: "directory",
+				label,
+				mention
+			});
+		}
+		function fileCandidate(candidate, preserveQuote, withLocation, t) {
+			const mention = formatFileMention(candidate, preserveQuote);
+			if (mention === void 0) return [];
+			const slash = candidate.path.lastIndexOf("/");
+			const name = candidate.path.slice(slash + 1);
+			const parent = slash < 0 ? "" : candidate.path.slice(0, slash);
+			const directory = candidate.kind === "directory";
+			const value = {
+				kind: "file",
+				fileKind: candidate.kind,
+				label: name,
+				mention
+			};
+			return [{
+				name: `${name}${directory ? "/" : ""}`,
+				...withLocation && parent !== "" ? { description: parent } : {},
+				icon: directory ? "folder" : "file",
+				section: t("section.files"),
+				value: JSON.stringify(value),
+				...directory ? { drill: true } : {}
+			}];
+		}
+		function sessionCandidate(candidate, updatedAt, now, home, t) {
+			const { unit, n } = (0, _prettier_ai_dsh_client_ui_primitives.relativeTime)(updatedAt, now);
+			const age = unit === "now" ? t("time.now") : t(`time.${unit}`, { n });
+			const location = candidate.sameWorkspace ? void 0 : candidate.cwd === void 0 ? t("candidate.noCwd") : abbreviateHomePath(candidate.cwd, home);
+			const value = {
+				kind: "session",
+				label: candidate.label,
+				mention: candidate.mention
+			};
+			return {
+				name: candidate.label,
+				description: location === void 0 ? age : `${location} · ${age}`,
+				icon: "session",
+				section: t("section.sessions"),
+				value: JSON.stringify(value)
+			};
+		}
+		function parseCandidate(value) {
+			if (value === void 0) return void 0;
+			return JSON.parse(value);
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,11 @@
+//#region lib/types/index.js
+/**
+* File/session reference plugin, 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.
+*/
+/** Host plugin body — no host-side behavior for this source plugin. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@prettier-ai/dsh-client-ui-reference`.
+* @module @prettier-ai/dsh-client-ui-reference/invariant
+*/
+const PACKAGE_NAME = "@prettier-ai/dsh-client-ui-reference";
+/** Cordis companion plugin name. */
+const name = "client-ui-reference-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: a single slash-source registration whose disposal is
+* proven by the HMR-safety spec — it emits no cordis events and owns no
+* cross-plugin mutable state.
+*/
+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/index.d.ts

@@ -0,0 +1,9 @@
+import type { Context as ClientContext } from '@prettier-ai/cordis';
+/** Required services: the trigger registry, the Remote namespaces, and the copy. */
+export declare const inject: string[];
+/**
+ * Register the combined `@file` / `@session` source.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,44 @@
+/** `reference` namespace dictionaries for the unified `@` source. */
+/** Dictionary namespace owned by this plugin. */
+export declare const NS = "reference";
+/**
+ * Simplified Chinese dictionary (the key-set source of truth).
+ *
+ * The `time.*` bucket words are this namespace's own copy of the session-row
+ * vocabulary: locale-owned copy keeps the words per plugin, while the
+ * bucketing they name is the one shared {@link relativeTime} in ui-primitives.
+ */
+export declare const zh: {
+    'section.files': string;
+    'section.sessions': string;
+    'candidate.noCwd': string;
+    'crumb.root': string;
+    'time.now': string;
+    'time.minutes': string;
+    'time.hours': string;
+    'time.days': string;
+    'time.months': string;
+    'time.years': string;
+};
+/** The reference namespace key union. */
+export type ReferenceKey = keyof typeof zh;
+declare module '@prettier-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The unified `@` reference menu's copy. */
+        reference: ReferenceKey;
+    }
+}
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'section.files': string;
+    'section.sessions': string;
+    'candidate.noCwd': string;
+    'crumb.root': string;
+    'time.now': string;
+    'time.minutes': string;
+    'time.hours': string;
+    'time.days': string;
+    'time.months': string;
+    'time.years': string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * File/session reference plugin, 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.
+ */
+/** Host plugin body — no host-side behavior for this source 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 `@prettier-ai/dsh-client-ui-reference`.
+ * @module @prettier-ai/dsh-client-ui-reference/invariant
+ */
+import type { Context } from '@prettier-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-ui-reference-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,83 @@
+{
+  "name": "@prettier-ai/dsh-client-ui-reference",
+  "description": "Unified Web @file and @session reference source",
+  "version": "0.1.2-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-reference"
+  },
+  "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": [
+        "@prettier-ai/dsh-api-remotes",
+        "@prettier-ai/dsh-api-session-controller",
+        "@prettier-ai/dsh-client-connection",
+        "@prettier-ai/dsh-client-locale",
+        "@prettier-ai/dsh-client-ui-input-trigger"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@prettier-ai/dsh-api-remotes": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-locale": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-input-trigger": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-connection": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-file-reference": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-api-session-controller": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-session-reference": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-typert-protocol": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-util-workspace-path": "^0.1.2-alpha.1",
+    "@prettier-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@prettier-ai/dsh-api-remotes": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-api-session-controller": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-connection": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-input-trigger": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-locale": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-primitives": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-slots": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-file-reference": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-typert-protocol": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-session-reference": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-util-workspace-path": "^0.1.2-alpha.1",
+    "@prettier-ai/cordis": "^4.0.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}