dsh-surface-bridge 0.1.0-alpha.1

package/src/host/narrow.ts

@@ -0,0 +1,180 @@
+/**
+ * Host-side validation of a selection that came back from a browser.
+ *
+ * The surface is the only producer of a selection, but it is still a browser
+ * boundary: a read answer is narrowed here before anything reads it, so a broken
+ * or hostile page cannot hand the renderer a shape it does not expect. Nothing is
+ * stored — this runs on the answer to a read, once per model step.
+ *
+ * @module dsh-surface-bridge/host/narrow
+ */
+
+import type { SurfaceElement, SurfaceRaster, SurfaceResource, SurfaceSelection } from '../contract.ts'
+
+/** Cap on the selection raster the browser may attach, in base64 characters (~450 KiB of PNG). */
+export const MAX_RASTER_BASE64 = 600_000
+/** Cap on elements accepted per selection; the source should already cap lower. */
+export const MAX_ELEMENTS = 200
+/** Cap on attached images per selection. */
+export const MAX_IMAGES = 8
+
+/** Narrow a finite number, or `undefined`. */
+function finiteOrUndefined(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+/** Narrow a style bag to short string/number entries. */
+function narrowStyle(value: unknown): Readonly<Record<string, string | number>> | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  const out: Record<string, string | number> = {}
+  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof entry === 'string' || typeof entry === 'number') out[key] = entry
+  }
+  return Object.keys(out).length === 0 ? undefined : out
+}
+
+/** Narrow an asset locator bag. */
+function narrowAsset(value: unknown): Readonly<Record<string, string>> | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  const out: Record<string, string> = {}
+  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof entry === 'string') out[key] = entry
+  }
+  return Object.keys(out).length === 0 ? undefined : out
+}
+
+/** Narrow a string array. */
+function narrowStringArray(value: unknown): readonly string[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const out = value.filter((entry): entry is string => typeof entry === 'string')
+  return out.length === 0 ? undefined : out
+}
+
+/** Narrow one element projection; `undefined` rejects the whole selection. */
+function narrowElement(value: unknown): SurfaceElement | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  const raw = value as Record<string, unknown>
+  const id = typeof raw.id === 'string' && raw.id.length > 0 ? raw.id : undefined
+  const type = typeof raw.type === 'string' && raw.type.length > 0 ? raw.type : undefined
+  if (id === undefined || type === undefined) return undefined
+  const x = finiteOrUndefined(raw.x)
+  const y = finiteOrUndefined(raw.y)
+  const width = finiteOrUndefined(raw.width)
+  const height = finiteOrUndefined(raw.height)
+  if (x === undefined || y === undefined || width === undefined || height === undefined) return undefined
+  const linksRaw = raw.links
+  let links: SurfaceElement['links']
+  if (typeof linksRaw === 'object' && linksRaw !== null && !Array.isArray(linksRaw)) {
+    const bag = linksRaw as Record<string, unknown>
+    links = {
+      ...(typeof bag.from === 'string' ? { from: bag.from } : {}),
+      ...(typeof bag.to === 'string' ? { to: bag.to } : {}),
+      ...(typeof bag.container === 'string' ? { container: bag.container } : {}),
+      ...(narrowStringArray(bag.bound) === undefined ? {} : { bound: narrowStringArray(bag.bound) as readonly string[] }),
+    }
+    if (Object.keys(links).length === 0) links = undefined
+  }
+  return {
+    id,
+    type,
+    label: typeof raw.label === 'string' ? raw.label : type,
+    ...(typeof raw.text === 'string' ? { text: raw.text } : {}),
+    x,
+    y,
+    width,
+    height,
+    ...(finiteOrUndefined(raw.angle) === undefined ? {} : { angle: finiteOrUndefined(raw.angle) as number }),
+    ...(narrowStyle(raw.style) === undefined ? {} : { style: narrowStyle(raw.style) as Readonly<Record<string, string | number>> }),
+    ...(narrowAsset(raw.asset) === undefined ? {} : { asset: narrowAsset(raw.asset) as Readonly<Record<string, string>> }),
+    ...(links === undefined ? {} : { links }),
+  }
+}
+
+/** Narrow one raster; an oversized or malformed raster is dropped, never the selection. */
+function narrowRaster(value: unknown): SurfaceRaster | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  const raw = value as Record<string, unknown>
+  if (raw.mediaType !== 'image/png' && raw.mediaType !== 'image/jpeg' && raw.mediaType !== 'image/webp' && raw.mediaType !== 'image/gif') return undefined
+  if (typeof raw.data !== 'string' || raw.data.length === 0) return undefined
+  if (raw.data.length > MAX_RASTER_BASE64) return undefined
+  return {
+    mediaType: 'image/png',
+    data: raw.data,
+    ...(typeof raw.name === 'string' ? { name: raw.name } : {}),
+    ...(typeof raw.elementId === 'string' ? { elementId: raw.elementId } : {}),
+  }
+}
+
+/** Narrow the attached image list, keeping only well-formed members. */
+function narrowImages(value: unknown): readonly SurfaceRaster[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const out: SurfaceRaster[] = []
+  for (const entry of value.slice(0, MAX_IMAGES)) {
+    const image = narrowRaster(entry)
+    if (image !== undefined) out.push(image)
+  }
+  return out.length === 0 ? undefined : out
+}
+
+/** Narrow the document a selection came from; a malformed locator is dropped, not the selection. */
+function narrowResource(value: unknown): SurfaceResource | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  const raw = value as Record<string, unknown>
+  const resource: { path?: string; name?: string; version?: number } = {}
+  if (typeof raw.path === 'string' && raw.path.length > 0) resource.path = raw.path
+  if (typeof raw.name === 'string' && raw.name.length > 0) resource.name = raw.name
+  const version = finiteOrUndefined(raw.version)
+  if (version !== undefined) resource.version = version
+  return Object.keys(resource).length === 0 ? undefined : resource
+}
+
+/** Narrow one published selection, or explain what is wrong with it. */
+export function narrowSelection(value: unknown): { ok: true; selection: SurfaceSelection } | { ok: false; error: string } {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return { ok: false, error: 'selection 必须是对象' }
+  const raw = value as Record<string, unknown>
+  const source = typeof raw.source === 'string' && raw.source.length > 0 ? raw.source : undefined
+  if (source === undefined) return { ok: false, error: 'selection.source 必填' }
+  const revision = finiteOrUndefined(raw.revision)
+  if (revision === undefined || !Number.isSafeInteger(revision) || revision < 0) {
+    return { ok: false, error: 'selection.revision 必须是非负安全整数' }
+  }
+  const count = finiteOrUndefined(raw.count)
+  if (count === undefined || !Number.isSafeInteger(count) || count < 0) {
+    return { ok: false, error: 'selection.count 必须是非负安全整数' }
+  }
+  if (!Array.isArray(raw.elements)) return { ok: false, error: 'selection.elements 必须是数组' }
+  if (raw.elements.length > MAX_ELEMENTS) return { ok: false, error: `selection.elements 超过上限 ${MAX_ELEMENTS}` }
+  const elements: SurfaceElement[] = []
+  for (const entry of raw.elements) {
+    const element = narrowElement(entry)
+    if (element === undefined) return { ok: false, error: 'selection.elements 存在缺字段的元素' }
+    elements.push(element)
+  }
+  const boundsRaw = raw.bounds
+  let bounds: SurfaceSelection['bounds']
+  if (typeof boundsRaw === 'object' && boundsRaw !== null && !Array.isArray(boundsRaw)) {
+    const bag = boundsRaw as Record<string, unknown>
+    const x = finiteOrUndefined(bag.x)
+    const y = finiteOrUndefined(bag.y)
+    const width = finiteOrUndefined(bag.width)
+    const height = finiteOrUndefined(bag.height)
+    if (x !== undefined && y !== undefined && width !== undefined && height !== undefined) bounds = { x, y, width, height }
+  }
+  return {
+    ok: true,
+    selection: {
+      source,
+      revision,
+      count,
+      title: typeof raw.title === 'string' && raw.title.length > 0 ? raw.title : source,
+      summary: typeof raw.summary === 'string' ? raw.summary : `${count} 个元素`,
+      elements,
+      ...(raw.truncated === true ? { truncated: true } : {}),
+      ...(narrowResource(raw.resource) === undefined ? {} : { resource: narrowResource(raw.resource) as SurfaceResource }),
+      ...(bounds === undefined ? {} : { bounds }),
+      ...(narrowImages(raw.images) === undefined ? {} : { images: narrowImages(raw.images) as readonly SurfaceRaster[] }),
+      ...(narrowStringArray(raw.notes) === undefined ? {} : { notes: narrowStringArray(raw.notes) as readonly string[] }),
+      ...(narrowStringArray(raw.capabilities) === undefined ? {} : { capabilities: narrowStringArray(raw.capabilities) as readonly string[] }),
+    },
+  }
+}

