dsh-surface-bridge 0.1.0-alpha.1

package/src/client/index.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 {} from '@deepseek-ai/dsh-client-locale/client'
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
+import type {} from '@deepseek-ai/dsh-client-ui-session/client'
+import type { LocaleNamespaceMap } from '@deepseek-ai/dsh-client-ui-slots'
+import { SurfaceBridgeRegistry, type SurfaceBridgeService } from './service.ts'
+import { SurfaceSelectionChip } from './SurfaceSelectionDock.tsx'
+import { NS, en, zh, 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 const inject = ['slots', 'locale'] as const
+
+/** 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: ClientContext): void {
+  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/src/client/locales.ts

@@ -0,0 +1,42 @@
+/**
+ * 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': '清空选择',
+} as const
+
+/** English dictionary; key set must match {@link zh} exactly. */
+export const en: Record<keyof typeof zh, string> = {
+  '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',
+}
+
+/** Dictionary key union for this namespace. */
+export type SurfaceBridgeKey = keyof typeof zh

package/src/client/service.ts

@@ -0,0 +1,110 @@
+/**
+ * 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'
+
+/** One source's live entry. */
+interface SourceEntry {
+  readonly descriptor: SurfaceSourceDescriptor
+  selection: SurfaceSelection | null
+  /** Whether the surface is on screen for the current Session; see {@link SurfaceBridgeService.setVisible}. */
+  visible: boolean
+}
+
+/** Default implementation of the bridge's browser-side registry. */
+export class SurfaceBridgeRegistry implements SurfaceBridgeService {
+  private readonly entries = new Map<string, SourceEntry>()
+  private readonly listeners = new Set<() => void>()
+  private revision = 0
+
+  /** @inheritdoc */
+  registerSource(descriptor: SurfaceSourceDescriptor): () => void {
+    this.entries.set(descriptor.id, { descriptor, selection: null, visible: false })
+    this.bump()
+    return () => {
+      this.entries.delete(descriptor.id)
+      this.bump()
+    }
+  }
+
+  /** @inheritdoc */
+  setVisible(source: string, visible: boolean): void {
+    const entry = this.entries.get(source)
+    if (entry === undefined || entry.visible === visible) return
+    entry.visible = visible
+    this.bump()
+  }
+
+  /** @inheritdoc */
+  isVisible(source: string): boolean {
+    return this.entries.get(source)?.visible === true
+  }
+
+  /** @inheritdoc */
+  publish(source: string, selection: SurfaceSelection | null): void {
+    const entry = this.entries.get(source)
+    if (entry === undefined) return
+    entry.selection = selection
+    this.bump()
+  }
+
+  /** @inheritdoc */
+  read(source: string): SurfaceSelection | null {
+    return this.entries.get(source)?.selection ?? null
+  }
+
+  /** @inheritdoc */
+  active(): readonly { descriptor: SurfaceSourceDescriptor; selection: SurfaceSelection }[] {
+    const out: { descriptor: SurfaceSourceDescriptor; selection: SurfaceSelection }[] = []
+    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: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /** @inheritdoc */
+  version(): number {
+    return this.revision
+  }
+
+  /** Advance the version and notify every subscriber. */
+  private bump(): void {
+    this.revision += 1
+    for (const listener of [...this.listeners]) listener()
+  }
+}

package/src/client/transport.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { OperationSettleResponse, OperationsPollResponse, SurfaceOperation, SurfaceOperationResult } from '../contract.ts'
+import { OPS_PATH, SETTLE_PATH } from '../contract.ts'
+
+/** Hold one poll for pending operations. */
+export async function pollOperations(sessionId: string, holdMs: number, signal: AbortSignal): Promise<readonly SurfaceOperation[]> {
+  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() as OperationsPollResponse
+  return Array.isArray(body.operations) ? body.operations : []
+}
+
+/** Report one operation's outcome back to the Host. */
+export async function settleOperation(sessionId: string, result: SurfaceOperationResult, signal?: AbortSignal): Promise<void> {
+  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() as OperationSettleResponse
+  if (body.accepted !== true) throw new Error('operation settle was not accepted')
+}

package/src/contract.ts

@@ -0,0 +1,351 @@
+/**
+ * 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'
+
+/** 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[]>
+}

package/src/css-modules.d.ts

@@ -0,0 +1,10 @@
+/* The client bundle compiles both forms: `*.module.css` to a hashed class map
+ * and a plain `*.css` to a side-effect style injection. Declaring them here keeps
+ * `tsc` (which only emits the Node half and the declarations) from rejecting the
+ * client half's imports. */
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'