@superdoc/sdk 2.5.0 → 2.6.0

package/dist/runtime/host.cjs

@@ -4,9 +4,11 @@ var node_child_process = require('node:child_process');
 var node_readline = require('node:readline');
 var transportCommon = require('./transport-common.cjs');
 var errors = require('./errors.cjs');
+var documentRpc = require('./document-rpc.cjs');
 
 const HOST_PROTOCOL_VERSION = '1.0';
-const REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
+const CLI_HOST_REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
+const DOCUMENT_HOST_REQUIRED_FEATURES = [...documentRpc.DOCUMENT_RPC_FEATURES, 'host.shutdown'];
 const CHANGE_MODES = ['direct', 'tracked'];
 const FORWARD_HOST_STDERR = typeof process !== 'undefined' && typeof process.env?.SUPERDOC_DEBUG_TEXT_REWRITE === 'string'
     ? process.env.SUPERDOC_DEBUG_TEXT_REWRITE === '1'
@@ -35,6 +37,9 @@ function buildHostSpawnArgs(prefixArgs, options) {
     }
     return args;
 }
+function buildDocumentHostSpawnArgs(prefixArgs) {
+    return [...prefixArgs];
+}
 /**
  * Computes the JS-side watchdog timeout for a single JSON-RPC request.
  *
@@ -60,11 +65,10 @@ function resolveJsWatchdogTimeout(watchdogTimeoutMs, requestTimeoutMs, timeoutMs
     }
     return Math.max(watchdogTimeoutMs, HOST_DEFAULT_REQUEST_TIMEOUT_MS + WATCHDOG_HEADROOM_MS);
 }
-/**
- * Transport that communicates with a long-lived CLI host process over JSON-RPC stdio.
- */
+/** Transport for the legacy CLI host or the structured document host. */
 class HostTransport {
-    cliBin;
+    hostBin;
+    processMode;
     env;
     startupTimeoutMs;
     shutdownTimeoutMs;
@@ -73,14 +77,18 @@ class HostTransport {
     maxQueueDepth;
     defaultChangeMode;
     user;
+    documentRpcEnabled;
     child = null;
     stdoutReader = null;
     pending = new Map();
     nextRequestId = 1;
     connecting = null;
     stopping = false;
+    hostFeatures = new Set();
+    documentRpcSessions = new Set();
     constructor(options) {
-        this.cliBin = options.cliBin;
+        this.hostBin = options.hostBin;
+        this.processMode = options.processMode ?? 'cli';
         this.env = options.env;
         this.startupTimeoutMs = options.startupTimeoutMs ?? 5_000;
         this.shutdownTimeoutMs = options.shutdownTimeoutMs ?? 5_000;
@@ -95,6 +103,12 @@ class HostTransport {
         }
         this.defaultChangeMode = options.defaultChangeMode;
         this.user = options.user;
+        this.documentRpcEnabled = documentRpc.documentRpcEnabled(options.env);
+        if (this.processMode === 'document' && !this.documentRpcEnabled) {
+            throw new errors.SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN requires SUPERDOC_SDK_DOCUMENT_RPC=1.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
     }
     async connect() {
         await this.ensureConnected();
@@ -125,6 +139,33 @@ class HostTransport {
     }
     async invoke(operation, params = {}, options = {}) {
         await this.ensureConnected();
+        if (this.documentRpcEnabled &&
+            documentRpc.supportsDocumentRpc(this.hostFeatures) &&
+            this.defaultChangeMode === undefined &&
+            this.user === undefined &&
+            operation.operationId === 'doc.open' &&
+            documentRpc.canOpenWithDocumentRpc(params, options)) {
+            const opened = documentRpc.buildDocumentOpenParams(params);
+            const response = await this.sendJsonRpcRequest('document.open', opened.params, this.resolveWatchdogTimeout(options.timeoutMs));
+            const result = documentRpc.mapDocumentOpenResult(response, opened.sessionId, params.doc);
+            this.documentRpcSessions.add(opened.sessionId);
+            return result;
+        }
+        const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
+        if (sessionId !== undefined && this.documentRpcSessions.has(sessionId)) {
+            const request = documentRpc.buildDocumentInvokeParams(sessionId, operation, params, options);
+            const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs));
+            const result = documentRpc.mapDocumentLifecycleResult(operation.operationId, response, sessionId);
+            if (operation.operationId === 'doc.close')
+                this.documentRpcSessions.delete(sessionId);
+            return result;
+        }
+        if (this.processMode === 'document') {
+            throw new errors.SuperDocCliError(`Standalone document host does not support ${operation.operationId} through structured RPC v0.`, {
+                code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+                details: { operationId: operation.operationId },
+            });
+        }
         const argv = transportCommon.buildOperationArgv(operation, params, options, this.requestTimeoutMs, this.defaultChangeMode, this.user);
         const stdinBase64 = options.stdinBytes ? Buffer.from(options.stdinBytes).toString('base64') : '';
         const watchdogTimeout = this.resolveWatchdogTimeout(options.timeoutMs);
@@ -142,13 +183,13 @@ class HostTransport {
         return resultRecord.data;
     }
     async ensureConnected() {
-        if (this.child && !this.child.killed) {
-            return;
-        }
         if (this.connecting) {
             await this.connecting;
             return;
         }
+        if (this.child && !this.child.killed) {
+            return;
+        }
         this.connecting = this.startHostProcess();
         try {
             await this.connecting;
@@ -158,8 +199,10 @@ class HostTransport {
         }
     }
     async startHostProcess() {
-        const { command, prefixArgs } = transportCommon.resolveInvocation(this.cliBin);
-        const args = buildHostSpawnArgs(prefixArgs, { requestTimeoutMs: this.requestTimeoutMs });
+        const { command, prefixArgs } = transportCommon.resolveInvocation(this.hostBin);
+        const args = this.processMode === 'document'
+            ? buildDocumentHostSpawnArgs(prefixArgs)
+            : buildHostSpawnArgs(prefixArgs, { requestTimeoutMs: this.requestTimeoutMs });
         const child = node_child_process.spawn(command, args, {
             env: {
                 ...process.env,
@@ -242,7 +285,8 @@ class HostTransport {
                 details: { features },
             });
         }
-        for (const requiredFeature of REQUIRED_FEATURES) {
+        const requiredFeatures = this.processMode === 'document' ? DOCUMENT_HOST_REQUIRED_FEATURES : CLI_HOST_REQUIRED_FEATURES;
+        for (const requiredFeature of requiredFeatures) {
             if (!features.includes(requiredFeature)) {
                 throw new errors.SuperDocCliError(`Host does not support required feature: ${requiredFeature}`, {
                     code: 'HOST_HANDSHAKE_FAILED',
@@ -250,6 +294,9 @@ class HostTransport {
                 });
             }
         }
+        this.hostFeatures.clear();
+        for (const feature of features)
+            this.hostFeatures.add(feature);
     }
     resolveWatchdogTimeout(timeoutMsOverride) {
         return resolveJsWatchdogTimeout(this.watchdogTimeoutMs, this.requestTimeoutMs, timeoutMsOverride);
@@ -349,6 +396,7 @@ class HostTransport {
         const error = rawError;
         const data = error.data;
         const cliCode = typeof data?.cliCode === 'string' ? data.cliCode : undefined;
+        const domainCode = typeof data?.domainCode === 'string' ? data.domainCode : undefined;
         const cliMessage = typeof data?.message === 'string' ? data.message : undefined;
         const exitCode = typeof data?.exitCode === 'number' ? data.exitCode : undefined;
         if (cliCode) {
@@ -358,6 +406,16 @@ class HostTransport {
                 exitCode,
             });
         }
+        if (domainCode) {
+            return new errors.SuperDocCliError(error.message, {
+                code: domainCode,
+                details: {
+                    ...(data?.details === undefined ? {} : { domainDetails: data.details }),
+                    ...(data?.stage === undefined ? {} : { stage: data.stage }),
+                    ...(data?.byteLength === undefined ? {} : { byteLength: data.byteLength }),
+                },
+            });
+        }
         if (error.code === JSON_RPC_TIMEOUT_CODE) {
             return new errors.SuperDocCliError(error.message, {
                 code: 'TIMEOUT',
@@ -373,6 +431,8 @@ class HostTransport {
         this.cleanupProcess(error);
     }
     cleanupProcess(error) {
+        this.hostFeatures.clear();
+        this.documentRpcSessions.clear();
         const child = this.child;
         if (child) {
             child.removeAllListeners();
@@ -398,5 +458,6 @@ class HostTransport {
 }
 
 exports.HostTransport = HostTransport;
+exports.buildDocumentHostSpawnArgs = buildDocumentHostSpawnArgs;
 exports.buildHostSpawnArgs = buildHostSpawnArgs;
 exports.resolveJsWatchdogTimeout = resolveJsWatchdogTimeout;

package/dist/runtime/host.d.ts

@@ -9,6 +9,7 @@ import { type InvokeOptions, type OperationSpec, type SuperDocClientOptions } fr
 export declare function buildHostSpawnArgs(prefixArgs: readonly string[], options: {
     requestTimeoutMs?: number;
 }): string[];
+export declare function buildDocumentHostSpawnArgs(prefixArgs: readonly string[]): string[];
 /**
  * Computes the JS-side watchdog timeout for a single JSON-RPC request.
  *
@@ -26,11 +27,10 @@ export declare function buildHostSpawnArgs(prefixArgs: readonly string[], option
  * Exported for unit testing.
  */
 export declare function resolveJsWatchdogTimeout(watchdogTimeoutMs: number, requestTimeoutMs: number | undefined, timeoutMsOverride: number | undefined): number;
-/**
- * Transport that communicates with a long-lived CLI host process over JSON-RPC stdio.
- */
+/** Transport for the legacy CLI host or the structured document host. */
 export declare class HostTransport {
-    private readonly cliBin;
+    private readonly hostBin;
+    private readonly processMode;
     private readonly env?;
     private readonly startupTimeoutMs;
     private readonly shutdownTimeoutMs;
@@ -39,14 +39,18 @@ export declare class HostTransport {
     private readonly maxQueueDepth;
     private readonly defaultChangeMode?;
     private readonly user?;
+    private readonly documentRpcEnabled;
     private child;
     private stdoutReader;
     private readonly pending;
     private nextRequestId;
     private connecting;
     private stopping;
+    private readonly hostFeatures;
+    private readonly documentRpcSessions;
     constructor(options: {
-        cliBin: string;
+        hostBin: string;
+        processMode?: 'cli' | 'document';
     } & SuperDocClientOptions);
     connect(): Promise<void>;
     dispose(): Promise<void>;

package/dist/runtime/host.js

@@ -2,8 +2,10 @@ import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { buildOperationArgv, resolveInvocation, } from './transport-common.js';
 import { SuperDocCliError } from './errors.js';
+import { DOCUMENT_RPC_FEATURES, buildDocumentInvokeParams, buildDocumentOpenParams, canOpenWithDocumentRpc, documentRpcEnabled, mapDocumentLifecycleResult, mapDocumentOpenResult, supportsDocumentRpc, } from './document-rpc.js';
 const HOST_PROTOCOL_VERSION = '1.0';
-const REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
+const CLI_HOST_REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
+const DOCUMENT_HOST_REQUIRED_FEATURES = [...DOCUMENT_RPC_FEATURES, 'host.shutdown'];
 const CHANGE_MODES = ['direct', 'tracked'];
 const FORWARD_HOST_STDERR = typeof process !== 'undefined' && typeof process.env?.SUPERDOC_DEBUG_TEXT_REWRITE === 'string'
     ? process.env.SUPERDOC_DEBUG_TEXT_REWRITE === '1'
@@ -32,6 +34,9 @@ export function buildHostSpawnArgs(prefixArgs, options) {
     }
     return args;
 }
+export function buildDocumentHostSpawnArgs(prefixArgs) {
+    return [...prefixArgs];
+}
 /**
  * Computes the JS-side watchdog timeout for a single JSON-RPC request.
  *
@@ -57,11 +62,10 @@ export function resolveJsWatchdogTimeout(watchdogTimeoutMs, requestTimeoutMs, ti
     }
     return Math.max(watchdogTimeoutMs, HOST_DEFAULT_REQUEST_TIMEOUT_MS + WATCHDOG_HEADROOM_MS);
 }
-/**
- * Transport that communicates with a long-lived CLI host process over JSON-RPC stdio.
- */
+/** Transport for the legacy CLI host or the structured document host. */
 export class HostTransport {
-    cliBin;
+    hostBin;
+    processMode;
     env;
     startupTimeoutMs;
     shutdownTimeoutMs;
@@ -70,14 +74,18 @@ export class HostTransport {
     maxQueueDepth;
     defaultChangeMode;
     user;
+    documentRpcEnabled;
     child = null;
     stdoutReader = null;
     pending = new Map();
     nextRequestId = 1;
     connecting = null;
     stopping = false;
+    hostFeatures = new Set();
+    documentRpcSessions = new Set();
     constructor(options) {
-        this.cliBin = options.cliBin;
+        this.hostBin = options.hostBin;
+        this.processMode = options.processMode ?? 'cli';
         this.env = options.env;
         this.startupTimeoutMs = options.startupTimeoutMs ?? 5_000;
         this.shutdownTimeoutMs = options.shutdownTimeoutMs ?? 5_000;
@@ -92,6 +100,12 @@ export class HostTransport {
         }
         this.defaultChangeMode = options.defaultChangeMode;
         this.user = options.user;
+        this.documentRpcEnabled = documentRpcEnabled(options.env);
+        if (this.processMode === 'document' && !this.documentRpcEnabled) {
+            throw new SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN requires SUPERDOC_SDK_DOCUMENT_RPC=1.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
     }
     async connect() {
         await this.ensureConnected();
@@ -122,6 +136,33 @@ export class HostTransport {
     }
     async invoke(operation, params = {}, options = {}) {
         await this.ensureConnected();
+        if (this.documentRpcEnabled &&
+            supportsDocumentRpc(this.hostFeatures) &&
+            this.defaultChangeMode === undefined &&
+            this.user === undefined &&
+            operation.operationId === 'doc.open' &&
+            canOpenWithDocumentRpc(params, options)) {
+            const opened = buildDocumentOpenParams(params);
+            const response = await this.sendJsonRpcRequest('document.open', opened.params, this.resolveWatchdogTimeout(options.timeoutMs));
+            const result = mapDocumentOpenResult(response, opened.sessionId, params.doc);
+            this.documentRpcSessions.add(opened.sessionId);
+            return result;
+        }
+        const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
+        if (sessionId !== undefined && this.documentRpcSessions.has(sessionId)) {
+            const request = buildDocumentInvokeParams(sessionId, operation, params, options);
+            const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs));
+            const result = mapDocumentLifecycleResult(operation.operationId, response, sessionId);
+            if (operation.operationId === 'doc.close')
+                this.documentRpcSessions.delete(sessionId);
+            return result;
+        }
+        if (this.processMode === 'document') {
+            throw new SuperDocCliError(`Standalone document host does not support ${operation.operationId} through structured RPC v0.`, {
+                code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+                details: { operationId: operation.operationId },
+            });
+        }
         const argv = buildOperationArgv(operation, params, options, this.requestTimeoutMs, this.defaultChangeMode, this.user);
         const stdinBase64 = options.stdinBytes ? Buffer.from(options.stdinBytes).toString('base64') : '';
         const watchdogTimeout = this.resolveWatchdogTimeout(options.timeoutMs);
@@ -139,13 +180,13 @@ export class HostTransport {
         return resultRecord.data;
     }
     async ensureConnected() {
-        if (this.child && !this.child.killed) {
-            return;
-        }
         if (this.connecting) {
             await this.connecting;
             return;
         }
+        if (this.child && !this.child.killed) {
+            return;
+        }
         this.connecting = this.startHostProcess();
         try {
             await this.connecting;
@@ -155,8 +196,10 @@ export class HostTransport {
         }
     }
     async startHostProcess() {
-        const { command, prefixArgs } = resolveInvocation(this.cliBin);
-        const args = buildHostSpawnArgs(prefixArgs, { requestTimeoutMs: this.requestTimeoutMs });
+        const { command, prefixArgs } = resolveInvocation(this.hostBin);
+        const args = this.processMode === 'document'
+            ? buildDocumentHostSpawnArgs(prefixArgs)
+            : buildHostSpawnArgs(prefixArgs, { requestTimeoutMs: this.requestTimeoutMs });
         const child = spawn(command, args, {
             env: {
                 ...process.env,
@@ -239,7 +282,8 @@ export class HostTransport {
                 details: { features },
             });
         }
-        for (const requiredFeature of REQUIRED_FEATURES) {
+        const requiredFeatures = this.processMode === 'document' ? DOCUMENT_HOST_REQUIRED_FEATURES : CLI_HOST_REQUIRED_FEATURES;
+        for (const requiredFeature of requiredFeatures) {
             if (!features.includes(requiredFeature)) {
                 throw new SuperDocCliError(`Host does not support required feature: ${requiredFeature}`, {
                     code: 'HOST_HANDSHAKE_FAILED',
@@ -247,6 +291,9 @@ export class HostTransport {
                 });
             }
         }
+        this.hostFeatures.clear();
+        for (const feature of features)
+            this.hostFeatures.add(feature);
     }
     resolveWatchdogTimeout(timeoutMsOverride) {
         return resolveJsWatchdogTimeout(this.watchdogTimeoutMs, this.requestTimeoutMs, timeoutMsOverride);
@@ -346,6 +393,7 @@ export class HostTransport {
         const error = rawError;
         const data = error.data;
         const cliCode = typeof data?.cliCode === 'string' ? data.cliCode : undefined;
+        const domainCode = typeof data?.domainCode === 'string' ? data.domainCode : undefined;
         const cliMessage = typeof data?.message === 'string' ? data.message : undefined;
         const exitCode = typeof data?.exitCode === 'number' ? data.exitCode : undefined;
         if (cliCode) {
@@ -355,6 +403,16 @@ export class HostTransport {
                 exitCode,
             });
         }
+        if (domainCode) {
+            return new SuperDocCliError(error.message, {
+                code: domainCode,
+                details: {
+                    ...(data?.details === undefined ? {} : { domainDetails: data.details }),
+                    ...(data?.stage === undefined ? {} : { stage: data.stage }),
+                    ...(data?.byteLength === undefined ? {} : { byteLength: data.byteLength }),
+                },
+            });
+        }
         if (error.code === JSON_RPC_TIMEOUT_CODE) {
             return new SuperDocCliError(error.message, {
                 code: 'TIMEOUT',
@@ -370,6 +428,8 @@ export class HostTransport {
         this.cleanupProcess(error);
     }
     cleanupProcess(error) {
+        this.hostFeatures.clear();
+        this.documentRpcSessions.clear();
         const child = this.child;
         if (child) {
             child.removeAllListeners();

package/dist/runtime/process.cjs

@@ -3,20 +3,28 @@
 var host = require('./host.cjs');
 var embeddedCli = require('./embedded-cli.cjs');
 var debugTrace = require('./debug-trace.cjs');
+var errors = require('./errors.cjs');
 
 /**
- * Internal runtime that delegates CLI invocations to a persistent host transport.
+ * Internal runtime that delegates operations to a persistent host transport.
  *
- * Resolves the CLI binary and creates a {@link HostTransport} that communicates
- * with a long-lived `superdoc host --stdio` process.
+ * Uses the standalone document host when explicitly configured. Otherwise it
+ * preserves the embedded CLI compatibility path.
  */
 class SuperDocRuntime {
     transport;
     constructor(options = {}) {
-        const cliBin = options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? embeddedCli.resolveEmbeddedCliBinary();
+        const documentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
+        if (documentHostBin !== undefined && documentHostBin.trim().length === 0) {
+            throw new errors.SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN must be a non-empty path.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
+        const hostBin = documentHostBin ?? options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? embeddedCli.resolveEmbeddedCliBinary();
         this.transport = new host.HostTransport({
-            cliBin,
             ...options,
+            hostBin,
+            processMode: documentHostBin === undefined ? 'cli' : 'document',
         });
     }
     async connect() {

package/dist/runtime/process.d.ts

@@ -1,9 +1,9 @@
 import type { DocumentRuntimeKind, InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions } from './transport-common.js';
 /**
- * Internal runtime that delegates CLI invocations to a persistent host transport.
+ * Internal runtime that delegates operations to a persistent host transport.
  *
- * Resolves the CLI binary and creates a {@link HostTransport} that communicates
- * with a long-lived `superdoc host --stdio` process.
+ * Uses the standalone document host when explicitly configured. Otherwise it
+ * preserves the embedded CLI compatibility path.
  */
 export declare class SuperDocRuntime {
     private readonly transport;

package/dist/runtime/process.js

@@ -1,19 +1,27 @@
 import { HostTransport } from './host.js';
 import { resolveEmbeddedCliBinary } from './embedded-cli.js';
 import { writeSdkDebugTrace } from './debug-trace.js';
+import { SuperDocCliError } from './errors.js';
 /**
- * Internal runtime that delegates CLI invocations to a persistent host transport.
+ * Internal runtime that delegates operations to a persistent host transport.
  *
- * Resolves the CLI binary and creates a {@link HostTransport} that communicates
- * with a long-lived `superdoc host --stdio` process.
+ * Uses the standalone document host when explicitly configured. Otherwise it
+ * preserves the embedded CLI compatibility path.
  */
 export class SuperDocRuntime {
     transport;
     constructor(options = {}) {
-        const cliBin = options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? resolveEmbeddedCliBinary();
+        const documentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
+        if (documentHostBin !== undefined && documentHostBin.trim().length === 0) {
+            throw new SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN must be a non-empty path.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
+        const hostBin = documentHostBin ?? options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? resolveEmbeddedCliBinary();
         this.transport = new HostTransport({
-            cliBin,
             ...options,
+            hostBin,
+            processMode: documentHostBin === undefined ? 'cli' : 'document',
         });
     }
     async connect() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/sdk",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Node SDK for SuperDoc, wrapping the SuperDoc CLI to read and edit .docx files from JavaScript and TypeScript.",
   "private": false,
   "license": "AGPL-3.0",
@@ -37,11 +37,11 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc/sdk-darwin-arm64": "2.5.0",
-    "@superdoc/sdk-linux-x64": "2.5.0",
-    "@superdoc/sdk-linux-arm64": "2.5.0",
-    "@superdoc/sdk-darwin-x64": "2.5.0",
-    "@superdoc/sdk-windows-x64": "2.5.0"
+    "@superdoc/sdk-darwin-arm64": "2.6.0",
+    "@superdoc/sdk-linux-x64": "2.6.0",
+    "@superdoc/sdk-darwin-x64": "2.6.0",
+    "@superdoc/sdk-linux-arm64": "2.6.0",
+    "@superdoc/sdk-windows-x64": "2.6.0"
   },
   "publishConfig": {
     "access": "public"
@@ -50,6 +50,7 @@
     "build": "rm -rf dist && node scripts/embed-prompts.mjs && node scripts/embed-tools.mjs && tsc && rollup -c rollup.cjs.config.mjs && rm -rf dist/prompts && mkdir -p dist/prompts && cp src/prompts/*.md dist/prompts/ && pnpm run audit:publish",
     "audit:publish": "node ../../../../scripts/audit-publish-artifact.mjs dist --label sdk-node-dist",
     "typecheck": "tsc --noEmit",
+    "test:document-host": "bun test src/runtime/__tests__/host-spawn-args.test.ts src/runtime/__tests__/document-rpc.test.ts src/__tests__/structured-document-rpc.e2e.test.ts src/__tests__/request-timeout-ms.e2e.test.ts",
     "smoke:product-action": "node scripts/product-action-smoke.mjs"
   }
 }

package/tools/catalog.json

@@ -5,7 +5,7 @@
   "tools": [
     {
       "toolName": "superdoc_get_content",
-      "description": "Read document content in various formats. Call this first in any workflow to understand document structure before making edits. Action \"blocks\" returns structured block data with nodeId, nodeType, textPreview, optional full text when includeText:true, formatting properties (fontFamily, fontSize, color, bold, underline, alignment), and ref handles for immediate use with superdoc_edit or superdoc_format. When you need to evaluate or rewrite existing paragraphs or clauses, prefer action \"blocks\" with includeText:true so you can identify the correct block and then target it by nodeId. Actions \"text\", \"markdown\", and \"html\" return compact strings. Actions \"markdown_projection\" and \"html_projection\" return detailed async projections with review modes, scopes, diagnostics, annotations, block maps, and optional source maps. Projection source targets use tracked coordinates and are valid only at evaluatedRevision; after any mutation, reproject before using them. Treat omitted or partially emitted annotations according to their status instead of guessing an anchor from rendered text. Action \"info\" returns document metadata: word count, paragraph count, page count, outline, available styles, and capability flags. The \"blocks\" action supports pagination via \"offset\" and \"limit\", and filtering via \"nodeTypes\". Other actions ignore these parameters. This tool never modifies the document. Do NOT call superdoc_edit or superdoc_format without first reading blocks to get valid refs and formatting reference values.\n\nEXAMPLES:\n  1. {\"action\":\"blocks\"}\n  2. {\"action\":\"blocks\",\"includeText\":true,\"offset\":0,\"limit\":20}\n  3. {\"action\":\"blocks\",\"offset\":0,\"limit\":20,\"nodeTypes\":[\"heading\",\"paragraph\"]}\n  4. {\"action\":\"text\"}\n  5. {\"action\":\"info\"}\n  6. {\"action\":\"html_projection\",\"reviewMode\":\"redline\",\"includeSourceMap\":true}\n  7. {\"action\":\"markdown_projection\",\"reviewMode\":\"original\",\"scope\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"paragraph-id\"},\"includeSourceMap\":true}",
+      "description": "Read document content in various formats. Call this first in any workflow to understand document structure before making edits. Action \"blocks\" returns structured block data with nodeId, nodeType, textPreview, optional full text when includeText:true, formatting properties (fontFamily, fontSize, color, bold, underline, alignment), and ref handles for immediate use with superdoc_edit or superdoc_format. Its optional reviewMode selects final, original, or redline numbering metadata without filtering blocks. When you need to evaluate or rewrite existing paragraphs or clauses, prefer action \"blocks\" with includeText:true so you can identify the correct block and then target it by nodeId. Actions \"text\", \"markdown\", and \"html\" return compact strings. Actions \"markdown_projection\" and \"html_projection\" return detailed async projections with review modes, scopes, diagnostics, annotations, block maps, and optional source maps. Projection source targets use tracked coordinates and are valid only at evaluatedRevision; after any mutation, reproject before using them. Treat omitted or partially emitted annotations according to their status instead of guessing an anchor from rendered text. Action \"info\" returns document metadata: word count, paragraph count, page count, outline, available styles, and capability flags. The \"blocks\" action supports pagination via \"offset\" and \"limit\", filtering via \"nodeTypes\", and numbering projection via \"reviewMode\". Other actions ignore pagination and filtering parameters. This tool never modifies the document. Do NOT call superdoc_edit or superdoc_format without first reading blocks to get valid refs and formatting reference values.\n\nEXAMPLES:\n  1. {\"action\":\"blocks\"}\n  2. {\"action\":\"blocks\",\"includeText\":true,\"offset\":0,\"limit\":20,\"reviewMode\":\"final\"}\n  3. {\"action\":\"blocks\",\"offset\":0,\"limit\":20,\"nodeTypes\":[\"heading\",\"paragraph\"]}\n  4. {\"action\":\"text\"}\n  5. {\"action\":\"info\"}\n  6. {\"action\":\"html_projection\",\"reviewMode\":\"redline\",\"includeSourceMap\":true}\n  7. {\"action\":\"markdown_projection\",\"reviewMode\":\"original\",\"scope\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"paragraph-id\"},\"includeSourceMap\":true}",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -33,7 +33,7 @@
           },
           "reviewMode": {
             "$ref": "#/$defs/SDProjectionReviewMode",
-            "description": "Only for actions 'markdown_projection', 'html_projection'. Omit for other actions."
+            "description": "Only for actions 'markdown_projection', 'html_projection', 'blocks'. Omit for other actions."
           },
           "scope": {
             "$ref": "#/$defs/SDProjectionScope",

package/tools/tools-policy.json

@@ -43,5 +43,5 @@
       "mutates": true
     }
   ],
-  "contractHash": "bfefe3880487f715579f3ba1bf11d94dd1af4151131b780a7d26dae65ca8c38e"
+  "contractHash": "5967b3cb6c6ca5f65dd887d1c3b2908478e47ac6a2b76f7b2bb207f3b5b21324"
 }

package/tools/tools.anthropic.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "superdoc_get_content",
-      "description": "Read document content in various formats. Call this first in any workflow to understand document structure before making edits. Action \"blocks\" returns structured block data with nodeId, nodeType, textPreview, optional full text when includeText:true, formatting properties (fontFamily, fontSize, color, bold, underline, alignment), and ref handles for immediate use with superdoc_edit or superdoc_format. When you need to evaluate or rewrite existing paragraphs or clauses, prefer action \"blocks\" with includeText:true so you can identify the correct block and then target it by nodeId. Actions \"text\", \"markdown\", and \"html\" return compact strings. Actions \"markdown_projection\" and \"html_projection\" return detailed async projections with review modes, scopes, diagnostics, annotations, block maps, and optional source maps. Projection source targets use tracked coordinates and are valid only at evaluatedRevision; after any mutation, reproject before using them. Treat omitted or partially emitted annotations according to their status instead of guessing an anchor from rendered text. Action \"info\" returns document metadata: word count, paragraph count, page count, outline, available styles, and capability flags. The \"blocks\" action supports pagination via \"offset\" and \"limit\", and filtering via \"nodeTypes\". Other actions ignore these parameters. This tool never modifies the document. Do NOT call superdoc_edit or superdoc_format without first reading blocks to get valid refs and formatting reference values.\n\nEXAMPLES:\n  1. {\"action\":\"blocks\"}\n  2. {\"action\":\"blocks\",\"includeText\":true,\"offset\":0,\"limit\":20}\n  3. {\"action\":\"blocks\",\"offset\":0,\"limit\":20,\"nodeTypes\":[\"heading\",\"paragraph\"]}\n  4. {\"action\":\"text\"}\n  5. {\"action\":\"info\"}\n  6. {\"action\":\"html_projection\",\"reviewMode\":\"redline\",\"includeSourceMap\":true}\n  7. {\"action\":\"markdown_projection\",\"reviewMode\":\"original\",\"scope\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"paragraph-id\"},\"includeSourceMap\":true}",
+      "description": "Read document content in various formats. Call this first in any workflow to understand document structure before making edits. Action \"blocks\" returns structured block data with nodeId, nodeType, textPreview, optional full text when includeText:true, formatting properties (fontFamily, fontSize, color, bold, underline, alignment), and ref handles for immediate use with superdoc_edit or superdoc_format. Its optional reviewMode selects final, original, or redline numbering metadata without filtering blocks. When you need to evaluate or rewrite existing paragraphs or clauses, prefer action \"blocks\" with includeText:true so you can identify the correct block and then target it by nodeId. Actions \"text\", \"markdown\", and \"html\" return compact strings. Actions \"markdown_projection\" and \"html_projection\" return detailed async projections with review modes, scopes, diagnostics, annotations, block maps, and optional source maps. Projection source targets use tracked coordinates and are valid only at evaluatedRevision; after any mutation, reproject before using them. Treat omitted or partially emitted annotations according to their status instead of guessing an anchor from rendered text. Action \"info\" returns document metadata: word count, paragraph count, page count, outline, available styles, and capability flags. The \"blocks\" action supports pagination via \"offset\" and \"limit\", filtering via \"nodeTypes\", and numbering projection via \"reviewMode\". Other actions ignore pagination and filtering parameters. This tool never modifies the document. Do NOT call superdoc_edit or superdoc_format without first reading blocks to get valid refs and formatting reference values.\n\nEXAMPLES:\n  1. {\"action\":\"blocks\"}\n  2. {\"action\":\"blocks\",\"includeText\":true,\"offset\":0,\"limit\":20,\"reviewMode\":\"final\"}\n  3. {\"action\":\"blocks\",\"offset\":0,\"limit\":20,\"nodeTypes\":[\"heading\",\"paragraph\"]}\n  4. {\"action\":\"text\"}\n  5. {\"action\":\"info\"}\n  6. {\"action\":\"html_projection\",\"reviewMode\":\"redline\",\"includeSourceMap\":true}\n  7. {\"action\":\"markdown_projection\",\"reviewMode\":\"original\",\"scope\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"paragraph-id\"},\"includeSourceMap\":true}",
       "input_schema": {
         "type": "object",
         "properties": {
@@ -31,7 +31,7 @@
           },
           "reviewMode": {
             "$ref": "#/$defs/SDProjectionReviewMode",
-            "description": "Only for actions 'markdown_projection', 'html_projection'. Omit for other actions."
+            "description": "Only for actions 'markdown_projection', 'html_projection', 'blocks'. Omit for other actions."
           },
           "scope": {
             "$ref": "#/$defs/SDProjectionScope",

package/tools/tools.generic.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "superdoc_get_content",
-      "description": "Read document content in various formats. Call this first in any workflow to understand document structure before making edits. Action \"blocks\" returns structured block data with nodeId, nodeType, textPreview, optional full text when includeText:true, formatting properties (fontFamily, fontSize, color, bold, underline, alignment), and ref handles for immediate use with superdoc_edit or superdoc_format. When you need to evaluate or rewrite existing paragraphs or clauses, prefer action \"blocks\" with includeText:true so you can identify the correct block and then target it by nodeId. Actions \"text\", \"markdown\", and \"html\" return compact strings. Actions \"markdown_projection\" and \"html_projection\" return detailed async projections with review modes, scopes, diagnostics, annotations, block maps, and optional source maps. Projection source targets use tracked coordinates and are valid only at evaluatedRevision; after any mutation, reproject before using them. Treat omitted or partially emitted annotations according to their status instead of guessing an anchor from rendered text. Action \"info\" returns document metadata: word count, paragraph count, page count, outline, available styles, and capability flags. The \"blocks\" action supports pagination via \"offset\" and \"limit\", and filtering via \"nodeTypes\". Other actions ignore these parameters. This tool never modifies the document. Do NOT call superdoc_edit or superdoc_format without first reading blocks to get valid refs and formatting reference values.\n\nEXAMPLES:\n  1. {\"action\":\"blocks\"}\n  2. {\"action\":\"blocks\",\"includeText\":true,\"offset\":0,\"limit\":20}\n  3. {\"action\":\"blocks\",\"offset\":0,\"limit\":20,\"nodeTypes\":[\"heading\",\"paragraph\"]}\n  4. {\"action\":\"text\"}\n  5. {\"action\":\"info\"}\n  6. {\"action\":\"html_projection\",\"reviewMode\":\"redline\",\"includeSourceMap\":true}\n  7. {\"action\":\"markdown_projection\",\"reviewMode\":\"original\",\"scope\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"paragraph-id\"},\"includeSourceMap\":true}",
+      "description": "Read document content in various formats. Call this first in any workflow to understand document structure before making edits. Action \"blocks\" returns structured block data with nodeId, nodeType, textPreview, optional full text when includeText:true, formatting properties (fontFamily, fontSize, color, bold, underline, alignment), and ref handles for immediate use with superdoc_edit or superdoc_format. Its optional reviewMode selects final, original, or redline numbering metadata without filtering blocks. When you need to evaluate or rewrite existing paragraphs or clauses, prefer action \"blocks\" with includeText:true so you can identify the correct block and then target it by nodeId. Actions \"text\", \"markdown\", and \"html\" return compact strings. Actions \"markdown_projection\" and \"html_projection\" return detailed async projections with review modes, scopes, diagnostics, annotations, block maps, and optional source maps. Projection source targets use tracked coordinates and are valid only at evaluatedRevision; after any mutation, reproject before using them. Treat omitted or partially emitted annotations according to their status instead of guessing an anchor from rendered text. Action \"info\" returns document metadata: word count, paragraph count, page count, outline, available styles, and capability flags. The \"blocks\" action supports pagination via \"offset\" and \"limit\", filtering via \"nodeTypes\", and numbering projection via \"reviewMode\". Other actions ignore pagination and filtering parameters. This tool never modifies the document. Do NOT call superdoc_edit or superdoc_format without first reading blocks to get valid refs and formatting reference values.\n\nEXAMPLES:\n  1. {\"action\":\"blocks\"}\n  2. {\"action\":\"blocks\",\"includeText\":true,\"offset\":0,\"limit\":20,\"reviewMode\":\"final\"}\n  3. {\"action\":\"blocks\",\"offset\":0,\"limit\":20,\"nodeTypes\":[\"heading\",\"paragraph\"]}\n  4. {\"action\":\"text\"}\n  5. {\"action\":\"info\"}\n  6. {\"action\":\"html_projection\",\"reviewMode\":\"redline\",\"includeSourceMap\":true}\n  7. {\"action\":\"markdown_projection\",\"reviewMode\":\"original\",\"scope\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"paragraph-id\"},\"includeSourceMap\":true}",
       "parameters": {
         "type": "object",
         "properties": {
@@ -31,7 +31,7 @@
           },
           "reviewMode": {
             "$ref": "#/$defs/SDProjectionReviewMode",
-            "description": "Only for actions 'markdown_projection', 'html_projection'. Omit for other actions."
+            "description": "Only for actions 'markdown_projection', 'html_projection', 'blocks'. Omit for other actions."
           },
           "scope": {
             "$ref": "#/$defs/SDProjectionScope",