@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/src/contract/univer-api-catalog.ts

@@ -0,0 +1,289 @@
+/**
+ * JSON-safe metadata for the DSH adapter over Univer's Sheets Facade.
+ *
+ * The catalog is deliberately an allow-list. It gives an Agent discoverable
+ * method names and argument contracts without exposing arbitrary JavaScript or
+ * an Injector instance to the tool protocol. Methods that change workbook
+ * state map to the same durable operations used by the typed tools.
+ */
+
+import type { WorkbookOperationType } from '../types.ts'
+
+export type UniverApiMode = 'read' | 'write'
+export type UniverApiAvailability = 'implemented' | 'metadata-only'
+
+export interface UniverApiArgument {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'json'
+  required?: boolean
+  description: string
+}
+
+export interface UniverApiDefinition {
+  api: string
+  mode: UniverApiMode
+  availability: UniverApiAvailability
+  description: string
+  args: Record<string, UniverApiArgument>
+  operation?: WorkbookOperationType
+  notes?: string
+}
+
+const rangeArgs: Record<string, UniverApiArgument> = {
+  sheet: { type: 'string', description: 'sheet id 或名称；也可传 sheetId/sheetName；单 sheet workbook 可省略' },
+  range: { type: 'object', required: true, description: '0-based 矩形范围：{ startRow, startColumn, endRow, endColumn }；也接受 A1:D4' },
+}
+
+/** Common Facade methods exposed by the DSH Host adapter. */
+export const UNIVER_API_CATALOG: readonly UniverApiDefinition[] = [
+  {
+    api: 'workbook.getSnapshot',
+    mode: 'read',
+    availability: 'implemented',
+    description: '读取当前 workbook 的 Univer snapshot。大表格请优先使用 worksheet.getRangeValues。',
+    args: {},
+  },
+  {
+    api: 'workbook.getWorksheets',
+    mode: 'read',
+    availability: 'implemented',
+    description: '返回 workbook 内所有 worksheet 的 id、名称和顺序。',
+    args: {},
+  },
+  {
+    api: 'worksheet.getRangeValues',
+    mode: 'read',
+    availability: 'implemented',
+    description: '读取 worksheet 的矩形区域值。',
+    args: rangeArgs,
+  },
+  {
+    api: 'worksheet.setValues',
+    mode: 'write',
+    availability: 'implemented',
+    description: '通过 Univer Range.setValues 写入值矩阵；range 可只传起点或省略，Host 会按矩阵尺寸推导。',
+    args: { sheet: rangeArgs.sheet, range: { type: 'object', description: '可选 0-based 范围；也可只传 startRow/startColumn，或使用 A1:D4' }, values: { type: 'array', required: true, description: '二维数组，也接受单行一维数组' } },
+    operation: 'update_cells',
+  },
+  {
+    api: 'worksheet.clearContent',
+    mode: 'write',
+    availability: 'implemented',
+    description: '清除 worksheet range 的内容。',
+    args: rangeArgs,
+    operation: 'clear_range',
+  },
+  {
+    api: 'worksheet.setBackgroundColor',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置 range 背景色。',
+    args: { ...rangeArgs, color: { type: 'string', required: true, description: 'CSS 颜色' } },
+    operation: 'format_cells',
+  },
+  {
+    api: 'worksheet.setFontColor',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置 range 字体颜色。',
+    args: { ...rangeArgs, color: { type: 'string', required: true, description: 'CSS 颜色' } },
+    operation: 'format_cells',
+  },
+  {
+    api: 'worksheet.setFontFamily',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置 range 字体。',
+    args: { ...rangeArgs, family: { type: 'string', required: true, description: '字体 family' } },
+    operation: 'format_cells',
+  },
+  {
+    api: 'worksheet.setFontSize',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置 range 字号。',
+    args: { ...rangeArgs, size: { type: 'number', required: true, description: '字号，单位 pt' } },
+    operation: 'format_cells',
+  },
+  {
+    api: 'worksheet.setFontWeight',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置 range 粗体状态。',
+    args: { ...rangeArgs, bold: { type: 'boolean', required: true, description: '是否粗体' } },
+    operation: 'format_cells',
+  },
+  {
+    api: 'worksheet.setFontStyle',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置 range 斜体状态。',
+    args: { ...rangeArgs, italic: { type: 'boolean', required: true, description: '是否斜体' } },
+    operation: 'format_cells',
+  },
+  {
+    api: 'worksheet.setHorizontalAlignment',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置 range 水平对齐。',
+    args: { ...rangeArgs, alignment: { type: 'string', required: true, description: 'left、center 或 normal' } },
+    operation: 'format_cells',
+  },
+  {
+    api: 'worksheet.setVerticalAlignment',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置 range 垂直对齐。',
+    args: { ...rangeArgs, alignment: { type: 'string', required: true, description: 'top、middle 或 bottom' } },
+    operation: 'format_cells',
+  },
+  {
+    api: 'worksheet.merge',
+    mode: 'write',
+    availability: 'implemented',
+    description: '合并 worksheet range。',
+    args: rangeArgs,
+    operation: 'merge_cells',
+  },
+  {
+    api: 'worksheet.breakApart',
+    mode: 'write',
+    availability: 'implemented',
+    description: '取消 worksheet range 的合并。',
+    args: rangeArgs,
+    operation: 'unmerge_cells',
+  },
+  {
+    api: 'worksheet.sort',
+    mode: 'write',
+    availability: 'implemented',
+    description: '对 worksheet range 按列排序。',
+    args: { ...rangeArgs, column: { type: 'number', required: true, description: '0-based 排序列索引' }, direction: { type: 'string', description: 'asc 或 desc，默认 asc' } },
+    operation: 'sort_range',
+  },
+  {
+    api: 'worksheet.setColumnWidth',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置列宽。',
+    args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 列索引' }, size: { type: 'number', required: true, description: '像素宽度' } },
+    operation: 'set_column_width',
+  },
+  {
+    api: 'worksheet.setRowHeight',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置行高。',
+    args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 行索引' }, size: { type: 'number', required: true, description: '像素高度' } },
+    operation: 'set_row_height',
+  },
+  {
+    api: 'worksheet.setHyperLink',
+    mode: 'write',
+    availability: 'implemented',
+    description: '给 range 左上角单元格设置超链接；等价于 workbook_edit 的 set_hyperlink command。',
+    args: { ...rangeArgs, url: { type: 'string', required: true, description: '目标 URL' }, label: { type: 'string', description: '显示文本' } },
+    operation: 'set_hyperlink',
+  },
+  {
+    api: 'worksheet.cancelHyperLink',
+    mode: 'write',
+    availability: 'implemented',
+    description: '移除 range 左上角单元格的超链接。',
+    args: rangeArgs,
+    operation: 'remove_hyperlink',
+  },
+  {
+    api: 'worksheet.setFreeze',
+    mode: 'write',
+    availability: 'implemented',
+    description: '冻结指定行列。',
+    args: { sheet: rangeArgs.sheet, rows: { type: 'number', description: '冻结行数，默认 0' }, columns: { type: 'number', description: '冻结列数，默认 0' } },
+    operation: 'freeze_panes',
+  },
+  {
+    api: 'worksheet.deleteCells',
+    mode: 'write',
+    availability: 'implemented',
+    description: '删除 range 内容，或按 left/up 移动邻近单元格。',
+    args: { ...rangeArgs, shift: { type: 'string', description: 'clear、left 或 up，默认 clear' } },
+    operation: 'delete_cells',
+  },
+  {
+    api: 'worksheet.insertRows',
+    mode: 'write',
+    availability: 'implemented',
+    description: '在指定行位置插入行。',
+    args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 行位置' }, count: { type: 'number', description: '行数，默认 1' } },
+    operation: 'insert_rows',
+  },
+  {
+    api: 'worksheet.deleteRows',
+    mode: 'write',
+    availability: 'implemented',
+    description: '删除指定行。',
+    args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 行位置' }, count: { type: 'number', description: '行数，默认 1' } },
+    operation: 'delete_rows',
+  },
+  {
+    api: 'worksheet.insertColumns',
+    mode: 'write',
+    availability: 'implemented',
+    description: '在指定列位置插入列。',
+    args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 列位置' }, count: { type: 'number', description: '列数，默认 1' } },
+    operation: 'insert_columns',
+  },
+  {
+    api: 'worksheet.deleteColumns',
+    mode: 'write',
+    availability: 'implemented',
+    description: '删除指定列。',
+    args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 列位置' }, count: { type: 'number', description: '列数，默认 1' } },
+    operation: 'delete_columns',
+  },
+  {
+    api: 'worksheet.setTextRotation',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置 range 文字旋转角度。',
+    args: { ...rangeArgs, rotation: { type: 'number', required: true, description: '旋转角度' } },
+    operation: 'format_cells',
+  },
+  {
+    api: 'worksheet.setNumberFormat',
+    mode: 'write',
+    availability: 'implemented',
+    description: '设置 range 数字格式。',
+    args: { ...rangeArgs, format: { type: 'string', required: true, description: 'Univer number format' } },
+    operation: 'format_cells',
+  },
+  {
+    api: 'worksheet.setName',
+    mode: 'write',
+    availability: 'implemented',
+    description: '修改 worksheet 名称。',
+    args: { sheet: rangeArgs.sheet, name: { type: 'string', required: true, description: '新的 sheet 名称' } },
+    operation: 'rename_sheet',
+  },
+  {
+    api: 'workbook.createSheet',
+    mode: 'write',
+    availability: 'implemented',
+    description: '持久化创建 worksheet；可用 sheetId 指定稳定 id。',
+    args: { name: { type: 'string', required: true, description: 'sheet 名称' }, sheetId: { type: 'string', description: '可选稳定 sheet id' } },
+    operation: 'create_sheet',
+  },
+  {
+    api: 'workbook.deleteSheet',
+    mode: 'write',
+    availability: 'implemented',
+    description: '持久化删除 worksheet；工作簿至少保留一个 sheet。',
+    args: { sheet: { type: 'string', description: 'sheet id 或名称；也接受 sheetId/sheetName' } },
+    operation: 'delete_sheet',
+  },
+]
+
+export const UNIVER_API_VERSION = '0.25.1-dsh-1'
+
+export function findUniverApi(api: string): UniverApiDefinition | undefined {
+  return UNIVER_API_CATALOG.find(item => item.api === api)
+}

