dsh-surface-bridge 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -51,7 +51,14 @@ export function apply(ctx: ClientContext): void {
 }
 ```
 
-`selection` 的形状见 [`src/contract.ts`](src/contract.ts) 的 `SurfaceSelection`：源只投影**元素行**（id / 类型 / 文本 / 坐标 / 尺寸 / 非默认样式 / 连接关系），桥拥有信封（revision、count、bounds、模型文本、可选图片）。
+面板侧还要接住"点击 transcript 里那条选区 chip"：桥把请求放进注册表，面板取走并选中元素。
+
+```ts
+const request = ctx.surfaceBridge.takeFocus('excalidraw', scene)   // 只取点名自己这张图的请求
+if (request !== null) selectAndScrollIntoView(request.elementIds)
+```
+
+`selection` 的形状见 [`src/contract.ts`](src/contract.ts) 的 `SurfaceSelection`：源只投影**元素行**（id / 类型 / 文本 / 坐标 / 尺寸 / 非默认样式 / 连接关系），桥拥有信封（revision、count、bounds、模型文本、可选图片）。文件类的面还可以给 `resource.display`（人读的名字，如 `main`）——桥不知道什么是扩展名，也不该知道。
 
 **图片不走文本。** 大载荷放进 `selection.images[]`，每条用 `elementId` 指向自己的元素；Host 把它们落成 durable 附件并以真正的 `image` 块追加到上下文。没有图片元素的选择，一个字节的图片都不产生。
 
@@ -72,21 +79,29 @@ const results = await ctx.surfaceBridgeHost.apply(sessionId, 'excalidraw',   //
 Host 半在 `agent/pre-step` 里做三件事，而且只在**带着新用户输入的那一步**做：
 
 1. 若该 Session 有面在轮询（`isSurfaceLive`），向浏览器**读一次**当前选择；
-2. 每个有选择的面，在消息末尾追加一条 `createUserMessage`（`source.kind = 'surface-selection'`，`form = 'snapshot'`）；
-3. 记下这个 turn 已经读过，**同一 turn 的后续 step 不再读**。
+2. 把选择**并进用户自己那条消息的最前面**：一个 `@"<显示名> · N 个元素"` mention（shell 把整个引号内容渲染成用户气泡里那个蓝色、带文件图标的引用 chip）；图片以真正的 `image` 块加进同一条消息；
+3. 追加一条隐藏的明细消息（`source.kind = 'surface-selection'`）装元素表，并记下这个 turn 已经读过，**同一 turn 的后续 step 不再读**。
+
+**为什么是一行、而且长在用户自己的气泡里。** Chat 视图对非 `user` 源的上下文节点**不渲染任何行**（`isVisibleChatNode` 把普通 Context 全部排除），所以可见的那一半必须是 `source.kind = 'user'` 的消息。而用户消息里行内有颜色的东西只有一种：`@…` 引用 chip，而且**它的显示文本就是 token 里的最后一段**——所以「文件 + 个数一起变蓝」只能把它们塞进同一个引号 token 里。于是选择以 mention 的形式并进用户那句话 —— 另起一条消息就会变成用户看到的"两行"。
 
 - **只在发送时读取**：用户画图期间什么都不发。这也让"发送时看到的选择"就是消息真正带上的选择。
 - **一个 turn 只读一次**：一个 turn 有多个 step（模型调用、工具结果、再调用），否则同一张图会被注入三遍。
 - **不可见的面答空**：读取的答案来自同一个注册表，而注册表只列"在屏幕上且有选择"的面，所以切会话/切标签后，旧选择既不会显示也不会被发送。
 - **无浏览器则跳过**：没有面在轮询（CLI、未打开过画布标签页）直接返回，不阻塞消息。
+- **没有用户消息可并时**（turn 由通知、定时唤醒或恢复的 goal 打开）：可见块另起一条 `user` 消息 —— 宁可多一行，也不能让选择只进模型、不进对话。
 - 形态与 `dsh-time-context`、`dsh-session-reference` 一致：都是官方认可的"生产者注入 user-role 上下文"路径。
 
-**在对话里长什么样（`form: 'notice'`）**：DSH 按消息源声明的 `form` 决定怎么渲染这条上下文，而**只有 `notice` 这一种 form 带 `summary`**，它的语义就是"不展开也要能读懂的一行"。所以选择集以一张带标题的卡片出现在对话里（`画布 · 2 个元素`），元素明细在展开里 —— 而不是一坨要滚过去的坐标文本。
+**点击那条 chip 之后。** chip 的文本是给人读的（`main · 3 个元素`），不是路径 —— 所以 shell 自己那个"打开这个文件"的动作在这里用不了（它会把整串当路径去 claim，然后抛错）。于是这次点击由桥的客户端半边**接管**：捕获阶段 `stopPropagation`，自己打开这张图的**文件地址**（和文件树同一个标签页），再把请求交给画布面板。识别、定位、打开都靠下面这张表：
 
-这不是自造 UI：卡片由 shell 自己渲染（shadcn/lucide 那套），本包只提供一行 summary。要注意的取舍是：
+| 需要的东西 | 来自哪里 |
+| --- | --- |
+| 哪条消息 | 行上的 `data-chat-node-key`（shell 自己滚动/锚点也用它）+ `data-conversation-session` |
+| 这是不是本包的 chip | chip 的 `title` 是否形如 `@"<名称> · N 个元素"` |
+| 这条消息带了哪个选择 | 隐藏明细消息的 `source`：`surface` / `message` / `document` / `elements` |
+| 打开哪个文件 | 同一条明细的 `source.path`（绝对路径）→ 按 shell 的语法组成 `dsh-resource://file/…`，与文件树点开同一个标签页 |
+| 谁来选中元素 | 该面自己的面板：`requestFocus` / `takeFocus`，请求一直留着直到面板接住（点击本身往往就是打开这个面板的动作） |
 
