dsh-surface-bridge 0.1.0-alpha.1

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

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ *
+ * @module dsh-surface-bridge/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type SurfaceBridgeService } from './service.ts';
+import { type SurfaceBridgeKey } from './locales.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Browser face of the surface bridge; the seam a business surface publishes into. */
+        surfaceBridge: SurfaceBridgeService;
+    }
+}
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The selection chip's copy. */
+        'surface-bridge': SurfaceBridgeKey;
+    }
+}
+/** The slot registry, the locale registry, and the composer's overlay slot declaration. */
+export declare const inject: readonly ["slots", "locale"];
+/**
+ * Client plugin body: provide the registry, register its copy, and contribute the
+ * one chip entry.
+ *
+ * The seat is `conversation.input.overlay` — inside the composer card, on the
+ * shell's top-edge anchor — rather than `conversation.input.dock`, which renders
+ * above the card in the same stack as the to-do dock. The overlay seat is what
+ * makes the chip a region of the input box instead of one more bar in that stack.
+ *
+ * @param ctx - Client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/index.js

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ *
+ * @module dsh-surface-bridge/client
+ */
+import { SurfaceBridgeRegistry } from "./service.js";
+import { SurfaceSelectionChip } from "./SurfaceSelectionDock.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'];
+/** Slot entry id; unique within the chip slot so a re-registration shadows instead of throwing. */
+const CHIP_ENTRY_ID = 'surface-bridge';
+/**
+ * Client plugin body: provide the registry, register its copy, and contribute the
+ * one chip entry.
+ *
+ * The seat is `conversation.input.overlay` — inside the composer card, on the
+ * shell's top-edge anchor — rather than `conversation.input.dock`, which renders
+ * above the card in the same stack as the to-do dock. The overlay seat is what
+ * makes the chip a region of the input box instead of one more bar in that stack.
+ *
+ * @param ctx - Client root context.
+ */
+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');
+    ctx.slots.inject('conversation.input.overlay', () => ctx.slots.register({
+        name: 'conversation.input.overlay',
+        id: CHIP_ENTRY_ID,
+        order: 5,
+        locale: NS,
+        inject: () => ({ bridge }),
+    }, SurfaceSelectionChip));
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Copy owned by the surface bridge.
+ *
+ * The bridge renders chrome inside the composer, so every string it shows comes from
+ * here and is registered for both shipped locales. The model-facing text is not here:
+ * it belongs to the Host renderer, which is not a locale consumer.
+ *
+ * The chip's visible label is deliberately terse — `画布 · 3 个元素` — because it sits
+ * on the input line, not in a panel of its own. The long form ("已选择 3 个元素") is
+ * the chip's accessible name and the summary menu's heading, where there is room for
+ * it and where it explains rather than labels.
+ *
+ * @module dsh-surface-bridge/client/locales
+ */
+/** Dictionary namespace owned by this plugin. */
+export declare const NS = "surface-bridge";
+/** Chinese dictionary. */
+export declare const zh: {
+    readonly 'chip.aria': "已选择 {count} 个元素，展开查看";
+    readonly 'chip.count': "{count} 个元素";
+    readonly 'menu.title': "已选择 {count} 个元素";
+    readonly 'menu.empty': "（没有元素明细）";
+    readonly 'menu.more': "还有 {count} 个元素未列出";
+    readonly 'action.reveal': "定位到画布";
+    readonly 'action.clear': "清空选择";
+};
+/** English dictionary; key set must match {@link zh} exactly. */
+export declare const en: Record<keyof typeof zh, string>;
+/** Dictionary key union for this namespace. */
+export type SurfaceBridgeKey = keyof typeof zh;

package/lib/types/client/locales.js

