@zseven-w/dsh-openpencil 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZSeven—W
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# DSH OpenPencil
+
+DeepSeek Harness plugin for previewing and editing OpenPencil `.op` documents inside a conversation.
+
+![DSH OpenPencil multi-frame preview and sidebar editor](docs/images/dsh-openpencil-overview.png)
+
+## 项目介绍
+
+**中文**
+
+DSH OpenPencil 是连接 DeepSeek Harness 与 OpenPencil 的智能设计插件，目标是让 Agent 直接驱动真实、可编辑、可交互的设计画布，而不是只返回一张生成图片。它支持在对话中渲染和浏览多页面 `.op` 设计稿，一键进入可缩放画布或完整编辑器（在支持的未来 DSH 中可使用原生右侧详情栏；当前发布的 rc.2 至 0.1.0-rc.6 自动使用插件自有的可缩放右侧工作台，并可切换全屏），继续使用 OpenPencil 的图层、属性、绘制、组件、交互和多类模板能力，快速创建 App 页面、演示文稿、社交媒体内容、信息图等不同类型的设计；同时让 DeepSeek Harness 中的 Agent 理解画布结构、节点、选区、组件关系与交互逻辑，直接调用模板、生成页面、修改组件、调整布局、编排交互、检查视觉质量并保存结果，把“对话提出需求—Agent 操作真实画布—实时预览与交互验证—继续迭代”整合成一条完整设计工作流。
+
+**English**
+
+DSH OpenPencil is an intelligent design plugin that connects DeepSeek Harness with OpenPencil. Its goal is to let an Agent directly operate a real, editable, and interactive design canvas instead of returning only a generated image. It can render and browse multi-page `.op` designs inside a conversation, then open them in a zoomable canvas or the full editor. A future host with the proposed native Tool-details seam can use DSH's right-hand details panel; published releases from rc.2 through 0.1.0-rc.6 use the plugin's resizable right-hand workbench, which can also switch to full screen. From there, users retain OpenPencil's layers, properties, drawing tools, components, interactions, and broad template library for creating app screens, presentations, social media content, infographics, and more. At the same time, the Agent can understand the canvas structure, nodes, selections, component relationships, and interaction logic; invoke templates; generate pages; modify components; adjust layouts; orchestrate interactions; inspect visual quality; and save the result. This brings requirement gathering, direct Agent-driven canvas editing, live preview and interaction validation, and continued iteration into one complete design workflow.
+
+## What works
+
+- `openpencil_render` creates an immutable, content-addressed `.op` snapshot and renders every top-level frame on the active page.
+- `openpencil_selection` reads the exact nodes selected in the live editor canvas.
+- `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 OpenPencil `batch_design` program to generate or restructure canvas nodes.
+- `openpencil_edit` modifies an explicit node or the single node selected by the user.
+- OpenPencil's installed headless exporter is the default, design-fidelity renderer.
+- The tool card shows the first top-level frame as a large replay-safe PNG. Multi-frame documents add a horizontally scrollable thumbnail rail, click-to-select, and previous/next navigation.
+- The large preview supports manual zoom, reset, fit-frame, and fit-content modes.
+- “Open interactive canvas” lazily mounts the read-only OpenPencil Web SDK. The canvas supports pan, zoom, and fit.
+- With `editable: true`, the edit action opens the managed OpenPencil editor with selection, layers, properties, drawing tools, undo/redo, and explicit save semantics. Published DSH releases through 0.1.0-rc.6 use a resizable plugin-owned right workbench; smaller viewports use full screen automatically.
+- The tool card and managed editor follow DSH's Chinese/English locale and light/dark theme without reloading the editing session.
+- Image and document grants are signed, hash-bound capabilities. Browser metadata does not expose an arbitrary host 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.
+
+The read-only Web SDK viewer and the managed editor are intentionally separate paths. Only one Web SDK viewer and one managed editor are active at a time because their current browser hosts own page-wide render pumps. “Edit source .op” remains available as a direct DSH file action.
+
+## Install into DSH
+
+Install the public plugin into an authenticated DSH prerelease without installing DSH globally:
+
+```sh
+npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 \
+  dsh plugin --profile web add @zseven-w/dsh-openpencil
+npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh web
+```
+
+Keep the private registry credential in a user-level or temporary npm config outside the checkout. This repository intentionally contains no registry credentials.
+
+## 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`.
+
+## 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:
+
+```sh
+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.
+
+## Build and verify
+
+```sh
+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:
+
+```sh
+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.
+
+## 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.
+
+Published DSH releases through 0.1.0-rc.6 do 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.
+
+## 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.
+
+## 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. Published releases through 0.1.0-rc.6 use 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.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,69 @@
+# Third-Party Notices
+
+This distribution includes the following third-party components.
+
+## OpenPencil Web SDK 0.8.4
+
+- Files: `lib/viewer-assets/sdk.js`, `lib/viewer-assets/op_web_sdk_bg.wasm`
+- Source: https://github.com/ZSeven-W/openpencil
+- License: MIT
+
+```text
+MIT License
+
+Copyright (c) 2026 ZSeven—W
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## CanvasKit (`canvaskit-wasm` 0.40.0)
+
+- Files: `lib/viewer-assets/canvaskit/canvaskit.js`, `lib/viewer-assets/canvaskit/canvaskit.wasm`
+- Source: https://www.npmjs.com/package/canvaskit-wasm/v/0.40.0
+- License: BSD-3-Clause
+
+```text
+Copyright (c) 2011 Google Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-openpencil bundle patch: mounts the plugin into a profile layer stack.
+# The profile's own cordis.patch.yml and any --patch overlays still apply
+# after this layer; rows here can be overridden by id in later layers.
+- insert:
+    - id: dsh-openpencil
+      name: '@zseven-w/dsh-openpencil'

package/lib/client/details-compat.d.ts

@@ -0,0 +1,28 @@
+/** Compatibility boundary for future DSH builds that add a keyed Tool-details seam. */
+import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client';
+import type { DetailsToolOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+/**
+ * Published DSH rc.2 through 0.1.0-rc.6 do not declare this slot. Keeping the
+ * proposed additive contract local lets a future supporting host activate the
+ * native surface without breaking current hosts. At runtime `slots.inject()`
+ * waits while a slot is absent, so current releases use the plugin workbench.
+ */
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        'tool.details.toolview': {
+            kind: 'keyed';
+            scope: 'session';
+            owner: DetailsToolOwnerProps;
+        };
+    }
+}
+/** Details props without importing a symbol absent from current DSH releases. */
+export type CompatibleToolDetailsViewProps = PropsRuntime<'tool.details.toolview'>;
+/** Call props with a possible future additive sidebar capability. */
+export type CompatibleToolCallViewProps = ToolCallViewProps & {
+    openDetails?: (() => void) | undefined;
+};
+export type OpenPencilEditorSurface = 'details' | 'modal';
+/** Prefer the native resident details panel and otherwise open our own modal. */
+export declare function requestOpenPencilEditor(openDetails: (() => void) | undefined, openModal: () => void): OpenPencilEditorSurface;

package/lib/client/details-compat.js

@@ -0,0 +1,10 @@
+/** Compatibility boundary for future DSH builds that add a keyed Tool-details seam. */
+/** Prefer the native resident details panel and otherwise open our own modal. */
+export function requestOpenPencilEditor(openDetails, openModal) {
+    if (openDetails !== undefined) {
+        openDetails();
+        return 'details';
+    }
+    openModal();
+    return 'modal';
+}

package/lib/client/editor-bridge.d.ts

@@ -0,0 +1,84 @@
+/** Browser-side protocol helpers for the managed OpenPencil editor iframe. */
+export type EditorInboundMessage = {
+    type: 'op-bridge/ready';
+    generation: number;
+    revision: number;
+} | {
+    type: 'op-bridge/opened';
+    generation: number;
+} | {
+    type: 'op-bridge/dirty-changed';
+    generation: number;
+    revision: number;
+    dirty: boolean;
+} | {
+    type: 'op-bridge/snapshot-result';
+    requestId: string;
+    docJson: string;
+    generation: number;
+    revision: number;
+} | {
+    type: 'op-bridge/snapshot-conflict';
+    requestId: string;
+    serverVersion: number;
+} | {
+    type: 'op-bridge/sync-conflict';
+    generation: number;
+    revision: number;
+    serverVersion: number;
+} | {
+    type: 'op-bridge/conflict-resolved';
+    requestId: string;
+} | {
+    type: 'op-shell/save';
+} | {
+    type: 'op-shell/copy';
+    text: string;
+};
+export type EditorOutboundMessage = {
+    type: 'op-bridge/init';
+    token: string;
+    mcpUrl?: string;
+} | {
+    type: 'op-bridge/theme';
+    colorScheme: EditorColorScheme;
+} | {
+    type: 'op-bridge/locale';
+    locale: EditorLocale;
+} | {
+    type: 'op-bridge/open-document';
+    json: string;
+} | {
+    type: 'op-bridge/snapshot';
+    purpose: 'save';
+    requestId: string;
+} | {
+    type: 'op-bridge/save-committed';
+    generation: number;
+    revision: number;
+};
+export type EditorColorScheme = 'light' | 'dark';
+export type EditorLocale = 'zh-CN' | 'en-US';
+/** Parse only the editor/host messages DSH implements. Unknown traffic is ignored. */
+export declare function parseEditorInbound(raw: unknown): EditorInboundMessage | undefined;
+export declare function encodeEditorOutbound(message: EditorOutboundMessage): string;
+/** Require an absolute loopback editor URL and derive its exact target origin. */
+export declare function editorOrigin(iframeUrl: string): string;
+/** Pin the host's resolved theme into the editor's first navigation. */
+export declare function editorIframeUrlWithTheme(iframeUrl: string, colorScheme: EditorColorScheme): string;
+/** Pin the host's resolved locale into the editor's first navigation. */
+export declare function editorIframeUrlWithLocale(iframeUrl: string, locale: EditorLocale): string;
+/** Translate DSH's compact locale id to the editor's BCP 47 contract. */
+export declare function editorLocaleFromDsh(locale: 'zh' | 'en'): EditorLocale;
+/** Resolve a launch/save/close capability and reject cross-origin control routes. */
+export declare function editorControlUrl(raw: string, base?: string): string;
+/** Validate source and exact origin before parsing any iframe message. */
+export declare function editorMessageFrom(event: Pick<MessageEvent, 'source' | 'origin' | 'data'>, frameWindow: Window | null, origin: string): EditorInboundMessage | undefined;
+/** Read-only gate for background auto-open flows; never asks an owner to close. */
+export declare function hasActiveEditor(): boolean;
+/** Page-wide single-editor coordinator. An existing dirty editor may veto takeover. */
+export declare function claimEditor(token: symbol, close: () => boolean | void, options?: {
+    replace?: boolean;
+}): (() => void) | undefined;
+/** Confirm before a user-driven panel close would discard unsaved canvas edits. */
+export declare function confirmEditorClose(dirty: boolean, confirm?: ((message?: string) => boolean) & typeof globalThis.confirm): boolean;

package/lib/client/editor-bridge.js

@@ -0,0 +1,127 @@
+/** Browser-side protocol helpers for the managed OpenPencil editor iframe. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function safeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function string(value) {
+    return typeof value === 'string';
+}
+/** Parse only the editor/host messages DSH implements. Unknown traffic is ignored. */
+export function parseEditorInbound(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value) || typeof value.type !== 'string')
+        return undefined;
+    switch (value.type) {
+        case 'op-bridge/ready':
+            return safeInteger(value.generation) && safeInteger(value.revision)
+                ? { type: value.type, generation: value.generation, revision: value.revision }
+                : undefined;
+        case 'op-bridge/opened':
+            return safeInteger(value.generation) ? { type: value.type, generation: value.generation } : undefined;
+        case 'op-bridge/dirty-changed':
+            return safeInteger(value.generation) && safeInteger(value.revision) && typeof value.dirty === 'boolean'
+                ? { type: value.type, generation: value.generation, revision: value.revision, dirty: value.dirty }
+                : undefined;
+        case 'op-bridge/snapshot-result':
+            return string(value.requestId) && string(value.docJson)
+                && safeInteger(value.generation) && safeInteger(value.revision)
+                ? {
+                    type: value.type,
+                    requestId: value.requestId,
+                    docJson: value.docJson,
+                    generation: value.generation,
+                    revision: value.revision,
+                }
+                : undefined;
+        case 'op-bridge/snapshot-conflict':
+            return string(value.requestId) && safeInteger(value.serverVersion)
+                ? { type: value.type, requestId: value.requestId, serverVersion: value.serverVersion }
+                : undefined;
+        case 'op-bridge/sync-conflict':
+            return safeInteger(value.generation) && safeInteger(value.revision) && safeInteger(value.serverVersion)
+                ? { type: value.type, generation: value.generation, revision: value.revision, serverVersion: value.serverVersion }
+                : undefined;
+        case 'op-bridge/conflict-resolved':
+            return string(value.requestId) ? { type: value.type, requestId: value.requestId } : undefined;
+        case 'op-shell/save':
+            return { type: value.type };
+        case 'op-shell/copy':
+            return string(value.text) ? { type: value.type, text: value.text } : undefined;
+        default:
+            return undefined;
+    }
+}
+export function encodeEditorOutbound(message) {
+    return JSON.stringify(message);
+}
+/** Require an absolute loopback editor URL and derive its exact target origin. */
+export function editorOrigin(iframeUrl) {
+    const url = new URL(iframeUrl);
+    const loopback = url.hostname === '127.0.0.1' || url.hostname === 'localhost' || url.hostname === '::1';
+    if (!loopback || (url.protocol !== 'http:' && url.protocol !== 'https:')) {
+        throw new Error('OpenPencil editor URL must use an HTTP loopback origin');
+    }
+    return url.origin;
+}
+/** Pin the host's resolved theme into the editor's first navigation. */
+export function editorIframeUrlWithTheme(iframeUrl, colorScheme) {
+    const url = new URL(iframeUrl);
+    url.searchParams.set('theme', colorScheme);
+    return url.href;
+}
+/** Pin the host's resolved locale into the editor's first navigation. */
+export function editorIframeUrlWithLocale(iframeUrl, locale) {
+    const url = new URL(iframeUrl);
+    url.searchParams.set('locale', locale);
+    return url.href;
+}
+/** Translate DSH's compact locale id to the editor's BCP 47 contract. */
+export function editorLocaleFromDsh(locale) {
+    return locale === 'zh' ? 'zh-CN' : 'en-US';
+}
+/** Resolve a launch/save/close capability and reject cross-origin control routes. */
+export function editorControlUrl(raw, base = window.location.href) {
+    const page = new URL(base);
+    const url = new URL(raw, page);
+    if (url.origin !== page.origin)
+        throw new Error('OpenPencil editor control URL must be same-origin');
+    return url.href;
+}
+/** Validate source and exact origin before parsing any iframe message. */
+export function editorMessageFrom(event, frameWindow, origin) {
+    if (frameWindow === null || event.source !== frameWindow || event.origin !== origin)
+        return undefined;
+    return parseEditorInbound(event.data);
+}
+let activeEditor;
+/** Read-only gate for background auto-open flows; never asks an owner to close. */
+export function hasActiveEditor() {
+    return activeEditor !== undefined;
+}
+/** Page-wide single-editor coordinator. An existing dirty editor may veto takeover. */
+export function claimEditor(token, close, options = {}) {
+    const previous = activeEditor;
+    if (previous !== undefined && previous.token !== token) {
+        if (options.replace === false || previous.close() === false)
+            return undefined;
+    }
+    activeEditor = { token, close };
+    return () => {
+        if (activeEditor?.token === token)
+            activeEditor = undefined;
+    };
+}
+/** Confirm before a user-driven panel close would discard unsaved canvas edits. */
+export function confirmEditorClose(dirty, confirm = window.confirm) {
+    return !dirty || confirm('OpenPencil has unsaved changes. Close the editor and discard them?');
+}

package/lib/client/editor-dock-layout.d.ts

@@ -0,0 +1,15 @@
+/** Self-contained DSH layout push used by the fallback OpenPencil workbench. */
+export declare const OPENPENCIL_WORKBENCH_DOCK_ATTRIBUTE = "openpencilWorkbenchDockOwner";
+export interface EditorWorkbenchDockLease {
+    update: (width: number) => void;
+    release: () => void;
+}
+/**
+ * Reserve real layout space for the fixed right-hand workbench.
+ *
+ * DSH's root is an auto-width block, so a right margin shrinks its AppFrame
+ * grid instead of covering the conversation. Ownership and exact inline-style
+ * restoration keep this compatible with HMR and fail closed around another
+ * plugin that already owns the root margin.
+ */
+export declare function claimEditorWorkbenchDock(root: HTMLElement, owner: string, initialWidth: number, computedMarginRight?: number): EditorWorkbenchDockLease | undefined;

package/lib/client/editor-dock-layout.js

@@ -0,0 +1,43 @@
+/** Self-contained DSH layout push used by the fallback OpenPencil workbench. */
+export const OPENPENCIL_WORKBENCH_DOCK_ATTRIBUTE = 'openpencilWorkbenchDockOwner';
+function dockWidth(width) {
+    return `${Math.max(0, Math.round(width))}px`;
+}
+/**
+ * Reserve real layout space for the fixed right-hand workbench.
+ *
+ * DSH's root is an auto-width block, so a right margin shrinks its AppFrame
+ * grid instead of covering the conversation. Ownership and exact inline-style
+ * restoration keep this compatible with HMR and fail closed around another
+ * plugin that already owns the root margin.
+ */
+export function claimEditorWorkbenchDock(root, owner, initialWidth, computedMarginRight = 0) {
+    const existingOwner = root.dataset[OPENPENCIL_WORKBENCH_DOCK_ATTRIBUTE];
+    if (existingOwner !== undefined && existingOwner !== owner)
+        return undefined;
+    if (existingOwner === undefined && (root.style.marginRight.trim() !== ''
+        || (Number.isFinite(computedMarginRight) && computedMarginRight > 0.5)))
+        return undefined;
+    const previousMarginRight = root.style.marginRight;
+    const previousMinWidth = root.style.minWidth;
+    root.dataset[OPENPENCIL_WORKBENCH_DOCK_ATTRIBUTE] = owner;
+    root.style.minWidth = '0';
+    let released = false;
+    const update = (width) => {
+        if (released || root.dataset[OPENPENCIL_WORKBENCH_DOCK_ATTRIBUTE] !== owner)
+            return;
+        root.style.marginRight = dockWidth(width);
+    };
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        if (root.dataset[OPENPENCIL_WORKBENCH_DOCK_ATTRIBUTE] !== owner)
+            return;
+        root.style.marginRight = previousMarginRight;
+        root.style.minWidth = previousMinWidth;
+        delete root.dataset[OPENPENCIL_WORKBENCH_DOCK_ATTRIBUTE];
+    };
+    update(initialWidth);
+    return { update, release };
+}

package/lib/client/editor-recovery.d.ts

@@ -0,0 +1,27 @@
+/** Same-origin client controls for durable managed-editor recovery. */
+import { type EditorLocale } from './editor-bridge.js';
+export interface EditorRecoverySummary {
+    id: string;
+    capturedAt: number;
+    bytes: number;
+    sourceName: string;
+    sourceChangedSinceCapture: boolean;
+    cacheLabel: string;
+}
+export interface EditorRecoveryLaunch {
+    sessionId: string;
+    recoveryUrl?: string;
+    recovery?: EditorRecoverySummary;
+}
+export declare function editorRecoverySummaryOf(value: unknown): EditorRecoverySummary | undefined;
+export declare function editorRecoveryItemUrl(launch: EditorRecoveryLaunch, recoveryId: string): string;
+/** Capture the authoritative daemon document; never serializes the iframe from React. */
+export declare function captureManagedEditorRecovery(launch: EditorRecoveryLaunch, fetcher?: typeof fetch): Promise<EditorRecoverySummary | undefined>;
+/** Explicitly restore into the live daemon. The user must still press Save to update `.op`. */
+export declare function restoreManagedEditorRecovery(launch: EditorRecoveryLaunch, recovery: EditorRecoverySummary, fetcher?: typeof fetch): Promise<string>;
+export declare function discardManagedEditorRecovery(launch: EditorRecoveryLaunch, recovery: EditorRecoverySummary, fetcher?: typeof fetch): Promise<void>;
+export interface EditorRecoveryCopy {
+    available: (sourceName: string) => string;
+    conflict: (sourceName: string) => string;
+}
+export declare function editorRecoveryCopy(locale: EditorLocale): EditorRecoveryCopy;