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

package/README.md

@@ -26,10 +26,8 @@ DSH 右侧栏的**业务面**（画布、表格、Notebook）与 **DSH 输入栏
 | 联动逻辑做成纯库，各插件 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 组合的**运行单元**。
+因此本包是一个**独立 bundle**，而不是一个给各插件 `import` 的库：唯一实例由 DSH 的
+Loader 保证，业务插件只 `inject` 服务 + `registerSource(...)`。
 
 ## 给业务插件用的 API
 
@@ -87,7 +85,7 @@ Host 半在 `agent/pre-step` 里做三件事，而且只在**带着新用户输
 
 这不是自造 UI：卡片由 shell 自己渲染（shadcn/lucide 那套），本包只提供一行 summary。要注意的取舍是：
 
-- `notice` **不允许再带 `sections`**（那是 `snapshot` 的字段），两者互斥；`tests/context-augmentation.test.mjs` 钉住了这条，避免有人顺手加回去。
+- `notice` **不允许再带 `sections`**（那是 `snapshot` 的字段），两者互斥。
 - summary 是**持久化在消息里的显示文本**，因此和注入正文一样是中文、不随 locale 变。模型读到的东西完全没变 —— 换的只是这一行怎么显示。
 
 ## 路由
@@ -107,7 +105,7 @@ Host 半在 `agent/pre-step` 里做三件事，而且只在**带着新用户输
 
 ## 扩展一个新业务面
 
-1. 建一个 `plugins/dsh-data-*` bundle，`dsh.client.inject` 里加上 `dsh-surface-bridge`（Loader 会保证桥先注册）。
+1. 建一个带 `dsh.client` 的 bundle，`dsh.client.inject` 里加上 `dsh-surface-bridge`（Loader 会保证桥先注册）。
 2. `inject: ['surfaceBridge', ...]`，`registerSource` 一个描述符，并在可见性变化时 `setVisible`。
 3. 用户选择变化时把投影好的 `SurfaceSelection` `publish` 到注册表（本地）。
 4. 自己的操作循环里把 `READ_SELECTION_OP` 答成 `[selection]` 或 `[]`。
@@ -122,11 +120,11 @@ chip、输入行占位、`agent/pre-step` 注入、图片附件化、长轮询
 - **每个面各自轮询。** 多个面同时挂在一个会话上时，读取请求会被先轮询到的那个取走。当前只有一个面，此路径正确；接第二个面时应把轮询收归桥的客户端半边（按 `operation.source` 分派）。
 - **回写不做持久队列。** 操作队列是同一个进程里两半之间的交接通道，画布关掉即失去意义；因此工具失败要响，而不是排队等。
 
-## 构建与测试
+## 源码
+
+发布的包里带 `src/`。构建是两个 half 一起出：
 
 ```bash
 pnpm build   # tsc（Host 半 + 类型）+ esbuild（唯一 client.js）
-pnpm test    # lib/types 上的 Node 规格：状态机、渲染、边界校验、打包形状守卫
+pnpm test
 ```
-
-`tests/context-augmentation.test.mjs` 里有一条**必须保留的守卫**：cordis 的 `Context` augmentation 只能写在包入口模块。放进 `contract.ts` 之类的共享类型模块时，同一段 `declare module` 会退化成*环境声明*并**替换**掉 cordis 的 `Context`，导致整张图里的 `ctx.effect` / `ctx.on` 全部不再类型检查。该用例会在它被"顺手整理"走时失败。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-surface-bridge",
   "description": "Shared seam between a right-Sidebar business surface and the DSH composer: one selection chip, one Host-context injection point, one write-back channel",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/src/client/service.ts

@@ -18,6 +18,7 @@
 
 import type {
   SurfaceBridgeService,
+  SurfaceFocusTarget,
   SurfaceSelection,
   SurfaceSourceDescriptor,
 } from '../contract.ts'
@@ -30,6 +31,8 @@ interface SourceEntry {
   selection: SurfaceSelection | null
   /** Whether the surface is on screen for the current Session; see {@link SurfaceBridgeService.setVisible}. */
   visible: boolean
+  /** A selection the transcript asked to see again, until the surface's view takes it. */
+  focus: SurfaceFocusTarget | null
 }
 
 /** Default implementation of the bridge's browser-side registry. */
@@ -40,7 +43,7 @@ export class SurfaceBridgeRegistry implements SurfaceBridgeService {
 
   /** @inheritdoc */
   registerSource(descriptor: SurfaceSourceDescriptor): () => void {
-    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)
@@ -91,6 +94,27 @@ export class SurfaceBridgeRegistry implements SurfaceBridgeService {
     })
   }
 