@@ -0,0 +1,36 @@
+/**
+ * Copy owned by the surface bridge.
+ *
+ * The bridge renders chrome inside the composer, so every string it shows comes from
+ * here and is registered for both shipped locales. The model-facing text is not here:
+ * it belongs to the Host renderer, which is not a locale consumer.
+ *
+ * The chip's visible label is deliberately terse — `画布 · 3 个元素` — because it sits
+ * on the input line, not in a panel of its own. The long form ("已选择 3 个元素") is
+ * the chip's accessible name and the summary menu's heading, where there is room for
+ * it and where it explains rather than labels.
+ *
+ * @module dsh-surface-bridge/client/locales
+ */
+/** Dictionary namespace owned by this plugin. */
+export const NS = 'surface-bridge';
+/** Chinese dictionary. */
+export const zh = {
+    'chip.aria': '已选择 {count} 个元素，展开查看',
+    'chip.count': '{count} 个元素',
+    'menu.title': '已选择 {count} 个元素',
+    'menu.empty': '（没有元素明细）',
+    'menu.more': '还有 {count} 个元素未列出',
+    'action.reveal': '定位到画布',
+    'action.clear': '清空选择',
+};
+/** English dictionary; key set must match {@link zh} exactly. */
+export const en = {
+    'chip.aria': '{count} elements selected, expand for details',
+    'chip.count': '{count} elements',
+    'menu.title': '{count} elements selected',
+    'menu.empty': '(no element details)',
+    'menu.more': '{count} more elements not listed',
+    'action.reveal': 'Reveal surface',
+    'action.clear': 'Clear selection',
+};

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

