pi-tldraw 0.1.0

package/src/mcp/client.ts

@@ -0,0 +1,126 @@
+import { parseMcpResponse, type JsonRpcResponse } from './response'
+
+export type McpTool = {
+	name: string
+	title?: string
+	description?: string
+	inputSchema?: unknown
+	_meta?: unknown
+}
+
+export type McpResource = {
+	uri: string
+	name?: string
+	title?: string
+	description?: string
+	mimeType?: string
+}
+
+const MCP_PROTOCOL_VERSION = '2025-06-18'
+
+export class TldrawMcpClient {
+	private sessionId: string | null = null
+	private nextId = 1
+
+	constructor(
+		private readonly endpoint: string,
+		private readonly ensureServer?: (signal?: AbortSignal) => Promise<void>
+	) {}
+
+	async initialize(signal?: AbortSignal) {
+		if (this.sessionId) return
+		await this.ensureServer?.(signal)
+
+		const { response, payload } = await this.post<JsonRpcResponse>(
+			{
+				jsonrpc: '2.0',
+				id: this.nextId++,
+				method: 'initialize',
+				params: {
+					protocolVersion: MCP_PROTOCOL_VERSION,
+					capabilities: {},
+					clientInfo: { name: 'pi-tldraw', version: '0.0.1' },
+				},
+			},
+			signal
+		)
+
+		const sessionId = response.headers.get('mcp-session-id')
+		if (!sessionId) {
+			throw new Error('tldraw MCP initialize succeeded but did not return mcp-session-id')
+		}
+		if (payload.error) throw new Error(payload.error.message)
+
+		this.sessionId = sessionId
+		await this.notifyInitialized(signal)
+	}
+
+	async listTools(signal?: AbortSignal): Promise<McpTool[]> {
+		const result = await this.request<{ tools?: McpTool[] }>('tools/list', {}, signal)
+		return result.tools ?? []
+	}
+
+	async listResources(signal?: AbortSignal): Promise<McpResource[]> {
+		const result = await this.request<{ resources?: McpResource[] }>('resources/list', {}, signal)
+		return result.resources ?? []
+	}
+
+	async callTool(name: string, args: Record<string, unknown>, signal?: AbortSignal) {
+		return this.request('tools/call', { name, arguments: args }, signal)
+	}
+
+	async readResource(uri: string, signal?: AbortSignal) {
+		return this.request('resources/read', { uri }, signal)
+	}
+
+	reset() {
+		this.sessionId = null
+	}
+
+	private async notifyInitialized(signal?: AbortSignal) {
+		await this.post(
+			{
+				jsonrpc: '2.0',
+				method: 'notifications/initialized',
+			},
+			signal,
+			{ sessionId: this.sessionId }
+		)
+	}
+
+	private async request<T = unknown>(method: string, params: unknown, signal?: AbortSignal): Promise<T> {
+		await this.initialize(signal)
+		const { payload } = await this.post<JsonRpcResponse<T>>(
+			{
+				jsonrpc: '2.0',
+				id: this.nextId++,
+				method,
+				params,
+			},
+			signal,
+			{ sessionId: this.sessionId }
+		)
+		if (payload.error) throw new Error(payload.error.message)
+		return payload.result as T
+	}
+
+	private async post<T>(body: unknown, signal?: AbortSignal, opts?: { sessionId?: string | null }) {
+		const headers: Record<string, string> = {
+			'Content-Type': 'application/json',
+			Accept: 'application/json, text/event-stream',
+		}
+		if (opts?.sessionId) headers['mcp-session-id'] = opts.sessionId
+
+		const response = await fetch(this.endpoint, {
+			method: 'POST',
+			headers,
+			body: JSON.stringify(body),
+			signal,
+		})
+		const text = await response.text()
+		if (!response.ok) {
+			throw new Error(`MCP HTTP ${response.status}: ${text}`)
+		}
+		return { response, payload: parseMcpResponse<T>(text) }
+	}
+}

package/src/mcp/response.ts

