pi-tldraw 0.1.0

package/src/canvas/export.ts

@@ -0,0 +1,164 @@
+export type CanvasExportFormat = 'png' | 'svg'
+export type CanvasExportScope = 'selected' | 'all'
+
+export interface CanvasExportCodeOptions {
+	format?: string
+	scope?: string
+	background?: boolean
+	padding?: number
+	scale?: number
+	pixelRatio?: number
+}
+
+export interface CanvasExportPayload {
+	dataUrl: string
+	width: number
+	height: number
+	format: CanvasExportFormat
+	scope: CanvasExportScope
+	exportedShapeIds: string[]
+	selectedCount: number
+	fallbackToAll: boolean
+}
+
+export interface ParsedDataUrl {
+	mimeType: string
+	data: string
+	bytes: number
+}
+
+export function normalizeCanvasExportFormat(format?: string): CanvasExportFormat {
+	const normalized = format?.toLowerCase().trim()
+	return normalized === 'svg' ? 'svg' : 'png'
+}
+
+export function normalizeCanvasExportScope(scope?: string): CanvasExportScope {
+	const normalized = scope?.toLowerCase().trim()
+	return normalized === 'all' ? 'all' : 'selected'
+}
+
+export function buildCanvasExportCode(options: CanvasExportCodeOptions = {}) {
+	const format = normalizeCanvasExportFormat(options.format)
+	const scope = normalizeCanvasExportScope(options.scope)
+	const exportOptions: Record<string, unknown> = {
+		format,
+		background: options.background ?? true,
+	}
+	if (typeof options.pixelRatio === 'number' && Number.isFinite(options.pixelRatio)) {
+		exportOptions.pixelRatio = options.pixelRatio
+	} else if (format === 'png') {
+		exportOptions.pixelRatio = 1
+	}
+	if (typeof options.padding === 'number' && Number.isFinite(options.padding)) exportOptions.padding = options.padding
+	if (typeof options.scale === 'number' && Number.isFinite(options.scale)) exportOptions.scale = options.scale
+
+	return `
+const __piExportScope = ${JSON.stringify(scope)}
+const __piExportFormat = ${JSON.stringify(format)}
+const __piExportOptions = ${JSON.stringify(exportOptions)}
+const __piToTldrawId = (id) => {
+	const value = String(id)
+	return value.startsWith('shape:') ? value : 'shape:' + value
+}
+const __piAllShapeIds = editor.getCurrentPageShapes()
+	.map((shape) => shape.shapeId ?? shape.id)
+	.filter(Boolean)
+	.map(String)
+let __piSelectedShapeIds = []
+try { __piSelectedShapeIds = (editor.getSelectedShapeIds() || []).map(String) } catch { __piSelectedShapeIds = [] }
+const __piFallbackToAll = __piExportScope === 'selected' && __piSelectedShapeIds.length === 0
+const __piFocusedIds = __piExportScope === 'selected' && __piSelectedShapeIds.length > 0 ? __piSelectedShapeIds : __piAllShapeIds
+if (__piFocusedIds.length === 0) throw new Error('No shapes to export.')
+const __piInternalIds = __piFocusedIds.map(__piToTldrawId)
+
+// The mcp-app exec sandbox disables window.setTimeout/setInterval/fetch/XMLHttpRequest
+// while user code runs. tldraw's export pipeline (exportToSvg + getSvgAsImage) needs
+// setTimeout (to unmount the react root on the next tick) and may need fetch (to embed
+// fonts/images). Borrow working globals from a hidden same-origin about:blank iframe and
+// install them on window only for the duration of the export call.
+const __piSandboxFrame = document.createElement('iframe')
+__piSandboxFrame.setAttribute('aria-hidden', 'true')
+__piSandboxFrame.style.cssText = 'width:0;height:0;border:0;position:absolute;left:-9999px;'
+document.body.appendChild(__piSandboxFrame)
+const __piBorrowedWindow = __piSandboxFrame.contentWindow
+const __piPriorSetTimeout = window.setTimeout
+const __piPriorSetInterval = window.setInterval
+const __piPriorFetch = window.fetch
+const __piPriorXHR = window.XMLHttpRequest
+try {
+	window.setTimeout = __piBorrowedWindow.setTimeout.bind(__piBorrowedWindow)
+	window.setInterval = __piBorrowedWindow.setInterval.bind(__piBorrowedWindow)
+	window.fetch = __piBorrowedWindow.fetch.bind(__piBorrowedWindow)
+	window.XMLHttpRequest = __piBorrowedWindow.XMLHttpRequest
+
+	// The focused editor proxy marks toImageDataUrl with ret:'this', so a direct call
+	// returns the proxy instead of the image result. Install a temp method on the real
+	// editor; the proxy invokes it via value.apply(target, args) with this === the real
+	// editor, so this.toImageDataUrl reaches the genuine implementation and its return
+	// value flows back untouched.
+	const __piMethodName = '__piExportImage_' + Math.random().toString(36).slice(2)
+	editor[__piMethodName] = async function(ids, opts) {
+		return await this.toImageDataUrl(ids, opts)
+	}
+	try {
+		const __piImage = await editor[__piMethodName](__piInternalIds, __piExportOptions)
+		return {
+			dataUrl: __piImage.url,
+			width: __piImage.width,
+			height: __piImage.height,
+			format: __piExportFormat,
+			scope: __piExportScope,
+			exportedShapeIds: __piFocusedIds,
+			selectedCount: __piSelectedShapeIds.length,
+			fallbackToAll: __piFallbackToAll,
+		}
+	} finally {
+		try { delete editor[__piMethodName] } catch {}
+	}
+} finally {
+	window.setTimeout = __piPriorSetTimeout
+	window.setInterval = __piPriorSetInterval
+	window.fetch = __piPriorFetch
+	window.XMLHttpRequest = __piPriorXHR
+	__piSandboxFrame.remove()
+}
+`
+}
+
+export function parseCanvasExportPayload(value: unknown): CanvasExportPayload {
+	if (!value || typeof value !== 'object') throw new Error('Canvas export did not return an object.')
+	const record = value as Record<string, unknown>
+	if (typeof record.dataUrl !== 'string') throw new Error('Canvas export did not return a data URL.')
+	if (typeof record.width !== 'number' || typeof record.height !== 'number') {
+		throw new Error('Canvas export did not return image dimensions.')
+	}
+	return {
+		dataUrl: record.dataUrl,
+		width: record.width,
+		height: record.height,
+		format: normalizeCanvasExportFormat(typeof record.format === 'string' ? record.format : undefined),
+		scope: normalizeCanvasExportScope(typeof record.scope === 'string' ? record.scope : undefined),
+		exportedShapeIds: Array.isArray(record.exportedShapeIds)
+			? record.exportedShapeIds.map(String)
+			: [],
+		selectedCount: typeof record.selectedCount === 'number' ? record.selectedCount : 0,
+		fallbackToAll: record.fallbackToAll === true,
+	}
+}
+
+export function parseDataUrl(dataUrl: string): ParsedDataUrl {
+	const match = dataUrl.match(/^data:([^;,]+)(;base64)?,(.*)$/s)
+	if (!match) throw new Error('Invalid image data URL returned by canvas export.')
+	const mimeType = match[1]
+	const isBase64 = Boolean(match[2])
+	const payload = match[3]
+	const data = isBase64 ? payload : Buffer.from(decodeURIComponent(payload), 'utf8').toString('base64')
+	return { mimeType, data, bytes: Buffer.byteLength(data, 'base64') }
+}
+
+export function formatBytes(bytes: number) {
+	if (bytes < 1024) return `${bytes} B`
+	const kib = bytes / 1024
+	if (kib < 1024) return `${kib.toFixed(1)} KiB`
+	return `${(kib / 1024).toFixed(1)} MiB`
+}

