DSH OpenPencil

The DeepSeek Harness plugin for OpenPencil — preview, inspect, and edit real .op documents inside a conversation.
_{Exact Multi-Frame Previews • Interactive Canvas • Managed Editor • Agent-Native Design Tools}

_{npm: @zseven-w/dsh-openpencil · Current plugin release: 0.1.0-rc.1 · Tested with DSH 0.1.0-rc.6}

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Français · Español · Deutsch · Português · Русский · हिन्दी · Türkçe · ไทย · Tiếng Việt · Bahasa Indonesia

_{Exact multi-frame .op previews with an interactive canvas and the managed editor workbench}

Why DSH OpenPencil

DSH OpenPencil connects DeepSeek Harness with OpenPencil so an Agent drives a real, editable, interactive design canvas instead of returning a generated image.

🖼️ Exact Multi-Frame Previews The installed OpenPencil headless exporter renders design-faithful previews: the first top-level frame as a large replay-safe PNG, plus a horizontally scrollable thumbnail rail, click-to-select, and previous/next navigation for multi-frame documents.	🗺️ Interactive Canvas "Open interactive canvas" lazily mounts the read-only OpenPencil Web SDK with pan, zoom, and fit — inspect any page, nested node, or inactive page without leaving the conversation.
✏️ Managed Editor With editable: true, the edit action opens the managed OpenPencil editor — selection, layers, properties, drawing tools, undo/redo, and explicit save semantics — in a resizable right-hand workbench with a full-screen option.	🤖 Agent-Native Design Tools Five tools — openpencil_new, openpencil_create, openpencil_edit, openpencil_render, openpencil_selection — let the Agent create, modify, and read a real canvas through transactional batch_design programs.
🔐 Capability-Gated Grants Image and document grants are signed, hash-bound capabilities. Browser metadata never exposes an arbitrary host path, and signed preview/editor capabilities never enter the canonical tool result or model context.	⚡ Transactional Safety A new document is published only after the whole batch_design program succeeds. The tool never overwrites an existing path, a failed batch leaves no empty file behind, and saves use an optimistic hash with atomic replace.
🌍 Follows DSH Look & Feel The tool card and managed editor follow DSH's Chinese/English locale and light/dark theme without reloading the editing session.	🎯 One Complete Workflow "Requirement in conversation → Agent edits the real canvas → live preview and interaction validation → keep iterating" — one loop, no screenshot round-trips.

Install into DSH

Install the public plugin into an authenticated DSH prerelease without installing DSH globally:

npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 \
  dsh plugin --profile web add @zseven-w/dsh-openpencil@latest
npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh web

The OpenPencil plugin is public and requires no npm token. If the DSH prerelease itself requires registry authentication, keep that credential in a user-level or temporary npm config outside the checkout. This repository intentionally contains no registry credentials.

Design Tools

Tool	What it does
openpencil_new	Creates a brand-new .op from one transactional batch_design program, saves it atomically through DSH's sandboxed filesystem, and requires no pre-opened editor.
openpencil_create	Applies a transactional batch_design program to generate or restructure nodes on an existing live canvas.
openpencil_edit	Modifies an explicit node or the single node selected by the user.
openpencil_render	Creates an immutable, content-addressed .op snapshot and renders every top-level frame on the active page — optional scale and editable.
openpencil_selection	Reads the exact nodes selected in the live editor canvas.

Agent Design Workflow

For a natural-language request with no existing document, the Agent should call openpencil_new with a new workspace-relative .op path and the first complete batch_design program. The tool runs that program in a private managed OpenPencil daemon and publishes the authoritative document only after the whole batch succeeds. It never overwrites an existing path and a failed batch leaves no empty file behind. The Agent should then call openpencil_render with the returned path, editable: true, and autoOpen: true to present the gallery and expand the editor once. Replayed or initially-settled historical cards never auto-open.

Use openpencil_create and openpencil_edit only for an existing live canvas. Their edits remain unsaved until the editor Save action.

Rendering Contract