@@ -0,0 +1,74 @@
+export type JsonRpcResponse<T = unknown> = {
+	jsonrpc: '2.0'
+	id?: string | number
+	result?: T
+	error?: { code: number; message: string; data?: unknown }
+}
+
+export type McpContentItem =
+	| { type: 'text'; text: string }
+	| Record<string, unknown>
+
+export type McpToolResult = {
+	content?: unknown
+	structuredContent?: unknown
+	[key: string]: unknown
+}
+
+export function parseMcpResponse<T>(text: string): T {
+	const trimmed = text.trim()
+	if (!trimmed) return undefined as T
+	if (isJsonPayload(trimmed)) return JSON.parse(trimmed) as T
+
+	const dataLine = trimmed.split(/\r?\n/).find((line) => line.startsWith('data:'))
+	if (dataLine) return JSON.parse(dataLine.slice('data:'.length).trim()) as T
+
+	throw new Error(`Could not parse MCP response: ${trimmed.slice(0, 200)}`)
+}
+
+const isJsonPayload = (text: string): boolean => text.startsWith('{') || text.startsWith('[')
+
+export function extractTextContent(result: McpToolResult): string {
+	const content = result.content
+	if (!Array.isArray(content)) return JSON.stringify(result, null, 2)
+	return content.map(contentItemText).join('\n')
+}
+
+function contentItemText(item: unknown): string {
+	if (isTextContent(item)) return item.text
+	return JSON.stringify(item)
+}
+
+const isTextContent = (item: unknown): item is { type: 'text'; text: string } =>
+	Boolean(
+		item &&
+			typeof item === 'object' &&
+			(item as Record<string, unknown>).type === 'text' &&
+			typeof (item as Record<string, unknown>).text === 'string'
+	)
+
+export function parseCanvasIdFromText(text: string): string | undefined {
+	return text.match(/Canvas ID: ([^\s]+)/)?.[1]
+}
+
+export function parseCanvasIdFromResult(result: McpToolResult): string | undefined {
+	return parseCanvasIdFromText(extractTextContent(result))
+}
+
+export function extractReturnValue(result: McpToolResult): unknown {
+	const text = extractTextContent(result)
+	const marker = 'Return value:\n'
+	const start = text.indexOf(marker)
+	if (start === -1) return undefined
+
+	const afterMarker = text.slice(start + marker.length)
+	const end = afterMarker.indexOf('\n\nCanvas ID:')
+	const json = (end === -1 ? afterMarker : afterMarker.slice(0, end)).trim()
+	if (!json) return undefined
+
+	try {
+		return JSON.parse(json)
+	} catch {
+		return undefined
+	}
+}

package/src/semantic/layer.ts