package/src/canvas/state.ts

@@ -0,0 +1,117 @@
+import type { CanvasBundle } from '../semantic/layer'
+
+export type CanvasStateBundle = {
+	shapes: unknown[]
+	assets?: unknown[]
+	bindings?: unknown[]
+	selectedIds?: unknown[]
+}
+
+export type SceneLens = 'all' | 'selected'
+
+export const INITIALIZE_CANVAS_CODE = 'return { initialized: true }'
+
+export const READ_CANVAS_STATE_CODE = `
+const shapes = editor.getCurrentPageShapes()
+const assets = typeof editor.getAssets === 'function' ? editor.getAssets() : []
+let bindings = []
+try {
+	for (const shape of shapes) {
+		const shapeId = shape.shapeId ?? shape.id
+		if (!shapeId || typeof editor.getBindingsFromShape !== 'function') continue
+		const shapeBindings = editor.getBindingsFromShape(shapeId, 'arrow') ?? []
+		bindings.push(...shapeBindings)
+	}
+} catch {
+	bindings = []
+}
+let selectedIds = []
+try { selectedIds = (editor.getSelectedShapeIds() || []).map((id) => String(id)) } catch { selectedIds = [] }
+return { shapes, assets, bindings, selectedIds }
+`
+
+export function summarizeSnapshot(snapshot: { shapes?: unknown[]; assets?: unknown[]; bindings?: unknown[] }) {
+	const shapeCount = Array.isArray(snapshot.shapes) ? snapshot.shapes.length : 0
+	const assetCount = Array.isArray(snapshot.assets) ? snapshot.assets.length : 0
+	const bindingCount = Array.isArray(snapshot.bindings) ? snapshot.bindings.length : 0
+	return `${shapeCount} shape(s), ${assetCount} asset(s), ${bindingCount} binding(s)`
+}
+
+export const normalizeShapeId = (id: unknown): string | null =>
+	id == null ? null : String(id).replace(/^shape:/, '')
+
+export function shapeIdOf(shape: unknown): string | null {
+	if (!shape || typeof shape !== 'object') return null
+	const record = shape as Record<string, unknown>
+	return normalizeShapeId(record.shapeId ?? record.id)
+}
+
+export function bindingTouchesSelection(binding: unknown, selectedIds: ReadonlySet<string>): boolean {
+	if (!binding || typeof binding !== 'object') return false
+	const record = binding as Record<string, unknown>
+	return [record.fromId, record.toId].some((id) => {
+		const normalized = normalizeShapeId(id)
+		return normalized != null && selectedIds.has(normalized)
+	})
+}
+
+export function applySceneLens(bundle: CanvasStateBundle, lens: SceneLens): CanvasStateBundle {
+	if (lens === 'all') return bundle
+
+	const selectedIds = selectedIdSet(bundle.selectedIds)
+	return {
+		...bundle,
+		shapes: bundle.shapes.filter((shape) => {
+			const id = shapeIdOf(shape)
+			return id != null && selectedIds.has(id)
+		}),
+		bindings: Array.isArray(bundle.bindings)
+			? bundle.bindings.filter((binding) => bindingTouchesSelection(binding, selectedIds))
+			: bundle.bindings,
+		selectedIds: [...selectedIds],
+	}
+}
+
+export const selectedIdSet = (selectedIds: unknown): ReadonlySet<string> =>
+	new Set(
+		(Array.isArray(selectedIds) ? selectedIds : [])
+			.map((id) => normalizeShapeId(id))
+			.filter((id): id is string => id != null)
+	)
+
+export function asCanvasBundle(bundle: CanvasStateBundle): CanvasBundle {
+	return {
+		shapes: bundle.shapes as CanvasBundle['shapes'],
+		assets: bundle.assets,
+		bindings: bundle.bindings,
+	}
+}
+
+export function toRawCanvasState(bundle: CanvasStateBundle) {
+	return {
+		shapes: bundle.shapes,
+		assets: bundle.assets ?? [],
+		bindings: bundle.bindings ?? [],
+	}
+}
+
+export function restoreCanvasCode(snapshot: { shapes?: unknown[] }) {
+	const shapes = Array.isArray(snapshot.shapes) ? snapshot.shapes : []
+	return `
+const snapshotShapes = ${JSON.stringify(shapes)}
+const currentShapes = editor.getCurrentPageShapes()
+const currentIds = currentShapes.map((shape) => shape.shapeId ?? shape.id).filter(Boolean)
+if (currentIds.length) editor.deleteShapes(currentIds)
+const nonArrows = snapshotShapes.filter((shape) => (shape._type ?? shape.type) !== 'arrow')
+const arrows = snapshotShapes.filter((shape) => (shape._type ?? shape.type) === 'arrow')
+for (const shape of nonArrows) editor.createShape(shape)
+for (const shape of arrows) editor.createShape(shape)
+const restoredIds = snapshotShapes.map((shape) => shape.shapeId ?? shape.id).filter(Boolean)
+if (restoredIds.length) {
+	editor.select(...restoredIds)
+	editor.zoomToSelection()
+	editor.selectNone()
+}
+return { restored: snapshotShapes.length, shapeIds: restoredIds }
+`
+}

