dsh-surface-bridge 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NoneFire
+
+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.md

@@ -0,0 +1,132 @@
+# dsh-surface-bridge
+
+DSH 右侧栏的**业务面**（画布、表格、Notebook）与 **DSH 输入栏**之间的唯一接缝：一条 chip、一处上下文注入点、一条回写通道。
+
+```
+┌─────────────┐  publish(selection)  ┌────────────────────────┐
+│ 业务插件    │ ───────────────────► │ dsh-surface-bridge     │
+│ (画布/表格) │ ◄─────────────────── │  · 输入行上的 chip      │
+└─────────────┘   同一个长轮询        │  · 注册表（仅本地）      │
+        ▲                             └───────────┬────────────┘
+        │  read：现在选了什么？                     │ agent/pre-step
+        └──────────────────────────────────────────┘
+                                                 ▼
+                                        user/message（上下文）
+```
+
+**关键：选择是"被读"的，不是"被推"的。** 用户画图、框选时**没有任何网络流量**；只有当一条消息要发出去、模型步骤开始准备时才向浏览器要一次。`publish` 是纯本地动作（驱动 chip + 作为那次读取的答案），不碰网络。
+
+## 为什么它必须是一个**已挂载的 bundle**，而不是 `packages/` 里的纯库
+
+这是本包存在的全部理由。设想把联动逻辑写成一个库，让每个业务插件 `import`：
+
+| 方案 | 结果 |
+| --- | --- |
+| 每个插件各写一套 chip + 注入 | 输入栏里 N 个 chip 抢位置；同一套 Host 注入被复制 N 次；视觉与行为各自漂移 |
+| 联动逻辑做成纯库，各插件 import | 看起来更轻，但库会被**分别打进每个插件自己的 client bundle**。于是 `ctx` 上出现 N 份服务实例，各自注册一个 `conversation.input.dock` 条目 —— chip 依然是 N 个。**纯库无法保证"全局唯一"** |
+| 联动逻辑做成独立 bundle（本包） | 唯一实例由 DSH 的 Loader 保证；业务插件只 `inject` 服务 + `registerSource(...)` |
+
+因此本仓库对 `packages/` 与 `plugins/` 的分工是明确的：
+
+- `packages/`：**无状态、可被任意打包**的纯代码（`ui`、`data-contracts`、`convert-core`）。
+- `plugins/`：需要在 `ctx` 上**提供唯一服务**、参与 profile 组合的**运行单元**。
+
+## 给业务插件用的 API
+
+### 浏览器侧：`ctx.surfaceBridge`
+
+```ts
+export const inject = ['surfaceBridge', 'locale'] as const
+
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.surfaceBridge.registerSource({
+    id: 'excalidraw',
+    label: '画布',
+    icon: IconEditOutlineRegular,
+    order: 10,
+    reveal: () => { ctx.sidebarRight.openTab('data-excalidraw') },   // chip 上的「定位」
+    focusElement: (id) => { canvas.focusElement(id) },               // 点摘要某一行
+  }), 'my-surface: source')
+
+  // 用户选择变化时：
+  ctx.surfaceBridge.publish('excalidraw', selectionOrNull)
+}
+```
+
+`selection` 的形状见 [`src/contract.ts`](src/contract.ts) 的 `SurfaceSelection`：源只投影**元素行**（id / 类型 / 文本 / 坐标 / 尺寸 / 非默认样式 / 连接关系），桥拥有信封（revision、count、bounds、模型文本、可选图片）。
+
+**图片不走文本。** 大载荷放进 `selection.images[]`，每条用 `elementId` 指向自己的元素；Host 把它们落成 durable 附件并以真正的 `image` 块追加到上下文。没有图片元素的选择，一个字节的图片都不产生。
+
+### Host 侧：`ctx.surfaceBridgeHost`
+
+```ts
+const live = ctx.surfaceBridgeHost.isSurfaceLive(sessionId)                  // 画布是否开着
+const all = await ctx.surfaceBridgeHost.readSelections(sessionId, signal)    // 现在选了什么
+const one = await ctx.surfaceBridgeHost.readSelection(sessionId, 'excalidraw', signal)
+const results = await ctx.surfaceBridgeHost.apply(sessionId, 'excalidraw',   // 回写并等结果
+  [{ op: 'update', payload: { id, fields } }], exec.signal)
+```
+
+`apply` 在**画布未打开**或**超时未回传**时返回明确的失败结果，绝不假装成功。
+
+## 上下文是怎么进模型的
+
+Host 半在 `agent/pre-step` 里做三件事，而且只在**带着新用户输入的那一步**做：
+
+1. 若该 Session 有面在轮询（`isSurfaceLive`），向浏览器**读一次**当前选择；
+2. 每个有选择的面，在消息末尾追加一条 `createUserMessage`（`source.kind = 'surface-selection'`，`form = 'snapshot'`）；
+3. 记下这个 turn 已经读过，**同一 turn 的后续 step 不再读**。
+
+- **只在发送时读取**：用户画图期间什么都不发。这也让"发送时看到的选择"就是消息真正带上的选择。
+- **一个 turn 只读一次**：一个 turn 有多个 step（模型调用、工具结果、再调用），否则同一张图会被注入三遍。
+- **不可见的面答空**：读取的答案来自同一个注册表，而注册表只列"在屏幕上且有选择"的面，所以切会话/切标签后，旧选择既不会显示也不会被发送。
+- **无浏览器则跳过**：没有面在轮询（CLI、未打开过画布标签页）直接返回，不阻塞消息。
+- 形态与 `dsh-time-context`、`dsh-session-reference` 一致：都是官方认可的"生产者注入 user-role 上下文"路径。
+
+**在对话里长什么样（`form: 'notice'`）**：DSH 按消息源声明的 `form` 决定怎么渲染这条上下文，而**只有 `notice` 这一种 form 带 `summary`**，它的语义就是"不展开也要能读懂的一行"。所以选择集以一张带标题的卡片出现在对话里（`画布 · 2 个元素`），元素明细在展开里 —— 而不是一坨要滚过去的坐标文本。
+
+这不是自造 UI：卡片由 shell 自己渲染（shadcn/lucide 那套），本包只提供一行 summary。要注意的取舍是：
+
+- `notice` **不允许再带 `sections`**（那是 `snapshot` 的字段），两者互斥；`tests/context-augmentation.test.mjs` 钉住了这条，避免有人顺手加回去。
+- summary 是**持久化在消息里的显示文本**，因此和注入正文一样是中文、不随 locale 变。模型读到的东西完全没变 —— 换的只是这一行怎么显示。
+
+## 路由
+
+全部挂在平台共享 API 通道（`ctx.connection.fetch.register`）上，因此继承平台的信任与鉴权围栏，不另开 webserver：
+
+只有两条路由，服务于**一个双向长轮询**：
+
+| 路由 | 方向 | 用途 |
+| --- | --- | --- |
+| `GET /api/data-canvas/ops?sessionId=&hold=` | 浏览器 ← Host | 长轮询（最长 20s）：取待执行操作，**以及 Host 的读取请求** |
+| `POST /api/data-canvas/settle` | 浏览器 → Host | 回传执行结果，或回传一次读取的答案 |
+
+读取复用了同一条队列（`READ_SELECTION_OP`，不带 source —— 只有浏览器知道有哪些面、哪些在屏幕上），所以浏览器不需要第二个监听器，一次读取就是一个已经parked 的连接上的往返。路径常量在 `src/contract.ts` 里只写一遍。
+
+校验没有消失，只是换了一端：旧设计要在 ingest 端校验推送来的选择，现在改为在**读取答案**上校验（`src/host/narrow.ts`）——浏览器仍然是边界，只是方向反了。
+
+## 扩展一个新业务面
+
+1. 建一个 `plugins/dsh-data-*` bundle，`dsh.client.inject` 里加上 `dsh-surface-bridge`（Loader 会保证桥先注册）。
+2. `inject: ['surfaceBridge', ...]`，`registerSource` 一个描述符，并在可见性变化时 `setVisible`。
+3. 用户选择变化时把投影好的 `SurfaceSelection` `publish` 到注册表（本地）。
+4. 自己的操作循环里把 `READ_SELECTION_OP` 答成 `[selection]` 或 `[]`。
+5. Host 侧工具通过 `ctx.surfaceBridgeHost` 读选择、送操作。
+
+chip、输入行占位、`agent/pre-step` 注入、图片附件化、长轮询回写全部由本包负责。
+
+## 已知边界
+
+- **读取窗口是 600ms。** 一次读取最多等这么久就拿不到答案（消息照发，只是不带选择）。本地环回上是毫秒级；设短是为了不为了上下文而拖延用户的消息。
+- **读取靠"有面在轮询"判定。** 从未打开过画布标签页的会话读不到东西——这是对的，那张画布根本不在屏幕上。
+- **每个面各自轮询。** 多个面同时挂在一个会话上时，读取请求会被先轮询到的那个取走。当前只有一个面，此路径正确；接第二个面时应把轮询收归桥的客户端半边（按 `operation.source` 分派）。
+- **回写不做持久队列。** 操作队列是同一个进程里两半之间的交接通道，画布关掉即失去意义；因此工具失败要响，而不是排队等。
+
+## 构建与测试
+
+```bash
+pnpm build   # tsc（Host 半 + 类型）+ esbuild（唯一 client.js）
+pnpm test    # lib/types 上的 Node 规格：状态机、渲染、边界校验、打包形状守卫
+```
+
+`tests/context-augmentation.test.mjs` 里有一条**必须保留的守卫**：cordis 的 `Context` augmentation 只能写在包入口模块。放进 `contract.ts` 之类的共享类型模块时，同一段 `declare module` 会退化成*环境声明*并**替换**掉 cordis 的 `Context`，导致整张图里的 `ctx.effect` / `ctx.on` 全部不再类型检查。该用例会在它被"顺手整理"走时失败。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-surface-bridge bundle patch: mount the shared surface↔composer seam.
+#
+# One plugin instance provides `ctx.surfaceBridge` (browser) and
+# `ctx.surfaceBridgeHost` (Host), and registers the single
+# `conversation.input.dock` entry every business surface's selection renders
+# through. Business plugins depend on it; they never re-implement the chip.
+- insert:
+    - id: dsh-surface-bridge
+      name: 'dsh-surface-bridge'