-- `notice` **不允许再带 `sections`**（那是 `snapshot` 的字段），两者互斥。
-- summary 是**持久化在消息里的显示文本**，因此和注入正文一样是中文、不随 locale 变。模型读到的东西完全没变 —— 换的只是这一行怎么显示。
+监听是捕获阶段、只读、从不 `preventDefault`；只对**本包自己的 label 形态**（`@"… · N 个元素"`）接管，别人手打的 `@path` 或助手消息里的文件引用照旧由 shell 打开。任何一步缺失（老 shell 没有那个属性、明细消息不在已加载窗口里、面已卸载）都只是这一次点击什么都不做，不会抛错、也不会误开别的文件。明细消息的 `source` 是簿记而非模型内容，因此不花一个 prompt token。
 
 ## 路由
 
@@ -119,6 +134,9 @@ chip、输入行占位、`agent/pre-step` 注入、图片附件化、长轮询
 - **读取靠"有面在轮询"判定。** 从未打开过画布标签页的会话读不到东西——这是对的，那张画布根本不在屏幕上。
 - **每个面各自轮询。** 多个面同时挂在一个会话上时，读取请求会被先轮询到的那个取走。当前只有一个面，此路径正确；接第二个面时应把轮询收归桥的客户端半边（按 `operation.source` 分派）。
 - **回写不做持久队列。** 操作队列是同一个进程里两半之间的交接通道，画布关掉即失去意义；因此工具失败要响，而不是排队等。