package/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'

package/src/errors.ts

@@ -0,0 +1,25 @@
+/** Shared wire-level errors for the Host API and browser client. */
+export type DataSheetErrorCode =
+  | 'VALIDATION_ERROR'
+  | 'WORKBOOK_NOT_FOUND'
+  | 'WORKTREE_NOT_FOUND'
+  | 'SESSION_SCOPE_DENIED'
+  | 'REVISION_CONFLICT'
+  | 'REVISION_UNAVAILABLE'
+  | 'WORKTREE_STATE_INVALID'
+  | 'PAYLOAD_TOO_LARGE'
+  | 'PERSISTENCE_FAILED'
+  | 'COLLABORATION_LIMIT'
+  | 'INTERNAL_ERROR'
+
+export class DataSheetError extends Error {
+  constructor(
+    readonly code: DataSheetErrorCode,
+    message: string,
+    readonly status = 400,
+    readonly details?: Record<string, unknown>,
+  ) {
+    super(message)
+    this.name = 'DataSheetError'
+  }
+}

package/src/http/assets-routes.ts

@@ -0,0 +1,177 @@
+/**
+ * Static plugin assets served on demand (docs/issue/0022 P3).
+ *
+ * The Univer engine chunk, the two xlsx workers and the standalone workbook
+ * page are all classic scripts or worker entry points the browser fetches after
+ * boot, so they are served from here rather than inlined into the client bundle.
+ * `univer-api.json` is the catalogue the Agent reads through its tool.
+ */
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { readFile, stat } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { LegacyRoute } from './routes.ts'
+import { guardDataSheetRequest } from './routes.ts'
+
+/**
+ * The plugin directory, found by walking up to the `package.json` that owns
+ * this file.
+ *
+ * It used to be a pair of `new URL('../../lib/...', import.meta.url)` candidates
+ * because the path depth differs between `src/` and the emitted `lib/types/`,
+ * which meant every file move silently changed what those URLs pointed at. The
+ * walk is depth-independent, so moving this module cannot break it.
+ */
+function pluginRoot(): string {
+  let directory = dirname(fileURLToPath(import.meta.url))
+  for (let depth = 0; depth < 8; depth += 1) {
+    if (existsSync(join(directory, 'package.json'))) return directory
+    const parent = dirname(directory)
+    if (parent === directory) break
+    directory = parent
+  }
+  return dirname(fileURLToPath(import.meta.url))
+}
+
+/** Absolute path of one build artifact under `lib/`. */
+const artifact = (name: string): string => join(pluginRoot(), 'lib', name)
+
+/** One artifact read, plus the identity that read is still valid for. */
+interface ResidentArtifact {
+  /** `mtimeMs:size`; a different string means the file was rebuilt. */
+  identity: string
+  bytes: Buffer
+  /** First 12 hex of the content's SHA-256 — the same value the chunk URL carries. */
+  hash: string
+}
+
+/** Last read per artifact name. The engine chunk is 13MB and changes only on rebuild. */
+const residentArtifacts = new Map<string, ResidentArtifact>()
+
+/**
+ * Read one `lib/` artifact, reusing the last read while the file is unchanged.
+ *
+ * The engine chunk used to be re-read from disk on every request, which was the
+ * only way to notice a rebuild. The `mtimeMs`/`size` identity notices the same
+ * rebuild without the disk read, and it is what lets the route answer the
+ * content-hash check below without hashing 13MB per request.
+ *
+ * @param name - file name under `lib/`.
+ * @returns the current bytes and content hash.
+ */
+async function readArtifact(name: string): Promise<ResidentArtifact> {
+  const path = artifact(name)
+  const info = await stat(path)
+  const identity = `${info.mtimeMs}:${info.size}`
+  const resident = residentArtifacts.get(name)
+  if (resident !== undefined && resident.identity === identity) return resident
+  const bytes = await readFile(path)
+  const next: ResidentArtifact = { identity, bytes, hash: createHash('sha256').update(bytes).digest('hex').slice(0, 12) }
+  residentArtifacts.set(name, next)
+  return next
+}
+
+/** Every static route this plugin serves. */
+export function assetRoutes(): LegacyRoute[] {
+  const routes: LegacyRoute[] = []
+  routes.push({
+    kind: 'exact',
+    path: '/data-sheet/univer-client.js',
+    handler: async (req, res) => {
+      if (!guardDataSheetRequest(req, res)) return
+      try {
+        const chunk = await readArtifact('univer-client.js')
+        // The loader asks for this file with its content hash in `?v=`. An exact
+        // match means the bytes cannot have changed, so the browser may keep them
+        // for a year and never ask again — which is the point: the chunk is 13MB
+        // and the sheet is opened in a fresh page constantly.
+        //
+        // Anything else — no `?v=` at all (the `/api/data-sheet?path=` transport mode
+        // drops the query), or a hash from a build that has since been replaced —
+        // is served `no-store`. A stale URL must never be able to pin different
+        // bytes, and that is exactly the failure the old unconditional `no-store`
+        // was there to prevent.
+        const requested = new URL(req.url ?? '/', 'http://x').searchParams.get('v')
+        const immutable = requested !== null && requested === chunk.hash
+        res.writeHead(200, {
+          'content-type': 'text/javascript; charset=utf-8',
+          'cache-control': immutable ? 'public, max-age=31536000, immutable' : 'no-store, must-revalidate',
+        })
+        if (req.method === 'HEAD') {
+          res.end()
+          return
+        }
+        res.end(chunk.bytes)
+      } catch {
+        res.writeHead(404)
+        res.end()
+      }
+    },
+  })
+
+  // XLSX/CSV encoding is loaded only when the user exports. Keeping it in a
+  // worker prevents SheetJS serialization from blocking the Univer canvas.
+  routes.push({
+    kind: 'exact',
+    path: '/data-sheet/xlsx-export-worker.js',
+    handler: async (_req, res) => {
+      if (!guardDataSheetRequest(_req, res)) return
+      try {
+        const body = await readFile(artifact('xlsx-export-worker.js'))
+        res.writeHead(200, {
+          'content-type': 'text/javascript; charset=utf-8',
+          'cache-control': 'no-cache',
+        })
+        res.end(body)
+      } catch {
+        res.writeHead(404)
+        res.end()
+      }
+    },
+  })
+
+  routes.push({
+    kind: 'exact',
+    path: '/data-sheet/xlsx-import-worker.js',
+    handler: async (_req, res) => {
+      if (!guardDataSheetRequest(_req, res)) return
+      try {
+        const body = await readFile(artifact('xlsx-import-worker.js'))
+        res.writeHead(200, {
+          'content-type': 'text/javascript; charset=utf-8',
+          'cache-control': 'no-cache',
+        })
+        res.end(body)
+      } catch {
+        res.writeHead(404)
+        res.end()
+      }
+    },
+  })
+
+  // Standalone client bundle for the optional full-browser workbook page.
+  routes.push({
+    kind: 'exact',
+    path: '/data-sheet/workbook-page.js',
+    handler: async (_req, res) => {
+      if (!guardDataSheetRequest(_req, res)) return
+      try {
+        const body = await readFile(artifact('workbook-page.js'))
+        res.writeHead(200, {
+          'content-type': 'text/javascript; charset=utf-8',
+          'cache-control': 'no-cache',
+        })
+        res.end(body)
+      } catch {
+        res.writeHead(404)
+        res.end()
+      }
+    },
+  })
+
+  // Workbook catalog for the browser picker. Workbook content stays behind
+  // the per-workbook snapshot endpoint; this route returns names and sheet
+  // summaries and accepts the small lifecycle mutations used by the picker.
+      return routes
+}