package/src/canvas/workflow.ts

@@ -0,0 +1,105 @@
+import {
+	INITIALIZE_CANVAS_CODE,
+	READ_CANVAS_STATE_CODE,
+	restoreCanvasCode,
+	summarizeSnapshot,
+	type CanvasStateBundle,
+} from './state'
+import { extractReturnValue, extractTextContent, parseCanvasIdFromText, type McpToolResult } from '../mcp/response'
+import type { StoredCanvasSnapshot } from '../store/project-store'
+
+export type CanvasHostPort = {
+	open(signal?: AbortSignal): Promise<{ url: string; spawned: boolean }>
+	execOnCanvas(
+		input: { code: string; canvasId?: string; timeoutMs?: number },
+		signal?: AbortSignal
+	): Promise<unknown>
+	getStatus(): { url: string | null; browserConnected: boolean }
+}
+
+export type CanvasWorkflowDeps = {
+	canvasHost: CanvasHostPort
+	loadCanvasSnapshot(cwd: string, canvasId?: string): Promise<StoredCanvasSnapshot | null>
+	saveCanvasSnapshot(
+		cwd: string,
+		canvasId: string,
+		state: { shapes?: unknown[]; assets?: unknown[]; bindings?: unknown[] },
+		opts?: { allowEmptyOverwrite?: boolean }
+	): Promise<StoredCanvasSnapshot>
+	resolveCanvasId(cwd: string, explicitCanvasId?: string): Promise<string | undefined>
+	rememberCanvasId(cwd: string, canvasId: string): Promise<void>
+	createProjectCanvasId(): string
+}
+
+export function createCanvasWorkflows(deps: CanvasWorkflowDeps) {
+	return {
+		async ensureBrowserAndRestore(
+			cwd: string,
+			canvasId: string | undefined,
+			signal?: AbortSignal,
+			opts: { restore?: boolean } = {}
+		) {
+			const { url, spawned } = await deps.canvasHost.open(signal)
+			let resolvedId = await deps.resolveCanvasId(cwd, canvasId)
+			let restoreText = spawned
+				? 'No project canvas restored.'
+				: 'Browser already open; live canvas unchanged.'
+
+			if (spawned && opts.restore !== false) {
+				if (!resolvedId) resolvedId = deps.createProjectCanvasId()
+				const snapshot = await deps.loadCanvasSnapshot(cwd, resolvedId)
+				if (snapshot) {
+					await deps.canvasHost.execOnCanvas(
+						{ code: restoreCanvasCode(snapshot), canvasId: snapshot.canvasId },
+						signal
+					)
+					await deps.rememberCanvasId(cwd, snapshot.canvasId)
+					restoreText = `Restored project canvas ${snapshot.canvasId} (${summarizeSnapshot(snapshot)}). Autosave is on.`
+				} else {
+					await deps.canvasHost.execOnCanvas(
+						{ code: INITIALIZE_CANVAS_CODE, canvasId: resolvedId },
+						signal
+					)
+					await deps.rememberCanvasId(cwd, resolvedId)
+					restoreText = `Started new project canvas ${resolvedId}. Autosave is on.`
+				}
+			}
+
+			return { url, spawned, resolvedId, restoreText }
+		},
+
+		async snapshotLiveCanvas(
+			cwd: string,
+			canvasId: string | undefined,
+			signal?: AbortSignal,
+			opts?: { allowEmptyOverwrite?: boolean }
+		) {
+			const hostStatus = deps.canvasHost.getStatus()
+			if (!hostStatus.browserConnected) {
+				throw new Error(
+					`No live browser canvas is connected. Open the canvas tab with /tldraw open, wait for "Canvas ready", then save again. Host: ${hostStatus.url ?? 'not started'}`
+				)
+			}
+			const result = (await deps.canvasHost.execOnCanvas(
+				{ code: READ_CANVAS_STATE_CODE, canvasId, timeoutMs: 60_000 },
+				signal
+			)) as McpToolResult
+			const text = extractTextContent(result)
+			const returnedCanvasId = parseCanvasIdFromText(text) ?? canvasId
+			if (!returnedCanvasId) throw new Error('Could not determine canvasId from live canvas read.')
+			const state = (result.structuredContent ?? extractReturnValue(result) ?? {}) as Partial<CanvasStateBundle>
+			const saved = await deps.saveCanvasSnapshot(
+				cwd,
+				returnedCanvasId,
+				{
+					shapes: Array.isArray(state.shapes) ? state.shapes : [],
+					assets: Array.isArray(state.assets) ? state.assets : [],
+					bindings: Array.isArray(state.bindings) ? state.bindings : [],
+				},
+				{ allowEmptyOverwrite: opts?.allowEmptyOverwrite }
+			)
+			await deps.rememberCanvasId(cwd, returnedCanvasId)
+			return saved
+		},
+	}
+}

package/src/commands/tldraw-command.ts

@@ -0,0 +1,48 @@
+const TLDRAW_COMMAND_TYPES = [
+	'reset',
+	'current',
+	'canvases',
+	'save',
+	'start',
+	'restart',
+	'tools',
+	'open',
+	'host',
+	'resource',
+	'status',
+] as const
+
+export type TldrawCommandType = (typeof TLDRAW_COMMAND_TYPES)[number]
+
+export type ParsedTldrawCommand = {
+	type: TldrawCommandType
+	force: boolean
+	canvasId?: string
+	requestedAction?: string
+}
+
+const COMMANDS: ReadonlySet<string> = new Set(TLDRAW_COMMAND_TYPES)
+
+export function parseTldrawCommand(args: string): ParsedTldrawCommand {
+	const parts = args.trim().split(/\s+/).filter(Boolean)
+	const rawAction = parts[0] ?? 'status'
+	const force = rawAction.endsWith('!') || parts.includes('--force')
+	const normalizedAction = rawAction.endsWith('!') ? rawAction.slice(0, -1) : rawAction
+	const canvasId = parts.slice(1).find((part) => !part.startsWith('--'))
+
+	return isTldrawCommandType(normalizedAction)
+		? withOptionalCanvasId({ type: normalizedAction, force }, canvasId)
+		: withOptionalCanvasId(
+			{ type: 'status', force, requestedAction: normalizedAction },
+			canvasId
+		)
+}
+
+const isTldrawCommandType = (value: string): value is TldrawCommandType => COMMANDS.has(value)
+
+function withOptionalCanvasId<T extends Omit<ParsedTldrawCommand, 'canvasId'>>(
+	command: T,
+	canvasId: string | undefined
+): T | (T & { canvasId: string }) {
+	return canvasId ? { ...command, canvasId } : command
+}