package/lib/client.js

@@ -0,0 +1,310 @@
+window.__ModuleLoader__.load({ id: "dsh-surface-bridge", factory: (require) => {
+var module = { exports: {} }; var exports = module.exports;
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.ts
+var index_exports = {};
+__export(index_exports, {
+  apply: () => apply,
+  inject: () => inject
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client/service.ts
+var SurfaceBridgeRegistry = class {
+  entries = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  revision = 0;
+  /** @inheritdoc */
+  registerSource(descriptor) {
+    this.entries.set(descriptor.id, { descriptor, selection: null, visible: false });
+    this.bump();
+    return () => {
+      this.entries.delete(descriptor.id);
+      this.bump();
+    };
+  }
+  /** @inheritdoc */
+  setVisible(source, visible) {
+    const entry = this.entries.get(source);
+    if (entry === void 0 || entry.visible === visible) return;
+    entry.visible = visible;
+    this.bump();
+  }
+  /** @inheritdoc */
+  isVisible(source) {
+    return this.entries.get(source)?.visible === true;
+  }
+  /** @inheritdoc */
+  publish(source, selection) {
+    const entry = this.entries.get(source);
+    if (entry === void 0) return;
+    entry.selection = selection;
+    this.bump();
+  }
+  /** @inheritdoc */
+  read(source) {
+    return this.entries.get(source)?.selection ?? null;
+  }
+  /** @inheritdoc */
+  active() {
+    const out = [];
+    for (const entry of this.entries.values()) {
+      if (entry.selection === null || !entry.visible) continue;
+      out.push({ descriptor: entry.descriptor, selection: entry.selection });
+    }
+    return out.sort((left, right) => {
+      const order = (left.descriptor.order ?? 0) - (right.descriptor.order ?? 0);
+      if (order !== 0) return order;
+      return left.descriptor.id < right.descriptor.id ? -1 : left.descriptor.id > right.descriptor.id ? 1 : 0;
+    });
+  }
+  /** @inheritdoc */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /** @inheritdoc */
+  version() {
+    return this.revision;
+  }
+  /** Advance the version and notify every subscriber. */
+  bump() {
+    this.revision += 1;
+    for (const listener of [...this.listeners]) listener();
+  }
+};
+
+// src/client/SurfaceSelectionDock.tsx
+var import_react = require("react");
+var import_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+
+// surface-bridge-css:/Users/fuzz/Documents/github/dsh-personal/plugins/dsh-surface-bridge/src/client/SurfaceSelectionDock.module.css
+var css = "[data-composer-card]:has([data-surface-chip]) [data-input-scroll]{text-indent:var(--surface-bridge-indent,0px)}.peUXVa_anchor{z-index:2;pointer-events:none;align-items:center;gap:6px;width:max-content;max-width:calc(100% - 26px);display:flex;position:absolute;top:13px;left:14px}.peUXVa_chip{border:.5px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-interactive-bg-hover);min-width:0;max-width:100%;height:22px;color:var(--dsw-alias-label-secondary);white-space:nowrap;cursor:pointer;pointer-events:auto;border-radius:999px;align-items:center;gap:6px;padding:0 8px 0 7px;font-family:inherit;font-size:12px;line-height:16px;display:inline-flex}.peUXVa_chip:hover{border-color:var(--dsw-alias-border-l4);color:var(--dsw-alias-label-primary)}.peUXVa_chip:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:1px}.peUXVa_glyph{color:currentColor;opacity:.75;flex:none;display:inline-flex}.peUXVa_label{flex:none;font-weight:500}.peUXVa_dot{color:var(--dsw-alias-label-caption);flex:none}.peUXVa_count{min-width:0;color:var(--dsw-alias-state-business-primary);font-variant-numeric:tabular-nums;text-overflow:ellipsis;overflow:hidden}.peUXVa_chevron{color:var(--dsw-alias-label-caption);flex:none;display:inline-flex}.peUXVa_clear{width:18px;height:18px;color:var(--dsw-alias-label-caption);cursor:pointer;pointer-events:auto;background:0 0;border:0;border-radius:999px;flex:none;justify-content:center;align-items:center;margin-left:-3px;padding:0;display:inline-flex}.peUXVa_clear:hover{background:var(--dsw-alias-interactive-bg-hover);color:var(--dsw-alias-label-primary)}.peUXVa_clear:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:1px}.peUXVa_row{align-items:baseline;gap:8px;min-width:0;display:flex}.peUXVa_rowType{color:var(--dsw-alias-label-caption);flex:none;font-size:11px;line-height:16px}.peUXVa_rowLabel{min-width:0;color:var(--dsw-alias-label-primary);text-overflow:ellipsis;white-space:nowrap;overflow:hidden}.peUXVa_rowGeom{color:var(--dsw-alias-label-caption);font-family:var(--font-tita-mono);flex:none;margin-left:auto;font-size:11px;line-height:16px}.peUXVa_more{color:var(--dsw-alias-label-caption);font-size:11px;line-height:16px}";
+var tagId = "dsh-surface-bridge//Users/fuzz/Documents/github/dsh-personal/plugins/dsh-surface-bridge/src/client/SurfaceSelectionDock.module.css";
+if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
+  const tag = document.createElement("style");
+  tag.dataset.plugin = "dsh-surface-bridge";
+  tag.dataset.pluginCss = tagId;
+  tag.textContent = css;
+  document.head.appendChild(tag);
+}
+var SurfaceSelectionDock_default = { "anchor": "peUXVa_anchor", "chevron": "peUXVa_chevron", "chip": "peUXVa_chip", "clear": "peUXVa_clear", "count": "peUXVa_count", "dot": "peUXVa_dot", "glyph": "peUXVa_glyph", "label": "peUXVa_label", "more": "peUXVa_more", "row": "peUXVa_row", "rowGeom": "peUXVa_rowGeom", "rowLabel": "peUXVa_rowLabel", "rowType": "peUXVa_rowType" };
+
+// src/client/SurfaceSelectionDock.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var MAX_SUMMARY_ROWS = 24;
+var ELEMENT_PREFIX = "element:";
+var ACTION_REVEAL = "action:reveal";
+var ACTION_CLEAR = "action:clear";
+function elementRowLabel(selection, index) {
+  const element = selection.elements[index];
+  if (element === void 0) return null;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { className: SurfaceSelectionDock_default.row, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: SurfaceSelectionDock_default.rowType, children: element.type }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: SurfaceSelectionDock_default.rowLabel, children: element.label.length > 0 ? element.label : element.id }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: SurfaceSelectionDock_default.rowGeom, children: `${Math.round(element.width)}\xD7${Math.round(element.height)}` })
+  ] });
+}
+function SurfaceChip({
+  bridge,
+  descriptor,
+  selection,
+  t
+}) {
+  const [open, setOpen] = (0, import_react.useState)(false);
+  const Glyph = descriptor.icon ?? import_dsh_client_ui_primitives.IconEditOutlineRegular;
+  const shown = selection.elements.slice(0, MAX_SUMMARY_ROWS);
+  const rows = [
+    { id: "note:title", label: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: SurfaceSelectionDock_default.more, children: String(t("menu.title", { count: selection.count })) }), disabled: true }
+  ];
+  for (const [index] of shown.entries()) {
+    const element = selection.elements[index];
+    if (element === void 0) continue;
+    rows.push({ id: `${ELEMENT_PREFIX}${element.id}`, label: elementRowLabel(selection, index) });
+  }
+  if (shown.length === 0) {
+    rows.push({ id: "element:none", label: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: SurfaceSelectionDock_default.more, children: String(t("menu.empty")) }), disabled: true });
+  } else if (selection.elements.length > shown.length) {
+    rows.push({
+      id: "element:more",
+      label: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: SurfaceSelectionDock_default.more, children: String(t("menu.more", { count: selection.count - shown.length })) }),
+      disabled: true
+    });
+  }
+  const footer = [];
+  if (descriptor.reveal !== void 0) {
+    footer.push({ id: ACTION_REVEAL, label: String(t("action.reveal")), icon: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_dsh_client_ui_primitives.IconFullscreenOutlineRegular, { size: 14 }) });
+  }
+  footer.push({ id: ACTION_CLEAR, label: String(t("action.clear")), danger: true });
+  const clear = () => {
+    bridge.publish(descriptor.id, null);
+    setOpen(false);
+  };
+  const onSelect = (id) => {
+    if (id === ACTION_REVEAL) {
+      descriptor.reveal?.();
+      setOpen(false);
+      return;
+    }
+    if (id === ACTION_CLEAR) {
+      clear();
+      return;
+    }
+    if (!id.startsWith(ELEMENT_PREFIX)) return;
+    const elementId = id.slice(ELEMENT_PREFIX.length);
+    if (elementId === "more" || elementId === "none") return;
+    descriptor.reveal?.();
+    descriptor.focusElement?.(elementId);
+    setOpen(false);
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      import_dsh_client_ui_primitives.Menu,
+      {
+        open,
+        anchor: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+          "button",
+          {
+            type: "button",
+            className: SurfaceSelectionDock_default.chip,
+            "data-surface-chip": "",
+            "aria-label": String(t("chip.aria", { count: selection.count })),
+            "aria-expanded": open,
+            onClick: () => {
+              setOpen((value) => !value);
+            },
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: SurfaceSelectionDock_default.glyph, "aria-hidden": "true", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Glyph, { size: 12 }) }),
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: SurfaceSelectionDock_default.label, children: descriptor.label }),
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: SurfaceSelectionDock_default.dot, "aria-hidden": "true", children: "\xB7" }),
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: SurfaceSelectionDock_default.count, children: String(t("chip.count", { count: selection.count })) }),
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: SurfaceSelectionDock_default.chevron, "aria-hidden": "true", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_dsh_client_ui_primitives.IconChevronDownOutlineRegular, { size: 12 }) })
+            ]
+          }
+        ),
+        items: rows,
+        footer,
+        onSelect,
+        onClose: () => {
+          setOpen(false);
+        },
+        side: "bottom",
+        align: "start",
+        portal: true
+      }
+    ),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "button",
+      {
+        type: "button",
+        className: SurfaceSelectionDock_default.clear,
+        "aria-label": String(t("action.clear")),
+        onClick: clear,
+        children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_dsh_client_ui_primitives.IconCloseOutlineRegular, { size: 12 })
+      }
+    )
+  ] });
+}
+function SurfaceSelectionChip({
+  bridge,
+  t
+}) {
+  (0, import_react.useSyncExternalStore)(
+    (listener) => bridge.subscribe(listener),
+    () => bridge.version(),
+    () => bridge.version()
+  );
+  const active = bridge.active();
+  const anchorRef = (0, import_react.useRef)(null);
+  (0, import_react.useLayoutEffect)(() => {
+    const anchor = anchorRef.current;
+    if (anchor === null) return;
+    const card = anchor.closest("[data-composer-card]");
+    if (card === null) return;
+    const apply2 = () => {
+      const width = anchor.getBoundingClientRect().width;
+      if (width <= 0) return;
+      card.style.setProperty("--surface-bridge-indent", `${Math.round(width) + 8}px`);
+    };
+    apply2();
+    if (typeof ResizeObserver === "undefined") return () => {
+      card.style.removeProperty("--surface-bridge-indent");
+    };
+    const observer = new ResizeObserver(apply2);
+    observer.observe(anchor);
+    return () => {
+      observer.disconnect();
+      card.style.removeProperty("--surface-bridge-indent");
+    };
+  }, [active.length]);
+  if (active.length === 0) return null;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: SurfaceSelectionDock_default.anchor, "data-surface-bridge": "", ref: anchorRef, children: active.map(({ descriptor, selection }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    SurfaceChip,
+    {
+      bridge,
+      descriptor,
+      selection,
+      t
+    },
+    descriptor.id
+  )) });
+}
+
+// src/client/locales.ts
+var NS = "surface-bridge";
+var zh = {
+  "chip.aria": "\u5DF2\u9009\u62E9 {count} \u4E2A\u5143\u7D20\uFF0C\u5C55\u5F00\u67E5\u770B",
+  "chip.count": "{count} \u4E2A\u5143\u7D20",
+  "menu.title": "\u5DF2\u9009\u62E9 {count} \u4E2A\u5143\u7D20",
+  "menu.empty": "\uFF08\u6CA1\u6709\u5143\u7D20\u660E\u7EC6\uFF09",
+  "menu.more": "\u8FD8\u6709 {count} \u4E2A\u5143\u7D20\u672A\u5217\u51FA",
+  "action.reveal": "\u5B9A\u4F4D\u5230\u753B\u5E03",
+  "action.clear": "\u6E05\u7A7A\u9009\u62E9"
+};
+var en = {
+  "chip.aria": "{count} elements selected, expand for details",
+  "chip.count": "{count} elements",
+  "menu.title": "{count} elements selected",
+  "menu.empty": "(no element details)",
+  "menu.more": "{count} more elements not listed",
+  "action.reveal": "Reveal surface",
+  "action.clear": "Clear selection"
+};
+
+// src/client/index.ts
+var inject = ["slots", "locale"];
+var CHIP_ENTRY_ID = "surface-bridge";
+function apply(ctx) {
+  const bridge = new SurfaceBridgeRegistry();
+  ctx.effect(() => ctx.reflect.provide("surfaceBridge", bridge), "dsh-surface-bridge: client registry");
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), "dsh-surface-bridge: dictionaries");
+  ctx.slots.inject("conversation.input.overlay", () => ctx.slots.register({
+    name: "conversation.input.overlay",
+    id: CHIP_ENTRY_ID,
+    order: 5,
+    locale: NS,
+    inject: () => ({ bridge })
+  }, SurfaceSelectionChip));
+}
+return module.exports; } });

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