package/src/host/render.ts

@@ -0,0 +1,226 @@
+/**
+ * Model-facing rendering of one selection.
+ *
+ * The text is the whole point of the bridge, so it is written for a reader that
+ * has never seen the surface: a one-line header naming the surface and the
+ * selection, the field semantics it needs to interpret the rows, one row per
+ * element, then the selection bounds and the operations it may issue.
+ *
+ * Token discipline is deliberate. Rows carry only facts a model can act on —
+ * identity, kind, text, geometry, non-default style, relations — and every value
+ * is rounded, because `x=120.00000000000001` costs the same as `x=120` and tells
+ * the model nothing. Heavy payloads never appear here: an image element reports
+ * its asset handle and its bytes travel beside this text as a real image block.
+ *
+ * @module dsh-surface-bridge/host/render
+ */
+
+import type { SurfaceElement, SurfaceSelection } from '../contract.ts'
+
+/** Maximum element rows rendered before the text degrades to a count. */
+export const MAX_RENDERED_ELEMENTS = 40
+
+/** Round a coordinate to one decimal; the precision a diagram actually needs. */
+function round(value: number): number {
+  if (!Number.isFinite(value)) return 0
+  return Math.round(value * 10) / 10
+}
+
+/** Render one style bag as `key=value` pairs, sorted for a stable prompt. */
+function renderStyle(style: Readonly<Record<string, string | number>> | undefined): string {
+  if (style === undefined) return ''
+  const entries = Object.entries(style)
+  if (entries.length === 0) return ''
+  const rendered = entries
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+    .map(([key, value]) => `${key}=${typeof value === 'number' ? round(value) : value}`)
+  return ` style{${rendered.join(',')}}`
+}
+
+/** Render one asset locator bag, sorted for a stable prompt. */
+function renderAsset(asset: Readonly<Record<string, string>> | undefined): string {
+  if (asset === undefined) return ''
+  const entries = Object.entries(asset)
+  if (entries.length === 0) return ''
+  const rendered = entries
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+    .map(([key, value]) => `${key}=${value}`)
+  return ` asset{${rendered.join(',')}}`
+}
+
+/** Render one element's connection relations. */
+function renderLinks(element: SurfaceElement): string {
+  const links = element.links
+  if (links === undefined) return ''
+  const parts: string[] = []
+  if (links.from !== undefined) parts.push(`from=${links.from}`)
+  if (links.to !== undefined) parts.push(`to=${links.to}`)
+  if (links.container !== undefined) parts.push(`container=${links.container}`)
+  if (links.bound !== undefined && links.bound.length > 0) parts.push(`bound=${links.bound.join('|')}`)
+  if (parts.length === 0) return ''
+  return ` links{${parts.join(',')}}`
+}
+
+/** Render one element row. */
+export function renderElementRow(element: SurfaceElement): string {
+  const text = element.text === undefined || element.text.length === 0
+    ? ''
+    : ` text=${JSON.stringify(element.text)}`
+  const angle = element.angle === undefined || round(element.angle) === 0 ? '' : ` angle=${round(element.angle)}`
+  return `- ${element.type} id=${element.id}${text} @(${round(element.x)},${round(element.y)}) `
+    + `${round(element.width)}x${round(element.height)}${angle}`
+    + `${renderStyle(element.style)}${renderAsset(element.asset)}${renderLinks(element)}`
+}
+
+/** 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @param name - Document name.
+ * @returns the name, or a shortened form ending in `…<extension>`.
+ */
+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}`
+}
+
+/**
+ * Render the one line the person reads in the transcript.
+ *
+ * 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.
+ *
+ * **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 个元素`.
+ *
+ * @param selection - Selection to summarise.
+ * @returns one line, 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}`
+}
+
+/**
+ * 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
+ * texts rather than one text shown twice.
+ *
+ * @param selection - Selection to render.
+ * @param selectionRef - Short stable handle for this selection, echoed by the tools.
+ * @returns the model-facing context text.
+ */
+export function renderSelectionText(selection: SurfaceSelection, selectionRef: string): string {
+  const shown = selection.elements.slice(0, MAX_RENDERED_ELEMENTS)
+  const lines: string[] = []
+  lines.push(
+    `[${selection.title} 选择集 ${selectionRef}] ${selection.summary}`
+    + `（共 ${selection.count} 个元素${selection.truncated === true || shown.length < selection.count ? `，下列只列出前 ${shown.length} 个` : ''}）`,
+  )
+  lines.push('元素字段：id 为稳定标识（写回时用它定位）；x/y 是左上角坐标，width/height 是尺寸；style 只列出非默认值；links 描述箭头端点与容器绑定。')
+  if (selection.resource !== undefined) {
+    const resource = selection.resource
+    const where = resource.path ?? resource.name ?? ''
+    const when = resource.version === undefined ? '' : `（版本 ${String(resource.version)}，也是文件最后修改时间）`
+    // Stated as the address to write back to, because that is the mistake this line
+    // prevents: a model that edits a same-named file somewhere else has not edited this.
+    if (where.length > 0) {
+      lines.push(`这份选择来自文件：${where}${when}。改动请指向这个文件，不要用同名文件代替。`)
+    }
+  }
+  if (shown.length === 0) {
+    lines.push('- （无元素明细）')
+  } else {
+    for (const element of shown) lines.push(renderElementRow(element))
+  }
+  if (selection.bounds !== undefined) {
+    const bounds = selection.bounds
+    lines.push(`选择集包围盒：@(${round(bounds.x)},${round(bounds.y)}) ${round(bounds.width)}x${round(bounds.height)}`)
+  }
+  const imageElements = selection.elements.filter(element => element.asset !== undefined)
+  if (imageElements.length > 0) {
+    lines.push(
+      `其中 ${imageElements.length} 个元素带图片素材：字节以图片块附在这次选区的可见消息里，文本里只保留 asset 定位，不要向用户索要图片数据。`,
+    )
+  }
+  if (selection.images !== undefined && selection.images.length > 0) {
+    const described = selection.images
+      .map(image => image.elementId === undefined ? '（整体）' : image.elementId)
+      .join('、')
+    lines.push(`这次选区附带 ${selection.images.length} 张图片（在可见消息里），对应元素：${described}。图片字节不在文本中，请直接使用这些图片。`)
+  }
+  for (const note of selection.notes ?? []) lines.push(note)
+  for (const capability of selection.capabilities ?? []) lines.push(capability)
+  return lines.join('\n')
+}

package/src/host/routes.ts

@@ -0,0 +1,117 @@
+/**
+ * The bridge's Host HTTP surface.
+ *
+ * Two exact routes under `/api/data-canvas/`, registered on DSH's shared API
+ * channel so they inherit the platform's trust and authentication fence instead of
+ * opening a second server. Both serve one long poll: the surface asks for work and
+ * reports what happened. Nothing is pushed to the Host on a selection change, so
+ * there is no ingest route to validate — see `narrow.ts` for the validation that
+ * still guards a read answer.
+ *
+ * @module dsh-surface-bridge/host/routes
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { ConnectionFetchRoute } from '@deepseek-ai/dsh-client-connection'
+import type {
+  BridgeErrorBody,
+  OperationSettleResponse,
+  OperationsPollResponse,
+  SurfaceOperationResult,
+} from '../contract.ts'
+import { OPS_PATH, SETTLE_PATH } from '../contract.ts'
+import type { SurfaceBridgeStore } from './store.ts'
+import { DEFAULT_POLL_HOLD_MS } from './store.ts'
+
+export { OPS_PATH, SETTLE_PATH }
+
+/** Build a JSON failure body. */
+function fail(status: number, error: string): Response {
+  const body: BridgeErrorBody = { ok: false, error }
+  return Response.json(body, { status })
+}
+
+/** Read and parse a JSON body, answering the failure response the route should return. */
+async function readJson(request: Request): Promise<{ ok: true; value: unknown } | { ok: false; response: Response }> {
+  const contentType = request.headers.get('content-type') ?? ''
+  if (!contentType.toLowerCase().startsWith('application/json')) {
+    return { ok: false, response: fail(415, '请求必须使用 application/json') }
+  }
+  try {
+    return { ok: true, value: await request.json() }
+  } catch {
+    return { ok: false, response: fail(400, '请求体不是合法 JSON') }
+  }
+}
+
+/** Narrow one operation result reported by a surface. */
+function narrowResult(value: unknown): SurfaceOperationResult | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  const raw = value as Record<string, unknown>
+  if (typeof raw.id !== 'string' || raw.id.length === 0) return undefined
+  if (typeof raw.ok !== 'boolean') return undefined
+  return {
+    id: raw.id,
+    ok: raw.ok,
+    ...(typeof raw.detail === 'string' ? { detail: raw.detail } : {}),
+    ...(typeof raw.error === 'string' ? { error: raw.error } : {}),
+    // A read answer rides here; the service validates it before anyone reads it.
+    ...(raw.value === undefined ? {} : { value: raw.value }),
+  }
+}
+
+/**
+ * Build every route the bridge serves.
+ *
+ * @param store - The bridge's Session-keyed state.
+ * @returns the exact Fetch routes to register on DSH's shared API channel.
+ */
+export function surfaceBridgeRoutes(store: SurfaceBridgeStore): readonly ConnectionFetchRoute[] {
+  return [
+    {
+      path: OPS_PATH,
+      methods: ['GET'],
+      requestBody: 'buffered',
+      fetch: async (request: Request): Promise<Response> => {
+        const url = new URL(request.url)
+        const sessionId = url.searchParams.get('sessionId')
+        if (sessionId === null || sessionId.length === 0) return fail(400, 'sessionId 必填')
+        const holdParam = url.searchParams.get('hold')
+        const hold = holdParam === null ? DEFAULT_POLL_HOLD_MS : Math.max(0, Math.min(DEFAULT_POLL_HOLD_MS, Number(holdParam) || 0))
+        const operations = await store.poll(sessionId, hold, request.signal)
+        const response: OperationsPollResponse = { operations }
+        return Response.json(response, { headers: { 'cache-control': 'no-store' } })
+      },
+    },
+    {
+      path: SETTLE_PATH,
+      methods: ['POST'],
+      requestBody: 'buffered',
+      fetch: async (request: Request): Promise<Response> => {
+        const body = await readJson(request)
+        if (!body.ok) return body.response
+        const payload = body.value as { sessionId?: unknown; result?: unknown } | null
+        if (typeof payload !== 'object' || payload === null || typeof payload.sessionId !== 'string' || payload.sessionId.length === 0) {
+          return fail(400, 'sessionId 必填')
+        }
+        const result = narrowResult(payload.result)
+        if (result === undefined) return fail(400, 'result 缺字段')
+        const accepted = store.settle(payload.sessionId, result)
+        const response: OperationSettleResponse = { accepted }
+        return Response.json(response)
+      },
+    },
+  ]
+}
+
+/**
+ * Register every bridge route for the lifetime of `ctx`.
+ *
+ * @param ctx - Plugin context; registrations are disposed with it.
+ * @param store - The bridge's Session-keyed state.
+ */
+export function registerSurfaceBridgeRoutes(ctx: Context, store: SurfaceBridgeStore): void {
+  for (const route of surfaceBridgeRoutes(store)) {
+    ctx.effect(() => ctx.connection.fetch.register(route), `dsh-surface-bridge: ${route.path}`)
+  }
+}

package/src/host/service.ts

@@ -0,0 +1,116 @@
+/**
+ * The bridge's Host service face: what a business plugin's tools call.
+ *
+ * A business plugin never touches the store or the routes. It asks three
+ * questions — "what is selected", "is the surface open", "please do this" — and
+ * the bridge owns how each is answered. "What is selected" is a *question*, not a
+ * cached value: nothing is remembered between steps. Keeping the face this small is what makes
+ * a second surface adoptable: nothing in it is canvas-shaped.
+ *
+ * @module dsh-surface-bridge/host/service
+ */
+
+import type {
+  SurfaceApplyOperation,
+  SurfaceBridgeHostFace,
+  SurfaceOperationResult,
+  SurfaceSelection,
+} from '../contract.ts'
+import { narrowSelection } from './narrow.ts'
+import { DEFAULT_OPERATION_TIMEOUT_MS, DEFAULT_READ_TIMEOUT_MS, SurfaceBridgeStore } from './store.ts'
+
+export type { SurfaceApplyOperation, SurfaceBridgeHostFace } from '../contract.ts'
+
+/** The bridge's Host service implementation. */
+export class SurfaceBridgeHost implements SurfaceBridgeHostFace {
+  private readonly store: SurfaceBridgeStore
+
+  /** @param store - Shared Session-keyed bridge state. */
+  constructor(store: SurfaceBridgeStore) {
+    this.store = store
+  }
+
+  /** @inheritdoc */
+  async readSelections(sessionId: string, signal?: AbortSignal): Promise<readonly SurfaceSelection[] | undefined> {
+    return await this.readInternal(sessionId, signal, false)
+  }
+
+  /** @inheritdoc */
+  async consumeSelections(sessionId: string, signal?: AbortSignal): Promise<readonly SurfaceSelection[] | undefined> {
+    return await this.readInternal(sessionId, signal, true)
+  }
+
+  /**
+   * One read, peeking or consuming.
+   *
+   * @param sessionId - Session whose surfaces are asked.
+   * @param signal - Aborts the wait when the turn is cancelled.
+   * @param consume - Whether the surface should spend its selection answering.
+   * @returns the valid selections that came back.
+   */
+  private async readInternal(
+    sessionId: string,
+    signal: AbortSignal | undefined,
+    consume: boolean,
+  ): Promise<readonly SurfaceSelection[] | undefined> {
+    const answer = await this.store.readSelections(sessionId, DEFAULT_READ_TIMEOUT_MS, signal, consume)
+    // Nothing answered: that is not the same fact as "nothing is selected", and the
+    // callers that can tell the user the difference must be able to.
+    if (answer === undefined) return undefined
+    const out: SurfaceSelection[] = []
+    for (const entry of answer) {
+      // The surface is trusted code, but it is still a browser boundary: a shape
+      // the renderer does not expect must not reach a model, and one bad member
+      // must not discard the rest of the answer.
+      const narrowed = narrowSelection(entry)
+      if (narrowed.ok && narrowed.selection.count > 0) out.push(narrowed.selection)
+    }
+    return out
+  }
+
+  /** @inheritdoc */
+  async readSelection(sessionId: string, source: string, signal?: AbortSignal): Promise<SurfaceSelection | null | undefined> {
+    const all = await this.readSelections(sessionId, signal)
+    if (all === undefined) return undefined
+    return all.find(selection => selection.source === source) ?? null
+  }
+
+  /** @inheritdoc */
+  isSurfaceLive(sessionId: string): boolean {
+    return this.store.isSurfaceLive(sessionId)
+  }
+
+  /** @inheritdoc */
+  async apply(
+    sessionId: string,
+    source: string,
+    operations: readonly SurfaceApplyOperation[],
+    signal?: AbortSignal,
+  ): Promise<readonly SurfaceOperationResult[]> {
+    if (operations.length === 0) return []
+    if (!this.store.isSurfaceLive(sessionId)) {
+      return operations.map(() => ({
+        id: '',
+        ok: false,
+        error: '画布未打开：请在右侧栏打开该画布标签页后重试。',
+      }))
+    }
+    const queued = operations.map(operation => this.store.enqueue(sessionId, source, operation.op, operation.payload))
+    return await Promise.all(queued.map(async (operation) => {
+      const result = await this.store.awaitResult(sessionId, operation.id, DEFAULT_OPERATION_TIMEOUT_MS, signal)
+      if (result === undefined) {
+        return {
+          id: operation.id,
+          ok: false,
+          error: '画布未在超时内回传执行结果（可能已关闭或正在重绘）。',
+        }
+      }
+      return result
+    }))
+  }
+
+  /** Release one Session's state. */
+  forget(sessionId: string): void {
+    this.store.forget(sessionId)
+  }
+}