+  /** @inheritdoc */
+  requestFocus(source: string, target: SurfaceFocusTarget): void {
+    const entry = this.entries.get(source)
+    if (entry === undefined) return
+    entry.focus = target
+    this.bump()
+  }
+
+  /** @inheritdoc */
+  takeFocus(source: string, document?: string): SurfaceFocusTarget | null {
+    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: () => void): () => void {
     this.listeners.add(listener)

package/src/contract.ts

@@ -252,6 +252,22 @@ export interface SurfaceSourceDescriptor {
   readonly focusElement?: (elementId: string) => void
 }
 
+/**
+ * One selection a person asked to see again.
+ *
+ * A message keeps the selection that rode with it, so the line in the transcript stays
+ * clickable long after the composer chip is gone. The transcript cannot select anything
+ * itself — that row belongs to the shell, and the one action its renderer offers is
+ * "open this file" — so the click lands here and the bridge hands the request to the
+ * surface's own view, which is the only part that knows how to select and scroll.
+ */
+export interface SurfaceFocusTarget {
+  /** Document the selection came from, when the surface is a view of a file. */
+  readonly document?: string
+  /** Elements to select and bring into view, in selection order. */
+  readonly elementIds: readonly string[]
+}
+
 /**
  * The `ctx.surfaceBridge` face a business surface publishes into.
  *
@@ -279,6 +295,25 @@ export interface SurfaceBridgeService {
   read(source: string): SurfaceSelection | null
   /** Read every source that currently has a selection, in chip order. */
   active(): readonly { descriptor: SurfaceSourceDescriptor; selection: SurfaceSelection }[]
+  /**
+   * Ask a surface's own view to show a selection again.
+   *
+   * Held until the view takes it: the request arrives from a click in the transcript,
+   * and the panel that answers it may not be mounted yet (the click itself is what
+   * opens it) or may still be loading the document. One pending request per source —
+   * a second click replaces the first, which is what a person means by clicking again.
+   */
+  requestFocus(source: string, target: SurfaceFocusTarget): void
+  /**
+   * Take the pending request for one source, clearing it.
+   *
+   * @param source - Surface whose request is taken.
+   * @param document - Document the caller is a view of. A request naming another
+   *   document is left in place for the view that can honour it, so two open panels
+   *   do not steal each other's request.
+   * @returns the request, or `null` when there is none for this caller.
+   */
+  takeFocus(source: string, document?: string): SurfaceFocusTarget | null
   /** Subscribe to any change (selection, sync state, roster). */
   subscribe(listener: () => void): () => void
   /** Snapshot version, for `useSyncExternalStore`. */

package/src/host/render.ts

@@ -73,108 +73,50 @@ export function renderElementRow(element: SurfaceElement): string {
 }
 
 /** How many element names the visible summary line carries before it degrades to `等`. */
-export const MAX_CHIP_NAMES = 3
-
-/** How long one element name may be on the visible summary line. */
-const MAX_CHIP_NAME_CHARS = 18
-
 /**
- * Width budget for the visible line, in half-width units.
+ * Render one document name as a reference the shell knows how to decorate.
  *
- * A user bubble is about 493px of usable width at the shell's 14px content font (max-width is
- * `min(748px * .702, 82%)` minus 16px of padding each side), and a CJK glyph there is roughly
- * 7px per unit of this measure — so ~70 units fit. The budget is set below that on purpose:
- * the estimate is a proxy, and the failure mode it buys insurance against is the line wrapping
- * to a second row, which is exactly what the request was about.
- */
-export const MAX_CHIP_LINE_UNITS = 56
-
-/** Approximate width of one string in half-width units: CJK counts double. */
-function widthUnits(text: string): number {
-  let total = 0
-  for (const char of text) total += (char.codePointAt(0) ?? 0) > 0x2e80 ? 2 : 1
-  return total
-}
-
-/** Width budget for the document name on the visible line, in half-width units. */
-export const MAX_CHIP_FILE_UNITS = 24
-
-/**
- * Shorten a document name for the visible line, keeping its extension.
+ * The transcript's own renderer projects a sent user message and turns an `@name` token into
+ * a blue, clickable reference chip — the only inline, clickable thing it draws inside a
+ * person's own bubble, and it comes with an icon and an "open this file" action for free.
+ * Writing the document that way is therefore what makes the selection part of the message
+ * the person actually sent, on its own line, instead of a second row under it.
  *
- * A 40-character file name would fill the line on its own and push the count onto a second row
- * — and the count is the part the reader is checking. The extension stays visible because it is
- * the part that says what kind of thing this is; the full name is one row down, in the detail.
+ * A name with whitespace has to be quoted: the shell's token rule ends an unquoted mention
+ * at the first space, and scene names really do contain spaces (`画布 2.excalidraw`).
  *
- * @param name - Document name.
- * @returns the name, or a shortened form ending in `…<extension>`.
+ * @param name - Document name, e.g. `main.excalidraw`.
+ * @returns the mention, e.g. `@main.excalidraw` or `@"画布 2.excalidraw"`.
  */
-function shortFileName(name: string): string {
-  if (widthUnits(name) <= MAX_CHIP_FILE_UNITS) return name
-  const dot = name.lastIndexOf('.')
-  const extension = dot > 0 ? name.slice(dot) : ''
-  const stem = dot > 0 ? name.slice(0, dot) : name
-  const room = MAX_CHIP_FILE_UNITS - widthUnits(extension) - 1
-  if (room <= 0) return `${name.slice(0, MAX_CHIP_FILE_UNITS - 1)}…`
-  let kept = ''
-  for (const char of stem) {
-    if (widthUnits(kept + char) > room) break
-    kept += char
-  }
-  // A separator left dangling before the ellipsis reads as a typo: `a-very-long-…` rather than
-  // `a-very-long…`.
-  kept = kept.replace(/[-_ .]+$/, '')
-  return `${kept}…${extension}`
+export function mentionOf(name: string): string {
+  return /[\s"]/.test(name) ? `@"${name}"` : `@${name}`
 }
 
 /**
- * Render the one line the person reads in the transcript.
+ * Render the inline summary appended to the person's own message.
  *
  * The element table stays in the hidden detail row, because a bubble of coordinates is not
  * something a person wants in their conversation. What they do want is to recognise what they
- * sent: the document, how many elements, and — when they fit — the first few names.
+ * sent — which document, how many elements — and to be able to get back to it.
  *
- * **One line, by construction.** The line carries the document and the count, then as many
- * names as the width budget allows; a name that would push it onto a second row is dropped
- * rather than wrapped. A selection of unlabelled shapes (the common case for a drawing someone
- * just made) therefore reads exactly `画布选区 · main.excalidraw · 1 个元素`.
+ * **No line of its own, by construction.** The text is a suffix, and its leading space is part
+ * of the form: the shell's mention rule requires whitespace (or the start of the text) before
+ * `@`, so a suffix glued to the end of a sentence would render as plain text.
  *
  * @param selection - Selection to summarise.
- * @returns one line, e.g. `画布选区 · main.excalidraw · 2 个元素：下单、风控`.
+ * @returns the suffix, e.g. ` @main.excalidraw · 2 个元素`.
  */
-export function renderSelectionChip(selection: SurfaceSelection): string {
-  const parts = [`${selection.title}选区`]
-  if (selection.resource?.name !== undefined) parts.push(shortFileName(selection.resource.name))
-  parts.push(`${selection.count} 个元素`)
-  const head = parts.join(' · ')
-  const names = (selection.elements ?? [])
-    .map(element => element.text ?? element.label)
-    .filter((name): name is string => typeof name === 'string' && name.length > 0)
-    .slice(0, MAX_CHIP_NAMES)
-    .map(name => (name.length > MAX_CHIP_NAME_CHARS ? `${name.slice(0, MAX_CHIP_NAME_CHARS)}…` : name))
-  if (names.length === 0) return head
-
-  // Greedy fit: add names while the whole line stays inside the budget. `等` is charged up
-  // front when there are more names than the list holds, so the suffix never overflows either.
-  const room = MAX_CHIP_LINE_UNITS - widthUnits(head) - 2
-  const fits: string[] = []
-  let used = 0
-  for (const name of names) {
-    const cost = widthUnits(name) + (fits.length === 0 ? 0 : 2)
-    if (used + cost > room) break
-    fits.push(name)
-    used += cost
-  }
-  if (fits.length === 0) return head
-  const suffix = selection.count > fits.length ? ' 等' : ''
-  return `${head}：${fits.join('、')}${suffix}`
+export function renderSelectionInline(selection: SurfaceSelection): string {
+  const name = selection.resource?.name
+  const head = name === undefined || name.length === 0 ? `${selection.title}选区` : mentionOf(name)
+  return ` ${head} · ${selection.count} 个元素`
 }
 
 /**
  * Render one selection as the text that enters the model step.
  *
  * This is the hidden detail row: every actionable fact, and nothing written for a person to
- * read — the visible line is {@link renderSelectionChip}. The two are deliberately different
+ * read — the person's line is {@link renderSelectionInline}. The two are deliberately different
  * texts rather than one text shown twice.
  *
  * @param selection - Selection to render.