@@ -0,0 +1,37 @@
+/**
+ * The one composer chip for every surface selection.
+ *
+ * Exactly one entry is registered into `conversation.input.overlay`, and it renders
+ * one capsule per source that currently has a selection. That is the whole reason the
+ * bridge is a mounted bundle: with the registry inlined per consumer, two surfaces
+ * would each register their own entry and the composer would grow a second chip with
+ * a different shape.
+ *
+ * Why the overlay seat and not the dock seat it used to occupy: the dock renders
+ * *above* the composer card, in the same stack as the to-do dock — so anything there
+ * shares the task list's form and reflows the whole input every time it appears. The
+ * overlay seat is inside the card, on the shell's own top-edge anchor, which is where
+ * the stylesheet puts the capsule on the input line itself.
+ *
+ * The chip is a pure view of local state. Nothing here talks to the Host: the
+ * selection is read from this registry when a model step asks for it, which is why
+ * the chip has no syncing, pending, or failed states to twitch between.
+ *
+ * @module dsh-surface-bridge/client/SurfaceSelectionDock
+ */
+import type { ReactNode } from 'react';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SurfaceBridgeService } from './service.ts';
+import { NS } from './locales.ts';
+/** Injected face of the chip entry. */
+export interface SurfaceDockInjected {
+    readonly bridge: SurfaceBridgeService;
+}
+/**
+ * The chip entry: one capsule per surface that has a selection and is on screen.
+ *
+ * Hiding is not done here — a source that goes off screen (a tab switch, a Session
+ * switch, a collapsed column) drops out of the registry's `active`, which both hides
+ * the capsule and removes it from the answer a read gets.
+ */
+export declare function SurfaceSelectionChip({ bridge, t, }: PropsRuntime<'conversation.input.overlay'> & InjectFace<SurfaceDockInjected> & PropsLocale<typeof NS>): ReactNode;

