@superdoc/sdk 2.5.0 → 2.7.0

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, DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE, DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE, buildDocumentInvokeParams, buildDocumentOpenParams, canOpenWithDocumentRpc, documentRpcRequestSupportsResponseTimeout, 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'
@@ -18,6 +20,21 @@ const HOST_DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 // abort. The buffer absorbs JSON-RPC serialization, stdio drain, and event-
 // loop latency.
 const WATCHDOG_HEADROOM_MS = 5_000;
+export function mapCliInvocationResult(operation, value) {
+    const envelopeKey = operation.responseEnvelopeKey;
+    if (envelopeKey === null || envelopeKey === undefined)
+        return value;
+    if (typeof envelopeKey !== 'string' || envelopeKey.length === 0) {
+        throw new SuperDocCliError('Generated operation has invalid response envelope metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { operationId: operation.operationId, responseEnvelopeKey: envelopeKey },
+        });
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return value;
+    const extracted = value[envelopeKey];
+    return extracted === undefined ? value : extracted;
+}
 /**
  * Builds the argv passed to `spawn` for `superdoc host --stdio`. Propagates
  * `requestTimeoutMs` to the host via `--request-timeout-ms`, since the SDK
@@ -32,6 +49,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 +77,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 +89,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;
@@ -90,8 +113,9 @@ export class HostTransport {
                 details: { defaultChangeMode: options.defaultChangeMode },
             });
         }
-        this.defaultChangeMode = options.defaultChangeMode;
+        this.defaultChangeMode = options.defaultChangeMode ?? undefined;
         this.user = options.user;
+        this.documentRpcEnabled = this.processMode === 'document' || documentRpcEnabled(options.env);
     }
     async connect() {
         await this.ensureConnected();
@@ -122,6 +146,53 @@ export class HostTransport {
     }
     async invoke(operation, params = {}, options = {}) {
         await this.ensureConnected();
+        const shouldOpenThroughCliTimeoutFallback = this.processMode === 'cli' &&
+            (this.requestTimeoutMs !== undefined ||
+                (options.timeoutMs !== undefined && !this.hostFeatures.has(DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE)));
+        if (this.documentRpcEnabled &&
+            supportsDocumentRpc(this.hostFeatures) &&
+            (this.defaultChangeMode === undefined || this.hostFeatures.has(DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE)) &&
+            operation.operationId === 'doc.open' &&
+            canOpenWithDocumentRpc(params, options) &&
+            !shouldOpenThroughCliTimeoutFallback) {
+            const opened = buildDocumentOpenParams(params, this.user, this.defaultChangeMode);
+            const requestTimeoutMs = this.resolveDocumentRequestTimeout(options.timeoutMs);
+            const response = await this.sendJsonRpcRequest('document.open', opened.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
+            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, this.hostFeatures);
+            const supportsResponseTimeout = documentRpcRequestSupportsResponseTimeout(operation, request);
+            const requestTimeoutMs = supportsResponseTimeout
+                ? this.resolveDocumentRequestTimeout(options.timeoutMs)
+                : undefined;
+            const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
+            const result = mapDocumentLifecycleResult(operation.operationId, response, sessionId, operation.operationId === 'doc.save' ? request.params.path === undefined : undefined);
+            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 cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
+        if (options.timeoutMs !== undefined && options.timeoutMs > cliHostRequestTimeoutMs) {
+            throw new SuperDocCliError(`CLI host cannot honor timeoutMs=${options.timeoutMs} above its ${cliHostRequestTimeoutMs}ms request ceiling.`, {
+                code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+                details: {
+                    feature: DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE,
+                    operationId: operation.operationId,
+                    timeoutMs: options.timeoutMs,
+                    hostRequestTimeoutMs: cliHostRequestTimeoutMs,
+                },
+            });
+        }
         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);
@@ -136,16 +207,16 @@ export class HostTransport {
             });
         }
         const resultRecord = response;
-        return resultRecord.data;
+        return mapCliInvocationResult(operation, 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,12 +226,14 @@ 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,
-                ...(this.env ?? {}),
+                ...this.env,
             },
             stdio: ['pipe', 'pipe', 'pipe'],
         });
@@ -239,7 +312,14 @@ export class HostTransport {
                 details: { features },
             });
         }
-        for (const requiredFeature of REQUIRED_FEATURES) {
+        const requiredFeatures = this.processMode === 'document'
+            ? [
+                ...DOCUMENT_HOST_REQUIRED_FEATURES,
+                ...(this.defaultChangeMode === undefined ? [] : [DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE]),
+                ...(this.requestTimeoutMs === undefined ? [] : [DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE]),
+            ]
+            : 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,11 +327,27 @@ export class HostTransport {
                 });
             }
         }
+        this.hostFeatures.clear();
+        for (const feature of features)
+            this.hostFeatures.add(feature);
     }
     resolveWatchdogTimeout(timeoutMsOverride) {
         return resolveJsWatchdogTimeout(this.watchdogTimeoutMs, this.requestTimeoutMs, timeoutMsOverride);
     }
-    async sendJsonRpcRequest(method, params, watchdogTimeoutMs) {
+    resolveDocumentRequestTimeout(timeoutMsOverride) {
+        const requestTimeoutMs = timeoutMsOverride ?? this.requestTimeoutMs;
+        if (requestTimeoutMs === undefined)
+            return undefined;
+        if (this.hostFeatures.has(DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE))
+            return requestTimeoutMs;
+        if (this.processMode === 'cli' && timeoutMsOverride === undefined)
+            return undefined;
+        throw new SuperDocCliError(`Structured document RPC host does not support ${DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE}.`, {
+            code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+            details: { feature: DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE },
+        });
+    }
+    async sendJsonRpcRequest(method, params, watchdogTimeoutMs, metadata = {}) {
         const child = this.child;
         if (!child || !child.stdin.writable) {
             throw new SuperDocCliError('Host process is not available.', {
@@ -271,6 +367,7 @@ export class HostTransport {
             id,
             method,
             params,
+            ...(metadata.requestTimeoutMs === undefined ? {} : { requestTimeoutMs: metadata.requestTimeoutMs }),
         });
         const promise = new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -346,6 +443,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 +453,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 +478,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

@@ -2,21 +2,49 @@
 
 var host = require('./host.cjs');
 var embeddedCli = require('./embedded-cli.cjs');
+var embeddedDocumentHost = require('./embedded-document-host.cjs');
 var debugTrace = require('./debug-trace.cjs');
+var errors = require('./errors.cjs');
 
+function resolveRuntimeProcess(options = {}, embedded = {
+    cli: embeddedCli.resolveEmbeddedCliBinary,
+    documentHost: embeddedDocumentHost.resolveEmbeddedDocumentHostBinary,
+}) {
+    const configuredDocumentHostPath = options.documentHostPath;
+    if (configuredDocumentHostPath !== undefined && configuredDocumentHostPath.trim().length === 0) {
+        throw new errors.SuperDocCliError('documentHostPath must be a non-empty path.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const configuredDocumentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
+    const documentHostBin = configuredDocumentHostPath ??
+        (configuredDocumentHostBin === 'embedded' ? embedded.documentHost() : configuredDocumentHostBin);
+    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',
+        });
+    }
+    if (documentHostBin !== undefined) {
+        return { hostBin: documentHostBin, processMode: 'document' };
+    }
+    return {
+        hostBin: options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? embedded.cli(),
+        processMode: 'cli',
+    };
+}
 /**
- * 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 runtimeProcess = resolveRuntimeProcess(options);
         this.transport = new host.HostTransport({
-            cliBin,
             ...options,
+            ...runtimeProcess,
         });
     }
     async connect() {
@@ -59,3 +87,4 @@ class SuperDocRuntime {
 }
 
 exports.SuperDocRuntime = SuperDocRuntime;
+exports.resolveRuntimeProcess = resolveRuntimeProcess;

package/dist/runtime/process.d.ts

@@ -1,9 +1,18 @@
 import type { DocumentRuntimeKind, InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions } from './transport-common.js';
+type RuntimeProcessResolution = {
+    hostBin: string;
+    processMode: 'cli' | 'document';
+};
+type EmbeddedRuntimeResolvers = {
+    cli: () => string;
+    documentHost: () => string;
+};
+export declare function resolveRuntimeProcess(options?: SuperDocClientOptions, embedded?: EmbeddedRuntimeResolvers): RuntimeProcessResolution;
 /**
- * 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,47 @@
 import { HostTransport } from './host.js';
 import { resolveEmbeddedCliBinary } from './embedded-cli.js';
+import { resolveEmbeddedDocumentHostBinary } from './embedded-document-host.js';
 import { writeSdkDebugTrace } from './debug-trace.js';
+import { SuperDocCliError } from './errors.js';
+export function resolveRuntimeProcess(options = {}, embedded = {
+    cli: resolveEmbeddedCliBinary,
+    documentHost: resolveEmbeddedDocumentHostBinary,
+}) {
+    const configuredDocumentHostPath = options.documentHostPath;
+    if (configuredDocumentHostPath !== undefined && configuredDocumentHostPath.trim().length === 0) {
+        throw new SuperDocCliError('documentHostPath must be a non-empty path.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const configuredDocumentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
+    const documentHostBin = configuredDocumentHostPath ??
+        (configuredDocumentHostBin === 'embedded' ? embedded.documentHost() : configuredDocumentHostBin);
+    if (documentHostBin !== undefined && documentHostBin.trim().length === 0) {
+        throw new SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN must be a non-empty path.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (documentHostBin !== undefined) {
+        return { hostBin: documentHostBin, processMode: 'document' };
+    }
+    return {
+        hostBin: options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? embedded.cli(),
+        processMode: 'cli',
+    };
+}
 /**
- * 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 runtimeProcess = resolveRuntimeProcess(options);
         this.transport = new HostTransport({
-            cliBin,
             ...options,
+            ...runtimeProcess,
         });
     }
     async connect() {

package/dist/runtime/transport-common.cjs

@@ -163,5 +163,6 @@ function buildOperationArgv(operation, params, options, runtimeTimeoutMs, defaul
     return argv;
 }
 
+exports.applyOperationParamAliases = applyOperationParamAliases;
 exports.buildOperationArgv = buildOperationArgv;
 exports.resolveInvocation = resolveInvocation;

package/dist/runtime/transport-common.d.ts

@@ -34,6 +34,14 @@ export interface UserIdentity {
 }
 export interface SuperDocClientOptions {
     env?: Record<string, string | undefined>;
+    /**
+     * Standalone document-host entry to use instead of the embedded CLI.
+     *
+     * The host-only path supports local lifecycle methods and generated Document
+     * API operations through structured RPC. Interface-only conveniences fail
+     * without CLI fallback.
+     */
+    documentHostPath?: string;
     /**
      * Default document engine for `client.open(...)`. Explicit `runtime` on an
      * individual open call takes precedence.
@@ -42,11 +50,13 @@ export interface SuperDocClientOptions {
     startupTimeoutMs?: number;
     shutdownTimeoutMs?: number;
     /**
-     * Upper bound (ms) on how long the host process may spend on a single
-     * `cli.invoke` request before it kills the operation and returns a
-     * `RequestTimeout` error. Propagated to the host via `--request-timeout-ms`
-     * at spawn. Raise this for documents that legitimately need more than 30s
-     * to process; the SDK widens its own JSON-RPC watchdog to match.
+     * Upper bound (ms) on how long the host process may spend on a request
+     * before it returns a `RequestTimeout` error. Retry-safe structured document
+     * requests carry this budget as transport metadata; requests that may apply
+     * non-idempotent side effects await a definitive result instead. CLI-host
+     * requests also receive the budget through `--request-timeout-ms` at spawn.
+     * Raise this for documents that legitimately need more than 30s to process;
+     * the SDK widens its own JSON-RPC watchdog to match.
      *
      * Defaults to the host's own default (30s) when unset.
      */