@@ -0,0 +1,309 @@
+/**
+ * Semantic layer for tldraw canvases.
+ *
+ * Turns the raw focused-shape "flood" into a compact, meaning-first view that is
+ * cheap for an LLM to read. The pipeline is a small set of pure functions over a
+ * uniform element table (the "tensor"):
+ *
+ *     bundle ──assemble──▶ RawRow[] ──enrich──▶ ElementRow[] ──render──▶ string
+ *
+ * Rendering is parameterized by an *aperture* — a named reduction policy:
+ *   - 'overview' : census + edge list + reading-order nodes. Right for small/medium
+ *                  canvases. Output grows with the canvas (O(nodes + edges)).
+ *   - 'summary'  : census + graph statistics (components, hubs) + size distribution.
+ *                  Bounded output (O(topK)) regardless of canvas size. Right for
+ *                  large/dense canvases where an edge list would itself be a flood.
+ *
+ * This module is deliberately a *walking skeleton*: the columns and renderers are
+ * the minimum that demonstrably reduces tokens while staying correct. Clustering,
+ * containment, role inference, handles, focus/halo scoping, and image rendering are
+ * later rings that enrich the same tensor — they are intentionally not here yet.
+ */
+
+export type ElementKind = 'node' | 'edge' | 'note' | 'text' | 'freehand' | 'frame' | 'group' | 'image'
+
+/** A shape in the tldraw "focused" format (the shape that exec reads/writes). */
+export interface FocusedShape {
+	_type?: string
+	type?: string
+	shapeId?: string
+	id?: string
+	x?: number
+	y?: number
+	w?: number
+	h?: number
+	text?: string
+	fromId?: string | null
+	toId?: string | null
+	[key: string]: unknown
+}
+
+export interface CanvasBundle {
+	shapes: FocusedShape[]
+	assets?: unknown[]
+	/**
+	 * Arrow→shape bindings. Intentionally ignored by the semantic layer: arrow
+	 * `fromId`/`toId` already carry the graph, so bindings are pure redundancy for
+	 * a reader. Kept in the type only so callers can pass a full bundle through.
+	 */
+	bindings?: unknown[]
+}
+
+/** Raw columns: a uniform row per element, before any derivation. */
+export interface RawRow {
+	id: string
+	kind: ElementKind
+	type: string
+	x: number
+	y: number
+	w: number
+	h: number
+	text: string
+	fromId: string | null
+	toId: string | null
+}
+
+/** Enriched row: raw columns + the minimal derived columns the renderers use. */
+export interface ElementRow extends RawRow {
+	cx: number
+	cy: number
+	area: number
+	degree: number
+}
+
+export type Aperture = 'overview' | 'summary'
+
+export interface RenderOptions {
+	aperture?: Aperture
+	/** Element-count threshold above which 'auto' picks 'summary'. */
+	autoThreshold?: number
+	/** Top-K hubs/largest nodes to list in the summary aperture. */
+	topK?: number
+}
+
+function kindOf(type: string): ElementKind {
+	switch (type) {
+		case 'arrow':
+			return 'edge'
+		case 'note':
+			return 'note'
+		case 'text':
+			return 'text'
+		case 'line':
+		case 'draw':
+			return 'freehand'
+		case 'frame':
+			return 'frame'
+		case 'group':
+			return 'group'
+		case 'image':
+			return 'image'
+		default:
+			return 'node'
+	}
+}
+
+const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
+
+/** Stage 1 — flatten every shape into a uniform raw row. Lossless w.r.t. the columns we keep. */
+export function assemble(bundle: CanvasBundle): RawRow[] {
+	const shapes = Array.isArray(bundle.shapes) ? bundle.shapes : []
+	return shapes.map((s) => {
+		const type = s._type ?? s.type ?? 'unknown'
+		return {
+			id: String(s.shapeId ?? s.id ?? ''),
+			kind: kindOf(type),
+			type,
+			x: Math.round(num(s.x)),
+			y: Math.round(num(s.y)),
+			w: Math.round(num(s.w)),
+			h: Math.round(num(s.h)),
+			text: (typeof s.text === 'string' ? s.text : '').trim(),
+			fromId: s.fromId != null ? String(s.fromId) : null,
+			toId: s.toId != null ? String(s.toId) : null,
+		}
+	})
+}
+
+/** Stage 2 — add the minimal derived columns (center, area, graph degree). */
+export function enrich(rows: RawRow[]): ElementRow[] {
+	const degree = new Map<string, number>()
+	for (const r of rows) {
+		if (r.kind !== 'edge') continue
+		if (r.fromId) degree.set(r.fromId, (degree.get(r.fromId) ?? 0) + 1)
+		if (r.toId) degree.set(r.toId, (degree.get(r.toId) ?? 0) + 1)
+	}
+	return rows.map((r) => ({
+		...r,
+		cx: r.x + r.w / 2,
+		cy: r.y + r.h / 2,
+		area: r.w * r.h,
+		degree: degree.get(r.id) ?? 0,
+	}))
+}
+
+/** Build the full tensor in one call. */
+export function buildTensor(bundle: CanvasBundle): ElementRow[] {
+	return enrich(assemble(bundle))
+}
+
+function splitNodesEdges(rows: ElementRow[]) {
+	const nodes = rows.filter((r) => r.kind !== 'edge')
+	const edges = rows.filter((r) => r.kind === 'edge')
+	return { nodes, edges }
+}
+
+function census(rows: ElementRow[]): string {
+	const counts: Record<string, number> = {}
+	for (const r of rows) counts[r.kind] = (counts[r.kind] ?? 0) + 1
+	return (
+		Object.entries(counts)
+			.sort(([, a], [, b]) => b - a)
+			.map(([k, v]) => `${v} ${k}${v > 1 ? 's' : ''}`)
+			.join(' · ') || 'empty'
+	)
+}
+
+function medianArea(nodes: ElementRow[]): number {
+	const areas = nodes
+		.map((n) => n.area)
+		.filter((a) => a > 0)
+		.sort((a, b) => a - b)
+	return areas.length ? areas[Math.floor(areas.length / 2)] : 0
+}
+
+function sizeClass(area: number, median: number): string {
+	if (!area || !median) return '·'
+	if (area < median * 0.5) return 's'
+	if (area > median * 2) return 'L'
+	return 'm'
+}
+
+function nodeLabel(id: string | null, byId: Map<string, ElementRow>): string {
+	if (!id) return '∅'
+	const n = byId.get(id)
+	if (!n) return `${id}?` // unresolved endpoint (orphan arrow)
+	return n.text ? `"${n.text}"` : n.type
+}
+
+/**
+ * 'overview' aperture — census + full edge list + reading-order node list.
+ * Output scales with the canvas; ideal for small/medium diagrams.
+ */
+export function renderOverview(rows: ElementRow[]): string {
+	const { nodes, edges } = splitNodesEdges(rows)
+	const byId = new Map(nodes.map((n) => [n.id, n]))
+	const median = medianArea(nodes)
+
+	const out: string[] = [`CANVAS · ${census(rows)}`, '']
+
+	if (edges.length) {
+		out.push('GRAPH')
+		for (const e of edges) {
+			const arrow = e.text ? ` —${e.text}→ ` : ' → '
+			out.push(`  ${nodeLabel(e.fromId, byId)}${arrow}${nodeLabel(e.toId, byId)}`)
+		}
+		out.push('')
+	}
+
+	out.push(`NODES (reading order, ${nodes.length})`)
+	const ordered = [...nodes].sort((a, b) => a.cy - b.cy || a.cx - b.cx)
+	for (const n of ordered) {
+		const loose = n.degree === 0 ? ' ·loose' : ''
+		out.push(`  [${sizeClass(n.area, median)}] ${n.type}${n.text ? ` "${n.text}"` : ''}${loose}`)
+	}
+	return out.join('\n')
+}
+
+/** Weakly-connected components over the node/edge graph (union-find). */
+function connectedComponents(nodes: ElementRow[], edges: ElementRow[]) {
+	const parent = new Map<string, string>()
+	const find = (x: string): string => {
+		let root = x
+		while (parent.get(root) !== root) root = parent.get(root)!
+		while (parent.get(x) !== root) {
+			const next = parent.get(x)!
+			parent.set(x, root)
+			x = next
+		}
+		return root
+	}
+	const union = (a: string, b: string) => {
+		const ra = find(a)
+		const rb = find(b)
+		if (ra !== rb) parent.set(ra, rb)
+	}
+	for (const n of nodes) parent.set(n.id, n.id)
+	for (const e of edges) {
+		if (e.fromId && e.toId && parent.has(e.fromId) && parent.has(e.toId)) union(e.fromId, e.toId)
+	}
+	const sizes = new Map<string, number>()
+	for (const n of nodes) {
+		const root = find(n.id)
+		sizes.set(root, (sizes.get(root) ?? 0) + 1)
+	}
+	return [...sizes.values()].sort((a, b) => b - a)
+}
+
+/**
+ * 'summary' aperture — census + graph statistics + size distribution. Bounded
+ * output (O(topK)) regardless of canvas size; ideal for large/dense diagrams
+ * where listing every edge would itself be a flood.
+ */
+export function renderSummary(rows: ElementRow[], topK = 8): string {
+	const { nodes, edges } = splitNodesEdges(rows)
+	const byId = new Map(nodes.map((n) => [n.id, n]))
+	const out: string[] = [`CANVAS · ${census(rows)}`, '']
+
+	// --- Graph shape ---
+	if (edges.length) {
+		const comps = connectedComponents(nodes, edges)
+		const isolated = nodes.filter((n) => n.degree === 0).length
+		const labeled = edges.filter((e) => e.text).length
+		out.push('GRAPH')
+		out.push(`  ${edges.length} edges · ${comps.length} component${comps.length === 1 ? '' : 's'} (largest ${comps[0] ?? 0}) · ${isolated} isolated`)
+		out.push(`  ${labeled}/${edges.length} edges labeled`)
+		const hubs = [...nodes]
+			.filter((n) => n.degree > 0)
+			.sort((a, b) => b.degree - a.degree)
+			.slice(0, topK)
+		if (hubs.length) {
+			out.push('  hubs:')
+			for (const h of hubs) out.push(`    ${nodeLabel(h.id, byId)} (deg ${h.degree})`)
+		}
+		out.push('')
+	}
+
+	// --- Size distribution ---
+	const median = medianArea(nodes)
+	const buckets: Record<string, number> = { s: 0, m: 0, L: 0, '·': 0 }
+	for (const n of nodes) buckets[sizeClass(n.area, median)]++
+	out.push('SIZE')
+	out.push(`  small ${buckets.s} · medium ${buckets.m} · large ${buckets.L} · sizeless ${buckets['·']}`)
+	const biggest = [...nodes]
+		.filter((n) => n.area > 0)
+		.sort((a, b) => b.area - a.area)
+		.slice(0, topK)
+	if (biggest.length) {
+		out.push('  largest:')
+		for (const n of biggest) out.push(`    ${nodeLabel(n.id, byId)}`)
+	}
+	return out.join('\n')
+}
+
+/** Pick an aperture from canvas size when the caller asks for 'auto' (default). */
+export function chooseAperture(rows: ElementRow[], threshold = 60): Aperture {
+	return rows.length > threshold ? 'summary' : 'overview'
+}
+
+/** Top-level convenience: build the tensor and render at the chosen aperture. */
+export function renderView(bundle: CanvasBundle, opts: RenderOptions = {}): string {
+	const rows = buildTensor(bundle)
+	const aperture = opts.aperture ?? chooseAperture(rows, opts.autoThreshold)
+	return aperture === 'summary' ? renderSummary(rows, opts.topK) : renderOverview(rows)
+}
+
+/** Rough token estimate (chars/4). Exported for metrics/tests. */
+export function estimateTokens(text: string): number {
+	return Math.round(text.length / 4)
+}

package/src/server/server-manager.ts

@@ -0,0 +1,153 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+export function createMcpServerManager(endpoint: string) {
+	let proc: ChildProcess | null = null
+	let starting: Promise<void> | null = null
+	let startedAt: number | null = null
+	let lastError: string | null = null
+	const logs: string[] = []
+
+	const appDir = resolveAppDir()
+	const autoStart = process.env.TLDRAW_MCP_AUTO_START !== 'false' && isLocalEndpoint(endpoint)
+
+	async function ensure(signal?: AbortSignal) {
+		if (await isReachable(endpoint)) return
+		if (!autoStart) {
+			throw new Error(
+				`tldraw MCP server is not reachable at ${endpoint}. Start it manually or unset TLDRAW_MCP_AUTO_START=false.`
+			)
+		}
+		if (starting) return starting
+		starting = startAndWait(signal).finally(() => {
+			starting = null
+		})
+		return starting
+	}
+
+	async function start(signal?: AbortSignal) {
+		if (await isReachable(endpoint)) return
+		if (starting) return starting
+		starting = startAndWait(signal).finally(() => {
+			starting = null
+		})
+		return starting
+	}
+
+	async function startAndWait(signal?: AbortSignal) {
+		if (!existsSync(appDir)) {
+			throw new Error(
+				`tldraw MCP app directory not found: ${appDir}. Set TLDRAW_MCP_APP_DIR to the packaged/local apps/mcp-app directory.`
+			)
+		}
+
+		if (!proc || proc.exitCode !== null || proc.killed) {
+			lastError = null
+			appendLog(`starting: cd ${appDir} && yarn dev`)
+			const child = spawn('yarn', ['dev'], {
+				cwd: appDir,
+				env: { ...process.env },
+				stdio: ['ignore', 'pipe', 'pipe'],
+				detached: true,
+			})
+			proc = child
+			startedAt = Date.now()
+			child.stdout?.on('data', (chunk) => appendLog(String(chunk)))
+			child.stderr?.on('data', (chunk) => appendLog(String(chunk)))
+			child.on('exit', (code, sig) => {
+				appendLog(`process exited: code=${code ?? 'null'} signal=${sig ?? 'null'}`)
+				if (code && code !== 0) lastError = `tldraw MCP server exited with code ${code}`
+			})
+		}
+
+		const started = Date.now()
+		while (Date.now() - started < 180_000) {
+			if (signal?.aborted) throw new Error('Cancelled')
+			if (await isReachable(endpoint)) return
+			if (proc.exitCode !== null) {
+				throw new Error(lastError ?? `tldraw MCP server exited before ${endpoint} became reachable`)
+			}
+			await delay(1000)
+		}
+		throw new Error(`Timed out waiting for tldraw MCP server at ${endpoint}. Recent logs:\n${logs.slice(-20).join('\n')}`)
+	}
+
+	async function restart(signal?: AbortSignal) {
+		await stop()
+		return startAndWait(signal)
+	}
+
+	async function stop() {
+		if (!proc || proc.exitCode !== null || proc.killed) return
+		appendLog('stopping managed server')
+		try {
+			// Kill the process group so the wrangler child exits too.
+			if (proc.pid) process.kill(-proc.pid, 'SIGTERM')
+			else proc.kill('SIGTERM')
+		} catch {
+			proc.kill('SIGTERM')
+		}
+		await delay(1000)
+		if (proc.exitCode === null && !proc.killed) {
+			try {
+				if (proc.pid) process.kill(-proc.pid, 'SIGKILL')
+				else proc.kill('SIGKILL')
+			} catch {
+				proc.kill('SIGKILL')
+			}
+		}
+	}
+
+	function getStatus() {
+		return {
+			endpoint,
+			autoStart,
+			appDir,
+			managedPid: proc?.pid ?? null,
+			startedAt,
+			lastError,
+			logs: logs.slice(-50),
+		}
+	}
+
+	function appendLog(text: string) {
+		for (const line of text.split(/\r?\n/)) {
+			if (!line.trim()) continue
+			logs.push(`${new Date().toISOString()} ${line}`)
+		}
+		while (logs.length > 200) logs.shift()
+	}
+
+	return { ensure, start, restart, stop, getStatus }
+}
+
+async function isReachable(endpoint: string) {
+	try {
+		const response = await fetch(endpoint, {
+			method: 'OPTIONS',
+			signal: AbortSignal.timeout(1500),
+		})
+		return response.ok || response.status === 204 || response.status === 405
+	} catch {
+		return false
+	}
+}
+
+function isLocalEndpoint(endpoint: string) {
+	try {
+		const url = new URL(endpoint)
+		return ['127.0.0.1', 'localhost', '0.0.0.0'].includes(url.hostname)
+	} catch {
+		return false
+	}
+}
+
+function resolveAppDir() {
+	if (process.env.TLDRAW_MCP_APP_DIR) return process.env.TLDRAW_MCP_APP_DIR
+	return fileURLToPath(new URL('../../mcp-app', import.meta.url))
+}
+
+function delay(ms: number) {
+	return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/store/export-store.ts

@@ -0,0 +1,33 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { CanvasExportFormat, CanvasExportScope } from '../canvas/export'
+
+export interface SaveCanvasImageExportInput {
+	canvasId?: string
+	format: CanvasExportFormat
+	scope: CanvasExportScope
+	data: string
+}
+
+export function getExportDir(cwd: string) {
+	return join(cwd, '.pi', 'tldraw-exports')
+}
+
+export function createExportFileName(input: Pick<SaveCanvasImageExportInput, 'canvasId' | 'format' | 'scope'>) {
+	const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+	const canvas = sanitizeFilePart(input.canvasId ?? 'canvas')
+	return `${stamp}-${canvas}-${input.scope}.${input.format}`
+}
+
+export async function saveCanvasImageExport(cwd: string, input: SaveCanvasImageExportInput) {
+	const dir = getExportDir(cwd)
+	await mkdir(dir, { recursive: true })
+	const file = createExportFileName(input)
+	const path = join(dir, file)
+	await writeFile(path, Buffer.from(input.data, 'base64'))
+	return path
+}
+
+function sanitizeFilePart(value: string) {
+	return value.replace(/[^a-zA-Z0-9_-]/g, '_')
+}