package/lib/types/client/SurfaceSelectionDock.js

@@ -0,0 +1,125 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { IconChevronDownOutlineRegular, IconCloseOutlineRegular, IconEditOutlineRegular, IconFullscreenOutlineRegular, Menu, } from '@deepseek-ai/dsh-client-ui-primitives';
+import styles from './SurfaceSelectionDock.module.css';
+/** Maximum element rows the summary menu lists. */
+const MAX_SUMMARY_ROWS = 24;
+/** Menu row id prefixes, so one `onSelect` can tell element rows from actions. */
+const ELEMENT_PREFIX = 'element:';
+const ACTION_REVEAL = 'action:reveal';
+const ACTION_CLEAR = 'action:clear';
+/** One element's row label: kind, name, and size in a single scannable line. */
+function elementRowLabel(selection, index) {
+    const element = selection.elements[index];
+    if (element === undefined)
+        return null;
+    return (_jsxs("span", { className: styles.row, children: [_jsx("span", { className: styles.rowType, children: element.type }), _jsx("span", { className: styles.rowLabel, children: element.label.length > 0 ? element.label : element.id }), _jsx("span", { className: styles.rowGeom, children: `${Math.round(element.width)}×${Math.round(element.height)}` })] }));
+}
+/** One capsule: a single source's selection and its summary menu. */
+function SurfaceChip({ bridge, descriptor, selection, t, }) {
+    const [open, setOpen] = useState(false);
+    const Glyph = descriptor.icon ?? IconEditOutlineRegular;
+    const shown = selection.elements.slice(0, MAX_SUMMARY_ROWS);
+    const rows = [
+        { id: 'note:title', label: _jsx("span", { className: styles.more, children: String(t('menu.title', { count: selection.count })) }), disabled: true },
+    ];
+    for (const [index] of shown.entries()) {
+        const element = selection.elements[index];
+        if (element === undefined)
+            continue;
+        rows.push({ id: `${ELEMENT_PREFIX}${element.id}`, label: elementRowLabel(selection, index) });
+    }
+    if (shown.length === 0) {
+        rows.push({ id: 'element:none', label: _jsx("span", { className: styles.more, children: String(t('menu.empty')) }), disabled: true });
+    }
+    else if (selection.elements.length > shown.length) {
+        rows.push({
+            id: 'element:more',
+            label: _jsx("span", { className: styles.more, children: String(t('menu.more', { count: selection.count - shown.length })) }),
+            disabled: true,
+        });
+    }
+    const footer = [];
+    if (descriptor.reveal !== undefined) {
+        footer.push({ id: ACTION_REVEAL, label: String(t('action.reveal')), icon: _jsx(IconFullscreenOutlineRegular, { size: 14 }) });
+    }
+    footer.push({ id: ACTION_CLEAR, label: String(t('action.clear')), danger: true });
+    const clear = () => {
+        // Local only: the surface keeps its own canvas selection, and the next change to
+        // it republishes. Clearing here means "do not carry this into the message".
+        bridge.publish(descriptor.id, null);
+        setOpen(false);
+    };
+    const onSelect = (id) => {
+        if (id === ACTION_REVEAL) {
+            descriptor.reveal?.();
+            setOpen(false);
+            return;
+        }
+        if (id === ACTION_CLEAR) {
+            clear();
+            return;
+        }
+        if (!id.startsWith(ELEMENT_PREFIX))
+            return;
+        const elementId = id.slice(ELEMENT_PREFIX.length);
+        if (elementId === 'more' || elementId === 'none')
+            return;
+        descriptor.reveal?.();
+        descriptor.focusElement?.(elementId);
+        setOpen(false);
+    };
+    return (_jsxs(_Fragment, { children: [_jsx(Menu, { open: open, anchor: (_jsxs("button", { type: "button", className: styles.chip, "data-surface-chip": "", "aria-label": String(t('chip.aria', { count: selection.count })), "aria-expanded": open, onClick: () => { setOpen(value => !value); }, children: [_jsx("span", { className: styles.glyph, "aria-hidden": "true", children: _jsx(Glyph, { size: 12 }) }), _jsx("span", { className: styles.label, children: descriptor.label }), _jsx("span", { className: styles.dot, "aria-hidden": "true", children: "\u00B7" }), _jsx("span", { className: styles.count, children: String(t('chip.count', { count: selection.count })) }), _jsx("span", { className: styles.chevron, "aria-hidden": "true", children: _jsx(IconChevronDownOutlineRegular, { size: 12 }) })] })), items: rows, footer: footer, onSelect: onSelect, onClose: () => { setOpen(false); }, side: "bottom", align: "start", portal: true }), _jsx("button", { type: "button", className: styles.clear, "aria-label": String(t('action.clear')), onClick: clear, children: _jsx(IconCloseOutlineRegular, { size: 12 }) })] }));
+}
+/**
+ * The chip entry: one capsule per surface that has a selection and is on screen.
+ *
+ * Hiding is not done here — a source that goes off screen (a tab switch, a Session
+ * switch, a collapsed column) drops out of the registry's `active`, which both hides
+ * the capsule and removes it from the answer a read gets.
+ */
+export function SurfaceSelectionChip({ bridge, t, }) {
+    useSyncExternalStore(listener => bridge.subscribe(listener), () => bridge.version(), () => bridge.version());
+    const active = bridge.active();
+    const anchorRef = useRef(null);
+    /*
+     * Tell the card how far to move its input line, so the text starts after the
+     * capsule instead of under it.
+     *
+     * This is the one place the bridge writes to the shell's DOM, and it is deliberate:
+     * the composer's scroll container is the only element that can move its own text,
+     * and the distance depends on the capsule's rendered width — which depends on the
+     * locale and the digit count, so a constant in the stylesheet would be wrong in at
+     * least one language. One scoped custom property, set while a chip is mounted and
+     * removed when it is not.
+     */
+    useLayoutEffect(() => {
+        const anchor = anchorRef.current;
+        if (anchor === null)
+            return;
+        // `closest` is not generic over attribute selectors, so the cast is the element
+        // the shell documents with that attribute.
+        const card = anchor.closest('[data-composer-card]');
+        if (card === null)
+            return;
+        const apply = () => {
+            const width = anchor.getBoundingClientRect().width;
+            if (width <= 0)
+                return;
+            // 8px of air between the capsule and the first character.
+            card.style.setProperty('--surface-bridge-indent', `${Math.round(width) + 8}px`);
+        };
+        apply();
+        if (typeof ResizeObserver === 'undefined')
+            return () => { card.style.removeProperty('--surface-bridge-indent'); };
+        const observer = new ResizeObserver(apply);
+        observer.observe(anchor);
+        return () => {
+            observer.disconnect();
+            card.style.removeProperty('--surface-bridge-indent');
+        };
+    }, [active.length]);
+    if (active.length === 0)
+        return null;
+    return (_jsx("div", { className: styles.anchor, "data-surface-bridge": "", ref: anchorRef, children: active.map(({ descriptor, selection }) => (_jsx(SurfaceChip, { bridge: bridge, descriptor: descriptor, selection: selection, t: t }, descriptor.id))) }));
+}