package/src/http/collaboration.ts

@@ -0,0 +1,144 @@
+/**
+ * The live collaboration stream (docs/issue/0022 P3).
+ *
+ * A server-sent event stream plus the presence beacon. This is a subscription
+ * protocol rather than request/response — the response stays open until the
+ * client goes away — which is why it is a module of its own.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { DataSheetError } from '../errors.ts'
+import { publishWorkbookPresence, subscribeWorkbookCollaboration, subscribeWorkbookPresence } from '../collaboration-hub.ts'
+import { readWorkbook } from '../workbook-manager.ts'
+import { parseRevision, readJsonBody, requireDataSheetSession, writeOperationError, type WorkbookRoute } from './routes.ts'
+import type { WorkbookOperation, WorkbookPresence } from '../types.ts'
+
+export async function handleCollaborationRoute(route: WorkbookRoute, req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean> {
+  const id = route.id
+
+  if (route.kind === 'presence' && req.method === 'POST') {
+    const sessionId = requireDataSheetSession(req, res, url)
+    if (sessionId === null) return true
+    let body: Record<string, unknown>
+    try { body = await readJsonBody(req) } catch (error) { writeOperationError(res, error); return true }
+    const kind = body.kind
+    if (kind !== 'selection' && kind !== 'editing' && kind !== 'active-sheet') {
+      writeOperationError(res, new DataSheetError('VALIDATION_ERROR', 'presence.kind 必须是 selection、editing 或 active-sheet'))
+      return true
+    }
+    const payload = body.payload
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+      writeOperationError(res, new DataSheetError('VALIDATION_ERROR', 'presence.payload 必须是对象'))
+      return true
+    }
+    if (JSON.stringify(payload).length > 8192) {
+      writeOperationError(res, new DataSheetError('PAYLOAD_TOO_LARGE', 'presence.payload 不能超过 8 KiB', 413))
+      return true
+    }
+    publishWorkbookPresence({ workbookId: id, sessionId, actor: 'user', kind, payload: payload as Record<string, unknown>, timestamp: new Date().toISOString() })
+    res.writeHead(202, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+    res.end(JSON.stringify({ ok: true, workbookId: id }))
+    return true
+  }
+
+  if (route.kind === 'collaboration' && req.method === 'GET') {
+    const sessionId = requireDataSheetSession(req, res, url)
+    if (sessionId === null) return true
+    const initialMeta = await readWorkbook(id)
+    if (initialMeta === null) {
+      res.writeHead(404)
+      res.end()
+      return true
+    }
+    const after = parseRevision(url.searchParams.get('after'))
+    const operations = (initialMeta.operations ?? []).filter(operation => operation.revision > after)
+    const currentRevision = initialMeta.revision ?? 0
+    const oldestRevision = operations[0]?.revision ?? currentRevision
+    const requiresSnapshot = after < oldestRevision - 1
+    const snapshot = requiresSnapshot
+      ? initialMeta.snapshot
+      : undefined
+    const pendingEvents: Array<{ operation: WorkbookOperation }> = []
+    const pendingPresence: Array<{ workbookId: string; presence: WorkbookPresence }> = []
+    let ready = false
+    let closed = false
+    const pendingWrites: string[] = []
+    const flushWrites = (): void => {
+      while (!closed && pendingWrites.length > 0) {
+        const frame = pendingWrites.shift() as string
+        if (!res.write(frame)) break
+      }
+    }
+    const writeOperationEvent = (operation: WorkbookOperation): void => {
+      if (closed) return
+      const frame = `id: ${operation.revision}\nevent: operation\ndata: ${JSON.stringify({ workbookId: id, operation })}\n\n`
+      if (pendingWrites.length > 0 || !res.write(frame)) {
+        if (pendingWrites.length >= 100) {
+          res.destroy()
+          return
+        }
+        pendingWrites.push(frame)
+      }
+    }
+    const writePresenceEvent = (presence: WorkbookPresence): void => {
+      if (closed || presence.sessionId === sessionId) return
+      const frame = `id: ${Date.parse(presence.timestamp) || Date.now()}\nevent: presence\ndata: ${JSON.stringify({ workbookId: id, presence })}\n\n`
+      if (pendingWrites.length > 0 || !res.write(frame)) {
+        if (pendingWrites.length >= 100) { res.destroy(); return }
+        pendingWrites.push(frame)
+      }
+    }
+    let unsubscribe: (() => void) | undefined
+    let unsubscribePresence: (() => void) | undefined
+    try {
+      unsubscribe = subscribeWorkbookCollaboration(id, event => {
+        if (closed) return
+        if (!ready) {
+          pendingEvents.push(event)
+          return
+        }
+        writeOperationEvent(event.operation)
+      })
+      unsubscribePresence = subscribeWorkbookPresence(id, event => {
+        if (closed || event.presence.sessionId === sessionId) return
+        if (!ready) pendingPresence.push(event)
+        else writePresenceEvent(event.presence)
+      })
+    } catch (error) {
+      res.writeHead(429, { 'content-type': 'application/json; charset=utf-8', 'retry-after': '5' })
+      res.end(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }))
+      return true
+    }
+    let heartbeat: ReturnType<typeof setInterval> | undefined
+    res.on('drain', flushWrites)
+    res.once('close', () => {
+      closed = true
+      if (heartbeat !== undefined) clearInterval(heartbeat)
+      unsubscribe?.()
+      unsubscribePresence?.()
+    })
+    heartbeat = setInterval(() => {
+      if (!closed) res.write(': heartbeat\n\n')
+    }, 15000)
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-cache, no-transform',
+      connection: 'keep-alive',
+    })
+    res.write(`event: ready\ndata: ${JSON.stringify({
+      workbookId: id,
+      revision: currentRevision,
+      operations: requiresSnapshot ? [] : operations,
+      requiresSnapshot,
+      ...(snapshot === undefined ? {} : { snapshot }),
+    })}\n\n`)
+    ready = true
+    for (const event of pendingEvents) {
+      if (event.operation.revision > currentRevision) writeOperationEvent(event.operation)
+    }
+    for (const event of pendingPresence) writePresenceEvent(event.presence)
+    await new Promise<void>(resolve => res.once('close', resolve))
+    return true
+  }
+
+  return false
+}