@superdoc/sdk 2.6.0 → 2.8.0

package/dist/runtime/document-rpc.js

@@ -1,17 +1,17 @@
 import { randomUUID } from 'node:crypto';
 import { SuperDocCliError } from './errors.js';
+import { applyOperationParamAliases, } from './transport-common.js';
 export const DOCUMENT_RPC_FEATURES = ['document.open', 'document.invoke', 'document.save', 'document.close'];
-const DOCUMENT_RPC_V0_OPERATIONS = new Set(['doc.getText', 'doc.insert', 'doc.save', 'doc.close']);
+export const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = 'document.open.defaultChangeMode';
+export const DOCUMENT_RPC_SOURCE_SAVE_FEATURE = 'document.save.source';
+export const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = 'host.request.timeoutMs';
 const DOCUMENT_RPC_OPEN_FIELDS = new Set(['doc', 'sessionId', 'runtime']);
-const DOCUMENT_RPC_INSERT_FIELDS = new Set([
-    'value',
-    'type',
-    'target',
-    'ref',
-    'in',
-    'placement',
-    'content',
-    'nestingPolicy',
+const DOCUMENT_RPC_SAVE_FIELDS = new Set(['sessionId', 'out', 'force', 'mode', 'inPlace']);
+const DOCUMENT_API_OPTION_FIELDS = new Set(['expectedRevision', 'changeMode', 'dryRun', 'supportCheck']);
+const DOCUMENT_API_REVISION_PREFLIGHT_OPERATIONS = new Set([
+    'doc.history.redo',
+    'doc.history.undo',
+    'doc.plan.execute',
 ]);
 function unsupported(message, operationId) {
     return new SuperDocCliError(message, {
@@ -19,21 +19,42 @@ function unsupported(message, operationId) {
         ...(operationId === undefined ? {} : { details: { operationId } }),
     });
 }
+function buildDocumentAuthor(user) {
+    if (user === undefined)
+        return undefined;
+    if (typeof user !== 'object' || user === null || Array.isArray(user)) {
+        throw new SuperDocCliError('user must be an object with a non-empty name.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const record = user;
+    if (typeof record.name !== 'string' || record.name.trim().length === 0) {
+        throw new SuperDocCliError('user.name must be a non-empty string.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (record.email !== undefined && typeof record.email !== 'string') {
+        throw new SuperDocCliError('user.email must be a string.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    return {
+        name: record.name,
+        ...(record.email === undefined ? {} : { email: record.email }),
+    };
+}
 export function documentRpcEnabled(env) {
     return (env?.SUPERDOC_SDK_DOCUMENT_RPC ?? process.env.SUPERDOC_SDK_DOCUMENT_RPC) === '1';
 }
 export function supportsDocumentRpc(features) {
     return DOCUMENT_RPC_FEATURES.every((feature) => features.has(feature));
 }
-function hasUnsupportedInvokeOptions(options) {
-    return (options.stdinBytes !== undefined ||
-        options.dryRun !== undefined ||
-        options.expectedRevision !== undefined ||
-        options.changeMode !== undefined);
-}
 export function canOpenWithDocumentRpc(params, options) {
-    if (hasUnsupportedInvokeOptions(options))
+    if (options.stdinBytes !== undefined)
+        return false;
+    if (options.dryRun !== undefined || options.expectedRevision !== undefined || options.changeMode !== undefined) {
         return false;
+    }
     if (typeof params.doc !== 'string' || params.doc.trim().length === 0 || params.doc === '-')
         return false;
     if (params.runtime !== undefined && params.runtime !== 'v2')
@@ -43,11 +64,17 @@ export function canOpenWithDocumentRpc(params, options) {
     }
     return Object.entries(params).every(([key, value]) => value === undefined || DOCUMENT_RPC_OPEN_FIELDS.has(key));
 }
-export function buildDocumentOpenParams(params) {
+export function buildDocumentOpenParams(params, user, defaultChangeMode) {
     const sessionId = typeof params.sessionId === 'string' && params.sessionId.length > 0 ? params.sessionId : randomUUID();
+    const author = buildDocumentAuthor(user);
     return {
         sessionId,
-        params: { sessionId, path: params.doc },
+        params: {
+            sessionId,
+            path: params.doc,
+            ...(author === undefined ? {} : { author }),
+            ...(defaultChangeMode == null ? {} : { defaultChangeMode }),
+        },
     };
 }
 export function mapDocumentOpenResult(response, sessionId, path) {
@@ -73,37 +100,120 @@ export function mapDocumentOpenResult(response, sessionId, path) {
         dirty: false,
     };
 }
-function documentInvokeInput(operationId, params) {
-    const allowedFields = operationId === 'doc.getText' ? new Set(['in']) : DOCUMENT_RPC_INSERT_FIELDS;
-    const input = Object.fromEntries(Object.entries(params).filter(([key, value]) => value !== undefined && key !== 'doc' && key !== 'sessionId'));
-    const unsupportedField = Object.keys(input).find((key) => !allowedFields.has(key));
-    if (unsupportedField) {
-        throw unsupported(`Structured document RPC v0 does not support ${operationId} field ${unsupportedField}.`, operationId);
-    }
-    return input;
+function supportsTrackedMode(operation) {
+    return operation.supportsTrackedMode === true || operation.supportsConditionalTrackedMode === true;
 }
-export function buildDocumentInvokeParams(sessionId, operation, params, options) {
-    if (!DOCUMENT_RPC_V0_OPERATIONS.has(operation.operationId)) {
-        throw unsupported(`Structured document RPC does not support ${operation.operationId} in v0.`, operation.operationId);
+function documentInvokePayload(operation, params, invokeOptions) {
+    const normalizedParams = applyOperationParamAliases(operation, params);
+    if (invokeOptions.stdinBytes !== undefined) {
+        throw unsupported('Structured document RPC does not support stdinBytes.', operation.operationId);
+    }
+    if (typeof normalizedParams.out === 'string' && normalizedParams.out.length > 0) {
+        throw unsupported('Structured document RPC does not support per-operation output paths.', operation.operationId);
+    }
+    if (normalizedParams.force === true) {
+        throw unsupported('Structured document RPC does not support per-operation force.', operation.operationId);
+    }
+    const input = {};
+    const options = {};
+    const paramsByName = new Map(operation.params.map((param) => [param.name, param]));
+    for (const [name, value] of Object.entries(normalizedParams)) {
+        if (value === undefined || name === 'doc' || name === 'sessionId' || name === 'out' || name === 'force')
+            continue;
+        const param = paramsByName.get(name);
+        if (!param) {
+            throw unsupported(`Structured document RPC does not support ${operation.operationId} field ${name}.`, operation.operationId);
+        }
+        if (typeof param.documentApiInputName === 'string' && param.documentApiInputName.length > 0) {
+            input[param.documentApiInputName] = value;
+            continue;
+        }
+        if (DOCUMENT_API_OPTION_FIELDS.has(name)) {
+            options[name] = value;
+            continue;
+        }
+        throw unsupported(`Structured document RPC does not support ${operation.operationId} field ${name}.`, operation.operationId);
     }
-    if (hasUnsupportedInvokeOptions(options)) {
-        throw unsupported('Structured document RPC v0 does not support document mutation options.', operation.operationId);
+    for (const name of ['expectedRevision', 'changeMode', 'dryRun']) {
+        const value = invokeOptions[name];
+        if (value === undefined || normalizedParams[name] !== undefined)
+            continue;
+        const projectedValue = name === 'expectedRevision' ? String(value) : value;
+        const param = paramsByName.get(name);
+        if (typeof param?.documentApiInputName === 'string' && param.documentApiInputName.length > 0) {
+            input[param.documentApiInputName] = projectedValue;
+        }
+        else {
+            options[name] = projectedValue;
+        }
+    }
+    if (options.changeMode !== undefined && !supportsTrackedMode(operation)) {
+        if (options.changeMode === 'tracked') {
+            throw unsupported(`Structured document RPC does not support tracked mode for ${operation.operationId}.`, operation.operationId);
+        }
+        if (options.changeMode !== 'direct') {
+            throw unsupported(`Structured document RPC received an invalid change mode for ${operation.operationId}.`, operation.operationId);
+        }
+        delete options.changeMode;
     }
+    if (options.dryRun !== undefined && operation.supportsDryRun !== true) {
+        if (options.dryRun === true) {
+            throw unsupported(`Structured document RPC does not support dry run for ${operation.operationId}.`, operation.operationId);
+        }
+        delete options.dryRun;
+    }
+    if (options.expectedRevision !== undefined && DOCUMENT_API_REVISION_PREFLIGHT_OPERATIONS.has(operation.operationId)) {
+        throw unsupported(`Structured document RPC does not yet support expectedRevision for ${operation.operationId}.`, operation.operationId);
+    }
+    if (options.expectedRevision !== undefined && operation.mutates !== true) {
+        throw unsupported(`Structured document RPC does not support expectedRevision for ${operation.operationId}.`, operation.operationId);
+    }
+    return {
+        input,
+        ...(Object.keys(options).length === 0 ? {} : { options }),
+    };
+}
+export function buildDocumentInvokeParams(sessionId, operation, params, options, hostFeatures) {
     if (operation.operationId === 'doc.save') {
-        if (params.inPlace === true || typeof params.out !== 'string' || params.out.length === 0) {
-            throw unsupported('Structured document RPC v0 requires doc.save({ out }) and does not support inPlace.', operation.operationId);
+        if (options.stdinBytes !== undefined ||
+            options.dryRun !== undefined ||
+            options.expectedRevision !== undefined ||
+            options.changeMode !== undefined) {
+            throw unsupported('Structured document RPC does not support document.save invoke options.', operation.operationId);
+        }
+        const unknownField = Object.entries(params).find(([name, value]) => value !== undefined && !DOCUMENT_RPC_SAVE_FIELDS.has(name))?.[0];
+        if (unknownField !== undefined) {
+            throw unsupported(`Structured document RPC does not support doc.save field ${unknownField}.`, operation.operationId);
+        }
+        if (params.inPlace !== undefined && typeof params.inPlace !== 'boolean') {
+            throw unsupported('Structured document RPC requires inPlace to be a boolean.', operation.operationId);
+        }
+        if (params.inPlace === true && params.out !== undefined) {
+            throw unsupported('Structured document RPC requires either inPlace or out, not both.', operation.operationId);
+        }
+        if (params.out !== undefined && (typeof params.out !== 'string' || params.out.length === 0)) {
+            throw unsupported('Structured document RPC requires out to be a non-empty path.', operation.operationId);
+        }
+        if (params.out === undefined && hostFeatures?.has(DOCUMENT_RPC_SOURCE_SAVE_FEATURE) !== true) {
+            throw unsupported('Structured document RPC host does not support source saves.', operation.operationId);
         }
         return {
             method: 'document.save',
             params: {
                 sessionId,
-                path: params.out,
-                overwrite: params.force === true,
+                ...(params.out === undefined ? {} : { path: params.out }),
+                ...(params.force === true ? { overwrite: true } : {}),
                 ...(params.mode === undefined ? {} : { mode: params.mode }),
             },
         };
     }
     if (operation.operationId === 'doc.close') {
+        if (options.stdinBytes !== undefined ||
+            options.dryRun !== undefined ||
+            options.expectedRevision !== undefined ||
+            options.changeMode !== undefined) {
+            throw unsupported('Structured document RPC does not support document.close invoke options.', operation.operationId);
+        }
         return {
             method: 'document.close',
             params: {
@@ -112,16 +222,40 @@ export function buildDocumentInvokeParams(sessionId, operation, params, options)
             },
         };
     }
+    const documentOperation = operation;
+    if (typeof documentOperation.documentApiOperationId !== 'string' ||
+        documentOperation.documentApiOperationId.length === 0) {
+        throw unsupported(`Structured document RPC does not support ${operation.operationId}.`, operation.operationId);
+    }
+    const payload = documentInvokePayload(documentOperation, params, options);
     return {
         method: 'document.invoke',
         params: {
             sessionId,
-            operationId: operation.operationId.slice('doc.'.length),
-            input: documentInvokeInput(operation.operationId, params),
+            operationId: documentOperation.documentApiOperationId,
+            input: payload.input,
+            ...(payload.options === undefined ? {} : { options: payload.options }),
         },
     };
 }
-export function mapDocumentLifecycleResult(operationId, response, sessionId) {
+export function documentRpcRequestSupportsResponseTimeout(operation, request) {
+    if (request.method === 'document.save')
+        return false;
+    if (request.method !== 'document.invoke')
+        return true;
+    const documentOperation = operation;
+    const requestOptions = typeof request.params.options === 'object' &&
+        request.params.options !== null &&
+        !Array.isArray(request.params.options)
+        ? request.params.options
+        : undefined;
+    if (requestOptions?.dryRun === true)
+        return true;
+    if (documentOperation.mutates === false)
+        return true;
+    return documentOperation.idempotency === 'idempotent';
+}
+export function mapDocumentLifecycleResult(operationId, response, sessionId, expectedInPlace) {
     if (operationId !== 'doc.save' && operationId !== 'doc.close')
         return response;
     if (typeof response !== 'object' || response == null || Array.isArray(response)) {
@@ -155,6 +289,7 @@ export function mapDocumentLifecycleResult(operationId, response, sessionId) {
     }
     const output = record.output;
     if (record.saved !== true ||
+        (typeof record.inPlace !== 'boolean' && !(record.inPlace === undefined && expectedInPlace === false)) ||
         typeof output !== 'object' ||
         output == null ||
         Array.isArray(output) ||
@@ -169,7 +304,7 @@ export function mapDocumentLifecycleResult(operationId, response, sessionId) {
         contextId: sessionId,
         runtime: 'v2',
         saved: true,
-        inPlace: false,
+        inPlace: record.inPlace ?? false,
         mode: record.mode,
         output,
         report: record.report,

package/dist/runtime/embedded-cli.cjs

@@ -1,78 +1,16 @@
 'use strict';
 
-var node_fs = require('node:fs');
-var node_module = require('node:module');
-var path = require('node:path');
-var node_url = require('node:url');
 var errors = require('./errors.cjs');
+var embeddedPlatform = require('./embedded-platform.cjs');
 
-var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
-const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-cli.cjs', document.baseURI).href)));
-const TARGET_TO_PACKAGE = {
-    'darwin-arm64': '@superdoc/sdk-darwin-arm64',
-    'darwin-x64': '@superdoc/sdk-darwin-x64',
-    'linux-x64': '@superdoc/sdk-linux-x64',
-    'linux-arm64': '@superdoc/sdk-linux-arm64',
-    'windows-x64': '@superdoc/sdk-windows-x64',
-};
-const TARGET_TO_DIR = {
-    'darwin-arm64': 'sdk-darwin-arm64',
-    'darwin-x64': 'sdk-darwin-x64',
-    'linux-x64': 'sdk-linux-x64',
-    'linux-arm64': 'sdk-linux-arm64',
-    'windows-x64': 'sdk-windows-x64',
-};
-function resolveTarget() {
-    const platform = process.platform;
-    const arch = process.arch;
-    if (platform === 'darwin' && arch === 'arm64')
-        return 'darwin-arm64';
-    if (platform === 'darwin' && arch === 'x64')
-        return 'darwin-x64';
-    if (platform === 'linux' && arch === 'x64')
-        return 'linux-x64';
-    if (platform === 'linux' && arch === 'arm64')
-        return 'linux-arm64';
-    if (platform === 'win32' && arch === 'x64')
-        return 'windows-x64';
-    return null;
-}
 function binaryNameForTarget(target) {
     return target === 'windows-x64' ? 'superdoc.exe' : 'superdoc';
 }
-function ensureExecutable(binaryPath) {
-    if (process.platform === 'win32')
-        return;
-    try {
-        node_fs.chmodSync(binaryPath, 0o755);
-    }
-    catch {
-        // Non-fatal: if chmod fails, spawn() will surface the real execution error.
-    }
-}
-function resolveFromPlatformPackage(target) {
-    const pkg = TARGET_TO_PACKAGE[target];
-    const binaryName = binaryNameForTarget(target);
-    try {
-        return require$1.resolve(`${pkg}/bin/${binaryName}`);
-    }
-    catch {
-        return null;
-    }
-}
-function resolveFromWorkspaceFallback(target) {
-    const binaryName = binaryNameForTarget(target);
-    const dirName = TARGET_TO_DIR[target];
-    const filePath = path.resolve(node_url.fileURLToPath(new URL('../../platforms', (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-cli.cjs', document.baseURI).href)))), dirName, 'bin', binaryName);
-    if (!node_fs.existsSync(filePath))
-        return null;
-    return filePath;
-}
 /**
  * Resolve the path to the embedded SuperDoc CLI binary for the current platform.
  */
 function resolveEmbeddedCliBinary() {
-    const target = resolveTarget();
+    const target = embeddedPlatform.resolveEmbeddedTarget();
     if (!target) {
         throw new errors.SuperDocCliError('No embedded SuperDoc CLI binary is available for this platform.', {
             code: 'UNSUPPORTED_PLATFORM',
@@ -82,18 +20,17 @@ function resolveEmbeddedCliBinary() {
             },
         });
     }
-    const platformPackagePath = resolveFromPlatformPackage(target);
-    const resolvedPath = platformPackagePath ?? resolveFromWorkspaceFallback(target);
+    const resolvedPath = embeddedPlatform.resolveEmbeddedPlatformBinary(target, binaryNameForTarget(target));
     if (!resolvedPath) {
         throw new errors.SuperDocCliError('Embedded SuperDoc CLI binary is missing for this platform.', {
             code: 'CLI_BINARY_MISSING',
             details: {
                 target,
-                packageName: TARGET_TO_PACKAGE[target],
+                packageName: embeddedPlatform.embeddedPlatformPackage(target),
             },
         });
     }
-    ensureExecutable(resolvedPath);
+    embeddedPlatform.ensureEmbeddedExecutable(resolvedPath);
     return resolvedPath;
 }
 

package/dist/runtime/embedded-cli.js

@@ -1,74 +1,13 @@
-import { chmodSync, existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { SuperDocCliError } from './errors.js';
-const require = createRequire(import.meta.url);
-const TARGET_TO_PACKAGE = {
-    'darwin-arm64': '@superdoc/sdk-darwin-arm64',
-    'darwin-x64': '@superdoc/sdk-darwin-x64',
-    'linux-x64': '@superdoc/sdk-linux-x64',
-    'linux-arm64': '@superdoc/sdk-linux-arm64',
-    'windows-x64': '@superdoc/sdk-windows-x64',
-};
-const TARGET_TO_DIR = {
-    'darwin-arm64': 'sdk-darwin-arm64',
-    'darwin-x64': 'sdk-darwin-x64',
-    'linux-x64': 'sdk-linux-x64',
-    'linux-arm64': 'sdk-linux-arm64',
-    'windows-x64': 'sdk-windows-x64',
-};
-function resolveTarget() {
-    const platform = process.platform;
-    const arch = process.arch;
-    if (platform === 'darwin' && arch === 'arm64')
-        return 'darwin-arm64';
-    if (platform === 'darwin' && arch === 'x64')
-        return 'darwin-x64';
-    if (platform === 'linux' && arch === 'x64')
-        return 'linux-x64';
-    if (platform === 'linux' && arch === 'arm64')
-        return 'linux-arm64';
-    if (platform === 'win32' && arch === 'x64')
-        return 'windows-x64';
-    return null;
-}
+import { embeddedPlatformPackage, ensureEmbeddedExecutable, resolveEmbeddedPlatformBinary, resolveEmbeddedTarget, } from './embedded-platform.js';
 function binaryNameForTarget(target) {
     return target === 'windows-x64' ? 'superdoc.exe' : 'superdoc';
 }
-function ensureExecutable(binaryPath) {
-    if (process.platform === 'win32')
-        return;
-    try {
-        chmodSync(binaryPath, 0o755);
-    }
-    catch {
-        // Non-fatal: if chmod fails, spawn() will surface the real execution error.
-    }
-}
-function resolveFromPlatformPackage(target) {
-    const pkg = TARGET_TO_PACKAGE[target];
-    const binaryName = binaryNameForTarget(target);
-    try {
-        return require.resolve(`${pkg}/bin/${binaryName}`);
-    }
-    catch {
-        return null;
-    }
-}
-function resolveFromWorkspaceFallback(target) {
-    const binaryName = binaryNameForTarget(target);
-    const dirName = TARGET_TO_DIR[target];
-    const filePath = path.resolve(fileURLToPath(new URL('../../platforms', import.meta.url)), dirName, 'bin', binaryName);
-    if (!existsSync(filePath))
-        return null;
-    return filePath;
-}
 /**
  * Resolve the path to the embedded SuperDoc CLI binary for the current platform.
  */
 export function resolveEmbeddedCliBinary() {
-    const target = resolveTarget();
+    const target = resolveEmbeddedTarget();
     if (!target) {
         throw new SuperDocCliError('No embedded SuperDoc CLI binary is available for this platform.', {
             code: 'UNSUPPORTED_PLATFORM',
@@ -78,17 +17,16 @@ export function resolveEmbeddedCliBinary() {
             },
         });
     }
-    const platformPackagePath = resolveFromPlatformPackage(target);
-    const resolvedPath = platformPackagePath ?? resolveFromWorkspaceFallback(target);
+    const resolvedPath = resolveEmbeddedPlatformBinary(target, binaryNameForTarget(target));
     if (!resolvedPath) {
         throw new SuperDocCliError('Embedded SuperDoc CLI binary is missing for this platform.', {
             code: 'CLI_BINARY_MISSING',
             details: {
                 target,
-                packageName: TARGET_TO_PACKAGE[target],
+                packageName: embeddedPlatformPackage(target),
             },
         });
     }
-    ensureExecutable(resolvedPath);
+    ensureEmbeddedExecutable(resolvedPath);
     return resolvedPath;
 }

package/dist/runtime/embedded-document-host.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+var embeddedPlatform = require('./embedded-platform.cjs');
+var errors = require('./errors.cjs');
+
+function binaryNameForTarget(target) {
+    return target === 'windows-x64' ? 'superdoc-document-host.exe' : 'superdoc-document-host';
+}
+function resolveEmbeddedDocumentHostBinary() {
+    const target = embeddedPlatform.resolveEmbeddedTarget();
+    if (!target) {
+        throw new errors.SuperDocCliError('No embedded SuperDoc document host is available for this platform.', {
+            code: 'UNSUPPORTED_PLATFORM',
+            details: { platform: process.platform, arch: process.arch },
+        });
+    }
+    const resolvedPath = embeddedPlatform.resolveEmbeddedPlatformBinary(target, binaryNameForTarget(target));
+    if (!resolvedPath) {
+        throw new errors.SuperDocCliError('Embedded SuperDoc document host is missing for this platform.', {
+            code: 'DOCUMENT_HOST_BINARY_MISSING',
+            details: { target, packageName: embeddedPlatform.embeddedPlatformPackage(target) },
+        });
+    }
+    embeddedPlatform.ensureEmbeddedExecutable(resolvedPath);
+    return resolvedPath;
+}
+
+exports.resolveEmbeddedDocumentHostBinary = resolveEmbeddedDocumentHostBinary;

package/dist/runtime/embedded-document-host.d.ts

@@ -0,0 +1 @@
+export declare function resolveEmbeddedDocumentHostBinary(): string;

package/dist/runtime/embedded-document-host.js

@@ -0,0 +1,23 @@
+import { embeddedPlatformPackage, ensureEmbeddedExecutable, resolveEmbeddedPlatformBinary, resolveEmbeddedTarget, } from './embedded-platform.js';
+import { SuperDocCliError } from './errors.js';
+function binaryNameForTarget(target) {
+    return target === 'windows-x64' ? 'superdoc-document-host.exe' : 'superdoc-document-host';
+}
+export function resolveEmbeddedDocumentHostBinary() {
+    const target = resolveEmbeddedTarget();
+    if (!target) {
+        throw new SuperDocCliError('No embedded SuperDoc document host is available for this platform.', {
+            code: 'UNSUPPORTED_PLATFORM',
+            details: { platform: process.platform, arch: process.arch },
+        });
+    }
+    const resolvedPath = resolveEmbeddedPlatformBinary(target, binaryNameForTarget(target));
+    if (!resolvedPath) {
+        throw new SuperDocCliError('Embedded SuperDoc document host is missing for this platform.', {
+            code: 'DOCUMENT_HOST_BINARY_MISSING',
+            details: { target, packageName: embeddedPlatformPackage(target) },
+        });
+    }
+    ensureEmbeddedExecutable(resolvedPath);
+    return resolvedPath;
+}

package/dist/runtime/embedded-platform.cjs

@@ -0,0 +1,108 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var node_module = require('node:module');
+var path = require('node:path');
+var node_url = require('node:url');
+var sdkVersion_generated = require('./sdk-version.generated.cjs');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-platform.cjs', document.baseURI).href)));
+const TARGET_TO_PACKAGE = {
+    'darwin-arm64': '@superdoc/sdk-darwin-arm64',
+    'darwin-x64': '@superdoc/sdk-darwin-x64',
+    'linux-x64': '@superdoc/sdk-linux-x64',
+    'linux-arm64': '@superdoc/sdk-linux-arm64',
+    'windows-x64': '@superdoc/sdk-windows-x64',
+};
+const TARGET_TO_DIR = {
+    'darwin-arm64': 'sdk-darwin-arm64',
+    'darwin-x64': 'sdk-darwin-x64',
+    'linux-x64': 'sdk-linux-x64',
+    'linux-arm64': 'sdk-linux-arm64',
+    'windows-x64': 'sdk-windows-x64',
+};
+function resolveEmbeddedTarget(platform = process.platform, arch = process.arch) {
+    if (platform === 'darwin' && arch === 'arm64')
+        return 'darwin-arm64';
+    if (platform === 'darwin' && arch === 'x64')
+        return 'darwin-x64';
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux-x64';
+    if (platform === 'linux' && arch === 'arm64')
+        return 'linux-arm64';
+    if (platform === 'win32' && arch === 'x64')
+        return 'windows-x64';
+    return null;
+}
+function embeddedPlatformPackage(target) {
+    return TARGET_TO_PACKAGE[target];
+}
+/**
+ * The binary shipped inside this package (`platforms/<target>/bin/`). A build
+ * that carries its own host is authoritative — it is the only copy guaranteed
+ * to match this SDK's code — so it is tried before any resolver lookup.
+ */
+function resolveFromPackageLocal(target, binaryName) {
+    const workspacePath = path.resolve(node_url.fileURLToPath(new URL('../../platforms', (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-platform.cjs', document.baseURI).href)))), TARGET_TO_DIR[target], 'bin', binaryName);
+    return node_fs.existsSync(workspacePath) ? workspacePath : null;
+}
+/**
+ * Resolve the platform package through Node, and reject a version that is not
+ * this SDK's own.
+ *
+ * Resolution starts from the installed SDK so pnpm's isolated optional
+ * dependency remains visible after the SDK itself is bundled. `require.resolve`
+ * can also fall back to NODE_PATH, so the version check prevents a host binary
+ * from an unrelated SDK version in a flat store from satisfying this lookup.
+ * optionalDependencies pin the platform package to an exact version, so a
+ * mismatch here is never legitimate.
+ */
+function resolveFromPlatformPackage(target, binaryName) {
+    const pkg = TARGET_TO_PACKAGE[target];
+    let sdkRequire;
+    try {
+        sdkRequire = node_module.createRequire(require$1.resolve('@superdoc/sdk'));
+    }
+    catch {
+        sdkRequire = require$1;
+    }
+    let binaryPath;
+    try {
+        binaryPath = sdkRequire.resolve(`${pkg}/bin/${binaryName}`);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const platformVersion = sdkRequire(sdkRequire.resolve(`${pkg}/package.json`)).version;
+        if (platformVersion !== sdkVersion_generated.SDK_VERSION)
+            return null;
+    }
+    catch {
+        // An unreadable platform manifest is itself disqualifying: an unverifiable
+        // host is exactly the case this guard exists to reject.
+        return null;
+    }
+    return binaryPath;
+}
+function resolveEmbeddedPlatformBinary(target, binaryName) {
+    // Package-local first: a self-contained build must never be overridden by
+    // whatever the module resolver happens to find on NODE_PATH.
+    return resolveFromPackageLocal(target, binaryName) ?? resolveFromPlatformPackage(target, binaryName);
+}
+function ensureEmbeddedExecutable(binaryPath) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        node_fs.chmodSync(binaryPath, 0o755);
+    }
+    catch {
+        // Non-fatal: spawn() reports the actionable execution error.
+    }
+}
+
+exports.embeddedPlatformPackage = embeddedPlatformPackage;
+exports.ensureEmbeddedExecutable = ensureEmbeddedExecutable;
+exports.resolveEmbeddedPlatformBinary = resolveEmbeddedPlatformBinary;
+exports.resolveEmbeddedTarget = resolveEmbeddedTarget;

package/dist/runtime/embedded-platform.d.ts

@@ -0,0 +1,5 @@
+export type SupportedEmbeddedTarget = 'darwin-arm64' | 'darwin-x64' | 'linux-x64' | 'linux-arm64' | 'windows-x64';
+export declare function resolveEmbeddedTarget(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): SupportedEmbeddedTarget | null;
+export declare function embeddedPlatformPackage(target: SupportedEmbeddedTarget): string;
+export declare function resolveEmbeddedPlatformBinary(target: SupportedEmbeddedTarget, binaryName: string): string | null;
+export declare function ensureEmbeddedExecutable(binaryPath: string): void;