package/src/diagram/guidance.ts

@@ -0,0 +1,44 @@
+export interface DiagramGuidanceOptions {
+	focus?: string
+}
+
+export interface DiagramGuidance {
+	focus?: string
+	text: string
+}
+
+export function normalizeFocus(focus?: string) {
+	const value = focus?.trim()
+	return value ? value : undefined
+}
+
+export function buildDiagramGuidance(options: DiagramGuidanceOptions = {}): DiagramGuidance {
+	const focus = normalizeFocus(options.focus)
+	const lines = ['# tldraw drawing guidance', '']
+
+	if (focus) lines.push(`Focus: ${focus}`, '')
+
+	lines.push(
+		'## One rule',
+		'',
+		'Draw for legibility: make space do the explanatory work.',
+		'',
+		'## Ideas while drawing',
+		'',
+		'- Begin with the relationship the viewer should understand, then place shapes so that relationship is visible before any label is read.',
+		'- Use negative space deliberately. Leave breathing room around shapes, groups, arrow paths, and labels.',
+		'- Prefer simple alignment over clever geometry. Order and rhythm make diagrams easier to scan.',
+		'- Let grouping emerge from spacing and containment, not from crowding.',
+		'- Route connections through open space. If a connector competes with another mark, move the shapes rather than forcing the line.',
+		'- Keep labels short and readable. Put explanatory text where it does not interrupt the drawing.',
+		'- Use visual weight sparingly. Color, fill, and shape should clarify attention, not decorate every element.',
+		'',
+		'## Finish by looking, not explaining',
+		'',
+		'- Step back and inspect the canvas as a reader.',
+		'- Ask what feels cramped, ambiguous, or noisy.',
+		'- Add space, simplify marks, or reposition elements until the relationships can breathe.'
+	)
+
+	return { focus, text: lines.join('\n') }
+}