@@ -0,0 +1,46 @@
+/**
+ * Browser half of the bridge: the source registry and the one live selection store.
+ *
+ * A business surface registers a descriptor once and then publishes its selection
+ * whenever the user changes it. The bridge owns everything after that — the chip and
+ * the answer to a read.
+ *
+ * Note what is *not* here: any network. Nothing leaves the page when the user selects
+ * something. The registry is the single local answer to "what is selected", read by
+ * the surface's own operation loop when the Host asks, which is why a selection only
+ * ever reaches a model as part of a message being sent.
+ *
+ * The vocabulary lives in `../contract.ts` because the Host half, the browser half,
+ * and every consumer must spell it the same way.
+ *
+ * @module dsh-surface-bridge/client/service
+ */
+import type { SurfaceBridgeService, 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 {
+    private readonly entries;
+    private readonly listeners;
+    private revision;
+    /** @inheritdoc */
+    registerSource(descriptor: SurfaceSourceDescriptor): () => void;
+    /** @inheritdoc */
+    setVisible(source: string, visible: boolean): void;
+    /** @inheritdoc */
+    isVisible(source: string): boolean;
+    /** @inheritdoc */
+    publish(source: string, selection: SurfaceSelection | null): void;
+    /** @inheritdoc */
+    read(source: string): SurfaceSelection | null;
+    /** @inheritdoc */
+    active(): readonly {
+        descriptor: SurfaceSourceDescriptor;
+        selection: SurfaceSelection;
+    }[];
+    /** @inheritdoc */
+    subscribe(listener: () => void): () => void;
+    /** @inheritdoc */
+    version(): number;
+    /** Advance the version and notify every subscriber. */
+    private bump;
+}

package/lib/types/client/service.js

@@ -0,0 +1,89 @@
+/**
+ * Browser half of the bridge: the source registry and the one live selection store.
+ *
+ * A business surface registers a descriptor once and then publishes its selection
+ * whenever the user changes it. The bridge owns everything after that — the chip and
+ * the answer to a read.
+ *
+ * Note what is *not* here: any network. Nothing leaves the page when the user selects
+ * something. The registry is the single local answer to "what is selected", read by
+ * the surface's own operation loop when the Host asks, which is why a selection only
+ * ever reaches a model as part of a message being sent.
+ *
+ * The vocabulary lives in `../contract.ts` because the Host half, the browser half,
+ * and every consumer must spell it the same way.
+ *
+ * @module dsh-surface-bridge/client/service
+ */
+/** Default implementation of the bridge's browser-side registry. */
+export class SurfaceBridgeRegistry {
+    entries = new Map();
+    listeners = new Set();
+    revision = 0;
+    /** @inheritdoc */
+    registerSource(descriptor) {
+        this.entries.set(descriptor.id, { descriptor, selection: null, visible: false });
+        this.bump();
+        return () => {
+            this.entries.delete(descriptor.id);
+            this.bump();
+        };
+    }
+    /** @inheritdoc */
+    setVisible(source, visible) {
+        const entry = this.entries.get(source);
+        if (entry === undefined || entry.visible === visible)
+            return;
+        entry.visible = visible;
+        this.bump();
+    }
+    /** @inheritdoc */
+    isVisible(source) {
+        return this.entries.get(source)?.visible === true;
+    }
+    /** @inheritdoc */
+    publish(source, selection) {
+        const entry = this.entries.get(source);
+        if (entry === undefined)
+            return;
+        entry.selection = selection;
+        this.bump();
+    }
+    /** @inheritdoc */
+    read(source) {
+        return this.entries.get(source)?.selection ?? null;
+    }
+    /** @inheritdoc */
+    active() {
+        const out = [];
+        for (const entry of this.entries.values()) {
+            // A hidden surface offers nothing: the chip must never advertise context the
+            // user cannot see, and the read answer draws on the same rule, so an
+            // invisible selection can never reach a model either.
+            if (entry.selection === null || !entry.visible)
+                continue;
+            out.push({ descriptor: entry.descriptor, selection: entry.selection });
+        }
+        return out.sort((left, right) => {
+            const order = (left.descriptor.order ?? 0) - (right.descriptor.order ?? 0);
+            if (order !== 0)
+                return order;
+            return left.descriptor.id < right.descriptor.id ? -1 : left.descriptor.id > right.descriptor.id ? 1 : 0;
+        });
+    }
+    /** @inheritdoc */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /** @inheritdoc */
+    version() {
+        return this.revision;
+    }
+    /** Advance the version and notify every subscriber. */
+    bump() {
+        this.revision += 1;
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Browser-side transport of the bridge.
+ *
+ * One long poll, held by the Host for up to twenty seconds, that carries both
+ * directions: the surface asks for work and reports what happened. A failure —
+ * including an abort from a page unload or a Connection generation change — is an
+ * ordinary reason to poll again rather than a broken surface.
+ *
+ * There is deliberately no "here is my selection" call. A selection is read by the
+ * Host when a model step needs it, so nothing travels while the user is merely
+ * drawing.
+ *
+ * @module dsh-surface-bridge/client/transport
+ */
+import type { SurfaceOperation, SurfaceOperationResult } from '../contract.ts';
+/** Hold one poll for pending operations. */
+export declare function pollOperations(sessionId: string, holdMs: number, signal: AbortSignal): Promise<readonly SurfaceOperation[]>;
+/** Report one operation's outcome back to the Host. */
+export declare function settleOperation(sessionId: string, result: SurfaceOperationResult, signal?: AbortSignal): Promise<void>;

package/lib/types/client/transport.js

@@ -0,0 +1,38 @@
+/**
+ * Browser-side transport of the bridge.
+ *
+ * One long poll, held by the Host for up to twenty seconds, that carries both
+ * directions: the surface asks for work and reports what happened. A failure —
+ * including an abort from a page unload or a Connection generation change — is an
+ * ordinary reason to poll again rather than a broken surface.
+ *
+ * There is deliberately no "here is my selection" call. A selection is read by the
+ * Host when a model step needs it, so nothing travels while the user is merely
+ * drawing.
+ *
+ * @module dsh-surface-bridge/client/transport
+ */
+import { OPS_PATH, SETTLE_PATH } from "../contract.js";
+/** Hold one poll for pending operations. */
+export async function pollOperations(sessionId, holdMs, signal) {
+    const url = `${OPS_PATH}?sessionId=${encodeURIComponent(sessionId)}&hold=${String(holdMs)}`;
+    const response = await fetch(url, { signal, headers: { accept: 'application/json' } });
+    if (!response.ok)
+        throw new Error(`operations poll failed: HTTP ${response.status}`);
+    const body = await response.json();
+    return Array.isArray(body.operations) ? body.operations : [];
+}
+/** Report one operation's outcome back to the Host. */
+export async function settleOperation(sessionId, result, signal) {
+    const response = await fetch(SETTLE_PATH, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ sessionId, result }),
+        ...(signal === undefined ? {} : { signal }),
+    });
+    if (!response.ok)
+        throw new Error(`operation settle failed: HTTP ${response.status}`);
+    const body = await response.json();
+    if (body.accepted !== true)
+        throw new Error('operation settle was not accepted');
+}

package/lib/types/contract.d.ts