+- **点击定位依赖 shell 的 DOM 标识。** 行上的 `data-chat-node-key` / `data-conversation-session` 和 chip 上的 `data-ref-chip` 不是本包定义的接口，是 shell 自己导航时也在读的属性（它的 Esc 处理同样 `closest("[data-conversation-session]")`）。**升级 DSH 后要复验这三处**：`transcript-focus.test.mjs` 里有一条构建产物断言盯着它们。真要彻底不依赖，就得让 shell 提供自定义节点渲染器，那属于 DSH 侧改动。
+- **chip 的 label 形态是握手协议。** 宿主写 `@"<显示名> · N 个元素"`，客户端按同一条正则读回来；两边改动必须同时。写歪了不会误伤别人：识别不出来的 chip 交回 shell，只是点不动。
+- **一个面同时只能挂一个待处理定位请求。** 连点两次 chip 是"看后一次"，不排队；这符合"再点一次"的直觉，也避免旧请求在新画布上突然生效。
 
 ## 源码
 

package/lib/client.js

@@ -35,7 +35,7 @@ var SurfaceBridgeRegistry = class {
   revision = 0;
   /** @inheritdoc */
   registerSource(descriptor) {
-    this.entries.set(descriptor.id, { descriptor, selection: null, visible: false });
+    this.entries.set(descriptor.id, { descriptor, selection: null, visible: false, focus: null });
     this.bump();
     return () => {
       this.entries.delete(descriptor.id);
@@ -78,6 +78,23 @@ var SurfaceBridgeRegistry = class {
     });
   }
   /** @inheritdoc */
+  requestFocus(source, target) {
+    const entry = this.entries.get(source);
+    if (entry === void 0) return;
+    entry.focus = target;
+    this.bump();
+  }
+  /** @inheritdoc */
+  takeFocus(source, document2) {
+    const entry = this.entries.get(source);
+    const focus = entry?.focus ?? null;
+    if (entry === void 0 || focus === null) return null;
+    if (document2 !== void 0 && focus.document !== void 0 && focus.document !== document2) return null;
+    entry.focus = null;
+    this.bump();
+    return focus;
+  }
+  /** @inheritdoc */
   subscribe(listener) {
     this.listeners.add(listener);
     return () => {
@@ -271,6 +288,118 @@ function SurfaceSelectionChip({
   )) });
 }
 
