dsh-surface-bridge 0.1.0-alpha.1

package/lib/types/contract.js

@@ -0,0 +1,38 @@
+/**
+ * The surface-bridge contract: the vocabulary a business surface (a right-Sidebar
+ * canvas, grid, or notebook) uses to hand its current selection to the composer,
+ * and the vocabulary the Host uses to turn that selection into model context.
+ *
+ * The contract is deliberately surface-agnostic. Nothing here mentions a canvas,
+ * a cell, or a table: a source projects its own selection into {@link SurfaceElement}
+ * rows, and the bridge owns the envelope (revision, count, bounds, the rendered
+ * model text, the optional raster). That split is what lets a second surface adopt
+ * the seam without the bridge learning what a shape is.
+ *
+ * @module dsh-surface-bridge/contract
+ */
+/**
+ * Route paths owned by the bridge.
+ *
+ * Spelled once, in the module both halves already import, because the browser's
+ * `fetch` and the Host's route registration are two halves of one wire: a typo in
+ * either would 404 at runtime with no compile-time signal.
+ */
+export const OPS_PATH = '/api/data-canvas/ops';
+export const SETTLE_PATH = '/api/data-canvas/settle';
+/**
+ * Reserved operation a Host read uses to ask a live surface what is selected.
+ *
+ * Its payload carries `consume`: a *consuming* read is one taken to put the selection
+ * into a message, and the surface drops its selection once it has answered, so the
+ * chip disappears from the composer at exactly the moment the context is spent. A
+ * non-consuming read is a peek (a tool asking what is selected) and changes nothing.
+ *
+ * It carries no source: only the browser knows which surfaces exist and which are
+ * on screen, so the Host asks "what has anyone selected?" and gets back a list. The
+ * surface answers through the ordinary settle channel with that list in
+ * {@link SurfaceOperationResult.value}. One queue item rather than a second channel,
+ * so the browser needs no extra listener and a read costs one round trip on a
+ * connection that is already parked and idle.
+ */
+export const READ_SELECTION_OP = '__surface-read-selection';

package/lib/types/host/narrow.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 { SurfaceSelection } from '../contract.ts';
+/** Cap on the selection raster the browser may attach, in base64 characters (~450 KiB of PNG). */
+export declare const MAX_RASTER_BASE64 = 600000;
+/** Cap on elements accepted per selection; the source should already cap lower. */
+export declare const MAX_ELEMENTS = 200;
+/** Cap on attached images per selection. */
+export declare const MAX_IMAGES = 8;
+/** Narrow one published selection, or explain what is wrong with it. */
+export declare function narrowSelection(value: unknown): {
+    ok: true;
+    selection: SurfaceSelection;
+} | {
+    ok: false;
+    error: string;
+};

package/lib/types/host/narrow.js

@@ -0,0 +1,193 @@
+/**
+ * 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
+ */
+/** 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) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/** Narrow a style bag to short string/number entries. */
+function narrowStyle(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        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) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry === 'string')
+            out[key] = entry;
+    }
+    return Object.keys(out).length === 0 ? undefined : out;
+}
+/** Narrow a string array. */
+function narrowStringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = value.filter((entry) => typeof entry === 'string');
+    return out.length === 0 ? undefined : out;
+}
+/** Narrow one element projection; `undefined` rejects the whole selection. */
+function narrowElement(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    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;
+    if (typeof linksRaw === 'object' && linksRaw !== null && !Array.isArray(linksRaw)) {
+        const bag = linksRaw;
+        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) }),
+        };
+        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) }),
+        ...(narrowStyle(raw.style) === undefined ? {} : { style: narrowStyle(raw.style) }),
+        ...(narrowAsset(raw.asset) === undefined ? {} : { asset: narrowAsset(raw.asset) }),
+        ...(links === undefined ? {} : { links }),
+    };
+}
+/** Narrow one raster; an oversized or malformed raster is dropped, never the selection. */
+function narrowRaster(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    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) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [];
+    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) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    const resource = {};
+    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) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return { ok: false, error: 'selection 必须是对象' };
+    const raw = value;
+    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 = [];
+    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;
+    if (typeof boundsRaw === 'object' && boundsRaw !== null && !Array.isArray(boundsRaw)) {
+        const bag = boundsRaw;
+        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) }),
+            ...(bounds === undefined ? {} : { bounds }),
+            ...(narrowImages(raw.images) === undefined ? {} : { images: narrowImages(raw.images) }),
+            ...(narrowStringArray(raw.notes) === undefined ? {} : { notes: narrowStringArray(raw.notes) }),
+            ...(narrowStringArray(raw.capabilities) === undefined ? {} : { capabilities: narrowStringArray(raw.capabilities) }),
+        },
+    };
+}

package/lib/types/host/render.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 declare const MAX_RENDERED_ELEMENTS = 40;
+/** Render one element row. */
+export declare function renderElementRow(element: SurfaceElement): string;
+/** How many element names the visible summary line carries before it degrades to `等`. */
+export declare const MAX_CHIP_NAMES = 3;
+/**
+ * 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 declare const MAX_CHIP_LINE_UNITS = 56;
+/** Width budget for the document name on the visible line, in half-width units. */
+export declare const MAX_CHIP_FILE_UNITS = 24;
+/**
+ * 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 declare function renderSelectionChip(selection: SurfaceSelection): string;
+/**
+ * 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 declare function renderSelectionText(selection: SurfaceSelection, selectionRef: string): string;

package/lib/types/host/render.js

@@ -0,0 +1,228 @@
+/**
+ * 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
+ */
+/** 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) {
+    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) {
+    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) {
+    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) {
+    const links = element.links;
+    if (links === undefined)
+        return '';
+    const parts = [];
+    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) {
+    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) {
+    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) {
+    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) {
+    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) => 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 = [];
+    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, selectionRef) {
+    const shown = selection.elements.slice(0, MAX_RENDERED_ELEMENTS);
+    const lines = [];
+    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/lib/types/host/routes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 { OPS_PATH, SETTLE_PATH } from '../contract.ts';
+import type { SurfaceBridgeStore } from './store.ts';
+export { OPS_PATH, SETTLE_PATH };
+/**
+ * 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 declare function surfaceBridgeRoutes(store: SurfaceBridgeStore): readonly ConnectionFetchRoute[];
+/**
+ * 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 declare function registerSurfaceBridgeRoutes(ctx: Context, store: SurfaceBridgeStore): void;