dsh-tldraw-canvas

dsh-tldraw-canvas

English | 中文

A DeepSeek Harness Desktop plugin that gives every Session its own tldraw canvas in the right sidebar. This build uses the original MIT-licensed tldraw v1 (2021–2022) instead of the commercially licensed tldraw 5 SDK, so there is no license key, no watermark, and no production gate.

The canvas autosaves into the Session's project directory — the directory the Workspace groups the Session under — so it travels with the workspace instead of living in browser storage.

Install

git clone https://github.com/amumulam/dsh-tldraw-canvas.git

Install the checked-out directory as a DSH bundle (Plugin Manager → install from folder, or install_bundle with its absolute path). client.js is prebuilt, so the installed copy does not need node_modules.

Use

1. Open the right sidebar for a Session.
2. Add a tab from the guide and choose Tldraw Canvas / Tldraw 画板.
3. Draw. Changes save automatically after a short pause, and again when the tab closes.

The status bar shows the save state and the workspace-relative file path.

Reading a canvas (Agent tool)

The Host half now owns the read path instead of leaving it to ad-hoc filesystem scripts. It registers the tldrawCanvas service and exposes it to agents as:

tldraw_read_canvas

Arguments:

• session_id — optional; defaults to the calling Session
• include_preview — default true; renders a PNG preview

The tool returns a normalized summary (format, shape/stroke/text counts, point count, bounds, per-shape details) plus the preview image, so an agent can answer “what is on my canvas?” without reading the JSON file manually. It accepts both the new v1 documents and legacy v5 snapshots.

Other Host plugins can inject tldrawCanvas and call:

const analysis = await ctx.tldrawCanvas.inspect(sessionId);
const { analysis, png } = await ctx.tldrawCanvas.render(sessionId);

inspect and render are read-only; configure/write access stays with the canvas tab and its autosave.

Workspace vs Session cwd

DSH's Workspace is a registry entry: a named directory plus the Sessions grouped under the directory they were created in. It is not an artifact bucket, and removing a Workspace never deletes its folder, files, or Session history.

A Session has two directory notions:

• Project origin — immutable SessionHeader.cwd. Workspace grouping and archived-Session reads are keyed from this path.
• Effective working directory — may move later through the working_directory tool. Agent tools write there, while existing shells keep their own process-local directories.

The canvas is anchored to the project origin, not the transient effective cwd. That way a cd inside one Session cannot split its drawings across directories, and a live Session and its archived replay read the same file. Use a separate Session in another directory for a separate canvas.

Where it saves

/.dsh/tldraw/.json

The Host resolves the Session's project directory itself, so the browser cannot choose an arbitrary path. Each canvas is written atomically and survives app restarts and Session switching.

Legacy v5 drawings

The first release of this plugin used tldraw 5. On the first v1 save of an old file, the Host copies the original next to it:

.dsh/tldraw/.v5.json

The client detects a v5 snapshot, converts freehand draw shapes to v1 points, and shows a 已迁移旧画板 / Legacy canvas migrated badge. Other v5 shape types are not converted; the badge tooltip reports how many were skipped. The .v5.json backup is never deleted by the plugin.

Implementation

• index.js — Host half: registers GET/PUT /api/tldraw, resolves the Session's cwd, reads/writes atomically, and backs up legacy v5 files.
• src/client-entry.js — Client half: registers the tldraw tab type, guide card, theme-aware editor, and debounced autosave.
• src/migrate.js — v5 draw-segment decoding and v5 → v1 document conversion.
• src/canvas-model.js — format-neutral analysis and the dependency-free PNG preview renderer.
• client.js — generated bundle.

Similar DSH plugins

There are several community drawing/canvas plugins; the closest ones differ in editor, storage, and agent surface:

Project	Editor	Where it lives	Persistence	Agent tools
johappel/dsh-tldraw (package dsh-whiteboard)	tldraw 5	right sidebar tab	workspace-level snapshot store	9 whiteboard tools
zhang-guo-wen/dsh-whiteboard	draw.io	main gallery + sidebar editor	plugin files/ directory	editor-oriented
Jegozhou/dsh-excalidraw	Excalidraw 0.18	main panel	DSH_HOME/excalidraw/drawings	5 typed scene tools
CSlawyer1985/dsh-excalidraw-board	excalidraw.com iframe	floating overlay	upstream site	none local
lb-aigc/dsh-canvas	React Flow node canvas	right sidebar + conversation	session projection	5 node tools

dsh-tldraw-canvas is intentionally different: it uses the MIT tldraw v1 editor, stores one file per Session inside that Session's project directory, and exposes a read-only summary + PNG preview tool rather than a collaborative editing toolset.

Why tldraw v1

The current tldraw 5 SDK is source-available but requires a commercial/trial/hobby license key in production. The original tldraw v1 is MIT, but it is no longer maintained (last release 1.29.2, 2022). This plugin intentionally trades modern features and maintenance for a genuinely open-source editor.

Development

npm install
npm run build

npm run build regenerates client.js from src/client-entry.js.

Tests

node --test test/*.test.mjs

The tests cover the Host API's read/write contract, invalid and concurrent requests, malformed files, temporary-file cleanup, legacy v5 backup, v5 paint-point decoding, v5 → v1 conversion, the reusable read service, and the agent tool's summary/image envelope.

Disclaimer

This is an independent community plugin. tldraw is a trademark of tldraw Inc.; this project is not affiliated with or endorsed by tldraw Inc. The bundled tldraw v1 code remains under its MIT license (see THIRD_PARTY_NOTICES.md).