+// src/client/transcript.ts
+var NODE_KEY_ATTRIBUTE = "data-chat-node-key";
+var SESSION_ATTRIBUTE = "data-conversation-session";
+var CHIP_ATTRIBUTE = "data-ref-chip";
+var SELECTION_SOURCE = "surface-selection";
+function documentOfMention(token) {
+  if (typeof token !== "string" || !token.startsWith("@")) return void 0;
+  const raw = token.slice(1);
+  const name = raw.length > 2 && raw.startsWith('"') && raw.endsWith('"') ? raw.slice(1, -1) : raw;
+  return name.length === 0 ? void 0 : name;
+}
+var SELECTION_LABEL = /^@"(.+?) · (\d+) 个元素"$/u;
+function selectionLabelOf(token) {
+  if (typeof token !== "string") return void 0;
+  const match = SELECTION_LABEL.exec(token);
+  const document2 = match?.[1];
+  return document2 === void 0 || document2.length === 0 ? void 0 : { document: document2 };
+}
+function selectionTargetOf(node, messageId, document2) {
+  if (node === void 0 || node.kind !== "context") return void 0;
+  const source = node.data?.source;
+  if (typeof source !== "object" || source === null) return void 0;
+  const fields = source;
+  if (fields.kind !== SELECTION_SOURCE) return void 0;
+  if (fields.message !== messageId) return void 0;
+  if (fields.document !== void 0 && fields.document !== document2) return void 0;
+  if (typeof fields.surface !== "string" || fields.surface.length === 0) return void 0;
+  if (!Array.isArray(fields.elements)) return void 0;
+  const elementIds = fields.elements.filter((id) => typeof id === "string" && id.length > 0);
+  if (elementIds.length === 0) return void 0;
+  return {
+    surface: fields.surface,
+    ...typeof fields.document === "string" ? { document: fields.document } : {},
+    ...typeof fields.path === "string" && fields.path.length > 0 ? { path: fields.path } : {},
+    elementIds
+  };
+}
+function targetForMessage(snapshot, messageId, document2) {
+  for (const node of snapshot.nodes.values()) {
+    const target = selectionTargetOf(node, messageId, document2);
+    if (target !== void 0) return target;
+  }
+  return void 0;
+}
+function snapshotOf(ctx, sessionId) {
+  const sessions = ctx.get("sessions");
+  const conversation = ctx.get("uiConversation");
+  if (sessions === void 0 || conversation === void 0) return void 0;
+  const binding = sessions.binding(sessionId);
+  if (binding === void 0 || binding === null) return void 0;
+  return conversation.binding(binding)?.target("chat").getSnapshot();
+}
+function encodeSegment(segment) {
+  return encodeURIComponent(segment).replace(/%3A/giu, ":");
+}
+function fileAddressOf(sessionId, cwd, path) {
+  const normalized = path.replace(/\\/gu, "/");
+  const root = cwd === void 0 ? "" : cwd.replace(/\\/gu, "/").replace(/\/+$/u, "");
+  const relative = root !== "" && normalized.startsWith(`${root}/`) ? normalized.slice(root.length + 1) : normalized;
+  const encoded = relative.split("/").map(encodeSegment).join("/");
+  return `dsh-resource://file/session/${encodeSegment(sessionId)}/${encoded}`;
+}
+function openDocument(ctx, sessionId, path) {
+  const sidebar = ctx.get("sidebarRight");
+  if (sidebar === void 0) return;
+  const sessions = ctx.get("sessions");
+  const cwd = sessions?.list.getSnapshot().byId[sessionId]?.cwd;
+  try {
+    sidebar.openResource(fileAddressOf(sessionId, cwd, path));
+  } catch {
+  }
+}
+function clickedChip(target) {
+  if (!(target instanceof Element)) return void 0;
+  const chip = target.closest(`[${CHIP_ATTRIBUTE}]`);
+  if (chip === null) return void 0;
+  const token = chip.getAttribute("title");
+  if (token === null || !token.startsWith("@")) return void 0;
+  const sessionId = chip.closest(`[${SESSION_ATTRIBUTE}]`)?.getAttribute(SESSION_ATTRIBUTE);
+  const nodeKey = chip.closest(`[${NODE_KEY_ATTRIBUTE}]`)?.getAttribute(NODE_KEY_ATTRIBUTE);
+  if (sessionId === null || sessionId === void 0 || nodeKey === null || nodeKey === void 0) return void 0;
+  return { token, sessionId, nodeKey };
+}
+function installTranscriptFocus(ctx, bridge) {
+  const onClick = (event) => {
+    const chip = clickedChip(event.target);
+    if (chip === void 0) return;
+    const label = selectionLabelOf(chip.token);
+    const document2 = label?.document ?? documentOfMention(chip.token);
+    if (document2 === void 0) return;
+    const snapshot = snapshotOf(ctx, chip.sessionId);
+    const messageId = snapshot?.nodes.get(chip.nodeKey)?.id;
+    const target = typeof messageId === "string" && snapshot !== void 0 ? targetForMessage(snapshot, messageId, document2) : void 0;
+    if (target === void 0) {
+      if (label !== void 0) event.stopPropagation();
+      return;
+    }
+    if (label !== void 0) {
+      event.stopPropagation();
+      if (target.path !== void 0) openDocument(ctx, chip.sessionId, target.path);
+    }
+    bridge.requestFocus(target.surface, {
+      ...target.document === void 0 ? {} : { document: target.document },
+      elementIds: target.elementIds
+    });
+  };
+  document.addEventListener("click", onClick, true);
+  return () => {
+    document.removeEventListener("click", onClick, true);
+  };
+}
+
 // src/client/locales.ts
 var NS = "surface-bridge";
 var zh = {
@@ -299,6 +428,7 @@ 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.effect(() => installTranscriptFocus(ctx, bridge), "dsh-surface-bridge: transcript focus");
   ctx.slots.inject("conversation.input.overlay", () => ctx.slots.register({
     name: "conversation.input.overlay",
     id: CHIP_ENTRY_ID,

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

@@ -1,11 +1,12 @@
 /**
  * Browser half of dsh-surface-bridge.
  *
- * Two things live here and nothing else: the `ctx.surfaceBridge` registry a
- * business surface publishes into, and the single `conversation.input.dock` entry
- * that renders every surface's selection. Keeping the chip in this bundle — rather
- * than letting each surface draw its own — is what makes the composer row stable
- * as more surfaces adopt the seam.
+ * Three things live here and nothing else: the `ctx.surfaceBridge` registry a
+ * business surface publishes into, the single `conversation.input.dock` entry
+ * that renders every surface's selection, and the listener that turns a click on a
+ * sent selection's reference chip back into a request for the surface. Keeping the
+ * chip in this bundle — rather than letting each surface draw its own — is what
+ * makes the composer row stable as more surfaces adopt the seam.
  *
  * @module dsh-surface-bridge/client
  */

package/lib/types/client/index.js

@@ -1,16 +1,18 @@
 /**
  * Browser half of dsh-surface-bridge.
  *
- * Two things live here and nothing else: the `ctx.surfaceBridge` registry a
- * business surface publishes into, and the single `conversation.input.dock` entry
- * that renders every surface's selection. Keeping the chip in this bundle — rather
- * than letting each surface draw its own — is what makes the composer row stable
- * as more surfaces adopt the seam.
+ * Three things live here and nothing else: the `ctx.surfaceBridge` registry a
+ * business surface publishes into, the single `conversation.input.dock` entry
+ * that renders every surface's selection, and the listener that turns a click on a
+ * sent selection's reference chip back into a request for the surface. Keeping the
+ * chip in this bundle — rather than letting each surface draw its own — is what
+ * makes the composer row stable as more surfaces adopt the seam.
  *
  * @module dsh-surface-bridge/client
  */
 import { SurfaceBridgeRegistry } from "./service.js";
 import { SurfaceSelectionChip } from "./SurfaceSelectionDock.js";
+import { installTranscriptFocus } from "./transcript.js";
 import { NS, en, zh } from "./locales.js";
 /** The slot registry, the locale registry, and the composer's overlay slot declaration. */
 export const inject = ['slots', 'locale'];
@@ -31,6 +33,10 @@ export 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');
+    // The chip in the composer is one half of the round trip; this is the other. A selection
+    // leaves the composer when it is sent, so the only thing left to click is the reference in
+    // the message — and the elements it named can only be selected by the surface's own panel.
+    ctx.effect(() => installTranscriptFocus(ctx, bridge), 'dsh-surface-bridge: transcript focus');
     ctx.slots.inject('conversation.input.overlay', () => ctx.slots.register({
         name: 'conversation.input.overlay',
         id: CHIP_ENTRY_ID,

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

@@ -15,7 +15,7 @@
  *
  * @module dsh-surface-bridge/client/service
  */
-import type { SurfaceBridgeService, SurfaceSelection, SurfaceSourceDescriptor } from '../contract.ts';
+import type { SurfaceBridgeService, SurfaceFocusTarget, SurfaceSelection, SurfaceSourceDescriptor } from '../contract.ts';
 export type { SurfaceBridgeService, SurfaceIconProps, SurfaceSourceDescriptor } from '../contract.ts';
 /** Default implementation of the bridge's browser-side registry. */
 export declare class SurfaceBridgeRegistry implements SurfaceBridgeService {
@@ -38,6 +38,10 @@ export declare class SurfaceBridgeRegistry implements SurfaceBridgeService {
         selection: SurfaceSelection;
     }[];
     /** @inheritdoc */
+    requestFocus(source: string, target: SurfaceFocusTarget): void;
+    /** @inheritdoc */
+    takeFocus(source: string, document?: string): SurfaceFocusTarget | null;
+    /** @inheritdoc */
     subscribe(listener: () => void): () => void;
     /** @inheritdoc */
     version(): number;

package/lib/types/client/service.js

@@ -22,7 +22,7 @@ export class SurfaceBridgeRegistry {
     revision = 0;
     /** @inheritdoc */
     registerSource(descriptor) {
-        this.entries.set(descriptor.id, { descriptor, selection: null, visible: false });
+        this.entries.set(descriptor.id, { descriptor, selection: null, visible: false, focus: null });
         this.bump();
         return () => {
             this.entries.delete(descriptor.id);
@@ -72,6 +72,28 @@ export class SurfaceBridgeRegistry {
         });
     }
     /** @inheritdoc */
+    requestFocus(source, target) {
+        const entry = this.entries.get(source);
+        if (entry === undefined)
+            return;
+        entry.focus = target;
+        this.bump();
+    }
+    /** @inheritdoc */
+    takeFocus(source, document) {
+        const entry = this.entries.get(source);
+        const focus = entry?.focus ?? null;
+        if (entry === undefined || focus === null)
+            return null;
+        // A request for another document stays put: the panel that can honour it is the one
+        // that is a view of that document, and taking it here would lose it silently.
+        if (document !== undefined && focus.document !== undefined && focus.document !== document)
+            return null;
+        entry.focus = null;
+        this.bump();
+        return focus;
+    }
+    /** @inheritdoc */
     subscribe(listener) {
         this.listeners.add(listener);
         return () => { this.listeners.delete(listener); };

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

@@ -0,0 +1,130 @@
+/**
+ * The way back from a sent selection to the surface that produced it.
+ *
+ * A selection leaves the composer when it is sent, and the chip that carried it disappears
+ * with it. What stays is the reference in the message: the bridge appends the document as an
+ * `@document` mention, and the shell draws that as a blue, clickable chip inside the person's
+ * own bubble. Clicking it opens the document — that much the shell does on its own — but the
+ * shell knows nothing about *elements*, and the person clicked a chip that says "1 个元素".
+ *
+ * So the click is observed here. The row the chip sits in carries the identity the shell
+ * itself navigates by — `data-conversation-session` and `data-chat-node-key`, the same
+ * attributes the shell's own escape-key handler reads — and the hidden detail message the
+ * bridge wrote carries the rest (see the `MessageSourceMap` augmentation in the package
+ * entry). Together they name the surface and the elements, and the request goes back through
+ * the bridge to the surface's own panel, which is the only part that can select and scroll.
+ *
+ * Every step is best-effort and read-only. The click is never intercepted or prevented: if
+ * any of this is missing — an older shell without the attribute, a message whose detail row
+ * is outside the loaded window, a surface that is no longer registered — the click still does
+ * what the shell's own action does, which is open the document.
+ *
+ * @module dsh-surface-bridge/client/transcript
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { SurfaceBridgeService } from '../contract.ts';
+/**
+ * Decode the document name out of a reference chip's token.
+ *
+ * The token is what the bridge wrote — `@main.excalidraw`, or `@"画布 2.excalidraw"` when the
+ * name carries whitespace, because the shell's own mention rule ends an unquoted token at the
+ * first space. The chip's `title` keeps the token verbatim, which is what makes it the honest
+ * thing to compare against the detail row's document.
+ *
+ * @param token - The chip's `title`, or anything else.
+ * @returns the document name, or `undefined` when this is not a document reference.
+ */
+export declare function documentOfMention(token: string | null | undefined): string | undefined;
+/**
+ * Read the bridge's own chip label off a token.
+ *
+ * @param token - The chip's `title`, or anything else.
+ * @returns the document the label names, or `undefined` for any other token.
+ */
+export declare function selectionLabelOf(token: string | null | undefined): {
+    readonly document: string;
+} | undefined;
+/** The parts of a Chat node this module reads. */
+interface ChatNodeLike {
+    readonly id?: unknown;
+    readonly kind?: unknown;
+    readonly data?: {
+        readonly source?: unknown;
+    };
+}
+/** The parts of a Chat snapshot this module reads. */
+interface ChatSnapshotLike {
+    readonly nodes: {
+        get(key: string): ChatNodeLike | undefined;
+        values(): readonly ChatNodeLike[];
+    };
+}
+/** One selection a click can bring back: which surface, which elements. */
+export interface SelectionTarget {
+    /** Surface that published the selection, as its id in the bridge registry. */
+    readonly surface: string;
+    /** What the chip reads for the document, when the detail row named one. */
+    readonly document?: string;
+    /** Absolute path of the document, when the surface knew it: what the click opens. */
+    readonly path?: string;
+    /** Elements to select and bring into view. */
+    readonly elementIds: readonly string[];
+}
+/**
+ * Read what one Chat node says about the selection that rode with a message.
+ *
+ * The node is the bridge's own hidden detail row, matched by the message it names — the
+ * message id, not the row's position, because a transcript that was reloaded, compacted or
+ * re-ordered still keeps the pairing. The document is checked too: a click on a chip must
+ * never select elements in a different drawing that happens to be open.
+ *
+ * @param node - A Chat node, of any kind.
+ * @param messageId - Message the click came from.
+ * @param document - Document the clicked chip names.
+ * @returns the surface and elements, or `undefined` when this node is not that selection.
+ */
+export declare function selectionTargetOf(node: ChatNodeLike | undefined, messageId: string, document: string): SelectionTarget | undefined;
+/**
+ * Find the selection one clicked message carried.
+ *
+ * @param snapshot - Chat snapshot of the Session the click happened in.
+ * @param messageId - Message the clicked row belongs to.
+ * @param document - Document the clicked chip names.
+ * @returns the target, or `undefined` when the message carried no selection of that document.
+ */
+export declare function targetForMessage(snapshot: ChatSnapshotLike, messageId: string, document: string): SelectionTarget | undefined;
+/**
+ * The `dsh-resource://file/…` address of one path, as the shell's own file links build it.
+ *
+ * The point of matching the shell exactly is that this opens *the same tab* the file tree opens
+ * for that file, rather than a second one for the same drawing. A path inside the Session's
+ * workspace becomes the workspace-relative address; anything else keeps its absolute spelling,
+ * which is also what the shell does.
+ *
+ * @param sessionId - Session whose workspace resolves the path.
+ * @param cwd - That Session's workspace root, when known.
+ * @param path - Absolute path of the document.
+ * @returns the file address.
+ */
+export declare function fileAddressOf(sessionId: string, cwd: string | undefined, path: string): string;
+/**
+ * Watch the transcript for clicks on a selection's reference chip.
+ *
+ * A capture-phase listener, and for the bridge's own chip form it is the *whole* handler: that
+ * chip's label is written for a person to read (`main · 2 个元素`), not a path the shell could
+ * open, so the click is taken over here — propagation stops, the document is opened at the
+ * address the file tree uses, and the surface is asked to select the elements again. A plain
+ * file mention (what older messages carry, and what anyone types by hand) is left alone: the
+ * shell opens it as it always did, and this only adds the element request.
+ *
+ * Every step is best-effort: a missing Session, a message whose detail row is outside the
+ * loaded window, a surface that has been unloaded — each one ends the handler without touching
+ * the event, except that the bridge's own label is always stopped, because the shell would
+ * refuse it and an uncaught refusal is worse than a click that does nothing.
+ *
+ * @param ctx - Client context, read lazily for the Session, Conversation and Sidebar services.
+ * @param bridge - The bridge the request lands in.
+ * @returns the disposer that removes the listener.
+ */
+export declare function installTranscriptFocus(ctx: ClientContext, bridge: SurfaceBridgeService): () => void;
+export {};