openpencil_render accepts a .op path, an optional scale (0 < scale <= 8, default 1), and optional editable (false by default). Leave width and height unset for the exact OpenPencil path: they describe a runtime viewport, not design export dimensions, and are accepted only by the lower-fidelity Jian fallback.

OpenPencil binary discovery checks, in order:

1. DSH_OPENPENCIL_BINARY or DSH_OPENPENCIL_DESKTOP
2. /Applications/OpenPencil.app/Contents/MacOS/openpencil-desktop
3. ~/Applications/OpenPencil.app/Contents/MacOS/openpencil-desktop
4. openpencil-desktop on PATH

Jian fallback discovery uses DSH_OPENPENCIL_JIAN, a known local release build, then PATH. If the exact OpenPencil binary is genuinely unavailable, Jian may produce a clearly labelled runtime-preview fallback. Exact renderer failures, timeouts, and invalid PNGs do not silently fall back.

Web Viewer Assets

DSH serves only client.js for a client plugin, so the OpenPencil ESM SDK, its WASM, and CanvasKit are staged as explicit same-origin assets:

npm run sync:viewer-assets

The sync command defaults to a sibling ../openpencil checkout. Override it with OPENPENCIL_ROOT or --openpencil-root. A complete prebuilt asset directory can be selected with DSH_OPENPENCIL_VIEWER_SOURCE. Runtime lookup can be overridden with DSH_OPENPENCIL_VIEWER_ASSET_DIR.

Viewer assets are lazy-loaded only after the user opens the canvas. If they are absent or invalid, PNG preview remains available and no canvas button is advertised.

Managed Editor

Editable sessions use OpenPencil's managed web host — the same architecture used by op-vscode. The plugin starts the host only after an authorized user action, keeps the daemon token in memory, validates iframe source and origin, and closes the process when the editor session ends. The editor surface is selected progressively: native Tool details when the host declares that seam, otherwise the plugin's right-hand workbench with resize and full-screen controls.

If DSH reloads or unloads the plugin while the canvas is dirty, the host keeps an opaque local recovery draft for up to seven days. Reopening the same source asks before restoring it into the live canvas; recovery never overwrites the .op file until the user explicitly saves.

Binary and source discovery can be overridden with:

• DSH_OPENPENCIL_EDITOR_BINARY for op-host-web-server;
• DSH_OPENPENCIL_SOURCE_ROOT (or OPENPENCIL_SOURCE_ROOT) for the web bundle and CanvasKit assets.

Saves use an optimistic source hash, an atomic replace, and a successor capability. If the source changes outside the editor, the plugin reports a conflict instead of overwriting it.

Result Metadata

The model-visible result stays plain JSON. Browser-only presentationMeta.$dshOpenPencil carries additive grants for:

• image: PNG path, preview/download URLs, and real width/height;
• frames: every exact-rendered top-level frame in active-page order, including its node id/name/index and signed PNG URLs;
• document: source action path plus immutable snapshot URL, bytes, and SHA-256;
• viewer: revisioned SDK/WASM/CanvasKit URLs when the asset route is attached;
• editor: scoped launch/refresh capabilities when editable: true is authorized.

The result also records renderer, rendererBinary, fidelity, and any warnings. Existing PNG-only schema-v1 messages remain renderable.

DSH 0.1.0-rc.6 does not persist browser presentation metadata for tools nested under PTC/Code Mode. The plugin recovers that UI-only projection through a same-origin, session-bound endpoint: the browser sends only the session id, call id, and immutable document SHA-256, while the host resolves the authoritative result from the durable DSH session log and uses a short-lived in-process marker only to authorize recent live editing. Signed preview/editor capabilities never enter the canonical tool result or model context. Durable history can restore read-only previews; editor grants are issued only for recent, trusted live results.

For bounded replay, nested metadata recovery accepts up to 128 top-level frames; larger Code Mode results remain available through their canonical JSON fallback.

Current Limits