@@ -0,0 +1,329 @@
+/**
+ * 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 declare const OPS_PATH = "/api/data-canvas/ops";
+export declare 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 declare const READ_SELECTION_OP = "__surface-read-selection";
+/** Media types an attached raster may use; the set the Host's attachment service admits. */
+export type SurfaceRasterMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+/** How one element connects to others in the same selection. */
+export interface SurfaceElementLinks {
+    /** Source-side endpoint id (an arrow's start). */
+    readonly from?: string;
+    /** Target-side endpoint id (an arrow's end). */
+    readonly to?: string;
+    /** Container this element is bound into (text inside a shape, label on a line). */
+    readonly container?: string;
+    /** Elements bound to this one. */
+    readonly bound?: readonly string[];
+}
+/** One element of a selection, projected to the facts a model can act on. */
+export interface SurfaceElement {
+    /** Stable identity inside the source; the handle every write-back operation addresses. */
+    readonly id: string;
+    /** Source-defined kind, e.g. `rectangle`, `arrow`, `text`, `image`, `cell`. */
+    readonly type: string;
+    /** One-line human label shown in the chip's summary list, e.g. `矩形 "下单"`. */
+    readonly label: string;
+    /** Text the element carries, if any. Absent for purely graphical elements. */
+    readonly text?: string;
+    /** Left edge in source coordinates. */
+    readonly x: number;
+    /** Top edge in source coordinates. */
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    /** Rotation in degrees, when the source has one. */
+    readonly angle?: number;
+    /** Presentation facts worth sending, already projected to short names. */
+    readonly style?: Readonly<Record<string, string | number>>;
+    /**
+     * Where a heavy payload lives, never the payload itself. An image element
+     * reports its asset handle here and the bytes travel as {@link SurfaceSelection.raster}.
+     */
+    readonly asset?: Readonly<Record<string, string>>;
+    /** Connection relations to other elements. */
+    readonly links?: SurfaceElementLinks;
+}
+/** A rectangle in source coordinates. */
+export interface SurfaceBounds {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * The document a selection was taken from, when the surface is a view of one file.
+ *
+ * A right-Sidebar surface is usually a view of a project file — a scene, a workbook, a
+ * notebook — and the Agent's tools address that file by path. Without this field the
+ * context said "the user selected 30 elements" and nothing about *which* document, so a
+ * model that wrote to the same-named file in another directory believed it had edited the
+ * drawing on screen. It had not. The path travels with the selection so the write-back
+ * can name the exact file, and the row the user reads says which document they sent.
+ *
+ * Optional throughout: a surface that is not a view of a file simply omits it.
+ */
+export interface SurfaceResource {
+    /** Absolute path on the Host, when the surface can name one. */
+    readonly path?: string;
+    /** Short name for the chip and the model header, e.g. `main.excalidraw`. */
+    readonly name?: string;
+    /**
+     * Version of the document this selection was projected from — a file mtime, a
+     * revision counter, whatever the surface uses. It is what lets the Agent detect that
+     * the file moved on between the selection and the edit.
+     */
+    readonly version?: number;
+}
+/** A raster the source attached for one element or for the selection as a whole. */
+export interface SurfaceRaster {
+    readonly mediaType: SurfaceRasterMediaType;
+    /** Base64 bytes without a data-URL prefix. */
+    readonly data: string;
+    /** Display name for the resulting attachment. */
+    readonly name?: string;
+    /**
+     * Element this raster belongs to, when it is one element's own bytes rather
+     * than a render of the whole selection. The model-facing text lists the same
+     * id, so the model can pair each image with the row that locates it.
+     */
+    readonly elementId?: string;
+}
+/** Everything one source wants the model to know about its current selection. */
+export interface SurfaceSelection {
+    /** Source id; the same string the source registered under. */
+    readonly source: string;
+    /**
+     * Monotonic revision minted by the source. The Host consumes each revision at
+     * most once, so a selection cannot leak into an unrelated later message.
+     */
+    readonly revision: number;
+    /** Element count. May exceed `elements.length` when the source caps the list. */
+    readonly count: number;
+    /** Human title of the surface, e.g. `Canvas`. Rendered in the chip and the model header. */
+    readonly title: string;
+    /** One-line chip summary, e.g. `已选择 3 个元素`. */
+    readonly summary: string;
+    /** Element projections, capped by the source. */
+    readonly elements: readonly SurfaceElement[];
+    /** True when `elements` is a truncated view of `count`. */
+    readonly truncated?: boolean;
+    /** The document this selection came from, when the surface is a view of a file. */
+    readonly resource?: SurfaceResource;
+    /** Bounding box of the whole selection, when the source can compute one. */
+    readonly bounds?: SurfaceBounds;
+    /**
+     * Heavy element payloads the source chose to send as real images instead of
+     * text. A source sends at most a few, capped by its own byte budget; each one
+     * names the element it belongs to so the text can stay a set of locators.
+     */
+    readonly images?: readonly SurfaceRaster[];
+    /** Extra facts the source wants in the model text (scene size, per-type counts…). */
+    readonly notes?: readonly string[];
+    /** What the model may do to this surface; rendered as the available operations. */
+    readonly capabilities?: readonly string[];
+}
+/** One selection as the Host holds it, with the arrival time that makes staleness visible. */
+export interface StoredSelection {
+    readonly selection: SurfaceSelection;
+    /** Host clock at arrival. */
+    readonly receivedAt: number;
+}
+/** One write-back operation an Agent asked the surface to perform. */
+export interface SurfaceOperation {
+    /** Operation id minted by the Host; echoed back with the result. */
+    readonly id: string;
+    /** Source the operation targets. */
+    readonly source: string;
+    /** Source-defined verb, e.g. `update`, `add`, `delete`. */
+    readonly op: string;
+    /** Source-defined payload. The bridge never interprets it. */
+    readonly payload: unknown;
+}
+/** Outcome of one operation, reported by the surface that executed it. */
+export interface SurfaceOperationResult {
+    readonly id: string;
+    readonly ok: boolean;
+    /** Source-reported detail on success (the element's final state, a count, …). */
+    readonly detail?: string;
+    /** Failure message on `ok: false`. */
+    readonly error?: string;
+    /**
+     * Value carried back for a read ({@link READ_SELECTION_OP}): every on-screen
+     * selection, as an array. Empty when nothing is selected or no surface is open.
+     */
+    readonly value?: unknown;
+}
+/** Poll response of `GET /api/data-canvas/ops`. */
+export interface OperationsPollResponse {
+    readonly operations: readonly SurfaceOperation[];
+}
+/** Reply body of `POST /api/data-canvas/ops/{id}`. */
+export interface OperationSettleResponse {
+    readonly accepted: boolean;
+}
+/** Body of a rejected bridge request. */
+export interface BridgeErrorBody {
+    readonly ok: false;
+    readonly error: string;
+}
+/** One write-back operation as a business plugin's tool states it. */
+export interface SurfaceApplyOperation {
+    /** Source-defined verb, e.g. `update`, `add`, `delete`. */
+    readonly op: string;
+    /** Source-defined payload, passed through the bridge untouched. */
+    readonly payload: unknown;
+}
+/** Glyph contract shared with the host shell's icon set. */
+export interface SurfaceIconProps {
+    readonly size?: number;
+    readonly className?: string;
+}
+/** What a surface declares once, at registration. */
+export interface SurfaceSourceDescriptor {
+    /** Stable source id; the same string published selections carry. */
+    readonly id: string;
+    /** Human label for the chip, e.g. `Canvas`. */
+    readonly label: string;
+    /** Glyph rendered before the label. */
+    readonly icon?: import('react').ComponentType<SurfaceIconProps>;
+    /** Lower sorts first when several sources have selections at once. */
+    readonly order?: number;
+    /**
+     * Bring the surface to the front. The chip's reveal action calls this; a source
+     * that cannot be revealed omits it and the action is not offered.
+     */
+    readonly reveal?: () => void;
+    /**
+     * Bring one element into view. The chip's summary list calls this when a row is
+     * picked, so a user reading "3 elements selected" can see which one they mean.
+     */
+    readonly focusElement?: (elementId: string) => void;
+}
+/**
+ * The `ctx.surfaceBridge` face a business surface publishes into.
+ *
+ * A surface registers once and then calls {@link publish} whenever the user's
+ * selection changes. Publishing is local — it drives the chip and answers the Host's
+ * read — and nothing about it touches the network.
+ */
+export interface SurfaceBridgeService {
+    /** Register one surface. The returned disposer removes it and its selection. */
+    registerSource(descriptor: SurfaceSourceDescriptor): () => void;
+    /**
+     * Tell the bridge whether a surface is on screen for the current Session.
+     *
+     * A surface that is hidden — the user switched tabs, switched Session, or
+     * collapsed the column — must not advertise a selection: the chip would offer
+     * to send context the user cannot see or clear. Hidden sources drop out of
+     * {@link active}, which both hides the chip and disarms the Host.
+     */
+    setVisible(source: string, visible: boolean): void;
+    /** Whether a source is currently on screen. */
+    isVisible(source: string): boolean;
+    /** Publish (or clear, with `null`) one source's selection. */
+    publish(source: string, selection: SurfaceSelection | null): void;
+    /** Read one source's current selection. */
+    read(source: string): SurfaceSelection | null;
+    /** Read every source that currently has a selection, in chip order. */
+    active(): readonly {
+        descriptor: SurfaceSourceDescriptor;
+        selection: SurfaceSelection;
+    }[];
+    /** Subscribe to any change (selection, sync state, roster). */
+    subscribe(listener: () => void): () => void;
+    /** Snapshot version, for `useSyncExternalStore`. */
+    version(): number;
+}
+/** The Host face of the bridge; what a business plugin's tools call. */
+export interface SurfaceBridgeHostFace {
+    /**
+     * Ask the live surfaces what they have selected right now.
+     *
+     * Read on demand rather than pushed on every change: nothing travels and nothing
+     * is remembered until a model step actually needs it. A surface that is closed,
+     * off screen, or has cleared its selection contributes nothing, so an invisible
+     * selection can never reach a model.
+     *
+     * @param sessionId - Session whose composer is in play.
+     * @param signal - Aborts the wait when the turn is cancelled.
+     * @returns one entry per source that has something selected — or `undefined` when
+     *   nothing answered at all. The difference matters and must not be flattened: an
+     *   empty array means "the surface spoke and there is no selection", while
+     *   `undefined` means "no surface is there to ask".
+     */
+    readSelections(sessionId: string, signal?: AbortSignal): Promise<readonly SurfaceSelection[] | undefined>;
+    /**
+     * Read every on-screen selection **and spend it**: the surface drops each selection
+     * it reported, so it is not offered again unless the user selects something else.
+     *
+     * Used at the step that is about to carry the selection into a message. A peek
+     * ({@link readSelections}) leaves the selection in place.
+     *
+     * @param sessionId - Session whose composer is in play.
+     * @param signal - Aborts the wait when the turn is cancelled.
+     * @returns the same answer as {@link readSelections}.
+     */
+    consumeSelections(sessionId: string, signal?: AbortSignal): Promise<readonly SurfaceSelection[] | undefined>;
+    /**
+     * Read one named source's current selection.
+     *
+     * @param sessionId - Session whose composer is in play.
+     * @param source - Source id to pick out of the answer.
+     * @param signal - Aborts the wait when the turn is cancelled.
+     * @returns that source's selection, `null` when it answered with none, or
+     *   `undefined` when nothing answered.
+     */
+    readSelection(sessionId: string, source: string, signal?: AbortSignal): Promise<SurfaceSelection | null | undefined>;
+    /**
+     * Whether a surface of this Session has polled recently enough to be considered open.
+     *
+     * @param sessionId - Session to test.
+     * @returns whether the surface is live.
+     */
+    isSurfaceLive(sessionId: string): boolean;
+    /**
+     * Run write-back operations on one surface and wait for its report.
+     *
+     * @param sessionId - Session owning the surface.
+     * @param source - Source id.
+     * @param operations - Operations to run, in order.
+     * @param signal - Aborts the wait when the turn is cancelled.
+     * @returns one result per operation, in the same order; an unanswered operation
+     *          comes back as an explicit failure rather than a silent success.
+     */
+    apply(sessionId: string, source: string, operations: readonly SurfaceApplyOperation[], signal?: AbortSignal): Promise<readonly SurfaceOperationResult[]>;
+}