Skip to main content

dsh-openpencil

130Stars6Forks2Issues0Watchers

A plugin for previewing, inspecting, and editing OpenPencil `.op` design files in DSH conversations: provides headless precise PNG rendering, read-only interactive canvas, and

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
TypeScript
License
MIT
Branch
main
deepseek-harnessdesigndshdsh-pluginopenpencilpptuiui-design

Install

cmdweb profile
$ dsh plugin --profile web add @zseven-w/dsh-openpencil

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin ZSeven-W/dsh-openpencil for me: review the repository at https://github.com/ZSeven-W/dsh-openpencil first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Line Pitch

dsh-openpencil turns the DSH conversation window into a workspace for previewing, inspecting, and real-time editing of OpenPencil .op design files: Agents can call five tools to render and send transactional design instructions to the canvas, while you directly see PNG thumbnails in chat, a pannable/zoomable read-only canvas, and a sidebar editor with save semantics.

Core Capabilities

  • Headless Precise Rendering: Through openpencil_render, calls OpenPencil's built-in headless exporter to generate fidelity-preserving PNGs for every top-level frame on the active page, outputting SHA-256 and dimension validation results
  • Read-Only Interactive Canvas: Click "Open Interactive Canvas" to on-demand mount the OpenPencil Web SDK, supporting pan, zoom, fit-to-view, allowing inspection of any page or nested nodes without leaving the conversation
  • Hosted Editor: When editable: true, the sidebar workspace launches a standalone op-host-web-server process, providing selection, layers, properties, drawing tools, undo/redo, and explicit save semantics
  • Agent-Native Design Tools: Exposes five tools total — openpencil_new / openpencil_create / openpencil_edit / openpencil_render / openpencil_selection — enabling Agents to create and modify canvases using transactional batch_design programs
  • Signed Capability Credentials: Both render outputs and editor entry points are delivered via HMAC-signed, content-addressed (filename + byte count + SHA-256) capability credentials, keeping host paths from leaking to browser or model context
  • Offline Draft Recovery: When the plugin is uninstalled or the browser disconnects, unsaved canvases are left as opaque records locally for 7 days; reopening the same .op file asks whether to restore, never auto-overwriting source files

Technical Implementation

  • Language: TypeScript (Node-side + browser-side React)
  • Key Dependencies: @deepseek-ai/cordis ^4.0.1, @deepseek-ai/dsh-tools ^0.1.0-rc.6, @deepseek-ai/dsh-fs ^0.1.0-rc.6, react ^18.2.0
  • Architecture Pattern: Cordis plugin + Host/Client dual-end; apply() registers five tools and three same-origin HTTP routes (render, viewer assets, hosted editor) in the Host process; browser-side React components consume presentationMeta.$dshOpenPencil to render PNG cards, galleries, read-only canvas, and sidebar editor
  • Entry Files: src/index.ts (Host-side Cordis service entry) + src/client/index.tsx (browser-side React entry)

Use Cases

Designers, PMs, or frontend developers can directly use natural language in DSH to have an Agent generate an .op design file and verify the preview, modify nodes one by one in the same conversation window; OpenPencil users who want to have their .op files interpreted, modified, or cross-page inspected by an Agent; and any scenario requiring "real-time editable design mockups" embedded in AI conversation flows rather than relying on screenshot roundtrips.

Prerequisites & Compatibility

DependencyMin VersionDescription
DeepSeek Harness>= 0.1.0-rc.6All @deepseek-ai/dsh-* packages in peerDependencies are ^0.1.0-rc.6, also depends on @deepseek-ai/cordis ^4.0.1
Node.js>= 24.11.0Explicitly declared in package.json#engines.node
Operating SystemmacOSPrecise rendering defaults to searching /Applications/OpenPencil.app and ~/Applications/OpenPencil.app (renderer.ts:520-521); Linux/Windows users need to provide OpenPencil binary via DSH_OPENPENCIL_BINARY / PATH
OpenPencil BinaryUndeclared (Optional)Used for "precise" rendering; defaults to automatic fallback to Jian and marks fidelity=runtime-preview when missing
Jian BinaryUndeclared (Optional)Only used as fallback renderer when OpenPencil binary is absent
op-host-web-serverUndeclared (Optional)Launches hosted editor when editable: true; can be specified via DSH_OPENPENCIL_EDITOR_BINARY
Native Node ModulesNonePlugin only uses Node built-in modules and child processes, no node-gyp bindings

Installation

dsh plugin --profile web add github:ZSeven-W/dsh-openpencil

Configuration

All runtime parameters of this plugin are overridden via environment variables as needed, not written to DSH configuration files:

Environment VariablePurposeDefault Behavior
DSH_OPENPENCIL_BINARY / DSH_OPENPENCIL_DESKTOPSpecifies OpenPencil binary path for precise rendering (mostly for Linux/Windows)Auto-searches /Applications/OpenPencil.app and ~/Applications/OpenPencil.app, then falls back to openpencil-desktop in PATH
DSH_OPENPENCIL_JIANSpecifies Jian binary path for fallback renderingSearches ~/workspace/jian/target/release/jian and PATH
DSH_OPENPENCIL_EDITOR_BINARYSpecifies op-host-web-server path for hosted editorSearches target/{release,debug}/op-host-web-server in OpenPencil source root, then PATH and macOS App in order
DSH_OPENPENCIL_SOURCE_ROOT / OPENPENCIL_SOURCE_ROOTSpecifies OpenPencil source root for resolving Web SDK and CanvasKit assetsDefaults to ~/workspace/openpencil
DSH_OPENPENCIL_VIEWER_ASSET_DIRPoints to pre-built read-only canvas asset directory (manifest.json + sdk.js + WASM + CanvasKit)Defaults to reading from built artifact lib/viewer-assets; canvas button won't show when missing
DSH_HOMEDSH user home directory, storage root for render outputs, signing keys, and recovery draftsDefaults to ~/.dsh

FAQ

Q: What happens when I say "help me make an App homepage" in the conversation?

A: The Agent will first call openpencil_new to atomically create a new .op file in the workspace; then use openpencil_render to render it as a PNG card displayed in the conversation, and finally attach editable: true + autoOpen: true to automatically expand the sidebar editor once. The entire process doesn't require you to manually select a filename or open the canvas first.

Q: What to do if rendering fails or gets stuck?

A: Precise rendering has a 60-second hard timeout (renderer.ts:49); the timeout will SIGKILL the child process and throw "OpenPencil render timed out"; PNG header, IHDR, dimensions and byte count are all validated (renderer.ts:863-877), and products exceeding 32 MB are rejected. Fallback rendering (runtime-preview) is only enabled when the OpenPencil binary is completely missing, and it doesn't take the blame for precise rendering failures.

Q: Can I directly modify elements on the canvas in the conversation, or do I need to open the editor?

A: The "read-only canvas" in the browser is read-only for inspection only; to actually modify the design, you must first use openpencil_render with editable: true to open the sidebar editor. The Agent applies changes to the real-time canvas via openpencil_create / openpencil_edit, but saving back to the .op file requires you to click Save in the editor.

Q: Will uninstalling the plugin delete my design files?

A: No. .op files in the workspace are managed by the DSH file system and are independent of the plugin lifecycle; if there are unsaved changes in the editor when uninstalling, the plugin will leave a 7-day local recovery draft on "plugin-dispose", which can be manually restored when reinstalling and opening the same .op file.

Q: How are multi-frame document previews presented?

A: Precise rendering outputs PNGs for all top-level frames on the active page; the frames field in results is ordered by node id/name/index; the browser card displays the first frame as a large image by default with a horizontal thumbnail bar below, supporting click-to-switch. Code Mode results with more than 128 frames only restore nested display metadata for the first 128 frames, with full data falling back to JSON.

Q: Will switching light/dark mode or English/Chinese language interrupt editing?

A: No. When host runtime changes (locale + light/dark theme), the tool cards and sidebar editor will refresh with the theme/language, but editing sessions and unsaved drafts are not lost (editor-panel.tsx listens to editorLocaleFromDsh / EditorColorScheme).

Getting Started Difficulty

Intermediate — The plugin runs with default configuration, but to truly leverage its value, you need write access to the DSH workspace, the OpenPencil (or fallback Jian) binary on your machine, and a basic understanding of the .op document model; regular users only need to know how to trigger the Agent, while developers integrating custom design flows need to understand batch_design syntax and environment variable overrides.

Known Issues & Limitations

  • Precise rendering doesn't support manual width/height specification: passing width / height will directly error; only accepts scale (0 < scale ≤ 8, default 1), please use fallback rendering path for dimension-specific rendering (renderer.ts:687, tool.ts:166-168)
  • Precise rendering has a hard 60-second timeout limit, and the child process will be killed via SIGKILL; oversized .op files (> 64 MB) or output PNGs (> 32 MB / total pixels > 128 million) will be rejected (renderer.ts:39-46, 863-877)
  • The browser read-only canvas is lazily loaded on-demand as a lightweight Web SDK; the rendering-required SDK + WASM + CanvasKit assets must first be synced to lib/viewer-assets via pnpm run sync:viewer-assets; when assets are missing, the canvas button won't appear, but PNG preview still works normally (README.md:159-169, viewer-assets.ts:1-15)
  • The sidebar editor depends on the op-host-web-server standalone process, which needs to be findable in PATH or the source root directory pointed to by environment variables; when not found, the edit button will be in an unavailable state
  • Currently there's no product-level retention policy for render cache and document snapshots, still managed by the system (README.md:205)
  • DSH 0.1.0-rc.6 doesn't persist nested browser display metadata under PTC / Code Mode; the plugin restores via same-origin session-bound endpoints; nested results > 128 frames only display metadata for the first 128 frames, with the rest falling back to JSON (README.md:196-198, presentation-hydration.ts:48)
  • Editor capability credentials have TTL: launch credentials 2 hours, refresh credentials 24 hours; after timeout or external changes to the .op file, you must call openpencil_render again to get new credentials (editor-host.ts:34-36, 858-962)

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/ZSeven-W/dsh-openpencil)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory