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

package/lib/editor-recovery.d.ts

@@ -0,0 +1,38 @@
+/** Durable, explicit recovery snapshots for managed OpenPencil editors. */
+export type EditorRecoveryReason = 'client-dispose' | 'plugin-dispose';
+export interface EditorRecoverySummary {
+    id: string;
+    capturedAt: number;
+    bytes: number;
+    sourceName: string;
+    sourceChangedSinceCapture: boolean;
+    cacheLabel: string;
+}
+export interface ManagedDaemonDocument {
+    documentJson: string;
+    version: number;
+}
+export interface EditorRecoveryDocument {
+    documentJson: string;
+}
+/** Read the daemon's authoritative in-memory document without exposing its token. */
+export declare function readManagedDaemonDocument(baseUrl: string, token: string, fetcher?: typeof fetch, signal?: AbortSignal): Promise<ManagedDaemonDocument>;
+/** Replace only the live daemon document; persisting to `.op` remains a separate Save. */
+export declare function restoreManagedDaemonDocument(baseUrl: string, token: string, recovery: ManagedDaemonDocument, fetcher?: typeof fetch): Promise<number>;
+/** Filesystem-backed store keyed by an HMAC of the source path. */
+export declare class EditorRecoveryStore {
+    #private;
+    constructor(key: Buffer, root?: string, now?: () => number);
+    capture(options: {
+        sourcePath: string;
+        sourceSha256: string;
+        sourceDocumentJson: string;
+        daemonDocument: ManagedDaemonDocument;
+        reason: EditorRecoveryReason;
+    }): Promise<EditorRecoverySummary | undefined>;
+    find(sourcePathValue: string, currentSourceSha256: string, currentSourceDocumentJson?: string): Promise<EditorRecoverySummary | undefined>;
+    read(sourcePathValue: string, id: string): Promise<EditorRecoveryDocument | undefined>;
+    discard(sourcePathValue: string, id: string): Promise<boolean>;
+    discardFor(sourcePathValue: string): Promise<boolean>;
+    prune(): Promise<void>;
+}

package/lib/editor-recovery.js

@@ -0,0 +1,319 @@
+/** Durable, explicit recovery snapshots for managed OpenPencil editors. */
+import { createHash, createHmac, randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { stateRoot } from './renderer.js';
+const RECOVERY_VERSION = 1;
+const RECOVERY_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_RECOVERY_FILES = 32;
+const MAX_DOCUMENT_BYTES = 64 * 1024 * 1024;
+// A recovery record stores the normalized document as a JSON string. In the
+// worst case every byte in that string needs one additional escape byte in the
+// outer JSON envelope. Keep separate document and envelope limits so every
+// document accepted by the host can still be recovered.
+const MAX_RECOVERY_ENVELOPE_BYTES = 1024 * 1024;
+const MAX_ESCAPED_DOCUMENT_BYTES = MAX_DOCUMENT_BYTES * 2 + 2;
+const MAX_RECOVERY_RECORD_BYTES = MAX_ESCAPED_DOCUMENT_BYTES + MAX_RECOVERY_ENVELOPE_BYTES;
+const RECOVERY_ID_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizedDocumentJson(value, label) {
+    const bytes = Buffer.byteLength(value);
+    if (bytes <= 0 || bytes > MAX_DOCUMENT_BYTES)
+        throw new Error(`${label} size is invalid`);
+    let document;
+    try {
+        document = JSON.parse(value);
+    }
+    catch {
+        throw new Error(`${label} is not valid JSON`);
+    }
+    if (!isRecord(document))
+        throw new Error(`${label} must be a document object`);
+    const normalized = JSON.stringify(document);
+    const normalizedBytes = Buffer.byteLength(normalized);
+    if (normalizedBytes <= 0 || normalizedBytes > MAX_DOCUMENT_BYTES)
+        throw new Error(`${label} size is invalid`);
+    return normalized;
+}
+function serializedRecoveryRecord(record) {
+    const serialized = JSON.stringify(record);
+    const serializedBytes = Buffer.byteLength(serialized);
+    const escapedDocumentBytes = Buffer.byteLength(JSON.stringify(record.documentJson));
+    const envelopeBytes = serializedBytes - escapedDocumentBytes;
+    if (envelopeBytes > MAX_RECOVERY_ENVELOPE_BYTES || serializedBytes > MAX_RECOVERY_RECORD_BYTES) {
+        throw new Error('OpenPencil recovery snapshot exceeds the cache size limit');
+    }
+    return serialized;
+}
+function recoveryRecordFrom(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (value.v !== RECOVERY_VERSION
+        || typeof value.id !== 'string' || !RECOVERY_ID_PATTERN.test(value.id)
+        || typeof value.sourcePath !== 'string' || resolve(value.sourcePath) !== value.sourcePath
+        || typeof value.sourceSha256AtCapture !== 'string' || !/^[a-f0-9]{64}$/.test(value.sourceSha256AtCapture)
+        || typeof value.documentSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(value.documentSha256)
+        || typeof value.documentJson !== 'string'
+        || typeof value.daemonVersion !== 'number' || !Number.isSafeInteger(value.daemonVersion) || value.daemonVersion < 0
+        || typeof value.capturedAt !== 'number' || !Number.isSafeInteger(value.capturedAt) || value.capturedAt <= 0
+        || (value.reason !== 'client-dispose' && value.reason !== 'plugin-dispose'))
+        return undefined;
+    try {
+        const documentJson = normalizedDocumentJson(value.documentJson, 'OpenPencil recovery document');
+        if (sha256(documentJson) !== value.documentSha256)
+            return undefined;
+        return { ...value, documentJson };
+    }
+    catch {
+        return undefined;
+    }
+}
+function daemonOrigin(baseUrl) {
+    const origin = new URL(baseUrl);
+    const loopback = origin.hostname === '127.0.0.1' || origin.hostname === 'localhost' || origin.hostname === '::1';
+    if (!loopback || (origin.protocol !== 'http:' && origin.protocol !== 'https:')) {
+        throw new Error('OpenPencil recovery endpoint must use an HTTP loopback origin');
+    }
+    if (origin.pathname !== '/' || origin.search !== '' || origin.hash !== '') {
+        throw new Error('OpenPencil recovery base URL must be an origin');
+    }
+    return origin;
+}
+async function boundedResponseBytes(response, label) {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > MAX_DOCUMENT_BYTES + 1024 * 1024) {
+        throw new Error(`${label} is too large`);
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length > MAX_DOCUMENT_BYTES + 1024 * 1024)
+        throw new Error(`${label} is too large`);
+    return bytes;
+}
+/** Read the daemon's authoritative in-memory document without exposing its token. */
+export async function readManagedDaemonDocument(baseUrl, token, fetcher = fetch, signal) {
+    const origin = daemonOrigin(baseUrl);
+    const timeout = AbortSignal.timeout(5_000);
+    const response = await fetcher(new URL('/api/mcp/document', origin).href, {
+        headers: {
+            authorization: `Bearer ${token}`,
+            'x-openpencil-token': token,
+            accept: 'application/json',
+        },
+        signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
+    });
+    const bytes = await boundedResponseBytes(response, 'OpenPencil recovery response');
+    if (!response.ok)
+        throw new Error(`OpenPencil recovery snapshot failed (${response.status})`);
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new Error('OpenPencil recovery snapshot returned invalid JSON');
+    }
+    if (!isRecord(value) || !isRecord(value.document) || typeof value.version !== 'number' || !Number.isSafeInteger(value.version) || value.version < 0) {
+        throw new Error('OpenPencil recovery snapshot returned an invalid document');
+    }
+    return { documentJson: normalizedDocumentJson(JSON.stringify(value.document), 'OpenPencil recovery document'), version: value.version };
+}
+/** Replace only the live daemon document; persisting to `.op` remains a separate Save. */
+export async function restoreManagedDaemonDocument(baseUrl, token, recovery, fetcher = fetch) {
+    const origin = daemonOrigin(baseUrl);
+    const documentJson = normalizedDocumentJson(recovery.documentJson, 'OpenPencil recovery document');
+    const response = await fetcher(new URL('/api/mcp/document', origin).href, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${token}`,
+            'x-openpencil-token': token,
+            'content-type': 'application/json',
+            accept: 'application/json',
+        },
+        body: JSON.stringify({
+            document: JSON.parse(documentJson),
+            sourceClientId: 'dsh-openpencil-recovery',
+            baseVersion: recovery.version,
+        }),
+        signal: AbortSignal.timeout(5_000),
+    });
+    const bytes = await boundedResponseBytes(response, 'OpenPencil recovery restore response');
+    if (!response.ok)
+        throw new Error(`OpenPencil recovery restore failed (${response.status})`);
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new Error('OpenPencil recovery restore returned invalid JSON');
+    }
+    if (!isRecord(value) || value.ok !== true || typeof value.version !== 'number' || !Number.isSafeInteger(value.version)) {
+        throw new Error('OpenPencil recovery restore returned an invalid result');
+    }
+    return value.version;
+}
+/** Filesystem-backed store keyed by an HMAC of the source path. */
+export class EditorRecoveryStore {
+    #key;
+    #root;
+    #now;
+    constructor(key, root = join(stateRoot(), 'recovery'), now = Date.now) {
+        if (key.length < 16)
+            throw new TypeError('editor recovery key is too short');
+        this.#key = Buffer.from(key);
+        this.#root = root;
+        this.#now = now;
+    }
+    async capture(options) {
+        const sourcePath = resolve(options.sourcePath);
+        const sourceDocumentJson = normalizedDocumentJson(options.sourceDocumentJson, 'OpenPencil source document');
+        const documentJson = normalizedDocumentJson(options.daemonDocument.documentJson, 'OpenPencil recovery document');
+        const id = this.#idFor(sourcePath);
+        if (documentJson === sourceDocumentJson) {
+            await this.discard(sourcePath, id);
+            return undefined;
+        }
+        if (!/^[a-f0-9]{64}$/.test(options.sourceSha256))
+            throw new Error('OpenPencil source hash is invalid');
+        const capturedAt = this.#now();
+        const record = {
+            v: RECOVERY_VERSION,
+            id,
+            sourcePath,
+            sourceSha256AtCapture: options.sourceSha256,
+            documentSha256: sha256(documentJson),
+            documentJson,
+            daemonVersion: options.daemonDocument.version,
+            capturedAt,
+            reason: options.reason,
+        };
+        const serialized = serializedRecoveryRecord(record);
+        await mkdir(this.#root, { recursive: true, mode: 0o700 });
+        await this.#atomicWrite(this.#pathFor(id), serialized);
+        await this.prune();
+        return this.#summary(record, options.sourceSha256);
+    }
+    async find(sourcePathValue, currentSourceSha256, currentSourceDocumentJson) {
+        const sourcePath = resolve(sourcePathValue);
+        const record = await this.#read(sourcePath, this.#idFor(sourcePath));
+        if (record === undefined)
+            return undefined;
+        if (currentSourceDocumentJson !== undefined
+            && record.documentJson === normalizedDocumentJson(currentSourceDocumentJson, 'OpenPencil source document')) {
+            await this.discard(sourcePath, record.id);
+            return undefined;
+        }
+        return this.#summary(record, currentSourceSha256);
+    }
+    async read(sourcePathValue, id) {
+        const sourcePath = resolve(sourcePathValue);
+        const record = await this.#read(sourcePath, id);
+        return record === undefined ? undefined : { documentJson: record.documentJson };
+    }
+    async discard(sourcePathValue, id) {
+        const sourcePath = resolve(sourcePathValue);
+        if (!RECOVERY_ID_PATTERN.test(id) || id !== this.#idFor(sourcePath))
+            return false;
+        try {
+            await rm(this.#pathFor(id));
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }
+    async discardFor(sourcePathValue) {
+        const sourcePath = resolve(sourcePathValue);
+        return this.discard(sourcePath, this.#idFor(sourcePath));
+    }
+    async prune() {
+        let names;
+        try {
+            names = await readdir(this.#root);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        const candidates = [];
+        for (const name of names) {
+            if (!RECOVERY_ID_PATTERN.test(name.replace(/\.json$/, '')) || !name.endsWith('.json'))
+                continue;
+            const path = join(this.#root, name);
+            const record = await this.#readPath(path);
+            if (record === undefined || this.#expired(record)) {
+                await rm(path, { force: true }).catch(() => { });
+            }
+            else {
+                candidates.push({ path, capturedAt: record.capturedAt });
+            }
+        }
+        candidates.sort((left, right) => right.capturedAt - left.capturedAt);
+        await Promise.all(candidates.slice(MAX_RECOVERY_FILES).map(candidate => rm(candidate.path, { force: true })));
+    }
+    #idFor(sourcePath) {
+        return createHmac('sha256', this.#key).update('dsh-openpencil/recovery/v1\0').update(sourcePath).digest('base64url');
+    }
+    #pathFor(id) {
+        return join(this.#root, `${id}.json`);
+    }
+    #expired(record) {
+        const age = this.#now() - record.capturedAt;
+        return age < 0 || age > RECOVERY_TTL_MS;
+    }
+    async #read(sourcePath, id) {
+        if (!RECOVERY_ID_PATTERN.test(id) || id !== this.#idFor(sourcePath))
+            return undefined;
+        const path = this.#pathFor(id);
+        const record = await this.#readPath(path);
+        if (record === undefined || record.sourcePath !== sourcePath || this.#expired(record)) {
+            await rm(path, { force: true }).catch(() => { });
+            return undefined;
+        }
+        return record;
+    }
+    async #readPath(path) {
+        try {
+            const info = await lstat(path);
+            if (info.isSymbolicLink() || !info.isFile() || info.size <= 0 || info.size > MAX_RECOVERY_RECORD_BYTES)
+                return undefined;
+            const value = JSON.parse(await readFile(path, 'utf8'));
+            return recoveryRecordFrom(value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async #atomicWrite(path, value) {
+        const temp = join(this.#root, `.recovery-${randomUUID()}.tmp`);
+        let handle;
+        try {
+            handle = await open(temp, 'wx', 0o600);
+            await handle.writeFile(value);
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            await rename(temp, path);
+        }
+        finally {
+            await handle?.close().catch(() => { });
+            await rm(temp, { force: true }).catch(() => { });
+        }
+    }
+    #summary(record, currentSourceSha256) {
+        return {
+            id: record.id,
+            capturedAt: record.capturedAt,
+            bytes: Buffer.byteLength(record.documentJson),
+            sourceName: basename(record.sourcePath),
+            sourceChangedSinceCapture: currentSourceSha256 !== record.sourceSha256AtCapture,
+            cacheLabel: `dsh-openpencil/recovery/${record.id}.json`,
+        };
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @zseven-w/dsh-openpencil — preview `.op` design documents in DSH.
+ *
+ * Plugin lifecycle: register the model-facing tool plus signed routes for
+ * exact PNGs, immutable document snapshots, and the optional read-only Web
+ * SDK canvas. Everything is
+ * registered through `ctx.effect` (or a returned disposer) so unloading the
+ * plugin removes every contribution.
+ *
+ * The `openpencil_render` tool never returns an ImageBlock — the DeepSeek
+ * adapter rejects image blocks anywhere in a request. The browser-only
+ * envelope rides `output.presentationMeta` into `ToolCallBlock.meta`, and
+ * the keyed `tool.call.toolview` client component renders a PNG-first card
+ * and lazily mounts the OpenPencil canvas on demand.
+ * @module @zseven-w/dsh-openpencil
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export { LEGACY_DESIGN_RENDER_TOOL_NAME, OPENPENCIL_CREATE_TOOL_NAME, OPENPENCIL_EDIT_TOOL_NAME, OPENPENCIL_NEW_TOOL_NAME, OPENPENCIL_RENDER_TOOL_NAME, OPENPENCIL_SELECTION_TOOL_NAME, OPENPENCIL_TOOL_NAMES, } from './tool-names.js';
+/** Stable plugin name (the loader entry id in cordis.patch.yml). */
+export declare const name = "@zseven-w/dsh-openpencil";
+/** Services this plugin's root fiber requires. */
+export declare const inject: string[];
+/** Plugin entry: mount every model-facing contribution. */
+export declare function apply(ctx: Context): Promise<() => Promise<void>>;

package/lib/index.js

@@ -0,0 +1,132 @@
+/**
+ * @zseven-w/dsh-openpencil — preview `.op` design documents in DSH.
+ *
+ * Plugin lifecycle: register the model-facing tool plus signed routes for
+ * exact PNGs, immutable document snapshots, and the optional read-only Web
+ * SDK canvas. Everything is
+ * registered through `ctx.effect` (or a returned disposer) so unloading the
+ * plugin removes every contribution.
+ *
+ * The `openpencil_render` tool never returns an ImageBlock — the DeepSeek
+ * adapter rejects image blocks anywhere in a request. The browser-only
+ * envelope rides `output.presentationMeta` into `ToolCallBlock.meta`, and
+ * the keyed `tool.call.toolview` client component renders a PNG-first card
+ * and lazily mounts the OpenPencil canvas on demand.
+ * @module @zseven-w/dsh-openpencil
+ */
+import { RENDER_ROUTE_PREFIX, RenderAccessController, prepareRenderAccessKey, } from './renderer.js';
+import { createDesignRenderTool } from './tool.js';
+import { createDesignCreateTool, createDesignEditTool, createDesignSelectionTool, } from './design-tools.js';
+import { createDesignNewTool } from './new-tool.js';
+import { VIEWER_ASSET_ROUTE_PREFIX, prepareViewerAssets, } from './viewer-assets.js';
+import { EDITOR_ROUTE_PREFIX, EditorHostController, } from './editor-host.js';
+import { OPENPENCIL_CREATE_TOOL_NAME, OPENPENCIL_EDIT_TOOL_NAME, OPENPENCIL_NEW_TOOL_NAME, OPENPENCIL_RENDER_TOOL_NAME, OPENPENCIL_SELECTION_TOOL_NAME, OPENPENCIL_TOOL_NAMES, } from './tool-names.js';
+import { PRESENTATION_HYDRATION_ROUTE, PresentationHydrationController, } from './presentation-hydration.js';
+export { LEGACY_DESIGN_RENDER_TOOL_NAME, OPENPENCIL_CREATE_TOOL_NAME, OPENPENCIL_EDIT_TOOL_NAME, OPENPENCIL_NEW_TOOL_NAME, OPENPENCIL_RENDER_TOOL_NAME, OPENPENCIL_SELECTION_TOOL_NAME, OPENPENCIL_TOOL_NAMES, } from './tool-names.js';
+/** Stable plugin name (the loader entry id in cordis.patch.yml). */
+export const name = '@zseven-w/dsh-openpencil';
+/** Services this plugin's root fiber requires. */
+export const inject = ['tools', 'sessions', 'fs', 'sandboxPolicy'];
+/** Read the optional bind-time trust snapshot without making Web-only runtime glue a hard peer. */
+function webRuntimeTrustedHosts(ctx) {
+    const get = ctx.get;
+    const runtime = typeof get === 'function' ? get.call(ctx, 'webRuntime') : undefined;
+    if (typeof runtime !== 'object' || runtime === null || !('trustedHosts' in runtime))
+        return [];
+    const trustedHosts = runtime.trustedHosts;
+    return Array.isArray(trustedHosts) && trustedHosts.every(value => typeof value === 'string')
+        ? trustedHosts
+        : [];
+}
+/** Plugin entry: mount every model-facing contribution. */
+export async function apply(ctx) {
+    const hostCtx = ctx;
+    const eventCtx = ctx;
+    const disposers = [];
+    const accessKey = await prepareRenderAccessKey();
+    const controller = new RenderAccessController(accessKey);
+    const viewerAssets = await prepareViewerAssets();
+    const editorHost = new EditorHostController(accessKey);
+    const presentationHydration = new PresentationHydrationController({
+        sessions: hostCtx.sessions,
+        render: controller,
+        viewer: viewerAssets,
+        editor: editorHost,
+        // webRuntime is provided after bind by the official Web bundle. Resolve
+        // it at request time so loopback still works on older/headless hosts while
+        // configured LAN authorities receive the same Host fence as DSH /api.
+        trustedHosts: () => webRuntimeTrustedHosts(ctx),
+    });
+    let editorHostDisposePromise;
+    const disposeEditorHost = () => {
+        editorHostDisposePromise ??= editorHost.dispose();
+        return editorHostDisposePromise;
+    };
+    // Tool registration: global (every agent sees it). The tool's
+    // presentationMeta consults `controller.routeAvailable`, so a profile
+    // without the webserver still gets a plain-JSON result — no dangling URL.
+    disposers.push(ctx.effect(() => hostCtx.tools.register(createDesignRenderTool(controller, viewerAssets, editorHost)), `dsh-openpencil: ${OPENPENCIL_RENDER_TOOL_NAME} tool`));
+    disposers.push(ctx.effect(() => hostCtx.tools.register(createDesignSelectionTool(editorHost)), `dsh-openpencil: ${OPENPENCIL_SELECTION_TOOL_NAME} tool`));
+    disposers.push(ctx.effect(() => hostCtx.tools.register(createDesignNewTool(editorHost, {
+        fs: hostCtx.fs,
+        sandboxPolicy: hostCtx.sandboxPolicy,
+        observe: (target, observation, exec) => eventCtx.emit('fs/observed', target, observation, exec),
+    })), `dsh-openpencil: ${OPENPENCIL_NEW_TOOL_NAME} tool`));
+    disposers.push(ctx.effect(() => hostCtx.tools.register(createDesignCreateTool(editorHost)), `dsh-openpencil: ${OPENPENCIL_CREATE_TOOL_NAME} tool`));
+    disposers.push(ctx.effect(() => hostCtx.tools.register(createDesignEditTool(editorHost)), `dsh-openpencil: ${OPENPENCIL_EDIT_TOOL_NAME} tool`));
+    disposers.push(ctx.effect(() => eventCtx.on('tools/result', (exec, result) => presentationHydration.observeToolResult(exec, result)), 'dsh-openpencil: nested presentation result observer'));
+    disposers.push(ctx.effect(() => eventCtx.on('session/disposed', session => presentationHydration.forgetSession(String(session.id))), 'dsh-openpencil: nested presentation session cleanup'));
+    // Optional Web routes: only mounted when a webServer service exists
+    // (headless profiles never attach, and `routeAvailable` stays false).
+    // The inject fiber is parent-scoped and tears itself down with this ctx;
+    // the inner effect's disposer is the route removal.
+    ctx.inject(['webServer'], (webCtx) => webCtx.effect(() => {
+        const webServer = webCtx.webServer;
+        const detach = controller.attachRoute();
+        const disposeRoute = webServer.register({
+            kind: 'prefix',
+            path: RENDER_ROUTE_PREFIX,
+            handler: (req, res) => controller.handle(req, res),
+        });
+        const disposePresentationRoute = webServer.register({
+            kind: 'exact',
+            path: PRESENTATION_HYDRATION_ROUTE,
+            handler: (req, res) => presentationHydration.handle(req, res),
+        });
+        const disposeViewerRoute = viewerAssets.available
+            ? (() => {
+                const detachViewer = viewerAssets.attachRoute();
+                const disposeViewer = webServer.register({
+                    kind: 'prefix',
+                    path: VIEWER_ASSET_ROUTE_PREFIX,
+                    handler: (req, res) => viewerAssets.handle(req, res),
+                });
+                return () => {
+                    disposeViewer();
+                    detachViewer();
+                };
+            })()
+            : undefined;
+        const detachEditor = editorHost.attachRoute();
+        const disposeEditorRoute = webServer.register({
+            kind: 'prefix',
+            path: EDITOR_ROUTE_PREFIX,
+            handler: (req, res) => editorHost.handle(req, res),
+        });
+        return async () => {
+            disposeEditorRoute();
+            detachEditor();
+            disposeViewerRoute?.();
+            disposePresentationRoute();
+            disposeRoute();
+            detach();
+            await disposeEditorHost();
+        };
+    }, 'dsh-openpencil: render route'));
+    ctx.logger.info(`dsh-openpencil mounted (${OPENPENCIL_TOOL_NAMES.join(' + ')}; viewer assets: ${viewerAssets.available ? 'ready' : 'unavailable'}; editor: ${editorHost.available ? 'ready' : 'unavailable'})`);
+    return async () => {
+        for (const dispose of disposers.reverse())
+            await dispose();
+        await disposeEditorHost();
+    };
+}

package/lib/mcp-client.d.ts

@@ -0,0 +1,47 @@
+/** Strict loopback JSON-RPC client for one managed OpenPencil editor. */
+export interface OpenPencilNodeSummary {
+    id: string;
+    type?: string;
+    name?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+export interface OpenPencilSelectionSnapshot {
+    sourcePath: string;
+    activePageId: string;
+    selectedIds: string[];
+    nodes: OpenPencilNodeSummary[];
+    updatedAt: number;
+}
+export interface OpenPencilMcpResult {
+    tool: string;
+    value: unknown;
+    text: string;
+}
+interface McpCallOptions {
+    baseUrl: string;
+    token: string;
+    tool: string;
+    arguments?: Record<string, unknown>;
+    signal?: AbortSignal;
+    fetcher?: typeof fetch;
+}
+interface McpVersionOptions {
+    baseUrl: string;
+    token: string;
+    signal?: AbortSignal;
+    fetcher?: typeof fetch;
+    /** Test seam; production uses the same bounded timeout as MCP calls. */
+    timeoutMs?: number;
+}
+/** Decode a JSON-RPC tools/call envelope, including MCP's HTTP-200 errors. */
+export declare function parseOpenPencilMcpResponse(tool: string, value: unknown): OpenPencilMcpResult;
+/** Call a first-party tool on a managed editor without exposing its daemon token. */
+export declare function callOpenPencilMcp(options: McpCallOptions): Promise<OpenPencilMcpResult>;
+/** Probe the daemon document version before and after a write. */
+export declare function getOpenPencilMcpVersion(options: McpVersionOptions): Promise<number>;
+/** Project get_selection into the bounded shape shared with the DSH client. */
+export declare function selectionSnapshotFromMcp(sourcePath: string, value: unknown, updatedAt?: number): OpenPencilSelectionSnapshot;
+export {};