• Follow-up edits to an existing canvas require an already-open managed editor. Changes remain unsaved until the user invokes its Save action.
• The lightweight Web SDK canvas is read-only; full editing uses the separate managed editor surface. On DSH 0.1.0-rc.6, the plugin uses the resizable right workbench with a full-screen option.
• The exact gallery covers top-level frames on the active page; the interactive canvas remains the way to inspect inactive pages and nested nodes.
• Render and snapshot caches still need a product-level retention policy.

Project Structure

dsh-openpencil/
├── src/                       Plugin sources (TypeScript)
│   ├── index.ts               Host plugin entry — Cordis service, tools, assets
│   ├── tool.ts / design-tools.ts / new-tool.ts   Host-side design tools
│   ├── renderer.ts            Exact OpenPencil renderer + Jian fallback
│   ├── editor-host.ts / editor-recovery.ts       Managed editor lifecycle + drafts
│   ├── viewer-assets.ts       Web SDK / WASM / CanvasKit asset staging
│   ├── mcp-client.ts          OpenPencil MCP connection
│   └── client/                Browser client — React workbench, gallery, selection dock
├── lib/                       Compiled output (published to npm)
├── scripts/                   Build helpers — viewer asset sync, client build, host tests
├── tests/                     Node test suites (client, host API, MCP, viewer assets)
├── docs/images/               Documentation screenshots
├── cordis.patch.yml           DSH bundle patch that mounts the plugin
├── tsconfig.json              Host / Node TypeScript config
└── tsconfig.client.json       Browser client TypeScript config

Build and Verify

npm run sync:viewer-assets
npm run build
npm run test:viewer-assets
npm run test:client
npm run test:host -- /absolute/path/to/design.op 375 1091

Builds require Node 24.11 or newer. DSH host/client packages are peer dependencies supplied by the target DSH profile. Build tools are resolved from local dev dependencies, the active linked DSH checkout, or an installed DSH source bundle; DSH_SOURCE_ROOT can select a source checkout explicitly. The lockfile pins standalone public build tooling when that environment is provisioned separately.

For a private DSH prerelease, keep the issued npm credential outside this repository (for example in a user-level or temporary .npmrc) and run the requested version directly:

npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh web

Never commit .npmrc, NPM_TOKEN, or copied registry credentials. This repository ignores local npm configuration by default.

test:host performs a real exact render, validates PNG IHDR geometry and SHA-256, exercises immutable image/document capabilities over HTTP, and checks that viewer assets are grantable. The expected dimensions are fixture-specific.

Ecosystem

DSH OpenPencil is the DeepSeek Harness plugin for OpenPencil — the world's first open-source AI-native vector design tool — and part of the ZSeven-W family of pure-Rust, AI-native tools.

Project	What it is
OpenPencil	The design tool this plugin drives — prompt-to-canvas generation, concurrent agent teams, design-as-code .op files, and a built-in MCP server. The exact previews, interactive canvas, and managed editor here are powered by OpenPencil itself.
agent-rs	A pure-Rust async runtime for shipping LLM agents — multi-provider, tool-capable end-to-end, structured permissions, real MCP, zero unsafe. Powers OpenPencil's built-in agent runtime.
jian	Pure-Rust, GPU-Skia UI framework — widgets, layout, events, and hot reload in one stack. OpenPencil's UI framework, and the source of this plugin's fallback renderer.
Zode	Open-source, AI-native coding assistant for your terminal — reads your code, runs commands, and drives OpenPencil over MCP.
noema	Local-first, non-vector memory system for coding agents — durable memory as inspectable files, works across runtimes.
openpencil-skill	The LLM skill plugin that teaches AI agents how to design with op — a companion to this DSH plugin.

Contributing

Contributions are welcome! Fork and clone, create a branch, run npm run build and the test suites, commit with Conventional Commits, and open a PR against main.

Community

Join our Discord — Ask questions, share designs, suggest features.

Recognized community: LINUX DO

License

MIT — Copyright (c) 2026 ZSeven-W

Third-party components are listed in THIRD_PARTY_NOTICES.md.