@@ -54,11 +64,13 @@ export interface SuperDocClientOptions {
     /**
      * JS-side watchdog (ms) the SDK waits for a host reply before giving up.
      * Independent of {@link requestTimeoutMs} (which controls the host-side
-     * operation budget). Most callers should leave this at its default and use
-     * {@link requestTimeoutMs} as the single operation-timeout knob —
-     * `resolveWatchdogTimeout` already widens the watchdog above the host
-     * ceiling automatically. Override only when you need to detect a hung or
-     * crashed host faster than the operation budget allows.
+     * operation budget). Structured requests that may apply non-idempotent side
+     * effects wait for a definitive host result instead of applying an unsafe
+     * response deadline. Most callers should leave this at its default and use
+     * {@link requestTimeoutMs} as the single timeout knob for retry-safe work —
+     * `resolveWatchdogTimeout` already widens the watchdog above the host ceiling
+     * automatically. Override only when you need to detect a hung or crashed host
+     * faster than the operation budget allows.
      */
     watchdogTimeoutMs?: number;
     maxQueueDepth?: number;
@@ -70,6 +82,12 @@ export interface CliInvocation {
     prefixArgs: string[];
 }
 export declare function resolveInvocation(cliBin: string): CliInvocation;
+/**
+ * Resolve contract-shaped param aliases onto their canonical generated names.
+ * Returns the same object when no alias applies. Throws on a conflicting
+ * canonical/alias pair so divergent values can never be silently coalesced.
+ */
+export declare function applyOperationParamAliases(operation: OperationSpec, params: Record<string, unknown>): Record<string, unknown>;
 /**
  * Build the CLI argument vector for an operation invocation.
  *

package/dist/runtime/transport-common.js

@@ -54,7 +54,7 @@ function assertKnownTemplatesApplyParams(operation, params) {
  * Returns the same object when no alias applies. Throws on a conflicting
  * canonical/alias pair so divergent values can never be silently coalesced.
  */
-function applyOperationParamAliases(operation, params) {
+export function applyOperationParamAliases(operation, params) {
     const aliasMap = OPERATION_PARAM_ALIASES[operation.operationId];
     if (!aliasMap)
         return params;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/sdk",
-  "version": "2.5.0",
+  "version": "2.7.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.7.0",
+    "@superdoc/sdk-darwin-x64": "2.7.0",
+    "@superdoc/sdk-linux-x64": "2.7.0",
+    "@superdoc/sdk-linux-arm64": "2.7.0",
+    "@superdoc/sdk-windows-x64": "2.7.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": "570f35bff614f42af4610ad37ad4d21d776cdf8e3515c206d25d50c0102d7484"
 }

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",